前言
Codex 看起来很像另一个 AI 编程助手。
能写代码，能解释代码，能补文档，能帮忙看报错。听起来和很多工具差不多。
但用一段时间后，会发现 Codex 的重点不在「多补几行代码」。它更像是被放进项目现场里的一个人：能看文件，能改文件，能跑命令，能看到构建失败，然后继续往下修。
这也是我觉得 Codex 值得单独写一篇文章的原因。
它不是一个适合拿来闲聊的工具。它最好用的时候，是手上已经有一个具体任务：修一个页面、补一组测试、整理一篇文章、排查一次部署、review 一次改动。
OpenAI 官方文档把 Codex 叫做 coding agent。这个说法其实挺准确。它不只是生成代码，而是参与一段工程流程。
下面这篇不是文档翻译。我查了 2026 年 6 月 6 日的 OpenAI Codex 官方手册，也看了几篇中文使用体验文章。最后还是按自己的理解重写成一份使用笔记：怎么把 Codex 用得更像一个能干活的同事，而不是一个回答问题的窗口。
1. 任务别直接扔成一团
很多需求会写成这样：
帮我实现用户登录功能
这句话不能说错，但太大了。
一个登录功能背后可能有表结构、接口、权限、前端页面、错误提示、测试、旧数据兼容。Codex 会努力做，但它很可能凭空猜一套方案，然后一路写下去。
我现在更常用的问法是：
检查项目结构，不要修改文件。告诉我这个功能会影响哪些地方。
这一步很有用。
它会去读目录，找配置，看技术栈，确认测试命令。现场讲清楚了，后面的改动会稳很多。
尤其是接手一个旧项目，或者隔了几周没碰的项目，让 Codex 做一次「看现场」，比直接让它改代码靠谱。
2. Codex 适合做一整段小闭环
过去用 AI 写代码，很多时候是在编辑器里补一段函数。
Codex 更适合这种任务：
给登录模块补测试，运行测试。如果失败，分析原因并修复。最后告诉我改了哪些文件。
这句话背后其实有好几步：
- 找到登录模块。
- 判断项目用什么测试框架。
- 写测试文件。
- 跑测试。
- 读失败日志。
- 修代码或修测试。
- 重新跑一遍。
- 总结 diff。
这就是 Codex 和普通聊天式工具的区别。它不只是在回答「测试应该怎么写」，而是在项目里把这件事做完。
当然，前提是任务不能太虚。
适合交给 Codex 的任务通常长这样：
修复 /search/ 页面 404。不要改主题源码。重点检查 content 页面、路由和 Hugo 配置。修复后运行 hugo 构建，并用本地预览确认页面能打开。
不适合这样：
优化一下博客
「优化」这个词太滑了。它可以是性能、样式、SEO、文案、配置，也可以什么都不是。
3. 好 prompt 不用很长，但要有四样东西
OpenAI 官方最佳实践里提到，给 Codex 的任务最好包含 Goal、Context、Constraints、Done when。
不用背英文。写的时候记四个问题就行：
- 要改成什么结果？
- 它应该看哪里？
- 哪些地方不能乱动？
- 怎么算做完？
比如：
当前 Hugo 博客点击搜索页会 404。
请检查 content、layouts 和 hugo.toml，找到原因后做最小修改。
不要改 themes/PaperMod 里的主题源码。
修复后运行 hugo --cleanDestinationDir --noBuildLock，并确认 /search/ 能打开。
这段话不优雅，但够用。
我以前会写很多背景，后来发现 Codex 更需要的是边界。它不怕任务普通，怕的是任务像半截微信消息。
4. Plan mode 不是装样子
复杂一点的任务，我会让它进入计划状态。
比如：
暂时不要改文件。请给出计划：会看哪些文件，可能怎么改，风险在哪里，最后怎么验证。
这能挡住很多无意义的返工。
有些任务一开始看起来简单，实际会牵扯一堆东西。比如「把文章列表改好看一点」，可能涉及主题模板、CSS、移动端布局、暗色模式、首页和归档页。直接开写，很容易半路发现方向不对。
Plan mode 的价值不是让流程变正式。它只是让 Codex 在动手前把脑子里的路线摊出来。
看到计划不对，马上纠正。比等它改完十个文件才回滚舒服多了。
5. 上下文要给准，不要给一堆
Codex 会自己读项目，但别让它大海捞针。
如果知道文件，直接点名：
重点看 content/posts/codex-guide.md、hugo.toml 和 layouts/partials/。
如果是报错，把完整报错贴出来。
如果是界面问题，截图比描述管用。
如果是网页问题，让它打开本地预览去看。Codex App 的 in-app browser 很适合这种事：本地 Hugo、Vite、Next.js 这类页面，打开以后直接检查路由、样式和交互。
我有个很简单的判断：自己都说不清相关文件在哪里，就让 Codex 查；已经知道入口，就别让它绕远路。
6. 权限别长期全开
Codex 能跑命令，权限就不能乱给。
官方文档里把权限拆成两件事：sandbox mode 和 approval policy。简单说，一个决定它能碰哪里，一个决定什么时候要问人。
日常常见三种：
| 模式 | 我会怎么用 |
|---|---|
| Read-only | 看项目、解释代码、做计划 |
| workspace-write | 日常改项目，最常用 |
| danger-full-access | 明确知道要跨目录、联网或做系统级操作时才考虑 |
workspace-write 通常够了。它能在工作区里读写文件、跑常规命令，越界时会停下来询问。
全权限确实省确认。但省掉确认，也省掉了护栏。
尤其是从网上拉来的仓库、没看过的脚本、需要联网的命令，我不建议直接全开。网页内容也要谨慎。官方文档提醒过，实时网页里可能有 prompt injection。别让一个网页里的奇怪文字影响本地项目。
7. AGENTS.md 是给 Codex 的项目便签
如果一条要求反复出现，就不要每次都写在 prompt 里。
比如这个博客项目，我经常会要求：
- 不改主题源码。
- 文章放在
content/posts/。 - 修改后跑 Hugo 构建。
- 中文文章少一点 AI 腔。
- Dock 在中文里写作「程序坞」。
这些就很适合写进 AGENTS.md。
一个简单版本：
# AGENTS.md
## 项目约定
- 这是一个 Hugo 博客项目。
- 不直接修改 themes/PaperMod 里的主题源码。
- 样式调整放在 assets/css/extended/。
- 文章放在 content/posts/。
## 验证方式
- 修改文章或配置后运行 hugo --cleanDestinationDir --noBuildLock。
- 涉及路由时，用本地预览确认页面能打开。
## 写作要求
- 中文文章少一点 AI 腔。
- 少用连续排比和空泛总结。
- 系统术语按中文界面写，例如 Dock 写作程序坞。
官方文档里提到，Codex 会在开始工作前读取这些文件。个人习惯可以放到 ~/.codex/AGENTS.md，项目规则放仓库里，子目录也可以有更具体的版本。
AGENTS.md 不要写成宣言。写命令、目录、限制、验收方式。越像项目便签，越有用。
8. Skills 适合处理重复手艺活
AGENTS.md 解决项目规则，Skills 更像一套固定手法。
比如「中文文章去 AI 味」这件事，如果每次都临时说：不要三段式、不要排比、少用然而此外、别太像说明书，迟早会漏。
做成 Skill 后，可以把判断标准、改写方法、禁用表达写进去。需要的时候直接调用。
适合做 Skill 的任务：
- 固定风格的文章改写。
- 周报、日报、公众号稿的固定格式。
- 某类项目的发布检查。
- 某个技术栈的 review 清单。
- 需要脚本配合的批量处理。
Skill 不靠长。边界清楚更重要。一个 Skill 解决一类问题就好。
9. MCP 是给 Codex 接外部眼睛
项目里的文件，Codex 自己能看。
项目外面的东西，就要靠工具。
MCP，也就是 Model Context Protocol，可以把外部工具和资料接给 Codex。官方文档里提到的例子包括开发文档、浏览器、Figma、Sentry、GitHub。
什么时候需要 MCP？
- 要查最新官方文档。
- 要看 GitHub issue 或 PR。
- 要读 Figma 设计稿。
- 要查 Sentry 里的线上报错。
- 要控制浏览器验证页面。
别为了显得高级就到处接 MCP。能用项目文件解决，就用项目文件。MCP 适合实时资料、授权资料和外部工具。
有副作用的工具调用要小心。改 issue、发消息、操作线上服务，这些都不是「点一下无所谓」的事。
10. App、CLI、IDE、Cloud 怎么选
我现在不会纠结哪个入口最好。不同场景用不同入口。
Codex App
适合长时间处理项目。
它有多线程、Local / Worktree / Cloud、diff、集成终端、in-app browser、Skills、Automations。写博客、改前端、检查页面、看 diff，我更愿意用 App。
尤其是前端任务，旁边开着本地预览，改完就看，比在终端里来回切舒服。
CLI
适合终端里顺手跑。
codex
也可以直接给一句任务：
codex "解释这个项目的启动流程"
CLI 里可以用 /permissions 切权限，用 /review 做审查，用 codex resume 恢复会话，用 codex exec 做非交互式任务。
IDE Extension
适合贴着代码改小范围问题。
选中一段代码，让它解释、补测试、改局部逻辑，这种场景 IDE 扩展最顺。
Cloud
适合把任务扔到远端环境里跑。
官方文档里说，Cloud 会克隆仓库，在隔离环境中处理任务。适合并行尝试方案，也适合从另一台设备委托任务。
但要记住：本地没提交、没推到 GitHub 的改动，Cloud 默认看不到。
11. Review 要单独拎出来
我现在不太喜欢让 Codex 一边写一边顺手 review。
写代码和审代码是两种状态。写的时候会顺着实现走，审的时候要专门找问题。
可以这样让它审：
Review 当前未提交改动。只输出 findings，按严重程度排序，重点看 bug、行为回归、安全风险和缺失测试。不要修改文件。
前端可以加：
重点看移动端溢出、键盘可访问性、空状态和加载状态。
后端可以换成：
重点看错误处理、权限边界、并发问题和数据库迁移风险。
官方文档里 /review 支持看未提交改动、commit，或者和 base branch 比较。这个功能值得单独用，不要只在最后说一句「看看有没有问题」。
12. 我会反复复制的几句话
看项目：
阅读当前项目结构，说明主要目录、启动方式、构建方式和最重要的约束。不要修改文件。
修 bug：
这个问题的现象是：{现象}。
相关报错是：{报错}。
请定位根因，做最小修复。修复后运行相关测试或构建命令，并说明验证结果。
改文章：
重写这篇文章。保留 front matter，正文重新组织。语气自然，减少 AI 味，不要频繁使用“你/你的”。写完后运行 Hugo 构建检查。
做前端：
优化这个页面的视觉效果。保留现有设计系统和组件结构，不引入新依赖。完成后打开本地预览检查桌面和移动端效果。
做 review：
Review 当前未提交改动。只输出 findings，按严重程度排序，重点看 bug、行为回归、安全风险和缺失测试。
沉淀项目规则：
根据这个项目的实际结构、构建命令、测试方式和我反复强调过的要求，生成一份简洁可执行的 AGENTS.md。不要写空泛原则。
13. 最容易翻车的地方
Git 状态不干净
让 Codex 大改之前，看一眼：
git status
至少知道当前有哪些未提交改动。否则改坏以后，很难分清哪些是原来的，哪些是 Codex 新改的。
任务太大
「实现用户系统」「优化整个项目」「重构前端架构」这种任务，不是不能做，但最好拆开。
拿到 Codex 的计划后，挑一个最小切口开始。
验证缺失
没有测试或构建检查，很多修改只是「看起来对」。
能跑测试就跑测试。没有测试，也至少跑构建、打开页面、检查命令输出。
多线程改同一批文件
Codex 可以并行开线程，但两个线程同时改同一批文件，冲突会很烦。
要并行，就拆清楚范围，或者用 Worktree。
长期开全权限
全权限省事，也容易让小问题变成大问题。日常项目没必要一直开。
14. 结语
Codex 用顺以后，感觉不像「问 AI 一个问题」。
更像是把一段杂活交给一个会读项目的人：看现场，做最小改动，跑验证，把结果说清楚。
它当然会犯错。会误解需求，会改多，会跑偏。所以人还是要定方向、看 diff、做取舍。
但如果把目标、上下文、权限和验收方式都放好，Codex 能接走很多以前很烦但必须做的活。
这就够了。