MCP

openclaw mcp ma dwa zadania:

• uruchamiać OpenClaw jako serwer MCP za pomocą openclaw mcp serve
• zarządzać należącymi do OpenClaw definicjami wychodzących serwerów MCP za pomocą list, show, set i unset

Innymi słowy:

• serve to OpenClaw działający jako serwer MCP
• list / show / set / unset to OpenClaw działający jako rejestr po stronie klienta MCP dla innych serwerów MCP, z których jego runtime'y mogą korzystać później

Użyj openclaw acp, gdy OpenClaw ma sam hostować sesję uprzęży kodowania i kierować ten runtime przez ACP.

# 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 obsługiwanymi przez OpenClaw
• masz już lokalny lub zdalny OpenClaw Gateway z routowanymi sesjami
• chcesz jednego serwera MCP, który działa z backendami kanałów OpenClaw, zamiast uruchamiać osobne mosty dla każdego kanału

Użyj zamiast tego openclaw acp, gdy OpenClaw ma hostować sam runtime 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żywaj 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 tego, aby:

• wyświetlać ostatnie routowane konwersacje
• odczytywać ostatnią historię transkrypcji
• czekać na nowe zdarzenia przychodzące
• wysyłać odpowiedź tą samą trasą
• widzieć żądania zatwierdzenia, które docierają, 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 --verbose
openclaw 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 wiadomości przychodzące na żywo mogą też przychodzić 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 odebrane przez MCP są śledzone w pamięci
• jeśli powiązana konwersacja wyśle później yes abcde lub no abcde, most konwertuje to na notifications/claude/channel/permission
• te powiadomienia istnieją tylko w sesji na żywo; jeśli klient MCP się rozłączy, nie ma celu push

Jest to celowo 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órzy faktycznie rozumieją metody powiadomień specyficzne dla Claude.

# Opcje

openclaw mcp serve obsługuje:

# Bezpieczeństwo i granica zaufania

Most nie wymyśla routingu. Udostępnia tylko konwersacje, które Gateway już umie 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 tylko na żywo/w pamięci dla bieżącej sesji mostu
• uwierzytelnianie mostu powinno używać tych samych mechanizmów tokenu lub hasła Gateway, którym ufałbyś w przypadku każdego innego zdalnego klienta Gateway

Jeśli konwersacji brakuje w conversations_list, zwykłą przyczyną nie jest konfiguracja MCP. Są nią brakujące lub niepełne metadane trasy w bazowej sesji Gateway.

# Testowanie

OpenClaw dostarcza deterministyczny smoke test Docker dla tego mostu:

pnpm test:docker:mcp-channels

Ten smoke test:

• uruchamia wstępnie zasilony kontener Gateway
• uruchamia drugi kontener, który startuje openclaw mcp serve
• weryfikuje wykrywanie konwersacji, odczyty transkrypcji, odczyty metadanych załączników, zachowanie kolejki zdarzeń na żywo i routing wysyłania wychodzącego
• waliduje powiadomienia kanału i uprawnień w stylu Claude przez rzeczywisty most MCP stdio

To najszybszy sposób, aby udowodnić, że most działa bez podłączania prawdziwego konta Telegram, Discord ani iMessage do przebiegu testowego.

Szerszy kontekst testowania znajdziesz w Testowanie.

# Rozwiązywanie problemów

# OpenClaw jako rejestr klientów MCP

To jest ścieżka openclaw mcp list, show, set i unset.

Te polecenia nie udostępniają OpenClaw przez MCP. Zarządzają definicjami serwerów MCP należącymi do OpenClaw w mcp.servers w konfiguracji OpenClaw.

Te zapisane definicje są przeznaczone dla środowisk uruchomieniowych, które OpenClaw uruchamia lub konfiguruje później, takich jak osadzony Pi i inne adaptery środowisk uruchomieniowych. OpenClaw przechowuje definicje centralnie, aby te środowiska uruchomieniowe 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 Pi uż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.

# Zapisane definicje serwerów MCP

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

Polecenia:

• openclaw mcp list
• openclaw mcp show [name]
• openclaw mcp set <name> <json>
• openclaw mcp unset <name>

Uwagi:

• list sortuje nazwy serwerów.
• show bez nazwy wypisuje pełny skonfigurowany obiekt serwera MCP.
• set oczekuje jednej wartości obiektu JSON w wierszu poleceń.
• Użyj transport: "streamable-http" dla serwerów MCP Streamable HTTP. openclaw mcp set normalizuje też natywne dla CLI type: "http" do tego samego kanonicznego kształtu konfiguracji w celu zgodności.
• unset kończy się niepowodzeniem, jeśli nazwany serwer nie istnieje.

Przykłady:

openclaw mcp list
openclaw mcp show context7 --json
openclaw mcp set context7 '{"command":"uvx","args":["context7-mcp"]}'
openclaw mcp set docs '{"url":"https://mcp.example.com","transport":"streamable-http"}'
openclaw mcp unset context7

Przykładowy kształt konfiguracji:

{
  "mcp": {
    "servers": {
      "context7": {
        "command": "uvx",
        "args": ["context7-mcp"]
      },
      "docs": {
        "url": "https://mcp.example.com",
        "transport": "streamable-http"
      }
    }
  }
}

# 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",
        "headers": {
          "Authorization": "Bearer <token>"
        }
      }
    }
  }
}

Wartości wrażliwe w url (userinfo) i headers są redagowane w logach i danych statusu.

# 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, czego osadzony Pi używa bezpośrednio.

Przykład:

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

# Obecne ograniczenia

Ta strona dokumentuje most w postaci dostarczanej obecnie.

Obecne ograniczenia:

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

# Powiązane

• Dokumentacja CLI
• Plugins