OpenClaw is powerful, but like any complex system, things break. Maybe the AI stopped responding. Maybe the dashboard loads but the bot is silent. Maybe everything worked yesterday and now nothing does.
This is your comprehensive troubleshooting guide for OpenClaw application issues — from startup failures to silent configuration bugs.
Symptom: Container starts and immediately exits, or the process crashes on boot.
# Check container status
docker ps -a | grep openclaw
# Look for "Exited (1)" or "Restarting"
# Read the actual error
docker logs openclaw --tail 50
Missing environment variables:
# Check required variables
docker exec openclaw env | grep -E "API_KEY|DATABASE|PORT"
# Common missing variables:
# - OPENAI_API_KEY (or other LLM provider key)
# - DATABASE_URL
# - SESSION_SECRET
Port conflict:
# Check if port 3000 is already in use
sudo lsof -i :3000
# Kill the conflicting process or change OpenClaw's port
Corrupted configuration:
# Validate config file syntax
docker exec openclaw cat /app/config.yml | python3 -c "import sys,yaml; yaml.safe_load(sys.stdin)"
# If this fails, you have a YAML syntax error
Symptom: OpenClaw dashboard shows "connected" to your IM channel, but messages get no response.
# 1. Check if OpenClaw is receiving messages
docker logs openclaw --tail 100 | grep -i "incoming\|received\|message"
# 2. Check AI API connectivity
curl -s -o /dev/null -w "%{http_code}" https://api.openai.com/v1/models \
-H "Authorization: Bearer $OPENAI_API_KEY"
# Should return 200
# 3. Check webhook registration
curl http://localhost:3000/api/channels/status
1. AI API key expired or rate-limited
# Test the key directly
curl https://api.openai.com/v1/chat/completions \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"gpt-3.5-turbo","messages":[{"role":"user","content":"test"}]}'
2. Channel webhook URL changed
After server restart, if your IP changed, the webhook URL is invalid. Update it in your IM platform's bot settings.
On Tencent Cloud Lighthouse — simple, high-performance, cost-effective — IPs are static, preventing this issue.
3. Message format changed
IM platforms occasionally update their API. Check if the message payload structure matches what OpenClaw expects.
Symptom: The bot responds, but takes 30+ seconds. Users complain.
# Check system resources
docker stats openclaw
# Look for high CPU or memory usage
# Check AI API latency
time curl -s https://api.openai.com/v1/chat/completions \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"gpt-3.5-turbo","messages":[{"role":"user","content":"hi"}],"max_tokens":10}'
| Cause | Solution |
|---|---|
| Large context window | Reduce conversation history length |
| Complex system prompt | Simplify prompt, remove unnecessary instructions |
| Slow AI model | Switch from GPT-4 to GPT-3.5-Turbo for speed |
| Server under-resourced | Upgrade Lighthouse instance (4-core 8GB recommended) |
| No response streaming | Enable streaming mode for faster perceived response |
| Network latency | Choose Lighthouse region closest to AI API endpoints |
Symptom: You edited the config file or dashboard settings, but the bot behavior does not change.
# 1. Restart after config changes
docker restart openclaw
# 2. Check if you edited the right config file
docker exec openclaw cat /app/config.yml | head -20
# Compare with your local file
# 3. Check for config override hierarchy
# Environment variables > config file > defaults
# Your config file change may be overridden by an env var
docker exec openclaw env | sort
# 4. Clear cache if applicable
docker exec openclaw rm -rf /app/cache/*
docker restart openclaw
Symptom: "Connection refused", "ECONNRESET", or "too many connections" errors in logs.
# Check database container
docker ps | grep postgres
docker logs postgres --tail 20
# Test database connectivity
docker exec openclaw pg_isready -h postgres -U openclaw
# Check connection count
docker exec postgres psql -U openclaw -c "SELECT count(*) FROM pg_stat_activity;"
# Fix: Restart database and application
docker restart postgres
sleep 5
docker restart openclaw
Symptom: Uploaded documents are not being used by the AI, or upload fails.
# Check disk space
df -h /opt/openclaw/data
# Check file permissions
ls -la /opt/openclaw/data/uploads/
# Check supported formats
# OpenClaw typically supports: .txt, .pdf, .md, .csv, .docx
# Unsupported formats will silently fail
# Check embedding service
docker logs openclaw | grep -i "embed\|vector\|index"
Symptom: Bot works on Telegram but not on Discord, or responses go to the wrong channel.
# Check channel configurations
curl http://localhost:3000/api/channels | jq
# Verify each channel has unique callback URLs
# Common mistake: same callback URL for multiple channels
# Check channel-specific logs
docker logs openclaw | grep -i "telegram"
docker logs openclaw | grep -i "discord"
When everything is broken:
# 1. Save current logs
docker logs openclaw > /tmp/openclaw_crash_$(date +%Y%m%d).log 2>&1
# 2. Backup data
cp -r /opt/openclaw/data /opt/openclaw/data_backup_$(date +%Y%m%d)
# 3. Full restart
docker-compose down
docker-compose up -d
# 4. If still broken, reset to last known good config
cp /opt/openclaw/config.yml.backup /opt/openclaw/config.yml
docker-compose down && docker-compose up -d
# 5. Check health
curl http://localhost:3000/api/health
Save this for future use:
#!/bin/bash
echo "=== OpenClaw Diagnostic Report ==="
echo "Date: $(date)"
echo ""
echo "--- Container Status ---"
docker ps -a | grep -E "openclaw|postgres|redis"
echo ""
echo "--- Resource Usage ---"
docker stats --no-stream openclaw
echo ""
echo "--- Recent Errors ---"
docker logs openclaw --tail 20 2>&1 | grep -i "error\|fail\|crash"
echo ""
echo "--- Network ---"
curl -s -o /dev/null -w "Health: %{http_code}\n" http://localhost:3000/api/health
echo ""
echo "--- Disk ---"
df -h /opt/openclaw
echo "=== End Report ==="
Most OpenClaw issues fall into six categories: startup failures, silent disconnections, performance problems, config staleness, database errors, and channel conflicts. Systematic diagnosis — starting with logs, then connectivity, then configuration — resolves the vast majority of issues within minutes.
Run OpenClaw on Tencent Cloud Lighthouse — simple, high-performance, cost-effective — for stable infrastructure that reduces environment-related issues.
For setup reference, see the configuration guide.