MCP

• 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

• 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

​

Scegliere il percorso MCP corretto

​

OpenClaw come server MCP

​

Quando usare serve

• 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

​

Come funziona

​

Scegliere una modalità client

​

Cosa espone serve

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

• 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

​

Modello degli eventi

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

​

Notifiche di canale Claude

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

• 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

​

Configurazione del client MCP

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

​

Opzioni

​

Sicurezza e confine di attendibilità

• 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

​

Test

pnpm test:docker:mcp-channels

• 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

​

Risoluzione dei problemi

​

OpenClaw come registro di client MCP

​

Definizioni salvate dei server MCP

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

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

openclaw mcp list
openclaw mcp show context7 --json
openclaw mcp status --verbose
openclaw mcp doctor --probe
openclaw mcp probe context7 --json
openclaw mcp add memory --command npx --arg -y --arg @modelcontextprotocol/server-memory
openclaw 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 docs
openclaw mcp logout docs
openclaw mcp unset context7

​

Ricette comuni per server

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-memory
openclaw 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.example
openclaw 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

{
  "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": []
}

{
  "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

​

Trasporto SSE / HTTP

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

​

Workflow OAuth

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 --verbose
openclaw mcp doctor docs --probe

openclaw mcp logout docs

​

Trasporto HTTP streamable

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

​

UI di controllo

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.

• 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

• 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