How a Single Gateway Manages 30+ Messaging Platforms in OpenClaw

Overall Architecture

The system runs a single long‑lived Gateway process that listens on 127.0.0.1:18789 and provides a WebSocket interface for all clients (macOS app, CLI/WebUI, iOS/Android). The Gateway maintains connections to every supported messaging platform (WhatsApp, Telegram, Slack, Discord, …) and acts as the sole source of truth for session state.

Eliminates duplicate platform connections.

Ensures consistent conversation context across devices.

Simplifies deployment to a single process per host.

One Gateway per host; it is the only place that opens a WhatsApp session.

Agent Runtime (pi‑mono)

OpenClaw embeds an agent runtime derived from pi‑mono . It reuses pi‑mono components (models, tools) but implements its own session management, discovery, and tool bindings. The runtime does not read ~/.pi/agent or <workspace>/.pi configuration files; session data is stored under ~/.openclaw/agents/<agentId>/sessions/.

Agent Loop Execution Flow

The loop consists of six stages:

intake → context assembly → model inference → tool execution → streaming replies → persistence

Intake : Gateway validates the incoming message, extracts the session ID and immediately returns { runId, acceptedAt } to the client.

Context Assembly : The Context Engine loads historic messages from JSONL files, injects six workspace files (AGENTS.md, SOUL.md, TOOLS.md, BOOTSTRAP.md, IDENTITY.md, USER.md), loads a snapshot of Skills, and truncates or compresses history to fit the model’s context window.

Model Inference : Calls an LLM API (Claude, GPT, or a local model) with the assembled context.

Tool Execution : If the model requests a tool (e.g., web browsing, file reading), the tool runs and its result is fed back to the model.

Streaming Replies : Model output is streamed to the client in real time.

Persistence : The full turn (user message, model reply, tool calls) is appended to a per‑session JSONL file.

Queue and Concurrency Control

Agent Loop execution is serialized per session key ("session lane"). Messages belonging to the same session are processed sequentially; different sessions may run in parallel. This prevents tool‑level race conditions such as concurrent file modifications.

Hook System

Two hook layers enable extensibility:

Internal (Gateway) Hooks : e.g., agent:bootstrap runs when building the bootstrap file.

Command Hooks : trigger points for commands like /new, /reset, /stop.

Plugin hooks provide finer‑grained lifecycle events: before_model_resolve – before model resolution, can override provider/model. before_prompt_build – before prompt construction, can inject additional context. before_tool_call / after_tool_call – around tool invocation. session_start / session_end – session lifecycle boundaries.

Context Engine Lifecycle

The engine defines four lifecycle points:

Ingest : Triggered when a new message is added; can store or index the message.

Assemble : Triggered before each model run; returns an ordered list of messages plus an optional systemPromptAddition that is inserted into the model’s context window.

Compact : Triggered when the context window is full or when the user runs /compact; typically compresses older messages by summarisation.

After Turn : Runs after a complete dialogue turn; can persist state or launch background compression.

Default (legacy) engine behavior:

Ingest – no operation (Session Manager handles persistence).

Assemble – pass‑through using the runtime’s sanitize → validate → limit pipeline.

Compact – delegated to the built‑in summariser.

After Turn – no operation.

Custom engines can be registered via the plugin configuration, for example a vector‑retrieval engine that performs RAG during the Assemble phase:

{
  plugins: {
    slots: {
      contextEngine: "my-custom-engine",
    },
    entries: {
      "my-custom-engine": {
        enabled: true,
      },
    },
  },
}

Session Management

Storage Structure

Session list ( sessions.json) – a map sessionKey → { sessionId, updatedAt, … } located at ~/.openclaw/agents/<agentId>/sessions/sessions.json.

Session records – per‑session JSONL files (

~/.openclaw/agents/<agentId>/sessions/<SessionId>.jsonl

) where each line records a full turn (user message, model reply, tool calls, etc.).

Session Key Mapping Rules

Session keys determine which messages belong to the same conversation. For direct messages the session.dmScope setting controls isolation: main (default) – all DMs share a single session across devices/channels. per-peer – isolate by sender ID. per-channel-peer – isolate by channel + sender (recommended for shared inboxes). per-account-channel-peer – isolate by account + channel + sender.

Group messages use the format agent:<agentId>:<channel>:group:<id>, each group receiving its own session.

If an agent receives DMs from multiple people, enabling secure DM mode is strongly recommended to avoid leaking private context between users.

Maintenance Configuration

{
  session: {
    maintenance: {
      mode: "warn",        // "warn" only reports, "enforce" performs cleanup
      pruneAfter: "30d",   // prune sessions older than 30 days
      maxEntries: 500,      // keep at most 500 sessions
      rotateBytes: "10mb"   // rotate sessions.json when it exceeds 10 MB
    }
  }
}

Maintenance steps execute in order:

Prune sessions older than pruneAfter.

Enforce maxEntries limit.

Archive JSONL files no longer referenced.

Rotate sessions.json if it exceeds rotateBytes.

Context File Injection

When building the system prompt, six workspace files are automatically injected: AGENTS.md – operation commands and "memory". SOUL.md – persona, boundaries, tone. TOOLS.md – user‑maintained tool specifications. BOOTSTRAP.md – one‑time bootstrap ritual (deleted after run). IDENTITY.md – agent name/style/emoji. USER.md – user configuration and preferred address.

Comparison with LangChain / CrewAI / AutoGen

Key differences are expressed across several dimensions:

Core positioning : OpenClaw is a personal AI assistant; the others are LLM application development frameworks.

Target users : OpenClaw targets end users; the alternatives target developers.

Execution model : OpenClaw runs as a locally long‑running service; the alternatives are invoked on demand.

Channel support : OpenClaw ships with 30+ platform integrations out‑of‑the‑box; others require manual integration.

Gateway : OpenClaw provides a unified control plane; the others have none.

State management : OpenClaw includes built‑in persistence; the alternatives leave persistence to the developer.

OpenClaw solves the problem of giving ordinary users a "eyes‑and‑hands" AI assistant that works inside familiar chat apps and can browse the web, read/write files, and execute commands. LangChain, CrewAI, and AutoGen solve the problem of enabling developers to build LLM applications more conveniently.

Technical Selection Guidance

Scenarios Where OpenClaw Fits

Need a 24/7 online personal AI assistant.

Require a single assistant usable across many chat platforms.

Prioritise data privacy by running locally.

Require a complete ecosystem (macOS, iOS, Android clients).

Scenarios Where It Is Less Suitable

Enterprise‑grade multi‑tenant deployments (security model still evolving).

Highly custom agent logic (LangChain may offer more flexibility).

Concern about the rapidly growing third‑party plugin ecosystem.

Security Recommendations

Run inside a sandbox VM or container.

Use minimal‑privilege, short‑lived tokens.

Restrict skill/extension registries and verify sources.

Periodically audit agent memory, state, and behaviour.

Deploy real‑time anti‑malware solutions.

Conclusion

The architecture consists of a single Gateway that governs the global control plane, a pi‑mono runtime that performs inference, a Context Engine that curates what the model sees, and a Session Manager that provides durable state. This unified control plane eliminates the complexity of per‑platform processes and, together with the hook system and extensible context engine, offers a concrete reference for AI‑agent design.