文档

goose

goose 将端点拆成两部分：Host URL 和由它自行追加的请求路径。填写不带路径的源站地址，并保留默认路径，这样内置的 OpenAI provider 就能通过一个密钥调用 Claude 和 GPT。

Settings → Models → Configure providers → OpenAI：Host URL 填写裸源地址，因为 goose 会自行追加请求路径（v1/chat/completions）。

Configure providers → OpenAI，或环境

# goose Desktop → Settings → Models → Configure providers → OpenAI
API Key           sk-kn-...
Host URL          https://api.kunavo.com
Organization ID   (leave blank)
Project           (leave blank)

# …or as environment variables, which goose CLI reads too:
OPENAI_API_KEY=sk-kn-...
OPENAI_HOST=https://api.kunavo.com

# OPENAI_BASE_PATH is left unset on purpose. Its default is
# v1/chat/completions, which is the path Kunavo serves — that default is
# exactly why Host URL above carries no /v1.

Host URL 不要带 /v1。 goose 将 OPENAI_BASE_PATH 定义为“追加到主机的请求路径（默认为 v1/chat/completions）”，并建议代理用户将 OPENAI_HOST 设置为“代理的根地址（末尾不带路径）”。这两点说明了表单的填写方式：字段中填写源站地址，默认路径会作为 /v1 添加。填写 https://api.kunavo.com/v1 会请求 /v1/v1/chat/completions；同一页面还说明，404 表示路径有误，而非密钥有误。

以下配置依据 goose 自己的文档整理，日期见下方。Kunavo 尚未让 goose 调用过其端点——无论是会话、流式对话，还是工具往返调用，都没有测试过。发布配置页面不等于完成测试，本文内容不应被视为测试结果；下面的 curl 是你可以在十秒内核验的部分，客户端的行为则取决于你与 goose。

Kunavo 不提供嵌入、文本转语音或语音转文本模型，因此该端点只响应聊天补全请求。goose 设置中任何用于转录音频或构建向量索引的功能，仍会使用原有的 provider 密钥——将 OpenAI provider 指向这里不会改变这些调用。

还没有密钥？创建 Kunavo 账户，创建一个密钥（以 sk-kn- 开头），并充值 $10 起——调用费用从该余额中扣除，失败的调用不会收费。随后，控制台会打开 goose 设置页面。

分步操作

在 /app/keys 创建密钥并复制——它只会显示一次。
在 goose Desktop 中：侧边栏 → Settings → Models → Configure providers → OpenAI。在 CLI 中：goose configure → Configure Providers → OpenAI。
填写 API Key 和 Host URL。将 Organization ID 和 Project 留空——goose 文档说明，这两项用于在 OpenAI 自有账户中跟踪用量和管理资源，而 Kunavo 没有可填写在此处的对应项目。点击 Submit。
选择模型。goose 的说明明确指出，goose configure“不支持输入自定义模型名称”——因此，如果返回的列表中没有所需 ID，请在 goose Desktop 中输入，或在 config.yaml 中设置 GOOSE_MODEL；该设置会覆盖此进程所使用的文件配置。
启动一个会话，并给它一个会操作文件的任务。goose 几乎所有操作都依赖工具调用——其服务商页面特别提醒，不支持工具调用的模型“只能完成聊天”，且使用这类模型时必须禁用扩展——因此，首次运行时让它读取并编辑某些内容，比打招呼更能说明问题。

已于 2026年9月29日对照 goose 的 Configure LLM Provider 页面检查。第三方设置会发生变化；如果这里的字段名称不再与你看到的内容一致，应以该页面为准，而不是本页。

调试客户端前先验证

一个请求即可确定故障来自端点、密钥还是配置文件。如果返回 JSON，则相同的基础 URL 和密钥可以在 goose 中使用。

# Settles whether a failure is the endpoint, the key, or the client.
curl -sS https://api.kunavo.com/v1/models \
  -H "Authorization: Bearer sk-kn-..."

字段中应填写哪个模型 ID

每个文本模型都可通过模型 ID 访问——实时列表见 GET /v1/models，包含价格的目录见模型页面。费率单位为每 1M token 的美元，格式为输入 / 输出。

模型 ID	Kunavo 输入 / 输出	它在 goose 中的位置
`claude-sonnet-5`	$1.40 / $7.00	作为文件编辑会话默认工作模型
`claude-opus-5`	$3.50 / $17.50	规划一个出错代价高昂的变更
`claude-haiku-4-5`	$0.70 / $3.50	低成本调用——分诊、摘要，以及全天运行的循环
`gpt-5-6-sol`	$2.00 / $12.00	来自另一个系列的第二意见，使用相同密钥和相同 Host URL

计费方式是从预付余额中按 token 扣费，无月费——参见计费。对于重复上下文——这正是编辑器或聊天客户端发送内容的大部分——提示缓存对账单的影响大于模型选择。

另一种方式：Kunavo 的 provider 文件

goose 也会从其 custom_providers 目录中的 JSON 文件加载 provider 定义。通过这种方式添加的 provider 会在选择器中拥有独立条目、独立密钥和已保存的模型列表，无需占用名为 OpenAI 的位置。Kunavo 在 kunavo.com/goose/kunavo.json 发布了一个 provider 文件。该文件根据实时目录生成，因此模型列表反映 Kunavo 当前提供的模型；文件中包含密钥变量的名称，但绝不包含密钥本身：

terminal

# macOS / Linux — goose reads every JSON file in this directory
mkdir -p ~/.config/goose/custom_providers
curl -fsSL https://kunavo.com/goose/kunavo.json \
  -o ~/.config/goose/custom_providers/kunavo.json

# The file names the variable; the key itself never goes in the file
export KUNAVO_API_KEY=sk-kn-...
goose session start --provider kunavo

Windows 上的目录为 %APPDATA%\Block\goose\config\custom_providers\。随后，goose Desktop 会在 Configure providers 下显示 Kunavo，你可以将密钥存入密钥链，而非环境变量。

端点。该文件将 base_url 设为 https://api.kunavo.com/v1。goose 文档没有说明该字段应填写 /v1 基础路径，还是示例中的完整 /v1/chat/completions；其源码给出了答案——derive_base_path 会将两者都转换为相同的 v1/chat/completions 路径。
GPT ID 使用 Responses API。goose 会将以 gpt-5 或 gpt-6 开头的模型 ID 发送到 /v1/responses，其他 ID 则发送到 /v1/chat/completions。Kunavo 同时提供这两种 API，因此文件中的 Claude 和 GPT ID 可使用同一个密钥。
列表中仅包含支持工具调用的模型。goose 几乎每轮都会调用工具，因此文件中不包含图像、视频和音频模型，尽管同一个密钥可以调用这些模型。

本页面的其他内容同样适用：这些信息来自 goose 文档和源码，并未实际运行验证。想要手动编写 provider？Configure providers → Add Custom Provider 会要求填写相同信息——类型 OpenAI Compatible、API URL https://api.kunavo.com/v1、你的 sk-kn- 密钥，以及以逗号分隔的模型列表。

常见问题

如何让 goose 使用自定义的 OpenAI 兼容 API？

使用内置 OpenAI provider，并为其指定主机。在 goose Desktop 中，路径为 Settings → Models → Configure providers → OpenAI，字段包括 API Key、Host URL、Organization ID 和 Project；在 CLI 中，运行 `goose configure` → Configure Providers → OpenAI，按提示输入相同信息。环境变量形式为 OPENAI_API_KEY 和 OPENAI_HOST。如果需要同时使用多个端点，goose 的 Add Custom Provider 流程会为每个端点在 provider 列表中创建独立条目。

goose 的 Host URL 末尾需要加 /v1 吗？

不需要，加上会导致请求失败。goose 将 OPENAI_BASE_PATH 说明为追加到主机后的请求路径，默认为 v1/chat/completions；同时告知代理用户将 OPENAI_HOST 设为代理根地址，不带尾随路径。因此，该字段应填写不带路径的源站地址——https://api.kunavo.com；默认路径会补上 /v1。若主机地址以 /v1 结尾，请求就会变成 /v1/v1/chat/completions，结果是 404，而不是身份验证错误。

设置自定义主机后，为什么 goose 返回 404？

goose 自己的说明是，404 通常表示基础路径与端点不匹配：大多数代理提供 v1/chat/completions，有些提供不带 v1 的 chat/completions，所设置的值必须与之匹配。Kunavo 提供 v1/chat/completions，这是 goose 的默认路径，因此，访问 Kunavo 时出现 404，最常见的原因是主机地址中也输入了 /v1，导致路径重复。若 401 提示未传入 API 密钥，则是另一种问题——goose 文档说明，放在 config.yaml 中的密钥会被忽略。

goose 能否通过 OpenAI 兼容端点使用 Claude 模型？

可以。provider 类型表示网络协议，而非厂商：goose 会向你配置的主机发送符合 OpenAI 格式的聊天补全请求，并直接传递模型 ID，因此 Claude ID 会由该端点解析，而不是由 goose 解析。需要注意的是，goose 大量使用工具调用；其 provider 页面说明，不支持工具调用的模型只能进行聊天补全，且必须禁用扩展——因此请选择支持工具的 ID。

Kunavo 测试过此配置吗？

没有。我们核对的是 goose 自己的文档（2026 年 9 月 21 日和 29 日）——字段名称、顺序以及主机与路径的规则均引自这些文档；对于 provider 文件，我们还核对了 goose 的 provider 源码（9 月 29 日）。Kunavo 尚未让 goose 会话调用过其端点，也未对该客户端中的流式传输、工具往返调用或扩展行为作出任何声明。唯一可以单独确认的是端点和密钥是否正常工作，本页面中的 curl 命令即可完成检查。

goose 有现成的 Kunavo provider 文件吗？

有：https://kunavo.com/goose/kunavo.json。将其保存到 goose 的 custom_providers 目录（macOS 和 Linux 上为 ~/.config/goose/custom_providers/，Windows 上为 %APPDATA%\Block\goose\config\custom_providers\），设置 KUNAVO_API_KEY 后，Kunavo 就会出现在 provider 列表中，且模型 ID 已预先填好。该文件根据实时目录生成，因此只列出 Kunavo 当前提供的模型，并且不包含密钥。