MCP

openclaw mcp remplit deux fonctions :

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

serve correspond à OpenClaw agissant comme serveur MCP. Les autres sous-commandes correspondent à OpenClaw agissant comme registre côté client MCP pour les serveurs que ses propres environnements d’exécution pourront utiliser ultérieurement.

Utilisez openclaw acp lorsqu’OpenClaw doit lui-même héberger une session de harnais de codage et acheminer cet environnement d’exécution via ACP.

Choisir le parcours MCP approprié

OpenClaw comme serveur MCP

Il s’agit du parcours 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 souhaitez un serveur MCP unique fonctionnant avec tous les backends de canaux d’OpenClaw, au lieu d’exécuter des passerelles distinctes pour chaque canal

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

Fonctionnement

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

Choisir un mode client

Ce qu’expose serve

La passerelle utilise les métadonnées existantes des routes de session du Gateway pour exposer les conversations adossées aux canaux. Une conversation apparaît lorsqu’OpenClaw dispose déjà d’un état de session avec une route connue, telle que :

• channel
• les métadonnées du destinataire ou de la destination
• accountId facultatif
• threadId facultatif

Les clients MCP disposent ainsi d’un emplacement unique pour :

• répertorier les conversations acheminées récentes
• lire l’historique récent des transcriptions
• attendre de nouveaux événements entrants
• renvoyer une réponse via la même route
• voir les demandes d’approbation reçues pendant que la passerelle est connectée

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 de la passerelle

Modèle d’événements

La passerelle conserve une file d’attente d’événements en mémoire tant qu’elle est connectée.

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

La passerelle peut également exposer des notifications de canal propres à Claude. Il s’agit de 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 sous forme de notifications MCP propres à Claude.

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

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

Comportement actuel de la passerelle :

• les messages de transcription user entrants sont transférés en tant que 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 <id> ou no <id> (<id> est l’identifiant de demande à 5 lettres, sans l), la passerelle le convertit en notifications/claude/channel/permission
• ces notifications sont limitées à la session active ; si le client MCP se déconnecte, aucune cible push n’est disponible

Ce comportement est volontairement propre au client. Les clients MCP génériques doivent utiliser les outils d’interrogation standard.

Configuration du client MCP

Exemple de configuration d’un 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 le routage. Il expose uniquement les conversations que le Gateway sait déjà router.

Cela signifie que :

• les listes d’autorisation des expéditeurs, 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 par l’intermédiaire d’une route existante enregistrée
• l’état des approbations est actif et conservé uniquement en mémoire 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 s’agit de métadonnées de route manquantes ou 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 exécute un seul conteneur : il initialise l’état des conversations, démarre le Gateway, puis lance openclaw mcp serve comme processus enfant stdio et le pilote comme un client MCP. Il vérifie la découverte des conversations, la lecture des transcriptions, la lecture des métadonnées des pièces jointes, le comportement de la file d’événements en direct ainsi que les notifications de canal et d’autorisation de style Claude sur le véritable pont MCP stdio. Le routage des envois sortants (messages_send réutilisant la route de conversation enregistrée) est couvert séparément par des tests unitaires dans src/mcp/channel-server.test.ts.

Il s’agit du moyen le plus rapide de prouver que le pont fonctionne sans intégrer de véritable compte Telegram, Discord ou iMessage à l’exécution du test.

Pour un contexte de test plus général, consultez Tests.

Résolution des problèmes

OpenClaw comme registre de clients 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 par l’intermédiaire de MCP. Elles gèrent les définitions de serveurs MCP administré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 environnements d’exécution qu’OpenClaw lance ou configure ultérieurement, comme OpenClaw intégré et d’autres adaptateurs d’environnement d’exécution. OpenClaw stocke les définitions de manière centralisée afin que ces environnements d’exécution n’aient pas à conserver leurs propres listes de serveurs MCP en double.

Les adaptateurs d’environnement d’exécution peuvent normaliser ce registre partagé dans la forme attendue par leur client en aval. Par exemple, OpenClaw intégré consomme directement les valeurs transport d’OpenClaw, 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 prend également en charge un bloc facultatif codex sur chaque serveur. Il s’agit de métadonnées de projection OpenClaw destinées uniquement aux fils de discussion du serveur d’application Codex ; elles ne modifient pas les sessions ACP, la configuration générique du harnais Codex ni les autres adaptateurs d’environnement d’exécution. Utilisez une valeur codex.agents non vide pour projeter un serveur uniquement dans des identifiants d’agents OpenClaw précis. Les listes d’agents vides, ne contenant que des espaces ou non valides sont rejetées par la validation de la configuration et omises du chemin de projection de l’environnement d’exécution 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 de confiance. OpenClaw supprime les métadonnées codex avant de transmettre la configuration native mcp_servers à Codex.

Définitions de serveurs MCP enregistrées

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>

Remarques :

• list trie les noms de serveurs.
• show sans nom affiche l’objet complet du serveur MCP configuré.
• status classe les transports configurés sans établir de connexion. --verbose inclut les détails résolus concernant le lancement, les délais d’expiration, OAuth, les filtres et les appels parallèles.
• doctor effectue des vérifications statiques sans établir de connexion. Ajoutez --probe lorsque la commande doit également vérifier que les serveurs activés se connectent.
• probe se connecte et signale le nombre d’outils, la prise en charge des ressources et invites, la prise en charge des modifications de liste et les diagnostics.
• add accepte des options stdio telles que --command, --arg, --env et --cwd, ou des options HTTP telles que --url, --transport, --header, --auth oauth, ainsi que des options TLS, de délai d’expiration et de sélection des 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 relatives aux appels d’outils parallèles sans remplacer l’intégralité de la définition du serveur. Ajoutez --probe pour vérifier le serveur mis à jour avant l’enregistrement.
• tools met à jour les filtres d’outils propres à chaque serveur. Les entrées d’inclusion et d’exclusion sont des noms d’outils MCP et des motifs glob simples *.
• 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 ; exécutez de nouveau la commande avec --code après l’approbation.
• logout efface les identifiants OAuth enregistrés pour le serveur nommé sans supprimer la définition de serveur enregistrée.
• reload libère les environnements d’exécution MCP en cours de processus mis en cache pour le processus CLI actuel uniquement. Les processus Gateway ou d’agent exécutés dans un autre processus nécessitent toujours leur propre mécanisme de rechargement ou de redémarrage.
• Utilisez transport: "streamable-http" pour les serveurs MCP HTTP diffusables. openclaw mcp set normalise également le type: "http" natif de la CLI vers la même forme de configuration canonique à des fins de 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 courantes pour les serveurs

Ces exemples enregistrent uniquement les définitions de serveur. Exécutez ensuite openclaw mcp doctor --probe pour vérifier 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

Structures 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": true,  "path": "/home/user/.openclaw/openclaw.json",  "servers": [    {      "name": "docs",      "ok": true,      "issues": [        {          "level": "warning",          "message": "Les identifiants OAuth ne sont pas autorisés ; exécutez openclaw mcp login docs"        }      ]    }  ]}

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

Exemple de structure 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 par l’intermédiaire d’événements envoyés par le serveur HTTP.

Exemple :

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

Les valeurs sensibles dans url (informations utilisateur) et headers sont masquées dans les journaux et la sortie d’état. openclaw mcp doctor émet un avertissement lorsque des entrées headers ou env qui semblent sensibles contiennent des valeurs littérales, afin que les opérateurs puissent retirer ces valeurs de la configuration validée dans le dépôt.

Processus OAuth

OAuth est destiné aux serveurs MCP HTTP qui annoncent le flux OAuth MCP. Les en-têtes statiques Authorization sont ignorés pour un serveur lorsque auth: "oauth" est activé. Les identifiants enregistrés par openclaw mcp login fonctionnent avec le MCP intégré, les exécuteurs CLI et le serveur d’application Codex local.

Tant que les identifiants ne sont pas disponibles, OpenClaw omet uniquement ce serveur MCP de l’environnement d’exécution de l’agent au lieu de faire échouer le tour de l’agent. L’opérateur, ou un agent disposant d’un accès au shell, peut alors exécuter openclaw mcp login <name> et utiliser le serveur lors d’un tour ultérieur.

Lorsqu’un service MCP distant s’appuie déjà sur un profil d’authentification OpenClaw distinct capable d’actualiser les identifiants, vous pouvez éventuellement définir oauth.authProfileId. OpenClaw actualise l’une ou l’autre source d’identifiants avant la projection dans l’environnement d’exécution et transmet uniquement le jeton d’accès actuel au client MCP en aval.

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

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

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 renouvelle les 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 et l’URL du serveur identifient toujours l’entrée du magasin d’identifiants.

Transport HTTP avec diffusion en continu

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

La configuration OpenClaw utilise transport: "streamable-http" comme orthographe canonique. Les valeurs type: "http" MCP natives de la CLI sont acceptées lorsqu’elles sont enregistrées au moyen de openclaw mcp set et réparées par openclaw doctor --fix dans une configuration existante, mais transport est la forme directement consommée par OpenClaw intégré.

Exemple :

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

Interface de contrôle

L’interface de contrôle dans le navigateur comprend une page dédiée aux paramètres MCP à l’emplacement /settings/mcp ; l’ancien chemin /mcp reste un alias. La page affiche le nombre de serveurs configurés, des récapitulatifs des serveurs activés, OAuth et filtrés, des lignes de transport par serveur, des commandes d’activation et de désactivation, les commandes CLI courantes et un éditeur limité à la section de configuration mcp.

Utilisez cette page pour les modifications effectuées par l’opérateur et les inventaires rapides. Utilisez openclaw mcp doctor --probe ou openclaw mcp probe lorsqu’une vérification active du serveur est nécessaire.

Procédure pour l’opérateur :

1. Ouvrez l’interface de contrôle et choisissez MCP.
2. Consultez les cartes récapitulatives indiquant le nombre total de serveurs, ainsi que les serveurs activés, OAuth et filtrés.
3. Utilisez chaque ligne de serveur pour obtenir des indications sur le transport, l’authentification, le filtre, le délai d’expiration et les commandes.
4. Basculez l’activation lorsque vous souhaitez conserver une définition tout en l’excluant de la découverte à l’exécution.
5. Modifiez la section de configuration mcp concernée pour apporter des changements structurels, tels que de nouveaux serveurs, des en-têtes, TLS, des métadonnées OAuth ou des filtres d’outils.
6. Choisissez Enregistrer pour conserver uniquement la configuration, ou Enregistrer et publier pour l’appliquer par l’intermédiaire du chemin de configuration du Gateway.
7. Exécutez openclaw mcp doctor --probe lorsqu’il est nécessaire de vérifier en direct que le serveur modifié démarre et répertorie les outils.

Remarques :

• 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 ressemblant à des URL sont expurgées avant le rendu lorsqu’elles contiennent des identifiants intégrés
• la page ne démarre pas elle-même les transports MCP
• les environnements d’exécution actifs peuvent nécessiter openclaw mcp reload, la publication de la configuration du Gateway ou le redémarrage du processus, selon le processus qui possède les clients MCP

Applications MCP

OpenClaw peut afficher les outils qui implémentent l’extension MCP Apps stable. Les applications sont facultatives, car leur code HTML provient du serveur MCP configuré et peut demander des outils ou des ressources visibles par l’application auprès de ce même serveur.

Activez le pont hôte :

openclaw config set mcp.apps.enabled true --strict-json

Redémarrez le Gateway après avoir modifié ce paramètre. Lorsqu’il est activé, OpenClaw démarre un écouteur HTTP(S) réservé au bac à sable sur le port du Gateway plus un (pour le Gateway par défaut, 18790). L’interface de contrôle charge les applications depuis cette origine distincte ; l’écouteur ne fournit jamais l’interface de contrôle, les routes authentifiées du Gateway ni les données utilisateur.

Les connexions directes au Gateway doivent avoir accès aux deux ports. Si un proxy inverse ou un terminateur TLS expose l’interface de contrôle, attribuez aux applications une origine publique dédiée et transmettez uniquement cette origine vers l’écouteur du bac à sable :

{  mcp: {    apps: {      enabled: true,      sandboxOrigin: "https://mcp-apps.example.com",      sandboxPort: 18790,    },  },}

L’origine du bac à sable doit être différente de celle de l’interface de contrôle. N’y hébergez aucun autre contenu authentifié ou sensible.

Par exemple, la démonstration React de base officielle peut être configurée comme suit :

{  mcp: {    apps: { enabled: true },    servers: {      "basic-react": {        command: "npx",        args: ["-y", "@modelcontextprotocol/server-basic-react", "--stdio"],      },    },  },}

Comportement et limites de sécurité :

• OpenClaw annonce l’extension io.modelcontextprotocol/ui uniquement lorsque les applications sont activées.
• Seules les ressources ui:// dont le type MIME correspond exactement à text/html;profile=mcp-app sont affichées.
• Les ressources d’interface utilisateur sont limitées à 2 Mio, placées derrière un proxy à double iframe sur une origine externe dédiée, chargées dans une origine d’application interne opaque et soumises à une CSP dérivée des métadonnées de la ressource.
• Les outils réservés aux applications (_meta.ui.visibility: ["app"]) restent exclus des listes d’outils du modèle. Les applications peuvent appeler uniquement les outils visibles par les applications sur leur serveur propriétaire qui respectent également la politique d’outils OpenClaw effective pour l’exécution ayant créé la vue.
• Les autorisations d’application liées à l’origine, telles que l’accès à la caméra, au microphone et à la géolocalisation, ne sont pas accordées tant que les documents internes des applications utilisent des origines opaques pour assurer l’isolation entre les applications.
• Le code HTML de l’application, les arguments complets des outils et les résultats bruts résident dans un bail de vue en mémoire limité à dix minutes et ne sont ni écrits sur le disque ni copiés dans les métadonnées d’aperçu de la transcription. La transcription stocke uniquement un descripteur limité de serveur, d’outil et de ressource lié à l’identifiant d’origine de l’appel d’outil. Après le redémarrage d’un Gateway, l’interface de contrôle peut vérifier ce descripteur par rapport à la transcription de la session authentifiée et récupérer de nouveau la ressource ui:// ; les vues reconstruites sont en lecture seule jusqu’à ce qu’une nouvelle exécution établisse les autorisations d’outils actuelles.
• openclaw security audit affiche un avertissement tant que le pont est activé. Désactivez-le avec openclaw config set mcp.apps.enabled false --strict-json lorsqu’il n’est pas nécessaire.

Limites actuelles

Cette page décrit le pont tel qu’il est fourni aujourd’hui.

Limites actuelles :

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

Pages connexes

• Référence de la CLI
• Plugins