我开始接触 Codex 是在 2021 年那会儿就是 GitHub Copilot 背后那个代码补全大模型。当时它给我的感觉是单写一个函数、补一段单元测试非常顺手可一旦让它在真实仓库里动十几个文件的公共接口它就只会对着第一个文件改一改然后停下来等你。四年之后再聊 Codex这个名字已经不是当年的意思了。OpenAI 把它重新打造成了跑在终端里的软件工程智能体——自己翻开仓库、读代码、列计划、改文件、跑测试、再根据报错接着改一条龙干到收工。这篇文章想讲透两件事Codex 从代码生成大模型到软件工程智能体这条演进路径底层到底发生了什么以及我在真实项目里从安装到落地这一路的工程实践——配置文件怎么写、模型怎么接、报错怎么查、什么样的活交给它最划算。适合手里有 Git 仓库、正犹豫要不要把日常 bug 修复、依赖升级、大规模重构交给这类智能体的开发者参考懂一点命令行就能跟上。1. 同一个名字两种物种Codex 的两次定义1.1 第一代 Codex一个很会续写的代码模型2021 年 OpenAI 发布 Codex 论文本质上是把 GPT-3 在 GitHub 海量代码上做了专门微调。它最大的成果是把代码生成的起点抬高了一大截如果我没记错的话当年规模较大的 12B 模型在 HumanEval 基准上 pass1 大约到了 28.8%pass100 能摸到 70% 以上。这个数字放到今天看不算什么但在当时已经是从玩具到能用的跨越——GitHub Copilot 就是靠它把 AI 补全真正卖给了几百万开发者。但它有非常明显的天花板我实际用 Copilot 那两年的体感可以总结成三条。第一它只有窗口没有上下文一次生成只看得见当前文件和编辑器里那一小段代码整个仓库长什么样它一无所知。第二它只会产出文本不会执行不会告诉你这段代码能不能编译、测试过不过。第三它没有打磨能力生成完就结束了出了 bug 也不会回头改。这就是典型的代码生成大模型单位是 token目标是接得通顺。1.2 第二代 Codex一个住在终端里的工程师2025 年 OpenAI 重新启用 Codex 这个名字但这次指的是一整套智能体工具链包括开源的 Codex CLI 命令行客户端、IDE 扩展以及背后的 agent 系统。同样是让 AI 写代码第二代 Codex 的定位完全不同它不是在你的光标后面补全而是以你的仓库为工作台把改代码当成一个需要规划、执行、验证、返工的任务来干。我自己第一次完整跑一个任务时的印象很深。我在一个中型 Python 仓库里让它把 logging 的旧式格式化字符串全部迁移成 f-string 风格并且保持日志输出格式完全不变。它先花了几轮读动作把仓库结构和相关文件扫了一遍然后列了个计划逐个文件改最后自动跑了一遍项目自带的测试。中间有一次改动让某个测试挂了它自己读了报错回退了那处修改换了个写法又跑了一次。整个过程大概十五分钟我只需要在几个关键写文件动作上点一下同意。这种体验和 Copilot 的补全完全是两个物种单位是任务目标是验收条件满足。1.3 一页纸看懂两类工具的差异维度代码生成大模型第一代 Codex软件工程智能体第二代 Codex输入当前文件 光标前的几行整个仓库 任务描述 历史会话输出一段补全文本一系列动作读文件、改文件、执行命令执行不执行只生成由 CLI 在沙箱中执行并回传结果验证靠人肉眼检查自动跑测试、lint、构建并迭代失败模式生成一段表面正确但跑不起来的代码执行了错误的命令或改了不该改的文件需要审批护栏这也是我把标题写成技术演进的原因所在。Codex 这个名字从模型变成系统不是把模型做大了一号而是把问题定义从下一个 token 是什么换成了下一个动作该做什么——这是完全不同的工程架构。2. 智能体循环的设计逻辑Codex 凭什么敢改整个仓库2.1 观察—行动—再观察比单次生成多了一个闭环第二代 Codex 的核心是一个做自动化的人再熟悉不过的控制回路请求进来之后模型根据当前状态仓库内容、任务描述、历史记录决定下一步动作——读哪个文件、改哪几行、跑什么命令CLI 负责把这些动作真实执行掉把执行结果文件内容、命令输出、退出码喂回给模型模型基于新状态再决定下一步。循环往复直到任务完成的判定出现。这个执行结果回喂的闭环是第一代模型完全没有的东西。单次生成像是一个只看剧本的演员直接上台演完整场戏智能体则像一边演一边看观众反应的现场演员——报错就是反应测试通过就是掌声。我见过很多刚接触 Codex CLI 的人低估这个差异总觉得反正都是大模型写代码但实际跑一个跨十来个文件的改动就能感受到没有闭环模型永远在赌有了闭环模型可以根据真实运行结果校准自己。2.2 工具与沙箱它凭什么能执行命令要让循环转起来光靠模型自身不够必须给它手。Codex CLI 内置的主要工具就是三类文件读写、代码检索、Shell 命令执行。这三类工具覆盖了软件工程动作的绝大部分也是它敢说改完跑一遍测试的底气。正因为能执行真实命令安全问题就必须认真设计。Codex CLI 的沙箱模式我日常主要用三种read-only只读适合陌生代码库探索、workspace-write可写当前工作区但文件系统访问被限制在项目目录内、danger-full-access完全放开适合一次性容器环境。此外网络访问默认也是受限的命令能不能访问外网由沙箱策略说了算不是模型随便 curl 就能出去。我的建议是默认永远用 workspace-write除非你明确知道自己在一个可丢弃的环境里。审批模式层叠在沙箱之上动作越敏感越需要人点头这一点在第五部分展开。2.3 上下文管理干一个小时的活Token 不够怎么办另一个容易被忽视的工程问题一个真实任务常常要持续十几轮甚至一个小时以上的循环对话上下文很快就会撑爆任何模型的窗口。Codex 的处理套路是压缩与淘汰把早期冗长的对话摘要成要点把已经完成的中间结果丢出窗口保留任务相关度最高的信息。CLI 里能感知到这种机制——跑长任务时偶尔会看到上下文被压缩的提示如果你感觉卡顿或者上下文太满也可以手动触发压缩。这里我想给第一次用的人一个直觉智能体任务本质上是上下文工程不是模型越大越能跑长任务。模型窗口决定的是单轮视野真正决定一个仓库级任务能不能干完的是系统怎么管理多轮状态的留存、精简和恢复。这个思路也延续到了配置里后面讲 model_small 这类辅助模型时还会再提。3. 开工前必做环境安装、登录鉴权与项目初始化3.1 三条安装路径npm 最省事Windows 有桌面版Codex CLI 官方推荐的方式是 npm 安装前置条件 Node.js 18 以上然后一条命令搞定npm install -g openai/codex装完验证一下codex --version如果你没有 Node 也不想装还可以走源码构建它是一个 Rust 实现的 CLI本地有 Rust 工具链的话可以从仓库编译或者直接用官方 Windows 桌面版安装包——桌面版对不熟悉命令行的同学友好很多它本质上是把同一个智能体包了一层图形界面。这里补一个实操经验Windows 桌面版装好之后第一次跑任务被安全软件拦住的概率不低因为进程要访问文件系统和一个常驻命令行环境如果杀毒软件弹窗记得选择信任。另外把仓库放在路径带中文或空格很深的目录里容易遇到一些冷门兼容问题建议先用纯英文短路径试跑通再挪回你习惯的位置。3.2 登录鉴权ChatGPT 账号设备码还是 API Key装完第一步是鉴权。两条路一是在终端执行codex login它会给你一个 8 位设备码让你在浏览器里完成登录授权登录状态会存在本机通常是~/.codex/下的凭据文件之后一段时间内不用重复登录。二是不登录 ChatGPT 账号直接用 API Key把OPENAI_API_KEY设置到环境变量里即可。两种方式各有适用场景。个人日常用官方服务登录账号更省事还能吃到账号套餐的额度脚本化、自动化或公司内部接入API Key 更干净换机器也简单。有一点必须在最开始就讲清楚Codex CLI 本身是开源工具但它默认连接的官方服务在哪些国家和地区可用完全取决于 OpenAI 官方的支持范围。你所在地区能不能直连官方服务、账号类型有没有权限这些都要以官方说明和你自己的网络环境实测为准不要轻信第三方教程。如果你所在的环境不方便直连官方服务最务实的路线是接入第三方 OpenAI 兼容 API 服务——比如后面要讲的 DeepSeek——通过自定义 provider 的方式让 CLI 换一个后端。这也是codex 国内能用吗这个问题的最主流答案CLI 照常用把后端换成你可以访问的服务。3.3 第一次跑通在空仓库里从零到一建议第一次别一上来就拿生产仓库练手。在空目录里先跑一遍mkdir demo cd demo git init codex 写一个读取 CSV 文件并按列统计缺失值数量的 Python 脚本再做一个最小示例数据跑通它这时候你会看到它先创建脚本然后可能自动用 python 执行一次。如果环境里没装 pandas它还会自己换用标准库实现或者提示装依赖。整个过程的交互点会通过审批模式呈现。等它说完成你ls看文件、手动跑一遍验证基本就理解了整个工具的工作节奏。这里有个第一印象很重要的细节Codex 默认是在当前目录的 Git 仓库上下文里工作的决策时会参考.gitignore来决定哪些文件不该动。所以第一次测试前先git init并提交一个干净的初始状态能让你在它乱搞时一键还原。后面第五部分会专门讲这套先提交再干活的铁律。4. config.toml 深度解析模型切换与 DeepSeek 等第三方大模型接入4.1 配置文件长什么样Codex CLI 的全局配置在~/.codex/config.toml较新版本也支持在项目根目录放.codex/config.toml做项目级覆盖。这是一个 TOML 格式的文件核心字段不多我日常用到的是这几项model gpt-5 # 主模型负责核心推理 model_small gpt-5-mini # 轻量模型用于摘要、压缩等辅助任务 approval_policy suggested # 审批策略 sandbox_mode workspace-write # 沙箱范围model就是整个智能体的主力大脑你填什么它就用什么干活。model_small这类辅助模型不是拿来写代码的而是干上下文摘要历史压缩这类不需要全力的活分开配置能在保证质量的同时省下不少 Token 成本。approval_policy和sandbox_mode在前面已经介绍过在配置里设好默认值就不用每次启动临时改。4.2 用 -m 参数和会话内命令切换模型配置文件设的是默认值实际使用中随时可以临时换。启动时用codex -m 模型名 任务描述指定进入交互会话后也可以通过斜杠命令切换当前模型。对第三方 provider 来说完整的模型名通常是provider名/模型ID的格式比如接入 DeepSeek 后就是deepseek/deepseek-chat。这样设计的好处是同一个 CLI可以在不同后端之间来回切。官方模型写不动的活换一个推理型模型再试试是很常见的工作流。尤其是在成本敏感的场景下你完全可以白天用官方模型做核心研发晚上批量任务切给便宜模型跑。4.3 接入 DeepSeek一个可复现的完整配置DeepSeek 是目前最常被用来接入 Codex CLI 的第三方服务之一因为它提供 OpenAI 兼容的 API接口风格几乎可以无缝对接。我这里给一份我实测过的配置模板整体思路也适用于任何 OpenAI 兼容服务。首先设置环境变量把 DeepSeek 的 API Key 存起来export DEEPSEEK_API_KEY你的key然后在~/.codex/config.toml里加上自定义 providermodel deepseek/deepseek-chat model_providers { deepseek { name deepseek, base_url https://api.deepseek.com, env_key DEEPSEEK_API_KEY } }配置的含义很直白这个 provider 名叫 deepseek请求发到base_url鉴权时从环境变量DEEPSEEK_API_KEY里读密钥。保存后随便起一个任务验证codex -m deepseek/deepseek-chat 用 Python 写一个快速排序并加两行注释说明复杂度能正常返回就说明链路通了。这里有两个版本差异要注意一是有些版本的 Codex CLI 默认使用 /responses 端点协议而 DeepSeek 只兼容传统的/v1/chat/completions如果你按上面的配置跑出现端点不支持的报错就需要在 provider 配置里补一个声明让 CLI 走 chat 协议——不同版本字段名略有出入以你用的版本官方文档为准二是模型 ID 必须以服务商实际发布名为准不能把 OpenAI 的模型名直接搬过去用。DeepSeek 常用的有deepseek-chat和deepseek-reasoner具体以服务商页面为准。我在自己的仓库里长期用deepseek-chat跑日常 bug 修复和依赖升级整体体验是复杂重构的规划能力比官方模型弱一些但胜在成本极低、请求链路可靠适合批量跑那些改了不心疼的机械性改动。一句话总结选型思路官方模型管难活第三方模型管量大活。5. 实战工作流审批模式、代码重构与测试验证的正确打开方式5.1 三种审批模式怎么选审批策略approval_policy是 Codex CLI 使用体验的开关值得先花时间理解。on-request下所有动作都要你逐条确认安全感最强但长任务会很累你基本成了点确定的人suggested下读文件、检索这类低风险动作自动执行写文件和跑命令这类有副作用的动作先请示——这是我最推荐的日常默认auto下全部自动执行适合你完全信任的仓库、一次性容器环境或者你在旁边盯着的自动化场景。我见过不少人一上来就用 auto 模式然后被吓到其实不必。沙箱已经把动作限制在工作区内auto 模式的真实风险上限没有想象中高但反过来团队协作的共享分支上最好还是 suggested 起步因为你不知道它会顺手改哪些文件。模式可以在配置里定默认也可以在会话中临时切换灵活用就好。5.2 一次标准重构任务的完整过程拿上周我做过的一次真实任务举例仓库里有一段老的 requests 会话封装要全部迁移成 httpx。我在干净分支上执行codex 将 src/client.py 以及 tests/ 下所有用到 requests.Session 的代码迁移到 httpx.Client保持对外函数签名和返回类型完全不变迁移完运行 pytest 并确认全部通过它的工作节奏大致是先读src/client.py和相关测试列出改动计划然后逐文件改写遇到 imports 变更会同步调整依赖声明改到一半跑了一次测试发现某个 mock 的兼容方式变了导致用例挂掉它自己定位到是 httpx 的响应对象属性不同又回去改了 mock最后 pytest 全绿。我在 suggested 模式下逐个确认了约 8 个写文件动作全程没插一句嘴。整个改动跨 6 个文件提交前我用git diff快速过了每一处质量基本可以直接合。有两点值得说。第一任务描述里保持函数签名不变确认测试通过这两句是关键约束绝大多数返工都是因为约束没写清。第二让它主动跑测试比让它帮我改完有价值得多——测试是它闭环里最重要的裁判没有裁判的比赛谁都没法保证质量。5.3 Prompt 的正确写法约束比指令更重要给智能体写任务描述和给补全类工具写注释是两回事。我的经验是四要素范围改哪些模块、不动哪些、约束保持什么不变、遵守什么规范、验收怎么算完成、禁止项绝对不要碰什么。对比一下就明白反面例子优化一下这个项目的性能——范围、约束、验收全没定义它可能漫无目的地改半天最后告诉你看起来好多了。正面例子项目 README 的接口延迟从第 3 节开始在主流程 src/process.py 中对 find_items 函数的循环做优化不得改变返回数据结构用 cProfile 跑一遍基准前后对比输出到 stdout完成后告诉我优化前后的耗时——范围明确、约束明确、验收可量化。还有一个很容易踩的坑别让它一次干完所有事。仓库级任务拆成两三个子任务连续执行每一个都带独立验收成功率会明显更高因为每个循环都有清晰的裁判点。我习惯的做法是先在脑子里把任务拆成探索—改 A—改 B—验证四个阶段然后逐个喂给它而不是一口气写一段五十行的任务描述。5.4 Git 协作铁律先提交再干活逐份验收智能体和人在 Git 仓库里的协作方式本质上是一样的工作区干净是前提。我自己的固定流程是先创建独立分支并提交当前干净状态再启动 Codex 干活它完成后我git diff --stat看改动范围是否符合预期再逐文件git diff细看确认无误才合回主分支。万一它改歪了git checkout一键还原重新描述再跑一次成本也很低。这条习惯的价值在长任务里尤其明显。有一次我让它升级某个依赖的大版本它改了 20 多个文件其中两处改动破坏了一个边缘逻辑。因为有干净分支我直接还原后再带着注意保留旧版本里对空输入的处理逻辑这个新约束重跑二十分钟就拿到了正确结果。没有 Git 兜底的智能体工作流就像不带安全绳的攀岩不建议体验。6. 高频问题排查实录登录异常、配置告警与端点连接失败6.1 登录上不去和组织设置加载失败登录是最多新手卡住的一环。常见表现是执行codex login之后浏览器授权页一直转圈或登录成功但 CLI 侧没同步到。处理思路一般是先检查本机凭据缓存是否存在且过期把~/.codex/下和认证相关的文件备份后清掉重来一遍如果是在公司网络环境确认是不是网络策略拦了授权跳转换一个网络再试。另外无法加载组织设置这类报错多半和账号所属组织有关。要么是登录的账号没有绑定任何组织而 CLI 版本默认走组织配置要么是 SSO 会话过期重新走一遍登录流程即可。这类问题绝大多数不是 CLI 坏了而是鉴权状态和环境不一致先把登录状态刷新一遍比什么都管用。6.2 配置告警unrecognized configuration setting用较老版本配置、然后升级 CLI 之后我最常看到的一个提示就是 codex is ignoring 1 unrecognized configuration setting. check for typos or deprecations ... 这类告警。这个报错本质是版本兼容问题配置文件里写的字段在当前版本里不存在了可能是拼写错误也可能是旧字段已废弃。处理很简单把你配置里新增的字段逐个对照当前版本文档确认拼写删掉废弃项保存后重新启动。顺便说一句遇到这种告警别直接忽略——配置里藏着一个不认识的名字意味着某个设置实际没有生效等你发现时可能就是一次行为异常的来源。我在一个老项目里就因此吃过亏旧版本的model字段写法在升级后失效我盯着一个配置跑了三天才发现一直都是模型名没生效。6.3 端点连接失败与模型不支持的排查连接类报错里比较典型的是跑任务时出现类似 cc switch local ... failed while handling codex endpoint /responses 的连接失败提示。这类问题基本可以归到三类原因。一是网络链路问题终端所在环境到服务端点的通信被限制或中断最简单的验证方式是确认同一环境下其他程序能否正常访问该 API 服务。二是base_url配错比如多了/v1、少了https请求落在错误路径上。三是不支持当前端点协议第三方服务往往只兼容 chat 协议而你用的 CLI 默认走 responses 协议按上一节的方式声明协议即可。模型不支持类报错像 the xxx model is not supported when using codex 这类提示几乎都是模型 ID 写错或该 provider 根本没有这个模型。排查顺序先确认你用的 provider 和模型名组合正确再去服务商文档查可用的模型列表最后用-m参数显式指定后重试。记住一个原则model 的取值永远要是那个 provider 真实存在的模型不存在跨服务商直接搬名字的魔法。6.4 一张表解决 80% 的启动期问题现象大概率原因处置方式登录后 CLI 不认凭据缓存过期或损坏清理~/.codex认证缓存后重新codex login无法加载组织设置账号无绑定组织 / SSO 会话过期重新登录检查账号与组织授权报 unrecognized configuration setting字段拼写错误或旧版遗留对照文档核对并删除废弃字段endpoint 连接失败网络不可达 / base_url 错误 / 协议不匹配验证网络、核对 base_url、按需声明 chat 协议model not supported模型 ID 不属于当前 provider查服务商模型列表用-m显式指定Windows 下任务异常安全软件拦截 / 路径含中文空格加信任、挪到英文短路径重试上下文越长响应越慢多轮历史积累手动压缩上下文拆分任务这几类问题我在多个项目里反复遇到上面每一条处置方式都是实测有效的。将来你如果碰到表格外的怪问题我的通用建议是开调试日志看完整报错链路绝大多数看着像玄学的问题日志里都有明确答案。最后聊一点个人体会。踩过几次坑之后我现在已经不会把 Codex CLI 当成能一口气吞下整个项目的魔法师了而是一个每天都要用的普通同事它干机械性的跨文件改动能帮我省一个下午它写测试用例比我快但它需要我提供清晰的边界和验收标准。我的工作习惯也固定下来了——每天早上开工先在当前分支提交干净状态再打开 Codex 处理那些不费脑但费手指的任务它干完我 review合入后继续下一个。这种节奏下它没有一次让我后悔过把活交给它。如果你也想试记住最核心的一件事把它当作风控严格的工程师而不是无所不能的自动补全器——给它清晰的约束让它自己跑通验证然后严格 review 它碰过的每一行。这四步做到位Codex 从代码生成大模型到软件工程智能体的这条演进就会真正变成你日常开发的一部分而不是又一个尝鲜后吃灰的玩具。