跳转至

计算机使用

通过一个内置的 computer 工具,代理(agent)可以查看并控制 Gateway 自身的桌面或已配对节点的桌面。两种宿主机都使用相同的 computer.act 和 screen.snapshot 契约;CUA 在任一宿主机上都复用相同的 provider 实现。provider 描述符标识了所支持的 v2 action、target、observation 和 delivery 族,因此该工具只暴露该 provider 能忠实执行的能力。坐标 action 绑定到 provider 颁发的参考系;能力足够的 provider 还可以定位窗口和元素、请求后台交付,并返回结构化的效果或拒绝证据。一个支持视觉的模型驱动该表面。

对于 云会话,该工具绑定到会话自身的桌面,而不是搜索配对节点。启用了 Desktop 的 Crabbox worker 会在 web Desktop 面板所显示的同一桌面会话中提供 CUA。它们的私有 computer 端点不会作为普通配对计算机暴露,工具参数也无法更改其节点或 Gateway。

对话还可以在 agent 仍停留在 Gateway 上时附加一个临时 Crabbox。在首次调用 computer 时,选择 environment 工具返回的 environmentId;后续调用会保留该桌面。agent 看到并控制的是聊天侧边栏中显示的同一个桌面。该 environment 必须属于当前对话,并且其租约、连接和已准入的代理运行必须保持有效。附件缺失或已停止时,绝不会将输入重定向到 Gateway 或其他计算机。完整的“在 Crabbox 中打开并展示给我”工作流,请参阅 Cloud Worker Desktop。

在 Desktop 面板中接管云环境会暂停 agent 输入并取消待处理的输入。agent 仍然可以观察屏幕。当被要求恢复时,它可以调用 computer 并传入 action: "take_control",将控制中的查看器切换为仅查看,并捕获一张新的截图。这种显式交接使用已准入运行的现有 computer 控制权限;不需要查看者另行颁发的交接令牌。你可以随时再次接管,也可以自行释放控制。普通输入绝不会自动接管,被打断的 action 也不会重放。接管会使先前的坐标观察和窗口/浏览器观察失效;请在输入前使用返回的截图,或获取一次新的定向观察。此仲裁规则适用于云环境桌面,包括对话附件和云会话,但不适用于普通 Gateway 桌面或已配对节点的桌面。

agent 只发出一个统一命令 computer.act;它无法选择节点如何执行该命令。在 macOS 上,Dashboard → Settings → This Mac → Capabilities 选择节点本地 provider:Peekaboo 是默认选项,并保留现有的进程内坐标 action 路径;CUA 则使用嵌入在 OpenClaw.app 中的驱动守护进程。应用会直接启动该守护进程,因此它继承 OpenClaw 的辅助功能和屏幕录制授权,且应用拥有的节点 worker 通过私有 socket 连接。Windows 和 Linux 可以使用可选的实验性 cua-computer 插件,该插件直接调用打包的 CUA Driver SDK。

Provider 选择绝不会按 action 回退。切换 provider 会关闭活动执行面、轮换 provider 代次,并重新通告节点命令。因此,CUA 失败会变成不可用结果,而不是通过 Peekaboo 静默执行同一 action。

要求

  • Gateway 上有可用的 computer provider,或者有一个已配对且已连接的节点同时通告 computer.act 和 screen.snapshot,并且 screen.snapshot 返回 displayFrameId。
  • macOS 执行端: 已启用应用设置 Allow Computer Control。该设置默认开启;显式选择关闭后会保持关闭。
  • macOS 执行端: 选择 Peekaboo(默认)或 CUA。仅当签名应用包中存在固定版本的驱动时,CUA 才可选;没有该工件的开发构建会显示 driver not bundled。
  • macOS 执行端: 已授予 OpenClaw 辅助功能(Accessibility) 和 屏幕录制(Screen Recording) 权限。原生 Peekaboo 路径还需要 Event Posting 访问权限,以供其 CoreGraphics 输入原语使用。
  • Windows/Linux 执行端: 在 Windows x64/ARM64 或基于 glibc 的 Linux x64/ARM64 上启用随附的 cua-computer 插件。其软件包包含固定版本的 CUA Driver SDK 运行时;无需配置 cua-driver 可执行文件、守护进程或 MCP server。
  • 对于节点,包含 computer.act 的配对更新必须在 Gateway 上获得批准。Gateway 自身的 computer 功能不需要配对节点。
  • 支持视觉的代理模型。
  • 工具策略需要暴露 computer。未配置 profile 时,本地引导流程会选择 Full,但会保留显式的 coding profile,而后者排除 computer。对于 Coding,将 computer 添加到 tools.alsoAllow;普通沙箱代理还需要将其添加到 tools.sandbox.tools.alsoAllow。云会话绑定的桌面包含在其默认沙箱策略中,但显式允许列表和拒绝规则仍然适用。Full 工具选择并不会授予 computer 控制权限。参见 工具 profile。

Gateway 桌面

在 Gateway 主机上启用 cua-computer,并运行针对性的工件检查:

openclaw plugins enable cua-computer
openclaw doctor --lint --only cua-computer/driver-artifacts

Gateway 控制需要显式启用该插件。仅加载插件的默认节点策略会保持 Gateway 控制关闭,并保留配对节点选择。

禁用或重新加载所选 provider 会暂停 computer 准入,并通过 Gateway 的插件重新加载生命周期关闭其原生执行。无关的插件重新加载会让该 computer 继续运行。后续执行会获取新的 provider 代次。

在无头 Linux Gateway 上,启用 托管桌面。此后,computer 控制会使用与 Control UI Desktop 面板相同的 X11 显示和私有 D-Bus 会话。Gateway 会为现有 provider 启动一个私有辅助进程;不需要节点进程或配对。关闭面板不会终止正在进行的 computer 执行。桌面关闭或重启会在替换显示之前关闭该执行,并使其帧和引用失效。

对于现有原生桌面,提供方使用 Gateway 进程的桌面环境和平台权限。可用性取决于该运行时会话;仅有一个正在运行的 Gateway 或可见的 VNC 流并不能证明计算机控制可用。macOS CUA 提供方仍然需要其应用自有的端点。外部 VNC 服务器不会为 CUA 识别本地显示:如果它优先于受管模式,受管计算机路由会报告该不匹配,而不是控制另一个桌面。

内置工具使用托管该代理运行的 Gateway 所持有的 Gateway 桌面。对于配对节点目标,远程 Gateway URL/令牌覆盖仍然受支持。

工具发现会读取已声明能力和记录的运行时健康状态,而不会启动桌面或等待其辅助程序。第一次计算机操作会探测所选 Gateway,并绑定到由此产生的实时提供方代次。仅有声明的操作列表并不意味着桌面已就绪。

对于 RPC 客户端,computer.status 的 probe: false 会执行这种被动读取。probe: true 会准备计算机并等待就绪;省略 probe 会为现有客户端保留该行为。并发探测共享准备过程,辅助程序启动仍受其一分钟超时限制。被动读取永远不会延长桌面的空闲生命周期,也不会重试失败的启动。

Linux Gateway 实机验证

在 Linux 上从构建好的源码检出目录中,安装受管桌面先决条件以及 mousepad,然后运行:

node --import ./scripts/tsx.mjs scripts/dev/computer-use-gateway-live-proof.ts \
  --artifacts /tmp/openclaw-gateway-computer-proof

请使用空的输出目录。该验证会启动一个隔离的 Gateway 和没有配对节点的受管桌面,捕获截图,在 Mousepad 中键入内容并读回文本,然后验证代次栅栏和已加入进程的清理。它不需要模型凭据,并在输出目录中保留截图、一份已编辑日志和 result.json。

添加 --runtime <executable> 可以在另一个运行时(如 Bun)上启动构建好的 Gateway,并在 PATH 中没有 node 的情况下运行该验证。如果 Gateway 或其计算机辅助程序在另一个可执行文件上运行,或任何自有进程运行 Node,验证将失败,并在 result.json 中记录每个自有进程的可执行文件。

computer 代理工具

内置的 computer 工具每次调用执行一个操作。选择 target: "gateway" 表示 Gateway 桌面,或选择 target: "node" 表示配对节点。提供 node 也会选择节点路由。两者都不指定时,第一次调用使用已配置的 Gateway 计算机,否则使用唯一已连接且具备计算机能力的节点。已配置但不可用的 Gateway 计算机将报告其错误;它绝不会静默地将输入重定向到节点。后续调用会保留所选主机,除非显式更改。云会话保留其固定桌面,并拒绝主机覆盖。

坐标是最近截图中的非负整数像素;提供方会将它们映射到显示点。坐标操作必须回显截图结果的 frameId,并且显式的 screenIndex 必须与该帧匹配。OpenClaw 还会将提供方发出的显示标识从截图带入操作中,因此显示重连或几何变化会封闭失败,而不会静默地重新定位到同一索引。这些检查会拒绝猜测的令牌以及来自另一个已交付帧或显示的令牌。令牌不是新鲜度保证:应用可能在捕获后改变同一显示上的像素,因此只要场景可能发生变化,就应重新截图。

  • 读取:screenshot 捕获桌面屏幕并返回 frameId。它不接受窗口、浏览器、元素或观察引用。
  • 指针:left_click、right_click、middle_click、double_click、triple_click、mouse_move、left_click_drag(带 startCoordinate)、left_mouse_down、left_mouse_up。
  • 滚动:scroll 带 scrollDirection(up|down|left|right)和 scrollAmount(滚轮刻度)。
  • 键盘:type(文本)、key(组合键,如 cmd+shift+t 或 Return)、hold_key(text 组合键保持 duration 秒)。
  • 节奏控制:wait(duration 秒),随后跟一张截图。此操作在本地运行,只要所选提供方支持截图即可用;它不需要原生等待命令。

具有 v2 窗口/元素家族的提供方还可以额外暴露 list_apps、list_windows、get_accessibility_tree、get_cursor_position、get_window_state、launch_app、kill_app、bring_to_front、set_value、zoom、escalate_scope 和 invoke_menu。提供方描述符具有权威性;不可用的操作会被省略,而不会通过另一个提供方模拟。

窗口输入坐标遵循观察结果的 details.coordinateSpace。CUA 报告 image-pixels:使用所交付图像中的像素,包括当 OpenClaw 调整其大小时。Peekaboo 报告 global-logical-points:使用桌面逻辑点。无障碍元素边界保留其原生屏幕坐标;在定位这些元素时优先使用 elementRef。浏览器坐标输入使用视口 CSS 像素。

对于窗口图像,请使用带 windowRef 和 includeScreenshot: true 的 get_window_state,然后将返回的 observationId 与窗口输入一起传递。对于 CUA,includeScreenshot: false 会跳过捕获并刷新无障碍元素及其引用。此选择退出需要更新的节点;默认和 true 观察结果仍然与旧节点兼容。使用这些引用进行元素操作;窗口像素输入仍然需要带有所交付图像的观察结果。原生 macOS Peekaboo 提供方拒绝 includeScreenshot: false,因为其窗口观察必须捕获。桌面 frameId 不能替代窗口观察:图像可能使用不同的坐标空间。与 screenshot 类似,wait 返回桌面捕获,并拒绝目标和观察引用。

CUA 提供方还暴露 v2 浏览器家族:get_browser_state、browser_prepare、browser_navigate、browser_click、browser_type、browser_dialog、browser_set_input_files、browser_download 和 browser_pointer。使用 list_windows 发现原生浏览器的 windowRef,然后将其传递给 get_browser_state 以获取不透明的 browserRef 和页面引用。后续的 get_browser_state 页面快照和浏览器操作要求同时提供 browserRef 和 pageRef;快照会返回输入所需的观察结果和元素引用。browser_prepare 也要求使用已发现的 windowRef,即使对于隔离配置文件也是如此。这些引用属于一次 Computer Use 执行和驱动代次;导航会使页面元素观察失效,而驱动重启会使完整的浏览器引用集失效。

CUA 额外暴露 get_recording_state、start_recording、stop_recording 和 replay_trajectory。录制和浏览器文件操作使用不透明的 openclaw:computer-resource 句柄。选定的计算机主机创建并验证底层文件和目录;代理操作从不接受原生路径、输出根目录或辅助可执行文件路径。句柄属于一次 Computer Use 执行,不能被另一执行复用。

在 macOS Peekaboo 提供商上,屏幕坐标滚动使用在请求坐标或当前指针处的前台滚轮输入。后台滚动需要来自其当前观察的窗口和一个元素;它从不回退到全局滚轮输入。

修饰键通过点击和滚动操作中的 text 字段传递(shift、ctrl、alt、cmd)。窗口输入后,支持 get_window_state 的提供商返回操作结果,随后返回新的窗口观察。使用该观察的 observationId 和元素引用执行下一个操作;无需单独的观察调用。如果后续失败,原始操作结果仍然可见:在再次变更前重新观察,而不重复输入。浏览器操作仍需要单独的浏览器观察。

其他输入操作返回新的桌面截图,以便模型观察结果。当屏幕与模型上下文中仍保留的上一帧逐像素相同时,工具仅返回元数据——“自上一帧以来屏幕未变化”——并且之前的 frameId 保持有效,因此重复截图不会重新进入模型上下文。如果连接了多个具备计算机能力的节点,请显式传递 node。

截图保持仅限模型:它们永远不会自动发送到聊天频道。将所有屏幕内容视为不可信输入;工具会警告模型不要遵循与用户请求冲突的屏幕指令。

CUA Driver 提供商

macOS 应用拥有的守护进程

签名的 macOS 应用捆绑了固定版本的通用 cua-driver 可执行文件,并在 Computer Control 提供商选择器中提供 CUA。OpenClaw 在 Application Support 下创建私有、仅属主可访问的套接字目录,并将 cua-driver serve --embedded 作为应用的直接子进程启动。它不通过 Gateway、TypeScript 工作进程、open(1) 或 NSWorkspace 启动;这些路径会破坏 macOS 的 TCC 责任链并创建第二个权限身份。

应用会等待私有套接字接受连接,然后才宣告 CUA 就绪。其 TypeScript 节点工作进程仅针对该套接字启动非特权 MCP 代理,并映射其他平台使用的相同类型化 computer.act v2 操作。权限变更会重启守护进程,而提供商变更、禁用 Computer Control、应用关闭或意外的子进程退出会移除已宣告的 CUA 命令,直到新一代就绪。

信任模型

Gateway 是授权瓶颈;驱动程序是一个简单执行器。OpenClaw 有意保持守护进程未设限,并在其上方通过工具暴露、危险命令允许列表、设备和命令配对审批、节点本地提供商启用以及操作系统权限来授权计算机使用。这与随附的 Peekaboo 执行器使用的授权边界相同。

固定版本的 CUA Driver 在运行时启动时固定其权限模式和有界清单。精确的 PID/窗口授权以及任何应用范围的窗口授权都必须在该启动批准的清单中声明;ask 条目对于无人值守调度是硬性拒绝。OpenClaw 转而驱动代理运行时发现的应用、窗口和元素。因此,有界模式无法在不复制 Gateway 策略或预先授权广泛应用程序类别的情况下表达此提供商模型,所以应用以不受限模式启动其托管守护进程,并绕过审批。

computer.act 节点调用策略在传输分发前对精确参数进行分类。强制终止应用、浏览器导航、浏览器下载、浏览器文件输入、开始录制、轨迹回放和桌面范围升级是不同的高风险类别;普通观察和输入仍然相互独立。分类不会增加逐操作提示,也不会削弱命令级门控:每个操作仍然需要相同的已暴露工具、已启用命令、已批准配对、已启用节点提供商和操作系统权限。

托管端点不是模型契约的一部分。CUA 插件不注册任何模型工具、CLI 命令、服务或原始 node-MCP 描述符,其操作架构不接受辅助二进制文件、套接字、原生会话、驱动程序参数或提供商工具名称。在 macOS 上,只有应用拥有的工作进程接收该端点,而节点 shell 执行通过应用主机路由,不包含该仅限工作进程的值。这些边界可防止 OpenClaw 模型操作选择通往托管守护进程的替代路径。

CUA 以 0600 模式创建 Unix 套接字,OpenClaw 将其放置在随机的仅属主可访问的 0700 目录中。这排除了远程客户端和其他本地用户。它不会认证或以沙箱隔离以同一登录用户身份运行的进程:这些进程位于此边界内部,可能能够发现并使用同一用户的资源。不受限 CUA 模式无法遏制被入侵的用户账户。更强的同用户隔离需要继承的连接式 IPC 或由操作系统强制实施的进程边界。

回环也是可达性,而非身份:机器上的任何进程都可以连接到 127.0.0.1。因此,Gateway 客户端不会仅因为通过回环到达就获得 operator.write。它必须通过身份验证并通过 Gateway 的设备配对和范围审批;如果没有单独受信任的本地或共享凭据,另一个已授权设备必须批准所请求的操作员范围。驱动程序及其套接字从不做出该决定。

CUA 描述符宣告窗口、元素和浏览器目标;后台和前台投递;图像、辅助功能和浏览器观察;以及录制。Peekaboo 仍然是默认提供商,且不宣告录制。

CUA 桌面输入使用前台桌面路由。deliveryMode 仅为窗口目标输入选择路由;在桌面操作上切换它不会改变该操作的投递方式。桌面结果保留原生效果和升级证据,标识其桌面作用域,并指示请求的投递模式何时不适用。已确认的输入并非应用已响应的证明:在重复之前,请验证预期的可见变化。

固定的 CUA 驱动程序支持按键点按,不支持持续键盘按住。Linux X11 按键点按包含一个短按间隔,以便轮询按键状态的应用程序能够观察到它们。其 Linux left_mouse_down 和 left_mouse_up 操作需要一个带有 windowRef 和当前包含图像的 observationId 的后台窗口像素目标;桌面目标和元素目标不支持这些按住操作。仅使用所选节点公开的操作。对于交互式应用,在尝试更长的任务之前,先验证移动、激活或其他预期控制是否改变了观察到的状态。

浏览器配置文件

browser_prepare 可以启动一个由驱动程序拥有的独立 Chromium 进程,使用新的临时配置文件或命名的隔离配置文件。它从不修改、复制、终止或附加到所选浏览器的现有配置文件。此适配器不公开现有配置文件/CDP 附加;浏览器准备仅限于隔离配置文件。

浏览器目标、页面、页面元素和对话框是不透明能力。在导航、重连或过期引用拒绝之后,重新获取浏览器状态。适配器从不向模型返回提供商原生的 CDP 目标 ID、标签页 ID 或页面引用。

维护者实时验证装置

该仓库包含一个开发测试装置,它保留真实垂直路径:面向代理的 computer 工具、Gateway node.invoke、配对节点以及所选的节点本地提供商。它有意与操作员应用和 Gateway 隔离。macOS 路径使用签名应用节点;Linux 路径在真实 X11 会话中使用可选加入的 cua-computer 插件。

两条路径都会在私有配置文件中生成一个新的仅用于验证的令牌:隔离 Gateway 使用 gateway.auth.token,应用或节点使用 gateway.remote.token。Gateway 使用 --auth token --bind loopback 启动。该装置清除继承的 Gateway 凭据、URL/端口覆盖以及配置/状态/配置文件覆盖,因此操作员设置无法替换验证设置。令牌从不出现在发出的命令或 rig.json 中;不要将生成的配置或整个临时目录作为证明发布。

macOS

从干净且已提交的检出构建签名应用,选择一个新配置文件和非默认回环端口,并准备两个配置视图:

scratch="$(mktemp -d /tmp/openclaw-cu-live.XXXXXX)"
scripts/dev/computer-use-macos-live-rig.sh prepare \
  cu-live-proof 29431 "$PWD/dist/OpenClaw.app" "$scratch" peekaboo

在单独的终端中运行发出的 gateway 和 app 命令。拆分配置是有意为之:外部启动的守护进程读取带有 gateway.mode: "local" 的临时配置,而应用配置文件读取 gateway.mode: "remote"、直接传输以及守护进程的回环 URL。如果应用读取本地模式,其 Port Guardian 将拥有该路由,而不是加入外部守护进程。该装置将其经过验证的启动字段保存在不可执行的 rig.json 中;后续命令会拒绝未知字段或与临时/配置文件布局不匹配的路径。它还初始化一个专用的 node 身份、已完成的新手引导、未暂停状态、Computer Control 以及用于启动调试节点工作进程的检出路径。没有单独的节点模式切换。

在第三个终端中,重新运行发出的 nodes 命令,直到配对条目已连接并通告 computer.act 以及一个 computerUse 描述符。不涉及操作员设备批准步骤:只读 CLI 不会在新的 cli-state 中创建身份,并且验证令牌会认证其回环操作员调用。验证运行器在单独的 agent-state 中使用同一令牌作为本地后端客户端,保留 operator.write。节点设备身份和配对检查保持启用;不要复制身份或禁用设备认证来引导该装置。

如果节点的命令界面仍处于待批准状态,请从该 nodes 输出中获取 .pending[0].requestId,并运行 scripts/dev/computer-use-macos-live-rig.sh approve "$scratch" <request-id>。

将一个无害的可编辑测试窗口放在另一个前台应用后面,然后运行垂直路径:

scripts/dev/computer-use-macos-live-rig.sh proof \
  "$scratch" peekaboo "Computer Use Fixture" "background proof" "Editor"

验证运行器首先要求唯一已连接的计算机节点通告所请求的提供商,然后执行 screenshot、list_windows、get_window_state、后台元素点击和输入,并重新观察窗口。它在临时目录下保存结构化结果和目标窗口的前后图像,并且除非提供商匹配、目标初始为非前台、前台应用和光标保持不变、目标内容已更改,并且最终效果已确认或为结构化拒绝,否则失败。使用另一个提供商重启隔离应用,并重新运行同一验证。不要在此装置中使用端口 18789、默认配置文件或 /Applications/OpenClaw.app。

通过 Crabbox 的 Linux X11

在 Crabbox Linux 主机上运行 Linux 验证,而不是在 macOS 容器中运行。由于 Xvfb 是真实的 X11 服务器,带有 Xvfb 的直接 AWS Crabbox 租约就足够了;macOS 上的本地容器不是远程 Linux 桌面验证。在一次性主机上安装 X11 测试夹具的前置条件,然后启动一个隔离会话:

sudo apt-get update
sudo apt-get install -y at-spi2-core dbus-x11 gir1.2-gtk-3.0 jq openbox python3-gi x11-utils xdotool xvfb

dbus-run-session -- bash

dbus-run-session -- bash 会打开一个嵌套 shell,因此上面的代码块到此为止。 在该新 shell 中运行以下所有内容:

export DISPLAY=:99 XDG_SESSION_TYPE=x11 NO_AT_BRIDGE=0
Xvfb "$DISPLAY" -screen 0 1280x800x24 -nolisten tcp &
openbox >/tmp/openclaw-cu-openbox.log 2>&1 &

scratch="$(mktemp -d /tmp/openclaw-cu-live.XXXXXX)"
scripts/dev/computer-use-macos-live-rig.sh prepare-linux \
  cu-linux-live-proof 29431 "$scratch"

在继承相同 DISPLAY 和 DBUS_SESSION_BUS_ADDRESS 的独立窗格中,运行生成的 gateway、node 和 fixture 命令。隔离配置共享一个仅 scratch 的随机 Gateway token,并且 gateway 会静默批准回环 node-device 配对。node 命令面仍需要显式批准:在 node 完成重连后运行生成的 nodes 命令,读取 .pending[0].requestId,并将其传递给 scripts/dev/computer-use-macos-live-rig.sh approve "$scratch" <request-id>。重复运行 nodes,直到恰好有一个已连接 node 通告 provider.id: "cua-computer"。

对非最前面的 GTK fixture 运行相同的 proof 运行器:

scripts/dev/computer-use-macos-live-rig.sh proof \
  "$scratch" cua "OpenClaw CUA X11 Target" "W3-LINUX CONFIRMED"

结果以及 window-before.png / window-after.png 会保留在 scratch 目录下。已确认的 mutation 必须保持 sentinel 作为活动 X11 窗口,并保持指针不变。上游 background_unavailable 或 background_occluded 结果只有在保持结构化且未尝试前台重试时,才是有效的拒绝证据。rig 会拒绝原生 Wayland,即使 DISPLAY 也同时存在用于 XWayland;应切换到 X11,而不是声称 Wayland 覆盖。

在任一 proof 之后,只停止你为 rig 启动的 Gateway、app/node 和 fixture 进程。只保留已检查的 proof 结果和合成捕获,然后删除任务拥有的 scratch 目录。在 macOS 上,还要删除新的 proof profile 目录(~/.openclaw-<profile>)及其 ai.openclaw.mac.profile.<profile> defaults 域。切勿清理 operator profile 或 Gateway。

Windows 和 Linux(实验性,直接 SDK)

捆绑的 cua-computer 插件默认在每个平台上加载其 Gateway 策略。在 Windows 和 Linux 上,本地计算机控制仍为可选启用;仅加载策略不会启动原生 driver、注册本地计算机命令或检查本地 driver 产物。macOS 保留其默认的 CUA 集成,使用 app 拥有的 daemon。显式禁用该插件也会禁用其 cloud computer 策略。

要启用实验性的 Windows 或 Linux node fulfiller(它直接使用固定的 CUA Driver SDK 契约):

  1. 启用插件:
openclaw plugins enable cua-computer
  1. 在启动 node 之前,验证 node 本地 SDK 包:
openclaw doctor --lint --only cua-computer/driver-artifacts

OpenClaw 会检查 SDK 包版本、所选 OS/CPU 包版本、常规文件身份,以及原生库和 Node 运行时固定的 SHA-256 摘要。干净的检查会打印 no findings。如果它报告 COMPUTER_DRIVER_* 错误,请在此 node 主机上重新安装或更新 OpenClaw,然后再次运行检查。不要下载独立的 cua-driver 可执行文件,也不要将其添加到 PATH;Windows 和 Linux 使用通过 npm 安装的进程内 SDK。

  1. 从交互式桌面会话启动 openclaw node run。插件会在 node 首次能力声明之前重复验证 artifacts 并确定 SDK 可用性。它会延迟为每个 provider 执行创建一个已配置的 SDK 运行时和一个受信任生命周期会话。窗口和桌面目标按 action 提供;escalate_scope 读取现有会话状态,而不会扩大其权限。完成、取消、Gateway 断开、provider 切换、本地 Stop 以及 command-host 关闭都会关闭该确切执行,最终化或丢弃其录制资源,关闭其会话,并关闭其运行时。

  2. 批准包含 computer.act 的配对更新。桌面 computer.act 是内置平台默认项,因此插件启用加上该批准即为完整授权;不需要 gateway.nodes.commands.allow 条目。希望关闭该命令的 operator 可以拒绝它:

{
  gateway: {
    nodes: { commands: { deny: ["computer.act"] } },
  },
}

被拒绝的命令会与其 computer 能力一起从 node 的通告面中隐藏,Gateway 会记录它隐藏了哪些命令。

该 fulfiller 目前仅控制主显示器。hold_key、left_mouse_down 和 left_mouse_up 不可用,因为 CUA Driver SDK 没有桌面范围的 held-input 契约。按住修饰键的点击、滚动和拖拽会被拒绝,因为类型化桌面方法不接受修饰键。key action 接受命名键、字母和修饰键组合(例如 cmd+c 或 Return);数字和标点键会被拒绝,因为 driver 会丢弃其依赖布局的 shift 状态,因此请改用 type action 发送该文本。每次 node 调用都会将取消传递给 SDK。

插件调用 CuaDriver.createConfigured,从不直接调用 create()。其授权上限、受信任会话身份、TTL 和 action 目标由 OpenClaw 拥有;面向模型的 screen.snapshot 和 computer.act 输入不能选择原生会话或扩大其权限。由于 driver 不报告稳定的显示器身份,frame 授权绑定到受信任会话代加上实时主显示器几何。延迟加载 SDK 不会改变该代,因此 list_windows 可以是新执行中的第一个 action。新会话会使未决 frame 失效,但在同一会话内以相同几何替换主显示器无法被检测;对于该 fulfiller,请优先使用稳定的单显示器会话。

在 Windows 和 Linux 上,这取代了以前的 0.10 daemon/MCP 集成:node 主机直接调用 SDK,Gateway 在其私有桌面 helper 中加载同一 provider。两者都不会启动独立的 cua-driver daemon,也不会代理 MCP 客户端。macOS 有意使用上述 app 拥有的嵌入式 daemon,以便 driver 保持在 OpenClaw.app 的 TCC 责任链中。对于单个 action,两条路径都不会回退到另一个 provider。

已接受的驱动记录位于 cua-computer 包中,并提供 npm 原生文件摘要和 macOS 归档摘要。更新 OpenClaw 会同时更新该记录和 SDK 包。由于这些主机上没有单独的驱动安装,因此没有独立的 Windows/Linux 驱动更新器或回滚目录;回滚时,请安装上一个已知良好的 OpenClaw 包,然后在重启节点前重新运行针对性 doctor 检查。

更新会保留现有桌面配置、显式插件启用或禁用状态,以及节点配对。Gateway 计算机支持不会更改现有节点命令契约,也不会自动启用本地 CUA 控制。

computer.act 节点命令

computer.act 是工具将输入路由经过的唯一节点命令(node.invoke 且 command: "computer.act")。它:

  • 本地启用:节点仅在 Computer Control 启用期间通告它。Gateway 可以在配对时一次性批准该通告表面。
  • 基于能力:工具要求已连接节点同时通告 computer.act 和 screen.snapshot。捆绑的 macOS 应用和可选的实验性 cua-computer 插件满足同一命令对。

Provider 描述符声明 contractVersion: 2。无效的能力描述符或 computer.act 结果信封会以 COMPUTER_CONTRACT_MISMATCH 被拒绝。

对由 provider 支持的 computer.act 命令的直接 node.invoke 调用必须在操作参数中包含 executionId UUID。内置 computer 工具会自动提供它。

对于 CUA,请对前面的 screen.snapshot 调用使用相同的 executionId。将其 displayFrameId 复制到操作中,并将其返回的 width 复制到 refWidth;坐标指该返回位图内的像素。CUA 将图像的两个维度限制为 maxWidth,但不会放大较小的显示,因此直接快照和内置工具共享同一坐标空间。

没有 executionId 的 CUA 快照是独立捕获:其临时执行在捕获后关闭,并且不能授权后续输入。

读取复用 screen.snapshot;没有第二个捕获路径。有关共享捕获命令,请参阅 相机和屏幕节点。

授权

  1. 启用平台 fulfiller:在 macOS 上,Dashboard → Settings → This Mac → Capabilities → Allow Computer Control 默认启用,然后选择 Peekaboo 或 CUA,并在 This Mac → Permissions 下授予 Accessibility 和 Screen Recording;在 Windows/Linux 上,遵循上述实验性 cua-computer 设置。
  2. 对于节点目标,请在 Gateway 上批准配对更新(新命令会强制重新配对)。Gateway 目标使用其本地启用的 provider,无需节点配对。
  3. 将该工具暴露给具备视觉能力的 agent。对于显式 coding profile:
{
  tools: {
    alsoAllow: ["computer"],
    // Sandboxed agents need this second gate too:
    sandbox: { tools: { alsoAllow: ["computer"] } },
  },
}

一旦节点本地控制启用且配对更新被批准,只要节点继续通告 computer.act,它就持久可用。没有租约、过期或 arm/disarm 命令。在本地禁用 Computer Control 会移除已通告的命令,并且节点在调用时重新检查该开关。

在 macOS 上,默认启用意味着已配对的 Gateway 在所需的 macOS 授权存在后,即可驱动指针和键盘输入。没有逐操作确认。在配对之前或之后的任何时间关闭 Allow Computer Control,即可停止通告并接受 computer.act。

gateway.nodes.commands.deny 仍然是显式全局撤销,并且始终优先;被拒绝的 computer.act 会与其 computer 能力一起从节点的通告表面中保留,并且 Gateway 会记录其保留的内容。任何 fulfiller 都不需要 gateway.nodes.commands.allow 条目:computer.act 是内置桌面平台默认项,因此节点本地启用加上配对批准就是所有平台上对任一 fulfiller 的完整授权。具有 operator.write 的已认证 operator 可以通过 node.invoke 调用已启用、已配对的命令;没有逐操作管理员检查。

安全

  • 工具策略、本地 provider 启用状态和平台权限必须一致。节点目标还要求 Gateway 命令策略、配对和节点应用设置。在 macOS 上,这包括 Allow Computer Control、Accessibility 和 Screen Recording;原生 Peekaboo 路径还要求 Event Posting。只要这些持久控制保持启用,操作就会执行;没有逐操作确认。
  • macOS fulfiller 一次发送一个字素的文本,因此取消、断开连接、暂停、禁用或端点替换会在下一个字素之前停止它。实验性 CUA Driver fulfiller 会将节点取消传递给每次调用的 SDK。
  • 在 macOS 上,捕获和输入需要已验证的已解锁桌面。临时保持唤醒覆盖活跃的 Computer 执行(包括后台操作),最长一小时。手动锁定、注销或未知状态会释放断言并终止执行;之后的解锁需要新的执行。可选的 保持计算机唤醒 可在任务之间保持已连接主机唤醒,而不更改持久 macOS 电源或锁定设置。
  • CUA 录制、回放、浏览器上传和浏览器下载路径属于所选计算机主机。模型仅接收不透明的执行范围资源句柄;遍历、绝对路径、符号链接逃逸和 helper 选择会在驱动分发之前被拒绝。
  • 屏幕截图仅供模型使用,且永远不会自动发送到聊天(issue #44759)。
  • 将屏幕内容视为不可信;它可能携带 prompt injection。

故障排除

Gateway 计算机不可用

在 Gateway 主机上启用 cua-computer,验证针对性 artifact 检查,并检查 Gateway 日志中 provider 的启动错误。对于受管理的 Linux 桌面,安装所需的 TigerVNC、XFCE 和 D-Bus 二进制文件,并确认外部 VNC 监听器未选择 attach 模式。对于现有桌面,确保 Gateway 在预期的图形会话中启动,并带有其显示环境和权限。仅启用 Desktop 面板不会启用 CUA。

如果意图是控制已配对的桌面,请显式选择 target: "node" 及其 node。不可用的 Gateway 目标绝不会将可能已完成的操作重定向到另一台计算机。

CUA Driver 错误代码

cua-computer 执行器会在工具结果和所选主机的日志中呈现类型化错误代码。常见代码如下:

代码 原因 修复
COMPUTER_DRIVER_UNAVAILABLE CUA 运行时无法初始化,macOS 应用拥有的端点缺失,或桌面权限/会话不可用。 在 macOS 上,确认已选择 CUA 且捆绑的驱动程序已就绪;在 Windows/Linux 上,在交互式桌面会话中运行 openclaw node run。如果固定的运行时缺失,请重新安装 OpenClaw。
COMPUTER_DRIVER_PACKAGE_MISSING 固定的 SDK 包、操作系统/CPU 原生包、原生库或 Node 运行时缺失或不可读。 在节点主机上重新安装 OpenClaw,重新运行 openclaw doctor --lint --only cua-computer/driver-artifacts,然后重启节点。
COMPUTER_DRIVER_VERSION_MISMATCH SDK 包或所选原生包与固定版本不匹配。 更新或重新安装 OpenClaw,使两个包来自同一发布版本;重新运行针对性的 doctor 检查。
COMPUTER_DRIVER_DIGEST_MISMATCH 原生 SDK 库或 Node 运行时不是常规包文件,或与其固定的 SHA-256 摘要不匹配。 不要手动运行或替换该文件。重新安装 OpenClaw,重新运行针对性的 doctor 检查,然后重启节点。
COMPUTER_DRIVER_PLATFORM_UNSUPPORTED 节点主机没有固定版本的原生 SDK 包,例如 musl Linux 或不支持的 CPU 架构。 对于此 provider,请使用 Windows x64/ARM64 或基于 glibc 的 Linux x64/ARM64。
COMPUTER_REFUSED_<code> 驱动程序使用结构化代码拒绝了该操作,例如 background_unavailable、background_occluded 或 foreground_unavailable(KDE/KWin Wayland)。 将目标窗口置于前台,切换到 X11,或使用受支持的合成器。参见上述兼容性说明。
COMPUTER_STALE_FRAME 坐标引用了不再有效的截图(上下文压缩、显示几何变化或参考宽度变化)。 在执行坐标操作前,重新获取一张 screenshot。
COMPUTER_STALE_OBSERVATION 窗口或浏览器引用属于较早的观察、导航、执行或驱动程序代际。 再次运行 get_window_state 或 get_browser_state,并使用新的不透明引用重试。
COMPUTER_UNSUPPORTED_ACTION 此执行器无法可靠执行的操作:hold_key、left_mouse_down、left_mouse_up,或按住修饰键的点击/拖拽/滚动。 使用受支持的操作。类型化 CUA Driver 桌面契约在这些调用中没有按住输入或修饰键参数。
COMPUTER_UNSUPPORTED_DISPLAY 非主 screenIndex、捕获/屏幕几何不匹配,或光标位于主显示器之外。 仅操作主显示器。
COMPUTER_UNSUPPORTED_KEY 驱动程序无法可靠复现的 key 值:其 Shift 状态取决于布局的数字或标点键,或未知键。 改为通过 type 操作发送该文本。
COMPUTER_DRIVER_ERROR / COMPUTER_INVALID_REQUEST 驱动程序失败但没有结构化代码,或操作参数格式错误。 检查驱动程序状态并重新截取屏幕截图;更正操作参数。
代码 原因 修复

桌面流

对于已断开的 web Desktop 面板,请检查 Gateway 日志 中的 desktop observer closed 和 node stream closed,以及节点日志中的 node stream closed。这些记录将首次本地清理 trigger 与观察到的 WebSocket closeCode 区分开;观察者记录还包括请求的 cleanupCode。

仅有 closeCode 为 1006 并不能确定是网络或代理故障:有意的所有者拆除也可能产生该代码。请比较 Gateway 和节点之间的触发器以及可用的来源/连接标识。这些记录省略了对等方关闭原因文本、观察者令牌、附加票据、凭据和桌面负载。

macOS 桌面可用性

如果 Desktop 面板报告 此 Mac 已锁定 或显示其锁定状态未知,请检查 仪表盘 → 设置 → 此 Mac → 桌面可用性。 OpenClaw 独立于可选的活动共享报告原生会话状态;已连接的节点或捕获的壁纸都不能证明桌面已解锁。

Screen Sharing 在正常登录期间保持连接。通过 Mac 的正常登录屏幕或本地解锁 Mac,然后启动新的 Computer 执行;旧执行不会恢复。如果 macOS 从查看器中省略其安全登录控件,请使用受支持的本地或远程登录路径。OpenClaw 的可用性报告不会改变 macOS 捕获该安全屏幕的方式。

对于应在任务之间保持唤醒的专用 Mac,请在 仪表盘 → 设置 → 此 Mac 中显式启用 保持计算机唤醒。它仍受当前连接、托管和已解锁会话要求约束。 当最后一个查看器断开连接时,Screen Sharing 可能会请求立即锁定;即使启用了 保持计算机唤醒,OpenClaw 也会遵循该锁定。Web Desktop 查看器不会创建 OpenClaw 保持唤醒执行。 参见 桌面可用性和保持唤醒。

macOS 权限

仪表盘 → 设置 → 此 Mac → 功能 中的 Computer Control 状态会分别检查辅助功能、事件发布和屏幕录制。由于 macOS 将这些授权存储在单独的 TCC 桶中,屏幕捕获可以正常工作,而输入仍被拒绝。

如果状态显示 辅助功能授权可能已过期,即使 macOS 拒绝它,OpenClaw 在 系统设置 → 隐私与安全性 → 辅助功能 下也可能已显示为启用。当辅助功能条目固定到较旧的应用程序构建时,就会出现这种情况。在该列表中选择 OpenClaw,使用 − 将其移除,然后重新添加 /Applications/OpenClaw.app。更改授权后,请退出并重新打开 OpenClaw,因为 macOS 可能会在进程生命周期内缓存辅助功能信任。

与其他桌面控制路径的关系

这是由代理驱动的路径。有关它与 PeekabooBridge 宿主的关系,请参见 Peekaboo 桥、Codex Computer Use 以及直接的 cua-driver MCP。

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw