本页目标
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
用途:保留原会话,同时尝试另一种方案。
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,认证失败、参数错误、中断或任务失败通常为非零。脚本应判断“零成功、非零失败”,不要依赖具体非零数字。
0;失败时流水线停止并保留 stderr、事件流和摘要。失败诊断要分别检查 Codex 退出码、JSONL 中的 error/turn.failed、上游命令状态和 Git diff。不要用 || true 吞错,也不要认为非零会自动回滚文件。
安全边界:示例使用只读沙箱。若改为写入,使用隔离 runner、固定工作区、文件白名单、最小凭据和测试门禁。CI 镜像应固定 CLI 版本并打印 codex --version,但不要打印秘密变量。
PowerShell 读取退出码:
$? 或 $LASTEXITCODE,不要假设跨平台管道行为完全一致。
最小练习
在临时 Git 仓库执行以下流程:- 验证 TUI 和状态。 运行
codex --sandbox read-only "说明当前目录是否为空,不要修改",进入后输入/status。预期看到 TUI、正确路径和只读沙箱。失败时不要提高权限,先查目录、认证和帮助。 - 验证文件引用。 在输入框输入
@,选择一个安全文件并要求解释;预期路径插入输入框。搜不到时检查工作目录和脱敏,@不会提升权限。 - 验证写入边界。 只在临时仓库中请求“创建
hello.txt,只修改这个文件”。只读时应被拒绝;切到workspace-write后再试。随后运行/diff,预期只看到该文件,并用git diff交叉核对。 - 验证退出和非交互。 输入
/exit,执行:
summary.md 为最终消息、成功退出码为 0。失败时检查 stderr、文件权限、参数帮助和当前版本。
常见失败诊断矩阵
三套推荐工作流
只读探索工作流
用途:第一次接触仓库时获得结构信息,不改变文件。 输入:/status 和 /diff 复核。
失败诊断:如果它尝试写入,检查沙箱和当前目录;如果上下文不足,先缩小到 README、配置和入口文件,不要直接引用整个仓库。
安全边界:探索仍会读取文件。排除凭据目录、生成物和生产日志;联网搜索不是读取本地文件的替代品。
版本核验:记录 codex --version、启动参数、/status 和工作区状态。
交互修改工作流
用途:需要讨论方案、逐步批准命令并查看 diff 的本地开发任务。 输入:/status;用 git diff --check 和实际测试退出码验收。
CI 非交互工作流
用途:在无 TUI、无人值守的 runner 中完成只读审查或受限修改。 输入:只读审查示例:codex-events.jsonl,过程日志写入 codex-run.log,退出码决定流水线是否继续。
写入示例:
--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
用途:先分析,再沿同一上下文执行修复(仅在本机帮助支持时使用)。resume 不支持、找不到最近会话或会话未保存时使用明确会话 ID,并查 codex exec resume --help。第一阶段使用 --ephemeral 时没有可恢复记录。
安全边界:第二阶段是新的自动修改边界,即便继承了上下文,也必须重新检查沙箱、目录、凭据和外部副作用。避免两个恢复任务并行写同一工作区。
只审指定文件
用途:缩小上下文和审查面,减少误读。--json 观察事件类型(若支持)。
交付前检查
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 为准。