CATS
138.50M · 2026-02-04
新手入门指南 - V1.0版本
goose 是一个本地化、可扩展、开源的 AI 智能体框架，旨在自动化复杂的软件工程任务。与传统的代码补全工具不同，goose 能够理解高层次的目标，并自主执行从代码编写、文件操作、命令运行到调试、测试的完整工作流。它是一个运行在你机器上的“AI 工程师助手”。
核心功能概览：
版本说明：本指南基于 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（从源码编译时） | 大多数用户只需下载二进制文件。 |
各系统额外要求与提示：
libssl, ca-certificates）。使用包管理器安装（如 apt, yum, dnf）即可。/usr/local/bin）。goose 提供多种安装方式，你可以根据操作系统和偏好选择最合适的一种。
这是最简单快捷的方式，脚本会自动检测系统并下载对应的预编译二进制文件。
打开终端 (Windows 可使用 PowerShell, CMD, 或 WSL终端)。
执行安装命令：
# 下载并运行安装脚本
$ curl -fsSL | bash
脚本行为说明：
goose 二进制下载到 $HOME/.local/bin/ 目录（Windows 为 %USERPROFILE%goose）。将 goose 添加到 PATH（如果脚本提示）：
安装后，如果终端提示 GOOSE_BIN_DIR 不在 PATH 中，你需要手动添加。
~/.bashrc, ~/.zshrc 或你所用 shell 的配置文件中。
export PATH="$HOME/.local/bin:$PATH"
source ~/.bashrc（或对应配置文件）使其生效。$PROFILE 文件中。
$env:Path = "$env:USERPROFILEgoose;" + $env:Path
验证安装：
$ goose --version
如果成功，将显示类似 goose 1.21.0 的版本信息。
如果你熟悉 Docker，这是保持环境纯净的好方法。项目提供了官方的 Docker 镜像。
拉取 goose 镜像：
$ docker pull ghcr.io/block/goose:latest
运行 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。如需桌面应用或更复杂的集成，建议使用其他安装方式。
如果你不想使用命令行，可以直接下载并运行桌面应用。
.dmg 文件 (Apple Silicon 或 Intel).exe 安装程序或 .zip 压缩包.AppImage, .deb, 或 .rpm 文件此方式要求已安装 Rust 工具链。
安装 Rust (如未安装):
$ curl --proto '=https' --tlsv1.2 -sSf | sh
$ source $HOME/.cargo/env
克隆仓库并构建:
$ git clone
$ cd goose
# 构建 CLI
$ cargo build --release --package goose-cli
# 构建完成后，二进制位于 target/release/goose
$ cp target/release/goose ~/.local/bin/ # 或其它 PATH 目录
安装后验证：无论采用哪种方式，都请执行 goose --version 或启动桌面应用，确认安装成功。
首次运行 goose 需要进行基础配置，主要是设置 AI 模型。
在终端中执行：
$ goose configure
此命令将启动一个交互式配置向导。
向导会引导你完成以下关键设置：
选择 Provider (模型提供商)：
你会看到如 databricks、openai 等选项。这取决于你想要使用的 AI 服务。
openai。goose 模型），选择 databricks。配置 API 密钥： 选择 Provider 后，系统会提示你输入相应的 API 密钥。
~/.config/goose/config.toml）。选择模型：
根据上一步选择的 Provider，系统会列出可用的模型（例如 gpt-4o, gpt-4-turbo, claude-3-5-sonnet 或 databricks 特定的模型名）。选择你想使用的模型。
工作目录设置： 配置 goose 操作文件的默认目录。可以保持默认（当前用户目录），或指定一个专用路径。
配置完成后，你可以通过一个简单命令测试 goose 是否工作正常：
# 向 goose 发送一个简单指令
$ goose run "请用当前目录下的文件名创建一个 Markdown 列表"
如果配置正确，goose 会列出当前目录的文件。你可能会看到它调用了相关工具（如 developer 扩展）来完成此任务。
如果你安装了桌面版，首次启动时，应用界面内通常也会有类似的配置流程，引导你输入 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 ch@t | 进入交互式对话模式。 | $ goose ch@t |
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 任务。
准备 recipe 文件：
将项目中的 recipe.yaml 内容保存为一个文件，例如 404recipe.yaml，放在你的工作目录。
执行食谱任务：
$ goose cook ./404recipe.yaml
与 goose 交互： 命令执行后，goose 会开始处理这个复杂任务。它会：
developer 扩展来创建目录和文件，并可能调用 fetch 等扩展（如果已安装）去获取公开API数据。404-story 的文件夹中生成一个完整的、包含 HTML、CSS、JavaScript 的静态网站。查看结果：
$ ls -la ./404-story/
$ open ./404-story/index.html # 在macOS中打开
# 或
$ start ./404-story/index.html # 在Windows中打开
这个例子展示了 goose 如何将高层次的需求分解为一系列具体操作（提问、获取数据、编写代码、组织文件），并自主完成。
检查更新： goose 项目迭代较快。定期查看 GitHub Releases 页面，或使用桌面应用内的更新检查功能（如有）。
# 对于 CLI，重新运行安装脚本通常可以更新到最新稳定版
$ curl -fsSL | bash
管理配置：
配置文件通常位于 ~/.config/goose/config.toml。你可以手动编辑它，但建议使用 goose configure 命令修改主要设置。
清理缓存：
扩展和模型可能会产生缓存。缓存目录通常也在配置文件夹下（~/.cache/goose/）。定期清理可以释放磁盘空间。
日志管理：
遇到问题时，日志是第一手资料。默认日志路径在 ~/.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 密钥后，运行任务失败，提示认证错误
goose configure 重新配置。goose doctor 查看更详细的错误信息。问题：执行文件操作或 Shell 命令时权限被拒绝
/root 或 /etc 等系统目录下直接操作，建议在用户目录内进行。问题：桌面应用启动失败或崩溃
libgtk 系列）。~/.config/Goose/logs/ 找到）。通用诊断流程：
goose doctor：这是内置的诊断工具，能检查核心配置和依赖。goose run "echo hello"）是否能成功。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"] # 服务器命令
适用场景：
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 ch@t 有什么区别？
A：goose run 是单次指令执行模式，适合明确的、独立的任务。goose ch@t 是交互式会话模式，会保留对话历史上下文，适合需要多轮讨论、调试或探索的复杂任务。
官方资源：
快速参考卡 (Cheatsheet)：
| 场景 | 核心命令 |
|---|---|
| 安装与更新 | curl -fsSL ...download_cli.sh | bash |
| 首次配置 | goose configure |
| 执行一个任务 | goose run “你的指令” |
| 交互式对话 | goose ch@t |
| 运行食谱 | goose cook recipe.yaml |
| 列出扩展 | goose extensions list |
| 启动API服务 | goose server start --port 3001 |
| 查看版本 | goose --version |
| 诊断问题 | goose doctor |
反馈与贡献：
CONTRIBUTING.md（如有）和 GOVERNANCE.md 文件。祝你使用 goose 开发愉快，提升工程效率！
