Code Agent 远程开发时，如何优雅地贴图？

Sat, 18 Apr 2026 00:00:00 +0000

最近你在远程开发中使用 Code Agent（如 Codex、Claude Code、OpenCode）时，或许都会遇到这个尴尬场景：本地剪贴板里明明有一张截图，远程终端里的 Agent 却看不见。然后你得多走好几步，才能让 Agent 看到这张图片。本文提供一个更快捷的解决方案。

背景

现在用 Code Agent 写代码，虽然咱们有 Playwright / Agent Browser 等工具，但还是难免让它看 UI、看报错截图、看网页风格等。如果是在本机环境，这事还算简单：图片在本机，终端也在本机，Agent 能读到文件就行。但我日常又很依赖远程开发，代码、服务、依赖都在远程机器上，终端通过 SSH 连过去。于是问题来了：

图片在 Mac 的剪贴板里；
Code Agent 跑在远程服务器上；
SSH 终端只能传字符，不能天然传一张剪贴板里的图片；
我又不想每次手动保存图片、scp 上传、再复制远程路径。

看起来只是一个很小的工作流问题，但用多了挺烦人。看着 IDE 中一些临时的截图文件，似乎在提示我，这肯定不是优雅的解决方案。

我想要什么效果？

理想状态很简单：

截图或者复制图片到本地剪贴板；
在远程终端里按一个快捷键；
图片自动上传到远程机器；
终端里自动粘贴一个远程文件路径；
我直接对 Agent 说：看这张图，然后继续干活。

简言之：在远程开发中使用 Claude Code / Codex / OpenCode 时，获得接近本地开发的贴图体验。

方案探索

方案一：拖拽了事

一开始我们都很朴素：先把截图保存成文件，然后再想办法把这个文件弄到远程机器上。如果正在用 VSCode/Cursor Remote-SSH，就直接把图片拖到远程项目目录里。这个动作不复杂，也足够直观。

在 macOS 下，如果终端使用 iTerm2，而你又在 iTerm2 开启了 shell integration，它支持按住 Option 把本地文件从 Finder 里拖到终端窗口，再上传到远程服务器。这个方案也能用，只是远程环境通常也要把 shell integration 配起来，才能让这条链路顺一点。

这两种做法的共同点是：都得先把图片保存到本地，然后再从本地去选文件。它会有一个保存截图到文件的过程，还有一个从本地找到这个图片的一步，我觉得这个过程有点繁琐：我们想要直接将剪贴板里的图片一键进入远程 Agent 工作流。

更烦的是，它很容易污染项目目录。比如为了给 Agent 看一张 UI 截图，随手拖进去一个 image.png、screenshot 2026-04-18.png，修完问题之后又忘了删。时间久了，项目里就多了一堆一次性的临时图片。你说它影响程序运行吧，也不一定；但每次 git status 看到它们，心情就不太美丽。

所以这个初始方案只适合低频场景。偶尔传一次没问题，天天这么干你最好确保自己没有洁癖，我很难忍受。虽然我取个名叫拖拽了事，然并不简单。

方案二：VSCode/Cursor + Claudeboard

后来我找到了 Claudeboard 这个插件，它的定位非常明确：在 VSCode Remote-SSH 场景下，把剪贴板图片上传到远程服务器，并生成 Claude Code 能访问的文件路径。

它的使用方式很直接：剪贴板里有图片后，在 VSCode/Cursor 中按 Ctrl + Alt + V，插件就会上传图片并插入路径。对于 Claude Code 这种跑在远程机器上的 Agent 来说，这就把“本地剪贴板图片”变成了“远程可读文件路径”。

这个方案其实相当不错，基本达到了我们理想状态，并且不需要额外配置。不过要注意，在 Cursor 中插件市场不能直接搜索到，但你可以从上面 GitHub 官方的 Release 页面下载 VSIX 插件再安装，亲测可用。

如果你的主力开发环境就是 VSCode 或 Cursor，选它没毛病。并且如果你是在 Windows 上开发，那就只推荐这个方案。因为我下一套解决方案更 hack 一些，也仅在 macOS 下验证过。

方案三：Mac 自定义解决方案

上一个方案是借助插件，主要在 VSCode / Cursor 里工作。而如果你像我一样，有时顺手开了个终端就准备干活，这个时候 Claudeboard 就帮不上忙了。为了贴一张图切回 VSCode，感觉有点为了吃口醋包顿饺子。

所以继续寻觅方案，然后找到这个脚本： iterm_smart_paste.sh，它可以实现一个快捷键，一键将剪贴板里的图片上传到远程机器，并粘贴一个远程文件路径。

这个方案的核心流程是：

用 pngpaste 从 macOS 剪贴板里取出图片；
保存成本地临时文件；
通过当前 SSH 会话的信息，把图片传到远程机器；
在终端里粘贴远程图片路径；
Code Agent 读取这个路径下的图片。

这听起来有点绕，但所幸事情都它包了，配置好之后，体感就是：复制图片，按快捷键，路径出来了。还是简单介绍一下安装过程：

安装依赖

首先安装 pngpaste：

1

brew install pngpaste

它的作用很单纯，就是从 macOS 剪贴板里把图片导出来。没有它的话，我们还得自己手动把截图存成文件，体验立刻回到解放前。

准备脚本

我把脚本放在了 ~/bin/iterm_smart_paste.sh：

1

vim ~/bin/iterm_smart_paste.sh

脚本参考这里。不过原版SSH 会话识别、上传稳定性这几块兼容性不太好，我顺手更新了个版本，可以从这里取到。

保存后给它执行权限：

1

chmod +x ~/bin/iterm_smart_paste.sh

绑定快捷键

接下来就是把这个脚本绑定到 iTerm2 的快捷键上。只要这几步：

打开 Settings/Preferences > Profiles > Keys；
新增一个快捷键；
Shortcut 选择你习惯的组合，比如 Cmd + Shift + V；
Action 选择 Run Coprocess；
参数填脚本路径：

1

/Users/你的用户名/bin/iterm_smart_paste.sh

如果你本来就在用 Alfred、Raycast 这类工具，也可以让它们来触发脚本。macOS 层面的热键工具会更灵活一些，但这里咱聊 iTerm2 的方案，就不给你引入其它工具了，内置的 Run Coprocess 也已够用。

使用效果

简单录屏了一下，可以看一眼效果，我还是满意的。

这个方案的话，如果长期使用，记得清理一下远程机器上的临时文件。这不用我提醒你吧：）

总结

跨平台多端使用并且习惯 VSCode/Cursor 的开发者，可以考虑方案二，借助插件就可实现。

如果是纯 macOS 用户，习惯 iTerm2 等终端开发，方案三也可以试试。

后记

作为一个有点追求完美的人，我不能接受原始的截图搬运工身份。你要说搞这些能有多少效率提升嘛，那倒未必。但是这种小阻碍解决之后，每次按上快捷键，你了解背后发生了些什么，并且是你让美好在发生，感觉内心安定。或许这也是程序员所追求的一种掌控感？

欢迎大家一起交流一下，你们在远程使用 Codex、Claude Code、OpenCode 时，是怎么处理图片输入的？

最近不打算写太系统性的东西，补几篇文章把工具用得更顺起来。欢迎点赞和关注。

我是个爱折腾技术的工程师，也乐于分享。欢迎点赞、关注、分享，更欢迎一起探讨技术问题，共同学习，共同进步。为了获得更及时的文章推送，欢迎关注我的公众号：爱折腾的风

Iterm2 on 飘逝的风