Integracje Gateway dla aplikacji zewnętrznych

Aplikacje zewnętrzne komunikują się z OpenClaw za pośrednictwem protokołu Gateway: transportu WebSocket oraz metod RPC. Użyj go, gdy skrypt, pulpit, zadanie CI, rozszerzenie IDE lub inny proces chce uruchamiać wykonania agentów, strumieniować zdarzenia, oczekiwać na wyniki, anulować pracę albo przeglądać zasoby Gateway.

Co jest obecnie dostępne

Prace nad przyszłym pakietem biblioteki klienckiej trwają wewnętrznie, ale nie jest on jeszcze publicznie dostępny do instalacji. Traktuj go jako szczegół implementacyjny wersji zapoznawczej, dopóki wydanie nie ogłosi opublikowanego, wersjonowanego pakietu.

Zalecana ścieżka

1. Uruchom lub wykryj Gateway.
2. Połącz się za pomocą protokołu Gateway.
3. Wywołuj udokumentowane metody RPC z dokumentacji RPC Gateway.
4. Przypnij testowaną wersję OpenClaw.
5. Po aktualizacji OpenClaw ponownie sprawdź dokumentację RPC.

W przypadku wykonań agentów zacznij od RPC agent i połącz je z agent.wait, aby uzyskać wynik końcowy. Do trwałego przechowywania stanu konwersacji używaj metod sessions.*. W integracjach interfejsu użytkownika subskrybuj zdarzenia Gateway i renderuj wyłącznie rodziny zdarzeń obsługiwane przez aplikację.

Kooperacyjne wstrzymywanie hosta

Kontrolery hostingu, które zamrażają działający proces lub tworzą jego migawkę, mogą korzystać z niezależnego od hosta uzgadniania wstrzymania:

1. Przestań przyjmować zewnętrzny ruch przychodzący kontrolowany przez hosta.
2. Wywołaj gateway.suspend.prepare ze stabilnym, unikatowym identyfikatorem requestId.
3. Jeśli odpowiedzią jest busy, pozostaw proces uruchomiony i ponów próbę później.
4. Jeśli odpowiedzią jest ready, zapisz zwrócony identyfikator suspensionId, a następnie zamroź proces lub utwórz jego migawkę przed czasem expiresAtMs.
5. Po wznowieniu albo po rezygnacji ze wstrzymania wywołaj gateway.suspend.resume z tym identyfikatorem suspensionId przez istniejące połączenie WebSocket lub ścieżkę sterowania Admin HTTP.

Przygotowany Gateway odrzuca nowe uzgadniania WebSocket. Kontroler WebSocket musi utrzymać otwarte uwierzytelnione połączenie przez cały czas operacji hosta. Jeśli nie można tego zagwarantować, przed przygotowaniem włącz i użyj Pluginu RPC Admin HTTP. Jeśli ścieżka sterowania zostanie utracona, przed ponownym połączeniem poczekaj na wygaśnięcie dwuminutowej dzierżawy; po wygaśnięciu przyjmowanie połączeń zostanie automatycznie wznowione.

Kontrakt RPC wygląda następująco:

• gateway.suspend.prepare — operator.admin; parametry { "requestId": "stable-host-operation-id" }
• gateway.suspend.status — operator.read; parametry { "suspensionId": "id-from-prepare" }
• gateway.suspend.resume — operator.admin; parametry { "suspensionId": "id-from-prepare" }

Identyfikatory są przycinane, muszą zawierać znak inny niż biały i są ograniczone do 128 znaków. Wynik zajętości przygotowania ma status: "busy", reason, retryAfterMs, activeCount oraz blockers. Wynik gotowości ma następującą postać:

{  "status": "ready",  "suspensionId": "2c3f...",  "expiresAtMs": 1770000000000,  "activeCount": 0,  "blockers": []}

Zapytanie o stan zwraca {"status":"running"} albo wynik gotowości z expiresAtMs. Wznowienie zwraca {"ok":true,"status":"running","resumed":true}; ponowne wywołanie po pomyślnym wznowieniu zwraca resumed: false.

Konkurencyjny identyfikator żądania lub przejściowy błąd wznowienia harmonogramu zwraca możliwy do ponowienia błąd UNAVAILABLE z retryAfterMs. Podczas odzyskiwania harmonogramu operacje przygotowania, sprawdzania stanu i wznowienia zwracają ten błąd, Gateway pozostaje niegotowy i działa w trybie bezpiecznego zamknięcia, a host nie może go zamrażać ani tworzyć jego migawki. OpenClaw automatycznie ponawia próbę uruchomienia harmonogramu i wznawia przyjmowanie połączeń dopiero po pomyślnym odzyskaniu. Niedopasowany identyfikator wznowienia zwraca INVALID_REQUEST. Przygotowanie korzysta ze wspólnego budżetu zapisu płaszczyzny sterowania Gateway wynoszącego trzy próby na minutę; przestrzegaj zwróconego opóźnienia ponowienia. Klienci WebSocket są grupowani według urządzenia i adresu IP. Kontrolery Admin HTTP są grupowane według ustalonego adresu IP klienta, dlatego kontrolery za jednym serwerem proxy mogą współdzielić budżet.

Przygotowanie służy wyłącznie do odmowy: OpenClaw zamyka przyjmowanie nowych operacji głównych, sesji i poleceń, wstrzymuje automatyczne cykle Cron oraz synchronicznie sprawdza wykonywaną pracę. Jeśli cokolwiek jest aktywne, wznawia harmonogram i ponownie otwiera przyjmowanie operacji przed zwróceniem busy; nie przerywa ani nie opróżnia tej pracy. Gotowa dzierżawa trwa dwie minuty. Ponowne wywołanie prepare z tym samym requestId odnawia ją; wygaśnięcie wznawia harmonogram przed ponownym otwarciem przyjmowania operacji. Emisja ponownego uruchomienia, której termin przypada podczas gotowej dzierżawy, czeka na jej wznowienie; trwające ponowne uruchomienie powoduje, że przygotowanie zwraca busy.

W stanie gotowości /healthz nadal działa, a /readyz zwraca 503. Lokalne lub uwierzytelnione odpowiedzi dotyczące gotowości zawierają gateway-draining; nieuwierzytelnione zdalne sondy otrzymują wyłącznie { "ready": false }. Sonda kondycji HTTP, metody wstrzymania na istniejących połączeniach WebSocket oraz wcześniej włączona trasa RPC Admin HTTP pozostają dostępne. Inne wywołania RPC zwracają możliwy do ponowienia błąd UNAVAILABLE. Wbudowane trasy HTTP obsługujące pracę użytkownika i zwykłe trasy HTTP Pluginów, w tym interfejsy API zgodne z OpenAI, operacje narzędzi i sesji, obserwacje Node oraz skonfigurowane punkty zaczepienia, zwracają 503 z error.code: "gateway_unavailable". Nowe uaktualnienia WebSocket należące do Pluginów również zwracają 503; obejmuje to własność uaktualnienia, a nie pracę wykonywaną później przez ustanowione gniazdo Pluginu.

To uzgadnianie nie utrwala wiadomości przychodzących, nie zatrzymuje transportów kanałów innych firm ani nie steruje platformą hostingową. Host musi odgrodzić ruch przychodzący przed przygotowaniem i pozostaje odpowiedzialny za wybudzanie, tworzenie migawek lub zamrażanie oraz zatrzymywanie. activeCount to łączna liczba śledzonych prac, natomiast blockers zawiera niezerowe liczby kategorii i ograniczone szczegóły zadań. Nie jest to ogólna bariera bezczynności procesu. Blokada background-exec ma wyłącznie charakter zbiorczy: tekst poleceń, identyfikatory procesów, dane wyjściowe oraz identyfikatory sesji lub zakresów nigdy nie przechodzą przez protokół. Kondycja kanałów, konserwacja, odświeżanie pamięci podręcznej, ustanowione sesje WebSocket Pluginów oraz niezarejestrowana praca w tle należąca do Pluginów mogą pozostać aktywne. Platforma hostingowa musi spójnie zamrozić pełne drzewo procesów i jego system plików lub utworzyć ich migawkę; ten pierwszy kontrakt nie może potwierdzić bezczynności niezarejestrowanej pracy.

Kod aplikacji a kod Pluginu

Używaj RPC Gateway, gdy kod działa poza OpenClaw:

• skrypty Node uruchamiające lub obserwujące wykonania agentów
• zadania CI wywołujące Gateway
• pulpity i panele administracyjne
• rozszerzenia IDE
• zewnętrzne mosty, które nie muszą stawać się Pluginami kanałów
• testy integracyjne z fikcyjnymi lub rzeczywistymi transportami Gateway

Używaj Plugin SDK, gdy kod działa wewnątrz OpenClaw:

• Pluginy dostawców
• Pluginy kanałów
• punkty zaczepienia narzędzi lub cyklu życia
• Pluginy środowiska wykonawczego agentów
• zaufane pomocnicze komponenty środowiska wykonawczego

Aplikacje zewnętrzne nie powinny importować openclaw/plugin-sdk/*; te ścieżki podrzędne są przeznaczone dla Pluginów ładowanych przez OpenClaw.

Powiązane materiały

• Protokół Gateway
• Dokumentacja RPC Gateway
• Polecenie agenta CLI
• Polecenie wiadomości CLI
• Pętla agenta
• Środowiska wykonawcze agentów
• Sesje
• Zadania w tle
• Agenci ACP
• Omówienie Plugin SDK