Cloud Sessions

云会话是一种普通会话，其编码工作运行在另一台机器上。它显示在侧边栏中，流式输出到聊天，并像本地会话一样保留其转录记录——Gateway 仍然是对话、已协调工作区、模型凭据和放置记录的拥有者，而命令、文件编辑和工具工作在远程执行。会话及其持久状态可在远程故障后存活。被回收或挂起的云工作器会在下一条消息时重启。先前处于活动状态但发生故障的工作器，在清理完成且其已保存的工作区就绪后，也会在下一条消息时重启。Gateway 更新会保留已附加的云机器，并就地刷新其工作器运行时。离线的已配对设备会保留其放置并等待设备返回。

会话可以在三个位置运行，并且每一个都使用相同的会话、相同的聊天和相同的位置选择器：

在所有远程放置中，模型推理始终通过 Gateway 代理——提供商凭据永远不会到达远程机器——已完成的工作会保留在 Gateway 中，作为已接受的仓库检查点或 Gateway 源托管 worktree 中的更改。OpenClaw 运行时（worker-turn）和 Codex（remote-exec）都可以使用相同的目标。

会话是客户端附加的对话。设备是已配对的硬件（协议中的 node）；runner 是执行主机的内部术语。放置选择工作运行的位置，而隔离描述该主机上的边界，而不是另一个目标。

无需 Gateway 检出即可开始¶

在 新建会话 中，在 位置 里选择一个 GitHub 仓库，选择一个已配对设备或云配置文件，并可选地在 远程检出 下设置源 ref。云配置文件也可以在 位置 中提供操作系统和机器类别选项；机器列表遵循所选操作系统。Gateway 记录源；节点获取它并创建会话分支。不会在 Gateway 上创建项目克隆或 worktree。启动会等待活动放置就绪后再发送您的提示，重试/重新加载恢复会保留仓库和 ref。

OpenClaw 和 Codex 都使用托管节点连接进行仓库准备。仅具有 SSH 载体的提供商无法托管此源。改为选择现有的 Gateway 文件夹会保留 托管 worktree 流程，包括本地更改和未发布的提交。

首次准备会固定已解析的上游提交。已接受的更改会作为不可变检查点，在 Stop 和替换后存活；恢复仍取决于被固定的上游提交保持可用。显式的 移动会话… → Gateway 会获取该源并实例化一个托管 worktree。有关 RPC 序列和设置权限，请参阅 分发与恢复。

图像和附件¶

通过常规聊天编辑器附加图像和 PDF，包括在现有云会话的后续轮次中。Gateway 会准备原生图像输入，包括扫描 PDF 的渲染页面。Codex 通过其 Gateway 侧 app-server 接收图像输入。其 remote-exec 放置会在执行前为远程文件工具暂存托管原始文件；这些临时副本会被排除在工作区协调之外。以下保留输入规则适用于 OpenClaw worker-turn 会话。

OpenClaw worker-turn 会话接受图像，包括仅图像消息以及内联图像和外置图像的有序混合。对于支持视觉的模型，Gateway 会使用与本地会话相同的图像清理、排序和历史修剪，从其托管媒体中填充当前输入和最近重放。仅文本模型会收到附件文件路径，而不接收原生图像输入。Gateway 保留规范转录和原始附件引用；只有工作器的输入会收到远程文件路径。

分发后发送的附件会通过身份验证传输通道复制到工作器工作区。这需要最新的节点主机安装以及工作器捆绑包；使用前请更新已配对设备或云配置文件中的节点包。文件工具可以读取其源文件，包括非图像附件。副本不会替换活动工作区，也不会覆盖工作器之前对同一附件的编辑。传输和启动前会检查放置和轮次所有权；当前附件不可用或过大时会产生错误，而不是静默丢弃图像。不可用的历史源（包括因配置的附件保留策略而过期的原始文件）会在重放暂存中被省略并给出警告，以免阻塞新轮次。规范转录引用和现有私有副本保持不变。

原始输入使用 media/inbound/openclaw-staged-<id>/ 下的 OpenClaw 拥有目录，并带有本地 Git 排除。本地和可写沙箱会话使用相同规则。自动输入保留要求由生产者生成的目录名称及其完整的常规 .gitignore 所有权标记；名称相似的被忽略项目目录不会仅凭名称被选中。输入副本和编辑会在工作区协调、工作器替换以及托管 worktree 移除和恢复过程中保持可用，但普通 Git 发布不会包含它们。要将图像或文档作为项目的一部分发布，请先显式将其复制到普通项目路径。现有受跟踪文件仍归项目所有；这不会从早期提交中移除文件，也不会撤销先前发布。

Turn cancellation, admitted-run closure, or loss of the exact placement claim cancels attachment streaming and the node transfer invocation, and prevents the abandoned turn from launching. Once cancellation is observed, no subsequent attachment is installed. There is a bounded final-write limitation with fs-safe 0.7.0: an exclusive create() that has already been entered may finish and leave its private copy. The transfer still rejects after that operation returns. Previously completed copies and worker edits remain intact; cancellation does not unlink files by path. TODO(fs-safe): adopt guarded exclusive-create with identity-bound rollback once the dependency supports it, closing this remaining window.

Attachment staging uses the existing workspace-result transfer limits (25,000 files and 256 MiB total), with a 6 MiB per-file media read limit. Encoded launch, inference, and image-bearing transcript frames must also fit within 25 MiB; base64 encoding counts toward those frame limits. Non-image transcript content and unrelated control traffic retain their 64 KiB limits. Worker turns have no native steering transport: messages received during a turn use the existing queued follow-up path, retaining their images and media metadata.

Paired devices: your own hardware as session hosts¶

Pair any machine with one pasted command, then opt it into session hosting:

openclaw connect <join-url> --service --session-host

The device holds an outbound connection to the Gateway, advertises worker slots (one per CPU core by default, tunable with nodeHost.workerRuns.capacity), and can optionally run each hosted session in a Docker-compatible container (nodeHost.workerRuns.isolation: "container"). A device that goes offline keeps its active placement — the session waits for it to reconnect rather than losing work.

The node host reconnects after transient transport loss. A worker child has a bounded 120-second admission window. If that window expires before the turn starts, the Gateway can launch another child, up to five attempts total (about ten minutes plus backoff), within the original turn timeout. Launch retries use exponential backoff with jitter; each attempt keeps its own terminal result and reason in the node launch journal. Credential and build rejections are terminal, and work that already started is never replayed by this policy.

If a journal-terminal worker has released its turn claim but teardown stalls, stuck-session recovery records the turn failure after a 30-second cleanup grace, on the next diagnostic cycle. Live workers and turns that still hold their claims are unaffected. On Gateway restart, orphan workspace cleanup for failed placements runs in the background after readiness; ownership fencing and pending workspace-result recovery still run before readiness.

See Nodes for pairing, capacity, isolation, and offline behavior, and Connect for the CLI.

Cloud workers: rented machines through Crabbox¶

Configure a profile under cloudWorkers.profiles and the bundled Crabbox plugin provisions machines on demand across cloud backends (AWS, Hetzner, and others), runs your setup command, enrolls the box as a temporary node, and tears everything down when the session stops. The machine is disposable by design: no standing credentials live on it, and the durable state stays with the Gateway.

See Cloud Workers for profiles, requirements, dispatching, moving sessions between destinations, and the security model.

Viewing the session desktop¶

Open Desktop from a session to connect directly to its execution machine. Cloud sessions select their worker desktop; sessions on paired devices select that device. The chat panel shows connection progress or a retry action instead of offering unrelated machines. The pop-out window keeps the session in its link, so both viewers follow placement changes and disconnect from the previous machine when the session moves or stops. A stopped cloud session does not switch either viewer to the Gateway desktop.

If you choose a source in the Desktop picker, the panel keeps that choice when the session's placement changes. Open desktop in new window opens that source and requests the panel's current view-only or control mode. Desktop links contain no credentials and do not grant control; the new viewer still performs its normal authentication and permission checks.

The machine must already support desktop viewing. For cloud workers, enable the Cloud Worker Desktop lab and desktop profile setting. Opening Desktop starts in view-only mode and does not change the machine's permissions or the agent's tool policy. The command palette's Desktop action also follows the current session on chat pages. Outside chat, it opens the machine picker.

To enter text from your local clipboard, take control and choose Keyboard before pasting with Command+V on macOS or Ctrl+V on Windows and Linux. The Keyboard field sends the pasted text to the remote desktop; shortcuts directed at the desktop canvas still operate on the remote machine. Keyboard input stays disabled until the control connection is ready.

Desktop and computer control¶

A desktop-enabled cloud session uses the same machine for the chat Desktop panel and the agent's computer tool. Enable the Cloud Worker Desktop lab and provision a Crabbox profile with settings.desktop: true. OpenClaw starts the worker's CUA provider inside the provisioned desktop session; the agent does not need to discover or choose a paired computer. Both OpenClaw and Codex sessions use this binding. A paired-device session instead uses that device's enabled Computer Control provider.

OpenClaw worker turns preserve their node host's display and desktop-session environment for local exec commands. On a desktop-enabled Linux worker, launch a GUI application with background: true to keep using computer while it runs.

使用支持视觉的模型，以及允许 computer 的工具配置。对于 coding 配置，将 computer 添加到 tools.alsoAllow。绑定的桌面在默认远程会话沙箱策略下可用；显式沙箱允许列表和拒绝列表仍然适用。在代理工作时观察桌面面板。手动接管云桌面会暂停代理输入。当你要求代理恢复时，它可以使用带有 action: "take_control" 的 computer；查看器切换为仅查看，并且代理会收到一张新的屏幕截图。此显式操作使用已批准运行现有的计算机控制权限，无需单独的由查看器签发的交接令牌。你可以随时再次接管。被中断的输入不会被重放。

Worker 转录保留屏幕截图。Codex 直接在代码模式之外暴露计算机工具，因此屏幕截图结果会以图像形式到达模型。为了让后续模型请求保持在传输限制内，OpenClaw 可以在模型上下文中用文本标记替换较早的、已处理的图像，同时保留当前计算机帧和未处理图像。不透明提供商重放保持不变；如果其所需上下文无法容纳，该轮次将失败并给出恢复指导。

计算机控制始终绑定到已批准的轮次、放置、节点连接和提供商。如果 OpenClaw worker 断开连接，其计算机执行即使在工具调用之间也会关闭；重新连接后，启动新轮次以重新获得计算机控制。其他持久会话操作仍可以完成。停止或替换机器会使旧工具句柄失效；不可用的桌面永远不会选择另一台已连接的计算机。一次性云桌面仍然不出现在普通配对计算机选择器中。有关支持的操作，请参阅 计算机使用；有关设置和查看权限，请参阅 Cloud Worker Desktop。

OpenClaw worker 会等待计算机和浏览器清理完成，然后再请求 Gateway 确认其轮次即将结束。如果在助手已回答之后清理失败，该轮次会报告失败，并附带有限且已脱敏的诊断信息，同时在转录中保留回答。Gateway 会通过工作区协调保留已确认的失败，包括任何额外的协调错误，并且不会自动在另一个模型上重放该轮次。重试前请检查桌面和工作区：清理失败不会撤销先前的输入。

对于 remote-exec 轮次，计算机清理会在工作区协调之前完成。如果清理失败，OpenClaw 会保留已捕获的回复、用量、交付证据以及任何先前的错误或中断，添加有限的清理诊断，并且不会自动重放该轮次。工作区恢复失败会报告这两个问题。安全敏感资源清理仍然会拒绝完成，而不是变成建议性警告；重试前请解决所报告的清理问题。

跨设备自动负载均衡¶

你不必选择设备。在位置选择器中选择 Auto（最空闲设备）——或者使用 autoDevice: true 进行分发——会自动选择一个配对的会话主机。OpenClaw worker-turn 放置首先优先选择相对于其 worker 容量而言已批准工作更少的主机。然后，在考虑仍在启动的分发后，它们会比较空闲 worker 槽位，并按设备 ID 打破剩余平局。仅会话的放置不会预留 worker 槽位。Codex remote-exec 放置不会消耗 worker 槽位，因此符合条件的主机仅按设备 ID 排序。当没有主机符合条件时，错误会准确说明原因：没有配对的会话主机、全部断开连接，或全部达到容量。

如果所选设备在工作区准备开始之前变得不符合条件，Auto 会在确认失败的分配已完全清理后，尝试最多三个排名靠前的主机。它不会重放工作区设置或已开始的工作。一旦工作区准备被批准，另一个填满设备槽位的轮次不会取消它；当会话启动轮次时，节点会再次检查物理容量。在整个准备过程中，节点身份和命令授权仍会持续检查。

有关选择规则，请参阅 节点；有关选择器，请参阅 Control UI。

休眠与唤醒：空闲挂起与预热镜像¶

两个配置设置可将云 worker 从始终在线的机器转变为空闲时休眠的计算资源：

• suspendAfter: "2h" — 会话空闲达到该时长后，Gateway 会执行与 Stop cloud worker… 相同的安全停止：先协调工作区，然后释放机器。挂起期间，你只需为保留的快照存储付费。下一条消息会自动配置替代机器——无需按下任何按钮。
• settings.warmImage — 准备项目的已提交检出和节点运行时，然后在节点注册前捕获可复用镜像。同一项目和配置的后续会话可以从该镜像启动；第一个会话无需先停止。仅限 Linux，并且当有效机器类型已知且 setupEnv 为空时默认启用。将主机环境转发到 setup 捕获的配置仅在你明确选择加入时才会捕获，而 settings.warmImage: false 会使任何配置保持冷启动。

对于源自 Gateway 检出的会话，关联的工作树共享稳定的项目标识。预热镜像保留原始的已提交种子和已验证运行时，而每个新会话都会获得新的注册及其当前工作区文件。匹配的种子会跳过源访问和完整的 Git pack 传输，包括针对私有或未发布的提交。更改的提交会准备新的种子，并可以刷新项目镜像。仅仓库会话则会在节点上获取，并且可以复用机器/运行时镜像和已验证的 Git 种子；它们不会从 Gateway 检出准备项目镜像。第一次分发包括准备和任何所需捕获；提供商启动和捕获成本仍决定整体延迟。

Each allocation keeps its original cold start or exact checkpoint choice through retries and Gateway restart. If an upgrade reports older warm-image state, follow Upgrade warm-image state; Doctor preserves known images and cleanup obligations, and reports manual recovery steps for leases whose original choice is unknown.

每次分配在重试和 Gateway 重启期间都会保留其原始的冷启动或精确检查点选择。如果升级报告了较旧的 warm-image 状态，请遵循升级 warm-image 状态；Doctor 会保留已知镜像和清理义务，并针对原始选择未知的租约报告手动恢复步骤。

Suspension never interrupts work: sessions with an active turn, queued messages, or unreconciled results are skipped and re-checked on the next sweep. See the profile fields in Cloud Workers for costs, capture boundaries, and prerequisites.

挂起永远不会中断工作：具有活动轮次、排队消息或未协调结果的会话会被跳过，并在下一次扫描时重新检查。有关成本、捕获边界和前提条件，请参阅Cloud Workers中的配置字段。

保留在 Gateway 中的内容¶

The transcript, the last-reconciled workspace files, placement history, and every provider credential live with the Gateway in all placements. After a clean reclaim or idle suspension, the next message provisions a replacement — warm when an image exists, cold otherwise.

在所有放置中，对话记录、最后协调的工作区文件、放置历史以及所有提供商凭据都随 Gateway 保留。在干净回收或空闲挂起之后，下一条消息会配置替代资源——如果存在镜像则为热启动，否则为冷启动。

Gateway updates, including new builds with the same version, retain an attached cloud machine and install the current worker bundle in place. Its workspace, installed packages, and desktop stay on that machine. A node must reconnect and support the current bundle installer before the update can finish. Failed installation leaves the runtime update pending and retains the machine for recovery; see cloud worker troubleshooting.

Gateway 更新（包括相同版本的新构建）会保留已附加的云机器，并就地安装当前 worker 捆绑包。其工作区、已安装的包和桌面环境保留在该机器上。在更新完成之前，节点必须重新连接并支持当前捆绑包安装程序。安装失败会使运行时更新保持待处理状态，并保留该机器用于恢复；请参阅cloud worker 故障排查。

When a Gateway restart interrupts a node-backed turn, recovery settles pending workspace results and retires the interrupted turn while retaining its machine. Continuing the session uses fresh execution authority and does not automatically replay an interrupted tool call. Explicit Stop, Move, and cleanup after provider loss still follow their normal teardown flow. Failed placements keep their diagnostic visible; resolve pending cleanup, then redispatch and retry. See session lifecycle and durability.

当 Gateway 重启中断由节点支持的轮次时，恢复流程会结算待处理的工作区结果，并结束被中断的轮次，同时保留其机器。继续会话会使用新的执行权限，并且不会自动重放被中断的工具调用。显式 Stop、Move 以及提供商丢失后的清理仍遵循其正常的拆除流程。失败的放置会保持其诊断信息可见；解决待处理的清理，然后重新分派并重试。请参阅会话生命周期与持久性。

An offline paired device keeps its placement active and waits to reconnect. Continue on Gateway… works while the device is offline, resuming from the last Gateway-synced workspace and discarding unsynced device changes. Changes made between reconciliations can be lost if the machine disappears; clean stops, including auto-suspension, reconcile before releasing it.

离线配对设备会保持其放置处于活动状态，并等待重新连接。在 Gateway 上继续…在设备离线时可用，它会从最后一次与 Gateway 同步的工作区恢复，并丢弃未同步的设备更改。如果在两次协调之间机器消失，期间所做的更改可能会丢失；正常停止（包括自动挂起）会在释放机器之前进行协调。

Repository-only checkpoint history remains until session deletion. While a worker runs, Files and diffs use its checkout. After Stop, changed-file previews remain available from the accepted checkpoint; editing, unchanged upstream files, and full diffs require restarting the worker. Publication can use an accepted Git-normalized checkpoint without a Gateway checkout. See what survives a dead machine.

仅仓库的检查点历史会保留到会话删除为止。当 worker 运行时，Files 和差异会使用其检出。在 Stop 之后，已更改文件的预览仍可从已接受的检查点获取；编辑、未更改的上游文件和完整差异需要重启 worker。发布可以使用已接受的 Git 规范化检查点，而无需 Gateway 检出。请参阅死机后保留的内容。

Reset keeps the repository and accepted changes but ends unfinished publication requests from the previous session lifecycle. Review the retained changes and request publication again after reset. Existing GitHub commits and pull requests remain unchanged.

Reset 会保留仓库和已接受的更改，但会结束上一个会话生命周期中未完成的发布请求。重置后，请审查保留的更改并再次请求发布。现有的 GitHub 提交和拉取请求保持不变。

相关¶

• Cloud Workers — 配置文件、分派、移动、安全模型
• Nodes — 配对、会话托管、容量、容器隔离
• Control UI — Place 选择器和会话徽章
• Connect — 单命令设备接入
• Managed worktrees — 源自 Gateway 检出的会话隔离
• Sandboxing — 作为替代，缩小本地执行的爆炸半径