Protokół Gateway

Protokół Gateway WS jest pojedynczą płaszczyzną sterowania + transportem węzłów dla OpenClaw. Wszyscy klienci (CLI, web UI, aplikacja macOS, węzły iOS/Android, węzły headless) łączą się przez WebSocket i deklarują swoją rolę + zakres podczas uzgadniania połączenia.

Transport

• WebSocket, ramki tekstowe z ładunkami JSON.
• Pierwsza ramka musi być żądaniem connect.
• Ramki przed połączeniem są ograniczone do 64 KiB. Po udanym uzgodnieniu połączenia klienci powinni przestrzegać limitów hello-ok.policy.maxPayload i hello-ok.policy.maxBufferedBytes. Przy włączonej diagnostyce zbyt duże ramki przychodzące i wolne bufory wychodzące emitują zdarzenia payload.large zanim gateway zamknie lub odrzuci dotkniętą ramkę. Te zdarzenia zachowują rozmiary, limity, powierzchnie i bezpieczne kody przyczyn. Nie zachowują treści wiadomości, zawartości załączników, surowej treści ramki, tokenów, plików cookie ani wartości tajnych.

Uzgadnianie połączenia (connect)

Gateway → Klient (wyzwanie przed połączeniem):

{  "type": "event",  "event": "connect.challenge",  "payload": { "nonce": "…", "ts": 1737264000000 }}

Klient → Gateway:

{  "type": "req",  "id": "…",  "method": "connect",  "params": {    "minProtocol": 3,    "maxProtocol": 4,    "client": {      "id": "cli",      "version": "1.2.3",      "platform": "macos",      "mode": "operator"    },    "role": "operator",    "scopes": ["operator.read", "operator.write"],    "caps": [],    "commands": [],    "permissions": {},    "auth": { "token": "…" },    "locale": "en-US",    "userAgent": "openclaw-cli/1.2.3",    "device": {      "id": "device_fingerprint",      "publicKey": "…",      "signature": "…",      "signedAt": 1737264000000,      "nonce": "…"    }  }}

Gateway → Klient:

{  "type": "res",  "id": "…",  "ok": true,  "payload": {    "type": "hello-ok",    "protocol": 4,    "server": { "version": "…", "connId": "…" },    "features": { "methods": ["…"], "events": ["…"] },    "snapshot": { "…": "…" },    "auth": {      "role": "operator",      "scopes": ["operator.read", "operator.write"]    },    "policy": {      "maxPayload": 26214400,      "maxBufferedBytes": 52428800,      "tickIntervalMs": 15000    }  }}

Gdy Gateway nadal kończy uruchamianie procesów pomocniczych, żądanie connect może zwrócić ponawialny błąd UNAVAILABLE z details.reason ustawionym na "startup-sidecars" oraz retryAfterMs. Klienci powinni ponawiać taką odpowiedź w ramach swojego ogólnego budżetu połączenia zamiast przedstawiać ją jako końcową awarię uzgadniania połączenia.

server, features, snapshot i policy są wymagane przez schemat (packages/gateway-protocol/src/schema/frames.ts). auth jest również wymagane i zgłasza wynegocjowaną rolę/zakresy. pluginSurfaceUrls jest opcjonalne i mapuje nazwy powierzchni pluginów, takie jak canvas, na zakresowe hostowane adresy URL.

Zakresowe adresy URL powierzchni pluginów mogą wygasać. Węzły mogą wywołać node.pluginSurface.refresh z { "surface": "canvas" }, aby otrzymać świeży wpis w pluginSurfaceUrls. Eksperymentalna przebudowa pluginu Canvas nie obsługuje przestarzałej ścieżki zgodności canvasHostUrl, canvasCapability ani node.canvas.capability.refresh; obecni klienci natywni i gatewaye muszą używać powierzchni pluginów.

Gdy token urządzenia nie zostanie wydany, hello-ok.auth zgłasza wynegocjowane uprawnienia bez pól tokenu:

{  "auth": {    "role": "operator",    "scopes": ["operator.read", "operator.write"]  }}

Zaufani klienci backendu w tym samym procesie (client.id: "gateway-client", client.mode: "backend") mogą pomijać device przy bezpośrednich połączeniach loopback, gdy uwierzytelniają się współdzielonym tokenem/hasłem gatewaya. Ta ścieżka jest zarezerwowana dla wewnętrznych RPC płaszczyzny sterowania i zapobiega blokowaniu lokalnej pracy backendu, takiej jak aktualizacje sesji podagentów, przez nieaktualne bazowe parowania CLI/urządzeń. Klienci zdalni, klienci pochodzący z przeglądarki, klienci węzłów oraz jawni klienci tokenu urządzenia/tożsamości urządzenia nadal używają normalnych kontroli parowania i podnoszenia zakresu.

Gdy token urządzenia zostanie wydany, hello-ok zawiera również:

{  "auth": {    "deviceToken": "…",    "role": "operator",    "scopes": ["operator.read", "operator.write"]  }}

Wbudowany bootstrap kodu QR/kodu konfiguracji jest świeżą ścieżką przekazania mobilnego. Udane bazowe połączenie kodem konfiguracji zwraca główny token węzła oraz jeden ograniczony token operatora:

{  "auth": {    "deviceToken": "…",    "role": "node",    "scopes": [],    "deviceTokens": [      {        "deviceToken": "…",        "role": "operator",        "scopes": ["operator.approvals", "operator.read", "operator.talk.secrets", "operator.write"]      }    ]  }}

Przekazanie operatora jest celowo ograniczone, aby onboarding przez QR mógł uruchomić mobilną pętlę operatora i ukończyć natywną konfigurację bez przyznawania zakresów modyfikacji parowania ani operator.admin. Obejmuje operator.talk.secrets, aby klient natywny mógł odczytać konfigurację Talk potrzebną po bootstrapie. Szersze parowanie i dostęp administracyjny wymagają osobnego zatwierdzonego parowania operatora lub przepływu tokenu. Klienci powinni utrwalać hello-ok.auth.deviceTokens tylko wtedy, gdy połączenie użyło uwierzytelniania bootstrap na zaufanym transporcie, takim jak wss:// lub loopback/parowanie lokalne.

Przykład węzła

{  "type": "req",  "id": "…",  "method": "connect",  "params": {    "minProtocol": 3,    "maxProtocol": 4,    "client": {      "id": "ios-node",      "version": "1.2.3",      "platform": "ios",      "mode": "node"    },    "role": "node",    "scopes": [],    "caps": ["camera", "canvas", "screen", "location", "voice"],    "commands": ["camera.snap", "canvas.navigate", "screen.record", "location.get"],    "permissions": { "camera.capture": true, "screen.record": false },    "auth": { "token": "…" },    "locale": "en-US",    "userAgent": "openclaw-ios/1.2.3",    "device": {      "id": "device_fingerprint",      "publicKey": "…",      "signature": "…",      "signedAt": 1737264000000,      "nonce": "…"    }  }}

Ramkowanie

• Żądanie: {type:"req", id, method, params}
• Odpowiedź: {type:"res", id, ok, payload|error}
• Zdarzenie: {type:"event", event, payload, seq?, stateVersion?}

Metody wywołujące skutki uboczne wymagają kluczy idempotencji (zobacz schemat).

Role + zakresy

Pełny model zakresów operatora, kontrole w czasie zatwierdzania i semantykę współdzielonych sekretów opisuje sekcja Zakresy operatora.

Role

• operator = klient płaszczyzny sterowania (CLI/UI/automatyzacja).
• node = host możliwości (camera/screen/canvas/system.run).

Zakresy (operator)

Typowe zakresy:

• operator.read
• operator.write
• operator.admin
• operator.approvals
• operator.pairing
• operator.talk.secrets

talk.config z includeSecrets: true wymaga operator.talk.secrets (lub operator.admin). Gdy sekrety są dołączone, klienci powinni odczytywać poświadczenie aktywnego dostawcy Talk z talk.resolved.config.apiKey; talk.providers.<id>.apiKey pozostaje w kształcie źródłowym i może być obiektem SecretRef albo zredagowanym ciągiem.

Metody RPC gatewaya zarejestrowane przez plugin mogą żądać własnego zakresu operatora, ale zastrzeżone prefiksy administracyjne rdzenia (config.*, exec.approvals.*, wizard.*, update.*) zawsze rozwiązują się do operator.admin.

Zakres metody jest tylko pierwszą bramką. Niektóre polecenia ukośnikowe osiągane przez chat.send nakładają dodatkowo surowsze kontrole na poziomie polecenia. Na przykład trwałe zapisy /config set i /config unset wymagają operator.admin.

node.pair.approve ma również dodatkową kontrolę zakresu w czasie zatwierdzania ponad bazowym zakresem metody:

• żądania bez poleceń: operator.pairing
• żądania z poleceniami węzła innymi niż exec: operator.pairing + operator.write
• żądania obejmujące system.run, system.run.prepare lub system.which: operator.pairing + operator.admin

Możliwości/polecenia/uprawnienia (węzeł)

Węzły deklarują roszczenia dotyczące możliwości w czasie połączenia:

• caps: kategorie możliwości wysokiego poziomu, takie jak camera, canvas, screen, location, voice i talk.
• commands: lista dozwolonych poleceń dla invoke.
• permissions: szczegółowe przełączniki (np. screen.record, camera.capture).

Gateway traktuje je jako roszczenia i egzekwuje listy dozwolone po stronie serwera.

Obecność

• system-presence zwraca wpisy kluczowane tożsamością urządzenia.
• Wpisy obecności obejmują deviceId, roles i scopes, aby UI mogły pokazywać jeden wiersz na urządzenie nawet wtedy, gdy łączy się ono zarówno jako operator, jak i node.
• node.list obejmuje opcjonalne pola lastSeenAtMs i lastSeenReason. Połączone węzły zgłaszają swój bieżący czas połączenia jako lastSeenAtMs z przyczyną connect; sparowane węzły mogą też zgłaszać trwałą obecność w tle, gdy zaufane zdarzenie węzła aktualizuje ich metadane parowania.

Zdarzenie aktywności węzła w tle

Węzły mogą wywołać node.event z event: "node.presence.alive", aby zapisać, że sparowany węzeł był aktywny podczas wybudzenia w tle bez oznaczania go jako połączonego.

{  "event": "node.presence.alive",  "payloadJSON": "{\"trigger\":\"silent_push\",\"sentAtMs\":1737264000000,\"displayName\":\"Peter's iPhone\",\"version\":\"2026.4.28\",\"platform\":\"iOS 18.4.0\",\"deviceFamily\":\"iPhone\",\"modelIdentifier\":\"iPhone17,1\",\"pushTransport\":\"relay\"}"}

trigger jest zamkniętym wyliczeniem: background, silent_push, bg_app_refresh, significant_location, manual lub connect. Nieznane ciągi wyzwalacza są normalizowane do background przez gateway przed utrwaleniem. Zdarzenie jest trwałe tylko dla uwierzytelnionych sesji urządzeń węzłów; sesje bez urządzenia lub niesparowane zwracają handled: false.

Udane gatewaye zwracają ustrukturyzowany wynik:

{  "ok": true,  "event": "node.presence.alive",  "handled": true,  "reason": "persisted"}

Starsze gatewaye mogą nadal zwracać { "ok": true } dla node.event; klienci powinni traktować to jako potwierdzone RPC, a nie jako trwałe utrwalenie obecności.

Zakresowanie zdarzeń rozgłoszeniowych

Zdarzenia rozgłoszeniowe WebSocket wypychane przez serwer są bramkowane zakresami, aby sesje zakresowane parowaniem lub tylko węzłowe nie odbierały biernie treści sesji.

• Ramki czatu, agenta i wyników narzędzi (w tym strumieniowane zdarzenia agent i wyniki wywołań narzędzi) wymagają co najmniej operator.read. Sesje bez operator.read całkowicie pomijają te ramki.
• Rozgłoszenia plugin.* zdefiniowane przez plugin są bramkowane do operator.write lub operator.admin, zależnie od tego, jak plugin je zarejestrował.
• Zdarzenia statusu i transportu (heartbeat, presence, tick, cykl życia connect/disconnect itd.) pozostają nieograniczone, aby stan transportu był obserwowalny dla każdej uwierzytelnionej sesji.
• Nieznane rodziny zdarzeń rozgłoszeniowych są domyślnie bramkowane zakresami (fail-closed), chyba że zarejestrowany handler jawnie je poluzuje.

Każde połączenie klienta utrzymuje własny numer sekwencyjny per klient, więc rozgłoszenia zachowują monotoniczną kolejność na tym gnieździe nawet wtedy, gdy różni klienci widzą różne, filtrowane zakresami podzbiory strumienia zdarzeń.

Typowe rodziny metod RPC

Publiczna powierzchnia WS jest szersza niż powyższe przykłady uzgadniania połączenia/uwierzytelniania. To nie jest wygenerowany zrzut — hello-ok.features.methods jest konserwatywną listą wykrywania zbudowaną z src/gateway/server-methods-list.ts oraz załadowanych eksportów metod pluginów/kanałów. Traktuj ją jako wykrywanie funkcji, a nie pełne wyliczenie src/gateway/server-methods/*.ts.

Typowe rodziny zdarzeń

• chat: aktualizacje czatu UI, takie jak chat.inject, oraz inne zdarzenia czatu wyłącznie transkrypcyjne. W protokole v4 ładunki delta przenoszą deltaText; message pozostaje skumulowaną migawką asystenta. Zastąpienia niebędące prefiksem ustawiają replace=true i używają deltaText jako tekstu zastępczego.
• session.message, session.operation i session.tool: aktualizacje transkrypcji, operacji sesji w toku oraz strumienia zdarzeń dla subskrybowanej sesji.
• sessions.changed: indeks sesji lub metadane zostały zmienione.
• presence: aktualizacje migawek obecności systemu.
• tick: okresowe zdarzenie keepalive / żywotności.
• health: aktualizacja migawki stanu Gateway.
• heartbeat: aktualizacja strumienia zdarzeń Heartbeat.
• cron: zdarzenie zmiany uruchomienia/zadania Cron.
• shutdown: powiadomienie o zamknięciu Gateway.
• node.pair.requested / node.pair.resolved: cykl życia parowania węzła.
• node.invoke.request: rozgłoszenie żądania wywołania węzła.
• device.pair.requested / device.pair.resolved: cykl życia sparowanego urządzenia.
• voicewake.changed: zmieniono konfigurację wyzwalacza słowa wybudzającego.
• exec.approval.requested / exec.approval.resolved: cykl życia zatwierdzenia wykonania.
• plugin.approval.requested / plugin.approval.resolved: cykl życia zatwierdzenia Plugin.

Metody pomocnicze węzłów

• Węzły mogą wywoływać skills.bins, aby pobrać bieżącą listę plików wykonywalnych umiejętności na potrzeby kontroli automatycznego zezwalania.

RPC rejestru zadań

Klienci operatorów mogą sprawdzać i anulować rekordy zadań w tle Gateway przez RPC rejestru zadań. Te metody zwracają oczyszczone podsumowania zadań, a nie surowy stan środowiska wykonawczego.

• tasks.list wymaga operator.read.
  • Parametry: opcjonalny status ("queued", "running", "completed", "failed", "cancelled" lub "timed_out") albo tablica tych statusów, opcjonalne agentId, opcjonalne sessionKey, opcjonalny limit od 1 do 500 oraz opcjonalny ciąg cursor.
  • Wynik: { "tasks": TaskSummary[], "nextCursor"?: string }.
• tasks.get wymaga operator.read.
  • Parametry: { "taskId": string }.
  • Wynik: { "task": TaskSummary }.
  • Brakujące identyfikatory zadań zwracają kształt błędu Gateway nie znaleziono.
• tasks.cancel wymaga operator.write.
  • Parametry: { "taskId": string, "reason"?: string }.
  • Wynik: { "found": boolean, "cancelled": boolean, "reason"?: string, "task"?: TaskSummary }.
  • found informuje, czy rejestr zawierał pasujące zadanie. cancelled informuje, czy środowisko wykonawcze zaakceptowało lub odnotowało anulowanie.

TaskSummary zawiera id, status i opcjonalne metadane, takie jak kind, runtime, title, agentId, sessionKey, childSessionKey, ownerKey, runId, taskId, flowId, parentTaskId, sourceId, znaczniki czasu, postęp, podsumowanie końcowe oraz oczyszczony tekst błędu. agentId identyfikuje agenta wykonującego zadanie; sessionKey i ownerKey zachowują kontekst żądającego oraz kontroli.

Metody pomocnicze operatora

• Operatorzy mogą wywołać commands.list (operator.read), aby pobrać inwentarz poleceń środowiska wykonawczego dla agenta.
  • agentId jest opcjonalne; pomiń je, aby odczytać domyślny obszar roboczy agenta.
  • scope kontroluje, do której powierzchni odnosi się główna wartość name:
    • text zwraca główny token polecenia tekstowego bez początkowego /
    • native oraz domyślna ścieżka both zwracają nazwy natywne uwzględniające dostawcę, gdy są dostępne
  • textAliases przenosi dokładne aliasy z ukośnikiem, takie jak /model i /m.
  • nativeName przenosi nazwę polecenia natywnego uwzględniającą dostawcę, gdy taka istnieje.
  • provider jest opcjonalne i wpływa tylko na nazewnictwo natywne oraz dostępność natywnych poleceń pluginu.
  • includeArgs=false pomija serializowane metadane argumentów w odpowiedzi.
• Operatorzy mogą wywołać tools.catalog (operator.read), aby pobrać katalog narzędzi środowiska wykonawczego dla agenta. Odpowiedź zawiera pogrupowane narzędzia i metadane pochodzenia:
  • source: core lub plugin
  • pluginId: właściciel pluginu, gdy source="plugin"
  • optional: czy narzędzie pluginu jest opcjonalne
• Operatorzy mogą wywołać tools.effective (operator.read), aby pobrać efektywny w środowisku wykonawczym inwentarz narzędzi dla sesji.
  • sessionKey jest wymagane.
  • Gateway wyprowadza zaufany kontekst środowiska wykonawczego z sesji po stronie serwera, zamiast akceptować kontekst uwierzytelniania lub dostarczania dostarczony przez wywołującego.
  • Odpowiedź jest ograniczoną do sesji, wyprowadzoną przez serwer projekcją aktywnego inwentarza, obejmującą narzędzia rdzenia, pluginów, kanałów oraz już wykrytych serwerów MCP.
  • tools.effective jest tylko do odczytu dla MCP: może przepuścić rozgrzany katalog MCP sesji przez końcową politykę narzędzi, ale nie tworzy środowisk wykonawczych MCP, nie łączy transportów ani nie wydaje tools/list. Jeśli nie istnieje pasujący rozgrzany katalog, odpowiedź może zawierać powiadomienie takie jak mcp-not-yet-connected, mcp-not-yet-listed lub mcp-stale-catalog.
  • Wpisy efektywnych narzędzi używają source="core", source="plugin", source="channel" lub source="mcp".
• Operatorzy mogą wywołać tools.invoke (operator.write), aby uruchomić jedno dostępne narzędzie przez tę samą ścieżkę polityki Gateway co /tools/invoke.
  • name jest wymagane. args, sessionKey, agentId, confirm i idempotencyKey są opcjonalne.
  • Jeśli obecne są zarówno sessionKey, jak i agentId, rozwiązany agent sesji musi pasować do agentId.
  • Ograniczone do właściciela wrappery rdzenia, takie jak cron, gateway i nodes, wymagają tożsamości właściciela/administratora (operator.admin), mimo że sama metoda tools.invoke ma uprawnienie operator.write.
  • Odpowiedź jest kopertą skierowaną do SDK z polami ok, toolName, opcjonalnym output i typowanymi polami error. Odmowy zatwierdzenia lub polityki zwracają ok:false w ładunku, zamiast omijać potok polityki narzędzi Gateway.
• Operatorzy mogą wywołać skills.status (operator.read), aby pobrać widoczny inwentarz Skills dla agenta.
  • agentId jest opcjonalne; pomiń je, aby odczytać domyślny obszar roboczy agenta.
  • Odpowiedź zawiera kwalifikowalność, brakujące wymagania, kontrole konfiguracji oraz oczyszczone opcje instalacji bez ujawniania surowych wartości sekretów.
• Operatorzy mogą wywołać skills.search i skills.detail (operator.read) dla metadanych odkrywania ClawHub.
• Operatorzy mogą wywołać skills.upload.begin, skills.upload.chunk i skills.upload.commit (operator.admin), aby przygotować prywatne archiwum Skills przed jego instalacją. Jest to osobna administracyjna ścieżka przesyłania dla zaufanych klientów, a nie zwykły przepływ instalacji Skills z ClawHub, i domyślnie jest wyłączona, chyba że włączono skills.install.allowUploadedArchives.
  • skills.upload.begin({ kind: "skill-archive", slug, sizeBytes, sha256?, force?, idempotencyKey? }) tworzy przesyłanie powiązane z tym slugiem i wartością force.
  • skills.upload.chunk({ uploadId, offset, dataBase64 }) dopisuje bajty przy dokładnym zdekodowanym przesunięciu.
  • skills.upload.commit({ uploadId, sha256? }) weryfikuje końcowy rozmiar i SHA-256. Commit tylko finalizuje przesyłanie; nie instaluje Skills.
  • Przesłane archiwa Skills są archiwami zip zawierającymi główny plik SKILL.md. Wewnętrzna nazwa katalogu archiwum nigdy nie wybiera celu instalacji.
• Operatorzy mogą wywołać skills.install (operator.admin) w trzech trybach:
  • Tryb ClawHub: { source: "clawhub", slug, version?, force? } instaluje folder Skills w katalogu skills/ domyślnego obszaru roboczego agenta.
  • Tryb przesyłania: { source: "upload", uploadId, slug, force?, sha256?, timeoutMs? } instaluje zatwierdzone przesyłanie w katalogu skills/<slug> domyślnego obszaru roboczego agenta. Slug i wartość force muszą odpowiadać pierwotnemu żądaniu skills.upload.begin. Ten tryb jest odrzucany, chyba że włączono skills.install.allowUploadedArchives. Ustawienie nie wpływa na instalacje ClawHub.
  • Tryb instalatora Gateway: { name, installId, timeoutMs? } uruchamia zadeklarowaną akcję metadata.openclaw.install na hoście Gateway. Starsi klienci nadal mogą wysyłać dangerouslyForceUnsafeInstall; to pole jest przestarzałe, akceptowane tylko ze względu na zgodność protokołu i ignorowane. Użyj security.installPolicy do decyzji instalacyjnych należących do operatora.
• Operatorzy mogą wywołać skills.update (operator.admin) w dwóch trybach:
  • Tryb ClawHub aktualizuje jeden śledzony slug albo wszystkie śledzone instalacje ClawHub w domyślnym obszarze roboczym agenta.
  • Tryb konfiguracji łata wartości skills.entries.<skillKey>, takie jak enabled, apiKey i env.

Widoki models.list

models.list przyjmuje opcjonalny parametr view:

• Pominięte lub "default": bieżące zachowanie środowiska wykonawczego. Jeśli skonfigurowano agents.defaults.models, odpowiedź jest dozwolonym katalogiem, w tym dynamicznie wykrytymi modelami dla wpisów provider/*. W przeciwnym razie odpowiedź jest pełnym katalogiem Gateway.
• "configured": zachowanie o rozmiarze selektora. Jeśli skonfigurowano agents.defaults.models, nadal ma pierwszeństwo, w tym odkrywanie ograniczone do dostawcy dla wpisów provider/*. Bez listy dozwolonych odpowiedź używa jawnych wpisów models.providers.*.models, przechodząc do pełnego katalogu tylko wtedy, gdy nie istnieją skonfigurowane wiersze modeli.
• "all": pełny katalog Gateway, z pominięciem agents.defaults.models. Używaj tego do diagnostyki i interfejsów odkrywania, nie do zwykłych selektorów modeli.

Zatwierdzenia exec

• Gdy żądanie exec wymaga zatwierdzenia, Gateway rozgłasza exec.approval.requested.
• Klienci operatora rozwiązują je, wywołując exec.approval.resolve (wymaga zakresu operator.approvals).
• Dla host=node żądanie exec.approval.request musi zawierać systemRunPlan (kanoniczne argv/cwd/rawCommand/metadane sesji). Żądania bez systemRunPlan są odrzucane.
• Po zatwierdzeniu przekazywane wywołania node.invoke system.run ponownie używają tego kanonicznego systemRunPlan jako autorytatywnego kontekstu polecenia/cwd/sesji.
• Jeśli wywołujący zmieni command, rawCommand, cwd, agentId lub sessionKey między przygotowaniem a końcowym, zatwierdzonym przekazaniem system.run, Gateway odrzuci uruchomienie zamiast ufać zmienionemu ładunkowi.

Awaryjna ścieżka dostarczania agenta

• Żądania agent mogą zawierać deliver=true, aby zażądać dostarczania wychodzącego.
• bestEffortDeliver=false zachowuje ścisłe zachowanie: nierozwiązane lub wyłącznie wewnętrzne cele dostarczania zwracają INVALID_REQUEST.
• bestEffortDeliver=true pozwala na przejście do wykonania tylko w sesji, gdy nie można rozwiązać żadnej zewnętrznej trasy możliwej do dostarczenia (na przykład sesje wewnętrzne/webchat lub niejednoznaczne konfiguracje wielokanałowe).
• Końcowe wyniki agent mogą zawierać result.deliveryStatus, gdy zażądano dostarczania, używając tych samych statusów sent, suppressed, partial_failed i failed, które udokumentowano dla openclaw agent --json --deliver.

Wersjonowanie

• PROTOCOL_VERSION znajduje się w packages/gateway-protocol/src/version.ts.
• Klienci wysyłają minProtocol + maxProtocol; serwer odrzuca zakresy, które nie obejmują jego bieżącego protokołu. Obecni klienci i serwery wymagają protokołu v4.
• Schematy i modele są generowane z definicji TypeBox:
  • pnpm protocol:gen
  • pnpm protocol:gen:swift
  • pnpm protocol:check

Stałe klienta

Klient referencyjny w src/gateway/client.ts używa tych wartości domyślnych. Wartości są stabilne w protokole v4 i stanowią oczekiwaną bazę dla klientów zewnętrznych.

Serwer ogłasza efektywne wartości policy.tickIntervalMs, policy.maxPayload i policy.maxBufferedBytes w hello-ok; klienci powinni respektować te wartości zamiast domyślnych sprzed uzgadniania.

Uwierzytelnianie

• Uwierzytelnianie Gateway za pomocą współdzielonego sekretu używa connect.params.auth.token albo connect.params.auth.password, zależnie od skonfigurowanego trybu uwierzytelniania.
• Tryby przenoszące tożsamość, takie jak Tailscale Serve (gateway.auth.allowTailscale: true) albo tryb spoza local loopback gateway.auth.mode: "trusted-proxy", spełniają kontrolę uwierzytelniania połączenia na podstawie nagłówków żądania zamiast connect.params.auth.*.
• Prywatny ingress gateway.auth.mode: "none" całkowicie pomija uwierzytelnianie połączenia współdzielonym sekretem; nie wystawiaj tego trybu na publiczny/niezaufany ingress.
• Po sparowaniu Gateway wydaje token urządzenia ograniczony do roli połączenia
  • zakresów. Jest zwracany w hello-ok.auth.deviceToken i powinien być utrwalony przez klienta na potrzeby przyszłych połączeń.
• Klienci powinni utrwalać podstawowy hello-ok.auth.deviceToken po każdym udanym połączeniu.
• Ponowne łączenie z tym zapisanym tokenem urządzenia powinno także ponownie używać zapisanego zatwierdzonego zestawu zakresów dla tego tokenu. Zachowuje to dostęp do odczytu/sondowania/statusu, który został już przyznany, i zapobiega cichemu zawężeniu ponownych połączeń do węższego, domyślnego zakresu tylko dla administratora.
• Składanie uwierzytelniania połączenia po stronie klienta (selectConnectAuth w src/gateway/client.ts):
  • auth.password jest niezależne i zawsze przekazywane dalej, gdy jest ustawione.
  • auth.token jest wypełniane według priorytetu: najpierw jawny współdzielony token, potem jawny deviceToken, a następnie zapisany token dla danego urządzenia (kluczowany przez deviceId + role).
  • auth.bootstrapToken jest wysyłany tylko wtedy, gdy żaden z powyższych elementów nie rozwiązał auth.token. Współdzielony token lub dowolny rozwiązany token urządzenia go tłumi.
  • Automatyczne promowanie zapisanego tokenu urządzenia przy jednorazowej ponownej próbie AUTH_TOKEN_MISMATCH jest ograniczone do zaufanych punktów końcowych — loopback albo wss:// z przypiętym tlsFingerprint. Publiczne wss:// bez przypięcia się nie kwalifikuje.
• Wbudowany bootstrap kodu konfiguracji zwraca podstawowy token węzła hello-ok.auth.deviceToken oraz ograniczony token operatora w hello-ok.auth.deviceTokens na potrzeby zaufanego przekazania mobilnego. Token operatora obejmuje operator.talk.secrets do natywnych odczytów konfiguracji Talk, ale wyklucza zakresy mutacji parowania oraz operator.admin.
• Gdy bootstrap kodu konfiguracji inny niż bazowy czeka na zatwierdzenie, szczegóły PAIRING_REQUIRED obejmują recommendedNextStep: "wait_then_retry", retryable: true oraz pauseReconnect: false. Klienci powinni kontynuować ponowne łączenie z tym samym tokenem bootstrapu, dopóki żądanie nie zostanie zatwierdzone albo token nie stanie się nieprawidłowy.
• Utrwalaj hello-ok.auth.deviceTokens tylko wtedy, gdy połączenie użyło uwierzytelniania bootstrapu przez zaufany transport, taki jak wss:// albo parowanie przez loopback/lokalne.
• Jeśli klient podaje jawny deviceToken albo jawne scopes, ten zestaw zakresów zażądany przez wywołującego pozostaje rozstrzygający; zakresy z pamięci podręcznej są ponownie używane tylko wtedy, gdy klient ponownie używa zapisanego tokenu dla danego urządzenia.
• Tokeny urządzeń można rotować/odwoływać przez device.token.rotate i device.token.revoke (wymaga zakresu operator.pairing). Rotowanie lub odwoływanie tokenu węzła albo innej roli niebędącej operatorem wymaga także operator.admin.
• device.token.rotate zwraca metadane rotacji. Zwraca zastępczy bearer token tylko dla wywołań z tego samego urządzenia, które są już uwierzytelnione tym tokenem urządzenia, aby klienci używający tylko tokenów mogli utrwalić zamiennik przed ponownym połączeniem. Rotacje współdzielone/administracyjne nie zwracają bearer tokenu.
• Wydawanie, rotacja i odwoływanie tokenów pozostają ograniczone do zatwierdzonego zestawu ról zapisanego we wpisie parowania danego urządzenia; mutacja tokenu nie może rozszerzyć ani wskazać roli urządzenia, której zatwierdzenie parowania nigdy nie przyznało.
• W sesjach tokenów sparowanych urządzeń zarządzanie urządzeniami jest samoograniczone, chyba że wywołujący ma także operator.admin: wywołujący bez uprawnień administratora mogą zarządzać tylko tokenem operatora dla wpisu własnego urządzenia. Zarządzanie tokenami węzła i innymi tokenami niebędącymi operatorami jest dostępne tylko dla administratora, nawet dla własnego urządzenia wywołującego.
• device.token.rotate i device.token.revoke sprawdzają także docelowy zestaw zakresów tokenu operatora względem bieżących zakresów sesji wywołującego. Wywołujący bez uprawnień administratora nie mogą rotować ani odwoływać szerszego tokenu operatora niż ten, który już posiadają.
• Niepowodzenia uwierzytelniania obejmują error.details.code oraz wskazówki odzyskiwania:
  • error.details.canRetryWithDeviceToken (boolean)
  • error.details.recommendedNextStep (retry_with_device_token, update_auth_configuration, update_auth_credentials, wait_then_retry, review_auth_configuration)
• Zachowanie klienta dla AUTH_TOKEN_MISMATCH:
  • Zaufani klienci mogą podjąć jedną ograniczoną ponowną próbę z tokenem dla danego urządzenia z pamięci podręcznej.
  • Jeśli ta ponowna próba się nie powiedzie, klienci powinni zatrzymać automatyczne pętle ponownego łączenia i pokazać operatorowi wskazówki dotyczące działania.
• AUTH_SCOPE_MISMATCH oznacza, że token urządzenia został rozpoznany, ale nie obejmuje żądanej roli/zakresów. Klienci nie powinni przedstawiać tego jako złego tokenu; poproś operatora o ponowne sparowanie albo zatwierdzenie węższego/szerszego kontraktu zakresów.

Tożsamość urządzenia + parowanie

• Węzły powinny zawierać stabilną tożsamość urządzenia (device.id) wyprowadzoną z odcisku palca pary kluczy.
• Gateway wydaje tokeny dla urządzenia + roli.
• Zatwierdzenia parowania są wymagane dla nowych identyfikatorów urządzeń, chyba że włączono lokalne automatyczne zatwierdzanie.
• Automatyczne zatwierdzanie parowania koncentruje się na bezpośrednich połączeniach przez lokalny local loopback.
• OpenClaw ma także wąską ścieżkę samopołączenia lokalną dla backendu/kontenera dla zaufanych przepływów pomocniczych ze współdzielonym sekretem.
• Połączenia z tego samego hosta przez tailnet lub LAN nadal są traktowane jako zdalne na potrzeby parowania i wymagają zatwierdzenia.
• Klienci WS zwykle uwzględniają tożsamość device podczas connect (operator + węzeł). Jedynymi wyjątkami operatora bez urządzenia są jawne ścieżki zaufania:
  • gateway.controlUi.allowInsecureAuth=true dla zgodności z niebezpiecznym HTTP tylko na localhost.
  • udane uwierzytelnienie operatora Control UI w gateway.auth.mode: "trusted-proxy".
  • gateway.controlUi.dangerouslyDisableDeviceAuth=true (tryb awaryjny, poważne obniżenie bezpieczeństwa).
  • bezpośrednie RPC backendu gateway-client przez loopback na zarezerwowanej wewnętrznej ścieżce pomocniczej.
• Pominięcie tożsamości urządzenia ma konsekwencje dla zakresu. Gdy połączenie operatora bez urządzenia jest dopuszczone przez jawną ścieżkę zaufania, OpenClaw nadal czyści samodzielnie zadeklarowane zakresy do pustego zestawu, chyba że ta ścieżka ma nazwany wyjątek zachowania zakresów. Metody ograniczone zakresem kończą się wtedy niepowodzeniem z missing scope.
• gateway.controlUi.dangerouslyDisableDeviceAuth=true to ścieżka awaryjnego zachowania zakresów Control UI. Nie przyznaje zakresów dowolnym niestandardowym klientom WebSocket w kształcie backendu lub CLI.
• Zarezerwowana ścieżka pomocnicza backendu gateway-client przez bezpośredni loopback zachowuje zakresy tylko dla wewnętrznych lokalnych RPC płaszczyzny sterowania; niestandardowe identyfikatory backendu nie otrzymują tego wyjątku.
• Wszystkie połączenia muszą podpisać nonce connect.challenge dostarczony przez serwer.

Diagnostyka migracji uwierzytelniania urządzeń

Dla starszych klientów, którzy nadal używają zachowania podpisywania sprzed challenge, connect zwraca teraz kody szczegółów DEVICE_AUTH_* w error.details.code ze stabilnym error.details.reason.

Typowe niepowodzenia migracji:

Cel migracji:

• Zawsze czekaj na connect.challenge.
• Podpisuj ładunek v2, który zawiera nonce serwera.
• Wyślij ten sam nonce w connect.params.device.nonce.
• Preferowany ładunek podpisu to v3, który wiąże platform i deviceFamily oprócz pól device/client/role/scopes/token/nonce.
• Starsze podpisy v2 pozostają akceptowane ze względów zgodności, ale przypinanie metadanych sparowanego urządzenia nadal kontroluje politykę poleceń przy ponownym połączeniu.

TLS + przypinanie

• TLS jest obsługiwane dla połączeń WS.
• Klienci mogą opcjonalnie przypiąć odcisk palca certyfikatu Gateway (zobacz konfigurację gateway.tls oraz gateway.remote.tlsFingerprint albo CLI --tls-fingerprint).

Zakres

Ten protokół udostępnia pełne API Gateway (status, kanały, modele, czat, agent, sesje, węzły, zatwierdzenia itd.). Dokładna powierzchnia jest zdefiniowana przez schematy TypeBox w packages/gateway-protocol/src/schema.ts.

Powiązane

• Protokół mostu
• Runbook Gateway