Cloud Sessions
A cloud session is an ordinary session whose coding work runs on another machine. It appears in the sidebar, streams into chat, and keeps its transcript exactly like a local session — the Gateway stays the owner of the conversation, the reconciled workspace, model credentials, and placement records, while commands, file edits, and tool work execute remotely. The session and its durable state survive a remote failure. Reclaimed or suspended cloud workers restart on the next message. A previously active worker that fails also restarts on the next message once cleanup is complete and its saved workspace is ready. Gateway updates retain attached cloud machines and refresh their worker runtime in place. An offline paired device keeps its placement and waits for the device to return.
Sessions can run in three places, and every one of them uses the same session, the same chat, and the same Place picker:
| Destination | The machine | Best for | Scope to dispatch |
|---|---|---|---|
| Gateway(默认) | 运行 openclaw gateway 的主机 |
日常会话 | — |
| 配对设备 | 你自己的硬件,通过 openclaw connect 连接一次 |
闲置的 Mac、构建机、你已有的服务器 | operator.write |
| 云端工作器 | 通过 Crabbox 租用的临时机器 | 突发容量、长时间任务、与你自己机器的隔离 | operator.admin |
在所有远程放置中,模型推理仍然通过 Gateway 代理——提供方凭据永远不会到达远程机器——已完成的工作会作为已接受的仓库检查点或 Gateway 源托管工作树中的变更保留在 Gateway 中。OpenClaw 运行时(worker-turn)和 Codex(remote-exec)都可以使用相同的目标。
会话是客户端所连接的对话。设备是已配对的硬件(协议中的 node);runner 是表示执行主机的内部术语。放置决定工作在哪里运行,而隔离描述的是该主机上的边界,而不是另一个目标。
在没有 Gateway 检出时启动¶
在 New Session 中,在 Place 中选择一个 GitHub 仓库,选择配对设备或云配置,并可选地在 Remote checkout 下设置源引用。云配置还可以在 Place 中提供操作系统和机器类别选项;机器列表会跟随所选操作系统。Gateway 记录源;node 获取它并创建会话分支。Gateway 上不会创建项目克隆或工作树。启动会等待放置处于活动状态后再发送提示词,并且重试/重新加载恢复会保留仓库和引用。
OpenClaw 和 Codex 都使用受管理的 node 连接来准备仓库。仅支持 SSH 载体的提供方无法承载此源。改为选择现有的 Gateway 文件夹会保留托管工作树流程,包括本地更改和未发布的提交。
首次准备会固定解析出的上游提交。已接受的更改会作为不可变的检查点在停止和替换后继续存在;恢复仍然取决于固定的上游提交保持可用。显式的 Move session… → Gateway 会获取该源并物化一个托管工作树。有关 RPC 序列和设置权限,请参阅调度与恢复。
图像与附件¶
通过常规聊天编辑器附加图像和 PDF,包括在现有云端会话的后续轮次中。Gateway 准备原生图像输入,包括从扫描 PDF 渲染出的页面。Codex 通过其 Gateway 端应用服务器接收图像输入。它的 remote-exec 放置会在执行前为远程文件工具暂存受管理的原始文件;这些临时副本不参与工作区协调。下面的输入保留规则适用于 OpenClaw worker-turn 会话。
OpenClaw worker-turn 会话接受图像,包括纯图像消息以及内联和卸载图像的排序混合。对于支持视觉的模型,Gateway 使用与本地会话相同的图像清理、排序和历史裁剪,从其受管媒体中水合当前输入和近期回放。纯文本模型会收到附件文件路径,但没有原生图像输入。Gateway 保留规范的转录和原始附件引用;只有工作器的输入会收到远程文件路径。
调度后发送的附件会通过经过身份验证的传输通道复制到工作器工作区。这需要当前的 node-host 安装以及工作器 bundle;使用前请更新配对设备或云配置的 node 包。文件工具可以读取其源文件,包括非图像附件。副本不会替换活动工作区,也不会覆盖先前工作器对同一附件的编辑。在传输和启动之前会检查放置和轮次所有权;如果当前附件不可用或过大,会产生错误,而不是静默丢弃图像。不可用的历史来源(包括因配置的附件保留而过期的原始文件)会在回放暂存时被省略并给出警告,以免阻塞新的轮次。规范的转录引用和现有的私有副本保持不变。
原始输入使用 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 限制。工作者回合没有原生转向传输:回合期间收到的消息使用现有的排队后续路径,并保留其图像和媒体元数据。
配对的设备:将你自己的硬件作为会话主机¶
使用一条粘贴的命令配对任意机器,然后将其选择用于会话托管:
该设备持有到 Gateway 的出站连接,通告工作者槽位(默认每个 CPU 核心一个,可通过 nodeHost.workerRuns.capacity 调整),并可选地在兼容 Docker 的容器中运行每个托管会话(nodeHost.workerRuns.isolation: "container")。离线的设备会保留其活动的放置——会话会等待它重新连接,而不是丢失工作。
节点主机在瞬时传输丢失后会重新连接。一个 worker 子进程有 120 秒的有界准入窗口。如果该窗口在回合开始之前到期,Gateway 可以启动另一个子进程,总共最多五次尝试(约十分钟加上退避),并在原始回合超时内完成。启动重试使用带抖动的指数退避;每次尝试在节点启动日志中保留自己的最终结果和原因。凭证和构建拒绝是终止性的,已经启动的工作绝不会被此策略重播。
如果日志中标记为终止的 worker 已释放其回合声明,但拆除过程停滞,卡住的会话恢复会在下一个诊断周期、30 秒清理宽限期后记录该回合失败。仍持有声明的活跃 worker 和回合不受影响。Gateway 重启时,针对失败放置的孤儿工作区清理在就绪后于后台运行;所有权栅栏和待处理的工作区结果恢复仍在就绪前运行。
参见 Nodes 了解配对、容量、隔离和离线行为,并通过 Connect 了解 CLI。
云 worker:通过 Crabbox 租用机器¶
在 cloudWorkers.profiles 下配置一个配置文件,内置的 Crabbox 插件会按需在多个云后端(AWS、Hetzner 等)之间供应机器,运行你的设置命令,将这台机器注册为临时节点,并在会话停止时拆除所有内容。这台机器在设计上是一次性的:其上不保留常驻凭证,持久状态保留在 Gateway 上。
有关配置文件、要求、调度、在目的地之间移动会话以及安全模型,请参阅 Cloud Workers。
查看会话桌面¶
从会话中打开 桌面 以直接连接到其执行机器。云会话选择其 worker 桌面;配对设备上的会话选择该设备。聊天面板显示连接进度或重试操作,而不是提供无关的机器。弹出窗口将会话保留在其链接中,因此两个查看者都会跟随放置变化,并在会话移动或停止时与之前的机器断开连接。已停止的云会话不会将任一查看者切换到 Gateway 桌面。
如果你在桌面选择器中选择了一个来源,当会话的放置变化时,面板会保留该选择。在新窗口中打开桌面会打开该来源,并请求面板当前的只读或控制模式。桌面链接不包含凭证,也不授予控制权;新查看者仍会执行其正常的身份验证和权限检查。
机器必须已经支持桌面查看。对于云 worker,请启用 Cloud Worker Desktop 实验室和桌面配置文件设置。打开桌面会以只读模式启动,并且不会改变机器的权限或代理的工具策略。命令面板中的 Desktop 操作在聊天页面上也会跟随当前会话。在聊天之外,它会打开机器选择器。
要从本地剪贴板输入文本,请先取得控制权并选择键盘,然后在 macOS 上按 Command+V 或在 Windows 和 Linux 上按 Ctrl+V 粘贴。键盘字段会将粘贴的文本发送到远程桌面;指向桌面画布的快捷键仍然在远程机器上操作。键盘输入在控制连接就绪前保持禁用。
桌面与计算机控制¶
支持桌面的云会话将同一台机器用于聊天桌面面板和代理的 computer 工具。启用 Cloud Worker Desktop 实验室,并配置一个带有 settings.desktop: true 的 Crabbox 配置文件。OpenClaw 会在已供应的桌面会话中启动 worker 的 CUA 提供程序;代理无需发现或选择配对的计算机。OpenClaw 和 Codex 会话都使用此绑定。配对设备会话则使用该设备已启用的 Computer Control 提供程序。
OpenClaw worker 回合会为其本地 exec 命令保留节点主机的显示和桌面会话环境。在启用桌面的 Linux worker 上,使用 background: true 启动 GUI 应用程序,以便在其运行期间继续使用 computer。
使用支持视觉的模型,并采用允许 computer 工具的配置文件。对于 coding 配置文件,将 computer 添加到 tools.alsoAllow。绑定的桌面在默认远程会话沙箱策略下可用;显式沙箱允许列表和拒绝规则仍然适用。在代理工作时观察“桌面”面板。手动接管云桌面会暂停代理输入。当你要求代理恢复时,它可以使用 computer 并指定 action: "take_control";查看器切换为仅查看模式,代理会收到一张新的截图。这一显式操作使用已受理运行的现有计算机控制权限,无需查看器单独发放的交接令牌。你可以随时再次接管控制。中断的输入不会重放。
工作进程记录保留截图。Codex 在代码模式之外直接暴露计算机工具,因此截图结果会以图像形式到达模型。为了将后续模型请求保持在传输限制内,OpenClaw 可以用模型上下文中的文本标记替换较旧的、已处理的图像,同时保留当前计算机帧和未处理的图像。不透明的提供商重放保持不变;如果其所需的上下文无法容纳,回合将失败并附有恢复指导。
计算机控制保持绑定到已受理的回合、放置、节点连接和提供商。如果 OpenClaw 工作进程断开连接,其计算机执行即使在工具调用之间也会关闭;重新连接后,启动新回合以重新获得计算机控制。其他持久会话操作仍可完成。停止或更换机器会使旧的工具句柄失效;不可用的桌面永远不会选择另一台已连接的计算机。一次性云桌面仍然不会出现在常规配对计算机选择器中。支持的操作用法参见 计算机使用,设置和查看权限参见 云工作桌面。
OpenClaw 工作进程会先等待计算机和浏览器清理完成,然后请求 Gateway 确认其回合即将结束。如果在助手已经作答之后清理失败,回合会报告失败,并附带有限且经脱敏的诊断信息,同时将答案保留在记录中。Gateway 会在工作区协调过程中保留已确认的失败,包括任何额外的协调错误,并且不会在另一个模型上自动重放该回合。重试前检查桌面和工作区:清理失败不会撤销之前的输入。
对于 remote-exec 回合,计算机清理会在工作区协调之前完成。如果清理失败,OpenClaw 会保留捕获的回复、使用情况、投递证据以及任何更早的错误或中断,添加有限范围的清理诊断信息,并且不会自动重放该回合。工作区恢复失败会同时报告这两个问题。安全敏感资源的清理仍然会拒绝完成,而不会变成建议性警告;重试前解决报告的清理问题。
跨设备自动负载均衡¶
你不必手动选择设备。在位置选择器中选择 Auto(最不繁忙的设备)— 或使用 autoDevice: true 调度 — 会自动选择一个已配对的会话主机。OpenClaw worker-turn 放置首先会优先选择已受理工作相对其工作进程容量较少的主机。随后,在计入仍在启动中的调度后,会比较空闲工作进程槽位;剩余并列按设备 ID 打破。仅会话的放置本身不会预留工作进程槽位。Codex remote-exec 放置不消耗工作进程槽位,因此合格主机仅按设备 ID 排序。当没有主机合格时,错误会确切说明原因:没有配对会话主机、全部断开连接,或全部容量已满。
如果所选设备在工作区准备开始前变得不合格,Auto 会在确认失败的分配已完全清理后,尝试最多三个已排序的主机。它不会重放工作区设置或已开始的工作。一旦工作区准备被受理,另一个回合填满设备槽位并不会取消它;节点会在会话启动回合时再次检查物理容量。在整个准备过程中,节点身份和命令授权持续受到检查。
休眠与唤醒:空闲挂起和热镜像¶
两个配置文件设置将云工作进程从常开机器转变为空闲时休眠的计算资源:
suspendAfter: "2h"— 当会话空闲达到该时长后,Gateway 会执行与 停止云工作进程… 相同的安全停止:先协调工作区,然后释放机器。挂起期间,你只需为保留的快照存储付费。下一条消息会自动配置替换机器 — 无需按下任何按钮。settings.warmImage— 准备项目的已提交检出和节点运行时,然后在节点注册前捕获可复用的镜像。同一项目和配置文件的后续会话可以从该镜像启动;第一个会话不必先停止。仅限 Linux,并且当有效机器类别已知且setupEnv为空时默认启用。将主机环境转发到 setup 的配置文件仅在你明确选择加入时才捕获,而settings.warmImage: false会使任何配置文件保持冷启动。
对于来自 Gateway 检出的会话,关联的工作树共享稳定的项目身份。热镜像保留原始的已提交种子和已验证的运行时,而每个新会话获得新的注册及其当前工作区文件。匹配的种子会跳过 origin 访问和完整的 Git pack 传输,包括私有或未发布的提交。更改的提交会准备新种子,并可以刷新项目的镜像。仅仓库会话改为在节点上获取,可以复用机器/运行时镜像和已验证的 Git 种子;它们不会从 Gateway 检出准备项目镜像。首次调度包括准备工作和任何必要的捕获;提供商启动和捕获成本仍然决定总体延迟。
每个分配在重试和 Gateway 重启期间都会保留其原始冷启动或精确检查点选择。如果升级报告了旧的 warm-image 状态,请遵循 升级 warm-image 状态;Doctor 会保留已知镜像和清理义务,并报告原始选择未知的租约的手动恢复步骤。
挂起不会中断工作:具有活动轮次、排队消息或未协调结果的会话会被跳过,并在下一次扫描时重新检查。请参阅 Cloud Workers 中的 profile 字段,了解成本、捕获边界和先决条件。
保留在 Gateway 中的内容¶
转录、最近协调的工作区文件、放置历史以及所有提供商凭据在所有放置中都随 Gateway 保留。在正常回收或空闲挂起之后,下一条消息会配置替代资源——如果存在镜像则为热启动,否则为冷启动。
Gateway 更新(包括相同版本的新构建)会保留已附加的云机器,并就地安装当前 worker bundle。其工作区、已安装软件包和桌面保留在该机器上。节点必须重新连接并支持当前 bundle 安装程序,更新才能完成。安装失败会使运行时更新保持待定,并保留机器用于恢复;请参阅 cloud worker 故障排除。
当 Gateway 重启中断由节点支持的轮次时,恢复会结算待处理的工作区结果,并退役被中断的轮次,同时保留其机器。继续会话会使用新的执行权限,并且不会自动重放被中断的工具调用。显式 Stop、Move 以及提供商丢失后的清理仍遵循其正常拆除流程。失败的放置会保持其诊断信息可见;解决待处理清理,然后重新调度并重试。请参阅 会话生命周期和持久性。
离线配对设备会保持其放置处于活动状态并等待重新连接。在 Gateway 上继续… 在设备离线时可用,它会从最后一次 Gateway 同步的工作区恢复,并丢弃未同步的设备更改。如果在协调之间机器消失,在协调之间所做的更改可能会丢失;正常停止(包括自动挂起)会在释放机器之前进行协调。
仅仓库的检查点历史会保留到会话删除。当 worker 运行时,文件 和差异使用其检出。在 Stop 之后,已接受检查点中的更改文件预览仍可用;编辑、未更改的上游文件和完整差异需要重启 worker。发布可以使用已接受的 Git 规范化检查点,而无需 Gateway 检出。请参阅 机器失效后保留的内容。
Reset 会保留仓库和已接受的更改,但会结束上一个会话生命周期中未完成的发布请求。重置后,请审查保留的更改并再次请求发布。现有 GitHub 提交和拉取请求保持不变。
相关¶
- Cloud Workers — profile、调度、Move、安全模型
- Nodes — 配对、会话托管、容量、容器隔离
- Control UI — Place 选择器和会话徽章
- Connect — 单命令设备入门
- Managed worktrees — 源自 Gateway 检出的会话的隔离
- Sandboxing — 改为减少本地执行的影响范围
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw