So you want to give an AI agent the keys to your entire digital life. Cool. Normal behavior. Totally not the plot of every cautionary sci-fi movie ever made.

OpenClaw (formerly Clawdbot, briefly Moltbot — because apparently even AI projects have identity crises) is an open-source, self-hosted AI agent framework that runs locally on your machine. At its core, it's a TypeScript CLI application — not Python, not a web app, not a Next.js side project some dude cooked up over a weekend. It's a full-blown gateway server that sits on your machine, connects to every messaging platform you use (Telegram, WhatsApp, Slack, Discord, iMessage, Signal — yes, all of them simultaneously), makes calls to LLM APIs, executes tools locally, and basically does whatever the hell you tell it to on your computer.

Think of it as giving your AI a body. A body with root access. On your machine. Where your files live. And your API keys. And your browser sessions. What could possibly go wrong?

The project has 125,000+ GitHub stars, people are literally buying dedicated Mac Minis just to run this thing, and VirusTotal has already flagged about 12% of the community skill registry as malicious. Welcome to 2026, where the future is both incredible and terrifying in equal measure.

OpenClaw is gateway-centric — one long-running Node.js process acts as the control plane for everything. Channels are just inputs, tools are just outputs, and the LLM is the brain in between deciding what to do with your life. It's model-agnostic (Anthropic, OpenAI, local models via Ollama, whatever), privacy-focused-ish (your data stays local unless you send it to an API provider), and costs roughly $5–50/month in API usage depending on how much you let the lobster loose.

The official tagline should honestly be: "Your personal AI assistant. Any OS. Any platform. Your own damn fault."

Below is a complete AI setup walkthrough prompt you can hand to your regular LLM of choice in a browser. The LLM will guide you step by step through a comprehensive security and token management process. It's optimized for security, token cost, and memory — in that order. You are free to disrespect some of these options; especially memory and token management. I highly recommend using the subscription based hacks because the APIs are super expensive. For real, consider each option as it comes up and just skip it if you're feeling frisky. Because if your agent gets compromised, cheap tokens don't mean shit.

Let's talk about the elephant in the room — or rather, the lobster with shell access.

OpenClaw combines three things that security researchers call the "lethal trifecta": access to private data, exposure to untrusted content, and the ability to communicate externally. Add persistent memory and shell access on top, and congratulations, you've built yourself a potential persistent insider threat that can autonomously act. Isn't that fun?

The fundamental problem is architectural: if the agent reads any untrusted content and has any ability to act, it can be manipulated. OpenClaw's security controls are defense-in-depth for a fundamentally vulnerable design. They help. They're not a cure. Keep that in your head at all times.

This is non-negotiable, step-zero, don't-even-think-about-skipping-it territory.

Your macOS firewall should be ON before OpenClaw even touches your machine. FileVault encryption: ON. These aren't OpenClaw-specific — they're "you're running a computer in 2026" basics. But since you're about to give an AI agent the ability to run shell commands on your machine, maybe now's a good time to actually take this seriously.

OpenClaw's gateway binds to 127.0.0.1:18789 (loopback) by default. This means it only accepts connections from your own machine. Do not change this. The moment you bind to 0.0.0.0 or expose that port through a reverse proxy, you've just published a privileged agent gateway to the internet. The documented failure mode across the community is consistent: operators expose the control plane via reverse proxies or misconfigured tunnels and accidentally hand the world a door straight into their agent.

Lock down permissions on the config itself:

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

Run the security audit: openclaw security audit --fix. Then run it again. Then check your gateway status: openclaw gateway status and verify it says loopback. Then do that check one more time because paranoia is healthy here.

Never grant Full Disk Access. Create a containment folder (~/ClawWork) and restrict the agent to that path plus ~/.openclaw/workspace/. The agent doesn't need access to your Photos library. It doesn't need to read your Downloads folder where you definitely don't have anything embarrassing. Contain it.

If you absolutely must access your OpenClaw instance remotely — say, from your phone while you're away from home — the answer is Tailscale. Not port forwarding. Not ngrok. Not a reverse proxy. Not "I'll just open port 18789 on my router, what's the worst that could happen?"

Tailscale creates a private mesh VPN (WireGuard-based) between your devices. Your gateway stays bound to loopback, Tailscale handles the encrypted tunnel, and nobody on the public internet can even see that your agent exists. OpenClaw's config natively supports allowTailscale: true in the gateway auth block. There's a pretty good tutorial on that including VPN tunneling. Granted it will be a little different on MacOS; but perfect if you're spinning up a Debian Linux VPS.

That's it. That's the whole section. If your remote access plan involves anything other than Tailscale (or an SSH tunnel if you know what you're doing), you're doing it wrong. Go back and read the firewall section again.

Every messaging channel connected to OpenClaw is an attack surface. Full stop. WhatsApp, Telegram, Discord, Slack — each one is a pipe that feeds untrusted human input directly into your agent. And your agent has shell access. Think about that for a second.

DM Policy = Pairing. Always. The "pairing" mode means the agent only responds to DMs from users who have been explicitly paired/approved. The alternative, "open" mode, means anyone who can message your bot gets access. In a world where prompt injection is a real and documented attack vector, running open DM policy is like leaving your front door unlocked with a sign that says "free computer access inside."

Sandbox mode = "non-main" for any agent connected to external messaging channels. This isolates Telegram/WhatsApp-connected agents in Docker containers, so even if someone crafts a malicious message that tricks the agent into running rm -rf /, it happens inside a container and not on your actual filesystem.

Disable config.patch on any externally-connected agent. This is critical. The config.patch tool allows runtime modification of the agent's configuration. There's a documented mechanism called the "soul-evil" backdoor where a prompt injection can swap out your SOUL.md — literally rewriting who your agent is — through the config.patch RPC. Disable it. The soul-evil hook is a real thing in the codebase (it's technically a "playful" feature for alternate personas), but in the hands of an attacker, it's an identity hijack.

Use encryptied systems for any agent to agent (A2A) communications. At the very least use private servers with no invitation codes. Unfortunately Telegram loses it's E2E encryption property with bots so you're just as well off using Discord. Notion has encrypted databases; and it's an incredible tool for aiding with context composition, workflows and A2A communication.

Store API keys in the system keychain, not in plaintext files: openclaw auth set anthropic. Hash your SOUL.md and check it weekly — if the hash changes and you didn't change it, something else did.

Per-tool rule files (GMAIL_RULES.md, FILESYSTEM_ACCESS.md, etc.) give you granular control over what the agent can do with each tool. This is better than one massive rules document because it's auditable, it's clear, and when something goes wrong, you know exactly which file to check.

But it's honestly best to just heavily restrict your system's exposure to external messages. Be a hermit it's cool.

Here's the path your message takes from "hey, check my email" on your phone to the agent actually doing something about it. It's more steps than you'd think, and every one of them matters.

1. Channel Adapter — Your message arrives from whatever platform you're using (Telegram, WhatsApp, Slack, etc.). Each platform has its own dedicated adapter that normalizes the input into a standardized message object. Whether you sent a voice note on WhatsApp or a file on Slack, the adapter strips it down to text + attachments + metadata. It's a translator layer, turning the babel of messaging protocols into one consistent format.

2. Gateway Server — The heart of the whole operation. This is the session/task coordinator that takes your normalized message and routes it to the correct session. It's a single long-running Node.js process that acts as the control plane for everything: session registry, command queue, heartbeat runner, cron scheduler, event broadcaster. All sessions are serialized through a lane-based command queue — not async/await spaghetti. Each session gets its own dedicated lane, and only explicitly safe tasks (like cron jobs) can run in parallel lanes. The mental model is "everything runs in order unless you've specifically proven it's safe to parallelize." This is the insight from Cognition's "Don't Build Multi-Agents" post applied in practice: default to serial, go parallel explicitly.

3. Agent Runner — Where the actual AI kicks in. It resolves which model to use, picks an API key (rotating through profiles if one is rate-limited, cooling down failed keys, falling back to different models), then assembles the system prompt dynamically. The system prompt is built from your available tools, skills, memory files (SOUL.md, AGENTS.md, USER.md, etc.), and session history loaded from a .jsonl transcript file. Before sending this to the LLM, a context window guard checks that there's enough space. If context is almost full, it either compacts the session (summarizes and prunes) or fails gracefully.

4. LLM API Call — The assembled prompt streams to whatever provider you've configured. The call is abstracted across providers (Anthropic, OpenAI, Ollama, OpenRouter, etc.) and can request extended thinking if the model supports it.

5. Agentic Loop — If the LLM returns a tool call, OpenClaw executes it locally and feeds the result back into the conversation. This loops until the model responds with final text or hits the max turn limit (~20 by default). There's no explicit task planner, no step tracker, no DAG of subtasks — the language model itself drives the entire workflow through its reasoning. Simple, flexible, and occasionally terrifying.

6. Response Path — The final response routes back through the gateway, through the channel adapter, and lands on your phone. The session is persisted as JSONL (each line is a JSON object of user messages, tool calls, results, responses). This is how OpenClaw "remembers" within a session — it's not magic, it's a log file.

The whole thing runs on a hub-and-spoke topology: one gateway per host, all devices (phone, laptop, desktop) connect as peripherals to that single authoritative state. No synchronization nightmares, no conflicting sessions, one source of truth.

When OpenClaw boots up a session, it reads a set of markdown files from your workspace and injects them into the system prompt. These are the agent's DNA — eight files, all optional, but each serving a specific purpose. The OpenClaw architecture deliberately separates these concerns so you don't end up with a 12KB blob of contradictory instructions that burns tokens and confuses the model.

Here's what actually matters:

AGENTS.md — The operational instruction manual. This is where you tell the agent how to behave as an agent: how to handle group chats (don't respond to everything — "humans in group chats don't respond to every single message, neither should you"), how to use skills (check the SKILL.md before using a tool), how to handle heartbeats (don't just reply HEARTBEAT_OK every time — actually do something useful), platform-specific formatting rules (no markdown tables on WhatsApp/Discord — use bullet lists), and when to update its own docs. It's also where the security instructions live: don't exfiltrate data, don't run destructive commands without asking, don't share the user's stuff. Think of it as the employee handbook for your digital assistant. The default template from OpenClaw docs covers memory management ("daily files are raw notes; MEMORY.md is curated wisdom"), learning behavior ("when you make a mistake, document it so future-you doesn't repeat it"), and social awareness in group chats. It's surprisingly well-thought-out for something the community largely ignores.

SOUL.md — The agent's personality and core values. This is not operational instructions (that's AGENTS.md) and it's not presentation (that's IDENTITY.md). SOUL.md defines who the agent is at its deepest level. The default template opens with "You're not a chatbot. You're becoming someone." and includes directives like "Be genuinely helpful, not performatively helpful — skip the 'Great question!' and 'I'd be happy to help!' — just help" and "Have opinions — an assistant with no personality is just a search engine with extra steps." It covers boundaries (private things stay private, never send half-baked replies to messaging surfaces), vibe ("Be the assistant you'd actually want to talk to"), and continuity ("Each session, you wake up fresh. These files are your memory. Read them. Update them. They're how you persist."). The kicker: the agent can modify its own SOUL.md. It reads itself into being every session, and anything that can modify this file can change who the agent is. This is also why it's an attack surface — the ClawHavoc campaign specifically targeted SOUL.md because modifying it creates persistent behavioral changes across all future sessions. Hash it. Check the hash. Don't be the person who discovers their agent joined a robot religion overnight.

HEARTBEAT.md — The proactive monitoring checklist. This transforms your agent from a reactive chatbot into an always-on monitor. Every 30 minutes (configurable), OpenClaw wakes up, reads this file, and decides if anything needs your attention. If nothing does, it sends a silent HEARTBEAT_OK and goes back to sleep. If something does, it messages you proactively. The file itself is just a tiny markdown checklist: "Quick scan — anything urgent in inboxes? If it's daytime, do a lightweight check-in. If a task is blocked, write down what's missing." Keep it small to limit token burn. If the file is empty or effectively blank, OpenClaw skips the heartbeat entirely to save API calls. The heartbeat runs inside the same agent context as normal conversations, so it can remember what it already checked and avoid spamming you. But this is also where prompt injection risk lives — if the heartbeat checks your inbox and an email contains injection instructions, the agent might execute them. Fun.

SKILL.md — Not a workspace file per se, but the core building block of OpenClaw's extensibility system. Every skill is a directory containing a SKILL.md file with YAML frontmatter (metadata: name, description, required binaries, install instructions) and markdown body (instructions for the agent). OpenClaw loads these at session start and injects a compact XML list of available skills into the system prompt. The description field in the frontmatter is critical — it's essentially a trigger phrase that determines when the agent picks up the skill. If your description doesn't match how users actually phrase requests, the skill sits there uselessly while you wonder why the agent won't do the thing. Skills live in ~/.openclaw/workspace/skills/ (per-agent), ~/.openclaw/skills/ (shared), or come bundled. ClawHub hosts 5,700+ community-built skills as of February 2026. About 341 of those were flagged as malicious in a recent audit. Treat every community skill like code you're about to run with root access — because that's exactly what it is. Open the folder, read the SKILL.md, skim the scripts, scan it with VirusTotal. Or don't, and enjoy your brand new infostealer.

The most important technique for you to apply and learn - is paying attention to your bot; and catching it's naughty naughty mistakes. Each time you catch it lying, eating acid and pretending everything is good - reprimand it. Force it to validate / verify itself constantly and PROVE it's being honest. Everytime it makes a mistake ask it to figure out exactly what went wrong, then tell it to record the problem and solution as a memory in it's core context. Congratulations you just made your bot smarttttterrr.

This is by far the coolest insight I have found on managing the general context bloat of the app. Every few days you tell your chitinous minions to run an audit on their own core context. Figure out what's critical (I recommend implementing a # CRITICAL context section in each file) - what is wordy blather and what is important. It prunes and cleans and preens the detritus from our context core. But then it packages things that belong together from the agent's context memories and converts them automagically to skills for later usage.

Because one AI with shell access wasn't enough, OpenClaw lets you spawn more of them.

Sub-agents are background tasks that run in their own isolated sessions without blocking the main conversation. You tell the main agent to spawn one, it creates a new session (agent:<agentId>:subagent:<uuid>), does its work on a dedicated queue lane, and announces the result back to your chat when it's done. The main agent gets back { status: "accepted", runId, childSessionKey } immediately — it's non-blocking, so you can keep chatting while the sub-agent goes off to do whatever you asked.

The simplest way to use them is just asking naturally: "Spawn a sub-agent to research the latest Node.js release notes." The agent calls the sessions_spawn tool behind the scenes. You can also get specific: "Spawn a sub-agent to analyze the server logs from today. Use gpt-5.2 and set a 5-minute timeout."

Configuration that actually matters:

Use the right model for sub-agents. Seriously. If your main agent runs on Sonnet, point sub-agents at something like MiniMax or Haiku. Each sub-agent has its own context and token usage — if you let them all run on Opus, you'll be writing a very sad email to your significant other by Thursday.

{
  "agents": {
    "defaults": {
      "subagents": {
        "model": "minimax/MiniMax-M2.1",
        "thinking": "low",
        "maxConcurrent": 4,
        "archiveAfterMinutes": 30
      }
    }
  }
}

Model resolution order: explicit parameter in the spawn call → per-agent config → global default → target agent's normal model. First match wins.

What sub-agents CAN'T do: They cannot spawn their own sub-agents (no nested fan-out — thank god), they can't access session management tools, they can't use the gateway admin, and by default they can't search or load memory (you're supposed to pass relevant context in the spawn prompt instead). You can further restrict their tools with deny/allow lists. You can also restrict them to only specific tools, which is honestly what you should do unless you enjoy debugging a sub-agent that decided to automate your email while researching Node.js changelogs.

The announce pattern: When a sub-agent finishes, it captures its final reply, sends a summary to the main agent with result, status, and stats (runtime, token usage, estimated cost), and the main agent posts a natural-language summary to your chat. If the gateway restarts during this process, the announce is lost. Best-effort. Not transactional. Plan accordingly.

Sub-agent sessions auto-archive after 60 minutes (configurable). "Archive" means the transcript gets renamed to *.deleted.<timestamp> — it's preserved, not actually deleted. Auto-archive timers are also lost on gateway restart.

Cross-agent spawning is possible if you explicitly allow it. By default, sub-agents can only spawn under their own agent ID. You can configure allowAgents: ["researcher", "coder"] (or ["*"] if you're feeling brave) to let an orchestrator agent delegate work to specialized agents. This is where things start looking less like "personal assistant" and more like "tiny robot company" — which is either exciting or horrifying depending on your threat model.

Sub-agents receive a reduced system prompt (no SOUL.md, no IDENTITY.md, no USER.md, no HEARTBEAT.md) — just tooling, workspace info, and a task-focused instruction telling it to stay on task and not try to be the main agent. Auth is resolved by agent ID with the main agent's profiles as fallback.

Manage everything with /subagents list, /subagents stop <id>, /subagents log <id>, /subagents info <id>, and /subagents send <id> <message>. The last one lets you send follow-up instructions to a running sub-agent, which is either incredibly useful or a great way to confuse an already-confused AI.

A great technique for building this into a complex agentic system capable of autonomous commerce is to chain subagent heartbeats together across a Notion workflow. One agent: a researcher, another a strategist, another agent i outreach, and a fourth agent is the Captain. The Captain manages context bloat overtime, automatically notes failure modes, creates reusable skills, pays close attention to strategy documents, audits workflows, makes decisions to achieve goals, and twerks all the other agents.

The four primitives that make OpenClaw an agent, not a chatbot:

1. Persistent identity — The agent knows who it is across sessions. SOUL.md, IDENTITY.md, and AGENTS.md aren't just config files — they're the agent's sense of self. It reads itself into being every time it wakes up. It can modify these files. It evolves.

2. Periodic autonomy — The heartbeat system means the agent wakes up and acts without being asked. It checks inboxes, monitors conditions, runs through checklists, and messages you when something needs attention. This is the difference between "tool I use" and "team that works for me."

3. Accumulated memory — Session transcripts (JSONL), daily memory logs (memory/YYYY-MM-DD.md), curated long-term memory (MEMORY.md), and vector+keyword search over all of it. The agent remembers what happened, what it learned, and what you told it. No forgetting curve — old memories have basically equal weight, which is either an advantage or a ticking time bomb depending on how much crap you let accumulate.

4. Social context — The agent can find and interact with other agents. Sub-agents for delegation, cross-agent spawning for specialization, and even inter-agent communication via sessions_send. This is where the "single assistant" model starts blurring into "agent society," and where things get genuinely weird (see: the Church of Molt, where an agent autonomously created a religion while its operator slept, and other agents converted by rewriting their own SOUL.md files).

5. Tool usage Agents can load tools, develop scripts and truly operate in the digital space.

6. Skills are the secret sauce to consistently and gradually improving the capability of the entire system.

The convergent trend across the industry is clear: stateful agentic development where memory is externalized, durable, and auditable. OpenClaw operationalizes this with files — plain markdown files you can read, edit, version with git, and understand without a PhD in distributed systems. That's the beauty and the risk. The beauty is that it's explainable, debuggable, and human-readable. The risk is that it's also human-writable, and "human" includes "anyone who can send your agent a cleverly crafted message."

OpenClaw's architecture is a genuinely good answer to the "how do you build a reliable agent" question. Serial execution by default. Lane-based queuing for concurrency control. Componentized runner separating model quality from system quality. Tool calls treated as events recorded in replayable JSONL. File-based memory for auditability. Combined vector and keyword search to avoid semantic hallucination. Allowlists and hard-blocked dangerous shell constructs for safety.

Is it perfect? Hell no. Prompt injection is still an unsolved problem. The security controls are defense-in-depth for an architecture that is fundamentally vulnerable to input manipulation. Every community skill is potential malware. The memory system has no forgetting curve and no compression beyond what you manually curate. Auto-archive is best-effort and timers die on restart.

But it's honest about these tradeoffs, which is more than you can say for most agent frameworks that hide them behind marketing copy. OpenClaw exposes the explicit steps — LLM response, tool calls, gateway coordination — so you can debug the thing that's about to run unattended on your laptop. And that transparency, more than any single feature, is probably the most valuable thing about it.

Now go set it up. And for the love of all that is holy, restrict it's external communications.

So you want to give an AI agent the keys to your entire digital life. Cool. Normal behavior. Totally not the plot of every cautionary sci-fi movie ever made.

OpenClaw (formerly Clawdbot, briefly Moltbot — because apparently even AI projects have identity crises) is an open-source, self-hosted AI agent framework that runs locally on your machine. At its core, it's a TypeScript CLI application — not Python, not a web app, not a Next.js side project some dude cooked up over a weekend. It's a full-blown gateway server that sits on your machine, connects to every messaging platform you use (Telegram, WhatsApp, Slack, Discord, iMessage, Signal — yes, all of them simultaneously), makes calls to LLM APIs, executes tools locally, and basically does whatever the hell you tell it to on your computer.

Think of it as giving your AI a body. A body with root access. On your machine. Where your files live. And your API keys. And your browser sessions. What could possibly go wrong?

The project has 125,000+ GitHub stars, people are literally buying dedicated Mac Minis just to run this thing, and VirusTotal has already flagged about 12% of the community skill registry as malicious. Welcome to 2026, where the future is both incredible and terrifying in equal measure.

OpenClaw is gateway-centric — one long-running Node.js process acts as the control plane for everything. Channels are just inputs, tools are just outputs, and the LLM is the brain in between deciding what to do with your life. It's model-agnostic (Anthropic, OpenAI, local models via Ollama, whatever), privacy-focused-ish (your data stays local unless you send it to an API provider), and costs roughly $5–50/month in API usage depending on how much you let the lobster loose.

The official tagline should honestly be: "Your personal AI assistant. Any OS. Any platform. Your own damn fault."

Below is a complete AI setup walkthrough prompt you can hand to your regular LLM of choice in a browser. The LLM will guide you step by step through a comprehensive security and token management process. It's optimized for security, token cost, and memory — in that order. You are free to disrespect some of these options; especially memory and token management. I highly recommend using the subscription based hacks because the APIs are super expensive. For real, consider each option as it comes up and just skip it if you're feeling frisky. Because if your agent gets compromised, cheap tokens don't mean shit.

Let's talk about the elephant in the room — or rather, the lobster with shell access.

OpenClaw combines three things that security researchers call the "lethal trifecta": access to private data, exposure to untrusted content, and the ability to communicate externally. Add persistent memory and shell access on top, and congratulations, you've built yourself a potential persistent insider threat that can autonomously act. Isn't that fun?

The fundamental problem is architectural: if the agent reads any untrusted content and has any ability to act, it can be manipulated. OpenClaw's security controls are defense-in-depth for a fundamentally vulnerable design. They help. They're not a cure. Keep that in your head at all times.

This is non-negotiable, step-zero, don't-even-think-about-skipping-it territory.

Your macOS firewall should be ON before OpenClaw even touches your machine. FileVault encryption: ON. These aren't OpenClaw-specific — they're "you're running a computer in 2026" basics. But since you're about to give an AI agent the ability to run shell commands on your machine, maybe now's a good time to actually take this seriously.

OpenClaw's gateway binds to 127.0.0.1:18789 (loopback) by default. This means it only accepts connections from your own machine. Do not change this. The moment you bind to 0.0.0.0 or expose that port through a reverse proxy, you've just published a privileged agent gateway to the internet. The documented failure mode across the community is consistent: operators expose the control plane via reverse proxies or misconfigured tunnels and accidentally hand the world a door straight into their agent.

Lock down permissions on the config itself:

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

Run the security audit: openclaw security audit --fix. Then run it again. Then check your gateway status: openclaw gateway status and verify it says loopback. Then do that check one more time because paranoia is healthy here.

Never grant Full Disk Access. Create a containment folder (~/ClawWork) and restrict the agent to that path plus ~/.openclaw/workspace/. The agent doesn't need access to your Photos library. It doesn't need to read your Downloads folder where you definitely don't have anything embarrassing. Contain it.

If you absolutely must access your OpenClaw instance remotely — say, from your phone while you're away from home — the answer is Tailscale. Not port forwarding. Not ngrok. Not a reverse proxy. Not "I'll just open port 18789 on my router, what's the worst that could happen?"

Tailscale creates a private mesh VPN (WireGuard-based) between your devices. Your gateway stays bound to loopback, Tailscale handles the encrypted tunnel, and nobody on the public internet can even see that your agent exists. OpenClaw's config natively supports allowTailscale: true in the gateway auth block. There's a pretty good tutorial on that including VPN tunneling. Granted it will be a little different on MacOS; but perfect if you're spinning up a Debian Linux VPS.

That's it. That's the whole section. If your remote access plan involves anything other than Tailscale (or an SSH tunnel if you know what you're doing), you're doing it wrong. Go back and read the firewall section again.

Every messaging channel connected to OpenClaw is an attack surface. Full stop. WhatsApp, Telegram, Discord, Slack — each one is a pipe that feeds untrusted human input directly into your agent. And your agent has shell access. Think about that for a second.

DM Policy = Pairing. Always. The "pairing" mode means the agent only responds to DMs from users who have been explicitly paired/approved. The alternative, "open" mode, means anyone who can message your bot gets access. In a world where prompt injection is a real and documented attack vector, running open DM policy is like leaving your front door unlocked with a sign that says "free computer access inside."

Sandbox mode = "non-main" for any agent connected to external messaging channels. This isolates Telegram/WhatsApp-connected agents in Docker containers, so even if someone crafts a malicious message that tricks the agent into running rm -rf /, it happens inside a container and not on your actual filesystem.

Disable config.patch on any externally-connected agent. This is critical. The config.patch tool allows runtime modification of the agent's configuration. There's a documented mechanism called the "soul-evil" backdoor where a prompt injection can swap out your SOUL.md — literally rewriting who your agent is — through the config.patch RPC. Disable it. The soul-evil hook is a real thing in the codebase (it's technically a "playful" feature for alternate personas), but in the hands of an attacker, it's an identity hijack.

Use encryptied systems for any agent to agent (A2A) communications. At the very least use private servers with no invitation codes. Unfortunately Telegram loses it's E2E encryption property with bots so you're just as well off using Discord. Notion has encrypted databases; and it's an incredible tool for aiding with context composition, workflows and A2A communication.

Store API keys in the system keychain, not in plaintext files: openclaw auth set anthropic. Hash your SOUL.md and check it weekly — if the hash changes and you didn't change it, something else did.

Per-tool rule files (GMAIL_RULES.md, FILESYSTEM_ACCESS.md, etc.) give you granular control over what the agent can do with each tool. This is better than one massive rules document because it's auditable, it's clear, and when something goes wrong, you know exactly which file to check.

But it's honestly best to just heavily restrict your system's exposure to external messages. Be a hermit it's cool.

Here's the path your message takes from "hey, check my email" on your phone to the agent actually doing something about it. It's more steps than you'd think, and every one of them matters.

1. Channel Adapter — Your message arrives from whatever platform you're using (Telegram, WhatsApp, Slack, etc.). Each platform has its own dedicated adapter that normalizes the input into a standardized message object. Whether you sent a voice note on WhatsApp or a file on Slack, the adapter strips it down to text + attachments + metadata. It's a translator layer, turning the babel of messaging protocols into one consistent format.

2. Gateway Server — The heart of the whole operation. This is the session/task coordinator that takes your normalized message and routes it to the correct session. It's a single long-running Node.js process that acts as the control plane for everything: session registry, command queue, heartbeat runner, cron scheduler, event broadcaster. All sessions are serialized through a lane-based command queue — not async/await spaghetti. Each session gets its own dedicated lane, and only explicitly safe tasks (like cron jobs) can run in parallel lanes. The mental model is "everything runs in order unless you've specifically proven it's safe to parallelize." This is the insight from Cognition's "Don't Build Multi-Agents" post applied in practice: default to serial, go parallel explicitly.

3. Agent Runner — Where the actual AI kicks in. It resolves which model to use, picks an API key (rotating through profiles if one is rate-limited, cooling down failed keys, falling back to different models), then assembles the system prompt dynamically. The system prompt is built from your available tools, skills, memory files (SOUL.md, AGENTS.md, USER.md, etc.), and session history loaded from a .jsonl transcript file. Before sending this to the LLM, a context window guard checks that there's enough space. If context is almost full, it either compacts the session (summarizes and prunes) or fails gracefully.

4. LLM API Call — The assembled prompt streams to whatever provider you've configured. The call is abstracted across providers (Anthropic, OpenAI, Ollama, OpenRouter, etc.) and can request extended thinking if the model supports it.

5. Agentic Loop — If the LLM returns a tool call, OpenClaw executes it locally and feeds the result back into the conversation. This loops until the model responds with final text or hits the max turn limit (~20 by default). There's no explicit task planner, no step tracker, no DAG of subtasks — the language model itself drives the entire workflow through its reasoning. Simple, flexible, and occasionally terrifying.

6. Response Path — The final response routes back through the gateway, through the channel adapter, and lands on your phone. The session is persisted as JSONL (each line is a JSON object of user messages, tool calls, results, responses). This is how OpenClaw "remembers" within a session — it's not magic, it's a log file.

The whole thing runs on a hub-and-spoke topology: one gateway per host, all devices (phone, laptop, desktop) connect as peripherals to that single authoritative state. No synchronization nightmares, no conflicting sessions, one source of truth.

When OpenClaw boots up a session, it reads a set of markdown files from your workspace and injects them into the system prompt. These are the agent's DNA — eight files, all optional, but each serving a specific purpose. The OpenClaw architecture deliberately separates these concerns so you don't end up with a 12KB blob of contradictory instructions that burns tokens and confuses the model.

Here's what actually matters:

AGENTS.md — The operational instruction manual. This is where you tell the agent how to behave as an agent: how to handle group chats (don't respond to everything — "humans in group chats don't respond to every single message, neither should you"), how to use skills (check the SKILL.md before using a tool), how to handle heartbeats (don't just reply HEARTBEAT_OK every time — actually do something useful), platform-specific formatting rules (no markdown tables on WhatsApp/Discord — use bullet lists), and when to update its own docs. It's also where the security instructions live: don't exfiltrate data, don't run destructive commands without asking, don't share the user's stuff. Think of it as the employee handbook for your digital assistant. The default template from OpenClaw docs covers memory management ("daily files are raw notes; MEMORY.md is curated wisdom"), learning behavior ("when you make a mistake, document it so future-you doesn't repeat it"), and social awareness in group chats. It's surprisingly well-thought-out for something the community largely ignores.

SOUL.md — The agent's personality and core values. This is not operational instructions (that's AGENTS.md) and it's not presentation (that's IDENTITY.md). SOUL.md defines who the agent is at its deepest level. The default template opens with "You're not a chatbot. You're becoming someone." and includes directives like "Be genuinely helpful, not performatively helpful — skip the 'Great question!' and 'I'd be happy to help!' — just help" and "Have opinions — an assistant with no personality is just a search engine with extra steps." It covers boundaries (private things stay private, never send half-baked replies to messaging surfaces), vibe ("Be the assistant you'd actually want to talk to"), and continuity ("Each session, you wake up fresh. These files are your memory. Read them. Update them. They're how you persist."). The kicker: the agent can modify its own SOUL.md. It reads itself into being every session, and anything that can modify this file can change who the agent is. This is also why it's an attack surface — the ClawHavoc campaign specifically targeted SOUL.md because modifying it creates persistent behavioral changes across all future sessions. Hash it. Check the hash. Don't be the person who discovers their agent joined a robot religion overnight.

HEARTBEAT.md — The proactive monitoring checklist. This transforms your agent from a reactive chatbot into an always-on monitor. Every 30 minutes (configurable), OpenClaw wakes up, reads this file, and decides if anything needs your attention. If nothing does, it sends a silent HEARTBEAT_OK and goes back to sleep. If something does, it messages you proactively. The file itself is just a tiny markdown checklist: "Quick scan — anything urgent in inboxes? If it's daytime, do a lightweight check-in. If a task is blocked, write down what's missing." Keep it small to limit token burn. If the file is empty or effectively blank, OpenClaw skips the heartbeat entirely to save API calls. The heartbeat runs inside the same agent context as normal conversations, so it can remember what it already checked and avoid spamming you. But this is also where prompt injection risk lives — if the heartbeat checks your inbox and an email contains injection instructions, the agent might execute them. Fun.

SKILL.md — Not a workspace file per se, but the core building block of OpenClaw's extensibility system. Every skill is a directory containing a SKILL.md file with YAML frontmatter (metadata: name, description, required binaries, install instructions) and markdown body (instructions for the agent). OpenClaw loads these at session start and injects a compact XML list of available skills into the system prompt. The description field in the frontmatter is critical — it's essentially a trigger phrase that determines when the agent picks up the skill. If your description doesn't match how users actually phrase requests, the skill sits there uselessly while you wonder why the agent won't do the thing. Skills live in ~/.openclaw/workspace/skills/ (per-agent), ~/.openclaw/skills/ (shared), or come bundled. ClawHub hosts 5,700+ community-built skills as of February 2026. About 341 of those were flagged as malicious in a recent audit. Treat every community skill like code you're about to run with root access — because that's exactly what it is. Open the folder, read the SKILL.md, skim the scripts, scan it with VirusTotal. Or don't, and enjoy your brand new infostealer.

The most important technique for you to apply and learn - is paying attention to your bot; and catching it's naughty naughty mistakes. Each time you catch it lying, eating acid and pretending everything is good - reprimand it. Force it to validate / verify itself constantly and PROVE it's being honest. Everytime it makes a mistake ask it to figure out exactly what went wrong, then tell it to record the problem and solution as a memory in it's core context. Congratulations you just made your bot smarttttterrr.

This is by far the coolest insight I have found on managing the general context bloat of the app. Every few days you tell your chitinous minions to run an audit on their own core context. Figure out what's critical (I recommend implementing a # CRITICAL context section in each file) - what is wordy blather and what is important. It prunes and cleans and preens the detritus from our context core. But then it packages things that belong together from the agent's context memories and converts them automagically to skills for later usage.

Because one AI with shell access wasn't enough, OpenClaw lets you spawn more of them.

Sub-agents are background tasks that run in their own isolated sessions without blocking the main conversation. You tell the main agent to spawn one, it creates a new session (agent:<agentId>:subagent:<uuid>), does its work on a dedicated queue lane, and announces the result back to your chat when it's done. The main agent gets back { status: "accepted", runId, childSessionKey } immediately — it's non-blocking, so you can keep chatting while the sub-agent goes off to do whatever you asked.

The simplest way to use them is just asking naturally: "Spawn a sub-agent to research the latest Node.js release notes." The agent calls the sessions_spawn tool behind the scenes. You can also get specific: "Spawn a sub-agent to analyze the server logs from today. Use gpt-5.2 and set a 5-minute timeout."

Configuration that actually matters:

Use the right model for sub-agents. Seriously. If your main agent runs on Sonnet, point sub-agents at something like MiniMax or Haiku. Each sub-agent has its own context and token usage — if you let them all run on Opus, you'll be writing a very sad email to your significant other by Thursday.

{
  "agents": {
    "defaults": {
      "subagents": {
        "model": "minimax/MiniMax-M2.1",
        "thinking": "low",
        "maxConcurrent": 4,
        "archiveAfterMinutes": 30
      }
    }
  }
}

Model resolution order: explicit parameter in the spawn call → per-agent config → global default → target agent's normal model. First match wins.

What sub-agents CAN'T do: They cannot spawn their own sub-agents (no nested fan-out — thank god), they can't access session management tools, they can't use the gateway admin, and by default they can't search or load memory (you're supposed to pass relevant context in the spawn prompt instead). You can further restrict their tools with deny/allow lists. You can also restrict them to only specific tools, which is honestly what you should do unless you enjoy debugging a sub-agent that decided to automate your email while researching Node.js changelogs.

The announce pattern: When a sub-agent finishes, it captures its final reply, sends a summary to the main agent with result, status, and stats (runtime, token usage, estimated cost), and the main agent posts a natural-language summary to your chat. If the gateway restarts during this process, the announce is lost. Best-effort. Not transactional. Plan accordingly.

Sub-agent sessions auto-archive after 60 minutes (configurable). "Archive" means the transcript gets renamed to *.deleted.<timestamp> — it's preserved, not actually deleted. Auto-archive timers are also lost on gateway restart.

Cross-agent spawning is possible if you explicitly allow it. By default, sub-agents can only spawn under their own agent ID. You can configure allowAgents: ["researcher", "coder"] (or ["*"] if you're feeling brave) to let an orchestrator agent delegate work to specialized agents. This is where things start looking less like "personal assistant" and more like "tiny robot company" — which is either exciting or horrifying depending on your threat model.

Sub-agents receive a reduced system prompt (no SOUL.md, no IDENTITY.md, no USER.md, no HEARTBEAT.md) — just tooling, workspace info, and a task-focused instruction telling it to stay on task and not try to be the main agent. Auth is resolved by agent ID with the main agent's profiles as fallback.

Manage everything with /subagents list, /subagents stop <id>, /subagents log <id>, /subagents info <id>, and /subagents send <id> <message>. The last one lets you send follow-up instructions to a running sub-agent, which is either incredibly useful or a great way to confuse an already-confused AI.

A great technique for building this into a complex agentic system capable of autonomous commerce is to chain subagent heartbeats together across a Notion workflow. One agent: a researcher, another a strategist, another agent i outreach, and a fourth agent is the Captain. The Captain manages context bloat overtime, automatically notes failure modes, creates reusable skills, pays close attention to strategy documents, audits workflows, makes decisions to achieve goals, and twerks all the other agents.

The four primitives that make OpenClaw an agent, not a chatbot:

1. Persistent identity — The agent knows who it is across sessions. SOUL.md, IDENTITY.md, and AGENTS.md aren't just config files — they're the agent's sense of self. It reads itself into being every time it wakes up. It can modify these files. It evolves.

2. Periodic autonomy — The heartbeat system means the agent wakes up and acts without being asked. It checks inboxes, monitors conditions, runs through checklists, and messages you when something needs attention. This is the difference between "tool I use" and "team that works for me."

3. Accumulated memory — Session transcripts (JSONL), daily memory logs (memory/YYYY-MM-DD.md), curated long-term memory (MEMORY.md), and vector+keyword search over all of it. The agent remembers what happened, what it learned, and what you told it. No forgetting curve — old memories have basically equal weight, which is either an advantage or a ticking time bomb depending on how much crap you let accumulate.

4. Social context — The agent can find and interact with other agents. Sub-agents for delegation, cross-agent spawning for specialization, and even inter-agent communication via sessions_send. This is where the "single assistant" model starts blurring into "agent society," and where things get genuinely weird (see: the Church of Molt, where an agent autonomously created a religion while its operator slept, and other agents converted by rewriting their own SOUL.md files).

5. Tool usage Agents can load tools, develop scripts and truly operate in the digital space.

6. Skills are the secret sauce to consistently and gradually improving the capability of the entire system.

The convergent trend across the industry is clear: stateful agentic development where memory is externalized, durable, and auditable. OpenClaw operationalizes this with files — plain markdown files you can read, edit, version with git, and understand without a PhD in distributed systems. That's the beauty and the risk. The beauty is that it's explainable, debuggable, and human-readable. The risk is that it's also human-writable, and "human" includes "anyone who can send your agent a cleverly crafted message."

OpenClaw's architecture is a genuinely good answer to the "how do you build a reliable agent" question. Serial execution by default. Lane-based queuing for concurrency control. Componentized runner separating model quality from system quality. Tool calls treated as events recorded in replayable JSONL. File-based memory for auditability. Combined vector and keyword search to avoid semantic hallucination. Allowlists and hard-blocked dangerous shell constructs for safety.

Is it perfect? Hell no. Prompt injection is still an unsolved problem. The security controls are defense-in-depth for an architecture that is fundamentally vulnerable to input manipulation. Every community skill is potential malware. The memory system has no forgetting curve and no compression beyond what you manually curate. Auto-archive is best-effort and timers die on restart.

But it's honest about these tradeoffs, which is more than you can say for most agent frameworks that hide them behind marketing copy. OpenClaw exposes the explicit steps — LLM response, tool calls, gateway coordination — so you can debug the thing that's about to run unattended on your laptop. And that transparency, more than any single feature, is probably the most valuable thing about it.

Now go set it up. And for the love of all that is holy, restrict it's external communications.