CC Switch 是什么、怎么用?给 Claude Code 和 Codex 配置自定义供应商(含报错排查)
CC Switch 管的是你本机的供应商配置,不提供模型和 Key。给 Claude Code 和 Codex 接自定义供应商,协议不一样、步骤也不一样;供应商报错多数是 Base URL、模型名或协议三处对不上。
1. CC Switch 是什么,不是什么
AI 编程工具(Claude Code、Codex 等)都有各自的配置文件来指定「请求发到哪里、用哪个 Key、用哪个模型」。如果你要在官方账号、几个中转服务、不同项目之间来回切换,手动改配置既麻烦又容易出错。CC Switch 就是把这些配置集中管理、一键切换的本机工具。它不是模型服务:没有模型、没有 Key、没有余额。所以「用 CC Switch 调用 cocodot」的准确说法是:CC Switch 保存并应用配置,cocodot 提供 API 端点、Key、模型调用和余额。二者独立。官方仓库是 farion1231/cc-switch,安装请认这个来源,别下载来路不明的第三方安装包。
2. 接入前准备:Key、余额、一次小额验证
先在 cocodot 后台创建一个 API Key,并确认账户里有余额(API 按量计费,支付宝或微信充值;Claude、GPT、Gemini 各线挂牌价不超官网,逐型号以价格页实时标价为准)。验证邮箱后有一份体验额度,仅可调 API,具体可用模型以价格页为准,足够你先跑通。建议一个项目一个 Key:用量能分开看,某个 Key 泄露也可以单独作废。配置之前,先在 cocodot 后台复制对应工具的「精确配置清单」,里面有当前的 Base URL 和模型角色,比任何文章里的写法都新。
3. 给 Claude Code 接入:原生 Anthropic 端点,不需要路由
Claude Code 说的是 Anthropic Messages 协议,cocodot 提供原生的 Anthropic 兼容端点,所以这条线不需要开 CC Switch 的路由。步骤:在 CC Switch 里添加 Claude Code 的自定义供应商,Base URL 填 `https://cocodot.co/api/ai`(注意不带 /v1),按配置清单填好各个模型角色,把真实 Key 粘贴在 CC Switch 本地,保存并启用,然后重启 Claude Code 会话。Base URL 带不带 /v1 是这条线最常见的错误:多写 /v1 通常得到 404。
4. 给 Codex 接入:为什么必须开本地路由
Codex 使用 OpenAI Responses 协议,而 cocodot 目前的 OpenAI 兼容端点提供的是 Chat Completions。两种协议不一样,不能直接对话,需要中间翻译一层:CC Switch 的 Codex Routing(本地路由) 就负责这件事。步骤:添加 Codex 供应商,Base URL 填 `https://cocodot.co/api/ai/v1`(带 /v1),上游格式选 Chat Completions,然后打开 Routing 总开关和 Codex 路由,最后重启 Codex 会话。三项缺一就会出现「连不上」或「行为不对」。
5. 模型名与上下文窗口:两件容易被忽略的设置
模型名:要用端点真正提供的名字,别凭记忆写。cocodot 的官方名和网关代号都可以用,完整列表在价格页,机器可读的版本是 `GET https://cocodot.co/api/ai/models`。上下文窗口:有些工具按你声明的窗口大小决定什么时候自动压缩对话。如果声明得比模型实际支持的小很多,工具会过早压缩、体验变差;如果声明得比实际大,则可能撞上限报错。以配置清单里给出的窗口为准,别自己随便改。
6. 「供应商错误」怎么排:三项对齐,再看 Key 和余额
按这个顺序查:① Base URL——Claude Code 不带 /v1,Codex 带 /v1;② 模型名——与端点列表一字不差;③ 协议和路由——Codex 必须开路由并选 Chat Completions;然后看④ Key是否有效、没有多余空格;最后看⑤ 余额是否为零(额度不足时请求会失败)。一次只改一项,改完重启会话再测,否则分不清是哪一项起了作用。想隔离 CC Switch 的因素,可以在终端里直接 curl 一次同样的端点,通了说明端点没问题,问题在本机配置。
7. Key 安全:三条别破的规矩
第一,真实 Key 只粘贴在 CC Switch 本机界面里,不要放进 Deep Link、网址或分享给别人的配置链接,URL 可能进入浏览器历史、日志、剪贴板历史和分析系统。第二,别把 Key 写进截图、聊天记录和公开仓库,发求助帖时先打码。第三,发现疑似泄露,立刻在后台作废该 Key 并重建,一个项目一个 Key 的好处就在这里:只影响一个项目。
8. 怎么确认「真的走了 cocodot」
配置完不要只看工具能不能回答,要确认请求确实走了你配置的端点:先发一条最小请求(一句话、很短的输出),然后去 cocodot 后台看用量记录里有没有刚才那条,余额是否按预期减少。如果后台没有记录,说明工具没有使用你的供应商,多半是会话没重启,或者官方登录仍然生效。确认通过后,再用它做真实工作。内置的 cocodot 预设我们已向 CC Switch 上游提交,在被接受并发布之前,请按本文方式手动添加。
供应商报错对照:症状 → 最可能原因 → 先做什么
| 症状 | 最可能原因 | 先做什么 |
|---|---|---|
| 401 / 认证失败 | Key 填错、过期,或粘进了错误的字段 | 重新复制 Key,确认没有多余空格和换行 |
| 404 / 路径不存在 | Base URL 多写或少写了 /v1 | Claude Code 用不带 /v1 的地址;Codex 用带 /v1 的 |
| model not found | 模型名与端点提供的不一致 | 按后台配置清单或模型列表原样复制 |
| Codex 连不上或行为异常 | 没开本地路由,或上游格式没选 Chat Completions | 开启路由总开关与 Codex 路由,重启 Codex 会话 |
| 切换后没生效 | 工具读的是旧配置,会话没重启 | 切换供应商后重启 Claude Code / Codex 会话 |
| 提示 not logged in | 工具仍在使用官方登录而不是自定义供应商 | 确认供应商已启用,再重启会话 |