会话托管

托管 OpenClaw 会话¶

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

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

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

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

当会话首次需要当前 worker 构建时，Gateway 会将其密封的 worker 工件发送到已配对的主机。节点会验证精确的内容哈希，原子地发布该工件，并在执行模式支持时对其进行预热。该工件包含其完整的 JavaScript 依赖闭包；节点不会安装包或执行生命周期脚本。安装属于会话请求，并接收其取消信号。重连维护不会安装或预热 worker 构建。

安装完成后，持久节点会为每个 Gateway 命名空间保留一个当前 worker 工件，即使没有会话也是如此。旧构建仅在某个活动或可恢复的放置需要它们时保留；常规维护会移除未引用的构建。每次新的分派仍会验证已安装的工件，并在有效时复用它，从而避免再次下载。云注册节点保留其各自按执行模式区分的安装和保留生命周期。

你也可以使用 openclaw connect --service --session-host 一步注册并启用服务主机。

对于进程范围的主机，使用 openclaw connect <join-url> --session-host 在前台注册。加入 URL 是一次性的；该进程停止后，使用 openclaw node run --session-host 重启主机，它会复用已保存的配对。参见 重新连接已配对的节点。

在 Control UI 的新会话中，具有写作用域的操作员可以选择特定的已配对设备或 自动。如果没有明确选择项目或文件夹，新建工作区 会启动一个空的隔离工作区，而不要求用户 Git 仓库。所选的 GitHub 仓库或 Gateway Git 检出仍为可选来源。OpenClaw 会创建一个会话拥有的托管工作区，使用精确的 deviceId 或 autoDevice: true 进行分派，并且只有在所选设备放置变为活动后才发送第一轮。新会话不会绑定 execNode 或浏览设备文件系统。

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

设备页面会在节点元数据中显示经过验证的 Gateway 拥有的 worker 版本。如果当前工件缺失或验证失败，设备页面会显示 缺少 worker 警告；显式的新会话会安装当前捆绑包。此状态是观察性的且以重连为范围：启动仍需要精确的持久回执和当前节点权限。

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

OpenClaw worker 轮次还需要支持 Gateway 捕获的 exec 策略的节点。如果你先更新 Gateway，较旧的节点会为 OpenClaw 会话显示 需要更新，直到你更新并重新连接它们。它们的 Codex 远程执行和其他已批准的节点命令保留其现有要求。先更新节点仍与较旧的 Gateway 兼容；节点仅在 Gateway 理解该支持时才通告此支持。

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

比节点已安装的 OpenClaw 更新的 worker 工具（例如 presence）仅在节点的 supervisor 声明支持时提供。较旧的节点继续托管 OpenClaw worker 轮次，但不提供这些工具。请更新节点上的 OpenClaw 并重启它以启用它们。

此设置会在已配对设备上启用受监督的会话轮次，包括 Gateway 拥有的工作区传输和结果协调。默认情况下，每个节点每个可用 CPU 核心有一个 worker 槽位。使用 nodeHost.workerRuns.capacity 配置槽位数量。超出容量的启动会等待最多 10 秒以获取持久槽位。仅由空闲 worker 占用的槽位可以被回收用于新工作；活动轮次和后台命令保留其槽位。当没有空闲或可回收槽位时，节点仍可用于状态和取消，但不会被选择用于新的会话轮次。

在一个回合结束后，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 可立即释放它。没有单独的空闲保留设置。

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

当前的 Linux 和 macOS 节点主机在应用 worker 或节点主机崩溃时，也会保留该清理所有权，前提是 Gateway 提供的 worker bundle 支持进程谱系。更新 Gateway 并更新和重启节点主机以接收此保护；仅安装新的 worker bundle 不会更新节点的 supervisor。恢复过程会在前一个所有者完成停止其命令期间保持容量占用。升级后的节点主机会为旧 worker bundle 保留已发布的启动消息和分离进程组所有权。

已安装的节点主机将 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 打破。仅会话的 placement 不会保留 worker 槽位。不消耗 worker 槽位的运行时改为选择设备 ID 最低的合格主机。

如果所选主机在工作区准备开始之前变得不合格，Gateway 会在确认任何失败的分配已清理后，尝试下一个排名靠前的主机，最多总共三个主机。其他分发失败会立即返回；Auto 永远不会重放工作区准备或已开始的工作。一旦工作区准备被准入，另一个填充主机槽位的回合不会取消它；节点在会话启动回合时检查物理容量。 节点身份和命令授权在整个准备过程中仍会检查。

如果没有合格主机，错误会说明是没有配对会话主机、主机断开连接或达到容量、某个主机需要更新，还是所选运行时不受支持。分发响应会标识所选设备。

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

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

Control UI 默认显示 设备离线 并等待，而不会放弃 placement、workspace 或权限。设备恢复后，重试下一轮。 在 Gateway 上继续… 是一个独立的破坏性选择：它会隔离设备所有者，并从最后一次 Gateway 同步的 workspace 继续，而不重放被中断的轮次。未同步的设备文件和进行中的工作可能会丢失。配对节点在其确切记录的断开连接后保持休眠 14 天；到达该边界时，其旧的 worker 环境被视为已消失，会话 placement 会正常协调。配对本身仍然保留，因此稍后重新连接可以配置一个全新环境。没有确切节点断开历史的旧配对会作为 fail-safe 保留，而不是因无关设备活动而过期。移除设备配对、静默修剪已被取代的配对，或仅移除其节点角色，会先使客户端失效，然后运行有针对性的环境和 placement 协调；显式移除会等待 credential fence 完成后再返回成功，周期性 sweep 会重试失败的 provider 或 placement 清理。

请参阅 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 根目录为只读，其分配的会话 workspace 为读写。 两者都挂载在其原始绝对主机路径上，以便密封的 bundle 和 workspace 描述符保持有效；会话 workspace 同时也是 容器工作目录。OpenClaw 仅传递现有的已冻结、 非机密 worker 环境允许列表，并且不添加其他主机挂载。 容器隔离保护主机文件系统的其余部分，并隔离 worker 进程，但 worker 仍然可以修改其分配的 workspace 并连接到 Gateway。

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

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