Bug type

Behavior bug (incorrect output/state without crash)

Summary

Setting up a Windows node and connecting it to a gateway is unnecessarily confusing. The current flow requires undocumented environment variables, has config files silently overwritten on restart, and splits pairing across two different CLI commands (openclaw devices vs openclaw nodes). A fresh install should be straightforward — it currently isn't.

Steps to reproduce

1 Install OpenClaw on a Windows machine
2 Run openclaw node install --host --port 18789
3 Try to connect to a LAN gateway

Expected behavior

Node connects to gateway successfully, or the install command prompts for the gateway token interactively. Error messages guide the user to the next step.

Actual behavior

• Node fails with token_mismatch — no hint about OPENCLAW_GATEWAY_TOKEN env var or missing --token flag
• Manually editing node.json is overwritten on openclaw node restart
• After fixing token, pairing-required error appears but openclaw nodes pending shows nothing — must use openclaw devices list instead (undiscoverable)
• Full workaround requires: stop service → set env var → run foreground → approve via openclaw devices approve on gateway

OpenClaw version

OpenClaw version: 2026.3.2

Operating system

Windows Server 2022 / Ubuntu 24.04

Install method

npm global

Logs, screenshots, and evidence

gateway log: unauthorized conn=... remote=192.168.0.4 client=SQLSERVER1 node v0.3.15 reason=token_mismatch
gateway log: cause=pairing-required handshake=failed client=node-host clientDisplayName=sqlserver01

Impact and severity

Affected: All users setting up Windows nodes on LAN gateways
Severity: High (blocks onboarding — node cannot connect without extensive troubleshooting)
Frequency: 100% repro on fresh Windows install
Consequence: New users cannot connect nodes without reading source code or getting external help

Additional information

Temporary workaround: Set OPENCLAW_GATEWAY_TOKEN env var before install, then run openclaw node run in foreground (not as service). Approve via openclaw devices approve <id> on the gateway host. Do not use openclaw node restart as it overwrites the config.

This appears to have existed since node host support was added — not a regressio