让 Codex 直连 Claude 网关：CC Switch 本地路由配置指南-平芜编程栈

让 Codex 直连 Claude 网关：CC Switch 本地路由配置指南

【免费下载链接】cc-switchA cross-platform desktop All-in-One assistant for Claude Code, Codex, OpenCode, OpenClaw, Grok Build & Hermes Agent. Only official website: ccswitch.io项目地址: https://gitcode.com/GitHub_Trending/cc/cc-switch

Codex 只说 OpenAI Responses 协议，而你的 Claude 网关只开出了 Anthropic Messages 端点（/v1/messages）——两边各说各话，直连必然 404。CC Switch（3.17.0+）的本地路由正好站在中间做翻译：Codex 照旧发 Responses 请求，路由把请求体改成 Anthropic Messages 发给上游，再把返回的 JSON/SSE 逐字段转回 Responses 结构。照着下文走完三步配置，就能在 Codex 里跑任意 Claude 模型，请求怎么转换、密钥存在哪里、截断从哪来，也一次讲清楚。

什么情况下你需要它

三个场景，命中任意一个就值得看下去：

手里只有中转网关密钥：某 Claude 家族中转网关只给了/v1/messages地址和 key，而你想用 Codex 的交互方式跑 Claude 模型。
公司禁了客户端，但保留了网关：模型服务可用，缺的只是一个被许可的客户端。Codex 顶在这个位置上，走的是网关正式放行的 Messages 协议。
想用 Codex 统一调度多模型：Responses 供应商走原生通道，Anthropic 格式的供应商走本地路由，在一个客户端里混着用。

痛点都出在同一处：新版 Codex CLI 面向 Responses API 设计，把网关地址直接填进 Codex 配置，它会对/responses端点发出请求，而 Anthropic 协议的上游根本没有这个路径。解法不是改 Codex，而是在本地架一个路由替两边翻译。

一次请求的旅程：Responses 到 Messages 再到 Responses

先过一遍原理，后面操作会顺很多。把本地路由想成公司前台：来访者（Codex）只和前台打交道，前台再决定怎么把事递到楼上（上游网关）。

阶段	发生什么
1. Codex 发出请求	目标地址是`http://127.0.0.1:15721/v1/responses`（默认端口 15721），协议是 Responses，模型名、对话、工具定义都在请求体里
2. 路由识别供应商	当前供应商的`Upstream Format`是`Anthropic Messages (routing required)`（上游格式：真实网关说的是 Anthropic 协议），路由决定进入转换分支
3. 改写请求	路径`/responses`→`/v1/messages`；请求体翻译成 Anthropic 结构；密钥按`Auth field`注入请求头；模型名做映射与`[1m]`后缀处理
4. 上游应答	网关返回 Anthropic 格式的 JSON，或 SSE 流式事件（thinking、工具调用、图片都在里面）
5. 转回 Responses	路由把 JSON/SSE 逐字段翻回 Responses 结构，Codex 看到的始终是一个"正常的 Responses 端点"

全程 Codex 无感知：它没改一个字，只是把"对方"换成了本地这台 15721 端口。

从零到可用：三步配置

① 注册网关供应商

打开 CC Switch，切到顶层Codex页签，点右上角加号，保持默认的Custom Configuration（自定义配置），填四个字段：

字段	填什么
`Provider Name`	任意，如`Claude Gateway`
`API Key`	网关密钥。真实密钥只存在 CC Switch 里，转发时由本地路由注入，永不写入 Codex 的 live 配置
`API Request URL`	只填网关服务根地址，如`https://your-gateway.example.com`。别自己拼`/v1/messages`；网关文档若给的是完整 messages URL，打开旁边的`Full URL`开关原样粘贴
`Default Model`	网关文档里能识别的 Claude 模型 id，如`claude-sonnet-5`，以网关文档为准

展开Advanced Options（高级选项），把Upstream Format从默认的Responses (native)改为Anthropic Messages (routing required)，下方出现三个配套字段：

Auth field（认证字段）：决定密钥用哪个请求头发给上游，两个只发其一。
- ANTHROPIC_AUTH_TOKEN (Authorization)：发Authorization: Bearer <key>。这是默认值，多数 Claude 中转网关用它；
- ANTHROPIC_API_KEY (x-api-key)：发 Anthropic 原生的x-api-key头，部分遵循原生约定的网关要求这个。选错典型症状是 401 / 403。
Emulate Claude Code client（伪装 Claude Code 客户端）：默认关闭。仅当网关明确限定"仅限 Claude Code 使用"时才开——它会替换 User-Agent、anthropic-beta、x-app等请求头，并在系统提示首行注入 Claude Code 身份标识。普通网关保持关闭。
Max output tokens（输出上限）：Anthropic 协议里max_tokens必填。Codex 请求没带上限时，路由回退到保守的 8192——细节见下文"能力清单"。遇到截断就把这里提到模型真实上限，别超过，否则上游直接 400。
Model Mapping（模型映射）：可选。每行一个网关能识别的模型 id（如claude-opus-4-8、claude-haiku-4-5-20251001），CC Switch 据此生成模型目录，Codex 的/model菜单里就能列出它们；留空则 Codex 只用默认模型。

保存后供应商卡片上会出现Needs Routing（需要路由）标记——这类供应商只在本地路由运行时可用。

② 打开路由开关并接管 Codex

进设置页Routing页，展开Local Routing（本地路由），完成两个开关：

打开Routing Master Switch（路由总开关），启动本地服务；默认监听127.0.0.1:15721，端口可在代理面板修改（见用户手册 Proxy Service）；
在Routing Enabled下打开Codex。"接管"指的就是这一步：CC Switch 改写~/.codex/config.toml，把当前model_provider段的base_url指向本地路由，并强制保留wire_api = "responses"（wire_api是 Codex 配置里的字段，声明它对外用哪种 API 协议）——所以接管之后 Codex 发的依然是 Responses 请求，只是收件人变了。Claude、Gemini 的开关可以保持关闭（见用户手册 App Routing）。

接管后config.toml大致长这样：

[model_providers.custom] name = "..." base_url = "http://127.0.0.1:15721/v1" wire_api = "responses"

安全设计值得单独说一句：auth.json里只有占位符，真实密钥留在 CC Switch 的供应商配置里，转发时才由本地路由按你选的Auth field注入——密钥不落进 Codex 的任何文件。

③ 启用供应商并重启 Codex

回到 Codex 供应商列表，点该供应商的Enable。如果路由没开，CC Switch 会提示该供应商需要路由服务先启动——回到上一步打开即可。

然后重启当前 Codex 终端会话：config.toml和模型目录是进程启动时读取的，运行中的进程不保证热加载。

进 Codex 后逐条验证：

配置过模型映射的话，用/model确认 Claude 模型出现在菜单里；
发一个小问题，看设置 → Routing 页的 "Current Provider" 从 "Waiting for first request..." 变成你的 Claude 供应商，"Total Requests" 开始增长；
用量面板里这些请求的模型名如实显示为claude-*，可按供应商筛选、核对 token 消耗。

启用后的能力清单与取舍

能力	行为
Prompt 缓存	转换后自动按 Anthropic 惯例注入 5 分钟缓存标记（系统提示、工具定义、对话历史），长对话不必每轮全价重发，免配置
Extended thinking	无损往返。带签名的 thinking / redacted-thinking 块会 Base64 编码后藏进 Responses 的`reasoning.encrypted_content`字段（前缀`ccswitch-anthropic-thinking-v1:`），下一轮工具请求时原样回放给上游
工具调用 / 图片 / PDF 输入	完整转换，多轮工具循环可用
`[1m]`长上下文标记	模型 id 以`[1m]`结尾（如`claude-sonnet-5[1m]`）时，路由剥离该后缀并自动加上 1M 上下文 beta 头（`context-1m-2025-08-07`），前提是网关支持；因为上游回写的模型名可能重新带上后缀，最终请求体上还会再剥离一次
Web search	被刻意禁用——转换层无法把`web_search`翻译成 Anthropic 端点的工具，留着只会让模型看到一件必败的事
输出上限	请求未携带时回退 8192；供应商层配置的`Max output tokens`优先级更高，会先注入请求体覆盖
截断上报	上游在输出上限处停止或流中断时，Codex 看到的是 "incomplete" 而非伪装的成功，方便发现并调大上限

推理强度也有对应映射：Codex 的reasoning.effort会被换算成 Anthropic thinking 的 token 预算——minimal/low → 2048、medium → 8192、high → 16384、xhigh/max/ultra → 24576；未识别的值直接不启用 extended thinking，避免误吞temperature/top_p。8192 回退值本身也是个权衡：

// Codex 请求未携带 max_output_tokens 时仅此回退生效； // 取 8192 是因为过高的默认值会让低上限模型/中转直接 400 且不可重试， // 而 8192 为当前所有 Claude 模型与绝大多数网关接受。 const DEFAULT_CODEX_ANTHROPIC_MAX_TOKENS: u64 = 8192;

默认上限配 high 档推理时，thinking 预算还会被钳到 4096，至少给可见回答留出 4096 的余量——这是回归测试覆盖过的行为。

常见报错速查表

症状	可能原因	处理
上游 401 / 403	`Auth field`与网关要求不匹配；或密钥本身失效、余额不足	在`ANTHROPIC_AUTH_TOKEN (Authorization)`与`ANTHROPIC_API_KEY (x-api-key)`间切换重试（多数网关用默认的 Bearer），并核对密钥
Codex 报 404 / 找不到`/responses`	路由接管没开，或手动把网关地址写进了 Codex 配置	检查`~/.codex/config.toml`当前供应商的`base_url`是否指向`http://127.0.0.1:15721/v1`
路由已开，上游仍 404	`API Request URL`填成了带其他协议路径的地址（如`/chat/completions`）	改回网关服务根地址；路径不常规时用`Full URL`开关直接贴完整 messages 端点
回答经常被截断	8192 回退上限在起作用，表现为回答不完整、`stop_reason=max_tokens`	在供应商表单`Max output tokens`调大（不超过模型/网关真实上限），保存后重试
`/model`不显示 Claude 模型	映射未加条目；或保存后没重启 Codex（目录不热加载）	补上模型映射并重启 Codex。默认模型即使不在映射中，直接请求也仍可用
Web search 不工作	设计如此，本链路不支持	需要联网搜索的任务切回 Responses / Chat 格式的供应商
报错说使用被限制为 Claude Code	供应商侧限定 Claude API 只能给 Claude Code 客户端用	打开`Emulate Claude Code client`尝试；仍被拒说明限制在供应商侧强制执行，需咨询密钥能否在 Claude Code 之外使用

想读源码从这里进

src-tauri/src/proxy/forwarder.rs：转发主流程，codex_responses_to_anthropic分支在此判定并执行路径重写、认证注入、max_tokens回退、[1m]剥离与 beta 头置位。
src-tauri/src/proxy/providers/transform_codex_anthropic.rs：请求体/响应体的双向转换本体（含 SSE），也是 thinking 块编码与effort_to_thinking_budget的所在。
src-tauri/src/proxy/cache_injector.rs：prompt 缓存标记注入器，负责system字符串转数组与断点预算。
src-tauri/src/codex_config.rs：接管 Codex 的配置写入，用toml_edit语法保持地改写config.toml，base_url与wire_api写入当前[model_providers.<current>]段而非顶层。