Codex 和 Claude Code 是目前最常用的两款终端编程助手分别来自 OpenAI 和 Anthropic。很多人装好之后的第一件事就是把默认模型换成第三方平台要么官方额度不够用要么团队已经在用 DeepSeek、智谱、Kimi、通义这些平台的 API不想再单独开一套订阅。opencodex 这个词最近被说得很多它并不是某个官方组件的名字而是社区把“Codex 和 Claude Code 接入第三方模型”这件事沉淀下来的配置方案和工具集合。这篇记录就按我实际跑过的顺序讲清楚两条接入路线、桌面端报错怎么处理以及 ccswitch 这类切换工具的关键参数。先给结论如果只用终端Codex 系优先改~/.codex/config.tomlClaude 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.tomlClaude Code 改环境变量。优点是简单、可控、没有额外进程缺点是 Codex 桌面端不一定听配置文件的Claude Code 如果遇到只支持 OpenAI 接口的平台也会被卡住。用本地切换工具。ccswitch、opencodex 这类方案思路是在本地起一个转发服务客户端只管连接这个服务服务再把请求转到你指定的第三方平台。优点是 UI 不用换模型名桌面端也能用缺点是多了一个服务进程多了一层排错点。我的建议是学习阶段先用第一种跑通了单条请求再决定要不要上第二种。不要一上来就装一堆工具最后连报错都分不清是哪个环节出的。2. 环境准备装 CLI准备第三方模型参数无论走哪条路线都要先保证 CLI 本身能跑。很多报错根本不是第三方模型的问题而是 CLI 没装好、路径不对、Node 版本太老。2.1 安装 Codex CLICodex CLI 最常见的安装方式是通过 npmnpm 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 CodeClaude 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/v1API key身份凭证sk-xxxx模型标识平台真实的模型 IDdeepseek-chat、glm-4-plus、qwen-max协议类型平台兼容 OpenAI 还是 Anthropicchat、responses或messages注意模型标识不是你在网页版聊天时看到的名字而是 API 文档里的 model 字段。很多报错都出在这里比如你把页面上的“DeepSeek Chat”写成了带空格的名称接口当然认不出来。3. Codex CLI 接入第三方模型config.toml 一步步配通Codex CLI 的配置逻辑比较集中大部分情况下只需要改一个文件。3.1 先找到配置目录避免改错文件Codex 的配置目录在用户主目录下macOS / Linux~/.codex/WindowsC:\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_keyCodex 会从这个环境变量里读取 API key而不是把 key 直接写死在配置里。wire_api请求协议。OpenAI 官方默认可能是responses但很多第三方平台只支持chat格式所以这里要先改成chat。然后设置环境变量export DEEPSEEK_API_KEYsk-你的key codex如果你的 key 是别的名称把env_key改成对应的环境变量名就行。3.3 单条验证通过后再进入复杂任务配置完之后不要直接丢一个大型重构任务进去。先用最简单的非交互命令验证codex exec 用一句话解释什么是数据库索引能正常返回结果说明 base_url、key、模型标识、协议类型都对了。如果报错按顺序检查是否 401key 错了或者环境变量名和env_key不一致。是否 404base_url 不对可能少了版本前缀。是否提示模型不支持模型标识不是平台真实 ID或者平台不支持responses协议。是否超时第三方平台响应慢或者网络到平台本身就不稳。单条能跑通再去试带工具调用的任务比如让 Codex 自己查目录、改文件。因为有些第三方模型虽然聊天能用但工具调用格式不支持会表现为“看起来在思考实际不执行”。4. Claude Code 接入第三方模型环境变量和启动脚本Claude Code 的配置方式和 Codex 完全不同核心是环境变量。4.1 三个核心环境变量在启动claude之前设置以下环境变量export ANTHROPIC_BASE_URLhttps://your-provider.example.com export ANTHROPIC_AUTH_TOKENsk-你的key export ANTHROPIC_MODELdeepseek-chat含义分别是ANTHROPIC_BASE_URL第三方平台提供的 Anthropic 兼容地址。Claude Code 会在这个基础地址上拼/v1/messages请求。ANTHROPIC_AUTH_TOKEN第三方平台给你的 key。Claude Code 会把它当作访问凭证带在请求头里。ANTHROPIC_MODEL指定实际使用的模型标识。如果不设置可能默认用 Anthropic 官方模型名第三方平台不认识就直接报错。有些场景超时时间也需要调大export API_TIMEOUT_MS300000这个变量控制 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_URLhttps://your-provider.example.com export ANTHROPIC_AUTH_TOKENsk-你的key export ANTHROPIC_MODELdeepseek-chat export API_TIMEOUT_MS300000 claudeWindows 下建一个claude3rd.cmdecho off set ANTHROPIC_BASE_URLhttps://your-provider.example.com set ANTHROPIC_AUTH_TOKENsk-你的key set ANTHROPIC_MODELdeepseek-chat set API_TIMEOUT_MS300000 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 codexmacOS / Linux或where codexWindows。记下返回的绝对路径。在 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_pathclaude 不是内部或外部命令npm 全局目录不在 PATH用 npm config get prefix 加 PATH401 / authenticationkey 错误或环境变量没生效检查 env_key、key 前后是否有空格404 not foundbase_url 路径不对确认是否少了 /v1 前缀model not supported模型标识不是平台真实 ID换成平台 API 文档里的模型 ID请求超时模型推理慢或超时设置太短调大 API_TIMEOUT_MS观察日志UI 里模型名没变但一直失败本地转发层协议转换失败重点看 /responses 还是 /chat/completions6.3 安全习惯和长期使用建议最后说几点长期使用要注意的地方。第一key 不要写死在配置文件里。Codex 配置支持env_key从环境变量读取Claude Code 环境变量本身就适合承载 key不要为了省事硬编码进config.toml或启动脚本里。第二区分平台能力和模型能力。很多第三方平台提供“OpenAI 兼容”接口但不代表所有模型都支持工具调用。Codex 和 Claude Code 这类编程助手强依赖工具调用如果一个模型连最基础的文件读取、命令执行都做不了聊天体验再好也落不了地。选模型时优先看它的函数调用、结构化输出支持情况。第三批量任务要有失败重试和日志机制。如果只是偶尔在终端问几个问题默认配置够用如果要跑批量代码审查、批量文件修改就要把输出目录、任务命名、失败记录提前想好。不要把所有任务堆在同一个会话里任务一多第三方平台很容易触发速率限制。第四工具更新前先读变更说明。CCSwitch 这类工具版本迭代很快某个版本改了接口路径或参数名都正常。不要因为一篇教程写的是旧命令就怀疑环境坏了先看工具的 README 和日志。最后我的建议是不管外界把某个方案说得多全真正决定能不能稳定用的是你对配置文件和报错信息的判断力。先把单条任务跑稳再开批量再上桌面端和切换工具这个顺序能少踩很多坑。