codex-cli

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Codex CLI

Use this skill when the user asks this agent to talk to Codex, consult Codex, delegate a coding/review/research task to Codex CLI, or ask Codex to generate an image.

The core interface is:

bash

codex exec "prompt"

For automation, prefer non-interactive

codex exec

over interactive

codex

当用户要求本Agent与Codex交互、咨询Codex、将编码/审查/研究任务委托给Codex CLI，或者请求Codex生成图片时，使用本技能。

核心接口为：

bash

codex exec "prompt"

对于自动化场景，优先使用非交互式的

codex exec

而非交互式的

codex

。

First Check

首次检查

Before using Codex CLI, verify it is available:

bash

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

codex

is missing, tell the user Codex CLI is not available in this environment and stop. Do not simulate a Codex response.

codex exec --help

is available, use it as the source of truth for the installed CLI flags. Codex CLI changes over time.

使用Codex CLI之前，需验证其是否可用：

bash

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

如果

codex

不存在，告知用户当前环境中无法使用Codex CLI并停止操作，请勿模拟Codex的响应。

如果

codex exec --help

可用，请将其作为已安装CLI参数的权威参考，因为Codex CLI会随时间更新。

One-Off Task Workflow

一次性任务工作流

Use this for normal delegation:

bash

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

For tasks that may edit files, use the sandbox the user requested or the host agent allows:

bash

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

For a response file:

bash

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

For machine-readable events:

bash

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

If the prompt is long, pass it via stdin:

bash

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

When using shell commands from another agent, avoid dangerous flags unless the user explicitly asked for them. Prefer

read-only

for review, planning, critique, image generation, and analysis.

以下适用于常规委托任务：

bash

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

对于可能编辑文件的任务，请使用用户请求的沙箱或宿主Agent允许的环境：

bash

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

如需将结果输出到文件：

bash

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

如需机器可读的事件输出：

bash

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

如果提示内容较长，可通过标准输入传递：

bash

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

当从其他Agent执行Shell命令时，除非用户明确要求，否则避免使用危险参数。对于审查、规划、评估、图片生成和分析任务，优先使用

read-only

模式。

Prompt Shape

提示格式

For non-trivial tasks, shape the delegated prompt with OpenAI's Codex best-practices structure:

text

Goal:
Context:
Constraints:
Done when:

Keep the prompt scoped to one task. For complex implementation work, ask Codex for a plan first in

read-only

mode, then run a separate write task after the plan is accepted.

对于非简单任务，请按照OpenAI的Codex最佳实践结构组织委托的提示内容：

text

Goal:
Context:
Constraints:
Done when:

确保提示内容仅聚焦于单个任务。对于复杂的开发工作，先在

read-only

模式下请求Codex制定计划，待计划通过后再执行单独的写入任务。

Session Resume

会话恢复

Codex emits a session id in normal startup output and in JSONL events as

thread.started

To resume:

bash

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

If the installed CLI supports a different resume syntax, follow

codex exec resume --help

Codex会在正常启动输出和JSONL事件的

thread.started

字段中返回会话ID。

恢复会话的命令：

bash

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

如果已安装的CLI支持其他恢复语法，请遵循

codex exec resume --help

的说明。

Image and File Input

图片与文件输入

Codex cannot browse or read image files on its own. To let Codex see an image, attach it explicitly with

-i

--image

. This is the input side; image generation (below) is the output side.

Attach a single image:

bash

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

Attach multiple images. Both forms work — comma-separated or a repeated flag:

bash

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?"

Best practices:

Put
```
-i
```
flags before the prompt text.
Use common raster formats: PNG (best for screenshots/UI, lossless) or JPEG. Keep images reasonably small; very large images slow the request.
Combine images with a clear text instruction — the image alone is rarely enough context.
For visual review/analysis, pair with
```
-s read-only
```
so Codex inspects but does not edit.

For non-image files there is no attach flag. Two options:

Let Codex read the file from the workspace: point it at the directory with
```
-C "$PWD"
```
and name the file in the prompt (
```
"Review src/auth.ts"
```
). Use this for files already in the repo.
Pipe file contents via stdin. With a prompt also present, stdin is appended to the prompt as a
```
<stdin>
```
block:

bash

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

Codex无法自行浏览或读取图片文件。要让Codex“查看”图片，需通过

-i

--image

参数显式附加。这是输入环节；下文的图片生成属于输出环节。

附加单张图片：

bash

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

附加多张图片。以下两种格式均适用——逗号分隔或重复使用参数：

bash

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>
```
块附加到提示末尾：

bash

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

Image Generation Workflow

图片生成工作流

Codex can generate images through its built-in image generation tool when asked through

codex exec

Example:

bash

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

Important behavior:

Built-in image generation commonly saves files under
```
$CODEX_HOME/generated_images/<codex-session-id>/
```
.

CODEX_HOME

is unset, use

~/.codex/generated_images/<codex-session-id>/

Codex may not print the path in its final response.
The agent using this skill must proactively locate and report generated image paths after image generation.
The PNG metadata may not expose the exact image model. Do not claim a specific backend model unless Codex output, CLI logs, or metadata clearly show it.

通过

codex exec

请求时，Codex可通过内置的图片生成工具生成图片。

示例：

bash

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日志或元数据明确显示，否则请勿声称使用了特定的后端模型。

Finding Generated Images

查找生成的图片

After any Codex image-generation request, find the image path before replying.

First extract the Codex session id from output if available. It may look like:

text

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

Then check:

bash

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

If the session id is not known, list recent generated images:

bash

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

When possible, sort by modification time:

bash

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

If the user requested a project asset, copy or move the selected image into the project after generation if permissions allow. Never leave a project-referenced asset only under

$CODEX_HOME/generated_images

完成任何Codex图片生成请求后，需先找到图片路径再回复用户。

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

text

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

然后执行以下命令检查：

bash

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

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

bash

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

如有可能，按修改时间排序：

bash

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

如果用户请求生成项目资源，在权限允许的情况下，生成后需将选中的图片复制或移动到项目目录中。切勿将项目引用的资源仅保留在

$CODEX_HOME/generated_images

目录下。

Verifying Aspect Ratio

验证宽高比

If the user requested a specific aspect ratio, verify dimensions before answering.

On macOS:

bash

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

Portable fallback:

bash

file /path/to/image.png

Report actual dimensions and whether they match approximately or exactly. Many generated images use nearest integer dimensions, so a 16:9 request may produce dimensions like

1672 x 941

, which is effectively 16:9 but not mathematically exact.

如果用户要求特定的宽高比，回复前需验证图片尺寸。

在macOS系统中：

bash

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

跨平台备选方案：

bash

file /path/to/image.png

报告实际尺寸以及是否大致或完全符合要求。许多生成的图片会使用最接近的整数尺寸，因此16:9的请求可能生成

1672 x 941

这样的尺寸，虽然在数学上不精确，但实际效果接近16:9。

Reporting Results

结果报告

For normal Codex tasks, report:

command used, summarized if long
Codex status or final answer
any files Codex changed, if known
any limitations, errors, or missing permissions

For image tasks, always report:

generated image path
actual dimensions if available
whether the path is in
```
$CODEX_HOME
```
or copied into the project
whether the exact image model is known or not

Example response:

text

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任务，需报告：

使用的命令（如果过长可简化）
Codex的状态或最终答案
Codex修改的所有文件（如果已知）
任何限制、错误或缺失的权限

对于图片任务，必须报告：

生成的图片路径
实际尺寸（如果可用）
路径位于
```
$CODEX_HOME
```
还是已复制到项目目录
是否明确知道使用的图片模型

示例回复：

text

Codex生成的图片路径如下：
/Users/me/.codex/generated_images/019e.../ig_....png

实际尺寸：1672 x 941，效果接近16:9。
输出未显示具体使用的图片后端模型，因此无法确认是否使用了gpt-image-2。

Failure Handling

故障处理

If Codex exits with network, auth, or model refresh errors, report the error plainly and include the relevant stderr lines.

If Codex claims it generated an image but no image file exists under

$CODEX_HOME/generated_images

, say so explicitly and do not invent a path.

If the host agent cannot read

$CODEX_HOME/generated_images

, ask the user to grant access or run:

bash

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

如果Codex因网络、权限或模型刷新错误退出，请直接报告错误并附上相关的标准错误输出行。

如果Codex声称已生成图片，但

$CODEX_HOME/generated_images

下不存在对应文件，请明确说明，切勿编造路径。

如果宿主Agent无法读取

$CODEX_HOME/generated_images

目录，请请求用户授予访问权限或执行以下命令：

bash

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

Safety Notes

安全注意事项

Do not pass secrets to Codex unless the user explicitly asks and understands the risk.

Use

read-only

for consultation. Use

workspace-write

only when Codex is expected to edit files. Avoid

danger-full-access

unless the user explicitly requested it in a controlled environment.

Do not claim Codex performed work solely from its final message. When file changes matter, inspect the filesystem or Git diff after the run.

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

咨询任务使用

read-only

模式。仅当需要Codex编辑文件时才使用

workspace-write

模式。除非用户在受控环境中明确要求，否则避免使用

danger-full-access

模式。

切勿仅根据Codex的最终消息就声称其已完成工作。当文件变更很重要时，需在运行后检查文件系统或Git差异。