OpenClaw Troubleshooting: Common Issues and How to Fix Them

Your AI agent was running fine. Then it stopped replying. Or it connects but does nothing. Or you deployed to a VPS and nothing works.

I've been running OpenClaw as a 24/7 autonomous business agent — handling Slack, cron jobs, sub-agents, the whole stack. I've hit most of the failure modes you'll hit. This is the playbook I wish I'd had on day one.

Start Here: The Diagnostic Ladder

Before you do anything else, run these five commands in order:

openclaw status
openclaw gateway status
openclaw logs --follow
openclaw doctor
openclaw channels status --probe

Here's what healthy output looks like:

• openclaw gateway status → Runtime: running and RPC probe: ok
• openclaw doctor → no blocking issues
• openclaw channels status --probe → all connected channels show ready

If any of these fail, you've already narrowed it down. 90% of issues are visible in this first pass.

Issue #1: Gateway Not Running

This is the most common one. Agent is unresponsive? Start with the gateway.

openclaw gateway status

If you see Runtime: stopped, the gateway process died. Common reasons:

Port conflict

lsof -i :18789
openclaw gateway --port 18790

Config misconfiguration

Look for this in logs: Gateway start blocked: set gateway.mode=local

Fix: Open ~/.openclaw/openclaw.json and ensure gateway.mode is set to "local".

Auth mismatch blocking the bind

If logs say refusing to bind gateway ... without auth, you've configured a non-loopback bind without an auth token:

openclaw config get gateway.auth.token
openclaw config get gateway.bind

Service vs CLI config drift

openclaw gateway install --force
openclaw gateway restart

Issue #2: Channel Connected, But Agent Won't Reply

The channel shows "connected" but messages go nowhere.

openclaw channels status --probe
openclaw pairing list --channel slack
openclaw logs --follow

Watch the logs for these signatures:

• drop guild message (mention required) → set requireMention: false in channel config
• pairing request → approve the pending sender
• blocked or allowlist → check channel allowlist config

Per-channel quick fixes

Slack: Verify both app token and bot token, plus required OAuth scopes.

Discord: Check groupPolicy config and message content intent.

Telegram: Disable privacy mode in BotFather, or ensure @mentions.

WhatsApp: Re-login: openclaw channels logout && openclaw channels login --verbose

Issue #3: AI Replies Failing (Rate Limits, Model Errors)

HTTP 429: rate_limit_error

openclaw models status
openclaw config get agents.defaults.models

Disable context1m or switch to a billing-enabled API key.

Issue #4: Cron Jobs Not Firing

openclaw cron status
openclaw cron list
openclaw cron runs --id <jobId> --limit 20

Force-run: openclaw cron run --id <jobId>

Issue #5: Control UI Won't Connect

Common auth error codes: AUTH_TOKEN_MISSING, AUTH_TOKEN_MISMATCH, AUTH_DEVICE_TOKEN_MISMATCH, device identity required.

Issue #6: Node Tools Failing

openclaw nodes status
openclaw nodes describe --node <name>

Issue #7: Browser Tool Failing

openclaw browser status
openclaw browser start --browser-profile openclaw

The Complete Diagnostic Checklist

1. openclaw status
2. openclaw gateway status
3. openclaw logs --follow
4. openclaw doctor
5. openclaw channels status --probe
6. openclaw pairing list --channel <name>
7. openclaw cron status + openclaw cron list
8. openclaw health --json

After an Upgrade: What Usually Breaks

openclaw gateway install --force
openclaw gateway restart
openclaw doctor

Get The OpenClaw Playbook — $9.99 →

Originally published at openclawplaybook.ai. Get The OpenClaw Playbook — $9.99