OpenClaw Worker CLI: Restricted Cloud Worker Runtime Entry Point

openclaw worker

openclaw worker functions as the restricted runtime entry point for launching a cloud worker orchestrator inside a prepared worker environment. It is not intended as a general command for manually registering workers.

The gateway installs the appropriate OpenClaw bundle and establishes a reverse SSH tunnel pinned to the host key. The worker launcher invokes this command using a preconfigured assignment. Through the tunnel forwarded local socket, the command connects and authenticates as the dedicated worker role.

Launch contract

This command reads a single bounded JSON launch envelope from standard input. The envelope contains the local socket path, a minted worker credential, bundle and protocol identifiers, the owner epoch, the one assigned session and turn, and the precise set of worker local tool names authorized for that turn. Before handoff, the Gateway resolves this final tool set from current policy; raw configuration and scheduled owner identity never appear in the worker envelope. The credential is never accepted through command line arguments, and this page deliberately omits any credential or manually crafted envelope example.

Admission fails closed when the envelope is invalid, the credential is refused, the bundle or protocol features mismatch, or the session and owner epoch are outdated. Missing, duplicate, or unknown tool names also cause the envelope to be rejected. Operators should launch workers through the cloud worker orchestrator rather than calling this entry point directly.

Runtime boundary

The process executes the standard embedded agent loop with a restricted backend:

• The read, write, edit, apply_patch, exec, and process coding tools run locally in the worker workspace when they appear in the turn authority issued by the Gateway. An empty authority runs the model without any tools.
• Model calls go through the gateway inference proxy. No local model authentication profile is loaded.
• Transcript writes use the gateway transcript commit RPC.
• Streaming and tool lifecycle updates use the gateway live event RPC.
• Only the assigned session and turn are accepted.

Worker mode does not start channels, Gateway HTTP surfaces, or automatic plugin startup beyond the assigned session toolset. It uses a disposable state directory and has no standing provider or forge credentials.

Worker to worker session dispatch is not available in this mode. Placement and dispatch remain owned by the gateway: an operator can dispatch an existing local or managed worktree session through the Gateway, but a worker process cannot dispatch itself or another worker.

The prepared assignment carries the transcript context, accepted base leaf, commit sequence, and live event cursor. On a tunnel reconnection, the process reauthenticates with the same credential and owner epoch, preserves the accepted transcript base, replays its unacknowledged live event tail, and reattaches an in flight inference turn with the same identity. The terminal inference message is authoritative if streamed deltas were missed. A superseding owner epoch fences the process and triggers a clean exit.

A stale-base-leaf transcript rejection halts the current run. Worker mode does not retry the rejected sequence against a different leaf, so no duplicate commit is produced; any still uncommitted in memory tail from that run is lost. Relaunch is the responsibility of the milestone 3 placement owner, which must create a fresh assignment from the gateway's authoritative transcript and commit ledger. Similarly, a gateway process restart terminates a pending inference turn with a provider error; only a tunnel or worker WebSocket reconnection can reattach to an active same process inference stream.

See Gateway protocol for the closed worker RPC surface and Cloud workers plan for the architecture and security model.