MCP

openclaw mcp ma dwa zadania:

• uruchamiać OpenClaw jako serwer MCP za pomocą openclaw mcp serve
• zarządzać definicjami wychodzących serwerów MCP zarządzanych przez OpenClaw za pomocą list, show, status, doctor, probe, add, set, configure, tools, login, logout, reload i unset

Innymi słowy:

• serve to OpenClaw działający jako serwer MCP
• pozostałe podpolecenia to OpenClaw działający jako rejestr po stronie klienta MCP dla serwerów MCP, z których jego środowiska uruchomieniowe mogą korzystać później

Użyj openclaw acp, gdy OpenClaw ma sam hostować sesję środowiska kodowania i kierować to środowisko uruchomieniowe przez ACP.

Wybierz właściwą ścieżkę MCP

OpenClaw ma kilka powierzchni MCP. Wybierz tę, która pasuje do właściciela środowiska uruchomieniowego agenta i właściciela narzędzi.

OpenClaw jako serwer MCP

To jest ścieżka openclaw mcp serve.

Kiedy używać serve

Użyj openclaw mcp serve, gdy:

• Codex, Claude Code lub inny klient MCP ma komunikować się bezpośrednio z konwersacjami kanałów opartymi na OpenClaw
• masz już lokalny lub zdalny OpenClaw Gateway z routowanymi sesjami
• chcesz jednego serwera MCP działającego z backendami kanałów OpenClaw zamiast uruchamiania osobnych mostów dla każdego kanału

Użyj zamiast tego openclaw acp, gdy OpenClaw ma hostować samo środowisko uruchomieniowe kodowania i utrzymywać sesję agenta wewnątrz OpenClaw.

Jak to działa

openclaw mcp serve uruchamia serwer MCP stdio. Klient MCP jest właścicielem tego procesu. Dopóki klient utrzymuje otwartą sesję stdio, most łączy się z lokalnym lub zdalnym OpenClaw Gateway przez WebSocket i udostępnia routowane konwersacje kanałów przez MCP.

Wybierz tryb klienta

Użyj tego samego mostu na dwa różne sposoby:

Co udostępnia serve

Most używa istniejących metadanych tras sesji Gateway, aby udostępniać konwersacje oparte na kanałach. Konwersacja pojawia się, gdy OpenClaw ma już stan sesji ze znaną trasą, taką jak:

• channel
• metadane odbiorcy lub miejsca docelowego
• opcjonalne accountId
• opcjonalne threadId

Daje to klientom MCP jedno miejsce do:

• wyświetlania ostatnich routowanych konwersacji
• odczytywania najnowszej historii transkrypcji
• oczekiwania na nowe zdarzenia przychodzące
• wysyłania odpowiedzi z powrotem przez tę samą trasę
• oglądania żądań zatwierdzenia, które przychodzą, gdy most jest połączony

Użycie

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

Narzędzia mostu

Obecny most udostępnia te narzędzia MCP:

Model zdarzeń

Most utrzymuje kolejkę zdarzeń w pamięci, gdy jest połączony.

Obecne typy zdarzeń:

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

Powiadomienia kanału Claude

Most może też udostępniać powiadomienia kanału specyficzne dla Claude. To odpowiednik adaptera kanału Claude Code w OpenClaw: standardowe narzędzia MCP pozostają dostępne, ale przychodzące wiadomości na żywo mogą też docierać jako powiadomienia MCP specyficzne dla Claude.

Gdy tryb kanału Claude jest włączony, serwer ogłasza eksperymentalne możliwości Claude i może emitować:

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

Obecne zachowanie mostu:

• przychodzące wiadomości transkrypcji user są przekazywane jako notifications/claude/channel
• żądania uprawnień Claude otrzymane przez MCP są śledzone w pamięci
• jeśli właściciel polecenia w połączonej konwersacji wyśle później yes abcde lub no abcde, most konwertuje to na notifications/claude/channel/permission
• te powiadomienia działają tylko w sesji na żywo; jeśli klient MCP się rozłączy, nie ma celu push

To celowo jest specyficzne dla klienta. Ogólni klienci MCP powinni polegać na standardowych narzędziach odpytywania.

Konfiguracja klienta MCP

Przykładowa konfiguracja klienta stdio:

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

W przypadku większości ogólnych klientów MCP zacznij od standardowej powierzchni narzędzi i ignoruj tryb Claude. Włącz tryb Claude tylko dla klientów, które faktycznie rozumieją metody powiadomień specyficzne dla Claude.

Opcje

openclaw mcp serve obsługuje:

Bezpieczeństwo i granica zaufania

Mostek nie wymyśla routingu. Udostępnia tylko rozmowy, które Gateway już potrafi routować.

Oznacza to, że:

• listy dozwolonych nadawców, parowanie i zaufanie na poziomie kanału nadal należą do bazowej konfiguracji kanału OpenClaw
• messages_send może odpowiadać tylko przez istniejącą zapisaną trasę
• stan zatwierdzeń jest żywy i przechowywany wyłącznie w pamięci dla bieżącej sesji mostka
• uwierzytelnianie mostka powinno używać tych samych mechanizmów tokenu lub hasła Gateway, którym zaufałbyś dla dowolnego innego zdalnego klienta Gateway

Jeśli rozmowy brakuje w conversations_list, zwykle przyczyną nie jest konfiguracja MCP. To brakujące lub niekompletne metadane trasy w bazowej sesji Gateway.

Testowanie

OpenClaw dostarcza deterministyczny smoke test Docker dla tego mostka:

pnpm test:docker:mcp-channels

Ten smoke test:

• uruchamia kontener Gateway z danymi początkowymi
• uruchamia drugi kontener, który wywołuje openclaw mcp serve
• weryfikuje wykrywanie rozmów, odczyty transkrypcji, odczyty metadanych załączników, działanie kolejki zdarzeń na żywo i routing wysyłania wychodzącego
• waliduje powiadomienia kanałów i uprawnień w stylu Claude przez rzeczywisty mostek MCP stdio

To najszybszy sposób, aby potwierdzić, że mostek działa bez podłączania prawdziwego konta Telegram, Discord lub iMessage do uruchomienia testu.

Szerszy kontekst testowania znajdziesz w Testowanie.

Rozwiązywanie problemów

OpenClaw jako rejestr klienta MCP

To ścieżka openclaw mcp list, show, status, doctor, probe, add, set, configure, tools, login, logout, reload i unset.

Te polecenia nie udostępniają OpenClaw przez MCP. Zarządzają definicjami serwerów MCP zarządzanymi przez OpenClaw w mcp.servers w konfiguracji OpenClaw. Nie odczytują serwerów mcporter z config/mcporter.json.

Te zapisane definicje są przeznaczone dla środowisk uruchomieniowych, które OpenClaw uruchamia lub konfiguruje później, takich jak osadzony OpenClaw i inne adaptery środowiska uruchomieniowego. OpenClaw przechowuje definicje centralnie, aby te środowiska nie musiały utrzymywać własnych zduplikowanych list serwerów MCP.

Adaptery środowiska uruchomieniowego mogą normalizować ten współdzielony rejestr do kształtu oczekiwanego przez ich klienta podrzędnego. Na przykład osadzony OpenClaw zużywa wartości transport OpenClaw bezpośrednio, podczas gdy Claude Code i Gemini otrzymują natywne dla CLI wartości type, takie jak http, sse lub stdio.

Codex app-server honoruje także opcjonalny blok codex na każdym serwerze. To są metadane projekcji OpenClaw wyłącznie dla wątków Codex app-server; nie zmieniają sesji ACP, ogólnej konfiguracji uprzęży Codex ani innych adapterów środowiska uruchomieniowego. Użyj niepustego codex.agents, aby rzutować serwer tylko do określonych identyfikatorów agentów OpenClaw. Puste, blank lub nieprawidłowe listy agentów są odrzucane przez walidację konfiguracji i pomijane przez ścieżkę projekcji środowiska uruchomieniowego, zamiast stawać się globalne. Użyj codex.defaultToolsApprovalMode (auto, prompt lub approve), aby wyemitować natywne default_tools_approval_mode Codex dla zaufanego serwera. OpenClaw usuwa metadane codex przed przekazaniem natywnej konfiguracji mcp_servers do Codex.

Zapisane definicje serwerów MCP

OpenClaw przechowuje też w konfiguracji lekki rejestr serwerów MCP dla powierzchni, które chcą definicji MCP zarządzanych przez OpenClaw.

Polecenia:

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

Uwagi:

• list sortuje nazwy serwerów.
• show bez nazwy wypisuje pełny skonfigurowany obiekt serwera MCP.
• status klasyfikuje skonfigurowane transporty bez łączenia się. --verbose zawiera rozstrzygnięte szczegóły uruchomienia, limitów czasu, OAuth, filtra i wywołań równoległych.
• doctor wykonuje kontrole statyczne bez łączenia się. Dodaj --probe, gdy polecenie powinno też zweryfikować, że włączone serwery się łączą.
• probe łączy się i raportuje liczby narzędzi, obsługę zasobów/promptów, obsługę zmian listy oraz diagnostykę.
• add akceptuje flagi stdio, takie jak --command, --arg, --env i --cwd, albo flagi HTTP, takie jak --url, --transport, --header, --auth oauth, TLS, limit czasu i flagi wyboru narzędzi.
• set oczekuje jednej wartości obiektu JSON w wierszu poleceń.
• configure aktualizuje włączenie, filtry narzędzi, limity czasu, OAuth, TLS i wskazówki równoległych wywołań narzędzi bez zastępowania całej definicji serwera.
• tools aktualizuje filtry narzędzi dla serwera. Wpisy include/exclude to nazwy narzędzi MCP i proste globy *.
• login uruchamia przepływ OAuth dla serwerów HTTP skonfigurowanych z auth: "oauth". Pierwsze uruchomienie wypisuje adres URL autoryzacji; uruchom ponownie z --code po zatwierdzeniu.
• logout czyści zapisane dane logowania OAuth dla wskazanego serwera bez usuwania zapisanej definicji serwera.
• reload usuwa zbuforowane wewnątrzprocesowe środowiska uruchomieniowe MCP. Procesy Gateway lub agenta w innym procesie nadal potrzebują własnej ścieżki przeładowania lub restartu.
• Użyj transport: "streamable-http" dla serwerów Streamable HTTP MCP. openclaw mcp set normalizuje też natywne dla CLI type: "http" do tego samego kanonicznego kształtu konfiguracji dla zgodności.
• unset kończy się niepowodzeniem, jeśli wskazany serwer nie istnieje.

Przykłady:

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

Typowe przepisy serwerów

Te przykłady zapisują tylko definicje serwerów. Następnie uruchom openclaw mcp doctor --probe, aby potwierdzić, że serwer startuje i udostępnia narzędzia.

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

Kształty wyjścia JSON

Używaj --json dla skryptów i pulpitów. Zestawy pól mogą z czasem rosnąć, więc konsumenci powinni ignorować nieznane klucze.

{  "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": "OAuth credentials are not authorized; run 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": []}

Przykładowy kształt konfiguracji:

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

Transport stdio

Uruchamia lokalny proces potomny i komunikuje się przez stdin/stdout.

Transport SSE / HTTP

Łączy się ze zdalnym serwerem MCP przez HTTP Server-Sent Events.

Przykład:

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

Wartości wrażliwe w url (userinfo) i headers są redagowane w logach i wyjściu statusu. openclaw mcp doctor ostrzega, gdy wyglądające na wrażliwe wpisy headers lub env zawierają dosłowne wartości, aby operatorzy mogli przenieść te wartości poza commitowaną konfigurację.

Przepływ pracy OAuth

OAuth jest przeznaczony dla serwerów MCP HTTP, które ogłaszają przepływ OAuth MCP. Statyczne nagłówki Authorization są ignorowane dla serwera, gdy włączone jest auth: "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 --verboseopenclaw mcp doctor docs --probe

openclaw mcp logout docs

Jeśli dostawca rotuje tokeny lub stan autoryzacji się zablokuje, uruchom openclaw mcp logout <name>, a następnie powtórz login. logout może wyczyścić poświadczenia dla zapisanego serwera HTTP nawet po usunięciu auth: "oauth" z konfiguracji, o ile nazwa serwera i URL nadal identyfikują wpis magazynu poświadczeń.

Transport Streamable HTTP

streamable-http to dodatkowa opcja transportu obok sse i stdio. Używa strumieniowania HTTP do dwukierunkowej komunikacji ze zdalnymi serwerami MCP.

Konfiguracja OpenClaw używa transport: "streamable-http" jako kanonicznej pisowni. Natywne dla CLI wartości MCP type: "http" są akceptowane przy zapisie przez openclaw mcp set i naprawiane przez openclaw doctor --fix w istniejącej konfiguracji, ale transport jest tym, co osadzony OpenClaw zużywa bezpośrednio.

Przykład:

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

Control UI

Przeglądarkowy Control UI zawiera dedykowaną stronę ustawień MCP pod adresem /mcp. Pokazuje liczbę skonfigurowanych serwerów, podsumowania włączenia/OAuth/filtrów, wiersze transportu dla poszczególnych serwerów, kontrolki włączania/wyłączania, typowe polecenia CLI oraz edytor zakresowy dla sekcji konfiguracji mcp.

Używaj tej strony do edycji operatorskich i szybkiej inwentaryzacji. Użyj openclaw mcp doctor --probe lub openclaw mcp probe, gdy potrzebujesz aktywnego potwierdzenia serwera.

Przepływ pracy operatora:

1. Otwórz Control UI i wybierz MCP.
2. Przejrzyj karty podsumowania dla łącznej liczby serwerów, serwerów włączonych, OAuth i odfiltrowanych.
3. Użyj każdego wiersza serwera, aby sprawdzić transport, uwierzytelnianie, filtr, limit czasu i podpowiedzi poleceń.
4. Przełącz włączenie, gdy chcesz zachować definicję, ale wykluczyć ją z wykrywania w czasie działania.
5. Edytuj sekcję konfiguracji mcp o określonym zakresie dla zmian strukturalnych, takich jak nowe serwery, nagłówki, TLS, metadane OAuth lub filtry narzędzi.
6. Wybierz Zapisz, aby tylko utrwalić konfigurację, albo Zapisz i opublikuj, aby zastosować ją przez ścieżkę konfiguracji Gateway.
7. Uruchom openclaw mcp doctor --probe, gdy potrzebujesz dowodu na żywo, że edytowany serwer uruchamia się i wyświetla narzędzia.

Uwagi:

• fragmenty poleceń ujmują nazwy serwerów w cudzysłowy, aby nietypowe nazwy nadal można było skopiować do powłoki
• wyświetlane wartości podobne do URL-i są redagowane przed renderowaniem, gdy zawierają osadzone dane uwierzytelniające
• strona sama nie uruchamia transportów MCP
• aktywne środowiska uruchomieniowe mogą wymagać openclaw mcp reload, opublikowania konfiguracji Gateway lub restartu procesu, zależnie od tego, który proces jest właścicielem klientów MCP

Bieżące ograniczenia

Ta strona dokumentuje most w postaci dostarczanej obecnie.

Bieżące ograniczenia:

• wykrywanie konwersacji zależy od istniejących metadanych tras sesji Gateway
• brak ogólnego protokołu push poza adapterem specyficznym dla Claude
• nie ma jeszcze narzędzi do edycji wiadomości ani reakcji
• transport HTTP/SSE/streamable-http łączy się z jednym serwerem zdalnym; nie ma jeszcze multipleksowanego upstreamu
• permissions_list_open obejmuje tylko zatwierdzenia zaobserwowane, gdy most jest połączony

Powiązane

• Dokumentacja CLI
• Pluginy