如何用 CC Switch 在 Codex 中使用 Claude 系网关（Anthropic Messages）模型-编程实验室

如何用 CC Switch 在 Codex 中使用 Claude 系网关（Anthropic Messages）模型

【免费下载链接】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

手里的 Claude 系中转网关或企业内部 Claude 网关只暴露 Anthropic Messages 协议端点（/v1/messages），而你希望用 Codex CLI 的交互习惯跑 Claude 系列模型——比如公司禁用了 Claude Code 客户端、只保留了经批准的 Claude 系网关，模型本身可用，缺的只是一个被允许的客户端。直接把这类网关地址填进 Codex 配置是不行的：新版 Codex CLI 面向 OpenAI Responses API，请求/responses在 Anthropic 协议的上游只会 404。CC Switch（3.17.0 及以上）的本地路由解决的就是这个问题：Codex 始终连本机路由、仍以 Responses 格式发请求，路由识别上游是 Anthropic 格式后，把请求改写并转换成/v1/messages发出去，再把响应转回 Responses 形态返回给 Codex。本文演示这条链路的完整配置与验证路径。

原理：本地路由在中间做了什么

这条链路分成四步：

Codex 接管时，本地配置被写成base_url = "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——推理内容、工具调用、图片都在转换范围内。

接管前后 Codex 配置的差异如下（文档示例，来自用户手册）：

# 路由前 base_url = "https://api.openai.com/v1" # 路由后 base_url = "http://127.0.0.1:15721/v1"

接管后auth.json里只有占位符，真实 Claude Key 仍保存在 CC Switch 的供应商配置里，由本地路由在转发时按你选的认证字段注入。关闭路由时，CC Switch 会把 Codex 配置恢复到路由前的状态并保存请求日志，开启前还会备份原始配置。

准备条件

开始之前需要三样东西：

已安装并能启动的 CC Switch，版本 3.17.0 及以上（「Anthropic Messages 上游」自 3.17.0 引入）；
已安装 Codex CLI，并且至少运行过一次，让~/.codex/目录结构存在；
一个能访问/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 身份。普通网关不需要开。
最大输出 tokens：Anthropic 协议的max_tokens是必填项，而 Codex 请求未携带输出上限时，路由按保守的 8192 兜底，长回答或深度思考可能被截断（表现为回复不完整、stop_reason=max_tokens）。遇到截断就在这里按模型真实上限调高，但不要超过——超了上游会直接 400。

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

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

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

协议转换依赖路由服务，所以先启动路由，再开启应用接管。进入 CC Switch 设置里的路由页面，展开本地路由，完成两个开关：

打开路由总开关，启动本地服务（首次开启会弹出一个说明确认框）。默认地址是127.0.0.1:15721；监听地址与端口在代理服务设置里可改，但修改前必须先停止代理，保存后重新启动。
在路由启用中打开Codex。如果只想让 Codex 走路由，可以保持 Claude、Gemini 关闭。

接管后，CC Switch 会把 Codex 的 live 配置指向本机路由，auth.json里只有占位符；真实 Key 仍由路由按认证字段配置注入。

第三步：启用供应商并重启 Codex

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

切换后建议重启当前 Codex 终端会话：config.toml和模型目录是 Codex 进程启动时读取的，运行中的进程不保证热加载。用户手册提到路由模式下切换供应商即时生效、无需重启 CLI，但那描述的是路由已接管状态下的供应商间切换；首次接管、或模型目录发生变化时，按路由攻略的建议重启一次更稳妥。

验证是否生效

进入 Codex 后可以逐级验证：

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

能力边界与已知限制

提示缓存自动生效：转换桥会按 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 输出上限的表现。在供应商表单高级选项的最大输出 tokens里调高（不要超过模型/网关真实上限），保存后重试。

/model看不到 Claude 模型

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

联网搜索用不了

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

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

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