MCP

openclaw mcp ha due compiti:

• eseguire OpenClaw come server MCP con openclaw mcp serve
• gestire le definizioni dei server MCP in uscita gestiti da OpenClaw con list, show, status, doctor, probe, add, set, configure, tools, login, logout, reload e unset

In altre parole:

• serve è OpenClaw che agisce come server MCP
• gli altri sottocomandi sono OpenClaw che agisce come registro lato client MCP per i server MCP che i suoi runtime potranno usare in seguito

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

Scegliere il percorso MCP corretto

OpenClaw ha diverse superfici MCP. Scegli quella che corrisponde a chi possiede il runtime dell'agente e a chi possiede gli strumenti.

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 tra 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 codifica 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 conversazioni di canali 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 da 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 --verboseopenclaw 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 di 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 rimangono 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 il proprietario del comando nella conversazione collegata invia in seguito yes abcde o no abcde, il bridge lo converte in notifications/claude/channel/permission
• queste notifiche sono solo per sessioni live; se il client MCP si disconnette, non esiste un target push

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

Configurazione del 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 degli 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 confine di attendibilità

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

Questo significa che:

• le allowlist dei mittenti, l'associazione e l'attendibilità a livello di canale appartengono ancora alla configurazione del canale OpenClaw sottostante
• messages_send può rispondere solo tramite una route archiviata esistente
• lo stato di approvazione è live/in memoria solo per la sessione bridge corrente
• l'autenticazione del bridge deve usare gli stessi controlli di token o password del Gateway che ritieni affidabili per qualsiasi altro client Gateway remoto

Se una conversazione manca da conversations_list, la causa abituale non è la configurazione MCP. Mancano metadati di route, o sono incompleti, nella sessione Gateway sottostante.

Test

OpenClaw include uno smoke Docker deterministico per questo bridge:

pnpm test:docker:mcp-channels

Questo smoke:

• avvia un container Gateway con seed
• avvia un secondo container che genera openclaw mcp serve
• verifica l'individuazione delle conversazioni, le letture delle trascrizioni, le letture dei metadati degli allegati, il comportamento della coda di eventi live e il routing degli invii in uscita
• convalida le notifiche di canale e autorizzazione in stile Claude sul bridge MCP stdio reale

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

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

Risoluzione dei problemi

OpenClaw come registro di client MCP

Questo è il percorso openclaw mcp list, show, status, doctor, probe, add, set, configure, tools, login, logout, reload e unset.

Questi comandi non espongono OpenClaw tramite MCP. Gestiscono le definizioni dei server MCP gestite da OpenClaw sotto mcp.servers nella configurazione OpenClaw. Non leggono i server mcporter da config/mcporter.json.

Quelle definizioni salvate sono per runtime che OpenClaw avvia o configura in seguito, come OpenClaw incorporato e altri adapter runtime. OpenClaw archivia le definizioni centralmente, così quei runtime non devono mantenere i propri elenchi duplicati di server MCP.

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

Codex app-server rispetta anche un blocco opzionale codex su ciascun server. Si tratta di metadati di proiezione OpenClaw solo per i thread Codex app-server; non modifica le sessioni ACP, la configurazione generica dell'harness Codex o altri adapter runtime. Usa codex.agents non vuoto per proiettare un server solo in specifici ID agente OpenClaw. Gli elenchi di agenti vuoti, blank o non validi vengono rifiutati dalla convalida della configurazione e omessi dal percorso di proiezione runtime invece di diventare globali. Usa codex.defaultToolsApprovalMode (auto, prompt o approve) per emettere il default_tools_approval_mode nativo di Codex per un server attendibile. OpenClaw rimuove i metadati codex prima di passare la configurazione nativa mcp_servers a Codex.

Definizioni salvate dei server MCP

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

Comandi:

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

Note:

• list ordina i nomi dei server.
• show senza nome stampa l'intero oggetto server MCP configurato.
• status classifica i trasporti configurati senza connettersi. --verbose include dettagli risolti su avvio, timeout, OAuth, filtro e chiamate parallele.
• doctor esegue controlli statici senza connettersi. Aggiungi --probe quando il comando deve verificare anche che i server abilitati si connettano.
• probe si connette e segnala conteggi degli strumenti, supporto per risorse/prompt, supporto alle modifiche dell'elenco e diagnostica.
• add accetta flag stdio come --command, --arg, --env e --cwd, oppure flag HTTP come --url, --transport, --header, --auth oauth, TLS, timeout e flag di selezione degli strumenti.
• set si aspetta un valore oggetto JSON sulla riga di comando.
• configure aggiorna abilitazione, filtri degli strumenti, timeout, OAuth, TLS e suggerimenti per chiamate parallele agli strumenti senza sostituire l'intera definizione del server.
• tools aggiorna i filtri strumenti per server. Le voci include/exclude sono nomi di strumenti MCP e semplici glob *.
• login esegue il flusso OAuth per server HTTP configurati con auth: "oauth". La prima esecuzione stampa un URL di autorizzazione; riesegui con --code dopo l'approvazione.
• logout cancella le credenziali OAuth archiviate per il server indicato senza rimuovere la definizione del server salvata.
• reload elimina i runtime MCP in-process in cache. I processi Gateway o agente in un altro processo necessitano comunque del proprio percorso di ricaricamento o riavvio.
• 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 fallisce se il server indicato non esiste.

Esempi:

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

Ricette comuni per server

Questi esempi salvano solo definizioni di server. Esegui poi openclaw mcp doctor --probe per dimostrare che il server si avvia ed espone strumenti.

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

Formati dell'output JSON

Usa --json per script e dashboard. Gli insiemi di campi possono crescere nel tempo, quindi i consumer devono ignorare le chiavi sconosciute.

{  "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": "Le credenziali OAuth non sono autorizzate; esegui 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": []}

Esempio di formato di configurazione:

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

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",        "auth": "oauth",        "timeout": 20,        "headers": {          "Authorization": "Bearer <token>"        }      }    }  }}

I valori sensibili in url (userinfo) e headers vengono redatti nei log e nell'output di stato. openclaw mcp doctor avvisa quando voci headers o env dall'aspetto sensibile contengono valori letterali, così gli operatori possono spostare quei valori fuori dalla configurazione committata.

Workflow OAuth

OAuth è per server MCP HTTP che pubblicizzano il flusso OAuth MCP. Gli header statici Authorization vengono ignorati per un server mentre auth: "oauth" è abilitato.

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

Se il provider ruota i token o lo stato di autorizzazione si blocca, esegui openclaw mcp logout <name>, quindi ripeti login. logout può cancellare le credenziali per un server HTTP salvato anche dopo che auth: "oauth" è stato rimosso dalla configurazione, purché il nome del server e l'URL identifichino ancora la voce dell'archivio credenziali.

Trasporto HTTP streamable

streamable-http è un'opzione di trasporto aggiuntiva accanto 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 nativi della CLI type: "http" sono accettati quando salvati tramite openclaw mcp set e riparati da openclaw doctor --fix nella configurazione esistente, ma transport è ciò che OpenClaw incorporato consuma direttamente.

Esempio:

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

UI di controllo

La UI di controllo nel browser include una pagina dedicata alle impostazioni MCP in /mcp. Mostra i conteggi dei server configurati, riepiloghi di abilitazione/OAuth/filtri, righe di trasporto per server, controlli di abilitazione/disabilitazione, comandi CLI comuni e un editor con ambito per la sezione di configurazione mcp.

Usa la pagina per modifiche da operatore e inventario rapido. Usa openclaw mcp doctor --probe o openclaw mcp probe quando ti serve una prova live del server.

Workflow dell'operatore:

1. Apri l'interfaccia utente di controllo e scegli MCP.
2. Esamina le schede di riepilogo per server totali, abilitati, OAuth e filtrati.
3. Usa ogni riga del server per suggerimenti su trasporto, autenticazione, filtro, timeout e comandi.
4. Attiva o disattiva l'abilitazione quando vuoi mantenere una definizione ma escluderla dal rilevamento in runtime.
5. Modifica la sezione di configurazione mcp con ambito per modifiche strutturali come nuovi server, intestazioni, TLS, metadati OAuth o filtri degli strumenti.
6. Scegli Salva per rendere persistente solo la configurazione, oppure Salva e pubblica per applicarla tramite il percorso di configurazione del Gateway.
7. Esegui openclaw mcp doctor --probe quando ti serve una prova live che il server modificato si avvii ed elenchi gli strumenti.

Note:

• i frammenti di comando racchiudono tra virgolette i nomi dei server affinché i nomi insoliti restino copiabili in una shell
• i valori visualizzati simili a URL vengono oscurati prima del rendering quando contengono credenziali incorporate
• la pagina non avvia autonomamente i trasporti MCP
• i runtime attivi potrebbero richiedere openclaw mcp reload, la pubblicazione della configurazione del Gateway o il riavvio del processo a seconda di quale processo possiede i client MCP

Limiti attuali

Questa pagina documenta il bridge così come viene distribuito oggi.

Limiti attuali:

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

Correlati

• Riferimento CLI
• Plugin