OpenClaw MCP Server einrichten: Verbindung in Minuten

OpenClaw als MCP server

Das ist der Pfad für openclaw mcp serve.

Wann du `serve` verwenden solltest

Nutze openclaw mcp serve, wenn:

Codex, Claude Code oder ein anderer MCP client direkt mit OpenClaw-gestützten Channel-Konversationen kommunizieren soll
du bereits ein lokales oder entferntes OpenClaw Gateway mit gerouteten Sessions hast
du einen einzigen MCP server möchtest, der über die Channel-Backends von OpenClaw hinweg funktioniert, anstatt separate Bridges pro Channel zu betreiben

Nutze stattdessen openclaw acp, wenn OpenClaw die Coding-Runtime selbst hosten und die Agent-Session innerhalb von OpenClaw behalten soll.

Wie es funktioniert

openclaw mcp serve startet einen stdio MCP server. Der MCP client kontrolliert diesen Prozess. Während der Client die stdio-Session offen hält, verbindet sich die Bridge über WebSocket mit einem lokalen oder entfernten OpenClaw Gateway und stellt geroutete Channel-Konversationen über MCP bereit.

Lifecycle:

Der MCP client startet openclaw mcp serve
Die Bridge verbindet sich mit dem Gateway
Geroutete Sessions werden zu MCP-Konversationen und Transcript/History-Tools
Live-Events werden im Speicher in eine Warteschlange gestellt, solange die Bridge verbunden ist
Wenn der Claude-Channel-Modus aktiviert ist, kann dieselbe Session auch Claude-spezifische Push-Benachrichtigungen empfangen

Wichtiges Verhalten:

Die Warteschlange für Live-Events startet, sobald die Bridge die Verbindung herstellt
Ältere Transcript-Historien werden mit messages_read gelesen
Claude Push-Benachrichtigungen existieren nur, solange die MCP-Session aktiv ist
Wenn der Client die Verbindung trennt, beendet sich die Bridge und die Warteschlange wird gelöscht

Einen Client-Modus wählen

Nutze dieselbe Bridge auf zwei verschiedene Arten:

Generische MCP clients: Nur Standard-MCP-Tools. Nutze conversations_list, messages_read, events_poll, events_wait, messages_send und die Approval-Tools.
Claude Code: Standard-MCP-Tools plus der Claude-spezifische Channel-Adapter. Aktiviere --claude-channel-mode on oder nutze den Standardwert auto.

Aktuell verhält sich auto genau wie on. Es gibt noch keine Erkennung der Client-Capabilities.

Was `serve` bereitstellt

Die Bridge nutzt vorhandene Gateway Session Route Metadaten, um Channel-basierte Konversationen anzuzeigen. Eine Konversation taucht auf, wenn OpenClaw bereits einen Session State mit einer bekannten Route hat, wie zum Beispiel:

channel
Empfänger- oder Ziel-Metadaten
optionale accountId
optionale threadId

Das bietet MCP Clients einen zentralen Ort, um:

aktuelle geroutete Konversationen aufzulisten
den aktuellen Verlauf der Transcripts zu lesen
auf neue Inbound Events zu warten
eine Antwort über dieselbe Route zurückzusenden
Genehmigungsanfragen zu sehen, die während der Verbindung der Bridge eingehen

Nutzung

# Local Gateway
openclaw mcp serve

# Remote Gateway
openclaw mcp serve --url wss://gateway-host:18789 --token-file ~/.openclaw/gateway.token

# Remote Gateway with password auth
openclaw mcp serve --url wss://gateway-host:18789 --password-file ~/.openclaw/gateway.password

# Enable verbose bridge logs
openclaw mcp serve --verbose

# Disable Claude-specific push notifications
openclaw mcp serve --claude-channel-mode off

Bridge Tools

Die aktuelle Bridge stellt diese MCP Tools bereit:

conversations_list
conversation_get
messages_read
attachments_fetch
events_poll
events_wait
messages_send
permissions_list_open
permissions_respond

`conversations_list`

Listet aktuelle Session-basierte Konversationen auf, die bereits Route Metadaten im Gateway Session State haben.

Nützliche Filter:

limit
search
channel
includeDerivedTitles
includeLastMessage

`conversation_get`

Gibt eine Konversation anhand des session_key zurück.

`messages_read`

Liest aktuelle Transcript-Nachrichten für eine Session-basierte Konversation.

`attachments_fetch`

Extrahiert nicht-textbasierte Inhaltsblöcke aus einer Transcript-Nachricht. Das ist eine Metadaten-Ansicht des Transcript-Inhalts, kein eigenständiger Speicher für Anhänge.

`events_poll`

Liest wartende Live-Events ab einem numerischen Cursor.

`events_wait`

Nutzt Long-Polling, bis das nächste passende Event eintrifft oder ein Timeout abläuft.

Verwende dies, wenn ein generischer MCP Client eine Zustellung in Echtzeit benötigt, ohne ein Claude-spezifisches Push-Protokoll zu nutzen.

`messages_send`

Sendet Text über dieselbe Route zurück, die bereits in der Session aufgezeichnet wurde.

Aktuelles Verhalten:

erfordert eine beste

Claude-Channel-Benachrichtigungen

Die Bridge kann auch Claude-spezifische Channel-Benachrichtigungen bereitstellen. Das ist das OpenClaw-Pendant zu einem Claude Code Channel-Adapter: Standard MCP-Tools bleiben verfügbar, aber eingehende Live-Nachrichten können auch als Claude-spezifische MCP-Benachrichtigungen ankommen.

Flags:

--claude-channel-mode off: Nur Standard MCP-Tools
--claude-channel-mode on: Claude-Channel-Benachrichtigungen aktivieren
--claude-channel-mode auto: Aktueller Standard; gleiches Bridge-Verhalten wie on

Wenn der Claude-Channel-Modus aktiviert ist, kündigt der Server experimentelle Claude-Funktionen an und kann Folgendes senden:

notifications/claude/channel
notifications/claude/channel/permission

Aktuelles Bridge-Verhalten:

Eingehende user Transcript-Nachrichten werden als notifications/claude/channel weitergeleitet
Über MCP empfangene Claude-Berechtigungsanfragen werden im Arbeitsspeicher verfolgt
Wenn die verknüpfte Konversation später yes abcde oder no abcde sendet, wandelt die Bridge dies in notifications/claude/channel/permission um
Diese Benachrichtigungen sind nur für Live-Sessions verfügbar; wenn die Verbindung zum MCP-Client abbricht, gibt es kein Push-Ziel

Das ist absichtlich client-spezifisch. Generische MCP-Clients sollten die Standard-Polling-Tools nutzen.

MCP-Client-Konfiguration

Beispiel für eine stdio-Client-Konfiguration:

{
  "mcpServers": {
    "openclaw": {
      "command": "openclaw",
      "args": [
        "mcp",
        "serve",
        "--url",
        "wss://gateway-host:18789",
        "--token-file",
        "/path/to/gateway.token"
      ]
    }
  }
}

Für die meisten generischen MCP-Clients solltest du mit der Standard-Tool-Oberfläche starten und den Claude-Modus ignorieren. Aktiviere den Claude-Modus nur für Clients, die die Claude-spezifischen Benachrichtigungsmethoden tatsächlich verstehen.

Optionen

openclaw mcp serve unterstützt diese Optionen:

--url <url>: Gateway WebSocket URL
--token <token>: Gateway-Token
--token-file <path>: Token aus einer Datei lesen
--password <password>: Gateway-Passwort
--password-file <path>: Passwort aus einer Datei lesen
--claude-channel-mode <auto|on|off>: Claude-Benachrichtigungsmodus
-v, --verbose: Ausführliche Logs auf stderr

Ich empfehle dir, --token-file oder --password-file zu verwenden, anstatt Secrets direkt als Klartext in der Befehlszeile zu übergeben.

Sicherheit und Vertrauensgrenzen

Die Bridge erfindet kein eigenes Routing. Sie macht lediglich Konversationen verfügbar, die das Gateway bereits zuordnen kann.

Das bedeutet für dich:

Sender-Allowlists, Pairing und das Vertrauen auf Channel-Ebene hängen weiterhin von deiner zugrunde liegenden OpenClaw-Channel-Konfiguration ab.
messages_send kann nur über eine bereits existierende, gespeicherte Route antworten.
Der Freigabestatus (approval state) bleibt nur live im Arbeitsspeicher für die Dauer der aktuellen Bridge-Session erhalten.
Für die Bridge-Authentifizierung solltest du dieselben Gateway-Token oder Passwort-Kontrollen nutzen, denen du auch bei jedem anderen Remote-Gateway-Client vertraust.

Falls eine Konversation in conversations_list fehlt, liegt das meistens nicht an deiner MCP-Konfiguration. Die Ursache sind dann eher fehlende oder unvollständige Route-Metadaten in der zugrunde liegenden Gateway-Session.

Testen

OpenClaw liefert einen deterministischen Docker-Smoke-Test für diese Bridge mit:

pnpm test:docker:mcp-channels

Dieser Test:

startet einen Gateway-Container mit Seed-Daten
startet einen zweiten Container, der openclaw mcp serve ausführt
überprüft die Conversation Discovery, das Lesen von Transcripts, Attachment-Metadaten, das Verhalten der Live-Event-Queue und das Routing für ausgehende Nachrichten
validiert Claude-spezifische Channel- und Permission-Benachrichtigungen über die echte stdio MCP-Bridge

Das ist der schnellste Weg, um zu beweisen, dass die Bridge funktioniert, ohne einen echten Telegram-, Discord- oder iMessage-Account in den Testlauf einbinden zu müssen.

Weitere Informationen zum Testen findest du unter Testing.

Fehlerbehebung

Keine Conversations gefunden

Das bedeutet meistens, dass die Gateway-Session noch nicht routbar ist. Prüfe, ob die zugrunde liegende Session Metadaten für Channel/Provider, Empfänger und optional Account/Thread gespeichert hat.

`events_poll` oder `events_wait` zeigt keine alten Nachrichten

Das ist so gewollt. Die Live-Queue startet erst, wenn die Bridge verbunden ist. Nutze messages_read, um den bisherigen Verlauf der Transcripts zu laden.

Claude-Benachrichtigungen erscheinen nicht

Prüfe diese Punkte:

Der Client hat die stdio MCP-Session offen gehalten
--claude-channel-mode steht auf on oder auto
Der Client unterstützt die Claude-spezifischen Benachrichtigungsmethoden
Die eingehende Nachricht kam an, nachdem die Bridge verbunden wurde

Freigaben (Approvals) fehlen

permissions_list_open zeigt nur Anfragen, die beobachtet wurden, während die Bridge verbunden war. Es handelt sich nicht um eine API für eine dauerhafte Historie von Freigaben.

AI Setup Assistant

OpenClaw als MCP-Client-Registry

Hier findest du die Pfade für openclaw mcp list, show, set und unset.

Diese Befehle geben OpenClaw nicht über MCP frei. Sie verwalten Definitionen für MCP-Server, die OpenClaw gehören, unter mcp.servers in der OpenClaw-Konfiguration.

Diese gespeicherten Definitionen sind für Runtimes gedacht, die OpenClaw später startet oder konfiguriert, wie zum Beispiel eingebettete Pi und andere Runtime-Adapter. OpenClaw speichert die Definitionen zentral, damit diese Runtimes keine eigenen, doppelten Listen von MCP-Servern führen müssen.

Wichtiges Verhalten:

Diese Befehle lesen oder schreiben nur die OpenClaw-Konfiguration
Sie verbinden sich nicht mit dem Ziel-MCP-Server
Sie validieren nicht, ob der Befehl, die URL oder der Remote-Transport gerade erreichbar ist
Runtime-Adapter entscheiden zum Zeitpunkt der Ausführung, welche Transport-Formen sie tatsächlich unterstützen

Gespeicherte MCP-Server-Definitionen

OpenClaw speichert außerdem eine leichtgewichtige MCP-Server-Registry in der Konfiguration für Oberflächen, die von OpenClaw verwaltete MCP-Definitionen benötigen.

Befehle:

openclaw mcp list
openclaw mcp show [name]
openclaw mcp set <name> <json>
openclaw mcp unset <name>

Beispiele:

openclaw mcp list
openclaw mcp show context7 --json
openclaw mcp set context7 '{"command":"uvx","args":["context7-mcp"]}'
openclaw mcp set docs '{"url":"https://mcp.example.com"}'
openclaw mcp unset context7

Beispiel für die Konfigurationsstruktur:

{
  "mcp": {
    "servers": {
      "context7": {
        "command": "uvx",
        "args": ["context7-mcp"]
      },
      "docs": {
        "url": "https://mcp.example.com"
      }
    }
  }
}

Stdio-Transport

Startet einen lokalen Child-Prozess und kommuniziert über stdin/stdout.

Feld	Beschreibung
`command`	Auszuführende Datei (erforderlich)
`args`	Array von Befehlszeilenargumenten
`env`	Zusätzliche Umgebungsvariablen
`cwd` / `workingDirectory`	Arbeitsverzeichnis für den Prozess

SSE / HTTP-Transport

Verbindet sich mit einem entfernten MCP-Server über HTTP Server-Sent Events.

Feld	Beschreibung
`url`	HTTP- oder HTTPS-URL des Remote-Servers (erforderlich)
`headers`	Optionale Key-Value-Map für HTTP-Header (zum Beispiel Auth-Token)
`connectionTimeout`	Verbindungs-Timeout pro Server in ms (optional)

Beispiel:

{
  "mcp": {
    "servers": {
      "remote-tools": {
        "url": "https://mcp.example.com",
        "headers": {
          "Authorization": "Bearer <token>"
        }
      }
    }
  }
}

Sensible Werte in der url (Userinfo) und in den headers werden in Logs und in der Statusausgabe geschwärzt.

Streamable HTTP-Transport

streamable-http ist eine zusätzliche Transport-Option neben sse und stdio. Sie nutzt HTTP-Streaming für die bidirektionale Kommunikation mit entfernten MCP-Servern.

Feld	Beschreibung
`url`	HTTP- oder HTTPS-URL des Remote-Servers (erforderlich)
`transport`	Auf `"streamable-http"` setzen, um diesen Transport zu wählen
`headers`	Optionale Key-Value-Map für HTTP-Header (zum Beispiel Auth-Token)
`connectionTimeout`	Verbindungs-Timeout pro Server in ms (optional)

Beispiel:

{
  "mcp": {
    "servers": {
      "streaming-tools": {
        "url": "https://mcp.example.com/stream",
        "transport": "streamable-http",
        "connectionTimeout": 10000,
        "headers": {
          "Authorization": "Bearer <token>"
        }
      }
    }
  }
}

Diese Befehle verwalten nur die gespeicherte Konfiguration. Sie starten nicht die Channel-Bridge, öffnen keine aktive MCP-Client-Session und prüfen nicht, ob der Zielserver erreichbar ist.

Aktuelle Einschränkungen

Diese Seite dokumentiert die Bridge im aktuellen Zustand.

Aktuelle Einschränkungen:

Die Discovery von Konversationen hängt von existierenden Gateway-Session-Route-Metadaten ab
Kein generisches Push-Protokoll außer dem Claude-spezifischen Adapter
Noch keine Tools zum Bearbeiten von Nachrichten oder für Reaktionen
Der HTTP/SSE/streamable-http-Transport verbindet sich mit einem einzelnen Remote-Server; noch kein gemultiplextes Upstream
permissions_list_open enthält nur Freigaben, die beobachtet wurden, während die Bridge verbunden war