OpenClaw-Architektur im Detail: Technische Prinzipien und Erweiterungspraxis der Dreischicht-Architektur

Kurzfassung (Architektur zuerst verstehen)

OpenClaw am schnellsten erfassen, wenn Sie drei Schichten im Kopf behalten: Gateway für Sessions, Channel für Nachrichtenrouting, LLM für Modellschnittstellen.
Ordnet sich ein Problem einer dieser Schichten zu, gehen Fehlersuche und Erweiterung deutlich schneller.
Neue Channels oder Provider entwickeln heißt im Kern: Schnittstelle implementieren und registrieren.

Um zwei Uhr nachts saß ich vor dem OpenClaw-Code und wollte einen DingTalk-Channel hinzufügen. Dutzende Dateien in src – gateway, channel, llm – alles verflochten. Wo anfangen? Ändere ich das Gateway und breche andere Channels? WhatsApp-Code kopieren? Und wenn nichts mehr startet?

Ehrlich gesagt: frustrierend. Die offizielle Doku erklärt die Nutzung, nicht den inneren Ablauf. Weiterentwicklung fühlte sich an wie Blindes Tasten – Webhook-Handler gefunden, aber Routing unklar; LLM-Aufruf gesehen, Provider-Registrierung undurchsichtig.

Drei Tage Quellcode-Analyse später wurde klar: Gateway für Sessions, Channel für Routing, LLM für Schnittstellen – Dreischicht-Architektur mit klaren Grenzen. Damit ist Erweiterung kein Raten mehr, sondern systematisch.

Dieser Artikel fasst die Erkenntnisse zusammen: warum drei Schichten, welches Problem jede löst, wie Gateway Sessions verwaltet, wie Channels Plattformen adaptieren, wie das Provider-Plugin-System im LLM-Layer funktioniert – plus Anleitung für Custom Channels und Provider.

Günstiger Einstieg: ArkClaw macht KI-Agenten zugänglich

OpenClaw (der „Hummer“) ist mächtig, aber die Konfiguration schreckt ab? ByteDance Volcano Engine bietet ArkClaw mit minimaler Hürde: ohne Server- und Token-Gefummel – ein Klick für einen 24/7-Agenten, der Browser steuert, Skripte ausführt und Kalender verwaltet.

Preis: 9,9 Yuan/Monat; mit Einladungscode ZLKUK54M (hier registrieren) 8,9 Yuan. Entwickler: Coding Plan Pro kann kostenlos inkludiert sein.

OpenClaw-Architektur im Überblick: Warum drei Schichten?

Am Anfang fragte ich mich: Warum so viel Schichtung? Nachricht vom Nutzer ans LLM – fertig?

Bei kleinem Umfang reicht Monolithik. OpenClaw soll aber Multi-Plattform (WhatsApp, Telegram, Gmail), Multi-Modell (Claude, GPT, lokal) und hunderte Sessions beherrschen. Ohne Schichten wächst alles zusammen – eine Änderung kann alles beeinflussen.

Design-Philosophie der Dreischicht-Architektur

Drei Schichten, je eine Aufgabe:

Gateway-Schicht (Session-Zentrale)

• Vollständiger Session-Lebenszyklus
• Nachrichten-Queue und Scheduling
• Authentifizierung und Berechtigungen
• WebSocket-Langzeitverbindungen

Channel-Schicht (Plattform-Adapter)

• Plattform-Nachrichtenformate adaptieren
• Routing-Regeln (DM vs. Gruppe, @-Trigger)
• Ereignisse (Empfang, Senden, Fehler)

LLM-Schicht (Modellschnittstelle)

• Einheitliche Provider-Schnittstelle
• Tool Calling (Function Calling)
• Streaming-Antworten
• MCP-Server-Integration

Gesamter Nachrichtenfluss

Konkretes Beispiel – WhatsApp-Nachricht an den Bot:

1. Channel empfängt: WhatsApp-Webhook, Normalisierung auf internes Format
2. Routing: DM oder Gruppe? @Bot? Berechtigung?
3. Gateway plant: Session finden/erstellen, Nachricht in Queue
4. LLM verarbeitet: Provider wählen (z. B. Anthropic), Kontext senden
5. Antwort zurück: LLM → Gateway → Channel → Nutzer

Das Geniale: Schichten bleiben unabhängig. Neue Plattform → nur Channel. Neues Modell → nur LLM. Gateway unverändert.

Gateway-Schicht: Kern der Session-Verwaltung

Beim ersten Gateway-Quellcode-Lesen war unklar: Was speichert ein Session-Objekt pro Nutzer?

Session-Lebenszyklus

Gateway als Paketsortierzentrum: Nutzer = Adresse, Session = Zustellprotokoll.

Railway - Moderne Deployment-Plattform, ohne DevOps-Aufwand, in Minuten live

Jetzt starten →Anzeige

Session-Inhalt:

• conversationHistory: Dialogverlauf (letzte N Nachrichten)
• context: Kontextvariablen (Einstellungen, temporäre Daten)
• state: Zustand (idle, processing, waiting)
• channelInfo: Herkunfts-Channel

Lebenszyklus-Management:

// Vereinfachtes Beispiel – Kernlogik
class SessionManager {
  // Bei eingehender Nachricht
  async handleMessage(userId, channelId, message) {
    // 1. Session finden (oder anlegen)
    let session = this.getOrCreate(userId, channelId);

    // 2. Verlauf aktualisieren
    session.conversationHistory.push(message);

    // 3. In Verarbeitungs-Queue
    await this.messageQueue.enqueue(session, message);

    // 4. Persistieren (Crash-Schutz)
    await this.persist(session);
  }
}

OpenClaw nutzt per-channel-peer-Isolation: Derselbe Nutzer auf WhatsApp und Telegram = zwei Sessions. Kein Kontext-Mix – Technik-Diskussion und Wetter-Frage bleiben getrennt.

Prioritätsstrategie für Nachrichtenplanung

Gateway verarbeitet nicht sofort alles – Scheduling-Queue löst zwei Probleme:

Problem 1: Concurrency
100 gleichzeitige Nutzer würden das LLM-API überlasten. Queue limitiert z. B. auf 10 parallele Anfragen.

Problem 2: Retry bei Fehlern
LLM-Aufruf schlägt fehl? Gateway retry bis 3× mit steigendem Intervall (1s, 2s, 4s).

// Kernlogik Nachrichten-Queue
class MessageQueue {
  async enqueue(session, message) {
    if (this.activeJobs >= this.maxConcurrency) {
      this.waitingQueue.push({ session, message });
      return;
    }

    this.activeJobs++;
    try {
      await this.process(session, message);
    } catch (error) {
      await this.retryWithBackoff(session, message);
    } finally {
      this.activeJobs--;
      this.processNext();
    }
  }
}

WebSocket-Langzeitverbindungen

Bei Echtzeit-Anwendungen (z. B. Support-Bot) ist Verbindungsmanagement kritisch.

OpenClaw:

• Heartbeat: Ping alle 30 Sekunden, Timeout = Verbindung tot
• Auto-Reconnect: Exponentielles Backoff (1s, 2s, 4s … max. 30s)
• State-Sync: Session nach Reconnect wiederherstellen

Kleine Details, große Wirkung auf Stabilität. Ohne Heartbeat: scheinbar lebende Verbindung, Nachrichten verschwinden.

Channel-Schicht: Multi-Plattform-Nachrichtenrouting

Die interessanteste Schicht: Wie einheitlich verarbeiten, wenn Formate völlig unterschiedlich sind?

Adapter-Muster

WhatsApp:

{
  "from": "1234567890",
  "body": "Hallo",
  "type": "text"
}

Telegram:

{
  "message": {
    "chat": {"id": 123},
    "text": "Hallo"
  }
}

Ohne Muster explodiert der Code. OpenClaw: standardisiertes Message-Interface, jeder Channel konvertiert.

// Standardisiertes Nachrichtenformat
interface StandardMessage {
  userId: string;
  content: string;
  timestamp: number;
  metadata: any;
}

// WhatsApp-Adapter
class WhatsAppChannel implements Channel {
  adaptMessage(rawMessage): StandardMessage {
    return {
      userId: rawMessage.from,
      content: rawMessage.body,
      timestamp: Date.now(),
      metadata: { platform: 'whatsapp' }
    };
  }
}

Gateway und LLM kennen nur StandardMessage, nicht die Plattform.

Routing-Regeln

Channel entscheidet: Antworten oder ignorieren.

dmPolicy (DM-Richtlinie)

• pairing: Erst koppeln (sicherste Option)
• allowlist: Nur Whitelist
• open: Alle (öffentlicher Bot)
• disabled: DMs aus

mentionGating (Gruppen-@-Trigger)
Nur bei @Bot antworten – gegen Spam:

class TelegramChannel {
  shouldRespond(message): boolean {
    if (message.chat.type === 'private') {
      return this.checkDmPolicy(message.from.id);
    }

    if (message.chat.type === 'group') {
      const mentioned = message.entities?.some(
        e => e.type === 'mention' && e.user.id === this.botId
      );
      return mentioned;
    }

    return false;
  }
}

Bei DingTalk-Channel habe ich dieselbe Logik genutzt – @-Erkennung über atUsers, gleiches Gerüst.

Custom Channel – typischer Ablauf

Discord-Anbindung:

1. Channel-Klasse: Channel-Interface implementieren
2. Pflichtmethoden:
   • start(): Channel starten (Webhook/WebSocket)
   • sendMessage(): Nachricht senden
   • adaptMessage(): Format-Konvertierung
3. Registrieren: Konfiguration ergänzen
4. Testen: ngrok für Webhook

Vollständige Beispiele im Praxis-Kapitel am Ende.

LLM-Schicht: Plugin-Design für Modellschnittstellen

2026 großes Refactoring: von Hardcoding zu Plugin-System – entscheidend für Modellvielfalt.

Provider-Plugin-System

Altes Design (Pseudocode):

Alibaba Cloud - Top-Wahl für Entwickler, exklusiv 15 % Rabatt auf Lighthouse-Server

15 % Rabatt sichern →Anzeige

// Alt: Hardcoded
if (config.provider === 'anthropic') {
  return new AnthropicClient();
} else if (config.provider === 'openai') {
  return new OpenAIClient();
}

Jedes neue Modell = neues if-else.

Neues Design – Provider-Interface:

interface LLMProvider {
  name: string;

  chat(messages: Message[], options: ChatOptions): AsyncIterator<string>;

  supportTools(): boolean;

  initialize(config: ProviderConfig): void;
}

Implementierung reicht – System scannt und registriert beim Start:

class ProviderRegistry {
  private providers = new Map<string, LLMProvider>();

  register(provider: LLMProvider) {
    this.providers.set(provider.name, provider);
  }

  get(name: string): LLMProvider {
    return this.providers.get(name);
  }
}

const registry = new ProviderRegistry();
registry.register(new AnthropicProvider());
registry.register(new OpenAIProvider());
registry.register(new OllamaProvider());

Neues Modell: Provider-Klasse schreiben, registrieren – Kerncode unverändert.

Unterschiede gängiger Provider

Einheitliche Schnittstelle, unterschiedliche Details:

Anthropic (Claude)

• Native Streaming (stream: true)
• Spezielles Tool-Use-Format (tools-Array)
• Großes Kontextfenster (Claude 3.5: 200k Tokens)

OpenAI (ChatGPT)

• Function Calling vs. Tool Use (Legacy vs. neu)
• Streaming liefert Delta-Fragmente – manuell zusammensetzen
• Strikte Rate Limits (RPM/TPM)

Ollama (lokal)

• Kein API-Key, HTTP an lokalen Dienst
• Performance hardwareabhängig (CPU langsam, GPU empfohlen)
• Tool-Support modellabhängig (llama3 ja, qwen evtl. nein)

Ollama + Llama3 lokal: Tool-Format wich von Claude ab – Anpassung nötig.

Tool Use im Detail

Tool Use = KI ruft Funktionen auf.

Frage „Wie spät ist es in Peking?“:

1. KI wählt get_current_time
2. Tool-Aufruf: {"name": "get_current_time", "args": {"city": "Peking"}}
3. OpenClaw führt aus: {"time": "2026-02-05 20:30"}
4. KI antwortet: „In Peking ist es 20:30 Uhr.“

Tool-Registrierung:

const tools = [
  {
    name: 'get_current_time',
    description: 'Aktuelle Uhrzeit für eine Stadt abrufen',
    parameters: {
      type: 'object',
      properties: {
        city: { type: 'string', description: 'Stadtname' }
      },
      required: ['city']
    }
  }
];

async function executeTool(toolName, args) {
  const handlers = {
    'get_current_time': (args) => {
      return { time: new Date().toLocaleString('de-DE', { timeZone: 'Asia/Shanghai' }) };
    }
  };

  return handlers[toolName](args);
}

Wichtig: Sandbox-Isolation – sonst führt die KI rm -rf / aus. OpenClaw erlaubt nur vordefinierte Tools.

Praxis: OpenClaw-Architektur erweitern

Theorie reicht – zwei vollständige Beispiele: Discord-Channel und Kimi-Provider.

Custom Channel: Discord

Discord: WebSocket-Empfang, REST zum Senden.

Schritt 1: Channel-Interface

import { Client, GatewayIntentBits } from 'discord.js';

class DiscordChannel implements Channel {
  private client: Client;
  private gateway: Gateway;

  async start() {
    this.client = new Client({
      intents: [
        GatewayIntentBits.Guilds,
        GatewayIntentBits.GuildMessages,
        GatewayIntentBits.DirectMessages
      ]
    });

    this.client.on('messageCreate', async (msg) => {
      if (msg.author.bot) return;

      const standardMsg = this.adaptMessage(msg);
      const response = await this.gateway.handleMessage(standardMsg);
      await msg.reply(response.content);
    });

    await this.client.login(process.env.DISCORD_TOKEN);
  }

  adaptMessage(discordMsg): StandardMessage {
    return {
      userId: discordMsg.author.id,
      channelId: 'discord',
      content: discordMsg.content,
      timestamp: discordMsg.createdTimestamp,
      metadata: {
        guildId: discordMsg.guildId,
        channelType: discordMsg.channel.type
      }
    };
  }

  async sendMessage(userId: string, content: string) {
    const user = await this.client.users.fetch(userId);
    await user.send(content);
  }
}

Schritt 2: Registrierung

In config.json:

{
  "channels": {
    "discord": {
      "enabled": true,
      "token": "YOUR_DISCORD_BOT_TOKEN",
      "dmPolicy": "open"
    }
  }
}

Startskript:

import { DiscordChannel } from './channels/discord';

const gateway = new Gateway(config);
const discordChannel = new DiscordChannel(gateway, config.channels.discord);
gateway.registerChannel('discord', discordChannel);

await discordChannel.start();

Schritt 3: Test

KiloClaw - Managed OpenClaw für Unternehmen: AI-Agent-Orchestrierung und smartes Modell-Routing

Jetzt starten →Anzeige

1. Bot auf Discord Developer Portal anlegen, Token holen
2. Bot auf Server einladen
3. OpenClaw starten, DM testen
4. Logs auf Nachrichtenfluss prüfen

Stolperstein: Discord-Berechtigungen – Bot braucht Send Messages und Read Message History.

Custom Provider: Kimi

Kimi-API (Moonshot) ähnelt OpenAI, Details unterscheiden sich.

Provider-Implementierung:

class KimiProvider implements LLMProvider {
  name = 'kimi';
  private apiKey: string;
  private baseURL = 'https://api.moonshot.cn/v1';

  initialize(config: ProviderConfig) {
    this.apiKey = config.apiKey;
  }

  async *chat(messages: Message[], options: ChatOptions) {
    const response = await fetch(`${this.baseURL}/chat/completions`, {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${this.apiKey}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        model: options.model || 'moonshot-v1-8k',
        messages: messages.map(m => ({
          role: m.role,
          content: m.content
        })),
        stream: true,
        temperature: options.temperature || 0.7
      })
    });

    const reader = response.body.getReader();
    const decoder = new TextDecoder();

    while (true) {
      const { done, value } = await reader.read();
      if (done) break;

      const chunk = decoder.decode(value);
      const lines = chunk.split('\n').filter(line => line.trim());

      for (const line of lines) {
        if (line.startsWith('data: ')) {
          const data = line.slice(6);
          if (data === '[DONE]') continue;

          const parsed = JSON.parse(data);
          const content = parsed.choices[0]?.delta?.content;
          if (content) {
            yield content;
          }
        }
      }
    }
  }

  supportTools(): boolean {
    return false; // Kimi unterstützt Function Calling derzeit nicht
  }
}

Provider registrieren:

const registry = new ProviderRegistry();
registry.register(new KimiProvider());

const config = {
  llm: {
    provider: 'kimi',
    apiKey: process.env.KIMI_API_KEY,
    model: 'moonshot-v1-32k'
  }
};

Erfahrungen:

• Streaming-Format wie OpenAI – gut übernehmbar
• Fehlerbehandlung bei Timeout untypisch
• Kein Function Calling – bei tool-abhängigen Apps ungeeignet

Performance-Optimierung

Lauffähig ist der Anfang – Optimierung der nächste Schritt.

Session-Cache mit Redis
Standard: Session im RAM, Neustart = Verlust.

class RedisSessionStore {
  private redis: Redis;

  async get(userId: string, channelId: string): Promise<Session> {
    const key = `session:${channelId}:${userId}`;
    const data = await this.redis.get(key);
    return data ? JSON.parse(data) : null;
  }

  async set(session: Session) {
    const key = `session:${session.channelId}:${session.userId}`;
    await this.redis.setex(key, 3600, JSON.stringify(session));
  }
}

Nachrichten-Queue mit Bull
Bei hoher Last In-Memory-Queue ersetzen:

import Queue from 'bull';

const messageQueue = new Queue('openclaw-messages', {
  redis: { host: 'localhost', port: 6379 }
});

messageQueue.process(10, async (job) => {
  const { session, message } = job.data;
  return await gateway.processMessage(session, message);
});

Concurrency-Limit für LLM-API
OpenAI z. B. 60 RPM – p-limit:

import pLimit from 'p-limit';

const limit = pLimit(10);

const tasks = messages.map(msg =>
  limit(() => provider.chat(msg))
);

await Promise.all(tasks);

Gemessene Wirkung:

• Vorher: 100 parallele Anfragen, Ø 8s, 15% Fehler
• Nachher: 100 parallele Anfragen, Ø 3s, <1% Fehler

Fazit

Von Gateway über Channel bis LLM – OpenClaw-Dreischicht-Architektur ist klar strukturiert. Jede Schicht hat eine Aufgabe, Erweiterung wird planbar.

Mit diesem Verständnis: neue Plattform = Channel-Adapter, neues Modell = Provider-Interface, Performance = gezielt auf der richtigen Schicht optimieren.

Für tiefe Anpassung: Repo klonen, Code entlang dieses Artikels lesen – Session-Management im Gateway, Routing in Channels, Provider-Registrierung im LLM-Layer sind das Herzstück.

Danach konfigurieren Sie nicht mehr blind, sondern beherrschen das System für Erweiterung und Optimierung.

Als Nächstes: einfachen Custom Channel (z. B. WeCom, Lark) bauen – praktisch vertieft sich das Verständnis. Die OpenClaw-Community auf GitHub Issues ist aktiv bei Fragen.

Weiterlesen

• OpenClaw-Konfiguration im Detail: Vollständiger openclaw.json-Leitfaden
• OpenClaw Multi-Plattform: 13 Channels zentral verwalten
• OpenClaw 2026 Installationsleitfaden: Deployment von null