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: File Map 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: "WhatsApp fully disconnected" Troubleshooting: Telegram "Bots have issues / forget things" Two separate problems that look the same: Telegram config fix template Troubleshooting: Signal "Signal RPC Failed to send message" This blocks cron jobs and cross channel notifications. Troubleshooting: Cron Jobs Troubleshooting: Memory / "It Forgot" The memory system has 3 layers. When the agent "forgets," one of these broke: Layer 1: Context window (within a session) Layer 2: Workspace memory files Layer 3: Vector memory database (SQLite + Gemini embeddings) Searching Sessions Find a person's conversations Find sessions by channel Most recent sessions Search message content across all sessions Read a specific session transcript Config Editing Safe edit pattern Always: backup, edit with jq, restart. Common edits Restore from backup Channel Security Modes Mode Behavior Risk open + allowFrom: [" "] Anyone can message, bot responds to all HIGH — burns API credits, bot speaks as you allowlist + allowFrom: ["+1..."] Only listed numbers get through LOW — explicit control pairing Unknown senders get a code, you approve LOW — approval gate disabled Channel completely off NONE Check current security posture Workspace Files File What When to edit SOUL.md Personality: tone, style ("no em dashes, lowercase casual") To change how the bot talks IDENTITY.md Name (Jarvis), creature type, emoji To rebrand USER.md Owner info, preferences When user context changes AGENTS.md Operating rules: memory protocol, safety, group chat behavior, heartbeat instructions To change bot behavior BOOT.md Startup instructions (autopilot notification protocol: WA → Signal) To change what happens on boot HEARTBEAT.md Periodic checklist (empty = no heartbeat API calls) To add/remove periodic tasks MEMORY.md Curated long term memory (loaded only in main/direct sessions) Bot manages this itself TOOLS.md Contacts, SSH hosts, device nicknames To add local tool notes memory/ .md Daily raw logs, topic specific chat logs Bot writes automatically Session JSONL Format Each .jsonl file has one JSON object per line. Types: type What session Session header: id, timestamp, cwd message Conversation turn: role (user/assistant/toolResult), content, model, usage custom Metadata: model snapshot , openclaw.cache ttl compaction Context window was pruned (old messages dropped) model change Model was switched mid session thinking level change Thinking level adjusted Session index ( sessions.json ) keys: Pattern: agent:main:{channel}:{contact} or agent:main:cron:{job uuid} Fields: sessionId (UUID = filename), lastChannel , origin.label (human name), origin.from (canonical address), updatedAt (epoch ms), chatType (direct/group) Gateway Startup Sequence Normal startup takes ~3 seconds: If any line is missing, that component failed to start. Check gateway.err.log . Known Error Patterns Error Meaning Fix Web connection closed (status 408) WhatsApp web timeout, auto retries up to 12x Usually self heals. If reaches 12/12, restart gateway Signal RPC 1: Failed to send message signal cli daemon lost connection Restart gateway Signal RPC 5: Failed to send message due to rate limiting Signal rate limit Wait and retry, reduce message frequency No profile name set (signal cli WARN) Floods logs, harmless signal cli a +ACCOUNT updateProfile given name "Name" Cross context messaging denied Agent tried to send across channels Not a bug — security guardrail. Message must originate from correct channel session getUpdates timed out after 500 seconds Telegram bot lost polling connection Restart gateway Unrecognized keys: "token", "username" Wrong config keys for Telegram bots Use botToken not token in openclaw.json RESOURCE EXHAUSTED (Gemini 429) Embedding rate limit Reduce workspace file churn, or upgrade Gemini quota lane wait exceeded Agent blocked on long LLM call Wait, or restart if stuck 2 min embedded run timeout: timeoutMs=600000 Agent response exceeded 10 min Break task into smaller pieces gateway timeout after 10000ms Gateway unreachable during restart window Cron fired while gateway was down — transient Extending OpenClaw OpenClaw has 4 extension layers. Each solves a different problem: Layer What Where How to add Skills Knowledge + workflows the agent loads on demand /opt/homebrew/lib/node modules/openclaw/skills/ or ~/.openclaw/workspace/skills/ clawdhub install <slug or npx add skill <repo Extensions Custom channel plugins (TypeScript) ~/.openclaw/extensions/{name}/ Create openclaw.plugin.json + TypeScript source Channels Messaging platforms (built in) openclaw.json → channels. + plugins.entries. Configure in openclaw.json, add credentials Cron jobs Scheduled autonomous tasks ~/.openclaw/cron/jobs.json Agent creates them via tool, or edit jobs.json directly Skills: ClawdHub Ecosystem Skills are the primary way to extend what the agent knows and can do. They're markdown files with optional scripts/assets that get loaded into context when relevant. Currently installed skills (bundled with OpenClaw): Category Skills Messaging discord, slack, imsg, wacli, voice call Social/Web bird (X/Twitter), blogwatcher, github, trello, notion Google gog, google workspace mcp, goplaces, local places Media nano banana pro (Gemini image gen), openai image gen, video frames, gifgrep, pixelation, sag (TTS), openai whisper, sherpa onnx tts, songsee, camsnap Coding agents coding agent (Codex/Claude Code/Pi), ccbg (background runner), tmux Productivity apple notes, apple reminders, bear notes, things mac, obsidian, himalaya (email) Smart home openhue (Philips Hue), eightctl (Eight Sleep), sonoscli, blucli (BluOS) Dev tools github, worktree, starter, desktop, supabase postgres best practices, superdesign Content remotion best practices, remotion fastest tech stack, humanizer, summarize, market, buildinpublic Meta skill creator, clawdhub, find skills, add skill, model usage, session logs, recentplans, canvas Creating Your Own Skill A skill is just a folder with a SKILL.md : SKILL.md format: Key principle: the context window is a shared resource. Only include what the agent doesn't already know. Prefer concise examples over verbose explanations. Multi Agent Orchestration OpenClaw can spawn other AI agents (Codex, Claude Code, Pi) as background workers. This is how you run parallel coding tasks, reviews, or any work that benefits from multiple agents. The pattern: bash pty:true background:true workdir:/path command:"agent 'task'" Parallel PR reviews: Parallel issue fixing with git worktrees: Auto notify when agent finishes: Adding a New Channel Channels are messaging platforms the agent can communicate through. Built in: WhatsApp, Signal, Telegram, iMessage, Discord, Slack. Enable a built in channel: Build a custom channel extension: Cross Channel Communication The agent can receive on one channel and send on another, but there are guardrails: BOOT.md notification protocol (already configured): The agent receives WhatsApp messages, responds on WhatsApp, then sends a notification summary to Signal. This is the primary cross channel pattern — autopilot on one channel, control center on another. Canvas: Web UI for Connected Devices Push HTML/games/dashboards to connected Mac/iOS/Android nodes: Voice Calls Initiate phone calls via Twilio/Telnyx/Plivo: Cron: Scheduled Autonomous Tasks License MIT

openclaw-config