Claude Code 中转接入 OpenCode 实战教程：配置与验证

📚 分类: AI编程助手配置 ⏱️ 预计耗时: 5 分钟 🎯 难度: 入门 🔧 环境要求: 已安装并成功运行过 OpenCode CLI 工具

你将学到什么

完成本教程后，你将能够：

[ ] 配置一个独立的第三方 Claude Code 中转服务提供商
[ ] 在 OpenCode 中成功连接并使用该中转服务
[ ] 排查并解决常见的连接和认证错误

最终效果

你将能够在 OpenCode 的 /models 命令列表中，看到并选择一个名为 claudecode-relay 的提供商下的模型。发送一条消息后，AI 能够正常回复，表明中转服务已成功接入。

前置准备

在开始前，请确认你的环境满足以下条件：

检查项	要求	验证方法
OpenCode	已安装并可正常启动	在终端输入 `opencode`，应能正常进入交互界面
中转服务信息	已获取有效的 `baseURL` 和 `API Key`	联系你的中转服务提供商获取

💡 提示：如果你还没有安装 OpenCode，请先参考官方文档完成安装。

第 1 步：配置第三方提供商

🎯 目标：在 OpenCode 的配置文件中，添加一个名为 claudecode-relay 的自定义提供商，并填入你的中转服务信息。

📝 操作：

找到并编辑 OpenCode 的配置文件。通常位于 ~/.config/opencode/opencode.json。

bash

# 使用文本编辑器打开配置文件，例如 Vim 或 VS Code
$ vim ~/.config/opencode/opencode.json

在配置文件中，找到 "provider" 字段，并添加一个新的条目 "claudecode-relay"。请确保 JSON 格式正确，注意逗号的使用。完整配置示例如下：

jsonc

{
  "$schema": "https://opencode.ai/config.json", // 配置文件格式规范
  "provider": {
    // 其他已存在的提供商配置...
    // 新增：Claude Code 中转服务提供商
    "claudecode-relay": {
      "npm": "@ai-sdk/anthropic", 
      "options": { 
        "baseURL": "https://url.com/v1", // [!code ++] // 替换为你的中转服务地址
        "apiKey": "你的API Key" // [!code ++] // 替换为你的 API Key
      }, 
      "models": { 
        "claude-opus-4-5-20251101": { // [!code ++] // 替换为你想使用的模型ID
          "name": "中转站的 opus 4.5", // [!code ++] // 给模型起一个易识别的名称
          "limit": { 
            "context": 200000, // [!code ++] // 上下文长度限制
            "output": 64000 // [!code ++] // 输出长度限制
          } 
        } 
      } 
    } 
  }
}

🤔 为什么要这样做？ OpenCode 通过 provider 字段管理不同的 AI 模型来源。"claudecode-relay" 是你自定义的提供商名称，"npm" 指定了通信协议，"options" 包含连接信息，"models" 则定义了该提供商下可用的模型及其参数。

✅ 验证：保存并关闭配置文件后，文件不应有任何JSON格式错误。你可以使用在线 JSON 校验工具检查，或直接进行下一步验证。

⚠️ 常见错误：

JSON 格式错误：最常见的错误是漏掉逗号或多加了逗号。例如，在 "apiKey": "你的API Key" 后面忘记加 ,。
- ❌ 错误示例：
  json
```
"apiKey": "你的API Key"
"models": { // 这里会报错，因为上一行缺少逗号
```
- ✅ 正确示例：
  json
```
"apiKey": "你的API Key",
"models": {
```

第 2 步：选择模型并验证连接

🎯 目标：启动 OpenCode，通过 /models 命令选择刚刚配置好的模型，并发送一条消息，确认整个链路通畅。

📝 操作：

在终端中启动 OpenCode：
bash
```
$ opencode
```
在 OpenCode 的交互界面中，输入以下命令来查看并选择模型：
bash
```
/models
```
你应该会在列表中看到一个名为 claudecode-relay 的提供商。选择它下面的模型，例如 claudecode-relay/claude-opus-4-5-20251101。
发送一句话进行测试，例如：
text
```
你好，请回复“连接成功”。
```

✅ 验证：

检查点 1：在 /models 列表中能看到 claudecode-relay/... 的选项，并可以成功选中。
检查点 2：发送消息后，能正常收到 AI 的回复。如果看到回复“连接成功”，则说明一切配置正确。

⚠️ 常见错误与排错：

现象	原因	解决方法
404 / Not Found	`baseURL` 写错了。中转服务的地址通常以 `/v1` 结尾，但你可能写成了其他路径。	优先检查 `baseURL`。确保它与你从服务商获取的地址完全一致，特别是结尾是否为 `/v1`。
401 / Unauthorized	`API Key` 无效、已过期或没有访问该模型的权限。	重新检查并确认你的 `API Key` 是否正确。如果确认无误，请联系你的中转服务提供商重新生成或购买新的 Key。

总结

恭喜你完成了本教程！🎉

回顾一下我们今天学到的核心内容：

配置第三方提供商：通过在 opencode.json 文件中添加 provider 条目，你可以将任何兼容的第三方服务（如 Claude Code 中转）接入 OpenCode。
选择与验证模型：使用 /models 命令可以浏览并选择你配置好的模型，发送一条消息即可快速验证连接是否成功。
常见错误排查：掌握了针对 404（地址错误）和 401（密钥错误）等常见问题的排查方法。

Claude Code 中转接入 OpenCode 实战教程：配置与验证 ​

你将学到什么 ​

最终效果 ​

前置准备 ​

第 1 步：配置第三方提供商 ​

第 2 步：选择模型并验证连接 ​

总结 ​