跳转至

会话托管

托管 OpenClaw 会话

macOS 菜单栏应用和无头节点主机可以通过相同的节点本地设置选择启用完整的 OpenClaw 会话托管功能:

{
  nodeHost: {
    workerRuns: { enabled: true },
  },
}

Warning

仅在你信任可作为共享 Gateway 基础架构的机器上启用会话托管。托管同意适用于设备,而非个人对它的所有权。现有的会话授权仍控制谁可以分派工作。

Gateway 会在持久化输入或启动 worker 之前,将插件 before_agent_run 策略应用于 OpenClaw 节点轮次。被阻止的轮次仅保留经过编辑的阻止消息,并使节点可用于下一轮次。该钩子能看到 Gateway 输入和历史记录;节点本地系统上下文随后才组装,且不包含在内。参见 钩子边界。

启用此设置后,请重启应用或节点主机。macOS 应用拥有一个配对的节点身份,并使用共享节点运行时进行会话托管;不要为同一台 Mac 启动第二个 CLI 节点。其原生摄像头、屏幕和桌面功能仍保留在该身份上。如果共享运行时无法启动,原生功能仍然可用,但会话托管不可用。

在已连接主机上批准更新的能力表面会自动刷新其会话托管声明和当前 worker 槽位。Gateway 会等待该新声明,然后才重新使主机可用;应用或节点主机进程无需重启。

当会话首次需要当前 worker 构建时,Gateway 会将其密封的 worker 工件发送到配对主机。节点验证精确的内容哈希,以原子方式发布工件,并在执行模式支持时对其进行预热。工件包含其完整的 JavaScript 依赖闭包;节点不会安装包或执行生命周期脚本。运行时块与工件一起被密封和验证,冷 worker 在加载轮次运行时之前完成准入。安装属于会话请求,并接收其取消信号。重连维护不会安装或预热 worker 构建。

安装后,持久节点会为每个 Gateway 命名空间保留一个当前 worker 工件,即使没有会话也是如此。较旧的构建仅在活跃或可恢复的部署需要它们时保留;正常维护会移除未被引用的构建。每次新的分派仍会验证已安装的工件,并在有效时复用,从而避免再次下载。已加入云端的节点保持其特定于执行模式的安装和保留生命周期。

你也可以通过 openclaw connect --service --session-host 一步完成服务主机的注册和启用。

对于进程作用域的主机,请在前台使用 openclaw connect <join-url> --session-host 进行注册。该加入 URL 是一次性的;在该进程停止后,使用 openclaw node run --session-host 重启主机,这会复用已保存的配对信息。参见 重新连接已配对的节点。

在 Control UI 的 New Session 中,具有写入作用域的操作员可以选择特定配对设备或 Auto。如果没有显式选择项目或文件夹,New workspace 会启动一个空的隔离工作区,且不需要用户 Git 仓库。所选 GitHub 仓库或 Gateway Git 检出仍是可选来源。OpenClaw 会创建会话拥有的托管工作区,使用确切的 deviceId 或 autoDevice: true 进行分派,并且仅在选择设备部署变为活跃后才发送第一轮。New Session 不会绑定 execNode 或浏览设备文件系统。

在 POSIX 主机上,OpenClaw 会将其托管工作区目录保持为私有(0700),即使主机使用 0002 的 umask 也是如此。重新打开时,现有节点拥有的工作区祖先目录会被收紧,因此传输可以在更新后恢复,而无需更改主机的 umask。已传输工作区内的文件保留其清单权限。

设备页面会在节点元数据中显示已验证的 Gateway 拥有的 worker 版本。如果当前工件缺失或验证失败,设备页面会显示 worker missing 警告;显式的新会话会安装当前包。此状态是观察性的且仅限重连范围:启动仍需要确切的持久收据和当前节点授权。

节点主机必须先支持当前的私有 worker-supervisor 协议方言,然后才能托管会话。较旧的已连接主机在会话选择器中仍然可见,但处于禁用状态。请在该设备上更新 OpenClaw 并重新连接;对于无头节点,运行 openclaw update,然后运行 openclaw node restart。Gateway 不会回退到节点的本地 OpenClaw 包或较旧的 supervisor 协议方言。

OpenClaw worker 轮次还要求节点支持 Gateway 捕获的 exec 策略。如果你先更新 Gateway,旧节点会针对 OpenClaw 会话显示 Update required,直到你更新并重新连接它们。它们的 Codex 远程执行和其他已批准的节点命令保留现有要求。先更新节点仍适用于较旧的 Gateway;节点仅会在 Gateway 理解该功能时通告此支持。

当节点在早于 2026.9.8 的 Gateway 中更新时,节点会保留该 Gateway 对其提供的 worker 包的 Skill Workshop 启动绑定。普通的归因聊天轮次继续工作,无需同时更新两侧。

当 Gateway 和节点主机都支持 node-worker-status-wait-v1 时,轮次完成会使用有界状态等待。节点会在确切轮次的终端结果被记录后立即唤醒等待中的请求;转录结算和 worker 清理所有权保持不变。此可选能力支持 Gateway/节点混合版本:可以先更新任一侧,而较旧的节点主机继续使用状态轮询。较新的节点仅向宣布该能力的 Gateway 通告 workerHost.statusWait: 1。重新连接时会重新协商支持。

托管轮次使用与 Gateway 本地轮次相同的预置工具表面和代理/会话策略。工作区文件和进程工具在节点上执行;Gateway 拥有的工具(包括网络搜索、记忆和会话发现)在 Gateway 上以当前轮次的实时权限和工具钩子执行。工具定义携带其执行位置,因此新增 Gateway 工具不需要单独的节点允许列表。

面向模型的工具使用与本地轮次相同的 Code Mode 或 Tool Search 呈现方式,包括 Gateway 已解析的模型设置和限制。Code Mode 在节点上运行,并按其声明的执行位置调用目录中的每个工具。其目录和待处理单元属于当前轮次;保留的工作进程在下一轮次会获得全新的呈现。节点工作进程在 Tool Search 中使用 tool_call,包括配置了目录模式时。

并发 Gateway 工具调用会等待现有的传输预算,因此更大的模型工具批次不会丢失调用。取消和心跳保持独立。

仅当节点声明其能力时,才提供 placement 本地的工具。不可用的 placement 或传输能力会记录在 Gateway 日志中。在节点上更新 OpenClaw 并重启以启用较新的本地工具。Gateway 操作使用匹配的已下载 worker bundle,并且不依赖于已安装的 supervisor 识别其工具名称。更新后的节点会继续公布旧版 Gateway 所期望的 Gateway 工具,从而在节点先更新时保留这些工具。

此设置允许在配对设备上进行受监督的会话轮次,包括 Gateway 拥有的工作区传输和结果核对。Gateway 在工作进程开始使用工具之前准备工具定义和文件系统策略。托管轮次遵循全局和代理特定的 tools.fs.workspaceOnly、tools.exec.applyPatch.enabled 和 tools.exec.applyPatch.allowModels,其会话权限模式优先级与本地轮次相同。工作区约束使用分配的节点工作区。模型读取预算和图像清理也来自 Gateway;工作进程不会从空配置中重建它们。

Gateway 在每轮次的 worker 准入响应中包含此工具目录和策略,包括复用 warm worker 进程时。保留的进程会收到当前轮次的目录和代次,因此一轮次不需要单独的发现请求。这使用现有的构建绑定的 worker 工具能力:worker 和 Gateway 必须运行相同的 bundle。经过认证的准入响应使用与 worker 推理相同的协商负载预算,因此完整工具目录不受较小的控制帧限制的上限约束。过大的目录会明确失败,而不是被截断。该目录不授予任何执行权限;每次 Gateway 工具调用仍会检查当前轮次的实时声明。

分配的作业空间内的 worker 回复附件会在工作区对账之前通过节点传输复制。相对和绝对的 MEDIA: 路径使用 worker 的字节,包括已完成的活动回复。该工作区之外的原始路径会产生远程文件附件错误;允许的托管媒体引用和 HTTP URL 保留其现有的传递策略。最终的聊天完成仍等待对账,并包含任何冲突摘要。

默认情况下,每个节点每个可用 CPU 核心有一个 worker 槽位。使用 nodeHost.workerRuns.capacity 配置槽位数。超出容量的启动会等待最多 10 秒以获得持久槽位。仅被空闲 worker 占用的槽位可被回收用于新工作;活动轮次和后台命令保留其槽位。当没有空闲或可回收的槽位时,节点仍可用于状态查询和取消,但不会被选中用于新的会话轮次。

容量、host-stat 和 skill-bin 更新不会中断活动的节点工作,也不会改变其配对权限。此行为需要更新的 Gateway;节点配置和已存储的配对保持不变。

轮次结束后,OpenClaw 可以将其 worker 进程保留最多两分钟,以便立即进行的后续操作无需重新加载运行时。计时器在 worker 确认轮次清理完成后开始。每个节点最多保留两个空闲 worker,并受其配置容量的限制;当需要空间时,它会首先淘汰空闲时间最长的 worker。空闲 worker 仍会使用内存:即使小型会话,每个保留的 worker 及其监督进程也会占用数百 MiB,在大量工作后可能出现更大的堆。Worker 由轮次启动,绝不会仅通过激活 placement 启动。

空闲复用需要 Gateway、节点和已安装的 worker bundle 通过 node-worker-idle-retention-v1 能力提供支持。较旧的组合保留其现有的后台命令保留行为。每次复用的轮次仍会获得全新的凭据、准入、历史记录、执行策略和轮次配置文件。进入空闲状态会关闭轮次连接,加入其可写清理流程,并移除已完成轮次的临时配置文件。后台命令仍受保护,不会被空闲逐出或超时;其现有环境和凭据有效期持续到它们完成。

空闲保留使用与后台命令保留相同的工作区对账契约,包括进程模式和容器模式。这两种契约都不会挂起 worker 进程。工作区清单的捕获、验证、更新和最终验证会检测并发变更;冲突或失败的 fence 会使用现有的对账和恢复流程。保留已结束的运行时不会授予其另一轮次的权限。

断开连接、节点关闭、更新暂停或 placement 拆除会通过正常的进程树或容器清理来淘汰空闲 worker。重新连接会等待该清理完成后再公布新的容量。如果空闲清理失败,正在运行的 supervisor 会保留其槽位并在两分钟后重试。Stop、Move 和 reclaim 保留其精确的 placement 所有权检查;空闲 worker 在崩溃或重启后永远不会被恢复。聊天 Stop 会取消活动工作,并且在没有轮次运行时不会清除空闲 worker。使用 placement Stop 或 reclaim 可立即释放它。没有单独的 idle-retention 设置。

停止一个活跃的托管回合时,即使 worker 在停止过程中遇到错误,也会记录这个已接受的取消。Worker 诊断信息会单独保留关闭失败信息。只有在进程树或容器完成清理之后,worker 槽位才会变为可用。

当前的 Linux 和 macOS 节点主机在应用 worker 或节点主机崩溃时,也会保留该清理所有权——前提是 Gateway 提供的 worker 捆绑包支持进程谱系。要获得此保护,请更新 Gateway,并更新和重启节点主机;仅安装新的 worker 捆绑包不会更新节点的 supervisor。恢复过程会在前一个所有者完成停止其命令期间继续保持容量被占用。升级后的节点主机为较旧的 worker 捆绑包保留已释放的启动消息和分离的进程组所有权。

已安装的节点主机单独打包 POSIX 启动辅助程序,以减少每个回合的启动工作。更新并重启节点主机以获得此改进。worker 在开始回合前仍会等待其持久化的启动回执;清理也会继续持有其 worker 槽位,直到进程树消失。

选择器从 environments.list 派生每一行设备。每个选定的运行时都需要一个可用、已连接且已配对的会话主机。OpenClaw worker 回合还要求具备已捕获的 exec-policy 支持,以及有效且精确的 worker 槽位——其中至少有一个空闲或可回收的空闲槽位。Codex 配对设备执行会直接启动其 exec-server,因此不会消耗或要求 worker 槽位。它所需命令必须出现在节点有效的 invocableCommands 中,而不仅仅是其声明的能力中。只有已批准的配对和 Gateway 命令允许列表都授权时,声明的命令才可用。已连接的非主机、不符合条件或已饱和的主机、需要更新的设备以及不可用的主机会保持可见,但会被禁用并附有可操作的原因。通过 openclaw connect --service --session-host 或 nodeHost.workerRuns 设置启用托管,然后重启节点主机。需要更新的主机必须先升级并重启,之后才能被选择。

在节点清单刷新期间,或者刷新失败时,选择器会保持已知设备可见,但会禁用远程选择和 Start(开始),直到新的清单到达。本地仍可被选择;缓存的 worker 槽位绝不会授权新的远程会话。

选择 Auto(自动)让 Gateway 选择符合条件的、已配对且已连接的会话主机。对于 OpenClaw worker 回合,它首先偏好已受理工作相对于其 worker 容量较少的主机。然后,在考虑仍在启动中的派发之后,比较空闲和可回收的空闲 worker 槽位,并通过设备 ID 打破剩余平局。仅会话的放置本身并不会预留 worker 槽位。不消耗 worker 槽位的运行时,则选择设备 ID 最低的符合条件主机。

如果某个被选中的主机在工作区准备开始之前变得不符合条件,Gateway 会在确认任何失败的分配已被清理之后,依次尝试下一个排名的主机,总共最多三个主机。其他派发失败会立即返回;Auto 绝不会重放工作区准备或已开始的工作。一旦工作区准备被接纳,另一个回合占满该主机的槽位并不会取消它;当会话启动回合时,节点会检查物理容量。在整个准备过程中,节点身份和命令授权仍会持续接受检查。

如果没有符合条件的主机,错误会说明:是没有已配对的会话主机、主机已断开连接或已达容量上限、主机需要更新,还是所选运行时不受支持。派发响应会标识被选中的设备。

当已知会话主机断开连接时,其配对设备记录仅保留最后接受的 current-v6 托管同意。离线行保持可见,并以“不可用”状态禁用。当前已禁用或为空的 v6 发布记录为 false;较旧的 v1-v5 以及需要更新的方言不会覆盖最后一项当前事实。已连接的清单始终优先于已存储的历史记录;缺失的存储值表示 false;精确 worker 槽位绝不会被持久化,也不会显示为离线容量。

如果设备离线,其活动放置仍保持活动:可用性以进程当前状态为准,而不是终态放置状态。sessions.list 和 sessions.describe 会投射 runner: { kind: "device", status: "offline" },直到那个确切的 current-v6 节点 runner 重新连接。因此,Gateway 重启后,在重新连接之前,活动设备放置会显示为离线;当前清单随后会将投射更改为 available,并发出会话刷新。精确 worker 槽位只限制其运行时消耗 worker 槽位的新放置;它们不会影响 Codex 远程执行或现有会话的可用性。

Control UI 显示 Device offline(设备离线),默认情况下会继续等待,而不会放弃放置、工作区或权限。设备返回后重试下一个回合。Continue on Gateway…(在 Gateway 上继续…)是一个独立的破坏性选项:它会隔离设备所有者,并从最后一个 Gateway 同步的工作区继续,且不会重放被中断的回合。未同步的设备文件和进行中的工作可能会丢失。配对的节点在其精确记录的断开连接之后会休眠 14 天;在该边界处,其旧的 worker 环境会被视为已不存在,会话放置会正常对账。配对本身仍然保留,因此之后重新连接可以配置全新环境。没有精确节点断开历史记录的旧式配对会以防故障方式保留,而不会因不相关的设备活动而过期。删除设备配对、静默清除已被取代的配对,或仅删除其节点角色,都会先使客户端失效,然后执行有针对性的环境和放置对账;显式删除会等待凭据隔离完成后再返回成功,周期性清理会重试失败的提供者或放置清理。

当设备 runner 不可用时(包括会话托管被禁用之后),Gateway 会暂停非强制性磁盘空间检查,并保留该放置的最后一次样本。检查会在当前 runner 重新连接后的下一次定期清理时恢复。禁用托管不会丢弃会话的工作区。

参见 Anthropic:跨计算机的 Claude 会话,了解 Control UI 的行为和存储来源。

在容器中隔离托管 worker 会话

默认情况下,托管的 OpenClaw worker 会话直接运行在配对的节点上。在该节点上将 nodeHost.workerRuns.isolation 设置为 "container",即可让每个 worker 运行在各自的容器中:

{
  nodeHost: {
    workerRuns: {
      enabled: true,
      isolation: "container",
      // Optional: use a digest-pinned, private-registry, or preloaded image.
      // containerImage: "registry.example.com/openclaw/node:24.21.0-slim",
    },
  },
}

更改任一设置后,请重启节点主机。隔离默认值为 "none",保留现有的直接进程行为。该设置在节点本地强制执行;Gateway 无法静默禁用它,也无法回退到未隔离的 worker。

容器隔离支持 Linux 和 macOS 节点主机;Windows 不受支持,因为原生 Windows 路径无法在容器内挂载到其原始路径。节点必须具有可用的兼容 Docker 的容器引擎。OpenClaw 会先尝试 docker CLI,包括由 Docker 支持的 OrbStack 安装,然后尝试 podman。所选引擎和守护进程会在节点主机启动时以及每次创建容器前进行检查。如果平台不受支持、两个引擎都不可用,或守护进程发生变化,会话托管或受影响的启动会显式失败,而不是回退到未隔离的 worker。请安装或启动引擎,验证 docker version 或 podman version,然后重启节点主机。

每次容器启动前,守护进程身份重新验证最多允许 30 秒。如果引擎命令超时,启动错误会指明引擎和操作(例如 docker info)及其截止时间。它会省略命令参数和环境变量值。重试前,请针对所选守护进程检查该操作。

默认镜像为 node:24.21.0-slim;如果镜像尚不存在,引擎会在首次使用时拉取它。设置 nodeHost.workerRuns.containerImage 可选择摘要固定镜像、私有注册表镜像,或引擎中已可用的镜像。镜像必须在其标准可执行文件搜索路径上提供受支持的 Node.js 24.16+ 或 26.1+ 运行时。如果镜像无法拉取、无法访问,或未提供合适的 Node.js 运行时,该会话启动会显式失败;它绝不会作为裸主机进程重试。在离线或受限节点上托管会话前,请预加载镜像或配置注册表访问权限。当 OpenClaw 更新其依赖项时,默认镜像可能会更新。在升级离线节点前,请预加载新的默认镜像,或将 nodeHost.workerRuns.containerImage 设置为该节点上已缓存的受支持镜像。例如,已缓存的 node:24.19.0-slim 仍然受支持,并且可以显式选择。现有的显式镜像设置会被保留;在升级 OpenClaw 前,请替换不受支持的 Node 镜像。Worker 启动需要受支持的运行时;较旧版本可能在运行时诊断运行前失败。

每个 worker 容器仅接收两个主机绑定挂载:其已验证的 worker bundle 根目录为只读,其分配的会话工作区为读写。两者都挂载在其原始绝对主机路径上,因此密封的 bundle 和工作区描述符保持有效;会话工作区也是容器工作目录。OpenClaw 仅传递现有的冻结的、非机密的 worker 环境允许列表,并且不添加其他主机挂载。容器隔离保护主机文件系统的其余部分并隔离 worker 进程,但 worker 仍可以修改其分配的工作区并连接到 Gateway。

容器使用引擎的正常出站网络,并且必须能够访问 Gateway worker WebSocket 端点。在节点主机上可用的 Gateway 地址(例如 127.0.0.1 或 localhost)当被 worker 使用时会指向容器内部;请改为配置一个可从容器网络访问的 Gateway 地址。如果 Gateway 需要自定义证书颁发机构,NODE_EXTRA_CA_CERTS 必须指向已位于已挂载 bundle 或会话工作区内的证书;OpenClaw 不会为其挂载另一个主机路径。需要访问仅限主机的浏览器状态的浏览器分配在容器隔离会话中不受支持。

取消和围栏会终止容器本身,而不仅仅是容器引擎客户端。节点主机会记录容器的持久引擎和容器身份,在重启协调期间检查该身份,并移除标记为同一 Gateway 的孤立 worker 容器。如果节点主机进程意外退出,正在运行的容器可能会存活到下一次节点主机启动;如果必须保持该清理窗口较短,请将节点主机置于可重启的服务之下。

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