文档
CC Switch
CC Switch 是一款桌面应用,可让 Claude Code 和 Codex 在不同提供商之间切换。将 Kunavo 配置为 Custom Configuration——服务根地址、Bearer 身份验证、Anthropic Messages 原生格式,不启用本地路由。
三个字段和两个下拉菜单。将 https://api.kunavo.com 设为端点,使用你的 sk-kn-… 密钥,并且——这是大多数指南会遗漏的部分——将 API Format 保持为 Anthropic Messages (Native),将 Auth Field 保持为 ANTHROPIC_AUTH_TOKEN。Kunavo 原生支持 Messages API,因此 Claude Code 侧无需使用本地路由。
Provider Name Kunavo
API Key sk-kn-...
API Endpoint https://api.kunavo.com <- service root, no /v1, no trailing slash
Advanced Options
API Format Anthropic Messages (Native) <- the default; do NOT switch
Auth Field ANTHROPIC_AUTH_TOKEN (Default)/v1,末尾也不加斜杠。Anthropic 风格的客户端会自行追加 /v1/messages——这就是为什么此字段看起来与所有 OpenAI 示例都不同,后者需要在基础 URL 中包含 /v1。详细说明见ANTHROPIC_BASE_URL 页面。分步操作(Claude Code 选项卡)
- 在
/app/keys创建密钥并复制——它只会显示一次。 - 在 CC Switch 中打开顶层
Claude Code选项卡并点击加号按钮。保留默认的Custom Configuration,不要选择预设配置。 - 填写
Provider Name、API Key,并将API Endpoint设为https://api.kunavo.com。 - 展开
Advanced Options,确认API Format为Anthropic Messages (Native),且Auth Field为ANTHROPIC_AUTH_TOKEN (Default)。两者都是默认值;这里要做的是检查,而不是更改。 - 保存,然后
Enable。卡片不应显示Needs Routing标记——该标记只会出现在需要转换协议的提供商上。
CC Switch 的当前版本为 v4.0.20,于 2026 年 10 月 24 日发布,其 Claude Code 路由指南列出了三个 API 格式选项——Anthropic Messages(Native)、OpenAI Responses API(Requires routing)和 OpenAI Chat Completions(Requires routing)(github.com/farion1231/cc-switch,读取于 2026 年 10 月 25 日)。
为何没有 “Needs Routing” 标记
CC Switch 的本地路由用于桥接不同协议。Claude Code 会向 /v1/messages 发送 Anthropic Messages 请求;只提供 OpenAI Chat Completions 或 Responses API 的网关无法响应此类请求,因此路由会在请求发出时进行转换,并在响应返回时转换回原格式。转换过程中,流式事件、工具调用和思考配置都会被重新塑形——虽然可以正常工作,但这也会在编辑器和模型之间增加一个环节。
Kunavo 直接提供 POST /v1/messages,因此 Claude Code 侧无需转换:提供商保持为 Anthropic Messages (Native),路由完全不会参与请求流程。Kunavo 还通过同一密钥提供 POST /v1/chat/completions 和 POST /v1/responses,这使得下文介绍的 Codex 接入方式成为可能。
| CC Switch 选项卡 | 将格式设为 | 本地路由 |
|---|---|---|
| Claude Code | Anthropic Messages (Native) | 无需启用 |
| Codex | Anthropic Messages (routing required) | 必须启用——路由会将 /responses 重写为 /v1/messages |
在 Codex 中运行 Claude 模型
其他提供商指南没有介绍这种接入方式。Codex 使用 OpenAI Responses API,因此直接指向 /v1/messages 端点会返回 404——CC Switch 通过让 Codex 使用本地路由并进行转换来解决此问题。在 Codex 选项卡中没有 Anthropic 预设,因此这也是一个 Custom Configuration:
Provider Name Kunavo
API Key sk-kn-...
API Request URL https://api.kunavo.com
Default Model claude-sonnet-5
Advanced Options
Upstream Format Anthropic Messages (routing required)sk-kn-… 密钥可用于 Messages 接口和 Responses 接口,两者都没有客户端允许列表。如果你想完全跳过转换,也可以让 Codex CLI 直接调用 Kunavo 原生的 /v1/responses 接口;具体方法见Codex CLI 页面。模型映射
CC Switch 会将 Claude Code 的三个档位映射到实际模型 ID。请填写这三项以及 Default fallback model——否则,未匹配的请求会沿用原始 Claude 名称透传,并在上游报错。费率以美元/百万 token 计,依次为输入/输出,实时读取自模型目录。
| 层级 | 模型 ID | Kunavo 输入 / 输出 | 为什么 |
|---|---|---|---|
| Haiku | claude-haiku-4-5 | $0.70 / $3.50 | Claude Code 会将后台子任务路由到此档位——最便宜的档位最合适 |
| Sonnet | claude-sonnet-5 | $1.40 / $7.00 | 日常使用的默认选择 |
| Opus | claude-opus-5-5 | $2.80 / $14.00 | 架构级变更 |
1M。声明上游并不支持的上下文长度并不会扩展任何能力,只会让问题在漫长对话中途才暴露出来。调试应用前先验证
只需一组请求,就能判断故障出在密钥、端点还是 CC Switch。如果两者都返回 200,那么仍然出问题的就是表单中的某个字段,而且几乎总是 Auth Field,或是不该出现在端点中的 /v1。
# Settles whether a failure is the key, the endpoint, or CC Switch.
# 200 + a JSON list of model ids means the same key works in the app.
curl -sS https://api.kunavo.com/v1/models \
-H "Authorization: Bearer sk-kn-..."
# The Anthropic face, which is the one the Claude Code tab actually calls.
curl -sS https://api.kunavo.com/v1/messages \
-H "Authorization: Bearer sk-kn-..." \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{"model":"claude-haiku-4-5","max_tokens":16,
"messages":[{"role":"user","content":"ping"}]}'参考资料
CC Switch 是开源项目,地址为 github.com/farion1231/cc-switch。上述字段名称和行为均来自其自身指南——Claude Code 路由指南和Codex 路由指南,两份指南都说明适用于 3.17.0 及更高版本。较旧版本的表单有所不同;如果找不到此处提到的字段,请查看应用的“关于”面板。Kunavo 相关说明见 Messages API、Chat Completions和集成中心。
常见问题
如何在 CC Switch 中添加自定义提供商?
在 Claude Code 选项卡中点击加号按钮,保留默认的 Custom Configuration,然后填写 Provider Name、API Key 和 API Endpoint。API Endpoint 是网关的服务根地址,末尾不要加斜杠——Kunavo 的地址是 https://api.kunavo.com,不带 /v1。然后打开 Advanced Options,检查两个字段:API Format 和 Auth Field。这两个字段决定提供商能否正常工作,也是大多数设置指南会遗漏的内容。
Kunavo 是否需要启用 CC Switch 的本地路由?
不需要。本地路由用于在协议之间进行转换——当上游只支持 OpenAI Responses 或 Chat Completions 时,它会将 Claude Code 的 /v1/messages 请求转换为相应格式。Kunavo 在 https://api.kunavo.com/v1/messages 原生提供 Anthropic Messages API,因此 API Format 保持默认的 Anthropic Messages (Native),提供商卡片不会显示 Needs Routing 标记,请求会直接发送到上游。仅支持 Chat Completions 的网关则必须为每个请求启用本地路由。
为什么 OpenAI 示例中有 /v1,而 API Endpoint 不需要?
因为这两种约定本来就不同。Anthropic 风格的客户端会自行追加 /v1/messages,因此只需要源站地址——https://api.kunavo.com。OpenAI SDK 预期 base_url 中已包含 /v1,因此需要填写 https://api.kunavo.com/v1。CC Switch 的 Claude Code 选项卡使用 Anthropic 约定,因此省略 /v1。弄反这一点是所有客户端中最常见的设置错误;ANTHROPIC_BASE_URL 页面会介绍这两种格式。
Auth Field 应设为 ANTHROPIC_API_KEY 吗?
不,应保留默认值 ANTHROPIC_AUTH_TOKEN。该默认值会让 CC Switch 发送 Authorization: Bearer <key>。选择 ANTHROPIC_API_KEY 会改为发送 x-api-key 请求头,Kunavo 也能正常读取,因此请求头本身不是问题;关键在于授权。Claude Code 在交互会话中使用 ANTHROPIC_API_KEY 前会要求一次性授权;如果在那里拒绝密钥,之后该密钥就会被忽略——这类身份验证失败看起来像是密钥错误,实际上密钥本身没有问题。
能否通过 CC Switch 在 Codex 中运行 Claude 模型?
可以,而这是大多数提供商指南会跳过的另一种接入方式。在 Codex 选项卡中,添加 Custom Configuration,填写 API Request URL https://api.kunavo.com 和 Default Model(例如 claude-sonnet-5),然后在 Advanced Options 中将 Upstream Format 设为 Anthropic Messages (routing required)。此方向必须启用本地路由,因为 Codex 使用 Responses API,路由会将 /responses 重写为 /v1/messages。CC Switch 自己的指南提醒,某些提供商会限制其 Claude API 只能由 Claude Code 客户端使用,这类密钥通过 Codex 时会失败;Kunavo 没有这种限制:同一个 sk-kn- 密钥可用于两种接入方式。
CC Switch 的模型映射应填写哪些模型 ID?
使用 Kunavo 的目录 ID。一个合理的默认分配是:在 Haiku 层使用 claude-haiku-4-5(每 100 万个令牌 $0.70 / $3.50),因为 Claude Code 会将后台子任务发送到那里;在 Sonnet 层使用 claude-sonnet-5($1.40 / $7.00);在 Opus 层使用 claude-opus-5-5($2.80 / $14.00)。还要始终填写 Default fallback model(默认回退模型):如果留空,CC Switch 会使用原始 Claude 名称转发未匹配的请求,而这些请求会在上游报错。实时列表位于 GET /v1/models。
CC Switch 会将我的 API 密钥放在哪里?
密钥存放在 CC Switch 自己的存储中,而不是客户端配置里。CC Switch 将提供商保存在 ~/.cc-switch/cc-switch.db 中;当本地路由接管客户端时,它只会将本地路由地址写入 ~/.claude/settings.json,并在身份验证条目中使用占位符——真正的密钥由路由在转发请求时注入。这是 CC Switch 的特性,与 Kunavo 无关;了解这一点很有用,因为你粘贴的密钥不会出现在你可能准备提交的文件中。