System Architecture Layers 🟡

Understanding OpenClaw's layered architecture is the foundation for understanding all other topics. This chapter maps out the 7-layer architecture and the role of each layer.

Learning Objectives

After reading this chapter, you'll be able to:

• Draw OpenClaw's 7-layer architecture diagram from memory
• Identify which source directory each layer corresponds to
• Understand the "lean core + capability plugins" design principle
• Explain the purpose of AGENTS.md boundary guard files

I. The 7-Layer Architecture

flowchart TB
    subgraph L1["Layer 1: CLI & Entry"]
        CLI["openclaw.mjs\nsrc/cli/\nsrc/entry.ts"]
    end

    subgraph L2["Layer 2: Gateway (Control Plane)"]
        GW["src/gateway/\nHTTP/WebSocket Server\nAuthentication & Authorization"]
    end

    subgraph L3["Layer 3: Routing"]
        ROUTE["src/routing/\nMessage → Agent Routing\nSession Key Construction"]
    end

    subgraph L4["Layer 4: Plugin Orchestration"]
        PLUGINS["src/plugins/\nPlugin Discovery & Loading\nPlugin Registry\nHook System"]
    end

    subgraph L5["Layer 5: Channel Adaptation"]
        CHAN["src/channels/\nextensions/telegram/\nextensions/discord/\n...20+ adapters"]
    end

    subgraph L6["Layer 6: Agent Reasoning"]
        AGENT["src/agents/\nBootstrap Construction\nLLM Calls\nTool Loop\nCompaction"]
    end

    subgraph L7["Layer 7: Infrastructure"]
        INFRA["src/infra/\nsrc/config/\nsrc/sessions/\nsrc/security/\nsrc/logging/"]
    end

    L1 --> L2 --> L3 --> L4 --> L5 --> L6 --> L7

II. Layer-by-Layer Breakdown

Layer 1: CLI & Entry

User-facing command-line interface. Key files:

• openclaw.mjs — CLI wrapper, starts the Node.js process
• src/entry.ts — runCli() main function
• src/cli/ — individual CLI command implementations

Layer 2: Gateway (Control Plane)

The central hub of the system. It's a control plane, not a data plane — meaning it doesn't process message content, only routes and coordinates.

Key responsibilities:

• HTTP API for Web UI and external tools
• WebSocket real-time communication for CLI
• Authentication (6 methods) and authorization
• Method Scopes permission model

Layer 3: Routing

Determines which Agent handles each incoming message, and which session context it belongs to.

• resolveAgentRoute() — 8-layer priority matching
• Session Key construction — conversation isolation

Layer 4: Plugin Orchestration

Manages the complete lifecycle of plugins:

• Discovery (scan extensions/ directories)
• Manifest parsing (openclaw.plugin.json)
• Loading (via jiti TypeScript runner)
• Registry (runtime capability mapping)
• Hook system (before/after agent reply)

Layer 5: Channel Adaptation

Platform-specific adapters. Each channel plugin:

• Connects to the platform API (Webhook or Long Polling)
• Converts platform messages to InboundEnvelope standard format
• Sends AI replies back to the platform

Layer 6: Agent Reasoning

The AI "thinking" layer:

• Bootstrap: build System Prompt (core instructions + CLAUDE.md + Skills + Memory)
• LLM Provider calls (streaming)
• Tool call loop (bash, files, MCP tools)
• Compaction: when context window fills up, compress with summaries

Layer 7: Infrastructure

Foundational support:

• src/config/ — configuration loading/parsing
• src/sessions/ — SQLite-based session storage
• src/infra/ — backoff, retry, heartbeat
• src/security/ — prompt injection protection, secret handling
• src/logging/ — structured logging

III. AGENTS.md Boundary Guard Files

Throughout the codebase you'll find AGENTS.md files (some say CLAUDE.md). These serve a special purpose:

src/plugin-sdk/AGENTS.md    ← "DO NOT import from src/ directly"
src/agents/AGENTS.md        ← "Agent layer boundary rules"

These files tell AI coding assistants (like Claude Code) the architectural boundaries — which modules can import which. This is OpenClaw using AI to enforce its own architectural integrity.

IV. "Lean Core + Plugin Capabilities" in Practice

The core (src/) contains only routing and coordination logic. Examples of what's not in core:

If you want to add a new platform, you add a plugin — you don't touch src/.

Summary

1. 7-layer architecture: CLI → Gateway → Routing → Plugin Orchestration → Channel Adaptation → Agent Reasoning → Infrastructure.
2. Gateway is control plane only: It orchestrates, not processes content.
3. Plugin layer is the extension point: All platform/model/capability support is in plugins.
4. AGENTS.md enforces boundaries: AI coding assistants read these files to understand what they can and cannot import.

← Running Locally | → Gateway Core