Codex 关键功能说明书
—— 从会用到用得好
一、Codex 到底是什么
Codex 是一个运行在终端里的 AI 编程助手，不是聊天机器人，也不是 IDE 的自动补全。
它的工作方式很简单，就四个字循环：Think → Act → Observe → Repeat。
- Think：拿到你的需求，分析上下文，想清楚怎么干
- Act：调用工具去执行——读文件、改代码、跑命令、查日志
- Observe：看执行结果，判断对不对、要不要修正
- Repeat：对了就继续下一步，不对就调方向再来
本质上，Codex 模拟了一个人拿到任务后的操作流程：先看看项目长什么样，再想方案，然后动手改，改完验证，验证通过交付。区别只是——它跑得比你快，但判断力还是需要你把关。
理解了这四个字，后面所有功能其实都围绕着"它能怎么 Think、它能怎么 Act、它能怎么 Observe"展开的。
二、必会清单 —— 这几个你必须知道
① apply_patch —— 它改代码的唯一方式
Codex 不会像人一样打开你的编辑器删删改改。它用 apply_patch 生成一个精确的 diff 片段，指定改哪个文件、第几行、把什么替换成什么。
你会经常看到这种格式：
*** Begin Patch
*** Update File: src/main.py
@@ -10,3 +10,3 @@
- def get_user(id):
+ def get_user(user_id):
*** End Patch
这里 - 是删掉的行，+ 是新增的行。Codex 每次改代码都会出这样的 patch，改完直接生效到你的文件里。你随时可以在编辑器里看到改动，不满意就撤回。
② exec_command —— 它在终端的双手
Codex 帮你跑一切终端命令：装依赖、跑测试、搜索代码、查看 git 历史、执行脚本。你不需要自己敲命令，告诉它要干嘛，它自己拼命令、自己执行、自己看结果。
背后的原理是它把每个命令当作一个独立的决策步骤：先判断要跑什么，跑完读输出，根据输出决定下一步。这和人在终端里"敲命令→看报错→修→再跑"的流程一样。
一个关键点：危险操作会触发沙箱保护或弹确认框。这不是 bug，是你的安全网。
③ 沙箱机制 —— 你的安全底线
Codex 跑在一个受限环境中。它可以：
- ✅ 读工作目录里的文件
- ✅ 写工作目录里的文件
- ❌ 随意操作系统文件
- ❌ 随意联网下载
当它确实需要做越权操作（如下载依赖、写系统临时目录），会弹窗让你确认。你批准的指令可以被记住，下次同类操作不再打扰你。
原理上，沙箱是通过文件系统权限 + 命令前缀规则来实现的。每个命令在执行前会被拆成独立段，逐段检查是否需要审批。
④ 读文件和搜索 —— 一切操作的前提
Codex 干活前必须先"看懂"你的项目。它主要用两个工具：
rg（ripgrep）：比传统 grep 快一个数量级的文本搜索cat/文件读取 API：精确读取指定文件的内容
你用不着手动喂代码、手动贴路径。告诉它"帮我在用户模块加个登录校验"，它会自己去搜相关的路由、中间件、数据库调用，然后才动手改。
三、重要清单 —— 会了效率翻倍
① Plan（计划/TODO）—— 别让它摸着石头过河
复杂任务 Codex 会自动生成分步计划，每一步标状态：pending、in_progress、completed。你能实时看到它先做什么、后做什么、哪步卡住了、为什么调了方向。
这同样也让 AI 工作更有条理。就像人做事，把大问题拆成小问题，逐个击破，比一次性闷头干出错率低得多。
② AGENTS.md —— 给 Codex 写一份项目说明书
在你的项目根目录（或任意子目录）放一个 AGENTS.md 文件，告诉 Codex：
- 项目的目录结构是怎么组织的
- 有什么编码规范、命名约定
- 测试怎么跑、构建怎么搞
- 哪些文件不能动
Codex 每次操作这个目录范围内的文件，都会遵守你写的规则。越深处的 AGENTS.md 优先级越高。
这可能是性价比最高的提效手段。花五分钟写清楚，每次协作都受益。没有它，Codex 就只能靠猜。
③ Skills —— 垂直场景的专业工具
Skills 是热插拔的能力模块。比如：
- documents：创建和编辑 Word 文档
- pdf：读取、生成、验证 PDF
- presentations：做 PPT
- spreadsheets：搞 Excel
- browser：控制浏览器操作
- imagegen：生成图片
每个 Skill 自带一份详细的 SKILL.md 操作指南。你用 $技能名 或在对话里提到相关任务，Codex 就会加载对应 Skill。
不用的时候它们安安静静在那，不占任何资源。
④ 审批模式 —— 掌控权永远在你手里
Codex 有四种模式：
| 模式 | 行为 | 适合谁 |
|---|---|---|
| never | 全部自动跑，不问 | 老手、信任的场景 |
| on-failure | 只失败了才问你 | 有一定经验 |
| untrusted | 每个操作都确认 | 新手推荐 |
| on-request | Codex 自己判断要不要问 | 折中选择 |
如果你是初学者，建议用 untrusted。每一步都能看到它在干什么，出错了也知道哪个环节的问题。等你熟悉了它的行为模式，再逐步放开。
四、可以放一放 —— 不急于入门就学的
自定义插件
能自己开发插件扩展 Codex 功能，但需要写配置清单、理解目录结构、有时还得处理缓存刷新。先把手头的基础功能用熟再说。
MCP 服务器
让 Codex 连接外部服务（数据库、API、各种数据源）的协议。功能很强，但配置有技术门槛，不是开箱即用的体验。
自动化 / 定时任务
定时监控、自动提醒、多线程协作这些功能，等你成了重度用户再研究。初期先把单次协作的流程跑顺畅。
五、避坑指南 —— 踩过的人最多就这几点
① 上下文窗口不是无限的
有些模型宣传百万 token 上下文，但 Codex 实际分配给你这轮对话的预算有限。别一次塞太多文件、提十几个需求。把大任务拆成小任务，分多轮给，效果好得多。
② Codex 不会自动 git commit
它只生成代码、修改文件，但不会帮你做版本管理。提交、回滚、分支管理都是你自己的事。好习惯：每次改完先 git diff 看一眼，满意了再 commit。
③ 沙箱会拦截网络操作
这是设计如此，不是 bug。你在命令行里下载依赖没问题，但 Codex 在沙箱里去下载可能会被拦。遇到这种情况它会提示需要权限，你同意就行。
④ 别让它猜你的意图
模糊的需求 = 跑偏的结果。"帮我修这个 bug"太泛，"用户登录接口返回 500 错误，帮我在 auth.py 里找原因并修复"就明确了。AI 不读心——信息给到位，产出才精准。
六、一点感受
Codex 跟我们习惯的工具很不一样。它不是自动补全，不是问答机器人，也不是替你写代码的黑箱。它更像一个坐在旁边的程序员搭档——你做决策，它去执行；你定方向，它干苦力。
先掌握必会清单里的四个东西：apply_patch、exec_command、沙箱机制、读文件。然后试试写个 AGENTS.md，用 Plan 管理复杂任务。等基本的协作节奏找到了，其他功能慢慢探索就行。
不用全会，用着用着自然就熟了。
