opencode 自定义模型渠道配置教程

opencode 配置自定义渠道的痛点

opencode 是一款开源 AI 编程代理（官网），提供终端、桌面和 IDE 多种使用方式，支持 75+ LLM 提供商（包括 Claude、GPT、Gemini 等），在 GitHub 上已获得超过 160K Star，月活开发者超过 750 万。但不少用户在初次使用时卡在了一个关键环节：如何配置公益站、中转站等自定义模型渠道？

官方文档（opencode.ai/docs）对此着墨不多，配置文件是 JSON 格式，字段嵌套较深，稍有不慎就会报错。更麻烦的是，不同渠道的 API 地址、模型名称各不相同，有些还需要在 URL 末尾加上 /v1 后缀。如果你还在到处翻 GitHub Issue 找配置方法，本文就是为你准备的。

下面我将详细介绍两种配置方式：方法一修改 baseURL（简单粗暴，推荐新手使用），以及方法二自定义 Provider（灵活精细，适合进阶用户）。

前置准备：安装 opencode

在开始配置之前，确保你已经安装了 opencode。推荐使用官方一键安装脚本：

# 推荐方式：一键安装（macOS / Linux / WSL）
curl -fsSL https://opencode.ai/install | bash

# macOS (Homebrew，推荐使用官方 tap)
brew install anomalyco/tap/opencode

# 或使用 npm 全局安装
npm install -g opencode-ai

Windows 用户可使用 choco install opencode 或 scoop install opencode，也可以在 WSL 中使用上述命令。更多安装方式请参考官方文档。

方法一：修改 baseURL（简单粗暴，推荐）

这是最简单的配置方式：先用 opencode 自带的登录流程完成 Anthropic 认证，然后手动把 API 请求地址替换成你的渠道地址。本质上就是「挂羊头卖狗肉」——让 opencode 以为自己连的是 Anthropic 官方，实际上请求发到了你的渠道。

步骤 1：初始化 Anthropic 配置

在终端中启动 opencode：

opencode

进入 TUI 界面后，输入 /connect 命令，在弹出的供应商列表中选择 Anthropic。系统会提示输入 API Key——这里直接输入你从渠道商那里获得的 API Key 即可，不需要是 Anthropic 官方的 Key。输入完成后按回车确认。

步骤 2：修改 opencode.json

退出 opencode 后，用编辑器打开配置文件，找到 provider 字段下的 anthropic 对象，在其中添加 baseURL 配置：

"provider": {
  "anthropic": {
    "options": {
      "baseURL": "你的渠道的Claude Code API URL地址/v1"
    }
  }
}

关键提醒：大多数渠道的 baseURL 需要在末尾加上 /v1。如果配置后请求报 404，大概率就是这个后缀没加。具体 URL 请向你使用的渠道商确认。

如果你使用的是 oh-my-openagent（原名 oh-my-opencode，一款 opencode 增强版插件，提供多 Agent 协作、自动模型编排等功能），还需要同步修改对应的插件配置文件（oh-my-openagent.jsonc 或旧版 oh-my-opencode.json）中的相关字段。

步骤 3：修改模型名称

最后一步，把 opencode 默认使用的模型名称改成你的渠道支持的模型。在 opencode.json 中找到 model 字段，修改为渠道提供的模型 ID。常见的模型名称包括：

# 示例：修改模型字段
"model": "claude-sonnet-4-5-20250929"

如果你需要使用更强的模型，也可以改为：

"model": "claude-opus-4-5-20251101"

模型名称取决于你的渠道支持哪些模型，务必与渠道商确认后再填写。保存配置文件后，重新启动 opencode 即可生效。

方法二：自定义 Provider（灵活精细）

方法一虽然简单，但它「劫持」了 Anthropic 的 provider 配置。如果你需要同时使用多个渠道，或者想要更精细地控制模型参数（如上下文长度、输出限制等），方法二更适合你。这种方式通过注册一个全新的 Provider 来实现，不会影响原有的 Anthropic 配置。

步骤 1：创建自定义供应商

在终端启动 opencode，输入 /connect 命令，在选择供应商时选择 Other（其他）。系统会提示你输入自定义的 Provider ID，你可以随意命名，比如 my-channel 或 gongyi，只要你自己能辨识即可。然后输入渠道提供的 API Key。

步骤 2：配置 Provider JSON

打开 ~/.config/opencode/opencode.json，在 provider 对象中，你会看到刚刚创建的供应商条目。将它补充完整：

"provider": {
  "my-channel": {
    "npm": "@anthropic-ai/sdk",
    "name": "我的渠道",
    "options": {
      "baseURL": "你的渠道的Claude Code API URL地址/v1",
      "apiKey": "你的API Key"
    },
    "models": {
      "claude-sonnet-4-5-20250929": {
        "name": "Claude Sonnet 4.5",
        "contextLength": 200000,
        "maxOutputTokens": 64000,
        "modalities": ["text"],
        "capabilities": ["code", "text"]
      }
    }
  }
}

下面对各字段做简要说明：

• npm：指定 SDK 类型，使用 Anthropic 兼容接口时填 @anthropic-ai/sdk
• name：显示名称，随意填写
• options.baseURL：渠道的 API 地址，别忘了 /v1 后缀
• options.apiKey：渠道提供的 API Key
• models：定义可用模型及其参数，键名为模型 ID

步骤 3：设置模型参数

在 opencode.json 的顶层配置中，将 model 字段指向你自定义 Provider 下的模型：

"model": "claude-sonnet-4-5-20250929"

如果你需要配置多个模型（比如一个用于日常编程，一个用于复杂推理），可以在 models 中添加多个条目：

"models": {
  "claude-sonnet-4-5-20250929": {
    "name": "Claude Sonnet 4.5",
    "contextLength": 200000,
    "maxOutputTokens": 64000,
    "modalities": ["text"],
    "capabilities": ["code", "text"]
  },
  "claude-opus-4-5-20251101": {
    "name": "Claude Opus 4.5",
    "contextLength": 200000,
    "maxOutputTokens": 32000,
    "modalities": ["text"],
    "capabilities": ["code", "text", "reasoning"]
  }
}

保存文件后重启 opencode，即可在模型选择中看到你配置的所有模型。

常见问题与注意事项

配置过程中可能会遇到一些坑，这里汇总几个常见问题：

• 请求报 404 错误：99% 的原因是 baseURL 没加 /v1 后缀。检查一下配置文件中的 URL 是否以 /v1 结尾。
• API Key 认证失败：确认你使用的是渠道商提供的 Key，而不是 Anthropic 官方的 Key。部分渠道的 Key 格式与官方不同。
• 模型名称不识别：不同渠道支持的模型 ID 可能不同，务必向渠道商确认准确的模型名称。不要想当然地填写。
• 使用限制：某些公益站或中转站可能会限制并发请求数或每日调用次数，使用前请了解渠道的使用规则。
• 平台合规风险：部分平台（包括 Anthropic 官方）可能禁止通过非官方 CLI 工具调用其 API。使用第三方渠道时请自行评估合规风险，本文仅供技术探讨。
• oh-my-openagent 用户：如果你使用了 oh-my-openagent（原名 oh-my-opencode）插件，修改配置时需要同时修改 opencode.json 和插件配置文件（oh-my-openagent.jsonc 或旧版 oh-my-opencode.json），确保二者一致。详见GitHub 仓库。
• 配置文件格式：JSON 格式要求严格，修改时注意逗号、引号、括号的配对。建议使用支持 JSON 语法检查的编辑器（如 VS Code）来编辑，避免格式错误导致 opencode 无法启动。

总结：选择适合你的配置方式

两种方法各有优劣，选择的关键在于你的使用场景：

两种配置方法对比

对比维度	方法一：修改 baseURL	方法二：自定义 Provider
配置难度	低，3 步搞定	中等，需手动编写 JSON
适用场景	只用一个渠道	多渠道切换或精细控制
灵活性	低，固定在 Anthropic 上	高，可注册任意数量 Provider
出错概率	低	中，JSON 格式容易手误

如果你只是想快速把 opencode 跑起来，方法一完全够用。如果你是重度用户，需要在不同渠道和模型之间灵活切换，方法二值得花几分钟配置一下。

无论选择哪种方式，核心步骤都是一样的：拿到 API Key → 修改配置文件 → 填入正确的 baseURL 和模型名称。只要这三个信息准确无误，opencode 就能正常工作。

希望这篇教程能帮你省去反复试错的时间。如果你在配置过程中遇到其他问题，欢迎在评论区交流。