本页目录
项目介绍
**它是什么。**Computer Use 是让智能体像人一样操作电脑界面:先截屏或读取窗口的控件树(控件树:窗口里按钮、输入框等元素的文字清单),看清按钮在哪,再移动鼠标、点击、输入,做完再截屏核对。它解决的是“这个软件没有接口、没有命令行,只能用鼠标点”的任务。本文介绍三个开源方案,另附 WorkBuddy 自带的实验性工具:
| 方案 | 开发与维护 | 开源与许可证 | 首次发布 | 最新版本 | GitHub 星数(2026-10 核查) |
|---|---|---|---|---|---|
| Peekaboo(macOS) | Peter Steinberger(GitHub steipete)发起,现归 openclaw 组织 | 开源,MIT | 首个 GitHub Release v1.0.0-beta.20,2025-06-08 | v4.9.5,2026-10-17 | 约 5,300 星,持续更新 |
| Windows-MCP(Windows) | CursorTouch(GitHub 组织,主要贡献者 Jeomon) | 开源,MIT | v0.1,2025-06-04 | v0.8.8,2026-10-10 | 约 9,500 星,持续更新 |
| Cua Driver(跨平台) | Cua(GitHub 组织 trycua,做计算机操作智能体的开源基础设施) | 开源,MIT | cua 仓库建于 2025-01-31 | cua-driver-rs v0.36.0,2026-10-16(标为预发布) | 整个 cua 仓库约 30,000 星,持续更新 |
| WorkBuddy 自带 computer-use(仅 macOS) | 腾讯 | 不开源,商业客户端 | 4.22.4 版加入 | 随客户端,当前 5.8.3 | 不适用 |
**接入方式:**三个开源方案都属于 MCP(一个本地程序,智能体客户端启动它并调用它提供的工具);WorkBuddy 的是客户端自带。Claude Code 自带的 Computer Use 与 Claude-in-Chrome 是 Anthropic 账号专属功能,要连境外服务,按本课的国内网络路线不推荐,本文也不写开启方法。
核心能力:
- 截屏、列出窗口、读取窗口里的按钮和输入框(控件树);
- 点击、输入文字、按快捷键、滚动、拖拽;
- 打开、切换、调整窗口;
- 操作没有接口的桌面软件。
三个方案的分工:Peekaboo 只支持 macOS 15 及以上;Windows-MCP 只支持 Windows 10/11,是 Windows 用户的首选;Cua Driver 跨 Windows、macOS、Linux。
**在同类工具里的位置:**在“让智能体操作网页和软件”的各类工具里,Computer Use 排在最后:有接口用接口,有命令行用命令行,网页用浏览器工具(Playwright MCP、Playwright CLI、agent-browser),都不行才轮到屏幕操作。
**国内网络:**安装源都能连上:清华 PyPI 源有 windows-mcp,阿里云 PyPI、npmmirror 也能用;GitHub release 能下载,但慢、时好时坏,只作备选。
使用前先记住三点:
- 能用接口、命令行、浏览器工具做的事,不要用 Computer Use。它最慢、最贵、最容易点错。Claude Code 官方文档的说法也是:有 MCP 先用 MCP,能用命令行就用命令行,浏览器任务用浏览器工具,都不行才轮到屏幕操作。
- 模型要能“看图”。截图要送进模型,纯文本模型看不到截图,只能靠控件树操作,能做的事少很多。
- 只在测试数据、单个窗口、独立虚拟机或测试账户里用。系统授权弹窗、登录、支付由人来点。
1. 官方链接与版本
核查日期:2026-10(GitHub、PyPI、Homebrew、npmmirror、官方文档站)。
| 方案 | 平台 | 官方仓库 / 文档 | 最新版本与日期 | 许可 |
|---|---|---|---|---|
| Peekaboo | macOS 15 及以上 | 仓库;MCP 说明;权限说明;发布页 | v4.9.5,2026-10-17(Homebrew tap 与 npmmirror 上的 @steipete/peekaboo 同为 4.9.5) | MIT |
| Windows-MCP | Windows 10 / 11 | 仓库;PyPI;安全策略 | v0.8.8,2026-10-10 | MIT |
| Cua Driver | Windows 10/11、macOS、Linux | 仓库;接入智能体;权限模式 | cua-driver-rs v0.36.0,2026-10-16(GitHub 标为预发布,官方安装脚本取最新发布) | MIT(Cua Spaces 应用另为 FSL-1.1-MIT) |
| WorkBuddy 自带 computer-use | 仅 macOS(实验性) | 更新日志;连接器说明 | 4.22.4 起;当前 5.8.3(2026-10-19) | 商业服务 |
两处版本变化要注意:
- Windows-MCP 对 Python 的要求变了。 PyPI 上 0.8.6 起(2026-09-26)要求 Python ≥ 3.14,0.8.8 也是 ≥ 3.14;但 v0.8.8 标签下的 README 仍写“Python 3.13+”,主分支 README 已改为 3.14+。按 PyPI 元数据为准:装 Python 3.14,或让 uv 自动下载 3.14。只装 3.13 时,
uvx windows-mcp会退回旧版或报错。 - Windows-MCP 的中文系统提示也在变。 v0.8.8 README 写:Windows 显示语言最好是英文,否则禁用 App 工具;主分支(尚未发版)改为“App 工具能识别本地化的开始菜单名称,不要求英文系统”。在中文 Windows 上,如果 App 工具报错,就把它禁用,先手动打开要操作的软件。
2. 能做什么、不能做什么、适合本课哪类任务
能做:
- 截屏、列出窗口、读取窗口里的按钮和输入框(控件树);
- 点击、输入文字、按快捷键、滚动、拖拽;
- 打开、切换、调整窗口大小;
- 操作没有接口的桌面软件,例如计算器、某些行情软件的只读界面、单位内网的老系统(只读查看)。
不能做或做不好:
- 速度慢:每一步都要截图、送模型、等回复,十几步的任务要几分钟。
- 会点错:窗口位置变了、弹窗挡住、分辨率缩放不一致,都会让坐标失效。
- 截图会进入模型:屏幕上的聊天记录、通知、文件名都可能被一起送出去。
- 游戏、视频、画布类界面没有控件树,只能靠截图,成功率更低(Windows-MCP 与 Cua 文档都写明了这一限制)。
- 不能替你点系统授权、杀毒软件拦截、管理员权限(UAC)弹窗。Windows 上普通权限的智能体操作不了以管理员身份运行的程序。
适合本课的任务: 演示“观察→动作→复核”的循环,理解智能体怎样把“看”和“做”接起来;用计算器、记事本、测试表格这类无风险软件做小练习。不适合拿来做批量数据采集(用接口或浏览器工具)、操作网银和证券账户、登录个人社交账号。
3. 三种做法怎么选
| 你的电脑 | Claude Code(CC Switch 接国内模型) | WorkBuddy |
|---|---|---|
| Windows 11 | Windows-MCP(首选)或 Cua Driver,经 MCP 接入 | 自定义连接器接 Windows-MCP 或 Cua Driver;WorkBuddy 自带的 computer-use 在 Windows 上不可用 |
| macOS | Peekaboo(首选)或 Cua Driver,经 MCP 接入 | 自带的实验性 computer-use,或自定义连接器接 Peekaboo |
三者都能截图、读控件、点击输入。区别:
- Peekaboo:只有 macOS;可从 npmmirror 用 npm 装(安装包自带程序);需要“屏幕录制”和“辅助功能”两项系统权限。
- Windows-MCP:只有 Windows;靠 Python 与 uv 运行;工具多,带 PowerShell、注册表、文件系统、进程管理等系统级能力,默认全部开启;默认开启匿名遥测。
- Cua Driver:Windows、macOS、Linux 都有;可设权限模式;对不能看图的模型有
--text-only过滤方案(见第 4.3 节);安装包只从 GitHub Releases 下载,没有国内镜像。GitHub 在国内能连上但慢、不稳定,只作备选。
4. 两个客户端的现状
4.1 Claude Code
Claude Code 自带的 Computer Use 与 Claude-in-Chrome 是 Anthropic 账号专属功能,要连境外服务,本课不推荐,也不写绕过或开启方法。经 CC Switch 接国内模型的 Claude Code,接第三方 MCP(Windows-MCP、Peekaboo、Cua Driver)来做 Computer Use。
4.2 WorkBuddy:有实验性自带工具,但只在 macOS
- 官方更新日志 4.22.4 版写有“新增实验性 computer-use 工具(仅 macOS)”;5.6.0 版写有“优化电脑操作、浏览器操作、Bash 命令等工具在对话中的展示形态”。
- WorkBuddy 自带的屏幕操作可能调用一个单独的视觉模型,截图可能被发往腾讯的服务端处理;使用前会弹出“等待操作屏幕授权”一类的确认,可选“本次”或“本次启动内始终”。
- 官方文档里没有这项功能的开启步骤和平台说明。社区文章也说 WorkBuddy“目前没有推出”Computer Use、需要自己准备环境(知乎,社区)。
- Windows 用户的做法: WorkBuddy 的“自定义连接器”支持安装自定义 MCP 服务,配置方式与 MCP 配置相同(官方连接器文档),可以把 Windows-MCP 或 Cua Driver 接进去。如果接上后模型说看不到截图,换能看图的模型(见 4.3)。
4.3 模型要能收图片
截图作为工具结果回到模型。模型不收图片时,有两种结果:请求直接报错,或模型看不到截图、只能凭控件树猜。
| 模型 | 能否收图(按官方文档) | 备注 |
|---|---|---|
| DeepSeek(CC Switch 路线) | deepseek-flash 支持图片输入,OpenAI 兼容端点和 Anthropic 兼容端点(https://api.deepseek.com/anthropic)都能传 image 块;旧名 deepseek-v4-flash-vision-exp 已由 Flash 承接(图像理解) | 图片只能放在 user 消息里;每张图最多按 384 token 计费,细节会被缩到约 800×800 等效分辨率。如果 Claude Code 把截图回传后 DeepSeek 报错或说看不到图,改用控件树方式(Cua 的 --text-only);其他 DeepSeek 型号以官方文档为准 |
| WorkBuddy 内置模型 | 选能看图的多模态模型 | 社区文章建议切到 Kimi、MiniMax 等原生多模态模型。具体哪些内置模型收图,以 WorkBuddy 模型选择器的标注为准 |
| 纯文本模型 | 不能 | 只能走控件树。Cua 官方给了 cua-mcp-filter --text-only 方案:不请求截图、把残留图片换成文字说明,模型靠控件编号操作;画布、视频等没有控件的界面仍需视觉模型 |
另外,截图会消耗 token 和积分。高分辨率屏幕可把截图缩小:Windows-MCP 用环境变量 WINDOWS_MCP_SCREENSHOT_SCALE=0.5。
5. 安装与配置
5.0 前置依赖
| 方案 | 依赖 |
|---|---|
| Windows-MCP | Windows 10/11;Python 3.14(或由 uv 自动下载);uv(Astral 出品的 Python 包管理器);国内镜像配置见 5.0.1 |
| Peekaboo | macOS 15 及以上;Node.js 22 及以上(走 npmmirror 安装时);系统设置里给运行它的程序开“屏幕录制”“辅助功能” |
| Cua Driver | Windows 10/11 或 macOS 14 及以上;Windows 上要在已登录的交互桌面里运行;能访问 GitHub Releases(无国内镜像;GitHub 国内访问不稳定,只作备选) |
| 两端共同 | 一个能看图的模型;一个专门的测试文件夹,例如 D:\cu_test(Windows)或 ~/cu_test(Mac) |
5.0.1 国内镜像配置
下面这些国内镜像在国内网络下都能连上,npmmirror 下载速度快。
| 下载什么 | 默认来源 | 国内镜像配置 |
|---|---|---|
| Python 安装包(电脑上一个 Python 都没有时) | python.org | npmmirror https://registry.npmmirror.com/-/binary/python/ 或华为云 https://repo.huaweicloud.com/python/ ,进对应版本目录下载 Windows x64 安装包 |
| uv 本身 | astral.sh 安装脚本,再从 GitHub 下载 uv 程序 | 已有任意 Python 时:pip install uv -i https://pypi.tuna.tsinghua.edu.cn/simple。官方脚本能下载,但它再从 GitHub 拉 uv 程序,国内访问不稳定,只作备选 |
| Python 包(windows-mcp 及依赖) | pypi.org | 环境变量 UV_DEFAULT_INDEX=https://pypi.tuna.tsinghua.edu.cn/simple(备选阿里:https://mirrors.aliyun.com/pypi/simple/) |
| uv 管理的 Python 3.14 | GitHub(python-build-standalone) | 环境变量 UV_PYTHON_INSTALL_MIRROR=https://registry.npmmirror.com/-/binary/python-build-standalone(变量名出自 uv 官方文档;如果 uv 仍从 GitHub 下载、很慢,检查这个变量有没有写进 MCP 配置的 env) |
| pip | pypi.org | pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple |
| npm(Peekaboo) | registry.npmjs.org | npm config set registry https://registry.npmmirror.com,或单次加 --registry=https://registry.npmmirror.com |
| Cua Driver | GitHub Releases(国内访问不稳定) | 没有国内镜像,只作备选 |
Windows 上写成用户环境变量(PowerShell,执行后重开终端和客户端):
setx UV_DEFAULT_INDEX "https://pypi.tuna.tsinghua.edu.cn/simple"
setx UV_PYTHON_INSTALL_MIRROR "https://registry.npmmirror.com/-/binary/python-build-standalone"
客户端启动 MCP 时未必读到你刚设的环境变量,所以下文的注册命令和连接器 JSON 里也把这两项写进 env。
5.1 首选:交给智能体装
Claude Code 端(Windows,装 Windows-MCP)
在 D:\cu_test 里打开终端,运行 claude,粘贴下面这段:
请帮我在这台 Windows 11 电脑上为 Claude Code 安装并注册 Windows-MCP(官方仓库 https://github.com/CursorTouch/Windows-MCP ,PyPI 包名 windows-mcp),要求如下:
1. 先只读检查:python --version、uv --version、where uvx。把结果告诉我。
2. 按国内网络配置下载源:用 setx 设用户环境变量 UV_DEFAULT_INDEX=https://pypi.tuna.tsinghua.edu.cn/simple 和 UV_PYTHON_INSTALL_MIRROR=https://registry.npmmirror.com/-/binary/python-build-standalone 。执行前把命令给我看。
3. 如果没有 uv:电脑上已有 Python 时用 pip install uv -i https://pypi.tuna.tsinghua.edu.cn/simple 安装;没有 Python 时停下来问我。
4. windows-mcp 当前版本要求 Python 3.14。不要改系统 Python,也不要卸载已有 Python;让 uv 自己管理 3.14(uv python install 3.14)。只用上面两个镜像,不要换其他来源。
5. 用本项目作用域注册(只在当前文件夹生效),用 uvx.exe 的绝对路径(where uvx 查到的那个),并且:
- 禁用 PowerShell、Registry、FileSystem、Process 四个工具;
- 关闭匿名遥测(ANONYMIZED_TELEMETRY=false),并把两个镜像变量也写进 -e;
参考写法:claude mcp add --transport stdio --scope local -e ANONYMIZED_TELEMETRY=false -e UV_DEFAULT_INDEX=https://pypi.tuna.tsinghua.edu.cn/simple -e UV_PYTHON_INSTALL_MIRROR=https://registry.npmmirror.com/-/binary/python-build-standalone windows-mcp -- <uvx.exe 绝对路径> windows-mcp serve --exclude-tools "PowerShell,Registry,FileSystem,Process"
6. 不要用 -s user 全局注册,不要改其他 MCP 配置,不要开 sse 或 http 网络模式。
7. 装完运行 claude mcp list,告诉我 windows-mcp 是否显示 Connected,并告诉我我需要重启 Claude Code 后在 /mcp 里确认。
8. 不要执行任何截图、点击、输入操作。遇到要输密码、要管理员权限、杀毒软件拦截、要联网下载大文件时,停下来问我。
它会请求的权限与怎么回应:
| 它要做的事 | 怎么回应 |
|---|---|
运行 python --version、uv --version、where uvx | 只读,可以允许 |
运行 setx UV_DEFAULT_INDEX ...、setx UV_PYTHON_INSTALL_MIRROR ... | 写用户环境变量,看清地址是 pypi.tuna.tsinghua.edu.cn、registry.npmmirror.com 再允许 |
运行 pip install uv -i ... | 看清是清华镜像再允许 |
运行 uv python install 3.14、首次运行 uvx windows-mcp | 要联网下载 Python 和依赖,允许;下载地址不是上面两个镜像时先问清楚 |
运行 irm https://astral.sh/uv/install.ps1 | iex | 本文不用这条(脚本从 GitHub 下载 uv,国内访问不稳定);它提出时拒绝,改走 pip 镜像 |
运行 claude mcp add ... | 会写入 Claude Code 的配置,看清是 --scope local、带 --exclude-tools 再允许 |
| 要求以管理员身份运行、改系统环境变量、改注册表、关杀毒软件 | 拒绝,改为自己判断后手动处理 |
Claude Code 端(macOS,装 Peekaboo)
请帮我在这台 Mac 上为 Claude Code 安装并注册 Peekaboo(官方仓库 https://github.com/openclaw/Peekaboo ),要求如下:
1. 先只读检查:sw_vers、node --version、npm config get registry、which peekaboo、peekaboo --version。
2. 用国内镜像通过 npm 全局安装:npm install -g @steipete/peekaboo --registry=https://registry.npmmirror.com (Node.js 低于 22 时停下来问我)。不要用 npx 临时运行,不要用 Homebrew tap(它从 GitHub 下载),不要从源码编译,不要下载 DMG。
3. 用本项目作用域注册,命令用 which peekaboo 查到的绝对路径:
claude mcp add --transport stdio --scope local peekaboo -- <peekaboo 绝对路径> mcp
4. 运行 peekaboo permissions status,把“屏幕录制”“辅助功能”的状态告诉我。缺哪一项,告诉我去系统设置哪里开,由我自己点,你不要尝试代点或绕过。
5. 不要运行 peekaboo config 配置任何模型或 API Key;不要执行截图、点击、输入。
6. 装完运行 claude mcp list,告诉我 peekaboo 是否 Connected。
WorkBuddy 端(Windows,接 Windows-MCP)
WorkBuddy 能按对话安装连接器市场里的连接器,但“自定义连接器”是在页面里粘贴配置。建议让 WorkBuddy 做准备工作,粘贴由你来:
我想在 WorkBuddy 的“自定义连接器”里接入 Windows-MCP(https://github.com/CursorTouch/Windows-MCP )。请你:
1. 只读检查这台电脑有没有 uv 和 uvx:运行 where uvx、uv --version,告诉我 uvx.exe 的完整路径。
2. 没有 uv 时,用 pip install uv -i https://pypi.tuna.tsinghua.edu.cn/simple 安装,先把命令给我看,等我同意再装;没有 Python 就停下来问我。
3. 生成一段自定义连接器用的 JSON:command 用 uvx.exe 的绝对路径;args 为 windows-mcp、serve、--exclude-tools、PowerShell,Registry,FileSystem,Process;env 里加 ANONYMIZED_TELEMETRY=false、UV_DEFAULT_INDEX=https://pypi.tuna.tsinghua.edu.cn/simple、UV_PYTHON_INSTALL_MIRROR=https://registry.npmmirror.com/-/binary/python-build-standalone。
4. 只把 JSON 给我,由我粘贴;不要改 WorkBuddy 的配置文件,不要执行截图或点击。
WorkBuddy 端(macOS)
先看左下头像 → 设置里有没有“电脑操控”“操作屏幕”一类开关。有就用自带的;找不到就按上面的思路接 Peekaboo,command 填 which peekaboo 查到的绝对路径,args 填 ["mcp"]。
5.2 要你亲手做的部分
- 系统授权(Mac):系统设置 → 隐私与安全性 → “屏幕与系统录音”和“辅助功能”,给 Terminal(或你运行 Claude Code 的程序)、WorkBuddy 打开开关。Peekaboo 文档说要授权给实际运行
peekaboo的那个程序;接进 WorkBuddy 时,授权给 WorkBuddy 本身,仍反复弹授权就看排错表最后一行。授权屏幕录制后可能要退出再重开客户端。 - Windows 安全提示:首次运行时,Windows Defender 或 360 等可能拦截 uv 下载的程序。是否放行由你判断,不要让智能体关杀毒软件。
- WorkBuddy 自定义连接器:左侧“专家·技能·连接器”→“连接器”页签 → 右上角“自定义连接器”,粘贴 JSON,保存后开启。新建任务时在输入框左下角
+→ 连接器里勾选它。 - 重启客户端:Claude Code 退出后重新运行
claude;WorkBuddy 退出(连托盘图标也退出)再打开。 - 测试环境:建一个只放测试数据的文件夹;有条件就用虚拟机或单独的 Windows 用户账户;操作前关掉微信、邮件、网银等窗口,关闭系统通知。
5.3 参考:手动安装命令
Windows 11(PowerShell,普通用户权限)
# 0. 国内镜像(见 5.0.1),设完重开终端
setx UV_DEFAULT_INDEX "https://pypi.tuna.tsinghua.edu.cn/simple"
setx UV_PYTHON_INSTALL_MIRROR "https://registry.npmmirror.com/-/binary/python-build-standalone"
# 1. 安装 uv(已有 Python 时走清华镜像)
pip install uv -i https://pypi.tuna.tsinghua.edu.cn/simple
# 官方脚本 irm https://astral.sh/uv/install.ps1 | iex 从 GitHub 下载 uv,国内访问不稳定,只作备选
# 2. 让 uv 管理 Python 3.14(不改系统 Python)
uv python install 3.14
# 3. 先手动跑一次,确认能启动(Ctrl+C 退出)
uvx windows-mcp serve --exclude-tools "PowerShell,Registry,FileSystem,Process"
# 4. 注册到 Claude Code(当前项目作用域)
claude mcp add --transport stdio --scope local -e ANONYMIZED_TELEMETRY=false -e UV_DEFAULT_INDEX=https://pypi.tuna.tsinghua.edu.cn/simple -e UV_PYTHON_INSTALL_MIRROR=https://registry.npmmirror.com/-/binary/python-build-standalone windows-mcp -- <uvx.exe 绝对路径> windows-mcp serve --exclude-tools "PowerShell,Registry,FileSystem,Process"
pip install uv装出的uvx.exe在该 Python 的Scripts目录下,官方脚本装在C:\Users\<用户名>\.local\bin\;以where uvx查到的为准。- 官方 README 说明:在 Windows 上遇到“Connection closed”,把
uvx换成uvx.exe的完整路径(用where uvx查)。 - 在 WSL 里运行 Claude Code 时,Windows-MCP 仍要在 Windows 侧运行,官方写法是用
powershell.exe -Command "C:\Users\<用户名>\.local\bin\uvx.exe windows-mcp serve"作为启动命令。 - 中文 Windows 上 App 工具报错时,把它加进排除列表:
--exclude-tools "PowerShell,Registry,FileSystem,Process,App"。代价是不能用它打开和切换窗口,改为自己先把软件打开。
WorkBuddy 自定义连接器 JSON(Windows):
{
"mcpServers": {
"windows-mcp": {
"type": "stdio",
"command": "C:\\Users\\<用户名>\\.local\\bin\\uvx.exe",
"args": ["windows-mcp", "serve", "--exclude-tools", "PowerShell,Registry,FileSystem,Process"],
"env": {
"ANONYMIZED_TELEMETRY": "false",
"UV_DEFAULT_INDEX": "https://pypi.tuna.tsinghua.edu.cn/simple",
"UV_PYTHON_INSTALL_MIRROR": "https://registry.npmmirror.com/-/binary/python-build-standalone"
}
}
}
}
Electron 类桌面应用(Claude Desktop、WorkBuddy 都是)未必继承系统 PATH,所以 command 写绝对路径(Windows-MCP 官方 README 对 Claude Desktop 这样说明,WorkBuddy 同样按绝对路径写)。
Cua Driver(Windows 备选)
irm https://cua.ai/driver/install.ps1 | iex
claude mcp add --transport stdio --scope local cua-driver -- cua-driver mcp
- 安装脚本从 GitHub Releases 下载 zip(没有国内镜像,GitHub 在国内慢、时好时坏),装到
%USERPROFILE%\.cua-driver\;cua-driver mcp-config --client claude会打印带绝对路径的注册命令。 - Windows 上权限模式由客户端
env里的CUA_DRIVER_PERMISSION_MODE决定,默认standard,允许向所有应用输入。 - 关闭遥测:在
env里设CUA_DRIVER_RS_TELEMETRY_ENABLED=0(变量名见 Hermes Agent 的 Computer Use 文档;如果设了仍不生效,以 Cua 官方文档为准)。
macOS(Peekaboo)
npm install -g @steipete/peekaboo --registry=https://registry.npmmirror.com
peekaboo --version
peekaboo permissions status
claude mcp add --transport stdio --scope local peekaboo -- "$(which peekaboo)" mcp
- npmmirror 上
@steipete/peekaboo最新为 4.9.5,只支持 darwin(即 macOS),要求 Node.js 22,安装脚本只做chmod,不再另行下载。 - 官方首推的
brew install openclaw/tap/peekaboo从 GitHub 下载,国内访问不稳定,只作备选;官方给的npx -y @steipete/peekaboo mcp每次启动临时下载,本课也不用。Peekaboo 的 MCP 只支持 stdio,HTTP / SSE 尚未实现。
5.4 怎样确认装好了
- Claude Code:终端里
claude mcp list显示windows-mcp(或peekaboo、cua-driver)为 Connected;重开claude后输入/mcp,能看到它和工具列表。Windows-MCP 应能看到Screenshot、Snapshot、Click、Type、App等,看不到PowerShell、Registry,说明排除生效。 - WorkBuddy:连接器页里自定义连接器显示已连接(绿点);新任务里问“你现在能用哪些 windows-mcp 工具”,回答的工具名与上面一致。
- Peekaboo:
peekaboo permissions status显示屏幕录制、辅助功能均已授权。 - 最小验证:打开计算器,让智能体“只截一次图,告诉我计算器显示的数字”,不做点击。能正确说出数字,说明截图通、模型能看图。
6. 使用教程:用计算器核一个环比增长率
场景: 某地 9 月 CPI 指数 105.2,8 月 102.8,算环比涨幅(百分比,保留两位小数)。手算答案:(105.2 − 102.8) ÷ 102.8 × 100 ≈ 2.33。这个任务本身用不着 Computer Use,选它是因为没有风险、答案可核对,便于观察“截图→点击→复核”的循环。
准备:
- 新建测试文件夹
D:\cu_test(Mac:~/cu_test),在里面启动 Claude Code 或在 WorkBuddy 里选它作为工作空间; - 手动打开系统计算器,切到“标准”模式,放在屏幕中间;
- 关掉其他窗口和通知。
提示词(两端通用,Mac 上把“Windows 计算器”改成“计算器”):
请用 windows-mcp(Mac 上用 peekaboo)操作已经打开的 Windows 计算器,计算 (105.2 - 102.8) / 102.8 * 100。
规则:
1. 只操作计算器这一个窗口,不打开、不切换到其他程序。
2. 每次点击前先截图或读取控件,确认按钮位置;按完等号后再截一次图,读出显示结果。
3. 把计算过程和结果写进本文件夹的 计算记录.md:写清每一步按了哪些键、最终显示的数字、保留两位小数后的结果。
4. 不保存截图文件,不读取其他文件,不联网。
5. 遇到任何弹窗、授权提示,停下来告诉我。
预期看到的工具调用(Windows-MCP 为例):
Screenshot / Snapshot → 看到计算器窗口和按钮
Click(或 Type) → 依次输入 105.2 − 102.8 = ÷ 102.8 × 100 =
Screenshot → 读出结果约 2.334630350194553
写入 计算记录.md → 客户端自带的写文件工具
标准模式计算器按键入顺序即时计算,所以要先按一次 = 得到 2.4,再继续 ÷、×。智能体如果直接按顺序输入整串,结果会不同,这正好是让它“复核截图”的理由。Peekaboo 的对应工具是 see(截图并列出控件)、click、type、press。
产出文件: 计算记录.md,内含按键步骤、显示结果、两位小数结果 2.33。
验收:
- 计算器屏幕上的数字与
计算记录.md一致,两位小数为 2.33; - 客户端的工具调用记录里,最后一步是截图复核,不是“点完就报结果”;
- 测试文件夹里只多了
计算记录.md,没有截图文件或其他文件; - 没有打开过其他程序。
7. 一个更长的例子:让智能体操作另一个智能体
本课的上机演示视频,是让 Hermes Agent 在一台独立的 macOS 虚拟机里操作 WorkBuddy 录出来的。这是一套“智能体操作另一个智能体”的 Computer Use 实例,可以用来理解这类任务要怎样设边界、怎样验收。这个例子不需要你复现。
流程:
- 定对象与指令。 定好被演示的软件,手册里的提示词原文照打。录交互界面,不用无头命令行日志冒充界面。
- 在独立虚拟机里操作。 智能体在虚拟机里驱动 WorkBuddy:真实移动鼠标、逐字输入、点真实的发送按钮,每一步后截图回读确认。不在日常使用的电脑桌面上点击或输入。
- 只录一个窗口。 按窗口绑定 WorkBuddy 主窗口录制,其他窗口和通知进不了画面;全屏录再裁剪不算隐私隔离。
- 记事件、按事件剪辑。 录制时记下开始输入、输入结束、点击发送、文件出现、预览加载等时刻和鼠标轨迹;后期按这些真实事件剪辑:压缩等待、在点击和输入处推近、换软件时拉回全景,不重排因果、不删真实错误。
- 本地语音合成配旁白。 旁白逐句合成,按句子时长排进时间轴,字幕从同一时间轴生成。
- 机器验收。 成片完整解码、核对音轨与帧数;抽取关键时刻和剪辑点两侧的帧检查画面;对最终音频做语音识别,核对数字、年份等关键词;用静帧检测加静音检测找“画面不动又没声音”的空白段。
这个流程里遇到过的常见坑:
| 现象 | 原因 | 处理 |
|---|---|---|
| 逐字输入被拒,或触发别的快捷键 | 前一个组合键之后系统仍认为 Command / Shift 按着 | 输入前检查修饰键状态,用一个普通键清掉再继续 |
| 点到 Dock、打开无关程序 | 把 Retina 截图像素当成点击坐标(差 2 倍) | 点击前先写出换算式:截图像素 ÷ 2 = 逻辑点 |
| 坐标全部失效、输入落空 | 用屏幕共享连到虚拟机时,虚拟机分辨率被改 | 录制期间不连屏幕共享;每步前校验显示尺寸和前台程序 |
| 原片只有前几分钟 | 系统中途停掉录屏流 | 用分段自愈的录屏脚本,后期按分段时间取材 |
| 渲染卡在 0% | 原片帧率不固定,静止段没有帧 | 先转成固定 30 fps 工作副本再渲染 |
| 点击回执显示目标不是 WorkBuddy | 截图工具的残留选区截走了输入 | 立即停止输入,取消一次仍不行就请人处理 |
| 诊断输出里出现令牌 | WorkBuddy 父进程参数里嵌着连接器令牌 | 不打印进程完整参数,只输出去敏字段 |
| 智能体说“没有其他写入” | 自述不可靠,可能另写了记忆文件 | 结束后枚举测试目录,包括 .workbuddy/memory/ 等隐藏文件 |
| 系统授权弹窗 | 需要人决定 | 停下请人处理,不代点“允许”、不关安全功能 |
这个例子的启示:Computer Use 能跑通,靠的是隔离环境 + 每步截图回读 + 事件留痕 + 结束后程序化核对,而不是相信“工具返回成功”。这套流程用的是自写的驱动脚本,没有用到 Peekaboo、Windows-MCP 或 Cua。
8. 常见问题与排错
| 现象 | 原因 | 处理 |
|---|---|---|
uvx windows-mcp 报 Python 版本不符或装到旧版 | 0.8.6 起要求 Python ≥ 3.14 | uv python install 3.14;不要只装 3.13 |
| 下载 Python 或依赖很慢、超时 | 没配镜像,uv 在连 GitHub 和 pypi.org | 按 5.0.1 设 UV_DEFAULT_INDEX、UV_PYTHON_INSTALL_MIRROR,并写进 MCP 配置的 env;清华镜像不通时换阿里 https://mirrors.aliyun.com/pypi/simple/ |
| npm 装 Peekaboo 很慢 | 用的是 registry.npmjs.org | 加 --registry=https://registry.npmmirror.com |
| Cua Driver 安装脚本卡住 | 要从 GitHub Releases 下载,GitHub 国内访问慢、不稳定 | 改用 Windows-MCP;确要用 Cua 时换个时段重试 |
| Claude Code 里显示 Connection closed | Windows 上 uvx 找不到或 PATH 不一致 | 用 where uvx 查绝对路径,注册时写 C:\Users\<用户名>\.local\bin\uvx.exe |
| WorkBuddy 自定义连接器一直“连接中”或工具列表为空 | command 写了相对命令,应用没继承 PATH;JSON 格式错 | command 写绝对路径;检查引号和逗号;退出 WorkBuddy(连托盘图标)再开 |
| 中文 Windows 上 App 工具报错、找不到程序 | v0.8.8 及以前对非英文系统支持不好 | 把 App 加进 --exclude-tools,自己先打开软件 |
| 智能体说看不到截图,或请求报 400 | 当前模型不收图片,或图片放的位置不被接受 | 换能看图的模型;纯文本模型改用 Cua 的 --text-only 方案 |
| 截图太大、很慢、积分消耗快 | 2K / 4K 屏幕原图尺寸大 | Windows-MCP 设 WINDOWS_MCP_SCREENSHOT_SCALE=0.5;只截目标窗口 |
| 点击位置偏了 | Windows 显示缩放(125%、150%)或多屏坐标混乱 | 只用主屏、缩放设 100% 试;让智能体先调用 DisplayInventory 读缩放信息 |
| 点不动某个程序 | 该程序以管理员身份运行,智能体是普通权限 | 换一个普通权限的程序练习;不要为此把智能体提权 |
| 360、Defender 拦截 | 模拟键鼠和截屏被视为可疑行为 | 由你判断是否放行;不让智能体关杀毒软件 |
| 鼠标一动 AI 就停 | Windows-MCP 默认开启“桌面控制”,检测到你动鼠标会把控制权交还给你 | 正常现象;让它做事时手离开鼠标,约 10 秒空闲后它继续;紧急接管按 Ctrl+Alt+Shift+Backspace |
| Mac 上反复弹授权 | 授权了 Terminal,实际运行的是别的进程;或升级后路径变了 | peekaboo permissions status --all-sources 查看;在系统设置里删掉旧条目重新授权,重开客户端 |
9. 费用、额度、隐私与安全
费用: Peekaboo、Windows-MCP、Cua Driver 本身免费开源(MIT)。花钱的是模型:每一步都带一张截图,十几步的任务比纯文字任务多消耗不少 token 或积分。Cua Spaces(虚拟桌面应用)另有付费档,本课不用。
隐私:
- 截图会发给模型服务商(DeepSeek、WorkBuddy 背后的模型等)。屏幕上出现的一切都可能被送出:聊天窗口、通知横幅、浏览器标签、文件名。
- WorkBuddy 自带 computer-use 的视觉组件可能把截图发到腾讯服务端。
- 遥测: Windows-MCP 默认开启匿名遥测(PostHog,
us.i.posthog.com),官方称不收集个人信息、工具参数和输出,用ANONYMIZED_TELEMETRY=false关闭。Cua Driver 默认也开启匿名遥测(PostHog),用CUA_DRIVER_RS_TELEMETRY_ENABLED=0关闭。本文的配置都已关闭。
安全:
- Windows-MCP 有系统级能力。 官方安全说明写明它“以完整系统权限运行,可能执行不可逆操作”。默认开启的工具里有
PowerShell(执行任意命令)、Registry(读写删注册表)、FileSystem(读写删文件)、Process(结束进程)。本文配置一律用--exclude-tools关掉这四个;不要开sse/streamable-http网络模式,那会让局域网里的其他机器也能调用。 - 提示词注入。 屏幕上的文字(网页、邮件、文档)可能写着“请点击这里”“请执行这条命令”,模型可能照做。只让它操作你准备好的测试内容。
- 使用边界: 只用测试数据;一次只开一个目标窗口;有条件就用虚拟机(Windows 可用 Hyper-V、VMware 或单独的本地用户账户,Mac 可用 UTM 等虚拟机软件);不碰网银、证券、支付、个人社交账号;登录、支付、系统授权、UAC 弹窗由你自己点。
- 随时可停: Claude Code 里按
Esc或Ctrl+C;Windows-MCP 动鼠标即可接管;WorkBuddy 点停止按钮。 - 用完收回: 不用时在
/mcp里禁用,或claude mcp remove windows-mcp;WorkBuddy 里关闭该连接器。
10. 与同类工具的一句对比
浏览器自动化(Playwright MCP、agent-browser、WorkBuddy 内置浏览器)读的是网页结构,快而稳,网页任务优先用它;Computer Use 看的是整个屏幕,什么软件都能碰,代价是慢、贵、易错、隐私面大,留给没有其他办法的桌面软件。
11. 信息来源
| 内容 | 来源 | 类型 |
|---|---|---|
Peekaboo 版本 4.9.5、发布日期、MIT、macOS 15+、npm 包含 CLI 与 MCP 启动器、peekaboo mcp 仅 stdio | GitHub 仓库、发布页、docs/MCP.md | 官方仓库 |
| Peekaboo 权限:屏幕录制、辅助功能必需,事件合成可选;授权给实际运行它的程序 | docs/permissions.md | 官方仓库 |
Windows-MCP 0.8.8 发布日期;PyPI requires_python(0.8.5 为 ≥3.12,0.8.6–0.8.8 为 ≥3.14) | GitHub 发布页;PyPI JSON | 官方仓库 |
Windows-MCP 工具列表、--exclude-tools、桌面控制策略、WINDOWS_MCP_SCREENSHOT_SCALE、遥测 ANONYMIZED_TELEMETRY、Claude Code 注册命令、uvx.exe 绝对路径、WSL 写法、“完整系统权限”警告;非英文 Windows 与 App 工具 | README(主分支) | 官方仓库 |
Cua Driver 跨平台、Windows 安装命令、cua-driver mcp、mcp-config、权限模式、--text-only 过滤 | Cua 仓库、connect-your-agent、permissions;https://cua.ai/driver/install.ps1 脚本注释 | 官方仓库 / 官方文档 |
Cua Driver 遥测默认开启及 CUA_DRIVER_RS_TELEMETRY_ENABLED=0 | Hermes Agent 文档 computer-use.md | 第三方官方文档 |
| Claude Code 自带 Computer Use 与 Claude-in-Chrome 要 Anthropic 账号 | computer-use、chrome | 官方文档 |
UV_DEFAULT_INDEX、UV_PYTHON_INSTALL_MIRROR 两个环境变量 | uv 环境变量文档 | 官方文档 |
| WorkBuddy 4.22.4“新增实验性 computer-use 工具(仅 macOS)”;5.8.3 发布日期;自定义 MCP | WorkBuddy 更新日志 | 官方文档 |
| WorkBuddy 自定义连接器入口与“配置方式与 MCP 类似” | 连接器说明 | 官方文档 |
| WorkBuddy 尚未推出 Computer Use、建议用多模态模型;Windows 管理员权限与杀毒软件干扰 | 知乎文章 | 社区 |
DeepSeek deepseek-flash 支持图片、Anthropic 兼容端点传图、图片只能在 user 消息 | DeepSeek 图像理解 | 官方文档 |
| DeepSeek 每图 384 token、约 800×800 等效分辨率 | DeepSeek 新闻 2026-08-21;博客园整理 | 官方文档 / 社区 |