从零配置 OpenCode

准备（Preparation） ​

本页适用于一个实际支持 OpenAI-compatible 请求的上游端点。预计 10 分钟；需要 CC Switch v3.20.0、OpenCode 和一把仅用于 OpenCode 的 Key。/v1/models 只说明该 Key 和分组可见某个模型 ID，不能证明端点接受 OpenCode 的请求格式，也不能把 ChatGPT 订阅登录替代成 API Key。

下载（Download） ​

从 OpenCode 官方仓库 或 官方文档 安装 OpenCode；例如官方 npm 方式是 npm i -g opencode-ai@latest。从 CC Switch v3.20.0 Release 下载与你的系统架构相符的包。打开已安装的 CC Switch，进入 关于，确认显示 v3.20.0；若实际版本不一致，先停止，不要继续配置。不要使用来历不明的安装脚本或镜像包。安装后新开终端并运行 opencode --version；只有命令成功并打印版本号，才继续首次启动。若找不到命令，先修复安装路径或 PATH。

首次启动（First launch） ​

先运行 opencode 一次，完成它自己的引导或登录，然后退出所有 OpenCode 会话。这样会建立原生配置目录；CC Switch 写入时不应与正在运行的客户端竞争同一个文件。

API Key 与分组（API Key and group） ​

在梭子蟹创建专用 Key，选择同时允许目标平台、端点和模型的分组。记录 Key 名称、时间和分组，不记录完整 Key。若需要工具或图片，也先确认该分组授予对应能力；401、403 不能靠更换模型名绕过。

模型目录：GET /v1/models ​

在配置 Provider 前，用同一把 Key 请求 GET https://suoxie.codes/v1/models，只从 data[].id 原样复制模型 ID 到 <MODEL_FROM_V1_MODELS>。下文的 <API_KEY> 只是说明应输入哪一把 Key；实际命令通过隐藏提示读取，不要把占位符或真实 Key 写进命令历史。

$secureKey = Read-Host "API key" -AsSecureString
$credential = [System.Net.NetworkCredential]::new("", $secureKey)
$env:SUOXIE_API_KEY = $credential.Password
try {
  curl.exe --fail-with-body https://suoxie.codes/v1/models `
    -H "Authorization: Bearer $env:SUOXIE_API_KEY"
}
finally {
  Remove-Item Env:SUOXIE_API_KEY
  Remove-Variable secureKey, credential
}

read -rsp "API key: " SUOXIE_API_KEY
printf '\n'
export SUOXIE_API_KEY
curl --fail-with-body https://suoxie.codes/v1/models \
  -H "Authorization: Bearer $SUOXIE_API_KEY"
unset SUOXIE_API_KEY

在 CC Switch 配置 Provider ​

先完全退出 OpenCode。若 ~/.config/opencode/opencode.json 已存在，手动复制为同目录的 opencode.json.before-cc-switch；确认副本可读后再操作。在 CC Switch 选择 OpenCode，点击 +，创建唯一 ID，例如 suoxie-openai。Base URL 填 https://suoxie.codes/v1，API Key 填专用 Key，模型填 <MODEL_FROM_V1_MODELS>，并选择 OpenAI-compatible。保存后，CC Switch 以增量方式更新 opencode.json；已有顶层设置和其他 provider 应保留。若原文件不存在，记录这一点即可，不要创建空的假备份。

下列 JSON 是应有的原生结构示意，<API_KEY> 仅是占位符：

{
  "provider": {
    "suoxie-openai": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Suoxie OpenAI-compatible",
      "options": {
        "baseURL": "https://suoxie.codes/v1",
        "apiKey": "<API_KEY>"
      },
      "models": {
        "<MODEL_FROM_V1_MODELS>": {
          "name": "<MODEL_FROM_V1_MODELS>"
        }
      }
    }
  }
}

不要把 /v1/chat/completions 粘进只接受 API 根地址的 baseURL，也不要因为模型出现在列表中就假定本地转换或代理对所有模型通用。

模型映射与协议（Model mapping and protocol） ​

OpenCode 的显示选择为 suoxie-openai/<MODEL_FROM_V1_MODELS>，上游真实模型也是 <MODEL_FROM_V1_MODELS>。默认模型、快速模型和备用模型都必须是同一 Key 通过 GET /v1/models 返回的 ID；本页不承诺任何固定 gpt-* 名称长期可用。@ai-sdk/openai-compatible 只选择 OpenAI-compatible 适配器，不会把 Anthropic、Gemini 或未知私有协议自动转换为可用协议。

保存、启用与重启（Save, enable, and reload） ​

确认 CC Switch 中 Provider 卡片已保存并启用，然后关闭终端与现有 OpenCode 会话，重新打开终端并运行 opencode。在模型选择中确认出现 suoxie-openai/<MODEL_FROM_V1_MODELS>；未出现时先检查 JSON 语法、Provider ID 和实际使用的 OpenCode 配置目录。

第一个请求（First request） ​

选择该 Provider 和模型，只发送 Reply with OK。成功标准是 OpenCode 返回简短文本，并且模型选择仍显示刚配置的 Provider。失败时一次只检查一个变量：Key/分组、模型 ID、https://suoxie.codes/v1、或上游是否真正支持 OpenAI-compatible 请求。

Key 用量（Key usage） ​

到 Key 用量 按时间、Key、分组、端点和真实模型筛选，核对请求数、输入/输出 Token 和费用。没有记录时先刷新并扩大时间范围；不要重复提交首个请求来猜测是否成功。

错误处理（Errors） ​

回滚与安全（Rollback and security） ​

先重新启用原来的 Provider 并用短请求确认，再删除本次新增的 provider.suoxie-openai。若需要完整恢复，退出 OpenCode 与 CC Switch，将手动创建的 opencode.json.before-cc-switch 复制回 opencode.json，重启后复测；本页不声称 CC Switch 会为 OpenCode 自动备份。不要提交 Key、截图、共享 .env 或同步配置目录；若正式凭据已泄露，应另行轮换。确认旧 Provider 路径的短请求正常后，最后撤销本轮临时测试 Key。若这里配置的是仍在使用的正式专用 Key，应继续保留它，只撤销本轮临时测试 Key，不影响正在使用的正式 Key。