e98c7dfbcb
* feat(gateway-protocol): add session placement schema Closed state discriminator for session execution placement (local/requested/provisioning/syncing/starting/active/draining/reconciling/reclaimed/failed), sessions.dispatch params, and worker-admission transcript/live cursor extensions. Swift protocol models mirror the schema. * feat(state): add worker session placement table worker_session_placements rows carry placement state, transition generation, worker ownership metadata, ACK cursors, and the turn claim columns used for atomic admission. * feat(cloud-workers): add durable placement state machine store SQLite-backed placement store split by concern: state table (placement-state), discriminated record types + shape invariants (placement-record), row codec + CAS transition values (placement-row-codec), atomic turn-claim admission/release/waiters (placement-turn-claims), and lifecycle CAS transitions (placement-store). * feat(cloud-workers): sync workspaces and attach sessions to worker environments Environment service session attachment + turn credentials, tunnel workspace commands over a dedicated SSH runner, and git/plain workspace sync into $HOME/.openclaw-worker/workspaces with an immutable manifest. Symlink escapes are rejected locally before transfer (macOS openrsync stat-fails them opaquely) and again by the remote manifest guard. * feat(worker): run one-shot embedded turns from launch descriptors Worker runtime executes a single embedded turn from a stdin launch descriptor and reports completed/failed/fenced on stdout for the gateway launcher. Terminal lifecycle live events are deferred past the final transcript flush; transcript projection helpers are shared via transcript-message instead of duplicated in the runtime. * feat(cloud-workers): dispatch placements and route worker turns Dispatch service drives local->requested->provisioning->syncing->starting->active with failure teardown (placement-dispatch-failure) and restart/runtime recovery incl. lost-worker reclaim (placement-dispatch-recovery). Worker turn launcher claims the placement turn atomically, builds a windowed launch descriptor (worker-turn-payload), runs the remote one-shot worker, and reconciles the committed transcript; agent runners route turns through the session placement admission provider. * feat(gateway): expose session placement RPCs and startup reconciliation sessions.dispatch RPC with lifecycle admission barriers, operator-facing placement projection on session listings, placement-aware session reset guard, and startup/interval reconciliation wiring for worker placements.
3.6 KiB
summary, read_when, title
| summary | read_when | title | ||
|---|---|---|---|---|
| Internal operator reference for the restricted cloud worker runtime |
|
Worker |
openclaw worker
openclaw worker is the restricted runtime entry point for a cloud worker
orchestrator to launch inside a prepared worker environment. It is not a
general-purpose command for manual worker registration.
The gateway installs the matching OpenClaw bundle and opens the host-key-pinned
reverse SSH tunnel. The worker launcher starts this command with a prepared
assignment. The command connects through the tunnel-forwarded local socket and
admits as the dedicated worker role.
Launch contract
The command reads exactly one bounded JSON launch envelope from standard input. The envelope carries the local socket location, minted worker credential, bundle and protocol identity, owner epoch, and the single assigned session and turn. The credential is never accepted through command-line arguments, and this page intentionally provides no credential or hand-authored envelope example.
Admission fails closed if the envelope is invalid, the credential is rejected, the bundle or protocol features do not match, or the session and owner epoch are no longer current. Operators should start workers through the cloud worker orchestrator rather than invoke this entry point directly.
Runtime boundary
The process runs the normal embedded agent loop with a restricted backend:
- The
read,write,edit,apply_patch,exec, andprocesscoding tools run locally in the worker workspace. - Model calls use the gateway inference proxy. No local model auth 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 plugin auto-start beyond the assigned session toolset. It uses a throwaway state directory and has no standing provider or forge credentials.
Worker-to-worker session dispatch is not exposed in this mode. Placement and dispatch remain gateway-owned: an operator can dispatch an existing local, managed-worktree session through the Gateway, while 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 reconnect, the process re-admits with the same credential and owner epoch, retains 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 causes a clean exit.
A stale-base-leaf transcript rejection fail-stops 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 belongs to the milestone-3 placement owner, which must
create a fresh assignment from the gateway's authoritative transcript and
commit ledger. Likewise, a gateway process restart terminates a pending
inference turn with a provider error; only a tunnel or worker WebSocket
reconnect 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.