故障处理
Codex 贴图没反应？先分执行端、剪贴板与附件是否真的送达
Codex 粘贴图片没反应、WSL 贴图进不去，或附件出现了却没有识别？按执行端、剪贴板内容、同机文件路径和图片附加逐步排查，再用已知图片验证实际识别，区分本地输入成功与模型看懂图片。
在 Codex 里粘贴截图，输入框没有变化；拖入后只出现一个路径；或者附件已经显示，回答却像没看到图。这几种情况需要不同的下一步。先确认使用的客户端和执行主机，再确认剪贴板或文件里确实有图片，最后验证本次请求中的图片是否被实际识别。
本文处理 codex paste image not working、WSL 贴图进不去和图片附件没有识别等问题。目标是把结果定位到“尚未附加”“本地附加已确认，送达或识别未确认”“出现明确请求错误”或“本次图片内容已核对”，不靠反复换快捷键判断。
先按眼前的现象分流
| 你看到的现象 | 下一步与判断依据 |
|---|---|
| 粘贴后什么都没有出现 | 按第 1、2 步确认客户端和剪贴板类型，再用文件方式对照 |
| 只出现文件名、路径或一段文字 | 尚不能确认图片已附加；按第 3、4 步使用该执行端支持的图片入口 |
| 有图片预览或附件，但回答说没看到 | 先核对它是否属于刚发送的那条消息，再按第 5 步测试识别 |
| 出现不支持图片、解码失败等明确错误 | 保留原文，按第 6 步区分文件、模型/服务与请求错误 |
| 能说出图中部分信息，但看错对象或看不清 | 按第 5 步核对图片编号、可辨细节和任务范围，不先归因于剪贴板 |
图片输入与图片生成是两件事。 这里验证的是让 Codex 查看已有图片，不是让它生成一张图。不要用生成工具是否可用来判断图片输入是否成功。
1. 确认在哪个输入框、哪台主机上操作
适用条件： 你还不能确定问题出在客户端、终端还是远程环境。
记录当前使用的是桌面 app、IDE 扩展、CLI，还是 Web 页面；CLI 还要记下终端程序、是否进入 WSL、SSH 或 tmux，以及 Codex 实际运行的主机。IDE 中同时打开了编辑器和集成终端时，也要确认图片被拖到了哪个输入区域。
CLI 在启动 Codex 的同一终端里查看版本与本机选项：
codex --version
codex --help预期结果： 能记录实际执行端的版本，并在帮助中找到 -i, --image。桌面 app 和 IDE 扩展分别查看自己的版本；终端里的 CLI 版本不能代替它们的版本。若命令不存在，先确认当前终端是否安装并能找到 CLI，不要把入口未启动当作贴图失败。
同一台电脑也可能有多个文件环境：Windows 文件管理器里的图片，不等于 WSL 中已经有相同路径；本地剪贴板里的截图，也不等于 SSH 服务器已经收到图片文件。tmux 或终端的粘贴行为还涉及中间输入层，单次无反应不足以断定 Codex 不支持图片。
到这一步应能写出“Windows 上的某终端 → WSL 内运行的 CLI”或“本地 IDE 扩展 → 远程项目”等完整关系。关系不清时先核对终端会话和项目位置，不急着更换模型或调整权限。
2. 分清剪贴板里是图片、文件对象还是文字
适用条件： 按粘贴快捷键无反应，或粘贴出来的内容与你预期不同。
用一张不含账号、密钥和私人内容的简单截图做对照。确认截图工具选择的是“复制图片”，还是只把图片保存到了磁盘。复制文件、复制图片地址、复制文件路径，也不一定产生相同的剪贴板内容。
- 在已有的、支持图片粘贴的本地图像编辑器中尝试粘贴这张测试图。若真正出现图像，说明至少该应用能从当前剪贴板取得图像；这还不能证明终端也能读取同一种数据。
- 若只有路径或文字，回到截图工具重新复制图像内容；若只是保存了文件，直接转第 3 步使用文件，不必继续试粘贴。
- 回到 Codex 的实际输入框，再试一次该客户端当前支持的粘贴方式。观察出现的是图像附件、纯文字，还是完全无变化；不要仅以按键已经按下作为成功证据。
预期结果： 能区分“剪贴板没有可用图像”和“图像在其他应用可用，但当前输入链路未接收”。后者先走文件附加作为对照，避免把某个系统或终端里的 Ctrl+V、Cmd+V、Alt+V 经验写成所有客户端通用操作。也不需要为了测试先安装第三方剪贴板插件。
3. CLI：先用同一执行主机上的图片文件绕开剪贴板
适用条件： 使用 Codex CLI，当前粘贴链路不确定；本机帮助中支持 -i/--image。
先把测试图保存或从图像编辑器导出为真正的 PNG 或 JPEG，用普通图像查看器打开，确认内容完整、方向正确。把扩展名改成 .png 不等于完成格式转换。 再确认运行 CLI 的那一侧能够读取这个文件。下面的 WSL、SSH 情形指 CLI 进程就在其中运行；如果只是本地客户端连接远程任务服务，要分别记录输入端和任务端，不凭远程项目目录推断附件读取位置。
- 本地 CLI：使用这台主机上的实际路径，包含空格时保留引号；相对路径要以当前启动目录为准，排障时优先使用已核对的绝对路径。
- WSL 内的 CLI：先在 WSL 中确认文件实际所在位置和可读性。不要把
C:\...原样当成 Linux 路径，也不要未经核对就假设挂载点或盘符转换一定有效。 - SSH 或其他远程执行环境：先通过已有授权的文件传输方式把测试图放到远程主机，再使用远程路径。本地路径文字不会自动把本地文件上传过去。
如果文件位置仍有疑问，先按 文件存在却读不到的路径与读取验证核对；这一步只解决文件可访问性，还没有证明图片进入模型输入。
下列命令启动一个带图的新 CLI 会话。把示例路径替换为刚核对过的实际路径，一次先附一张图；这是正常模型请求，会使用当前账号的额度：
codex -i "/actual/path/probe.png" "只查看附图，不修改文件。描述主要形状、颜色和相对位置；看不清或没有收到图片时明确说明，不根据文件名猜测。"OpenAI 图片输入文档也支持 --image 和多张图片。单图验证通过后，如需对比两张，可使用重复选项并明确顺序：
codex --image "/actual/path/before.png" --image "/actual/path/after.png" "比较第 1 张与第 2 张截图，只列出可见差异，不修改文件。"预期结果： 文件读取不再报错，并能进入带图的请求流程；随后仍要按第 5 步核对实际识别。若文件方式成功、粘贴方式失败，问题已缩小到剪贴板与客户端输入链路，可以先继续使用文件附加。若报路径不存在、不可读或图片无效，先修正该项，不轮流换模型重试。
可选：只检查 CLI 本地构造的输入
适用条件： 想进一步确认图片有没有进入 CLI 构造的输入，而且当前版本的帮助中提供该调试命令。
codex debug prompt-input --help确认帮助里支持 --image 后，仍然用这张不含敏感信息的测试图：
codex debug prompt-input --image "/actual/path/probe.png" "检查这张测试图的输入构造。"官方命令参考说明，它把模型可见的输入列表渲染为 JSON。检查用户输入中是否有对应图片项，而不只是带路径的文字；输出可能包含上下文和图片编码，不要把整份结果贴到公开论坛。
预期结果： 可以确认本地输入构造中的图片项；该命令本身不向模型发出识别请求。它不证明服务端接受了请求，也不证明模型实际看懂图片。命令不存在时跳过此项，使用当前版本的正式附图入口，不为这一项调试强制升级到预览版。
本次核验的 CLI 版本中，不存在的图片路径会在输入文字里产生 Codex could not read the local image，而调试命令仍可能以退出码 0 结束。因此还要检查有没有读取失败文本和真正的图片项，不能只看进程是否正常退出；其他版本以实际输出为准。
4. 桌面 app、IDE 与 Web：核对接收区域和本次消息
适用条件： 使用图形界面；拖入后没变化、图片落进编辑器，或界面有附件但回答没有对应它。
按 官方图片输入说明选择对应入口：桌面 app 和 IDE 扩展把图片拖入提示输入框时按住 Shift；IDE 要特别确认接收区域是 Codex 输入框，避免变成编辑器打开文件。官方文档的 Web 分栏说明的是 ChatGPT Web 输入框，可使用附件、粘贴或拖入；其他 Web 任务页面要按自己的实际入口和提示确认，不直接套用这一能力。CLI 的快捷键经验不能直接套到这些输入框。
先附一张测试图，检查预览或附件是否与该文件对应，再写清需要检查的内容并发送。发送后核对刚才那条消息及其可见附件状态；上一条消息的预览、磁盘上仍存在的文件，或输入框中尚未发送的附件，都不能证明本次请求已经包含它。
预期结果： 至少能确认正确的图片进入了本次输入。若界面只显示本地预览、没有可核对的送达状态，就记录“本地附加已确认，送达与识别待验证”，不要假设界面能展示所有传输细节。出现上传或请求错误时保留原文，转第 6 步。
只在文字里写“看一下 /path/screenshot.png”，与显式附加图片不是同一项证据。桌面端也可以按官方说明让 Codex 检查系统中的图片，但仍要确认实际执行端能访问该文件，并核对本轮是否有成功读取/查看它的工具记录；不要仅凭路径出现在对话里，就认定图片已经作为视觉输入送出。
5. 附件出现之后，验证它实际识别了什么
适用条件： 已确认本次输入有图片，或希望区分“附加成功”与“回答看起来像看过”。
选一张自己知道内容、带有几种清楚形状和颜色的非敏感测试图，文件名不要暗示答案。使用一个没有先前图像描述的新测试会话，仅附这一张图；不要先把图里有什么写进提示词。
只分析本次附图，不修改文件、不生成图片。
请描述主要形状的颜色、数量及相对位置，并指出哪些细节无法确定。
如果当前没有可用图片输入，请明确说明，不根据文件名或文字上下文补全。这是正常请求，会使用额度，先做一次受控对照即可。把回答与图像逐项核对：颜色、数量、左右关系是否吻合；是否把不清楚的内容标为不确定。模型说“我看到了”或恰好猜中一句泛泛描述，都不足以独立证明识别成功。
| 可观察到的证据 | 可以得出的结论 |
|---|---|
| 文件能打开、路径可读 | 图片文件可用；尚未证明已附加 |
| 本次附件可见，或调试输入中有图片项 | 已有本地附加/构造证据；送达与识别仍需核对 |
| 请求返回明确错误 | 按报错阶段排查；不能当作图片已识别 |
| 本轮回答准确对应未在文字中透露的可见细节 | 本次输入已表现出对应的识别能力；不代表所有图片都能准确理解 |
若测试图能识别，原截图却不行，先检查原图是否正确、是否压缩得过小、文字是否能被人直接看清。需要时从原图导出清晰的相关局部，标明这是哪一处，保留理解问题所需的上下文。多图任务则明确“第 1 张/第 2 张”和关注区域，不把不同图片的细节混在一起。
失败后的处理： 测试图也无法对应时，记录客户端、所用入口、可见附件和原始回复，再走第 6 步；不要把模型的自述当作传输日志，也不要通过在提示词里透露答案来让验收“通过”。
6. 有明确报错时，按阶段处理
适用条件： 已取得报错原文，而非只有“好像没反应”。
- 文件不存在或无法读取： 回到第 3 步核对实际主机、启动目录、路径拼写和该文件的读取权限。修正具体路径或授权范围即可，不把开放整个磁盘作为默认修复。
- 图片无效或解码失败： 用本地图像查看器确认文件，重新导出一张真实 PNG/JPEG 后做单图对照；仍失败时记录格式和文件大小。不要把 API 文档中的某个大小上限直接当作所有 Codex 客户端的统一限制。
- 明确提示模型或服务不支持图片： 记录所选模型、连接的服务和完整错误，核对该服务对当前模型与图片输入的官方支持。若使用自定义 provider，先查有效配置与服务能力，不因改了模型名称就认定兼容；配置有疑问见 config.toml 生效范围。
- 登录、连接、限流或超时错误： 图片可能已经在本地附加，但请求尚未成功完成。认证类问题看 登录与 401 排查；上传或模型请求连接失败时，保留客户端报错中的目标与阶段，核对当前连接和服务状态。只有在任务工具下载或读取远程图片时，相关命令连不上网，才转 任务网络排查。429 不等于不支持图片，也不要靠删除凭据或关闭安全校验试运气。
没有明确错误、只有错误的图像回答时，继续按第 5 步检查原图质量、图片顺序和识别表现。不要为了排障反复切换付费模型、添加不明 provider，或上传含隐私的截图到第三方转换网站。
7. 验收与求助：说清停在哪一层
修复后用原来失败的入口再做一次相同测试，确认附件属于本次请求，回答也能对应测试图中未在文字中透露的细节。若只能通过文件附加工作，而剪贴板仍失败，应记录“文件方式可用，粘贴链路未解决”，不称为所有图片输入已经恢复。
求助时提供脱敏后的客户端及版本、操作系统/终端、WSL/SSH 等执行关系、粘贴或附图方式、文件格式与大小、原始错误，以及已经确认的层级。用可公开的测试图复现；不要公开整份调试 JSON、私有截图、访问令牌或完整会话日志。
本文于 2026-10-17 核对 OpenAI 官方图片输入与命令参考，并在隔离目录用本机 CLI 0.163.0-alpha.10.2 验证图片输入构造与路径错误。该验证未调用模型；桌面端、IDE、Web 入口依据官方说明，未宣称实测所有系统的剪贴板或实际图像识别。最终识别仍需按本文的受控图片步骤在你的实际执行端核对。