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 (6)"]
        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
LM Studio providerBundled local LM Studio provider with onboarding, runtime model discovery, stream preload, and memory-search embeddings for self-hosted OpenAI-compatible modelsmodels.providers.lmstudio2026.4.12Official docs
Self-hosted private networkPer-provider opt-in (allowPrivateNetwork) for trusted self-hosted OpenAI-compatible endpoints on private/loopback addressesmodels.providers.*.request.allowPrivateNetwork2026.4.10Official docs
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
Per-agent thinking/reasoning defaultsConfigure thinking/reasoning/fast mode per agent with automatic fallbackagents.list[].defaults.think2026.3.22Reference
Native image generation modelSet the default model for the built-in image_generate toolagents.defaults.imageGenerationModel.primary2026.3.22Reference
Global default provider parametersSet default provider parameters applied to all agentsagents.defaults.params2026.4.1Reference
System prompt overrideControlled prompt experiments and heartbeat prompt-section controlsagents.defaults.systemPromptOverride2026.4.7Reference
Local model lean mode (experimental)Drop heavyweight default tools (browser, cron, message) to reduce prompt size for weaker local-model setups; has no effect on normal (non-local) pathsagents.defaults.experimental.localModelLean: true2026.4.15Official docs
Config validationValidate config before gateway startupCLI: openclaw config validate2026.3.2Reference
DeepSeek V4 bundled catalogDeepSeek V4 Flash and V4 Pro in bundled model catalog; V4 Flash is the onboarding defaultagents.list[].model2026.4.24Official docs
Bootstrap context injection controlDisable workspace bootstrap file injection for agents that fully own their prompt lifecycleagents.defaults.contextInjection: "never"2026.4.24Reference
Preflight compaction triggerOpt-in preflight that runs local compaction when the active transcript JSONL grows past a byte limit, rotating the file before the next turnagents.defaults.compaction.maxActiveTranscriptBytes2026.4.26Phase 2
Model pricing skipSkip startup OpenRouter and LiteLLM pricing-catalog fetches for offline or restricted-network installs; explicit models.providers.*.pricing values continue to workmodels.pricing.enabled2026.4.27Phase 6
Opt-in follow-up commitmentsHidden extraction of inferred follow-up commitments from conversations, delivered via heartbeat; per-agent/per-channel scopingcommitments.enabled, commitments.maxPerDay2026.4.29Official docs
Thread-bound session spawningthreadBindings.spawnSessions replaces the legacy split subagent/ACP thread-spawn toggles; migrated automatically by openclaw doctor --fixthreadBindings.spawnSessions2026.5.2Official docs
Skip optional bootstrap filesSkip selected optional workspace bootstrap files without disabling required workspace setupagents.defaults.skipOptionalBootstrapFiles2026.5.2Official docs
Tool progress verbositySet channel streaming tool-progress detail: "compact" (default, explain-mode summaries) or "raw" (full command/output for debugging); per-agent overrides supportedagents.defaults.toolProgressDetail2026.5.4Reference
Post-compaction loop guardAbort agent run with compaction_loop_persisted after same (tool, args, result) triple repeats N times following auto-compaction-retry; tunable window sizetools.loopDetection.postCompactionGuard.windowSize2026.5.4Reference
Config schemaPrint generated JSON schema for openclaw.jsonCLI: openclaw config schema2026.3.28Reference
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
QQ BotQQ Bot bundled channel with multi-account, slash commands, reminders, and mediachannels.qqbot2026.3.31Official docs
WhatsApp emoji reactionsAgents can react to incoming WhatsApp messages with emoji; configure with reactionLevelchannels.whatsapp.reactionLevel2026.3.31Official docs
Channel context visibilityFilter supplemental quote/thread/history context by sender allowlist per channelchannels.<ch>.contextVisibility2026.4.5Official docs
WhatsApp native reply quotingConfigurable native reply-thread quoting for WhatsApp conversationschannels.whatsapp.replyToMode2026.4.22Official docs
WhatsApp per-chat system promptsPer-group and per-direct systemPrompt injected as GroupSystemPrompt context; "*" wildcard fallback; account-scoped overrideschannels.whatsapp.groups.<id>.systemPrompt, channels.whatsapp.direct.<id>.systemPrompt2026.4.22Official docs
Tencent YuanbaoTencent Yuanbao channel via external openclaw-plugin-yuanbao plugin; WebSocket bot DMs and group chatschannels.yuanbao2026.4.27Official docs
WhatsApp Channel/Newsletter targetsSend outbound messages to WhatsApp Channel or Newsletter feeds using @newsletter target syntaxchannels.whatsapp@newsletter target2026.5.2Official docs
Streaming progress draftsUnified streaming.mode: "progress" with auto-labelled draft previews and shared streaming.progress.* config across Discord, Telegram, Matrix, Slack, and Microsoft Teamschannels.<ch>.streaming.mode: "progress"2026.5.3Official docs
Streaming command-text controlHide exec/command text in preview progress lines ("status") while keeping full command visible in raw progress mode; separate preview and progress controlsstreaming.preview.commandText, streaming.progress.commandText2026.5.4Official docs

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
QMD cross-agent collectionsOpt specific agents into searching another agent’s session history by namememorySearch.qmd.extraCollections2026.3.31Phase 2
Amazon Bedrock embeddingsMemory embeddings via Titan, Cohere, Nova, TwelveLabs; AWS credential-chain auto-detectionmemorySearch.provider: "bedrock"2026.4.5Phase 2
GitHub Copilot embeddingsMemory search embedding provider using GitHub Copilot transport with token refresh and remote override supportmemorySearch.provider: "copilot"2026.4.15Phase 2
LanceDB cloud storagememory-lancedb backend supports remote object storage so durable memory indexes can run on cloud storage instead of local diskmemory-lancedb plugin2026.4.15Official docs
Memory dreaming (experimental)Background promotion of daily-log content into durable MEMORY.md; three phases (light, deep, REM)dreaming.enabled, dreaming.frequency2026.4.5Phase 2
Dreaming aging controlsTune recall decay and promotion decisionsdreaming.recencyHalfLifeDays, dreaming.maxAgeDays2026.4.5Phase 2
Dreaming separate storage (default)Dreaming phase blocks (## Light Sleep, ## REM Sleep) stored in memory/dreaming/{phase}/YYYY-MM-DD.md instead of inline in daily memory files — prevents daily notes from being dominated by structured candidate output; opt out by setting storage.mode: "inline"plugins.entries.memory-core.config.dreaming.storage.mode2026.4.15Phase 2
Dreaming REM toolingPreview and explain promotion decisions; replay-safe rerunsopenclaw memory rem-harness, promote-explain2026.4.5Phase 2
Dreaming REM historical backfillReplay old daily notes into Dreams and durable memory via rem-harness --pathopenclaw memory rem-harness --path2026.4.9Phase 2
Dreaming diary viewStructured diary view in Control UI with timeline, backfill/reset controls, and traceable summariesControl UI2026.4.9Phase 2
Dreaming ChatGPT import + memory-wikiImport ChatGPT conversation history as source chats; Imported Insights and Memory Palace diary subtabs for inspecting compiled wiki pages and source pagesControl UI2026.4.11Phase 2
Active MemoryOptional plugin that runs a dedicated memory sub-agent before each reply to automatically surface relevant context, preferences, and past details without requiring explicit “remember this” prompts; configurable message/recent/full context modes with /verbose inspectionplugins.entries.active-memory2026.4.10Official docs
Compaction notify userControl whether the “🧹 Compacting context…” notice is shownagents.defaults.compaction.notifyUser2026.4.2Phase 2
Pluggable compaction providerReplace built-in LLM summarization pipeline via plugin registryagents.defaults.compaction.provider2026.4.7Phase 2
Memory CLIStatus, index, search from terminalopenclaw memory *Reference
Local embedding context sizeTune local embedding context window for constrained hosts without patching memory hostmemorySearch.local.contextSize2026.4.23Phase 2
Dreaming heartbeat-independentDreaming runs as an isolated lightweight agent turn regardless of whether heartbeat is enabled or what heartbeat.activeHours allowsdreaming.enabled2026.4.23Phase 2
Hybrid search raw scoresvectorScore and textScore exposed alongside combined score on hybrid results for retrieval contribution inspectionmemorySearch.query.hybrid2026.4.24Phase 2
Asymmetric embedding configSeparate queryInputType and documentInputType for OpenAI-compatible providers that use different input types for queries vs. documents (e.g., query vs. passage)memorySearch.queryInputType, memorySearch.documentInputType2026.4.26Phase 2
Dream Diary model overrideDedicated dreaming.model knob for Dream Diary narrative subagents to avoid paid conversation models during memory housekeepingdreaming.model2026.4.26Phase 2

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
Exec inline eval hardeningRequire fresh approval for inline interpreter eval (python -c, node -e, etc.)tools.exec.strictInlineEval2026.3.22Phase 3
Marketplace manifest securityRemote marketplace manifests validated to prevent install-path expansion outside repo2026.3.22Phase 3
Exec env injection blockingBlock proxy, TLS, Docker endpoint, and package index env var overrides in host exec2026.3.31Phase 3
Plugin install fail-closedCritical dangerous-code findings block plugin/skill install by default; override with --dangerously-force-unsafe-install2026.3.31Phase 3
Gateway auth hardeningtrusted-proxy rejects mixed shared-token configs; local-direct fallback requires configured tokengateway.auth2026.3.31Phase 6
Runtime event trust hardeningBackground notifyOnExit, ACP relays, and wake-hook payloads marked untrusted so they cannot inject System: text2026.4.7Phase 3
Plugin archive integrityClawHub downloads verified against version metadata SHA-256; fails closed on missing or malformed integrity data2026.4.7Phase 3
Gateway config exec write lockmodel-facing config.apply/config.patch cannot change safeBins, safeBinTrustedDirs, or strictInlineEval (2026.4.7); extended in 2026.4.14 to block all flags enumerated by openclaw security audit2026.4.7Phase 3
Dotenv runtime-control env blockingWorkspace .env cannot override runtime-control or browser-control env vars2026.4.9Phase 3
Exec approval secret redactionSecrets are redacted in exec approval prompts so inline approval review cannot leak credential material2026.4.15Phase 3
Gateway auth per-request resolutionGateway bearer resolved per-request on all HTTP paths; token rotation via secrets.reload or config hot-reload takes effect immediately without restart2026.4.15Phase 3
Workspace file symlink hardeningagents.files API routes through fs-safe helpers; symlink aliases for agent files rejected; real-path resolved from file descriptor to prevent swap-between-open-and-realpath attacks2026.4.15Phase 3
Dotenv OPENCLAW_* env blockingAll OPENCLAW_* keys blocked from untrusted workspace .env files; fails closed for new runtime-control variables2026.4.20Phase 3
Device pairing scope restrictionNon-admin paired-device sessions restricted to own device’s pairing actions; cannot enumerate or approve other devices2026.4.20Phase 3
Gateway tool mutation guard (full)model-facing config.patch/config.apply cannot rewrite operator-trusted paths or bypass the guard via per-agent agents.list[] overrides2026.4.20Phase 3
WebSocket broadcast authoperator.read required for chat, agent, and tool-result event frames; pairing-scoped sessions no longer receive session chat content passively2026.4.20Phase 3
MCP stdio env injection blockedInterpreter-startup env keys (NODE_OPTIONS, etc.) blocked for stdio MCP servers2026.4.20Phase 3
enforceOwnerForCommands bypass fixOwner identity required for owner-enforced commands; permissive allowFrom wildcards or empty ownerAllowFrom no longer bypass owner checks2026.4.21Phase 3
Plugin update integrity fail-closedPinned plugin/hook-pack updates abort when exact integrity hash drift is detected; drift details exposed via openclaw update --json2026.4.22Phase 3
Control UI config endpoint auth/__openclaw/control-ui-config.json requires authenticated access when gateway.auth enabledgateway.auth2026.4.22Phase 3
WhatsApp/group-chat prompt injection fencingContact names, vCard fields, location labels, group names, and participant labels rendered through fenced untrusted metadata JSON instead of inline message body2026.4.23Phase 3
Gateway config write lock (allowlist)Agent-driven config.apply/config.patch fail closed against a narrow allowlist of operator-tunable paths (prompt, model, mention-gating) instead of a hand-maintained denylist2026.4.23Phase 3
Exec-approval explicit enablementChat exec-approval gates require explicit enablement; auto-approval from config or owner allowlists alone is no longer sufficient2026.4.23Phase 3
MCP owner-tool privilege escalation fixACPX OpenClaw tools bridge blocked from listing or invoking owner-only tools such as cron via non-owner MCP callers2026.4.23Phase 3
Browser SSRF policy in sandboxed sessionsResolved browser.ssrfPolicy passed into sandbox browser bridges; private-network opt-ins now cover sandboxed browser navigationbrowser.ssrfPolicy2026.4.24Phase 3
Device token scope containmentPairing-only sessions cannot rotate or revoke higher-scope operator tokens; token rotation and revocation are caller-scope contained2026.4.25Phase 3
Session transcript redactionConfigured redactSensitive patterns now also applied to persisted session transcript JSONL so secrets no longer appear in the clear in transcript fileslogging.redactSensitive2026.4.25Phase 3
Outbound proxy routingOperator-managed opt-in proxy routing via proxy.enabled + proxy.proxyUrl/OPENCLAW_PROXY_URL; strict http:// forward-proxy validation, loopback-only gateway bypassproxy.enabled, proxy.proxyUrl2026.4.26Phase 6
LaunchAgent secrets hardeningManaged LaunchAgent/service installations load secrets from owner-only env files instead of plist EnvironmentVariables; secrets no longer visible in world-readable plist metadata2026.4.27Phase 6
Media MIME sanitizationMedia-understanding MIME type sanitization is end-anchored; parameterized MIME values, malformed whitespace, and suffix payloads are rejected before file-context handling2026.4.27Phase 3
Timing-safe credential comparisonCredential bytes compared with padded timing-safe buffers instead of hashing before equality checks, preventing timing side-channel attacks2026.4.29Phase 3
Debug-log argument sanitizationDebug log arguments sanitized before writing to console.* to prevent log forging via gateway payload fields2026.4.29Phase 3
Workspace COMSPEC/CLOUDSDK_PYTHON blockingCOMSPEC and CLOUDSDK_PYTHON blocked from workspace .env to prevent Windows shell and Python interpreter redirection2026.4.29Phase 3
Tool profile restriction narrowingtools.exec/tools.fs config sections no longer implicitly widen restrictive profiles (messaging, minimal); explicit alsoAllow entries required; startup warning on affected configstools.alsoAllow2026.4.29Reference
Workspace state-directory env override blockedWorkspace .env cannot override the gateway state-directory path2026.5.2Phase 3
Gateway env file operator secrets preservationOperator-added secrets in the Gateway env file preserved across re-stage; only OpenClaw-managed keys are cleared2026.5.3Phase 6
Docker gateway container hardeningBundled docker-compose.yml drops NET_RAW and NET_ADMIN capabilities and enables no-new-privileges for the gateway containerdocker-compose.yml2026.5.5Phase 6

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, x_search — 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 providersDuckDuckGo and other bundled providers, plus official external providers such as Brave and Perplexitytools.web.search.provider, plugins.entries.<provider>.config.webSearchExa/Tavily/Firecrawl: 2026.3.22; SearXNG: 2026.4.1Phase 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
Cron per-job tool allowlistRestrict which tools a cron job can use via --tools flagopenclaw cron --tools2026.4.1Reference
Cron state/definition splitJob definitions in cron/jobs.json (stable, git-trackable); runtime execution state in cron/jobs-state.json (ephemeral, auto-rebuilt)2026.4.20Phase 7
Background task flowsUnified background-run control plane with openclaw flows list|show|cancelopenclaw flows2026.3.31Reference
Image generation (native)Built-in image generation via image_generate toolagents.defaults.imageGenerationModel.primary2026.3.22Reference
Image generation (plugin)Generate images via OpenRouter API (FLUX, Gemini, GPT, MiniMax image-01)generate_image tool (image-gen plugin)— (MiniMax: 2026.3.28)Extension
Video generation (native)Built-in video_generate tool; providers include xAI, Alibaba Wan, Runwayvideo_generate tool2026.4.5Official docs
Music generation (native)Built-in music_generate tool; bundled Google Lyria and MiniMax providers; async deliverymusic_generate tool2026.4.5Official docs
ComfyUI workflowsBundled comfy plugin for local/cloud ComfyUI; image, video, and music generationcomfy plugin2026.4.5Official docs
Computer useVM-based macOS interaction via 7 vm_* toolsvm_* tools (computer-use plugin)Phase 8 , Extension
openclaw inferFirst-class CLI hub for provider-backed inference workflows: model, media, web, and embedding tasksopenclaw infer2026.4.7Official docs
Webhook ingress pluginExternal automation creates and drives bound TaskFlows via per-route shared-secret endpointsplugins.entries.webhook-ingress2026.4.7Official docs
Google MeetBundled participant plugin — personal Google auth, Chrome/Twilio realtime sessions, paired-node Chrome support, artifact/attendance exports, googlemeet recover-tab recoveryplugins.entries.google-meet2026.4.24Official docs
Browser coordinate clicksClick at viewport coordinates for managed and existing-session browser automationbrowser tool2026.4.24Reference
Browser action timeoutConfigurable per-action timeout with 60 s default so long waits do not fail at the transport boundarybrowser.actionTimeoutMs2026.4.24Reference
Browser per-profile headlessOverride headless mode per locally launched browser profilebrowser.profiles.<name>.headless2026.4.24Official docs
Talk WebRTC voiceBrowser WebRTC realtime voice sessions in Control UI backed by OpenAI Realtime; openclaw_agent_consult handoff for tool-backed answers2026.4.24Official docs
Config migrationImport Claude Code, Claude Desktop, and Hermes configurations (instructions, MCP servers, skills, prompts, credentials) with dry-run preview and pre-migration backupCLI: openclaw migrate2026.4.26Official docs
Docker sandbox GPU passthroughOpt-in sandbox.docker.gpus passthrough for Docker sandbox containers when the host Docker runtime supports --gpussandbox.docker.gpus2026.4.27Custom Sandbox Images
Cron failure alert for skipped jobsAlert on persistently skipped jobs without counting skips as execution errors or affecting retry backoffcron.jobs[].failureAlert.includeSkipped / openclaw cron edit --failure-alert-include-skipped2026.4.27Reference
Grok 4.3 bundled catalogGrok 4.3 added to the bundled xAI catalog and set as the xAI default chat modelagents.list[].model2026.5.2Official docs
File-transfer pluginBundled plugin with file_fetch, dir_list, dir_fetch, and file_write for binary file operations on paired nodes; path policy under plugins.entries.file-transfer.config.nodes; symlinks refused by default; 16 MB per-round-trip ceilingfile_fetch, dir_list, dir_fetch, file_write tools2026.5.3Official docs
/steer commandQueue-independent steering of the active current-session run without starting a new turnCLI: /steer <message>2026.5.3Official docs
/side command alias/side as a text and native slash-command alias for /btw side questionsCLI: /side <message>2026.5.3Official docs

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.14+ minimum (Node 24 recommended)2026.3.13-1 (lowered 2026.3.24)Phase 1
Gateway diagnostics exportSupport-ready diagnostics export with sanitized logs, status, health, config, and stability snapshotsCLI: openclaw diagnostics2026.4.22Official docs
OTEL diagnosticsOpt-in OpenTelemetry span export for runs, model calls, and tool executions; content capture disabled by defaultdiagnostics.otel.endpoint2026.4.24Official docs
Matrix self device verificationFull cross-signing identity trust for self-device verification via CLICLI: openclaw matrix verify self2026.4.24Official docs
Node pairing auto-approve CIDRsDisabled-by-default auto-approval for first-time node pairing from explicit trusted CIDRs; all upgrade flows remain manualgateway.nodes.pairing.autoApproveCidrs2026.4.24Official docs
Auto-update kill switchOPENCLAW_NO_AUTO_UPDATE=1 disables background package auto-updates for deliberate version holds during incident recovery, without editing configOPENCLAW_NO_AUTO_UPDATE env var2026.4.26Phase 6
Matrix E2EE setupOne-command Matrix encryption setup, recovery bootstrap, and verification status via openclaw matrix encryption setupCLI: openclaw matrix encryption setup2026.4.26Official docs
Node stale entry removalRemove stale gateway-owned node pairing records without hand-editing state filesCLI: openclaw nodes remove --node <id|name|ip>2026.4.26Official docs
Gateway restart flagsopenclaw gateway restart --force and --wait <duration> for immediate restarts or timed drain waitsCLI: openclaw gateway restart --force/--wait2026.5.2Official docs
Gateway config fail-closedInvalid config now causes gateway startup and hot-reload to fail closed; openclaw doctor --fix owns last-known-good repair instead of auto-restore on load2026.5.3Phase 6
OPENCLAW_SKIP_ONBOARDINGSkip the interactive onboarding wizard for automated Docker installs while still applying gateway defaultsOPENCLAW_SKIP_ONBOARDING=1 env var2026.4.29Phase 6
Models auth listInspect saved per-agent auth profiles without dumping secrets; filterable by providerCLI: openclaw models auth list [--provider <id>] [--json]2026.5.4Reference
Sessions list paginationopenclaw sessions capped at 100 rows by default with --limit <n|all> override to control output size on large storesCLI: openclaw sessions list --limit2026.5.4Reference

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_dispatch hookIntercept inbound messages before routing with canonical metadataPlugin API2026.3.24Reference
before_tool_call hookIntercept tool calls before execution; supports async requireApproval to pause for user confirmation (used by content-guard, network-guard)Plugin API2026.2.1 (requireApproval: 2026.3.28)Reference
before_agent_reply hookShort-circuit the LLM with synthetic replies after inline actionsPlugin API2026.4.2Reference
before_agent_finalize hookIntercept and modify agent replies after generation but before finalization and deliveryPlugin API2026.4.25Reference
message_received hookObserve incoming channel messages as a fire-and-forget notificationPlugin APIReference
llm_input hookIntercept prompts before sending to modelPlugin API2026.2.16Reference
llm_output hookIntercept model responses after receivingPlugin API2026.2.16Reference
Plugin SDKPublic plugin SDK surface via openclaw/plugin-sdk/* subpaths (openclaw/extension-api removed)openclaw/plugin-sdk/*2026.3.22Reference
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 startup declarationExplicit activation.onStartup metadata in plugin manifests so only plugins that intentionally register startup-time surfaces are loaded at bootPlugin manifest2026.4.27Official docs
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
Control UI Model Auth statusOverview card showing OAuth token health and provider rate-limit pressure; attention callouts when tokens are expiring or expired; backed by models.authStatus gateway method (cached 60s, credentials stripped)Control UI overview2026.4.15Official docs
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