Troubleshooting

OpenClaw setup troubleshooting

This page is for setup failures after or during installation. Use it to diagnose command-not-found, gateway, dashboard, token, and provider auth problems with minimal guesswork.

If OpenClaw is not installed yet, start at install OpenClaw. If you want the full guided setup flow, use OpenClaw setup guide.

Decision tree
  1. Can you run openclaw --help? If no, fix install/PATH first.
  2. Does openclaw gateway status show healthy? If no, fix gateway/runtime.
  3. Does openclaw dashboard open and connect? If no, fix auth/token network path.
  4. Do channels/providers fail while gateway is healthy? Debug integration/auth config.

Install failures

  • Confirm Node 22+ is installed.
  • Retry with official installer script first.
  • If npm/pnpm path was used, ensure global bin is in PATH.
node -v
npm -v
npm prefix -g
echo "$PATH"

openclaw: command not found

Add npm global bin to PATH and restart shell:

export PATH="$(npm prefix -g)/bin:$PATH"

Then run openclaw --version to confirm.

Onboarding failures

  • Re-run wizard: openclaw onboard --install-daemon.
  • Use openclaw doctor to detect invalid/legacy config.
  • If provider auth fails, re-enter credentials through openclaw configure.

Gateway unreachable

  • Check service: openclaw gateway status.
  • Try foreground mode: openclaw gateway --port 18789.
  • If remote, verify tunnel/mesh path before UI debugging.

Dashboard unauthorized / WebSocket 1008

  • Get token: openclaw config get gateway.auth.token.
  • If missing/invalid: openclaw doctor --generate-gateway-token.
  • Paste token in dashboard settings and reconnect.

Provider auth mismatch (model errors, unauthorized API)

  • Validate provider key and default model pair.
  • Reconfigure via openclaw configure.
  • Run minimal test in dashboard after config update.

Messaging integration problems

  • Confirm bot token and channel binding are correct.
  • Verify allowlist rules if messages are silently ignored.
  • Test first in Control UI to isolate channel vs runtime issues.

Memory search confusion

  • Memory is file-backed: ensure workspace memory files exist and are writable.
  • If semantic recall is expected, confirm memory search backend/provider setup.
  • If memory issues started after switching model providers, clear session files and retest to remove stale provider-specific context.
  • When in doubt, test with a small known memory note and query it explicitly.

For secure production rollouts, pair this with security hardening guidance.

Cookie preferences