Operations Guide

Never break your gateway again

Battle-tested prevention and recovery procedures from 30+ days of production OpenClaw use. What I broke, how I fixed it, how you avoid it.

Read the Guide OpenClaw Docs

Daily Prevention

The 5-minute checklist that saves hours

Run these checks daily. Catch problems before they become outages.

✅ Morning Health Check

✓ Gateway status: openclaw gateway status — should show "running"
✓ Model availability: Test a simple query — verify primary + fallbacks respond
⚠ Disk space: df -h ~/.openclaw — alert if >80% used
✓ Session logs: Check for error spikes in last 24h
⚠ API rate limits: Verify you're under daily quotas (OpenAI, Anthropic, Google)
💡 Pro tip: Automate this checklist with a cron job. I run mine at 8 AM daily via openclaw cron.

War Stories

Real problems we've faced and fixed

From 30+ days of production use. Each problem includes the symptom, root cause, and exact fix.

🔴 Discord Auth Failure (401 Error)

Symptom

Discord channel status: 🔴 Failed
Error: 401 Unauthorized

Root Cause

Discord bot tokens expire or get invalidated. This happens when you regenerate the token in Discord Developer Portal, the bot was kicked/banned, or token was copied incorrectly.

Quick Fix

# 1. Go to Discord Developer Portal → Bot → Reset Token
# 2. Update config:
nano ~/.openclaw/openclaw.json
# 3. Restart: openclaw gateway restart

Prevention

Store tokens in a password manager. Don't commit tokens to git. Test bot connection after any token change.

🔍 Models Configured But Not Showing

Symptom

$ openclaw models list
# SumoPod/BytePlus models missing

Root Cause

The config file says the provider exists, but the gateway didn't load it. Base URL wrong, API key invalid, or gateway needs restart.

Quick Fix

# 1. Test API: curl -s https://ai.sumopod.com/v1/models
# 2. Restart: openclaw gateway restart
# 3. Verify: openclaw models list | grep sumopod

Prevention

Always test API with curl before adding to config. Restart gateway after any provider config change.

🌙 Midnight Memory Sync Failing

Symptom

❌ Knowledge Backup — Failed: directory is not a git repository

Root Cause

The Obsidian vault wasn't initialized as a git repo. The sync script tries to push to GitHub but fails.

Quick Fix

cd ~/path/to/obsidian-vault
git init && git remote add origin https://github.com/youruser/your-vault.git
git add . && git commit -m "Initial commit" && git push -u origin main

Prevention

Initialize git on day one when setting up Obsidian. Test push/pull before relying on automated sync.

⚙️ Config Changes Not Applying

Symptom

# You edit openclaw.json, but behavior doesn't change

Root Cause

OpenClaw reads config on startup. Editing the file doesn't automatically reload it.

Quick Fix

# Option A: openclaw gateway restart
# Option B: kill -USR1 $(pgrep -f openclaw)

Prevention

Get in the habit: edit config → restart gateway → test. Use openclaw config.validate before restarting.

📱 Telegram Bot Won't Respond in Groups

Symptom

Bot responds in DMs ✅ Bot ignores group messages ❌

Root Cause

Telegram has "privacy mode" for bots. By default, bots can't read all group messages — only messages that mention them.

Quick Fix

# Option A: Set requireMention: true in config
# Option B: @BotFather → /setprivacy → Disable

Prevention

Set requireMention: true from the start. Document expected behavior for users.

⚠️ Model Rate Limiting (HTTP 429)

Symptom

Error: HTTP 429 Too Many Requests
Fallback chain exhausted

Root Cause

You hit the API provider's rate limit. Gemini: 60 req/min, Claude: 50 req/min, OpenAI: varies.

Quick Fix

# Switch primary model temporarily
"primary": "bailian/glm-4.7"
openclaw gateway restart

Prevention

Always configure 2-3 fallback models. Monitor rate limit headers. Consider paid tier if consistent.

💾 Disk Space Warnings

Symptom

$ df -h ~/.openclaw
/dev/sda1 50G 42G 5G 89% ⚠️

Root Cause

Session logs, memory indexes, and config backups grow over time. Without cleanup, they fill the disk.

Quick Fix

# Clean old logs: rm -rf ~/.openclaw/logs/*.log.*
# Prune sessions: find ~/.openclaw/sessions -mtime +7 -delete
# Compress: gzip ~/.openclaw/logs/*.log.*

Prevention

Set up log rotation cron job. Monitor disk usage. Store large files outside ~/.openclaw.

🔧 Gateway Won't Start (Config Syntax Error)

Symptom

Error: Invalid JSON in config file

Root Cause

You edited openclaw.json and introduced a syntax error (missing comma, unclosed brace, trailing comma).

Quick Fix

# 1. Validate: openclaw config.validate
# 2. Restore backup: cp ~/.openclaw/openclaw.json.backup ~/.openclaw/openclaw.json
# 3. Restart: openclaw gateway start

Prevention

Always run openclaw config.validate after editing. Keep automatic backups enabled.

When Things Break

Recovery playbooks

Something went wrong. Don't panic. Follow the playbook.

🔴 Gateway Won't Start

! Check logs: journalctl -u openclaw -n 50
⚠ Common cause: Config syntax error — run openclaw config.validate
✓ Fix: Restore from backup: cp ~/.openclaw/openclaw.json.backup ~/.openclaw/openclaw.json
✓ Restart: openclaw gateway restart

🔴 Model Rate-Limited

⚠ Symptom: HTTP 429 errors in logs, fallback chain exhausted
✓ Immediate: Switch to a different provider in openclaw.json
✓ Long-term: Add more fallbacks, implement request queuing
# Emergency: Force restart with clean config openclaw gateway stop cp ~/.openclaw/config.default.json ~/.openclaw/openclaw.json openclaw gateway start

Want the full guide?

This is a condensed version. The full guide includes weekly maintenance, backup strategies, and 15+ recovery playbooks.

Back to Portfolio