MCP

openclaw mcp ha due compiti:

• eseguire OpenClaw come server MCP con openclaw mcp serve
• gestire le definizioni dei server MCP in uscita di proprietà di OpenClaw con list, show, set e unset

In altre parole:

• serve è OpenClaw che agisce come server MCP
• list / show / set / unset è OpenClaw che agisce come registro lato client MCP per altri server MCP che i suoi runtime potrebbero consumare in seguito

Usa openclaw acp quando OpenClaw deve ospitare direttamente una sessione di harness di programmazione e instradare quel runtime tramite ACP.

# OpenClaw come server MCP

Questo è il percorso openclaw mcp serve.

# Quando usare serve

Usa openclaw mcp serve quando:

• Codex, Claude Code o un altro client MCP deve parlare direttamente con conversazioni di canali supportate da OpenClaw
• hai già un Gateway OpenClaw locale o remoto con sessioni instradate
• vuoi un unico server MCP che funzioni su tutti i backend di canale di OpenClaw invece di eseguire bridge separati per canale

Usa invece openclaw acp quando OpenClaw deve ospitare direttamente il runtime di programmazione e mantenere la sessione agente dentro OpenClaw.

# Come funziona

openclaw mcp serve avvia un server MCP stdio. Il client MCP possiede quel processo. Finché il client mantiene aperta la sessione stdio, il bridge si connette a un Gateway OpenClaw locale o remoto tramite WebSocket ed espone le conversazioni di canale instradate tramite MCP.

# Scegliere una modalità client

Usa lo stesso bridge in due modi diversi:

# Cosa espone serve

Il bridge usa i metadati esistenti delle rotte di sessione del Gateway per esporre conversazioni supportate dai canali. Una conversazione appare quando OpenClaw ha già uno stato di sessione con una rotta nota, ad esempio:

• channel
• metadati di destinatario o destinazione
• accountId opzionale
• threadId opzionale

Questo offre ai client MCP un unico punto per:

• elencare le conversazioni instradate recenti
• leggere la cronologia recente delle trascrizioni
• attendere nuovi eventi in ingresso
• inviare una risposta tramite la stessa rotta
• vedere le richieste di approvazione che arrivano mentre il bridge è connesso

# Utilizzo

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

# Strumenti del bridge

Il bridge attuale espone questi strumenti MCP:

# Modello degli eventi

Il bridge mantiene una coda di eventi in memoria mentre è connesso.

Tipi di evento attuali:

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

# Notifiche canale Claude

Il bridge può anche esporre notifiche di canale specifiche di Claude. Questo è l'equivalente OpenClaw di un adattatore di canale Claude Code: gli strumenti MCP standard restano disponibili, ma i messaggi live in ingresso possono anche arrivare come notifiche MCP specifiche di Claude.

Quando la modalità canale Claude è abilitata, il server annuncia capacità sperimentali Claude e può emettere:

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

Comportamento attuale del bridge:

• i messaggi di trascrizione user in ingresso vengono inoltrati come notifications/claude/channel
• le richieste di permesso Claude ricevute tramite MCP vengono tracciate in memoria
• se la conversazione collegata invia in seguito yes abcde o no abcde, il bridge lo converte in notifications/claude/channel/permission
• queste notifiche sono solo per la sessione live; se il client MCP si disconnette, non c'è alcun destinatario push

Questo è intenzionalmente specifico del client. I client MCP generici dovrebbero basarsi sugli strumenti standard di polling.

# Configurazione client MCP

Esempio di configurazione client stdio:

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

Per la maggior parte dei client MCP generici, inizia con la superficie di strumenti standard e ignora la modalità Claude. Attiva la modalità Claude solo per i client che comprendono effettivamente i metodi di notifica specifici di Claude.

# Opzioni

openclaw mcp serve supporta:

# Sicurezza e limite di fiducia

Il bridge non inventa l'instradamento. Espone solo le conversazioni che il Gateway sa già come instradare.

Questo significa che:

• allowlist dei mittenti, pairing e fiducia a livello di canale appartengono ancora alla configurazione del canale OpenClaw sottostante
• messages_send può rispondere solo tramite una rotta archiviata esistente
• lo stato di approvazione è live/in memoria solo per la sessione bridge attuale
• l'autenticazione del bridge dovrebbe usare gli stessi controlli tramite token o password del Gateway che considereresti affidabili per qualsiasi altro client Gateway remoto

Se una conversazione manca da conversations_list, la causa abituale non è la configurazione MCP. Sono metadati di rotta mancanti o incompleti nella sessione Gateway sottostante.

# Test

OpenClaw include uno smoke Docker deterministico per questo bridge:

pnpm test:docker:mcp-channels

Quello smoke:

• avvia un container Gateway con seed
• avvia un secondo container che esegue openclaw mcp serve
• verifica discovery delle conversazioni, letture delle trascrizioni, letture dei metadati degli allegati, comportamento della coda di eventi live e instradamento degli invii in uscita
• convalida notifiche di canale e permesso in stile Claude tramite il vero bridge MCP stdio

Questo è il modo più rapido per dimostrare che il bridge funziona senza collegare un account reale Telegram, Discord o iMessage all'esecuzione del test.

Per un contesto di test più ampio, vedi Test.

# Risoluzione dei problemi

# OpenClaw come registro client MCP

Questo è il percorso openclaw mcp list, show, set e unset.

Questi comandi non espongono OpenClaw tramite MCP. Gestiscono le definizioni dei server MCP di proprietà di OpenClaw sotto mcp.servers nella configurazione di OpenClaw.

Le definizioni salvate sono destinate ai runtime che OpenClaw avvia o configura in seguito, come Pi integrato e altri adattatori runtime. OpenClaw archivia le definizioni centralmente così che tali runtime non debbano mantenere i propri elenchi duplicati di server MCP.

Gli adattatori runtime possono normalizzare questo registro condiviso nella forma attesa dal loro client downstream. Ad esempio, Pi integrato consuma direttamente i valori transport di OpenClaw, mentre Claude Code e Gemini ricevono valori type nativi della CLI come http, sse o stdio.

# Definizioni salvate dei server MCP

OpenClaw archivia anche un registro leggero dei server MCP nella configurazione per le superfici che vogliono definizioni MCP gestite da OpenClaw.

Comandi:

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

Note:

• list ordina i nomi dei server.
• show senza un nome stampa l'intero oggetto del server MCP configurato.
• set si aspetta un valore oggetto JSON sulla riga di comando.
• Usa transport: "streamable-http" per i server MCP Streamable HTTP. openclaw mcp set normalizza anche type: "http" nativo della CLI nella stessa forma di configurazione canonica per compatibilità.
• unset non riesce se il server indicato non esiste.

Esempi:

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

Esempio di forma della configurazione:

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

# Trasporto stdio

Avvia un processo figlio locale e comunica tramite stdin/stdout.

# Trasporto SSE / HTTP

Si connette a un server MCP remoto tramite HTTP Server-Sent Events.

Esempio:

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

I valori sensibili in url (userinfo) e headers vengono oscurati nei log e nell'output di stato.

# Trasporto Streamable HTTP

streamable-http è un'opzione di trasporto aggiuntiva insieme a sse e stdio. Usa lo streaming HTTP per la comunicazione bidirezionale con server MCP remoti.

La configurazione di OpenClaw usa transport: "streamable-http" come grafia canonica. I valori MCP type: "http" nativi della CLI sono accettati quando salvati tramite openclaw mcp set e riparati da openclaw doctor --fix nella configurazione esistente, ma transport è ciò che Pi integrato consuma direttamente.

Esempio:

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

# Limiti attuali

Questa pagina documenta il bridge così come distribuito oggi.

Limiti attuali:

• la scoperta delle conversazioni dipende dai metadati di route delle sessioni Gateway esistenti
• nessun protocollo push generico oltre all'adattatore specifico di Claude
• nessuno strumento per modificare o reagire ai messaggi per ora
• il trasporto HTTP/SSE/streamable-http si connette a un singolo server remoto; nessun upstream multiplexed per ora
• permissions_list_open include solo le approvazioni osservate mentre il bridge è connesso

# Correlati

• Riferimento CLI
• Plugins