1. 开始动手前先把 12 步的全貌和验收标准定下来上周帮一个朋友排查 Codex 安装问题他折腾了三天最后发现卡在 Node.js 版本上。这种事我见得太多了。Codex 这个终端编程智能体本身安装门槛并不高真正拦人的地方全在细节Node 版本、登录方式、模型和认证的配对、配置文件里的字段名随便一个不对跑起来就是各种看不懂的报错。这篇文章就把我从零配置到能正常干活的全过程拆成 12 步每一步都有明确的验收标准照着做完你就能在本地终端里指挥 Codex 读代码、改代码、跑命令。先花一分钟说清楚 Codex 是什么。它不是官网对话框里那个聊天机器人也不是网页 IDE 里的某一个按钮。Codex CLI 是一个跑在你本地终端的编程智能体你给它一个任务它会自己读项目文件、定位相关代码、执行命令、生成改动然后在你的审批下落地。说白了它更像一个坐在你工位旁边的实习生只不过这个实习生的阅读速度和处理速度都比你快。这个工具适合谁如果你是第一次用 CLI 工具的小白这篇的每一步都按傻瓜也能过的标准写如果你已经在用别的编程智能体想换个模型服务或者把 Codex 接入现有项目重点看第 5 章和第 7 章。开始之前我把完整路线图列出来你可以对照着打勾阶段步骤这一步做什么验收标准准备1检查终端与系统环境能正常打开终端知道系统版本环境2安装 Node.js LTSnode -v和npm -v有输出环境3安装 Git 并配置身份git --version可用user.name/user.email 已设置安装4全局安装 Codex CLIcodex --version有输出认证5登录 ChatGPT 或配置 API KeyCodex 能识别你的认证信息验证6跑一个最小任务codex能完整返回一次结果配置7读懂 config.toml能说出当前模型和安全模式配置8模型与认证方式配对不再报 model not supported配置9设置沙箱与审批策略清楚自己的权限边界扩展10接入 DeepSeek 等第三方模型用第三方模型跑通一个任务实战11在真实项目里完成任务改动经 git diff 审查后符合预期排错12高频报错排查常见报错 5 分钟内定位后面每一章都会拆开讲。这里先给一个重要的心理预期Codex 的版本迭代很快你装到的版本可能比我写这篇时的版本新命令名和配置字段名偶尔会有出入。遇到这种情况不要慌直接看官方文档和codex --help底层逻辑不会变。2. 第 1-3 步Node.js、Git、Codex 本体前置环境一个都别省2.1 第 1 步安装 Node.js版本不是越高越好Codex 官方是通过 npm 分发的所以 Node.js 是第一个硬门槛。这里最反直觉的一点是不是装最新版就一定好。Node 的奇数版本比如 19、21、23是实验版本很多工具链在上面表现不正常真正该选的是 LTS长期支持版目前用 20 或 22 都行具体以官方要求为准。Windows 上装 Node我建议直接用官网的 msi 安装包一路下一步装完打开一个新的 PowerShell 窗口验证node -v npm -v能打出版本号就说明环境通了。如果你用的是包管理器也可以用winget install OpenJS.NodeJS.LTS效果一样。这里提醒一句从 Windows Store 装的 Node 有时候权限目录很怪npm 全局安装会各种报错遇到这种问题优先卸载重装 msi 版别跟它较劲。如果你要同时维护多个 Node 版本可以考虑 nvm 或者 Windows 上的 nvm-windows这算进阶玩法新手不折腾。Node 这里磨蹭半小时是正常的社区里Codex 打不开的求助帖相当一部分最后都回到这个原因上。2.2 第 2 步安装 Git并设置好身份信息可能有人会问我又不是要用 GitHub为什么装 Git因为 Codex 在工作时要读取仓库状态、生成 diff、帮你做提交离开 Git 它就像瞎了一只眼。就算项目没推送到远程本地也最好是一个 Git 仓库。Git 的安装同样简单官网下载安装包或者winget install Git.Git装完验证git --version装完别急着走把身份信息配好否则后面 Codex 生成提交时会报作者未知之类的错git config --global user.name 你的名字 git config --global user.email 你的邮箱用git config --global --list检查一遍。这一步和 Node 一样是后面所有工作的地基跳过去后面会花更多时间补。2.3 第 3 步全局安装 Codex CLI我用的安装方式始终是 npm 全局安装因为官方包名和更新链路最直接npm install -g openai/codex安装完成后验证codex --version这一步最常见的坑就是codex命令找不到。原因通常是 npm 的全局 bin 目录没有加进 PATH。Windows 上可以先查一下 npm 全局目录npm config get prefix然后把%APPDATA%\npm或对应的全局目录加进 PATH再重开终端。如果你不想折腾 PATH临时应急可以先用npx openai/codex --version但后面每次都要带 npx 很烦还是建议把 PATH 一次配好。另外如果你看到网上有人从 GitHub release 直接下载打包好的桌面版或二进制也可以那个不需要先装 Node。但我个人还是推荐 CLI 方式因为桌面版界面虽然好看底层配置还是一样的而且 CLI 是接脚本、接 CI 的基础早晚要会。社区里很多人纠结官网下载入口在哪其实 npm 这一条路就是最官方的入口。3. 第 4-6 步登录、最小验证、第一份配置3.1 第 4 步登录认证选 ChatGPT 账号还是 API Key装完 Codex下一步是让它知道你是谁。这里有两种认证路线选哪条取决于你的使用场景。第一种是 ChatGPT 账号登录直接执行codex login它会尝试打开浏览器跳转到官方账号授权页。如果你在 WSL 或者远程服务器上浏览器可能弹不出来终端里一般会输出一个授权链接手动复制到本地浏览器打开也能完成。这种方式的优点是操作直观缺点是模型使用受你的会员套餐限制额度用完了就得等或者升级。第二种是 API Key 方式codex login --api-key然后在提示符里粘贴你在 OpenAI 平台创建的 API Key。这种方式走按量计费适合自动化脚本、批量任务、或者你没有 ChatGPT 会员的场景。登录完成后凭据默认存在~/.codex/auth.jsonWindows 上是%USERPROFILE%\.codex\auth.json。这个文件里存的是 token 或 key 的明文注意别提交进 Git 仓库、别截图发群丢了等于把账户权限交给别人。这也是很多Codex 登录入口相关提问背后的知识点——登录入口就在这条命令里不在别的什么神秘网页上。3.2 第 5 步跑一个最小任务确认链路全通认证完成之后先别想着接项目跑一个最小任务验证链路。直接进交互模式codex看到欢迎提示后输入列出当前目录下所有文件并统计每个文件的代码行数。如果一切正常Codex 会执行命令、返回结果在这个过程中你可能会看到审批提示——它会问你是否允许运行某条命令按提示确认就行。这一步能完整跑通说明从 Node 到认证到模型调用整条链路都是通的后面就算遇到问题也不是环境问题而是配置问题。如果这一步就报错最常见的三类情况是command not found回到第 3 步查 PATH、认证失败回到第 4 步查 auth.json、模型不支持下一章详解。顺便提一句Codex 的交互界面底部一般有快捷键提示比如用?或help能查看当前模式下的所有操作新版本界面变化很快遇到看不懂的按键先按?看看比猜省时间。3.3 第 6 步认识 config.toml这是后面所有高级玩法的入口Codex 的配置集中在~/.codex/config.tomlWindows 上就是%USERPROFILE%\.codex\config.toml。第一次安装后这个文件可能不存在没关系你可以在需要时手动创建。下面是我自己环境里的一个最小示例model gpt-5 model_provider openai sandbox_mode workspace-write [model_providers.openai] name OpenAI base_url https://api.openai.com/v1 env_key OPENAI_API_KEY wire_api responses先不用逐字段背这一章你只需要记住三件事model是默认模型名model_provider是走哪个服务商sandbox_mode是权限沙箱级别。真正的接口地址和密钥配置在[model_providers.xxx]这一段里。Codex 底层有一套执行沙箱官方叫 sandboxed execution harness你看到的 read-only、workspace-write 这些档位控制的就是这个执行器的权限范围。改完配置后要重启 Codex 进程才生效。我见过不少人改了 config.toml 然后抱怨怎么没变化多半就是忘了重开。这个文件后面接 DeepSeek 的时候还会再细讲这里先有概念就行。4. 第 7-9 步模型配对、安全策略、服务商抽象层4.1 第 7 步把模型和认证方式配对远离 model not supported模型不支持是 Codex 配置里遇到率最高的报错之一网上搜 Codex 问题十条有两条是这个。比如我见过有人把模型名写成gpt-5.6-sol结果直接报the gpt-5.6-sol model is not supported when using codex with a ...。这个报错的根源不是模型不存在而是认证方式和模型不匹配。用 ChatGPT 账号登录时你能用的模型由订阅套餐决定套餐里包含哪些模型你就用哪些用 API Key 登录时模型必须是对 API 端点开放的型号两者名单并不完全一致。很多教程里写的模型名在另一个人那里就是不好使因为你们登录方式不同。所以我的建议很朴素第一次跑通之前不要动 model 这个字段用默认值。跑通之后再按你自己的认证方式去官方文档里查支持的模型列表一个个试。改完模型如果报不支持先检查你的认证方式再检查模型名有没有写错九成问题出在这两个地方。4.2 第 8 步设置沙箱和审批策略别一上来就 full-autoCodex 能执行命令意味着它有破坏力。官方在安全上给了三道闸沙箱模式、命令审批、以及 git 兜底。config.toml 里的sandbox_mode有三个档位档位允许做什么适合场景read-only只读不允许写文件和执行修改命令看代码、问问题、做分析workspace-write可以在当前项目目录内写文件和执行命令日常开发任务danger-full-access不限制可以碰项目外路径有明确信任边界时再用日常开发我建议workspace-write够用又有底线。审批策略上新版 Codex 默认会对你确认关键操作如果你在终端里看到它等着你确认别嫌烦这是安全设计。想省事的同学可能会想直接给--full-auto我的建议是首次玩 Codex 的那几天千万别等你摸清楚它的行为模式、知道它会犯哪些低级错误之后再考虑。另外一个好习惯是每次让它开工前先保证当前目录是一个干净的 Git 仓库并且你自己已经 commit 过一版基线。这样不管它改成什么样一条git checkout .就能全部还原这是最实在的后悔药。4.3 第 9 步理解模型服务商抽象层为接第三方服务做准备如果你只看官方默认配置Codex 是个封闭工具但它的model_providers其实是一个开放抽象层它允许你声明任意一个兼容 OpenAI 接口的服务商然后让 Codex 发请求到那个服务商。这套机制就是后面接 DeepSeek 的基础。这里有个关键概念叫wire_api它决定 Codex 用哪种协议跟服务商通信。responses是 OpenAI 新一代的接口协议chat是更通用的、兼容 OpenAI chat completions 的协议。第三方服务支持哪种协议你就配哪种。很多第三方服务只实现了chat协议如果硬配成responses就会在请求/responses端点时报错——这是社区里一个非常高频的问题后面排错章还会再提。5. 第 10 步接入 DeepSeek 等第三方模型服务的完整配置说到Codex 接入 DeepSeek这应该是很多人搜这个教程的真正目的。原因不难理解官方旗舰模型的成本和额度对个人开发者不太友好而像 DeepSeek 这类性价比更友好的模型服务让 Codex 这种消耗大量 token 的 agent 工具用起来压力小得多。这类配置完全在本地文件里完成不改动任何官方组件属于官方支持的扩展方式。5.1 一份能跑通的 DeepSeek 配置长这样以我的环境为例接入 DeepSeek 只需要在 config.toml 里声明一个 provider然后切换默认 provider 即可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然后设置环境变量Windows PowerShell 里$env:DEEPSEEK_API_KEY 你的 DeepSeek API KeyLinux 或者 macOS 的 bash/zsh 里export DEEPSEEK_API_KEY你的 DeepSeek API Key重启 Codex再跑一次最小任务如果正常返回结果就说明你已经成功把 Codex 的默认模型从官方服务切到了 DeepSeek。想要验证自己确实走的是 DeepSeek最简单的办法是故意把 model 设成一个 DeepSeek 独有的模型名比如 deepseek-chat它能跑通就说明链路没问题。之后想让这个 key 每次开机都生效Windows 用户可以用setx DEEPSEEK_API_KEY 你的 Key写入用户环境变量注意 setx 之后要重开终端。类似的配置可以套用到任何兼容 OpenAI 接口的服务上核心就是三个字段base_url填服务商的接口地址env_key填你存放密钥的环境变量名wire_api按服务商实际支持的协议填。换服务商等于换这三个字段其他都不用动。5.2 接第三方服务最容易踩的三个坑第一个坑接口地址别带错路径。有的服务商要求写域名根路径有的要求带/v1写错了会 404 或鉴权失败。判断依据很简单看服务商文档里给的示例请求长什么样示例里请求打向哪里base_url 就填到哪里。第二个坑key 填混。DeepSeek 的 key 不是 OpenAI 的 keyenv_key这个字段名也不能随便改它必须和你真实设置的环境变量名保持一致。我见过有人把env_key写成DEEPSEEK_API_KEY但环境变量里设的是DEEPSEEK_KEY结果 Codex 一直拿不到 key报 401 报了一下午。第三个坑不是所有模型都适合当编码 agent。如果你发现某个模型能聊天但不会干活——比如不会调用工具、不会读文件——大概率是模型本身不支持 tool calling换个工具调用能力强的模型再试。另外说句实在话第三方模型在复杂项目上的表现和官方旗舰模型是有差距的把 DeepSeek 当默认模型之后遇到它处理不了的大型重构再切回官方模型兜底这个双模型策略我在实际项目里用得很顺手。6. 第 11 步在真实项目里走一遍完整流程6.1 从一句话需求到代码改动配置全部就绪后找一个你自己熟悉的项目练手别上来就动核心代码。我习惯用一个简单的 demo 项目来跑流程比如让它给项目添加一个 .gitignore 文件忽略 node_modules 和临时文件。在仓库根目录执行codex exec 给项目添加一个 .gitignore忽略 node_modules、dist、*.log 这类常见的临时文件如果你的版本不支持exec子命令就进入交互模式输入同样的任务效果一样。Codex 会先读目录结构找到已有文件确定 .gitignore 该放哪、该忽略什么然后生成改动。你会发现它每一步几乎都有日志输出这些日志非常有用相当于它在给你讲它打算怎么做。看到不对劲的操作直接拒绝审批它就会换思路。任务完成后用git diff审查它改了什么。这是跟工具配合最重要的动作不管它多聪明你才是最终负责人。检查没问题再提交。我个人的红线是我不看懂的改动不提交。6.2 交互模式、会话恢复、与 IDE 扩展联动除了codex exec这种一次性任务交互模式codex更适合边聊边改。你可以先问这个项目的启动流程是什么让它读代码给你讲再一步步让它改。会话中途断了也没关系用codex resume可以接着上次的对话继续不用从头讲背景。如果你在用 VS Code官方还提供 IDE 扩展装完之后可以在编辑器侧边栏直接和 Codex 对话它能看到你打开的整个工作区。用起来的感觉和目前社区里流行的 Claude Code 之类的工具很接近但既然标题是 Codex这里就不展开对比了。我的经验是小改动、想快速验证想法用 CLI改多个文件、需要结合编辑器跳转上下文时用 IDE 扩展更顺手。一个实用的小技巧给 Codex 的提示词里塞足上下文。光说帮我修 bug是没用的要说清 bug 现象、复现步骤、怀疑的文件、验收标准。它就像一个阅读理解能力很强但缺少常识的实习生你把需求文档写到位它给你的产出质量会高一个档次。7. 第 12 步高频报错排查手册建议直接收藏最后这一章我把社区里和我自己踩过的高频问题整理成一张表按现象→原因→解法的线路来遇到问题先对号入座7.1 一张表解决 80% 的报错现象大概率原因处理办法codex不是内部或外部命令npm 全局目录不在 PATH重开终端把 npm prefix 对应目录加进 PATH打开codex闪退或卡住Node 版本过旧或异常升级到官方要求的 LTS 版本重试登录时浏览器打不开环境没有图形界面用终端输出的授权链接手动完成或改用codex login --api-keymodel not supported认证方式和模型不匹配换成默认模型跑通后再按文档选支持列表里的模型401 unauthorizedAPI Key 没设或写错检查环境变量和~/.codex/auth.json请求/responses端点报错当前服务商不支持 responses 协议把该 provider 的wire_api改成chat或换回官方接口地址想写文件却被拒绝sandbox_mode限制太严提升到workspace-write或临时用danger-full-access额度不足 / quota exceededChatGPT 套餐额度用完等额度重置或切换到 API Key 计费7.2 两个常年被反复追问的疑难报错第一个是/responses端点报错。Codex 新版默认走 responses 协议这个协议对服务商的兼容性要求很高。如果你之前用某些图形化的接口切换工具改过 base_url或者照着网上的配置把 base_url 指向了一个只支持 chat 协议的服务那么 Codex 调用/responses端点就会失败。排查思路很简单先把 base_url 改回官方地址确认问题消失再换成第三方服务时把 wire_api 改成chat。记住报错的是端点不代表 Codex 坏了是它和服务商之间协议对不上。第二个是改了配置没生效。config.toml 是启动时加载的改完必须重启 Codex 进程。还有更隐蔽的情况你改了配置文件但环境变量里的 key 还是旧的或者你同时开了多个终端有些终端加载的是旧环境变量。排查配置问题永远用最小改动法一次只改一个变量改完重开终端跑最小任务验证。最后说一点个人体会。Codex 这类工具最让人上头的不是它多能写代码而是它把从想法到改动的反馈周期压缩到了分钟级。12 步全部走完你得到的不是一个能用的工具而是一个需要你持续调教的队友。我在实际使用中的经验是每次任务结束花三十秒看它生成的 diff总结它哪里做得好、哪里需要纠偏下次给提示词的时候把纠偏要求写进去它的表现会肉眼可见地变好。如果你在配置过程中遇到了这篇没覆盖到的报错先别急着重装按最近改了什么、什么时候开始报错、完整报错原文是什么这三个问题自查一遍多半能自己找到答案。
Codex CLI 从零配置指南：12步搭建终端编程智能体
1. 开始动手前先把 12 步的全貌和验收标准定下来上周帮一个朋友排查 Codex 安装问题他折腾了三天最后发现卡在 Node.js 版本上。这种事我见得太多了。Codex 这个终端编程智能体本身安装门槛并不高真正拦人的地方全在细节Node 版本、登录方式、模型和认证的配对、配置文件里的字段名随便一个不对跑起来就是各种看不懂的报错。这篇文章就把我从零配置到能正常干活的全过程拆成 12 步每一步都有明确的验收标准照着做完你就能在本地终端里指挥 Codex 读代码、改代码、跑命令。先花一分钟说清楚 Codex 是什么。它不是官网对话框里那个聊天机器人也不是网页 IDE 里的某一个按钮。Codex CLI 是一个跑在你本地终端的编程智能体你给它一个任务它会自己读项目文件、定位相关代码、执行命令、生成改动然后在你的审批下落地。说白了它更像一个坐在你工位旁边的实习生只不过这个实习生的阅读速度和处理速度都比你快。这个工具适合谁如果你是第一次用 CLI 工具的小白这篇的每一步都按傻瓜也能过的标准写如果你已经在用别的编程智能体想换个模型服务或者把 Codex 接入现有项目重点看第 5 章和第 7 章。开始之前我把完整路线图列出来你可以对照着打勾阶段步骤这一步做什么验收标准准备1检查终端与系统环境能正常打开终端知道系统版本环境2安装 Node.js LTSnode -v和npm -v有输出环境3安装 Git 并配置身份git --version可用user.name/user.email 已设置安装4全局安装 Codex CLIcodex --version有输出认证5登录 ChatGPT 或配置 API KeyCodex 能识别你的认证信息验证6跑一个最小任务codex能完整返回一次结果配置7读懂 config.toml能说出当前模型和安全模式配置8模型与认证方式配对不再报 model not supported配置9设置沙箱与审批策略清楚自己的权限边界扩展10接入 DeepSeek 等第三方模型用第三方模型跑通一个任务实战11在真实项目里完成任务改动经 git diff 审查后符合预期排错12高频报错排查常见报错 5 分钟内定位后面每一章都会拆开讲。这里先给一个重要的心理预期Codex 的版本迭代很快你装到的版本可能比我写这篇时的版本新命令名和配置字段名偶尔会有出入。遇到这种情况不要慌直接看官方文档和codex --help底层逻辑不会变。2. 第 1-3 步Node.js、Git、Codex 本体前置环境一个都别省2.1 第 1 步安装 Node.js版本不是越高越好Codex 官方是通过 npm 分发的所以 Node.js 是第一个硬门槛。这里最反直觉的一点是不是装最新版就一定好。Node 的奇数版本比如 19、21、23是实验版本很多工具链在上面表现不正常真正该选的是 LTS长期支持版目前用 20 或 22 都行具体以官方要求为准。Windows 上装 Node我建议直接用官网的 msi 安装包一路下一步装完打开一个新的 PowerShell 窗口验证node -v npm -v能打出版本号就说明环境通了。如果你用的是包管理器也可以用winget install OpenJS.NodeJS.LTS效果一样。这里提醒一句从 Windows Store 装的 Node 有时候权限目录很怪npm 全局安装会各种报错遇到这种问题优先卸载重装 msi 版别跟它较劲。如果你要同时维护多个 Node 版本可以考虑 nvm 或者 Windows 上的 nvm-windows这算进阶玩法新手不折腾。Node 这里磨蹭半小时是正常的社区里Codex 打不开的求助帖相当一部分最后都回到这个原因上。2.2 第 2 步安装 Git并设置好身份信息可能有人会问我又不是要用 GitHub为什么装 Git因为 Codex 在工作时要读取仓库状态、生成 diff、帮你做提交离开 Git 它就像瞎了一只眼。就算项目没推送到远程本地也最好是一个 Git 仓库。Git 的安装同样简单官网下载安装包或者winget install Git.Git装完验证git --version装完别急着走把身份信息配好否则后面 Codex 生成提交时会报作者未知之类的错git config --global user.name 你的名字 git config --global user.email 你的邮箱用git config --global --list检查一遍。这一步和 Node 一样是后面所有工作的地基跳过去后面会花更多时间补。2.3 第 3 步全局安装 Codex CLI我用的安装方式始终是 npm 全局安装因为官方包名和更新链路最直接npm install -g openai/codex安装完成后验证codex --version这一步最常见的坑就是codex命令找不到。原因通常是 npm 的全局 bin 目录没有加进 PATH。Windows 上可以先查一下 npm 全局目录npm config get prefix然后把%APPDATA%\npm或对应的全局目录加进 PATH再重开终端。如果你不想折腾 PATH临时应急可以先用npx openai/codex --version但后面每次都要带 npx 很烦还是建议把 PATH 一次配好。另外如果你看到网上有人从 GitHub release 直接下载打包好的桌面版或二进制也可以那个不需要先装 Node。但我个人还是推荐 CLI 方式因为桌面版界面虽然好看底层配置还是一样的而且 CLI 是接脚本、接 CI 的基础早晚要会。社区里很多人纠结官网下载入口在哪其实 npm 这一条路就是最官方的入口。3. 第 4-6 步登录、最小验证、第一份配置3.1 第 4 步登录认证选 ChatGPT 账号还是 API Key装完 Codex下一步是让它知道你是谁。这里有两种认证路线选哪条取决于你的使用场景。第一种是 ChatGPT 账号登录直接执行codex login它会尝试打开浏览器跳转到官方账号授权页。如果你在 WSL 或者远程服务器上浏览器可能弹不出来终端里一般会输出一个授权链接手动复制到本地浏览器打开也能完成。这种方式的优点是操作直观缺点是模型使用受你的会员套餐限制额度用完了就得等或者升级。第二种是 API Key 方式codex login --api-key然后在提示符里粘贴你在 OpenAI 平台创建的 API Key。这种方式走按量计费适合自动化脚本、批量任务、或者你没有 ChatGPT 会员的场景。登录完成后凭据默认存在~/.codex/auth.jsonWindows 上是%USERPROFILE%\.codex\auth.json。这个文件里存的是 token 或 key 的明文注意别提交进 Git 仓库、别截图发群丢了等于把账户权限交给别人。这也是很多Codex 登录入口相关提问背后的知识点——登录入口就在这条命令里不在别的什么神秘网页上。3.2 第 5 步跑一个最小任务确认链路全通认证完成之后先别想着接项目跑一个最小任务验证链路。直接进交互模式codex看到欢迎提示后输入列出当前目录下所有文件并统计每个文件的代码行数。如果一切正常Codex 会执行命令、返回结果在这个过程中你可能会看到审批提示——它会问你是否允许运行某条命令按提示确认就行。这一步能完整跑通说明从 Node 到认证到模型调用整条链路都是通的后面就算遇到问题也不是环境问题而是配置问题。如果这一步就报错最常见的三类情况是command not found回到第 3 步查 PATH、认证失败回到第 4 步查 auth.json、模型不支持下一章详解。顺便提一句Codex 的交互界面底部一般有快捷键提示比如用?或help能查看当前模式下的所有操作新版本界面变化很快遇到看不懂的按键先按?看看比猜省时间。3.3 第 6 步认识 config.toml这是后面所有高级玩法的入口Codex 的配置集中在~/.codex/config.tomlWindows 上就是%USERPROFILE%\.codex\config.toml。第一次安装后这个文件可能不存在没关系你可以在需要时手动创建。下面是我自己环境里的一个最小示例model gpt-5 model_provider openai sandbox_mode workspace-write [model_providers.openai] name OpenAI base_url https://api.openai.com/v1 env_key OPENAI_API_KEY wire_api responses先不用逐字段背这一章你只需要记住三件事model是默认模型名model_provider是走哪个服务商sandbox_mode是权限沙箱级别。真正的接口地址和密钥配置在[model_providers.xxx]这一段里。Codex 底层有一套执行沙箱官方叫 sandboxed execution harness你看到的 read-only、workspace-write 这些档位控制的就是这个执行器的权限范围。改完配置后要重启 Codex 进程才生效。我见过不少人改了 config.toml 然后抱怨怎么没变化多半就是忘了重开。这个文件后面接 DeepSeek 的时候还会再细讲这里先有概念就行。4. 第 7-9 步模型配对、安全策略、服务商抽象层4.1 第 7 步把模型和认证方式配对远离 model not supported模型不支持是 Codex 配置里遇到率最高的报错之一网上搜 Codex 问题十条有两条是这个。比如我见过有人把模型名写成gpt-5.6-sol结果直接报the gpt-5.6-sol model is not supported when using codex with a ...。这个报错的根源不是模型不存在而是认证方式和模型不匹配。用 ChatGPT 账号登录时你能用的模型由订阅套餐决定套餐里包含哪些模型你就用哪些用 API Key 登录时模型必须是对 API 端点开放的型号两者名单并不完全一致。很多教程里写的模型名在另一个人那里就是不好使因为你们登录方式不同。所以我的建议很朴素第一次跑通之前不要动 model 这个字段用默认值。跑通之后再按你自己的认证方式去官方文档里查支持的模型列表一个个试。改完模型如果报不支持先检查你的认证方式再检查模型名有没有写错九成问题出在这两个地方。4.2 第 8 步设置沙箱和审批策略别一上来就 full-autoCodex 能执行命令意味着它有破坏力。官方在安全上给了三道闸沙箱模式、命令审批、以及 git 兜底。config.toml 里的sandbox_mode有三个档位档位允许做什么适合场景read-only只读不允许写文件和执行修改命令看代码、问问题、做分析workspace-write可以在当前项目目录内写文件和执行命令日常开发任务danger-full-access不限制可以碰项目外路径有明确信任边界时再用日常开发我建议workspace-write够用又有底线。审批策略上新版 Codex 默认会对你确认关键操作如果你在终端里看到它等着你确认别嫌烦这是安全设计。想省事的同学可能会想直接给--full-auto我的建议是首次玩 Codex 的那几天千万别等你摸清楚它的行为模式、知道它会犯哪些低级错误之后再考虑。另外一个好习惯是每次让它开工前先保证当前目录是一个干净的 Git 仓库并且你自己已经 commit 过一版基线。这样不管它改成什么样一条git checkout .就能全部还原这是最实在的后悔药。4.3 第 9 步理解模型服务商抽象层为接第三方服务做准备如果你只看官方默认配置Codex 是个封闭工具但它的model_providers其实是一个开放抽象层它允许你声明任意一个兼容 OpenAI 接口的服务商然后让 Codex 发请求到那个服务商。这套机制就是后面接 DeepSeek 的基础。这里有个关键概念叫wire_api它决定 Codex 用哪种协议跟服务商通信。responses是 OpenAI 新一代的接口协议chat是更通用的、兼容 OpenAI chat completions 的协议。第三方服务支持哪种协议你就配哪种。很多第三方服务只实现了chat协议如果硬配成responses就会在请求/responses端点时报错——这是社区里一个非常高频的问题后面排错章还会再提。5. 第 10 步接入 DeepSeek 等第三方模型服务的完整配置说到Codex 接入 DeepSeek这应该是很多人搜这个教程的真正目的。原因不难理解官方旗舰模型的成本和额度对个人开发者不太友好而像 DeepSeek 这类性价比更友好的模型服务让 Codex 这种消耗大量 token 的 agent 工具用起来压力小得多。这类配置完全在本地文件里完成不改动任何官方组件属于官方支持的扩展方式。5.1 一份能跑通的 DeepSeek 配置长这样以我的环境为例接入 DeepSeek 只需要在 config.toml 里声明一个 provider然后切换默认 provider 即可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然后设置环境变量Windows PowerShell 里$env:DEEPSEEK_API_KEY 你的 DeepSeek API KeyLinux 或者 macOS 的 bash/zsh 里export DEEPSEEK_API_KEY你的 DeepSeek API Key重启 Codex再跑一次最小任务如果正常返回结果就说明你已经成功把 Codex 的默认模型从官方服务切到了 DeepSeek。想要验证自己确实走的是 DeepSeek最简单的办法是故意把 model 设成一个 DeepSeek 独有的模型名比如 deepseek-chat它能跑通就说明链路没问题。之后想让这个 key 每次开机都生效Windows 用户可以用setx DEEPSEEK_API_KEY 你的 Key写入用户环境变量注意 setx 之后要重开终端。类似的配置可以套用到任何兼容 OpenAI 接口的服务上核心就是三个字段base_url填服务商的接口地址env_key填你存放密钥的环境变量名wire_api按服务商实际支持的协议填。换服务商等于换这三个字段其他都不用动。5.2 接第三方服务最容易踩的三个坑第一个坑接口地址别带错路径。有的服务商要求写域名根路径有的要求带/v1写错了会 404 或鉴权失败。判断依据很简单看服务商文档里给的示例请求长什么样示例里请求打向哪里base_url 就填到哪里。第二个坑key 填混。DeepSeek 的 key 不是 OpenAI 的 keyenv_key这个字段名也不能随便改它必须和你真实设置的环境变量名保持一致。我见过有人把env_key写成DEEPSEEK_API_KEY但环境变量里设的是DEEPSEEK_KEY结果 Codex 一直拿不到 key报 401 报了一下午。第三个坑不是所有模型都适合当编码 agent。如果你发现某个模型能聊天但不会干活——比如不会调用工具、不会读文件——大概率是模型本身不支持 tool calling换个工具调用能力强的模型再试。另外说句实在话第三方模型在复杂项目上的表现和官方旗舰模型是有差距的把 DeepSeek 当默认模型之后遇到它处理不了的大型重构再切回官方模型兜底这个双模型策略我在实际项目里用得很顺手。6. 第 11 步在真实项目里走一遍完整流程6.1 从一句话需求到代码改动配置全部就绪后找一个你自己熟悉的项目练手别上来就动核心代码。我习惯用一个简单的 demo 项目来跑流程比如让它给项目添加一个 .gitignore 文件忽略 node_modules 和临时文件。在仓库根目录执行codex exec 给项目添加一个 .gitignore忽略 node_modules、dist、*.log 这类常见的临时文件如果你的版本不支持exec子命令就进入交互模式输入同样的任务效果一样。Codex 会先读目录结构找到已有文件确定 .gitignore 该放哪、该忽略什么然后生成改动。你会发现它每一步几乎都有日志输出这些日志非常有用相当于它在给你讲它打算怎么做。看到不对劲的操作直接拒绝审批它就会换思路。任务完成后用git diff审查它改了什么。这是跟工具配合最重要的动作不管它多聪明你才是最终负责人。检查没问题再提交。我个人的红线是我不看懂的改动不提交。6.2 交互模式、会话恢复、与 IDE 扩展联动除了codex exec这种一次性任务交互模式codex更适合边聊边改。你可以先问这个项目的启动流程是什么让它读代码给你讲再一步步让它改。会话中途断了也没关系用codex resume可以接着上次的对话继续不用从头讲背景。如果你在用 VS Code官方还提供 IDE 扩展装完之后可以在编辑器侧边栏直接和 Codex 对话它能看到你打开的整个工作区。用起来的感觉和目前社区里流行的 Claude Code 之类的工具很接近但既然标题是 Codex这里就不展开对比了。我的经验是小改动、想快速验证想法用 CLI改多个文件、需要结合编辑器跳转上下文时用 IDE 扩展更顺手。一个实用的小技巧给 Codex 的提示词里塞足上下文。光说帮我修 bug是没用的要说清 bug 现象、复现步骤、怀疑的文件、验收标准。它就像一个阅读理解能力很强但缺少常识的实习生你把需求文档写到位它给你的产出质量会高一个档次。7. 第 12 步高频报错排查手册建议直接收藏最后这一章我把社区里和我自己踩过的高频问题整理成一张表按现象→原因→解法的线路来遇到问题先对号入座7.1 一张表解决 80% 的报错现象大概率原因处理办法codex不是内部或外部命令npm 全局目录不在 PATH重开终端把 npm prefix 对应目录加进 PATH打开codex闪退或卡住Node 版本过旧或异常升级到官方要求的 LTS 版本重试登录时浏览器打不开环境没有图形界面用终端输出的授权链接手动完成或改用codex login --api-keymodel not supported认证方式和模型不匹配换成默认模型跑通后再按文档选支持列表里的模型401 unauthorizedAPI Key 没设或写错检查环境变量和~/.codex/auth.json请求/responses端点报错当前服务商不支持 responses 协议把该 provider 的wire_api改成chat或换回官方接口地址想写文件却被拒绝sandbox_mode限制太严提升到workspace-write或临时用danger-full-access额度不足 / quota exceededChatGPT 套餐额度用完等额度重置或切换到 API Key 计费7.2 两个常年被反复追问的疑难报错第一个是/responses端点报错。Codex 新版默认走 responses 协议这个协议对服务商的兼容性要求很高。如果你之前用某些图形化的接口切换工具改过 base_url或者照着网上的配置把 base_url 指向了一个只支持 chat 协议的服务那么 Codex 调用/responses端点就会失败。排查思路很简单先把 base_url 改回官方地址确认问题消失再换成第三方服务时把 wire_api 改成chat。记住报错的是端点不代表 Codex 坏了是它和服务商之间协议对不上。第二个是改了配置没生效。config.toml 是启动时加载的改完必须重启 Codex 进程。还有更隐蔽的情况你改了配置文件但环境变量里的 key 还是旧的或者你同时开了多个终端有些终端加载的是旧环境变量。排查配置问题永远用最小改动法一次只改一个变量改完重开终端跑最小任务验证。最后说一点个人体会。Codex 这类工具最让人上头的不是它多能写代码而是它把从想法到改动的反馈周期压缩到了分钟级。12 步全部走完你得到的不是一个能用的工具而是一个需要你持续调教的队友。我在实际使用中的经验是每次任务结束花三十秒看它生成的 diff总结它哪里做得好、哪里需要纠偏下次给提示词的时候把纠偏要求写进去它的表现会肉眼可见地变好。如果你在配置过程中遇到了这篇没覆盖到的报错先别急着重装按最近改了什么、什么时候开始报错、完整报错原文是什么这三个问题自查一遍多半能自己找到答案。
