Cloud worker troubleshooting

Symptoms you may see when dispatching to or running on a cloud worker, and the check that resolves each one.

Troubleshooting

• No cloud profile is advertised — run the operator.read-scoped openclaw gateway call environments.list --params '{}'. If the response has no profiles, ask an administrator to validate cloudWorkers.profiles, inspect the provider plugin, and restart the Gateway. This is a configuration or provider-activation problem, not an authorization result.
• Cloud destinations are hidden or an RPC is denied — cloud profile dispatch and profile-target moves require operator.admin. operator.write can dispatch or move to an eligible paired device, move to the Gateway, and reclaim a placement; operator.read alone can discover profiles but cannot start, stop, or move a session. Profile configuration, infrastructure pairing, Connect machine, raw environment lifecycle, direct execNode execution, incognito sessions, and arbitrary host or node paths remain operator.admin.
• The selected runtime lacks cloud placement support — choose a model whose advertised runtime supports cloud placement. The bundled OpenClaw and Codex runtimes are supported; undeclared runtimes remain local-only.
• Codex cannot use a cloud profile — verify that the profile advertises remote-exec, the Gateway enables a trusted Codex plugin installation, and gateway.nodes.commands.allow includes codex.exec-server.stdio.v1 without a matching deny rule. Bootstrap supplies the cloud-node plugin automatically. Approve the exact node invocation when prompted. Codex does not require an available OpenClaw worker slot; a missing plugin or denied command must be corrected rather than bypassed with Gateway or SSH execution.
• The portal tool is unavailable on a worker — confirm the session uses OpenClaw worker-turn on an enrolled node that advertises portal-stream support. Update older node bundles when necessary. SSH-backed remote-exec placements, including Codex sessions, do not run the OpenClaw worker tool loop; move the session back to the Gateway with sessions.move when a Gateway-hosted portal is needed.
• "Worker bootstrap requires Node.js on the leased host" — add a Node install to settings.setup (see The setup command).
• gh: command not found on a cloud worker — install GitHub CLI in settings.setup (see the Debian/Ubuntu example in Configuration), or install it on the paired worker host. Crabbox developer images include it; the sealed worker bundle does not.
• AWS instance-role attestation fails — clear aws.instanceProfile (and CRABBOX_AWS_INSTANCE_PROFILE, if set). Install Crabbox 0.41.1 or newer; older binaries do not satisfy the fixed-ID and authoritative providerMetadata.instanceProfileAttached contracts required for AWS admission.
• Dispatch or workspace recovery fails — inspect environments.list and sessions.describe. A failed environment exposes its bounded environment error. A failed placement exposes recoveryError plus its durable per-session terminalReason; the selected Control UI chat shows that terminal reason above the composer. When deeper diagnosis is necessary, an operator on the Gateway host can inspect the durable worker state read-only. Do not edit the state database to bypass lifecycle fencing.
• Crabbox setup cannot reach the lease — check the selected backend's networking and setup-transport requirements in the Crabbox provider reference. Correct Crabbox's configuration and rerun crabbox doctor --provider <backend> --json before retrying.
• Session shows a reclaimed or suspended badge after being idle — this is expected when its profile sets suspendAfter. The next message provisions a replacement worker, warm when an image exists.
• A warm image is unavailable — a new allocation can select cold provisioning before its choice is recorded. An already admitted allocation keeps its original cold/checkpoint choice through retries. If its checkpoint cannot be forked, resolve the provider error or stop that allocation before starting a replacement; retry does not switch images silently.
• Warm-image migration or capacity blocks dispatch — run openclaw doctor --fix for legacy state and follow its exact cleanup guidance. For capacity, stop outstanding workers or resolve pending image cleanup with openclaw crabbox warm-images; allocation choices and cleanup obligations are never evicted to make room.
• Cloud bootstrap requests a rebuild — run pnpm build in the Gateway source checkout, then restart the Gateway and retry. The running build, its package metadata, and the built plugin outputs must agree; editing source or matching the displayed version alone is insufficient.
• Cloud bootstrap download fails — the error identifies the connection, TLS, HTTP-response, or body-transfer phase. A download TLS reset happened before an HTTP response; check the worker provider's outbound policy and the Gateway's TLS endpoint from the worker, not only from the Gateway host. For an HTTP status, check proxy routing and download authorization. A download body error means response headers arrived; inspect the interrupted transfer, local disk, or archive-integrity error. Use a Gateway origin permitted by the provider's policy; do not disable certificate validation or bypass that policy.
• Node enrollment times out — inspect the bootstrap download or install error, node process state, and bounded node-log tail included in the enrollment error. Verify that profile setup installed a supported Node.js release and npm, that npm can reach the dependency registry, and that the box can reach the Gateway's advertised TLS URL. Forward /__openclaw__/worker-bootstrap/artifacts/<sha256> as well as the public worker/node WebSocket routes through your proxy. If the error contains proxy_attribution_required, add the reverse proxy's source address to gateway.trustedProxies.
• Client timeout while dispatching — openclaw gateway call defaults to a 10s timeout; pass --timeout generously. Dispatch keeps running server-side either way, and an identical retry on the same Gateway joins that in-flight operation instead of provisioning another worker. A retry with a different profile or session identity is rejected.
• Provider authorization fails after doctor passes — read-only readiness does not prove permission to allocate or tear down a lease. Inspect the denied action and follow the selected provider's provisioning and cleanup requirements in the Crabbox provider reference.
• Worker reclaimed after a Gateway update — OpenClaw releases idle cloud workers built for the previous build, keeps the session and workspace, and provisions a replacement on the next message. Workers interrupted mid-turn or while starting, or holding unaccepted results, still fail and need explicit redispatch.
• Cloud workspace conflict notice — the turn completed and kept the local version of each listed path. Use the staged-ref commands in the notice to inspect or take the cloud version; no retry is required for the non-conflicting changes, which are already applied.
• Cloud session disk-space warning — delete unneeded files from the remote workspace or stop the cloud worker before large writes. The warning clears automatically after the next successful sample shows enough free space; a failed sample leaves the last successful warning visible and does not affect the session lifecycle.
• “The previous cloud turn's workspace result is still reconciling” — the Gateway waited briefly for the prior result's durable fence and could not acquire the session claim. Wait for reconciliation to finish, then retry the turn; restarting the Gateway is safe because recovery preserves staged results before reclaiming a dead worker.
• GitHub publication failed — for Gateway-brokered publication through Publish PR or remote-exec github_publish, open Agents → Tools → GitHub Identity and confirm the effective @login, selected scope, access expiry, and refresh state. Reconnect GitHub when refresh is expired or unavailable; use a managed PAT only as the explicit fallback. For push rejection, inspect repository write access and branch drift; /user verification does not prove repository write access and the broker never force-pushes. For pull request rejection, grant pull-request write access and retry Publish PR or call github_publish again with a new tool call.
• Repository publication is unavailable — Git clean filters, unsafe Git configuration, or failed publication-snapshot validation can prevent preparing a publishable checkpoint. Raw recovery checkpoints and normal Stop still preserve accepted changes. Correct the repository configuration, then run another turn or save an edit to prepare a new checkpoint before requesting publication again.
• Lease housekeeping — crabbox list --provider <backend> --json is a read-only inventory. crabbox stop --provider <backend> --id <lease> and crabbox release --provider <backend> --id <lease> are destructive and release a lease manually. OpenClaw keeps the lease alive while its session is placed, then stops heartbeating during teardown so genuinely idle leases expire on the profile's idleTimeout. A temporary heartbeat failure, including a lease claim conflict, warns and keeps the next scheduled renewal. Crabbox 0.43.0 and older do not expose the heartbeat command; OpenClaw warns once per environment and cannot prevent coordinator-idle reaping on those binaries.