Codex 和 Claude Code 是目前最常用的两款终端编程助手，分别来自 OpenAI 和 Anthropic。很多人装好之后的第一件事，就是把默认模型换成第三方平台：要么官方额度不够用，要么团队已经在用 DeepSeek、智谱、Kimi、通义这些平台的 API，不想再单独开一套订阅。opencodex 这个词最近被说得很多，它并不是某个官方组件的名字，而是社区把“Codex 和 Claude Code 接入第三方模型”这件事沉淀下来的配置方案和工具集合。这篇记录就按我实际跑过的顺序，讲清楚两条接入路线、桌面端报错怎么处理，以及 ccswitch 这类切换工具的关键参数。
先给结论：如果只用终端，Codex 系优先改~/.codex/config.toml，Claude Code 系优先改环境变量；如果用的是 Codex 桌面端，或者想保持界面里的模型名不变，那就需要借助 ccswitch 这类本地转发方案。下面从判断路线开始拆。
1. 先判断路线：Codex 走 provider 配置，Claude Code 走环境变量
很多教程一上来就让人改配置，结果越改越乱。原因是 Codex 和 Claude Code 的接口协议不一样，接入方式不能混着用。
1.1 两边握手协议不同，别把配置方式混着用
Codex 是 OpenAI 的产品线，底层默认走 OpenAI 的 Responses API 或 Chat Completions。市面上很多第三方平台都宣称自己兼容 OpenAI 接口，所以 Codex 接入第三方模型时，核心思路是给它指定一个新的base_url，再告诉它这个平台的协议是chat还是responses。
Claude Code 是 Anthropic 的产品线，默认走 Anthropic Messages API。第三方平台如果想给 Claude Code 用，要么本身提供 Anthropic 兼容端点，要么需要通过一个本地转发层把请求格式翻译过去。这不是改一个环境变量就能解决的，需要先确认平台到底兼容哪种协议。
所以开写配置之前，先回答一个问题：你的第三方平台给你的是哪种 endpoint？如果平台文档里写的是“OpenAI 兼容”，那接 Codex 更容易；如果写的是“Anthropic 兼容”，那接 Claude Code 更容易。两边都只写“兼容”的，就要做好格式翻译的准备。
1.2 两条路线怎么选
实际使用中就两条路：
- 直接改官方 CLI 的配置。Codex 改
~/.codex/config.toml，Claude Code 改环境变量。优点是简单、可控、没有额外进程；缺点是 Codex 桌面端不一定听配置文件的，Claude Code 如果遇到只支持 OpenAI 接口的平台，也会被卡住。 - 用本地切换工具。ccswitch、opencodex 这类方案，思路是在本地起一个转发服务，客户端只管连接这个服务，服务再把请求转到你指定的第三方平台。优点是 UI 不用换模型名，桌面端也能用；缺点是多了一个服务进程，多了一层排错点。
我的建议是：学习阶段先用第一种，跑通了单条请求，再决定要不要上第二种。不要一上来就装一堆工具，最后连报错都分不清是哪个环节出的。
2. 环境准备：装 CLI，准备第三方模型参数
无论走哪条路线，都要先保证 CLI 本身能跑。很多报错根本不是第三方模型的问题，而是 CLI 没装好、路径不对、Node 版本太老。
2.1 安装 Codex CLI
Codex CLI 最常见的安装方式是通过 npm：
npm install -g @openai/codex codex --version如果你电脑里有 Homebrew，也可以用 brew 安装，具体以官方 README 为准。装完之后先别急着配模型，先跑一下codex --version，能输出版本号说明 CLI 本身没问题。
如果codex命令找不到，优先检查 npm 的全局目录是否在 PATH 里：
npm config get prefix这个命令会输出一个目录，比如/usr/local或C:\Users\你的用户名\AppData\Roaming\npm，把里面的 bin 或 npm 目录加进 PATH 再试。
2.2 安装 Claude Code
Claude Code 同样通过 npm 安装：
npm install -g @anthropic-ai/claude-code claude --version安装后在终端里输入claude就能进入交互界面。如果 Windows 终端报“claude 不是内部或外部命令”，原因基本一样：npm 全局目录不在 PATH 里。这个我在后面单独讲。
有一个容易忽略的点：CLI 会更新得比较快，不同版本的参数解析可能有差异。如果你照着某篇老教程改了配置没生效，先npm update -g @openai/codex或更新 Claude Code，再重新看报错。
2.3 第三方模型的四个必要参数
不管用哪个平台，都要先准备四个参数，缺一个都会卡住：
| 参数 | 含义 | 示例 |
|---|---|---|
| base_url | 平台提供给 API 的基础地址 | https://api.deepseek.com/v1 |
| API key | 身份凭证 | sk-xxxx |
| 模型标识 | 平台真实的模型 ID | deepseek-chat、glm-4-plus、qwen-max |
| 协议类型 | 平台兼容 OpenAI 还是 Anthropic | chat、responses或messages |
注意：模型标识不是你在网页版聊天时看到的名字，而是 API 文档里的 model 字段。很多报错都出在这里，比如你把页面上的“DeepSeek Chat”写成了带空格的名称，接口当然认不出来。
3. Codex CLI 接入第三方模型：config.toml 一步步配通
Codex CLI 的配置逻辑比较集中，大部分情况下只需要改一个文件。
3.1 先找到配置目录，避免改错文件
Codex 的配置目录在用户主目录下：
- macOS / Linux：
~/.codex/ - Windows：
C:\Users\你的用户名\.codex\
目录下常见两个文件：config.toml和auth.json。config.toml里保存模型、provider、代理转发等配置；auth.json里保存登录凭证和 key。后面这个文件不要提交到代码仓库，也不要截图分享。
第一次运行时如果没有config.toml，可以先手动建一个，或者用codex跑一次让它自动生成，然后再编辑。
3.2 自定义 provider 的常见写法
以下是一份常见的第三方 provider 配置示例，以 DeepSeek 为例：
model_provider = "deepseek" model = "deepseek/deepseek-chat" [model_providers.deepseek] name = "DeepSeek" base_url = "https://api.deepseek.com/v1" env_key = "DEEPSEEK_API_KEY" wire_api = "chat"字段含义：
model_provider：告诉 Codex 用哪个自定义 provider。model：格式是“provider 名称/模型标识”。base_url：第三方平台的 API 基础地址，具体以平台文档为准，有的以/v1结尾，有的不以。env_key：Codex 会从这个环境变量里读取 API key，而不是把 key 直接写死在配置里。wire_api：请求协议。OpenAI 官方默认可能是responses，但很多第三方平台只支持chat格式，所以这里要先改成chat。
然后设置环境变量：
export DEEPSEEK_API_KEY="sk-你的key" codex如果你的 key 是别的名称，把env_key改成对应的环境变量名就行。
3.3 单条验证通过后再进入复杂任务
配置完之后，不要直接丢一个大型重构任务进去。先用最简单的非交互命令验证：
codex exec "用一句话解释什么是数据库索引"能正常返回结果，说明 base_url、key、模型标识、协议类型都对了。如果报错，按顺序检查：
- 是否 401：key 错了，或者环境变量名和
env_key不一致。 - 是否 404：base_url 不对，可能少了版本前缀。
- 是否提示模型不支持：模型标识不是平台真实 ID，或者平台不支持
responses协议。 - 是否超时：第三方平台响应慢，或者网络到平台本身就不稳。
单条能跑通，再去试带工具调用的任务，比如让 Codex 自己查目录、改文件。因为有些第三方模型虽然聊天能用，但工具调用格式不支持，会表现为“看起来在思考，实际不执行”。
4. Claude Code 接入第三方模型：环境变量和启动脚本
Claude Code 的配置方式和 Codex 完全不同，核心是环境变量。
4.1 三个核心环境变量
在启动claude之前，设置以下环境变量：
export ANTHROPIC_BASE_URL="https://your-provider.example.com" export ANTHROPIC_AUTH_TOKEN="sk-你的key" export ANTHROPIC_MODEL="deepseek-chat"含义分别是：
ANTHROPIC_BASE_URL：第三方平台提供的 Anthropic 兼容地址。Claude Code 会在这个基础地址上拼/v1/messages请求。ANTHROPIC_AUTH_TOKEN：第三方平台给你的 key。Claude Code 会把它当作访问凭证带在请求头里。ANTHROPIC_MODEL：指定实际使用的模型标识。如果不设置，可能默认用 Anthropic 官方模型名，第三方平台不认识就直接报错。
有些场景超时时间也需要调大：
export API_TIMEOUT_MS=300000这个变量控制 Claude Code 请求的超时时间，单位是毫秒。第三方模型如果推理慢，默认超时可能不够。
再说一个关键边界：如果第三方平台只有 OpenAI 兼容接口，没有 Anthropic 兼容接口，那直接设置这三个环境变量是不够的。因为协议格式不同，需要本地转发层把请求从 Anthropic 格式转成 OpenAI 格式。这种情况下别硬调环境变量，去用切换工具方案。
4.2 Windows 下“claude 不是内部或外部命令”的处理
热搜里常见的报错是：
claude : 无法将“claude”项识别为 cmdlet、函数、脚本文件或可运行程序的名称。还有更老的提示：
'claude' 不是内部或外部命令，也不是可运行的程序或批处理文件。原因基本都是：npm 全局安装目录不在系统的 PATH 环境变量里。处理步骤：
- 执行
npm config get prefix，拿到全局目录。 - 把
%APPDATA%\npm或上面拿到的目录加入用户 PATH。 - 重新开一个终端窗口，执行
claude --version验证。
如果不想改 PATH，也可以临时用npx启动：
npx @anthropic-ai/claude-code不过这种方式每次都要解析包，启动稍慢，长期使用还是建议把 PATH 配好。
4.3 用启动脚本固化配置
环境变量在终端关闭后就失效了。如果每天都要用，建议写成启动脚本。
macOS / Linux 下可以建一个claude3rd.sh：
#!/usr/bin/env bash export ANTHROPIC_BASE_URL="https://your-provider.example.com" export ANTHROPIC_AUTH_TOKEN="sk-你的key" export ANTHROPIC_MODEL="deepseek-chat" export API_TIMEOUT_MS=300000 claudeWindows 下建一个claude3rd.cmd：
@echo off set ANTHROPIC_BASE_URL=https://your-provider.example.com set ANTHROPIC_AUTH_TOKEN=sk-你的key set ANTHROPIC_MODEL=deepseek-chat set API_TIMEOUT_MS=300000 claude这样每次启动都从同一个脚本进去，配置不会散落在各个终端里。注意脚本里包含 key 的话，不要放到公开仓库。
5. 桌面端报错与 opencodex、ccswitch 这类切换工具
桌面端和 CLI 是两套不同的启动方式，很多在终端里没问题的配置，到了桌面端就报错。
5.1 unable to locate the codex cli binary 到底是谁找不到谁
常见报错：
unable to locate the codex cli binary. set codex_cli_path or ensure the electron resources include bin/codex.这个报错的意思是：Codex 桌面端本身是 Electron 应用，它需要调用一个真正的 Codex CLI 二进制文件来执行任务，但它在默认位置没找到。
排查顺序：
- 在终端执行
which codex（macOS / Linux）或where codex（Windows）。 - 记下返回的绝对路径。
- 在 Codex 桌面端的设置里找到
codex_cli_path或类似选项，填上这个绝对路径。 - 保存后完全退出桌面端，重新打开。
为什么终端能跑，桌面端却找不到？因为桌面端从图形界面启动时，不一定会读取你终端里配置的 PATH。所以不要觉得“我在终端明明能用 Codex”，就把这个报错当成偶发问题。
如果which codex都没输出，说明 CLI 本身没装好，先回到第 2 节重新安装。
5.2 切换工具的思路：本地转发，UI 保持原模型名
ccswitch 和 opencodex 这类方案的原理可以这么理解：它们在你本地 127.0.0.1 上起一个转发服务，把 Codex 桌面端或 CLI 发出的请求接住，再转发到你配置的第三方平台。客户端看到的还是原来的接口，所以不需要改 UI 里的模型名，这就是“换第三方模型但 UI 不换模型”。
这类工具通常需要配置几个参数：
- 监听端口，比如
127.0.0.1:8787。 - 第三方平台的 base_url、key、模型标识。
- 请求协议类型，要明确是
chat还是responses。 - 日志级别和超时时间。
好处是桌面端也能用，坏处是多了一层服务。每次报错都要先分清：是客户端连不上本地服务，还是本地服务连不上第三方平台。最直接的区分方式是看日志。
注意：本地转发服务只监听
127.0.0.1，不要把它绑定到0.0.0.0，也不要开放给局域网，否则别人可能借用你的 key。
5.3 /responses 接口报错时的排查顺序
另一个常见报错是：
cc switch local proxy failed while handling codex endpoint /responses意思是：本地转发服务在处理 Codex 发来的/responses请求时失败了。这个报错的关键词是/responses，这是 OpenAI 的 Responses API 路径。
很多第三方平台并不支持完整的 Responses API，只支持更常见的/chat/completions。所以排查顺序是：
- 先确认第三方平台有没有提供 Responses API 兼容端点。
- 如果只支持 chat 格式，把转换工具或配置里的协议类型改成
chat。 - 再检查模型标识是否真实存在，有些平台对
/responses路径的模型白名单有限。 - 打开日志，看转发服务访问第三方平台时返回的是 401、404 还是 400，按状态码继续排查。
这个报错里最容易踩的坑是：以为切换工具坏了，实际上是上游平台不支持某类请求格式。
6. 批量跑任务前先看边界，再谈效率
单条请求跑通之后，很多人会直接上批量任务，然后被各种不确定性打蒙。这里提前说清楚几个判断标准。
6.1 稳定性、速度和资源占用怎么判断
不要只看一次演示结果。至少观察以下指标：
- 单次请求耗时：从发起到看到第一个 token 的时间，以及完整生成的时间。
- 成功率：连续跑 10 到 20 条任务，记录成功、失败、超时的数量。
- 资源占用：CLI 进程和本地转发服务的内存、CPU 占用。
- 错误重试：第三方平台是否有频率限制，报 429 后是否会自动重试。
低配机器也能跑这些工具，但如果任务一多就卡住，通常不是模型的问题，而是本地服务或网络出口被占满了。
6.2 常见报错排查表
这里整理了一份我实测时常用的排查表：
| 报错或现象 | 常见原因 | 优先排查 |
|---|---|---|
| unable to locate the codex cli binary | 桌面端找不到 CLI 文件 | 用 which/where 定位，设置 codex_cli_path |
| claude 不是内部或外部命令 | npm 全局目录不在 PATH | 用 npm config get prefix 加 PATH |
| 401 / authentication | key 错误或环境变量没生效 | 检查 env_key、key 前后是否有空格 |
| 404 not found | base_url 路径不对 | 确认是否少了 /v1 前缀 |
| model not supported | 模型标识不是平台真实 ID | 换成平台 API 文档里的模型 ID |
| 请求超时 | 模型推理慢或超时设置太短 | 调大 API_TIMEOUT_MS，观察日志 |
| UI 里模型名没变但一直失败 | 本地转发层协议转换失败 | 重点看 /responses 还是 /chat/completions |
6.3 安全习惯和长期使用建议
最后说几点长期使用要注意的地方。
第一，key 不要写死在配置文件里。Codex 配置支持env_key从环境变量读取，Claude Code 环境变量本身就适合承载 key，不要为了省事硬编码进config.toml或启动脚本里。
第二，区分平台能力和模型能力。很多第三方平台提供“OpenAI 兼容”接口，但不代表所有模型都支持工具调用。Codex 和 Claude Code 这类编程助手强依赖工具调用，如果一个模型连最基础的文件读取、命令执行都做不了，聊天体验再好也落不了地。选模型时优先看它的函数调用、结构化输出支持情况。
第三，批量任务要有失败重试和日志机制。如果只是偶尔在终端问几个问题，默认配置够用；如果要跑批量代码审查、批量文件修改，就要把输出目录、任务命名、失败记录提前想好。不要把所有任务堆在同一个会话里，任务一多，第三方平台很容易触发速率限制。
第四，工具更新前先读变更说明。CCSwitch 这类工具版本迭代很快，某个版本改了接口路径或参数名都正常。不要因为一篇教程写的是旧命令就怀疑环境坏了，先看工具的 README 和日志。
最后我的建议是：不管外界把某个方案说得多全，真正决定能不能稳定用的是你对配置文件和报错信息的判断力。先把单条任务跑稳，再开批量，再上桌面端和切换工具，这个顺序能少踩很多坑。
