关于 Clawd Cursor
Clawd Cursor 是供 Agent 操作 Windows、macOS 或 Linux 桌面界面的本地 MCP 服务。它将无障碍信息和 OCR 整合为 UI 映射,验证操作,并通过统一安全关卡处理调用。
主要功能
- 01跨平台桌面控制
- 02无障碍信息与 OCR UI 映射
- 03用于屏幕交互的视觉回退
- 04操作验证
- 05允许、确认或阻止的安全关卡
- 06暂停并等待人工输入
适用场景
- 01自动化原生桌面应用
- 02操作没有公开 API 的图形界面
- 03在登录或 2FA 时暂停自动化
- 04验证重要的点击和输入
MCP 相关
Clawd Cursor 通过 MCP 工具向兼容 Agent 提供桌面控制能力。本地服务会对工具调用执行统一安全检查,并可暂停以等待人工输入。
配置
本地服务的配置在各客户端中通用,复制后粘贴到客户端的 MCP 配置文件即可。
工具
本地服务需要在你的电脑上运行后才能读取工具,维护者暂未提供工具列表。
详细介绍
Clawd Cursor
为任何 AI Agent 提供安全的桌面控制。将屏幕编译为 UI 映射,并通过稳定 ID 操作元素(仅在最后手段下使用截图/视觉识别),
验证自身操作,并通过一个安全检查点来把关所有操作。本地 · 跨操作系统 · 适用于任何模型。
快速开始 · 最新动态 · 与众不同之处 · 引擎 · 工作原理 · 工具 · 平台 · 更新日志
最新动态
1.5.24 — AI 永远不会碰你的悬浮提示条,失败也不再伪装成结果。
- 暂停期间等待你操作时,不会读取、点击或输入任何内容。悬浮提示条和暂停提示永远不会成为操作目标,即使是来自另一个 clawdcursor 进程的操作也不例外。
- 在 macOS 上,没有屏幕录制权限时,截图会报错,而不是返回一张桌面壁纸;打开的弹出窗口也可以读取。
- clawdcursor 驱动的浏览器在导航时会切换到前台。
- OCR 读取失败时会报告错误,而不是显示“No text detected”;只有引擎确实提供 OCR
confidence时,才会显示该值。
1.5.23 — **Windows:按名称查找元素时,不再误匹配无关字母。**其他页面上单独的“C”可能会匹配“User code 0”,而“Don't Save”可能会匹配 Save。现在,部分匹配必须是所查找名称中的真实片段。
1.5.22 — **尽可能缩短轮到你操作的时间。**当 Agent 需要你协助(例如登录或输入 2FA 验证码)时,它只会请求你完成这一步,其余操作由它自行完成。使用 done_when(完成后屏幕上会显示的内容)时,你一完成操作,提示就会从蓝色变回琥珀色,无需点击 Resume。
1.5.21
- **
set_value不再猜测字段。**以前,如果没有字段名称或角色,它会向窗口中最大的文本框输入内容;现在则会要求你指定字段。 - **macOS:缺少屏幕录制权限不再导致所有功能失效。**只有截图和 OCR 会失败,并会说明如何修复;窗口、按键和辅助功能仍可正常使用。
- Windows 上的页面文本更整洁(不含占位字符),并包含一项依赖项安全更新。 1.5.20
- 屏幕上的胶囊控件不再挡住 Agent 自己的点击。 它会显示在浏览器标签页和地址栏所在的位置;现在,每次点击、拖动或滚动前,它都会暂时让开,然后再回来。适用于 Windows、macOS 和 Linux。
- 在 Linux 和 macOS 上读取页面也不再高亮页面。
copy_all_text通过辅助功能读取文档,与 Windows 上一样:获取精确文本,不选中任何内容,也不触碰剪贴板。 - 输入完成后会恢复你的剪贴板(
smart_type也一样),并且只会在粘贴完成后恢复,因此响应缓慢的应用无法粘贴你之前复制的内容。 - macOS:
window focus会聚焦你指定的进程;屏幕锁定时会明确告知;侧边栏点击会经过验证;单独的修饰键(shift)也能正常使用。
1.5.19 — 输入操作绝不会粘贴你自己的剪贴板内容。 clawdcursor 通过粘贴来输入;在 Windows 上,写入剪贴板可能会静默失败,导致粘贴时发送了你自己复制的内容。现在,每次粘贴前都会检查剪贴板;如果其中没有目标文本,就会逐键输入。
1.5.18
- 暂停提示中新增“其他”。 Agent 暂停等待你时,提示中会在“继续”和“结束任务”之间显示第三个按钮:你可以输入回复,而不是让 Agent 执行该步骤——例如“改用测试账号”、一段代码或调整计划——然后按 Enter。Agent 会根据你写的内容继续。在 Windows、macOS 和 Linux 上均可使用;通过 MCP 调用
pause_for_user时,会返回{status:"replied", reply}。 - 读取页面不再高亮页面(Windows)。
copy_all_text会像屏幕阅读器一样读取文档:获取精确文本,不使用 Ctrl+A,不选中任何内容,也不触碰剪贴板。 - 每个工具都添加了 MCP 工具注释,
window/system现在会说明每项操作、其副作用以及返回内容。
1.5.17
- macOS:ASCII 以外的文本会按原样输入和粘贴 — “café 日本語” 不会再变成 “cafa aaa” 或 “caf√©”。
copy_all_text绝不会选中编辑器或列表(在那里按 Ctrl+A 会选中整份文档或所有邮件)。
1.5.16
- 遇到障碍时会暂停等待你,然后继续执行。 登录、2FA 验证码、CAPTCHA、升级页面:Agent 不会放弃,而是会暂停。屏幕周围的辉光会变为蓝色,屏幕提示会说明需要你做什么(“登录 Outlook,然后点击继续”)。点击继续,它就会从暂停处接着执行;点击结束任务则会停止。你自己的 Agent 也可以通过 MCP 调用
system({ action: "pause_for_user", message })实现同样的效果;在终端中可运行clawdcursor resume(或使用--end)。 - 所有操作系统现在都有辉光和横幅。 macOS 和 Linux 现在也有与 Windows 相同的屏幕边缘辉光和横幅:Agent 工作时为琥珀色,等待你时为蓝色。双击横幅即可停止所有操作。
- macOS 的盲操作模式已赶上 Windows。 原生辅助功能助手可在 0.3 s 内列出窗口(此前为 11 s),并在 0.06–0.2 s 内读取窗口树。当系统对话框占用键盘时,输入操作会被拒绝;如果另一个应用的对话框接管了按键,Agent 也会收到通知。
- Windows 和 Linux 上的盲操作模式更加精准。 经典控件不再被读取为空白窗格;读取的是打开的对话框;点击会打开模态窗口的按钮不再导致 10 s 卡顿;会按名称查找正确的字段;聚焦窗口时也不再取消最大化状态。
- 升级拦截页面现在会被视为障碍。 点击
Upgrade、Subscribe或Start trial时需要确认。 - 了解你正在运行的版本。
clawdcursor versions会列出所有已安装的副本(全局 npm、Claude Desktop 扩展、Claude Code 插件),安装程序也会说明更新了哪些内容。
其他内容请参阅更新日志。
它是什么
Clawd Cursor 是一个本地 MCP 服务,让任何可调用工具的 Agent——Claude Code、Cursor、Windsurf、OpenClaw、Claude Agent SDK,或你自己的循环——都能安全地控制真实桌面。它可以像人一样点击、输入、读取屏幕、打开应用并操作任何 GUI:原生应用、浏览器,甚至画布。
大多数“让 Agent 使用电脑”的工具都会截取屏幕截图并交给视觉模型处理——速度慢、成本高,而且脆弱。Clawd Cursor 会将屏幕编译成一张 UI 映射:它将无障碍树和 OCR 融合为一组带置信度评分的元素,每个元素都标记有稳定的 el_NN ID,并通过 ID 操作元素——而不是使用像素坐标。坐标仅用于最后的截图/视觉层(读取当前帧中的实时像素),适用于仅有画布的应用或确实需要空间推理的任务。这样做成本更低、速度更快、更私密,而且——独一无二的是——它会检查每个操作是否确实达到了所声称的效果。
只要人能在屏幕上完成的事,你的 Agent 也能做到。没有 API、没有集成?没问题——只需按正确顺序读取、点击、按键并等待。将它用作最后一公里的后备方案:有原生 API?就用它。有 CLI?就用它。Clawd Cursor 专为点击操作、旧版应用,以及没有公开接口的 GUI 而设计。
与众不同之处
桌面 Agent 领域竞争激烈。最接近的安装即用同类产品是 Windows-MCP 和 Terminator(桌面 MCP 服务);仅限浏览器的工具(browser-use、Playwright MCP)与它们相邻;而 OmniParser / UI-TARS 则是以视觉为核心的解析方案,你可以基于它们构建 Agent,但它们并不是可供安装的产品。以下是对这些方案的坦诚对比 — Clawd Cursor 做到了哪些热门选项做不到的事:
| Clawd Cursor | browser-use | Playwright MCP | OmniParser / UI-TARS | computer-use | |
|---|---|---|---|---|---|
| 适用于任何桌面应用,而不只是 Web | ✅ | 仅限 Web | 仅限 Web | ✅ | ✅ |
| 跨操作系统(Windows + macOS + Linux) | ✅ | — | — | 不一 | 沙盒 |
| 无需视觉模型的感知 | ✅ 编译后的 a11y + OCR 地图 | DOM | a11y 树 | ❌ 以视觉为核心 | ❌ 视觉 |
| 验证自身操作(偏差) | ✅ | — | — | — | — |
| 单一安全关卡(允许/确认/阻止) | ✅ | — | — | — | — |
| 任何模型 / 供应商 | ✅ | ✅ | 不是 Agent | 特定模型 | 仅限 Claude |
| 原生支持 MCP(一个配置,适用于任何宿主) | ✅ | 库 | 测试框架 | — | 工具调用 API |
| 仅限本地运行,无需云端 | ✅ | ✅ | ✅ | 需要模型 | 屏幕 → 云端 |
这里有三项确实很少见:
- 优先使用成本最低的感知方式,完全本地运行。 无障碍树(免费)→ OCR(便宜)→ 截图(昂贵 — 只有这一层会把像素放进模型的上下文;“截图”和“视觉”是同一步骤)。Agent 只在必要时才升级,因此令牌成本会随任务难度变化 — 使用本地模型时,任何数据都不会离开设备。以视觉为核心的 Agent(OmniParser、UI-TARS)每次观察都需要把截图传给模型。
- 它会验证。 对重要操作传入
expect后,Clawd Cursor 会重新检查实时屏幕(为异步 UI 留出短暂的稳定等待时间),并在发现偏差时报告 DEVIATION,而不是给出空洞的“成功”。不能仅凭操作前就已成立的证据,将任务标记为完成。 - 一道安全关卡。 每次调用 — 无论来自通过 stdio 连接的编辑器、通过 HTTP 连接的外部 Agent,还是内置循环 — 都会在接触桌面之前经过单一的
safety.evaluate()关卡(允许 / 确认 / 阻止)。Agent 无法绕过它。
此外:只要有 Agent 正在操作,Windows、macOS 和 Linux 屏幕上都会显示 “desktop control in progress” 横幅,并在屏幕边缘显示琥珀色光晕 — 双击横幅即可停止。 当 Agent 需要你协助时(例如登录或输入双重身份验证代码),光晕会变成蓝色,横幅会说明需要执行什么操作,并提供 Resume 和 End task。坐在设备前的人始终知情,也始终可以使用紧急停止开关。
安装
clawdcursor 是一个发布到 npm 的 MCP 服务 — 你可以像安装其他 MCP 服务一样,将它安装到任何支持 MCP 的 Agent 中(Claude Code、Claude Desktop、Cursor、Windsurf、Zed、OpenAI Codex,或你自己的循环)。
Claude Desktop — 一键扩展(无需终端)
下载适用于你操作系统的扩展并打开 — Claude Desktop 会安装它:
| Windows | macOS | Linux |
|---|---|---|
| clawdcursor-win32.mcpb | clawdcursor-darwin.mcpb | clawdcursor-linux.mcpb |
- 双击该文件(或前往 Settings → Extensions → Advanced settings → Install Extension… 并选择该文件)。
- 开启 Allow clawdcursor to control this computer — 这是一次性的桌面控制授权;开启之前,每个工具都会返回授权提示。
- macOS: macOS 首次询问时,请在 Privacy & Security → Accessibility 和 Screen Recording 中允许 Claude。
无需 Node.js、npm 或编辑 JSON — Claude Desktop 会自行运行打包好的服务。以下内容适用于其他 Agent,或未安装扩展的 Claude Desktop。
1 — 安装引擎并授予授权(一次性)
npm i -g clawdcursor
clawdcursor consent --accept # one-time desktop-control consent (required)
clawdcursor grant # macOS only — approve Accessibility + Screen Recording
支持 MCP elicitation 的宿主(例如 Claude Code、VS Code)也允许你跳过
consent --accept:首次调用工具时,应用会直接询问 “Allow clawdcursor to control this computer”。
零安装也可行 — 将下方任意代码片段中的
clawdcursor替换为npx -y clawdcursor,npx 就会按需获取它。不过仍建议全局安装:它可固定版本,且能在磁盘上检查(对于具有完整桌面控制权限的工具,这比每次运行时自动获取latest更安全),并且 macOS 原生辅助程序会在安装时构建。需要 Node.js 20+。
各操作系统的前置条件。 Windows 安装简便 —
sharp和@nut-tree-fork/nut-js附带预构建二进制文件,因此无需 C++/Python 构建工具。macOS 需要 Xcode Command Line Tools(xcode-select --install)才能截图/使用视觉功能;即使没有这些工具,基于辅助功能的核心控制仍然可用。Linux 需要几个 npm 无法安装的系统软件包:tesseract-ocr(OCR)、python3-gi+gir1.2-atspi-2.0(辅助功能树),以及 — 在 Wayland 上 —ydotool(模拟输入)。
2 — 将其添加到你的 Agent(选择宿主)
一键添加(Cursor、VS Code):
所有宿主运行的命令都相同——clawdcursor mcp --compact,也可以运行
npx -y clawdcursor mcp --compact,无需全局安装。不同宿主的配置格式
有所不同:
Claude Code
claude mcp add clawdcursor -s user -- clawdcursor mcp --compact
Cursor · Windsurf · Claude Desktop · Cline · Gemini CLI — 通用的 mcpServers 格式:
{
"mcpServers": {
"clawdcursor": { "command": "clawdcursor", "args": ["mcp", "--compact"] }
}
}
Claude Desktop 读取 %APPDATA%\Claude\claude_desktop_config.json(Windows)或
~/Library/Application Support/Claude/claude_desktop_config.json(macOS)。
Gemini CLI 读取 ~/.gemini/settings.json。
VS Code(Copilot) — .vscode/mcp.json 使用 servers,而非 mcpServers:
{
"servers": {
"clawdcursor": { "command": "clawdcursor", "args": ["mcp", "--compact"] }
}
}
Zed — settings.json 中的 context_servers:
{
"context_servers": {
"clawdcursor": { "command": "clawdcursor", "args": ["mcp", "--compact"] }
}
}
OpenAI Codex — ~/.codex/config.toml。首次启动可能需要几秒,
因此请调高默认的 10 s 启动超时:
[mcp_servers.clawdcursor]
command = "clawdcursor"
args = ["mcp", "--compact"]
startup_timeout_sec = 30
opencode — opencode.json 使用 mcp,且 command 是一个数组:
{
"mcp": {
"clawdcursor": { "type": "local", "command": ["clawdcursor", "mcp", "--compact"] }
}
}
其他任何 MCP 宿主(Goose、Continue 等)——注册一个 stdio 服务,命令设为
clawdcursor,参数设为 mcp --compact。
Windows: 有些宿主会在不启动 shell 的情况下启动服务,因此无法找到
clawdcursor或npx(二者都是.cmd启动脚本)。如果服务无法启动,请用cmd /c包装命令——例如"command": "cmd", "args": ["/c", "clawdcursor", "mcp", "--compact"], 或claude mcp add clawdcursor -s user -- cmd /c clawdcursor mcp --compact。
设置就这么简单。向你的 Agent 提问:“打开 Outlook,并回复 Sarah 发来的最新邮件。”
或者:一条命令安装插件(Claude Code)
跳过手动配置——此仓库提供了一个插件,只需一步即可注册工具并
捆绑使用指南技能。它会解析软件包的 bin(绝不使用
硬编码的 dist/ 路径),因此升级不会导致它失效:
claude plugin marketplace add AmrDab/clawdcursor
claude plugin install clawdcursor@clawdcursor
单行安装命令(npm i -g,并检查 Node 版本、PATH 和授权)
# Windows (PowerShell)
powershell -c "irm https://clawdcursor.com/install.ps1 | iex"
# macOS / Linux
curl -fsSL https://clawdcursor.com/install.sh | bash
注意。 你无需自行运行
clawdcursor mcp——宿主会在需要时通过 stdio 启动它。clawdcursor doctor不属于 MCP 配置的一部分;它只会为自主运行的agent守护进程配置内置大模型。在 macOS 上,必须启用“辅助功能” (主要控制路径);“屏幕录制”是可选的(仅用作视觉回退方案)。对于编辑器的权限允许列表, 请使用服务级通配符mcp__clawdcursor,而不要逐个添加工具——这样即使工具改名也不会受影响。
引擎
感知 + 验证核心(自 v1.5.0 起称为 UI State Compiler):
compile_ui将无障碍树和 OCR 融合为屏幕上带有置信度评分的地图,并为每个元素标记稳定的el_NNID。通过{element_id, snapshot_id}操作元素,而不是依赖像素 — 几乎不消耗令牌,还能适应 DPI、尺寸调整和布局变化。find_button/find_field会按含义定位目标,并提供其 ID。- 响应式验证。 在操作上指定
expect→ Clawd Cursor 会在实时屏幕上确认结果;如果 UI 未按预期响应,则返回 DEVIATION。 - 跨平台一致性。 编译器、安全字段脱敏和坐标处理可在 Windows、macOS 和 Linux 上运行;外部 Agent(MCP)接口会通过安全关卡解析
el_NN引用,并说明它是否连接到了你已有的浏览器。
Set-of-Mark 风格的元素 ID 和无障碍 / OCR 融合本身并非新理念 — 少见的是跨三个操作系统,通过单一 MCP 配置,在本地以无障碍优先的方式(无需视觉模型),配备内置验证关卡和单一安全检查点来实现这些功能。
工作原理
大脑所在的位置决定了运行方式。两种模式可以并行运行。
| 大脑所在位置… | 模式 | 命令 | 调用方式 |
|---|---|---|---|
| 在你的编辑器中(Claude Code、Cursor、Windsurf、Zed) | 直接工具 | clawdcursor mcp | 通过 stdio MCP 调用各个工具 |
| 在拥有独立 LLM 的无头 Agent 中(OpenClaw、Agent SDK、你的循环) | 直接工具 | clawdcursor agent --no-llm | 同样的工具,通过 HTTP MCP 调用 |
| 在 Clawd Cursor 内部(定时运行 /“提交后即可离开”) | 精简 Agent 循环 | clawdcursor agent + 通过 doctor 配置的 LLM | task / submit_task |
| 会将子任务委派给内置循环的外部大脑 | 直接调用 + 委派 | clawdcursor agent + 你的客户端 | 使用 task({instruction:…}) 进行移交 |
循环
读取无障碍树(开销低)→ 操作有名称的目标 → 根据最新观察结果进行验证 → 仅在需要时升级感知(OCR → 截图,这是唯一会向模型发送像素的层级)。无障碍树信息稀疏?system.detect_webview 会通过 CDP 将 Electron / WebView2 应用切换到 browser.*。仅使用画布的应用(Paint、Figma、游戏)?使用截图 + 坐标点击。
flowchart TB
task["User task"] --> loop["Agent LLM loop<br/>plans · chooses tools · verifies"]
loop --> observe{"Cheapest observation<br/>that answers the question"}
observe -- "obs·a11y — free" --> a11y["A11y tree<br/>(structured text + el_NN handles)"]
observe -- "obs·ocr — cheap" --> ocr["OCR (OS-level, no vision LLM)"]
observe -- "obs·dom — medium" --> dom["Browser DOM (CDP)"]
observe -- "obs·vision — expensive" --> vision["Screenshot (image into context)"]
a11y --> act
ocr --> act
dom --> act
vision --> act
act["Act<br/>click/type/key/drag · invoke/set_value · open_app · batch"] --> safety
safety["Single safety gate<br/>safety.evaluate() → allow / confirm / block"] -- allowed --> tools["Tool registry<br/>98 granular + 7 compound"]
safety -- needs user --> confirm["Human confirmation"] --> tools
safety -- denied --> blocked["blocked"]
tools --> desktop["Real desktop"]
desktop --> verify{"expect → does state match?"}
verify -- pass --> done["done"]
verify -- "DEVIATION" --> loop
classDef agentNode fill:#dbeafe,stroke:#2563eb,color:#0f172a;
classDef gate fill:#ede9fe,stroke:#7c3aed,color:#0f172a;
classDef obsNode fill:#fef9c3,stroke:#ca8a04,color:#0f172a;
classDef actNode fill:#ffedd5,stroke:#ea580c,color:#0f172a;
classDef stop fill:#fee2e2,stroke:#dc2626,color:#0f172a;
class loop,verify agentNode;
class safety,confirm,tools gate;
class observe,a11y,ocr,dom,vision obsNode;
class act actNode;
class blocked stop;
用于确定性连续操作的 batch。 如果后续 N 个步骤已知,可将它们合并为一次调用 — 每个步骤仍会经过安全关卡;任何防护检查未通过或发生错误时,批处理都会停止,并提供逐步跟踪记录。
任务委派。 在守护进程上配置 LLM 后,外部 Agent 可随时移交任务:task({"instruction":"…"})。内置循环会接管并汇报结果 — 将繁杂工作交给更便宜的模型,无需耗费你自己的上下文。
工具箱
我们并排提供两套目录。工具箱包含 7 个复合工具,每个工具都有一个 action 枚举,涵盖约 10–20 个动词(整个目录约 7,000 个令牌,含架构——约为细粒度工具集约 20,000 个令牌的三分之一;编辑器宿主已熟悉 computer_20250124 的结构)。细粒度工具集包含 98 个底层原语,每个动词对应一个架构(适用于需要顶层工具的运行时,或用于调试)。两者都通过同一个 safety.evaluate() 关卡运行;完整目录始终可通过 MCP tools/list 查看。
| 工具箱 | 操作 |
|---|---|
computer | screenshot、click、double_click、right_click、triple_click、hover、move、scroll、scroll_horizontal、drag、drag_path、type、key、wait |
accessibility | read_tree、find、get_element、focused、invoke、focus、set_value、get_value、expand、collapse、toggle、select、state、list_children、wait_for、compile_ui、find_button、find_field、smart_click、smart_type、smart_read |
window | list、active、focus、maximize、minimize、restore、close、resize、list_displays、screen_size、open_app、open_file、open_url、switch_tab、navigate |
system | copy_all_text、ocr、clipboard_read、clipboard_write、shortcuts_list、shortcuts_run、undo、pause_for_user、report、build_uri、open_uri、open_app、open_file、open_url、detect_webview、relaunch_with_cdp、delegate、system_time、system_prompt |
browser | connect、page_context、read_text、click、type、select_option、evaluate、wait_for、list_tabs、switch_tab、scroll |
task | run(默认;有界同步——最多等待 timeout 指定的时长;若任务耗时更久,则返回 {status:"running"} 和进度;再次调用以继续等待)、status、abort、resume(继续执行因等待用户而暂停的任务)。委托给内置循环。需要带有 LLM 的 clawdcursor agent。 |
batch | {steps:[…]}——将 N 次调用合并为一次往返;每个步骤为 {name, arguments, expect?},每步都会重新感知并经过安全检查;任何一步未命中时都会停止并附上跟踪记录。 |
computer({ action: "key", combo: "mod+s" }) // Cmd+S / Ctrl+S, resolved per-OS
accessibility({ action: "invoke", name: "Send" }) // click by name, not pixels
window({ action: "open_app", name: "Outlook" })
task({ instruction: "open Notepad and type hello" }) // hand off to the thin loop
优先使用成本最低的感知方式
每次观察都有成本。从能奏效的最低成本级别开始;只有失败时才升级。实时日志(CLAWD_LOG=pretty,在 TTY 中默认启用)会通过每次调用的徽标实时显示这一阶梯。
| 级别 | 徽标 | 成本 | 来源 | 适用时机 |
|---|---|---|---|---|
| T1 结构化 | obs·a11y | 几乎免费 | accessibility.*、window.*、browser.read_text、剪贴板 | 默认。文本和边界框,无图像,无视觉 LLM。 |
| T2 OCR | obs·ocr | 低 | system.ocr、smart_read / smart_click / smart_type | 无障碍树为空或内容稀疏时。提取操作系统级文本,不产生图像字节。 |
| T3 DOM | obs·dom | 中 | browser.read_text / page_context(CDP) | WebView / Electron / Chrome 内容。 |
| T4 截图(视觉) | obs·vision | 高 | computer.screenshot | 唯一会将像素放入模型上下文的级别。仅限 Canvas 的应用或空间推理。最后的手段。 |
操作工具会记录 act。在普通轮次中观察到 obs·a11y → act → obs·a11y,以及偶尔升级到 obs·vision,这就是完整的效率模型,清晰可见。
传输方式
一种协议——MCP——两种传输方式,共用同一目录和 JSON-RPC 信封。两者均无状态;无需会话握手。
| 传输方式 | 适用时机 | 客户端配置 |
|---|---|---|
| stdio MCP | 编辑器宿主。按需提供工具——无需守护进程。 | {"command":"clawdcursor","args":["mcp","--compact"]} |
| HTTP MCP | 无头 Agent、守护进程、编排、Agent SDK。向 http://127.0.0.1:3847/mcp 发送 JSON-RPC POST 请求。 | 运行 clawdcursor agent。Bearer 令牌位于 ~/.clawdcursor/token。 |
# HTTP MCP — list tools
# (the Accept header is required — the MCP spec's Streamable HTTP transport
# rejects requests that don't accept both JSON and SSE with a 406)
curl -s -X POST http://127.0.0.1:3847/mcp \
-H "Authorization: Bearer $(cat ~/.clawdcursor/token)" \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
平台支持
平台代码封装在单一的 PlatformAdapter 接口后(src/platform/{windows,macos,linux}.ts + wayland-backend.ts)。业务逻辑绝不会读取 process.platform。
| 平台 | UI 自动化 | OCR | 浏览器(CDP) | 输入 |
|---|---|---|---|---|
| Windows 10/11(x64 / ARM64) | 通过 PowerShell 桥接使用 UIA | Windows.Media.Ocr | Chrome / Edge | nut-js |
| macOS 12+(Intel / Apple Silicon) | 原生 AX 助手(Swift),JXA 回退方案 | Apple Vision | Chrome / Edge | nut-js + System Events |
| Linux X11 | 通过 python3-gi 使用 AT-SPI | Tesseract | Chrome / Edge | nut-js |
| Linux Wayland | 通过 python3-gi 使用 AT-SPI | Tesseract | Chrome / Edge | ydotool / wtype |
- Windows — 无需设置;PowerShell 桥接会按需启动。
- macOS — 首次运行需要辅助功能(必需)+ 屏幕录制(可选)权限;
clawdcursor grant会引导你完成对话框操作。适配器会处理 Retina/HiDPI — 请勿预先缩放坐标。 - Linux X11 —
apt install tesseract-ocr python3-gi gir1.2-atspi-2.0。 - Linux Wayland — 相同配置,另需
ydotool+ydotoold(首选)或wtype(仅键盘)。
安全与隐私
| 等级 | 操作 | 行为 |
|---|---|---|
| 允许 | 读取、打开应用、导航、在非敏感字段中输入、最小化 | 立即执行 |
| 确认 | 发送、删除、购买、转账、关闭窗口/退出应用和显示桌面的组合键、敏感应用 | 暂停以等待批准(使用 batch({allowConfirm:true}) 授权) |
| 阻止 | Ctrl+Alt+Del、锁定 / 注销 / 强制退出 / 关机键序列 | 直接拒绝(无执行路径) |
- 暂停,而非强行继续。 在登录、双重身份验证、CAPTCHA 或计划限制页面上,Agent 会将桌面交给你(蓝色光晕、“继续” / “结束任务”),而不是猜测。暂停在 15 分钟后超时(
CLAWD_PAUSE_TIMEOUT_MIN);CLAWD_NO_PAUSE=1可关闭暂停功能。 - 网络隔离。 绑定到
127.0.0.1。验证方式:netstat -an | findstr 3847(Windows)/| grep 3847(Unix)。 - 每个 HTTP 请求都进行 Bearer 令牌身份验证(
~/.clawdcursor/token)。 - 敏感应用策略。 电子邮件、银行业务、密码管理器、私人消息应用会自动提升至“确认”级别。
- 默认不收集遥测数据。 不会向外发送任何数据。屏幕截图保留在 RAM 中;使用本地模型时,任何数据都不会离开设备;使用云服务提供商时,屏幕截图只会发送到你配置的端点。
clawdcursor report为可选功能,并会准确预览将要发送的内容。 - 提示词注入防护。 屏幕文本会放在
<untrusted-screen-content>标签中返回 — 它是数据,绝不是指令。 - 日志隐私。 日志会对密码字段值进行脱敏(
AXSecureTextField、UIAIsPassword=true)。
关于私密漏洞报告,请参阅 SECURITY.md。
架构
| 目录 | 内容 |
|---|---|
src/core/ | 精简的 Agent 循环(runAgent)、感知层(a11y / snapshot / fingerprint / UI compiler)、响应式验证、焦点防护、安全门。 |
src/tools/ | 98 个细粒度工具 + 7 个复合聚合器 + batch、操作手册、注册表、分发。 |
src/platform/ | PlatformAdapter + Windows / macOS / Linux / Wayland、OCR 引擎、CDP 驱动程序、URI 处理程序。 |
src/llm/ | 提供商客户端(Claude、GPT、Gemini、Llama、Kimi、Ollama、…)、凭据、模型配置。 |
src/surface/ | CLI、MCP 服务(stdio + HTTP)、仪表板、doctor、引导设置、控制横幅。 |
PlatformAdapter 是平台代码唯一交互的对象;safety.evaluate() 是工具执行的唯一途径。这两个接口边界正是整个设计的核心。
CLI
供用户诊断安装问题。Agent 通过 MCP 连接。
clawdcursor consent Manage desktop-control consent (--accept / --revoke / --status)
clawdcursor grant Grant macOS permissions (interactive, macOS only)
clawdcursor doctor Configure the AI provider for `agent` mode (+ diagnostics)
clawdcursor status Readiness check (consent, permissions, AI config)
clawdcursor versions Every installed copy and its version (global, Claude Desktop extension, Claude Code plugin)
clawdcursor resume Continue a task paused for you (same as the on-screen Resume); --end to stop it
clawdcursor mcp stdio MCP server — editor hosts spawn this; you don't
clawdcursor agent Daemon: HTTP MCP on :3847, optional built-in thin loop
clawdcursor agent --no-llm Daemon, tool surface only (no built-in brain)
clawdcursor stop Stop every running mode
clawdcursor uninstall Remove all config and data
Options: --port <n> (default 3847) · --compact · --no-banner · --provider <name> · --accept
开发
git clone https://github.com/AmrDab/clawdcursor.git && cd clawdcursor
npm install
npm run build # tsc + postbuild → dist/surface/cli.js
npm test # vitest (1,000+ tests)
npm run lint # eslint
npm link # global `clawdcursor` shim (Admin shell on Windows)
测试会在 CI 中使用 Node 20 和 22,在 Ubuntu、macOS 和 Windows 上运行,并包括覆盖率门槛、性能预警以及 npm audit 检查。
技术栈: TypeScript · Node 20+ · nut-js · Playwright · sharp · Express · Model Context Protocol SDK · Zod · commander。
贡献
欢迎提交 PR — 有关开发流程、分支约定以及每项变更都必须通过的测试矩阵,请参阅 CONTRIBUTING.md。请在 issues 中报告 Bug 和功能需求;私密安全报告请通过 SECURITY.md 提交。
许可证
MIT — 请参阅 LICENSE。
致谢
本项目基于 Model Context Protocol SDK、nut-js、Playwright、Anthropic computer_20250124 工具格式,以及 AT-SPI / UIA / AX 树构建,正是这些技术让与应用无关的 GUI 自动化成为可能。
clawdcursor.com · Discord · 更新日志 · npm
评论
一个开放协议,规定了 AI 应用如何以统一方式连接外部工具与数据源。客户端负责与模型对话,MCP 服务负责提供工具、资源和提示模板,两者通过标准消息通信,同一个服务可以被不同客户端复用。