Fleet Model

OpenClaw fleet model

The model every other skill and command here assumes. Load a reference only when the task needs that depth; the routing table says which.

Shape: source is not state

• One host, N instances. Each instance is one Docker Compose project named <project_prefix><name>.
• Source (compose project, image) and state (the mounted state tree) are separate. Recreating a container keeps state; anything written inside the container outside a mount dies with it.
• Paths come from the live mount table, never from memory. Container-side destinations are fixed by upstream; the host side is whatever docker inspect reports for this instance.
• Isolation is per instance on state dir, config path, workspace and gateway port. Credential directories are not on that list and may deliberately be shared.
• The gateway listens on one container port; each instance publishes its own host port, normally on loopback. Paths and mounts: references/layout.md.

Config

Operator-owned, outside this repo, mode 0600. Ladder, first hit wins: $OPENCLAW_OPS_CONFIG → ./.openclaw-ops.json → ~/.config/openclaw-ops/fleet.json → /etc/openclaw-ops/fleet.json. It holds only what discovery cannot infer: project_prefix, reference, policy.canary, policy.update_channel, policy.soak_days, policy.stale_log_hours, policy.snapshot_dir, and per instance manage, role, criticality, aliases, secrets (names and ids, never values). A host_fingerprint mismatch forces read-only — the file describes another machine. With no config discovery still works and mutations do not. Fields: references/fleet-config.md.

Selector

fleet.py resolve <selector> owns the grammar; nothing else reimplements it.

A mutation must name its targets: empty and all are refused, because a selector that widens as the fleet grows turns a one-instance fix into a fleet-wide incident.

Exec

Every CLI call goes through ${CLAUDE_PLUGIN_ROOT}/scripts/ocexec.py <instance> [--mode auto|hot|cold] [--json] -- <openclaw args…>. Never hand-write docker exec; never call a site wrapper for what the CLI already does.

• hot — compose exec -T into the gateway through the secret-injection wrapper. The normal path.
• cold — one-off container over the state dir. Only while the instance is down, and only for setup, qa, database.
• Refusals are contract: alien instance · --accept-capabilities · --probe against a live gateway · cold over a running state dir · R3/R4 argv, which belong to a command that builds a plan.
• Both streams are redacted; --json parses stdout only. Exit 64 refused · 65 unknown instance · 66 no docker. Modes and standing bans: references/exec-contract.md.

States

A deep battery downgrades ok to degraded and never the reverse. Nothing is hidden: an object that looks like an instance and fails the fingerprint is still listed.

Dry-run and --yes

• A mutation is anything after which observable state differs. The word status in a name proves nothing.
• Every mutation prints eight blocks first: TARGET · PRECHECK · CHANGE · BACKUP · IMPACT · VALIDATE · ROLLBACK · APPLY. R3 and R4 add IRREVERSIBLE · CONFIRM. ROLLBACK is an executable command; prose is a bug.
• --yes applies — never in the same turn the command was first proposed, and never because the user approved something earlier.
• R3 needs a backup that already exists, R4 a typed phrase, anything past the canary a separate confirmation. Good→changed batches fail fast; broken→repair batches continue and report.

Routing