e427f280d9
* docs(nodes): split the nodes overview by reader job
docs/nodes/index.md was 68,029 bytes, 8,871 words and 35 headings mixing
pairing how-tos, node-host setup, session hosting, command-policy reference and
per-platform allowlists in one page. One H2, "Remote node host (system.run)",
parented 17 H3 sections that were not about system.run, and the page ended with
no next-steps list.
The page already lived in a directory with eleven siblings (audio, camera,
computer-use, images, location-command, media-playback, media-understanding,
presence, talk, troubleshooting, voicewake), so this extends that directory
rather than creating a parallel one. index.md becomes a real index at the same
/nodes route: intro, a "Node pages" list that also names the eleven existing
siblings, and the anchor table below.
Children, one per reader job:
- pairing-and-status.md - approve a node, read status and host stats, upgrade
a fleet across the N-1 protocol window.
- node-host.md - foreground, service, SSH-tunnel and headless node hosts,
gateway preconditions, identity state, and the system.* command surface.
- node-exec.md - allowlist commands, point exec at a node, raw node.invoke,
and exec node binding.
- mcp-and-skills.md - node-hosted MCP servers, node-hosted skills, and local
Ollama inference.
- session-hosting.md - nodeHost.workerRuns, device placement and capacity,
and container isolation.
- session-catalogs.md - Codex, Claude, OpenCode and Pi session discovery and
continuation on paired nodes.
- file-transfers.md - terminal uploads and the File Transfer plugin tools.
- command-policy.md - the platform default allowlists, dangerous-command
opt-ins, gateway.nodes/tools.exec config, and the permissions map.
- device-commands.md - widget panel, camera, screen recording, location, SMS
and device data CLI helpers.
Anchor strategy
Per-anchor redirects are not possible: redirectSource() in
scripts/lib/docs-redirects.mjs rejects any source containing [?#]. Every anchor
the old page published is therefore kept alive on the index itself as authored
<a id="..." /> stubs inside a "Where each section moved" list, each pointing at
its new home. Ids were computed with parseDocsDocument, not a slug
approximation, so the thirteen punctuated headings keep both their encoded and
their cleaned id (for example pairing-%2B-status and pairing-+-status). All 48
ids the pre-split page published resolve on the new index; the index publishes
only two ids of its own, node-pages and where-each-section-moved, so no stub
collides with a heading the index still owns. parseDocsDocument reports zero
collisions on the index and on every child.
Losslessness
Reassembling the 35 section bodies reproduces the original body byte for byte,
apart from the two declared link retargets below. Counts, original body vs
children:
- words 8,634 -> 8,634
- characters 66,320 -> 66,358 (+38, the two retargets)
- code fences 29 -> 29, identical fence for fence as a multiset
- markdown links 30 -> 30
- table rows 16 -> 16, all three tables byte-identical
- the per-platform default-allowlist table is byte-identical: 8 rows, with
iOS 11, watchOS 3, Android 19, macOS 14, Windows 6 and Linux 2 commands
No prose was rewritten. Two intra-page fragment links whose target moved to a
different child, both `](#command-policy)` in device-commands.md, became links
to /nodes/command-policy#command-policy; that is the whole +38 characters.
Sections keep their original relative order within each child, so the five
directional cross-references the page carried ("the environment fallback
above", "see above", "see below", "the static platform-default table above")
all still resolve on their own page.
Also updated: the "Nodes and media" nav group in docs/docs.json, eight in-repo
deep links repointed at the new pages (docs/releases/2026.9.2.md left
untouched, its anchor still resolves through the stubs), fourteen zh-CN
glossary entries for the new titles and index link labels, and
src/docs/config-path-docs.test.ts, which asserts on the `openclaw config`
bracket-path examples that now live in node-exec.md.
Closes audit findings: r3-0443, r3-0445, r3-0447
* docs(nodes): link the relocated device command examples from the exec page
The exec page's "(camera, screen, location, below)" pointed at helpers the
split moved to /nodes/device-commands. Replace the directional word with a
link. Found by ClawSweeper; the orphan-reference scanner's patterns do not
match a bare trailing "below" with no noun phrase in front of it.
3.7 KiB
| summary | read_when | title | sidebarTitle | |||
|---|---|---|---|---|---|---|
| Allowlist node commands, point exec at a node, and invoke commands directly |
|
Run commands on a node | Node exec |
Allowlist the commands
Exec approvals are per node host. Add allowlist entries from the gateway:
openclaw approvals allowlist add --node <id|name|ip> "/usr/bin/uname"
openclaw approvals allowlist add --node <id|name|ip> "/usr/bin/sw_vers"
Approvals live on the node host in
~/.openclaw/state/openclaw.sqlite#exec_approvals_config.
Point exec at the node
Configure defaults (gateway config):
openclaw config set tools.exec.host node
openclaw config set tools.exec.mode allowlist
openclaw config set tools.exec.node "<id-or-name>"
Or per session:
/exec host=node security=allowlist node=<id-or-name>
Once set, any exec call with host=node runs on the node host (subject to the node allowlist/approvals).
host=auto will not implicitly choose the node on its own. An explicit per-call host=node request is allowed from auto only when no sandbox runtime is active; while a sandbox runtime is active, auto rejects it. To run on a node from a sandboxed session, or to make node exec the session default, set tools.exec.host=node or /exec host=node ... explicitly.
Related:
Invoking commands
Low-level (raw RPC):
openclaw nodes invoke --node <idOrNameOrIp> --command device.info --params '{}'
nodes invoke blocks system.run and system.run.prepare; those commands only run through the exec tool with host=node (see above). Higher-level helpers exist for the common "give the agent a MEDIA attachment" workflows (camera, screen, location: see Node device commands).
Long-running streaming node commands use additive node.invoke.progress
events. Each event carries the invoke ID, a zero-based sequence number, and a
bounded UTF-8 text chunk; the Gateway orders chunks before delivering them to
the caller. The existing node.invoke.result remains the single terminal
response. Streaming callers can set an inactivity deadline that starts with the
first progress event and resets after later progress while retaining the
invoke's separate hard timeout during approval and execution. Result, hard
timeout, inactivity timeout, and node disconnect all discard pending stream
state. Caller cancellation emits node.invoke.cancel; the node host then
terminates the matching process tree. Existing request/response commands are unchanged.
Exec node binding
With no node target set, exec host=node selects the sole paired, connected node that supports system.run. Other paired devices do not make the selection ambiguous. If multiple executable nodes are connected, choose a target per call or bind exec to a specific node; the active Canvas target does not select the exec host. A bound or explicit target that is offline or cannot execute commands is rejected rather than redirected to another node.
A binding sets the default node for exec host=node and can be overridden per agent.
Global default:
openclaw config set tools.exec.node "node-id-or-name"
Per-agent override:
openclaw config get agents.entries
openclaw config set 'agents.entries.main.tools.exec.node' "node-id-or-name"
Unset the binding to use the sole eligible node, or choose a target per call when multiple eligible nodes are connected:
openclaw config unset tools.exec.node
openclaw config unset 'agents.entries.main.tools.exec.node'