计算机使用

计算机使用功能让代理能够通过一个内置的 computer 工具查看并控制 Gateway 自身的桌面或已配对节点的桌面。两个主机都使用相同的 computer.act 和 screen.snapshot 契约；CUA 在任一主机上复用相同的 provider 实现。provider 的描述符会标识所支持的 v2 action、target、observation 和 delivery 族，因此该工具只暴露该 provider 能够忠实执行的内容。坐标操作绑定到由 provider 签发的参考坐标系；具备相应能力的 provider 还可以寻址窗口和元素、请求后台投递，并返回结构化的效果或拒绝证据。具备视觉能力的模型驱动该界面。

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

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

在 Desktop 面板中接管云环境会暂停代理输入并取消待处理输入。代理仍可以观察屏幕。当被要求恢复时，它可以调用 computer 并传入 action: "take_control"，将控制方查看器切换为仅查看模式并截取一张新的屏幕截图。这种显式交接使用已准入运行现有的计算机控制权限；它不需要单独的由查看器签发的交接令牌。你可以随时再次接管，也可以自行释放控制。普通输入永远不会自动接管，被中断的操作也不会重放。接管会使之前的坐标和窗口/浏览器观察失效；在输入之前，请使用返回的屏幕截图或进行一次新的针对性观察。此仲裁适用于云环境桌面，包括对话附加项和云会话，而不适用于普通 Gateway 或已配对节点桌面。

代理发出一个统一命令 computer.act；它无法选择节点如何执行该命令。在 macOS 上，仪表盘 → 设置 → 此 Mac → 功能 用于选择节点本地 provider：Peekaboo 是默认选项，并保留现有的进程内坐标操作路径，而 CUA 使用嵌入在 OpenClaw.app 中的 driver 守护进程。该应用会直接生成该守护进程，使其继承 OpenClaw 的辅助功能和屏幕录制授权，并且由应用拥有的节点工作器通过私有套接字连接。Windows 和 Linux 可以使用可选的实验性 cua-computer 插件，该插件直接调用打包的 CUA Driver SDK。

provider 选择绝不会按操作回退。切换 provider 会关闭当前活动执行面，轮换 provider 代际，并重新通告节点命令。因此，CUA 失败会变为不可用结果，而不是静默地通过 Peekaboo 运行同一操作。

需求¶

• Gateway 上可用的 computer provider，或一个已配对且已连接的节点，该节点同时通告 computer.act 和 screen.snapshot，并且 screen.snapshot 返回 displayFrameId。
• macOS 执行方： 应用设置 允许计算机控制 已启用。它默认开启；显式关闭的选择会保持关闭。
• macOS 执行方： 选择 Peekaboo（默认）或 CUA。只有当固定版本的 driver 存在于已签名的应用包中时，CUA 才可选择；缺少该产物的开发构建会显示 未捆绑 driver。
• macOS 执行方： 已授予 OpenClaw 辅助功能 和 屏幕录制 权限。原生 Peekaboo 路径还要求事件发布访问权限，用于其 CoreGraphics 输入原语。
• Windows/Linux 执行方： 在 Windows x64/ARM64 或基于 glibc 的 Linux x64/ARM64 上启用捆绑的 cua-computer 插件。其包包含固定版本的 CUA Driver SDK 运行时；未配置 cua-driver 可执行文件、守护进程或 MCP 服务器。
• 对于节点，包含 computer.act 的配对更新已在 Gateway 上获批。Gateway 自身的 computer 不需要已配对节点。
• 具备视觉能力的代理模型。
• 暴露 computer 的工具策略。本地入门配置在未配置 profile 时选择 Full，但会保留显式的 coding profile，该 profile 会将其排除。对于 Coding，请将 computer 添加到 tools.alsoAllow；普通沙箱代理还需要将其添加到 tools.sandbox.tools.alsoAllow。云会话绑定的桌面包含在其默认沙箱策略中，但显式允许列表和拒绝列表仍然适用。选择 Full 工具不会授予计算机控制权限。请参阅工具配置文件。

Gateway 桌面¶

在 Gateway 主机上启用 cua-computer，并运行聚焦的产物检查：

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

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

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

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

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

内置工具使用由该 Gateway 托管的 agent 运行所使用的 Gateway 桌面。对于已配对的 node 目标，仍支持远程 Gateway URL/token 覆盖。

Linux Gateway 实时验证¶

在 Linux 上，从已构建的源代码检出中，安装托管桌面前置依赖以及 mousepad，然后运行：

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

使用空的输出目录。该证明会启动一个隔离的 Gateway 和托管桌面，且没有已配对的 node，捕获屏幕截图，向 Mousepad 输入文本并读回文本，然后验证代际围栏和已 join 进程清理。它不需要模型凭据，并会在输出目录中留下屏幕截图、脱敏日志和 result.json。

添加 --runtime <executable> 可在其他运行时（例如 Bun）上启动已构建的 Gateway，并在 PATH 中没有 node 的情况下运行该证明。如果 Gateway 或其 computer 辅助进程运行在其他可执行文件上，或任何受管进程运行 Node，该证明会失败，并在 result.json 中记录每个受管进程的可执行文件。

computer agent 工具¶

内置 computer 工具每次调用执行一个操作。为 Gateway 桌面选择 target: "gateway"，为已配对的 node 选择 target: "node"。提供 node 也会选择 node 路由。若未提供任一选择器，首次调用会使用已配置的 Gateway computer，否则使用唯一已连接的具备 computer 能力的 node。已配置但不可用的 Gateway computer 会报告其错误；它绝不会静默地将输入重定向到 node。后续调用会保留所选主机，除非显式更改。云会话保留其固定桌面，并拒绝主机覆盖。

坐标是最近一次屏幕截图中的非负整数像素；provider 会将其映射到显示点。坐标操作必须回显屏幕截图结果的 frameId，且显式提供的 screenIndex 必须与该帧匹配。OpenClaw 还会将 provider 签发的显示标识从屏幕截图带入操作，因此显示器重连或几何变化会失败关闭，而不是静默地重新指向同一索引。这些检查会拒绝猜测的 token 以及来自另一个已交付帧或显示的 token。token 不是新鲜度保证：应用可能在捕获之后更改同一显示器上的像素，因此每当场景可能已变化时，都应截取新的屏幕截图。

• 读取：screenshot 捕获桌面屏幕并返回 frameId。它不接受窗口、浏览器、元素或 observation 引用。
• 指针：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 秒），随后执行一次屏幕截图。该操作在本地运行，只要所选 provider 支持屏幕截图即可用；它不需要原生 wait 命令。

支持 v2 窗口/元素家族的 provider 还可以额外暴露 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。provider 描述符是权威依据；不可用的操作会被省略，而不是通过另一个 provider 模拟。

窗口输入坐标遵循 observation 的 details.coordinateSpace。CUA 报告 image-pixels：使用已交付图像中的像素，包括 OpenClaw 调整其大小后的情况。Peekaboo 报告 global-logical-points：使用桌面逻辑点。可访问性元素边界保留其原生屏幕坐标；在针对这些元素时优先使用 elementRef。浏览器坐标输入使用视口 CSS 像素。

对于窗口图像，使用带有 windowRef 和 includeScreenshot: true 的 get_window_state，然后将返回的 observationId 与窗口输入一起传递。对于 CUA，includeScreenshot: false 会跳过捕获，并刷新可访问性元素及其引用。此选择退出需要更新的 node；默认值和 true observation 仍与旧版 node 兼容。使用这些引用执行元素操作；窗口像素输入仍需要一个带有已交付图像的 observation。原生 macOS Peekaboo provider 拒绝 includeScreenshot: false，因为其窗口 observation 需要捕获。桌面 frameId 不能替代窗口 observation：图像可能使用不同的坐标空间。与 screenshot 类似，wait 返回桌面捕获，并拒绝 target 和 observation 引用。

CUA provider 还暴露 v2 浏览器家族：get_browser_state、browser_prepare、browser_navigate、browser_click、browser_type、browser_dialog、browser_set_input_files、browser_download 和 browser_pointer。使用 get_browser_state 绑定已发现的本地浏览器窗口，然后使用返回的不透明 browserRef、pageRef、observation 和元素引用。这些引用属于一次 Computer Use 执行和一个 driver 代际；导航会使页面元素 observation 失效，而 driver 重启会使完整的浏览器引用集失效。

CUA 还额外暴露 get_recording_state、start_recording、stop_recording 和 replay_trajectory。录制和浏览器文件操作使用不透明的 openclaw:computer-resource 句柄。所选 computer 主机会创建并验证底层文件和目录；agent 操作从不接受原生路径、输出根目录或辅助可执行文件路径。句柄属于一次 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 worker、open(1) 或 NSWorkspace 启动；这些路径会破坏 macOS 的 TCC 责任链，并创建第二个权限身份。

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

信任模型¶

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

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

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

托管端点不属于模型契约的一部分。CUA 插件不注册任何模型工具、CLI 命令、服务或原始 node-MCP 描述符，并且其操作模式不接受辅助二进制文件、套接字、原生会话、驱动程序参数或提供商工具名称。在 macOS 上，只有应用自持 worker 会接收该端点，而 node shell 执行会通过应用主机路由，且不带该仅限 worker 的值。这些边界可防止 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¶

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

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"、直接传输以及守护进程的 loopback URL。如果应用读取本地模式，则其 Port Guardian 将拥有该路由，而不是加入外部守护进程。该验证装置将经过验证的启动字段保存在不可执行的 rig.json 中；后续命令会拒绝未知字段或与临时目录/配置文件布局不匹配的路径。它还会预置专用的 node 身份、已完成的上线引导、未暂停状态、Computer Control 以及用于启动调试节点工作进程的检出路径。没有单独的节点模式切换开关。

在第三个终端中，重新运行生成的 nodes 命令，直到配对条目已连接并通告 computer.act 以及 computerUse 描述符。此过程不涉及操作员设备批准步骤：只读 CLI 不会在全新的 cli-state 中创建身份，验证令牌可对其 loopback 操作员调用进行身份验证。验证运行器在单独的 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 的 AWS Crabbox 就足够了，因为 Xvfb 是真实的 X11 服务器；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 命令。隔离配置共享一个仅限临时目录的随机 Gateway 令牌，并且 gateway 会静默批准 loopback 节点设备配对。节点命令接口仍需显式批准：在节点完成重新连接后运行生成的 nodes 命令，读取 .pending[0].requestId，并将其传递给 scripts/dev/computer-use-macos-live-rig.sh approve "$scratch" <request-id>。重新运行 nodes，直到恰好有一个已连接节点通告 provider.id: "cua-computer"。

对非最前 GTK 测试夹具执行相同的证明运行器：

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 目录下。已确认的变更必须保持哨兵作为活动 X11 窗口，并且不改变指针。上游 background_unavailable 或 background_occluded 结果只有在保持结构化且未尝试前台重试时，才是有效的拒绝证据。即使 XWayland 同时存在 DISPLAY，该 rig 也会拒绝原生 Wayland；应切换到 X11，而不是声称覆盖 Wayland。

在任一证明之后，只停止你为该 rig 启动的 Gateway、app/节点和测试夹具进程。只保留已检查的证明结果和合成捕获，然后删除任务拥有的 scratch 目录。在 macOS 上，还要删除新的证明 profile 目录（~/.openclaw-<profile>）及其 ai.openclaw.mac.profile.<profile> defaults 域。切勿清理操作员 profile 或 Gateway。

Windows 和 Linux（实验性，直接 SDK）¶

捆绑的 cua-computer 插件在每个平台上默认加载其 Gateway 策略。在 Windows 和 Linux 上，本地计算机控制仍为可选启用；仅加载策略不会启动原生驱动、注册本地计算机命令或探测本地驱动工件。macOS 保留其默认的 CUA 集成，使用 app 拥有的守护进程。显式禁用该插件也会禁用其云计算机策略。

要启用实验性的 Windows 或 Linux 节点 fulfiller（它直接使用固定的 CUA Driver SDK 契约）：

1. 启用插件：

openclaw plugins enable cua-computer

1. 在启动节点之前，验证节点本地 SDK 包：

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

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

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

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

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

被拒绝的命令会连同其 computer 能力一起从节点通告的 surface 中隐藏，Gateway 会记录它隐藏了哪些命令。

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

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

在 Windows 和 Linux 上，这取代了以前的 0.10 daemon/MCP 集成：节点主机直接调用 SDK，Gateway 在其私有桌面 helper 中加载同一 provider。两者都不会启动独立的 cua-driver 守护进程或代理 MCP 客户端。macOS 有意使用上文所述的 app 拥有的嵌入式守护进程，以便驱动保持在 OpenClaw.app 的 TCC 责任链中。对于单个操作，两条路径都不会回退到另一个 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 插件实现同一命令对。

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

对由提供程序支持的 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 目标使用其本地启用的提供程序，无需节点配对。
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 上，默认启用意味着，只要所需的 macOS 授权已存在，已配对的 Gateway 就可以驱动指针和键盘输入。没有逐操作确认。请在配对前或之后的任何时间关闭 Allow Computer Control，以停止通告并接受 computer.act。

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

安全¶

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

故障排除¶

Gateway 计算机不可用¶

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

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

CUA Driver 错误代码¶

cua-computer fulfiller 会在工具结果和所选主机日志中呈现类型化错误代码。常见的有：

桌面流¶

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

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

macOS 桌面可用性¶

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

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

对于应在任务之间保持唤醒的专用 Mac，请在 仪表板 → 设置 → 此 Mac 中显式启用 保持电脑唤醒。它仍受当前连接、托管和已解锁会话要求约束。当最后一个查看器断开时，屏幕共享可能请求立即锁定；即使启用了 保持电脑唤醒，OpenClaw 也会遵守该锁定。Web 桌面查看器不会创建 OpenClaw 保持唤醒执行。参见 桌面可用性与保持唤醒。

macOS 权限¶

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

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

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

这是由智能体驱动的路径。请参见 Peekaboo 桥接，了解它与 PeekabooBridge 宿主、Codex Computer Use 以及直接的 cua-driver MCP 的关系。