网关

云会话

状态：active

云会话是一个普通会话，其编码工作在另一台计算机上运行。它出现在侧边栏中，流式传输到聊天中，并像本地会话一样保留其记录 - 网关保留对话、协调的工作区、模型凭据和放置记录的所有者，而命令、文件编辑和工具工作则远程执行。会话及其持久状态在远程故障中仍然存在。回收或暂停的云工作人员会在下一条消息时重新启动。一旦清理完成并且其保存的工作空间准备就绪，之前失败的活动工作线程也会在下一条消息时重新启动。网关更新保留连接的云计算机并刷新其工作运行时。离线配对的设备保持其位置并等待设备返回。

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

目标	机器	最适合	派遣范围
网关（默认）	运行`openclaw gateway`的主机	日常会话	—
配对设备	您自己的硬件，与 `openclaw connect` 连接一次	备用 Mac、组装机、您已拥有的服务器	`operator.write`
云工作者	通过 Crabbox 租赁的一次性机器	突发容量、长时间作业、与您自己的机器隔离	`operator.admin`

在所有远程放置中，模型推理通过网关保持代理（提供者凭据永远不会到达远程计算机），并且已完成的工作将作为接受的存储库检查点或网关源管理的工作树中的更改保留在网关中。 OpenClaw 运行时（worker-turn）和 Codex （remote-exec）都可以使用相同的目标。

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

在没有网关结账的情况下开始

在 New Session 中，在 Place 中选择 GitHub 存储库，选择配对的设备或云配置文件，并可选择在 Remote checkout 下设置源引用。云配置文件还可以就地提供操作系统和机器级别选择；机器列表遵循所选的操作系统。网关记录来源；节点获取它并创建会话分支。网关上不会创建项目克隆或工作树。启动会在发送提示之前等待活动放置，并且 retry/reload 恢复会保留存储库和引用。

OpenClaw 和 Codex 都使用受管节点连接进行存储库准备。仅具有 SSH 运营商的提供商无法托管此源。选择现有网关文件夹将保留托管工作树流，包括本地更改和未发布的提交。

第一个准备固定已解析的上游提交。接受的更改作为不可变的检查点在停止和替换中继续存在；恢复仍然取决于固定的上游提交仍然可用。显式 Move 会话...→ Gateway 获取该源并具体化托管工作树。有关 RPC 序列和设置权限，请参阅 dispatch 和 recovery。

图片和附件

通过普通聊天编辑器附加图像和 PDF，包括稍后在现有云会话中添加图像和 PDF。网关准备本机图像输入，包括扫描 PDF 的渲染页面。 Codex 通过其网关端应用程序服务器接收图像输入。其 remote-exec 放置阶段在执行前管理远程文件工具的原始文件；这些临时副本被排除在工作区协调之外。以下保留输入规则适用于 OpenClaw worker-turn 会话。

OpenClaw worker-turn 会话接受图像，包括仅图像消息以及内联和卸载图像的有序混合。对于具有视觉支持的模型，网关使用与本地会话相同的图像清理、排序和历史修剪来水合来自其托管媒体的当前输入和最近重播。纯文本模型接收附件文件路径，无需本机图像输入。网关保留存储的文字记录和原始附件参考；只有工作人员的输入接收远程文件路径。

调度后发送的附件将通过经过身份验证的传输通道复制到工作人员工作区中。这需要当前的节点主机安装以及工作包；使用前更新配对设备或云配置文件的节点包。文件工具可以读取其源文件，包括非图像附件。副本不会替换活动工作区或覆盖早期工作人员对同一附件的编辑。在转移和启动之前检查放置和回合所有权；当前附件不可用或过大会产生错误，而不是默默地删除图像。不可用的历史源（包括因配置的附件保留而过期的原始源）将从重放暂存中省略并带有警告，因此它们不会阻止新的回合。存储的成绩单参考和现有的私人副本保持不变。

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

轮次取消、允许运行关闭或丢失确切的放置声明会取消附件流和节点传输调用，并阻止已放弃的轮次启动。一旦观察到取消，则不会安装后续附件。 fs-safe 0.7.0 有一个有界的最终写入限制：已输入的独占 create() 可能会完成并留下其私有副本。该操作返回后，传输仍然被拒绝。先前完成的副本和工作人员编辑保持不变；取消不会按路径取消文件链接。 TODO（fs-safe）：一旦依赖项支持，采用带有身份绑定回滚的受保护的独占创建，关闭剩余的窗口。

附件暂存使用现有的工作区结果传输限制（总共 25,000 个文件和 256 个 MiB），每个文件介质读取限制为 6 MiB。编码的启动、推理和承载图像的转录帧也必须在 25 MiB 之内； Base64 编码计入这些帧限制。非图像转录内容和不相关的控制流量保留其 64 KiB 限制。工作轮次没有本机转向传输：轮次期间收到的消息使用现有的排队后续路径，保留其图像和媒体元数据。

配对设备：您自己的硬件作为会话主机

将任何计算机与一个粘贴的命令配对，然后选择将其加入会话托管：

bash

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

该设备保持与网关的出站连接，通告工作插槽（默认情况下每个 CPU 核心一个，可通过 nodeHost.workerRuns.capacity 进行调整），并且可以选择在 Docker- 兼容容器（nodeHost.workerRuns.isolation: "container"）中运行每个托管会话。离线的设备会保持其活动位置——会话等待它重新连接而不是丢失工作。

节点主机在短暂传输丢失后重新连接。工人孩子的进入窗口有 120 秒的限制。如果该窗口在回合开始前到期，则网关可以在原始回合超时内启动另一个子项，总共最多尝试五次（大约十分钟加上退避）。启动重试使用带抖动的指数退避；每次尝试都会在节点启动日志中保留其自己的最终结果和原因。凭证和构建拒绝是最终的，并且此策略永远不会重播已经开始的工作。

如果日志终端工作人员已释放其轮次声明但拆卸停止，则卡住会话恢复会在下一个诊断周期的 30 秒清理宽限期后记录轮次失败。仍然持有其声明的活着的工人和回合不受影响。网关重新启动时，失败放置的孤立工作区清理会在准备就绪后在后台运行；所有权防护和挂起的工作区结果恢复在准备就绪之前仍会运行。

有关配对、容量、隔离和离线行为，请参阅 Nodes；有关 CLI，请参阅 Connect。

云工人：通过Crabbox租用机器

在 cloudWorkers.profiles 下配置配置文件，捆绑的 Crabbox 插件可跨云后端（AWS、Hetzner 等）按需配置机器，运行设置命令，将盒子注册为临时节点，并在会话停止时拆除所有内容。该机器在设计上是一次性的：其上不存在任何长期凭证，并且持久状态保留在网关中。

有关配置文件、要求、调度、在目标之间移动会话以及安全模型，请参阅 Cloud Workers。

查看会话桌面

从会话中打开 Desktop 以直接连接到其执行机。云会话选择其工作人员桌面；配对设备上的会话选择该设备。聊天面板显示连接进度或重试操作，而不是提供不相关的计算机。弹出窗口将会话保持在其链接中，因此两个查看器都会跟踪位置更改，并在会话移动或停止时与前一台计算机断开连接。停止的云会话不会将任一查看器切换到网关桌面。

如果您在桌面选择器中选择源，则当会话的位置发生更改时，面板会保留该选择。 在新窗口中打开桌面 打开该源并请求面板当前的仅查看或控制模式。桌面链接不包含凭据，也不授予控制权；新查看器仍然执行正常的身份验证和权限检查。

该机器必须已经支持桌面查看。对于云工作人员，启用云工作人员桌面实验室和桌面配置文件设置。 Opening Desktop 以仅查看模式启动，并且不会更改计算机的权限或代理的工具策略。命令选项板的桌面操作也遵循聊天页面上的当前会话。在聊天之外，它会打开机器选择器。

要从本地剪贴板输入文本，请控制并选择 Keyboard，然后在 macOS 上使用 Command+V 或在 Windows 上使用 Ctrl+V 进行粘贴， Linux。键盘字段将粘贴的文本发送到远程桌面；针对桌面画布的快捷方式仍然可以在远程计算机上运行。在控制连接准备就绪之前，键盘输入将保持禁用状态。

桌面及电脑控制

支持桌面的云会话将同一台计算机用于聊天桌面面板和代理的 computer 工具。启用 Cloud Worker Desktop 实验室并使用 settings.desktop: true 配置 Crabbox 配置文件。 OpenClaw 在配置的桌面会话内启动工作人员的 CUA 提供程序；代理不需要发现或选择配对的计算机。 OpenClaw 和 Codex 会话都使用此绑定。配对设备会话改为使用该设备启用的计算机 Control 提供程序。

OpenClaw 工作线程轮流为本地 exec 命令保留其节点主机的显示和桌面会话环境。在支持桌面的 Linux 工作线程上，使用 background: true 启动 GUI 应用程序，以在其运行时继续使用 computer。

使用支持视觉的模型和允许 computer 的工具配置文件。对于 coding 配置文件，将 computer 添加到 tools.alsoAllow。绑定桌面在默认远程会话沙箱策略下可用；明确的沙箱允许名单和拒绝仍然适用。代理工作时观察桌面面板。手动控制云桌面会暂停座席输入。当您要求代理恢复时，可以使用computer和action: "take_control"；查看器切换到仅查看状态，代理会收到新的屏幕截图。此显式操作使用已承认运行的现有计算机控制权限，无需单独的查看者颁发的切换令牌。您可以随时重新掌控一切。不会重播中断的输入。

工作人员成绩单保留屏幕截图。 Codex直接暴露计算机工具，外部代码模式，因此截图结果以图像形式到达模型。为了将以后的模型请求保持在传输限制内，OpenClaw 可以在模型上下文中使用文本标记替换旧的、已处理的图像，同时保留当前计算机帧和未处理的图像。不透明的提供商重播保持不变；如果其所需的上下文不适合，则转弯将失败并带有恢复指导。

计算机控制仍然与允许的回合、放置、节点连接和提供者绑定。如果 OpenClaw 工作线程断开连接，即使在工具调用之间，其计算机执行也会关闭；重新连接后开始新一轮以重新获得计算机控制权。其他持久会话操作仍然可以完成。停止或更换机器会使旧工具手柄失效；不可用的桌面永远不会选择另一台连接的计算机。普通的配对计算机选择器中仍然不存在一次性云桌面。请参阅计算机使用了解支持的操作，并参阅 Cloud Worker Desktop 了解设置和查看权限。

OpenClaw 工作人员等待计算机和浏览器清理，然后请求网关确认其轮次已完成。如果在助理回答后清理失败，则轮流会通过有限的、经过编辑的诊断来报告失败，同时将答案保留在记录中。网关通过工作区协调保留已确认的故障，包括任何其他协调错误，并且不会自动在另一个模型上重播该轮次。重试之前检查桌面和工作区：清理失败不会撤消之前的输入。

对于 remote-exec 轮次，计算机清理在工作区协调之前完成。如果清理失败，OpenClaw 会保留捕获的回复、使用情况、交付证据以及任何早期错误或中断，添加有界清理诊断，并且不会自动重播回合。工作区恢复失败会报告这两个问题。安全敏感的资源清理仍然拒绝完成，而不是成为咨询警告；在重试之前解决报告的清理问题。

跨设备自动负载均衡

您不必选择设备。在位置选择器中选择 Auto（最不繁忙的设备） — 或使用 autoDevice: true 进行调度 — 会自动选择配对的会话主机。 OpenClaw worker-turn 放置首先喜欢相对于其工作人员容量而言承认工作较少的主机。然后，他们在考虑仍在开始的调度后比较空闲的工作插槽，通过设备 ID 打破剩余的联系。会话的放置本身并不保留工作槽位。 Codex remote-exec 放置不会消耗工作线程槽位，因此符合条件的主机仅按设备 ID 进行排名。当没有主机符合条件时，错误会准确说明原因：没有会话主机配对、全部断开连接或全部满负荷。

如果在工作区准备开始之前选定的设备变得不合格，则在确认完全清理失败的分配后，自动会尝试最多三个排名的主机。它不会重播工作区设置或已开始的工作。一旦工作区准备被允许，另一轮填充设备的插槽不会取消它；当会话启动轮次时，节点再次检查物理容量。 Node 身份和命令授权在整个准备过程中保持检查。

选择规则请参见 Nodes，选择器请参见 Control UI。

睡眠和醒来：空闲暂停和温暖的图像

两个配置文件设置可将云工作人员从始终在线的计算机转变为空闲时休眠的计算：

suspendAfter: "2h" — 会话闲置一段时间后，网关执行与 Stop 云工作线程相同的安全停止…：它首先协调工作区，然后释放计算机。暂停期间，您只需为保留的快照存储付费。下一条消息会自动提供替换 — 无需按任何按钮。
settings.warmImage — 准备项目的提交签出和节点运行时，然后在节点注册之前捕获可重用的映像。同一项目和配置文件的后续会话可以从该图像开始；第一个会话不必先停止。仅 Linux，并且当有效机器类别已知并且 setupEnv 为空时默认启用。仅当您明确选择加入时，配置文件才会将主机环境转发到设置捕获，并且 settings.warmImage: false 会使任何配置文件保持冷状态。

对于来自网关结帐的会话，链接的工作树共享稳定的项目标识。温暖的映像保留原始的提交种子和经过验证的运行时，而每个新会话都会获得新的注册及其当前工作区文件。匹配的种子会跳过原始访问和完整的 Git 包传输，包括私有或未发布的提交。更改的提交准备新的种子并可以刷新项目的映像。仅存储库会话改为在节点上获取，并且可以重用 machine/runtime 图像和经过验证的 Git 种子；他们不准备来自网关结帐的项目图像。第一次派遣包括准备和任何需要的捕获；提供商的启动和捕获成本仍然决定总体延迟。

每个分配通过重试和网关重启来保持其原始冷启动或精确的检查点选择。如果升级报告较旧的热映像状态，请按照升级热映像状态； Doctor 保留已知图像和清理义务，并报告原始选择未知的租赁的手动恢复步骤。

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

网关保留什么

记录、最后协调的工作区文件、放置历史记录以及每个提供商凭证都与所有放置中的网关一起保存。在干净回收或空闲暂停之后，下一条消息提供替换 - 当图像存在时为热，否则为冷。

网关更新（包括具有相同版本的新版本）保留附加的云计算机并安装当前的工作程序包。它的工作区、安装的软件包和桌面都保留在该计算机上。在更新完成之前，节点必须重新连接并支持当前的捆绑包安装程序。安装失败会使运行时更新处于挂起状态，并保留计算机以进行恢复；请参阅云工作人员故障排除。

当网关重新启动中断节点支持的轮转时，恢复会解决挂起的工作区结果并退出中断的轮转，同时保留其机器。继续会话使用新的执行权限，并且不会自动重播中断的工具调用。提供程序丢失后的显式停止、移动和清理仍然遵循正常的拆卸流程。失败的放置使其诊断可见；解决挂起的清理问题，然后重新分派并重试。请参阅会话生命周期和持久性。

离线配对的设备保持其位置处于活动状态并等待重新连接。 在网关上继续... 在设备离线时工作，从上次网关同步的工作区恢复并丢弃未同步的设备更改。如果机器消失，调节之间所做的更改可能会丢失；干净的停止，包括自动暂停，在释放之前进行协调。

仅存储库的检查点历史记录将保留到会话删除为止。当工作程序运行时，Files 和 diffs 使用其签出。停止后，更改的文件预览仍然可以从接受的检查点获取；编辑、未更改的上游文件和完整差异需要重新启动工作程序。发布可以使用接受的 Git 规范化检查点，而无需网关签出。请参阅死机中幸存的内容。

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