Cloud Workers (disposable machines)

Cloud workers run a session's coding work on a disposable machine. The transcript and accepted workspace changes stay with the Gateway. Official hub: docs.openclaw.ai/gateway/cloud-workers. Named in v2026.9.3–9.4 (repository-backed cloud work, then cloud-worker controls).

Opt-in. If cloudWorkers is absent or profiles is empty, OpenClaw does not advertise a Cloud destination. This is not the OpenAI Agents API hosted Linux box. Agents API keeps the harness in OpenAI's cloud. Cloud workers keep placement and credentials on your Gateway and lease a Crabbox (or other plugin) machine.

What runs where

ConcernOpenClaw worker-turnCodex remote-exec
Agent loopCloud box (openclaw worker)Gateway (Codex app-server)
Shell and workspace filesCloud boxCloud node, paired device, or SSH-backed provider
Model inference and provider authGateway (proxied)Gateway (API key or ChatGPT subscription)
TranscriptGatewayGateway

Web search, fetch, memory, and messaging tools still execute on the Gateway under the session policy. HTTP that the commands make still runs at the placement. The same Crabbox profile can host either harness; the selected runtime picks worker-turn vs remote-exec.

Quick start in Control UI

  1. Configure Crabbox for the OS user that runs the Gateway. Keep credentials in Crabbox, not in OpenClaw profile settings. Crabbox 0.80.0+ is required.
  2. New Session → repository or New workspace → Cloud. If no profile exists, OpenClaw can suggest one from your Crabbox backend. Viewing the suggestion does not install a CLI or allocate a machine. Saving it needs administrator access.
  3. Suggested cloud profile: Linux, smallest advertised standard class, 4-hour total lifetime, 45-minute idle timeout and suspend, warm images on. Edit later under Settings → Connections → Cloud environments.

TTL counts from creation, including provisioning. Idle timeout counts inactivity. The earlier deadline ends the lease. Stop finishes after the session shuts down and the provider accepts cleanup. With Crabbox, physical release can continue afterward: the environment stays destroying until release is confirmed, and charges can continue in that interval.

Who may dispatch

A Cloud destination appears when the connected operator has operator.write plus administrator access or an explicit role grant, environments.list advertises at least one profile in dispatchableProfileIds, and the selected agent runtime supports cloud placement. Setup scripts and moves to cloud profiles remain administrator-only. Fresh workspaces do not copy arbitrary Gateway folders; pick New workspace or a repository URL.

Verify before you trust a profile

openclaw config validate --json
openclaw plugins inspect crabbox --runtime --json
crabbox doctor --provider <backend> --json

Read-only readiness does not prove allocation, enrollment, or cleanup. Default gateway.reload.mode: "hybrid" applies cloudWorkers changes without a Gateway restart. With reload off, a Control UI save restarts the Gateway; a file edit waits for a manual restart. Profile changes apply to newly provisioned workers; running workers keep the settings they were admitted with. See plugin hot reload.

Enrollment and public origin

After Crabbox setup, the cloud node dials the Gateway's public TLS endpoint over outbound WebSocket. Cloud dispatch refuses loopback, link-local, or unspecified Gateway addresses before allocating a machine. For a loopback Gateway behind HTTPS ingress, set gateway.publicOrigin to the proxy's bare origin. If that proxy is cloudflared, nginx, or similar, gateway.trustedProxies must include the proxy source address or enrollment fails with proxy_attribution_required. The proxy must also forward /__openclaw__/worker-bootstrap/artifacts/ and preserve Authorization—do not serve those archives as unauthenticated static files.

Related