Clawd BotandClaude Opus 4.6
ca9b510922
- Reset master to upstream/main (16,697 commits) - Overlay 2,271 local-only files (skills, tools, workspace, configs, apps) - Restore IDENTITY.md and USER.md templates - Build verified, gateway running, Discord working Co-Authored-By: Claude Opus 4.6 <[email protected]>
588 lines
11 KiB
Markdown
588 lines
11 KiB
Markdown
# 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`
|