TL;DR
OpenClaw troubleshooting covers connection drops, authentication failures, routing errors, and performance issues. Most problems stem from network instability, incorrect API keys, or misconfigured channels. This guide provides step-by-step fixes for the 15 most common OpenClaw errors.
Installation and Setup Issues
Node.js version mismatch
Problem: openclaw command not found or fails with "unsupported Node version."
Cause: OpenClaw requires Node.js 22 or later. Older versions lack required features.
Fix:
Check your Node version:
node --version
If it's below 22, update Node:
# Using nvm (recommended)
nvm install 22
nvm use 22
# Or download from nodejs.org
Reinstall OpenClaw:
npm install -g openclaw@latest
Verify installation:
openclaw --version
Permission denied during installation
Problem: npm install -g openclaw fails with EACCES or permission errors.
Cause: npm tries to write to system directories without proper permissions.
Fix:
Don't use sudo. Instead, configure npm to use a user directory:
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
Add to your shell profile (~/.zshrc or ~/.bashrc):
export PATH=~/.npm-global/bin:$PATH
Reload your shell:
source ~/.zshrc
Install OpenClaw:
npm install -g openclaw@latest
Config file not found
Problem: OpenClaw can't find ~/.openclaw/config.json after installation.
Cause: The onboarding wizard didn't run or failed silently.
Fix:
Run onboarding manually:
openclaw onboard
If that fails, create the config directory:
mkdir -p ~/.openclaw
Create a minimal config file:
cat > ~/.openclaw/config.json << 'EOF'
{
"version": "1.0.0",
"providers": {},
"agents": {},
"channels": {},
"routing": []
}
EOF
Run onboarding again:
openclaw onboard
Channel Connection Problems
WhatsApp QR code won't scan
Problem: QR code appears but WhatsApp app says "Invalid QR code" or doesn't respond.
Cause: QR code expired or network issues between your phone and OpenClaw.
Fix:
- Make sure your phone and computer are on the same network
- Regenerate the QR code:
openclaw channels logout whatsapp
openclaw channels login whatsapp
- Scan within 30 seconds (QR codes expire quickly)
- If it still fails, check firewall settings:
# macOS
sudo /usr/libexec/ApplicationFirewall/socketfilterfw --add /usr/local/bin/node
# Linux (ufw)
sudo ufw allow 18789/tcp
WhatsApp disconnects after a few hours
Problem: WhatsApp works initially but disconnects after 2-4 hours.
Cause: WhatsApp's protocol requires periodic heartbeats. Network changes or sleep mode interrupt the connection.
Fix:
Enable auto-reconnect:
openclaw channels config whatsapp --auto-reconnect true --reconnect-interval 300
This checks the connection every 5 minutes and reconnects if needed.
If you're on a laptop, prevent sleep while OpenClaw runs:
# macOS
caffeinate -i openclaw gateway
# Linux
systemd-inhibit --what=sleep openclaw gateway
For production, run OpenClaw on a server instead of a laptop.
Telegram bot doesn't receive messages
Problem: Bot is online but doesn't respond to messages.
Cause: Bot lacks necessary permissions or the token is invalid.
Fix:
Test the bot token:
curl https://api.telegram.org/bot<YOUR_TOKEN>/getMe
If this returns an error, regenerate the token:
- Open Telegram and message @BotFather
- Send
/mybots - Select your bot
- Choose "API Token" → "Regenerate Token"
- Update OpenClaw:
openclaw channels update telegram --token NEW_TOKEN
For group chats, add the bot as an admin with "Read Messages" permission.
Discord bot shows offline
Problem: Bot appears offline in Discord server list.
Cause: Missing "Message Content Intent" or invalid token.
Fix:
- Go to Discord Developer Portal
- Select your application
- Go to "Bot" tab
- Enable "Message Content Intent" under Privileged Gateway Intents
- Save changes
- Restart OpenClaw:
openclaw gateway restart
If the bot is still offline, check the token:
openclaw channels test discord
If it fails, regenerate the token in the Developer Portal and update OpenClaw.
iMessage bridge not working (macOS)
Problem: iMessage channel shows "disconnected" or doesn't receive messages.
Cause: Missing accessibility permissions or Messages app not running.
Fix:
- Open System Settings → Privacy & Security → Accessibility
- Add Terminal (or your terminal app) to the allowed list
- Restart OpenClaw:
openclaw gateway restart
- Make sure Messages app is running and signed in
- Test by sending yourself a message
If it still doesn't work, check the bridge process:
ps aux | grep openclaw-imessage-bridge
If it's not running, start it manually:
openclaw channels restart imessage
Authentication and API Errors
Invalid API key
Problem: "Authentication failed" or "Invalid API key" errors in logs.
Cause: Wrong API key, expired key, or key without proper permissions.
Fix:
Verify your API key:
# For Anthropic
curl https://api.anthropic.com/v1/messages \
-H "x-api-key: YOUR_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{"model":"claude-sonnet-4-6","max_tokens":10,"messages":[{"role":"user","content":"Hi"}]}'
# For OpenAI
curl https://api.openai.com/v1/chat/completions \
-H "Authorization: Bearer YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"gpt-4","messages":[{"role":"user","content":"Hi"}],"max_tokens":10}'
If the curl command fails, your key is invalid. Get a new one from your provider's dashboard.
Update OpenClaw:
openclaw config set --provider anthropic --api-key NEW_KEY
Restart the Gateway:
openclaw gateway restart
Rate limit exceeded
Problem: "Rate limit exceeded" or "Too many requests" errors.
Cause: You're sending too many requests to your AI provider.
Fix:
Check your usage:
openclaw stats --period 1h
Enable rate limiting:
openclaw limits set --max-requests 50 --window 3600
This limits you to 50 requests per hour. Adjust based on your provider's limits.
For burst traffic, enable queuing:
openclaw config set --enable-queue true --queue-max-size 100
Messages queue when you hit the rate limit and process when capacity is available.
Model not found
Problem: "Model not found" or "Invalid model" errors.
Cause: You specified a model that doesn't exist or isn't available to your account.
Fix:
List available models:
# Anthropic
curl https://api.anthropic.com/v1/models \
-H "x-api-key: YOUR_KEY"
# OpenAI
curl https://api.openai.com/v1/models \
-H "Authorization: Bearer YOUR_KEY"
Update your agent config:
openclaw agents update default --model claude-sonnet-4-6
Restart the Gateway:
openclaw gateway restart
Insufficient credits
Problem: "Insufficient credits" or "Payment required" errors.
Cause: Your AI provider account ran out of credits or hit billing limits.
Fix:
Check your account balance on your provider's dashboard:
- Anthropic: https://console.anthropic.com/settings/billing
- OpenAI: https://platform.openai.com/account/billing
Add credits or update your payment method.
While you wait, route to a free or local model:
openclaw agents add fallback --provider ollama --model llama2
openclaw routing add --fallback fallback
Message Routing Failures
Messages go to wrong agent
Problem: Messages route to the wrong AI agent despite routing rules.
Cause: Routing rules conflict or have incorrect priorities.
Fix:
List all routing rules:
openclaw routing list
Check for conflicts. Rules with higher priority match first. If you have:
Priority 5: channel=whatsapp → agent=default
Priority 10: sender=+1234567890 → agent=vip
Messages from +1234567890 on WhatsApp go to vip (priority 10 wins).
Remove conflicting rules:
openclaw routing remove <rule-id>
Add rules with correct priorities:
openclaw routing add --channel whatsapp --agent default --priority 1
openclaw routing add --sender +1234567890 --agent vip --priority 10
Test routing:
openclaw routing test --channel whatsapp --sender +1234567890 --message "test"
This shows which agent would handle the message without sending it.
Keyword routing doesn't work
Problem: Messages with specific keywords don't route to the configured agent.
Cause: Keywords are case-sensitive or the message doesn't contain the exact keyword.
Fix:
Make keywords case-insensitive:
openclaw routing add --keyword "debug" --agent debugging --case-insensitive
Use regex for flexible matching:
openclaw routing add --pattern "debug|error|bug" --agent debugging
This matches "debug", "error", or "bug" anywhere in the message.
Test keyword matching:
openclaw routing test --message "I found a debug issue"
Custom routing function errors
Problem: Custom routing function throws errors or doesn't execute.
Cause: Syntax errors, missing dependencies, or incorrect return values.
Fix:
Test your routing function:
openclaw routing test-custom ~/.openclaw/routing.js --message "test"
This runs your function and shows the result or error.
Common issues:
- Syntax errors: Check your JavaScript syntax
- Missing return: Always return an agent name
- Async functions: Don't use async/await in routing functions (they must be synchronous)
Example correct function:
module.exports = function route(message) {
// Always return a string (agent name)
if (message.channel === 'whatsapp') {
return 'whatsapp-agent';
}
return 'default';
};
Example incorrect function:
// DON'T DO THIS
module.exports = async function route(message) {
const result = await someAsyncOperation();
return result; // Async functions not supported
};
Fallback agent not triggered
Problem: When primary agent fails, messages don't route to fallback.
Cause: Fallback not configured or primary agent doesn't report failures correctly.
Fix:
Configure fallback:
openclaw routing set-fallback backup-agent
Test fallback:
# Temporarily disable primary agent
openclaw agents disable default
# Send a test message
openclaw routing test --message "test"
# Should show fallback agent
Re-enable primary agent:
openclaw agents enable default
Performance and Memory Issues
High memory usage
Problem: OpenClaw uses 2GB+ of RAM and keeps growing.
Cause: Session data accumulates over time without cleanup.
Fix:
Check memory usage:
openclaw stats --memory
Clear old sessions:
openclaw sessions clear --older-than 7d
Reduce session timeout:
openclaw config set --session-timeout 1800
Sessions now expire after 30 minutes of inactivity instead of the default 1 hour.
Enable automatic cleanup:
openclaw config set --auto-cleanup true --cleanup-interval 3600
This runs cleanup every hour.
Slow response times
Problem: AI responses take 30+ seconds or time out.
Cause: Network latency, slow AI provider, or queue backlog.
Fix:
Check queue status:
openclaw queue status
If the queue has 50+ messages, increase concurrency:
openclaw config set --max-concurrent-requests 10
This processes 10 messages simultaneously instead of the default 3.
Check network latency to your AI provider:
# Anthropic
ping api.anthropic.com
# OpenAI
ping api.openai.com
If latency is high (>200ms), consider using a different provider or a local model.
Enable request timeout:
openclaw config set --request-timeout 30000
Requests that take longer than 30 seconds fail and retry.
Gateway becomes unresponsive
Problem: Gateway stops responding to messages or API calls.
Cause: Deadlock, infinite loop, or resource exhaustion.
Fix:
Check Gateway status:
openclaw gateway status
If it's frozen, get a thread dump:
kill -SIGUSR1 $(pgrep -f "openclaw gateway")
This writes a thread dump to ~/.openclaw/gateway.log. Look for stuck operations.
Restart the Gateway:
openclaw gateway restart
Enable health checks:
openclaw config set --health-check-interval 60
The Gateway now checks its own health every 60 seconds and restarts if unresponsive.
CPU usage spikes
Problem: OpenClaw uses 100% CPU constantly.
Cause: Infinite loop, excessive logging, or message flood.
Fix:
Check what's consuming CPU:
top -p $(pgrep -f "openclaw gateway")
Reduce log level:
openclaw config set --log-level warn
This disables debug and info logs, reducing I/O.
Check for message floods:
openclaw stats --messages --period 1h
If you're receiving 1000+ messages per hour, enable rate limiting per channel:
openclaw channels config whatsapp --rate-limit 100 --rate-window 3600
Gateway Crashes and Restarts
Gateway crashes on startup
Problem: openclaw gateway crashes immediately with no error message.
Cause: Corrupted config file or missing dependencies.
Fix:
Run in debug mode:
openclaw gateway --debug
This shows detailed error messages.
Common causes:
- Corrupted config: Backup and reset config
cp ~/.openclaw/config.json ~/.openclaw/config.json.backup
openclaw config reset
openclaw onboard
- Missing dependencies: Reinstall OpenClaw
npm uninstall -g openclaw
npm install -g openclaw@latest
- Port already in use: Change the port
openclaw gateway --port 18790
Gateway crashes during operation
Problem: Gateway runs for a while then crashes unexpectedly.
Cause: Unhandled exception, memory leak, or external process killing it.
Fix:
Check crash logs:
tail -100 ~/.openclaw/gateway.log
Look for stack traces or error messages before the crash.
Enable crash dumps:
openclaw config set --enable-crash-dumps true
Next crash writes a dump to ~/.openclaw/crashes/. Share this with the OpenClaw team for debugging.
Run Gateway with auto-restart:
openclaw gateway --auto-restart
The Gateway restarts automatically after crashes.
For production, use a process manager:
# Using pm2
npm install -g pm2
pm2 start openclaw -- gateway
pm2 save
pm2 startup
Session data lost after restart
Problem: Conversations reset after Gateway restarts.
Cause: Sessions not persisted to disk or corrupted session file.
Fix:
Enable session persistence:
openclaw config set --persist-sessions true --session-file ~/.openclaw/sessions.db
Sessions now save to disk every 30 seconds.
Check session file:
ls -lh ~/.openclaw/sessions.db
If it's 0 bytes or missing, sessions aren't saving. Check disk space:
df -h ~
If disk is full, free up space and restart the Gateway.
Restore from backup:
cp ~/.openclaw/sessions.db.backup ~/.openclaw/sessions.db
openclaw gateway restart
Platform-Specific Problems
macOS: "openclaw" cannot be opened
Problem: macOS blocks OpenClaw with "unidentified developer" warning.
Cause: macOS Gatekeeper security feature.
Fix:
Allow OpenClaw:
xattr -d com.apple.quarantine $(which openclaw)
Or go to System Settings → Privacy & Security and click "Allow Anyway" next to the OpenClaw warning.
Linux: Permission denied for inotify
Problem: "ENOSPC: System limit for number of file watchers reached."
Cause: Linux limits the number of files a process can watch.
Fix:
Increase the limit:
echo fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.conf
sudo sysctl -p
Restart OpenClaw:
openclaw gateway restart
Windows: Command not found
Problem: openclaw command not recognized on Windows.
Cause: npm global bin directory not in PATH.
Fix:
Find npm global directory:
npm config get prefix
Add it to PATH:
- Open System Properties → Environment Variables
- Edit "Path" under User variables
- Add
C:\Users\YourName\AppData\Roaming\npm(or the path from above) - Click OK and restart your terminal
Verify:
openclaw --version
Docker: Network issues
Problem: OpenClaw in Docker can't connect to messaging platforms.
Cause: Docker network isolation.
Fix:
Run with host network:
docker run --network host openclaw/openclaw gateway
Or expose the Gateway port:
docker run -p 18789:18789 openclaw/openclaw gateway
For WhatsApp, you need to expose additional ports for QR code scanning:
docker run -p 18789:18789 -p 3000:3000 openclaw/openclaw gateway
Debugging Tools and Logs
Enable debug logging
Get detailed logs:
openclaw config set --log-level debug
openclaw gateway restart
Logs go to ~/.openclaw/gateway.log by default.
Watch logs in real-time:
tail -f ~/.openclaw/gateway.log
Test individual components
Test channels:
openclaw channels test whatsapp
openclaw channels test telegram
openclaw channels test discord
Test agents:
openclaw agents test default --message "Hello"
Test routing:
openclaw routing test --channel whatsapp --sender +1234567890 --message "debug issue"
Inspect Gateway state
Get current state:
openclaw gateway inspect
This shows:
- Active channels and their status
- Configured agents and their health
- Routing rules and priorities
- Queue size and pending messages
- Memory usage and uptime
Export diagnostics
Generate a diagnostic report:
openclaw diagnostics export > openclaw-diagnostics.json
This includes:
- Config (with API keys redacted)
- Recent logs
- Error counts
- Performance metrics
- System info
Share this with support when reporting issues.
Network debugging
Test connectivity to AI providers:
openclaw network test anthropic
openclaw network test openai
This checks:
- DNS resolution
- TLS handshake
- API endpoint reachability
- Latency
If any check fails, you have a network issue.
FAQ
Why does OpenClaw use so much memory?
OpenClaw keeps session history in memory for fast access. Each session stores the full conversation context. If you have 100 active sessions with 50 messages each, that's 5000 messages in memory.
Reduce memory usage:
- Lower session timeout
- Enable automatic cleanup
- Limit context length per session
openclaw config set --session-timeout 1800 --auto-cleanup true --max-context-length 50
Can I run OpenClaw without internet?
Yes, if you use a local AI model. Install Ollama and configure OpenClaw to use it:
# Install Ollama
curl https://ollama.ai/install.sh | sh
# Pull a model
ollama pull llama2
# Configure OpenClaw
openclaw agents add local --provider ollama --model llama2 --endpoint http://localhost:11434
Messaging platforms still need internet, but AI inference runs locally.
How do I migrate to a new machine?
Export your config:
openclaw config export > openclaw-backup.json
Copy openclaw-backup.json to the new machine.
Install OpenClaw:
npm install -g openclaw@latest
Import config:
openclaw config import openclaw-backup.json
Reconnect channels (QR codes and tokens don't transfer):
openclaw channels login whatsapp
openclaw channels update telegram --token YOUR_TOKEN
Why do messages arrive out of order?
OpenClaw processes messages concurrently. If you send 3 messages quickly, they might reach the AI provider in different orders depending on network timing.
Enable sequential processing:
openclaw config set --max-concurrent-requests 1
This processes one message at a time, preserving order. It's slower but guarantees sequence.
Can I use OpenClaw for production?
Yes, but follow these guidelines:
- Run on a server, not a laptop
- Use a process manager (pm2, systemd)
- Enable session persistence
- Set up monitoring and alerts
- Configure rate limits
- Use a reverse proxy (nginx) for the Control UI
- Enable HTTPS
- Back up config regularly
Example systemd service:
[Unit]
Description=OpenClaw Gateway
After=network.target
[Service]
Type=simple
User=openclaw
WorkingDirectory=/home/openclaw
ExecStart=/usr/bin/openclaw gateway --port 18789
Restart=always
RestartSec=10
[Install]
WantedBy=multi-user.target
How do I report bugs?
- Generate diagnostics:
openclaw diagnostics export > diagnostics.json
- Open an issue on GitHub
- Include:
- OpenClaw version (
openclaw --version) - Node.js version (
node --version) - Operating system
- Steps to reproduce
- Diagnostic report (redact sensitive data)
Conclusion
Most OpenClaw issues come from network problems, incorrect config, or platform-specific quirks. This guide covers the 15 most common errors and their fixes.
Key troubleshooting steps:
- Check logs first (
~/.openclaw/gateway.log) - Test components individually (channels, agents, routing)
- Enable debug mode for detailed errors
- Use diagnostic tools to export state
- Join the community for help
If you're building API workflows alongside OpenClaw, check out Apidog for API design, testing, and documentation. It complements OpenClaw's conversational interface with structured API management.
Next steps:
- Bookmark this guide for quick reference
- Set up monitoring to catch issues early
- Join the OpenClaw Discord for real-time help
- Contribute fixes back to the project on GitHub
