openclaw/docs/troubleshooting/quick-fixes.md

OpenClaw Quick Troubleshooting Fixes

Quick reference for common OpenClaw issues and their immediate fixes.

Gateway Issues

Gateway Stuck/Unresponsive

One-liner fix:

pkill -9 -f "openclaw.*gateway" && rm -f /tmp/openclaw-$UID/gateway.*.lock && sudo systemctl restart openclaw-gateway

Verify:

openclaw status && ss -ltnp | grep 18789

Orphaned Gateway Processes

Find them:

ps aux | grep "openclaw.*gateway"

Kill them:

kill -9 <PID>   # Replace <PID> with actual process ID

Or kill all:

pkill -9 -f "openclaw.*gateway"

Gateway Won't Start (Port Already in Use)

# Find what's using port 18789
ss -ltnp | grep 18789

# Force-kill and restart
pkill -9 -f "openclaw.*gateway"
openclaw gateway run --force

Agent Issues

"1 bootstrapping" Status

Quick fix:

find ~/.openclaw/agents -name "BOOTSTRAP.md" -delete

Or more careful:

find ~/.openclaw/agents -name "BOOTSTRAP.md"  # Review first
mv ~/.openclaw/agents/main/BOOTSTRAP.md ~/.openclaw/agents/main/BOOTSTRAP.md.bak

Agent Not Responding

Check agent status:

openclaw status | grep -A5 "Agents:"

Restart gateway:

sudo systemctl restart openclaw-gateway

Check agent workspace:

ls -la ~/.openclaw/agents/*/
ls -la ~/.openclaw/workspace/

Session Issues

Session Timeout Loop

Identify problematic session:

journalctl --user -u openclaw-gateway -n 100 | grep "timeout"

Remove session (replace SESSION_ID):

SESSION_ID="<session-id-from-logs>"
cd ~/.openclaw/agents/sonnet/sessions
mv ${SESSION_ID}.jsonl ${SESSION_ID}.jsonl.bak
rm -f ${SESSION_ID}.jsonl.lock
sudo systemctl restart openclaw-gateway

Session Too Large

Find large sessions:

find ~/.openclaw/agents -name "*.jsonl" -size +10M -exec ls -lh {} \;

Archive old sessions:

cd ~/.openclaw/agents/main/sessions
mkdir -p archive
mv *.jsonl.bak archive/

Sessions Not Saving

Check permissions:

ls -la ~/.openclaw/agents/*/sessions/
chmod 700 ~/.openclaw/agents/*/sessions
chmod 600 ~/.openclaw/agents/*/sessions/sessions.json

Verify session scope:

openclaw config get session.scope

Installation Issues

Dual Installation (User vs System)

Detect conflict:

which openclaw
/usr/bin/openclaw --version
~/.local/bin/openclaw --version 2>/dev/null || echo "No user install"
systemctl --user cat openclaw-gateway | grep ExecStart

Remove user installation:

rm ~/.local/bin/openclaw
rm -rf ~/.local/lib/node_modules/openclaw

Update system installation:

sudo npm install -g openclaw@latest
which openclaw
openclaw --version

Version Mismatch

Check all versions:

openclaw --version                          # CLI version
openclaw gateway version                   # Gateway version
systemctl --user cat openclaw-gateway      # Service ExecStart path
$(systemctl --user cat openclaw-gateway | grep ExecStart | awk '{print $2}') --version

Force update:

sudo npm install -g openclaw@latest --force

Configuration Issues

Config File Not Found

Check config location:

echo $OPENCLAW_CONFIG_PATH
ls -la ~/.openclaw/openclaw.json

Recreate config:

openclaw config wizard

Config Syntax Error

Validate config:

openclaw config validate

Check JSON syntax:

cat ~/.openclaw/openclaw.json | jq '.'

Common issues:

• Trailing commas in arrays
• Missing quotes around strings
• Invalid escape sequences

Config Not Taking Effect

Restart gateway after changes:

openclaw config set key value
sudo systemctl restart openclaw-gateway
openclaw status

Verify config is loaded:

openclaw config show | grep "key"

Channel Issues

Channel Disconnected

Check channel status:

openclaw channels status --probe

Common fixes:

# Discord: Re-add bot token
openclaw config set discord.token "YOUR_TOKEN"

# Telegram: Re-add bot token
openclaw config set telegram.token "YOUR_TOKEN"

# Slack: Re-authenticate
openclaw login slack

# Restart to reconnect
sudo systemctl restart openclaw-gateway

Channel Configuration Missing

List configured channels:

openclaw config show | grep -A10 "channels:"

Add channel:

openclaw channels add <channel-type>

Logging & Debugging

View Recent Logs

# Last 50 lines
journalctl --user -u openclaw-gateway -n 50

# Follow live
journalctl --user -u openclaw-gateway -f

# Last 5 minutes
journalctl --user -u openclaw-gateway --since "5 minutes ago"

# Filter for errors
journalctl --user -u openclaw-gateway -p err

Enable Debug Logging

openclaw config set logging.level debug
openclaw config set logging.gatewayWsLog full
sudo systemctl restart openclaw-gateway

Disable Debug Logging

openclaw config set logging.level info
openclaw config set logging.gatewayWsLog auto
sudo systemctl restart openclaw-gateway

Lock File Issues

Gateway Lock Error

Remove lock manually:

ls -la /tmp/openclaw-$UID/
rm /tmp/openclaw-$UID/gateway.*.lock

Check if process is actually running:

cat /tmp/openclaw-$UID/gateway.*.lock  # Note the PID
ps -p <PID>                             # Check if alive

Stale Lock After Crash

# Clean all locks
rm -f /tmp/openclaw-$UID/*.lock

# Restart
openclaw gateway run

Network Issues

Gateway Not Reachable Remotely

Check binding mode:

openclaw config get gateway.bind
openclaw config get gateway.mode

Fix for LAN access:

openclaw config set gateway.bind lan
sudo systemctl restart openclaw-gateway

Fix for Tailscale access:

openclaw config set gateway.mode remote
openclaw config set gateway.tailscale.mode serve
sudo systemctl restart openclaw-gateway

Test Local Connection

# Health check
curl http://localhost:18789/health

# Check port
ss -ltnp | grep 18789

# Test WebSocket (if websocat installed)
echo '{"method":"health","params":{}}' | websocat ws://localhost:18789

Emergency Commands

Nuclear Restart (Fixes Most Issues)

# Kill everything
pkill -9 -f openclaw

# Clean locks
rm -f /tmp/openclaw-$UID/*.lock

# Restart service
sudo systemctl restart openclaw-gateway

# Wait 5 seconds
sleep 5

# Verify
openclaw status

Full Reset (⚠️ Deletes All Sessions)

# Backup first!
cp -r ~/.openclaw ~/.openclaw.backup.$(date +%Y%m%d-%H%M%S)

# Stop everything
sudo systemctl stop openclaw-gateway
pkill -9 -f openclaw

# Remove state
rm -rf ~/.openclaw

# Reinstall
npm install -g openclaw@latest

# Reconfigure
openclaw config wizard
openclaw gateway install
openclaw gateway start

Restore from Backup

# Stop gateway
sudo systemctl stop openclaw-gateway

# Restore (replace timestamp)
cp -r ~/.openclaw.backup.20260210-083000/* ~/.openclaw/

# Fix permissions
chmod 600 ~/.openclaw/openclaw.json
chmod 700 ~/.openclaw/agents/*/sessions

# Restart
sudo systemctl start openclaw-gateway

Diagnostic One-Liners

# Quick health check
openclaw status && journalctl --user -u openclaw-gateway -n 20

# Full diagnostic
openclaw status --deep && openclaw doctor

# Process check
ps aux | grep openclaw && ss -ltnp | grep 18789

# Config check
openclaw config validate && openclaw config show

# Session count
ls ~/.openclaw/agents/*/sessions/*.jsonl 2>/dev/null | wc -l

# Large sessions
find ~/.openclaw/agents -name "*.jsonl" -size +5M -exec ls -lh {} \;

# Recent errors
journalctl --user -u openclaw-gateway --since "1 hour ago" -p err

# Check versions
openclaw --version && node --version && npm --version

Common Error Messages

"Gateway is already running"

pkill -9 -f "openclaw.*gateway"
rm -f /tmp/openclaw-$UID/gateway.*.lock
openclaw gateway run

"embedded run timeout"

# Find session ID in error message, then:
SESSION_ID="<session-id>"
rm ~/.openclaw/agents/*/sessions/${SESSION_ID}.jsonl*
sudo systemctl restart openclaw-gateway

"Cannot find module"

# Reinstall dependencies
cd $(npm root -g)/openclaw
npm install --omit=dev

# Or reinstall openclaw
sudo npm install -g openclaw@latest --force

"Permission denied"

# Fix ownership (if running as 'alex')
sudo chown -R alex:alex ~/.openclaw
chmod 700 ~/.openclaw
chmod 600 ~/.openclaw/openclaw.json

"EADDRINUSE"

# Port already in use
ss -ltnp | grep 18789
pkill -9 -f "openclaw.*gateway"
openclaw gateway run --force

Prevention

Regular Health Checks

# Add to crontab: check status every hour
0 * * * * openclaw status > /tmp/openclaw-health.log 2>&1

Automatic Cleanup

# Clean old session backups (30+ days)
find ~/.openclaw/agents -name "*.jsonl.bak" -mtime +30 -delete

# Archive large sessions
find ~/.openclaw/agents -name "*.jsonl" -size +20M -exec mv {} {}.archived \;

Log Rotation

# systemd handles this automatically, but verify:
journalctl --user -u openclaw-gateway --vacuum-time=7d

When All Else Fails

1. Capture diagnostic info:

   {
     echo "=== Status ==="
     openclaw status
     echo -e "\n=== Processes ==="
     ps aux | grep openclaw
     echo -e "\n=== Locks ==="
     ls -la /tmp/openclaw-$UID/
     echo -e "\n=== Recent Logs ==="
     journalctl --user -u openclaw-gateway -n 50
     echo -e "\n=== Config ==="
     openclaw config show
   } > /tmp/openclaw-diagnostic.txt
   

2. Share diagnostic file with support or create an issue

3. Try nuclear restart (see above)

4. If still broken, restore from backup and report issue

Quick Reference

Issue	Quick Fix
Gateway stuck	pkill -9 -f openclaw && systemctl restart openclaw-gateway
Bootstrapping	rm ~/.openclaw/agents/*/BOOTSTRAP.md
Session timeout	rm ~/.openclaw/agents/*/sessions/<id>.jsonl*
Dual install	rm ~/.local/bin/openclaw && sudo npm i -g openclaw@latest
Config not loading	systemctl restart openclaw-gateway
Channel disconnected	openclaw channels status --probe
Lock file	rm /tmp/openclaw-$UID/gateway.*.lock
Port in use	openclaw gateway run --force

Getting Help

• Documentation: https://docs.openclaw.ai
• Issues: https://github.com/openclaw/openclaw/issues
• Logs: journalctl --user -u openclaw-gateway -f
• Config: openclaw config show
• Status: openclaw status --deep