mcpField
C
Clawd Cursor

Clawd Cursor

本地服务
github.com/AmrDab开发工具406今天更新

关于 Clawd Cursor

Clawd Cursor 是供 Agent 操作 Windows、macOS 或 Linux 桌面界面的本地 MCP 服务。它将无障碍信息和 OCR 整合为 UI 映射,验证操作,并通过统一安全关卡处理调用。

主要功能

  1. 01跨平台桌面控制
  2. 02无障碍信息与 OCR UI 映射
  3. 03用于屏幕交互的视觉回退
  4. 04操作验证
  5. 05允许、确认或阻止的安全关卡
  6. 06暂停并等待人工输入

适用场景

  1. 01自动化原生桌面应用
  2. 02操作没有公开 API 的图形界面
  3. 03在登录或 2FA 时暂停自动化
  4. 04验证重要的点击和输入

MCP 相关

Clawd Cursor 通过 MCP 工具向兼容 Agent 提供桌面控制能力。本地服务会对工具调用执行统一安全检查,并可暂停以等待人工输入。

配置

本地服务的配置在各客户端中通用,复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置
{
"mcpServers": {
"clawdcursor": {
"command": "npx",
"args": [
"-y",
"clawdcursor"
]
}
}
}
启动命令npx -y clawdcursor

本地服务需要在你的电脑上安装运行环境(如 Node.js 18+)。各客户端的配置文件位置不同,请参考客户端文档。

安装包
npmclawdcursor1.5.23

工具

还没有获取到工具列表

本地服务需要在你的电脑上运行后才能读取工具,维护者暂未提供工具列表。

详细介绍

Clawd Cursor

为任何 AI Agent 提供安全的桌面控制。将屏幕编译为 UI 映射,并通过稳定 ID 操作元素(仅在最后手段下使用截图/视觉识别),
验证自身操作,并通过一个安全检查点来把关所有操作。本地 · 跨操作系统 · 适用于任何模型。

MIT 许可证 最新版本 npm Node 20+ 跨平台 Glama 上的 clawdcursor MCP 服务 测试 Discord

快速开始 · 最新动态 · 与众不同之处 · 引擎 · 工作原理 · 工具 · 平台 · 更新日志


最新动态

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 Cursorbrowser-usePlaywright MCPOmniParser / UI-TARScomputer-use
适用于任何桌面应用,而不只是 Web✅仅限 Web仅限 Web✅✅
跨操作系统(Windows + macOS + Linux)✅——不一沙盒
无需视觉模型的感知✅ 编译后的 a11y + OCR 地图DOMa11y 树❌ 以视觉为核心❌ 视觉
验证自身操作(偏差)✅————
单一安全关卡(允许/确认/阻止)✅————
任何模型 / 供应商✅✅不是 Agent特定模型仅限 Claude
原生支持 MCP(一个配置,适用于任何宿主)✅库测试框架—工具调用 API
仅限本地运行,无需云端✅✅✅需要模型屏幕 → 云端

这里有三项确实很少见:

  1. 优先使用成本最低的感知方式,完全本地运行。 无障碍树(免费)→ OCR(便宜)→ 截图(昂贵 — 只有这一层会把像素放进模型的上下文;“截图”和“视觉”是同一步骤)。Agent 只在必要时才升级,因此令牌成本会随任务难度变化 — 使用本地模型时,任何数据都不会离开设备。以视觉为核心的 Agent(OmniParser、UI-TARS)每次观察都需要把截图传给模型。
  2. 它会验证。 对重要操作传入 expect 后,Clawd Cursor 会重新检查实时屏幕(为异步 UI 留出短暂的稳定等待时间),并在发现偏差时报告 DEVIATION,而不是给出空洞的“成功”。不能仅凭操作前就已成立的证据,将任务标记为完成。
  3. 一道安全关卡。 每次调用 — 无论来自通过 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 会安装它:

WindowsmacOSLinux
clawdcursor-win32.mcpbclawdcursor-darwin.mcpbclawdcursor-linux.mcpb
  1. 双击该文件(或前往 Settings → Extensions → Advanced settings → Install Extension… 并选择该文件)。
  2. 开启 Allow clawdcursor to control this computer — 这是一次性的桌面控制授权;开启之前,每个工具都会返回授权提示。
  3. 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):

添加到 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_NN ID。通过 {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 配置的 LLMtask / 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 查看。

工具箱操作
computerscreenshot、click、double_click、right_click、triple_click、hover、move、scroll、scroll_horizontal、drag、drag_path、type、key、wait
accessibilityread_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
windowlist、active、focus、maximize、minimize、restore、close、resize、list_displays、screen_size、open_app、open_file、open_url、switch_tab、navigate
systemcopy_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
browserconnect、page_context、read_text、click、type、select_option、evaluate、wait_for、list_tabs、switch_tab、scroll
taskrun(默认;有界同步——最多等待 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 OCRobs·ocr低system.ocr、smart_read / smart_click / smart_type无障碍树为空或内容稀疏时。提取操作系统级文本,不产生图像字节。
T3 DOMobs·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 桥接使用 UIAWindows.Media.OcrChrome / Edgenut-js
macOS 12+(Intel / Apple Silicon)原生 AX 助手(Swift),JXA 回退方案Apple VisionChrome / Edgenut-js + System Events
Linux X11通过 python3-gi 使用 AT-SPITesseractChrome / Edgenut-js
Linux Wayland通过 python3-gi 使用 AT-SPITesseractChrome / Edgeydotool / 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、UIA IsPassword=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

评论

支持 Markdown

第一次接触 MCP?

从协议是什么,到在客户端里装上第一个服务,这几条回答覆盖了大多数入门问题。

一个开放协议,规定了 AI 应用如何以统一方式连接外部工具与数据源。客户端负责与模型对话,MCP 服务负责提供工具、资源和提示模板,两者通过标准消息通信,同一个服务可以被不同客户端复用。