参考文章：WSL2 Codex图片粘贴问题（无法粘贴Codex粘贴图片）WSLg、Wayland剪贴板、X11剪贴板、xclip、ImageMagick、wl-paste、wl-clipboard、XFixes
文章目录
- VS Code 终端中的 Codex CLI 按 Ctrl+V 无法粘贴图片：不是剪贴板坏了，而是快捷键被拦截
- 摘要
- 一、问题现象
- 二、先确认图片数据链路是否正常
- 1. 检查 Wayland 剪贴板
- 2. 检查 X11 剪贴板
- 3. 检查后台服务
- 三、真正原因：VS Code 把 Ctrl+V 截走了
- 四、解决方法：使用 sendSequence 发送原始 Ctrl+V
- 第一步：打开键盘快捷键 JSON
- 第二步：确认打开的是 keybindings.json
- 第三步：覆盖终端中的 Ctrl+V 行为
- 五、验证修复结果
- 六、一个重要取舍：普通文本怎么粘贴？
- 七、为什么不直接启用 sendKeybindingsToShell？
- 八、快速故障定位表
- 九、备用方案：直接使用图片文件
- 十、总结
- 第一层：图片数据链路
- 第二层：键盘事件链路
- 参考资料
VS Code 终端中的 Codex CLI 按 Ctrl+V 无法粘贴图片：不是剪贴板坏了，而是快捷键被拦截
实测环境：Windows 11 + WSL2/WSLg + Ubuntu 26.04 + VS Code Remote WSL + Codex CLI 0.149.0
问题表现：独立终端中的 Codex 已经可以粘贴图片，但 VS Code 集成终端中按Ctrl+V没有任何反应
最终原因：Windows 版 VS Code 把Ctrl+V当成“向终端粘贴内容”，没有把原始Ctrl+V控制字符交给 Codex
摘要
此前，我已经解决了 Windows 与 WSLg（WSL Ubuntu） 之间的图片剪贴板格式问题：后台桥接服务会把 Wayland 中的image/bmp转换为 X11CLIPBOARD中的image/png。在独立的 Git Bash 终端里运行 Codex CLI 后，按Ctrl+V已经能够附加图片。
奇怪的是，把同样的 Codex CLI 放到 VS Code 的 WSL 集成终端里运行，Ctrl+V又失效了：既没有出现[Image #1]，也没有任何报错，输入框看起来完全没有变化。
最终确认，这不是桥接服务失效，也不是虚拟环境、WSL 配置或 Codex 图片能力的问题，而是另一个独立层次的问题：
Windows 图片剪贴板 │ ▼ WSLg Wayland image/bmp │ 后台桥接服务 ▼ X11 CLIPBOARD image/png ← 图片数据已经准备好 │ ▼ Codex CLI 等待原始 Ctrl+V 按键 ← VS Code 在这里截走了按键解决办法是在 VS Code 的keybindings.json中，通过workbench.action.terminal.sendSequence把Ctrl+V对应的控制字符\u0016直接发送给终端前台程序。
一、问题现象
Codex CLI 的交互式输入框支持直接粘贴图片。OpenAI 官方文档也说明，可以把图片粘贴到交互式 composer，或者使用codex --image将图片文件附加到首条提示中。
在独立终端中，复制 Windows 截图后按Ctrl+V，Codex 可以显示：
[Image #1]但在 VS Code 的 WSL 集成终端中执行相同步骤，结果却是：
- 输入框没有出现图片附件；
- 没有
Failed to paste image错误； - 没有任何可见字符；
- 连续按
Ctrl+V依旧像什么都没有发生。
“完全没有反应”其实是一个非常关键的线索。
如果 Codex 收到了Ctrl+V，只是读取不到图片，它通常会明确提示：
Failed to paste image: no image on clipboard现在连这个错误都没有，说明失败很可能发生在 Codex 之前：按键根本没有到达 Codex。
二、先确认图片数据链路是否正常
不要一看到Ctrl+V无效，就立刻修改剪贴板服务。应该先把“图片数据”和“键盘事件”分开验证。
1. 检查 Wayland 剪贴板
wl-paste --list-types在排查过程中，这条命令有时只显示：
text/html text/plain;charset=utf-8 STRING也可能完全没有输出。这只能说明当时 Wayland clipboard 的 owner 和格式状态，不能单独证明最终供 Codex 使用的 X11 剪贴板没有图片。
我们的桥接器最终发布到的是 X11CLIPBOARD，因此还必须检查 X11。
2. 检查 X11 剪贴板
xclip-selectionclipboard-tTARGETS-o实测输出包含：
TARGETS image/png这说明 Codex 所需的 PNG 已经存在于 X11 剪贴板中。
3. 检查后台服务
systemctl--userstatus codex-clipboard-bridge.service journalctl--user-ucodex-clipboard-bridge.service-n30--no-pager实测服务状态为：
ActiveState=active SubState=running日志中还能看到刚复制的截图已经转换成功：
codex-clipboard-bridge: bridged 2520x1620 image (...) to X11 as PNG至此，图片链路已经形成完整证据闭环：
桥接服务正在运行 + 日志记录转换成功 + X11 TARGETS 包含 image/png = 图片数据已经准备好因此，VS Code 中的问题不是“没有图片”，而是“没有触发 Codex 读取图片”。
三、真正原因：VS Code 把 Ctrl+V 截走了
在 Windows 版 VS Code 的集成终端里，Ctrl+V默认是一个 VS Code 终端快捷键，其含义是：
Paste into active terminal也就是说，VS Code 会读取系统剪贴板，并尝试把其中的文本作为粘贴内容写入终端。这个过程与“把原始Ctrl+V按键发送给终端前台程序”并不是同一件事。
当剪贴板里是一张图片而不是文本时，VS Code 没有可写入终端的文本，于是表面上什么也不会发生；与此同时，Codex 也没有收到它监听的Ctrl+V控制字符。
这解释了为什么：
- Git Bash 独立窗口中可以成功；
- VS Code 集成终端中没有反应；
- 同一个 WSL、同一个 Codex、同一个剪贴板服务，表现却不同。
差异并不在 WSL，而在终端宿主如何处理快捷键。
四、解决方法：使用 sendSequence 发送原始 Ctrl+V
第一步：打开键盘快捷键 JSON
在 VS Code 中按：
Ctrl+Shift+P搜索：
Preferences: Open Keyboard Shortcuts (JSON)选择用户快捷键配置，而不是Open Default Keyboard Shortcuts (JSON)。
第二步：确认打开的是 keybindings.json
新文件通常只有一个空数组：
[]Windows 上对应的用户配置路径通常是：
C:\Users\<用户名>\AppData\Roaming\Code\User\keybindings.json注意，这里修改的是keybindings.json，不是项目里的.vscode/settings.json，也不是 WSL 里的 shell 配置文件。
第三步：覆盖终端中的 Ctrl+V 行为
写入：
[{"key":"ctrl+v","command":"workbench.action.terminal.sendSequence","args":{"text":"\u0016"},"when":"terminalFocus"}]配置项的含义如下：
| 配置 | 作用 |
|---|---|
"key": "ctrl+v" | 捕获 VS Code 中的Ctrl+V |
workbench.action.terminal.sendSequence | 向活动终端发送指定字符序列 |
"text": "\u0016" | 发送 ASCII 十进制 22，也就是控制字符Ctrl+V |
"when": "terminalFocus" | 只在集成终端拥有焦点时生效，不影响代码编辑器 |
保存文件后，快捷键通常会立即生效，不需要重启 WSL，也不需要重新安装 Codex 或剪贴板服务。
五、验证修复结果
按照下面的顺序测试：
在 Windows 中复制或截取一张图片；
确认桥接器已生成 X11 PNG：
xclip-selectionclipboard-tTARGETS-o确认输出包含
image/png；在 VS Code 集成终端中启动 Codex：
codex聚焦 Codex 输入框，按
Ctrl+V。
修复成功后，输入框会显示：
[Image #1]这时可以继续输入对图片的说明，再按 Enter 一起发送。
六、一个重要取舍：普通文本怎么粘贴？
上面的配置把集成终端中的Ctrl+V交给了终端前台程序。这非常适合 Codex，但也意味着 VS Code 原来的“粘贴文本到终端”快捷键被覆盖。
此时普通文本可以通过以下方式粘贴：
- 在终端中单击鼠标右键；
- 使用终端菜单中的 Paste；
- 或者给 Codex 图片粘贴设置一个单独的快捷键。
如果希望保留原来的Ctrl+V文本粘贴，推荐改用Ctrl+Alt+V触发 Codex 图片读取：
[{"key":"ctrl+alt+v","command":"workbench.action.terminal.sendSequence","args":{"text":"\u0016"},"when":"terminalFocus"}]这样：
Ctrl+V → 普通终端文本粘贴 Ctrl+Alt+V → 把原始 Ctrl+V 发送给 Codex，读取图片对于经常同时粘贴命令和截图的用户，这个方案更不容易混淆。
七、为什么不直接启用 sendKeybindingsToShell？
VS Code 还提供：
"terminal.integrated.sendKeybindingsToShell":true但它会把大量快捷键都交给 shell，可能连Ctrl+F等 VS Code 终端快捷键也一起改变。为了解决一个明确的Ctrl+V冲突，没有必要扩大影响范围。
sendSequence只处理我们指定的按键，作用范围更小，也更容易理解和撤销。
八、快速故障定位表
| 现象 | 更可能的问题 | 检查方向 |
|---|---|---|
Codex 显示no image on clipboard | 按键已送达，但图片格式或剪贴板 owner 不正确 | 检查 Wayland/X11 图片类型 |
VS Code 中按Ctrl+V完全无反应 | VS Code 拦截了快捷键 | 配置terminal.sendSequence |
| 独立终端成功，VS Code 失败 | 终端宿主按键处理不同 | 检查 VS Codekeybindings.json |
xclip ... TARGETS没有image/png | 图片桥接尚未成功 | 检查服务状态和日志 |
xclip ... TARGETS已有image/png，Codex 仍无反应 | 图片已就绪，但 Codex 没收到按键 | 发送\u0016 |
这里最重要的排查原则是：
不要把“剪贴板里有没有图片”和“Ctrl+V 有没有送到 Codex”混成一个问题。它们属于两条不同链路，必须分别验证。
九、备用方案：直接使用图片文件
如果暂时不想修改快捷键，也可以绕过剪贴板，通过文件路径启动 Codex：
codex--image/path/to/screenshot.png"请分析这张截图"这能验证 Codex 本身是否具备图片输入能力，但它不能代替交互式会话中随手按Ctrl+V的体验。
十、总结
这次问题之所以容易误判，是因为它发生在连续的两层兼容链路上：
第一层：图片数据链路
Windows screenshot → WSLg Wayland image/bmp → clipboard bridge → X11 image/png这一层由 Codex WSL Clipboard Bridge 解决。
第二层：键盘事件链路
Ctrl+V → VS Code 默认执行 terminal paste → Codex 收不到 Ctrl+V这一层通过下面的配置解决：
{"key":"ctrl+v","command":"workbench.action.terminal.sendSequence","args":{"text":"\u0016"},"when":"terminalFocus"}最终，桥接服务负责把图片准备成 Codex 能读取的格式，VS Code 快捷键则负责真正触发 Codex 去读取它。两者缺一不可。
参考资料
- OpenAI Codex CLI 官方文档
- OpenAI Codex 命令参考：
--image - VS Code 官方文档：终端复制与粘贴
- VS Code 官方文档：Custom sequence keyboard shortcuts
- Codex WSL Clipboard Bridge 项目主页
