openclaw-config

# 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: ```bash 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: ```bash # 1. Is the bot actually running? grep -i "whatsapp.*starting\|whatsapp.*listening" ~/.openclaw/logs/gateway.log | tail -5 # 2. Check for 408 timeout drops (WhatsApp web disconnects frequently) grep -i "408\|499\|retry" ~/.openclaw/logs/gateway.err.log | tail -10 # If you see "Web connection closed (status 408). Retry 1/12" — this is normal, # it auto-recovers. But if retries reach 12/12, the session dropped completely. # 3. Check for cross-context messaging blocks grep -i "cross-context.*denied" ~/.openclaw/logs/gateway.err.log | tail -10 # Common: "Cross-context messaging denied: action=send target provider "whatsapp" while bound to "signal"" # This means the agent was in a Signal session and tried to reply on WhatsApp. # FIX: The message needs to come through in the WhatsApp session context, not Signal. # 4. Check the session exists for that contact cat ~/.openclaw/agents/main/sessions/sessions.json | jq -r 'to_entries[] | select(.key | test("whatsapp")) | "\(.key) | \(.value.origin.label // "?")"' # 5. Check if the sender is allowed cat ~/.openclaw/openclaw.json | jq '.channels.whatsapp | {dmPolicy, allowFrom, selfChatMode, groupPolicy}' # If dmPolicy is "allowlist" and the sender isn't in allowFrom, message is silently dropped. # 6. Check if it's a group message (groups are disabled by default) cat ~/.openclaw/openclaw.json | jq '.channels.whatsapp.groupPolicy' # "disabled" means ALL group messages are ignored. # 7. Check for lane congestion (agent busy with another task) grep "lane wait exceeded" ~/.openclaw/logs/gateway.err.log | tail -5 # If the agent is stuck on a long LLM call, new messages queue up. # 8. Check for agent run timeout grep "embedded run timeout" ~/.openclaw/logs/gateway.err.log | tail -5 # Hard limit is 600s (10 min). If the agent's response takes longer, it's killed. ``` ### "WhatsApp fully disconnected" ```bash # Check credential files exist (should be ~1400 files) ls ~/.openclaw/credentials/whatsapp/default/ | wc -l # If 0 files: session was never created or got wiped # Fix: re-pair with `openclaw configure` # Check for QR/pairing events grep -i "pair\|link\|qr\|scan\|logged out" ~/.openclaw/logs/gateway.log | tail -10 # Check for Baileys errors grep -i "baileys\|DisconnectReason\|logout\|stream:error" ~/.openclaw/logs/gateway.err.log | tail -20 # Nuclear fix: delete credentials and re-pair # rm -rf ~/.openclaw/credentials/whatsapp/default/ # openclaw configure ``` --- ## Troubleshooting: Telegram ### "Bots have issues / forget things" Two separate problems that look the same: ```bash # 1. Check for config validation errors (THE COMMON ONE) grep -i "telegram.*unrecognized\|telegram.*invalid\|telegram.*policy" ~/.openclaw/logs/gateway.err.log | tail -10 # Known issue: the keys "token" and "username" under accounts are not recognized. # The correct field is "botToken", not "token". # 2. Check the actual config cat ~/.openclaw/openclaw.json | jq '.channels.telegram' # Verify each bot has "botToken" (not "token") and "name" fields. # 3. Check polling status — bots die after getUpdates timeout grep -i "telegram.*exit\|telegram.*timeout\|getUpdates" ~/.openclaw/logs/gateway.err.log | tail -10 # "[telegram] [sales] channel exited: Request to 'getUpdates' timed out after 500 seconds" # This means the bot lost connection to Telegram's API and stopped listening. # Fix: restart gateway — `openclaw gateway restart` # 4. Check the polling offset (if bot "forgets" or replays old messages) cat ~/.openclaw/telegram/update-offset-coder.json cat ~/.openclaw/telegram/update-offset-sales.json # If lastUpdateId is stuck or 0, the bot will reprocess old messages. # To skip to latest: the gateway sets this automatically on restart. # 5. Check if both bots are starting grep -i "telegram.*starting\|telegram.*coder\|telegram.*sales" ~/.openclaw/logs/gateway.log | tail -10 # 6. "Bot forgets" — this is usually a session issue, not Telegram # Each Telegram user gets their own session in sessions.json. # Check if the session exists: cat ~/.openclaw/agents/main/sessions/sessions.json | jq -r 'to_entries[] | select(.key | test("telegram")) | "\(.key) | \(.value.origin.label // "?")"' # 7. Check if compaction happened (context window pruned = "forgot") SESS_ID="paste-session-id" grep '"compaction"' ~/.openclaw/agents/main/sessions/$SESS_ID.jsonl | wc -l # If compaction count > 0, old messages were pruned from context. # The agent's compaction mode is: cat ~/.openclaw/openclaw.json | jq '.agents.defaults.compaction' ``` ### Telegram config fix template ```bash # Correct Telegram config structure: cat ~/.openclaw/openclaw.json | jq '.channels.telegram = { "enabled": true, "accounts": { "coder": { "name": "Bot Display Name", "enabled": true, "botToken": "your-bot-token-here" }, "sales": { "name": "Sales Bot Name", "enabled": true, "botToken": "your-bot-token-here" } }, "dmPolicy": "pairing", "groupPolicy": "disabled" }' > /tmp/oc.json && mv /tmp/oc.json ~/.openclaw/openclaw.json ``` --- ## Troubleshooting: Signal ### "Signal RPC Failed to send message" This blocks cron jobs and cross-channel notifications. ```bash # 1. Check if signal-cli process is alive ps aux | grep "[s]ignal-cli" # 2. Check the RPC endpoint grep -i "signal.*starting\|signal.*8080\|signal.*rpc" ~/.openclaw/logs/gateway.log | tail -10 # Should see: "[signal] [default] starting provider (http://127.0.0.1:8080)" # 3. Check for connection instability grep -i "HikariPool\|reconnecting\|SSE stream error\|terminated" ~/.openclaw/logs/gateway.err.log | tail -10 # "HikariPool-1 - Thread starvation or clock leap detected" = signal-cli internal DB issue # "SSE stream error: TypeError: terminated" = lost connection to signal-cli daemon # 4. Check for rate limiting grep -i "signal.*rate" ~/.openclaw/logs/gateway.err.log | tail -5 # "Signal RPC -5: Failed to send message due to rate limiting" # 5. Check for wrong target format grep -i "unknown target" ~/.openclaw/logs/gateway.err.log | tail -5 # "Unknown target "adi" for Signal. Hint: <E.164|uuid:ID|...>" # The agent must use phone numbers (+1...) or uuid: format, not names. # 6. Fix profile name warning spam grep -c "No profile name set" ~/.openclaw/logs/gateway.err.log # If high count: run signal-cli updateProfile to set a name # 7. Test signal-cli directly ACCT=$(cat ~/.openclaw/openclaw.json | jq -r '.channels.signal.account') echo "Account: $ACCT" # signal-cli -a $ACCT send -m "test" +TARGET_NUMBER # 8. Check if the signal-cli daemon needs restart # The gateway manages signal-cli as a subprocess. # Restart the whole gateway: openclaw gateway restart ``` --- ## Troubleshooting: Cron Jobs ```bash # 1. Overview of all jobs cat ~/.openclaw/cron/jobs.json | jq -r '.jobs[] | "\(.enabled | if . then "ON " else "OFF" end) \(.state.lastStatus // "never" | if . == "error" then "FAIL" elif . == "ok" then "OK " else . end) \(.name)"' # 2. Failing jobs with error details cat ~/.openclaw/cron/jobs.json | jq '.jobs[] | select(.state.lastStatus == "error") | {name, error: .state.lastError, lastRun: (.state.lastRunAtMs | . / 1000 | todate), id}' # 3. Read the actual run log for a failing job JOB_ID="paste-job-uuid-here" tail -20 ~/.openclaw/cron/runs/$JOB_ID.jsonl | python3 -c " import sys, json for line in sys.stdin: try: obj = json.loads(line)