MCP

openclaw mcp svolge due funzioni:

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

serve corrisponde a OpenClaw che opera come server MCP. Gli altri sottocomandi corrispondono a OpenClaw che opera come registro lato client MCP per server che i suoi runtime potranno utilizzare in seguito.

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

Scegliere il percorso MCP corretto

OpenClaw come server MCP

Questo è il percorso openclaw mcp serve.

Quando utilizzare serve

Utilizzare openclaw mcp serve quando:

• Codex, Claude Code o un altro client MCP deve comunicare direttamente con le conversazioni dei canali supportate da OpenClaw
• è già disponibile un Gateway OpenClaw locale o remoto con sessioni instradate
• si desidera un unico server MCP che funzioni con tutti i backend dei canali di OpenClaw, anziché eseguire bridge separati per ciascun canale

Utilizzare invece openclaw acp quando OpenClaw deve ospitare direttamente il runtime di programmazione e mantenere la sessione dell'agente all'interno di OpenClaw.

Funzionamento

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

Scegliere una modalità client

Elementi esposti da serve

Il bridge utilizza i metadati di instradamento delle sessioni già presenti nel Gateway per esporre conversazioni supportate dai canali. Una conversazione viene visualizzata quando OpenClaw dispone già di uno stato di sessione con un percorso noto, ad esempio:

• channel
• metadati del destinatario o della destinazione
• accountId facoltativo
• threadId facoltativo

Ciò offre ai client MCP un unico punto da cui:

• elencare le conversazioni instradate recenti
• leggere la cronologia recente delle trascrizioni
• attendere nuovi eventi in ingresso
• inviare una risposta tramite lo stesso percorso
• visualizzare le richieste di approvazione ricevute 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

Modello degli eventi

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

Tipi di eventi attuali:

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

Notifiche del canale Claude

Il bridge può inoltre esporre notifiche specifiche del canale Claude. È l'equivalente OpenClaw di un adattatore di canale Claude Code: gli strumenti MCP standard rimangono disponibili, ma i messaggi in ingresso in tempo reale possono anche arrivare come notifiche MCP specifiche di Claude.

Quando la modalità canale Claude è abilitata, il server dichiara funzionalità sperimentali di Claude e può emettere:

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

Comportamento attuale del bridge:

• i messaggi della trascrizione user in ingresso vengono inoltrati come notifications/claude/channel
• le richieste di autorizzazione di Claude ricevute tramite MCP vengono registrate in memoria
• se il proprietario del comando nella conversazione collegata invia successivamente yes <id> o no <id> (<id> è l'id richiesta di 5 lettere, escluso l), il bridge lo converte in notifications/claude/channel/permission
• queste notifiche sono disponibili soltanto durante la sessione attiva; se il client MCP si disconnette, non esiste alcuna destinazione push

Questo comportamento è intenzionalmente specifico del client. I client MCP generici devono utilizzare gli strumenti di polling standard.

Configurazione del client MCP

Esempio di configurazione di un 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, iniziare con la superficie di strumenti standard e ignorare la modalità Claude. Attivare 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 crea autonomamente l'instradamento. Espone soltanto le conversazioni che il Gateway sa già come instradare.

Ciò significa che:

• gli elenchi di mittenti consentiti, l'associazione e l'attendibilità a livello di canale continuano ad appartenere alla configurazione del canale OpenClaw sottostante
• messages_send può rispondere soltanto tramite una route esistente e memorizzata
• lo stato delle approvazioni è attivo e conservato solo in memoria per la sessione corrente del bridge
• l'autenticazione del bridge deve usare gli stessi controlli tramite token o password del Gateway considerati attendibili per qualsiasi altro client Gateway remoto

Se una conversazione non è presente in conversations_list, in genere la causa non è la configurazione MCP. Si tratta di metadati di route mancanti o incompleti nella sessione Gateway sottostante.

Test

OpenClaw include uno smoke test Docker deterministico per questo bridge:

pnpm test:docker:mcp-channels

Lo smoke test esegue un singolo container: inizializza lo stato delle conversazioni, avvia il Gateway, quindi genera openclaw mcp serve come processo figlio stdio e lo controlla come client MCP. Verifica il rilevamento delle conversazioni, la lettura delle trascrizioni, la lettura dei metadati degli allegati, il comportamento della coda degli eventi in tempo reale e le notifiche di canale e autorizzazione in stile Claude tramite il bridge MCP stdio reale. L'instradamento degli invii in uscita (messages_send che riutilizza la route della conversazione memorizzata) è trattato separatamente dai test unitari in src/mcp/channel-server.test.ts.

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

Per un contesto più ampio sui test, consultare 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 amministrate da OpenClaw in mcp.servers nella configurazione di OpenClaw. Non leggono i server mcporter da config/mcporter.json.

Le definizioni salvate sono destinate ai runtime che OpenClaw avvia o configura successivamente, come OpenClaw incorporato e altri adattatori di runtime. OpenClaw memorizza le definizioni centralmente, in modo che tali runtime non debbano conservare propri elenchi duplicati di server MCP.

Gli adattatori di runtime possono normalizzare questo registro condiviso nella forma prevista dal client downstream. Ad esempio, OpenClaw incorporato utilizza 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 inoltre un blocco facoltativo codex su ogni server. Si tratta di metadati di proiezione OpenClaw destinati soltanto ai thread di Codex app-server; non modificano le sessioni ACP, la configurazione generica dell'harness Codex o altri adattatori di runtime. Usare un valore codex.agents non vuoto per proiettare un server soltanto in specifici ID agente OpenClaw. Gli elenchi di agenti vuoti, composti da spazi o non validi vengono rifiutati dalla convalida della configurazione e omessi dal percorso di proiezione del runtime anziché diventare globali. Usare codex.defaultToolsApprovalMode (auto, prompt o approve) per emettere il valore nativo default_tools_approval_mode di Codex per un server attendibile. OpenClaw rimuove i metadati codex prima di passare a Codex la configurazione nativa mcp_servers.

Definizioni dei server MCP salvate

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 un nome stampa l'oggetto completo del server MCP configurato.
• status classifica i trasporti configurati senza connettersi. --verbose include i dettagli risolti relativi ad avvio, timeout, OAuth, filtri e chiamate parallele.
• doctor esegue controlli statici senza connettersi. Aggiungere --probe quando il comando deve verificare anche la connessione dei server abilitati.
• probe si connette e segnala il numero di strumenti, il supporto per risorse e prompt, il supporto per le modifiche agli elenchi e la diagnostica.
• add accetta flag stdio come --command, --arg, --env e --cwd, oppure flag HTTP come --url, --transport, --header, --auth oauth, nonché flag TLS, di timeout e di selezione degli strumenti.
• set richiede un singolo valore oggetto JSON nella riga di comando.
• configure aggiorna abilitazione, filtri degli strumenti, timeout, OAuth, TLS e indicazioni sulle chiamate parallele agli strumenti senza sostituire l'intera definizione del server. Aggiungere --probe per verificare il server aggiornato prima del salvataggio.
• tools aggiorna i filtri degli strumenti per server. Le voci di inclusione/esclusione sono nomi di strumenti MCP e semplici glob *.
• login esegue il flusso OAuth per i server HTTP configurati con auth: "oauth". La prima esecuzione stampa un URL di autorizzazione; eseguire nuovamente con --code dopo l'approvazione.
• logout cancella le credenziali OAuth memorizzate per il server indicato senza rimuovere la definizione salvata del server.
• reload elimina i runtime MCP in-process memorizzati nella cache soltanto per il processo CLI corrente. I processi Gateway o agente eseguiti in un altro processo richiedono comunque il proprio percorso di ricaricamento o riavvio.
• Usare transport: "streamable-http" per i server MCP Streamable HTTP. openclaw mcp set normalizza inoltre il valore 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 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

Configurazioni comuni dei server

Questi esempi salvano solo le definizioni dei server. Eseguire successivamente openclaw mcp doctor --probe per verificare che il server si avvii ed esponga gli 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

Strutture dell'output JSON

Utilizzare --json per script e dashboard. Gli insiemi di campi possono aumentare nel tempo, pertanto i client 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": true,  "path": "/home/user/.openclaw/openclaw.json",  "servers": [    {      "name": "docs",      "ok": true,      "issues": [        {          "level": "warning",          "message": "Le credenziali OAuth non sono autorizzate; eseguire 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": []}

Esempio di struttura della 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 (informazioni utente) e headers vengono oscurati nei log e nell'output di stato. openclaw mcp doctor avvisa quando le voci headers o env che sembrano sensibili contengono valori letterali, affinché gli operatori possano spostare tali valori fuori dalla configurazione sottoposta a commit.

Flusso di lavoro OAuth

OAuth è destinato ai server MCP HTTP che dichiarano il supporto del flusso OAuth MCP. Le intestazioni statiche Authorization vengono ignorate per un server quando auth: "oauth" è abilitato. Le credenziali salvate da openclaw mcp login funzionano con MCP integrato, gli esecutori CLI e l'app-server Codex locale.

Finché le credenziali non sono disponibili, OpenClaw omette dal runtime dell'agente solo quel server MCP, anziché causare il fallimento del turno dell'agente. L'operatore, o un agente con accesso alla shell, può quindi eseguire openclaw mcp login <name> e utilizzare il server in un turno successivo.

Quando un servizio MCP remoto è già supportato da un profilo di autenticazione separato di OpenClaw in grado di eseguire l'aggiornamento, è possibile impostare facoltativamente oauth.authProfileId. OpenClaw aggiorna una delle due origini delle credenziali prima della proiezione nel runtime e passa al client MCP a valle solo il token di accesso corrente.

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

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

Trasporto HTTP con streaming

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

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

Esempio:

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

Interfaccia di controllo

L'interfaccia di controllo nel browser include una pagina dedicata alle impostazioni MCP in /settings/mcp; il precedente percorso /mcp rimane un alias. La pagina mostra i conteggi dei server configurati, i riepiloghi di server abilitati, OAuth e filtri, le righe di trasporto per server, i controlli di abilitazione/disabilitazione, i comandi CLI comuni e un editor circoscritto per la sezione di configurazione mcp.

Utilizzare la pagina per le modifiche dell'operatore e un rapido inventario. Utilizzare openclaw mcp doctor --probe o openclaw mcp probe quando è necessaria una verifica attiva del server.

Flusso di lavoro dell'operatore:

1. Aprire l'interfaccia di controllo e scegliere MCP.
2. Esaminare le schede di riepilogo per i server totali, abilitati, OAuth e filtrati.
3. Utilizzare ogni riga del server per indicazioni su trasporto, autenticazione, filtro, timeout e comandi.
4. Attivare o disattivare l'abilitazione quando si desidera mantenere una definizione ma escluderla dal rilevamento in fase di esecuzione.
5. Modificare la sezione di configurazione circoscritta mcp per cambiamenti strutturali come nuovi server, intestazioni, TLS, metadati OAuth o filtri degli strumenti.
6. Scegliere Save per rendere persistente solo la configurazione oppure Save & Publish per applicarla tramite il percorso di configurazione del Gateway.
7. Eseguire openclaw mcp doctor --probe quando è necessaria una verifica attiva 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 rimangano copiabili in una shell
• i valori simili a URL visualizzati 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 del processo che gestisce i client MCP

App MCP

OpenClaw può eseguire il rendering degli strumenti che implementano l'estensione MCP Apps stabile. Le app richiedono l'attivazione esplicita perché il loro HTML proviene dal server MCP configurato e può richiedere strumenti o risorse visibili all'app da quello stesso server.

Abilitare il bridge host:

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

Riavviare il Gateway dopo aver modificato questa impostazione. Quando è abilitato, OpenClaw avvia un listener HTTP(S) riservato alla sandbox sulla porta del Gateway più uno (per il Gateway predefinito, 18790). L'interfaccia di controllo carica le app da questa origine separata; il listener non serve mai l'interfaccia di controllo, le route autenticate del Gateway o i dati utente.

Le connessioni dirette al Gateway devono poter accedere a entrambe le porte. Se un proxy inverso o un terminatore TLS espone l'interfaccia di controllo, assegnare alle app un'origine pubblica dedicata e inoltrare tramite proxy solo tale origine al listener della sandbox:

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

L'origine della sandbox deve essere diversa dall'origine dell'interfaccia di controllo. Non ospitarvi altri contenuti autenticati o sensibili.

Ad esempio, la demo React di base ufficiale può essere configurata come segue:

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

Comportamento e limiti di sicurezza:

• OpenClaw pubblicizza l'estensione io.modelcontextprotocol/ui solo quando le app sono abilitate.
• Vengono visualizzate solo le risorse ui:// con il tipo MIME esatto text/html;profile=mcp-app.
• Le risorse dell'interfaccia utente hanno un limite di 2 MiB, sono collocate dietro un proxy a doppio iframe su un'origine esterna dedicata, caricate in un'origine interna opaca dell'app e vincolate da una CSP derivata dai metadati della risorsa.
• Gli strumenti riservati alle app (_meta.ui.visibility: ["app"]) restano esclusi dagli elenchi degli strumenti del modello. Le app possono chiamare solo strumenti visibili alle app sul server proprietario che superino anche i criteri effettivi di OpenClaw per gli strumenti dell'esecuzione che ha creato la vista.
• Le autorizzazioni delle app associate all'origine, come fotocamera, microfono e geolocalizzazione, non vengono concesse mentre i documenti interni delle app utilizzano origini opache per l'isolamento tra app.
• L'HTML dell'app, gli argomenti completi degli strumenti e i risultati non elaborati risiedono in un lease della vista in memoria, limitato a dieci minuti, e non vengono scritti su disco né copiati nei metadati di anteprima della trascrizione. La trascrizione memorizza solo un descrittore limitato di server, strumento e risorsa associato all'ID originale della chiamata dello strumento. Dopo il riavvio del Gateway, l'interfaccia di controllo può verificare tale descrittore rispetto alla trascrizione della sessione autenticata e recuperare nuovamente la risorsa ui://; le viste ricostruite sono di sola lettura finché una nuova esecuzione non stabilisce le autorizzazioni correnti degli strumenti.
• openclaw security audit mostra un avviso mentre il bridge è abilitato. Disabilitarlo con openclaw config set mcp.apps.enabled false --strict-json quando non è necessario.

Limiti attuali

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

Limiti attuali:

• il rilevamento delle conversazioni dipende dai metadati esistenti delle route di sessione del Gateway
• nessun protocollo push generico oltre all'adattatore specifico per Claude
• non sono ancora disponibili strumenti per modificare i messaggi o aggiungere reazioni
• il trasporto HTTP/SSE/streamable-http si connette a un singolo server remoto; non è ancora disponibile un upstream multiplexato
• permissions_list_open include solo le approvazioni osservate mentre il bridge è connesso

Correlati

• Riferimento della CLI
• Plugin