OpenClawSkills
GitHub
Deep Dive • TutorialHeader.readTime

Architecture

A deep dive into OpenClaw's Gateway-centric design, network model, and agent execution loop.

OpenClaw is built around a Gateway-centric architecture where a single long-running process manages all channel connections and provides a unified control plane. This design ensures reliability, security, and simplicity.

Tutorial.step

Core Components

The Gateway

The Gateway (<code>openclaw gateway</code>) is the heart of OpenClaw. It is a single process that:

  • Manages all channel connections (WhatsApp, Telegram, Discord, etc.).
  • Provides a WebSocket control plane on port <strong>18789</strong> (default).
  • Handles session management and routing.
  • Serves the Control UI / Dashboard.
  • Manages the <strong>Canvas host</strong> for visual interfaces.
  • Coordinates inter-agent communication.

Stability Tip

One Gateway per host is recommended. It is the only process allowed to own the WhatsApp Web session, ensuring stability and preventing conflicts.
Tutorial.step

Network Model

OpenClaw uses a <strong>loopback-first</strong> approach for maximum security:

  • <strong>Default:</strong> Gateway WebSocket runs on <code>ws://127.0.0.1:18789</code> (localhost only).
  • <strong>Remote Access:</strong> Use SSH tunnels, Tailscale, or configure <code>--bind</code> with authentication tokens for secure outside access.
  • <strong>Canvas Host:</strong> A dedicated HTTP file server on port <strong>18793</strong> serving <code>/__openclaw__/canvas/</code> for high-performance node WebViews.

Architecture Overview

WhatsApp / Telegram / Discord / iMessage (+ plugins)
            │
            ▼
┌───────────────────────────────────────────────┐
│                 Gateway                   │  ws://127.0.0.1:18789
│            (Single Source of Truth)          │
│                                              │  http://<host>:18793
└───────────────────────┬───────────────────────┘
                        │
  ┌─────────────────────┼─────────────────────┐
  │                     │                     │
  ▼                     ▼                     ▼
OpenClaw Agent (RPC)      CLI Tool      Native Apps (iOS/macOS)
Tutorial.step

The Agent Loop

The agent loop is the core processing cycle that defines how messages are handled:

  1. <strong>Message Received:</strong> A connected channel receives an incoming message.
  2. <strong>Session Routing:</strong> The message is routed to the appropriate session (main, group, or isolated).
  3. <strong>Context Loading:</strong> The agent loads relevant historical context, memories, and tools.
  4. <strong>LLM Processing:</strong> The structured request is sent to the LLM provider (Claude, GPT, etc.).
  5. <strong>Tool Execution:</strong> The agent autonomously executes tools (browser, file system, shell) as needed.
  6. <strong>Response Streaming:</strong> The final response is streamed back to the channel in real-time.
  7. <strong>Memory Update:</strong> The conversation is indexed and saved to the workspace.
Tutorial.step

Session Model

Session Types
  • <strong>Main Session:</strong> Collapses all direct messages into a shared context.
  • <strong>Group Sessions:</strong> Each group chat gets an isolated workspace.
  • <strong>Isolated Sessions:</strong> Created for specific security or ephemeral needs.
Session Features
  • <strong>Activation Modes:</strong> Control responsiveness (mention-only, always, etc.).
  • <strong>Queue Management:</strong> Efficient handling of concurrent requests.
  • <strong>Sandboxing:</strong> Optional Docker isolation for multi-tenant environments.
Tutorial.step

Workspace Structure

OpenClaw is <strong>file-system first</strong>. Everything is stored in your configuration and workspace directories:

File Hierarchy
~/.openclaw/openclaw.json    # Configuration file
~/.openclaw/credentials/     # Secure channel tokens
~/.openclaw/workspace/       # Workspace Root
├── AGENTS.md                # Agent persona definitions
├── SOUL.md                  # Core personality & logic
├── TOOLS.md                 # Custom tool definitions
├── skills/                  # Plugin/Skill directory
└── sessions/                # Active conversation states
Tutorial.step

Multi-Agent Routing

OpenClaw supports advanced routing of messages based on:

  • <strong>Channel:</strong> Different agents for WhatsApp vs Discord.
  • <strong>Account/Peer:</strong> Route specific contacts to dedicated personas.
  • <strong>Workspace Isolation:</strong> Each agent can be locked to its own directory and set of skills.
Tutorial.step

Streaming & Protocol

Streaming & Chunking

OpenClaw uses <strong>Block Streaming</strong> to send responses in chunks for perceived speed. It also supports <strong>Telegram Draft Streaming</strong>, showing typing indicators and drafts in real-time.

Communication Protocols
  • <strong>WebSocket:</strong> For real-time delivery and Control UI updates.
  • <strong>RPC (Remote Procedure Call):</strong> Used by agents for tool invocation and context queries.