Chapter 4: Gateway Architecture

The OpenClaw Gateway is the core engine that makes everything work. Understanding how it is built helps you configure it correctly, troubleshoot problems faster, and extend it with confidence. This chapter explains the internal architecture of the gateway — how messages move through it, what each layer does, and why the design choices were made.

What the Gateway Is

When you run openclaw start, you launch a Node.js server process on your machine or cloud host. This process is the Gateway. It does several things simultaneously:

Listens for incoming messages on every connected channel
Authenticates and identifies the sender
Routes the message to the correct workspace and agent
Executes any skills the agent needs
Returns the response back through the originating channel

Everything in OpenClaw flows through this single process.

The Four Layers

The Gateway has four distinct processing layers. Every message passes through all four in sequence.

Incoming Message
      ↓
┌─────────────────────┐
│  1. Channel Layer   │  Receives raw messages from WhatsApp, Telegram, Slack, etc.
├─────────────────────┤
│  2. Auth Layer      │  Verifies the sender's identity and permissions
├─────────────────────┤
│  3. Router Layer    │  Selects the right workspace, agent, and skill set
├─────────────────────┤
│  4. Agent Layer     │  Sends the message to the AI model and executes tools
└─────────────────────┘
      ↓
Outgoing Response

Layer 1 — Channel Layer

The Channel Layer is a collection of channel adapters — one for each messaging platform. Each adapter:

Connects to the platform's API (WhatsApp Business API, Telegram Bot API, Slack Events API, etc.)
Listens for incoming messages in real time
Normalizes the message into OpenClaw's internal format
Passes the normalized message to the Auth Layer

The normalization step is critical. WhatsApp, Telegram, and Slack all use different JSON schemas. The channel adapter converts all of them into a single OpenClaw Message Object:

{
  "channel": "whatsapp",
  "channelUserId": "+1234567890",
  "workspaceId": "team-dev",
  "text": "Refactor this function to async/await",
  "timestamp": 1714500000000,
  "attachments": []
}

Layer 2 — Auth Layer

The Auth Layer checks every incoming message against the workspace allowlist:

Identifies the sender by their channel-specific ID (phone number, username, user ID)
Looks up whether this sender is authorized in any workspace
Rejects unauthorized senders with a polite error (or silence, depending on config)
Attaches the workspace and user context to the message object

This is where pairing codes are verified. When a new user wants access, they use a pairing command and the gateway registers their channel ID in the workspace allowlist.

Layer 3 — Router Layer

The Router Layer decides:

Which workspace owns this conversation
Which agent should handle this message
Which skills the agent has access to
What session context (conversation history) to attach

The Router maintains an in-memory session store. Each user gets a session that carries their conversation history. When you run /reset, the Router clears your session.

Layer 4 — Agent Layer

The Agent Layer is where actual AI processing happens:

Builds the prompt from message + session history + system prompt
Calls the configured AI model API (Claude, GPT-4, Gemini, or local)
Executes any tool calls the model requests (file reads, shell commands, web searches)
Collects the full response
Returns the response to the Router for delivery

The Message Lifecycle

Step	Layer	Action
1	Channel	WhatsApp webhook fires with user message
2	Channel	Adapter normalizes message to OpenClaw format
3	Auth	Sender phone number looked up in allowlist
4	Auth	Workspace `team-dev` matched, user `alice` identified
5	Router	Agent `claude-sonnet` selected for workspace
6	Router	Session history for alice retrieved
7	Agent	Prompt built: system prompt + history + new message
8	Agent	Claude API called with full prompt
9	Agent	Claude requests `run_bash` tool — gateway executes it
10	Agent	Final response assembled
11	Router	Response stored in session history
12	Channel	Response sent back to alice via WhatsApp

Sessions

The Gateway handles multiple users simultaneously using async I/O. Sessions are stored in memory:

{
  "userId": "alice",
  "workspaceId": "team-dev",
  "messages": [
    { "role": "user", "content": "..." },
    { "role": "assistant", "content": "..." }
  ],
  "createdAt": 1714500000000,
  "lastActiveAt": 1714503600000
}

Sessions expire after configurable inactivity (default: 30 minutes). Reset manually with /reset.

The Daemon Process

When you run openclaw onboard --install-daemon, OpenClaw installs as a system daemon that starts automatically on boot:

OS	Daemon System
macOS	launchd
Linux	systemd
Windows	Task Scheduler

openclaw start          # start the gateway
openclaw stop           # stop the gateway
openclaw restart        # restart (reload config)
openclaw status         # check if running + active channels

Always run openclaw restart after editing openclaw.json.

Configuration Loading Order

Global defaults — built-in defaults for every setting
Config file — your openclaw.json overrides the defaults
Environment variables — OPENCLAW_* vars override the config file
Runtime flags — CLI flags override everything

OPENCLAW_CLAUDE_API_KEY=sk-ant-... openclaw start

Health Endpoint

GET http://localhost:3000/health

{
  "status": "ok",
  "uptime": 3621,
  "channels": {
    "whatsapp": "connected",
    "telegram": "connected",
    "slack": "disconnected"
  },
  "activeSessions": 4
}

Logs

Logs are written to ~/.openclaw/logs/openclaw.log.

Level	What It Shows
`error`	Fatal errors, crashed channels
`warn`	Non-fatal issues, retries
`info`	Message received/sent, agent called
`debug`	Full message payloads, API calls
`trace`	Everything — very verbose

Set log level in openclaw.json:

{
  "logLevel": "info"
}

Or enable trace for your current session only with the /trace chat command.

Next: Chapter 5 — Workspaces & Multi-Agent Routing — Learn how workspaces organize users and how the router picks the right agent for each message.