Architecture Overview: Gateway, Agents, and Skills

Architecture Overview: Gateway, Agents, and Skills

Before you write a single line of configuration, you need a mental model of how OpenClaw actually works under the hood. This isn't academic navel-gazing -- understanding the architecture will save you hours of debugging later and let you build more sophisticated automations from day one.

Think of OpenClaw like a well-organized company. There's a CEO (the Gateway) who receives all incoming requests, employees (Agents) who process those requests using their expertise, and tools (Skills) that employees use to get work done.

Let's break each one down.

The Gateway: OpenClaw's Brain

The Gateway is the central nervous system of your OpenClaw deployment. It's a WebSocket-based control plane that listens on port 18789 by default and handles everything:

• Message routing -- Receives incoming messages from any connected channel (WhatsApp, Telegram, Slack, etc.) and routes them to the appropriate agent
• State management -- Tracks conversation context, user sessions, and agent states
• Skill execution -- Orchestrates skill calls and returns results
• Model coordination -- Sends prompts to your configured AI model(s) and handles responses

┌─────────────────────────────────────────────────────────┐
│                    THE GATEWAY (port 18789)              │
│                                                         │
│  ┌──────────┐  ┌──────────────┐  ┌───────────────────┐  │
│  │ Message   │  │ State        │  │ Skill             │  │
│  │ Router    │  │ Manager      │  │ Executor          │  │
│  └──────────┘  └──────────────┘  └───────────────────┘  │
│                                                         │
│  ┌──────────┐  ┌──────────────┐  ┌───────────────────┐  │
│  │ WebSocket │  │ Model        │  │ Plugin            │  │
│  │ Server    │  │ Coordinator  │  │ Manager           │  │
│  └──────────┘  └──────────────┘  └───────────────────┘  │
└─────────────────────────────────────────────────────────┘
         ▲              ▲              ▲
         │              │              │
    ┌────┘    ┌─────────┘    ┌─────────┘
    │         │              │
┌───┴───┐ ┌──┴──┐    ┌──────┴──────┐
│Channels│ │Models│    │   Skills    │
│WhatsApp│ │GPT-4│    │ Web Browse  │
│Telegram│ │Claude│    │ Email Send  │
│ Slack  │ │Ollama│    │ File Mgmt   │
│Discord │ │ etc. │    │ Smart Home  │
└────────┘ └──────┘    └─────────────┘

Agents: The Workers

An Agent in OpenClaw is a configured AI persona that handles conversations. Think of agents as specialized employees -- each one can have:

• A specific AI model (GPT-4, Claude, Llama, Mistral, etc.)
• A system prompt defining its personality and behavior
• A set of enabled skills determining what actions it can take
• Memory configuration controlling how much context it retains
• Channel assignments specifying which messaging platforms it serves

Here's a simplified agent configuration:

agents:
  - name: "HomeAssistant"
    model: "gpt-4"
    system_prompt: |
      You are a helpful home automation assistant.
      You control smart home devices and help with
      daily routines. Be concise and friendly.
    skills:
      - smart_home
      - weather
      - calendar
    channels:
      - telegram
      - whatsapp
    memory:
      max_context_tokens: 8000
      conversation_ttl: 3600

You can run multiple agents simultaneously, each with different models, skills, and personalities. One agent might handle your personal messages on Telegram while another handles customer support on WhatsApp.

The Pi Agent Runtime

Under the hood, each agent runs inside OpenClaw's Pi agent runtime -- a conversation management layer that handles:

1. Context window management -- Intelligently summarizes and compresses conversation history to stay within model token limits
2. Skill selection -- Determines which skills are relevant to the current request
3. Tool calling -- Formats and executes skill calls based on model output
4. Response formatting -- Adapts responses for the target messaging platform (e.g., Markdown for Telegram, plain text for SMS)

The Pi runtime is what makes OpenClaw feel intelligent rather than just reactive. It maintains conversational context, remembers user preferences within a session, and chains multiple skill calls together to accomplish complex tasks.

Skills: The Abilities

Skills are modular capabilities that give your agents the power to interact with the real world. OpenClaw ships with 56+ built-in skills organized into categories:

Each skill is defined by a SKILL.md file -- a structured markdown document that tells the AI model what the skill can do, what parameters it accepts, and how to call it. This is one of OpenClaw's most elegant design decisions: skills are described in natural language that both humans and AI models can understand.

Here's what a simplified SKILL.md looks like:

# Weather Skill

## Description
Get current weather and forecasts for any location.

## Actions

### get_current
Get the current weather for a location.

**Parameters:**
- `location` (string, required): City name or coordinates
- `units` (string, optional): "metric" or "imperial" (default: "metric")

**Returns:** Temperature, conditions, humidity, wind speed

### get_forecast
Get a multi-day weather forecast.

**Parameters:**
- `location` (string, required): City name or coordinates
- `days` (integer, optional): Number of days (1-7, default: 3)

How Messages Flow: The Complete Pipeline

Let's trace a message from the moment you type it on WhatsApp to the moment you receive a response. Understanding this flow is essential for debugging and optimization.

You type on WhatsApp: "Turn off the living room lights"
                │
                ▼
┌──────────────────────────────┐
│  1. WhatsApp Channel Adapter │  ← Receives message via WhatsApp Business API
│     Normalizes to internal   │
│     message format           │
└──────────────┬───────────────┘
               │
               ▼
┌──────────────────────────────┐
│  2. Gateway Message Router   │  ← Identifies user, selects appropriate agent
│     Routes to assigned agent │
└──────────────┬───────────────┘
               │
               ▼
┌──────────────────────────────┐
│  3. Pi Agent Runtime         │  ← Loads conversation context and history
│     Prepares context window  │
└──────────────┬───────────────┘
               │
               ▼
┌──────────────────────────────┐
│  4. AI Model (e.g., GPT-4)  │  ← Receives system prompt + context + message
│     Decides to use skill     │     Returns: call smart_home.toggle_device
│                              │     params: {device: "living_room_lights",
│                              │              action: "off"}
└──────────────┬───────────────┘
               │
               ▼
┌──────────────────────────────┐
│  5. Skill Executor           │  ← Validates params, calls Home Assistant API
│     Executes smart_home      │     Returns: {success: true}
│     skill                    │
└──────────────┬───────────────┘
               │
               ▼
┌──────────────────────────────┐
│  6. AI Model (second pass)   │  ← Receives skill result
│     Generates human response │     Returns: "Done! Living room lights are
│                              │     now off."
└──────────────┬───────────────┘
               │
               ▼
┌──────────────────────────────┐
│  7. WhatsApp Channel Adapter │  ← Formats response for WhatsApp
│     Sends response back      │     Delivers to your phone
└──────────────────────────────┘

The entire round-trip typically takes 2-5 seconds, depending on your AI model's response time and the complexity of the skill execution.

The Plugin Architecture

Beyond built-in skills, OpenClaw supports a robust plugin system. Plugins can:

• Add new messaging channel adapters
• Register custom skills
• Modify message processing pipelines
• Add middleware (logging, rate limiting, content filtering)
• Integrate with external services

The ClawHub marketplace is where the community shares plugins and skills. Think of it like npm for AI assistant capabilities -- you can install a "Spotify Controller" skill, a "Jira Ticket Manager" skill, or a "Recipe Finder" skill with a single command.

# Install a community skill from ClawHub
openclaw skill install @clawhub/spotify-controller
openclaw skill install @clawhub/jira-manager

Putting It All Together

Here's the mental model to carry with you through the rest of this course:

1. Gateway = The central hub. Everything connects here. It runs on port 18789 and manages the entire system.
2. Agents = AI personas with specific models, prompts, skills, and channel assignments. You can have many.
3. Skills = Modular abilities defined by SKILL.md files. They give agents the power to interact with external services.
4. Channels = Messaging platforms (WhatsApp, Telegram, etc.) that connect users to agents.
5. Pi Runtime = The conversation engine inside each agent that manages context, selects skills, and chains actions.