- name
- openclaw-expert
- description
- 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
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 modelsModel 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(or1hfor Anthropic OAuth/token auth) - Target:
none(setlastfor delivery to last contact) - Reply
HEARTBEAT_OKwhen 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:
# 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 sectionStrategy for large files:
- Read the first 40 lines (TOC or section overview) to locate the heading
grep -n '^## TARGET'to find the line number- 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.