MCP

openclaw mcp hat zwei Aufgaben:

• OpenClaw als MCP-Server mit openclaw mcp serve ausführen
• von OpenClaw verwaltete Definitionen ausgehender MCP-Server mit list, show, status, doctor, probe, add, set, configure, tools, login, logout, reload und unset verwalten

Anders gesagt:

• serve ist OpenClaw, das als MCP-Server agiert
• die anderen Unterbefehle sind OpenClaw, das als clientseitige MCP-Registry für MCP-Server agiert, die seine Laufzeiten später verwenden können

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

Den richtigen MCP-Pfad wählen

OpenClaw hat mehrere MCP-Oberflächen. Wählen Sie diejenige, die dazu passt, wer die Agent-Laufzeit besitzt und wer die Tools besitzt.

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 OpenClaw-gestützten Kanalunterhaltungen sprechen soll
• Sie bereits ein lokales oder entferntes OpenClaw Gateway mit weitergeleiteten 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-Laufzeit selbst hosten und die Agent-Sitzung innerhalb von OpenClaw behalten 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 über WebSocket mit einem lokalen oder entfernten OpenClaw Gateway und stellt weitergeleitete Kanalunterhaltungen über MCP bereit.

Einen Client-Modus wählen

Verwenden Sie dieselbe Bridge auf zwei verschiedene Arten:

Was serve bereitstellt

Die Bridge verwendet vorhandene Gateway-Sitzungsroutenmetadaten, um kanalgestützte Unterhaltungen bereitzustellen. Eine Unterhaltung erscheint, wenn OpenClaw bereits Sitzungsstatus mit einer bekannten Route hat, wie etwa:

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

Dadurch erhalten MCP-Clients einen Ort, um:

• zuletzt weitergeleitete Unterhaltungen aufzulisten
• aktuellen Transkriptverlauf 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 --verboseopenclaw mcp serve --claude-channel-mode off

Bridge-Tools

Die aktuelle Bridge stellt diese MCP-Tools bereit:

Ereignismodell

Die Bridge hält eine Ereigniswarteschlange im Speicher, solange 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 eingehende Live-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 Speicher verfolgt
• wenn der Befehlsinhaber in der verknüpften Unterhaltung später yes abcde oder no abcde sendet, wandelt die Bridge dies in notifications/claude/channel/permission um
• diese Benachrichtigungen gelten nur für Live-Sitzungen; wenn der MCP-Client die Verbindung trennt, gibt es kein Push-Ziel

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

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

Optionen

openclaw mcp serve unterstützt:

Sicherheits- und Vertrauensgrenze

Die Bridge erfindet kein Routing. Sie macht nur Unterhaltungen verfügbar, die Gateway bereits routen kann.

Das bedeutet:

• Sender-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 Genehmigungsstatus ist nur für die aktuelle Bridge-Sitzung live/im Speicher
• Bridge-Authentifizierung sollte dieselben Gateway-Token- oder Passwortkontrollen verwenden, denen Sie auch für jeden anderen Remote-Gateway-Client vertrauen würden

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

Testen

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

pnpm test:docker:mcp-channels

Dieser Smoke-Test:

• startet einen Gateway-Container mit Seed-Daten
• startet einen zweiten Container, der openclaw mcp serve erzeugt
• verifiziert Unterhaltungserkennung, Lesen von Transkripten, Lesen von Anhangsmetadaten, Verhalten der Live-Event-Queue und Routing ausgehender Sendungen
• validiert Claude-artige Kanal- und Berechtigungsbenachrichtigungen über die echte stdio-MCP-Bridge

Dies ist der schnellste Weg, um 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-Client-Registry

Dies ist der Pfad für openclaw mcp list, show, status, doctor, probe, add, set, configure, tools, login, logout, reload und unset.

Diese Befehle stellen OpenClaw nicht über MCP bereit. Sie verwalten von OpenClaw verwaltete MCP-Serverdefinitionen unter mcp.servers in der OpenClaw-Konfiguration. Sie lesen keine mcporter-Server aus config/mcporter.json.

Diese gespeicherten Definitionen sind für Laufzeiten bestimmt, die OpenClaw später startet oder konfiguriert, etwa eingebettetes OpenClaw 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. Beispielsweise verwendet eingebettetes OpenClaw OpenClaw-transport-Werte direkt, während Claude Code und Gemini CLI-native type-Werte wie http, sse oder stdio erhalten.

Codex app-server berücksichtigt außerdem einen optionalen codex-Block auf jedem Server. Dies sind OpenClaw-Projektionsmetadaten nur für Codex app-server-Threads; sie ändern keine ACP-Sitzungen, generische Codex-Harness-Konfigurationen oder andere Laufzeitadapter. Verwenden Sie nicht leere codex.agents, um einen Server nur in bestimmte OpenClaw- Agent-IDs zu projizieren. Leere, blanke oder ungültige Agent-Listen werden von der Konfigurationsvalidierung abgelehnt und vom Laufzeit-Projektionspfad ausgelassen, statt global zu werden. Verwenden Sie codex.defaultToolsApprovalMode (auto, prompt oder approve), um Codexs natives default_tools_approval_mode für einen vertrauenswürdigen Server auszugeben. OpenClaw entfernt die codex-Metadaten, bevor es die native mcp_servers- Konfiguration an Codex übergibt.

Gespeicherte MCP-Serverdefinitionen

OpenClaw speichert außerdem eine leichtgewichtige 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 status [--verbose]
• openclaw mcp doctor [name] [--probe]
• openclaw mcp probe [name]
• openclaw mcp add <name> [flags]
• openclaw mcp set <name> <json>
• openclaw mcp configure <name> [flags]
• openclaw mcp tools <name> [--include csv] [--exclude csv] [--clear]
• openclaw mcp login <name> [--code code]
• openclaw mcp logout <name>
• openclaw mcp reload
• openclaw mcp unset <name>

Hinweise:

• list sortiert Servernamen.
• show ohne Namen gibt das vollständig konfigurierte MCP-Serverobjekt aus.
• status klassifiziert konfigurierte Transporte, ohne eine Verbindung herzustellen. --verbose enthält aufgelöste Details zu Start, Timeout, OAuth, Filter und parallelen Aufrufen.
• doctor führt statische Prüfungen ohne Verbindungsaufbau durch. Fügen Sie --probe hinzu, wenn der Befehl auch verifizieren soll, dass aktivierte Server eine Verbindung herstellen.
• probe verbindet sich und meldet Tool-Anzahlen, Unterstützung für Ressourcen/Prompts, Unterstützung für Listenänderungen und Diagnosen.
• add akzeptiert stdio-Flags wie --command, --arg, --env und --cwd oder HTTP-Flags wie --url, --transport, --header, --auth oauth, TLS, Timeout und Tool-Auswahl-Flags.
• set erwartet einen JSON-Objektwert auf der Befehlszeile.
• configure aktualisiert Aktivierung, Tool-Filter, Timeouts, OAuth, TLS und Hinweise zu parallelen Tool-Aufrufen, ohne die gesamte Serverdefinition zu ersetzen.
• tools aktualisiert Tool-Filter pro Server. Include-/Exclude-Einträge sind MCP-Tool-Namen und einfache *-Globs.
• login führt den OAuth-Fluss für HTTP-Server aus, die mit auth: "oauth" konfiguriert sind. Der erste Lauf gibt eine Autorisierungs-URL aus; führen Sie ihn nach der Genehmigung erneut mit --code aus.
• logout löscht gespeicherte OAuth-Zugangsdaten für den benannten Server, ohne die gespeicherte Serverdefinition zu entfernen.
• reload verwirft zwischengespeicherte MCP-Laufzeiten im Prozess. Gateway- oder Agent-Prozesse in einem anderen Prozess benötigen weiterhin ihren eigenen Reload- oder Neustartpfad.
• Verwenden Sie transport: "streamable-http" für Streamable-HTTP-MCP-Server. openclaw mcp set normalisiert außerdem CLI-native type: "http" zur Kompatibilität in dieselbe kanonische Konfigurationsform.
• unset schlägt fehl, wenn der benannte Server nicht existiert.

Beispiele:

openclaw mcp listopenclaw mcp show context7 --jsonopenclaw mcp status --verboseopenclaw mcp doctor --probeopenclaw mcp probe context7 --jsonopenclaw mcp add memory --command npx --arg -y --arg @modelcontextprotocol/server-memoryopenclaw mcp set context7 '{"command":"uvx","args":["context7-mcp"]}'openclaw mcp tools context7 --include 'resolve-library-id,get-library-docs'openclaw mcp set docs '{"url":"https://mcp.example.com","transport":"streamable-http"}'openclaw mcp configure docs --timeout 20 --connect-timeout 5 --include 'search,read_*'openclaw mcp configure docs --auth oauth --oauth-scope 'docs.read'openclaw mcp login docsopenclaw mcp logout docsopenclaw mcp unset context7

Gängige Serverrezepte

Diese Beispiele speichern nur Serverdefinitionen. Führen Sie anschließend openclaw mcp doctor --probe aus, um nachzuweisen, dass der Server startet und Tools bereitstellt.

openclaw mcp add files \  --command npx \  --arg -y \  --arg @modelcontextprotocol/server-filesystem \  --arg "$HOME/Documents" \  --include 'read_file,list_directory,search_files'openclaw mcp doctor files --probe

openclaw mcp add memory \  --command npx \  --arg -y \  --arg @modelcontextprotocol/server-memoryopenclaw mcp probe memory --json

openclaw mcp add local-tools \  --command node \  --arg ./dist/mcp-server.js \  --cwd /srv/openclaw-tools \  --env API_BASE=https://internal.exampleopenclaw mcp status --verbose

openclaw mcp add docs \  --url https://mcp.example.com/mcp \  --transport streamable-http \  --auth oauth \  --oauth-scope docs.read \  --timeout 20 \  --connect-timeout 5 \  --include 'search,read_*'openclaw mcp doctor docs --probe

openclaw mcp set cua-driver '{"command":"cua-driver","args":["mcp"]}'openclaw mcp tools cua-driver --include 'list_apps,observe,click,type'openclaw mcp doctor cua-driver --probe

JSON-Ausgabeformen

Verwenden Sie --json für Skripte und Dashboards. Feldmengen können im Laufe der Zeit wachsen, daher sollten Verbraucher unbekannte Schlüssel ignorieren.

{  "path": "/home/user/.openclaw/openclaw.json",  "servers": [    {      "name": "docs",      "configured": true,      "enabled": true,      "ok": true,      "transport": "streamable-http",      "launch": "streamable-http https://mcp.example.com/mcp",      "auth": "oauth",      "authStatus": {        "hasTokens": true,        "hasClientInformation": true,        "hasCodeVerifier": false,        "hasDiscoveryState": true,        "hasLastAuthorizationUrl": false      },      "requestTimeoutMs": 20000,      "connectionTimeoutMs": 5000,      "toolFilter": {        "include": ["search", "read_*"],        "exclude": []      },      "supportsParallelToolCalls": true    }  ]}

{  "ok": false,  "path": "/home/user/.openclaw/openclaw.json",  "servers": [    {      "name": "docs",      "ok": false,      "issues": [        {          "level": "error",          "message": "OAuth credentials are not authorized; run openclaw mcp login docs"        }      ]    }  ]}

{  "path": "/home/user/.openclaw/openclaw.json",  "generatedAt": "2026-05-31T09:00:00.000Z",  "servers": {    "docs": {      "launch": "streamable-http https://mcp.example.com/mcp",      "tools": 2,      "resources": true,      "prompts": false,      "listChanged": {        "tools": true,        "resources": false,        "prompts": false      }    }  },  "tools": ["docs__read_page", "docs__search"],  "diagnostics": []}

Beispiel-Konfigurationsform:

{  "mcp": {    "servers": {      "context7": {        "command": "uvx",        "args": ["context7-mcp"]      },      "docs": {        "url": "https://mcp.example.com",        "transport": "streamable-http",        "timeout": 20,        "connectTimeout": 5,        "supportsParallelToolCalls": true,        "auth": "oauth",        "oauth": {          "scope": "docs.read"        },        "sslVerify": true,        "clientCert": "/path/to/client.crt",        "clientKey": "/path/to/client.key",        "toolFilter": {          "include": ["search_*"],          "exclude": ["admin_*"]        }      }    }  }}

Stdio-Transport

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

SSE-/HTTP-Transport

Stellt über HTTP Server-Sent Events eine Verbindung zu einem Remote-MCP-Server her.

Beispiel:

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

Vertrauliche Werte in url (userinfo) und headers werden in Logs und Statusausgaben geschwärzt. openclaw mcp doctor warnt, wenn vertraulich wirkende headers- oder env-Einträge wörtliche Werte enthalten, damit Operatoren diese Werte aus committeter Konfiguration entfernen können.

OAuth-Workflow

OAuth ist für HTTP-MCP-Server vorgesehen, die den MCP-OAuth-Flow ankündigen. Statische Authorization-Header werden für einen Server ignoriert, solange auth: "oauth" aktiviert ist.

openclaw mcp set docs '{"url":"https://mcp.example.com/mcp","transport":"streamable-http","auth":"oauth","oauth":{"scope":"docs.read"}}'

openclaw mcp login docs

openclaw mcp login docs --code abc123

openclaw mcp status --verboseopenclaw mcp doctor docs --probe

openclaw mcp logout docs

Wenn der Provider Tokens rotiert oder der Autorisierungszustand hängen bleibt, führen Sie openclaw mcp logout <name> aus und wiederholen Sie dann login. logout kann Zugangsdaten für einen gespeicherten HTTP-Server löschen, selbst nachdem auth: "oauth" aus der Konfiguration entfernt wurde, solange Servername und URL den Eintrag im Zugangsdaten-Speicher weiterhin identifizieren.

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-Werte type: "http" werden akzeptiert, wenn sie über openclaw mcp set gespeichert werden, und in bestehender Konfiguration durch openclaw doctor --fix repariert, aber transport ist das, was eingebettetes OpenClaw direkt verarbeitet.

Beispiel:

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

Control UI

Die Browser-Control-UI enthält eine eigene MCP-Einstellungsseite unter /mcp. Sie zeigt die Anzahl konfigurierter Server, Zusammenfassungen zu aktiviert/OAuth/Filtern, Transportzeilen pro Server, Steuerelemente zum Aktivieren/Deaktivieren, gängige CLI-Befehle und einen bereichsbezogenen Editor für den Konfigurationsabschnitt mcp.

Verwenden Sie die Seite für Operator-Bearbeitungen und schnelle Inventarisierung. Verwenden Sie openclaw mcp doctor --probe oder openclaw mcp probe, wenn Sie einen Live-Server-Nachweis benötigen.

Operator-Workflow:

1. Öffnen Sie die Control UI und wählen Sie MCP.
2. Prüfen Sie die Übersichtskarten für Gesamtzahl, aktivierte, OAuth- und gefilterte Server.
3. Nutzen Sie jede Serverzeile für Hinweise zu Transport, Auth, Filter, Timeout und Befehlen.
4. Schalten Sie die Aktivierung um, wenn Sie eine Definition behalten, sie aber von der Laufzeiterkennung ausschließen möchten.
5. Bearbeiten Sie den bereichsspezifischen mcp-Konfigurationsabschnitt für strukturelle Änderungen wie neue Server, Header, TLS, OAuth-Metadaten oder Tool-Filter.
6. Wählen Sie Speichern, um nur die Konfiguration zu speichern, oder Speichern & Veröffentlichen, um sie über den Gateway-Konfigurationspfad anzuwenden.
7. Führen Sie openclaw mcp doctor --probe aus, wenn Sie Live-Nachweise benötigen, dass der bearbeitete Server startet und Tools auflistet.

Hinweise:

• Befehlssnippets setzen Servernamen in Anführungszeichen, damit ungewöhnliche Namen in einer Shell kopierbar bleiben
• angezeigte URL-ähnliche Werte werden vor dem Rendern redigiert, wenn sie eingebettete Anmeldedaten enthalten
• die Seite startet MCP-Transporte nicht selbst
• aktive Laufzeiten benötigen möglicherweise openclaw mcp reload, eine Gateway-Konfigurationsveröffentlichung oder einen Prozessneustart, je nachdem, welcher Prozess die MCP-Clients besitzt

Aktuelle Grenzen

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

Aktuelle Grenzen:

• die Konversationserkennung hängt von vorhandenen Gateway-Sitzungsrouten-Metadaten 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