Gateway won't start
Check: is port 18789 already in use? Run 'lsof -i :18789' to check. Verify your openclaw.json is valid JSON (missing commas are the #1 cause). Check that your API key is valid and billing is set up. Run 'openclaw daemon logs' to see the actual error message.
Models list is empty
This almost always means your API key is wrong or expired. Go back to your provider's console (console.anthropic.com or platform.openai.com) and verify the key is valid. Make sure billing is active. Try restarting the daemon after updating the key.
WhatsApp won't connect
QR code won't scan: ensure your phone and OpenClaw machine are on the same network. Try regenerating the QR. If using Docker, make sure the port mapping is correct. Session keeps expiring: WhatsApp sessions need periodic re-pairing, especially after OpenClaw updates. Check that you're using the latest Baileys version.
PATH issues after installation
If 'openclaw' command is not found after npm install: your npm global bin directory isn't in your PATH. Run 'npm config get prefix' to find where npm puts global binaries, then add that path/bin to your shell profile (~/.zshrc or ~/.bashrc). Restart your terminal after updating.
Permission errors
On macOS/Linux, npm global installs may need sudo. Run 'sudo npm install -g openclaw@latest'. If you're using Docker, check that the mounted volumes have the correct ownership (UID 1000). On WSL2, ensure you're running commands inside the WSL terminal, not Windows CMD.