Cloud Worker Desktop

在 Crabbox 配置上启用交互式桌面，并通过其经身份验证的云节点进行连接。

让代理打开应用¶

配置好 Crabbox 配置文件后，可以说 “在 Crabbox 中打开并展示给我。” 代理可以将临时环境附加到当前对话，在该环境中运行应用程序，并在聊天侧面板中打开其视图。代理的主工作区和会话位置保持不变。

附加环境会安装并验证用于远程应用命令的 worker 捆绑包，但会跳过代理运行时的预热，因为代理仍停留在当前执行主机上。OpenClaw worker 轮次仍会预热其代理运行时。

对于“打开并展示”请求，代理在创建附加环境时会传递 presentation: "desktop" 或 presentation: "portal"。侧面板会在分配前打开，并显示机器启动进度。Web 预览会等待所请求的应用程序，而不是显示另一个门户。如果发出请求的浏览器无法接收初始展示，新建的预留将在配置前被取消；现有附加环境仍然可用。

对于原生应用，请使用其操作系统的配置文件，并设置 settings.desktop: true，同时启用 Cloud Worker Desktop 实验室功能。代理会启动应用程序并打开 Desktop 面板。当其模型支持视觉且工具策略允许 computer 时，它可以使用附加环境的 environmentId 观察和控制同一桌面。手动接管会暂停代理输入；观察结果仍然可用。当被要求恢复时，代理可以在其现有的计算机控制权限下，使用 computer 并设置 action: "take_control"。你的查看器会返回仅查看模式，代理会收到一张新的屏幕截图。无需单独的、由查看器颁发的交接令牌。你可以随时重新取得控制权或自行释放它；普通代理输入永远不会自动接管。

对于 Web 应用，代理会启动服务器并在侧面板中打开一个门户。附加桌面上的浏览器可以使用 CUA 测试该服务器，但它的浏览器状态和 Cookie 与你的门户视图是分开的。

Crabbox 插件的 crabbox 工具负责创建、状态、远程命令、后台应用进程和停止操作。它仅在已配置 Crabbox 配置且处于沙箱会话之外时可用。现有的 screen 工具会在发起该轮次请求的浏览器中打开 Desktop 或 Portal 面板。远程命令保留会话的 exec 和 process 工具策略，并在配置时使用正常的一次性执行审批。来自 Gateway 的可执行文件允许列表无法移植到临时机器上：禁用审批的允许列表策略会拒绝远程命令，而不是绕过该策略。macOS 和原生 Windows 配置文件需要下文描述的镜像准备。

后续对话会复用会话中附加的机器。关闭侧面板会隐藏其视图；在配置的生命周期内，后台应用仍然可用。完成后，请要求停止特定应用或停止整个 Crabbox。机器是一次性的：在停止它之前保存所需输出。附加机器不会自动同步主工作区；代理必须在机器上复制所需文件或准备好项目。

如果停止会话环境失败，清理会在下一次对账扫描时以 30 秒到五分钟的指数退避重试。在十次尝试或一小时后（以先到者为准），清理将在该 Gateway 进程的剩余时间内暂停。环境状态会报告包含租约 ID、最后一次失败和恢复说明的错误；租约仍保持归属并阻止替换，直到清理得到确认。对于 Crabbox，可以使用 crabbox leases list 检查它，并在需要时运行 crabbox stop <lease>，然后在该会话中重试停止操作。显式停止操作或 Gateway 重启会开始新的重试预算。来自 Crabbox 的纯文本 404 表示清理结果未知，而不是租约已释放的证据。

在降级到不包含会话附加功能的构建之前，请先停止附加机器。较旧的构建可以读取数据库，但会将它们视为普通的未分配环境，并且不会维护会话活动或进行清理。有关备份、保留和重新升级的约定，请参阅会话环境存储。

桌面（交互式）¶

Cloud Worker Desktop 允许管理员从 Control UI 查看或控制具备相应能力的 worker，而无需将其云节点暴露为普通的已配对节点。启用 Cloud Worker Desktop 实验室功能，然后在 Linux、已准备好的 macOS 或原生 Windows 的 Crabbox 配置上设置 settings.desktop: true。对于 Windows，选择 windows/normal；不支持 WSL2 桌面。桌面能力在预热时固定：更改设置会影响新配置的 worker，而现有的非桌面租约必须停止并重新配置。温镜像捕获仍仅限 Linux。即使共享配置启用了温镜像，原生桌面也会冷配置。

实验室功能开关无需重启 Gateway 即可生效。已连接的 Control UI 页面会自动更新桌面可用性。禁用它会关闭 worker 桌面观察；worker 及其应用程序会继续运行。重新启用它会恢复对已具备桌面能力的 worker 的访问。更改实验室功能不会配置或替换 worker。

捆绑的 Crabbox 插件支持直接 AWS 和 Azure 配置。当所选协调器支持对应目标的桌面时，支持由协调器托管的 AWS、Azure 和 Hetzner 配置。OpenClaw 保持 worker 仅限节点执行：openclaw worker、工作区传输、桌面观察和应用启动都使用经身份验证的出站节点连接。它不会恢复 SSH 执行、反向隧道或 rsync。直接 Hetzner 会拒绝 OpenClaw 的固定租约 ID，因此在分配之前桌面配置就会失败，除非 Hetzner 使用具备相应能力的托管协调器。

每个节点通过 127.0.0.1:5900 连接到其桌面的已认证 RFB 服务器。桌面还包含一个在端口 9222 上启用环回 CDP 的浏览器，以及由提供商拥有的 Browser 和 Terminal 启动器。OpenClaw 会安装一个 worker 壁纸，以便轻松识别一次性桌面。设置是幂等的，并在云桌面可用之前完成，包括在配置重放时。项目镜像准备会保持桌面设置先于项目设置和捕获。

Linux 使用 Crabbox 的 XFCE 会话，显示在 :99。原生 Windows 使用 Crabbox 的交互式会话启动器，使已注册的节点和 CUA 以桌面用户身份运行，并在重放时检查相同的账户和会话。macOS 使用专用的已签名 OpenClaw Cloud Worker 应用，在 worker 账户的 GUI 会话中承载 CUA 和已注册节点；请参阅下文中的镜像前提条件。

具有视觉能力且其工具策略允许 computer 的代理通过会话的精确放置控制此桌面；它不能选择另一个节点。这适用于 OpenClaw workers 和 Codex 远程执行。有关工具启用和手动控制指南，请参阅 桌面和计算机控制。

桌面永远不会获得公共入站访问。节点在本地读取租约的密码文件，检查环回 RFB 安全提议，并为查看器保留同一连接。Linux 和 Windows 使用 VNC 密码认证。macOS 使用 Apple Remote Desktop 账户认证，使用检查到的 worker 用户名和 Crabbox 托管密码的私有副本。这些凭据会短暂通过已认证的节点连接用于预认证；查看器不会输入 worker 密码。节点通过其已连接的来源兑换一次性 Gateway broker 票据。因此，打开查看器不会创建额外的未认证探测连接。TLS 部署固定使用节点连接所用的同一 Gateway 证书。Gateway 在分发前和附加后都会重新验证持久环境、租约、节点、所有者纪元、桌面描述符、连接和配对；排空、替换或拆除会中止流和任何待处理的应用启动。共享桌面会话所有者执行 RFB 预认证、仅查看输入过滤和单控制器仲裁。浏览器协议协商与 worker 认证重叠，但认证成功和桌面流量会等待双方完成。

打开的聊天会在已提交的会话放置事件到达时更新其桌面目标，包括 worker 替换和拆除，而无需等待侧边栏刷新。

关闭请求的 Gateway 连接会取消待处理的查看器设置和未认领的节点流，释放其观察者槽位，而无需等待票据过期。其他已连接的查看器保留其流。

如果你在设置期间关闭或替换 Desktop 面板，它会在设置返回时释放未使用的观察。这会释放该次尝试的节点流和查看器槽位，而无需等待票据过期或中断另一个查看器。已连接的查看器保留现有的短暂隐藏行为。

当空闲时，Gateway 会在桌面观察者和节点桌面或门户流上发送 WebSocket 保活消息，因此未变化的屏幕或安静的预览不会在代理后面静默。背压可能会延迟 pong 回复，而不会撤销流；所属会话和控制连接仍然控制拆除。

当另一个操作员接管控制时，你的查看器会以仅查看模式重新连接。通知会通过其已认证的资料名称标识新控制器，或者在未设置资料名称时通过其已认证的用户 ID 标识。没有已认证用户身份的连接会显示通用的接管通知。

在降级到无法读取正在使用的桌面元数据的 Gateway 之前，停止并释放受影响的 worker 环境，包括主会话放置和会话附件。当旧版 Gateway 缺少其元数据时，这包括原生桌面，以及任何在浏览器或终端描述符中使用固定启动器 args 的提供商。Linux 提供商也可以使用启动器参数；仅支持原生桌面查看并不足以使旧版 Gateway 与这些记录兼容。

等待已确认的租约拆除；关闭查看器或挂起 worker 是不够的。旧版 Gateway 可能会拒绝不支持的密码路径或启动器参数，或者缺少认证所需的 macOS 账户元数据。已确认的拆除会清除桌面描述符，以便旧版本可以读取这些记录。如果你已经降级，请先返回到支持版本以停止这些 worker。

macOS 镜像前提条件¶

准备一个 macOS 15 或更高版本的 worker 镜像，其中包含 /Applications/OpenClawCloudWorker.app，使用 Developer ID Application 身份签名，并包含其捆绑的 CUA 驱动程序。在 macOS 上从源代码检出构建专用应用：

OPENCLAW_MAC_CLOUD_WORKER_HOST=1 scripts/package-mac-app.sh

在镜像中安装生成的 dist/OpenClawCloudWorker.app。为预期的 worker 账户授予 OpenClaw Cloud Worker 的辅助功能（Accessibility）和屏幕录制（Screen Recording）访问权限，安装 Google Chrome，并登录到未锁定的桌面。云应用拥有自己的 bundle 身份和权限授予，与普通 OpenClaw 应用分开。配置会在启动前验证已签名的 cloud-host 能力；旧版或普通应用不满足此要求。

该应用使用现有的 本地 CUA 信任边界：以 worker 账户运行的进程可以发现并使用其桌面资源。桌面配置和工具策略设置管理受管理的 OpenClaw 入口点；它们不会沙箱化已授权的 shell 代码。当需要与该代码隔离时，请使用没有这些桌面授予的单独账户或镜像。

保持 Crabbox 的无密码 sudo 访问对 worker 账户启用。桌面启动会使用它进入 GUI 会话，然后以该 worker 账户身份运行应用、浏览器和终端。

该应用同时拥有 CUA 和临时云节点。在其 GUI 会话保持未锁定期间，它会续期一个短生命周期的空闲断言，以在轮次之间保持桌面处于活动状态。显式或托管锁定仍会终止云主机。如果其桌面会话或守护进程变得不可用，该应用会在退役 CUA 之前释放断言并停止节点。在恢复镜像先决条件后，重新配置不可用的桌面。现有的云放置、注册和拆除所有者继续管理租约。

AWS macOS 需要可用的 EC2 Mac Dedicated Host 和 On-Demand 分配。通过 Gateway 主机上的 Crabbox 配置准备好的镜像和主机选择。Crabbox 不会隐式分配新的 Dedicated Host。参见 Crabbox 提供商支持。

原生 Windows 先决条件¶

使用带有 Crabbox 的 CrabboxDesktopLauncher 服务的托管 Windows 桌面镜像，并为已配置的 worker 账户提供活动桌面。桌面注册在该交互式会话内运行；普通的分离式 SSH 启动器仍然是无头 Windows worker 的路径。Session 0 进程或属于其他账户的进程无法满足桌面注册重放。参见 Windows 运行时先决条件。

OpenClaw 将租约的托管 TightVNC 服务器切换到交互式账户，并启用 GDI 捕获，同时保留 Crabbox 的 VNC 身份验证，并将监听器限制为回环。镜像必须允许 TightVNC 应用程序模式。配置重放会复用已验证的服务器，使已附加的查看器保持连接；在其交互式会话结束后，释放并重新配置该 worker。

此模式控制活动桌面；它不提供登录、Ctrl+Alt+Delete 或安全桌面控制。使用 OpenClaw 配置重放或重新配置进行恢复。Crabbox 的通用 VNC 重置管理服务模式。

包含符号链接的工作区要求镜像中启用 Windows 开发者模式，或为交互式账户授予 Create symbolic links 权限。

桌面大小¶

在 Control UI 侧边栏中打开 系统，以选择一个 worker 并将其桌面 用作主工作区。停靠的 Desktop 面板和聊天侧 Desktop 面板仍然可用； 所有展示都复用桌面连接实现和 Gateway 控制仲裁。

桌面大小 菜单在面板和独立桌面视图中可用：

• 适应 是默认选项。它将现有帧缓冲区缩放到查看器，而不更改 worker 的显示分辨率。
• 实际大小 显示帧缓冲区，不进行本地缩放或远程调整大小。
• 匹配 请求将查看器的尺寸作为 worker 的显示分辨率。在请求待定或不受支持时，它也会进行本地缩放。

匹配 仅在控制连接完成身份验证且 worker 提供商允许虚拟显示调整大小后出现。仅查看连接无法请求调整大小。直接主机桌面不会获得此权限。

Crabbox 插件允许为其专用 Linux XFCE 桌面发送调整大小请求。匹配 还要求 VNC 服务器支持桌面调整大小协商，例如 Crabbox 的动态 TigerVNC 桌面。原生 worker 桌面和旧版固定大小的 Xvfb/x11vnc worker 使用 适应 和 实际大小。要调整旧版 Linux worker 的大小，请将 Crabbox 更新到支持动态 XFCE 的构建版本，并重新配置桌面 worker。仅更改菜单不会升级现有 worker。

对同一来源的控制重连会保留大小选择。更改来源会将其重置为 适应。失去控制或调整大小权限也会将 匹配 重置为 适应。