Skip to main content

安装 goose

这页汇总 goose Desktop 和 goose CLI 的安装方式。想先快速跑通流程，可以先看 快速开始。

你可以选择安装 goose Desktop、goose CLI，或两者都装。

你可以直接从浏览器下载 goose Desktop，或者通过 Homebrew 安装。

方案 1：下载安装包

点击下面的按钮下载 macOS 版本的 goose Desktop：

macOS Apple 芯片 macOS Intel
  1. 解压下载的压缩包。
  2. 运行应用启动 goose Desktop。
更新

建议定期更新 goose。

方案 2：通过 Homebrew 安装

Homebrew 安装的也是同一个桌面应用，但它还能帮你统一处理后续更新：

brew install --cask block-goose
权限

如果你使用的是 Apple Mac M3，且 goose Desktop 启动后看不到窗口，请检查 ~/.config 目录是否具有读写权限。

goose 需要在这里创建日志目录和日志文件。权限修正后，应用一般就能正常加载。操作细节可参考已知问题指南。

设置 LLM Provider​

goose 需要通过一个可用的 LLM Provider 获得理解请求和执行任务所需的 AI 能力。首次使用时，它会引导你完成 Provider 配置。

第一次打开 goose Desktop 时，欢迎页通常会提供以下入口：

  • Quick Setup with API Key - goose 会根据你的 API Key 自动识别并配置 Provider。
  • ChatGPT Subscription - 使用 ChatGPT Plus / Pro 订阅登录，访问 GPT-5 Codex 模型。
  • Agent Router by Tetrate - 通过自动配置快速接入多个 AI 模型。
  • OpenRouter - 通过单一 API 使用多个模型，按量付费。
  • Other Providers - 在设置里手动配置其它 Provider。
模型选择

goose 很依赖 tool calling 能力。对大多数开发任务，优先选择 tool calling 表现稳定的模型。

免费额度

第一次通过 goose 自动完成 Tetrate 认证时，你会获得 10 美元免费额度；新老 Tetrate 用户都适用。

更新 Provider​

你可以随时更换 LLM Provider、切换模型或更新 API Key。

  1. 点击左上角的 按钮打开侧边栏。
  2. 点击 Settings。
  3. 进入 Models 标签。
  4. 选择更新 Provider、切换模型，或者点击 Reset Provider and Model 重新开始配置。更细的说明见 配置 LLM Provider。
计费与速率限制
Google Gemini 提供可直接开始使用的免费额度。除此之外，你需要确保在所选 LLM Provider 账户中有可用余额，才能正常发起请求。

部分 Provider 还会限制 API 请求频率，这会直接影响使用体验。你可以继续阅读 设置 LLM 速率限制，了解如何在使用 goose 时更高效地管理这些限制。

运行 goose​

选择好 Provider 后，Desktop 会直接进入可用的会话界面。你只需要在输入框里输入任务即可开始。

共享配置​

goose CLI 和 Desktop 共享核心配置，包括：

  • LLM Provider 设置
  • 当前模型
  • 扩展配置

这意味着你可以在 Desktop 里完成配置，再切回 CLI 继续使用；反之亦然。更完整的说明见 Config Files。

info

虽然核心配置在两个界面之间是共享的，但扩展可以自行决定如何存储认证信息。有些扩展会直接使用共享配置文件，有些则会使用自己的存储逻辑。

你可以通过以下方式进入共享配置：

  1. 点击左上角的 按钮打开侧边栏。
  2. 点击 Settings。

在 CI/CD 中固定 goose 版本​

在 CI/CD 或其它自动化、非交互环境中，建议通过 GOOSE_VERSION 固定特定版本，以保证安装可复现，并避免在 stable tag 不包含对应 CLI 二进制资源时出现下载 404。

完整示例与用法说明见 CI/CD Environments。

为 Linux 发行版生成 manpages​

如果你正在为某个 Linux 发行版打包 goose，或者要做自定义构建，可以从 CLI 命令定义自动生成 Unix manpages：

just generate-manpages

这个命令会在 target/man/ 下生成 ROFF 格式的 manpage（例如 goose.1、goose-session.1），你可以把它们安装到 /usr/share/man/man1/，从而通过 man 命令提供离线文档。

manpage 生成需要 goose 源码仓库，主要面向 Fedora、Debian 等发行版的打包维护者。实现细节可参考 generate_manpages.rs。

额外资源​