Skip to main content

​
Troubleshooting

Start here when something is not working. Most issues are diagnosed in two commands: 
openclaw doctor         # config, health, and repair
openclaw status --deep  # gateway + channel probe
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:
SymptomLikely causeFirst step
Gateway won’t start, exits immediatelyUnknown/invalid config keyopenclaw doctor --fix
Gateway won’t start, “address in use”Port collisionlsof -i :18789, change port
Channel stopped working after an upgradeService on Bun or version-managed Nodeopenclaw doctor (offers Node migration)
WhatsApp logged out / status 409-515Conflicting WhatsApp Web sessionRelink (see below)
Bot ignores DMsdmPolicy: "disabled" or sender not in allowFromCheck channels.<channel>.dmPolicy
Bot ignores group messagesgroupPolicy / missing mentionCheck groups + requireMention
”No credentials found”Provider key not in ~/.openclaw/.envAdd key, restart daemon
429 / rate limitSingle key over quotaAdd rotation keys
Browser WebSocket 1008 UnauthorizedBrowser can’t pass bearer tokenTailscale/trusted-proxy auth
Tool blocked unexpectedlySandbox or tool policyopenclaw sandbox explain

​
Gateway not starting

lsof -i :18789
Change the port in ~/.openclaw/openclaw.json:
{ gateway: { port: 18790 } }
Then restart: systemctl --user restart openclaw-gateway (Linux) or openclaw gateway start (macOS/manual).
The gateway refuses to start with unrecognised top-level keys:
openclaw doctor --fix   # removes unknown keys, fills missing defaults
Review the diff before restarting.
systemctl --user status openclaw-gateway
journalctl --user -u openclaw-gateway -n 50
systemctl --user start openclaw-gateway
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.
openclaw doctor   # warns and offers to migrate to a system Node install

​
openclaw command not found

node -v         # should be v24+
npm prefix -g   # should be in your PATH

echo 'export PATH="$(npm prefix -g)/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
openclaw --version

​
Channel issues

openclaw status --deep
ls -l ~/.openclaw/credentials/whatsapp/*/creds.json
If credentials are stale or missing, relink (the phone holding the account must be online):
openclaw channels logout --channel whatsapp
openclaw channels login --channel whatsapp --verbose
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

openclaw models status
openclaw doctor
If the key is in your shell but the daemon can’t find it, it must be in ~/.openclaw/.env:
echo 'ANTHROPIC_API_KEY=sk-ant-...' >> ~/.openclaw/.env
systemctl --user restart openclaw-gateway
Configure key rotation:
# ~/.openclaw/.env
ANTHROPIC_API_KEYS=sk-ant-key1,sk-ant-key2
The gateway retries with the next key on 429 responses.
Use an API key instead of the subscription setup-token:
echo 'ANTHROPIC_API_KEY=sk-ant-...' >> ~/.openclaw/.env
systemctl --user restart openclaw-gateway
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: 
openclaw sandbox explain
openclaw sandbox explain --json
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

openclaw logs --follow
openclaw logs --json
journalctl --user -u openclaw-gateway -f      # Linux
openclaw channels logs --channel whatsapp --follow
For more detail: 
OPENCLAW_LOG_LEVEL=debug openclaw gateway --port 18789

​
Still stuck?

openclaw doctor --deep   # comprehensive scan including extra gateway installs
Read the output carefully — doctor usually identifies the fix. If not: