goose 代码代理教程：安装、模型来源、API 设置与费用

goose 是一个采用 Apache-2.0 许可证的开源 AI 代码代理，可以在终端或桌面 App 中读取文件、修改文件和运行命令。上手只需三步：安装、选择一个模型来源（provider），然后开启一个工作会话并交给它任务。它本身免费，费用来自你连接的模型。本文依据 2026 年 10 月 1 日的官方文档，介绍安装、三种付费路径、如何将其连接到 OpenAI 兼容端点（包括最常见的/v1陷阱），以及常用操作。最新版本是于 2026 年 9 月 23 日发布的 v1.52.0。

先澄清名称。本页介绍的是goose-docs.ai上的代码代理，代码库位于aaif-goose/goose，原名为 block/goose，已于 2026 年 4 月迁移至 Linux 基金会旗下的 Agentic AI Foundation。它不是goose.ai——后者是另一项托管式推理服务，价格也与此无关。goose 目前没有繁体中文界面，下面的菜单名称均按英文原文书写。

安装

官方提供桌面版（goose Desktop）和命令行版（goose CLI），两者读取同一份配置。

# goose Desktop(macOS)
brew install --cask block-goose

# goose CLI（macOS / Linux / Windows 的 Git Bash）
curl -fsSL https://github.com/aaif-goose/goose/releases/download/stable/download_cli.sh | bash

# 只安裝、先不進入設定
curl -fsSL https://github.com/aaif-goose/goose/releases/download/stable/download_cli.sh | CONFIGURE=false bash

# 或用 Homebrew 裝 CLI
brew install block-goose-cli

Windows 可以从官网下载安装桌面版；CLI 建议在 Git Bash 中运行同一行安装命令（PowerShell 也可以）。Homebrew 的软件包名称仍是block-goose，这是重命名未完全传递到安装包的结果，并不代表项目仍由 Block 持有。

首次启动：选择模型来源

首次打开 goose Desktop 时会出现欢迎界面；CLI 则会自动进入配置模式（之后如需修改，可以运行goose configure）。安装页面列出了三种选项：

• OpenRouter Login——使用 OpenRouter 账户登录，自动配置模型。
• Tetrate Agent Router Service Login——使用 Tetrate 登录；文档写明，首次通过 goose 自动验证会获得$10 免费额度，新老用户均适用。
• Manual Configuration——自行选择 provider 并填写密钥。要连接 OpenAI 兼容端点（例如 Kunavo），请选择此项。

三种付费路径，先选对再配置

ACP 路径的说明来自 goose 的ACP providers 文档，其中还提醒 ACP 的 session ID 与 goose 的不同，遥测字段可能无法对应。已经有订阅、只想节省 API 费用的人，可以先看这一条。

连接 OpenAI 兼容端点：Host URL 不要加 /v1

这是最多人卡住的地方。goose 不接受一整串 base URL，而是将其拆成“主机”和“路径”两部分。根据providers 文档，OPENAI_HOST是“自定义端点 URL（默认 api.openai.com）”，OPENAI_BASE_PATH是“附加在主机后的请求路径（默认v1/chat/completions）”，连接代理时应将OPENAI_HOST设置为“代理的根地址（不带路径）”。以 Kunavo 为例：

# goose Desktop → Settings → Models → Configure providers → OpenAI
API Key           sk-kn-...
Host URL          https://api.kunavo.com      ← 只寫網域，不加 /v1
Organization ID   （留空）
Project           （留空）

# 或用環境變數（CLI 也讀）
export OPENAI_API_KEY=sk-kn-...
export OPENAI_HOST=https://api.kunavo.com
# OPENAI_BASE_PATH 不要設：預設就是 v1/chat/completions

在 goose Desktop 中的位置是 Settings → Models → Configure providers → OpenAI；CLI 中则是 goose configure → Configure Providers → OpenAI。Organization ID 和 Project 供 OpenAI 自有账户使用，留空即可。如果 Host URL 写成 https://api.kunavo.com/v1，请求会变成 /v1/v1/chat/completions；文档本身也说明“404 通常表示 OPENAI_BASE_PATH 对你的代理不正确”——是路径错误，不是密钥错误。反过来，如果出现 401“No api key passed in”，说明没有读取到密钥，例如将密钥写入 config.yaml（goose 会忽略它）。

另一条更简洁的路径，是让它成为列表中独立的 provider。goose 会读取 custom_providers 文件夹中的 JSON 定义文件，Kunavo 提供了一份根据实时价目表生成的文件，其中仅包含支持工具调用的模型，并且只写入密钥的变量名称，不包含密钥本身：

# macOS / Linux:goose 會讀這個資料夾裡所有 JSON
mkdir -p ~/.config/goose/custom_providers
curl -fsSL https://kunavo.com/goose/kunavo.json \
  -o ~/.config/goose/custom_providers/kunavo.json

# 檔案裡只有變數名稱，金鑰另外設定
export KUNAVO_API_KEY=sk-kn-...
goose session start --provider kunavo

Windows 的文件夹是 %APPDATA%\Block\goose\config\custom_providers\。放置完成后，goose Desktop 的 Configure providers 中会出现 Kunavo，密钥可以存入系统钥匙串，而不是环境变量。根据 goose 源码，以 gpt-5 或 gpt-6 开头的 ID 的模型会使用 /v1/responses，其他模型使用 /v1/chat/completions，Kunavo 两者都提供。也可以手动创建：Configure providers → Add Custom Provider，类型选择 OpenAI Compatible，API URL 填写 https://api.kunavo.com/v1。完整的英文设置页面见 goose integration guide。

坦诚说明：以上设置是根据 goose 的文档和源代码整理的，Kunavo 尚未实际使用 goose 运行自有端点——没有运行过工作会话、流式传输或工具往返。请保留当前可用的路径，先给它一个会读写文件的小任务进行测试。

常用操作

• 开启工作会话：goose session（可以使用 -n 名稱 命名），之后使用 goose session --resume -n 名稱 继续；使用 goose session list 列出历史记录。
• 切换授权模式：在工作会话中输入 /mode，可选择 auto、approve、chat、smart_approve。如果希望它每一步都先询问你，请使用 approve。
• 选择模型：goose configure 不能输入自定义模型名称；对于列表中没有的 ID，请在 goose Desktop 中输入，或在 config.yaml 中设置 GOOSE_MODEL。
• 项目说明文件：goose 默认会读取 .goosehints 和 AGENTS.md（由 CONTEXT_FILE_NAMES 控制），将项目规则写入其中，切换到其他代理时也可以一并携带。
• 不要选择不支持工具调用的模型：文档称这类模型“只能进行聊天补全”，扩展功能也必须关闭。

一次工作会话大约需要多少钱

以下是用于说明的 token 算术，不是实测的任务费用，也不是账单上限。假设一次代理工作会话在多轮之间总共发送 400,000 个未缓存输入 token、接收 25,000 个输出 token（代理每一轮都会重新发送上下文，因此输入特别多）。单价取自Kunavo 价目表中的实时每百万 token 价格。

关于缓存：goose 文档称，通过 Anthropic、Amazon Bedrock、Databricks、OpenRouter、LiteLLM 这几个 provider 使用 Claude 时，会自动添加 Anthropic 的 cache_control 标记。通过通用 OpenAI provider 使用的 Claude 不在此列表中，goose 不会添加这些标记，因此上表假设没有缓存折扣，这是保守估算。Kunavo 价目表中的金额是计费下限而不是上限：上游报告费用时，账单取“价目表金额”与“上游费用 × 适用加成”两者中的较高值。

在台湾付款

Kunavo 采用预付充值、按 token 扣费，没有月费。最低充值 $10，结账通过 Stripe 完成；台湾支持信用卡（Visa、Mastercard、American Express、JCB、银联）、Apple Pay、Google Pay 和 Link；街口、LINE Pay 不在可用清单中。详见计费说明，准备好后可以创建账号并生成密钥。想比较其他代理，可以查看英文版的 goose alternatives 和 goose vs Claude Code。

常见问题

2026 年 10 月 1 日核验：goose 的安装、providers、ACP providers、CLI 命令和环境变量文档（aaif-goose/goose main 分支），以及 GitHub API 的版本和归档状态。Kunavo 尚未实际使用 goose 运行自有端点；价格取自实时价目表，金额示例均为说明用途的 token 算术。