Installation paths: one‑liner script vs npm vs git
OpenClaw offers three install methods, each with distinct trade‑offs:
One‑liner installer (recommended): `curl -fsSL https://openclaw.ai/install.sh | bash`. Detects Node.js ≥ 22, installs CLI globally, and launches onboarding. Best for clean, fast setup.
npm global install: `npm install -g openclaw@latest` then `openclaw onboard`. For systems that already have Node 22+ or for CI/CD automation where you need version pinning.
Git dev install: Clone from GitHub and `npm install`. Use only if you need to modify core code or contribute. Requires manual `openclaw onboard --install-daemon` afterwards; it does not auto‑register daemon.
Regardless of method, you must run `openclaw onboard --install-daemon` immediately after install or the gateway runs only in the current terminal session and stops on reboot.
Daemon setup: systemd / LaunchAgent / Windows Task Scheduler
`--install-daemon` registers a user‑level service that starts on boot and restarts on crash:
| Platform | Service type | Verify | Management |
|---|---|---|---|
| Linux (systemd) | User unit | `systemctl --user is-enabled openclaw-gateway.service` | `systemctl --user start|stop|restart openclaw-gateway` |
| macOS (launchd) | LaunchAgent plist | `launchctl list | grep openclaw` | `launchctl unload ~/Library/LaunchAgents/com.openclaw.gateway.plist` then `load` |
| Windows (WSL2) | Scheduled Task | `schtasks /Query /TN "OpenClaw Gateway"` | `schtasks /Run /TN "OpenClaw Gateway"` |
User‑level, not system‑level: The daemon runs as your user. Use `systemctl --user`, not `sudo systemctl`. Root‑level commands will not find the service.
Port 18789 conflict: If gateway fails to start, run `lsof -i :18789` (macOS/Linux) or `netstat -ano | findstr :18789` (Windows) to find and kill the conflicting process, or change the port in config.
State directory: Default `~/.openclaw/`. You can override with `OPENCLAW_STATE_DIR` env var or `state.dir` in config. Never place on cloud‑sync folders (iCloud, Dropbox, OneDrive) — they cause lock contention and DB corruption.
WSL2 notes: Ensure Node.js is installed inside WSL. The daemon registers as a WSL user service. External access requires Windows firewall rules or SSH tunneling from Windows host.
Config baseline: bind mode, auth, state directory
Key fields in `~/.openclaw/openclaw.json` to verify before going live:
gateway.bind: Default `127.0.0.1` (loopback only). Change to `0.0.0.0` or a specific IP for remote access. Non‑loopback binding requires auth or Gateway will refuse to start.
gateway.auth: Token‑based auth is default in 2026. Set via `openclaw config set gateway.auth.token
State dir: Keep on local SSD. Avoid cloud‑sync drives — concurrent writes from multiple devices corrupt the SQLite DB. Use `OPENCLAW_STATE_DIR` or `state.dir` to relocate if needed.
gateway.port: Default 18789. If occupied, either kill the existing process or change port in config and restart.
Health ladder: status → logs → doctor → channels probe
Follow this ordered diagnostic chain to isolate the failure layer:
openclaw gateway status: Shows process state, listening address, connected channels. If `disconnected` or `unauthorized`, proceed.
openclaw logs --follow: Live log stream. Look for ERROR/WARN — port binding failures, config key errors, auth rejects, channel disconnects. Logs also available under `~/.openclaw/logs/`.
openclaw doctor: Automated health checks — Node version, port availability, config syntax, state dir perms, API keys, pairing status. doctor prints actionable remediation hints.
openclaw channels status --probe: Per‑channel connectivity test. Shows pairing state, message success rate. If `pairing required`, revisit onboarding or re‑approve device in Control UI.
This ladder enforces service layer → log layer → config layer → business layer progression, preventing wasted effort on the wrong level.
Recovery checklist: port conflicts, env vars, config key drift, pairing loss
Common failure modes and their proven fixes:
Gateway fails to start: port 18789 in use: `lsof -i :18789` → `kill -9
Daemon not starting on boot: Verify registration: `systemctl --user is-enabled openclaw-gateway.service` (Linux) or `launchctl list | grep openclaw` (macOS). If missing, rerun `openclaw onboard --install-daemon`.
Environment variables missing in daemon: Daemon inherits env from user session. For systemd, drop env files into `~/.config/environment.d/`; for LaunchAgent, set `EnvironmentVariables` in plist. After changes, `systemctl --user restart openclaw-gateway` or `launchctl kickstart`.
Config key drift after upgrade: 2026.4.x renamed `gateway.token` → `gateway.auth.token` and now requires explicit `gateway.mode` (default `local`). Run `openclaw doctor` for migration hints or manually edit `openclaw.json` to match new schema.
Non‑loopback bind without auth: If `gateway.bind` is `0.0.0.0` but no `gateway.auth.token` or `gateway.auth.password` set, Gateway aborts with a clear error. Add token auth, then restart.
Channel pairing lost (token revoked, bot deleted): Open Control UI → Devices → remove stale device, then `openclaw onboard` to re‑pair. Or `openclaw pairing list --channel
Docker bind‑mode pitfall: Official Docker setup uses `gateway.bind: lan` (not `localhost` or `0.0.0.0`). If container IP changes to `172.x.x.x`, reset with `openclaw config set gateway.bind lan` and restart container.
Restart order matters: After any config change, try `openclaw gateway restart` first. If that fails, use the platform‑specific service manager: `systemctl --user restart openclaw-gateway` (Linux) or `launchctl kickstart -k gui/$(id -u)/com.openclaw.gateway` (macOS).
Likely you skipped `openclaw onboard --install-daemon`, so the gateway lives only in the current shell. Also check Node.js version (needs ≥ 22) and port 18789 conflicts. Run: `openclaw onboard --install-daemon` → `openclaw gateway status` → `openclaw doctor`.
2026.4.x renamed config keys (e.g., `gateway.token` → `gateway.auth.token`) and now requires explicit `gateway.mode`. Run `openclaw doctor` for migration steps, apply fixes to `~/.openclaw/openclaw.json`, then `openclaw gateway restart`. If still failing, restart the user service directly with `systemctl --user restart openclaw-gateway` (Linux) or `launchctl kickstart` (macOS).
Yes, for production. A cloud Mac (MESHLAUNCH bare‑metal) gives 24/7 uptime, no sleep, stable public IP, and easy firewall/Security Group configuration. Pair with a reverse proxy (Nginx/Caddy) for TLS termination. See pricing page for available regions.
On native Windows use the PowerShell installer `iwr -useb https://openclaw.ai/install.ps1 | iex`. For best compatibility use WSL2 (Ubuntu) and follow the Linux flow. The daemon registers as a Windows Scheduled Task; ensure it runs with your user account and that env vars (API keys) are visible to the task.
Alternative approaches fall short: relying on a local Mac alone exposes you to sleep, ISP outages, and IP changes; Docker without persistent volumes loses state on container replacement; manual starts without daemon registration guarantee eventual downtime.For a stable, AI‑Agent‑ready production environment, MESHLAUNCH's cloud Mac Mini nodes combined with proper daemon configuration (systemd/LaunchAgent) and token auth offer the most reliable 7×24 Gateway operation.