Parowanie zarządzane przez Gateway

W parowaniu zarządzanym przez Gateway Gateway jest źródłem prawdy dla tego, które węzły mogą dołączyć. Interfejsy użytkownika (aplikacja macOS, przyszłe klienty) są tylko frontendami, które zatwierdzają lub odrzucają oczekujące żądania.

Ważne: węzły WS używają parowania urządzeń (rola node) podczas connect. node.pair.* to osobny magazyn parowania i nie kontroluje uzgadniania WS. Tylko klienty, które jawnie wywołują node.pair.*, używają tego przepływu.

Pojęcia

• Oczekujące żądanie: węzeł poprosił o dołączenie; wymaga zatwierdzenia.
• Sparowany węzeł: zatwierdzony węzeł z wydanym tokenem uwierzytelniania.
• Transport: punkt końcowy WS Gateway przekazuje żądania, ale nie decyduje o członkostwie. (Obsługa starszego mostu TCP została usunięta.)

Jak działa parowanie

1. Węzeł łączy się z Gateway WS i żąda parowania.
2. Gateway zapisuje oczekujące żądanie i emituje node.pair.requested.
3. Zatwierdzasz albo odrzucasz żądanie (CLI lub interfejs użytkownika).
4. Po zatwierdzeniu Gateway wydaje nowy token (tokeny są rotowane przy ponownym parowaniu).
5. Węzeł ponownie łączy się przy użyciu tokenu i jest teraz „sparowany”.

Oczekujące żądania automatycznie wygasają po 5 minutach.

Przepływ CLI (przyjazny dla trybu bezobsługowego)

openclaw nodes pendingopenclaw nodes approve <requestId>openclaw nodes reject <requestId>openclaw nodes statusopenclaw nodes remove --node <id|name|ip>openclaw nodes rename --node <id|name|ip> --name "Living Room iPad"

nodes status pokazuje sparowane/połączone węzły oraz ich możliwości.

Powierzchnia API (protokół Gateway)

Zdarzenia:

• node.pair.requested - emitowane, gdy zostanie utworzone nowe oczekujące żądanie.
• node.pair.resolved - emitowane, gdy żądanie zostanie zatwierdzone/odrzucone/wygaszone.

Metody:

• node.pair.request - tworzy oczekujące żądanie lub używa istniejącego ponownie.
• node.pair.list - wyświetla oczekujące + sparowane węzły (operator.pairing).
• node.pair.approve - zatwierdza oczekujące żądanie (wydaje token).
• node.pair.reject - odrzuca oczekujące żądanie.
• node.pair.remove - usuwa sparowany węzeł. W przypadku parowań opartych na urządzeniu cofa rolę node urządzenia: modyfikuje devices/paired.json i unieważnia/rozłącza sesje tego urządzenia z rolą węzła. Urządzenie z mieszanymi rolami (np. ma także operator) zachowuje swój wiersz i traci tylko rolę node; wiersz urządzenia wyłącznie z rolą węzła jest usuwany. Usuwa także każdy pasujący starszy wpis parowania węzła zarządzany przez gateway. Authz: operator.pairing może usuwać wiersze węzłów niebędące operatorami; wywołujący z tokenem urządzenia, który cofa rolę węzła własnego urządzenia z mieszanymi rolami, dodatkowo potrzebuje operator.admin.
• node.pair.verify - weryfikuje { nodeId, token }.

Uwagi:

• node.pair.request jest idempotentne dla każdego węzła: powtarzane wywołania zwracają to samo oczekujące żądanie.
• Powtarzane żądania dla tego samego oczekującego węzła odświeżają także przechowywane metadane węzła oraz najnowszą migawkę deklarowanych poleceń z listy dozwolonych, widoczną dla operatora.
• Zatwierdzenie zawsze generuje świeży token; żaden token nigdy nie jest zwracany z node.pair.request.
• Poziomy zakresów operatora i kontrole wykonywane podczas zatwierdzania są podsumowane w Zakresach operatora.
• Żądania mogą zawierać silent: true jako wskazówkę dla przepływów automatycznego zatwierdzania.
• node.pair.approve używa deklarowanych poleceń z oczekującego żądania, aby wymusić dodatkowe zakresy zatwierdzania:
  • żądanie bez poleceń: operator.pairing
  • żądanie polecenia innego niż exec: operator.pairing + operator.write
  • żądanie system.run / system.run.prepare / system.which: operator.pairing + operator.admin

Bramkowanie poleceń węzła (2026.3.31+)

Gdy węzeł łączy się po raz pierwszy, parowanie jest żądane automatycznie. Dopóki żądanie parowania nie zostanie zatwierdzone, wszystkie oczekujące polecenia węzła z tego węzła są filtrowane i nie zostaną wykonane. Po ustanowieniu zaufania przez zatwierdzenie parowania deklarowane polecenia węzła stają się dostępne zgodnie ze zwykłą polityką poleceń.

Oznacza to, że:

• Węzły, które wcześniej polegały wyłącznie na parowaniu urządzenia w celu udostępniania poleceń, muszą teraz ukończyć parowanie węzła.
• Polecenia kolejkowane przed zatwierdzeniem parowania są odrzucane, a nie odraczane.

Granice zaufania zdarzeń węzła (2026.3.31+)

Podsumowania pochodzące z węzłów i powiązane zdarzenia sesji są ograniczone do zamierzonej, zaufanej powierzchni. Przepływy sterowane powiadomieniami lub wyzwalane przez węzły, które wcześniej polegały na szerszym dostępie do narzędzi hosta lub sesji, mogą wymagać dostosowania. To utwardzenie zapewnia, że zdarzenia węzła nie mogą eskalować do dostępu do narzędzi na poziomie hosta poza tym, na co pozwala granica zaufania węzła.

Trwałe aktualizacje obecności węzła podążają za tą samą granicą tożsamości. Zdarzenie node.presence.alive jest akceptowane tylko z uwierzytelnionych sesji urządzeń węzłów i aktualizuje metadane parowania tylko wtedy, gdy tożsamość urządzenia/węzła jest już sparowana. Samodzielnie deklarowane wartości client.id nie wystarczą do zapisania stanu ostatniej aktywności.

Automatyczne zatwierdzanie (aplikacja macOS)

Aplikacja macOS może opcjonalnie próbować cichego zatwierdzenia, gdy:

• żądanie jest oznaczone jako silent, oraz
• aplikacja może zweryfikować połączenie SSH z hostem gateway przy użyciu tego samego użytkownika.

Jeśli ciche zatwierdzenie się nie powiedzie, następuje powrót do zwykłego monitu „Zatwierdź/Odrzuć”.

Automatyczne zatwierdzanie urządzeń z zaufanych CIDR

Parowanie urządzeń WS dla role: node domyślnie pozostaje ręczne. W prywatnych sieciach węzłów, w których Gateway już ufa ścieżce sieciowej, operatorzy mogą włączyć tę funkcję jawnie podanymi CIDR lub dokładnymi adresami IP:

{  gateway: {    nodes: {      pairing: {        autoApproveCidrs: ["192.168.1.0/24"],      },    },  },}

Granica bezpieczeństwa:

• Wyłączone, gdy gateway.nodes.pairing.autoApproveCidrs nie jest ustawione.
• Nie istnieje ogólny tryb automatycznego zatwierdzania dla LAN ani sieci prywatnych.
• Kwalifikuje się tylko świeże parowanie urządzenia z role: node bez żądanych zakresów.
• Klienty operatora, przeglądarki, Control UI i WebChat pozostają ręczne.
• Aktualizacje ról, zakresów, metadanych i kluczy publicznych pozostają ręczne.
• Ścieżki nagłówka zaufanego proxy przez same-host loopback nie kwalifikują się, ponieważ tę ścieżkę mogą podszyć lokalni wywołujący.

Automatyczne zatwierdzanie aktualizacji metadanych

Gdy już sparowane urządzenie ponownie łączy się wyłącznie ze zmianami metadanych niewrażliwych (na przykład nazwa wyświetlana lub wskazówki platformy klienta), OpenClaw traktuje to jako metadata-upgrade. Ciche automatyczne zatwierdzanie jest wąskie: dotyczy tylko zaufanych lokalnych ponownych połączeń nieprzeglądarkowych, które już udowodniły posiadanie lokalnych lub współdzielonych poświadczeń, w tym ponownych połączeń natywnej aplikacji na tym samym hoście po zmianach metadanych wersji systemu operacyjnego. Klienty przeglądarki/Control UI i klienty zdalne nadal używają jawnego przepływu ponownego zatwierdzania. Aktualizacje zakresów (read na write/admin) oraz zmiany klucza publicznego nie kwalifikują się do automatycznego zatwierdzania metadata-upgrade - pozostają jawnymi żądaniami ponownego zatwierdzenia.

Pomocniki parowania QR

/pair qr renderuje ładunek parowania jako ustrukturyzowane multimedia, aby klienty mobilne i przeglądarkowe mogły go bezpośrednio zeskanować.

Usunięcie urządzenia usuwa także wszelkie przestarzałe oczekujące żądania parowania dla tego identyfikatora urządzenia, więc nodes pending nie pokazuje osieroconych wierszy po cofnięciu.

Lokalność i przekazywane nagłówki

Parowanie Gateway traktuje połączenie jako loopback tylko wtedy, gdy zgadzają się zarówno surowe gniazdo, jak i dowody z każdego nadrzędnego proxy. Jeśli żądanie dociera przez loopback, ale niesie dowody w nagłówkach Forwarded, dowolnym X-Forwarded-* lub X-Real-IP, te dowody z przekazanych nagłówków dyskwalifikują deklarację lokalności loopback. Ścieżka parowania wymaga wtedy jawnego zatwierdzenia zamiast cicho traktować żądanie jako połączenie z tego samego hosta. Zobacz Uwierzytelnianie zaufanego proxy, aby poznać równoważną regułę dla uwierzytelniania operatora.

Przechowywanie (lokalne, prywatne)

Stan parowania jest przechowywany w katalogu stanu Gateway (domyślnie ~/.openclaw):

• ~/.openclaw/nodes/paired.json
• ~/.openclaw/nodes/pending.json

Jeśli nadpiszesz OPENCLAW_STATE_DIR, folder nodes/ przeniesie się razem z nim.

Uwagi dotyczące bezpieczeństwa:

• Tokeny są sekretami; traktuj paired.json jako wrażliwy.
• Rotacja tokenu wymaga ponownego zatwierdzenia (lub usunięcia wpisu węzła).

Zachowanie transportu

• Transport jest bezstanowy; nie przechowuje członkostwa.
• Jeśli Gateway jest offline albo parowanie jest wyłączone, węzły nie mogą się parować.
• Jeśli Gateway działa w trybie zdalnym, parowanie nadal odbywa się względem magazynu zdalnego Gateway.

Powiązane

• Parowanie kanału
• Węzły
• CLI urządzeń