Codex 这个编程 agent 工具最近在开发者圈子里讨论度很高。我身边不少同事第一次用它生成代码时都被那种“你下指令、它自己读文件改代码跑命令”的工作方式惊到但过去想用上它得先解决登录和模型可用性的问题。现在 Codex 支持自定义模型供应商终于能接国产模型了比如 DeepSeek按量付费、便宜、接口兼容跑日常任务完全够用。这篇文章我按自己的实操过程整理出一份保姆级教程覆盖安装、配置、真实任务、高频报错排查Windows 和 macOS 都能照着做。虽然标题里写了多图预警不过这篇我会尽量把每一步的运行回显都转述清楚你对着自己的终端看就行。配置这东西一次跑通之后其实挺简单真正麻烦的是中间那些零碎报错我会把最近网上出现频率最高的几个坑单独拉出来讲免得你在同一个地方卡半天。1. 为什么 Codex 能接国产模型先搞清楚接口这件事1.1 Codex 到底是什么Codex 是 OpenAI 出的终端编程代理工具官方的定位是“在终端里帮你完成编码任务的 agent”。它和我们常用的代码补全插件不一样补全插件是你写一句它接一句Codex 更像一个外包程序员你给它一句自然语言需求它会自己规划步骤、读取项目文件、修改代码、执行命令碰到报错还会自己修。举个我常用的例子你说“帮我把 src 目录下所有 Python 文件的 import 排序一下顺便把没用的 import 清掉”它不是只给你一段代码而是会先列出操作计划然后动手改文件改完跑一遍测试确认没破坏东西。这种多步骤自主执行的能力才是它被称为 agent 而不是补全插件的原因。很多人在这一步就卡住了因为以前想用 Codex要么得有一个 ChatGPT 账号直接登录要么绑定 OpenAI 官方 API 账单对国内开发者来说前后都有门槛。直到 Codex 支持自定义模型供应商之后情况才真正变了。1.2 关键点Codex 不挑模型只认接口Codex 底层是通过 OpenAI SDK 发请求的也就是说它认的是协议不是品牌。它只要求目标服务器长得很像 OpenAI也就是能正确处理它发过去的请求格式就行。Codex 新版本默认走 OpenAI 的 Responses API也就是 /v1/responses 这个端点同时也兼容老的 Chat Completions API也就是 /v1/chat/completions 这个端点。国产模型这边就更有意思了。DeepSeek 开放平台提供的是 OpenAI 兼容接口意思是你可以用 OpenAI SDK 的写法去调 DeepSeek 的模型只需要把 Base URL 换成 DeepSeek 的地址把 API Key 换成 DeepSeek 的 Key模型名写成 deepseek-chat 或 deepseek-reasoner 就行。于是两条路就接上了Codex 在配置文件里允许你自定义 model_provider指定 Base URL、API Key 环境变量、模型名和通信协议。你把这些指向 DeepSeekCodex 就会老老实实地把请求发到 DeepSeek 服务器底层模型就从 GPT 系列悄悄换成了国产模型。这里有个很多人踩过的细节Codex 默认用 Responses API 协议而 DeepSeek 的 OpenAI 兼容接口目前主要兼容的是 Chat Completions 协议。如果你配置完不声明协议Codex 会拿 /v1/responses 去请求 DeepSeekDeepSeek 一看这个路径不存在直接给你返 404 或者一个“endpoint not found”的报错。所以后面配置文件里必须写清楚wire_api chat这一步能省掉你后面一大半麻烦。用表格看三种接入方式会更清楚接入方式模型来源登录方式优点缺点ChatGPT 账号登录OpenAI 官方模型浏览器授权登录可能要求手机验证配置最省事账号套餐限制模型名新模型不一定能用OpenAI API KeyOpenAI 官方模型API Key按量计费模型齐全需要绑卡成本比较高DeepSeek 自定义接入DeepSeek 国产模型DeepSeek API Key便宜、充值方便、接口兼容需要手动配置能力上限不如顶级模型说白了这次“Codex 终于能用国产模型了”并不是什么特殊破解而是 Codex 主动开放了自定义模型供应商的口子加上国产模型厂商把自己的接口做成了 OpenAI 兼容格式两边一碰就成了。2. 准备与安装先把 Codex CLI 跑起来2.1 你需要准备的四样东西动手之前先清点一下装备别等配置到一半才发现少了关键项。第一Node.js 环境。Codex CLI 是基于 Node.js 发布的你需要装 Node.js 18 以上的版本建议直接用 LTS 长期支持版。有些太老的系统自带 Node 16运行 Codex 会直接报版本不支持这种就别挣扎了升级 Node 比绕开问题容易得多。第二npm。这个一般跟着 Node.js 一起装好了不用额外折腾。第三DeepSeek 的 API Key。这个需要去 DeepSeek 开放平台注册账号创建一个 API Key然后充一点钱。别看到“充值”两个字就紧张它的价格比海外大模型便宜一个数量级跑日常任务几块钱能用很久。第四一个趁手的终端。Windows 上我强烈建议用 Windows Terminal不要用老掉牙的 cmd。macOS 直接用系统自带的 Terminal 就行。这一步没有技术含量但终端好用程度直接影响你后续排错的效率。2.2 安装 Codex CLI安装过程非常简单本质上就一条命令的事。打开终端执行npm install -g openai/codex装完之后确认一下版本号能正常输出版本就说明装好了codex --version如果这一步卡住百分之八九十是网络问题导致 npm 下载超时或中断。国内环境下把 npm 镜像切到国内源通常能解决。执行下面两行命令把 registry 换成国内镜像npm config set registry https://registry.npmmirror.com npm install -g openai/codex换源之后再装基本一次过。Windows 上还有一个常见问题npm 全局安装的目录可能没有加入系统的 PATH。症状是安装过程中没有任何报错但执行codex --version的时候提示“无法识别 codex 命令”。解决办法是找到 npm 的全局安装目录一般长这样C:\Users\你的用户名\AppData\Roaming\npm手动把它加进系统环境变量的 Path 里然后重新打开一个终端窗口再试。2.3 绕开手机号验证直接进入 API Key 模式很多人在这一步差点放弃因为在终端里执行codex login之后它会把浏览器弹出来引导你登录 ChatGPT 账号。登录过程中可能要完成手机号验证对国内用户来说相当不友好而且万一你这个账号不支持某些模型后面还会蹦出一堆模型名相关的报错。我们不要走这条路。我们用的是 Codex 的另一种认证方式API Key 模式。简单说Codex 不一定非要绑定 ChatGPT 账号它可以完全靠配置文件和环境变量决定“请求发到哪、用什么 Key 认证”。只要你不执行codex login它就默认按配置文件来。这里有一个细节需要专门提醒千万不要把 DeepSeek 的 Key 设成OPENAI_API_KEY环境变量。Codex 一旦发现这个变量会认为你想走 OpenAI 官方默认通道然后把请求发到 api.openai.comDeepSeek 的 Key 在那边自然没法通过认证直接给你报 401。正确做法是给 DeepSeek 单独用一个环境变量名比如DEEPSEEK_API_KEY然后在配置文件里声明这个变量名Codex 就知道该读它了。3. 核心配置把 DeepSeek 写进 config.toml3.1 先去 DeepSeek 开放平台拿 Key到 DeepSeek 开放平台的官网注册账号登录后进入“API Keys”页面创建一个新的 API Key。创建完成之后它会完整显示一次 Key格式一般是sk-开头的一长串字符一定立刻复制保存因为关掉页面之后就看不到了。然后给账户充一点钱。DeepSeek 是按 token 计费的充个几十块钱足够你跑很久的 Codex 任务而且它的计费规则里还有缓存命中折扣同一个代码文件反复读的时候成本还会更低。拿到 Key 之后把 Key 写入环境变量。Windows 的 PowerShell 里执行setx DEEPSEEK_API_KEY sk-你复制的keymacOS 或 Linux 在终端里执行echo export DEEPSEEK_API_KEYsk-你复制的key ~/.zshrc source ~/.zshrc注意 Windows 的setx设置完需要重开一个终端窗口才会生效别设完立刻在原窗口里测试发现读不到那不是配置错了是环境变量还没刷新。3.2 config.toml 逐行拆解Codex CLI 的配置文件路径有固定要求。macOS 和 Linux 上是~/.codex/config.tomlWindows 上是%USERPROFILE%\.codex\config.toml也就是用户主目录下的.codex文件夹里的config.toml。如果.codex目录不存在自己新建一个就行。然后打开 config.toml填入下面这份配置model deepseek-chat model_provider deepseek [model_providers.deepseek] name DeepSeek base_url https://api.deepseek.com/v1 env_key DEEPSEEK_API_KEY wire_api chat这份配置我一行一行说清楚你理解之后自己改动也方便。第一行model deepseek-chat是默认模型名。deepseek-chat 对应 DeepSeek 最新的对话模型能力均衡、工具调用稳定给 Codex 用最合适。还有一个模型叫 deepseek-reasoner是推理模型但它返回的格式中带有额外的 reasoning_content 字段在 Codex 这种 agent 场景下容易造成解析问题我实际测下来并不推荐。第二行model_provider deepseek告诉 Codex你默认用的模型供应商不是 OpenAI而是下面配置里名字叫 deepseek 的这个供应商。然后[model_providers.deepseek]下面是一组针对这个供应商的详细参数。name就是个展示名写什么都行。base_url是核心中的核心它决定了 Codex 往哪个服务器发请求DeepSeek 的官方兼容地址是https://api.deepseek.com/v1这个地址同时支持 chat completions 接口记得带上/v1。env_key是关键设计。它不让你把 API Key 直接写在配置文件里而是告诉 Codex“你需要的 Key 去 DEEPSEEK_API_KEY 这个环境变量里取。”这样一来即使你把 config.toml 提交到 git 仓库也不会泄露密钥。这段配置里真正能救命的是最后一行wire_api chat。默认情况下Codex 新版本和模型通信时用的是 Responses API也就是 /v1/responses 这个端点。但 DeepSeek 的兼容接口目前主要支持的是 Chat Completions也就是 /v1/chat/completions 这个端点。如果你不写wire_api chatCodex 会默认按 Responses 协议去请求 DeepSeek结果就是 404 或者 endpoint not found。只要写上wire_api chatCodex 就会改用 Chat Completions 协议发请求两边就能正常对上话。3.3 第一次运行 codex 验证连通性配置写完了先做个最基础的连通性测试别一上来就跑复杂任务。在终端里执行codex 11等于几正常情况下Codex 会进入工作流程思考一下然后给你一个简单回答。他可能会调用代码执行能力去算也可能直接告诉你答案这取决于模型自己的判断。看到正常回复就说明整条链路已经通了。如果这一步出问题报错会集中在三种情况。第一种是 401 unauthorized说明 API Key 没配对检查环境变量DEEPSEEK_API_KEY是否真的设置成功以及 config.toml 里的 env_key 是否写成了别的名字。第二种是 404 或者 endpoint not found九成是wire_api chat没写或者 base_url 末尾多了奇怪的路径。第三种是 model not found说明模型名写错了回到 DeepSeek 官网核对一下当前支持的模型名deepseek-chat 这个命名还是相当通用的。还有一个小技巧Codex 支持用-f参数指定一个不同的配置文件方便你同时维护多套供应商配置。比如今天想用 DeepSeek明天想切回官方模型不用反复改默认配置只要准备两份 toml 文件启动时用codex -f ~/.codex/deepseek.toml指定就行。4. 实战让 Codex 用国产模型写一个真实任务4.1 场景设计用自然语言下需求配置跑通之后我们看一个完整的真实任务。假设我的下载目录里有一大堆相机导出的照片文件名都是 IMG_20240601_123456.jpg 这种一眼看不出照片内容我想按照 EXIF 里的拍摄日期统一重命名成“2024-06-01_001.jpg”这种格式同一天的照片按时间顺序补上序号。这个需求其实并不简单它涉及到读 EXIF 信息、文件名排序、批量重命名、处理重名冲突几个环节。如果手写脚本至少得十几分钟。我把这个任务原封不动丢给 Codex帮我写一个 Python 脚本把 /Users/mac/Downloads/test_rename 目录下的所有 jpg 文件按照 EXIF 拍摄日期重命名为 2024-06-01_001.jpg 这种格式。同一天的照片按拍摄时间递增补两位序号如果 EXIF 读取失败就回退到文件修改时间先不要真的执行重命名给我看脚本内容就行。注意我最后加了一句“先不要真的执行重命名”这是 Codex 这类 agent 工具使用中很重要的安全习惯。你永远可以让它先出方案确认没问题再放权执行避免它一上来就改动你的真实文件。4.2 观察 agent 的工作流程Codex 接到需求后的行为非常有代表性。它会先扫一遍项目目录看看里面有哪些文件然后提出一个执行计划接着开始写代码。它不是一次性把完整脚本丢出来就完事而是会先告诉你它准备怎么做然后逐步落实。我那次执行的过程大致是这样的Codex 先读取了目录列表发现里面混了 jpg 和 mov 文件于是问我 mkv 和 mov 类型的文件要不要一起处理。我回复说只处理 jpg它会继续调整方案然后写出一个完整脚本。我看了没问题让它执行它真的创建了脚本文件并运行最后把重命名前后的文件名对比列给我看。这种“理解上下文、主动发现模糊点、确认后再动手”的交互方式是 Codex 这类 agent 和普通 ChatGPT 聊天窗最大的区别。前者是在替你做事情后者只是在给你出主意。4.3 用 AGENTS.md 约束模型行为跑了几次任务之后我强烈建议每个项目里都放一个 AGENTS.md 文件。这个文件的作用是给 Codex 提供项目上下文让它一进来就了解你的项目习惯不用每次重新交代。这个文件放在项目根目录格式就是纯 MarkdownCodex 每次处理这个目录里的任务时会自动读取。我的一个团队项目里是这样写的# 项目约定 - 所有代码注释使用中文 - 所有面向用户的输出使用中文 - Python 代码要求兼容 3.10 及以上版本 - 修改代码后必须运行 tests 目录下的相关测试 - 自动生成的临时文件统一放在 /tmp 下不要放在项目目录里这个文件的价值在于你不需要每次对话时反复强调同样的约束。Codex 一旦读到 AGENTS.md就会把这些规则当成隐性要求。接 DeepSeek 这类国产模型之后我更建议在 AGENTS.md 里写上“所有回复使用中文”因为 deepseek-chat 对中文指令的理解和回复流畅度都很高写上这句之后整个交互体验会舒服很多。5. 高频报错排查从网上最多的几条错误说起5.1 报错速查表最近社区里关于 Codex 接入国产模型的报错帖子非常多我把出现频率最高的几条整理成一张速查表你碰到哪条直接对号入座。报错信息根本原因解决办法cc switch local proxy failed while handling codex endpoint /responses本地代理工具和 Codex 配置冲突或协议不匹配统一用一套配置把 wire_api 设为 chatcodex ran out of room in the models context window会话上下文窗口塞满新开线程拆分任务限制输出长度the gpt-5.6-sol model is not supported when using codex with a chatgpt acc登录了 ChatGPT 账号账号套餐不支持该模型名别用账号登录走 API Key 自定义模型unable to locate the codex cli binary or required runtime componentsCodex CLI 没有正确安装或 PATH 没配对重装 Node.js检查 npm 全局目录 PATH登录需要手机号验证走了 ChatGPT 账号登录流程不走账号登录用环境变量提供 Keycodex 桌面版一直显示正在重新连接本地服务没起来或登录态失效退出重登检查本地端口占用5.2 重点排查cc switch local proxy failed这条报错印象太深了因为最近群里至少有五个人贴过同样的话。CC Switch 是一个社区做的配置切换工具本来是为了方便在 Codex、Claude Code 这些工具之间快速切换模型供应商。它的原理是在本地起一个代理服务把你的请求先转发给它再由它转发到实际的模型服务器。问题恰恰出在这个“中间商”上。如果你既在 Codex 的 config.toml 里配置了 DeepSeek 的 base_url又开着 CC Switch 的本地代理Codex 的请求可能被双重转发最终打到 /v1/responses 这个路径上而 DeepSeek 不认这个路径于是报错一大堆。我的建议很直接刚上手接国产模型时先不要用 CC Switch 这类工具直接用原生 config.toml 配置把链路搞清楚。如果你确实需要多套模型配置来回切也要理清自己的路径要么 Codex 直连 DeepSeek要么完全让 CC Switch 接管代理千万不要两套逻辑混着开。如果已经混用了把 CC Switch 里监听的本地代理关掉或者把 Codex 配置里的 base_url 改回原版冷重启 Codex 再试。5.3 重点排查上下文窗口溢出Codex 和模型的一次会话可能会持续很多轮每一轮对话、每一次读文件、每一次命令执行结果都会累积进模型的上下文窗口。当任务特别长或者模型回复特别啰嗦时就容易出现 codex ran out of room in the models context window 这条报错字面意思就是“模型上下文窗口已经没有地方放新内容了”。这个问题在接 DeepSeek 之后出现的概率不低原因倒不是因为 DeepSeek 上下文短而是因为 Coding agent 的工作方式本身就极其消耗上下文它读一个文件可能几千 token调用一次工具又几千 token几十轮下来窗口再大也会顶不住。解决办法有三种。第一开启新线程。Codex 的每一个会话是独立线程新开一个就能清空上下文历史。第二拆分任务。不要把“重构整个项目”这种大需求一次性丢给它拆成“先重构 A 模块”“再重构 B 模块”这种粒度每个任务单独开会话。第三在提示词里要求模型精简输出。比如在 AGENTS.md 里加一条“修改文件时只输出必要内容不要复述全部代码”可以有效减少上下文消耗。5.4 账号模型限制和安装问题那条 the gpt-5.6-sol model is not supported 报错看着很吓人其实原理很简单你执行codex login登录了 ChatGPT 账号Codex 会去校验这个账号能不能用某个模型名。ChatGPT 账号套餐内部对模型名有白名单未开放或者不在你套餐范围内的模型名直接拒绝。而当我们走 API Key 自定义模型这条路时模型名完全由你配置文件指定根本不会经过这个白名单校验所以这个报错永远不会出现。还有 Windows 用户常遇到的 unable to locate the codex cli binary多半不是 Codex 的问题而是环境变量 Path 没有包含 npm 全局安装目录。怎么确认呢在终端执行npm root -g它会输出全局 node_modules 的路径那个路径的上一层目录才是 npm 全局 bin 目录。把它加到系统 Path重新开终端基本就解决了。至于安装未完成或桌面版一直无法启动这类问题大概率是杀毒软件拦截了安装程序写文件或者安装包下载不完整。建议先退出杀毒软件或添加白名单再重新下载安装包。桌面版和 CLI 版是两套独立的程序CLI 版有问题不影响桌面版反过来也一样你可以根据报错选择其中一个作为主力工具。6. 进阶调优让 Codex DeepSeek 更好用6.1 用 CC Switch 在官方模型和国产模型之间切换前面说新手上路先别用 CC Switch但当你把原生配置跑熟之后CC Switch 这类工具还是值得用的。你可以把 Codex 官方默认配置和 DeepSeek 自定义配置分别存成两套预设需要切换时在 GUI 里点一下就行不用每次手动改 config.toml。使用时有几个细节要注意。第一切换配置前把当前 Codex 会话完全退出不要挂着会话切配置否则新配置不会生效。第二CC Switch 的本地代理端口不要和别的程序冲突常见被占用的端口比如 8080、3000换一个不常用的端口更省心。第三不管怎么切记住协议一致性原则发往 OpenAI 官方用 Responses发往 DeepSeek 用 Chat Completions。CC Switch 里如果能选协议记得跟着供应商走。6.2 把 Codex 的习惯训练成可复用的技能Codex 的 Skills 机制值得关注。简单来说Skill 是一组预定义的指令和上下文你可以把某个项目的代码规范、常用工具链、测试命令封装成一个 Skill然后告诉 Codex 在特定场景下自动加载。这比 AGENTS.md 更结构化。我的做法是把团队里“新项目脚手架”的流程做成一个 Skill内容包括目录结构、代码风格、依赖管理方式、启动命令等。以后让 Codex 帮忙新建模块时它会自动按这套规范执行而不是每次临时问。对于国产模型来说这种预置上下文尤其重要因为把规范写在明面上比让模型通过项目反推要可靠得多。6.3 我用了两周之后的真实感受最后说说体验。把 DeepSeek 接进 Codex 之后我每天都用它处理大概三到五个小时的实际开发任务包括写脚本、改 bug、做小工具、自动跑测试。整体感觉是日常任务的完成度相当高尤其是 Python 和 TypeScript 这类生态成熟的语言代码生成质量比我预期的要好。中文沟通也非常顺畅你用中文提需求它用中文回复注释直接生成中文这在写内部工具的时候节省了很多不必要的沟通成本。延迟方面比 OpenAI 官方模型略高一点但还在可接受范围内。如果你追求的是拿 Codex 来写大型架构设计、处理极其复杂的代码库重构那我不建议把国产模型当主力那种场景下模型的推理深度还是有差距。但如果你和我一样日常更多是写脚本、做自动化、处理杂活DeepSeek 的性价比高得很明显。最后分享一个我自己的小习惯。接国产模型之后我在所有项目 AGENTS.md 里都加了一行“所有注释和回复使用中文”。这个细节看起来小实际体验提升很大因为 DeepSeek 对中文的支持本来就很好让 Codex 用中文和你同步进度、解释改动比看英文输出舒服太多了。自己用顺手之后你大概率也会回来感谢这一行的。