codex

@rules/routing.md

Codex 技能

<output_language>

默认将所有面向用户的交付内容、保存的产物、报告、计划、生成的文档、摘要、交接说明、提交/消息草稿和验证说明设为韩语，即使此规范技能文件以英语编写。

保留源代码标识符、CLI 命令、文件路径、架构键、JSON/YAML 字段名称、API 名称、软件包名称、专有名词和引用的源文摘录，并使用其所需或原本的语言。

仅在用户明确要求使用其他语言、现有目标产物为保持一致性必须使用其他语言，或机器可读契约要求使用精确的英语词元时，才使用其他语言。如果存在本地化模板或参考资料（例如 *.ko.md 或 *.ko.json），请优先将其用于面向用户的产物。

</output_language>

<instruction_contract>

字段	契约
意图	仅当用户明确要求使用 Codex CLI 时，构建、运行或说明安全的 codex CLI 调用。
范围	负责 codex exec、codex review、恢复/分叉流程、沙盒选择、额外目录标志以及结果摘要。
权限依据	用户意图和本地项目规则优先；必要时根据已安装命令的帮助信息或当前文档核实 Codex CLI 的行为。
依据	回答应以命令格式、CLI 输出、审查输出、沙盒选择以及观察到的警告/错误为依据。
工具	仅当用户要求运行 CLI 时才使用 shell 执行；否则提供命令或转交处理。
输出	返回实际使用或建议使用的确切命令，总结输出/警告，并逐字保留 CLI 词元。
验证	检查非交互运行是否使用 codex exec、审查是否保持只读、可写沙盒是否明确指定，以及绕过标志是否设有使用限制。
停止条件	构建或运行所请求的 Codex 命令，并报告结果、警告或阻碍后即停止。

</instruction_contract>

默认值

参数	默认值
模型选择	使用 Codex CLI 默认值，除非用户明确要求 -m / --model
配置文件	使用 CLI 默认值，除非用户明确要求 -p / --profile
沙盒	分析时使用 --sandbox read-only，仅当用户要求 Codex 编辑时使用 --sandbox workspace-write
审批策略	仅交互模式——使用 CLI 默认值，除非用户明确要求 -a / --ask-for-approval
无头模式	codex exec
恢复目标	恢复最新的非交互运行时使用 codex exec resume --last，恢复最新的交互会话时使用 codex resume --last

除非用户明确提出要求，否则不要询问用户选择的模型、配置文件或审批策略。

路由

当请求确实需要 Codex CLI 或单独的 Codex 会话时，使用此技能。

• 如果请求可能超出范围，在构建命令前阅读 rules/routing.md。
• 如果用户只需要通用写作、文档整理或本地编辑，而不需要实际使用 codex CLI，则转交给直接编辑流程或其他技能。

示例

正向示例：

• “使用 Codex 审查此代码仓库并总结风险。”
• “运行 codex exec 并分析此架构。”
• “继续上一个 Codex 会话，并让它完成补丁。”
• “针对基准分支运行 codex review，并列出阻塞问题。”

反向示例：

• “改写此操作手册，让它更易读。”
• “为我们的代码仓库创建一个新技能。”

边界示例：

• “研究 Codex 沙盒模式并说明其作用。” 仅当用户希望使用 codex CLI 时才使用此技能；否则转交给研究或直接文档处理流程。

重要：非交互模式

非交互式运行 Codex 时，始终使用 codex exec 子命令。 不带子命令调用 codex "prompt" 会启动交互式 TUI。

# Non-interactive
codex exec --sandbox read-only "your prompt here"

# Interactive TUI
codex "your prompt here"

codex exec 从参数或 stdin 读取提示词，并在完成后将结果输出到 stdout。

运行任务

在更改沙盒模式、恢复会话或添加其他目录之前，请阅读 references/recipes.md 中的具体命令示例。

选择沙盒模式

标志	使用场景
--sandbox read-only	常规分析、审查、规划或结构化输出，且不写入文件
--sandbox workspace-write	仅当用户明确希望 Codex 修改工作区中的文件时
--sandbox danger-full-access	仅在获得明确批准后，且仅限隔离环境
--dangerously-bypass-approvals-and-sandbox	仅在获得明确批准后，且仅限由外部沙盒隔离的环境

选择审批策略（仅限交互模式）

-a / --ask-for-approval 仅适用于顶层交互式 codex 命令，不适用于 codex exec。对于非交互式运行，请通过 --sandbox 控制安全性。

标志	使用场景
-a untrusted	仅限交互模式 — 对任何不受信任的命令，Codex 都必须向用户请求升级授权
-a on-request	仅限交互模式 — Codex 判断需要时会请求批准
-a never	仅限交互模式 — Codex 不会请求批准；仅与限制严格的 --sandbox 搭配使用

如果用户未指定，请省略 -a，并采用 CLI 默认设置。

命令规范

• 从 codex exec --sandbox read-only "your prompt here" 开始。
• 仅当用户明确要求时，才添加 -m <model> 或 -p <profile>。
• 仅当用户需要机器可读的 JSONL 输出时，才使用 --json。
• 当用户希望最终响应遵循 JSON schema 时，使用 --output-schema <FILE>。
• 当任务需要访问启动目录以外的文件时，使用 --add-dir <path>；仅在明确要求编辑时，才搭配可写沙盒。
• 当用户指定了其他目录时，使用 -C <dir> / --cd <dir> 设置工作根目录。
• 使用 --dangerously-bypass-approvals-and-sandbox 前，请先征求用户同意。
• 对常规文件编辑，优先使用 --sandbox workspace-write，而不是绕过审批。

恢复会话

codex exec resume --last "continue the previous task"
codex exec resume <session-id> "continue with this follow-up"
codex resume --last       # interactive picker for the latest TUI session

使用 codex exec resume --last 恢复最新的非交互式运行。 当用户指定了某个会话，或最新运行并非所需会话时，使用 codex exec resume <session-id>。 恢复会话时，除非用户明确要求更改模型、配置文件、沙盒或审批策略，否则保留现有会话设置。 仅当用户希望从现有会话分支，而不是继续使用该会话时，才使用 codex fork --last。

代码审查

codex review --uncommitted "review the local changes and list blocking issues"
codex review --base main "review this branch against main and summarize risks"
codex review --commit <sha> "review only the changes in this commit"

codex review 本身为只读操作；不要将其与 --sandbox workspace-write 或 --dangerously-bypass-approvals-and-sandbox 搭配使用。

完成后

• 总结结果，包括任何警告或不完整的输出。
• 告知用户可以使用 codex exec resume --last 或 codex exec resume <session-id> 恢复会话。
• 询问用户是要继续、调整提示词，还是切回直接操作。

审慎评估

把 Codex 当作同事，而不是权威。

• 有可靠依据且确信时，信任自己的知识。
• 若意见不一致，请先查阅最新文档或一手资料，再决定是否接受某项说法。
• 请记住，独立的 Codex 会话也可能出错或信息过时。
• 存在真正的歧义时，让用户决定。

错误处理

• command not found: codex：告知用户尚未安装 OpenAI Codex CLI。
• 身份验证错误：使用 codex login，或检查已配置的 OpenAI 凭据路径。
• 沙箱阻止：仅当用户希望这样做时，使用适当的 --sandbox 重试。
• 审批阻止（仅限交互式 codex）：仅当用户希望这样做时，使用限制较少的 -a 重试。
• 未找到会话：运行 codex exec resume（不带 --last）以使用选择器，或切换为 codex resume --last 以恢复最新的交互式会话。
• 无效标志或模型错误：检查 codex --help 或 codex exec --help，并使用受支持的选项重试。
• 位于 Git 仓库之外：仅当用户已接受此次运行将在没有仓库保护措施的情况下进行时，才添加 --skip-git-repo-check。

<validation_checklist>

• 请求明确需要 Codex CLI 或单独的 Codex 会话。
• 非交互式运行使用 codex exec；自动化不使用交互式 TUI 调用。
• codex review 保持只读，且不与可写沙箱或绕过标志搭配使用。
• 仅当用户明确希望 Codex 修改工作区文件时，才使用 --sandbox workspace-write。
• 最终输出包含命令形式、观察到的结果、警告，以及任何身份验证／会话／沙箱阻止信息。

</validation_checklist>