OpenCode 接入 CCSub 中转教程：模型映射与终端编码配置

OpenCode 是终端里跑的开源编码助手，和 Claude Code、Codex 一样走命令行交互，但它的模型来源是自己配置的 provider，而不是写死某个厂商。这意味着你只要把 provider 的 Base URL 指向 CCSub，就能在同一个终端界面里调用 GPT 系列和 Claude 系列模型。

这篇教程只做一件事：让 OpenCode 稳定连上 https://ccsub.xyz，并且不和已经装好的 Codex CLI 配置互相覆盖。如果你还没注册，先看 注册与充值 拿到密钥，再回来照着做。

开始之前：确认三件事

• Node.js 已安装（node -v 能输出版本号），OpenCode 通过 npx 或本地安装启动都依赖它。
• 已有 CCSub 的 API Key，形如 sk-你的CCSub密钥，在控制台的密钥页面创建。
• 账户余额充足。OpenCode 一次会话会带较长的上下文，输入 token 消耗比单轮对话高，余额不足时客户端通常只报连接层失败，很容易误判成网络问题。

提醒：CCSub 的 OpenAI 兼容入口是 https://ccsub.xyz/v1，Anthropic 原生入口是 https://ccsub.xyz/api。OpenCode 用哪个取决于你配置的 provider 类型，两者不能混填。

第一步：先查清楚有哪些模型可调用

不要凭记忆写模型 ID。CCSub 的可用模型列表可以通过公开接口查询：

curl https://ccsub.xyz/v1/models \
  -H "Authorization: Bearer sk-你的CCSub密钥"

返回结果里的 id 字段就是你要填进 OpenCode 配置的值。常见的例子包括 gpt-5.6-sol、gpt-5.6-terra、gpt-5.6-luna、gpt-5.5、claude-sonnet-4-6、claude-opus-4-8、claude-haiku-4-5 等。写错一个字符，客户端就会在发起请求时报 404 或模型不存在。

第二步：写入环境变量

OpenCode 读取环境变量来拿地址和密钥。在 Linux / macOS 上编辑 ~/.zshrc 或 ~/.bashrc，在 Windows 上用系统环境变量面板添加：

export OPENAI_BASE_URL="https://ccsub.xyz/v1"
export OPENAI_API_KEY="sk-你的CCSub密钥"

保存后执行 source ~/.zshrc 让当前终端生效，然后用 echo $OPENAI_BASE_URL 验证。注意 OPENAI_BASE_URL 只写域名和 /v1，不要在后面拼 /chat/completions，兼容层会自动补全路径。

为什么不是 https://ccsub.xyz/openai

https://ccsub.xyz/openai 是给 Codex CLI 用的原生入口，它会自动请求 /responses 端点。OpenCode 的 OpenAI 兼容 provider 走的是标准的 /v1/chat/completions，所以要用 https://ccsub.xyz/v1。这两个地址填反，是最常见的连接失败原因之一。

第三步：在 OpenCode 里配置自定义 provider

新建或修改 OpenCode 的配置文件，加入一个指向 CCSub 的 provider，并把模型 ID 映射成你能记住的别名：

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "ccsub": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "CCSub",
      "options": {
        "baseURL": "https://ccsub.xyz/v1",
        "apiKey": "{env:OPENAI_API_KEY}"
      },
      "models": {
        "gpt-5.6-sol": { "name": "GPT-5.6 Sol" },
        "gpt-5.5": { "name": "GPT-5.5" },
        "claude-sonnet-4-6": { "name": "Claude Sonnet 4.6" },
        "claude-haiku-4-5": { "name": "Claude Haiku 4.5" }
      }
    }
  },
  "model": "ccsub/gpt-5.6-sol"
}

要点说明：

• npm 指定的适配器让 OpenCode 按 OpenAI 兼容协议发请求，最终打到 https://ccsub.xyz/v1/chat/completions。
• apiKey 用 {env:OPENAI_API_KEY} 引用环境变量，比把密钥明文写进配置文件安全，也方便换机器。
• models 里的键必须是 CCSub 返回的真实模型 ID，值只是显示名称，改中文也不会影响调用。
• model 字段写 provider/model 格式，启动后默认就用这个模型。

如果你更习惯用 Claude 系列模型，也可以把它指向 Anthropic 原生入口：Base URL 填 https://ccsub.xyz/api，客户端会自动请求 /v1/messages。这是 Claude Code 走的同一条通道，适合需要长上下文推理和缓存读写的场景。

第四步：和 Codex CLI 配置分开，别互相覆盖

OpenCode 用户往往同时装了 Codex CLI，这两个工具的配置形态完全不同：

• Codex CLI 用一份 TOML 配置，地址填 https://ccsub.xyz/openai，并设置 wire_api = "responses"，它会自动请求 /responses 端点。
• OpenCode 用 JSON 配置加环境变量，地址填 https://ccsub.xyz/v1，走 /v1/chat/completions。

两者共用 OPENAI_API_KEY 是可以的，因为密钥本身通用。但如果你为了迁就 Codex 把 OPENAI_BASE_URL 改成 https://ccsub.xyz/openai，OpenCode 就会把请求发到错误的路径上。建议在 OpenCode 的 provider 里显式写死 baseURL，不要依赖全局环境变量兜底，这样即使 Codex 那边调整了配置，也不会牵连 OpenCode。

连接失败时的排查顺序

终端里报错信息通常很笼统，按下面的顺序逐层排除最快：

1. 先测密钥和网络：直接跑第一步的 curl https://ccsub.xyz/v1/models。如果这一步就失败，问题在密钥或网络，和 OpenCode 无关。
2. 检查 Base URL 是不是填了 /openai：这是最常见的错误，把它改回 https://ccsub.xyz/v1。
3. 检查模型 ID 是否拼错：用 /v1/models 的返回结果逐字比对，注意 claude-haiku-4-5 这类带日期的变体。
4. 确认环境变量已生效：新开的终端窗口才会读到最新变量，改完记得 source 或重启终端。
5. 看是否余额不足：账户欠费时部分客户端只显示连接错误。登录 CCSub 控制台核对余额和用量明细。
6. 检查本地代理：终端里残留的 HTTP 代理设置可能拦截请求到 ccsub.xyz，临时关闭后再试。

如果以上都排除了还连不上，把终端报错原文和你的配置文件片段一起提交到工单，能显著缩短定位时间。

成本与充值提醒

OpenCode 是重度消耗型工具：它会把项目文件片段、历史对话一起塞进上下文，单次请求的输入 token 往往比网页对话高出数倍。从平台用量看，gpt-5.6-sol 是近 30 天调用量最高的模型，gpt-5.5 紧随其后，两者都适合日常编码；claude-sonnet-4-6 则在长上下文任务里表现稳定。

建议做法：

• 先小额充值跑几天，观察控制台的 Token 明细，估算自己的日均消耗。
• 给 OpenCode 单独创建一个 API Key，方便按工具区分用量。
• 日常补全和简单改动用轻量模型，复杂重构再切到旗舰模型，成本差距很明显。

下一步

配置跑通后，建议继续阅读 入门使用手册 了解 Token 明细怎么看，以及 API 参数与推理能力 确认各接口支持哪些参数。遇到具体报错，故障排查 里有按症状索引的速查表。还没开始的话，先去 注册与充值 创建密钥，再回到本文第三步。

CCSub API 调用方法

如果你使用 OpenAI 兼容客户端，把 Base URL 设置为 https://ccsub.xyz/v1，API Key 使用控制台创建的 sk-你的CCSub密钥。

export OPENAI_BASE_URL=https://ccsub.xyz/v1
export OPENAI_API_KEY=sk-你的CCSub密钥

Codex 请使用原生 Responses 专用地址。先设置密钥：

export CCSUB_API_KEY=sk-你的CCSub密钥

再在 ~/.codex/config.toml 配置自定义 provider：

model = "gpt-5.6-sol"
model_provider = "ccsub"
[model_providers.ccsub]
name = "CCSub"
base_url = "https://ccsub.xyz/openai"
env_key = "CCSUB_API_KEY"
wire_api = "responses"

Claude Code 使用专用 Messages Base URL：

export ANTHROPIC_BASE_URL=https://ccsub.xyz/api
export ANTHROPIC_AUTH_TOKEN=sk-你的CCSub密钥

需要确认当前可用模型时，可以请求 GET https://ccsub.xyz/v1/models。正式长任务前，建议先用短请求验证 Key、余额和模型是否正常。