OpenClaw Architecture and Insights

• Role: It does not think, reason, or decide. Its sole job is to accept inputs, manage connections, and route traffic.
• Hub-and-Spoke Design: It separates the interface layer (WhatsApp, Slack, CLI) from the intelligence layer. This ensures that if a channel fails, the agent remains alive.
• Typed Protocol: It enforces a strictly typed protocol. Every WebSocket frame is validated against a JSON schema to ensure stability before it ever reaches an agent.
• Device Identity: It handles security handshakes. Clients (like the CLI or Mobile Nodes) must cryptographically sign a challenge to prove their identity before connecting.

• Authentication: They handle specific login methods, such as QR pairing for WhatsApp (via Baileys), Bot Tokens for Discord, or native macOS integration for iMessage.
• Normalisation: They parse incoming data—extracting text, handling media attachments, and processing emoji reactions—into a standardised format the Gateway understands.
• Access Control: Security happens here first. Adapters check Allowlists (e.g., is this phone number allowed?) and Pairing Policies before a message is even processed.
• Formatting: They convert the agent’s generic markdown response into the specific dialect required by the platform (e.g., converting bolding syntax for Slack vs. WhatsApp).

1. Messages: Standard chats from humans via adapters like Whatsapp, Telegram etc
2. Heartbeats: A timer (default: 30 mins) that prompts the agent to “check for tasks.” If no action is needed, the system suppresses the response. This allows the agent to self-initiate work.
3. Cron Jobs: Scheduled events with specific instructions (e.g., “9:00 AM: Check my email”). This enables routine maintenance or daily briefings.
4. Hooks: Internal triggers fired by state changes, such as the system booting up or an agent finishing a task.
5. Webhooks: Notifications from external systems (e.g., a GitHub PR or Jira ticket) that trigger the agent to act immediately.
6. Agent-to-Agent: Messages sent between agents to collaborate. A “researcher” agent can finish a task and queue a job for a “writer” agent.

• Markdown Storage: Memory is stored in plain text files you can read and edit (MEMORY.md for facts, 2026-01-26.md for daily logs).
• Two-Layer System:
  • Daily Memory: An append-only log of everything that happened today.
  • Long-Term Memory: Curated facts (e.g., “User prefers TypeScript”).
• Hybrid Search: It retrieves memory using both Semantic Search (vector embeddings for meaning) and Keyword Search (exact matches for specific IDs or keys).
  • Example: Memory contains: “Chose PostgreSQL for production database.” Later, you ask — semantic search finds it. “What is POSTGRES_URL?” — keyword search finds it.
  • Hybrid retrieval handles both intent and precision — something pure vector systems often miss.
• Memory Flush & Compaction: To manage context limits, the system “compacts” (summarizes) old logs. Crucially, it performs a Memory Flush first—extracting key facts to persistent storage—before the raw logs are compressed, ensuring data isn’t lost.
• Debounced Indexing: Why Memory Doesn’t Thrash
  • Memory files change frequently: multiple writes per minute, tool edits, manual edits.
  • Indexing after every keystroke would be wasteful. OpenClaw waits briefly before indexing changes. If multiple edits happen quickly, they are collapsed into one indexing pass.
  • Example: Between 2:00–2:03 PM — three notes appended, one preference updated, a summary written. Instead of indexing five times, OpenClaw indexes once.
  • This enables: fast interaction, stable embeddings, low compute overhead.

Goal: Deeply personal, always-available assistant on your Mac (or Linux) with full host access, iMessage/voice wake, proactive heartbeats, and secure phone access.

Architecture (Solo)

[ You + Phone + Devices ]
           │
           ▼
Multi-Channel Inputs (WhatsApp, iMessage, Telegram, CLI, Web)
           │
           ▼
Channel Adapter (normalize, auth, media)
           │
           ▼
Gateway Server (native, port 18789, runs as daemon)
      ┌─────────────┴─────────────┐
      ▼                           ▼
Lane Queue (serial per session)   Control Plane (Menu Bar + Dashboard)
           │
           ▼
Brain / Agent Runner (LLM selector, prompt builder, context guard)
           ↻
     Agentic Loop (think → act → observe)
           │
           ▼
Tool Execution (full host access – sandbox disabled)
├── Browser (semantic a11y)
├── Filesystem (full ~/)
├── Shell (allowlist optional)
├── Code REPL, APIs, etc.
           │
           ▼
Persistent Memory (~/clawd/ + MEMORY.md + hybrid search)
           │
Security & Guardrails (light – trusted main session)
           │
Response Path (streaming back to channels)

Key decisions:

• Native install (not Docker) for lowest latency and native macOS features.
• Sandbox disabled or permissive (you trust yourself).
• Tailscale for secure remote access.
• Full filesystem & proactive features enabled.

Step-by-Step Setup (Solo)

1. Install OpenClaw — curl -fsSL https://openclaw.ai/install.sh | bash
2. Run onboarding wizard — openclaw onboard --install-daemon (sets up API keys, default LLM, LaunchAgent on macOS).
3. Set up Tailscale — Install on Mac and phone, same tailnet; expose gateway: sudo tailscale serve https://openclaw:18789 --https=443
4. Configure trusted main session — Edit ~/.openclaw/config.json: sandbox disabled for main, heartbeatInterval, dailyBriefing.
5. Enable channels — iMessage, WhatsApp/Telegram bridges; test with a message.
6. Start / verify — openclaw gateway status and openclaw dashboard

Adding Skills & Plugins (Solo) — From ClawHub: chat “install skill research-paper” or openclaw skills install research-paper. From GitHub: openclaw skills install https://github.com/user/my-skill. Create your own: add SKILL.md in ~/.openclaw/skills/<name>/, then openclaw skills reload. Plugins: openclaw plugins install @openclaw/msteams or drop into ~/.openclaw/plugins/. Skills run with full host privileges — review before enabling.

Security Tips (Solo) — Use Tailscale only; openclaw skills audit before installing; keep credentials in a separate workspace; regular openclaw update.

Goal: 24/7 centralized team brain with strict isolation, shared company memory, and controlled access for 5–50 users.

Architecture (SMB)

[ Team Members (Slack/Discord/Teams) ]
           │
           ▼
Public Channels + Webhooks → Gateway (Docker container)
           │
           ▼
Lane Queues (per user / per channel session)
           │
           ▼
Brain / Agent Runner (multi-persona routing)
           ↻
     Agentic Loop
           │
           ▼
Tool Execution Engine (strict Docker sandbox per turn)
├── Ephemeral containers (no host access)
├── Browser, Filesystem (rw in /workspace only)
├── Shell (very strict allowlist)
           │
           ▼
Persistent Shared Memory (mounted volume: MEMORY.md + company skills)
           │
Security Layer (allowlists, domain auth, budgets, audit)
           │
           ▼
Response Path (streaming + typing indicators)
           │
Control Plane (accessible only via SSH tunnel / Tailscale)

Key decisions:

• Dockerized on Linux VPS for 24/7 uptime + easy scaling.
• Strict sandbox for every non-admin session.
• Persistent volume for shared company brain.
• Admin-only skill/plugin approval.

Step-by-Step Setup (SMB)

1. Provision a VPS (Ubuntu 22.04+, 2 vCPU / 4 GB RAM, 20+ GB SSD) – Hetzner, DigitalOcean, Fly.io, etc.
2. Install Docker & prerequisites — sudo apt update && sudo apt install curl git docker.io docker-compose-plugin and sudo usermod -aG docker $USER
3. Create project & persistent volume — mkdir ~/openclaw-team && cd ~/openclaw-team
4. Deploy with official Docker setup — docs: curl -fsSL https://docs.openclaw.ai/install/docker.sh | bash
5. Configure strict sandbox & multi-user settings — Edit mounted config.json (sandbox mode non-main, security allowFrom, channels.requireMention).
6. Connect team channels (Slack/Discord bot tokens) via onboarding inside container.
7. Secure control plane — Dashboard/admin only via SSH tunnel or Tailscale; optional Tailscale Funnel for webhooks.
8. Start & monitor — docker compose up -d and docker compose logs -f

Adding Skills & Plugins (SMB – governed) — Admin-only: openclaw skills install --admin research-paper. Company skills: private Git repo, mount at /skills/company, config skills.sources. Team flow: request in DM → admin reviews → install → announce. Plugins: same admin-only process.

Security & Governance (SMB) — Audit every skill with openclaw skills audit; resource budgets per user/session; append-only audit logs; capability tokens; regular container restarts and volume backups.

The Plugin Architecture

The system relies on a discovery-based model located in the extensions/ directory. It does not require you to hardcode imports into the main server file.

• The Loader: The plugin loader (src/plugins/loader.ts) scans the workspace packages.
• Identification: It looks for a specific openclaw.extensions field inside the package.json of installed packages.
• Validation & Hot-Loading: It validates the plugin against declared JSON schemas and “hot-loads” them when the corresponding configuration is present. This means you can drop a plugin into the folder, configure it, and it works immediately.

The Four Types of Plugins

OpenClaw supports extensibility across four distinct layers of the architecture:

1. Channel Plugins: Purpose: To connect OpenClaw to messaging platforms not supported out of the box. Examples: Microsoft Teams, Matrix, Mattermost, Signal. They implement the standard “Adapter” interface (auth, parsing, formatting).
2. Tool Plugins: Purpose: To give the agent new capabilities beyond the standard Bash/Browser tools. Examples: Spotify controller, Jira integration, Home Assistant connector.
3. Memory Plugins: Purpose: To swap out the underlying storage engine. Examples: Vector Database (Pinecone, Weaviate) or Knowledge Graph.
4. Provider Plugins: Purpose: To change the “brain” of the agent. Examples: Self-hosted LLMs (Ollama) or new API providers.

The Skill Registry & Marketplace

While Plugins extend the system, Skills extend the agent’s knowledge.

• The Marketplace: Over 31,000 skills — like “apps” for your agent.
• Structure: A skill is defined by a SKILL.md file in skills/<skill>/. It acts as a playbook or SOP.
• Link: Plugins = capability (code). Skills = instruction (knowledge). Plugins give the employee new equipment; Skills give the handbook on how to use it.

The Distinction: Code vs. Markdown

• Plugins (Code): Live in extensions/, TypeScript/JavaScript, register tools via api.registerTool.
• Skills (Prompts): Live in skills/ as SKILL.md, Markdown SOPs/playbooks.

The Workflow: (1) Plugin Load → registers e.g. jira_create_ticket. (2) Skill Discovery → finds “How to manage projects”. (3) Injection → when you say “file a bug”, relevant Skill is injected. (4) Execution → agent calls the tool from the Plugin.

Layer 1: Network Isolation (The “Localhost” Default) — By default the Gateway binds to 127.0.0.1. Remote access: SSH Tunneling (e.g. ssh -N -L 18789:127.0.0.1:18789) or Tailscale (Serve for Tailnet-only, Funnel for public with password).

Layer 2: Device Identity & Cryptographic Handshakes — Device Pairing for CLI, Mobile Nodes, Web UI. Challenge-response; new devices need admin approval and get a device token.

Layer 3: Channel Access Control — DM Pairing (unknown users get pairing code; block until openclaw pairing approve). Allowlists for specific numbers/usernames. Group policies e.g. requireMention: true.

Layer 4: Docker Sandboxing — Main session (you) runs on host. Untrusted sessions (dm/group) run in ephemeral Docker containers; e.g. rm -rf / only hits the container. Configurable granularity and strictness.

Layer 5: Memory Safeguards — Secret detection/redaction before writing to memory. Fact verification (claims vs verified facts) to limit memory poisoning.

Risks and Mitigations