OpenClaw Operations Runbook
Diagnose and fix real problems. Every command here is tested and works.
Quick Health Check
Run this first when anything seems wrong. Copy-paste the whole block:
echo "=== GATEWAY ===" && \
ps aux | grep -c "[o]penclaw" && \
echo "=== CONFIG JSON ===" && \
python3 -m json.tool ~/.openclaw/openclaw.json > /dev/null 2>&1 && echo "JSON: OK" || echo "JSON: BROKEN" && \
echo "=== CHANNELS ===" && \
cat ~/.openclaw/openclaw.json | jq -r '.channels | to_entries[] | "\(.key): policy=\(.value.dmPolicy // "n/a") enabled=\(.value.enabled // "implicit")"' && \
echo "=== PLUGINS ===" && \
cat ~/.openclaw/openclaw.json | jq -r '.plugins.entries | to_entries[] | "\(.key): \(.value.enabled)"' && \
echo "=== CREDS ===" && \
ls ~/.openclaw/credentials/whatsapp/default/ 2>/dev/null | wc -l | xargs -I{} echo "WhatsApp keys: {} files" && \
for d in ~/.openclaw/credentials/telegram/*/; do bot=$(basename "$d"); [ -f "$d/token.txt" ] && echo "Telegram $bot: OK" || echo "Telegram $bot: MISSING"; done && \
[ -f ~/.openclaw/credentials/bird/cookies.json ] && echo "Bird cookies: OK" || echo "Bird cookies: MISSING" && \
echo "=== CRON ===" && \
cat ~/.openclaw/cron/jobs.json | jq -r '.jobs[] | "\(.name): enabled=\(.enabled) status=\(.state.lastStatus // "never") \(.state.lastError // "")"' && \
echo "=== RECENT ERRORS ===" && \
tail -10 ~/.openclaw/logs/gateway.err.log 2>/dev/null && \
echo "=== MEMORY DB ===" && \
sqlite3 ~/.openclaw/memory/main.sqlite "SELECT COUNT(*) || ' chunks, ' || (SELECT COUNT(*) FROM files) || ' files indexed' FROM chunks;" 2>/dev/null
File Map
~/.openclaw/
├── openclaw.json # MAIN CONFIG — channels, auth, gateway, plugins, skills
├── openclaw.json.bak* # Auto-backups (.bak, .bak.1, .bak.2 ...)
├── exec-approvals.json # Exec approval socket config
│
├── agents/main/
│ ├── agent/auth-profiles.json # Anthropic auth tokens
│ └── sessions/
│ ├── sessions.json # SESSION INDEX — keys are like agent:main:whatsapp:+1234
│ └── *.jsonl # Session transcripts (one JSON per line)
│
├── workspace/ # Agent workspace (git-tracked)
│ ├── SOUL.md # Personality, writing style, tone rules
│ ├── IDENTITY.md # Name, creature type, vibe
│ ├── USER.md # Owner context and preferences
│ ├── AGENTS.md # Session behavior, memory rules, safety
│ ├── BOOT.md # Boot instructions (autopilot notification protocol)
│ ├── HEARTBEAT.md # Periodic task checklist (empty = skip heartbeat)
│ ├── MEMORY.md # Curated long-term memory (main session only)
│ ├── TOOLS.md # Contacts, SSH hosts, device nicknames
│ ├── memory/ # Daily logs: YYYY-MM-DD.md, topic-chat.md
│ └── skills/ # Workspace-level skills
│
├── memory/main.sqlite # Vector memory DB (Gemini embeddings, FTS5 search)
│
├── logs/
│ ├── gateway.log # Runtime: startup, channel init, config reload, shutdown
│ ├── gateway.err.log # Errors: connection drops, API failures, timeouts
│ └── commands.log # Command execution log
│
├── cron/
│ ├── jobs.json # Job definitions (schedule, payload, delivery target)
│ └── runs/ # Per-job run logs: {job-uuid}.jsonl
│
├── credentials/
│ ├── whatsapp/default/ # Baileys session: ~1400 app-state-sync-key-*.json files
│ ├── telegram/{botname}/token.txt # Bot tokens (one per bot account)
│ └── bird/cookies.json # X/Twitter auth cookies
│
├── extensions/{name}/ # Custom plugins (TypeScript)
│ ├── openclaw.plugin.json # {"id", "channels", "configSchema"}
│ ├── index.ts # Entry point
│ └── src/ # channel.ts, actions.ts, runtime.ts, types.ts
│
├── identity/ # device.json, device-auth.json
├── devices/ # paired.json, pending.json
├── media/inbound/ # Received images, audio files
├── media/browser/ # Browser screenshots
├── browser/openclaw/user-data/ # Chromium profile (~180MB)
├── tools/signal-cli/ # Signal CLI binary
├── subagents/runs.json # Sub-agent execution log
├── canvas/index.html # Web canvas UI
└── telegram/
├── update-offset-coder.json # {"lastUpdateId": N} — Telegram polling cursor
└── update-offset-sales.json # Reset these to 0 to replay missed messages
Troubleshooting: WhatsApp
"I sent a message but got no reply"
This is the #1 issue. The message arrives but the bot doesn't respond. Check in this order:
grep -i "whatsapp.*starting\|whatsapp.*listening" ~/.openclaw/logs/gateway.log | tail -5
grep -i "408\|499\|retry" ~/.openclaw/logs/gateway.err.log | tail -10
grep -i "cross-context.*denied" ~/.openclaw/logs/gateway.err.log | tail -10
cat ~/.openclaw/agents/main/sessions/sessions.json | jq -r 'to_entries[] | select(.key | test("whatsapp")) | "\(.key) | \(.value.origin.label // "?")"'
cat ~/.openclaw/openclaw.json | jq '.channels.whatsapp | {dmPolicy, allowFrom, selfChatMode, groupPolicy}'
cat ~/.openclaw/openclaw.json | jq '.channels.whatsapp.groupPolicy'
grep "lane wait exceeded" ~/.openclaw/logs/gateway.err.log | tail -5
grep "embedded run timeout" ~/.openclaw/logs/gateway.err.log | tail -5
"WhatsApp fully disconnected"
ls ~/.openclaw/credentials/whatsapp/default/ | wc -l
grep -i "pair\|link\|qr\|scan\|logged out" ~/.openclaw/logs/gateway.log | tail -10
grep -i "baileys\|DisconnectReason\|logout\|stream:error" ~/.openclaw/logs/gateway.err.log | tail -20
Troubleshooting: Telegram
"Bots have issues / forget things"
Two separate problems that look the same:
grep -i "telegram.*unrecognized\|telegram.*invalid\|telegram.*policy" ~/.openclaw/logs/gateway.err.log | tail -10
cat ~/.openclaw/openclaw.json | jq '.channels.telegram'
grep -i "telegram.*exit\|telegram.*timeout\|getUpdates" ~/.openclaw/logs/gateway.err.log | tail -10
cat ~/.openclaw/telegram/update-offset-coder.json
cat ~/.openclaw/telegram/update-offset-sales.json
grep -i "telegram.*starting\|telegram.*coder\|telegram.*sales" ~/.openclaw/logs/gateway.log | tail -10
cat ~/.openclaw/agents/main/sessions/sessions.json | jq -r 'to_entries[] | select(.key | tes
