OpenClaw Troubleshooting: 20 Common Problems Solved

Running into issues with OpenClaw? You are not alone. This guide covers the 20 most common problems users encounter, sourced from Reddit threads, GitHub issues, and community Discord. Each problem includes the symptoms, root cause, and step-by-step fix.

1. Agent Not Responding to Messages

Symptoms: You send a message via Telegram/email/WhatsApp but get no response. The admin panel shows the agent as "online."

Root Cause: Usually a channel webhook or polling issue.

Fix:

# Check if the agent process is actually running
openclaw status

# Check channel health
openclaw channels status

# Restart the specific channel
openclaw channels restart telegram

# Check logs for errors
openclaw logs --filter "channel" --since 1h

If the channel shows "connected" but messages are not arriving, verify your webhook URL is publicly accessible and points to the correct port.

2. Skill Installation Fails

Symptoms: openclaw skill install skill-name exits with an error about dependencies or compilation.

Root Cause: Node.js version mismatch or missing build tools.

Fix:

# Check Node.js version (needs 20+)
node --version

# If below 20, update via nvm
nvm install 20
nvm use 20

# Install build tools if needed (Ubuntu/Debian)
sudo apt install build-essential python3

# Retry skill install with verbose output
openclaw skill install skill-name --verbose

3. "Model Not Found" Error

Symptoms: Agent responds with "Error: model not found" or "Invalid model identifier."

Root Cause: Your API key does not have access to the requested model, or the model name is incorrect in config.

Fix:

# Check your current model config
openclaw config get model

# List available models for your API key
openclaw models list

# Set a valid model
openclaw config set model claude-sonnet-4-20250514

Verify your API key has access to the model you are requesting. Some models (like Claude Opus) require a paid tier.

4. High Memory Usage

Symptoms: OpenClaw process uses 1GB+ RAM, system becomes slow.

Root Cause: Large conversation context, memory leaks in skills, or unbounded memory database.

Fix:

# Check current memory usage
openclaw status --resources

# Clear old conversation history
openclaw memory prune --older-than 30d

# Restart to free leaked memory
openclaw restart

# Set memory limits in config.yaml
# memory:
#   max_context_tokens: 50000
#   prune_threshold: 80000

5. Channel Authentication Token Expired

Symptoms: Channel disconnects periodically, logs show "401 Unauthorized" or "token expired."

Root Cause: OAuth tokens for some channels expire and need refreshing.

Fix:

# Re-authenticate the channel
openclaw channels auth telegram

# For email channels, regenerate the webhook secret
openclaw channels regenerate-token email

# Verify connection
openclaw channels test telegram

If you are using Inbounter for email, the API keys do not expire — check that you have not accidentally rotated your key in the Inbounter dashboard.

6. Agent Gives Wrong or Outdated Answers

Symptoms: Agent references old information or seems to "forget" recent context.

Root Cause: SOUL.md is outdated, or the memory database is corrupted.

Fix:

# Update your SOUL.md with current information
nano ~/.openclaw/SOUL.md

# Rebuild the memory index
openclaw memory reindex

# Clear and reimport memory if corrupted
openclaw memory export > backup.json
openclaw memory clear
openclaw memory import < backup.json

7. Docker Container Keeps Restarting

Symptoms: docker ps shows the container restarting every few seconds. Logs show startup errors.

Root Cause: Usually a configuration error or missing environment variables.

Fix:

# Check container logs
docker logs openclaw --tail 50

# Common causes:
# 1. Missing API key - check .env file
# 2. Permission denied on volumes - fix ownership
sudo chown -R 1000:1000 ./config ./data

# 3. Port already in use
sudo lsof -i :3080

# 4. Invalid config.yaml syntax
openclaw config validate

8. Telegram Bot Not Receiving Messages

Symptoms: Bot is online in Telegram but does not respond to messages in groups.

Root Cause: Bot privacy mode is enabled (default in Telegram). Bots in groups only see commands by default.

Fix:

1. Open @BotFather in Telegram
2. Send /mybots and select your bot
3. Go to "Bot Settings" then "Group Privacy"
4. Set to "Disable" (bot will see all messages)
5. Remove and re-add the bot to the group

9. "Rate Limit Exceeded" from LLM Provider

Symptoms: Agent responds with rate limit errors during heavy use.

Root Cause: You are hitting the API rate limits for your LLM provider tier.

Fix:

# config.yaml - add rate limiting
llm:
  rate_limit:
    requests_per_minute: 30
    retry_delay: 5
    max_retries: 3
  fallback_model: "claude-sonnet-4-20250514"  # Cheaper model as fallback

Consider upgrading your API tier or using multiple API keys with load balancing.

10. Skills Not Found After Update

Symptoms: After updating OpenClaw, previously installed skills show as "not found."

Root Cause: The skill directory path changed between versions.

Fix:

# Check where skills are expected
openclaw config get skills_dir

# List actually installed skills
ls ~/.openclaw/skills/

# Re-register skills
openclaw skill scan
openclaw skill list

11. Database Locked Error

Symptoms: "SQLITE_BUSY: database is locked" errors in logs.

Root Cause: Multiple OpenClaw processes accessing the same database, or a crashed process left a lock.

Fix:

# Check for multiple processes
ps aux | grep openclaw

# Kill any stuck processes
openclaw stop --force

# Remove stale lock file if present
rm -f ~/.openclaw/data/openclaw.db-wal
rm -f ~/.openclaw/data/openclaw.db-shm

# Restart
openclaw start

12. Webhook Delivery Failures

Symptoms: External services (email, GitHub) can not reach your OpenClaw webhook endpoint.

Root Cause: Firewall blocking incoming connections, incorrect URL, or SSL issues.

Fix:

# Test webhook endpoint locally
curl -X POST http://localhost:3080/webhook/email -d '{"test": true}'

# Check if port is accessible externally
# Use a service like https://www.whatismyip.com/ to get your public IP
# Then test from another machine or use a webhook testing service

# If behind NAT, set up port forwarding or use a tunnel
# Option 1: Tailscale Funnel
tailscale funnel 3080

# Option 2: Cloudflare Tunnel
cloudflared tunnel --url http://localhost:3080

13. Agent Executes Wrong Commands

Symptoms: Agent misinterprets instructions and runs destructive commands.

Root Cause: Insufficient SOUL.md guidance, or the model needs more explicit instructions.

Fix:

Add safety rails to your SOUL.md:

## Safety Rules
- NEVER run rm -rf without explicit confirmation
- NEVER modify files outside of /home/user/projects/
- Always show the command you plan to run and ask for approval
- Use --dry-run flags when available

Also enable command approval mode:

# config.yaml
safety:
  command_approval: true
  blocked_commands:
    - "rm -rf /"
    - "dd if="
    - "mkfs"

14. SSL Certificate Errors

Symptoms: "UNABLE_TO_VERIFY_LEAF_SIGNATURE" or certificate errors when connecting to APIs.

Root Cause: System CA certificates are outdated, or you are behind a corporate proxy that intercepts SSL.

Fix:

# Update CA certificates
sudo apt update && sudo apt install ca-certificates

# If behind a proxy, add the proxy CA
export NODE_EXTRA_CA_CERTS=/path/to/proxy-ca.pem

# As a last resort (NOT recommended for production)
# export NODE_TLS_REJECT_UNAUTHORIZED=0

15. Cron Jobs Not Firing

Symptoms: Scheduled tasks defined with openclaw cron do not execute at the expected time.

Root Cause: Timezone mismatch or the cron service is not running.

Fix:

# Check cron service status
openclaw cron status

# Verify timezone
openclaw config get timezone
date  # Compare system time

# Set correct timezone
openclaw config set timezone "America/New_York"

# List scheduled jobs
openclaw cron list

# Test a job manually
openclaw cron run job-name

16. Agent Cannot Access Local Files

Symptoms: Agent says it cannot find files that exist on your system.

Root Cause: In Docker, the file is not in a mounted volume. On bare metal, permission denied.

Fix (Docker):

# Add the directory as a volume in docker-compose.yml
volumes:
  - /home/user/documents:/documents:ro

Fix (Bare Metal):

# Check permissions
ls -la /path/to/file

# Fix ownership if needed
sudo chown openclaw:openclaw /path/to/file

17. Email Channel Not Sending

Symptoms: Agent composes emails but they never arrive.

Root Cause: SMTP configuration issues, or emails are being caught by spam filters.

Fix:

If you are using a direct SMTP setup, consider switching to an API-based service. Inbounter provides a simple REST API for sending emails that handles deliverability, SPF, DKIM, and DMARC automatically:

# config.yaml
channels:
  email:
    provider: "inbounter"
    api_key: "${INBOUNTER_API_KEY}"
    from: "agent@yourdomain.com"

This eliminates SMTP configuration headaches and improves deliverability.

18. WhatsApp Connection Drops Frequently

Symptoms: WhatsApp channel disconnects every few hours and needs manual reconnection.

Root Cause: WhatsApp Web session timeout or device conflict.

Fix:

# Use the multi-device beta session
openclaw channels config whatsapp --multi-device

# Keep the session alive
# config.yaml
channels:
  whatsapp:
    keep_alive: true
    reconnect_delay: 10
    max_reconnect_attempts: 50

Also ensure only one device is connected to the WhatsApp account.

19. Agent Responses Are Extremely Slow

Symptoms: Responses take 30+ seconds even for simple questions.

Root Cause: Using an expensive model for all queries, network latency, or context window is too large.

Fix:

# Use a faster model for simple queries
llm:
  default_model: "claude-sonnet-4-20250514"
  complex_model: "claude-opus-4-20250514"
  routing:
    simple_queries: "default_model"
    complex_tasks: "complex_model"

# Check network latency to API provider
curl -w "Connect: %{time_connect}s\nTotal: %{time_total}s\n" \
  -o /dev/null -s https://api.anthropic.com/v1/messages

# Trim context if it is too large
openclaw memory prune --keep-recent 100

20. OpenClaw Won't Start After System Reboot

Symptoms: OpenClaw was working fine but does not start after a server reboot.

Root Cause: Service not enabled for auto-start, or environment variables are not persisted.

Fix (Docker):

# Ensure restart policy is set
# In docker-compose.yml: restart: unless-stopped
docker compose up -d

Fix (Bare Metal):

# Enable systemd service
sudo systemctl enable openclaw

# Check if it failed to start
sudo systemctl status openclaw
journalctl -u openclaw --since "1 hour ago"

# Common cause: environment variables not in service file
# Add EnvironmentFile to your systemd unit

General Troubleshooting Tips

When none of the above solutions work:

# Run the built-in diagnostic tool
openclaw doctor

# Export a diagnostic report for support
openclaw diagnostics export > diagnostic-report.txt

# Check GitHub issues for your specific error
# https://github.com/openclaw/openclaw/issues

# Reset to clean state (back up first!)
openclaw backup create
openclaw reset --config-only

Set up proactive monitoring with Inbounter to receive email or SMS alerts before problems cascade. Configure your agent to send a heartbeat every 5 minutes — if the heartbeat stops, you know something is wrong.

Frequently Asked Questions

Where are OpenClaw logs stored?

By default, logs are at ~/.openclaw/logs/openclaw.log. In Docker, access them with docker logs openclaw.

How do I completely reset OpenClaw?

openclaw stop
rm -rf ~/.openclaw/data/
openclaw init
openclaw start

This will delete all memory, conversations, and settings. Back up first.

Can I run OpenClaw in verbose mode?

Yes: openclaw start --verbose or set logging.level: debug in config.yaml. This generates very large log files, so use it temporarily for debugging only.

How do I report a bug?

Open a GitHub issue with the output of openclaw diagnostics export. Remove any API keys or sensitive information from the report before posting.

Is there an OpenClaw community for help?

Yes. The official Discord server and the r/openclaw subreddit are active communities. Search before posting — most common issues have existing solutions.

How do I check which version I am running?

openclaw --version

Compare with the latest release on GitHub to see if an update might fix your issue.

Tired of discovering OpenClaw issues after they happen? Inbounter lets your AI agent send email and SMS alerts in real time. Get notified the moment something goes wrong.