CC Switch Codex 接 Claude 模型实战：Anthropic Messages 上游本地路由详解

2026-09-06 16:34:02作者：魏侃纯Zoe

A 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

本篇指南面向 CC Switch 3.17.0 及以上版本，讲解如何在不修改 Codex CLI 的前提下，把只暴露 Anthropic Messages 协议（/v1/messages）的 Claude 系中转网关接入 Codex：核心思路是让 Codex 始终请求本机 127.0.0.1:15721 路由，由路由完成 Responses 协议与 Anthropic Messages 协议之间的双向转换。读完本文，你可以独立完成供应商配置、路由接管、认证头选择、推理/工具调用的往返验证，并定位 401/404/截断等典型故障。

为什么需要本地路由

新版 Codex CLI 面向 OpenAI Responses API，而各类 Claude 系中转网关、企业内部网关暴露的是 Anthropic Messages 协议，也就是 /v1/messages。这两种协议的请求体、流式事件和返回结构完全不同：把这类网关的地址直接填进 Codex 配置里，请求打到 /responses 只会得到 404。

这个功能面向「手里只有 /v1/messages 端点」的场景：你有一个 Claude 系中转网关的 Key，想用 Codex 的交互习惯跑 Claude 系列模型；或者公司出于合规策略禁用了 Claude Code 客户端、只保留了经批准的 Claude 系网关——模型本身可用，缺的只是一个被允许的客户端，Codex 正好补上这个位置。

CC Switch 的做法是让 Codex 始终连本机路由，仍以 Responses API 发送请求；路由识别当前供应商是 Anthropic 格式后，把请求转换成 Anthropic Messages 发给上游，再把响应转换回 Responses 形态返回给 Codex。这条链路主要分成四步：

Codex 接管时，本地配置会被写成 http://127.0.0.1:15721/v1，并强制保持 wire_api = "responses"。
供应商的上游格式 anthropic 告诉路由：真实上游说的是 Anthropic Messages 协议。
路由把 /responses 改写到 /v1/messages，并把 Responses 请求体转换成 Anthropic 请求体。
上游返回后，路由再把 Anthropic 的 JSON 或 SSE 转回 Codex 能理解的 Responses JSON/SSE——推理内容、工具调用、图片都在转换范围内。

「上游格式是 anthropic」这一判定并非只看一个字段。从源码 src-tauri/src/proxy/providers/codex.rs 可以看到，codex_provider_uses_anthropic 会依次检查供应商设置里的 apiFormat、元数据中的 api_format，以及 live 配置 TOML 里的 wire_api；is_anthropic_wire_api 认可的取值包括 anthropic、anthropic_messages、anthropic-messages、claude、messages 等多种形式（见 codex.rs L705-L708）。测试用例 test_should_convert_responses_to_anthropic_path_guard（codex.rs L1371 起）则验证了只有当 App 类型是 Codex 且供应商确认为 Anthropic 时，should_convert_codex_responses_to_anthropic 才返回 true，其他 App 或 chat/responses 格式供应商不会误入这条转换路径。

准备工作

你需要先准备好三样东西：

已安装并能启动的 CC Switch（3.17.0 及以上，「Anthropic Messages 上游」自 3.17.0 引入）。
已安装 Codex CLI，并至少运行过一次，让 ~/.codex/ 目录结构存在。
一个能访问 Anthropic Messages 协议端点（/v1/messages）的 API Key——来自某个 Claude 系中转网关，或企业内部的 Claude 网关；端点地址和认证方式以网关文档为准。注意：部分供应商会限制其 Claude API 只能在 Claude Code 中使用，这类 Key 走 Codex 可能会报错，拿不准就先咨询供应商。

Codex 页签目前没有 Anthropic 内置预设，因此走「自定义配置」路径，全程也就四五个字段。

第一步：添加 Codex 供应商

打开 CC Switch，切到顶部的 Codex 标签，点击右上角的加号添加供应商，保持默认的 自定义配置，然后填写：

供应商名称：随意，例如 Claude Gateway。
API Key：你的网关 Key。真实 Key 只保存在 CC Switch 里，由本地路由转发时注入，不会进入 Codex 的 live 配置。
API 请求地址：填网关服务根地址即可，例如 https://claude-gateway.example.com。带不带 /v1 都能被正确处理，路由会自动把请求打到 /v1/messages；不要自己拼 /v1/messages（如果网关文档给的就是完整 messages URL，打开旁边的 完整 URL 开关原样粘贴也可以）。地址栏下方那句「兼容 OpenAI Response 格式」的黄色提示是为 Responses 直连场景写的通用文案，选 Anthropic 格式时按本文填写即可。
默认模型：填网关认识的 Claude 模型 id，例如 claude-sonnet-5，以网关文档给出的模型名为准。

然后展开 高级选项，把 上游格式 从默认的 Responses（原生） 改成 Anthropic Messages（需开启路由）。

选中 Anthropic Messages 后，下方会多出三个配套字段：

认证字段：决定 API Key 以哪个请求头发给上游，两者只发其一，按网关文档选择。
- ANTHROPIC_AUTH_TOKEN（Authorization）：发 Authorization: Bearer <key>，是默认值，多数 Claude 系中转网关用这种。
- ANTHROPIC_API_KEY（x-api-key）：发 x-api-key: <key>，部分沿用 Anthropic 原生请求头约定的网关要求这种。选错通常表现为 401 / 403。
模拟 Claude Code 客户端：默认关闭。仅当网关或其上游限制「只能通过 Claude Code 使用」时才打开，开启后会伪装 User-Agent、anthropic-beta、x-app 请求头，并在系统提示首行注入 Claude Code 身份。普通网关不需要开；开启后仍被拒的处理见「常见问题」。源码注释（src-tauri/src/proxy/forwarder.rs L1443-L1450 附近）明确说明该模拟「默认关闭」，且 Codex/OpenAI 指纹类请求头在这条路径上会被剥离，不会泄漏给 Anthropic 上游。
最大输出 tokens：Anthropic 协议的 max_tokens 是必填项，而 Codex 请求未携带输出上限时，路由按保守的 8192 兜底，长回答或深度思考可能被截断（表现为回复不完整、stop_reason=max_tokens）。遇到截断就在这里按模型真实上限调高，但不要超过——超了上游会直接 400。这个 8192 的兜底常量可以直接在源码中找到：src-tauri/src/proxy/forwarder.rs L1573 定义了 DEFAULT_CODEX_ANTHROPIC_MAX_TOKENS: u64 = 8192，并在 L1574-L1577 作为 responses_request_to_anthropic 的默认参数传入，注释说明「太高的默认值会被上游 400 且不可重试」。

同区的 模型映射 是可选项：把 claude-opus-4-8、claude-sonnet-5、claude-haiku-4-5-20251001 这类模型 id（以你上游认识的名字为准）逐行加进去，CC Switch 会生成模型目录让 Codex 的 /model 菜单能列出它们；不填也能用，Codex 会直接请求默认模型。

保存供应商后，卡片上会出现 需要路由 标记——这类供应商必须在本地路由运行时才能正常工作。

第二步：开启本地路由并接管 Codex

进入设置里的 路由 页面，展开 本地路由，完成两个开关：

打开 路由总开关，启动本地服务（首次开启会弹出一个说明确认框）。默认地址是 127.0.0.1:15721——该端口同样是数据库 schema 的默认值（见 src-tauri/src/database/schema.rs 中 listen_port INTEGER NOT NULL DEFAULT 15721）。
在 路由启用 中打开 Codex。如果只想让 Codex 走路由，可以保持 Claude、Gemini 关闭。

接管后，CC Switch 会把 Codex 的 live 配置指向本机路由（base_url = http://127.0.0.1:15721/v1），auth.json 里只有占位符。真实 Claude Key 仍保存在 CC Switch 的供应商配置里，由本地路由在转发时按你选的认证字段注入。这个改写动作在源码中有专门的函数 apply_codex_official_proxy_route，测试用例（src-tauri/src/codex_config.rs L3411 起）验证了接管后 base_url 被指向 http://127.0.0.1:15721/v1 且 wire_api 保持 responses。

第三步：切换供应商并重启 Codex

回到 Codex 供应商列表，点击 Claude 供应商的 启用。如果路由没有在运行，CC Switch 会提示「此供应商使用 Anthropic Messages 接口格式，需要路由服务才能正常使用，请先启动路由」——回到第二步打开即可。

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

进入 Codex 后可以逐级验证：

配置了模型映射的话，用 /model 查看 Claude 模型是否已出现在菜单里；没配映射时 Codex 直接用默认模型。
发一个小问题，观察设置 → 路由页面的「当前 Provider」从「等待首次请求」变成你的 Claude 供应商、「总请求数」开始增长。
用量看板里，这些请求的模型名会如实显示为 claude-*，可按供应商筛选核对 token 用量。

转换桥的源码级细节

文档层面「双向转换」一句带过，实际实现集中在 src-tauri/src/proxy/providers/transform_codex_anthropic.rs（约 3000 行），值得展开几个关键机制：

推理内容的跨桥往返。 Anthropic 的 thinking block 带签名，Codex 侧的 reasoning.encrypted_content 字段是不透明的加密区。转换桥定义了前缀常量 ccswitch-anthropic-thinking-v1:（transform_codex_anthropic.rs L28），用 URL-safe base64 把签名后的 thinking/redacted_thinking 块编码进 encrypted_content，下一轮工具结果请求时再由 decode_anthropic_thinking_block 解码回放，并通过编码器同一校验逻辑防止无签名块被恶意回放（L92-L99）。同时，Codex 的 reasoning.effort 会被映射成 Anthropic 的 thinking budget：effort_to_thinking_budget（L36-L46）将 minimal/low → 2048、medium → 8192、high → 16384、xhigh/max/ultra → 24576 token；测试（L2364 附近）特意验证了当默认 max_tokens=8192 时高推理档位的 budget 会被钳制，避免思考预算吃掉几乎全部输出上限。

截断如实上报。 Anthropic 的 stop_reason 到 Responses 状态码的映射在 map_anthropic_stop_reason_to_status（L121-L137）：max_tokens 映射为 incomplete + max_output_tokens，refusal 映射为 incomplete + content_filter。也就是说上游停在输出上限或触发安全拒绝时，Codex 看到的是「未完成」而非被伪装的成功——这正是前文建议「调高最大输出 tokens」的底层依据。

提示缓存与用量对账。 转发器在构造 Anthropic 请求体后自动注入 5 分钟提示缓存标记（forwarder.rs L1594-L1603 的 enable... 调用，注释标明无需 beta 头）；响应侧的 build_responses_usage_from_anthropic（transform_codex_anthropic.rs L149 起）负责把 Anthropic 的 usage 换算成 Responses 口径：input_tokens = fresh + cache_read + cache_creation，缓存读/写作为子集单独暴露，供内部计费解析器按不同费率计价。

[1m] 长上下文标记。 默认模型或模型映射里的模型 id 以 [1m] 结尾（如 claude-sonnet-5[1m]）时，forwarder.rs（L1513-L1590 附近）会剥掉该标记并在响应请求中补发对应的 1M 上下文 beta 头，前提是网关支持该能力；注释特别说明 Codex→Anthropic 路径上刻意跳过了通用的 [1m] 剥离逻辑，以保证标记能存活到最终的 Anthropic 请求体。

能力边界与已知限制

提示缓存自动生效：转换桥会按 Anthropic 标准注入 5 分钟提示缓存标记（系统提示、工具定义与对话历史），长对话不会每轮全价重发，无需任何配置。
推理与工具无损：extended thinking 内容跨桥往返保留（见上一节的编码机制），多轮工具调用、图片与 PDF 输入都被完整转换。
支持 [1m] 长上下文标记：默认模型或模型映射里的模型 id 以 [1m] 结尾（如 claude-sonnet-5[1m]）时，路由会剥掉标记并自动补发对应的 1M 上下文 beta 头，前提是网关支持该能力。
联网搜索不可用：Anthropic 上游模式下 Codex 的内置 web_search 会被主动禁用——转换层无法把它翻译给 Anthropic 端点，禁用是为了不给模型呈现一个必然失败的工具。
截断如实上报：上游停在输出上限或流被掐断时，Codex 会看到「未完成」而不是被伪装的成功，方便你察觉并调高最大输出 tokens。

常见问题

上游返回 401 或 403

十有八九是认证字段与网关要求不符：在 ANTHROPIC_AUTH_TOKEN（Authorization） 与 ANTHROPIC_API_KEY（x-api-key） 之间按网关文档换一个再试（多数网关用默认的 Bearer）。另外确认 Key 本身有效、有余额。

Codex 报 404 或找不到 /responses

通常是没有开启 Codex 路由接管，或者你手动把网关的地址直接写给了 Codex——Anthropic 协议的上游没有 /responses 端点，这样一定 404。检查 ~/.codex/config.toml 里当前 provider 的 base_url 是否指向 http://127.0.0.1:15721/v1。

上游返回 404（路由已开启）

检查 API 请求地址：应该是网关的服务根地址，而不是带 /chat/completions 之类其它协议路径的地址。网关路径特殊时，用 完整 URL 开关直接粘贴完整的 messages 端点。

回复经常中途截断

这是默认 8192 输出上限的表现（源码常量 DEFAULT_CODEX_ANTHROPIC_MAX_TOKENS，见前文）。在供应商表单高级选项的 最大输出 tokens 里调高（不要超过模型/网关真实上限），保存后重试。

/model 看不到 Claude 模型

确认模型映射里已添加条目，保存供应商后重启 Codex——模型目录不会被运行中的进程热加载。默认模型不在映射里时菜单不会列出它，但直接请求仍然有效。

联网搜索用不了

设计如此，见「能力边界」。需要联网搜索的任务建议切回 Responses/Chat 格式的供应商。

报错提示只能在 Claude Code 中使用

部分供应商会限制其 Claude API 只能在 Claude Code 客户端中使用，经 Codex 走本文链路时会被拒绝。可以尝试打开高级选项里的 模拟 Claude Code 客户端 开关；若开启后仍然报错，说明限制在供应商服务端，请咨询供应商确认你的 Key 能否在 Claude Code 之外使用。普通网关请保持该开关关闭。