Node

Run a headless node host that connects to gateway WebSocket and exposes

''system.run'' / ''system.which'' on the local machine.

Use a node host when you want agents to run commands on other computers in your

network without installing the full macOS companion app there.

Common use cases:

- Run commands on remote Linux/Windows machines (build servers, lab machines, NAS).

- Keep execution sandboxed on the gateway but delegate approved runs to other hosts.

- Provide a lightweight, headless execution target for automation or CI nodes.

Execution remains protected by execution approvals and per-agent allowlists on the

node host, so you can keep command access scoped and explicit.

If ''browser.enabled'' is not, the node host automatically advertises browser proxy

disabled on the node. This allows agents to use browser automation on that node

without extra configuration.

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

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

Options:

- ''--host <host>'': Gateway WebSocket host (default: ''127.0.0.1'')

- ''--port <port>'': Gateway WebSocket port (default: ''18789'')

- ''--tls'': Use TLS for gateway connection

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

- ''--node-id <id>'': Override node ID (clears pairing token)

Install headless node host as a user service.

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

Options:

- ''--host <host>'': Gateway WebSocket host (default: ''127.0.0.1'')

- ''--port <port>'': Gateway WebSocket port (default: ''18789'')

- ''--tls'': Use TLS for gateway connection

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

- ''--node-id <id>'': Override node ID (clears pairing token)

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

- ''--runtime <runtime>'': Service runtime (''node'' or ''bun'')

- ''--force'': Reinstall/overwrite (if already installed)

Manage service:

openclaw node status
openclaw node stop
openclaw node restart
openclaw node uninstall

Use ''openclaw node run'' as a foreground node host (no service).

Service commands accept ''--json'' for machine-readable output.

First connection creates a pending node pairing request on the gateway.

Approve via:

openclaw nodes pending
openclaw nodes approve <requestId>

Node host stores its node ID, token, display name, and gateway connection info in

''~/.openclaw/node.json''.

''system.run'' is approved by local exec approver:

- ''~/.openclaw/exec-approvals.json''

- ''Execution approvals''

- ''openclaw approvals --node <id|name|ip>'' (edit from gateway)