CLI commands
MCP
openclaw mcp heeft twee taken:
- OpenClaw als een MCP-server uitvoeren met
openclaw mcp serve - door OpenClaw beheerde definities van uitgaande MCP-servers beheren met
list,show,status,doctor,probe,add,set,configure,tools,login,logout,reloadenunset
Bij serve fungeert OpenClaw als een MCP-server. Bij de andere subopdrachten fungeert OpenClaw als een clientregister voor MCP-servers die de eigen runtimes later kunnen gebruiken.
Gebruik openclaw acp wanneer OpenClaw zelf een sessie voor een programmeerharnas moet hosten en die runtime via ACP moet routeren.
Kies het juiste MCP-pad
| Doel | Gebruik | Waarom |
|---|---|---|
| Een externe MCP-client OpenClaw-kanaalgesprekken laten lezen/verzenden | openclaw mcp serve |
OpenClaw is de MCP-server en stelt door de Gateway ondersteunde gesprekken beschikbaar via stdio. |
| MCP-servers van derden opslaan voor door OpenClaw beheerde agentuitvoeringen | openclaw mcp add, set, configure, tools, login |
OpenClaw is het clientregister voor MCP-servers en projecteert die servers later naar geschikte runtimes. |
| Een opgeslagen server controleren zonder een agentbeurt uit te voeren | openclaw mcp status, doctor, probe |
status en doctor inspecteren de configuratie; probe opent een live MCP-verbinding en vermeldt de mogelijkheden. |
| MCP-configuratie vanuit een browser bewerken | Control UI /settings/mcp (alias /mcp) |
De pagina toont de inventaris, inschakeling, OAuth-/filtersamenvattingen, opdrachthints en een editor met het bereik mcp. |
| Codex app-server een afgebakende native MCP-server geven | mcp.servers.<name>.codex |
Het blok codex beïnvloedt alleen de threadprojectie van Codex app-server en wordt verwijderd voordat de native configuratie wordt doorgegeven. |
| Door ACP gehoste harnassessies uitvoeren | openclaw acp en ACP-agenten |
De ACP-brugmodus accepteert geen injectie van MCP-servers per sessie; configureer in plaats daarvan Gateway-/Plugin-bruggen. |
OpenClaw als een MCP-server
Dit is het pad openclaw mcp serve.
Wanneer serve te gebruiken
Gebruik openclaw mcp serve wanneer:
- Codex, Claude Code of een andere MCP-client rechtstreeks moet communiceren met door OpenClaw ondersteunde kanaalgesprekken
- je al een lokale of externe OpenClaw Gateway met gerouteerde sessies hebt
- je één MCP-server wilt die met alle kanaalbackends van OpenClaw werkt, in plaats van afzonderlijke bruggen per kanaal uit te voeren
Gebruik in plaats daarvan openclaw acp wanneer OpenClaw zelf de programmeerruntime moet hosten en de agentsessie binnen OpenClaw moet houden.
Hoe het werkt
openclaw mcp serve start een stdio-MCP-server. De MCP-client is eigenaar van dat proces. Zolang de client de stdio-sessie openhoudt, maakt de brug via WebSocket verbinding met een lokale of externe OpenClaw Gateway en stelt deze gerouteerde kanaalgesprekken beschikbaar via MCP.
Client start de brug
De MCP-client start openclaw mcp serve.
Brug maakt verbinding met Gateway
De brug maakt via WebSocket verbinding met de OpenClaw Gateway.
Sessies worden MCP-gesprekken
Gerouteerde sessies worden MCP-gesprekken en hulpmiddelen voor transcripties/geschiedenis.
Livegebeurtenissen worden in de wachtrij geplaatst
Livegebeurtenissen worden in het geheugen in de wachtrij geplaatst zolang de brug verbonden is.
Optionele Claude-push
Als de Claude-kanaalmodus is ingeschakeld, kan dezelfde sessie ook Claude-specifieke pushmeldingen ontvangen.
Belangrijk gedrag
- de status van de livewachtrij begint wanneer de brug verbinding maakt
- oudere transcriptiegeschiedenis wordt gelezen met
messages_read - Claude-pushmeldingen bestaan alleen zolang de MCP-sessie actief is
- wanneer de client de verbinding verbreekt, wordt de brug afgesloten en verdwijnt de livewachtrij
- eenmalige agentingangen zoals
openclaw agentenopenclaw infer model runsluiten alle gebundelde MCP-runtimes die ze openen af zodra het antwoord is voltooid, zodat herhaalde gescripte uitvoeringen geen onderliggende stdio-MCP-processen opstapelen - stdio-MCP-servers die door OpenClaw worden gestart (gebundeld of door de gebruiker geconfigureerd), worden bij het afsluiten als een procesboom beëindigd, zodat subprocessen die door de server zijn gestart niet blijven bestaan nadat de bovenliggende stdio-client is afgesloten
- bij het verwijderen of opnieuw instellen van een sessie worden de MCP-clients van die sessie via het gedeelde opschoningspad voor runtimes opgeruimd, zodat er geen achtergebleven stdio-verbindingen aan een verwijderde sessie gekoppeld blijven
Kies een clientmodus
Algemene MCP-clients
Alleen standaard MCP-hulpmiddelen. Gebruik conversations_list, messages_read, events_poll, events_wait, messages_send en de goedkeuringshulpmiddelen.
Claude Code
Standaard MCP-hulpmiddelen plus de Claude-specifieke kanaaladapter. Schakel --claude-channel-mode on in of behoud de standaardwaarde auto.
Wat serve beschikbaar stelt
De brug gebruikt bestaande routeringsmetadata van Gateway-sessies om door kanalen ondersteunde gesprekken beschikbaar te stellen. Een gesprek verschijnt wanneer OpenClaw al een sessiestatus heeft met een bekende route, zoals:
channel- metadata van ontvanger of bestemming
- optionele
accountId - optionele
threadId
Dit biedt MCP-clients één plek om:
- recente gerouteerde gesprekken weer te geven
- recente transcriptiegeschiedenis te lezen
- op nieuwe inkomende gebeurtenissen te wachten
- een antwoord via dezelfde route terug te sturen
- goedkeuringsverzoeken te zien die binnenkomen terwijl de brug verbonden is
Gebruik
Lokale Gateway
openclaw mcp serveExterne Gateway (token)
openclaw mcp serve --url wss://gateway-host:18789 --token-file ~/.openclaw/gateway.tokenExterne Gateway (wachtwoord)
openclaw mcp serve --url wss://gateway-host:18789 --password-file ~/.openclaw/gateway.passwordUitgebreid / Claude uit
openclaw mcp serve --verboseopenclaw mcp serve --claude-channel-mode offBrughulpmiddelen
conversations_list
Geeft recente, door sessies ondersteunde gesprekken weer die al routeringsmetadata in de sessiestatus van de Gateway hebben.
Filters: limit (max. 500), search, channel, includeDerivedTitles, includeLastMessage.
conversation_get
Retourneert één gesprek op basis van session_key via een rechtstreekse zoekactie naar een Gateway-sessie.
messages_read
Leest recente transcriptieberichten voor één door een sessie ondersteund gesprek. limit is standaard 20, maximaal 200.
attachments_fetch
Extraheert niet-tekstuele inhoudsblokken van berichten uit één transcriptiebericht. Dit is een metadataweergave van transcriptie-inhoud, geen zelfstandige duurzame blobopslag voor bijlagen.
events_poll
Leest in de wachtrij geplaatste livegebeurtenissen vanaf een numerieke cursor. limit maximaal 200.
events_wait
Pollt langdurig totdat de volgende overeenkomende gebeurtenis in de wachtrij binnenkomt of een time-out verstrijkt (standaard 30s, maximaal 300s).
Gebruik dit wanneer een algemene MCP-client bijna-realtimelevering nodig heeft zonder een Claude-specifiek pushprotocol.
messages_send
Stuurt tekst terug via dezelfde route die al voor de sessie is vastgelegd.
Huidig gedrag:
- vereist een bestaande gespreksroute
- gebruikt het kanaal, de ontvanger, de account-id en de thread-id van de sessie
- verzendt alleen tekst
permissions_list_open
Geeft openstaande goedkeuringsverzoeken voor exec/Plugin weer die de brug heeft waargenomen sinds deze verbinding maakte met de Gateway.
permissions_respond
Handelt één openstaand goedkeuringsverzoek voor exec/Plugin af met:
allow-onceallow-alwaysdeny
Gebeurtenismodel
De brug houdt een gebeurteniswachtrij in het geheugen bij zolang deze verbonden is.
Huidige gebeurtenistypen:
messageexec_approval_requestedexec_approval_resolvedplugin_approval_requestedplugin_approval_resolvedclaude_permission_request
Claude-kanaalmeldingen
De brug kan ook Claude-specifieke kanaalmeldingen beschikbaar stellen. Dit is het OpenClaw-equivalent van een Claude Code-kanaaladapter: standaard MCP-hulpmiddelen blijven beschikbaar, maar live inkomende berichten kunnen ook binnenkomen als Claude-specifieke MCP-meldingen.
uit
--claude-channel-mode off: alleen standaard MCP-hulpmiddelen.
aan
--claude-channel-mode on: Claude-kanaalmeldingen inschakelen.
automatisch (standaard)
--claude-channel-mode auto: huidige standaardwaarde; hetzelfde bruggedrag als on.
Wanneer de Claude-kanaalmodus is ingeschakeld, kondigt de server experimentele Claude-mogelijkheden aan en kan deze het volgende uitzenden:
notifications/claude/channelnotifications/claude/channel/permission
Huidig gedrag van de brug:
- inkomende
user-transcriptieberichten worden doorgestuurd alsnotifications/claude/channel - Claude-machtigingsverzoeken die via MCP worden ontvangen, worden in het geheugen bijgehouden
- als de opdrachteigenaar in het gekoppelde gesprek later
yes <id>ofno <id>verzendt (<id>is de aanvraag-id van 5 letters, zonderl), zet de brug dit om naarnotifications/claude/channel/permission - deze meldingen gelden alleen voor de live sessie; als de MCP-client de verbinding verbreekt, is er geen pushdoel
Dit is bewust clientspecifiek. Algemene MCP-clients moeten vertrouwen op de standaard pollinghulpmiddelen.
MCP-clientconfiguratie
Voorbeeldconfiguratie voor een stdio-client:
{ "mcpServers": { "openclaw": { "command": "openclaw", "args": [ "mcp", "serve", "--url", "wss://gateway-host:18789", "--token-file", "/path/to/gateway.token" ] } }}Begin voor de meeste generieke MCP-clients met het standaard tooloppervlak en negeer de Claude-modus. Schakel de Claude-modus alleen in voor clients die de Claude-specifieke meldingsmethoden daadwerkelijk begrijpen.
Opties
openclaw mcp serve ondersteunt:
--urlstringWebSocket-URL van de Gateway. Standaard gateway.remote.url wanneer geconfigureerd.
--tokenstringGateway-token.
--token-filestringToken uit bestand lezen.
--passwordstringGateway-wachtwoord.
--password-filestringWachtwoord uit bestand lezen.
--claude-channel-mode"auto" | "on" | "off"Claude-meldingsmodus. Standaard auto.
-v, --verbosebooleanUitgebreide logboeken op stderr.
Beveiligings- en vertrouwensgrens
De bridge verzint geen routering. Deze stelt alleen gesprekken beschikbaar die de Gateway al kan routeren.
Dat betekent:
- toelatingslijsten voor afzenders, koppeling en vertrouwen op kanaalniveau blijven onderdeel van de onderliggende OpenClaw-kanaalconfiguratie
messages_sendkan alleen antwoorden via een bestaande opgeslagen route- de goedkeuringsstatus is alleen live/in het geheugen beschikbaar voor de huidige bridgesessie
- bridge-authenticatie moet dezelfde Gateway-token- of wachtwoordcontroles gebruiken die je voor elke andere externe Gateway-client zou vertrouwen
Als een gesprek in conversations_list ontbreekt, ligt dat doorgaans niet aan de MCP-configuratie. De oorzaak is ontbrekende of onvolledige routeringsmetadata in de onderliggende Gateway-sessie.
Testen
OpenClaw levert een deterministische Docker-rooktest voor deze bridge:
pnpm test:docker:mcp-channelsDie rooktest voert één container uit: de test vult de gespreksstatus, start de Gateway, start vervolgens openclaw mcp serve als een stdio-subproces en stuurt dit aan als MCP-client. De test verifieert gespreksdetectie, het lezen van transcripten, het lezen van bijlagemetadata, het gedrag van de wachtrij voor livegebeurtenissen en kanaal- en toestemmingsmeldingen in Claude-stijl via de echte stdio-MCP-bridge. Routering voor uitgaande verzending (messages_send waarbij de opgeslagen gespreksroute opnieuw wordt gebruikt) wordt afzonderlijk gedekt door unittests in src/mcp/channel-server.test.ts.
Dit is de snelste manier om te bewijzen dat de bridge werkt zonder een echt Telegram-, Discord- of iMessage-account in de testuitvoering op te nemen.
Zie Testen voor een bredere testcontext.
Probleemoplossing
Geen gesprekken geretourneerd
Dit betekent doorgaans dat de Gateway-sessie nog niet routeerbaar is. Controleer of de onderliggende sessie opgeslagen routeringsmetadata bevat voor kanaal/provider, ontvanger en optioneel account/thread.
events_poll of events_wait mist oudere berichten
Dit is te verwachten. De livewachtrij begint wanneer de bridge verbinding maakt. Lees oudere transcriptgeschiedenis met messages_read.
Claude-meldingen verschijnen niet
Controleer al het volgende:
- de client heeft de stdio-MCP-sessie opengehouden
--claude-channel-modeisonofauto- de client begrijpt de Claude-specifieke meldingsmethoden daadwerkelijk
- het inkomende bericht is ontvangen nadat de bridge verbinding maakte
Goedkeuringen ontbreken
permissions_list_open toont alleen goedkeuringsverzoeken die zijn waargenomen terwijl de bridge verbonden was. Het is geen duurzame API voor goedkeuringsgeschiedenis.
OpenClaw als MCP-clientregister
Dit is het pad voor openclaw mcp list, show, status, doctor, probe, add, set,
configure, tools, login, logout, reload en unset.
Deze opdrachten stellen OpenClaw niet via MCP beschikbaar. Ze beheren door OpenClaw beheerde MCP-serverdefinities onder mcp.servers in de OpenClaw-configuratie. Ze lezen geen mcporter-servers uit config/mcporter.json.
Die opgeslagen definities zijn bedoeld voor runtimes die OpenClaw later start of configureert, zoals ingebedde OpenClaw en andere runtime-adapters. OpenClaw slaat de definities centraal op, zodat die runtimes geen eigen dubbele lijsten met MCP-servers hoeven bij te houden.
Belangrijk gedrag
- deze opdrachten lezen of schrijven alleen de OpenClaw-configuratie
status,list,show,doctorzonder--probe,set,configure,tools,logout,reloadenunsetmaken geen verbinding met de doel-MCP-serverloginvoert de MCP OAuth-netwerkstroom uit voor de geconfigureerde HTTP-server en slaat de resulterende lokale aanmeldgegevens opstatus --verbosetoont informatie over het opgeloste transport, de authenticatie, time-out, filters en parallelle toolaanroepen zonder verbinding te makendoctorcontroleert opgeslagen definities op lokale installatieproblemen, zoals ontbrekende stdio-opdrachten, ongeldige werkmappen, ontbrekende TLS-bestanden, uitgeschakelde servers, letterlijke gevoelige header-/omgevingswaarden en onvolledige OAuth-autorisatiedoctor --probevoegt hetzelfde bewijs van een liveverbinding toe alsprobenadat de statische controles zijn geslaagdprobemaakt verbinding met de geselecteerde server of alle geconfigureerde servers, geeft tools weer en rapporteert mogelijkheden/diagnostiekaddbouwt een definitie op uit vlaggen en voert een test uit voordat deze wordt opgeslagen, tenzij--no-probeis ingesteld of eerst OAuth-autorisatie nodig is- runtime-adapters bepalen tijdens de uitvoering welke transportvormen ze daadwerkelijk ondersteunen
enabled: falsehoudt een server opgeslagen, maar sluit deze uit van detectie door de ingebedde runtimetimeoutenconnectTimeoutstellen time-outs per server in seconden in voor verzoeken en verbindingensupportsParallelToolCalls: truemarkeert servers die adapters gelijktijdig kunnen aanroepen- HTTP-servers kunnen statische headers, OAuth-aanmelding, beheer van TLS-verificatie en paden naar mTLS-certificaten/-sleutels gebruiken
- ingebedde OpenClaw stelt geconfigureerde MCP-tools beschikbaar in normale toolprofielen voor
codingenmessaging;minimalverbergt ze nog steeds entools.deny: ["bundle-mcp"]schakelt ze expliciet uit toolFilter.includeentoolFilter.excludeper server filteren gedetecteerde MCP-tools voordat ze OpenClaw-tools worden- servers die resources of prompts adverteren, stellen ook hulptools beschikbaar voor het weergeven/lezen van resources en het weergeven/ophalen van prompts; die gegenereerde hulpnamen (
resources_list,resources_read,prompts_list,prompts_get) gebruiken hetzelfde insluitings-/uitsluitingsfilter - dynamische wijzigingen in de MCP-toollijst maken de gecachte catalogus voor die sessie ongeldig; bij de volgende detectie/het volgende gebruik wordt deze vanaf de server vernieuwd
- herhaalde fouten bij MCP-toolrequests of in het protocol onderbreken die server kortstondig, zodat één defecte server niet de hele beurt verbruikt
- sessiegebonden gebundelde MCP-runtimes worden na
mcp.sessionIdleTtlMsmilliseconden inactiviteit opgeruimd (standaard 10 minuten; stel0in om dit uit te schakelen) en eenmalige ingebedde uitvoeringen ruimen ze aan het einde van de uitvoering op
Runtime-adapters kunnen dit gedeelde register normaliseren naar de vorm die hun downstreamclient verwacht. Ingebedde OpenClaw gebruikt bijvoorbeeld rechtstreeks OpenClaw-waarden voor transport, terwijl Claude Code en Gemini CLI-eigen waarden voor type ontvangen, zoals http, sse of stdio.
Codex-app-server respecteert ook een optioneel codex-blok op elke server. Dit is
OpenClaw-projectiemetadata, uitsluitend voor Codex-app-serverthreads; deze wijzigt geen
ACP-sessies, generieke Codex-harnasconfiguratie of andere runtime-adapters.
Gebruik een niet-lege codex.agents om een server alleen naar specifieke OpenClaw-
agent-id's te projecteren. Lege, blanco of ongeldige agentlijsten worden door de configuratie-
validatie geweigerd en door het runtimeprojectiepad weggelaten in plaats van
globaal te worden. Gebruik codex.defaultToolsApprovalMode (auto, prompt of approve)
om de native default_tools_approval_mode van Codex voor een vertrouwde server uit te voeren.
OpenClaw verwijdert de codex-metadata voordat de native mcp_servers-
configuratie aan Codex wordt doorgegeven.
Opgeslagen MCP-serverdefinities
Opdrachten:
openclaw mcp listopenclaw 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 reloadopenclaw mcp unset <name>
Opmerkingen:
listsorteert servernamen.showzonder naam toont het volledige geconfigureerde MCP-serverobject.statusclassificeert geconfigureerde transporten zonder verbinding te maken.--verbosebevat opgeloste details over starten, time-outs, OAuth, filters en parallelle aanroepen.doctorvoert statische controles uit zonder verbinding te maken. Voeg--probetoe wanneer de opdracht ook moet verifiëren dat ingeschakelde servers verbinding maken.probemaakt verbinding en rapporteert aantallen tools, ondersteuning voor resources/prompts, ondersteuning voor lijstwijzigingen en diagnostiek.addaccepteert stdio-vlaggen zoals--command,--arg,--enven--cwd, of HTTP-vlaggen zoals--url,--transport,--header,--auth oauth, TLS-, time-out- en toolselectievlaggen.setverwacht één JSON-objectwaarde op de opdrachtregel.configurewerkt de inschakeling, toolfilters, time-outs, OAuth, TLS en informatie voor parallelle toolaanroepen bij zonder de volledige serverdefinitie te vervangen. Voeg--probetoe om de bijgewerkte server te verifiëren voordat deze wordt opgeslagen.toolswerkt toolfilters per server bij. Insluitings-/uitsluitingsvermeldingen zijn MCP-toolnamen en eenvoudige*-globpatronen.loginvoert de OAuth-stroom uit voor HTTP-servers die metauth: "oauth"zijn geconfigureerd. De eerste uitvoering toont een autorisatie-URL; voer de opdracht na goedkeuring opnieuw uit met--code.logoutwist opgeslagen OAuth-aanmeldgegevens voor de genoemde server zonder de opgeslagen serverdefinitie te verwijderen.reloadverwijdert gecachte MCP-runtimes in het proces alleen voor het huidige CLI-proces. Gateway- of agentprocessen in een ander proces hebben nog steeds hun eigen herlaad- of herstartpad nodig.- Gebruik
transport: "streamable-http"voor Streamable HTTP MCP-servers.openclaw mcp setnormaliseert voor compatibiliteit ook de CLI-eigentype: "http"naar dezelfde canonieke configuratievorm. unsetmislukt als de genoemde server niet bestaat.
Voorbeelden:
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 context7Veelgebruikte serverrecepten
Deze voorbeelden slaan alleen serverdefinities op. Voer daarna openclaw mcp doctor --probe uit om te verifiëren dat de server start en tools beschikbaar stelt.
Bestandssysteem
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 --probeBeperk bestandssysteemservers tot de kleinste mappenstructuur die de agent moet kunnen lezen of bewerken.
Geheugen
openclaw mcp add memory \ --command npx \ --arg -y \ --arg @modelcontextprotocol/server-memoryopenclaw mcp probe memory --jsonGebruik een toolfilter als de server schrijftools beschikbaar stelt die niet toegankelijk mogen zijn voor normale agents.
Lokaal script
openclaw mcp add local-tools \ --command node \ --arg ./dist/mcp-server.js \ --cwd /srv/openclaw-tools \ --env API_BASE=https://internal.exampleopenclaw mcp status --verbosedoctor controleert of cwd bestaat en of de opdracht vanuit de geconfigureerde omgeving kan worden gevonden.
Externe HTTP
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 --probeGebruik OAuth wanneer de externe server dit ondersteunt. Als de server statische headers vereist, leg letterlijke bearertokens dan niet vast in een commit.
Desktop/CUA
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 --probeServers voor directe desktopbesturing nemen de machtigingen over van het proces dat ze starten. Gebruik beperkte toolfilters en machtigingsprompts op besturingssysteemniveau.
Structuren van JSON-uitvoer
Gebruik --json voor scripts en dashboards. Verzamelingen velden kunnen in de loop van de tijd groeien, dus consumers moeten onbekende sleutels negeren.
status --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 } ]}doctor --json
{ "ok": true, "path": "/home/user/.openclaw/openclaw.json", "servers": [ { "name": "docs", "ok": true, "issues": [ { "level": "warning", "message": "OAuth-referenties zijn niet geautoriseerd; voer openclaw mcp login docs uit" } ] } ]}doctor --json wordt afgesloten met een niet-nulstatus wanneer een ingeschakelde, gecontroleerde server een probleem op error-niveau heeft. Problemen van het type warning en info worden gemeld, maar zorgen er op zichzelf niet voor dat de opdracht mislukt.
probe --json
{ "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": []}probe --json opent een live MCP-clientsessie en drukt het resultaat rechtstreeks af; anders dan bij status/doctor heeft de uitvoer geen path-veld op het hoogste niveau. De sleutels resources en prompts zijn alleen aanwezig wanneer de server die mogelijkheid daadwerkelijk adverteert (een server zonder prompts laat de sleutel prompts weg in plaats van false te rapporteren). Gebruik probe als bewijs van bereikbaarheid en mogelijkheden, niet voor controles van statische configuratie.
Voorbeeld van een configuratiestructuur:
{ "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_*"] } } } }}Stdio-transport
Start een lokaal onderliggend proces en communiceert via stdin/stdout.
| Veld | Beschrijving |
|---|---|
command |
Uitvoerbaar bestand om te starten (vereist) |
args |
Reeks opdrachtregelargumenten |
env |
Extra omgevingsvariabelen |
cwd / workingDirectory |
Werkmap voor het proces |
SSE-/HTTP-transport
Maakt via HTTP Server-Sent Events verbinding met een externe MCP-server.
| Veld | Beschrijving |
|---|---|
url |
HTTP- of HTTPS-URL van de externe server (vereist) |
headers |
Optionele sleutel-waardetoewijzing van HTTP-headers (bijvoorbeeld auth-tokens) |
connectionTimeoutMs |
Verbindingstime-out per server in ms (optioneel) |
connectTimeout |
Verbindingstime-out per server in seconden (optioneel) |
timeout / requestTimeoutMs |
Time-out voor MCP-verzoeken per server in seconden of ms |
auth: "oauth" |
Gebruik MCP-OAuth-referenties die door openclaw mcp login zijn opgeslagen |
sslVerify |
Stel alleen in op false voor expliciet vertrouwde privé-HTTPS-eindpunten |
clientCert / clientKey |
Paden naar mTLS-clientcertificaat en -sleutel |
supportsParallelToolCalls |
Aanwijzing dat gelijktijdige aanroepen veilig zijn voor deze server |
Voorbeeld:
{ "mcp": { "servers": { "remote-tools": { "url": "https://mcp.example.com", "auth": "oauth", "timeout": 20, "headers": { "Authorization": "Bearer <token>" } } } }}Gevoelige waarden in url (gebruikersinfo) en headers worden in logboeken en statusuitvoer geredigeerd. openclaw mcp doctor waarschuwt wanneer headers- of env-items die gevoelig lijken letterlijke waarden bevatten, zodat operators die waarden uit vastgelegde configuratie kunnen verwijderen.
OAuth-workflow
OAuth is bedoeld voor HTTP-MCP-servers die de MCP-OAuth-stroom adverteren. Statische Authorization-headers worden voor een server genegeerd zolang auth: "oauth" is ingeschakeld. Referenties die door openclaw mcp login zijn opgeslagen, werken met ingebedde MCP, CLI-runners en de lokale Codex-appserver.
Totdat referenties beschikbaar zijn, laat OpenClaw alleen die MCP-server weg uit de agentruntime, in plaats van de agentbeurt te laten mislukken. De operator, of een agent met shelltoegang, kan vervolgens openclaw mcp login <name> uitvoeren en de server tijdens een latere beurt gebruiken.
Wanneer een externe MCP-service al wordt ondersteund door een afzonderlijk OpenClaw-auth-profiel dat kan vernieuwen, kun je optioneel oauth.authProfileId instellen. OpenClaw vernieuwt een van beide bronnen van referenties vóór de runtimeprojectie en geeft alleen het huidige toegangstoken door aan de onderliggende MCP-client.
De server opslaan
Voeg de server toe of werk deze bij met auth: "oauth" en eventuele optionele OAuth-metagegevens.
openclaw mcp set docs '{"url":"https://mcp.example.com/mcp","transport":"streamable-http","auth":"oauth","oauth":{"scope":"docs.read"}}'Sla voor een bearer die door een auth-profiel wordt ondersteund de profielkoppeling op:
openclaw mcp set docs '{"url":"https://mcp.example.com/mcp","transport":"streamable-http","auth":"oauth","oauth":{"authProfileId":"docs:mcp"}}'Aanmelden starten
Voer de aanmelding uit om het autorisatieverzoek te maken.
openclaw mcp login docsOpenClaw drukt de autorisatie-URL af en slaat de tijdelijke OAuth-verificatiestatus op in de OpenClaw-statusmap.
Voltooien met de code
Nadat je in de browser toestemming hebt gegeven, geef je de geretourneerde code terug aan OpenClaw.
openclaw mcp login docs --code abc123Autorisatie controleren
Gebruik status of doctor om te bevestigen dat tokens aanwezig zijn.
openclaw mcp status --verboseopenclaw mcp doctor docs --probeReferenties wissen
Uitloggen verwijdert opgeslagen OAuth-referenties, maar behoudt de opgeslagen serverdefinitie.
openclaw mcp logout docsAls de provider tokens roteert of de autorisatiestatus vastloopt, voer je openclaw mcp logout <name> uit en herhaal je vervolgens login. logout kan referenties voor een opgeslagen HTTP-server wissen, zelfs nadat auth: "oauth" uit de configuratie is verwijderd, zolang de servernaam en URL de vermelding in de referentieopslag nog steeds identificeren.
Streamable HTTP-transport
streamable-http is een aanvullende transportoptie naast sse en stdio. Deze gebruikt HTTP-streaming voor bidirectionele communicatie met externe MCP-servers.
| Veld | Beschrijving |
|---|---|
url |
HTTP- of HTTPS-URL van de externe server (vereist) |
transport |
Stel in op "streamable-http" om dit transport te selecteren; indien weggelaten gebruikt OpenClaw sse |
headers |
Optionele sleutel-waardetoewijzing van HTTP-headers (bijvoorbeeld authenticatietokens) |
connectionTimeoutMs |
Verbindingstime-out per server in ms (optioneel) |
connectTimeout |
Verbindingstime-out per server in seconden (optioneel) |
timeout / requestTimeoutMs |
Time-out voor MCP-verzoeken per server in seconden of ms |
auth: "oauth" |
Gebruik MCP OAuth-referenties die zijn opgeslagen door openclaw mcp login |
sslVerify |
Stel alleen in op false voor expliciet vertrouwde privé-HTTPS-eindpunten |
clientCert / clientKey |
Paden naar het mTLS-clientcertificaat en de sleutel |
supportsParallelToolCalls |
Geeft aan dat gelijktijdige aanroepen veilig zijn voor deze server |
De OpenClaw-configuratie gebruikt transport: "streamable-http" als de canonieke spelling. CLI-native MCP-waarden voor type: "http" worden geaccepteerd wanneer ze via openclaw mcp set worden opgeslagen en worden door openclaw doctor --fix in bestaande configuraties hersteld, maar transport is wat het ingebedde OpenClaw rechtstreeks gebruikt.
Voorbeeld:
{ "mcp": { "servers": { "streaming-tools": { "url": "https://mcp.example.com/stream", "transport": "streamable-http", "connectTimeout": 10, "timeout": 30, "headers": { "Authorization": "Bearer <token>" } } } }}Control UI
De Control UI in de browser bevat een speciale pagina met MCP-instellingen op /settings/mcp; het eerdere pad /mcp blijft als alias bestaan. De pagina toont aantallen geconfigureerde servers, samenvattingen van ingeschakelde servers, OAuth en filters, transportrijen per server, bedieningselementen om servers in of uit te schakelen, algemene CLI-opdrachten en een editor met een beperkt bereik voor de configuratiesectie mcp.
Gebruik de pagina voor wijzigingen door operators en een snel overzicht. Gebruik openclaw mcp doctor --probe of openclaw mcp probe wanneer je live bewijs van de server nodig hebt.
Werkstroom voor operators:
- Open de Control UI en kies MCP.
- Bekijk de overzichtskaarten voor het totale aantal, ingeschakelde servers, OAuth en gefilterde servers.
- Gebruik elke serverrij voor informatie over transport, authenticatie, filters, time-outs en opdrachten.
- Schakel de server in of uit wanneer je een definitie wilt behouden maar deze van runtime-detectie wilt uitsluiten.
- Bewerk de configuratiesectie
mcpmet beperkt bereik voor structurele wijzigingen, zoals nieuwe servers, headers, TLS, OAuth-metadata of toolfilters. - Kies Save om alleen de configuratie op te slaan, of Save & Publish om deze via het configuratiepad van de Gateway toe te passen.
- Voer
openclaw mcp doctor --probeuit wanneer je live bewijs nodig hebt dat de bewerkte server start en tools weergeeft.
Opmerkingen:
- opdrachtfragmenten plaatsen servernamen tussen aanhalingstekens, zodat ongebruikelijke namen in een shell kopieerbaar blijven
- weergegeven URL-achtige waarden worden vóór het renderen geredigeerd wanneer ze ingesloten referenties bevatten
- de pagina start zelf geen MCP-transporten
- actieve runtimes hebben mogelijk
openclaw mcp reload, publicatie van de Gateway-configuratie of een herstart van het proces nodig, afhankelijk van welk proces eigenaar is van de MCP-clients
MCP Apps
OpenClaw kan tools renderen die de stabiele MCP Apps-extensie implementeren. Apps zijn opt-in, omdat hun HTML afkomstig is van de geconfigureerde MCP-server en zij vanaf diezelfde server om voor de app zichtbare tools of resources kunnen vragen.
Schakel de hostbridge in:
openclaw config set mcp.apps.enabled true --strict-jsonHerstart de Gateway nadat je deze instelling hebt gewijzigd. Wanneer deze is ingeschakeld, start OpenClaw een HTTP(S)-listener die uitsluitend voor de sandbox is bedoeld, op de Gateway-poort plus één (voor de standaard-Gateway: 18790). De Control UI laadt Apps vanaf die afzonderlijke origin; de listener biedt nooit de Control UI, geauthenticeerde Gateway-routes of gebruikersgegevens aan.
Directe Gateway-verbindingen hebben toegang tot beide poorten nodig. Als een reverse proxy of TLS-terminator de Control UI beschikbaar stelt, geef Apps dan een eigen openbare origin en stuur alleen die origin via een proxy door naar de sandboxlistener:
{ mcp: { apps: { enabled: true, sandboxOrigin: "https://mcp-apps.example.com", sandboxPort: 18790, }, },}De sandbox-origin moet verschillen van de origin van de Control UI. Host daarop geen andere geauthenticeerde of gevoelige inhoud.
De officiële eenvoudige React-demo kan bijvoorbeeld als volgt worden geconfigureerd:
{ mcp: { apps: { enabled: true }, servers: { "basic-react": { command: "npx", args: ["-y", "@modelcontextprotocol/server-basic-react", "--stdio"], }, }, },}Gedrag en beveiligingsgrenzen:
- OpenClaw kondigt de extensie
io.modelcontextprotocol/uialleen aan wanneer Apps zijn ingeschakeld. - Alleen resources van
ui://met exact het MIME-typetext/html;profile=mcp-appworden gerenderd. - UI-resources zijn beperkt tot 2 MiB, worden achter een dubbele iframe-proxy op een afzonderlijke buitenste origin geplaatst, in een ondoorzichtige binnenste App-origin geladen en beperkt door een CSP die is afgeleid van de resourcemetadata.
- Tools die uitsluitend voor Apps zijn bedoeld (
_meta.ui.visibility: ["app"]), blijven buiten de lijst met modeltools. Apps kunnen alleen voor de app zichtbare tools op hun eigen server aanroepen die ook voldoen aan het effectieve OpenClaw-toolbeleid voor de uitvoering die de weergave heeft gemaakt. - Aan een origin gebonden App-machtigingen, zoals camera, microfoon en geolocatie, worden niet verleend zolang binnenste App-documenten ondoorzichtige origins gebruiken voor isolatie tussen Apps.
- App-HTML, volledige toolargumenten en onbewerkte resultaten bevinden zich in een begrensde weergavelease van tien minuten in het geheugen en worden niet naar schijf geschreven of naar metadata voor transcriptvoorbeelden gekopieerd. Het transcript slaat alleen een begrensde server-, tool- en resourcebeschrijving op die aan de oorspronkelijke toolaanroep-ID is gekoppeld. Na een herstart van de Gateway kan de Control UI die beschrijving verifiëren aan de hand van het geauthenticeerde sessietranscript en de resource
ui://opnieuw ophalen; gereconstrueerde weergaven zijn alleen-lezen totdat een nieuwe uitvoering actuele toolmachtigingen vastlegt. openclaw security auditwaarschuwt zolang de bridge is ingeschakeld. Schakel deze uit metopenclaw config set mcp.apps.enabled false --strict-jsonwanneer deze niet nodig is.
Huidige beperkingen
Deze pagina documenteert de bridge zoals die momenteel wordt geleverd.
Huidige beperkingen:
- gespreksdetectie is afhankelijk van bestaande routemetadata van Gateway-sessies
- geen generiek pushprotocol naast de Claude-specifieke adapter
- nog geen tools voor het bewerken van berichten of het toevoegen van reacties
- HTTP/SSE/streamable-http-transport maakt verbinding met één externe server; nog geen gemultiplexte upstream
permissions_list_openbevat alleen goedkeuringen die zijn waargenomen terwijl de bridge verbonden is