OpenClaw Expert Guide

Complete OpenClaw reference: architecture, gateway, CLI (50+ commands), 25+ channels, 25+ providers, tools, plugins, automation, security, installation, plat...

Security Scan

This is an instruction-only, read‑only documentation skill that matches its name/description and does not request credentials or install code, but the SKILL.md contains a prompt-injection pattern so you should review the files before trusting privileged agent actions.

Purpose & Capability

The skill is a large, offline reference for OpenClaw (architecture, gateway, CLI, channels, providers, tools, etc.). The files, SKILL.md, and README align with that purpose. There are no unexpected binaries, install scripts, or environment variables declared that would be disproportionate to a docs/reference skill.

Instruction Scope

The SKILL.md tells the agent to load only the relevant reference file and to consult those docs to answer OpenClaw questions. That is appropriate for a docs skill, but the static scanner flagged a 'system-prompt-override' pattern inside SKILL.md — the skill includes an explicit top-level instruction block (YAML header/description) that could be abused as a prompt-injection vector if your agent blindly trusts file contents as system-level directives. Also, the reference files include operational commands and runbooks (CLI examples, SSH tunnels, env var usage) which are normal documentation but could lead an agent to recommend running commands on the host; review any suggested commands before executing them.

Install Mechanism

No install spec or external downloads are present; this is instruction-only with documentation files. No code is written to disk by an installer here, which is the lowest-risk install profile.

Credentials

The skill declares no required env vars, credentials, or config paths. The documentation references many env var names and secrets as part of the OpenClaw docs (expected for a reference), but the skill does not require you to provide any secrets to install or use it.

Persistence & Privilege

always is false and the skill is user-invocable. It does not request permanent elevated presence or claim to modify other skills or system-wide config. Autonomous invocation is enabled by platform default but is not combined with other privilege red flags here.

Scan Findings in Context

[system-prompt-override] unexpected: SKILL.md contains a YAML header/description and explicit agent routing instructions; that pattern can be flagged as a system-prompt-override because large instruction blocks in doc files can attempt to influence agent behavior. For a docs/reference skill this is plausible/expected, but treat it as a prompt-injection signal and manually review for directives that demand system-level changes, secrets exfiltration, or execution of host commands.

Assessment

This skill appears to be what it claims: a large offline OpenClaw documentation pack with no installers or credential requirements. Before installing or enabling it for autonomous use: 1) Verify the source/author (the registry lists an owner ID but no homepage); prefer skills from known publishers or a GitHub repo you can inspect. 2) Manually scan SKILL.md and the reference files for any lines that tell the agent to run shell commands, read files outside the workspace, fetch remote URLs, or print/transfer secrets — documentation often contains such examples and an agent might repeat them. 3) If you plan to allow autonomous agent invocation, test the skill in an isolated/dev profile (use a non-production gateway/profile) so you can observe what suggestions the agent produces before granting it broader privileges. 4) If you are uneasy about prompt-injection, restrict the skill to user-invoked only (don’t enable autonomous invocation for high-privilege agents) and avoid providing any host secrets to the environment while evaluating the skill.

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 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:

# 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.