云工作节点故障排查
在向云工作器调度或在其上运行时,您可能看到的症状,以及解决每个症状的检查项。
故障排查¶
Worker transcript commit failed; check Gateway logs.—— Gateway 无法完成转录提交。确定性失败(包括格式错误的数据库准入回执)会结束本轮对话;在重试前检查worker transcript commit failed警告以了解根本原因。临时性准入失败(包括并发的模式发布使回执失效)会触发重新连接,并使用新的准入进行重放。失败并不证明没有任何内容被持久化。从丢失的确认中恢复时,仍会重放原始提交标识,以避免重复消息。Crabbox profile setup failed、Crabbox node runtime preparation failed或Crabbox node enrollment setup failed,并伴随coordinator read retry N/M reason=timeout和context deadline exceeded—— 当每一行输出都是协调器超时诊断时,OpenClaw 会在现有阶段预算内采用退避策略重试同一条固定租约命令最多三次。任何脚本输出都会阻止重试。重试耗尽时的错误会保留协调器诊断和尝试次数;在再次调度前检查协调器可用性。provider=<backend> does not support fixed idempotent lease IDs—— OpenClaw 云工作器需要支持固定幂等租约 ID 的 Crabbox 后端。选择兼容的后端;不要移除--lease-id。这个确切的 exit-2 拒绝发生在 Crabbox 请求机器之前,因此新的调度会在没有清理请求的情况下永久失败。重放期间的其他 exit-2 失败和拒绝仍可能保留分配责任。-
工作器一直停留在
destroying状态,并出现has no local claim、does not match a valid ... claim、no exact resource-bound local claim或strict claim identifier mismatch—— 本地所有权记录缺失或不匹配并不能证明远端不存在。在重试 Stop 之前,检查提供方清单中的确切租约,并恢复正确的 Crabbox 状态或遵循提供方的所有权恢复流程。措辞“如果之前的停止操作已验证不存在,则无需再做任何事情”是有条件的;OpenClaw 不能仅凭此清除现有的清理义务。 -
没有公布任何云配置 —— 运行具有
operator.read作用域的openclaw gateway call environments.list --params '{}'。如果响应中没有profiles,请让管理员验证cloudWorkers.profiles并检查提供方插件;配置更改无需重启即可重新加载;在gateway.reload.mode: "off"模式下,Gateway 配置写入(如 Control UI 保存)会重启 Gateway,而直接编辑文件则需要等待手动执行openclaw gateway restart。这是配置或提供方激活问题,而不是授权结果。 - 云目标被隐藏或 RPC 被拒绝 —— 云配置调度和到配置目标的移动需要
operator.admin。operator.write可以调度或移动到符合条件的已配对设备、移动到 Gateway,并回收一个部署;仅operator.read可以发现配置,但不能启动、停止或移动会话。Profile 配置、基础设施配对、Connect machine、原始环境生命周期、直接execNode执行、隐身会话以及任意主机或节点路径仍需要operator.admin。 - 所选运行时缺乏云部署支持 —— 选择其公布的运行时支持云部署的模型。内置的 OpenClaw 和 Codex 运行时受支持;未声明的运行时仍仅限本地使用。
- Codex 无法使用云配置 —— 验证配置是否公布
remote-exec、Gateway 是否启用了受信任的 Codex 插件安装,以及gateway.nodes.commands.allow是否包含codex.exec-server.stdio.v1且没有匹配的拒绝规则。Bootstrap 会自动提供云节点插件。在提示时批准确切的节点调用。Codex 不需要可用的 OpenClaw 工作器槽位;缺少插件或被拒绝的命令必须予以纠正,而不能通过 Gateway 或 SSH 执行来绕过。 - 工作器上无法使用门户工具 —— 确认会话在公布了 portal-stream 支持的已注册节点上使用 OpenClaw
worker-turn。必要时更新旧版节点捆绑包。基于 SSH 的remote-exec部署(包括 Codex 会话)不会运行 OpenClaw 工作器工具循环;当需要 Gateway 托管门户时,使用sessions.move将会话移回 Gateway。 - “Worker bootstrap requires Node.js on the leased host” —— 在
settings.setup中添加 Node 安装(参见 设置命令)。如果 APT 安装了 Node.js 24 后设置仍报告不支持的 Node 版本,则可能是在PATH中靠前的 nvm 管理的 Node 遮蔽了它。Debian/Ubuntu 设置方法 会就地升级该 nvm 安装,并在最终检查仍然失败时报告解析到的 Node 路径和版本。 - 云工作器上出现
gh: command not found—— 在settings.setup中安装 GitHub CLI(参见 配置 中的 Debian/Ubuntu 示例),或将其安装在配对的工作器主机上。Crabbox 开发者镜像包含它;密封的工作器捆绑包不包含它。 - 仓库准备报告
clone-failed或checkout-failed—— 部署错误包含 Git 阶段、退出或终止状态,以及有界且已脱敏的 stderr。在重试调度前,利用该详细信息检查节点上的 Git 可用性、仓库访问权限或网络连接。原生 Windows 仓库准备会启用 Git 的长路径处理,因为当部分克隆创建.promisor文件时,嵌套的会话目录可能超出限制。 - 准备好的项目的 Git 验证失败 —— 错误会指明 Git 子命令以及它是超时、超出输出缓冲区、启动失败、退出不成功还是收到信号。准备好的工作区的 Git 操作最多允许十分钟(与种子验证一致),且在提供方的整体命令截止时间内。
git fsck超时可能表明从新启动的快照读取缓慢;退出不成功则需要调查工作器的 Git 对象存储。在缓存重用之前仍会运行完整的完整性检查。 - Windows 工作区传输报告
Filename too long—— 更新 Gateway 并重新调配工作器。新传输的工作区会在其私有仓库中启用 Git 的长路径处理,使包导入、检出以及后续的工作区捕获可以使用深度嵌套的会话路径。全局 Git 配置和 Windows 注册表设置保持不变。 - AWS 实例角色证明失败 —— 清除
aws.instanceProfile(以及已设置的CRABBOX_AWS_INSTANCE_PROFILE)。插件会在 AWS 准入之前自动安装受支持的 Crabbox;使用openclaw doctor --fix诊断失败的托管安装。 - 调度或工作区恢复失败 —— 检查
environments.list和sessions.describe。失败的环境会暴露其有界的环境错误。失败的部署会暴露recoveryError以及其持久的按会话terminalReason;所选的 Control UI 聊天会在输入框上方显示该终止原因。当需要更深入的诊断时,Gateway 主机上的操作员可以只读方式检查持久的工作器状态。不要编辑状态数据库以绕过生命周期围栏。 - 节点工作器启动被拒绝 —— 错误会指明失败的启动、状态或取消命令,并包含节点有界且已脱敏的诊断信息。当节点将新的启动请求拒绝为无效(
INVALID_REQUEST)时,本轮会立即失败且不进行取消,因为该节点从未注册该启动;无效的启动描述符通常意味着 Gateway 和节点运行不同的版本,因此请更新较旧的一方。如果无法确认取消,错误还会包含取消失败信息;在重试前检查工作器的状态。失败的部署会保留其记录的原因;仅当该原因表明构建不匹配时,才会出现构建更新指南。 - 归档失败 —— Control UI 会立即隐藏会话,并且只有在归档本身被拒绝时才恢复它。活动会话的工作必须完成停止;重复请求无法取代已经在停止该工作的操作。已经失败的工作器可以在提供方清理仍处于待处理状态时进行归档,同时保留其工作树和恢复记录。归档保存后的工作树清理错误会被记录以供稍后清理。客户端超时不会取消已接受的请求,也不能证明其结果;在重试前检查会话当前的归档状态。
- Crabbox 设置无法访问租约 —— 在 Crabbox 提供方参考 中查看所选后端的网络和设置传输要求。纠正 Crabbox 的配置,并在重试前重新运行
crabbox doctor --provider <backend> --json。 - Crabbox 命令执行失败 —— 错误会保留有界且已脱敏的运行器诊断信息。执行失败可能发生在进程启动之后,包括在输出捕获或清理期间。Bootstrap 版本验证和插件激活错误包含退出码、信号以及清理后的 stderr 尾部;利用该原因诊断缺失的依赖项或已终止的进程。
- Linux 配置分配了另一个操作系统 —— 更新 Gateway。Linux 分配会显式请求 Linux,覆盖环境中的 Crabbox 目标或配置默认值。Windows 模式和 macOS 市场选择仍遵循解析后的配置。
- Crabbox 检查报告协调器读取重试 —— Crabbox 负责在一分钟预算内进行读取重试。OpenClaw 每次租约检查允许两分钟,其中包括在负载较高的主机上进程启动和退出的一分钟;Machine0 保留五分钟用于就绪检查。调配读取也会遵守剩余的整体截止时间。如果检查仍然失败,在重试调度前使用
crabbox inspect --provider <backend> --id <lease> --json检查协调器可用性和租约。 - Crabbox 工作器在其租约从未被准入后一直处于
destroying状态 —— 更新 Gateway。在下次协调时,正常退出的停止操作如果在协调器租约读取和释放时都报告404/not_found,则完成拆除并释放热镜像分配所有权。两个响应都必须指明该租约。被识别的直接提供方 exit-4 缺失也会完成拆除;身份验证错误、超时、不完整的输出和失败的释放仍然属于错误。 - 会话在空闲后显示已回收或已暂停的徽标 —— 当其配置设置了
suspendAfter时,这是预期行为。下一条消息会调配一个替代工作器;存在镜像时该工作器为热(warm)状态。 - 热镜像不可用 —— 新的分配可以在其选择被记录之前选择冷调配。已经准入的分配会在重试中保持其原始的冷/检查点选择。如果其检查点无法派生,请解决提供方错误或先停止该分配,然后再启动替代分配;重试不会静默切换镜像。
- 热镜像迁移或容量问题阻止调度 —— 对遗留状态运行
openclaw doctor --fix,并遵循其精确的清理指南。对于容量问题,停止未完成的工作器,或使用openclaw crabbox warm-images解决挂起的镜像清理;分配选择和清理义务永远不会被逐出以腾出空间。 -
checkpoint mode must be auto, native, or archive且捕获已暂停 —— 所选的 Crabbox 提供方、目标或协调器不支持请求的原生捕获,并且较旧的 CLI 没有报告明确的“不支持捕获”回执。将 Crabbox 更新到 0.69.0 或更高版本,该版本包含 Crabbox #2613。随后 OpenClaw 会记录最新的拒绝并继续调配;后续的工作器在可用时会使用现有的兼容快照,否则进行冷调配(在 Snapshots 中显示为 Cold only)。从拒绝发生算起,经过warmImages.refreshAfter时间后,针对该镜像键的捕获尝试会恢复。再次拒绝会刷新标记时间戳;成功的捕获会清除它。当不再有镜像、分配或操作时,维护操作会在warmImages.refreshAfter时间过去后从本地状态中删除仅标记行,而无需新的拒绝。已被较旧 CLI 暂停的捕获仍需要 暂停捕获恢复:该拒绝发生在创建任何检查点之前,但在使用--recover之前,请确认 Crabbox 检查点目录中的源租约和捕获时间。在配置上设置settings.warmImage: false作为解决方法,以停止捕获尝试。 -
项目镜像捕获失败 — 会话会在其捕获恢复说明之前报告底层提供程序的诊断信息,例如检查点配额被拒绝。重试前请先解决该根因。未解决的捕获仍会阻止注册,直到提供程序工件与记录的捕获完成对账。
- Cloud bootstrap 要求重新构建 — 在 Gateway 源代码检出目录中运行
pnpm build,然后重启 Gateway 并重试。正在运行的构建、其包元数据以及构建出的插件输出必须一致;仅编辑源码或匹配所显示的版本是不够的。 - Cloud bootstrap 下载失败 — 错误会指明是连接、TLS、HTTP 响应还是正文传输阶段出现问题。Crabbox 会以短暂退避重试瞬时传输故障以及 HTTP 502/503/504 响应;连续三次无字节进展的失败后会停止。如果某次尝试使保留的部分文件变大,则该失败计数会被重置。总工作量仍受现有 core 规格安装命令期限的约束;每个停滞的连接或正文传输在空闲两分钟后超时。被中断的下载会保留其部分文件,并使用
Range: bytes=N-请求剩余字节,因此缓慢或易重置连接的代理不会让每次尝试都回到字节零。完整的 HTTP 200 响应会替换部分文件;不一致的范围响应会丢弃该文件,并在相同的无进展限制内从零重试。安装前,完整归档仍必须与其声明的大小和 SHA-256 匹配;完整性失败会丢弃部分字节并停止。每个 bootstrap 工件令牌最多允许 256 次串行提供;已完成的完整/范围响应以及被中断的完整/范围响应均计入其中。这个固定上限既能容纳频繁续传,也能限制工件重放,包括缓冲代理重置其下游连接的情况。并发请求会收到带有transfer_in_progress的 HTTP 503;这些忙碌响应会在安装命令的期限内退避等待,且不消耗无进展失败预算。其他 HTTP 503 响应仍会计入该限制。Bootstrap 与 node-worker-bundle 传输令牌共享由大小决定的 45–95 分钟 bootstrap 操作窗口,一旦注册或操作结束即被吊销;node-worker-bundle 传输令牌只允许提供一次。范围请求会减少每次提供的字节数;重试不会延长这些有效期、提高提供预算或绕过所有者的吊销。每次重试都会记录阶段、错误码、尝试次数和连续无进展失败次数。完整性、身份、unsafe-path、TLS-pin 以及 HTTP 401/403/404/409/410 失败会立即停止。download TLS重置发生在 HTTP 响应之前;请从 worker 侧检查 worker 提供程序的出站策略和 Gateway 的 TLS 端点,而不仅仅从 Gateway 主机检查。如果是 HTTP 状态码问题,请检查代理路由和下载授权。download body错误意味着响应头已到达;请检查被中断的传输、本地磁盘或归档完整性错误。请使用提供程序策略允许的 Gateway 源站(origin);不要禁用证书验证或绕过该策略。 - Bootstrap 下载失败并出现
ECONNRESET/ 来自 worker 的连接重置 — 反复出现连接级失败且没有保留任何字节,说明 worker 无法访问错误中命名的 Gateway 公共源站。请从提供程序的沙箱内部探测该源站,例如curl -v --connect-timeout 15 --max-time 30 https://gateway.example.com/(将示例替换为报告中的源站;不需要工件 URL 或令牌)。收到 HTTP 响应说明 TLS 连接成功;在收到任何响应之前发生重置,则指向提供程序的出站网络策略或该源站的 TLS 端点。从其他主机成功下载并不能证明该源站可达。某些提供程序的出口过滤器会对 quick-tunnel 主机名(例如*.trycloudflare.com)重置 TLS;2026-10-03 在 Daytona 上曾观察到这种情况。请在可从该提供程序访问的主机名上配置gateway.publicOrigin,然后重试调度。 - 节点注册超时 — 该命令现在使用 core 规格的 bootstrap 窗口进行下载和安装,而不是固定的 15 分钟截止时间。更大的工件和缓慢的 Gateway 上行链路会获得更多时间,包括断点续传。项目准备会将两个归档都计入,因为并发下载会共享上行链路。外层置备预算会在授权产生之前预留这些工作,并保留独立的连接等待、诊断和清理余量。配对持续整个活动注册及其大小决定的窗口(包括节点连接等待),而不是在十分钟后过期。关闭或超时未完成的注册会吊销其配对凭据并阻止其配对;重放会为同一安装身份签发新的凭据。请检查 bootstrap 下载或安装错误、节点进程状态,以及注册错误中包含的有界节点日志尾部。请确认配置文件设置安装了受支持的 Node.js 版本和 npm,npm 可以访问依赖注册表,并且该机器可以访问 Gateway 公布的 TLS URL。请通过你的代理转发
/__openclaw__/worker-bootstrap/artifacts/<sha256>以及公共的 worker/node WebSocket 路由。如果错误包含proxy_attribution_required,请将反向代理的源地址添加到gateway.trustedProxies。 - 调度(dispatch)期间客户端超时 —
openclaw gateway call默认超时为 10 秒;请传入充足的--timeout。无论哪种情况,调度都会在服务端继续运行;在同一 Gateway 上进行完全相同的重试会加入该进行中的操作,而不是置备另一个 worker。使用不同配置文件或会话身份的重试会被拒绝。 doctor通过后提供程序授权失败 — 只读的就绪检查并不能证明有权分配或拆除租约。请检查被拒绝的操作,并遵循 Crabbox 提供程序参考 中选定提供程序的置备和清理要求。- Gateway 更新后的 worker 运行时更新 — OpenClaw 会在现有机器上安装当前的 worker 包,同时保留其工作区、已安装的软件包和桌面。后台对账会在重新连接且保留了会话的已配对主机上开始安装新运行时,通常在重新连接后约一分钟内开始。可在 Gateway 日志中跟踪该安装;日志会记录开始、每 30 秒的进度、带原因的每次中断以及完成状态。
sessions.describe和sessions.list等会话 RPC 可以等到对账流程完成后再调用。对于由首次调度或已提交回合执行的安装,置备或活动会话放置中的workerRuntimeInstall以及 Control UI 聊天通知也会显示传输和安装进度。与此同时提交的回合会等待同一个传输;卡住的会话诊断会为等待中的回合报告worker:runtime_refresh,为执行安装的首次调度报告worker:runtime_install。失败的运行时更新会保留机器以便恢复;请在 Gateway 的 worker 环境日志中查看安装程序错误。被中断的节点回合会通过正常的会话恢复以全新的执行权限继续。显式的 Stop 和 Move 请求仍会完成拆除;已被提供程序丢失的机器无法复用。 Cloud worker finished, but its workspace result could not be reconciled— 请阅读node workspace command failed (<code>)之后的详细信息,以及节点主机日志中对应的警告。工作区错误会保留有界且脱敏后的诊断信息,包括文件系统和进程辅助程序的失败。如果 root 拥有的容器报告workspace quiescence refuses root-owned worker sessions,请同时更新节点主机和 Gateway;原生 Linux 辅助程序支持 root 拥有的会话,而不会冻结其他 root 进程。较旧的 detached 脚本仍然需要非 root 的 worker 账户。- 云工作区冲突通知 — 回合已完成,并保留了所列每个路径的本地版本。请使用通知中的 staged-ref 命令检查或采用云版本;非冲突更改已应用,无需重试。
- 云会话磁盘空间警告 — 在进行大写入前,请删除远程工作区中不需要的文件,或停止云 worker。当下一次成功采样显示有足够可用空间后,警告会自动消除;失败的采样会保留最近成功时的警告,且不影响会话生命周期。
- “上一个云回合的工作区结果仍在对账中” — Gateway 短暂地等待前一个结果的持久围栏,但未能获取会话认领。请等待对账完成,然后重试该回合;重启 Gateway 是安全的,因为恢复流程会在回收已死 worker 之前保留暂存结果。
- GitHub 发布失败 — 对于通过 Publish PR 或 remote-exec
github_publish进行的 Gateway 中介发布,请打开 Agents → Tools → GitHub Identity,确认生效的@login、所选范围、访问有效期和刷新状态。当刷新已过期或不可用时,请重新连接 GitHub;仅将托管 PAT 作为明确回退方案使用。对于推送被拒绝,请检查仓库写权限和分支漂移;/user验证不能证明仓库写权限,且中介永远不会改写已发布的历史。如果已发布分支不再符合已接受的历史,请保留本地工作,并在已发布的 head 之上应用预期编辑以刷新现有 PR;对于有意重写的历史,请使用新的会话分支和替代 PR。不要反复发布相同的分叉,也不要仅仅为了让变基后的分支可以推送而合并旧历史。分支观察失败时,需要恢复读取权限/连接,而不是假定该分支不存在。对于拉取请求被拒绝,请授予 PR 写权限,然后重试 Publish PR,或使用新的工具调用再次调用github_publish。 - 仓库发布不可用 — Git clean 过滤器、不安全的 Git 配置或发布快照验证失败,都可能阻止准备可发布的检查点。原始恢复检查点和正常的 Stop 仍会保留已接受的更改。请修正仓库配置,然后运行另一个回合或保存一次编辑以准备新的检查点,再请求发布。
- 租约维护 —
crabbox list --provider <backend> --json是只读的资源清单。crabbox stop --provider <backend> --id <lease>和crabbox release --provider <backend> --id <lease>是破坏性操作,会手动释放租约。OpenClaw 会在其会话被放置期间保持租约存活,然后在拆除过程中停止心跳,从而让真正空闲的租约在配置文件的idleTimeout到期。临时心跳失败(包括租约认领冲突)会产生警告,并保留下一次计划的续约。不支持租约心跳的后端会产生警告;插件会在使用前确保 CLI 本身支持该命令。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw