Troubleshooting Common Issues

#First Steps: openclaw doctor

When something goes wrong, openclaw doctor is your starting point. It runs a comprehensive diagnostic of your entire OpenClaw installation and reports issues with suggested fixes.

Example output:

OpenClaw Doctor
===============
System:
  [PASS] Node.js v22.4.0
  [PASS] Operating system: macOS 15.3 (arm64)
  [PASS] Disk space: 45 GB available
  [PASS] Memory: 16 GB (14.2 GB available)
Configuration:
  [PASS] openclaw.json valid
  [PASS] SOUL.md present (2.4 KB)
  [WARN] API key for OpenAI not configured
  [PASS] API key for Anthropic configured
API Connectivity:
  [PASS] Anthropic API: connected (234ms)
  [SKIP] OpenAI API: not configured
  [PASS] ClawHub: reachable (189ms)
Gateway:
  [PASS] Gateway running (PID 1234, port 3420)
  [PASS] Uptime: 3 days 14 hours
  [PASS] Memory usage: 187 MB
Channels:
  [PASS] Telegram: connected
  [FAIL] Discord: disconnected (invalid token)
  [SKIP] WhatsApp: not configured
Skills:
  [PASS] 15 skills loaded
  [WARN] 1 skill has security warnings
Summary: 1 failure, 2 warnings
Run 'openclaw doctor --fix' to attempt automatic repairs.

#Automatic Fixes

The --fix flag attempts to automatically resolve common issues:

• Regenerating corrupted configuration files
• Restarting the gateway if it is stuck
• Reinstalling broken skills
• Fixing file permissions
• Reconnecting messaging channels

#Agent Not Responding

This is the most common issue. Your agent is running but does not reply to messages.

#Diagnostic Steps

1. 1
   Check if the gateway is running

   Run openclaw health. If the Gateway shows 'Not running', start it with openclaw gateway start.

2. 2
   Check API connectivity

   Run openclaw doctor. Look at the 'API Connectivity' section. If your provider shows an error, your API key may be invalid, expired, or rate-limited.

3. 3
   Check the messaging channel

   Look at the 'Channels' section in openclaw doctor output. If your channel shows 'disconnected', the token or credentials may be wrong.

4. 4
   Check the logs

   Run openclaw logs --follow and send a test message. Watch for error messages in the log output. There is no openclaw gateway logs subcommand; logs are a top-level command.

5. 5
   Verify allowed users

   Check openclaw.json to make sure your user ID is in the allowed_users list for your messaging channel. If it is missing, the agent ignores your messages.

#Common Causes and Fixes

#Permission Errors

#macOS: "Operation not permitted"

OpenClaw needs Full Disk Access and Accessibility permissions on macOS. If you see "Operation not permitted" in the logs:

1. Open System Settings > Privacy & Security > Full Disk Access
2. Add the OpenClaw binary (which openclaw to find the path)
3. Also check Accessibility and add OpenClaw there
4. Restart the gateway: openclaw gateway restart

#Linux: File Permission Denied

If OpenClaw cannot read or write files:

#Linux: Systemd Service Permission Issues

If the systemd service fails with permission errors:

Common fixes:

• Ensure the service runs as the correct user
• Verify loginctl enable-linger is set for the user
• Check that the WorkingDirectory in the service file exists and is accessible

#Skill Installation Failures

#"Skill not found on ClawHub"

The skill name might be different from what you expect. Search for it to find the exact name.

#"Version conflict"

If a skill requires a newer version of OpenClaw:

Then retry the installation:

#"Security audit failed"

The built-in security scanner blocked the skill. There is no openclaw security review; the one documented subcommand is the audit, and --deep "adds best-effort live Gateway probes and plugin-owned security audit collectors":

If you trust the skill after reviewing it, there is no --skip-audit flag either. The documented way past an install policy warning is to acknowledge it:

#"Skill failed to load"

There is no openclaw skills validate. The documented readiness command is check, which "reports missing prerequisites independently of agent exclusion":

Common YAML frontmatter issues:

• Missing required fields (name, version, author, description)
• Invalid YAML syntax (wrong indentation, missing quotes around special characters)
• Duplicate field names

#Gateway Crashes

#Gateway Keeps Crashing and Restarting

Check the crash logs. openclaw logs will "Tail Gateway file logs over RPC", and the page size flag is --limit, not --last:

Look for:

• Out of memory: Too many skills loaded, or context window too large. Reduce max_context_tokens in config.
• Unhandled exception: Usually a bug. Update OpenClaw to the latest version.
• SIGKILL: The OS killed the process (likely out of memory). Increase available RAM or reduce resource usage.

#Gateway Will Not Start

The --verbose flag provides detailed startup information. Common issues:

Port already in use:

Error: EADDRINUSE: address already in use :::3420

Find what is using the port:

Kill the conflicting process or change the port in openclaw.json.

Corrupted configuration:

Error: Failed to parse openclaw.json

Validate the JSON:

If the JSON is corrupted, restore from the rotated backup. There is no backups/ directory: "Any config write (including a --fix repair) rotates a backup to ~/.openclaw/openclaw.json.bak (with a numbered .bak.1...bak.4 ring)", so the most recent good copy sits beside the live file.

Missing dependencies:

Error: Cannot find module 'xxx'

Reinstall OpenClaw:

#Messaging Connection Drops

#Telegram Connection Drops Periodically

Telegram uses long-polling, which can be disrupted by network issues. Increase resilience:

{
  "channels": {
    "telegram": {
      "polling_timeout": 30,
      "retry_delay": 5000,
      "max_retries": -1
    }
  }
}

max_retries: -1 means infinite retries.

#Discord Bot Goes Offline

Discord bots can disconnect due to:

• Rate limiting (too many messages)
• Invalid intents configuration
• WebSocket connection timeouts

Check Discord-specific logs. There is no --filter flag on openclaw logs, so narrow the output yourself:

Ensure your bot has the "Message Content Intent" enabled in the Discord Developer Portal under Bot > Privileged Gateway Intents.

#WhatsApp Webhook Stops Receiving

WhatsApp webhooks can silently fail if:

• Your webhook URL becomes unreachable (server restart, IP change)
• The webhook verification fails
• Meta deactivates the webhook due to errors

Verify your webhook is working:

#iMessage Stops Working After macOS Update

macOS updates can change the Messages database schema or reset permissions:

1. Re-grant Full Disk Access to OpenClaw
2. Restart the Messages app
3. Restart the OpenClaw Gateway
4. If still broken, check the OpenClaw GitHub issues for macOS version-specific fixes

#Heartbeat Issues

#Heartbeat Not Firing

There is no openclaw heartbeat command group and no --last flag. The documented reader is openclaw system heartbeat last, whose siblings are enable and disable, and which "always print the raw RPC JSON payload".

If no heartbeat cycles appear:

• Check that heartbeat.enabled is true in config
• Verify the gateway is running
• Check if active hours are configured and you are outside them
• Look for API errors in the logs

#Heartbeat Using Wrong Model

Read the value from the CLI rather than hunting through the file. There is no openclaw config edit, but openclaw config get reads one key by path:

The command reports the path as unset rather than printing nothing: "A schema-valid but unset path explains that the runtime default applies", and "Optional fields with no runtime value are reported as unset". An unset heartbeat model means the heartbeat runs on the agent's own model. model is one of the heartbeat block's supported fields, so set it with openclaw config set agents.defaults.heartbeat.model "<provider/model>", or run openclaw config file, which "Prints the active config file path", and edit that file by hand.

#Cron Jobs Not Executing

Cron jobs depend on the heartbeat. If the heartbeat is disabled, cron jobs will not run.

Check that:

• The cron job is enabled (not paused)
• The schedule syntax is valid
• The timezone is correct
• The heartbeat is enabled and running

#Performance Issues

#Slow Response Times

If your agent takes a long time to respond:

1. Check API latency: openclaw health --test-api anthropic
2. Check context size: Large conversation histories slow down processing. Reduce max_history_messages.
3. Check skill count: Too many active skills increase prompt size. Disable unused skills.
4. Check the model: Opus 4.6 is slower than Sonnet 4.6, which is slower than Haiku 4.
5. Check system resources: top or htop to see if the machine is overloaded.

#High Memory Usage

The Gateway should use 150-250 MB. If it uses more:

• Too many skills loaded (each adds to memory)
• Memory leak (update to latest OpenClaw version)
• Large data files cached in memory

Restart the gateway to reclaim memory:

#Resetting Your Agent

If all else fails, you can reset various components:

#Soft Reset (Keep Configuration)

Restart the gateway and clear caches:

#Reset Conversation History

This clears all conversation history while keeping your configuration, skills, and SOUL.md.

#Reset Skills to Defaults

This removes all community and custom skills, keeping only built-in skills. Your SOUL.md and configuration are preserved.

#Full Reset

There is no --full flag. The scope is a value: --scope takes config, config+creds+sessions, or full, and --dry-run will "print actions without removing files" first.

After a full reset, run the onboarding wizard again:

#Getting Help

#Check the Logs

The gateway logs contain detailed information about every action:

Filter for errors yourself, since the documented flags are --limit, --max-bytes, --follow, --interval, --json, --plain, --no-color, --local-time and --utc:

#Community Resources

• GitHub Issues: github.com/openclaw/openclaw/issues, Search for your issue or file a new one
• Discord Community: The OpenClaw Discord server has active support channels
• ClawHub Forums: clawhub.ai/forums, Community discussions and skill-specific help

#Filing a Bug Report

When reporting an issue, include:

1. OpenClaw version (openclaw --version)
2. Operating system and version
3. Node.js version (node --version)
4. Output of openclaw doctor
5. Relevant log entries (openclaw logs --limit 50)
6. Steps to reproduce the issue
7. Expected vs actual behavior

#Quick Reference: Common Fixes

#Next Steps

• Security Hardening: prevent issues caused by security misconfigurations
• Heartbeat & Cron: fix heartbeat and scheduling issues
• Messaging Channels: resolve channel-specific problems
• Cost Optimization: when cost limits cause unexpected behavior