01 认识 Goose

什么是 Goose？

Goose 是一款开源的 AI 编码代理（AI Coding Agent），由 AI 开源软件基金会（AAIF） 在 Linux Foundation 旗下孵化并维护。它使用 Rust 语言编写并采用 Apache 2.0 许可证，能够自主理解开发者的自然语言指令，自动完成代码生成、调试、重构、文档编写、测试编写、代码审查等软件工程任务。

Goose 最初由 Block（Square）内部开发并开源，后移交至 AAIF 基金会治理，目前已获得 45,000+ GitHub 星标，是当前最活跃的开源 AI 编码代理项目之一。

核心特性

• 多提供商支持 — 支持 OpenAI、Anthropic Claude、Google Gemini、Ollama（本地）、OpenRouter、AWS Bedrock、Azure OpenAI、Groq 等 15+ LLM 提供商
• MCP 扩展生态 — 基于 Model Context Protocol（MCP）的 70+ 扩展，涵盖文件系统、数据库、浏览器、API 调用等能力
• 双模式运行 — CLI 命令行工具 + Desktop 桌面图形应用，满足不同使用习惯
• 自主代理能力 — 能够规划多步骤任务、执行命令、读写文件、调用 API，全程无需人工干预
• ACP 协议 — 支持 Agent Communication Protocol，可与其他 AI 代理互操作
• 完全本地可运行 — 搭配 Ollama 等本地模型，无需任何外部 API 即可在离线环境使用

Goose vs. 其他 AI 编码工具

💡 提示： Goose 的最大优势在于开源透明、提供商无关的架构和丰富的 MCP 扩展生态。你可以自由选择最适合你需求和预算的模型。

02 快速上手（5 分钟）

本章带你从零开始，在 5 分钟内完成 Goose 的安装、配置并成功运行第一次任务。

步骤 1：安装 Goose

根据你的操作系统选择以下一种方式安装：

macOS / Linux（推荐）：

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

macOS（Homebrew）：

brew install block-goose-cli

Windows： 下载 PowerShell 安装脚本并运行：

# 下载安装脚本
Invoke-WebRequest -Uri https://github.com/aaif-goose/goose/releases/download/stable/download_cli.ps1 -OutFile download_cli.ps1
# 运行安装脚本
.\download_cli.ps1

步骤 2：配置 LLM 提供商

运行配置向导，选择你想要的 LLM 提供商并输入 API 密钥：

goose configure

配置向导会引导你完成以下步骤：

1. 选择 LLM 提供商（如 OpenAI、Anthropic、Ollama 等）
2. 输入 API Key（本地模型可跳过）
3. 选择模型名称
4. 确认配置并保存至 ~/.config/goose/config.yaml

💡 提示： 你也可以通过环境变量快速配置。设置 GOOSE_PROVIDER 和 GOOSE_MODEL 即可跳过配置向导直接使用。

步骤 3：运行你的第一个任务

安装并配置完成后，使用以下命令让 Goose 执行你的第一个任务：

goose run -t "创建一个 Python 脚本，输出 'Hello, Goose!'，并在当前目录生成一个 README.md 文件说明如何使用"

Goose 会自动理解你的指令，规划执行步骤，创建文件并输出结果。

步骤 4：验证安装

确认 Goose 已正确安装：

goose --version

如果看到版本号输出，说明安装成功！

💡 提示： 使用 goose --help 查看所有可用命令和选项。

03 安装指南

Goose 支持多种安装方式，覆盖所有主流操作系统。以下是完整的安装方法汇总。

macOS / Linux — 一键脚本安装（推荐）

使用官方安装脚本自动下载并安装最新稳定版：

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

该脚本会自动检测操作系统架构，下载对应的二进制文件并添加到 PATH。

macOS — Homebrew 安装

CLI 命令行工具：

brew install block-goose-cli

Desktop 桌面应用：

brew install --cask block-goose

Windows 安装

下载 PowerShell 安装脚本并执行：

Invoke-WebRequest -Uri https://github.com/aaif-goose/goose/releases/download/stable/download_cli.ps1 -OutFile download_cli.ps1
.\download_cli.ps1

Desktop 桌面应用（跨平台）

访问 GitHub Releases 页面 下载对应平台的安装包：

• macOS: Goose-*.dmg
• Windows: Goose-*.exe
• Linux: Goose-*.AppImage

从源码编译安装

如果你有 Rust 开发环境，可以从源码编译：

git clone https://github.com/aaif-goose/goose.git
cd goose
cargo build --release
# 编译后的二进制文件在 target/release/goose

验证安装

安装完成后，验证是否成功：

goose --version

💡 提示： 推荐首次用户使用一键脚本安装或 Homebrew 安装，快速开始无需手动配置 Rust 环境。

04 配置 LLM 提供商

Goose 支持 15+ LLM 提供商。你可以自由选择和切换后端模型，而无需改变使用方式。

使用配置向导（推荐）

最简单的方式是运行交互式配置向导：

goose configure

配置向导会以菜单形式引导你完成提供商选择、API Key 输入和模型选择。

支持的 LLM 提供商

使用环境变量配置

设置以下环境变量可以快速配置，跳过交互式向导：

# 设置提供商和模型
export GOOSE_PROVIDER=openai
export GOOSE_MODEL=gpt-4o

# 设置 API Key（不同提供商对应不同变量名）
export OPENAI_API_KEY=sk-xxxxxxxxxxxx

# 启用调试输出
export GOOSE_DEBUG=1

通过命令设置

你也可以直接通过命令行设置提供商：

goose configure --set provider anthropic

直接编辑配置文件

配置文件位于 ~/.config/goose/config.yaml。手动编辑可获得最精细的控制：

# 打开配置文件
vim ~/.config/goose/config.yaml

💡 提示： 对于本地开发和测试，推荐搭配 Ollama 使用开源模型（如 Llama 3、Qwen 2.5），完全免费且无需联网。对于生产级别的代码生成，推荐使用 Claude 3.5 Sonnet 或 GPT-4o。

05 日常使用

Goose 提供多种使用模式，适应不同的工作场景。

交互式会话

直接运行 goose 启动交互式会话。你会进入一个对话界面，可以连续向 Goose 提出多个任务：

goose

在交互式会话中，你可以：

• 提出连续的多步骤任务
• 要求修改之前生成的内容
• 让 Goose 解释它所做的操作
• 随时输入 /exit 或 /quit 退出

单次执行（Inline 模式）

使用 goose run -t 直接传入文本指令执行一次性任务：

goose run -t "在当前目录下创建一个 Python Flask Web 应用，包含一个返回 JSON 的 /api/hello 端点"

从文件加载指令

将指令写入文件，通过 --instructions 参数传入：

goose run --instructions task.md

task.md 文件内容示例：

请完成以下任务：
1. 在当前目录初始化一个 Node.js 项目
2. 安装 Express 框架
3. 创建一个包含 GET / 和 POST /data 两个端点的服务器
4. 添加一个测试文件使用 Supertest 进行测试

从标准输入读取

通过管道或重定向将指令传入：

echo "查找当前目录下所有超过 1MB 的文件并列出它们" | goose run -i -

Desktop 桌面应用

Goose Desktop 提供了图形界面，适合不习惯命令行的用户。安装后打开应用：

• 通过直观的聊天界面与 Goose 交互
• 可视化查看文件变更和命令执行结果
• 通过图形界面管理 MCP 扩展
• 支持暗色/亮色主题切换

从 GitHub Releases 下载桌面应用：

• macOS: Goose-*.dmg
• Windows: Goose-*.exe
• Linux: Goose-*.AppImage

💡 提示： 对于日常开发中的重复性任务，建议使用 goose run -t 的单次执行模式。对于复杂的多步骤项目，交互式会话更为高效。

06 MCP 扩展

MCP（Model Context Protocol）是 Goose 的扩展协议，允许 Goose 通过标准化的接口与外部工具和服务交互。Goose 拥有 70+ MCP 扩展，涵盖文件系统、数据库、浏览器、API 调用等能力。

⚠️ 重要： Goose 没有 goose mcp list、goose mcp install 或 goose mcp uninstall 命令。MCP 扩展通过 goose configure 交互式菜单或直接编辑配置文件来管理。

方法一：通过配置向导管理扩展

运行 goose configure 进入交互式菜单，选择添加/删除扩展：

goose configure

在向导中你可以浏览可用扩展、添加新扩展或移除已有扩展。

方法二：在单次执行中使用扩展

使用 --with-extension 参数临时加载扩展：

goose run -t "列出当前目录下所有 Python 文件的内容" --with-extension npx/@modelcontextprotocol/server-filesystem

方法三：手动编辑配置文件

配置文件位于 ~/.config/goose/config.yaml，可以直接编辑添加扩展配置：

# ~/.config/goose/config.yaml 扩展配置示例
extensions:
  filesystem:
    type: stdio
    command: npx
    args:
      - "@modelcontextprotocol/server-filesystem"
      - /path/to/allowed/directory
  github:
    type: stdio
    command: npx
    args:
      - "@modelcontextprotocol/server-github"
    env:
      GITHUB_TOKEN: ghp_xxxxxxxxxxxx

常用 MCP 扩展列表

💡 提示： MCP 扩展是 Goose 生态中最强大的功能之一。通过组合多个扩展，Goose 可以完成非常复杂的跨系统任务，例如：读取数据库 → 分析数据 → 生成报告 → 通过 GitHub 提交 PR。

07 进阶技巧

自定义 System Prompt（.goosehints 文件）

Goose 支持通过 ~/.goosehints 文件自定义系统提示词（System Prompt），让 Goose 按照你的偏好行事：

# 在 ~/.goosehints 中写入以下内容
你是一位资深 Rust 开发者。请遵循以下原则：
- 所有代码必须通过 clippy 检查
- 优先使用迭代器而非显式循环
- 为所有公开函数添加文档注释
- 使用 anyhow 处理错误

.goosehints 文件会附加到每次会话的 system prompt 中，影响 Goose 的行为风格和质量标准。

💡 提示： 你可以在项目根目录下创建 .goosehints 文件，实现项目级别的自定义提示。Goose 会自动检测并加载当前目录及其父目录中的该文件。

创建命令别名

为了更高效地使用 Goose，可以在 shell 配置文件中创建别名：

# 在 ~/.zshrc 或 ~/.bashrc 中添加
alias goosed='GOOSE_DEBUG=1 goose'
alias goosereview='goose run -t "Review the code changes in the current git diff and suggest improvements"'
alias goosecommit='goose run -t "Write a commit message for the current git diff and commit"'
alias gpt4='GOOSE_PROVIDER=openai GOOSE_MODEL=gpt-4o goose'
alias claude='GOOSE_PROVIDER=anthropic GOOSE_MODEL=claude-sonnet-4-20250514 goose'

在 CI/CD 中使用 Goose

Goose 可以集成到 CI/CD 流水线中，实现自动化的代码审查、文档生成或测试编写：

# .github/workflows/goose-review.yml 示例
name: Goose Code Review
on: [pull_request]
jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install Goose
        run: curl -fsSL https://github.com/aaif-goose/goose/releases/download/stable/download_cli.sh | bash
      - name: Run Code Review
        env:
          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
          GOOSE_PROVIDER: openai
          GOOSE_MODEL: gpt-4o
        run: goose run -t "Review the git diff of this PR and provide feedback on code quality, potential bugs, and suggestions for improvement"

成本优化策略

• 本地模型优先 — 日常开发和简单任务使用 Ollama + Llama 3 或 Qwen 2.5，完全免费
• 分级使用 — 简单任务用便宜模型（GPT-4o-mini），复杂任务用高端模型（Claude Sonnet）
• 使用 OpenRouter — 统一管理多个提供商和 API Key，按用量付费，可设置价格上限
• 限制会话长度 — 避免过长的交互式会话消耗大量 Token
• 精确指令 — 指令越精确，模型需要的推理步骤越少，Token 消耗越低

配置运行模式

通过 GOOSE_MODE 环境变量控制运行模式：

# 自动模式（默认）- 自动执行所有操作，无需确认
export GOOSE_MODE=auto

# 审批模式 - 每次操作前请求用户确认
export GOOSE_MODE=approve

# 聊天模式 - 纯对话，不执行操作
export GOOSE_MODE=chat

# 智能审批模式 - 根据风险级别判断是否需要确认
export GOOSE_MODE=smart_approve

08 常见问题与排错

1. 安装失败：「curl: command not found」

原因： 系统未安装 curl。

解决： 使用 Homebrew 安装（macOS）或通过包管理器安装 curl（Linux）：

# macOS
brew install curl

# Ubuntu/Debian
sudo apt install curl

# CentOS/RHEL
sudo yum install curl

2. 「command not found: goose」

原因： Goose 不在 PATH 中。

解决： 安装脚本会自动添加到 PATH，但可能需要重启终端或重新加载配置文件：

# 重新加载 shell 配置
source ~/.zshrc  # 或 source ~/.bashrc
# 或手动添加路径
export PATH="$HOME/.goose/bin:$PATH"

3. 「No provider configured」错误

原因： 未配置 LLM 提供商。

解决： 运行 goose configure 完成配置，或设置环境变量：

export GOOSE_PROVIDER=openai
export GOOSE_MODEL=gpt-4o
export OPENAI_API_KEY=sk-xxxxxxxxxxxx

4. API 认证错误「401 Unauthorized」

原因： API Key 无效或未设置。

解决： 检查 API Key 是否正确，确保环境变量名与提供商匹配。例如 OpenAI 使用 OPENAI_API_KEY，Anthropic 使用 ANTHROPIC_API_KEY。

5. 速率限制错误「429 Too Many Requests」

原因： 短时间内请求过多。

解决： 降低使用频率，或升级 API 套餐获取更高速率限制。使用本地模型（Ollama）可完全避免此问题。

6. 模型返回结果质量差

原因： 使用的模型不适合当前任务。

解决： 切换至更强大的模型（如 Claude Sonnet 或 GPT-4o），或在 .goosehints 文件中提供更详细的上下文和示例。

7. MCP 扩展不工作

原因： 扩展配置错误或依赖未安装。

解决：

• 确保 Node.js 已安装（npx 扩展需要）
• 检查 ~/.config/goose/config.yaml 中的扩展配置格式
• 运行 goose configure 重新添加扩展

8. Goose 运行缓慢

原因： 网络延迟、模型响应慢或 Token 消耗大。

解决： 使用本地模型（Ollama）消除网络延迟，或选择响应更快的模型（如 GPT-4o-mini）。对于大项目，拆分任务为更小的子任务。

9. Goose 在 Windows 上无法运行

原因： PowerShell 执行策略限制。

解决： 以管理员身份运行 PowerShell 并设置执行策略：

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

10. 配置文件在哪里？

原因： 找不到配置文件。

解决： Goose 的配置文件位于 ~/.config/goose/config.yaml。你可以通过以下命令确认文件是否已创建：

ls -la ~/.config/goose/config.yaml

11. 如何更新 Goose？

原因： 需要升级到最新版本。

解决： 重新运行安装脚本即可覆盖更新：

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

12. 日志输出在哪里？

原因： 需要调试问题。

解决： 设置 GOOSE_LOG_LEVEL 环境变量控制日志级别：

export GOOSE_LOG_LEVEL=debug
export GOOSE_DEBUG=1
goose run -t "Your task"

💡 提示： 遇到问题时，首先运行 goose --version 确认版本，然后检查 goose configure 是否正确配置了提供商。大部分问题源于配置错误或 API Key 问题。

09 附录

A. 命令参考速查表

B. 安装命令速查表

C. 环境变量参考表

D. 常用 MCP 扩展参考表

💡 提示： 本书附录可作为日常使用的快速参考。将常用命令和环境变量截图或打印出来，贴在工位上方便查阅。