Goose

Goose 快速入门

Block（原 Square）出品的 AI 编程 Agent —— 不只是补全代码，而是真正”干活”。

这是什么？适合谁？

Goose 是 Block 公司（原 Square）开发、现由 Linux Foundation 旗下 Agentic AI Foundation（AAIF）治理的开源 AI Agent，专注于”执行”而非”建议”。它能安装依赖、执行命令、编辑文件、运行测试，像一个真正的开发者一样完成任务。Rust 编写，Apache-2.0 开源，GitHub 51K+ stars，500+ 贡献者，5,118 次提交。

适合谁？一是需要全自主编码 Agent 的开发者；二是需要 AI 处理复杂开发任务的团队；三是注重扩展性的用户（Goose 支持 70+ MCP 扩展和自定义插件系统）。不适合：只需要简单代码补全的用户（用 GitHub Copilot）。

准备工作

• 安装：CLI 一键脚本 curl -fsSL https://github.com/aaif-goose/goose/releases/download/stable/download_cli.sh | bash 或桌面版安装包
• API 密钥：LLM 提供商的 API Key（Anthropic / OpenAI / Google / Ollama / OpenRouter 等 15+ 提供商）
• 系统：macOS / Linux / Windows（桌面版 + CLI）
• 可选：Homebrew 安装：brew install goose

3 步快速上手

第 1 步：安装

# macOS
brew install aaif-goose/tap/goose
# 或从 GitHub Releases 下载
# 或一键脚本
curl -fsSL https://github.com/aaif-goose/goose/releases/download/stable/download_cli.sh | bash

第 2 步：配置

export GOOSE_PROVIDER=openai
export GOOSE_MODEL=gpt-4o
# 或使用 Claude
export GOOSE_PROVIDER=anthropic
export GOOSE_MODEL=claude-sonnet-4
goose session start  # 启动交互会话

第 3 步：运行任务

cd my-project
goose run "给这个项目添加 TypeScript 类型定义"

常见踩坑

踩坑 1：权限不足

• 症状：Goose 无法修改文件
• 原因：文件权限限制
• 解决：确保项目目录有读写权限

踩坑 2：任务超时

• 症状：复杂任务中途停止
• 原因：默认超时限制
• 解决：export GOOSE_MAX_TURNS=2000 增加轮次上限

踩坑 3：Goose 未经确认直接修改文件

• 症状：Goose 执行编辑操作时没有提示用户确认
• 原因：默认模式为 auto，Goose 自动批准工具调用
• 解决：设置 export GOOSE_MODE=approve 或 GOOSE_MODE=smart_approve，每次工具调用前先请求确认
• 参考：Goose 官方文档

踩坑 4：Ollama / DeepSeek 模型不调用工具

• 症状：使用 DeepSeek V4 或本地 Ollama 模型时，Goose 不执行工具调用
• 原因：部分模型不支持工具调用（function calling）
• 解决：切换到支持工具调用的模型（如 qwen2.5、Claude、GPT-4o），或减少不必要的扩展数量
• 参考：GitHub Issue #9333

踩坑 5：Keychain/密钥环错误

• 症状：启动时密钥环相关错误
• 原因：系统密钥环无法访问
• 解决：设置 export GOOSE_DISABLE_KEYRING=1 强制使用文件存储密钥
• 参考：官方 Known Issues

踩坑 6：无限循环/响应停滞

• 症状：Goose 陷入”doom spiral”——反复执行同样的操作或长时间无响应
• 原因：上下文窗口填满或 Agent 逻辑陷入循环
• 解决：Ctrl+C 终止当前会话，启动新会话，将大任务拆分为多个小会话，并使用 .goosehints 提供更多上下文

踩坑 7：Node.js 扩展在 Windows 上不生效

• 症状：Windows 上 MCP 扩展报 “Node.js installer script not found”
• 原因：Node.js 未正确安装或环境变量未设置
• 解决：安装 Node.js 并确保 npx 在 PATH 中，或使用 uvx 运行非 Node 扩展

初级用法

1. 一键代码重构 — 在项目目录运行 goose run "将项目中所有 var 声明改为 const/let"，Goose 自动扫描并修改所有文件
2. 添加测试 — goose run "为 src/utils.js 添加单元测试，使用 Jest"，Goose 自动创建测试文件并验证
3. 文档生成 — goose run "为 src/ 下的所有函数生成 JSDoc 注释"，Goose 逐个文件处理并添加文档
4. Git 操作辅助 — goose run "帮我写 commit message 并提交"，Goose 分析变更内容生成规范的提交信息

高级玩法

1. 子 Agent 并行任务 — Goose 支持子 Agent（Subagents）机制，同时执行多个独立任务：export GOOSE_MAX_BACKGROUND_TASKS=5，让 Goose 将任务分解给子 Agent 并行处理
2. Recipe 工作流 — 创建 .yaml Recipe 文件，固化 AI 工作流（含指令、扩展、参数、子 Recipe），可在不同项目中重复使用
3. ACP 协议连接 IDE — Goose 可作为 ACP（Agent Client Protocol）服务器运行，从 VS Code、JetBrains、Zed 等 IDE 中连接使用 Goose 的能力
4. 自定义 MCP 扩展 — 基于 MCP 标准编写自己的扩展服务器（支持 Python / TypeScript / Go），注册到 Goose 中让 Agent 调用
5. 安全沙箱模式 — 开启高级安全防护：export SECURITY_PROMPT_ENABLED=true 启用提示注入检测，结合 ML 分类器和对抗评审者构建多层级安全防线

小技巧

1. 使用 .goosehints 文件 — 在项目根目录创建 .goosehints 文件，写入项目背景和技术栈说明，Goose 每次运行自动读取，大幅提升输出质量
2. 配方（Recipe）复用 — 将常用的工作流保存为 Recipe YAML 文件，团队共享统一的 AI 工作流规范
3. 自动紧凑上下文 — 设置 export GOOSE_AUTO_COMPACT_THRESHOLD=0.7，当上下文利用率达到 70% 时自动压缩，延长会话寿命
4. 快捷模式切换 — 无需重启，在对话中输入 /mode approve 或 /mode auto 随时切换工具执行模式
5. 成本估算 — 设置 export GOOSE_CLI_SHOW_COST=true 实时显示每次对话的 Token 消耗和费用估算

进阶学习建议

• 深入 Recipe 系统：Goose 的 Recipe 是比简单 Prompt 更强的抽象层，阅读官方文档的 Recipe 指南，学习如何组合子 Recipe、声明扩展依赖和参数化指令
• 搭建自己的 MCP 扩展服务器：Goose 支持 70+ 预置 MCP 扩展，但编写自己的扩展才是真正释放潜力的方式。从 Python FastMCP 框架开始，编写一个连接内部 API 的扩展
• 研究 ACP 协议：Agent Client Protocol 是 Goose 实现跨 IDE 集成的核心协议，学习 ACP 标准后可以编写自定义客户端
• 参与 AAIF 治理：Goose 由 Linux Foundation 旗下的 Agentic AI Foundation 管理，开源治理透明度高，贡献代码或参与技术讨论可以直接影响 Gooes 的发展方向

FAQ 常见问题

Q: Goose 收费吗？

A: 完全免费开源（Apache 2.0）。你只需支付调用 LLM 的 API 费用。新用户可获得 $10 Tetrate 免费额度。也支持使用已有的 ChatGPT Plus/Pro、Claude Code 等订阅。

Q: Goose 和 Claude Code 有什么区别？

A: Goose（51K stars, Apache 2.0）是开源、多提供商、可扩展的 Agent，支持 15+ LLM 提供商和 70+ MCP 扩展。Claude Code（订阅制）仅限 Anthropic 模型。Goose 还能将 Claude Code 作为底层 Provider 使用（通过 ACP 或 CLI Provider 集成）。

Q: 支持哪些 LLM 提供商？

A: 15+ 个：Anthropic Claude、OpenAI GPT、Google Gemini、Ollama 本地模型、OpenRouter、Azure OpenAI、AWS Bedrock、Databricks、GitHub Copilot、ChatGPT 订阅直连等。

Q: 什么是 MCP 扩展？ 如何安装？

A: MCP（Model Context Protocol）是一种标准化的 AI 工具接口协议。Goose 的扩展通过 MCP 服务器提供。安装命令示例：goose mcp add server-name -- python server.py，Goose 自动管理扩展生命周期。

Q: Goose 有桌面端吗？

A: 有。Goose 提供 macOS、Linux、Windows 原生桌面应用，内置 CLI、API 和 MCP Apps（在桌面中渲染交互式 UI 的扩展）。

参考链接

• Goose GitHub
• Goose 文档
• Goose 快速入门
• Goose 已知问题
• Goose GitHub Issues

免责声明

本文基于官方文档和公开资料整理，AI辅助生成，MagicNetWorld 尚未完成独立实测