Codex 画图：Finch 图片生成工具

通过本机已安装并完成 OAuth 登录的 Codex CLI 及其内置 imagegen / image_gen 能力，在 Finch 中生成和编辑图片。

• 使用现有的 Codex OAuth 登录态
• 不需要 OPENAI_API_KEY
• 支持图片生成、编辑、合成及最多 5 张参考图
• 长时间生成任务在后台异步运行，避免触发 Finch 单次工具调用超时
• 同时返回内联图片与可靠的本地预览路径
• 提供 Finch 原生「继续改图」入口，可在 Canvas 批注板标记区域后继续交给 Codex 修改

使用前准备

本 mini tool 会将图片生成任务交给 Codex。安装前，本机需要具备：

1. 较新的 Codex CLI，其中包含系统 imagegen 技能及内置 image_gen 工具。
2. 有效的 Codex OAuth 登录态。
3. Codex 所需的网络连接。

请参考官方文档安装或更新 Codex CLI：

• https://developers.openai.com/codex/cli

常见的 npm 安装方式：

npm install -g @openai/codex

**Windows 说明：**小工具会优先查找原生 codex.exe（npm 版在 Windows 上自带），也支持 npm 生成的 codex.cmd 启动脚本（通过 cmd.exe 调用）。无需手动创建硬链接或修改 PATH。

登录并检查本机环境：

codex login
codex --version
codex login status

codex login status 应显示已登录。本 mini tool 不会读取、复制或保存 OAuth token；身份验证由 Codex CLI 在自己的本地配置中管理。

安装到 Finch

npx @finchtoys/minitools add finch-codex-imagegen

然后打开 Finch → 工具箱 → 小工具，审核所需权限并启用 Codex 画图。

工具需要以下权限：

• 执行命令：启动固定的本机 codex 可执行文件；提示词通过 stdin 传入，不会插入 shell 命令。
• 网络访问：Codex 使用现有 OAuth 会话连接 OpenAI。
• 文件系统读写：读取参考图片，并在当前 Finch 工作目录内写入生成的 PNG 文件。

Agent 工具使用 risk: medium：执行命令固定为 Codex，输出路径限制在工作区内，不覆盖现有文件，并且每个后台任务都有时间上限。

使用方法

直接用自然语言告诉 Finch，例如：

生成一个精致的翠绿色小鸟应用图标，深色背景，不要文字。

以 Image 1 为需要保留的产品，Image 2 为风格参考。保持产品形状和相机角度不变，采用 Image 2 的线条风格和低饱和配色。

注册的工具名为 codex_imagegen_image，支持以下操作：

• status：检查 Codex CLI/OAuth 状态，或使用 job_id 查询异步任务
• generate：生成一张新图片，可选参考图
• edit：编辑或合成图片

generate 和 edit 都支持 input_image_paths，即最多包含 5 张 PNG/JPEG/WebP 图片的有序数组；旧版字段 input_image_path 仍然兼容。

参考图会通过重复的 --image 参数传给 Codex。请在提示词中明确说明 Image 1、Image 2 等各自的用途。使用 edit 时，默认以 Image 1 为主要编辑目标，Image 2–5 为参考图；使用 generate 时，附加图片默认仅作为视觉参考，除非提示词明确要求转换其中某张图片。

可视化继续改图

图片生成完成后，Finch 会在 Composer 显示「继续改图」按钮，并可在同一会话的生成回复结束时询问是否标注修改；普通文字回复和其他会话不会触发此提示：

1. 选择「标注后修改」，在 Canvas 批注板中添加最多 8 个点标记或矩形框。
2. 每放下一个标记，批注板会暂时隐藏，并在可输入的 Finch 原生表单中显示当前标记位置预览、记录该处修改要求；保存后返回批注板，标记出现翠绿色已记录状态，点击已有编号可重新编辑。
3. 全部标记说明完成后点击「完成标注」，mini tool 会把原图作为 Image 1、带标记的定位图作为 Image 2，并将结构化改图请求填入 Composer。ComposerAction 暂不支持强制显示图片缩略图，因此两张图以文件 token 展示；自动生成的定位图使用简短文件名 location-map.png。
4. 输入框只保留简短改图请求、两张图片引用和“标记 1：…”等本地化标记摘要；定位图角色、禁止保留标记及保护未修改区域等内部约束由 ComposerAction 的 getReminder() 在发送时一次性注入，模型可见，但输入框和发送后的消息气泡均不展示。检查后发送，Finch 会继续调用 Codex CLI 改图。

批注图只用于定位，提示词会明确要求 Codex 不得把红色框、点标记或数字保留在最终成品中。刚生成的图片可直接在 Composer 中自然描述下一步修改。Composer 的「历史图片」菜单会跨会话保留最近 5 张生成或修改结果；点击任一历史项会先打开可调整大小的大图预览窗口，确认内容后可选择「标注后修改」或「描述修改这张图」继续迭代。

异步任务

图片生成可能超过 Finch 单次工具调用的等待时间。本 mini tool 会在独立的后台进程中启动 Codex：

1. generate 或 edit 默认等待最多 75 秒。
2. 如果尚未完成，则返回 job_id，而不是取消生成任务。
3. Finch 使用该 job_id 调用 status，每次查询最多可等待 90 秒。
4. 任务运行期间不要重复提交原始生成请求。

每个后台任务最长运行 10 分钟。

输出与预览可靠性

生成文件会写入当前 Finch 工作目录，且绝不会覆盖现有文件。

当成品路径包含非 ASCII 或其他不安全字符时，工具会在自身的扩展数据目录内创建一个仅含 ASCII 字符的预览别名，例如 finch-imagegen-preview-<job-id>.png。路径本身可安全展示时会直接使用成品文件，不会在成品旁边再创建别名。

这样既能避免本地 Markdown 图片预览失败，也不会污染当前工作目录。工具会返回一行准确的 Markdown 供 Finch 展示，并明确要求 Agent 不要使用 Session attach，以免错误地把生成图片放入用户的 Composer 附件区。

限制

• 最多 5 张输入图片
• 输入格式支持 PNG、JPEG 和 WebP
• 每张输入图片最大 30 MB
• 输出格式为 PNG
• 内联预览最大 15 MB；更大的成品仍可通过文件路径访问
• 后台任务最长 10 分钟
• 输出必须位于当前 Finch 工作目录内

Codex 内置图片生成会计入用户的 Codex 使用额度。功能是否可用取决于用户套餐、工作区设置、网络环境和 Codex 版本。

故障排查

找不到 Codex CLI

检查：

command -v codex
codex --version

本 mini tool 会搜索 PATH，也会检查 /usr/local/bin/codex、/opt/homebrew/bin/codex 等常见位置。

Codex 尚未登录

在本机运行：

codex login
codex login status

不要在 Finch 对话中粘贴 OAuth token。

imagegen 或 image_gen 不可用

更新 Codex CLI，并确认当前版本包含系统图片生成技能。本 mini tool 会刻意禁用依赖 API Key 的 scripts/image_gen.py 回退方案。

结果显示任务仍在运行

使用返回的 job_id 调用 action=status，并设置 wait_for_seconds=90。不要再次生成同一张图片。

图片文件存在，但 Markdown 预览失败

使用工具返回的 ASCII 预览路径，而不是原始文件名。自 0.2.1 起，工具会自动创建该别名。

安全与隐私

• 本 mini tool 不读取或保存 OAuth token 与 API Key。
• 子进程环境中会移除 OPENAI_API_KEY，防止意外回退到 API 计费。
• 提示词通过 stdin 传给 Codex，不会写入 mini tool 的任务元数据。
• Codex 使用 --sandbox workspace-write、--ephemeral 和 --skip-git-repo-check 运行。
• 输出路径被限制在当前 Finch 工作区内。
• 输入路径会经过格式和文件大小校验。
• 用户提示词绝不会被插入 shell 命令。

许可证

MIT