goose 安装完全指南：CLI 与 Desktop 双端安装、LLM 供应商配置及版本管理

本文基于 goose 仓库的官方安装文档 installation.md 及配套安装脚本源码编写，覆盖 macOS、Linux、Windows 三大平台下 goose CLI 与 goose Desktop 的全部安装方式。读完本篇，你将掌握：如何按平台选择正确的安装渠道、安装脚本中各个环境变量（GOOSE_VERSION、CONFIGURE、GOOSE_LINUX_VARIANT 等）的实际作用、如何完成首次 LLM 供应商配置与后续更换，以及如何在 CI/CD 中锁定版本、如何为 Linux 发行版生成 manpage。

两种形态：goose Desktop 与 goose CLI

goose 提供两个可独立安装、共享同一套核心配置的形态：

• goose Desktop：图形界面应用，适合希望以窗口化方式管理会话、扩展和模型设置的场景；
• goose CLI：终端中的命令行工具，支持交互式会话（goose session）与自动化/无头环境，是脚本、CI/CD 集成的主力入口。

两者共享 LLM 供应商设置、模型选择与扩展配置，安装其一或同时安装均可。

在 macOS 上安装

Desktop 版本

方式一：直接从浏览器下载 zip 包，解压后运行可执行文件启动应用。

方式二：通过 Homebrew 安装，Homebrew 安装的是同一个应用包，并额外负责后续更新：

brew install --cask block-goose

权限提示（Apple M3 机型）：如果启动 goose Desktop 后不显示窗口，请检查 ~/.config 目录是否具备读写权限。goose 需要该权限来创建日志目录和日志文件；授予权限后应用即可正常加载。可参考文档中的 Known Issues 指南处理 macOS 权限问题。

CLI 版本

方式一：官方下载脚本，获取并安装最新版本：

curl -fsSL https://github.com/aaif-goose/goose/releases/download/stable/download_cli.sh | bash

该脚本会从 stable 发布标签拉取最新二进制并完成安装。若希望跳过交互式配置流程（例如在自动化环境中），将 CONFIGURE 置为 false：

curl -fsSL https://github.com/aaif-goose/goose/releases/download/stable/download_cli.sh | CONFIGURE=false bash

方式二：Homebrew 安装预编译的 CLI 工具，同样可享受自动更新：

brew install block-goose-cli

安装后建议保持版本更新，执行：

goose update

在 Linux 上安装

Desktop 版本

从浏览器下载 DEB 包后：

1. 下载 DEB 文件；
2. 在终端中进入文件所在目录；
3. 运行 sudo dpkg -i (文件名).deb；
4. 从应用菜单启动 goose。

CLI 版本

与 macOS 相同的安装脚本：

curl -fsSL https://github.com/aaif-goose/goose/releases/download/stable/download_cli.sh | bash

非交互式安装同样支持 CONFIGURE=false bash；更新使用 goose update。

WSL/最小化系统的依赖提示：如果下载或解压阶段失败，可能需要先安装 bzip2（发布包使用 .tar.bz2 格式）：

sudo apt update && sudo apt install bzip2 -y

在 Windows 上安装

Desktop 版本

从浏览器下载 zip 包，解压后运行可执行文件即可启动。

CLI 版本（原生安装）

原生安装需要以下环境之一：

• Git Bash（推荐）：随 Git for Windows 提供；
• MSYS2：第三方环境；
• PowerShell：Windows 10/11 自带。

Git Bash / MSYS2 安装方式：

curl -fsSL https://github.com/aaif-goose/goose/releases/download/stable/download_cli.sh | bash

跳过交互式配置：

curl -fsSL https://github.com/aaif-goose/goose/releases/download/stable/download_cli.sh | CONFIGURE=false bash

PowerShell 安装方式：先下载安装脚本到当前目录，再执行：

Invoke-WebRequest -Uri "https://raw.githubusercontent.com/aaif-goose/goose/main/download_cli.ps1" -OutFile "download_cli.ps1";

.\download_cli.ps1

PATH 配置：如果安装后提示 goose 不在 PATH 中，按环境分别处理。

Git Bash / MSYS2：

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

PowerShell（写入用户 profile）：

# Add to your PowerShell profile
$profilePath = $PROFILE
if (!(Test-Path $profilePath)) { New-Item -Path $profilePath -ItemType File -Force }
Add-Content -Path $profilePath -Value '$env:PATH = "$env:USERPROFILE\.local\bin;$env:PATH"'
# Reload profile or restart PowerShell
. $PROFILE

配置完成后，即可在任意目录直接运行 goose 命令。

WSL 方式（可选）：官方推荐在 Windows 上原生运行 CLI，但如需 Linux 风格环境，也可使用 WSL：

1. 以管理员身份打开 PowerShell，安装 WSL 与默认 Ubuntu 发行版：

wsl --install

2. 按提示重启计算机，然后启动 Ubuntu shell：

wsl -d Ubuntu

3. 在 WSL 内运行安装脚本：

curl -fsSL https://github.com/aaif-goose/goose/releases/download/stable/download_cli.sh | bash

如需跳过交互配置，追加 CONFIGURE=false。必要时将 goose 与 API Key 写入 PATH/环境变量：

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
echo 'export OPENAI_API_KEY=your_api_key' >> ~/.bashrc
source ~/.bashrc

安装脚本参数详解（以 download_cli.sh 源码为依据）

官方安装脚本 download_cli.sh 是各平台共用的 bash 安装入口，文件头部的注释完整列出了它支持的环境变量。结合源码实现，这些参数的实际行为如下：

环境变量	默认值	作用
GOOSE_BIN_DIR	macOS/Linux/WSL 为 $HOME/.local/bin；Windows 下为 $USERPROFILE/goose	goose 二进制安装目录，脚本不存在时会创建
GOOSE_VERSION	空（使用 stable 标签）	锁定具体版本，支持 vX.Y.Z、vX.Y.Z-suffix、X.Y.Z 三种格式；脚本会做 semver 正则校验，不合法直接报错退出
GOOSE_PROVIDER / GOOSE_MODEL	空	指定 goose 使用的供应商与模型
GOOSE_LINUX_VARIANT	自动检测（standard/musl），也可指定 vulkan	Linux 包变体；musl 变体对应 goose-...-unknown-linux-musl.tar.bz2，vulkan 对应带 -vulkan 后缀的资产
GOOSE_WINDOWS_VARIANT	standard	Windows 包变体，可选 standard 或 cuda；cuda 对应带 -cuda 后缀的 zip 资产
CANARY	false	设为 true 时从 canary 发布标签下载，而非 stable
CONFIGURE	true	设为 false 时跳过安装后的 goose configure 交互配置

脚本的几处关键实现细节（见 download_cli.sh）：

• 操作系统与架构检测：优先识别 MSYS2/Cygwin/Windows 环境，其次识别 Termux（Android）与 WSL（通过 /proc/version 中的 Microsoft/WSL 特征判定为 Linux），最后回退到 uname。架构仅支持 x86_64 与 arm64/aarch64（后者会被归一化为 aarch64）；Windows 包目前仅支持 x86_64。
• musl 自动识别：在 Linux 上若 OSTYPE 以 linux-musl 开头，或 ldd --version 输出含 musl，则自动选用 musl 变体；检测到 Termux 时也强制使用 musl 便携构建。
• 下载失败回退：若未指定 GOOSE_VERSION 且未请求 canary，脚本会查询 GitHub 的 latest 发布标签并改用其资产地址重试一次，规避 stable 标签资产缺失导致的 404。
• 解压失败诊断：tar 解压失败时脚本会检查错误日志，若匹配到 bzip2 缺失特征会明确提示安装 bzip2。
• 原子性替换：在 Linux 上若目标二进制正在运行，直接写入会报 ETXTBSY（Text file busy），脚本会先把旧二进制改名为 .old、再移入新二进制，失败时回滚恢复旧版本（见 download_cli.sh）。
• 非交互式处理：CONFIGURE 为 true 但 stdin 不是终端（如 curl | bash）时，脚本检测不到 TTY 会跳过 goose configure 并提示安装后手动执行。

Windows 的 PowerShell 脚本 download_cli.ps1 提供对等的变量集（$env:GOOSE_BIN_DIR、$env:GOOSE_VERSION、$env:GOOSE_WINDOWS_VARIANT、$env:CANARY、$env:CONFIGURE），默认安装目录为 $env:USERPROFILE\.local\bin，仅支持 x86_64 架构，并使用 Expand-Archive 解压 zip 资产。

配置 LLM 供应商（Set LLM Provider）

goose 依赖受支持的 LLM 供应商提供推理能力。首次使用时会被提示配置供应商。

goose Desktop：首次打开应用时，欢迎界面即引导你选择供应商配置方式。

goose CLI：首次运行会自动进入配置模式，提供三种方式：

• OpenRouter Login —— 登录 OpenRouter，自动配置模型；
• Tetrate Agent Router Service Login —— 登录 Tetrate Agent Router Service，自动配置模型；
• Manual Configuration —— 手动选择供应商并填写凭据。

文档中给出的 Tetrate 自动配置流程示例：

┌   goose-configure
│
◇ How would you like to set up your provider?
│ Tetrate Agent Router Service Login
│
Opening browser for Tetrate Agent Router Service authentication...
[goose opens the browser and prints details]

Authentication complete!

Configuring Tetrate Agent Router Service...
✓ Tetrate Agent Router Service configuration complete
✓ Models configured successfully

Testing configuration...
✓ Configuration test passed!
✓ Developer extension enabled!
└ Tetrate Agent Router Service setup complete! You can now use goose.

Windows 用户的 keyring 处理：在 Windows 上手动配置供应商时，如果提示是否存入 keyring，建议选择“不存入”。若设置 API Key 时遇到 keyring 错误，可以直接改用环境变量，然后重新运行 goose configure。此时 goose 会检测到环境变量并显示：

● OPENAI_API_KEY is set via environment variable

这条提示对应源码 configure.rs 中的环境变量检测逻辑——配置器在填写凭据前先检查同名环境变量是否已存在，已存在则直接提示而非要求重复输入。要让 API Key 跨会话持久生效，可写入 shell profile：

echo 'export OPENAI_API_KEY=your_api_key' >> ~/.bashrc
source ~/.bashrc

免费额度提示：通过 goose 首次自动完成 Tetrate 认证的用户（无论新旧用户）可获得 10 美元免费额度。

更换供应商或模型（Update Provider）

供应商、模型和 API Key 可随时更改。

goose Desktop：

1. 点击左上角侧边栏按钮打开侧边栏；
2. 点击侧边栏中的 Settings；
3. 进入 Models 标签页；
4. 选择更新供应商、切换模型，或点击 Reset Provider and Model 清空设置并返回欢迎界面。

goose CLI：

goose configure

在菜单中选择 Configure Providers，按提示选择供应商并输入/更新 API Key。以方向键高亮选项后按 Enter 确认。文档示例（选择 Google Gemini）：

┌   goose-configure
│
◇ What would you like to configure?
│ Configure Providers
│
◇ Which model provider should we use?
│ Google Gemini
│
◇ Provider Google Gemini requires GOOGLE_API_KEY, please enter a value
│▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪
│
◇ Enter a model from that provider:
│ gemini-2.0-flash-exp
│
◇  Hello there! You're all set to use me, so please ask away!
│
└  Configuration saved successfully

goose update：CLI 自更新的安全机制

安装后建议定期执行 goose update 保持版本最新。从源码 update.rs 可以看到，goose update 并非简单的“下载覆盖”，它包含完整的安全校验链：

1. 从 stable（或 --canary 对应的 canary）发布标签下载当前平台对应的资产；
2. 通过 Sigstore 验证 SLSA 溯源信息（verify_provenance），验证失败会中止更新，这是更新流程中显式的安全检查点；
3. 解压到临时目录，且解压逻辑带有路径穿越（zip-slip）防护，逐个校验条目不得逃逸出目标目录；
4. 定位到二进制后原地替换当前可执行文件；Windows 上还会同步复制随包的运行时 DLL；
5. 如请求重新配置，则自动执行一次 goose configure。

此外源码中预留了 disable-update 编译特性，在禁用更新的构建中执行 goose update 会直接报错退出。

启动会话（Running goose）

goose Desktop：完成供应商选择后会话界面即就绪，直接在输入框中键入问题、任务或指令即可。

goose CLI：进入你希望作为工作目录的路径，然后运行：

goose session

CLI 与 Desktop 的共享配置

goose CLI 与 Desktop UI 共享全部核心配置，包括 LLM 供应商设置、模型选择与扩展配置。无论在哪一端安装或配置扩展，设置都保存在中心位置，两端立即可用，便于在两种界面间无缝切换且保持设置一致。

需要注意的是：核心配置共享，但扩展在存放认证凭据时具有一定灵活性——部分扩展使用共享配置文件，部分扩展实现自己的存储方式。

进入共享配置的入口：

• Desktop：左上角打开侧边栏 → Settings；
• CLI：goose configure。

在 CI/CD 中固定 goose 版本

在 CI/CD 及其他自动化、非交互环境中，应通过 GOOSE_VERSION 锁定具体版本，使安装可复现，并避免在 stable 发布标签未包含对应二进制资产时下载 404。这与 download_cli.sh 中的实现一致：一旦设置 GOOSE_VERSION，脚本会跳过 stable/canary 标签逻辑，直接使用该版本标签构造下载地址，并在格式不合法时校验失败退出。

GOOSE_VERSION=v1.2.29 curl -fsSL <安装脚本地址> | bash

完整的 CI/CD 用法示例可参考仓库文档中的 CI/CD 教程章节。

为 Linux 发行版生成 manpage

如果你在为 Linux 发行版打包 goose 或制作自定义构建，可以从 CLI 命令定义生成 Unix manpage：

just generate-manpages

该 recipe 定义于 Justfile，实际执行 cargo run -p goose-cli --bin generate_manpages，在 target/man/ 下产出 ROFF 格式的 manpage（如 goose.1、goose-session.1），可安装到 /usr/share/man/man1/ 为 man 命令提供离线文档。

实现位于 generate_manpages.rs，其工作原理：

• 基于 clap 的 CommandFactory 取出 CLI 命令树 Cli::command()，使用 clap_mangen 渲染 ROFF 文本；
• 两遍处理：第一遍递归收集所有子命令名（跳过隐藏命令与 help），第二遍为每个命令生成 manpage 并自动追加 SEE ALSO 交叉引用（主命令列出全部一级子命令，子命令列出同级命令），保证 man goose 与 man goose-session 之间可以互相跳转；
• 子命令按 父命令-子命令 规则命名（如 goose-session）；在 Windows 上构建时直接跳过生成，因为 manpage 属于 Unix/Linux 惯例。

该工具面向 Fedora、Debian 等发行版打包场景使用。

延伸阅读

• 安装完成后的下一步是配置 LLM 供应商 的完整参数，以及通过 Using Extensions 指南安装、启用或禁用扩展来扩展 goose 的能力；
• 共享配置文件的完整说明见文档中的 Config Files 指南；
• 各平台安装脚本源码（download_cli.sh、download_cli.ps1）与更新逻辑（update.rs）是深入理解 goose 分发机制的直接依据。