Codex CLI 入门：把终端变成可审查的 AI 编程工作台

本文只讨论 Codex CLI，不讨论 Codex Desktop。示例基于本机验证的 codex-cli 0.134.0。

摘要： Codex CLI 不是“终端版 ChatGPT”，而是一个能在本地仓库里读代码、改文件、跑命令、看 diff 的 coding agent。真正提高效率的不是记住所有参数，而是学会三件事：用 codex 进入交互式工作台，用 slash commands 控制会话和权限，用 codex exec 处理一次性任务。

它适合做什么

Codex CLI 适合放在本地工程目录里使用：

普通终端：
  你输入命令 -> 工具输出结果 -> 你自己判断下一步

Codex CLI：
  你给目标和边界 -> Codex 读项目、调用工具、改文件、跑验证 -> 你审查 diff 和结论

它最适合这些任务：

• 读陌生仓库，整理目录结构、入口、构建命令和风险点。
• 小范围修 bug，要求它先定位、再改动、再验证。
• 写 README、迁移说明、release notes、技术博客草稿。
• 提交前做本地 code review，看行为风险和测试缺口。
• 分析测试失败、构建错误、接口报错等命令行输出。

它不适合一上来就接“把整个系统重构好”。给 AI 编程工具的任务越清楚，输出越稳定：目录、边界、验证方式和审查节奏都要说清楚。

先跑起来

最常用启动方式：

codex

在指定仓库启动：

codex --cd /path/to/repo

带一个初始任务启动：

codex "Explain this codebase. Do not edit files."

指定模型：

codex --model gpt-5.5

恢复最近一次会话：

codex resume --last

环境异常时先体检：

codex doctor --summary

沙箱怎么理解

Codex CLI 会在执行命令和写文件前套一层权限护栏。它主要控制两件事：哪些目录能写、能不能联网。

常用三档：

模式	适合场景	风险
read-only	只读分析、读陌生仓库	不能改文件
workspace-write	写代码、写文档、跑本地验证	只能写当前工作区和显式追加目录
danger-full-access	受控容器或临时环境	等同放开本机权限，不建议日常使用

日常建议：

codex --sandbox read-only        # 先读，不改文件
codex --sandbox workspace-write  # 小范围修改，默认推荐

不确定当前权限时，在 TUI 里输入：

/status

如果需要让 Codex 访问额外目录，用 --add-dir 明确加，不要把整个用户目录都丢进去：

codex --cd /path/to/repo --add-dir /path/to/shared-docs

最常用的 8 个斜杠命令

进入交互式 TUI 后，输入 / 会打开 slash commands 菜单。日常不用背全量命令，先掌握这 8 个。

命令	什么时候用	价值
/status	刚进会话、准备改文件前	看模型、目录、权限、上下文用量
/model	任务变复杂或想降成本时	在不退出会话的情况下切模型
/permissions	需要写文件、联网、跑高风险命令时	把权限调到和任务风险匹配
/plan	跨文件改动、重构、排障前	先看方案、文件范围、验证命令和风险
/diff	Codex 改完文件后	看真实改动，不只听自然语言总结
/review	提交前	让 Codex 以 code review 视角找风险
/compact	对话很长但任务还没结束	压缩上下文，保留关键结论
/new	一个任务完成后	开新上下文，避免旧假设污染下一件事

一个简单规则：/status 看边界，/plan 控节奏，/diff 看事实，/review 查风险。

一套稳定的交互式工作流

不要上来就让 Codex 改代码。更稳的节奏是：

定边界 -> 先计划 -> 小步执行 -> 看 diff -> 跑验证

读仓库时这样问：

请阅读当前仓库，不要改文件。输出：
- 项目定位
- 主要目录和入口
- 构建/测试/自检命令
- 你认为最需要小心的风险点
- 建议下一步先做什么

准备改动时这样问：

/plan 请为这个任务给出最小修改方案：<任务描述>。
要求：
- 不要直接改代码
- 列出预计修改文件
- 说明验证命令
- 标出风险点

确认计划后再让它执行：

按刚才的计划执行。保持最小改动，改完运行验证命令。

改完后固定做三件事：

/diff
/review
请总结本次改动、验证结果、剩余风险和建议提交信息。

这套流程的重点不是“多问几句”，而是把 AI 的行为变成可审查的交付过程。

非交互模式：用 codex exec 处理一次性任务

交互式 TUI 适合边看边协作；codex exec 适合一次性总结、脚本、管道和 CI。

总结仓库：

codex exec "summarize this repository and list the top 5 risks"

把输出写入文件：

codex exec "generate release notes for the last 10 commits" \
  -o release-notes.md

分析测试日志：

npm test 2>&1 \
  | codex exec "summarize the failing tests and propose the smallest likely fix"

输出 JSONL 事件流，便于脚本处理：

codex exec --json "summarize the repo structure"

用 JSON Schema 约束最终输出：

codex exec "Extract project metadata" \
  --output-schema ./schema.json \
  -o ./project-metadata.json

codex exec 默认不会像交互模式那样一路询问你。自动化场景里要显式控制权限：

codex exec --sandbox read-only "review this repository"
codex exec --sandbox workspace-write "fix the failing tests"

不要在公共 CI 里把 API Key 暴露给整个 job。更稳的做法是只在单次调用范围内注入凭证，并避免让不可信仓库代码读取完整环境变量。

生成文档后，用 Trae CN 回到编辑器

CLI 很适合生成和改写 Markdown，但最终审阅通常还是要回到编辑器。比如 Codex 新增了这篇文档后，我希望直接用 Trae CN 打开它，而不是再复制路径、切窗口、手动找文件。

Trae CN 的命令行入口是 trae。打开文件：

trae -r blog/ai/engineering-delivery/agentic-coding/codex-cli-slash-commands-productivity-guide.md

跳到具体行：

trae -r -g blog/ai/engineering-delivery/agentic-coding/codex-cli-slash-commands-productivity-guide.md:1

这里两个参数最常用：

参数	含义
-r / --reuse-window	复用已有 Trae CN 窗口，避免开出一堆新窗口
-g / --goto	打开文件并跳到 file:line[:column]

如果希望先确保 Trae CN 打开的是当前仓库目录，再跳到文件，可以先打开目录：

trae -r .
trae -r -g blog/ai/engineering-delivery/agentic-coding/codex-cli-slash-commands-productivity-guide.md:1

这个仓库里我还加了一个小 skill，专门处理“让 Codex 帮我用 Trae CN 打开文件”的场景：

.trae/skills/trae-cn-open-file/scripts/open_in_trae_cn.sh \
  blog/ai/engineering-delivery/agentic-coding/codex-cli-slash-commands-productivity-guide.md 1

它做的事情比直接 trae -g 稍微多一点：先检查路径是否存在，再尝试判断 Trae CN 是否已经打开在目标仓库；如果目录已经对，就直接复用窗口跳文件；如果状态不明确，就先复用窗口打开仓库目录，再跳到目标文件。

以后在 Codex 里可以直接说：

使用 Trae CN 打开 blog/ai/engineering-delivery/agentic-coding/codex-cli-slash-commands-productivity-guide.md

这样就能把“CLI 生成文档”和“编辑器审阅文档”连起来。

提示词怎么写更省时间

把 Codex CLI 当成工程协作者，而不是聊天机器人。好提示词通常包含四件事：目标、边界、验证、输出格式。

不要这样写：

帮我看看这个项目。

改成：

请阅读当前仓库，不要改文件。输出项目定位、主要目录、验证命令、风险点和下一步建议。

不要这样写：

修一下这个 bug。

改成：

修复这个 bug：<现象>。
约束：
- 先定位根因，不要直接改
- 只做最小必要修改
- 如果需要改公共模块，先说明影响面
- 改完运行相关测试
- 最后给出 diff 摘要、验证结果和剩余风险

不要这样写：

把这个重构一下。

改成：

/plan 请为这个重构给出方案，不要改代码。
要求：
- 保持现有行为不变
- 分阶段，每阶段都能独立验证
- 标出高风险文件
- 给出回滚策略

常见坑

坑	表现	建议
长对话一直续	旧假设、旧错误反复影响新任务	一个任务结束就 /new，必要结论写进文件
不看 diff	Codex 说得对，但实际改动超范围	改完必用 /diff，再决定是否接受
让它猜验证命令	跑错测试或只跑了无关命令	把验证命令写进 prompt 或 AGENTS.md
权限开太大	AI 探索成本低，但错误影响面变大	从 read-only 或 workspace-write 开始
把 API Key 当登录状态	认证、计费、模型权限判断混乱	区分 ChatGPT 登录和 API Key，自动化单独管理

我的默认用法

个人日常可以按这套来：

读陌生仓库：
  codex --sandbox read-only

写代码/文档：
  codex --sandbox workspace-write

复杂任务：
  先 /plan，再执行

改完：
  /diff
  /review
  跑仓库测试或自检

任务结束：
  /new

一次性任务用：

codex exec "<task>"
some-command | codex exec "<instruction>"
codex exec --json "<task>"

如果只想记一句话：把 Codex CLI 当成本地可执行的工程协作者，但每一步都要留下边界、diff 和验证。

参考资料

• Codex CLI 官方文档
• Codex CLI features
• Codex CLI slash commands
• Codex non-interactive mode
• Codex authentication
• openai/codex GitHub 仓库