你有没有遇到过这种情况身边人都在吹 Codex 多好用你打开终端敲了个codex结果发现默认配置要先有 OpenAI 账号看了一眼价格直接劝退。其实 Codex CLI 是开源的它完全可以把模型请求转发到你自己的 API 服务商比如 DeepSeek、国产开源模型服务或者公司内部自建的大模型网关。这篇文章专门讲这件事从怎么理解 Codex 的模型接入机制到怎么改配置文件、怎么设置环境变量、怎么排查最常见的 400 报错一条线走完。这篇内容适合谁如果你用过 ChatGPT 或这类 AI 编程工具但不想被单一厂商绑死或者你是团队里负责搭 AI 工具链的人想给同事统一配一个便宜的模型入口又或者你只是对 codex 怎么工作感到好奇想搞明白它和普通 API 调用到底差在哪里。那这篇指南应该能帮到你。我把实际配置过程中踩过的坑、翻过的文档和最终跑通的方案都整理在下面了照着做就行。1. 整体设计与思路拆解Codex 为什么需要动配置1.1 默认配置只认官方服务其余全靠自定义Codex CLI 是 OpenAI 推出的命令行 AI 编程代理它会读取你的终端上下文、修改文件、执行命令。默认安装完成后它会假设你要连的是 OpenAI 的官方模型 API所以内置的模型名、接口地址、鉴权方式全都是按官方服务写的。但问题是并不是所有人都有条件直接使用官方服务。有的是因为支付方式受限有的是因为业务数据需要走私有化模型有的单纯是想用 DeepSeek 这种性价比更高的模型。这时候如果还用默认配置Codex 就会一直卡在登录或鉴权上。好在这个工具从设计上就留了口子它支持通过config.toml文件自定义模型供应商model provider。你只需要告诉它“你要去哪个地址、用什么格式、拿哪个 key 去换 token”它就能把请求发到任何兼容的 API 服务上。这一步的本质是把 Codex 从一个“官方客户端”改造成“通用客户端”。改造的复杂度并不高真正让人困惑的是它的协议选择。Codex 新版默认走的是 OpenAI 的 Responses 协议而国内很多 API 服务商目前只兼容 Chat Completions 协议两者在接口路径和请求结构上都不一样。如果只改个 base_url 就急着跑大概率会遇到 404 或者 400 错误。所以先理解协议差异后面配置才不会抓瞎。1.2 接入自定义 API 的硬性条件协议兼容最关键判断一个 API 服务能不能接入 Codex核心不是看它支不支持 OpenAI而是看它支持哪种格式的接口。Codex 的模型提供商配置里有一个参数叫wire_api它决定了 Codex 用哪种协议去通信目前有两种可选responses和chat。responses是 OpenAI 新一代接口路径通常是/responsesCodex 官方默认用它。chat是更普及的 OpenAI 兼容接口路径一般是/v1/chat/completions现在市面上 90% 以上的第三方模型服务都兼容这个格式包括 DeepSeek、国内厂商的开放平台、各种开源自建网关。很多人在配 DeepSeek 时犯的错误是只把 base_url 改成了 DeepSeek 的地址但没改wire_api结果 Codex 还在请求/responsesDeepSeek 那边根本没有这个端点自然就报错。你在搜索引擎里看到的大量“codex 接入 deepseek 报错”基本都属于这种情况。所以在开始动手之前建议你先确认三件事第一你的 API 服务商有没有提供 OpenAI 兼容接口第二它支持的是chat还是responses或者两个都支持第三模型名到底叫什么。这三件事确认清楚后面的配置就是填空那么简单。1.3 为什么有人用网关中转有人直连服务商实际操作中我发现用户大体分成两条路线。一条是直接连服务商比如 DeepSeek 开放平台简单、便宜、不用维护适合个人开发者和中小企业。另一条是自建 API 网关把多个模型聚集在一个入口后面统一鉴权、统一计费、统一格式转换适合团队协作或者有安全合规需求的场景。网关方案能解决一个很现实的麻烦Codex 只能配一个默认模型供应商但团队里有人想用便宜快的模型写简单脚本有人想用推理能力强的模型做复杂重构。你可以用网关做路由把同一个请求地址后面的模型名映射到不同后端。不过网关方案要求你自己处理格式转换尤其是把 Responses 协议转换成 Chat Completions这块如果没配好就会出现cc switch local proxy failed while handling codex endpoint /responses这类错误。这篇指南以直连服务商为主网关的思路我会在常见问题里顺带讲一下。2. 配置文件核心细节与实操要点2.1 config.toml 是什么Codex 的中控台Codex 的配置集中在~/.codex/config.toml文件里它采用 TOML 格式就是那种“中括号分块、键值对赋值”的写法。如果你是第一次用可能还没有这个文件Codex 会在你运行codex后自动生成一个默认版本。你也可以手动创建路径不会变。这个文件的主要内容分三块第一块是全局设置比如默认模型、审批策略第二块是模型提供商定义也就是[model_providers.xxx]这一节第三块是其他杂项比如自定义指令文件路径。我们这次主要动的是前两块。我建议你先跑一遍codex --version确认安装成功再运行一次codex或者codex exec hello让它自动生成默认配置。之后再去编辑这个文件就不会出现“文件目录不存在”的尴尬问题。改配置前记得备份这是个好习惯特别是你后面要反复调试的时候。2.2 手写一个 model provider字段逐个解释下面这段配置是我在直连 DeepSeek 时用的你先感受一下结构后面我会逐项拆解model deepseek/deepseek-chat model_provider deepseek [model_providers.deepseek] name DeepSeek base_url https://api.deepseek.com env_key DEEPSEEK_API_KEY wire_api chatmodel_provider deepseek是指定用哪一个提供商块它的值必须和后面中括号里的名字对应。model deepseek/deepseek-chat是完整模型名格式是“提供商名/模型名”。为什么前面要加提供商名做前缀因为 Codex 设计上允许你在多个提供商之间切换用前缀避免模型名冲突。后面你如果配了第二个提供商就不会搞混。[model_providers.deepseek]这个中括号表示定义了一个名为deepseek的提供商块。name只是给日志和界面展示用的写个容易认的名字就行。base_url是 API 服务的根地址注意这里不包含/v1也不包含具体的接口路径Codex 会自己拼接。env_key告诉 Codex 从哪个环境变量读取 API Key这里写DEEPSEEK_API_KEY就表示启动前你需要在终端里设置这个环境变量。wire_api是协议选择DeepSeek 老版接口走chat新版如果你确认支持responses也可以填responses。这里有一个经常被忽略的点base_url到底要不要带/v1。有的服务商给的接口地址是https://api.xxx.com/v1你照着填进去可能遇到双路径报错。稳妥的做法是先在服务商文档里看示例 curl 命令比如 DeepSeek 官方给的示例是curl https://api.deepseek.com/chat/completions那 base_url 就填https://api.deepseek.com不带/v1。如果示例里是https://api.xxx.com/v1/chat/completions那 base_url 就要带/v1。这个规则不统一完全由服务商决定所以别凭感觉猜去翻文档。2.3 协议选择是核心responses 还是 chatwire_api的值直接决定了 Codex 怎么拼接请求。填chat时Codex 会把请求发到{base_url}/chat/completions填responses时会发到{base_url}/responses。很多 API 服务商没有实现/responses端点所以当你看到错误信息里提到/responses时优先考虑把wire_api改成chat。但也有反向的例子有些服务商为了兼容 Codex 新版本特意实现了/responses端点这时候如果你还在用chat反而会少一些 Codex 的完整功能。判断依据只有一个服务商的 API 文档。在配置时我个人的建议是优先用chat。因为兼容性最好绝大多数模型服务商都支持坑最少。Codex 的很多高级功能确实依赖responses但如果你只是想让编程助手跑起来、能改代码、能执行命令chat完全够用。等你把全流程跑通了再去研究服务商是否支持responses也不迟。2.4 环境变量、鉴权与 Key 安全Codex 不会把 API Key 写进配置文件而是通过环境变量读取。这个设计很合理config.toml 如果提交到 Git 仓库不会泄露密钥。配置时先设置环境变量再启动 Codex。export DEEPSEEK_API_KEYsk-你的key确认环境变量是否生效可以用echo $DEEPSEEK_API_KEY检查。这里有一个非常常见的坑你改了.zshrc或者.bashrc里的 export但当前终端窗口没执行source ~/.bashrcCodex 起来后还是读不到 Key报 401 鉴权失败。别问我是怎么知道的白折腾了二十分钟。另外加上api_key字段可以在配置里直接写死 Key但不推荐。如果只是自己本地玩图省事写死也能跑。要是配置文件会同步到别的机器或者进 Git那就千万别写老老实实用环境变量。安全不是小事。2.5 模型名别乱填一文说清 provider 与 model 的关系我看过的配置错误里出现频率最高的不是协议问题而是模型名填错。Codex 报错时经常会给你提示比如api error: 400 the supported api model names are deepseek-flash, deepseek-v4这说明服务商已经明确告诉你有哪些模型可用但你填的模型名不在范围内。这里要理清一个逻辑model deepseek/deepseek-chat中的deepseek是提供商前缀deepseek-chat才是服务商那边的真实模型名。不同服务商的模型名五花八门同一个服务商的模型还会升级更名所以最可靠的办法是去服务商的控制台或文档里查当前可用的模型列表而不是在网上复制一份旧配置。另外不是每个服务商的名字都叫deepseek你完全可以用my_provider这种自定义名字做前缀只要中括号块名、model_provider值、model里的前缀三者一致就行。3. 从零到一接入你的专属模型的完整流程3.1 前置准备工作安装与基础验证开始之前先确认环境里有没有 Node.js。Codex CLI 推荐通过 npm 安装也可以用原生安装脚本但我个人实测 npm 的方式最省心因为升级方便。安装命令很简单npm install -g openai/codex安装完先验证一下codex --version能输出版本号说明基础环境没问题。然后设置好你的 API Key 环境变量再去改配置。这里还要提醒一句先别着急改配置先用默认配置跑一次codex让它生成默认的config.toml。如果网络环境无法访问默认地址这一步会卡住那也没关系你可以手动创建目录和文件然后再填内容。运行mkdir -p ~/.codex touch ~/.codex/config.toml就能把文件先建出来。3.2 获取 API Key 和模型名以 DeepSeek 为例以 DeepSeek 开放平台为例。登录控制台后在“API Keys”页面创建一把新的 Key把sk-开头的那串字符串复制下来。然后去“模型列表”或者官方文档看当前可用的模型名比如你搜到的报错提示里有deepseek-flash、deepseek-v4那就说明这些是平台正在服务的模型名。注意每个平台的模型名更新频率不太一样有的平台淘汰旧模型后旧名字还会保留一段时间但不可用。我在配置时吃过这个亏照着网上的旧教程填了deepseek-chat结果平台早就升级成 v4 了请求打过去直接 400。所以建议你配置前花一分钟看一眼控制台的模型列表不要靠记忆。3.3 编写 config.toml完整可用配置示例下面的配置是我实测能直接跑通的你只需要替换 API Key 环境变量的值和模型名# ~/.codex/config.toml model deepseek/deepseek-v4 model_provider deepseek [model_providers.deepseek] name DeepSeek base_url https://api.deepseek.com env_key DEEPSEEK_API_KEY wire_api chat保存文件后回到终端确保环境变量已设置然后运行export DEEPSEEK_API_KEYsk-你的key codex exec print hello in python如果一切正常Codex 会调用远程模型然后返回一段 Python 代码。这时候你就完成了“从零到一接入自定义模型”的第一步。这里再补充一个细节如果你希望 Codex 在本地执行生成的命令前先向你确认可以加上approval_policy on_request或者保持默认。默认配置对新手来说更安全它会在每次执行可能修改系统的命令前询问你。等信任度高了以后再调成更激进的策略也不迟。3.4 配置其他模型服务商同样套路改三处就行理解了 DeepSeek 的配置方式后换到其他服务商只是替换三个变量base_url、env_key、model。给你一个速查框架model 你的提供商名/你的模型名 model_provider 你的提供商名 [model_providers.你的提供商名] name 显示名称 base_url 服务商给的根地址 env_key 你的APIKEY环境变量名 wire_api chat比如你要接一个自建的模型网关地址是http://10.0.0.10:8080那你只需要把base_url改成http://10.0.0.10:8080把模型名改成网关里配置好的名称。这种灵活性正是 Codex 作为开源工具最大的好处。3.5 首次运行验证从“打开了但没有完全打开”到真正干活配置完成后建议按这个顺序做功能验证先跑最简单的codex exec print hello确认基础链路通然后跑一个需要读取文件的请求比如codex exec read the current directory and summarize what it contains测试工具调用最后跑一个需要修改文件的请求比如让它在临时目录里创建文件测试写权限。这样三级测试下来Codex 的链路基本就都验证过了。我在第一次配置完时犯了一个比较低级的错误base_url填的是完整接口地址结果 Codex 请求时在路径后面又拼了一次/chat/completions变成了https://api.deepseek.com/v1/chat/completions/chat/completions。这种错误很容易排查因为报错里的 URL 会非常明显。所以看到奇怪的 404 时先看一眼完整请求 URL八成问题就出在这。4. 常见问题与排查技巧实录4.1 错误速查表直接对应你的报错信息我把实际遇到的问题和社区里高频的报错整理成了一张表你可以直接对照排查。报错特征根本原因解决办法api error: 400 the supported api model names are ...模型名填错或者该模型已下线去平台控制台查当前真实模型名更新 config.toml 中的 model 字段请求路径里出现/responses且服务商不支持wire_api未设置或错填成responses把wire_api改成chat401 Unauthorized 或认证失败API Key 没设置或环境变量读不到确认export已执行并检查env_key是否和环境变量名一致failed to connect或网络超时base_url 填错或者该地址根本不通用curl -v测试地址连通性确认根路径正确404 Not Foundbase_url 带上了多余的/v1或具体路径把 base_url 调整为基本 URL去掉已拼接的路径部分上下文超长报错比如maximum context length is 1048576 tokens模型上下文窗口有限输入内容超出限制精简对话上下文或换更大上下文窗口的模型这张表不是让你背下来而是在报错时按图索骥。我遇到最多的情况是第一种和第二种叠加模型名填了旧的wire_api又没改一次性出现两个错误容易让人误以为配置完全不对其实是两步都没走完。4.2 400 错误的完整排查步骤如果你只记住一种排查方法建议记住这个。遇到任何 400按下面四步走。第一步看报错正文。Codex 会返回很友好的提示比如the supported api model names are deepseek-flash, deepseek-v4这相当于服务商在帮你纠错。把提示里的模型名抄下来检查你的配置。第二步检查协议。确认服务商文档里写的接口示例是/chat/completions还是/responses然后对照wire_api。第三步检查 base_url。去掉末尾的/v1或/chat/completions只保留根地址再试一次。第四步直接用 curl 测一次接口。比如curl https://api.deepseek.com/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer $DEEPSEEK_API_KEY \ -d { model: deepseek-v4, messages: [{role: user, content: hi}] }如果 curl 能返回正常结果说明服务商没问题问题一定在 Codex 的配置上。如果 curl 本身就报错那就是 Key、模型名或地址的问题先解决这个再回头调 Codex。4.3 关于本地网关和请求转发服务的一些说明有些同学用的不是服务商直连而是本地起了个网关服务把 Codex 的请求做一层转发和转换。这种方式本身没毛病但需要注意的是网关必须能处理你配置的wire_api。有个典型报错叫cc switch local proxy failed while handling codex endpoint /responses当你看到这个时就是在请求/responses端点时本地网关没能成功处理。排查思路很简单先看你网关的日志确认它有没有收到请求、返回了什么状态码。如果网关日志里显示收到了请求但崩溃了大概率是网关那边不支持 Responses 协议你需要把wire_api改成chat或者在网关层面把/responses转换到/chat/completions。我建议普通用户直接用厂商的chat协议就好网关转换的维护成本其实不低。4.4 模型上下文超长与 token 设置还有一个不算高频但很恼火的错误this models maximum context length is 1048576 tokens. however...。这表示模型上下文窗口有上限而你的输入和输出加起来超了。Codex 在交互过程中会把系统提示词、工具定义、历史消息全部拼进上下文如果项目特别大或者你给了很长的自定义提示词很容易顶到上限。遇到这类问题有几个办法一是换上下文窗口更大的模型二是在自定义提示词里约定简洁回答少让模型长篇大论三是主动清理对话不要让 Codex 无限积累历史。Codex 的工具调用本身会消耗不少 token特别是让它读取大文件时所以控制文件读取范围也是一种优化。不要一味堆上下文窗口很多时候是使用习惯的问题。4.5 一个容易被忽略的细节配置改了没生效Codex 会在启动时读取 config.toml。如果你在 Codex 运行途中改了配置正在进行的会话不会自动重载。正确操作是退出当前会话、重新运行codex。如果你改了环境变量也要确认当前终端已经加载了新值否则会一直用旧值造成“我改了为什么没反应”的假象。另外Codex 的配置目录除了config.toml还可以放自定义指令文件~/codex.md这个文件里的内容会作为系统提示的一部分发给模型。如果你想定制 Codex 的行为风格可以在这里写清楚要求。不过要注意这个文件里的每一句话都会占 token别写太多废话。5. 进阶优化与实际使用体验5.1 模型选择策略便宜快模型与强推理模型怎么搭接入自定义 API 后选择模型就是你自己的事了。我的经验是把 Codex 当作日常编程助手时“快”比“聪明”更重要。因为 Codex 是 agent它会反复调用模型来读文件、改代码、跑命令每做一步都要等模型响应如果模型速度慢体感会非常难受。所以日常的简单任务建议用响应快、价格低的模型比如一些 flash 版或 lite 版的模型。只有在你需要做大型重构、复杂架构分析的时候再切换到推理能力更强的模型。Codex 配置里切换模型的方式很直接改model字段后重启即可不需要动其他东西。如果嫌手动切换麻烦可以考虑本地的模型管理工具或者通过网关做模型路由让 Codex 在不同请求之间自动分流。5.2 注意 token 消耗与成本控制自定义 API 的好处是便宜但不代表可以无限挥霍。Codex 这类 agent 工具的 token 消耗量远超普通聊天。因为它每执行一个工具调用都要把当前状态再发给模型一次长对话场景下一次复杂任务消耗几万甚至几十万 token 都很正常。我在长期使用中总结了一个省钱套路每次会话尽量聚焦一个小目标不要在一个会话里塞进太多任务。任务一旦完成就开启新会话避免历史上下文积累太多。自定义指令文件里也可以写“回答尽量精简不要输出多余解释”这样也能省下不少输出 token。5.3 与团队协作统一配置模板的重要性如果是团队使用建议用一个标准化配置模板把模型提供商、模型名、自定义指令都统一起来。可以放在 Git 仓库里维护用脚本自动复制到~/.codex/config.toml。API Key 不要放进仓库每个人用自己的环境变量。这样新同事加入时跑一个初始化脚本就能直接用不用每个人重新趟一遍配置的坑。我甚至在团队里把初始化脚本写成了make init-codex之后大家遇到问题只需要看脚本内容就知道怎么排查。标准化配置带来的最大好处是出问题时的讨论成本大幅下降因为大家的环境是一致的。6. 写在最后的几点心得6.1 别被报错吓到Codex 的报错其实很友好这套配置流程看起来步骤多但本质就是改一个配置文件。我见过很多朋友在第一步报错时就放弃了其实只要对照报错信息里的提示词去改九成问题都能解决。最怕的是“不看报错正文直接全网搜”搜出来的答案未必适用于你的服务商。6.2 我的建议顺序先跑通再优化个人建议是不要把第一次目标定得太高先能用chat协议跑通一个最简单的任务确认链路通然后再去优化模型选择、协议升级、网关定制这些花样。跑通一次之后后面的所有操作都会顺畅很多因为你已经知道关键环节在哪里。6.3 一个小技巧善用 dry-run 和日志Codex 环境下有CODEX_LOG_LEVEL之类的环境变量可以开启详细日志遇到搞不懂的请求路径或参数时把日志级别调高你会看到 Codex 真正发给 API 的完整 URL 和请求体。这是排查配置问题最直接的手段比对着文档猜要高效得多。实测下来很多 400 错误在日志里一眼就能看出是路径重复还是模型名不对。最后说一句实在的Codex 这类工具的价值在于它能真正帮你干活而不是让你折腾配置。配置自定义 API 只是第一步等跑通之后你完全可以把它接入自己最顺手的模型按自己的习惯定制提示词让它成为真正的专属编程搭档。希望这篇指南能帮你少走点弯路把更多时间花在写代码本身。