claude-home/productivity/openclaw/troubleshooting.md

OpenClaw Troubleshooting Guide

Gateway Startup Issues

Container Won't Start

Symptoms: docker compose up fails immediately

Diagnosis:

docker compose logs openclaw-gateway

Common Causes:

1. Missing environment variables:

   • Check .env file exists and contains required keys
   • Verify MINIMAX_API_KEY and DISCORD_BOT_TOKEN are set
   • Solution: Copy .env.example to .env and populate

2. Port conflict (18789 already in use):

   • Check: netstat -tulpn | grep 18789
   • Solution: Stop conflicting service or change port in docker-compose.yml

3. Invalid openclaw.json syntax:

   • JSON5 allows comments and trailing commas
   • Validate: docker compose config (checks interpolation)
   • Solution: Fix syntax errors, remove invalid characters

Container Starts but Exits Immediately

Symptoms: Container runs briefly then stops

Diagnosis:

docker compose logs --tail=50 openclaw-gateway
docker compose ps

Common Causes:

1. Invalid MiniMax API key:

   • Error: "Authentication failed" or "Invalid API key"
   • Solution: Verify key at https://platform.minimax.io/
   • Check key format: Should start with sk-

2. Docker socket permission denied:

   • Error: "Cannot connect to Docker daemon"
   • Check: ls -l /var/run/docker.sock
   • Solution: Already mounted in compose file; check LXC nesting enabled

3. Configuration file not found:

   • Error: "Cannot read openclaw.json"
   • Check: ls -la /opt/openclaw/openclaw.json
   • Solution: Create file from plan template

Discord Integration Issues

Bot Not Connecting to Discord

Symptoms: Bot shows offline in Discord server

Diagnosis:

docker compose logs openclaw-gateway | grep -i discord
docker compose exec openclaw-gateway openclaw channels status --probe

Common Causes:

1. Invalid bot token:

   • Error: "Incorrect login credentials"
   • Solution: Regenerate token in Discord Developer Portal
   • Update .env file and restart: docker compose restart

2. Missing Message Content Intent:

   • Error: "Used disallowed intents"
   • Solution:
     1. Go to Discord Developer Portal
     2. Bot → Privileged Gateway Intents
     3. Enable "Message Content Intent"
     4. Restart OpenClaw gateway

3. Bot not invited to server:

   • No error, just offline status
   • Solution: Generate invite URL from OAuth2 → URL Generator
   • Use scopes: bot + applications.commands
   • Invite with required permissions

Bot Online but Not Responding to DMs

Symptoms: Bot shows online but doesn't reply to messages

Diagnosis:

# Check channel configuration
docker compose exec openclaw-gateway openclaw channels status discord

# Check recent logs
docker compose logs --tail=100 openclaw-gateway | grep -E "(DM|discord)"

Common Causes:

1. Pairing required but not approved:

   • Bot sends pairing code on first message
   • Code expires after 1 hour
   • Solution: Approve pairing:

     docker compose exec openclaw-gateway openclaw pairing list discord
     docker compose exec openclaw-gateway openclaw pairing approve discord <code>
     

2. Policy set to disabled:

   • Check openclaw.json → channels.discord.dm.policy
   • Should be "pairing" or "open"
   • Solution: Change policy and restart

3. Message Content Intent disabled (again):

   • Bot can't read message text
   • Solution: See "Missing Message Content Intent" above

Pairing Code Not Working

Symptoms: User receives pairing code but approval command fails

Diagnosis:

# List all pending pairing requests
docker compose exec openclaw-gateway openclaw pairing list discord

# Check logs for pairing errors
docker compose logs openclaw-gateway | grep -i pairing

Solutions:

1. Code expired (>1 hour old):

   • Regenerate: Send new DM to bot
   • Approve new code within 1 hour

2. Wrong pairing code format:

   • Code format: Usually 6-digit alphanumeric
   • Case-sensitive: Use exact code from Discord message

3. Multiple pending codes:

   • List all codes: openclaw pairing list discord
   • Approve latest code (most recent timestamp)

MiniMax API Issues

API Authentication Errors

Symptoms: "Authentication failed" or "Invalid API key" in logs

Diagnosis:

# Check API key is set
docker compose exec openclaw-gateway env | grep MINIMAX

# Test API key directly
curl -X POST https://api.minimax.io/anthropic/v1/messages \
  -H "Authorization: Bearer $MINIMAX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"MiniMax-M2.1","max_tokens":10,"messages":[{"role":"user","content":"test"}]}'

Solutions:

1. Key not set or incorrect:

   • Verify .env file contains: MINIMAX_API_KEY=sk-...
   • Restart after changes: docker compose restart

2. Key revoked or expired:

   • Log in to https://platform.minimax.io/
   • Check API key status
   • Generate new key if needed

3. Interpolation not working:

   • Check openclaw.json uses: "apiKey": "${MINIMAX_API_KEY}"
   • Verify .env file is in same directory as docker-compose.yml

Rate Limiting or Quota Errors

Symptoms: "Rate limit exceeded" or "Insufficient quota"

Diagnosis:

# Check recent API errors
docker compose logs openclaw-gateway | grep -i "rate\|quota"

Solutions:

1. Rate limit (temporary):

   • Wait 60 seconds and retry
   • Reduce message frequency
   • Consider upgrading MiniMax plan

2. Quota exceeded (billing):

   • Check account balance at https://platform.minimax.io/
   • Add credits or upgrade plan
   • Set usage alerts to prevent future issues

3. Context window exceeded:

   • Error: "Context length too long"
   • Reduce historyLimit in openclaw.json (default 20)
   • Current limit: 200,000 tokens (very high, unlikely to hit)

Performance Issues

High Memory Usage

Symptoms: Container using >2GB RAM, system sluggish

Diagnosis:

# Check container stats
docker stats openclaw

# Check for stuck browser processes
docker compose exec openclaw-gateway ps aux | grep -E "(chrome|firefox|playwright)"

Solutions:

1. Browser automation processes not cleaned up:

   • Restart gateway: docker compose restart
   • Consider disabling browser skills if not needed

2. Large workspace files:

   • Check workspace size: du -sh /opt/openclaw/workspace
   • Clean old files: Review and remove unnecessary workspace data

3. Memory leak (rare):

   • Update to latest version: docker compose pull && docker compose up -d
   • Report issue to OpenClaw GitHub

Slow Response Times

Symptoms: Bot takes >30 seconds to respond

Diagnosis:

# Check API latency
docker compose logs openclaw-gateway | grep -i "duration\|latency"

# Check network connectivity
docker compose exec openclaw-gateway ping -c 3 api.minimax.io

Solutions:

1. MiniMax API slow:

   • Switch to lightning model: minimax/MiniMax-M2.1-lightning
   • Edit openclaw.json → agents.defaults.model.primary
   • Restart gateway

2. Large context window:

   • Reduce historyLimit in openclaw.json (e.g., 10 instead of 20)
   • Shorter history = faster responses

3. Network latency:

   • Check internet connection on LXC: ping -c 5 8.8.8.8
   • Verify DNS resolution: nslookup api.minimax.io

High CPU Usage

Symptoms: Constant high CPU (>50%) even when idle

Diagnosis:

# Check process CPU usage
docker compose exec openclaw-gateway top -b -n 1

# Check for infinite loops in logs
docker compose logs --tail=200 openclaw-gateway

Solutions:

1. Stuck skill execution:

   • Identify stuck process in logs
   • Restart gateway: docker compose restart

2. Discord WebSocket reconnect loop:

   • Error: "WebSocket closed, reconnecting..."
   • Check Discord API status: https://discordstatus.com/
   • Verify bot token is valid

3. Log spam:

   • Reduce log level: Add LOG_LEVEL=warn to .env
   • Restart gateway

Configuration Issues

Changes Not Taking Effect

Symptoms: Modified openclaw.json but behavior unchanged

Solution:

# Restart gateway to reload configuration
docker compose restart openclaw-gateway

# Verify configuration loaded
docker compose logs openclaw-gateway | grep "Configuration loaded"

# Check for configuration errors
docker compose logs openclaw-gateway | grep -i "config\|error"

Environment Variables Not Interpolating

Symptoms: Literal ${VAR_NAME} in logs instead of values

Diagnosis:

# Check environment variables are set in container
docker compose exec openclaw-gateway env | grep -E "(MINIMAX|DISCORD)"

Solutions:

1. Docker Compose not loading .env:

   • Verify .env file is in same directory as docker-compose.yml
   • Check file permissions: ls -la .env (should be readable)

2. Variable name mismatch:

   • Ensure .env uses exact name from openclaw.json
   • Case-sensitive: MINIMAX_API_KEY not minimax_api_key

3. Quoting issues:

   • Don't quote values in .env: KEY=value not KEY="value"
   • OpenClaw handles interpolation, Docker doesn't need quotes

Emergency Recovery

Complete Service Reset

If all else fails, nuclear option:

# Stop and remove all containers
docker compose down -v

# Clear workspace (CAUTION: deletes all agent memory/files)
rm -rf workspace/*
rm -rf logs/*

# Reset configuration to defaults
cp openclaw.json openclaw.json.backup
# Re-create openclaw.json from plan template

# Recreate from scratch
docker compose up -d

# Watch logs for errors
docker compose logs -f

LXC Container Issues

If Docker itself is broken:

# From Proxmox host
ssh root@10.10.0.11

# Restart LXC
pct restart 224

# If restart fails, stop and start
pct stop 224
pct start 224

# Check LXC status
pct status 224

# Access LXC console directly
pct enter 224

Rollback to Previous Version

If update caused issues:

# Pin to specific working version
# Edit docker-compose.yml, change:
# image: openclaw/gateway:latest
# To:
# image: openclaw/gateway:2026.1.24-1

# Recreate container
docker compose down
docker compose up -d

Diagnostic Commands Reference

# Full system health check
docker compose exec openclaw-gateway openclaw doctor

# Channel status (Discord, etc.)
docker compose exec openclaw-gateway openclaw channels status --probe

# Model configuration
docker compose exec openclaw-gateway openclaw models list
docker compose exec openclaw-gateway openclaw models get minimax/MiniMax-M2.1

# Pairing management
docker compose exec openclaw-gateway openclaw pairing list discord
docker compose exec openclaw-gateway openclaw pairing approve discord <code>
docker compose exec openclaw-gateway openclaw pairing revoke discord <user_id>

# Container health
docker compose ps
docker compose logs --tail=50 openclaw-gateway
docker stats openclaw

# Network connectivity
docker compose exec openclaw-gateway ping -c 3 api.minimax.io
docker compose exec openclaw-gateway curl -I https://discord.com/api/v10/gateway

# File system check
docker compose exec openclaw-gateway df -h
docker compose exec openclaw-gateway du -sh /workspace/*

Getting Help

Official Resources:

• Documentation: https://docs.openclaw.ai/
• GitHub Issues: https://github.com/openclaw/openclaw/issues
• Community Discord: [Check OpenClaw website for invite]

Homelab-Specific:

• Check MemoryGraph: python ~/.claude/skills/memorygraph/client.py recall "openclaw"
• Review CONTEXT.md: /mnt/NV2/Development/claude-home/productivity/openclaw/CONTEXT.md
• Infrastructure inventory: /mnt/NV2/Development/claude-home/server-configs/hosts.yml