# OpenClaw Quick Troubleshooting Fixes

Quick reference for common OpenClaw issues and their immediate fixes.

## Gateway Issues

### Gateway Stuck/Unresponsive

**One-liner fix:**

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

**Verify:**

```bash
openclaw status && ss -ltnp | grep 18789
```

### Orphaned Gateway Processes

**Find them:**

```bash
ps aux | grep "openclaw.*gateway"
```

**Kill them:**

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

**Or kill all:**

```bash
pkill -9 -f "openclaw.*gateway"
```

### Gateway Won't Start (Port Already in Use)

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

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

**Or more careful:**

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

```bash
openclaw status | grep -A5 "Agents:"
```

**Restart gateway:**

```bash
sudo systemctl restart openclaw-gateway
```

**Check agent workspace:**

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

## Session Issues

### Session Timeout Loop

**Identify problematic session:**

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

**Remove session (replace SESSION_ID):**

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

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

**Archive old sessions:**

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

### Sessions Not Saving

**Check permissions:**

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

**Verify session scope:**

```bash
openclaw config get session.scope
```

## Installation Issues

### Dual Installation (User vs System)

**Detect conflict:**

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

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

**Update system installation:**

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

### Version Mismatch

**Check all versions:**

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

```bash
sudo npm install -g openclaw@latest --force
```

## Configuration Issues

### Config File Not Found

**Check config location:**

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

**Recreate config:**

```bash
openclaw config wizard
```

### Config Syntax Error

**Validate config:**

```bash
openclaw config validate
```

**Check JSON syntax:**

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

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

**Verify config is loaded:**

```bash
openclaw config show | grep "key"
```

## Channel Issues

### Channel Disconnected

**Check channel status:**

```bash
openclaw channels status --probe
```

**Common fixes:**

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

```bash
openclaw config show | grep -A10 "channels:"
```

**Add channel:**

```bash
openclaw channels add <channel-type>
```

## Logging & Debugging

### View Recent Logs

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

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

### Disable Debug Logging

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

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

**Check if process is actually running:**

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

### Stale Lock After Crash

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

# Restart
openclaw gateway run
```

## Network Issues

### Gateway Not Reachable Remotely

**Check binding mode:**

```bash
openclaw config get gateway.bind
openclaw config get gateway.mode
```

**Fix for LAN access:**

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

**Fix for Tailscale access:**

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

### Test Local Connection

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

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

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

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

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

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

### "embedded run timeout"

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

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

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

### "Permission denied"

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

### "EADDRINUSE"

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

## Prevention

### Regular Health Checks

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

### Automatic Cleanup

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

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

## When All Else Fails

1. **Capture diagnostic info:**

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