Skip to main content

​
Troubleshooting

Start here when something is not working. Most issues are diagnosed in two commands:
See Doctor for the full check list, and Health checks for status commands.

​
Failure signatures

Match the symptom to the likely cause before digging deeper:

​
Gateway not starting

Change the port in ~/.openclaw/openclaw.json:
Then restart: systemctl --user restart openclaw-gateway (Linux) or openclaw gateway start (macOS/manual).
The gateway refuses to start with unrecognised top-level keys:
Review the diff before restarting.
If it keeps crashing, run in the foreground to see the error: openclaw gateway --port 18789.
WhatsApp and Telegram require a stable system Node, not Bun. Version-managed Node paths (nvm, fnm, volta, asdf) can break a background service after upgrades because the service does not load your shell init.

​
Gateway restart preflight gate

openclaw gateway restart (and gateway start) runs checks before it touches the service. When a check blocks, no restart happens — the running gateway keeps its current config. The command exits non-zero with the reason. What the preflight checks, in order: When the config validity gate blocks, the output looks like:
Fix it with:
If the post-restart health check times out, the CLI first looks for stale gateway processes (leftover PIDs from a previous run holding or competing for the port), terminates them, and retries the restart once. If it still cannot reach a healthy port within 60 s, it fails with port diagnostics — including “Gateway process is running but port is still free” when the process is up but never bound the port (startup hang, crash loop, or a very slow VM) — plus these next steps:
With --json, the preflight failures and health warnings are emitted as structured JSON (action: "restart", ok: false, warnings: [...]) instead of terminal text — useful for scripts and automation.

​
openclaw command not found

​
Channel issues

If credentials are stale or missing, relink (the phone holding the account must be online):
A conflicting WhatsApp Web session is open. Close all other WhatsApp Web sessions, then relink. Status 515 auto-retries once after pairing — this is normal.
  1. Confirm the bot token is still valid (not revoked in the provider console)
  2. openclaw channels status --channel telegram
  3. Check the allowlist: channels.telegram.allowFrom must include the sender
  4. openclaw channels logs --channel telegram --follow
  1. groupPolicy must be open or allowlist with the group allowlisted
  2. The bot usually requires an @mention — set requireMention: false on the group to disable
  3. Telegram: disable Privacy Mode in BotFather so the bot sees group messages
  4. The sender must be in groupAllowFrom (or allowFrom as fallback)
  1. openclaw gateway status — is it running?
  2. Check dmPolicy — "disabled" means no DM replies
  3. Check allowFrom
  4. openclaw security audit — open DM policies are flagged

​
AI provider issues

If the key is in your shell but the daemon can’t find it, it must be in ~/.openclaw/.env:
Configure key rotation:
The gateway retries with the next key on 429 responses.
Use an API key instead of the subscription setup-token:
If agents.defaults.models is set, it is the allowlist for /model. Either add the model, clear the allowlist, or pick one from openclaw models list.

​
Control panel / web UI

  1. openclaw gateway status
  2. Open http://127.0.0.1:18789/ directly — if that works but another URL doesn’t, check your remote access config
  3. openclaw dashboard opens the correct URL automatically
Browsers can’t pass bearer tokens in WebSocket handshakes. Use Tailscale Serve with gateway.auth.allowTailscale: true, trusted-proxy auth, or connect via the macOS app / CLI.

​
Tools blocked unexpectedly

If an agent says a tool is blocked, inspect the effective policy:
This prints the sandbox mode, whether the session is sandboxed, the effective tool allow/deny and where it came from, and the elevated gates. See Sandboxing.

​
Logs and diagnostics

For more detail:

​
Still stuck?

Read the output carefully — doctor usually identifies the fix. If not: