接入 OpenCode

OpenCode 是一款开源智能开发工具，提供桌面版和命令行版，能够理解项目上下文、修改代码、调用工具，并连接不同的模型供应商。更多信息请查看 OpenCode 官方文档。

OpenCode 可通过 Better Gate 客户端或手动配置接入 Better Gate。当前版本的 CC Switch 暂无经过验证的完整接入流程。请选择一种可用方式，不要同时使用，以免配置相互覆盖。

1 安装 OpenCode

1.1 安装 OpenCode 桌面版（Windows、macOS、Linux）

打开 OpenCode 官方下载页，下载并安装对应系统的版本。

1.2 安装 OpenCode CLI（Windows、macOS、Linux）

先安装 Node.js，然后打开终端，运行：

npm install -g opencode-ai
opencode --version

安装完成后，请至少启动一次 OpenCode。开始配置 Better Gate 前，请完整退出 OpenCode Desktop 和所有 OpenCode CLI 会话。

2 准备 Better Gate 配置

登录 Better Gate 控制台。
确认账户有可用余额（组织成员需确认自己的成员额度够用）。
打开“API Keys”，点击“创建 Key”。
填写 Key 名称，路由方式保持默认的“智能路由”就行，它会自动挑可用渠道；只有需要固定渠道时才选“指定渠道分组”。组织管理员为成员创建 Key，记得勾选“分配给成员”。
点击创建，复制并保存好完整的 API Key。
打开“模型列表”，复制准备使用的模型 ID。

OpenCode 的自定义提供商使用 OpenAI 兼容协议。Claude 系列模型通过该协议时，可能无法保留原生缓存等 Claude 专属能力。

3 选择接入方式

3.1 通过 Better Gate 客户端接入 OpenCode (推荐)

下载并安装 Better Gate 客户端：

系统	下载地址
Windows	下载 Better Gate Windows 客户端
macOS	下载 Better Gate macOS 客户端

安装并启动客户端，点击“登录”。
浏览器打开授权页面后，确认当前账号并点击“授权并继续”，随后返回客户端。

Better Gate 客户端主界面

通过客户端接入 OpenCode：

OpenCode 支持同时连接多把 API Key，接入弹窗按密钥独立管理，不是选一把 Key 就完成。

完整退出 OpenCode Desktop 和所有 OpenCode CLI 会话。
找到 OpenCode 卡片，点击“一键接入”（已经接入过至少一把密钥时，按钮会显示“管理接入 (n)”，打开的是同一个弹窗）。
在弹窗的密钥列表中，找到要使用的 API Key，点击这一行的“添加”；如果列表未更新，点击“刷新密钥”。
在模型列表中勾选一个或多个要接入的模型，点击“确认添加”。
需要接入其他密钥或模型时，重复第 3、4 步；全部完成后点击“完成”关闭弹窗。

不再需要某把密钥时，点击它这一行的“移除”即可断开；如果该密钥的模型是 OpenCode 当前的默认模型，“移除”按钮会被禁用，需要先在 OpenCode 里把默认模型换成其他来源，再回来移除。

3.2 手动配置 OpenCode

OpenCode CLI 与 Desktop 共用用户级配置：

macOS、Linux：~/.config/opencode/opencode.jsonc
Windows：%USERPROFILE%\.config\opencode\opencode.jsonc

先启动 OpenCode，在交互界面执行 /connect：

在供应商列表底部选择 Other。
Provider ID 输入 better-gate。
粘贴完整的 Better Gate API Key。

凭证会由 OpenCode 保存到自己的认证文件中。随后创建或编辑 opencode.jsonc：

{
  "$schema": "https://opencode.ai/config.json",
  "model": "better-gate/YOUR_MODEL_ID",
  "provider": {
    "better-gate": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Better Gate",
      "options": {
        "baseURL": "https://gateway.better-gate.com/v1"
      },
      "models": {
        "YOUR_MODEL_ID": {
          "name": "YOUR_MODEL_ID"
        }
      }
    }
  }
}

将所有 YOUR_MODEL_ID 替换为 Better Gate 控制台中的真实模型 ID。如果文件中已有其他配置，请合并 model 和 provider 字段，不要直接覆盖原文件。

完成任一接入方式后，重新启动 OpenCode，执行 /models 并选择 Better Gate 模型；手动配置时还可以运行 opencode auth list 检查凭证。新建会话并发送一条简短消息，再前往 Better Gate 控制台的用量页面，确认是否出现对应的请求记录。