Feature Atlas

Feature Atlas

A structured map of every OpenClaw feature — organized by category, cross-referenced to guide sections, and annotated with known issues. Use this page to understand what’s available, where to configure it, and what to watch out for.

Feature Overview

  %%{init: { "theme": "base", "themeVariables": { "fontFamily": "ui-sans-serif, -apple-system, BlinkMacSystemFont, Segoe UI, Helvetica, Arial", "primaryColor": "#1F4E79", "primaryBorderColor": "#93C5FD", "primaryTextColor": "#F8FAFC", "lineColor": "#94A3B8", "secondaryColor": "#334155", "tertiaryColor": "#334155", "background": "transparent" } }}%%
graph TB
    subgraph CH["Channels & Messaging"]
        direction TB
        CH1["WhatsApp · Signal · Google Chat"]
        CH2["DM & Group Policies"]
        CH3["Mention Gating · Chat Commands"]
    end

    subgraph AG["Agents & Configuration"]
        direction TB
        AG1["Agent Definitions · Routing"]
        AG2["A2A · Subagents · LLM Providers"]
        AG3["Config Includes · Validation"]
    end

    subgraph SM["Sessions & Memory"]
        direction TB
        SM1["Session Scoping (4 modes)"]
        SM2["Two-Layer Memory · Hybrid Search"]
        SM3["Compaction · Temporal Decay"]
    end

    subgraph SE["Security & Hardening"]
        direction TB
        SE1["Sandbox Modes · Docker / VM"]
        SE2["Tool Policies (8 layers)"]
        SE3["5 Guard Plugins · SOUL.md"]
    end

    subgraph TA["Tools & Automation"]
        direction TB
        TA1["44 Tools in 8 Groups"]
        TA2["Cron Jobs · Web Search"]
        TA3["Browser · Computer Use · Image Gen"]
    end

    subgraph DO["Deployment & Operations"]
        direction TB
        DO1["Gateway · LaunchAgent · systemd"]
        DO2["Docker / VM Deploy · Tailscale"]
        DO3["Health Endpoints · Multi-Gateway"]
    end

    subgraph IN["Plugin System & Internals"]
        direction LR
        IN1["Plugin Hooks (4)"]
        IN2["Session Router"]
        IN3["HTTP API · Control UI"]
    end

    CH -->|connects| AG
    AG -->|uses| SM
    AG -->|invokes| TA
    SE -.->|enforces| TA
    TA -->|runs on| DO
    TA -.->|built on| IN

    classDef channels fill:#15803d,stroke:#86EFAC,color:#F8FAFC,stroke-width:1.5px
    classDef agents fill:#1d4ed8,stroke:#93C5FD,color:#F8FAFC,stroke-width:1.5px
    classDef sessions fill:#7c3aed,stroke:#C4B5FD,color:#F8FAFC,stroke-width:1.5px
    classDef security fill:#dc2626,stroke:#FCA5A5,color:#F8FAFC,stroke-width:1.5px
    classDef tools fill:#0891b2,stroke:#7DD3FC,color:#F8FAFC,stroke-width:1.5px
    classDef deploy fill:#d97706,stroke:#FCD34D,color:#F8FAFC,stroke-width:1.5px
    classDef internals fill:#334155,stroke:#94A3B8,color:#F8FAFC,stroke-width:1px

    class CH1,CH2,CH3 channels
    class AG1,AG2,AG3 agents
    class SM1,SM2,SM3 sessions
    class SE1,SE2,SE3 security
    class TA1,TA2,TA3 tools
    class DO1,DO2,DO3 deploy
    class IN1,IN2,IN3 internals

Editable source: The diagram is also available as an Excalidraw file — open it at excalidraw.com for a richer, editable version.


Agents & Configuration

How agents are defined, routed, and connected to each other.

Features

FeatureDescriptionConfig KeySinceGuide
Agent definitionsNamed agents with separate workspaces, tools, and model configagents.list[]Phase 1
Agent defaultsShared defaults inherited by all agentsagents.defaultsReference
Multi-agent routingBind channels/peers to specific agents via pattern matchingbindings[]Phase 4
WorkspacesPer-agent directories with SOUL.md and AGENTS.md for behavioral constraintsagents.list[].workspacePhase 3
Agent-to-agent (A2A)Delegate tasks between agents via sessions_sendtools.agentToAgentPhase 4
SubagentsSpawn background sub-tasks within an agent’s sessionagents.defaults.subagentsReference
Subagent limitsControl nesting depth and concurrency of spawned sub-agentssubagents.maxSpawnDepth, maxChildrenPerAgent2026.2.16Reference
LLM providersMulti-provider support (Anthropic, OpenAI, Gemini, OpenRouter, xAI, Groq)agents.list[].providerPhase 1
Per-channel model overridesUse different models for different channelschannels.modelByChannel2026.2.21Reference
SkillsBundled skill packages (coding-agent, github, healthcheck)skills.allowBundledReference
Config includesSplit config across multiple files with $include$includeReference
Config validationValidate config before gateway startupCLI: openclaw config validate2026.3.2Reference
Environment files.env loading from CWD → ~/.openclaw/ → config env block.env filesReference

Use Cases

  • Single agent with search delegation — main agent + isolated search agent (Phase 5 )
  • Multi-channel routing — separate agents per channel with binding patterns (Phase 4 )
  • Workspace isolation — per-agent SOUL.md to enforce different behavioral rules (Phase 3 )
  • Config splitting$include for managing complex multi-agent configs (Reference )

Known Issues

IssueStatusImpactWorkaround
#15176 — Channel bindings regressionOpenBindings to non-default agents brokenNot relevant for recommended 2-agent config (all channels route to main)
#9857sessions_spawn sandbox bugOpenBoth agents sandboxed with per-agent tools breaks spawnRun search agent unsandboxed
#14046 — ANNOUNCE_SKIP timing raceOpen (PR #15383 )A2A sessions_send delivers despite ANNOUNCE_SKIPNone — message is delivered regardless

Channels & Messaging

How external users communicate with agents through messaging platforms.

Features

FeatureDescriptionConfig KeySinceGuide
WhatsAppFull WhatsApp channel with DMs, groups, media, pairingchannels.whatsappPhase 4
SignalSignal channel with DMs, groups, linked device supportchannels.signalPhase 4
Google ChatGoogle Chat via GCP service account, DMs and spaceschannels.googlechatGoogle Chat
TelegramTelegram channel (supported, not detailed in guide)channels.telegramOfficial docs
DiscordDiscord channel (supported, not detailed in guide)channels.discordOfficial docs
SlackSlack channel (supported, not detailed in guide)channels.slackOfficial docs
DM policiesControl who can DM: pairing, allowlist, open, disabledchannels.<ch>.dmPolicyReference
Group policiesControl group access: allowlist, open, disabledchannels.<ch>.groupPolicyReference
Mention gatingRequire @mention before agent responds in groupschannels.<ch>.groups.*.requireMentionReference
Mention patternsRegex patterns for channels without native @mention (Signal)agents.list[].groupChat.mentionPatternsReference
Chat commandsUser-facing /help, /reset, /status, /whoami, /compact, /stopReference
DirectivesSession modifiers: /think, /elevated, /modelReference
Dangerous commandsGated commands: /bash, /config, /debug, /restartcommands.*Reference
Proactive messagingSend messages to any chat via message tool with explicit targetmessage toolReference
Per-channel modelsOverride LLM model per channelchannels.modelByChannel2026.2.21Reference
Signal groups schemaNative groups config block for Signal channelchannels.signal.groups2026.3.13-1Phase 6

Use Cases

  • WhatsApp personal assistant — pairing-based DMs with group mention gating (Phase 4 )
  • Signal secure messaging — privacy-focused channel with regex mention patterns (Phase 4 , Phase 6 )
  • Google Chat workspace bot — GCP service account for team/org use (Google Chat )
  • Morning briefing delivery — cron job with delivery.to for automated group reports (Morning Briefing recipe )
  • Multi-channel routing — different agents respond on different channels (Phase 4 )

Known Issues

IssueStatusImpactWorkaround
#11758requireMention broken on WhatsApp (LID transition)OpenmentionedJids use @lid format vs selfJid @s.whatsapp.net — mention detection always failsNoted in Phase 3 ; use group allowlist instead of mention gating
#14046 — ANNOUNCE_SKIP timing raceOpen (PR #15383 )Cron delivery proceeds despite agent returning ANNOUNCE_SKIPNone

Sessions & Memory

How conversations are scoped, persisted, and how agents remember across sessions.

Features

FeatureDescriptionConfig KeySinceGuide
Session scopingIsolate conversations: main, per-peer, per-channel-peer, per-account-channel-peersession.dmScopeSessions , Reference
Session lifecycleCreation, compaction, pruning of session transcriptsSessions
Session resetClear session via /reset command or CLI/reset command, openclaw sessions resetReference
Session cleanupPrune orphaned sessions and manage disk usageopenclaw sessions cleanup2026.2.23Reference
Two-layer memoryDaily markdown files (auto-loaded today + yesterday) + semantic search for olderagents.defaults.memorySearchPhase 2
Local memory searchOn-device embeddings via node-llama-cpp (no external API)memorySearch.provider: "local"Phase 2
Remote memory searchExternal embedding provider (OpenAI, etc.)memorySearch.provider: "remote"Phase 2
Hybrid searchCombine vector similarity + full-text search with configurable weightsmemorySearch.query.hybridPhase 2
MMR deduplicationMaximal Marginal Relevance to deduplicate similar search resultsmemorySearch.query.hybrid.mmrPhase 2
Temporal decayDown-rank older memory entries with configurable half-lifememorySearch.temporalDecayPhase 2
Memory cacheIn-memory cache for frequent search queriesmemorySearch.cachePhase 2
Pre-compaction flushWrite memories before session compaction to prevent losscompaction.memoryFlushPhase 2
Compaction tuningReserve tokens for response, keep recent context across compactioncompaction.reserveTokens, keepRecentTokens2026.2.21Reference
Post-compaction reindexingImmediate memory reindex after compaction for same-turn searchabilitycompaction.postIndexSync, memorySearch.sync.sessions.postCompactionForce2026.3.12Phase 2
Multimodal memory indexingIndex images and audio in extraPaths via Gemini embeddingsmemorySearch.provider: "gemini" + gemini-embedding-2-preview2026.3.11Phase 2
Memory CLIStatus, index, search from terminalopenclaw memory *Reference

Use Cases

  • Personal assistant with long-term recall — hybrid search with temporal decay (Phase 2 )
  • Knowledge vault — structured memory for research and reference material (Knowledge Vault recipe )
  • Privacy-first memory — local embeddings, no external API calls (Phase 2 )
  • Multi-agent shared context — agents in the same workspace share memory files (Phase 4 )

Known Issues

No major open issues affecting sessions or memory.


Security & Hardening

Layers of protection from sandbox isolation to network controls.

Features

FeatureDescriptionConfig KeySinceGuide
Sandbox modesContainer isolation: off, non-main, allagents.defaults.sandbox.modeReference
Sandbox scopeIsolate per-agent or per-sessionsandbox.scopeReference
Workspace accessControl sandbox filesystem access: none, ro, rwsandbox.workspaceAccessReference
Sandbox tool allow listSeparate tool policy layer for sandboxed sessionstools.sandbox.tools.allowReference
Docker isolationDedicated OS user + Docker sandboxing for agentsPhase 6 , Scripts
VM isolation (macOS)macOS VMs via Lume for host isolationPhase 6
VM isolation (Linux)Linux VMs via Multipass/KVM with Docker insidePhase 6
Tool policies8-layer cascade for tool allow/denytools.*, agents.list[].tools.*Reference
Tool profilesPreset bundles: minimal, coding, messaging, fulltools.profileReference
Elevated modeEscape sandbox for trusted operationstools.elevatedReference
content-guardLLM-based prompt injection scanning at A2A boundaryPlugin config2026.2.1Phase 5 , Extension
channel-guardInbound channel message injection scanningPlugin configExtension
file-guardPath-based file access protection (no_access, read_only, no_delete)Plugin configExtension
network-guardApplication-level domain allowlisting for web_fetch and execPlugin configExtension
command-guardRegex-based dangerous command blocking for exec/bashPlugin configExtension
SOUL.mdAgent behavioral constraints loaded at session startWorkspace filePhase 3
Gateway authToken-based authentication for the gateway APIgateway.authPhase 3
Gateway auth auto-generationGateway generates a secure token if none is configured2026.2.19Phase 3
Secrets managementAudit, configure, apply, and reload secrets without restartopenclaw secrets *2026.2.26Phase 6
Network egress controlOS-level firewall rules to restrict outbound connectionsHardened Multi-Agent , Scripts
Security auditCLI-driven security posture assessmentopenclaw security auditSecurity Audit example
SSRF hardeningBrowser SSRF policy with private network controlsbrowser.ssrfPolicy2026.2.23Phase 3
Exec obfuscation detectionDetect and block obfuscated shell commands2026.2.23Phase 3
Exec safeBin path pinningPin trusted binary paths for exec allowliststools.exec.safeBinTrustedDirs2026.2.22Reference
CSP enforcementContent Security Policy for Control UI2026.2.16Phase 3
Workspace plugin auto-load disabledWorkspace-level plugins no longer auto-loaded (security hardening)2026.3.12Phase 3
Device pairing bootstrap tokensImproved pairing token security for device bootstrap2026.3.12Phase 3

Use Cases

  • Pragmatic single agent — no Docker, guard plugins as the safety net (Pragmatic Single Agent )
  • Hardened multi-agent — Docker sandbox + all five guard plugins + network egress (Hardened Multi-Agent )
  • VM-based isolation — strongest host separation for high-security deployments (Phase 6 )
  • Search agent isolation — content-guard scans search results before they reach the main agent (Phase 5 )
  • Security audit — automated posture check with openclaw security audit --deep (Security Audit example )

Known Issues

IssueStatusImpactWorkaround
#9857sessions_spawn sandbox bugOpenCan’t sandbox both main and search agents with per-agent toolsRun search agent unsandboxed; tool policy provides isolation

Tools & Automation

The 44 built-in tools, cron scheduling, web search, browser, and extended capabilities.

Features

FeatureDescriptionConfig KeySinceGuide
Runtime toolsexec, bash, process — shell execution and process managementgroup:runtimeReference
Filesystem toolsread, write, edit, apply_patch — file operationsgroup:fsReference
Session toolssessions_list, sessions_history, sessions_send, sessions_spawn, sessions_yield, session_statusgroup:sessionssessions_yield: 2026.3.12Reference
Memory toolsmemory_search, memory_get — semantic search and retrievalgroup:memoryReference
Web toolsweb_search, web_fetch — search and fetch web contentgroup:webReference
UI toolsbrowser, canvas — browser automation and artifact renderinggroup:uiReference
Automation toolscron, gateway — scheduling and gateway controlgroup:automationReference
Messaging toolsmessage — send messages to channels with explicit targetsgroup:messagingReference
Node toolsnodes — remote paired device operationsgroup:nodesReference
PDF toolRead and extract content from PDF filespdf tool2026.3.2Reference
Web search providersBrave, Perplexity, xAI (Grok)tools.web.search.providerxAI: 2026.2.9Phase 5
Browser automationPlaywright-based browser with CDP protocolbrowser toolReference
Cron jobs (isolated)Fresh throwaway session per run with optional channel deliverycron.jobs[].sessionTarget: "isolated"Reference
Cron jobs (main)Inject events into agent’s existing main sessioncron.jobs[].sessionTarget: "main"Reference
Cron delivery modesannounce (channel), none (silent), webhook (HTTP POST)cron.jobs[].deliveryReference
Cron webhook triggersExternal triggers for cron jobs via authenticated webhookcron.webhookToken2026.2.16Reference
Cron notifyDeliver cron output to a channel peercron.notify2026.2.16Reference
Image generationGenerate images via OpenRouter API (FLUX, Gemini, GPT)generate_image tool (image-gen plugin)Extension
Computer useVM-based macOS interaction via 7 vm_* toolsvm_* tools (computer-use plugin)Phase 8 , Extension

Use Cases

  • Isolated web search agentweb_search + web_fetch on a dedicated agent, denied on main (Phase 5 )
  • Automated morning briefing — cron job with isolated session + announce delivery (Morning Briefing recipe )
  • Knowledge vault management — filesystem tools + memory for structured research (Knowledge Vault recipe )
  • Image generation in chatgenerate_image tool via image-gen plugin (Extension )
  • VM computer automation — execute tasks in a macOS VM via computer-use plugin (Phase 8 )

Known Issues

IssueStatusImpactWorkaround
#14046 — ANNOUNCE_SKIP timing race in cron deliveryOpen (PR #15383 )Agent returns ANNOUNCE_SKIP but delivery proceeds due to stale historyNone
#6535after_tool_result hook not wiredOpenCan’t hook into tool results for post-processingUse before_tool_call + pre-fetch pattern

Deployment & Operations

Running OpenClaw in production: service management, infrastructure, and day-to-day operations.

Features

FeatureDescriptionConfig KeySinceGuide
Gateway configurationMode, bind address, port, auth, hot-reloadgateway.*Reference
Config hot-reloadAutomatic config reload without restartgateway.reload.mode: "auto"Reference
LaunchAgent (macOS)User-level service management via launchdPhase 6
LaunchDaemon (macOS)System-level hardened service (dedicated user, no shell)Phase 6
systemd (Linux)Linux service management with user or system unitsPhase 6
Docker deploymentContainerized gateway with sandbox supportPhase 6 , Scripts
VM deployment (macOS)Lume / Parallels VMs for strongest host isolationPhase 6
VM deployment (Linux)Multipass / KVM VMs with Docker insidePhase 6
TailscaleRemote access via WireGuard mesh networkPhase 6
Health endpoints/health, /healthz, /ready, /readyz for monitoring2026.3.1Reference
LoggingConfigurable redaction and file size capslogging.*maxFileBytes: 2026.2.22Reference
MigrationMove deployment to new machine (config, creds, memory, channels)Phase 7
Multi-gateway (profiles)Multiple gateway configs via --profile flagMulti-Gateway
Multi-gateway (multi-user)Separate OS users per gateway instanceMulti-Gateway
Multi-gateway (VM variants)One VM per channel for maximum isolationMulti-Gateway
Custom sandbox imagesBuild Docker images with pre-installed toolsCustom Sandbox Images
Diagnosticsopenclaw doctor, openclaw doctor --fixReference
Light context heartbeatReduced context for heartbeat cycles to save tokensagents.*.heartbeat.lightContext2026.3.1Reference
Docker timezone supportOPENCLAW_TZ environment variable for container timezoneOPENCLAW_TZ env var2026.3.13-1Phase 6
Node.js version guardRuntime enforces Node.js 22.16.0+ minimum2026.3.13-1Phase 1

Use Cases

  • Single-machine production — LaunchAgent + Docker sandbox + Tailscale (Phase 6 )
  • Hardened daemon — LaunchDaemon with dedicated user, no login shell (Phase 6 )
  • Multi-user setup — separate OS users per gateway for channel separation (Multi-Gateway )
  • Machine migration — step-by-step procedure for moving everything to new hardware (Phase 7 )
  • Custom tooling — pre-built sandbox images with project-specific packages (Custom Sandbox Images )

Known Issues

No major open issues affecting deployment.


Internals

Plugin System & Architecture

How the gateway works under the hood — the module system, plugin lifecycle, and extension points.

Features

FeatureDescriptionConfig KeySinceGuide
before_tool_call hookIntercept tool calls before execution (used by content-guard, network-guard)Plugin API2026.2.1Reference
message_received hookIntercept incoming channel messages (used by channel-guard)Plugin APIReference
llm_input hookIntercept prompts before sending to modelPlugin API2026.2.16Reference
llm_output hookIntercept model responses after receivingPlugin API2026.2.16Reference
Plugin discoveryWorkspace → user-level → bundled; first match wins~/.openclaw/extensions/Reference
Plugin allow/denyAllowlist + per-plugin enabled flag; both must passplugins.allow, plugins.entries.*.enabledReference
Plugin tool registrationPlugins can register custom tools (image-gen → generate_image, computer-use → vm_*)Plugin APIReference
Plugin configurationPer-plugin config block with model, thresholds, timeoutsplugins.entries.*Reference
Single-process gatewayNode.js process handling all agents, channels, sessions, and UIArchitecture
Session router & queueRoute incoming messages to the correct agent sessionArchitecture , Sessions
Channel connectorsProtocol adapters for each messaging platformArchitecture
WebSocket protocol v3Real-time streaming for Control UI and HTTP APIArchitecture
HTTP APIOpenAI-compatible /v1/chat/completions endpointgateway.*Architecture
Control UIBrowser-based operator interface (Vite + Lit)Architecture
mDNS discoveryLocal network service discoverydiscovery.mdnsReference
Tool systemUnified tool dispatch with policy enforcementArchitecture

Use Cases

  • Custom guard plugin — use before_tool_call hook to intercept and validate tool calls (Extension docs )
  • Input/output loggingllm_input/llm_output hooks for compliance and auditing (Reference )
  • Custom tool plugin — register new tools accessible by agents (e.g., image-gen, computer-use) (Extension docs )
  • API integration — use the HTTP API for programmatic agent interaction (Architecture )

Known Issues

IssueStatusImpactWorkaround
#6535after_tool_result hook not wiredOpenCan’t hook into tool results for post-processing or content scanningUse before_tool_call + pre-fetch pattern for content scanning
Last updated on