Codex 指令速查：从会用到用顺手

这篇是写给已经装好 Codex CLI、但还停留在“打开终端跟它聊天”的使用者。Codex 真正好用的地方，不只是让它改代码，而是把一次性提问、持续会话、自动化脚本、代码审查、上下文管理这些动作拆成一组清晰的指令。

很多人第一次用 Codex，会把它当成一个终端里的 ChatGPT：输入需求，等它回答。这样当然也能用，但很容易遇到两个问题：

1. 不知道什么时候该让它直接改代码，什么时候只让它分析。
2. 每次都重新解释项目背景、权限边界和任务目标，效率不高。

更好的方式，是先把 Codex 的指令分成几类来理解：

• 启动和登录
• 交互式会话
• 非交互式执行
• 审查和应用变更
• 会话恢复与分支
• 权限、沙箱和配置
• MCP、插件和扩展能力

下面按实际使用频率来讲。

1. 安装与登录：先让 Codex 能正常工作

Codex CLI 可以用 npm 或 Homebrew 安装：

npm install -g @openai/codex
# 或
brew install --cask codex

安装后直接运行：

codex

第一次使用时，通常会进入登录流程。你可以使用 ChatGPT 账号登录，也可以使用 API Key：

codex login

如果你想用 API Key，可以把 key 从标准输入传给 Codex：

printenv OPENAI_API_KEY | codex login --with-api-key

检查当前登录状态：

codex login status

如果要清除登录信息：

codex logout

这组命令解决的是“能不能用”的问题。只要登录状态正常，后面的指令才有意义。

2. codex：最常用的交互式入口

最简单的入口就是：

codex

它会打开一个交互式会话。你可以在里面描述需求，比如：

帮我看一下这个项目的启动流程，并指出最容易出错的三个地方。

也可以启动时直接带上 prompt：

codex "阅读这个仓库，给我一份模块结构说明"

如果要指定工作目录，用 -C：

codex -C /path/to/project "帮我分析这个项目的测试结构"

常见选项还有：

codex -m gpt-5.5 "帮我重构这个函数"

codex --search "帮我根据最新文档检查这个 SDK 的用法是否过时"

codex -s workspace-write "实现这个功能，但只允许修改当前工作区文件"

我的建议是：

• 想边看边改，用 codex。
• 想一次性跑完任务，用后面讲的 codex exec。
• 不确定任务范围时，先让它分析和计划，不要一上来就给全权限。

3. 交互式会话里的斜杠指令

进入 codex 之后，可以用 / 查看可用的斜杠指令。这些指令更像“会话控制面板”，不是普通聊天内容。

/model：切换模型

/model

用于查看或切换当前会话使用的模型。

如果你发现一个任务需要更强推理能力，可以切到更强的模型；如果只是改一点文案或做轻量分析，也可以切到更快的模型。

/fast：切换快速模式

/fast on
/fast off
/fast status

适合在“小修小补、快速问答、简单代码定位”场景里使用。复杂重构、跨模块分析、线上故障排查这类任务，不建议盲目追求快。

/plan：先要计划，不急着改

/plan

或者：

/plan 给这个服务设计一个迁移方案，要求兼容旧接口

这是我认为非常实用的指令。很多时候你并不是要 Codex 马上动手，而是要它先把风险、步骤、影响范围讲清楚。

适合用 /plan 的场景：

• 重构核心模块
• 数据库字段调整
• API 行为变化
• 前端页面大改
• 发布流程改造

一个好习惯是：先 /plan，确认方向后再让 Codex 实现。

/review：让 Codex 做代码审查

/review

适合在提交前检查当前改动。它会把注意力放在潜在 bug、边界条件、回归风险上。

如果你希望 Codex 不只是“帮你写”，还要“帮你挡问题”，这个指令应该经常用。

/diff：查看本轮改了什么

/diff

当 Codex 改了一堆文件后，先别急着提交。用 /diff 看一下变更范围，确认它没有顺手改掉不该改的东西。

尤其是以下情况要多看 diff：

• 它修改了配置文件
• 它改了测试快照
• 它动了锁文件
• 它同时改了前端、后端、脚本

/status：查看当前会话状态

/status

这个指令用来确认当前模型、权限、工作区、配置等状态。排查“为什么它不能写文件”“为什么它没有联网搜索”“为什么当前目录不对”时很有用。

/permissions：调整权限

/permissions

Codex 的能力强不强，不只看模型，也看你给它什么权限。

权限相关指令适合用来回答这些问题：

• 能不能写当前工作区？
• 能不能运行命令？
• 是否需要每次确认？
• 有没有额外可读目录？

如果你在一个重要仓库里工作，建议保持权限克制：先读、再计划、最后再开放写入。

/sandbox-add-read-dir：增加只读上下文目录

/sandbox-add-read-dir /path/to/another/repo

有些任务需要参考另一个仓库，但不希望 Codex 改它。这个时候可以把它作为只读目录加进来。

典型场景：

• 主项目要参考旧项目实现
• 后端要参考前端类型定义
• 新服务要参考老服务 API
• 写文档时要参考另一个资料目录

/mcp：查看 MCP 工具

/mcp

如果你给 Codex 配了 MCP Server，比如数据库、浏览器、内部工具、GitHub、Linear 等，就可以通过这个指令查看当前可用工具。

MCP 的价值是让 Codex 不只会读代码，还能接触外部系统。但这也意味着权限边界更重要：能查什么、能不能写、能不能执行危险操作，都要提前想清楚。

/init：生成项目规则

/init

通常会用于初始化项目规则文件，比如 AGENTS.md。这个文件可以写项目约定：

• 代码风格
• 测试命令
• 分支规则
• 目录说明
• 禁止修改的路径
• 发布前检查项

如果你在一个长期项目里使用 Codex，AGENTS.md 很重要。它能减少你每次重复解释项目规则的成本。

/compact：压缩上下文

/compact

长会话里，上下文会越来越多。/compact 可以把前面的对话压缩成更短的摘要，保留主要任务状态。

适合在这些时候使用：

• 一个任务已经跑了很久
• 中间查了很多资料
• 已经完成前半段，准备进入实现阶段
• 你发现 Codex 开始忘记早期约束

/clear、/new、/quit

/clear
/new
/quit

这几个用于清理或结束会话：

• /clear：清空当前会话上下文
• /new：开始新会话
• /quit 或 /exit：退出 Codex

不要把完全无关的任务一直塞在同一个会话里。一个会话最好只围绕一个明确目标。

4. codex exec：把 Codex 当成脚本工具

codex exec 是非交互式模式。它适合自动化、批处理、CI 辅助、日志分析等场景。

最简单的用法：

codex exec "总结这个仓库的结构，并列出 5 个风险点"

你也可以把管道输入交给它：

npm test 2>&1 \
  | codex exec "总结失败的测试，并给出最小修复建议"

分析日志：

tail -n 200 app.log \
  | codex exec "找出最可能的根因，并给出下一步排查步骤"

生成发布说明：

codex exec "根据最近 10 个 commit 生成 release notes" \
  | tee release-notes.md

如果希望输出最后一条消息到文件：

codex exec "提取项目元信息" -o project-summary.md

如果你要把 Codex 接进自动化流程，exec 比交互式 TUI 更适合。

5. codex review：专门做代码审查

除了会话里的 /review，命令行也有独立的审查指令：

codex review

审查未提交改动：

codex review --uncommitted

和某个基础分支对比：

codex review --base main

审查某个 commit：

codex review --commit <SHA>

你也可以追加自定义审查要求：

codex review --uncommitted "重点检查并发安全、权限校验和数据库迁移风险"

这个指令适合放在提交前，尤其是你已经让 Codex 改过代码之后，再让它从另一个角度挑问题。

6. resume 和 fork：不要浪费已经建立好的上下文

Codex 会话最值钱的不是那几句回答，而是它已经理解过的上下文。

恢复最近一次交互式会话：

codex resume --last

恢复指定会话：

codex resume <SESSION_ID>

非交互式模式也可以恢复：

codex exec resume --last "继续修复刚才发现的问题"

如果你想在已有会话基础上开一个分支，而不是污染原来的上下文，可以用：

codex fork --last

resume 适合“继续刚才的任务”，fork 适合“沿着另一个方向试试”。

7. apply：应用 Codex 生成的变更

如果你使用 Codex Cloud 或某些远程任务流程，可能会拿到一个任务 ID。此时可以用：

codex apply <TASK_ID>

它会把 Codex 产生的 diff 应用到本地工作区。

建议应用之后立刻做三件事：

git diff

npm test
# 或你的项目测试命令

git status -sb

不要把 apply 当成自动合并按钮。它只是帮你把变更拿下来，是否接受仍然要由你判断。

8. 沙箱与审批：控制 Codex 能做什么

Codex 的权限控制主要由两个概念组成：

• sandbox：它能访问和修改什么
• approval：它什么时候需要你确认

常见沙箱模式：

codex -s read-only
codex -s workspace-write
codex -s danger-full-access

大致可以这样理解：

审批策略常见有：

codex -a on-request
codex -a never
codex -a untrusted

日常使用建议：

• 看代码、问问题：read-only
• 做普通功能：workspace-write + on-request
• 自动化脚本：谨慎使用 never
• 不要在重要机器上随手开 danger-full-access

9. 配置文件：把常用偏好固定下来

Codex 的配置通常在：

~/.codex/config.toml

项目内也可以有：

.codex/config.toml

你可以用 -c 临时覆盖配置：

codex -c model="gpt-5.5" "分析这个模块"

也可以使用 profile：

codex --profile work

一个简单配置示例：

model = "gpt-5.5"
approval_policy = "on-request"
sandbox_mode = "workspace-write"

[features]
web_search = true

配置文件适合放“长期偏好”，命令行参数适合放“本次任务的特殊要求”。

10. MCP 与插件：让 Codex 接入外部工具

管理 MCP Server：

codex mcp list
codex mcp get <name>
codex mcp add <name> <command>
codex mcp remove <name>

如果 MCP Server 需要登录：

codex mcp login <name>
codex mcp logout <name>

插件相关入口：

codex plugin marketplace

MCP 和插件不是新手第一天必须掌握的东西。更合理的顺序是：

1. 先熟悉 codex 和斜杠指令。
2. 再学会 codex exec 自动化。
3. 最后再接 MCP 和插件扩展外部系统。

否则很容易还没建立基本使用习惯，就先把权限和工具链搞复杂。

11. 一套日常工作流

如果你刚开始用 Codex，可以按这个节奏来：

第一步：让它先读项目

codex -C /path/to/project "阅读项目结构，说明主要模块和启动方式，不要修改文件"

第二步：让它给计划

/plan 给这个功能设计实现方案，列出需要改哪些文件、风险点和测试方式

第三步：确认后再实现

按刚才的方案实现，保持改动尽量小，并补充必要测试

第四步：看 diff

/diff

第五步：审查

/review

或者在终端里：

codex review --uncommitted "重点检查回归风险和边界条件"

第六步：跑测试，把失败日志交给它

npm test 2>&1 | codex exec "总结失败原因，并给出最小修复建议"

这个流程比“直接让 Codex 改到能跑”为好。它把计划、实现、审查、验证拆开，出错时也更容易定位。

12. 最容易踩的坑

坑一：一上来就给大权限

danger-full-access 看起来省事，但也最容易出事。除非你在容器、临时机器、隔离环境里，否则不要把它当默认模式。

坑二：把所有任务塞进一个长会话

一个会话写功能、改文案、查线上问题、顺便重构配置，最后上下文会变得很混乱。任务边界变了，就 /new。

坑三：不看 diff

AI 写代码最怕“顺手”。它可能顺手改格式、顺手换依赖、顺手动配置。每次实现后都应该看 diff。

坑四：没有项目规则

长期项目一定要写 AGENTS.md 或项目级规则。否则你每次都要重新告诉它测试命令、目录约定、提交习惯、哪些文件不能改。

坑五：把 exec 当万能自动驾驶

codex exec 很适合自动化，但它不是替你承担责任。凡是会写文件、发请求、部署、删除数据的任务，都应该有明确权限和校验步骤。

结论

Codex 的核心不是“多一个 AI 聊天窗口”，而是把编码任务拆成可控制的工作流：

• 用 codex 做交互式协作
• 用斜杠指令管理模型、计划、权限和上下文
• 用 codex exec 做自动化分析和批处理
• 用 codex review 做提交前检查
• 用 resume / fork 延续或分叉已有上下文
• 用 sandbox、approval 和配置文件控制风险

如果只记一条建议：不要一开始就让 Codex 直接改。先让它读项目、写计划、说明风险，再放开权限实现。这样用起来更慢一点，但结果通常更稳。