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
| Feature | Description | Config Key | Since | Guide |
|---|---|---|---|---|
| Agent definitions | Named agents with separate workspaces, tools, and model config | agents.list[] | — | Phase 1 |
| Agent defaults | Shared defaults inherited by all agents | agents.defaults | — | Reference |
| Multi-agent routing | Bind channels/peers to specific agents via pattern matching | bindings[] | — | Phase 4 |
| Workspaces | Per-agent directories with SOUL.md and AGENTS.md for behavioral constraints | agents.list[].workspace | — | Phase 3 |
| Agent-to-agent (A2A) | Delegate tasks between agents via sessions_send | tools.agentToAgent | — | Phase 4 |
| Subagents | Spawn background sub-tasks within an agent’s session | agents.defaults.subagents | — | Reference |
| Subagent limits | Control nesting depth and concurrency of spawned sub-agents | subagents.maxSpawnDepth, maxChildrenPerAgent | 2026.2.16 | Reference |
| LLM providers | Multi-provider support (Anthropic, OpenAI, Gemini, OpenRouter, xAI, Groq) | agents.list[].provider | — | Phase 1 |
| Per-channel model overrides | Use different models for different channels | channels.modelByChannel | 2026.2.21 | Reference |
| Skills | Bundled skill packages (coding-agent, github, healthcheck) | skills.allowBundled | — | Reference |
| Config includes | Split config across multiple files with $include | $include | — | Reference |
| Config validation | Validate config before gateway startup | CLI: openclaw config validate | 2026.3.2 | Reference |
| Environment files | .env loading from CWD → ~/.openclaw/ → config env block | .env files | — | Reference |
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 —
$includefor managing complex multi-agent configs (Reference )
Known Issues
| Issue | Status | Impact | Workaround |
|---|---|---|---|
| #15176 — Channel bindings regression | Open | Bindings to non-default agents broken | Not relevant for recommended 2-agent config (all channels route to main) |
#9857
— sessions_spawn sandbox bug | Open | Both agents sandboxed with per-agent tools breaks spawn | Run search agent unsandboxed |
| #14046 — ANNOUNCE_SKIP timing race | Open (PR #15383 ) | A2A sessions_send delivers despite ANNOUNCE_SKIP | None — message is delivered regardless |
Channels & Messaging
How external users communicate with agents through messaging platforms.
Features
| Feature | Description | Config Key | Since | Guide |
|---|---|---|---|---|
| Full WhatsApp channel with DMs, groups, media, pairing | channels.whatsapp | — | Phase 4 | |
| Signal | Signal channel with DMs, groups, linked device support | channels.signal | — | Phase 4 |
| Google Chat | Google Chat via GCP service account, DMs and spaces | channels.googlechat | — | Google Chat |
| Telegram | Telegram channel (supported, not detailed in guide) | channels.telegram | — | Official docs |
| Discord | Discord channel (supported, not detailed in guide) | channels.discord | — | Official docs |
| Slack | Slack channel (supported, not detailed in guide) | channels.slack | — | Official docs |
| DM policies | Control who can DM: pairing, allowlist, open, disabled | channels.<ch>.dmPolicy | — | Reference |
| Group policies | Control group access: allowlist, open, disabled | channels.<ch>.groupPolicy | — | Reference |
| Mention gating | Require @mention before agent responds in groups | channels.<ch>.groups.*.requireMention | — | Reference |
| Mention patterns | Regex patterns for channels without native @mention (Signal) | agents.list[].groupChat.mentionPatterns | — | Reference |
| Chat commands | User-facing /help, /reset, /status, /whoami, /compact, /stop | — | — | Reference |
| Directives | Session modifiers: /think, /elevated, /model | — | — | Reference |
| Dangerous commands | Gated commands: /bash, /config, /debug, /restart | commands.* | — | Reference |
| Proactive messaging | Send messages to any chat via message tool with explicit target | message tool | — | Reference |
| Per-channel models | Override LLM model per channel | channels.modelByChannel | 2026.2.21 | Reference |
| Signal groups schema | Native groups config block for Signal channel | channels.signal.groups | 2026.3.13-1 | Phase 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.tofor automated group reports (Morning Briefing recipe ) - Multi-channel routing — different agents respond on different channels (Phase 4 )
Known Issues
| Issue | Status | Impact | Workaround |
|---|---|---|---|
#11758
— requireMention broken on WhatsApp (LID transition) | Open | mentionedJids use @lid format vs selfJid @s.whatsapp.net — mention detection always fails | Noted in Phase 3 ; use group allowlist instead of mention gating |
| #14046 — ANNOUNCE_SKIP timing race | Open (PR #15383 ) | Cron delivery proceeds despite agent returning ANNOUNCE_SKIP | None |
Sessions & Memory
How conversations are scoped, persisted, and how agents remember across sessions.
Features
| Feature | Description | Config Key | Since | Guide |
|---|---|---|---|---|
| Session scoping | Isolate conversations: main, per-peer, per-channel-peer, per-account-channel-peer | session.dmScope | — | Sessions , Reference |
| Session lifecycle | Creation, compaction, pruning of session transcripts | — | — | Sessions |
| Session reset | Clear session via /reset command or CLI | /reset command, openclaw sessions reset | — | Reference |
| Session cleanup | Prune orphaned sessions and manage disk usage | openclaw sessions cleanup | 2026.2.23 | Reference |
| Two-layer memory | Daily markdown files (auto-loaded today + yesterday) + semantic search for older | agents.defaults.memorySearch | — | Phase 2 |
| Local memory search | On-device embeddings via node-llama-cpp (no external API) | memorySearch.provider: "local" | — | Phase 2 |
| Remote memory search | External embedding provider (OpenAI, etc.) | memorySearch.provider: "remote" | — | Phase 2 |
| Hybrid search | Combine vector similarity + full-text search with configurable weights | memorySearch.query.hybrid | — | Phase 2 |
| MMR deduplication | Maximal Marginal Relevance to deduplicate similar search results | memorySearch.query.hybrid.mmr | — | Phase 2 |
| Temporal decay | Down-rank older memory entries with configurable half-life | memorySearch.temporalDecay | — | Phase 2 |
| Memory cache | In-memory cache for frequent search queries | memorySearch.cache | — | Phase 2 |
| Pre-compaction flush | Write memories before session compaction to prevent loss | compaction.memoryFlush | — | Phase 2 |
| Compaction tuning | Reserve tokens for response, keep recent context across compaction | compaction.reserveTokens, keepRecentTokens | 2026.2.21 | Reference |
| Post-compaction reindexing | Immediate memory reindex after compaction for same-turn searchability | compaction.postIndexSync, memorySearch.sync.sessions.postCompactionForce | 2026.3.12 | Phase 2 |
| Multimodal memory indexing | Index images and audio in extraPaths via Gemini embeddings | memorySearch.provider: "gemini" + gemini-embedding-2-preview | 2026.3.11 | Phase 2 |
| Memory CLI | Status, index, search from terminal | openclaw 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
| Feature | Description | Config Key | Since | Guide |
|---|---|---|---|---|
| Sandbox modes | Container isolation: off, non-main, all | agents.defaults.sandbox.mode | — | Reference |
| Sandbox scope | Isolate per-agent or per-session | sandbox.scope | — | Reference |
| Workspace access | Control sandbox filesystem access: none, ro, rw | sandbox.workspaceAccess | — | Reference |
| Sandbox tool allow list | Separate tool policy layer for sandboxed sessions | tools.sandbox.tools.allow | — | Reference |
| Docker isolation | Dedicated OS user + Docker sandboxing for agents | — | — | Phase 6 , Scripts |
| VM isolation (macOS) | macOS VMs via Lume for host isolation | — | — | Phase 6 |
| VM isolation (Linux) | Linux VMs via Multipass/KVM with Docker inside | — | — | Phase 6 |
| Tool policies | 8-layer cascade for tool allow/deny | tools.*, agents.list[].tools.* | — | Reference |
| Tool profiles | Preset bundles: minimal, coding, messaging, full | tools.profile | — | Reference |
| Elevated mode | Escape sandbox for trusted operations | tools.elevated | — | Reference |
| content-guard | LLM-based prompt injection scanning at A2A boundary | Plugin config | 2026.2.1 | Phase 5 , Extension |
| channel-guard | Inbound channel message injection scanning | Plugin config | — | Extension |
| file-guard | Path-based file access protection (no_access, read_only, no_delete) | Plugin config | — | Extension |
| network-guard | Application-level domain allowlisting for web_fetch and exec | Plugin config | — | Extension |
| command-guard | Regex-based dangerous command blocking for exec/bash | Plugin config | — | Extension |
| SOUL.md | Agent behavioral constraints loaded at session start | Workspace file | — | Phase 3 |
| Gateway auth | Token-based authentication for the gateway API | gateway.auth | — | Phase 3 |
| Gateway auth auto-generation | Gateway generates a secure token if none is configured | — | 2026.2.19 | Phase 3 |
| Secrets management | Audit, configure, apply, and reload secrets without restart | openclaw secrets * | 2026.2.26 | Phase 6 |
| Network egress control | OS-level firewall rules to restrict outbound connections | — | — | Hardened Multi-Agent , Scripts |
| Security audit | CLI-driven security posture assessment | openclaw security audit | — | Security Audit example |
| SSRF hardening | Browser SSRF policy with private network controls | browser.ssrfPolicy | 2026.2.23 | Phase 3 |
| Exec obfuscation detection | Detect and block obfuscated shell commands | — | 2026.2.23 | Phase 3 |
| Exec safeBin path pinning | Pin trusted binary paths for exec allowlists | tools.exec.safeBinTrustedDirs | 2026.2.22 | Reference |
| CSP enforcement | Content Security Policy for Control UI | — | 2026.2.16 | Phase 3 |
| Workspace plugin auto-load disabled | Workspace-level plugins no longer auto-loaded (security hardening) | — | 2026.3.12 | Phase 3 |
| Device pairing bootstrap tokens | Improved pairing token security for device bootstrap | — | 2026.3.12 | Phase 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
| Issue | Status | Impact | Workaround |
|---|---|---|---|
#9857
— sessions_spawn sandbox bug | Open | Can’t sandbox both main and search agents with per-agent tools | Run search agent unsandboxed; tool policy provides isolation |
Tools & Automation
The 44 built-in tools, cron scheduling, web search, browser, and extended capabilities.
Features
| Feature | Description | Config Key | Since | Guide |
|---|---|---|---|---|
| Runtime tools | exec, bash, process — shell execution and process management | group:runtime | — | Reference |
| Filesystem tools | read, write, edit, apply_patch — file operations | group:fs | — | Reference |
| Session tools | sessions_list, sessions_history, sessions_send, sessions_spawn, sessions_yield, session_status | group:sessions | sessions_yield: 2026.3.12 | Reference |
| Memory tools | memory_search, memory_get — semantic search and retrieval | group:memory | — | Reference |
| Web tools | web_search, web_fetch — search and fetch web content | group:web | — | Reference |
| UI tools | browser, canvas — browser automation and artifact rendering | group:ui | — | Reference |
| Automation tools | cron, gateway — scheduling and gateway control | group:automation | — | Reference |
| Messaging tools | message — send messages to channels with explicit targets | group:messaging | — | Reference |
| Node tools | nodes — remote paired device operations | group:nodes | — | Reference |
| PDF tool | Read and extract content from PDF files | pdf tool | 2026.3.2 | Reference |
| Web search providers | Brave, Perplexity, xAI (Grok) | tools.web.search.provider | xAI: 2026.2.9 | Phase 5 |
| Browser automation | Playwright-based browser with CDP protocol | browser tool | — | Reference |
| Cron jobs (isolated) | Fresh throwaway session per run with optional channel delivery | cron.jobs[].sessionTarget: "isolated" | — | Reference |
| Cron jobs (main) | Inject events into agent’s existing main session | cron.jobs[].sessionTarget: "main" | — | Reference |
| Cron delivery modes | announce (channel), none (silent), webhook (HTTP POST) | cron.jobs[].delivery | — | Reference |
| Cron webhook triggers | External triggers for cron jobs via authenticated webhook | cron.webhookToken | 2026.2.16 | Reference |
| Cron notify | Deliver cron output to a channel peer | cron.notify | 2026.2.16 | Reference |
| Image generation | Generate images via OpenRouter API (FLUX, Gemini, GPT) | generate_image tool (image-gen plugin) | — | Extension |
| Computer use | VM-based macOS interaction via 7 vm_* tools | vm_* tools (computer-use plugin) | — | Phase 8 , Extension |
Use Cases
- Isolated web search agent —
web_search+web_fetchon 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 chat —
generate_imagetool via image-gen plugin (Extension ) - VM computer automation — execute tasks in a macOS VM via computer-use plugin (Phase 8 )
Known Issues
| Issue | Status | Impact | Workaround |
|---|---|---|---|
| #14046 — ANNOUNCE_SKIP timing race in cron delivery | Open (PR #15383 ) | Agent returns ANNOUNCE_SKIP but delivery proceeds due to stale history | None |
#6535
— after_tool_result hook not wired | Open | Can’t hook into tool results for post-processing | Use before_tool_call + pre-fetch pattern |
Deployment & Operations
Running OpenClaw in production: service management, infrastructure, and day-to-day operations.
Features
| Feature | Description | Config Key | Since | Guide |
|---|---|---|---|---|
| Gateway configuration | Mode, bind address, port, auth, hot-reload | gateway.* | — | Reference |
| Config hot-reload | Automatic config reload without restart | gateway.reload.mode: "auto" | — | Reference |
| LaunchAgent (macOS) | User-level service management via launchd | — | — | Phase 6 |
| LaunchDaemon (macOS) | System-level hardened service (dedicated user, no shell) | — | — | Phase 6 |
| systemd (Linux) | Linux service management with user or system units | — | — | Phase 6 |
| Docker deployment | Containerized gateway with sandbox support | — | — | Phase 6 , Scripts |
| VM deployment (macOS) | Lume / Parallels VMs for strongest host isolation | — | — | Phase 6 |
| VM deployment (Linux) | Multipass / KVM VMs with Docker inside | — | — | Phase 6 |
| Tailscale | Remote access via WireGuard mesh network | — | — | Phase 6 |
| Health endpoints | /health, /healthz, /ready, /readyz for monitoring | — | 2026.3.1 | Reference |
| Logging | Configurable redaction and file size caps | logging.* | maxFileBytes: 2026.2.22 | Reference |
| Migration | Move deployment to new machine (config, creds, memory, channels) | — | — | Phase 7 |
| Multi-gateway (profiles) | Multiple gateway configs via --profile flag | — | — | Multi-Gateway |
| Multi-gateway (multi-user) | Separate OS users per gateway instance | — | — | Multi-Gateway |
| Multi-gateway (VM variants) | One VM per channel for maximum isolation | — | — | Multi-Gateway |
| Custom sandbox images | Build Docker images with pre-installed tools | — | — | Custom Sandbox Images |
| Diagnostics | openclaw doctor, openclaw doctor --fix | — | — | Reference |
| Light context heartbeat | Reduced context for heartbeat cycles to save tokens | agents.*.heartbeat.lightContext | 2026.3.1 | Reference |
| Docker timezone support | OPENCLAW_TZ environment variable for container timezone | OPENCLAW_TZ env var | 2026.3.13-1 | Phase 6 |
| Node.js version guard | Runtime enforces Node.js 22.16.0+ minimum | — | 2026.3.13-1 | Phase 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
| Feature | Description | Config Key | Since | Guide |
|---|---|---|---|---|
before_tool_call hook | Intercept tool calls before execution (used by content-guard, network-guard) | Plugin API | 2026.2.1 | Reference |
message_received hook | Intercept incoming channel messages (used by channel-guard) | Plugin API | — | Reference |
llm_input hook | Intercept prompts before sending to model | Plugin API | 2026.2.16 | Reference |
llm_output hook | Intercept model responses after receiving | Plugin API | 2026.2.16 | Reference |
| Plugin discovery | Workspace → user-level → bundled; first match wins | ~/.openclaw/extensions/ | — | Reference |
| Plugin allow/deny | Allowlist + per-plugin enabled flag; both must pass | plugins.allow, plugins.entries.*.enabled | — | Reference |
| Plugin tool registration | Plugins can register custom tools (image-gen → generate_image, computer-use → vm_*) | Plugin API | — | Reference |
| Plugin configuration | Per-plugin config block with model, thresholds, timeouts | plugins.entries.* | — | Reference |
| Single-process gateway | Node.js process handling all agents, channels, sessions, and UI | — | — | Architecture |
| Session router & queue | Route incoming messages to the correct agent session | — | — | Architecture , Sessions |
| Channel connectors | Protocol adapters for each messaging platform | — | — | Architecture |
| WebSocket protocol v3 | Real-time streaming for Control UI and HTTP API | — | — | Architecture |
| HTTP API | OpenAI-compatible /v1/chat/completions endpoint | gateway.* | — | Architecture |
| Control UI | Browser-based operator interface (Vite + Lit) | — | — | Architecture |
| mDNS discovery | Local network service discovery | discovery.mdns | — | Reference |
| Tool system | Unified tool dispatch with policy enforcement | — | — | Architecture |
Use Cases
- Custom guard plugin — use
before_tool_callhook to intercept and validate tool calls (Extension docs ) - Input/output logging —
llm_input/llm_outputhooks 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
| Issue | Status | Impact | Workaround |
|---|---|---|---|
#6535
— after_tool_result hook not wired | Open | Can’t hook into tool results for post-processing or content scanning | Use before_tool_call + pre-fetch pattern for content scanning |