用 `-i` 把截图和设计稿带进 Codex 首轮指令

2026-08-09

有些活儿用文字描述特别累。页面上某个按钮的边距歪了、弹窗里的报错截了个图、设计稿标注了一堆间距和圆角——你要把这些转成一段文字提示词，光写描述就得花五分钟，还容易写漏。Codex（OpenAI Codex）的命令行工具给了一个更直接的入口：把图片文件当成首轮指令的一部分带进去。

这个入口就是顶层选项 -i, --image <FILE>...。在 codex-cli 0.147.0（Windows 11）上执行 codex --help，它在顶层选项区的官方说明是”给首轮指令附图”。注意两点：它是顶层选项，不是 codex exec 的专有选项；参数写成 <FILE>...，末尾那三个点说明它不止收一个文件。

先把话说在前面：我们这台机器上只跑过只读命令，一次模型对话请求都没发过。所以这篇文章能告诉你命令怎么写、产出落在哪、哪几处要检查，但不会告诉你”Codex 看图看得准不准”——那需要真实发请求才能下结论，本文不编。

一、命令怎么写

交互式：最常用的一条

codex --help 给出的用法行是 codex [OPTIONS] [PROMPT]，也就是说不带子命令时，选项透传给交互式 CLI，[PROMPT] 直接作为位置参数带入首轮指令。所以最短的一条长这样：

codex -i ./design/login-shot.png "对照这张截图，找出登录页按钮与输入框之间的间距问题，先只给分析，不要改文件"

拆开说每个部分为什么在这：

-i ./design/login-shot.png：图片路径。按 codex --help 的用法行 codex [OPTIONS] [PROMPT]，选项写在 prompt 前面，-i 是顶层选项，照这个顺序写就对了。
结尾那句”先只给分析，不要改文件”：不是玄学，是给自己留一步。首轮带图的场景常常是”我还没想好怎么改”，先让它说，再决定要不要放权。

如果要一次带多张图（比如改前改后各一张），<FILE>... 说明这个选项可以接多个文件。具体写法以你本机 codex --help 的实际输出为准，别照抄别人博客里的写法。

Windows 上的路径坑

本站读者用 Windows 的多，这里分开写：

# Git Bash：用正斜杠，路径带空格或中文时整段加引号
codex -i "./docs/截图 2026-08-09.png" "这张图里的报错是什么原因"

# PowerShell：反斜杠可用，同样建议引号包住
codex -i ".\docs\login-shot.png" "对照这张截图列出布局问题"

在 Git Bash 里写 Windows 风格的反斜杠路径是高频事故：反斜杠会被 shell 当成转义符处理，你以为传出去的路径和 shell 实际拼出来的并不是一回事。养成习惯——Git Bash 一律正斜杠，写完先自己 ls 一下那个路径。

配合工作目录和沙箱

真实项目里很少是”当前目录就是仓库根”。把这几个选项组合上：

codex -C /d/work/repo -s read-only -a untrusted \
  -i ./ui/bug-shot.png \
  "对照截图定位问题代码位置，列出涉及的文件和行号，不要修改任何文件"

-C, --cd <DIR>：指定 agent 的工作根目录。图片路径是相对你执行命令时的当前目录还是相对 -C 指定的根目录，是最容易含糊的地方——省事的办法是图片直接写绝对路径，或者干脆先 cd 到仓库根再执行。
-s read-only：官方对这一档的原文是”The agent can inspect files, but it can’t edit files or run commands without approval.”。看图定位问题这类活儿本来就不需要写权限，先卡死更省心。顺带一提，官方标注的默认模式是 workspace-write，不是只读。
-a untrusted：审批策略里最紧的一档，只有”受信任”命令（如 ls、cat、sed）免审批，模型提出不在受信集合内的命令时升级给你确认。

有个概念一定要分清：-a never 的官方释义是”从不询问，执行失败直接回传给模型”，它改变的只是要不要问你，沙箱边界还在。真正撤掉边界的是 -s danger-full-access 或者 --dangerously-bypass-approvals-and-sandbox（官方对后者的原文是 “EXTREMELY DANGEROUS. Intended solely for running in environments that are externally sandboxed”）。把”never”当成”放权”是最常见的误读。

二、产出物长什么样

交互式模式下产出就在 TUI 里，看完即走。要把结果接进后续流程，得换成 codex exec（官方说明 “Run Codex non-interactively”）。它有三个跟产出直接相关的选项，全部来自 codex-cli 0.147.0（Windows 11）上 codex exec --help 的实测输出：

选项	官方说明	产出形态
`--json`	事件以 JSONL 打到 stdout	一行一个事件的流
`-o, --output-last-message <FILE>`	把 agent 的最后一条消息写到文件	单个文件，只有最终结论
`--output-schema <FILE>`	一个 JSON Schema 文件路径，描述模型最终回复的结构	让最终回复按你定义的结构返回

组合起来大概是这样：

codex -i ./ui/bug-shot.png exec \
  --skip-git-repo-check \
  -o ./out/ui-review.md \
  "对照截图列出页面上的视觉问题，每条给出可能的样式文件"

以上按 codex [OPTIONS] <COMMAND> [ARGS] 的用法行组合，未逐项实测，以你本机 codex exec --help 为准。

几个关键点：

-o 写出的是最后一条消息，不是完整过程。你要的是”一份可以贴进 issue 的结论”就用它；要的是”每一步做了什么”就用 --json 自己解析 JSONL。
--json 输出的每个事件里具体有哪些字段，本文不列——我们没有实际跑过对话请求，编字段名会把读者带沟里。真要接管道，先自己跑一次把前几行 dump 下来看。
--output-schema 接的是一个 JSON Schema 文件。想让”看图找问题”变成一份结构化清单（比如每条包含严重程度、涉及文件），schema 得你自己写。
--skip-git-repo-check 允许在非 Git 仓库里运行。纯粹看一张图、不碰代码时，工作目录经常不是仓库，加上它省事。
另外两个在自动化里常配的：--ephemeral（不把会话文件落盘）、--ignore-user-config（不加载 $CODEX_HOME/config.toml，但auth 仍然使用 CODEX_HOME）。后者容易误以为”什么都不读了”，其实凭据照读。

三、怎么验收

按这个顺序查，能挡掉绝大部分”图好像没进去”的情况。

第一步，确认图片能力在本版本是什么状态。 跑 codex features list，它输出三列：特性名、阶段、当前生效值。在 codex-cli 0.147.0（Windows 11）上，view_image 这一行是 stable / true。这一步的意义在于：阶段会随版本变，别拿别人半年前的截图当依据，看你自己机器上的输出。

顺带说个容易误读的现象：removed 阶段的特性仍然会出现在这个列表里，而且部分 removed 项的生效值是 true。它的含义是”这个开关本身不再需要控制、行为已固化”，不等于功能没了。

第二步，确认配置真的加载成功了。 如果你刚往 config.toml 里加了 [tools] view_image = true，先跑一次：

codex doctor --summary

在 codex-cli 0.147.0（Windows 11）上，我们故意用 codex -c 'features=[unclosed' doctor --summary 传了一段语法不合法的 TOML，结果是：命令没有崩溃退出，doctor 照常跑完，但输出里出现了这一行：

✗ config       config could not be loaded - Fix the reported config error, then rerun codex doctor.

这条一手结论很有价值——配置写坏了 Codex 不会拦你，doctor 才会告诉你没加载成功。所以”我明明改了配置怎么没生效”的第一步永远是跑 doctor 看 config 这一行，而不是反复重启。

顺便别指望 --strict-config 兜底。在 codex-cli 0.147.0（Windows 11）上执行 codex -c model_reasoning_effortt=high --strict-config exec --help，故意把键名拼错，结果正常打印了 help，没有报未知字段错误。说明它的校验发生在真正加载配置去跑会话时，--help 这类不进入会话的路径不触发。

第三步，确认选项值没写错。 沙箱这类枚举值写错会直接被 CLI 拦下。在 codex-cli 0.147.0（Windows 11）上执行 codex -s bogus-mode，输出是：

error: invalid value 'bogus-mode' for '--sandbox <SANDBOX_MODE>'
  [possible values: read-only, workspace-write, danger-full-access]

For more information, try '--help'.

看到这种带 [possible values: ...] 的报错就别猜了，照着括号里抄。

第四步，检查图片路径本身。 这一步没有捷径：ls 一下你写进 -i 的那个路径，确认文件真的在。三个高频错法——Git Bash 里用了反斜杠、路径带空格没加引号、加了 -C 之后以为图片路径也跟着换根。

四、什么情况不适用

图里有敏感信息的时候。 截图是最容易漏东西的载体：浏览器标签栏带着内网域名、终端里躺着一段 token、侧边栏显示着真实用户名和客户项目名。附图之前先裁剪打码，这是人的活儿，工具替不了。这里不做任何安全性承诺——该脱敏就脱敏。

指望它替代设计规范文档的时候。 一张截图里的间距、字号、色值，靠看图还原和靠 design token 还原是两回事。长期生效的规范应该写进项目的自定义指令文件（官方文档索引里另有《Custom instructions with AGENTS.md》一页），而不是每次会话重新贴一张图。

需要动手改文件的时候要额外想一步。 前面给的示例都刻意用了 -s read-only。如果你要的是”看着截图直接改样式”，就得放到 workspace-write，那时候沙箱边界才真正起作用。在 codex-cli 0.147.0（Windows 11）上我们做过一个只读验证：用 codex sandbox 在默认沙箱状态下执行一条往仓库路径写文件的命令，命令返回后目标文件并不存在。这说明边界是实打实存在的，但也提醒你——权限没给够时，“它说改好了”和”文件真的变了”是两件事，改完自己 git status 看一眼。

桌面应用和 IDE 扩展里怎么贴图，本文不涉及。 那两个面我们完全没有实测，官方文档索引里另有《ChatGPT desktop app》《Codex IDE extension》页；索引里还有一页《Image inputs》（本文未取其正文内容），需要更细的口径请直接看官方页（任何文档页 URL 后加 .md 后缀就能拿到 Markdown 版本，很适合直接喂给工具读）。

最后再强调一遍那句最重要的：本文所有”本机实测”都来自 codex-cli 0.147.0（Windows 11）上的只读命令输出。同一台机器上，我们采集时先后两次执行 codex --version 分别得到 0.131.0 和 0.147.0——Codex 具备自更新能力，选项和特性阶段都会随版本变。排查任何跟版本相关的问题，都以当次 codex --version 的实时输出为准。