---

name: openclaw-node-setup description: "Set up and manage OpenClaw remote nodes — headless hosts that connect to your Gateway for remote execution, browser proxy, and emergency recovery. Covers macOS and Linux, with battle-tested solutions for common pitfalls." metadata: { "openclaw": { "emoji": "🖥️", "requires": { "bins": ["ssh"] }, }, }

OpenClaw Node Setup

Set up remote OpenClaw nodes that connect to your Gateway for remote command execution, browser automation, and emergency recovery.

What this skill covers:

• Installing and pairing a headless node (macOS & Linux)
• Running as a persistent service (LaunchAgent / systemd)
• Browser proxy for residential IP browsing
• Emergency recovery scripts (restart Gateway remotely)
• Preventing macOS sleep (server mode)
• Common pitfalls and their solutions

Why use a remote node?

• Run commands on other machines (MacBook at home, office server, lab machine)
• Browser proxy — browse with a residential IP instead of datacenter IP
• Emergency recovery — restart your Gateway when it goes down
• Distributed execution — delegate tasks to different machines

---

Prerequisites

| Requirement | Details | |-------------|---------| | Node.js | ≥ 22 | | OpenClaw | Latest (npm install -g openclaw) | | Network | Tailscale or VPN recommended (don't expose Gateway port publicly) |

Quick Start

1. Install OpenClaw on the node

macOS:

brew install node
npm install -g openclaw

Linux (Ubuntu/Debian):

curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs
npm install -g openclaw

2. First connection (foreground)

openclaw node run \
  --host <gateway-tailscale-ip> \
  --port 18789 \
  --tls \
  --display-name "MyNode"

3. Approve pairing on the Gateway

# On the Gateway machine:
openclaw devices list          # See pending requests
openclaw devices approve <id>  # Approve the node

⚠️ Gotcha: Use openclaw devices approve, NOT openclaw nodes approve. They are different commands.

4. Install as persistent service

macOS (LaunchAgent):

openclaw node install \
  --host <gateway-ip> \
  --port 18789 \
  --tls \
  --display-name "MyNode"

# Start it
launchctl bootstrap gui/$UID ~/Library/LaunchAgents/ai.openclaw.node.plist

Linux (systemd):

openclaw node install \
  --host <gateway-ip> \
  --port 18789 \
  --tls \
  --display-name "MyNode"

systemctl --user enable --now openclaw-node.service

Manage:

openclaw node status
openclaw node stop
openclaw node restart

---

Passwordless sudo (for full remote control)

If you want the agent to run privileged commands on the node:

echo "$USER ALL=(ALL) NOPASSWD: ALL" | sudo tee /etc/sudoers.d/$USER

---

Prevent macOS sleep (server mode)

Keep the Mac awake 24/7, even with the lid closed:

sudo pmset -a \
  sleep 0 \
  disksleep 0 \
  displaysleep 5 \
  womp 1 \
  networkoversleep 1 \
  powernap 1 \
  tcpkeepalive 1 \
  standby 0 \
  autopoweroff 0 \
  hibernatemode 0

| Setting | Value | What it does | |---------|-------|-------------| | sleep 0 | Never sleep | Stays awake even with lid closed | | displaysleep 5 | 5 min | Screen off to save energy | | womp 1 | On | Wake on network access | | standby 0 | Off | No deep standby | | autopoweroff 0 | Off | No auto power off | | hibernatemode 0 | Off | No hibernation | | powernap 1 | On | Background tasks while "sleeping" | | tcpkeepalive 1 | On | Keep TCP connections alive |

Clamshell note: To use the built-in camera with lid closed, you need a fake HDMI dongle (~$5). Without it, macOS disables the camera when the lid closes.

---

Browser Proxy

Nodes automatically advertise a browser proxy. This lets the agent browse the web from the node's IP (useful for residential IP access).

Setup

# On the node, install Playwright's Chromium:
npx playwright install chromium

Usage (from the agent)

browser open target=node node=MyNode profile=openclaw url=https://example.com
browser snapshot target=node node=MyNode profile=openclaw

Disable (if not needed)

Add to node config:

{
  "nodeHost": {
    "browserProxy": {
      "enabled": false
    }
  }
}

---

Emergency Recovery (SSH back to Gateway)

Set up SSH access from the node to the Gateway so you can recover from crashes.

1. Generate SSH key on the node

ssh-keygen -t ed25519 -f ~/.ssh/id_ed25519 -N '' -C 'node-emergency'

2. Add public key to Gateway

# On the Gateway server:
echo "<paste-public-key>" >> ~/.ssh/authorized_keys

3. Create emergency script

Save as ~/emergency-vps.sh on the node:

#!/bin/bash
# Emergency recovery script — run from node to manage Gateway
VPS="user@<gateway-tailscale-ip>"
NVM="export NVM_DIR=/home/user/.nvm && source \$NVM_DIR/nvm.sh"

case "$1" in
  status)
    echo "=== Server Status ==="
    ssh $VPS "uptime && df -h / && free -h | head -2"
    ;;
  gateway-status)
    echo "=== Gateway Status ==="
    ssh $VPS "$NVM && openclaw gateway status 2>&1 | grep -E 'Runtime|Listening|Gateway'"
    ;;
  gateway-restart)
    echo "=== Restarting Gateway ==="
    ssh $VPS "systemctl --user restart openclaw-gateway.service && sleep 2 && systemctl --user is-active openclaw-gateway.service"
    ;;
  gateway-start)
    ssh $VPS "systemctl --user start openclaw-gateway.service"
    ;;
  gateway-stop)
    ssh $VPS "systemctl --user stop openclaw-gateway.service"
    ;;
  reboot)
    echo "=== REBOOTING SERVER ==="
    ssh $VPS "sudo reboot"
    ;;
  logs)
    echo "=== Recent Gateway Logs ==="
    ssh $VPS "tail -50 /tmp/openclaw-1000/openclaw-\$(date +%Y-%m-%d).log"
    ;;
  *)
    echo "Usage: $0 {status|gateway-status|gateway-restart|gateway-start|gateway-stop|reboot|logs}"
    ;;
esac

chmod +x ~/emergency-vps.sh
~/emergency-vps.sh status  # Test it

Tailscale SSH note: First connection may require browser approval at https://login.tailscale.com/.... Do this once while you have physical access.

---

Common Pitfalls (Battle-Tested)

These are real issues we hit during setup. Each one cost 15-60 minutes to debug:

🔴 nginx reverse proxy blocks WebSocket

Symptom: Node connects but immediately disconnects.

Cause: nginx with basic auth or HTTP/2 breaks WebSocket upgrade.

Fix: Connect directly to the Gateway port via Tailscale, bypassing nginx entirely.

🔴 HTTP/2 ALPN breaks WebSocket

Symptom: Connection fails with h2 protocol errors.

Cause: nginx 1.18+ with global http2 directive conflicts with WebSocket upgrade.

Fix: Don't route node connections through nginx. Use direct Tailscale IP + port.

🔴 node.json doesn't read token field

Symptom: Node authenticates but Gateway rejects with "invalid token".

Cause: The token field in ~/.openclaw/node.json may not be read properly.

Fix: Use environment variable instead:

export OPENCLAW_GATEWAY_TOKEN="your-token"
openclaw node run ...

🔴 openclaw nodes approve doesn't work for pairing

Symptom: You run openclaw nodes approve but nothing happens.

Cause: Wrong command. nodes manages already-paired nodes; devices handles pairing.

Fix:

openclaw devices list       # See pending requests
openclaw devices approve <requestId>

🔴 Gateway bound to loopback

Symptom: Node can't connect — "connection refused".

Cause: Gateway defaults to 127.0.0.1 (localhost only).

Fix: Change Gateway bind to lan in config:

{
  "gateway": {
    "bind": "lan"
  }
}

Then restart the Gateway.

🔴 sudo requires password over node

Symptom: sudo: a terminal is required to read the password

Fix: Add passwordless sudo (see above).

🔴 Tailscale SSH needs browser approval

Symptom: SSH hangs, then prints "visit https://login.tailscale.com/..."

Fix: Open the URL on any device where Tailscale is logged in. One-time approval per connection pair.

---

Security Checklist

• [ ] Gateway port closed in public firewall (only via Tailscale/VPN)
• [ ] SSH only via Tailscale (port 22 closed publicly)
• [ ] Exec approvals configured on node (~/.openclaw/exec-approvals.json)
• [ ] Emergency recovery script tested
• [ ] sudo limited to necessary commands (or full NOPASSWD if trusted)

---

Verify Setup

# From the Gateway, check node status:
openclaw nodes status

# Expected output:
# MyNode | darwin | connected | caps: browser, system

From the agent:

nodes status                              # List all nodes
nodes run node=MyNode command=["uptime"]  # Test execution

---

License

MIT