文档

文档

opencode

opencode 基于 Vercel AI SDK 构建其提供商,因此要将它指向新的端点,只需通过一个配置块指定 npm 包和 baseURL。指定的包决定它使用两种 wire 格式中的哪一种。

在 opencode.json 中添加一个提供商配置块 — 聊天补全使用 @ai-sdk/openai-compatible,需要 /v1/responses 接口时使用 @ai-sdk/openai。

opencode.json
{
  "$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 }
        }
      }
    }
  }
}
2026-10-10 用 opencode 1.18.35 实测:按上面的 provider 配置、使用 claude-sonnet-5,一个真实的编码任务从头到尾跑通。GPT 模型目前在 opencode 里还不可靠——opencode 每个请求都会带输出上限,而带上这个上限时,我们 GPT 模型背后的供应商有时会把模型的工具调用从回复里漏掉,导致这一轮结束时没有完成修改。在本提示移除之前,请在 opencode 里使用 Claude 模型。
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 是会进入仓库的文件;如果其中包含明文密钥,就无法保密。
opencode 的内置提供方以及它所知道的上下文上限都来自 models.dev(见其提供方文档,读取于 2026-10-22)。Kunavo 还没有收录在 models.dev 上:申请收录在 2026-10-22 仍未合并。所以要在 opencode.json 里自己写一个提供方块,下面的上限也需要你自己设置。
为每个模型分别设置 limit.context 和 limit.output。opencode 会根据这些数值跟踪剩余上下文,因此未设置这两项的模型会按一个并非其自身限制的默认值来计算预算。
还没有密钥?创建 Kunavo 账户,创建一个密钥(以 sk-kn- 开头),并充值 $10 起——调用费用从该余额中扣除,失败的调用不会收费。随后,控制台会打开 opencode 设置页面。

分步操作

  1. 在 /app/keys 创建密钥并复制——它只会显示一次。
  2. 导出它:export KUNAVO_API_KEY=sk-kn-...
  3. 将提供商配置块添加到 opencode.json——若要对所有项目生效,请使用位于 ~/.config/opencode/opencode.json 的全局配置;若只对当前仓库生效,则使用项目根目录中的配置。
  4. 启动 opencode,然后从模型列表中选择模型;提供商会显示在你为其指定的 name 名称下。
  5. 之后要添加模型时,在 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 的美元,格式为输入 / 输出。

模型 IDKunavo 输入 / 输出它在 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 系列,等上面的提示移除后再用
计费方式是从预付余额中按 token 扣费,无月费——参见 计费。对于重复上下文——这正是编辑器或聊天客户端发送内容的大部分——提示缓存对账单的影响大于模型选择。

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> },并填写提供商目录中的数值,这样上下文读数和压缩节点就会与实际情况一致。