Goose 保姆级部署教程：Block 开源 AI 开发 Agent 从零到一完整搭建

Goose 是 Block（Square 母公司）开源的通用 AI Agent，现在已捐赠给 Linux Foundation 旗下的 Agentic AI Foundation（AAIF）托管。它不是「只能写代码」的插件——从桌面应用到 CLI 到可嵌入的 API，覆盖代码、研究、写作、自动化、数据分析各种场景。整个项目用 Rust 编写，截至本文写作时在 GitHub 上收获约 5.6 万 Star，main 分支几乎每天都有提交。

为什么值得部署？第一，它同时提供桌面 App（macOS / Linux / Windows）和完整 CLI，你的配置（模型、扩展）在两端之间共享，切换无缝。第二，它接 15+ 模型供应商（Anthropic、OpenAI、Google、Ollama、OpenRouter、Azure、Bedrock），还能用你现有的 Claude / ChatGPT / Gemini 订阅通过 ACP 登录。第三，它通过 MCP 开放协议接 70+ 扩展，相当于给 Agent 装上浏览器、终端、数据库等工具。本文从零开始，把 Goose CLI 在 Linux / macOS / Windows 上装好、配好模型、跑完第一个小应用。

一、项目介绍与适用场景

Goose 的形态是「一个会自己读目录、跑命令、写文件、调扩展的 Agent」。你在终端敲 goose session，它进入一个会话，给它一句话比如「帮我用 JS 写个井字棋」，它会自己建计划、写代码、跑起来。适合：

• 桌面党：想要一个图形界面的 AI Agent，不只是代码助手，还能帮你写周报、做研究、自动化桌面操作。
• 服务器党：没有 GUI 的远程开发机，用 CLI 版 goose session 干活。
• CI/CD 玩家：用 GOOSE_VERSION 固定版本把 Goose 钉进流水线，跑自动化任务。
• 想要 Linux Foundation 中立治理：不希望工具被某一家商业公司绑架，项目已进入 AAIF 基金会治理。

二、核心功能逐条拆解

1. 桌面 + CLI 双形态：桌面 App 给 GUI，CLI 给终端，配置共享（provider、模型、扩展集中存储）。
2. 15+ 模型供应商：Anthropic、OpenAI、Google、Ollama、OpenRouter、Azure、Bedrock、SageMaker TGI、GitHub Copilot 等；可直接用 ChatGPT Plus/Pro 订阅登录。
3. 70+ MCP 扩展：通过 MCP 开放协议挂工具，如 Computer Controller（能开浏览器、抓网页、跑自动化）。
4. 会话机制：goose session 起一段连续对话；goose session -r 恢复上一段会话。
5. 配置中心：goose configure 交互式菜单，管 provider、加扩展、开关扩展、调设置。
6. 版本固定：CI/CD 里用 GOOSE_VERSION 环境变量钉版本，避免 stable 标签滚动导致 404。
7. Rust 编写：性能好、跨平台移植性强，官方提供 macOS / Linux / Windows 三端二进制。
8. 扩展凭证独立存储：核心配置共享，扩展凭证可各自存放，适合企业级权限隔离。
9. 访问控制：官方文档提供 access controls 配置，不让 Goose 完全自治。
10. Tetrate Agent Router：官方合作的多模型路由服务，一次登录用多家模型，送 $10 免费额度。

三、全套官方链接

四、硬件与环境前置要求

Goose 本体是 Rust 编译的单二进制，资源占用很小：

• 操作系统：桌面版 macOS（Apple Silicon / Intel）、Linux（DEB / RPM / Flatpak）、Windows；CLI 版 macOS / Linux / Windows（Git Bash / MSYS2 / PowerShell）。
• Windows CLI 前置：Git Bash（推荐）、MSYS2、或 PowerShell 任意一个。
• 依赖：Linux 下解压可能需要 bzip2（官方文档 tip：sudo apt install bzip2 -y）。
• 模型侧：云端 API 只需网络；本地 Ollama 则需自己先装好 Ollama。
• 内存 / CPU：Goose 本体 < 200MB，模型推理在云端或你 GPU 上。

出处：官方 Installation 文档（https://goose-docs.ai/docs/getting-started/installation）。

五、多平台安装步骤

5.1 macOS 安装

桌面版（Homebrew）：官方文档原文：

brew install --cask block-goose

也可以从官网下载 zip（macOS Silicon / Intel 两个包），解压后直接运行。

CLI 版（脚本）：

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

CLI 版（Homebrew）：

brew install block-goose-cli

5.2 Linux 安装

桌面版：下载 DEB（Ubuntu/Debian）后：

sudo dpkg -i (filename).deb

或选 RPM（RHEL/Fedora）、Flatpak（通用）。

CLI 版：

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

官方提示：如果下载解压失败，先装 bzip2：

sudo apt update && sudo apt install bzip2 -y

非交互式安装（CI 场景）：

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

5.3 Windows 安装

桌面版：官网下载 zip，解压运行。

CLI 版（Git Bash / MSYS2）：

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

PowerShell：

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

PATH 设置（官方文档原文）：

Git Bash：

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

PowerShell：

$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"'
. $PROFILE

WSL：

wsl --install
wsl -d Ubuntu

进入 Ubuntu 后再跑上面那条 curl 安装脚本。

六、配置文件全部参数解释

Goose 用 goose configure 交互式配置，官方 quickstart 给出的菜单流程：

┌ goose-configure
│◆ What would you like to configure?
│ ● Configure Providers (Change provider or update credentials)
│ ○ Add Extension
│ ○ Toggle Extensions
│ ○ Remove Extension
│ ○ goose settings
└

Provider 菜单里可选：Amazon Bedrock、SageMaker TGI、Anthropic、Azure OpenAI、ChatGPT Codex、Claude Code CLI、Tetrate Agent Router、Google Gemini、OpenRouter、Ollama 等。

环境变量（官方文档）：

把 Key 持久化到 shell：

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

官方文档明确：goose 会检测到环境变量并显示 ● OPENAI_API_KEY is set via environment variable。

七、启动、后台常驻与开机自启

7.1 启动

goose session

首次启动会引导你选 Provider、选模型。预期：进入会话界面，输入框等你下指令。

恢复上一次会话：

goose session -r

7.2 后台常驻

Goose 是交互式 Agent，本身不设计成常驻服务进程。需要长驻时（如接 IM、跑定时任务）用 tmux：

tmux new -s goose
goose session

7.3 升级

官方文档原文：

goose update

桌面版用 brew upgrade --cask block-goose。

7.4 修改端口

Goose 作为客户端不监听端口；接本地 Ollama 时改 Ollama 的 OLLAMA_HOST，然后在 goose configure 里选 Ollama 时填新 Base URL。

八、功能实操教程

第 1 步：按上面任一平台方法装好 CLI。

第 2 步：跑 goose configure，选 Configure Providers。

第 3 步：选 Tetrate Agent Router Service（官方 quickstart 推荐，送 $10 额度），按提示在浏览器里完成 OAuth；或选 Google Gemini 贴 GOOGLE_API_KEY。

第 4 步：在模型列表里选一个模型（官方示例里推荐 gpt-5，或选 gemini-2.5-pro）。

第 5 步：建个空目录 mkdir goose-demo && cd goose-demo，敲 goose session。

第 6 步：输入官方示例任务：

create an interactive browser-based tic-tac-toe game in javascript where a player competes against a bot

Goose 会自己建计划、写 JS + HTML 文件。

第 7 步：想让它在浏览器里打开游戏？goose configure → Add Extension → Built-in Extension → Computer Controller，timeout 设 300 秒。然后 goose session -r 恢复会话，说「open the tic-tac-toe game in a browser」。

九、全套报错故障排查

报错 1： Windows 下配置时报 keyring 错误。 原因分析：Windows 没有原生 keyring。 解决方案：官方文档提示——配置时选「不存到 keyring」，或手动 export OPENAI_API_KEY=... 后再 goose configure，Goose 会检测到环境变量。

报错 2： macOS M3 启动桌面版没窗口。 原因分析：~/.config 目录没有读写权限（官方 Known Issues）。 解决方案：给 ~/.config 加读写权限，Goose 需要在这里建日志目录。

报错 3： 安装脚本下载后解压失败。 原因分析：缺 bzip2。 解决方案：官方文档 tip：sudo apt install bzip2 -y。

报错 4： goose: command not found。 原因分析：~/.local/bin 不在 PATH。 解决方案：按本文 5.3 节把那行 export 加进 ~/.bashrc 并 source。

报错 5： CI 里拉到 stable 标签后二进制 404。 原因分析：stable 标签滚动，新版不一定包含对应平台二进制。 解决方案：官方文档——用 GOOSE_VERSION=x.y.z 钉死具体版本。

十、升级、回滚与卸载

升级：CLI 跑 goose update；brew 版跑 brew upgrade；桌面版跟随自动更新或重下。

备份建议：Goose 配置在 ~/.config/goose/（含 provider、扩展配置），整个目录打包备份。

回滚：用 GOOSE_VERSION 指定旧版本号重新跑安装脚本。

卸载：删 ~/.local/bin/goose 和 ~/.config/goose/；brew 版 brew uninstall block-goose-cli。

十一、商用许可与合规风险提示

Goose 采用 Apache-2.0，且已捐赠给 Linux Foundation AAIF 基金会治理，商用、二次开发、嵌入自有产品都很友好。注意点：

• 模型 API 费用由你选的 provider 单独计费；Tetrate 路由的 $10 额度是营销行为，用完照常付费。
• 把公司代码喂给 Anthropic / OpenAI 时，确认供应商是否用你的数据训练——敏感场景选 Ollama 本地模型或企业零保留条款。
• Goose 是 Agent 形态，会自己跑命令、开浏览器、读写文件；官方文档专门有 access controls 章节，生产环境务必先配好权限边界再让它自治。
• 项目从 Block 公司捐赠到基金会后，路线图由社区治理，不再是 Block 内部产品。

参考链接

• GitHub 仓库：https://github.com/aaif-goose/goose
• 安装文档：https://goose-docs.ai/docs/getting-started/installation
• 快速上手：https://goose-docs.ai/docs/quickstart
• 故障排查：https://goose-docs.ai/docs/troubleshooting/known-issues