让 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

你手里有一把只能打/v1/messages端点的 Claude 网关密钥，却想用 Codex 的交互方式跑 Claude 模型。直接把网关地址塞进 Codex，只会得到一个对/responses的 404——新版 Codex CLI 只认 OpenAI Responses API，而 Claude 网关讲的是 Anthropic Messages 协议。CC Switch 的本地路由就是来补这个缺口的。

配置完成后你能做什么

一句话：让 Codex 继续说 Responses，由 CC Switch 在本地把请求翻译成 Anthropic Messages 发给上游，再把响应翻译回来。配完之后，你用 Codex 的交互方式跑任意 Claude 模型，推理、多轮工具调用、图片都能无损往返，长对话还自动带上缓存。配好的供应商长这样，卡片右上角挂着"需要路由"标记 📌：

动手前需要准备什么

已安装并能启动 CC Switch（3.17.0 及以上，Anthropic Messages 上游从该版本引入）；
已安装 Codex CLI 并至少跑过一次，让~/.codex/目录结构就位；
一把能访问/v1/messages端点的密钥，来自 Claude 家族中转网关或企业内部 Claude 网关；端点地址和鉴权方式以网关文档为准；
留意：个别供应商把 Claude API 标成"仅限 Claude Code 使用"，这类密钥经 Codex 调用可能报错，拿不准就先问供应商。

完整配置步骤

建一个走路由的 Claude 供应商

切到顶层Codex页签，点右上角加号新增供应商，保持默认的Custom Configuration，只填这几个字段：

Provider Name：随便起，比如Claude Gateway。
API Key：填网关密钥。真密钥只存在 CC Switch 里，转发时由本地路由注入，永远不写进 Codex 的 live 配置（auth.json里只有占位符）。
API Request URL：填网关的服务根地址，例如https://claude-gateway.example.com，带不带尾部/v1都行——路由会自动往/v1/messages打。别自己拼/v1/messages；如果网关文档给的就是完整 messages 地址，打开旁边的Full URL开关原样粘贴。地址栏下那行"compatible with OpenAI Response format"是写给直连 Responses 场景的通用文案，选了 Anthropic 后按这里的填法来即可。
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)发x-api-key: <key>，少数遵循 Anthropic 原生头约定的网关才要。选错通常表现为 401 / 403。
Emulate Claude Code client：默认关。只有当网关或上游把使用限定为"Claude Code 专用"时才开，它会仿造 User-Agent、anthropic-beta、x-app头，并在系统提示第一行注入 Claude Code 身份。普通网关保持关闭即可。
Max output tokens：Anthropic 的max_tokens必填。Codex 请求没带上限时，路由回退到保守的 8192，长回答或深度推理可能被截断（表现为回答不完整、stop_reason=max_tokens）。遇到截断就把它提到模型真实上限——但别超过，否则上游直接 400。
Model Mapping（可选）：每行一个网关能识别的模型 id（如claude-opus-4-8、claude-sonnet-5、claude-haiku-4-5-20251001），CC Switch 据此生成模型目录，让 Codex 的/model菜单能列出来；留空也行，那样 Codex 只用默认模型。

把 Codex 接到本地路由

进设置页Routing页，展开Local Routing，打开两个开关：

打开Routing Master Switch启动本地服务（首次会弹确认框）。默认地址是127.0.0.1:15721，端口可在代理面板里改，与用户手册 4.1一致。
在Routing Enabled下打开Codex。若只想让 Codex 走路由，Claude 和 Gemini 保持关闭即可（多个应用可同时开，见用户手册 4.2）。

接管后，CC Switch 把 Codex 的 live 配置指向本地：base_url = http://127.0.0.1:15721/v1，auth.json只放占位符。真正的 Claude 密钥留在供应商配置里，转发时由本地路由按你选的 Auth field 注入。

启用供应商并验证

回到 Codex 供应商列表，点 Claude 供应商的Enable。如果路由没在跑，CC Switch 会提示这类供应商需要路由服务才能工作，回到上一步打开即可。

切换后重启当前 Codex 终端会话——config.toml和模型目录是进程启动时读的，运行中的进程不保证热加载。进 Codex 后可以这样确认：

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

底层数据流是怎么跑的

把原理单独拎出来看。整个过程可以想象成你请了个翻译官守在门口：Codex 只管说它会的 Responses，翻译官把它翻译成上游听得懂的 Anthropic Messages，再把上游的回话翻译回来。请求进去再返回的完整路径：

Codex ──Responses 请求──▶ 本地路由 127.0.0.1:15721 ──/v1/messages + Anthropic 请求体──▶ 上游 Claude 网关 上游 Claude 网关 ──Anthropic JSON / SSE──▶ 本地路由 ──Responses JSON / SSE──▶ Codex

具体发生的事，按方向拆成三块理解。

入口改写。供应商的anthropic上游格式告诉路由：真实上游说的是 Anthropic Messages。于是路由把/responses重写为/v1/messages，并把整个请求体从 Responses 转成 Anthropic 结构。

出口翻译。上游返回后，Anthropic 的 JSON 或 SSE 被逐段翻回 Responses 结构，推理、工具调用、图片都在这一步还原。有个精巧处理：Anthropic 带签名的 thinking / redacted-thinking 块会被 Base64 编码后藏进 Responses 的reasoning.encrypted_content字段（前缀ccswitch-anthropic-thinking-v1:），这样 Codex 下一轮工具请求能原样回放签名思考块，不丢推理链。

几个自动兜底。

Prompt 缓存自动注入标准 5 分钟标记，覆盖系统提示、工具定义、对话历史，长对话不会每轮全价重发。
max_tokens 回退：请求没带上限时落到默认 8192；供应商层配的Max output tokens优先级更高，会先覆盖请求体再算 thinking 预算。
[1m]长上下文标记：模型 id 以[1m]结尾（如claude-sonnet-5[1m]）时，路由剥离该后缀并自动加上 1M 上下文 beta 头（context-1m-2025-08-07），前提是网关支持；因为上游回写可能重新带上[1m]，最终请求体上还会再剥一次。
Web search 被禁用：转换层没法为 Anthropic 端点翻译这个工具，留着只会让模型看见一个必失败的工具。

Codex 的reasoning.effort会被映射成 Anthropic thinking 的 token 预算：

Codex effort	thinking 预算
minimal / low	2048
medium	8192
high	16384
xhigh / max / ultra	24576

未识别的值不启用 extended thinking，避免误吞 temperature / top_p。默认 8192 上限配 high 档位时，预算还会被钳到至少给可见回答留出 4096 余量。

常见问题排查

上游返回 401 / 403

现象：转发后上游直接拒绝。
原因：Auth field 与网关要求不匹配，或密钥本身失效、无余额。
解法：在Authorization (Bearer)与x-api-key间切换重试（多数网关用默认的 Bearer），同时确认密钥有效且有余额。

Codex 报 404 或找不到/responses

现象：请求打出去就 404。
原因：路由没接管，或手动把网关地址写进了 Codex——Anthropic 协议的上游根本没有/responses端点。
解法：检查~/.codex/config.toml中当前供应商的base_url是否指向http://127.0.0.1:15721/v1。

路由已开，上游仍 404

现象：接管正常，但请求打到错误路径。
原因：API Request URL 填成了带其他协议路径的地址（如/chat/completions），而非服务根。
解法：改填服务根地址；网关路径不常规时，用Full URL开关直接粘贴完整 messages 端点。

回答经常被截断

现象：回答不完整、stop_reason=max_tokens。
原因：默认 8192 输出上限生效。
解法：在 Advanced Options 的Max output tokens调大，别超过模型/网关真实上限，保存后重试。

/model不显示 Claude 模型

现象：菜单里找不到配的 Claude 模型。
原因：没加模型映射，或加完没重启 Codex（目录不热加载）。
解法：补上模型映射条目并重启 Codex；默认模型不在映射里时菜单不列它，但直接请求仍可用。

Web search 不工作

现象：联网搜索类任务失败。
原因：设计如此，Anthropic 上游模式下内置web_search被刻意禁用。
解法：需要联网搜索时，切回 Responses / Chat 格式的供应商。

报错说使用被限制为 Claude Code

现象：转发后被网关拒绝，提示仅限 Claude Code。
原因：部分供应商把 Claude API 限定给 Claude Code 客户端。
解法：打开 Advanced Options 的Emulate Claude Code client再试；仍报错说明限制在供应商侧强制执行，去咨询供应商你的密钥能否在 Claude Code 之外使用。普通网关保持该开关关闭。

功能边界与适用场景

Web search 不可用：Anthropic 上游模式下被禁用，需要联网搜索的场景请切回 Responses / Chat 供应商。
"仅限 Claude Code"的密钥：供应商侧强制执行限定的密钥，即使开了模拟客户端也可能被拒，能否在 Claude Code 之外使用以供应商答复为准。
[1m]长上下文：需网关本身支持对应 beta 能力，否则该标记无意义。
合规：在"公司禁用客户端但保留网关"的场景用之前，先确认这符合所在组织的具体政策——被禁的到底是特定客户端还是某种使用方式，各地不同。走第三方中转网关时，也请阅读目标网关在计费、合规与数据留存方面的条款。

延伸资料与源码入口

用户手册：Proxy Service、App Routing
发布说明：v3.17.0
官方指南：Codex 经 Claude 上游路由
核心转换实现：transform_codex_anthropic.rs
转发入口与 max_tokens / 缓存 /[1m]处理：forwarder.rs
Codex 配置写入（wire_api = "responses"保留）：codex_config.rs

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析