Cloud worker 故障排查

在向云 worker 分发或在其上运行时，您可能会看到的症状，以及解决每个症状的检查方法。

故障排查¶

• 未公布云 profile — 运行 operator.read 作用域的 openclaw gateway call environments.list --params '{}'。如果响应中没有 profiles，请让管理员验证 cloudWorkers.profiles 并检查提供方插件；配置更改无需重启即可重新加载；当 gateway.reload.mode: "off" 时，Gateway 配置写入（如 Control UI 保存）会重启 Gateway，而直接编辑文件则需要等待手动 openclaw gateway restart。这是配置或提供方激活问题，而非授权结果。
• 云目标被隐藏或 RPC 被拒绝 — 云 profile 分发和以 profile 为目标的移动需要 operator.admin。operator.write 可以分发或移动到符合条件的已配对设备、移动到 Gateway，并回收一个放置；仅 operator.read 可以发现 profile，但无法启动、停止或移动会话。Profile 配置、基础设施配对、Connect machine、原始环境生命周期、直接 execNode 执行、隐身会话以及任意主机或节点路径仍属于 operator.admin。
• 所选运行时缺少云放置支持 — 请选择其公布运行时支持云放置的模型。内置的 OpenClaw 和 Codex 运行时受支持；未声明的运行时仍仅限本地。
• Codex 无法使用云 profile — 请验证 profile 是否公布 remote-exec、Gateway 是否启用了受信任的 Codex 插件安装，以及 gateway.nodes.commands.allow 是否包含 codex.exec-server.stdio.v1 且没有对应的拒绝规则。Bootstrap 会自动提供云节点插件。出现提示时请批准确切的节点调用。Codex 不需要可用的 OpenClaw worker 槽位；缺失插件或被拒绝的命令必须加以纠正，而不能通过 Gateway 或 SSH 执行来绕过。
• Portal 工具在 worker 上不可用 — 请确认会话在公告支持 portal-stream 的已注册节点上使用 OpenClaw worker-turn。必要时更新较旧的节点包。SSH 后端的 remote-exec 放置（包括 Codex 会话）不运行 OpenClaw worker 工具循环；当需要 Gateway 托管的 portal 时，请使用 sessions.move 将会话移回 Gateway。
• "Worker bootstrap requires Node.js on the leased host" — 请将 Node 安装添加到 settings.setup（参见 setup 命令）。
• 云 worker 上出现 gh: command not found — 请在 settings.setup 中安装 GitHub CLI（参见 配置 中的 Debian/Ubuntu 示例），或将其安装到已配对的 worker 主机上。Crabbox 开发镜像包含它；密封的 worker 包不包含。
• 仓库准备报告 clone-failed 或 checkout-failed — 放置错误包含 Git 阶段、退出或终止状态，以及有界且经过脱敏的 stderr。请利用该详细信息在重试分发前检查节点上的 Git 可用性、仓库访问权限或网络连接。原生 Windows 仓库准备会启用 Git 的长路径处理，因为当部分克隆创建 .promisor 文件时，嵌套的会话目录可能超出该限制。
• 准备好的项目 Git 验证失败 — 错误会指出 Git 子命令以及它是超时、超出输出缓冲区、启动失败、非成功退出，还是收到信号。准备好的工作区 Git 操作允许最多十分钟（与种子验证一致），且须在提供方的整体命令期限内。git fsck 超时可能表示从新启动的快照读取缓慢；非成功退出需要调查 worker 的 Git 对象存储。缓存复用前仍会运行完整完整性检查。
• Windows 工作区传输报告 Filename too long — 请更新 Gateway 并重新配置 worker。新传输的工作区会在其私有仓库中启用 Git 的长路径处理，从而使包导入、检出以及后续的工作区捕获可以使用深度嵌套的会话路径。全局 Git 配置和 Windows 注册表设置保持不变。
• AWS 实例角色证明失败 — 请清除 aws.instanceProfile（以及已设置的 CRABBOX_AWS_INSTANCE_PROFILE）。插件会在 AWS 准入前自动安装受支持的 Crabbox；请使用 openclaw doctor --fix 诊断失败的管理安装。
• 分发或工作区恢复失败 — 请检查 environments.list 和 sessions.describe。失败的环境会暴露其有界环境错误。失败的放置会暴露 recoveryError 以及其持久的每会话 terminalReason；所选的 Control UI 聊天会在输入框上方显示该终止原因。当需要更深层次的诊断时，Gateway 主机上的操作员可以只读方式检查持久的 worker 状态。不要编辑状态数据库来绕过生命周期围栏。
• 节点 worker 启动被拒绝 — 错误会指出失败的启动、状态或取消命令，并包含节点有界且经过脱敏的诊断信息。当节点将新的启动请求视为无效（INVALID_REQUEST）而拒绝时，回合会立即失败且不会取消，因为节点从未注册该启动；无效的启动描述符通常意味着 Gateway 和节点运行不同的版本，因此请更新较旧的一方。如果无法确认取消，错误还会包含取消失败信息；请在重试前检查 worker 状态。失败的放置会保留其记录的原因；只有当该原因表明构建不匹配时，才会出现构建更新指引。
• 归档失败 — Control UI 会立即隐藏会话，并且仅当归档本身被拒绝时才恢复它。活动会话的工作必须完成停止；重复请求无法替代已经在停止该工作的操作。已失败的 worker 可以在提供方清理仍待处理时进行归档，其工作树和恢复记录会被保留。归档保存后的工作树清理错误会被记录以供后续清理。客户端超时不会取消已接受的请求，也不能证明其结果；请在重试前检查会话当前的归档状态。
• Crabbox 设置无法访问租约 — 请在 Crabbox 提供方参考 中检查所选后端的网络和设置传输要求。在重试前更正 Crabbox 的配置并重新运行 crabbox doctor --provider <backend> --json。
• Crabbox 检查报告协调器读取重试 — Crabbox 负责在一分钟预算内进行读取重试。OpenClaw 每次租约检查允许两分钟，包括在负载较高的主机上进程启动和退出的一分钟；Machine0 保留五分钟用于就绪检查。预置读取也会遵守剩余的整体期限。如果检查仍然失败，请在重试分发前使用 crabbox inspect --provider <backend> --id <lease> --json 检查协调器可用性和租约。
• Crabbox worker 在其租约从未被接纳后仍停留在 destroying 状态 — 请更新 Gateway。在下一次协调时，正常退出且对协调器租约读取和释放均报告 404/not_found 的停止操作会完成拆除并释放暖镜像分配所有权。两个响应都必须指明该租约。被识别的直接提供方 exit-4 缺失也会完成拆除；认证错误、超时、不完整输出和失败的释放仍属于错误。
• 会话在空闲后显示已回收或已暂停徽标 — 当其 profile 设置了 suspendAfter 时，这是预期行为。下一条消息会预置一个替换 worker，如果存在镜像则为暖启动。
• 暖镜像不可用 — 新的分配可以在其选择被记录之前选择冷预置。已获接纳的分配会在重试时保持其最初的冷/检查点选择。如果其检查点无法分叉，请在启动替换之前解决提供方错误或停止该分配；重试不会静默切换镜像。
• 暖镜像迁移或容量阻止分发 — 请对旧状态运行 openclaw doctor --fix 并遵循其确切的清理指引。对于容量问题，请停止未完成的 worker 或使用 openclaw crabbox warm-images 解决待处理的镜像清理；分配选择和清理义务绝不会为了让出空间而被驱逐。
• checkpoint mode must be auto, native, or archive 与暂停的捕获 — 所选的 Crabbox 提供方、目标或协调器不支持所请求的原生捕获，而较旧的 CLI 未报告明确的不支持捕获回执。请将 Crabbox 更新到 0.69.0 或更高版本，其中包含 Crabbox #2613。OpenClaw 随后会记录最新的拒绝并继续预置；后续 worker 在存在可用快照时使用现有的兼容快照，否则进行冷预置（在 Snapshots 中显示为 Cold only）。每个符合条件的 worker 都会重试捕获，因此 Crabbox 配置更改会应用于下一次分发。再次拒绝会刷新标记时间戳；成功的捕获会清除它。当不再有镜像、分配或操作时，维护操作会在 warmImages.refreshAfter 之后且没有新的拒绝的情况下，从本地状态中删除仅含标记的行。已被较旧 CLI 暂停的捕获仍需要暂停捕获恢复：该拒绝发生在任何检查点创建之前，但在使用 --recover 之前，请确认 Crabbox 检查点目录中的源租约和捕获时间。作为变通方法，可在 profile 上设置 settings.warmImage: false 以停止捕获尝试。
• 项目镜像捕获失败 — 会话会在其捕获恢复说明之前报告底层提供方诊断，例如检查点配额拒绝。请在重试前解决该原因。未解决的捕获仍会阻止注册，直到提供方工件和已记录的捕获得到协调。
• 云引导请求重建 — 请在 Gateway 源代码检出目录中运行 pnpm build，然后重启 Gateway 并重试。正在运行的构建、其包元数据和构建后的插件输出必须一致；仅编辑源代码或匹配显示的版本是不够的。

• 云引导下载失败 — 错误会指出连接、TLS、HTTP 响应或正文传输阶段。Crabbox 会以较短退避重试瞬时传输失败和 HTTP 502/503/504 响应，在连续三次无字节进展的失败后停止。使保留的部分文件增长的尝试会重置该失败计数。总工作量仍受现有核心规模的 setup 命令期限约束，每个停滞的连接或正文传输会在空闲两分钟后超时。中断的下载会保留其部分文件，并使用 Range: bytes=N- 请求剩余字节，因此缓慢或容易重置的代理不会迫使每次尝试都回到字节零。完整的 HTTP 200 响应会替换部分文件；不一致的范围会丢弃该文件并在相同的无进展限制内从零重试。完整归档在安装前仍必须与其声明的大小和 SHA-256 匹配；完整性失败会丢弃部分字节并停止。每个引导工件令牌最多允许 256 次串行服务，包括已完成和中断的完整或范围响应。这个固定上限可容纳频繁恢复，同时限制工件重放，包括当缓冲代理重置其下游连接时。并发请求会收到带有 transfer_in_progress 的 HTTP 503；这些繁忙响应会在 setup 命令期限内以退避方式等待，而不消耗无进展失败预算。其他 HTTP 503 响应仍会计入该限制。引导和节点 worker 包传输令牌共享由大小决定的 45–95 分钟引导操作窗口，并且一旦注册或操作结束即被撤销；节点 worker 包传输令牌只允许服务一次。范围请求会减少每次服务的字节数；重试绝不会延长这些生命周期、提高服务预算或绕过所有者撤销。每次重试都会记录阶段、错误代码、尝试次数和连续无进展失败次数。完整性、身份、不安全路径、TLS 固定以及 HTTP 401/403/404/409/410 失败会立即停止。download TLS 重置发生在 HTTP 响应之前；请从 worker（而不仅是 Gateway 主机）检查 worker 提供方的出站策略和 Gateway 的 TLS 端点。对于 HTTP 状态，请检查代理路由和下载授权。download body 错误意味着响应头已到达；请检查被中断的传输、本地磁盘或归档完整性错误。请使用提供方策略允许的 Gateway 来源；不要禁用证书验证或绕过该策略。

• 节点注册超时 — 该命令现在使用按核心大小计算的引导窗口用于其下载和安装，而不是固定的 15 分钟截止。较大的工件和较慢的 Gateway 上行链路会获得更多时间，包括已恢复的传输。项目准备会将两个归档都计入，因为并发下载共享上行链路。外层供应预算在授权存在之前预留此工作，并保留独立的连接等待、诊断和清理额度。配对持续覆盖实时注册及其由大小派生的窗口，包括节点连接等待，而不是在十分钟后过期。关闭或超时一个未完成的注册会吊销其配对凭据并阻止其配对；重放会为同一设置身份签发新的凭据。检查注册错误中包含的引导下载或安装错误、节点进程状态以及有界的 node-log 尾部。验证配置文件设置已安装受支持的 Node.js 版本和 npm，npm 可以访问依赖注册表，并且该机器可以访问 Gateway 通告的 TLS URL。通过你的代理转发 /__openclaw__/worker-bootstrap/artifacts/<sha256> 以及公共 worker/node WebSocket 路由。如果错误包含 proxy_attribution_required，请将反向代理的源地址添加到 gateway.trustedProxies。

• 分发时客户端超时 — openclaw gateway call 默认使用 10s 超时；请设置足够宽松的 --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-environment 日志以查看安装程序错误。被中断的节点轮次会通过正常会话恢复以新的执行权限恢复。显式的 Stop 和 Move 请求仍会完成其拆除，而提供商已经丢失的机器无法重新使用。
• 云工作区冲突通知 — 该轮次已完成，并保留了每个列出路径的本地版本。使用通知中的暂存引用命令来检查或采用云端版本；对于无冲突的更改无需重试，因为它们已经应用。
• 云会话磁盘空间警告 — 在进行大量写入之前，从远程工作区删除不需要的文件或停止云 worker。下一次成功采样显示足够可用空间后，警告会自动清除；失败的采样会保留最后一次成功警告的显示，并且不影响会话生命周期。
• “上一个云轮次的工作区结果仍在协调中” — Gateway 短暂等待了先前结果的持久化栅栏，但无法获取会话声明。等待协调完成，然后重试该轮次；重启 Gateway 是安全的，因为恢复会在回收死 worker 之前保留暂存结果。
• GitHub 发布失败 — 对于通过 Publish PR 或 remote-exec github_publish 进行的 Gateway 代理发布，打开 Agents → Tools → GitHub Identity 并确认有效的 @login、已选范围、访问过期时间和刷新状态。当刷新已过期或不可用时，重新连接 GitHub；仅在明确回退时使用托管 PAT。对于推送拒绝，检查仓库写权限和分支漂移；/user 验证并不能证明仓库写权限，并且代理从不重写已发布历史。如果已发布分支不再符合已接受历史，请保留本地工作，并在已发布头之上应用预期编辑以刷新现有 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 本身支持该命令后再使用。