OpenCode 中文教程

Appearance

第三方中转（Claude Code 兼容） ​

这一页只做一件事：把“宣称兼容 Claude Code”的第三方中转，接到 OpenCode 里。

学完你能做什么 ​

你将完成 3 件事：

  1. 配一个独立 provider（例如 claudecode-relay），把 baseURL 指到中转的 .../v1
  2. 配置 API Key（二选一：写在 opencode.json 或存到 auth.json）
  3. 在 /models 里选择模型并发一句话验证

🎒 开始前的准备 ​

  • [ ] 完成了 1.2 安装，能运行 opencode
  • [ ] 你已经从中转服务拿到了 baseURL 和 API Key

从中转服务拿到两样东西：

  1. baseURL：中转给你的接口地址
  2. API Key：通常形如 k-...

baseURL 的填写规则（常见两种给法）：

  1. 对方给到 /v1 就原样填：例如 https://url.com/v1
  2. 只给域名就补 /v1：例如 https://url.com → https://url.com/v1

提示：很多 Claude/Anthropic 兼容中转的消息接口路径会包含 .../v1/messages，可用于你排查 baseURL 是否少了 /v1。

跟我做 ​

第 1 步：在 opencode.json 配置一个独立 provider ​

编辑 ~/.config/opencode/opencode.json，添加一个自定义 provider（这里用 claudecode-relay 作为 provider ID）：

jsonc
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "claudecode-relay": {
      "npm": "@ai-sdk/anthropic",
      "options": {
        "baseURL": "https://url.com/v1"
      },
      "models": {
        "claude-opus-4-5-20251101": {
          "name": "zhongzhuang",
          "limit": {
            "context": 200000,
            "output": 64000
          },
          "options": {
            "thinking": {
              "type": "enabled",
              "budgetTokens": 16000
            }
          }
        }
      }
    }
  }
}

说明：

  • npm 用来告诉 OpenCode：这个 provider 要按哪种"协议/SDK 驱动"发请求。Claude/Anthropic 兼容中转一般要用 @ai-sdk/anthropic；如果你删掉这行，OpenCode 可能会按默认的 OpenAI-compatible 方式去理解这个 provider，从而请求失败。
  • 你也可以直接改 provider.anthropic 来走中转；那种写法本质上同样是在走 Anthropic 这套协议，但不建议（原因见文末"补充说明"）。
  • claude-opus-4-5-20251101 会作为你在 OpenCode 里看到的"模型 ID"，在 /models 里显示成 claudecode-relay/claude-opus-4-5-20251101
  • models.<id>.name 需要替换成中转商要求的模型名（本章用 zhongzhuang 作为教学占位）
  • limit.context 和 limit.output 定义模型的上下文窗口和最大输出长度。如果不配置，默认值为 0，会导致自动压缩功能失效。推荐值见下表。
模型contextoutput
claude-opus-4-520000064000
claude-sonnet-4-520000064000

💡 想深入了解上下文压缩机制和 limit 参数的作用？请参阅 5.20 上下文压缩。

第 2 步：配置 API Key（二选一） ​

你只需要选下面一种方式配置 Key：

方案 1：把 Key 写在 opencode.json（更简单） ​

在上面的 provider.claudecode-relay.options 里添加 apiKey，并推荐用 {env:...}：

jsonc
{
  "provider": {
    "claudecode-relay": {
      "options": {
        "baseURL": "https://url.com/v1",
        "apiKey": "{env:CLAUDECODE_RELAY_API_KEY}"
      }
    }
  }
}

方案 2：把 Key 存到 OpenCode 认证（auth.json） ​

运行：

bash
opencode auth login

在交互界面里：

  1. 选择 Other
  2. 输入 provider ID：claudecode-relay
  3. 粘贴你的 API Key

它会把 Key 写入 OpenCode 的认证文件 auth.json。你可以用下面命令查看“实际写到了哪个路径”（命令输出里会显示路径）：

bash
opencode auth list

重要：不要两边都写

为了避免你“以为换了 Key 但没生效”，建议只保留一种方式。

  • 如果你选择了方案 1（opencode.json 里有 options.apiKey），就不要再做 auth login。
  • 如果你选择了方案 2（存到 auth.json），就不要在 opencode.json 里再写 options.apiKey。

原因：当 opencode.json 里存在 options.apiKey 时，会优先使用它。

第 3 步：选择模型并验证 ​

启动 OpenCode：

bash
opencode

输入：

text
/models

选择 claudecode-relay/claude-opus-4-5-20251101，然后发送一句话验证：

text
你好，请简单介绍一下你自己

检查点 ✅ ​

  • [ ] /models 里能看到 claudecode-relay/... 并成功选择
  • [ ] 发送消息能收到 AI 回复

踩坑提醒 ​

现象原因解决
404 / Not FoundbaseURL 写错了优先检查 baseURL 是否应该是 .../v1，并确认它能拼出 .../v1/messages
401 / UnauthorizedKey 无效/没权限重新生成 Key，或检查套餐/权限
选了模型就报错模型名不支持调整 models.<id>.name 为中转商支持的模型名

补充说明：为什么不建议直接改 provider.anthropic ​

你当然可以把中转写到 provider.anthropic，但不建议这么做：

  • 会把你原本的 anthropic 配置也一起“换成中转”（不利于后续切回官方或对比排查）
  • 更容易在 opencode auth login 时把 Key 存到错误的 providerID（例如误存成 anthropic），排查会变复杂

用一个独立 providerID（例如本章的 claudecode-relay）能把“中转配置”与“官方 anthropic 配置”隔离开。

下一步 ​

遇到问题？

中转配置卡住了？加入社群，和 500+ 同路人一起交流，实时答疑。