Cal Corum 425bb1abd8 Update OpenClaw documentation with deployment details

Update CONTEXT with npm installation model, Homebrew wrapper setup,
systemd service config, and MiniMax integration. Expand troubleshooting
with gateway, Docker, and Homebrew error scenarios.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

2026-02-07 22:21:05 -06:00

15 KiB

Raw Blame History

OpenClaw Troubleshooting Guide

Gateway Startup Issues

Container Won't Start

Symptoms: docker compose up fails immediately

Diagnosis:

docker compose logs openclaw-gateway

Common Causes:

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
Port conflict (18789 already in use):
- Check: netstat -tulpn | grep 18789
- Solution: Stop conflicting service or change port in docker-compose.yml
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:

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-
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
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:

Invalid bot token:
- Error: "Incorrect login credentials"
- Solution: Regenerate token in Discord Developer Portal
- Update .env file and restart: docker compose restart
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
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:

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>

Policy set to disabled:
- Check openclaw.json → channels.discord.dm.policy
- Should be "pairing" or "open"
- Solution: Change policy and restart
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:

Code expired (>1 hour old):
- Regenerate: Send new DM to bot
- Approve new code within 1 hour
Wrong pairing code format:
- Code format: Usually 6-digit alphanumeric
- Case-sensitive: Use exact code from Discord message
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:

Key not set or incorrect:
- Verify .env file contains: MINIMAX_API_KEY=sk-...
- Restart after changes: docker compose restart
Key revoked or expired:
- Log in to https://platform.minimax.io/
- Check API key status
- Generate new key if needed
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:

Rate limit (temporary):
- Wait 60 seconds and retry
- Reduce message frequency
- Consider upgrading MiniMax plan
Quota exceeded (billing):
- Check account balance at https://platform.minimax.io/
- Add credits or upgrade plan
- Set usage alerts to prevent future issues
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:

Browser automation processes not cleaned up:
- Restart gateway: docker compose restart
- Consider disabling browser skills if not needed
Large workspace files:
- Check workspace size: du -sh /opt/openclaw/workspace
- Clean old files: Review and remove unnecessary workspace data
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:

MiniMax API slow:
- Switch to lightning model: minimax/MiniMax-M2.1-lightning
- Edit openclaw.json → agents.defaults.model.primary
- Restart gateway
Large context window:
- Reduce historyLimit in openclaw.json (e.g., 10 instead of 20)
- Shorter history = faster responses
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:

Stuck skill execution:
- Identify stuck process in logs
- Restart gateway: docker compose restart
Discord WebSocket reconnect loop:
- Error: "WebSocket closed, reconnecting..."
- Check Discord API status: https://discordstatus.com/
- Verify bot token is valid
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:

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)
Variable name mismatch:
- Ensure .env uses exact name from openclaw.json
- Case-sensitive: MINIMAX_API_KEY not minimax_api_key
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:

# Check if binary is installed
which <binary-name>

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

Solutions:

Install via Homebrew (recommended for skills):

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

Install via apt (for system tools):

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:

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

Use helper script from root:

ssh root@10.10.0.224 "brew-as-openclaw --version"

Fix PATH for openclaw user:

ssh openclaw@10.10.0.224
echo 'eval "$(/home/linuxbrew/.linuxbrew/bin/brew shellenv bash)"' >> ~/.bashrc
source ~/.bashrc
brew --version

Manual shellenv in commands:

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:

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

Install ClawHub CLI:

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

Use alternative skill installation:

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

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

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

Install skills as openclaw user (UID 1000):

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:

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

Fix directory ownership:

ssh root@10.10.0.224
chown -R openclaw:openclaw /home/linuxbrew

Reinstall Homebrew:

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)"'

Install system dependencies:

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:

# 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

15 KiB Raw Blame History

OpenClaw Troubleshooting Guide

Gateway Startup Issues

Container Won't Start

Container Starts but Exits Immediately

Discord Integration Issues

Bot Not Connecting to Discord

Bot Online but Not Responding to DMs

Pairing Code Not Working

MiniMax API Issues

API Authentication Errors

Rate Limiting or Quota Errors

Performance Issues

High Memory Usage

Slow Response Times

High CPU Usage

Configuration Issues

Changes Not Taking Effect

Environment Variables Not Interpolating

Skill and Package Management Issues

Skill Installation Fails - Missing Binary Dependencies

Homebrew Command Not Found

ClawHub CLI Not Found

Skill Permission Errors

Homebrew Installation Issues

Emergency Recovery

Complete Service Reset

LXC Container Issues

Rollback to Previous Version

Diagnostic Commands Reference

Getting Help

15 KiB

Raw Blame History