OpenClaw Troubleshooting: Common Issues and How to Fix Them

Hex · March 30, 2026 · 11 min read

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

# Check if something else grabbed the port
lsof -i :18789

# Start on a different port if needed
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". If you're running inside a container or as a dedicated user, check that user's home directory for the config.

Auth mismatch blocking the bind

If logs say refusing to bind gateway ... without auth, you've configured a non-loopback bind (like lan or tailnet) without an auth token. Fix:

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

Either set the auth token or switch back to loopback bind.

Service vs CLI config drift

If the service is installed but running different config than your CLI expects:

openclaw gateway install --force
openclaw gateway restart

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

This one's sneaky — 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) → group message is being filtered because the agent needs to be @mentioned. Fix: mention the agent in the group, or set requireMention: false in channel config.
pairing request → a new sender is waiting for approval. Fix: openclaw pairing list --channel slack then approve.
blocked or allowlist → sender or channel is filtered by policy. Fix: check your channel allowlist config.

Per-channel quick fixes

Slack: Socket mode connected but no responses? Verify both app token and bot token are correct, and that the required OAuth scopes are present.

Discord: Bot online but guild messages ignored? Check groupPolicy config and ensure message content intent is enabled in the Discord developer portal.

Telegram: Bot responds to DMs but silent in groups? Privacy mode is probably on. Disable it in BotFather, or make sure your users are mentioning the bot.

WhatsApp: Random disconnect loops? Re-login:

openclaw channels logout
openclaw channels login --verbose

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

The agent receives messages and tries to respond, but the AI call fails. Watch for this in logs:

HTTP 429: rate_limit_error: Extra usage is required for long context requests

This means you're hitting the Anthropic long-context path (context1m: true) on an account that isn't eligible. Fix:

openclaw models status
openclaw config get agents.defaults.models

Either disable context1m on the model to fall back to the standard context window, or switch to an API key with billing enabled. You can also configure fallback models so runs continue gracefully when Anthropic rejects the long-context request.

Issue #4: Cron Jobs Not Firing

You set up a cron to run nightly. It's been silent for two days.

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

Common log signatures:

cron: scheduler disabled; jobs will not run automatically → scheduler is off. Enable it in config.
heartbeat skipped, reason=quiet-hours → outside the active hours window. Check your heartbeat.quietHours config.
heartbeat: unknown accountId → the delivery target account ID in your cron config is wrong.

To force-run a cron immediately and verify it works:

openclaw cron run --id <jobId>

Issue #5: Control UI Won't Connect

You open the dashboard and it just spins. Or it shows "unauthorized."

openclaw gateway status
openclaw doctor
openclaw logs --follow

The most common auth error codes and their fixes:

AUTH_TOKEN_MISSING → paste the gateway token into the Control UI settings. Find it with: openclaw config get gateway.auth.token
AUTH_TOKEN_MISMATCH → token mismatch. If canRetryWithDeviceToken=true, allow one retry. Otherwise run the token drift recovery flow.
AUTH_DEVICE_TOKEN_MISMATCH → cached device token is stale. Rotate it: openclaw devices list then re-approve.
device identity required → you're on HTTP, not HTTPS. Device auth requires a secure context.

Issue #6: Node Tools Failing

Your agent has a paired phone or device, but tools like camera, location, or exec aren't working.

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

Common signatures:

NODE_BACKGROUND_UNAVAILABLE → the node app needs to be in the foreground on the device.
LOCATION_PERMISSION_REQUIRED or similar → OS-level permission not granted. Go into device settings and grant it.
SYSTEM_RUN_DENIED: approval required → exec approval pending. Approve it via the Control UI or CLI.
SYSTEM_RUN_DENIED: allowlist miss → the command you're trying to run isn't in the exec allowlist.

Issue #7: Browser Tool Failing

Your agent tries to use the browser tool and gets an error.

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

Common signatures:

Failed to start Chrome CDP on port → Chrome didn't launch. Check that browser.executablePath in config points to a real Chrome binary.
browser.executablePath not found → path is wrong. Update config with the correct Chrome path.
Chrome extension relay is running, but no tab is connected → you're using the extension relay profile and haven't clicked the toolbar button to attach the tab.

---

The Complete Diagnostic Checklist

Bookmark this. Run it any time your agent goes weird:

openclaw status — overall health in one shot
openclaw gateway status — is the process running?
openclaw logs --follow — real-time error stream
openclaw doctor — config/service issue scanner
openclaw channels status --probe — per-channel connectivity
openclaw pairing list --channel <name> — pending approvals?
openclaw cron status + openclaw cron list — scheduler healthy?
openclaw health --json — deep gateway health snapshot

If you're still stuck after this, tail the log file directly:

tail -f /tmp/openclaw/openclaw-$(date +%Y-%m-%d).log | grep -E "error|warn|drop|block"

After an Upgrade: What Usually Breaks

Post-upgrade issues almost always fall into two buckets:

Auth config drift: New versions sometimes have stricter auth defaults. Check gateway.auth.mode, gateway.bind, and gateway.remote.url. If you're on a remote gateway, verify the URL target is still correct.

Pairing state resets: Device or channel pairing can go stale after upgrades. Run openclaw devices list and openclaw pairing list for all your channels, approve anything pending.

When in doubt after an upgrade:

openclaw gateway install --force
openclaw gateway restart
openclaw doctor

Stop Debugging Manually — Get the Full Playbook

Troubleshooting is the boring part. The interesting part is what you build once your agent is running reliably: autonomous content pipelines, self-managing codebases, AI agent teams that actually ship.

The ClawKit playbook covers the complete setup — from first install to production-grade autonomous agent operations, including how to structure your workspace so issues like these don't come back.

Get ClawKit — $9.99 →

One purchase. Lifetime access. Used by developers running serious AI agent setups.