OpenClaw Deep Dive

What is OpenClaw?

• Self-hosted AI assistant connecting 17+ messaging channels to LLMs
• Hub-and-spoke gateway architecture on port 18789
• Tagline: "EXFOLIATE! EXFOLIATE!"

Origin Story

Why It Blew Up

• Universal messaging hub — one AI across all platforms
• Self-hosted — no cloud dependency, full privacy
• Production-ready — 913K LOC, battle-tested at scale
• Extensible — 52 skills, 35 extensions, plugin system
• Native apps — macOS menu bar, iOS/Android clients

By the Numbers

High-Level Architecture

┌─────────────────────────────────────────────────────────┐
│  Channels (WhatsApp, Discord, Slack, Telegram, etc.)   │
└─────────────────────┬───────────────────────────────────┘
                      │
                      ▼
            ┌─────────────────┐
            │  Gateway :18789 │  ← WebSocket + HTTP
            └────────┬─────────┘
                     │
                     ▼
            ┌─────────────────┐
            │   Agent Core    │  ← Pi Agent, routing, sessions
            └────────┬─────────┘
                     │
                     ▼
        ┌────────────────────────┐
        │  Tools & LLM Providers │  ← Claude, GPT, Gemini
        └────────────────────────┘
  

Tech Stack

Monorepo Structure

The Gateway

export async function startGatewayServer(
  port: number,
  config: GatewayConfig
): Promise<GatewayServer> {
  // WebSocket + HTTP server
  // Channel managers
  // Agent dispatcher
}

Gateway: Server Startup

export async function startGatewayServer(port: number, config: GatewayConfig) {
  const httpServer = http.createServer(handleRequest);
  const wss = new WebSocketServer({ server: httpServer });

  wss.on('connection', async (ws, req) => {
    const session = await createSession(ws, req);
    attachFrameHandlers(session);
  });

  httpServer.listen(port);
  await startChannels(config.channels);
  await startDiscovery(port);

  return { httpServer, wss, config };
}
  

src/gateway/server.ts

WebSocket Protocol Frames

const RequestFrame = Type.Object({
  type: Type.Literal('request'),
  id: Type.String(),
  method: Type.String(),
  params: Type.Optional(Type.Any())
});

const ResponseFrame = Type.Object({
  type: Type.Literal('response'),
  id: Type.String(),
  result?: Type.Any(),
  error?: Type.String()
});

const EventFrame = Type.Object({
  type: Type.Literal('event'),
  event: Type.String(),
  data: Type.Any()
});
  

src/gateway/protocol.ts

Connect Handshake

RPC Methods & Authorization

const READ_METHODS = new Set([
  'getChannels', 'getConversations', 'getMessages', 'getConfig'
]);

const WRITE_METHODS = new Set([
  'sendMessage', 'updateConfig', 'startChannel', 'stopChannel'
]);

function authorizeGatewayMethod(method: string, session: Session) {
  if (WRITE_METHODS.has(method) && !session.isAuthenticated) {
    throw new Error('Write methods require authentication');
  }
  return true;
}
  

src/gateway/auth.ts — 50+ RPC methods total

Gateway HTTP Layer

async function handleRequest(req: IncomingMessage, res: ServerResponse) {
  // Execute plugin hooks
  const hookResult = await runHttpHooks(req);
  if (hookResult) return sendResponse(res, hookResult);

  // Tool HTTP endpoints
  if (req.url?.startsWith('/tools/')) return handleToolRequest(req, res);

  // OpenAI-compatible API
  if (req.url === '/v1/chat/completions') return handleChatCompletion(req, res);

  // Control UI
  if (req.url === '/') return serveControlUI(res);

  res.writeHead(404); res.end();
}
  

src/gateway/http.ts

Channel Manager

async function startChannel(channelId: string, config: ChannelConfig) {
  const abortController = new AbortController();
  const adapter = await createAdapter(config.type, config);

  adapter.on('message', async (msg) => {
    const conversation = await getOrCreateConversation(channelId, msg.from);
    await dispatchToAgent(conversation, msg);
  });

  await adapter.connect(abortController.signal);
  channelRegistry.set(channelId, { adapter, abortController });

  broadcastEvent('channelStarted', { channelId });
}
  

src/gateway/channels.ts

Discovery & mDNS

• Bonjour/mDNS for local network discovery
• Tailscale integration for remote access
• Wide-area DNS-SD for internet-scale discovery
• Service type: _openclaw._tcp.local.
• Advertises port, protocol version, device ID, capabilities

Channel Abstraction

• InboundAdapter — receive messages from platform
• OutboundAdapter — send messages to platform
• MessageNormalizer — convert to unified format
• AttachmentHandler — file upload/download
• ReactionHandler — emoji reactions
• ThreadHandler — threaded conversations
• PresenceHandler — typing indicators, online status
• MembershipHandler — group/channel member mgmt
• EditHandler — message editing
• DeleteHandler — message deletion
• SearchHandler — message history search
• AuthHandler — OAuth/token refresh
• RateLimiter — per-platform rate limits
• RetryPolicy — exponential backoff
• ErrorMapper — platform errors → unified codes
• CapabilityDetector — feature support matrix

16 interfaces for one unified messaging abstraction

Outbound Adapter Pattern

const telegramOutbound: OutboundAdapter = {
  async sendText(conversationId, text, options) {
    const chunks = chunkMessage(text, 4096);
    for (const chunk of chunks) {
      await bot.api.sendMessage(conversationId, chunk, {
        parse_mode: 'Markdown',
        disable_web_page_preview: options?.noPreview
      });
    }
  },

  async sendMedia(conversationId, attachment) {
    const file = new InputFile(attachment.data);
    await bot.api.sendDocument(conversationId, file);
  }
};
  

src/channels/telegram/outbound.ts

Discord & WhatsApp

// No chunking needed
chunker: null,
maxLength: 2000,

async sendText(channelId, text) {
  const channel = await
    client.channels.fetch(channelId);
  await channel.send(text);
}
      

Plugin System

async function loadOpenClawPlugins(pluginDir: string) {
  const manifests = await glob('**/openclaw.plugin.json', { cwd: pluginDir });

  for (const manifestPath of manifests) {
    const manifest = await readJSON(manifestPath);
    const plugin = await import(manifest.entry);
    await plugin.initialize(gatewayContext);
    pluginRegistry.set(manifest.id, plugin);
  }
}
  

{
  "id": "spotify-player",
  "version": "1.2.0",
  "entry": "./dist/index.js",
  "hooks": ["beforeMessage", "afterMessage"],
  "capabilities": ["audio-playback"]
}