Five-Layer Architecture: The Complete Journey of a Message from Arrival to Execution

Chapter 5: Five-Layer Architecture Dissected: The Complete Chain from Message Arrival to Execution

5.1 Five-Layer Architecture Overview

OpenClaw's architecture is designed as a strict five-layer model, with each layer having clear responsibility boundaries and technical implementations. This layered design allows each layer to evolve independently without impacting the stability of other layers.

┌─────────────────────────────────────────────────────────────────┐
│  Layer 1: Input Sources                                         │
│  WhatsApp / Telegram / Slack / Discord / Email / Webhook / ...  │
└─────────────────────────┬───────────────────────────────────────┘
                          │ Raw platform messages
                          ▼
┌─────────────────────────────────────────────────────────────────┐
│  Layer 2: Integration Gateway                                   │
│  Channel Bridge │ Session Manager │ Command Queue │ Plugin Registry │
└─────────────────────────┬───────────────────────────────────────┘
                          │ InternalMessage (standardized)
                          ▼
┌─────────────────────────────────────────────────────────────────┐
│  Layer 3: Agent Core (Pi)                                       │
│  pi-ai │ pi-agent-core │ ReAct Loop │ Tool Registry             │
└─────────────────────────┬───────────────────────────────────────┘
                          │ ToolCall requests
                          ▼
┌─────────────────────────────────────────────────────────────────┐
│  Layer 4: Action Layer                                          │
│  Tool Executor │ HITL Approval │ Integration Adapters           │
└─────────────────────────┬───────────────────────────────────────┘
                          │ API calls / system operations
                          ▼
┌─────────────────────────────────────────────────────────────────┐
│  Layer 5: External Systems                                      │
│  LLM Providers │ CRM │ Calendar │ Database │ Custom APIs        │
└─────────────────────────────────────────────────────────────────┘

Technical implementation and key boundaries for each layer:

5.2 The Complete Sequence Diagram

Here is the complete sequence of a WhatsApp message from arrival in OpenClaw to the response returning to the user:

User       WhatsApp    Channel     Gateway     Command     Pi          LLM        Action
(Phone)    Business    Bridge      Core        Queue       Agent       Provider   Layer
  │           │           │           │           │           │           │          │
  │─sends────►│           │           │           │           │           │          │
  │           │─Webhook──►│           │           │           │           │          │
  │           │           │─parse────►│           │           │           │          │
  │           │           │           │─Session──►│           │           │          │
  │           │           │           │  resolve  │           │           │          │
  │           │           │           │─enqueue──►│           │           │          │
  │           │           │           │           │─dispatch─►│           │          │
  │           │           │           │           │           │─load─────────────────►
  │           │           │           │           │           │  Memory   │          │
  │           │           │           │           │           │─completion─────────► │
  │           │           │           │           │           │◄─response──────────  │
  │           │           │           │           │           │  (ToolCall)|          │
  │           │           │           │           │           │─execute tool──────────►│
  │           │           │           │           │           │◄─tool result──────────│
  │           │           │           │           │           │─completion─────────► │
  │           │           │           │           │           │◄─final resp.───────── │
  │           │           │           │◄─response─│           │           │          │
  │           │           │◄─format───│           │           │           │          │
  │           │◄─send─────│           │           │           │           │          │
  │◄─reply────│           │           │           │           │           │          │

Typical latency breakdown (using Anthropic Claude Sonnet, single tool call):

5.3 Layer 1: Input Sources

The 20+ Supported Messaging Platforms

The Input Sources layer is the entry point for user messages into the OpenClaw system. OpenClaw's supported platforms fall into several categories:

Instant Messaging Platforms:

Ticketing and Support Platforms:

Email and Collaboration Platforms:

Custom Ingestion:

Handling Platform Specificity

Different platforms have vastly different message formats. WhatsApp messages have from (E.164 phone number), type (text/image/audio), timestamp; Slack messages have user (user ID), channel (channel ID), thread_ts (thread timestamp).

The Channel Bridge's core responsibility is to abstract these differences away — converting messages from all platforms into the unified InternalMessage format, making all subsequent Gateway processing platform-agnostic.

Channel Bridge Configuration Example

{
  "channels": [
    {
      "id": "whatsapp-main",
      "type": "whatsapp",
      "name": "WhatsApp Business Main",
      "config": {
        "phoneNumberId": "${WHATSAPP_PHONE_NUMBER_ID}",
        "accessToken": "${WHATSAPP_ACCESS_TOKEN}",
        "verifyToken": "${WHATSAPP_VERIFY_TOKEN}",
        "webhookPath": "/webhooks/whatsapp"
      }
    },
    {
      "id": "telegram-bot",
      "type": "telegram",
      "name": "Telegram Support Bot",
      "config": {
        "botToken": "${TELEGRAM_BOT_TOKEN}",
        "mode": "webhook",
        "webhookUrl": "https://your-domain.com/webhooks/telegram"
      }
    },
    {
      "id": "slack-workspace",
      "type": "slack",
      "name": "Internal Slack Workspace",
      "config": {
        "botToken": "${SLACK_BOT_TOKEN}",
        "signingSecret": "${SLACK_SIGNING_SECRET}",
        "appToken": "${SLACK_APP_TOKEN}",
        "socketMode": true
      }
    }
  ]
}

5.4 Layer 2: Integration Gateway

The Integration Gateway is the central orchestrator of the entire system, running as a single Node.js process.

The Channel Bridge Subsystem

The Gateway embeds all Channel Bridges and manages their lifecycle uniformly:

When the Gateway process starts:
1. Read the channels configuration
2. Instantiate the corresponding Channel Bridge class for each channel
3. Call bridge.connect() to establish the connection to the platform
4. Register message handler callbacks (bridge.onMessage → gateway.handleIncoming)
5. Start the Webhook server (unified HTTP service, routing to each Bridge)

Channel Bridges receive messages via two modes:

• Push mode (Webhook): The platform actively pushes; low latency, suitable for WhatsApp, Slack, etc.
• Pull mode (Polling): Gateway periodically fetches; suitable for Email and platforms that don't support Webhooks

The Session Management Subsystem

Session management is one of the most complex subsystems within the Gateway. Its core problem to solve is: how to accurately map messages arriving from different platforms and different users to the correct Agent Session.

Session Identifier Construction:

Session ID = channelId + "/" + senderId + "/" + threadId (optional)

Examples:
  whatsapp-main/+18005551234                    (WhatsApp user)
  telegram-bot/987654321                         (Telegram user)
  slack-workspace/U01ABC123/thread:1234567890.001 (Slack thread)

Session Lifecycle:

Message arrives
   │
   ├─ Session ID already exists?
   │  ├─ Yes → Load existing Session (restore conversation history)
   │  └─ No → Create new Session (initialize Memory)
   │
Session processing
   │
   ├─ No new messages for 30 minutes → Session enters Idle state (Memory written to disk)
   ├─ No new messages for 24 hours → Session expires (Short-term Memory cleared)
   └─ User sends /reset → Manual Session reset

The Command Queue Subsystem

The Command Queue is the Gateway's concurrency control core. Its Lane design solves a fundamental tension: wanting the system to be highly concurrent overall, while guaranteeing that messages within a single Session are processed in order.

┌──────────────────────────────────────────────────────────────────┐
│  Command Queue Internal Structure                                 │
│                                                                  │
│  Global Lane    ┌──────────────────────────────────────────┐    │
│  (max: 4)       │ ConfigReload │ PluginInstall │  DB Backup │    │
│                 └──────────────────────────────────────────┘    │
│                                                                  │
│  Session Lane   ┌─────┐ ┌─────┐ ┌─────┐                        │
│  (per session,  │Sess1│ │Sess2│ │Sess3│ ... N sessions          │
│   max: 1 each)  │ msg │ │ msg │ │ msg │                        │
│                 └─────┘ └─────┘ └─────┘                        │
│                                                                  │
│  SubAgent Lane  ┌──┐┌──┐┌──┐┌──┐┌──┐┌──┐┌──┐┌──┐             │
│  (max: 8)       │SA││SA││SA││SA││SA││SA││SA││SA│             │
│                 └──┘└──┘└──┘└──┘└──┘└──┘└──┘└──┘             │
│                                                                  │
│  Cron Lane      ⏰ Task1  ⏰ Task2  ⏰ Task3  ... (unlimited)   │
└──────────────────────────────────────────────────────────────────┘

The importance of steer-backlog mode: When a user sends multiple messages in rapid succession (for example: first "Help me look up", then "Order number 12345", then "Thanks"), the Session Lane merges the first two messages before processing (steer-backlog), preventing Pi from responding to an incomplete message.

The Plugin Registry Subsystem

The Plugin Registry is the Gateway's extension point manager. It maintains a Plugin registry, managing Plugin loading order (some Plugins may depend on others), initialization state, and health checks.

// Interfaces provided by Plugin Registry (simplified)
interface PluginRegistry {
  register(plugin: PluginDefinition): void;
  getChannelBridge(type: string): ChannelBridge;
  getMiddleware(phase: 'pre' | 'post'): Middleware[];
  getGlobalService(name: string): any;
}

5.5 Layer 3: Agent Core (Pi)

Pi's Reasoning Loop (ReAct Pattern)

Pi uses the ReAct (Reasoning + Acting) pattern to execute its reasoning loop:

1. Thought:      Analyze the current situation, decide on the next action
2. Action:       Call a tool (read/write/edit/bash, or a tool exposed by a Skill)
3. Observation:  Receive the tool's execution result
4. ... repeat 1–3 until the task is complete ...
5. Response:     Generate the final response and return it to the user

Pi's System Prompt is highly refined, staying under 1,000 tokens:

You are {agentName}, an AI assistant running on the OpenClaw framework.

You have the following tools available:
- read(path): Read the content of a file or URL
- write(path, content): Write content to a file
- edit(path, old, new): Make precise edits to a file
- bash(command): Execute a shell command

{skillsContext}  ← Description of currently active Skills (dynamically injected)

Current Session information:
- User: {userId}
- Channel: {channelName}
- Time: {currentTime}

{memoryContext}  ← Relevant context retrieved from Long-term Memory (dynamically injected)

Please respond to the user's questions concisely and professionally. When tools are needed,
think before acting.

pi-agent-core's Core Data Structures

// Core state of the reasoning loop (simplified)
interface AgentSession {
  id: string;
  agentId: string;
  messages: Message[];           // Short-term Memory (current conversation)
  tools: Tool[];                 // Currently available tools list
  maxIterations: number;         // Prevents infinite loops (default: 20)
  currentIteration: number;
  status: 'running' | 'waiting' | 'complete' | 'error';
}

interface Message {
  role: 'system' | 'user' | 'assistant' | 'tool';
  content: string | ToolCall[] | ToolResult[];
}

interface ToolCall {
  id: string;
  name: string;
  input: Record<string, unknown>;
}

LLM Call Retries and Fault Tolerance

Pi implements exponential backoff retries for LLM API calls:

// Retry configuration (can be overridden in openclaw.json)
{
  "llm": {
    "retryConfig": {
      "maxRetries": 3,
      "initialDelayMs": 1000,
      "maxDelayMs": 30000,
      "backoffMultiplier": 2,
      "retryOn": [429, 500, 502, 503, 504]
    }
  }
}

5.6 Layer 4: Action Layer

The Tool Execution Engine

The Action Layer is responsible for actually executing the tool calls requested by Pi. It is the execution layer between Pi and the external world.

Tool execution flow:

Pi issues a ToolCall
    │
    ▼
Action Layer receives it
    │
    ├─ Is the tool on the approval whitelist?
    │  ├─ Yes → Execute immediately
    │  └─ No → Enter HITL approval queue
    │           │
    │           ├─ Wait for human approval (Control UI displays request)
    │           │  ├─ Approved → Continue execution
    │           │  ├─ Rejected → Return rejection message to Pi
    │           │  └─ Timeout (default 300s) → Cancel execution
    │
    ▼
Execute tool (bash/read/write/edit or integration adapter)
    │
    ▼
Return ToolResult to Pi

Human-in-the-Loop (HITL) Approval

HITL is a critical production safety mechanism in OpenClaw. It allows you to set mandatory human approval checkpoints for high-risk operations.

Configuring HITL rules:

{
  "hitl": {
    "enabled": true,
    "rules": [
      {
        "id": "require-approval-for-writes",
        "description": "Require approval for all file write operations",
        "condition": {
          "tool": "write",
          "pathPattern": "/etc/**"
        },
        "action": "require_approval",
        "timeout": 300,
        "notifyChannels": ["slack-workspace"]
      },
      {
        "id": "require-approval-for-payments",
        "description": "Require approval for all payment operations",
        "condition": {
          "integration": "stripe",
          "methods": ["createPayment", "createRefund"]
        },
        "action": "require_approval",
        "approvers": ["[email protected]"]
      },
      {
        "id": "auto-approve-reads",
        "description": "Automatically approve all read-only operations",
        "condition": {
          "tool": ["read", "bash"],
          "bashPattern": "^(ls|cat|grep|find|curl -G).*"
        },
        "action": "auto_approve"
      }
    ]
  }
}

In the Control UI, the HITL approval queue displays pending operations in real time, including:

• The operation's complete parameters
• The conversation context that triggered the operation
• Estimated scope of impact
• One-click approve/reject buttons

Integration Adapters

For 50+ official integrations, the Action Layer provides corresponding integration adapters that convert Pi's tool calls into concrete API requests:

Pi calls: tool("hubspot.createContact", { name: "Alice", email: "[email protected]" })
         ↓
Action Layer:
  1. Look up the "hubspot" integration adapter
  2. Call the adapter's createContact method
  3. Adapter constructs the HubSpot API request:
     POST https://api.hubapi.com/crm/v3/objects/contacts
     Authorization: Bearer ${HUBSPOT_ACCESS_TOKEN}
     { "properties": { "firstname": "Alice", "email": "[email protected]" } }
  4. Handle the response, return standardized ToolResult
         ↓
Pi receives: { success: true, contactId: "1234567", url: "https://app.hubspot.com/..." }

Integration Configuration Example

{
  "integrations": [
    {
      "id": "hubspot",
      "type": "hubspot",
      "config": {
        "accessToken": "${HUBSPOT_ACCESS_TOKEN}",
        "portalId": "${HUBSPOT_PORTAL_ID}"
      },
      "permissions": {
        "read": true,
        "write": true,
        "requireApproval": ["deleteContact", "deleteCompany"]
      }
    },
    {
      "id": "google-calendar",
      "type": "google-calendar",
      "config": {
        "serviceAccountKey": "${GOOGLE_SERVICE_ACCOUNT_KEY}",
        "delegatedUser": "[email protected]"
      },
      "permissions": {
        "read": true,
        "write": true,
        "requireApproval": ["deleteEvent"]
      }
    }
  ]
}

5.7 Layer 5: External Systems

LLM Provider Management

The most important external system in the External Systems layer is the LLM Provider. OpenClaw abstracts the API differences between providers through the pi-ai package.

Supported LLM Providers and key parameters:

Multi-Provider failover configuration:

{
  "llm": {
    "providers": [
      {
        "id": "anthropic-primary",
        "type": "anthropic",
        "apiKey": "${ANTHROPIC_API_KEY}",
        "defaultModel": "claude-sonnet-4-5-20251201",
        "priority": 1
      },
      {
        "id": "openai-fallback",
        "type": "openai",
        "apiKey": "${OPENAI_API_KEY}",
        "defaultModel": "gpt-4o-mini",
        "priority": 2
      }
    ],
    "failoverPolicy": {
      "enabled": true,
      "failoverOn": [429, 500, 503],
      "maxFailoverAttempts": 2
    }
  }
}

When the primary Provider returns an error, Pi automatically switches to the secondary Provider to maintain service availability.

CRM Integrations

CRM integrations enable Agents to read and write customer data — a core capability for customer service and sales scenarios:

Supported CRMs:
  Salesforce    → SOQL queries + REST API
  HubSpot       → CRM API v3
  Pipedrive     → REST API v1/v2
  Zoho CRM      → REST API v4
  Freshsales    → REST API

Calendar Integrations

Supported Calendar Services:
  Google Calendar  → Calendar API v3
  Outlook          → Microsoft Graph Calendar API
  Calendly         → API v2 (query and create appointments)
  Cal.com          → REST API (open-source calendar)

Document Integrations

Supported Document Services:
  Notion           → Notion API (read/write Pages and Databases)
  Confluence       → REST API v2 (read/write spaces and pages)
  Google Docs      → Google Docs API (read/write documents)
  Google Drive     → Drive API (file search and reading)
  SharePoint       → Microsoft Graph API

Database Integrations (Read-Only Mode)

For safety, database integrations default to read-only operations (SELECT queries only):

{
  "integrations": [
    {
      "id": "main-db",
      "type": "postgresql",
      "config": {
        "host": "localhost",
        "port": 5432,
        "database": "myapp",
        "user": "${DB_USER}",
        "password": "${DB_PASSWORD}",
        "ssl": true
      },
      "permissions": {
        "mode": "readonly",
        "allowedTables": ["users", "orders", "products"]
      }
    }
  ]
}

If write permissions are needed, they must be explicitly authorized through HITL configuration, with approval requirements set for each write operation.

5.8 Boundary and Security Design

Security Boundaries Between Layers

The five-layer architecture is not just a functional division — it is also a security division:

Input Sources layer:
  └─ Authentication: Verify Webhook signatures (WhatsApp HMAC-SHA256 / Slack signature verification)
  └─ Rate limiting: Independent message rate limits per Channel
  └─ Content filtering: Optional content safety filtering middleware

Integration Gateway layer:
  └─ Session isolation: Data for different Sessions is completely isolated
  └─ Command validation: All commands sent to Pi go through Schema validation
  └─ Single-writer: Database writes have a single entry point

Agent Core layer:
  └─ Tool sandboxing: bash tool can be configured for sandbox mode (restricted shell)
  └─ Iteration limits: Prevents Pi from falling into infinite reasoning loops
  └─ Token budget: Maximum token count per LLM call

Action Layer:
  └─ HITL: High-risk operations require mandatory human approval
  └─ Read-only mode: Database integrations are read-only by default
  └─ Permission whitelists: Each integration explicitly declares allowed operations

External Systems layer:
  └─ Key isolation: API Keys injected via environment variables, never appear in config files
  └─ Least privilege: Each integration requests only the minimum necessary permission scope

Audit Logging

All operations crossing layer boundaries generate audit logs:

{
  "timestamp": "2026-04-26T10:30:00.123Z",
  "level": "audit",
  "event": "tool_executed",
  "sessionId": "whatsapp-main/+18005551234",
  "agentId": "support-agent",
  "tool": "hubspot.createContact",
  "input": { "name": "Alice", "email": "[email protected]" },
  "result": { "success": true, "contactId": "1234567" },
  "hitlApproval": { "required": false, "autoApproved": true },
  "durationMs": 342,
  "llmTokensUsed": { "input": 2341, "output": 187 }
}

Summary

This chapter fully dissected OpenClaw's five-layer architecture:

Layer 1 — Input Sources: 20+ messaging platforms are unified through Channel Bridges, with each platform's specific format smoothed out at this layer.

Layer 2 — Integration Gateway: The central orchestrator, responsible for Session resolution (8-priority Binding rules), Command Queue (4 Lanes, 4 modes), and Plugin Registry management. The Single-writer Pattern ensures data consistency.

Layer 3 — Agent Core (Pi): A reasoning engine using the ReAct pattern, embedded execution (not a subprocess), only 4 foundational tools, System Prompt under 1,000 tokens — pursuing low latency and high concurrency.

Layer 4 — Action Layer: The execution layer for tool execution and HITL approval. It is Pi's "hands," and also the last line of defense for security.

Layer 5 — External Systems: The integration point for LLM Providers, CRM, calendar, documents, databases, and other external systems. Platform API differences are hidden behind unified integration adapters.

Understanding the responsibility boundaries and data flows of these five layers is the foundation for deploying OpenClaw at depth in production. From WhatsApp message to Agent response, the entire chain completes in 1–5 seconds, with every millisecond of latency attributable to a specific component.

This concludes the first five chapters of the OpenClaw Complete Guide. From product understanding (ch01) to hands-on installation (ch02), from the full conceptual map (ch03) to competitor comparison (ch04), and finally to architecture dissection (ch05) — you now have all the foundational knowledge needed to use OpenClaw in depth.