openclaw worker¶
openclaw worker 是 Gateway 拥有的启动器在已准备好的云或配对节点 worker 环境中启动时使用的受限运行时入口点。
它不是用于手动注册 worker 的通用命令。
Gateway 会通过已注册节点的经过身份验证的连接安装匹配的 OpenClaw bundle。worker 启动器使用准备好的分配启动此命令,然后 worker 通过其自身的经过身份验证的出站 WebSocket 连接回 Gateway,作为专用的 worker 角色。
启动契约¶
该命令从标准输入中读取恰好一个有界的 JSON 启动信封。 信封包含 Gateway worker 端点、铸造的 worker 凭据、bundle 和协议身份、owner epoch、唯一分配的 session 和 turn,以及该 turn 被授权的精确 worker 本地工具名称。Gateway 在交接前根据当前策略解析出最终工具集;原始配置和 scheduled-owner 身份永远不会进入 worker 信封。 凭据从不通过命令行参数接受,并且本页有意不提供凭据或手工编写的信封示例。
节点 supervisor 使用一个私有托管入口点,可以在后台进程仍然存在时,将连续的 turn 接纳到同一环境中。每个 turn 仍然会收到一个新的有界信封、Gateway 连接和工具权限。 上述独立命令仍然是单 turn 入口点。
停止节点 worker 环境会取消待处理的 admission,并尝试清理其工作区进程、托管 worker 和持久启动 owner。一个清理 owner 的失败不会跳过其他 owner。Stop 在这些尝试完成后报告清理错误;清理仍未确认的启动会保留其容量预留,直到恢复成功。在 Stop 等待被跟踪的 worker 清理稳定时,同一环境不能接纳另一个 turn。
如果初始化失败,独立的清理仍可能完成,但在初始化成功之前,节点不会通告可用容量。
当失败 turn 的清理记录了一个终止 placement 时,session 描述会刷新为 failed 并附带恢复原因,而不是保留 draining。
在当前 Linux 和 macOS 节点主机上,启动日志会识别 worker 的进程 owner;应用程序 worker.mjs 作为其子进程运行。owner 会在应用程序崩溃后存活,并在释放容量之前保留嵌套命令清理。
节点主机重启后,恢复过程会短暂观察该确切 owner,而不会终止其清理观察者。未完成的清理会保留其 slot,同时其他空闲 slot 仍然可用。节点 supervisor 会继续观察该清理,并在记录的 lineage 完成且物理进程树消亡后自动归还 slot。关闭 supervisor 会放弃并加入其观察,而不会释放未完成的 ownership。在保留 turn receipt 期间,状态、启动 replay 和取消共享同一恢复;已完成的 turn 结果保持不变。此保护需要
更新的节点主机以及当前 worker bundle;仅更新 Gateway
不会替换旧节点的监督路径。
启动必须在每种完整序列化形式中都适合 25 MiB:节点调用事件和托管 worker 输入行,包括节点的连接端点。 Gateway 在需要时修剪较旧的完整 turn,但不会丢弃最新的 provider replay checkpoint。如果该 replay 单元无法容纳,turn 会在交接前失败,并带有可见的重试说明。托管行限制不包括其最终换行符;独立 stdin 计算每个字节。
如果信封无效、凭据被拒绝、bundle 或协议特性不匹配,或者 session 和 owner epoch 不再当前,admission 会失败关闭。缺失、重复或未知的工具名称也会使信封无效。操作员应通过云 worker 编排器启动 worker,而不是直接调用此入口点。
如果 admission 用尽其 120 秒重试预算,终端错误会包含尝试次数、Gateway 主机和端口(或本地 socket 路径)以及最后一次失败。
connect failed 表示 WebSocket 未打开;请检查可达性和 TLS。
no hello within deadline 表示它已打开,但 Gateway 未完成 worker admission。可重试的 admission 拒绝会保留其原因。这些有界的、凭据脱敏的细节会出现在节点启动日志和 turn 错误中。
容器启动在创建每个容器之前会重新验证固定的 daemon 身份。此检查为繁忙的 daemon 允许 30 秒;超时仍会使启动失败并指明命令。已更改的 daemon 身份仍然是硬性失败。
运行时边界¶
该进程使用受限后端运行正常的嵌入式 agent 循环:
- 当
read、write、edit、apply_patch、exec和process编码工具存在于 Gateway 签发的 turn 权限中时,它们会在 worker 工作区中本地运行。空权限会以无工具方式运行模型。 - 模型调用默认使用 Gateway 推理代理。显式配置的配对设备 profile 可以选择 worker 本地推理,使用节点预置的模型配置和外部范围的代理 auth;不会加载 Gateway auth profile。
- Transcript 写入使用 gateway transcript-commit RPC。
- 流式传输和工具生命周期更新使用 gateway live-event RPC。
- 只接受已分配的 session 和 turn。
Worker 模式不会启动超出已分配 session 工具集的 channels、Gateway HTTP 表面或插件自动启动。它使用一次性状态目录。代理 worker 没有模型 provider 凭据,并且 worker exec 不会读取或投射 Gateway secret store。显式选择的 local-inference worker 将其节点授予的不透明 auth 值保存在运行时内存中。外部保管者必须将实际 provider 密钥保存在不受信任的 worker 工作负载之外;worker 进程不是同一用户凭据隔离边界。当 Gateway 的有效共享 GitHub 身份可用时,worker 会在其私有启动信封中收到一个 turn 绑定的 access token。该 token 会在一次性状态目录内的私有每 turn profile 中物化,在下次绑定之前删除较早的 profile,并在该目录被删除时清除。密封的 worker 启动器会将其绑定到每个 exec 子进程。必须在 worker 主机上安装 GitHub CLI;bundle 包含启动器,不包含 gh。
物化技能文件是位于私有目录中的临时轮次输入,该目录与 worker 状态及其 GitHub 凭据隔离。其目录范围限定于会话和工作区,并且每个技能路径都使用一个简短可读的名称,以及其名称、来源和已验证内容的摘要。未变更的投递会按确定性的提示顺序重新创建相同的路径,因此后续轮次可以复用提供方的提示前缀,并读取来自较早轮次的引用,而无需重写转录历史。已变更的技能内容会获得新路径。Worker 在清理期间持有文件系统锁;另一个活动轮次无法替换其输入,而崩溃恢复只会回收确定已死亡的拥有者。每轮删除失败会记录 Materialized skill cleanup failed。Node Claude 技能会话会针对临时 Workshop 配置单独报告 Node Claude skill session cleanup failed。这些范围受限且经过脱敏的警告会标识可能残留的文件。在检查权限并手动删除所报告的目录之前,请等待 worker 或会话及其拥有的进程已停止。仅完成一个轮次并不意味着受管 worker 已停止。这些文件系统删除失败会保留原始的成功、错误、取消或超时,而不会重放工作或声称删除成功。Worker 状态删除(包括 GitHub 凭据清理)在失败时仍会拒绝。进程排空、权限撤销、数据库关闭以及传输或 MCP 关闭保留其现有失败行为。无效的技能完整性或投递限制仍会拒绝该轮次。
Worker 通过有界的引导加载器加载工作区 AGENTS.md,并将 Gateway 提供的系统指令作为字面文本追加。它不会从工作区或 agent 状态目录中发现 SYSTEM.md 或 APPEND_SYSTEM.md。
Worker 到 worker 的会话分发在此模式下未公开。放置和分发仍由 Gateway 控制:操作员可以通过 Gateway 分发一个现有的本地、受管 worktree 会话,而 worker 进程不能分发自身或另一个 worker。
准备好的任务携带转录上下文、已接受的基础叶、提交序列和实时事件游标。在 worker WebSocket 重连时,进程使用相同的凭据和拥有者纪元重新准入,保留已接受的转录基础,重放其未确认的实时事件尾部,并以相同身份重新附加一个进行中的推理轮次。如果流式增量被错过,则终端推理消息是权威的。取代性的拥有者纪元会隔离该进程并导致干净退出。
stale-base-leaf 转录拒绝会使当前运行失败停止。Worker 模式不会针对不同的叶重试被拒绝的序列,因此不会产生重复提交;来自该运行中任何仍未提交的内存尾部都会丢失。重新启动属于 placement,它必须从 Gateway 的权威转录和提交账本创建新的任务。同样,Gateway 进程重启会以提供方错误终止待处理的推理轮次;只有 worker WebSocket 重连才能重新附加到同一进程的活动推理流。
Gateway 在确认推理准入之前持久化准入,并在发布终端消息之前持久化完成。Gateway 关闭和会话生命周期排空也会等待已接受的提供方和存储工作完成,包括在取消开始时仍在等待的准入。如果原生存储结算未知,Gateway 会保留该失败,并且不会重试终端写入或重放受影响的推理身份。独立的关闭清理仍会在报告失败之前运行。
参见 Gateway 协议 了解封闭的 worker RPC 接口,以及 Cloud workers 了解架构和安全模型。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw