从代码补全到软件工程智能体：Codex CLI实战指南

我开始接触 Codex 是在 2021 年那会儿，就是 GitHub Copilot 背后那个代码补全大模型。当时它给我的感觉是：单写一个函数、补一段单元测试，非常顺手；可一旦让它在真实仓库里动十几个文件的公共接口，它就只会对着第一个文件改一改，然后停下来等你。四年之后再聊 Codex，这个名字已经不是当年的意思了。OpenAI 把它重新打造成了跑在终端里的软件工程智能体——自己翻开仓库、读代码、列计划、改文件、跑测试、再根据报错接着改，一条龙干到收工。这篇文章想讲透两件事：Codex 从代码生成大模型到软件工程智能体这条演进路径，底层到底发生了什么；以及我在真实项目里从安装到落地这一路的工程实践——配置文件怎么写、模型怎么接、报错怎么查、什么样的活交给它最划算。适合手里有 Git 仓库、正犹豫要不要把日常 bug 修复、依赖升级、大规模重构交给这类智能体的开发者参考，懂一点命令行就能跟上。

1. 同一个名字，两种物种：Codex 的两次定义

1.1 第一代 Codex：一个很会"续写"的代码模型

2021 年 OpenAI 发布 Codex 论文，本质上是把 GPT-3 在 GitHub 海量代码上做了专门微调。它最大的成果是把代码生成的起点抬高了一大截：如果我没记错的话，当年规模较大的 12B 模型在 HumanEval 基准上 pass@1 大约到了 28.8%，pass@100 能摸到 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 这个名字从"模型"变成"系统"，不是把模型做大了一号，而是把问题定义从"下一个 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里加上自定义 provider：

model = "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% 的启动期问题

这几类问题我在多个项目里反复遇到，上面每一条处置方式都是实测有效的。将来你如果碰到表格外的怪问题，我的通用建议是：开调试日志看完整报错链路，绝大多数"看着像玄学"的问题，日志里都有明确答案。

最后聊一点个人体会。踩过几次坑之后，我现在已经不会把 Codex CLI 当成"能一口气吞下整个项目的魔法师"了，而是一个每天都要用的普通同事：它干机械性的跨文件改动能帮我省一个下午，它写测试用例比我快，但它需要我提供清晰的边界和验收标准。我的工作习惯也固定下来了——每天早上开工，先在当前分支提交干净状态，再打开 Codex 处理那些"不费脑但费手指"的任务，它干完我 review，合入后继续下一个。这种节奏下，它没有一次让我后悔过把活交给它。如果你也想试，记住最核心的一件事：把它当作风控严格的工程师，而不是无所不能的自动补全器——给它清晰的约束，让它自己跑通验证，然后严格 review 它碰过的每一行。这四步做到位，Codex 从代码生成大模型到软件工程智能体的这条演进，就会真正变成你日常开发的一部分，而不是又一个尝鲜后吃灰的玩具。