claude-home/productivity/openclaw/troubleshooting.md

# OpenClaw Troubleshooting Guide

## Gateway Startup Issues

### Container Won't Start
**Symptoms:** `docker compose up` fails immediately

**Diagnosis:**
```bash
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:**
```bash
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:**
```bash
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:**
```bash
# 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:
     ```bash
     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:**
```bash
# 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:**
```bash
# 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:**
```bash
# 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:**
```bash
# 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:**
```bash
# 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:**
```bash
# 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:**
```bash
# 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:**
```bash
# 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

## Skill and Package Management Issues

### Skill Installation Fails - Missing Binary Dependencies
**Symptoms:** Skill reports "command not found" or "binary not available on PATH"

**Diagnosis:**
```bash
# Check if binary is installed
which <binary-name>

# List Homebrew packages
ssh root@10.10.0.224 "brew-as-openclaw list"
```

**Solutions:**

1. **Install via Homebrew (recommended for skills):**
   ```bash
   # From root shell
   ssh root@10.10.0.224
   brew-as-openclaw install <package>

   # Or as openclaw user
   ssh openclaw@10.10.0.224
   brew install <package>
   ```

2. **Install via apt (for system tools):**
   ```bash
   ssh root@10.10.0.224
   apt-get update
   apt-get install <package>
   ```

**Common Skill Dependencies:**
- `jq` - JSON processing → `brew-as-openclaw install jq`
- `ffmpeg` - Media processing → `brew-as-openclaw install ffmpeg`
- `imagemagick` - Image manipulation → `brew-as-openclaw install imagemagick`
- `git` - Already installed via apt
- `curl` - Already installed via apt

### Homebrew Command Not Found
**Symptoms:** `brew: command not found` when running as openclaw user

**Diagnosis:**
```bash
# Check if Homebrew is installed
ssh root@10.10.0.224 "ls -la /home/linuxbrew/.linuxbrew/bin/brew"

# Check PATH configuration
ssh openclaw@10.10.0.224 "cat ~/.bashrc | grep brew"
```

**Solutions:**

1. **Use helper script from root:**
   ```bash
   ssh root@10.10.0.224 "brew-as-openclaw --version"
   ```

2. **Fix PATH for openclaw user:**
   ```bash
   ssh openclaw@10.10.0.224
   echo 'eval "$(/home/linuxbrew/.linuxbrew/bin/brew shellenv bash)"' >> ~/.bashrc
   source ~/.bashrc
   brew --version
   ```

3. **Manual shellenv in commands:**
   ```bash
   ssh openclaw@10.10.0.224 'eval "$(/home/linuxbrew/.linuxbrew/bin/brew shellenv bash)" && brew list'
   ```

### ClawHub CLI Not Found
**Symptoms:** `clawhub: command not found` when trying to install skills

**Diagnosis:**
```bash
# Check if ClawHub CLI is installed
ssh openclaw@10.10.0.224 "which clawhub"

# Check npm global packages
ssh openclaw@10.10.0.224 "npm list -g --depth=0"
```

**Solutions:**

1. **Install ClawHub CLI:**
   ```bash
   ssh openclaw@10.10.0.224
   npm install -g clawhub

   # Or install locally in OpenClaw workspace
   cd /opt/openclaw/workspace
   npm install clawhub
   npx clawhub --version
   ```

2. **Use alternative skill installation:**
   ```bash
   # Manual skill installation
   cd /opt/openclaw/workspace
   mkdir -p skills/<skill-name>
   nano skills/<skill-name>/SKILL.md
   ```

### Skill Permission Errors
**Symptoms:** "Permission denied" when installing or running skills

**Diagnosis:**
```bash
# Check workspace ownership
ssh root@10.10.0.224 "ls -la /opt/openclaw/workspace"

# Check skill directory permissions
ssh root@10.10.0.224 "ls -la /opt/openclaw/workspace/skills"
```

**Solutions:**

1. **Fix ownership (workspace should be accessible to Docker node user, UID 1000):**
   ```bash
   ssh root@10.10.0.224
   chown -R 1000:1000 /opt/openclaw/workspace
   ```

2. **Install skills as openclaw user (UID 1000):**
   ```bash
   ssh openclaw@10.10.0.224
   cd /opt/openclaw/workspace
   clawhub install <skill>
   ```

### Homebrew Installation Issues
**Symptoms:** Homebrew won't install or shows permission errors

**Diagnosis:**
```bash
# Check Homebrew directory ownership
ssh root@10.10.0.224 "ls -la /home/linuxbrew/.linuxbrew"

# Check openclaw user exists
ssh root@10.10.0.224 "id openclaw"
```

**Solutions:**

1. **Fix directory ownership:**
   ```bash
   ssh root@10.10.0.224
   chown -R openclaw:openclaw /home/linuxbrew
   ```

2. **Reinstall Homebrew:**
   ```bash
   ssh root@10.10.0.224
   rm -rf /home/linuxbrew/.linuxbrew
   su - openclaw -c 'NONINTERACTIVE=1 /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"'
   ```

3. **Install system dependencies:**
   ```bash
   ssh root@10.10.0.224
   apt-get update
   apt-get install -y build-essential procps curl file git
   ```

## Emergency Recovery

### Complete Service Reset
If all else fails, nuclear option:

```bash
# 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:

```bash
# 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:

```bash
# 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

```bash
# 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`