直接说结论Codex 这个工具就是我一直期待的“能自己看代码、改代码、跑命令、看报错”的终端编程 Agent。OpenAI 官方出品最近这波更新加上社区玩法已经非常成熟标题里说的“最新焚决”我理解成一份可以照着练的操作心法。这篇文章我会把安装、登录、配置、日常用法、高频报错一次讲透保证你看完能自己跑起来而不是把教程扔进收藏夹吃灰。这篇内容适合三类人一是被重复性重构和补测试折磨的日常开发二是想用 AI 做代码审查、批量修改的老手三是刚接触 AI 编程工具、想找一条正经上手路径的新人。我会尽量把每一步都写清楚包括为什么要这么做踩过的坑也一并交代。1. Codex 到底是什么从“能聊”到“能干”的分水岭1.1 一句话定位这个工具Codex 是 OpenAI 官方推出的命令行编程智能体。它不是你在网页里聊天的那个 ChatGPT而是一个住在你终端里的“实习工程师”你把任务丢给它它自己去读项目文件、定位问题、改代码、跑测试、看报错然后把改动结果整理给你。Copilot 类工具是“帮你补全下一行”Codex 是“帮你完成整个任务”。我刚开始用的时候也怀疑过这玩意会不会就是把对话模型包装了一下。实际用下来最大的感受是它和你共享同一个工作目录能看到真实的上下文。你说“这个接口调用报错了”它不会凭空给你编一段代码而是真的去翻你的代码、复现问题、动手改再跑一遍验证。这个“动手闭环”是它和普通聊天助手的本质区别。1.2 为什么终端 Agent 才是 AI 编程能落地的形态很多人问网页聊天里让 AI 写代码不是也能写吗能写但写出来的是“脱离土壤”的代码。真正改一个项目你得让它知道目录结构、依赖关系、既有代码风格、构建命令和测试逻辑。终端 Agent 天然就在这个环境里工作天然能调用工具读文件、写文件、执行 Shell 命令、查看 git 状态。这不是多少亿参数能替代的而是“有没有手脚”的问题。Codex 的工作流大致是理解任务 - 规划改动 - 修改文件 - 执行命令验证 - 汇报结果。中间每一步都能看到关键操作需要你点头才执行。这就像你带了一个上手很快的新同事你只需要做 code review不需要自己动手写。和网页版写代码相比它还有一个隐形的优势可复现。命令、上下文、改动都发生在本地出了错你能看到完整过程而不是面对一个黑盒对话。1.3 谁适合装、谁可以再等等先说适合的人。第一类是每天要和大量重复代码打交道的开发者比如跨文件重命名、批量补日志、统一错误处理这种活交给它非常省心。第二类是写测试很痛苦的人它能按既有测试风格自动生成用例你只需要审一遍。第三类是做代码审查的人把 git diff 丢给它让它从“有没有明显 bug、边界条件、安全隐患”的角度先过一遍效率提升非常明显。不适合的人也有完全没接触过终端、不会 git、不打算学命令行基础的同学建议先把基础补一补再用。还有一类是幻想“描述一个 App 就能自动做完整个项目”的现阶段还是趁早打消念头。Codex 是生产力工具不是许愿机它把脏活累活干完但方向和质量把关必须是你自己。2. 装好 Codex从零到能跑的最稳路径2.1 前置条件先把环境补齐安装前先确认三件事Node.js 版本、git 是否可用、终端是否正常。Codex CLI 基于 Node.js 开发官方要求 Node.js 18 及以上我建议直接用 20 LTS 或更新版本少踩兼容性的坑。检查方法很简单node -v npm -v git --version如果 node 命令找不到先去官网下载 LTS 版本装好这里没什么技巧就是别装太老的版本。git 是必须的因为 Codex 要读取仓库状态、生成 diff。即使你只是临时用一下也建议在一个 git 仓库里跑否则它改动文件后你没法回退出了事很被动。我一般会先git init或者直接在已有项目里用。账号方面你需要一个能登录 OpenAI 服务的账号。后面的鉴权部分我会细说这里先记住要么准备 ChatGPT 账号支持浏览器登录要么准备一个 OpenAI API Key二选一即可。2.2 三种安装方式怎么选第一种是 npm 全局安装最省事npm install -g openai/codex装完验证一下codex --version能看到版本号就说明安装成功。如果提示权限问题通常是 npm 全局目录没有写入权限解决办法是调整 npm 前缀目录而不是直接sudo npm install后者后患很多。第二种是从 GitHub Releases 下载二进制适合不用 npm 或者网络环境对 npm 不友好的情况。下载对应平台的压缩包解压后把可执行文件放到 PATH 目录里就行。这种方式的好处是自带运行时不需要额外管理 Node 版本。第三种是桌面版和 VS Code 插件。桌面版有图形界面适合不太习惯纯命令行的朋友VS Code 插件装好后在编辑器侧边栏直接开一个对话框选中代码就能让 Codex 改。我个人主力还是 CLI因为我的日常工作流本来就在终端里桌面版和插件算是给不同习惯的人准备的入口底层能力是一样的。装好之后先别急着干活跑一下官方自带的交互界面确认能正常进入codex如果终端能打开一个聊天界面说明核心组件都正常。2.3 登录与鉴权两种身份各有用处Codex 支持两种鉴权方式它们的区别直接决定了后面你能用什么模型。第一种是 ChatGPT 账号登录。终端里执行codex login它会打开浏览器你登录 ChatGPT 账号并授权之后凭证会存在本地。这种方式适合已经订阅 ChatGPT Plus 或 Pro 的用户好处是不用管 API 计费适合日常高频使用。第二种是 API Key。如果你有 OpenAI API 平台的密钥把它写入环境变量export OPENAI_API_KEYsk-你的密钥在 Windows PowerShell 里是$env:OPENAI_API_KEY...。这种方式适合有 API 配额、或者想通过第三方兼容服务接入的用户。这两种方式不仅计费不同能用的模型也不同。ChatGPT 账号登录时模型是账号方案绑定的API Key 方式则可以比较自由地在配置文件里指定模型。后面第 5 节要讲的gpt-5.6-sol报错根源就在这里先记住这个结论。3. 把 Codex 调教成自己的专属外挂配置与模型接入3.1 配置文件在哪核心字段怎么读Codex 的配置文件路径是~/.codex/config.toml。macOS 和 Linux 在用户主目录下Windows 一般在C:\Users\你的用户名\.codex\config.toml。第一次运行后文件会自动创建。你可以直接编辑它注意是 TOML 格式缩进和键值对写错会导致配置不生效。我用得最多的几个字段如下model gpt-5.4-codex model_provider openai sandbox_mode workspace-write temperature 0.2model指定默认模型model_provider指定模型服务商默认是openaisandbox_mode是沙箱模式后面细说temperature控制回答随机性代码生成我习惯调低改到 0.2 左右让输出更稳定可预期。配置文件改完重新打开codex就会生效。想确认当前配置被正确读取可以在终端里手动打开文件检查或者直接跑一个小任务看行为是否符合预期。3.2 接入 DeepSeek 这类兼容模型这一节是很多朋友关心的重点不想用官方模型或者没有 OpenAI API 额度的时候怎么办。答案是接入兼容 OpenAI 接口的第三方模型服务最典型的就是 DeepSeek。DeepSeek 提供与 OpenAI 兼容的接口格式Codex 也专门支持这种“自定义模型服务商”的配置方式。做法是在config.toml里加一段 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然后把你的 DeepSeek API Key 写入环境变量export DEEPSEEK_API_KEY你的key配置完成后跑一个最简单的任务验证codex exec 用一句话解释什么是回调函数如果正常返回内容说明链路通了。wire_api chat这个字段的意思是走 Chat Completions 协议DeepSeek 当前支持这个协议OpenAI 官方模型则是responses协议。接第三方服务时这个字段几乎决定了你能不能连上很多人漏配导致一堆莫名其妙的报错。接入第三方模型的收益很直接调用成本通常低很多而且账号获取也方便。代价是模型能力和官方的 Codex 专用模型有差距在复杂项目理解上偶尔会“犯迷糊”。我的建议是日常简单任务、批量修改、测试生成这类活交给第三方模型重大架构调整再用回官方模型两者共存一点都不冲突。3.3 沙箱模式先学会保护自己再让它干活沙箱模式决定了 Codex 能对你的系统做到什么程度这是新手最容易忽略的安全点。默认有三种模式read-only只读模式它只能看文件、跑只读命令不能改动任何文件。适合让它做代码审查、解释代码、分析报错。workspace-write工作区可写模式它能改当前项目目录里的文件但不能动项目之外的系统文件。日常开发强烈推荐这个。完全自动模式不需要审批直接执行命令和改动通常带dangerous之类的明确警告前缀只适合在容器、虚拟机或一次性环境里用。配置方式简单sandbox_mode workspace-write刚上手的朋友我建议先老老实实用workspace-write不要一上来就追求“全自动”。原因很简单它是你的工作目录出了问题你还能靠 git 回退一旦放开到整个系统一条rm -rf级别的误操作就够你哭的。等你对它的行为模式熟悉了再根据场景决定要不要放开。另外就算在workspace-write模式下Codex 执行每条影响文件系统的操作前默认也会弹出 diff 让你审批。这是最后一道防线一定要养成“扫一眼再回车”的习惯。我见过不少朋友图快一路按确认结果让它在配置改了不该改的东西事后排查半天。4. 日常高频实操三种用法把 Codex 吃透4.1 交互式对话模式边看边批大多数时候我用的都是交互模式终端里直接敲codex进入。界面会显示当前工作目录你直接用自然语言描述任务即可。举个例子我在一个后端项目里看到某段逻辑有重复代码我会说“把 service 层里三个重复的订单状态校验逻辑抽成一个公共函数保持对外行为不变。”它会先读相关文件给出改动计划然后逐个文件修改。每个文件改动后界面里会出现 diff你可以按确认、拒绝也可以追加要求让它重改。这个模式的核心价值是“过程可控”。它不会一次性闷头改完十个文件让你无从 review而是每动一个文件就停下来等你判断。遇到改得不对的情况直接说“不对这个分支逻辑要保持原样”它就能基于当前上下文重新调整。我还会在对话里夹带“硬约束”比如“不要改动公共配置”“不要引入新的第三方依赖”“不要动测试文件”。你约束得越清楚它跑偏的概率越低。这比事后纠错省事得多。4.2 非交互 exec 模式适合脚本和管道有些场景不适合慢慢聊天比如批量处理、定时任务、配合 git 做自动化检查。这时候用codex exec一次性把任务丢给它它跑完直接退出codex exec 给 src/utils.ts 里的每个函数补上 JSDoc 注释这个模式特别适合和管道配合。我常用的几个组合# 让 Codex 审查尚未提交的改动 git diff | codex exec 请审查这段 diff找出潜在 bug 和边界问题按严重程度列出 # 让 Codex 总结一段时间内的提交 git log --oneline -10 | codex exec 用三句话总结最近的开发重点codex exec还有两个简写别名codex e是 execcodex c是 chat。终端里少敲几个字母用久了体感差别还是很大的。注意一点exec 模式默认也会走沙箱和审批逻辑所以即使在脚本里调用它也不会绕过安全限制。如果你想完全无人值守需要额外指定相应模式我建议只在 CI 的隔离环境里这么干。4.3 AGENTS.md 与 skills让 Codex 更懂你的项目如果你觉得 Codex 每次进项目都像“失忆”那是因为它还不知道你的项目约定。解决办法是在仓库根目录放一个AGENTS.md文件用自然语言写清楚这个项目的规矩。我自己的项目里通常会写这些内容启动和测试命令是什么、目录结构怎么组织、代码风格有哪些约定比如用单引号还是双引号、命名规范、有没有不能乱动的文件、发布流程是什么。Codex 每次启动时会自动读取这个文件相当于一份“项目入职手册”。除了项目级约定还有全局约定放在~/.codex/AGENTS.md对你所有项目生效。我在这里写了通用偏好比如“写代码前先看相似文件保持风格一致”“提交信息用约定式提交格式”这样不管进哪个项目它都会自动带上这些习惯。进阶玩法是 skills 目录。在~/.codex/skills/下建一个文件夹里面放SKILL.md描述这个技能做什么、怎么调用再配一些模板或脚本。比如我建了一个“发版检查”技能它会在发布前自动检查版本号、更新日志、打包脚本是否齐全。这个能力有点类似给 Codex 装插件把反复要做的事情沉淀下来。5. 踩坑实录高频报错与排查速查表用到现在最常见的报错翻来覆去就那么几个我把它们整理成速查表方便你对着处理。报错关键字核心原因解决思路auth token is unavailable没有有效的登录凭证或 API Key重新执行codex login或检查环境变量OPENAI_API_KEY429 too many requests请求频率超限等待一段时间检查账号配额层级降低并发和调用频率exceeded retry limit重试次数耗尽通常也是限流配合上一条处理必要时切换模型服务商model is not supported... chatgpt accountChatGPT 账号登录方式与配置模型不匹配改用 API Key 鉴权或把模型改成账号方案支持的型号配置文件不生效TOML 格式错误或字段名拼错打开~/.codex/config.toml逐行核对注意井号注释和引号5.1 auth token is unavailable这个报错十有八九是登录状态丢了。要么是凭证过期要么是环境变量没设置对。我的排查顺序是先执行codex login重新走一遍浏览器授权如果还不行检查OPENAI_API_KEY是否真的在当前终端会话里。这里有个坑你在.bashrc或.zshrc里写了环境变量但当前终端没重新加载照样报这个错。跑一下echo $OPENAI_API_KEY确认能看到值再决定下一步。5.2 429 限流与 exceeded retry limit429 too many requests是官方接口在告诉你“你太快了”。Codex 内部会自动重试但重试次数耗尽就会报exceeded retry limit。遇到这种情况我的做法是停一会儿再继续或者把任务拆小。如果是用 ChatGPT 账号登录免费额度或低档套餐的限流阈值很低一个稍大的重构任务就很容易触发。换用 API Key 并升档配额或者接入第三方兼容模型都能有效避开这个限制。5.3 gpt-5.6-sol 模型不支持的问题这个报错的完整信息是 the gpt-5.6-sol model is not supported when using codex with a chatgpt account。我一开始也被绕晕了后来才明白你的config.toml里写了model gpt-5.6-sol但鉴权方式是 ChatGPT 账号登录账号方案只允许用固定的 Codex 专用模型于是它直接拒绝支持。解决办法有两条路第一把配置里的model改成你的账号方案支持的型号或者干脆注释掉model字段让它用默认模型第二改用 API Key 方式鉴权那样就能自由指定模型了。搞清楚这个原理之后你就明白为什么网上有人说“必须用 API Key 才能切某些模型”了。5.4 几个容易被忽略的小坑除了上面三个高频报错还有几个小坑值得记一下。第一是 Node.js 版本太高也会出问题。有次我升级到最新的 Node 版本后Codex 启动报了一串模块错误降回 LTS 版本就正常了。工具链兼容性这种事LTS 永远是最稳的选择。第二是中文路径问题。如果你的项目路径或用户名带中文某些终端环境下 Codex 处理文件路径会不正常表现是改了文件但找不到、或者识别不了工作目录。这不是怪力乱神是底层工具链对路径编码支持不完善建议项目放在纯英文路径下。第三是 git 仓库太大或者有大量未提交改动时Codex 会花很多时间扫描文件和生成 diff反应会变慢。我的习惯是让它干活之前先把自己手头的改动提交一下给它一个干净的起点既快又安全。第四是不要同时开多个 Codex 会话操作同一个目录。虽然大部分时候没问题但两个会话同时改同一个文件时后写入的会覆盖先写入的而且没有任何提示。我吃过一次亏之后就养成了“一个项目只开一个会话”的习惯。还有一个容易被忽略的点Codex 的能力会随版本迭代变化很大。网上很多旧教程里的命令和配置到新版本可能已经失效了。遇到“命令不存在”“字段不认识”这类问题先检查一下自己安装的版本是不是太旧npm update -g openai/codex更新到最新版再看。最后分享一个我每天都在用的小技巧把 Codex 当成“结对同事”而不是“万能工具”。我会在 AGENTS.md 里写清项目约定在对话里给足上下文和约束然后每次它改完我都会花时间认真 review 每一处 diff。很多 AI 编程翻车的案例不是因为工具不行而是因为使用的人把把关的环节省掉了。我自己用下来最大的体会是Codex 真正的价值不是替你写代码而是把你从“机械执行”里解放出来让你把精力花在判断和设计上。它把脏活累活干得很快但方向由你把控。如果你能接受这个定位它绝对值得长期留在你的工具箱里。
直接说结论Codex 这个工具就是我一直期待的“能自己看代码、改代码、跑命令、看报错”的终端编程 Agent。OpenAI 官方出品最近这波更新加上社区玩法已经非常成熟标题里说的“最新焚决”我理解成一份可以照着练的操作心法。这篇文章我会把安装、登录、配置、日常用法、高频报错一次讲透保证你看完能自己跑起来而不是把教程扔进收藏夹吃灰。这篇内容适合三类人一是被重复性重构和补测试折磨的日常开发二是想用 AI 做代码审查、批量修改的老手三是刚接触 AI 编程工具、想找一条正经上手路径的新人。我会尽量把每一步都写清楚包括为什么要这么做踩过的坑也一并交代。1. Codex 到底是什么从“能聊”到“能干”的分水岭1.1 一句话定位这个工具Codex 是 OpenAI 官方推出的命令行编程智能体。它不是你在网页里聊天的那个 ChatGPT而是一个住在你终端里的“实习工程师”你把任务丢给它它自己去读项目文件、定位问题、改代码、跑测试、看报错然后把改动结果整理给你。Copilot 类工具是“帮你补全下一行”Codex 是“帮你完成整个任务”。我刚开始用的时候也怀疑过这玩意会不会就是把对话模型包装了一下。实际用下来最大的感受是它和你共享同一个工作目录能看到真实的上下文。你说“这个接口调用报错了”它不会凭空给你编一段代码而是真的去翻你的代码、复现问题、动手改再跑一遍验证。这个“动手闭环”是它和普通聊天助手的本质区别。1.2 为什么终端 Agent 才是 AI 编程能落地的形态很多人问网页聊天里让 AI 写代码不是也能写吗能写但写出来的是“脱离土壤”的代码。真正改一个项目你得让它知道目录结构、依赖关系、既有代码风格、构建命令和测试逻辑。终端 Agent 天然就在这个环境里工作天然能调用工具读文件、写文件、执行 Shell 命令、查看 git 状态。这不是多少亿参数能替代的而是“有没有手脚”的问题。Codex 的工作流大致是理解任务 - 规划改动 - 修改文件 - 执行命令验证 - 汇报结果。中间每一步都能看到关键操作需要你点头才执行。这就像你带了一个上手很快的新同事你只需要做 code review不需要自己动手写。和网页版写代码相比它还有一个隐形的优势可复现。命令、上下文、改动都发生在本地出了错你能看到完整过程而不是面对一个黑盒对话。1.3 谁适合装、谁可以再等等先说适合的人。第一类是每天要和大量重复代码打交道的开发者比如跨文件重命名、批量补日志、统一错误处理这种活交给它非常省心。第二类是写测试很痛苦的人它能按既有测试风格自动生成用例你只需要审一遍。第三类是做代码审查的人把 git diff 丢给它让它从“有没有明显 bug、边界条件、安全隐患”的角度先过一遍效率提升非常明显。不适合的人也有完全没接触过终端、不会 git、不打算学命令行基础的同学建议先把基础补一补再用。还有一类是幻想“描述一个 App 就能自动做完整个项目”的现阶段还是趁早打消念头。Codex 是生产力工具不是许愿机它把脏活累活干完但方向和质量把关必须是你自己。2. 装好 Codex从零到能跑的最稳路径2.1 前置条件先把环境补齐安装前先确认三件事Node.js 版本、git 是否可用、终端是否正常。Codex CLI 基于 Node.js 开发官方要求 Node.js 18 及以上我建议直接用 20 LTS 或更新版本少踩兼容性的坑。检查方法很简单node -v npm -v git --version如果 node 命令找不到先去官网下载 LTS 版本装好这里没什么技巧就是别装太老的版本。git 是必须的因为 Codex 要读取仓库状态、生成 diff。即使你只是临时用一下也建议在一个 git 仓库里跑否则它改动文件后你没法回退出了事很被动。我一般会先git init或者直接在已有项目里用。账号方面你需要一个能登录 OpenAI 服务的账号。后面的鉴权部分我会细说这里先记住要么准备 ChatGPT 账号支持浏览器登录要么准备一个 OpenAI API Key二选一即可。2.2 三种安装方式怎么选第一种是 npm 全局安装最省事npm install -g openai/codex装完验证一下codex --version能看到版本号就说明安装成功。如果提示权限问题通常是 npm 全局目录没有写入权限解决办法是调整 npm 前缀目录而不是直接sudo npm install后者后患很多。第二种是从 GitHub Releases 下载二进制适合不用 npm 或者网络环境对 npm 不友好的情况。下载对应平台的压缩包解压后把可执行文件放到 PATH 目录里就行。这种方式的好处是自带运行时不需要额外管理 Node 版本。第三种是桌面版和 VS Code 插件。桌面版有图形界面适合不太习惯纯命令行的朋友VS Code 插件装好后在编辑器侧边栏直接开一个对话框选中代码就能让 Codex 改。我个人主力还是 CLI因为我的日常工作流本来就在终端里桌面版和插件算是给不同习惯的人准备的入口底层能力是一样的。装好之后先别急着干活跑一下官方自带的交互界面确认能正常进入codex如果终端能打开一个聊天界面说明核心组件都正常。2.3 登录与鉴权两种身份各有用处Codex 支持两种鉴权方式它们的区别直接决定了后面你能用什么模型。第一种是 ChatGPT 账号登录。终端里执行codex login它会打开浏览器你登录 ChatGPT 账号并授权之后凭证会存在本地。这种方式适合已经订阅 ChatGPT Plus 或 Pro 的用户好处是不用管 API 计费适合日常高频使用。第二种是 API Key。如果你有 OpenAI API 平台的密钥把它写入环境变量export OPENAI_API_KEYsk-你的密钥在 Windows PowerShell 里是$env:OPENAI_API_KEY...。这种方式适合有 API 配额、或者想通过第三方兼容服务接入的用户。这两种方式不仅计费不同能用的模型也不同。ChatGPT 账号登录时模型是账号方案绑定的API Key 方式则可以比较自由地在配置文件里指定模型。后面第 5 节要讲的gpt-5.6-sol报错根源就在这里先记住这个结论。3. 把 Codex 调教成自己的专属外挂配置与模型接入3.1 配置文件在哪核心字段怎么读Codex 的配置文件路径是~/.codex/config.toml。macOS 和 Linux 在用户主目录下Windows 一般在C:\Users\你的用户名\.codex\config.toml。第一次运行后文件会自动创建。你可以直接编辑它注意是 TOML 格式缩进和键值对写错会导致配置不生效。我用得最多的几个字段如下model gpt-5.4-codex model_provider openai sandbox_mode workspace-write temperature 0.2model指定默认模型model_provider指定模型服务商默认是openaisandbox_mode是沙箱模式后面细说temperature控制回答随机性代码生成我习惯调低改到 0.2 左右让输出更稳定可预期。配置文件改完重新打开codex就会生效。想确认当前配置被正确读取可以在终端里手动打开文件检查或者直接跑一个小任务看行为是否符合预期。3.2 接入 DeepSeek 这类兼容模型这一节是很多朋友关心的重点不想用官方模型或者没有 OpenAI API 额度的时候怎么办。答案是接入兼容 OpenAI 接口的第三方模型服务最典型的就是 DeepSeek。DeepSeek 提供与 OpenAI 兼容的接口格式Codex 也专门支持这种“自定义模型服务商”的配置方式。做法是在config.toml里加一段 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然后把你的 DeepSeek API Key 写入环境变量export DEEPSEEK_API_KEY你的key配置完成后跑一个最简单的任务验证codex exec 用一句话解释什么是回调函数如果正常返回内容说明链路通了。wire_api chat这个字段的意思是走 Chat Completions 协议DeepSeek 当前支持这个协议OpenAI 官方模型则是responses协议。接第三方服务时这个字段几乎决定了你能不能连上很多人漏配导致一堆莫名其妙的报错。接入第三方模型的收益很直接调用成本通常低很多而且账号获取也方便。代价是模型能力和官方的 Codex 专用模型有差距在复杂项目理解上偶尔会“犯迷糊”。我的建议是日常简单任务、批量修改、测试生成这类活交给第三方模型重大架构调整再用回官方模型两者共存一点都不冲突。3.3 沙箱模式先学会保护自己再让它干活沙箱模式决定了 Codex 能对你的系统做到什么程度这是新手最容易忽略的安全点。默认有三种模式read-only只读模式它只能看文件、跑只读命令不能改动任何文件。适合让它做代码审查、解释代码、分析报错。workspace-write工作区可写模式它能改当前项目目录里的文件但不能动项目之外的系统文件。日常开发强烈推荐这个。完全自动模式不需要审批直接执行命令和改动通常带dangerous之类的明确警告前缀只适合在容器、虚拟机或一次性环境里用。配置方式简单sandbox_mode workspace-write刚上手的朋友我建议先老老实实用workspace-write不要一上来就追求“全自动”。原因很简单它是你的工作目录出了问题你还能靠 git 回退一旦放开到整个系统一条rm -rf级别的误操作就够你哭的。等你对它的行为模式熟悉了再根据场景决定要不要放开。另外就算在workspace-write模式下Codex 执行每条影响文件系统的操作前默认也会弹出 diff 让你审批。这是最后一道防线一定要养成“扫一眼再回车”的习惯。我见过不少朋友图快一路按确认结果让它在配置改了不该改的东西事后排查半天。4. 日常高频实操三种用法把 Codex 吃透4.1 交互式对话模式边看边批大多数时候我用的都是交互模式终端里直接敲codex进入。界面会显示当前工作目录你直接用自然语言描述任务即可。举个例子我在一个后端项目里看到某段逻辑有重复代码我会说“把 service 层里三个重复的订单状态校验逻辑抽成一个公共函数保持对外行为不变。”它会先读相关文件给出改动计划然后逐个文件修改。每个文件改动后界面里会出现 diff你可以按确认、拒绝也可以追加要求让它重改。这个模式的核心价值是“过程可控”。它不会一次性闷头改完十个文件让你无从 review而是每动一个文件就停下来等你判断。遇到改得不对的情况直接说“不对这个分支逻辑要保持原样”它就能基于当前上下文重新调整。我还会在对话里夹带“硬约束”比如“不要改动公共配置”“不要引入新的第三方依赖”“不要动测试文件”。你约束得越清楚它跑偏的概率越低。这比事后纠错省事得多。4.2 非交互 exec 模式适合脚本和管道有些场景不适合慢慢聊天比如批量处理、定时任务、配合 git 做自动化检查。这时候用codex exec一次性把任务丢给它它跑完直接退出codex exec 给 src/utils.ts 里的每个函数补上 JSDoc 注释这个模式特别适合和管道配合。我常用的几个组合# 让 Codex 审查尚未提交的改动 git diff | codex exec 请审查这段 diff找出潜在 bug 和边界问题按严重程度列出 # 让 Codex 总结一段时间内的提交 git log --oneline -10 | codex exec 用三句话总结最近的开发重点codex exec还有两个简写别名codex e是 execcodex c是 chat。终端里少敲几个字母用久了体感差别还是很大的。注意一点exec 模式默认也会走沙箱和审批逻辑所以即使在脚本里调用它也不会绕过安全限制。如果你想完全无人值守需要额外指定相应模式我建议只在 CI 的隔离环境里这么干。4.3 AGENTS.md 与 skills让 Codex 更懂你的项目如果你觉得 Codex 每次进项目都像“失忆”那是因为它还不知道你的项目约定。解决办法是在仓库根目录放一个AGENTS.md文件用自然语言写清楚这个项目的规矩。我自己的项目里通常会写这些内容启动和测试命令是什么、目录结构怎么组织、代码风格有哪些约定比如用单引号还是双引号、命名规范、有没有不能乱动的文件、发布流程是什么。Codex 每次启动时会自动读取这个文件相当于一份“项目入职手册”。除了项目级约定还有全局约定放在~/.codex/AGENTS.md对你所有项目生效。我在这里写了通用偏好比如“写代码前先看相似文件保持风格一致”“提交信息用约定式提交格式”这样不管进哪个项目它都会自动带上这些习惯。进阶玩法是 skills 目录。在~/.codex/skills/下建一个文件夹里面放SKILL.md描述这个技能做什么、怎么调用再配一些模板或脚本。比如我建了一个“发版检查”技能它会在发布前自动检查版本号、更新日志、打包脚本是否齐全。这个能力有点类似给 Codex 装插件把反复要做的事情沉淀下来。5. 踩坑实录高频报错与排查速查表用到现在最常见的报错翻来覆去就那么几个我把它们整理成速查表方便你对着处理。报错关键字核心原因解决思路auth token is unavailable没有有效的登录凭证或 API Key重新执行codex login或检查环境变量OPENAI_API_KEY429 too many requests请求频率超限等待一段时间检查账号配额层级降低并发和调用频率exceeded retry limit重试次数耗尽通常也是限流配合上一条处理必要时切换模型服务商model is not supported... chatgpt accountChatGPT 账号登录方式与配置模型不匹配改用 API Key 鉴权或把模型改成账号方案支持的型号配置文件不生效TOML 格式错误或字段名拼错打开~/.codex/config.toml逐行核对注意井号注释和引号5.1 auth token is unavailable这个报错十有八九是登录状态丢了。要么是凭证过期要么是环境变量没设置对。我的排查顺序是先执行codex login重新走一遍浏览器授权如果还不行检查OPENAI_API_KEY是否真的在当前终端会话里。这里有个坑你在.bashrc或.zshrc里写了环境变量但当前终端没重新加载照样报这个错。跑一下echo $OPENAI_API_KEY确认能看到值再决定下一步。5.2 429 限流与 exceeded retry limit429 too many requests是官方接口在告诉你“你太快了”。Codex 内部会自动重试但重试次数耗尽就会报exceeded retry limit。遇到这种情况我的做法是停一会儿再继续或者把任务拆小。如果是用 ChatGPT 账号登录免费额度或低档套餐的限流阈值很低一个稍大的重构任务就很容易触发。换用 API Key 并升档配额或者接入第三方兼容模型都能有效避开这个限制。5.3 gpt-5.6-sol 模型不支持的问题这个报错的完整信息是 the gpt-5.6-sol model is not supported when using codex with a chatgpt account。我一开始也被绕晕了后来才明白你的config.toml里写了model gpt-5.6-sol但鉴权方式是 ChatGPT 账号登录账号方案只允许用固定的 Codex 专用模型于是它直接拒绝支持。解决办法有两条路第一把配置里的model改成你的账号方案支持的型号或者干脆注释掉model字段让它用默认模型第二改用 API Key 方式鉴权那样就能自由指定模型了。搞清楚这个原理之后你就明白为什么网上有人说“必须用 API Key 才能切某些模型”了。5.4 几个容易被忽略的小坑除了上面三个高频报错还有几个小坑值得记一下。第一是 Node.js 版本太高也会出问题。有次我升级到最新的 Node 版本后Codex 启动报了一串模块错误降回 LTS 版本就正常了。工具链兼容性这种事LTS 永远是最稳的选择。第二是中文路径问题。如果你的项目路径或用户名带中文某些终端环境下 Codex 处理文件路径会不正常表现是改了文件但找不到、或者识别不了工作目录。这不是怪力乱神是底层工具链对路径编码支持不完善建议项目放在纯英文路径下。第三是 git 仓库太大或者有大量未提交改动时Codex 会花很多时间扫描文件和生成 diff反应会变慢。我的习惯是让它干活之前先把自己手头的改动提交一下给它一个干净的起点既快又安全。第四是不要同时开多个 Codex 会话操作同一个目录。虽然大部分时候没问题但两个会话同时改同一个文件时后写入的会覆盖先写入的而且没有任何提示。我吃过一次亏之后就养成了“一个项目只开一个会话”的习惯。还有一个容易被忽略的点Codex 的能力会随版本迭代变化很大。网上很多旧教程里的命令和配置到新版本可能已经失效了。遇到“命令不存在”“字段不认识”这类问题先检查一下自己安装的版本是不是太旧npm update -g openai/codex更新到最新版再看。最后分享一个我每天都在用的小技巧把 Codex 当成“结对同事”而不是“万能工具”。我会在 AGENTS.md 里写清项目约定在对话里给足上下文和约束然后每次它改完我都会花时间认真 review 每一处 diff。很多 AI 编程翻车的案例不是因为工具不行而是因为使用的人把把关的环节省掉了。我自己用下来最大的体会是Codex 真正的价值不是替你写代码而是把你从“机械执行”里解放出来让你把精力花在判断和设计上。它把脏活累活干得很快但方向由你把控。如果你能接受这个定位它绝对值得长期留在你的工具箱里。
