从零开始搭建部署 block/goose 完整攻略

从零开始搭建部署 goose 完整攻略

新手入门指南 - V1.0版本

📋 目录

• 简介
• 系统要求
• 系统安装
• 首次配置与运行
• 常用指令大全
• 通过示例快速体验
• 日常维护
• 故障排除
• 进阶配置
• 常见问题
• 资源链接与快速参考卡

简介

goose 是一个本地化、可扩展、开源的 AI 智能体框架，旨在自动化复杂的软件工程任务。与传统的代码补全工具不同，goose 能够理解高层次的目标，并自主执行从代码编写、文件操作、命令运行到调试、测试的完整工作流。它是一个运行在你机器上的“AI 工程师助手”。

核心功能概览：

• 🤖 自主任务执行：根据自然语言指令，完成从项目创建到代码部署的多种任务。
• 🔧 本地优先与可扩展：核心逻辑在本地运行，支持通过 Model Context Protocol (MCP) 集成多种工具和扩展。
• 💻 多模态交互：提供桌面图形界面 (GUI) 和命令行界面 (CLI)，满足不同场景需求。
• 📦 灵活的模型支持：可配置使用云端或本地的多种大型语言模型 (LLM)。
• 📁 项目感知与操作：内置开发者工具，可直接读写文件、运行 Shell 命令、分析代码结构。

版本说明：本指南基于 goose 主分支（版本约 1.21.0）编写。项目处于活跃开发中，部分功能可能更新，请以官方文档为准。

教程约定：

• 命令：表示在终端中执行的命令。
• $：表示命令提示符，其后的内容是需要你输入的命令。
• (GUI)：表示在桌面应用程序中进行的操作。
• 路径/文件名：表示文件系统路径或文件名。

系统要求

在安装 goose 前，请确保你的系统满足以下基础要求。

组件	最低要求	推荐配置	说明
操作系统	Windows 10 (1809+), macOS 11+, Linux (主流发行版)	最新稳定版	需为64位系统。
处理器	支持 SSE2 的 x86_64 或 Apple Silicon (arm64)	多核处理器	主要用于运行客户端，重型计算在模型服务端。
内存	4 GB RAM	8 GB RAM 或更高	运行桌面应用和多个扩展时需要更多内存。
磁盘空间	500 MB 可用空间	1 GB 或更多	用于安装二进制文件、存储配置和缓存。
网络连接	可访问互联网	稳定的宽带连接	用于下载安装包、与模型 API 通信。
依赖环境	无（二进制版本）	Git, Rust（从源码编译时）	大多数用户只需下载二进制文件。

各系统额外要求与提示：

• Windows：建议在 WSL 2 (Windows Subsystem for Linux) 环境下使用 CLI，以获得最佳兼容性。原生 Windows 命令提示符或 PowerShell 也可运行。
• macOS：可能需要允许运行来自“未识别开发者”的应用（首次运行时在系统偏好设置的“安全性与隐私”中批准）。
• Linux：需要基础的开发库（如 libssl, ca-certificates）。使用包管理器安装（如 apt, yum, dnf）即可。
• 通用提示：
  • 代理设置：如果你所在网络需要代理才能访问 GitHub 或模型 API，请提前在系统或终端中配置好 HTTP/HTTPS 代理。
  • 权限问题：安装和运行可能需要管理员/root权限（如安装到 /usr/local/bin）。

系统安装

goose 提供多种安装方式，你可以根据操作系统和偏好选择最合适的一种。

方案一：使用官方安装脚本（推荐，适用于所有主流系统）

这是最简单快捷的方式，脚本会自动检测系统并下载对应的预编译二进制文件。

1. 打开终端 (Windows 可使用 PowerShell, CMD, 或 WSL终端)。

2. 执行安装命令：

   # 下载并运行安装脚本
   $ curl -fsSL https://github.com/block/goose/releases/download/stable/download_cli.sh | bash
   

   脚本行为说明：

   • 自动检测你的操作系统（Linux, macOS, Windows）和架构（x86_64, arm64）。
   • 默认将 goose 二进制下载到 $HOME/.local/bin/ 目录（Windows 为 %USERPROFILE%\goose）。
   • 安装完成后，会尝试引导你进行首次配置（可跳过，后续手动进行）。

3. 将 goose 添加到 PATH（如果脚本提示）： 安装后，如果终端提示 GOOSE_BIN_DIR 不在 PATH 中，你需要手动添加。

   • Linux/macOS：将以下行添加到 ~/.bashrc, ~/.zshrc 或你所用 shell 的配置文件中。

     export PATH="$HOME/.local/bin:$PATH"
     

     然后执行 source ~/.bashrc（或对应配置文件）使其生效。
   • Windows (PowerShell)：将以下行添加到 $PROFILE 文件中。

     $env:Path = "$env:USERPROFILE\goose;" + $env:Path
     

4. 验证安装：

   $ goose --version
   

   如果成功，将显示类似 goose 1.21.0 的版本信息。

方案二：使用 Docker（适合容器化环境）

如果你熟悉 Docker，这是保持环境纯净的好方法。项目提供了官方的 Docker 镜像。

1. 拉取 goose 镜像：

   $ docker pull ghcr.io/block/goose:latest
   

2. 运行 goose 容器（基础命令）：

   # 以交互模式运行，并挂载当前目录到容器内以便 goose 操作文件
   $ docker run -it --rm -v $(pwd):/home/goose/workspace ghcr.io/block/goose:latest
   # 获取帮助
   $ docker run --rm ghcr.io/block/goose:latest --help
   

   注意：Docker 方式主要运行 CLI。如需桌面应用或更复杂的集成，建议使用其他安装方式。

方案三：桌面应用程序（适合偏好图形界面的用户）

如果你不想使用命令行，可以直接下载并运行桌面应用。

1. 访问 GitHub Releases 页面。
2. 找到最新的版本，在“Assets”部分下载对应你系统的安装包：
   • macOS: .dmg 文件 (Apple Silicon 或 Intel)
   • Windows: .exe 安装程序或 .zip 压缩包
   • Linux: .AppImage, .deb, 或 .rpm 文件
3. 像安装普通软件一样完成安装并启动。

方案四：从源代码构建（适合开发者或定制需求）

此方式要求已安装 Rust 工具链。

1. 安装 Rust (如未安装):

   $ curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
   $ source $HOME/.cargo/env
   

2. 克隆仓库并构建:

   $ git clone https://github.com/block/goose.git
   $ cd goose
   # 构建 CLI
   $ cargo build --release --package goose-cli
   # 构建完成后，二进制位于 target/release/goose
   $ cp target/release/goose ~/.local/bin/  # 或其它 PATH 目录
   

安装后验证：无论采用哪种方式，都请执行 goose --version 或启动桌面应用，确认安装成功。

首次配置与运行

首次运行 goose 需要进行基础配置，主要是设置 AI 模型。

1. 启动配置向导

在终端中执行：

$ goose configure

此命令将启动一个交互式配置向导。

2. 核心配置步骤

向导会引导你完成以下关键设置：

• 选择 Provider (模型提供商)： 你会看到如 databricks、openai 等选项。这取决于你想要使用的 AI 服务。

  • 如果你使用 OpenAI 的模型（如 GPT-4），选择 openai。
  • 如果你使用 Databricks 提供的模型（项目示例中提到的 goose 模型），选择 databricks。
  • 其他选项对应其他支持的模型服务。

• 配置 API 密钥： 选择 Provider 后，系统会提示你输入相应的 API 密钥。

  • 对于 OpenAI：你需要一个有效的 OpenAI API Key。
  • 对于 Databricks：你需要配置 Databricks 主机和令牌。
  • 安全提示：API 密钥是敏感信息，请妥善保管。goose 会将其加密存储在本地配置文件中（通常位于 ~/.config/goose/config.toml）。

• 选择模型： 根据上一步选择的 Provider，系统会列出可用的模型（例如 gpt-4o, gpt-4-turbo, claude-3-5-sonnet 或 databricks 特定的模型名）。选择你想使用的模型。

• 工作目录设置： 配置 goose 操作文件的默认目录。可以保持默认（当前用户目录），或指定一个专用路径。

3. 配置完成与快速测试

配置完成后，你可以通过一个简单命令测试 goose 是否工作正常：

# 向 goose 发送一个简单指令
$ goose run "请用当前目录下的文件名创建一个 Markdown 列表"

如果配置正确，goose 会列出当前目录的文件。你可能会看到它调用了相关工具（如 developer 扩展）来完成此任务。

4. （可选）启动桌面应用

如果你安装了桌面版，首次启动时，应用界面内通常也会有类似的配置流程，引导你输入 Provider 和 API Key。

常用指令大全

掌握以下核心命令将帮助你高效使用 goose CLI。

基础命令

命令	说明	示例
goose --version	查看版本信息。	$ goose --version
goose --help	查看全局帮助。	$ goose --help
goose configure	交互式配置向导。	$ goose configure
goose doctor	运行诊断，检查系统环境和配置。	$ goose doctor

任务执行命令

命令	说明	示例
goose run <指令>	执行单条自然语言指令。	$ goose run "创建一个简单的Python HTTP服务器"
goose chat	进入交互式对话模式。	$ goose chat
goose cook <recipe文件>	执行一个预定义的“食谱”任务。	$ goose cook recipe.yaml

扩展管理命令

命令	说明	示例
goose extensions list	列出已安装和可用的扩展。	$ goose extensions list
goose extensions add <名称>	安装一个新扩展。	$ goose extensions add fetch
goose extensions remove <名称>	移除一个扩展。	$ goose extensions remove fetch

会话与日志命令

命令	说明	示例
goose sessions list	列出历史会话。	$ goose sessions list
goose logs	查看 goose 的运行日志（需指定日志路径，通常在配置中）。	$ tail -f ~/.config/goose/logs/goose.log

服务器命令（用于高级集成）

命令	说明	示例
goose server start	启动 goose 的本地 API 服务器。	$ goose server start --port 3001
goose server stop	停止本地 API 服务器。	$ goose server stop
goose server status	查看服务器状态。	$ goose server status

通过示例快速体验

理论不如实践。让我们通过运行一个内置的“食谱”来直观感受 goose 的能力。我们将执行 recipe.yaml 中描述的 404Portfolio 任务。

1. 准备 recipe 文件： 将项目中的 recipe.yaml 内容保存为一个文件，例如 404recipe.yaml，放在你的工作目录。

2. 执行食谱任务：

   $ goose cook ./404recipe.yaml
   

3. 与 goose 交互： 命令执行后，goose 会开始处理这个复杂任务。它会：

   • 理解任务目标：创建一个基于用户公开资料的个性化 404 页面。
   • 向你提问：首先，它会询问你使用哪个平台（GitHub, Dev.to, Bluesky）及对应的用户名。
   • 自主执行：根据你的回答，它会调用内置的 developer 扩展来创建目录和文件，并可能调用 fetch 等扩展（如果已安装）去获取公开API数据。
   • 编写代码：最终，它会在一个名为 404-story 的文件夹中生成一个完整的、包含 HTML、CSS、JavaScript 的静态网站。

4. 查看结果：

   $ ls -la ./404-story/
   $ open ./404-story/index.html  # 在macOS中打开
   # 或
   $ start ./404-story/index.html # 在Windows中打开
   

这个例子展示了 goose 如何将高层次的需求分解为一系列具体操作（提问、获取数据、编写代码、组织文件），并自主完成。

日常维护

1. 检查更新： goose 项目迭代较快。定期查看 GitHub Releases 页面，或使用桌面应用内的更新检查功能（如有）。

   # 对于 CLI，重新运行安装脚本通常可以更新到最新稳定版
   $ curl -fsSL https://github.com/block/goose/releases/download/stable/download_cli.sh | bash
   

2. 管理配置： 配置文件通常位于 ~/.config/goose/config.toml。你可以手动编辑它，但建议使用 goose configure 命令修改主要设置。

3. 清理缓存： 扩展和模型可能会产生缓存。缓存目录通常也在配置文件夹下（~/.cache/goose/）。定期清理可以释放磁盘空间。

4. 日志管理： 遇到问题时，日志是第一手资料。默认日志路径在 ~/.config/goose/logs/。你可以配置日志级别（如 RUST_LOG=debug）来获取更详细的信息。

   # 以调试模式运行并查看输出
   $ RUST_LOG=debug goose run "你的指令" 2>&1 | less
   

故障排除

问题：命令未找到 (command not found: goose)

• 原因：goose 二进制所在目录未加入系统 PATH。
• 解决：参考 系统安装 章节，将 $HOME/.local/bin（或你自定义的目录）添加到 shell 的 PATH 环境变量中。

问题：配置 API 密钥后，运行任务失败，提示认证错误

• 原因：API 密钥无效、过期，或网络无法访问对应服务商。
• 解决：
  1. 重新在对应服务商平台检查并复制正确的 API 密钥。
  2. 运行 goose configure 重新配置。
  3. 检查网络连接和代理设置。
  4. 运行 goose doctor 查看更详细的错误信息。

问题：执行文件操作或 Shell 命令时权限被拒绝

• 原因：goose 进程权限不足以访问目标目录或执行命令。
• 解决：
  1. 确保工作目录路径正确且 goose 有读写权限。
  2. 在 Linux/macOS 下，避免在 /root 或 /etc 等系统目录下直接操作，建议在用户目录内进行。
  3. 检查是否有防病毒软件或沙盒机制阻止了 goose 的操作。

问题：桌面应用启动失败或崩溃

• 原因：可能是缺少运行时依赖，或与系统图形环境不兼容。
• 解决：
  1. 确保系统已安装必要的图形库（如 Linux 下的 libgtk 系列）。
  2. 尝试以命令行启动桌面应用（如果支持），查看错误输出。
  3. 查看应用日志（通常可在 ~/.config/Goose/logs/ 找到）。
  4. 考虑使用 CLI 版本作为替代。

通用诊断流程：

1. 运行 goose doctor：这是内置的诊断工具，能检查核心配置和依赖。
2. 检查日志：查看详细错误信息。
3. 简化复现：尝试一个最简单的指令（如 goose run "echo hello"）是否能成功。
4. 查阅社区：前往 Discord 或 GitHub Issues 搜索类似问题。

进阶配置

goose 的配置文件 (~/.config/goose/config.toml) 支持更精细的调整。以下是一个配置示例片段及其说明：

[agent]
# 默认使用的模型提供商和模型
provider = "openai"
model = "gpt-4o"

# 工作目录
working_dir = "/Users/yourname/Projects"

[agent.openai]
# OpenAI 特定的配置
api_key = "sk-..." # 建议通过 configure 设置，这里会自动填充
base_url = "https://api.openai.com/v1" # 可指向自定义端点

[extensions]
# 自动启用的内置扩展
enabled = ["developer", "computercontroller"]

# 自定义扩展配置
[[extensions.custom]]
name = "my_mcp_tool"
type = "stdio" # 通过标准输入输出通信
cmd = "uvx"    # 使用 uvx 工具运行
args = ["my-mcp-server"] # 服务器命令

适用场景：

• 多模型切换：你可以创建多个配置节，通过环境变量或命令行参数快速切换。
• 自定义 MCP 服务器：集成自己编写的或第三方的 MCP 服务器以扩展 goose 的工具集。
• 网络与代理：在配置中指定代理服务器地址。

常见问题

Q：goose 会把我本地的代码上传到云端吗？ A：不会。 goose 是一个本地优先的框架。代码、文件操作都在你的机器上完成。只有为了理解指令和生成计划，你选择的 LLM 提供商（如 OpenAI）会收到相关的文本提示。API 密钥和模型调用是你的直接交互。务必阅读并理解你所选模型提供商的数据使用政策。

Q：支持哪些编程语言和框架？ A：goose 不限于特定语言。它的能力取决于其集成的工具（扩展）和背后 LLM 的知识。内置的 developer 扩展可以操作任何文本文件，因此理论上可以处理任何语言的代码。对于特定框架的深度支持，需要相应的扩展或 LLM 具备相关知识。

Q：运行 goose 成本高吗？ A：成本主要来自你使用的 云端 LLM API 调用（如 OpenAI, Anthropic）。goose 本身是免费开源的。你可以通过以下方式控制成本： - 使用更经济的模型（如 gpt-4o-mini 而非 gpt-4o）。 - 在配置中设置使用限制。 - 对于简单任务，考虑使用本地开源模型（需要额外配置兼容的 MCP 服务器）。

Q：如何为 goose 开发扩展？ A：goose 通过 Model Context Protocol (MCP) 集成扩展。你可以遵循 MCP 协议开发任何语言编写的服务器，并通过配置文件将其添加为 stdio 类型的扩展。参考 rmpc crate 和 MCP 官方文档进行开发。

Q：goose run 和 goose chat 有什么区别？ A：goose run 是单次指令执行模式，适合明确的、独立的任务。goose chat 是交互式会话模式，会保留对话历史上下文，适合需要多轮讨论、调试或探索的复杂任务。

资源链接与快速参考卡

官方资源：

• GitHub 仓库：github.com/block/goose (代码、Issues、Releases)
• 官方文档：block.github.io/goose/docs
• Discord 社区：discord.gg/goose-oss (获取实时帮助和交流)
• 项目官网：goose.blocks (如有)

快速参考卡 (Cheatsheet)：

场景	核心命令
安装与更新	curl -fsSL ...download_cli.sh | bash
首次配置	goose configure
执行一个任务	goose run “你的指令”
交互式对话	goose chat
运行食谱	goose cook recipe.yaml
列出扩展	goose extensions list
启动API服务	goose server start --port 3001
查看版本	goose --version
诊断问题	goose doctor

反馈与贡献：

• 发现 bug 或有功能建议？请在 GitHub Issues 创建。
• 想贡献代码？请阅读仓库中的 CONTRIBUTING.md（如有）和 GOVERNANCE.md 文件。
• 翻译或文档改进也是宝贵的贡献。

---

祝你使用 goose 开发愉快，提升工程效率！ 🦢