cc-switch 配置教程

用 TheRouter 做多客户端的统一路由层，而不是手改每个 CLI 的本地配置。

当你需要在 Claude Code、Codex、Gemini CLI、OpenCode、OpenClaw 之间切换 provider， cc-switch 会比手改每个工具的配置文件更稳定。TheRouter 的价值则是让这些客户端共用一把 routing key、统一路由策略、故障切换和计费视图。

什么时候应该优先看这页

如果你是“多客户端切换”而不是“单一工具直连”，这页优先级高于 Cursor 或 Claude Code 单页导读。

1. 先创建 TheRouter routing key

先在 TheRouter 控制台创建 tenant API key。cc-switch 里粘贴的是这把 key，不是 management key。

text

Dashboard → API Keys
Create Key
立即复制完整 key

预期格式：sk-...

2. 在 cc-switch 里选择目标客户端

先选你要驱动的客户端，再加 TheRouter preset。不同客户端背后对应不同协议。

text

Claude Code  → Anthropic 兼容路径
Codex        → OpenAI 兼容路径
Gemini CLI   → Gemini 原生路径
OpenCode     → OpenAI 兼容路径
OpenClaw     → OpenAI 兼容路径

3. 添加 TheRouter preset

打开 Add Provider，搜索 TheRouter，粘贴 key，然后启用 preset。如果列表里还没有，先把 cc-switch 更新到包含最新 provider presets 的版本。

text

cc-switch → 目标客户端 → Add Provider
搜索：TheRouter
粘贴：sk-...
启用 preset
必要时重启目标 CLI

4. 理解不同客户端的 base URL 规则

cc-switch 帮你减少手动编辑，但不会抹平协议边界。不同客户端仍然要走各自正确的 TheRouter 入口。

text

Claude Code preset:
  base URL = https://api.therouter.ai

Codex / OpenCode / OpenClaw preset:
  base URL = https://api.therouter.ai/v1

Gemini CLI preset:
  base URL = https://api.therouter.ai

5. 先验证链路，再排桌面端问题

先确认 key 和模型别名是活的，再去怀疑 cc-switch 或目标 CLI。

bash

curl https://api.therouter.ai/v1/models \
  -H "Authorization: Bearer $THEROUTER_API_KEY" | head -c 400

常见错误

text

1. 用成了 management key，而不是 tenant routing key
2. 把 OpenAI 兼容和 Anthropic / Gemini 原生入口混在一起
3. 切换 preset 之后没重启目标 CLI
4. 以为 cc-switch 会自动修正错误模型别名
5. 直接拿缓存里的旧模型名继续用

cc-switch 不是协议转换魔法

cc-switch 主要解决的是“本地配置管理”问题，不是把所有客户端都变成同一种协议。你仍然需要为 Claude Code、Gemini CLI 和 OpenAI 兼容工具选择正确的 TheRouter preset。