codex-vision

codex-vision

封装 OpenAI Codex CLI（上游二进制文件位于 /Applications/Codex.app/Contents/Resources/codex），用于视觉任务——图像输入、图像生成、图像编辑——让 Claude 无需手动编写临时文件或每次都亲自通过 Shell 调用，即可调用 Codex。

何时调用此技能

有两种触发方式：

A. 显式调用——无条件触发。 任何匹配 use codex-vision、/codex-vision 或直接调用此封装程序的 Shell 命令都会触发。无需图像上下文（用户有意指定此技能）。

B. 图像意图触发——需要同时具备图像上下文和 Codex 意图。 图像上下文包括：现有图像路径／附件（PNG、JPG、JPEG、WebP、GIF）、用户正在引用的刚生成的截图，或明确要求生成／编辑视觉内容（模型图、线框图、设计图）。单独出现“codex”一词不足以触发；没有目标文件的单独“screenshot”也不足以触发。

• 用户要求 Claude 让 Codex 查看某张特定截图或磁盘上的 PNG／JPG 路径 → review。
• 用户要求 Codex 生成图像／模型图／线框图／设备框架渲染图（必须明确表达 Codex 意图——仅说“生成一个模型”会转到其他工具）→ generate。
• 用户要求 Codex 编辑／标注／清理现有图像文件（必须提供路径）→ edit。
• 刚刚生成了一张截图（例如由 mcp__claude-in-chrome__computer 使用 save_to_disk: true 保存）并且用户明确要求 Codex 侧审查该图像——而不只是截图生成后接着进行的任意 Codex 任务。

何时不调用此技能

以下情况默认使用普通的 codex exec 或持久化 Codex 会话技能：

• 用户要求 Codex 审查代码、PR、差异、函数——纯文本，没有图像。-i 标志无关。
• 用户要求 Codex 编写、重构或调试代码——直接调用 codex exec "<prompt>"。
• 用户向 Codex 提出一般性问题（“问问 codex 对 X 的看法”“让 codex 解释 Y”），且没有附带图像。
• 用户想要使用 Codex 进行长时间运行的代码仓库编码会话，尤其是由截图驱动的实现循环——改用已安装的持久化 Codex/tmux 工作流，以便同一个限定在该代码仓库范围内的 Codex 会话能够审查、实现、测试并恢复。
• 用户提到“codex”，但实际内容是文本（日志、堆栈跟踪、JSON、代码）——codex-vision 无法提供帮助；image_gen 工具提示词会误导模型。
• 用户的磁盘上有截图，但当前请求与该截图无关——不要仅因为 /tmp/ 中存在 PNG 就自动触发。

如果用户意图不明确（“Codex，看看我的作品”），先暂停并询问内容是图像还是文本，再选择调用路径。

如何调用

此技能是一个独立的 Shell 封装程序。通过 Bash 工具运行：

~/.claude/skills/codex-vision/scripts/codex-vision.sh <mode> [options] <args>

长时间运行的图像任务

对于持久化代码仓库工作，不要使用此技能的 --tmux 模式。该模式只是对一次性 codex exec 调用的可观测封装。

对于“使用这张仪表盘截图，重新设计页面、实现代码、测试，并稍后继续”等任务，请改用已安装的持久化 Codex/tmux 工作流，而不是 codex-vision。该工作流应保留限定在代码仓库范围内的 Codex UUID，支持重复附加图像，并将输入／输出图像保存在代码仓库的 .agent/codex/images/ 交接目录中。

内容存储

此技能有意设计为临时的一次性工具。不要通过 codex-vision 创建或管理代码仓库本地的 .agent/codex/ 目录树。

• 输入图像从调用者提供的路径读取。如果调用者提供 URL，请先将其下载到 /tmp/。
• 生成和编辑后的图像默认保存到 /tmp/codex-vision-out/<slug>-<timestamp>.png。
• tmux 观察日志默认保存到 /tmp/claude-codex-<slug>.log。

如果用户需要持久的代码仓库本地图像历史、重复截图，或与实现工作相关联的生成素材，请改用持久化 Codex/tmux 工作流。

模式

模式	概述	功能
review IMAGE [IMAGE...] PROMPT	单次图像审查	运行 codex exec -i ...
generate PROMPT	请求 Codex 生成图像	将提示词包装为 "Use image_gen to ; save to "
edit IMAGE PROMPT	请求 Codex 编辑图像	将提示词包装为 "Use image_gen to edit the attached image: ..."

选项

选项	效果
--out PATH	生成或编辑后图像的输出路径（默认：/tmp/codex-vision-out/<slug>-<ts>.png）
--tmux NAME	在 claude-codex-<NAME> tmux 会话中运行；用户可以使用 tmux attach -t claude-codex-<NAME> 实时查看
--keep	完成后保留 tmux 会话和日志（默认：清理）
--model MODEL	传递给 codex exec --model（例如 gpt-5-codex）
--resume UUID	按 ID 恢复指定的 codex 会话；适用于调用方已知 UUID 的情况
--resume-last-vision	强制恢复最近的 codex-vision 会话（缓存于 ~/.claude/skills/codex-vision/.last-session-uuid）
--fresh	强制启动全新的 codex 会话，即使提示词的措辞会触发智能恢复启发式规则

会话续接

该包装器会在后续调用间保留 codex 上下文，以便迭代模型图或重新审查更新后的屏幕截图时，无需再次承担冷启动开销。每次成功调用都会将 codex 会话 UUID 记录到 ~/.claude/skills/codex-vision/.last-session-uuid，下一次调用会通过一条简单的启发式规则查询该缓存：

• 自动恢复仅适用于 review。如果 review 提示词包含后续操作措辞——continue、iterate、follow up、based on the previous、again with、now also、now add、also add、refine、tweak、as before、same image、keep going——包装器会自动恢复缓存的会话（重新审查更新后的屏幕截图时会保留上下文）。
• generate / edit 永远不会自动恢复（即使提示词包含后续操作措辞）：恢复图像会话会再次生成大致相同的图像（重复生成相同图像的 bug）。除非传入 --resume <UUID> / --resume-last-vision，否则它们会启动全新会话。
• 否则，包装器会启动全新会话，并使用新的 UUID 更新缓存。

标志优先级（从高到低）：--fresh（始终新建）> --resume UUID （使用指定 UUID）> --resume-last-vision（强制使用缓存）> 启发式规则。

恢复的会话会沿用原始轮次的 codex 沙盒和工作区配置，因此 generate / edit 会写入与首次运行相同的 OUT_PATH 父目录，无需再次传入 --sandbox。如果缓存文件不存在，启发式规则会静默回退到新会话，不会报错。

Claude 必须遵循的约定

• tmux 会话名称始终以 claude-codex- 为前缀。 脚本会强制执行此规则；绝不可绕过。这样用户可以通过 tmux ls | grep claude-codex- 识别 Claude 启动的会话。
• 日志写入 /tmp/claude-codex-<slug>.log——路径固定，方便用户独立运行 tail -f 查看。
• 图像默认输出到 /tmp/codex-vision-out/。
• 不要将 codex-vision 图像写入 .agent/codex/——该目录用于持久的、限定于仓库的 Codex/tmux 会话。
• **仅在以下情况使用 --tmux：**预计运行时间超过 30 秒，或用户希望观察／中断任务，或用户明确要求创建会话。对于快速图像审查，默认使用同步模式。
• 对于混合工作流（输入图像 + 生成结果），使用 edit 模式——它会在一次 Codex 调用中处理两部分。

示例

# Quick screenshot review
~/.claude/skills/codex-vision/scripts/codex-vision.sh review /tmp/ui.png "What's wrong with this layout?"

# Image generation
~/.claude/skills/codex-vision/scripts/codex-vision.sh generate "isometric diagram of a 4-trajectory GRPO group with advantages" --out /tmp/grpo.png

# Image editing
~/.claude/skills/codex-vision/scripts/codex-vision.sh edit /tmp/raw.png "remove the red overlay; make background transparent" --out /tmp/clean.png

# Long observable review
~/.claude/skills/codex-vision/scripts/codex-vision.sh review /tmp/ui.png "deep walk-through" --tmux ui-review
# user attaches with: tmux attach -t claude-codex-ui-review

此技能触发时 Claude 的处理方式

1. 根据用户意图识别模式：review（查看图像）/ generate（生成图像）/ edit（修改图像）。
2. 解析图像路径——这些路径应该已存在于磁盘上。如果用户提供 URL，先下载到 /tmp/。
3. 使用 shell wrapper 构建命令。只调用一次 Bash。
4. 选择同步模式还是 --tmux：短任务使用同步模式；如果用户想要实时查看，或任务需要长时间运行，则使用 --tmux。
5. 调用后，返回 Codex 的文本回复（review 模式），或返回输出路径和一句话摘要（generate / edit 模式）。
6. 如果 OUT_PATH 中存在生成的文件，将其展示给用户（例如：“图像已保存到 /tmp/codex-vision-out/...”）。

前置条件

此技能要求：

• 已安装 Codex CLI（macOS 上为 /Applications/Codex.app/Contents/Resources/codex，或 PATH 中的 codex，来自 OpenAI Codex CLI）
• 已通过 Codex 身份验证——用户已运行过一次 codex login（或已登录 Codex.app）
• 如果使用 --tmux，则已安装 tmux（macOS 上运行 brew install tmux）

脚本按以下顺序自动检测 codex 二进制文件：

1. $CODEX_VISION_CODEX_BIN（显式覆盖——可指向任意 codex 二进制文件）
2. which codex（PATH 中的任意位置）
3. /Applications/Codex.app/Contents/Resources/codex（独立的 Codex.app）
4. /Applications/ChatGPT.app/Contents/Resources/codex（捆绑在 ChatGPT.app 中的 codex——合并到 ChatGPT.app 中的 Codex 应用）
5. 每用户 ~/Applications/ 下的同两个应用包
6. 失败并显示清晰的错误消息

如果 codex 位于不常见的位置，请运行 export CODEX_VISION_CODEX_BIN=/path/to/codex。

用户如何安装此技能

如果用户询问“如何安装 codex-vision”，或想与他人分享，可通过 npx skills 安装。

仅限 Claude Code——直接放入 ~/.claude/skills/codex-vision/：

npx skills add thenamangoyal/codex-vision -g -a claude-code -y

一次安装到所有 Agent——Claude Code、Cursor、Codex CLI、Gemini CLI。源文件只写入一次到 ~/.agents/skills/codex-vision/，再通过符号链接放入各个 Agent 的技能目录：

npx skills add thenamangoyal/codex-vision -g --all

使用 @v0.3.1 固定特定版本。对于项目范围的安装，去掉 -g。使用 npx skills remove codex-vision 卸载。

验证：

~/.claude/skills/codex-vision/scripts/codex-vision.sh doctor
~/.claude/skills/codex-vision/scripts/codex-vision.sh selftest

直接克隆作为备用方案（无需 npx skills）：git clone https://github.com/thenamangoyal/codex-vision ~/.claude/skills/codex-vision。

触发测试

触发评估（tests/triggering/cases.yaml + scripts/check-triggering.sh） 会用 50 条手写的用户提示词，对此清单中的触发门控进行基准测试—— 其中 15 条应触发，20 条应跳过，15 条应要求澄清。运行器会将所有用例 批量放入一次 codex exec 调用，解析判定结果，并在出现任何假阳性 （预期为 skip/clarify，但模型回答 FIRE）或假阴性（预期为 fire，但模型回答 SKIP/CLARIFY）时失败。截至 v0.3.2，连续 3 次试运行均稳定达到 50/50。运行方式：

bash ~/.claude/skills/codex-vision/scripts/check-triggering.sh             # one trial
bash ~/.claude/skills/codex-vision/scripts/check-triggering.sh --runs 3    # majority over 3

如果修改 YAML description 或 When to invoke / When NOT to invoke 部分，请重新运行测试并收紧措辞，直到结果恢复到 50/50。

会话模式压力测试

会话续接逻辑有自己的回归测试，位于 tests/session-modes/check-session-modes.sh。它会模拟 codex CLI， 在私有的 CODEX_HOME 下生成逼真的 rollout 文件，并断言四种核心行为： 默认启动新会话、--resume UUID、启发式续接 （提示词包含后续跟进的措辞）以及启发式新会话（提示词不包含此类措辞）。 第五种情况验证 --fresh 会覆盖启发式判断。每次运行都会将 markdown 摘要写入 tests/session-modes/results-<timestamp>.md。运行方式：

bash ~/.claude/skills/codex-vision/tests/session-modes/check-session-modes.sh

此测试离线运行（不联网，不进行真实的 codex 调用）；每次修改 wrapper 的会话续接代码块后都应重新运行。

注意事项

• 不要绕过 claude-codex- 前缀——用户通过它识别由 Claude 启动的会话。
• 除非传入了 --keep，否则不要遗留日志或会话。
• 未经询问，不要将图像写入用户的代码库；默认的 /tmp/codex-vision-out/ 是安全的。
• 不要对仅需 5 秒的简单审核使用 --tmux——这只会带来额外开销。