You notice your Telegram bot went silent. You check — the OpenClaw gateway is down again. You restart it. It comes back up. Forty minutes later, down again. Sound familiar? This is a crash loop, and it has specific causes. Here's how to diagnose and fix each one.
OpenClaw bots crash in two different ways, and they have different causes:
| Symptom | Likely cause | How to tell |
|---|---|---|
| Bot stops responding but process still running | Telegram connection dropped / token invalid | openclaw status shows "running" but bot doesn't reply |
| Gateway process exits and restarts | Unhandled exception, config error, or resource exhaustion | Logs show repeated "starting" messages |
| Gateway exits and doesn't restart | Config file corrupted, missing env var, port conflict | Service stays stopped until you manually restart |
Run this first to see what's actually happening:
log stream --predicate 'subsystem == "io.openclaw"' --last 1h | tail -50
sudo journalctl -u openclaw-gateway -n 100 --no-pager
OpenClaw runs a Node.js process. Some AI provider SDKs and plugin code have memory leaks — small objects that accumulate over hours. After 8-16 hours, memory exceeds available RAM and the OS terminates the process.
# Check process memory right now ps aux | grep openclaw | grep -v grep # Check if system is low on memory free -h # Linux vm_stat # Mac
# Add to your gateway startup args (or systemd ExecStart) node --max-old-space-size=512 ... # Or: configure max memory in openclaw config # openclaw.json → "gateway.maxMemoryMb": 512
If your Mac shut down ungracefully (power cut, force-restart) while OpenClaw was writing config, the config file can be truncated. On the next startup, the gateway fails to parse it and exits immediately.
# Check if config is valid JSON cat ~/.openclaw/workspace/openclaw.json | python3 -m json.tool # Or check logs for parse errors grep -i "config\|parse\|json" /tmp/openclaw*.log 2>/dev/null || \ sudo journalctl -u openclaw-gateway | grep -i "config\|parse\|json"
# Check for automatic backup ls ~/.openclaw/workspace/openclaw.json.bak* # Restore if backup exists cp ~/.openclaw/workspace/openclaw.json.bak ~/.openclaw/workspace/openclaw.json # Re-run gateway setup if no backup openclaw gateway setup
If you regenerated your token in BotFather, or if Telegram revoked it (unusual), OpenClaw starts successfully but cannot connect to Telegram. The process keeps running but your bot is silent. Some versions exit and restart repeatedly.
# Look for Telegram auth errors in logs grep -i "telegram\|token\|401\|unauthorized" ~/.openclaw/workspace/logs/*.log 2>/dev/null | tail -20 # Quick test: check the token manually curl "https://api.telegram.org/bot<YOUR_TOKEN>/getMe"
# Edit config and replace the token nano ~/.openclaw/workspace/openclaw.json # → Find "botToken" under channels.telegram # → Replace with new token from BotFather # Then restart openclaw gateway restart
macOS updates and Homebrew upgrades can silently change your Node.js version. If native modules (node-pty, better-sqlite3) were compiled for Node 18 and you're now running Node 22, they crash immediately with a binding error.
node --version # Should show the same version OpenClaw was installed with # Check for binding errors in logs grep -i "binding\|NODE_MODULE_VERSION\|was compiled against" ~/.openclaw/workspace/logs/*.log 2>/dev/null | tail -5
cd ~/.openclaw # Rebuild all native modules for current Node version npm rebuild # If that fails, reinstall from scratch npm install # Then restart openclaw gateway restart
OpenClaw needs a specific port to run. If another process claims it first (another OpenClaw instance, a dev server, Docker container), the gateway exits immediately with EADDRINUSE.
# Find what's using OpenClaw's default port lsof -i :4999 2>/dev/null || ss -tlnp | grep 4999 # Check logs for the specific error grep -i "EADDRINUSE\|address in use\|port" ~/.openclaw/workspace/logs/*.log 2>/dev/null | tail -5
# Kill the process on the port (replace PID from lsof output) kill -9 <PID> # Or change OpenClaw's port in config: # openclaw.json → "gateway.port": 5001 # Restart openclaw gateway restart
OpenClaw and its dependencies need to write temp files, logs, and database records. When disk is full, any write fails and the process crashes. On VPS with small root partitions, this can fill up fast.
df -h / du -sh ~/.openclaw/workspace/logs/ 2>/dev/null du -sh /var/log/ 2>/dev/null # Linux
# Clear npm cache npm cache clean --force # Clear old logs journalctl --vacuum-size=200M # Linux find ~/.openclaw/workspace/logs -mtime +7 -delete # Clear /tmp sudo rm -rf /tmp/*
Run this in order. Stop at the first thing that shows a problem:
# 1. Check if process is running at all
pgrep -fl openclaw
# 2. Check recent logs for errors
sudo journalctl -u openclaw-gateway -n 50 --no-pager 2>/dev/null || \
tail -50 ~/.openclaw/workspace/logs/*.log 2>/dev/null
# 3. Check config is valid JSON
node -e "require('fs').readFileSync(process.env.HOME+'/.openclaw/workspace/openclaw.json','utf8')" && echo "config OK" || echo "CONFIG BROKEN"
# 4. Check disk
df -h / | tail -1
# 5. Check memory
free -h 2>/dev/null || vm_stat | grep Pages
# 6. Check Node version
node --version
# 7. Try a clean restart and watch for errors
openclaw gateway stop && openclaw gateway start 2>&1 | head -20If you've gone through all six causes and your bot is still crashing, there's likely something environment-specific going on — a plugin, a specific config combination, or a system state issue that doesn't fit the standard patterns.
At this point, the most efficient path is a fresh repair session where you can see live logs while you try fixes. Mechanic automates this: it collects diagnostics, tries the most likely strategy first, and escalates to a live terminal session if needed.