This is the complete OpenClaw fieldguide, presented by Vic Boomer as part of the OpenClaw publication. No summary, no interpretation, no omissions. For an interpreted reading, pick a different Vic Pill on the body page.

OpenClaw Field Guide

A practical guide to installation, architecture and use of OpenClaw. This manual combines the conceptual principles behind the system with technical instructions you follow step by step.

Documentation updated up to v2026.5.22. OpenClaw evolves at a high pace. Everything in this document describes how the system works at that version. Later releases add features or restructure things, and rarely something disappears. For current canonical documentation see docs.openclaw.ai; this fieldguide is a careful snapshot, not a living reference.

The field guide is written as a companion to the architecture documents in vicboomer/. Those give the technical depth; this document gives you the overall picture and the hands.

What OpenClaw really is

OpenClaw is a personal AI agent runtime that runs locally. You talk to it the way you chat with a person, via its own OpenClaw iOS/Android/macOS app (the most direct route, with voice, camera and location), or via messaging platforms like Telegram, Discord, Slack, Signal, iMessage and, with caution, WhatsApp. Instead of a web interface, you talk to your AI the way you chat with a person.

That is an important difference.

Most AI tools work according to the model:

question → answer → done

OpenClaw is designed for:

person → agent → collaboration → automation

Your Claw becomes a digital colleague, not a chatbot. It lives in your existing conversations, remembers what you are working on, and can act independently.

What makes a Claw unique

Personality

Each Claw has its own identity, captured in files like SOUL.md and IDENTITY.md. They define tone of voice, behaviour, caution, and style. That creates a consistent character, not a generic assistant that starts over each time.

Memory

A Claw remembers information about your preferences, ongoing projects and past conversations. This happens through MEMORY.md and USER.md. Memory is automatically included in every interaction; the agent knows who you are and what you were working on.

Proactive behaviour

A Claw can perform tasks independently via a mechanism called heartbeat. Every X minutes the agent checks for triggers: new emails, calendar changes, notifications. Examples:

• Send a daily briefing
• Detect conflicts in your calendar
• Prioritise your inbox
• Do a flight check in

The rules for these live in HEARTBEAT.md.

Self extending

One of the most important ideas behind OpenClaw is that a Claw can build new capabilities. When you ask for something it cannot yet do, the agent can write new code, build an integration, or add a tool. “Can you summarise my email every morning?” Then the Claw can build a Gmail integration itself, create a scheduled task, and generate a report.

Architecture in brief

OpenClaw consists of three layers:

INTERFACES    →  where you talk to the agent
     ↓            (WhatsApp, Telegram, Discord, CLI, web dashboard)
GATEWAY       →  the central system
     ↓            (route messages, manage sessions, authentication, security)
SERVICES      →  connections to the outside world
                  (LLM providers, messaging platforms, browser, filesystem)

The Gateway is the heart: a single Node.js process that combines WebSocket and HTTP, manages all channels, and runs the agent runtime. Everything runs locally on your hardware; only the API calls to the LLM leave your network.

Concepts you will encounter

Before we go further, a short introduction to the terms that return without explanation in the rest of this document. No one wants to look up halfway through Part 7 what a “session” is.

• Claw is an individual agent with its own personality, memory and channel connections. One OpenClaw runtime can run multiple Claws at once, each with its own workspace.
• Gateway is the central Node.js process that orchestrates all channels, sessions and agent runs. One gateway per machine; the Claws live inside it.
• Daemon is the gateway when it runs as a background service (via launchd on macOS, systemd on Linux, or the macOS menu bar app), so you do not need to keep a terminal open.
• Workspace is the folder (default ~/.openclaw/workspace/) with the markdown files that give a Claw its personality and memory. Each Claw has one workspace.
• Channel is a connection to a messaging platform (WhatsApp, Telegram, Slack, Discord, and so on) or a direct interface (iOS app, macOS app, TUI). One Claw can be present on multiple channels at once.
• Session is an ongoing conversation between you and a Claw, with memory between turns. Sessions are tied to a channel plus peer; different chats are different sessions.
• Skill is a reusable ability, stored as a folder with a SKILL.md (instruction plus metadata). The Claw knows when it can call a skill.
• Tool is a primitive action the Claw can perform, for example reading a file, opening a web page, running a bash command. Skills are built from tools.
• Heartbeat is an internal timer that wakes the Claw periodically without you sending anything. With it the agent can do proactive tasks, maintain memory, send reminders.
• Soul is the SOUL.md file in the workspace that captures the Claw’s personality and values. Loaded as system context at every session.
• Memory is everything the Claw remembers between sessions: short term (MEMORY.md), daily notes, and optionally a vector index for semantic search.

Should you lose track later, this section is still here.

How you work with a Claw

The biggest mistake people make is using their Claw as a search engine.

Do not:

Question → Answer → Done

Do:

Project → Collaborate → Iterate → Automate

See your Claw as an assistant, researcher, planner and operator. Not a chatbot. Give context, share projects, let the agent think along. The more you share, the better the agent gets.

Examples of daily use

Daily briefing: every morning an overview of your calendar, important mail and news.

Inbox triage: agent reads emails and sorts them: urgent, reply needed, archive.

Planning assistant: agent replans tasks when meetings run late.

Research assistant: agent reads documents, searches the web, and produces summaries.

Smart home: “Turn off the living room light” via WhatsApp.

Code review: agent looks at a PR, summarises the changes, and sends the result to Telegram.

From concept to practice

The rest of this field guide brings the above principles into practice. Each part builds on the previous, from installation to multi agent setups with memory, automation and sandboxing. Follow it in order, or jump to the part you need if you are already running.

Part 1: Installation and first start

What you need

• macOS, Linux or Windows (macOS is best tested)
• Node.js 22+: OpenClaw is TypeScript, runs on Node
• At least one LLM API key: Anthropic Claude is the recommended first choice

Install Node.js

node --version
# Must show v22.x.x or higher. If not:
brew install node@22

Install OpenClaw

npm install -g openclaw@latest

Check:

openclaw --version

Troubleshooting: command not found

npm prefix -g
# Add the path to ~/.zshrc:
export PATH="$(npm prefix -g)/bin:$PATH"

macOS sharp problem:

SHARP_IGNORE_GLOBAL_LIBVIPS=1 npm install -g openclaw@latest

The onboarding wizard

openclaw onboard --install-daemon

The wizard walks you through four steps:

1. Gateway authentication: set a token (generate with openssl rand -hex 32)
2. LLM provider: fill in an API key (Anthropic, OpenAI, Gemini, or another)
3. First channel: WhatsApp, Telegram, Discord, or later
4. Daemon install: gateway as a background service

After completion the gateway is running. Check:

openclaw status

What is now on your machine

~/.openclaw/
├── openclaw.json          ← main configuration
├── workspace/             ← agent workspace (personality, memory, skills)
│   ├── SOUL.md            ← personality and values
│   ├── IDENTITY.md        ← name and emoji
│   ├── USER.md            ← information about you
│   ├── AGENTS.md          ← operational rules
│   ├── MEMORY.md          ← long term memory
│   └── HEARTBEAT.md       ← proactive tasks
├── sessions/              ← conversation transcripts
├── credentials/           ← auth tokens (0600 permissions)
└── cron/                  ← scheduled tasks

Part 2: Security, before you go further

This is the most important part. OpenClaw has powerful security options, but you have to enable them. Do not skip this.

Run a security audit

openclaw security audit

Automatically fix what can be fixed:

openclaw security audit --fix

The six checks you MUST do

1. Gateway binds to localhost

// ~/.openclaw/openclaw.json
{
  gateway: {
    bind: "loopback"  // default and safest. NEVER "lan" without auth.
  }
}

2. Gateway authentication on

{
  gateway: {
    auth: {
      mode: "token",
      token: "${OPENCLAW_GATEWAY_TOKEN}"  // via env var, NEVER hardcoded
    }
  }
}

3. DM policy set to pairing

{
  channels: {
    whatsapp: { dmPolicy: "pairing" }
  }
}

The four options:

4. File permissions

chmod 700 ~/.openclaw
chmod 600 ~/.openclaw/openclaw.json

If ~/.openclaw/ is in a cloud sync folder (iCloud, Dropbox): move it. Otherwise your credentials get synchronised.

5. Tool restrictions

If you use OpenClaw as a chat assistant (not as a dev tool):

{
  tools: {
    profile: "messaging",
    deny: ["group:automation", "group:runtime", "group:fs"],
    fs: { workspaceOnly: true },
    exec: { security: "deny", ask: "always" },
    elevated: { enabled: false }
  }
}

6. Groups require @mention

{
  channels: {
    whatsapp: {
      groups: { "*": { requireMention: true } }
    }
  }
}

Safe starting configuration (copy paste)

{
  gateway: {
    mode: "local",
    bind: "loopback",
    auth: {
      mode: "token",
      token: "${OPENCLAW_GATEWAY_TOKEN}"
    }
  },
  session: {
    dmScope: "per-channel-peer"
  },
  tools: {
    profile: "messaging",
    deny: ["group:automation", "group:runtime", "group:fs", "sessions_spawn", "sessions_send"],
    fs: { workspaceOnly: true },
    exec: { security: "deny", ask: "always" },
    elevated: { enabled: false }
  },
  channels: {
    whatsapp: {
      dmPolicy: "pairing",
      groups: { "*": { requireMention: true } }
    }
  }
}

Part 3: Connecting your first channel

Start with one channel. Add more only when the first is working.

WhatsApp

⚠️ Ban risk: NEVER use your own main number.

WhatsApp has no official Bot API for personal accounts. OpenClaw connects via Baileys, a community library that reverse engineered the WhatsApp Web protocol. This falls under WhatsApp’s “unauthorized clients” clause in their ToS, and WhatsApp’s ML system recognises automation patterns (fast replies, 24/7 active, bot behaviour). The ban applies to the phone number, not OpenClaw. If you link your main number you could lose your whole WhatsApp life (business contacts, family, groups, everything).

What instead?

• A second number (eSIM, virtual number such as Twilio, an old Pixel with a prepaid SIM)
• A dedicated bot number that exists only for this use case
• For commercial / multi user use: the official WhatsApp Business API (via Twilio/Meta). OpenClaw has no built in channel for that, but you can connect it via your own plugin

Further restrictions: dmPolicy: "allowlist" (not "pairing" for publicly reachable bots), allowFrom with explicit numbers, no volume or frequency that would mark you as a bot.

openclaw channels login
# Scan the QR code with your phone (make sure it is your second number!)

WhatsApp uses Baileys (no official API). The session expires periodically; re pair with openclaw channels login.

Telegram

1. Create a bot via @BotFather
2. Add the token:

export TELEGRAM_BOT_TOKEN="123456:ABC..."

3. Restart the gateway or wait for hot reload

Discord

1. Create a bot in the Discord Developer Portal
2. Turn on Message Content Intent
3. Add the token:

export DISCORD_BOT_TOKEN="your-token"

Verify it works

openclaw channels status
openclaw channels status --probe  # deeper check

Send a test message to your bot. If all is well you get a reply.

Part 4: Setting up LLM providers

API keys via environment variables

Add to ~/.zshrc:

export ANTHROPIC_API_KEY="sk-ant-your-key"
# Optional:
export OPENAI_API_KEY="sk-..."
export GEMINI_API_KEY="..."
export OPENROUTER_API_KEY="sk-or-..."

Never put API keys directly in openclaw.json. Always use ${VAR_NAME} syntax.

Available providers

Set the model

openclaw models set anthropic/claude-sonnet-4-5

Or in config:

{
  agents: {
    defaults: {
      model: {
        primary: "anthropic/claude-sonnet-4-5",
        fallbacks: ["openai/gpt-5.2"]
      }
    }
  }
}

The fallback chain tries models in order. On an auth error the API key is rotated first; only once all keys are exhausted does it move to the next model.

Multi key rotation

Multiple API keys from the same provider:

export ANTHROPIC_API_KEYS="key1,key2,key3"

OpenClaw rotates automatically on rate limits or billing errors.

Local model via Ollama

ollama pull llama3.3

{
  agents: {
    defaults: {
      model: { primary: "ollama/llama3.3" }
    }
  }
}

Ollama is automatically discovered if running on localhost:11434. OpenClaw detects vision capability via /api/show, so if an Ollama model is multimodal the correct image media type is set automatically so you can send pictures.

Amazon Bedrock (AWS)

{
  models: {
    providers: {
      bedrock: {
        region: "eu-central-1",
        // IAM auth via @aws/bedrock-token-generator (default when AWS credentials are available)
      }
    }
  }
}

OpenClaw does inference profile discovery and region injection automatically. For Bedrock models only available via OpenAI compatible endpoints, use bedrock-mantle/<model>.

Bedrock can also be used as embedding provider for memory search, useful if you want to keep memoryCore fully inside AWS.

Own endpoint (LM Studio, vLLM, SGLang)

{
  models: {
    providers: {
      lmstudio: {
        baseUrl: "http://localhost:1234/v1",
        apiKey: "lmstudio",
        api: "openai-completions",
        models: [
          { id: "minimax-m2.5", name: "MiniMax M2.5", contextWindow: 200000 }
        ]
      }
    }
  }
}

Fast mode (lower latency)

{
  agents: {
    defaults: {
      model: {
        params: { fast_mode: true }
      }
    }
  }
}

Works with Anthropic (service_tier: "auto") and OpenAI. Cron jobs use fast mode by default.

Tiered pricing and session costs

Many modern models charge different prices for cache hits, cache misses and different input/output tiers. OpenClaw tracks session cost as a snapshot (not cumulatively added), so the amount you see in the UI matches the actual bill, even on long sessions or mid session model switches.

openclaw infer, direct inference

A new sub CLI for direct LLM interaction without an agent loop:

openclaw infer "Translate this to English: Hallo wereld"
openclaw infer image "A cat on a skateboard"
openclaw infer tts "Good morning" --voice shimmer
openclaw infer search "OpenClaw release notes"

Useful for scripts, one shots and quick tests. Documentation: docs/cli/capability.md.

Useful commands

openclaw models list             # available models
openclaw models status           # auth status per provider
openclaw models fallbacks list   # fallback chain
openclaw models fallbacks add openai/gpt-5.2
openclaw models aliases add opus anthropic/claude-opus-4-6
openclaw infer "question"        # direct inference

Part 5: Personalising your agent

At every session the agent reads a set of markdown files from the workspace. This is its “personality” and “memory”.

IDENTITY.md, name and look

Name: Atlas
Emoji: 🏛️

The agent uses this name in conversations and the emoji appears in channel messages.

SOUL.md, personality and limits

# Personality
You are a pragmatic assistant with dry humour.
You give concise answers unless detail is explicitly requested.

# Limits
- Never give medical or legal advice
- Refer to professionals on sensitive topics
- Be honest when you do not know something

USER.md, information about you

# Tom
- Software architect, based in Amsterdam
- Time zone: Europe/Amsterdam
- Communicates in English
- Works with TypeScript, Swift, Kotlin
- Uses Obsidian for documentation

The more you write here, the better the agent tunes to you.

AGENTS.md, operational rules

# Way of working
- Use Markdown in answers
- Add source references where possible
- For code questions: always read the relevant files first
- Save important information in memory/

MEMORY.md, long term memory

This file is automatically injected into every system prompt (max 20,000 characters). The agent sees it at every turn without calling tools.

# Long term memory

## Projects
- OpenClaw documentation: 24 chapters in vicboomer/
- Pantion: dialog protocol for intent convergence

## Preferences
- Concise and technical
- English communication

The agent can also update this file itself. Over time it grows organically.

HEARTBEAT.md, proactive tasks

# Tasks at every check in

## Daily
- Check whether there are unread reminders in memory/
- Update the summary of ongoing projects in MEMORY.md

## Weekly (Monday)
- Write a weekly overview to memory/

Part 6: Memory, how the agent remembers

OpenClaw has three memory layers:

Automatic memory flush

When a session is about to hit the context window limit, the agent automatically writes important facts to memory/YYYY-MM-DD.md before the transcript is compacted. This prevents memory loss on long conversations.

On /reset or /new the same happens; the agent saves facts before the transcript is cleared.

Activate semantic search

{
  agents: {
    defaults: {
      memorySearch: {
        enabled: true,
        provider: "openai",
        model: "text-embedding-3-small"
      }
    }
  }
}

Now the agent can use memory_search "topic" to search across all daily notes. Search results combine vector similarity with text match and time decay (more recent notes score higher).

Multimodal memory (images and audio)

You can also index photos and audio recordings:

{
  agents: {
    defaults: {
      memorySearch: {
        multimodal: {
          enabled: true,
          modalities: ["image", "audio"]
        },
        provider: "gemini",
        model: "gemini-embedding-2-preview",
        fallback: "none"
      }
    }
  }
}

Supported types: .jpg, .png, .webp, .gif, .heic (images), .mp3, .wav, .ogg, .m4a, .flac (audio).

Local embeddings (no API cost)

{
  agents: {
    defaults: {
      memorySearch: {
        provider: "local",
        local: {
          modelPath: "hf:ggml-org/embedding-model.gguf",
          modelCacheDir: "~/.openclaw/models"
        },
        fallback: "openai"  // fallback when local fails
      }
    }
  }
}

Sleep phases and aging

memory-core has a staged lifecycle: instead of one opaque “dreaming” process there are configurable sleep phases (sleeping, REM preview, wake write). You can set a retention/cleanup policy per agent:

{
  agents: {
    defaults: {
      memoryCore: {
        dreamingAging: {
          retentionDays: 365,
          autoCleanup: true
        }
      }
    }
  }
}

With REM preview you can inspect what a memory cycle would do before it actually writes to disk, useful when you are starting out with memoryCore and want to see what your agent extracts from transcripts.

Grounded REM backfill

The dreaming subsystem can feed back historic daily notes via a “grounded REM backfill” lane. This means:

• Facts from old daily notes are re evaluated and promoted to short term memory if relevant
• A grounded scene lane offers daily context snapshots to the dreaming cycle
• The dreaming diary UI in the Control Panel shows a timeline with backfill/reset buttons and traceable summaries

Useful when your agent has weeks of conversations but had “forgotten” older facts; the backfill brings them back without manual reindexing.

Memory Wiki

memory-wiki is a new extension on top of memory-core that structures your memory as a wiki/vault (comparable to Obsidian). You get:

• Wiki pages with backlinks between related notes
• An ingest/compile/lint pipeline that turns transcripts into structured wiki pages
• An agent lint tool that flags missing provenance or dead links
• A wiki apply mutation tool with which the agent can edit wiki pages itself
• Dashboard report pages and wiki doctor diagnostics
• An Obsidian style CLI bridge so you can sync your vault

openclaw plugins install memory-wiki
openclaw wiki doctor              # diagnose
openclaw wiki ingest               # process new content

The wiki can also act as a shared search bridge for the regular memory_search tool; agents can find wiki pages without you needing a separate tool.

Active Memory

The newest memory extension: a blocking memory sub agent that, before every reply, automatically retrieves relevant memories and injects them into the agent context. This makes the agent feel “up to date” without you having to ask for memory_search.

{
  plugins: {
    entries: {
      "active-memory": {
        enabled: true,
        config: {
          enabled: true,
          agents: ["main"],
          allowedChatTypes: ["direct"],
          queryMode: "recent",       // or "semantic", "hybrid"
          promptStyle: "balanced",   // how aggressively to inject memories
          timeoutMs: 15000,
          maxSummaryChars: 220,
          persistTranscripts: false,
          logging: true
        }
      }
    }
  }
}

Active Memory runs as a bounded sidecar with timeout; if it takes too long, the reply continues without the extra context. Configurable per agent and chat type (DMs only by default, not groups). Docs: docs/concepts/active-memory.md.

Useful commands

openclaw memory status               # index statistics
openclaw memory search "topic"       # search memory
openclaw memory index                # reindex everything
openclaw wiki doctor                 # (memory-wiki) sanity check vault

Part 7: Skills, what the agent can do

Skills are the “abilities” of the agent. Each skill is a folder with a SKILL.md file describing what the skill does and what it needs.

Look at available skills

openclaw skills list              # all skills
openclaw skills list --eligible   # only available skills
openclaw skills check             # which skills lack requirements
openclaw skills info github       # details of a specific skill

How skills work

There are two execution paths:

1. Tool dispatch (fast, deterministic), the skill calls a built in tool directly:

/web_search "OpenClaw documentation"

No AI needed. The CLI parses the command and runs the tool directly.

2. Model invocation (flexible, via agent), the agent reads SKILL.md and follows the instructions:

/github "create an issue for the memory bug"

The agent reads the GitHub skill instructions, thinks about the steps, and executes them with the available tools (bash, read, write, and so on).

Claude Code in chat: claude-code-proxy

The claude-code-proxy skill makes Claude Code conversationally available via your messaging channels. From your phone (WhatsApp, Telegram, Discord) you can have Claude Code code as if you were sitting behind your laptop:

/claude-code-proxy "fix the regression in src/foo.ts and commit it"

The skill is budget capped and channel aware; output is formatted for the channel you are working on and you have limits so you do not accidentally burn a day of tokens from the couch.

Skill security

Skill policy validation is also enforced client side, before execution reaches the server. Try to run a skill not allowed by your policy and you get immediate feedback instead of waiting for a server rejection.

Install skills

Some skills require external programs:

# Check which skills need extra software
openclaw skills check --verbose

# Skills from ClawHub (the public registry)
npx clawhub install <skill-name>

Make your own skill

mkdir -p ~/.openclaw/workspace/skills/my-skill

Create SKILL.md:

---
name: my_skill
description: "Description of what the skill does"
metadata:
  openclaw:
    emoji: "🔧"
    requires:
      bins: ["curl"]
      env: ["MY_API_KEY"]
---

# My Skill

When the user asks for [specific task], do:

1. Use the web_fetch tool to retrieve data from [URL]
2. Process the result
3. Return a summary

The skill is immediately available (hot reload, 250ms debounce).

Skill configuration

{
  skills: {
    entries: {
      "github": { enabled: true },
      "apple-notes": { enabled: true },
      "dangerous-skill": { enabled: false }
    }
  }
}

Part 8: Multiple channels at once

OpenClaw can connect to 20+ channels at once. Each channel has its own adapter with its own capabilities.

Add channels

openclaw channels add --channel telegram --account alerts --token $TOKEN
openclaw channels add --channel discord --account work --token $DISCORD_TOKEN

Or interactively:

openclaw channels add

Channel capabilities

Slack supports Block Kit: agents can send rich messages with buttons, menus and sections. WeChat has a full integration, documented in docs/channels/wechat.md.

Channel specific options

A few new knobs you can set per channel:

Slack, only react to explicit @mention in threads

{
  channels: {
    slack: {
      thread: {
        requireExplicitMention: true
      }
    }
  }
}

Prevents the bot from continuing to reply in an ongoing thread once it has been tagged. Every new question must explicitly contain @bot.

WhatsApp, replies with quote

{
  channels: {
    whatsapp: {
      replyToMode: "quoted"   // or "auto" for automatic detection
    }
  }
}

Bot replies now show the original message quote, the way a normal user would.

Matrix, auto join during onboarding During openclaw onboard the Matrix bot can automatically accept room invitations, useful if you want to connect many rooms at once without confirming each by hand.

Discord: small fixes under the hood: gateway connections now use ws for compatibility, voice receive has a hardened error recovery path and empty gateway type errors contain stack hints again.

Inbound mention policy, centralised

All channels share one mention policy: one central place where you configure when the Claw may answer in a group. Adjust it in one channel and the rules apply everywhere. Previously each channel had its own rules, which led to confusing differences between Slack, Discord, Telegram, Matrix and WhatsApp.

Voice and meetings, when chat is not enough

A Claw is not limited to text on channels that support more. Three capabilities that work where the channel allows them:

Voice calls. Browser, Discord and native nodes (iOS, macOS) share one unified talk system. A call that starts in the browser can be handed over to iOS or Discord without interruption. For Discord, audio is streamed directly via ElevenLabs, without a separate transcribe step.

Google Meet. A Claw can join Google Meet meetings via a paired node Chrome transport. Transcript entries come back as artifacts in the session, so the Claw can still talk about it afterwards.

Telephony (DTMF). For voice calls OpenClaw supports keypad tones during a call. Essential when the Claw has to work through an IVR menu to call back, for example.

Durable message lifecycle

Outbound messages go through a structured lifecycle: queued, sending, sent or failed. Channels often show a live updating message during a running agent run (“progress draft”) so you can follow along while the Claw is working. More importantly: a network outage or a gateway restart no longer leads to lost messages, even at high volume.

Multi account (same channel, different bots)

{
  channels: {
    telegram: {
      accounts: {
        personal: {
          botToken: "token-1",
          dmPolicy: "pairing",
          allowFrom: ["+31612345678"]
        },
        alerts: {
          botToken: "token-2",
          dmPolicy: "open",
          allowFrom: ["*"]
        }
      },
      defaultAccount: "personal"
    }
  }
}

Look at status

openclaw channels status           # overview
openclaw channels status --probe   # deeper check (connection test)
openclaw channels list             # all accounts

Part 9: Multi agent, multiple personalities

This is where OpenClaw becomes truly powerful. You can run multiple agents, each with their own workspace, personality, model and channel connections.

Create agents

openclaw agents add work --workspace ~/.openclaw/workspace-work
openclaw agents add home --workspace ~/.openclaw/workspace-home

Or in config:

{
  agents: {
    list: [
      { id: "home", default: true, workspace: "~/.openclaw/workspace-home" },
      { id: "work", workspace: "~/.openclaw/workspace-work" },
      { id: "ops", workspace: "~/.openclaw/workspace-ops" }
    ]
  }
}

Bind agents to channels

Who serves which channel:

{
  bindings: [
    { agentId: "home", match: { channel: "whatsapp" } },
    { agentId: "work", match: { channel: "slack" } },
    { agentId: "ops", match: { channel: "telegram", accountId: "alerts" } }
  ]
}

Or via CLI:

openclaw agents bind --agent work --bind slack
openclaw agents bind --agent ops --bind "telegram:alerts"

Routing rules

The router decides which agent gets a message. Priority:

1. Exact peer match (Discord: role + guild + peer)
2. Thread inheritance (child follows parent)
3. Guild + roles (Discord)
4. Account match
5. Channel match
6. Default agent

Each agent has its own workspace

~/.openclaw/workspace-home/     ← own SOUL.md, MEMORY.md, skills
~/.openclaw/workspace-work/     ← different model, different personality
~/.openclaw/workspace-ops/      ← minimal personality, focus on monitoring

Configure per agent:

{
  agents: {
    list: [
      {
        id: "work",
        workspace: "~/.openclaw/workspace-work",
        model: { primary: "anthropic/claude-opus-4-6" },
        thinking: "high",
        heartbeat: {
          every: "1h",
          target: "slack",
          // include heartbeat section in system prompt per agent
          includeSystemPromptSection: true
        },
        // override complete system prompt for this agent
        systemPromptOverride: "You are an ops bot. Answer briefly and in EN."
      }
    ]
  }
}

Per agent system prompt overrides are useful when one agent must fundamentally speak differently from the rest, for example an ops bot that only delivers dry status updates. For light agents without a heartbeat loop, heartbeat.includeSystemPromptSection: false also saves a fair number of tokens.

Subagents (automatically spawned agents)

The main agent can spawn subagents for parallel tasks:

User: "Find information about X and Y at the same time"
Agent: spawns two subagents, each with its own session
Subagent 1: searches X → reports back
Subagent 2: searches Y → reports back
Agent: combines the results

Subagents respect depth limits:

Sandboxed subagents have limited visibility; they can only see their own session and sessions they spawned.

Commands

openclaw agents list                    # all agents
openclaw agents bindings                # who is bound to what
openclaw agents add <name> --workspace <path>
openclaw agents delete <name> --force

Part 10: Scheduled tasks with cron

The built in scheduler lets agents run at scheduled times, deliver results via channels, and automatically recover from errors.

One off reminder

openclaw cron add \
  --name "Reminder" \
  --at "2026-04-01T09:00:00Z" \
  --session main \
  --system-event "Reminder: review documentation" \
  --wake now \
  --delete-after-run

Relative time (in 20 minutes)

openclaw cron add \
  --name "Check" \
  --at "20m" \
  --session main \
  --system-event "Check the status of the deployment" \
  --wake now

Daily recurring (isolated session)

openclaw cron add \
  --name "Morning status" \
  --cron "0 7 * * *" \
  --tz "Europe/Amsterdam" \
  --session isolated \
  --message "Summarise the inbox and calendar for today." \
  --announce \
  --channel whatsapp \
  --to "+31612345678"

Weekly with heavier model

openclaw cron add \
  --name "Weekly analysis" \
  --cron "0 6 * * 1" \
  --tz "Europe/Amsterdam" \
  --session isolated \
  --message "Weekly analysis of project progress." \
  --model "opus" \
  --thinking high \
  --announce

Cron in an existing session (--session-key)

With --session-key you let a cron job run in a specific existing session. Useful when you want a recurring task that stays inside an ongoing thread instead of starting a new isolated session each time:

openclaw cron add \
  --name "Project standup" \
  --cron "0 9 * * 1-5" \
  --tz "Europe/Amsterdam" \
  --session-key "agent:work:slack:C12345" \
  --message "Summarise the open issues of project X."

The session key decides which conversation the cron touches: agent:<id>:<channel>:<peer>. The agent then sees the full context of that thread at every run, as if you had sent the message yourself.

Cron versus heartbeat, when which?

Managing

openclaw cron list                  # all jobs
openclaw cron status                # status overview
openclaw cron runs --id <jobId>     # history
openclaw cron run <jobId>           # run manually
openclaw cron edit <jobId> --message "New prompt"
openclaw cron remove <jobId>

Error handling

On transient errors (rate limits, timeouts, 5xx) OpenClaw retries with exponential backoff:

You can set a failure alert:

{
  cron: {
    failureAlert: {
      after: 3,
      channel: "telegram",
      to: "12345",
      cooldownMs: 3600000
    }
  }
}

Part 11: Browser automation

The agent can visit web pages, fill in forms, take screenshots and more via Playwright.

Activate

{
  browser: {
    enabled: true,
    defaultProfile: "openclaw"
  }
}

Manual testing

openclaw browser start
openclaw browser open https://example.com
openclaw browser screenshot
openclaw browser snapshot    # ARIA accessibility tree (text, not pixels)

What the agent can do

The agent has browser tools available in skills:

Browser session selection

The fastest way to choose which browser the agent uses:

The agent automatically picks the user profile if available.

Tip: Use browserSession: "user" when the agent has to log in to services where you are already authenticated (Google, GitHub, internal tools). Use "agent" for clean scraping without touching your personal session.

Profiles

{
  browser: {
    profiles: {
      work: { cdpPort: 18801 },
      remote: { cdpUrl: "http://10.0.0.42:9222" }
    }
  }
}

Browser profiles, hot reloading

The browser server context supports profile hot reloading: changes in profiles are picked up immediately without restarting the browser. Tab management is robust, and tighter guards around interactive actions prevent parallel agents from getting in each other’s way.

For Browserbase users: direct WebSocket CDP connections are now supported, measurably lower latency than HTTP polling:

{
  browser: {
    profiles: {
      cloud: {
        cdpUrl: "wss://connect.browserbase.com?apiKey=..."
      }
    }
  }
}

SSRF protection

The browser refuses navigation to private networks by default. Override (only if you know what you are doing):

{
  browser: {
    ssrfPolicy: {
      dangerouslyAllowPrivateNetwork: true
    }
  }
}

Part 12: Heartbeat, the proactive agent

The heartbeat is a timer that wakes the agent periodically without you sending a message. With it the agent can maintain memory, send reminders and perform tasks.

Activate

{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m",
        activeHours: {
          start: "08:00",
          end: "22:00",
          timezone: "Europe/Amsterdam"
        },
        target: "last",
        model: "anthropic/claude-sonnet-4-5",
        // include heartbeat section in system prompt
        includeSystemPromptSection: true
      }
    }
  }
}

What the agent does on a heartbeat

The agent reads HEARTBEAT.md and follows the instructions. Typically:

• Update memory
• Check reminders
• Review running tasks

If there is nothing to report, the agent replies with HEARTBEAT_OK (invisible to you).

Commands

openclaw system heartbeat last      # view last heartbeat
openclaw system heartbeat enable    # turn on
openclaw system heartbeat disable   # turn off

Part 13: Docker sandboxing

A Claw can execute code: run bash commands, start Python scripts, edit files, drive a browser. That is exactly what makes it useful, and exactly what makes it risky. A prompt injection in an incoming email, a misconfigured skill, a sub agent that calls an unexpected tool: in all those scenarios you do not want the execution to land on your host machine unchecked.

Docker sandboxing runs the tool execution of a Claw in an isolated container. The container has by default a read only root filesystem, no network connection, all Linux capabilities removed, a memory limit and a PID limit. A malicious command that could damage your host simply cannot do so inside the sandbox.

When does the sandbox kick in?

Not at every turn. Starting a sandbox costs a few seconds, so OpenClaw tries to use it as targeted as possible. The mode setting decides which executions go through the container:

non-main is the pragmatic middle ground: your own interaction stays direct, but as soon as the Claw spawns a subagent itself (often for parallel tasks on unpredictable data) that one goes into the container. For public bots serving unknown users, all is the right choice.

Activate

First build the Docker image that serves as base. The script in scripts/sandbox-setup.sh does it in one go:

scripts/sandbox-setup.sh

Then configure the sandbox in openclaw.json:

{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main",
        docker: {
          image: "node:22-slim",
          readOnlyRoot: true,
          network: "none",
          capDrop: ["ALL"],
          memory: "512m",
          pidsLimit: 100
        }
      }
    }
  }
}

memory and pidsLimit are soft upper bounds preventing a runaway tool from eating your host. The values above are roomy enough for normal tasks (reading files, running short scripts, calling an API) but too tight for heavy data processing. Raise them if you give your Claw genuinely large workloads.

What is and is not reachable from the container?

The sandbox is not a full copy of your system. By default:

• Workspace (the folder with SOUL.md, MEMORY.md, skills): mounted read only, so the Claw can read its own context but cannot rewrite its personality from a tool.
• Filesystem outside the workspace: not reachable. A tool that tries to read ~/.ssh/id_rsa simply gets “no such file”.
• Network: off by default. If a tool needs to go on the web (such as the web_fetch tool), the network traffic goes through a controlled path in the gateway, not via the container itself.
• Secret material (~/.openclaw/credentials/): not mounted. The gateway forwards only the strictly necessary tokens, and only when the tool actually needs them.

The result is that a compromised tool cannot hijack the Claw itself, let alone your system.

What you can expect in use

Three things you notice in practice:

1. First cold start is slower. The image has to be loaded once. After that, sandbox invocations run in hundreds of milliseconds.
2. Tools needing network ask for explicit permission. A tool that overrides network: "none" requires a setting in the tool config or a permission prompt to you.
3. Logs appear in openclaw logs as always, but you see that a tool ran “in sandbox”, so afterwards you know which execution was isolated.

When to leave it off

On a personal laptop where you are the only user, where you wrote or installed all skills yourself, and where no one else can drive your Claw, the sandbox mostly adds overhead. mode: "off" is a reasonable choice then. As soon as you put your Claw on a public channel (open WhatsApp number, Discord bot for your community, web form posting to the gateway), non-main or all is no longer a luxury but the norm.

Part 14: Hooks and automation

A skill is something the Claw can decide to use itself. A hook is the opposite: a piece of code that runs without the Claw asking for it, because something happens in the system. A message arrives, a session starts, a command is called, and you want to attach something to that. Log, transform, forward, block.

Conceptually: skills let you give the Claw new abilities. Hooks let you give the system itself behaviour that exists independently of the Claw. A hook can intercept a message before the Claw ever sees it, or do something after the Claw has finished replying.

Available events

Make a hook

mkdir -p ~/.openclaw/hooks/my-hook

HOOK.md:

---
name: my-hook
description: "Log every received message"
metadata:
  openclaw:
    events: ["message:received"]
---

handler.ts:

export default async function(event) {
  console.log(`Message from ${event.context.from}: ${event.context.content}`);
}

Gmail integration via hooks

openclaw webhooks gmail setup --account your-email@gmail.com --project gcp-project

{
  hooks: {
    enabled: true,
    mappings: [
      {
        match: { path: "gmail" },
        action: "agent",
        agentId: "main",
        deliver: true
      }
    ]
  }
}

Wake hooks are untrusted

Events that arrive via wake triggers (external pings that wake the Claw) are marked as untrusted. That means such an event cannot quietly inject trusted context into your Claw; everything from a wake event is treated as content from an unknown sender.

Why it matters: if you use hooks to let external systems “talk” to your agent (webhooks, Gmail Pub/Sub, Discord embeds), an attacker who can fire a wake trigger can no longer pretend the payload comes from a trusted source. Tools that only open for trusted content stay closed.

Hooks also receive more context (trigger, channelId) so hook implementations can make context aware decisions about what to do with an event.

Note: if you use your own hooks.internal.handlers config, that field is only kept as compat input. The canonical config key is hooks.internal.entries.

Part 15: Native apps

Important to know: OpenClaw has its own iOS and Android app with which you talk directly to your agent, without WhatsApp/Telegram/Discord in between. For many users this is the primary daily interface, not an addition. The messaging channels are an extension when you want your agent in a normal chat app or a group; the native apps are for direct, personal conversations with full device integration (camera, location, voice).

iOS app, a full chat client

The iOS app connects directly to your gateway (locally via Bonjour/mDNS or remotely via Tailscale) and is a complete OpenClaw client:

Communication:

• Chat with your agent: own chat interface, no WhatsApp/Telegram needed
• Talk mode: push to talk and continuous voice conversation
• Voice wake: background wake word detection (“Hey Atlas…”)
• Apple Watch: chat, voice input and exec approvals on your wrist
• Push notifications for agent replies and exec approvals, with approve/deny straight from the lock screen without opening the app

Device integration (the agent can use this):

• Camera (photo and video capture on request)
• Location (significant location monitor)
• Screen (ReplayKit recording)
• Photo library, calendar, contacts, reminders
• Motion data
• Widgets / Live Activities

Under the hood:

• Dual gateway sessions (one for device capabilities, one for chat/voice)
• TLS certificate pinning (SHA256 fingerprint)
• 11Labs voice integration with PCM/MP3 fallback
• An authenticated background presence beacon so the gateway knows whether the iOS client is active without the app being open
• Talk handoff to native nodes: a voice call that starts in the browser can be handed over to iOS without interruption

Connecting:

openclaw qr   # generates pairing QR; scan with the iOS app

Gateway connection error messages are clearly worded and the release versioning is pinned on CalVer (apps/ios/version.json).

Android app

Similar to iOS, Kotlin based (StateFlow + coroutines), connects directly via WebSocket. Chat interface, talk mode, push notifications. The QR pairing process is robust: stale setup codes are wiped on new QR scans and stored device tokens take precedence.

macOS app (menu bar)

The macOS app is a menu bar application with:

• Gateway control (start/stop/restart): gateway runs as child process of the app
• Chat interface with your agent (canonical session keys, /new, /reset, /clear)
• Canvas windows for web content
• Talk mode (voice), with experimental MLX Talk provider for local speech synthesis (no API needed, runs on Apple Silicon)
• Auto update via Sparkle (the macOS update/restart handoff is robust and prevents the app from being stuck in a half started state after an npm update)
• Screen snapshots for monitor preview: the macOS app provides a screen.snapshot node command with which the Control Panel can show a live preview of your Mac screen in the monitor view

Which interface when?

Terminal UI (TUI)

openclaw tui

Full chat interface in the terminal. Useful for SSH sessions.

Control Panel (web)

openclaw dashboard
# Or navigate to http://127.0.0.1:18789/

Web interface built with Lit web components. Shows channel status, sessions, configuration, logs.

Part 16: CLI reference (the most important commands)

Daily use

openclaw status                    # quick health check
openclaw status --all              # full overview
openclaw status --deep             # with connection tests
openclaw doctor                    # diagnosis + fixes
openclaw doctor --fix              # auto repair
openclaw logs --follow             # follow logs (live)

Gateway

openclaw gateway start             # start
openclaw gateway stop              # stop
openclaw gateway restart           # restart
openclaw gateway run               # run in foreground (debug)
openclaw gateway install           # install as service
openclaw gateway status            # service status

Configuration

openclaw config get <path>          # get a value
openclaw config set <path> <value>  # set a value
openclaw config validate            # validate config
openclaw configure                  # interactive wizard

Messages

openclaw message send --target "+31612345678" --message "Hello"
openclaw agent --message "What time is it?" --deliver
openclaw agent --message "code" --thinking high --local

Updating

openclaw update                    # to newest version
openclaw update status             # current version + available update
openclaw update --channel beta     # to beta channel

Part 17: Configuration overview

What hot reloads and what does not

Config file structure

{
  // Gateway: network, auth, TLS
  gateway: { bind: "loopback", port: 18789, auth: { ... } },

  // Agents: models, workspace, heartbeat, sessions
  agents: { defaults: { ... }, list: [ ... ] },

  // Channels: WhatsApp, Telegram, Discord, etc.
  channels: { whatsapp: { ... }, telegram: { ... } },

  // Routing: which agent serves which channel
  bindings: [ ... ],

  // Tools: which tools the agent may use
  tools: { profile: "messaging", deny: [ ... ] },

  // Skills: which skills are active
  skills: { entries: { ... } },

  // Cron: scheduled tasks
  cron: { enabled: true, ... },

  // Browser: automation
  browser: { enabled: true, ... },

  // Hooks: event handlers
  hooks: { enabled: true, ... },

  // Sessions: scope, reset, threads, compaction checkpoints
  session: { dmScope: "per-channel-peer", ... },
  sessions: {
    compactionCheckpointOptions: { enabled: true, maxCheckpoints: 10 }
  },

  // Models: provider config, discovery
  models: { providers: { ... } },

  // Memory: vector search, embeddings
  // (in agents.defaults.memorySearch)

  // Environment variables
  env: { vars: { ... } },

  // $include: split config across files
  agents: { $include: "./agents.json5" },
}

Environment variables in config

{
  gateway: {
    auth: { token: "${OPENCLAW_GATEWAY_TOKEN}" }
  }
}

Escape literal ${} with $${}.

Part 18: Troubleshooting

Gateway does not start

lsof -i :18789              # port already in use?
openclaw doctor              # auto diagnosis
openclaw config validate     # config errors?

Channel does not respond

openclaw channels status --probe
openclaw logs --follow       # look for error messages

WhatsApp link expired

openclaw channels login      # scan the QR code again

Model not found

openclaw models list         # which models are available?
openclaw models status       # auth status per provider

Session stuck

openclaw gateway restart
# Or specifically:
openclaw sessions            # view active sessions

Memory does not search

openclaw memory status       # is the index built?
openclaw memory index        # reindex

Everything fails

openclaw doctor --fix        # auto repair
openclaw security audit --fix
openclaw gateway restart

Part 19: Updating and maintenance

Update

openclaw update

This command pulls the newest version, installs it, checks config compatibility, and restarts the gateway.

Update channels

openclaw update --channel beta
openclaw update status

Rollback

npm i -g openclaw@2026.3.11   # pin to a specific version
openclaw gateway restart

Backup

openclaw backup create

Part 20: Going further

The vicboomer architecture documents

These documents give the technical depth behind everything you learned above:

Online sources

• Official docs: docs.openclaw.ai
• Security: docs.openclaw.ai/gateway/security
• Discord community: discord.gg/clawd

Snapshot of OpenClaw v2026.5.22, May 2026. Current canonical documentation: docs.openclaw.ai.