Gateway Troubleshooting

This guide helps you diagnose and resolve common issues with OpenClaw Gateway. It covers startup problems, connection issues, performance problems, and error scenarios.

Quick Diagnosis

Health Check

Start with a comprehensive health check:

# Check overall gateway health
openclaw gateway health

# Detailed status
openclaw gateway status --detailed

# Check all channels
openclaw channels status --all

# Test agent connectivity
openclaw agent test

Common Issues Overview

Issue Category	Common Symptoms	Quick Fix
Startup	Gateway won’t start, crashes immediately	Check configuration, permissions, ports
Network	Can’t connect to messaging platforms	Verify internet, credentials, API status
Performance	Slow responses, high memory usage	Check resources, optimize configuration
Authentication	Token errors, permission denied	Verify tokens, check permissions
Messages	Messages not sending/receiving	Check channel configuration, logs

Startup Issues

Gateway Won’t Start

Check Configuration

# Validate configuration syntax
openclaw config validate

# Show configuration
openclaw config show

# Check specific sections
openclaw config validate --section gateway
openclaw config validate --section channels

Common Configuration Errors

Invalid JSON syntax:

# Error: Configuration file contains invalid JSON
# Fix: Check JSON syntax
cat ~/.openclaw/openclaw.json | jq .

# Or use online JSON validator

Missing required fields:

# Error: Missing required field 'gateway.port'
# Fix: Add missing field
openclaw config set gateway.port 18789

Invalid values:

# Error: Invalid port number
# Fix: Use valid port (1-65535)
openclaw config set gateway.port 18789

Permission Issues

# Check file permissions
ls -la ~/.openclaw/

# Fix permissions
chmod 600 ~/.openclaw/openclaw.json
chmod 700 ~/.openclaw/

# Check process permissions
ps aux | grep openclaw

# Run as correct user
sudo -u username openclaw gateway

Port Conflicts

# Check if port is in use
netstat -an | grep 18789
lsof -i :18789

# Kill conflicting process
sudo kill -9 <PID>

# Or use different port
openclaw config set gateway.port 19000

Gateway Crashes on Startup

Check Logs

# View startup logs
openclaw gateway logs --tail 50

# View error logs
openclaw gateway logs --level error

# View logs with timestamp
openclaw gateway logs --follow --timestamp

Common Crash Causes

Memory issues:

# Check available memory
free -h

# Increase memory limit
openclaw config set gateway.maxMemory "2GB"

# Use 64-bit version if available

Dependency issues:

# Check Node.js version
node --version  # Should be 22+

# Reinstall dependencies
npm install -g openclaw@latest

# Or from source
cd /path/to/openclaw
npm install
npm build

Network Issues

Cannot Connect to Messaging Platforms

General Network Check

# Check internet connectivity
ping 8.8.8.8
curl -I https://www.google.com

# Check DNS resolution
nslookup api.telegram.org
nslookup web.whatsapp.com

# Check firewall
sudo ufw status
sudo iptables -L

WhatsApp Connection Issues

# Test WhatsApp connectivity
openclaw channels test whatsapp

# Check WhatsApp Web status
curl -I https://web.whatsapp.com

# Check QR code generation
openclaw channels login whatsapp --test

# Common fixes:
# 1. Ensure WhatsApp is not active elsewhere
# 2. Check network connectivity
# 3. Re-scan QR code
openclaw channels logout whatsapp
openclaw channels login whatsapp

Telegram Connection Issues

# Test Telegram API
curl -X GET "https://api.telegram.org/bot<TOKEN>/getMe"

# Test bot token
openclaw channels test telegram --token "YOUR_TOKEN"

# Check webhook status
openclaw channels webhook status telegram

# Common fixes:
# 1. Verify bot token is correct
# 2. Check bot is not blocked by Telegram
# 3. Ensure webhook URL is accessible
openclaw config set channels.telegram.webhook.enabled false
openclaw config set channels.telegram.polling.enabled true

Discord Connection Issues

# Test Discord API
curl -X GET "https://discord.com/api/v10/users/@me" \
  -H "Authorization: Bot <TOKEN>"

# Test gateway connection
openclaw channels test discord

# Check bot permissions
# 1. Go to Discord Developer Portal
# 2. Verify bot has correct intents
# 3. Check bot is in server with proper permissions

# Reconnect Discord
openclaw channels reconnect discord

SSL/TLS Issues

Certificate Problems

# Check SSL certificate
openssl s_client -connect api.telegram.org:443

# Check certificate expiration
openssl s_client -connect api.telegram.org:443 2>/dev/null | \
  openssl x509 -noout -dates

# Fix certificate issues (Linux)
sudo update-ca-certificates

# Fix certificate issues (macOS)
brew update && brew upgrade ca-certificates

Webhook SSL Issues

# Test webhook SSL
curl -X POST https://your-domain.com/webhook/telegram \
  -H "Content-Type: application/json" \
  -d '{"test": true}'

# Generate self-signed certificate (testing)
openssl req -newkey rsa:2048 -new -nodes -x509 -days 365 \
  -keyout key.pem -out cert.pem

# Use Let's Encrypt (production)
certbot certonly --standalone -d your-domain.com

Performance Issues

Slow Response Times

Check Resource Usage

# Check CPU and memory usage
top -p $(pgrep openclaw)
htop -p $(pgrep openclaw)

# Check memory usage specifically
ps aux | grep openclaw | grep -v grep

# Check disk I/O
iotop -p $(pgrep openclaw)

# Check network I/O
iftop -i eth0

Optimize Configuration

# Increase worker processes
openclaw config set gateway.workers 4

# Optimize database settings
openclaw config set gateway.database.poolSize 10

# Enable caching
openclaw config set gateway.cache.enabled true
openclaw config set gateway.cache.maxSize "100MB"

# Optimize message processing
openclaw config set gateway.batchSize 50
openclaw config set gateway.batchTimeout 1000

Memory Leaks

# Monitor memory over time
watch -n 5 'ps aux | grep openclaw'

# Generate memory dump
kill -USR1 $(pgrep openclaw)

# Check for memory leaks
openclaw gateway memory-profile

# Restart gateway if needed
openclaw gateway restart

High CPU Usage

Identify CPU-intensive operations

# Profile CPU usage
openclaw gateway profile --cpu

# Check which operations are slow
openclaw gateway logs --filter performance

# Optimize agent execution
openclaw config set agents.default.timeout 30000
openclaw config set agents.default.maxTokens 2048

Reduce CPU Usage

# Limit concurrent operations
openclaw config set gateway.maxConcurrent 10

# Enable rate limiting
openclaw config set security.rateLimit.enabled true

# Optimize polling intervals
openclaw config set channels.telegram.polling.interval 2000

Authentication Issues

Token Problems

Invalid or Expired Tokens

# Check token validity
openclaw gateway validate-token

# Generate new token
openclaw gateway generate-token

# Rotate all tokens
openclaw gateway rotate-tokens

# Check token expiration
openclaw gateway list-tokens --show-expiration

API Key Issues

# Test API keys
openclaw agent test --provider anthropic
openclaw agent test --provider openai

# Update API keys
export ANTHROPIC_API_KEY="new-key"
export OPENAI_API_KEY="new-key"

# Test with new keys
openclaw agent test

Permission Issues

File Permissions

# Check configuration file permissions
ls -la ~/.openclaw/openclaw.json

# Fix permissions
chmod 600 ~/.openclaw/openclaw.json
chmod 700 ~/.openclaw/

# Check log file permissions
ls -la ~/.openclaw/logs/

# Fix log permissions
chmod 640 ~/.openclaw/logs/*

macOS Permissions (iMessage)

# Check Full Disk Access
ls -la ~/Library/Messages/chat.db

# Reset permissions
sudo tccutil reset All com.apple.Messages

# Test imsg CLI
imsg version
imsg list-chats

# Re-grant permissions
# System Settings → Privacy & Security → Full Disk Access
# Add OpenClaw and imsg

Message Issues

Messages Not Sending

Check Channel Status

# Check all channels
openclaw channels status --all

# Check specific channel
openclaw channels status whatsapp

# Test channel connectivity
openclaw channels test whatsapp

# Check message queue
openclaw gateway queue --channel whatsapp

Common Send Failures

Rate limiting:

# Check rate limit status
openclaw channels status --rate-limit

# Wait and retry
openclaw message send --channel whatsapp --target "+1234567890" \
  --message "Test" --retry 3

Invalid recipient:

# Validate recipient
openclaw message validate --channel whatsapp --target "+1234567890"

# Check allowed recipients
openclaw config get channels.whatsapp.allowFrom

Network issues:

# Test network connectivity
ping web.whatsapp.com
curl -I https://api.telegram.org

# Check firewall
sudo ufw status

Messages Not Receiving

Check Receiver Configuration

# Check if receiver is running
openclaw gateway status

# Check receiver logs
openclaw gateway logs --filter receiver

# Test message reception
openclaw channels test-receive whatsapp

Webhook Issues

# Check webhook status
openclaw channels webhook status telegram

# Test webhook endpoint
curl -X POST http://localhost:8443/webhook/telegram \
  -H "Content-Type: application/json" \
  -d '{"update_id": 123, "message": {"text": "test"}}'

# Restart webhook
openclaw channels webhook restart telegram

Error Scenarios

Database Issues

Database Corruption

# Check database integrity
openclaw gateway db-check

# Repair database
openclaw gateway db-repair

# Rebuild database
openclaw gateway db-rebuild

# Backup before repair
openclaw gateway backup

Database Lock Issues

# Check for database locks
openclaw gateway db-status

# Clear locks
openclaw gateway db-clear-locks

# Restart database
openclaw gateway restart-db

Agent Issues

Agent Not Responding

# Check agent status
openclaw agent status

# Test agent connection
openclaw agent test

# Restart agent
openclaw agent restart

# Check agent logs
openclaw agent logs

Agent Execution Errors

# Check agent configuration
openclaw config get agents.default

# Test with simple prompt
openclaw agent test --prompt "Hello"

# Check model availability
openclaw agent test --model claude-3.5-sonnet

# Enable debug logging
openclaw config set logging.components.agent debug

Debug Tools

Debug Mode

# Start gateway in debug mode
openclaw gateway --debug

# Enable debug logging
openclaw config set logging.level debug

# Debug specific component
openclaw config set logging.components.whatsapp debug

# View debug logs
openclaw gateway logs --follow --level debug

Profiling

# CPU profiling
openclaw gateway profile --cpu --duration 30

# Memory profiling
openclaw gateway profile --memory --duration 30

# Network profiling
openclaw gateway profile --network --duration 30

# Generate flame graph
openclaw gateway profile --flamegraph

Health Monitoring

# Continuous health monitoring
openclaw gateway monitor --interval 60

# Health check with alerts
openclaw gateway monitor --alert-email admin@example.com

# Export health metrics
openclaw gateway metrics --format prometheus

Recovery Procedures

Complete Gateway Reset

# Backup current configuration
openclaw gateway backup

# Stop gateway
openclaw gateway stop

# Reset configuration (careful!)
openclaw config reset

# Reinitialize
openclaw onboard --force

# Restore from backup if needed
openclaw gateway restore backup-2024-01-15.json

Disaster Recovery

# Restore from backup
openclaw gateway restore --backup latest

# Verify restoration
openclaw gateway health

# Test all channels
openclaw channels test --all

# Send test message
openclaw message test

Getting Help

Support Resources

# Generate support bundle
openclaw support bundle --output support-bundle.tar.gz

# Check version
openclaw --version

# Check system info
openclaw system-info

# Export logs
openclaw logs export --last 24h --format json

Community Support

GitHub Issues: github.com/openclaw/openclaw/issues
Discord Community: discord.gg/openclaw
Documentation: docs.openclaw.dev

Bug Reports

When filing bug reports, include:

# System information
openclaw system-info

# Configuration (sanitized)
openclaw config show --sanitize

# Recent logs
openclaw logs export --last 1h

# Health status
openclaw gateway health --detailed

Troubleshooting Commands Reference

# Health and Status
openclaw gateway health
openclaw gateway status [--detailed]
openclaw channels status [--all]
openclaw agent status

# Testing
openclaw channels test <channel>
openclaw agent test [--model <model>]
openclaw message test

# Configuration
openclaw config validate [--section <section>]
openclaw config show [--section <section>]
openclaw config get <path>

# Logs and Debugging
openclaw gateway logs [--follow] [--level <level>]
openclaw channels logs <channel>
openclaw agent logs

# Recovery
openclaw gateway restart
openclaw gateway backup
openclaw gateway restore <backup>
openclaw config reset

💡 Developer Wellness

“Debugging is temporary. Inner peace is forever. Powered by Coffee & Stoic Philosophy.”

When you’re deep in troubleshooting mode, remember that technical challenges are temporary. Take a moment to breathe, step back, and approach problems with a calm, rational mindset.

For those moments when you need a philosophical perspective on debugging and life, consider exploring timeless wisdom at StoicLines.store — where ancient philosophy meets modern development challenges.

With this troubleshooting guide, you should be able to diagnose and resolve most OpenClaw Gateway issues. For additional help, reach out to the community! 🛠️