How to Run an OpenClaw Node Host

A node host lets your Gateway stay on one machine while commands run on another. The model still talks to the Gateway; the Gateway forwards selected exec/system calls to the node host. This is useful for build machines, Macs with UI permissions, GPU boxes, or any environment you want available without moving the whole Gateway there.

When this is the right move

Use node host mode when the assistant needs controlled access to a second machine. Do not use it just to avoid proper deployment boundaries. It adds a real execution surface, so approvals and pairing matter. If all you need is another chat channel, configure the channel on the Gateway instead.

The practical workflow

1. Decide where the Gateway lives and where commands should execute. Keep that mental model clear: Gateway receives messages and runs the model; node host executes forwarded commands.
2. Start the node host with a display name so it is recognizable in devices and node status output.
3. If the Gateway is loopback-bound, create an SSH tunnel from the node host to the Gateway host and connect through the tunnel port.
4. Approve the device pairing request on the Gateway host. Re-run devices list before approving if the node retried.
5. Configure exec approvals on the node host and allow only the commands the agent actually needs.

Grounded command or config pattern

The documented foreground and service commands are straightforward. Auth prefers OPENCLAW_GATEWAY_TOKEN or OPENCLAW_GATEWAY_PASSWORD for node-host connections.

openclaw node run --host <gateway-host> --port 18789 --display-name "Build Node"
ssh -N -L 18790:127.0.0.1:18789 user@gateway-host
export OPENCLAW_GATEWAY_TOKEN="<gateway-token>"
openclaw node run --host 127.0.0.1 --port 18790 --display-name "Build Node"
openclaw node install --host <gateway-host> --port 18789 --display-name "Build Node"
openclaw node restart

After the node attempts to connect, approve it from the Gateway side with openclaw devices list and openclaw devices approve <requestId>, then inspect openclaw nodes status. The docs also support naming through --display-name or openclaw nodes rename.

Operator notes

Exec approvals are enforced on the node host, not magically on the Gateway. Approvals live on the node host at ~/.openclaw/exec-approvals.json. That means a build node and a Mac UI node can have different allowlists, ask policies, and risk profiles, which is exactly what you want.

Rollout approach

For run an openclaw node host, I would make the first pass deliberately small: one owner, one machine or channel, one visible test, and one rollback path. OpenClaw features become powerful when they connect to real tools and real messages, so the safest rollout is not a giant configuration day. It is a short rehearsal that proves the docs-grounded path works in your exact workspace before you depend on it while busy.

Common mistake

The common mistake is treating the command as the whole feature. The command starts the workflow, but the surrounding state is what keeps it reliable: config validation, auth, pairing, permissions, logs, and a tiny verification step. If those pieces are skipped, the next failure looks random even when OpenClaw is behaving exactly as configured.

Maintenance rhythm

Once this is working, write down the exact command, config path, or approval decision you used. Future you will not remember the tiny detail that made the setup safe. A small note in the workspace or runbook is cheaper than rediscovering the same behavior during an outage, especially after updates or machine changes.

Safety checks

Be strict. A node host can execute commands on another machine, and approval-backed node runs bind exact request context. The docs call out additional protections for direct shell/runtime file executions, but you should still use sandboxing, separate hosts, or explicit allowlists for broader interpreter workflows.

How to verify it worked

A healthy node host appears in openclaw nodes status, can be described by id/name/IP, and has the expected approvals behavior. Test with a harmless allowed command first, then confirm a disallowed command asks or denies according to the node host policy.

If you want the operator version with sharper checklists, safer defaults, and fewer “why is this broken?” afternoons, The OpenClaw Playbook is the shortcut I would hand to a serious OpenClaw owner.