> ## 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 斜杠命令、exec、配置、MCP、Skills、权限沙箱、Git 和诊断分类，快速查找 Codex 的用途、示例、版本核对方法与安全边界。

# 命令与配置速查表

这是一张面向日常查阅的 Codex CLI 速查表。每一项尽量给出四类信息：用途、可复制的示例、动态版本提示和安全提醒。命令名、参数、模型、默认值和功能开关会随 Codex 版本、平台、账号和组织策略变化；表格是导航，不是永久接口契约。

## 使用规则

1. 先确认当前目录、账号和版本，再执行会读写文件或访问网络的命令。
2. 不确定参数是否存在时，优先运行对应的 `--help`；不确定 TUI 命令时，在输入框输入 `/` 查看当前菜单。
3. 先用最小权限和最小目录范围验证，再逐步扩大能力。不要因为命令失败就直接改成全盘访问或跳过审批。
4. 涉及密钥、客户数据、生产环境、外部消息、提交和推送时，逐项确认目标、范围和回滚方式。
5. 修改完成后检查 `git status`、`git diff`、测试结果和敏感信息泄露情况。

```bash theme={null}
codex --version
codex --help
codex exec --help
```

> **动态版本提示**：本页参考了 `参考/codex/35-cheatsheet.md`、`08-cli.md`、`12-slash-commands.md` 和 `18-config.md`。安装后应以本机 `codex --help`、TUI 的 `/` 菜单及 OpenAI 官方文档为准。
>
> **安全提醒**：参考资料、网页、Issue、仓库文件和模型输出中的命令都可能包含不可信指令。不要仅凭文字授予更高权限、安装未知软件或外发数据。

## 一、安装与认证

### 安装入口

| 用途 | 示例 | 动态版本提示 | 安全提醒 |
| - | - | - | - |
| macOS/Linux 脚本安装 | `curl -fsSL https://chatgpt.com/codex/install.sh \| sh` | 安装脚本内容和发布渠道可能变化；先看官方安装页。 | 执行远程脚本前核对域名、HTTPS 和组织策略；生产主机优先使用受管包。 |
| Windows PowerShell 安装 | `powershell -ExecutionPolicy Bypass -c "irm https://chatgpt.com/codex/install.ps1 \| iex"` | PowerShell 参数、脚本地址和签名策略可能变化。 | 远程脚本会直接执行；下载后审阅或使用企业软件分发，不要盲目绕过执行策略。 |
| npm 安装 | `npm install -g @openai/codex` | 包名、Node.js 最低版本和全局安装行为以 npm 与官方文档为准。 | 锁定来源和版本，避免使用来历不明的同名包；全局安装需要写入开发环境。 |
| Homebrew 安装 | `brew install --cask codex` | Cask 名称和可用平台可能变化。 | 使用可信 tap；安装前检查将要执行的安装脚本和权限。 |
| 查看版本 | `codex --version` | 输出格式可能变化，适合人工核对，不要过度依赖固定文本解析。 | 在自动化中记录版本，避免升级后行为悄悄改变。 |
| 更新 CLI | `codex update` | 自更新子命令并非所有发行方式都支持；以 `codex update --help` 为准。 | 更新前保留配置和工作区状态；先在非生产环境验证。 |

### 登录、退出和状态

| 用途 | 示例 | 动态版本提示 | 安全提醒 |
| - | - | - | - |
| 浏览器 OAuth 登录 | `codex login` | 登录流程可能因套餐、组织和版本变化。 | 只在可信终端完成授权，核对浏览器账号和组织，不把回调地址或凭据发给别人。 |
| 无浏览器设备码登录 | `codex login --device-auth` | 设备码支持和参数名称以 `codex login --help` 为准。 | 设备码短时有效；不要在聊天、日志或截图中暴露。 |
| API Key 登录 | `printenv OPENAI_API_KEY \| codex login --with-api-key` | API Key 登录方式可能调整；优先查看帮助。 | 通过标准输入传递，不要把 key 写进命令历史、脚本、仓库或日志。 |
| 查看登录状态 | `codex login status` | 已登录时通常以退出码表示成功，但输出文本可能变化。 | 状态检查不会证明账号拥有目标模型或组织权限；脚本应同时处理失败分支。 |
| 退出登录 | `codex logout` | 清理范围可能随版本变化；退出前确认是否会影响其他本地会话。 | 共享机器退出登录；不要删除整个 `CODEX_HOME` 来代替注销。 |
| 安装与认证体检 | `codex doctor` | 诊断项目和检查项会增加或变化；先看 `codex doctor --help`。 | 输出可能包含路径、配置和环境信息，分享日志前脱敏。 |

### 安装后的最小验收

```bash theme={null}
codex --version
codex login status
codex doctor
```

用途：确认命令可执行、认证状态明确、基础环境没有明显问题。

动态版本提示：如果 `doctor` 不存在或参数不同，运行 `codex --help`，不要从其他版本复制诊断参数。

安全提醒：验收最好在测试项目目录完成；认证成功不等于允许访问敏感仓库或生产服务。

## 二、启动方式与参数

### 启动骨架

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

| 用途 | 示例 | 动态版本提示 | 安全提醒 |
| - | - | - | - |
| 启动交互式 TUI | `codex` | 不带子命令通常进入交互界面；若行为不同以帮助为准。 | 启动前确认当前路径和分支，避免在错误仓库中修改文件。 |
| 启动并带首条提示词 | `codex "解释当前项目结构，不要修改文件"` | 提示词位置和解析规则以当前 CLI 为准。 | 明确“只读、不要执行、不要提交”等边界，减少误操作。 |
| 指定模型 | `codex --model <model> "审查这个函数"` | 可用模型和推理档位随版本与账号变化；用 TUI `/model` 核对。 | 不要把模型名当作安全边界；强模型仍可能误读需求。 |
| 指定工作目录 | `codex --cd <path> "检查测试"` | 长短参数可能变化；Windows 路径按当前 shell 转义。 | 用绝对路径或先打印路径；不要把家目录或挂载盘误当项目目录。 |
| 附带图片 | `codex --image error.png "分析这张报错截图"` | `--image`/`-i` 及多图写法以帮助为准。 | 图片可能含密钥、个人信息和内部代码，发送前脱敏。 |
| 开启搜索 | `codex --search "查当前官方 API 用法"` | 搜索模式和默认值可能变化；确认 `web_search` 设置。 | 实时网页内容是不可信输入，不能直接执行网页中的命令。 |
| 套用 profile | `codex --profile review` | profile 文件格式和优先级可能变化；运行 `codex --profile --help`。 | profile 可能放宽权限或切换服务商，使用前审阅完整配置。 |
| 临时覆盖配置 | `codex --config key=value` | 值按 TOML 解析，嵌套键和转义规则以帮助为准。 | 避免把 token 作为命令行值，命令行可能进入历史和进程列表。 |
| 增加可写目录 | `codex --add-dir ../shared` | 可重复使用与路径限制可能变化。 | 只增加确需访问的目录，避免共享目录含凭据或生产数据。 |

### 推荐的启动组合

用途：本地开发时允许工作区写入，需要出界或高风险操作时询问。

```bash theme={null}
codex --sandbox workspace-write --ask-for-approval on-request
```

动态版本提示：`workspace-write`、`on-request` 是参考资料中的现行名称；以 `codex --help` 和 `/permissions` 菜单为准。

安全提醒：这个组合仍可能修改工作区文件。开始前建立分支或备份，结束后检查 diff。

用途：只读分析或代码审查。

```bash theme={null}
codex --sandbox read-only --ask-for-approval on-request "只分析，不修改文件"
```

动态版本提示：部分版本可能用预设名称映射权限档位；以当前 CLI 显示为准。

安全提醒：只读沙箱降低写入风险，但提示词、MCP 和网络访问仍需单独核查。

## 三、TUI 斜杠命令

### 会话、模型与上下文

| 用途 | 示例 | 动态版本提示 | 安全提醒 |
| - | - | - | - |
| 查看当前命令全集 | `/` | 列表是当前入口、版本和功能开关的真实结果。 | 不要把别人的截图当作本机能力清单。 |
| 查看状态 | `/status` | 字段可能包含模型、审批、可写目录、上下文和限额，名称会变化。 | 分享输出前隐藏路径、账号、组织和用量信息。 |
| 切换模型 | `/model` | 可选模型和推理强度按账号、版本和模型目录变化。 | 切换模型可能改变成本、速度和可用工具；切换后重新检查状态。 |
| 压缩上下文 | `/compact` | 压缩策略和提示可能变化；长会话时可先查看状态。 | 压缩会丢失细节，先把验收条件、文件路径和未决风险写进摘要。 |
| 新建对话 | `/new` | 是否保留终端滚屏以当前版本为准。 | 新对话不代表未提交改动消失；仍需检查工作区。 |
| 清屏并新对话 | `/clear` | 可能同时清理显示和上下文；不要与 `Ctrl+L` 混用。 | 清空后旧上下文不可作为安全审计记录，重要结论先保存。 |
| 规划模式 | `/plan` | 是否可用以及参数形式可能随版本变化。 | 计划不是批准；执行前仍需审阅写入、网络和外部操作。 |
| 设置个性 | `/personality` | 功能可能由 feature 或模型目录控制。 | 风格设置不改变权限，也不应被当成行为保证。 |

### 检查、恢复与退出

| 用途 | 示例 | 动态版本提示 | 安全提醒 |
| - | - | - | - |
| 查看改动 | `/diff` | 通常覆盖暂存、未暂存和未跟踪文件；Git 行为可能变化。 | 交付前审阅所有新文件，防止敏感文件被生成或加入。 |
| 代码审查 | `/review` | 审查模式、基线选择和模型可能随版本变化。 | 审查结果不是测试或人工批准的替代品。 |
| 复制最近输出 | `/copy` 或 `Ctrl+O` | 复制对象和快捷键可通过 `/keymap` 变化。 | 复制内容可能含密钥、内部路径和客户数据，粘贴前检查目标。 |
| 恢复会话 | `/resume` | 会话存储位置和列表格式可能变化。 | 恢复前确认项目路径和账号，避免把旧会话用于错误仓库。 |
| 分叉会话 | `/fork` | 分叉是否可用以当前菜单为准。 | 分叉只复制上下文，不会自动复制工作区状态；两条线程可能互相覆盖文件。 |
| 侧聊 | `/side` 或 `/btw` | 别名可能变化，使用 `/` 搜索。 | 侧聊仍可能读取当前上下文；不要在其中粘贴秘密。 |
| 查看 MCP | `/mcp` 或 `/mcp verbose` | 详细子命令和显示内容可能变化。 | 工具列表不等于工具可信；逐一确认服务器来源和权限。 |
| 查看 Skills | `/skills` | Skill 列表由本机安装、目录和版本决定。 | 启用前阅读 Skill 指令，尤其是网络、写文件和凭据处理部分。 |
| 退出会话 | `/exit` 或 `/quit` | 别名和退出提示可能变化。 | 退出前保存重要输出，确认没有正在运行的破坏性任务。 |

### 其他 TUI 命令

| 用途 | 示例 | 动态版本提示 | 安全提醒 |
| - | - | - | - |
| 调整权限 | `/permissions` | 选项名称可能显示为 Auto、Read Only、Full Access 等不同文案。 | 放宽后任务可能立即获得更多能力；任务结束后恢复收紧设置。 |
| 调整状态栏 | `/statusline` | 可选字段和排序方式可能变化。 | 状态栏不应显示秘密；不要把 token 或环境变量放入界面。 |
| 调整快捷键 | `/keymap` | 动作名和键名以本机菜单为准。 | 修改后记录映射，避免把退出、审批等关键动作绑定到易误触按键。 |
| 调整主题 | `/theme` | 主题名称随版本和终端变化。 | 主题只影响显示，不改变权限或模型行为。 |
| 启用 Fast | `/fast on`、`/fast off`、`/fast status` | 仅在当前模型和账号提供服务层时出现。 | Fast 不代表更安全或更准确；仍需审阅输出和 diff。 |
| 初始化项目规则 | `/init` | 生成的 `AGENTS.md` 内容和路径可能变化。 | 审阅生成内容，不要让它写入密钥、错误权限或未经确认的自动操作。 |

## 四、TUI 快捷键与前缀

| 用途 | 示例 | 动态版本提示 | 安全提醒 |
| - | - | - | - |
| 重绘屏幕但保留对话 | `Ctrl+L` | 终端复合环境可能拦截该组合键。 | 它不是 `/clear`；确认不会误清上下文。 |
| 中断当前操作 | `Ctrl+C` | 终端可能需要按一次或多次；以界面提示为准。 | 中断不一定回滚已完成的文件写入，事后必须查 diff。 |
| 排队下一条输入 | `Tab` | 任务运行中的排队行为可能变化。 | 不要排队未经审阅的写入、删除、发布或外发命令。 |
| 编辑长提示词 | `Ctrl+G` | 使用 `VISUAL` 或 `EDITOR`，平台配置会影响结果。 | 外部编辑器临时文件可能落盘；不要在提示词中写秘密。 |
| 反向搜索提示历史 | `Ctrl+R` | 终端或 shell 可能优先拦截该键。 | 历史可能含 token；清理敏感历史并避免把 key 放入提示词。 |
| 查看 raw 滚屏 | `Alt+R` | 快捷键可能通过 `/keymap` 改变或被终端占用。 | raw 输出仍可能包含敏感信息。 |
| 行首执行 shell | `!git status` | `!` 模式和审批行为以 TUI 菜单与版本为准。 | 这是直接执行 shell 的入口；检查命令，禁止复制未知破坏性命令。 |
| 引用工作区文件 | `@src/app.ts` | 文件搜索和补全范围随版本变化。 | 引用文件会把内容带入上下文，先确认没有秘密和个人数据。 |

`Ctrl+L` 只重绘屏幕；`/clear` 通常会清理显示并开启新对话；`/compact` 则压缩上下文继续当前任务。三者用途不同，执行前确认目标。

## 五、`codex exec` 非交互执行

### 基本用法

| 用途 | 示例 | 动态版本提示 | 安全提醒 |
| - | - | - | - |
| 执行一次审查 | `codex exec "审查当前改动并列出风险"` | `exec` 的别名和默认输出会变化；用 `codex exec --help`。 | 非交互不会有人在每一步点确认，必须显式设置沙箱和审批。 |
| 从标准输入读取提示词 | `cat prompt.txt \| codex exec -` | Windows shell 的管道和编码可能不同。 | 输入文件可能含秘密；运行前审阅并限制文件权限。 |
| 指定模型和沙箱 | `codex exec -m <model> -s read-only "分析测试失败"` | 短参数和可用模型以帮助为准。 | 只读分析仍可能访问上下文和外部工具，按最小权限配置。 |
| 输出 JSONL 事件 | `codex exec --json "运行测试并总结"` | 事件类型、字段和顺序是动态接口，不能硬编码全部字段。 | 日志可能包含源码、路径和错误中的秘密，存储与上传前脱敏。 |
| 写出最后一条消息 | `codex exec -o result.txt "总结当前状态"` | `-o`/`--output-last-message` 名称和是否同时打印以帮助为准。 | 输出文件可能覆盖既有文件；使用专用临时路径并检查内容。 |
| 约束最终 JSON | `codex exec --output-schema schema.json "输出结构化结果"` | Schema 支持和校验行为可能变化。 | Schema 只约束格式，不保证内容正确或没有敏感数据。 |
| 不保存会话 | `codex exec --ephemeral "只做一次分析"` | 会话留存范围可能变化；不要把它当作绝对无痕保证。 | 进程、shell、代理和外部服务仍可能留下日志。 |
| 非 Git 目录执行 | `codex exec --skip-git-repo-check "分析这个临时目录"` | 参数可能被限制或改名。 | 跳过仓库检查会失去部分 diff 和回滚保障；只用于隔离临时目录。 |
| 恢复最近 exec | `codex exec resume --last` | 子命令结构以帮助为准。 | 恢复前确认工作目录、提示上下文和未完成操作。 |

### 脚本化建议

用途：让机器读取事件、让人读取最终摘要。

```bash theme={null}
codex exec --json -o result.txt -s workspace-write -a never "运行测试；只修复失败测试并总结改动"
```

动态版本提示：`--json`、`-o`、`-s` 和 `-a` 的组合以本地帮助为准；自动化应固定 CLI 版本并测试升级。

安全提醒：`-a never` 表示无人值守，不能单独使用；必须搭配受限沙箱、专用分支、超时、日志脱敏和人工审阅。

`--full-auto` 在参考资料中属于已弃用的兼容写法；新脚本优先使用明确的 `--sandbox` 和 `--ask-for-approval`，并以当前帮助确认是否仍支持。任何跳过全部审批和沙箱的参数都应只在隔离 runner 中使用。

## 六、配置文件与优先级

### 文件位置

| 用途 | 示例 | 动态版本提示 | 安全提醒 |
| - | - | - | - |
| 用户级默认配置 | `~/.codex/config.toml` | `CODEX_HOME` 可改变默认位置；查看当前版本文档。 | 文件可能含服务地址、通知命令和行为策略；设置适当权限，不提交仓库。 |
| 项目级配置 | `<repo>/.codex/config.toml` | 项目层是否加载取决于信任状态和版本。 | 陌生仓库的项目配置是不可信输入；信任前审阅。 |
| profile 文件 | `~/.codex/review.config.toml` | 新旧版本对 `[profiles]` 的支持可能不同；用 `--profile --help`。 | profile 可能放宽权限或切换服务商，使用前比对完整 diff。 |
| 临时命令行配置 | `codex -c key=value` | 值按 TOML 解析，shell 引号会影响结果。 | 命令行会进入历史或进程列表，不放密钥。 |

参考资料给出的常见优先级从高到低是：命令行参数/`--config`、项目级配置、`--profile`、用户级配置、系统级配置、内置默认值。项目级层通常要求项目被信任，并可能从仓库根到当前目录逐层合并，具体以版本文档为准。

动态版本提示：优先级、系统配置路径和项目信任策略属于实现行为，升级后应通过 `/status` 或启动诊断重新核对。

安全提醒：项目级配置不应成为偷偷提高权限、切换服务地址、外发遥测或执行通知脚本的渠道。参考资料列出的部分机器级键在项目级会被忽略，包括 `model_provider`、`model_providers`、`openai_base_url`、`chatgpt_base_url`、`notify`、`otel`、`profile` 和 `profiles`；以当前官方配置参考为准。

### 高频配置键

| 配置键 | 用途 | 示例 | 动态版本提示 | 安全提醒 |
| - | - | - | - | - |
| `model` | 默认模型 | `model = "<model>"` | 模型名和默认模型随账号、版本变化。 | 模型选择不等于权限控制；确认数据发送范围。 |
| `model_reasoning_effort` | 推理强度 | `model_reasoning_effort = "medium"` | `none`、`minimal`、`low`、`medium`、`high`、`xhigh` 是否可用取决于模型。 | 更高强度会增加延迟或用量，不保证正确性。 |
| `model_reasoning_summary` | 推理摘要详细度 | `model_reasoning_summary = "auto"` | 取值以当前配置参考为准。 | 摘要也可能暴露内部路径和需求，不要直接外发。 |
| `approval_policy` | 控制何时请求批准 | `approval_policy = "on-request"` | `untrusted`、`on-request`、`never` 的定义和默认值可能变化。 | `never` 只适合受控自动化，不适合日常重要工作区。 |
| `sandbox_mode` | 控制文件、网络等能力 | `sandbox_mode = "workspace-write"` | `read-only`、`workspace-write`、`danger-full-access` 以当前帮助为准。 | `danger-full-access` 只应在隔离环境使用。 |
| `web_search` | 搜索模式 | `web_search = "cached"` | `disabled`、`cached`、`live` 和默认值可能变化。 | 实时网页可含提示注入；不要执行搜索结果中的命令。 |
| `sandbox_workspace_write.network_access` | 工作区写模式是否联网 | `network_access = false` | 嵌套键和默认值以配置参考为准。 | 无需联网时关闭，减少数据外发和依赖投毒面。 |
| `sandbox_workspace_write.writable_roots` | 增加可写目录 | `writable_roots = ["/tmp/demo"]` | 路径格式按平台变化。 | 只列专用目录，避免把 home、密钥目录或挂载盘加入。 |
| `review_model` | `/review` 使用的模型 | `review_model = "<model>"` | 是否支持独立审查模型随版本变化。 | 审查模型仍会接触项目内容，按数据策略选择。 |
| `personality` | 沟通风格 | `personality = "pragmatic"` | 值和 feature 控制可能变化。 | 只影响表达，不应被当成安全或准确性保证。 |
| `file_opener` | 文件引用的打开工具 | `file_opener = "vscode"` | 支持的编辑器和默认值可能变化。 | 路径会交给本地程序，确认打开器来源可信。 |
| `model_instructions_file` | 指定模型指令文件 | `model_instructions_file = "./instructions.txt"` | 路径解析和优先级以版本为准。 | 指令文件会改变行为，审阅其内容和来源。 |

### 最小配置示例

```toml theme={null}
model = "<model>"
model_reasoning_effort = "medium"
approval_policy = "on-request"
sandbox_mode = "workspace-write"
web_search = "cached"

[sandbox_workspace_write]
network_access = false
```

用途：建立一个偏保守的日常默认，再按任务临时覆盖。

动态版本提示：`<model>` 必须替换为本机 `/model` 或组织文档中可用的模型；默认值不要根据旧文章推断。

安全提醒：配置文件是行为默认，不是审批记录。修改后重新启动并用 `/status` 检查；不要把认证信息写进 TOML。

TOML 注意：顶层键通常放在表段前，字符串要加引号，数组使用 TOML 语法。解析失败时先运行配置相关帮助或 `codex doctor`，不要连续猜键名。

### `-c` 与 profile

用途：只临时覆盖一次配置，不改文件。

```bash theme={null}
codex -c web_search='"live"' "查官方最新文档"
codex -c sandbox_workspace_write.network_access=false "只做本地分析"
```

动态版本提示：`-c` 的长写法、点号嵌套语法和 TOML 引号规则以 `codex --help` 为准。

安全提醒：命令行内容可能进入历史；不要使用 `-c` 传递秘密。实时搜索前确认网页数据可以发送给外部服务。

用途：切换一套命名配置。

```bash theme={null}
codex --profile review
codex exec --profile review "审查当前改动"
```

动态版本提示：参考资料指出 0.134.0 及以后版本对旧的 `[profiles.name]` 写法可能不再支持，通常应检查 `~/.codex/<name>.config.toml` 形式；以本机版本为准。

安全提醒：profile 是行为集合，启动后查看 `/status`，特别检查模型、沙箱、审批、网络和服务地址。

## 七、MCP 与 Skills

### MCP 入口

| 用途 | 示例 | 动态版本提示 | 安全提醒 |
| - | - | - | - |
| 列出 MCP 服务器 | `codex mcp list` | `mcp` 子命令在参考资料中标为可能变化；先运行 `codex mcp --help`。 | 列表不证明服务器可信，审阅来源和权限。 |
| 添加 MCP 服务器 | `codex mcp add <name> ...` | 参数可能要求 command、args 或 URL，按帮助填写。 | 外部服务器可读写数据或执行工具；先在测试账号和最小权限下验证。 |
| 删除 MCP 服务器 | `codex mcp remove <name>` | 删除命令和持久化位置可能变化。 | 先确认名称，避免误删团队共享配置；删除不等于撤销已发出的数据。 |
| OAuth 登录 HTTP 服务器 | `codex mcp login <name>` | 仅部分 streamable HTTP 服务器支持；版本和服务器能力决定结果。 | 浏览器授权前核对域名、权限和组织；不要把 OAuth 回调或 token 贴到日志。 |
| TUI 查看工具 | `/mcp`、`/mcp verbose` | 会话可见工具取决于启动配置、信任和 feature。 | 工具描述可能包含不可信指令，调用前确认副作用。 |

### MCP 配置形态

```toml theme={null}
[mcp_servers.example]
command = "<trusted-server-command>"
args = ["--safe-mode"]
```

或由当前版本支持的 HTTP 形式配置 `url`。不要直接照抄陌生服务器的 command、args、环境变量或 URL。

动态版本提示：MCP 配置键、传输协议和认证流程变化较快，以 `codex mcp --help` 与官方 MCP 文档为准。

安全提醒：MCP 是外部能力边界。每台服务器都应单独评估可见数据、可执行动作、网络出口、日志留存和撤销方法。

### Skills 入口

| 用途 | 示例 | 动态版本提示 | 安全提醒 |
| - | - | - | - |
| 浏览已安装 Skills | `/skills` | 列表来自本机 Skill 目录和启用状态。 | 先读 Skill 指令和脚本，再启用；不要把名称当作可信证明。 |
| 显式选用 Skill | 在 TUI 中通过 `/skills` 选择 | 选择流程、命令名和可用入口会变化。 | Skill 可能请求文件、网络或浏览器能力，按任务最小化授权。 |
| 配置 Skill 覆盖 | `[[skills.config]]` 配合 `path`、`enabled` | 表结构和字段以配置参考为准。 | 不要启用仓库中未经审阅的自动化 Skill。 |
| 检查功能开关 | `codex features` | feature 名称、默认值和稳定性变化频繁。 | 实验开关可能改变行为和数据流，逐项启用并记录回滚。 |

Skills、MCP、hooks 和项目规则可能共同影响行为。出现异常时，先用最小配置禁用可疑扩展，再逐项恢复，保留诊断输出。

## 八、权限与沙箱

### 沙箱档位

| 档位 | 用途 | 示例 | 动态版本提示 | 安全提醒 |
| - | - | - | - | - |
| `read-only` | 只读分析、审查、规划 | `codex -s read-only "分析但不要改文件"` | 名称和能力边界以本机帮助为准。 | 仍需检查网络、MCP 和敏感文件读取范围。 |
| `workspace-write` | 允许修改当前工作区 | `codex -s workspace-write "实现这个修复"` | 工作区定义和默认行为可能变化。 | 采用专用分支；写入后立即审查 diff。 |
| `danger-full-access` | 全面访问，通常包含更大文件和网络能力 | `codex -s danger-full-access` | 能力边界和警告会变化。 | 仅限隔离容器、临时 runner 或明确批准的环境。 |

### 审批策略

| 策略 | 用途 | 示例 | 动态版本提示 | 安全提醒 |
| - | - | - | - | - |
| `untrusted` | 对不可信操作更严格询问 | `codex -a untrusted` | 具体信任判断属于版本实现。 | 适合陌生项目和探索阶段，但仍要看每次批准内容。 |
| `on-request` | 需要时暂停请求批准 | `codex -a on-request` | 询问触发条件可能变化。 | 推荐本地日常使用；批准前看完整命令和目标路径。 |
| `never` | 无人值守执行 | `codex -a never` | 非交互限制和失败行为以帮助为准。 | 只在受控 CI、专用分支和受限沙箱使用。 |

`--yolo` 或 `--dangerously-bypass-approvals-and-sandbox` 这类参数会绕过审批和沙箱。动态版本提示：别名、警告和支持状态可能变化；不要依赖它作为正常工作流。安全提醒：只在外部隔离、无敏感数据、可销毁的环境使用，日常开发不要启用。

## 九、Git 与交付检查

| 用途 | 示例 | 动态版本提示 | 安全提醒 |
| - | - | - | - |
| 查看工作区状态 | `git status --short --branch` | Git 输出格式应尽量由脚本解析结构化字段而非固定文本。 | 确认目录、分支和远端正确，避免在错误仓库操作。 |
| 查看统计 diff | `git diff --stat` | 只统计已追踪差异；未跟踪文件需配合 status。 | 先看范围，再看详细内容。 |
| 查看完整 diff | `git diff` | 暂存内容需另用 `git diff --cached`。 | 检查敏感值、生成文件、删除和权限变化。 |
| 检查空白错误 | `git diff --check` | Git 版本对诊断文案可能不同。 | 修复前确认不是有意格式；不要用忽略检查掩盖问题。 |
| 查看未跟踪文件 | `git status --short` | 状态代码是 Git 接口，脚本应稳健处理特殊路径。 | 新文件最容易漏审，逐个打开确认内容。 |
| 查看最近提交 | `git log -1 --oneline --decorate` | 装饰信息随分支状态变化。 | 提交前确认基线、作者和目标分支。 |
| 创建分支 | `git switch -c <branch>` | 老版本可需要 `git checkout -b`。 | 分支名不要含客户信息；确认不会覆盖同名分支。 |
| 暂存指定文件 | `git add -- <file>` | Git 参数可用 `--` 区分路径和选项。 | 精确暂存，避免把密钥和无关改动加入提交。 |
| 提交前审查 | `git diff --cached --check` | 输出依 Git 版本变化。 | 只在测试通过、diff 已审阅后提交。 |
| 恢复单文件未提交改动 | `git restore --source=HEAD -- <file>` | 恢复命令在旧 Git 版本可能不同。 | 会丢失该文件未提交内容；先确认没有他人工作。 |

Codex 的 `/diff` 可作为会话内快速检查，但不能替代 `git status`、`git diff`、测试和人工审阅。`codex exec` 或 TUI 生成的提交信息也必须按普通 Git 变更审查。

### 提交与推送安全边界

用途：推送前做最小检查。

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

动态版本提示：Git 默认分支、远端名称和工作流由项目决定。

安全提醒：用户未明确要求时，不要自动提交或推送；推送前确认远端、分支、评审状态和凭据来源。

不要把 token 写进远端 URL、脚本、日志或提示词。不要使用强制推送改写共享分支历史，除非经过明确授权并完成影响评估。

## 十、诊断与故障定位

### 由浅入深

| 用途 | 示例 | 动态版本提示 | 安全提醒 |
| - | - | - | - |
| 确认 CLI 可用 | `codex --version` | 版本输出可能含渠道和构建信息。 | 记录版本，不在错误版本上反复猜参数。 |
| 查全局帮助 | `codex --help` | 这是当前安装版本的入口清单。 | 帮助输出也可能暴露本地能力，分享前脱敏。 |
| 查子命令帮助 | `codex exec --help` | 子命令参数最应以此为准。 | 先理解参数副作用，再复制组合命令。 |
| 查登录问题 | `codex login status` | 退出码和提示文本可能变化。 | 不要用打印 token 的方式“验证”认证。 |
| 运行体检 | `codex doctor` | 检查项随版本增加或调整。 | 上传诊断前清理路径、用户名、组织和密钥。 |
| 查 TUI 能力 | 输入 `/` | 只显示当前入口实际可用命令。 | 版本差异优先看本机菜单，不要硬套旧教程。 |
| 查当前会话 | `/status` | 字段和显示位置可能变化。 | 核对模型、权限、沙箱、目录和网络状态。 |
| 查 MCP | `codex mcp list`、`/mcp verbose` | MCP 可能是实验能力，子命令会变化。 | 逐台隔离测试，确认工具是否能写文件或发请求。 |
| 查 Git 基线 | `git status --short --branch` | Git 分支状态是外部事实。 | 错误目录是最常见的高风险原因之一。 |

### 常见现象与处理

| 现象 | 先做什么 | 动态版本提示 | 安全提醒 |
| - | - | - | - |
| 找不到参数 | 运行对应 `--help`，再查官方文档 | 参数可能被弃用、改名或受 feature 控制。 | 不要用危险别名替代未知参数。 |
| TUI 画面错位 | 按 `Ctrl+L` 重绘 | 终端、tmux、SSH 可能拦截快捷键。 | 不要因显示错位直接重启或清空会话。 |
| `/clear` 后找不到上下文 | 这是新对话行为，查看会话恢复选项 | `/new`、`/clear`、`/compact` 差异会变化。 | 清空前保存关键验收标准和路径。 |
| 项目配置不生效 | 检查项目信任、路径和 TOML 语法 | 项目层加载规则随版本变化。 | 不要为了生效而盲目信任陌生仓库。 |
| 配置解析失败 | 检查引号、表段、根键顺序和键名 | 官方配置参考可能新增或删除键。 | 从最小配置逐项恢复，避免复制未知配置。 |
| MCP 工具不出现 | 查 `codex mcp list`、`/mcp verbose` 和 feature | 连接协议和登录支持变化较快。 | 不要把服务器 URL 或 OAuth token 发到公开渠道。 |
| exec 卡住或无人值守失败 | 检查审批、沙箱、超时、网络和退出码 | 非交互行为和事件类型可能变化。 | 不要直接改成全盘访问；先在临时目录复现。 |
| 改动范围不清楚 | 同时运行 `git status`、`git diff` 和测试 | `/diff` 可能展示未跟踪文件，但 Git 命令仍是基线。 | 防止误提交秘密、构建产物和客户数据。 |
| 认证失败 | `codex login status`、`codex doctor`，核对账号和网络 | OAuth、设备码和组织策略会变化。 | 不要把完整错误日志原样公开。 |

## 十一、最小验证流程

### 只读验证

用途：验证版本、认证、目录和非交互输出，不修改项目文件。

```bash theme={null}
codex --version
codex login status
git status --short --branch
codex exec --sandbox read-only --ask-for-approval on-request -o codex-check.txt "只用一句话说明当前目录是否为 Git 仓库"
```

动态版本提示：如果 `--ask-for-approval` 或 `-o` 在本机不可用，运行 `codex exec --help` 并改用当前名称。

安全提醒：`codex-check.txt` 可能覆盖已有文件；换成专用临时目录或不存在的文件名，并在结束后删除非必要产物。

### 配置验证

用途：验证临时覆盖不会修改用户级配置。

```bash theme={null}
codex -c web_search='"cached"'
```

进入 TUI 后执行：

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

动态版本提示：状态字段未必直接显示搜索模式；必要时用对应帮助和诊断确认。

安全提醒：测试实时搜索或外部服务前，先确认数据策略和网络出口。

### 改动验证

用途：验证一项小改动的审查闭环。

```bash theme={null}
git switch -c codex-check
git status --short
# 在隔离测试文件上执行最小任务
git diff --check
git diff --stat
git diff
```

动态版本提示：项目可能要求不同分支命名、格式化和测试命令。

安全提醒：验证文件必须是可删除的测试文件；不要在生产仓库、共享分支或含真实数据的目录演练。

## 十二、交付前一页检查

* `codex --version` 已记录，参数和斜杠命令已用本机帮助核对。
* 当前工作目录、Git 分支、远端和账号都确认无误。
* 模型、推理强度、沙箱、审批、网络和 MCP 工具状态符合任务需要。
* `git status --short`、`git diff`、`git diff --check` 已检查。
* 未跟踪文件、删除、权限变化、生成物和配置变更均已逐项审阅。
* 测试、构建、类型检查或最小诊断已执行，并记录失败项。
* 没有把 API Key、OAuth token、SSH 私钥、`.env`、客户数据或内部日志写入仓库和输出。
* 没有因为一次失败就启用全盘访问、跳过全部审批或信任陌生项目。
* 未明确授权时没有提交、推送、发布、外发消息或修改生产系统。

**最终原则**：查不到时先看 `--help`，看不清时先用 `/status`，改完先看 Git diff；能力越大，目录越小、审批越明确、验证越具体。