0cb59d88ff
* docs: fix checkable ux defects in docs/cli and docs/concepts
Works the subset of open `ux` audit findings for docs/cli/ and
docs/concepts/ where the finding names something objectively checkable
against the current tree or the source: a missing prerequisite, a
self-contradiction, an unstated default, or a step a reader cannot
execute as written. Stylistic rows ("add an intro paragraph", "this
section is dense", "consider a table") are left open.
Missing prerequisites and unexecutable steps:
- cli/voicecall: page says the plugin must be installed and enabled but
never gives the commands (r3-1260).
- cli/acp: the `acpx` section uses the external `acpx` npm CLI without
saying where it comes from, and the page also uses `acpx` for the
unrelated `@openclaw/acpx` Gateway plugin, which installs no binary
(r3-1236).
- concepts/memory-builtin: "Run interactive llama.cpp setup once" names
no command; it is `openclaw onboard` (r3-1445).
- concepts/memory-honcho: setup prompts for API credentials the page
never says how to obtain (r3-1476).
- concepts/personal-agent-benchmark-pack: the run command needs a source
checkout and OPENCLAW_ENABLE_PRIVATE_QA_CLI=1, neither stated
(r3-1481).
Contradictions:
- concepts/delegate-architecture: the bindings example configures the
same `delegate` agent with a weaker deny list than the tool-policy
section two screens up, dropping write/edit/apply_patch from an agent
the page says is locked down (r3-1453).
- cli/config vs cli/models: `config set` rejects a model reference it
cannot resolve, `models set` saves it with a warning. Both were
correct and neither said the other existed (r3-1178).
- concepts/typing-indicators: the Defaults list omits the
message-tool-only rule, which resolveTypingMode() applies ahead of the
group rules the list does give (r3-1494).
Missing elements and stale terms:
- concepts/main-session: names the default `all` visibility without
`tools.sessions.visibility` (r5-0010).
- cli/path: never links /plugins/oc-path (r3-1211).
- cli/agents: two Related lists that had drifted apart (r3-1282).
- cli/tasks: the only docs/cli title carrying literal backticks
(r3-1304).
- cli/worker: internal roadmap term "milestone-3 placement owner"
(r3-1268).
- concepts/delegate-architecture: Azure AD is now Microsoft Entra ID
(r3-1452).
- concepts/multi-agent: a JSON5 config example fenced as `js` while the
page's other two use `json5` (r3-1378).
No heading text changed, so no anchor id is added or dropped; verified
with parseDocsDocument over all 15 pages before and after. Adds the two
zh-CN glossary sources check-docs-i18n-glossary requires, each beside a
related existing entry rather than appended at the end.
* docs(models): scope the config-set validation comparison to text models
ClawSweeper P2 on docs/cli/models.md:38. The paragraph covers both
`models set` and `models set-image`, so "the same setting" implied that
`config set agents.defaults.imageModel.primary` also rejects an
unresolvable model. It does not: `pathMayAffectTextModelRefs` in
src/cli/config-model-validation.ts:52 returns true for
`agents.defaults` only when `path[2] === "model"`, so `imageModel` is
excluded and the config mutation validator never runs a model check on
it.
Names `agents.defaults.model` explicitly and says the check is
text-model only, rather than leaving readers to infer a validation
guarantee `config set` does not provide for image models.
7.2 KiB
| 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 Gateway-owned
launcher to start inside a prepared cloud or paired-node worker environment.
It is not a general-purpose command for manual worker registration.
The Gateway installs the matching OpenClaw bundle through the enrolled node's
authenticated connection. The worker launcher starts this command with a
prepared assignment, and the worker connects back to the Gateway over its own
authenticated outbound WebSocket as the dedicated worker role.
Launch contract
The command reads exactly one bounded JSON launch envelope from standard input. The envelope carries the Gateway worker endpoint, minted worker credential, bundle and protocol identity, owner epoch, the single assigned session and turn, and the exact worker-local tool names authorized for that turn. The Gateway resolves this final tool set from current policy before handoff; raw config and scheduled-owner identity never enter the worker envelope. The credential is never accepted through command-line arguments, and this page intentionally provides no credential or hand-authored envelope example.
The node supervisor uses a private managed entry point that can admit successive turns into the same environment while background processes remain. Each turn still receives a fresh bounded envelope, Gateway connection, and tool authority. The standalone command above remains a single-turn entry point.
Launches must fit 25 MiB in each complete serialized form: the node invocation event and the managed worker input line, including the node's connection endpoint. The Gateway trims older complete turns when needed, without discarding the newest provider replay checkpoint. If that replay unit cannot fit, the turn fails before handoff with a visible retry instruction. The managed line limit excludes its final newline; standalone stdin counts every byte.
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. Missing, duplicate, or unknown tool names also invalidate the envelope. Operators should start workers through the cloud worker orchestrator rather than invoke this entry point directly.
If admission exhausts its 120-second retry budget, the terminal error includes
the attempt count, Gateway host and port (or local socket path), and last failure.
connect failed means the WebSocket did not open; check reachability and TLS.
no hello within deadline means it opened but the Gateway did not complete worker
admission. A retryable admission rejection retains its reason. These bounded,
credential-redacted details appear in the node launch journal and turn error.
Container launches revalidate the pinned daemon identity before creating each container. This check allows 30 seconds for a busy daemon; a timeout still fails the launch and names the command. A changed daemon identity remains a hard failure.
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 when present in the Gateway-issued turn authority. An empty authority runs the model with no tools. - 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 model provider credentials. When the Gateway's effective shared GitHub identity
is available, the worker receives a turn-bound access token in its private launch
envelope. The token is materialized in a private per-turn profile inside the
throwaway state directory, with earlier profiles removed before the next binding,
and scrubbed when that directory is removed. The sealed worker launcher binds it
to each exec child. GitHub CLI must be installed on the worker host; the bundle
includes the launcher, not gh.
Materialized skill files are temporary turn inputs in a private directory separate
from worker state and its GitHub credentials. A failed per-turn deletion logs
Materialized skill cleanup failed. Node Claude skill sessions separately report
Node Claude skill session cleanup failed for temporary Workshop configuration. These
bounded, redacted warnings identify files that may remain. Wait until the worker or
session and its owned processes have stopped before checking permissions and manually
removing the reported directory. A completed turn alone does not mean a managed worker
has stopped. These filesystem deletion failures preserve the original success, error,
cancellation, or timeout without replaying work or claiming deletion succeeded.
Worker state deletion, including GitHub credential cleanup, still rejects on failure.
Process draining, authority revocation, database close, and transport or MCP close
retain their existing failure behavior. Invalid skill integrity or delivery limits
still reject the turn.
The worker loads workspace AGENTS.md through the bounded bootstrap loader and
appends Gateway-supplied system instructions as literal text. It does not discover
SYSTEM.md or APPEND_SYSTEM.md from the workspace or agent state directory.
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 worker WebSocket 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
placement, 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 worker WebSocket reconnect can
reattach to an active same-process inference stream.
See Gateway protocol for the closed worker RPC surface and Cloud workers for the architecture and security model.