一个能自己翻代码、写代码、跑测试、修 bug 的终端智能体，听起来像噱头，但我用 Codex 跑完几个真实项目之后，可以负责任地说：它把这条链路真的跑通了。这篇实战教程我不想写成一份功能清单式的说明书，而是把它拆成一条完整的上手路径——从安装环境、理解工作方式，到用一个真实小项目走完迭代闭环，再到高频报错排查和高阶玩法，全部是我自己踩过坑之后的整理。适合已经会用终端和 git、想试试 AI 编码智能体到底能帮到什么程度的开发者，也适合想给团队引入类似工具的技术负责人。
Codex 不是那种“在编辑器里给你补全下一个单词”的助手，它是一个运行在终端里的 AI 编程智能体。你把任务交给它之后，它会自己读文件、规划修改、执行命令、看报错、再改代码，直到任务完成为止。整个过程你也可以随时插话、批准、否决。下面直接进入正题。
1. 先搞清楚 Codex 到底是个什么玩意
1.1 一句话定位：它是能动手干活的智能体，不是聊天框
我见过不少朋友第一次用 Codex，习惯性地把它当成一个终端版聊天机器人：问一句“这段代码什么意思”，它答一句，然后对话结束。这完全低估了它的设计目标。Codex 的核心能力不是“回答”，而是“执行”。你给它一个目标，比如“修复测试里那两个失败的用例”，它做的不是给你解释失败原因，而是自己去读测试代码、找源文件、改代码、跑测试、确认通过。
本质区别在于：传统聊天式 AI 把“写代码”当作文字生成，而 Codex 把“改代码”当作一连串可执行动作的组合。它通过命令行接口直接接触文件系统、git 状态和本地环境。这意味着它能做的不只是写函数，还包括创建目录、修改配置、运行测试、查看错误输出、回滚自己的改动。
我用过一个很直观的类比：它像一个阅读速度快、打字快、但偶尔会自作主张的实习生。你给它一份清晰的说明书，它能完成一整套工序；你不给说明书，它也敢硬着头皮干，然后干出一堆需要你擦屁股的事。
1.2 它和 IDE 补全插件的本质区别
传统 AI 补全插件的工作方式，是盯着你光标所在的位置，预测你接下来要敲的字符。它能给你省掉很多样板代码，但不会替你完成跨文件的修改任务。比如“把整个模块的错误处理改成统一返回自定义异常类”，这种任务补全插件没法做，因为它的视野根本不在整个项目的层面。
Codex 的视野是整个工作目录。它会先看项目的文件结构，阅读相关文件内容，理解现有的代码风格，然后才动手改。补全是“帮你打字”，Codex 是“帮你完成工序”。
具体到日常感受上，我举一个例子：我在一个项目里发现日志格式不统一，有些地方用print，有些地方用标准库的logging。我直接对 Codex 说：“把项目里的print调试信息统一替换成logging，保持输出格式一致，改完跑一遍测试。”它会把涉及的文件列出来，逐个改，然后跑测试给我看结果。这种事情以前我自己做要花半小时，而且容易漏。
1.3 合适场景与不合适场景
先说合适场景。小到批量重命名文件、补充函数 docstring、生成单元测试，大到跨文件小重构、修复失败的 CI 脚本、迁移配置格式，这些都是 Codex 的强项。这类任务的共同点是：边界清晰、约束明确、可以通过测试来验证结果。
再说不合适场景。如果你给它一个几百万行的遗留系统，让它“优化一下性能”，它大概率会陷入迷茫。原因很简单：上下文窗口有限，它没法一次性读完整个项目；业务上下文缺失，它不理解系统的领域逻辑；没有测试保护，它改了之后没人告诉它改坏了多少东西。我第一次让 Codex 处理一个大型老项目的重构时，它自信地改了几个文件的函数签名，结果连锁报错一片。不是它蠢，而是我在一个不适合的场景里用了它。
所以，使用 Codex 的第一原则是：给它一个边界清晰、可验证的任务，而不是一个宏伟的蓝图。把它当执行力强的实习生，别把它当架构师。
2. 环境准备与安装排坑（新手最容易卡死的地方）
2.1 前置条件：软件与服务开通
Codex 的运行依赖云端模型服务，所以你的机器必须能正常联网，离线环境就别折腾了，它的核心逻辑就是本地执行、云端推理。除此之外，你需要准备三样东西：
- 一台能用终端的电脑。macOS、Linux 都顺畅，Windows 我建议用 WSL，纯 Windows 命令行环境我没测过。
- Node 环境和包管理器。Codex 的 CLI 通过 npm 分发，装的时候我会确认 Node 版本够新，至少不要低于官方要求的底线。
- git。这个很重要，不只是版本控制，Codex 会依赖 git 状态来判断工作目录是否安全、是否有改动冲突。有 git 兜底，你才能放心让它放手干。
基本终端操作能力也是必需的。你至少要知道cd、ls、git status这些命令，别拿到工具之后第一步就被环境卡住。
2.2 安装、验证与登录
安装本身不复杂，一行命令搞定：
npm install -g @openai/codex装完之后先验证版本，确认命令已经进入 PATH：
codex --version能输出版本号，说明安装成功。接下来是登录鉴权：
codex login这一步会打开浏览器让你完成授权，授权成功后终端会显示登录的用户信息。登录凭证会持久化在你的本地配置目录里，所以下次打开新终端一般不需要重新登录。但如果你换了电脑、重装了系统，就得重新走一遍登录流程。
我不建议在多台机器之间复制登录令牌，这属于能省则省的坑。真出了问题，重新登录的成本很低，没必要冒凭证泄露的风险。
2.3 工作目录规划与 git 仓库隔离
很多新手上来就在一个塞满 node_modules、venv、缓存文件的目录里跑 Codex，结果它光读取文件树就已经快被淹没了，表现就是反应迟钝、上下文不够用、甚至改错文件。这个问题的根源不是 Codex 能力不行，而是工作目录太脏。
我的习惯是：每个任务都用独立的临时目录或独立的小仓库。目录里只有相关源码、测试、配置文件和一份专门给 Codex 看的说明文档，其余无关文件全部清掉或用.gitignore排除。
还有一个容易翻车的细节：Codex 默认会检查当前目录是不是一个 git 仓库。如果它不是 git 仓库，执行任务时会报错，需要额外加参数跳过这个检查。但我从不跳，因为 git 仓库给了 Codex 一个“改坏了能还原”的保障。它跑完一轮，我git diff一看，所有改动干干净净地摆在眼前。
3. 核心运行机制：AGENTS.md、会话与权限控制
3.1 AGENTS.md 是真正的项目大脑
用过几次 Codex 你就会发现，它表现好坏的最大变量，不是你给它的那几条临时指令，而是项目根目录下有没有一份AGENTS.md。
AGENTS.md是 Codex 每次进入项目时自动读取的说明文件。你可以把它理解成一份“给智能体看的项目说明书”：技术栈是什么、依赖怎么装、测试命令是什么、代码风格有什么约束、哪些事情绝对不能做。Codex 会把这些当作行动准则，在规划任务和写代码的时候自动遵守。
我在一个 Python 项目里写的 AGENTS.md 大致长这样：
# 项目说明 这是一个基于 Python 3.11 的命令行工具，依赖管理使用 uv。 ## 常用命令 - 运行测试: uv run pytest - 格式检查: uv run ruff check . - 启动应用: uv run python -m app ## 代码风格 - 所有函数必须有类型注解 - 路径操作一律使用 pathlib，不用 os.path - 不允许使用全局可变状态 ## 禁止事项 - 不修改 tests/ 目录下的现有测试 - 不添加新的第三方依赖 - 不删除历史脚本，即使它们看起来没用为什么这份文件的价值这么高？因为大模型对你项目的了解完全来自你提供的上下文。你写清楚约定，它就会按约定执行；你不写，它每次都会基于“通用经验”自由发挥。通用经验在通用场景里好使，在你的项目里很可能水土不服。
AGENTS.md 还能沉淀团队规范。把这份文件提交到仓库里，每个克隆这个仓库的人，在本地跑 Codex 时都会自动获得相同的行为约束。这比在群里反复强调“代码风格要注意”高效得多。
3.2 会话的三种启动方式与恢复
Codex 的会话机制我总结下来有三种用法，对应不同场景：
第一种是交互式模式，直接在终端输入codex进入 TUI 界面。在这种模式里，你会看到一个对话框，还有一个实时面板展示 Codex 正在做什么——读取了哪个文件、计划执行什么命令、产生了什么输出。你可以边看边干预，随时纠正方向。我大部分重活都在这个模式下干，因为控制感最强。
第二种是单次执行模式：
codex exec "为这个项目补充单元测试，覆盖正常、边界和异常三个分支" --sandbox workspace-write这种模式适合批量任务和脚本化场景。它跑完就退出，不需要你盯着交互界面。
第三种是恢复会话。之前跑会话中断了，或者隔了半天想接着之前的上下文继续，可以执行：
codex resume它会把你没结束的会话重新拉起来。我实测中断恢复之后，它还能记得之前的对话内容，不用重新解释一遍任务背景。
3.3 权限审批模式：读、写、执行，怎么放权才安全
Codex 默认不是“全自动乱跑”的。它在执行敏感操作时会停下来征求你同意。我遇到的审批动作大概分三类：读文件、写文件、执行命令。
在交互式界面里，Codex 要执行某个操作时，界面上会显示即将进行的动作，你按a放行，按r驳回。刚上手的前几次，我的建议是全部手动审批，一条一条看它到底想干什么。这不是浪费时间，而是建立“模型信任感”的过程。
等你对它的行为模式有数了，再考虑调整授权策略。比如可以先放开“读文件”的审批，让它的探索过程更流畅；再逐步放开“写文件”和“执行命令”的审批。千万不要一上来就全自动，除非你非常清楚自己在干什么，而且项目有完善的测试兜底。
我个人见过最惨的翻车现场，是有人在一个没有测试保护的项目里给了 Codex 完全自动权限，让它做一次“简单重构”。结果它改了十几处函数调用，中间某个环节理解偏差，最终测试全红，代码已经改成一坨难以回退的状态。不是不能恢复，而是恢复成本远高于一开始多点几次手动批准。
3.4 沙箱与全自动的安全边界
Codex 提供了沙箱参数，用来限制它能触碰的文件范围。我常用的两档是只读和当前工作区可写。如果你不想让它碰工作目录之外的任何东西，就用只读模式；如果任务需要创建脚本文件、生成输出，那就用当前工作区可写。
真正危险的选项是“完全放开访问”那档，它意味着 Codex 可以读写你机器上的任何文件。不管是谁给你的教程里写了多香的自动化流程，我建议你保持敬畏。全自动模式最适合的场景是：任务极其明确、测试非常完善、并且你做好了跑完立刻 review 的准备。
哪怕用全自动模式跑完，我也有一个雷打不动的习惯：马上git diff看一遍所有改动。这个动作花不了几分钟，但它能让你在问题爆炸之前发现异常的修改。
4. 实战：让 Codex 从零搭一个文件批量整理工具
4.1 场景设定与准备工作
单靠讲概念很难建立直觉，我拿一个实际跑过的模拟项目来完整演示一遍。场景是这样的：某个目录下散落着一百多个从相机导出的文件，命名是IMG_0001.JPG、IMG_0002.MOV这种，完全看不出内容。需要写一个工具，把文件按拍摄时间重命名成20240101_121530.JPG这种格式，遇到重名自动加序号，并且禁止修改原文件内容。
这个场景看着小，但链路非常完整：读文件信息、写新文件名、处理冲突、写测试、跑验证，覆盖了 Codex 的典型工作流。
我先建了一个任务目录，在里面初始化了 git 仓库。然后写了一份针对这个场景的 AGENTS.md：
# 批量文件整理工具 - 脚本语言：Python 3.11 - 输入目录：./input - 输出目录：./output（不存在则创建） - 重命名规则：按照片拍摄时间格式化为 YYYYMMDD_HHMMSS.ext - 冲突策略：如果目标文件已存在，追加 _1 _2 后缀 - 测试命令：python -m pytest tests/ ## 禁止事项 - 不修改输入目录里的原始文件 - 不覆盖已存在的文件 - 不向终端输出额外日志之外的内容4.2 第一轮：先要方案，再让它动手
进入交互模式之后，我没有直接说“给我写个脚本”，而是给了它一段约束更强的话：
“这是一个批量文件整理任务。先不要写代码，先输出你的实现方案：你会怎么读取拍摄时间、怎么处理没元数据的文件、怎么解决重名冲突、怎么验证结果。我确认方案之后你再动手。”
这一步非常关键。很多人第一次用 AI 编程，上来就让它写代码，结果它写完一版，你发现问题，它再改一版，来回好几轮，比你自己写还慢。先要方案，可以让它在动手之前暴露错误假设。
Codex 给出的第一版方案是：用 Python 的 exif 库读取 JPG 的拍摄时间，用 ffmpeg 读取视频元数据。方案整体合理，但有个在我的场景里不可接受的假设：它默认所有文件都有拍摄时间，没有处理“文件没有元数据”的分支。我把这一点指出来，要求加一个兜底策略：读取不到拍摄时间的文件，放到一个unresolved/子目录，而不是报错中断。
这里就是人的价值所在：模型负责结构化的执行方案，你负责业务约束和异常边界。
4.3 第二轮：写代码、跑测试、迭代修复
方案确认之后，我让它动手实现，并且明确要求“写完脚本之后补一组测试，覆盖正常重命名、重名冲突、缺失元数据三个场景”。
Codex 生成脚本的过程，在界面上能看到它读文件、创建脚本、跑测试、看到测试失败、再修复的完整循环。第一版测试跑出来，有一个用例挂了——缺失元数据的分支里，它把文件复制到了unresolved/目录，但忘记保留原文件名，导致输出目录里出现了两堆毫无辨识度的file1、file2。
我没有直接告诉它怎么修，只把测试输出贴回对话框，描述了一句“这个分支的行为不符合预期：保留原文件名”。它看了报错，定位到对应代码，改了那一段，再跑测试，全部通过。
这个交互过程里最重要的是：Codex 每改一步，我都能通过git diff看到具体变化。它没有自作主张去动 AGENTS.md 里禁止修改的文件，行为在边界之内。
4.4 收尾：写说明文档和提交信息
脚本和测试都通过了，我让它顺手补了一份 README，说明脚本的运行方式、参数、输出结构。又让它根据当前改动生成了一版 commit message。这两个活儿属于纯文档工作，Codex 执行得很稳，基本不用改就能用。
最终我 review 了完整 diff，确认没有越界修改，然后git commit。整个项目从零到可用，大约花了一个多小时，其中大部分时间花在边界条件讨论和数据准备上，真正写代码的时间被大幅压缩。
这个案例最让我有体感的地方在于：Codex 不是“替你写代码”的工具，而是“陪你按规范写代码”的协作者。你负责定义规范、审核边界，它负责快速实现和自检。
5. 高频报错与排查思路速查表
用了一段时间之后，我把遇到过的典型问题整理成了一张排查表，按“表现 / 可能原因 / 解决思路”三列整理，遇到问题的时候直接对照着查。
| 表现 | 可能原因 | 解决思路 |
|---|---|---|
| 提示登录失败或凭据无效 | 登录状态过期、凭证损坏 | 重新执行登录命令，完成浏览器授权后再试 |
| 任务一直停在“等待审批” | 权限审批模式是手动档 | 在界面里按放行键，或调整授权策略 |
| 执行命令时提示权限不足 | 沙箱限制访问范围 | 检查沙箱参数，必要时放宽到当前工作区可写 |
| 会话突然中断，上下文丢失 | 网络波动或进程被关闭 | 用恢复命令把会话拉起来，通常能记住之前内容 |
| 它“看不懂”项目结构，答非所问 | 工作目录太脏，上下文被无关文件挤占 | 清理目录、写 AGENTS.md、把无关文件加进忽略规则 |
| 改了一些不该改的文件 | AGENTS.md 里没写明禁止事项 | 在 AGENTS.md 里补充“不修改某目录”的约束 |
| 测试反复失败，它越改越乱 | 任务目标不清晰，或测试本身有歧义 | 先把失败信息贴给它，明确描述预期行为，再让它小步修改 |
| 离线环境下完全无法使用 | 它依赖云端模型推理 | 只能在联网环境下运行，离线替代方案不推荐折腾 |
这张表里最有价值的其实是中间几行。我一开始遇到“它改了不该改的文件”时，第一反应是责怪模型不聪明。后来才发现，根源是我根本没在 AGENTS.md 里写“不要改配置文件”。模型在缺乏约束的情况下，选择改某个文件是非常合理的。你给了它边界，它才可能守住边界。
排查这类问题有个通用顺序：先看 AGENTS.md 写没写清楚，再看 git diff 确认它到底动了什么，最后才是考虑模型能力问题。绝大多数“AI 乱来”的情况，前面两步都能找到答案。
6. 高阶玩法：批量任务、多文件重构与团队规范
6.1 用 exec 模式做批量任务
如果你的工作流里有一堆小任务，比如给十几个模块各补一段规范头注释、批量格式化代码、把一整套测试文件从 unittest 迁移到 pytest，一个个在交互模式下聊太费时间。这些场景适合用 exec 模式批量跑。
codex exec "为 src/ 目录下的所有 Python 文件补充模块级 docstring，说明模块职责" --sandbox workspace-write codex exec "为 utils 模块补充单元测试，覆盖空输入和超大输入两个边界" --sandbox workspace-writeexec 模式的输出可以直接重定向到文件，方便脚本化记录。我试过同时开几个终端并行跑不同目录的任务，只要确保不同任务改动的是不同文件，冲突概率很低。如果两个任务同时改同一个文件，大概率会互相踩，那就得不偿失了。
6.2 多文件重构的正确姿势
重构是最考验 Codex 使用技巧的场景。一上来就让它“重构整个模块”，不是不行，而是容易失控。我总结出来的正确姿势是：把大重构拆成小步，每一步之间都保持代码可运行。
举个例子，假设要把一个 Flask 项目从旧的装饰器鉴权模式迁移到统一的依赖注入鉴权，我不会让 Codex 一次改完。我会把任务拆成：第一步，梳理现有鉴权逻辑，列出所有受影响的文件和调用链；第二步，先改核心鉴权模块，跑测试；第三步，再逐个改业务接口，每改一个跑一次相关测试；最后才统一清理旧代码。
Codex 在每一步里的角色都很明确：它是一个执行力强的程序员，但不是项目负责人。它能看到你给它看的文件，能沿着调用链改代码，但它看不到你脑子里的整体规划。你要做的是把规划拆成它能理解的步骤，然后逐步喂给它。
有一个口诀我一直在用：小步快跑，每一步都能跑通测试，永远不要把项目留在一半改不动也没法回退的状态。
6.3 把 AGENTS.md 提升为团队协作约定
AGENTS.md 的价值不止于个人项目。如果你们团队里所有人都用同一个 AI 编程工具，把项目约定写进 AGENTS.md 并提交到仓库，相当于给每个成员配了一个“默认遵守项目规范的 AI 助理”。
我建议在团队仓库的 AGENTS.md 里至少写四类内容：技术栈和依赖管理方式、常用命令清单、代码风格约束、明确禁止的操作。如果团队已有 lint 和格式检查工具，把它们的命令写进去，Codex 就会在完成代码修改之后主动跑检查。
还有一个细节：AGENTS.md 要放在 git 仓库里，并且纳入 review 流程。因为它的本质是“项目行为的可执行文档”，当项目约定变化时，AGENTS.md 也应该同步更新。我在团队里养成了一个习惯：每次技术决策变了，顺手更新 AGENTS.md，让每个后来的人都从文件里读到最新约定，而不是依赖口头传承。
6.4 我现在固定使用的完整工作流
走完一遍真实项目之后，我沉淀出了一套标准流程，现在每次用 Codex 都按这个来：
- 新项目先花五分钟写 AGENTS.md，明确边界和禁止事项。
- 交互模式下先向它要实施计划，确认边界后再让它动手。
- 逐步放权：先只允许读文件，再放开写文件，最后才放开命令执行。
- 每次它完成一个阶段，我看一眼
git diff，跑一遍对应测试。 - 中途不满意就让它停下来，调整指示再继续，绝不硬着头皮跑到最后。
- 全部完成后，用它的输出生成说明文档和提交信息，人工过一遍。
这套流程谈不上炫技，但它帮我避开了绝大多数“AI 乱改代码”的坑。核心逻辑很简单：代码可以交给模型写，但验收必须由人来做。模型负责速度和广度，人类负责判断和收口。
最后再说点实在的。我用了几个月 Codex 的体会是：它本质上像一个阅读速度快、执行速度快、但不太会主动质疑需求的实习生。你交代得越模糊，它越敢自由发挥，越容易顺手干出计划外的事情；你给它的约束越清楚，它的产出就越接近你真正想要的东西。
所以我现在无论多急，都会先花五分钟把 AGENTS.md 和本轮目标写清楚，再让它干活。这个习惯帮我省下的返工时间，远超那五分钟的投入。如果你想尽快体感它的价值，我建议第一周刻意用“先要方案、再分批放权、逐次审查”的节奏，把每一条改动都当成自己亲手写的那样去 review。跑完一个真实小项目，你会获得比看多少篇教程都更深的理解。
