参考文章：WSL2 Codex图片粘贴问题（无法粘贴Codex粘贴图片）WSLg、Wayland剪贴板、X11剪贴板、xclip、ImageMagick、wl-paste、wl-clipboard、XFixes

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 转换为 X11 CLIPBOARD 中的 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 剪贴板没有图片。

我们的桥接器最终发布到的是 X11 CLIPBOARD，因此还必须检查 X11。

2. 检查 X11 剪贴板

xclip -selection clipboard -t TARGETS -o

实测输出包含：

TARGETS
image/png

这说明 Codex 所需的 PNG 已经存在于 X11 剪贴板中。

3. 检查后台服务

systemctl --user status codex-clipboard-bridge.service
journalctl --user -u codex-clipboard-bridge.service -n 30 --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 或剪贴板服务。

---

五、验证修复结果

按照下面的顺序测试：

1. 在 Windows 中复制或截取一张图片；

2. 确认桥接器已生成 X11 PNG：

   xclip -selection clipboard -t TARGETS -o
   

3. 确认输出包含 image/png；

4. 在 VS Code 集成终端中启动 Codex：

   codex
   

5. 聚焦 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 Code keybindings.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 项目主页