MCP

openclaw mcp a deux rôles :

• exécuter OpenClaw comme serveur MCP avec openclaw mcp serve
• gérer les définitions de serveurs MCP sortants gérés par OpenClaw avec list, show, status, doctor, probe, add, set, configure, tools, login, logout, reload et unset

Autrement dit :

• serve correspond à OpenClaw agissant comme serveur MCP
• les autres sous-commandes correspondent à OpenClaw agissant comme registre côté client MCP pour les serveurs MCP que ses runtimes pourront consommer ultérieurement

Utilisez openclaw acp lorsqu’OpenClaw doit héberger lui-même une session de harnais de codage et acheminer ce runtime via ACP.

Choisir le bon chemin MCP

OpenClaw dispose de plusieurs surfaces MCP. Choisissez celle qui correspond à l’entité qui possède le runtime d’agent et à celle qui possède les outils.

OpenClaw comme serveur MCP

C’est le chemin openclaw mcp serve.

Quand utiliser serve

Utilisez openclaw mcp serve lorsque :

• Codex, Claude Code ou un autre client MCP doit communiquer directement avec des conversations de canaux adossées à OpenClaw
• vous disposez déjà d’un Gateway OpenClaw local ou distant avec des sessions acheminées
• vous voulez un serveur MCP unique qui fonctionne avec les backends de canaux d’OpenClaw au lieu d’exécuter des ponts séparés par canal

Utilisez plutôt openclaw acp lorsqu’OpenClaw doit héberger lui-même le runtime de codage et conserver la session d’agent dans OpenClaw.

Fonctionnement

openclaw mcp serve démarre un serveur MCP stdio. Le client MCP possède ce processus. Tant que le client garde la session stdio ouverte, le pont se connecte à un Gateway OpenClaw local ou distant via WebSocket et expose les conversations de canaux acheminées via MCP.

Choisir un mode client

Utilisez le même pont de deux façons différentes :

Ce que serve expose

Le pont utilise les métadonnées de routes de sessions Gateway existantes pour exposer les conversations adossées à des canaux. Une conversation apparaît lorsqu’OpenClaw possède déjà un état de session avec une route connue, comme :

• channel
• des métadonnées de destinataire ou de destination
• accountId facultatif
• threadId facultatif

Cela donne aux clients MCP un endroit unique pour :

• lister les conversations acheminées récentes
• lire l’historique de transcription récent
• attendre de nouveaux événements entrants
• envoyer une réponse via la même route
• voir les demandes d’approbation qui arrivent pendant que le pont est connecté

Utilisation

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

Outils du pont

Le pont actuel expose ces outils MCP :

Modèle d’événements

Le pont conserve une file d’événements en mémoire tant qu’il est connecté.

Types d’événements actuels :

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

Notifications de canal Claude

Le pont peut également exposer des notifications de canal propres à Claude. C’est l’équivalent OpenClaw d’un adaptateur de canal Claude Code : les outils MCP standard restent disponibles, mais les messages entrants en direct peuvent également arriver comme notifications MCP propres à Claude.

Lorsque le mode canal Claude est activé, le serveur annonce les capacités expérimentales Claude et peut émettre :

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

Comportement actuel du pont :

• les messages de transcription entrants user sont transférés comme notifications/claude/channel
• les demandes d’autorisation Claude reçues via MCP sont suivies en mémoire
• si le propriétaire de la commande dans la conversation liée envoie ensuite yes abcde ou no abcde, le pont convertit cela en notifications/claude/channel/permission
• ces notifications sont propres à la session en direct ; si le client MCP se déconnecte, il n’y a pas de cible push

C’est intentionnellement propre au client. Les clients MCP génériques doivent s’appuyer sur les outils de polling standard.

Configuration du client MCP

Exemple de configuration de client stdio :

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

Pour la plupart des clients MCP génériques, commencez avec la surface d’outils standard et ignorez le mode Claude. Activez le mode Claude uniquement pour les clients qui comprennent réellement les méthodes de notification propres à Claude.

Options

openclaw mcp serve prend en charge :

Sécurité et limite de confiance

Le pont n’invente pas de routage. Il expose uniquement les conversations que le Gateway sait déjà router.

Cela signifie que :

• les listes d’expéditeurs autorisés, l’appairage et la confiance au niveau du canal relèvent toujours de la configuration du canal OpenClaw sous-jacent
• messages_send peut uniquement répondre via une route stockée existante
• l’état d’approbation est actif/en mémoire uniquement pour la session actuelle du pont
• l’authentification du pont doit utiliser les mêmes contrôles de jeton ou de mot de passe du Gateway que ceux auxquels vous feriez confiance pour tout autre client Gateway distant

Si une conversation est absente de conversations_list, la cause habituelle n’est pas la configuration MCP. Il manque des métadonnées de route, ou elles sont incomplètes, dans la session Gateway sous-jacente.

Tests

OpenClaw fournit un test de fumée Docker déterministe pour ce pont :

pnpm test:docker:mcp-channels

Ce test de fumée :

• démarre un conteneur Gateway prérempli
• démarre un second conteneur qui lance openclaw mcp serve
• vérifie la découverte des conversations, la lecture des transcriptions, la lecture des métadonnées de pièces jointes, le comportement de la file d’événements en direct et le routage des envois sortants
• valide les notifications de canal et d’autorisation de style Claude via le vrai pont MCP stdio

C’est le moyen le plus rapide de prouver que le pont fonctionne sans connecter un vrai compte Telegram, Discord ou iMessage à l’exécution de test.

Pour un contexte de test plus large, consultez Tests.

Dépannage

OpenClaw comme registre client MCP

Il s’agit du chemin openclaw mcp list, show, status, doctor, probe, add, set, configure, tools, login, logout, reload et unset.

Ces commandes n’exposent pas OpenClaw via MCP. Elles gèrent les définitions de serveurs MCP gérées par OpenClaw sous mcp.servers dans la configuration OpenClaw. Elles ne lisent pas les serveurs mcporter depuis config/mcporter.json.

Ces définitions enregistrées sont destinées aux runtimes qu’OpenClaw lance ou configure ultérieurement, comme OpenClaw intégré et d’autres adaptateurs de runtime. OpenClaw stocke les définitions de façon centralisée afin que ces runtimes n’aient pas besoin de conserver leurs propres listes de serveurs MCP en double.

Les adaptateurs de runtime peuvent normaliser ce registre partagé dans la forme attendue par leur client en aval. Par exemple, OpenClaw intégré consomme directement les valeurs OpenClaw transport, tandis que Claude Code et Gemini reçoivent des valeurs type natives de la CLI comme http, sse ou stdio.

Le serveur d’application Codex respecte aussi un bloc facultatif codex sur chaque serveur. Ce sont des métadonnées de projection OpenClaw pour les fils du serveur d’application Codex uniquement ; elles ne modifient pas les sessions ACP, la configuration générique du harnais Codex ni les autres adaptateurs de runtime. Utilisez codex.agents non vide pour projeter un serveur uniquement dans des identifiants d’agents OpenClaw spécifiques. Les listes d’agents vides, blanches ou invalides sont rejetées par la validation de configuration et omises par le chemin de projection du runtime au lieu de devenir globales. Utilisez codex.defaultToolsApprovalMode (auto, prompt ou approve) pour émettre le default_tools_approval_mode natif de Codex pour un serveur approuvé. OpenClaw retire les métadonnées codex avant de transmettre la configuration native mcp_servers à Codex.

Définitions de serveurs MCP enregistrées

OpenClaw stocke également un registre léger de serveurs MCP dans la configuration pour les surfaces qui veulent des définitions MCP gérées par OpenClaw.

Commandes :

• 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>

Notes :

• list trie les noms de serveurs.
• show sans nom affiche l’objet complet du serveur MCP configuré.
• status classe les transports configurés sans se connecter. --verbose inclut les détails résolus de lancement, de délai d’expiration, d’OAuth, de filtre et d’appels parallèles.
• doctor effectue des contrôles statiques sans se connecter. Ajoutez --probe lorsque la commande doit aussi vérifier que les serveurs activés se connectent.
• probe se connecte et signale le nombre d’outils, la prise en charge des ressources/prompts, la prise en charge des changements de liste et les diagnostics.
• add accepte des drapeaux stdio comme --command, --arg, --env et --cwd, ou des drapeaux HTTP comme --url, --transport, --header, --auth oauth, TLS, délai d’expiration et sélection d’outils.
• set attend une valeur d’objet JSON sur la ligne de commande.
• configure met à jour l’activation, les filtres d’outils, les délais d’expiration, OAuth, TLS et les indications d’appels d’outils parallèles sans remplacer toute la définition du serveur.
• tools met à jour les filtres d’outils par serveur. Les entrées include/exclude sont des noms d’outils MCP et de simples globs *.
• login exécute le flux OAuth pour les serveurs HTTP configurés avec auth: "oauth". La première exécution affiche une URL d’autorisation ; relancez avec --code après approbation.
• logout efface les identifiants OAuth stockés pour le serveur nommé sans supprimer la définition de serveur enregistrée.
• reload libère les runtimes MCP en processus mis en cache. Les processus Gateway ou d’agent dans un autre processus ont toujours besoin de leur propre chemin de rechargement ou de redémarrage.
• Utilisez transport: "streamable-http" pour les serveurs MCP Streamable HTTP. openclaw mcp set normalise aussi le type: "http" natif de la CLI vers la même forme de configuration canonique par compatibilité.
• unset échoue si le serveur nommé n’existe pas.

Exemples :

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

Recettes de serveurs courantes

Ces exemples enregistrent uniquement des définitions de serveurs. Exécutez ensuite openclaw mcp doctor --probe pour prouver que le serveur démarre et expose des outils.

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

Formes de sortie JSON

Utilisez --json pour les scripts et les tableaux de bord. Les ensembles de champs peuvent s'étendre au fil du temps ; les consommateurs doivent donc ignorer les clés inconnues.

{  "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": []}

Exemple de forme de configuration :

{  "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_*"]        }      }    }  }}

Transport stdio

Lance un processus enfant local et communique via stdin/stdout.

Transport SSE / HTTP

Se connecte à un serveur MCP distant via HTTP Server-Sent Events.

Exemple :

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

Les valeurs sensibles dans url (userinfo) et headers sont masquées dans les journaux et la sortie d'état. openclaw mcp doctor avertit lorsque des entrées headers ou env semblant sensibles contiennent des valeurs littérales, afin que les opérateurs puissent déplacer ces valeurs hors de la configuration validée.

Workflow OAuth

OAuth est destiné aux serveurs MCP HTTP qui annoncent le flux OAuth MCP. Les en-têtes Authorization statiques sont ignorés pour un serveur tant que auth: "oauth" est activé.

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

Si le fournisseur effectue une rotation des jetons ou si l'état d'autorisation reste bloqué, exécutez openclaw mcp logout <name>, puis répétez login. logout peut effacer les identifiants d'un serveur HTTP enregistré même après la suppression de auth: "oauth" de la configuration, tant que le nom du serveur et l'URL identifient toujours l'entrée du stockage d'identifiants.

Transport HTTP streamable

streamable-http est une option de transport supplémentaire aux côtés de sse et stdio. Elle utilise le streaming HTTP pour une communication bidirectionnelle avec des serveurs MCP distants.

La configuration OpenClaw utilise transport: "streamable-http" comme orthographe canonique. Les valeurs MCP natives de CLI type: "http" sont acceptées lorsqu'elles sont enregistrées via openclaw mcp set et réparées par openclaw doctor --fix dans la configuration existante, mais transport est ce qu'OpenClaw intégré consomme directement.

Exemple :

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

UI de contrôle

L'UI de contrôle du navigateur inclut une page dédiée aux paramètres MCP à /mcp. Elle affiche le nombre de serveurs configurés, des résumés d'activation/OAuth/filtres, des lignes de transport par serveur, des contrôles d'activation/désactivation, des commandes CLI courantes et un éditeur limité à la section de configuration mcp.

Utilisez la page pour les modifications opérateur et l'inventaire rapide. Utilisez openclaw mcp doctor --probe ou openclaw mcp probe lorsque vous avez besoin d'une preuve de serveur actif.

Workflow opérateur :

1. Ouvrez l’interface de contrôle et choisissez MCP.
2. Consultez les cartes de synthèse pour les serveurs totaux, activés, OAuth et filtrés.
3. Utilisez chaque ligne de serveur pour consulter les indications de transport, d’authentification, de filtre, de délai d’expiration et de commande.
4. Activez ou désactivez l’activation lorsque vous voulez conserver une définition tout en l’excluant de la découverte à l’exécution.
5. Modifiez la section de configuration mcp délimitée pour les changements structurels tels que de nouveaux serveurs, en-têtes, TLS, métadonnées OAuth ou filtres d’outils.
6. Choisissez Enregistrer pour persister uniquement la configuration, ou Enregistrer et publier pour l’appliquer via le chemin de configuration Gateway.
7. Exécutez openclaw mcp doctor --probe lorsque vous avez besoin d’une preuve en direct que le serveur modifié démarre et liste les outils.

Notes :

• les extraits de commande placent les noms de serveurs entre guillemets afin que les noms inhabituels restent copiables dans un shell
• les valeurs affichées qui ressemblent à des URL sont masquées avant le rendu lorsqu’elles contiennent des identifiants intégrés
• la page ne démarre pas les transports MCP par elle-même
• les environnements d’exécution actifs peuvent nécessiter openclaw mcp reload, une publication de configuration Gateway ou un redémarrage de processus selon le processus qui possède les clients MCP

Limites actuelles

Cette page documente le pont tel qu’il est livré aujourd’hui.

Limites actuelles :

• la découverte des conversations dépend des métadonnées de route de session Gateway existantes
• aucun protocole push générique au-delà de l’adaptateur propre à Claude
• aucun outil de modification de message ni de réaction pour l’instant
• le transport HTTP/SSE/streamable-http se connecte à un seul serveur distant ; aucun amont multiplexé pour l’instant
• permissions_list_open inclut uniquement les approbations observées pendant que le pont est connecté

Connexe

• Référence CLI
• Plugins