Codex 使用简明教程：让 AI 真正帮你干活，而不是陪你绕圈

更新时间：2026-07-18

Codex 能读代码、改文件、运行命令、调用工具并持续排查，但它不会自动知道你的真实目标、项目边界和“做到什么才算完成”。

真正稳定的用法不是寻找一段万能 prompt，而是把不同信息放到合适的层级：

• 一次性要求放在当前 prompt。
• 长期硬规则放在 AGENTS.md。
• 长而低频的解释放在 docs/。
• 重复工作流做成 skill。
• 能机械判断的事情交给脚本、hooks 或 command rules。
• 外部系统通过 MCP、连接器或插件接入。
• 复杂且可并行的只读工作再考虑 subagents。

一句话概括：

• 你准备让 Codex 在真实 Git 仓库里读、改、测，而不只是回答问题。
• 你希望不同会话、不同开发者都遵守同一套项目边界。
• 你想减少重复 prompt，同时避免把整本规范塞进每一轮上下文。
• 你关心脏工作区、敏感信息、误提交、过度重构和“测试过了”这类模糊表述。

如果你只想问一个函数是什么意思，直接问即可；本文重点是持续、可验证的项目协作。

这张表最重要的原则是：一条规则只设一个主要归属，其他位置只保留触发条件和链接。复制得越多，漂移得越快。

下面是当前项目采用的结构，名称已经泛化：

只有 AGENTS.md、Codex 配置、skills、hooks、rules 和 custom agents 属于 Codex 能识别的约定表面；PLANS.md、docs/Codex工作规则/、路由脚本和测试文件都是这个项目自己的工程约定，必须由 AGENTS.md 或 skill 明确引用。

Codex 会在工作前读取生效范围内的 AGENTS.md。项目可以在子目录放更近的 AGENTS.md 或 AGENTS.override.md；更靠近当前工作目录的规则优先。

因此，根文件应该像机场指示牌：短、稳定、能指路。不要把它写成机场地下管线图。

一个公开安全的最小示例：

三个常见错误：

1. 把所有构建命令、设计规范和故障手册都塞进去。
2. 写“每次都全量构建、全量测试”，导致小改动成本失控。
3. 写成绝对承诺，却没有脚本或测试保证它真的执行。

长规则适合放进 docs/，但不要要求每个任务预加载整套目录。

当前项目采用一个索引页管理触发条件：

维护专题文档时遵循四条原则：

• 写长期稳定边界，不写单次任务流水。
• 当前代码和实测是事实基线，文档冲突时先查证。
• 正常流程放 skill，异常和解释放专题文档。
• 易变端口、会话名和凭证获取方式放本地脱敏记录，不写进公开规范。

Skill 是带元数据的可复用工作流。Codex 先看到 name、description 和路径，只有显式调用或任务匹配时才加载完整 SKILL.md；这叫渐进式披露。

仓库级 skill 放在 .agents/skills//SKILL.md。最小格式：

可选的 agents/openai.yaml 用于界面名称、默认 prompt、调用策略和工具依赖。它不是业务规则的第二份副本。

当前项目沉淀了四个高频 skill：

Skill 适合固定步骤，不适合模糊原则。一个流程如果重复出现、步骤稳定、做错有成本，就值得沉淀。

这是最容易被一行模糊规则带偏的地方：

“提交所有”也不等于可以提交本地记录、测试报告、缓存、构建产物、凭证和明显无关改动。

当前项目有一个自定义 scripts/codex-route.mjs。它不是 Codex 内置功能，而是把“路径 → 风险 → 专题文档 → 最小验证”机械化的工程模式。

常用方式：

输出示意：

使用它时必须记住：

1. --changed 不知道哪些改动属于当前任务，先看 git status --short 和关键 diff。
2. 路由按路径给出下限，不能替代代码语义、用户授权和运行态验收。
3. 配置文件不能只按扩展名判断。认证、权限、构建、部署和敏感运行配置应上调风险。
4. git diff --check 不覆盖暂存区和未跟踪文件；提交前还要运行 git diff --cached --check，并检查新文件。
5. 路由建议的是命令，不代表命令已经执行。

当前项目使用的风险语言：

这套分级是项目约定，不是 Codex 内置等级。

Hooks 和 Rules 都有价值，但不能把它们写成“装上就绝对安全”。

Hooks 可以在工具调用前后、权限请求、用户提交 prompt、subagent 停止或当前任务停止时执行命令。

当前项目用：

• PostToolUse：跟踪部分写工具和 Git 命令，提醒本地目录被暂存。
• Stop：在满足条件时写最小脱敏归档，或因附件复制继续一轮。

最小配置示意：

边界同样重要：

• PostToolUse 是事后反馈，不能撤销已经发生的副作用。
• Matcher 只覆盖列出的工具；Shell 仍可能通过其他方式写文件。
• 项目 Hook 必须在可信仓库中加载；非托管命令 Hook 的新增或修改还要按定义重新审核信任。
• transcript_path 的 transcript 格式不是稳定接口，不应把完整解析当成永久兼容协议。
• Hook 自测只能证明脚本逻辑，不等于 Codex 生命周期端到端已经验收。

自动归档是这个项目的可选模式，不是 Codex 内建最佳实践。若团队采用，至少要明确用户知情、白名单字段、脱敏失败策略、本地私有目录、访问权限、留存期限和删除办法。不要默认复制完整 transcript。

Rules 当前仍是实验功能，只控制 Codex 请求在沙箱外运行的命令。它按参数前缀匹配，最严格的决策优先：

• allow：允许。
• prompt：每次询问。
• forbidden：阻止。

示例：

修改后用实际规则引擎检查：

一条 pattern = ["cat", ".env"] 只能拦截这个精确参数前缀，挡不住 sed、Python、绝对路径或其他工具读取。Rules 不是文件权限、沙箱、DLP、业务鉴权或代码审查的替代品。

项目级 .codex/config.toml、Hooks 和 Rules 都只在项目 .codex/ 层受信任时加载；Rules 修改后需要重启 Codex。

下面是基于当前项目、为公开读者收紧后的配置骨架；数值是项目选择，不是通用最优默认：

说明：

• project_doc_max_bytes 限制项目说明进入初始指令的字节数；它不是“越大越好”。
• tool_output_token_limit 控制单项工具输出保留预算；真正的专项测试仍应尽量输出精炼结果。
• max_depth = 1 允许根任务创建直接 subagent，但不继续嵌套。
• 示例用 prompt 作为公开保守值。只有充分审查工具语义后，才考虑更宽松的批准模式。
• 个人偏好可以放用户级配置；凭证值不要写进项目或全局 TOML。优先用 OAuth、系统 Keychain、credential helper 或环境变量引用。

本地仓库事实优先读文件和命令。GitHub、Figma、Notion、浏览器、内部文档和其他外部系统，更适合通过 MCP、连接器或插件访问。

使用 MCP 前回答三个问题：

1. 它只读，还是会写外部系统？
2. 它的认证由 OAuth、环境变量引用还是系统凭证管理器提供？
3. 哪些工具需要逐次批准，哪些可以自动运行？

不要把 token、cookie、私钥或静态认证头直接写进仓库配置。

当前项目定义了三个只读审查角色：

• 架构边界审查。
• 安全与脱敏审查。
• 测试与验收审查。

Custom agent 文件只是角色定义，不会因为存在就自动执行。应由 prompt、AGENTS.md 或 skill 在合适任务中请求调度。

适合并行：

• 多个独立代码区的只读探索。
• 安全、架构、测试三个互不重复的审查角度。
• 独立日志或测试结果分析。

谨慎并行：

• 多个代理同时编辑同一文件。
• 子任务依赖前一个子任务的结论。
• 需要一个统一数据迁移或回滚决策的高风险变更。

Subagents 会增加 token 与协调成本。并行是为了隔离噪声和加速独立工作，不是为了让任务看起来更热闹。

PLANS.md 是项目自定义模板，不是 Codex 自动识别的特殊协议。当前项目只在这些情况下使用：

• 用户明确要求先计划。
• 目标、授权或验收标准未决，合理假设会显著改变结果。
• 同时跨越两个以上主要边界，需要协调顺序或回滚。
• 涉及迁移、权限、公开协议、共享主协议、发布、同步、部署或回滚。

单文件低风险修改、普通评估和仅仅使用并行审查，不自动触发计划。

一个有效计划至少回答：

计划服务于行动，不是为了写一份看起来很忙的阶段报告。

直接写清动作边界，例如：“只读整理提交范围”“只创建本地 commit，不要 push”或“只推送已有提交，不要 stage/commit 工作区”。把授权写清楚，比事后问“你怎么推上去了”便宜得多。

“已验证”必须说明验证对象、命令、结果和未覆盖范围。

当前项目中的真实示例：

公开教程不能假设每个仓库都有这些脚本。使用前先读 package.json#scripts、Makefile 或项目说明；不要凭习惯编造 npm run typecheck。

还要区分三种表述：

• 静态验证完成：diff、语法、类型或文本检查通过。
• 运行态已验证：真实打开目标页面、操作交互或请求目标 API。
• 人工验收建议：交给用户执行的步骤，尚未执行。

只有真实做过第二项，才能写“运行态已验证”。

生产构建不是普通开发任务的默认验证。它可能耗时、覆盖开发缓存或改变当前服务状态；只有构建本身在范围内时才运行。

建议固定这些底线：

• 不读取、输出或提交明文 token、cookie、密码、私钥和连接凭证。
• 不把秘密写进项目或用户级 config.toml；配置只引用安全来源。
• 不把完整用户隐私、生产 payload、敏感正文或原始内部日志写进公开文档。
• 不用 git reset --hard、git checkout -- 或递归删除来“清理”不明工作区。
• 不把本地记录、报告、缓存、构建产物和附件默认提交。
• 数据库、部署、生产环境和外部写操作需要与任务匹配的明确授权。
• Rules 和 Hooks 是辅助防线，不替代最小权限、沙箱、服务端鉴权和人工审查。
• 浏览或引用外部最新信息时优先使用官方来源；内部项目事实优先看当前源码。

不需要第一天就搭完整自动化：

1. 写一个不超过一两页的根 AGENTS.md。
2. 放入 3 到 6 条真正不可突破的架构和安全红线。
3. 把真实测试、类型检查和启动入口写清楚。
4. 建一个专题索引，不让长文档默认全量加载。
5. 同一流程重复两三次后再做 skill。
6. 路径与验证映射稳定后再做路由脚本。
7. 危险命令模式稳定后再加精确 Rules，并用 execpolicy check 测试。
8. 生命周期需求明确后再加 Hooks；先处理信任、隐私、失败和兼容性。
9. 外部实时事实和动作通过 MCP/连接器接入。
10. 多个独立只读问题出现时，再引入 custom agents 和并行调度。

先让 Codex 稳定做到“范围清楚、改动可查、验证真实、结果说清”，再追求自动化。

• 任务类型、目标入口、不做范围和授权是否明确？
• 工作区已有改动是否保持原样并排除在本轮之外？
• 是否沿用现有模块和数据流，没有夹带无关重构？
• 是否没有暴露秘密、私密正文和本机信息？
• 路由或风险判断是否只覆盖本轮范围，并按语义上调？
• 是否有针对真实行为的专项验证？
• 静态、运行态和人工验收建议是否区分清楚？
• staged 文件与授权是否一致，且排除了本地记录和生成物？
• commit 与 push 是否分别得到明确授权？
• 是否说明改动、实际验证、未验证项和剩余风险？

版本敏感能力以官方文档为准：

• Customization overview
• Custom instructions with AGENTS.md
• Build skills
• Hooks
• Rules
• Subagents
• Model Context Protocol
• Configuration Reference

Codex 最擅长的不是替你猜完所有需求，而是在目标、边界和反馈清楚后，把具体工作推进得又快又稳。

你负责方向、授权和完成标准；Codex 负责读事实、做改动、跑验证、暴露风险。方向盘仍在人手里，油门才值得踩下去。