OpenClaw Expert Guide

Complete OpenClaw reference: architecture, gateway, CLI (50+ commands), 25+ channels, 25+ providers, tools, plugins, automation, security, installation, platforms. Use when answering OpenClaw config/setup/behavior questions, debugging issues (gateway, channels, failover, sandboxing, heartbeat, cron), writing openclaw.json, setting up channels (WhatsApp/Telegram/Discord/Signal/Slack/iMessage/etc.), configuring providers (Anthropic/OpenAI/Gemini/xAI/Ollama/MiniMax/etc.), managing agents/sessions/memory/workspace, CLI commands, automation (cron/hooks/heartbeat/tasks), installing on any platform (macOS/Linux/Windows/Docker/VPS/RPi/iOS/Android), using tools (exec/browser/image/video/TTS/music/sub-agents/ACP), plugins, security hardening, troubleshooting, or gateway protocol. NOT for writing OpenClaw source code.

OpenClaw Expert Skill

Complete OpenClaw reference compiled from 426+ official documentation pages. 12 reference files covering every aspect of the platform.

Reference File Index

Load the relevant file based on the user's question. Read only what's needed.

#	File	Topics	Lines
01	references/01-core-concepts.md	Architecture, agent runtime/loop, workspace, active memory, compaction, context engine, delegate architecture, dreaming, experimental features, markdown, memory (builtin/honcho/QMD/search), messages, model failover, model providers, models CLI, multi-agent routing, OAuth, presence, QA E2E automation, command queue, retry policy, sessions (management/pruning/tools), SOUL.md personality, streaming/chunking, system prompt, timezones, TypeBox schema, typing indicators, usage tracking, GPT-5.4/Codex agentic parity, Pi integration architecture, OpenProse	2647
02	references/02-gateway.md	Gateway runbook, authentication, background process, Bonjour/mDNS discovery, CLI backends, config (agents/channels/tools), configuration reference/examples, diagnostics export, doctor, gateway lock, health checks, heartbeat, local models, logging, multiple gateways, network model, OpenAI Chat Completions HTTP API, OpenResponses HTTP API, OpenShell, gateway-owned pairing, gateway protocol, remote access/setup, sandboxing (Docker/SSH/OpenShell), secrets management, security audit checks	1538
03	references/03-cli.md	All 50+ CLI subcommands: ACP, agent, agents, approvals/exec-policy, backup, browser, channels, completion, config, configure, cron, dashboard, devices, directory, DNS, docs, doctor, flows/tasks, gateway, health, hooks, infer/capability, logs, MCP, memory, message, models, node, nodes, onboard, pairing, plugins, proxy, QR, reset, sandbox, secrets, security, sessions, setup, skills, status, system, tasks, TUI/chat/terminal, uninstall, update, voicecall, webhooks, wiki + quick reference table	3299
04	references/04-channels.md	Channel overview/routing, groups, pairing, broadcast groups, location parsing, QA channel, BlueBubbles, Discord, Feishu/Lark, Google Chat, iMessage (legacy), IRC, LINE, Matrix (+ push rules), Mattermost, MS Teams, Nextcloud Talk, Nostr, QQ Bot, Signal, Slack, Synology Chat, Telegram, Tlon/Urbit, Twitch, WeChat, WhatsApp, Zalo (bot + personal), DM/group policy, multi-account, troubleshooting, feature comparison table	2765
05	references/05-providers.md	Anthropic, OpenAI, Gemini, OpenRouter, MiniMax, DeepSeek, Groq, Ollama, Together AI, Mistral, Fireworks, xAI, Perplexity, Amazon Bedrock, Cloudflare AI Gateway, Z.AI/GLM (Zhipu), 40+ additional providers (Arcee, Bedrock Mantle, Chutes, Claude Max Proxy, ComfyUI, GitHub Copilot, Gradium, Kilocode, LiteLLM, SGLang, Synthetic, Tencent, Vercel AI GW, vLLM, Volcengine, Vydra, Xiaomi, and more), model selection/failover config, env vars quick reference	1689
06	references/06-tools.md	Tool architecture, exec, code_execution, browser, message (agent send), image_generate, video_generate, music_generate, tts, web_fetch, sessions_spawn (sub-agents), web_search, tool configuration, gateway tool, memory_search/memory_get, session_status, plugin-provided tools	1448
07	references/07-plugins.md	Plugin system (install/develop/lifecycle), bundled plugins, voice-call, music-2.6, channel plugins, SDK conventions, registerCliBackend, registerAgentToolResultMiddleware, createOptionalChannelSetupSurface	1190
08	references/08-automation.md	Cron jobs (create/list/edit/delete/run/logs/doctor), background tasks (ledger), task flow, hooks (HTTP webhooks), standing orders, program examples (weekly status, content/social, financial, system monitoring), heartbeat, isolated sessions, failureDestination, model switch auth, Gmail PubSub, how they work together	948
09	references/09-installation.md	Getting started, updating, Docker (SSH/OpenShell sandbox, HEALTHCHECK, shared-network, VM runtime), Nix, Raspberry Pi, uninstall, onboarding wizard, VPS/Linux server deployment, migration guide, platform notes, Control UI custom build	1019
10	references/10-security-and-misc.md	Security model, exec approvals, sandbox modes, autoApproveCidrs, trusted-proxy, audit checks, FAQ, troubleshooting (gateway probe, doctor, channels --probe), debugging (watcher, PI_RAW_STREAM), env vars, scripts reference, nodes (remote exec, token rotation, SecretRef), diagnostics (export/recorder/privacy/flags), CI pipeline, RPC adapters	1226
11	references/11-platforms.md	macOS (app, discovery, --json), iOS (APNS relay, autoApproveCidrs, relay refresh), Android (autoApproveCidrs, foreground service, auto-reconnect, wide-area discover), Windows (companion, source dev loop, status), Linux (exe.dev, enable-linger), VPS hosting (shared agent, nodes, TimeoutStartSec), Web UI — Control UI (identity, auth gating, approval upgrade, base-hash guard, SecretRef preflight, abort, optimistic messages, compact button, Talk WebRTC, cron panel, schema.lookup, embedSandbox, chat.inject, config.apply) + WebChat (maxChars, abort metadata, tools panel)	965
12	references/12-reference.md	Configuration system overview, full config schema (gateway/agents/session/channels/cron/hooks/browser/UI/diagnostics/env), agent config reference, heartbeat reference (directPolicy/lightContext/isolatedSession/activeHours/ackMaxChars/multi-account/per-agent merge), workspace file map (BOOT.md hooks, bootstrap size limits, sandbox seed, Git backup), session management (threadBindings/maintenance/identityLinks), authentication (trusted-proxy fail-closed, HTTP API), gateway WS protocol (handshake/framing/roles/scopes/broadcast/RPC method families incl. diagnostics/secrets/sessions/approval/pairing), RPC adapters, CLI reference, onboarding wizard reference (providers table incl. MiniMax/StepFun/Synthetic/Moonshot/Kimi), file locations, env vars (OOM_SCORE_ADJ/PLUGIN_STAGE_DIR/ALLOW_INSECURE_PRIVATE_WS/PI_RAW_STREAM/DEBUG_TIMING/NODE_COMPILE_CACHE)	1546

Routing Guide

Match the user's question to the best starting file(s). Many topics span multiple files — follow cross-references.

Question Pattern	Start With	Then Check
Configuration / openclaw.json schema	12-reference.md	02-gateway.md
How do I set up X channel?	04-channels.md
How do I configure X provider?	05-providers.md
CLI command help / "how do I run..."	03-cli.md
Debugging / "not working" / errors	10-security-and-misc.md	03-cli.md (doctor/probe)
Heartbeat config / behavior	12-reference.md (heartbeat ref)	08-automation.md, 02-gateway.md
Cron jobs / scheduled tasks	08-automation.md	03-cli.md (cron CLI)
Hooks / webhooks	08-automation.md	03-cli.md (hooks CLI)
Standing orders / task flow	08-automation.md
Installation / getting started	09-installation.md	11-platforms.md
Docker setup	09-installation.md	02-gateway.md (sandboxing)
VPS / headless / PM2 / systemd	09-installation.md	11-platforms.md
Platform-specific apps (macOS/iOS/Android/Windows)	11-platforms.md
Control UI / WebChat / Web UI	11-platforms.md
Security / sandboxing / exec approvals	10-security-and-misc.md	02-gateway.md, 03-cli.md
Tools (exec/browser/image/video/TTS/music)	06-tools.md
Sub-agents / ACP / sessions_spawn	06-tools.md	01-core-concepts.md
Plugins (install/develop/voice-call/music)	07-plugins.md
Architecture / how OpenClaw works	01-core-concepts.md
Memory systems (builtin/honcho/QMD)	01-core-concepts.md	03-cli.md (memory CLI)
Agent workspace / bootstrap files	01-core-concepts.md	12-reference.md (workspace ref)
Sessions / multi-agent / routing	01-core-concepts.md	12-reference.md (session ref)
Model failover / retry / fallback chains	01-core-concepts.md	05-providers.md
System prompt / SOUL.md / personality	01-core-concepts.md
Streaming / typing indicators / presence	01-core-concepts.md
Usage tracking / token costs	01-core-concepts.md
Gateway protocol / WebSocket RPC	12-reference.md	02-gateway.md
Nodes / remote exec / token rotation	10-security-and-misc.md	12-reference.md
Diagnostics / export / recorder	10-security-and-misc.md
Environment variables	10-security-and-misc.md	12-reference.md
Migration / updating	09-installation.md
Bonjour / mDNS / discovery	02-gateway.md
OpenAI-compatible API / OpenResponses	02-gateway.md
GPT-5.4 / Codex parity / strict-agentic	01-core-concepts.md
Pi integration / createAgentSession	01-core-concepts.md
OpenProse / .prose workflows	01-core-concepts.md	07-plugins.md
FAQ	10-security-and-misc.md

Key Quick-Reference

Config File Location

~/.openclaw/openclaw.json (JSON5 with comments/trailing commas)

Essential CLI Commands

bash

openclaw onboard          # Interactive setup
openclaw doctor           # Diagnose issues
openclaw doctor --fix     # Auto-repair
openclaw gateway start    # Start daemon
openclaw gateway status   # Check status
openclaw status --deep    # Full health probe
openclaw config get <path>    # Read config value
openclaw config set <path> <value>  # Write config value
openclaw cron list        # List cron jobs
openclaw models list      # List available models
openclaw models scan      # Probe all configured models

Model Format

Always provider/model — e.g. anthropic/claude-sonnet-4-6, openai/gpt-5.4, minimax/MiniMax-M2.7

DM Policy Options

pairing (default) → allowlist → open → disabled

Sandbox Modes

off (default) | non-main | all — scope: session | agent | shared

Heartbeat Defaults

• Interval: 30m (or 1h for Anthropic OAuth/token auth)
• Target: none (set last for delivery to last contact)
• Reply HEARTBEAT_OK when nothing needs attention

Session Scoping

main | per-peer | per-channel-peer (recommended) | per-account-channel-peer

File Precedence (workspace context)

Bootstrap files loaded every session: AGENTS.md, SOUL.md, USER.md, IDENTITY.md, TOOLS.md, HEARTBEAT.md Per-file limit: bootstrapMaxChars (default 12000), total: bootstrapTotalMaxChars (default 60000)

Grep Patterns for Efficient Lookup

All reference files are large. Use targeted reads instead of loading entire files:

bash

# Find a specific topic's section
grep -n '^## \|^### ' references/01-core-concepts.md   # List all headings
grep -n 'heartbeat' references/12-reference.md          # Find heartbeat mentions
grep -n '^## Telegram' references/04-channels.md         # Jump to Telegram section
grep -n '^## Anthropic' references/05-providers.md       # Jump to Anthropic section

Strategy for large files:

1. Read the first 40 lines (TOC or section overview) to locate the heading
2. grep -n '^## TARGET' to find the line number
3. Read only that section with offset/limit

Common Multi-File Lookups

Some topics are spread across files. Read in this order:

Topic	Primary	Secondary	Tertiary
Heartbeat	12-reference.md §Heartbeat Reference	08-automation.md §Heartbeat	02-gateway.md §Heartbeat
Sandboxing	02-gateway.md §Sandboxing	10-security-and-misc.md §Security	03-cli.md §Sandbox
Memory	01-core-concepts.md §Memory	03-cli.md §Memory	07-plugins.md §Memory Plugins
Exec approvals	10-security-and-misc.md §Security	03-cli.md §Approvals	11-platforms.md §Control UI
Docker	09-installation.md §Docker	02-gateway.md §Sandboxing
WebSocket	12-reference.md §Gateway Protocol	02-gateway.md §Gateway Protocol	01-core-concepts.md §TypeBox

Notes

• All 12 reference files have a Table of Contents at the top — read that first to locate the relevant section.
• Cross-reference between files is common. The routing guide and multi-file lookup table above cover the main overlaps.
• All content verified against live docs at docs.openclaw.ai as of April 2026.