Organized AI · Educational Series

OpenClaw Architecture

Learn the OpenClaw personal AI assistant from the ground up — Gateway, channels, agents, skills, nodes, Tailscale, and security. A phased, interactive learning journey. The lobster way. 🦞

6 Phases

20+ Channels

3 Learning Modes

Node.js 22.16+ Required

Phase 1 — The Gateway

The single WebSocket control plane at :18789. Sessions, channel adapters, tool routing, event streaming, config hot-reload.

ws://127.0.0.1:18789 openclaw.json Control UI openclaw doctor

→

Phase 2 — Channels

20+ messaging adapters. DM pairing policy. Group routing. One internal protocol. The Pi agent never knows which channel sent the message.

Telegram Slack Discord WhatsApp dmPolicy: pairing

→

Phase 3 — Agents + Sessions

The Pi agent in RPC mode. The 6-step agent loop. Main vs. group sessions. Thinking levels. Agent-to-agent communication via sessions_* tools.

Pi agent RPC AGENTS.md SOUL.md sessions_send /compact /new /think

→

Phase 4 — Skills + Nodes

Skills = what the agent knows. Nodes = what the agent can do. ClawHub, workspace skills, macOS/iOS/Android companion apps, and node.invoke.

ClawHub SKILL.md macOS node iOS Voice Wake node.invoke

→

Phase 5 — Tailscale + Security

Gateway runs on loopback by design. Tailscale Serve for tailnet access, Funnel for public. Six security layers. Docker sandboxing. Default-safe, opt-in to exposure.

Tailscale Serve Tailscale Funnel Docker sandbox openclaw doctor

→

Phase 6 — Deployment

Deploy to Cloudflare Pages, run a remote Linux gateway, Docker compose, or Nix. Your own version of this doc site from what you built.

Cloudflare Pages Docker compose Nix pnpm deploy

→

Quick Start

# Clone and run → git clone https://github.com/Organized-AI/openclaw-education → cd openclaw-education → pnpm install → pnpm setup ✓ Mode selected: Full Hands-On → pnpm phase:1 # The Gateway → pnpm phase:2 # Channels → pnpm phase:3 # Agents + Sessions → pnpm phase:4 # Skills + Nodes → pnpm phase:5 # Tailscale + Security → pnpm phase:6 # Deployment + Doc Site → pnpm deploy

Learning Modes

Docs Only

Browse architecture diagrams, phase breakdowns, and concept explainers. No OpenClaw install needed. Just Node.js + pnpm.

★ Diagrams + Docs

Generate real Mermaid diagrams and annotated examples. OpenClaw optional. The recommended starting point for workshops.

Full Hands-On

Live Gateway + channel exercises + diagrams. Connect real channels on your machine. OpenClaw required.

Key Concepts

01 — Gateway

WebSocket server at :18789. Not the AI — the router. Think post office, not postman.

02 — Channels

20+ adapters normalize inbound messages into one OpenClaw format. The agent never knows the difference.

03 — Pi Agent

Runs the loop: receive → think → tools → stream reply. Connects via RPC. Channel-agnostic.

04 — Sessions

main = your 1:1. Groups get isolated sessions. Each carries model, history, usage stats.

05 — Skills

Markdown files injected into agent context. Three tiers: bundled, managed (ClawHub), workspace.

06 — Nodes

macOS/iOS/Android companion apps exposing device capabilities via node.invoke.

Prerequisites

Tool	Version	Required	Notes
Node.js	22.16+ or 24	✓ Required	Runtime for all phase scripts
pnpm	8+	✓ Required	`npm install -g pnpm`
Git	any	✓ Required	Clone and commit phase outputs
OpenClaw	latest	★ Hands-On	`npm install -g openclaw@latest`
Tailscale	any	◌ Optional	Phase 5 remote exercises
Cloudflare	—	◌ Optional	Phase 6 deployment

Full Architecture

Messaging Surfaces — 20+ channels ────────────────────────────────────────────────────────────────────────────── WhatsApp Telegram Slack Discord Signal iMessage Matrix IRC +13 │ │ │ │ │ │ │ │ └─────────┴──────────┴─────────┴──────────┴──────────┴──────────┴────────┘ │ Channel Adapters (each runs inside the Gateway process) │ ▼ ┌──────────────────────────────────────────────────────────────────────────┐ │ GATEWAY │ │ ws://127.0.0.1:18789 │ │ │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌──────────────┐ │ │ │ Sessions │ │ Tool Router │ │ Event Stream│ │ Config │ │ │ │ main+groups │ │ browser │ │ typing │ │ hot-reload │ │ │ │ per-thread │ │ canvas/cron │ │ presence │ │ openclaw │ │ │ │ │ │ nodes/hooks │ │ media/usage │ │ .json │ │ │ └─────────────┘ └─────────────┘ └─────────────┘ └──────────────┘ │ └──────────────────────────────┬───────────────────────────────────────────┘ │ ┌─────────────────────┼────────────────────────┐ │ │ │ ▼ ▼ ▼ ┌─────────────────┐ ┌─────────────────┐ ┌──────────────────────┐ │ PI AGENT │ │ CLI │ │ Companion Nodes │ │ (RPC mode) │ │ openclaw agent │ │ macOS — menu bar │ │ │ │ openclaw send │ │ iOS — Voice Wake │ │ think → tools │ │ openclaw doctor │ │ Android — full node │ │ → stream reply │ │ │ │ system.run/notify │ └────────┬────────┘ └─────────────────┘ └──────────────────────┘ │ Agent Workspace Tailscale layer (optional) ~/.openclaw/workspace/ Serve → tailnet-only access AGENTS.md SOUL.md TOOLS.md Funnel → public + password auth skills/ (ClawHub + workspace)

Phase 1

The Gateway

The single WebSocket control plane that powers all of OpenClaw. It is not the AI. It is the router.

pnpm phase:1

What Is the Gateway?

A local WebSocket server at ws://127.0.0.1:18789 that receives messages from channels, routes them to the Pi agent, and delivers replies back through the correct channel adapter.

Mental model: The Gateway is the post office. The Pi agent is the letter writer. The channels are the mailboxes. The post office does not write letters — it routes them.

What Connects to the Gateway

Channel Adapters

In-process adapters that pipe inbound messages in and deliver replies out. One per connected channel.

Pi Agent (RPC)

Runs the agent loop over WebSocket. Streams replies token by token.

CLI Tools

openclaw agent, openclaw send — connect as WS clients.

Companion Nodes

macOS, iOS, Android apps connect as WS clients to expose device capabilities.

Control UI + WebChat

Browser-based session management at http://127.0.0.1:18789.

What the Gateway Manages

SessionsOne per conversation thread, persist across restarts

Channel AdaptersOne per connected channel, normalizes native format

Tool RoutingRoutes tool calls to browser, Canvas, cron, webhooks, nodes

Event StreamingTyping, presence, media pipeline, usage tracking

Config Hot-ReloadWatches ~/.openclaw/openclaw.json, applies without restart

Gateway Architecture

Inbound — 20+ channels WhatsApp Telegram Slack Discord Signal iMessage Matrix +13 more │ │ │ │ │ │ │ └─────────┴────────┴────────┴─────────┴─────────┴─────────┘ │ Channel Adapters (normalize to OpenClaw struct) │ ▼ ┌──────────────────────────────────────────────────────────┐ │ GATEWAY :18789 │ │ Sessions │ Tool Router │ Event Stream │ Config Reload │ └───────────────────────────┬──────────────────────────────┘ │ RPC over WebSocket │ ▼ ┌──────────────────────────────────────────────────────────┐ │ PI AGENT — 6-step loop │ │ 1. Receive 2. Load context 3. Think │ │ 4. Tool calls 5. Stream reply 6. Update session │ └──────────────────────────────────────────────────────────┘

Config Reference — openclaw.json

The Gateway reads all configuration from ~/.openclaw/openclaw.json. It hot-reloads most settings without a restart.

Minimal Config

{ "agent": { "model": "anthropic/claude-sonnet-4-6" } }

Full Config Anatomy

Section	Key Fields	Notes
agent	model, thinkingLevel	AI model and reasoning depth
channels.telegram	botToken, allowFrom, dmPolicy	Create bot via @BotFather
channels.slack	botToken, appToken	Socket Mode required
channels.discord	token	Message Content Intent required
gateway	bind, port, auth, tailscale	bind always "loopback"
agents.defaults	workspace, sandbox.mode	sandbox: "none" or "non-main"
browser	enabled, color	Browser automation toggle

Critical Rules

gateway.bind = "loopback" — always. Never 0.0.0.0. Use Tailscale for remote access.

gateway.tailscale.mode = off / serve / funnel
channels.*.dmPolicy = "pairing" (recommended) or "open"
agents.defaults.sandbox.mode = "none" (main) or "non-main" (Docker for groups)

Phase 2

Channels

20+ messaging channels. One internal protocol. The Pi agent never knows which channel a message came from.

pnpm phase:2

Channel Routing

Each channel adapter runs inside the Gateway process. It normalizes inbound messages into OpenClaw's internal format and translates outbound replies back to each channel's native format. Telegram gets Markdown. Slack gets Block Kit. Discord gets embeds. The agent never knows the difference.

Routing Path

1. User sends messageOn any channel (Telegram, Slack, etc.)

2. Channel adapter receivesgrammY, Bolt, discord.js, Baileys...

3. Normalize to OpenClaw structCommon format regardless of source

4. Gateway finds/creates sessionBased on thread ID + channel

5. Dispatch to Pi agentRPC over WebSocket

6. Agent streams replyToken by token

7. Route back through adapterTranslate to channel-native format

Supported Channels

Baileys adapter. QR code login via openclaw channels login.

grammY adapter. Create bot via @BotFather, add botToken to config.

Slack

Bolt adapter. Socket Mode required. Install to workspace with bot scopes.

Discord

discord.js adapter. Message Content Intent required.

Signal

signal-cli adapter. Local Signal client required.

iMessage

BlueBubbles adapter. Requires BlueBubbles Server on macOS.

Plus: Google Chat, Microsoft Teams, Matrix, IRC, LINE, Mattermost, Nostr, Tlon, Twitch, Zalo, WeChat, WebChat, and more.

DM Pairing Policy

The default security model for direct messages. Unknown senders get a pairing code — the bot ignores them until you approve.

DM Pairing Flow Inbound DM arrives │ ▼ Sender in allowFrom list? │ ┌────┴────┐ │ │ YES NO │ │ ▼ ▼ Create dmPolicy? Session │ ┌───┴───┐ │ │ "open" "pairing" │ │ ▼ ▼ Create Send pairing code Session Wait for approval │ ▼ openclaw pairing approve telegram <code> │ ▼ Add to allowFrom → Create Session

Channel Setup Guides

Create bot via @BotFather on Telegram
Add botToken to channels.telegram in openclaw.json
Restart gateway

Slack

Create app at api.slack.com
Enable Socket Mode
Add bot scopes (chat:write, app_mentions:read, etc.)
Install to workspace

Discord

Create bot at Discord Developer Portal
Enable Message Content Intent
Invite with bot + applications.commands scopes

→ openclaw channels login Scan QR code with WhatsApp mobile app

Verify

→ openclaw doctor ✓ Gateway running ✓ Telegram connected ✓ Slack connected

Key insight: The Gateway is channel-agnostic at the session layer. Adding a new channel is config-only — no code changes, no agent modifications.

Phase 3

Agents + Sessions

The Pi agent connects to the Gateway in RPC mode, receives messages, runs the agent loop, and streams replies.

pnpm phase:3

Agent Architecture

The Agent Loop (6 Steps)

Pi Agent — RPC Mode 1. RECEIVE message + session context from Gateway │ ▼ 2. LOAD prompt context: AGENTS.md + SOUL.md + TOOLS.md + active skills + session history │ ▼ 3. THINK optional reasoning: off │ minimal │ low │ medium │ high │ xhigh │ ▼ 4. TOOLS execute tool calls: browser │ canvas │ cron │ system.run sessions_* │ node.invoke │ ▼ 5. STREAM reply token by token → Gateway → Channel │ ▼ 6. UPDATE append history, update token count + cost prune if context window exceeded

Agent Workspace

Located at ~/.openclaw/workspace/. These files define your agent's personality and capabilities:

File	Purpose
AGENTS.md	Your instructions — applies universally across all channels
SOUL.md	Personality, values, tone of voice
TOOLS.md	Tool descriptions and usage guidance
skills/<name>/SKILL.md	Per-skill instructions (see Phase 4)

Key insight: The agent does not know which channel it is responding to. AGENTS.md applies universally. This is by design — your assistant behaves consistently whether the message came from Telegram, Slack, or Discord.

Session Model

Session Types

main

Your personal 1:1 with the assistant. Full tool access. No sandboxing by default. One per Gateway instance.

Group Sessions

One per group chat thread. Keyed by group ID. Can be sandboxed independently via Docker containers.

Session Fields

Field	Description
model	Which AI model to use for this session
thinkingLevel	off / minimal / low / medium / high / xhigh
verboseLevel	Controls response detail level
sendPolicy	Controls message sending behavior
groupActivation	How the agent activates in group chats
history	Conversation history for context
tokenCount	Tokens used in this session
cost	Running cost for this session

Chat Commands

Command	What It Does
/new	Wipe history entirely — fresh session
/compact	Summarize and compress history
/think <level>	Change thinking depth for this session
/verbose	Toggle verbose output
/usage	Show token usage and costs
/status	Show session status
/activation	Configure group activation mode

Agent-to-Agent Communication

The sessions_* tools enable multi-agent coordination:

sessions_list — all active sessions with metadata
sessions_history — transcript of a specific session
sessions_send — message another session

Phase 4

Skills + Nodes

Skills = what the agent knows. Nodes = what the agent can do.

pnpm phase:4

Skills Platform

Skills are markdown files injected into the agent's context. They teach the agent specific workflows without changing the model. Think employee training manuals, not model fine-tuning.

Three Skill Tiers

Bundled

Ship with OpenClaw. Always available. Includes: browser automation, Canvas, cron jobs.

Managed (ClawHub)

Community registry at clawhub.com. Install on demand. Curated and versioned.

Workspace

Your skills at ~/.openclaw/workspace/skills/<name>/SKILL.md. Active immediately, no restart.

Creating a Workspace Skill

# Create a custom skill → mkdir -p ~/.openclaw/workspace/skills/gtm-audit → cat > ~/.openclaw/workspace/skills/gtm-audit/SKILL.md << 'EOF' # GTM Tag Audit When asked to audit GTM tags: 1. Open the GTM container in the browser 2. List all tags with their trigger conditions 3. Check for duplicate or conflicting tags 4. Verify conversion tracking setup 5. Report findings in a structured table EOF # Active immediately — no restart needed

Nodes

Nodes are companion apps (macOS, iOS, Android) that pair with the Gateway via WebSocket and expose device-local capabilities. The agent invokes nodes via node.invoke — it never touches devices directly.

macOS Node

Action	Description
system.run	Execute shell commands on the host machine
system.notify	macOS native notifications
canvas.*	Canvas drawing and manipulation
camera.snap	Take photos with connected camera
screen.record	Screen recording
location.get	Device location

Elevated mode: type /elevated on for host permissions.

iOS Node

Voice Wake, Talk Mode, Canvas, camera, screen recording, Bonjour pairing.

Android Node

Chat + Voice + Canvas, camera, screen recording, notifications, location, SMS, contacts, calendar.

Node Invocation Flow

node.invoke — how the agent uses devices Pi Agent │ │ node.invoke("system.run", { cmd: "..." }) │ ▼ ┌──────────────┐ │ GATEWAY │ ─── routes to registered node └──────┬───────┘ │ ▼ ┌──────────────────┐ │ macOS Node │ ─── executes on host │ (menu bar app) │ └──────┬───────────┘ │ │ { result: "...", exitCode: 0 } │ ▼ Pi Agent ─── processes result, continues loop

Key insight: Skills = what the agent knows. Nodes = what the agent can do. A skill can orchestrate multiple node capabilities — e.g., a "morning briefing" skill that uses camera.snap, location.get, and system.notify together.

Phase 5

Tailscale + Security

Default-safe. Opt-in to exposure. Every increase in access requires explicit configuration.

pnpm phase:5

Tailscale + Gateway

The Gateway runs on loopback by design — only your machine can reach it. Tailscale provides secure remote access without opening ports.

Access Modes

Local Only

Default. gateway.bind: "loopback". Only processes on this machine can connect. No auth needed.

Tailscale Serve

Tailnet-only access. Tailscale identity = authentication. No password needed. Your devices on your tailnet.

Tailscale Funnel

Public internet access. Requires gateway.auth.mode: "password". OpenClaw refuses to start without it.

Serve Config

{ "gateway": { "bind": "loopback", "tailscale": { "mode": "serve", "resetOnExit": false } } }

Funnel Config

{ "gateway": { "bind": "loopback", "auth": { "mode": "password", "password": "your-strong-password-here" }, "tailscale": { "mode": "funnel" } } }

Network Topology

Three Access Modes LOCAL TAILSCALE SERVE TAILSCALE FUNNEL 127.0.0.1 tailnet only public internet │ │ │ │ WireGuard tunnel HTTPS → Funnel │ │ │ │ │ Password check │ │ ┌───┴───┐ │ │ pass fail → 401 │ │ │ └───────────────┴───────────────────┘ │ ▼ GATEWAY :18789 │ ┌───────┴───────┐ │ │ main session group sessions full access Docker sandbox

Security Model — Six Layers

Layer 1 — Gateway BindingLoopback only. Never 0.0.0.0.

Layer 2 — DM PairingUnknown senders get pairing code. Bot ignores until approved.

Layer 3 — Session SandboxingNon-main sessions run in Docker containers.

Layer 4 — Funnel PasswordHard enforcement. OpenClaw won't start without it.

Layer 5 — Tool DenylistConfigurable per-agent tool restrictions.

Layer 6 — openclaw doctorPre-flight health check after every config change.

Docker Sandbox — Tool Access

Allowed in Sandbox

bash, process, read, write, edit, sessions_*

Denied in Sandbox

browser, canvas, nodes, cron, discord, gateway

Security Checklist

☐ gateway.bind: "loopback"
☐ dmPolicy: "pairing" on all channels
☐ Funnel requires password
☐ Groups: requireMention: true
☐ sandbox.mode: "non-main" if groups connected
☐ openclaw doctor runs clean

Phase 6

Deployment

Aggregates all phase documentation into a static site and deploys it — or saves locally.

pnpm phase:6

Deployment Guide

scripts/generate-docs.js reads all PHASE-*/DOCUMENTATION/*.md and AGENT-HANDOFF/*.md, combines with index.html into OUTPUT/local/, and optionally pushes to Cloudflare Pages.

Cloudflare Pages

# Set credentials → export CLOUDFLARE_API_TOKEN="your-token" → export CLOUDFLARE_ACCOUNT_ID="your-account-id" # Deploy → pnpm deploy ✓ Generated docs from 6 phases ✓ Deployed to openclaw-education.pages.dev

Local Fallback

→ pnpm docs ✓ Generated to OUTPUT/local/ → open OUTPUT/local/index.html

Alternative Deployment Paths

Remote Linux Gateway

npm install -g openclaw@latest then openclaw onboard --install-daemon. Runs as a systemd user service.

Docker Compose

git clone openclaw && docker compose up -d. Container-based deployment.

Nix

nix run github:openclaw/nix-openclaw. Declarative configuration.

What You Built

By completing all 6 phases, you now have:

Running Assistant

Gateway daemon running at ws://127.0.0.1:18789
Connected channels (Telegram, Slack, Discord, WhatsApp, etc.)
Pi agent responding with personalized AGENTS.md and SOUL.md
At least one workspace skill active

Secure Remote Access

Tailscale Serve configured for tailnet access
DM pairing enabled on all channels
Docker sandboxing for non-main sessions
openclaw doctor passing all checks

Documentation Site

Deployed to Cloudflare Pages or saved locally
Generated from your own phase outputs

Complete Mental Model

The Full Picture Channels (20+) │ Channel Adapters (normalize to OpenClaw struct) │ ▼ ┌──────────────────────────────────────┐ │ GATEWAY :18789 │ │ Sessions │ Tools │ Events │ Config │ └──────────────────┬───────────────────┘ │ ▼ ┌──────────────────────────────────────┐ │ PI AGENT (RPC) │ │ receive → think → tools → stream │ └──────────┬──────────┬───────────────┘ │ │ Skills (knows) Nodes (does) bundled macOS / iOS / Android ClawHub system.run / camera workspace Voice Wake / Canvas │ │ └────┬─────┘ │ Tailscale Serve / Funnel (secure remote access)

Where to Go Next

Official Docs

docs.openclaw.ai

OpenClaw Source

github.com/openclaw/openclaw

ClawHub

Community skills registry

Organized AI

github.com/Organized-AI