MCP

openclaw mcp hat zwei Aufgaben:

• OpenClaw mit openclaw mcp serve als MCP-Server ausführen
• von OpenClaw verwaltete Definitionen ausgehender MCP-Server mit list, show, set und unset verwalten

Mit anderen Worten:

• serve bedeutet, dass OpenClaw als MCP-Server agiert
• list / show / set / unset bedeutet, dass OpenClaw als clientseitige MCP-Registry für andere MCP-Server agiert, die seine Runtimes später nutzen können

Verwenden Sie openclaw acp, wenn OpenClaw selbst eine Coding-Harness-Sitzung hosten und diese Runtime über ACP routen soll.

# OpenClaw als MCP-Server

Dies ist der Pfad openclaw mcp serve.

# Wann Sie serve verwenden sollten

Verwenden Sie openclaw mcp serve, wenn:

• Codex, Claude Code oder ein anderer MCP-Client direkt mit kanalbezogenen, von OpenClaw gestützten Konversationen sprechen soll
• Sie bereits ein lokales oder entferntes OpenClaw Gateway mit gerouteten Sitzungen haben
• Sie einen MCP-Server möchten, der über die Kanal-Backends von OpenClaw hinweg funktioniert, statt separate Bridges pro Kanal auszuführen

Verwenden Sie stattdessen openclaw acp, wenn OpenClaw die Coding-Runtime selbst hosten und die Agent-Sitzung innerhalb von OpenClaw halten soll.

# Funktionsweise

openclaw mcp serve startet einen stdio-MCP-Server. Der MCP-Client besitzt diesen Prozess. Solange der Client die stdio-Sitzung offen hält, verbindet sich die Bridge per WebSocket mit einem lokalen oder entfernten OpenClaw Gateway und stellt geroutete Kanalkonversationen über MCP bereit.

# Clientmodus auswählen

Verwenden Sie dieselbe Bridge auf zwei verschiedene Arten:

# Was serve bereitstellt

Die Bridge verwendet vorhandene Routemetadaten der Gateway-Sitzung, um kanalgestützte Konversationen bereitzustellen. Eine Konversation erscheint, wenn OpenClaw bereits Sitzungszustand mit einer bekannten Route hat, zum Beispiel:

• channel
• Empfänger- oder Zielmetadaten
• optionales accountId
• optionales threadId

Damit erhalten MCP-Clients eine zentrale Stelle, um:

• kürzlich geroutete Konversationen aufzulisten
• aktuelle Transkriptverläufe zu lesen
• auf neue eingehende Ereignisse zu warten
• eine Antwort über dieselbe Route zurückzusenden
• Genehmigungsanfragen zu sehen, die eintreffen, während die Bridge verbunden ist

# Verwendung

openclaw mcp serve

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

openclaw mcp serve --url wss://gateway-host:18789 --password-file ~/.openclaw/gateway.password

openclaw mcp serve --verbose
openclaw mcp serve --claude-channel-mode off

# Bridge-Tools

Die aktuelle Bridge stellt diese MCP-Tools bereit:

# Ereignismodell

Die Bridge hält eine In-Memory-Ereigniswarteschlange, während sie verbunden ist.

Aktuelle Ereignistypen:

• message
• exec_approval_requested
• exec_approval_resolved
• plugin_approval_requested
• plugin_approval_resolved
• claude_permission_request

# Claude-Kanalbenachrichtigungen

Die Bridge kann auch Claude-spezifische Kanalbenachrichtigungen bereitstellen. Dies ist das OpenClaw-Äquivalent eines Claude-Code-Kanaladapters: Standard-MCP-Tools bleiben verfügbar, aber live eingehende Nachrichten können auch als Claude-spezifische MCP-Benachrichtigungen eintreffen.

Wenn der Claude-Kanalmodus aktiviert ist, kündigt der Server experimentelle Claude-Fähigkeiten an und kann Folgendes ausgeben:

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

Aktuelles Bridge-Verhalten:

• eingehende user-Transkriptnachrichten werden als notifications/claude/channel weitergeleitet
• über MCP empfangene Claude-Berechtigungsanfragen werden im Arbeitsspeicher nachverfolgt
• 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 gelten nur für die Live-Sitzung; wenn der MCP-Client die Verbindung trennt, gibt es kein Push-Ziel

Dies ist absichtlich client-spezifisch. Generische MCP-Clients sollten sich auf die Standard-Polling-Tools verlassen.

# MCP-Clientkonfiguration

Beispiel für eine stdio-Clientkonfiguration:

{
  "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 beginnen Sie mit der Standard-Tool-Oberfläche und ignorieren den Claude-Modus. Aktivieren Sie den Claude-Modus nur für Clients, die die Claude-spezifischen Benachrichtigungsmethoden tatsächlich verstehen.

# Optionen

openclaw mcp serve unterstützt:

# Sicherheits- und Vertrauensgrenze

Die Bridge erfindet kein Routing. Sie stellt nur Konversationen bereit, die das Gateway bereits routen kann.

Das bedeutet:

• Absender-Allowlists, Pairing und Vertrauen auf Kanalebene gehören weiterhin zur zugrunde liegenden OpenClaw-Kanalkonfiguration
• messages_send kann nur über eine vorhandene gespeicherte Route antworten
• der Genehmigungszustand ist nur live/im Arbeitsspeicher für die aktuelle Bridge-Sitzung
• die Bridge-Authentifizierung sollte dieselben Gateway-Token- oder Passwortkontrollen verwenden, denen Sie bei jedem anderen entfernten Gateway-Client vertrauen würden

Wenn eine Konversation in conversations_list fehlt, liegt die übliche Ursache nicht in der MCP-Konfiguration. Es fehlen Routemetadaten in der zugrunde liegenden Gateway-Sitzung oder diese sind unvollständig.

# Tests

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

pnpm test:docker:mcp-channels

Dieser Smoke-Test:

• startet einen mit Startdaten versehenen Gateway-Container
• startet einen zweiten Container, der openclaw mcp serve startet
• verifiziert Konversationserkennung, Transkriptlesevorgänge, Attachment-Metadaten-Lesevorgänge, Verhalten der Live-Ereigniswarteschlange und ausgehendes Senderouting
• validiert Claude-artige Kanal- und Berechtigungsbenachrichtigungen über die echte stdio-MCP-Bridge

Dies ist der schnellste Weg, nachzuweisen, dass die Bridge funktioniert, ohne ein echtes Telegram-, Discord- oder iMessage-Konto in den Testlauf einzubinden.

Weiteren Testkontext finden Sie unter Testen.

# Fehlerbehebung

# OpenClaw als MCP-Clientregistry

Dies ist der Pfad für openclaw mcp list, show, set und unset.

Diese Befehle stellen OpenClaw nicht über MCP bereit. Sie verwalten OpenClaw-eigene MCP-Serverdefinitionen unter mcp.servers in der OpenClaw-Konfiguration.

Diese gespeicherten Definitionen sind für Laufzeiten gedacht, die OpenClaw später startet oder konfiguriert, wie eingebettetes Pi und andere Laufzeitadapter. OpenClaw speichert die Definitionen zentral, damit diese Laufzeiten keine eigenen doppelten MCP-Serverlisten pflegen müssen.

Laufzeitadapter können diese gemeinsame Registry in die Form normalisieren, die ihr nachgelagerter Client erwartet. Zum Beispiel nutzt eingebettetes Pi die OpenClaw-transport-Werte direkt, während Claude Code und Gemini CLI-native type-Werte wie http, sse oder stdio erhalten.

# Gespeicherte MCP-Serverdefinitionen

OpenClaw speichert außerdem eine schlanke MCP-Server-Registry in der Konfiguration für Oberflächen, die von OpenClaw verwaltete MCP-Definitionen verwenden möchten.

Befehle:

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

Hinweise:

• list sortiert Servernamen.
• show ohne Namen gibt das vollständig konfigurierte MCP-Serverobjekt aus.
• set erwartet einen JSON-Objektwert auf der Befehlszeile.
• Verwenden Sie transport: "streamable-http" für Streamable-HTTP-MCP-Server. openclaw mcp set normalisiert außerdem CLI-native type: "http"-Werte aus Kompatibilitätsgründen in dieselbe kanonische Konfigurationsform.
• unset schlägt fehl, wenn der benannte Server nicht existiert.

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","transport":"streamable-http"}'
openclaw mcp unset context7

Beispielhafte Konfigurationsform:

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

# Stdio-Transport

Startet einen lokalen Kindprozess und kommuniziert über stdin/stdout.

# SSE-/HTTP-Transport

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

Beispiel:

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

Vertrauliche Werte in url (userinfo) und headers werden in Logs und Statusausgaben redigiert.

# Streamable-HTTP-Transport

streamable-http ist eine zusätzliche Transportoption neben sse und stdio. Sie verwendet HTTP-Streaming für bidirektionale Kommunikation mit Remote-MCP-Servern.

Die OpenClaw-Konfiguration verwendet transport: "streamable-http" als kanonische Schreibweise. CLI-native MCP-type: "http"-Werte werden akzeptiert, wenn sie über openclaw mcp set gespeichert werden, und in bestehenden Konfigurationen durch openclaw doctor --fix repariert, aber transport ist das, was eingebettetes Pi direkt nutzt.

Beispiel:

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

# Aktuelle Grenzen

Diese Seite dokumentiert die Bridge so, wie sie heute ausgeliefert wird.

Aktuelle Grenzen:

• Konversationserkennung hängt von vorhandenen Gateway-Sitzungsroutenmetadaten ab
• kein generisches Push-Protokoll über den Claude-spezifischen Adapter hinaus
• noch keine Tools zum Bearbeiten von Nachrichten oder zum Reagieren
• HTTP-/SSE-/streamable-http-Transport verbindet sich mit einem einzelnen Remote-Server; noch kein multiplexter Upstream
• permissions_list_open enthält nur Genehmigungen, die beobachtet wurden, während die Bridge verbunden ist

# Verwandt

• CLI-Referenz
• Plugins