Preflight · doctor · Error Matrix · Reproducible Deploy
Builders wiring their first Channel usually stall on "Gateway won't start" — not weak models. Node versions, directory permissions, .env vs YAML drift, busy ports, proxies, and DNS can each explode into red logs. This guide gives a preflight checklist, a minimal vs multi-channel comparison, six diagnostic steps (including openclaw doctor), an error symptom matrix, and a cloud migration self-check. For pm2 and always-on baselines, read the persistent cloud deploy playbook; for pricing context, open rental pricing.
Install scripts look short; the expensive part is writing runtime assumptions: which user launches Gateway, where configs resolve, default log paths, which ports must be free, and who owns proxy/DNS. Many "Gateway won't start" incidents are Node plus macOS permission interactions, not OpenClaw logic. The five gaps below show up constantly in community threads — capture them in a Runbook to avoid reinstalling three times before noticing PATH drift.
If you plan Slack or Telegram next, decide token rotation and least-privilege directories early; first channel success with stale env vars makes the second rotation painful.
Node and package manager drift: OpenClaw expects a modern Node LTS. Mixing nvm, fnm, and system node often yields correct node -v in a terminal but an old binary under your process supervisor. Pin one golden invocation and verify the real binary in doctor output.
Working directory and permission boundaries: Cloning into Desktop or iCloud-backed folders invites locks or permission surprises. Keep production trees under a dedicated subtree in the service user's home and document writable AgentSkill paths.
Ports and firewall defaults: Dashboard and Gateway listeners that collide with other daemons exit immediately; corporate proxies or host firewalls may block outbound LLM calls. Add a port scan plus a one-line outbound curl smoke test to preflight.
Multiple config sources: .env, shell profiles, launchd/pm2 env blocks, and YAML overlays together create "I edited the wrong file" bugs. Pick a single source of truth and document precedence.
Logging and observability gaps: Without stdout destinations and rotation, the first long run fills disks or scrolls away the real error. Fix paths and retention at install time — an order of magnitude cheaper than retrofitting monitors.
Check the list, then pick an install path in the next section: minimal Gateway only or multi-channel production topology.
Turning on Slack, mail, and webhooks on day one explodes the failure matrix. Safer: boot Gateway on the smallest profile with healthy logs, then add one Channel Adapter per change window so rollbacks stay obvious. The table aligns expectations for your first review.
| Dimension | Minimal (Gateway + single channel or CLI) | Multi-channel incremental |
|---|---|---|
| Goal | Validate process, config parsing, LLM egress, baseline skills | Validate routing, token rotation, concurrent session isolation |
| Config surface | Few env vars, shallow YAML | Many webhooks/tokens; error surface grows fast |
| Triage order | Gateway logs and doctor first, then model API | Separate channel errors from agent errors |
| Rollback cost | Low — comment one adapter and diff | High — keep per-channel snapshots |
| Best for | First-time builders and small teams | Teams with Runbooks heading to production |
Stabilize an idle Gateway before adapters; reversing the order stacks three error classes in one log stream.
These steps isolate process-level failure (exit on boot, bad config, busy ports). If the process is healthy but messages never arrive, debug adapters only after Gateway looks green. Community CLIs often ship openclaw doctor (or a fix variant) — substitute the exact subcommand from your release notes.
Freeze the repro command: Record npm script vs global CLI vs pm2, plus cwd, in the ticket.
Run environment self-check: Execute openclaw doctor, archive full output, and circle Node paths, permission denials, missing deps, and schema errors.
Validate configs in layers: Parse YAML/JSON, then verify env vars are not overridden by shell profiles.
Check listeners: Ensure Dashboard and Gateway ports are free; note VPN quirks on loopback.
Capture the first 200 log lines: Walk upward from the first ERROR — root causes often appear earlier as warnings.
Minimal rollback test: Disable optional adapters and third-party skills, keep one official sample, then bisect restores.
cd /path/to/openclaw node -v npm -v openclaw doctor openclaw doctor --fix npm run start 2>&1 | tee /tmp/openclaw-boot.log lsof -nP -iTCP -sTCP:LISTEN | grep -E '3000|8787'
Tip: doctor --fix mutates local config — snapshot files or run through change control before using it on production nodes.
Use this as an on-call cheat card: match the symptom, execute the first action, and only then widen the search. If three passes fail, return to section three for full logs and bisect.
| Symptom | Likely cause | First action |
|---|---|---|
| Immediate exit, no stack | Node mismatch or wrong binary on PATH | Align nvm/pm2 node; rerun doctor |
| YAML/JSON parse errors | Indentation, encoding, merge junk | Validate syntax; restore minimal config |
| Port already in use | Zombie process or conflicting daemon | lsof, free the port or change it |
| LLM timeouts / TLS errors | Proxy, DNS, corporate MITM | curl egress test; trust chain / HTTPS_PROXY |
| Channel auth fails while process lives | Expired token or webhook URL drift | Rotate secrets; verify callback host |
| AgentSkill EACCES | Filesystem permissions or sandbox | Fix ownership; audit skill scripts |
Warning: Avoid repeated sudo npm install -g without understanding the process model — globals can report "installed" while runtime still resolves the wrong module tree.
Install firefighting and long-run reliability are adjacent disciplines: the first optimizes reproducible cold starts, the second optimizes crash recovery and auditability. These measurable prompts help reviews without replacing upstream docs.
When laptops cannot meet unattended and zero-dialog requirements, cloud self-checks add guardian restart policy, Dashboard exposure, and log rotation — copy the production anchors from the persistent cloud playbook.
Security reminder: Never paste full .env files into chat; use expiring secret channels and document revocation.
Laptops juggling sleep, updates, and shared sessions inject randomness that working installs cannot fix. Dedicated, region-placed cloud Mac nodes make "boots every day" easier than "boots when the lid is open." For teams baking OpenClaw into delivery standards, VpsMesh Mac Mini cloud rental is usually the better fit: native Apple Silicon, 24/7 metal, flexible rental windows — spend cycles on Gateway logic instead of machine state.
Usually cwd drift or env overrides: pm2/systemd loads another path than your interactive shell. Capture argv and cwd from section three before trusting doctor again.
Heartbeat and unattended SLAs rarely survive laptops. Read the persistent deploy guide, then use the order page and pricing page for regions.
Start at the Help Center for SSH/VNC topics; keep doctor output plus boot logs for escalation.