> ## Documentation Index
> Fetch the complete documentation index at: https://aicoding.cscitech.top/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI 完整使用

> 从交互式 TUI 到 codex exec，掌握目录、模型、权限、文件引用、斜杠命令、会话恢复、JSONL 和退出码，并能诊断常见失败。

## 本页目标

Codex CLI 有两种主模式：`codex` 启动交互式 TUI（Terminal User Interface），适合探索、讨论、审批和逐步修改；`codex exec` 完成一次非交互任务后退出，适合脚本、批处理和 CI。本页的命令、模型名称、默认值和斜杠命令会随 CLI 版本、平台和账号变化，执行前以本机帮助为准。

建议在测试仓库或临时副本练习。不要把 API key、SSH 私钥、`.env`、客户数据或生产目录交给未经审查的任务。

## 开始前检查

| 命令                              | 用途         | 输入与预期               | 失败诊断、安全边界、版本核验                                                    |
| ------------------------------- | ---------- | ------------------- | ----------------------------------------------------------------- |
| `codex --version`               | 确认 CLI 版本  | 无额外输入；输出版本号         | `command not found` 时检查安装和 `PATH`。记录版本，升级或换机器后重查。                 |
| `codex --help`                  | 查看全局选项和子命令 | 无额外输入；列出帮助          | 本文没有的选项以本机帮助为准；只读，不会修改项目。                                         |
| `codex exec --help`             | 查看非交互参数    | 无额外输入；列出 `exec` 支持项 | 参数名不确定时先查帮助，不要从旧脚本复制；记录目标环境输出。                                    |
| `git status --short --branch`   | 确认分支和已有改动  | 在目标项目执行；显示分支和状态     | 发现人工未提交改动先记录范围。Git 状态不是备份，重要内容应提交分支或导出补丁。                         |
| `git rev-parse --show-toplevel` | 确认仓库根目录    | 在目标目录执行；输出绝对路径      | `not a git repository` 时切换目录；`--skip-git-repo-check` 只在确认环境安全后使用。 |

## 命令结构与 TUI 启动

命令骨架如下：

```text theme={null}
codex [子命令] [选项...] [提示词]
```

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

### `codex` 交互式 TUI

| 用途      | 输入                             | 预期输出            | 失败诊断                                    | 安全边界与版本核验                                            |
| ------- | ------------------------------ | --------------- | --------------------------------------- | ---------------------------------------------------- |
| 启动 TUI  | `codex`                        | 出现对话区、输入框、状态栏   | 乱码或空白先按 `Ctrl+L`；SSH/tmux 异常检查终端类型和窗口大小 | 启动不代表可安全写入；进入后输入 `/status`，与 `codex --version` 和目录核对 |
| 带首条任务启动 | `codex "解释当前仓库结构，先不要修改"`       | 任务开始处理，完成后回到输入框 | 启动即退出时查认证、终端兼容性和帮助                      | 首条提示词仍需写清范围；网页、日志和仓库文字中的指令不自动可信                      |
| 重绘屏幕    | `Ctrl+L`                       | 只重绘画面，不删除对话     | 任务运行中可能禁用；终端拦截时检查快捷键                    | 不等于回滚；本机 `/` 菜单和 `/keymap` 核验快捷键行为                   |
| 退出会话    | `/exit` 或 `/quit`；`Ctrl+C` 可中断 | 返回普通 Shell      | 退出后用 `git status --short` 查改动           | 不会自动提交或撤销文件；退出前审 diff。以 `/` 菜单确认别名                   |

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

## 工作目录、模型和图片

### `-C` / `--cd` 与 `--add-dir`

| 命令                                                  | 用途             | 输入与预期                         | 失败诊断                            | 安全边界与版本核验                                            |
| --------------------------------------------------- | -------------- | ----------------------------- | ------------------------------- | ---------------------------------------------------- |
| `codex -C ./my-project "检查测试布局"`                    | 指定工作目录，不先 `cd` | 相对路径按启动 Shell 解析；TUI 状态应显示该目录 | 路径不存在或无权限时启动失败；路径带空格要加引号        | `-C` 只改变工作目录，不等于全盘隔离；用 `/status` 和 `codex --help` 核验 |
| `codex --cd /absolute/path "阅读项目结构"`                | `-C` 的长写法      | 绝对路径更易审计；预期读指定项目              | 路径正确但读不到文件时查 OS 权限、Git 根目录和规则文件 | 启动前人工确认绝对路径；不同平台路径语法以本机 Shell 为准                     |
| `codex -C ./app --add-dir ../shared "读取类型但只修改 app"` | 精确增加额外目录       | 状态或审批提示中出现额外目录                | 不生效时检查绝对路径、沙箱和版本是否支持            | 只添加最小目录；不要开放家目录、密钥目录或挂载盘。分别运行两个子命令帮助核验               |

### `-m` / `--model` 与推理强度

| 命令或操作                                           | 用途             | 输入与预期                        | 失败诊断                        | 安全边界与版本核验                                         |
| ----------------------------------------------- | -------------- | ---------------------------- | --------------------------- | ------------------------------------------------- |
| `codex -m MODEL_ID "审查边界条件"`                    | 临时选择模型         | `MODEL_ID` 换成本机可用值；状态栏显示所选模型 | 不存在、无权限或服务不可用时查登录和 `/model` | 模型不改变沙箱和审批；以 `codex --version`、`/model` 和官方当前文档核验 |
| TUI `/model`                                    | 在当前会话切换模型或推理强度 | 打开选择界面；后续回合使用新值              | 菜单缺少模型通常是账号或版本差异；不要写死旧型号    | 切换后再 `/status`；推理强度不是权限控制                         |
| `codex -c model_reasoning_effort=medium "分析方案"` | 在支持的版本临时设置推理强度 | 预期状态中出现该设置                   | 未知键或取值时删除它，回到 `/model` 和帮助  | 可用档位随模型变化；仅使用本机帮助列出的取值                            |
| `codex -i error.png "根据截图定位问题"`                 | 给首条任务附图片       | 预期模型能看到图片                    | 文件不存在、格式或大小不支持时查路径和帮助       | 截图先遮盖密码、Cookie、客户数据；`-i` 是否可用以 `codex --help` 核验  |

## 沙箱与审批

沙箱决定“能做什么”，审批决定“执行前是否询问”。只读加 `never` 仍不能写；宽松沙箱加谨慎提示词也不适合无人值守。

| 参数                                                      | 用途、输入与预期                  | 失败诊断                                 | 安全边界                        | 版本核验                                           |
| ------------------------------------------------------- | ------------------------- | ------------------------------------ | --------------------------- | ---------------------------------------------- |
| `--sandbox read-only` / `-s read-only`                  | 只读探索、审查和建议；写入应被拒绝         | 读不到文件时查目录、权限、规则；若称已写入，立即看 Git        | 只读仍可能暴露上下文；不要无必要扫描秘密目录      | `codex --help` 确认取值，TUI `/status` 确认实际档位       |
| `--sandbox workspace-write`                             | 允许工作区内修改；预期能写代码和运行必要验证    | 写失败时查挂载、文件权限、是否仍是只读；改动超范围立即停         | 明确文件范围、禁止事项和测试；网络、安装、部署另行确认 | 启动前后运行 `git status --short`，用 `/status` 核验可写目录 |
| `--sandbox danger-full-access`                          | 仅在隔离容器或临时 runner 中使用近乎全权限 | 个人电脑上不要继续放权；隔离条件不明就停止                | 禁止在生产机、含真实凭据的开发机或不可信仓库使用    | 每次查 `--help` 和版本，并记录 runner 用户、镜像和网络策略         |
| `--ask-for-approval on-request` / `-a`                  | 交互开发中需要时暂停询问              | 一直等待可能是把交互任务用于无人值守；完全不问检查是否为 `never` | 审批不是沙箱；放宽前先确认命令、路径、重定向      | 用 `/status` 和 `codex exec --help` 核验实际值        |
| `--ask-for-approval untrusted`                          | 对不可信命令询问或拦截               | 具体分类随版本变化，未知时查帮助                     | 仍要人工读完整命令，不按名称判断安全          | 以本机帮助定义为准                                      |
| `--ask-for-approval never`                              | 无人值守任务不等待人工输入             | 交互任务若不再询问是预期行为；失败看 stderr 和退出码       | 必须搭配最小沙箱、目录、网络和凭据；不能单独使用    | 用 `codex exec --help` 和受控测试核验                  |
| `--yolo` 或 `--dangerously-bypass-approvals-and-sandbox` | 某些版本的完全绕过选项               | 不存在时不要寻找别的危险开关                       | 日常机器、生产目录、真实密钥环境禁止使用        | 只在本机帮助明确存在且隔离环境中核验；新脚本不要依赖                     |

旧脚本中的 `--full-auto` 可能只是弃用兼容项。新任务优先使用明确的 `--sandbox workspace-write`，并确认本机帮助。

## 文件引用与 Shell

### `@` 文件引用

| 用途        | 输入                                 | 预期输出                | 失败诊断                   | 安全边界与版本核验                         |
| --------- | ---------------------------------- | ------------------- | ---------------------- | --------------------------------- |
| 精确引用工作区文件 | TUI 输入 `@`，选择 `@src/auth.ts`，再输入任务 | 文件路径插入输入框，模型读取相应上下文 | 搜不到时检查工作目录、大小写、忽略规则和权限 | `@` 不会提升权限；引用前脱敏。输入 `@` 看本机是否提供补全 |
| 引用目录或大文件  | 选择目录后说明具体范围                        | 可能读取相关文件或提示上下文不足    | 缩小范围、分批引用，不要强行塞全仓库     | 大文件和生成物可能泄露敏感信息；以当前 TUI 行为核验      |

### 行首 `!` Shell 模式

| 用途            | 输入与预期                                            | 失败诊断                                     | 安全边界                                      | 版本核验                        |
| ------------- | ------------------------------------------------ | ---------------------------------------- | ----------------------------------------- | --------------------------- |
| 直接执行并把结果放入上下文 | TUI 输入 `!git status --short`；Shell 输出显示，并可供下一轮使用 | `!` 不在首字符或被终端特殊处理时改用无副作用的 `!printf test` | 仍可能删除、联网或读取凭据；按真实 Shell 命令审查，不因“只是上下文”而放行 | 从 `/` 菜单确认；`/keymap` 检查相关绑定 |

## 斜杠命令

斜杠命令只在 TUI 输入框中作为消息首字符生效。输入 `/` 打开当前版本菜单，继续输入字母过滤。下表是高频命令，不是固定全集。

| 命令              | 用途                     | 输入与预期                         | 失败诊断                                        | 安全边界与版本核验                                         |
| --------------- | ---------------------- | ----------------------------- | ------------------------------------------- | ------------------------------------------------- |
| `/status`       | 查看模型、目录、沙箱、审批、可写目录、上下文 | 输入 `/status`；显示会话概况           | 未知时从 `/` 菜单选择                               | 状态可能含路径和组织信息；每次改变配置后重查                            |
| `/model`        | 切模型或推理设置               | 输入 `/model`；出现选择界面            | 检查登录、账号和菜单可用项                               | 不改变文件权限；选择后再 `/status`                            |
| `/permissions`  | 在交互会话调整权限              | 输入 `/permissions`；出现当前版本支持的档位 | 未知或设置不生效时查 `/`、启动参数和 `/status`              | 放宽前确定目录、网络和命令；任务后恢复收紧                             |
| `/diff`         | 查看 Git 改动，某些版本含未跟踪文件   | 输入 `/diff`；显示差异               | 无输出时用 `git status`、`git diff`；非 Git 目录可能无结果 | diff 不阻止副作用，也不等于测试通过；必须交叉核对 Git                   |
| `/review`       | 审查工作区改动                | 输入 `/review`；可能选择基线并输出问题      | 无改动时检查分支和基线；范围不符时补充文件范围                     | 结果需人工验证，不能直接当作“可合并”证明；以 `/` 菜单和 `/status` 记录版本、模型 |
| `/compact`      | 压缩长对话，继续当前任务           | 输入命令；返回摘要                     | 仍超上下文时减少无关内容或新建会话                           | 摘要可能丢细节，把验收条件重新写入；输入 `/` 核验存在                     |
| `/clear`        | 清屏并开全新对话               | 输入命令；旧上下文清空                   | 找不到时从菜单选择替代项                                | 不撤销文件改动；重要路径先保存                                   |
| `/new`          | 开新对话，是否清屏按版本           | 输入命令；新线程或上下文                  | 未知时使用菜单中的新会话动作                              | 新会话仍在同一工作区，先查 Git；以菜单核验                           |
| `/resume`       | 在 TUI 中恢复历史会话          | 输入命令；出现会话列表或选择器               | 查不到时检查账号、`CODEX_HOME`、目录和是否 `--ephemeral`   | 旧提示词可能过期或含秘密，恢复后先 `/status` 和检查 diff              |
| `/fork`         | 从当前会话建立分支              | 输入命令；得到新会话，原线程保留              | 新线程上下文不全时补充范围和验收                            | 不要让两个线程同时写同一工作区；以会话 ID 和 `/status` 核验             |
| `/exit`、`/quit` | 退出 TUI                 | 输入任一命令；回到 Shell               | 任务运行中可能暂时不可用                                | 不自动回滚；退出后检查 Git。以当前 `/` 菜单确认别名                    |
| `/mcp`          | 查看会话可用 MCP 工具          | 输入命令，必要时按版本支持 `verbose`       | 工具不显示时检查配置、认证和 `codex mcp --help`           | 外部工具可能读写或外发数据，逐项审查；实验性行为按版本核验                     |
| `/skills`       | 浏览或选用本地 Skill          | 输入命令；显示可用 Skill               | 未出现时查项目配置和安装状态                              | Skill 指令也需审查，不能自动提高权限；以菜单为准                       |
| `/keymap`       | 查看或修改快捷键               | 输入命令；显示绑定设置                   | 终端拦截或版本不支持时查看帮助                             | 修改前记录默认值；不要把快捷键配置当作安全控制                           |

`Ctrl+L` 只重绘屏幕，`/clear` 才会丢当前上下文。任务运行期间部分命令会被禁用；可以按版本支持的 `Tab` 排队下一条输入，但执行前仍需审查。

## 会话恢复与分叉

### `codex resume`

| 用途     | 输入                                     | 预期                | 失败诊断                               | 安全边界与版本核验                                                 |
| ------ | -------------------------------------- | ----------------- | ---------------------------------- | --------------------------------------------------------- |
| 恢复历史会话 | `codex resume`                         | 列表、选择器或最近会话       | 检查会话是否持久化、账号、`CODEX_HOME` 和目录      | 恢复后重新 `/status`，不要假设旧权限仍适用；运行 `codex resume --help`       |
| 恢复最近会话 | `codex resume --last`（若支持）             | 恢复当前目录最近会话        | 参数不存在时按帮助使用会话 ID                   | 不能跨目录猜测“最近”；以本机帮助核验                                       |
| 非交互继续  | `codex exec resume --last "继续修复"`（若支持） | 延续最近 exec 会话并输出结果 | 没有会话或 ID 时检查持久化；`--ephemeral` 无法恢复 | 两阶段任务仍需重新检查沙箱、diff 和外部副作用；以 `codex exec resume --help` 核验 |

### `codex fork`

用途：保留原会话，同时尝试另一种方案。

```bash theme={null}
codex fork SESSION_ID
```

预期：创建新的会话 ID，原线程保留。失败时运行 `codex fork --help`，并确认复制的是完整 ID。安全边界是避免两个线程同时写同一工作区，优先使用独立工作树、临时副本或只读模式。创建后记录原、新 ID，并用 `/status` 验证目录、模型和权限。

`--ephemeral`（若本机支持）表示不持久化会话，适合一次性任务，但不能依赖它做 `resume`。它不等于网络隔离，输出仍可能进入 Shell 或 CI 日志。

## `codex exec`：非交互模式

### 基础与权限

| 命令                                              | 用途              | 输入与预期                       | 失败诊断                                       | 安全边界与版本核验                               |
| ----------------------------------------------- | --------------- | --------------------------- | ------------------------------------------ | --------------------------------------- |
| `codex exec "总结当前仓库"`                           | 一次性分析，完成后退出     | 最终答复输出到 stdout，过程通常到 stderr | 认证、仓库和模型错误看完整 stderr；非 Git 目录进入仓库或确认使用跳过检查 | 无人值守默认按只读思路设计；运行 `codex exec --help`    |
| `codex e "同样的任务"`                               | `exec` 短别名（若支持） | 预期行为等同 `exec`               | 不支持时使用完整写法                                 | 脚本固定短别名前先在目标版本核验                        |
| `codex exec --sandbox workspace-write "修复失败测试"` | 非交互修改工作区        | 返回总结并退出；是否改成功以 diff 和测试为准   | 无改动时查是否只读、任务是否只要求建议、工作区是否可写                | 用独立工作区、文件白名单和测试门禁；不要依赖提示词限制范围           |
| `codex exec --skip-git-repo-check "分析临时目录"`     | 跳过 Git 仓库检查     | 预期能在非 Git 目录启动              | 参数不存在或任务失败时查帮助                             | 只在确定目录安全且可回滚时使用；跳过检查不是备份                |
| `codex exec --ephemeral "一次性分析"`                | 不持久化会话（若支持）     | 返回结果但之后不能依赖 resume          | 找不到会话时检查此选项和 `CODEX_HOME`                  | 不落盘不等于不上传、不记录 stdout；按 `exec --help` 核验 |

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

### stdin 两种用法

| 形式                                     | 用途               | 输入与预期                 | 失败诊断                                    | 安全边界与版本核验                                |
| -------------------------------------- | ---------------- | --------------------- | --------------------------------------- | ---------------------------------------- |
| `npm test 2>&1 \| codex exec "总结失败原因"` | 指令写在参数，管道内容作为上下文 | 测试输出送入模型，最终答复到 stdout | 上游无输出或 Shell 管道异常时分别检查；上游失败不等于 Codex 失败 | 日志可能有令牌和个人数据，限行、脱敏后再传；以 `exec --help` 核验 |
| `cat prompt.txt \| codex exec -`       | stdin 是完整提示词     | 按模板文件的全部内容执行          | stdin 为空或 `-` 不支持时查帮助                   | 模板和上游输出都要先审查；不可信内容不要与写权限组合               |

### stdout、stderr、`--json` 与 `-o`

| 命令                                                     | 用途              | 输入与预期                                                                    | 失败诊断                              | 安全边界与版本核验                                               |
| ------------------------------------------------------ | --------------- | ------------------------------------------------------------------------ | --------------------------------- | ------------------------------------------------------- |
| `codex exec "任务" > result.txt 2> run.log`              | 分开保存结果和过程       | stdout 进 `result.txt`，stderr 进 `run.log`                                 | 结果混入过程时检查是否误用 `2>&1`；文件为空看 stderr | 日志和结果都可能含敏感信息；在测试仓库验证分流，并记录版本                           |
| `codex exec --json "检查改动"`                             | 输出 JSONL 事件流    | stdout 每行是独立 JSON，可能有 `thread.started`、`item.*`、`turn.completed`、`error` | 不要把 stderr 合并；解析器处理未知事件和失败事件      | JSONL 不改变权限；不要执行 JSON 字段中的命令字符串；以 `exec --help` 和回归样例核验 |
| `codex exec -o summary.md "总结改动"`                      | 保存最终一条消息        | `summary.md` 写入最终答复，通常仍输出 stdout                                         | 检查父目录、权限、覆盖行为和任务是否提前失败            | 输出路径不要指向配置或共享敏感目录；以帮助核验完整长选项                            |
| `codex exec --json -o summary.md "审查改动"`               | CI 同时取得事件流和人读摘要 | stdout 为 JSONL，文件为最终消息                                                   | 确认 `-o` 没把 JSONL 写入摘要；分别保存 stderr | 事件流只作为机器输入，摘要仍需人工验证；升级后回归两种输出                           |
| `codex exec --output-schema schema.json "按 schema 输出"` | 约束最终消息结构（若支持）   | 预期最终结果符合 Schema                                                          | 先独立校验 Schema；不符合时保留原始输出和校验错误      | Schema 不限制文件、网络或命令权限；以本机帮助确认是否实验性                       |

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

```jsonl theme={null}
{"type":"thread.started","thread_id":"SESSION_ID"}
{"type":"turn.started"}
{"type":"item.completed","item":{"type":"agent_message","text":"分析完成"}}
{"type":"turn.completed","usage":{"input_tokens":100,"output_tokens":20}}
```

## 退出码与 CI

成功通常返回 `0`，认证失败、参数错误、中断或任务失败通常为非零。脚本应判断“零成功、非零失败”，不要依赖具体非零数字。

```bash theme={null}
set -o pipefail
codex exec --json --sandbox read-only -o codex-summary.md \
  "审查当前改动，按严重度输出问题" > codex-events.jsonl
code=$?
printf 'codex exit code: %s\n' "$code"
if [ "$code" -ne 0 ]; then
  exit "$code"
fi
git diff --check
git status --short
```

预期：成功时有 JSONL、摘要文件和退出码 `0`；失败时流水线停止并保留 stderr、事件流和摘要。失败诊断要分别检查 Codex 退出码、JSONL 中的 `error`/`turn.failed`、上游命令状态和 Git diff。不要用 `|| true` 吞错，也不要认为非零会自动回滚文件。

安全边界：示例使用只读沙箱。若改为写入，使用隔离 runner、固定工作区、文件白名单、最小凭据和测试门禁。CI 镜像应固定 CLI 版本并打印 `codex --version`，但不要打印秘密变量。

PowerShell 读取退出码：

```powershell theme={null}
codex exec "检查当前改动" | Out-File result.txt
$code = $LASTEXITCODE
Write-Host "codex exit code: $code"
exit $code
```

升级后用一个无风险成功任务和一个故意错误参数任务验证 `$?` 或 `$LASTEXITCODE`，不要假设跨平台管道行为完全一致。

## 最小练习

在临时 Git 仓库执行以下流程：

```bash theme={null}
mkdir codex-cli-demo
cd codex-cli-demo
git init
git status --short --branch
codex --version
```

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

```bash theme={null}
codex exec --sandbox read-only --json -o summary.md \
  "用一句话说明当前目录的 Git 状态"
code=$?
printf 'exit=%s\n' "$code"
```

预期 stdout 为 JSONL、`summary.md` 为最终消息、成功退出码为 `0`。失败时检查 stderr、文件权限、参数帮助和当前版本。

## 常见失败诊断矩阵

| 现象              | 先检查                                     | 常见原因                          | 处理方式                           | 安全边界                  |
| --------------- | --------------------------------------- | ----------------------------- | ------------------------------ | --------------------- |
| `codex` 找不到     | `codex --version`、Shell 的 `PATH`        | 未安装或安装目录未加入 PATH              | 重新打开终端，检查安装器输出和当前用户 PATH       | 不要从不明网站下载同名可执行文件      |
| 启动后立刻退出         | `codex --help`、认证状态、stderr              | 未登录、参数错误或终端不兼容                | 先运行帮助和登录检查，再重试最小任务             | 不要为绕过认证把 key 写入命令历史   |
| 提示不是 Git 仓库     | `git rev-parse --show-toplevel`         | 工作目录不对或目录尚未初始化                | 切到正确仓库；仅在临时目录确认后跳过检查           | 跳过仓库检查会失去版本边界，不是修复备份  |
| `-C` 后仍读错项目     | `/status`、`pwd`、`git rev-parse`         | 相对路径按启动 Shell 解析，或项目有父级 Git 根 | 改用绝对路径并重新核对状态                  | 路径不明确时不要批准写入          |
| 文件无法读取          | `git status`、OS 权限、文件路径                 | 忽略规则、权限、符号链接或工作区外路径           | 用 `@` 重新选择，缩小引用范围              | 不要为读一个文件开放整个家目录       |
| 写入被拒绝           | `/status`、沙箱值、文件权限                      | 仍是 `read-only` 或目录不可写         | 明确切到 `workspace-write`，检查挂载和权限 | 只给必要目录，不用全盘访问解决问题     |
| 写入未询问           | `/status`、启动参数 `-a`                     | 审批为 `never` 或当前动作被视为允许        | 在交互任务改为 `on-request`，审查实际命令    | 无人值守不代表可以忽略沙箱         |
| 任务一直等待          | 当前子命令、审批设置、stdin                        | 交互任务在等输入，或管道未结束               | 确认是否应使用 `exec`，结束上游 stdin      | 不要在 CI 中把 TUI 当作自动化接口 |
| `/status` 未知    | 输入框首字符、`/` 菜单                           | 当前入口或版本没有该命令                  | 输入 `/` 选择本机实际命令                | 不要把 App/IDE 命令表套到 CLI |
| `/diff` 没有结果    | `git status --short`、`git diff`         | 非 Git 目录、没有改动或版本实现不同          | 用 Git 原生命令交叉核对                 | `/diff` 不是测试，也不是回滚    |
| `/review` 范围不对  | 分支、基线、`git diff`                        | 基线选择错误或改动未被当前工作区看到            | 重新说明基线和文件范围                    | 审查无发现不等于可发布           |
| `/resume` 找不到会话 | 会话 ID、`CODEX_HOME`、账号、目录                | 使用了 `--ephemeral` 或更换了存储位置    | 用帮助确认语法，复制完整 ID                | 恢复旧会话前重新审查旧提示词        |
| `exec` 输出混乱     | stdout/stderr 重定向                       | 使用 `2>&1` 合并了过程日志             | 分开保存 `> result 2> log`         | 日志也可能含敏感信息            |
| JSONL 解析失败      | 原始 stdout、stderr、版本                     | 把 stderr 合并进 stdout，或事件结构变化   | 逐行解析、忽略未知事件并升级测试               | 不执行 JSON 字段中的字符串命令    |
| `-o` 文件为空       | 父目录、权限、退出码                              | 任务提前失败或路径不可写                  | 先看 stderr 和退出码，再检查文件           | 不要把输出写入配置或生产文件        |
| 退出码为非零          | stderr、JSONL `error`/`turn.failed`、上游状态 | 认证、参数、模型、被中断或任务失败             | 保存证据并停止后续自动修改                  | 非零不会自动撤销已产生的改动        |

## 三套推荐工作流

### 只读探索工作流

用途：第一次接触仓库时获得结构信息，不改变文件。

输入：

```bash theme={null}
codex -C /absolute/path/to/repo \
  --sandbox read-only \
  "先阅读 README、构建脚本和测试入口；列出目录结构、启动方式和三个未知风险，不修改文件"
```

预期输出：TUI 中出现探索结果和后续建议；Git 状态保持不变。完成后可输入 `/status` 和 `/diff` 复核。

失败诊断：如果它尝试写入，检查沙箱和当前目录；如果上下文不足，先缩小到 README、配置和入口文件，不要直接引用整个仓库。

安全边界：探索仍会读取文件。排除凭据目录、生成物和生产日志；联网搜索不是读取本地文件的替代品。

版本核验：记录 `codex --version`、启动参数、`/status` 和工作区状态。

### 交互修改工作流

用途：需要讨论方案、逐步批准命令并查看 diff 的本地开发任务。

输入：

```bash theme={null}
codex -C ./repo \
  --sandbox workspace-write \
  --ask-for-approval on-request \
  "先检查相关实现和测试，提出最小方案；确认后只修改 src/auth.ts 和对应测试，完成后运行指定测试"
```

预期输出：Codex 先说明计划；需要写文件或运行受限命令时暂停询问；完成后输入：

```text theme={null}
/status
/diff
/review
```

失败诊断：没有计划就直接修改时中断并重新声明约束；diff 超出文件白名单时停止，不要继续让它“顺手整理”。测试失败时保存原始输出，区分代码问题和环境依赖问题。

安全边界：审批弹窗中的命令逐字审查，包括管道、重定向、脚本和工作目录；提交、推送、部署、删除和外发请求默认不批准。

版本核验：变更模型或权限后重新 `/status`；用 `git diff --check` 和实际测试退出码验收。

### CI 非交互工作流

用途：在无 TUI、无人值守的 runner 中完成只读审查或受限修改。

输入：只读审查示例：

```bash theme={null}
set -o pipefail
printf '%s\n' "审查当前改动，按严重度列出问题；不要修改文件" \
  | codex exec - --sandbox read-only --json \
  > codex-events.jsonl 2> codex-run.log
code=$?
printf 'codex exit code: %s\n' "$code"
```

预期输出：事件流写入 `codex-events.jsonl`，过程日志写入 `codex-run.log`，退出码决定流水线是否继续。

写入示例：

```bash theme={null}
codex exec --sandbox workspace-write \
  --ask-for-approval never \
  -o codex-summary.md \
  "只修复失败测试；修改完成后运行测试并说明修改文件"
```

失败诊断：先检查 runner 的工作目录、认证、CLI 版本、stderr 和退出码；若模型没有修改，确认任务是否真的要求修改、沙箱是否可写、上游测试是否产生输入。不要自动重试无限次。

安全边界：CI 使用独立 runner、最小 Secret、固定目录和网络白名单；写入任务完成后检查 diff 白名单和测试结果。`--ask-for-approval never` 只表示不等待人工，不表示任务安全。

版本核验：镜像中固定 CLI 版本；每次运行打印版本和非敏感配置；升级前回归 stdin、JSONL、`-o`、退出码和 Git 检查。

## 命令组合示例

### 分析测试失败但不修改

用途：把失败日志作为上下文，让 Codex 只输出诊断。

```bash theme={null}
npm test 2>&1 | codex exec --sandbox read-only \
  "归纳失败测试、最可能根因和三步排查建议；不要修改文件" \
  > test-diagnosis.md
```

预期：`test-diagnosis.md` 主要是最终诊断，过程在 stderr；Codex 不应产生代码改动。失败时分别检查 `npm test` 和 `codex exec` 的状态，避免把上游失败误判为分析失败。

安全边界：限制日志行数并脱敏；如果测试输出包含令牌，先在上游过滤。版本核验使用 `codex exec --help` 确认管道语义。

### 生成摘要并保留事件

用途：同时为机器保留事件、为人保留最终摘要。

```bash theme={null}
codex exec --json -o review-summary.md \
  --sandbox read-only \
  "审查当前改动，指出行为回归、缺失测试和高风险操作" \
  > review-events.jsonl 2> review-run.log
```

预期：`review-events.jsonl` 是逐行 JSON，`review-summary.md` 是最终消息，`review-run.log` 保存过程。退出码为非零时，先停止合并流程。

失败诊断：摘要缺失看退出码和日志；JSONL 无法解析时确认没有把 stderr 合并。安全边界是审查三份输出中的路径和秘密；版本核验是升级后保留一份脱敏回归样例。

### 两阶段 resume

用途：先分析，再沿同一上下文执行修复（仅在本机帮助支持时使用）。

```bash theme={null}
codex exec --sandbox read-only "审查这处改动，详细列出问题"
codex exec resume --last --sandbox workspace-write \
  --ask-for-approval never \
  "只修复已确认的问题，运行相关测试"
```

预期：第二阶段延续第一阶段会话并输出修复结果；以 Git diff 和测试验收，而不是只看模型总结。

失败诊断：`resume` 不支持、找不到最近会话或会话未保存时使用明确会话 ID，并查 `codex exec resume --help`。第一阶段使用 `--ephemeral` 时没有可恢复记录。

安全边界：第二阶段是新的自动修改边界，即便继承了上下文，也必须重新检查沙箱、目录、凭据和外部副作用。避免两个恢复任务并行写同一工作区。

### 只审指定文件

用途：缩小上下文和审查面，减少误读。

```bash theme={null}
codex exec --sandbox read-only \
  "只审查 src/auth.ts 和 tests/auth.test.ts。不要读取或修改其他文件；列出每个发现对应的行号"
```

预期：输出聚焦两个文件；实际读取范围仍用日志、工具事件或 Git 检查确认。

失败诊断：如果输出涉及其他文件，停止并检查提示、项目规则和任务工具调用；不要把“只审查”当作强制访问控制。

安全边界：真正的边界来自沙箱、目录、权限和外部系统策略；提示词只是意图表达。版本核验使用 `--json` 观察事件类型（若支持）。

## 交付前检查

```bash theme={null}
git diff --check
git status --short
git diff --stat
git diff
```

确认：工作目录和分支正确；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` 为准。