Node

text

Copy

openclaw node

Run a headless node host that connects to the Gateway WebSocket and exposes

/ on this machine.

Why use a node host?

Use a node host when you want agents to run commands on other machines in your network without installing a full macOS companion app there.

Common use cases:

• Run commands on remote Linux/Windows boxes (build servers, lab machines, NAS).
• Keep exec sandboxed on the gateway, but delegate approved runs to other hosts.
• Provide a lightweight, headless execution target for automation or CI nodes.

Execution is still guarded by exec approvals and per‑agent allowlists on the node host, so you can keep command access scoped and explicit.

Browser proxy (zero-config)

Node hosts automatically advertise a browser proxy if

is not disabled on the node. This lets the agent use browser automation on that node without extra configuration.

By default, the proxy exposes the node's normal browser profile surface. If you set

, the proxy becomes restrictive: non-allowlisted profile targeting is rejected, and persistent profile create/delete routes are blocked through the proxy.

Disable it on the node if needed:

json5
Copy
{
  nodeHost: {
    browserProxy: {
      enabled: false,
    },
  },
}

Run (foreground)

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

Options:

• text

  Copy

  --host <host>
  : Gateway WebSocket host (default:
  text

  Copy

  127.0.0.1
  )
• text

  Copy

  --port <port>
  : Gateway WebSocket port (default:
  text

  Copy

  18789
  )
• text

  Copy

  --tls
  : Use TLS for the gateway connection
• text

  Copy

  --tls-fingerprint <sha256>
  : Expected TLS certificate fingerprint (sha256)
• text

  Copy

  --node-id <id>
  : Override node id (clears pairing token)
• text

  Copy

  --display-name <name>
  : Override the node display name

Gateway auth for node host

and resolve gateway auth from config/env (no / flags on node commands):

• text

  Copy

  OPENCLAW_GATEWAY_TOKEN
  /
  text

  Copy

  OPENCLAW_GATEWAY_PASSWORD
  are checked first.
• Then local config fallback:
  text

  Copy

  gateway.auth.token
  /
  text

  Copy

  gateway.auth.password
  .
• In local mode, node host intentionally does not inherit
  text

  Copy

  gateway.remote.token
  /
  text

  Copy

  gateway.remote.password
  .
• If
  text

  Copy

  gateway.auth.token
  /
  text

  Copy

  gateway.auth.password
  is explicitly configured via SecretRef and unresolved, node auth resolution fails closed (no remote fallback masking).
• In
  text

  Copy

  gateway.mode=remote
  , remote client fields (
  text

  Copy

  gateway.remote.token
  /
  text

  Copy

  gateway.remote.password
  ) are also eligible per remote precedence rules.
• Node host auth resolution only honors
  text

  Copy

  OPENCLAW_GATEWAY_*
  env vars.

For a node connecting to a non-loopback

Gateway on a trusted private network, set . Without it, node startup fails closed and asks you to use , an SSH tunnel, or Tailscale. This is a process-environment opt-in, not an config key. persists it into the supervised node service when it is present in the install command environment.

Service (background)

Install a headless node host as a user service.

bash
Copy
openclaw node install --host <gateway-host> --port 18789

Options:

• text

  Copy

  --host <host>
  : Gateway WebSocket host (default:
  text

  Copy

  127.0.0.1
  )
• text

  Copy

  --port <port>
  : Gateway WebSocket port (default:
  text

  Copy

  18789
  )
• text

  Copy

  --tls
  : Use TLS for the gateway connection
• text

  Copy

  --tls-fingerprint <sha256>
  : Expected TLS certificate fingerprint (sha256)
• text

  Copy

  --node-id <id>
  : Override node id (clears pairing token)
• text

  Copy

  --display-name <name>
  : Override the node display name
• text

  Copy

  --runtime <runtime>
  : Service runtime (
  text

  Copy

  node
  or
  text

  Copy

  bun
  )
• text

  Copy

  --force
  : Reinstall/overwrite if already installed

Manage the service:

bash
Copy
openclaw node status
openclaw node start
openclaw node stop
openclaw node restart
openclaw node uninstall

Use

for a foreground node host (no service).

Service commands accept

for machine-readable output.

The node host retries Gateway restart and network closes in-process. If the Gateway reports a terminal token/password/bootstrap auth pause, the node host logs the close detail and exits non-zero so launchd/systemd can restart it with fresh config and credentials. Pairing-required pauses stay in the foreground flow so the pending request can be approved.

Pairing

The first connection creates a pending device pairing request (

) on the Gateway. Approve it via:

bash
Copy
openclaw devices list
openclaw devices approve <requestId>

On tightly controlled node networks, the Gateway operator can explicitly opt in to auto-approving first-time node pairing from trusted CIDRs:

json5
Copy
{
  gateway: {
    nodes: {
      pairing: {
        autoApproveCidrs: ["192.168.1.0/24"],
      },
    },
  },
}

This is disabled by default. It only applies to fresh

pairing with no requested scopes. Operator/browser clients, Control UI, WebChat, and role, scope, metadata, or public-key upgrades still require manual approval.

If the node retries pairing with changed auth details (role/scopes/public key), the previous pending request is superseded and a new

is created. Run again before approval.

The node host stores its node id, token, display name, and gateway connection info in

.

Exec approvals

is gated by local exec approvals:

• text

  Copy

  ~/.openclaw/exec-approvals.json
• Exec approvals
• text

  Copy

  openclaw approvals --node <id|name|ip>
  (edit from the Gateway)

For approved async node exec, OpenClaw prepares a canonical

before prompting. The later approved forward reuses that stored plan, so edits to command/cwd/session fields after the approval request was created are rejected instead of changing what the node executes.

Related

• CLI reference
• Nodes