Codex 指令保姆级教程：新手常用命令、使用场景和避坑指南

Codex 指令的核心作用不是“让 AI 更会聊天”，而是帮你控制 Codex 在项目里的工作方式：读哪些文件、能不能改代码、用什么模型、怎么看 diff、何时做 review。新手先掌握十几个高频指令，就能把 Codex 从“会写代码的助手”变成可管理的项目协作者。

如果你刚开始用 Codex，最容易踩的坑不是不会写 prompt，而是不知道什么时候该让 Codex 停下来、先计划、先看权限、先检查改动。尤其是在真实项目里，Codex 可以读取仓库、修改文件、执行命令，能力越强，越需要边界。

本文围绕一件事展开：怎样用 Codex 指令安全、高效地完成一次开发任务。内容会覆盖 prompt 和 slash command 的区别、常用命令的使用场景、AGENTS.md 的写法、/side 和 /fork 的区别，以及改完代码后必须做的检查。

Codex 指令和普通 prompt 有什么区别

普通 prompt 是你告诉 Codex“要做什么”。例如：

帮我找出登录接口失败的原因，先不要改代码。

Codex 指令通常是以 / 开头的 slash command，用来管理“Codex 怎么工作”。例如：

/status
/model
/diff
/review

OpenAI 官方的 Codex CLI 文档把 slash commands 单独列为 CLI 的交互能力，其中包括会话状态、权限、文件引用、diff、review、fork、side conversation、AGENTS.md 初始化等功能。实际可用命令会受版本、配置、插件和当前客户端影响，所以本机里输入 / 看到的列表才是当前环境的准确信息。可以参考 OpenAI 的 Codex CLI 文档 和 Codex CLI slash commands 文档 做事实校验。

新手要记住一个判断标准：prompt 管任务，slash command 管工作台。

例如你要修一个 bug，prompt 负责说明目标、限制和验收标准；/status 负责确认当前模型、目录和权限；/mention 负责把相关文件交给 Codex；/diff 负责看真实改动；/review 负责让 Codex从审查角度再看一遍风险。

新手先掌握的 10 个 Codex 指令

/init：给项目写长期规则

/init 适合第一次进入一个项目时使用。它会在项目里生成或辅助生成 AGENTS.md，让 Codex 以后进入这个仓库时能先读取固定规则。

不要把 AGENTS.md 当成摆设。它应该写清楚四类信息：

## Commands
- Install: pnpm install
- Dev: pnpm dev
- Test: pnpm test
- Lint: pnpm lint

## Rules
- 不要修改 dist、build、generated 目录
- 优先复用现有组件和工具函数
- 业务逻辑改动后必须跑测试
- 改动保持最小，不做顺手重构

## Architecture
- API client 在 src/lib/api
- 页面路由在 src/app
- 通用组件在 src/components
- 权限逻辑在 src/auth

## Before finishing
- 说明改了哪些文件
- 说明跑了哪些测试
- 没跑测试时说明原因

/init 的价值在于减少重复解释。团队如果已经有统一的代码规范、测试命令、禁止修改目录，就应该沉淀进 AGENTS.md。这和 Jumei 这类需要标准化执行的团队流程很像：规则先固化，执行才稳定。做跨账号内容、素材、数据复盘时，也要把流程放进系统，而不是每次靠人记忆；可以参考 Jumei 的工作方式 来理解这种“先规则，后执行”的思路。

/status：先确认 Codex 站在哪里

/status 用来查看当前会话的模型、权限策略、可写目录、token 使用情况等信息。新手在以下场景应该先敲它：

/status

适合使用的场景包括：刚进入一个陌生项目、担心当前目录不对、不确定是否是只读模式、不知道模型是否适合当前任务、对话已经很长但还要继续改代码。

很多事故不是模型能力问题，而是上下文和权限没有确认。你以为 Codex 在 A 仓库，它可能在 B 目录；你以为它只能读，实际上它可以改；你以为它还记得前面的限制，但上下文已经接近上限。/status 是低成本的确认动作。

/model：小活别用重模型，大活别省模型

/model 用来切换当前会话模型。简单任务不一定需要最强模型，复杂任务也不要为了省成本让弱模型硬扛。

适合使用强模型的任务包括：

• 跨模块重构。
• 复杂 bug 定位。
• 不熟悉的大型代码库阅读。
• 数据迁移、权限、支付、安全相关修改。
• 需要先比较多种方案的架构调整。

适合使用轻量模型的任务包括：

• 改一处文案。
• 补一个简单测试。
• 修一个明显类型错误。
• 解释一个短函数。
• 写一个临时脚本。

一个实用规则是：如果任务失败会造成线上风险、数据风险、权限风险，就不要只看成本；如果任务只是局部、明确、可快速验证，就不要浪费强模型。

/permissions：先定边界，再让 Codex 动手

/permissions 用来调整 Codex 的审批和执行权限。OpenAI 文档里说明，用户可以通过该命令选择类似 Auto、Read Only 等权限预设，后续动作会遵守当前审批模式。

新手建议保守一点。陌生项目、生产项目、没有 git 管理的旧项目、数据库脚本、批量文件修改，都不适合一上来全自动。

更稳的方式是：

/permissions

然后选择更接近“先读、再确认、后修改”的模式。你可以先让 Codex 只分析项目结构，等它给出计划后再放开修改权限。

/plan：大任务先拆，不要直接改

/plan 适合用于复杂任务的前置拆解。它不是为了拖慢进度，而是为了防止 Codex 在还没理解边界时直接大面积改文件。

适合先用 /plan 的任务包括：

• 多文件重构。
• 迁移框架或 SDK。
• 修复原因不明的线上 bug。
• 优化性能瓶颈。
• 改权限、登录、支付、数据同步。
• 给旧项目补测试体系。

可以这样写：

/plan 先定位相关文件，给出最小改动方案，不要直接改代码。说明风险点和需要验证的命令。

计划阶段要看三件事：它有没有找到真正相关的文件；它的改动范围是不是过大；它有没有说清楚怎么验证。如果计划都说不清，直接让它改代码只会放大风险。

/mention：把上下文缩小到关键文件

/mention 用来把某个文件明确加入当前上下文。官方文档也把它定位为高亮或引用文件的能力，常见写法是：

/mention src/lib/api.ts

很多人把整个项目丢给 Codex，然后问“为什么它乱读”。更好的方式是先给错误日志、相关文件、配置文件和测试文件。

例如登录接口报错，你可以先 mention：

/mention src/app/login/page.tsx
/mention src/lib/auth.ts
/mention src/api/session.ts
/mention tests/auth.test.ts

这样 Codex 的注意力会集中在更小范围内，误改无关模块的概率也会下降。对于需要多团队协作的运营工具也是同理，流程越复杂，越要把输入边界缩小；Jumei 的 产品能力 也是围绕账号、流程、执行和数据边界来组织，而不是把所有动作混在一起。

/diff：不要只相信总结，要看真实改动

/diff 是新手最该养成习惯的指令之一。Codex 改完代码后，它的文字总结只能当索引，真正要看的还是 diff。

/diff

检查 diff 时重点看：

• 是否改了不相关文件。
• 是否新增了重复逻辑。
• 是否删除了边界判断。
• 是否引入了硬编码配置。
• 是否把测试改成了“迎合实现”。
• 是否出现无意义格式化导致的大面积 diff。

官方 slash commands 文档说明，/diff 会展示已暂存、未暂存以及未跟踪文件的变化。对新手来说，这一步就是“方向盘还在你手里”的证明。

/review：提交前让 Codex 换成审查视角

/review 用来让 Codex 审查当前工作树，重点关注行为变化、缺失测试、潜在回归等问题。更稳的组合是：

/diff
/review

先自己看真实改动，再让 Codex 用 review 视角补一遍。审查时不要只问“有没有问题”，要给它更明确的重点：

/review 请重点看行为回归、边界条件、缺失测试、安全风险和不必要的大范围改动。

如果 review 给出问题，不要急着让它全自动修。先判断问题是否真实，再让它只修确认过的点。对于需要稳定交付的团队，review 是成本最低的风险控制动作之一。

/compact：压缩上下文，不是重开任务

/compact 适合在一个任务做了很久、对话太长但还要继续时使用。它会把前文压缩成摘要，释放上下文空间。

使用前最好明确告诉 Codex 要保留什么：

/compact 保留当前目标、已修改文件、未解决问题、测试结果、用户明确禁止事项。

不要把 /compact 当成万能保险。摘要可能丢细节，所以关键限制要重新强调。比如“不要改数据库结构”“不要改线上 UI”“不要重命名接口”这类约束，压缩前后都应该明确。

/resume：跨天继续同一个任务

/resume 用来恢复历史会话。适合跨天调试、长时间迁移、分阶段重构，或者你昨天已经让 Codex 读完项目，今天想继续。

/resume

恢复后第一件事仍然建议跑：

/status

因为恢复的是会话，不代表当前目录、权限、模型、工作树状态都和昨天一样。真实项目会被其他人提交、格式化、切分分支，继续前必须重新确认环境。

Codex 指令里的 /side 和 /fork 怎么选

/side 和 /fork 都和分支思考有关，但用途不同。

/side 更像临时旁路问题。你不想打断主任务，只是想问一个风险、概念或替代方案，可以开 side conversation。官方文档也说明，/side 会开启独立于父线程的临时对话，结束后回到主线。

适合 /side 的问题：

• “这个方案有没有明显安全风险？”
• “这段错误日志可能来自哪里？”
• “这个库升级会影响哪些模块？”
• “有没有比当前实现更小的改法？”

/fork 更像真正复制一条新线。它适合试另一套实现方案、探索不同架构、比较两个修复方向。官方文档说明，/fork 会把当前会话克隆到一个新线程，原线程保持不变。

适合 /fork 的情况：

• A 方案和 B 方案都可能成立。
• 想让 Codex 尝试一次较大重构，但不想污染主线。
• 需要保留当前进度，同时开一条实验路径。

简单判断：问一嘴用 /side，走另一条实现线用 /fork。

Codex 指令新手进项目后的稳定工作流

下面这套流程适合大多数第一次接触项目的 Codex 新手：

cd my-project
codex

第一步，初始化项目规则：

/init

第二步，看当前会话状态：

/status

第三步，先读项目，不要改代码：

先不要改代码。帮我读一下项目结构，说明启动命令、测试命令、主要模块、最危险的目录和你建议优先看的文件。

第四步，大任务先计划：

/plan 先定位相关文件，给出最小改动方案，不要直接改代码。说明你会改哪些文件、为什么改、怎么验证。

第五步，确认计划后再实现：

按这个方案实现，保持改动尽量小。不要顺手重构无关文件。

第六步，看真实改动：

/diff

第七步，做提交前审查：

/review 请重点检查行为回归、缺失测试、边界条件和安全风险。

第八步，跑项目自己的测试命令。不要把 Codex 的“看起来没问题”当成验收。对于业务团队来说，这一步对应的是执行后的数据复盘；例如社媒矩阵运营里，动作做完还要看账号状态、发布结果、线索质量和转化路径，相关的数据闭环可以参考 Jumei 数据分析。

Codex 指令项目里的 AGENTS.md 怎么写才真正有用

很多人用 /init 后就不管了，结果 AGENTS.md 只有几句空话。真正有用的项目规则应该能回答四个问题：怎么启动、怎么测试、哪些地方不能碰、做完怎么交付。

建议写成这种结构：

AGENTS.md

## Project Overview
这是一个 Next.js 项目，使用 pnpm。核心业务在 src/app 和 src/modules。

## Commands
- Install: pnpm install
- Dev: pnpm dev
- Test: pnpm test
- Lint: pnpm lint
- Build: pnpm build

## Safe Editing Rules
- 不要修改 src/generated
- 不要修改 public/vendor
- 不要直接改数据库 migration，除非任务明确要求
- 不要引入新的状态管理库
- 改业务逻辑后必须补或更新测试

## Code Style
- 优先复用现有组件
- 不新增无必要抽象
- 不做大面积格式化
- 保持改动和任务目标一致

## Final Response
- 说明改动摘要
- 说明验证命令和结果
- 没有运行的测试要说明原因

AGENTS.md 不需要长，但必须具体。越是团队项目，越要把“不能做什么”写清楚。Codex 很擅长执行，但它不会天然知道你们团队的隐性规则。

这也是自动化平台的基本原则：先把边界、动作、复盘固化，再放大执行规模。做海外社媒矩阵时，如果账号、权限、SOP 和数据回收没有分层，自动化只会放大混乱；可以结合 Jumei 自动化运营 的思路理解。

Codex 指令使用中的常见错误

第一个错误，是把 slash command 写进普通句子里。一般应该让命令出现在输入开头，例如：

/status

不要写成：

请帮我 /status 看一下

第二个错误，是没确认权限就让 Codex 改代码。新手尤其不要在旧项目、生产项目、无测试项目里一上来全自动。

第三个错误，是任务没拆清楚就让 Codex “优化一下”。“优化”太宽泛，容易引发顺手重构。更好的写法是：

只优化 src/lib/search.ts 里查询慢的问题，不改接口签名。先解释瓶颈，再给最小改动方案。

第四个错误，是只看 Codex 的总结，不看 /diff。总结可能漏掉无关改动，diff 才是事实。

第五个错误，是把 /compact 当成新任务入口。一个新需求最好用 /new 或清空上下文；未完成的同一任务才适合 /compact。

第六个错误，是把不同工具的命令体系混用。Codex、Claude Code、IDE 插件、Web 版客户端的命令和规则可能不同。不要拿别的工具教程硬套当前 Codex 环境。最稳的方法是在本机输入 / 查看当前可用命令。

怎么判断 Codex 改得对不对

判断 Codex 不是看它回答得多自信，而是看四个证据。

第一，看 diff。改动是否集中，是否符合任务目标，是否有无关格式化。

第二，看测试。至少跑项目已有的测试、lint 或 build。没有测试时，也要做最小人工验证。

第三，看边界。异常输入、空数据、权限不足、网络失败、并发请求、老数据兼容，这些地方最容易出回归。

第四，看可回滚。一次改动最好能清楚知道改了哪些文件、为什么改、出了问题怎么撤回。

对运营团队来说，Codex 的执行也可以借鉴 SOP 管理：先定义动作，再执行，再检查，再复盘。Jumei 面向海外社媒矩阵的 多账号管理 也是类似逻辑，账号、环境、权限、数据要分层，否则规模越大越难控。

提交前检查清单

• 已运行 /diff，确认没有无关文件。
• 已运行 /review，确认没有高风险问题。
• 已执行项目测试或说明无法执行的原因。
• 已检查新增配置、权限和数据边界。
• 已把未完成事项写进最终说明。

常见问题

1. Codex 指令是不是所有版本都一样？

不一定。命令列表会受版本、系统、客户端、插件、实验开关和配置影响。以当前 Codex 里输入 / 后显示的命令为准，官方文档适合用来理解主流能力和使用方式。

2. 新手最先应该学哪几个命令？

优先学 /init、/status、/model、/permissions、/plan、/mention、/diff、/review。这几个命令覆盖了项目规则、状态确认、模型选择、权限边界、任务拆解、上下文收敛、改动检查和风险审查。

3. Codex 会不会自动乱改代码？

取决于权限、提示词和你的检查习惯。如果权限放得很开、任务描述又很宽泛，它可能会做超出预期的改动。新手建议先读项目、先计划、再确认实现，并且每次改完都看 /diff。

4. /plan 会不会浪费时间？

小改动可能没必要，但复杂任务先计划通常更省时间。一次错误的大范围修改，回滚和排查成本远高于提前花几分钟看方案。

5. /compact 会丢上下文吗？

它会把长对话压缩成摘要，所以可能丢失细节。使用前应明确要求保留任务目标、关键限制、已改文件、未解决问题和验证结果。特别重要的约束，压缩后要重新声明。

6. /side 和 /fork 有什么区别？

/side 适合临时问题，不想污染主任务；/fork 适合开另一条完整实现路线。简单说，临时咨询用 /side，方案分叉用 /fork。

7. Codex 和 ChatGPT 写代码有什么区别？

ChatGPT 更像远程顾问，你需要贴代码、贴错误、贴上下文。Codex 更像在项目目录里的协作者，可以读文件、改文件、跑命令、看 diff、做 review。能力更贴近真实开发流程，也更需要权限和边界管理。

8. Codex 改完代码后固定要做什么？

固定三步：先 /diff 看真实改动，再 /review 查风险，最后跑测试或构建命令。没有测试时，要说明没有跑的原因，并做最小人工验证。

总结

Codex 指令的价值不在于让你记住更多命令，而在于建立一套可控的工作流。新手先用 /init 写项目规则，用 /status 确认状态，用 /permissions 控制边界，用 /plan 拆复杂任务，用 /mention 收窄上下文，用 /diff 看事实，用 /review 做风险检查。

把 Codex 当成会执行的项目同事，而不是完全自动驾驶。你给它上下文、边界和验收标准，它负责提速；你保留方向、检查和最终判断，项目才不会被“聪明过头”的自动化带偏。