跳转至

Cloud Worker Desktop

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

请求代理打开应用

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

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

对于“打开并展示”请求,代理在创建附加环境时会传递 presentation: "desktop" 或 presentation: "portal"。侧边面板在分配之前打开,并显示机器启动进度。Web 预览会等待所请求的应用程序,而不是显示另一个 portal。如果请求方浏览器无法接收初始呈现,则新预留会在供给之前被取消;现有的附加环境仍保持可用。

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

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

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

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

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

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

Desktop(交互式){#desktop-interactive}

Cloud Worker Desktop 允许管理员从 Control UI 观察或控制一台有能力的 worker,而无需将 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 在显示 :99 上的 XFCE 会话。原生 Windows 使用 Crabbox 的交互式会话启动器,使已注册节点和 CUA 以桌面用户身份运行,并在重放时检查相同的帐户和会话。macOS 使用专用签名应用 OpenClaw Cloud Worker,在 worker 帐户的 GUI 会话中托管 CUA 和已注册节点;请参阅下面的镜像先决条件。

具备视觉能力且工具策略允许 computer 的代理通过会话的精确放置控制此桌面;它不能选择其他节点。这适用于 OpenClaw worker 和 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,并登录到已解锁的桌面。云应用拥有自己的捆绑包身份和权限授予,与普通 OpenClaw 应用相互独立。预配会在启动它之前验证已签名的云托管能力;旧版或普通应用不满足此要求。

该应用使用现有的 本地 CUA 信任边界:以 worker 帐户运行的进程可以发现并使用其桌面资源。桌面配置文件和工具策略设置控制受管 OpenClaw 入口点;它们不会对经授权的 shell 代码进行沙箱隔离。当需要与该代码隔离时,请使用没有这些桌面授权的单独帐户或镜像。

为 worker 帐户保持启用 Crabbox 的免密 sudo 访问。桌面启动会使用它进入 GUI 会话,然后以该 worker 帐户运行应用、浏览器和终端。

该应用同时拥有 CUA 和临时云节点。当其 GUI 会话保持未解锁时,它会续订一个短期的空闲断言,以在轮次之间保持桌面活动。显式锁定或托管锁定仍会终止云主机。如果其桌面会话或守护进程变为不可用,该应用会释放断言并停止节点,然后再停用 CUA。在恢复映像先决条件后,重新预置不可用的桌面。现有的云放置、注册和拆除所有者继续管理租约。

AWS macOS 需要一个可用的 EC2 Mac 专用主机和按需分配。通过 Gateway 主机上的 Crabbox 配置准备好的映像和主机选择。Crabbox 不会隐式分配新的专用主机。请参阅 Crabbox 提供商支持。

原生 Windows 先决条件

使用带有 Crabbox 的 CrabboxDesktopLauncher 服务、并为所配置的工作节点账户提供活动桌面的受管 Windows 桌面映像。桌面注册在该交互式会话内运行;普通的分离式 SSH 启动器仍是无头 Windows 工作节点的路径。Session 0 进程或属于其他账户的进程无法用于桌面注册重放。请参阅 Windows 运行时先决条件。

OpenClaw 将租约的受管 TightVNC 服务器切换到使用 GDI 捕获的交互式账户,同时保留 Crabbox 的 VNC 身份验证,并将监听器限制为回环(loopback)。映像必须允许 TightVNC 应用程序模式。预置重放会复用已验证的服务器,从而让已连接的查看者保持连接;在其交互式会话结束后,释放并重新预置该工作节点。

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

包含符号链接的工作区需要映像中启用 Windows 开发人员模式,或为交互式账户授予 Create symbolic links 权限。

桌面尺寸

在 Control UI 侧边栏中打开 Systems 以选择工作节点,并将其桌面用作主工作区。停靠的和聊天侧的 Desktop 面板仍可使用;所有演示都复用桌面连接实现和 Gateway 控制仲裁。

桌面尺寸菜单在面板和独立桌面视图中均可用:

  • 适应是默认设置。它会将现有帧缓冲缩放到查看器,而不改变工作节点的显示分辨率。
  • 实际显示帧缓冲,不进行本地缩放或远程调整大小。
  • 匹配请求将查看器的尺寸作为工作节点的显示分辨率。在请求待处理或不受支持时,它还会进行本地缩放。

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

Crabbox 插件允许针对其专用的 Linux XFCE 桌面发出调整大小请求。匹配还要求 VNC 服务器能够协商桌面调整大小,例如 Crabbox 的动态 TigerVNC 桌面。原生工作节点桌面和较旧的固定尺寸 Xvfb/x11vnc 工作节点使用适应和实际。要调整较旧的 Linux 工作节点的大小,请将 Crabbox 更新到支持动态 XFCE 的构建,并重新预置桌面工作节点。仅更改菜单不会升级现有工作节点。

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

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