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 appartenant à OpenClaw avec list, show, set et unset

Autrement dit :

• serve correspond à OpenClaw agissant comme serveur MCP
• list / show / set / unset correspond à OpenClaw agissant comme registre côté client MCP pour d'autres serveurs MCP que ses runtimes pourront consommer plus tard

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

# OpenClaw comme serveur MCP

Il s'agit du 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 avez déjà un Gateway OpenClaw local ou distant avec des sessions routées
• vous voulez un seul serveur MCP qui fonctionne avec les backends de canaux d'OpenClaw au lieu d'exécuter des passerelles séparées 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 maintient la session stdio ouverte, la passerelle se connecte à un Gateway OpenClaw local ou distant via WebSocket et expose les conversations de canaux routées via MCP.

# Choisir un mode client

Utilisez la même passerelle de deux façons différentes :

# Ce que serve expose

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

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

Cela donne aux clients MCP un emplacement unique pour :

• lister les conversations routé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 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 --verbose
openclaw mcp serve --claude-channel-mode off

# Outils de la passerelle

La passerelle actuelle expose ces outils MCP :

# 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 aussi exposer des notifications de canal spécifiques à 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 aussi arriver comme notifications MCP spécifiques à Claude.

Lorsque le mode de 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 de la passerelle :

• 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 la conversation liée envoie ensuite yes abcde ou no abcde, la passerelle convertit cela en notifications/claude/channel/permission
• ces notifications ne valent que pour la session en direct ; si le client MCP se déconnecte, il n'y a pas de cible push

C'est volontairement spécifique 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 par 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 spécifiques à Claude.

# Options

openclaw mcp serve prend en charge :

# Sécurité et limite de confiance

La passerelle n'invente pas de routage. Elle expose uniquement les conversations que Gateway sait déjà router.

Cela signifie que :

• les listes d'autorisation d'expéditeurs, l'appairage et la confiance au niveau du canal appartiennent toujours à la configuration de canal OpenClaw sous-jacente
• messages_send ne peut répondre que via une route stockée existante
• l'état d'approbation est uniquement en direct/en mémoire pour la session de passerelle actuelle
• l'authentification de la passerelle doit utiliser les mêmes contrôles de jeton ou de mot de passe Gateway que ceux auxquels vous feriez confiance pour tout autre client Gateway distant

Si une conversation manque dans 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 smoke Docker déterministe pour cette passerelle :

pnpm test:docker:mcp-channels

Ce smoke :

• démarre un conteneur Gateway initialisé
• 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'attente d'événements en direct et le routage des envois sortants
• valide les notifications de canal et d'autorisation de style Claude via la véritable passerelle MCP stdio

C'est le moyen le plus rapide de prouver que la passerelle 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 de clients MCP

Ceci est le chemin openclaw mcp list, show, set et unset.

Ces commandes n’exposent pas OpenClaw via MCP. Elles gèrent les définitions de serveurs MCP appartenant à OpenClaw sous mcp.servers dans la configuration OpenClaw.

Ces définitions enregistrées sont destinées aux environnements d’exécution qu’OpenClaw lance ou configure ultérieurement, comme le Pi intégré et d’autres adaptateurs d’exécution. OpenClaw stocke les définitions de manière centralisée afin que ces environnements d’exécution n’aient pas besoin de conserver leurs propres listes de serveurs MCP en double.

Les adaptateurs d’exécution peuvent normaliser ce registre partagé dans la forme attendue par leur client en aval. Par exemple, le Pi 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.

# Définitions de serveurs MCP enregistrées

OpenClaw stocke aussi 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 set <name> <json>
• openclaw mcp unset <name>

Remarques :

• list trie les noms de serveurs.
• show sans nom affiche l’objet complet des serveurs MCP configurés.
• set attend une valeur d’objet JSON sur la ligne de commande.
• 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 pour compatibilité.
• unset échoue si le serveur nommé n’existe pas.

Exemples :

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

Exemple de forme de configuration :

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

# 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",
        "headers": {
          "Authorization": "Bearer <token>"
        }
      }
    }
  }
}

Les valeurs sensibles dans url (userinfo) et headers sont masquées dans les journaux et la sortie d’état.

# Transport Streamable HTTP

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

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

Exemple :

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

# 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
• pas encore d’outils de modification de message ou de réaction
• 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é

# Associé

• Référence CLI
• Plugins