文档
opencode
opencode 基于 Vercel AI SDK 构建其提供商,因此要将它指向新的端点,只需通过一个配置块指定 npm 包和 baseURL。指定的包决定它使用两种 wire 格式中的哪一种。
在 opencode.json 中添加一个提供商配置块 — 聊天补全使用 @ai-sdk/openai-compatible,需要 /v1/responses 接口时使用 @ai-sdk/openai。
{
"$schema": "https://opencode.ai/config.json",
"small_model": "kunavo/claude-haiku-4-5",
"provider": {
"kunavo": {
"npm": "@ai-sdk/openai-compatible",
"name": "Kunavo",
"options": {
"baseURL": "https://api.kunavo.com/v1",
"apiKey": "{env:KUNAVO_API_KEY}"
},
"models": {
"claude-sonnet-5": {
"name": "Claude Sonnet 5",
"limit": { "context": 200000, "output": 64000 }
},
"claude-haiku-4-5": {
"name": "Claude Haiku 4.5",
"limit": { "context": 200000, "output": 64000 }
}
}
}
}
}npm 字段决定传输格式。@ai-sdk/openai-compatible 使用 /v1/chat/completions;@ai-sdk/openai 使用 /v1/responses。所有模型都用 chat-completions 包,GPT 也不例外。在 2026-10-10 用 opencode 1.18.35 的一次运行中,通过 Responses 包调用 gpt-5-6-sol 返回的都是空回合——没有文本,也没有工具调用——所以目前不要走这个包。"apiKey": "{env:KUNAVO_API_KEY}" 会在加载配置时从环境变量读取密钥。opencode.json 是会进入仓库的文件;如果其中包含明文密钥,就无法保密。limit.context 和 limit.output。opencode 会根据这些数值跟踪剩余上下文,因此未设置这两项的模型会按一个并非其自身限制的默认值来计算预算。sk-kn- 开头),并充值 $10 起——调用费用从该余额中扣除,失败的调用不会收费。随后,控制台会打开 opencode 设置页面。分步操作
- 在
/app/keys创建密钥并复制——它只会显示一次。 - 导出它:
export KUNAVO_API_KEY=sk-kn-... - 将提供商配置块添加到
opencode.json——若要对所有项目生效,请使用位于~/.config/opencode/opencode.json的全局配置;若只对当前仓库生效,则使用项目根目录中的配置。 - 启动
opencode,然后从模型列表中选择模型;提供商会显示在你为其指定的name名称下。 - 之后要添加模型时,在
models下再添加一个键——ID 是在线路上传输的值,name只是显示标签。
已于 2026年9月6日对照 opencode 的提供商文档检查。第三方设置会发生变化;如果这里的字段名称不再与你看到的内容一致,应以该页面为准,而不是本页。
调试客户端前先验证
一个请求即可确定故障来自端点、密钥还是配置文件。如果返回 JSON,则相同的基础 URL 和密钥可以在 opencode 中使用。
# 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 输入 / 输出 | 它在 opencode 中的位置 |
|---|---|---|
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 | 同一个 @ai-sdk/openai-compatible 块下的 GPT 系列,等上面的提示移除后再用 |
2026年10月10日实测。OpenCode 1.18.35 在 claude-sonnet-5 上运行了一个小型仓库任务(让一个含六个测试的单元测试集全部通过,开始时其中五个失败):5 次模型调用,53,077 个输入 token(其中 26,999 个读自缓存,24,212 个写入缓存),3,976 个输出 token,按 Kunavo 的费率合计 $0.0766。同一任务在其他客户端上的数据见 LLM 成本计算器。
常见问题
如何为 opencode 添加自定义提供商?
在 opencode.json 的 "provider" 下添加配置块,指定 npm 包、显示名称、options.baseURL、options.apiKey 和 models 映射。对于提供 /v1/chat/completions 的端点,使用 @ai-sdk/openai-compatible;对于提供 /v1/responses 的端点,使用 @ai-sdk/openai。之后,该提供商会以你指定的名称显示在 opencode 的模型列表中。
如何避免将 API 密钥写入 opencode.json?
在 options.apiKey 中使用 {env:VAR_NAME} 插值语法,例如 "apiKey": "{env:KUNAVO_API_KEY}",并在 shell 中导出该变量。opencode 会在加载配置时解析它,因此可以安全地将配置文件与其所配置的项目一同提交。
opencode 中的 @ai-sdk/openai 和 @ai-sdk/openai-compatible 有什么区别?
它们会在同一个 base URL 上选择不同的端点。@ai-sdk/openai-compatible 调用 /chat/completions,几乎所有网关都实现了该端点;@ai-sdk/openai 调用更新的 OpenAI 接口 /responses。请选择端点实际提供的那个包——如果包选错了,即使 base URL 正确,请求也会返回 404。
为什么 opencode 比预期更早耗尽上下文?
因为模型条目没有 limit 块,所以 opencode 按默认值而非模型的实际上下文窗口计算预算。在 opencode.json 的该模型条目中添加 "limit": { "context": <window>, "output": <max output> },并填写提供商目录中的数值,这样上下文读数和压缩节点就会与实际情况一致。