Skip to main content

本页目标

Codex CLI 有两种主模式:codex 启动交互式 TUI(Terminal User Interface),适合探索、讨论、审批和逐步修改;codex exec 完成一次非交互任务后退出,适合脚本、批处理和 CI。本页的命令、模型名称、默认值和斜杠命令会随 CLI 版本、平台和账号变化,执行前以本机帮助为准。 建议在测试仓库或临时副本练习。不要把 API key、SSH 私钥、.env、客户数据或生产目录交给未经审查的任务。

开始前检查

命令结构与 TUI 启动

命令骨架如下:
codex 是主命令,exec、resume、fork 改变运行方式,-m、--sandbox 等调整参数,最后的字符串是提示词。Shell 的引号、变量和重定向仍由当前 Shell 处理。

codex 交互式 TUI

TUI 通常有三个区域:对话区显示计划、工具调用、命令输出、差异和最终答复;输入框接收普通提示、/、@ 和行首 !;状态栏显示模型、目录、权限或上下文。信息字段随版本变化,始终以 /status 为准。

工作目录、模型和图片

-C / --cd 与 --add-dir

-m / --model 与推理强度

沙箱与审批

沙箱决定“能做什么”,审批决定“执行前是否询问”。只读加 never 仍不能写;宽松沙箱加谨慎提示词也不适合无人值守。 旧脚本中的 --full-auto 可能只是弃用兼容项。新任务优先使用明确的 --sandbox workspace-write,并确认本机帮助。

文件引用与 Shell

@ 文件引用

行首 ! Shell 模式

斜杠命令

斜杠命令只在 TUI 输入框中作为消息首字符生效。输入 / 打开当前版本菜单,继续输入字母过滤。下表是高频命令,不是固定全集。 Ctrl+L 只重绘屏幕,/clear 才会丢当前上下文。任务运行期间部分命令会被禁用;可以按版本支持的 Tab 排队下一条输入,但执行前仍需审查。

会话恢复与分叉

codex resume

codex fork

用途:保留原会话,同时尝试另一种方案。
预期:创建新的会话 ID,原线程保留。失败时运行 codex fork --help,并确认复制的是完整 ID。安全边界是避免两个线程同时写同一工作区,优先使用独立工作树、临时副本或只读模式。创建后记录原、新 ID,并用 /status 验证目录、模型和权限。 --ephemeral(若本机支持)表示不持久化会话,适合一次性任务,但不能依赖它做 resume。它不等于网络隔离,输出仍可能进入 Shell 或 CI 日志。

codex exec:非交互模式

基础与权限

交互 TUI 适合需要来回沟通、实时审批和审 diff 的任务;exec 适合脚本、CI、批量和无终端环境。exec 没有活人批准,因此权限必须在启动参数中显式定义。

stdin 两种用法

stdout、stderr、--json 与 -o

示例 JSONL 形态如下,字段和事件类型不应写死:

退出码与 CI

成功通常返回 0,认证失败、参数错误、中断或任务失败通常为非零。脚本应判断“零成功、非零失败”,不要依赖具体非零数字。
预期:成功时有 JSONL、摘要文件和退出码 0;失败时流水线停止并保留 stderr、事件流和摘要。失败诊断要分别检查 Codex 退出码、JSONL 中的 error/turn.failed、上游命令状态和 Git diff。不要用 || true 吞错,也不要认为非零会自动回滚文件。 安全边界:示例使用只读沙箱。若改为写入,使用隔离 runner、固定工作区、文件白名单、最小凭据和测试门禁。CI 镜像应固定 CLI 版本并打印 codex --version,但不要打印秘密变量。 PowerShell 读取退出码:
升级后用一个无风险成功任务和一个故意错误参数任务验证 $? 或 $LASTEXITCODE,不要假设跨平台管道行为完全一致。

最小练习

在临时 Git 仓库执行以下流程:
  1. 验证 TUI 和状态。 运行 codex --sandbox read-only "说明当前目录是否为空,不要修改",进入后输入 /status。预期看到 TUI、正确路径和只读沙箱。失败时不要提高权限,先查目录、认证和帮助。
  2. 验证文件引用。 在输入框输入 @,选择一个安全文件并要求解释;预期路径插入输入框。搜不到时检查工作目录和脱敏,@ 不会提升权限。
  3. 验证写入边界。 只在临时仓库中请求“创建 hello.txt,只修改这个文件”。只读时应被拒绝;切到 workspace-write 后再试。随后运行 /diff,预期只看到该文件,并用 git diff 交叉核对。
  4. 验证退出和非交互。 输入 /exit,执行:
预期 stdout 为 JSONL、summary.md 为最终消息、成功退出码为 0。失败时检查 stderr、文件权限、参数帮助和当前版本。

常见失败诊断矩阵

三套推荐工作流

只读探索工作流

用途:第一次接触仓库时获得结构信息,不改变文件。 输入:
预期输出:TUI 中出现探索结果和后续建议;Git 状态保持不变。完成后可输入 /status 和 /diff 复核。 失败诊断:如果它尝试写入,检查沙箱和当前目录;如果上下文不足,先缩小到 README、配置和入口文件,不要直接引用整个仓库。 安全边界:探索仍会读取文件。排除凭据目录、生成物和生产日志;联网搜索不是读取本地文件的替代品。 版本核验:记录 codex --version、启动参数、/status 和工作区状态。

交互修改工作流

用途:需要讨论方案、逐步批准命令并查看 diff 的本地开发任务。 输入:
预期输出:Codex 先说明计划;需要写文件或运行受限命令时暂停询问;完成后输入:
失败诊断:没有计划就直接修改时中断并重新声明约束;diff 超出文件白名单时停止,不要继续让它“顺手整理”。测试失败时保存原始输出,区分代码问题和环境依赖问题。 安全边界:审批弹窗中的命令逐字审查,包括管道、重定向、脚本和工作目录;提交、推送、部署、删除和外发请求默认不批准。 版本核验:变更模型或权限后重新 /status;用 git diff --check 和实际测试退出码验收。

CI 非交互工作流

用途:在无 TUI、无人值守的 runner 中完成只读审查或受限修改。 输入:只读审查示例:
预期输出:事件流写入 codex-events.jsonl,过程日志写入 codex-run.log,退出码决定流水线是否继续。 写入示例:
失败诊断:先检查 runner 的工作目录、认证、CLI 版本、stderr 和退出码;若模型没有修改,确认任务是否真的要求修改、沙箱是否可写、上游测试是否产生输入。不要自动重试无限次。 安全边界:CI 使用独立 runner、最小 Secret、固定目录和网络白名单;写入任务完成后检查 diff 白名单和测试结果。--ask-for-approval never 只表示不等待人工,不表示任务安全。 版本核验:镜像中固定 CLI 版本;每次运行打印版本和非敏感配置;升级前回归 stdin、JSONL、-o、退出码和 Git 检查。

命令组合示例

分析测试失败但不修改

用途:把失败日志作为上下文,让 Codex 只输出诊断。
预期:test-diagnosis.md 主要是最终诊断,过程在 stderr;Codex 不应产生代码改动。失败时分别检查 npm test 和 codex exec 的状态,避免把上游失败误判为分析失败。 安全边界:限制日志行数并脱敏;如果测试输出包含令牌,先在上游过滤。版本核验使用 codex exec --help 确认管道语义。

生成摘要并保留事件

用途:同时为机器保留事件、为人保留最终摘要。
预期:review-events.jsonl 是逐行 JSON,review-summary.md 是最终消息,review-run.log 保存过程。退出码为非零时,先停止合并流程。 失败诊断:摘要缺失看退出码和日志;JSONL 无法解析时确认没有把 stderr 合并。安全边界是审查三份输出中的路径和秘密;版本核验是升级后保留一份脱敏回归样例。

两阶段 resume

用途:先分析,再沿同一上下文执行修复(仅在本机帮助支持时使用)。
预期:第二阶段延续第一阶段会话并输出修复结果;以 Git diff 和测试验收,而不是只看模型总结。 失败诊断:resume 不支持、找不到最近会话或会话未保存时使用明确会话 ID,并查 codex exec resume --help。第一阶段使用 --ephemeral 时没有可恢复记录。 安全边界:第二阶段是新的自动修改边界,即便继承了上下文,也必须重新检查沙箱、目录、凭据和外部副作用。避免两个恢复任务并行写同一工作区。

只审指定文件

用途:缩小上下文和审查面,减少误读。
预期:输出聚焦两个文件;实际读取范围仍用日志、工具事件或 Git 检查确认。 失败诊断:如果输出涉及其他文件,停止并检查提示、项目规则和任务工具调用;不要把“只审查”当作强制访问控制。 安全边界:真正的边界来自沙箱、目录、权限和外部系统策略;提示词只是意图表达。版本核验使用 --json 观察事件类型(若支持)。

交付前检查

确认:工作目录和分支正确;diff 只包含允许文件;没有秘密、日志和临时产物;沙箱、审批、额外目录和网络权限符合最小权限;测试退出码真实为 0;JSONL、stdout、stderr 和摘要文件分别处理;恢复或分叉后重新核对线程、目录、模型和权限。 参考资料:参考/codex/08-cli.md、参考/codex/12-slash-commands.md、参考/codex/28-noninteractive.md、参考/codex/35-cheatsheet.md。动态行为以本机 codex --help、子命令帮助、TUI 的 / 菜单和 /status 为准。