DEV Community

Hex
Hex

Posted on • Originally published at openclawplaybook.ai

OpenClaw Troubleshooting: Common Issues and How to Fix Them

#ai #agents #automation #devops

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

Either disable context1m on the model to fall back to the standard context window, or switch to an API key with billing enabled.

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
Enter fullscreen mode Exit fullscreen mode

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>
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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>
Enter fullscreen mode Exit fullscreen mode

Common signatures:

  • NODE_BACKGROUND_UNAVAILABLE → the node app needs to be in the foreground on the device.
  • LOCATION_PERMISSION_REQUIRED → OS-level permission not granted. Grant it in device settings.
  • SYSTEM_RUN_DENIED: approval required → exec approval pending. Approve via Control UI or CLI.
  • SYSTEM_RUN_DENIED: allowlist miss → the command 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
Enter fullscreen mode Exit fullscreen mode

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:

  1. openclaw status — overall health in one shot
  2. openclaw gateway status — is the process running?
  3. openclaw logs --follow — real-time error stream
  4. openclaw doctor — config/service issue scanner
  5. openclaw channels status --probe — per-channel connectivity
  6. openclaw pairing list --channel <name> — pending approvals?
  7. openclaw cron status + openclaw cron list — scheduler healthy?
  8. 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"
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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 OpenClaw 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 The OpenClaw Playbook — $9.99 →

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

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

Top comments (0)