Run a node host

​

Remote node host (system.run)

• Approval-backed node runs bind exact request context. The exec path prepares a canonical systemRunPlan before approval; once granted, the gateway forwards that stored plan, not any later caller-edited command/cwd/session fields, and re-validates the working directory before running.
• For direct shell/runtime file executions, OpenClaw also best-effort binds one concrete local file operand and denies the run if that file changes before execution.
• If OpenClaw cannot identify exactly one concrete local file for an interpreter/runtime command, approval-backed execution is denied instead of pretending full runtime coverage. Use sandboxing, separate hosts, or an explicit trusted allowlist/full workflow for broader interpreter semantics.

​

Gateway deployments that cannot host nodes

• Machine authentication: Tailscale identity headers do not authenticate node-role connections. In gateway.auth.mode: "trusted-proxy", a new node also cannot supply the proxy’s user identity headers. To use a shared token, switch to token mode and configure gateway.auth.token with a SecretRef; trusted-proxy mode rejects mixed token configuration. A trusted-proxy Gateway can use gateway.auth.password only for clean loopback/direct callers. See trusted-proxy mixed token configuration.
• Node onboarding URL: With only the default gateway.bind: "loopback" and no advertised endpoint, openclaw devices join-code reports: Gateway is only bound to loopback. Set gateway.bind=lan, enable tailscale serve, or configure plugins.entries.device-pair.config.publicUrl. Configure a reachable endpoint through Tailscale Serve, gateway.remote.url, or plugins.entries.device-pair.config.publicUrl. Remote join URLs require TLS; enabling LAN bind alone does not enable plaintext remote join URLs. Explicitly configured loopback endpoints can produce HTTP join URLs, but the joining machine must be able to reach that loopback endpoint, for example through a local tunnel. Plaintext LAN pairing can use a setup code directly.
• Node onboarding support: Join-code creation and /j redemption are core Gateway operations. They do not require enabling the device-pair plugin, even though its retained publicUrl configuration field can supply an endpoint. See Join codes for the printed npx openclaw connect <url> command.
• Device session runtime: Paired-device runners support the embedded OpenClaw runtime and explicitly authorized Codex remote-exec; ACPX routes cannot dispatch to a paired device. Codex requires codex.exec-server.stdio.v1 in gateway.nodes.commands.allow plus its normal pairing and invocation approvals. Runtime policy belongs on provider/model routes, not the ignored whole-agent runtime keys. Multi-agent rosters must also set agents.ownership: "explicit". See Codex paired-device placement and runtime policy.
• Edge routing: When a reverse proxy or access edge fronts the Gateway, the node must satisfy edge auth on the join request, its main Gateway WebSocket, and the worker WebSocket. Keep WebSocket upgrade enabled for /__openclaw__/worker. You can instead exempt /j/* and /__openclaw__/worker from edge identity auth because both routes enforce their own short-lived credentials. See worker protocol.

1. In Cloudflare Zero Trust, create an Access service token. Copy its Client ID and Client Secret when Cloudflare displays them.
2. Add a Service Auth policy that accepts the token on the Access application protecting the Gateway. If /j/* and /__openclaw__/worker are separate Access applications, add the same policy to both.
3. On the node, provide the conventional environment fallback and connect:
   export CF_ACCESS_CLIENT_ID="<client-id>"
   export CF_ACCESS_CLIENT_SECRET="<client-secret>"
   openclaw connect https://gateway.example/j/<code> --service
   

​

Start a node host (foreground)

openclaw node run --host <gateway-host> --port 18789 --display-name "Build Node"

openclaw node run --pair "oc-pair://<setup-code>"

​

Remote gateway via SSH tunnel (loopback bind)

# Terminal A (keep running): forward local 18790 -> gateway 127.0.0.1:18789
ssh -N -L 18790:127.0.0.1:18789 user@gateway-host

# Terminal B: export the gateway token and connect through the tunnel
export OPENCLAW_GATEWAY_TOKEN="<gateway-token>"
openclaw node run --host 127.0.0.1 --port 18790 --display-name "Build Node"

• openclaw node run supports token or password auth.
• Env vars are preferred: OPENCLAW_GATEWAY_TOKEN / OPENCLAW_GATEWAY_PASSWORD.
• Config fallback is gateway.auth.token / gateway.auth.password.
• In local mode, node host intentionally ignores gateway.remote.token / gateway.remote.password.
• In remote mode, gateway.remote.token / gateway.remote.password are eligible per remote precedence rules.
• If active local gateway.auth.* SecretRefs are configured but unresolved, node-host auth fails closed.
• Node-host auth resolution only honors OPENCLAW_GATEWAY_* env vars.

​

Start a node host (service)

openclaw node install --host <gateway-host> --port 18789 --display-name "Build Node"
openclaw node start
openclaw node restart

​

Pair + name

openclaw devices list
openclaw devices approve <deviceRequestId>

openclaw nodes pending
openclaw nodes approve <nodeRequestId>
openclaw nodes describe --node <id|name|ip>

• --display-name on openclaw node run / openclaw node install (persists in the shared nodeHost.config SQLite machine-state value alongside the client instance ID and Gateway connection metadata).
• openclaw nodes rename --node <id|name|ip> --name "Build Node" (gateway override).

​

Headless identity state

• ~/.openclaw/state/openclaw.sqlite (config_machine_state, key nodeHost.config): the client instance ID, display name, and Gateway connection metadata.
• ~/.openclaw/state/openclaw.sqlite (device_identities, key primary): the signed device keypair and derived cryptographic device ID.
• ~/.openclaw/state/openclaw.sqlite (device_auth_tokens): paired device auth tokens keyed by cryptographic device ID and role.

​

System commands (node host / mac node)

openclaw nodes notify --node <idOrNameOrIp> --title "Ping" --body "Gateway ready"
openclaw nodes invoke --node <idOrNameOrIp> --command system.which --params '{"bins":["git"]}'

• system.run returns stdout/stderr/exit code in the payload.
• Shell execution now goes through the exec tool with host=node; nodes remains the direct-RPC surface for explicit node commands.
• nodes invoke does not expose system.run or system.run.prepare; those stay on the exec path only.
• The exec path reads the node policy and prepares a canonical systemRunPlan. Full/off execution resolves working-directory aliases without adding approval-only script checks. When caller or node policy requires approval binding, stricter path and script checks remain in place. Once an approval is granted, the gateway forwards that stored plan, not any later caller-edited command/cwd/session fields.
• system.notify respects notification permission state on the macOS app; supports --priority <passive|active|timeSensitive> and --delivery <system|overlay|auto>.
• Unrecognized node platform / deviceFamily metadata uses a conservative default allowlist that excludes system.run and system.which. If you intentionally need those commands for an unknown platform, add them explicitly via gateway.nodes.commands.allow.
• A system.run request supports cwd, an env map, timeoutMs, and needsScreenRecording — these are fields of the request payload carried on the exec path (see above), not nodes invoke CLI flags.
• For shell wrappers (bash|sh|zsh ... -c/-lc), request-scoped env values are reduced to an explicit allowlist (TERM, LANG, LC_*, COLORTERM, NO_COLOR, FORCE_COLOR).
• For allow-always decisions in allowlist mode, known dispatch wrappers (env, flock, nice, nohup, stdbuf, timeout) persist inner executable paths instead of wrapper paths. If unwrapping is not safe, no allowlist entry is persisted automatically.
• On Windows node hosts in allowlist mode, shell-wrapper runs via cmd.exe /c require approval (allowlist entry alone does not auto-allow the wrapper form).
• Node hosts ignore PATH overrides in the env object and strip a large, maintained set of interpreter/shell startup variables (for example NODE_OPTIONS, PYTHONPATH, BASH_ENV, DYLD_*, LD_*) before running a command. If you need extra PATH entries, configure the node host service environment (or install tools in standard locations) instead of passing PATH via env.
• On macOS node mode, system.run is gated by exec approvals in the macOS app (Settings → Exec approvals). Ask/allowlist/full behave the same as the headless node host; denied prompts return SYSTEM_RUN_DENIED.
• On headless node host, system.run is gated by the local SQLite exec approvals row; on macOS specifically, see the exec-host routing env vars under Headless node host below.

​

Headless node host (cross-platform)

openclaw node run --host <gateway-host> --port 18789

• Device pairing and command-surface approval are still required; follow Pair + name through both stages.
• Client instance metadata, signed device identity, and pairing auth use separate state records; see Headless identity state.
• Exec approvals are enforced locally via ~/.openclaw/state/openclaw.sqlite#exec_approvals_config (see Exec approvals).
• On macOS, the headless node host executes system.run locally by default. Set OPENCLAW_NODE_EXEC_HOST=app to require the companion app exec host, with no local fallback. OPENCLAW_NODE_EXEC_FALLBACK does not change current routing.
• Add --tls / --tls-fingerprint when the Gateway WS uses TLS.

​

Mac node mode

• The macOS menubar app connects to the Gateway WS server as a node (so openclaw nodes … works against this Mac).
• In remote mode, the app opens an SSH tunnel for the Gateway port and connects to localhost.