OpenClaw Troubleshooting: The Complete Guide to Fixing Common Issues

Quick Diagnostics: The First 60 Seconds

Before diving into specific problems, run this command ladder on any OpenClaw issue:

• `openclaw gateway status` shows `Runtime: running` and `RPC probe: ok`
• `openclaw doctor` reports no blocking config/service issues
• `openclaw channels status --probe` shows connected/ready channels

# 1. Quick health check
openclaw status

# 2. Gateway status
openclaw gateway status

# 3. Follow logs in real-time
openclaw logs --follow

# 4. Run the doctor (auto-repairs common issues)
openclaw doctor

# 5. Check channel connectivity
openclaw channels status --probe

Gateway Won't Start

The Gateway failing to start is the most common issue. Here's the systematic fix.

Symptom: "Runtime: stopped" or "another gateway instance is already listening"

Step 1: Check what's blocking the start:

Step 2: Common error signatures — EADDRINUSE means port 18789 is already in use (kill the existing process or change port). "refusing to bind gateway without auth" means non-loopback bind needs a token (add gateway.auth.token to config). "Gateway start blocked: set gateway.mode=local" means local mode not enabled (set gateway.mode to local in config).

Step 3: Fix port conflicts:

Step 4: Fix auth requirements for remote binds. If you're binding to lan or tailnet, you need authentication.

Symptom: Gateway shows "Runtime: running" but "RPC probe: failed". This means the Gateway process is alive but unreachable.

Common causes: Wrong auth token (the token in your CLI doesn't match the one in the service config), wrong URL (you're trying to connect to the wrong host/port), or firewall blocking local connections.

openclaw gateway status
openclaw logs --follow

# Find what's using port 18789
lsof -i :18789

# Kill the process if needed
kill <PID>

{
  gateway: {
    mode: "local",
    bind: "lan",
    auth: {
      token: "your-secure-token-here"
    }
  }
}

# Restart the Gateway
openclaw gateway restart

# If that doesn't work, reinstall service metadata
openclaw gateway install --force
openclaw gateway restart

Bot Isn't Replying

When channels show as connected but your bot stays silent, it's almost always a routing or policy issue.

Symptom: Channels are connected but nothing answers.

Common causes: "drop guild message (mention required)" means group chat requires @mention. "pairing request" means the sender needs approval. "blocked/allowlist" means the sender is not in the allowlist.

If your bot won't reply in groups, this is almost always the issue—OpenClaw defaults to ignoring group messages unless mentioned. Configure mention patterns.

Pro tip: For WhatsApp groups, you need to add the bot as an admin to receive all messages. Regular group membership limits what the bot can see.

For DM channels, approve pending pairings:

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

{
  messages: {
    groupChat: {
      mentionPatterns: ["@openclaw", "@your-bot-name", "openclaw"]
    }
  },
  channels: {
    telegram: {
      groups: {
        "*": { requireMention: true }
      }
    },
    discord: {
      groups: {
        "*": { requireMention: false }
      }
    }
  }
}

# List pending pairings
openclaw pairing list --channel telegram

# Approve a specific sender
openclaw pairing approve --channel telegram --sender <sender-id>

Dashboard Connectivity Issues

Symptom: "unauthorized" or "device identity required". The Control UI won't connect? This is usually an auth mismatch.

Step 1: Verify Gateway is running. Step 2: Check auth configuration. Step 3: Get your auth token.

Common auth errors: "device identity required" means non-secure context or missing device auth (use HTTPS or configure device auth). "device nonce required" means client not completing challenge flow (update your OpenClaw client). "unauthorized" means token mismatch (verify tokens match between CLI and dashboard).

For remote access, you have two recommended options: Tailscale (recommended) or SSH tunnel.

openclaw gateway status
openclaw config get gateway.auth
openclaw config get gateway.auth.token

# If no token exists, generate one
openclaw doctor --generate-gateway-token

# Option 1: Tailscale (Recommended)
openclaw gateway --tailscale serve
# Then open https://<your-machine>.tailnet.ts.net/

# Option 2: SSH tunnel
ssh -N -L 18789:127.0.0.1:18789 user@your-vps
# Then open http://127.0.0.1:18789/

Channel Connection Problems

WhatsApp Issues: "missing_scope" or "not_in_channel" means your WhatsApp Web session has expired or lacks permissions. Re-authenticate with `openclaw channels login --channel whatsapp`.

Telegram Issues: If the bot won't respond to /start, verify your bot token and test the bot API. If needed, message @BotFather on Telegram to create a new bot, then reconfigure with `openclaw channels configure telegram`.

Discord Issues: If the bot is not in the server or missing permissions, regenerate the invite link from the Discord Developer Portal. Ensure the bot has Send Messages, Read Message History, and Use Slash Commands permissions.

# WhatsApp
openclaw channels login --channel whatsapp
openclaw channels status --probe --channel whatsapp

# Telegram
openclaw config get channels.telegram.botToken
curl "https://api.telegram.org/bot<TOKEN>/getMe"
openclaw channels configure telegram

# Discord
openclaw channels status --probe --channel discord

Model and API Issues

HTTP 429: Rate Limit Errors. Getting rate limited by Anthropic or OpenAI? Check which model is being used and look for rate limit errors in logs.

Solutions by provider: Anthropic quota exhausted — check billing at console.anthropic.com. Anthropic "Extra usage required for long context" — disable context1m or enable Extra Usage. OpenAI rate limit hit — add fallback models.

"No credentials found for profile" means authentication is not configured. Add credentials with `openclaw models auth add` or use OAuth with `openclaw models auth login`.

"Model X is not allowed" means your configured model isn't in your allowed models list. List available models and update your config accordingly.

# Check which model is being used
openclaw models status

# Look for rate limit errors
openclaw logs --follow | grep -i "rate_limit"

{
  models: {
    defaults: {
      providers: [
        {
          provider: "anthropic",
          models: [
            { name: "claude-opus-4-5-2025-01-31", params: { context1m: false } }
          ]
        }
      ]
    }
  }
}

# Add credentials
openclaw models auth add --provider anthropic --api-key <your-key>

# Or use OAuth
openclaw models auth login --provider openai

# List available models
openclaw models list

# Update config to use an available model
openclaw config set agents.defaults.models[0] "claude-sonnet-4-20250514"

Cron and Heartbeat Not Working

If scheduled tasks never run, check the scheduler status.

Common issues: "cron: scheduler disabled" means cron is turned off (enable in config). "heartbeat skipped (quiet-hours)" means outside active hours (adjust activeHours). "heartbeat skipped (dm-blocked)" means direct message is blocked (set directPolicy to allow).

openclaw cron status
openclaw cron list
openclaw system heartbeat last

{
  automation: {
    cron: {
      enabled: true
    },
    heartbeat: {
      enabled: true,
      activeHours: {
        start: "08:00",
        end: "23:00"
      }
    }
  }
}

Node Pairing Problems

If paired node tools fail, check node status and approvals.

Common node errors: NODE_BACKGROUND_UNAVAILABLE means the node app is not in the foreground. CAMERA_PERMISSION_REQUIRED means missing OS permission (grant camera permission in phone settings). SYSTEM_RUN_DENIED: approval required means exec needs approval. SYSTEM_RUN_DENIED: allowlist miss means the command is blocked (add to exec allowlist).

# Check node status
openclaw nodes status

# Describe specific node
openclaw nodes describe --node <node-id>

# Check approvals
openclaw approvals get --node <node-id>

Browser Tool Failures

If browser automation doesn't work, check browser status and profiles.

Common browser errors: "Failed to start Chrome CDP" means the browser process failed (install Chrome or check path). "browser.executablePath not found" means invalid path (set correct path in config). "Chrome extension relay not attached" means no tab is connected (attach via toolbar button).

# Check browser status
openclaw browser status

# Start browser with profile
openclaw browser start --browser-profile openclaw

# List available profiles
openclaw browser profiles

After Upgrades: Things Suddenly Broke

OpenClaw regularly ships updates that enforce stricter defaults. Here's what commonly breaks after upgrades.

Auth and URL override behavior changed: If you set gateway.mode=remote, CLI calls may be targeting remote while your local service works fine.

Bind and auth guardrails are stricter: Non-loopback binds (lan, tailnet, custom) now require auth.

Pairing and device identity changed: After upgrades, you may need to re-approve devices.

# Check your mode
openclaw config get gateway.mode

# Ensure CLI targets local when needed
openclaw --url http://127.0.0.1:18789 status

# Verify bind and auth are both set
openclaw config get gateway.bind
openclaw config get gateway.auth.token

# List devices and pairings
openclaw devices list
openclaw pairing list --channel telegram

# Re-run doctor to repair
openclaw doctor

Memory Keeps Forgetting Things

If context doesn't persist between sessions, check memory configuration and verify memory files exist.

Ensure persistent memory is configured with semantic mode enabled and both core and episodic stores active.

Pro tip: Make sure your AGENTS.md, SOUL.md, and USER.md files are in your workspace folder (default: ~/.openclaw/workspace/).

# Check memory configuration
openclaw config get memory

# Verify memory files exist
ls -la ~/.openclaw/agents/*/memory/

{
  memory: {
    mode: "semantic",
    enabled: true,
    stores: {
      core: {
        enabled: true,
        path: "memory/core.json"
      },
      episodic: {
        enabled: true,
        path: "memory/episodic/"
      }
    }
  }
}

Windows-Specific Issues

"git not found" or "openclaw not recognized": Install Git for Windows and add git to your PATH. For npm global bin, find your npm prefix with `npm config get prefix` and add it to PATH (typically %AppData%\npm). Restart PowerShell after updating PATH.

Garbled Chinese text in output: This is a console code page mismatch. Set UTF-8 encoding and restart the Gateway.

# Set UTF-8 encoding
chcp 65001
[Console]::InputEncoding = [System.Text.UTF8Encoding]::new($false)
[Console]::OutputEncoding = [System.Text.UTF8Encoding]::new($false)

# Restart Gateway
openclaw gateway restart

When All Else Fails

The `openclaw doctor` command is your best friend—it automatically repairs common issues.

For hard-to-diagnose issues, get verbose logs by following logs in real-time or checking the log file directly.

When asking for help in the OpenClaw Discord or GitHub, generate a read-only diagnosis with log tail (tokens redacted) using `openclaw status --all`.

# Run the doctor
openclaw doctor

# Follow logs in real-time
openclaw logs --follow

# Or check the log file directly
tail -f "$(ls -t /tmp/openclaw/openclaw-*.log | head -1)"

# Get a pasteable report
openclaw status --all

Conclusion

Most OpenClaw issues fall into a few categories: Gateway not running (check port conflicts and auth settings), bot not replying (check pairing, allowlists, and mention requirements), dashboard won't connect (verify auth tokens and connection method), channel issues (re-authenticate the channel), and model errors (check API keys, rate limits, and model configuration). When in doubt, start with `openclaw status`, `openclaw doctor`, and `openclaw logs --follow`. These three commands diagnose the majority of issues in under 60 seconds. Remember: most problems are configuration-related, not bugs. Check your logs first, run the doctor second, and you'll typically find the answer within minutes.

Frequently asked questions