Protokół Gateway WS jest jedną płaszczyzną sterowania + transportem węzłów dla OpenClaw. Wszyscy klienci (CLI, interfejs WWW, aplikacja macOS, węzły iOS/Android, węzły bezinterfejsowe) łączą się przez WebSocket i deklarują swoją rolę oraz zakres podczas uzgadniania połączenia.Documentation Index
Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt
Use this file to discover all available pages before exploring further.
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.maxPayloadorazhello-ok.policy.maxBufferedBytes. Gdy diagnostyka jest włączona, zbyt duże ramki przychodzące i powolne bufory wychodzące emitują zdarzeniapayload.largezanim Gateway zamknie lub odrzuci daną ramkę. Te zdarzenia zachowują rozmiary, limity, powierzchnie i bezpieczne kody powodów. Nie zachowują treści wiadomości, zawartości załączników, surowej treści ramki, tokenów, ciasteczek ani wartości tajnych.
Uzgadnianie połączenia (connect)
Gateway → Klient (wyzwanie przed połączeniem):connect może
zwrócić ponawialny błąd UNAVAILABLE z details.reason ustawionym na
"startup-sidecars" oraz retryAfterMs. Klienci powinni ponowić taką odpowiedź
w ramach swojego ogólnego budżetu połączenia zamiast pokazywać ją jako końcową
awarię uzgadniania połączenia.
server, features, snapshot i policy są wymagane przez schemat
(src/gateway/protocol/schema/frames.ts). auth także jest wymagane i raportuje
wynegocjowaną rolę/zakresy. pluginSurfaceUrls jest opcjonalne i mapuje nazwy
powierzchni pluginów, takie jak canvas, na zakresowane hostowane adresy URL.
Zakresowane 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 refaktoryzacja pluginu Canvas nie
obsługuje przestarzałej ścieżki zgodności canvasHostUrl, canvasCapability ani
node.canvas.capability.refresh; aktualni klienci natywni i Gateway muszą używać powierzchni pluginów.
Gdy token urządzenia nie zostanie wydany, hello-ok.auth raportuje wynegocjowane
uprawnienia bez pól tokenu:
client.id: "gateway-client",
client.mode: "backend") mogą pomijać device w bezpośrednich połączeniach loopback, gdy
uwierzytelniają się współdzielonym tokenem/hasłem Gateway. 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ądzenia. 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ą zwykłych kontroli parowania i podnoszenia zakresu.
Gdy token urządzenia zostanie wydany, hello-ok zawiera także:
hello-ok.auth może również zawierać dodatkowe
ograniczone wpisy ról w deviceTokens:
scopes: [], a każdy przekazany token operatora pozostaje ograniczony do listy dozwolonych
zakresów operatora bootstrap (operator.approvals, operator.read,
operator.talk.secrets, operator.write). Kontrole zakresu bootstrap pozostają
prefiksowane rolą: wpisy operatora spełniają tylko żądania operatora, a role inne niż operator
nadal wymagają zakresów z prefiksem własnej roli.
Przykład Node
Ramkowanie
- Żądanie:
{type:"req", id, method, params} - Odpowiedź:
{type:"res", id, ok, payload|error} - Zdarzenie:
{type:"event", event, payload, seq?, stateVersion?}
Role + zakresy
Pełny model zakresów operatora, kontrole w czasie zatwierdzania oraz semantykę współdzielonego sekretu opisano w Zakresach 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.readoperator.writeoperator.adminoperator.approvalsoperator.pairingoperator.talk.secrets
talk.config z includeSecrets: true wymaga operator.talk.secrets
(lub operator.admin).
Metody RPC Gateway zarejestrowane przez plugin mogą żądać własnego zakresu operatora, ale
zarezerwowane podstawowe prefiksy administracyjne (config.*, exec.approvals.*, wizard.*,
update.*) zawsze rozstrzygają się do operator.admin.
Zakres metody jest tylko pierwszą bramką. Niektóre polecenia ukośnikowe osiągane przez
chat.send stosują dodatkowo surowsze kontrole na poziomie polecenia. Na przykład trwałe
zapisy /config set i /config unset wymagają operator.admin.
node.pair.approve ma także dodatkową kontrolę zakresu w czasie zatwierdzania, oprócz
bazowego zakresu 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.preparelubsystem.which:operator.pairing+operator.admin
Możliwości/polecenia/uprawnienia (węzeł)
Węzły deklarują roszczenia możliwości podczas łączenia:caps: wysokopoziomowe kategorie możliwości, takie jakcamera,canvas,screen,location,voiceitalk.commands: lista dozwolonych poleceń dla invoke.permissions: szczegółowe przełączniki (np.screen.record,camera.capture).
Obecność
system-presencezwraca wpisy indeksowane tożsamością urządzenia.- Wpisy obecności obejmują
deviceId,rolesiscopes, aby UI mogły pokazać jeden wiersz na urządzenie nawet wtedy, gdy łączy się ono zarówno jako operator, jak i node. node.listzawiera opcjonalne polalastSeenAtMsilastSeenReason. Połączone węzły raportują swój bieżący czas połączenia jakolastSeenAtMsz powodemconnect; sparowane węzły mogą także raportować trwałą obecność w tle, gdy zaufane zdarzenie węzła aktualizuje ich metadane parowania.
Zdarzenie działania 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.
trigger jest zamkniętym enum: background, silent_push, bg_app_refresh,
significant_location, manual lub connect. Nieznane ciągi wyzwalacza są normalizowane przez
Gateway do background 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 Gateway zwracają ustrukturyzowany wynik:
{ "ok": true } dla node.event; klienci powinni traktować to jako
potwierdzone RPC, a nie jako trwałe utrwalenie obecności.
Zakresowanie zdarzeń broadcast
Zdarzenia broadcast wypychane przez serwer przez WebSocket są ograniczane zakresem, aby sesje ograniczone do parowania lub tylko węzłowe nie odbierały pasywnie treści sesji.- Ramki czatu, agenta i wyników narzędzi (w tym strumieniowane zdarzenia
agenti wyniki wywołań narzędzi) wymagają co najmniejoperator.read. Sesje bezoperator.readcałkowicie pomijają te ramki. - Broadcasty
plugin.*zdefiniowane przez pluginy są bramkowane dooperator.writeluboperator.admin, zależnie od sposobu ich zarejestrowania przez plugin. - Zdarzenia statusu i transportu (
heartbeat,presence,tick, cykl życia connect/disconnect itd.) pozostają nieograniczone, aby kondycja transportu była obserwowalna dla każdej uwierzytelnionej sesji. - Nieznane rodziny zdarzeń broadcast są domyślnie bramkowane zakresem (fail-closed), chyba że zarejestrowany handler jawnie je rozluźnia.
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 to konserwatywna
lista wykrywania zbudowana 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.
System i tożsamość
System i tożsamość
healthzwraca zbuforowany lub świeżo sprawdzony snapshot kondycji Gateway.diagnostics.stabilityzwraca ostatni ograniczony rejestrator stabilności diagnostycznej. Zachowuje metadane operacyjne, takie jak nazwy zdarzeń, liczby, rozmiary bajtowe, odczyty pamięci, stan kolejki/sesji, nazwy kanałów/pluginów oraz identyfikatory sesji. Nie zachowuje tekstu czatu, treści webhooków, wyników narzędzi, surowych treści żądań lub odpowiedzi, tokenów, ciasteczek ani wartości tajnych. Wymagany jest zakres odczytu operatora.statuszwraca podsumowanie Gateway w stylu/status; pola wrażliwe są uwzględniane tylko dla klientów operatora z zakresem administracyjnym.gateway.identity.getzwraca tożsamość urządzenia Gateway używaną przez przepływy relay i parowania.system-presencezwraca bieżący snapshot obecności dla połączonych urządzeń operatora/węzła.system-eventdopisuje zdarzenie systemowe i może aktualizować/rozgłaszać kontekst obecności.last-heartbeatzwraca najnowsze utrwalone zdarzenie heartbeat.set-heartbeatsprzełącza przetwarzanie heartbeat w Gateway.
Modele i użycie
Modele i użycie
models.listzwraca katalog modeli dozwolonych w środowisku uruchomieniowym. Przekaż{ "view": "configured" }dla skonfigurowanych modeli o rozmiarze odpowiednim dla selektora (agents.defaults.modelsnajpierw, potemmodels.providers.*.models) albo{ "view": "all" }dla pełnego katalogu.usage.statuszwraca okna użycia dostawcy/podsumowania pozostałego limitu.usage.costzwraca zagregowane podsumowania kosztów użycia dla zakresu dat.doctor.memory.statuszwraca gotowość pamięci wektorowej / buforowanych embeddingów dla aktywnego domyślnego obszaru roboczego agenta. Przekaż{ "probe": true }lub{ "deep": true }tylko wtedy, gdy wywołujący jawnie chce ping do aktywnego dostawcy embeddingów.doctor.memory.remHarnesszwraca ograniczony, tylko do odczytu podgląd wiązki testowej REM dla zdalnych klientów płaszczyzny sterowania. Może zawierać ścieżki obszaru roboczego, fragmenty pamięci, wyrenderowany ugruntowany markdown oraz kandydatów do głębokiej promocji, więc wywołujący potrzebująoperator.read.sessions.usagezwraca podsumowania użycia dla poszczególnych sesji.sessions.usage.timeserieszwraca szeregi czasowe użycia dla jednej sesji.sessions.usage.logszwraca wpisy dziennika użycia dla jednej sesji.
Kanały i pomocniki logowania
Kanały i pomocniki logowania
channels.statuszwraca podsumowania statusu wbudowanych + dołączonych kanałów/Plugin.channels.logoutwylogowuje z określonego kanału/konta, jeśli kanał obsługuje wylogowanie.web.login.starturuchamia przepływ logowania QR/web dla bieżącego dostawcy kanału web obsługującego QR.web.login.waitczeka na ukończenie tego przepływu logowania QR/web i uruchamia kanał po powodzeniu.push.testwysyła testowe powiadomienie push APNs do zarejestrowanego węzła iOS.voicewake.getzwraca zapisane wyzwalacze słowa wybudzającego.voicewake.setaktualizuje wyzwalacze słowa wybudzającego i rozgłasza zmianę.
Wiadomości i dzienniki
Wiadomości i dzienniki
sendto bezpośrednie RPC dostarczania wychodzącego dla wysyłek kierowanych do kanału/konta/wątku poza wykonawcą czatu.logs.tailzwraca ogon skonfigurowanego dziennika plikowego Gateway z kontrolkami kursora/limitu i maksymalnej liczby bajtów.
Talk i TTS
Talk i TTS
talk.catalogzwraca tylko do odczytu katalog dostawców Talk dla mowy, transkrypcji strumieniowej i głosu w czasie rzeczywistym. Zawiera identyfikatory dostawców, etykiety, stan konfiguracji, ujawnione identyfikatory modeli/głosów, tryby kanoniczne, transporty, strategie mózgu oraz flagi audio/możliwości czasu rzeczywistego bez zwracania sekretów dostawcy ani modyfikowania konfiguracji globalnej.talk.configzwraca efektywny ładunek konfiguracji Talk;includeSecretswymagaoperator.talk.secrets(luboperator.admin).talk.session.createtworzy sesję Talk posiadaną przez Gateway dlarealtime/gateway-relay,transcription/gateway-relaylubstt-tts/managed-room.brain: "direct-tools"wymagaoperator.admin.talk.session.joinweryfikuje token sesji zarządzanego pokoju, emituje zdarzeniasession.readylubsession.replacedwedług potrzeb oraz zwraca metadane pokoju/sesji wraz z ostatnimi zdarzeniami Talk bez tokenu w postaci jawnej ani zapisanego skrótu tokenu.talk.session.appendAudiodołącza wejściowy dźwięk PCM base64 do sesji przekaźnika czasu rzeczywistego i transkrypcji posiadanych przez Gateway.talk.session.startTurn,talk.session.endTurnitalk.session.cancelTurnsterują cyklem życia tury w zarządzanym pokoju z odrzuceniem nieaktualnej tury przed wyczyszczeniem stanu.talk.session.cancelOutputzatrzymuje wyjściowy dźwięk asystenta, głównie dla wejścia w trakcie wypowiedzi bramkowanego przez VAD w sesjach przekaźnika Gateway.talk.session.submitToolResultkończy wywołanie narzędzia dostawcy wyemitowane przez sesję przekaźnika czasu rzeczywistego posiadaną przez Gateway. Przekażoptions: { willContinue: true }dla tymczasowego wyjścia narzędzia, gdy wynik końcowy pojawi się później, albooptions: { suppressResponse: true }, gdy wynik narzędzia powinien zaspokoić wywołanie dostawcy bez uruchamiania kolejnej odpowiedzi asystenta w czasie rzeczywistym.talk.session.closezamyka sesję przekaźnika, transkrypcji lub zarządzanego pokoju posiadaną przez Gateway i emituje końcowe zdarzenia Talk.talk.modeustawia/rozgłasza bieżący stan trybu Talk dla klientów WebChat/Control UI.talk.client.createtworzy sesję dostawcy czasu rzeczywistego posiadaną przez klienta przy użyciuwebrtclubprovider-websocket, podczas gdy Gateway posiada konfigurację, poświadczenia, instrukcje i politykę narzędzi.talk.client.toolCallpozwala transportom czasu rzeczywistego posiadanym przez klienta przekazywać wywołania narzędzi dostawcy do polityki Gateway. Pierwszym obsługiwanym narzędziem jestopenclaw_agent_consult; klienci otrzymują identyfikator uruchomienia i czekają na normalne zdarzenia cyklu życia czatu przed przesłaniem wyniku narzędzia specyficznego dla dostawcy.talk.eventto pojedynczy kanał zdarzeń Talk dla adapterów czasu rzeczywistego, transkrypcji, STT/TTS, zarządzanego pokoju, telefonii i spotkań.talk.speaksyntetyzuje mowę przez aktywnego dostawcę mowy Talk.tts.statuszwraca stan włączenia TTS, aktywnego dostawcę, dostawców awaryjnych i stan konfiguracji dostawcy.tts.providerszwraca widoczny inwentarz dostawców TTS.tts.enableitts.disableprzełączają stan preferencji TTS.tts.setProvideraktualizuje preferowanego dostawcę TTS.tts.converturuchamia jednorazową konwersję tekstu na mowę.
Sekrety, konfiguracja, aktualizacja i kreator
Sekrety, konfiguracja, aktualizacja i kreator
secrets.reloadponownie rozwiązuje aktywne SecretRefs i podmienia stan sekretów środowiska uruchomieniowego tylko po pełnym powodzeniu.secrets.resolverozwiązuje przypisania sekretów docelowych dla polecenia dla określonego zestawu polecenie/cel.config.getzwraca bieżącą migawkę konfiguracji i skrót.config.setzapisuje zweryfikowany ładunek konfiguracji.config.patchscala częściową aktualizację konfiguracji.config.applyweryfikuje + zastępuje pełny ładunek konfiguracji.config.schemazwraca aktywny ładunek schematu konfiguracji używany przez narzędzia Control UI i CLI: schemat,uiHints, wersję oraz metadane generowania, w tym metadane schematu Plugin + kanału, gdy środowisko uruchomieniowe może je załadować. Schemat zawiera metadane póltitle/descriptionwyprowadzone z tych samych etykiet i tekstu pomocy używanych przez UI, w tym zagnieżdżone gałęzie obiektów, wieloznaczników, elementów tablicy oraz kompozycjianyOf/oneOf/allOf, gdy istnieje pasująca dokumentacja pól.config.schema.lookupzwraca ładunek wyszukiwania ograniczony do ścieżki dla jednej ścieżki konfiguracji: znormalizowaną ścieżkę, płytki węzeł schematu, dopasowaną wskazówkę +hintPathoraz podsumowania bezpośrednich elementów podrzędnych do przechodzenia w głąb w UI/CLI. Węzły schematu wyszukiwania zachowują dokumentację widoczną dla użytkownika i wspólne pola walidacji (title,description,type,enum,const,format,pattern, ograniczenia liczbowe/ciągów/tablic/obiektów oraz flagi takie jakadditionalProperties,deprecated,readOnly,writeOnly). Podsumowania elementów podrzędnych ujawniająkey, znormalizowanepath,type,required,hasChildrenoraz dopasowanehint/hintPath.update.runuruchamia przepływ aktualizacji Gateway i planuje restart tylko wtedy, gdy sama aktualizacja się powiodła; wywołujący z sesją mogą dołączyćcontinuationMessage, aby po uruchomieniu wznowić jedną kolejną turę agenta przez kolejkę kontynuacji restartu. Aktualizacje menedżera pakietów wymuszają nieodroczony restart aktualizacyjny bez okresu wyciszenia po podmianie pakietu, aby stary proces Gateway nie ładował leniwie dalej z zastąpionego drzewadist.update.statuszwraca najnowszy buforowany znacznik restartu aktualizacji, w tym działającą wersję po restarcie, gdy jest dostępna.wizard.start,wizard.next,wizard.statusiwizard.canceludostępniają kreator wdrażania przez WS RPC.
Pomocniki agenta i obszaru roboczego
Pomocniki agenta i obszaru roboczego
agents.listzwraca skonfigurowane wpisy agentów, w tym efektywny model i metadane środowiska uruchomieniowego.agents.create,agents.updateiagents.deletezarządzają rekordami agentów i okablowaniem obszaru roboczego.agents.files.list,agents.files.getiagents.files.setzarządzają plikami obszaru roboczego inicjalizacji udostępnianymi agentowi.tasks.list,tasks.getitasks.canceludostępniają rejestr zadań Gateway klientom SDK i operatora.artifacts.list,artifacts.getiartifacts.downloadudostępniają podsumowania artefaktów pochodzących z transkrypcji oraz pobrania dla jawnego zakresusessionKey,runIdlubtaskId. Zapytania o uruchomienia i zadania rozwiązują sesję właściciela po stronie serwera i zwracają tylko media transkrypcji z pasującą proweniencją; niebezpieczne lub lokalne źródła URL zwracają nieobsługiwane pobrania zamiast pobierania po stronie serwera.environments.listienvironments.statusudostępniają klientom SDK tylko do odczytu wykrywanie środowisk lokalnych Gateway i węzłów.agent.identity.getzwraca efektywną tożsamość asystenta dla agenta lub sesji.agent.waitczeka na zakończenie uruchomienia i zwraca końcową migawkę, gdy jest dostępna.
Kontrola sesji
Kontrola sesji
sessions.listzwraca bieżący indeks sesji, w tym metadaneagentRuntimedla każdego wiersza, gdy skonfigurowano backend środowiska uruchomieniowego agenta.sessions.subscribeisessions.unsubscribeprzełączają subskrypcje zdarzeń zmian sesji dla bieżącego klienta WS.sessions.messages.subscribeisessions.messages.unsubscribeprzełączają subskrypcje zdarzeń transkrypcji/wiadomości dla jednej sesji.sessions.previewzwraca ograniczone podglądy transkrypcji dla określonych kluczy sesji.sessions.describezwraca jeden wiersz sesji Gateway dla dokładnego klucza sesji.sessions.resolverozwiązuje lub kanonikalizuje cel sesji.sessions.createtworzy nowy wpis sesji.sessions.sendwysyła wiadomość do istniejącej sesji.sessions.steerto wariant przerwania i pokierowania dla aktywnej sesji.sessions.abortprzerywa aktywną pracę dla sesji. Wywołujący może przekazaćkeyplus opcjonalnerunId, albo samorunIddla aktywnych uruchomień, które Gateway może rozwiązać do sesji.sessions.patchaktualizuje metadane/nadpisania sesji i raportuje rozwiązany model kanoniczny oraz efektywneagentRuntime.sessions.reset,sessions.deleteisessions.compactwykonują konserwację sesji.sessions.getzwraca pełny zapisany wiersz sesji.- Wykonywanie czatu nadal używa
chat.history,chat.send,chat.abortichat.inject.chat.historyjest normalizowane do wyświetlania dla klientów UI: wbudowane tagi dyrektyw są usuwane z widocznego tekstu, ładunki XML wywołań narzędzi w zwykłym tekście (w tym<tool_call>...</tool_call>,<function_call>...</function_call>,<tool_calls>...</tool_calls>,<function_calls>...</function_calls>i ucięte bloki wywołań narzędzi) oraz ujawnione tokeny sterujące modelu ASCII/pełnej szerokości są usuwane, czyste wiersze asystenta z cichymi tokenami, takie jak dokładneNO_REPLY/no_reply, są pomijane, a zbyt duże wiersze mogą być zastępowane symbolami zastępczymi.
Parowanie urządzeń i tokeny urządzeń
Parowanie urządzeń i tokeny urządzeń
device.pair.listzwraca oczekujące i zatwierdzone sparowane urządzenia.device.pair.approve,device.pair.rejectidevice.pair.removezarządzają rekordami parowania urządzeń.device.token.rotaterotuje token sparowanego urządzenia w granicach jego zatwierdzonej roli i zakresu wywołującego.device.token.revokeunieważnia token sparowanego urządzenia w granicach jego zatwierdzonej roli i zakresu wywołującego.
Parowanie węzłów, wywoływanie i oczekująca praca
Parowanie węzłów, wywoływanie i oczekująca praca
node.pair.request,node.pair.list,node.pair.approve,node.pair.reject,node.pair.removeinode.pair.verifyobejmują parowanie węzłów i weryfikację inicjalizacji.node.listinode.describezwracają stan znanych/połączonych węzłów.node.renameaktualizuje etykietę sparowanego węzła.node.invokeprzekazuje polecenie do połączonego węzła.node.invoke.resultzwraca wynik żądania wywołania.node.eventprzenosi zdarzenia pochodzące z węzła z powrotem do Gateway.node.pending.pullinode.pending.ackto API kolejki połączonego węzła.node.pending.enqueueinode.pending.drainzarządzają trwałą oczekującą pracą dla węzłów offline/rozłączonych.
Rodziny zatwierdzeń
Rodziny zatwierdzeń
exec.approval.request,exec.approval.get,exec.approval.listiexec.approval.resolveobsługują jednorazowe żądania zatwierdzenia wykonania oraz wyszukiwanie/ponowne odtwarzanie oczekujących zatwierdzeń.exec.approval.waitDecisionczeka na jedno oczekujące zatwierdzenie wykonania i zwraca ostateczną decyzję (lubnullpo przekroczeniu limitu czasu).exec.approvals.getiexec.approvals.setzarządzają migawkami polityki zatwierdzania wykonań Gateway.exec.approvals.node.getiexec.approvals.node.setzarządzają lokalną dla węzła polityką zatwierdzania wykonań za pomocą poleceń przekazywania węzła.plugin.approval.request,plugin.approval.list,plugin.approval.waitDecisioniplugin.approval.resolveobsługują przepływy zatwierdzania definiowane przez plugin.
Automatyzacja, Skills i narzędzia
Automatyzacja, Skills i narzędzia
- Automatyzacja:
wakeplanuje natychmiastowe lub przy następnym Heartbeat wstrzyknięcie tekstu wybudzenia;cron.get,cron.list,cron.status,cron.add,cron.update,cron.remove,cron.run,cron.runszarządzają zaplanowaną pracą. - Skills i narzędzia:
commands.list,skills.*,tools.catalog,tools.effective,tools.invoke.
Typowe rodziny zdarzeń
chat: aktualizacje czatu UI, takie jakchat.inject, oraz inne zdarzenia czatu dotyczące wyłącznie transkrypcji.session.messageisession.tool: aktualizacje transkrypcji/strumienia zdarzeń dla subskrybowanej sesji.sessions.changed: zmieniono indeks sesji lub metadane.presence: aktualizacje migawki obecności systemu.tick: okresowe zdarzenie keepalive / żywotności.health: aktualizacja migawki kondycji 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: emisja żą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ła
- Węzły mogą wywoływać
skills.bins, aby pobrać bieżącą listę plików wykonywalnych skill na potrzeby kontroli automatycznego zezwalania.
RPC rejestru zadań
Klienci operatora mogą przeglądać i anulować rekordy zadań w tle Gateway za pomocą RPC rejestru zadań. Te metody zwracają oczyszczone podsumowania zadań, a nie surowy stan runtime.tasks.listwymagaoperator.read.- Parametry: opcjonalny
status("queued","running","completed","failed","cancelled"lub"timed_out") albo tablica tych statusów, opcjonalnyagentId, opcjonalnysessionKey, opcjonalnylimitod1do500oraz opcjonalny ciągcursor. - Wynik:
{ "tasks": TaskSummary[], "nextCursor"?: string }.
- Parametry: opcjonalny
tasks.getwymagaoperator.read.- Parametry:
{ "taskId": string }. - Wynik:
{ "task": TaskSummary }. - Brakujące identyfikatory zadań zwracają kształt błędu Gateway typu not-found.
- Parametry:
tasks.cancelwymagaoperator.write.- Parametry:
{ "taskId": string, "reason"?: string }. - Wynik:
{ "found": boolean, "cancelled": boolean, "reason"?: string, "task"?: TaskSummary }. foundinformuje, czy rejestr zawierał pasujące zadanie.cancelledinformuje, czy runtime zaakceptował albo zarejestrował anulowanie.
- Parametry:
TaskSummary zawiera id, status oraz opcjonalne metadane, takie jak kind,
runtime, title, agentId, sessionKey, childSessionKey, ownerKey,
runId, taskId, flowId, parentTaskId, sourceId, znaczniki czasu, postęp,
końcowe podsumowanie oraz oczyszczony tekst błędu.
Metody pomocnicze operatora
- Operatorzy mogą wywołać
commands.list(operator.read), aby pobrać inwentarz poleceń runtime dla agenta.agentIdjest opcjonalne; pomiń je, aby odczytać domyślny obszar roboczy agenta.scopekontroluje, do której powierzchni odnosi się podstawowa wartośćname:textzwraca podstawowy token polecenia tekstowego bez początkowego/nativei domyślna ścieżkabothzwracają natywne nazwy świadome providera, gdy są dostępne
textAliasesprzenosi dokładne aliasy ukośnikowe, takie jak/modeli/m.nativeNameprzenosi natywną nazwę polecenia świadomą providera, gdy taka istnieje.providerjest opcjonalne i wpływa tylko na nazewnictwo natywne oraz dostępność natywnych poleceń plugin.includeArgs=falsepomija zserializowane metadane argumentów w odpowiedzi.
- Operatorzy mogą wywołać
tools.catalog(operator.read), aby pobrać katalog narzędzi runtime dla agenta. Odpowiedź zawiera pogrupowane narzędzia oraz metadane pochodzenia:source:corelubpluginpluginId: właściciel plugin, gdysource="plugin"optional: czy narzędzie plugin jest opcjonalne
- Operatorzy mogą wywołać
tools.effective(operator.read), aby pobrać efektywny w runtime inwentarz narzędzi dla sesji.sessionKeyjest wymagane.- Gateway wyprowadza zaufany kontekst runtime z sesji po stronie serwera, zamiast akceptować kontekst uwierzytelniania lub dostarczania podany przez wywołującego.
- Odpowiedź jest ograniczona do sesji i odzwierciedla to, czego aktywna rozmowa może użyć teraz, w tym narzędzia core, plugin i kanału.
- Operatorzy mogą wywołać
tools.invoke(operator.write), aby wywołać jedno dostępne narzędzie przez tę samą ścieżkę polityki gateway co/tools/invoke.namejest wymagane.args,sessionKey,agentId,confirmiidempotencyKeysą opcjonalne.- Jeśli obecne są jednocześnie
sessionKeyiagentId, rozwiązany agent sesji musi pasować doagentId. - Odpowiedź jest kopertą przeznaczoną dla SDK z polami
ok,toolName, opcjonalnymoutputoraz typowanymi polamierror. Odmowy wynikające z zatwierdzeń lub polityki zwracająok:falsew ładunku, zamiast omijać potok polityki narzędzi gateway.
- Operatorzy mogą wywołać
skills.status(operator.read), aby pobrać widoczny inwentarz skill dla agenta.agentIdjest 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.searchiskills.detail(operator.read) dla metadanych odkrywania ClawHub. - Operatorzy mogą wywołać
skills.upload.begin,skills.upload.chunkiskills.upload.commit(operator.admin), aby przygotować prywatne archiwum skill przed jego instalacją. Jest to osobna ścieżka przesyłania administracyjnego dla zaufanych klientów, a nie zwykły przepływ instalowania skill z ClawHub, i jest domyślnie wyłączona, chyba że włączonoskills.install.allowUploadedArchives.skills.upload.begin({ kind: "skill-archive", slug, sizeBytes, sha256?, force?, idempotencyKey? })tworzy przesyłanie powiązane z tym slug i wartością force.skills.upload.chunk({ uploadId, offset, dataBase64 })dopisuje bajty pod dokładnym zdekodowanym przesunięciem.skills.upload.commit({ uploadId, sha256? })weryfikuje końcowy rozmiar i SHA-256. Commit tylko finalizuje przesłanie; nie instaluje skill.- Przesłane archiwa skill to archiwa zip zawierające główny
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 skill w kataloguskills/domyślnego obszaru roboczego agenta. - Tryb przesyłania:
{ source: "upload", uploadId, slug, force?, sha256?, timeoutMs? }instaluje zatwierdzone przesłanie w kataloguskills/<slug>domyślnego obszaru roboczego agenta. Slug i wartość force muszą pasować do pierwotnego żądaniaskills.upload.begin. Ten tryb jest odrzucany, chyba że włączonoskills.install.allowUploadedArchives. To ustawienie nie wpływa na instalacje ClawHub. - Tryb instalatora Gateway:
{ name, installId, dangerouslyForceUnsafeInstall?, timeoutMs? }uruchamia zadeklarowaną akcjęmetadata.openclaw.installna hoście gateway.
- Tryb ClawHub:
- Operatorzy mogą wywołać
skills.update(operator.admin) w dwóch trybach:- Tryb ClawHub aktualizuje jeden śledzony slug lub wszystkie śledzone instalacje ClawHub w domyślnym obszarze roboczym agenta.
- Tryb konfiguracji aktualizuje wartości
skills.entries.<skillKey>, takie jakenabled,apiKeyienv.
Widoki models.list
models.list akceptuje opcjonalny parametr view:
- Pominięty lub
"default": bieżące zachowanie runtime. Jeśli skonfigurowanoagents.defaults.models, odpowiedzią jest dozwolony katalog, w tym dynamicznie odkryte modele dla wpisówprovider/*. W przeciwnym razie odpowiedzią jest pełny katalog Gateway. "configured": zachowanie o rozmiarze selektora. Jeśli skonfigurowanoagents.defaults.models, nadal ma pierwszeństwo, w tym odkrywanie ograniczone do providera dla wpisówprovider/*. Bez listy dozwolonych odpowiedź używa jawnych wpisówmodels.providers.*.models, wracając do pełnego katalogu tylko wtedy, gdy nie istnieją żadne skonfigurowane wiersze modeli."all": pełny katalog Gateway, z pominięciemagents.defaults.models. Używaj tego do diagnostyki i interfejsów odkrywania, a nie w zwykłych selektorach modeli.
Zatwierdzenia wykonań
- Gdy żądanie wykonania wymaga zatwierdzenia, gateway emituje
exec.approval.requested. - Klienci operatora rozstrzygają je, wywołując
exec.approval.resolve(wymaga zakresuoperator.approvals). - Dla
host=nodeżądanieexec.approval.requestmusi zawieraćsystemRunPlan(kanoniczneargv/cwd/rawCommand/metadane sesji). Żądania bezsystemRunPlansą odrzucane. - Po zatwierdzeniu przekazane wywołania
node.invoke system.runponownie używają tego kanonicznegosystemRunPlanjako autorytatywnego kontekstu polecenia/cwd/sesji. - Jeśli wywołujący zmieni
command,rawCommand,cwd,agentIdlubsessionKeymiędzy przygotowaniem a ostatecznym zatwierdzonym przekazaniemsystem.run, gateway odrzuca uruchomienie zamiast ufać zmodyfikowanemu ładunkowi.
Awaryjna ścieżka dostarczania agenta
- Żądania
agentmogą zawieraćdeliver=true, aby zażądać dostarczenia wychodzącego. bestEffortDeliver=falsezachowuje ścisłe działanie: nierozwiązane lub wyłącznie wewnętrzne cele dostarczania zwracająINVALID_REQUEST.bestEffortDeliver=truepozwala na awaryjne przejście do wykonania tylko w sesji, gdy nie można rozwiązać żadnej zewnętrznej trasy dostarczalnej (na przykład sesje wewnętrzne/webchat lub niejednoznaczne konfiguracje wielokanałowe).- Końcowe wyniki
agentmogą zawieraćresult.deliveryStatus, gdy żądano dostarczenia, używając tych samych statusówsent,suppressed,partial_failedifailed, które udokumentowano dlaopenclaw agent --json --deliver.
Wersjonowanie
PROTOCOL_VERSIONznajduje się wsrc/gateway/protocol/version.ts.- Klienci wysyłają
minProtocol+maxProtocol; serwer odrzuca zakresy, które nie obejmują jego bieżącego protokołu. Klienci natywni używają dolnej granicy v3, aby addytywni klienci v4 nadal mogli łączyć się z gateway v3. - Schematy i modele są generowane z definicji TypeBox:
pnpm protocol:genpnpm protocol:gen:swiftpnpm protocol:check
Stałe klienta
Klient referencyjny wsrc/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.
| Stała | Domyślna wartość | Źródło |
|---|---|---|
PROTOCOL_VERSION | 4 | src/gateway/protocol/version.ts |
MIN_CLIENT_PROTOCOL_VERSION | 3 | src/gateway/protocol/version.ts |
| Limit czasu żądania (na RPC) | 30_000 ms | src/gateway/client.ts (requestTimeoutMs) |
| Limit czasu preauth / wyzwania połączenia | 15_000 ms | src/gateway/handshake-timeouts.ts (konfiguracja/env może zwiększyć sparowany budżet serwera/klienta) |
| Początkowy backoff ponownego połączenia | 1_000 ms | src/gateway/client.ts (backoffMs) |
| Maksymalny backoff ponownego połączenia | 30_000 ms | src/gateway/client.ts (scheduleReconnect) |
| Ograniczenie szybkiej ponownej próby po zamknięciu z powodu tokenu urządzenia | 250 ms | src/gateway/client.ts |
Okres karencji wymuszonego zatrzymania przed terminate() | 250 ms | FORCE_STOP_TERMINATE_GRACE_MS |
Domyślny limit czasu stopAndWait() | 1_000 ms | STOP_AND_WAIT_TIMEOUT_MS |
Domyślny interwał tyknięcia (przed hello-ok) | 30_000 ms | src/gateway/client.ts |
| Zamknięcie po przekroczeniu limitu tyknięcia | kod 4000, gdy cisza przekracza tickIntervalMs * 2 | src/gateway/client.ts |
MAX_PAYLOAD_BYTES | 25 * 1024 * 1024 (25 MB) | src/gateway/server-constants.ts |
policy.tickIntervalMs, policy.maxPayload
i policy.maxBufferedBytes w hello-ok; klienci powinni respektować te wartości
zamiast domyślnych wartości sprzed handshake.
Uwierzytelnianie
- Uwierzytelnianie Gateway współdzielonym sekretem używa
connect.params.auth.tokenalboconnect.params.auth.password, zależnie od skonfigurowanego trybu uwierzytelniania. - Tryby przenoszące tożsamość, takie jak Tailscale Serve
(
gateway.auth.allowTailscale: true) albo nielokalnygateway.auth.mode: "trusted-proxy", spełniają kontrolę uwierzytelniania połączenia na podstawie nagłówków żądania zamiastconnect.params.auth.*. - Prywatne wejście
gateway.auth.mode: "none"całkowicie pomija uwierzytelnianie połączenia współdzielonym sekretem; nie wystawiaj tego trybu na publiczne/niezaufane wejście. - Po sparowaniu Gateway wydaje token urządzenia ograniczony do roli połączenia
- zakresów. Jest zwracany w
hello-ok.auth.deviceTokeni powinien być utrwalony przez klienta na potrzeby przyszłych połączeń.
- zakresów. Jest zwracany w
- Klienci powinni utrwalać główny
hello-ok.auth.deviceTokenpo 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/próbkowania/statusu, który został już przyznany, i zapobiega cichej redukcji ponownych połączeń do węższego, niejawnego zakresu tylko administracyjnego.
- Składanie uwierzytelniania połączenia po stronie klienta (
selectConnectAuthwsrc/gateway/client.ts):auth.passwordjest ortogonalne i zawsze jest przekazywane, gdy jest ustawione.auth.tokenjest wypełniane według priorytetu: najpierw jawny współdzielony token, potem jawnydeviceToken, a następnie zapisany token dla danego urządzenia (kluczowany przezdeviceId+role).auth.bootstrapTokenjest wysyłany tylko wtedy, gdy żaden z powyższych mechanizmów nie wyznaczyłauth.token. Współdzielony token albo dowolny wyznaczony token urządzenia go tłumi.- Automatyczne promowanie zapisanego tokenu urządzenia podczas jednorazowej
ponownej próby
AUTH_TOKEN_MISMATCHjest ograniczone tylko do zaufanych punktów końcowych — loopback albowss://z przypiętymtlsFingerprint. Publicznewss://bez przypięcia się nie kwalifikuje.
- Dodatkowe wpisy
hello-ok.auth.deviceTokenssą tokenami przekazania bootstrap. Utrwalaj je tylko wtedy, gdy połączenie użyło uwierzytelniania bootstrap na zaufanym transporcie, takim jakwss://albo parowanie loopback/lokalne. - Jeśli klient podaje jawny
deviceTokenalbo jawnescopes, ten zestaw zakresów żądany przez wywołującego pozostaje autorytatywny; zakresy z pamięci podręcznej są używane ponownie tylko wtedy, gdy klient ponownie używa zapisanego tokenu dla danego urządzenia. - Tokeny urządzeń można rotować/odwoływać przez
device.token.rotateidevice.token.revoke(wymaga zakresuoperator.pairing). device.token.rotatezwraca metadane rotacji. Powtarza zastępczy token bearer tylko dla wywołań z tego samego urządzenia, które są już uwierzytelnione tym tokenem urządzenia, dzięki czemu klienci używający tylko tokenu mogą utrwalić zamiennik przed ponownym połączeniem. Rotacje współdzielone/administracyjne nie powtarzają tokenu bearer.- Wydawanie, rotacja i odwoływanie tokenów pozostają ograniczone do zatwierdzonego zestawu ról zapisanego we wpisie parowania tego urządzenia; mutacja tokenu nie może rozszerzyć ani wskazać roli urządzenia, której nigdy nie przyznało zatwierdzenie parowania.
- Dla sesji tokenów sparowanych urządzeń zarządzanie urządzeniami jest samoograniczone, chyba że
wywołujący ma także
operator.admin: wywołujący niebędący administratorem mogą usuwać/odwoływać/rotować tylko wpis własnego urządzenia. device.token.rotateidevice.token.revokesprawdzają także zestaw zakresów docelowego tokenu operatora względem bieżących zakresów sesji wywołującego. Wywołujący niebędący administratorem nie mogą rotować ani odwoływać szerszego tokenu operatora niż ten, który już posiadają.- Niepowodzenia uwierzytelniania zawierają
error.details.codeoraz wskazówki odzyskiwania:error.details.canRetryWithDeviceToken(wartość logiczna)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 działania.
AUTH_SCOPE_MISMATCHoznacza, że token urządzenia został rozpoznany, ale nie obejmuje żądanej roli/zakresów. Klienci nie powinni przedstawiać tego jako błędnego tokenu; poproś operatora o ponowne sparowanie albo zatwierdzenie węższego/szerszego kontraktu zakresu.
Tożsamość urządzenia + parowanie
- Węzły powinny zawierać stabilną tożsamość urządzenia (
device.id) pochodzącą z odcisku palca pary kluczy. - Gateway wydaje tokeny na urządzenie + rolę.
- Zatwierdzenia parowania są wymagane dla nowych identyfikatorów urządzeń, chyba że włączone jest lokalne automatyczne zatwierdzanie.
- Automatyczne zatwierdzanie parowania koncentruje się na bezpośrednich połączeniach local loopback.
- OpenClaw ma także wąską ścieżkę samopołączenia lokalną dla backendu/kontenera dla zaufanych przepływów pomocniczych współdzielonego sekretu.
- Połączenia tailnet lub LAN na tym samym hoście nadal są traktowane jako zdalne dla parowania i wymagają zatwierdzenia.
- Klienci WS zwykle dołączają tożsamość
devicepodczasconnect(operator + węzeł). Jedynymi wyjątkami operatora bez urządzenia są jawne ścieżki zaufania:gateway.controlUi.allowInsecureAuth=truedla zgodności z niebezpiecznym HTTP tylko na localhost.- udane uwierzytelnienie operatora w Control UI przez
gateway.auth.mode: "trusted-proxy". gateway.controlUi.dangerouslyDisableDeviceAuth=true(tryb awaryjny, poważne obniżenie bezpieczeństwa).- bezpośrednie RPC backendu
gateway-clientprzez loopback, uwierzytelnione współdzielonym tokenem/hasłem Gateway.
- Wszystkie połączenia muszą podpisać nonce
connect.challengedostarczony przez serwer.
Diagnostyka migracji uwierzytelniania urządzeń
Dla starszych klientów, którzy nadal używają zachowania podpisywania sprzed wyzwania,connect zwraca teraz
kody szczegółów DEVICE_AUTH_* w error.details.code ze stabilnym error.details.reason.
Typowe niepowodzenia migracji:
| Komunikat | details.code | details.reason | Znaczenie |
|---|---|---|---|
device nonce required | DEVICE_AUTH_NONCE_REQUIRED | device-nonce-missing | Klient pominął device.nonce (albo wysłał pustą wartość). |
device nonce mismatch | DEVICE_AUTH_NONCE_MISMATCH | device-nonce-mismatch | Klient podpisał nieaktualnym/błędnym nonce. |
device signature invalid | DEVICE_AUTH_SIGNATURE_INVALID | device-signature | Ładunek podpisu nie pasuje do ładunku v2. |
device signature expired | DEVICE_AUTH_SIGNATURE_EXPIRED | device-signature-stale | Podpisany znacznik czasu jest poza dozwolonym odchyleniem. |
device identity mismatch | DEVICE_AUTH_DEVICE_ID_MISMATCH | device-id-mismatch | device.id nie pasuje do odcisku palca klucza publicznego. |
device public key invalid | DEVICE_AUTH_PUBLIC_KEY_INVALID | device-public-key | Format/kanonizacja klucza publicznego nie powiodła się. |
- 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ążeplatformideviceFamilyoprócz pól urządzenia/klienta/roli/zakresów/tokenu/nonce. - Starsze podpisy
v2pozostają akceptowane dla zgodności, ale przypinanie metadanych sparowanego urządzenia nadal kontroluje politykę poleceń przy ponownym połączeniu.
TLS + przypinanie
- TLS jest obsługiwany dla połączeń WS.
- Klienci mogą opcjonalnie przypiąć odcisk palca certyfikatu gateway (zobacz konfigurację
gateway.tlsorazgateway.remote.tlsFingerprintalbo 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 definiowana przez schematy TypeBox wsrc/gateway/protocol/schema.ts.