codex-cli

Codex CLI

当用户要求此 Agent 与 Codex 对话、咨询 Codex、委派编码／审查／研究任务给 Codex CLI，或让 Codex 生成图像时，使用此技能。

核心接口是：

codex exec "prompt"

自动化时，优先使用非交互式的 codex exec，而不是交互式的 codex。

首先检查

使用 Codex CLI 前，确认其可用：

command -v codex
codex --version
codex exec --help

如果缺少 codex，请告知用户当前环境无法使用 Codex CLI，然后停止。不要模拟 Codex 的回复。

如果可以使用 codex exec --help，请以其内容为准，确认已安装 CLI 支持的标志。Codex CLI 会随时间变化。

单次任务工作流

用于常规委派：

codex exec -C "$PWD" -s read-only "Review this repository and identify likely bugs"

对于可能会编辑文件的任务，使用用户要求或宿主 Agent 允许的沙盒：

codex exec -C "$PWD" -s workspace-write "Implement the requested change"

对于响应文件：

codex exec -C "$PWD" -o /tmp/codex-last-message.md "Summarize this project"

对于机器可读事件：

codex exec -C "$PWD" --json -o /tmp/codex-last-message.md "Analyze this project"

如果提示词很长，请通过 stdin 传递：

codex exec -C "$PWD" - < /tmp/prompt.txt

从其他 Agent 使用 shell 命令时，除非用户明确要求，否则避免使用危险标志。对于审查、规划、评议、图像生成和分析，优先使用 read-only。

提示词结构

对于复杂任务，按照 OpenAI 的 Codex 最佳实践结构来组织委派提示词：

Goal:
Context:
Constraints:
Done when:

将提示词限定为单个任务。对于复杂的实现工作，先在 read-only 模式下让 Codex 制定计划，待计划获批后，再单独执行写入任务。

恢复会话

Codex 会在常规启动输出以及 JSONL 事件的 thread.started 中输出会话 ID。

恢复会话：

codex exec resume <session-id> "Continue from the previous task"

如果已安装的 CLI 支持不同的恢复语法，请遵循 codex exec resume --help。

图像和文件输入

Codex 无法自行浏览或读取图像文件。如需让 Codex 查看 图像，请使用 -i/--image 显式附加。这是输入端；图像生成（见下文）则是输出端。

附加单张图像：

codex exec -C "$PWD" -s read-only -i screenshot.png "Explain the error shown here"

附加多张图像。以下两种形式均可使用：逗号分隔或重复标志：

codex exec -i before.png,after.png "Compare these two UI states"
codex exec -i mock1.png -i mock2.png "Which layout is closer to the spec?"

最佳实践：

• 将 -i 标志放在提示词文本之前。
• 使用常见的光栅格式：PNG（最适合截图／UI，无损）或 JPEG。图像大小应适中；过大的图像会拖慢请求。
• 将图像与清晰的文字说明一起提供——仅有图像通常不足以提供上下文。
• 进行视觉审查／分析时，搭配 -s read-only 使用，让 Codex 检查但不编辑。

对于非图像文件，没有附加标志。可以采用以下两种方式：

• 让 Codex 从工作区读取文件：使用 -C "$PWD" 指定目录，并在提示词中写明文件名（"Review src/auth.ts"）。适用于仓库中已有的文件。
• 通过 stdin 传递文件内容。如果同时提供提示词，stdin 内容会作为 <stdin> 块追加到提示词中：

codex exec -C "$PWD" "Summarize the attached log" < /tmp/build.log

图像生成工作流

通过 codex exec 请求时，Codex 可以使用内置的图像生成工具生成图像。

示例：

codex exec "Generate a black banana image with aspect ratio 16:9"

重要行为：

• 内置图像生成通常会将文件保存到 $CODEX_HOME/generated_images/<codex-session-id>/。
• 如果未设置 CODEX_HOME，则使用 ~/.codex/generated_images/<codex-session-id>/。
• Codex 可能不会在最终回复中打印路径。
• 使用此技能的 Agent 必须在图像生成后主动查找并报告生成图像的路径。
• PNG 元数据可能无法显示确切的图像模型。除非 Codex 输出、CLI 日志或元数据明确显示，否则不要声称使用了特定的后端模型。

查找生成的图像

每次请求 Codex 生成图像后，都要在回复前找到图像路径。

首先，从输出中提取 Codex 会话 ID（如果有）。其格式可能如下：

session id: 019e8cbf-5054-7131-9440-ee592f0d8a17

然后检查：

ls -l "${CODEX_HOME:-$HOME/.codex}/generated_images/<session-id>"

如果不知道会话 ID，请列出最近生成的图像：

find "${CODEX_HOME:-$HOME/.codex}/generated_images" -type f -maxdepth 3 -print

如果可以，请按修改时间排序：

find "${CODEX_HOME:-$HOME/.codex}/generated_images" -type f -maxdepth 3 -print0 \
  | xargs -0 ls -lt

如果用户请求的是项目资源，并且权限允许，则在生成后将所选图像复制或移动到项目中。不要让项目引用的资源只留在 $CODEX_HOME/generated_images 下。

验证宽高比

如果用户要求特定宽高比，请在回答前验证尺寸。

在 macOS 上：

sips -g pixelWidth -g pixelHeight /path/to/image.png

跨平台替代方案：

file /path/to/image.png

报告实际尺寸，并说明它们是大致匹配还是完全匹配。许多生成的图像会采用最接近的整数尺寸，因此，要求 16:9 时，生成的尺寸可能是 1672 x 941，这在实际效果上符合 16:9，但在数学上并不完全精确。

报告结果

对于常规 Codex 任务，请报告：

• 使用的命令；如果命令较长，可概述
• Codex 状态或最终答复
• Codex 修改的任何文件（如果已知）
• 任何限制、错误或权限不足的情况

对于图像任务，请务必报告：

• 生成的图像路径
• 实际尺寸（如果可用）
• 路径位于 $CODEX_HOME 中，还是已复制到项目中
• 是否知道确切的图像模型

示例答复：

Codex generated the image here:
/Users/me/.codex/generated_images/019e.../ig_....png

Actual size: 1672 x 941, effectively 16:9.
The output does not expose the exact image backend model, so I cannot verify whether it was gpt-image-2.

故障处理

如果 Codex 因网络、身份验证或模型刷新错误而退出，请明确报告错误，并附上相关的 stderr 行。

如果 Codex 声称已生成图像，但 $CODEX_HOME/generated_images 下不存在图像文件，请明确说明，不要编造路径。

如果宿主 Agent 无法读取 $CODEX_HOME/generated_images，请请求用户授予访问权限，或运行：

find "${CODEX_HOME:-$HOME/.codex}/generated_images" -type f -maxdepth 3 -print0 | xargs -0 ls -lt

安全提示

除非用户明确要求并了解风险，否则不要向 Codex 传递机密信息。

进行咨询时使用 read-only。只有在预期 Codex 会编辑文件时，才使用 workspace-write。除非用户明确要求在受控环境中使用，否则避免使用 danger-full-access。

不要仅凭 Codex 的最终消息就声称它已完成工作。当文件变更很重要时，请在运行后检查文件系统或 Git diff。