Goose 自定义端点配置

最后更新:

兼容聊天使用明确的 host 与请求路径,运行前核对协议。

显式指定聊天路径与模型

设置 GOOSE_PROVIDER=openai、OPENAI_HOST=https://api.kkaiapi.com、OPENAI_BASE_PATH=v1/chat/completions 和 OPENAI_API_KEY,GOOSE_MODEL 填 claude-sonnet-5-5,再启动 goose session。新版还支持 OPENAI_BASE_URL,排查时避免多个端点变量相互覆盖。

最小覆盖配置
export GOOSE_PROVIDER=openai
export OPENAI_HOST=https://api.kkaiapi.com
export OPENAI_BASE_PATH=v1/chat/completions
export OPENAI_API_KEY=sk-你的kkaiapi密钥
export GOOSE_MODEL=claude-sonnet-5-5

goose session

先用只读工具检查一个项目文件

在临时项目中让 Goose 列出文件并解释一份 README,核对第一次模型请求的路径和工具返回。确认文本与工具都成功后再授权编辑任务。若请求转到 Responses,检查模型路由与端点参数;本页 Claude 示例使用 Chat Completions。

Goose 怎么和它的供应商对话

Goose 的 OpenAI provider 支持通过 OPENAI_HOST 与 OPENAI_BASE_PATH 配置请求,也支持新版 OPENAI_BASE_URL。示例显式选择聊天路径,以免模型名称与自动路由规则把请求转到不同协议。

环境变量、系统钥匙串与声明式供应商可能并存。先检查实际运行进程能读到的设置,再核对一次请求日志。编辑器或桌面应用是否继承终端环境取决于启动方式。

Goose → GOOSE_PROVIDER=openai + OPENAI_HOST 覆盖 → Claude Sonnet 5.5 / Claude Opus 5 / GPT-6.1 Sol / Kimi K2.7 Code / Qwen 3.7 Max
一个 host 覆盖,一个 Key;Agent 循环连同工具调用经一个端点走

声明式路径:一个自定义供应商文件

除了环境变量覆盖,当前 Goose 文档还描述了声明式的自定义供应商:一个放进 ~/.config/goose/custom_providers/ 目录(Windows 上是对应平台的配置目录)的 JSON 文件,把网关注册成一个和内置供应商并列的、带名字的供应商。文件里声明引擎(chat-completions 端点用 openai)、哪个环境变量存 Key、端点 URL,以及这个供应商提供的模型。

这里的 URL 约定要留意,因为它又反过来了:和 OPENAI_HOST 不一样,自定义供应商的 base_url 是完整的请求 URL,包含路径,https://api.kkaiapi.com/v1/chat/completions。每个 models 条目都带一个 context_limit,让 Goose 知道能打包多大的窗口。

想让网关在 Goose 的供应商列表里以自己的名字出现、有自己的 Key 变量,而不是占用 openai 这个槽位时,声明式文件更合适。环境变量覆盖更适合 CI 和快速切换。两条路最终都到同一个端点;选一个,别叠加着用。

示例中的 32000 为本地测试预算,实际请求仍须满足该模型的上下文与输出限制。

~/.config/goose/custom_providers/kkaiapi.json
{
  "name": "kkaiapi",
  "display_name": "kkaiapi",
  "engine": "openai",
  "api_key_env": "KKAIAPI_KEY",
  "base_url": "https://api.kkaiapi.com/v1/chat/completions",
  "models": [
    { "name": "claude-sonnet-5-5", "context_limit": 32000 },
    { "name": "claude-opus-5",   "context_limit": 32000 },
    { "name": "kimi-k2.7-code",    "context_limit": 32000 }
  ],
  "supports_streaming": true,
  "requires_auth": true
}
声明式供应商对应的 Key
export KKAIAPI_KEY=sk-你的kkaiapi密钥
goose configure   # 供应商列表里会出现 kkaiapi

给自主 Agent 选模型

实际的工作方式是固定住任务集,让 GOOSE_MODEL 在两三个候选之间轮换,每个跑几轮会话。因为每个候选都经同一个 Key,按 Key 的用量视图会不用你自己记账就给每次实验定价。

  • Goose 会跑一段一段无人值守的过程:规划、改文件、跑命令、读输出、循环。工具调用的可靠性比文笔更重要,这也是 claude-sonnet-5-5 和 claude-opus-5 成为主循环默认选择的原因
  • 像 kimi-k2.7-code 这类编程调优过的 ID 值得在重构密集的会话里测一下;经一个网关,这个测试就是改一个 GOOSE_MODEL 变量,不是迁移供应商
  • 长会话会累积上下文。一个通过 context_limit 如实声明真实 20 万窗口的模型,能让 Goose 在需要摘要之前带更多会话历史
  • 脚本或 CI 场景下,一个中端 ID(gpt-6.1-sol、qwen3.8-max)对边界清晰的任务经常够用,成本只是旗舰模型的一小部分;先在自己的任务上测,再决定要不要默认用更贵的

主力模型价格

价格按 kkaiapi 中文区实时价格计算,输入/输出费用与计价数量见各行。

报价更新于 2026-10-27,来源:https://api.kkaiapi.com/api/pricing。展示数量为报价单位,按实际用量计费。 官方参考标记 ≈ 的金额为约数,原始参考价可在公开报价中核对。 GPT-6.1 Sol:官方对比价适用于输入不超过 272K tokens 的标准档。 Qwen 3.8 Max:官方对比价采用北京地域参考;隐式缓存与显式消息块缓存的读取单独定价;缓存写入单独计价。
模型模型 ID输入(CNY)输出(CNY)官方参考价(约数标记 ≈)
Claude Sonnet 5.5claude-sonnet-5-5¥2 / 1M tokens¥10 / 1M tokensCNY 输入 ¥14 / 输出 ¥70 / 1M tokens;USD 输入 $2 / 输出 $10 / 1M tokens
Claude Opus 5claude-opus-5¥5 / 1M tokens¥25 / 1M tokensCNY 输入 ¥35 / 输出 ¥175 / 1M tokens;USD 输入 $5 / 输出 $25 / 1M tokens
GPT-6.1 Solgpt-6.1-sol¥2 / 1M tokens¥10 / 1M tokensCNY 输入 ¥14 / 输出 ¥70 / 1M tokens;USD 输入 $2 / 输出 $10 / 1M tokens
Kimi K2.7 Codekimi-k2.7-code¥5.5 / 1M tokens¥24 / 1M tokensCNY 输入 ¥6.5 / 输出 ¥27 / 1M tokens;USD 输入 ≈$0.9 / 输出 $4 / 1M tokens
Qwen 3.8 Maxqwen3.8-max¥10.5 / 1M tokens¥32 / 1M tokensCNY 输入 ¥12 / 输出 ¥36 / 1M tokens;USD 输入 ≈$1.6 / 输出 ≈$5 / 1M tokens

Goose 专属的翻车点

在 OPENAI_HOST 后面加了 /v1。这个变量接受裸 host,路径活在已经默认是 v1/chat/completions 的 OPENAI_BASE_PATH 里。把 https://api.kkaiapi.com/v1 填成 host,会产生 /v1/v1/... 这样的请求和 404。这是最常见的一个错误,恰恰因为这一类工具里其它每一个都要求带 /v1 后缀。

自定义供应商文件里的完整 URL 约定。声明式的 base_url 是完整请求 URL,包含 /v1/chat/completions,和 OPENAI_HOST 正好相反的约定。把一个裸 host 拷进自定义供应商文件,和把一个完整 URL 拷进 OPENAI_HOST 一样会坏得很彻底。

config.yaml 里的 Key 不参与鉴权。Goose 从钥匙串或环境变量读密钥,放在 config.yaml 里的 Key 值会被忽略。如果改完文件之后 401 依然存在,原因就在这;导出这个变量,或者重新跑 goose configure 在提示时输入 Key。

桌面会话看不到 shell 导出的变量。桌面应用不会继承终端配置里的任何东西。通过桌面设置界面配置供应商,或者从已经设好变量的 shell 启动。

配置来源叠加。一个旧的 OPENAI_HOST 导出可能覆盖掉刚在 config.yaml 里设的值,因为环境变量优先于文件。路由看起来不对时,在启动 Goose 的同一个 shell 里打印相关变量,再去怪任何一层。

谁会把 Goose 接到一个网关上

  • 把 Goose 当日常主力用的工程师,想让 Claude、GPT、Kimi、Qwen 都在一个 Key 背后,而不是每家厂商各一套凭证
  • 把 Goose 放进 CI 或定时任务的团队。纯环境变量路径意味着运行器只需要两个路由变量和一个密钥,注入和轮换都容易
  • 在真实任务上对比 Agent 模型的开发者,每个候选是对着同一个端点改一次 GOOSE_MODEL,按 Key 的用量自动定价
  • 想让 Agent 花费按 Key 和按模型可见、不用去对几个厂商仪表盘的平台团队
  • 手头没有某家厂商官方支付渠道的开发者,充值后按量调用不需要海外卡

验证接入与排查首次会话

开一个会话之前先确认网关提供了 GOOSE_MODEL 里的那个 ID;/v1/models 的列表是权威拼写,版本后缀也算。

第一次会话的失败是有规律的。404 说明 host 和路径拼出了问题,几乎总是 OPENAI_HOST 里带了 /v1。401 说明 Key 不在 Goose 会去找的地方:没有在启动它的 shell 里导出、不在钥匙串里、或者只是没用地躺在 config.yaml 里。网关返回模型不存在,是 GOOSE_MODEL 里的 ID 拼错了。如果会话能起来但工具调用表现异常,先确认用的是真正支持工具调用的模型;上面表里的 ID 都支持。

循环跑起来之后,kkaiapi 控制台会显示每次请求的模型、token 数和花费。自主 Agent 是这一点最要紧的场景:会话长、工具调用轮次多,用量视图是唯一能看清一下午的 Goose 到底花了多少的地方。

确认接口可用
curl -s https://api.kkaiapi.com/v1/models \
  -H "Authorization: Bearer $OPENAI_API_KEY" | head -50

配置依据与版本核对

本文于 2026 年 10 月 18 日核对项目官方配置说明。界面名称随版本变化时,以已安装版本的字段和请求日志为准。KK 模型 ID、价格及开放接口以模型与价格为准;本页示例采用 Chat Completions 文本调用,工具、图片和结构化输出需要分别验证。

常见问题

Goose 能通过 openai 供应商跑 Claude 或 Kimi 模型吗?

支持聊天接口的文本模型可通过 openai provider 测试。工具循环还需要该模型接口支持工具请求与响应,先做一次只读工具往返,不能仅凭模型 ID 可填写就推断全部能力正常。

OPENAI_HOST 需要带 /v1 后缀吗?

本例 OPENAI_HOST 使用 API 根域名,OPENAI_BASE_PATH 显式设为 v1/chat/completions。新版也支持 OPENAI_BASE_URL,若设置多种覆盖变量,先检查它们的优先级与实际 URL。

环境变量覆盖和自定义供应商文件有什么区别?

环境变量覆盖直接改写内置的 openai 供应商:设置最快,适合 CI。~/.config/goose/custom_providers/ 里的自定义供应商 JSON 会把网关注册成一个带自己的 Key 变量和模型列表的独立供应商。两者最终都到同一个端点;选一个用。

为什么 Goose 会忽略我填进 config.yaml 的 API Key?

这是设计如此。Goose 从系统钥匙串或环境变量读密钥,忽略 config.yaml 里的 Key。导出 OPENAI_API_KEY(或者你声明的 api_key_env 变量),或者通过 goose configure 或桌面设置界面输入 Key,让它落进钥匙串。

CLI 和桌面应用共用这份配置吗?

共用 config.yaml 和钥匙串,但不共用 shell 环境:终端里导出的变量只对从那个终端启动的 CLI 会话生效,不会传到桌面应用。通过桌面应用自己的设置界面配置,或者依赖共享的配置文件加钥匙串。

Agent 任务该给 GOOSE_MODEL 填哪个模型?

主循环先从 claude-sonnet-5-5 开始;它在多步工具调用上表现稳。重构密集的会话可以测 kimi-k2.7-code,边界清晰的 CI 任务测一个中端 ID。经一个端点,每次测试都只是改一个变量。