Claude Code 接入 Codex：协议转换与多模型切换实操指南

1. 理解“Claude Code 里调用 Codex”这件事的本质

最近我在终端里最常用的两个命令行 AI 工具，一个是 Claude Code，一个是 Codex CLI。本来它们各自跑各自的，互不相干：Claude Code 负责长对话和仓库级改动，Codex CLI 负责一些需要快速出结果的编码任务。直到我试了 CC Switch 这类配置工具，发现 Claude Code 的请求其实可以被后台切到 Codex 的端点——也就是说，你继续在 Claude Code 的对话框里写任务，但真正干活的模型可能是 OpenAI 的 Codex。

先别急着往下配，我建议花两分钟搞清楚“这到底是怎么接上的”。因为很多人配置失败，不是操作不对，而是对协议层完全没概念。

1.1 两种 CLI 各司其职，但协议完全不同

Claude Code 是 Anthropic 的官方命令行编程助手，它原生走的是 Anthropic Messages API，核心端点是POST /v1/messages，请求体里带的是system、messages、tools这些字段，工具调用的结构用的是 Anthropic 自己那套格式。

Codex 是 OpenAI 的命令行编程工具，底层走的是 Responses API，核心端点是POST /v1/responses（有些供应商也写成/responses），请求体结构和 Anthropic 完全不同，工具调用协议也是另一套格式。

这两套协议就像插座和插头不匹配：Claude Code 这个插头，直接插不进 Codex 的插座。所以“Claude Code 里调用 Codex”这句话，本质上不是在 Claude Code 里装一个 Codex 插件，而是需要一个中间层，把 Anthropic 协议请求转写成 Codex 协议请求，再转发过去。

这就是 CC Switch 这类工具存在的理由。

1.2 CC Switch 在中间做了什么

CC Switch 会在本机启动一个监听127.0.0.1的小服务，然后修改 Claude Code 的配置，把ANTHROPIC_BASE_URL指向本地这个端口。当你在 Claude Code 里输入任务时，请求先到本地服务，由它做两件事：

1. 把 Anthropic 协议的请求改写成目标供应商需要的协议格式；
2. 带着你配置的 API Key，转发到目标供应商的真实端点。

反过来，目标供应商返回的响应，也会被它转回 Anthropic 格式，Claude Code 才能正常渲染。

所以从 Claude Code 的视角看，它只是在跟一个“Anthropic 兼容端点”通信；从 Codex 后端的视角看，它只是在接收一个“正常客户端”的请求。中间那个转发服务承担了协议翻译的角色。

这个设计其实挺好的。它意味着你换模型后端时，完全不用改 Claude Code 的交互习惯、对话历史管理、工具调用方式，所有前端体验保持不变，只是背后的“大脑”换了。

1.3 哪种场景值得这么接

我在实测之后，觉得这种接法主要适合三类人：

• 想体验 Codex 模型，但不想离开 Claude Code 的交互界面。Claude Code 的会话管理、子代理、上下文概览做得确实舒服，而 Codex 的模型在处理某些编码任务时逻辑又很清晰，两边优点都想要，那就接。
• 手上已经有多个不同供应商的 API Key，想统一在一个终端界面里调用。这也是 CC Switch 支持 DeepSeek、Qwen、GLM 这些模型的原因，切换供应商只是几秒钟的事。
• 有 Claude Code 使用习惯，但希望用 API Key 直连第三方模型，不依赖官方账号登录。通过配置ANTHROPIC_BASE_URL和 API Key，Claude Code 启动后不强制走官方 OAuth 流程，这也是社区里很常见的一种接法。

当然，也要说实话：这种接法并不适合所有人。如果你需要用到 Claude 官方特有的长上下文、Artifacts 或某些最新模型能力，那还是留在官方端点更稳。协议转换层再成熟，也做不到 100% 还原所有特性。

2. 动手之前：两个 CLI 与一个切换器的正确安装姿势

配置出问题，很大一部分原因是环境本身就没装干净。我建议按下面的顺序把基础打好，不要跳步。

2.1 安装 Claude Code 并确认版本

Claude Code 最主流的安装方式还是 npm 全局安装：

npm install -g @anthropic-ai/claude-code

装完以后确认一下版本：

claude --version

如果之前装过旧版本，建议先更新到最新版。社区里很多奇怪的报错，其实在旧版本上压根不会出现，新版早就修了。更新命令：

npm update -g @anthropic-ai/claude-code

然后在项目目录里跑一次claude，完成首次初始化。这一步会生成~/.claude/目录和项目级配置，后续 CC Switch 会去读写这些配置。

如果你平时在 VSCode 里用 Claude Code 插件，也一样。VSCode 插件本质上调用的是本机的claude客户端和环境变量配置，插件本身不做独立的网络请求，所以本机配置改好了，VSCode 里同样生效。

注意：首次启动 Claude Code 时，官方会建议你登录账号。这一步可以先登录，也可以用 API Key 走第三方端点之后再启动。两种方式不冲突，后面切换端点时 CC Switch 会覆盖相关配置。

2.2 安装 Codex CLI 并完成认证

Codex CLI 同样有 npm 安装方式：

npm install -g @openai/codex

装完后终端直接输codex就能进入交互界面。首次使用会有初始化引导，主要做两件事：选择认证方式、确认模型配置。

认证方式一般有两种：一种是登录 ChatGPT 账号走订阅认证，另一种是直接用 OpenAI 的 API Key。如果你打算在 CC Switch 里配置 Codex 供应商，建议直接用 API Key 方式，方便后续复制到 CC Switch 里用。

装完以后先单独跑一次codex，确认它可以正常完成任务。这是因为我们后面做排查时需要区分“问题是出在 Codex 服务本身，还是出在 Claude Code 到 Codex 的转发链路”。如果 Codex CLI 本身都跑不通，那就先别接 Claude Code。

Codex CLI 的配置文件在~/.codex/config.toml，字段大致长这样：

model = "gpt-5-codex" model_provider = "openai" [model_providers.openai] name = "OpenAI" base_url = "https://api.openai.com/v1" env_key = "OPENAI_API_KEY" wire_api = "responses"

字段名和模型名可能随版本变化，以你本机实际生成的为准。但核心结构就是：指定默认模型名，指定供应商，指定 base_url、环境变量名和接口类型。

2.3 安装 CC Switch 并核对本地端口

CC Switch 是一个开源配置切换工具，官方仓库里有各平台的安装包。装完之后它是一个桌面小窗口，里面列出各种模型供应商。选一个你需要的，填入 API Key 和端点信息，点一下开关，它就会把本机 Claude Code 的配置改掉，并在本地起一个转发服务。

这里有个关键点值得说一下：这个本地服务的默认端口是固定的（常见的是8787，不同版本可能不同）。如果你本机的端口被别的程序占用，CC Switch 的转发服务会启动失败，对应的现象就是 Claude Code 一启动就报连不上端点。所以装完 CC Switch 后，先检查一下端口状态：

lsof -i :8787

如果端口被占用，可以在 CC Switch 的设置里换一个高位端口，或者先把占用端口的进程处理掉。

2.4 验证原始链路：curl 直接请求端点

这一步很多人会跳过，但恰恰是排查利器。在你配置任何东西之前，先用 curl 直接访问目标端点的根路径或一个最简单的请求，确认这个端点本身是可用的。比如用 Codex 官方端点时：

curl https://api.openai.com/v1/responses \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "gpt-5-codex", "input": "hi" }'

如果这个请求能够正常返回，说明 API Key 有效、模型名有效、端点路径正确。那么后续所有问题都可以锁定在“本机转发链路或配置切换”上。

如果你的供应商是 DeepSeek、Qwen 这类第三方，同样先把 base_url 换成对应服务的地址试一遍。这一步花不了两分钟，却能帮你省下后面两个小时。

3. 核心配置：把 Codex 端点接进 Claude Code 的两条路

环境准备好以后，就到了正式对接环节。我实测下来有两条路：用 CC Switch 的图形界面，或者手动改配置。两条路各有适用场景，下面都展开说。

3.1 方案一：用 CC Switch 图形化配置

这是大多数人首选的方案，操作步骤很简单：

1. 打开 CC Switch，找到供应商列表；
2. 选择或新建“OpenAI / Codex”类型的供应商；
3. 在配置里填入 Base URL，一般填的是https://api.openai.com/v1；
4. 填入 API Key；
5. 填默认模型名，比如gpt-5-codex；
6. 点击切换按钮，让 CC Switch 把配置写入 Claude Code 本地设置。

切换完成后，CC Switch 会提示本地转发服务已启动。这个时候重新打开 Claude Code，输入/status查看当前端点，如果显示的是http://127.0.0.1:8787之类，说明配置已经生效。

这里有一个容易踩的坑：Base URL 是否带/v1后缀，不同版本要求不一样。有的供应商要求填https://api.openai.com/v1，有的要求填到根域。填错了，报错信息往往很隐晦——不是“404”，而是类似协议解析失败、模型不存在的奇怪提示。

我的建议是按照 CC Switch 界面里的“默认值”填，不要自己凭感觉删减路径。如果你不确定，先填上，跑一次，报错再调整。

切换成功之后，在 Claude Code 里随便问一个编码问题，正常情况下模型会在你本机执行命令、读写文件，整个交互和官方版几乎没区别。

3.2 方案二：手动配置的可行性与边界

手动配置有两种姿势，但需要注意边界。

第一种姿势：直接设置环境变量，指向一个本身就是 Anthropic 兼容协议的端点。也就是说，如果某个供应商/网关服务提供了兼容 Anthropic Messages API 的端点，那么你只需要：

export ANTHROPIC_BASE_URL="https://your-llm-gateway.example.com" export ANTHROPIC_API_KEY="sk-xxxx"

然后正常启动 Claude Code 即可。这种姿势不需要 CC Switch，因为目标端点本身就“说” Anthropic 的语言。

第二种姿势：目标是 OpenAI 兼容协议端点，那就不能只靠环境变量了。很多人不知道这点，把ANTHROPIC_BASE_URL直接指向https://api.openai.com/v1，结果 Claude Code 拿 Anthropic 协议去请求 OpenAI 端点，返回的要么是 404，要么是路由不匹配。这就像你把一个英标插头直接往欧标插座里怼，物理上不匹配。

所以，如果你想对接 OpenAI 官方 Codex、DeepSeek、Qwen 这些 OpenAI 兼容端点，就老老实实让 CC Switch 这类工具来做协议转换，不要试图通过手动改环境变量绕过中间层。除非你自己能写一个请求转换服务，否则这条路不通。

3.3 切换后的冒烟测试清单

配置完成后，不要急着开始干重活。我建议按下面这个清单做一遍冒烟测试：

1. 启动测试：进入 Claude Code，确认没有报连接错误；
2. 基础对话：问一个简单问题，确认模型有正常响应；
3. 工具调用：让它“读取当前目录的文件列表”，确认工具调用链路正常；
4. 执行命令：让它“运行date命令”，确认终端命令执行权限正常；
5. 长对话：连续追问几个相关问题，确认历史上下文没有被截断或错乱；
6. 切换回归：用 CC Switch 切回官方端点，再启动一次 Claude Code，确认官方链路也正常。

第 6 步很多人会忽略，但其实很重要。切换工具最怕的就是改坏了配置后回不去。我建议每次切换后，都把当前可用状态记下来；如果 CC Switch 支持配置导出，就导出一份备份。

4. 高频报错排查：从 “local proxy failed” 到 “model not supported”

配置这类工具链，不怕出问题，就怕出了问题不知道往哪个方向查。我把这几天遇到的报错和排查链路完整还原出来，你按这个顺序走，大概率能自己解决。

4.1 报错定位：区分本地问题还是远端问题

先说一个最常见的报错，错误信息大致长这样：

cc switch local proxy failed while handling codex endpoint /responses. provider ...

第一次看到这个报错，很容易慌，因为信息太短，完全不知道是哪里出了问题。但你要冷静下来想一个关键问题：这个错误是本地转发服务抛出来的，不是 Codex 远端返回给它的。

“local proxy failed”意思是：CC Switch 这个本地服务，在处理发往 Codex 端点的/responses路由时，自己挂了或判断出错了。也就是说，故障点大概率在本地配置，而不是 Codex 服务本身。

排查的第一步，是先确认远端服务是否正常。用我前面说的 curl 方法直接请求一次目标端点。如果 curl 能通，那就说明问题在本地。

4.2 排查链路第一步：检查端点地址和路由拼接

本地转发服务要正常工作，它得知道 Codex 端点到底在哪。如果你在 CC Switch 里填的 Base URL 不完整，比如漏了/v1，或者多填了/v1/v1，转发服务拼接出来的路径就会是错的，然后它就会抛出 “failed while handling codex endpoint” 这类错误。

具体检查方式：

1. 打开 CC Switch 的供应商配置，确认 Base URL 和供应商文档一致；
2. 看看错误信息里的路径是/v1/responses还是/responses，确认你填的 Base URL 是根域还是带/v1；
3. 如果你填的是https://api.openai.com/v1，最终拼接出的路径应该是/v1/responses，多一层少一层都不行。

这种路径拼接问题，在 macOS 和 Linux 上表现可能还不一样，因为环境变量的覆盖顺序不同。我建议把 CC Switch 配置里的 URL 拿出来，手动拼一遍目标路径，再用 curl 验证。

4.3 排查链路第二步：检查模型标识是否被支持

另一个高频报错长这样：

the 'gpt-5.6-sol' model is not supported when using codex with a ...

这个报错就比较直接了：你配置的模型名不在供应商支持列表里。最常见的原因是别人在社交平台分享了一个“新模型名”，你拿来就填上去了，但实际上该模型在当前端点并不存在，或者只有特定账号权限才能用。

遇到这类报错，不要硬猜模型名，去对应供应商的官方文档查当前支持的模型列表。即使你看到某个模型名确实存在，也要确认它是否支持你选的接口类型（是responses还是chat/completions）。模型名写错，转发服务本身没问题，但远端会拒绝请求，最终也会表现为“处理失败”。

4.4 排查链路第三步：认证信息是否完整传递

如果端点地址和模型名都没问题，那就要查认证信息。

CC Switch 在转发请求时，会把 API Key 放到请求头里。如果你的 Key 填错、填了已过期的 Key、或者 Key 对应的账号权限不足以访问某个模型，远端会返回 401/403。但很多时候，转发服务不会把原始错误原封不动抛给你，而是打包成一句“local proxy failed”，这就很误导人。

验证方法依然是用 curl：用同一个 API Key 直接请求目标端点。如果 curl 返回 401/403，那就是 Key 的问题，去换一个有效 Key 即可；如果 curl 正常，那才是转发服务在请求头处理上出了问题，检查 CC Switch 是否把环境变量读对了。

4.5 一个完整排查过程的还原

我举一个真实例子。有一回我切换 Codex 后，Claude Code 里输任何内容都报错，提示就是 “local proxy failed while handling codex endpoint /responses”。

我的排查顺序是这样的：

先 curl 请求https://api.openai.com/v1/responses，用同一个 Key，模型名填配置里那个，结果返回 200，说明远端没问题。

然后我打开 CC Switch，看到 Base URL 里填的是https://api.openai.com/，没有/v1。而 Codex 端点实际路径是/v1/responses，默认拼接出来就成了/responses，路由自然对不上。

我把 Base URL 改成https://api.openai.com/v1，重新切换，再试，问题消失。

这个例子想说明的是：报错信息里的 “/responses” 并不一定是真正的问题，它更像是转发服务在“挂掉之前最后想访问的地方”。真正的问题往往在前面一层——端点路径拼接、协议转换、认证传递。排查时一定要从远端往回推，先确认远端可用，再查本地配置。

5. 进阶玩法：一个界面轮换 Codex、DeepSeek、Qwen、GLM

配置打通之后，你会发现最爽的不是“Claude Code 用了 Codex”，而是“一套界面，想切谁就切谁”。

5.1 多供应商配置的一键切换

CC Switch 支持同时维护多套供应商配置。我目前维护了五套：

• Anthropic 官方（Claude 系列）
• OpenAI Codex（官方端点）
• DeepSeek（API 兼容端点）
• Qwen（阿里云百炼兼容端点）
• GLM（智谱开放平台兼容端点）

日常使用中，切供应商只需要在 CC Switch 界面里换一下。切完之后重启 Claude Code（或者直接开一个新会话），就能用上新的模型后端。

这种多供应商模式的真正价值在于：不同模型擅长的任务不一样。比如我在做架构设计时优先用 Claude 系列，写算法题时切到 Codex，做中文内容总结时用 DeepSeek 或 Qwen，跑特定格式输出时用 GLM。以前这些模型散落在不同的工具或网页里，现在全部集中在 Claude Code 这一个界面里。

5.2 协议转换带来的能力折损

不过要有个清醒的认知：协议转换层不是万能的，它会带来能力折损。

Claude Code 对 Anthropic 协议的理解是最深的。当接入 OpenAI 兼容端点时，虽然基本的对话和工具调用都能正常工作，但一些深度依赖 Anthropic 协议的特性支持的没那么好。比如：

• 某些高级工具调用的嵌套写法，OpenAI 兼容端点解析不了；
• 长上下文管理策略，两边协议差别较大，切换后对话长度上限可能下降；
• 部分模型供应商返回的流式格式不标准，可能导致 Claude Code 渲染异常。

我实测下来的体感是：普通对话、代码编写、文件操作这些常用场景，切换后几乎无感；但复杂的多子代理协作、超长上下文总结这类重型任务，建议还是用模型本身的原生端点或官方端点。

下面这个表格是我根据实际使用整理的，仅供参考：

供应商	端点类型	主要优势	切换后的实测表现
Anthropic 官方	Anthropic 原生	与 Claude Code 契合度最高	满血，所有特性可用
OpenAI Codex	OpenAI Responses	编码逻辑清晰，适合算法实现	基本流畅，个别工具嵌套会简化处理
DeepSeek	OpenAI 兼容	中文理解好，性价比高	常用功能正常，长对话偶尔有延迟
Qwen	OpenAI 兼容	中文生成质量高，API 稳定	正常，代码类工具有小概率格式异常
GLM	OpenAI 兼容	结构化输出不错	正常，复杂工具调用建议简化写法

5.3 不开 Claude 账号直接用第三方模型的注意事项

最后说一个大家很关心的话题：能不能不登录 Claude 账号，直接用 Claude Code 界面配第三方模型？

答案是能。操作上其实很简单：在启动 Claude Code 之前，设置好ANTHROPIC_BASE_URL指向本地 CC Switch 端口，同时给ANTHROPIC_API_KEY填入一个非空值（比如第三方供应商的 Key）。Claude Code 检测到自定义端点和 Key 后，不会强制要求走官方 OAuth 登录流程。

这种玩法虽然方便，但有几个注意事项：

1. API Key 的权限要搞清楚：第三方供应商的 Key 能调用哪些模型，要在供应商控制台看明白，填了没权限的模型会一直报错。
2. 不要直接在团队共享环境里这么配：团队项目里直接改环境变量，会影响别人。要用就在个人环境里用，或者通过项目中.claude/settings.json的env字段单独配置。
3. 配置好后要测试回切：这种“不登录 + 第三方端点”的状态，切回官方端点时偶尔会出现 token 缓存问题。我遇到过切回官方后 Claude Code 仍显示匿名模式的情况，重启一次就好了。

我现在的习惯是：每套供应商配置旁边都会留一份 curl 探活脚本和一个配置快照。每次切换前先探活，切换后记录状态，出问题时能在五分钟内回滚。这套流程跑顺以后，Claude Code 对我来说就不再是“Claude 专用工具”了，它成了一个统一的终端 AI 工作台——背后接 Codex、DeepSeek、Qwen、GLM 都行。