openclaw/docs
openclaw/docs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore(i18n): refresh pl translations

Browse Source
This commit is contained in:
openclaw-docs-i18n[bot] 2026-05-01 10:06:45 +00:00
parent 30cacf5db6
commit ae84e59b5f
39 changed files with 5748 additions and 4853 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

214
docs/pl/automation/tasks.md
View File

@ -1,48 +1,48 @@
---
read_when:
- Sprawdzanie trwających lub niedawno ukończonych prac w tle
- Debugowanie niepowodzeń dostarczania dla odłączonych uruchomień agenta
- Debugowanie niepowodzeń dostarczania w uruchomieniach agenta w trybie odłączonym
- Zrozumienie, jak uruchomienia w tle wiążą się z sesjami, Cron i Heartbeat
sidebarTitle: Background tasks
summary: Śledzenie zadań w tle dla uruchomień ACP, subagentów, izolowanych zadań Cron i operacji CLI
title: Zadania w tle
x-i18n:
generated_at: "2026-04-30T16:27:49Z"
generated_at: "2026-05-01T09:56:19Z"
model: gpt-5.5
provider: openai
source_hash: 999653c9360323d5135e33193c76458cba8c288227de46a6217f1ccbed2a6d34
source_hash: 8782987a79989264ae3bd1ca4b16755bdfb7e295e4f77933bf3a38c136d837f4
source_path: automation/tasks.md
workflow: 16
---
<Note>
Szukasz harmonogramowania? Zobacz [Automatyzacja i zadania](/pl/automation), aby wybrać właściwy mechanizm. Ta strona jest dziennikiem aktywności pracy w tle, a nie harmonogramem.
Szukasz planowania? Zobacz [Automatyzacja i zadania](/pl/automation), aby wybrać właściwy mechanizm. Ta strona jest dziennikiem aktywności pracy w tle, a nie harmonogramem.
</Note>
Zadania w tle śledzą pracę wykonywaną **poza główną sesją konwersacji**: uruchomienia ACP, uruchomienia subagentów, izolowane wykonania zadań cron oraz operacje inicjowane przez CLI.
Zadania w tle śledzą pracę wykonywaną **poza główną sesją rozmowy**: uruchomienia ACP, tworzenie podagentów, izolowane wykonania zadań Cron oraz operacje inicjowane z CLI.
Zadania **nie** zastępują sesji, zadań cron ani Heartbeat — są **dziennikiem aktywności**, który zapisuje, jaka odłączona praca została wykonana, kiedy i czy zakończyła się powodzeniem.
Zadania **nie** zastępują sesji, zadań Cron ani Heartbeat — są **dziennikiem aktywności**, który rejestruje, jaka odłączona praca została wykonana, kiedy i czy zakończyła się powodzeniem.
<Note>
Nie każde uruchomienie agenta tworzy zadanie. Tury Heartbeat i zwykły czat interaktywny tego nie robią. Robią to wszystkie wykonania cron, uruchomienia ACP, uruchomienia subagentów oraz polecenia agenta CLI.
Nie każde uruchomienie agenta tworzy zadanie. Tury Heartbeat i zwykły czat interaktywny tego nie robią. Wszystkie wykonania Cron, uruchomienia ACP, uruchomienia podagentów i polecenia agenta z CLI tworzą zadania.
</Note>
## TL;DR
- Zadania są **rekordami**, nie harmonogramami — cron i Heartbeat decydują, _kiedy_ praca działa, zadania śledzą, _co się wydarzyło_.
- ACP, subagenci, wszystkie zadania cron oraz operacje CLI tworzą zadania. Tury Heartbeat tego nie robią.
- Każde zadanie przechodzi przez `queued → running → terminal` (succeeded, failed, timed_out, cancelled albo lost).
- Zadania cron pozostają aktywne, dopóki środowisko wykonawcze cron nadal jest właścicielem zadania; jeśli
- Zadania są **rekordami**, a nie harmonogramami — Cron i Heartbeat decydują, _kiedy_ praca jest uruchamiana, a zadania śledzą, _co się wydarzyło_.
- ACP, podagenci, wszystkie zadania Cron i operacje CLI tworzą zadania. Tury Heartbeat tego nie robią.
- Każde zadanie przechodzi przez `queued → running → terminal` (succeeded, failed, timed_out, cancelled lub lost).
- Zadania Cron pozostają aktywne, dopóki środowisko wykonawcze Cron nadal jest właścicielem zadania; jeśli
stan środowiska wykonawczego w pamięci zniknął, konserwacja zadań najpierw sprawdza trwałą historię
uruchomień cron, zanim oznaczy zadanie jako utracone.
- Ukończenie jest sterowane wypychaniem: odłączona praca może powiadomić bezpośrednio albo wybudzić
sesję żądającą/Heartbeat po zakończeniu, więc pętle odpytywania statusu mają
zwykle niewłaściwy kształt.
- Izolowane uruchomienia cron i ukończenia subagentów w trybie best-effort czyszczą śledzone karty przeglądarki/procesy dla swojej sesji podrzędnej przed końcowym księgowaniem czyszczenia.
- Dostarczanie izolowanego cron tłumi przestarzałe pośrednie odpowiedzi nadrzędne, gdy praca potomnego subagenta wciąż się opróżnia, i preferuje końcowe wyjście potomne, gdy dotrze przed dostarczeniem.
uruchomień Cron, zanim oznaczy zadanie jako utracone.
- Ukończenie jest sterowane powiadomieniami push: odłączona praca może powiadomić bezpośrednio albo wybudzić
sesję żądającą/Heartbeat po zakończeniu, dlatego pętle odpytywania statusu
zwykle mają niewłaściwy kształt.
- Izolowane uruchomienia Cron i zakończenia podagentów w miarę możliwości czyszczą śledzone karty przeglądarki/procesy dla swojej sesji podrzędnej przed końcowym księgowaniem czyszczenia.
- Izolowane dostarczanie Cron tłumi nieaktualne tymczasowe odpowiedzi nadrzędne, gdy praca podagentów potomnych nadal się opróżnia, i preferuje końcowe wyjście potomne, gdy dotrze ono przed dostarczeniem.
- Powiadomienia o ukończeniu są dostarczane bezpośrednio do kanału albo kolejkowane do następnego Heartbeat.
- `openclaw tasks list` pokazuje wszystkie zadania; `openclaw tasks audit` ujawnia problemy.
- Rekordy końcowe są przechowywane przez 7 dni, a potem automatycznie usuwane.
- Rekordy terminalne są przechowywane przez 7 dni, a potem automatycznie usuwane.
## Szybki start
@ -64,7 +64,7 @@ Nie każde uruchomienie agenta tworzy zadanie. Tury Heartbeat i zwykły czat int
openclaw tasks show <lookup>
```
</Tab>
<Tab title="Anulowanie i powiadamianie">
<Tab title="Anulowanie i powiadomienia">
```bash
# Cancel a running task (kills the child session)
openclaw tasks cancel <lookup>
@ -97,26 +97,26 @@ Nie każde uruchomienie agenta tworzy zadanie. Tury Heartbeat i zwykły czat int
## Co tworzy zadanie
| Źródło | Typ środowiska wykonawczego | Kiedy tworzony jest rekord zadania | Domyślna polityka powiadomień |
| ---------------------- | ------------ | ------------------------------------------------------ | --------------------- |
| Uruchomienia ACP w tle | `acp` | Uruchomienie podrzędnej sesji ACP | `done_only` |
| Orkiestracja subagentów | `subagent` | Uruchomienie subagenta przez `sessions_spawn` | `done_only` |
| Zadania Cron (wszystkie typy) | `cron` | Każde wykonanie cron (w głównej sesji i izolowane) | `silent` |
| Operacje CLI | `cli` | Polecenia `openclaw agent`, które działają przez Gateway | `silent` |
| Zadania multimedialne agenta | `cli` | Uruchomienia `video_generate` oparte na sesji | `silent` |
| Źródło | Typ środowiska wykonawczego | Kiedy tworzony jest rekord zadania | Domyślna polityka powiadomień |
| --------------------- | --------------------------- | ----------------------------------------------------- | ----------------------------- |
| Uruchomienia ACP w tle | `acp` | Tworzenie podrzędnej sesji ACP | `done_only` |
| Orkiestracja podagentów | `subagent` | Tworzenie podagenta przez `sessions_spawn` | `done_only` |
| Zadania Cron (wszystkie typy) | `cron` | Każde wykonanie Cron (w sesji głównej i izolowane) | `silent` |
| Operacje CLI | `cli` | Polecenia `openclaw agent`, które działają przez Gateway | `silent` |
| Zadania multimedialne agenta | `cli` | Uruchomienia `music_generate`/`video_generate` oparte na sesji | `silent` |
<AccordionGroup>
<Accordion title="Domyślne powiadomienia dla cron i multimediów">
Zadania cron w głównej sesji domyślnie używają polityki powiadomień `silent` — tworzą rekordy do śledzenia, ale nie generują powiadomień. Izolowane zadania cron również domyślnie używają `silent`, ale są bardziej widoczne, ponieważ działają we własnej sesji.
<Accordion title="Domyślne powiadomienia dla Cron i multimediów">
Zadania Cron w sesji głównej domyślnie używają polityki powiadomień `silent` — tworzą rekordy do śledzenia, ale nie generują powiadomień. Izolowane zadania Cron również domyślnie używają `silent`, ale są bardziej widoczne, ponieważ działają we własnej sesji.
Uruchomienia `video_generate` oparte na sesji również używają polityki powiadomień `silent`. Nadal tworzą rekordy zadań, ale ukończenie jest przekazywane z powrotem do pierwotnej sesji agenta jako wewnętrzne wybudzenie, aby agent mógł sam napisać wiadomość uzupełniającą i dołączyć gotowe wideo. Jeśli włączysz `tools.media.asyncCompletion.directSend`, asynchroniczne ukończenia `music_generate` i `video_generate` najpierw próbują bezpośredniego dostarczenia do kanału, zanim wrócą do ścieżki wybudzenia sesji żądającej.
Uruchomienia `music_generate` i `video_generate` oparte na sesji również używają polityki powiadomień `silent`. Nadal tworzą rekordy zadań, ale ukończenie jest przekazywane z powrotem do pierwotnej sesji agenta jako wewnętrzne wybudzenie, aby agent mógł samodzielnie napisać wiadomość uzupełniającą i dołączyć gotowe media. Jeśli włączysz `tools.media.asyncCompletion.directSend`, asynchroniczne ukończenia `video_generate` mogą najpierw spróbować bezpośredniego dostarczenia do kanału; asynchroniczne ukończenia `music_generate` pozostają na ścieżce wybudzenia sesji żądającej.
</Accordion>
<Accordion title="Zabezpieczenie współbieżnego video_generate">
Gdy zadanie `video_generate` oparte na sesji jest nadal aktywne, narzędzie działa także jako zabezpieczenie: powtórzone wywołania `video_generate` w tej samej sesji zwracają status aktywnego zadania zamiast uruchamiać drugą współbieżną generację. Użyj `action: "status"`, gdy potrzebujesz jawnego sprawdzenia postępu/statusu po stronie agenta.
<Accordion title="Zabezpieczenie współbieżnych video_generate">
Gdy zadanie `video_generate` oparte na sesji jest nadal aktywne, narzędzie działa także jako zabezpieczenie: powtarzane wywołania `video_generate` w tej samej sesji zwracają status aktywnego zadania zamiast rozpoczynać drugie współbieżne generowanie. Użyj `action: "status"`, gdy chcesz jawnie sprawdzić postęp/status po stronie agenta.
</Accordion>
<Accordion title="Co nie tworzy zadań">
- Tury Heartbeat — główna sesja; zobacz [Heartbeat](/pl/gateway/heartbeat)
- Tury Heartbeat — sesja główna; zobacz [Heartbeat](/pl/gateway/heartbeat)
- Zwykłe interaktywne tury czatu
- Bezpośrednie odpowiedzi `/command`
@ -137,58 +137,58 @@ stateDiagram-v2
running --> lost : session gone > 5 min
```
| Status | Co oznacza |
| Status | Co oznacza |
| ----------- | -------------------------------------------------------------------------- |
| `queued` | Utworzone, czeka na uruchomienie agenta |
| `running` | Tura agenta jest aktywnie wykonywana |
| `succeeded` | Ukończone pomyślnie |
| `failed` | Ukończone z błędem |
| `timed_out` | Przekroczyło skonfigurowany limit czasu |
| `cancelled` | Zatrzymane przez operatora przez `openclaw tasks cancel` |
| `lost` | Środowisko wykonawcze utraciło autorytatywny stan wspierający po 5-minutowym okresie karencji |
| `queued` | Utworzone, czeka na uruchomienie agenta |
| `running` | Tura agenta jest aktywnie wykonywana |
| `succeeded` | Ukończone pomyślnie |
| `failed` | Ukończone z błędem |
| `timed_out` | Przekroczono skonfigurowany limit czasu |
| `cancelled` | Zatrzymane przez operatora przez `openclaw tasks cancel` |
| `lost` | Środowisko wykonawcze utraciło autorytatywny stan zaplecza po 5-minutowym okresie karencji |
Przejścia zachodzą automatycznie — gdy powiązane uruchomienie agenta się kończy, status zadania aktualizuje się odpowiednio.
Przejścia zachodzą automatycznie — gdy powiązane uruchomienie agenta się kończy, status zadania jest aktualizowany odpowiednio.
Ukończenie uruchomienia agenta jest autorytatywne dla aktywnych rekordów zadań. Udane odłączone uruchomienie finalizuje się jako `succeeded`, zwykłe błędy uruchomienia finalizują się jako `failed`, a wyniki limitu czasu lub przerwania finalizują się jako `timed_out`. Jeśli operator wcześniej anulował zadanie albo środowisko wykonawcze zapisało już silniejszy stan końcowy, taki jak `failed`, `timed_out` albo `lost`, późniejszy sygnał sukcesu nie obniża tego statusu końcowego.
Ukończenie uruchomienia agenta jest autorytatywne dla aktywnych rekordów zadań. Pomyślne odłączone uruchomienie finalizuje się jako `succeeded`, zwykłe błędy uruchomienia finalizują się jako `failed`, a wyniki przekroczenia limitu czasu lub przerwania finalizują się jako `timed_out`. Jeśli operator już anulował zadanie albo środowisko wykonawcze już zapisało silniejszy stan terminalny, taki jak `failed`, `timed_out` lub `lost`, późniejszy sygnał powodzenia nie obniża tego statusu terminalnego.
`lost` uwzględnia środowisko wykonawcze:
- Zadania ACP: metadane podrzędnej sesji ACP zniknęły.
- Zadania subagentów: podrzędna sesja zniknęła z docelowego magazynu agentów.
- Zadania Cron: środowisko wykonawcze cron nie śledzi już zadania jako aktywnego, a trwała
historia uruchomień cron nie pokazuje końcowego wyniku dla tego uruchomienia. Audyt offline CLI
nie traktuje własnego pustego stanu środowiska wykonawczego cron w procesie jako autorytatywnego.
- Zadania ACP: zniknęły metadane podrzędnej sesji ACP stanowiące zaplecze.
- Zadania podagentów: podrzędna sesja stanowiąca zaplecze zniknęła z docelowego magazynu agenta.
- Zadania Cron: środowisko wykonawcze Cron nie śledzi już zadania jako aktywnego, a trwała
historia uruchomień Cron nie pokazuje terminalnego wyniku dla tego uruchomienia. Audyt offline CLI
nie traktuje własnego pustego stanu środowiska wykonawczego Cron w procesie jako autorytatywnego.
- Zadania CLI: izolowane zadania sesji podrzędnej używają sesji podrzędnej; zadania CLI
oparte na czacie używają zamiast tego aktywnego kontekstu uruchomienia, więc zalegające
oparte na czacie używają zamiast tego kontekstu uruchomienia na żywo, więc pozostające
wiersze sesji kanału/grupy/bezpośredniej nie utrzymują ich przy życiu. Uruchomienia
`openclaw agent` oparte na Gateway także finalizują się na podstawie wyniku uruchomienia, więc ukończone uruchomienia
nie pozostają aktywne, dopóki proces czyszczący nie oznaczy ich jako `lost`.
`openclaw agent` oparte na Gateway również finalizują się na podstawie wyniku uruchomienia, więc ukończone uruchomienia
nie pozostają aktywne, dopóki proces sprzątający nie oznaczy ich jako `lost`.
## Dostarczanie i powiadomienia
Gdy zadanie osiąga stan końcowy, OpenClaw Cię powiadamia. Istnieją dwie ścieżki dostarczania:
Gdy zadanie osiąga stan terminalny, OpenClaw powiadamia Cię. Istnieją dwie ścieżki dostarczania:
**Dostarczanie bezpośrednie** — jeśli zadanie ma docelowy kanał (`requesterOrigin`), wiadomość o ukończeniu trafia bezpośrednio do tego kanału (Telegram, Discord, Slack itd.). Dla ukończeń subagentów OpenClaw zachowuje również powiązane kierowanie wątku/tematu, gdy jest dostępne, i może uzupełnić brakujące `to` / konto z zapisanej trasy sesji żądającej (`lastChannel` / `lastTo` / `lastAccountId`), zanim zrezygnuje z dostarczania bezpośredniego.
**Dostarczanie bezpośrednie** — jeśli zadanie ma docelowy kanał (`requesterOrigin`), wiadomość o ukończeniu trafia prosto do tego kanału (Telegram, Discord, Slack itd.). W przypadku ukończeń podagentów OpenClaw zachowuje również powiązane trasowanie wątku/tematu, gdy jest dostępne, i może uzupełnić brakujące `to` / konto z zapisanej trasy sesji żądającej (`lastChannel` / `lastTo` / `lastAccountId`), zanim zrezygnuje z bezpośredniego dostarczenia.
**Dostarczanie kolejkowane w sesji** — jeśli dostarczanie bezpośrednie się nie powiedzie albo nie ustawiono źródła, aktualizacja jest kolejkowana jako zdarzenie systemowe w sesji żądającego i pojawia się przy następnym Heartbeat.
**Dostarczanie kolejkowane w sesji** — jeśli bezpośrednie dostarczenie się nie powiedzie albo nie ustawiono pochodzenia, aktualizacja jest kolejkowana jako zdarzenie systemowe w sesji żądającego i pojawia się przy następnym Heartbeat.
<Tip>
Ukończenie zadania wyzwala natychmiastowe wybudzenie Heartbeat, więc szybko zobaczysz wynik — nie musisz czekać na następny zaplanowany takt Heartbeat.
Ukończenie zadania wyzwala natychmiastowe wybudzenie Heartbeat, więc szybko widzisz wynik — nie musisz czekać na następny zaplanowany takt Heartbeat.
</Tip>
Oznacza to, że zwykły przepływ pracy jest oparty na wypychaniu: uruchom odłączoną pracę raz, a potem pozwól środowisku wykonawczemu wybudzić Cię lub powiadomić o ukończeniu. Odpytuj stan zadania tylko wtedy, gdy potrzebujesz debugowania, interwencji albo jawnego audytu.
Oznacza to, że typowy przepływ pracy jest oparty na push: uruchom odłączoną pracę raz, a potem pozwól środowisku wykonawczemu wybudzić Cię lub powiadomić po ukończeniu. Odpytuj stan zadania tylko wtedy, gdy potrzebujesz debugowania, interwencji lub jawnego audytu.
### Polityki powiadomień
Kontroluj, ile informacji otrzymujesz o każdym zadaniu:
| Polityka | Co jest dostarczane |
| --------------------- | ----------------------------------------------------------------------- |
| `done_only` (domyślna) | Tylko stan końcowy (succeeded, failed itd.) — **to jest wartość domyślna** |
| `state_changes` | Każde przejście stanu i aktualizacja postępu |
| `silent` | Nic |
| Polityka | Co jest dostarczane |
| -------------------- | -------------------------------------------------------------------------- |
| `done_only` (domyślna) | Tylko stan terminalny (succeeded, failed itd.) — **to jest domyślne** |
| `state_changes` | Każde przejście stanu i aktualizacja postępu |
| `silent` | Nic |
Zmień politykę, gdy zadanie działa:
Zmień politykę, gdy zadanie jest uruchomione:
```bash
openclaw tasks notify <lookup> state_changes
@ -210,7 +210,7 @@ openclaw tasks notify <lookup> state_changes
openclaw tasks show <lookup>
```
Token wyszukiwania akceptuje ID zadania, ID uruchomienia albo klucz sesji. Pokazuje pełny rekord, w tym czas, stan dostarczania, błąd i podsumowanie końcowe.
Token wyszukiwania akceptuje ID zadania, ID uruchomienia albo klucz sesji. Pokazuje pełny rekord, w tym czas, stan dostarczania, błąd i podsumowanie terminalne.
</Accordion>
<Accordion title="tasks cancel">
@ -218,7 +218,7 @@ openclaw tasks notify <lookup> state_changes
openclaw tasks cancel <lookup>
```
Dla zadań ACP i subagentów zabija to sesję podrzędną. Dla zadań śledzonych przez CLI anulowanie jest zapisywane w rejestrze zadań (nie ma osobnego uchwytu podrzędnego środowiska wykonawczego). Status przechodzi na `cancelled`, a powiadomienie o dostarczeniu jest wysyłane, gdy ma zastosowanie.
W przypadku zadań ACP i podagentów zabija to sesję podrzędną. W przypadku zadań śledzonych przez CLI anulowanie jest zapisywane w rejestrze zadań (nie ma osobnego uchwytu podrzędnego środowiska wykonawczego). Status przechodzi na `cancelled`, a powiadomienie o dostarczeniu jest wysyłane, gdy ma to zastosowanie.
</Accordion>
<Accordion title="tasks notify">
@ -231,16 +231,16 @@ openclaw tasks notify <lookup> state_changes
openclaw tasks audit [--json]
```
Ujawnia problemy operacyjne. Ustalenia pojawiają się także w `openclaw status`, gdy wykryto problemy.
Ujawnia problemy operacyjne. Wyniki pojawiają się również w `openclaw status`, gdy wykryto problemy.
| Ustalenie | Ważność | Wyzwalacz |
| Ustalenie | Ważność | Wyzwalacz |
| ------------------------- | ---------- | ------------------------------------------------------------------------------------------------------------ |
| `stale_queued` | ostrzeżenie | W kolejce przez ponad 10 minut |
| `stale_running` | błąd | Uruchomione przez ponad 30 minut |
| `lost` | ostrzeżenie/błąd | Własność zadania wspieranego przez runtime zniknęła; zachowane utracone zadania ostrzegają do `cleanupAfter`, potem stają się błędami |
| `delivery_failed` | ostrzeżenie | Dostarczenie nie powiodło się, a zasada powiadamiania nie jest `silent` |
| `missing_cleanup` | ostrzeżenie | Zadanie terminalne bez znacznika czasu czyszczenia |
| `inconsistent_timestamps` | ostrzeżenie | Naruszenie osi czasu (na przykład zakończono przed rozpoczęciem) |
| `stale_queued` | warn | W kolejce przez ponad 10 minut |
| `stale_running` | error | Uruchomione przez ponad 30 minut |
| `lost` | warn/error | Własność zadania wspieranego przez środowisko wykonawcze zniknęła; zachowane utracone zadania ostrzegają do `cleanupAfter`, a następnie stają się błędami |
| `delivery_failed` | warn | Dostarczenie nie powiodło się, a zasada powiadamiania nie ma wartości `silent` |
| `missing_cleanup` | warn | Zadanie terminalne bez znacznika czasu czyszczenia |
| `inconsistent_timestamps` | warn | Naruszenie osi czasu (na przykład zakończono przed rozpoczęciem) |
</Accordion>
<Accordion title="konserwacja zadań">
@ -249,41 +249,41 @@ openclaw tasks notify <lookup> state_changes
openclaw tasks maintenance --apply [--json]
```
Użyj tego, aby podejrzeć lub zastosować uzgadnianie, stemplowanie czyszczenia i przycinanie dla zadań oraz stanu Task Flow.
Użyj tego, aby podejrzeć lub zastosować uzgadnianie, oznaczanie czyszczenia i przycinanie dla zadań oraz stanu Task Flow.
Uzgadnianie jest świadome runtime:
Uzgadnianie uwzględnia środowisko wykonawcze:
- Zadania ACP/subagent sprawdzają swoją nadrzędną sesję podrzędną.
- Zadania subagent, których sesja podrzędna ma nagrobek odzyskiwania po restarcie, są oznaczane jako utracone zamiast traktowania ich jako możliwe do odzyskania sesje nadrzędne.
- Zadania Cron sprawdzają, czy runtime cron nadal jest właścicielem zadania, następnie odzyskują status terminalny z utrwalonych dzienników uruchomień cron/stanu zadania, zanim ostatecznie przejdą do `lost`. Tylko proces Gateway jest autorytatywny dla zestawu aktywnych zadań cron w pamięci; audyt CLI offline używa trwałej historii, ale nie oznacza zadania cron jako utraconego wyłącznie dlatego, że ten lokalny Set jest pusty.
- Zadania CLI oparte na czacie sprawdzają właścicielski kontekst aktywnego uruchomienia, a nie tylko wiersz sesji czatu.
- Zadania ACP/subagenta sprawdzają swoją bazową sesję podrzędną.
- Zadania subagenta, których sesja podrzędna ma nagrobek odzyskiwania po restarcie, są oznaczane jako utracone zamiast traktowania ich jako możliwych do odzyskania sesji bazowych.
- Zadania Cron sprawdzają, czy środowisko wykonawcze cron nadal jest właścicielem zadania, a następnie odzyskują status terminalny z utrwalonych dzienników uruchomień cron/stanu zadania przed przejściem awaryjnym do `lost`. Tylko proces Gateway jest autorytatywny dla przechowywanego w pamięci zestawu aktywnych zadań cron; audyt CLI offline używa trwałej historii, ale nie oznacza zadania cron jako utraconego wyłącznie dlatego, że lokalny Set jest pusty.
- Zadania CLI wspierane przez czat sprawdzają właścicielski kontekst aktywnego uruchomienia, a nie tylko wiersz sesji czatu.
Czyszczenie po zakończeniu również jest świadome runtime:
Czyszczenie po ukończeniu także uwzględnia środowisko wykonawcze:
- Zakończenie subagent na zasadzie najlepszych starań zamyka śledzone karty/procesy przeglądarki dla sesji podrzędnej, zanim czyszczenie ogłoszenia będzie kontynuowane.
- Zakończenie izolowanego cron na zasadzie najlepszych starań zamyka śledzone karty/procesy przeglądarki dla sesji cron, zanim uruchomienie zostanie całkowicie rozebrane.
- Dostarczanie izolowanego cron w razie potrzeby czeka na dalsze działania potomnego subagent i tłumi nieaktualny tekst potwierdzenia rodzica zamiast go ogłaszać.
- Dostarczanie zakończenia subagent preferuje najnowszy widoczny tekst asystenta; jeśli jest pusty, przechodzi do oczyszczonego najnowszego tekstu narzędzia/toolResult, a uruchomienia wywołań narzędzi zakończone wyłącznie limitem czasu mogą zostać zwinięte do krótkiego podsumowania częściowego postępu. Terminalne nieudane uruchomienia ogłaszają status niepowodzenia bez ponownego odtwarzania przechwyconego tekstu odpowiedzi.
- Niepowodzenia czyszczenia nie przesłaniają rzeczywistego wyniku zadania.
- Ukończenie subagenta na zasadzie najlepszej próby zamyka śledzone karty przeglądarki/procesy dla sesji podrzędnej przed kontynuacją czyszczenia ogłoszenia.
- Ukończenie izolowanego cron na zasadzie najlepszej próby zamyka śledzone karty przeglądarki/procesy dla sesji cron, zanim uruchomienie zostanie w pełni zakończone.
- Dostarczenie izolowanego cron w razie potrzeby czeka na dalsze działania potomnego subagenta i tłumi nieaktualny tekst potwierdzenia rodzica zamiast go ogłaszać.
- Dostarczenie ukończenia subagenta preferuje najnowszy widoczny tekst asystenta; jeśli jest pusty, przechodzi awaryjnie do oczyszczonego najnowszego tekstu narzędzia/toolResult, a uruchomienia wywołań narzędzi zakończone wyłącznie limitem czasu mogą zostać zwinięte do krótkiego podsumowania częściowego postępu. Terminalne nieudane uruchomienia ogłaszają status niepowodzenia bez odtwarzania przechwyconego tekstu odpowiedzi.
- Błędy czyszczenia nie maskują rzeczywistego wyniku zadania.
</Accordion>
<Accordion title="lista | pokazanie | anulowanie przepływu zadań">
<Accordion title="tasks flow list | show | cancel">
```bash
openclaw tasks flow list [--status <status>] [--json]
openclaw tasks flow show <lookup> [--json]
openclaw tasks flow cancel <lookup>
```
Użyj ich, gdy zależy Ci na orkiestrującym Task Flow, a nie na jednym konkretnym rekordzie zadania w tle.
Użyj ich, gdy interesuje Cię orkiestrujący Task Flow, a nie pojedynczy rekord zadania w tle.
</Accordion>
</AccordionGroup>
## Tablica zadań czatu (`/tasks`)
Użyj `/tasks` w dowolnej sesji czatu, aby zobaczyć zadania w tle połączone z tą sesją. Tablica pokazuje aktywne i niedawno ukończone zadania z runtime, statusem, czasem oraz szczegółami postępu lub błędu.
Użyj `/tasks` w dowolnej sesji czatu, aby zobaczyć zadania w tle powiązane z tą sesją. Tablica pokazuje aktywne i niedawno ukończone zadania wraz ze środowiskiem wykonawczym, statusem, czasem oraz szczegółami postępu lub błędu.
Gdy bieżąca sesja nie ma widocznych połączonych zadań, `/tasks` przechodzi do lokalnych dla agenta liczników zadań, aby nadal zapewnić przegląd bez ujawniania szczegółów innych sesji.
Gdy bieżąca sesja nie ma widocznych powiązanych zadań, `/tasks` przechodzi awaryjnie do lokalnych dla agenta liczników zadań, dzięki czemu nadal otrzymujesz przegląd bez ujawniania szczegółów innych sesji.
Aby zobaczyć pełny rejestr operatora, użyj CLI: `openclaw tasks list`.
@ -297,11 +297,11 @@ Tasks: 3 queued · 2 running · 1 issues
Podsumowanie raportuje:
- **aktywne** — liczba `queued` + `running`
- **niepowodzenia** — liczba `failed` + `timed_out` + `lost`
- **wedługRuntime** — podział według `acp`, `subagent`, `cron`, `cli`
- **active** — liczba `queued` + `running`
- **failures** — liczba `failed` + `timed_out` + `lost`
- **byRuntime** — podział według `acp`, `subagent`, `cron`, `cli`
Zarówno `/status`, jak i narzędzie `session_status` używają migawki zadań świadomej czyszczenia: preferowane są aktywne zadania, nieaktualne ukończone wiersze są ukrywane, a ostatnie niepowodzenia pojawiają się tylko wtedy, gdy nie pozostaje żadna aktywna praca. Dzięki temu karta statusu koncentruje się na tym, co ważne teraz.
Zarówno `/status`, jak i narzędzie `session_status` używają migawki zadań świadomej czyszczenia: aktywne zadania mają pierwszeństwo, nieaktualne ukończone wiersze są ukrywane, a niedawne niepowodzenia pojawiają się tylko wtedy, gdy nie pozostała żadna aktywna praca. Dzięki temu karta statusu koncentruje się na tym, co jest teraz istotne.
## Przechowywanie i konserwacja
@ -313,8 +313,8 @@ Rekordy zadań są utrwalane w SQLite pod adresem:
$OPENCLAW_STATE_DIR/tasks/runs.sqlite
```
Rejestr ładuje się do pamięci przy starcie Gateway i synchronizuje zapisy do SQLite, aby zapewnić trwałość między restartami.
Gateway ogranicza dziennik zapisu z wyprzedzeniem SQLite, używając domyślnego progu
Rejestr jest ładowany do pamięci podczas startu gateway i synchronizuje zapisy do SQLite, aby zapewnić trwałość między restartami.
Gateway utrzymuje dziennik zapisu z wyprzedzeniem SQLite w ograniczonym rozmiarze, używając domyślnego progu
autocheckpoint SQLite oraz okresowych i wykonywanych przy zamykaniu punktów kontrolnych `TRUNCATE`.
### Automatyczna konserwacja
@ -323,13 +323,13 @@ Proces sprzątający uruchamia się co **60 sekund** i obsługuje cztery rzeczy:
<Steps>
<Step title="Uzgadnianie">
Sprawdza, czy aktywne zadania nadal mają autorytatywne wsparcie runtime. Zadania ACP/subagent używają stanu sesji podrzędnej, zadania cron używają własności aktywnego zadania, a zadania CLI oparte na czacie używają właścicielskiego kontekstu uruchomienia. Jeśli ten stan wsparcia zniknie na więcej niż 5 minut, zadanie zostaje oznaczone jako `lost`.
Sprawdza, czy aktywne zadania nadal mają autorytatywne wsparcie środowiska wykonawczego. Zadania ACP/subagenta używają stanu sesji podrzędnej, zadania cron używają własności aktywnego zadania, a zadania CLI wspierane przez czat używają właścicielskiego kontekstu uruchomienia. Jeśli ten stan bazowy zniknie na ponad 5 minut, zadanie jest oznaczane jako `lost`.
</Step>
<Step title="Naprawa sesji ACP">
Zamyka terminalne lub osierocone jednorazowe sesje ACP należące do rodzica oraz zamyka nieaktualne terminalne lub osierocone trwałe sesje ACP tylko wtedy, gdy nie pozostaje aktywne powiązanie rozmowy.
Zamyka terminalne lub osierocone jednorazowe sesje ACP należące do rodzica oraz zamyka nieaktualne terminalne lub osierocone trwałe sesje ACP tylko wtedy, gdy nie pozostaje żadne aktywne powiązanie rozmowy.
</Step>
<Step title="Stemplowanie czyszczenia">
Ustawia znacznik czasu `cleanupAfter` na zadaniach terminalnych (endedAt + 7 dni). Podczas przechowywania utracone zadania nadal pojawiają się w audycie jako ostrzeżenia; po wygaśnięciu `cleanupAfter` albo gdy brakuje metadanych czyszczenia, są błędami.
<Step title="Oznaczanie czyszczenia">
Ustawia znacznik czasu `cleanupAfter` dla zadań terminalnych (endedAt + 7 dni). Podczas retencji utracone zadania nadal pojawiają się w audycie jako ostrzeżenia; po wygaśnięciu `cleanupAfter` albo gdy brakuje metadanych czyszczenia, są błędami.
</Step>
<Step title="Przycinanie">
Usuwa rekordy po ich dacie `cleanupAfter`.
@ -337,35 +337,35 @@ Proces sprzątający uruchamia się co **60 sekund** i obsługuje cztery rzeczy:
</Steps>
<Note>
**Przechowywanie:** rekordy zadań terminalnych są przechowywane przez **7 dni**, a następnie automatycznie przycinane. Konfiguracja nie jest potrzebna.
**Retencja:** rekordy zadań terminalnych są przechowywane przez **7 dni**, a następnie automatycznie przycinane. Konfiguracja nie jest wymagana.
</Note>
## Jak zadania odnoszą się do innych systemów
<AccordionGroup>
<Accordion title="Zadania i Task Flow">
[Task Flow](/pl/automation/taskflow) to warstwa orkiestracji przepływów ponad zadaniami w tle. Pojedynczy przepływ może koordynować wiele zadań w trakcie swojego życia, używając trybów synchronizacji zarządzanej lub lustrzanej. Użyj `openclaw tasks`, aby sprawdzić poszczególne rekordy zadań, oraz `openclaw tasks flow`, aby sprawdzić orkiestrujący przepływ.
[Task Flow](/pl/automation/taskflow) to warstwa orkiestracji przepływu nad zadaniami w tle. Pojedynczy przepływ może koordynować wiele zadań w trakcie swojego życia, używając zarządzanych lub lustrzanych trybów synchronizacji. Użyj `openclaw tasks`, aby sprawdzić pojedyncze rekordy zadań, oraz `openclaw tasks flow`, aby sprawdzić orkiestrujący przepływ.
Zobacz [Task Flow](/pl/automation/taskflow), aby poznać szczegóły.
Szczegóły znajdziesz w [Task Flow](/pl/automation/taskflow).
</Accordion>
<Accordion title="Zadania i cron">
**Definicja** zadania cron znajduje się w `~/.openclaw/cron/jobs.json`; stan wykonania runtime znajduje się obok niej w `~/.openclaw/cron/jobs-state.json`. **Każde** wykonanie cron tworzy rekord zadania — zarówno w sesji głównej, jak i izolowane. Zadania cron w sesji głównej domyślnie używają zasady powiadamiania `silent`, więc są śledzone bez generowania powiadomień.
**Definicja** zadania cron znajduje się w `~/.openclaw/cron/jobs.json`; stan wykonania środowiska wykonawczego znajduje się obok w `~/.openclaw/cron/jobs-state.json`. **Każde** wykonanie cron tworzy rekord zadania — zarówno w sesji głównej, jak i izolowanej. Zadania cron w sesji głównej domyślnie używają zasady powiadamiania `silent`, więc są śledzone bez generowania powiadomień.
Zobacz [Zadania Cron](/pl/automation/cron-jobs).
</Accordion>
<Accordion title="Zadania i heartbeat">
Uruchomienia Heartbeat są turami w sesji głównej — nie tworzą rekordów zadań. Gdy zadanie się zakończy, może wyzwolić wybudzenie Heartbeat, aby wynik był szybko widoczny.
<Accordion title="Zadania i Heartbeat">
Uruchomienia Heartbeat to tury sesji głównej — nie tworzą rekordów zadań. Gdy zadanie się zakończy, może wyzwolić wybudzenie heartbeat, aby wynik był widoczny natychmiast.
Zobacz [Heartbeat](/pl/gateway/heartbeat).
</Accordion>
<Accordion title="Zadania i sesje">
Zadanie może odwoływać się do `childSessionKey` (gdzie działa praca) i `requesterSessionKey` (kto ją uruchomił). Sesje są kontekstem rozmowy; zadania są śledzeniem aktywności na tej warstwie.
Zadanie może odwoływać się do `childSessionKey` (gdzie wykonywana jest praca) i `requesterSessionKey` (kto je uruchomił). Sesje są kontekstem rozmowy; zadania są śledzeniem aktywności nad nimi.
</Accordion>
<Accordion title="Zadania i uruchomienia agenta">
`runId` zadania łączy się z uruchomieniem agenta wykonującym pracę. Zdarzenia cyklu życia agenta (start, koniec, błąd) automatycznie aktualizują status zadania — nie musisz ręcznie zarządzać cyklem życia.
`runId` zadania łączy je z uruchomieniem agenta wykonującym pracę. Zdarzenia cyklu życia agenta (start, koniec, błąd) automatycznie aktualizują status zadania — nie musisz ręcznie zarządzać cyklem życia.
</Accordion>
</AccordionGroup>
@ -373,6 +373,6 @@ Proces sprzątający uruchamia się co **60 sekund** i obsługuje cztery rzeczy:
- [Automatyzacja i zadania](/pl/automation) — wszystkie mechanizmy automatyzacji w skrócie
- [CLI: Zadania](/pl/cli/tasks) — dokumentacja poleceń CLI
- [Heartbeat](/pl/gateway/heartbeat) — okresowe tury w sesji głównej
- [Heartbeat](/pl/gateway/heartbeat) — okresowe tury sesji głównej
- [Zaplanowane zadania](/pl/automation/cron-jobs) — planowanie pracy w tle
- [Task Flow](/pl/automation/taskflow) — orkiestracja przepływów ponad zadaniami
- [Task Flow](/pl/automation/taskflow) — orkiestracja przepływu nad zadaniami

239
docs/pl/channels/bluebubbles.md
View File

@ -2,42 +2,42 @@
read_when:
- Konfigurowanie kanału BlueBubbles
- Rozwiązywanie problemów z parowaniem Webhook
- Konfigurowanie iMessage w systemie macOS
- Konfigurowanie iMessage na macOS
sidebarTitle: BlueBubbles
summary: iMessage przez serwer BlueBubbles na macOS (wysyłanie/odbieranie przez REST, wskaźniki pisania, reakcje, parowanie, działania zaawansowane).
summary: iMessage za pośrednictwem serwera macOS BlueBubbles (wysyłanie/odbieranie przez REST, wskaźniki pisania, reakcje, parowanie, zaawansowane działania).
title: BlueBubbles
x-i18n:
generated_at: "2026-04-30T09:35:42Z"
generated_at: "2026-05-01T09:56:26Z"
model: gpt-5.5
provider: openai
source_hash: 7a77b248ed86eb4114f8b7f1fc6bd4cea004d65095a0439a4a8c814bc180082c
source_hash: 499cc2a46db6e0eddfb897e96ec4b3e4a39ba9f2f6da8e7485c1c46562de4145
source_path: channels/bluebubbles.md
workflow: 16
---
Status: dołączony plugin, który komunikuje się z serwerem BlueBubbles na macOS przez HTTP. **Zalecany do integracji z iMessage** ze względu na bogatsze API i łatwiejszą konfigurację w porównaniu ze starszym kanałem imsg.
Status: dołączony Plugin komunikujący się z serwerem BlueBubbles macOS przez HTTP. **Zalecany do integracji z iMessage** ze względu na bogatsze API i łatwiejszą konfigurację w porównaniu ze starszym kanałem imsg.
<Note>
Bieżące wydania OpenClaw zawierają BlueBubbles, więc normalne pakietowane kompilacje nie wymagają osobnego kroku `openclaw plugins install`.
Bieżące wydania OpenClaw zawierają BlueBubbles, więc normalne spakowane kompilacje nie wymagają osobnego kroku `openclaw plugins install`.
</Note>
## Omówienie
- Działa na macOS za pośrednictwem aplikacji pomocniczej BlueBubbles ([bluebubbles.app](https://bluebubbles.app)).
- Zalecane/przetestowane: macOS Sequoia (15). macOS Tahoe (26) działa; edycja jest obecnie uszkodzona w Tahoe, a aktualizacje ikon grup mogą zgłaszać powodzenie, ale się nie synchronizować.
- OpenClaw komunikuje się z nim przez jego REST API (`GET /api/v1/ping`, `POST /message/text`, `POST /chat/:id/*`).
- Wiadomości przychodzące docierają przez webhooki; odpowiedzi wychodzące, wskaźniki pisania, potwierdzenia odczytu i tapbacki są wywołaniami REST.
- Załączniki i naklejki są pobierane jako multimedia przychodzące (i udostępniane agentowi, gdy to możliwe).
- Odpowiedzi Auto-TTS, które syntetyzują dźwięk MP3 lub CAF, są dostarczane jako dymki notatek głosowych iMessage zamiast zwykłych załączników plików.
- Parowanie/lista dozwolonych działa tak samo jak w innych kanałach (`/channels/pairing` itd.) z `channels.bluebubbles.allowFrom` + kodami parowania.
- Reakcje są udostępniane jako zdarzenia systemowe tak jak w Slack/Telegram, aby agenci mogli je „wspomnieć” przed odpowiedzią.
- Zalecane/testowane: macOS Sequoia (15). macOS Tahoe (26) działa; edycja jest obecnie uszkodzona w Tahoe, a aktualizacje ikon grup mogą zgłaszać powodzenie, ale się nie synchronizować.
- OpenClaw komunikuje się z nim przez REST API (`GET /api/v1/ping`, `POST /message/text`, `POST /chat/:id/*`).
- Wiadomości przychodzące docierają przez webhooks; odpowiedzi wychodzące, wskaźniki pisania, potwierdzenia odczytu i tapbacki są wywołaniami REST.
- Załączniki i naklejki są pobierane jako przychodzące multimedia (i udostępniane agentowi, gdy to możliwe).
- Automatyczne odpowiedzi TTS, które syntetyzują dźwięk MP3 lub CAF, są dostarczane jako dymki notatek głosowych iMessage zamiast zwykłych załączników plików.
- Parowanie/lista dozwolonych działa tak samo jak w innych kanałach (`/channels/pairing` itp.) z `channels.bluebubbles.allowFrom` + kodami parowania.
- Reakcje są udostępniane jako zdarzenia systemowe tak jak w Slack/Telegram, więc agenci mogą je „wzmiankować” przed odpowiedzią.
- Funkcje zaawansowane: edycja, cofanie wysłania, wątki odpowiedzi, efekty wiadomości, zarządzanie grupami.
## Szybki start
<Steps>
<Step title="Zainstaluj BlueBubbles">
Zainstaluj serwer BlueBubbles na Macu (postępuj zgodnie z instrukcjami na [bluebubbles.app/install](https://bluebubbles.app/install)).
Zainstaluj serwer BlueBubbles na swoim Macu (postępuj zgodnie z instrukcjami na [bluebubbles.app/install](https://bluebubbles.app/install)).
</Step>
<Step title="Włącz web API">
W konfiguracji BlueBubbles włącz web API i ustaw hasło.
@ -59,26 +59,26 @@ Bieżące wydania OpenClaw zawierają BlueBubbles, więc normalne pakietowane ko
```
</Step>
<Step title="Skieruj webhooki do gatewaya">
Skieruj webhooki BlueBubbles do swojego gatewaya (przykład: `https://your-gateway-host:3000/bluebubbles-webhook?password=<password>`).
<Step title="Skieruj webhooks do gateway">
Skieruj webhooks BlueBubbles do swojego gateway (przykład: `https://your-gateway-host:3000/bluebubbles-webhook?password=<password>`).
</Step>
<Step title="Uruchom gateway">
Uruchom gateway; zarejestruje on obsługę webhooka i rozpocznie parowanie.
Uruchom gateway; zarejestruje obsługę webhook i rozpocznie parowanie.
</Step>
</Steps>
<Warning>
**Bezpieczeństwo**
- Zawsze ustaw hasło webhooka.
- Uwierzytelnianie webhooka jest zawsze wymagane. OpenClaw odrzuca żądania webhooka BlueBubbles, jeśli nie zawierają hasła/guid zgodnego z `channels.bluebubbles.password` (na przykład `?password=<password>` lub `x-password`), niezależnie od topologii loopback/proxy.
- Uwierzytelnianie hasłem jest sprawdzane przed odczytaniem/przetworzeniem pełnych treści webhooka.
- Zawsze ustaw hasło webhook.
- Uwierzytelnianie webhook jest zawsze wymagane. OpenClaw odrzuca żądania webhook BlueBubbles, chyba że zawierają hasło/guid pasujące do `channels.bluebubbles.password` (na przykład `?password=<password>` lub `x-password`), niezależnie od topologii loopback/proxy.
- Uwierzytelnianie hasłem jest sprawdzane przed odczytaniem/przeanalizowaniem pełnych treści webhook.
</Warning>
## Utrzymywanie aktywności Messages.app (konfiguracje VM / headless)
## Utrzymywanie Messages.app przy życiu (VM / konfiguracje headless)
Niektóre konfiguracje VM macOS / always-on mogą doprowadzić do przejścia Messages.app w stan „bezczynności” (zdarzenia przychodzące zatrzymują się, dopóki aplikacja nie zostanie otwarta/przeniesiona na pierwszy plan). Prostym obejściem jest **szturchanie Messages co 5 minut** za pomocą AppleScript + LaunchAgent.
Niektóre konfiguracje macOS VM / zawsze włączone mogą doprowadzić do przejścia Messages.app w stan „bezczynności” (zdarzenia przychodzące zatrzymują się, dopóki aplikacja nie zostanie otwarta/przeniesiona na pierwszy plan). Prostym obejściem jest **pobudzanie Messages co 5 minut** za pomocą AppleScript + LaunchAgent.
<Steps>
<Step title="Zapisz AppleScript">
@ -132,10 +132,10 @@ Niektóre konfiguracje VM macOS / always-on mogą doprowadzić do przejścia Mes
</plist>
```
Uruchamia się to **co 300 sekund** oraz **przy logowaniu**. Pierwsze uruchomienie może wywołać monity macOS **Automation** (`osascript` → Messages). Zatwierdź je w tej samej sesji użytkownika, która uruchamia LaunchAgent.
To uruchamia się **co 300 sekund** i **przy logowaniu**. Pierwsze uruchomienie może wywołać monity macOS **Automatyzacja** (`osascript` → Messages). Zatwierdź je w tej samej sesji użytkownika, która uruchamia LaunchAgent.
</Step>
<Step title="Wczytaj go">
<Step title="Załaduj go">
```bash
launchctl unload ~/Library/LaunchAgents/com.user.poke-messages.plist 2>/dev/null || true
launchctl load ~/Library/LaunchAgents/com.user.poke-messages.plist
@ -151,56 +151,56 @@ BlueBubbles jest dostępny w interaktywnym onboardingu:
openclaw onboard
```
Kreator pyta o:
Kreator prosi o:
<ParamField path="Server URL" type="string" required>
<ParamField path="Adres URL serwera" type="string" required>
Adres serwera BlueBubbles (np. `http://192.168.1.100:1234`).
</ParamField>
<ParamField path="Password" type="string" required>
<ParamField path="Hasło" type="string" required>
Hasło API z ustawień BlueBubbles Server.
</ParamField>
<ParamField path="Webhook path" type="string" default="/bluebubbles-webhook">
Ścieżka endpointu webhooka.
<ParamField path="Ścieżka webhook" type="string" default="/bluebubbles-webhook">
Ścieżka punktu końcowego webhook.
</ParamField>
<ParamField path="DM policy" type="string">
<ParamField path="Zasada DM" type="string">
`pairing`, `allowlist`, `open` lub `disabled`.
</ParamField>
<ParamField path="Allow list" type="string[]">
Numery telefonów, adresy e-mail lub cele czatu.
<ParamField path="Lista dozwolonych" type="string[]">
Numery telefonów, adresy e-mail lub cele czatów.
</ParamField>
Możesz także dodać BlueBubbles przez CLI:
Możesz też dodać BlueBubbles przez CLI:
```
openclaw channels add bluebubbles --http-url http://192.168.1.100:1234 --password <password>
```
## Kontrola dostępu (DM-y + grupy)
## Kontrola dostępu (DM + grupy)
<Tabs>
<Tab title="DM-y">
<Tab title="DM">
- Domyślnie: `channels.bluebubbles.dmPolicy = "pairing"`.
- Nieznani nadawcy otrzymują kod parowania; wiadomości są ignorowane do czasu zatwierdzenia (kody wygasają po 1 godzinie).
- Zatwierdź przez:
- `openclaw pairing list bluebubbles`
- `openclaw pairing approve bluebubbles <CODE>`
- Parowanie jest domyślną wymianą tokena. Szczegóły: [Parowanie](/pl/channels/pairing)
- Parowanie jest domyślną wymianą tokenów. Szczegóły: [Parowanie](/pl/channels/pairing)
</Tab>
<Tab title="Grupy">
- `channels.bluebubbles.groupPolicy = open | allowlist | disabled` (domyślnie: `allowlist`).
- `channels.bluebubbles.groupAllowFrom` kontroluje, kto może wyzwalać działanie w grupach, gdy ustawiono `allowlist`.
- `channels.bluebubbles.groupAllowFrom` kontroluje, kto może wyzwalać w grupach, gdy ustawione jest `allowlist`.
</Tab>
</Tabs>
### Wzbogacanie nazw kontaktów (macOS, opcjonalne)
### Wzbogacanie nazw kontaktów (macOS, opcjonalnie)
Webhooki grup BlueBubbles często zawierają tylko surowe adresy uczestników. Jeśli chcesz, aby kontekst `GroupMembers` pokazywał zamiast nich lokalne nazwy kontaktów, możesz włączyć wzbogacanie z lokalnych Kontaktów na macOS:
Webhooks grup BlueBubbles często zawierają tylko surowe adresy uczestników. Jeśli chcesz, aby kontekst `GroupMembers` pokazywał zamiast tego lokalne nazwy kontaktów, możesz włączyć lokalne wzbogacanie z Kontaktów na macOS:
- `channels.bluebubbles.enrichGroupParticipantsFromContacts = true` włącza wyszukiwanie. Domyślnie: `false`.
- Wyszukiwania są uruchamiane dopiero po tym, jak dostęp do grupy, autoryzacja poleceń i bramka wzmianek przepuszczą wiadomość.
- Wzbogacani są tylko uczestnicy telefoniczni bez nazw.
- Wyszukiwania uruchamiają się dopiero po tym, jak dostęp grupowy, autoryzacja poleceń i bramka wzmianki przepuszczą wiadomość.
- Wzbogacani są tylko nienazwani uczestnicy telefoniczni.
- Surowe numery telefonów pozostają wartością zapasową, gdy nie zostanie znalezione lokalne dopasowanie.
```json5
@ -213,13 +213,13 @@ Webhooki grup BlueBubbles często zawierają tylko surowe adresy uczestników. J
}
```
### Bramka wzmianek (grupy)
### Bramka wzmianki (grupy)
BlueBubbles obsługuje bramkę wzmianek dla czatów grupowych, zgodnie z zachowaniem iMessage/WhatsApp:
BlueBubbles obsługuje bramkę wzmianki dla czatów grupowych, zgodnie z zachowaniem iMessage/WhatsApp:
- Używa `agents.list[].groupChat.mentionPatterns` (lub `messages.groupChat.mentionPatterns`) do wykrywania wzmianek.
- Gdy `requireMention` jest włączone dla grupy, agent odpowiada tylko po wzmiance.
- Polecenia kontrolne od autoryzowanych nadawców omijają bramkę wzmianek.
- Polecenia sterujące od autoryzowanych nadawców omijają bramkę wzmianki.
Konfiguracja dla grupy:
@ -240,13 +240,13 @@ Konfiguracja dla grupy:
### Bramka poleceń
- Polecenia kontrolne (np. `/config`, `/model`) wymagają autoryzacji.
- Polecenia sterujące (np. `/config`, `/model`) wymagają autoryzacji.
- Używa `allowFrom` i `groupAllowFrom` do określenia autoryzacji poleceń.
- Autoryzowani nadawcy mogą uruchamiać polecenia kontrolne nawet bez wzmianki w grupach.
- Autoryzowani nadawcy mogą uruchamiać polecenia sterujące nawet bez wzmiankowania w grupach.
### System prompt dla grupy
### Systemowy prompt dla grupy
Każdy wpis w `channels.bluebubbles.groups.*` akceptuje opcjonalny ciąg `systemPrompt`. Wartość jest wstrzykiwana do promptu systemowego agenta w każdej turze obsługującej wiadomość w tej grupie, dzięki czemu możesz ustawić personę lub reguły zachowania dla grupy bez edytowania promptów agenta:
Każdy wpis w `channels.bluebubbles.groups.*` akceptuje opcjonalny ciąg `systemPrompt`. Wartość jest wstrzykiwana do systemowego promptu agenta w każdej turze obsługującej wiadomość w tej grupie, dzięki czemu możesz ustawić osobowość lub reguły zachowania dla grupy bez edytowania promptów agenta:
```json5
{
@ -262,9 +262,9 @@ Każdy wpis w `channels.bluebubbles.groups.*` akceptuje opcjonalny ciąg `system
}
```
Klucz odpowiada temu, co BlueBubbles zgłasza jako `chatGuid` / `chatIdentifier` / numeryczny `chatId` dla grupy, a wpis z symbolem wieloznacznym `"*"` zapewnia wartość domyślną dla każdej grupy bez dokładnego dopasowania (ten sam wzorzec używany przez `requireMention` i zasady narzędzi dla grup). Dokładne dopasowania zawsze wygrywają z symbolem wieloznacznym. DM-y ignorują to pole; zamiast tego użyj dostosowania promptu na poziomie agenta lub konta.
Klucz odpowiada temu, co BlueBubbles zgłasza jako `chatGuid` / `chatIdentifier` / numeryczne `chatId` dla grupy, a wpis wieloznaczny `"*"` zapewnia domyślne ustawienie dla każdej grupy bez dokładnego dopasowania (ten sam wzorzec używany przez `requireMention` i zasady narzędzi dla grup). Dokładne dopasowania zawsze wygrywają z wieloznacznikiem. DM ignorują to pole; zamiast tego użyj dostosowania promptu na poziomie agenta lub konta.
#### Przykład działania: odpowiedzi w wątkach i reakcje tapback (Private API)
#### Przykład praktyczny: odpowiedzi w wątkach i reakcje tapback (Private API)
Po włączeniu BlueBubbles Private API wiadomości przychodzące docierają z krótkimi identyfikatorami wiadomości (na przykład `[[reply_to:5]]`), a agent może wywołać `action=reply`, aby odpowiedzieć w wątku na konkretną wiadomość, albo `action=react`, aby dodać tapback. `systemPrompt` dla grupy to niezawodny sposób, aby agent wybierał właściwe narzędzie:
@ -290,20 +290,20 @@ Po włączeniu BlueBubbles Private API wiadomości przychodzące docierają z kr
}
```
Reakcje tapback i odpowiedzi w wątkach wymagają BlueBubbles Private API; zobacz [Zaawansowane akcje](#advanced-actions) i [Identyfikatory wiadomości](#message-ids-short-vs-full), aby poznać mechanikę działania.
Reakcje tapback i odpowiedzi w wątkach wymagają BlueBubbles Private API; zobacz [Akcje zaawansowane](#advanced-actions) i [Identyfikatory wiadomości](#message-ids-short-vs-full), aby poznać podstawową mechanikę.
## Powiązania konwersacji ACP
Czaty BlueBubbles można przekształcić w trwałe obszary robocze ACP bez zmiany warstwy transportowej.
Czaty BlueBubbles można przekształcać w trwałe obszary robocze ACP bez zmiany warstwy transportowej.
Szybki przepływ operatora:
- Uruchom `/acp spawn codex --bind here` w DM-ie lub dozwolonym czacie grupowym.
- Przyszłe wiadomości w tej samej konwersacji BlueBubbles są kierowane do uruchomionej sesji ACP.
- Uruchom `/acp spawn codex --bind here` w DM lub dozwolonym czacie grupowym.
- Przyszłe wiadomości w tej samej konwersacji BlueBubbles będą kierowane do utworzonej sesji ACP.
- `/new` i `/reset` resetują tę samą powiązaną sesję ACP w miejscu.
- `/acp close` zamyka sesję ACP i usuwa powiązanie.
Skonfigurowane trwałe powiązania są także obsługiwane przez wpisy `bindings[]` najwyższego poziomu z `type: "acp"` i `match.channel: "bluebubbles"`.
Skonfigurowane trwałe powiązania są też obsługiwane przez wpisy najwyższego poziomu `bindings[]` z `type: "acp"` i `match.channel: "bluebubbles"`.
`match.peer.id` może używać dowolnej obsługiwanej formy celu BlueBubbles:
@ -362,9 +362,9 @@ Zobacz [Agenci ACP](/pl/tools/acp-agents), aby poznać wspólne zachowanie powi
}
```
## Zaawansowane akcje
## Zaawansowane działania
BlueBubbles obsługuje zaawansowane akcje wiadomości, gdy są włączone w konfiguracji:
BlueBubbles obsługuje zaawansowane działania na wiadomościach, gdy są włączone w konfiguracji:
```json5
{
@ -389,20 +389,20 @@ BlueBubbles obsługuje zaawansowane akcje wiadomości, gdy są włączone w konf
```
<AccordionGroup>
<Accordion title="Dostępne akcje">
- **react**: Dodaj/usuń reakcje tapback (`messageId`, `emoji`, `remove`). Natywny zestaw tapbacków iMessage to `love`, `like`, `dislike`, `laugh`, `emphasize` i `question`. Gdy agent wybierze emoji spoza tego zestawu (na przykład `👀`), narzędzie reakcji wraca do `love`, aby tapback nadal został wyrenderowany zamiast powodować niepowodzenie całego żądania. Skonfigurowane reakcje potwierdzeń nadal są walidowane rygorystycznie i zwracają błąd dla nieznanych wartości.
<Accordion title="Dostępne działania">
- **react**: Dodaj/usuń reakcje tapback (`messageId`, `emoji`, `remove`). Natywny zestaw tapback iMessage to `love`, `like`, `dislike`, `laugh`, `emphasize` i `question`. Gdy agent wybierze emoji spoza tego zestawu (na przykład `👀`), narzędzie reakcji używa awaryjnie `love`, aby tapback nadal się wyrenderował zamiast powodować niepowodzenie całego żądania. Skonfigurowane reakcje potwierdzenia nadal są walidowane ściśle i zwracają błąd dla nieznanych wartości.
- **edit**: Edytuj wysłaną wiadomość (`messageId`, `text`).
- **unsend**: Cofnij wysłanie wiadomości (`messageId`).
- **reply**: Odpowiedz na konkretną wiadomość (`messageId`, `text`, `to`).
- **sendWithEffect**: Wyślij z efektem iMessage (`text`, `to`, `effectId`).
- **renameGroup**: Zmień nazwę czatu grupowego (`chatGuid`, `displayName`).
- **setGroupIcon**: Ustaw ikonę/zdjęcie czatu grupowego (`chatGuid`, `media`) — zawodne w macOS 26 Tahoe (API może zwrócić sukces, ale ikona się nie zsynchronizuje).
- **setGroupIcon**: Ustaw ikonę/zdjęcie czatu grupowego (`chatGuid`, `media`) — zawodne na macOS 26 Tahoe (API może zwrócić sukces, ale ikona się nie zsynchronizuje).
- **addParticipant**: Dodaj kogoś do grupy (`chatGuid`, `address`).
- **removeParticipant**: Usuń kogoś z grupy (`chatGuid`, `address`).
- **leaveGroup**: Opuść czat grupowy (`chatGuid`).
- **upload-file**: Wyślij multimedia/pliki (`to`, `buffer`, `filename`, `asVoice`).
- Notatki głosowe: ustaw `asVoice: true` z dźwiękiem **MP3** lub **CAF**, aby wysłać jako wiadomość głosową iMessage. BlueBubbles konwertuje MP3 → CAF podczas wysyłania notatek głosowych.
- Starszy alias: `sendAttachment` nadal działa, ale `upload-file` jest kanoniczną nazwą akcji.
- Starszy alias: `sendAttachment` nadal działa, ale kanoniczną nazwą działania jest `upload-file`.
</Accordion>
</AccordionGroup>
@ -414,27 +414,27 @@ OpenClaw może udostępniać _krótkie_ identyfikatory wiadomości (np. `1`, `2`
- `MessageSid` / `ReplyToId` mogą być krótkimi identyfikatorami.
- `MessageSidFull` / `ReplyToIdFull` zawierają pełne identyfikatory dostawcy.
- Krótkie identyfikatory są przechowywane w pamięci; mogą wygasnąć po restarcie lub usunięciu z pamięci podręcznej.
- Akcje akceptują krótki lub pełny `messageId`, ale krótkie identyfikatory zwrócą błąd, jeśli nie będą już dostępne.
- Działania akceptują krótki albo pełny `messageId`, ale krótkie identyfikatory zwrócą błąd, jeśli nie będą już dostępne.
Używaj pełnych identyfikatorów dla trwałych automatyzacji i przechowywania:
Używaj pełnych identyfikatorów w trwałych automatyzacjach i magazynach danych:
- Szablony: `{{MessageSidFull}}`, `{{ReplyToIdFull}}`
- Kontekst: `MessageSidFull` / `ReplyToIdFull` w przychodzących payloadach
- Kontekst: `MessageSidFull` / `ReplyToIdFull` w przychodzących ładunkach
Zobacz [Konfigurację](/pl/gateway/configuration), aby poznać zmienne szablonów.
Zobacz [Konfiguracja](/pl/gateway/configuration), aby poznać zmienne szablonów.
<a id="coalescing-split-send-dms-command--url-in-one-composition"></a>
## Scalanie podzielonych wysyłek DM (polecenie + URL w jednej kompozycji)
## Scalanie rozdzielonych wiadomości DM (polecenie + URL w jednej kompozycji)
Gdy użytkownik wpisze polecenie i URL razem w iMessage — np. `Dump https://example.com/article` — Apple dzieli wysyłkę na **dwa osobne dostarczenia Webhook**:
Gdy użytkownik wpisze razem polecenie i URL w iMessage — np. `Dump https://example.com/article` — Apple rozdziela wysyłkę na **dwa osobne dostarczenia Webhook**:
1. Wiadomość tekstową (`"Dump"`).
2. Dymek podglądu URL (`"https://..."`) z obrazami podglądu OG jako załącznikami.
Dwa webhooki docierają do OpenClaw w odstępie ok. 0,8–2,0 s w większości konfiguracji. Bez scalania agent otrzymuje samo polecenie w turze 1, odpowiada (często „wyślij mi URL”) i widzi URL dopiero w turze 2 — wtedy kontekst polecenia jest już utracony.
W większości konfiguracji oba Webhooki docierają do OpenClaw w odstępie około 0,8-2,0 s. Bez scalania agent otrzymuje samo polecenie w turze 1, odpowiada (często „wyślij mi URL”) i widzi URL dopiero w turze 2 — wtedy kontekst polecenia jest już utracony.
`channels.bluebubbles.coalesceSameSenderDms` włącza dla DM scalanie kolejnych webhooków od tego samego nadawcy w jedną turę agenta. Czaty grupowe nadal są kluczowane per wiadomość, więc struktura tur wielu użytkowników jest zachowana.
`channels.bluebubbles.coalesceSameSenderDms` włącza dla DM scalanie kolejnych Webhooków od tego samego nadawcy w jedną turę agenta. Czaty grupowe nadal są kluczowane według wiadomości, więc struktura tur wielu użytkowników zostaje zachowana.
<Tabs>
<Tab title="Kiedy włączyć">
@ -442,12 +442,12 @@ Dwa webhooki docierają do OpenClaw w odstępie ok. 0,8–2,0 s w większości k
- Dostarczasz Skills, które oczekują `command + payload` w jednej wiadomości (dump, paste, save, queue itd.).
- Twoi użytkownicy wklejają URL-e, obrazy lub długą treść obok poleceń.
- Możesz zaakceptować dodatkowe opóźnienie tur DM (zobacz niżej).
- Możesz zaakceptować dodatkowe opóźnienie tury DM (zobacz niżej).
Pozostaw wyłączone, gdy:
- Potrzebujesz minimalnego opóźnienia polecenia dla jednowyrazowych wyzwalaczy DM.
- Wszystkie Twoje przepływy są jednorazowymi poleceniami bez późniejszych payloadów.
- Potrzebujesz minimalnego opóźnienia poleceń dla jednowyrazowych wyzwalaczy DM.
- Wszystkie Twoje przepływy to jednorazowe polecenia bez następujących po nich ładunków.
</Tab>
<Tab title="Włączanie">
@ -461,7 +461,7 @@ Dwa webhooki docierają do OpenClaw w odstępie ok. 0,8–2,0 s w większości k
}
```
Przy włączonej fladze i bez jawnego `messages.inbound.byChannel.bluebubbles` okno debounce rozszerza się do **2500 ms** (domyślnie bez scalania to 500 ms). Szersze okno jest wymagane — rytm podzielonej wysyłki Apple 0,8–2,0 s nie mieści się w ciaśniejszej wartości domyślnej.
Przy włączonej fladze i bez jawnego `messages.inbound.byChannel.bluebubbles` okno debounce rozszerza się do **2500 ms** (domyślna wartość bez scalania to 500 ms). Szersze okno jest wymagane — kadencja rozdzielonej wysyłki Apple wynosząca 0,8-2,0 s nie mieści się w ciaśniejszej wartości domyślnej.
Aby samodzielnie dostroić okno:
@ -481,30 +481,30 @@ Dwa webhooki docierają do OpenClaw w odstępie ok. 0,8–2,0 s w większości k
</Tab>
<Tab title="Kompromisy">
- **Dodatkowe opóźnienie dla poleceń sterujących DM.** Przy włączonej fladze wiadomości z poleceniami sterującymi DM (takie jak `Dump`, `Save` itd.) czekają teraz do końca okna debounce przed wysłaniem, na wypadek gdyby nadchodził Webhook z payloadem. Polecenia czatu grupowego zachowują natychmiastową wysyłkę.
- **Scalone wyjście jest ograniczone** — scalony tekst ma limit 4000 znaków z jawnym znacznikiem `…[truncated]`; załączniki mają limit 20; wpisy źródłowe mają limit 10 (po przekroczeniu zachowywane są pierwszy i najnowsze). Każdy źródłowy `messageId` nadal trafia do deduplikacji przychodzącej, więc późniejsze odtworzenie dowolnego pojedynczego zdarzenia przez MessagePoller jest rozpoznawane jako duplikat.
- **Opcjonalne, per kanał.** Inne kanały (Telegram, WhatsApp, Slack, …) pozostają bez zmian.
- **Dodatkowe opóźnienie dla poleceń sterujących DM.** Przy włączonej fladze wiadomości poleceń sterujących DM (takie jak `Dump`, `Save` itd.) czekają teraz do końca okna debounce przed wysłaniem, na wypadek gdyby nadchodził Webhook z ładunkiem. Polecenia z czatów grupowych zachowują natychmiastowe wysyłanie.
- **Scalony wynik jest ograniczony** — scalony tekst ma limit 4000 znaków z jawnym znacznikiem `…[truncated]`; załączniki mają limit 20; wpisy źródłowe mają limit 10 (powyżej tego progu zachowywane są pierwszy i najnowszy). Każde źródłowe `messageId` nadal trafia do deduplikacji przychodzących, więc późniejsze odtworzenie dowolnego pojedynczego zdarzenia przez MessagePoller zostanie rozpoznane jako duplikat.
- **Włączane opcjonalnie, per kanał.** Inne kanały (Telegram, WhatsApp, Slack, …) pozostają bez zmian.
</Tab>
</Tabs>
### Scenariusze i to, co widzi agent
| Użytkownik komponuje | Apple dostarcza | Flaga wyłączona (domyślnie) | Flaga włączona + okno 2500 ms |
| ------------------------------------------------------------------ | ------------------------- | --------------------------------------- | ----------------------------------------------------------------------- |
| `Dump https://example.com` (jedna wysyłka) | 2 webhooki w odstępie ~1 s | Dwie tury agenta: samo „Dump”, potem URL | Jedna tura: scalony tekst `Dump https://example.com` |
| `Save this 📎image.jpg caption` (załącznik + tekst) | 2 webhooki | Dwie tury | Jedna tura: tekst + obraz |
| `/status` (samodzielne polecenie) | 1 Webhook | Natychmiastowa wysyłka | **Poczekaj do końca okna, potem wyślij** |
| Samodzielnie wklejony URL | 1 Webhook | Natychmiastowa wysyłka | Natychmiastowa wysyłka (tylko jeden wpis w kubełku) |
| Tekst + URL wysłane jako dwie celowo osobne wiadomości, minuty osobno | 2 webhooki poza oknem | Dwie tury | Dwie tury (okno wygasa między nimi) |
| Szybki zalew (>10 małych DM w oknie) | N webhooków | N tur | Jedna tura, ograniczone wyjście (pierwsze + najnowsze, zastosowane limity tekstu/załączników) |
| Użytkownik komponuje | Apple dostarcza | Flaga wyłączona (domyślnie) | Flaga włączona + okno 2500 ms |
| ------------------------------------------------------------------ | --------------------------------------- | ---------------------------------------------- | ----------------------------------------------------------------------- |
| `Dump https://example.com` (jedna wysyłka) | 2 Webhooki w odstępie około 1 s | Dwie tury agenta: samo „Dump”, potem URL | Jedna tura: scalony tekst `Dump https://example.com` |
| `Save this 📎image.jpg caption` (załącznik + tekst) | 2 Webhooki | Dwie tury | Jedna tura: tekst + obraz |
| `/status` (samodzielne polecenie) | 1 Webhook | Natychmiastowe wysłanie | **Czekaj do końca okna, potem wyślij** |
| URL wklejony samodzielnie | 1 Webhook | Natychmiastowe wysłanie | Natychmiastowe wysłanie (tylko jeden wpis w kubełku) |
| Tekst + URL wysłane jako dwie celowo osobne wiadomości, w odstępie minut | 2 Webhooki poza oknem | Dwie tury | Dwie tury (okno wygasa między nimi) |
| Szybki zalew (>10 małych DM w oknie) | N Webhooków | N tur | Jedna tura, ograniczony wynik (pierwsze + najnowsze, zastosowane limity tekstu/załączników) |
### Rozwiązywanie problemów ze scalaniem podzielonych wysyłek
### Rozwiązywanie problemów ze scalaniem rozdzielonej wysyłki
Jeśli flaga jest włączona, a podzielone wysyłki nadal docierają jako dwie tury, sprawdź każdą warstwę:
Jeśli flaga jest włączona, a rozdzielone wysyłki nadal docierają jako dwie tury, sprawdź każdą warstwę:
<AccordionGroup>
<Accordion title="Konfiguracja faktycznie załadowana">
<Accordion title="Konfiguracja rzeczywiście załadowana">
```
grep coalesceSameSenderDms ~/.openclaw/openclaw.json
```
@ -513,23 +513,23 @@ Jeśli flaga jest włączona, a podzielone wysyłki nadal docierają jako dwie t
</Accordion>
<Accordion title="Okno debounce wystarczająco szerokie dla Twojej konfiguracji">
Sprawdź dziennik serwera BlueBubbles w `~/Library/Logs/bluebubbles-server/main.log`:
Sprawdź dziennik serwera BlueBubbles pod `~/Library/Logs/bluebubbles-server/main.log`:
```
grep -E "Dispatching event to webhook" main.log | tail -20
```
Zmierz przerwę między wysłaniem tekstu w stylu `"Dump"` a następującym po nim wysłaniem `"https://..."; Attachments:`. Zwiększ `messages.inbound.byChannel.bluebubbles`, aby komfortowo obejmowało tę przerwę.
Zmierz odstęp między wysłaniem tekstu w stylu `"Dump"` a następującym po nim wysłaniem `"https://..."; Attachments:`. Podnieś `messages.inbound.byChannel.bluebubbles`, aby z zapasem obejmował ten odstęp.
</Accordion>
<Accordion title="Znaczniki czasu JSONL sesji ≠ przybycie Webhook">
Znaczniki czasu zdarzeń sesji (`~/.openclaw/agents/<id>/sessions/*.jsonl`) odzwierciedlają moment, w którym Gateway przekazuje wiadomość agentowi, **a nie** moment przybycia webhooka. Druga wiadomość w kolejce oznaczona `[Queued messages while agent was busy]` znaczy, że pierwsza tura nadal trwała, gdy dotarł drugi Webhook — kubełek scalania został już opróżniony. Dostrajaj okno względem dziennika serwera BB, a nie dziennika sesji.
<Accordion title="Znaczniki czasu JSONL sesji ≠ nadejście Webhooka">
Znaczniki czasu zdarzeń sesji (`~/.openclaw/agents/<id>/sessions/*.jsonl`) odzwierciedlają moment, w którym Gateway przekazuje wiadomość agentowi, **a nie** moment nadejścia Webhooka. Druga wiadomość w kolejce oznaczona `[Queued messages while agent was busy]` znaczy, że pierwsza tura nadal działała, gdy nadszedł drugi Webhook — kubełek scalania został już opróżniony. Dostrajaj okno względem dziennika serwera BB, a nie dziennika sesji.
</Accordion>
<Accordion title="Presja pamięci spowalniająca wysyłkę odpowiedzi">
Na mniejszych maszynach (8 GB) tury agenta mogą trwać na tyle długo, że kubełek scalania opróżnia się przed ukończeniem odpowiedzi, a URL trafia jako druga tura w kolejce. Sprawdź `memory_pressure` i `ps -o rss -p $(pgrep openclaw-gateway)`; jeśli Gateway ma ponad ~500 MB RSS, a kompresor jest aktywny, zamknij inne ciężkie procesy albo przenieś się na większy host.
<Accordion title="Presja pamięci spowalnia wysyłanie odpowiedzi">
Na mniejszych maszynach (8 GB) tury agenta mogą trwać na tyle długo, że kubełek scalania zostanie opróżniony przed zakończeniem odpowiedzi, a URL trafi jako druga tura w kolejce. Sprawdź `memory_pressure` i `ps -o rss -p $(pgrep openclaw-gateway)`; jeśli Gateway przekracza około 500 MB RSS, a kompresor jest aktywny, zamknij inne ciężkie procesy albo przejdź na większy host.
</Accordion>
<Accordion title="Wysyłki cytujące odpowiedź to inna ścieżka">
Jeśli użytkownik stuknął `Dump` jako **odpowiedź** na istniejący dymek URL (iMessage pokazuje plakietkę „1 Reply” na dymku Dump), URL znajduje się w `replyToBody`, a nie w drugim Webhook. Scalanie nie ma zastosowania — to kwestia skill/prompt, nie debouncera.
<Accordion title="Wysyłki z cytowaną odpowiedzią to inna ścieżka">
Jeśli użytkownik stuknął `Dump` jako **odpowiedź** na istniejący dymek URL (iMessage pokazuje znaczek „1 odpowiedź” na dymku Dump), URL znajduje się w `replyToBody`, a nie w drugim Webhooku. Scalanie nie ma tu zastosowania — to kwestia Skills/promptu, a nie debouncera.
</Accordion>
</AccordionGroup>
@ -549,49 +549,50 @@ Kontroluj, czy odpowiedzi są wysyłane jako pojedyncza wiadomość, czy strumie
## Multimedia + limity
- Załączniki przychodzące są pobierane i przechowywane w pamięci podręcznej multimediów.
- Przychodzące załączniki są pobierane i przechowywane w pamięci podręcznej multimediów.
- Limit multimediów przez `channels.bluebubbles.mediaMaxMb` dla multimediów przychodzących i wychodzących (domyślnie: 8 MB).
- Tekst wychodzący jest dzielony na fragmenty do `channels.bluebubbles.textChunkLimit` (domyślnie: 4000 znaków).
## Odniesienie konfiguracji
## Dokumentacja konfiguracji
Pełna konfiguracja: [Konfiguracja](/pl/gateway/configuration)
<AccordionGroup>
<Accordion title="Połączenie i Webhook">
- `channels.bluebubbles.enabled`: Włącz/wyłącz kanał.
- `channels.bluebubbles.serverUrl`: Bazowy URL REST API BlueBubbles.
- `channels.bluebubbles.serverUrl`: Bazowy URL API REST BlueBubbles.
- `channels.bluebubbles.password`: Hasło API.
- `channels.bluebubbles.webhookPath`: Ścieżka punktu końcowego Webhook (domyślnie: `/bluebubbles-webhook`).
- `channels.bluebubbles.webhookPath`: Ścieżka punktu końcowego Webhooka (domyślnie: `/bluebubbles-webhook`).
</Accordion>
<Accordion title="Polityka dostępu">
<Accordion title="Zasady dostępu">
- `channels.bluebubbles.dmPolicy`: `pairing | allowlist | open | disabled` (domyślnie: `pairing`).
- `channels.bluebubbles.allowFrom`: Lista dozwolonych DM (uchwyty, adresy e-mail, numery E.164, `chat_id:*`, `chat_guid:*`).
- `channels.bluebubbles.groupPolicy`: `open | allowlist | disabled` (domyślnie: `allowlist`).
- `channels.bluebubbles.groupAllowFrom`: Lista dozwolonych nadawców grupowych.
- `channels.bluebubbles.enrichGroupParticipantsFromContacts`: W macOS opcjonalnie wzbogacaj nienazwanych uczestników grup z lokalnych Kontaktów po przejściu bramkowania. Domyślnie: `false`.
- `channels.bluebubbles.enrichGroupParticipantsFromContacts`: Na macOS opcjonalnie wzbogacaj nienazwanych uczestników grup z lokalnych Kontaktów po przejściu bramek. Domyślnie: `false`.
- `channels.bluebubbles.groups`: Konfiguracja per grupa (`requireMention` itd.).
</Accordion>
<Accordion title="Dostarczanie i dzielenie na fragmenty">
- `channels.bluebubbles.sendReadReceipts`: Wysyłaj potwierdzenia odczytu (domyślnie: `true`).
- `channels.bluebubbles.blockStreaming`: Włącz streaming blokowy (domyślnie: `false`; wymagane dla odpowiedzi strumieniowych).
- `channels.bluebubbles.textChunkLimit`: Rozmiar wychodzącego fragmentu w znakach (domyślnie: 4000).
- `channels.bluebubbles.sendTimeoutMs`: Limit czasu na żądanie w ms dla wysyłek tekstu wychodzącego przez `/api/v1/message/text` (domyślnie: 30000). Zwiększ w konfiguracjach macOS 26, gdzie wysyłki iMessage przez Private API mogą zawiesić się na ponad 60 sekund wewnątrz frameworka iMessage; na przykład `45000` lub `60000`. Sondy, wyszukiwania czatów, reakcje, edycje i kontrole kondycji obecnie zachowują krótszą domyślną wartość 10 s; rozszerzenie zakresu na reakcje i edycje jest planowane jako kolejny krok. Nadpisanie dla konta: `channels.bluebubbles.accounts.<accountId>.sendTimeoutMs`.
- `channels.bluebubbles.chunkMode`: `length` (domyślnie) dzieli tylko po przekroczeniu `textChunkLimit`; `newline` dzieli na pustych wierszach (granicach akapitów) przed dzieleniem według długości.
- `channels.bluebubbles.blockStreaming`: Włącz strumieniowanie blokowe (domyślnie: `false`; wymagane dla odpowiedzi strumieniowych).
- `channels.bluebubbles.textChunkLimit`: Rozmiar fragmentu wychodzącego w znakach (domyślnie: 4000).
- `channels.bluebubbles.sendTimeoutMs`: Limit czasu na żądanie w ms dla wysyłek tekstu wychodzącego przez `/api/v1/message/text` (domyślnie: 30000). Zwiększ w konfiguracjach macOS 26, w których wysyłki Private API iMessage mogą zatrzymywać się na ponad 60 sekund wewnątrz frameworka iMessage; na przykład `45000` albo `60000`. Sondy, wyszukiwania czatów, reakcje, edycje i kontrole kondycji obecnie zachowują krótszą wartość domyślną 10 s; rozszerzenie zakresu na reakcje i edycje jest planowane jako kolejny krok. Nadpisanie dla konta: `channels.bluebubbles.accounts.<accountId>.sendTimeoutMs`.
- `channels.bluebubbles.chunkMode`: `length` (domyślnie) dzieli tylko po przekroczeniu `textChunkLimit`; `newline` dzieli po pustych wierszach (granicach akapitów) przed dzieleniem według długości.
</Accordion>
<Accordion title="Media i historia">
- `channels.bluebubbles.mediaMaxMb`: Limit mediów przychodzących/wychodzących w MB (domyślnie: 8).
- `channels.bluebubbles.mediaLocalRoots`: Jawna lista dozwolonych bezwzględnych katalogów lokalnych dopuszczonych dla wychodzących lokalnych ścieżek mediów. Wysyłki ścieżek lokalnych są domyślnie odrzucane, chyba że ta opcja jest skonfigurowana. Nadpisanie dla konta: `channels.bluebubbles.accounts.<accountId>.mediaLocalRoots`.
- `channels.bluebubbles.coalesceSameSenderDms`: Scalaj kolejne webhooki DM od tego samego nadawcy w jedną turę agenta, aby dzielona wysyłka tekst+URL Apple dotarła jako jedna wiadomość (domyślnie: `false`). Zobacz [Scalanie DM-ów dzielonych przy wysyłce](#coalescing-split-send-dms-command--url-in-one-composition), aby poznać scenariusze, dostrajanie okna i kompromisy. Po włączeniu bez jawnego `messages.inbound.byChannel.bluebubbles` rozszerza domyślne okno debounce dla ruchu przychodzącego z 500 ms do 2500 ms.
- `channels.bluebubbles.coalesceSameSenderDms`: Scal kolejne Webhooki DM od tego samego nadawcy w jedną turę agenta, aby podzielona wysyłka tekst+URL Apple dotarła jako jedna wiadomość (domyślnie: `false`). Zobacz [Scalanie podzielonych wysyłek DM](#coalescing-split-send-dms-command--url-in-one-composition), aby poznać scenariusze, strojenie okna i kompromisy. Po włączeniu bez jawnego `messages.inbound.byChannel.bluebubbles` rozszerza domyślne okno opóźnienia przychodzącego z 500 ms do 2500 ms.
- `channels.bluebubbles.historyLimit`: Maksymalna liczba wiadomości grupowych dla kontekstu (0 wyłącza).
- `channels.bluebubbles.dmHistoryLimit`: Limit historii DM.
- `channels.bluebubbles.replyContextApiFallback`: Gdy odpowiedź przychodząca dociera bez `replyToBody`/`replyToSender`, a pamięciowa pamięć podręczna kontekstu odpowiedzi nie trafia, pobierz oryginalną wiadomość z BlueBubbles HTTP API jako awaryjne rozwiązanie typu best effort (domyślnie: `false`). Przydatne dla wdrożeń z wieloma instancjami współdzielącymi jedno konto BlueBubbles, po restartach procesu albo po eksmisji z długotrwałej pamięci podręcznej TTL/LRU. Pobieranie jest chronione przed SSRF tą samą polityką co każde inne żądanie klienta BlueBubbles, nigdy nie zgłasza wyjątku i wypełnia pamięć podręczną, aby kolejne odpowiedzi amortyzowały koszt. Nadpisanie dla konta: `channels.bluebubbles.accounts.<accountId>.replyContextApiFallback`. Ustawienie na poziomie kanału propaguje się do kont, które pomijają tę flagę.
</Accordion>
<Accordion title="Akcje i konta">
- `channels.bluebubbles.actions`: Włącz/wyłącz określone akcje.
- `channels.bluebubbles.actions`: Włącz/wyłącz konkretne akcje.
- `channels.bluebubbles.accounts`: Konfiguracja wielu kont.
</Accordion>
@ -612,34 +613,34 @@ Preferuj `chat_guid` dla stabilnego routingu:
- Bezpośrednie uchwyty: `+15555550123`, `user@example.com`
- Jeśli bezpośredni uchwyt nie ma istniejącego czatu DM, OpenClaw utworzy go przez `POST /api/v1/chat/new`. Wymaga to włączenia BlueBubbles Private API.
### Routing iMessage kontra SMS
### Routing iMessage a SMS
Gdy ten sam uchwyt ma na Macu zarówno czat iMessage, jak i SMS (na przykład numer telefonu zarejestrowany w iMessage, który otrzymywał także awaryjne wiadomości w zielonych dymkach), OpenClaw preferuje czat iMessage i nigdy po cichu nie przełącza się na SMS. Aby wymusić czat SMS, użyj jawnego prefiksu celu `sms:` (na przykład `sms:+15555550123`). Uchwyty bez pasującego czatu iMessage nadal wysyłają przez dowolny czat zgłaszany przez BlueBubbles.
Gdy ten sam uchwyt ma na Macu zarówno czat iMessage, jak i SMS (na przykład numer telefonu zarejestrowany w iMessage, który otrzymał też awaryjne wiadomości zielonego dymku), OpenClaw preferuje czat iMessage i nigdy po cichu nie obniża routingu do SMS. Aby wymusić czat SMS, użyj jawnego prefiksu celu `sms:` (na przykład `sms:+15555550123`). Uchwyty bez pasującego czatu iMessage nadal wysyłają przez dowolny czat zgłoszony przez BlueBubbles.
## Bezpieczeństwo
- Żądania Webhook są uwierzytelniane przez porównanie parametrów zapytania lub nagłówków `guid`/`password` z `channels.bluebubbles.password`.
- Utrzymuj hasło API i endpoint webhooka w tajemnicy (traktuj je jak dane uwierzytelniające).
- Nie ma obejścia uwierzytelniania webhooków BlueBubbles dla localhosta. Jeśli pośredniczysz w ruchu webhooków przez proxy, zachowaj hasło BlueBubbles w żądaniu od początku do końca. `gateway.trustedProxies` nie zastępuje tutaj `channels.bluebubbles.password`. Zobacz [Bezpieczeństwo Gateway](/pl/gateway/security#reverse-proxy-configuration).
- Utrzymuj hasło API i endpoint Webhook w tajemnicy (traktuj je jak dane uwierzytelniające).
- Nie ma obejścia localhost dla uwierzytelniania Webhook BlueBubbles. Jeśli proxyujesz ruch Webhook, zachowaj hasło BlueBubbles w żądaniu od początku do końca. `gateway.trustedProxies` nie zastępuje tutaj `channels.bluebubbles.password`. Zobacz [bezpieczeństwo Gateway](/pl/gateway/security#reverse-proxy-configuration).
- Włącz HTTPS i reguły zapory na serwerze BlueBubbles, jeśli wystawiasz go poza swoją sieć LAN.
## Rozwiązywanie problemów
- Jeśli zdarzenia pisania/odczytu przestaną działać, sprawdź logi webhooków BlueBubbles i zweryfikuj, czy ścieżka gateway odpowiada `channels.bluebubbles.webhookPath`.
- Kody parowania wygasają po jednej godzinie; użyj `openclaw pairing list bluebubbles` i `openclaw pairing approve bluebubbles <code>`.
- Jeśli zdarzenia pisania/odczytu przestają działać, sprawdź logi Webhook BlueBubbles i zweryfikuj, czy ścieżka Gateway odpowiada `channels.bluebubbles.webhookPath`.
- Kody parowania wygasają po godzinie; użyj `openclaw pairing list bluebubbles` i `openclaw pairing approve bluebubbles <code>`.
- Reakcje wymagają prywatnego API BlueBubbles (`POST /api/v1/message/react`); upewnij się, że wersja serwera je udostępnia.
- Edycja/cofanie wysłania wymagają macOS 13+ i zgodnej wersji serwera BlueBubbles. W macOS 26 (Tahoe) edycja jest obecnie zepsuta z powodu zmian w prywatnym API.
- Aktualizacje ikony grupy mogą być niestabilne w macOS 26 (Tahoe): API może zwrócić sukces, ale nowa ikona się nie zsynchronizuje.
- OpenClaw automatycznie ukrywa znane jako zepsute akcje na podstawie wersji macOS serwera BlueBubbles. Jeśli edycja nadal pojawia się w macOS 26 (Tahoe), wyłącz ją ręcznie za pomocą `channels.bluebubbles.actions.edit=false`.
- `coalesceSameSenderDms` jest włączone, ale dzielone wysyłki (np. `Dump` + URL) nadal docierają jako dwie tury: zobacz listę kontrolną [rozwiązywania problemów ze scalaniem dzielonych wysyłek](#split-send-coalescing-troubleshooting) — częste przyczyny to zbyt ciasne okno debounce, znaczniki czasu logu sesji błędnie odczytane jako przybycie webhooka albo wysyłka cytatu odpowiedzi (która używa `replyToBody`, a nie drugiego webhooka).
- Edycja/cofnięcie wysłania wymagają macOS 13+ i zgodnej wersji serwera BlueBubbles. Na macOS 26 (Tahoe) edycja jest obecnie zepsuta z powodu zmian w prywatnym API.
- Aktualizacje ikon grup mogą być niestabilne na macOS 26 (Tahoe): API może zwrócić sukces, ale nowa ikona się nie synchronizuje.
- OpenClaw automatycznie ukrywa znane zepsute akcje na podstawie wersji macOS serwera BlueBubbles. Jeśli edycja nadal pojawia się na macOS 26 (Tahoe), wyłącz ją ręcznie za pomocą `channels.bluebubbles.actions.edit=false`.
- `coalesceSameSenderDms` jest włączone, ale podzielone wysyłki (np. `Dump` + URL) nadal docierają jako dwie tury: zobacz listę kontrolną [rozwiązywania problemów ze scalaniem podzielonych wysyłek](#split-send-coalescing-troubleshooting) — częste przyczyny to zbyt krótkie okno opóźnienia, znaczniki czasu logu sesji błędnie odczytane jako przybycie Webhook albo wysyłka z cytatem odpowiedzi (która używa `replyToBody`, a nie drugiego Webhooka).
- Informacje o statusie/kondycji: `openclaw status --all` lub `openclaw status --deep`.
Ogólne informacje o przepływie pracy kanałów znajdziesz w [Kanałach](/pl/channels) i przewodniku [Plugins](/pl/tools/plugin).
Ogólny opis przepływu pracy kanałów znajdziesz w [Kanałach](/pl/channels) i przewodniku [Plugins](/pl/tools/plugin).
## Powiązane
- [Routing kanałów](/pl/channels/channel-routing) — routing sesji dla wiadomości
- [Przegląd kanałów](/pl/channels) — wszystkie obsługiwane kanały
- [Omówienie kanałów](/pl/channels) — wszystkie obsługiwane kanały
- [Grupy](/pl/channels/groups) — zachowanie czatu grupowego i bramkowanie wzmianek
- [Parowanie](/pl/channels/pairing) — uwierzytelnianie DM i przepływ parowania
- [Bezpieczeństwo](/pl/gateway/security) — model dostępu i wzmacnianie zabezpieczeń

192
docs/pl/channels/groups.md
View File

@ -1,42 +1,42 @@
---
read_when:
- Zmiana zachowania czatu grupowego lub kontroli wzmianek
- Zmiana zachowania czatu grupowego lub bramkowania wzmianek
sidebarTitle: Groups
summary: Zachowanie czatu grupowego w różnych interfejsach (Discord/iMessage/Matrix/Microsoft Teams/Signal/Slack/Telegram/WhatsApp/Zalo)
title: Grupy
x-i18n:
generated_at: "2026-04-30T16:27:33Z"
generated_at: "2026-05-01T09:56:04Z"
model: gpt-5.5
provider: openai
source_hash: ed9cba03cf4546a20d473e8095a54858530869b27f8934f2680e8dbe987dbf5e
source_hash: a8580f98ab03c89770688102da776627d8ce18b7bd34c4a687009fd4aabb6213
source_path: channels/groups.md
workflow: 16
---
OpenClaw traktuje czaty grupowe spójnie na wszystkich powierzchniach: Discord, iMessage, Matrix, Microsoft Teams, Signal, Slack, Telegram, WhatsApp, Zalo.
OpenClaw traktuje czaty grupowe spójnie we wszystkich powierzchniach: Discord, iMessage, Matrix, Microsoft Teams, Signal, Slack, Telegram, WhatsApp, Zalo.
## Wprowadzenie dla początkujących (2 minuty)
OpenClaw „działa” na Twoich własnych kontach komunikatorów. Nie ma osobnego użytkownika bota WhatsApp. Jeśli **Ty** jesteś w grupie, OpenClaw może widzieć tę grupę i odpowiadać w niej.
OpenClaw „żyje” na Twoich własnych kontach komunikatorów. Nie ma oddzielnego użytkownika bota WhatsApp. Jeśli **Ty** jesteś w grupie, OpenClaw może widzieć tę grupę i odpowiadać w niej.
Domyślne zachowanie:
- Grupy są ograniczone (`groupPolicy: "allowlist"`).
- Odpowiedzi wymagają wzmianki, chyba że jawnie wyłączysz wymóg wzmianki.
- Zwykłe końcowe odpowiedzi w grupach/kanałach są domyślnie prywatne. Widoczny wynik w pokoju używa narzędzia `message`.
- Odpowiedzi wymagają wzmianki, chyba że jawnie wyłączysz bramkowanie wzmianką.
- Zwykłe końcowe odpowiedzi w grupach/kanałach są domyślnie prywatne. Widoczne wyjście w pokoju używa narzędzia `message`.
W praktyce: nadawcy z listy dozwolonych mogą wywołać OpenClaw, wspominając o nim.
Innymi słowy: nadawcy z listy dozwolonych mogą wyzwolić OpenClaw, wspominając o nim.
<Note>
**TL;DR**
- **Dostęp DM** jest kontrolowany przez `*.allowFrom`.
- **Dostęp grupowy** jest kontrolowany przez `*.groupPolicy` + listy dozwolonych (`*.groups`, `*.groupAllowFrom`).
- **Wyzwalanie odpowiedzi** jest kontrolowane przez wymóg wzmianki (`requireMention`, `/activation`).
- **Wyzwalanie odpowiedzi** jest kontrolowane przez bramkowanie wzmianką (`requireMention`, `/activation`).
</Note>
Szybki przebieg (co dzieje się z wiadomością grupową):
Szybki przepływ (co dzieje się z wiadomością grupową):
```
groupPolicy? disabled -> drop
@ -47,16 +47,20 @@ otherwise -> reply
## Widoczne odpowiedzi
W przypadku pokojów grupowych/kanałowych OpenClaw domyślnie ustawia `messages.groupChat.visibleReplies: "message_tool"`.
Oznacza to, że agent nadal przetwarza turę i może aktualizować pamięć/stan sesji, ale jego zwykła końcowa odpowiedź nie jest automatycznie publikowana z powrotem w pokoju. Aby wypowiedzieć się widocznie, agent używa `message(action=send)`.
Dla pokojów grupowych/kanałów OpenClaw domyślnie ustawia `messages.groupChat.visibleReplies: "message_tool"`.
Oznacza to, że agent nadal przetwarza turę i może aktualizować stan pamięci/sesji, ale jego zwykła końcowa odpowiedź nie jest automatycznie publikowana z powrotem w pokoju. Aby wypowiedzieć się widocznie, agent używa `message(action=send)`.
W przypadku czatów bezpośrednich i każdej innej tury źródłowej użyj `messages.visibleReplies: "message_tool"`, aby zastosować globalnie takie samo zachowanie widocznych odpowiedzi wyłącznie przez narzędzie. `messages.groupChat.visibleReplies` pozostaje bardziej szczegółowym nadpisaniem dla pokojów grupowych/kanałowych.
Jeśli narzędzie wiadomości jest niedostępne w aktywnej polityce narzędzi, OpenClaw przełącza się
na automatyczne widoczne odpowiedzi zamiast po cichu tłumić odpowiedź.
`openclaw doctor` ostrzega o tej niezgodności.
Zastępuje to stary wzorzec wymuszania na modelu odpowiedzi `NO_REPLY` dla większości tur w trybie obserwowania. W trybie wyłącznie narzędziowym brak widocznego działania oznacza po prostu niewywołanie narzędzia wiadomości.
Dla czatów bezpośrednich i każdej innej tury źródłowej użyj `messages.visibleReplies: "message_tool"`, aby zastosować globalnie to samo zachowanie widocznej odpowiedzi wyłącznie przez narzędzie. `messages.groupChat.visibleReplies` pozostaje bardziej szczegółowym nadpisaniem dla pokojów grupowych/kanałów.
Wskaźniki pisania są nadal wysyłane, gdy agent działa w trybie wyłącznie narzędziowym. Domyślny grupowy tryb pisania jest dla tych tur podnoszony z „message” do „instant”, ponieważ może nigdy nie pojawić się zwykły tekst wiadomości asystenta, zanim agent zdecyduje, czy wywołać narzędzie wiadomości. Jawna konfiguracja trybu pisania nadal ma pierwszeństwo.
Zastępuje to stary wzorzec wymuszania na modelu odpowiedzi `NO_REPLY` dla większości tur w trybie nasłuchiwania. W trybie wyłącznie narzędziowym brak widocznego działania oznacza po prostu niewywołanie narzędzia wiadomości.
Aby przywrócić starsze automatyczne końcowe odpowiedzi dla pokojów grupowych/kanałowych:
Wskaźniki pisania nadal są wysyłane, gdy agent pracuje w trybie wyłącznie narzędziowym. Domyślny grupowy tryb pisania jest podnoszony z „message” do „instant” dla tych tur, ponieważ może nigdy nie pojawić się zwykły tekst wiadomości asystenta, zanim agent zdecyduje, czy wywołać narzędzie wiadomości. Jawna konfiguracja trybu pisania nadal ma pierwszeństwo.
Aby przywrócić starsze automatyczne końcowe odpowiedzi dla pokojów grupowych/kanałów:
```json5
{
@ -68,10 +72,10 @@ Aby przywrócić starsze automatyczne końcowe odpowiedzi dla pokojów grupowych
}
```
Gateway przeładowuje konfigurację `messages` na gorąco po zapisaniu pliku. Uruchom ponownie tylko wtedy,
gdy obserwowanie plików lub przeładowywanie konfiguracji jest wyłączone we wdrożeniu.
Gateway przeładowuje konfigurację `messages` na gorąco po zapisaniu pliku. Uruchom ponownie tylko
wtedy, gdy obserwowanie plików lub przeładowywanie konfiguracji jest wyłączone we wdrożeniu.
Aby wymagać, by widoczny wynik przechodził przez narzędzie wiadomości dla każdego czatu źródłowego:
Aby wymagać, aby widoczne wyjście przechodziło przez narzędzie wiadomości dla każdego czatu źródłowego:
```json5
{
@ -81,7 +85,7 @@ Aby wymagać, by widoczny wynik przechodził przez narzędzie wiadomości dla ka
}
```
Natywne polecenia ukośnikowe (Discord, Telegram i inne powierzchnie z natywną obsługą poleceń) omijają `visibleReplies: "message_tool"` i zawsze odpowiadają widocznie, aby natywny dla kanału interfejs poleceń otrzymał oczekiwaną odpowiedź. Dotyczy to tylko zweryfikowanych tur poleceń natywnych; polecenia `/...` wpisywane jako tekst i zwykłe tury czatu nadal stosują skonfigurowane domyślne ustawienie grupy.
Natywne polecenia ukośnikowe (Discord, Telegram i inne powierzchnie z natywną obsługą poleceń) omijają `visibleReplies: "message_tool"` i zawsze odpowiadają widocznie, aby natywny dla kanału interfejs poleceń otrzymał oczekiwaną odpowiedź. Dotyczy to tylko zweryfikowanych natywnych tur poleceń; wpisywane tekstowo polecenia `/...` i zwykłe tury czatu nadal przestrzegają skonfigurowanej domyślnej wartości grupowej.
## Widoczność kontekstu i listy dozwolonych
@ -90,20 +94,20 @@ W bezpieczeństwie grupowym biorą udział dwie różne kontrolki:
- **Autoryzacja wyzwalania**: kto może wyzwolić agenta (`groupPolicy`, `groups`, `groupAllowFrom`, listy dozwolonych specyficzne dla kanału).
- **Widoczność kontekstu**: jaki dodatkowy kontekst jest wstrzykiwany do modelu (tekst odpowiedzi, cytaty, historia wątku, przekazane metadane).
Domyślnie OpenClaw priorytetowo traktuje normalne zachowanie czatu i zachowuje kontekst głównie w takiej postaci, w jakiej został odebrany. Oznacza to, że listy dozwolonych przede wszystkim decydują, kto może wyzwalać działania, a nie stanowią uniwersalnej granicy redakcji dla każdego cytowanego lub historycznego fragmentu.
Domyślnie OpenClaw priorytetowo traktuje normalne zachowanie czatu i zachowuje kontekst głównie tak, jak został otrzymany. Oznacza to, że listy dozwolonych przede wszystkim decydują, kto może wyzwalać działania, a nie stanowią uniwersalnej granicy redakcji dla każdego cytowanego lub historycznego fragmentu.
<AccordionGroup>
<Accordion title="Obecne zachowanie jest specyficzne dla kanału">
- Niektóre kanały już stosują filtrowanie na podstawie nadawcy dla dodatkowego kontekstu w określonych ścieżkach (na przykład inicjowanie wątków Slack, wyszukiwania odpowiedzi/wątków Matrix).
- Inne kanały nadal przekazują kontekst cytatu/odpowiedzi/przekazania w takiej postaci, w jakiej został odebrany.
- Niektóre kanały już stosują filtrowanie oparte na nadawcy dla dodatkowego kontekstu w konkretnych ścieżkach (na przykład inicjowanie wątków Slack, wyszukiwania odpowiedzi/wątków Matrix).
- Inne kanały nadal przekazują kontekst cytatu/odpowiedzi/przekazania tak, jak został otrzymany.
</Accordion>
<Accordion title="Kierunek wzmacniania zabezpieczeń (planowany)">
- `contextVisibility: "all"` (domyślnie) zachowuje obecne działanie „jak odebrano”.
<Accordion title="Kierunek utwardzania (planowany)">
- `contextVisibility: "all"` (domyślnie) zachowuje obecne zachowanie „tak jak otrzymano”.
- `contextVisibility: "allowlist"` filtruje dodatkowy kontekst do nadawców z listy dozwolonych.
- `contextVisibility: "allowlist_quote"` to `allowlist` plus jeden jawny wyjątek dla cytatu/odpowiedzi.
Dopóki ten model wzmacniania zabezpieczeń nie zostanie wdrożony spójnie we wszystkich kanałach, należy spodziewać się różnic między powierzchniami.
Dopóki ten model utwardzania nie zostanie wdrożony spójnie we wszystkich kanałach, spodziewaj się różnic między powierzchniami.
</Accordion>
</AccordionGroup>
@ -115,14 +119,14 @@ Jeśli chcesz...
| Cel | Co ustawić |
| -------------------------------------------- | ---------------------------------------------------------- |
| Zezwolić na wszystkie grupy, ale odpowiadać tylko na @wzmianki | `groups: { "*": { requireMention: true } }` |
| Wyłączyć wszystkie odpowiedzi grupowe | `groupPolicy: "disabled"` |
| Tylko konkretne grupy | `groups: { "<group-id>": { ... } }` (bez klucza `"*"`) |
| Tylko Ty możesz wyzwalać w grupach | `groupPolicy: "allowlist"`, `groupAllowFrom: ["+1555..."]` |
| Wyłączyć wszystkie odpowiedzi grupowe | `groupPolicy: "disabled"` |
| Tylko konkretne grupy | `groups: { "<group-id>": { ... } }` (bez klucza `"*"`) |
| Tylko Ty możesz wyzwalać w grupach | `groupPolicy: "allowlist"`, `groupAllowFrom: ["+1555..."]` |
## Klucze sesji
- Sesje grupowe używają kluczy sesji `agent:<agentId>:<channel>:group:<id>` (pokoje/kanały używają `agent:<agentId>:<channel>:channel:<id>`).
- Tematy forów Telegram dodają `:topic:<threadId>` do identyfikatora grupy, aby każdy temat miał własną sesję.
- Tematy forum Telegram dodają `:topic:<threadId>` do identyfikatora grupy, więc każdy temat ma własną sesję.
- Czaty bezpośrednie używają głównej sesji (lub sesji per nadawca, jeśli skonfigurowano).
- Heartbeats są pomijane dla sesji grupowych.
@ -130,21 +134,21 @@ Jeśli chcesz...
## Wzorzec: osobiste DM + publiczne grupy (jeden agent)
Tak — działa to dobrze, jeśli Twój „osobisty” ruch to **DM-y**, a Twój „publiczny” ruch to **grupy**.
Tak — działa to dobrze, jeśli Twój „osobisty” ruch to **DM**, a Twój „publiczny” ruch to **grupy**.
Dlaczego: w trybie jednego agenta DM-y zwykle trafiają do **głównego** klucza sesji (`agent:main:main`), podczas gdy grupy zawsze używają **niegłównych** kluczy sesji (`agent:main:<channel>:group:<id>`). Jeśli włączysz sandboxing z `mode: "non-main"`, te sesje grupowe działają w skonfigurowanym backendzie sandboxa, podczas gdy Twoja główna sesja DM pozostaje na hoście. Docker jest domyślnym backendem, jeśli nie wybierzesz innego.
Dlaczego: w trybie jednego agenta DM zwykle trafiają do **głównego** klucza sesji (`agent:main:main`), podczas gdy grupy zawsze używają **niegłównych** kluczy sesji (`agent:main:<channel>:group:<id>`). Jeśli włączysz sandboxing z `mode: "non-main"`, te sesje grupowe działają w skonfigurowanym backendzie sandboxa, podczas gdy Twoja główna sesja DM pozostaje na hoście. Docker jest domyślnym backendem, jeśli nie wybierzesz innego.
Daje to jeden „mózg” agenta (wspólna przestrzeń robocza + pamięć), ale dwie postawy wykonawcze:
Daje to jeden „mózg” agenta (wspólny obszar roboczy + pamięć), ale dwie postawy wykonawcze:
- **DM-y**: pełne narzędzia (host)
- **DM**: pełne narzędzia (host)
- **Grupy**: sandbox + ograniczone narzędzia
<Note>
Jeśli potrzebujesz naprawdę oddzielnych przestrzeni roboczych/person („osobiste” i „publiczne” nigdy nie mogą się mieszać), użyj drugiego agenta + powiązań. Zobacz [Routing wielu agentów](/pl/concepts/multi-agent).
Jeśli potrzebujesz naprawdę oddzielnych obszarów roboczych/person („osobiste” i „publiczne” nigdy nie mogą się mieszać), użyj drugiego agenta + powiązań. Zobacz [Routing wieloagentowy](/pl/concepts/multi-agent).
</Note>
<Tabs>
<Tab title="DM-y na hoście, grupy w sandboxie">
<Tab title="DM na hoście, grupy w sandboxie">
```json5
{
agents: {
@ -169,7 +173,7 @@ Jeśli potrzebujesz naprawdę oddzielnych przestrzeni roboczych/person („osobi
```
</Tab>
<Tab title="Grupy widzą tylko folder z listy dozwolonych">
Chcesz, aby „grupy widziały tylko folder X” zamiast „brak dostępu do hosta”? Zachowaj `workspaceAccess: "none"` i zamontuj w sandboxie tylko ścieżki z listy dozwolonych:
Chcesz, aby „grupy widziały tylko folder X” zamiast „braku dostępu do hosta”? Zachowaj `workspaceAccess: "none"` i zamontuj w sandboxie tylko ścieżki z listy dozwolonych:
```json5
{
@ -197,17 +201,17 @@ Jeśli potrzebujesz naprawdę oddzielnych przestrzeni roboczych/person („osobi
Powiązane:
- Klucze konfiguracji i wartości domyślne: [Konfiguracja Gateway](/pl/gateway/config-agents#agentsdefaultssandbox)
- Debugowanie, dlaczego narzędzie jest blokowane: [Sandbox a polityka narzędzi a podwyższone uprawnienia](/pl/gateway/sandbox-vs-tool-policy-vs-elevated)
- Debugowanie, dlaczego narzędzie jest zablokowane: [Sandbox kontra polityka narzędzi kontra podwyższone uprawnienia](/pl/gateway/sandbox-vs-tool-policy-vs-elevated)
- Szczegóły montowań bind: [Sandboxing](/pl/gateway/sandboxing#custom-bind-mounts)
## Etykiety wyświetlania
- Etykiety UI używają `displayName`, gdy jest dostępne, sformatowane jako `<channel>:<token>`.
- Etykiety UI używają `displayName`, gdy jest dostępne, sformatowanego jako `<channel>:<token>`.
- `#room` jest zarezerwowane dla pokojów/kanałów; czaty grupowe używają `g-<slug>` (małe litery, spacje -> `-`, zachowaj `#@+._-`).
## Polityka grup
## Polityka grupowa
Kontroluj, jak wiadomości grupowe/pokojowe są obsługiwane dla każdego kanału:
Kontroluj, jak wiadomości grupowe/pokojowe są obsługiwane per kanał:
```json5
{
@ -254,30 +258,30 @@ Kontroluj, jak wiadomości grupowe/pokojowe są obsługiwane dla każdego kanał
}
```
| Polityka | Zachowanie |
| Polityka | Zachowanie |
| ------------- | ------------------------------------------------------------ |
| `"open"` | Grupy omijają listy dozwolonych; wymóg wzmianki nadal obowiązuje. |
| `"disabled"` | Całkowicie blokuje wszystkie wiadomości grupowe. |
| `"open"` | Grupy omijają listy dozwolonych; bramkowanie wzmianką nadal ma zastosowanie. |
| `"disabled"` | Całkowicie blokuje wszystkie wiadomości grupowe. |
| `"allowlist"` | Zezwala tylko na grupy/pokoje pasujące do skonfigurowanej listy dozwolonych. |
<AccordionGroup>
<Accordion title="Uwagi dla poszczególnych kanałów">
- `groupPolicy` jest oddzielone od wymogu wzmianki (który wymaga @wzmianek).
<Accordion title="Uwagi per kanał">
- `groupPolicy` jest oddzielne od bramkowania wzmianką (które wymaga @wzmianek).
- WhatsApp/Telegram/Signal/iMessage/Microsoft Teams/Zalo: użyj `groupAllowFrom` (fallback: jawne `allowFrom`).
- Signal: `groupAllowFrom` może pasować albo do przychodzącego identyfikatora grupy Signal, albo do telefonu/UUID nadawcy.
- Zatwierdzenia parowania DM (wpisy magazynu `*-allowFrom`) dotyczą tylko dostępu DM; autoryzacja nadawcy grupowego pozostaje jawnie przypisana do list dozwolonych grup.
- Zatwierdzenia parowania DM (wpisy magazynu `*-allowFrom`) mają zastosowanie tylko do dostępu DM; autoryzacja nadawcy w grupie pozostaje jawna dla list dozwolonych grup.
- Discord: lista dozwolonych używa `channels.discord.guilds.<id>.channels`.
- Slack: lista dozwolonych używa `channels.slack.channels`.
- Matrix: lista dozwolonych używa `channels.matrix.groups`. Preferuj identyfikatory pokojów lub aliasy; wyszukiwanie nazw dołączonych pokojów działa na zasadzie best-effort, a nierozwiązane nazwy są ignorowane w czasie wykonywania. Użyj `channels.matrix.groupAllowFrom`, aby ograniczyć nadawców; obsługiwane są także listy dozwolonych `users` na poziomie pokoju.
- Grupowe DM-y są kontrolowane oddzielnie (`channels.discord.dm.*`, `channels.slack.dm.*`).
- Matrix: lista dozwolonych używa `channels.matrix.groups`. Preferuj identyfikatory pokojów lub aliasy; wyszukiwanie nazwy dołączonego pokoju jest best-effort, a nierozwiązane nazwy są ignorowane w czasie działania. Użyj `channels.matrix.groupAllowFrom`, aby ograniczyć nadawców; obsługiwane są także listy dozwolonych `users` per pokój.
- Grupowe DM są kontrolowane oddzielnie (`channels.discord.dm.*`, `channels.slack.dm.*`).
- Lista dozwolonych Telegram może pasować do identyfikatorów użytkowników (`"123456789"`, `"telegram:123456789"`, `"tg:123456789"`) lub nazw użytkowników (`"@alice"` albo `"alice"`); prefiksy nie rozróżniają wielkości liter.
- Domyślna wartość to `groupPolicy: "allowlist"`; jeśli lista dozwolonych grup jest pusta, wiadomości grupowe są blokowane.
- Bezpieczeństwo w czasie wykonywania: gdy blok dostawcy całkowicie nie istnieje (brak `channels.<provider>`), polityka grup przechodzi w tryb fail-closed (zwykle `allowlist`) zamiast dziedziczyć `channels.defaults.groupPolicy`.
- Domyślnie ustawione jest `groupPolicy: "allowlist"`; jeśli Twoja lista dozwolonych grup jest pusta, wiadomości grupowe są blokowane.
- Bezpieczeństwo w czasie działania: gdy blok dostawcy całkowicie nie istnieje (brak `channels.<provider>`), polityka grupowa przechodzi w tryb zamknięty w razie błędu (zwykle `allowlist`) zamiast dziedziczyć `channels.defaults.groupPolicy`.
</Accordion>
</AccordionGroup>
Szybki model mentalny (kolejność oceny wiadomości grupowych):
Szybki model mentalny (kolejność oceny dla wiadomości grupowych):
<Steps>
<Step title="groupPolicy">
@ -286,16 +290,16 @@ Szybki model mentalny (kolejność oceny wiadomości grupowych):
<Step title="Listy dozwolonych grup">
Listy dozwolonych grup (`*.groups`, `*.groupAllowFrom`, lista dozwolonych specyficzna dla kanału).
</Step>
<Step title="Wymóg wzmianki">
Wymóg wzmianki (`requireMention`, `/activation`).
<Step title="Bramkowanie na podstawie wzmianki">
Bramkowanie na podstawie wzmianki (`requireMention`, `/activation`).
</Step>
</Steps>
## Wymóg wzmianki (domyślnie)
## Bramkowanie na podstawie wzmianki (domyślnie)
Wiadomości grupowe wymagają wzmianki, chyba że nadpisano to dla danej grupy. Wartości domyślne znajdują się dla każdego podsystemu w `*.groups."*"`.
Wiadomości grupowe wymagają wzmianki, chyba że zostanie to nadpisane dla danej grupy. Wartości domyślne znajdują się dla każdego podsystemu w `*.groups."*"`.
Odpowiedź na wiadomość bota liczy się jako niejawna wzmianka, gdy kanał obsługuje metadane odpowiedzi. Cytowanie wiadomości bota może również liczyć się jako niejawna wzmianka w kanałach, które udostępniają metadane cytatu. Obecne wbudowane przypadki obejmują Telegram, WhatsApp, Slack, Discord, Microsoft Teams i ZaloUser.
Odpowiedź na wiadomość bota liczy się jako niejawna wzmianka, gdy kanał obsługuje metadane odpowiedzi. Cytowanie wiadomości bota może również liczyć się jako niejawna wzmianka w kanałach, które udostępniają metadane cytowania. Obecne wbudowane przypadki obejmują Telegram, WhatsApp, Slack, Discord, Microsoft Teams i ZaloUser.
```json5
{
@ -334,40 +338,40 @@ Odpowiedź na wiadomość bota liczy się jako niejawna wzmianka, gdy kanał obs
```
<AccordionGroup>
<Accordion title="Uwagi dotyczące bramkowania wzmianek">
- `mentionPatterns` to bezpieczne wzorce wyrażeń regularnych niewrażliwe na wielkość liter; nieprawidłowe wzorce i niebezpieczne formy zagnieżdżonych powtórzeń są ignorowane.
- Powierzchnie udostępniające jawne wzmianki nadal przechodzą; wzorce są mechanizmem zapasowym.
<Accordion title="Uwagi dotyczące bramkowania na podstawie wzmianki">
- `mentionPatterns` to bezpieczne wzorce wyrażeń regularnych bez rozróżniania wielkości liter; nieprawidłowe wzorce i niebezpieczne formy z zagnieżdżonymi powtórzeniami są ignorowane.
- Powierzchnie, które udostępniają jawne wzmianki, nadal przechodzą; wzorce są mechanizmem zapasowym.
- Nadpisanie dla agenta: `agents.list[].groupChat.mentionPatterns` (przydatne, gdy wielu agentów współdzieli grupę).
- Bramkowanie wzmianek jest wymuszane tylko wtedy, gdy wykrywanie wzmianek jest możliwe (skonfigurowano natywne wzmianki lub `mentionPatterns`).
- Dodanie grupy lub nadawcy do listy dozwolonych nie wyłącza bramkowania wzmianek; ustaw dla tej grupy `requireMention` na `false`, gdy wszystkie wiadomości powinny wyzwalać działanie.
- Kontekst promptu czatu grupowego przenosi rozstrzygniętą instrukcję cichej odpowiedzi w każdej turze; pliki obszaru roboczego nie powinny duplikować mechaniki `NO_REPLY`.
- Grupy, w których ciche odpowiedzi są dozwolone, traktują czyste puste tury modelu lub tury zawierające tylko rozumowanie jako ciche, równoważne `NO_REPLY`. Czaty bezpośrednie robią to samo tylko wtedy, gdy bezpośrednie ciche odpowiedzi są jawnie dozwolone; w przeciwnym razie puste odpowiedzi pozostają nieudanymi turami agenta.
- Domyślne ustawienia Discord znajdują się w `channels.discord.guilds."*"` (można je nadpisać dla gildii/kanału).
- Kontekst historii grupy jest opakowywany jednolicie we wszystkich kanałach i jest **tylko oczekujący** (wiadomości pominięte z powodu bramkowania wzmianek); użyj `messages.groupChat.historyLimit` jako globalnej wartości domyślnej oraz `channels.<channel>.historyLimit` (lub `channels.<channel>.accounts.*.historyLimit`) dla nadpisań. Ustaw `0`, aby wyłączyć.
- Bramkowanie na podstawie wzmianki jest wymuszane tylko wtedy, gdy wykrywanie wzmianki jest możliwe (skonfigurowano natywne wzmianki lub `mentionPatterns`).
- Dodanie grupy lub nadawcy do listy dozwolonych nie wyłącza bramkowania na podstawie wzmianki; ustaw `requireMention` tej grupy na `false`, gdy wszystkie wiadomości mają wyzwalać odpowiedź.
- Kontekst promptu czatu grupowego przenosi rozwiązaną instrukcję cichej odpowiedzi w każdej turze; pliki przestrzeni roboczej nie powinny powielać mechaniki `NO_REPLY`.
- Grupy, w których ciche odpowiedzi są dozwolone, traktują czyste puste tury modelu lub tury zawierające tylko rozumowanie jako ciche, równoważne z `NO_REPLY`. Czaty bezpośrednie robią to samo tylko wtedy, gdy bezpośrednie ciche odpowiedzi są jawnie dozwolone; w przeciwnym razie puste odpowiedzi pozostają nieudanymi turami agenta.
- Wartości domyślne Discord znajdują się w `channels.discord.guilds."*"` (możliwe do nadpisania dla gildii/kanału).
- Kontekst historii grup jest opakowywany jednolicie we wszystkich kanałach i jest **tylko oczekujący** (wiadomości pominięte z powodu bramkowania na podstawie wzmianki); użyj `messages.groupChat.historyLimit` jako globalnej wartości domyślnej oraz `channels.<channel>.historyLimit` (lub `channels.<channel>.accounts.*.historyLimit`) dla nadpisań. Ustaw `0`, aby wyłączyć.
</Accordion>
</AccordionGroup>
## Ograniczenia narzędzi dla grup/kanałów (opcjonalne)
## Ograniczenia narzędzi dla grupy/kanału (opcjonalne)
Niektóre konfiguracje kanałów obsługują ograniczanie narzędzi dostępnych **wewnątrz konkretnej grupy/pokoju/kanału**.
Niektóre konfiguracje kanałów obsługują ograniczanie tego, które narzędzia są dostępne **w konkretnej grupie/pokoju/kanale**.
- `tools`: zezwalaj/odmawiaj narzędzi dla całej grupy.
- `toolsBySender`: nadpisania według nadawcy w grupie. Używaj jawnych prefiksów kluczy: `id:<senderId>`, `e164:<phone>`, `username:<handle>`, `name:<displayName>` oraz symbolu wieloznacznego `"*"`. Starsze klucze bez prefiksu są nadal akceptowane i dopasowywane tylko jako `id:`.
- `tools`: zezwalaj na narzędzia lub odmawiaj ich dla całej grupy.
- `toolsBySender`: nadpisania dla nadawcy w obrębie grupy. Używaj jawnych prefiksów kluczy: `id:<senderId>`, `e164:<phone>`, `username:<handle>`, `name:<displayName>` oraz symbolu wieloznacznego `"*"`. Starsze klucze bez prefiksu są nadal akceptowane i dopasowywane wyłącznie jako `id:`.
Kolejność rozstrzygania (wygrywa najbardziej szczegółowe):
Kolejność rozstrzygania (najbardziej szczegółowe wygrywa):
<Steps>
<Step title="Group toolsBySender">
<Step title="Grupowe toolsBySender">
Dopasowanie `toolsBySender` grupy/kanału.
</Step>
<Step title="Group tools">
<Step title="Grupowe tools">
`tools` grupy/kanału.
</Step>
<Step title="Default toolsBySender">
<Step title="Domyślne toolsBySender">
Domyślne (`"*"`) dopasowanie `toolsBySender`.
</Step>
<Step title="Default tools">
<Step title="Domyślne tools">
Domyślne (`"*"`) `tools`.
</Step>
</Steps>
@ -393,15 +397,15 @@ Przykład (Telegram):
```
<Note>
Ograniczenia narzędzi dla grup/kanałów są stosowane oprócz globalnej polityki narzędzi/agenta (odmowa nadal wygrywa). Niektóre kanały używają innego zagnieżdżenia dla pokojów/kanałów (np. Discord `guilds.*.channels.*`, Slack `channels.*`, Microsoft Teams `teams.*.channels.*`).
Ograniczenia narzędzi dla grupy/kanału są stosowane dodatkowo względem globalnych zasad narzędzi lub zasad narzędzi agenta (odmowa nadal wygrywa). Niektóre kanały używają innego zagnieżdżenia dla pokojów/kanałów (np. Discord `guilds.*.channels.*`, Slack `channels.*`, Microsoft Teams `teams.*.channels.*`).
</Note>
## Listy dozwolonych grup
Gdy skonfigurowano `channels.whatsapp.groups`, `channels.telegram.groups` lub `channels.imessage.groups`, klucze działają jako lista dozwolonych grup. Użyj `"*"`, aby zezwolić na wszystkie grupy, nadal ustawiając domyślne zachowanie dotyczące wzmianek.
Gdy skonfigurowano `channels.whatsapp.groups`, `channels.telegram.groups` lub `channels.imessage.groups`, klucze działają jako lista dozwolonych grup. Użyj `"*"`, aby zezwolić na wszystkie grupy i jednocześnie nadal ustawić domyślne zachowanie dotyczące wzmianki.
<Warning>
Częste nieporozumienie: zatwierdzenie parowania DM nie jest tym samym co autoryzacja grupy. W kanałach obsługujących parowanie DM magazyn parowania odblokowuje tylko DM. Polecenia grupowe nadal wymagają jawnej autoryzacji nadawcy grupowego z list dozwolonych konfiguracji, takich jak `groupAllowFrom`, albo udokumentowanego zapasowego mechanizmu konfiguracji dla tego kanału.
Częste nieporozumienie: zatwierdzenie parowania DM nie jest tym samym co autoryzacja grupy. W kanałach obsługujących parowanie DM magazyn parowania odblokowuje tylko DM. Polecenia grupowe nadal wymagają jawnej autoryzacji nadawcy grupowego z list dozwolonych w konfiguracji, takich jak `groupAllowFrom`, lub udokumentowanego zapasowego mechanizmu konfiguracji dla danego kanału.
</Warning>
Typowe intencje (kopiuj/wklej):
@ -414,7 +418,7 @@ Typowe intencje (kopiuj/wklej):
}
```
</Tab>
<Tab title="Zezwalaj tylko na konkretne grupy (WhatsApp)">
<Tab title="Zezwól tylko na określone grupy (WhatsApp)">
```json5
{
channels: {
@ -428,7 +432,7 @@ Typowe intencje (kopiuj/wklej):
}
```
</Tab>
<Tab title="Zezwalaj na wszystkie grupy, ale wymagaj wzmianki">
<Tab title="Zezwól na wszystkie grupy, ale wymagaj wzmianki">
```json5
{
channels: {
@ -439,7 +443,7 @@ Typowe intencje (kopiuj/wklej):
}
```
</Tab>
<Tab title="Wyzwalacze tylko dla właściciela (WhatsApp)">
<Tab title="Wyzwalanie tylko przez właściciela (WhatsApp)">
```json5
{
channels: {
@ -456,42 +460,42 @@ Typowe intencje (kopiuj/wklej):
## Aktywacja (tylko właściciel)
Właściciele grup mogą przełączać aktywację dla poszczególnych grup:
Właściciele grup mogą przełączać aktywację dla grupy:
- `/activation mention`
- `/activation always`
Właściciel jest określany przez `channels.whatsapp.allowFrom` (albo własny numer E.164 bota, gdy nie ustawiono). Wyślij polecenie jako samodzielną wiadomość. Inne powierzchnie obecnie ignorują `/activation`.
Właściciel jest określany przez `channels.whatsapp.allowFrom` (lub własny numer E.164 bota, gdy nie ustawiono). Wyślij polecenie jako samodzielną wiadomość. Inne powierzchnie obecnie ignorują `/activation`.
## Pola kontekstu
Ładunki przychodzące z grupy ustawiają:
Ładunki przychodzące grupy ustawiają:
- `ChatType=group`
- `GroupSubject` (jeśli znane)
- `GroupMembers` (jeśli znane)
- `WasMentioned` (wynik bramkowania wzmianek)
- `GroupSubject` (jeśli znany)
- `GroupMembers` (jeśli znani)
- `WasMentioned` (wynik bramkowania na podstawie wzmianki)
- Tematy forum Telegram zawierają również `MessageThreadId` i `IsForum`.
Uwagi specyficzne dla kanałów:
Uwagi specyficzne dla kanału:
- BlueBubbles może opcjonalnie wzbogacać nienazwanych uczestników grup macOS z lokalnej bazy Kontaktów przed wypełnieniem `GroupMembers`. Domyślnie jest to wyłączone i uruchamia się dopiero po przejściu normalnego bramkowania grupy.
- BlueBubbles może opcjonalnie wzbogacać nienazwanych uczestników grup macOS z lokalnej bazy Contacts przed wypełnieniem `GroupMembers`. Jest to domyślnie wyłączone i działa dopiero po przejściu normalnego bramkowania grupy.
Prompt systemowy agenta zawiera wprowadzenie grupowe w pierwszej turze nowej sesji grupowej. Przypomina modelowi, aby odpowiadał jak człowiek, unikał tabel Markdown, minimalizował puste wiersze i stosował normalne odstępy czatu oraz unikał wpisywania dosłownych sekwencji `\n`. Nazwy grup i etykiety uczestników pochodzące z kanału są renderowane jako ogrodzone niezaufane metadane, a nie jako wbudowane instrukcje systemowe.
Prompt systemowy agenta zawiera wprowadzenie grupowe w pierwszej turze nowej sesji grupowej. Przypomina modelowi, aby odpowiadał jak człowiek, unikał tabel Markdown, minimalizował puste wiersze i stosował zwykłe odstępy czatu oraz unikał wpisywania dosłownych sekwencji `\n`. Nazwy grup pochodzące z kanału i etykiety uczestników są renderowane jako odgrodzone niezaufane metadane, a nie wbudowane instrukcje systemowe.
## Szczegóły iMessage
- Preferuj `chat_id:<id>` przy routingu lub dodawaniu do listy dozwolonych.
- Lista czatów: `imsg chats --limit 20`.
- Preferuj `chat_id:<id>` podczas routingu lub dodawania do listy dozwolonych.
- Wyświetl czaty: `imsg chats --limit 20`.
- Odpowiedzi grupowe zawsze wracają do tego samego `chat_id`.
## Prompty systemowe WhatsApp
Zobacz [WhatsApp](/pl/channels/whatsapp#system-prompts), aby poznać kanoniczne reguły promptów systemowych WhatsApp, w tym rozstrzyganie promptów grupowych i bezpośrednich, zachowanie symboli wieloznacznych oraz semantykę nadpisań kont.
Zobacz [WhatsApp](/pl/channels/whatsapp#system-prompts), aby poznać kanoniczne reguły promptów systemowych WhatsApp, w tym rozstrzyganie promptów grupowych i bezpośrednich, zachowanie symbolu wieloznacznego oraz semantykę nadpisywania konta.
## Szczegóły WhatsApp
Zobacz [Wiadomości grupowe](/pl/channels/group-messages), aby poznać zachowanie dotyczące tylko WhatsApp (wstrzykiwanie historii, szczegóły obsługi wzmianek).
Zobacz [Wiadomości grupowe](/pl/channels/group-messages), aby poznać zachowanie dotyczące wyłącznie WhatsApp (wstrzykiwanie historii, szczegóły obsługi wzmianki).
## Powiązane

44
docs/pl/channels/qa-channel.md
View File

@ -1,29 +1,31 @@
---
read_when:
- Podłączasz syntetyczny transport QA do lokalnego uruchomienia testów lub uruchomienia testów w CI
- Potrzebujesz dołączonego interfejsu konfiguracji qa-channel
- Iterujesz nad kompleksową automatyzacją kontroli jakości
- Podłączasz syntetyczny transport QA do lokalnego uruchomienia testów lub uruchomienia w CI
- Potrzebujesz wbudowanego interfejsu konfiguracji qa-channel
- Pracujesz iteracyjnie nad kompleksową automatyzacją QA
summary: Syntetyczny Plugin kanału klasy Slack do deterministycznych scenariuszy QA OpenClaw
title: Kanał QA
x-i18n:
generated_at: "2026-04-30T09:39:15Z"
generated_at: "2026-05-01T09:56:25Z"
model: gpt-5.5
provider: openai
source_hash: e1de1f52da1a14c845cf2a536ddc6f36ab52ed6364f68d9ece32ce272e2a2f96
source_hash: efe057812de1fbc6d89d2b6d5860cd6af4648c3e86913efa3a69267c4e8c57b4
source_path: channels/qa-channel.md
workflow: 16
---
`qa-channel` to dołączony syntetyczny transport wiadomości do zautomatyzowanego QA OpenClaw. Nie jest to kanał produkcyjny — istnieje po to, aby ćwiczyć tę samą granicę Plugin kanału, której używają rzeczywiste transporty, przy zachowaniu deterministycznego i w pełni możliwego do inspekcji stanu.
`qa-channel` to wbudowany syntetyczny transport wiadomości do zautomatyzowanego QA OpenClaw. Nie jest to kanał produkcyjny — istnieje po to, aby ćwiczyć tę samą granicę Plugin kanału, której używają rzeczywiste transporty, przy zachowaniu deterministycznego i w pełni możliwego do inspekcji stanu.
## Co robi
- Gramatyka celów klasy Slack:
- `dm:<user>`
- `channel:<room>`
- `group:<room>`
- `thread:<room>/<thread>`
- Syntetyczna szyna oparta na HTTP do wstrzykiwania wiadomości przychodzących, przechwytywania transkrypcji wychodzącej, tworzenia wątków, reakcji, edycji, usuwania oraz akcji wyszukiwania/odczytu.
- Uruchamiany po stronie hosta moduł samokontroli, który zapisuje raport Markdown w `.artifacts/qa-e2e/`.
- Współdzielone konwersacje `channel:` i `group:` są prezentowane agentom jako tury pokoju grupy/kanału, dzięki czemu ćwiczą tę samą politykę widocznych odpowiedzi i routingu narzędzi wiadomości, której używają Discord, Slack, Telegram i podobne transporty.
- Syntetyczna magistrala oparta na HTTP do wstrzykiwania wiadomości przychodzących, przechwytywania transkryptów wychodzących, tworzenia wątków, reakcji, edycji, usuwania oraz akcji wyszukiwania/odczytu.
- Uruchamiacz autotestu po stronie hosta, który zapisuje raport Markdown w `.artifacts/qa-e2e/`.
## Konfiguracja
@ -43,30 +45,30 @@ x-i18n:
Klucze konta:
- `enabled` — główny przełącznik dla tego konta.
- `enabled` — główny przełącznik tego konta.
- `name` — opcjonalna etykieta wyświetlana.
- `baseUrl` — URL syntetycznej szyny.
- `baseUrl` — URL syntetycznej magistrali.
- `botUserId` — identyfikator użytkownika bota w stylu Matrix używany w gramatyce celów.
- `botDisplayName` — nazwa wyświetlana dla wiadomości wychodzących.
- `pollTimeoutMs` — okno oczekiwania długiego odpytywania. Liczba całkowita od 100 do 30000.
- `allowFrom` — lista dozwolonych nadawców (identyfikatory użytkowników lub `"*"`).
- `defaultTo` — cel zastępczy, gdy nie podano żadnego.
- `actions.messages` / `actions.reactions` / `actions.search` / `actions.threads` — bramkowanie narzędzi dla poszczególnych akcji.
- `defaultTo` — cel awaryjny, gdy nie podano żadnego.
- `actions.messages` / `actions.reactions` / `actions.search` / `actions.threads` — bramkowanie narzędzi według akcji.
Klucze wielokontowe na najwyższym poziomie:
Klucze wielu kont na najwyższym poziomie:
- `accounts` — rekord nazwanych nadpisań dla poszczególnych kont, indeksowany według identyfikatora konta.
- `defaultAccount` — preferowany identyfikator konta, gdy skonfigurowano wiele kont.
## Moduły uruchamiające
## Uruchamiacze
Samokontrola po stronie hosta (zapisuje raport Markdown w `.artifacts/qa-e2e/`):
Autotest po stronie hosta (zapisuje raport Markdown w `.artifacts/qa-e2e/`):
```bash
pnpm qa:e2e
```
To przechodzi przez `qa-lab`, uruchamia szynę QA z repozytorium, startuje dołączony wycinek środowiska uruchomieniowego `qa-channel` i wykonuje deterministyczną samokontrolę.
To przechodzi przez `qa-lab`, uruchamia magistralę QA z repozytorium, bootuje wbudowany fragment środowiska wykonawczego `qa-channel` i wykonuje deterministyczny autotest.
Pełny zestaw scenariuszy oparty na repozytorium:
@ -74,7 +76,7 @@ Pełny zestaw scenariuszy oparty na repozytorium:
pnpm openclaw qa suite
```
Uruchamia scenariusze równolegle względem linii QA Gateway. Zobacz [omówienie QA](/pl/concepts/qa-e2e-automation), aby poznać scenariusze, profile i tryby dostawców.
Uruchamia scenariusze równolegle względem ścieżki QA Gateway. Zobacz [Przegląd QA](/pl/concepts/qa-e2e-automation), aby poznać scenariusze, profile i tryby providerów.
Witryna QA oparta na Dockerze (Gateway + interfejs debuggera QA Lab w jednym stosie):
@ -82,12 +84,12 @@ Witryna QA oparta na Dockerze (Gateway + interfejs debuggera QA Lab w jednym sto
pnpm qa:lab:up
```
Buduje witrynę QA, uruchamia oparty na Dockerze stos Gateway + QA Lab i wypisuje URL QA Lab. Następnie możesz wybierać scenariusze, wybrać linię modelu, uruchamiać pojedyncze przebiegi i obserwować wyniki na żywo. Debugger QA Lab jest oddzielony od dostarczanego pakietu interfejsu Control UI.
Buduje witrynę QA, uruchamia oparty na Dockerze stos Gateway + QA Lab i wypisuje URL QA Lab. Stamtąd możesz wybierać scenariusze, wybierać ścieżkę modelu, uruchamiać pojedyncze przebiegi i obserwować wyniki na żywo. Debugger QA Lab jest oddzielny od dostarczanego pakietu Control UI.
## Powiązane
- [Omówienie QA](/pl/concepts/qa-e2e-automation) — ogólny stos, adaptery transportu, tworzenie scenariuszy
- [QA Matrix](/pl/concepts/qa-matrix) — przykładowy moduł uruchamiający transport na żywo, który steruje rzeczywistym kanałem
- [Przegląd QA](/pl/concepts/qa-e2e-automation) — ogólny stos, adaptery transportu, tworzenie scenariuszy
- [Matrix QA](/pl/concepts/qa-matrix) — przykładowy uruchamiacz transportu na żywo, który steruje rzeczywistym kanałem
- [Parowanie](/pl/channels/pairing)
- [Grupy](/pl/channels/groups)
- [Omówienie kanałów](/pl/channels)
- [Przegląd kanałów](/pl/channels)

371
docs/pl/ci.md
View File

@ -1,75 +1,75 @@
---
read_when:
- Musisz zrozumieć, dlaczego zadanie CI zostało lub nie zostało uruchomione
- Debugujesz nieudaną kontrolę GitHub Actions
- Koordynujesz uruchomienie lub ponowne uruchomienie walidacji wydania
- Diagnozujesz nieudane sprawdzenie GitHub Actions
- Koordynujesz uruchomienie lub ponowienie walidacji wydania
summary: Graf zadań CI, bramki zakresu, parasole wydań i lokalne odpowiedniki poleceń
title: Potok CI
x-i18n:
generated_at: "2026-04-30T18:39:07Z"
generated_at: "2026-05-01T09:56:23Z"
model: gpt-5.5
provider: openai
source_hash: a24afc27606ac7f4e9ead89acdd319bffa23336610f8a6cd8b576ea1a5b233dd
source_hash: 679913539743f9495fffa010489ec95e05ce875751afa8a93bf8bf7045d6d9de
source_path: ci.md
workflow: 16
---
OpenClaw CI uruchamia się przy każdym wypchnięciu do `main` i dla każdego pull requesta. Zadanie `preflight` klasyfikuje różnicę i wyłącza kosztowne ścieżki, gdy zmieniły się tylko niepowiązane obszary. Ręczne uruchomienia `workflow_dispatch` celowo omijają inteligentne zawężanie zakresu i rozgałęziają pełny graf dla kandydatów do wydania oraz szerokiej walidacji. Ścieżki Android pozostają opcjonalne przez `include_android`. Pokrycie Plugin tylko dla wydań znajduje się w osobnym workflow [`Wstępne wydanie Plugin`](#plugin-prerelease) i uruchamia się tylko z [`Pełnej walidacji wydania`](#full-release-validation) albo przez jawne ręczne wywołanie.
OpenClaw CI działa przy każdym wypchnięciu do `main` i każdym pull requeście. Zadanie `preflight` klasyfikuje różnicę i wyłącza kosztowne ścieżki, gdy zmieniły się tylko niepowiązane obszary. Ręczne uruchomienia `workflow_dispatch` celowo omijają inteligentne zawężanie zakresu i rozwijają pełny graf dla kandydatów do wydania oraz szerokiej walidacji. Ścieżki Androida pozostają opcjonalne przez `include_android`. Pokrycie Plugin tylko dla wydań znajduje się w osobnym przepływie pracy [`Wstępna wersja Plugin`](#plugin-prerelease) i działa wyłącznie z poziomu [`Pełnej walidacji wydania`](#full-release-validation) albo jawnego ręcznego dispatcha.
## Przegląd potoku
## Przegląd pipeline’u
| Zadanie | Cel | Kiedy się uruchamia |
| -------------------------------- | -------------------------------------------------------------------------------------------- | --------------------------------- |
| `preflight` | Wykrywa zmiany tylko w dokumentacji, zmienione zakresy, zmienione rozszerzenia i buduje manifest CI | Zawsze przy wypchnięciach i PR-ach, które nie są szkicami |
| `security-scm-fast` | Wykrywanie kluczy prywatnych i audyt workflow przez `zizmor` | Zawsze przy wypchnięciach i PR-ach, które nie są szkicami |
| `security-dependency-audit` | Audyt produkcyjnego lockfile bez zależności względem ostrzeżeń npm | Zawsze przy wypchnięciach i PR-ach, które nie są szkicami |
| `security-fast` | Wymagany agregat dla szybkich zadań bezpieczeństwa | Zawsze przy wypchnięciach i PR-ach, które nie są szkicami |
| `check-dependencies` | Produkcyjne przejście Knip tylko dla zależności oraz strażnik listy dozwolonych nieużywanych plików | Zmiany istotne dla Node |
| `build-artifacts` | Buduje `dist/`, Control UI, sprawdzenia zbudowanych artefaktów i artefakty wielokrotnego użytku dla zadań podrzędnych | Zmiany istotne dla Node |
| `checks-fast-core` | Szybkie linuksowe ścieżki poprawności, takie jak sprawdzenia bundled/plugin-contract/protocol | Zmiany istotne dla Node |
| `checks-fast-contracts-channels` | Shardowane sprawdzenia kontraktów kanałów ze stabilnym zagregowanym wynikiem sprawdzenia | Zmiany istotne dla Node |
| `checks-node-core-test` | Shardy testów rdzenia Node, z wyłączeniem ścieżek kanałów, bundled, kontraktów i rozszerzeń | Zmiany istotne dla Node |
| `check` | Shardowany odpowiednik głównej lokalnej bramki: typy produkcyjne, lint, strażniki, typy testów i rygorystyczny smoke | Zmiany istotne dla Node |
| `check-additional` | Shardy architektury, granic, strażników powierzchni rozszerzeń, granic pakietów i gateway-watch | Zmiany istotne dla Node |
| `build-smoke` | Testy smoke zbudowanego CLI i smoke pamięci startowej | Zmiany istotne dla Node |
| `checks` | Weryfikator testów kanałów dla zbudowanych artefaktów | Zmiany istotne dla Node |
| `checks-node-compat-node22` | Ścieżka budowania i smoke zgodności z Node 22 | Ręczne wywołanie CI dla wydań |
| `check-docs` | Formatowanie dokumentacji, lint i sprawdzenia niedziałających linków | Zmieniono dokumentację |
| `skills-python` | Ruff + pytest dla Skills opartych na Pythonie | Zmiany istotne dla Python-skill |
| `checks-windows` | Testy procesów/ścieżek specyficzne dla Windows oraz współdzielone regresje specyfikatorów importu runtime | Zmiany istotne dla Windows |
| `macos-node` | Ścieżka testów TypeScript na macOS używająca współdzielonych zbudowanych artefaktów | Zmiany istotne dla macOS |
| `macos-swift` | Swift lint, budowanie i testy aplikacji macOS | Zmiany istotne dla macOS |
| `android` | Testy jednostkowe Android dla obu wariantów oraz jedna kompilacja debug APK | Zmiany istotne dla Android |
| `test-performance-agent` | Codzienna optymalizacja wolnych testów przez Codex po zaufanej aktywności | Sukces CI na main albo ręczne wywołanie |
| Zadanie | Cel | Kiedy działa |
| -------------------------------- | -------------------------------------------------------------------------------------------- | ---------------------------------- |
| `preflight` | Wykrywa zmiany tylko w dokumentacji, zmienione zakresy, zmienione rozszerzenia i buduje manifest CI | Zawsze przy wypchnięciach i PR-ach innych niż draft |
| `security-scm-fast` | Wykrywanie kluczy prywatnych i audyt workflow przez `zizmor` | Zawsze przy wypchnięciach i PR-ach innych niż draft |
| `security-dependency-audit` | Audyt produkcyjnego lockfile’a bez instalowania zależności względem advisory npm | Zawsze przy wypchnięciach i PR-ach innych niż draft |
| `security-fast` | Wymagany agregat dla szybkich zadań bezpieczeństwa | Zawsze przy wypchnięciach i PR-ach innych niż draft |
| `check-dependencies` | Produkcyjny przebieg Knip tylko dla zależności oraz strażnik listy dozwolonych nieużywanych plików | Zmiany istotne dla Node |
| `build-artifacts` | Buduje `dist/`, Control UI, kontrole zbudowanych artefaktów i artefakty wielokrotnego użycia dla dalszych zadań | Zmiany istotne dla Node |
| `checks-fast-core` | Szybkie linuksowe ścieżki poprawności, takie jak kontrole pakietów wbudowanych/kontraktu Plugin/protokołu | Zmiany istotne dla Node |
| `checks-fast-contracts-channels` | Shardowane kontrole kontraktów kanałów ze stabilnym zagregowanym wynikiem kontroli | Zmiany istotne dla Node |
| `checks-node-core-test` | Shardy testów rdzenia Node, z wyłączeniem ścieżek kanałów, pakietów wbudowanych, kontraktów i rozszerzeń | Zmiany istotne dla Node |
| `check` | Shardowany odpowiednik głównej lokalnej bramki: typy produkcyjne, lint, strażnicy, typy testów i rygorystyczny smoke | Zmiany istotne dla Node |
| `check-additional` | Shardy architektury, granic, strażników powierzchni rozszerzeń, granic pakietów i obserwowania Gateway | Zmiany istotne dla Node |
| `build-smoke` | Testy smoke zbudowanego CLI i smoke pamięci startowej | Zmiany istotne dla Node |
| `checks` | Weryfikator testów kanałów zbudowanych artefaktów | Zmiany istotne dla Node |
| `checks-node-compat-node22` | Ścieżka budowania zgodności i smoke dla Node 22 | Ręczny dispatch CI dla wydań |
| `check-docs` | Formatowanie dokumentacji, lint i kontrole uszkodzonych linków | Zmieniona dokumentacja |
| `skills-python` | Ruff + pytest dla Skills opartych na Pythonie | Zmiany istotne dla Skills w Pythonie |
| `checks-windows` | Testy procesów/ścieżek specyficzne dla Windows oraz współdzielone regresje specyfikatorów importu runtime | Zmiany istotne dla Windows |
| `macos-node` | Ścieżka testów TypeScript na macOS z użyciem współdzielonych zbudowanych artefaktów | Zmiany istotne dla macOS |
| `macos-swift` | Swift lint, budowanie i testy dla aplikacji macOS | Zmiany istotne dla macOS |
| `android` | Testy jednostkowe Androida dla obu flavorów oraz jedno budowanie APK debug | Zmiany istotne dla Androida |
| `test-performance-agent` | Codzienna optymalizacja wolnych testów przez Codex po zaufanej aktywności | Sukces CI na main albo ręczny dispatch |
## Kolejność szybkiego niepowodzenia
## Kolejność szybkiego przerywania
1. `preflight` decyduje, które ścieżki w ogóle istnieją. Logika `docs-scope` i `changed-scope` to kroki wewnątrz tego zadania, a nie samodzielne zadania.
2. `security-scm-fast`, `security-dependency-audit`, `security-fast`, `check`, `check-additional`, `check-docs` i `skills-python` szybko kończą się niepowodzeniem bez czekania na cięższe zadania artefaktów i macierzy platform.
3. `build-artifacts` nakłada się z szybkimi ścieżkami Linuksa, aby konsumenci podrzędni mogli wystartować, gdy tylko współdzielone budowanie będzie gotowe.
4. Cięższe ścieżki platform i runtime rozgałęziają się później: `checks-fast-core`, `checks-fast-contracts-channels`, `checks-node-core-test`, `checks`, `checks-windows`, `macos-node`, `macos-swift` i `android`.
1. `preflight` decyduje, które ścieżki w ogóle istnieją. Logika `docs-scope` i `changed-scope` to kroki w tym zadaniu, a nie samodzielne zadania.
2. `security-scm-fast`, `security-dependency-audit`, `security-fast`, `check`, `check-additional`, `check-docs` i `skills-python` kończą się niepowodzeniem szybko, bez czekania na cięższe zadania macierzy artefaktów i platform.
3. `build-artifacts` nakłada się na szybkie ścieżki Linuksa, aby dalsi konsumenci mogli ruszyć, gdy tylko współdzielone budowanie będzie gotowe.
4. Cięższe ścieżki platform i runtime rozwijają się potem: `checks-fast-core`, `checks-fast-contracts-channels`, `checks-node-core-test`, `checks`, `checks-windows`, `macos-node`, `macos-swift` i `android`.
GitHub może oznaczać zastąpione zadania jako `cancelled`, gdy nowsze wypchnięcie trafi do tego samego PR-a albo referencji `main`. Traktuj to jako szum CI, chyba że najnowsze uruchomienie dla tej samej referencji również kończy się niepowodzeniem. Zagregowane sprawdzenia shardów używają `!cancelled() && always()`, więc nadal zgłaszają normalne niepowodzenia shardów, ale nie kolejkowują się po tym, jak cały workflow został już zastąpiony. Automatyczny klucz współbieżności CI jest wersjonowany (`CI-v7-*`), aby zombie po stronie GitHub w starej grupie kolejki nie mogło bezterminowo blokować nowszych uruchomień main. Ręczne uruchomienia pełnego zestawu używają `CI-manual-v1-*` i nie anulują uruchomień w toku.
GitHub może oznaczać zastąpione zadania jako `cancelled`, gdy nowsze wypchnięcie trafi do tego samego PR-a albo refa `main`. Traktuj to jako szum CI, chyba że najnowsze uruchomienie dla tego samego refa również kończy się niepowodzeniem. Zagregowane kontrole shardów używają `!cancelled() && always()`, więc nadal raportują zwykłe awarie shardów, ale nie ustawiają się w kolejce po tym, jak cały workflow został już zastąpiony. Automatyczny klucz współbieżności CI jest wersjonowany (`CI-v7-*`), aby zombie po stronie GitHuba w starej grupie kolejki nie mogło bezterminowo blokować nowszych uruchomień main. Ręczne uruchomienia pełnego zestawu używają `CI-manual-v1-*` i nie anulują trwających uruchomień.
## Zakres i routowanie
## Zakres i routing
Logika zakresu znajduje się w `scripts/ci-changed-scope.mjs` i jest objęta testami jednostkowymi w `src/scripts/ci-changed-scope.test.ts`. Ręczne wywołanie pomija wykrywanie changed-scope i sprawia, że manifest preflight zachowuje się tak, jakby zmienił się każdy zakresowy obszar.
Logika zakresu znajduje się w `scripts/ci-changed-scope.mjs` i jest pokryta testami jednostkowymi w `src/scripts/ci-changed-scope.test.ts`. Ręczny dispatch pomija wykrywanie zmienionego zakresu i sprawia, że manifest preflight zachowuje się tak, jakby zmienił się każdy zakresowany obszar.
- **Edycje workflow CI** walidują graf CI Node oraz linting workflow, ale same nie wymuszają natywnych buildów Windows, Android ani macOS; te ścieżki platform pozostają zawężone do zmian w źródłach platform.
- **Edycje dotyczące tylko routowania CI, wybrane tanie edycje fixture testów rdzenia oraz wąskie edycje pomocnicze/routingu testów kontraktu Plugin** używają szybkiej ścieżki manifestu tylko dla Node: `preflight`, bezpieczeństwo i jedno zadanie `checks-fast-core`. Ta ścieżka pomija artefakty budowania, zgodność z Node 22, kontrakty kanałów, pełne shardy rdzenia, shardy bundled-plugin oraz dodatkowe macierze strażników, gdy zmiana jest ograniczona do powierzchni routingu lub pomocniczych, które szybkie zadanie ćwiczy bezpośrednio.
- **Sprawdzenia Node na Windows** są zawężone do specyficznych dla Windows wrapperów procesów/ścieżek, pomocników runnerów npm/pnpm/UI, konfiguracji menedżera pakietów oraz powierzchni workflow CI, które wykonują tę ścieżkę; niepowiązane zmiany źródeł, Plugin, install-smoke i tylko testów pozostają na linuksowych ścieżkach Node.
- **Edycje workflow CI** walidują graf CI Node oraz lint workflow, ale same nie wymuszają natywnych buildów Windows, Androida ani macOS; te ścieżki platform pozostają ograniczone do zmian w źródłach platform.
- **Edycje tylko routingu CI, wybrane tanie edycje fixture’ów testów rdzenia i wąskie edycje pomocników/routingu testów kontraktu Plugin** używają szybkiej ścieżki manifestu tylko dla Node: `preflight`, bezpieczeństwo i jedno zadanie `checks-fast-core`. Ta ścieżka pomija artefakty builda, zgodność Node 22, kontrakty kanałów, pełne shardy rdzenia, shardy wbudowanych Plugin i dodatkowe macierze strażników, gdy zmiana jest ograniczona do powierzchni routingu lub pomocników, które szybkie zadanie ćwiczy bezpośrednio.
- **Kontrole Node na Windows** są ograniczone do wrapperów procesów/ścieżek specyficznych dla Windows, pomocników runnerów npm/pnpm/UI, konfiguracji menedżera pakietów oraz powierzchni workflow CI, które wykonują tę ścieżkę; niepowiązane zmiany źródeł, Plugin, install-smoke i zmiany tylko w testach pozostają na linuksowych ścieżkach Node.
Najwolniejsze rodziny testów Node są dzielone lub balansowane tak, aby każde zadanie pozostało małe bez nadmiernego rezerwowania runnerów: kontrakty kanałów uruchamiają się jako trzy ważone shardy, małe ścieżki jednostkowe rdzenia są parowane, auto-reply działa jako czterech zbalansowanych workerów (z poddrzewem reply podzielonym na shardy agent-runner, dispatch oraz commands/state-routing), a agentowe konfiguracje Gateway/Plugin są rozłożone na istniejące agentowe zadania Node tylko ze źródeł zamiast czekać na zbudowane artefakty. Szerokie testy przeglądarkowe, QA, multimediów i różne testy Plugin używają dedykowanych konfiguracji Vitest zamiast współdzielonego catch-all dla Plugin. Shardy include-pattern zapisują wpisy czasów z użyciem nazwy sharda CI, więc `.artifacts/vitest-shard-timings.json` może odróżnić całą konfigurację od przefiltrowanego sharda. `check-additional` trzyma razem pracę kompilacji/canary dla granic pakietów i oddziela architekturę topologii runtime od pokrycia gateway watch; shard strażnika granic uruchamia swoje małe niezależne strażniki współbieżnie w jednym zadaniu. Gateway watch, testy kanałów i shard granic wsparcia rdzenia działają współbieżnie wewnątrz `build-artifacts` po tym, jak `dist/` i `dist-runtime/` są już zbudowane.
Najwolniejsze rodziny testów Node są dzielone lub równoważone tak, aby każde zadanie pozostawało małe bez nadmiernego rezerwowania runnerów: kontrakty kanałów działają jako trzy ważone shardy, małe ścieżki jednostkowe rdzenia są parowane, auto-reply działa jako cztery zrównoważone workery (z poddrzewem reply podzielonym na shardy agent-runner, dispatch oraz commands/state-routing), a konfiguracje agentic Gateway/Plugin są rozłożone po istniejących zadaniach agentic Node tylko ze źródeł zamiast czekać na zbudowane artefakty. Szerokie testy przeglądarkowe, QA, media i różne testy Plugin używają swoich dedykowanych konfiguracji Vitest zamiast współdzielonego ogólnego zestawu Plugin. Shardy wzorców uwzględniania zapisują wpisy czasów z użyciem nazwy shardu CI, więc `.artifacts/vitest-shard-timings.json` może odróżnić całą konfigurację od filtrowanego shardu. `check-additional` utrzymuje razem prace kompilacji/canary granic pakietów i oddziela architekturę topologii runtime od pokrycia obserwowania Gateway; shard strażnika granic uruchamia swoje małe niezależne strażniki współbieżnie w jednym zadaniu. Obserwowanie Gateway, testy kanałów i shard granic wsparcia rdzenia działają współbieżnie w `build-artifacts` po tym, jak `dist/` i `dist-runtime/` są już zbudowane.
Android CI uruchamia zarówno `testPlayDebugUnitTest`, jak i `testThirdPartyDebugUnitTest`, a następnie buduje Play debug APK. Wariant third-party nie ma osobnego zestawu źródeł ani manifestu; jego ścieżka testów jednostkowych nadal kompiluje wariant z flagami BuildConfig SMS/call-log, unikając jednocześnie zduplikowanego zadania pakowania debug APK przy każdym wypchnięciu istotnym dla Android.
Android CI uruchamia zarówno `testPlayDebugUnitTest`, jak i `testThirdPartyDebugUnitTest`, a następnie buduje debug APK Play. Flavor third-party nie ma osobnego zestawu źródeł ani manifestu; jego ścieżka testów jednostkowych nadal kompiluje flavor z flagami BuildConfig dla SMS/rejestru połączeń, unikając jednocześnie duplikowania zadania pakowania debug APK przy każdym wypchnięciu istotnym dla Androida.
Shard `check-dependencies` uruchamia `pnpm deadcode:dependencies` (produkcyjne przejście Knip tylko dla zależności przypięte do najnowszej wersji Knip, z wyłączonym minimalnym wiekiem wydania pnpm dla instalacji `dlx`) oraz `pnpm deadcode:unused-files`, które porównuje produkcyjne znaleziska nieużywanych plików z Knip z `scripts/deadcode-unused-files.allowlist.mjs`. Strażnik nieużywanych plików kończy się niepowodzeniem, gdy PR dodaje nowy, niezweryfikowany nieużywany plik albo pozostawia nieaktualny wpis listy dozwolonych, zachowując jednocześnie intencjonalne dynamiczne powierzchnie Plugin, generowane, build, live-test i mosty pakietów, których Knip nie może rozwiązać statycznie.
Shard `check-dependencies` uruchamia `pnpm deadcode:dependencies` (produkcyjny przebieg Knip tylko dla zależności, przypięty do najnowszej wersji Knip, z wyłączonym minimalnym wiekiem wydania pnpm dla instalacji `dlx`) oraz `pnpm deadcode:unused-files`, które porównuje produkcyjne wyniki nieużywanych plików z Knip z `scripts/deadcode-unused-files.allowlist.mjs`. Strażnik nieużywanych plików kończy się niepowodzeniem, gdy PR dodaje nowy, nieprzejrzany nieużywany plik albo zostawia nieaktualny wpis na liście dozwolonych, zachowując jednocześnie celowe powierzchnie dynamicznych Plugin, wygenerowane, buildów, testów live i mostków pakietów, których Knip nie potrafi rozwiązać statycznie.
## Ręczne wywołania
## Ręczne dispatche
Ręczne wywołania CI uruchamiają ten sam graf zadań co normalne CI, ale wymuszają każdą zakresową ścieżkę poza Android: shardy Linux Node, shardy bundled-plugin, kontrakty kanałów, zgodność Node 22, `check`, `check-additional`, build smoke, sprawdzenia dokumentacji, Python skills, Windows, macOS i i18n Control UI. Samodzielne ręczne wywołania CI uruchamiają Android tylko z `include_android=true`; parasol pełnego wydania włącza Android, przekazując `include_android=true`. Statyczne sprawdzenia wstępnego wydania Plugin, shard tylko dla wydania `agentic-plugins`, pełny sweep batch rozszerzeń oraz ścieżki Docker wstępnego wydania Plugin są wykluczone z CI. Pakiet Docker wstępnego wydania uruchamia się tylko wtedy, gdy `Full Release Validation` wywołuje osobny workflow `Plugin Prerelease` z włączoną bramką release-validation.
Ręczne dispatche CI uruchamiają ten sam graf zadań co zwykłe CI, ale wymuszają wszystkie zakresowane ścieżki nieandroidowe: shardy Linux Node, shardy wbudowanych Plugin, kontrakty kanałów, zgodność Node 22, `check`, `check-additional`, build smoke, kontrole dokumentacji, Python skills, Windows, macOS i i18n Control UI. Samodzielne ręczne dispatche CI uruchamiają Androida tylko z `include_android=true`; pełny parasol wydania włącza Androida przez przekazanie `include_android=true`. Statyczne kontrole prerelease Plugin, shard tylko dla wydań `agentic-plugins`, pełny wsadowy sweep rozszerzeń i dockerowe ścieżki prerelease Plugin są wyłączone z CI. Zestaw dockerowy prerelease działa tylko wtedy, gdy `Pełna walidacja wydania` dispatchuje osobny workflow `Wstępna wersja Plugin` z włączoną bramką walidacji wydania.
Ręczne uruchomienia używają unikalnej grupy współbieżności, więc pełny zestaw dla kandydata do wydania nie jest anulowany przez inne wypchnięcie ani uruchomienie PR na tej samej referencji. Opcjonalne wejście `target_ref` pozwala zaufanemu wywołującemu uruchomić ten graf względem brancha, tagu albo pełnego SHA commita, używając pliku workflow z wybranej referencji wywołania.
Ręczne uruchomienia używają unikalnej grupy współbieżności, więc pełny zestaw kandydata do wydania nie jest anulowany przez kolejne wypchnięcie ani uruchomienie PR na tym samym refie. Opcjonalne wejście `target_ref` pozwala zaufanemu wywołującemu uruchomić ten graf względem gałęzi, taga albo pełnego SHA commita, używając pliku workflow z wybranego refa dispatcha.
```bash
gh workflow run ci.yml --ref release/YYYY.M.D
@ -77,17 +77,17 @@ gh workflow run ci.yml --ref main -f target_ref=<branch-or-sha> -f include_andro
gh workflow run full-release-validation.yml --ref main -f ref=<branch-or-sha>
```
## Runery
## Runnery
| Runner | Zadania |
| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ubuntu-24.04` | `preflight`, szybkie zadania i agregaty bezpieczeństwa (`security-scm-fast`, `security-dependency-audit`, `security-fast`), szybkie kontrole protokołu/kontraktu/wbudowanych elementów, shardowane kontrole kontraktu kanałów, shardy `check` z wyjątkiem lintingu, shardy i agregaty `check-additional`, weryfikatory agregatów testów Node, kontrole dokumentacji, Python skills, workflow-sanity, labeler, auto-response; preflight install-smoke także używa Ubuntu hostowanego przez GitHub, aby macierz Blacksmith mogła kolejkować się wcześniej |
| `blacksmith-4vcpu-ubuntu-2404` | `CodeQL Critical Quality`, lżejsze shardy rozszerzeń, `checks-fast-core`, `checks-node-compat-node22`, `check-prod-types` oraz `check-test-types` |
| `blacksmith-8vcpu-ubuntu-2404` | `build-artifacts`, build-smoke, shardy testów Node dla Linuksa, shardy testów wbudowanych pluginów, `android` |
| `blacksmith-16vcpu-ubuntu-2404` | `check-lint` (wystarczająco wrażliwy na CPU, że 8 vCPU kosztowało więcej, niż oszczędzało); kompilacje Docker install-smoke (czas kolejki 32 vCPU kosztował więcej, niż oszczędzał) |
| `blacksmith-16vcpu-windows-2025` | `checks-windows` |
| `blacksmith-6vcpu-macos-latest` | `macos-node` w `openclaw/openclaw`; forki przechodzą awaryjnie na `macos-latest` |
| `blacksmith-12vcpu-macos-latest` | `macos-swift` w `openclaw/openclaw`; forki przechodzą awaryjnie na `macos-latest` |
| Runner | Zadania |
| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ubuntu-24.04` | `preflight`, szybkie zadania i agregaty bezpieczeństwa (`security-scm-fast`, `security-dependency-audit`, `security-fast`), szybkie kontrole protokołu/kontraktów/dołączonych elementów, podzielone kontrole kontraktów kanałów, fragmenty `check` z wyjątkiem lintu, fragmenty i agregaty `check-additional`, weryfikatory agregatów testów Node, kontrole dokumentacji, Python Skills, workflow-sanity, labeler, auto-response; install-smoke preflight także używa Ubuntu hostowanego przez GitHub, aby macierz Blacksmith mogła wcześniej trafić do kolejki |
| `blacksmith-4vcpu-ubuntu-2404` | `CodeQL Critical Quality`, lżejsze fragmenty Pluginów, `checks-fast-core`, `checks-node-compat-node22`, `check-prod-types` oraz `check-test-types` |
| `blacksmith-8vcpu-ubuntu-2404` | `build-artifacts`, build-smoke, fragmenty testów Linux Node, fragmenty testów dołączonych Pluginów, `android` |
| `blacksmith-16vcpu-ubuntu-2404` | `check-lint` (na tyle wrażliwe na CPU, że 8 vCPU kosztowało więcej, niż oszczędzało); kompilacje Docker install-smoke (czas oczekiwania w kolejce 32-vCPU kosztował więcej, niż oszczędzał) |
| `blacksmith-16vcpu-windows-2025` | `checks-windows` |
| `blacksmith-6vcpu-macos-latest` | `macos-node` w `openclaw/openclaw`; forki wracają do `macos-latest` |
| `blacksmith-12vcpu-macos-latest` | `macos-swift` w `openclaw/openclaw`; forki wracają do `macos-latest` |
## Lokalne odpowiedniki
@ -117,27 +117,37 @@ pnpm test:perf:groups:compare .artifacts/test-perf/baseline-before.json .artifac
## Pełna walidacja wydania
`Full Release Validation` to ręczny nadrzędny workflow dla „uruchom wszystko przed wydaniem”. Przyjmuje gałąź, tag lub pełny SHA commita, uruchamia ręczny workflow `CI` z tym celem, uruchamia `Plugin Prerelease` dla dowodu dotyczącego wyłącznie wydania: pluginu/pakietu/statycznych zasobów/Docker, oraz uruchamia `OpenClaw Release Checks` dla smoke testów instalacji, akceptacji pakietu, zestawów ścieżki wydania Docker, live/E2E, OpenWebUI, zgodności QA Lab, Matrix i ścieżek Telegram. Może także uruchomić powydaniowy workflow `NPM Telegram Beta E2E`, gdy podano specyfikację opublikowanego pakietu.
`Full Release Validation` to ręczny nadrzędny workflow dla „uruchomienia wszystkiego przed wydaniem”. Przyjmuje gałąź, tag albo pełny SHA commita, uruchamia ręczny workflow `CI` z tym celem, uruchamia `Plugin Prerelease` dla dowodów dotyczących wyłącznie wydania: Pluginów, pakietów, statycznych zasobów i Docker, oraz uruchamia `OpenClaw Release Checks` dla install smoke, package acceptance, zestawów ścieżki wydania Docker, live/E2E, OpenWebUI, parytetu QA Lab, Matrix oraz ścieżek Telegram. Może także uruchomić powydaniowy workflow `NPM Telegram Beta E2E`, gdy podano opublikowaną specyfikację pakietu.
`release_profile` steruje zakresem live/provider przekazywanym do kontroli wydania:
Zobacz [Pełna walidacja wydania](/pl/reference/full-release-validation), aby poznać
macierz etapów, dokładne nazwy zadań workflow, różnice między profilami, artefakty oraz
uchwyty do ukierunkowanych ponownych uruchomień.
- `minimum` zachowuje najszybsze krytyczne dla wydania ścieżki OpenAI/rdzenia.
`release_profile` steruje zakresem live/provider przekazywanym do kontroli wydania. Ręczne workflow wydania domyślnie używają `stable`; użyj `full` tylko wtedy, gdy celowo potrzebujesz szerokiej doradczej macierzy dostawców/mediów.
- `minimum` zachowuje najszybsze, krytyczne dla wydania ścieżki OpenAI/core.
- `stable` dodaje stabilny zestaw provider/backend.
- `full` uruchamia szeroką macierz doradczą provider/media.
- `full` uruchamia szeroką doradczą macierz dostawców/mediów.
Workflow nadrzędny zapisuje identyfikatory uruchomionych workflow podrzędnych, a końcowe zadanie `Verify full validation` ponownie sprawdza bieżące konkluzje uruchomień podrzędnych i dołącza tabele najwolniejszych zadań dla każdego uruchomienia podrzędnego. Jeśli workflow podrzędny zostanie uruchomiony ponownie i zakończy się powodzeniem, uruchom ponownie tylko zadanie weryfikujące rodzica, aby odświeżyć wynik workflow nadrzędnego i podsumowanie czasów.
Workflow nadrzędny zapisuje identyfikatory uruchomionych workflow podrzędnych, a końcowe zadanie `Verify full validation` ponownie sprawdza bieżące wyniki uruchomień podrzędnych i dopisuje tabele najwolniejszych zadań dla każdego uruchomienia podrzędnego. Jeśli workflow podrzędny zostanie uruchomiony ponownie i zakończy się powodzeniem, uruchom ponownie tylko zadanie weryfikatora nadrzędnego, aby odświeżyć wynik workflow nadrzędnego i podsumowanie czasów.
Do odzyskiwania zarówno `Full Release Validation`, jak i `OpenClaw Release Checks` przyjmują `rerun_group`. Użyj `all` dla kandydata do wydania, `ci` tylko dla zwykłego pełnego podrzędnego CI, `release-checks` dla każdego podrzędnego zadania wydania albo węższej grupy: `install-smoke`, `cross-os`, `live-e2e`, `package`, `qa`, `qa-parity`, `qa-live` lub `npm-telegram` w workflow nadrzędnym. Dzięki temu ponowne uruchomienie nieudanego zestawu wydania pozostaje ograniczone po ukierunkowanej poprawce.
Do odzyskiwania zarówno `Full Release Validation`, jak i `OpenClaw Release Checks` przyjmują `rerun_group`. Użyj `all` dla kandydata do wydania, `ci` tylko dla zwykłego pełnego workflow podrzędnego CI, `plugin-prerelease` tylko dla podrzędnego prerelease Pluginu, `release-checks` dla każdego podrzędnego workflow wydania albo węższej grupy: `install-smoke`, `cross-os`, `live-e2e`, `package`, `qa`, `qa-parity`, `qa-live` lub `npm-telegram` w workflow nadrzędnym. Dzięki temu ponowne uruchomienie nieudanego środowiska wydania pozostaje ograniczone po ukierunkowanej poprawce.
`OpenClaw Release Checks` używa zaufanego odniesienia workflow, aby jednorazowo rozwiązać wybrane odniesienie do tarballa `release-package-under-test`, a następnie przekazuje ten artefakt zarówno do workflow Docker ścieżki wydania live/E2E, jak i do sharda akceptacji pakietu. To utrzymuje spójne bajty pakietu między zestawami wydania i unika ponownego pakowania tego samego kandydata w wielu zadaniach podrzędnych.
`OpenClaw Release Checks` używa zaufanego odwołania workflow, aby raz rozwiązać wybrane odwołanie do tarballa `release-package-under-test`, a następnie przekazuje ten artefakt zarówno do workflow Docker ścieżki wydania live/E2E, jak i do fragmentu package acceptance. Dzięki temu bajty pakietu pozostają spójne między środowiskami wydania i unika się ponownego pakowania tego samego kandydata w wielu zadaniach podrzędnych.
## Shardy live i E2E
Zduplikowane uruchomienia `Full Release Validation` dla `ref=main` i `rerun_group=all`
zastępują starszy workflow nadrzędny. Monitor nadrzędny anuluje każdy workflow podrzędny,
który już uruchomił, gdy workflow nadrzędny zostaje anulowany, więc nowsza walidacja main
nie czeka za przestarzałym dwugodzinnym uruchomieniem release-check. Walidacja gałęzi/tagu wydania
oraz ukierunkowane grupy ponownego uruchomienia zachowują `cancel-in-progress: false`.
Podrzędny workflow wydania live/E2E zachowuje szerokie natywne pokrycie `pnpm test:live`, ale uruchamia je jako nazwane shardy przez `scripts/test-live-shard.mjs` zamiast jednego zadania szeregowego:
## Fragmenty live i E2E
Podrzędny workflow wydania live/E2E zachowuje szerokie natywne pokrycie `pnpm test:live`, ale uruchamia je jako nazwane fragmenty przez `scripts/test-live-shard.mjs` zamiast jednego zadania szeregowego:
- `native-live-src-agents`
- `native-live-src-gateway-core`
- filtrowane według providera zadania `native-live-src-gateway-profiles`
- zadania `native-live-src-gateway-profiles` filtrowane według providera
- `native-live-src-gateway-backends`
- `native-live-test`
- `native-live-extensions-a-k`
@ -145,57 +155,57 @@ Podrzędny workflow wydania live/E2E zachowuje szerokie natywne pokrycie `pnpm t
- `native-live-extensions-openai`
- `native-live-extensions-o-z-other`
- `native-live-extensions-xai`
- podzielone shardy audio/wideo mediów oraz filtrowane według providera shardy muzyki
- podzielone fragmenty mediów audio/wideo oraz fragmenty muzyki filtrowane według providera
Dzięki temu zachowane jest to samo pokrycie plików, a powolne awarie providerów live są łatwiejsze do ponownego uruchomienia i diagnozowania. Nazwy agregatów shardów `native-live-extensions-o-z`, `native-live-extensions-media` i `native-live-extensions-media-music` pozostają prawidłowe dla ręcznych jednorazowych ponownych uruchomień.
Zachowuje to to samo pokrycie plików, jednocześnie ułatwiając ponowne uruchamianie i diagnozowanie wolnych awarii providerów live. Nazwy zagregowanych fragmentów `native-live-extensions-o-z`, `native-live-extensions-media` i `native-live-extensions-media-music` pozostają poprawne dla ręcznych jednorazowych ponownych uruchomień.
Natywne shardy mediów live działają w `ghcr.io/openclaw/openclaw-live-media-runner:ubuntu-24.04`, zbudowanym przez workflow `Live Media Runner Image`. Ten obraz wstępnie instaluje `ffmpeg` i `ffprobe`; zadania mediów tylko weryfikują pliki binarne przed konfiguracją. Utrzymuj zestawy live oparte na Docker na zwykłych runnerach Blacksmith — zadania kontenerowe są niewłaściwym miejscem do uruchamiania zagnieżdżonych testów Docker.
Natywne fragmenty mediów live działają w `ghcr.io/openclaw/openclaw-live-media-runner:ubuntu-24.04`, zbudowanym przez workflow `Live Media Runner Image`. Ten obraz wstępnie instaluje `ffmpeg` i `ffprobe`; zadania mediów przed konfiguracją tylko weryfikują binaria. Zachowaj zestawy live oparte na Docker na zwykłych runnerach Blacksmith — zadania kontenerowe nie są właściwym miejscem do uruchamiania zagnieżdżonych testów Docker.
Shardy modeli/backendów live oparte na Docker używają oddzielnego współdzielonego obrazu `ghcr.io/openclaw/openclaw-live-test:<sha>` dla wybranego commita. Workflow wydania live buduje i wypycha ten obraz raz, a następnie shardy modelu live Docker, Gateway, backendu CLI, wiązania ACP i harnessa Codex działają z `OPENCLAW_SKIP_DOCKER_BUILD=1`. Jeśli te shardy niezależnie przebudowują pełny cel źródłowy Docker, uruchomienie wydania jest błędnie skonfigurowane i zmarnuje czas zegarowy na duplikaty kompilacji obrazów.
Fragmenty modeli/backendów live oparte na Docker używają oddzielnego współdzielonego obrazu `ghcr.io/openclaw/openclaw-live-test:<sha>` dla wybranego commita. Workflow wydania live buduje i wypycha ten obraz raz, a następnie fragmenty modelu live Docker, Gateway podzielony według providerów, backend CLI, powiązanie ACP oraz harness Codex działają z `OPENCLAW_SKIP_DOCKER_BUILD=1`. Fragmenty Gateway Docker mają jawne limity `timeout` na poziomie skryptu poniżej limitu czasu zadania workflow, aby zablokowany kontener lub ścieżka sprzątania szybko zakończyły się niepowodzeniem zamiast zużywać cały budżet release-check. Jeśli te fragmenty niezależnie przebudowują pełny docelowy obraz Docker źródeł, uruchomienie wydania jest błędnie skonfigurowane i zmarnuje czas na zegarze na zduplikowane kompilacje obrazów.
## Akceptacja pakietu
## Package Acceptance
Użyj `Package Acceptance`, gdy pytanie brzmi: „czy ten instalowalny pakiet OpenClaw działa jako produkt?”. Różni się to od zwykłego CI: zwykłe CI waliduje drzewo źródeł, podczas gdy akceptacja pakietu waliduje pojedynczy tarball przez ten sam harness Docker E2E, którego użytkownicy używają po instalacji lub aktualizacji.
Użyj `Package Acceptance`, gdy pytanie brzmi: „czy ten instalowalny pakiet OpenClaw działa jako produkt?”. Różni się to od zwykłego CI: zwykłe CI waliduje drzewo źródeł, podczas gdy package acceptance waliduje pojedynczy tarball przez ten sam harness Docker E2E, którego użytkownicy używają po instalacji lub aktualizacji.
### Zadania
1. `resolve_package` pobiera `workflow_ref`, rozwiązuje jednego kandydata pakietu, zapisuje `.artifacts/docker-e2e-package/openclaw-current.tgz`, zapisuje `.artifacts/docker-e2e-package/package-candidate.json`, przesyła oba jako artefakt `package-under-test` oraz wypisuje źródło, odniesienie workflow, odniesienie pakietu, wersję, SHA-256 i profil w podsumowaniu kroku GitHub.
2. `docker_acceptance` wywołuje `openclaw-live-and-e2e-checks-reusable.yml` z `ref=workflow_ref` i `package_artifact_name=package-under-test`. Workflow wielokrotnego użytku pobiera ten artefakt, waliduje inwentarz tarballa, przygotowuje obrazy Docker z digestem pakietu, gdy są potrzebne, i uruchamia wybrane ścieżki Docker względem tego pakietu zamiast pakować checkout workflow. Gdy profil wybiera wiele ukierunkowanych `docker_lanes`, workflow wielokrotnego użytku przygotowuje pakiet i współdzielone obrazy raz, a następnie rozdziela te ścieżki jako równoległe ukierunkowane zadania Docker z unikalnymi artefaktami.
3. `package_telegram` opcjonalnie wywołuje `NPM Telegram Beta E2E`. Działa, gdy `telegram_mode` nie jest `none`, i instaluje ten sam artefakt `package-under-test`, gdy Package Acceptance rozwiązało jeden; samodzielne uruchomienie Telegram nadal może zainstalować opublikowaną specyfikację npm.
4. `summary` powoduje niepowodzenie workflow, jeśli rozwiązanie pakietu, akceptacja Docker albo opcjonalna ścieżka Telegram zakończyły się niepowodzeniem.
1. `resolve_package` pobiera `workflow_ref`, rozwiązuje jednego kandydata pakietu, zapisuje `.artifacts/docker-e2e-package/openclaw-current.tgz`, zapisuje `.artifacts/docker-e2e-package/package-candidate.json`, przesyła oba jako artefakt `package-under-test` oraz wypisuje źródło, ref workflow, ref pakietu, wersję, SHA-256 i profil w podsumowaniu kroku GitHub.
2. `docker_acceptance` wywołuje `openclaw-live-and-e2e-checks-reusable.yml` z `ref=workflow_ref` i `package_artifact_name=package-under-test`. Wielokrotnie używany workflow pobiera ten artefakt, weryfikuje inwentarz archiwum tar, przygotowuje obrazy Docker z digestem pakietu, gdy jest to potrzebne, i uruchamia wybrane ścieżki Docker względem tego pakietu zamiast pakować checkout workflow. Gdy profil wybiera wiele docelowych `docker_lanes`, wielokrotnie używany workflow przygotowuje pakiet i obrazy współdzielone raz, a następnie rozdziela te ścieżki jako równoległe docelowe zadania Docker z unikalnymi artefaktami.
3. `package_telegram` opcjonalnie wywołuje `NPM Telegram Beta E2E`. Uruchamia się, gdy `telegram_mode` nie jest `none`, i instaluje ten sam artefakt `package-under-test`, gdy Package Acceptance rozwiązał pakiet; samodzielne wywołanie Telegram nadal może instalować opublikowaną specyfikację npm.
4. `summary` kończy workflow niepowodzeniem, jeśli rozwiązanie pakietu, akceptacja Docker albo opcjonalna ścieżka Telegram zakończyły się niepowodzeniem.
### Źródła kandydatów
- `source=npm` akceptuje tylko `openclaw@beta`, `openclaw@latest` albo dokładną wersję wydania OpenClaw, taką jak `openclaw@2026.4.27-beta.2`. Używaj tego do akceptacji opublikowanych wersji beta/stabilnych.
- `source=ref` pakuje zaufaną gałąź, tag albo pełny SHA commita `package_ref`. Resolver pobiera gałęzie/tagi OpenClaw, sprawdza, czy wybrany commit jest osiągalny z historii gałęzi repozytorium albo z tagu wydania, instaluje zależności w odłączonym worktree i pakuje go za pomocą `scripts/package-openclaw-for-docker.mjs`.
- `source=npm` akceptuje tylko `openclaw@beta`, `openclaw@latest` albo dokładną wersję wydania OpenClaw, taką jak `openclaw@2026.4.27-beta.2`. Użyj tego do akceptacji opublikowanej wersji beta/stabilnej.
- `source=ref` pakuje zaufaną gałąź, tag albo pełny SHA commita `package_ref`. Resolver pobiera gałęzie/tagi OpenClaw, weryfikuje, że wybrany commit jest osiągalny z historii gałęzi repozytorium albo tagu wydania, instaluje zależności w odłączonym worktree i pakuje go za pomocą `scripts/package-openclaw-for-docker.mjs`.
- `source=url` pobiera HTTPS `.tgz`; `package_sha256` jest wymagane.
- `source=artifact` pobiera jeden `.tgz` z `artifact_run_id` i `artifact_name`; `package_sha256` jest opcjonalne, ale powinno być podane dla artefaktów udostępnianych zewnętrznie.
Trzymaj `workflow_ref` i `package_ref` oddzielnie. `workflow_ref` to zaufany kod workflow/harnessu, który uruchamia test. `package_ref` to commit źródłowy pakowany, gdy `source=ref`. Dzięki temu bieżący harness testowy może weryfikować starsze zaufane commity źródłowe bez uruchamiania starej logiki workflow.
Trzymaj `workflow_ref` i `package_ref` osobno. `workflow_ref` to zaufany kod workflow/harnessa, który uruchamia test. `package_ref` to commit źródłowy, który zostaje spakowany, gdy `source=ref`. Dzięki temu bieżący harness testowy może weryfikować starsze zaufane commity źródłowe bez uruchamiania starej logiki workflow.
### Profile zestawu
### Profile zestawów
- `smoke` — `npm-onboard-channel-agent`, `gateway-network`, `config-reload`
- `package` — `npm-onboard-channel-agent`, `doctor-switch`, `update-channel-switch`, `upgrade-survivor`, `bundled-channel-deps-compat`, `plugins-offline`, `plugin-update`
- `package` — `npm-onboard-channel-agent`, `doctor-switch`, `update-channel-switch`, `upgrade-survivor`, `published-upgrade-survivor`, `bundled-channel-deps-compat`, `plugins-offline`, `plugin-update`
- `product` — `package` plus `mcp-channels`, `cron-mcp-cleanup`, `openai-web-search-minimal`, `openwebui`
- `full` — pełne fragmenty ścieżki wydania Docker z OpenWebUI
- `custom` — dokładne `docker_lanes`; wymagane, gdy `suite_profile=custom`
Profil `package` używa offline pokrycia pluginów, aby walidacja opublikowanego pakietu nie zależała od dostępności ClawHub na żywo. Opcjonalna ścieżka Telegram ponownie używa artefaktu `package-under-test` w `NPM Telegram Beta E2E`, z zachowaną ścieżką specyfikacji opublikowanego npm dla samodzielnych uruchomień.
Profil `package` używa pokrycia Plugin w trybie offline, aby walidacja opublikowanego pakietu nie była uzależniona od dostępności ClawHub na żywo. Opcjonalna ścieżka Telegram ponownie używa artefaktu `package-under-test` w `NPM Telegram Beta E2E`, zachowując ścieżkę opublikowanej specyfikacji npm dla samodzielnych wywołań.
Kontrole wydania wywołują Package Acceptance z `source=ref`, `package_ref=<release-ref>`, `workflow_ref=<release workflow ref>`, `suite_profile=custom`, `docker_lanes='bundled-channel-deps-compat plugins-offline'` oraz `telegram_mode=mock-openai`. Fragmenty Docker ścieżki wydania pokrywają nakładające się ścieżki pakietu/aktualizacji/pluginów; Package Acceptance utrzymuje natywny dla artefaktu dowód zgodności bundled-channel, pluginów offline oraz Telegram względem tego samego rozwiązanego tarballa pakietu. Kontrole wydań między systemami operacyjnymi nadal obejmują specyficzne dla OS zachowanie onboardingu, instalatora i platformy; walidację produktu pakietu/aktualizacji należy zaczynać od Package Acceptance. Ścieżki świeżego pakietu i instalatora Windows sprawdzają także, czy zainstalowany pakiet może zaimportować nadpisanie browser-control z surowej bezwzględnej ścieżki Windows. Smoke między systemami operacyjnymi dla tury agenta OpenAI domyślnie używa `OPENCLAW_CROSS_OS_OPENAI_MODEL`, gdy jest ustawione, w przeciwnym razie `openai/gpt-5.4-mini`, aby dowód instalacji i Gateway pozostał szybki oraz deterministyczny.
Kontrole wydania wywołują Package Acceptance z `source=ref`, `package_ref=<release-ref>`, `workflow_ref=<release workflow ref>`, `suite_profile=custom`, `docker_lanes='bundled-channel-deps-compat plugins-offline'` i `telegram_mode=mock-openai`. Fragmenty Docker ścieżki wydania obejmują nakładające się ścieżki pakietu/aktualizacji/Plugin; Package Acceptance zachowuje natywny dla artefaktu dowód kompatybilności dołączonych kanałów, offline Plugin i Telegram względem tego samego rozwiązanego archiwum tar pakietu. Kontrole wydania Cross-OS nadal obejmują specyficzne dla systemu operacyjnego wdrażanie, instalator i zachowanie platformy; walidacja produktu pakietu/aktualizacji powinna zaczynać się od Package Acceptance. Ścieżka Docker `published-upgrade-survivor` waliduje jedną opublikowaną bazę pakietu na uruchomienie. W Package Acceptance rozwiązane archiwum tar `package-under-test` zawsze jest kandydatem, a `published_upgrade_survivor_baseline` wybiera zastępczą opublikowaną bazę, domyślnie `openclaw@latest`; polecenia ponownego uruchomienia nieudanej ścieżki zachowują tę bazę. Ustaw `published_upgrade_survivor_baselines=release-history`, aby rozszerzyć ścieżkę na zdeduplikowaną macierz historii: sześć najnowszych wydań stabilnych, `2026.4.23` oraz najnowsze wydanie stabilne sprzed `2026-03-15`. Ustaw `published_upgrade_survivor_scenarios=reported-issues`, aby rozszerzyć te same bazy na fixtures ukształtowane jak zgłoszenia dla konfiguracji/runtime-deps Feishu, zachowanych plików bootstrap/persona, ścieżek logów z tyldą i nieaktualnych katalogów głównych wersjonowanych runtime-deps. Lokalne uruchomienia agregujące mogą przekazywać dokładne specyfikacje pakietów przez `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPECS`, zachować pojedynczą ścieżkę przez `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPEC`, taką jak `openclaw@2026.4.15`, albo ustawić `OPENCLAW_UPGRADE_SURVIVOR_SCENARIOS` dla macierzy scenariuszy. Opublikowana ścieżka konfiguruje bazę za pomocą wbudowanej receptury polecenia `openclaw config set`, zapisuje kroki receptury w `summary.json` i sonduje `/healthz`, `/readyz` oraz status RPC po uruchomieniu Gateway. Świeże ścieżki pakietu i instalatora Windows także weryfikują, że zainstalowany pakiet może zaimportować nadpisanie browser-control z surowej bezwzględnej ścieżki Windows. Smoke między systemami operacyjnymi dla tury agenta OpenAI domyślnie używa `OPENCLAW_CROSS_OS_OPENAI_MODEL`, gdy jest ustawione, w przeciwnym razie `openai/gpt-5.4-mini`, dzięki czemu dowód instalacji i Gateway pozostaje szybki i deterministyczny.
### Okna zgodności ze starszymi wersjami
Package Acceptance ma ograniczone okna zgodności ze starszymi wersjami dla już opublikowanych pakietów. Pakiety do `2026.4.25` włącznie, w tym `2026.4.25-beta.*`, mogą używać ścieżki zgodności:
- znane prywatne wpisy QA w `dist/postinstall-inventory.json` mogą wskazywać pliki pominięte w tarballu;
- znane prywatne wpisy QA w `dist/postinstall-inventory.json` mogą wskazywać pliki pominięte w archiwum tar;
- `doctor-switch` może pominąć podprzypadek utrwalania `gateway install --wrapper`, gdy pakiet nie udostępnia tej flagi;
- `update-channel-switch` może przyciąć brakujące `pnpm.patchedDependencies` z fałszywego fixture git pochodzącego z tarballa i może logować brakujące utrwalone `update.channel`;
- smoke testy pluginów mogą czytać starsze lokalizacje rekordów instalacji albo akceptować brak utrwalenia rekordu instalacji z marketplace;
- `plugin-update` może zezwolić na migrację metadanych konfiguracji, nadal wymagając, aby rekord instalacji i zachowanie bez ponownej instalacji pozostały niezmienione.
- `update-channel-switch` może usuwać brakujące `pnpm.patchedDependencies` z fałszywego fixture git pochodzącego z archiwum tar i może logować brak utrwalonego `update.channel`;
- testy smoke Plugin mogą odczytywać starsze lokalizacje rekordów instalacji albo akceptować brak utrwalenia rekordu instalacji marketplace;
- `plugin-update` może dopuścić migrację metadanych konfiguracji, nadal wymagając, aby rekord instalacji i zachowanie bez ponownej instalacji pozostały niezmienione.
Opublikowany pakiet `2026.4.26` może także ostrzegać o plikach stempli metadanych lokalnego builda, które zostały już dostarczone. Późniejsze pakiety muszą spełniać nowoczesne kontrakty; te same warunki powodują błąd zamiast ostrzeżenia albo pominięcia.
Opublikowany pakiet `2026.4.26` może także ostrzegać o plikach znaczników metadanych lokalnego buildu, które zostały już wysłane. Późniejsze pakiety muszą spełniać nowoczesne kontrakty; te same warunki powodują błąd zamiast ostrzeżenia albo pominięcia.
### Przykłady
@ -238,152 +248,152 @@ gh workflow run package-acceptance.yml \
-f docker_lanes='install-e2e plugin-update'
```
Podczas debugowania nieudanego uruchomienia akceptacji pakietu zacznij od podsumowania `resolve_package`, aby potwierdzić źródło pakietu, wersję i SHA-256. Następnie sprawdź uruchomienie potomne `docker_acceptance` i jego artefakty Docker: `.artifacts/docker-tests/**/summary.json`, `failures.json`, logi ścieżek, czasy faz i polecenia ponownego uruchomienia. Preferuj ponowne uruchomienie nieudanego profilu pakietu albo dokładnych ścieżek Docker zamiast ponownego uruchamiania pełnej walidacji wydania.
Podczas debugowania nieudanego uruchomienia akceptacji pakietu zacznij od podsumowania `resolve_package`, aby potwierdzić źródło pakietu, wersję i SHA-256. Następnie sprawdź uruchomienie podrzędne `docker_acceptance` i jego artefakty Docker: `.artifacts/docker-tests/**/summary.json`, `failures.json`, logi ścieżek, czasy faz i polecenia ponownego uruchomienia. Preferuj ponowne uruchomienie nieudanego profilu pakietu albo dokładnych ścieżek Docker zamiast ponownego uruchamiania pełnej walidacji wydania.
## Smoke instalacji
Oddzielny workflow `Install Smoke` ponownie używa tego samego skryptu zakresu przez własne zadanie `preflight`. Dzieli pokrycie smoke na `run_fast_install_smoke` i `run_full_install_smoke`.
Osobny workflow `Install Smoke` ponownie używa tego samego skryptu zakresu przez własne zadanie `preflight`. Dzieli pokrycie smoke na `run_fast_install_smoke` i `run_full_install_smoke`.
- **Szybka ścieżka** uruchamia się dla pull requestów dotykających powierzchni Docker/pakietu, zmian pakietu/manifestu bundled pluginów albo powierzchni core plugin/channel/gateway/Plugin SDK, które wykonują zadania smoke Docker. Zmiany wyłącznie źródłowe w bundled pluginach, edycje tylko testów i edycje tylko dokumentacji nie rezerwują workerów Docker. Szybka ścieżka buduje obraz głównego Dockerfile raz, sprawdza CLI, uruchamia smoke CLI usuwania współdzielonego workspace agentów, uruchamia kontenerowy e2e gateway-network, weryfikuje argument builda bundled extension i uruchamia ograniczony profil Docker bundled-plugin w ramach 240-sekundowego łącznego limitu czasu polecenia (każde uruchomienie Docker scenariusza jest ograniczone osobno).
- **Pełna ścieżka** zachowuje instalację pakietu QR oraz pokrycie Docker instalatora/aktualizacji dla nocnych uruchomień harmonogramu, ręcznych uruchomień, kontroli wydań przez workflow-call i pull requestów, które faktycznie dotykają powierzchni instalatora/pakietu/Docker. W trybie pełnym install-smoke przygotowuje albo ponownie używa jednego obrazu smoke GHCR głównego Dockerfile dla docelowego SHA, a następnie uruchamia instalację pakietu QR, smoke testy głównego Dockerfile/Gateway, smoke testy instalatora/aktualizacji oraz szybkie Docker E2E bundled-plugin jako osobne zadania, aby praca instalatora nie czekała za smoke testami obrazu głównego.
- **Szybka ścieżka** działa dla pull requestów dotykających powierzchni Docker/pakietu, zmian pakietów/manifestów dołączonych Plugin albo powierzchni rdzeniowego Plugin/kanału/gateway/Plugin SDK, które ćwiczą zadania smoke Docker. Zmiany wyłącznie w źródłach dołączonych Plugin, edycje wyłącznie testów i edycje wyłącznie dokumentacji nie rezerwują workerów Docker. Szybka ścieżka buduje obraz głównego Dockerfile raz, sprawdza CLI, uruchamia smoke CLI usuwania agentów ze współdzielonego workspace, uruchamia kontenerowe e2e gateway-network, weryfikuje argument buildu dołączonego rozszerzenia i uruchamia ograniczony profil Docker dołączonego Plugin z 240-sekundowym łącznym limitem czasu polecenia (każde uruchomienie Docker scenariusza jest ograniczone osobno).
- **Pełna ścieżka** zachowuje instalację pakietu QR oraz pokrycie Docker/aktualizacji instalatora dla nocnych uruchomień według harmonogramu, wywołań ręcznych, kontroli wydania przez workflow-call i pull requestów, które faktycznie dotykają powierzchni instalatora/pakietu/Docker. W trybie pełnym install-smoke przygotowuje albo ponownie używa jednego obrazu smoke GHCR głównego Dockerfile dla docelowego SHA, a następnie uruchamia instalację pakietu QR, smoke głównego Dockerfile/Gateway, smoke instalatora/aktualizacji i szybkie Docker E2E dołączonego Plugin jako osobne zadania, aby praca instalatora nie czekała za smoke głównego obrazu.
Push’e do `main` (w tym commity merge) nie wymuszają pełnej ścieżki; gdy logika zakresu zmian zażądałaby pełnego pokrycia przy pushu, workflow zachowuje szybki smoke Docker i pozostawia pełny install smoke walidacji nocnej albo wydaniowej.
Wypchnięcia do `main` (w tym commity scalające) nie wymuszają pełnej ścieżki; gdy logika zakresu zmian zażądałaby pełnego pokrycia przy pushu, workflow zachowuje szybki smoke Docker i zostawia pełny smoke instalacji walidacji nocnej albo wydania.
Wolny smoke globalnej instalacji Bun dla image-provider jest osobno bramkowany przez `run_bun_global_install_smoke`. Uruchamia się w nocnym harmonogramie i z workflow kontroli wydań, a ręczne uruchomienia `Install Smoke` mogą go włączyć, ale pull requesty i push’e do `main` nie. Testy Docker QR i instalatora zachowują własne instalacyjne Dockerfile.
Wolny smoke dostawcy obrazu dla globalnej instalacji Bun jest osobno bramkowany przez `run_bun_global_install_smoke`. Uruchamia się w nocnym harmonogramie i z workflow kontroli wydania, a ręczne wywołania `Install Smoke` mogą go włączyć, ale pull requesty i wypchnięcia do `main` tego nie robią. Testy Docker QR i instalatora zachowują własne Dockerfile skupione na instalacji.
## Lokalne Docker E2E
`pnpm test:docker:all` prebuduje jeden współdzielony obraz live-test, pakuje OpenClaw raz jako tarball npm i buduje dwa współdzielone obrazy `scripts/e2e/Dockerfile`:
`pnpm test:docker:all` buduje z wyprzedzeniem jeden współdzielony obraz live-test, pakuje OpenClaw raz jako archiwum tar npm i buduje dwa współdzielone obrazy `scripts/e2e/Dockerfile`:
- surowy runner Node/Git dla ścieżek instalatora/aktualizacji/zależności pluginów;
- funkcjonalny obraz, który instaluje ten sam tarball do `/app` dla normalnych ścieżek funkcjonalnych.
- czysty runner Node/Git dla ścieżek instalatora/aktualizacji/zależności Plugin;
- funkcjonalny obraz, który instaluje to samo archiwum tar w `/app` dla normalnych ścieżek funkcjonalności.
Definicje ścieżek Docker znajdują się w `scripts/lib/docker-e2e-scenarios.mjs`, logika planera w `scripts/lib/docker-e2e-plan.mjs`, a runner wykonuje tylko wybrany plan. Scheduler wybiera obraz dla ścieżki za pomocą `OPENCLAW_DOCKER_E2E_BARE_IMAGE` i `OPENCLAW_DOCKER_E2E_FUNCTIONAL_IMAGE`, a następnie uruchamia ścieżki z `OPENCLAW_SKIP_DOCKER_BUILD=1`.
Definicje ścieżek Docker znajdują się w `scripts/lib/docker-e2e-scenarios.mjs`, logika planera znajduje się w `scripts/lib/docker-e2e-plan.mjs`, a runner wykonuje tylko wybrany plan. Scheduler wybiera obraz dla każdej ścieżki za pomocą `OPENCLAW_DOCKER_E2E_BARE_IMAGE` i `OPENCLAW_DOCKER_E2E_FUNCTIONAL_IMAGE`, a następnie uruchamia ścieżki z `OPENCLAW_SKIP_DOCKER_BUILD=1`.
### Parametry dostrajania
### Parametry do dostrojenia
| Variable | Default | Purpose |
| -------------------------------------- | ------- | --------------------------------------------------------------------------------------------- |
| `OPENCLAW_DOCKER_ALL_PARALLELISM` | 10 | Liczba slotów puli głównej dla normalnych ścieżek. |
| `OPENCLAW_DOCKER_ALL_TAIL_PARALLELISM` | 10 | Liczba slotów puli końcowej wrażliwej na dostawców. |
| `OPENCLAW_DOCKER_ALL_LIVE_LIMIT` | 9 | Limit równoczesnych ścieżek live, aby dostawcy nie throttlowali. |
| `OPENCLAW_DOCKER_ALL_NPM_LIMIT` | 10 | Limit równoczesnych ścieżek instalacji npm. |
| `OPENCLAW_DOCKER_ALL_SERVICE_LIMIT` | 7 | Limit równoczesnych ścieżek wielousługowych. |
| `OPENCLAW_DOCKER_ALL_START_STAGGER_MS` | 2000 | Odstęp między startami ścieżek, aby uniknąć burz tworzenia w daemonie Docker; ustaw `0`, aby wyłączyć odstęp. |
| `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS` | 7200000 | Zapasowy limit czasu na ścieżkę (120 minut); wybrane ścieżki live/tail używają ciaśniejszych limitów. |
| `OPENCLAW_DOCKER_ALL_DRY_RUN` | unset | `1` wypisuje plan schedulera bez uruchamiania ścieżek. |
| `OPENCLAW_DOCKER_ALL_LANES` | unset | Rozdzielona przecinkami dokładna lista ścieżek; pomija cleanup smoke, aby agenci mogli odtworzyć jedną nieudaną ścieżkę. |
| Zmienna | Domyślna | Cel |
| -------------------------------------- | -------- | ------------------------------------------------------------------------------------------------- |
| `OPENCLAW_DOCKER_ALL_PARALLELISM` | 10 | Liczba slotów głównej puli dla zwykłych ścieżek. |
| `OPENCLAW_DOCKER_ALL_TAIL_PARALLELISM` | 10 | Liczba slotów puli końcowej wrażliwej na dostawców. |
| `OPENCLAW_DOCKER_ALL_LIVE_LIMIT` | 9 | Limit współbieżnych ścieżek live, aby dostawcy nie ograniczali przepustowości. |
| `OPENCLAW_DOCKER_ALL_NPM_LIMIT` | 10 | Limit współbieżnych ścieżek instalacji npm. |
| `OPENCLAW_DOCKER_ALL_SERVICE_LIMIT` | 7 | Limit współbieżnych ścieżek z wieloma usługami. |
| `OPENCLAW_DOCKER_ALL_START_STAGGER_MS` | 2000 | Odstęp między startami ścieżek, aby uniknąć burz tworzenia w demonie Docker; ustaw `0`, aby go wyłączyć. |
| `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS` | 7200000 | Awaryjny limit czasu dla każdej ścieżki (120 minut); wybrane ścieżki live/końcowe używają ciaśniejszych limitów. |
| `OPENCLAW_DOCKER_ALL_DRY_RUN` | unset | `1` wypisuje plan harmonogramu bez uruchamiania ścieżek. |
| `OPENCLAW_DOCKER_ALL_LANES` | unset | Dokładna lista ścieżek rozdzielona przecinkami; pomija smoke cleanup, aby agenci mogli odtworzyć jedną nieudaną ścieżkę. |
Ścieżka cięższa niż jej efektywny limit może nadal wystartować z pustej puli, a następnie działa sama, dopóki nie zwolni pojemności. Lokalny agregat wykonuje preflight Docker, usuwa przestarzałe kontenery OpenClaw E2E, emituje status aktywnych ścieżek, utrwala czasy ścieżek dla kolejności od najdłuższych i domyślnie przestaje planować nowe ścieżki z puli po pierwszym błędzie.
Ścieżka cięższa niż jej efektywny limit nadal może wystartować z pustej puli, a następnie działa sama, dopóki nie zwolni pojemności. Lokalny agregat wstępnie sprawdza Docker, usuwa przestarzałe kontenery OpenClaw E2E, emituje status aktywnej ścieżki, utrwala czasy ścieżek na potrzeby kolejności od najdłuższych oraz domyślnie zatrzymuje planowanie nowych ścieżek z puli po pierwszym niepowodzeniu.
### Wielokrotnego użytku workflow live/E2E
Wielokrotnego użytku workflow live/E2E pyta `scripts/test-docker-all.mjs --plan-json`, jaki pakiet, rodzaj obrazu, obraz live, ścieżka i pokrycie poświadczeń są wymagane. `scripts/docker-e2e.mjs` następnie konwertuje ten plan na wyjścia i podsumowania GitHub. Albo pakuje OpenClaw przez `scripts/package-openclaw-for-docker.mjs`, pobiera artefakt pakietu z bieżącego uruchomienia, albo pobiera artefakt pakietu z `package_artifact_run_id`; waliduje inventory tarballa; buduje i wypycha tagowane digestem pakietu obrazy bare/functional GHCR Docker E2E przez cache warstw Docker Blacksmith, gdy plan potrzebuje ścieżek z zainstalowanym pakietem; oraz ponownie używa podanych wejść `docker_e2e_bare_image`/`docker_e2e_functional_image` albo istniejących obrazów z digestem pakietu zamiast przebudowywać. Pobrania obrazów Docker są ponawiane z ograniczonym 180-sekundowym limitem czasu na próbę, aby zablokowany strumień registry/cache szybko ponowił próbę zamiast zużywać większość ścieżki krytycznej CI.
Wielokrotnego użytku workflow live/E2E pyta `scripts/test-docker-all.mjs --plan-json`, jaki pakiet, rodzaj obrazu, obraz live, ścieżka i pokrycie poświadczeń są wymagane. `scripts/docker-e2e.mjs` następnie konwertuje ten plan na wyjścia i podsumowania GitHub. Albo pakuje OpenClaw przez `scripts/package-openclaw-for-docker.mjs`, pobiera artefakt pakietu z bieżącego przebiegu albo pobiera artefakt pakietu z `package_artifact_run_id`; weryfikuje inwentarz archiwum tar; buduje i wypycha oznaczone skrótem pakietu obrazy bare/functional GHCR Docker E2E przez cache warstw Docker Blacksmith, gdy plan wymaga ścieżek z zainstalowanym pakietem; oraz ponownie używa podanych wejść `docker_e2e_bare_image`/`docker_e2e_functional_image` albo istniejących obrazów ze skrótem pakietu zamiast przebudowywać. Pobieranie obrazów Docker jest ponawiane z ograniczonym limitem 180 sekund na próbę, aby zablokowany strumień rejestru/cache szybko ponowił próbę zamiast zużywać większość krytycznej ścieżki CI.
### Fragmenty ścieżki wydania
Pokrycie Docker wydania uruchamia mniejsze fragmentowane zadania z `OPENCLAW_SKIP_DOCKER_BUILD=1`, aby każdy fragment pobierał tylko potrzebny rodzaj obrazu i wykonywał wiele ścieżek przez ten sam ważony scheduler:
Pokrycie Docker dla wydania uruchamia mniejsze zadania podzielone na fragmenty z `OPENCLAW_SKIP_DOCKER_BUILD=1`, więc każdy fragment pobiera tylko ten rodzaj obrazu, którego potrzebuje, i wykonuje wiele ścieżek przez ten sam ważony harmonogram:
- `OPENCLAW_DOCKER_ALL_PROFILE=release-path`
- `OPENCLAW_DOCKER_ALL_CHUNK=core | package-update-openai | package-update-anthropic | package-update-core | plugins-runtime-plugins | plugins-runtime-services | plugins-runtime-install-a..h | bundled-channels`
Obecne fragmenty Docker wydania to `core`, `package-update-openai`, `package-update-anthropic`, `package-update-core`, `plugins-runtime-plugins`, `plugins-runtime-services`, od `plugins-runtime-install-a` do `plugins-runtime-install-h`, `bundled-channels-core`, `bundled-channels-update-a`, `bundled-channels-update-discord`, `bundled-channels-update-b` oraz `bundled-channels-contracts`. Zbiorczy fragment `bundled-channels` pozostaje dostępny do ręcznych, jednorazowych ponowień, a `plugins-runtime-core`, `plugins-runtime` i `plugins-integrations` pozostają zbiorczymi aliasami Plugin/runtime. Alias pasa `install-e2e` pozostaje zbiorczym aliasem ręcznego ponowienia dla obu pasów instalatora dostawców. Fragment `bundled-channels` uruchamia podzielone pasy `bundled-channel-*` i `bundled-channel-update-*` zamiast szeregowego pasa all-in-one `bundled-channel-deps`.
Obecne fragmenty Docker dla wydania to `core`, `package-update-openai`, `package-update-anthropic`, `package-update-core`, `plugins-runtime-plugins`, `plugins-runtime-services`, `plugins-runtime-install-a` do `plugins-runtime-install-h`, `bundled-channels-core`, `bundled-channels-update-a`, `bundled-channels-update-discord`, `bundled-channels-update-b` i `bundled-channels-contracts`. Agregujący fragment `bundled-channels` pozostaje dostępny do ręcznych jednorazowych ponownych uruchomień, a `plugins-runtime-core`, `plugins-runtime` i `plugins-integrations` pozostają agregującymi aliasami plugin/runtime. Alias ścieżki `install-e2e` pozostaje agregującym aliasem ręcznego ponownego uruchomienia dla obu ścieżek instalatora dostawców. Fragment `bundled-channels` uruchamia podzielone ścieżki `bundled-channel-*` i `bundled-channel-update-*` zamiast sekwencyjnej, wszystko-w-jednym ścieżki `bundled-channel-deps`.
OpenWebUI jest włączany do `plugins-runtime-services`, gdy wymaga tego pełne pokrycie ścieżki wydania, i zachowuje samodzielny fragment `openwebui` tylko dla wywołań dotyczących wyłącznie OpenWebUI. Pasy aktualizacji kanałów wbudowanych ponawiają próbę raz w przypadku przejściowych awarii sieci npm.
OpenWebUI jest składany do `plugins-runtime-services`, gdy wymaga tego pełne pokrycie ścieżki wydania, i zachowuje samodzielny fragment `openwebui` tylko dla wywołań dotyczących wyłącznie OpenWebUI. Ścieżki aktualizacji kanałów wbudowanych ponawiają raz próbę w przypadku przejściowych awarii sieci npm.
Każdy fragment przesyła `.artifacts/docker-tests/` z logami pasów, czasami, `summary.json`, `failures.json`, czasami faz, JSON planu harmonogramu, tabelami wolnych pasów i poleceniami ponownego uruchomienia dla poszczególnych pasów. Wejście workflow `docker_lanes` uruchamia wybrane pasy względem przygotowanych obrazów zamiast zadań fragmentów, co ogranicza debugowanie pasa z błędem do jednego docelowego zadania Docker i przygotowuje, pobiera lub ponownie wykorzystuje artefakt pakietu dla tego uruchomienia; jeśli wybrany pas jest pasem live Docker, docelowe zadanie buduje lokalnie obraz live-test dla tego ponowienia. Wygenerowane polecenia GitHub do ponowienia dla poszczególnych pasów zawierają `package_artifact_run_id`, `package_artifact_name` i wejścia przygotowanych obrazów, gdy te wartości istnieją, dzięki czemu pas z błędem może ponownie użyć dokładnie tego pakietu i tych obrazów z nieudanego uruchomienia.
Każdy fragment przesyła `.artifacts/docker-tests/` z logami ścieżek, czasami, `summary.json`, `failures.json`, czasami faz, JSON planu harmonogramu, tabelami wolnych ścieżek oraz poleceniami ponownego uruchomienia dla każdej ścieżki. Wejście workflow `docker_lanes` uruchamia wybrane ścieżki względem przygotowanych obrazów zamiast zadań fragmentów, co ogranicza debugowanie nieudanej ścieżki do jednego docelowego zadania Docker oraz przygotowuje, pobiera lub ponownie używa artefaktu pakietu dla tego przebiegu; jeśli wybrana ścieżka jest ścieżką live Docker, docelowe zadanie buduje lokalnie obraz testu live dla tego ponownego uruchomienia. Wygenerowane polecenia GitHub do ponownego uruchomienia dla każdej ścieżki zawierają `package_artifact_run_id`, `package_artifact_name` oraz wejścia przygotowanych obrazów, gdy te wartości istnieją, dzięki czemu nieudana ścieżka może ponownie użyć dokładnie tego pakietu i obrazów z nieudanego przebiegu.
```bash
pnpm test:docker:rerun <run-id> # download Docker artifacts and print combined/per-lane targeted rerun commands
pnpm test:docker:timings <summary> # slow-lane and phase critical-path summaries
pnpm test:docker:rerun <run-id> # pobierz artefakty Docker i wypisz połączone/docelowe polecenia ponownego uruchomienia dla ścieżek
pnpm test:docker:timings <summary> # podsumowania wolnych ścieżek i krytycznej ścieżki faz
```
Zaplanowany workflow live/E2E codziennie uruchamia pełny zestaw Docker ścieżki wydania.
Zaplanowany workflow live/E2E uruchamia codziennie pełny zestaw Docker ścieżki wydania.
## Przedpremiera Plugin
## Przedpremierowa wersja Plugin
`Plugin Prerelease` zapewnia droższe pokrycie produktu/pakietu, dlatego jest osobnym workflow wywoływanym przez `Full Release Validation` albo jawnie przez operatora. Zwykłe pull requesty, wypchnięcia do `main` i samodzielne ręczne wywołania CI nie uruchamiają tego zestawu. Równoważy testy wbudowanych Plugin między ośmioma workerami rozszerzeń; te zadania shardów rozszerzeń uruchamiają do dwóch grup konfiguracji Plugin naraz, z jednym workerem Vitest na grupę i większą stertą Node, aby partie Plugin intensywnie używające importów nie tworzyły dodatkowych zadań CI.
`Plugin Prerelease` to droższe pokrycie produktu/pakietu, więc jest osobnym workflow uruchamianym przez `Full Release Validation` albo przez jawnego operatora. Zwykłe pull requesty, wypchnięcia do `main` i samodzielne ręczne uruchomienia CI utrzymują ten zestaw wyłączony. Równoważy testy wbudowanych pluginów między ośmiu pracowników rozszerzeń; te zadania shardów rozszerzeń uruchamiają do dwóch grup konfiguracji pluginów naraz, z jednym pracownikiem Vitest na grupę i większą stertą Node, aby partie pluginów ciężkie pod względem importów nie tworzyły dodatkowych zadań CI. Ścieżka przedpremierowa Docker tylko dla wydań grupuje docelowe ścieżki Docker w małe grupy, aby uniknąć rezerwowania dziesiątek runnerów dla zadań trwających od jednej do trzech minut.
## QA Lab
QA Lab ma dedykowane pasy CI poza głównym workflow o inteligentnym zakresie.
QA Lab ma dedykowane ścieżki CI poza głównym workflow z inteligentnym zakresem.
- Workflow `Parity gate` uruchamia się przy pasujących zmianach PR i ręcznym wywołaniu; buduje prywatny runtime QA i porównuje mockowe pakiety agentowe GPT-5.5 oraz Opus 4.6.
- Workflow `QA-Lab - All Lanes` uruchamia się co noc na `main` i przy ręcznym wywołaniu; rozdziela mockową bramkę parzystości, live pas Matrix oraz live pasy Telegram i Discord jako równoległe zadania. Zadania live używają środowiska `qa-live-shared`, a Telegram/Discord używają dzierżaw Convex.
- Workflow `Parity gate` działa przy pasujących zmianach PR i ręcznym uruchomieniu; buduje prywatne środowisko uruchomieniowe QA i porównuje agentowe pakiety mock GPT-5.5 oraz Opus 4.6.
- Workflow `QA-Lab - All Lanes` działa co noc na `main` i przy ręcznym uruchomieniu; rozdziela mock parity gate, ścieżkę live Matrix oraz ścieżki live Telegram i Discord jako równoległe zadania. Zadania live używają środowiska `qa-live-shared`, a Telegram/Discord używają dzierżaw Convex.
Kontrole wydania uruchamiają live pasy transportu Matrix i Telegram z deterministycznym mockowym dostawcą oraz modelami zakwalifikowanymi jako mock (`mock-openai/gpt-5.5` i `mock-openai/gpt-5.5-alt`), aby kontrakt kanału był odizolowany od opóźnień live modelu i normalnego uruchamiania provider-plugin. Live transport gateway wyłącza wyszukiwanie pamięci, ponieważ parzystość QA osobno obejmuje zachowanie pamięci; łączność dostawcy jest objęta osobnymi zestawami live model, native provider i Docker provider.
Kontrole wydania uruchamiają ścieżki live transportu Matrix i Telegram z deterministycznym dostawcą mock oraz modelami kwalifikowanymi jako mock (`mock-openai/gpt-5.5` i `mock-openai/gpt-5.5-alt`), dzięki czemu kontrakt kanału jest odizolowany od opóźnień modeli live i normalnego startu provider-plugin. Gateway transportu live wyłącza wyszukiwanie w pamięci, ponieważ parytet QA pokrywa zachowanie pamięci osobno; łączność dostawców jest pokryta przez osobne zestawy modeli live, natywnych dostawców i dostawców Docker.
Matrix używa `--profile fast` dla zaplanowanych bramek i bramek wydania, dodając `--fail-fast` tylko wtedy, gdy obsługuje to sprawdzony CLI. Domyślna wartość CLI i ręczne wejście workflow pozostają `all`; ręczne wywołanie `matrix_profile=all` zawsze dzieli pełne pokrycie Matrix na zadania `transport`, `media`, `e2ee-smoke`, `e2ee-deep` i `e2ee-cli`.
Matrix używa `--profile fast` dla zaplanowanych bramek i bramek wydania, dodając `--fail-fast` tylko wtedy, gdy wyewidencjonowane CLI to obsługuje. Domyślne CLI i ręczne wejście workflow pozostają `all`; ręczne uruchomienie `matrix_profile=all` zawsze dzieli pełne pokrycie Matrix na zadania `transport`, `media`, `e2ee-smoke`, `e2ee-deep` i `e2ee-cli`.
`OpenClaw Release Checks` uruchamia również krytyczne dla wydania pasy QA Lab przed zatwierdzeniem wydania; jego bramka parzystości QA uruchamia pakiety kandydata i bazowe jako równoległe zadania pasów, a następnie pobiera oba artefakty do małego zadania raportu na potrzeby końcowego porównania parzystości.
`OpenClaw Release Checks` uruchamia także krytyczne dla wydania ścieżki QA Lab przed zatwierdzeniem wydania; jego bramka parytetu QA uruchamia pakiety kandydata i bazowe jako równoległe zadania ścieżek, a następnie pobiera oba artefakty do małego zadania raportu na potrzeby końcowego porównania parytetu.
Nie umieszczaj ścieżki lądowania PR za `Parity gate`, chyba że zmiana rzeczywiście dotyka runtime QA, parzystości pakietów modeli albo powierzchni należącej do workflow parzystości. W przypadku zwykłych poprawek kanałów, konfiguracji, dokumentacji lub testów jednostkowych traktuj to jako opcjonalny sygnał i korzystaj z dowodów z właściwego zakresu CI/kontroli.
Nie umieszczaj ścieżki lądowania PR za `Parity gate`, chyba że zmiana faktycznie dotyka środowiska uruchomieniowego QA, parytetu pakietów modeli albo powierzchni, której właścicielem jest workflow parytetu. Dla zwykłych poprawek kanału, konfiguracji, dokumentacji lub testów jednostkowych traktuj to jako opcjonalny sygnał i korzystaj zamiast tego z dowodów z CI/kontroli o odpowiednim zakresie.
## CodeQL
Workflow `CodeQL` jest celowo wąskim skanerem bezpieczeństwa pierwszego przejścia, a nie pełnym przeglądem repozytorium. Codzienne, ręczne oraz ochronne uruchomienia dla pull requestów innych niż szkic skanują kod workflow Actions oraz powierzchnie JavaScript/TypeScript najwyższego ryzyka za pomocą zapytań bezpieczeństwa o wysokiej pewności, filtrowanych do `security-severity` high/critical.
Workflow `CodeQL` jest celowo wąskim skanerem bezpieczeństwa pierwszego przebiegu, a nie pełnym przeglądem repozytorium. Codzienne, ręczne i niebędące szkicami uruchomienia strażnika pull requestów skanują kod workflow Actions oraz powierzchnie JavaScript/TypeScript o najwyższym ryzyku za pomocą zapytań bezpieczeństwa o wysokiej pewności, filtrowanych do wysokiego/krytycznego `security-severity`.
Ochrona pull requestów pozostaje lekka: uruchamia się tylko dla zmian pod `.github/actions`, `.github/codeql`, `.github/workflows`, `packages` lub `src` i wykonuje tę samą macierz bezpieczeństwa o wysokiej pewności co zaplanowany workflow. Android i macOS CodeQL pozostają poza domyślnymi PR.
Strażnik pull requestów pozostaje lekki: startuje tylko dla zmian w `.github/actions`, `.github/codeql`, `.github/workflows`, `packages` lub `src` i uruchamia tę samą macierz bezpieczeństwa o wysokiej pewności co zaplanowany workflow. Android i macOS CodeQL pozostają poza domyślnymi ustawieniami PR.
### Kategorie bezpieczeństwa
| Kategoria | Powierzchnia |
| ------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `/codeql-security-high/core-auth-secrets` | Auth, sekrety, sandbox, cron i bazowy gateway |
| `/codeql-security-high/channel-runtime-boundary` | Kontrakty implementacji kanałów core oraz runtime Plugin kanału, gateway, Plugin SDK, sekrety, punkty styku audytu |
| `/codeql-security-high/core-auth-secrets` | Uwierzytelnianie, sekrety, sandbox, cron i bazowy gateway |
| `/codeql-security-high/channel-runtime-boundary` | Kontrakty implementacji kanału core oraz środowisko uruchomieniowe Plugin kanału, Gateway, Plugin SDK, sekrety, punkty styku audytu |
| `/codeql-security-high/network-ssrf-boundary` | Powierzchnie core SSRF, parsowania IP, ochrony sieci, web-fetch i polityki SSRF Plugin SDK |
| `/codeql-security-high/mcp-process-tool-boundary` | Serwery MCP, helpery wykonywania procesów, dostarczanie wychodzące i bramki wykonywania narzędzi agenta |
| `/codeql-security-high/plugin-trust-boundary` | Instalacja Plugin, loader, manifest, registry, etapowanie zależności runtime, ładowanie źródeł i powierzchnie zaufania kontraktu pakietu Plugin SDK |
| `/codeql-security-high/mcp-process-tool-boundary` | Serwery MCP, pomocniki wykonywania procesów, dostarczanie wychodzące i bramki wykonywania narzędzi agentów |
| `/codeql-security-high/plugin-trust-boundary` | Powierzchnie zaufania instalacji Plugin, loadera, manifestu, rejestru, przygotowania zależności uruchomieniowych, ładowania źródeł i kontraktu pakietu Plugin SDK |
### Shardy bezpieczeństwa specyficzne dla platform
- `CodeQL Android Critical Security` — zaplanowany shard bezpieczeństwa Android. Buduje aplikację Android ręcznie dla CodeQL na najmniejszym runnerze Blacksmith Linux akceptowanym przez workflow sanity. Przesyła pod `/codeql-critical-security/android`.
- `CodeQL macOS Critical Security` — tygodniowy/ręczny shard bezpieczeństwa macOS. Buduje aplikację macOS ręcznie dla CodeQL na Blacksmith macOS, odfiltrowuje wyniki budowania zależności z przesyłanego SARIF i przesyła pod `/codeql-critical-security/macos`. Utrzymywany poza codziennymi domyślnymi uruchomieniami, ponieważ budowanie macOS dominuje czas wykonania nawet przy czystym stanie.
- `CodeQL Android Critical Security` — zaplanowany shard bezpieczeństwa Android. Buduje aplikację Android ręcznie dla CodeQL na najmniejszym runnerze Blacksmith Linux akceptowanym przez sanity workflow. Przesyła pod `/codeql-critical-security/android`.
- `CodeQL macOS Critical Security` — tygodniowy/ręczny shard bezpieczeństwa macOS. Buduje aplikację macOS ręcznie dla CodeQL na Blacksmith macOS, odfiltrowuje wyniki budowania zależności z przesyłanego SARIF i przesyła pod `/codeql-critical-security/macos`. Utrzymywany poza codziennymi domyślnymi ustawieniami, ponieważ budowanie macOS dominuje czas wykonania nawet przy czystym przebiegu.
### Kategorie jakości krytycznej
### Kategorie krytycznej jakości
`CodeQL Critical Quality` to odpowiadający shard niezwiązany z bezpieczeństwem. Uruchamia tylko zapytania jakości JavaScript/TypeScript o poziomie błędu i niezwiązane z bezpieczeństwem, na wąskich powierzchniach o wysokiej wartości, na mniejszym runnerze Blacksmith Linux. Jego ochrona pull requestów jest celowo mniejsza niż profil zaplanowany: PR inne niż szkic uruchamiają tylko pasujące shardy `agent-runtime-boundary`, `config-boundary`, `core-auth-secrets`, `channel-runtime-boundary`, `gateway-runtime-boundary`, `memory-runtime-boundary`, `mcp-process-runtime-boundary`, `provider-runtime-boundary`, `session-diagnostics-boundary`, `plugin-boundary`, `plugin-sdk-package-contract` i `plugin-sdk-reply-runtime` dla zmian w kodzie poleceń/modeli/wykonywania narzędzi agenta i dyspozycji odpowiedzi, kodzie schematu/migracji/IO konfiguracji, kodzie auth/sekretów/sandboxu/bezpieczeństwa, core channel i runtime wbudowanych channel plugin, gateway protocol/server-method, runtime pamięci/spoiwie SDK, MCP/procesie/dostarczaniu wychodzącym, runtime dostawcy/katalogu modeli, diagnostyce sesji/kolejkach dostarczania, loaderze Plugin, Plugin SDK/kontrakcie pakietu albo runtime odpowiedzi Plugin SDK. Zmiany konfiguracji CodeQL i workflow jakości uruchamiają wszystkie dwanaście shardów jakości PR.
`CodeQL Critical Quality` to odpowiadający shard niezwiązany z bezpieczeństwem. Uruchamia tylko zapytania jakości JavaScript/TypeScript o poziomie błędu, niezwiązane z bezpieczeństwem, na wąskich powierzchniach o wysokiej wartości na mniejszym runnerze Blacksmith Linux. Jego strażnik pull requestów jest celowo mniejszy niż profil zaplanowany: PR-y niebędące szkicami uruchamiają tylko pasujące shardy `agent-runtime-boundary`, `config-boundary`, `core-auth-secrets`, `channel-runtime-boundary`, `gateway-runtime-boundary`, `memory-runtime-boundary`, `mcp-process-runtime-boundary`, `provider-runtime-boundary`, `session-diagnostics-boundary`, `plugin-boundary`, `plugin-sdk-package-contract` i `plugin-sdk-reply-runtime` dla zmian w kodzie wykonywania poleceń/modeli/narzędzi agentów i wysyłki odpowiedzi, schematu konfiguracji/migracji/IO, uwierzytelniania/sekretów/sandboxa/bezpieczeństwa, core channel i środowiska uruchomieniowego wbudowanego channel plugin, protokołu Gateway/metody serwera, środowiska uruchomieniowego pamięci/kleju SDK, MCP/procesu/dostarczania wychodzącego, środowiska uruchomieniowego dostawcy/katalogu modeli, diagnostyki sesji/kolejek dostarczania, loadera pluginów, kontraktu Plugin SDK/pakietu albo środowiska uruchomieniowego odpowiedzi Plugin SDK. Zmiany konfiguracji CodeQL i workflow jakości uruchamiają wszystkie dwanaście shardów jakości PR.
Ręczne wywołanie akceptuje:
Ręczne uruchomienie akceptuje:
```
profile=all|agent-runtime-boundary|config-boundary|core-auth-secrets|channel-runtime-boundary|gateway-runtime-boundary|memory-runtime-boundary|mcp-process-runtime-boundary|plugin-boundary|plugin-sdk-package-contract|plugin-sdk-reply-runtime|provider-runtime-boundary|session-diagnostics-boundary
```
Wąskie profile są zaczepami szkoleniowymi/iteracyjnymi do uruchamiania jednego shardu jakości w izolacji.
Wąskie profile są zaczepami do nauki/iteracji, służącymi do uruchamiania jednego fragmentu jakości w izolacji.
| Kategoria | Powierzchnia |
| ------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/codeql-critical-quality/core-auth-secrets` | Kod granicy bezpieczeństwa Auth, sekretów, piaskownicy, Cron i Gateway |
| `/codeql-critical-quality/config-boundary` | Schemat konfiguracji, migracja, normalizacja i kontrakty IO |
| `/codeql-critical-quality/gateway-runtime-boundary` | Schematy protokołu Gateway i kontrakty metod serwera |
| `/codeql-critical-quality/channel-runtime-boundary` | Kontrakty implementacji głównego kanału i dołączonego kanału Plugin |
| `/codeql-critical-quality/agent-runtime-boundary` | Wykonywanie poleceń, dyspozycja modeli/dostawców, dyspozycja i kolejki automatycznych odpowiedzi oraz kontrakty środowiska wykonawczego płaszczyzny sterowania ACP |
| `/codeql-critical-quality/mcp-process-runtime-boundary` | Serwery MCP i mosty narzędziowe, pomocniki nadzoru procesów oraz kontrakty dostarczania wychodzącego |
| `/codeql-critical-quality/memory-runtime-boundary` | SDK hosta pamięci, fasady środowiska wykonawczego pamięci, aliasy SDK pamięci Plugin, kod wiążący aktywację środowiska wykonawczego pamięci oraz polecenia doctor pamięci |
| `/codeql-critical-quality/session-diagnostics-boundary` | Wewnętrzne elementy kolejki odpowiedzi, kolejki dostarczania sesji, pomocniki wiązania/dostarczania sesji wychodzących, powierzchnie pakietów zdarzeń/logów diagnostycznych oraz kontrakty CLI doctor sesji |
| `/codeql-critical-quality/plugin-sdk-reply-runtime` | Dyspozycja odpowiedzi przychodzących w SDK Plugin, pomocniki ładunków/kawałkowania/środowiska wykonawczego odpowiedzi, opcje odpowiedzi kanału, kolejki dostarczania oraz pomocniki wiązania sesji/wątków |
| Kategoria | Powierzchnia |
| ------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/codeql-critical-quality/core-auth-secrets` | Kod granicy bezpieczeństwa uwierzytelniania, sekretów, sandboxa, Cron i Gateway |
| `/codeql-critical-quality/config-boundary` | Schemat konfiguracji, migracja, normalizacja i kontrakty IO |
| `/codeql-critical-quality/gateway-runtime-boundary` | Schematy protokołu Gateway i kontrakty metod serwera |
| `/codeql-critical-quality/channel-runtime-boundary` | Kontrakty implementacyjne głównych kanałów i dołączonych Plugin kanałów |
| `/codeql-critical-quality/agent-runtime-boundary` | Wykonywanie poleceń, rozsyłanie modeli/dostawców, rozsyłanie i kolejki automatycznych odpowiedzi oraz kontrakty środowiska wykonawczego płaszczyzny sterowania ACP |
| `/codeql-critical-quality/mcp-process-runtime-boundary` | Serwery MCP i mosty narzędzi, pomocniki nadzoru procesów oraz kontrakty dostarczania wychodzącego |
| `/codeql-critical-quality/memory-runtime-boundary` | SDK hosta pamięci, fasady środowiska wykonawczego pamięci, aliasy pamięci Plugin SDK, spoiwo aktywacji środowiska wykonawczego pamięci oraz polecenia doctor pamięci |
| `/codeql-critical-quality/session-diagnostics-boundary` | Wewnętrzne mechanizmy kolejki odpowiedzi, kolejki dostarczania sesji, pomocniki wiązania/dostarczania sesji wychodzących, powierzchnie zdarzeń diagnostycznych/pakietów logów oraz kontrakty CLI doctor sesji |
| `/codeql-critical-quality/plugin-sdk-reply-runtime` | Rozsyłanie odpowiedzi przychodzących w Plugin SDK, pomocniki ładunku odpowiedzi/fragmentowania/środowiska wykonawczego, opcje odpowiedzi kanału, kolejki dostarczania oraz pomocniki wiązania sesji/wątku |
| `/codeql-critical-quality/provider-runtime-boundary` | Normalizacja katalogu modeli, uwierzytelnianie i wykrywanie dostawców, rejestracja środowiska wykonawczego dostawców, domyślne ustawienia/katalogi dostawców oraz rejestry web/search/fetch/embedding |
| `/codeql-critical-quality/ui-control-plane` | Inicjalizacja Control UI, lokalna trwałość danych, przepływy sterowania Gateway oraz kontrakty środowiska wykonawczego płaszczyzny sterowania zadaniami |
| `/codeql-critical-quality/web-media-runtime-boundary` | Kontrakty środowiska wykonawczego głównego pobierania/wyszukiwania w sieci, IO multimediów, rozumienia multimediów, generowania obrazów i generowania multimediów |
| `/codeql-critical-quality/plugin-boundary` | Kontrakty loadera, rejestru, powierzchni publicznej i punktów wejścia SDK Plugin |
| `/codeql-critical-quality/plugin-sdk-package-contract` | Opublikowane źródło SDK Plugin po stronie pakietu i pomocniki kontraktu pakietu Plugin |
| `/codeql-critical-quality/ui-control-plane` | Bootstrap Control UI, lokalna trwałość, przepływy sterowania Gateway oraz kontrakty środowiska wykonawczego płaszczyzny sterowania zadaniami |
| `/codeql-critical-quality/web-media-runtime-boundary` | Główne kontrakty środowiska wykonawczego web fetch/search, IO mediów, rozumienia mediów, generowania obrazów i generowania mediów |
| `/codeql-critical-quality/plugin-boundary` | Kontrakty loadera, rejestru, powierzchni publicznej i punktu wejścia Plugin SDK |
| `/codeql-critical-quality/plugin-sdk-package-contract` | Opublikowane źródło Plugin SDK po stronie pakietu i pomocniki kontraktu pakietu Plugin |
Jakość pozostaje oddzielona od bezpieczeństwa, aby ustalenia jakościowe można było planować, mierzyć, wyłączać lub rozszerzać bez zaciemniania sygnału bezpieczeństwa. Rozszerzenie CodeQL dla Swift, Python i dołączonych Plugin powinno zostać ponownie dodane jako zakresowane lub shardowane prace następcze dopiero po ustabilizowaniu środowiska wykonawczego i sygnału w wąskich profilach.
Jakość pozostaje oddzielona od bezpieczeństwa, aby ustalenia jakościowe można było planować, mierzyć, wyłączać lub rozszerzać bez zaciemniania sygnału bezpieczeństwa. Rozszerzenie CodeQL dla Swift, Python i dołączonych Plugin powinno zostać dodane z powrotem jako zakresowane lub podzielone na fragmenty prace następcze dopiero wtedy, gdy wąskie profile będą miały stabilne środowisko wykonawcze i sygnał.
## Przepływy utrzymania
## Przepływy utrzymaniowe
### Agent dokumentacji
### Docs Agent
Workflow `Docs Agent` to sterowana zdarzeniami ścieżka utrzymania Codex, która utrzymuje istniejącą dokumentację w zgodności z niedawno wprowadzonymi zmianami. Nie ma czystego harmonogramu: udane uruchomienie CI dla wypchnięcia na `main` przez użytkownika innego niż bot może ją wyzwolić, a ręczne wywołanie może uruchomić ją bezpośrednio. Wywołania workflow-run są pomijane, gdy `main` przesunął się dalej albo gdy w ostatniej godzinie utworzono inne niepominięte uruchomienie Docs Agent. Gdy działa, przegląda zakres commitów od poprzedniego niepominiętego źródłowego SHA Docs Agent do bieżącego `main`, więc jedno godzinne uruchomienie może objąć wszystkie zmiany na main zgromadzone od ostatniego przebiegu dokumentacji.
Przepływ pracy `Docs Agent` to sterowana zdarzeniami ścieżka utrzymaniowa Codex do utrzymywania istniejącej dokumentacji w zgodzie z niedawno wprowadzonymi zmianami. Nie ma czystego harmonogramu: udany przebieg CI po wypchnięciu na `main` przez konto niebędące botem może go wyzwolić, a ręczne uruchomienie może go wykonać bezpośrednio. Wywołania z workflow-run są pomijane, gdy `main` przeszedł dalej albo gdy w ostatniej godzinie utworzono inny niepominięty przebieg Docs Agent. Gdy jest uruchamiany, przegląda zakres commitów od poprzedniego SHA źródłowego niepominiętego Docs Agent do bieżącego `main`, więc jeden godzinny przebieg może objąć wszystkie zmiany na main nagromadzone od ostatniego przejścia dokumentacji.
### Agent wydajności testów
### Test Performance Agent
Workflow `Test Performance Agent` to sterowana zdarzeniami ścieżka utrzymania Codex dla wolnych testów. Nie ma czystego harmonogramu: udane uruchomienie CI dla wypchnięcia na `main` przez użytkownika innego niż bot może ją wyzwolić, ale jest pomijana, jeśli inne wywołanie workflow-run już działało lub działa danego dnia UTC. Ręczne wywołanie omija tę dzienną bramkę aktywności. Ścieżka buduje raport wydajności zgrupowanego pełnego zestawu Vitest, pozwala Codex wprowadzać tylko małe, zachowujące pokrycie poprawki wydajności testów zamiast szerokich refaktoryzacji, następnie ponownie uruchamia raport pełnego zestawu i odrzuca zmiany, które zmniejszają bazową liczbę przechodzących testów. Jeśli baza ma testy zakończone niepowodzeniem, Codex może naprawiać tylko oczywiste awarie, a raport pełnego zestawu po agencie musi przejść, zanim cokolwiek zostanie zatwierdzone. Gdy `main` posunie się naprzód, zanim wypchnięcie bota trafi do repozytorium, ścieżka wykonuje rebase zweryfikowanej poprawki, ponownie uruchamia `pnpm check:changed` i ponawia wypchnięcie; konfliktujące nieaktualne poprawki są pomijane. Używa GitHub-hosted Ubuntu, aby akcja Codex mogła zachować tę samą postawę bezpieczeństwa drop-sudo co agent dokumentacji.
Przepływ pracy `Test Performance Agent` to sterowana zdarzeniami ścieżka utrzymaniowa Codex dla wolnych testów. Nie ma czystego harmonogramu: udany przebieg CI po wypchnięciu na `main` przez konto niebędące botem może go wyzwolić, ale zostanie pominięty, jeśli inne wywołanie workflow-run już zostało uruchomione lub działało danego dnia UTC. Ręczne uruchomienie omija tę dzienną bramkę aktywności. Ścieżka buduje raport wydajności pełnego zestawu zgrupowanych testów Vitest, pozwala Codex wprowadzać tylko małe, zachowujące pokrycie poprawki wydajności testów zamiast szerokich refaktoryzacji, następnie ponownie uruchamia raport pełnego zestawu i odrzuca zmiany, które zmniejszają bazową liczbę przechodzących testów. Jeśli baza ma nieprzechodzące testy, Codex może naprawić tylko oczywiste awarie, a raport pełnego zestawu po agencie musi przejść, zanim cokolwiek zostanie zatwierdzone. Gdy `main` przesunie się przed wypchnięciem bota, ścieżka wykonuje rebase zweryfikowanej łatki, ponownie uruchamia `pnpm check:changed` i ponawia wypchnięcie; konfliktujące, nieaktualne łatki są pomijane. Używa Ubuntu hostowanego przez GitHub, aby akcja Codex mogła zachować tę samą postawę bezpieczeństwa drop-sudo co agent dokumentacji.
### Zduplikowane PR po scaleniu
Workflow `Duplicate PRs After Merge` to ręczny workflow utrzymaniowy dla osób utrzymujących, służący do sprzątania duplikatów po wylądowaniu zmian. Domyślnie działa jako dry-run i zamyka tylko jawnie wymienione PR, gdy `apply=true`. Przed modyfikacją GitHub weryfikuje, że PR, który wylądował, został scalony oraz że każdy duplikat ma albo wspólne przywołane zgłoszenie, albo nakładające się zmienione hunki.
Przepływ pracy `Duplicate PRs After Merge` to ręczny przepływ utrzymaniowy dla porządkowania duplikatów po wylądowaniu zmian. Domyślnie działa w trybie dry-run i zamyka tylko jawnie wymienione PR, gdy `apply=true`. Przed modyfikacją GitHub weryfikuje, że wylądowany PR jest scalony oraz że każdy duplikat ma albo wspólne referencjonowane zgłoszenie, albo nakładające się zmienione fragmenty.
```bash
gh workflow run duplicate-after-merge.yml \
@ -394,27 +404,38 @@ gh workflow run duplicate-after-merge.yml \
## Lokalne bramki sprawdzania i routing zmian
Logika lokalnych ścieżek zmian znajduje się w `scripts/changed-lanes.mjs` i jest wykonywana przez `scripts/check-changed.mjs`. Ta lokalna bramka sprawdzania jest surowsza wobec granic architektury niż szeroki zakres platformy CI:
Lokalna logika zmienionych ścieżek żyje w `scripts/changed-lanes.mjs` i jest wykonywana przez `scripts/check-changed.mjs`. Ta lokalna bramka sprawdzania jest bardziej rygorystyczna wobec granic architektury niż szeroki zakres platformy CI:
- zmiany produkcyjne core uruchamiają typecheck produkcji core i testów core oraz lint/guardy core;
- zmiany wyłącznie w testach core uruchamiają tylko typecheck testów core oraz lint core;
- zmiany produkcyjne rozszerzeń uruchamiają typecheck produkcji rozszerzeń i testów rozszerzeń oraz lint rozszerzeń;
- zmiany wyłącznie w testach rozszerzeń uruchamiają typecheck testów rozszerzeń oraz lint rozszerzeń;
- publiczne zmiany SDK Plugin lub kontraktu Plugin rozszerzają zakres do typecheck rozszerzeń, ponieważ rozszerzenia zależą od tych kontraktów core (przebiegi rozszerzeń Vitest pozostają jawną pracą testową);
- wersjonowania obejmujące tylko metadane wydania uruchamiają ukierunkowane sprawdzenia wersji/konfiguracji/zależności root;
- nieznane zmiany root/konfiguracji przechodzą bezpiecznie na wszystkie ścieżki sprawdzania.
- zmiany produkcyjne core uruchamiają typecheck core prod i core test oraz lint/guardy core;
- zmiany dotyczące wyłącznie testów core uruchamiają tylko typecheck core test oraz lint core;
- zmiany produkcyjne rozszerzeń uruchamiają typecheck extension prod i extension test oraz lint rozszerzeń;
- zmiany dotyczące wyłącznie testów rozszerzeń uruchamiają typecheck extension test oraz lint rozszerzeń;
- zmiany publicznego Plugin SDK lub kontraktu Plugin rozszerzają się do typecheck rozszerzeń, ponieważ rozszerzenia zależą od tych kontraktów core (przeglądy rozszerzeń Vitest pozostają jawną pracą testową);
- podbicia wersji dotyczące tylko metadanych wydania uruchamiają ukierunkowane kontrole wersji/konfiguracji/zależności głównych;
- nieznane zmiany root/config bezpiecznie przechodzą w tryb wszystkich ścieżek sprawdzania.
Lokalny routing zmienionych testów znajduje się w `scripts/test-projects.test-support.mjs` i celowo jest tańszy niż `check:changed`: bezpośrednie edycje testów uruchamiają same siebie, edycje źródeł preferują jawne mapowania, następnie testy siostrzane i zależności z grafu importów. Wspólna konfiguracja dostarczania group-room jest jednym z jawnych mapowań: zmiany w konfiguracji widocznych odpowiedzi grupowych, trybie dostarczania odpowiedzi źródłowych lub systemowym prompcie narzędzia wiadomości przechodzą przez główne testy odpowiedzi oraz regresje dostarczania Discord i Slack, aby wspólna zmiana domyślna zakończyła się niepowodzeniem przed pierwszym wypchnięciem PR. Używaj `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed` tylko wtedy, gdy zmiana jest na tyle szeroka dla całego harnessu, że tani zmapowany zestaw nie jest wiarygodnym przybliżeniem.
Lokalny routing zmienionych testów żyje w `scripts/test-projects.test-support.mjs` i celowo jest tańszy niż `check:changed`: bezpośrednie edycje testów uruchamiają same siebie, edycje źródeł preferują jawne mapowania, następnie testy rodzeństwa i zależności grafu importów. Wspólna konfiguracja dostarczania group-room jest jednym z jawnych mapowań: zmiany konfiguracji widocznej odpowiedzi grupy, trybu dostarczania odpowiedzi źródłowej albo promptu systemowego narzędzia wiadomości przechodzą przez główne testy odpowiedzi oraz regresje dostarczania Discord i Slack, aby zmiana wspólnej wartości domyślnej zawiodła przed pierwszym wypchnięciem PR. Używaj `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed` tylko wtedy, gdy zmiana jest na tyle szeroka dla harnessu, że tani zestaw mapowany nie jest wiarygodnym przybliżeniem.
## Walidacja Testbox
Uruchamiaj Testbox z katalogu głównego repozytorium i preferuj świeżo rozgrzane pudełko do szerokiego dowodu. Przed przeznaczeniem wolnej bramki na pudełko, które zostało ponownie użyte, wygasło albo właśnie zgłosiło nieoczekiwanie dużą synchronizację, najpierw uruchom `pnpm testbox:sanity` wewnątrz pudełka.
Uruchamiaj Testbox z katalogu głównego repozytorium i preferuj świeżo rozgrzany box dla szerokiego dowodu. Przed poświęceniem wolnej bramki na box, który był użyty ponownie, wygasł albo właśnie zgłosił nieoczekiwanie dużą synchronizację, uruchom najpierw `pnpm testbox:sanity` wewnątrz boxa.
Sprawdzenie sanity szybko kończy się niepowodzeniem, gdy wymagane pliki root, takie jak `pnpm-lock.yaml`, zniknęły albo gdy `git status --short` pokazuje co najmniej 200 śledzonych usunięć. Zwykle oznacza to, że zdalny stan synchronizacji nie jest wiarygodną kopią PR; zatrzymaj to pudełko i rozgrzej świeże zamiast debugować awarię testu produktu. Dla celowych PR z dużą liczbą usunięć ustaw `OPENCLAW_TESTBOX_ALLOW_MASS_DELETIONS=1` dla tego przebiegu sanity.
Kontrola sanity szybko kończy się niepowodzeniem, gdy wymagane pliki główne, takie jak `pnpm-lock.yaml`, zniknęły albo gdy `git status --short` pokazuje co najmniej 200 śledzonych usunięć. Zwykle oznacza to, że zdalny stan synchronizacji nie jest wiarygodną kopią PR; zatrzymaj ten box i rozgrzej świeży zamiast debugować awarię testu produktu. Dla celowych PR z dużą liczbą usunięć ustaw `OPENCLAW_TESTBOX_ALLOW_MASS_DELETIONS=1` dla tego przebiegu sanity.
`pnpm testbox:run` kończy także lokalne wywołanie Blacksmith CLI, które pozostaje w fazie synchronizacji przez ponad pięć minut bez danych wyjściowych po synchronizacji. Ustaw `OPENCLAW_TESTBOX_SYNC_TIMEOUT_MS=0`, aby wyłączyć tę osłonę, albo użyj większej wartości w milisekundach dla wyjątkowo dużych lokalnych różnic.
`pnpm testbox:run` kończy też lokalne wywołanie Blacksmith CLI, które pozostaje w fazie synchronizacji przez ponad pięć minut bez wyjścia po synchronizacji. Ustaw `OPENCLAW_TESTBOX_SYNC_TIMEOUT_MS=0`, aby wyłączyć ten guard, albo użyj większej wartości w milisekundach dla nietypowo dużych lokalnych diffów.
Crabbox to druga, należąca do repozytorium ścieżka zdalnego boxa dla dowodu linuksowego, gdy Blacksmith jest niedostępny albo gdy preferowana jest własna pojemność chmurowa. Rozgrzej box, uwodnij go przez przepływ pracy projektu, a następnie uruchamiaj polecenia przez Crabbox CLI:
```bash
pnpm crabbox:warmup -- --idle-timeout 90m
pnpm crabbox:hydrate -- --id <cbx_id>
pnpm crabbox:run -- --id <cbx_id> --shell "OPENCLAW_TESTBOX=1 pnpm check:changed"
pnpm crabbox:stop -- <cbx_id>
```
`.crabbox.yaml` zawiera domyślne ustawienia dostawcy, synchronizacji i uwadniania GitHub Actions. Wyklucza lokalny `.git`, aby uwodniony checkout Actions zachował własne zdalne metadane Git zamiast synchronizować lokalne remotes i magazyny obiektów maintainerów, a także wyklucza lokalne artefakty środowiska wykonawczego/buildu, których nigdy nie należy przesyłać. `.github/workflows/crabbox-hydrate.yml` zawiera checkout, konfigurację Node/pnpm, pobranie `origin/main` oraz przekazanie niesekretnego środowiska, które późniejsze polecenia `crabbox run --id <cbx_id>` odczytują jako źródło.
## Powiązane
- [Omówienie instalacji](/pl/install)
- [Przegląd instalacji](/pl/install)
- [Kanały deweloperskie](/pl/install/development-channels)

73
docs/pl/cli/channels.md
View File

@ -1,21 +1,21 @@
---
read_when:
- Chcesz dodawać/usuwać konta kanałów (WhatsApp/Telegram/Discord/Google Chat/Slack/Mattermost (Plugin)/Signal/iMessage/Matrix)
- Chcesz sprawdzić status kanału lub śledzić logi kanału
summary: Dokumentacja referencyjna CLI dla `openclaw channels` (konta, status, logowanie/wylogowanie, logi)
- Chcesz dodać/usunąć konta kanałów (WhatsApp/Telegram/Discord/Google Chat/Slack/Mattermost (plugin)/Signal/iMessage/Matrix)
- Chcesz sprawdzić status kanału lub śledzić dzienniki kanału na bieżąco
summary: Dokumentacja CLI dla `openclaw channels` (konta, status, logowanie/wylogowanie, logi)
title: Kanały
x-i18n:
generated_at: "2026-04-30T09:42:03Z"
generated_at: "2026-05-01T09:56:21Z"
model: gpt-5.5
provider: openai
source_hash: 6fc3c5983114c17e0e7284450aa161b658312c05864db65e09d6d764e357cd1f
source_hash: 1f673a626b46cd4c8ba7eb28963d27e7e3f630dd86723332faab9b4c86553da9
source_path: cli/channels.md
workflow: 16
---
# `openclaw channels`
Zarządzaj kontami kanałów czatu i ich stanem działania na Gateway.
Zarządzaj kontami kanałów czatu i ich statusem uruchomieniowym w Gateway.
Powiązana dokumentacja:
@ -33,18 +33,18 @@ openclaw channels resolve --channel slack "#general" "@jane"
openclaw channels logs --channel all
```
## Stan / możliwości / rozwiązywanie nazw / logi
## Status / capabilities / resolve / logs
- `channels status`: `--probe`, `--timeout <ms>`, `--json`
- `channels capabilities`: `--channel <name>`, `--account <id>` (tylko z `--channel`), `--target <dest>`, `--timeout <ms>`, `--json`
- `channels resolve`: `<entries...>`, `--channel <name>`, `--account <id>`, `--kind <auto|user|group>`, `--json`
- `channels logs`: `--channel <name|all>`, `--lines <n>`, `--json`
`channels status --probe` to ścieżka na żywo: na osiągalnym Gateway uruchamia dla każdego konta
kontrole `probeAccount` i opcjonalnie `auditAccount`, więc dane wyjściowe mogą obejmować stan
`channels status --probe` to ścieżka na żywo: na osiągalnym gateway uruchamia dla każdego konta
kontrole `probeAccount` i opcjonalne `auditAccount`, więc dane wyjściowe mogą zawierać stan
transportu oraz wyniki sondowania, takie jak `works`, `probe failed`, `audit ok` lub `audit failed`.
Jeśli Gateway jest nieosiągalny, `channels status` przełącza się na podsumowania oparte wyłącznie
na konfiguracji zamiast danych wyjściowych sondowania na żywo.
Jeśli gateway jest nieosiągalny, `channels status` wraca do podsumowań opartych wyłącznie na konfiguracji
zamiast danych wyjściowych sondowania na żywo.
## Dodawanie / usuwanie kont
@ -55,20 +55,22 @@ openclaw channels remove --channel telegram --delete
```
<Tip>
`openclaw channels add --help` pokazuje flagi dla poszczególnych kanałów (token, klucz prywatny, token aplikacji, ścieżki signal-cli itd.).
`openclaw channels add --help` pokazuje flagi właściwe dla każdego kanału (token, klucz prywatny, token aplikacji, ścieżki signal-cli itd.).
</Tip>
`channels remove` działa tylko na zainstalowanych/skonfigurowanych pluginach kanałów. Dla instalowalnych kanałów z katalogu najpierw użyj `channels add`.
Typowe nieinteraktywne powierzchnie dodawania obejmują:
- kanały z tokenem bota: `--token`, `--bot-token`, `--app-token`, `--token-file`
- pola transportu Signal/iMessage: `--signal-number`, `--cli-path`, `--http-url`, `--http-host`, `--http-port`, `--db-path`, `--service`, `--region`
- pola Google Chat: `--webhook-path`, `--webhook-url`, `--audience-type`, `--audience`
- pola Matrix: `--homeserver`, `--user-id`, `--access-token`, `--password`, `--device-name`, `--initial-sync-limit`
- pola Nostr: `--private-key`, `--relay-urls`
- pola Tlon: `--ship`, `--url`, `--code`, `--group-channels`, `--dm-allowlist`, `--auto-discover-channels`
- `--use-env` dla uwierzytelniania domyślnego konta opartego na zmiennych środowiskowych tam, gdzie jest obsługiwane
- kanały bot-token: `--token`, `--bot-token`, `--app-token`, `--token-file`
- Pola transportu Signal/iMessage: `--signal-number`, `--cli-path`, `--http-url`, `--http-host`, `--http-port`, `--db-path`, `--service`, `--region`
- Pola Google Chat: `--webhook-path`, `--webhook-url`, `--audience-type`, `--audience`
- Pola Matrix: `--homeserver`, `--user-id`, `--access-token`, `--password`, `--device-name`, `--initial-sync-limit`
- Pola Nostr: `--private-key`, `--relay-urls`
- Pola Tlon: `--ship`, `--url`, `--code`, `--group-channels`, `--dm-allowlist`, `--auto-discover-channels`
- `--use-env` dla uwierzytelniania domyślnego konta opartego na zmiennych środowiskowych, gdy jest obsługiwane
Jeśli Plugin kanału musi zostać zainstalowany podczas polecenia dodawania sterowanego flagami, OpenClaw używa domyślnego źródła instalacji kanału bez otwierania interaktywnego monitu instalacji Plugin.
Jeśli plugin kanału musi zostać zainstalowany podczas polecenia dodawania sterowanego flagami, OpenClaw używa domyślnego źródła instalacji kanału bez otwierania interaktywnego monitu instalacji pluginu.
Gdy uruchomisz `openclaw channels add` bez flag, interaktywny kreator może zapytać o:
@ -76,19 +78,19 @@ Gdy uruchomisz `openclaw channels add` bez flag, interaktywny kreator może zapy
- opcjonalne nazwy wyświetlane dla tych kont
- `Bind configured channel accounts to agents now?`
Jeśli potwierdzisz przypisanie teraz, kreator zapyta, który agent ma być właścicielem każdego skonfigurowanego konta kanału, i zapisze powiązania routingu ograniczone do konta.
Jeśli potwierdzisz wiązanie teraz, kreator zapyta, który agent powinien być właścicielem każdego skonfigurowanego konta kanału, i zapisze wiązania routingu o zakresie konta.
Możesz też zarządzać tymi samymi regułami routingu później za pomocą `openclaw agents bindings`, `openclaw agents bind` i `openclaw agents unbind` (zobacz [agenci](/pl/cli/agents)).
Tymi samymi regułami routingu możesz też zarządzać później za pomocą `openclaw agents bindings`, `openclaw agents bind` i `openclaw agents unbind` (zobacz [agenci](/pl/cli/agents)).
Gdy dodasz konto inne niż domyślne do kanału, który nadal używa ustawień najwyższego poziomu dla pojedynczego konta, OpenClaw przenosi wartości najwyższego poziomu ograniczone do konta do mapy kont kanału przed zapisaniem nowego konta. Większość kanałów zapisuje te wartości w `channels.<channel>.accounts.default`, ale dołączone kanały mogą zamiast tego zachować istniejące pasujące promowane konto. Matrix jest aktualnym przykładem: jeśli jedno nazwane konto już istnieje albo `defaultAccount` wskazuje istniejące nazwane konto, promocja zachowuje to konto zamiast tworzyć nowe `accounts.default`.
Gdy dodajesz konto inne niż domyślne do kanału, który nadal używa jednokontowych ustawień najwyższego poziomu, OpenClaw promuje wartości najwyższego poziomu o zakresie konta do mapy kont kanału przed zapisaniem nowego konta. Większość kanałów zapisuje te wartości w `channels.<channel>.accounts.default`, ale kanały wbudowane mogą zamiast tego zachować istniejące pasujące promowane konto. Matrix jest obecnym przykładem: jeśli istnieje już jedno nazwane konto albo `defaultAccount` wskazuje istniejące nazwane konto, promocja zachowuje to konto zamiast tworzyć nowe `accounts.default`.
Zachowanie routingu pozostaje spójne:
- Istniejące powiązania tylko z kanałem (bez `accountId`) nadal dopasowują konto domyślne.
- `channels add` nie tworzy automatycznie ani nie przepisuje powiązań w trybie nieinteraktywnym.
- Konfiguracja interaktywna może opcjonalnie dodać powiązania ograniczone do konta.
- Istniejące wiązania tylko kanału (bez `accountId`) nadal pasują do konta domyślnego.
- `channels add` nie tworzy automatycznie ani nie przepisuje wiązań w trybie nieinteraktywnym.
- Konfiguracja interaktywna może opcjonalnie dodać wiązania o zakresie konta.
Jeśli Twoja konfiguracja była już w stanie mieszanym (obecne nazwane konta i nadal ustawione wartości najwyższego poziomu dla pojedynczego konta), uruchom `openclaw doctor --fix`, aby przenieść wartości ograniczone do konta do promowanego konta wybranego dla tego kanału. Większość kanałów promuje do `accounts.default`; Matrix może zamiast tego zachować istniejący nazwany/domyślny cel.
Jeśli Twoja konfiguracja była już w stanie mieszanym (nazwane konta są obecne, a jednokontowe wartości najwyższego poziomu nadal ustawione), uruchom `openclaw doctor --fix`, aby przenieść wartości o zakresie konta do promowanego konta wybranego dla tego kanału. Większość kanałów promuje do `accounts.default`; Matrix może zamiast tego zachować istniejący nazwany/domyślny cel.
## Logowanie i wylogowanie (interaktywne)
@ -98,15 +100,15 @@ openclaw channels logout --channel whatsapp
```
- `channels login` obsługuje `--verbose`.
- `channels login` i `logout` mogą wywnioskować kanał, gdy skonfigurowano tylko jeden obsługiwany cel logowania.
- Uruchom `channels login` z terminala na hoście Gateway. Agent `exec` blokuje ten interaktywny przepływ logowania; natywne dla kanału narzędzia logowania agenta, takie jak `whatsapp_login`, powinny być używane z czatu, gdy są dostępne.
- `channels login` i `logout` mogą wywnioskować kanał, gdy skonfigurowany jest tylko jeden obsługiwany cel logowania.
- Uruchom `channels login` z terminala na hoście gateway. Agent `exec` blokuje ten interaktywny przepływ logowania; natywnych dla kanału narzędzi logowania agenta, takich jak `whatsapp_login`, należy używać z czatu, gdy są dostępne.
## Rozwiązywanie problemów
- Uruchom `openclaw status --deep`, aby wykonać szerokie sondowanie.
- Użyj `openclaw doctor`, aby uzyskać prowadzone poprawki.
- `openclaw channels list` wypisuje `Claude: HTTP 403 ... user:profile` → migawka użycia wymaga zakresu `user:profile`. Użyj `--no-usage`, podaj klucz sesji claude.ai (`CLAUDE_WEB_SESSION_KEY` / `CLAUDE_WEB_COOKIE`) albo uwierzytelnij ponownie przez Claude CLI.
- `openclaw channels status` przełącza się na podsumowania oparte wyłącznie na konfiguracji, gdy Gateway jest nieosiągalny. Jeśli obsługiwane poświadczenie kanału jest skonfigurowane przez SecretRef, ale niedostępne w bieżącej ścieżce polecenia, raportuje to konto jako skonfigurowane z notatkami o ograniczonej funkcjonalności, zamiast pokazywać je jako nieskonfigurowane.
- `openclaw channels list` wypisuje `Claude: HTTP 403 ... user:profile` → migawka użycia potrzebuje zakresu `user:profile`. Użyj `--no-usage`, podaj klucz sesji claude.ai (`CLAUDE_WEB_SESSION_KEY` / `CLAUDE_WEB_COOKIE`) albo ponownie uwierzytelnij przez Claude CLI.
- `openclaw channels status` wraca do podsumowań opartych wyłącznie na konfiguracji, gdy gateway jest nieosiągalny. Jeśli obsługiwane poświadczenie kanału jest skonfigurowane przez SecretRef, ale niedostępne w bieżącej ścieżce polecenia, konto jest raportowane jako skonfigurowane z notatkami o degradacji zamiast jako nieskonfigurowane.
## Sondowanie możliwości
@ -121,8 +123,8 @@ Uwagi:
- `--channel` jest opcjonalne; pomiń je, aby wyświetlić każdy kanał (w tym rozszerzenia).
- `--account` jest poprawne tylko z `--channel`.
- `--target` akceptuje `channel:<id>` lub surowy numeryczny identyfikator kanału i dotyczy tylko Discord.
- Sondy są specyficzne dla dostawcy: intencje Discord + opcjonalne uprawnienia kanału; zakresy bota + użytkownika Slack; flagi bota Telegram + Webhook; wersja demona Signal; token aplikacji Microsoft Teams + role/zakresy Graph (z adnotacjami tam, gdzie znane). Kanały bez sond zgłaszają `Probe: unavailable`.
- `--target` akceptuje `channel:<id>` albo surowy numeryczny identyfikator kanału i dotyczy tylko Discord.
- Sondy są specyficzne dla dostawcy: intencje Discord + opcjonalne uprawnienia kanału; zakresy bota + użytkownika Slack; flagi bota Telegram + webhook; wersja demona Signal; token aplikacji Microsoft Teams + role/zakresy Graph (z adnotacjami tam, gdzie są znane). Kanały bez sond raportują `Probe: unavailable`.
## Rozwiązywanie nazw na identyfikatory
@ -138,9 +140,10 @@ Uwagi:
- Użyj `--kind user|group|auto`, aby wymusić typ celu.
- Rozwiązywanie preferuje aktywne dopasowania, gdy wiele wpisów ma tę samą nazwę.
- `channels resolve` jest tylko do odczytu. Jeśli wybrane konto jest skonfigurowane przez SecretRef, ale to poświadczenie jest niedostępne w bieżącej ścieżce polecenia, polecenie zwraca ograniczone nierozwiązane wyniki z notatkami zamiast przerywać całe uruchomienie.
- `channels resolve` jest tylko do odczytu. Jeśli wybrane konto jest skonfigurowane przez SecretRef, ale to poświadczenie jest niedostępne w bieżącej ścieżce polecenia, polecenie zwraca zdegradowane nierozwiązane wyniki z notatkami zamiast przerywać całe uruchomienie.
- `channels resolve` nie instaluje pluginów kanałów. Użyj `channels add --channel <name>` przed rozwiązywaniem nazw dla instalowalnego kanału z katalogu.
## Powiązane
- [Dokumentacja CLI](/pl/cli)
- [Omówienie kanałów](/pl/channels)
- [Przegląd kanałów](/pl/channels)

35
docs/pl/cli/configure.md
View File

@ -1,43 +1,43 @@
---
read_when:
- Chcesz interaktywnie dostosować poświadczenia, urządzenia lub ustawienia domyślne agenta
- Chcesz interaktywnie dostosować poświadczenia, urządzenia lub domyślne ustawienia agenta
summary: Dokumentacja referencyjna CLI dla `openclaw configure` (interaktywne monity konfiguracji)
title: Konfiguracja
x-i18n:
generated_at: "2026-04-30T09:42:21Z"
generated_at: "2026-05-01T09:56:06Z"
model: gpt-5.5
provider: openai
source_hash: 1bde13a139c299879ff13a85c17afdd55dce7ad758418266854428b059d8a05e
source_hash: 437a6ec43a48611bf08bdeb0a6e692581c488fac283f0104b172088db37949bb
source_path: cli/configure.md
workflow: 16
---
# `openclaw configure`
Interaktywny monit do konfigurowania poświadczeń, urządzeń i domyślnych ustawień agenta.
Interaktywny kreator do konfigurowania danych uwierzytelniających, urządzeń i domyślnych ustawień agentów.
<Note>
Sekcja **Model** zawiera wielokrotny wybór dla listy dozwolonych `agents.defaults.models` (tego, co pojawia się w `/model` i selektorze modelu). Opcje konfiguracji ograniczone do dostawcy scalają wybrane modele z istniejącą listą dozwolonych zamiast zastępować niepowiązanych dostawców już obecnych w konfiguracji. Ponowne uruchomienie uwierzytelniania dostawcy z konfiguracji zachowuje istniejące `agents.defaults.model.primary`. Użyj `openclaw models auth login --provider <id> --set-default` lub `openclaw models set <model>`, gdy celowo chcesz zmienić model domyślny.
Sekcja **Model** zawiera wybór wielokrotny dla listy dozwolonych `agents.defaults.models` (tego, co pojawia się w `/model` i selektorze modeli). Opcje konfiguracji ograniczone do dostawcy scalają wybrane modele z istniejącą listą dozwolonych zamiast zastępować niepowiązanych dostawców obecnych już w konfiguracji. Ponowne uruchomienie uwierzytelniania dostawcy z poziomu konfiguracji zachowuje istniejące `agents.defaults.model.primary`. Użyj `openclaw models auth login --provider <id> --set-default` albo `openclaw models set <model>`, gdy celowo chcesz zmienić model domyślny.
</Note>
Gdy konfiguracja rozpoczyna się od wyboru uwierzytelniania dostawcy, selektory modelu domyślnego i listy dozwolonych automatycznie preferują tego dostawcę. W przypadku sparowanych dostawców, takich jak Volcengine i BytePlus, ta sama preferencja pasuje także do ich wariantów planu kodowania (`volcengine-plan/*`, `byteplus-plan/*`). Jeśli filtr preferowanego dostawcy utworzyłby pustą listę, konfiguracja wraca do niefiltrowanego katalogu zamiast pokazywać pusty selektor.
Gdy konfiguracja zaczyna się od opcji uwierzytelniania dostawcy, selektory modelu domyślnego i listy dozwolonych automatycznie preferują tego dostawcę. W przypadku sparowanych dostawców, takich jak Volcengine i BytePlus, ta sama preferencja obejmuje także ich warianty planu kodowania (`volcengine-plan/*`, `byteplus-plan/*`). Jeśli filtr preferowanego dostawcy dałby pustą listę, konfiguracja wraca do niefiltrowanego katalogu zamiast pokazywać pusty selektor.
<Tip>
`openclaw config` bez podpolecenia otwiera ten sam kreator. Użyj `openclaw config get|set|unset` do nieinteraktywnych edycji.
</Tip>
Dla wyszukiwania w sieci `openclaw configure --section web` pozwala wybrać dostawcę
i skonfigurować jego poświadczenia. Niektórzy dostawcy pokazują też specyficzne
dla dostawcy monity uzupełniające:
W przypadku wyszukiwania w sieci `openclaw configure --section web` pozwala wybrać dostawcę
i skonfigurować jego dane uwierzytelniające. Niektórzy dostawcy pokazują też właściwe dla dostawcy
kolejne monity:
- **Grok** może zaoferować opcjonalną konfigurację `x_search` z tym samym `XAI_API_KEY` i
pozwolić wybrać model `x_search`.
- **Kimi** może poprosić o region API Moonshot (`api.moonshot.ai` kontra
- **Kimi** może poprosić o region Moonshot API (`api.moonshot.ai` albo
`api.moonshot.cn`) oraz domyślny model wyszukiwania w sieci Kimi.
Powiązane:
- Odniesienie konfiguracji Gateway: [Konfiguracja](/pl/gateway/configuration)
- Odniesienie do konfiguracji Gateway: [Konfiguracja](/pl/gateway/configuration)
- CLI konfiguracji: [Konfiguracja](/pl/cli/config)
## Opcje
@ -58,11 +58,12 @@ Dostępne sekcje:
Uwagi:
- Wybór miejsca uruchamiania Gateway zawsze aktualizuje `gateway.mode`. Możesz wybrać „Kontynuuj” bez innych sekcji, jeśli to wszystko, czego potrzebujesz.
- Usługi zorientowane na kanały (Slack/Discord/Matrix/Microsoft Teams) podczas konfiguracji proszą o listy dozwolonych kanałów/pokojów. Możesz wprowadzić nazwy lub identyfikatory; kreator rozwiązuje nazwy na identyfikatory, gdy to możliwe.
- Jeśli uruchomisz krok instalacji demona, uwierzytelnianie tokenem wymaga tokenu, a `gateway.auth.token` jest zarządzane przez SecretRef, konfiguracja weryfikuje SecretRef, ale nie zapisuje rozwiązanych wartości tokenów w postaci zwykłego tekstu w metadanych środowiska usługi supervisor.
- Jeśli uwierzytelnianie tokenem wymaga tokenu, a skonfigurowany token SecretRef nie jest rozwiązany, konfiguracja blokuje instalację demona z praktycznymi wskazówkami naprawczymi.
- Jeśli skonfigurowane są zarówno `gateway.auth.token`, jak i `gateway.auth.password`, a `gateway.auth.mode` nie jest ustawione, konfiguracja blokuje instalację demona do czasu jawnego ustawienia trybu.
- Wybranie miejsca, w którym działa Gateway, zawsze aktualizuje `gateway.mode`. Możesz wybrać „Kontynuuj” bez innych sekcji, jeśli to wszystko, czego potrzebujesz.
- Po zapisach lokalnej konfiguracji konfigurator materializuje nowo wymagane zależności środowiska uruchomieniowego dołączonych Plugin. To wąski krok naprawczy menedżera pakietów, a nie pełne uruchomienie `openclaw doctor`. Konfiguracja zdalnego Gateway nie instaluje lokalnych zależności Plugin.
- Usługi zorientowane na kanały (Slack/Discord/Matrix/Microsoft Teams) proszą podczas konfiguracji o listy dozwolonych kanałów/pokoi. Możesz podać nazwy albo identyfikatory; kreator rozwiązuje nazwy na identyfikatory, gdy to możliwe.
- Jeśli uruchomisz krok instalacji demona, uwierzytelnianie tokenem wymaga tokenu, a `gateway.auth.token` jest zarządzane przez SecretRef, konfigurator weryfikuje SecretRef, ale nie utrwala rozwiązanych wartości tokenu w postaci zwykłego tekstu w metadanych środowiska usługi nadzorcy.
- Jeśli uwierzytelnianie tokenem wymaga tokenu, a skonfigurowany SecretRef tokenu nie jest rozwiązany, konfigurator blokuje instalację demona z praktycznymi wskazówkami naprawczymi.
- Jeśli skonfigurowano zarówno `gateway.auth.token`, jak i `gateway.auth.password`, a `gateway.auth.mode` nie jest ustawione, konfigurator blokuje instalację demona do czasu jawnego ustawienia trybu.
## Przykłady
@ -75,5 +76,5 @@ openclaw configure --section gateway --section daemon
## Powiązane
- [Odniesienie CLI](/pl/cli)
- [Odwołanie CLI](/pl/cli)
- [Konfiguracja](/pl/gateway/configuration)

250
docs/pl/cli/gateway.md
View File

@ -2,30 +2,30 @@
read_when:
- Uruchamianie Gateway z poziomu CLI (środowisko deweloperskie lub serwery)
- Debugowanie uwierzytelniania Gateway, trybów wiązania i łączności
- Wykrywanie Gateway przez Bonjour (lokalne + szerokoobszarowe DNS-SD)
- Wykrywanie Gateway za pomocą Bonjour (lokalne + szerokoobszarowe DNS-SD)
sidebarTitle: Gateway
summary: OpenClaw Gateway CLI (`openclaw gateway`) — uruchamiaj, odpytuj i wykrywaj Gateway
summary: OpenClaw Gateway CLI (`openclaw gateway`) — uruchamiaj, odpytuj i wykrywaj bramy Gateway
title: Gateway
x-i18n:
generated_at: "2026-04-30T09:43:23Z"
generated_at: "2026-05-01T09:56:29Z"
model: gpt-5.5
provider: openai
source_hash: fe53f1ec289bf463766634a9b03bc234e109fdddf35b3fa3958fb8c5255c81a9
source_hash: 127a6ccb4baa1ad5e5051db0bc7ef0ed30d410c4c3d13f36356483a6e03dce4c
source_path: cli/gateway.md
workflow: 16
---
Gateway jest serwerem WebSocket OpenClaw (kanały, węzły, sesje, hooki). Podkomendy na tej stronie znajdują się pod `openclaw gateway …`.
Gateway to serwer WebSocket OpenClaw (kanały, węzły, sesje, hooki). Podkomendy na tej stronie znajdują się pod `openclaw gateway …`.
<CardGroup cols={3}>
<Card title="Bonjour discovery" href="/pl/gateway/bonjour">
Lokalna konfiguracja mDNS + szerokoobszarowego DNS-SD.
<Card title="Wykrywanie Bonjour" href="/pl/gateway/bonjour">
Konfiguracja lokalnego mDNS + szerokoobszarowego DNS-SD.
</Card>
<Card title="Discovery overview" href="/pl/gateway/discovery">
Jak OpenClaw ogłasza i znajduje Gateway.
<Card title="Omówienie wykrywania" href="/pl/gateway/discovery">
Jak OpenClaw rozgłasza i znajduje bramy.
</Card>
<Card title="Configuration" href="/pl/gateway/configuration">
Klucze konfiguracji Gateway najwyższego poziomu.
<Card title="Konfiguracja" href="/pl/gateway/configuration">
Klucze konfiguracji gateway najwyższego poziomu.
</Card>
</CardGroup>
@ -44,13 +44,13 @@ openclaw gateway run
```
<AccordionGroup>
<Accordion title="Startup behavior">
- Domyślnie Gateway odmawia uruchomienia, jeśli `gateway.mode=local` nie jest ustawione w `~/.openclaw/openclaw.json`. Użyj `--allow-unconfigured` do jednorazowych/deweloperskich uruchomień.
- Oczekuje się, że `openclaw onboard --mode local` i `openclaw setup` zapiszą `gateway.mode=local`. Jeśli plik istnieje, ale brakuje `gateway.mode`, traktuj to jako uszkodzoną lub nadpisaną konfigurację i napraw ją, zamiast niejawnie zakładać tryb lokalny.
<Accordion title="Zachowanie podczas uruchamiania">
- Domyślnie Gateway odmawia uruchomienia, jeśli w `~/.openclaw/openclaw.json` nie ustawiono `gateway.mode=local`. Użyj `--allow-unconfigured` do uruchomień ad hoc/deweloperskich.
- Oczekuje się, że `openclaw onboard --mode local` i `openclaw setup` zapiszą `gateway.mode=local`. Jeśli plik istnieje, ale brakuje `gateway.mode`, potraktuj to jako uszkodzoną lub nadpisaną konfigurację i napraw ją, zamiast zakładać niejawnie tryb lokalny.
- Jeśli plik istnieje i brakuje `gateway.mode`, Gateway traktuje to jako podejrzane uszkodzenie konfiguracji i odmawia „zgadywania local” za Ciebie.
- Bindowanie poza loopback bez uwierzytelniania jest blokowane (zabezpieczenie).
- `SIGUSR1` wyzwala ponowne uruchomienie w ramach procesu, gdy jest autoryzowane (`commands.restart` jest domyślnie włączone; ustaw `commands.restart: false`, aby zablokować ręczny restart, podczas gdy zastosowanie/aktualizacja narzędzi i konfiguracji Gateway pozostają dozwolone).
- Handlery `SIGINT`/`SIGTERM` zatrzymują proces Gateway, ale nie przywracają żadnego niestandardowego stanu terminala. Jeśli opakowujesz CLI za pomocą TUI lub wejścia w trybie raw, przywróć terminal przed wyjściem.
- `SIGUSR1` wyzwala restart w procesie, gdy jest autoryzowany (`commands.restart` jest domyślnie włączone; ustaw `commands.restart: false`, aby zablokować ręczny restart, podczas gdy zastosowanie/aktualizacja narzędzia i konfiguracji gateway pozostaną dozwolone).
- Handlery `SIGINT`/`SIGTERM` zatrzymują proces gateway, ale nie przywracają żadnego niestandardowego stanu terminala. Jeśli opakowujesz CLI za pomocą TUI lub wejścia w trybie raw, przywróć terminal przed wyjściem.
</Accordion>
</AccordionGroup>
@ -58,40 +58,40 @@ openclaw gateway run
### Opcje
<ParamField path="--port <port>" type="number">
Port WebSocket (wartość domyślna pochodzi z konfiguracji/env; zwykle `18789`).
Port WebSocket (domyślnie pochodzi z konfiguracji/env; zwykle `18789`).
</ParamField>
<ParamField path="--bind <loopback|lan|tailnet|auto|custom>" type="string">
Tryb bindowania nasłuchu.
Tryb bindowania listenera.
</ParamField>
<ParamField path="--auth <token|password>" type="string">
Nadpisanie trybu uwierzytelniania.
</ParamField>
<ParamField path="--token <token>" type="string">
Nadpisanie tokena (ustawia też `OPENCLAW_GATEWAY_TOKEN` dla procesu).
Nadpisanie tokenu (ustawia także `OPENCLAW_GATEWAY_TOKEN` dla procesu).
</ParamField>
<ParamField path="--password <password>" type="string">
Nadpisanie hasła.
</ParamField>
<ParamField path="--password-file <path>" type="string">
Odczytaj hasło Gateway z pliku.
Odczytaj hasło gateway z pliku.
</ParamField>
<ParamField path="--tailscale <off|serve|funnel>" type="string">
Udostępnij Gateway przez Tailscale.
</ParamField>
<ParamField path="--tailscale-reset-on-exit" type="boolean">
Resetuj konfigurację serve/funnel Tailscale przy wyłączaniu.
Zresetuj konfigurację Tailscale serve/funnel przy zamykaniu.
</ParamField>
<ParamField path="--allow-unconfigured" type="boolean">
Zezwól na start Gateway bez `gateway.mode=local` w konfiguracji. Omija zabezpieczenie startowe tylko dla jednorazowego/deweloperskiego bootstrapu; nie zapisuje ani nie naprawia pliku konfiguracji.
Zezwól na start gateway bez `gateway.mode=local` w konfiguracji. Omija zabezpieczenie startowe wyłącznie dla bootstrapu ad hoc/deweloperskiego; nie zapisuje ani nie naprawia pliku konfiguracji.
</ParamField>
<ParamField path="--dev" type="boolean">
Utwórz konfigurację deweloperską + przestrzeń roboczą, jeśli ich brakuje (pomija BOOTSTRAP.md).
Utwórz konfigurację deweloperską + workspace, jeśli ich brakuje (pomija BOOTSTRAP.md).
</ParamField>
<ParamField path="--reset" type="boolean">
Resetuj konfigurację deweloperską + dane uwierzytelniające + sesje + przestrzeń roboczą (wymaga `--dev`).
Zresetuj konfigurację deweloperską + poświadczenia + sesje + workspace (wymaga `--dev`).
</ParamField>
<ParamField path="--force" type="boolean">
Zabij każdy istniejący nasłuch na wybranym porcie przed uruchomieniem.
Zabij dowolny istniejący listener na wybranym porcie przed startem.
</ParamField>
<ParamField path="--verbose" type="boolean">
Szczegółowe logi.
@ -109,42 +109,42 @@ openclaw gateway run
Loguj surowe zdarzenia strumienia modelu do jsonl.
</ParamField>
<ParamField path="--raw-stream-path <path>" type="string">
Ścieżka jsonl surowego strumienia.
Ścieżka surowego strumienia jsonl.
</ParamField>
<Warning>
Wbudowane `--password` może być widoczne w lokalnych listach procesów. Preferuj `--password-file`, env albo `gateway.auth.password` oparte na SecretRef.
Wbudowane `--password` może zostać ujawnione w lokalnych listach procesów. Preferuj `--password-file`, env albo `gateway.auth.password` oparte na SecretRef.
</Warning>
### Profilowanie startu
### Profilowanie uruchamiania
- Ustaw `OPENCLAW_GATEWAY_STARTUP_TRACE=1`, aby logować czasy faz podczas startu Gateway, w tym opóźnienie `eventLoopMax` dla każdej fazy oraz czasy tabel wyszukiwania pluginów dla zainstalowanego indeksu, rejestru manifestów, planowania startu i pracy nad owner-map.
- Ustaw `OPENCLAW_DIAGNOSTICS=timeline` z `OPENCLAW_DIAGNOSTICS_TIMELINE_PATH=<path>`, aby zapisać best-effort oś czasu diagnostyki startu JSONL dla zewnętrznych harnessów QA. Możesz też włączyć flagę przez `diagnostics.flags: ["timeline"]` w konfiguracji; ścieżka nadal jest podawana przez env. Dodaj `OPENCLAW_DIAGNOSTICS_EVENT_LOOP=1`, aby uwzględnić próbki pętli zdarzeń.
- Uruchom `pnpm test:startup:gateway -- --runs 5 --warmup 1`, aby zmierzyć wydajność startu Gateway. Benchmark rejestruje pierwsze wyjście procesu, `/healthz`, `/readyz`, czasy śladu startu, opóźnienie pętli zdarzeń oraz szczegóły czasów tabel wyszukiwania pluginów.
- Ustaw `OPENCLAW_GATEWAY_STARTUP_TRACE=1`, aby logować czasy faz podczas startu Gateway, w tym opóźnienie `eventLoopMax` dla każdej fazy oraz czasy tabel wyszukiwania pluginów dla installed-index, rejestru manifestów, planowania startu i pracy owner-map.
- Ustaw `OPENCLAW_DIAGNOSTICS=timeline` z `OPENCLAW_DIAGNOSTICS_TIMELINE_PATH=<path>`, aby zapisać best-effort oś czasu diagnostyki startu JSONL dla zewnętrznych harnessów QA. Możesz też włączyć flagę przez `diagnostics.flags: ["timeline"]` w konfiguracji; ścieżka nadal jest dostarczana przez env. Dodaj `OPENCLAW_DIAGNOSTICS_EVENT_LOOP=1`, aby uwzględnić próbki event-loop.
- Uruchom `pnpm test:startup:gateway -- --runs 5 --warmup 1`, aby wykonać benchmark startu Gateway. Benchmark rejestruje pierwsze wyjście procesu, `/healthz`, `/readyz`, czasy śladu startu, opóźnienie event-loop oraz szczegóły czasów tabel wyszukiwania pluginów.
## Odpytywanie działającego Gateway
Wszystkie polecenia zapytań używają RPC WebSocket.
Wszystkie komendy zapytań używają RPC przez WebSocket.
<Tabs>
<Tab title="Output modes">
- Domyślnie: czytelne dla człowieka (kolorowane w TTY).
- `--json`: czytelny maszynowo JSON (bez stylowania/spinnera).
- `--no-color` (lub `NO_COLOR=1`): wyłącz ANSI, zachowując układ dla człowieka.
<Tab title="Tryby wyjścia">
- Domyślnie: czytelne dla człowieka (kolorowe w TTY).
- `--json`: JSON czytelny maszynowo (bez stylowania/spinnera).
- `--no-color` (lub `NO_COLOR=1`): wyłącza ANSI, zachowując układ czytelny dla człowieka.
</Tab>
<Tab title="Shared options">
<Tab title="Opcje wspólne">
- `--url <url>`: URL WebSocket Gateway.
- `--token <token>`: token Gateway.
- `--password <password>`: hasło Gateway.
- `--timeout <ms>`: limit czasu/budżet (różni się zależnie od polecenia).
- `--timeout <ms>`: timeout/budżet (różni się w zależności od komendy).
- `--expect-final`: czekaj na odpowiedź „final” (wywołania agenta).
</Tab>
</Tabs>
<Note>
Gdy ustawiasz `--url`, CLI nie wraca do danych uwierzytelniających z konfiguracji ani środowiska. Przekaż jawnie `--token` lub `--password`. Brak jawnych danych uwierzytelniających jest błędem.
Gdy ustawisz `--url`, CLI nie wraca do konfiguracji ani poświadczeń środowiskowych. Przekaż jawnie `--token` lub `--password`. Brak jawnych poświadczeń jest błędem.
</Note>
### `gateway health`
@ -153,7 +153,7 @@ Gdy ustawiasz `--url`, CLI nie wraca do danych uwierzytelniających z konfigurac
openclaw gateway health --url ws://127.0.0.1:18789
```
Endpoint HTTP `/healthz` jest sondą żywotności: zwraca odpowiedź, gdy serwer może odpowiadać przez HTTP. Endpoint HTTP `/readyz` jest bardziej rygorystyczny i pozostaje czerwony, dopóki sidecary startowe, kanały lub skonfigurowane hooki wciąż się stabilizują. Lokalne lub uwierzytelnione szczegółowe odpowiedzi gotowości zawierają blok diagnostyczny `eventLoop` z opóźnieniem pętli zdarzeń, wykorzystaniem pętli zdarzeń, stosunkiem rdzeni CPU oraz flagą `degraded`.
Endpoint HTTP `/healthz` jest sondą żywotności: zwraca odpowiedź, gdy serwer może odpowiadać przez HTTP. Endpoint HTTP `/readyz` jest bardziej rygorystyczny i pozostaje czerwony, dopóki zależności runtime pluginów startowych, sidecary, kanały lub skonfigurowane hooki nadal się stabilizują. Lokalne lub uwierzytelnione szczegółowe odpowiedzi gotowości zawierają blok diagnostyczny `eventLoop` z opóźnieniem event-loop, wykorzystaniem event-loop, współczynnikiem rdzeni CPU i flagą `degraded`.
### `gateway usage-cost`
@ -171,7 +171,7 @@ openclaw gateway usage-cost --json
### `gateway stability`
Pobierz najnowszy rejestrator stabilności diagnostycznej z działającego Gateway.
Pobierz ostatni rejestrator stabilności diagnostycznej z działającego Gateway.
```bash
openclaw gateway stability
@ -182,7 +182,7 @@ openclaw gateway stability --json
```
<ParamField path="--limit <limit>" type="number" default="25">
Maksymalna liczba najnowszych zdarzeń do uwzględnienia (maks. `1000`).
Maksymalna liczba ostatnich zdarzeń do uwzględnienia (maks. `1000`).
</ParamField>
<ParamField path="--type <type>" type="string">
Filtruj według typu zdarzenia diagnostycznego, takiego jak `payload.large` lub `diagnostic.memory.pressure`.
@ -201,16 +201,16 @@ openclaw gateway stability --json
</ParamField>
<AccordionGroup>
<Accordion title="Privacy and bundle behavior">
- Rekordy zachowują metadane operacyjne: nazwy zdarzeń, liczby, rozmiary bajtów, odczyty pamięci, stan kolejki/sesji, nazwy kanałów/pluginów oraz zredagowane podsumowania sesji. Nie przechowują tekstu czatu, treści webhooków, wyników narzędzi, surowych treści żądań ani odpowiedzi, tokenów, ciasteczek, wartości sekretów, nazw hostów ani surowych identyfikatorów sesji. Ustaw `diagnostics.enabled: false`, aby całkowicie wyłączyć rejestrator.
- Przy krytycznych wyjściach Gateway, timeoutach zamykania i niepowodzeniach startu po restarcie OpenClaw zapisuje tę samą migawkę diagnostyczną do `~/.openclaw/logs/stability/openclaw-stability-*.json`, gdy rejestrator ma zdarzenia. Sprawdź najnowszy pakiet poleceniem `openclaw gateway stability --bundle latest`; `--limit`, `--type` i `--since-seq` mają też zastosowanie do wyjścia pakietu.
<Accordion title="Prywatność i zachowanie pakietu">
- Rekordy zachowują metadane operacyjne: nazwy zdarzeń, liczby, rozmiary bajtów, odczyty pamięci, stan kolejki/sesji, nazwy kanałów/pluginów i zredagowane podsumowania sesji. Nie zachowują tekstu czatu, treści webhooków, wyników narzędzi, surowych treści żądań ani odpowiedzi, tokenów, cookies, wartości sekretów, nazw hostów ani surowych identyfikatorów sesji. Ustaw `diagnostics.enabled: false`, aby całkowicie wyłączyć rejestrator.
- Przy krytycznych wyjściach Gateway, timeoutach zamykania i niepowodzeniach startu po restarcie OpenClaw zapisuje ten sam snapshot diagnostyczny do `~/.openclaw/logs/stability/openclaw-stability-*.json`, gdy rejestrator ma zdarzenia. Sprawdź najnowszy pakiet przez `openclaw gateway stability --bundle latest`; `--limit`, `--type` i `--since-seq` mają zastosowanie także do wyjścia pakietu.
</Accordion>
</AccordionGroup>
### `gateway diagnostics export`
Zapisz lokalny zip diagnostyki przeznaczony do dołączania do zgłoszeń błędów. Model prywatności i zawartość pakietu opisuje [Eksport diagnostyki](/pl/gateway/diagnostics).
Zapisz lokalny zip diagnostyki zaprojektowany do dołączania do zgłoszeń błędów. Model prywatności i zawartość pakietu opisuje [Eksport diagnostyki](/pl/gateway/diagnostics).
```bash
openclaw gateway diagnostics export
@ -219,7 +219,7 @@ openclaw gateway diagnostics export --json
```
<ParamField path="--output <path>" type="string">
Ścieżka wyjściowa zip. Domyślnie jest to eksport wsparcia w katalogu stanu.
Ścieżka wyjściowa zip. Domyślnie eksport wsparcia w katalogu stanu.
</ParamField>
<ParamField path="--log-lines <count>" type="number" default="5000">
Maksymalna liczba oczyszczonych linii logów do uwzględnienia.
@ -228,16 +228,16 @@ openclaw gateway diagnostics export --json
Maksymalna liczba bajtów logów do sprawdzenia.
</ParamField>
<ParamField path="--url <url>" type="string">
URL WebSocket Gateway dla migawki zdrowia.
URL WebSocket Gateway dla snapshotu zdrowia.
</ParamField>
<ParamField path="--token <token>" type="string">
Token Gateway dla migawki zdrowia.
Token Gateway dla snapshotu zdrowia.
</ParamField>
<ParamField path="--password <password>" type="string">
Hasło Gateway dla migawki zdrowia.
Hasło Gateway dla snapshotu zdrowia.
</ParamField>
<ParamField path="--timeout <ms>" type="number" default="3000">
Timeout migawki statusu/zdrowia.
Timeout snapshotu statusu/zdrowia.
</ParamField>
<ParamField path="--no-stability-bundle" type="boolean">
Pomiń wyszukiwanie utrwalonego pakietu stabilności.
@ -246,13 +246,13 @@ openclaw gateway diagnostics export --json
Wypisz zapisaną ścieżkę, rozmiar i manifest jako JSON.
</ParamField>
Eksport zawiera manifest, podsumowanie Markdown, kształt konfiguracji, oczyszczone szczegóły konfiguracji, oczyszczone podsumowania logów, oczyszczone migawki statusu/zdrowia Gateway oraz najnowszy pakiet stabilności, jeśli istnieje.
Eksport zawiera manifest, podsumowanie Markdown, kształt konfiguracji, oczyszczone szczegóły konfiguracji, oczyszczone podsumowania logów, oczyszczone snapshoty statusu/zdrowia Gateway oraz najnowszy pakiet stabilności, jeśli istnieje.
Jest przeznaczony do udostępniania. Zachowuje szczegóły operacyjne pomagające w debugowaniu, takie jak bezpieczne pola logów OpenClaw, nazwy podsystemów, kody statusu, czasy trwania, skonfigurowane tryby, porty, identyfikatory pluginów, identyfikatory providerów, niesekretne ustawienia funkcji i zredagowane operacyjne komunikaty logów. Pomija lub redaguje tekst czatu, treści webhooków, wyniki narzędzi, dane uwierzytelniające, ciasteczka, identyfikatory kont/wiadomości, tekst promptów/instrukcji, nazwy hostów i wartości sekretów. Gdy komunikat w stylu LogTape wygląda jak tekst payloadu użytkownika/czatu/narzędzia, eksport zachowuje tylko informację, że komunikat został pominięty, oraz liczbę jego bajtów.
Jest przeznaczony do udostępniania. Zachowuje szczegóły operacyjne pomagające w debugowaniu, takie jak bezpieczne pola logów OpenClaw, nazwy podsystemów, kody statusu, czasy trwania, skonfigurowane tryby, porty, identyfikatory pluginów, identyfikatory dostawców, niesekretne ustawienia funkcji i zredagowane operacyjne komunikaty logów. Pomija lub redaguje tekst czatu, treści webhooków, wyniki narzędzi, poświadczenia, cookies, identyfikatory kont/wiadomości, tekst promptów/instrukcji, nazwy hostów i wartości sekretów. Gdy komunikat w stylu LogTape wygląda jak tekst payloadu użytkownika/czatu/narzędzia, eksport zachowuje tylko informację, że komunikat został pominięty, oraz jego liczbę bajtów.
### `gateway status`
`gateway status` pokazuje usługę Gateway (launchd/systemd/schtasks) oraz opcjonalną sondę łączności/możliwości uwierzytelnienia.
`gateway status` pokazuje usługę Gateway (launchd/systemd/schtasks) oraz opcjonalną sondę łączności/możliwości uwierzytelniania.
```bash
openclaw gateway status
@ -261,7 +261,7 @@ openclaw gateway status --require-rpc
```
<ParamField path="--url <url>" type="string">
Dodaj jawny cel sondowania. Skonfigurowane zdalne + localhost nadal są sondowane.
Dodaj jawny cel sondy. Skonfigurowany zdalny + localhost nadal są sondowane.
</ParamField>
<ParamField path="--token <token>" type="string">
Uwierzytelnianie tokenem dla sondy.
@ -276,48 +276,48 @@ openclaw gateway status --require-rpc
Pomiń sondę łączności (widok tylko usługi).
</ParamField>
<ParamField path="--deep" type="boolean">
Skanuj również usługi systemowe.
Skanuj także usługi na poziomie systemu.
</ParamField>
<ParamField path="--require-rpc" type="boolean">
Podnieś domyślną sondę łączności do sondy odczytu i zakończ z kodem niezerowym, gdy ta sonda odczytu się nie powiedzie. Nie można łączyć z `--no-probe`.
Ulepsz domyślną sondę łączności do sondy odczytu i zakończ z kodem niezerowym, gdy ta sonda odczytu się nie powiedzie. Nie można łączyć z `--no-probe`.
</ParamField>
<AccordionGroup>
<Accordion title="Status semantics">
<Accordion title="Semantyka statusu">
- `gateway status` pozostaje dostępne do diagnostyki nawet wtedy, gdy lokalna konfiguracja CLI jest brakująca lub nieprawidłowa.
- Domyślne `gateway status` potwierdza stan usługi, połączenie WebSocket oraz możliwość uwierzytelniania widoczną w czasie uzgadniania. Nie potwierdza operacji odczytu/zapisu/administrowania.
- Sondy diagnostyczne nie modyfikują stanu przy pierwszym uwierzytelnianiu urządzenia: używają ponownie istniejącego tokenu urządzenia z pamięci podręcznej, jeśli taki istnieje, ale nie tworzą nowej tożsamości urządzenia CLI ani rekordu parowania urządzenia tylko do odczytu wyłącznie po to, aby sprawdzić status.
- `gateway status` w miarę możliwości rozwiązuje skonfigurowane SecretRefs uwierzytelniania na potrzeby uwierzytelniania sondy.
- Jeśli wymagany SecretRef uwierzytelniania nie zostanie rozwiązany w tej ścieżce polecenia, `gateway status --json` zgłasza `rpc.authWarning`, gdy łączność/uwierzytelnianie sondy się nie powiedzie; przekaż jawnie `--token`/`--password` albo najpierw rozwiąż źródło sekretu.
- Jeśli sonda powiedzie się, ostrzeżenia o nierozwiązanych odwołaniach uwierzytelniania są pomijane, aby uniknąć fałszywych alarmów.
- Używaj `--require-rpc` w skryptach i automatyzacji, gdy nasłuchująca usługa nie wystarcza i wywołania RPC z zakresem odczytu także muszą być sprawne.
- `--deep` dodaje best-effort skanowanie dodatkowych instalacji launchd/systemd/schtasks. Gdy wykryto wiele usług podobnych do Gateway, wynik dla człowieka wypisuje wskazówki dotyczące czyszczenia i ostrzega, że większość konfiguracji powinna uruchamiać jeden Gateway na maszynę.
- Wynik dla człowieka obejmuje rozwiązaną ścieżkę pliku dziennika oraz migawkę ścieżek konfiguracji/ważności CLI względem usługi, aby pomóc diagnozować dryf profilu lub katalogu stanu.
- Domyślne `gateway status` potwierdza stan usługi, połączenie WebSocket oraz możliwość uwierzytelniania widoczną w czasie uzgadniania połączenia. Nie potwierdza operacji odczytu/zapisu/administracyjnych.
- Próby diagnostyczne nie modyfikują stanu przy pierwszym uwierzytelnieniu urządzenia: ponownie używają istniejącego buforowanego tokenu urządzenia, jeśli taki istnieje, ale nie tworzą nowej tożsamości urządzenia CLI ani rekordu parowania urządzenia tylko do odczytu wyłącznie po to, aby sprawdzić status.
- `gateway status` rozwiązuje skonfigurowane SecretRefs uwierzytelniania na potrzeby uwierzytelnienia próby, gdy jest to możliwe.
- Jeśli wymagany SecretRef uwierzytelniania nie zostanie rozwiązany w tej ścieżce polecenia, `gateway status --json` zgłasza `rpc.authWarning`, gdy łączność/uwierzytelnienie próby zawiedzie; przekaż jawnie `--token`/`--password` albo najpierw rozwiąż źródło sekretu.
- Jeśli próba się powiedzie, ostrzeżenia o nierozwiązanych odwołaniach uwierzytelniania są pomijane, aby uniknąć fałszywych alarmów.
- Używaj `--require-rpc` w skryptach i automatyzacji, gdy nasłuchująca usługa nie wystarcza i potrzebujesz także sprawnych wywołań RPC z zakresem odczytu.
- `--deep` dodaje najlepszą możliwą próbę skanowania dodatkowych instalacji launchd/systemd/schtasks. Gdy wykryto wiele usług podobnych do Gateway, wynik dla człowieka wypisuje wskazówki czyszczenia i ostrzega, że większość konfiguracji powinna uruchamiać jeden gateway na maszynę.
- Wynik dla człowieka zawiera rozwiązaną ścieżkę pliku dziennika oraz migawkę ścieżek/ważności konfiguracji CLI względem usługi, aby pomóc diagnozować rozjazd profilu lub katalogu stanu.
</Accordion>
<Accordion title="Linux systemd auth-drift checks">
- W instalacjach Linux systemd kontrole dryfu uwierzytelniania usługi odczytują z jednostki zarówno wartości `Environment=`, jak i `EnvironmentFile=` (w tym `%h`, ścieżki w cudzysłowach, wiele plików oraz opcjonalne pliki `-`).
- Kontrole dryfu rozwiązują SecretRefs `gateway.auth.token` z użyciem scalonego środowiska uruchomieniowego (najpierw środowisko polecenia usługi, potem rezerwowo środowisko procesu).
- Jeśli uwierzytelnianie tokenem nie jest faktycznie aktywne (jawne `gateway.auth.mode` równe `password`/`none`/`trusted-proxy` albo tryb nieustawiony, gdy hasło może wygrać i żaden kandydat tokenu nie może wygrać), kontrole dryfu tokenu pomijają rozwiązywanie tokenu konfiguracji.
<Accordion title="Kontrole rozjazdu uwierzytelniania w Linux systemd">
- W instalacjach Linux systemd kontrole rozjazdu uwierzytelniania usługi odczytują zarówno wartości `Environment=`, jak i `EnvironmentFile=` z jednostki (w tym `%h`, ścieżki w cudzysłowach, wiele plików oraz opcjonalne pliki `-`).
- Kontrole rozjazdu rozwiązują SecretRefs `gateway.auth.token` przy użyciu scalonego środowiska runtime (najpierw środowisko polecenia usługi, następnie awaryjnie środowisko procesu).
- Jeśli uwierzytelnianie tokenem nie jest efektywnie aktywne (jawny `gateway.auth.mode` o wartości `password`/`none`/`trusted-proxy` albo brak ustawionego trybu, gdy hasło może wygrać i żaden kandydat na token nie może wygrać), kontrole rozjazdu tokenu pomijają rozwiązywanie tokenu konfiguracji.
</Accordion>
</AccordionGroup>
### `gateway probe`
`gateway probe` to polecenie „debuguj wszystko”. Zawsze sonduje:
`gateway probe` to polecenie „debugowania wszystkiego”. Zawsze sprawdza:
- skonfigurowany zdalny Gateway (jeśli ustawiony) oraz
- localhost (loopback) **nawet jeśli skonfigurowano zdalny Gateway**.
- skonfigurowany zdalny gateway (jeśli ustawiony), oraz
- localhost (local loopback) **nawet jeśli zdalny jest skonfigurowany**.
Jeśli przekażesz `--url`, ten jawny cel zostanie dodany przed oboma powyższymi. Wynik dla człowieka oznacza cele jako:
Jeśli przekażesz `--url`, ten jawny cel zostanie dodany przed oboma pozostałymi. Wynik dla człowieka oznacza cele jako:
- `URL (explicit)`
- `Remote (configured)` albo `Remote (configured, inactive)`
- `Remote (configured)` lub `Remote (configured, inactive)`
- `Local loopback`
<Note>
Jeśli dostępnych jest wiele Gateway, polecenie wypisuje je wszystkie. Wiele Gateway jest obsługiwanych, gdy używasz izolowanych profili/portów (np. bota ratunkowego), ale większość instalacji nadal uruchamia pojedynczy Gateway.
Jeśli osiągalnych jest wiele gateways, wypisuje je wszystkie. Wiele gateways jest obsługiwanych, gdy używasz izolowanych profili/portów (np. bota ratunkowego), ale większość instalacji nadal uruchamia pojedynczy gateway.
</Note>
```bash
@ -326,26 +326,26 @@ openclaw gateway probe --json
```
<AccordionGroup>
<Accordion title="Interpretation">
<Accordion title="Interpretacja">
- `Reachable: yes` oznacza, że co najmniej jeden cel zaakceptował połączenie WebSocket.
- `Capability: read-only|write-capable|admin-capable|pairing-pending|connect-only` zgłasza, co sonda mogła potwierdzić o uwierzytelnianiu. Jest to oddzielne od osiągalności.
- `Read probe: ok` oznacza, że szczegółowe wywołania RPC z zakresem odczytu (`health`/`status`/`system-presence`/`config.get`) również się powiodły.
- `Read probe: limited - missing scope: operator.read` oznacza, że połączenie się powiodło, ale RPC z zakresem odczytu jest ograniczone. Jest to zgłaszane jako **zdegradowana** osiągalność, a nie pełna awaria.
- `Read probe: failed` po `Connect: ok` oznacza, że Gateway zaakceptował połączenie WebSocket, ale kolejne diagnostyki odczytu przekroczyły limit czasu albo się nie powiodły. To także jest **zdegradowana** osiągalność, a nie nieosiągalny Gateway.
- Podobnie jak `gateway status`, sonda używa ponownie istniejącego uwierzytelniania urządzenia z pamięci podręcznej, ale nie tworzy pierwszej tożsamości urządzenia ani stanu parowania.
- Kod wyjścia jest niezerowy tylko wtedy, gdy żaden sondowany cel nie jest osiągalny.
- `Capability: read-only|write-capable|admin-capable|pairing-pending|connect-only` zgłasza, co próba zdołała potwierdzić w zakresie uwierzytelniania. Jest to oddzielne od osiągalności.
- `Read probe: ok` oznacza, że wywołania RPC szczegółów z zakresem odczytu (`health`/`status`/`system-presence`/`config.get`) również się powiodły.
- `Read probe: limited - missing scope: operator.read` oznacza, że połączenie się powiodło, ale RPC z zakresem odczytu jest ograniczone. Jest to zgłaszane jako **zdegradowana** osiągalność, nie pełna awaria.
- `Read probe: failed` po `Connect: ok` oznacza, że Gateway zaakceptował połączenie WebSocket, ale kolejne diagnostyki odczytu przekroczyły limit czasu lub zawiodły. To również jest **zdegradowana** osiągalność, nie nieosiągalny Gateway.
- Podobnie jak `gateway status`, probe ponownie używa istniejącego buforowanego uwierzytelniania urządzenia, ale nie tworzy pierwszej tożsamości urządzenia ani stanu parowania.
- Kod wyjścia jest niezerowy tylko wtedy, gdy żaden sprawdzany cel nie jest osiągalny.
</Accordion>
<Accordion title="JSON output">
Poziom główny:
<Accordion title="Wynik JSON">
Najwyższy poziom:
- `ok`: co najmniej jeden cel jest osiągalny.
- `degraded`: co najmniej jeden cel zaakceptował połączenie, ale nie ukończył pełnej szczegółowej diagnostyki RPC.
- `capability`: najlepsza możliwość widziana we wszystkich osiągalnych celach (`read_only`, `write_capable`, `admin_capable`, `pairing_pending`, `connected_no_operator_scope` albo `unknown`).
- `primaryTargetId`: najlepszy cel do traktowania jako aktywnego zwycięzcę w tej kolejności: jawny URL, tunel SSH, skonfigurowany zdalny cel, a następnie local loopback.
- `warnings[]`: best-effort rekordy ostrzeżeń z `code`, `message` i opcjonalnym `targetIds`.
- `network`: wskazówki URL local loopback/tailnet wyprowadzone z bieżącej konfiguracji i sieci hosta.
- `discovery.timeoutMs` i `discovery.count`: rzeczywisty budżet wykrywania/liczba wyników użyte w tym przebiegu sondy.
- `degraded`: co najmniej jeden cel zaakceptował połączenie, ale nie ukończył pełnej diagnostyki szczegółowej RPC.
- `capability`: najlepsza możliwość widziana wśród osiągalnych celów (`read_only`, `write_capable`, `admin_capable`, `pairing_pending`, `connected_no_operator_scope` lub `unknown`).
- `primaryTargetId`: najlepszy cel do potraktowania jako aktywnego zwycięzcę w tej kolejności: jawny URL, tunel SSH, skonfigurowany zdalny, następnie local loopback.
- `warnings[]`: rekordy ostrzeżeń typu best-effort z `code`, `message` i opcjonalnymi `targetIds`.
- `network`: wskazówki URL local loopback/tailnet pochodzące z bieżącej konfiguracji i sieci hosta.
- `discovery.timeoutMs` i `discovery.count`: rzeczywisty budżet wykrywania/liczba wyników użyte dla tego przebiegu próby.
Dla celu (`targets[].connect`):
@ -357,21 +357,21 @@ openclaw gateway probe --json
- `role`: rola uwierzytelniania zgłoszona w `hello-ok`, gdy dostępna.
- `scopes`: przyznane zakresy zgłoszone w `hello-ok`, gdy dostępne.
- `capability`: udostępniona klasyfikacja możliwości uwierzytelniania dla tego celu.
- `capability`: ujawniona klasyfikacja możliwości uwierzytelniania dla tego celu.
</Accordion>
<Accordion title="Common warning codes">
- `ssh_tunnel_failed`: konfiguracja tunelu SSH nie powiodła się; polecenie wróciło do bezpośrednich sond.
- `multiple_gateways`: więcej niż jeden cel był osiągalny; to nietypowe, chyba że celowo uruchamiasz izolowane profile, takie jak bot ratunkowy.
- `auth_secretref_unresolved`: skonfigurowany SecretRef uwierzytelniania nie mógł zostać rozwiązany dla celu, który się nie powiódł.
- `probe_scope_limited`: połączenie WebSocket się powiodło, ale sonda odczytu była ograniczona przez brakujący `operator.read`.
<Accordion title="Typowe kody ostrzeżeń">
- `ssh_tunnel_failed`: konfiguracja tunelu SSH nie powiodła się; polecenie wróciło do bezpośrednich prób.
- `multiple_gateways`: osiągalny był więcej niż jeden cel; jest to nietypowe, chyba że celowo uruchamiasz izolowane profile, takie jak bot ratunkowy.
- `auth_secretref_unresolved`: skonfigurowany SecretRef uwierzytelniania nie mógł zostać rozwiązany dla celu, który zawiódł.
- `probe_scope_limited`: połączenie WebSocket się powiodło, ale próba odczytu została ograniczona przez brakujące `operator.read`.
</Accordion>
</AccordionGroup>
#### Zdalnie przez SSH (parzystość aplikacji Mac)
#### Zdalnie przez SSH (parytet aplikacji Mac)
Tryb „Remote over SSH” w aplikacji macOS używa lokalnego przekierowania portu, dzięki czemu zdalny Gateway (który może być powiązany tylko z loopback) staje się osiągalny pod `ws://127.0.0.1:<port>`.
Tryb aplikacji macOS „Remote over SSH” używa lokalnego przekierowania portu, dzięki czemu zdalny gateway (który może być przypisany tylko do loopback) staje się osiągalny pod `ws://127.0.0.1:<port>`.
Odpowiednik CLI:
@ -380,13 +380,13 @@ openclaw gateway probe --ssh user@gateway-host
```
<ParamField path="--ssh <target>" type="string">
`user@host` albo `user@host:port` (port domyślnie `22`).
`user@host` lub `user@host:port` (port domyślnie `22`).
</ParamField>
<ParamField path="--ssh-identity <path>" type="string">
Plik tożsamości.
</ParamField>
<ParamField path="--ssh-auto" type="boolean">
Wybierz pierwszy wykryty host Gateway jako cel SSH z rozwiązanego punktu końcowego wykrywania (`local.` plus skonfigurowana domena rozległa, jeśli istnieje). Wskazówki tylko TXT są ignorowane.
Wybierz pierwszy wykryty host gateway jako cel SSH z rozwiązanego punktu końcowego wykrywania (`local.` plus skonfigurowana domena rozległa, jeśli istnieje). Wskazówki tylko TXT są ignorowane.
</ParamField>
Konfiguracja (opcjonalna, używana jako wartości domyślne):
@ -404,7 +404,7 @@ openclaw gateway call logs.tail --params '{"sinceMs": 60000}'
```
<ParamField path="--params <json>" type="string" default="{}">
Łańcuch obiektu JSON dla parametrów.
Ciąg obiektu JSON dla parametrów.
</ParamField>
<ParamField path="--url <url>" type="string">
URL WebSocket Gateway.
@ -441,7 +441,7 @@ openclaw gateway uninstall
### Instalacja z wrapperem
Użyj `--wrapper`, gdy zarządzana usługa musi startować przez inny plik wykonywalny, na przykład shim menedżera sekretów albo pomocnik run-as. Wrapper otrzymuje normalne argumenty Gateway i odpowiada za to, aby ostatecznie wykonać `openclaw` albo Node z tymi argumentami.
Użyj `--wrapper`, gdy zarządzana usługa musi wystartować przez inny plik wykonywalny, na przykład shim menedżera sekretów albo pomocnik uruchamiania jako inny użytkownik. Wrapper otrzymuje normalne argumenty Gateway i odpowiada za ostateczne wykonanie `openclaw` albo Node z tymi argumentami.
```bash
cat > ~/.local/bin/openclaw-doppler <<'EOF'
@ -455,7 +455,7 @@ openclaw gateway install --wrapper ~/.local/bin/openclaw-doppler --force
openclaw gateway restart
```
Wrapper można też ustawić przez środowisko. `gateway install` sprawdza, czy ścieżka jest plikiem wykonywalnym, zapisuje wrapper w `ProgramArguments` usługi i utrwala `OPENCLAW_WRAPPER` w środowisku usługi na potrzeby późniejszych wymuszonych reinstalacji, aktualizacji i napraw doctor.
Możesz też ustawić wrapper przez środowisko. `gateway install` sprawdza, czy ścieżka jest plikiem wykonywalnym, zapisuje wrapper w `ProgramArguments` usługi oraz utrwala `OPENCLAW_WRAPPER` w środowisku usługi na potrzeby późniejszych wymuszonych reinstalacji, aktualizacji i napraw doctor.
```bash
OPENCLAW_WRAPPER="$HOME/.local/bin/openclaw-doppler" openclaw gateway install --force
@ -470,39 +470,39 @@ openclaw gateway restart
```
<AccordionGroup>
<Accordion title="Command options">
<Accordion title="Opcje poleceń">
- `gateway status`: `--url`, `--token`, `--password`, `--timeout`, `--no-probe`, `--require-rpc`, `--deep`, `--json`
- `gateway install`: `--port`, `--runtime <node|bun>`, `--token`, `--wrapper <path>`, `--force`, `--json`
- `gateway uninstall|start|stop|restart`: `--json`
</Accordion>
<Accordion title="Lifecycle behavior">
- Użyj `gateway restart`, aby ponownie uruchomić zarządzaną usługę. Nie łącz `gateway stop` i `gateway start` jako zamiennika restartu; w macOS `gateway stop` celowo wyłącza LaunchAgent przed jego zatrzymaniem.
- Polecenia cyklu życia akceptują `--json` na potrzeby skryptów.
<Accordion title="Zachowanie cyklu życia">
- Użyj `gateway restart`, aby zrestartować zarządzaną usługę. Nie łącz `gateway stop` i `gateway start` jako substytutu restartu; w macOS `gateway stop` celowo wyłącza LaunchAgent przed jego zatrzymaniem.
- Polecenia cyklu życia akceptują `--json` do skryptów.
</Accordion>
<Accordion title="Auth and SecretRefs at install time">
- Gdy uwierzytelnianie tokenem wymaga tokenu, a `gateway.auth.token` jest zarządzane przez SecretRef, `gateway install` sprawdza, czy SecretRef można rozwiązać, ale nie utrwala rozwiązanego tokenu w metadanych środowiska usługi.
- Jeśli uwierzytelnianie tokenem wymaga tokenu, a skonfigurowany SecretRef tokenu jest nierozwiązany, instalacja kończy się zamkniętą awarią zamiast utrwalać rezerwowy tekst jawny.
- Dla uwierzytelniania hasłem w `gateway run` preferuj `OPENCLAW_GATEWAY_PASSWORD`, `--password-file` albo `gateway.auth.password` oparte na SecretRef zamiast wbudowanego `--password`.
- W wywnioskowanym trybie uwierzytelniania `OPENCLAW_GATEWAY_PASSWORD` ustawione tylko w powłoce nie rozluźnia wymagań tokenu przy instalacji; podczas instalowania zarządzanej usługi użyj trwałej konfiguracji (`gateway.auth.password` albo `env` konfiguracji).
- Jeśli skonfigurowano zarówno `gateway.auth.token`, jak i `gateway.auth.password`, a `gateway.auth.mode` jest nieustawione, instalacja jest blokowana do czasu jawnego ustawienia trybu.
<Accordion title="Uwierzytelnianie i SecretRefs podczas instalacji">
- Gdy uwierzytelnianie tokenem wymaga tokenu, a `gateway.auth.token` jest zarządzany przez SecretRef, `gateway install` sprawdza, czy SecretRef da się rozwiązać, ale nie utrwala rozwiązanego tokenu w metadanych środowiska usługi.
- Jeśli uwierzytelnianie tokenem wymaga tokenu, a skonfigurowany SecretRef tokenu jest nierozwiązany, instalacja kończy się bezpieczną odmową zamiast utrwalać awaryjny tekst jawny.
- Dla uwierzytelniania hasłem w `gateway run` preferuj `OPENCLAW_GATEWAY_PASSWORD`, `--password-file` albo `gateway.auth.password` wspierane przez SecretRef zamiast wbudowanego `--password`.
- W wywnioskowanym trybie uwierzytelniania wyłącznie powłokowe `OPENCLAW_GATEWAY_PASSWORD` nie rozluźnia wymagań tokenu instalacji; użyj trwałej konfiguracji (`gateway.auth.password` lub `env` konfiguracji) podczas instalowania zarządzanej usługi.
- Jeśli skonfigurowane są zarówno `gateway.auth.token`, jak i `gateway.auth.password`, a `gateway.auth.mode` nie jest ustawione, instalacja jest blokowana do czasu jawnego ustawienia trybu.
</Accordion>
</AccordionGroup>
## Wykrywanie Gateway (Bonjour)
## Wykrywanie gateways (Bonjour)
`gateway discover` skanuje sygnały nawigacyjne Gateway (`_openclaw-gw._tcp`).
`gateway discover` skanuje beacony Gateway (`_openclaw-gw._tcp`).
- Multicast DNS-SD: `local.`
- Unicast DNS-SD (Wide-Area Bonjour): wybierz domenę (przykład: `openclaw.internal.`) i skonfiguruj split DNS + serwer DNS; zobacz [Bonjour](/pl/gateway/bonjour).
Tylko Gateway z włączonym wykrywaniem Bonjour (domyślnie) ogłaszają sygnał nawigacyjny.
Tylko gateways z włączonym wykrywaniem Bonjour (domyślnie) reklamują beacon.
Rekordy wykrywania Wide-Area obejmują (TXT):
Rekordy wykrywania Wide-Area zawierają (TXT):
- `role` (wskazówka roli Gateway)
- `role` (wskazówka roli gateway)
- `transport` (wskazówka transportu, np. `gateway`)
- `gatewayPort` (port WebSocket, zwykle `18789`)
- `sshPort` (opcjonalny; klienci domyślnie ustawiają cele SSH na `22`, gdy go nie ma)
@ -520,7 +520,7 @@ openclaw gateway discover
Limit czasu dla polecenia (browse/resolve).
</ParamField>
<ParamField path="--json" type="boolean">
Wynik czytelny maszynowo (wyłącza również stylowanie/spinner).
Wynik czytelny maszynowo (wyłącza też stylizację/spinner).
</ParamField>
Przykłady:
@ -531,13 +531,13 @@ openclaw gateway discover --json | jq '.beacons[].wsUrl'
```
<Note>
- CLI skanuje `local.` oraz skonfigurowaną domenę rozległą, gdy jest włączona.
- `wsUrl` w danych wyjściowych JSON jest wyprowadzany z rozwiązanego punktu końcowego usługi, a nie ze wskazówek wyłącznie TXT, takich jak `lanHost` lub `tailnetDns`.
- W mDNS `local.` wartości `sshPort` i `cliPath` są rozgłaszane tylko wtedy, gdy `discovery.mdns.mode` ma wartość `full`. DNS-SD w sieci rozległej nadal zapisuje `cliPath`; `sshPort` również pozostaje tam opcjonalne.
- CLI skanuje `local.` oraz skonfigurowaną domenę sieci rozległej, gdy jest włączona.
- `wsUrl` w wyjściu JSON jest wyprowadzany z rozpoznanego punktu końcowego usługi, a nie z podpowiedzi wyłącznie TXT, takich jak `lanHost` lub `tailnetDns`.
- W mDNS `local.` wartości `sshPort` i `cliPath` są rozgłaszane tylko wtedy, gdy `discovery.mdns.mode` ma wartość `full`. DNS-SD w sieci rozległej nadal zapisuje `cliPath`; `sshPort` również tam pozostaje opcjonalne.
</Note>
## Powiązane
- [Dokumentacja CLI](/pl/cli)
- [Runbook Gateway](/pl/gateway)
- [Dokumentacja referencyjna CLI](/pl/cli)
- [Procedura operacyjna Gateway](/pl/gateway)

150
docs/pl/cli/models.md
View File

@ -1,26 +1,26 @@
---
read_when:
- Chcesz zmienić domyślne modele lub wyświetlić status uwierzytelniania dostawcy
- Chcesz zmienić domyślne modele lub wyświetlić stan uwierzytelniania dostawcy
- Chcesz przeskanować dostępne modele/dostawców i debugować profile uwierzytelniania
summary: Dokumentacja referencyjna CLI dla `openclaw models` (status/list/set/scan, aliasy, mechanizmy zastępcze, uwierzytelnianie)
summary: Dokumentacja referencyjna CLI dla `openclaw models` (status/list/set/scan, aliasy, mechanizmy rezerwowe, uwierzytelnianie)
title: Modele
x-i18n:
generated_at: "2026-04-30T09:44:40Z"
generated_at: "2026-05-01T09:56:47Z"
model: gpt-5.5
provider: openai
source_hash: 95e2361989b583f7f52947dad1faaaba44dc6a5f58719cc2e83c13fce7c33adc
source_hash: 538d3e4808329737fdc044dc6e14e5c7c78052e75d8a8b3b257b1ebd821c84d1
source_path: cli/models.md
workflow: 16
---
# `openclaw models`
Wykrywanie, skanowanie i konfiguracja modeli (model domyślny, modele zastępcze, profile uwierzytelniania).
Wykrywanie, skanowanie i konfiguracja modeli (model domyślny, modele awaryjne, profile uwierzytelniania).
Powiązane:
- Dostawcy + modele: [Modele](/pl/providers/models)
- Koncepcje wyboru modelu + polecenie slash `/models`: [Koncepcja modeli](/pl/concepts/models)
- Koncepcje wyboru modelu + polecenie ukośnikowe `/models`: [Koncepcja modeli](/pl/concepts/models)
- Konfiguracja uwierzytelniania dostawcy: [Pierwsze kroki](/pl/start/getting-started)
## Typowe polecenia
@ -32,66 +32,72 @@ openclaw models set <model-or-alias>
openclaw models scan
```
`openclaw models status` pokazuje rozstrzygnięty model domyślny/modele zastępcze oraz przegląd uwierzytelniania.
Gdy dostępne są migawki użycia dostawców, sekcja statusu OAuth/klucza API zawiera
okna użycia dostawców i migawki limitów.
Obecni dostawcy z oknami użycia: Anthropic, GitHub Copilot, Gemini CLI, OpenAI
Codex, MiniMax, Xiaomi i z.ai. Uwierzytelnianie użycia pochodzi z hooków właściwych
dla dostawcy, gdy są dostępne; w przeciwnym razie OpenClaw przechodzi do pasujących
danych uwierzytelniających OAuth/klucza API z profili uwierzytelniania, env lub konfiguracji.
W wyjściu `--json` `auth.providers` to przegląd dostawców świadomy env/konfiguracji/magazynu,
natomiast `auth.oauth` to wyłącznie kondycja profili magazynu uwierzytelniania.
Dodaj `--probe`, aby uruchomić sondy uwierzytelniania na żywo wobec każdego skonfigurowanego profilu dostawcy.
Sondy są rzeczywistymi żądaniami (mogą zużywać tokeny i wyzwalać limity szybkości).
Użyj `--agent <id>`, aby sprawdzić stan modelu/uwierzytelniania skonfigurowanego agenta. Gdy pominięte,
polecenie używa `OPENCLAW_AGENT_DIR`/`PI_CODING_AGENT_DIR`, jeśli są ustawione, a w przeciwnym razie
`openclaw models status` pokazuje rozwiązany model domyślny/modele awaryjne oraz przegląd uwierzytelniania.
Gdy dostępne są migawki użycia dostawcy, sekcja stanu OAuth/klucza API zawiera
okna użycia dostawcy i migawki limitów.
Obecni dostawcy okien użycia: Anthropic, GitHub Copilot, Gemini CLI, OpenAI
Codex, MiniMax, Xiaomi i z.ai. Uwierzytelnianie użycia pochodzi z haków specyficznych
dla dostawcy, gdy są dostępne; w przeciwnym razie OpenClaw wraca do pasujących
poświadczeń OAuth/klucza API z profili uwierzytelniania, środowiska lub konfiguracji.
W wyjściu `--json` `auth.providers` jest przeglądem dostawców świadomym
środowiska/konfiguracji/magazynu, natomiast `auth.oauth` obejmuje tylko kondycję
profili magazynu uwierzytelniania.
Dodaj `--probe`, aby uruchomić sondy uwierzytelniania na żywo względem każdego skonfigurowanego profilu dostawcy.
Sondy to rzeczywiste żądania (mogą zużywać tokeny i wyzwalać limity szybkości).
Użyj `--agent <id>`, aby sprawdzić stan modelu/uwierzytelniania skonfigurowanego agenta. Gdy pominięto,
polecenie używa `OPENCLAW_AGENT_DIR`/`PI_CODING_AGENT_DIR`, jeśli są ustawione, w przeciwnym razie
skonfigurowanego agenta domyślnego.
Wiersze sond mogą pochodzić z profili uwierzytelniania, danych uwierzytelniających env lub `models.json`.
Wiersze sond mogą pochodzić z profili uwierzytelniania, poświadczeń środowiskowych lub `models.json`.
Uwagi:
- `models set <model-or-alias>` akceptuje `provider/model` albo alias.
- `models list` jest tylko do odczytu: odczytuje konfigurację, profile uwierzytelniania, istniejący stan katalogu
oraz wiersze katalogu należące do dostawcy, ale nie przepisuje
- `models set <model-or-alias>` przyjmuje `provider/model` lub alias.
- `models list` jest tylko do odczytu: odczytuje konfigurację, profile uwierzytelniania, istniejący stan
katalogu i wiersze katalogu należące do dostawcy, ale nie przepisuje
`models.json`.
- Kolumna `Auth` jest na poziomie dostawcy i jest tylko do odczytu. Jest obliczana na podstawie lokalnych
metadanych profilu uwierzytelniania, znaczników env, skonfigurowanych kluczy dostawcy, znaczników lokalnego dostawcy,
znaczników env/profilu AWS Bedrock oraz syntetycznych metadanych uwierzytelniania Plugin;
nie ładuje runtime dostawcy, nie odczytuje sekretów z keychain, nie wywołuje
API dostawcy ani nie dowodzi dokładnej gotowości wykonania dla poszczególnych modeli.
- `models list --all --provider <id>` może obejmować statyczne wiersze katalogu należące do dostawcy
z manifestów Plugin lub dołączonych metadanych katalogu dostawcy, nawet jeśli
nie uwierzytelniono się jeszcze u tego dostawcy. Te wiersze nadal są pokazywane jako
niedostępne, dopóki nie skonfiguruje się pasującego uwierzytelniania.
- Szerokie `models list --all` scala wiersze katalogu manifestu nad wierszami rejestru
bez ładowania hooków uzupełniania runtime dostawcy. Szybkie ścieżki manifestu filtrowane po dostawcy
- Kolumna `Auth` jest na poziomie dostawcy i jest tylko do odczytu. Jest obliczana z lokalnych
metadanych profilu uwierzytelniania, znaczników środowiska, skonfigurowanych kluczy dostawcy, znaczników
lokalnego dostawcy, znaczników środowiska/profilu AWS Bedrock oraz metadanych syntetycznego uwierzytelniania pluginu;
nie ładuje środowiska uruchomieniowego dostawcy, nie odczytuje sekretów z keychaina, nie wywołuje API dostawcy
ani nie potwierdza dokładnej gotowości wykonania dla pojedynczego modelu.
- `models list --all --provider <id>` może zawierać należące do dostawcy statyczne wiersze katalogu
z manifestów pluginów lub dołączonych metadanych katalogu dostawcy, nawet gdy
nie uwierzytelniłeś się jeszcze u tego dostawcy. Te wiersze nadal są pokazywane jako
niedostępne, dopóki nie zostanie skonfigurowane pasujące uwierzytelnianie.
- `models list` utrzymuje responsywność płaszczyzny sterowania, gdy odkrywanie katalogu dostawcy
jest wolne. Widoki domyślne i skonfigurowane wracają do skonfigurowanych lub
syntetycznych wierszy modeli po krótkim oczekiwaniu i pozwalają odkrywaniu zakończyć się w
tle. Użyj `--all`, gdy potrzebujesz dokładnego pełnego odkrytego katalogu i
chcesz zaczekać na odkrywanie dostawcy.
- Szerokie `models list --all` scala wiersze katalogu z manifestu nad wierszami rejestru
bez ładowania haków uzupełniających środowiska uruchomieniowego dostawcy. Szybkie ścieżki manifestu filtrowane według dostawcy
używają tylko dostawców oznaczonych jako `static`; dostawcy oznaczeni jako `refreshable`
pozostają oparte na rejestrze/pamięci podręcznej i dołączają wiersze manifestu jako uzupełnienia, natomiast
dostawcy oznaczeni jako `runtime` pozostają przy wykrywaniu z rejestru/runtime.
- `models list` utrzymuje natywne metadane modelu i limity runtime oddzielnie. W wyjściu tabelarycznym
`Ctx` pokazuje `contextTokens/contextWindow`, gdy efektywny limit runtime
dostawcy oznaczeni jako `runtime` pozostają przy odkrywaniu z rejestru/środowiska uruchomieniowego.
- `models list` utrzymuje natywne metadane modelu i limity środowiska uruchomieniowego jako osobne wartości. W wyjściu tabelarycznym
`Ctx` pokazuje `contextTokens/contextWindow`, gdy efektywny limit środowiska uruchomieniowego
różni się od natywnego okna kontekstu; wiersze JSON zawierają `contextTokens`,
gdy dostawca ujawnia ten limit.
gdy dostawca udostępnia ten limit.
- `models list --provider <id>` filtruje według identyfikatora dostawcy, takiego jak `moonshot` lub
`openai-codex`. Nie akceptuje etykiet wyświetlanych z interaktywnych selektorów dostawców,
takich jak `Moonshot AI`.
- Referencje modeli są analizowane przez podział przy **pierwszym** `/`. Jeśli identyfikator modelu zawiera `/` (w stylu OpenRouter), dołącz prefiks dostawcy (przykład: `openrouter/moonshotai/kimi-k2`).
- Jeśli pominiesz dostawcę, OpenClaw najpierw rozstrzyga wejście jako alias, następnie
jako unikalne dopasowanie skonfigurowanego dostawcy dla tego dokładnego identyfikatora modelu, a dopiero potem
przechodzi do skonfigurowanego dostawcy domyślnego z ostrzeżeniem o wycofaniu.
`openai-codex`. Nie przyjmuje etykiet wyświetlanych z interaktywnych
selektorów dostawców, takich jak `Moonshot AI`.
- Referencje modeli są parsowane przez podział na **pierwszym** `/`. Jeśli ID modelu zawiera `/` (w stylu OpenRouter), dołącz prefiks dostawcy (przykład: `openrouter/moonshotai/kimi-k2`).
- Jeśli pominiesz dostawcę, OpenClaw rozwiązuje dane wejściowe najpierw jako alias, potem
jako unikalne dopasowanie skonfigurowanego dostawcy dla dokładnego identyfikatora modelu, a dopiero potem
wraca do skonfigurowanego dostawcy domyślnego z ostrzeżeniem o wycofaniu.
Jeśli ten dostawca nie udostępnia już skonfigurowanego modelu domyślnego, OpenClaw
przechodzi do pierwszego skonfigurowanego dostawcy/modelu zamiast zgłaszać
nieaktualny domyślny usuniętego dostawcy.
wraca do pierwszej skonfigurowanej pary dostawca/model zamiast pokazywać
nieaktualny domyślny wybór usuniętego dostawcy.
- `models status` może pokazywać `marker(<value>)` w wyjściu uwierzytelniania dla niesekretnych symboli zastępczych (na przykład `OPENAI_API_KEY`, `secretref-managed`, `minimax-oauth`, `oauth:chutes`, `ollama-local`) zamiast maskować je jako sekrety.
### Skanowanie modeli
`models scan` odczytuje publiczny katalog `:free` OpenRouter i szereguje kandydatów do
użycia jako modele zastępcze. Sam katalog jest publiczny, więc skanowanie samych metadanych nie wymaga
`models scan` odczytuje publiczny katalog `:free` OpenRouter i klasyfikuje kandydatów do
użycia awaryjnego. Sam katalog jest publiczny, więc skanowania samych metadanych nie wymagają
klucza OpenRouter.
Domyślnie OpenClaw próbuje sondować obsługę narzędzi i obrazów za pomocą wywołań modeli na żywo.
Jeśli nie skonfigurowano klucza OpenRouter, polecenie przechodzi do wyjścia zawierającego tylko metadane
Domyślnie OpenClaw próbuje sondować obsługę narzędzi i obrazów za pomocą wywołań modelu na żywo.
Jeśli nie skonfigurowano klucza OpenRouter, polecenie wraca do wyjścia zawierającego tylko metadane
i wyjaśnia, że modele `:free` nadal wymagają `OPENROUTER_API_KEY` do
sond i inferencji.
@ -110,10 +116,10 @@ Opcje:
- `--set-image`
- `--json`
`--set-default` i `--set-image` wymagają sond na żywo; wyniki skanowania zawierające
tylko metadane są informacyjne i nie są stosowane do konfiguracji.
`--set-default` i `--set-image` wymagają sond na żywo; wyniki skanowania tylko metadanych
mają charakter informacyjny i nie są stosowane do konfiguracji.
### Status modeli
### Stan modeli
Opcje:
@ -122,7 +128,7 @@ Opcje:
- `--check` (kod wyjścia 1=wygasłe/brakujące, 2=wygasające)
- `--probe` (sonda na żywo skonfigurowanych profili uwierzytelniania)
- `--probe-provider <name>` (sonduj jednego dostawcę)
- `--probe-profile <id>` (powtarzane lub rozdzielone przecinkami identyfikatory profili)
- `--probe-profile <id>` (powtarzalne lub rozdzielone przecinkami identyfikatory profili)
- `--probe-timeout <ms>`
- `--probe-concurrency <n>`
- `--probe-max-tokens <n>`
@ -132,7 +138,7 @@ Opcje:
i uruchamiania jest kierowana do stderr, aby skrypty mogły przekazywać stdout bezpośrednio
do narzędzi takich jak `jq`.
Koszyki statusu sond:
Koszyki stanu sond:
- `ok`
- `auth`
@ -143,17 +149,17 @@ Koszyki statusu sond:
- `unknown`
- `no_model`
Oczekiwane przypadki szczegółów/kodów przyczyn sond:
Oczekiwane przypadki szczegółów/kodów przyczyny sondy:
- `excluded_by_auth_order`: zapisany profil istnieje, ale jawne
`auth.order.<provider>` go pominęło, więc sonda zgłasza wykluczenie zamiast
go próbować.
próbować go użyć.
- `missing_credential`, `invalid_expires`, `expired`, `unresolved_ref`:
profil jest obecny, ale nie kwalifikuje się/nie może zostać rozstrzygnięty.
- `no_model`: uwierzytelnianie dostawcy istnieje, ale OpenClaw nie mógł rozstrzygnąć kandydata modelu,
którego można sondować dla tego dostawcy.
profil jest obecny, ale nie kwalifikuje się lub nie da się go rozwiązać.
- `no_model`: uwierzytelnianie dostawcy istnieje, ale OpenClaw nie mógł rozwiązać kandydata
modelu możliwego do sondowania dla tego dostawcy.
## Aliasy + modele zastępcze
## Aliasy + modele awaryjne
```bash
openclaw models aliases list
@ -169,14 +175,14 @@ openclaw models auth setup-token --provider <id>
openclaw models auth paste-token
```
`models auth add` to interaktywny pomocnik uwierzytelniania. Może uruchomić przepływ uwierzytelniania dostawcy
(OAuth/klucz API) albo poprowadzić do ręcznego wklejenia tokenu, zależnie od
`models auth add` to interaktywny pomocnik uwierzytelniania. Może uruchomić przepływ uwierzytelniania
dostawcy (OAuth/klucz API) albo poprowadzić Cię przez ręczne wklejenie tokenu, zależnie od
wybranego dostawcy.
`models auth login` uruchamia przepływ uwierzytelniania Plugin dostawcy (OAuth/klucz API). Użyj
`models auth login` uruchamia przepływ uwierzytelniania pluginu dostawcy (OAuth/klucz API). Użyj
`openclaw plugins list`, aby zobaczyć, którzy dostawcy są zainstalowani.
Użyj `openclaw models auth --agent <id> <subcommand>`, aby zapisać wyniki uwierzytelniania w
magazynie konkretnego skonfigurowanego agenta. Flaga nadrzędna `--agent` jest respektowana przez
Użyj `openclaw models auth --agent <id> <subcommand>`, aby zapisać wyniki uwierzytelniania do
magazynu konkretnego skonfigurowanego agenta. Flaga nadrzędna `--agent` jest respektowana przez
`add`, `login`, `setup-token`, `paste-token` i `login-github-copilot`.
Przykłady:
@ -191,17 +197,17 @@ Uwagi:
którzy udostępniają metody uwierzytelniania tokenem.
- `setup-token` wymaga interaktywnego TTY i uruchamia metodę uwierzytelniania tokenem dostawcy
(domyślnie metodę `setup-token` tego dostawcy, gdy ją udostępnia).
- `paste-token` akceptuje ciąg tokenu wygenerowany gdzie indziej lub z automatyzacji.
- `paste-token` wymaga `--provider`, pyta o wartość tokenu i zapisuje
ją pod domyślnym identyfikatorem profilu `<provider>:manual`, chyba że przekażesz
- `paste-token` przyjmuje ciąg tokenu wygenerowany gdzie indziej lub z automatyzacji.
- `paste-token` wymaga `--provider`, prosi o wartość tokenu i zapisuje
ją do domyślnego identyfikatora profilu `<provider>:manual`, chyba że przekażesz
`--profile-id`.
- `paste-token --expires-in <duration>` zapisuje bezwzględny czas wygaśnięcia tokenu na podstawie
względnego czasu trwania, takiego jak `365d` lub `12h`.
- Uwaga Anthropic: pracownicy Anthropic powiedzieli nam, że użycie Claude CLI w stylu OpenClaw jest ponownie dozwolone, więc OpenClaw traktuje ponowne użycie Claude CLI i użycie `claude -p` jako usankcjonowane dla tej integracji, chyba że Anthropic opublikuje nową politykę.
- Anthropic `setup-token` / `paste-token` pozostają dostępne jako obsługiwana ścieżka tokenu OpenClaw, ale OpenClaw obecnie preferuje ponowne użycie Claude CLI i `claude -p`, gdy są dostępne.
- Uwaga Anthropic: pracownicy Anthropic poinformowali nas, że użycie Claude CLI w stylu OpenClaw jest ponownie dozwolone, więc OpenClaw traktuje ponowne użycie Claude CLI i użycie `claude -p` jako usankcjonowane dla tej integracji, chyba że Anthropic opublikuje nową politykę.
- Anthropic `setup-token` / `paste-token` pozostają dostępne jako obsługiwana ścieżka tokenu OpenClaw, ale OpenClaw preferuje teraz ponowne użycie Claude CLI i `claude -p`, gdy są dostępne.
## Powiązane
- [Dokumentacja CLI](/pl/cli)
- [Wybór modelu](/pl/concepts/model-providers)
- [Przełączanie awaryjne modelu](/pl/concepts/model-failover)
- [Przełączanie awaryjne modeli](/pl/concepts/model-failover)

132
docs/pl/cli/onboard.md
View File

@ -1,38 +1,38 @@
---
read_when:
- Chcesz przejść przez konfigurację z przewodnikiem dla Gateway, obszaru roboczego, uwierzytelniania, kanałów i Skills
summary: Dokumentacja referencyjna CLI dla `openclaw onboard` (interaktywne wprowadzenie)
title: Wdrażanie
- Potrzebujesz konfiguracji z przewodnikiem dla Gateway, obszaru roboczego, uwierzytelniania, kanałów i Skills
summary: Dokumentacja referencyjna CLI dla `openclaw onboard` (interaktywne wdrażanie)
title: Wprowadzenie
x-i18n:
generated_at: "2026-04-30T09:45:05Z"
generated_at: "2026-05-01T09:57:04Z"
model: gpt-5.5
provider: openai
source_hash: 583310458b2e2bc8ddc1513112c960520d972716be0c33e4177d0db30e896504
source_hash: 1276a0b20f37da470bb4d49b38d06bacc38e7d0e85737a22971a2a9a3d90e244
source_path: cli/onboard.md
workflow: 16
---
# `openclaw onboard`
Interaktywne wdrażanie dla lokalnej lub zdalnej konfiguracji Gateway.
Interaktywny onboarding do konfiguracji lokalnego lub zdalnego Gateway.
## Powiązane przewodniki
<CardGroup cols={2}>
<Card title="Centrum wdrażania CLI" href="/pl/start/wizard" icon="rocket">
<Card title="Centrum onboardingu CLI" href="/pl/start/wizard" icon="rocket">
Przewodnik po interaktywnym przepływie CLI.
</Card>
<Card title="Omówienie wdrażania" href="/pl/start/onboarding-overview" icon="map">
Jak elementy wdrażania OpenClaw łączą się ze sobą.
<Card title="Omówienie onboardingu" href="/pl/start/onboarding-overview" icon="map">
Jak elementy onboardingu OpenClaw łączą się ze sobą.
</Card>
<Card title="Informacje referencyjne konfiguracji CLI" href="/pl/start/wizard-cli-reference" icon="book">
Wyniki, elementy wewnętrzne i zachowanie poszczególnych kroków.
<Card title="Dokumentacja konfiguracji CLI" href="/pl/start/wizard-cli-reference" icon="book">
Dane wyjściowe, mechanizmy wewnętrzne i zachowanie poszczególnych kroków.
</Card>
<Card title="Automatyzacja CLI" href="/pl/start/wizard-cli-automation" icon="terminal">
Flagi nieinteraktywne i konfiguracje skryptowe.
Flagi nieinteraktywne i skryptowane konfiguracje.
</Card>
<Card title="Wdrażanie aplikacji macOS" href="/pl/start/onboarding" icon="apple">
Przepływ wdrażania dla aplikacji paska menu macOS.
<Card title="Onboarding aplikacji macOS" href="/pl/start/onboarding" icon="apple">
Przepływ onboardingu dla aplikacji paska menu macOS.
</Card>
</CardGroup>
@ -49,17 +49,17 @@ openclaw onboard --skip-bootstrap
openclaw onboard --mode remote --remote-url wss://gateway-host:18789
```
`--flow import` używa dostawców migracji należących do Plugin, takich jak Hermes. Działa tylko względem świeżej konfiguracji OpenClaw; jeśli istniejąca konfiguracja, poświadczenia, sesje albo pliki pamięci/tożsamości obszaru roboczego są obecne, zresetuj je albo wybierz świeżą konfigurację przed importem.
`--flow import` używa dostawców migracji należących do pluginów, takich jak Hermes. Działa tylko wobec świeżej konfiguracji OpenClaw; jeśli istnieją już konfiguracja, dane uwierzytelniające, sesje albo pliki pamięci/tożsamości obszaru roboczego, zresetuj je albo wybierz świeżą konfigurację przed importem.
`--modern` uruchamia podgląd konwersacyjnego wdrażania Crestodian. Bez
`--modern`, `openclaw onboard` zachowuje klasyczny przepływ wdrażania.
`--modern` uruchamia podgląd konwersacyjnego onboardingu Crestodian. Bez
`--modern`, `openclaw onboard` zachowuje klasyczny przepływ onboardingu.
Dla celów `ws://` w prywatnej sieci z tekstem jawnym (tylko zaufane sieci), ustaw
`OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1` w środowisku procesu wdrażania.
Nie ma odpowiednika `openclaw.json` dla tego awaryjnego obejścia transportu
po stronie klienta.
Dla zwykłotekstowych celów `ws://` w sieci prywatnej (tylko zaufane sieci), ustaw
`OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1` w środowisku procesu onboardingu.
Nie istnieje odpowiednik `openclaw.json` dla tego awaryjnego obejścia
transportu po stronie klienta.
Niestandardowy dostawca nieinteraktywny:
Nieinteraktywny niestandardowy dostawca:
```bash
openclaw onboard --non-interactive \
@ -72,8 +72,8 @@ openclaw onboard --non-interactive \
--custom-image-input
```
`--custom-api-key` jest opcjonalne w trybie nieinteraktywnym. Jeśli zostanie pominięte, wdrażanie sprawdza `CUSTOM_API_KEY`.
OpenClaw automatycznie oznacza typowe identyfikatory modeli wizyjnych jako obsługujące obrazy. Przekaż `--custom-image-input` dla nieznanych niestandardowych identyfikatorów wizyjnych albo `--custom-text-input`, aby wymusić metadane tylko tekstowe.
`--custom-api-key` jest opcjonalne w trybie nieinteraktywnym. Jeśli zostanie pominięte, onboarding sprawdza `CUSTOM_API_KEY`.
OpenClaw automatycznie oznacza popularne identyfikatory modeli wizyjnych jako obsługujące obrazy. Przekaż `--custom-image-input` dla nieznanych identyfikatorów niestandardowych modeli wizyjnych albo `--custom-text-input`, aby wymusić metadane wyłącznie tekstowe.
LM Studio obsługuje także flagę klucza specyficzną dla dostawcy w trybie nieinteraktywnym:
@ -96,9 +96,9 @@ openclaw onboard --non-interactive \
--accept-risk
```
`--custom-base-url` domyślnie przyjmuje `http://127.0.0.1:11434`. `--custom-model-id` jest opcjonalne; jeśli zostanie pominięte, wdrażanie używa sugerowanych wartości domyślnych Ollama. Identyfikatory modeli chmurowych, takie jak `kimi-k2.5:cloud`, również tu działają.
`--custom-base-url` domyślnie ma wartość `http://127.0.0.1:11434`. `--custom-model-id` jest opcjonalne; jeśli zostanie pominięte, onboarding używa sugerowanych wartości domyślnych Ollama. Identyfikatory modeli chmurowych, takie jak `kimi-k2.5:cloud`, także tutaj działają.
Przechowuj klucze dostawców jako referencje zamiast tekstu jawnego:
Przechowuj klucze dostawców jako odwołania zamiast zwykłego tekstu:
```bash
openclaw onboard --non-interactive \
@ -107,26 +107,28 @@ openclaw onboard --non-interactive \
--accept-risk
```
Z `--secret-input-mode ref` wdrażanie zapisuje referencje oparte na zmiennych środowiskowych zamiast wartości kluczy w tekście jawnym.
Dla dostawców opartych na profilach uwierzytelniania zapisuje to wpisy `keyRef`; dla dostawców niestandardowych zapisuje to `models.providers.<id>.apiKey` jako referencję środowiskową (na przykład `{ source: "env", provider: "default", id: "CUSTOM_API_KEY" }`).
Z `--secret-input-mode ref` onboarding zapisuje odwołania oparte na zmiennych środowiskowych zamiast wartości kluczy w postaci zwykłego tekstu.
Dla dostawców opartych na profilach uwierzytelniania zapisuje to wpisy `keyRef`; dla dostawców niestandardowych zapisuje to `models.providers.<id>.apiKey` jako odwołanie do zmiennej środowiskowej (na przykład `{ source: "env", provider: "default", id: "CUSTOM_API_KEY" }`).
Kontrakt trybu nieinteraktywnego `ref`:
Kontrakt nieinteraktywnego trybu `ref`:
- Ustaw zmienną środowiskową dostawcy w środowisku procesu wdrażania (na przykład `OPENAI_API_KEY`).
- Nie przekazuj wbudowanych flag klucza (na przykład `--openai-api-key`), chyba że ta zmienna środowiskowa jest również ustawiona.
- Jeśli wbudowana flaga klucza zostanie przekazana bez wymaganej zmiennej środowiskowej, wdrażanie szybko kończy się błędem z instrukcjami.
- Ustaw zmienną środowiskową dostawcy w środowisku procesu onboardingu (na przykład `OPENAI_API_KEY`).
- Nie przekazuj wbudowanych flag klucza (na przykład `--openai-api-key`), chyba że ta zmienna środowiskowa jest także ustawiona.
- Jeśli wbudowana flaga klucza zostanie przekazana bez wymaganej zmiennej środowiskowej, onboarding szybko kończy się niepowodzeniem z instrukcjami.
Opcje tokena Gateway w trybie nieinteraktywnym:
Opcje tokenu Gateway w trybie nieinteraktywnym:
- `--gateway-auth token --gateway-token <token>` przechowuje token w tekście jawnym.
- `--gateway-auth token --gateway-token <token>` przechowuje token w postaci zwykłego tekstu.
- `--gateway-auth token --gateway-token-ref-env <name>` przechowuje `gateway.auth.token` jako środowiskowy SecretRef.
- `--gateway-token` i `--gateway-token-ref-env` wzajemnie się wykluczają.
- `--gateway-token-ref-env` wymaga niepustej zmiennej środowiskowej w środowisku procesu wdrażania.
- Z `--install-daemon`, gdy uwierzytelnianie tokenem wymaga tokena, tokeny Gateway zarządzane przez SecretRef są walidowane, ale nie są utrwalane jako rozwiązany tekst jawny w metadanych środowiska usługi nadzorcy.
- Z `--install-daemon`, jeśli tryb tokenu wymaga tokena, a skonfigurowany token SecretRef nie może zostać rozwiązany, wdrażanie kończy się bezpiecznym niepowodzeniem z instrukcjami naprawy.
- Z `--install-daemon`, jeśli skonfigurowane są zarówno `gateway.auth.token`, jak i `gateway.auth.password`, a `gateway.auth.mode` nie jest ustawione, wdrażanie blokuje instalację, dopóki tryb nie zostanie ustawiony jawnie.
- Lokalne wdrażanie zapisuje `gateway.mode="local"` w konfiguracji. Jeśli w późniejszym pliku konfiguracji brakuje `gateway.mode`, traktuj to jako uszkodzenie konfiguracji albo niekompletną ręczną edycję, a nie jako poprawny skrót trybu lokalnego.
- `--allow-unconfigured` to osobna awaryjna furtka środowiska uruchomieniowego Gateway. Nie oznacza, że wdrażanie może pominąć `gateway.mode`.
- `--gateway-token-ref-env` wymaga niepustej zmiennej środowiskowej w środowisku procesu onboardingu.
- Z `--install-daemon`, gdy uwierzytelnianie tokenem wymaga tokenu, tokeny gateway zarządzane przez SecretRef są walidowane, ale nie są utrwalane jako rozwiązany zwykły tekst w metadanych środowiska usługi nadzorcy.
- Z `--install-daemon`, jeśli tryb tokenu wymaga tokenu, a skonfigurowany SecretRef tokenu jest nierozwiązany, onboarding kończy się w trybie zamkniętym z instrukcjami naprawy.
- Z `--install-daemon`, jeśli skonfigurowane są zarówno `gateway.auth.token`, jak i `gateway.auth.password`, a `gateway.auth.mode` nie jest ustawione, onboarding blokuje instalację do czasu jawnego ustawienia trybu.
- Lokalny onboarding zapisuje `gateway.mode="local"` w konfiguracji. Jeśli w późniejszym pliku konfiguracji brakuje `gateway.mode`, traktuj to jako uszkodzenie konfiguracji albo niepełną ręczną edycję, a nie jako prawidłowy skrót trybu lokalnego.
- Lokalny onboarding materializuje nowo wymagane zależności uruchomieniowe dołączonych pluginów po zapisaniu konfiguracji, zanim będą kontynuowane obszar roboczy/bootstrap, instalacja daemona lub kontrole kondycji. To wąski krok naprawy menedżera pakietów, a nie pełne uruchomienie `openclaw doctor`.
- Zdalny onboarding zapisuje tylko informacje o połączeniu dla zdalnego Gateway i nie instaluje lokalnych zależności dołączonych pluginów.
- `--allow-unconfigured` to osobny awaryjny mechanizm środowiska uruchomieniowego Gateway. Nie oznacza, że onboarding może pominąć `gateway.mode`.
Przykład:
@ -140,24 +142,24 @@ openclaw onboard --non-interactive \
--accept-risk
```
Stan lokalnego Gateway w trybie nieinteraktywnym:
Kondycja lokalnego gateway w trybie nieinteraktywnym:
- Jeśli nie przekażesz `--skip-health`, wdrażanie czeka na osiągalny lokalny Gateway, zanim zakończy się powodzeniem.
- `--install-daemon` najpierw uruchamia ścieżkę instalacji zarządzanego Gateway. Bez tej flagi musisz mieć już uruchomiony lokalny Gateway, na przykład `openclaw gateway run`.
- Jeśli w automatyzacji chcesz tylko zapisy konfiguracji/obszaru roboczego/bootstrapu, użyj `--skip-health`.
- O ile nie przekażesz `--skip-health`, onboarding czeka na osiągalny lokalny gateway, zanim zakończy się powodzeniem.
- `--install-daemon` najpierw uruchamia ścieżkę zarządzanej instalacji gateway. Bez niej lokalny gateway musi już działać, na przykład `openclaw gateway run`.
- Jeśli w automatyzacji chcesz wyłącznie zapisy konfiguracji/obszaru roboczego/bootstrapu, użyj `--skip-health`.
- Jeśli samodzielnie zarządzasz plikami obszaru roboczego, przekaż `--skip-bootstrap`, aby ustawić `agents.defaults.skipBootstrap: true` i pominąć tworzenie `AGENTS.md`, `SOUL.md`, `TOOLS.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md` oraz `BOOTSTRAP.md`.
- W natywnym Windows `--install-daemon` najpierw próbuje użyć Zaplanowanych zadań, a jeśli tworzenie zadania zostanie odrzucone, przechodzi do elementu logowania w folderze Autostart użytkownika.
- W natywnym Windows `--install-daemon` najpierw próbuje użyć Zaplanowanych zadań, a jeśli tworzenie zadania zostanie odrzucone, przechodzi do elementu logowania w folderze Autostart dla użytkownika.
Zachowanie interaktywnego wdrażania w trybie referencji:
Zachowanie interaktywnego onboardingu w trybie odwołań:
- Wybierz **Użyj referencji sekretu**, gdy pojawi się monit.
- Wybierz **Użyj odwołania do sekretu**, gdy pojawi się monit.
- Następnie wybierz jedno z:
- Zmienna środowiskowa
- Skonfigurowany dostawca sekretów (`file` lub `exec`)
- Wdrażanie wykonuje szybką walidację wstępną przed zapisaniem referencji.
- Jeśli walidacja się nie powiedzie, wdrażanie pokazuje błąd i pozwala spróbować ponownie.
- Skonfigurowany dostawca sekretów (`file` albo `exec`)
- Onboarding wykonuje szybką walidację wstępną przed zapisaniem odwołania.
- Jeśli walidacja się nie powiedzie, onboarding pokazuje błąd i pozwala spróbować ponownie.
### Nieinteraktywne wybory punktów końcowych Z.AI
### Nieinteraktywne wybory punktu końcowego Z.AI
<Note>
`--auth-choice zai-api-key` automatycznie wykrywa najlepszy punkt końcowy Z.AI dla Twojego klucza (preferuje ogólne API z `zai/glm-5.1`). Jeśli konkretnie chcesz punkty końcowe GLM Coding Plan, wybierz `zai-coding-global` albo `zai-coding-cn`.
@ -186,35 +188,35 @@ openclaw onboard --non-interactive \
## Uwagi dotyczące przepływu
<AccordionGroup>
<Accordion title="Typy przepływów">
- `quickstart`: minimalne monity, automatycznie generuje token Gateway.
- `manual`: pełne monity dla portu, powiązania i uwierzytelniania (alias `advanced`).
- `import`: uruchamia wykrytego dostawcę migracji, pokazuje podgląd planu, a następnie stosuje go po potwierdzeniu.
<Accordion title="Typy przepływu">
- `quickstart`: minimalne monity, automatycznie generuje token gateway.
- `manual`: pełne monity dotyczące portu, powiązania i uwierzytelniania (alias `advanced`).
- `import`: uruchamia wykrytego dostawcę migracji, wyświetla podgląd planu, a następnie stosuje go po potwierdzeniu.
</Accordion>
<Accordion title="Wstępne filtrowanie dostawców">
Gdy wybór uwierzytelniania wskazuje preferowanego dostawcę, wdrażanie wstępnie filtruje selektory modelu domyślnego i listy dozwolonych pozycji do tego dostawcy. W przypadku Volcengine i BytePlus dopasowuje to również warianty planu kodowania (`volcengine-plan/*`, `byteplus-plan/*`).
Gdy wybór uwierzytelniania implikuje preferowanego dostawcę, onboarding wstępnie filtruje selektory modelu domyślnego i listy dozwolonych do tego dostawcy. W przypadku Volcengine i BytePlus dopasowuje to także warianty planu kodowania (`volcengine-plan/*`, `byteplus-plan/*`).
Jeśli filtr preferowanego dostawcy nie zwróci jeszcze żadnych załadowanych modeli, wdrażanie wraca do niefiltrowanego katalogu zamiast pozostawiać selektor pusty.
Jeśli filtr preferowanego dostawcy nie zwróci jeszcze żadnych załadowanych modeli, onboarding wraca do niefiltrowanego katalogu zamiast pozostawiać selektor pusty.
</Accordion>
<Accordion title="Dodatkowe pytania dotyczące wyszukiwania w sieci">
Niektórzy dostawcy wyszukiwania w sieci uruchamiają dodatkowe monity specyficzne dla dostawcy:
<Accordion title="Dodatkowe monity wyszukiwania w sieci">
Niektórzy dostawcy wyszukiwania w sieci wyzwalają dodatkowe monity specyficzne dla dostawcy:
- **Grok** może zaoferować opcjonalną konfigurację `x_search` z tym samym `XAI_API_KEY` i wyborem modelu `x_search`.
- **Kimi** może zapytać o region Moonshot API (`api.moonshot.ai` kontra `api.moonshot.cn`) i domyślny model wyszukiwania w sieci Kimi.
- **Kimi** może zapytać o region API Moonshot (`api.moonshot.ai` albo `api.moonshot.cn`) oraz domyślny model wyszukiwania w sieci Kimi.
</Accordion>
<Accordion title="Inne zachowania">
- Zachowanie zakresu DM lokalnego wdrażania: [informacje referencyjne konfiguracji CLI](/pl/start/wizard-cli-reference#outputs-and-internals).
- Zachowanie zakresu lokalnego onboardingu DM: [dokumentacja konfiguracji CLI](/pl/start/wizard-cli-reference#outputs-and-internals).
- Najszybszy pierwszy czat: `openclaw dashboard` (Control UI, bez konfiguracji kanału).
- Dostawca niestandardowy: połącz dowolny punkt końcowy zgodny z OpenAI lub Anthropic, w tym hostowanych dostawców, których nie ma na liście. Użyj Nieznany, aby wykryć automatycznie.
- Jeśli wykryty zostanie stan Hermes, wdrażanie oferuje przepływ migracji. Użyj [Migruj](/pl/cli/migrate), aby uzyskać plany próbne, tryb nadpisywania, raporty i dokładne mapowania.
- Dostawca niestandardowy: połącz dowolny punkt końcowy zgodny z OpenAI lub Anthropic, w tym dostawców hostowanych niewymienionych na liście. Użyj Unknown, aby wykryć automatycznie.
- Jeśli wykryto stan Hermes, onboarding oferuje przepływ migracji. Użyj [Migrate](/pl/cli/migrate), aby uzyskać plany dry-run, tryb nadpisywania, raporty i dokładne mapowania.
</Accordion>
</AccordionGroup>
## Typowe polecenia uzupełniające
## Typowe polecenia następcze
```bash
openclaw configure
@ -222,5 +224,5 @@ openclaw agents add <name>
```
<Note>
`--json` nie oznacza trybu nieinteraktywnego. Użyj `--non-interactive` dla skryptów.
`--json` nie oznacza trybu nieinteraktywnego. Użyj `--non-interactive` w skryptach.
</Note>

198
docs/pl/cli/plugins.md
View File

@ -1,15 +1,15 @@
---
read_when:
- Chcesz zainstalować pluginy Gateway lub zgodne pakiety albo nimi zarządzać
- Chcesz debugować błędy ładowania Plugin
- Chcesz instalować pluginy Gateway lub zgodne pakiety albo nimi zarządzać
- Chcesz debugować błędy ładowania pluginów
sidebarTitle: Plugins
summary: Dokumentacja CLI dla `openclaw plugins` (list, install, marketplace, uninstall, enable/disable, deps, doctor)
summary: Dokumentacja referencyjna CLI dla `openclaw plugins` (list, install, marketplace, uninstall, enable/disable, deps, doctor)
title: Pluginy
x-i18n:
generated_at: "2026-04-30T09:45:43Z"
generated_at: "2026-05-01T09:57:19Z"
model: gpt-5.5
provider: openai
source_hash: 381e3243eaefb5b5e31db8fd2ba459773649a6ef427080a12018ea92b25f707c
source_hash: cc4b2b753b541dd143e9c2f7e8a2153711a18e15773c65f91756d2729ca3d6fb
source_path: cli/plugins.md
workflow: 16
---
@ -17,16 +17,16 @@ x-i18n:
Zarządzaj Pluginami Gateway, pakietami hooków i zgodnymi pakietami.
<CardGroup cols={2}>
<Card title="Plugin system" href="/pl/tools/plugin">
Przewodnik dla użytkownika końcowego dotyczący instalowania, włączania i rozwiązywania problemów z Pluginami.
<Card title="System Pluginów" href="/pl/tools/plugin">
Przewodnik dla użytkowników końcowych dotyczący instalowania, włączania i rozwiązywania problemów z Pluginami.
</Card>
<Card title="Plugin bundles" href="/pl/plugins/bundles">
<Card title="Pakiety Pluginów" href="/pl/plugins/bundles">
Model zgodności pakietów.
</Card>
<Card title="Plugin manifest" href="/pl/plugins/manifest">
<Card title="Manifest Pluginu" href="/pl/plugins/manifest">
Pola manifestu i schemat konfiguracji.
</Card>
<Card title="Security" href="/pl/gateway/security">
<Card title="Bezpieczeństwo" href="/pl/gateway/security">
Utwardzanie zabezpieczeń instalacji Pluginów.
</Card>
</CardGroup>
@ -40,6 +40,7 @@ openclaw plugins list --verbose
openclaw plugins list --json
openclaw plugins install <path-or-spec>
openclaw plugins inspect <id>
openclaw plugins inspect <id> --runtime
openclaw plugins inspect <id> --json
openclaw plugins inspect --all
openclaw plugins info <id>
@ -59,77 +60,85 @@ openclaw plugins marketplace list <marketplace>
openclaw plugins marketplace list <marketplace> --json
```
Aby zbadać powolne instalowanie, sprawdzanie, odinstalowywanie lub odświeżanie rejestru, uruchom polecenie z `OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1`. Ślad zapisuje czasy faz do stderr i zachowuje możliwość parsowania wyjścia JSON. Zobacz [Debugowanie](/pl/help/debugging#plugin-lifecycle-trace).
Aby zbadać powolną instalację, inspekcję, odinstalowanie lub odświeżanie rejestru, uruchom
polecenie z `OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1`. Ślad zapisuje czasy faz
do stderr i zachowuje możliwość parsowania wyjścia JSON. Zobacz [Debugowanie](/pl/help/debugging#plugin-lifecycle-trace).
<Note>
Dołączone Pluginy są dostarczane z OpenClaw. Niektóre są domyślnie włączone (na przykład dołączeni dostawcy modeli, dołączeni dostawcy mowy i dołączony Plugin przeglądarki); inne wymagają `plugins enable`.
Dołączone Pluginy są dostarczane z OpenClaw. Niektóre są domyślnie włączone (na przykład dołączeni dostawcy modeli, dołączeni dostawcy mowy oraz dołączony Plugin przeglądarki); inne wymagają `plugins enable`.
Natywne Pluginy OpenClaw muszą dostarczać `openclaw.plugin.json` z wbudowanym JSON Schema (`configSchema`, nawet jeśli jest pusty). Zgodne pakiety używają zamiast tego własnych manifestów pakietów.
Natywne Pluginy OpenClaw muszą dostarczać `openclaw.plugin.json` z wbudowanym schematem JSON Schema (`configSchema`, nawet jeśli jest pusty). Zgodne pakiety używają zamiast tego własnych manifestów pakietów.
`plugins list` pokazuje `Format: openclaw` lub `Format: bundle`. Szczegółowe wyjście list/info pokazuje też podtyp pakietu (`codex`, `claude` lub `cursor`) oraz wykryte możliwości pakietu.
`plugins list` pokazuje `Format: openclaw` albo `Format: bundle`. Szczegółowe wyjście list/info pokazuje także podtyp pakietu (`codex`, `claude` albo `cursor`) oraz wykryte możliwości pakietu.
</Note>
### Instalacja
```bash
openclaw plugins install <package> # Najpierw ClawHub, potem npm
openclaw plugins install clawhub:<package> # Tylko ClawHub
openclaw plugins install npm:<package> # Tylko npm
openclaw plugins install <package> --force # nadpisz istniejącą instalację
openclaw plugins install <package> --pin # przypnij wersję
openclaw plugins install <package> # ClawHub first, then npm
openclaw plugins install clawhub:<package> # ClawHub only
openclaw plugins install npm:<package> # npm only
openclaw plugins install <package> --force # overwrite existing install
openclaw plugins install <package> --pin # pin version
openclaw plugins install <package> --dangerously-force-unsafe-install
openclaw plugins install <path> # ścieżka lokalna
openclaw plugins install <path> # local path
openclaw plugins install <plugin>@<marketplace> # marketplace
openclaw plugins install <plugin> --marketplace <name> # marketplace (jawnie)
openclaw plugins install <plugin> --marketplace <name> # marketplace (explicit)
openclaw plugins install <plugin> --marketplace https://github.com/<owner>/<repo>
```
<Warning>
Same nazwy pakietów są najpierw sprawdzane w ClawHub, a potem w npm. Traktuj instalacje Pluginów jak uruchamianie kodu. Preferuj przypięte wersje.
Same nazwy pakietów są sprawdzane najpierw w ClawHub, a potem w npm. Traktuj instalacje Pluginów jak uruchamianie kodu. Preferuj przypięte wersje.
</Warning>
<Note>
ClawHub jest główną powierzchnią dystrybucji i odkrywania większości Pluginów. Npm pozostaje obsługiwaną ścieżką awaryjną i ścieżką instalacji bezpośredniej. Podczas migracji do ClawHub OpenClaw nadal dostarcza niektóre należące do OpenClaw pakiety Pluginów `@openclaw/*` w npm; wersje tych pakietów mogą pozostawać w tyle za dołączonym źródłem między pociągami wydań Pluginów. Jeśli npm zgłasza należący do OpenClaw pakiet Pluginu jako przestarzały, ta opublikowana wersja jest starym zewnętrznym artefaktem; użyj Pluginu dołączonego do bieżącego OpenClaw albo lokalnego checkoutu, dopóki nie zostanie opublikowany nowszy pakiet npm.
ClawHub jest główną powierzchnią dystrybucji i odkrywania dla większości Pluginów. Npm
pozostaje obsługiwaną ścieżką awaryjną i bezpośredniej instalacji. Podczas migracji do
ClawHub OpenClaw nadal dostarcza niektóre pakiety Pluginów należące do OpenClaw `@openclaw/*`
w npm; te wersje pakietów mogą pozostawać w tyle za dołączonym źródłem między cyklami wydań
Pluginów. Jeśli npm zgłasza pakiet Pluginu należący do OpenClaw jako przestarzały, ta
opublikowana wersja jest starym zewnętrznym artefaktem; użyj Pluginu dołączonego do
aktualnego OpenClaw albo lokalnego checkoutu, dopóki nie zostanie opublikowany nowszy pakiet npm.
</Note>
<AccordionGroup>
<Accordion title="Config includes and invalid-config recovery">
Jeśli sekcja `plugins` jest wspierana przez jednoplikowe `$include`, `plugins install/update/enable/disable/uninstall` zapisują zmiany do tego dołączonego pliku i pozostawiają `openclaw.json` bez zmian. Dołączenia główne, tablice dołączeń i dołączenia z sąsiednimi nadpisaniami kończą się bezpiecznie niepowodzeniem zamiast spłaszczania. Zobacz [dołączenia konfiguracji](/pl/gateway/configuration), aby poznać obsługiwane kształty.
<Accordion title="Dołączenia konfiguracji i odzyskiwanie po nieprawidłowej konfiguracji">
Jeśli sekcja `plugins` jest oparta na jednoplikowym `$include`, `plugins install/update/enable/disable/uninstall` zapisują do tego dołączonego pliku i pozostawiają `openclaw.json` bez zmian. Dołączenia główne, tablice dołączeń i dołączenia z sąsiednimi nadpisaniami kończą się bezpiecznym niepowodzeniem zamiast spłaszczania. Obsługiwane kształty opisuje [Dołączanie konfiguracji](/pl/gateway/configuration).
Jeśli konfiguracja jest nieprawidłowa podczas instalacji, `plugins install` zwykle kończy się bezpiecznie niepowodzeniem i informuje, aby najpierw uruchomić `openclaw doctor --fix`. Podczas uruchamiania Gateway nieprawidłowa konfiguracja jednego Pluginu jest izolowana do tego Pluginu, aby inne kanały i Pluginy mogły nadal działać; `openclaw doctor --fix` może poddać kwarantannie nieprawidłowy wpis Pluginu. Jedynym udokumentowanym wyjątkiem w czasie instalacji jest wąska ścieżka odzyskiwania dla dołączonych Pluginów, które jawnie wybierają `openclaw.install.allowInvalidConfigRecovery`.
Jeśli konfiguracja jest nieprawidłowa podczas instalacji, `plugins install` zwykle kończy się bezpiecznym niepowodzeniem i informuje, aby najpierw uruchomić `openclaw doctor --fix`. Podczas uruchamiania Gateway nieprawidłowa konfiguracja jednego Pluginu jest izolowana do tego Pluginu, dzięki czemu inne kanały i Pluginy mogą nadal działać; `openclaw doctor --fix` może poddać nieprawidłowy wpis Pluginu kwarantannie. Jedynym udokumentowanym wyjątkiem w czasie instalacji jest wąska ścieżka odzyskiwania dołączonych Pluginów dla Pluginów, które jawnie włączają `openclaw.install.allowInvalidConfigRecovery`.
</Accordion>
<Accordion title="--force and reinstall vs update">
`--force` ponownie używa istniejącego celu instalacji i nadpisuje już zainstalowany Plugin lub pakiet hooków w miejscu. Używaj go, gdy celowo instalujesz ponownie ten sam identyfikator z nowej ścieżki lokalnej, archiwum, pakietu ClawHub lub artefaktu npm. Do rutynowych aktualizacji już śledzonego Pluginu npm preferuj `openclaw plugins update <id-or-npm-spec>`.
<Accordion title="--force oraz ponowna instalacja kontra aktualizacja">
`--force` ponownie używa istniejącego celu instalacji i nadpisuje już zainstalowany Plugin albo pakiet hooków w miejscu. Używaj tej opcji, gdy celowo ponownie instalujesz ten sam identyfikator z nowej ścieżki lokalnej, archiwum, pakietu ClawHub albo artefaktu npm. Do rutynowych aktualizacji już śledzonego Pluginu npm preferuj `openclaw plugins update <id-or-npm-spec>`.
Jeśli uruchomisz `plugins install` dla identyfikatora Pluginu, który jest już zainstalowany, OpenClaw zatrzyma się i wskaże `plugins update <id-or-npm-spec>` dla normalnej aktualizacji albo `plugins install <package> --force`, gdy naprawdę chcesz nadpisać bieżącą instalację z innego źródła.
Jeśli uruchomisz `plugins install` dla identyfikatora Pluginu, który jest już zainstalowany, OpenClaw zatrzyma się i wskaże `plugins update <id-or-npm-spec>` dla zwykłej aktualizacji albo `plugins install <package> --force`, gdy rzeczywiście chcesz nadpisać bieżącą instalację z innego źródła.
</Accordion>
<Accordion title="--pin scope">
`--pin` dotyczy tylko instalacji npm. Nie jest obsługiwane z `--marketplace`, ponieważ instalacje marketplace utrwalają metadane źródła marketplace zamiast specyfikacji npm.
<Accordion title="Zakres --pin">
`--pin` dotyczy tylko instalacji npm. Nie jest obsługiwane z `--marketplace`, ponieważ instalacje z marketplace utrwalają metadane źródła marketplace zamiast specyfikacji npm.
</Accordion>
<Accordion title="--dangerously-force-unsafe-install">
`--dangerously-force-unsafe-install` to opcja awaryjna dla fałszywych alarmów w wbudowanym skanerze niebezpiecznego kodu. Pozwala kontynuować instalację nawet wtedy, gdy wbudowany skaner zgłasza wyniki `critical`, ale **nie** omija blokad polityki hooka Pluginu `before_install` i **nie** omija niepowodzeń skanowania.
`--dangerously-force-unsafe-install` to opcja awaryjna dla fałszywych alarmów we wbudowanym skanerze niebezpiecznego kodu. Pozwala kontynuować instalację nawet wtedy, gdy wbudowany skaner zgłasza ustalenia `critical`, ale **nie** omija blokad polityki hooka Pluginu `before_install` i **nie** omija niepowodzeń skanowania.
Ta flaga CLI dotyczy przepływów instalacji/aktualizacji Pluginów. Instalacje zależności Skills obsługiwane przez Gateway używają odpowiadającego nadpisania żądania `dangerouslyForceUnsafeInstall`, podczas gdy `openclaw skills install` pozostaje osobnym przepływem pobierania/instalacji Skills z ClawHub.
Ta flaga CLI dotyczy przepływów instalacji/aktualizacji Pluginów. Instalacje zależności Skills obsługiwane przez Gateway używają odpowiadającego nadpisania żądania `dangerouslyForceUnsafeInstall`, natomiast `openclaw skills install` pozostaje osobnym przepływem pobierania/instalacji Skills z ClawHub.
Jeśli Plugin opublikowany przez Ciebie w ClawHub jest blokowany przez skan rejestru, użyj kroków dla wydawcy w [ClawHub](/pl/tools/clawhub).
</Accordion>
<Accordion title="Hook packs and npm specs">
`plugins install` jest także powierzchnią instalacji dla pakietów hooków, które udostępniają `openclaw.hooks` w `package.json`. Użyj `openclaw hooks` do filtrowanej widoczności hooków i włączania poszczególnych hooków, a nie do instalacji pakietów.
<Accordion title="Pakiety hooków i specyfikacje npm">
`plugins install` jest także powierzchnią instalacji dla pakietów hooków, które udostępniają `openclaw.hooks` w `package.json`. Używaj `openclaw hooks` do filtrowanej widoczności hooków i włączania poszczególnych hooków, nie do instalacji pakietów.
Specyfikacje npm są **wyłącznie rejestrowe** (nazwa pakietu + opcjonalna **dokładna wersja** lub **dist-tag**). Specyfikacje Git/URL/file oraz zakresy semver są odrzucane. Instalacje zależności działają lokalnie w projekcie z `--ignore-scripts` dla bezpieczeństwa, nawet gdy Twoja powłoka ma globalne ustawienia instalacji npm.
Specyfikacje npm są **wyłącznie rejestrowe** (nazwa pakietu + opcjonalna **dokładna wersja** albo **dist-tag**). Specyfikacje Git/URL/file i zakresy semver są odrzucane. Instalacje zależności działają lokalnie w projekcie z `--ignore-scripts` ze względów bezpieczeństwa, nawet jeśli Twoja powłoka ma globalne ustawienia instalacji npm.
Użyj `npm:<package>`, gdy chcesz pominąć wyszukiwanie w ClawHub i zainstalować bezpośrednio z npm. Same specyfikacje pakietów nadal preferują ClawHub i wracają do npm tylko wtedy, gdy ClawHub nie ma tego pakietu lub wersji.
Użyj `npm:<package>`, gdy chcesz pominąć wyszukiwanie w ClawHub i zainstalować bezpośrednio z npm. Same specyfikacje pakietów nadal preferują ClawHub i wracają do npm tylko wtedy, gdy ClawHub nie ma danego pakietu albo wersji.
Same specyfikacje i `@latest` pozostają na stabilnej ścieżce. Jeśli npm rozwiąże którąkolwiek z nich do wersji przedwydaniowej, OpenClaw zatrzyma się i poprosi o jawne wyrażenie zgody za pomocą tagu przedwydaniowego, takiego jak `@beta`/`@rc`, albo dokładnej wersji przedwydaniowej, takiej jak `@1.2.3-beta.4`.
Same specyfikacje i `@latest` pozostają na stabilnej ścieżce. Jeśli npm rozwiąże którąkolwiek z nich do wersji przedpremierowej, OpenClaw zatrzyma się i poprosi o jawne wyrażenie zgody za pomocą tagu przedpremierowego, takiego jak `@beta`/`@rc`, albo dokładnej wersji przedpremierowej, takiej jak `@1.2.3-beta.4`.
Jeśli sama specyfikacja instalacji pasuje do identyfikatora dołączonego Pluginu (na przykład `diffs`), OpenClaw instaluje dołączony Plugin bezpośrednio. Aby zainstalować pakiet npm o tej samej nazwie, użyj jawnej specyfikacji z zakresem (na przykład `@scope/diffs`).
Jeśli sama specyfikacja instalacji pasuje do identyfikatora dołączonego Pluginu (na przykład `diffs`), OpenClaw zainstaluje bezpośrednio dołączony Plugin. Aby zainstalować pakiet npm o tej samej nazwie, użyj jawnej specyfikacji z zakresem (na przykład `@scope/diffs`).
</Accordion>
<Accordion title="Archives">
Obsługiwane archiwa: `.zip`, `.tgz`, `.tar.gz`, `.tar`. Archiwa natywnych Pluginów OpenClaw muszą zawierać prawidłowy `openclaw.plugin.json` w wyodrębnionym katalogu głównym Pluginu; archiwa zawierające tylko `package.json` są odrzucane, zanim OpenClaw zapisze rekordy instalacji.
<Accordion title="Archiwa">
Obsługiwane archiwa: `.zip`, `.tgz`, `.tar.gz`, `.tar`. Archiwa natywnych Pluginów OpenClaw muszą zawierać prawidłowy `openclaw.plugin.json` w wyodrębnionym katalogu głównym Pluginu; archiwa, które zawierają tylko `package.json`, są odrzucane, zanim OpenClaw zapisze rekordy instalacji.
Obsługiwane są także instalacje z marketplace Claude.
@ -143,25 +152,25 @@ openclaw plugins install clawhub:openclaw-codex-app-server
openclaw plugins install clawhub:openclaw-codex-app-server@1.2.3
```
OpenClaw preferuje teraz także ClawHub dla samych, bezpiecznych dla npm specyfikacji Pluginów. Wraca do npm tylko wtedy, gdy ClawHub nie ma tego pakietu lub wersji:
OpenClaw preferuje teraz także ClawHub dla samych, bezpiecznych dla npm specyfikacji Pluginów. Wraca do npm tylko wtedy, gdy ClawHub nie ma danego pakietu albo wersji:
```bash
openclaw plugins install openclaw-codex-app-server
```
Użyj `npm:`, aby wymusić rozwiązywanie wyłącznie przez npm, na przykład gdy ClawHub jest niedostępny albo wiesz, że pakiet istnieje tylko w npm:
Użyj `npm:`, aby wymusić rozwiązywanie wyłącznie przez npm, na przykład gdy ClawHub jest nieosiągalny albo wiesz, że pakiet istnieje tylko w npm:
```bash
openclaw plugins install npm:openclaw-codex-app-server
openclaw plugins install npm:@scope/plugin-name@1.0.1
```
OpenClaw pobiera archiwum pakietu z ClawHub, sprawdza deklarowaną zgodność API Pluginu / minimalną zgodność Gateway, a następnie instaluje je przez normalną ścieżkę archiwum. Zarejestrowane instalacje zachowują metadane źródła ClawHub na potrzeby późniejszych aktualizacji.
Instalacje ClawHub bez wersji zachowują zarejestrowaną specyfikację bez wersji, aby `openclaw plugins update` mogło śledzić nowsze wydania ClawHub; jawne selektory wersji lub tagów, takie jak `clawhub:pkg@1.2.3` i `clawhub:pkg@beta`, pozostają przypięte do tego selektora.
OpenClaw pobiera archiwum pakietu z ClawHub, sprawdza deklarowane API Pluginu / minimalną zgodność z Gateway, a następnie instaluje je zwykłą ścieżką archiwum. Zarejestrowane instalacje zachowują metadane źródła ClawHub na potrzeby późniejszych aktualizacji.
Instalacje ClawHub bez wersji zachowują zarejestrowaną specyfikację bez wersji, aby `openclaw plugins update` mógł śledzić nowsze wydania ClawHub; jawne selektory wersji lub tagów, takie jak `clawhub:pkg@1.2.3` i `clawhub:pkg@beta`, pozostają przypięte do tego selektora.
#### Skrót marketplace
Użyj skrótu `plugin@marketplace`, gdy nazwa marketplace istnieje w lokalnej pamięci podręcznej rejestru Claude pod `~/.claude/plugins/known_marketplaces.json`:
Użyj skrótu `plugin@marketplace`, gdy nazwa marketplace istnieje w lokalnej pamięci podręcznej rejestru Claude w `~/.claude/plugins/known_marketplaces.json`:
```bash
openclaw plugins marketplace list <marketplace-name>
@ -178,16 +187,16 @@ openclaw plugins install <plugin-name> --marketplace ./my-marketplace
```
<Tabs>
<Tab title="Marketplace sources">
<Tab title="Źródła marketplace">
- nazwa znanego marketplace Claude z `~/.claude/plugins/known_marketplaces.json`
- lokalny katalog główny marketplace lub ścieżka `marketplace.json`
- lokalny katalog główny marketplace albo ścieżka `marketplace.json`
- skrót repozytorium GitHub, taki jak `owner/repo`
- URL repozytorium GitHub, taki jak `https://github.com/owner/repo`
- URL git
</Tab>
<Tab title="Remote marketplace rules">
W przypadku zdalnych marketplace ładowanych z GitHub lub git wpisy Pluginów muszą pozostawać wewnątrz sklonowanego repozytorium marketplace. OpenClaw akceptuje względne źródła ścieżek z tego repozytorium i odrzuca HTTP(S), ścieżki bezwzględne, git, GitHub oraz inne nieścieżkowe źródła Pluginów ze zdalnych manifestów.
<Tab title="Reguły zdalnego marketplace">
W przypadku zdalnych marketplace ładowanych z GitHub lub git wpisy Pluginów muszą pozostawać wewnątrz sklonowanego repozytorium marketplace. OpenClaw akceptuje źródła ze ścieżkami względnymi z tego repozytorium i odrzuca HTTP(S), ścieżki bezwzględne, git, GitHub oraz inne źródła Pluginów niebędące ścieżkami ze zdalnych manifestów.
</Tab>
</Tabs>
@ -195,11 +204,11 @@ Dla ścieżek lokalnych i archiwów OpenClaw automatycznie wykrywa:
- natywne Pluginy OpenClaw (`openclaw.plugin.json`)
- pakiety zgodne z Codex (`.codex-plugin/plugin.json`)
- pakiety zgodne z Claude (`.claude-plugin/plugin.json` lub domyślny układ komponentów Claude)
- pakiety zgodne z Claude (`.claude-plugin/plugin.json` albo domyślny układ komponentów Claude)
- pakiety zgodne z Cursor (`.cursor-plugin/plugin.json`)
<Note>
Zgodne pakiety instalują się w normalnym katalogu głównym Pluginów i uczestniczą w tym samym przepływie list/info/enable/disable. Obecnie obsługiwane są Skills pakietów, command-skills Claude, domyślne wartości Claude `settings.json`, domyślne wartości Claude `.lsp.json` / zadeklarowanych w manifeście `lspServers`, command-skills Cursor oraz zgodne katalogi hooków Codex; inne wykryte możliwości pakietów są pokazywane w diagnostyce/info, ale nie są jeszcze podłączone do wykonywania w czasie działania.
Zgodne pakiety instalują się w zwykłym katalogu głównym Pluginów i uczestniczą w tym samym przepływie list/info/enable/disable. Obecnie obsługiwane są Skills pakietów, command-skills Claude, domyślne ustawienia Claude `settings.json`, domyślne ustawienia Claude `.lsp.json` / deklarowane w manifeście `lspServers`, command-skills Cursor oraz zgodne katalogi hooków Codex; inne wykryte możliwości pakietów są pokazywane w diagnostyce/info, ale nie są jeszcze podłączone do wykonywania w runtime.
</Note>
### Lista
@ -215,45 +224,45 @@ openclaw plugins list --json
Pokaż tylko włączone Pluginy.
</ParamField>
<ParamField path="--verbose" type="boolean">
Przełącz z widoku tabeli na szczegółowe wiersze dla każdego Pluginu z metadanymi źródła/pochodzenia/wersji/aktywacji.
Przełącz z widoku tabeli na szczegółowe wiersze dla każdego Pluginu z metadanymi source/origin/version/activation.
</ParamField>
<ParamField path="--json" type="boolean">
Czytelny maszynowo inwentarz oraz diagnostyka rejestru.
Inwentarz czytelny maszynowo oraz diagnostyka rejestru.
</ParamField>
<Note>
`plugins list` najpierw odczytuje utrwalony lokalny rejestr pluginów, z awaryjnym wariantem pochodnym wyłącznie z manifestu, gdy rejestru brakuje albo jest nieprawidłowy. Przydaje się do sprawdzania, czy plugin jest zainstalowany, włączony i widoczny dla planowania zimnego startu, ale nie jest aktywną sondą środowiska uruchomieniowego już działającego procesu Gateway. Po zmianie kodu pluginu, włączenia, polityki haków albo `plugins.load.paths` uruchom ponownie Gateway obsługujący kanał, zanim będziesz oczekiwać uruchomienia nowego kodu `register(api)` albo haków. W przypadku wdrożeń zdalnych/kontenerowych sprawdź, czy restartujesz faktyczny proces potomny `openclaw gateway run`, a nie tylko proces opakowujący.
`plugins list` najpierw odczytuje utrwalony lokalny rejestr Plugin, z rezerwowym wariantem wyprowadzanym tylko z manifestu, gdy rejestru brakuje lub jest nieprawidłowy. Przydaje się do sprawdzania, czy Plugin jest zainstalowany, włączony i widoczny dla planowania zimnego startu, ale nie jest aktywną sondą środowiska uruchomieniowego już działającego procesu Gateway. Po zmianie kodu Plugin, włączenia, zasad hooków lub `plugins.load.paths` uruchom ponownie Gateway obsługujący kanał, zanim oczekujesz uruchomienia nowego kodu `register(api)` lub hooków. W przypadku wdrożeń zdalnych/kontenerowych sprawdź, czy uruchamiasz ponownie właściwy proces potomny `openclaw gateway run`, a nie tylko proces opakowujący.
</Note>
W przypadku pracy nad dołączonym pluginem wewnątrz spakowanego obrazu Docker podmontuj katalog źródłowy pluginu
na odpowiadającą mu spakowaną ścieżkę źródłową, na przykład
`/app/extensions/synology-chat`. OpenClaw wykryje tę podmontowaną nakładkę źródeł
Podczas pracy nad dołączonym Plugin wewnątrz spakowanego obrazu Docker podmontuj katalog
źródłowy Plugin na odpowiadającą mu spakowaną ścieżkę źródłową, na przykład
`/app/extensions/synology-chat`. OpenClaw wykryje tę podmontowaną nakładkę źródłową
przed `/app/dist/extensions/synology-chat`; zwykły skopiowany katalog źródłowy
pozostaje nieaktywny, więc normalne instalacje pakietowe nadal używają skompilowanego dist.
pozostaje nieaktywny, więc standardowe spakowane instalacje nadal używają skompilowanego dist.
Do debugowania haków środowiska uruchomieniowego:
Do debugowania hooków środowiska uruchomieniowego:
- `openclaw plugins inspect <id> --json` pokazuje zarejestrowane haki i diagnostykę z przebiegu inspekcji po załadowaniu modułu.
- `openclaw plugins inspect <id> --runtime --json` pokazuje zarejestrowane hooki i diagnostykę z przebiegu inspekcji z załadowanym modułem. Inspekcja środowiska uruchomieniowego nigdy nie pobiera brakujących dołączonych zależności środowiska uruchomieniowego; użyj `openclaw plugins deps --repair`, gdy potrzebna jest naprawa.
- `openclaw gateway status --deep --require-rpc` potwierdza osiągalny Gateway, wskazówki dotyczące usługi/procesu, ścieżkę konfiguracji i kondycję RPC.
- Niedołączone haki konwersacji (`llm_input`, `llm_output`, `before_agent_finalize`, `agent_end`) wymagają `plugins.entries.<id>.hooks.allowConversationAccess=true`.
- Niedostarczane w zestawie hooki konwersacji (`llm_input`, `llm_output`, `before_agent_finalize`, `agent_end`) wymagają `plugins.entries.<id>.hooks.allowConversationAccess=true`.
Użyj `--link`, aby uniknąć kopiowania katalogu lokalnego (dodaje do `plugins.load.paths`):
Użyj `--link`, aby uniknąć kopiowania lokalnego katalogu (dodaje do `plugins.load.paths`):
```bash
openclaw plugins install -l ./my-plugin
```
<Note>
`--force` nie jest obsługiwane z `--link`, ponieważ instalacje linkowane ponownie używają ścieżki źródłowej zamiast kopiować pliki na zarządzany cel instalacji.
`--force` nie jest obsługiwane z `--link`, ponieważ instalacje linkowane ponownie używają ścieżki źródłowej zamiast kopiować na zarządzany cel instalacji.
Użyj `--pin` przy instalacjach npm, aby zapisać rozwiązaną dokładną specyfikację (`name@version`) w zarządzanym indeksie pluginów, zachowując domyślne zachowanie bez przypięcia.
Użyj `--pin` przy instalacjach npm, aby zapisać rozwiązaną dokładną specyfikację (`name@version`) w zarządzanym indeksie Plugin, zachowując domyślne zachowanie bez przypięcia.
</Note>
### Indeks pluginów
### Indeks Plugin
Metadane instalacji pluginów są stanem zarządzanym przez maszynę, a nie konfiguracją użytkownika. Instalacje i aktualizacje zapisują je do `plugins/installs.json` w aktywnym katalogu stanu OpenClaw. Jego mapa najwyższego poziomu `installRecords` jest trwałym źródłem metadanych instalacji, w tym rekordów dla uszkodzonych lub brakujących manifestów pluginów. Tablica `plugins` jest pamięcią podręczną zimnego rejestru pochodną z manifestów. Plik zawiera ostrzeżenie, aby go nie edytować, i jest używany przez `openclaw plugins update`, odinstalowywanie, diagnostykę oraz zimny rejestr pluginów.
Metadane instalacji Plugin są stanem zarządzanym maszynowo, a nie konfiguracją użytkownika. Instalacje i aktualizacje zapisują je do `plugins/installs.json` w aktywnym katalogu stanu OpenClaw. Jego najwyższego poziomu mapa `installRecords` jest trwałym źródłem metadanych instalacji, w tym rekordów dla uszkodzonych lub brakujących manifestów Plugin. Tablica `plugins` jest wyprowadzoną z manifestów pamięcią podręczną zimnego rejestru. Plik zawiera ostrzeżenie, aby go nie edytować, i jest używany przez `openclaw plugins update`, odinstalowywanie, diagnostykę oraz zimny rejestr Plugin.
Gdy OpenClaw wykryje dostarczone starsze rekordy `plugins.installs` w konfiguracji, przenosi je do indeksu pluginów i usuwa klucz konfiguracji; jeśli którykolwiek zapis się nie powiedzie, rekordy konfiguracji są zachowywane, aby metadane instalacji nie zostały utracone.
Gdy OpenClaw zobaczy dostarczone starsze rekordy `plugins.installs` w konfiguracji, przenosi je do indeksu Plugin i usuwa klucz konfiguracji; jeśli którykolwiek zapis się nie powiedzie, rekordy konfiguracji zostają zachowane, aby metadane instalacji nie zostały utracone.
### Zależności środowiska uruchomieniowego
@ -264,9 +273,11 @@ openclaw plugins deps --prune
openclaw plugins deps --json
```
`plugins deps` sprawdza spakowany etap zależności środowiska uruchomieniowego dla należących do OpenClaw dołączonych pluginów wybranych przez konfigurację pluginów, włączone/skonfigurowane kanały, skonfigurowanych dostawców modeli albo domyślne ustawienia dołączonych manifestów. Nie jest to ścieżka instalacji/aktualizacji dla zewnętrznych pluginów npm ani ClawHub.
`plugins deps` sprawdza etap spakowanych zależności środowiska uruchomieniowego dla należących do OpenClaw dołączonych Plugin wybranych przez konfigurację Plugin, włączone/skonfigurowane kanały, skonfigurowanych dostawców modeli lub domyślne wartości dołączonych manifestów. Nie jest to ścieżka instalacji/aktualizacji dla zewnętrznych Plugin npm ani ClawHub.
Użyj `--repair`, gdy instalacja pakietowa zgłasza brakujące dołączone zależności środowiska uruchomieniowego podczas startu Gateway albo `plugins doctor`. Naprawa instaluje tylko brakujące zależności włączonych dołączonych pluginów, z wyłączonymi skryptami cyklu życia. Użyj `--prune`, aby usunąć przestarzałe, nieznane zewnętrzne korzenie zależności środowiska uruchomieniowego pozostawione przez starsze układy pakietów.
Użyj `--repair`, gdy spakowana instalacja zgłasza brakujące dołączone zależności środowiska uruchomieniowego podczas startu Gateway lub `plugins doctor`. Naprawa instaluje tylko brakujące zależności włączonych dołączonych Plugin z wyłączonymi skryptami cyklu życia. Użyj `--prune`, aby usunąć nieaktualne, nieznane zewnętrzne katalogi główne zależności środowiska uruchomieniowego pozostawione przez starsze układy pakietów.
Pełny plan, etapowanie i cykl życia naprawy opisuje [Rozwiązywanie zależności Plugin](/pl/plugins/dependency-resolution).
### Odinstalowanie
@ -276,7 +287,7 @@ openclaw plugins uninstall <id> --dry-run
openclaw plugins uninstall <id> --keep-files
```
`uninstall` usuwa rekordy pluginów z `plugins.entries`, utrwalonego indeksu pluginów, wpisów listy zezwoleń/odmów dla pluginów oraz połączonych wpisów `plugins.load.paths`, gdy ma to zastosowanie. O ile nie ustawiono `--keep-files`, odinstalowanie usuwa też śledzony zarządzany katalog instalacji, gdy znajduje się on w głównym katalogu rozszerzeń pluginów OpenClaw. W przypadku pluginów Active Memory slot pamięci jest resetowany do `memory-core`.
`uninstall` usuwa rekordy Plugin z `plugins.entries`, utrwalonego indeksu Plugin, wpisów listy dozwolonych/zablokowanych Plugin oraz linkowanych wpisów `plugins.load.paths`, gdy ma to zastosowanie. O ile nie ustawiono `--keep-files`, odinstalowanie usuwa także śledzony zarządzany katalog instalacji, gdy znajduje się on w katalogu głównym rozszerzeń Plugin OpenClaw. W przypadku Plugin aktywnej pamięci slot pamięci resetuje się do `memory-core`.
<Note>
`--keep-config` jest obsługiwane jako przestarzały alias dla `--keep-files`.
@ -292,25 +303,25 @@ openclaw plugins update @openclaw/voice-call@beta
openclaw plugins update openclaw-codex-app-server --dangerously-force-unsafe-install
```
Aktualizacje dotyczą śledzonych instalacji pluginów w zarządzanym indeksie pluginów oraz śledzonych instalacji pakietów haków w `hooks.internal.installs`.
Aktualizacje dotyczą śledzonych instalacji Plugin w zarządzanym indeksie Plugin oraz śledzonych instalacji pakietów hooków w `hooks.internal.installs`.
<AccordionGroup>
<Accordion title="Rozwiązywanie id pluginu kontra specyfikacja npm">
Gdy przekazujesz id pluginu, OpenClaw ponownie używa zapisanej specyfikacji instalacji dla tego pluginu. Oznacza to, że wcześniej zapisane tagi dystrybucyjne, takie jak `@beta`, i dokładne przypięte wersje będą nadal używane podczas późniejszych uruchomień `update <id>`.
<Accordion title="Rozwiązywanie identyfikatora Plugin względem specyfikacji npm">
Gdy podasz identyfikator Plugin, OpenClaw ponownie użyje zapisanej specyfikacji instalacji dla tego Plugin. Oznacza to, że wcześniej zapisane tagi dist, takie jak `@beta`, oraz dokładnie przypięte wersje będą nadal używane przy późniejszych uruchomieniach `update <id>`.
W przypadku instalacji npm możesz też przekazać jawną specyfikację pakietu npm z tagiem dystrybucyjnym albo dokładną wersją. OpenClaw rozwiązuje tę nazwę pakietu z powrotem do śledzonego rekordu pluginu, aktualizuje ten zainstalowany plugin i zapisuje nową specyfikację npm do przyszłych aktualizacji opartych na id.
W przypadku instalacji npm możesz także podać jawną specyfikację pakietu npm z tagiem dist lub dokładną wersją. OpenClaw rozwiązuje tę nazwę pakietu z powrotem do śledzonego rekordu Plugin, aktualizuje ten zainstalowany Plugin i zapisuje nową specyfikację npm dla przyszłych aktualizacji opartych na identyfikatorze.
Przekazanie nazwy pakietu npm bez wersji lub tagu także rozwiązuje ją z powrotem do śledzonego rekordu pluginu. Użyj tego, gdy plugin był przypięty do dokładnej wersji i chcesz przenieść go z powrotem na domyślną linię wydań rejestru.
Podanie nazwy pakietu npm bez wersji lub tagu także rozwiązuje się z powrotem do śledzonego rekordu Plugin. Użyj tego, gdy Plugin był przypięty do dokładnej wersji i chcesz przenieść go z powrotem na domyślną linię wydań rejestru.
</Accordion>
<Accordion title="Kontrole wersji i dryf integralności">
Przed aktywną aktualizacją npm OpenClaw sprawdza zainstalowaną wersję pakietu względem metadanych rejestru npm. Jeśli zainstalowana wersja i zapisana tożsamość artefaktu już pasują do rozwiązanego celu, aktualizacja jest pomijana bez pobierania, ponownej instalacji ani przepisywania `openclaw.json`.
Przed aktywną aktualizacją npm OpenClaw sprawdza zainstalowaną wersję pakietu względem metadanych rejestru npm. Jeśli zainstalowana wersja i zapisana tożsamość artefaktu już odpowiadają rozwiązanemu celowi, aktualizacja jest pomijana bez pobierania, ponownej instalacji ani przepisywania `openclaw.json`.
Gdy istnieje zapisany hash integralności, a hash pobranego artefaktu się zmienia, OpenClaw traktuje to jako dryf artefaktu npm. Interaktywne polecenie `openclaw plugins update` wypisuje oczekiwane i faktyczne hashe oraz prosi o potwierdzenie przed kontynuowaniem. Nieinteraktywne pomocniki aktualizacji kończą się zamknięciem z błędem, chyba że wywołujący dostarczy jawną politykę kontynuacji.
Gdy istnieje zapisany hash integralności, a hash pobranego artefaktu się zmieni, OpenClaw traktuje to jako dryf artefaktu npm. Interaktywne polecenie `openclaw plugins update` wypisuje oczekiwane i rzeczywiste hashe oraz prosi o potwierdzenie przed kontynuacją. Nieinteraktywne pomocniki aktualizacji kończą się odmową, chyba że wywołujący dostarczy jawną politykę kontynuacji.
</Accordion>
<Accordion title="--dangerously-force-unsafe-install przy aktualizacji">
`--dangerously-force-unsafe-install` jest też dostępne w `plugins update` jako awaryjne obejście fałszywych alarmów wbudowanego skanowania niebezpiecznego kodu podczas aktualizacji pluginów. Nadal nie omija blokad polityki `before_install` pluginu ani blokowania po niepowodzeniu skanowania i dotyczy tylko aktualizacji pluginów, a nie aktualizacji pakietów haków.
`--dangerously-force-unsafe-install` jest także dostępne w `plugins update` jako awaryjne obejście dla fałszywych alarmów wbudowanego skanowania niebezpiecznego kodu podczas aktualizacji Plugin. Nadal nie omija blokad polityki `before_install` Plugin ani blokowania po niepowodzeniu skanowania i dotyczy tylko aktualizacji Plugin, nie aktualizacji pakietów hooków.
</Accordion>
</AccordionGroup>
@ -318,22 +329,23 @@ Aktualizacje dotyczą śledzonych instalacji pluginów w zarządzanym indeksie p
```bash
openclaw plugins inspect <id>
openclaw plugins inspect <id> --runtime
openclaw plugins inspect <id> --json
```
Głęboka introspekcja pojedynczego pluginu. Pokazuje tożsamość, stan ładowania, źródło, zarejestrowane możliwości, haki, narzędzia, polecenia, usługi, metody Gateway, trasy HTTP, flagi polityki, diagnostykę, metadane instalacji, możliwości pakietu oraz wszelką wykrytą obsługę serwera MCP lub LSP.
Inspekcja pokazuje tożsamość, stan ładowania, źródło, możliwości manifestu, flagi polityk, diagnostykę, metadane instalacji, możliwości pakietu oraz wykrytą obsługę serwerów MCP lub LSP bez domyślnego importowania środowiska uruchomieniowego Plugin. Dodaj `--runtime`, aby załadować moduł Plugin i uwzględnić zarejestrowane hooki, narzędzia, polecenia, usługi, metody Gateway oraz trasy HTTP. Inspekcja środowiska uruchomieniowego kończy się niepowodzeniem ze wskazówką naprawy, gdy brakuje dołączonych zależności środowiska uruchomieniowego; użyj `openclaw plugins deps --repair`, aby jawnie je naprawić.
Każdy plugin jest klasyfikowany według tego, co faktycznie rejestruje w środowisku uruchomieniowym:
Każdy Plugin jest klasyfikowany według tego, co faktycznie rejestruje w środowisku uruchomieniowym:
- **plain-capability** — jeden typ możliwości (np. plugin tylko dostawcy)
- **plain-capability** — jeden typ możliwości (np. Plugin tylko dla dostawcy)
- **hybrid-capability** — wiele typów możliwości (np. tekst + mowa + obrazy)
- **hook-only** — tylko haki, bez możliwości ani powierzchni
- **hook-only** — tylko hooki, bez możliwości ani powierzchni
- **non-capability** — narzędzia/polecenia/usługi, ale bez możliwości
Zobacz [Kształty pluginów](/pl/plugins/architecture#plugin-shapes), aby dowiedzieć się więcej o modelu możliwości.
Więcej informacji o modelu możliwości zawiera [Kształty Plugin](/pl/plugins/architecture#plugin-shapes).
<Note>
Flaga `--json` wypisuje raport czytelny maszynowo, odpowiedni do skryptowania i audytu. `inspect --all` renderuje tabelę dla całej floty z kolumnami kształtu, rodzajów możliwości, powiadomień o zgodności, możliwości pakietu i podsumowania haków. `info` jest aliasem dla `inspect`.
Flaga `--json` wypisuje raport czytelny maszynowo, odpowiedni do skryptów i audytu. `inspect --all` renderuje tabelę dla całej floty z kolumnami kształtu, rodzajów możliwości, powiadomień o zgodności, możliwości pakietu i podsumowania hooków. `info` jest aliasem dla `inspect`.
</Note>
### Doctor
@ -342,9 +354,9 @@ Flaga `--json` wypisuje raport czytelny maszynowo, odpowiedni do skryptowania i
openclaw plugins doctor
```
`doctor` zgłasza błędy ładowania pluginów, diagnostykę manifestu/wykrywania oraz powiadomienia o zgodności. Gdy wszystko jest czyste, wypisuje `No plugin issues detected.`
`doctor` zgłasza błędy ładowania Plugin, diagnostykę manifestu/wykrywania oraz powiadomienia o zgodności. Gdy wszystko jest poprawne, wypisuje `No plugin issues detected.`
W przypadku niepowodzeń kształtu modułu, takich jak brakujące eksporty `register`/`activate`, uruchom ponownie z `OPENCLAW_PLUGIN_LOAD_DEBUG=1`, aby dołączyć zwarte podsumowanie kształtu eksportów w wyjściu diagnostycznym.
W przypadku awarii kształtu modułu, takich jak brak eksportów `register`/`activate`, uruchom ponownie z `OPENCLAW_PLUGIN_LOAD_DEBUG=1`, aby uwzględnić zwarte podsumowanie kształtu eksportów w wyjściu diagnostycznym.
### Rejestr
@ -354,12 +366,12 @@ openclaw plugins registry --refresh
openclaw plugins registry --json
```
Lokalny rejestr pluginów jest utrwalonym modelem zimnego odczytu OpenClaw dla tożsamości zainstalowanych pluginów, włączenia, metadanych źródła i własności wkładów. Normalny start, wyszukiwanie właściciela dostawcy, klasyfikacja konfiguracji kanałów i inwentarz pluginów mogą go odczytywać bez importowania modułów środowiska uruchomieniowego pluginów.
Lokalny rejestr Plugin to utrwalony zimny model odczytu OpenClaw dla tożsamości zainstalowanych Plugin, włączenia, metadanych źródła i własności wkładów. Standardowy start, wyszukiwanie właściciela dostawcy, klasyfikacja konfiguracji kanału i inwentarz Plugin mogą go odczytywać bez importowania modułów środowiska uruchomieniowego Plugin.
Użyj `plugins registry`, aby sprawdzić, czy utrwalony rejestr jest obecny, aktualny albo przestarzały. Użyj `--refresh`, aby odbudować go z utrwalonego indeksu pluginów, polityki konfiguracji oraz metadanych manifestu/pakietu. To jest ścieżka naprawy, a nie ścieżka aktywacji środowiska uruchomieniowego.
Użyj `plugins registry`, aby sprawdzić, czy utrwalony rejestr jest obecny, aktualny lub nieaktualny. Użyj `--refresh`, aby odbudować go z utrwalonego indeksu Plugin, polityki konfiguracji i metadanych manifestu/pakietu. To ścieżka naprawy, a nie ścieżka aktywacji środowiska uruchomieniowego.
<Warning>
`OPENCLAW_DISABLE_PERSISTED_PLUGIN_REGISTRY=1` to przestarzały awaryjny przełącznik zgodności na wypadek błędów odczytu rejestru. Preferuj `plugins registry --refresh` albo `openclaw doctor --fix`; awaryjny wariant env służy tylko do odzyskiwania startu w nagłych sytuacjach, gdy migracja jest wdrażana.
`OPENCLAW_DISABLE_PERSISTED_PLUGIN_REGISTRY=1` to przestarzały awaryjny przełącznik zgodności dla błędów odczytu rejestru. Preferuj `plugins registry --refresh` lub `openclaw doctor --fix`; rezerwowe zachowanie env służy tylko do awaryjnego odzyskania startu podczas wdrażania migracji.
</Warning>
### Marketplace
@ -369,10 +381,10 @@ openclaw plugins marketplace list <source>
openclaw plugins marketplace list <source> --json
```
Lista Marketplace akceptuje lokalną ścieżkę Marketplace, ścieżkę `marketplace.json`, skrót GitHub taki jak `owner/repo`, URL repozytorium GitHub albo URL git. `--json` wypisuje rozwiązaną etykietę źródła oraz sparsowany manifest Marketplace i wpisy pluginów.
Lista Marketplace przyjmuje lokalną ścieżkę marketplace, ścieżkę `marketplace.json`, skrót GitHub taki jak `owner/repo`, URL repo GitHub albo URL git. `--json` wypisuje rozwiązaną etykietę źródła oraz sparsowany manifest marketplace i wpisy Plugin.
## Powiązane
- [Budowanie pluginów](/pl/plugins/building-plugins)
- [Budowanie Plugin](/pl/plugins/building-plugins)
- [Dokumentacja CLI](/pl/cli)
- [Pluginy społecznościowe](/pl/plugins/community)
- [Społecznościowe Plugin](/pl/plugins/community)

57
docs/pl/cli/proxy.md
View File

@ -1,32 +1,36 @@
---
read_when:
- Musisz lokalnie przechwycić ruch transportowy OpenClaw do debugowania
- Chcesz sprawdzić sesje proxy debugowania, blob-y lub wbudowane presety zapytań
summary: Dokumentacja CLI dla `openclaw proxy`, lokalnego proxy debugowania i inspektora przechwyceń
title: Proxy
- Musisz zweryfikować routing przez proxy zarządzane przez operatora przed wdrożeniem
- Musisz lokalnie przechwycić ruch transportowy OpenClaw w celu debugowania.
- Chcesz sprawdzić sesje proxy debugowania, obiekty blob lub wbudowane ustawienia wstępne zapytań
summary: Dokumentacja referencyjna CLI dla `openclaw proxy`, obejmująca walidację proxy zarządzanego przez operatora i inspektor przechwytywania lokalnego proxy debugowania
title: Serwer proxy
x-i18n:
generated_at: "2026-04-24T09:03:57Z"
model: gpt-5.4
generated_at: "2026-05-01T09:57:47Z"
model: gpt-5.5
provider: openai
source_hash: 7af5c596fb36f67e3fcffaff14dcbb4eabbcff0b95174ac6058a097ec9fd715f
source_hash: e0820de861bfe1ec14e0c1624d636d6474b5fedd317e3ba1baaa61f6530e06e9
source_path: cli/proxy.md
workflow: 15
workflow: 16
---
# `openclaw proxy`
Uruchamiaj lokalne jawne proxy debugowania i sprawdzaj przechwycony ruch.
Sprawdź routing proxy zarządzany przez operatora albo uruchom lokalny jawny proxy debugowania
i przeanalizuj przechwycony ruch.
To polecenie debugowania służy do badania na poziomie transportu. Może uruchomić
lokalne proxy, uruchomić polecenie potomne z włączonym przechwytywaniem, wyświetlić sesje przechwyceń,
odpytować typowe wzorce ruchu, odczytywać przechwycone blob-y i czyścić lokalne dane
przechwyceń.
Użyj `validate`, aby wstępnie sprawdzić forward proxy zarządzany przez operatora przed włączeniem
routingu proxy OpenClaw. Pozostałe polecenia to narzędzia debugowania do
diagnostyki na poziomie transportu: mogą uruchomić lokalny proxy, uruchomić polecenie podrzędne
z włączonym przechwytywaniem, wyświetlić sesje przechwytywania, wyszukiwać typowe wzorce ruchu, odczytywać
przechwycone bloby oraz usuwać lokalne dane przechwytywania.
## Polecenia
```bash
openclaw proxy start [--host <host>] [--port <port>]
openclaw proxy run [--host <host>] [--port <port>] -- <cmd...>
openclaw proxy validate [--json] [--proxy-url <url>] [--allowed-url <url>] [--denied-url <url>] [--timeout-ms <ms>]
openclaw proxy coverage
openclaw proxy sessions [--limit <count>]
openclaw proxy query --preset <name> [--session <id>]
@ -34,6 +38,27 @@ openclaw proxy blob --id <blobId>
openclaw proxy purge
```
## Walidacja
`openclaw proxy validate` sprawdza efektywny adres URL proxy zarządzanego przez operatora z
`--proxy-url`, konfiguracji albo `OPENCLAW_PROXY_URL`. Zgłasza problem z konfiguracją, gdy
żaden proxy nie jest włączony i skonfigurowany; użyj `--proxy-url` do jednorazowego wstępnego sprawdzenia
przed zmianą konfiguracji. Domyślnie weryfikuje, czy publiczne miejsce docelowe działa
przez proxy oraz czy proxy nie może dotrzeć do tymczasowego kanarka loopback.
Niestandardowe odrzucane miejsca docelowe działają w trybie fail-closed: odpowiedzi HTTP i niejednoznaczne
awarie transportowe kończą się niepowodzeniem, chyba że możesz osobno zweryfikować specyficzny dla wdrożenia
sygnał odmowy.
Opcje:
- `--json`: wypisz JSON czytelny maszynowo.
- `--proxy-url <url>`: zweryfikuj ten adres URL proxy zamiast konfiguracji lub zmiennej środowiskowej.
- `--allowed-url <url>`: dodaj miejsce docelowe, które powinno działać przez proxy. Powtórz, aby sprawdzić wiele miejsc docelowych.
- `--denied-url <url>`: dodaj miejsce docelowe, które powinno być blokowane przez proxy. Powtórz, aby sprawdzić wiele miejsc docelowych.
- `--timeout-ms <ms>`: limit czasu na żądanie w milisekundach.
Zobacz [Proxy sieciowy](/pl/security/network-proxy), aby uzyskać wskazówki dotyczące wdrożenia i semantyki odmowy.
## Presety zapytań
`openclaw proxy query --preset <name>` akceptuje:
@ -48,10 +73,12 @@ openclaw proxy purge
## Uwagi
- `start` domyślnie używa `127.0.0.1`, chyba że ustawiono `--host`.
- `run` uruchamia lokalne proxy debugowania, a następnie uruchamia polecenie po `--`.
- Przechwycenia to lokalne dane debugowania; po zakończeniu użyj `openclaw proxy purge`.
- `run` uruchamia lokalny proxy debugowania, a następnie uruchamia polecenie po `--`.
- `validate` kończy działanie z kodem 1, gdy konfiguracja proxy lub sprawdzenia miejsc docelowych nie powiodą się.
- Przechwycone dane są lokalnymi danymi debugowania; użyj `openclaw proxy purge` po zakończeniu.
## Powiązane
- [Dokumentacja CLI](/pl/cli)
- [Proxy sieciowy](/pl/security/network-proxy)
- [Uwierzytelnianie zaufanego proxy](/pl/gateway/trusted-proxy-auth)

113
docs/pl/cli/update.md
View File

@ -1,14 +1,14 @@
---
read_when:
- Chcesz bezpiecznie zaktualizować roboczą kopię źródeł
- Należy zrozumieć zachowanie skrótu `--update`
summary: Referencja CLI dla `openclaw update` (względnie bezpieczna aktualizacja źródeł + automatyczny restart Gateway)
- Chcesz bezpiecznie zaktualizować kopię roboczą kodu źródłowego
- Musisz zrozumieć zachowanie skrótu `--update`
summary: Dokumentacja referencyjna CLI dla `openclaw update` (względnie bezpieczna aktualizacja źródła + automatyczne ponowne uruchomienie Gateway)
title: Aktualizacja
x-i18n:
generated_at: "2026-04-30T09:45:52Z"
generated_at: "2026-05-01T09:57:45Z"
model: gpt-5.5
provider: openai
source_hash: 9cd4be6be8f6ae7df501f8bce3d208dd507ae5a1539f9772101cd844dcd93976
source_hash: bfbbd6e3cd1a83e3700fa248a6ce2cb3adf1c94d0d5491895eea21bfec5d52b0
source_path: cli/update.md
workflow: 16
---
@ -39,23 +39,23 @@ openclaw --update
## Opcje
- `--no-restart`: pomija ponowne uruchomienie usługi Gateway po pomyślnej aktualizacji. Aktualizacje przez menedżera pakietów, które ponownie uruchamiają Gateway, przed powodzeniem polecenia weryfikują, że ponownie uruchomiona usługa zgłasza oczekiwaną zaktualizowaną wersję.
- `--channel <stable|beta|dev>`: ustawia kanał aktualizacji (git + npm; zapisywany w konfiguracji).
- `--tag <dist-tag|version|spec>`: nadpisuje docelowy pakiet tylko dla tej aktualizacji. W przypadku instalacji pakietowych `main` mapuje się na `github:openclaw/openclaw#main`.
- `--dry-run`: wyświetla planowane działania aktualizacji (kanał/tag/cel/przepływ ponownego uruchomienia) bez zapisywania konfiguracji, instalowania, synchronizowania plugins ani ponownego uruchamiania.
- `--no-restart`: pomija ponowne uruchomienie usługi Gateway po udanej aktualizacji. Aktualizacje przez menedżera pakietów, które ponownie uruchamiają Gateway, sprawdzają przed powodzeniem polecenia, czy ponownie uruchomiona usługa zgłasza oczekiwaną zaktualizowaną wersję.
- `--channel <stable|beta|dev>`: ustawia kanał aktualizacji (git + npm; utrwalany w konfiguracji).
- `--tag <dist-tag|version|spec>`: nadpisuje cel pakietu tylko dla tej aktualizacji. Dla instalacji pakietowych `main` mapuje się na `github:openclaw/openclaw#main`.
- `--dry-run`: pokazuje planowane działania aktualizacji (kanał/tag/cel/przepływ ponownego uruchomienia) bez zapisywania konfiguracji, instalowania, synchronizowania pluginów ani ponownego uruchamiania.
- `--json`: wypisuje czytelny maszynowo JSON `UpdateRunResult`, w tym
`postUpdate.plugins.integrityDrifts`, gdy podczas synchronizacji plugins po aktualizacji
wykryto dryf artefaktu npm plugin.
- `--timeout <seconds>`: limit czasu dla każdego kroku (domyślnie 1800s).
- `--yes`: pomija monity o potwierdzenie (na przykład potwierdzenie downgrade'u).
`postUpdate.plugins.integrityDrifts`, gdy podczas synchronizacji pluginów po aktualizacji
zostanie wykryty dryf artefaktu pluginu npm.
- `--timeout <seconds>`: limit czasu dla każdego kroku (domyślnie 1800 s).
- `--yes`: pomija monity o potwierdzenie (na przykład potwierdzenie obniżenia wersji).
<Warning>
Downgrade'y wymagają potwierdzenia, ponieważ starsze wersje mogą uszkodzić konfigurację.
Obniżenie wersji wymaga potwierdzenia, ponieważ starsze wersje mogą uszkodzić konfigurację.
</Warning>
## `update status`
Pokazuje aktywny kanał aktualizacji + tag/gałąź/SHA git (dla checkoutów źródłowych) oraz dostępność aktualizacji.
Pokazuje aktywny kanał aktualizacji + tag/gałąź/SHA git (dla checkoutów źródłowych), a także dostępność aktualizacji.
```bash
openclaw update status
@ -66,12 +66,12 @@ openclaw update status --timeout 10
Opcje:
- `--json`: wypisuje czytelny maszynowo JSON statusu.
- `--timeout <seconds>`: limit czasu sprawdzania (domyślnie 3s).
- `--timeout <seconds>`: limit czasu dla sprawdzeń (domyślnie 3 s).
## `update wizard`
Interaktywny przepływ wyboru kanału aktualizacji i potwierdzenia, czy ponownie uruchomić Gateway
po aktualizacji (domyślnie ponowne uruchomienie). Jeśli wybierzesz `dev` bez checkoutu git,
Interaktywny przepływ wyboru kanału aktualizacji i potwierdzenia, czy po aktualizacji ponownie uruchomić Gateway
(domyślnie jest ponownie uruchamiany). Jeśli wybierzesz `dev` bez checkoutu git,
zaproponuje jego utworzenie.
Opcje:
@ -80,43 +80,48 @@ Opcje:
## Co robi
Gdy jawnie przełączysz kanały (`--channel ...`), OpenClaw utrzymuje też zgodność
Gdy jawnie przełączasz kanały (`--channel ...`), OpenClaw utrzymuje też zgodność
metody instalacji:
- `dev` → zapewnia checkout git (domyślnie: `~/openclaw`, nadpisz przez `OPENCLAW_GIT_DIR`),
aktualizuje go i instaluje globalne CLI z tego checkoutu.
- `dev` → zapewnia checkout git (domyślnie: `~/openclaw`, nadpisanie przez `OPENCLAW_GIT_DIR`),
aktualizuje go i instaluje globalny CLI z tego checkoutu.
- `stable` → instaluje z npm przy użyciu `latest`.
- `beta` → preferuje dist-tag npm `beta`, ale wraca do `latest`, gdy beta jest
niedostępna albo starsza niż bieżące wydanie stable.
- `beta` → preferuje dist-tag npm `beta`, ale wraca do `latest`, gdy beta
nie istnieje albo jest starsza niż bieżące wydanie stabilne.
Automatyczny aktualizator rdzenia Gateway (gdy jest włączony w konfiguracji) używa ponownie tej samej ścieżki aktualizacji.
Automatyczny aktualizator rdzenia Gateway (gdy jest włączony w konfiguracji) uruchamia ścieżkę aktualizacji CLI
poza aktywnym handlerem żądań Gateway. Aktualizacje menedżera pakietów `update.run`
z płaszczyzny sterowania wymuszają niezależne od odroczenia ponowne uruchomienie aktualizacji bez okresu schłodzenia po podmianie pakietu,
ponieważ stary proces Gateway może nadal mieć w pamięci fragmenty wskazujące na
pliki usunięte przez nowy pakiet.
W przypadku instalacji przez menedżera pakietów `openclaw update` rozwiązuje docelową wersję
pakietu przed wywołaniem menedżera pakietów. Globalne instalacje npm używają instalacji etapowanej:
OpenClaw instaluje nowy pakiet w tymczasowym prefiksie npm, weryfikuje tam spis zapakowanego `dist`,
a następnie podmienia to czyste drzewo pakietu do rzeczywistego globalnego prefiksu. Jeśli weryfikacja się nie powiedzie,
doctor po aktualizacji, synchronizacja plugin i ponowne uruchomienie nie są wykonywane z podejrzanego drzewa.
Nawet gdy zainstalowana wersja już odpowiada celowi, polecenie odświeża globalną instalację pakietu,
a następnie wykonuje synchronizację plugin, odświeżenie uzupełnień poleceń rdzenia i ponowne uruchomienie.
Utrzymuje to zapakowane sidecary oraz rekordy plugin należące do kanału w zgodzie z
zainstalowaną kompilacją OpenClaw, pozostawiając pełne przebudowy uzupełnień poleceń plugin
Dla instalacji przez menedżera pakietów `openclaw update` rozwiązuje docelową
wersję pakietu przed wywołaniem menedżera pakietów. Globalne instalacje npm używają instalacji etapowej:
OpenClaw instaluje nowy pakiet w tymczasowym prefiksie npm, weryfikuje
tam spis spakowanego `dist`, a następnie podmienia to czyste drzewo pakietu do
rzeczywistego globalnego prefiksu. Jeśli weryfikacja się nie powiedzie, doctor po aktualizacji, synchronizacja pluginów i
praca restartu nie są uruchamiane z podejrzanego drzewa. Nawet gdy zainstalowana wersja
już odpowiada celowi, polecenie odświeża globalną instalację pakietu,
a następnie uruchamia synchronizację pluginów, odświeżenie uzupełnień poleceń rdzenia i pracę restartu. Dzięki temu
spakowane sidecary i rekordy pluginów należące do kanału pozostają zgodne z
zainstalowanym buildem OpenClaw, pozostawiając pełne przebudowy uzupełnień poleceń pluginów
jawnym uruchomieniom `openclaw completion --write-state`.
Gdy zainstalowana jest lokalna zarządzana usługa Gateway i włączone jest ponowne uruchomienie,
Gdy zainstalowana jest lokalna zarządzana usługa Gateway i włączony jest restart,
aktualizacje przez menedżera pakietów zatrzymują działającą usługę przed zastąpieniem drzewa pakietu,
następnie odświeżają metadane usługi ze zaktualizowanej instalacji, ponownie uruchamiają usługę
i weryfikują, że ponownie uruchomiony Gateway zgłasza oczekiwaną wersję. Przy
a następnie odświeżają metadane usługi ze zaktualizowanej instalacji, ponownie uruchamiają
usługę i sprawdzają, czy ponownie uruchomiony Gateway zgłasza oczekiwaną wersję. Z
`--no-restart` zastąpienie pakietu nadal jest wykonywane, ale zarządzana usługa nie jest
zatrzymywana ani ponownie uruchamiana, więc działający Gateway może zachować stary kod do czasu,
aż uruchomisz go ponownie ręcznie.
zatrzymywana ani uruchamiana ponownie, więc działający Gateway może zachować stary kod, dopóki
nie uruchomisz go ponownie ręcznie.
## Przepływ checkoutu git
### Wybór kanału
- `stable`: wykonuje checkout najnowszego tagu innego niż beta, następnie kompiluje i uruchamia doctor.
- `beta`: preferuje najnowszy tag `-beta`, ale wraca do najnowszego tagu stable, gdy beta jest niedostępna albo starsza.
- `dev`: wykonuje checkout `main`, a następnie fetch i rebase.
- `stable`: checkout najnowszego tagu niebędącego beta, potem build i doctor.
- `beta`: preferuje najnowszy tag `-beta`, ale wraca do najnowszego tagu stabilnego, gdy beta nie istnieje lub jest starsza.
- `dev`: checkout `main`, potem fetch i rebase.
### Kroki aktualizacji
@ -130,45 +135,45 @@ aż uruchomisz go ponownie ręcznie.
<Step title="Pobierz upstream">
Tylko dev.
</Step>
<Step title="Kompilacja wstępna (tylko dev)">
Uruchamia lint i kompilację TypeScript w tymczasowym drzewie roboczym. Jeśli tip się nie powiedzie, cofa się maksymalnie o 10 commitów, aby znaleźć najnowszą czystą kompilację.
<Step title="Build wstępny (tylko dev)">
Uruchamia lint i build TypeScript w tymczasowym drzewie roboczym. Jeśli tip się nie powiedzie, cofa się maksymalnie o 10 commitów, aby znaleźć najnowszy czysty build.
</Step>
<Step title="Rebase">
Wykonuje rebase na wybrany commit (tylko dev).
</Step>
<Step title="Zainstaluj zależności">
Używa menedżera pakietów repozytorium. W przypadku checkoutów pnpm aktualizator uruchamia `pnpm` na żądanie (najpierw przez `corepack`, a potem awaryjnie przez tymczasowe `npm install pnpm@10`) zamiast uruchamiać `npm run build` wewnątrz workspace pnpm.
Używa menedżera pakietów repozytorium. Dla checkoutów pnpm aktualizator bootstrapuje `pnpm` na żądanie (najpierw przez `corepack`, potem z tymczasowym fallbackiem `npm install pnpm@10`) zamiast uruchamiać `npm run build` wewnątrz workspace pnpm.
</Step>
<Step title="Zbuduj Control UI">
Buduje gateway i Control UI.
</Step>
<Step title="Uruchom doctor">
`openclaw doctor` działa jako końcowa kontrola bezpiecznej aktualizacji.
`openclaw doctor` działa jako końcowe sprawdzenie bezpiecznej aktualizacji.
</Step>
<Step title="Synchronizuj plugins">
Synchronizuje plugins z aktywnym kanałem. Dev używa dołączonych plugins; stable i beta używają npm. Aktualizuje plugins zainstalowane przez npm.
<Step title="Synchronizuj pluginy">
Synchronizuje pluginy do aktywnego kanału. Dev używa dołączonych pluginów; stable i beta używają npm. Aktualizuje pluginy zainstalowane przez npm.
</Step>
</Steps>
<Warning>
Jeśli dokładnie przypięta aktualizacja npm plugin rozwiąże się do artefaktu, którego integralność różni się od zapisanego rekordu instalacji, `openclaw update` przerywa aktualizację tego artefaktu plugin zamiast go instalować. Zainstaluj ponownie albo zaktualizuj plugin jawnie dopiero po zweryfikowaniu, że ufasz nowemu artefaktowi.
Jeśli dokładnie przypięta aktualizacja pluginu npm rozwiązuje się do artefaktu, którego integralność różni się od zapisanego rekordu instalacji, `openclaw update` przerywa tę aktualizację artefaktu pluginu zamiast ją instalować. Przeinstaluj lub zaktualizuj plugin jawnie dopiero po sprawdzeniu, że ufasz nowemu artefaktowi.
</Warning>
<Note>
Niepowodzenia synchronizacji plugin po aktualizacji powodują niepowodzenie wyniku aktualizacji i zatrzymują dalsze ponowne uruchamianie. Napraw błąd instalacji albo aktualizacji plugin, a następnie ponownie uruchom `openclaw update`.
Niepowodzenia synchronizacji pluginów po aktualizacji powodują niepowodzenie wyniku aktualizacji i zatrzymują dalszą pracę restartu. Napraw błąd instalacji lub aktualizacji pluginu, a następnie ponownie uruchom `openclaw update`.
Gdy zaktualizowany Gateway startuje, włączone zależności runtime dołączonych plugin są przygotowywane przed aktywacją plugin. Ponowne uruchomienia wywołane aktualizacją opróżniają aktywne przygotowywanie zależności runtime przed zamknięciem Gateway, więc ponowne uruchomienia menedżera usług nie przerywają trwającej instalacji npm.
Gdy zaktualizowany Gateway startuje, włączone zależności runtime dołączonych pluginów są przygotowywane etapowo przed aktywacją pluginów. Restarty `update.run` menedżera pakietów omijają normalne odroczenie bezczynności i okres schłodzenia restartu po podmianie drzewa pakietu, więc stary proces nie może nadal leniwie ładować usuniętych fragmentów. Restarty menedżera usług nadal opróżniają etapowe przygotowanie zależności runtime przed zamknięciem Gateway.
Jeśli bootstrap pnpm nadal się nie powiedzie, aktualizator zatrzymuje się wcześnie z błędem właściwym dla menedżera pakietów zamiast próbować `npm run build` wewnątrz checkoutu.
Jeśli bootstrap pnpm nadal się nie powiedzie, aktualizator zatrzyma się wcześniej z błędem specyficznym dla menedżera pakietów zamiast próbować `npm run build` wewnątrz checkoutu.
</Note>
## Skrót `--update`
`openclaw --update` jest przepisywane na `openclaw update` (przydatne dla powłok i skryptów uruchamiających).
`openclaw --update` przepisuje się na `openclaw update` (przydatne dla powłok i skryptów uruchamiających).
## Powiązane
- `openclaw doctor` (proponuje najpierw uruchomienie aktualizacji w checkoutach git)
- [Kanały deweloperskie](/pl/install/development-channels)
- `openclaw doctor` (oferuje najpierw uruchomienie aktualizacji w checkoutach git)
- [Kanały rozwojowe](/pl/install/development-channels)
- [Aktualizowanie](/pl/install/updating)
- [Dokumentacja CLI](/pl/cli)

44
docs/pl/cli/voicecall.md
View File

@ -1,22 +1,28 @@
---
read_when:
- Używasz Plugin połączeń głosowych i chcesz poznać punkty wejścia CLI
- Chcesz zobaczyć szybkie przykłady dla `voicecall setup|smoke|call|continue|dtmf|status|tail|expose`
summary: Dokumentacja CLI dla `openclaw voicecall` (powierzchnia poleceń Plugin połączeń głosowych)
title: Voicecall
- Używasz pluginu voice-call i potrzebujesz punktów wejścia CLI
- Potrzebujesz szybkich przykładów dla `voicecall setup|smoke|call|continue|dtmf|status|tail|expose`
summary: Dokumentacja referencyjna CLI dla `openclaw voicecall` (interfejs poleceń Plugin połączeń głosowych)
title: Połączenie głosowe
x-i18n:
generated_at: "2026-04-25T13:44:54Z"
model: gpt-5.4
generated_at: "2026-05-01T09:57:49Z"
model: gpt-5.5
provider: openai
source_hash: 7c8b83ef75f792920024a67b0dee1b07aff9f55486de1149266c6d94854ca0fe
source_hash: c040cf4cd984ad6d6dd302923494a7c8ee131390b803fe20a9894b077f08d5bb
source_path: cli/voicecall.md
workflow: 15
workflow: 16
---
# `openclaw voicecall`
`voicecall` to polecenie dostarczane przez Plugin. Pojawia się tylko wtedy, gdy Plugin połączeń głosowych jest zainstalowany i włączony.
Gdy Gateway działa, polecenia operacyjne (`call`, `start`,
`continue`, `speak`, `dtmf`, `end` i `status`) są wysyłane do środowiska
uruchomieniowego połączeń głosowych tego Gateway. Jeśli żaden Gateway nie jest
osiągalny, używane jest zapasowe autonomiczne środowisko uruchomieniowe
CLI.
Główna dokumentacja:
- Plugin połączeń głosowych: [Voice Call](/pl/plugins/voice-call)
@ -26,6 +32,7 @@ Główna dokumentacja:
```bash
openclaw voicecall setup
openclaw voicecall smoke
openclaw voicecall status --json
openclaw voicecall status --call-id <id>
openclaw voicecall call --to "+15555550123" --message "Hello" --mode notify
openclaw voicecall continue --call-id <id> --message "Any questions?"
@ -33,26 +40,29 @@ openclaw voicecall dtmf --call-id <id> --digits "ww123456#"
openclaw voicecall end --call-id <id>
```
`setup` domyślnie wypisuje czytelne dla człowieka kontrole gotowości. Użyj `--json` w
skryptach:
`setup` domyślnie wypisuje kontrole gotowości czytelne dla człowieka. Użyj `--json` dla
skryptów:
```bash
openclaw voicecall setup --json
```
W przypadku zewnętrznych providerów (`twilio`, `telnyx`, `plivo`) setup musi rozwiązać publiczny
URL Webhook z `publicUrl`, tunelu lub ekspozycji Tailscale. Fallback do lokalnego/prywatnego
serwowania jest odrzucany, ponieważ operatorzy nie mogą do niego dotrzeć.
`status` domyślnie wypisuje aktywne połączenia jako JSON. Przekaż `--call-id <id>`, aby sprawdzić
jedno połączenie.
W przypadku zewnętrznych dostawców (`twilio`, `telnyx`, `plivo`) konfiguracja musi rozpoznać publiczny
adres URL Webhook z `publicUrl`, tunelu lub ekspozycji Tailscale. Zapasowy
serwer local loopback/prywatny jest odrzucany, ponieważ operatorzy nie mogą go osiągnąć.
`smoke` uruchamia te same kontrole gotowości. Nie wykona prawdziwego połączenia telefonicznego,
chyba że obecne są jednocześnie `--to` i `--yes`:
chyba że obecne są zarówno `--to`, jak i `--yes`:
```bash
openclaw voicecall smoke --to "+15555550123" # test na sucho
openclaw voicecall smoke --to "+15555550123" --yes # rzeczywiste połączenie notify
openclaw voicecall smoke --to "+15555550123" # dry run
openclaw voicecall smoke --to "+15555550123" --yes # live notify call
```
## Udostępnianie Webhooków (Tailscale)
## Udostępnianie Webhook (Tailscale)
```bash
openclaw voicecall expose --mode serve

93
docs/pl/concepts/commitments.md
View File

@ -1,34 +1,29 @@
---
read_when:
- Chcesz, aby OpenClaw pamiętał naturalne kontynuacje
- Chcesz zrozumieć, czym wywnioskowane zgłoszenia kontrolne różnią się od przypomnień
- Chcesz przejrzeć lub odrzucić zobowiązania dotyczące dalszych działań
- Chcesz, aby OpenClaw pamiętał naturalne pytania uzupełniające
- Chcesz zrozumieć, czym wywnioskowane zameldowania różnią się od przypomnień
- Chcesz przejrzeć lub odrzucić zobowiązania do dalszych działań
sidebarTitle: Commitments
summary: Wywnioskowana pamięć działań następczych dla zgłoszeń kontrolnych, które nie są dokładnymi przypomnieniami
title: Wywnioskowane zobowiązania
x-i18n:
generated_at: "2026-04-30T09:46:48Z"
generated_at: "2026-05-01T09:58:12Z"
model: gpt-5.5
provider: openai
source_hash: 3f51af0ac2c9841258fbeeb8f2f98dba6f438b8e0c9433f601a0504d6ef27111
source_hash: 78841d87fe749aa5b04a967218396df1c1a7884c5767b09215c96aee34fa2014
source_path: concepts/commitments.md
workflow: 16
---
Zobowiązania to krótkotrwałe pamięci dotyczące działań następczych. Po ich włączeniu OpenClaw może
zauważyć, że rozmowa utworzyła przyszłą okazję do kontaktu kontrolnego, i zapamiętać,
aby wrócić do niej później.
Zobowiązania to krótkotrwałe pamięci działań następczych. Gdy są włączone, OpenClaw może zauważyć, że rozmowa stworzyła okazję do przyszłego sprawdzenia sytuacji, i zapamiętać, aby wrócić do niej później.
Przykłady:
- Wspominasz o jutrzejszej rozmowie kwalifikacyjnej. OpenClaw może odezwać się po niej.
- Mówisz, że jesteś wyczerpany. OpenClaw może później zapytać, czy udało Ci się przespać.
- Agent mówi, że wróci do sprawy po zmianie sytuacji. OpenClaw może śledzić
tę otwartą pętlę.
- Mówisz, że jesteś wyczerpany. OpenClaw może później zapytać, czy udało ci się przespać.
- Agent mówi, że wróci do tematu po zmianie sytuacji. OpenClaw może śledzić tę otwartą pętlę.
Zobowiązania nie są trwałymi faktami jak `MEMORY.md` i nie są dokładnymi
przypomnieniami. Znajdują się pomiędzy pamięcią a automatyzacją: OpenClaw zapamiętuje
zobowiązanie powiązane z rozmową, a następnie Heartbeat dostarcza je, gdy nadejdzie termin.
Zobowiązania nie są trwałymi faktami takimi jak `MEMORY.md` i nie są dokładnymi przypomnieniami. Znajdują się między pamięcią a automatyzacją: OpenClaw zapamiętuje zobowiązanie powiązane z rozmową, a następnie Heartbeat dostarcza je, gdy nadejdzie termin.
## Włącz zobowiązania
@ -39,7 +34,7 @@ openclaw config set commitments.enabled true
openclaw config set commitments.maxPerDay 3
```
Odpowiednik w `openclaw.json`:
Równoważny `openclaw.json`:
```json
{
@ -50,57 +45,43 @@ Odpowiednik w `openclaw.json`:
}
```
`commitments.maxPerDay` ogranicza liczbę wywnioskowanych działań następczych, które mogą zostać dostarczone
w ramach jednej sesji agenta w ruchomym okresie dobowym. Wartość domyślna to `3`.
`commitments.maxPerDay` ogranicza liczbę wywnioskowanych działań następczych, które można dostarczyć na sesję agenta w kroczącym dniu. Wartość domyślna to `3`.
## Jak to działa
Po odpowiedzi agenta OpenClaw może uruchomić ukryte, działające w tle przejście ekstrakcji w
oddzielnym kontekście. To przejście szuka tylko wywnioskowanych zobowiązań do działań następczych. Nie
zapisuje niczego w widocznej rozmowie i nie prosi głównego agenta
o rozumowanie dotyczące ekstrakcji.
Po odpowiedzi agenta OpenClaw może uruchomić ukryty przebieg wyodrębniania w tle w osobnym kontekście. Ten przebieg szuka wyłącznie wywnioskowanych zobowiązań do działań następczych. Nie zapisuje niczego w widocznej rozmowie i nie prosi głównego agenta o rozumowanie na temat wyodrębniania.
Gdy znajdzie kandydata o wysokiej pewności, OpenClaw zapisuje zobowiązanie z:
- identyfikatorem agenta
- kluczem sesji
- oryginalnym kanałem i celem dostarczenia
- pierwotnym kanałem i celem dostarczenia
- oknem terminu
- krótką sugerowaną wiadomością kontrolną
- wystarczającym kontekstem źródłowym, aby Heartbeat mógł zdecydować, czy ją wysłać
- metadanymi niebędącymi instrukcjami, których Heartbeat używa do decyzji, czy je wysłać
Dostarczenie odbywa się przez Heartbeat. Gdy zobowiązanie osiągnie termin, Heartbeat
dodaje je do tury Heartbeat dla tego samego agenta i zakresu kanału.
Model może wysłać jedną naturalną wiadomość kontrolną albo odpowiedzieć `HEARTBEAT_OK`, aby ją odrzucić.
Dostarczenie odbywa się przez Heartbeat. Gdy nadchodzi termin zobowiązania, Heartbeat dodaje zobowiązanie do tury Heartbeat dla tego samego agenta i zakresu kanału. Model może wysłać jedną naturalną wiadomość kontrolną albo odpowiedzieć `HEARTBEAT_OK`, aby ją odrzucić. Jeśli Heartbeat jest skonfigurowany z `target: "none"`, zobowiązania z nadejściem terminu pozostają wewnętrzne i nie wysyłają zewnętrznych wiadomości kontrolnych. Prompty dostarczania zobowiązań nie odtwarzają pierwotnego tekstu rozmowy, a tury Heartbeat dla zobowiązań z nadejściem terminu działają bez narzędzi OpenClaw.
OpenClaw nigdy nie dostarcza wywnioskowanego zobowiązania natychmiast po jego zapisaniu.
Termin jest ograniczany do co najmniej jednego interwału Heartbeat po utworzeniu zobowiązania,
dzięki czemu działanie następcze nie może wrócić echem w tej samej chwili, w której zostało
wywnioskowane.
OpenClaw nigdy nie dostarcza wywnioskowanego zobowiązania natychmiast po jego zapisaniu. Termin jest ograniczany do co najmniej jednego interwału Heartbeat po utworzeniu zobowiązania, więc działanie następcze nie może wrócić echem w tej samej chwili, w której zostało wywnioskowane.
## Zakres
Zobowiązania są ograniczone do dokładnego kontekstu agenta i kanału, w którym zostały
utworzone. Działanie następcze wywnioskowane podczas rozmowy z jednym agentem w Discord nie jest
dostarczane przez innego agenta, inny kanał ani niepowiązaną sesję.
Zobowiązania są ograniczone do dokładnego kontekstu agenta i kanału, w którym zostały utworzone. Działanie następcze wywnioskowane podczas rozmowy z jednym agentem w Discord nie zostanie dostarczone przez innego agenta, inny kanał ani niepowiązaną sesję.
Ten zakres jest częścią funkcji. Naturalne wiadomości kontrolne powinny sprawiać wrażenie kontynuacji tej samej
rozmowy, a nie globalnego systemu przypomnień.
Ten zakres jest częścią funkcji. Naturalne wiadomości kontrolne powinny sprawiać wrażenie kontynuacji tej samej rozmowy, a nie globalnego systemu przypomnień.
## Zobowiązania a przypomnienia
| Potrzeba | Użyj |
| Potrzeba | Użyj |
| ----------------------------------------------- | ---------------------------------------- |
| "Przypomnij mi o 15:00" | [Zaplanowane zadania](/pl/automation/cron-jobs) |
| "Odezwij się do mnie za 20 minut" | [Zaplanowane zadania](/pl/automation/cron-jobs) |
| "Uruchamiaj ten raport w każdy dzień roboczy" | [Zaplanowane zadania](/pl/automation/cron-jobs) |
| "Mam jutro rozmowę kwalifikacyjną" | Zobowiązania |
| "Nie spałem całą noc" | Zobowiązania |
| "Wróć do sprawy, jeśli nie odpowiem w tym otwartym wątku" | Zobowiązania |
| „Przypomnij mi o 15:00” | [Zaplanowane zadania](/pl/automation/cron-jobs) |
| „Daj mi znać za 20 minut” | [Zaplanowane zadania](/pl/automation/cron-jobs) |
| „Uruchamiaj ten raport w każdy dzień roboczy” | [Zaplanowane zadania](/pl/automation/cron-jobs) |
| „Mam jutro rozmowę kwalifikacyjną” | Zobowiązania |
| „Nie spałem całą noc” | Zobowiązania |
| „Wróć do tematu, jeśli nie odpowiem w tym otwartym wątku” | Zobowiązania |
Dokładne żądania użytkownika należą już do ścieżki harmonogramu. Zobowiązania są przeznaczone tylko
dla wywnioskowanych działań następczych: momentów, w których użytkownik nie poprosił o przypomnienie,
ale rozmowa wyraźnie utworzyła przydatną przyszłą okazję do kontaktu kontrolnego.
Dokładne prośby użytkownika już należą do ścieżki harmonogramu. Zobowiązania służą wyłącznie do wywnioskowanych działań następczych: sytuacji, w których użytkownik nie poprosił o przypomnienie, ale rozmowa wyraźnie stworzyła użyteczną okazję do przyszłego sprawdzenia sytuacji.
## Zarządzaj zobowiązaniami
@ -114,17 +95,13 @@ openclaw commitments --status snoozed
openclaw commitments dismiss cm_abc123
```
Zobacz [`openclaw commitments`](/pl/cli/commitments), aby uzyskać dokumentację polecenia.
Zobacz [`openclaw commitments`](/pl/cli/commitments), aby poznać opis polecenia.
## Prywatność i koszt
Ekstrakcja zobowiązań używa przejścia LLM, więc jej włączenie dodaje użycie modelu w tle
po kwalifikujących się turach. Przejście jest ukryte przed rozmową widoczną dla użytkownika,
ale może odczytać ostatnią wymianę potrzebną do zdecydowania, czy istnieje
działanie następcze.
Wyodrębnianie zobowiązań używa przebiegu LLM, więc jego włączenie dodaje użycie modelu w tle po kwalifikujących się turach. Ten przebieg jest ukryty przed rozmową widoczną dla użytkownika, ale może odczytać niedawną wymianę potrzebną do ustalenia, czy istnieje działanie następcze.
Zapisane zobowiązania są lokalnym stanem OpenClaw. Są pamięcią operacyjną, a nie
pamięcią długoterminową. Wyłącz funkcję za pomocą:
Zapisane zobowiązania są lokalnym stanem OpenClaw. Są pamięcią operacyjną, a nie pamięcią długoterminową. Wyłącz funkcję za pomocą:
```bash
openclaw config set commitments.enabled false
@ -135,18 +112,16 @@ openclaw config set commitments.enabled false
Jeśli oczekiwane działania następcze się nie pojawiają:
- Potwierdź, że `commitments.enabled` ma wartość `true`.
- Sprawdź `openclaw commitments --all` pod kątem rekordów oczekujących, odrzuconych, odłożonych lub wygasłych.
- Sprawdź `openclaw commitments --all`, aby znaleźć rekordy oczekujące, odrzucone, odłożone lub wygasłe.
- Upewnij się, że Heartbeat działa dla agenta.
- Sprawdź, czy `commitments.maxPerDay` nie został już osiągnięty dla tej
sesji agenta.
- Pamiętaj, że dokładne przypomnienia są pomijane przez ekstrakcję zobowiązań i powinny
zamiast tego pojawić się w [zaplanowanych zadaniach](/pl/automation/cron-jobs).
- Sprawdź, czy limit `commitments.maxPerDay` nie został już osiągnięty dla tej sesji agenta.
- Pamiętaj, że dokładne przypomnienia są pomijane przez wyodrębnianie zobowiązań i zamiast tego powinny pojawiać się w [zaplanowanych zadaniach](/pl/automation/cron-jobs).
## Powiązane
- [Omówienie pamięci](/pl/concepts/memory)
- [Przegląd pamięci](/pl/concepts/memory)
- [Active Memory](/pl/concepts/active-memory)
- [Heartbeat](/pl/gateway/heartbeat)
- [Zaplanowane zadania](/pl/automation/cron-jobs)
- [`openclaw commitments`](/pl/cli/commitments)
- [Dokumentacja konfiguracji](/pl/gateway/configuration-reference#commitments)
- [Informacje o konfiguracji](/pl/gateway/configuration-reference#commitments)

174
docs/pl/concepts/openclaw-sdk.md
View File

@ -1,66 +1,63 @@
---
read_when:
- Tworzysz zewnętrzną aplikację, skrypt, pulpit, zadanie CI lub rozszerzenie IDE, które komunikuje się z OpenClaw
- Wybierasz między SDK aplikacji a SDK Plugin
- Tworzysz zewnętrzną aplikację, skrypt, panel, zadanie CI lub rozszerzenie IDE, które komunikuje się z OpenClaw
- Wybierasz między App SDK a Plugin SDK
- Integrujesz się z uruchomieniami agentów Gateway, sesjami, zdarzeniami, zatwierdzeniami, modelami lub narzędziami
sidebarTitle: App SDK
summary: Publiczny SDK aplikacji OpenClaw dla zewnętrznych aplikacji, skryptów, pulpitów nawigacyjnych, zadań CI i rozszerzeń IDE
summary: Publiczny SDK aplikacji OpenClaw dla zewnętrznych aplikacji, skryptów, paneli, zadań CI i rozszerzeń IDE
title: SDK aplikacji OpenClaw
x-i18n:
generated_at: "2026-04-30T09:49:04Z"
generated_at: "2026-05-01T09:58:28Z"
model: gpt-5.5
provider: openai
source_hash: 9c46454d172a25d329a796461982dc4307d3720a28df777eda8605996505e38c
source_hash: a6b22e9f4f809a572cfd19fd22f633a706dd23b8bee2f3c244003a0861a41073
source_path: concepts/openclaw-sdk.md
workflow: 16
---
**OpenClaw App SDK** to publiczne API klienta dla aplikacji poza procesem
OpenClaw. Użyj `@openclaw/sdk`, gdy skrypt, dashboard, zadanie CI, rozszerzenie IDE
lub inna aplikacja zewnętrzna chce połączyć się z Gateway, uruchamiać przebiegi
agentów, strumieniować zdarzenia, czekać na wyniki, anulować pracę albo sprawdzać
zasoby Gateway.
**OpenClaw App SDK** to publiczny interfejs API klienta dla aplikacji poza procesem OpenClaw. Użyj `@openclaw/sdk`, gdy skrypt, pulpit, zadanie CI, rozszerzenie IDE lub inna aplikacja zewnętrzna chce połączyć się z Gateway, uruchamiać przebiegi agentów, strumieniować zdarzenia, czekać na wyniki, anulować pracę albo sprawdzać zasoby Gateway.
<Note>
App SDK różni się od [Plugin SDK](/pl/plugins/sdk-overview).
`@openclaw/sdk` komunikuje się z Gateway spoza OpenClaw.
`openclaw/plugin-sdk/*` jest przeznaczone wyłącznie dla pluginów działających wewnątrz OpenClaw i
rejestrujących dostawców, kanały, narzędzia, hooki lub zaufane środowiska uruchomieniowe.
`openclaw/plugin-sdk/*` jest przeznaczone wyłącznie dla pluginów uruchamianych wewnątrz OpenClaw, które rejestrują dostawców, kanały, narzędzia, hooki albo zaufane środowiska wykonawcze.
</Note>
## Co Jest Dostępne Dzisiaj
`@openclaw/sdk` zawiera:
| Powierzchnia | Status | Co robi |
| ------------------------- | ------- | ---------------------------------------------------------------------------- |
| `OpenClaw` | Gotowe | Główny punkt wejścia klienta. Obejmuje transport, połączenie, żądania i zdarzenia. |
| `GatewayClientTransport` | Gotowe | Transport WebSocket oparty na kliencie Gateway. |
| `oc.agents` | Gotowe | Wyświetla, tworzy, aktualizuje, usuwa i pobiera uchwyty agentów. |
| `Agent.run()` | Gotowe | Uruchamia przebieg `agent` w Gateway i zwraca `Run`. |
| `oc.runs` | Gotowe | Tworzy, pobiera, oczekuje, anuluje i strumieniuje przebiegi. |
| `Run.events()` | Gotowe | Strumieniuje znormalizowane zdarzenia pojedynczego przebiegu z odtworzeniem dla szybkich przebiegów. |
| `Run.wait()` | Gotowe | Wywołuje `agent.wait` i zwraca stabilny `RunResult`. |
| `Run.cancel()` | Gotowe | Wywołuje `sessions.abort` według identyfikatora przebiegu, z kluczem sesji, gdy jest dostępny. |
| `oc.sessions` | Gotowe | Tworzy, rozwiązuje, wysyła do, poprawia, kompaktuje i pobiera uchwyty sesji. |
| `Session.send()` | Gotowe | Wywołuje `sessions.send` i zwraca `Run`. |
| `oc.models` | Gotowe | Wywołuje `models.list` oraz bieżące RPC statusu `models.authStatus`. |
| `oc.tools` | Częściowe | Wyświetla katalog narzędzi i efektywne narzędzia; bezpośrednie wywoływanie narzędzi nie jest podłączone. |
| `oc.approvals` | Gotowe | Wyświetla i rozstrzyga zgody na exec przez RPC zgód Gateway. |
| `oc.rawEvents()` | Gotowe | Udostępnia surowe zdarzenia Gateway dla zaawansowanych konsumentów. |
| `normalizeGatewayEvent()` | Gotowe | Konwertuje surowe zdarzenia Gateway do stabilnego kształtu zdarzeń SDK. |
| Powierzchnia | Status | Co robi |
| ------------------------- | ------ | -------------------------------------------------------------------------- |
| `OpenClaw` | Gotowe | Główny punkt wejścia klienta. Odpowiada za transport, połączenie, żądania i zdarzenia. |
| `GatewayClientTransport` | Gotowe | Transport WebSocket oparty na kliencie Gateway. |
| `oc.agents` | Gotowe | Wyświetla, tworzy, aktualizuje, usuwa i pobiera uchwyty agentów. |
| `Agent.run()` | Gotowe | Uruchamia przebieg `agent` w Gateway i zwraca `Run`. |
| `oc.runs` | Gotowe | Tworzy, pobiera, oczekuje, anuluje i strumieniuje przebiegi. |
| `Run.events()` | Gotowe | Strumieniuje znormalizowane zdarzenia dla przebiegu z odtworzeniem dla szybkich przebiegów. |
| `Run.wait()` | Gotowe | Wywołuje `agent.wait` i zwraca stabilne `RunResult`. |
| `Run.cancel()` | Gotowe | Wywołuje `sessions.abort` według identyfikatora przebiegu, z kluczem sesji, gdy jest dostępny. |
| `oc.sessions` | Gotowe | Tworzy, rozwiązuje, wysyła do, aktualizuje, kompaktuje i pobiera uchwyty sesji. |
| `Session.send()` | Gotowe | Wywołuje `sessions.send` i zwraca `Run`. |
| `oc.models` | Gotowe | Wywołuje `models.list` i bieżące RPC statusu `models.authStatus`. |
| `oc.tools` | Gotowe | Wyświetla, zakresuje i wywołuje narzędzia Gateway przez potok zasad. |
| `oc.artifacts` | Gotowe | Wyświetla, pobiera i pobiera z Gateway artefakty transkryptu. |
| `oc.approvals` | Gotowe | Wyświetla i rozwiązuje zatwierdzenia exec przez RPC zatwierdzeń Gateway. |
| `oc.rawEvents()` | Gotowe | Udostępnia surowe zdarzenia Gateway dla zaawansowanych konsumentów. |
| `normalizeGatewayEvent()` | Gotowe | Konwertuje surowe zdarzenia Gateway do stabilnego kształtu zdarzeń SDK. |
SDK eksportuje także podstawowe typy używane przez te powierzchnie:
SDK eksportuje też podstawowe typy używane przez te powierzchnie:
`AgentRunParams`, `RunResult`, `RunStatus`, `OpenClawEvent`,
`OpenClawEventType`, `GatewayEvent`, `OpenClawTransport`,
`GatewayRequestOptions`, `SessionCreateParams`, `SessionSendParams`,
`RuntimeSelection`, `EnvironmentSelection`, `WorkspaceSelection`,
`ApprovalMode` oraz powiązane typy wyników.
`ArtifactSummary`, `ArtifactQuery`, `ArtifactsListResult`,
`ArtifactsGetResult`, `ArtifactsDownloadResult`, `RuntimeSelection`,
`EnvironmentSelection`, `WorkspaceSelection`, `ApprovalMode` oraz powiązane
typy wyników.
## Połącz Się Z Gateway
Utwórz klienta z jawnym adresem URL Gateway albo wstrzyknij własny transport dla
testów i osadzonych środowisk uruchomieniowych aplikacji.
Utwórz klienta z jawnym adresem URL Gateway albo wstrzyknij niestandardowy transport do testów i osadzonych środowisk wykonawczych aplikacji.
```typescript
import { OpenClaw } from "@openclaw/sdk";
@ -75,11 +72,9 @@ await oc.connect();
```
`new OpenClaw({ gateway: "ws://..." })` jest równoważne z `url`. Opcja
`gateway: "auto"` jest akceptowana przez konstruktor, ale automatyczne
wykrywanie Gateway nie jest jeszcze osobną funkcją SDK; przekaż `url`, gdy aplikacja nie wie już,
jak wykrywać Gateway.
`gateway: "auto"` jest akceptowana przez konstruktor, ale automatyczne wykrywanie Gateway nie jest jeszcze osobną funkcją SDK; przekaż `url`, gdy aplikacja nie wie już, jak wykryć Gateway.
W testach przekaż obiekt implementujący `OpenClawTransport`:
Do testów przekaż obiekt implementujący `OpenClawTransport`:
```typescript
const oc = new OpenClaw({
@ -94,8 +89,7 @@ const oc = new OpenClaw({
## Uruchom Agenta
Użyj `oc.agents.get(id)`, gdy aplikacja potrzebuje uchwytu agenta, a następnie wywołaj
`agent.run()`.
Użyj `oc.agents.get(id)`, gdy aplikacja potrzebuje uchwytu agenta, a następnie wywołaj `agent.run()`.
```typescript
const agent = await oc.agents.get("main");
@ -118,14 +112,9 @@ const result = await run.wait({ timeoutMs: 120_000 });
console.log(result.status);
```
Referencje modeli kwalifikowane dostawcą, takie jak `openai/gpt-5.5`, są dzielone na
nadpisania `provider` i `model` Gateway. `timeoutMs` pozostaje w SDK w milisekundach i
jest konwertowane na sekundy limitu czasu Gateway dla RPC `agent`.
Referencje modeli z kwalifikatorem dostawcy, takie jak `openai/gpt-5.5`, są dzielone na nadpisania `provider` i `model` Gateway. `timeoutMs` pozostaje w SDK w milisekundach i jest konwertowane na sekundy limitu czasu Gateway dla RPC `agent`.
`run.wait()` używa RPC Gateway `agent.wait`. Termin oczekiwania, który wygasa,
gdy przebieg nadal jest aktywny, zwraca `status: "accepted"` zamiast udawać,
że sam przebieg przekroczył limit czasu. Limity czasu środowiska uruchomieniowego, przerwane przebiegi i anulowane przebiegi są
normalizowane do `timed_out` lub `cancelled`.
`run.wait()` używa RPC `agent.wait` Gateway. Termin oczekiwania, który upływa, gdy przebieg nadal jest aktywny, zwraca `status: "accepted"` zamiast udawać, że sam przebieg przekroczył limit czasu. Limity czasu środowiska wykonawczego, przerwane przebiegi i anulowane przebiegi są normalizowane do `timed_out` albo `cancelled`.
## Twórz I Ponownie Używaj Sesji
@ -141,7 +130,7 @@ const run = await session.send("Prepare release notes from the current diff.");
await run.wait();
```
`Session.send()` wywołuje `sessions.send` i zwraca `Run`. Uchwyty sesji obsługują także:
`Session.send()` wywołuje `sessions.send` i zwraca `Run`. Uchwyty sesji obsługują też:
```typescript
await session.abort(run.id);
@ -176,17 +165,17 @@ Typowe typy zdarzeń obejmują:
| `run.started` | Początek cyklu życia `agent` |
| `run.completed` | Koniec cyklu życia `agent` |
| `run.failed` | Błąd cyklu życia `agent` |
| `run.cancelled` | Koniec przerwanego/anulowanego cyklu życia |
| `run.timed_out` | Koniec cyklu życia po przekroczeniu limitu czasu |
| `run.cancelled` | Koniec cyklu życia po przerwaniu/anulowaniu |
| `run.timed_out` | Koniec cyklu życia po limicie czasu |
| `assistant.delta` | Delta strumieniowania asystenta |
| `assistant.message` | Wiadomość asystenta |
| `thinking.delta` | Strumień myślenia lub planu |
| `thinking.delta` | Strumień myślenia albo planu |
| `tool.call.started` | Początek narzędzia/elementu/polecenia |
| `tool.call.delta` | Aktualizacja narzędzia/elementu/polecenia |
| `tool.call.completed` | Ukończenie narzędzia/elementu/polecenia |
| `tool.call.failed` | Niepowodzenie narzędzia/elementu/polecenia lub status zablokowania |
| `approval.requested` | Żądanie zgody na exec lub plugin |
| `approval.resolved` | Rozstrzygnięcie zgody na exec lub plugin |
| `tool.call.failed` | Niepowodzenie narzędzia/elementu/polecenia albo status zablokowany |
| `approval.requested` | Żądanie zatwierdzenia exec albo pluginu |
| `approval.resolved` | Rozwiązanie zatwierdzenia exec albo pluginu |
| `session.created` | Utworzenie `sessions.changed` |
| `session.updated` | Aktualizacja `sessions.changed` |
| `session.compacted` | Compaction `sessions.changed` |
@ -194,8 +183,7 @@ Typowe typy zdarzeń obejmują:
| `artifact.updated` | Zdarzenia strumienia poprawek |
| `raw` | Dowolne zdarzenie bez stabilnego mapowania SDK |
`Run.events()` filtruje zdarzenia do jednego identyfikatora przebiegu i odtwarza już widziane zdarzenia dla
szybkich przebiegów. Oznacza to, że udokumentowany przepływ jest bezpieczny:
`Run.events()` filtruje zdarzenia do jednego identyfikatora przebiegu i odtwarza już zaobserwowane zdarzenia dla szybkich przebiegów. Oznacza to, że udokumentowany przepływ jest bezpieczny:
```typescript
const run = await agent.run("Summarize the latest session.");
@ -207,26 +195,44 @@ for await (const event of run.events()) {
}
```
Do strumieni obejmujących całą aplikację użyj `oc.events()`. Do surowych ramek Gateway użyj
`oc.rawEvents()`.
Dla strumieni obejmujących całą aplikację użyj `oc.events()`. Dla surowych ramek Gateway użyj `oc.rawEvents()`.
## Modele, Narzędzia I Zgody
## Modele, Narzędzia, Artefakty I Zatwierdzenia
Pomocniki modeli mapują się na bieżące metody Gateway:
Pomocnicy modeli mapują się na bieżące metody Gateway:
```typescript
await oc.models.list();
await oc.models.status({ probe: false }); // calls models.authStatus
```
Pomocniki narzędzi udostępniają katalog Gateway i widok efektywnych narzędzi:
Pomocnicy narzędzi udostępniają katalog Gateway, efektywny widok narzędzi i bezpośrednie wywołanie narzędzia Gateway. `oc.tools.invoke()` zwraca typowaną kopertę zamiast rzucać wyjątek dla odmów wynikających z zasad albo zatwierdzeń.
```typescript
await oc.tools.list();
await oc.tools.effective({ sessionKey: "main" });
await oc.tools.invoke("tool-name", {
args: { input: "value" },
sessionKey: "main",
confirm: false,
idempotencyKey: "tool-call-1",
});
```
Pomocniki zgód używają RPC zgód exec:
Pomocnicy artefaktów udostępniają projekcję artefaktów Gateway dla kontekstu sesji, przebiegu albo zadania. Każde wywołanie wymaga jednego jawnego zakresu `sessionKey`, `runId` albo `taskId`:
```typescript
const { artifacts } = await oc.artifacts.list({ sessionKey: "main" });
const first = artifacts[0];
if (first) {
const { artifact } = await oc.artifacts.get(first.id, { sessionKey: "main" });
const download = await oc.artifacts.download(artifact.id, { sessionKey: "main" });
console.log(download.encoding, download.url);
}
```
Pomocnicy zatwierdzeń używają RPC zatwierdzeń exec:
```typescript
const approvals = await oc.approvals.list();
@ -235,60 +241,48 @@ await oc.approvals.respond("approval-id", { decision: "approve" });
## Jawnie Nieobsługiwane Dzisiaj
SDK zawiera nazwy dla modelu produktu, którego chcemy, ale nie udaje po cichu,
że istnieją RPC Gateway. Te wywołania obecnie rzucają jawne błędy braku obsługi:
SDK zawiera nazwy dla modelu produktu, którego chcemy, ale nie udaje po cichu, że RPC Gateway istnieją. Te wywołania obecnie rzucają jawne błędy braku obsługi:
```typescript
await oc.tasks.list();
await oc.tasks.get("task-id");
await oc.tasks.cancel("task-id");
await oc.tools.invoke("tool-name", {});
await oc.artifacts.list();
await oc.artifacts.get("artifact-id");
await oc.artifacts.download("artifact-id");
await oc.environments.list();
await oc.environments.create({});
await oc.environments.status("environment-id");
await oc.environments.delete("environment-id");
```
Pola pojedynczego przebiegu `workspace`, `runtime`, `environment` i `approvals` są typowane
jako przyszły kształt, ale bieżący Gateway nie obsługuje tych nadpisań w
RPC `agent`. Jeśli wywołujący je przekażą, SDK rzuca błąd przed przesłaniem przebiegu,
aby praca nie została przypadkowo wykonana z domyślnym zachowaniem workspace, runtime,
environment lub approval.
Pola `workspace`, `runtime`, `environment` i `approvals` dla przebiegu są typowane jako przyszły kształt, ale bieżący Gateway nie obsługuje tych nadpisań w RPC `agent`. Jeśli wywołujący je przekażą, SDK rzuci wyjątek przed przesłaniem przebiegu, aby praca nie została przypadkowo wykonana z domyślnym zachowaniem workspace, środowiska wykonawczego, environment albo zatwierdzeń.
## App SDK A Plugin SDK
## App SDK Kontra Plugin SDK
Używaj App SDK, gdy kod działa poza OpenClaw:
Użyj App SDK, gdy kod działa poza OpenClaw:
- skrypty Node uruchamiające lub obserwujące przebiegi agentów
- zadania CI wywołujące Gateway
- dashboardy i panele administracyjne
- skrypty Node, które uruchamiają albo obserwują przebiegi agentów
- zadania CI, które wywołują Gateway
- pulpity i panele administracyjne
- rozszerzenia IDE
- zewnętrzne mosty, które nie muszą stać się pluginami kanałów
- testy integracyjne z fałszywymi lub prawdziwymi transportami Gateway
- zewnętrzne mosty, które nie muszą stawać się pluginami kanałów
- testy integracyjne z fałszywymi albo prawdziwymi transportami Gateway
Używaj Plugin SDK, gdy kod działa wewnątrz OpenClaw:
Użyj Plugin SDK, gdy kod działa wewnątrz OpenClaw:
- pluginy dostawców
- pluginy kanałów
- hooki narzędzi lub cyklu życia
- pluginy uprzęży agenta
- zaufane pomocniki środowiska uruchomieniowego
- hooki narzędzi albo cyklu życia
- pluginy uprzęży agentów
- zaufani pomocnicy środowiska wykonawczego
Kod App SDK powinien importować z `@openclaw/sdk`. Kod pluginu powinien importować z
udokumentowanych podścieżek `openclaw/plugin-sdk/*`. Nie mieszaj tych dwóch kontraktów.
Kod App SDK powinien importować z `@openclaw/sdk`. Kod pluginów powinien importować z udokumentowanych podścieżek `openclaw/plugin-sdk/*`. Nie mieszaj tych dwóch kontraktów.
## Powiązana Dokumentacja
## Powiązane Dokumenty
- [Projekt API OpenClaw App SDK](/pl/reference/openclaw-sdk-api-design)
- [Dokumentacja RPC Gateway](/pl/reference/rpc)
- [Pętla agenta](/pl/concepts/agent-loop)
- [Środowiska uruchomieniowe agentów](/pl/concepts/agent-runtimes)
- [Środowiska wykonawcze agentów](/pl/concepts/agent-runtimes)
- [Sesje](/pl/concepts/session)
- [Zadania w tle](/pl/automation/tasks)
- [Agenci ACP](/pl/tools/acp-agents)

481
docs/pl/gateway/config-agents.md
View File

@ -1,24 +1,24 @@
---
read_when:
- Dostrajanie domyślnych ustawień agenta (modele, myślenie, przestrzeń robocza, Heartbeat, media, Skills)
- Konfigurowanie trasowania wieloagentowego i powiązań
- Dostrajanie domyślnych ustawień agenta (modele, myślenie, obszar roboczy, Heartbeat, media, Skills)
- Konfigurowanie routingu wieloagentowego i powiązań
- Dostosowywanie sesji, dostarczania wiadomości i zachowania trybu rozmowy
summary: Domyślne ustawienia agenta, routing wielu agentów, sesja, wiadomości i konfiguracja rozmowy
summary: Domyślne ustawienia agenta, routing wieloagentowy, sesja, wiadomości i konfiguracja rozmów
title: Konfiguracja — agenci
x-i18n:
generated_at: "2026-04-30T16:27:48Z"
generated_at: "2026-05-01T09:58:37Z"
model: gpt-5.5
provider: openai
source_hash: e6a38f42c35c6c6e46d6d00ad710c6c80d78703e0b7e3388f5631cf91eb17084
source_hash: 12a3c0c4a79d6753c7cebdb366e3a0272571841f3eaa0e08ded21fe54f485ca8
source_path: gateway/config-agents.md
workflow: 16
---
Klucze konfiguracji o zakresie agenta pod `agents.*`, `multiAgent.*`, `session.*`,
Klucze konfiguracji zakresu agenta w `agents.*`, `multiAgent.*`, `session.*`,
`messages.*` i `talk.*`. Kanały, narzędzia, środowisko uruchomieniowe Gateway oraz inne
klucze najwyższego poziomu opisuje [odwołanie konfiguracji](/pl/gateway/configuration-reference).
klucze najwyższego poziomu opisuje [Dokumentacja konfiguracji](/pl/gateway/configuration-reference).
## Domyślne ustawienia agentów
## Domyślne ustawienia agenta
### `agents.defaults.workspace`
@ -32,7 +32,7 @@ Domyślnie: `~/.openclaw/workspace`.
### `agents.defaults.repoRoot`
Opcjonalny katalog główny repozytorium wyświetlany w wierszu Runtime promptu systemowego. Jeśli nie ustawiono, OpenClaw wykrywa go automatycznie, przechodząc w górę od katalogu roboczego.
Opcjonalny katalog główny repozytorium pokazywany w wierszu Runtime promptu systemowego. Jeśli nie jest ustawiony, OpenClaw wykrywa go automatycznie, przechodząc w górę od obszaru roboczego.
```json5
{
@ -59,14 +59,14 @@ Opcjonalna domyślna lista dozwolonych Skills dla agentów, które nie ustawiaj
```
- Pomiń `agents.defaults.skills`, aby domyślnie nie ograniczać Skills.
- Pomiń `agents.list[].skills`, aby odziedziczyć ustawienia domyślne.
- Ustaw `agents.list[].skills: []`, aby wyłączyć Skills.
- Pomiń `agents.list[].skills`, aby odziedziczyć wartości domyślne.
- Ustaw `agents.list[].skills: []`, aby nie używać Skills.
- Niepusta lista `agents.list[].skills` jest ostatecznym zestawem dla tego agenta; nie
jest scalana z ustawieniami domyślnymi.
jest scalana z wartościami domyślnymi.
### `agents.defaults.skipBootstrap`
Wyłącza automatyczne tworzenie plików inicjalizacji katalogu roboczego (`AGENTS.md`, `SOUL.md`, `TOOLS.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md`, `BOOTSTRAP.md`).
Wyłącza automatyczne tworzenie plików inicjalizacji obszaru roboczego (`AGENTS.md`, `SOUL.md`, `TOOLS.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md`, `BOOTSTRAP.md`).
```json5
{
@ -74,12 +74,26 @@ Wyłącza automatyczne tworzenie plików inicjalizacji katalogu roboczego (`AGEN
}
```
### `agents.defaults.skipOptionalBootstrapFiles`
Pomija tworzenie wybranych opcjonalnych plików obszaru roboczego, nadal zapisując wymagane pliki inicjalizacji. Prawidłowe wartości: `SOUL.md`, `USER.md`, `HEARTBEAT.md` i `IDENTITY.md`.
```json5
{
agents: {
defaults: {
skipOptionalBootstrapFiles: ["SOUL.md", "USER.md"],
},
},
}
```
### `agents.defaults.contextInjection`
Określa, kiedy pliki inicjalizacji katalogu roboczego są wstrzykiwane do promptu systemowego. Domyślnie: `"always"`.
Kontroluje, kiedy pliki inicjalizacji obszaru roboczego są wstrzykiwane do promptu systemowego. Domyślnie: `"always"`.
- `"continuation-skip"`: bezpieczne tury kontynuacji (po ukończonej odpowiedzi asystenta) pomijają ponowne wstrzyknięcie inicjalizacji katalogu roboczego, zmniejszając rozmiar promptu. Uruchomienia Heartbeat i ponowienia po Compaction nadal odbudowują kontekst.
- `"never"`: wyłącz inicjalizację katalogu roboczego i wstrzykiwanie plików kontekstu w każdej turze. Używaj tego tylko dla agentów, które w pełni zarządzają cyklem życia własnego promptu (niestandardowe silniki kontekstu, natywne środowiska uruchomieniowe budujące własny kontekst lub wyspecjalizowane przepływy bez bootstrapu). Tury Heartbeat i odzyskiwania po Compaction również pomijają wstrzykiwanie.
- `"continuation-skip"`: bezpieczne tury kontynuacji (po ukończonej odpowiedzi asystenta) pomijają ponowne wstrzyknięcie inicjalizacji obszaru roboczego, zmniejszając rozmiar promptu. Uruchomienia Heartbeat i ponowienia po Compaction nadal odbudowują kontekst.
- `"never"`: wyłącza wstrzykiwanie inicjalizacji obszaru roboczego i plików kontekstowych w każdej turze. Używaj tego tylko dla agentów, które w pełni kontrolują cykl życia swojego promptu (niestandardowe silniki kontekstu, natywne środowiska uruchomieniowe budujące własny kontekst albo wyspecjalizowane przepływy bez inicjalizacji). Tury Heartbeat i odzyskiwania po Compaction również pomijają wstrzykiwanie.
```json5
{
@ -89,7 +103,7 @@ Określa, kiedy pliki inicjalizacji katalogu roboczego są wstrzykiwane do promp
### `agents.defaults.bootstrapMaxChars`
Maksymalna liczba znaków na plik inicjalizacji katalogu roboczego przed obcięciem. Domyślnie: `12000`.
Maksymalna liczba znaków na plik inicjalizacji obszaru roboczego przed obcięciem. Domyślnie: `12000`.
```json5
{
@ -99,7 +113,7 @@ Maksymalna liczba znaków na plik inicjalizacji katalogu roboczego przed obcięc
### `agents.defaults.bootstrapTotalMaxChars`
Maksymalna łączna liczba znaków wstrzykiwanych ze wszystkich plików inicjalizacji katalogu roboczego. Domyślnie: `60000`.
Maksymalna łączna liczba znaków wstrzykniętych ze wszystkich plików inicjalizacji obszaru roboczego. Domyślnie: `60000`.
```json5
{
@ -109,12 +123,12 @@ Maksymalna łączna liczba znaków wstrzykiwanych ze wszystkich plików inicjali
### `agents.defaults.bootstrapPromptTruncationWarning`
Steruje tekstem ostrzeżenia widocznym dla agenta, gdy kontekst bootstrapu zostanie obcięty.
Kontroluje widoczny dla agenta tekst ostrzeżenia, gdy kontekst inicjalizacji zostanie obcięty.
Domyślnie: `"once"`.
- `"off"`: nigdy nie wstrzykuj tekstu ostrzeżenia do promptu systemowego.
- `"once"`: wstrzyknij ostrzeżenie raz dla każdej unikalnej sygnatury obcięcia (zalecane).
- `"always"`: wstrzykuj ostrzeżenie przy każdym uruchomieniu, gdy występuje obcięcie.
- `"always"`: wstrzykuj ostrzeżenie przy każdym uruchomieniu, gdy istnieje obcięcie.
```json5
{
@ -122,27 +136,27 @@ Domyślnie: `"once"`.
}
```
### Mapa właścicielstwa budżetów kontekstu
### Mapa właścicielstwa budżetu kontekstu
OpenClaw ma wiele wysokowolumenowych budżetów promptu/kontekstu i są one
OpenClaw ma wiele promptów i budżetów kontekstu o dużej objętości, które są
celowo podzielone według podsystemów, zamiast przechodzić przez jedno ogólne
pokrętło.
- `agents.defaults.bootstrapMaxChars` /
`agents.defaults.bootstrapTotalMaxChars`:
zwykłe wstrzykiwanie inicjalizacji katalogu roboczego.
zwykłe wstrzykiwanie inicjalizacji obszaru roboczego.
- `agents.defaults.startupContext.*`:
jednorazowy wstęp uruchamiania modelu przy resecie/starcie, w tym ostatnie dzienne
pliki `memory/*.md`. Same komendy czatu `/new` i `/reset` są
jednorazowy wstęp uruchomienia modelu po resecie/starcie, w tym ostatnie codzienne
pliki `memory/*.md`. Same polecenia czatu `/new` i `/reset` są
potwierdzane bez wywoływania modelu.
- `skills.limits.*`:
zwięzła lista Skills wstrzykiwana do promptu systemowego.
zwarta lista Skills wstrzykiwana do promptu systemowego.
- `agents.defaults.contextLimits.*`:
ograniczone wycinki środowiska uruchomieniowego i wstrzykiwane bloki należące do runtime.
ograniczone wycinki środowiska uruchomieniowego i wstrzykiwane bloki należące do środowiska uruchomieniowego.
- `memory.qmd.limits.*`:
rozmiar indeksowanego fragmentu wyszukiwania pamięci i wstrzyknięcia.
rozmiar fragmentów zindeksowanego wyszukiwania pamięci i wstrzyknięć.
Użyj odpowiedniego nadpisania per agent tylko wtedy, gdy jeden agent potrzebuje innego
Używaj odpowiedniego nadpisania na agenta tylko wtedy, gdy jeden agent potrzebuje innego
budżetu:
- `agents.list[].skillsLimits.maxSkillsPromptChars`
@ -150,8 +164,8 @@ budżetu:
#### `agents.defaults.startupContext`
Steruje wstępem startowym pierwszej tury wstrzykiwanym przy uruchomieniach modelu po resecie/starcie.
Same komendy czatu `/new` i `/reset` potwierdzają reset bez wywoływania
Kontroluje wstęp startowy pierwszej tury wstrzykiwany przy uruchomieniach modelu po resecie/starcie.
Same polecenia czatu `/new` i `/reset` potwierdzają reset bez wywoływania
modelu, więc nie ładują tego wstępu.
```json5
@ -173,7 +187,7 @@ modelu, więc nie ładują tego wstępu.
#### `agents.defaults.contextLimits`
Wspólne wartości domyślne dla ograniczonych powierzchni kontekstu runtime.
Współdzielone wartości domyślne dla ograniczonych powierzchni kontekstu środowiska uruchomieniowego.
```json5
{
@ -192,7 +206,8 @@ Wspólne wartości domyślne dla ograniczonych powierzchni kontekstu runtime.
- `memoryGetMaxChars`: domyślny limit wycinka `memory_get` przed dodaniem
metadanych obcięcia i powiadomienia o kontynuacji.
- `memoryGetDefaultLines`: domyślne okno wierszy `memory_get`, gdy pominięto `lines`.
- `memoryGetDefaultLines`: domyślne okno linii `memory_get`, gdy `lines` jest
pominięte.
- `toolResultMaxChars`: limit wyników narzędzi na żywo używany dla utrwalonych wyników i
odzyskiwania po przepełnieniu.
- `postCompactionMaxChars`: limit wycinka AGENTS.md używany podczas wstrzykiwania
@ -200,7 +215,7 @@ Wspólne wartości domyślne dla ograniczonych powierzchni kontekstu runtime.
#### `agents.list[].contextLimits`
Nadpisanie per agent dla wspólnych pokręteł `contextLimits`. Pominięte pola dziedziczą
Nadpisanie na agenta dla współdzielonych pokręteł `contextLimits`. Pominięte pola dziedziczą
z `agents.defaults.contextLimits`.
```json5
@ -227,7 +242,7 @@ z `agents.defaults.contextLimits`.
#### `skills.limits.maxSkillsPromptChars`
Globalny limit dla zwięzłej listy Skills wstrzykiwanej do promptu systemowego. Nie
Globalny limit zwartej listy Skills wstrzykiwanej do promptu systemowego. Nie
wpływa to na odczytywanie plików `SKILL.md` na żądanie.
```json5
@ -242,7 +257,7 @@ wpływa to na odczytywanie plików `SKILL.md` na żądanie.
#### `agents.list[].skillsLimits.maxSkillsPromptChars`
Nadpisanie per agent dla budżetu promptu Skills.
Nadpisanie budżetu promptu Skills na agenta.
```json5
{
@ -264,7 +279,7 @@ Nadpisanie per agent dla budżetu promptu Skills.
Maksymalny rozmiar w pikselach najdłuższego boku obrazu w blokach obrazu transkrypcji/narzędzi przed wywołaniami dostawcy.
Domyślnie: `1200`.
Niższe wartości zwykle zmniejszają zużycie tokenów wizji i rozmiar ładunku żądania dla uruchomień z dużą liczbą zrzutów ekranu.
Niższe wartości zwykle zmniejszają użycie tokenów wizji i rozmiar ładunku żądania przy uruchomieniach z wieloma zrzutami ekranu.
Wyższe wartości zachowują więcej szczegółów wizualnych.
```json5
@ -275,7 +290,7 @@ Wyższe wartości zachowują więcej szczegółów wizualnych.
### `agents.defaults.userTimezone`
Strefa czasowa dla kontekstu promptu systemowego (nie znaczników czasu wiadomości). Wraca do strefy czasowej hosta.
Strefa czasowa dla kontekstu promptu systemowego (nie znaczników czasu wiadomości). W razie braku używana jest strefa czasowa hosta.
```json5
{
@ -347,55 +362,55 @@ Format czasu w prompcie systemowym. Domyślnie: `auto` (preferencja systemu oper
- Forma ciągu znaków ustawia tylko model podstawowy.
- Forma obiektu ustawia model podstawowy oraz uporządkowane modele przełączania awaryjnego.
- `imageModel`: akceptuje ciąg znaków (`"provider/model"`) albo obiekt (`{ primary, fallbacks }`).
- Używane przez ścieżkę narzędzia `image` jako konfiguracja modelu wizyjnego.
- Używane także jako trasowanie awaryjne, gdy wybrany/domyślny model nie może przyjmować danych wejściowych obrazu.
- Preferuj jawne odwołania `provider/model`. Same identyfikatory są akceptowane dla zgodności; jeśli sam identyfikator jednoznacznie pasuje do skonfigurowanego wpisu obsługującego obrazy w `models.providers.*.models`, OpenClaw kwalifikuje go do tego dostawcy. Niejednoznaczne skonfigurowane dopasowania wymagają jawnego prefiksu dostawcy.
- Używane przez ścieżkę narzędzia `image` jako jego konfiguracja modelu wizyjnego.
- Używane także jako trasowanie awaryjne, gdy wybrany/domyślny model nie może przyjąć danych wejściowych obrazu.
- Preferuj jawne odwołania `provider/model`. Same identyfikatory są akceptowane dla zgodności; jeśli sam identyfikator jednoznacznie pasuje do skonfigurowanej pozycji obsługującej obrazy w `models.providers.*.models`, OpenClaw kwalifikuje go do tego providera. Niejednoznaczne skonfigurowane dopasowania wymagają jawnego prefiksu providera.
- `imageGenerationModel`: akceptuje ciąg znaków (`"provider/model"`) albo obiekt (`{ primary, fallbacks }`).
- Używane przez współdzieloną funkcję generowania obrazów oraz każdą przyszłą powierzchnię narzędzia/Plugin, która generuje obrazy.
- Używane przez współdzieloną możliwość generowania obrazów oraz każdą przyszłą powierzchnię narzędzia/Plugin generującą obrazy.
- Typowe wartości: `google/gemini-3.1-flash-image-preview` dla natywnego generowania obrazów Gemini, `fal/fal-ai/flux/dev` dla fal, `openai/gpt-image-2` dla OpenAI Images albo `openai/gpt-image-1.5` dla wyjścia OpenAI PNG/WebP z przezroczystym tłem.
- Jeśli wybierasz dostawcę/model bezpośrednio, skonfiguruj także pasujące uwierzytelnianie dostawcy (na przykład `GEMINI_API_KEY` lub `GOOGLE_API_KEY` dla `google/*`, `OPENAI_API_KEY` lub OpenAI Codex OAuth dla `openai/gpt-image-2` / `openai/gpt-image-1.5`, `FAL_KEY` dla `fal/*`).
- Jeśli pominięto, `image_generate` nadal może wywnioskować domyślnego dostawcę opartego na uwierzytelnianiu. Najpierw próbuje bieżącego domyślnego dostawcy, a następnie pozostałych zarejestrowanych dostawców generowania obrazów w kolejności identyfikatora dostawcy.
- Jeśli wybierasz bezpośrednio providera/model, skonfiguruj też pasujące uwierzytelnianie providera (na przykład `GEMINI_API_KEY` lub `GOOGLE_API_KEY` dla `google/*`, `OPENAI_API_KEY` lub OpenAI Codex OAuth dla `openai/gpt-image-2` / `openai/gpt-image-1.5`, `FAL_KEY` dla `fal/*`).
- Jeśli pominięte, `image_generate` nadal może wywnioskować domyślnego providera opartego na uwierzytelnianiu. Najpierw próbuje bieżącego domyślnego providera, a potem pozostałych zarejestrowanych providerów generowania obrazów w kolejności identyfikatorów providerów.
- `musicGenerationModel`: akceptuje ciąg znaków (`"provider/model"`) albo obiekt (`{ primary, fallbacks }`).
- Używane przez współdzieloną funkcję generowania muzyki oraz wbudowane narzędzie `music_generate`.
- Używane przez współdzieloną możliwość generowania muzyki oraz wbudowane narzędzie `music_generate`.
- Typowe wartości: `google/lyria-3-clip-preview`, `google/lyria-3-pro-preview` albo `minimax/music-2.6`.
- Jeśli pominięto, `music_generate` nadal może wywnioskować domyślnego dostawcę opartego na uwierzytelnianiu. Najpierw próbuje bieżącego domyślnego dostawcy, a następnie pozostałych zarejestrowanych dostawców generowania muzyki w kolejności identyfikatora dostawcy.
- Jeśli wybierasz dostawcę/model bezpośrednio, skonfiguruj także pasujące uwierzytelnianie dostawcy/klucz API.
- Jeśli pominięte, `music_generate` nadal może wywnioskować domyślnego providera opartego na uwierzytelnianiu. Najpierw próbuje bieżącego domyślnego providera, a potem pozostałych zarejestrowanych providerów generowania muzyki w kolejności identyfikatorów providerów.
- Jeśli wybierasz bezpośrednio providera/model, skonfiguruj też pasujące uwierzytelnianie/klucz API providera.
- `videoGenerationModel`: akceptuje ciąg znaków (`"provider/model"`) albo obiekt (`{ primary, fallbacks }`).
- Używane przez współdzieloną funkcję generowania wideo oraz wbudowane narzędzie `video_generate`.
- Używane przez współdzieloną możliwość generowania wideo oraz wbudowane narzędzie `video_generate`.
- Typowe wartości: `qwen/wan2.6-t2v`, `qwen/wan2.6-i2v`, `qwen/wan2.6-r2v`, `qwen/wan2.6-r2v-flash` albo `qwen/wan2.7-r2v`.
- Jeśli pominięto, `video_generate` nadal może wywnioskować domyślnego dostawcę opartego na uwierzytelnianiu. Najpierw próbuje bieżącego domyślnego dostawcy, a następnie pozostałych zarejestrowanych dostawców generowania wideo w kolejności identyfikatora dostawcy.
- Jeśli wybierasz dostawcę/model bezpośrednio, skonfiguruj także pasujące uwierzytelnianie dostawcy/klucz API.
- Dołączony dostawca generowania wideo Qwen obsługuje maksymalnie 1 wyjściowe wideo, 1 obraz wejściowy, 4 wejściowe wideo, czas trwania 10 sekund oraz opcje na poziomie dostawcy `size`, `aspectRatio`, `resolution`, `audio` i `watermark`.
- Jeśli pominięte, `video_generate` nadal może wywnioskować domyślnego providera opartego na uwierzytelnianiu. Najpierw próbuje bieżącego domyślnego providera, a potem pozostałych zarejestrowanych providerów generowania wideo w kolejności identyfikatorów providerów.
- Jeśli wybierasz bezpośrednio providera/model, skonfiguruj też pasujące uwierzytelnianie/klucz API providera.
- Dołączony provider generowania wideo Qwen obsługuje maksymalnie 1 wyjściowy film, 1 obraz wejściowy, 4 filmy wejściowe, czas trwania 10 sekund oraz opcje na poziomie providera `size`, `aspectRatio`, `resolution`, `audio` i `watermark`.
- `pdfModel`: akceptuje ciąg znaków (`"provider/model"`) albo obiekt (`{ primary, fallbacks }`).
- Używane przez narzędzie `pdf` do trasowania modelu.
- Jeśli pominięto, narzędzie PDF wraca do `imageModel`, a następnie do rozwiązanego modelu sesji/domyślnego.
- Jeśli pominięte, narzędzie PDF przechodzi awaryjnie na `imageModel`, a następnie na rozwiązany model sesji/domyślny.
- `pdfMaxBytesMb`: domyślny limit rozmiaru PDF dla narzędzia `pdf`, gdy `maxBytesMb` nie zostanie przekazane podczas wywołania.
- `pdfMaxPages`: domyślna maksymalna liczba stron rozważanych przez tryb awaryjny ekstrakcji w narzędziu `pdf`.
- `pdfMaxPages`: domyślna maksymalna liczba stron uwzględniana przez tryb awaryjny ekstrakcji w narzędziu `pdf`.
- `verboseDefault`: domyślny poziom szczegółowości dla agentów. Wartości: `"off"`, `"on"`, `"full"`. Domyślnie: `"off"`.
- `reasoningDefault`: domyślna widoczność rozumowania dla agentów. Wartości: `"off"`, `"on"`, `"stream"`. `agents.list[].reasoningDefault` na poziomie agenta zastępuje tę wartość domyślną. Skonfigurowane domyślne ustawienia rozumowania są stosowane tylko dla właścicieli, autoryzowanych nadawców lub kontekstów Gateway operatora-administratora, gdy nie ustawiono nadpisania rozumowania dla wiadomości lub sesji.
- `elevatedDefault`: domyślny poziom podwyższonego wyjścia dla agentów. Wartości: `"off"`, `"on"`, `"ask"`, `"full"`. Domyślnie: `"on"`.
- `model.primary`: format `provider/model` (np. `openai/gpt-5.5` dla dostępu przez klucz API albo `openai-codex/gpt-5.5` dla Codex OAuth). Jeśli pominiesz dostawcę, OpenClaw najpierw próbuje aliasu, potem unikalnego dopasowania skonfigurowanego dostawcy dla dokładnego identyfikatora modelu, a dopiero potem wraca do skonfigurowanego domyślnego dostawcy (przestarzałe zachowanie zgodności, więc preferuj jawne `provider/model`). Jeśli ten dostawca nie udostępnia już skonfigurowanego modelu domyślnego, OpenClaw wraca do pierwszego skonfigurowanego dostawcy/modelu zamiast ujawniać nieaktualną wartość domyślną usuniętego dostawcy.
- `models`: skonfigurowany katalog modeli i lista dozwolonych dla `/model`. Każdy wpis może zawierać `alias` (skrót) i `params` (specyficzne dla dostawcy, na przykład `temperature`, `maxTokens`, `cacheRetention`, `context1m`, `responsesServerCompaction`, `responsesCompactThreshold`, `chat_template_kwargs`, `extra_body`/`extraBody`).
- Bezpieczne edycje: użyj `openclaw config set agents.defaults.models '<json>' --strict-json --merge`, aby dodać wpisy. `config set` odrzuca zamiany, które usunęłyby istniejące wpisy listy dozwolonych, chyba że przekażesz `--replace`.
- Przepływy konfiguracji/wdrażania ograniczone do dostawcy scalają wybrane modele dostawcy z tą mapą i zachowują niezwiązanych dostawców już skonfigurowanych.
- Dla bezpośrednich modeli OpenAI Responses kompakcja po stronie serwera jest włączana automatycznie. Użyj `params.responsesServerCompaction: false`, aby przestać wstrzykiwać `context_management`, albo `params.responsesCompactThreshold`, aby nadpisać próg. Zobacz [kompakcję OpenAI po stronie serwera](/pl/providers/openai#server-side-compaction-responses-api).
- `params`: globalne domyślne parametry dostawcy stosowane do wszystkich modeli. Ustawiane w `agents.defaults.params` (np. `{ cacheRetention: "long" }`).
- Kolejność pierwszeństwa scalania `params` (konfiguracja): `agents.defaults.params` (globalna baza) jest nadpisywane przez `agents.defaults.models["provider/model"].params` (dla modelu), a następnie `agents.list[].params` (pasujący identyfikator agenta) nadpisuje według klucza. Szczegóły znajdziesz w [Prompt Caching](/pl/reference/prompt-caching).
- `params.extra_body`/`params.extraBody`: zaawansowany przekazywany dalej JSON scalany z treściami żądań `api: "openai-completions"` dla proxy zgodnych z OpenAI. Jeśli koliduje z wygenerowanymi kluczami żądania, dodatkowa treść wygrywa; nienatywne trasy uzupełnień nadal potem usuwają właściwe tylko dla OpenAI `store`.
- `params.chat_template_kwargs`: argumenty szablonu czatu zgodne z vLLM/OpenAI scalane z najwyższym poziomem treści żądań `api: "openai-completions"`. Dla `vllm/nemotron-3-*` z wyłączonym myśleniem dołączony Plugin vLLM automatycznie wysyła `enable_thinking: false` i `force_nonempty_content: true`; jawne `chat_template_kwargs` nadpisują wygenerowane wartości domyślne, a `extra_body.chat_template_kwargs` nadal ma ostateczne pierwszeństwo. Dla kontrolek myślenia Qwen w vLLM ustaw `params.qwenThinkingFormat` na `"chat-template"` albo `"top-level"` w tym wpisie modelu.
- `compat.supportedReasoningEfforts`: lista wysiłków rozumowania zgodnych z OpenAI dla modelu. Uwzględnij `"xhigh"` dla niestandardowych punktów końcowych, które faktycznie je akceptują; OpenClaw wtedy udostępnia `/think xhigh` w menu poleceń, wierszach sesji Gateway, walidacji poprawek sesji, walidacji CLI agenta i walidacji `llm-task` dla tego skonfigurowanego dostawcy/modelu. Użyj `compat.reasoningEffortMap`, gdy backend oczekuje wartości specyficznej dla dostawcy dla kanonicznego poziomu.
- `params.preserveThinking`: opcjonalne włączenie zachowanego myślenia tylko dla Z.AI. Gdy jest włączone i myślenie jest włączone, OpenClaw wysyła `thinking.clear_thinking: false` i odtwarza wcześniejsze `reasoning_content`; zobacz [myślenie Z.AI i zachowane myślenie](/pl/providers/zai#thinking-and-preserved-thinking).
- `agentRuntime`: domyślna niskopoziomowa polityka środowiska uruchomieniowego agenta. Pominięty identyfikator domyślnie oznacza OpenClaw Pi. Użyj `id: "pi"`, aby wymusić wbudowany uprząż PI, `id: "auto"`, aby pozwolić zarejestrowanym uprzężom Plugin przejmować obsługiwane modele, zarejestrowanego identyfikatora uprzęży, takiego jak `id: "codex"`, albo obsługiwanego aliasu backendu CLI, takiego jak `id: "claude-cli"`. Ustaw `fallback: "none"`, aby wyłączyć automatyczny powrót do PI. Jawne środowiska uruchomieniowe Plugin, takie jak `codex`, domyślnie kończą się zamkniętym błędem, chyba że ustawisz `fallback: "pi"` w tym samym zakresie nadpisania. Zachowuj odwołania do modeli w kanonicznej postaci `provider/model`; wybieraj Codex, Claude CLI, Gemini CLI i inne backendy wykonawcze przez konfigurację środowiska uruchomieniowego zamiast starszych prefiksów dostawcy środowiska uruchomieniowego. Zobacz [środowiska uruchomieniowe agentów](/pl/concepts/agent-runtimes), aby sprawdzić, czym różni się to od wyboru dostawcy/modelu.
- Moduły zapisujące konfigurację, które mutują te pola (na przykład `/models set`, `/models set-image` oraz polecenia dodawania/usuwania modeli awaryjnych), zapisują kanoniczną formę obiektu i zachowują istniejące listy awaryjne, gdy to możliwe.
- `reasoningDefault`: domyślna widoczność rozumowania dla agentów. Wartości: `"off"`, `"on"`, `"stream"`. `agents.list[].reasoningDefault` dla danego agenta zastępuje tę wartość domyślną. Skonfigurowane domyślne wartości rozumowania są stosowane tylko dla właścicieli, autoryzowanych nadawców albo kontekstów Gateway administratora-operatora, gdy nie ustawiono zastąpienia rozumowania na poziomie wiadomości ani sesji.
- `elevatedDefault`: domyślny poziom wyniesionego wyjścia dla agentów. Wartości: `"off"`, `"on"`, `"ask"`, `"full"`. Domyślnie: `"on"`.
- `model.primary`: format `provider/model` (np. `openai/gpt-5.5` dla dostępu przez klucz API albo `openai-codex/gpt-5.5` dla Codex OAuth). Jeśli pominiesz providera, OpenClaw najpierw próbuje aliasu, potem unikalnego dopasowania skonfigurowanego providera dla tego dokładnego identyfikatora modelu, a dopiero potem przechodzi awaryjnie na skonfigurowanego domyślnego providera (przestarzałe zachowanie zgodności, więc preferuj jawne `provider/model`). Jeśli ten provider nie udostępnia już skonfigurowanego modelu domyślnego, OpenClaw przechodzi awaryjnie na pierwszy skonfigurowany provider/model zamiast zgłaszać nieaktualną wartość domyślną usuniętego providera.
- `models`: skonfigurowany katalog modeli i lista dozwolonych dla `/model`. Każda pozycja może zawierać `alias` (skrót) i `params` (specyficzne dla providera, na przykład `temperature`, `maxTokens`, `cacheRetention`, `context1m`, `responsesServerCompaction`, `responsesCompactThreshold`, `chat_template_kwargs`, `extra_body`/`extraBody`).
- Bezpieczne edycje: użyj `openclaw config set agents.defaults.models '<json>' --strict-json --merge`, aby dodać pozycje. `config set` odrzuca zamiany, które usunęłyby istniejące pozycje listy dozwolonych, chyba że przekażesz `--replace`.
- Przepływy konfiguracji/wdrażania ograniczone do providera scalają wybrane modele providera z tą mapą i zachowują niepowiązanych providerów, którzy są już skonfigurowani.
- Dla bezpośrednich modeli OpenAI Responses Compaction po stronie serwera jest włączana automatycznie. Użyj `params.responsesServerCompaction: false`, aby zatrzymać wstrzykiwanie `context_management`, albo `params.responsesCompactThreshold`, aby zastąpić próg. Zobacz [Compaction po stronie serwera OpenAI](/pl/providers/openai#server-side-compaction-responses-api).
- `params`: globalne domyślne parametry providera stosowane do wszystkich modeli. Ustawiane w `agents.defaults.params` (np. `{ cacheRetention: "long" }`).
- Kolejność pierwszeństwa scalania `params` (konfiguracja): `agents.defaults.params` (globalna baza) jest zastępowane przez `agents.defaults.models["provider/model"].params` (dla modelu), a następnie `agents.list[].params` (pasujący identyfikator agenta) zastępuje według klucza. Szczegóły znajdziesz w [Buforowanie promptów](/pl/reference/prompt-caching).
- `params.extra_body`/`params.extraBody`: zaawansowany przekazywany dalej JSON scalany z treściami żądań `api: "openai-completions"` dla proxy zgodnych z OpenAI. Jeśli koliduje z wygenerowanymi kluczami żądania, dodatkowa treść wygrywa; nienatywne trasy completions nadal potem usuwają właściwe tylko dla OpenAI `store`.
- `params.chat_template_kwargs`: argumenty szablonu czatu zgodne z vLLM/OpenAI, scalane z najwyższym poziomem treści żądań `api: "openai-completions"`. Dla `vllm/nemotron-3-*` z wyłączonym myśleniem dołączony Plugin vLLM automatycznie wysyła `enable_thinking: false` i `force_nonempty_content: true`; jawne `chat_template_kwargs` zastępują wygenerowane wartości domyślne, a `extra_body.chat_template_kwargs` nadal ma ostateczny priorytet. Dla kontrolek myślenia vLLM Qwen ustaw `params.qwenThinkingFormat` na `"chat-template"` albo `"top-level"` w tej pozycji modelu.
- `compat.supportedReasoningEfforts`: lista wysiłków rozumowania zgodnych z OpenAI dla danego modelu. Uwzględnij `"xhigh"` dla niestandardowych endpointów, które faktycznie to akceptują; OpenClaw udostępni wtedy `/think xhigh` w menu poleceń, wierszach sesji Gateway, walidacji poprawek sesji, walidacji CLI agenta i walidacji `llm-task` dla tego skonfigurowanego providera/modelu. Użyj `compat.reasoningEffortMap`, gdy backend wymaga wartości specyficznej dla providera dla kanonicznego poziomu.
- `params.preserveThinking`: opcjonalne włączenie zachowanego myślenia tylko dla Z.AI. Gdy jest włączone i myślenie jest aktywne, OpenClaw wysyła `thinking.clear_thinking: false` i odtwarza wcześniejsze `reasoning_content`; zobacz [Myślenie Z.AI i zachowane myślenie](/pl/providers/zai#thinking-and-preserved-thinking).
- `agentRuntime`: domyślna niskopoziomowa polityka środowiska uruchomieniowego agenta. Pominięty identyfikator domyślnie oznacza OpenClaw Pi. Użyj `id: "pi"`, aby wymusić wbudowany harness PI, `id: "auto"`, aby pozwolić zarejestrowanym harnessom Plugin przejmować obsługiwane modele, zarejestrowanego identyfikatora harnessu, takiego jak `id: "codex"`, albo obsługiwanego aliasu backendu CLI, takiego jak `id: "claude-cli"`. Ustaw `fallback: "none"`, aby wyłączyć automatyczne przejście awaryjne na PI. Jawne środowiska uruchomieniowe Plugin, takie jak `codex`, domyślnie kończą się zamkniętym błędem, chyba że ustawisz `fallback: "pi"` w tym samym zakresie zastąpienia. Zachowuj odwołania do modeli w kanonicznej postaci `provider/model`; wybieraj Codex, Claude CLI, Gemini CLI i inne backendy wykonawcze przez konfigurację środowiska uruchomieniowego zamiast starszych prefiksów providera środowiska uruchomieniowego. Zobacz [Środowiska uruchomieniowe agentów](/pl/concepts/agent-runtimes), aby dowiedzieć się, czym różni się to od wyboru providera/modelu.
- Programy zapisujące konfigurację, które mutują te pola (na przykład `/models set`, `/models set-image` oraz polecenia dodawania/usuwania modeli awaryjnych), zapisują kanoniczną formę obiektową i zachowują istniejące listy modeli awaryjnych, gdy to możliwe.
- `maxConcurrent`: maksymalna liczba równoległych uruchomień agentów między sesjami (każda sesja nadal jest serializowana). Domyślnie: 4.
### `agents.defaults.agentRuntime`
`agentRuntime` kontroluje, który niskopoziomowy wykonawca uruchamia tury agenta. Większość
wdrożeń powinna zachować domyślne środowisko uruchomieniowe OpenClaw Pi. Użyj go, gdy zaufany
Plugin dostarcza natywną uprząż, taką jak dołączona uprząż serwera aplikacji Codex,
Plugin zapewnia natywny harness, taki jak dołączony harness serwera aplikacji Codex,
albo gdy chcesz użyć obsługiwanego backendu CLI, takiego jak Claude CLI. Model mentalny
opisano w [środowiskach uruchomieniowych agentów](/pl/concepts/agent-runtimes).
opisano w [Środowiska uruchomieniowe agentów](/pl/concepts/agent-runtimes).
```json5
{
@ -411,14 +426,14 @@ opisano w [środowiskach uruchomieniowych agentów](/pl/concepts/agent-runtimes)
}
```
- `id`: `"auto"`, `"pi"`, zarejestrowany identyfikator uprzęży Plugin albo obsługiwany alias backendu CLI. Dołączony Plugin Codex rejestruje `codex`; dołączony Plugin Anthropic udostępnia backend CLI `claude-cli`.
- `fallback`: `"pi"` albo `"none"`. W `id: "auto"` pominięty fallback domyślnie przyjmuje `"pi"`, aby stare konfiguracje mogły nadal używać PI, gdy żadna uprząż Plugin nie przejmie uruchomienia. W trybie jawnego środowiska uruchomieniowego Plugin, takim jak `id: "codex"`, pominięty fallback domyślnie przyjmuje `"none"`, aby brakująca uprząż zakończyła się błędem zamiast po cichu używać PI. Nadpisania środowiska uruchomieniowego nie dziedziczą fallbacku z szerszego zakresu; ustaw `fallback: "pi"` obok jawnego środowiska uruchomieniowego, gdy celowo chcesz tego fallbacku zgodności. Awarie wybranej uprzęży Plugin zawsze są ujawniane bezpośrednio.
- Nadpisania środowiskowe: `OPENCLAW_AGENT_RUNTIME=<id|auto|pi>` nadpisuje `id`; `OPENCLAW_AGENT_HARNESS_FALLBACK=pi|none` nadpisuje fallback dla tego procesu.
- `id`: `"auto"`, `"pi"`, zarejestrowany identyfikator harnessu Plugin albo obsługiwany alias backendu CLI. Dołączony Plugin Codex rejestruje `codex`; dołączony Plugin Anthropic udostępnia backend CLI `claude-cli`.
- `fallback`: `"pi"` albo `"none"`. W `id: "auto"` pominięta wartość awaryjna domyślnie wynosi `"pi"`, aby stare konfiguracje mogły nadal używać PI, gdy żaden harness Plugin nie przejmie uruchomienia. W trybie jawnego środowiska uruchomieniowego Plugin, takim jak `id: "codex"`, pominięta wartość awaryjna domyślnie wynosi `"none"`, aby brakujący harness powodował błąd zamiast po cichu używać PI. Zastąpienia środowiska uruchomieniowego nie dziedziczą wartości awaryjnej z szerszego zakresu; ustaw `fallback: "pi"` obok jawnego środowiska uruchomieniowego, gdy celowo chcesz tego awaryjnego zachowania zgodności. Błędy wybranego harnessu Plugin są zawsze zgłaszane bezpośrednio.
- Zastąpienia środowiskowe: `OPENCLAW_AGENT_RUNTIME=<id|auto|pi>` zastępuje `id`; `OPENCLAW_AGENT_HARNESS_FALLBACK=pi|none` zastępuje wartość awaryjną dla tego procesu.
- Dla wdrożeń tylko z Codex ustaw `model: "openai/gpt-5.5"` i `agentRuntime.id: "codex"`. Możesz też jawnie ustawić `agentRuntime.fallback: "none"` dla czytelności; jest to wartość domyślna dla jawnych środowisk uruchomieniowych Plugin.
- Dla wdrożeń Claude CLI preferuj `model: "anthropic/claude-opus-4-7"` oraz `agentRuntime.id: "claude-cli"`. Starsze odwołania do modeli `claude-cli/claude-opus-4-7` nadal działają dla zgodności, ale nowa konfiguracja powinna zachowywać kanoniczny wybór dostawcy/modelu i umieszczać backend wykonawczy w `agentRuntime.id`.
- Dla wdrożeń Claude CLI preferuj `model: "anthropic/claude-opus-4-7"` plus `agentRuntime.id: "claude-cli"`. Starsze odwołania do modeli `claude-cli/claude-opus-4-7` nadal działają dla zgodności, ale nowa konfiguracja powinna zachować kanoniczny wybór provider/model i umieszczać backend wykonawczy w `agentRuntime.id`.
- Starsze klucze polityki środowiska uruchomieniowego są przepisywane do `agentRuntime` przez `openclaw doctor --fix`.
- Wybór uprzęży jest przypinany dla identyfikatora sesji po pierwszym osadzonym uruchomieniu. Zmiany konfiguracji/środowiska wpływają na nowe lub zresetowane sesje, nie na istniejącą transkrypcję. Starsze sesje z historią transkrypcji, ale bez zapisanego przypięcia, są traktowane jako przypięte do PI. `/status` raportuje efektywne środowisko uruchomieniowe, na przykład `Runtime: OpenClaw Pi Default` albo `Runtime: OpenAI Codex`.
- To kontroluje wyłącznie wykonywanie tekstowych tur agenta. Generowanie multimediów, wizja, PDF, muzyka, wideo i TTS nadal używają swoich ustawień dostawcy/modelu.
- Wybór harnessu jest przypinany dla identyfikatora sesji po pierwszym osadzonym uruchomieniu. Zmiany konfiguracji/środowiska wpływają na nowe lub zresetowane sesje, nie na istniejący transkrypt. Starsze sesje z historią transkryptu, ale bez zapisanego przypięcia, są traktowane jako przypięte do PI. `/status` raportuje efektywne środowisko uruchomieniowe, na przykład `Runtime: OpenClaw Pi Default` albo `Runtime: OpenAI Codex`.
- Kontroluje to tylko wykonywanie tekstowych tur agenta. Generowanie mediów, wizja, PDF, muzyka, wideo i TTS nadal używają swoich ustawień provider/model.
**Wbudowane skróty aliasów** (mają zastosowanie tylko wtedy, gdy model znajduje się w `agents.defaults.models`):
@ -426,7 +441,7 @@ opisano w [środowiskach uruchomieniowych agentów](/pl/concepts/agent-runtimes)
| ------------------- | ------------------------------------------ |
| `opus` | `anthropic/claude-opus-4-6` |
| `sonnet` | `anthropic/claude-sonnet-4-6` |
| `gpt` | `openai/gpt-5.5` or `openai-codex/gpt-5.5` |
| `gpt` | `openai/gpt-5.5` lub `openai-codex/gpt-5.5` |
| `gpt-mini` | `openai/gpt-5.4-mini` |
| `gpt-nano` | `openai/gpt-5.4-nano` |
| `gemini` | `google/gemini-3.1-pro-preview` |
@ -441,7 +456,7 @@ Modele Anthropic Claude 4.6 domyślnie używają myślenia `adaptive`, gdy nie u
### `agents.defaults.cliBackends`
Opcjonalne backendy CLI do tekstowych uruchomień awaryjnych (bez wywołań narzędzi). Przydatne jako zapasowe rozwiązanie, gdy dostawcy API zawodzą.
Opcjonalne backendy CLI dla rezerwowych uruchomień tylko tekstowych (bez wywołań narzędzi). Przydatne jako zapas, gdy dostawcy API zawiodą.
```json5
{
@ -470,13 +485,13 @@ Opcjonalne backendy CLI do tekstowych uruchomień awaryjnych (bez wywołań narz
}
```
- Backendy CLI są przede wszystkim tekstowe; narzędzia są zawsze wyłączone.
- Backendy CLI są tekstowe w pierwszej kolejności; narzędzia są zawsze wyłączone.
- Sesje są obsługiwane, gdy ustawiono `sessionArg`.
- Przekazywanie obrazów jest obsługiwane, gdy `imageArg` przyjmuje ścieżki plików.
- Przekazywanie obrazów jest obsługiwane, gdy `imageArg` akceptuje ścieżki plików.
### `agents.defaults.systemPromptOverride`
Zastąp cały prompt systemowy złożony przez OpenClaw stałym ciągiem znaków. Ustaw na poziomie domyślnym (`agents.defaults.systemPromptOverride`) albo dla agenta (`agents.list[].systemPromptOverride`). Wartości dla agenta mają pierwszeństwo; wartość pusta lub zawierająca wyłącznie białe znaki jest ignorowana. Przydatne do kontrolowanych eksperymentów z promptami.
Zastępuje cały prompt systemowy złożony przez OpenClaw stałym ciągiem tekstowym. Ustaw na poziomie domyślnym (`agents.defaults.systemPromptOverride`) albo dla agenta (`agents.list[].systemPromptOverride`). Wartości dla poszczególnych agentów mają pierwszeństwo; wartość pusta lub zawierająca tylko białe znaki jest ignorowana. Przydatne do kontrolowanych eksperymentów z promptami.
```json5
{
@ -490,7 +505,7 @@ Zastąp cały prompt systemowy złożony przez OpenClaw stałym ciągiem znaków
### `agents.defaults.promptOverlays`
Niezależne od dostawcy nakładki promptów stosowane według rodziny modeli. Identyfikatory modeli z rodziny GPT-5 otrzymują współdzielony kontrakt zachowania u różnych dostawców; `personality` kontroluje tylko przyjazną warstwę stylu interakcji.
Niezależne od dostawcy nakładki promptów stosowane według rodziny modelu. Identyfikatory modeli z rodziny GPT-5 otrzymują wspólny kontrakt zachowania u wszystkich dostawców; `personality` steruje tylko przyjazną warstwą stylu interakcji.
```json5
{
@ -508,7 +523,7 @@ Niezależne od dostawcy nakładki promptów stosowane według rodziny modeli. Id
- `"friendly"` (domyślnie) i `"on"` włączają przyjazną warstwę stylu interakcji.
- `"off"` wyłącza tylko przyjazną warstwę; oznaczony kontrakt zachowania GPT-5 pozostaje włączony.
- Starsze `plugins.entries.openai.config.personality` nadal jest odczytywane, gdy to współdzielone ustawienie nie jest ustawione.
- Starsze `plugins.entries.openai.config.personality` jest nadal odczytywane, gdy to wspólne ustawienie nie jest ustawione.
### `agents.defaults.heartbeat`
@ -541,15 +556,15 @@ Okresowe uruchomienia Heartbeat.
```
- `every`: ciąg czasu trwania (ms/s/m/h). Domyślnie: `30m` (uwierzytelnianie kluczem API) albo `1h` (uwierzytelnianie OAuth). Ustaw na `0m`, aby wyłączyć.
- `includeSystemPromptSection`: gdy ma wartość false, pomija sekcję Heartbeat w prompcie systemowym i pomija wstrzyknięcie `HEARTBEAT.md` do kontekstu rozruchowego. Domyślnie: `true`.
- `includeSystemPromptSection`: gdy ma wartość false, pomija sekcję Heartbeat w prompcie systemowym i pomija wstrzykiwanie `HEARTBEAT.md` do kontekstu startowego. Domyślnie: `true`.
- `suppressToolErrorWarnings`: gdy ma wartość true, wycisza ładunki ostrzeżeń o błędach narzędzi podczas uruchomień Heartbeat.
- `timeoutSeconds`: maksymalny czas w sekundach dozwolony dla tury agenta Heartbeat, zanim zostanie przerwana. Pozostaw nieustawione, aby użyć `agents.defaults.timeoutSeconds`.
- `directPolicy`: zasada dostarczania bezpośredniego/DM. `allow` (domyślnie) zezwala na dostarczanie do celu bezpośredniego. `block` blokuje dostarczanie do celu bezpośredniego i emituje `reason=dm-blocked`.
- `lightContext`: gdy ma wartość true, uruchomienia Heartbeat używają lekkiego kontekstu rozruchowego i zachowują tylko `HEARTBEAT.md` z plików rozruchowych przestrzeni roboczej.
- `isolatedSession`: gdy ma wartość true, każde uruchomienie Heartbeat działa w świeżej sesji bez wcześniejszej historii rozmowy. Ten sam wzorzec izolacji co cron `sessionTarget: "isolated"`. Zmniejsza koszt tokenów na Heartbeat z około 100K do około 2-5K tokenów.
- `skipWhenBusy`: gdy ma wartość true, uruchomienia Heartbeat są odkładane przy dodatkowo zajętych ścieżkach: pracy subagentów lub zagnieżdżonych poleceń. Ścieżki Cron zawsze odkładają Heartbeat, nawet bez tej flagi.
- Dla agenta: ustaw `agents.list[].heartbeat`. Gdy dowolny agent definiuje `heartbeat`, Heartbeat uruchamiają **tylko ci agenci**.
- Heartbeat uruchamia pełne tury agenta — krótsze interwały zużywają więcej tokenów.
- `timeoutSeconds`: maksymalny czas w sekundach dozwolony dla tury agenta Heartbeat przed jej przerwaniem. Pozostaw nieustawione, aby użyć `agents.defaults.timeoutSeconds`.
- `directPolicy`: zasada dostarczania bezpośredniego/DM. `allow` (domyślnie) zezwala na dostarczanie do bezpośredniego celu. `block` tłumi dostarczanie do bezpośredniego celu i emituje `reason=dm-blocked`.
- `lightContext`: gdy ma wartość true, uruchomienia Heartbeat używają lekkiego kontekstu startowego i zachowują tylko `HEARTBEAT.md` z plików startowych obszaru roboczego.
- `isolatedSession`: gdy ma wartość true, każde uruchomienie Heartbeat działa w świeżej sesji bez wcześniejszej historii konwersacji. Ten sam wzorzec izolacji co w Cron `sessionTarget: "isolated"`. Zmniejsza koszt tokenów na jedno Heartbeat z około 100K do około 2-5K tokenów.
- `skipWhenBusy`: gdy ma wartość true, uruchomienia Heartbeat są odraczane przy dodatkowo zajętych ścieżkach: pracy subagenta lub zagnieżdżonego polecenia. Ścieżki Cron zawsze odraczają Heartbeat, nawet bez tej flagi.
- Dla agenta: ustaw `agents.list[].heartbeat`. Gdy dowolny agent definiuje `heartbeat`, **tylko ci agenci** uruchamiają Heartbeat.
- Heartbeat uruchamiają pełne tury agenta — krótsze interwały zużywają więcej tokenów.
### `agents.defaults.compaction`
@ -585,19 +600,19 @@ Okresowe uruchomienia Heartbeat.
}
```
- `mode`: `default` albo `safeguard` (podsumowanie porcjami dla długich historii). Zobacz [Compaction](/pl/concepts/compaction).
- `provider`: identyfikator zarejestrowanego providera Plugin compaction. Gdy jest ustawiony, wywoływane jest `summarize()` providera zamiast wbudowanego podsumowania LLM. W razie niepowodzenia następuje powrót do wbudowanego mechanizmu. Ustawienie providera wymusza `mode: "safeguard"`. Zobacz [Compaction](/pl/concepts/compaction).
- `timeoutSeconds`: maksymalna liczba sekund dozwolona dla pojedynczej operacji compaction, zanim OpenClaw ją przerwie. Domyślnie: `900`.
- `keepRecentTokens`: budżet punktu odcięcia Pi do zachowania najnowszego końca transkryptu dosłownie. Ręczne `/compact` honoruje to ustawienie, gdy jest jawnie ustawione; w przeciwnym razie ręczna compaction jest twardym punktem kontrolnym.
- `identifierPolicy`: `strict` (domyślnie), `off` albo `custom`. `strict` poprzedza podsumowanie compaction wbudowanymi wskazówkami dotyczącymi zachowywania nieprzezroczystych identyfikatorów.
- `identifierInstructions`: opcjonalny niestandardowy tekst dotyczący zachowywania identyfikatorów używany, gdy `identifierPolicy=custom`.
- `qualityGuard`: kontrole ponawiania przy niepoprawnie sformatowanych wynikach dla podsumowań safeguard. Domyślnie włączone w trybie safeguard; ustaw `enabled: false`, aby pominąć audyt.
- `midTurnPrecheck`: opcjonalna kontrola presji pętli narzędzi Pi. Gdy `enabled: true`, OpenClaw sprawdza presję kontekstu po dołączeniu wyników narzędzi i przed następnym wywołaniem modelu. Jeśli kontekst już się nie mieści, przerywa bieżącą próbę przed przesłaniem promptu i używa istniejącej ścieżki odzyskiwania po precheck, aby skrócić wyniki narzędzi albo wykonać compaction i ponowić. Działa z trybami compaction `default` i `safeguard`. Domyślnie: wyłączone.
- `postCompactionSections`: opcjonalne nazwy sekcji H2/H3 z AGENTS.md do ponownego wstrzyknięcia po compaction. Domyślnie `["Session Startup", "Red Lines"]`; ustaw `[]`, aby wyłączyć ponowne wstrzykiwanie. Gdy nieustawione albo jawnie ustawione na tę domyślną parę, starsze nagłówki `Every Session`/`Safety` są też akceptowane jako starsza ścieżka awaryjna.
- `model`: opcjonalne nadpisanie `provider/model-id` tylko dla podsumowania compaction. Użyj tego, gdy główna sesja powinna zachować jeden model, ale podsumowania compaction powinny działać na innym; gdy nieustawione, compaction używa głównego modelu sesji.
- `maxActiveTranscriptBytes`: opcjonalny próg bajtów (`number` albo ciągi takie jak `"20mb"`), który wyzwala normalną lokalną compaction przed uruchomieniem, gdy aktywny JSONL przekroczy próg. Wymaga `truncateAfterCompaction`, aby udana compaction mogła obrócić sesję na mniejszy następczy transkrypt. Wyłączone, gdy nieustawione albo `0`.
- `notifyUser`: gdy `true`, wysyła użytkownikowi krótkie powiadomienia, gdy compaction się zaczyna i gdy się kończy (na przykład „Kompaktowanie kontekstu...” i „Compaction ukończona”). Domyślnie wyłączone, aby compaction była cicha.
- `memoryFlush`: cicha agentowa tura przed automatyczną compaction, służąca do zapisania trwałych pamięci. Ustaw `model` na dokładny provider/model, taki jak `ollama/qwen3:8b`, gdy ta tura porządkowa powinna pozostać na modelu lokalnym; nadpisanie nie dziedziczy aktywnego łańcucha awaryjnego sesji. Pomijane, gdy przestrzeń robocza jest tylko do odczytu.
- `mode`: `default` albo `safeguard` (kawałkowe streszczanie długich historii). Zobacz [Compaction](/pl/concepts/compaction).
- `provider`: identyfikator zarejestrowanego Plugin dostawcy Compaction. Gdy jest ustawiony, wywoływane jest `summarize()` dostawcy zamiast wbudowanego streszczania LLM. W razie niepowodzenia następuje powrót do wbudowanego mechanizmu. Ustawienie dostawcy wymusza `mode: "safeguard"`. Zobacz [Compaction](/pl/concepts/compaction).
- `timeoutSeconds`: maksymalna liczba sekund dozwolona dla pojedynczej operacji Compaction, zanim OpenClaw ją przerwie. Domyślnie: `900`.
- `keepRecentTokens`: budżet punktu odcięcia Pi na zachowanie najnowszego ogona transkryptu bez zmian. Ręczne `/compact` respektuje to, gdy jest jawnie ustawione; w przeciwnym razie ręczna Compaction jest twardym punktem kontrolnym.
- `identifierPolicy`: `strict` (domyślnie), `off` albo `custom`. `strict` poprzedza streszczanie Compaction wbudowanymi wskazówkami zachowania nieprzezroczystych identyfikatorów.
- `identifierInstructions`: opcjonalny niestandardowy tekst zachowania identyfikatorów używany, gdy `identifierPolicy=custom`.
- `qualityGuard`: kontrole ponawiania przy niepoprawnie sformatowanych danych wyjściowych dla podsumowań safeguard. Domyślnie włączone w trybie safeguard; ustaw `enabled: false`, aby pominąć audyt.
- `midTurnPrecheck`: opcjonalna kontrola presji pętli narzędzi Pi. Gdy `enabled: true`, OpenClaw sprawdza presję kontekstu po dołączeniu wyników narzędzi i przed kolejnym wywołaniem modelu. Jeśli kontekst już się nie mieści, przerywa bieżącą próbę przed przesłaniem promptu i ponownie używa istniejącej ścieżki odzyskiwania z kontroli wstępnej, aby skrócić wyniki narzędzi albo wykonać Compaction i spróbować ponownie. Działa z trybami Compaction `default` i `safeguard`. Domyślnie: wyłączone.
- `postCompactionSections`: opcjonalne nazwy sekcji H2/H3 z AGENTS.md do ponownego wstrzyknięcia po Compaction. Domyślnie `["Session Startup", "Red Lines"]`; ustaw `[]`, aby wyłączyć ponowne wstrzykiwanie. Gdy nieustawione albo jawnie ustawione na tę domyślną parę, starsze nagłówki `Every Session`/`Safety` są także akceptowane jako starszy mechanizm awaryjny.
- `model`: opcjonalne nadpisanie `provider/model-id` tylko dla streszczania Compaction. Użyj tego, gdy główna sesja ma zachować jeden model, ale podsumowania Compaction mają działać na innym; gdy nieustawione, Compaction używa podstawowego modelu sesji.
- `maxActiveTranscriptBytes`: opcjonalny próg bajtów (`number` lub ciągi takie jak `"20mb"`), który wyzwala normalną lokalną Compaction przed uruchomieniem, gdy aktywny JSONL przekroczy próg. Wymaga `truncateAfterCompaction`, aby udana Compaction mogła obrócić transkrypt na mniejszy następny. Wyłączone, gdy nieustawione albo `0`.
- `notifyUser`: gdy `true`, wysyła użytkownikowi krótkie powiadomienia, gdy Compaction się zaczyna i gdy się kończy (na przykład „Compacting context...” i „Compaction complete”). Domyślnie wyłączone, aby Compaction pozostała cicha.
- `memoryFlush`: cicha agentowa tura przed automatyczną Compaction w celu zapisania trwałych wspomnień. Ustaw `model` na dokładny model dostawcy, taki jak `ollama/qwen3:8b`, gdy ta porządkowa tura ma pozostać na lokalnym modelu; nadpisanie nie dziedziczy aktywnego łańcucha awaryjnego sesji. Pomijane, gdy obszar roboczy jest tylko do odczytu.
### `agents.defaults.contextPruning`
@ -626,10 +641,10 @@ Przycina **stare wyniki narzędzi** z kontekstu w pamięci przed wysłaniem do L
<Accordion title="zachowanie trybu cache-ttl">
- `mode: "cache-ttl"` włącza przebiegi przycinania.
- `ttl` kontroluje, jak często przycinanie może zostać uruchomione ponownie (po ostatnim dotknięciu cache).
- `ttl` steruje tym, jak często przycinanie może uruchomić się ponownie (po ostatnim dotknięciu pamięci podręcznej).
- Przycinanie najpierw miękko skraca zbyt duże wyniki narzędzi, a następnie w razie potrzeby twardo czyści starsze wyniki narzędzi.
**Miękkie skracanie** zachowuje początek i koniec oraz wstawia `...` pośrodku.
**Miękkie skracanie** zachowuje początek + koniec i wstawia `...` w środku.
**Twarde czyszczenie** zastępuje cały wynik narzędzia symbolem zastępczym.
@ -643,7 +658,7 @@ Uwagi:
Zobacz [Przycinanie sesji](/pl/concepts/session-pruning), aby poznać szczegóły zachowania.
### Strumieniowanie blokowe
### Strumieniowanie bloków
```json5
{
@ -661,9 +676,9 @@ Zobacz [Przycinanie sesji](/pl/concepts/session-pruning), aby poznać szczegół
- Kanały inne niż Telegram wymagają jawnego `*.blockStreaming: true`, aby włączyć odpowiedzi blokowe.
- Nadpisania kanałów: `channels.<channel>.blockStreamingCoalesce` (oraz warianty dla poszczególnych kont). Signal/Slack/Discord/Google Chat domyślnie używają `minChars: 1500`.
- `humanDelay`: losowa pauza między odpowiedziami blokowymi. `natural` = 800–2500 ms. Nadpisanie dla agenta: `agents.list[].humanDelay`.
- `humanDelay`: losowa pauza między odpowiedziami blokowymi. `natural` = 800–2500 ms. Nadpisanie dla poszczególnych agentów: `agents.list[].humanDelay`.
Zobacz [Streaming](/pl/concepts/streaming), aby poznać szczegóły zachowania i dzielenia na fragmenty.
Zobacz [Strumieniowanie](/pl/concepts/streaming), aby poznać szczegóły zachowania i dzielenia na fragmenty.
### Wskaźniki pisania
@ -678,8 +693,8 @@ Zobacz [Streaming](/pl/concepts/streaming), aby poznać szczegóły zachowania i
}
```
- Wartości domyślne: `instant` dla czatów bezpośrednich/wzmianek, `message` dla czatów grupowych bez wzmianki.
- Nadpisania dla sesji: `session.typingMode`, `session.typingIntervalSeconds`.
- Domyślnie: `instant` dla czatów bezpośrednich/wzmianek, `message` dla czatów grupowych bez wzmianki.
- Nadpisania dla poszczególnych sesji: `session.typingMode`, `session.typingIntervalSeconds`.
Zobacz [Wskaźniki pisania](/pl/concepts/typing-indicators).
@ -687,7 +702,7 @@ Zobacz [Wskaźniki pisania](/pl/concepts/typing-indicators).
### `agents.defaults.sandbox`
Opcjonalna izolacja dla osadzonego agenta. Pełny przewodnik znajdziesz w sekcji [Izolacja](/pl/gateway/sandboxing).
Opcjonalna izolacja w sandboxie dla osadzonego agenta. Zobacz [Izolacja w sandboxie](/pl/gateway/sandboxing), aby poznać pełny przewodnik.
```json5
{
@ -782,52 +797,52 @@ Opcjonalna izolacja dla osadzonego agenta. Pełny przewodnik znajdziesz w sekcji
}
```
<Accordion title="Szczegóły izolacji">
<Accordion title="Sandbox details">
**Backend:**
- `docker`: lokalne środowisko uruchomieniowe Docker (domyślne)
- `ssh`: ogólne zdalne środowisko uruchomieniowe oparte na SSH
- `openshell`: środowisko uruchomieniowe OpenShell
- `docker`: lokalne środowisko wykonawcze Docker (domyślne)
- `ssh`: ogólne zdalne środowisko wykonawcze oparte na SSH
- `openshell`: środowisko wykonawcze OpenShell
Gdy wybrano `backend: "openshell"`, ustawienia specyficzne dla środowiska uruchomieniowego przenoszą się do
Gdy wybrano `backend: "openshell"`, ustawienia specyficzne dla środowiska wykonawczego są przenoszone do
`plugins.entries.openshell.config`.
**Konfiguracja backendu SSH:**
- `target`: cel SSH w formie `user@host[:port]`
- `command`: polecenie klienta SSH (domyślnie: `ssh`)
- `workspaceRoot`: bezwzględny zdalny katalog główny używany dla obszarów roboczych zależnych od zakresu
- `workspaceRoot`: bezwzględny zdalny katalog główny używany dla przestrzeni roboczych w poszczególnych zakresach
- `identityFile` / `certificateFile` / `knownHostsFile`: istniejące pliki lokalne przekazywane do OpenSSH
- `identityData` / `certificateData` / `knownHostsData`: treść inline lub SecretRef, które OpenClaw materializuje w plikach tymczasowych w czasie działania
- `strictHostKeyChecking` / `updateHostKeys`: pokrętła zasad kluczy hosta OpenSSH
- `identityData` / `certificateData` / `knownHostsData`: treść wbudowana lub SecretRefs, które OpenClaw materializuje jako pliki tymczasowe w czasie działania
- `strictHostKeyChecking` / `updateHostKeys`: przełączniki zasad kluczy hostów OpenSSH
**Kolejność pierwszeństwa uwierzytelniania SSH:**
**Priorytet uwierzytelniania SSH:**
- `identityData` ma pierwszeństwo przed `identityFile`
- `certificateData` ma pierwszeństwo przed `certificateFile`
- `knownHostsData` ma pierwszeństwo przed `knownHostsFile`
- Wartości `*Data` oparte na SecretRef są rozwiązywane z aktywnej migawki środowiska uruchomieniowego sekretów przed rozpoczęciem sesji izolacji
- wartości `*Data` oparte na SecretRef są rozwiązywane z aktywnego zrzutu środowiska wykonawczego sekretów przed rozpoczęciem sesji sandbox
**Zachowanie backendu SSH:**
- inicjalizuje zdalny obszar roboczy raz po utworzeniu lub ponownym utworzeniu
- następnie utrzymuje zdalny obszar roboczy SSH jako kanoniczny
- kieruje `exec`, narzędzia plikowe i ścieżki mediów przez SSH
- inicjuje zdalną przestrzeń roboczą raz po utworzeniu lub ponownym utworzeniu
- następnie utrzymuje zdalną przestrzeń roboczą SSH jako kanoniczną
- kieruje `exec`, narzędzia plikowe i ścieżki multimediów przez SSH
- nie synchronizuje automatycznie zdalnych zmian z powrotem do hosta
- nie obsługuje kontenerów przeglądarki izolacji
- nie obsługuje kontenerów przeglądarki sandbox
**Dostęp do obszaru roboczego:**
**Dostęp do workspace:**
- `none`: obszar roboczy izolacji zależny od zakresu pod `~/.openclaw/sandboxes`
- `ro`: obszar roboczy izolacji w `/workspace`, obszar roboczy agenta zamontowany tylko do odczytu w `/agent`
- `rw`: obszar roboczy agenta zamontowany do odczytu/zapisu w `/workspace`
- `none`: sandbox workspace dla danego zakresu w `~/.openclaw/sandboxes`
- `ro`: sandbox workspace w `/workspace`, workspace agenta zamontowany tylko do odczytu w `/agent`
- `rw`: workspace agenta zamontowany do odczytu/zapisu w `/workspace`
**Zakres:**
- `session`: kontener i obszar roboczy dla każdej sesji
- `agent`: jeden kontener i obszar roboczy na agenta (domyślnie)
- `shared`: współdzielony kontener i obszar roboczy (bez izolacji między sesjami)
- `session`: kontener + workspace dla sesji
- `agent`: jeden kontener + workspace na agenta (domyślnie)
- `shared`: współdzielony kontener i workspace (bez izolacji między sesjami)
**Konfiguracja Plugin OpenShell:**
@ -857,30 +872,30 @@ Gdy wybrano `backend: "openshell"`, ustawienia specyficzne dla środowiska uruch
**Tryb OpenShell:**
- `mirror`: inicjalizuje zdalne środowisko z lokalnego przed exec, synchronizuje z powrotem po exec; lokalny obszar roboczy pozostaje kanoniczny
- `remote`: inicjalizuje zdalne środowisko raz przy tworzeniu izolacji, następnie utrzymuje zdalny obszar roboczy jako kanoniczny
- `mirror`: przed wykonaniem zasiej środowisko z lokalnego do zdalnego, po wykonaniu zsynchronizuj z powrotem; lokalny workspace pozostaje kanoniczny
- `remote`: zasiej zdalne środowisko raz podczas tworzenia sandboxa, a następnie utrzymuj zdalny workspace jako kanoniczny
W trybie `remote` lokalne edycje hosta wykonane poza OpenClaw nie są automatycznie synchronizowane z izolacją po kroku inicjalizacji.
Transport odbywa się przez SSH do izolacji OpenShell, ale Plugin jest właścicielem cyklu życia izolacji i opcjonalnej synchronizacji lustrzanej.
W trybie `remote` zmiany lokalne hosta wykonane poza OpenClaw nie są automatycznie synchronizowane do sandboxa po kroku zasiania.
Transport odbywa się przez SSH do sandboxa OpenShell, ale Plugin zarządza cyklem życia sandboxa i opcjonalną synchronizacją lustrzaną.
**`setupCommand`** uruchamia się raz po utworzeniu kontenera (przez `sh -lc`). Wymaga wyjścia do sieci, zapisywalnego katalogu głównego i użytkownika root.
**Kontenery domyślnie używają `network: "none"`** — ustaw `"bridge"` (lub niestandardową sieć bridge), jeśli agent potrzebuje dostępu wychodzącego.
**Kontenery domyślnie mają `network: "none"`** — ustaw na `"bridge"` (albo niestandardową sieć bridge), jeśli agent potrzebuje dostępu wychodzącego.
`"host"` jest blokowane. `"container:<id>"` jest domyślnie blokowane, chyba że jawnie ustawisz
`sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true` (tryb awaryjny).
**Załączniki przychodzące** są umieszczane w `media/inbound/*` w aktywnym obszarze roboczym.
**Załączniki przychodzące** są umieszczane w `media/inbound/*` w aktywnym workspace.
**`docker.binds`** montuje dodatkowe katalogi hosta; powiązania globalne i dla agenta są scalane.
**Izolowana przeglądarka** (`sandbox.browser.enabled`): Chromium + CDP w kontenerze. Adres URL noVNC jest wstrzykiwany do promptu systemowego. Nie wymaga `browser.enabled` w `openclaw.json`.
Dostęp obserwatora noVNC domyślnie używa uwierzytelniania VNC, a OpenClaw emituje krótkotrwały adres URL z tokenem (zamiast ujawniać hasło we współdzielonym adresie URL).
**Przeglądarka w sandboxie** (`sandbox.browser.enabled`): Chromium + CDP w kontenerze. Adres URL noVNC jest wstrzykiwany do promptu systemowego. Nie wymaga `browser.enabled` w `openclaw.json`.
Dostęp obserwatora noVNC domyślnie używa uwierzytelniania VNC, a OpenClaw emituje krótkotrwały URL z tokenem (zamiast ujawniać hasło we współdzielonym adresie URL).
- `allowHostControl: false` (domyślnie) blokuje sesjom izolowanym możliwość kierowania na przeglądarkę hosta.
- `network` domyślnie ma wartość `openclaw-sandbox-browser` (dedykowana sieć bridge). Ustaw `bridge` tylko wtedy, gdy jawnie chcesz globalną łączność bridge.
- `allowHostControl: false` (domyślnie) blokuje sesjom w sandboxie możliwość wskazywania przeglądarki hosta.
- `network` domyślnie to `openclaw-sandbox-browser` (dedykowana sieć bridge). Ustaw `bridge` tylko wtedy, gdy jawnie chcesz globalnej łączności bridge.
- `cdpSourceRange` opcjonalnie ogranicza ruch przychodzący CDP na krawędzi kontenera do zakresu CIDR (na przykład `172.21.0.1/32`).
- `sandbox.browser.binds` montuje dodatkowe katalogi hosta tylko w kontenerze przeglądarki izolacji. Gdy jest ustawione (w tym `[]`), zastępuje `docker.binds` dla kontenera przeglądarki.
- Domyślne ustawienia uruchamiania są zdefiniowane w `scripts/sandbox-browser-entrypoint.sh` i dostrojone dla hostów kontenerów:
- `sandbox.browser.binds` montuje dodatkowe katalogi hosta tylko do kontenera przeglądarki sandboxa. Gdy jest ustawione (w tym `[]`), zastępuje `docker.binds` dla kontenera przeglądarki.
- Domyślne opcje uruchamiania są zdefiniowane w `scripts/sandbox-browser-entrypoint.sh` i dostrojone dla hostów kontenerów:
- `--remote-debugging-address=127.0.0.1`
- `--remote-debugging-port=<derived from OPENCLAW_BROWSER_CDP_PORT>`
- `--user-data-dir=${HOME}/.chrome`
@ -901,18 +916,20 @@ Dostęp obserwatora noVNC domyślnie używa uwierzytelniania VNC, a OpenClaw emi
- `--disable-3d-apis`, `--disable-software-rasterizer` i `--disable-gpu` są
domyślnie włączone i można je wyłączyć za pomocą
`OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0`, jeśli wymaga tego użycie WebGL/3D.
- `OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0` ponownie włącza rozszerzenia, jeśli zależy od nich Twój przepływ pracy.
- `OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0` ponownie włącza rozszerzenia, jeśli Twój przepływ pracy
od nich zależy.
- `--renderer-process-limit=2` można zmienić za pomocą
`OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=<N>`; ustaw `0`, aby użyć domyślnego limitu procesów Chromium.
- oraz `--no-sandbox`, gdy włączono `noSandbox`.
- Wartości domyślne są bazą obrazu kontenera; użyj niestandardowego obrazu przeglądarki z niestandardowym
entrypointem, aby zmienić domyślne ustawienia kontenera.
`OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=<N>`; ustaw `0`, aby użyć domyślnego
limitu procesów Chromium.
- plus `--no-sandbox`, gdy `noSandbox` jest włączone.
- Wartości domyślne są bazą obrazu kontenera; aby zmienić domyślne ustawienia kontenera, użyj niestandardowego obrazu przeglądarki z niestandardowym
entrypoint.
</Accordion>
Izolacja przeglądarki i `sandbox.docker.binds` działają tylko z Dockerem.
Sandboxing przeglądarki i `sandbox.docker.binds` działają tylko z Dockerem.
Budowanie obrazów:
Zbuduj obrazy:
```bash
scripts/sandbox-setup.sh # main sandbox image
@ -923,8 +940,8 @@ scripts/sandbox-browser-setup.sh # optional browser image
Użyj `agents.list[].tts`, aby nadać agentowi własnego dostawcę TTS, głos, model,
styl lub tryb automatycznego TTS. Blok agenta jest głęboko scalany z globalnym
`messages.tts`, dzięki czemu współdzielone dane uwierzytelniające mogą pozostać w jednym miejscu, podczas gdy poszczególni
agenci nadpisują tylko potrzebne pola głosu lub dostawcy. Nadpisanie aktywnego agenta
`messages.tts`, więc współdzielone poświadczenia mogą pozostać w jednym miejscu, a poszczególni
agenci nadpisują tylko potrzebne im pola głosu lub dostawcy. Nadpisanie aktywnego agenta
dotyczy automatycznych odpowiedzi mówionych, `/tts audio`, `/tts status` oraz
narzędzia agenta `tts`. Zobacz [Tekst na mowę](/pl/tools/tts#per-agent-voice-overrides),
aby poznać przykłady dostawców i kolejność pierwszeństwa.
@ -982,27 +999,27 @@ aby poznać przykłady dostawców i kolejność pierwszeństwa.
```
- `id`: stabilny identyfikator agenta (wymagany).
- `default`: gdy ustawiono kilka, wygrywa pierwszy (zostanie zapisane ostrzeżenie). Jeśli nie ustawiono żadnego, domyślny jest pierwszy wpis listy.
- `model`: forma tekstowa ustawia ścisły podstawowy model dla agenta bez fallbacku modelu; forma obiektowa `{ primary }` także jest ścisła, chyba że dodasz `fallbacks`. Użyj `{ primary, fallbacks: [...] }`, aby włączyć fallback dla tego agenta, albo `{ primary, fallbacks: [] }`, aby jawnie wymusić ścisłe zachowanie. Zadania Cron, które nadpisują tylko `primary`, nadal dziedziczą domyślne fallbacki, chyba że ustawisz `fallbacks: []`.
- `params`: parametry strumienia dla agenta scalane nad wybranym wpisem modelu w `agents.defaults.models`. Użyj tego do nadpisań specyficznych dla agenta, takich jak `cacheRetention`, `temperature` lub `maxTokens`, bez duplikowania całego katalogu modeli.
- `tts`: opcjonalne nadpisania zamiany tekstu na mowę dla agenta. Blok jest głęboko scalany nad `messages.tts`, więc współdzielone dane uwierzytelniające dostawcy i politykę fallbacku trzymaj w `messages.tts`, a tutaj ustawiaj tylko wartości specyficzne dla persony, takie jak dostawca, głos, model, styl lub tryb automatyczny.
- `default`: gdy ustawiono kilka, wygrywa pierwszy (rejestrowane jest ostrzeżenie). Jeśli nie ustawiono żadnego, domyślna jest pierwsza pozycja listy.
- `model`: forma tekstowa ustawia ścisły główny model dla agenta bez modelu zapasowego; forma obiektowa `{ primary }` także jest ścisła, chyba że dodasz `fallbacks`. Użyj `{ primary, fallbacks: [...] }`, aby włączyć dla tego agenta model zapasowy, albo `{ primary, fallbacks: [] }`, aby jawnie ustawić ścisłe zachowanie. Zadania Cron, które nadpisują tylko `primary`, nadal dziedziczą domyślne modele zapasowe, chyba że ustawisz `fallbacks: []`.
- `params`: parametry strumienia dla agenta scalane ponad wybranym wpisem modelu w `agents.defaults.models`. Użyj tego do nadpisań specyficznych dla agenta, takich jak `cacheRetention`, `temperature` lub `maxTokens`, bez duplikowania całego katalogu modeli.
- `tts`: opcjonalne nadpisania text-to-speech dla agenta. Blok jest głęboko scalany ponad `messages.tts`, więc wspólne dane uwierzytelniające dostawcy i zasady awaryjne trzymaj w `messages.tts`, a tutaj ustawiaj tylko wartości specyficzne dla persony, takie jak dostawca, głos, model, styl lub tryb automatyczny.
- `skills`: opcjonalna lista dozwolonych Skills dla agenta. Jeśli pominięto, agent dziedziczy `agents.defaults.skills`, gdy jest ustawione; jawna lista zastępuje wartości domyślne zamiast je scalać, a `[]` oznacza brak Skills.
- `thinkingDefault`: opcjonalny domyślny poziom myślenia dla agenta (`off | minimal | low | medium | high | xhigh | adaptive | max`). Nadpisuje `agents.defaults.thinkingDefault` dla tego agenta, gdy nie ustawiono nadpisania dla wiadomości ani sesji. Wybrany profil dostawcy/modelu kontroluje, które wartości są prawidłowe; dla Google Gemini `adaptive` zachowuje dynamiczne myślenie zarządzane przez dostawcę (`thinkingLevel` pominięte w Gemini 3/3.1, `thinkingBudget: -1` w Gemini 2.5).
- `thinkingDefault`: opcjonalny domyślny poziom myślenia dla agenta (`off | minimal | low | medium | high | xhigh | adaptive | max`). Nadpisuje `agents.defaults.thinkingDefault` dla tego agenta, gdy nie ustawiono nadpisania dla wiadomości ani sesji. Wybrany profil dostawcy/modelu kontroluje, które wartości są prawidłowe; dla Google Gemini `adaptive` zachowuje dynamiczne myślenie kontrolowane przez dostawcę (`thinkingLevel` pominięte w Gemini 3/3.1, `thinkingBudget: -1` w Gemini 2.5).
- `reasoningDefault`: opcjonalna domyślna widoczność rozumowania dla agenta (`on | off | stream`). Nadpisuje `agents.defaults.reasoningDefault` dla tego agenta, gdy nie ustawiono nadpisania rozumowania dla wiadomości ani sesji.
- `fastModeDefault`: opcjonalna wartość domyślna trybu szybkiego dla agenta (`true | false`). Ma zastosowanie, gdy nie ustawiono nadpisania trybu szybkiego dla wiadomości ani sesji.
- `agentRuntime`: opcjonalne nadpisanie niskopoziomowej polityki runtime dla agenta. Użyj `{ id: "codex" }`, aby jeden agent używał tylko Codex, podczas gdy inni agenci zachowują domyślny fallback PI w trybie `auto`.
- `runtime`: opcjonalny deskryptor runtime dla agenta. Użyj `type: "acp"` z wartościami domyślnymi `runtime.acp` (`agent`, `backend`, `mode`, `cwd`), gdy agent powinien domyślnie używać sesji uprzęży ACP.
- `identity.avatar`: ścieżka względna wobec obszaru roboczego, URL `http(s)` albo URI `data:`.
- `agentRuntime`: opcjonalne nadpisanie niskopoziomowych zasad środowiska uruchomieniowego dla agenta. Użyj `{ id: "codex" }`, aby jeden agent działał tylko z Codex, podczas gdy inni agenci zachowują domyślną opcję awaryjną PI w trybie `auto`.
- `runtime`: opcjonalny deskryptor środowiska uruchomieniowego dla agenta. Użyj `type: "acp"` z wartościami domyślnymi `runtime.acp` (`agent`, `backend`, `mode`, `cwd`), gdy agent ma domyślnie używać sesji uprzęży ACP.
- `identity.avatar`: ścieżka względna względem obszaru roboczego, URL `http(s)` albo URI `data:`.
- `identity` wyprowadza wartości domyślne: `ackReaction` z `emoji`, `mentionPatterns` z `name`/`emoji`.
- `subagents.allowAgents`: lista dozwolonych identyfikatorów agentów dla jawnych celów `sessions_spawn.agentId` (`["*"]` = dowolny; domyślnie: tylko ten sam agent). Uwzględnij identyfikator żądającego, gdy samocelowane wywołania `agentId` mają być dozwolone.
- `subagents.allowAgents`: lista dozwolonych identyfikatorów agentów dla jawnych celów `sessions_spawn.agentId` (`["*"]` = dowolny; domyślnie: tylko ten sam agent). Uwzględnij identyfikator żądającego, gdy samocelujące wywołania `agentId` mają być dozwolone.
- Ochrona dziedziczenia piaskownicy: jeśli sesja żądającego działa w piaskownicy, `sessions_spawn` odrzuca cele, które działałyby bez piaskownicy.
- `subagents.requireAgentId`: gdy ma wartość true, blokuje wywołania `sessions_spawn`, które pomijają `agentId` (wymusza jawny wybór profilu; domyślnie: false).
---
## Routing wielu agentów
## Routing wieloagentowy
Uruchamiaj wielu izolowanych agentów w jednym Gateway. Zobacz [Wielu agentów](/pl/concepts/multi-agent).
Uruchamiaj wielu izolowanych agentów w jednym Gateway. Zobacz [Multi-Agent](/pl/concepts/multi-agent).
```json5
{
@ -1021,7 +1038,7 @@ Uruchamiaj wielu izolowanych agentów w jednym Gateway. Zobacz [Wielu agentów](
### Pola dopasowania powiązania
- `type` (opcjonalne): `route` dla normalnego routingu (brak typu domyślnie oznacza route), `acp` dla trwałych powiązań konwersacji ACP.
- `type` (opcjonalne): `route` dla normalnego routingu (brakujący typ domyślnie oznacza route), `acp` dla trwałych powiązań rozmów ACP.
- `match.channel` (wymagane)
- `match.accountId` (opcjonalne; `*` = dowolne konto; pominięte = konto domyślne)
- `match.peer` (opcjonalne; `{ kind: direct|group|channel, id }`)
@ -1034,16 +1051,16 @@ Uruchamiaj wielu izolowanych agentów w jednym Gateway. Zobacz [Wielu agentów](
2. `match.guildId`
3. `match.teamId`
4. `match.accountId` (dokładne, bez peer/guild/team)
5. `match.accountId: "*"` (w całym kanale)
5. `match.accountId: "*"` (dla całego kanału)
6. Agent domyślny
W obrębie każdego poziomu wygrywa pierwszy pasujący wpis `bindings`.
Dla wpisów `type: "acp"` OpenClaw rozwiązuje według dokładnej tożsamości konwersacji (`match.channel` + konto + `match.peer.id`) i nie używa powyższej kolejności poziomów powiązań routingu.
Dla wpisów `type: "acp"` OpenClaw rozstrzyga według dokładnej tożsamości rozmowy (`match.channel` + konto + `match.peer.id`) i nie używa powyższej kolejności poziomów powiązań routingu.
### Profile dostępu dla agenta
### Profile dostępu dla agentów
<Accordion title="Pełny dostęp (bez piaskownicy)">
<Accordion title="Full access (no sandbox)">
```json5
{
@ -1061,7 +1078,7 @@ Dla wpisów `type: "acp"` OpenClaw rozwiązuje według dokładnej tożsamości k
</Accordion>
<Accordion title="Narzędzia tylko do odczytu + obszar roboczy">
<Accordion title="Read-only tools + workspace">
```json5
{
@ -1090,7 +1107,7 @@ Dla wpisów `type: "acp"` OpenClaw rozwiązuje według dokładnej tożsamości k
</Accordion>
<Accordion title="Brak dostępu do systemu plików (tylko wiadomości)">
<Accordion title="No filesystem access (messaging only)">
```json5
{
@ -1136,7 +1153,7 @@ Dla wpisów `type: "acp"` OpenClaw rozwiązuje według dokładnej tożsamości k
</Accordion>
Zobacz [Piaskownica i narzędzia wielu agentów](/pl/tools/multi-agent-sandbox-tools), aby poznać szczegóły pierwszeństwa.
Zobacz [Multi-Agent Sandbox & Tools](/pl/tools/multi-agent-sandbox-tools), aby poznać szczegóły pierwszeństwa.
---
@ -1186,37 +1203,37 @@ Zobacz [Piaskownica i narzędzia wielu agentów](/pl/tools/multi-agent-sandbox-t
}
```
<Accordion title="Szczegóły pól sesji">
<Accordion title="Session field details">
- **`scope`**: podstawowa strategia grupowania sesji dla kontekstów czatu grupowego.
- `per-sender` (domyślnie): każdy nadawca otrzymuje izolowaną sesję w kontekście kanału.
- `global`: wszyscy uczestnicy w kontekście kanału współdzielą jedną sesję (używaj tylko wtedy, gdy współdzielony kontekst jest zamierzony).
- **`dmScope`**: sposób grupowania wiadomości DM.
- `main`: wszystkie wiadomości DM współdzielą sesję główną.
- `per-peer`: izoluje według identyfikatora nadawcy między kanałami.
- `per-channel-peer`: izoluje według kanału i nadawcy (zalecane dla skrzynek odbiorczych wielu użytkowników).
- `per-account-channel-peer`: izoluje według konta, kanału i nadawcy (zalecane dla wielu kont).
- **`identityLinks`**: mapuje identyfikatory kanoniczne na peery z prefiksem dostawcy na potrzeby współdzielenia sesji między kanałami. Polecenia dockowania, takie jak `/dock_discord`, używają tej samej mapy, aby przełączyć trasę odpowiedzi aktywnej sesji na inny połączony peer kanału; zobacz [Dockowanie kanałów](/pl/concepts/channel-docking).
- **`reset`**: podstawowa polityka resetowania. `daily` resetuje o lokalnej godzinie `atHour`; `idle` resetuje po `idleMinutes`. Gdy skonfigurowano oba ustawienia, wygrywa to, które wygaśnie jako pierwsze. Świeżość resetu dziennego używa `sessionStartedAt` w wierszu sesji; świeżość resetu bezczynności używa `lastInteractionAt`. Zapisy w tle i zdarzenia systemowe, takie jak Heartbeat, wybudzenia Cron, powiadomienia exec i księgowanie Gateway, mogą aktualizować `updatedAt`, ale nie utrzymują świeżości sesji dziennych/bezczynności.
- **`resetByType`**: nadpisania dla poszczególnych typów (`direct`, `group`, `thread`). Starsze `dm` jest akceptowane jako alias `direct`.
- **`parentForkMaxTokens`**: maksymalna wartość `totalTokens` sesji nadrzędnej dozwolona przy tworzeniu rozwidlonej sesji wątku (domyślnie `100000`).
- Jeśli `totalTokens` sesji nadrzędnej przekracza tę wartość, OpenClaw uruchamia świeżą sesję wątku zamiast dziedziczyć historię transkryptu sesji nadrzędnej.
- Ustaw `0`, aby wyłączyć to zabezpieczenie i zawsze zezwalać na rozwidlanie z sesji nadrzędnej.
- **`mainKey`**: pole starszej wersji. Runtime zawsze używa `"main"` dla głównego zasobnika czatu bezpośredniego.
- **`agentToAgent.maxPingPongTurns`**: maksymalna liczba tur odpowiedzi zwrotnych między agentami podczas wymian agent-agent (liczba całkowita, zakres: `0`–`5`). `0` wyłącza łańcuch ping-pong.
- **`sendPolicy`**: dopasowuje według `channel`, `chatType` (`direct|group|channel`, ze starszym aliasem `dm`), `keyPrefix` lub `rawKeyPrefix`. Pierwsza odmowa wygrywa.
- **`maintenance`**: kontrola czyszczenia i retencji magazynu sesji.
- **`scope`**: podstawowa strategia grupowania sesji dla kontekstów czatów grupowych.
- `per-sender` (domyślnie): każdy nadawca otrzymuje odizolowaną sesję w kontekście kanału.
- `global`: wszyscy uczestnicy w kontekście kanału współdzielą jedną sesję (używaj tylko wtedy, gdy zamierzony jest współdzielony kontekst).
- **`dmScope`**: sposób grupowania wiadomości prywatnych.
- `main`: wszystkie wiadomości prywatne współdzielą sesję główną.
- `per-peer`: izoluj według identyfikatora nadawcy między kanałami.
- `per-channel-peer`: izoluj według kanału + nadawcy (zalecane dla skrzynek odbiorczych wielu użytkowników).
- `per-account-channel-peer`: izoluj według konta + kanału + nadawcy (zalecane dla wielu kont).
- **`identityLinks`**: mapuje identyfikatory kanoniczne na równorzędne identyfikatory z prefiksem dostawcy do współdzielenia sesji między kanałami. Polecenia dokowania, takie jak `/dock_discord`, używają tej samej mapy, aby przełączyć trasę odpowiedzi aktywnej sesji na inny połączony równorzędny identyfikator kanału; zobacz [Dokowanie kanałów](/pl/concepts/channel-docking).
- **`reset`**: podstawowa polityka resetowania. `daily` resetuje o lokalnej godzinie `atHour`; `idle` resetuje po `idleMinutes`. Gdy skonfigurowano oba ustawienia, wygrywa to, które wygaśnie jako pierwsze. Świeżość dziennego resetu używa pola `sessionStartedAt` wiersza sesji; świeżość resetu bezczynności używa `lastInteractionAt`. Zapisy w tle/zdarzeniach systemowych, takie jak Heartbeat, wybudzenia Cron, powiadomienia exec i czynności porządkowe Gateway, mogą aktualizować `updatedAt`, ale nie utrzymują świeżości sesji dziennych/bezczynnych.
- **`resetByType`**: nadpisania według typu (`direct`, `group`, `thread`). Starsze `dm` jest akceptowane jako alias dla `direct`.
- **`parentForkMaxTokens`**: maksymalna wartość `totalTokens` sesji nadrzędnej dozwolona podczas tworzenia sforkowanej sesji wątku (domyślnie `100000`).
- Jeśli `totalTokens` sesji nadrzędnej przekracza tę wartość, OpenClaw uruchamia świeżą sesję wątku zamiast dziedziczyć historię transkrypcji sesji nadrzędnej.
- Ustaw `0`, aby wyłączyć tę osłonę i zawsze zezwalać na forking z sesji nadrzędnej.
- **`mainKey`**: starsze pole. Środowisko uruchomieniowe zawsze używa `"main"` dla głównego zasobnika czatu bezpośredniego.
- **`agentToAgent.maxPingPongTurns`**: maksymalna liczba zwrotnych tur odpowiedzi między agentami podczas wymian między agentami (liczba całkowita, zakres: `0`–`5`). `0` wyłącza łańcuch ping-pong.
- **`sendPolicy`**: dopasowanie według `channel`, `chatType` (`direct|group|channel`, ze starszym aliasem `dm`), `keyPrefix` lub `rawKeyPrefix`. Pierwsza odmowa wygrywa.
- **`maintenance`**: kontrolki czyszczenia magazynu sesji + retencji.
- `mode`: `warn` emituje tylko ostrzeżenia; `enforce` stosuje czyszczenie.
- `pruneAfter`: próg wieku dla nieaktualnych wpisów (domyślnie `30d`).
- `maxEntries`: maksymalna liczba wpisów w `sessions.json` (domyślnie `500`). Runtime zapisuje czyszczenie wsadowe z niewielkim buforem wysokiego poziomu dla limitów produkcyjnych; `openclaw sessions cleanup --enforce` stosuje limit natychmiast.
- `maxEntries`: maksymalna liczba wpisów w `sessions.json` (domyślnie `500`). Środowisko uruchomieniowe zapisuje czyszczenie wsadowe z małym buforem wysokiego poziomu dla limitów o rozmiarze produkcyjnym; `openclaw sessions cleanup --enforce` stosuje limit natychmiast.
- `rotateBytes`: przestarzałe i ignorowane; `openclaw doctor --fix` usuwa je ze starszych konfiguracji.
- `resetArchiveRetention`: retencja archiwów transkryptów `*.reset.<timestamp>`. Domyślnie `pruneAfter`; ustaw `false`, aby wyłączyć.
- `maxDiskBytes`: opcjonalny budżet dyskowy katalogu sesji. W trybie `warn` rejestruje ostrzeżenia; w trybie `enforce` najpierw usuwa najstarsze artefakty/sesje.
- `highWaterBytes`: opcjonalny cel po czyszczeniu budżetu. Domyślnie `80%` z `maxDiskBytes`.
- **`threadBindings`**: globalne ustawienia domyślne dla funkcji sesji powiązanych z wątkiem.
- `enabled`: główny przełącznik domyślny (dostawcy mogą nadpisać; Discord używa `channels.discord.threadBindings.enabled`)
- `idleHours`: domyślne automatyczne odfokusowanie po bezczynności w godzinach (`0` wyłącza; dostawcy mogą nadpisać)
- `maxAgeHours`: domyślny twardy maksymalny wiek w godzinach (`0` wyłącza; dostawcy mogą nadpisać)
- `resetArchiveRetention`: retencja archiwów transkrypcji `*.reset.<timestamp>`. Domyślnie `pruneAfter`; ustaw `false`, aby wyłączyć.
- `maxDiskBytes`: opcjonalny budżet dysku katalogu sesji. W trybie `warn` zapisuje ostrzeżenia w logu; w trybie `enforce` najpierw usuwa najstarsze artefakty/sesje.
- `highWaterBytes`: opcjonalny cel po czyszczeniu budżetu. Domyślnie `80%` wartości `maxDiskBytes`.
- **`threadBindings`**: globalne wartości domyślne funkcji sesji powiązanych z wątkiem.
- `enabled`: główny przełącznik domyślny (dostawcy mogą nadpisywać; Discord używa `channels.discord.threadBindings.enabled`)
- `idleHours`: domyślne automatyczne odfokusowanie po bezczynności w godzinach (`0` wyłącza; dostawcy mogą nadpisywać)
- `maxAgeHours`: domyślny twardy maksymalny wiek w godzinach (`0` wyłącza; dostawcy mogą nadpisywać)
</Accordion>
@ -1254,38 +1271,38 @@ Zobacz [Piaskownica i narzędzia wielu agentów](/pl/tools/multi-agent-sandbox-t
### Prefiks odpowiedzi
Nadpisania dla kanału/konta: `channels.<channel>.responsePrefix`, `channels.<channel>.accounts.<id>.responsePrefix`.
Nadpisania według kanału/konta: `channels.<channel>.responsePrefix`, `channels.<channel>.accounts.<id>.responsePrefix`.
Rozstrzyganie (najbardziej szczegółowe wygrywa): konto → kanał → globalne. `""` wyłącza i zatrzymuje kaskadę. `"auto"` wyprowadza `[{identity.name}]`.
Rozstrzyganie (najbardziej szczegółowe wygrywa): konto → kanał → globalne. `""` wyłącza i zatrzymuje kaskadę. `"auto"` tworzy `[{identity.name}]`.
**Zmienne szablonu:**
| Zmienna | Opis | Przykład |
| ----------------- | ---------------------------- | --------------------------- |
| `{model}` | Krótka nazwa modelu | `claude-opus-4-6` |
| `{modelFull}` | Pełny identyfikator modelu | `anthropic/claude-opus-4-6` |
| `{provider}` | Nazwa dostawcy | `anthropic` |
| `{thinkingLevel}` | Bieżący poziom myślenia | `high`, `low`, `off` |
| `{identity.name}` | Nazwa tożsamości agenta | (tak samo jak `"auto"`) |
| Zmienna | Opis | Przykład |
| ----------------- | -------------------------- | --------------------------- |
| `{model}` | Krótka nazwa modelu | `claude-opus-4-6` |
| `{modelFull}` | Pełny identyfikator modelu | `anthropic/claude-opus-4-6` |
| `{provider}` | Nazwa dostawcy | `anthropic` |
| `{thinkingLevel}` | Bieżący poziom myślenia | `high`, `low`, `off` |
| `{identity.name}` | Nazwa tożsamości agenta | (tak samo jak `"auto"`) |
Wielkość liter w zmiennych nie ma znaczenia. `{think}` jest aliasem `{thinkingLevel}`.
Zmienne nie rozróżniają wielkości liter. `{think}` jest aliasem dla `{thinkingLevel}`.
### Reakcja potwierdzenia
- Domyślnie używa `identity.emoji` aktywnego agenta, w przeciwnym razie `"👀"`. Ustaw `""`, aby wyłączyć.
- Nadpisania dla kanału: `channels.<channel>.ackReaction`, `channels.<channel>.accounts.<id>.ackReaction`.
- Kolejność rozstrzygania: konto → kanał → `messages.ackReaction` → rezerwowo tożsamość.
- Nadpisania według kanału: `channels.<channel>.ackReaction`, `channels.<channel>.accounts.<id>.ackReaction`.
- Kolejność rozstrzygania: konto → kanał → `messages.ackReaction` → awaryjna wartość tożsamości.
- Zakres: `group-mentions` (domyślnie), `group-all`, `direct`, `all`.
- `removeAckAfterReply`: usuwa potwierdzenie po odpowiedzi w kanałach obsługujących reakcje, takich jak Slack, Discord, Telegram, WhatsApp i BlueBubbles.
- `removeAckAfterReply`: usuwa potwierdzenie po odpowiedzi na kanałach obsługujących reakcje, takich jak Slack, Discord, Telegram, WhatsApp i BlueBubbles.
- `messages.statusReactions.enabled`: włącza reakcje statusu cyklu życia w Slack, Discord i Telegram.
W Slack i Discord brak ustawienia pozostawia reakcje statusu włączone, gdy reakcje potwierdzenia są aktywne.
W Telegram ustaw to jawnie na `true`, aby włączyć reakcje statusu cyklu życia.
W Telegram ustaw jawnie na `true`, aby włączyć reakcje statusu cyklu życia.
### Debounce przychodzących wiadomości
Grupuje szybkie wiadomości tekstowe od tego samego nadawcy w jedną turę agenta. Media/załączniki opróżniają kolejkę natychmiast. Polecenia sterujące omijają debounce.
Grupuje szybkie wiadomości wyłącznie tekstowe od tego samego nadawcy w jedną turę agenta. Multimedia/załączniki opróżniają kolejkę natychmiast. Polecenia sterujące omijają debounce.
### TTS (zamiana tekstu na mowę)
### TTS (tekst na mowę)
```json5
{
@ -1333,19 +1350,19 @@ Grupuje szybkie wiadomości tekstowe od tego samego nadawcy w jedną turę agent
}
```
- `auto` kontroluje domyślny tryb auto-TTS: `off`, `always`, `inbound` lub `tagged`. `/tts on|off` może nadpisać preferencje lokalne, a `/tts status` pokazuje efektywny stan.
- `auto` kontroluje domyślny automatyczny tryb TTS: `off`, `always`, `inbound` albo `tagged`. `/tts on|off` może nadpisać lokalne preferencje, a `/tts status` pokazuje efektywny stan.
- `summaryModel` nadpisuje `agents.defaults.model.primary` dla automatycznego podsumowania.
- `modelOverrides` jest domyślnie włączone; `modelOverrides.allowProvider` domyślnie ma wartość `false` (wymaga jawnego włączenia).
- Klucze API używają rezerwowo `ELEVENLABS_API_KEY`/`XI_API_KEY` i `OPENAI_API_KEY`.
- Dołączani dostawcy mowy są własnością Pluginów. Jeśli ustawiono `plugins.allow`, uwzględnij każdy Plugin dostawcy TTS, którego chcesz użyć, na przykład `microsoft` dla Edge TTS. Starszy identyfikator dostawcy `edge` jest akceptowany jako alias `microsoft`.
- `modelOverrides` jest domyślnie włączone; `modelOverrides.allowProvider` domyślnie ma wartość `false` (wymaga świadomego włączenia).
- Klucze API używają awaryjnie `ELEVENLABS_API_KEY`/`XI_API_KEY` oraz `OPENAI_API_KEY`.
- Dołączeni dostawcy mowy są zarządzani przez Pluginy. Jeśli ustawiono `plugins.allow`, uwzględnij każdy Plugin dostawcy TTS, którego chcesz używać, na przykład `microsoft` dla Edge TTS. Starszy identyfikator dostawcy `edge` jest akceptowany jako alias dla `microsoft`.
- `providers.openai.baseUrl` nadpisuje punkt końcowy OpenAI TTS. Kolejność rozstrzygania to konfiguracja, następnie `OPENAI_TTS_BASE_URL`, następnie `https://api.openai.com/v1`.
- Gdy `providers.openai.baseUrl` wskazuje punkt końcowy inny niż OpenAI, OpenClaw traktuje go jako serwer TTS zgodny z OpenAI i łagodzi walidację modelu/głosu.
- Gdy `providers.openai.baseUrl` wskazuje punkt końcowy inny niż OpenAI, OpenClaw traktuje go jako serwer TTS zgodny z OpenAI i rozluźnia walidację modelu/głosu.
---
## Talk
Ustawienia domyślne trybu Talk (macOS/iOS/Android).
Wartości domyślne trybu Talk (macOS/iOS/Android).
```json5
{
@ -1374,21 +1391,21 @@ Ustawienia domyślne trybu Talk (macOS/iOS/Android).
}
```
- `talk.provider` musi pasować do klucza w `talk.providers`, gdy skonfigurowano wielu dostawców Talk.
- Starsze płaskie klucze Talk (`talk.voiceId`, `talk.voiceAliases`, `talk.modelId`, `talk.outputFormat`, `talk.apiKey`) służą tylko zgodności i są automatycznie migrowane do `talk.providers.<provider>`.
- Identyfikatory głosów używają rezerwowo `ELEVENLABS_VOICE_ID` lub `SAG_VOICE_ID`.
- `providers.*.apiKey` akceptuje ciągi jawnego tekstu lub obiekty SecretRef.
- Rezerwowe `ELEVENLABS_API_KEY` ma zastosowanie tylko wtedy, gdy nie skonfigurowano klucza API Talk.
- `talk.provider` musi odpowiadać kluczowi w `talk.providers`, gdy skonfigurowano wielu dostawców Talk.
- Starsze płaskie klucze Talk (`talk.voiceId`, `talk.voiceAliases`, `talk.modelId`, `talk.outputFormat`, `talk.apiKey`) służą tylko do zgodności i są automatycznie migrowane do `talk.providers.<provider>`.
- Identyfikatory głosów używają awaryjnie `ELEVENLABS_VOICE_ID` albo `SAG_VOICE_ID`.
- `providers.*.apiKey` akceptuje ciągi w postaci zwykłego tekstu albo obiekty SecretRef.
- Awaryjna wartość `ELEVENLABS_API_KEY` ma zastosowanie tylko wtedy, gdy nie skonfigurowano klucza API Talk.
- `providers.*.voiceAliases` pozwala dyrektywom Talk używać przyjaznych nazw.
- `providers.mlx.modelId` wybiera repozytorium Hugging Face używane przez lokalny pomocnik MLX w macOS. Jeśli pominięto, macOS używa `mlx-community/Soprano-80M-bf16`.
- Odtwarzanie MLX w macOS działa przez dołączony pomocnik `openclaw-mlx-tts`, gdy jest obecny, albo przez plik wykonywalny w `PATH`; `OPENCLAW_MLX_TTS_BIN` nadpisuje ścieżkę pomocnika na potrzeby programowania.
- `speechLocale` ustawia identyfikator ustawień regionalnych BCP 47 używany przez rozpoznawanie mowy Talk w iOS/macOS. Pozostaw nieustawione, aby użyć domyślnych ustawień urządzenia.
- `silenceTimeoutMs` kontroluje, jak długo tryb Talk czeka po ciszy użytkownika, zanim wyśle transkrypt. Brak ustawienia zachowuje domyślne okno pauzy platformy (`700 ms on macOS and Android, 900 ms on iOS`).
- `providers.mlx.modelId` wybiera repozytorium Hugging Face używane przez lokalnego pomocnika MLX na macOS. Jeśli pominięte, macOS używa `mlx-community/Soprano-80M-bf16`.
- Odtwarzanie MLX w macOS działa przez dołączonego pomocnika `openclaw-mlx-tts`, gdy jest obecny, albo przez plik wykonywalny w `PATH`; `OPENCLAW_MLX_TTS_BIN` nadpisuje ścieżkę pomocnika na potrzeby programowania.
- `speechLocale` ustawia identyfikator ustawień regionalnych BCP 47 używany przez rozpoznawanie mowy Talk w iOS/macOS. Pozostaw nieustawione, aby użyć wartości domyślnej urządzenia.
- `silenceTimeoutMs` kontroluje, jak długo tryb Talk czeka po ciszy użytkownika, zanim wyśle transkrypcję. Brak ustawienia zachowuje domyślne okno pauzy platformy (`700 ms na macOS i Android, 900 ms na iOS`).
---
## Powiązane
- [Informacje referencyjne konfiguracji](/pl/gateway/configuration-reference) — wszystkie inne klucze konfiguracji
- [Dokumentacja konfiguracji](/pl/gateway/configuration-reference) — wszystkie pozostałe klucze konfiguracji
- [Konfiguracja](/pl/gateway/configuration) — typowe zadania i szybka konfiguracja
- [Przykłady konfiguracji](/pl/gateway/configuration-examples)

324
docs/pl/gateway/config-channels.md
View File

@ -1,56 +1,56 @@
---
read_when:
- Konfigurowanie Plugin kanału (uwierzytelnianie, kontrola dostępu, wiele kont)
- Konfigurowanie Plugin kanału (uwierzytelnianie, kontrola dostępu, obsługa wielu kont)
- Rozwiązywanie problemów z kluczami konfiguracji dla poszczególnych kanałów
- Audytowanie zasad DM, zasad grupowych lub bramkowania wzmianek
- Audyt zasad DM, zasad grup lub bramkowania wzmianek
summary: 'Konfiguracja kanałów: kontrola dostępu, parowanie i klucze dla poszczególnych kanałów w Slack, Discord, Telegram, WhatsApp, Matrix, iMessage i innych'
title: Konfiguracja — kanały
x-i18n:
generated_at: "2026-04-30T16:28:41Z"
generated_at: "2026-05-01T09:58:38Z"
model: gpt-5.5
provider: openai
source_hash: aba14cb43e1fe914cc7c03f41bed1b5915cc6b2ad8e0f1d47f58b7e98c1b3915
source_hash: ce1571d51e026182d49b935780a986780a90b05afc0acca027b2541b80a1aac2
source_path: gateway/config-channels.md
workflow: 16
---
Klucze konfiguracji poszczególnych kanałów pod `channels.*`. Obejmuje dostęp do DM i grup,
konfiguracje wielu kont, bramkowanie wzmiankami oraz klucze poszczególnych kanałów dla Slack, Discord,
Telegram, WhatsApp, Matrix, iMessage i innych dołączonych Plugin kanałów.
Konfiguracja kluczy dla poszczególnych kanałów w `channels.*`. Obejmuje dostęp DM i grupowy,
konfiguracje wielu kont, bramkowanie wzmianek oraz klucze per kanał dla Slack, Discord,
Telegram, WhatsApp, Matrix, iMessage i innych dołączonych pluginów kanałów.
Informacje o agentach, narzędziach, środowisku uruchomieniowym Gateway i innych kluczach najwyższego poziomu znajdziesz w
[Dokumentacji konfiguracji](/pl/gateway/configuration-reference).
Dla agentów, narzędzi, środowiska uruchomieniowego Gateway i innych kluczy najwyższego poziomu zobacz
[Dokumentację konfiguracji](/pl/gateway/configuration-reference).
## Kanały
Każdy kanał uruchamia się automatycznie, gdy istnieje jego sekcja konfiguracji (chyba że ustawiono `enabled: false`).
### Dostęp do DM i grup
### Dostęp DM i grupowy
Wszystkie kanały obsługują zasady DM i zasady grup:
Wszystkie kanały obsługują zasady DM i zasady grupowe:
| Zasada DM | Zachowanie |
| ------------------- | --------------------------------------------------------------- |
| `pairing` (domyślna) | Nieznani nadawcy otrzymują jednorazowy kod parowania; właściciel musi zatwierdzić |
| `allowlist` | Tylko nadawcy w `allowFrom` (lub sparowanym magazynie dozwolonych) |
| Zasada DM | Zachowanie |
| ------------------- | -------------------------------------------------------------- |
| `pairing` (domyślnie) | Nieznani nadawcy otrzymują jednorazowy kod parowania; właściciel musi zatwierdzić |
| `allowlist` | Tylko nadawcy w `allowFrom` (albo w sparowanym magazynie zezwoleń) |
| `open` | Zezwalaj na wszystkie przychodzące DM (wymaga `allowFrom: ["*"]`) |
| `disabled` | Ignoruj wszystkie przychodzące DM |
| `disabled` | Ignoruj wszystkie przychodzące DM |
| Zasada grup | Zachowanie |
| Zasada grupowa | Zachowanie |
| --------------------- | ------------------------------------------------------ |
| `allowlist` (domyślna) | Tylko grupy pasujące do skonfigurowanej listy dozwolonych |
| `open` | Pomijaj listy dozwolonych grup (bramkowanie wzmiankami nadal obowiązuje) |
| `disabled` | Blokuj wszystkie wiadomości z grup/pokoi |
| `allowlist` (domyślnie) | Tylko grupy pasujące do skonfigurowanej listy zezwoleń |
| `open` | Pomijaj grupowe listy zezwoleń (bramkowanie wzmianek nadal obowiązuje) |
| `disabled` | Blokuj wszystkie wiadomości grupowe/pokojowe |
<Note>
`channels.defaults.groupPolicy` ustawia wartość domyślną, gdy `groupPolicy` dostawcy nie jest ustawione.
Kody parowania wygasają po 1 godzinie. Oczekujące żądania parowania DM są ograniczone do **3 na kanał**.
Jeśli blok dostawcy jest całkowicie nieobecny (brak `channels.<provider>`), zasada grup w czasie wykonywania wraca do `allowlist` (fail-closed) z ostrzeżeniem przy starcie.
Jeśli blok dostawcy całkowicie nie istnieje (brak `channels.<provider>`), zasada grupowa środowiska uruchomieniowego wraca do `allowlist` (fail-closed) z ostrzeżeniem przy starcie.
</Note>
### Nadpisania modelu kanału
Użyj `channels.modelByChannel`, aby przypiąć konkretne identyfikatory kanałów do modelu. Wartości akceptują `provider/model` lub skonfigurowane aliasy modeli. Mapowanie kanału obowiązuje, gdy sesja nie ma już nadpisania modelu (na przykład ustawionego przez `/model`).
Użyj `channels.modelByChannel`, aby przypiąć konkretne identyfikatory kanałów do modelu. Wartości akceptują `provider/model` albo skonfigurowane aliasy modeli. Mapowanie kanałów ma zastosowanie, gdy sesja nie ma już nadpisania modelu (na przykład ustawionego przez `/model`).
```json5
{
@ -73,7 +73,7 @@ Użyj `channels.modelByChannel`, aby przypiąć konkretne identyfikatory kanał
### Domyślne ustawienia kanałów i Heartbeat
Użyj `channels.defaults` do współdzielonego zachowania zasad grup i Heartbeat między dostawcami:
Użyj `channels.defaults` do współdzielonych zasad grupowych i zachowania Heartbeat u dostawców:
```json5
{
@ -91,11 +91,11 @@ Użyj `channels.defaults` do współdzielonego zachowania zasad grup i Heartbeat
}
```
- `channels.defaults.groupPolicy`: zapasowa zasada grup, gdy `groupPolicy` na poziomie dostawcy nie jest ustawiona.
- `channels.defaults.contextVisibility`: domyślny tryb widoczności dodatkowego kontekstu dla wszystkich kanałów. Wartości: `all` (domyślnie, uwzględnia cały cytowany/wątkowy/historyczny kontekst), `allowlist` (uwzględnia tylko kontekst od nadawców z listy dozwolonych), `allowlist_quote` (tak samo jak lista dozwolonych, ale zachowuje jawny kontekst cytatu/odpowiedzi). Nadpisanie dla kanału: `channels.<channel>.contextVisibility`.
- `channels.defaults.heartbeat.showOk`: uwzględnia zdrowe statusy kanałów w wyjściu Heartbeat.
- `channels.defaults.heartbeat.showAlerts`: uwzględnia statusy zdegradowane/błędów w wyjściu Heartbeat.
- `channels.defaults.heartbeat.useIndicator`: renderuje zwarte wyjście Heartbeat w stylu wskaźnika.
- `channels.defaults.groupPolicy`: zastępcza zasada grupowa, gdy `groupPolicy` na poziomie dostawcy nie jest ustawione.
- `channels.defaults.contextVisibility`: domyślny tryb widoczności dodatkowego kontekstu dla wszystkich kanałów. Wartości: `all` (domyślnie, dołącz cały kontekst cytatów/wątków/historii), `allowlist` (dołączaj tylko kontekst od nadawców z listy zezwoleń), `allowlist_quote` (tak samo jak allowlist, ale zachowaj jawny kontekst cytatu/odpowiedzi). Nadpisanie per kanał: `channels.<channel>.contextVisibility`.
- `channels.defaults.heartbeat.showOk`: uwzględniaj zdrowe statusy kanałów w wyjściu Heartbeat.
- `channels.defaults.heartbeat.showAlerts`: uwzględniaj statusy zdegradowane/błędów w wyjściu Heartbeat.
- `channels.defaults.heartbeat.useIndicator`: renderuj kompaktowe wyjście Heartbeat w stylu wskaźnika.
### WhatsApp
@ -158,9 +158,9 @@ WhatsApp działa przez kanał web Gateway (Baileys Web). Uruchamia się automaty
```
- Polecenia wychodzące domyślnie używają konta `default`, jeśli istnieje; w przeciwnym razie pierwszego skonfigurowanego identyfikatora konta (posortowanego).
- Opcjonalne `channels.whatsapp.defaultAccount` nadpisuje ten wybór domyślnego konta zapasowego, gdy pasuje do skonfigurowanego identyfikatora konta.
- Opcjonalne `channels.whatsapp.defaultAccount` nadpisuje ten domyślny wybór konta zastępczego, gdy pasuje do skonfigurowanego identyfikatora konta.
- Starszy katalog uwierzytelniania Baileys dla jednego konta jest migrowany przez `openclaw doctor` do `whatsapp/default`.
- Nadpisania dla konta: `channels.whatsapp.accounts.<id>.sendReadReceipts`, `channels.whatsapp.accounts.<id>.dmPolicy`, `channels.whatsapp.accounts.<id>.allowFrom`.
- Nadpisania per konto: `channels.whatsapp.accounts.<id>.sendReadReceipts`, `channels.whatsapp.accounts.<id>.dmPolicy`, `channels.whatsapp.accounts.<id>.allowFrom`.
</Accordion>
@ -219,10 +219,10 @@ WhatsApp działa przez kanał web Gateway (Baileys Web). Uruchamia się automaty
}
```
- Token bota: `channels.telegram.botToken` lub `channels.telegram.tokenFile` (tylko zwykły plik; dowiązania symboliczne odrzucane), z `TELEGRAM_BOT_TOKEN` jako wartością zapasową dla konta domyślnego.
- `apiRoot` to wyłącznie główny adres Telegram Bot API. Użyj `https://api.telegram.org` albo własnego hostowanego/proxy głównego adresu, a nie `https://api.telegram.org/bot<TOKEN>`; `openclaw doctor --fix` usuwa przypadkowy końcowy sufiks `/bot<TOKEN>`.
- Opcjonalne `channels.telegram.defaultAccount` nadpisuje wybór konta domyślnego, gdy pasuje do skonfigurowanego identyfikatora konta.
- W konfiguracjach wielu kont (co najmniej 2 identyfikatory kont) ustaw jawne konto domyślne (`channels.telegram.defaultAccount` lub `channels.telegram.accounts.default`), aby uniknąć routingu zapasowego; `openclaw doctor` ostrzega, gdy tego brakuje albo jest nieprawidłowe.
- Token bota: `channels.telegram.botToken` albo `channels.telegram.tokenFile` (tylko zwykły plik; symlinki odrzucane), z `TELEGRAM_BOT_TOKEN` jako zastępczą wartością dla konta domyślnego.
- `apiRoot` to wyłącznie katalog główny Telegram Bot API. Użyj `https://api.telegram.org` albo własnego hostowanego/proxy katalogu głównego, nie `https://api.telegram.org/bot<TOKEN>`; `openclaw doctor --fix` usuwa przypadkowy końcowy sufiks `/bot<TOKEN>`.
- Opcjonalne `channels.telegram.defaultAccount` nadpisuje domyślny wybór konta, gdy pasuje do skonfigurowanego identyfikatora konta.
- W konfiguracjach wielu kont (2+ identyfikatory kont) ustaw jawne domyślne (`channels.telegram.defaultAccount` albo `channels.telegram.accounts.default`), aby uniknąć trasowania zastępczego; `openclaw doctor` ostrzega, gdy tego brakuje albo jest nieprawidłowe.
- `configWrites: false` blokuje zapisy konfiguracji inicjowane przez Telegram (migracje identyfikatorów supergrup, `/config set|unset`).
- Wpisy najwyższego poziomu `bindings[]` z `type: "acp"` konfigurują trwałe powiązania ACP dla tematów forum (użyj kanonicznego `chatId:topic:topicId` w `match.peer.id`). Semantyka pól jest współdzielona w [Agentach ACP](/pl/tools/acp-agents#channel-specific-settings).
- Podglądy strumieni Telegram używają `sendMessage` + `editMessageText` (działa w czatach bezpośrednich i grupowych).
@ -328,35 +328,35 @@ WhatsApp działa przez kanał web Gateway (Baileys Web). Uruchamia się automaty
}
```
- Token: `channels.discord.token`, z `DISCORD_BOT_TOKEN` jako wartością zapasową dla konta domyślnego.
- Bezpośrednie wywołania wychodzące, które podają jawny Discord `token`, używają tego tokena dla wywołania; ustawienia ponawiania/polityki konta nadal pochodzą z wybranego konta w aktywnej migawce środowiska uruchomieniowego.
- Opcjonalne `channels.discord.defaultAccount` nadpisuje wybór konta domyślnego, gdy pasuje do skonfigurowanego identyfikatora konta.
- Użyj `user:<id>` (DM) albo `channel:<id>` (kanał gildii) dla celów dostarczania; same numeryczne identyfikatory są odrzucane.
- Slugi gildii są pisane małymi literami, ze spacjami zastąpionymi przez `-`; klucze kanałów używają nazwy w postaci sluga (bez `#`). Preferuj identyfikatory gildii.
- Wiadomości autorstwa botów są domyślnie ignorowane. `allowBots: true` je włącza; użyj `allowBots: "mentions"`, aby akceptować tylko wiadomości botów, które wspominają bota (własne wiadomości nadal filtrowane).
- `channels.discord.guilds.<id>.ignoreOtherMentions` (oraz nadpisania kanałów) odrzuca wiadomości, które wspominają innego użytkownika lub rolę, ale nie bota (z wyłączeniem @everyone/@here).
- `maxLinesPerMessage` (domyślnie 17) dzieli wysokie wiadomości nawet wtedy, gdy mają mniej niż 2000 znaków.
- `channels.discord.threadBindings` steruje trasowaniem powiązanym z wątkami Discord:
- `enabled`: nadpisanie Discord dla funkcji sesji powiązanych z wątkiem (`/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age` oraz powiązane dostarczanie/trasowanie)
- `idleHours`: nadpisanie Discord dla automatycznego cofania fokusu po nieaktywności w godzinach (`0` wyłącza)
- Token: `channels.discord.token`, z `DISCORD_BOT_TOKEN` jako wartością zastępczą dla konta domyślnego.
- Bezpośrednie połączenia wychodzące, które podają jawny `token` Discord, używają tego tokena do wywołania; ustawienia ponawiania/polityki konta nadal pochodzą z wybranego konta w aktywnej migawce runtime.
- Opcjonalne `channels.discord.defaultAccount` zastępuje wybór konta domyślnego, gdy pasuje do skonfigurowanego identyfikatora konta.
- Używaj `user:<id>` (DM) lub `channel:<id>` (kanał gildii) dla celów dostarczania; same identyfikatory numeryczne są odrzucane.
- Slugi gildii są pisane małymi literami, a spacje zastępuje się `-`; klucze kanałów używają nazwy w formie sluga (bez `#`). Preferuj identyfikatory gildii.
- Wiadomości autorstwa botów są domyślnie ignorowane. `allowBots: true` je włącza; użyj `allowBots: "mentions"`, aby akceptować tylko wiadomości botów, które wzmiankują bota (własne wiadomości nadal są filtrowane).
- `channels.discord.guilds.<id>.ignoreOtherMentions` (oraz nadpisania kanałów) odrzuca wiadomości, które wzmiankują innego użytkownika lub rolę, ale nie bota (z wyłączeniem @everyone/@here).
- `maxLinesPerMessage` (domyślnie 17) dzieli wysokie wiadomości nawet wtedy, gdy mają poniżej 2000 znaków.
- `channels.discord.threadBindings` kontroluje routing powiązany z wątkami Discord:
- `enabled`: nadpisanie Discord dla funkcji sesji powiązanych z wątkiem (`/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age` oraz powiązane dostarczanie/routing)
- `idleHours`: nadpisanie Discord dla automatycznego cofnięcia fokusu po bezczynności w godzinach (`0` wyłącza)
- `maxAgeHours`: nadpisanie Discord dla twardego maksymalnego wieku w godzinach (`0` wyłącza)
- `spawnSubagentSessions`: przełącznik opt-in dla automatycznego tworzenia/powiązywania wątku przez `sessions_spawn({ thread: true })`
- Wpisy najwyższego poziomu `bindings[]` z `type: "acp"` konfigurują trwałe powiązania ACP dla kanałów i wątków (użyj identyfikatora kanału/wątku w `match.peer.id`). Semantyka pól jest wspólna w [Agenci ACP](/pl/tools/acp-agents#channel-specific-settings).
- `spawnSubagentSessions`: przełącznik opt-in dla automatycznego tworzenia/powiązania wątku przez `sessions_spawn({ thread: true })`
- Wpisy najwyższego poziomu `bindings[]` z `type: "acp"` konfigurują trwałe powiązania ACP dla kanałów i wątków (użyj identyfikatora kanału/wątku w `match.peer.id`). Semantyka pól jest wspólna w [Agentach ACP](/pl/tools/acp-agents#channel-specific-settings).
- `channels.discord.ui.components.accentColor` ustawia kolor akcentu dla kontenerów komponentów Discord v2.
- `channels.discord.voice` włącza rozmowy w kanałach głosowych Discord oraz opcjonalne automatyczne dołączanie i nadpisania LLM + TTS.
- `channels.discord.voice.model` opcjonalnie nadpisuje model LLM używany do odpowiedzi w kanałach głosowych Discord.
- `channels.discord.voice` włącza rozmowy na kanałach głosowych Discord oraz opcjonalne automatyczne dołączanie + nadpisania LLM + TTS.
- `channels.discord.voice.model` opcjonalnie nadpisuje model LLM używany do odpowiedzi na kanałach głosowych Discord.
- `channels.discord.voice.daveEncryption` i `channels.discord.voice.decryptionFailureTolerance` są przekazywane do opcji DAVE `@discordjs/voice` (domyślnie `true` i `24`).
- OpenClaw dodatkowo próbuje odzyskiwać odbiór głosu przez opuszczenie sesji głosowej i ponowne dołączenie do niej po powtarzających się błędach odszyfrowania.
- `channels.discord.streaming` jest kanonicznym kluczem trybu strumieniowania. Starsze wartości `streamMode` oraz logiczne `streaming` są automatycznie migrowane.
- `channels.discord.autoPresence` mapuje dostępność środowiska uruchomieniowego na obecność bota (healthy => online, degraded => idle, exhausted => dnd) i pozwala na opcjonalne nadpisania tekstu statusu.
- `channels.discord.dangerouslyAllowNameMatching` ponownie włącza zmienne dopasowywanie nazwy/tagu (tryb zgodności break-glass).
- `channels.discord.execApprovals`: natywne dla Discord dostarczanie zatwierdzeń exec oraz autoryzacja zatwierdzających.
- `enabled`: `true`, `false` albo `"auto"` (domyślnie). W trybie automatycznym zatwierdzenia exec aktywują się, gdy zatwierdzających można rozwiązać z `approvers` albo `commands.ownerAllowFrom`.
- `approvers`: identyfikatory użytkowników Discord uprawnionych do zatwierdzania żądań exec. Gdy pominięte, używa zapasowo `commands.ownerAllowFrom`.
- OpenClaw dodatkowo próbuje odzyskać odbiór głosu przez opuszczenie sesji głosowej i ponowne dołączenie po powtarzających się błędach odszyfrowywania.
- `channels.discord.streaming` to kanoniczny klucz trybu strumienia. Starsze wartości `streamMode` oraz boolowskie `streaming` są automatycznie migrowane.
- `channels.discord.autoPresence` mapuje dostępność runtime na obecność bota (healthy => online, degraded => idle, exhausted => dnd) i pozwala na opcjonalne nadpisania tekstu statusu.
- `channels.discord.dangerouslyAllowNameMatching` ponownie włącza zmienne dopasowywanie nazwy/tagu (tryb zgodności awaryjnej).
- `channels.discord.execApprovals`: natywne dla Discord dostarczanie zatwierdzeń exec i autoryzacja zatwierdzających.
- `enabled`: `true`, `false` lub `"auto"` (domyślnie). W trybie automatycznym zatwierdzenia exec aktywują się, gdy zatwierdzających da się rozpoznać z `approvers` lub `commands.ownerAllowFrom`.
- `approvers`: identyfikatory użytkowników Discord uprawnionych do zatwierdzania żądań exec. Gdy pominięte, używa zastępczo `commands.ownerAllowFrom`.
- `agentFilter`: opcjonalna lista dozwolonych identyfikatorów agentów. Pomiń, aby przekazywać zatwierdzenia dla wszystkich agentów.
- `sessionFilter`: opcjonalne wzorce kluczy sesji (podciąg albo regex).
- `target`: gdzie wysyłać monity zatwierdzenia. `"dm"` (domyślnie) wysyła do DM zatwierdzających, `"channel"` wysyła do kanału źródłowego, `"both"` wysyła do obu. Gdy cel zawiera `"channel"`, przyciski mogą być używane tylko przez rozwiązanych zatwierdzających.
- `cleanupAfterResolve`: gdy `true`, usuwa DM zatwierdzeń po zatwierdzeniu, odmowie albo przekroczeniu czasu.
- `sessionFilter`: opcjonalne wzorce kluczy sesji (podciąg lub regex).
- `target`: gdzie wysyłać monity o zatwierdzenie. `"dm"` (domyślnie) wysyła do DM zatwierdzającego, `"channel"` wysyła do kanału źródłowego, `"both"` wysyła do obu. Gdy target zawiera `"channel"`, przycisków mogą używać tylko rozpoznani zatwierdzający.
- `cleanupAfterResolve`: gdy `true`, usuwa DM z zatwierdzeniem po zatwierdzeniu, odmowie lub przekroczeniu limitu czasu.
**Tryby powiadomień o reakcjach:** `off` (brak), `own` (wiadomości bota, domyślnie), `all` (wszystkie wiadomości), `allowlist` (z `guilds.<id>.users` dla wszystkich wiadomości).
@ -389,11 +389,11 @@ WhatsApp działa przez kanał web Gateway (Baileys Web). Uruchamia się automaty
}
```
- JSON konta usługi: wbudowany (`serviceAccount`) albo oparty na pliku (`serviceAccountFile`).
- SecretRef konta usługi jest również obsługiwany (`serviceAccountRef`).
- Wartości zapasowe env: `GOOGLE_CHAT_SERVICE_ACCOUNT` albo `GOOGLE_CHAT_SERVICE_ACCOUNT_FILE`.
- Użyj `spaces/<spaceId>` albo `users/<userId>` dla celów dostarczania.
- `channels.googlechat.dangerouslyAllowNameMatching` ponownie włącza zmienne dopasowywanie podmiotu e-mail (tryb zgodności break-glass).
- JSON konta usługi: inline (`serviceAccount`) lub oparty na pliku (`serviceAccountFile`).
- Obsługiwany jest też SecretRef konta usługi (`serviceAccountRef`).
- Wartości zastępcze env: `GOOGLE_CHAT_SERVICE_ACCOUNT` lub `GOOGLE_CHAT_SERVICE_ACCOUNT_FILE`.
- Używaj `spaces/<spaceId>` lub `users/<userId>` dla celów dostarczania.
- `channels.googlechat.dangerouslyAllowNameMatching` ponownie włącza zmienne dopasowywanie principal e-mail (tryb zgodności awaryjnej).
### Slack
@ -465,44 +465,44 @@ WhatsApp działa przez kanał web Gateway (Baileys Web). Uruchamia się automaty
}
```
- **Tryb Socket** wymaga zarówno `botToken`, jak i `appToken` (`SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN` jako zapasowa wartość env dla konta domyślnego).
- **Tryb HTTP** wymaga `botToken` oraz `signingSecret` (w katalogu głównym albo dla konta).
- `socketMode` przekazuje strojenie transportu Slack SDK Socket Mode do publicznego API odbiornika Bolt. Używaj go tylko podczas badania przekroczeń czasu ping/pong albo nieaktualnego zachowania websocket.
- **Tryb Socket** wymaga zarówno `botToken`, jak i `appToken` (`SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN` jako wartość zastępcza env dla konta domyślnego).
- **Tryb HTTP** wymaga `botToken` oraz `signingSecret` (na poziomie root lub per konto).
- `socketMode` przekazuje strojenie transportu Socket Mode Slack SDK do publicznego API odbiornika Bolt. Używaj tego tylko podczas badania limitów czasu ping/pong lub nieaktualnego zachowania websocketu.
- `botToken`, `appToken`, `signingSecret` i `userToken` akceptują jawne
ciągi znaków albo obiekty SecretRef.
- Migawki kont Slack ujawniają pola źródła/statusu dla poszczególnych poświadczeń, takie jak
`botTokenSource`, `botTokenStatus`, `appTokenStatus` oraz, w trybie HTTP,
ciągi znaków lub obiekty SecretRef.
- Migawki kont Slack udostępniają pola źródła/statusu dla poszczególnych poświadczeń, takie jak
`botTokenSource`, `botTokenStatus`, `appTokenStatus`, a w trybie HTTP
`signingSecretStatus`. `configured_unavailable` oznacza, że konto jest
skonfigurowane przez SecretRef, ale bieżąca ścieżka polecenia/środowiska uruchomieniowego nie mogła
rozwiązać wartości sekretu.
skonfigurowane przez SecretRef, ale bieżąca ścieżka polecenia/runtime nie mogła
rozpoznać wartości sekretu.
- `configWrites: false` blokuje zapisy konfiguracji inicjowane przez Slack.
- Opcjonalne `channels.slack.defaultAccount` nadpisuje wybór konta domyślnego, gdy pasuje do skonfigurowanego identyfikatora konta.
- `channels.slack.streaming.mode` jest kanonicznym kluczem trybu strumieniowania Slack. `channels.slack.streaming.nativeTransport` kontroluje natywny transport strumieniowania Slack. Starsze wartości `streamMode`, logiczne `streaming` oraz `nativeStreaming` są automatycznie migrowane.
- Użyj `user:<id>` (DM) albo `channel:<id>` dla celów dostarczania.
- Opcjonalne `channels.slack.defaultAccount` zastępuje wybór konta domyślnego, gdy pasuje do skonfigurowanego identyfikatora konta.
- `channels.slack.streaming.mode` to kanoniczny klucz trybu strumienia Slack. `channels.slack.streaming.nativeTransport` kontroluje natywny transport strumieniowy Slack. Starsze wartości `streamMode`, boolowskie `streaming` i `nativeStreaming` są automatycznie migrowane.
- Używaj `user:<id>` (DM) lub `channel:<id>` dla celów dostarczania.
**Tryby powiadomień o reakcjach:** `off`, `own` (domyślnie), `all`, `allowlist` (z `reactionAllowlist`).
**Izolacja sesji wątku:** `thread.historyScope` jest osobna dla wątku (domyślnie) albo współdzielona w kanale. `thread.inheritParent` kopiuje transkrypt kanału nadrzędnego do nowych wątków.
**Izolacja sesji wątku:** `thread.historyScope` jest per wątek (domyślnie) lub współdzielone w kanale. `thread.inheritParent` kopiuje transkrypt kanału nadrzędnego do nowych wątków.
- Natywne strumieniowanie Slack oraz status wątku w stylu asystenta Slack „pisze...” wymagają celu wątku odpowiedzi. DM najwyższego poziomu pozostają domyślnie poza wątkiem, więc używają `typingReaction` albo normalnego dostarczania zamiast podglądu w stylu wątku.
- `typingReaction` dodaje tymczasową reakcję do przychodzącej wiadomości Slack podczas generowania odpowiedzi, a następnie usuwa ją po ukończeniu. Użyj krótkiego kodu emoji Slack, takiego jak `"hourglass_flowing_sand"`.
- `channels.slack.execApprovals`: natywne dla Slack dostarczanie zatwierdzeń exec oraz autoryzacja zatwierdzających. Ten sam schemat co Discord: `enabled` (`true`/`false`/`"auto"`), `approvers` (identyfikatory użytkowników Slack), `agentFilter`, `sessionFilter` i `target` (`"dm"`, `"channel"` albo `"both"`).
- Natywne strumieniowanie Slack oraz status wątku w stylu asystenta Slack „pisze...” wymagają celu wątku odpowiedzi. DM najwyższego poziomu domyślnie pozostają poza wątkiem, więc używają `typingReaction` lub normalnego dostarczania zamiast podglądu w stylu wątku.
- `typingReaction` dodaje tymczasową reakcję do przychodzącej wiadomości Slack, gdy odpowiedź jest w toku, a następnie usuwa ją po ukończeniu. Użyj shortcode emoji Slack, takiego jak `"hourglass_flowing_sand"`.
- `channels.slack.execApprovals`: natywne dla Slack dostarczanie zatwierdzeń exec i autoryzacja zatwierdzających. Ten sam schemat co Discord: `enabled` (`true`/`false`/`"auto"`), `approvers` (identyfikatory użytkowników Slack), `agentFilter`, `sessionFilter` i `target` (`"dm"`, `"channel"` lub `"both"`).
| Grupa akcji | Domyślnie | Uwagi |
| ------------ | ------- | ---------------------- |
| reactions | włączone | Reagowanie + lista reakcji |
| messages | włączone | Odczyt/wysyłanie/edycja/usuwanie |
| pins | włączone | Przypinanie/odpinanie/lista |
| reactions | włączone | Reaguj + wyświetl reakcje |
| messages | włączone | Odczytaj/wyślij/edytuj/usuń |
| pins | włączone | Przypnij/odepnij/wyświetl |
| memberInfo | włączone | Informacje o członku |
| emojiList | włączone | Lista niestandardowych emoji |
### Mattermost
Mattermost jest dostarczany jako dołączony plugin w bieżących wydaniach OpenClaw. Starsze albo
niestandardowe kompilacje mogą zainstalować bieżący pakiet npm przez
`openclaw plugins install @openclaw/mattermost`; jeśli npm zgłasza pakiet
należący do OpenClaw jako przestarzały, użyj dołączonego pluginu albo lokalnego checkoutu,
dopóki nowszy pakiet npm nie zostanie opublikowany.
Mattermost jest dostarczany jako dołączony Plugin w bieżących wydaniach OpenClaw. Starsze lub
niestandardowe kompilacje mogą zainstalować bieżący pakiet npm za pomocą
`openclaw plugins install @openclaw/mattermost`; jeśli npm zgłasza
pakiet należący do OpenClaw jako przestarzały, użyj dołączonego Plugin lub lokalnego checkoutu
do czasu opublikowania nowszego pakietu npm.
```json5
{
@ -532,23 +532,23 @@ dopóki nowszy pakiet npm nie zostanie opublikowany.
}
```
Tryby czatu: `oncall` (odpowiada przy @-wzmiance, domyślnie), `onmessage` (każda wiadomość), `onchar` (wiadomości zaczynające się od prefiksu wyzwalacza).
Tryby czatu: `oncall` (odpowiada przy @-wzmiance, domyślnie), `onmessage` (każda wiadomość), `onchar` (wiadomości zaczynające się od prefiksu wyzwalającego).
Gdy natywne polecenia Mattermost są włączone:
- `commands.callbackPath` musi być ścieżką (na przykład `/api/channels/mattermost/command`), a nie pełnym adresem URL.
- `commands.callbackUrl` musi rozwiązywać się do punktu końcowego Gateway OpenClaw i być osiągalny z serwera Mattermost.
- Natywne wywołania zwrotne slash są uwierzytelniane tokenami dla poszczególnych poleceń zwracanymi
przez Mattermost podczas rejestracji polecenia slash. Jeśli rejestracja się nie powiedzie albo żadne
polecenia nie zostaną aktywowane, OpenClaw odrzuca wywołania zwrotne komunikatem
- `commands.callbackPath` musi być ścieżką (na przykład `/api/channels/mattermost/command`), a nie pełnym URL.
- `commands.callbackUrl` musi wskazywać endpoint OpenClaw Gateway i być osiągalny z serwera Mattermost.
- Natywne callbacki slash są uwierzytelniane tokenami per polecenie zwróconymi
przez Mattermost podczas rejestracji polecenia slash. Jeśli rejestracja się nie powiedzie lub żadne
polecenia nie zostaną aktywowane, OpenClaw odrzuca callbacki z
`Unauthorized: invalid command token.`
- Dla prywatnych/tailnet/wewnętrznych hostów wywołań zwrotnych Mattermost może wymagać,
aby `ServiceSettings.AllowedUntrustedInternalConnections` zawierało host/domenę wywołania zwrotnego.
Użyj wartości hosta/domeny, nie pełnych adresów URL.
- `channels.mattermost.configWrites`: zezwól albo odmów zapisów konfiguracji inicjowanych przez Mattermost.
- `channels.mattermost.requireMention`: wymagaj `@mention` przed odpowiadaniem w kanałach.
- `channels.mattermost.groups.<channelId>.requireMention`: nadpisanie bramkowania wzmianką dla kanału (`"*"` jako domyślne).
- Opcjonalne `channels.mattermost.defaultAccount` nadpisuje wybór konta domyślnego, gdy pasuje do skonfigurowanego identyfikatora konta.
- W przypadku prywatnych/tailnet/wewnętrznych hostów callback Mattermost może wymagać,
aby `ServiceSettings.AllowedUntrustedInternalConnections` zawierało host/domenę callback.
Użyj wartości hosta/domeny, nie pełnych URL.
- `channels.mattermost.configWrites`: zezwól lub odmów zapisów konfiguracji inicjowanych przez Mattermost.
- `channels.mattermost.requireMention`: wymagaj `@mention` przed odpowiedzią w kanałach.
- `channels.mattermost.groups.<channelId>.requireMention`: nadpisanie bramkowania wzmianki per kanał (`"*"` dla domyślnego).
- Opcjonalne `channels.mattermost.defaultAccount` zastępuje wybór konta domyślnego, gdy pasuje do skonfigurowanego identyfikatora konta.
### Signal
@ -571,13 +571,13 @@ Gdy natywne polecenia Mattermost są włączone:
**Tryby powiadomień o reakcjach:** `off`, `own` (domyślnie), `all`, `allowlist` (z `reactionAllowlist`).
- `channels.signal.account`: przypnij uruchamianie kanału do określonej tożsamości konta Signal.
- `channels.signal.configWrites`: zezwól lub zabroń zapisów konfiguracji inicjowanych przez Signal.
- `channels.signal.account`: przypina uruchamianie kanału do konkretnej tożsamości konta Signal.
- `channels.signal.configWrites`: zezwala na zapisy konfiguracji inicjowane przez Signal albo ich odmawia.
- Opcjonalne `channels.signal.defaultAccount` zastępuje domyślny wybór konta, gdy pasuje do skonfigurowanego identyfikatora konta.
### BlueBubbles
BlueBubbles to zalecana ścieżka iMessage (oparta na Plugin, skonfigurowana w `channels.bluebubbles`).
BlueBubbles to zalecana ścieżka iMessage (oparta na Plugin, konfigurowana w `channels.bluebubbles`).
```json5
{
@ -592,14 +592,14 @@ BlueBubbles to zalecana ścieżka iMessage (oparta na Plugin, skonfigurowana w `
}
```
- Główne ścieżki kluczy omówione tutaj: `channels.bluebubbles`, `channels.bluebubbles.dmPolicy`.
- Opisane tutaj główne ścieżki kluczy: `channels.bluebubbles`, `channels.bluebubbles.dmPolicy`.
- Opcjonalne `channels.bluebubbles.defaultAccount` zastępuje domyślny wybór konta, gdy pasuje do skonfigurowanego identyfikatora konta.
- Wpisy najwyższego poziomu `bindings[]` z `type: "acp"` mogą powiązać konwersacje BlueBubbles z trwałymi sesjami ACP. Użyj uchwytu BlueBubbles albo ciągu docelowego (`chat_id:*`, `chat_guid:*`, `chat_identifier:*`) w `match.peer.id`. Semantyka pól wspólnych: [Agenci ACP](/pl/tools/acp-agents#channel-specific-settings).
- Wpisy najwyższego poziomu `bindings[]` z `type: "acp"` mogą wiązać konwersacje BlueBubbles z trwałymi sesjami ACP. Użyj uchwytu BlueBubbles albo ciągu docelowego (`chat_id:*`, `chat_guid:*`, `chat_identifier:*`) w `match.peer.id`. Semantyka pól współdzielonych: [agenci ACP](/pl/tools/acp-agents#channel-specific-settings).
- Pełna konfiguracja kanału BlueBubbles jest udokumentowana w [BlueBubbles](/pl/channels/bluebubbles).
### iMessage
OpenClaw uruchamia `imsg rpc` (JSON-RPC przez stdio). Nie jest wymagany daemon ani port.
OpenClaw uruchamia `imsg rpc` (JSON-RPC przez stdio). Demon ani port nie są wymagane.
```json5
{
@ -627,11 +627,11 @@ OpenClaw uruchamia `imsg rpc` (JSON-RPC przez stdio). Nie jest wymagany daemon a
- Wymaga pełnego dostępu do dysku dla bazy danych Wiadomości.
- Preferuj cele `chat_id:<id>`. Użyj `imsg chats --limit 20`, aby wyświetlić listę czatów.
- `cliPath` może wskazywać wrapper SSH; ustaw `remoteHost` (`host` lub `user@host`) do pobierania załączników przez SCP.
- `cliPath` może wskazywać wrapper SSH; ustaw `remoteHost` (`host` albo `user@host`) do pobierania załączników przez SCP.
- `attachmentRoots` i `remoteAttachmentRoots` ograniczają ścieżki załączników przychodzących (domyślnie: `/Users/*/Library/Messages/Attachments`).
- SCP używa ścisłej weryfikacji klucza hosta, więc upewnij się, że klucz hosta pośredniczącego już istnieje w `~/.ssh/known_hosts`.
- `channels.imessage.configWrites`: zezwól lub zabroń zapisów konfiguracji inicjowanych przez iMessage.
- Wpisy najwyższego poziomu `bindings[]` z `type: "acp"` mogą powiązać konwersacje iMessage z trwałymi sesjami ACP. Użyj znormalizowanego uchwytu albo jawnego celu czatu (`chat_id:*`, `chat_guid:*`, `chat_identifier:*`) w `match.peer.id`. Semantyka pól wspólnych: [Agenci ACP](/pl/tools/acp-agents#channel-specific-settings).
- SCP używa ścisłego sprawdzania klucza hosta, więc upewnij się, że klucz hosta przekaźnika już istnieje w `~/.ssh/known_hosts`.
- `channels.imessage.configWrites`: zezwala na zapisy konfiguracji inicjowane przez iMessage albo ich odmawia.
- Wpisy najwyższego poziomu `bindings[]` z `type: "acp"` mogą wiązać konwersacje iMessage z trwałymi sesjami ACP. Użyj znormalizowanego uchwytu albo jawnego celu czatu (`chat_id:*`, `chat_guid:*`, `chat_identifier:*`) w `match.peer.id`. Semantyka pól współdzielonych: [agenci ACP](/pl/tools/acp-agents#channel-specific-settings).
<Accordion title="Przykład wrappera SSH dla iMessage">
@ -644,7 +644,7 @@ exec ssh -T gateway-host imsg "$@"
### Matrix
Matrix jest oparty na Plugin i skonfigurowany w `channels.matrix`.
Matrix jest oparty na Plugin i konfigurowany w `channels.matrix`.
```json5
{
@ -675,24 +675,24 @@ Matrix jest oparty na Plugin i skonfigurowany w `channels.matrix`.
```
- Uwierzytelnianie tokenem używa `accessToken`; uwierzytelnianie hasłem używa `userId` + `password`.
- `channels.matrix.proxy` kieruje ruch HTTP Matrix przez jawny serwer proxy HTTP(S). Nazwane konta mogą go zastąpić przez `channels.matrix.accounts.<id>.proxy`.
- `channels.matrix.network.dangerouslyAllowPrivateNetwork` zezwala na prywatne/wewnętrzne serwery homeserver. `proxy` i ta zgoda sieciowa są niezależnymi mechanizmami kontroli.
- `channels.matrix.defaultAccount` wybiera preferowane konto w konfiguracjach z wieloma kontami.
- `channels.matrix.proxy` kieruje ruch HTTP Matrix przez jawny proxy HTTP(S). Nazwane konta mogą go zastąpić za pomocą `channels.matrix.accounts.<id>.proxy`.
- `channels.matrix.network.dangerouslyAllowPrivateNetwork` zezwala na prywatne/wewnętrzne serwery domowe. `proxy` i ta zgoda sieciowa są niezależnymi kontrolkami.
- `channels.matrix.defaultAccount` wybiera preferowane konto w konfiguracjach wielokontowych.
- `channels.matrix.autoJoin` domyślnie ma wartość `off`, więc zaproszone pokoje i nowe zaproszenia w stylu DM są ignorowane, dopóki nie ustawisz `autoJoin: "allowlist"` z `autoJoinAllowlist` albo `autoJoin: "always"`.
- `channels.matrix.execApprovals`: natywne dla Matrix dostarczanie zatwierdzeń exec i autoryzacja zatwierdzających.
- `enabled`: `true`, `false` albo `"auto"` (domyślnie). W trybie auto zatwierdzenia exec aktywują się, gdy zatwierdzających można ustalić z `approvers` albo `commands.ownerAllowFrom`.
- `approvers`: identyfikatory użytkowników Matrix (np. `@owner:example.org`) uprawnione do zatwierdzania żądań exec.
- `channels.matrix.execApprovals`: natywne dla Matrix dostarczanie zatwierdzeń wykonania i autoryzacja zatwierdzających.
- `enabled`: `true`, `false` albo `"auto"` (domyślnie). W trybie automatycznym zatwierdzenia wykonania aktywują się, gdy zatwierdzających da się rozpoznać z `approvers` albo `commands.ownerAllowFrom`.
- `approvers`: identyfikatory użytkowników Matrix (np. `@owner:example.org`) uprawnione do zatwierdzania żądań wykonania.
- `agentFilter`: opcjonalna lista dozwolonych identyfikatorów agentów. Pomiń, aby przekazywać zatwierdzenia dla wszystkich agentów.
- `sessionFilter`: opcjonalne wzorce kluczy sesji (podciąg lub wyrażenie regularne).
- `target`: gdzie wysyłać monity o zatwierdzenie. `"dm"` (domyślnie), `"channel"` (pokój źródłowy) albo `"both"`.
- Nadpisania dla poszczególnych kont: `channels.matrix.accounts.<id>.execApprovals`.
- `sessionFilter`: opcjonalne wzorce kluczy sesji (podciąg albo regex).
- `target`: miejsce wysyłania próśb o zatwierdzenie. `"dm"` (domyślnie), `"channel"` (pokój źródłowy) albo `"both"`.
- Zastąpienia per konto: `channels.matrix.accounts.<id>.execApprovals`.
- `channels.matrix.dm.sessionScope` kontroluje, jak DM w Matrix są grupowane w sesje: `per-user` (domyślnie) współdzieli według kierowanego peera, a `per-room` izoluje każdy pokój DM.
- Sondy statusu Matrix i wyszukiwania w katalogu na żywo używają tej samej polityki proxy co ruch w czasie działania.
- Sondy statusu Matrix i wyszukiwania katalogu na żywo używają tej samej polityki proxy co ruch w czasie działania.
- Pełna konfiguracja Matrix, reguły kierowania i przykłady konfiguracji są udokumentowane w [Matrix](/pl/channels/matrix).
### Microsoft Teams
Microsoft Teams jest oparty na Plugin i skonfigurowany w `channels.msteams`.
Microsoft Teams jest oparty na Plugin i konfigurowany w `channels.msteams`.
```json5
{
@ -707,12 +707,12 @@ Microsoft Teams jest oparty na Plugin i skonfigurowany w `channels.msteams`.
}
```
- Główne ścieżki kluczy omówione tutaj: `channels.msteams`, `channels.msteams.configWrites`.
- Pełna konfiguracja Teams (poświadczenia, Webhook, polityka DM/grup, nadpisania dla zespołów/kanałów) jest udokumentowana w [Microsoft Teams](/pl/channels/msteams).
- Opisane tutaj główne ścieżki kluczy: `channels.msteams`, `channels.msteams.configWrites`.
- Pełna konfiguracja Teams (dane uwierzytelniające, Webhook, polityka DM/grup, zastąpienia per zespół/per kanał) jest udokumentowana w [Microsoft Teams](/pl/channels/msteams).
### IRC
IRC jest oparty na Plugin i skonfigurowany w `channels.irc`.
IRC jest oparty na Plugin i konfigurowany w `channels.irc`.
```json5
{
@ -733,9 +733,9 @@ IRC jest oparty na Plugin i skonfigurowany w `channels.irc`.
}
```
- Główne ścieżki kluczy omówione tutaj: `channels.irc`, `channels.irc.dmPolicy`, `channels.irc.configWrites`, `channels.irc.nickserv.*`.
- Opisane tutaj główne ścieżki kluczy: `channels.irc`, `channels.irc.dmPolicy`, `channels.irc.configWrites`, `channels.irc.nickserv.*`.
- Opcjonalne `channels.irc.defaultAccount` zastępuje domyślny wybór konta, gdy pasuje do skonfigurowanego identyfikatora konta.
- Pełna konfiguracja kanału IRC (host/port/TLS/kanały/listy dozwolonych/bramkowanie wzmianką) jest udokumentowana w [IRC](/pl/channels/irc).
- Pełna konfiguracja kanału IRC (host/port/TLS/kanały/listy dozwolonych/bramkowanie wzmianek) jest udokumentowana w [IRC](/pl/channels/irc).
### Wiele kont (wszystkie kanały)
@ -760,32 +760,34 @@ Uruchamiaj wiele kont na kanał (każde z własnym `accountId`):
}
```
- `default` jest używane, gdy `accountId` jest pominięte (CLI + routing).
- `default` jest używane, gdy `accountId` zostanie pominięte (CLI + kierowanie).
- Tokeny środowiskowe dotyczą tylko konta **domyślnego**.
- Bazowe ustawienia kanału dotyczą wszystkich kont, chyba że zostaną nadpisane dla konta.
- Bazowe ustawienia kanału mają zastosowanie do wszystkich kont, chyba że zostaną zastąpione per konto.
- Użyj `bindings[].match.accountId`, aby kierować każde konto do innego agenta.
- Jeśli dodasz konto inne niż domyślne przez `openclaw channels add` (albo onboarding kanału), gdy nadal używasz jednokontowej konfiguracji kanału na najwyższym poziomie, OpenClaw najpierw przeniesie wartości jednokontowe z najwyższego poziomu, przypisane do konta, do mapy kont kanału, aby pierwotne konto nadal działało. Większość kanałów przenosi je do `channels.<channel>.accounts.default`; Matrix może zamiast tego zachować istniejący pasujący cel nazwany/domyślny.
- Istniejące powiązania tylko z kanałem (bez `accountId`) nadal pasują do konta domyślnego; powiązania przypisane do kont pozostają opcjonalne.
- `openclaw doctor --fix` naprawia także mieszane kształty, przenosząc jednokontowe wartości z najwyższego poziomu, przypisane do konta, do promowanego konta wybranego dla tego kanału. Większość kanałów używa `accounts.default`; Matrix może zamiast tego zachować istniejący pasujący cel nazwany/domyślny.
- Jeśli dodasz konto inne niż domyślne za pomocą `openclaw channels add` (albo onboardingu kanału), będąc nadal na jednokontowej konfiguracji kanału najwyższego poziomu, OpenClaw najpierw przenosi wartości jednokontowe najwyższego poziomu o zakresie konta do mapy kont kanału, aby pierwotne konto nadal działało. Większość kanałów przenosi je do `channels.<channel>.accounts.default`; Matrix może zamiast tego zachować istniejący pasujący nazwany/domyślny cel.
- Istniejące wiązania tylko dla kanału (bez `accountId`) nadal pasują do konta domyślnego; wiązania o zakresie konta pozostają opcjonalne.
- `openclaw doctor --fix` naprawia też mieszane kształty, przenosząc jednokontowe wartości najwyższego poziomu o zakresie konta do promowanego konta wybranego dla tego kanału. Większość kanałów używa `accounts.default`; Matrix może zamiast tego zachować istniejący pasujący nazwany/domyślny cel.
### Inne kanały Plugin
Wiele kanałów Plugin jest konfigurowanych jako `channels.<id>` i udokumentowanych na swoich dedykowanych stronach kanałów (na przykład Feishu, Matrix, LINE, Nostr, Zalo, Nextcloud Talk, Synology Chat i Twitch).
Zobacz pełny indeks kanałów: [Kanały](/pl/channels).
Zobacz pełny indeks kanałów: [kanały](/pl/channels).
### Bramkowanie wzmianką w czacie grupowym
### Bramkowanie wzmianek w czacie grupowym
Wiadomości grupowe domyślnie **wymagają wzmianki** (wzmianki w metadanych albo bezpieczne wzorce wyrażeń regularnych). Dotyczy czatów grupowych WhatsApp, Telegram, Discord, Google Chat i iMessage.
Wiadomości grupowe domyślnie **wymagają wzmianki** (wzmianki w metadanych albo bezpieczne wzorce regex). Dotyczy to czatów grupowych WhatsApp, Telegram, Discord, Google Chat i iMessage.
Widoczne odpowiedzi są kontrolowane osobno. Pokoje grupowe/kanałowe domyślnie używają `messages.groupChat.visibleReplies: "message_tool"`: OpenClaw nadal przetwarza turę, ale zwykłe odpowiedzi końcowe pozostają prywatne, a widoczne wyjście w pokoju wymaga `message(action=send)`. Ustaw `"automatic"` tylko wtedy, gdy chcesz zachować starsze zachowanie, w którym zwykłe odpowiedzi są publikowane z powrotem w pokoju. Aby zastosować to samo zachowanie widocznych odpowiedzi tylko przez narzędzie także do czatów bezpośrednich, ustaw `messages.visibleReplies: "message_tool"`.
Widoczne odpowiedzi są kontrolowane osobno. Pokoje grupowe/kanałowe domyślnie używają `messages.groupChat.visibleReplies: "message_tool"`: OpenClaw nadal przetwarza turę, ale zwykłe końcowe odpowiedzi pozostają prywatne, a widoczne wyjście w pokoju wymaga `message(action=send)`. Ustaw `"automatic"` tylko wtedy, gdy chcesz zachowania starszego typu, w którym zwykłe odpowiedzi są publikowane z powrotem do pokoju. Aby zastosować to samo zachowanie widocznej odpowiedzi wyłącznie przez narzędzie także do czatów bezpośrednich, ustaw `messages.visibleReplies: "message_tool"`.
Gateway przeładowuje konfigurację `messages` na gorąco po zapisaniu pliku. Restartuj tylko wtedy, gdy obserwowanie plików albo przeładowywanie konfiguracji jest wyłączone we wdrożeniu.
Jeśli narzędzie wiadomości jest niedostępne w ramach aktywnej polityki narzędzi, OpenClaw wraca do automatycznych widocznych odpowiedzi zamiast po cichu tłumić odpowiedź. `openclaw doctor` ostrzega o tej niezgodności.
Gateway przeładowuje konfigurację `messages` na gorąco po zapisaniu pliku. Restartuj tylko wtedy, gdy obserwowanie plików albo przeładowanie konfiguracji jest wyłączone we wdrożeniu.
**Typy wzmianek:**
- **Wzmianki w metadanych**: natywne wzmianki platformy @. Ignorowane w trybie czatu z samym sobą w WhatsApp.
- **Wzorce tekstowe**: bezpieczne wzorce wyrażeń regularnych w `agents.list[].groupChat.mentionPatterns`. Nieprawidłowe wzorce i niebezpieczne zagnieżdżone powtórzenia są ignorowane.
- Bramkowanie wzmianką jest egzekwowane tylko wtedy, gdy wykrywanie jest możliwe (natywne wzmianki albo co najmniej jeden wzorzec).
- **Wzmianki w metadanych**: natywne wzmianki @ platformy. Ignorowane w trybie czatu z samym sobą WhatsApp.
- **Wzorce tekstowe**: bezpieczne wzorce regex w `agents.list[].groupChat.mentionPatterns`. Nieprawidłowe wzorce i niebezpieczne zagnieżdżone powtórzenia są ignorowane.
- Bramkowanie wzmianek jest egzekwowane tylko wtedy, gdy wykrywanie jest możliwe (natywne wzmianki albo co najmniej jeden wzorzec).
```json5
{
@ -802,9 +804,9 @@ Gateway przeładowuje konfigurację `messages` na gorąco po zapisaniu pliku. Re
}
```
`messages.groupChat.historyLimit` ustawia globalną wartość domyślną. Kanały mogą ją nadpisać przez `channels.<channel>.historyLimit` (albo dla konta). Ustaw `0`, aby wyłączyć.
`messages.groupChat.historyLimit` ustawia globalną wartość domyślną. Kanały mogą ją zastąpić za pomocą `channels.<channel>.historyLimit` (albo per konto). Ustaw `0`, aby wyłączyć.
`messages.visibleReplies` to globalna wartość domyślna dla tur źródłowych; `messages.groupChat.visibleReplies` nadpisuje ją dla tur źródłowych grup/kanałów. Listy dozwolonych kanału i bramkowanie wzmianką nadal decydują, czy tura jest przetwarzana.
`messages.visibleReplies` to globalna wartość domyślna tury źródłowej; `messages.groupChat.visibleReplies` zastępuje ją dla tur źródłowych grup/kanałów. Listy dozwolonych kanałów i bramkowanie wzmianek nadal decydują, czy tura jest przetwarzana.
#### Limity historii DM
@ -821,13 +823,13 @@ Gateway przeładowuje konfigurację `messages` na gorąco po zapisaniu pliku. Re
}
```
Rozwiązywanie: nadpisanie dla DM → domyślna wartość dostawcy → brak limitu (wszystko zachowane).
Rozstrzyganie: zastąpienie per DM → domyślna wartość dostawcy → brak limitu (wszystko zachowane).
Obsługiwane: `telegram`, `whatsapp`, `discord`, `slack`, `signal`, `imessage`, `msteams`.
#### Tryb czatu z samym sobą
Dodaj własny numer do `allowFrom`, aby włączyć tryb czatu z samym sobą (ignoruje natywne wzmianki @, odpowiada tylko na wzorce tekstowe):
Dodaj własny numer w `allowFrom`, aby włączyć tryb czatu z samym sobą (ignoruje natywne wzmianki @, odpowiada tylko na wzorce tekstowe):
```json5
{
@ -875,34 +877,34 @@ Dodaj własny numer do `allowFrom`, aby włączyć tryb czatu z samym sobą (ign
}
```
<Accordion title="Szczegóły polecenia">
<Accordion title="Szczegóły poleceń">
- Ten blok konfiguruje powierzchnie poleceń. Aktualny wbudowany i dołączony katalog poleceń znajdziesz w sekcji [Polecenia ukośnikiem](/pl/tools/slash-commands).
- Ta strona jest **dokumentacją kluczy konfiguracji**, a nie pełnym katalogiem poleceń. Polecenia należące do kanałów/Pluginów, takie jak QQ Bot `/bot-ping` `/bot-help` `/bot-logs`, LINE `/card`, device-pair `/pair`, memory `/dreaming`, phone-control `/phone` oraz Talk `/voice`, są opisane na stronach swoich kanałów/Pluginów oraz w sekcji [Polecenia ukośnikiem](/pl/tools/slash-commands).
- Ten blok konfiguruje powierzchnie poleceń. Aktualny wbudowany i dołączony katalog poleceń znajduje się w [Poleceniach ukośnikowych](/pl/tools/slash-commands).
- Ta strona to **odniesienie do kluczy konfiguracji**, a nie pełny katalog poleceń. Polecenia należące do kanałów/Pluginów, takie jak QQ Bot `/bot-ping` `/bot-help` `/bot-logs`, LINE `/card`, parowanie urządzeń `/pair`, pamięć `/dreaming`, sterowanie telefonem `/phone` i Talk `/voice`, są udokumentowane na stronach ich kanałów/Pluginów oraz w [Poleceniach ukośnikowych](/pl/tools/slash-commands).
- Polecenia tekstowe muszą być **samodzielnymi** wiadomościami zaczynającymi się od `/`.
- `native: "auto"` włącza natywne polecenia dla Discord/Telegram, pozostawia Slack wyłączony.
- `native: "auto"` włącza polecenia natywne dla Discord/Telegram, pozostawia Slack wyłączony.
- `nativeSkills: "auto"` włącza natywne polecenia Skills dla Discord/Telegram, pozostawia Slack wyłączony.
- Nadpisanie dla kanału: `channels.discord.commands.native` (wartość boolowska albo `"auto"`). `false` usuwa wcześniej zarejestrowane polecenia.
- Nadpisz rejestrację natywnych poleceń Skills dla kanału za pomocą `channels.<provider>.commands.nativeSkills`.
- Nadpisanie dla kanału: `channels.discord.commands.native` (wartość boolowska lub `"auto"`). `false` czyści wcześniej zarejestrowane polecenia.
- Nadpisz rejestrację natywnych Skills dla kanału za pomocą `channels.<provider>.commands.nativeSkills`.
- `channels.telegram.customCommands` dodaje dodatkowe wpisy menu bota Telegram.
- `bash: true` włącza `! <cmd>` dla powłoki hosta. Wymaga `tools.elevated.enabled` oraz nadawcy w `tools.elevated.allowFrom.<channel>`.
- `config: true` włącza `/config` (odczytuje/zapisuje `openclaw.json`). W przypadku klientów `chat.send` Gateway trwałe zapisy `/config set|unset` wymagają też `operator.admin`; tylko do odczytu `/config show` pozostaje dostępne dla zwykłych klientów operatora z zakresem zapisu.
- `config: true` włącza `/config` (odczytuje/zapisuje `openclaw.json`). Dla klientów Gateway `chat.send` trwałe zapisy `/config set|unset` wymagają też `operator.admin`; tylko do odczytu `/config show` pozostaje dostępne dla zwykłych klientów operatora z zakresem zapisu.
- `mcp: true` włącza `/mcp` dla konfiguracji serwera MCP zarządzanego przez OpenClaw w `mcp.servers`.
- `plugins: true` włącza `/plugins` do wykrywania, instalowania oraz włączania/wyłączania Pluginów.
- `channels.<provider>.configWrites` kontroluje mutacje konfiguracji dla kanału (domyślnie: true).
- W kanałach z wieloma kontami `channels.<provider>.accounts.<id>.configWrites` kontroluje również zapisy kierowane do tego konta (na przykład `/allowlist --config --account <id>` albo `/config set channels.<provider>.accounts.<id>...`).
- `restart: false` wyłącza `/restart` oraz akcje narzędzia restartu Gateway. Domyślnie: `true`.
- `ownerAllowFrom` to jawna allowlista właściciela dla poleceń/narzędzi dostępnych tylko dla właściciela. Jest oddzielna od `allowFrom`.
- `ownerDisplay: "hash"` haszuje identyfikatory właściciela w prompcie systemowym. Ustaw `ownerDisplaySecret`, aby kontrolować haszowanie.
- `allowFrom` jest osobne dla każdego dostawcy. Gdy jest ustawione, stanowi **jedyne** źródło autoryzacji (allowlisty/parowanie kanałów oraz `useAccessGroups` są ignorowane).
- `channels.<provider>.configWrites` ogranicza mutacje konfiguracji dla kanału (domyślnie: true).
- W kanałach z wieloma kontami `channels.<provider>.accounts.<id>.configWrites` ogranicza też zapisy kierowane do tego konta (na przykład `/allowlist --config --account <id>` lub `/config set channels.<provider>.accounts.<id>...`).
- `restart: false` wyłącza `/restart` i akcje narzędzia restartu Gateway. Domyślnie: `true`.
- `ownerAllowFrom` to jawna lista dozwolonych właścicieli dla poleceń/narzędzi dostępnych tylko dla właściciela. Jest oddzielna od `allowFrom`.
- `ownerDisplay: "hash"` haszuje identyfikatory właścicieli w prompcie systemowym. Ustaw `ownerDisplaySecret`, aby kontrolować haszowanie.
- `allowFrom` jest konfigurowane dla każdego dostawcy. Gdy jest ustawione, jest **jedynym** źródłem autoryzacji (listy dozwolonych kanałów/parowanie oraz `useAccessGroups` są ignorowane).
- `useAccessGroups: false` pozwala poleceniom omijać zasady grup dostępu, gdy `allowFrom` nie jest ustawione.
- Mapa dokumentacji poleceń:
- wbudowany i dołączony katalog: [Polecenia ukośnikiem](/pl/tools/slash-commands)
- wbudowany i dołączony katalog: [Polecenia ukośnikowe](/pl/tools/slash-commands)
- powierzchnie poleceń specyficzne dla kanałów: [Kanały](/pl/channels)
- polecenia QQ Bot: [QQ Bot](/pl/channels/qqbot)
- polecenia parowania: [Parowanie](/pl/channels/pairing)
- polecenie karty LINE: [LINE](/pl/channels/line)
- dreaming pamięci: [Dreaming](/pl/concepts/dreaming)
- Dreaming pamięci: [Dreaming](/pl/concepts/dreaming)
</Accordion>
@ -910,6 +912,6 @@ Dodaj własny numer do `allowFrom`, aby włączyć tryb czatu z samym sobą (ign
## Powiązane
- [Dokumentacja konfiguracji](/pl/gateway/configuration-reference) — klucze najwyższego poziomu
- [Odniesienie do konfiguracji](/pl/gateway/configuration-reference) — klucze najwyższego poziomu
- [Konfiguracja — agenci](/pl/gateway/config-agents)
- [Przegląd kanałów](/pl/channels)
- [Omówienie kanałów](/pl/channels)

178
docs/pl/gateway/config-tools.md
View File

@ -1,44 +1,44 @@
---
read_when:
- Konfigurowanie zasad `tools.*`, list dozwolonych lub funkcji eksperymentalnych
- Konfigurowanie polityki `tools.*`, list dozwolonych lub funkcji eksperymentalnych
- Rejestrowanie niestandardowych dostawców lub zastępowanie bazowych adresów URL
- Konfigurowanie samodzielnie hostowanych punktów końcowych zgodnych z OpenAI
sidebarTitle: Tools and custom providers
summary: Konfiguracja narzędzi (zasady, eksperymentalne przełączniki, narzędzia obsługiwane przez dostawcę) oraz konfiguracja niestandardowego dostawcy i bazowego adresu URL
summary: Konfiguracja narzędzi (zasady, eksperymentalne przełączniki, narzędzia obsługiwane przez dostawcę) oraz konfiguracja niestandardowego dostawcy / bazowego adresu URL
title: Konfiguracja — narzędzia i niestandardowi dostawcy
x-i18n:
generated_at: "2026-04-30T09:51:48Z"
generated_at: "2026-05-01T09:58:40Z"
model: gpt-5.5
provider: openai
source_hash: 1790c92ecaf822c837326d8e22e9d72cc44e5d4cc0bcc00c154ba5160975002a
source_hash: 97e6bd8c762f6f7a9985b99ec016dde22c8ea8adc925778b11c2ae5103b887a8
source_path: gateway/config-tools.md
workflow: 16
---
Klucze konfiguracji `tools.*` oraz konfiguracja niestandardowego dostawcy / bazowego adresu URL. Agentów, kanały i inne klucze konfiguracji najwyższego poziomu opisuje [Dokumentacja konfiguracji](/pl/gateway/configuration-reference).
`tools.*` klucze konfiguracji oraz konfiguracja niestandardowego dostawcy / bazowego adresu URL. Informacje o agentach, kanałach i innych kluczach konfiguracji najwyższego poziomu znajdziesz w [odniesieniu do konfiguracji](/pl/gateway/configuration-reference).
## Narzędzia
### Profile narzędzi
`tools.profile` ustawia bazową listę dozwolonych narzędzi przed `tools.allow`/`tools.deny`:
`tools.profile` ustawia bazową listę dozwolonych elementów przed `tools.allow`/`tools.deny`:
<Note>
Lokalne wdrażanie domyślnie ustawia w nowych konfiguracjach lokalnych `tools.profile: "coding"`, gdy nie podano wartości (istniejące jawne profile są zachowywane).
Lokalny onboarding domyślnie ustawia w nowych konfiguracjach lokalnych `tools.profile: "coding"`, gdy nie jest ustawiony (istniejące jawne profile są zachowywane).
</Note>
| Profil | Obejmuje |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `minimal` | Tylko `session_status` |
| `minimal` | tylko `session_status` |
| `coding` | `group:fs`, `group:runtime`, `group:web`, `group:sessions`, `group:memory`, `cron`, `image`, `image_generate`, `video_generate` |
| `messaging` | `group:messaging`, `sessions_list`, `sessions_history`, `sessions_send`, `session_status` |
| `full` | Bez ograniczeń (tak samo jak przy braku ustawienia) |
| `full` | Brak ograniczeń (tak samo jak brak ustawienia) |
### Grupy narzędzi
| Grupa | Narzędzia |
| ------------------ | ----------------------------------------------------------------------------------------------------------------------- |
| `group:runtime` | `exec`, `process`, `code_execution` (`bash` jest akceptowany jako alias dla `exec`) |
| `group:runtime` | `exec`, `process`, `code_execution` (`bash` jest akceptowany jako alias dla `exec`) |
| `group:fs` | `read`, `write`, `edit`, `apply_patch` |
| `group:sessions` | `sessions_list`, `sessions_history`, `sessions_send`, `sessions_spawn`, `sessions_yield`, `subagents`, `session_status` |
| `group:memory` | `memory_search`, `memory_get` |
@ -49,11 +49,11 @@ Lokalne wdrażanie domyślnie ustawia w nowych konfiguracjach lokalnych `tools.p
| `group:nodes` | `nodes` |
| `group:agents` | `agents_list` |
| `group:media` | `image`, `image_generate`, `video_generate`, `tts` |
| `group:openclaw` | Wszystkie wbudowane narzędzia (z wyłączeniem provider plugins) |
| `group:openclaw` | Wszystkie wbudowane narzędzia (z wyłączeniem Plugin dostawców) |
### `tools.allow` / `tools.deny`
Globalna polityka zezwalania/odmawiania narzędzi (odmowa ma pierwszeństwo). Nie rozróżnia wielkości liter, obsługuje symbole wieloznaczne `*`. Stosowana nawet wtedy, gdy piaskownica Docker jest wyłączona.
Globalna polityka zezwalania/odmawiania narzędzi (odmowa wygrywa). Bez rozróżniania wielkości liter, obsługuje symbole wieloznaczne `*`. Stosowana nawet wtedy, gdy piaskownica Docker jest wyłączona.
```json5
{
@ -63,7 +63,7 @@ Globalna polityka zezwalania/odmawiania narzędzi (odmowa ma pierwszeństwo). Ni
### `tools.byProvider`
Dodatkowo ogranicza narzędzia dla konkretnych dostawców lub modeli. Kolejność: profil bazowy → profil dostawcy → zezwól/odmów.
Dodatkowo ogranicza narzędzia dla konkretnych dostawców lub modeli. Kolejność: profil bazowy → profil dostawcy → zezwalaj/odmawiaj.
```json5
{
@ -79,7 +79,7 @@ Dodatkowo ogranicza narzędzia dla konkretnych dostawców lub modeli. Kolejnoś
### `tools.elevated`
Kontroluje podniesiony dostęp `exec` poza piaskownicą:
Kontroluje podwyższony dostęp `exec` poza piaskownicą:
```json5
{
@ -96,8 +96,8 @@ Kontroluje podniesiony dostęp `exec` poza piaskownicą:
```
- Nadpisanie per agent (`agents.list[].tools.elevated`) może tylko dodatkowo ograniczać.
- `/elevated on|off|ask|full` zapisuje stan dla sesji; dyrektywy inline mają zastosowanie do pojedynczej wiadomości.
- Podniesiony `exec` omija piaskownicę i używa skonfigurowanej ścieżki wyjścia (`gateway` domyślnie albo `node`, gdy celem `exec` jest `node`).
- `/elevated on|off|ask|full` zapisuje stan dla sesji; dyrektywy inline dotyczą pojedynczej wiadomości.
- Podwyższone `exec` omija piaskownicę i używa skonfigurowanej ścieżki wyjścia (`gateway` domyślnie albo `node`, gdy celem exec jest `node`).
### `tools.exec`
@ -121,7 +121,7 @@ Kontroluje podniesiony dostęp `exec` poza piaskownicą:
### `tools.loopDetection`
Kontrole bezpieczeństwa pętli narzędzi są **domyślnie wyłączone**. Ustaw `enabled: true`, aby aktywować wykrywanie. Ustawienia można zdefiniować globalnie w `tools.loopDetection` i nadpisać per agent w `agents.list[].tools.loopDetection`.
Kontrole bezpieczeństwa pętli narzędzi są **domyślnie wyłączone**. Ustaw `enabled: true`, aby aktywować wykrywanie. Ustawienia można definiować globalnie w `tools.loopDetection` i nadpisywać per agent w `agents.list[].tools.loopDetection`.
```json5
{
@ -155,7 +155,7 @@ Kontrole bezpieczeństwa pętli narzędzi są **domyślnie wyłączone**. Ustaw
Twardy próg zatrzymania dla dowolnego przebiegu bez postępu.
</ParamField>
<ParamField path="detectors.genericRepeat" type="boolean">
Ostrzegaj przy powtarzanych wywołaniach tego samego narzędzia z tymi samymi argumentami.
Ostrzegaj przy powtarzających się wywołaniach tego samego narzędzia z tymi samymi argumentami.
</ParamField>
<ParamField path="detectors.knownPollNoProgress" type="boolean">
Ostrzegaj/blokuj przy znanych narzędziach odpytywania (`process.poll`, `command_status` itd.).
@ -165,7 +165,7 @@ Kontrole bezpieczeństwa pętli narzędzi są **domyślnie wyłączone**. Ustaw
</ParamField>
<Warning>
Jeśli `warningThreshold >= criticalThreshold` lub `criticalThreshold >= globalCircuitBreakerThreshold`, walidacja kończy się niepowodzeniem.
Jeśli `warningThreshold >= criticalThreshold` albo `criticalThreshold >= globalCircuitBreakerThreshold`, walidacja kończy się niepowodzeniem.
</Warning>
### `tools.web`
@ -200,7 +200,7 @@ Jeśli `warningThreshold >= criticalThreshold` lub `criticalThreshold >= globalC
### `tools.media`
Konfiguruje rozumienie przychodzących multimediów (obraz/audio/wideo):
Konfiguruje rozumienie przychodzących multimediów (obrazu/audio/wideo):
```json5
{
@ -208,7 +208,7 @@ Konfiguruje rozumienie przychodzących multimediów (obraz/audio/wideo):
media: {
concurrency: 2,
asyncCompletion: {
directSend: false, // opt-in: send finished async music/video directly to the channel
directSend: false, // opt-in: send finished async video directly to the channel
},
audio: {
enabled: true,
@ -238,30 +238,30 @@ Konfiguruje rozumienie przychodzących multimediów (obraz/audio/wideo):
```
<AccordionGroup>
<Accordion title="Media model entry fields">
**Wpis dostawcy** (`type: "provider"` albo pominięte):
<Accordion title="Pola wpisu modelu multimediów">
**Wpis dostawcy** (`type: "provider"` lub pominięty):
- `provider`: identyfikator dostawcy API (`openai`, `anthropic`, `google`/`gemini`, `groq` itd.)
- `model`: nadpisanie identyfikatora modelu
- `profile` / `preferredProfile`: wybór profilu z `auth-profiles.json`
- `model`: zastąpienie identyfikatora modelu
- `profile` / `preferredProfile`: wybór profilu `auth-profiles.json`
**Wpis CLI** (`type: "cli"`):
- `command`: plik wykonywalny do uruchomienia
- `args`: argumenty z szablonami (obsługuje `{{MediaPath}}`, `{{Prompt}}`, `{{MaxChars}}` itd.; `openclaw doctor --fix` migruje przestarzałe symbole zastępcze `{input}` do `{{MediaPath}}`)
- `args`: argumenty szablonowane (obsługuje `{{MediaPath}}`, `{{Prompt}}`, `{{MaxChars}}` itd.; `openclaw doctor --fix` migruje przestarzałe symbole zastępcze `{input}` do `{{MediaPath}}`)
**Pola wspólne:**
**Wspólne pola:**
- `capabilities`: opcjonalna lista (`image`, `audio`, `video`). Wartości domyślne: `openai`/`anthropic`/`minimax` → obraz, `google` → obraz+audio+wideo, `groq` → audio.
- `prompt`, `maxChars`, `maxBytes`, `timeoutSeconds`, `language`: nadpisania dla pojedynczego wpisu.
- `tools.media.image.timeoutSeconds` oraz pasujące wpisy `timeoutSeconds` modeli obrazu mają też zastosowanie, gdy agent wywołuje jawne narzędzie `image`.
- `capabilities`: opcjonalna lista (`image`, `audio`, `video`). Domyślne: `openai`/`anthropic`/`minimax` → obraz, `google` → obraz+audio+wideo, `groq` → audio.
- `prompt`, `maxChars`, `maxBytes`, `timeoutSeconds`, `language`: zastąpienia dla pojedynczego wpisu.
- `tools.media.image.timeoutSeconds` i pasujące wpisy `timeoutSeconds` modelu obrazu mają też zastosowanie, gdy agent wywołuje jawne narzędzie `image`.
- Awarie powodują przejście do następnego wpisu.
Uwierzytelnianie dostawcy używa standardowej kolejności: `auth-profiles.json` → zmienne środowiskowe → `models.providers.*.apiKey`.
Uwierzytelnianie dostawcy stosuje standardową kolejność: `auth-profiles.json` → zmienne środowiskowe → `models.providers.*.apiKey`.
**Pola asynchronicznego ukończenia:**
**Pola ukończenia asynchronicznego:**
- `asyncCompletion.directSend`: gdy ma wartość `true`, ukończone asynchroniczne zadania `music_generate` i `video_generate` najpierw próbują bezpośredniego dostarczenia do kanału. Wartość domyślna: `false` (starsza ścieżka wybudzania sesji żądającego/dostarczania przez model).
- `asyncCompletion.directSend`: gdy `true`, ukończone asynchroniczne zadania multimedialne obsługujące bezpośrednie dostarczanie ukończenia najpierw próbują bezpośredniego dostarczenia do kanału. Domyślnie: `false` (ścieżka wybudzenia sesji żądającego/dostarczenia przez model). Obecnie dotyczy to asynchronicznego `video_generate`; ukończenia asynchronicznego `music_generate` pozostają pośredniczone przez sesję żądającego nawet wtedy, gdy ta opcja jest włączona.
</Accordion>
</AccordionGroup>
@ -281,9 +281,9 @@ Konfiguruje rozumienie przychodzących multimediów (obraz/audio/wideo):
### `tools.sessions`
Kontroluje, które sesje mogą być adresowane przez narzędzia sesji (`sessions_list`, `sessions_history`, `sessions_send`).
Kontroluje, które sesje mogą być wskazywane przez narzędzia sesji (`sessions_list`, `sessions_history`, `sessions_send`).
Wartość domyślna: `tree` (bieżąca sesja + sesje przez nią uruchomione, takie jak subagenci).
Domyślnie: `tree` (bieżąca sesja + sesje przez nią utworzone, takie jak subagenci).
```json5
{
@ -297,19 +297,19 @@ Wartość domyślna: `tree` (bieżąca sesja + sesje przez nią uruchomione, tak
```
<AccordionGroup>
<Accordion title="Visibility scopes">
<Accordion title="Zakresy widoczności">
- `self`: tylko klucz bieżącej sesji.
- `tree`: bieżąca sesja + sesje uruchomione przez bieżącą sesję (subagenci).
- `agent`: dowolna sesja należąca do bieżącego identyfikatora agenta (może obejmować innych użytkowników, jeśli uruchamiasz sesje dla poszczególnych nadawców pod tym samym identyfikatorem agenta).
- `all`: dowolna sesja. Adresowanie między agentami nadal wymaga `tools.agentToAgent`.
- Ograniczenie piaskownicy: gdy bieżąca sesja działa w piaskownicy, a `agents.defaults.sandbox.sessionToolsVisibility="spawned"`, widoczność jest wymuszana na `tree`, nawet jeśli `tools.sessions.visibility="all"`.
- `tree`: bieżąca sesja + sesje utworzone przez bieżącą sesję (subagenci).
- `agent`: dowolna sesja należąca do identyfikatora bieżącego agenta (może obejmować innych użytkowników, jeśli uruchamiasz sesje dla poszczególnych nadawców pod tym samym identyfikatorem agenta).
- `all`: dowolna sesja. Kierowanie między agentami nadal wymaga `tools.agentToAgent`.
- Ograniczenie sandboxa: gdy bieżąca sesja jest w sandboxie, a `agents.defaults.sandbox.sessionToolsVisibility="spawned"`, widoczność jest wymuszana na `tree`, nawet jeśli `tools.sessions.visibility="all"`.
</Accordion>
</AccordionGroup>
### `tools.sessions_spawn`
Kontroluje obsługę załączników inline dla `sessions_spawn`.
Kontroluje obsługę załączników w treści dla `sessions_spawn`.
```json5
{
@ -328,13 +328,13 @@ Kontroluje obsługę załączników inline dla `sessions_spawn`.
```
<AccordionGroup>
<Accordion title="Attachment notes">
<Accordion title="Uwagi dotyczące załączników">
- Załączniki są obsługiwane tylko dla `runtime: "subagent"`. Środowisko uruchomieniowe ACP je odrzuca.
- Pliki są materializowane w przestrzeni roboczej procesu podrzędnego w `.openclaw/attachments/<uuid>/` wraz z `.manifest.json`.
- Treść załączników jest automatycznie redagowana przy utrwalaniu transkrypcji.
- Dane wejściowe Base64 są walidowane ścisłymi kontrolami alfabetu/dopełnienia oraz strażnikiem rozmiaru przed dekodowaniem.
- Pliki są materializowane w obszarze roboczym dziecka w `.openclaw/attachments/<uuid>/` z plikiem `.manifest.json`.
- Treść załączników jest automatycznie redagowana z trwałego zapisu transkryptu.
- Dane wejściowe Base64 są weryfikowane za pomocą ścisłych kontroli alfabetu/wypełnienia oraz zabezpieczenia rozmiaru przed dekodowaniem.
- Uprawnienia plików to `0700` dla katalogów i `0600` dla plików.
- Czyszczenie podąża za zasadą `cleanup`: `delete` zawsze usuwa załączniki; `keep` zachowuje je tylko wtedy, gdy `retainOnSessionKeep: true`.
- Czyszczenie przestrzega polityki `cleanup`: `delete` zawsze usuwa załączniki; `keep` zachowuje je tylko wtedy, gdy `retainOnSessionKeep: true`.
</Accordion>
</AccordionGroup>
@ -343,7 +343,7 @@ Kontroluje obsługę załączników inline dla `sessions_spawn`.
### `tools.experimental`
Eksperymentalne flagi narzędzi wbudowanych. Domyślnie wyłączone, chyba że ma zastosowanie reguła automatycznego włączenia dla ścisłego agenta GPT-5.
Eksperymentalne flagi wbudowanych narzędzi. Domyślnie wyłączone, chyba że ma zastosowanie reguła automatycznego włączania dla ściśle agentowego GPT-5.
```json5
{
@ -356,8 +356,8 @@ Eksperymentalne flagi narzędzi wbudowanych. Domyślnie wyłączone, chyba że m
```
- `planTool`: włącza ustrukturyzowane narzędzie `update_plan` do śledzenia nietrywialnej pracy wieloetapowej.
- Domyślnie: `false`, chyba że `agents.defaults.embeddedPi.executionContract` (lub nadpisanie dla agenta) ustawiono na `"strict-agentic"` dla uruchomienia rodziny GPT-5 OpenAI lub OpenAI Codex. Ustaw `true`, aby wymusić włączenie narzędzia poza tym zakresem, albo `false`, aby pozostawić je wyłączone nawet dla uruchomień strict-agentic GPT-5.
- Gdy jest włączone, prompt systemowy dodaje też wskazówki użycia, aby model używał go tylko do istotnej pracy i utrzymywał najwyżej jeden krok `in_progress`.
- Domyślnie: `false`, chyba że `agents.defaults.embeddedPi.executionContract` (lub nadpisanie dla danego agenta) jest ustawione na `"strict-agentic"` dla uruchomienia OpenAI albo OpenAI Codex z rodziny GPT-5. Ustaw `true`, aby wymusić włączenie narzędzia poza tym zakresem, albo `false`, aby pozostawić je wyłączone nawet dla uruchomień strict-agentic GPT-5.
- Gdy jest włączone, prompt systemowy dodaje też wskazówki użycia, aby model korzystał z niego tylko przy istotnej pracy i utrzymywał najwyżej jeden krok `in_progress`.
### `agents.defaults.subagents`
@ -377,10 +377,10 @@ Eksperymentalne flagi narzędzi wbudowanych. Domyślnie wyłączone, chyba że m
}
```
- `model`: domyślny model dla tworzonych podagentów. Jeśli pominięto, podagenci dziedziczą model wywołującego.
- `allowAgents`: domyślna lista dozwolonych identyfikatorów agentów docelowych dla `sessions_spawn`, gdy agent żądający nie ustawia własnego `subagents.allowAgents` (`["*"]` = dowolny; domyślnie: tylko ten sam agent).
- `model`: domyślny model dla uruchamianych subagentów. Jeśli pominięto, subagenci dziedziczą model wywołującego.
- `allowAgents`: domyślna lista dozwolonych identyfikatorów agentów docelowych dla `sessions_spawn`, gdy agent żądający nie ustawi własnego `subagents.allowAgents` (`["*"]` = dowolny; domyślnie: tylko ten sam agent).
- `runTimeoutSeconds`: domyślny limit czasu (w sekundach) dla `sessions_spawn`, gdy wywołanie narzędzia pomija `runTimeoutSeconds`. `0` oznacza brak limitu czasu.
- Polityka narzędzi dla podagenta: `tools.subagents.tools.allow` / `tools.subagents.tools.deny`.
- Zasady narzędzi dla poszczególnych subagentów: `tools.subagents.tools.allow` / `tools.subagents.tools.deny`.
---
@ -417,18 +417,18 @@ OpenClaw używa wbudowanego katalogu modeli. Dodaj niestandardowych dostawców p
<AccordionGroup>
<Accordion title="Auth and merge precedence">
- Użyj `authHeader: true` + `headers` dla niestandardowych potrzeb uwierzytelniania.
- Użyj `authHeader: true` + `headers` dla niestandardowych wymagań uwierzytelniania.
- Nadpisz katalog główny konfiguracji agenta za pomocą `OPENCLAW_AGENT_DIR` (albo `PI_CODING_AGENT_DIR`, starszego aliasu zmiennej środowiskowej).
- Priorytet scalania dla pasujących identyfikatorów dostawców:
- Niepuste wartości `baseUrl` z `models.json` agenta wygrywają.
- Niepuste wartości `apiKey` agenta wygrywają tylko wtedy, gdy ten dostawca nie jest zarządzany przez SecretRef w bieżącym kontekście konfiguracji/profilu uwierzytelniania.
- Wartości `apiKey` dostawcy zarządzanego przez SecretRef są odświeżane ze znaczników źródłowych (`ENV_VAR_NAME` dla odwołań do env, `secretref-managed` dla odwołań do pliku/exec) zamiast utrwalania rozwiązanych sekretów.
- Wartości nagłówków dostawcy zarządzanego przez SecretRef są odświeżane ze znaczników źródłowych (`secretref-env:ENV_VAR_NAME` dla odwołań do env, `secretref-managed` dla odwołań do pliku/exec).
- Kolejność scalania dla pasujących identyfikatorów dostawców:
- Niepuste wartości `baseUrl` z `models.json` agenta mają pierwszeństwo.
- Niepuste wartości `apiKey` agenta mają pierwszeństwo tylko wtedy, gdy ten dostawca nie jest zarządzany przez SecretRef w bieżącym kontekście konfiguracji/profilu uwierzytelniania.
- Wartości `apiKey` dostawcy zarządzanego przez SecretRef są odświeżane ze znaczników źródłowych (`ENV_VAR_NAME` dla odwołań do zmiennych środowiskowych, `secretref-managed` dla odwołań do pliku/exec) zamiast utrwalać rozwiązane sekrety.
- Wartości nagłówków dostawcy zarządzanego przez SecretRef są odświeżane ze znaczników źródłowych (`secretref-env:ENV_VAR_NAME` dla odwołań do zmiennych środowiskowych, `secretref-managed` dla odwołań do pliku/exec).
- Puste lub brakujące `apiKey`/`baseUrl` agenta wracają do `models.providers` w konfiguracji.
- Pasujące `contextWindow`/`maxTokens` modelu używają wyższej wartości spośród jawnej konfiguracji i niejawnych wartości katalogu.
- Pasujące `contextTokens` modelu zachowuje jawny limit wykonawczy, gdy jest obecny; użyj go, aby ograniczyć efektywny kontekst bez zmiany natywnych metadanych modelu.
- Pasujące `contextTokens` modelu zachowuje jawny limit środowiska uruchomieniowego, gdy jest obecny; użyj go, aby ograniczyć efektywny kontekst bez zmieniania natywnych metadanych modelu.
- Użyj `models.mode: "replace"`, gdy chcesz, aby konfiguracja w pełni przepisała `models.json`.
- Utrwalanie znaczników jest autorytatywne względem źródła: znaczniki są zapisywane z aktywnej migawki konfiguracji źródłowej (przed rozwiązaniem), a nie z rozwiązanych wartości sekretów w czasie wykonania.
- Utrwalanie znaczników jest autorytatywne względem źródła: znaczniki są zapisywane z aktywnej migawki konfiguracji źródłowej (przed rozwiązaniem), nie z rozwiązanych wartości sekretów w środowisku uruchomieniowym.
</Accordion>
</AccordionGroup>
@ -438,56 +438,56 @@ OpenClaw używa wbudowanego katalogu modeli. Dodaj niestandardowych dostawców p
<AccordionGroup>
<Accordion title="Top-level catalog">
- `models.mode`: zachowanie katalogu dostawców (`merge` albo `replace`).
- `models.providers`: mapa niestandardowych dostawców kluczowana identyfikatorem dostawcy.
- `models.providers`: mapa niestandardowych dostawców indeksowana identyfikatorem dostawcy.
- Bezpieczne edycje: użyj `openclaw config set models.providers.<id> '<json>' --strict-json --merge` albo `openclaw config set models.providers.<id>.models '<json-array>' --strict-json --merge` dla aktualizacji addytywnych. `config set` odmawia destrukcyjnych zamian, chyba że przekażesz `--replace`.
</Accordion>
<Accordion title="Provider connection and auth">
- `models.providers.*.api`: adapter żądań (`openai-completions`, `openai-responses`, `anthropic-messages`, `google-generative-ai` itd.). Dla samodzielnie hostowanych backendów `/v1/chat/completions`, takich jak MLX, vLLM, SGLang i większość lokalnych serwerów zgodnych z OpenAI, użyj `openai-completions`. Niestandardowy dostawca z `baseUrl`, ale bez `api`, domyślnie używa `openai-completions`; ustaw `openai-responses` tylko wtedy, gdy backend obsługuje `/v1/responses`.
- `models.providers.*.apiKey`: poświadczenie dostawcy (preferuj SecretRef/podstawianie env).
- `models.providers.*.apiKey`: poświadczenie dostawcy (preferuj podstawianie SecretRef/zmiennych środowiskowych).
- `models.providers.*.auth`: strategia uwierzytelniania (`api-key`, `token`, `oauth`, `aws-sdk`).
- `models.providers.*.contextWindow`: domyślne natywne okno kontekstu dla modeli tego dostawcy, gdy wpis modelu nie ustawia `contextWindow`.
- `models.providers.*.contextTokens`: domyślny efektywny limit kontekstu wykonawczego dla modeli tego dostawcy, gdy wpis modelu nie ustawia `contextTokens`.
- `models.providers.*.maxTokens`: domyślny limit tokenów wyjściowych dla modeli tego dostawcy, gdy wpis modelu nie ustawia `maxTokens`.
- `models.providers.*.timeoutSeconds`: opcjonalny limit czasu żądania HTTP modelu dla dostawcy, w sekundach, obejmujący połączenie, nagłówki, treść i obsługę przerwania całego żądania.
- `models.providers.*.injectNumCtxForOpenAICompat`: dla Ollama + `openai-completions` wstrzykuj `options.num_ctx` do żądań (domyślnie: `true`).
- `models.providers.*.authHeader`: wymuś transport poświadczenia w nagłówku `Authorization`, gdy jest wymagany.
- `models.providers.*.contextWindow`: domyślne natywne okno kontekstu dla modeli u tego dostawcy, gdy wpis modelu nie ustawia `contextWindow`.
- `models.providers.*.contextTokens`: domyślny efektywny limit kontekstu środowiska uruchomieniowego dla modeli u tego dostawcy, gdy wpis modelu nie ustawia `contextTokens`.
- `models.providers.*.maxTokens`: domyślny limit tokenów wyjściowych dla modeli u tego dostawcy, gdy wpis modelu nie ustawia `maxTokens`.
- `models.providers.*.timeoutSeconds`: opcjonalny limit czasu żądania HTTP modelu dla danego dostawcy w sekundach, obejmujący połączenie, nagłówki, treść i obsługę przerwania całego żądania.
- `models.providers.*.injectNumCtxForOpenAICompat`: dla Ollama + `openai-completions`, wstrzykuje `options.num_ctx` do żądań (domyślnie: `true`).
- `models.providers.*.authHeader`: wymusza transport poświadczeń w nagłówku `Authorization`, gdy jest wymagany.
- `models.providers.*.baseUrl`: bazowy adres URL nadrzędnego API.
- `models.providers.*.headers`: dodatkowe statyczne nagłówki do routingu proxy/dzierżawcy.
- `models.providers.*.headers`: dodatkowe statyczne nagłówki do trasowania przez proxy/dzierżawcę.
</Accordion>
<Accordion title="Request transport overrides">
`models.providers.*.request`: nadpisania transportu dla żądań HTTP dostawcy modelu.
- `request.headers`: dodatkowe nagłówki (scalane z domyślnymi dostawcy). Wartości akceptują SecretRef.
- `request.auth`: nadpisanie strategii uwierzytelniania. Tryby: `"provider-default"` (użyj wbudowanego uwierzytelniania dostawcy), `"authorization-bearer"` (z `token`), `"header"` (z `headerName`, `value`, opcjonalnym `prefix`).
- `request.proxy`: nadpisanie proxy HTTP. Tryby: `"env-proxy"` (użyj zmiennych środowiskowych `HTTP_PROXY`/`HTTPS_PROXY`), `"explicit-proxy"` (z `url`). Oba tryby akceptują opcjonalny podobiekt `tls`.
- `request.tls`: nadpisanie TLS dla połączeń bezpośrednich. Pola: `ca`, `cert`, `key`, `passphrase` (wszystkie akceptują SecretRef), `serverName`, `insecureSkipVerify`.
- `request.allowPrivateNetwork`: gdy `true`, zezwalaj na HTTPS do `baseUrl`, gdy DNS rozwiązuje się na zakresy prywatne, CGNAT lub podobne, przez osłonę pobierania HTTP dostawcy (zgoda operatora dla zaufanych, samodzielnie hostowanych punktów końcowych zgodnych z OpenAI). Adresy URL strumienia dostawcy modelu przez local loopback, takie jak `localhost`, `127.0.0.1` i `[::1]`, są dozwolone automatycznie, chyba że ustawiono to jawnie na `false`; hosty LAN, tailnet i prywatnego DNS nadal wymagają zgody. WebSocket używa tego samego `request` dla nagłówków/TLS, ale nie tej bramki SSRF pobierania. Domyślnie `false`.
- `request.auth`: nadpisanie strategii uwierzytelniania. Tryby: `"provider-default"` (używa wbudowanego uwierzytelniania dostawcy), `"authorization-bearer"` (z `token`), `"header"` (z `headerName`, `value`, opcjonalnie `prefix`).
- `request.proxy`: nadpisanie proxy HTTP. Tryby: `"env-proxy"` (używa zmiennych środowiskowych `HTTP_PROXY`/`HTTPS_PROXY`), `"explicit-proxy"` (z `url`). Oba tryby akceptują opcjonalny podobiekt `tls`.
- `request.tls`: nadpisanie TLS dla bezpośrednich połączeń. Pola: `ca`, `cert`, `key`, `passphrase` (wszystkie akceptują SecretRef), `serverName`, `insecureSkipVerify`.
- `request.allowPrivateNetwork`: gdy `true`, zezwala na HTTPS do `baseUrl`, gdy DNS rozwiązuje nazwę na zakresy prywatne, CGNAT lub podobne, przez zabezpieczenie pobierania HTTP dostawcy (świadoma zgoda operatora dla zaufanych, samodzielnie hostowanych punktów końcowych zgodnych z OpenAI). Adresy URL strumienia dostawcy modelu local loopback, takie jak `localhost`, `127.0.0.1` i `[::1]`, są dozwolone automatycznie, chyba że jawnie ustawiono to na `false`; hosty LAN, tailnet i prywatne hosty DNS nadal wymagają zgody. WebSocket używa tego samego `request` dla nagłówków/TLS, ale nie tej bramki SSRF pobierania. Domyślnie `false`.
</Accordion>
<Accordion title="Model catalog entries">
- `models.providers.*.models`: jawne wpisy katalogu modeli dostawcy.
- `models.providers.*.models.*.input`: modalności wejściowe modelu. Użyj `["text"]` dla modeli wyłącznie tekstowych i `["text", "image"]` dla natywnych modeli obrazu/wizji. Załączniki obrazów są wstrzykiwane do tur agenta tylko wtedy, gdy wybrany model jest oznaczony jako obsługujący obrazy.
- `models.providers.*.models.*.contextWindow`: metadane natywnego okna kontekstu modelu. Nadpisuje to `contextWindow` na poziomie dostawcy dla tego modelu.
- `models.providers.*.models.*.contextTokens`: opcjonalny limit kontekstu wykonawczego. Nadpisuje to `contextTokens` na poziomie dostawcy; użyj go, gdy chcesz mniejszy efektywny budżet kontekstu niż natywne `contextWindow` modelu; `openclaw models list` pokazuje obie wartości, gdy się różnią.
- `models.providers.*.models.*.compat.supportsDeveloperRole`: opcjonalna wskazówka zgodności. Dla `api: "openai-completions"` z niepustym nienatywnym `baseUrl` (host inny niż `api.openai.com`) OpenClaw wymusza to na `false` w czasie wykonania. Puste/pominięte `baseUrl` zachowuje domyślne zachowanie OpenAI.
- `models.providers.*.models.*.compat.requiresStringContent`: opcjonalna wskazówka zgodności dla zgodnych z OpenAI punktów końcowych czatu obsługujących tylko ciągi znaków. Gdy `true`, OpenClaw spłaszcza czysto tekstowe tablice `messages[].content` do zwykłych ciągów znaków przed wysłaniem żądania.
- `models.providers.*.models.*.input`: modalności wejściowe modelu. Użyj `["text"]` dla modeli tylko tekstowych oraz `["text", "image"]` dla natywnych modeli obrazu/wizji. Załączniki obrazów są wstrzykiwane do tur agenta tylko wtedy, gdy wybrany model jest oznaczony jako obsługujący obrazy.
- `models.providers.*.models.*.contextWindow`: natywne metadane okna kontekstu modelu. Nadpisuje `contextWindow` na poziomie dostawcy dla tego modelu.
- `models.providers.*.models.*.contextTokens`: opcjonalny limit kontekstu środowiska uruchomieniowego. Nadpisuje `contextTokens` na poziomie dostawcy; użyj go, gdy chcesz mniejszy efektywny budżet kontekstu niż natywne `contextWindow` modelu; `openclaw models list` pokazuje obie wartości, gdy się różnią.
- `models.providers.*.models.*.compat.supportsDeveloperRole`: opcjonalna wskazówka zgodności. Dla `api: "openai-completions"` z niepustym, nienatywnym `baseUrl` (host inny niż `api.openai.com`) OpenClaw wymusza to na `false` w środowisku uruchomieniowym. Puste/pominięte `baseUrl` zachowuje domyślne zachowanie OpenAI.
- `models.providers.*.models.*.compat.requiresStringContent`: opcjonalna wskazówka zgodności dla tekstowych punktów końcowych czatu zgodnych z OpenAI. Gdy `true`, OpenClaw spłaszcza czysto tekstowe tablice `messages[].content` do zwykłych ciągów znaków przed wysłaniem żądania.
</Accordion>
<Accordion title="Amazon Bedrock discovery">
- `plugins.entries.amazon-bedrock.config.discovery`: katalog główny ustawień automatycznego wykrywania Bedrock.
- `plugins.entries.amazon-bedrock.config.discovery.enabled`: włącz/wyłącz niejawne wykrywanie.
- `plugins.entries.amazon-bedrock.config.discovery`: korzeń ustawień automatycznego wykrywania Bedrock.
- `plugins.entries.amazon-bedrock.config.discovery.enabled`: włącza/wyłącza niejawne wykrywanie.
- `plugins.entries.amazon-bedrock.config.discovery.region`: region AWS do wykrywania.
- `plugins.entries.amazon-bedrock.config.discovery.providerFilter`: opcjonalny filtr identyfikatora dostawcy do ukierunkowanego wykrywania.
- `plugins.entries.amazon-bedrock.config.discovery.refreshInterval`: interwał odpytywania dla odświeżania wykrywania.
- `plugins.entries.amazon-bedrock.config.discovery.providerFilter`: opcjonalny filtr identyfikatora dostawcy dla ukierunkowanego wykrywania.
- `plugins.entries.amazon-bedrock.config.discovery.refreshInterval`: interwał odpytywania odświeżania wykrywania.
- `plugins.entries.amazon-bedrock.config.discovery.defaultContextWindow`: zapasowe okno kontekstu dla wykrytych modeli.
- `plugins.entries.amazon-bedrock.config.discovery.defaultMaxTokens`: zapasowy maksymalny limit tokenów wyjściowych dla wykrytych modeli.
</Accordion>
</AccordionGroup>
Interaktywne wdrażanie niestandardowego dostawcy wnioskuje wejście obrazów dla typowych identyfikatorów modeli wizyjnych, takich jak GPT-4o, Claude, Gemini, Qwen-VL, LLaVA, Pixtral, InternVL, Mllama, MiniCPM-V i GLM-4V, oraz pomija dodatkowe pytanie dla znanych rodzin wyłącznie tekstowych. Nieznane identyfikatory modeli nadal pytają o obsługę obrazów. Nieinteraktywne wdrażanie używa tego samego wnioskowania; przekaż `--custom-image-input`, aby wymusić metadane obsługi obrazów, albo `--custom-text-input`, aby wymusić metadane wyłącznie tekstowe.
Interaktywne wdrażanie niestandardowego dostawcy wywnioskuje wejście obrazu dla popularnych identyfikatorów modeli wizyjnych, takich jak GPT-4o, Claude, Gemini, Qwen-VL, LLaVA, Pixtral, InternVL, Mllama, MiniCPM-V i GLM-4V, oraz pomija dodatkowe pytanie dla znanych rodzin tylko tekstowych. Nieznane identyfikatory modeli nadal wyświetlają pytanie o obsługę obrazów. Nieinteraktywne wdrażanie używa tego samego wnioskowania; przekaż `--custom-image-input`, aby wymusić metadane obsługi obrazów, albo `--custom-text-input`, aby wymusić metadane tylko tekstowe.
### Przykłady dostawców
@ -547,7 +547,7 @@ Interaktywne wdrażanie niestandardowego dostawcy wnioskuje wejście obrazów dl
</Accordion>
<Accordion title="Modele lokalne (LM Studio)">
Zobacz [Modele lokalne](/pl/gateway/local-models). W skrócie: uruchom duży model lokalny przez LM Studio Responses API na mocnym sprzęcie; pozostaw scalone modele hostowane jako rozwiązanie awaryjne.
Zobacz [Modele lokalne](/pl/gateway/local-models). TL;DR: uruchom duży model lokalny przez LM Studio Responses API na solidnym sprzęcie; zachowaj scalone modele hostowane jako fallback.
</Accordion>
<Accordion title="MiniMax M2.7 (bezpośrednio)">
```json5
@ -623,7 +623,7 @@ Interaktywne wdrażanie niestandardowego dostawcy wnioskuje wejście obrazów dl
Dla punktu końcowego w Chinach: `baseUrl: "https://api.moonshot.cn/v1"` lub `openclaw onboard --auth-choice moonshot-api-key-cn`.
Natywne punkty końcowe Moonshot deklarują zgodność użycia strumieniowego we współdzielonym transporcie `openai-completions`, a OpenClaw opiera to na możliwościach punktu końcowego, a nie wyłącznie na wbudowanym identyfikatorze dostawcy.
Natywne punkty końcowe Moonshot deklarują zgodność użycia strumieniowania we wspólnym transporcie `openai-completions`, a OpenClaw opiera to na możliwościach punktu końcowego, a nie wyłącznie na wbudowanym identyfikatorze dostawcy.
</Accordion>
<Accordion title="OpenCode">
@ -675,7 +675,7 @@ Interaktywne wdrażanie niestandardowego dostawcy wnioskuje wejście obrazów dl
}
```
Bazowy adres URL powinien pomijać `/v1` (klient Anthropic dołącza go automatycznie). Skrót: `openclaw onboard --auth-choice synthetic-api-key`.
Bazowy URL powinien pomijać `/v1` (klient Anthropic dodaje go sam). Skrót: `openclaw onboard --auth-choice synthetic-api-key`.
</Accordion>
<Accordion title="Z.AI (GLM-4.7)">
@ -694,7 +694,7 @@ Interaktywne wdrażanie niestandardowego dostawcy wnioskuje wejście obrazów dl
- Ogólny punkt końcowy: `https://api.z.ai/api/paas/v4`
- Punkt końcowy do kodowania (domyślny): `https://api.z.ai/api/coding/paas/v4`
- Dla ogólnego punktu końcowego zdefiniuj niestandardowego dostawcę z nadpisaniem bazowego adresu URL.
- Dla ogólnego punktu końcowego zdefiniuj niestandardowego dostawcę z nadpisaniem bazowego URL.
</Accordion>
</AccordionGroup>
@ -703,7 +703,7 @@ Interaktywne wdrażanie niestandardowego dostawcy wnioskuje wejście obrazów dl
## Powiązane
- [Konfiguracja — agenty](/pl/gateway/config-agents)
- [Konfiguracja — agenci](/pl/gateway/config-agents)
- [Konfiguracja — kanały](/pl/gateway/config-channels)
- [Dokumentacja konfiguracji](/pl/gateway/configuration-reference) — inne klucze najwyższego poziomu
- [Narzędzia i pluginy](/pl/tools)
- [Narzędzia i plugins](/pl/tools)

389
docs/pl/gateway/doctor.md
View File

@ -1,15 +1,15 @@
---
read_when:
- Dodawanie lub modyfikowanie migracji doctor
- Wprowadzanie zmian w konfiguracji łamiących kompatybilność
- Wprowadzanie zmian konfiguracji powodujących niezgodność wsteczną
sidebarTitle: Doctor
summary: 'Polecenie doctor: kontrole stanu, migracje konfiguracji i kroki naprawcze'
summary: 'Polecenie doctor: kontrole kondycji, migracje konfiguracji i kroki naprawcze'
title: Diagnostyka
x-i18n:
generated_at: "2026-04-30T16:28:47Z"
generated_at: "2026-05-01T09:58:44Z"
model: gpt-5.5
provider: openai
source_hash: 89150fe2b2848f1f168b42ca6b240bc0e6a0edee4f1bcad7f79d297face9c95e
source_hash: eef5715d485609fa60bdb4aa97ee441b053a60519b9dea03b0c8ec09db157474
source_path: gateway/doctor.md
workflow: 16
---
@ -22,7 +22,7 @@ x-i18n:
openclaw doctor
```
### Tryby bez interfejsu i automatyzacji
### Tryby bezobsługowe i automatyzacji
<Tabs>
<Tab title="--yes">
@ -30,7 +30,7 @@ openclaw doctor
openclaw doctor --yes
```
Akceptuje wartości domyślne bez monitów (w tym kroki naprawy restartu/usługi/sandboxa, gdy mają zastosowanie).
Akceptuje wartości domyślne bez pytań (w tym kroki naprawy restartu/usługi/piaskownicy, gdy mają zastosowanie).
</Tab>
<Tab title="--repair">
@ -38,7 +38,7 @@ openclaw doctor
openclaw doctor --repair
```
Stosuje zalecane naprawy bez monitów (naprawy + restarty tam, gdzie jest to bezpieczne).
Stosuje zalecane naprawy bez pytań (naprawy i restarty tam, gdzie jest to bezpieczne).
</Tab>
<Tab title="--repair --force">
@ -46,7 +46,7 @@ openclaw doctor
openclaw doctor --repair --force
```
Stosuje także agresywne naprawy (nadpisuje niestandardowe konfiguracje nadzorcy).
Stosuje również agresywne naprawy (nadpisuje niestandardowe konfiguracje supervisora).
</Tab>
<Tab title="--non-interactive">
@ -54,7 +54,7 @@ openclaw doctor
openclaw doctor --non-interactive
```
Uruchamia się bez monitów i stosuje tylko bezpieczne migracje (normalizacja konfiguracji + przeniesienia stanu na dysku). Pomija działania restartu/usługi/sandboxa wymagające potwierdzenia przez człowieka. Migracje starszego stanu uruchamiają się automatycznie po wykryciu.
Uruchamia się bez pytań i stosuje tylko bezpieczne migracje (normalizacja konfiguracji i przeniesienia stanu na dysku). Pomija działania restartu/usługi/piaskownicy, które wymagają potwierdzenia przez człowieka. Migracje starszego stanu uruchamiają się automatycznie po wykryciu.
</Tab>
<Tab title="--deep">
@ -62,12 +62,12 @@ openclaw doctor
openclaw doctor --deep
```
Skanuje usługi systemowe pod kątem dodatkowych instalacji Gateway (launchd/systemd/schtasks).
Skanuje usługi systemowe pod kątem dodatkowych instalacji gatewaya (launchd/systemd/schtasks).
</Tab>
</Tabs>
Jeśli chcesz przejrzeć zmiany przed zapisem, najpierw otwórz plik konfiguracyjny:
Jeśli chcesz przejrzeć zmiany przed zapisem, najpierw otwórz plik konfiguracji:
```bash
cat ~/.openclaw/openclaw.json
@ -76,104 +76,109 @@ cat ~/.openclaw/openclaw.json
## Co robi (podsumowanie)
<AccordionGroup>
<Accordion title="Kondycja, UI i aktualizacje">
- Opcjonalna aktualizacja przed uruchomieniem dla instalacji z git (tylko interaktywnie).
- Sprawdzenie świeżości protokołu UI (przebudowuje Control UI, gdy schemat protokołu jest nowszy).
- Sprawdzenie kondycji + monit o restart.
- Podsumowanie stanu Skills (kwalifikujące się/brakujące/zablokowane) i stanu pluginów.
<Accordion title="Kondycja, interfejs użytkownika i aktualizacje">
- Opcjonalna aktualizacja przed uruchomieniem dla instalacji git (tylko interaktywnie).
- Sprawdzenie aktualności protokołu UI (przebudowuje Control UI, gdy schemat protokołu jest nowszy).
- Sprawdzenie kondycji i pytanie o restart.
- Podsumowanie statusu Skills (kwalifikujące się/brakujące/zablokowane) i status Plugin.
</Accordion>
<Accordion title="Konfiguracja i migracje">
- Normalizacja konfiguracji dla starszych wartości.
- Migracja konfiguracji Talk ze starszych płaskich pól `talk.*` do `talk.provider` + `talk.providers.<provider>`.
- Sprawdzenia migracji przeglądarki dla starszych konfiguracji rozszerzenia Chrome i gotowości Chrome MCP.
- Ostrzeżenia o nadpisaniach dostawcy OpenCode (`models.providers.opencode` / `models.providers.opencode-go`).
- Ostrzeżenia o maskowaniu Codex OAuth (`models.providers.openai-codex`).
- Sprawdzenie wymagań wstępnych TLS OAuth dla profili OpenAI Codex OAuth.
- Ostrzeżenia o nadpisaniu dostawcy OpenCode (`models.providers.opencode` / `models.providers.opencode-go`).
- Ostrzeżenia o przesłanianiu OAuth w Codex (`models.providers.openai-codex`).
- Sprawdzenie wymagań wstępnych OAuth TLS dla profili OpenAI Codex OAuth.
- Ostrzeżenia allowlisty Plugin/narzędzi, gdy `plugins.allow` jest restrykcyjne, ale polityka narzędzi nadal żąda wildcard lub narzędzi należących do Plugin.
- Migracja starszego stanu na dysku (sesje/katalog agenta/uwierzytelnianie WhatsApp).
- Migracja starszych kluczy kontraktu manifestu pluginu (`speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, `webSearchProviders` → `contracts`).
- Migracja starszego magazynu cron (`jobId`, `schedule.cron`, pola delivery/payload najwyższego poziomu, `provider` w payload, proste zadania awaryjne webhooka `notify: true`).
- Migracja starszej polityki runtime agenta do `agents.defaults.agentRuntime` i `agents.list[].agentRuntime`.
- Czyszczenie nieaktualnej konfiguracji pluginów, gdy pluginy są włączone; gdy `plugins.enabled=false`, nieaktualne odwołania do pluginów są traktowane jako nieaktywna konfiguracja izolująca i zostają zachowane.
- Migracja starszych kluczy kontraktu manifestu Plugin (`speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, `webSearchProviders` → `contracts`).
- Migracja starszego magazynu Cron (`jobId`, `schedule.cron`, pola delivery/payload najwyższego poziomu, payload `provider`, proste zadania awaryjne Webhook `notify: true`).
- Migracja starszej runtime-policy agenta do `agents.defaults.agentRuntime` i `agents.list[].agentRuntime`.
- Czyszczenie nieaktualnej konfiguracji Plugin, gdy pluginy są włączone; gdy `plugins.enabled=false`, nieaktualne odwołania do Plugin są traktowane jako nieaktywna konfiguracja izolacyjna i są zachowywane.
</Accordion>
<Accordion title="Stan i integralność">
- Inspekcja pliku blokady sesji i czyszczenie nieaktualnych blokad.
- Naprawa transkryptu sesji dla zduplikowanych gałęzi przepisywania promptów utworzonych przez dotknięte kompilacje 2026.4.24.
- Wykrywanie tombstone odzyskiwania po restarcie zaklinowanego subagenta, z obsługą `--fix` do czyszczenia nieaktualnych flag przerwanego odzyskiwania, aby startup nie traktował dalej dziecka jako przerwanego przez restart.
- Wykrywanie znaczników tombstone odzyskiwania po restarcie zablokowanego subagenta, z obsługą `--fix` do czyszczenia nieaktualnych flag przerwanego odzyskiwania, aby startup nie traktował dalej procesu potomnego jako przerwanego przez restart.
- Sprawdzenia integralności stanu i uprawnień (sesje, transkrypty, katalog stanu).
- Sprawdzenia uprawnień pliku konfiguracyjnego (chmod 600) przy uruchomieniu lokalnym.
- Kondycja uwierzytelniania modelu: sprawdza wygaśnięcie OAuth, może odświeżać wygasające tokeny i raportuje stany cooldown/disabled profilu uwierzytelniania.
- Sprawdzenia uprawnień pliku konfiguracji (chmod 600) podczas uruchamiania lokalnego.
- Kondycja uwierzytelniania modeli: sprawdza wygaśnięcie OAuth, może odświeżać wygasające tokeny i raportuje stany cooldown/disabled profilu uwierzytelniania.
- Wykrywanie dodatkowego katalogu workspace (`~/openclaw`).
</Accordion>
<Accordion title="Gateway, usługi i nadzorcy">
- Naprawa obrazu sandboxa, gdy sandboxing jest włączony.
- Migracja starszej usługi i wykrywanie dodatkowego Gateway.
<Accordion title="Gateway, usługi i supervisory">
- Naprawa obrazu piaskownicy, gdy piaskownica jest włączona.
- Migracja starszej usługi i wykrywanie dodatkowego gatewaya.
- Migracja starszego stanu kanału Matrix (w trybie `--fix` / `--repair`).
- Sprawdzenia runtime Gateway (usługa zainstalowana, ale nieuruchomiona; buforowana etykieta launchd).
- Ostrzeżenia o stanie kanałów (sondowane z uruchomionego Gateway).
- Audyt konfiguracji nadzorcy (launchd/systemd/schtasks) z opcjonalną naprawą.
- Ostrzeżenia o statusie kanałów (sondowane z działającego gatewaya).
- Audyt konfiguracji supervisora (launchd/systemd/schtasks) z opcjonalną naprawą.
- Czyszczenie środowiska wbudowanego proxy dla usług Gateway, które przechwyciły wartości powłoki `HTTP_PROXY` / `HTTPS_PROXY` / `NO_PROXY` podczas instalacji lub aktualizacji.
- Sprawdzenia dobrych praktyk runtime Gateway (Node kontra Bun, ścieżki menedżera wersji).
- Diagnostyka kolizji portu Gateway (domyślnie `18789`).
</Accordion>
<Accordion title="Uwierzytelnianie, bezpieczeństwo i parowanie">
- Ostrzeżenia bezpieczeństwa dla otwartych polityk wiadomości prywatnych.
- Sprawdzenia uwierzytelniania Gateway dla trybu tokenu lokalnego (oferuje generowanie tokenu, gdy nie istnieje żadne źródło tokenu; nie nadpisuje konfiguracji SecretRef tokenów).
- Wykrywanie problemów z parowaniem urządzeń (oczekujące żądania pierwszego parowania, oczekujące podniesienia roli/zakresu, nieaktualny dryf lokalnej pamięci podręcznej tokenu urządzenia oraz dryf uwierzytelniania sparowanego rekordu).
- Ostrzeżenia bezpieczeństwa dla otwartych polityk DM.
- Sprawdzenia uwierzytelniania Gateway dla lokalnego trybu tokenu (oferuje wygenerowanie tokenu, gdy nie istnieje źródło tokenu; nie nadpisuje konfiguracji SecretRef tokenu).
- Wykrywanie problemów z parowaniem urządzenia (oczekujące żądania pierwszego parowania, oczekujące uaktualnienia roli/zakresu, nieaktualny dryf lokalnego cache tokenu urządzenia oraz dryf uwierzytelniania sparowanego rekordu).
</Accordion>
<Accordion title="Workspace i powłoka">
- Sprawdzenie systemd linger w systemie Linux.
- Sprawdzenie rozmiaru pliku bootstrapu workspace (ostrzeżenia o obcięciu/bliskości limitu dla plików kontekstu).
- Sprawdzenie stanu uzupełniania powłoki i automatyczna instalacja/aktualizacja.
- Sprawdzenie gotowości dostawcy osadzania wyszukiwania pamięci (model lokalny, zdalny klucz API lub binarka QMD).
- Sprawdzenia instalacji ze źródeł (niezgodność workspace pnpm, brakujące zasoby UI, brakująca binarka tsx).
- Zapisuje zaktualizowaną konfigurację + metadane kreatora.
- Sprawdzenie systemd linger w Linuksie.
- Sprawdzenie rozmiaru pliku bootstrap workspace (ostrzeżenia o obcięciu/zbliżeniu do limitu dla plików kontekstu).
- Sprawdzenie statusu uzupełniania powłoki i automatyczna instalacja/aktualizacja.
- Sprawdzenie gotowości dostawcy embeddingów wyszukiwania pamięci (model lokalny, zdalny klucz API lub binarium QMD).
- Sprawdzenia instalacji ze źródeł (niezgodność workspace pnpm, brakujące zasoby UI, brakujące binarium tsx).
- Zapisuje zaktualizowaną konfigurację i metadane kreatora.
</Accordion>
</AccordionGroup>
## Uzupełnianie i reset interfejsu Dreams
## Backfill i reset interfejsu Dreams
Scena Dreams w Control UI zawiera akcje **Backfill**, **Reset** i **Clear Grounded** dla przepływu pracy grounded dreaming. Te akcje używają metod RPC w stylu Gateway doctor, ale **nie** są częścią naprawy/migracji CLI `openclaw doctor`.
Scena Dreams w Control UI zawiera działania **Backfill**, **Reset** i **Clear Grounded** dla przepływu pracy ugruntowanego Dreaming. Te działania używają metod RPC w stylu doctora gatewaya, ale **nie** są częścią naprawy/migracji CLI `openclaw doctor`.
Co robią:
- **Backfill** skanuje historyczne pliki `memory/YYYY-MM-DD.md` w aktywnym workspace, uruchamia przebieg dziennika grounded REM i zapisuje odwracalne wpisy uzupełnienia w `DREAMS.md`.
- **Reset** usuwa tylko te oznaczone wpisy dziennika uzupełnienia z `DREAMS.md`.
- **Clear Grounded** usuwa tylko przygotowane wpisy krótkoterminowe wyłącznie grounded, które pochodzą z historycznego odtworzenia i nie zgromadziły jeszcze żywego recall ani dziennego wsparcia.
- **Backfill** skanuje historyczne pliki `memory/YYYY-MM-DD.md` w aktywnym workspace, uruchamia przebieg ugruntowanego dziennika REM i zapisuje odwracalne wpisy backfill do `DREAMS.md`.
- **Reset** usuwa tylko te oznaczone wpisy dziennika backfill z `DREAMS.md`.
- **Clear Grounded** usuwa tylko przygotowane, wyłącznie ugruntowane wpisy krótkoterminowe, które pochodzą z odtworzenia historii i nie zgromadziły jeszcze żywego recall ani dziennego wsparcia.
Czego same **nie** robią:
- nie edytują `MEMORY.md`
- nie uruchamiają pełnych migracji doctor
- nie przygotowują automatycznie kandydatów grounded do aktywnego magazynu promocji krótkoterminowej, chyba że najpierw jawnie uruchomisz przygotowaną ścieżkę CLI
- nie uruchamiają pełnych migracji doctora
- nie przygotowują automatycznie ugruntowanych kandydatów w magazynie promocji krótkoterminowej na żywo, chyba że najpierw jawnie uruchomisz przygotowaną ścieżkę CLI
Jeśli chcesz, aby historyczne odtworzenie grounded wpływało na normalną głęboką ścieżkę promocji, użyj zamiast tego przepływu CLI:
Jeśli chcesz, aby ugruntowane historyczne odtworzenie wpływało na zwykłą ścieżkę głębokiej promocji, użyj zamiast tego przepływu CLI:
```bash
openclaw memory rem-backfill --path ./memory --stage-short-term
```
Przygotowuje to trwałych kandydatów grounded w magazynie krótkoterminowego Dreaming, pozostawiając `DREAMS.md` jako powierzchnię przeglądu.
To przygotowuje ugruntowanych trwałych kandydatów w krótkoterminowym magazynie Dreaming, pozostawiając `DREAMS.md` jako powierzchnię przeglądu.
## Szczegółowe zachowanie i uzasadnienie
<AccordionGroup>
<Accordion title="0. Opcjonalna aktualizacja (instalacje git)">
Jeśli jest to checkout git, a doctor działa interaktywnie, przed uruchomieniem doctor oferuje aktualizację (fetch/rebase/build).
Jeśli jest to checkout git, a doctor działa interaktywnie, proponuje aktualizację (fetch/rebase/build) przed uruchomieniem doctora.
</Accordion>
<Accordion title="1. Normalizacja konfiguracji">
Jeśli konfiguracja zawiera starsze kształty wartości (na przykład `messages.ackReaction` bez nadpisania specyficznego dla kanału), doctor normalizuje je do bieżącego schematu.
Obejmuje to starsze płaskie pola Talk. Bieżąca publiczna konfiguracja Talk to `talk.provider` + `talk.providers.<provider>`. Doctor przepisuje stare kształty `talk.voiceId` / `talk.voiceAliases` / `talk.modelId` / `talk.outputFormat` / `talk.apiKey` do mapy dostawcy.
Obejmuje to starsze płaskie pola Talk. Bieżąca publiczna konfiguracja Talk to `talk.provider` + `talk.providers.<provider>`. Doctor przepisuje stare kształty `talk.voiceId` / `talk.voiceAliases` / `talk.modelId` / `talk.outputFormat` / `talk.apiKey` do mapy dostawców.
Doctor ostrzega także, gdy `plugins.allow` nie jest puste, a polityka narzędzi używa
wpisów wildcard lub narzędzi należących do Plugin. `tools.allow: ["*"]` pasuje tylko do narzędzi
z pluginów, które faktycznie się ładują; nie omija wyłącznej allowlisty Plugin.
</Accordion>
<Accordion title="2. Migracje starszych kluczy konfiguracji">
Gdy konfiguracja zawiera wycofane klucze, inne polecenia odmawiają uruchomienia i proszą o uruchomienie `openclaw doctor`.
Gdy konfiguracja zawiera przestarzałe klucze, inne polecenia odmawiają uruchomienia i proszą o uruchomienie `openclaw doctor`.
Doctor:
@ -181,7 +186,7 @@ Przygotowuje to trwałych kandydatów grounded w magazynie krótkoterminowego Dr
- Pokaże zastosowaną migrację.
- Przepisze `~/.openclaw/openclaw.json` ze zaktualizowanym schematem.
Gateway także automatycznie uruchamia migracje doctor przy starcie, gdy wykryje starszy format konfiguracji, więc nieaktualne konfiguracje są naprawiane bez ręcznej interwencji. Migracje magazynu zadań Cron obsługuje `openclaw doctor --fix`.
Gateway automatycznie uruchamia też migracje doctora przy starcie, gdy wykryje starszy format konfiguracji, więc nieaktualne konfiguracje są naprawiane bez ręcznej interwencji. Migracje magazynu zadań Cron są obsługiwane przez `openclaw doctor --fix`.
Bieżące migracje:
@ -206,72 +211,72 @@ Przygotowuje to trwałych kandydatów grounded w magazynie krótkoterminowego Dr
- `plugins.entries.voice-call.config.streaming.sttProvider` → `plugins.entries.voice-call.config.streaming.provider`
- `plugins.entries.voice-call.config.streaming.openaiApiKey|sttModel|silenceDurationMs|vadThreshold` → `plugins.entries.voice-call.config.streaming.providers.openai.*`
- `bindings[].match.accountID` → `bindings[].match.accountId`
- Dla kanałów z nazwanymi `accounts`, ale utrzymującymi się wartościami kanału najwyższego poziomu dla pojedynczego konta, przenosi te wartości o zakresie konta do wypromowanego konta wybranego dla tego kanału (`accounts.default` dla większości kanałów; Matrix może zachować istniejący pasujący nazwany/domyślny cel)
- W przypadku kanałów z nazwanymi `accounts`, ale pozostawionymi jednokontowymi wartościami kanału najwyższego poziomu, przenieś te wartości o zakresie konta do promowanego konta wybranego dla tego kanału (`accounts.default` dla większości kanałów; Matrix może zachować istniejący zgodny nazwany/domyślny cel)
- `identity` → `agents.list[].identity`
- `agent.*` → `agents.defaults` + `tools.*` (tools/elevated/exec/sandbox/subagents)
- `agent.model`/`allowedModels`/`modelAliases`/`modelFallbacks`/`imageModelFallbacks` → `agents.defaults.models` + `agents.defaults.model.primary/fallbacks` + `agents.defaults.imageModel.primary/fallbacks`
- usuwa `agents.defaults.llm`; użyj `models.providers.<id>.timeoutSeconds` dla limitów czasu wolnych dostawców/modeli
- usuń `agents.defaults.llm`; użyj `models.providers.<id>.timeoutSeconds` dla limitów czasu wolnych dostawców/modeli
- `browser.ssrfPolicy.allowPrivateNetwork` → `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork`
- `browser.profiles.*.driver: "extension"` → `"existing-session"`
- usuwa `browser.relayBindHost` (starsze ustawienie relay rozszerzenia)
- starsze `models.providers.*.api: "openai"` → `"openai-completions"` (startup Gateway także pomija dostawców, których `api` ustawiono na przyszłą lub nieznaną wartość enum, zamiast kończyć się niepowodzeniem w trybie zamkniętym)
- usuń `browser.relayBindHost` (starsze ustawienie przekaźnika rozszerzenia)
- starsze `models.providers.*.api: "openai"` → `"openai-completions"` (podczas uruchamiania Gateway pomija też dostawców, których `api` jest ustawione na przyszłą lub nieznaną wartość enum, zamiast kończyć działanie błędem)
Ostrzeżenia doctor zawierają także wskazówki dotyczące domyślnego konta dla kanałów z wieloma kontami:
Ostrzeżenia doctor obejmują też wskazówki dotyczące domyślnego konta dla kanałów wielokontowych:
- Jeśli skonfigurowano co najmniej dwa wpisy `channels.<channel>.accounts` bez `channels.<channel>.defaultAccount` ani `accounts.default`, doctor ostrzega, że routing awaryjny może wybrać nieoczekiwane konto.
- Jeśli skonfigurowano co najmniej dwa wpisy `channels.<channel>.accounts` bez `channels.<channel>.defaultAccount` lub `accounts.default`, doctor ostrzega, że routing awaryjny może wybrać nieoczekiwane konto.
- Jeśli `channels.<channel>.defaultAccount` jest ustawione na nieznany identyfikator konta, doctor ostrzega i wypisuje skonfigurowane identyfikatory kont.
</Accordion>
<Accordion title="2b. OpenCode provider overrides">
Jeśli ręcznie dodano `models.providers.opencode`, `opencode-zen` lub `opencode-go`, zastępuje to wbudowany katalog OpenCode z `@mariozechner/pi-ai`. Może to wymusić modele na niewłaściwe API albo wyzerować koszty. Doctor ostrzega, aby można było usunąć nadpisanie i przywrócić routing API oraz koszty dla poszczególnych modeli.
<Accordion title="2b. Nadpisania dostawcy OpenCode">
Jeśli ręcznie dodano `models.providers.opencode`, `opencode-zen` lub `opencode-go`, nadpisuje to wbudowany katalog OpenCode z `@mariozechner/pi-ai`. Może to wymusić modele na niewłaściwym API albo wyzerować koszty. Doctor ostrzega, aby można było usunąć nadpisanie i przywrócić routing API oraz koszty per model.
</Accordion>
<Accordion title="2c. Browser migration and Chrome MCP readiness">
Jeśli konfiguracja przeglądarki nadal wskazuje usuniętą ścieżkę rozszerzenia Chrome, doctor normalizuje ją do bieżącego modelu dołączania Chrome MCP lokalnego dla hosta:
<Accordion title="2c. Migracja przeglądarki i gotowość Chrome MCP">
Jeśli konfiguracja przeglądarki nadal wskazuje usuniętą ścieżkę rozszerzenia Chrome, doctor normalizuje ją do bieżącego modelu dołączania host-local Chrome MCP:
- `browser.profiles.*.driver: "extension"` staje się `"existing-session"`
- `browser.relayBindHost` jest usuwane
Doctor audytuje także lokalną dla hosta ścieżkę Chrome MCP, gdy używasz `defaultProfile: "user"` lub skonfigurowanego profilu `existing-session`:
Doctor audytuje też ścieżkę host-local Chrome MCP, gdy używasz `defaultProfile: "user"` lub skonfigurowanego profilu `existing-session`:
- sprawdza, czy Google Chrome jest zainstalowany na tym samym hoście dla domyślnych profili automatycznego łączenia
- sprawdza wykrytą wersję Chrome i ostrzega, gdy jest niższa niż Chrome 144
- przypomina o włączeniu zdalnego debugowania na stronie inspekcji przeglądarki (na przykład `chrome://inspect/#remote-debugging`, `brave://inspect/#remote-debugging` lub `edge://inspect/#remote-debugging`)
Doctor nie może włączyć za Ciebie ustawienia po stronie Chrome. Lokalny dla hosta Chrome MCP nadal wymaga:
Doctor nie może włączyć za Ciebie ustawienia po stronie Chrome. Host-local Chrome MCP nadal wymaga:
- przeglądarki opartej na Chromium 144+ na hoście gateway/node
- przeglądarki opartej na Chromium w wersji 144+ na hoście gateway/node
- lokalnie uruchomionej przeglądarki
- włączonego zdalnego debugowania w tej przeglądarce
- zatwierdzenia pierwszego monitu zgody na dołączenie w przeglądarce
Gotowość tutaj dotyczy wyłącznie lokalnych wymagań wstępnych dołączania. Existing-session zachowuje obecne limity tras Chrome MCP; zaawansowane trasy, takie jak `responsebody`, eksport PDF, przechwytywanie pobrań i akcje wsadowe, nadal wymagają zarządzanej przeglądarki albo surowego profilu CDP.
Gotowość tutaj dotyczy tylko lokalnych wymagań dołączenia. Existing-session zachowuje bieżące limity tras Chrome MCP; zaawansowane trasy, takie jak `responsebody`, eksport PDF, przechwytywanie pobrań i akcje wsadowe, nadal wymagają zarządzanej przeglądarki albo surowego profilu CDP.
Ta kontrola **nie** dotyczy przepływów Docker, sandbox, remote-browser ani innych przepływów headless. One nadal używają surowego CDP.
Ta kontrola **nie** dotyczy Docker, sandbox, remote-browser ani innych przepływów headless. One nadal używają surowego CDP.
</Accordion>
<Accordion title="2d. OAuth TLS prerequisites">
Gdy skonfigurowano profil OpenAI Codex OAuth, doctor sprawdza punkt końcowy autoryzacji OpenAI, aby zweryfikować, czy lokalny stos TLS Node/OpenSSL potrafi zweryfikować łańcuch certyfikatów. Jeśli test zakończy się błędem certyfikatu (na przykład `UNABLE_TO_GET_ISSUER_CERT_LOCALLY`, wygasły certyfikat albo certyfikat samopodpisany), doctor wypisuje wskazówki naprawy właściwe dla platformy. W macOS z Node z Homebrew naprawą jest zwykle `brew postinstall ca-certificates`. Z `--deep` test działa nawet wtedy, gdy Gateway jest zdrowy.
<Accordion title="2d. Wymagania wstępne OAuth TLS">
Gdy skonfigurowany jest profil OpenAI Codex OAuth, doctor odpytuje punkt końcowy autoryzacji OpenAI, aby zweryfikować, czy lokalny stos TLS Node/OpenSSL może zweryfikować łańcuch certyfikatów. Jeśli próba zakończy się błędem certyfikatu (na przykład `UNABLE_TO_GET_ISSUER_CERT_LOCALLY`, wygasły certyfikat lub certyfikat z podpisem własnym), doctor wypisuje wskazówki naprawy specyficzne dla platformy. W macOS z Node z Homebrew naprawą zwykle jest `brew postinstall ca-certificates`. Z `--deep` próba działa nawet wtedy, gdy gateway jest zdrowy.
</Accordion>
<Accordion title="2e. Codex OAuth provider overrides">
Jeśli wcześniej dodano starsze ustawienia transportu OpenAI pod `models.providers.openai-codex`, mogą one przesłaniać wbudowaną ścieżkę dostawcy Codex OAuth, której nowsze wydania używają automatycznie. Doctor ostrzega, gdy widzi te stare ustawienia transportu obok Codex OAuth, aby można było usunąć lub przepisać przestarzałe nadpisanie transportu i odzyskać wbudowane zachowanie routingu/fallback. Niestandardowe proxy i nadpisania obejmujące tylko nagłówki są nadal obsługiwane i nie wywołują tego ostrzeżenia.
<Accordion title="2e. Nadpisania dostawcy Codex OAuth">
Jeśli wcześniej dodano starsze ustawienia transportu OpenAI pod `models.providers.openai-codex`, mogą one przesłonić wbudowaną ścieżkę dostawcy Codex OAuth, której nowsze wydania używają automatycznie. Doctor ostrzega, gdy widzi te stare ustawienia transportu razem z Codex OAuth, aby można było usunąć albo przepisać nieaktualne nadpisanie transportu i odzyskać wbudowane zachowanie routingu/fallback. Niestandardowe proxy i nadpisania wyłącznie nagłówków są nadal obsługiwane i nie wywołują tego ostrzeżenia.
</Accordion>
<Accordion title="2f. Codex plugin route warnings">
Gdy włączony jest dołączony Plugin Codex, doctor sprawdza także, czy główne referencje modeli `openai-codex/*` nadal rozwiązują się przez domyślny runner PI. Ta kombinacja jest prawidłowa, gdy chcesz używać uwierzytelniania Codex OAuth/subskrypcji przez PI, ale łatwo pomylić ją z natywnym harness app-server Codex. Doctor ostrzega i wskazuje jawną postać app-server: `openai/*` plus `agentRuntime.id: "codex"` albo `OPENCLAW_AGENT_RUNTIME=codex`.
<Accordion title="2f. Ostrzeżenia tras Pluginu Codex">
Gdy włączony jest dołączony Plugin Codex, doctor sprawdza też, czy referencje modeli głównych `openai-codex/*` nadal rozwiązują się przez domyślny runner PI. Taka kombinacja jest poprawna, gdy chcesz używać uwierzytelniania Codex OAuth/subskrypcji przez PI, ale łatwo pomylić ją z natywną uprzężą app-server Codex. Doctor ostrzega i wskazuje jawną postać app-server: `openai/*` plus `agentRuntime.id: "codex"` lub `OPENCLAW_AGENT_RUNTIME=codex`.
Doctor nie naprawia tego automatycznie, ponieważ obie trasy są prawidłowe:
Doctor nie naprawia tego automatycznie, ponieważ obie trasy są poprawne:
- `openai-codex/*` + PI oznacza „użyj uwierzytelniania Codex OAuth/subskrypcji przez zwykły runner OpenClaw”.
- `openai/*` + `runtime: "codex"` oznacza „uruchom osadzony turn przez natywny app-server Codex”.
- `/codex ...` oznacza „kontroluj albo podłącz natywną rozmowę Codex z czatu”.
- `/acp ...` albo `runtime: "acp"` oznacza „użyj zewnętrznego adaptera ACP/acpx”.
- `openai-codex/*` + PI oznacza „użyj uwierzytelniania Codex OAuth/subskrypcji przez normalny runner OpenClaw”.
- `openai/*` + `runtime: "codex"` oznacza „uruchom osadzoną turę przez natywny app-server Codex”.
- `/codex ...` oznacza „kontroluj lub powiąż natywną konwersację Codex z czatu”.
- `/acp ...` lub `runtime: "acp"` oznacza „użyj zewnętrznego adaptera ACP/acpx”.
Jeśli pojawi się ostrzeżenie, wybierz zamierzoną trasę i ręcznie edytuj konfigurację. Pozostaw ostrzeżenie bez zmian, gdy PI Codex OAuth jest zamierzone.
Jeśli pojawi się ostrzeżenie, wybierz zamierzoną trasę i ręcznie edytuj konfigurację. Zachowaj ostrzeżenie bez zmian, gdy PI Codex OAuth jest zamierzone.
</Accordion>
<Accordion title="3. Legacy state migrations (disk layout)">
<Accordion title="3. Migracje starszego stanu (układ dysku)">
Doctor może migrować starsze układy na dysku do bieżącej struktury:
- Magazyn sesji i transkrypty:
- Magazyn sesji + transkrypty:
- z `~/.openclaw/sessions/` do `~/.openclaw/agents/<agentId>/sessions/`
- Katalog agenta:
- z `~/.openclaw/agent/` do `~/.openclaw/agents/<agentId>/agent/`
@ -279,209 +284,209 @@ Przygotowuje to trwałych kandydatów grounded w magazynie krótkoterminowego Dr
- ze starszego `~/.openclaw/credentials/*.json` (oprócz `oauth.json`)
- do `~/.openclaw/credentials/whatsapp/<accountId>/...` (domyślny identyfikator konta: `default`)
Te migracje są best-effort i idempotentne; doctor wyemituje ostrzeżenia, gdy pozostawi jakiekolwiek starsze foldery jako kopie zapasowe. Gateway/CLI automatycznie migruje też starsze sesje i katalog agenta przy uruchomieniu, aby historia/uwierzytelnianie/modele trafiły do ścieżki per-agent bez ręcznego uruchamiania doctor. Ujednolicanie dostawcy talk/mapy dostawców porównuje teraz według równości strukturalnej, więc różnice wynikające wyłącznie z kolejności kluczy nie wywołują już powtarzających się zmian no-op `doctor --fix`.
Te migracje są wykonywane według najlepszych starań i są idempotentne; doctor wyemituje ostrzeżenia, gdy pozostawi jakiekolwiek starsze foldery jako kopie zapasowe. Gateway/CLI automatycznie migruje też starsze sesje i katalog agenta podczas uruchamiania, dzięki czemu historia/uwierzytelnianie/modele trafiają do ścieżki per agent bez ręcznego uruchamiania doctor. Normalizacja dostawcy/mapy dostawców talk porównuje teraz przez równość strukturalną, więc różnice dotyczące wyłącznie kolejności kluczy nie wywołują już powtarzanych zmian no-op `doctor --fix`.
</Accordion>
<Accordion title="3a. Legacy plugin manifest migrations">
Doctor skanuje wszystkie zainstalowane manifesty Plugin pod kątem przestarzałych kluczy możliwości najwyższego poziomu (`speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, `webSearchProviders`). Po ich znalezieniu proponuje przeniesienie ich do obiektu `contracts` i przepisanie pliku manifestu w miejscu. Ta migracja jest idempotentna; jeśli klucz `contracts` ma już te same wartości, starszy klucz jest usuwany bez duplikowania danych.
<Accordion title="3a. Migracje starszych manifestów Pluginów">
Doctor skanuje wszystkie zainstalowane manifesty Pluginów pod kątem przestarzałych kluczy możliwości najwyższego poziomu (`speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, `webSearchProviders`). Po ich znalezieniu oferuje przeniesienie ich do obiektu `contracts` i przepisanie pliku manifestu w miejscu. Ta migracja jest idempotentna; jeśli klucz `contracts` ma już te same wartości, starszy klucz jest usuwany bez duplikowania danych.
</Accordion>
<Accordion title="3b. Legacy cron store migrations">
Doctor sprawdza także magazyn zadań cron (`~/.openclaw/cron/jobs.json` domyślnie albo `cron.store`, gdy został nadpisany) pod kątem starych kształtów zadań, które harmonogram nadal akceptuje dla zgodności.
<Accordion title="3b. Migracje starszego magazynu Cron">
Doctor sprawdza też magazyn zadań Cron (`~/.openclaw/cron/jobs.json` domyślnie albo `cron.store`, gdy nadpisano) pod kątem starych kształtów zadań, które harmonogram nadal akceptuje dla kompatybilności.
Bieżące porządki cron obejmują:
Bieżące porządki Cron obejmują:
- `jobId` → `id`
- `schedule.cron` → `schedule.expr`
- pola payload najwyższego poziomu (`message`, `model`, `thinking`, ...) → `payload`
- pola dostarczania najwyższego poziomu (`deliver`, `channel`, `to`, `provider`, ...) → `delivery`
- aliasy dostarczania `provider` w payload → jawne `delivery.channel`
- proste starsze zadania fallback webhook `notify: true` → jawne `delivery.mode="webhook"` z `delivery.to=cron.webhook`
- pola delivery najwyższego poziomu (`deliver`, `channel`, `to`, `provider`, ...) → `delivery`
- aliasy delivery `provider` w payload → jawne `delivery.channel`
- proste starsze zadania fallback webhook z `notify: true` → jawne `delivery.mode="webhook"` z `delivery.to=cron.webhook`
Doctor automatycznie migruje zadania `notify: true` tylko wtedy, gdy może to zrobić bez zmiany zachowania. Jeśli zadanie łączy starszy fallback notify z istniejącym trybem dostarczania innym niż webhook, doctor ostrzega i pozostawia to zadanie do ręcznego przeglądu.
Doctor automatycznie migruje zadania `notify: true` tylko wtedy, gdy może to zrobić bez zmiany zachowania. Jeśli zadanie łączy starszy fallback notify z istniejącym trybem delivery innym niż webhook, doctor ostrzega i pozostawia to zadanie do ręcznego przeglądu.
</Accordion>
<Accordion title="3c. Session lock cleanup">
Doctor skanuje każdy katalog sesji agenta pod kątem przestarzałych plików blokad zapisu — plików pozostawionych, gdy sesja zakończyła się nienormalnie. Dla każdego znalezionego pliku blokady raportuje: ścieżkę, PID, czy PID nadal żyje, wiek blokady oraz czy uznaje się ją za przestarzałą (martwy PID albo starsza niż 30 minut). W trybie `--fix` / `--repair` automatycznie usuwa przestarzałe pliki blokad; w przeciwnym razie wypisuje notatkę i instruuje, aby uruchomić ponownie z `--fix`.
<Accordion title="3c. Czyszczenie blokad sesji">
Doctor skanuje każdy katalog sesji agenta pod kątem nieaktualnych plików blokad zapisu — plików pozostawionych po nienormalnym zakończeniu sesji. Dla każdego znalezionego pliku blokady raportuje: ścieżkę, PID, czy PID nadal żyje, wiek blokady oraz czy jest uznawana za nieaktualną (martwy PID albo starsza niż 30 minut). W trybie `--fix` / `--repair` automatycznie usuwa nieaktualne pliki blokad; w przeciwnym razie wypisuje notatkę i instruuje, aby uruchomić ponownie z `--fix`.
</Accordion>
<Accordion title="3d. Session transcript branch repair">
Doctor skanuje pliki JSONL sesji agenta pod kątem zduplikowanego kształtu gałęzi utworzonego przez błąd przepisywania transkryptu prompt z 2026.4.24: porzucony turn użytkownika z wewnętrznym kontekstem runtime OpenClaw oraz aktywny sibling zawierający ten sam widoczny prompt użytkownika. W trybie `--fix` / `--repair` doctor tworzy kopię zapasową każdego dotkniętego pliku obok oryginału i przepisuje transkrypt do aktywnej gałęzi, aby czytniki historii gateway i pamięci nie widziały już zduplikowanych turnów.
<Accordion title="3d. Naprawa gałęzi transkryptu sesji">
Doctor skanuje pliki JSONL sesji agenta pod kątem zduplikowanego kształtu gałęzi utworzonego przez błąd przepisywania transkryptu promptu z 2026.4.24: porzuconą turę użytkownika z wewnętrznym kontekstem runtime OpenClaw oraz aktywne rodzeństwo zawierające ten sam widoczny prompt użytkownika. W trybie `--fix` / `--repair` doctor tworzy kopię zapasową każdego dotkniętego pliku obok oryginału i przepisuje transkrypt do aktywnej gałęzi, aby historia gateway i czytniki pamięci nie widziały już zduplikowanych tur.
</Accordion>
<Accordion title="4. State integrity checks (session persistence, routing, and safety)">
Katalog stanu jest operacyjnym pniem mózgu. Jeśli zniknie, tracisz sesje, poświadczenia, logi i konfigurację (chyba że masz kopie zapasowe gdzie indziej).
<Accordion title="4. Kontrole integralności stanu (utrwalanie sesji, routing i bezpieczeństwo)">
Katalog stanu jest operacyjnym rdzeniem. Jeśli zniknie, utracisz sesje, poświadczenia, logi i konfigurację (chyba że masz kopie zapasowe gdzie indziej).
Doctor sprawdza:
- **Brak katalogu stanu**: ostrzega przed katastrofalną utratą stanu, prosi o ponowne utworzenie katalogu i przypomina, że nie może odzyskać brakujących danych.
- **Uprawnienia katalogu stanu**: weryfikuje możliwość zapisu; proponuje naprawę uprawnień (i emituje wskazówkę `chown`, gdy wykryje niezgodność właściciela/grupy).
- **Katalog stanu synchronizowany z chmurą w macOS**: ostrzega, gdy stan rozwiązuje się pod iCloud Drive (`~/Library/Mobile Documents/com~apple~CloudDocs/...`) albo `~/Library/CloudStorage/...`, ponieważ ścieżki oparte na synchronizacji mogą powodować wolniejsze I/O i wyścigi blokad/synchronizacji.
- **Katalog stanu Linux na SD albo eMMC**: ostrzega, gdy stan rozwiązuje się do źródła montowania `mmcblk*`, ponieważ losowe I/O oparte na SD albo eMMC może być wolniejsze i szybciej się zużywać przy zapisach sesji i poświadczeń.
- **Uprawnienia katalogu stanu**: weryfikuje możliwość zapisu; oferuje naprawę uprawnień (i emituje wskazówkę `chown`, gdy wykryto niezgodność właściciela/grupy).
- **Katalog stanu synchronizowany z chmurą w macOS**: ostrzega, gdy stan jest rozwiązywany pod iCloud Drive (`~/Library/Mobile Documents/com~apple~CloudDocs/...`) lub `~/Library/CloudStorage/...`, ponieważ ścieżki oparte na synchronizacji mogą powodować wolniejsze I/O oraz wyścigi blokad/synchronizacji.
- **Katalog stanu Linux SD lub eMMC**: ostrzega, gdy stan jest rozwiązywany do źródła montowania `mmcblk*`, ponieważ losowe I/O oparte na SD lub eMMC może być wolniejsze i zużywać się szybciej przy zapisach sesji i poświadczeń.
- **Brak katalogów sesji**: `sessions/` i katalog magazynu sesji są wymagane do utrwalania historii i unikania awarii `ENOENT`.
- **Niezgodność transkryptu**: ostrzega, gdy najnowsze wpisy sesji mają brakujące pliki transkryptu.
- **Główna sesja „1-line JSONL”**: sygnalizuje, gdy główny transkrypt ma tylko jeden wiersz (historia się nie kumuluje).
- **Wiele katalogów stanu**: ostrzega, gdy istnieje wiele folderów `~/.openclaw` w różnych katalogach domowych albo gdy `OPENCLAW_STATE_DIR` wskazuje gdzie indziej (historia może zostać podzielona między instalacje).
- **Przypomnienie o trybie zdalnym**: jeśli `gateway.mode=remote`, doctor przypomina, aby uruchomić go na zdalnym hoście (stan znajduje się tam).
- **Uprawnienia pliku konfiguracji**: ostrzega, jeśli `~/.openclaw/openclaw.json` jest czytelny dla grupy/świata, i proponuje zaostrzenie do `600`.
- **Niezgodność transkrypcji**: ostrzega, gdy ostatnie wpisy sesji mają brakujące pliki transkrypcji.
- **Główna sesja „1-line JSONL”**: sygnalizuje, gdy główna transkrypcja ma tylko jeden wiersz (historia się nie gromadzi).
- **Wiele katalogów stanu**: ostrzega, gdy istnieje wiele folderów `~/.openclaw` w katalogach domowych lub gdy `OPENCLAW_STATE_DIR` wskazuje gdzie indziej (historia może rozdzielić się między instalacjami).
- **Przypomnienie o trybie zdalnym**: jeśli `gateway.mode=remote`, doctor przypomina, aby uruchomić go na hoście zdalnym (stan znajduje się tam).
- **Uprawnienia pliku konfiguracji**: ostrzega, jeśli `~/.openclaw/openclaw.json` jest czytelny dla grupy/świata, i oferuje zaostrzenie do `600`.
</Accordion>
<Accordion title="5. Model auth health (OAuth expiry)">
Doctor sprawdza profile OAuth w magazynie uwierzytelniania, ostrzega, gdy tokeny wkrótce wygasną lub wygasły, i może je odświeżyć, gdy jest to bezpieczne. Jeśli profil OAuth/token Anthropic jest przestarzały, sugeruje klucz API Anthropic albo ścieżkę setup-token Anthropic. Monity odświeżania pojawiają się tylko przy uruchomieniu interaktywnym (TTY); `--non-interactive` pomija próby odświeżenia.
<Accordion title="5. Kondycja uwierzytelniania modelu (wygaśnięcie OAuth)">
Doctor sprawdza profile OAuth w magazynie uwierzytelniania, ostrzega, gdy tokeny wkrótce wygasną lub wygasły, i może je odświeżyć, gdy jest to bezpieczne. Jeśli profil OAuth/tokenu Anthropic jest nieaktualny, sugeruje klucz API Anthropic albo ścieżkę setup-token Anthropic. Monity o odświeżenie pojawiają się tylko przy uruchomieniu interaktywnym (TTY); `--non-interactive` pomija próby odświeżenia.
Gdy odświeżenie OAuth trwale się nie powiedzie (na przykład `refresh_token_reused`, `invalid_grant` albo dostawca informujący, że trzeba zalogować się ponownie), doctor zgłasza, że wymagane jest ponowne uwierzytelnienie, i wypisuje dokładne polecenie `openclaw models auth login --provider ...` do uruchomienia.
Gdy odświeżenie OAuth trwale się nie powiedzie (na przykład `refresh_token_reused`, `invalid_grant` albo dostawca poleci ponowne zalogowanie), doctor zgłasza, że wymagane jest ponowne uwierzytelnienie, i wypisuje dokładne polecenie `openclaw models auth login --provider ...` do uruchomienia.
Doctor raportuje też profile uwierzytelniania, które są tymczasowo niedostępne z powodu:
Doctor zgłasza też profile uwierzytelniania, które są tymczasowo niedostępne z powodu:
- krótkich cooldownów (limity szybkości/timeouty/błędy uwierzytelniania)
- krótkich okresów wyciszenia (limity szybkości/limity czasu/błędy uwierzytelniania)
- dłuższych wyłączeń (błędy rozliczeń/kredytów)
</Accordion>
<Accordion title="6. Walidacja modelu hooków">
Jeśli `hooks.gmail.model` jest ustawione, narzędzie diagnostyczne waliduje odwołanie do modelu względem katalogu i listy dozwolonych oraz ostrzega, gdy nie da się go rozpoznać albo jest niedozwolone.
Jeśli ustawiono `hooks.gmail.model`, doctor waliduje odwołanie do modelu względem katalogu i listy dozwolonych oraz ostrzega, gdy nie uda się go rozwiązać albo jest niedozwolone.
</Accordion>
<Accordion title="7. Naprawa obrazu piaskownicy">
Gdy piaskownica jest włączona, narzędzie diagnostyczne sprawdza obrazy Docker i proponuje zbudowanie albo przełączenie na starsze nazwy, jeśli bieżącego obrazu brakuje.
Gdy piaskownica jest włączona, doctor sprawdza obrazy Docker i oferuje zbudowanie lub przełączenie na starsze nazwy, jeśli bieżący obraz nie istnieje.
</Accordion>
<Accordion title="7b. Zależności środowiska uruchomieniowego dołączonych pluginów">
Narzędzie diagnostyczne weryfikuje zależności środowiska uruchomieniowego tylko dla dołączonych pluginów, które są aktywne w bieżącej konfiguracji albo włączone przez domyślne ustawienie w dołączonym manifeście, na przykład `plugins.entries.discord.enabled: true`, starsze `channels.discord.enabled: true`, skonfigurowane `models.providers.*` / odwołania do modeli agentów albo dołączony plugin domyślnie włączony bez przypisania do dostawcy. Jeśli czegoś brakuje, narzędzie diagnostyczne zgłasza pakiety i instaluje je w trybie `openclaw doctor --fix` / `openclaw doctor --repair`. Zewnętrzne pluginy nadal używają `openclaw plugins install` / `openclaw plugins update`; narzędzie diagnostyczne nie instaluje zależności dla dowolnych ścieżek pluginów.
<Accordion title="7b. Zależności runtime dołączonych pluginów">
Doctor weryfikuje zależności runtime tylko dla dołączonych pluginów, które są aktywne w bieżącej konfiguracji lub włączone przez domyślne ustawienie ich dołączonego manifestu, na przykład `plugins.entries.discord.enabled: true`, starsze `channels.discord.enabled: true`, skonfigurowane `models.providers.*` / odwołania do modeli agentów albo domyślnie włączony dołączony plugin bez własności dostawcy. Jeśli czegoś brakuje, doctor zgłasza pakiety i instaluje je w trybie `openclaw doctor --fix` / `openclaw doctor --repair`. Zewnętrzne pluginy nadal używają `openclaw plugins install` / `openclaw plugins update`; doctor nie instaluje zależności dla dowolnych ścieżek pluginów.
Podczas naprawy wykonywanej przez narzędzie diagnostyczne instalacje zależności npm środowiska uruchomieniowego dołączonych pluginów raportują postęp spinnerem w sesjach TTY oraz okresowymi wierszami postępu w wyjściu potokowanym/beznadzorowym. Gateway i lokalny CLI mogą także na żądanie naprawiać zależności środowiska uruchomieniowego aktywnych dołączonych pluginów przed zaimportowaniem dołączonego pluginu. Te instalacje są ograniczone do katalogu głównego instalacji środowiska uruchomieniowego pluginu, działają z wyłączonymi skryptami, nie zapisują pliku blokady pakietów i są chronione blokadą katalogu głównego instalacji, aby równoczesne uruchomienia CLI lub Gateway nie modyfikowały tego samego drzewa `node_modules` w tym samym czasie.
Podczas naprawy doctor instalacje npm zależności runtime dołączonych pluginów zgłaszają postęp spinnera w sesjach TTY i okresowy postęp liniowy w wyjściu potokowanym/bezgłowym. Uruchamianie Gateway i ponowne ładowanie konfiguracji przechodzą w tryb planowania pluginów przed importem modułów runtime dołączonych pluginów; zwykłe importy runtime służą wyłącznie weryfikacji i nie uruchamiają naprawy menedżera pakietów. Te instalacje są ograniczone do katalogu głównego instalacji runtime pluginu, uruchamiane z wyłączonymi skryptami, nie zapisują blokady pakietów i są chronione blokadą katalogu głównego instalacji, aby równoległe uruchomienia CLI lub Gateway nie mutowały tego samego drzewa `node_modules` w tym samym czasie. Nieaktualne starsze blokady po zabitych uruchomieniach Docker/kontenera są odzyskiwane, gdy ich metadane właściciela nie mogą potwierdzić bieżącej inkarnacji procesu, a pliki blokad są stare.
</Accordion>
<Accordion title="8. Migracje usług Gateway i wskazówki czyszczenia">
Narzędzie diagnostyczne wykrywa starsze usługi Gateway (launchd/systemd/schtasks) i proponuje ich usunięcie oraz zainstalowanie usługi OpenClaw z użyciem bieżącego portu Gateway. Może też skanować dodatkowe usługi podobne do Gateway i wypisywać wskazówki czyszczenia. Usługi Gateway OpenClaw nazwane według profilu są traktowane jako pełnoprawne i nie są oznaczane jako „dodatkowe”.
Doctor wykrywa starsze usługi gateway (launchd/systemd/schtasks) i oferuje ich usunięcie oraz zainstalowanie usługi OpenClaw z użyciem bieżącego portu gateway. Może też skanować dodatkowe usługi podobne do gateway i wypisywać wskazówki czyszczenia. Usługi OpenClaw gateway nazwane profilem są traktowane jako pełnoprawne i nie są oznaczane jako „dodatkowe”.
W systemie Linux, jeśli brakuje usługi Gateway poziomu użytkownika, ale istnieje usługa Gateway OpenClaw poziomu systemu, narzędzie diagnostyczne nie instaluje automatycznie drugiej usługi poziomu użytkownika. Sprawdź za pomocą `openclaw gateway status --deep` albo `openclaw doctor --deep`, a następnie usuń duplikat albo ustaw `OPENCLAW_SERVICE_REPAIR_POLICY=external`, gdy nadzorca systemowy zarządza cyklem życia Gateway.
W systemie Linux, jeśli brakuje usługi gateway na poziomie użytkownika, ale istnieje usługa OpenClaw gateway na poziomie systemu, doctor nie instaluje automatycznie drugiej usługi na poziomie użytkownika. Sprawdź za pomocą `openclaw gateway status --deep` lub `openclaw doctor --deep`, a następnie usuń duplikat albo ustaw `OPENCLAW_SERVICE_REPAIR_POLICY=external`, gdy zewnętrzny supervisor zarządza cyklem życia gateway.
</Accordion>
<Accordion title="8b. Migracja Matrix podczas uruchamiania">
Gdy konto kanału Matrix ma oczekującą lub wymagającą działania migrację starszego stanu, narzędzie diagnostyczne (w trybie `--fix` / `--repair`) tworzy migawkę przed migracją, a następnie próbuje wykonać kroki migracji: migrację starszego stanu Matrix oraz przygotowanie starszego stanu szyfrowanego. Oba kroki są niekrytyczne; błędy są logowane, a uruchamianie jest kontynuowane. W trybie tylko do odczytu (`openclaw doctor` bez `--fix`) ta kontrola jest całkowicie pomijana.
<Accordion title="8b. Migracja uruchomieniowa Matrix">
Gdy konto kanału Matrix ma oczekującą lub możliwą do wykonania migrację starszego stanu, doctor (w trybie `--fix` / `--repair`) tworzy migawkę przed migracją, a następnie uruchamia kroki migracji w trybie best-effort: migrację starszego stanu Matrix i przygotowanie starszego stanu szyfrowanego. Oba kroki nie są krytyczne; błędy są logowane, a uruchamianie jest kontynuowane. W trybie tylko do odczytu (`openclaw doctor` bez `--fix`) to sprawdzenie jest całkowicie pomijane.
</Accordion>
<Accordion title="8c. Parowanie urządzeń i dryf autoryzacji">
Narzędzie diagnostyczne sprawdza teraz stan parowania urządzeń jako część zwykłego przebiegu kontroli kondycji.
<Accordion title="8c. Parowanie urządzeń i dryf uwierzytelniania">
Doctor sprawdza teraz stan parowania urządzeń jako część zwykłego przebiegu kontroli kondycji.
Co raportuje:
Co zgłasza:
- oczekujące żądania pierwszego parowania
- oczekujące aktualizacje ról dla już sparowanych urządzeń
- oczekujące aktualizacje zakresów dla już sparowanych urządzeń
- naprawy niezgodności klucza publicznego, gdy identyfikator urządzenia nadal pasuje, ale tożsamość urządzenia nie pasuje już do zatwierdzonego rekordu
- oczekujące pierwsze żądania parowania
- oczekujące podniesienia roli dla już sparowanych urządzeń
- oczekujące rozszerzenia zakresu dla już sparowanych urządzeń
- naprawy niezgodności klucza publicznego, gdy id urządzenia nadal pasuje, ale tożsamość urządzenia nie pasuje już do zatwierdzonego rekordu
- sparowane rekordy bez aktywnego tokenu dla zatwierdzonej roli
- sparowane tokeny, których zakresy odbiegły od zatwierdzonej linii bazowej parowania
- lokalne wpisy tokenów urządzenia w pamięci podręcznej dla bieżącej maszyny, które są starsze niż rotacja tokenu po stronie Gateway albo zawierają nieaktualne metadane zakresów
- sparowane tokeny, których zakresy dryfują poza zatwierdzoną bazę parowania
- lokalne wpisy pamięci podręcznej tokenów urządzenia dla bieżącej maszyny, które poprzedzają rotację tokenu po stronie gateway albo mają nieaktualne metadane zakresu
Narzędzie diagnostyczne nie zatwierdza automatycznie żądań parowania ani nie rotuje automatycznie tokenów urządzeń. Zamiast tego wypisuje dokładne następne kroki:
Doctor nie zatwierdza automatycznie żądań parowania ani nie rotuje automatycznie tokenów urządzeń. Zamiast tego wypisuje dokładne następne kroki:
- sprawdź oczekujące żądania za pomocą `openclaw devices list`
- zatwierdź dokładne żądanie za pomocą `openclaw devices approve <requestId>`
- zrotuj świeży token za pomocą `openclaw devices rotate --device <deviceId> --role <role>`
- usuń i ponownie zatwierdź nieaktualny rekord za pomocą `openclaw devices remove <deviceId>`
To zamyka typowy problem „już sparowane, ale nadal wymagane jest parowanie”: narzędzie diagnostyczne odróżnia teraz pierwsze parowanie od oczekujących aktualizacji ról/zakresów oraz od dryfu nieaktualnego tokenu lub tożsamości urządzenia.
To zamyka typową lukę „już sparowane, ale nadal wymagane jest parowanie”: doctor odróżnia teraz pierwsze parowanie od oczekujących podniesień roli/zakresu oraz od dryfu nieaktualnego tokenu/tożsamości urządzenia.
</Accordion>
<Accordion title="9. Ostrzeżenia bezpieczeństwa">
Narzędzie diagnostyczne emituje ostrzeżenia, gdy dostawca jest otwarty na wiadomości prywatne bez listy dozwolonych albo gdy zasada jest skonfigurowana w niebezpieczny sposób.
Doctor emituje ostrzeżenia, gdy dostawca jest otwarty na wiadomości prywatne bez listy dozwolonych albo gdy polityka jest skonfigurowana w niebezpieczny sposób.
</Accordion>
<Accordion title="10. Utrzymywanie systemd (Linux)">
Jeśli działa jako usługa użytkownika systemd, narzędzie diagnostyczne zapewnia włączenie utrzymywania, aby Gateway pozostał aktywny po wylogowaniu.
<Accordion title="10. systemd linger (Linux)">
Jeśli działa jako usługa użytkownika systemd, doctor upewnia się, że lingering jest włączony, aby gateway pozostał aktywny po wylogowaniu.
</Accordion>
<Accordion title="11. Stan obszaru roboczego (Skills, pluginy i starsze katalogi)">
Narzędzie diagnostyczne wypisuje podsumowanie stanu obszaru roboczego dla domyślnego agenta:
<Accordion title="11. Status obszaru roboczego (skills, pluginy i starsze katalogi)">
Doctor wypisuje podsumowanie stanu obszaru roboczego dla domyślnego agenta:
- **Status Skills**: zlicza kwalifikujące się Skills, Skills z brakującymi wymaganiami oraz Skills zablokowane przez listę dozwolonych.
- **Starsze katalogi obszaru roboczego**: ostrzega, gdy `~/openclaw` albo inne starsze katalogi obszaru roboczego istnieją obok bieżącego obszaru roboczego.
- **Status Plugin**: zlicza włączone/wyłączone/błędne pluginy; wypisuje identyfikatory pluginów dla wszelkich błędów; raportuje możliwości dołączonych pluginów.
- **Ostrzeżenia dotyczące zgodności Plugin**: oznacza pluginy, które mają problemy ze zgodnością z bieżącym środowiskiem uruchomieniowym.
- **Diagnostyka Plugin**: ujawnia wszelkie ostrzeżenia lub błędy z czasu ładowania emitowane przez rejestr pluginów.
- **Status Skills**: zlicza skills kwalifikujące się, z brakującymi wymaganiami i blokowane przez listę dozwolonych.
- **Starsze katalogi obszaru roboczego**: ostrzega, gdy `~/openclaw` lub inne starsze katalogi obszaru roboczego istnieją obok bieżącego obszaru roboczego.
- **Status Plugin**: zlicza włączone/wyłączone/błędne pluginy; wymienia ID pluginów dla wszelkich błędów; zgłasza możliwości pluginów pakietu.
- **Ostrzeżenia kompatybilności Plugin**: sygnalizuje pluginy, które mają problemy z kompatybilnością z bieżącym runtime.
- **Diagnostyka Plugin**: ujawnia wszelkie ostrzeżenia lub błędy czasu ładowania emitowane przez rejestr pluginów.
</Accordion>
<Accordion title="11b. Rozmiar pliku inicjalizacyjnego">
Narzędzie diagnostyczne sprawdza, czy pliki inicjalizacyjne obszaru roboczego (na przykład `AGENTS.md`, `CLAUDE.md` albo inne wstrzyknięte pliki kontekstu) są blisko skonfigurowanego budżetu znaków albo go przekraczają. Raportuje dla każdego pliku liczbę znaków surowych i wstrzykniętych, procent obcięcia, przyczynę obcięcia (`max/file` albo `max/total`) oraz łączną liczbę wstrzykniętych znaków jako ułamek całkowitego budżetu. Gdy pliki są obcięte albo blisko limitu, narzędzie diagnostyczne wypisuje wskazówki dotyczące dostrajania `agents.defaults.bootstrapMaxChars` i `agents.defaults.bootstrapTotalMaxChars`.
<Accordion title="11b. Rozmiar pliku bootstrap">
Doctor sprawdza, czy pliki bootstrap obszaru roboczego (na przykład `AGENTS.md`, `CLAUDE.md` lub inne wstrzyknięte pliki kontekstu) są blisko skonfigurowanego budżetu znaków albo go przekraczają. Zgłasza dla każdego pliku surowe i wstrzyknięte liczby znaków, procent obcięcia, przyczynę obcięcia (`max/file` lub `max/total`) oraz łączną liczbę wstrzykniętych znaków jako ułamek całkowitego budżetu. Gdy pliki są obcięte lub blisko limitu, doctor wypisuje wskazówki dotyczące dostrajania `agents.defaults.bootstrapMaxChars` i `agents.defaults.bootstrapTotalMaxChars`.
</Accordion>
<Accordion title="11d. Czyszczenie nieaktualnego pluginu kanału">
Gdy `openclaw doctor --fix` usuwa brakujący plugin kanału, usuwa także osieroconą konfigurację zakresu kanału, która odwoływała się do tego pluginu: wpisy `channels.<id>`, cele Heartbeat nazwane kanałem oraz nadpisania `agents.*.models["<channel>/*"]`. Zapobiega to pętlom uruchamiania Gateway, gdy środowisko uruchomieniowe kanału już nie istnieje, ale konfiguracja nadal żąda, aby Gateway się z nim powiązał.
Gdy `openclaw doctor --fix` usuwa brakujący plugin kanału, usuwa też wiszącą konfigurację w zakresie kanału, która odwoływała się do tego pluginu: wpisy `channels.<id>`, cele heartbeat, które wskazywały kanał, oraz nadpisania `agents.*.models["<channel>/*"]`. Zapobiega to pętlom uruchamiania Gateway, gdy runtime kanału zniknął, ale konfiguracja nadal wymaga, aby gateway się z nim powiązał.
</Accordion>
<Accordion title="11c. Uzupełnianie powłoki">
Narzędzie diagnostyczne sprawdza, czy uzupełnianie tabulatorem jest zainstalowane dla bieżącej powłoki (zsh, bash, fish albo PowerShell):
Doctor sprawdza, czy uzupełnianie tabulatorem jest zainstalowane dla bieżącej powłoki (zsh, bash, fish lub PowerShell):
- Jeśli profil powłoki używa wolnego wzorca dynamicznego uzupełniania (`source <(openclaw completion ...)`), narzędzie diagnostyczne aktualizuje go do szybszego wariantu z plikiem w pamięci podręcznej.
- Jeśli uzupełnianie jest skonfigurowane w profilu, ale brakuje pliku pamięci podręcznej, narzędzie diagnostyczne automatycznie odtwarza pamięć podręczną.
- Jeśli uzupełnianie nie jest w ogóle skonfigurowane, narzędzie diagnostyczne prosi o jego instalację (tylko w trybie interaktywnym; pomijane z `--non-interactive`).
- Jeśli profil powłoki używa wolnego dynamicznego wzorca uzupełniania (`source <(openclaw completion ...)`), doctor aktualizuje go do szybszego wariantu pliku z pamięci podręcznej.
- Jeśli uzupełnianie jest skonfigurowane w profilu, ale brakuje pliku pamięci podręcznej, doctor automatycznie regeneruje pamięć podręczną.
- Jeśli uzupełnianie nie jest w ogóle skonfigurowane, doctor pyta o jego instalację (tylko tryb interaktywny; pomijane z `--non-interactive`).
Uruchom `openclaw completion --write-state`, aby ręcznie odtworzyć pamięć podręczną.
Uruchom `openclaw completion --write-state`, aby ręcznie zregenerować pamięć podręczną.
</Accordion>
<Accordion title="12. Kontrole uwierzytelniania Gateway (token lokalny)">
Narzędzie diagnostyczne sprawdza gotowość lokalnego uwierzytelniania tokenem Gateway.
<Accordion title="12. Sprawdzenia uwierzytelniania Gateway (token lokalny)">
Doctor sprawdza gotowość lokalnego uwierzytelniania tokenem gateway.
- Jeśli tryb tokenu wymaga tokenu, a nie istnieje żadne źródło tokenu, narzędzie diagnostyczne proponuje jego wygenerowanie.
- Jeśli `gateway.auth.token` jest zarządzany przez SecretRef, ale niedostępny, narzędzie diagnostyczne ostrzega i nie zastępuje go tekstem jawnym.
- `openclaw doctor --generate-gateway-token` wymusza generowanie tylko wtedy, gdy nie skonfigurowano SecretRef tokenu.
- Jeśli tryb tokenu wymaga tokenu i nie istnieje żadne źródło tokenu, doctor oferuje jego wygenerowanie.
- Jeśli `gateway.auth.token` jest zarządzany przez SecretRef, ale niedostępny, doctor ostrzega i nie nadpisuje go tekstem jawnym.
- `openclaw doctor --generate-gateway-token` wymusza generowanie tylko wtedy, gdy nie skonfigurowano tokenu SecretRef.
</Accordion>
<Accordion title="12b. Naprawy tylko do odczytu świadome SecretRef">
Niektóre przepływy naprawy muszą sprawdzać skonfigurowane poświadczenia bez osłabiania zachowania szybkiego przerywania przy błędzie w czasie wykonywania.
Niektóre przepływy napraw muszą sprawdzać skonfigurowane poświadczenia bez osłabiania zachowania runtime fail-fast.
- `openclaw doctor --fix` używa teraz tego samego modelu podsumowania SecretRef tylko do odczytu co polecenia z rodziny statusu dla ukierunkowanych napraw konfiguracji.
- Przykład: naprawa `allowFrom` / `groupAllowFrom` `@username` w Telegram próbuje użyć skonfigurowanych poświadczeń bota, gdy są dostępne.
- Jeśli token bota Telegram jest skonfigurowany przez SecretRef, ale niedostępny w bieżącej ścieżce polecenia, narzędzie diagnostyczne raportuje, że poświadczenie jest skonfigurowane, ale niedostępne, i pomija automatyczne rozpoznawanie zamiast kończyć się awarią albo błędnie zgłaszać token jako brakujący.
- `openclaw doctor --fix` używa teraz tego samego modelu podsumowania SecretRef tylko do odczytu co polecenia z rodziny status dla ukierunkowanych napraw konfiguracji.
- Przykład: naprawa Telegram `allowFrom` / `groupAllowFrom` `@username` próbuje użyć skonfigurowanych poświadczeń bota, gdy są dostępne.
- Jeśli token bota Telegram jest skonfigurowany przez SecretRef, ale niedostępny w bieżącej ścieżce polecenia, doctor zgłasza, że poświadczenie jest skonfigurowane, ale niedostępne, i pomija automatyczne rozwiązywanie zamiast ulegać awarii lub błędnie zgłaszać brak tokenu.
</Accordion>
<Accordion title="13. Kontrola kondycji Gateway + restart">
Narzędzie diagnostyczne uruchamia kontrolę kondycji i proponuje ponowne uruchomienie Gateway, gdy wygląda na niesprawny.
<Accordion title="13. Sprawdzenie kondycji Gateway + restart">
Doctor uruchamia sprawdzenie kondycji i oferuje ponowne uruchomienie gateway, gdy wygląda na niezdrowy.
</Accordion>
<Accordion title="13b. Gotowość wyszukiwania pamięci">
Narzędzie diagnostyczne sprawdza, czy skonfigurowany dostawca osadzeń wyszukiwania pamięci jest gotowy dla domyślnego agenta. Zachowanie zależy od skonfigurowanego zaplecza i dostawcy:
Doctor sprawdza, czy skonfigurowany dostawca osadzania wyszukiwania pamięci jest gotowy dla domyślnego agenta. Zachowanie zależy od skonfigurowanego backendu i dostawcy:
- **Zaplecze QMD**: sonduje, czy plik binarny `qmd` jest dostępny i można go uruchomić. Jeśli nie, wypisuje wskazówki naprawy, w tym pakiet npm i opcję ręcznej ścieżki do pliku binarnego.
- **Jawny dostawca lokalny**: sprawdza lokalny plik modelu albo rozpoznany zdalny/pobieralny URL modelu. Jeśli go brakuje, sugeruje przełączenie na dostawcę zdalnego.
- **Jawny dostawca zdalny** (`openai`, `voyage` itd.): weryfikuje, czy klucz API jest obecny w środowisku albo magazynie uwierzytelniania. Wypisuje konkretne wskazówki naprawy, jeśli go brakuje.
- **Backend QMD**: sprawdza, czy binarka `qmd` jest dostępna i możliwa do uruchomienia. Jeśli nie, wypisuje wskazówki naprawy, w tym pakiet npm i opcję ręcznej ścieżki do binarki.
- **Jawny dostawca lokalny**: sprawdza lokalny plik modelu lub rozpoznany zdalny/pobieralny URL modelu. Jeśli go brakuje, sugeruje przełączenie na dostawcę zdalnego.
- **Jawny dostawca zdalny** (`openai`, `voyage` itd.): weryfikuje, czy klucz API jest obecny w środowisku lub magazynie uwierzytelniania. Wypisuje praktyczne wskazówki naprawy, jeśli go brakuje.
- **Dostawca automatyczny**: najpierw sprawdza dostępność modelu lokalnego, a następnie próbuje każdego dostawcy zdalnego w kolejności automatycznego wyboru.
Gdy dostępny jest zapisany w pamięci podręcznej wynik sondy Gateway (Gateway był zdrowy w momencie kontroli), narzędzie diagnostyczne porównuje jego wynik z konfiguracją widoczną dla CLI i odnotowuje wszelkie rozbieżności. Narzędzie diagnostyczne nie uruchamia nowego pingu osadzeń na domyślnej ścieżce; użyj głębokiego polecenia stanu pamięci, gdy chcesz sprawdzić dostawcę na żywo.
Gdy dostępny jest wynik sondy Gateway z pamięci podręcznej (Gateway był sprawny w chwili sprawdzania), doctor porównuje jego wynik z konfiguracją widoczną dla CLI i odnotowuje wszelkie rozbieżności. Doctor nie uruchamia świeżego pingu osadzania na domyślnej ścieżce; użyj polecenia głębokiego statusu pamięci, gdy chcesz wykonać bieżące sprawdzenie dostawcy.
Użyj `openclaw memory status --deep`, aby zweryfikować gotowość osadzeń w czasie wykonywania.
Użyj `openclaw memory status --deep`, aby zweryfikować gotowość osadzania w czasie działania.
</Accordion>
<Accordion title="14. Ostrzeżenia stanu kanałów">
Jeśli Gateway jest zdrowy, narzędzie diagnostyczne uruchamia sondę stanu kanałów i raportuje ostrzeżenia z sugerowanymi poprawkami.
<Accordion title="14. Ostrzeżenia o statusie kanałów">
Jeśli Gateway jest sprawny, doctor uruchamia sondę statusu kanałów i zgłasza ostrzeżenia z sugerowanymi poprawkami.
</Accordion>
<Accordion title="15. Audyt + naprawa konfiguracji nadzorcy">
Narzędzie diagnostyczne sprawdza zainstalowaną konfigurację nadzorcy (launchd/systemd/schtasks) pod kątem brakujących lub przestarzałych wartości domyślnych (np. zależności systemd network-online i opóźnienia restartu). Gdy znajdzie niezgodność, zaleca aktualizację i może przepisać plik usługi/zadanie do bieżących wartości domyślnych.
<Accordion title="15. Audyt i naprawa konfiguracji nadzorcy">
Doctor sprawdza zainstalowaną konfigurację nadzorcy (launchd/systemd/schtasks) pod kątem brakujących lub nieaktualnych wartości domyślnych (np. zależności systemd od network-online i opóźnienia restartu). Gdy znajdzie niezgodność, zaleca aktualizację i może przepisać plik usługi/zadanie do bieżących wartości domyślnych.
Uwagi:
- `openclaw doctor` pyta przed przepisaniem konfiguracji supervisora.
- `openclaw doctor --yes` akceptuje domyślne monity naprawcze.
- `openclaw doctor` pyta przed przepisaniem konfiguracji nadzorcy.
- `openclaw doctor --yes` akceptuje domyślne monity naprawy.
- `openclaw doctor --repair` stosuje zalecane poprawki bez monitów.
- `openclaw doctor --repair --force` nadpisuje niestandardowe konfiguracje supervisora.
- `OPENCLAW_SERVICE_REPAIR_POLICY=external` pozostawia doctor w trybie tylko do odczytu dla cyklu życia usługi Gateway. Nadal raportuje stan usługi i uruchamia naprawy niezwiązane z usługą, ale pomija instalację/uruchamianie/restart/bootstrap usługi, przepisywanie konfiguracji supervisora oraz czyszczenie starszych usług, ponieważ zewnętrzny supervisor jest właścicielem tego cyklu życia.
- W systemie Linux doctor nie przepisuje metadanych polecenia/punktu wejścia, gdy odpowiadająca jednostka systemd Gateway jest aktywna. Ignoruje też nieaktywne, niestarsze dodatkowe jednostki podobne do Gateway podczas skanowania zduplikowanych usług, aby pliki usług towarzyszących nie powodowały zbędnego szumu przy czyszczeniu.
- Jeśli uwierzytelnianie tokenem wymaga tokena, a `gateway.auth.token` jest zarządzane przez SecretRef, instalacja/naprawa usługi przez doctor sprawdza SecretRef, ale nie zapisuje rozwiązanych wartości tokenów w postaci jawnego tekstu w metadanych środowiska usługi supervisora.
- Doctor wykrywa zarządzane wartości środowiska usługi oparte na `.env`/SecretRef, które starsze instalacje LaunchAgent, systemd lub Zaplanowanego zadania Windows osadziły inline, i przepisuje metadane usługi tak, aby te wartości były ładowane ze źródła uruchomieniowego zamiast z definicji supervisora.
- `openclaw doctor --repair --force` nadpisuje niestandardowe konfiguracje nadzorcy.
- `OPENCLAW_SERVICE_REPAIR_POLICY=external` utrzymuje doctor w trybie tylko do odczytu dla cyklu życia usługi Gateway. Nadal zgłasza kondycję usługi i uruchamia naprawy niezwiązane z usługą, ale pomija instalację/uruchomienie/restart/bootstrap usługi, przepisywanie konfiguracji nadzorcy i czyszczenie starszych usług, ponieważ tym cyklem życia zarządza zewnętrzny nadzorca.
- W systemie Linux doctor nie przepisuje metadanych polecenia/punktu wejścia, gdy pasująca jednostka systemd Gateway jest aktywna. Ignoruje też nieaktywne, niestarsze dodatkowe jednostki podobne do Gateway podczas skanowania zduplikowanych usług, aby towarzyszące pliki usług nie generowały szumu przy czyszczeniu.
- Jeśli uwierzytelnianie tokenem wymaga tokenu, a `gateway.auth.token` jest zarządzany przez SecretRef, instalacja/naprawa usługi przez doctor weryfikuje SecretRef, ale nie utrwala rozwiązanych wartości tokenów w postaci jawnego tekstu w metadanych środowiska usługi nadzorcy.
- Doctor wykrywa zarządzane wartości środowiska usługi oparte na `.env`/SecretRef, które starsze instalacje LaunchAgent, systemd lub Windows Scheduled Task osadziły bezpośrednio, i przepisuje metadane usługi tak, aby te wartości były ładowane ze źródła wykonawczego zamiast z definicji nadzorcy.
- Doctor wykrywa, gdy polecenie usługi nadal przypina stary `--port` po zmianie `gateway.port`, i przepisuje metadane usługi na bieżący port.
- Jeśli uwierzytelnianie tokenem wymaga tokena, a skonfigurowany token SecretRef nie jest rozwiązany, doctor blokuje ścieżkę instalacji/naprawy z praktycznymi wskazówkami.
- Jeśli skonfigurowano zarówno `gateway.auth.token`, jak i `gateway.auth.password`, a `gateway.auth.mode` nie jest ustawione, doctor blokuje instalację/naprawę, dopóki tryb nie zostanie ustawiony jawnie.
- Dla jednostek systemd użytkownika w systemie Linux kontrole rozbieżności tokena w doctor obejmują teraz zarówno źródła `Environment=`, jak i `EnvironmentFile=` podczas porównywania metadanych uwierzytelniania usługi.
- Naprawy usług przez doctor odmawiają przepisania, zatrzymania lub ponownego uruchomienia usługi Gateway ze starszego pliku binarnego OpenClaw, gdy konfiguracja została ostatnio zapisana przez nowszą wersję. Zobacz [Rozwiązywanie problemów z Gateway](/pl/gateway/troubleshooting#split-brain-installs-and-newer-config-guard).
- Zawsze możesz wymusić pełne przepisanie za pomocą `openclaw gateway install --force`.
- Jeśli uwierzytelnianie tokenem wymaga tokenu, a skonfigurowany token SecretRef nie może zostać rozwiązany, doctor blokuje ścieżkę instalacji/naprawy z praktycznymi wskazówkami.
- Jeśli skonfigurowane są jednocześnie `gateway.auth.token` i `gateway.auth.password`, a `gateway.auth.mode` nie jest ustawione, doctor blokuje instalację/naprawę do czasu jawnego ustawienia trybu.
- Dla jednostek systemd użytkownika w systemie Linux kontrole dryfu tokenów w doctor obejmują teraz zarówno źródła `Environment=`, jak i `EnvironmentFile=` podczas porównywania metadanych uwierzytelniania usługi.
- Naprawy usług przez doctor odmawiają przepisania, zatrzymania lub zrestartowania usługi Gateway ze starszego binarium OpenClaw, gdy konfiguracja została ostatnio zapisana przez nowszą wersję. Zobacz [Rozwiązywanie problemów z Gateway](/pl/gateway/troubleshooting#split-brain-installs-and-newer-config-guard).
- Zawsze możesz wymusić pełne przepisanie przez `openclaw gateway install --force`.
</Accordion>
<Accordion title="16. Środowisko uruchomieniowe Gateway + diagnostyka portów">
Doctor sprawdza środowisko uruchomieniowe usługi (PID, ostatni status zakończenia) i ostrzega, gdy usługa jest zainstalowana, ale faktycznie nie działa. Sprawdza też kolizje portów na porcie Gateway (domyślnie `18789`) i raportuje prawdopodobne przyczyny (Gateway już działa, tunel SSH).
<Accordion title="16. Diagnostyka środowiska wykonawczego i portu Gateway">
Doctor sprawdza środowisko wykonawcze usługi (PID, ostatni status wyjścia) i ostrzega, gdy usługa jest zainstalowana, ale faktycznie nie działa. Sprawdza też kolizje portów na porcie Gateway (domyślnie `18789`) i zgłasza prawdopodobne przyczyny (Gateway już działa, tunel SSH).
</Accordion>
<Accordion title="17. Najlepsze praktyki środowiska uruchomieniowego Gateway">
Doctor ostrzega, gdy usługa Gateway działa na Bun lub ścieżce Node zarządzanej wersjami (`nvm`, `fnm`, `volta`, `asdf` itd.). Kanały WhatsApp + Telegram wymagają Node, a ścieżki menedżerów wersji mogą przestać działać po aktualizacjach, ponieważ usługa nie ładuje inicjalizacji powłoki. Doctor proponuje migrację do systemowej instalacji Node, gdy jest dostępna (Homebrew/apt/choco).
<Accordion title="17. Najlepsze praktyki środowiska wykonawczego Gateway">
Doctor ostrzega, gdy usługa Gateway działa na Bun albo na ścieżce Node zarządzanej wersjami (`nvm`, `fnm`, `volta`, `asdf` itd.). Kanały WhatsApp i Telegram wymagają Node, a ścieżki menedżerów wersji mogą przestać działać po aktualizacjach, ponieważ usługa nie ładuje inicjalizacji powłoki. Doctor proponuje migrację do systemowej instalacji Node, gdy jest dostępna (Homebrew/apt/choco).
Nowo zainstalowane lub naprawione usługi zachowują jawne katalogi główne środowiska (`NVM_DIR`, `FNM_DIR`, `VOLTA_HOME`, `ASDF_DATA_DIR`, `BUN_INSTALL`, `PNPM_HOME`) i stabilne katalogi binarne użytkownika, ale odgadnięte katalogi awaryjne menedżerów wersji są zapisywane do PATH usługi tylko wtedy, gdy te katalogi istnieją na dysku. Dzięki temu wygenerowany PATH supervisora pozostaje zgodny z tym samym audytem minimalnego PATH, który doctor uruchamia później.
Nowo zainstalowane lub naprawione usługi zachowują jawne katalogi główne środowiska (`NVM_DIR`, `FNM_DIR`, `VOLTA_HOME`, `ASDF_DATA_DIR`, `BUN_INSTALL`, `PNPM_HOME`) oraz stabilne katalogi binarne użytkownika, ale odgadnięte katalogi awaryjne menedżerów wersji są zapisywane do PATH usługi tylko wtedy, gdy te katalogi istnieją na dysku. Dzięki temu wygenerowana PATH nadzorcy pozostaje zgodna z tym samym audytem minimalnej PATH, który doctor uruchamia później.
</Accordion>
<Accordion title="18. Zapis konfiguracji + metadane kreatora">
Doctor zapisuje wszelkie zmiany konfiguracji i oznacza metadane kreatora, aby zarejestrować uruchomienie doctor.
<Accordion title="18. Zapis konfiguracji i metadane kreatora">
Doctor utrwala wszelkie zmiany konfiguracji i oznacza metadane kreatora, aby zarejestrować uruchomienie doctor.
</Accordion>
<Accordion title="19. Wskazówki dotyczące przestrzeni roboczej (backup + system pamięci)">
Doctor sugeruje system pamięci przestrzeni roboczej, gdy go brakuje, i wyświetla wskazówkę dotyczącą backupu, jeśli przestrzeń robocza nie jest jeszcze objęta git.
<Accordion title="19. Wskazówki dotyczące obszaru roboczego (kopia zapasowa i system pamięci)">
Doctor sugeruje system pamięci obszaru roboczego, gdy go brakuje, i wypisuje wskazówkę dotyczącą kopii zapasowej, jeśli obszar roboczy nie jest jeszcze objęty git.
Zobacz [/concepts/agent-workspace](/pl/concepts/agent-workspace), aby poznać pełny przewodnik po strukturze przestrzeni roboczej i backupie git (zalecane prywatne GitHub lub GitLab).
Zobacz [/concepts/agent-workspace](/pl/concepts/agent-workspace), aby uzyskać pełny przewodnik po strukturze obszaru roboczego i kopii zapasowej git (zalecany prywatny GitHub lub GitLab).
</Accordion>
</AccordionGroup>

68
docs/pl/gateway/logging.md
View File

@ -1,28 +1,28 @@
---
read_when:
- Zmiana danych wyjściowych lub formatów logów
- Zmiana wyjścia logów lub ich formatów
- Debugowanie danych wyjściowych CLI lub Gateway
summary: Powierzchnie logowania, logi plikowe, style logów WS i formatowanie konsoli
title: Rejestrowanie Gateway
summary: Miejsca rejestrowania logów, logi plikowe, style logów WS i formatowanie konsoli
title: Rejestrowanie dzienników Gateway
x-i18n:
generated_at: "2026-04-30T09:54:19Z"
generated_at: "2026-05-01T09:58:57Z"
model: gpt-5.5
provider: openai
source_hash: 9ce9c78201d2e26760282b08eacb17826b1eac84e80b99d3a9d5cbff4078b5b3
source_hash: f843812a41c25f9ca1884543ad3a5663c8e0bc327027cbd2b58ea6557c466aa9
source_path: gateway/logging.md
workflow: 16
---
# Logowanie
# Rejestrowanie
Omówienie z perspektywy użytkownika (CLI + Control UI + konfiguracja) znajdziesz w [/logging](/pl/logging).
Przegląd z perspektywy użytkownika (CLI + Control UI + konfiguracja) znajdziesz w [/logging](/pl/logging).
OpenClaw ma dwie „powierzchnie” logów:
- **Wyjście konsoli** (to, co widzisz w terminalu / Debug UI).
- **Logi plikowe** (linie JSON) zapisywane przez logger Gateway.
- **Logi plikowe** (wiersze JSON) zapisywane przez logger Gateway.
## Logger plikowy
## Logger oparty na plikach
- Domyślny rotowany plik logu znajduje się w `/tmp/openclaw/` (jeden plik dziennie): `openclaw-YYYY-MM-DD.log`
- Data używa lokalnej strefy czasowej hosta Gateway.
@ -32,9 +32,9 @@ OpenClaw ma dwie „powierzchnie” logów:
- `logging.file`
- `logging.level`
Format pliku to jeden obiekt JSON na linię.
Format pliku to jeden obiekt JSON w każdym wierszu.
Karta Logs w Control UI śledzi ten plik przez Gateway (`logs.tail`).
Karta logów w Control UI śledzi ten plik przez Gateway (`logs.tail`).
CLI może zrobić to samo:
```bash
@ -44,15 +44,15 @@ openclaw logs --follow
**Tryb szczegółowy a poziomy logowania**
- **Logi plikowe** są kontrolowane wyłącznie przez `logging.level`.
- `--verbose` wpływa tylko na **szczegółowość konsoli** (oraz styl logów WS); **nie**
- `--verbose` wpływa tylko na **szczegółowość konsoli** (i styl logów WS); **nie**
podnosi poziomu logów plikowych.
- Aby przechwycić szczegóły dostępne tylko w trybie szczegółowym w logach plikowych, ustaw `logging.level` na `debug` lub
- Aby przechwycić w logach plikowych szczegóły dostępne tylko w trybie szczegółowym, ustaw `logging.level` na `debug` lub
`trace`.
## Przechwytywanie konsoli
CLI przechwytuje `console.log/info/warn/error/debug/trace` i zapisuje je do logów plikowych,
jednocześnie nadal wypisując je na stdout/stderr.
nadal wypisując je na stdout/stderr.
Szczegółowość konsoli możesz dostroić niezależnie przez:
@ -61,21 +61,21 @@ Szczegółowość konsoli możesz dostroić niezależnie przez:
## Redakcja
OpenClaw może maskować wrażliwe tokeny, zanim dane wyjściowe logów lub transkrypcji opuszczą
proces. Ta polityka redakcji logowania jest stosowana do ujść tekstowych konsoli, logów plikowych,
rekordów logów OTLP i transkrypcji sesji, więc pasujące wartości sekretów są
maskowane, zanim linie JSONL lub komunikaty zostaną zapisane na dysku.
OpenClaw może maskować wrażliwe tokeny, zanim wyjście logu lub transkrypcji opuści
proces. Ta polityka redakcji logów jest stosowana do konsoli, logów plikowych, rekordów
logów OTLP i tekstowych ujść transkrypcji sesji, więc pasujące wartości sekretów są
maskowane przed zapisaniem wierszy JSONL lub komunikatów na dysku.
- `logging.redactSensitive`: `off` | `tools` (domyślnie: `tools`)
- `logging.redactPatterns`: tablica ciągów regex (zastępuje wartości domyślne)
- Użyj surowych ciągów regex (automatyczne `gi`) albo `/pattern/flags`, jeśli potrzebujesz niestandardowych flag.
- Dopasowania są maskowane przez zachowanie pierwszych 6 + ostatnich 4 znaków (długość >= 18), w przeciwnym razie `***`.
- Wartości domyślne obejmują typowe przypisania kluczy, flagi CLI, pola JSON, nagłówki bearer, bloki PEM i popularne prefiksy tokenów.
- Używaj surowych ciągów regex (automatyczne `gi`) albo `/pattern/flags`, jeśli potrzebujesz własnych flag.
- Dopasowania są maskowane przez zachowanie pierwszych 6 i ostatnich 4 znaków (długość >= 18), w przeciwnym razie `***`.
- Domyślne wartości obejmują typowe przypisania kluczy, flagi CLI, pola JSON, nagłówki bearer, bloki PEM, popularne prefiksy tokenów oraz nazwy pól danych płatniczych, takie jak numer karty, CVC/CVV, współdzielony token płatniczy i poświadczenie płatnicze.
Niektóre granice bezpieczeństwa zawsze redagują dane niezależnie od `logging.redactSensitive`.
Obejmuje to zdarzenia wywołań narzędzi Control UI, dane wyjściowe narzędzia `sessions_history`,
eksporty wsparcia diagnostycznego, obserwacje błędów dostawców, wyświetlanie poleceń zatwierdzania exec
oraz logi protokołu WebSocket Gateway. Te powierzchnie nadal mogą używać
Obejmuje to zdarzenia wywołań narzędzi Control UI, wyjście narzędzia `sessions_history`,
eksporty wsparcia diagnostycznego, obserwacje błędów dostawców, wyświetlanie poleceń
zatwierdzania exec oraz logi protokołu WebSocket Gateway. Te powierzchnie nadal mogą używać
`logging.redactPatterns` jako dodatkowych wzorców, ale `redactSensitive: "off"`
nie sprawia, że emitują surowe sekrety.
@ -91,10 +91,10 @@ Gateway wypisuje logi protokołu WebSocket w dwóch trybach:
### Styl logów WS
`openclaw gateway` obsługuje przełącznik stylu dla danego Gateway:
`openclaw gateway` obsługuje przełącznik stylu dla każdego Gateway:
- `--ws-log auto` (domyślnie): tryb normalny jest zoptymalizowany; tryb szczegółowy używa zwięzłego wyjścia
- `--ws-log compact`: zwięzłe wyjście (sparowane żądanie/odpowiedź) w trybie szczegółowym
- `--ws-log auto` (domyślnie): tryb normalny jest zoptymalizowany; tryb szczegółowy używa kompaktowego wyjścia
- `--ws-log compact`: kompaktowe wyjście (sparowane żądanie/odpowiedź) w trybie szczegółowym
- `--ws-log full`: pełne wyjście dla każdej ramki w trybie szczegółowym
- `--compact`: alias dla `--ws-log compact`
@ -113,25 +113,25 @@ openclaw gateway --verbose --ws-log full
## Formatowanie konsoli (logowanie podsystemów)
Formater konsoli jest **świadomy TTY** i wypisuje spójne linie z prefiksami.
Formatter konsoli jest **świadomy TTY** i wypisuje spójne wiersze z prefiksami.
Loggery podsystemów utrzymują wyjście w grupach i ułatwiają skanowanie.
Zachowanie:
- **Prefiksy podsystemów** w każdej linii (np. `[gateway]`, `[canvas]`, `[tailscale]`)
- **Prefiksy podsystemów** w każdym wierszu (np. `[gateway]`, `[canvas]`, `[tailscale]`)
- **Kolory podsystemów** (stabilne dla każdego podsystemu) oraz kolorowanie poziomów
- **Kolor, gdy wyjście jest TTY albo środowisko wygląda jak rozbudowany terminal** (`TERM`/`COLORTERM`/`TERM_PROGRAM`), respektuje `NO_COLOR`
- **Kolor, gdy wyjście jest TTY albo środowisko wygląda jak zaawansowany terminal** (`TERM`/`COLORTERM`/`TERM_PROGRAM`), respektuje `NO_COLOR`
- **Skrócone prefiksy podsystemów**: usuwa początkowe `gateway/` + `channels/`, zachowuje ostatnie 2 segmenty (np. `whatsapp/outbound`)
- **Podloggery według podsystemu** (automatyczny prefiks + strukturalne pole `{ subsystem }`)
- **`logRaw()`** dla wyjścia QR/UX (bez prefiksu, bez formatowania)
- **Pod-loggery według podsystemu** (automatyczny prefiks + strukturalne pole `{ subsystem }`)
- **`logRaw()`** do wyjścia QR/UX (bez prefiksu, bez formatowania)
- **Style konsoli** (np. `pretty | compact | json`)
- **Poziom logowania konsoli** oddzielny od poziomu logowania plikowego (plik zachowuje pełne szczegóły, gdy `logging.level` jest ustawione na `debug`/`trace`)
- **Poziom logowania konsoli** oddzielny od poziomu logów plikowych (plik zachowuje pełne szczegóły, gdy `logging.level` jest ustawione na `debug`/`trace`)
- **Treści wiadomości WhatsApp** są logowane na poziomie `debug` (użyj `--verbose`, aby je zobaczyć)
Dzięki temu istniejące logi plikowe pozostają stabilne, a wyjście interaktywne jest łatwe do skanowania.
## Powiązane
- [Logowanie](/pl/logging)
- [Rejestrowanie](/pl/logging)
- [Eksport OpenTelemetry](/pl/gateway/opentelemetry)
- [Eksport diagnostyki](/pl/gateway/diagnostics)

513
docs/pl/gateway/protocol.md
View File

@ -1,39 +1,38 @@
---
read_when:
- Implementowanie lub aktualizowanie klientów WS Gateway
- Debugowanie niezgodności protokołu lub niepowodzeń połączenia
- Regenerowanie schematu/modeli protokołu
- Debugowanie niezgodności protokołu lub błędów połączenia
- Ponowne generowanie schematu/modeli protokołu
summary: 'Protokół WebSocket Gateway: uzgadnianie, ramki, wersjonowanie'
title: Protokół Gateway
x-i18n:
generated_at: "2026-04-30T09:55:53Z"
generated_at: "2026-05-01T09:59:08Z"
model: gpt-5.5
provider: openai
source_hash: c0d922e9b4b778c333873e551498b905461f30f944e809555b45669ae2f5c404
source_hash: 8295e4e416250e7381393c0aa6a0016719f96552485cf9d56bb3896c9704c4a9
source_path: gateway/protocol.md
workflow: 16
---
Protokół WS Gateway jest **pojedynczą płaszczyzną sterowania + transportem węzłów** dla
OpenClaw. Wszyscy klienci (CLI, internetowy interfejs użytkownika, aplikacja macOS, węzły iOS/Android, węzły bez interfejsu)
łączą się przez WebSocket i deklarują swoją **rolę** + **zakres** podczas
uzgadniania połączenia.
Gateway WS protocol 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 sprzed połączenia są ograniczone do 64 KiB. Po udanym uzgodnieniu połączenia klienci
- 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`. Gdy diagnostyka jest włączona,
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 powodów. Nie zachowują treści
wiadomości, zawartości załączników, surowej treści ramki, tokenów, cookies ani wartości sekretów.
zanim gateway zamknie połączenie lub odrzuci dotkniętą 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 sekretów.
## Uzgodnienie połączenia (connect)
## Uzgadnianie połączenia (connect)
Gateway → Klient (wyzwanie sprzed połączenia):
Gateway → Klient (wyzwanie przed połączeniem):
```json
{
@ -104,17 +103,17 @@ Gateway → Klient:
}
```
Gdy Gateway nadal kończy uruchamianie procesów pomocniczych, żądanie `connect` może
Gdy Gateway nadal kończy uruchamianie sidecarów startowych, żądanie `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 całkowitego budżetu połączenia, zamiast prezentować ją jako końcową
w ramach swojego ogólnego budżetu połączenia, zamiast prezentować ją jako końcową
awarię uzgadniania połączenia.
`server`, `features`, `snapshot` i `policy` są wymagane przez schemat
(`src/gateway/protocol/schema/frames.ts`). `auth` również jest wymagane i zgłasza
(`src/gateway/protocol/schema/frames.ts`). `auth` także jest wymagane i raportuje
wynegocjowaną rolę/zakresy. `canvasHostUrl` jest opcjonalne.
Gdy nie wydano tokenu urządzenia, `hello-ok.auth` zgłasza wynegocjowane
Gdy nie wydano tokenu urządzenia, `hello-ok.auth` raportuje wynegocjowane
uprawnienia bez pól tokenu:
```json
@ -126,15 +125,16 @@ uprawnienia bez pól tokenu:
}
```
Zaufani klienci backendu w tym samym procesie (`client.id: "gateway-client"`,
`client.mode: "backend"`) mogą pominąć `device` w bezpośrednich połączeniach loopback,
Zaufani klienci backendowi działający w tym samym procesie (`client.id: "gateway-client"`,
`client.mode: "backend"`) mogą pominąć `device` przy 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 sprawia, że nieaktualne bazowe powiązania CLI/urządzenia
nie blokują lokalnej pracy backendu, takiej jak aktualizacje sesji subagentów. Klienci zdalni,
klienci pochodzący z przeglądarki, klienci węzłów oraz jawni klienci z tokenem urządzenia/tożsamością urządzenia
nadal używają zwykłych kontroli parowania i podnoszenia zakresu.
dla wewnętrznych RPC płaszczyzny sterowania i zapobiega blokowaniu lokalnej pracy backendu,
takiej jak aktualizacje sesji subagentów, przez nieaktualne bazowe dane parowania CLI/urządzenia.
Klienci zdalni, klienci pochodzący z przeglądarki, klienci węzłowi oraz jawni klienci
z tokenem urządzenia/tożsamością urządzenia nadal używają zwykłych kontroli parowania
i podnoszenia zakresów.
Gdy wydano token urządzenia, `hello-ok` zawiera także:
Gdy token urządzenia zostanie wydany, `hello-ok` zawiera także:
```json
{
@ -166,12 +166,12 @@ ograniczone wpisy ról w `deviceTokens`:
}
```
Dla wbudowanego przepływu bootstrapu węzła/operatora podstawowy token węzła pozostaje
`scopes: []`, a każdy przekazany token operatora pozostaje ograniczony do listy dozwolonej operatora
bootstrapu (`operator.approvals`, `operator.read`,
`operator.talk.secrets`, `operator.write`). Kontrole zakresu bootstrapu pozostają
prefiksowane rolą: wpisy operatora spełniają tylko żądania operatora, a role inne niż operator
nadal potrzebują zakresów z własnym prefiksem roli.
Dla wbudowanego przepływu bootstrapu węzeł/operator główny token węzła pozostaje
`scopes: []`, a każdy przekazany token operatora pozostaje ograniczony do allowlisty
operatora bootstrapu (`operator.approvals`, `operator.read`,
`operator.talk.secrets`, `operator.write`). Kontrole zakresów bootstrapu pozostają
prefiksowane rolą: wpisy operatora spełniają wyłącznie żądania operatora, a role
inne niż operator nadal potrzebują zakresów z własnym prefiksem roli.
### Przykład węzła
@ -214,7 +214,7 @@ nadal potrzebują zakresów z własnym prefiksem roli.
- **Odpowiedź**: `{type:"res", id, ok, payload|error}`
- **Zdarzenie**: `{type:"event", event, payload, seq?, stateVersion?}`
Metody powodujące skutki uboczne wymagają **kluczy idempotencji** (zobacz schemat).
Metody wywołujące skutki uboczne wymagają **kluczy idempotencji** (zobacz schemat).
## Role + zakresy
@ -237,44 +237,44 @@ Typowe zakresy:
`talk.config` z `includeSecrets: true` wymaga `operator.talk.secrets`
(lub `operator.admin`).
Metody RPC Gateway rejestrowane przez Plugin mogą żądać własnego zakresu operatora, ale
zarezerwowane prefiksy administracyjne rdzenia (`config.*`, `exec.approvals.*`, `wizard.*`,
`update.*`) zawsze są rozwiązywane do `operator.admin`.
Metody RPC gateway zarejestrowane przez Plugin mogą żądać własnego zakresu operatora, ale
zarezerwowane główne prefiksy administracyjne (`config.*`, `exec.approvals.*`, `wizard.*`,
`update.*`) zawsze rozwiązują się do `operator.admin`.
Zakres metody jest tylko pierwszą bramką. Niektóre polecenia ukośnikowe dostępne przez
`chat.send` nakładają dodatkowo ostrzejsze kontrole na poziomie polecenia. Na przykład trwałe
Zakres metody jest tylko pierwszą bramką. Niektóre komendy slash osiągane przez
`chat.send` nakładają na to surowsze kontrole na poziomie komendy. 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, ponad
bazowy zakres metody:
podstawowym zakresem metody:
- żądania bez polecenia: `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`:
- żądania bez komend: `operator.pairing`
- żądania z komendami węzła innymi niż exec: `operator.pairing` + `operator.write`
- żądania zawierające `system.run`, `system.run.prepare` lub `system.which`:
`operator.pairing` + `operator.admin`
### Możliwości/polecenia/uprawnienia (węzeł)
### Możliwości/komendy/uprawnienia (node)
Węzły deklarują roszczenia możliwości w czasie łączenia:
Węzły deklarują twierdzenia o możliwościach w czasie połączenia:
- `caps`: kategorie możliwości wysokiego poziomu.
- `commands`: lista dozwolonych poleceń dla invoke.
- `commands`: allowlista komend dla invoke.
- `permissions`: szczegółowe przełączniki (np. `screen.record`, `camera.capture`).
Gateway traktuje je jako **roszczenia** i egzekwuje listy dozwolone po stronie serwera.
Gateway traktuje je jako **twierdzenia** i egzekwuje allowlisty po stronie serwera.
## Obecność
- `system-presence` zwraca wpisy kluczowane tożsamością urządzenia.
- Wpisy obecności zawierają `deviceId`, `roles` i `scopes`, aby interfejsy użytkownika mogły pokazać jeden wiersz na urządzenie
nawet gdy łączy się ono zarówno jako **operator**, jak i **węzeł**.
- `node.list` zawiera opcjonalne pola `lastSeenAtMs` i `lastSeenReason`. Połączone węzły zgłaszają
swój bieżący czas połączenia jako `lastSeenAtMs` z powodem `connect`; sparowane węzły mogą także zgłaszać
- `system-presence` zwraca wpisy kluczowane według 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` zawiera opcjonalne pola `lastSeenAtMs` i `lastSeenReason`. Połączone węzły raportują
czas bieżącego połączenia jako `lastSeenAtMs` z powodem `connect`; sparowane węzły mogą także raportować
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ł
Węzły mogą wywołać `node.event` z `event: "node.presence.alive"`, aby zarejestrować, że sparowany węzeł był
aktywny podczas wybudzenia w tle bez oznaczania go jako połączonego.
```json
@ -284,12 +284,12 @@ aktywny podczas wybudzenia w tle bez oznaczania go jako połączonego.
}
```
`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`.
`trigger` jest zamkniętym enumem: `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łowych; sesje bez urządzenia lub niesparowane zwracają `handled: false`.
Pomyślne gateway zwracają ustrukturyzowany wynik:
Udane gateway zwracają ustrukturyzowany wynik:
```json
{
@ -301,75 +301,75 @@ Pomyślne gateway zwracają ustrukturyzowany wynik:
```
Starsze gateway mogą nadal zwracać `{ "ok": true }` dla `node.event`; klienci powinni traktować to jako
potwierdzone RPC, nie jako trwałe utrwalenie obecności.
potwierdzone RPC, a nie jako trwałe utrwalenie obecności.
## Zakresowanie zdarzeń broadcast
Wypychanie przez serwer zdarzeń broadcast WebSocket jest bramkowane zakresem, aby sesje ograniczone do parowania lub tylko do węzła nie odbierały pasywnie treści sesji.
Zdarzenia broadcast wypychane przez serwer przez WebSocket są bramkowane zakresem, tak aby sesje o zakresie 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 `agent` i wyniki wywołań narzędzi) wymagają co najmniej `operator.read`. Sesje bez `operator.read` całkowicie pomijają te ramki.
- **Zdefiniowane przez Plugin broadcasty `plugin.*`** są bramkowane do `operator.write` lub `operator.admin`, zależnie od tego, jak zarejestrował je Plugin.
- **Zdarzenia statusu i transportu** (`heartbeat`, `presence`, `tick`, cykl życia połączenia/rozłączenia itd.) pozostają nieograniczone, aby stan transportu był widoczny dla każdej uwierzytelnionej sesji.
- **Nieznane rodziny zdarzeń broadcast** są domyślnie bramkowane zakresem (fail-closed), chyba że zarejestrowany handler jawnie je poluzuje.
- **Broadcasty `plugin.*` definiowane 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 połączenia/rozłączenia itd.) pozostają nieograniczone, aby stan transportu był obserwowalny dla każdej uwierzytelnionej sesji.
- **Nieznane rodziny zdarzeń broadcast** są domyślnie bramkowane zakresem (fail-closed), chyba że zarejestrowany handler jawnie je rozluźni.
Każde połączenie klienta utrzymuje własny numer sekwencyjny dla klienta, więc broadcasty zachowują monotoniczną kolejność na tym gnieździe nawet wtedy, gdy różni klienci widzą różne, filtrowane zakresem podzbiory strumienia zdarzeń.
Każde połączenie klienta zachowuje własny numer sekwencji per klient, więc broadcasty zachowują monotoniczne uporządkowanie na tym gnieździe nawet wtedy, gdy różni klienci widzą różne podzbiory strumienia zdarzeń odfiltrowane według zakresu.
## 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 odkrywania zbudowana z `src/gateway/server-methods-list.ts` oraz załadowanych
eksportów metod plugin/kanału. Traktuj ją jako odkrywanie funkcji, nie pełne
nie jest wygenerowany zrzut — `hello-ok.features.methods` jest konserwatywną listą
odkrywania zbudowaną z `src/gateway/server-methods-list.ts` oraz załadowanych
eksportów metod pluginu/kanału. Traktuj ją jako odkrywanie funkcji, a nie pełne
wyliczenie `src/gateway/server-methods/*.ts`.
<AccordionGroup>
<Accordion title="System i tożsamość">
- `health` zwraca buforowany lub świeżo sprawdzony snapshot stanu gateway.
- `diagnostics.stability` zwraca ostatni ograniczony rejestrator stabilności diagnostycznej. Przechowuje metadane operacyjne, takie jak nazwy zdarzeń, liczby, rozmiary w bajtach, odczyty pamięci, stan kolejki/sesji, nazwy kanałów/pluginów i identyfikatory sesji. Nie przechowuje tekstu czatu, treści webhook, wyników narzędzi, surowych treści żądań ani odpowiedzi, tokenów, cookies ani wartości sekretów. Wymagany jest zakres odczytu operatora.
- `health` zwraca buforowaną lub świeżo sprawdzoną migawkę stanu gateway.
- `diagnostics.stability` zwraca ostatni ograniczony rejestrator stabilności diagnostycznej. Zachowuje metadane operacyjne, takie jak nazwy zdarzeń, liczby, rozmiary bajtów, odczyty pamięci, stan kolejki/sesji, nazwy kanałów/pluginów i identyfikatory sesji. Nie zachowuje tekstu czatu, treści webhooków, wyników narzędzi, surowych treści żądań ani odpowiedzi, tokenów, ciasteczek ani wartości sekretów. Wymagany jest zakres odczytu operatora.
- `status` zwraca podsumowanie gateway w stylu `/status`; pola wrażliwe są uwzględniane tylko dla klientów operatora z zakresem administratora.
- `gateway.identity.get` zwraca tożsamość urządzenia gateway używaną przez przepływy relay i parowania.
- `system-presence` zwraca bieżący snapshot obecności dla połączonych urządzeń operatora/węzła.
- `system-presence` zwraca bieżącą migawkę obecności dla połączonych urządzeń operator/węzeł.
- `system-event` dopisuje zdarzenie systemowe i może aktualizować/rozgłaszać kontekst obecności.
- `last-heartbeat` zwraca ostatnie utrwalone zdarzenie heartbeat.
- `set-heartbeats` przełącza przetwarzanie heartbeat w gateway.
- `last-heartbeat` zwraca najnowsze utrwalone zdarzenie Heartbeat.
- `set-heartbeats` przełącza przetwarzanie Heartbeat na gateway.
</Accordion>
<Accordion title="Modele i użycie">
- `models.list` zwraca katalog modeli dozwolonych w runtime. Przekaż `{ "view": "configured" }` dla skonfigurowanych modeli w rozmiarze selektora (`agents.defaults.models` najpierw, potem `models.providers.*.models`) albo `{ "view": "all" }` dla pełnego katalogu.
- `usage.status` zwraca okna użycia dostawcy oraz podsumowania pozostałego limitu.
- `models.list` zwraca katalog modeli dozwolonych w czasie działania. Przekaż `{ "view": "configured" }` dla skonfigurowanych modeli o rozmiarze odpowiednim dla selektora (`agents.defaults.models` najpierw, potem `models.providers.*.models`) albo `{ "view": "all" }` dla pełnego katalogu.
- `usage.status` zwraca okna użycia dostawcy/podsumowania pozostałego limitu.
- `usage.cost` zwraca zagregowane podsumowania kosztów użycia dla zakresu dat.
- `doctor.memory.status` zwraca gotowość pamięci wektorowej / buforowanych osadzeń dla aktywnego domyślnego obszaru roboczego agenta. Przekaż `{ "probe": true }` lub `{ "deep": true }` tylko wtedy, gdy wywołujący jawnie chce sprawdzenia dostępności dostawcy osadzeń na żywo.
- `doctor.memory.remHarness` zwraca ograniczony, tylko do odczytu podgląd harnessu REM dla zdalnych klientów płaszczyzny sterowania. Może zawierać ścieżki obszaru roboczego, fragmenty pamięci, wyrenderowany ugruntowany Markdown i kandydatów do głębokiej promocji, więc wywołujący potrzebują `operator.read`.
- `doctor.memory.status` zwraca gotowość pamięci wektorowej / buforowanego osadzania dla aktywnego domyślnego obszaru roboczego agenta. Przekaż `{ "probe": true }` lub `{ "deep": true }` tylko wtedy, gdy wywołujący wyraźnie chce aktywnego pingowania dostawcy osadzania.
- `doctor.memory.remHarness` zwraca ograniczony, tylko do odczytu podgląd zestawu REM dla zdalnych klientów płaszczyzny sterowania. Może zawierać ścieżki obszaru roboczego, fragmenty pamięci, wyrenderowany ugruntowany Markdown i kandydatów do głębokiej promocji, więc wywołujący potrzebują `operator.read`.
- `sessions.usage` zwraca podsumowania użycia dla poszczególnych sesji.
- `sessions.usage.timeseries` zwraca szeregi czasowe użycia dla jednej sesji.
- `sessions.usage.timeseries` zwraca użycie w szeregach czasowych dla jednej sesji.
- `sessions.usage.logs` zwraca wpisy dziennika użycia dla jednej sesji.
</Accordion>
<Accordion title="Kanały i pomocnicze logowanie">
- `channels.status` zwraca podsumowania statusu wbudowanych oraz dołączonych kanałów/Pluginów.
<Accordion title="Kanały i pomocnicy logowania">
- `channels.status` zwraca podsumowania stanu wbudowanych + dołączonych kanałów/pluginów.
- `channels.logout` wylogowuje określony kanał/konto tam, gdzie kanał obsługuje wylogowanie.
- `web.login.start` uruchamia przepływ logowania QR/web dla bieżącego dostawcy kanału web obsługującego QR.
- `web.login.wait` czeka na zakończenie tego przepływu logowania QR/web i po powodzeniu uruchamia kanał.
- `web.login.wait` czeka na ukończenie tego przepływu logowania QR/web i po sukcesie uruchamia kanał.
- `push.test` wysyła testowe powiadomienie push APNs do zarejestrowanego węzła iOS.
- `voicewake.get` zwraca zapisane wyzwalacze słowa aktywującego.
- `voicewake.set` aktualizuje wyzwalacze słowa aktywującego i rozgłasza zmianę.
- `voicewake.get` zwraca zapisane wyzwalacze słów wybudzania.
- `voicewake.set` aktualizuje wyzwalacze słów wybudzania i rozgłasza zmianę.
</Accordion>
<Accordion title="Wiadomości i dzienniki">
- `send` to bezpośrednie RPC dostarczania wychodzącego dla wysyłek ukierunkowanych na kanał/konto/wątek poza runnerem czatu.
- `logs.tail` zwraca skonfigurowany ogon pliku dziennika Gateway z kontrolkami kursora/limitu i maksymalnej liczby bajtów.
- `send` to bezpośredni RPC dostarczania wychodzącego dla wysyłek kierowanych na kanał/konto/wątek poza runnerem czatu.
- `logs.tail` zwraca skonfigurowany końcowy fragment dziennika plikowego Gateway z kontrolą kursora/limitu i maksymalnej liczby bajtów.
</Accordion>
<Accordion title="Talk i TTS">
- `talk.config` zwraca efektywny ładunek konfiguracji Talk; `includeSecrets` wymaga `operator.talk.secrets` (lub `operator.admin`).
- `talk.config` zwraca efektywny payload konfiguracji Talk; `includeSecrets` wymaga `operator.talk.secrets` (lub `operator.admin`).
- `talk.mode` ustawia/rozgłasza bieżący stan trybu Talk dla klientów WebChat/Control UI.
- `talk.speak` syntetyzuje mowę przez aktywnego dostawcę mowy Talk.
- `tts.status` zwraca stan włączenia TTS, aktywnego dostawcę, dostawców awaryjnych i stan konfiguracji dostawcy.
- `tts.providers` zwraca widoczny spis dostawców TTS.
- `tts.status` zwraca stan włączenia TTS, aktywnego dostawcę, dostawców awaryjnych oraz stan konfiguracji dostawcy.
- `tts.providers` zwraca widoczny inwentarz dostawców TTS.
- `tts.enable` i `tts.disable` przełączają stan preferencji TTS.
- `tts.setProvider` aktualizuje preferowanego dostawcę TTS.
- `tts.convert` uruchamia jednorazową konwersję tekstu na mowę.
@ -377,159 +377,186 @@ wyliczenie `src/gateway/server-methods/*.ts`.
</Accordion>
<Accordion title="Sekrety, konfiguracja, aktualizacja i kreator">
- `secrets.reload` ponownie rozwiązuje aktywne SecretRefy i podmienia stan sekretów runtime tylko przy pełnym powodzeniu.
- `secrets.reload` ponownie rozwiązuje aktywne SecretRefs i podmienia stan sekretów w czasie działania tylko przy pełnym sukcesie.
- `secrets.resolve` rozwiązuje przypisania sekretów docelowych dla polecenia dla określonego zestawu poleceń/celów.
- `config.get` zwraca bieżącą migawkę konfiguracji i hash.
- `config.set` zapisuje zwalidowany ładunek konfiguracji.
- `config.set` zapisuje zweryfikowany payload konfiguracji.
- `config.patch` scala częściową aktualizację konfiguracji.
- `config.apply` waliduje i zastępuje pełny ładunek konfiguracji.
- `config.schema` zwraca aktywny ładunek schematu konfiguracji używany przez narzędzia Control UI i CLI: schemat, `uiHints`, wersję i metadane generowania, w tym metadane schematów Pluginów i kanałów, gdy runtime może je załadować. Schemat obejmuje metadane pól `title` / `description` pochodzące z tych samych etykiet i tekstu pomocy, których używa UI, w tym zagnieżdżone obiekty, wildcardy, elementy tablic oraz gałęzie kompozycji `anyOf` / `oneOf` / `allOf`, gdy istnieje pasująca dokumentacja pola.
- `config.schema.lookup` zwraca ładunek wyszukiwania ograniczony do ścieżki dla jednej ścieżki konfiguracji: znormalizowaną ścieżkę, płytki węzeł schematu, dopasowaną wskazówkę + `hintPath` oraz podsumowania bezpośrednich dzieci do zagłębiania się w UI/CLI. Węzły schematu wyszukiwania zachowują dokumentację widoczną dla użytkownika i typowe pola walidacyjne (`title`, `description`, `type`, `enum`, `const`, `format`, `pattern`, ograniczenia liczb/ciągów/tablic/obiektów oraz flagi takie jak `additionalProperties`, `deprecated`, `readOnly`, `writeOnly`). Podsumowania dzieci udostępniają `key`, znormalizowaną `path`, `type`, `required`, `hasChildren` oraz dopasowane `hint` / `hintPath`.
- `update.run` uruchamia przepływ aktualizacji Gateway i planuje restart tylko wtedy, gdy sama aktualizacja się powiedzie.
- `update.status` zwraca najnowszy zapisany sentinel restartu aktualizacji, w tym działającą wersję po restarcie, gdy jest dostępna.
- `wizard.start`, `wizard.next`, `wizard.status` i `wizard.cancel` udostępniają kreator wdrożeniowy przez WS RPC.
- `config.apply` waliduje + zastępuje pełny payload konfiguracji.
- `config.schema` zwraca payload aktywnego schematu konfiguracji używany przez narzędzia Control UI i CLI: schemat, `uiHints`, wersję oraz metadane generowania, w tym metadane schematów pluginów + kanałów, gdy środowisko uruchomieniowe może je załadować. Schemat zawiera metadane pól `title` / `description` pochodzące z tych samych etykiet i tekstu pomocy, których używa UI, w tym gałęzie zagnieżdżonych obiektów, symboli wieloznacznych, elementów tablicy oraz kompozycji `anyOf` / `oneOf` / `allOf`, gdy istnieje pasująca dokumentacja pól.
- `config.schema.lookup` zwraca payload wyszukiwania ograniczonego do ścieżki dla jednej ścieżki konfiguracji: znormalizowaną ścieżkę, płytki węzeł schematu, dopasowaną podpowiedź + `hintPath` oraz bezpośrednie podsumowania dzieci do drążenia 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 jak `additionalProperties`, `deprecated`, `readOnly`, `writeOnly`). Podsumowania dzieci ujawniają `key`, znormalizowaną `path`, `type`, `required`, `hasChildren`, a także dopasowane `hint` / `hintPath`.
- `update.run` uruchamia przepływ aktualizacji Gateway i planuje restart tylko wtedy, gdy sama aktualizacja się powiodła. Aktualizacje menedżera pakietów wymuszają nieodroczony restart aktualizacyjny bez okresu schłodzenia po podmianie pakietu, aby stary proces Gateway nie kontynuował leniwego ładowania z zastąpionego drzewa `dist`.
- `update.status` zwraca najnowszy zbuforowany sentinel restartu aktualizacji, w tym wersję uruchomioną po restarcie, gdy jest dostępna.
- `wizard.start`, `wizard.next`, `wizard.status` i `wizard.cancel` udostępniają kreatora wdrożenia przez WS RPC.
</Accordion>
<Accordion title="Pomocniki agenta i obszaru roboczego">
- `agents.list` zwraca skonfigurowane wpisy agentów, w tym efektywny model i metadane runtime.
- `agents.create`, `agents.update` i `agents.delete` zarządzają rekordami agentów oraz powiązaniami obszaru roboczego.
- `agents.files.list`, `agents.files.get` i `agents.files.set` zarządzają plikami startowymi obszaru roboczego udostępnionymi agentowi.
<Accordion title="Pomocnicy agenta i obszaru roboczego">
- `agents.list` zwraca skonfigurowane wpisy agentów, w tym efektywny model i metadane czasu działania.
- `agents.create`, `agents.update` i `agents.delete` zarządzają rekordami agentów i połączeniem z obszarem roboczym.
- `agents.files.list`, `agents.files.get` i `agents.files.set` zarządzają plikami startowymi obszaru roboczego udostępnianymi agentowi.
- `artifacts.list`, `artifacts.get` i `artifacts.download` udostępniają podsumowania artefaktów pochodzących z transkrypcji oraz pobrania dla jawnego zakresu `sessionKey`, `runId` lub `taskId`. Zapytania o przebiegi i zadania rozwiązują sesję właściciela po stronie serwera i zwracają tylko media transkrypcji z pasującym pochodzeniem; niebezpieczne lub lokalne źródła URL zwracają nieobsługiwane pobrania zamiast pobierania po stronie serwera.
- `agent.identity.get` zwraca efektywną tożsamość asystenta dla agenta lub sesji.
- `agent.wait` czeka na zakończenie uruchomienia i zwraca końcową migawkę, gdy jest dostępna.
- `agent.wait` czeka na zakończenie przebiegu i zwraca końcową migawkę, gdy jest dostępna.
</Accordion>
<Accordion title="Kontrola sesji">
- `sessions.list` zwraca bieżący indeks sesji, w tym metadane `agentRuntime` dla każdego wiersza, gdy skonfigurowany jest backend runtime agenta.
- `sessions.subscribe` i `sessions.unsubscribe` przełączają subskrypcje zdarzeń zmiany sesji dla bieżącego klienta WS.
- `sessions.messages.subscribe` i `sessions.messages.unsubscribe` przełączają subskrypcje zdarzeń transkryptu/wiadomości dla jednej sesji.
- `sessions.preview` zwraca ograniczone podglądy transkryptów dla określonych kluczy sesji.
- `sessions.list` zwraca bieżący indeks sesji, w tym metadane `agentRuntime` dla każdego wiersza, gdy skonfigurowany jest backend czasu działania agenta.
- `sessions.subscribe` i `sessions.unsubscribe` przełączają subskrypcje zdarzeń zmian sesji dla bieżącego klienta WS.
- `sessions.messages.subscribe` i `sessions.messages.unsubscribe` przełączają subskrypcje zdarzeń transkrypcji/wiadomości dla jednej sesji.
- `sessions.preview` zwraca ograniczone podglądy transkrypcji dla określonych kluczy sesji.
- `sessions.resolve` rozwiązuje lub kanonizuje cel sesji.
- `sessions.create` tworzy nowy wpis sesji.
- `sessions.send` wysyła wiadomość do istniejącej sesji.
- `sessions.steer` to wariant przerwania i sterowania dla aktywnej sesji.
- `sessions.abort` przerywa aktywną pracę dla sesji. Wywołujący może przekazać `key` plus opcjonalny `runId` albo przekazać sam `runId` dla aktywnych uruchomień, które Gateway może rozwiązać do sesji.
- `sessions.abort` przerywa aktywną pracę dla sesji. Wywołujący może przekazać `key` oraz opcjonalne `runId` albo przekazać samo `runId` dla aktywnych przebiegów, które Gateway może rozwiązać do sesji.
- `sessions.patch` aktualizuje metadane/nadpisania sesji i zgłasza rozwiązany model kanoniczny oraz efektywny `agentRuntime`.
- `sessions.reset`, `sessions.delete` i `sessions.compact` wykonują konserwację sesji.
- `sessions.get` zwraca pełny zapisany wiersz sesji.
- Wykonywanie czatu nadal używa `chat.history`, `chat.send`, `chat.abort` i `chat.inject`. `chat.history` jest znormalizowane do wyświetlania dla klientów UI: znaczniki dyrektyw inline 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ładne `NO_REPLY` / `no_reply`, są pomijane, a zbyt duże wiersze mogą zostać zastąpione placeholderami.
- Wykonanie czatu nadal używa `chat.history`, `chat.send`, `chat.abort` i `chat.inject`. `chat.history` jest normalizowane pod kątem wyświetlania dla klientów UI: wbudowane znaczniki 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>` oraz ucięte bloki wywołań narzędzi) i ujawnione tokeny kontrolne modelu ASCII/pełnej szerokości są usuwane, czyste wiersze asystenta z cichymi tokenami, takie jak dokładne `NO_REPLY` / `no_reply`, są pomijane, a zbyt duże wiersze mogą być zastępowane symbolami zastępczymi.
</Accordion>
<Accordion title="Parowanie urządzeń i tokeny urządzeń">
- `device.pair.list` zwraca oczekujące i zatwierdzone sparowane urządzenia.
- `device.pair.approve`, `device.pair.reject` i `device.pair.remove` zarządzają rekordami parowania urządzeń.
- `device.token.rotate` rotuje token sparowanego urządzenia w granicach zatwierdzonej roli i zakresu wywołującego.
- `device.token.revoke` unieważnia token sparowanego urządzenia w granicach zatwierdzonej roli i zakresu wywołującego.
- `device.token.rotate` rotuje token sparowanego urządzenia w granicach jego zatwierdzonej roli i zakresu wywołującego.
- `device.token.revoke` unieważnia token sparowanego urządzenia w granicach jego zatwierdzonej roli i zakresu wywołującego.
</Accordion>
<Accordion title="Parowanie węzłów, wywoływanie i oczekująca praca">
- `node.pair.request`, `node.pair.list`, `node.pair.approve`, `node.pair.reject`, `node.pair.remove` i `node.pair.verify` obejmują parowanie węzłów i weryfikację startową.
- `node.list` i `node.describe` zwracają stan znanych/połączonych węzłów.
- `node.rename` aktualizuje etykietę sparowanego węzła.
- `node.invoke` przekazuje polecenie do połączonego węzła.
<Accordion title="Parowanie Node, wywołania i oczekująca praca">
- `node.pair.request`, `node.pair.list`, `node.pair.approve`, `node.pair.reject`, `node.pair.remove` i `node.pair.verify` obejmują parowanie Node i weryfikację startową.
- `node.list` i `node.describe` zwracają stan znanych/połączonych Node.
- `node.rename` aktualizuje etykietę sparowanego Node.
- `node.invoke` przekazuje polecenie do połączonego Node.
- `node.invoke.result` zwraca wynik żądania wywołania.
- `node.event` przenosi zdarzenia pochodzące z węzła z powrotem do Gateway.
- `node.canvas.capability.refresh` odświeża tokeny możliwości canvas ograniczone zakresem.
- `node.pending.pull` i `node.pending.ack` to API kolejki połączonego węzła.
- `node.pending.enqueue` i `node.pending.drain` zarządzają trwałą oczekującą pracą dla węzłów offline/rozłączonych.
- `node.event` przenosi zdarzenia pochodzące z Node z powrotem do gateway.
- `node.canvas.capability.refresh` odświeża tokeny możliwości canvas o ograniczonym zakresie.
- `node.pending.pull` i `node.pending.ack` to API kolejki połączonego Node.
- `node.pending.enqueue` i `node.pending.drain` zarządzają trwałą oczekującą pracą dla Node offline/rozłączonych.
</Accordion>
<Accordion title="Rodziny zatwierdzeń">
- `exec.approval.request`, `exec.approval.get`, `exec.approval.list` i `exec.approval.resolve` obejmują jednorazowe żądania zatwierdzenia exec oraz wyszukiwanie/odtwarzanie oczekujących zatwierdzeń.
- `exec.approval.waitDecision` czeka na jedno oczekujące zatwierdzenie exec i zwraca ostateczną decyzję (lub `null` po przekroczeniu limitu czasu).
- `exec.approvals.get` i `exec.approvals.set` zarządzają migawkami zasad zatwierdzania exec Gateway.
- `exec.approvals.node.get` i `exec.approvals.node.set` zarządzają lokalną dla węzła zasadą zatwierdzania exec przez polecenia przekaźnika węzła.
- `plugin.approval.request`, `plugin.approval.list`, `plugin.approval.waitDecision` i `plugin.approval.resolve` obejmują przepływy zatwierdzania zdefiniowane przez Plugin.
- `exec.approvals.get` i `exec.approvals.set` zarządzają migawkami zasad zatwierdzania exec w gateway.
- `exec.approvals.node.get` i `exec.approvals.node.set` zarządzają lokalną dla Node zasadą zatwierdzania exec przez polecenia przekaźnika Node.
- `plugin.approval.request`, `plugin.approval.list`, `plugin.approval.waitDecision` i `plugin.approval.resolve` obejmują przepływy zatwierdzania definiowane przez plugin.
</Accordion>
<Accordion title="Automatyzacja, Skills i narzędzia">
- Automatyzacja: `wake` planuje natychmiastowe lub przy następnym Heartbeat wstrzyknięcie tekstu wybudzającego; `cron.list`, `cron.status`, `cron.add`, `cron.update`, `cron.remove`, `cron.run`, `cron.runs` zarządzają zaplanowaną pracą.
- Skills i narzędzia: `commands.list`, `skills.*`, `tools.catalog`, `tools.effective`.
- Automatyzacja: `wake` planuje natychmiastowe lub przy następnym Heartbeat wstrzyknięcie tekstu wybudzenia; `cron.list`, `cron.status`, `cron.add`, `cron.update`, `cron.remove`, `cron.run`, `cron.runs` zarządzają zaplanowaną pracą.
- Skills i narzędzia: `commands.list`, `skills.*`, `tools.catalog`, `tools.effective`, `tools.invoke`.
</Accordion>
</AccordionGroup>
### Typowe rodziny zdarzeń
### Wspólne rodziny zdarzeń
- `chat`: aktualizacje czatu UI, takie jak `chat.inject` i inne zdarzenia czatu
obejmujące tylko transkrypt.
- `session.message` i `session.tool`: aktualizacje transkryptu/strumienia zdarzeń dla
dotyczące wyłącznie transkrypcji.
- `session.message` i `session.tool`: aktualizacje transkrypcji/strumienia zdarzeń dla
subskrybowanej sesji.
- `sessions.changed`: indeks sesji lub metadane uległy zmianie.
- `sessions.changed`: zmieniono indeks sesji lub metadane.
- `presence`: aktualizacje migawki obecności systemu.
- `tick`: okresowe zdarzenie keepalive / żywotności.
- `health`: aktualizacja migawki kondycji Gateway.
- `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`: rozgłoszenie żądania wywołania węzła.
- `cron`: zdarzenie zmiany przebiegu/zadania Cron.
- `shutdown`: powiadomienie o wyłączeniu gateway.
- `node.pair.requested` / `node.pair.resolved`: cykl życia parowania Node.
- `node.invoke.request`: rozgłaszanie żądania wywołania Node.
- `device.pair.requested` / `device.pair.resolved`: cykl życia sparowanego urządzenia.
- `voicewake.changed`: konfiguracja wyzwalacza słowa aktywującego uległa zmianie.
- `voicewake.changed`: zmieniono konfigurację wyzwalacza słów wybudzania.
- `exec.approval.requested` / `exec.approval.resolved`: cykl życia zatwierdzenia exec.
- `plugin.approval.requested` / `plugin.approval.resolved`: cykl życia zatwierdzenia Pluginu.
- `plugin.approval.requested` / `plugin.approval.resolved`: cykl życia zatwierdzenia pluginu.
### Metody pomocnicze węzła
### Metody pomocnicze Node
- Węzły mogą wywołać `skills.bins`, aby pobrać bieżącą listę plików wykonywalnych Skills
do kontroli automatycznego zezwalania.
- Nodes mogą wywołać `skills.bins`, aby pobrać bieżącą listę plików wykonywalnych Skills
na potrzeby kontroli automatycznego zezwalania.
### Metody pomocnicze operatora
- Operatorzy mogą wywołać `commands.list` (`operator.read`), aby pobrać spis poleceń środowiska wykonawczego dla agenta.
- Operatorzy mogą wywołać `commands.list` (`operator.read`), aby pobrać
inwentarz poleceń czasu wykonywania dla agenta.
- `agentId` jest opcjonalne; pomiń je, aby odczytać domyślny obszar roboczy agenta.
- `scope` kontroluje, do której powierzchni kieruje główne `name`:
- `text` zwraca główny token polecenia tekstowego bez początkowego `/`
- `native` oraz domyślna ścieżka `both` zwracają natywne nazwy uwzględniające dostawcę, gdy są dostępne
- `textAliases` przenosi dokładne aliasy z ukośnikiem, takie jak `/model` i `/m`.
- `nativeName` przenosi natywną nazwę polecenia uwzględniającą dostawcę, gdy taka istnieje.
- `provider` jest opcjonalne i wpływa tylko na nazewnictwo natywne oraz dostępność natywnych poleceń pluginów.
- `scope` kontroluje, do której powierzchni kieruje podstawowe `name`:
- `text` zwraca podstawowy token polecenia tekstowego bez początkowego `/`
- `native` oraz domyślna ścieżka `both` zwracają natywne nazwy świadome dostawcy,
gdy są dostępne
- `textAliases` zawiera dokładne aliasy z ukośnikiem, takie jak `/model` i `/m`.
- `nativeName` zawiera natywną nazwę polecenia świadomą dostawcy, gdy taka istnieje.
- `provider` jest opcjonalne i wpływa tylko na nazewnictwo natywne oraz dostępność
natywnych poleceń Plugin.
- `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:
- Operatorzy mogą wywołać `tools.catalog` (`operator.read`), aby pobrać katalog narzędzi czasu wykonywania dla
agenta. Odpowiedź obejmuje pogrupowane narzędzia oraz 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 spis narzędzi dla sesji.
- `pluginId`: właściciel Plugin, gdy `source="plugin"`
- `optional`: czy narzędzie Plugin jest opcjonalne
- Operatorzy mogą wywołać `tools.effective` (`operator.read`), aby pobrać efektywny w czasie wykonywania
inwentarz narzędzi dla sesji.
- `sessionKey` jest wymagane.
- Gateway wyprowadza zaufany kontekst środowiska wykonawczego z sesji po stronie serwera, zamiast akceptować uwierzytelnianie lub kontekst dostarczenia podany przez wywołującego.
- Odpowiedź jest ograniczona do sesji i odzwierciedla to, czego aktywna konwersacja może używać w tej chwili, w tym narzędzia core, pluginów i kanałów.
- Operatorzy mogą wywołać `skills.status` (`operator.read`), aby pobrać widoczny spis umiejętności dla agenta.
- Gateway wywodzi zaufany kontekst czasu wykonywania 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 konwersacja może użyć teraz,
w tym narzędzia rdzenia, Plugin i kanału.
- 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` oraz
`idempotencyKey` są opcjonalne.
- Jeśli obecne są zarówno `sessionKey`, jak i `agentId`, rozpoznany agent sesji musi pasować do
`agentId`.
- Odpowiedź jest kopertą przeznaczoną dla SDK z polami `ok`, `toolName`, opcjonalnym `output` oraz 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.
- Odpowiedź obejmuje 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.install` (`operator.admin`) w dwóch trybach:
- Tryb ClawHub: `{ source: "clawhub", slug, version?, force? }` instaluje folder umiejętności w katalogu `skills/` domyślnego obszaru roboczego agenta.
- Tryb instalatora Gateway: `{ name, installId, dangerouslyForceUnsafeInstall?, timeoutMs? }` uruchamia zadeklarowaną akcję `metadata.openclaw.install` na hoście Gateway.
- Tryb ClawHub: `{ source: "clawhub", slug, version?, force? }` instaluje
folder Skills w katalogu `skills/` domyślnego obszaru roboczego agenta.
- Tryb instalatora Gateway: `{ name, installId, dangerouslyForceUnsafeInstall?, timeoutMs? }`
uruchamia zadeklarowaną akcję `metadata.openclaw.install` na hoście Gateway.
- 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 aktualizuje wartości `skills.entries.<skillKey>`, takie jak `enabled`, `apiKey` i `env`.
- Tryb ClawHub aktualizuje jeden śledzony slug albo wszystkie śledzone instalacje ClawHub w
domyślnym obszarze roboczym agenta.
- Tryb konfiguracji aktualizuje wartości `skills.entries.<skillKey>`, takie jak `enabled`,
`apiKey` i `env`.
### Widoki `models.list`
`models.list` przyjmuje opcjonalny parametr `view`:
`models.list` akceptuje opcjonalny parametr `view`:
- Pominięty lub `"default"`: bieżące zachowanie środowiska wykonawczego. Jeśli skonfigurowano `agents.defaults.models`, odpowiedzią jest dozwolony katalog; w przeciwnym razie odpowiedzią jest pełny katalog Gateway.
- `"configured"`: zachowanie o rozmiarze selektora. Jeśli skonfigurowano `agents.defaults.models`, nadal ma pierwszeństwo. W przeciwnym razie odpowiedź używa jawnych wpisów `models.providers.*.models`, z powrotem do pełnego katalogu tylko wtedy, gdy nie istnieją żadne skonfigurowane wiersze modeli.
- Pominięty lub `"default"`: bieżące zachowanie czasu wykonywania. Jeśli skonfigurowano `agents.defaults.models`, odpowiedzią jest dozwolony katalog; w przeciwnym razie odpowiedzią jest pełny katalog Gateway.
- `"configured"`: zachowanie o rozmiarze selektora. Jeśli skonfigurowano `agents.defaults.models`, nadal ma pierwszeństwo. W przeciwnym razie odpowiedź używa jawnych wpisów `models.providers.*.models`, przechodząc do pełnego katalogu tylko wtedy, gdy nie istnieją żadne 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 rozstrzygają 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 przekazane dalej wywołania `node.invoke system.run` ponownie używają tego kanonicznego `systemRunPlan` jako autorytatywnego kontekstu polecenia/cwd/sesji.
- Jeśli wywołujący zmodyfikuje `command`, `rawCommand`, `cwd`, `agentId` lub `sessionKey` między przygotowaniem a końcowym zatwierdzonym przekazaniem `system.run`, Gateway odrzuca uruchomienie zamiast ufać zmodyfikowanemu ładunkowi.
- Dla `host=node`, `exec.approval.request` musi zawierać `systemRunPlan` (kanoniczne `argv`/`cwd`/`rawCommand`/metadane sesji). Żądania bez `systemRunPlan` są odrzucane.
- Po zatwierdzeniu przekazane dalej wywołania `node.invoke system.run` ponownie używają tego kanonicznego
`systemRunPlan` jako autorytatywnego kontekstu polecenia/cwd/sesji.
- Jeśli wywołujący zmodyfikuje `command`, `rawCommand`, `cwd`, `agentId` lub
`sessionKey` między przygotowaniem a końcowym zatwierdzonym przekazaniem `system.run`, Gateway
odrzuca uruchomienie zamiast ufać zmodyfikowanemu ładunkowi.
## Awaryjne dostarczanie agenta
- Żądania `agent` mogą zawierać `deliver=true`, aby zażądać dostarczenia wychodzącego.
- `bestEffortDeliver=false` zachowuje ścisłe działanie: nierozwiązane albo tylko wewnętrzne cele dostarczenia zwracają `INVALID_REQUEST`.
- `bestEffortDeliver=true` pozwala na powrót do wykonania tylko w sesji, gdy nie da się rozwiązać zewnętrznej dostarczalnej trasy (na przykład sesje wewnętrzne/webchat albo niejednoznaczne konfiguracje wielokanałowe).
- `bestEffortDeliver=false` zachowuje ścisłe zachowanie: nierozpoznane lub wyłącznie wewnętrzne cele dostarczania zwracają `INVALID_REQUEST`.
- `bestEffortDeliver=true` pozwala na powrót do wykonywania tylko w sesji, gdy nie da się rozpoznać zewnętrznej trasy możliwej do dostarczenia (na przykład sesje wewnętrzne/webchat lub niejednoznaczne konfiguracje wielokanałowe).
## Wersjonowanie
@ -542,111 +569,145 @@ wyliczenie `src/gateway/server-methods/*.ts`.
### Stałe klienta
Klient referencyjny w `src/gateway/client.ts` używa tych wartości domyślnych. Wartości są stabilne w protokole v3 i stanowią oczekiwany punkt odniesienia dla klientów zewnętrznych.
Klient referencyjny w `src/gateway/client.ts` używa tych wartości domyślnych. Wartości są
stabilne w protocol v3 i stanowią oczekiwaną bazę dla klientów zewnętrznych.
| Stała | Domyślnie | Źródło |
| --------------------------------------- | ----------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| `PROTOCOL_VERSION` | `3` | `src/gateway/protocol/schema/protocol-schemas.ts` |
| Limit czasu żądania (na RPC) | `30_000` ms | `src/gateway/client.ts` (`requestTimeoutMs`) |
| Limit czasu preauth / connect-challenge | `15_000` ms | `src/gateway/handshake-timeouts.ts` (config/env może zwiększyć sparowany budżet serwera/klienta) |
| Początkowe opóźnienie ponownego łączenia | `1_000` ms | `src/gateway/client.ts` (`backoffMs`) |
| Maks. opóźnienie ponownego łączenia | `30_000` ms | `src/gateway/client.ts` (`scheduleReconnect`) |
| Ograniczenie szybkiej ponownej próby po zamknięciu 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ł tick (przed `hello-ok`) | `30_000` ms | `src/gateway/client.ts` |
| Zamknięcie z powodu limitu czasu tick | kod `4000`, gdy cisza przekracza `tickIntervalMs * 2` | `src/gateway/client.ts` |
| `MAX_PAYLOAD_BYTES` | `25 * 1024 * 1024` (25 MB) | `src/gateway/server-constants.ts` |
| Stała | Domyślna | Źródło |
| ----------------------------------------- | ---------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| `PROTOCOL_VERSION` | `3` | `src/gateway/protocol/schema/protocol-schemas.ts` |
| Limit czasu żądania (na RPC) | `30_000` ms | `src/gateway/client.ts` (`requestTimeoutMs`) |
| Limit czasu preauth / connect-challenge | `15_000` ms | `src/gateway/handshake-timeouts.ts` (config/env mogą zwiększyć sparowany budżet serwera/klienta) |
| Początkowe opóźnienie ponownego połączenia | `1_000` ms | `src/gateway/client.ts` (`backoffMs`) |
| Maks. opóźnienie ponownego połączenia | `30_000` ms | `src/gateway/client.ts` (`scheduleReconnect`) |
| Ograniczenie szybkiej próby po zamknięciu tokena 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ł taktu (przed `hello-ok`) | `30_000` ms | `src/gateway/client.ts` |
| Zamknięcie po przekroczeniu limitu czasu taktu | kod `4000`, gdy cisza przekracza `tickIntervalMs * 2` | `src/gateway/client.ts` |
| `MAX_PAYLOAD_BYTES` | `25 * 1024 * 1024` (25 MB) | `src/gateway/server-constants.ts` |
Serwer ogłasza efektywne `policy.tickIntervalMs`, `policy.maxPayload` i `policy.maxBufferedBytes` w `hello-ok`; klienci powinni respektować te wartości zamiast domyślnych wartości sprzed uzgadniania.
Serwer ogłasza efektywne wartości `policy.tickIntervalMs`, `policy.maxPayload`
oraz `policy.maxBufferedBytes` w `hello-ok`; klienci powinni respektować te wartości
zamiast wartości domyślnych sprzed uzgadniania.
## Uwierzytelnianie
- Uwierzytelnianie Gateway za pomocą współdzielonego sekretu używa `connect.params.auth.token` lub `connect.params.auth.password`, zależnie od skonfigurowanego trybu uwierzytelniania.
- Tryby przenoszące tożsamość, takie jak Tailscale Serve (`gateway.auth.allowTailscale: true`) albo nie-loopback `gateway.auth.mode: "trusted-proxy"`, spełniają kontrolę uwierzytelniania połączenia na podstawie nagłówków żądania zamiast `connect.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 parowaniu Gateway wydaje **token urządzenia** ograniczony do roli połączenia + zakresów. Jest zwracany w `hello-ok.auth.deviceToken` i powinien zostać utrwalony przez klienta do przyszłych połączeń.
- Klienci powinni utrwalać główne `hello-ok.auth.deviceToken` po każdym udanym połączeniu.
- Ponowne łączenie z użyciem tego **zapisanego** tokenu 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, niejawnego zakresu tylko administracyjnego.
- Składanie uwierzytelniania połączenia po stronie klienta (`selectConnectAuth` w `src/gateway/client.ts`):
- `auth.password` jest ortogonalne i zawsze jest przekazywane, gdy jest ustawione.
- `auth.token` jest wypełniane według priorytetu: najpierw jawny token współdzielony, potem jawny `deviceToken`, a następnie zapisany token dla urządzenia (kluczowany przez `deviceId` + `role`).
- `auth.bootstrapToken` jest wysyłane tylko wtedy, gdy żadne z powyższych nie rozwiązało `auth.token`. Token współdzielony albo dowolny rozwiązany token urządzenia go wycisza.
- Automatyczne promowanie zapisanego tokenu urządzenia przy jednorazowej ponownej próbie `AUTH_TOKEN_MISMATCH` jest ograniczone tylko do **zaufanych punktów końcowych** — loopback albo `wss://` z przypiętym `tlsFingerprint`. Publiczne `wss://` bez przypięcia się nie kwalifikuje.
- Dodatkowe wpisy `hello-ok.auth.deviceTokens` są tokenami przekazania bootstrap. Utrwalaj je tylko wtedy, gdy połączenie używało uwierzytelniania bootstrap na zaufanym transporcie, takim jak `wss://` albo parowanie loopback/lokalne.
- Jeśli klient podaje **jawny** `deviceToken` albo jawne `scopes`, zestaw zakresów żądany przez wywołującego pozostaje autorytatywny; zakresy z pamięci podręcznej są ponownie używane tylko wtedy, gdy klient ponownie używa zapisanego tokenu dla urządzenia.
- Tokeny urządzeń można rotować/odwoływać za pomocą `device.token.rotate` i `device.token.revoke` (wymaga zakresu `operator.pairing`).
- `device.token.rotate` zwraca metadane rotacji. Zwraca zastępczy token bearer tylko dla wywołań z tego samego urządzenia, które są już uwierzytelnione tym tokenem urządzenia, aby klienci używający wyłącznie tokenu mogli utrwalić zamiennik przed ponownym połączeniem. Rotacje współdzielone/administracyjne nie zwracają 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 zatwierdzenie parowania nigdy nie przyznało.
- Dla sesji tokenu sparowanego urządzenia zarządzanie urządzeniem jest ograniczone do samego siebie, 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.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 niebędący administratorem nie mogą rotować ani odwoływać szerszego tokenu operatora niż ten, który już posiadają.
- Niepowodzenia uwierzytelniania zawierają `error.details.code` oraz wskazówki odzyskiwania:
- Uwierzytelnianie Gateway z użyciem 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 nie-loopback
`gateway.auth.mode: "trusted-proxy"`, spełniają sprawdzenie uwierzytelnienia 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 publicznym/niezaufanym ingress.
- Po sparowaniu Gateway wystawia **token urządzenia** ograniczony do roli połączenia
+ zakresów. Jest zwracany w `hello-ok.auth.deviceToken` i powinien być
trwale zapisany przez klienta na potrzeby przyszłych połączeń.
- Klienci powinni trwale zapisywać główny `hello-ok.auth.deviceToken` po każdym
udanym połączeniu.
- Ponowne łączenie z tym **zapisanym** tokenem urządzenia powinno też ponownie używać zapisanego
zatwierdzonego zestawu zakresów dla tego tokenu. Zachowuje to dostęp read/probe/status,
który został już przyznany, i pozwala uniknąć cichego zawężenia ponownych połączeń do
węższego, niejawnego 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 jest przekazywane, gdy jest ustawione.
- `auth.token` jest wypełniane według priorytetu: najpierw jawny token współdzielony,
następnie jawny `deviceToken`, a potem zapisany token dla urządzenia (kluczowany przez
`deviceId` + `role`).
- `auth.bootstrapToken` jest wysyłany tylko wtedy, gdy żadne z powyższych nie rozwiązało
`auth.token`. Token współdzielony lub dowolny rozwiązany token urządzenia go wyłącza.
- Automatyczne promowanie zapisanego tokenu urządzenia przy jednorazowej
ponownej próbie `AUTH_TOKEN_MISMATCH` jest ograniczone do **wyłącznie zaufanych punktów końcowych** —
loopback albo `wss://` z przypiętym `tlsFingerprint`. Publiczne `wss://`
bez pinningu się nie kwalifikuje.
- Dodatkowe wpisy `hello-ok.auth.deviceTokens` to tokeny przekazania bootstrap.
Zapisuj je trwale tylko wtedy, gdy połączenie używało uwierzytelniania bootstrap na zaufanym transporcie,
takim jak `wss://` albo parowanie loopback/lokalne.
- Jeśli klient podaje **jawny** `deviceToken` albo jawne `scopes`, ten
żądany przez wywołującego zestaw zakresów pozostaje autorytatywny; zakresy z cache są
używane ponownie tylko wtedy, gdy klient ponownie używa zapisanego tokenu dla urządzenia.
- Tokeny urządzeń można rotować/odwoływać przez `device.token.rotate` i
`device.token.revoke` (wymaga zakresu `operator.pairing`).
- `device.token.rotate` zwraca metadane rotacji. Zwraca zastępczy
token bearer tylko dla wywołań z tego samego urządzenia, które są już uwierzytelnione tym
tokenem urządzenia, aby klienci używający wyłącznie tokenu mogli zapisać jego zamiennik przed
ponownym połączeniem. Rotacje współdzielone/admin nie zwracają tokenu bearer.
- Wystawianie, 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 zatwierdzenie parowania nigdy nie przyznało.
- W przypadku sparowanych sesji tokenów urządzeń zarządzanie urządzeniami jest ograniczone do siebie, chyba że
wywołujący ma również `operator.admin`: wywołujący bez uprawnień administratora mogą usuwać/odwoływać/rotować
tylko wpis **własnego** urządzenia.
- `device.token.rotate` i `device.token.revoke` sprawdzają też 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ż mają.
- Błędy uwierzytelniania zawierają `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 z pamięci podręcznej dla urządzenia.
- Zaufani klienci mogą podjąć jedną ograniczoną ponowną próbę z tokenem dla urządzenia z cache.
- Jeśli ta ponowna próba się nie powiedzie, klienci powinni zatrzymać automatyczne pętle ponownego łączenia i pokazać wskazówki działań operatora.
## Tożsamość urządzenia + parowanie
- Węzły powinny zawierać stabilną tożsamość urządzenia (`device.id`) wyprowadzoną z
- Węzły powinny zawierać stabilną tożsamość urządzenia (`device.id`) pochodzącą z
odcisku palca pary kluczy.
- Gateway wydają tokeny na urządzenie + rolę.
- Zatwierdzenia parowania są wymagane dla nowych identyfikatorów urządzeń, chyba że
włączone jest lokalne automatyczne zatwierdzanie.
- Gateway wystawiają 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 też wąską ścieżkę samopołączenia lokalną dla backendu/kontenera dla
- OpenClaw ma też wąską ścieżkę samopołączenia lokalnego dla backendu/kontenera na potrzeby
zaufanych przepływów pomocniczych ze współdzielonym sekretem.
- Połączenia z tego samego hosta przez tailnet lub LAN nadal są traktowane jako zdalne przy parowaniu i
- Połączenia z tego samego hosta przez tailnet lub LAN nadal są traktowane jako zdalne na potrzeby parowania i
wymagają zatwierdzenia.
- Klienty WS zwykle dołączają tożsamość `device` podczas `connect` (operator +
węzeł). Jedyne wyjątki operatora bez urządzenia to jawne ścieżki zaufania:
- `gateway.controlUi.allowInsecureAuth=true` dla zgodności niezabezpieczonego HTTP tylko na localhost.
- pomyślne uwierzytelnienie operatora Control UI `gateway.auth.mode: "trusted-proxy"`.
- Klienci WS zwykle dołączają 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 niebezpiecznego HTTP tylko na localhost.
- udane uwierzytelnianie operatora Control UI w `gateway.auth.mode: "trusted-proxy"`.
- `gateway.controlUi.dangerouslyDisableDeviceAuth=true` (awaryjne obejście, poważne obniżenie bezpieczeństwa).
- RPC backendu `gateway-client` przez direct-loopback uwierzytelnione współdzielonym
- bezpośrednie backendowe RPC `gateway-client` przez loopback uwierzytelnione współdzielonym
tokenem/hasłem Gateway.
- 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 wyzwania, `connect` zwraca teraz
kody szczegółów `DEVICE_AUTH_*` w `error.details.code` ze stabilnym `error.details.reason`.
Dla starszych klientów, którzy nadal używają podpisywania sprzed challenge, `connect` zwraca teraz
kody szczegółów `DEVICE_AUTH_*` pod `error.details.code` ze stabilnym `error.details.reason`.
Typowe błędy migracji:
Typowe niepowodzenia migracji:
| Komunikat | details.code | details.reason | Znaczenie |
| --------------------------- | -------------------------------- | ------------------------ | -------------------------------------------------- |
| `device nonce required` | `DEVICE_AUTH_NONCE_REQUIRED` | `device-nonce-missing` | Klient pominął `device.nonce` (lub wysłał pustą wartość). |
| `device nonce mismatch` | `DEVICE_AUTH_NONCE_MISMATCH` | `device-nonce-mismatch` | Klient podpisał przy użyciu nieaktualnego/nieprawidłowego nonce. |
| `device signature invalid` | `DEVICE_AUTH_SIGNATURE_INVALID` | `device-signature` | Ładunek podpisu nie pasuje do ładunku v2. |
| `device nonce required` | `DEVICE_AUTH_NONCE_REQUIRED` | `device-nonce-missing` | Klient pominął `device.nonce` (albo wysłał pusty). |
| `device nonce mismatch` | `DEVICE_AUTH_NONCE_MISMATCH` | `device-nonce-mismatch` | Klient podpisał z 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/kanonikalizacja klucza publicznego nie powiodła się. |
| `device public key invalid` | `DEVICE_AUTH_PUBLIC_KEY_INVALID` | `device-public-key` | Format/kanonizacja klucza publicznego nie powiodły się. |
Cel migracji:
- Zawsze czekaj na `connect.challenge`.
- Podpisz ładunek v2 zawierający nonce serwera.
- Wyślij ten sam nonce w `connect.params.device.nonce`.
- Podpisuj ładunek v2, który zawiera nonce serwera.
- Wysyłaj ten sam nonce w `connect.params.device.nonce`.
- Preferowany ładunek podpisu to `v3`, który wiąże `platform` i `deviceFamily`
oprócz pól urządzenia/klienta/roli/zakresów/tokenu/nonce.
- Starsze podpisy `v2` pozostają akceptowane dla zgodności, ale przypięcie metadanych
sparowanego urządzenia nadal kontroluje politykę poleceń przy ponownym połączeniu.
- Starsze podpisy `v2` pozostają akceptowane dla zgodności, ale przypięcie
metadanych sparowanego urządzenia nadal kontroluje zasady poleceń przy ponownym połączeniu.
## TLS + przypinanie
## TLS + pinning
- TLS jest obsługiwany dla połączeń WS.
- Klienty mogą opcjonalnie przypiąć odcisk palca certyfikatu Gateway (zobacz konfigurację `gateway.tls`
oraz `gateway.remote.tlsFingerprint` lub CLI `--tls-fingerprint`).
- 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ładny zakres jest zdefiniowany przez
Ten protokół udostępnia **pełne API Gateway** (status, kanały, modele, chat,
agent, sesje, węzły, zatwierdzenia itd.). Dokładna powierzchnia jest zdefiniowana przez
schematy TypeBox w `src/gateway/protocol/schema.ts`.
## Powiązane
- [Protokół mostu](/pl/gateway/bridge-protocol)
- [Instrukcja operacyjna Gateway](/pl/gateway)
- [Protokół Bridge](/pl/gateway/bridge-protocol)
- [Runbook Gateway](/pl/gateway)

275
docs/pl/gateway/troubleshooting.md
View File

@ -1,24 +1,24 @@
---
read_when:
- Centrum rozwiązywania problemów skierowało Cię tutaj w celu dokładniejszej diagnostyki
- Potrzebne są stabilne sekcje instrukcji operacyjnej oparte na objawach, z dokładnymi poleceniami
- Centrum rozwiązywania problemów skierowało Cię tutaj w celu przeprowadzenia dokładniejszej diagnostyki
- Potrzebujesz stabilnych sekcji runbooka opartych na objawach z dokładnymi poleceniami
sidebarTitle: Troubleshooting
summary: Szczegółowa procedura rozwiązywania problemów z Gateway, kanałami, automatyzacją, węzłami i przeglądarką
summary: Szczegółowy runbook rozwiązywania problemów z Gateway, kanałami, automatyzacją, węzłami i przeglądarką
title: Rozwiązywanie problemów
x-i18n:
generated_at: "2026-04-30T09:57:07Z"
generated_at: "2026-05-01T09:59:27Z"
model: gpt-5.5
provider: openai
source_hash: 48735a68daa92678867a9cafb3ceeb37063bb91dee8c4c94e185f74eb0296fcb
source_hash: a808dcfd8527b041f629cff24308550f961e9eeb4d7d4ce6f1ce84dff6bbef89
source_path: gateway/troubleshooting.md
workflow: 16
---
Ta strona to szczegółowy runbook. Zacznij od [/help/troubleshooting](/pl/help/troubleshooting), jeśli najpierw chcesz przejść przez szybki przepływ triage.
Ta strona to szczegółowy runbook. Zacznij od [/help/troubleshooting](/pl/help/troubleshooting), jeśli najpierw chcesz przejść szybką ścieżkę triage.
## Drabina poleceń
Uruchom najpierw te polecenia, w tej kolejności:
Uruchom je najpierw, w tej kolejności:
```bash
openclaw status
@ -28,17 +28,17 @@ openclaw doctor
openclaw channels status --probe
```
Oczekiwane sygnały zdrowego stanu:
Oczekiwane sygnały poprawnego działania:
- `openclaw gateway status` pokazuje `Runtime: running`, `Connectivity probe: ok` oraz wiersz `Capability: ...`.
- `openclaw doctor` nie zgłasza blokujących problemów z konfiguracją ani usługami.
- `openclaw channels status --probe` pokazuje aktualny status transportu dla każdego konta oraz, tam gdzie jest to obsługiwane, wyniki sondowania/audytu, takie jak `works` lub `audit ok`.
- `openclaw doctor` nie zgłasza blokujących problemów z konfiguracją/usługą.
- `openclaw channels status --probe` pokazuje bieżący status transportu dla każdego konta oraz, tam gdzie jest to obsługiwane, wyniki sondy/audytu, takie jak `works` lub `audit ok`.
## Instalacje split brain i ochrona nowszej konfiguracji
## Instalacje split brain i zabezpieczenie nowszej konfiguracji
Użyj tego, gdy usługa Gateway niespodziewanie zatrzymuje się po aktualizacji albo logi pokazują, że jeden plik binarny `openclaw` jest starszy niż wersja, która ostatnio zapisała `openclaw.json`.
Użyj tego, gdy usługa gateway nieoczekiwanie zatrzymuje się po aktualizacji albo logi pokazują, że jeden plik binarny `openclaw` jest starszy niż wersja, która ostatnio zapisała `openclaw.json`.
OpenClaw oznacza zapisy konfiguracji polem `meta.lastTouchedVersion`. Polecenia tylko do odczytu nadal mogą sprawdzać konfigurację zapisaną przez nowszy OpenClaw, ale mutacje procesów i usług odmawiają kontynuacji ze starszego pliku binarnego. Zablokowane akcje obejmują uruchamianie, zatrzymywanie, restartowanie i odinstalowywanie usługi Gateway, wymuszoną ponowną instalację usługi, uruchomienie Gateway w trybie usługi oraz czyszczenie portu przez `gateway --force`.
OpenClaw oznacza zapisy konfiguracji polem `meta.lastTouchedVersion`. Polecenia tylko do odczytu nadal mogą sprawdzać konfigurację zapisaną przez nowszą wersję OpenClaw, ale mutacje procesów i usług odmawiają kontynuacji ze starszego pliku binarnego. Blokowane działania obejmują uruchamianie, zatrzymywanie, restart, odinstalowanie usługi gateway, wymuszoną ponowną instalację usługi, uruchamianie gateway w trybie usługi oraz czyszczenie portu przez `gateway --force`.
```bash
which openclaw
@ -49,10 +49,10 @@ openclaw config get meta.lastTouchedVersion
<Steps>
<Step title="Fix PATH">
Popraw `PATH`, aby `openclaw` wskazywał nowszą instalację, a następnie ponownie uruchom akcję.
Popraw `PATH`, aby `openclaw` wskazywał nowszą instalację, a następnie ponownie uruchom działanie.
</Step>
<Step title="Reinstall the gateway service">
Ponownie zainstaluj docelową usługę Gateway z nowszej instalacji:
Ponownie zainstaluj docelową usługę gateway z nowszej instalacji:
```bash
openclaw gateway install --force
@ -61,12 +61,12 @@ openclaw config get meta.lastTouchedVersion
</Step>
<Step title="Remove stale wrappers">
Usuń przestarzałe pakiety systemowe lub stare wpisy wrapperów, które nadal wskazują stary plik binarny `openclaw`.
Usuń nieaktualny pakiet systemowy lub stare wpisy wrappera, które nadal wskazują stary plik binarny `openclaw`.
</Step>
</Steps>
<Warning>
Tylko w przypadku celowego downgrade’u lub awaryjnego odzyskiwania ustaw `OPENCLAW_ALLOW_OLDER_BINARY_DESTRUCTIVE_ACTIONS=1` dla pojedynczego polecenia. Przy normalnej pracy pozostaw tę zmienną nieustawioną.
Tylko w przypadku celowego obniżenia wersji lub awaryjnego odzyskiwania ustaw `OPENCLAW_ALLOW_OLDER_BINARY_DESTRUCTIVE_ACTIONS=1` dla pojedynczego polecenia. Przy normalnym działaniu pozostaw tę zmienną nieustawioną.
</Warning>
## Anthropic 429 wymaga dodatkowego użycia dla długiego kontekstu
@ -83,7 +83,7 @@ Szukaj:
- Wybrany model Anthropic Opus/Sonnet ma `params.context1m: true`.
- Bieżące poświadczenie Anthropic nie kwalifikuje się do użycia długiego kontekstu.
- Żądania nie powiodą się tylko w długich sesjach/uruchomieniach modelu, które wymagają ścieżki beta 1M.
- Żądania zawodzą tylko w długich sesjach/uruchomieniach modelu, które potrzebują ścieżki beta 1M.
Opcje naprawy:
@ -95,7 +95,7 @@ Opcje naprawy:
Użyj poświadczenia Anthropic kwalifikującego się do żądań długiego kontekstu albo przełącz się na klucz API Anthropic.
</Step>
<Step title="Configure fallback models">
Skonfiguruj modele awaryjne, aby uruchomienia były kontynuowane, gdy żądania długiego kontekstu Anthropic zostaną odrzucone.
Skonfiguruj modele zapasowe, aby uruchomienia były kontynuowane, gdy żądania długiego kontekstu Anthropic zostaną odrzucone.
</Step>
</Steps>
@ -103,15 +103,15 @@ Powiązane:
- [Anthropic](/pl/providers/anthropic)
- [Użycie tokenów i koszty](/pl/reference/token-use)
- [Dlaczego widzę HTTP 429 z Anthropic?](/pl/help/faq-first-run#why-am-i-seeing-http-429-ratelimiterror-from-anthropic)
- [Dlaczego widzę HTTP 429 od Anthropic?](/pl/help/faq-first-run#why-am-i-seeing-http-429-ratelimiterror-from-anthropic)
## Lokalny backend zgodny z OpenAI przechodzi bezpośrednie sondy, ale uruchomienia agentów kończą się niepowodzeniem
## Lokalny backend zgodny z OpenAI przechodzi bezpośrednie sondy, ale uruchomienia agenta zawodzą
Użyj tego, gdy:
- `curl ... /v1/models` działa
- małe bezpośrednie wywołania `/v1/chat/completions` działają
- uruchomienia modeli OpenClaw nie powiodą się tylko w zwykłych turach agenta
- uruchomienia modeli OpenClaw zawodzą tylko podczas normalnych tur agenta
```bash
curl http://127.0.0.1:1234/v1/models
@ -124,27 +124,27 @@ openclaw logs --follow
Szukaj:
- bezpośrednie małe wywołania się udają, ale uruchomienia OpenClaw zawodzą tylko przy większych promptach
- bezpośrednie małe wywołania kończą się powodzeniem, ale uruchomienia OpenClaw zawodzą tylko przy większych promptach
- błędy `model_not_found` lub 404, mimo że bezpośrednie `/v1/chat/completions`
działa z tym samym prostym identyfikatorem modelu
- błędy backendu dotyczące `messages[].content`, który oczekuje ciągu znaków
- błędy backendu dotyczące `messages[].content`, które oczekuje ciągu znaków
- okresowe ostrzeżenia `incomplete turn detected ... stopReason=stop payloads=0` z lokalnym backendem zgodnym z OpenAI
- awarie backendu pojawiające się tylko przy większej liczbie tokenów promptu lub pełnych promptach środowiska uruchomieniowego agenta
- awarie backendu, które pojawiają się tylko przy większej liczbie tokenów promptu lub pełnych promptach środowiska wykonawczego agenta
<AccordionGroup>
<Accordion title="Common signatures">
- `model_not_found` z lokalnym serwerem w stylu MLX/vLLM → sprawdź, czy `baseUrl` zawiera `/v1`, `api` to `"openai-completions"` dla backendów `/v1/chat/completions`, a `models.providers.<provider>.models[].id` jest prostym lokalnym identyfikatorem dostawcy. Wybierz go raz z prefiksem dostawcy, na przykład `mlx/mlx-community/Qwen3-30B-A3B-6bit`; pozostaw wpis katalogu jako `mlx-community/Qwen3-30B-A3B-6bit`.
- `messages[...].content: invalid type: sequence, expected a string` → backend odrzuca strukturalne części treści Chat Completions. Naprawa: ustaw `models.providers.<provider>.models[].compat.requiresStringContent: true`.
- `incomplete turn detected ... stopReason=stop payloads=0` → backend ukończył żądanie Chat Completions, ale nie zwrócił widocznego dla użytkownika tekstu asystenta dla tej tury. OpenClaw ponawia bezpieczne do odtworzenia puste tury zgodne z OpenAI jeden raz; trwałe niepowodzenia zwykle oznaczają, że backend emituje pustą/nietekstową treść albo tłumi tekst odpowiedzi końcowej.
- bezpośrednie małe żądania się udają, ale uruchomienia agentów OpenClaw zawodzą awariami backendu/modelu (na przykład Gemma w niektórych kompilacjach `inferrs`) → transport OpenClaw prawdopodobnie jest już poprawny; backend zawodzi na większym kształcie promptu środowiska uruchomieniowego agenta.
- niepowodzenia zmniejszają się po wyłączeniu narzędzi, ale nie znikają → schematy narzędzi były częścią presji, ale pozostały problem nadal dotyczy pojemności modelu/serwera upstream albo błędu backendu.
- `model_not_found` z lokalnym serwerem w stylu MLX/vLLM → sprawdź, czy `baseUrl` zawiera `/v1`, `api` ma wartość `"openai-completions"` dla backendów `/v1/chat/completions`, a `models.providers.<provider>.models[].id` jest prostym lokalnym identyfikatorem dostawcy. Wybierz go raz z prefiksem dostawcy, na przykład `mlx/mlx-community/Qwen3-30B-A3B-6bit`; wpis w katalogu pozostaw jako `mlx-community/Qwen3-30B-A3B-6bit`.
- `messages[...].content: invalid type: sequence, expected a string` → backend odrzuca ustrukturyzowane części treści Chat Completions. Naprawa: ustaw `models.providers.<provider>.models[].compat.requiresStringContent: true`.
- `incomplete turn detected ... stopReason=stop payloads=0` → backend ukończył żądanie Chat Completions, ale nie zwrócił widocznego dla użytkownika tekstu asystenta dla tej tury. OpenClaw ponawia puste tury zgodne z OpenAI, które można bezpiecznie odtworzyć, jeden raz; trwałe awarie zwykle oznaczają, że backend emituje pustą/nietekstową treść albo tłumi tekst końcowej odpowiedzi.
- bezpośrednie małe żądania kończą się powodzeniem, ale uruchomienia agenta OpenClaw zawodzą z awariami backendu/modelu (na przykład Gemma w niektórych buildach `inferrs`) → transport OpenClaw prawdopodobnie jest już poprawny; backend zawodzi na większym kształcie promptu środowiska wykonawczego agenta.
- awarie zmniejszają się po wyłączeniu narzędzi, ale nie znikają → schematy narzędzi były częścią presji, ale pozostały problem nadal dotyczy pojemności modelu/serwera upstream albo błędu backendu.
</Accordion>
<Accordion title="Fix options">
1. Ustaw `compat.requiresStringContent: true` dla backendów Chat Completions obsługujących tylko ciągi znaków.
2. Ustaw `compat.supportsTools: false` dla modeli/backendów, które nie potrafią niezawodnie obsłużyć powierzchni schematu narzędzi OpenClaw.
3. Ogranicz presję promptu tam, gdzie to możliwe: mniejszy bootstrap przestrzeni roboczej, krótsza historia sesji, lżejszy model lokalny albo backend z silniejszą obsługą długiego kontekstu.
4. Jeśli małe bezpośrednie żądania nadal przechodzą, a tury agentów OpenClaw wciąż powodują awarie w backendzie, traktuj to jako ograniczenie serwera/modelu upstream i zgłoś tam reprodukcję z zaakceptowanym kształtem payloadu.
3. Zmniejsz presję promptu tam, gdzie to możliwe: mniejszy bootstrap workspace, krótsza historia sesji, lżejszy model lokalny albo backend z mocniejszą obsługą długiego kontekstu.
4. Jeśli małe bezpośrednie żądania nadal przechodzą, a tury agenta OpenClaw wciąż powodują awarię wewnątrz backendu, potraktuj to jako ograniczenie serwera/modelu upstream i zgłoś tam reprodukcję z zaakceptowanym kształtem payloadu.
</Accordion>
</AccordionGroup>
@ -156,7 +156,7 @@ Powiązane:
## Brak odpowiedzi
Jeśli kanały działają, ale nic nie odpowiada, przed ponownym łączeniem czegokolwiek sprawdź routing i politykę.
Jeśli kanały działają, ale nic nie odpowiada, sprawdź routing i zasady, zanim cokolwiek ponownie połączysz.
```bash
openclaw status
@ -168,15 +168,15 @@ openclaw logs --follow
Szukaj:
- Parowanie oczekujące dla nadawców DM.
- Bramkowanie wzmianek grupowych (`requireMention`, `mentionPatterns`).
- Niezgodności list dozwolonych kanałów/grup.
- Oczekujące parowanie dla nadawców DM.
- Bramka wzmianki w grupie (`requireMention`, `mentionPatterns`).
- Niezgodności allowlist kanału/grupy.
Typowe sygnatury:
- `drop guild message (mention required` → wiadomość grupowa zignorowana do czasu wzmianki.
- `drop guild message (mention required` → wiadomość grupowa ignorowana do czasu wzmianki.
- `pairing request` → nadawca wymaga zatwierdzenia.
- `blocked` / `allowlist` → nadawca/kanał został odfiltrowany przez politykę.
- `blocked` / `allowlist` → nadawca/kanał został odfiltrowany przez zasady.
Powiązane:
@ -199,42 +199,42 @@ openclaw gateway status --json
Szukaj:
- Poprawny URL sondy i URL dashboardu.
- Niezgodność trybu uwierzytelniania/tokenu między klientem a Gateway.
- Niezgodność trybu/tokena uwierzytelniania między klientem a gateway.
- Użycie HTTP tam, gdzie wymagana jest tożsamość urządzenia.
<AccordionGroup>
<Accordion title="Connect / auth signatures">
- `device identity required` → niezabezpieczony kontekst lub brak uwierzytelniania urządzenia.
- `origin not allowed` → `Origin` przeglądarki nie znajduje się w `gateway.controlUi.allowedOrigins` (albo łączysz się z pochodzenia przeglądarki spoza local loopback bez jawnej listy dozwolonych).
- `origin not allowed` → przeglądarkowy `Origin` nie znajduje się w `gateway.controlUi.allowedOrigins` (albo łączysz się z pochodzenia przeglądarki spoza loopback bez jawnej allowlist).
- `device nonce required` / `device nonce mismatch` → klient nie kończy przepływu uwierzytelniania urządzenia opartego na wyzwaniu (`connect.challenge` + `device.nonce`).
- `device signature invalid` / `device signature expired` → klient podpisał niewłaściwy payload (albo nieaktualny znacznik czasu) dla bieżącego handshake’u.
- `AUTH_TOKEN_MISMATCH` z `canRetryWithDeviceToken=true` → klient może wykonać jedną zaufaną ponowną próbę z buforowanym tokenem urządzenia.
- Ta ponowna próba z tokenem z pamięci podręcznej ponownie używa buforowanego zestawu zakresów zapisanego ze sparowanym tokenem urządzenia. Wywołujący z jawnym `deviceToken` / jawnymi `scopes` zachowują zamiast tego żądany zestaw zakresów.
- Poza tą ścieżką ponowienia priorytet uwierzytelniania połączenia jest następujący: najpierw jawny współdzielony token/hasło, potem jawny `deviceToken`, potem zapisany token urządzenia, a potem token bootstrapu.
- W asynchronicznej ścieżce interfejsu sterowania Tailscale Serve nieudane próby dla tego samego `{scope, ip}` są serializowane, zanim limiter zapisze niepowodzenie. Dwie złe równoczesne ponowne próby od tego samego klienta mogą więc zwrócić `retry later` przy drugiej próbie zamiast dwóch zwykłych niezgodności.
- `too many failed authentication attempts (retry later)` z klienta przeglądarkowego pochodzącego z local loopback → powtarzające się niepowodzenia z tego samego znormalizowanego `Origin` są tymczasowo blokowane; inne pochodzenie localhost używa osobnego koszyka.
- powtarzające się `unauthorized` po tej ponownej próbie → rozjazd tokenu współdzielonego/tokenu urządzenia; odśwież konfigurację tokenów i w razie potrzeby ponownie zatwierdź/obróć token urządzenia.
- `gateway connect failed:` → niewłaściwy cel hosta/portu/URL.
- `device signature invalid` / `device signature expired` → klient podpisał niewłaściwy payload (albo nieaktualny znacznik czasu) dla bieżącego handshake.
- `AUTH_TOKEN_MISMATCH` z `canRetryWithDeviceToken=true` → klient może wykonać jedną zaufaną próbę ponowienia z buforowanym tokenem urządzenia.
- Ta ponowna próba z buforowanym tokenem ponownie używa buforowanego zestawu zakresów zapisanego ze sparowanym tokenem urządzenia. Wywołujący z jawnym `deviceToken` / jawnymi `scopes` zachowują zamiast tego swój żądany zestaw zakresów.
- Poza tą ścieżką ponawiania priorytet uwierzytelniania przy połączeniu to najpierw jawny współdzielony token/hasło, następnie jawny `deviceToken`, potem zapisany token urządzenia, a na końcu token bootstrap.
- Na asynchronicznej ścieżce Tailscale Serve Control UI nieudane próby dla tego samego `{scope, ip}` są serializowane, zanim limiter zarejestruje awarię. Dwie błędne równoczesne próby ponowienia od tego samego klienta mogą więc zwrócić `retry later` przy drugiej próbie zamiast dwóch zwykłych niezgodności.
- `too many failed authentication attempts (retry later)` od klienta przeglądarkowego z origin loopback → powtarzające się awarie z tego samego znormalizowanego `Origin` są tymczasowo blokowane; inny origin localhost używa osobnego koszyka.
- powtarzające się `unauthorized` po tej ponownej próbie → rozjazd tokenu współdzielonego/tokenu urządzenia; odśwież konfigurację tokena i w razie potrzeby ponownie zatwierdź/obróć token urządzenia.
- `gateway connect failed:` → nieprawidłowy host/port/docelowy URL.
</Accordion>
</AccordionGroup>
### Szybka mapa kodów szczegółów uwierzytelniania
Użyj `error.details.code` z nieudanego odpowiedzi `connect`, aby wybrać następną akcję:
Użyj `error.details.code` z nieudanego response `connect`, aby wybrać następne działanie:
| Kod szczegółowy | Znaczenie | Zalecane działanie |
| ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `AUTH_TOKEN_MISSING` | Klient nie wysłał wymaganego współdzielonego tokena. | Wklej/ustaw token w kliencie i spróbuj ponownie. Dla ścieżek panelu: `openclaw config get gateway.auth.token`, a następnie wklej go w ustawieniach Control UI. |
| `AUTH_TOKEN_MISMATCH` | Współdzielony token nie pasował do tokena uwierzytelniania gateway. | Jeśli `canRetryWithDeviceToken=true`, zezwól na jedną zaufaną próbę ponowienia. Próby ponowienia z tokenem z pamięci podręcznej ponownie używają zapisanych zatwierdzonych zakresów; wywołujący z jawnymi `deviceToken` / `scopes` zachowują żądane zakresy. Jeśli nadal się nie udaje, uruchom [listę kontrolną odzyskiwania dryfu tokena](/pl/cli/devices#token-drift-recovery-checklist). |
| `AUTH_DEVICE_TOKEN_MISMATCH` | Token zapisany w pamięci podręcznej dla urządzenia jest nieaktualny lub cofnięty. | Obróć/ponownie zatwierdź token urządzenia za pomocą [CLI urządzeń](/pl/cli/devices), a następnie połącz się ponownie. |
| `PAIRING_REQUIRED` | Tożsamość urządzenia wymaga zatwierdzenia. Sprawdź `error.details.reason` pod kątem `not-paired`, `scope-upgrade`, `role-upgrade` lub `metadata-upgrade` i użyj `requestId` / `remediationHint`, gdy są dostępne. | Zatwierdź oczekujące żądanie: `openclaw devices list`, a następnie `openclaw devices approve <requestId>`. Uaktualnienia zakresu/roli używają tego samego przepływu po sprawdzeniu żądanego dostępu. |
| Kod szczegółu | Znaczenie | Zalecane działanie |
| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `AUTH_TOKEN_MISSING` | Klient nie wysłał wymaganego tokenu współdzielonego. | Wklej/ustaw token w kliencie i spróbuj ponownie. Dla ścieżek dashboardu: `openclaw config get gateway.auth.token`, a następnie wklej go w ustawieniach Control UI. |
| `AUTH_TOKEN_MISMATCH` | Token współdzielony nie pasował do tokenu uwierzytelniania Gateway. | Jeśli `canRetryWithDeviceToken=true`, zezwól na jedną zaufaną próbę ponowienia. Ponowienia z tokenem z pamięci podręcznej używają zapisanych zatwierdzonych zakresów; wywołujący z jawnym `deviceToken` / `scopes` zachowują żądane zakresy. Jeśli nadal się nie udaje, uruchom [listę kontrolną odzyskiwania dryfu tokenu](/pl/cli/devices#token-drift-recovery-checklist). |
| `AUTH_DEVICE_TOKEN_MISMATCH` | Token per urządzenie z pamięci podręcznej jest nieaktualny lub cofnięty. | Obróć/ponownie zatwierdź token urządzenia za pomocą [devices CLI](/pl/cli/devices), a następnie połącz ponownie. |
| `PAIRING_REQUIRED` | Tożsamość urządzenia wymaga zatwierdzenia. Sprawdź `error.details.reason` pod kątem `not-paired`, `scope-upgrade`, `role-upgrade` lub `metadata-upgrade` i użyj `requestId` / `remediationHint`, gdy są obecne. | Zatwierdź oczekujące żądanie: `openclaw devices list`, a następnie `openclaw devices approve <requestId>`. Ulepszenia zakresu/roli używają tego samego przepływu po przejrzeniu żądanego dostępu. |
<Note>
Bezpośrednie wywołania RPC backendu przez loopback, uwierzytelnione współdzielonym tokenem/hasłem gateway, nie powinny zależeć od bazowego zakresu sparowanego urządzenia CLI. Jeśli podagenci lub inne wywołania wewnętrzne nadal kończą się niepowodzeniem z `scope-upgrade`, sprawdź, czy wywołujący używa `client.id: "gateway-client"` i `client.mode: "backend"` oraz czy nie wymusza jawnego `deviceIdentity` ani tokena urządzenia.
Bezpośrednie backendowe RPC przez loopback uwierzytelniane współdzielonym tokenem/hasłem Gateway nie powinny zależeć od bazowego zakresu sparowanego urządzenia z CLI. Jeśli subagenci lub inne wywołania wewnętrzne nadal kończą się niepowodzeniem z `scope-upgrade`, sprawdź, czy wywołujący używa `client.id: "gateway-client"` oraz `client.mode: "backend"` i nie wymusza jawnego `deviceIdentity` ani tokenu urządzenia.
</Note>
Sprawdzenie migracji uwierzytelniania urządzeń v2:
Kontrola migracji uwierzytelniania urządzeń v2:
```bash
openclaw --version
@ -246,7 +246,7 @@ Jeśli logi pokazują błędy nonce/podpisu, zaktualizuj łączącego się klien
<Steps>
<Step title="Poczekaj na connect.challenge">
Klient czeka na `connect.challenge` wystawione przez gateway.
Klient czeka na `connect.challenge` wystawione przez Gateway.
</Step>
<Step title="Podpisz payload">
Klient podpisuje payload powiązany z wyzwaniem.
@ -256,14 +256,14 @@ Jeśli logi pokazują błędy nonce/podpisu, zaktualizuj łączącego się klien
</Step>
</Steps>
Jeśli `openclaw devices rotate` / `revoke` / `remove` zostaje nieoczekiwanie odrzucone:
Jeśli `openclaw devices rotate` / `revoke` / `remove` jest niespodziewanie odrzucane:
- sesje tokenów sparowanych urządzeń mogą zarządzać tylko **własnym** urządzeniem, chyba że wywołujący ma także `operator.admin`
- sesje tokenu sparowanego urządzenia mogą zarządzać tylko **własnym** urządzeniem, chyba że wywołujący ma też `operator.admin`
- `openclaw devices rotate --scope ...` może żądać tylko zakresów operatora, które sesja wywołującego już posiada
Powiązane:
- [Konfiguracja](/pl/gateway/configuration) (tryby uwierzytelniania gateway)
- [Konfiguracja](/pl/gateway/configuration) (tryby uwierzytelniania Gateway)
- [Control UI](/pl/web/control-ui)
- [Urządzenia](/pl/cli/devices)
- [Dostęp zdalny](/pl/gateway/remote)
@ -283,33 +283,33 @@ openclaw gateway status --deep # also scan system-level services
Szukaj:
- `Runtime: stopped` z podpowiedziami kodu zakończenia.
- `Runtime: stopped` ze wskazówkami kodu zakończenia.
- Niezgodność konfiguracji usługi (`Config (cli)` kontra `Config (service)`).
- Konflikty portu/listenera.
- Dodatkowe instalacje launchd/systemd/schtasks, gdy użyto `--deep`.
- Podpowiedzi czyszczenia `Other gateway-like services detected (best effort)`.
- Wskazówki czyszczenia `Other gateway-like services detected (best effort)`.
<AccordionGroup>
<Accordion title="Typowe sygnatury">
- `Gateway start blocked: set gateway.mode=local` lub `existing config is missing gateway.mode` → lokalny tryb gateway nie jest włączony albo plik konfiguracji został nadpisany i utracił `gateway.mode`. Naprawa: ustaw `gateway.mode="local"` w konfiguracji albo ponownie uruchom `openclaw onboard --mode local` / `openclaw setup`, aby ponownie oznaczyć oczekiwaną konfigurację trybu lokalnego. Jeśli uruchamiasz OpenClaw przez Podman, domyślna ścieżka konfiguracji to `~/.openclaw/openclaw.json`.
- `refusing to bind gateway ... without auth` → powiązanie inne niż loopback bez prawidłowej ścieżki uwierzytelniania gateway (token/hasło albo trusted-proxy, gdy skonfigurowane).
- `Gateway start blocked: set gateway.mode=local` lub `existing config is missing gateway.mode` → lokalny tryb Gateway nie jest włączony albo plik konfiguracji został nadpisany i utracił `gateway.mode`. Poprawka: ustaw `gateway.mode="local"` w konfiguracji albo ponownie uruchom `openclaw onboard --mode local` / `openclaw setup`, aby odtworzyć oczekiwaną konfigurację trybu lokalnego. Jeśli uruchamiasz OpenClaw przez Podman, domyślna ścieżka konfiguracji to `~/.openclaw/openclaw.json`.
- `refusing to bind gateway ... without auth` → wiązanie inne niż loopback bez prawidłowej ścieżki uwierzytelniania Gateway (token/hasło albo zaufane proxy, gdy skonfigurowane).
- `another gateway instance is already listening` / `EADDRINUSE` → konflikt portu.
- `Other gateway-like services detected (best effort)` → istnieją nieaktualne lub równoległe jednostki launchd/systemd/schtasks. Większość konfiguracji powinna utrzymywać jeden gateway na maszynę; jeśli potrzebujesz więcej niż jednego, odizoluj porty oraz konfigurację/stan/przestrzeń roboczą. Zobacz [/gateway#multiple-gateways-same-host](/pl/gateway#multiple-gateways-same-host).
- `System-level OpenClaw gateway service detected` z doctor → istnieje systemowa jednostka systemd, podczas gdy brakuje usługi na poziomie użytkownika. Usuń lub wyłącz duplikat, zanim pozwolisz doctor zainstalować usługę użytkownika, albo ustaw `OPENCLAW_SERVICE_REPAIR_POLICY=external`, jeśli jednostka systemowa jest zamierzonym nadzorcą.
- `Gateway service port does not match current gateway config` → zainstalowany nadzorca nadal przypina stary `--port`. Uruchom `openclaw doctor --fix` albo `openclaw gateway install --force`, a następnie zrestartuj usługę gateway.
- `Other gateway-like services detected (best effort)` → istnieją przestarzałe lub równoległe jednostki launchd/systemd/schtasks. Większość konfiguracji powinna utrzymywać jeden Gateway na maszynę; jeśli potrzebujesz więcej niż jednego, odizoluj porty + konfigurację/stan/przestrzeń roboczą. Zobacz [/gateway#multiple-gateways-same-host](/pl/gateway#multiple-gateways-same-host).
- `System-level OpenClaw gateway service detected` z doctor → istnieje jednostka systemowa systemd, podczas gdy brakuje usługi na poziomie użytkownika. Usuń lub wyłącz duplikat, zanim pozwolisz doctor zainstalować usługę użytkownika, albo ustaw `OPENCLAW_SERVICE_REPAIR_POLICY=external`, jeśli jednostka systemowa jest zamierzonym nadzorcą.
- `Gateway service port does not match current gateway config` → zainstalowany nadzorca nadal przypina stary `--port`. Uruchom `openclaw doctor --fix` albo `openclaw gateway install --force`, a następnie zrestartuj usługę Gateway.
</Accordion>
</AccordionGroup>
Powiązane:
- [Wykonywanie w tle i narzędzie procesu](/pl/gateway/background-process)
- [Exec w tle i narzędzie procesu](/pl/gateway/background-process)
- [Konfiguracja](/pl/gateway/configuration)
- [Doctor](/pl/gateway/doctor)
## Gateway przywrócił ostatnią znaną dobrą konfigurację
Użyj tego, gdy Gateway uruchamia się, ale logi mówią, że przywrócił `openclaw.json`.
Użyj tego, gdy Gateway się uruchamia, ale logi mówią, że przywrócił `openclaw.json`.
```bash
openclaw logs --follow
@ -323,16 +323,16 @@ Szukaj:
- `Config auto-restored from last-known-good`
- `gateway: invalid config was restored from last-known-good backup`
- `config reload restored last-known-good config after invalid-config`
- Plik `openclaw.json.clobbered.*` ze znacznikiem czasu obok aktywnej konfiguracji
- Zdarzenie systemowe głównego agenta zaczynające się od `Config recovery warning`
- Pliku `openclaw.json.clobbered.*` ze znacznikiem czasu obok aktywnej konfiguracji
- Zdarzenia systemowego głównego agenta, które zaczyna się od `Config recovery warning`
<AccordionGroup>
<Accordion title="Co się stało">
- Odrzucona konfiguracja nie przeszła walidacji podczas uruchamiania lub hot reload.
- Odrzucona konfiguracja nie przeszła walidacji podczas uruchamiania lub gorącego przeładowania.
- OpenClaw zachował odrzucony payload jako `.clobbered.*`.
- Aktywna konfiguracja została przywrócona z ostatniej zweryfikowanej kopii last-known-good.
- Następna tura głównego agenta otrzymuje ostrzeżenie, aby nie przepisywać odrzuconej konfiguracji bez sprawdzenia.
- Jeśli wszystkie problemy walidacji znajdowały się pod `plugins.entries.<id>...`, OpenClaw nie przywróciłby całego pliku. Awarie lokalne dla Plugin pozostają głośne, a niepowiązane ustawienia użytkownika pozostają w aktywnej konfiguracji.
- Aktywna konfiguracja została przywrócona z ostatniej zwalidowanej kopii last-known-good.
- Następny przebieg głównego agenta otrzymuje ostrzeżenie, aby nie przepisywać odrzuconej konfiguracji na ślepo.
- Jeśli wszystkie problemy walidacji znajdowały się pod `plugins.entries.<id>...`, OpenClaw nie przywróciłby całego pliku. Lokalne awarie Plugin pozostają widoczne, podczas gdy niezwiązane ustawienia użytkownika zostają w aktywnej konfiguracji.
</Accordion>
<Accordion title="Sprawdź i napraw">
@ -345,31 +345,32 @@ Szukaj:
```
</Accordion>
<Accordion title="Typowe sygnatury">
- `.clobbered.*` istnieje → zewnętrzna bezpośrednia edycja lub odczyt podczas uruchamiania zostały przywrócone.
- `.rejected.*` istnieje → zapis konfiguracji wykonywany przez OpenClaw nie przeszedł schematu lub kontroli nadpisania przed zatwierdzeniem.
- `Config write rejected:` → zapis próbował usunąć wymagany kształt, gwałtownie zmniejszyć plik lub utrwalić nieprawidłową konfigurację.
- `missing-meta-vs-last-good`, `gateway-mode-missing-vs-last-good` lub `size-drop-vs-last-good:*` → uruchamianie potraktowało bieżący plik jako nadpisany, ponieważ utracił pola lub rozmiar w porównaniu z kopią last-known-good.
- Istnieje `.clobbered.*` → zewnętrzna bezpośrednia edycja lub odczyt przy uruchamianiu zostały przywrócone.
- Istnieje `.rejected.*` → zapis konfiguracji należący do OpenClaw nie przeszedł schematu lub kontroli nadpisania przed zatwierdzeniem.
- `Config write rejected:` → zapis próbował usunąć wymaganą strukturę, gwałtownie zmniejszyć plik lub utrwalić nieprawidłową konfigurację.
- `Rejected validation details:` → log odzyskiwania lub powiadomienie głównego agenta zawiera ścieżkę schematu, która spowodowała przywrócenie, taką jak `agents.defaults.execution` lub `gateway.auth.password.source`.
- `missing-meta-vs-last-good`, `gateway-mode-missing-vs-last-good` lub `size-drop-vs-last-good:*` → uruchamianie potraktowało bieżący plik jako nadpisany, ponieważ utracił pola lub rozmiar w porównaniu z kopią zapasową last-known-good.
- `Config last-known-good promotion skipped` → kandydat zawierał zredagowane placeholdery sekretów, takie jak `***`.
</Accordion>
<Accordion title="Opcje naprawy">
1. Zachowaj przywróconą aktywną konfigurację, jeśli jest poprawna.
2. Skopiuj tylko zamierzone klucze z `.clobbered.*` lub `.rejected.*`, a następnie zastosuj je za pomocą `openclaw config set` lub `config.patch`.
3. Uruchom `openclaw config validate` przed ponownym uruchomieniem.
4. Jeśli edytujesz ręcznie, zachowaj pełną konfigurację JSON5, nie tylko częściowy obiekt, który chcesz zmienić.
3. Uruchom `openclaw config validate` przed restartem.
4. Jeśli edytujesz ręcznie, zachowaj pełną konfigurację JSON5, a nie tylko częściowy obiekt, który chcesz zmienić.
</Accordion>
</AccordionGroup>
Powiązane:
- [Config](/pl/cli/config)
- [Konfiguracja: hot reload](/pl/gateway/configuration#config-hot-reload)
- [Konfiguracja: gorące przeładowanie](/pl/gateway/configuration#config-hot-reload)
- [Konfiguracja: ścisła walidacja](/pl/gateway/configuration#strict-validation)
- [Doctor](/pl/gateway/doctor)
## Ostrzeżenia sondy Gateway
Użyj tego, gdy `openclaw gateway probe` dociera do czegoś, ale nadal drukuje blok ostrzeżeń.
Użyj tego, gdy `openclaw gateway probe` dociera do czegoś, ale nadal wypisuje blok ostrzeżenia.
```bash
openclaw gateway probe
@ -380,26 +381,26 @@ openclaw gateway probe --ssh user@gateway-host
Szukaj:
- `warnings[].code` i `primaryTargetId` w wyjściu JSON.
- Czy ostrzeżenie dotyczy awaryjnego SSH, wielu gateway, brakujących zakresów czy nierozwiązanych odwołań uwierzytelniania.
- Czy ostrzeżenie dotyczy awaryjnego SSH, wielu Gateway, brakujących zakresów czy nierozwiązanych odwołań uwierzytelniania.
Typowe sygnatury:
- `SSH tunnel failed to start; falling back to direct probes.` → konfiguracja SSH nie powiodła się, ale polecenie nadal spróbowało bezpośrednich skonfigurowanych/celów loopback.
- `multiple reachable gateways detected` → odpowiedział więcej niż jeden cel. Zwykle oznacza to zamierzoną konfigurację wielu gateway albo nieaktualne/zduplikowane listenery.
- `multiple reachable gateways detected` → odpowiedział więcej niż jeden cel. Zwykle oznacza to zamierzoną konfigurację z wieloma Gateway albo przestarzałe/zduplikowane listenery.
- `Read-probe diagnostics are limited by gateway scopes (missing operator.read)` → połączenie zadziałało, ale szczegółowe RPC jest ograniczone zakresem; sparuj tożsamość urządzenia albo użyj poświadczeń z `operator.read`.
- `Gateway accepted the WebSocket connection, but follow-up read diagnostics failed` → połączenie zadziałało, ale pełny zestaw diagnostycznych RPC przekroczył limit czasu lub nie powiódł się. Traktuj to jako osiągalny Gateway z ograniczoną diagnostyką; porównaj `connect.ok` i `connect.rpcOk` w wyjściu `--json`.
- `Capability: pairing-pending` lub `gateway closed (1008): pairing required` → gateway odpowiedział, ale ten klient nadal wymaga parowania/zatwierdzenia przed normalnym dostępem operatora.
- nierozwiązany tekst ostrzeżenia SecretRef `gateway.auth.*` / `gateway.remote.*` → materiał uwierzytelniający był niedostępny w tej ścieżce polecenia dla celu, który się nie powiódł.
- `Gateway accepted the WebSocket connection, but follow-up read diagnostics failed` → połączenie zadziałało, ale pełny zestaw diagnostycznych RPC przekroczył limit czasu lub zakończył się niepowodzeniem. Traktuj to jako osiągalny Gateway z ograniczoną diagnostyką; porównaj `connect.ok` i `connect.rpcOk` w wyjściu `--json`.
- `Capability: pairing-pending` lub `gateway closed (1008): pairing required` → Gateway odpowiedział, ale ten klient nadal wymaga parowania/zatwierdzenia przed normalnym dostępem operatora.
- nierozwiązany tekst ostrzeżenia SecretRef `gateway.auth.*` / `gateway.remote.*` → materiał uwierzytelniania był niedostępny w tej ścieżce polecenia dla nieudanego celu.
Powiązane:
- [Gateway](/pl/cli/gateway)
- [Wiele gateway na tym samym hoście](/pl/gateway#multiple-gateways-same-host)
- [Wiele Gateway na tym samym hoście](/pl/gateway#multiple-gateways-same-host)
- [Dostęp zdalny](/pl/gateway/remote)
## Kanał połączony, wiadomości nie przepływają
Jeśli stan kanału jest połączony, ale przepływ wiadomości nie działa, skup się na zasadach, uprawnieniach i regułach dostarczania właściwych dla kanału.
Jeśli stan kanału to połączony, ale przepływ wiadomości nie działa, skup się na polityce, uprawnieniach i regułach dostarczania specyficznych dla kanału.
```bash
openclaw channels status --probe
@ -411,14 +412,14 @@ openclaw config get channels
Szukaj:
- Zasada DM (`pairing`, `allowlist`, `open`, `disabled`).
- Zasady wiadomości prywatnych (`pairing`, `allowlist`, `open`, `disabled`).
- Lista dozwolonych grup i wymagania dotyczące wzmianki.
- Brakujące uprawnienia/zakresy API kanału.
Typowe sygnatury:
- `mention required` → komunikat zignorowany przez zasady wzmiankowania w grupie.
- `pairing` / ślady oczekiwania na zatwierdzenie → nadawca nie jest zatwierdzony.
- `mention required` → wiadomość zignorowana przez zasady wzmianek w grupie.
- `pairing` / ślady oczekującego zatwierdzenia → nadawca nie jest zatwierdzony.
- `missing_scope`, `not_in_channel`, `Forbidden`, `401/403` → problem z uwierzytelnianiem/uprawnieniami kanału.
Powiązane:
@ -430,7 +431,7 @@ Powiązane:
## Dostarczanie Cron i Heartbeat
Jeśli cron lub heartbeat nie uruchomił się albo nie dostarczył komunikatu, najpierw sprawdź stan harmonogramu, a następnie cel dostarczenia.
Jeśli Cron lub Heartbeat nie uruchomił się albo nie dostarczył wiadomości, najpierw sprawdź stan harmonogramu, a potem cel dostarczania.
```bash
openclaw cron status
@ -440,21 +441,21 @@ openclaw system heartbeat last
openclaw logs --follow
```
Sprawdź:
Szukaj:
- Cron jest włączony i istnieje następne wybudzenie.
- Włączony Cron i obecne następne wybudzenie.
- Status historii uruchomień zadania (`ok`, `skipped`, `error`).
- Powody pominięcia Heartbeat (`quiet-hours`, `requests-in-flight`, `cron-in-progress`, `lanes-busy`, `alerts-disabled`, `empty-heartbeat-file`, `no-tasks-due`).
<AccordionGroup>
<Accordion title="Common signatures">
- `cron: scheduler disabled; jobs will not run automatically` → cron wyłączony.
- `cron: scheduler disabled; jobs will not run automatically` → Cron wyłączony.
- `cron: timer tick failed` → takt harmonogramu nie powiódł się; sprawdź błędy plików/logów/środowiska uruchomieniowego.
- `heartbeat skipped` z `reason=quiet-hours` → poza oknem aktywnych godzin.
- `heartbeat skipped` z `reason=empty-heartbeat-file` → `HEARTBEAT.md` istnieje, ale zawiera tylko puste wiersze / nagłówki markdown, więc OpenClaw pomija wywołanie modelu.
- `heartbeat skipped` z `reason=quiet-hours` → poza oknem godzin aktywności.
- `heartbeat skipped` z `reason=empty-heartbeat-file` → plik `HEARTBEAT.md` istnieje, ale zawiera tylko puste wiersze / nagłówki Markdown, więc OpenClaw pomija wywołanie modelu.
- `heartbeat skipped` z `reason=no-tasks-due` → `HEARTBEAT.md` zawiera blok `tasks:`, ale żadne zadania nie są należne w tym takcie.
- `heartbeat: unknown accountId` → nieprawidłowy identyfikator konta dla celu dostarczenia Heartbeat.
- `heartbeat skipped` z `reason=dm-blocked` → cel Heartbeat został rozpoznany jako miejsce docelowe typu DM, gdy `agents.defaults.heartbeat.directPolicy` (lub nadpisanie dla agenta) ma wartość `block`.
- `heartbeat: unknown accountId` → nieprawidłowy identyfikator konta dla celu dostarczania Heartbeat.
- `heartbeat skipped` z `reason=dm-blocked` → cel Heartbeat został rozpoznany jako miejsce docelowe typu DM, gdy `agents.defaults.heartbeat.directPolicy` (lub nadpisanie dla agenta) jest ustawione na `block`.
</Accordion>
</AccordionGroup>
@ -477,24 +478,24 @@ openclaw logs --follow
openclaw status
```
Sprawdź:
Szukaj:
- Node jest online z oczekiwanymi możliwościami.
- Node online z oczekiwanymi możliwościami.
- Przyznane uprawnienia systemu operacyjnego do kamery/mikrofonu/lokalizacji/ekranu.
- Stan zatwierdzeń exec i listy dozwolonych.
- Zatwierdzenia wykonywania poleceń i stan listy dozwolonych.
Typowe sygnatury:
- `NODE_BACKGROUND_UNAVAILABLE` → aplikacja Node musi być na pierwszym planie.
- `*_PERMISSION_REQUIRED` / `LOCATION_PERMISSION_REQUIRED` → brak uprawnienia systemu operacyjnego.
- `SYSTEM_RUN_DENIED: approval required` → oczekuje zatwierdzenie exec.
- `*_PERMISSION_REQUIRED` / `LOCATION_PERMISSION_REQUIRED` → brakuje uprawnienia systemu operacyjnego.
- `SYSTEM_RUN_DENIED: approval required` → oczekuje zatwierdzenie wykonania polecenia.
- `SYSTEM_RUN_DENIED: allowlist miss` → polecenie zablokowane przez listę dozwolonych.
Powiązane:
- [Zatwierdzenia exec](/pl/tools/exec-approvals)
- [Zatwierdzenia wykonywania poleceń](/pl/tools/exec-approvals)
- [Rozwiązywanie problemów z Node](/pl/nodes/troubleshooting)
- [Node](/pl/nodes/index)
- [Nodes](/pl/nodes/index)
## Narzędzie przeglądarki zawodzi
@ -508,41 +509,41 @@ openclaw logs --follow
openclaw doctor
```
Sprawdź:
Szukaj:
- Czy `plugins.allow` jest ustawione i obejmuje `browser`.
- Prawidłową ścieżkę do pliku wykonywalnego przeglądarki.
- Czy `plugins.allow` jest ustawione i zawiera `browser`.
- Prawidłowa ścieżka do pliku wykonywalnego przeglądarki.
- Osiągalność profilu CDP.
- Dostępność lokalnego Chrome dla profili `existing-session` / `user`.
<AccordionGroup>
<Accordion title="Plugin / executable signatures">
- `unknown command "browser"` lub `unknown command 'browser'` → dołączony Plugin przeglądarki jest wykluczony przez `plugins.allow`.
- brak narzędzia przeglądarki / niedostępne, gdy `browser.enabled=true` → `plugins.allow` wyklucza `browser`, więc Plugin nigdy nie został załadowany.
- brakujące / niedostępne narzędzie przeglądarki przy `browser.enabled=true` → `plugins.allow` wyklucza `browser`, więc Plugin nigdy się nie załadował.
- `Failed to start Chrome CDP on port` → nie udało się uruchomić procesu przeglądarki.
- `browser.executablePath not found` → skonfigurowana ścieżka jest nieprawidłowa.
- `browser.cdpUrl must be http(s) or ws(s)` → skonfigurowany URL CDP używa nieobsługiwanego schematu, takiego jak `file:` lub `ftp:`.
- `browser.cdpUrl has invalid port` → skonfigurowany URL CDP ma błędny port lub port spoza zakresu.
- `Playwright is not available in this gateway build; '<feature>' is unsupported.` → bieżąca instalacja Gateway nie ma zależności środowiska uruchomieniowego `playwright-core` z dołączonego Plugin przeglądarki; uruchom `openclaw doctor --fix`, a następnie zrestartuj Gateway. Migawki ARIA i podstawowe zrzuty stron nadal mogą działać, ale nawigacja, migawki AI, zrzuty elementów według selektorów CSS i eksport PDF pozostają niedostępne.
- `browser.cdpUrl has invalid port` → skonfigurowany URL CDP ma nieprawidłowy port albo port spoza zakresu.
- `Playwright is not available in this gateway build; '<feature>' is unsupported.` → bieżąca instalacja Gateway nie ma zależności środowiska uruchomieniowego `playwright-core` dołączonego Pluginu przeglądarki; uruchom `openclaw doctor --fix`, a potem zrestartuj Gateway. Migawki ARIA i podstawowe zrzuty ekranu stron nadal mogą działać, ale nawigacja, migawki AI, zrzuty ekranu elementów według selektorów CSS i eksport PDF pozostają niedostępne.
</Accordion>
<Accordion title="Chrome MCP / existing-session signatures">
- `Could not find DevToolsActivePort for chrome` → Chrome MCP `existing-session` nie mógł jeszcze podłączyć się do wybranego katalogu danych przeglądarki. Otwórz stronę inspekcji przeglądarki, włącz zdalne debugowanie, pozostaw przeglądarkę otwartą, zatwierdź pierwszy monit podłączenia, a następnie spróbuj ponownie. Jeśli stan zalogowania nie jest wymagany, preferuj zarządzany profil `openclaw`.
- `No Chrome tabs found for profile="user"` → profil podłączenia Chrome MCP nie ma otwartych lokalnych kart Chrome.
- `Could not find DevToolsActivePort for chrome` → istniejąca sesja Chrome MCP nie mogła jeszcze dołączyć do wybranego katalogu danych przeglądarki. Otwórz stronę inspekcji przeglądarki, włącz zdalne debugowanie, pozostaw przeglądarkę otwartą, zatwierdź pierwszy monit dołączenia, a potem spróbuj ponownie. Jeśli stan zalogowania nie jest wymagany, wybierz zarządzany profil `openclaw`.
- `No Chrome tabs found for profile="user"` → profil dołączania Chrome MCP nie ma otwartych lokalnych kart Chrome.
- `Remote CDP for profile "<name>" is not reachable` → skonfigurowany zdalny punkt końcowy CDP nie jest osiągalny z hosta Gateway.
- `Browser attachOnly is enabled ... not reachable` lub `Browser attachOnly is enabled and CDP websocket ... is not reachable` → profil tylko do podłączenia nie ma osiągalnego celu albo punkt końcowy HTTP odpowiedział, ale WebSocket CDP nadal nie mógł zostać otwarty.
- `Browser attachOnly is enabled ... not reachable` lub `Browser attachOnly is enabled and CDP websocket ... is not reachable` → profil tylko do dołączania nie ma osiągalnego celu albo punkt końcowy HTTP odpowiedział, ale WebSocket CDP nadal nie mógł zostać otwarty.
</Accordion>
<Accordion title="Element / screenshot / upload signatures">
- `fullPage is not supported for element screenshots` → żądanie zrzutu ekranu połączyło `--full-page` z `--ref` lub `--element`.
- `element screenshots are not supported for existing-session profiles; use ref from snapshot.` → wywołania zrzutów ekranu Chrome MCP / `existing-session` muszą używać przechwycenia strony lub `--ref` z migawki, a nie CSS `--element`.
- `existing-session file uploads do not support element selectors; use ref/inputRef.` → haki przesyłania Chrome MCP wymagają referencji z migawek, a nie selektorów CSS.
- `existing-session file uploads currently support one file at a time.` → wyślij jedno przesłanie na wywołanie w profilach Chrome MCP.
- `element screenshots are not supported for existing-session profiles; use ref from snapshot.` → wywołania zrzutów ekranu Chrome MCP / `existing-session` muszą używać przechwytywania strony lub `--ref` z migawki, a nie CSS `--element`.
- `existing-session file uploads do not support element selectors; use ref/inputRef.` → haki przesyłania Chrome MCP potrzebują odwołań z migawek, a nie selektorów CSS.
- `existing-session file uploads currently support one file at a time.` → wysyłaj jedno przesłanie na wywołanie w profilach Chrome MCP.
- `existing-session dialog handling does not support timeoutMs.` → haki okien dialogowych w profilach Chrome MCP nie obsługują nadpisań limitu czasu.
- `existing-session type does not support timeoutMs overrides.` → pomiń `timeoutMs` dla `act:type` w profilach `profile="user"` / Chrome MCP `existing-session` albo użyj zarządzanego profilu przeglądarki/CDP, gdy wymagany jest niestandardowy limit czasu.
- `existing-session evaluate does not support timeoutMs overrides.` → pomiń `timeoutMs` dla `act:evaluate` w profilach `profile="user"` / Chrome MCP `existing-session` albo użyj zarządzanego profilu przeglądarki/CDP, gdy wymagany jest niestandardowy limit czasu.
- `existing-session type does not support timeoutMs overrides.` → pomiń `timeoutMs` dla `act:type` w profilach `profile="user"` / istniejących sesjach Chrome MCP albo użyj zarządzanego profilu przeglądarki/CDP, gdy wymagany jest niestandardowy limit czasu.
- `existing-session evaluate does not support timeoutMs overrides.` → pomiń `timeoutMs` dla `act:evaluate` w profilach `profile="user"` / istniejących sesjach Chrome MCP albo użyj zarządzanego profilu przeglądarki/CDP, gdy wymagany jest niestandardowy limit czasu.
- `response body is not supported for existing-session profiles yet.` → `responsebody` nadal wymaga zarządzanej przeglądarki lub surowego profilu CDP.
- nieaktualne nadpisania widoku / trybu ciemnego / ustawień regionalnych / trybu offline w profilach tylko do podłączenia lub zdalnych profilach CDP → uruchom `openclaw browser stop --browser-profile <name>`, aby zamknąć aktywną sesję sterowania i zwolnić stan emulacji Playwright/CDP bez restartowania całego Gateway.
- nieaktualne nadpisania widoku / trybu ciemnego / ustawień regionalnych / trybu offline w profilach tylko do dołączania lub zdalnych profilach CDP → uruchom `openclaw browser stop --browser-profile <name>`, aby zamknąć aktywną sesję sterowania i zwolnić stan emulacji Playwright/CDP bez restartowania całego Gateway.
</Accordion>
</AccordionGroup>
@ -550,11 +551,11 @@ Sprawdź:
Powiązane:
- [Przeglądarka (zarządzana przez OpenClaw)](/pl/tools/browser)
- [Rozwiązywanie problemów z przeglądarką](/pl/tools/browser-linux-troubleshooting)
- [Rozwiązywanie problemów z przeglądarką w systemie Linux](/pl/tools/browser-linux-troubleshooting)
## Jeśli wykonano uaktualnienie i coś nagle przestało działać
## Jeśli po aktualizacji coś nagle przestało działać
Większość awarii po uaktualnieniu wynika z rozjazdu konfiguracji albo z egzekwowania teraz bardziej rygorystycznych wartości domyślnych.
Większość awarii po aktualizacji wynika z dryfu konfiguracji albo ze ściślejszego egzekwowania wartości domyślnych.
<AccordionGroup>
<Accordion title="1. Auth and URL override behavior changed">
@ -567,13 +568,13 @@ Większość awarii po uaktualnieniu wynika z rozjazdu konfiguracji albo z egzek
Co sprawdzić:
- Jeśli `gateway.mode=remote`, wywołania CLI mogą celować w usługę zdalną, podczas gdy lokalna usługa działa prawidłowo.
- Jeśli `gateway.mode=remote`, wywołania CLI mogą trafiać do zdalnego celu, podczas gdy lokalna usługa działa prawidłowo.
- Jawne wywołania `--url` nie wracają do zapisanych poświadczeń.
Typowe sygnatury:
- `gateway connect failed:` → niewłaściwy docelowy URL.
- `unauthorized` → punkt końcowy osiągalny, ale błędne uwierzytelnianie.
- `gateway connect failed:` → nieprawidłowy docelowy URL.
- `unauthorized` → punkt końcowy osiągalny, ale uwierzytelnianie jest nieprawidłowe.
</Accordion>
<Accordion title="2. Bind and auth guardrails are stricter">
@ -587,13 +588,13 @@ Większość awarii po uaktualnieniu wynika z rozjazdu konfiguracji albo z egzek
Co sprawdzić:
- Powiązania inne niż local loopback (`lan`, `tailnet`, `custom`) wymagają prawidłowej ścieżki uwierzytelniania Gateway: uwierzytelniania współdzielonym tokenem/hasłem albo poprawnie skonfigurowanego wdrożenia `trusted-proxy` innego niż local loopback.
- Stare klucze takie jak `gateway.token` nie zastępują `gateway.auth.token`.
- Bindowania inne niż loopback (`lan`, `tailnet`, `custom`) wymagają prawidłowej ścieżki uwierzytelniania Gateway: uwierzytelniania współdzielonym tokenem/hasłem albo poprawnie skonfigurowanego wdrożenia `trusted-proxy` bez loopback.
- Stare klucze, takie jak `gateway.token`, nie zastępują `gateway.auth.token`.
Typowe sygnatury:
- `refusing to bind gateway ... without auth` → powiązanie inne niż local loopback bez prawidłowej ścieżki uwierzytelniania Gateway.
- `Connectivity probe: failed` podczas działania środowiska uruchomieniowego → Gateway działa, ale jest niedostępny z bieżącymi uwierzytelnianiem/adresem URL.
- `refusing to bind gateway ... without auth` → bindowanie inne niż loopback bez prawidłowej ścieżki uwierzytelniania Gateway.
- `Connectivity probe: failed` podczas działania środowiska uruchomieniowego → Gateway działa, ale jest niedostępny przy bieżącym uwierzytelnianiu/adresie URL.
</Accordion>
<Accordion title="3. Pairing and device identity state changed">
@ -606,7 +607,7 @@ Większość awarii po uaktualnieniu wynika z rozjazdu konfiguracji albo z egzek
Co sprawdzić:
- Oczekujące zatwierdzenia urządzeń dla panelu i Node.
- Oczekujące zatwierdzenia urządzeń dla panelu i węzłów.
- Oczekujące zatwierdzenia parowania DM po zmianach zasad lub tożsamości.
Typowe sygnatury:
@ -617,7 +618,7 @@ Większość awarii po uaktualnieniu wynika z rozjazdu konfiguracji albo z egzek
</Accordion>
</AccordionGroup>
Jeśli konfiguracja usługi i środowisko uruchomieniowe nadal są niespójne po sprawdzeniach, zainstaluj ponownie metadane usługi z tego samego profilu/katalogu stanu:
Jeśli po tych kontrolach konfiguracja usługi i środowisko uruchomieniowe nadal się nie zgadzają, zainstaluj ponownie metadane usługi z tego samego katalogu profilu/stanu:
```bash
openclaw gateway install --force
@ -627,7 +628,7 @@ openclaw gateway restart
Powiązane:
- [Uwierzytelnianie](/pl/gateway/authentication)
- [Exec w tle i narzędzie procesów](/pl/gateway/background-process)
- [Wykonywanie poleceń w tle i narzędzie procesów](/pl/gateway/background-process)
- [Parowanie zarządzane przez Gateway](/pl/gateway/pairing)
## Powiązane

733
docs/pl/help/testing.md
View File

File diff suppressed because it is too large Load Diff

106
docs/pl/install/updating.md
View File

@ -1,14 +1,14 @@
---
read_when:
- Aktualizowanie OpenClaw
- Coś przestaje działać po aktualizacji
summary: Bezpieczne aktualizowanie OpenClaw (instalacja globalna lub ze źródeł) oraz strategia wycofywania
- Coś się psuje po aktualizacji
summary: Bezpieczne aktualizowanie OpenClaw (instalacji globalnej lub ze źródeł) oraz strategia wycofania zmian
title: Aktualizacja
x-i18n:
generated_at: "2026-04-30T10:02:40Z"
generated_at: "2026-05-01T09:59:39Z"
model: gpt-5.5
provider: openai
source_hash: 17d4839002b153976e014e0eefcb44f92dcb9bb45b81bf30efb1e8e8c0f30ec3
source_hash: b6ee340af569dde3a6cf61fff26d2a0ab8c8ec882b652f41d6ac8e22ddc5fed1
source_path: install/updating.md
workflow: 16
---
@ -17,34 +17,38 @@ Dbaj o aktualność OpenClaw.
## Zalecane: `openclaw update`
Najszybszy sposób aktualizacji. Wykrywa typ instalacji (npm albo git), pobiera najnowszą wersję, uruchamia `openclaw doctor` i ponownie uruchamia Gateway.
Najszybszy sposób aktualizacji. Wykrywa typ instalacji (npm lub git), pobiera najnowszą wersję, uruchamia `openclaw doctor` i restartuje Gateway.
```bash
openclaw update
```
Aby przełączyć kanały albo wskazać konkretną wersję:
Aby przełączyć kanały lub wskazać konkretną wersję:
```bash
openclaw update --channel beta
openclaw update --channel dev
openclaw update --tag main
openclaw update --dry-run # podgląd bez stosowania zmian
openclaw update --dry-run # preview without applying
```
`--channel beta` preferuje wersję beta, ale środowisko runtime wraca do stable/latest, gdy tag beta jest brakujący albo starszy niż najnowsze wydanie stabilne. Użyj `--tag beta`, jeśli chcesz surowego tagu dist-tag npm beta dla jednorazowej aktualizacji pakietu.
`--channel beta` preferuje wersję beta, ale środowisko uruchomieniowe wraca do stable/latest, gdy
brakuje tagu beta albo jest on starszy niż najnowsze stabilne wydanie. Użyj `--tag beta`,
jeśli chcesz użyć surowego npm beta dist-tag do jednorazowej aktualizacji pakietu.
Zobacz [Kanały rozwojowe](/pl/install/development-channels), aby poznać semantykę kanałów.
Zobacz [Kanały programistyczne](/pl/install/development-channels), aby poznać semantykę kanałów.
## Przełączanie między instalacjami npm i git
Używaj kanałów, gdy chcesz zmienić typ instalacji. Aktualizator zachowuje Twój stan, konfigurację, dane uwierzytelniające i przestrzeń roboczą w `~/.openclaw`; zmienia tylko to, z której instalacji kodu OpenClaw korzystają CLI i Gateway.
Używaj kanałów, gdy chcesz zmienić typ instalacji. Aktualizator zachowuje Twój
stan, konfigurację, poświadczenia i obszar roboczy w `~/.openclaw`; zmienia tylko to,
z której instalacji kodu OpenClaw korzystają CLI i Gateway.
```bash
# instalacja pakietu npm -> edytowalny checkout git
# npm package install -> editable git checkout
openclaw update --channel dev
# checkout git -> instalacja pakietu npm
# git checkout -> npm package install
openclaw update --channel stable
```
@ -55,35 +59,48 @@ openclaw update --channel dev --dry-run
openclaw update --channel stable --dry-run
```
Kanał `dev` zapewnia checkout git, buduje go i instaluje globalne CLI z tego checkoutu. Kanały `stable` i `beta` używają instalacji pakietowych. Jeśli Gateway jest już zainstalowany, `openclaw update` odświeża metadane usługi i uruchamia ją ponownie, chyba że przekażesz `--no-restart`.
Kanał `dev` zapewnia checkout git, buduje go i instaluje globalny CLI
z tego checkoutu. Kanały `stable` i `beta` używają instalacji pakietowych. Jeśli
Gateway jest już zainstalowany, `openclaw update` odświeża metadane usługi
i restartuje ją, chyba że przekażesz `--no-restart`.
## Alternatywa: ponownie uruchom instalator
## Alternatywa: ponowne uruchomienie instalatora
```bash
curl -fsSL https://openclaw.ai/install.sh | bash
```
Dodaj `--no-onboard`, aby pominąć wdrażanie. Aby wymusić konkretny typ instalacji przez instalator, przekaż `--install-method git --no-onboard` albo `--install-method npm --no-onboard`.
Dodaj `--no-onboard`, aby pominąć onboarding. Aby wymusić konkretny typ instalacji przez
instalator, przekaż `--install-method git --no-onboard` albo
`--install-method npm --no-onboard`.
Jeśli `openclaw update` zawiedzie po fazie instalacji pakietu npm, ponownie uruchom instalator. Instalator nie wywołuje starego aktualizatora; uruchamia bezpośrednio globalną instalację pakietu i może odzyskać częściowo zaktualizowaną instalację npm.
Jeśli `openclaw update` nie powiedzie się po fazie instalacji pakietu npm, uruchom
instalator ponownie. Instalator nie wywołuje starego aktualizatora; uruchamia globalną
instalację pakietu bezpośrednio i może naprawić częściowo zaktualizowaną instalację npm.
```bash
curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method npm
```
Aby przypiąć odzyskiwanie do konkretnej wersji albo tagu dist-tag, dodaj `--version`:
Aby przypiąć odzyskiwanie do konkretnej wersji lub dist-tag, dodaj `--version`:
```bash
curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method npm --version <version-or-dist-tag>
```
## Alternatywa: ręcznie przez npm, pnpm albo bun
## Alternatywa: ręcznie przez npm, pnpm lub bun
```bash
npm i -g openclaw@latest
```
Gdy `openclaw update` zarządza globalną instalacją npm, najpierw instaluje cel w tymczasowym prefiksie npm, weryfikuje spis spakowanego `dist`, a następnie podmienia czyste drzewo pakietu do prawdziwego prefiksu globalnego. Zapobiega to nakładaniu przez npm nowego pakietu na przestarzałe pliki ze starego pakietu. Jeśli polecenie instalacji zawiedzie, OpenClaw ponawia próbę raz z `--omit=optional`. Ta ponowna próba pomaga hostom, na których natywne zależności opcjonalne nie mogą się skompilować, jednocześnie zachowując widoczność pierwotnego błędu, jeśli obejście także zawiedzie.
Gdy `openclaw update` zarządza globalną instalacją npm, najpierw instaluje cel w
tymczasowym prefiksie npm, weryfikuje spis spakowanego `dist`, a potem podmienia
czyste drzewo pakietu do rzeczywistego globalnego prefiksu. Dzięki temu npm nie nakłada
nowego pakietu na przestarzałe pliki ze starego pakietu. Jeśli polecenie instalacji się nie powiedzie,
OpenClaw ponawia próbę raz z `--omit=optional`. Ta ponowna próba pomaga hostom, na których natywne
opcjonalne zależności nie mogą się skompilować, jednocześnie zachowując widoczność pierwotnego błędu,
jeśli rozwiązanie awaryjne także się nie powiedzie.
```bash
pnpm add -g openclaw@latest
@ -97,36 +114,36 @@ bun add -g openclaw@latest
<AccordionGroup>
<Accordion title="Drzewo pakietów tylko do odczytu">
OpenClaw traktuje spakowane globalne instalacje jako tylko do odczytu w czasie runtime, nawet gdy globalny katalog pakietu jest zapisywalny przez bieżącego użytkownika. Zależności runtime dołączonych Pluginów są umieszczane w zapisywalnym katalogu runtime zamiast modyfikować drzewo pakietu. Dzięki temu `openclaw update` nie ściga się z działającym Gateway ani lokalnym agentem, który naprawia zależności Pluginów podczas tej samej instalacji.
OpenClaw traktuje spakowane globalne instalacje jako tylko do odczytu w czasie działania, nawet gdy globalny katalog pakietu jest zapisywalny przez bieżącego użytkownika. Dołączone zależności środowiska uruchomieniowego Pluginów są przygotowywane w zapisywalnym katalogu środowiska uruchomieniowego zamiast modyfikować drzewo pakietu. Dzięki temu `openclaw update` nie konkuruje z działającym Gateway ani lokalnym agentem naprawiającym zależności Pluginów podczas tej samej instalacji.
Niektóre konfiguracje npm w Linuksie instalują pakiety globalne w katalogach należących do root, takich jak `/usr/lib/node_modules/openclaw`. OpenClaw obsługuje taki układ przez tę samą zewnętrzną ścieżkę stagingu.
Niektóre konfiguracje npm w systemie Linux instalują globalne pakiety w katalogach należących do roota, takich jak `/usr/lib/node_modules/openclaw`. OpenClaw obsługuje taki układ przez tę samą zewnętrzną ścieżkę przygotowawczą.
</Accordion>
<Accordion title="Utwardzone jednostki systemd">
Ustaw zapisywalny katalog stagingu, który jest uwzględniony w `ReadWritePaths`:
<Accordion title="Wzmocnione jednostki systemd">
Ustaw zapisywalny katalog przygotowawczy uwzględniony w `ReadWritePaths`:
```ini
Environment=OPENCLAW_PLUGIN_STAGE_DIR=/var/lib/openclaw/plugin-runtime-deps
ReadWritePaths=/var/lib/openclaw /home/openclaw/.openclaw /tmp
```
`OPENCLAW_PLUGIN_STAGE_DIR` przyjmuje także listę ścieżek. OpenClaw rozwiązuje zależności runtime dołączonych Pluginów od lewej do prawej po wymienionych katalogach głównych, traktuje wcześniejsze katalogi główne jako tylko do odczytu, wstępnie zainstalowane warstwy, i instaluje albo naprawia wyłącznie w końcowym zapisywalnym katalogu głównym:
`OPENCLAW_PLUGIN_STAGE_DIR` akceptuje także listę ścieżek. OpenClaw rozwiązuje dołączone zależności środowiska uruchomieniowego Pluginów od lewej do prawej w podanych katalogach głównych, traktuje wcześniejsze katalogi jako preinstalowane warstwy tylko do odczytu i instaluje lub naprawia tylko w końcowym zapisywalnym katalogu głównym:
```ini
Environment=OPENCLAW_PLUGIN_STAGE_DIR=/opt/openclaw/plugin-runtime-deps:/var/lib/openclaw/plugin-runtime-deps
ReadWritePaths=/var/lib/openclaw /home/openclaw/.openclaw /tmp
```
Jeśli `OPENCLAW_PLUGIN_STAGE_DIR` nie jest ustawione, OpenClaw używa `$STATE_DIRECTORY`, gdy systemd je udostępnia, a następnie wraca do `~/.openclaw/plugin-runtime-deps`. Krok naprawy traktuje ten staging jako lokalny katalog główny pakietów należący do OpenClaw i ignoruje prefiks npm użytkownika oraz ustawienia globalne, więc konfiguracja npm dla instalacji globalnej nie przekierowuje zależności dołączonych Pluginów do `~/node_modules` ani do globalnego drzewa pakietu.
Jeśli `OPENCLAW_PLUGIN_STAGE_DIR` nie jest ustawione, OpenClaw używa `$STATE_DIRECTORY`, gdy zapewnia je systemd, a następnie wraca do `~/.openclaw/plugin-runtime-deps`. Krok naprawy traktuje ten obszar przygotowawczy jako lokalny katalog główny pakietów należący do OpenClaw i ignoruje prefiks npm użytkownika oraz ustawienia globalne, więc konfiguracja npm dla instalacji globalnej nie przekierowuje dołączonych zależności Pluginów do `~/node_modules` ani do globalnego drzewa pakietu.
</Accordion>
<Accordion title="Wstępne sprawdzenie miejsca na dysku">
Przed aktualizacjami pakietów i naprawami dołączonych zależności runtime OpenClaw próbuje wykonać najlepsze możliwe sprawdzenie miejsca na dysku dla woluminu docelowego. Mała ilość miejsca generuje ostrzeżenie ze sprawdzoną ścieżką, ale nie blokuje aktualizacji, ponieważ limity systemu plików, migawki i woluminy sieciowe mogą zmienić się po sprawdzeniu. Rzeczywista instalacja npm, kopiowanie i weryfikacja po instalacji pozostają rozstrzygające.
Przed aktualizacjami pakietów i naprawami dołączonych zależności środowiska uruchomieniowego OpenClaw próbuje wykonać orientacyjne sprawdzenie miejsca na dysku dla woluminu docelowego. Mała ilość miejsca generuje ostrzeżenie ze sprawdzoną ścieżką, ale nie blokuje aktualizacji, ponieważ limity systemu plików, migawki i woluminy sieciowe mogą się zmienić po sprawdzeniu. Rzeczywista instalacja npm, kopiowanie i weryfikacja po instalacji pozostają rozstrzygające.
</Accordion>
<Accordion title="Zależności runtime dołączonych Pluginów">
Instalacje pakietowe utrzymują zależności runtime dołączonych Pluginów poza drzewem pakietu tylko do odczytu. Przy uruchomieniu i podczas `openclaw doctor --fix` OpenClaw naprawia zależności runtime tylko dla dołączonych Pluginów, które są aktywne w konfiguracji, aktywne przez starszą konfigurację kanału albo włączone przez domyślne ustawienie ich dołączonego manifestu. Sam utrwalony stan uwierzytelnienia kanału nie wyzwala naprawy zależności runtime podczas startu Gateway.
<Accordion title="Dołączone zależności środowiska uruchomieniowego Pluginów">
Instalacje pakietowe trzymają dołączone zależności środowiska uruchomieniowego Pluginów poza drzewem pakietu tylko do odczytu. Podczas uruchamiania i w trakcie `openclaw doctor --fix` OpenClaw naprawia zależności środowiska uruchomieniowego tylko dla dołączonych Pluginów, które są aktywne w konfiguracji, aktywne przez starszą konfigurację kanału albo włączone przez domyślne ustawienie dołączonego manifestu. Sam utrwalony stan uwierzytelniania kanału nie uruchamia naprawy zależności środowiska uruchomieniowego przy starcie Gateway.
Jawne wyłączenie ma pierwszeństwo. Wyłączony Plugin albo kanał nie ma naprawianych zależności runtime tylko dlatego, że istnieje w pakiecie. Zewnętrzne Pluginy i niestandardowe ścieżki ładowania nadal używają `openclaw plugins install` albo `openclaw plugins update`.
Jawne wyłączenie ma pierwszeństwo. Wyłączony Plugin lub kanał nie ma naprawianych zależności środowiska uruchomieniowego tylko dlatego, że istnieje w pakiecie. Zewnętrzne Pluginy i niestandardowe ścieżki ładowania nadal używają `openclaw plugins install` albo `openclaw plugins update`.
</Accordion>
</AccordionGroup>
@ -149,14 +166,21 @@ Automatyczny aktualizator jest domyślnie wyłączony. Włącz go w `~/.openclaw
}
```
| Kanał | Zachowanie |
| -------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `stable` | Czeka `stableDelayHours`, a potem stosuje aktualizację z deterministycznym jitterem w ramach `stableJitterHours` (rozproszone wdrożenie). |
| `beta` | Sprawdza co `betaCheckIntervalHours` (domyślnie: co godzinę) i stosuje natychmiast. |
| `dev` | Brak automatycznego stosowania. Użyj ręcznie `openclaw update`. |
| Kanał | Zachowanie |
| -------- | --------------------------------------------------------------------------------------------------------------- |
| `stable` | Czeka `stableDelayHours`, a następnie stosuje z deterministycznym jitterem w ramach `stableJitterHours` (rozproszony rollout). |
| `beta` | Sprawdza co `betaCheckIntervalHours` (domyślnie: co godzinę) i stosuje natychmiast. |
| `dev` | Brak automatycznego stosowania. Użyj ręcznie `openclaw update`. |
Gateway zapisuje także podpowiedź o aktualizacji przy uruchomieniu (wyłącz przez `update.checkOnStart: false`).
W przypadku downgrade'u albo odzyskiwania po incydencie ustaw `OPENCLAW_NO_AUTO_UPDATE=1` w środowisku Gateway, aby zablokować automatyczne stosowanie aktualizacji nawet wtedy, gdy skonfigurowano `update.auto.enabled`. Podpowiedzi o aktualizacji przy starcie nadal mogą działać, chyba że wyłączono także `update.checkOnStart`.
Gateway zapisuje także wskazówkę aktualizacji przy starcie (wyłącz przez `update.checkOnStart: false`).
W przypadku downgrade'u lub odzyskiwania po incydencie ustaw `OPENCLAW_NO_AUTO_UPDATE=1` w środowisku Gateway, aby zablokować automatyczne stosowanie nawet wtedy, gdy skonfigurowano `update.auto.enabled`. Wskazówki aktualizacji przy starcie nadal mogą działać, chyba że wyłączono także `update.checkOnStart`.
Aktualizacje menedżera pakietów żądane przez aktywny handler płaszczyzny sterowania Gateway
wymuszają niezależny od odroczenia i cooldownu restart aktualizacji po podmianie pakietu. Dzięki temu
stary proces w pamięci nie pozostaje wystarczająco długo, aby leniwie ładować fragmenty
z drzewa pakietu, które zostało już zastąpione. Powłokowe `openclaw update`
pozostaje preferowaną ścieżką dla nadzorowanych instalacji, ponieważ może zatrzymać i
zrestartować usługę wokół aktualizacji.
## Po aktualizacji
@ -168,9 +192,9 @@ W przypadku downgrade'u albo odzyskiwania po incydencie ustaw `OPENCLAW_NO_AUTO_
openclaw doctor
```
Migruje konfigurację, audytuje zasady DM i sprawdza kondycję Gateway. Szczegóły: [Doctor](/pl/gateway/doctor)
Migruje konfigurację, audytuje polityki DM i sprawdza kondycję Gateway. Szczegóły: [Doctor](/pl/gateway/doctor)
### Uruchom ponownie Gateway
### Zrestartuj Gateway
```bash
openclaw gateway restart
@ -198,7 +222,7 @@ openclaw gateway restart
`npm view openclaw version` pokazuje bieżącą opublikowaną wersję.
</Tip>
### Przypnij commit (źródło)
### Przypnij commit (źródła)
```bash
git fetch origin
@ -212,7 +236,7 @@ Aby wrócić do najnowszej wersji: `git checkout main && git pull`.
## Jeśli utkniesz
- Uruchom ponownie `openclaw doctor` i uważnie przeczytaj wynik.
- Dla `openclaw update --channel dev` na checkoutach źródłowych aktualizator automatycznie bootstrapuje `pnpm`, gdy jest to potrzebne. Jeśli zobaczysz błąd bootstrapu pnpm/corepack, zainstaluj `pnpm` ręcznie (albo ponownie włącz `corepack`) i ponów aktualizację.
- Dla `openclaw update --channel dev` na checkoutach źródłowych aktualizator automatycznie bootstrapuje `pnpm`, gdy jest to potrzebne. Jeśli zobaczysz błąd bootstrapu pnpm/corepack, zainstaluj `pnpm` ręcznie (albo ponownie włącz `corepack`) i ponownie uruchom aktualizację.
- Sprawdź: [Rozwiązywanie problemów](/pl/gateway/troubleshooting)
- Zapytaj na Discord: [https://discord.gg/clawd](https://discord.gg/clawd)
@ -220,4 +244,4 @@ Aby wrócić do najnowszej wersji: `git checkout main && git pull`.
- [Przegląd instalacji](/pl/install): wszystkie metody instalacji.
- [Doctor](/pl/gateway/doctor): kontrole kondycji po aktualizacjach.
- [Migracja](/pl/install/migrating): przewodniki migracji wersji głównych.
- [Migracja](/pl/install/migrating): przewodniki po migracji głównych wersji.

176
docs/pl/logging.md
View File

@ -1,39 +1,39 @@
---
read_when:
- Potrzebujesz przystępnego dla początkujących omówienia rejestrowania zdarzeń w OpenClaw
- Potrzebujesz przyjaznego dla początkujących omówienia logowania w OpenClaw
- Chcesz skonfigurować poziomy logowania, formaty lub maskowanie
- Diagnozujesz problem i musisz szybko znaleźć logi
summary: Logi plików, dane wyjściowe konsoli, śledzenie logów w CLI i karta Dzienniki w Control UI
- Rozwiązujesz problem i musisz szybko znaleźć logi
summary: Logi plików, dane wyjściowe konsoli, śledzenie na żywo w CLI i karta Logi w Control UI
title: Rejestrowanie
x-i18n:
generated_at: "2026-04-30T10:02:58Z"
generated_at: "2026-05-01T10:00:42Z"
model: gpt-5.5
provider: openai
source_hash: 916fb03219d571f0302560a4cb6755940575c92fff0b4eab024b9dad53f841ce
source_hash: d41ce5b1ae30fe1ca65577abe387fc266bd281686acb10098f82b8e78dfaa357
source_path: logging.md
workflow: 16
---
OpenClaw ma dwie główne powierzchnie dzienników:
OpenClaw ma dwa główne obszary logowania:
- **Dzienniki plikowe** (linie JSON) zapisywane przez Gateway.
- **Wyjście konsoli** wyświetlane w terminalach i interfejsie Gateway Debug UI.
- **Dzienniki plikowe** (wiersze JSON) zapisywane przez Gateway.
- **Dane wyjściowe konsoli** wyświetlane w terminalach i w interfejsie debugowania Gateway.
Karta **Logs** w Control UI śledzi plik dziennika gatewaya. Ta strona wyjaśnia, gdzie
znajdują się dzienniki, jak je czytać oraz jak konfigurować poziomy i formaty dzienników.
Karta **Dzienniki** w Control UI śledzi plik dziennika Gateway. Ta strona wyjaśnia, gdzie
znajdują się dzienniki, jak je czytać oraz jak konfigurować poziomy i formaty logowania.
## Gdzie znajdują się dzienniki
Domyślnie Gateway zapisuje rotowany plik dziennika w:
Domyślnie Gateway zapisuje rotacyjny plik dziennika w:
`/tmp/openclaw/openclaw-YYYY-MM-DD.log`
Data używa lokalnej strefy czasowej hosta gatewaya.
Data używa lokalnej strefy czasowej hosta Gateway.
Każdy plik jest rotowany po osiągnięciu `logging.maxFileBytes` (domyślnie: 100 MB).
OpenClaw przechowuje do pięciu numerowanych archiwów obok aktywnego pliku, takich jak
`openclaw-YYYY-MM-DD.1.log`, i kontynuuje zapisywanie do nowego aktywnego dziennika zamiast
tłumić diagnostykę.
`openclaw-YYYY-MM-DD.1.log`, i zapisuje dalej do nowego aktywnego dziennika zamiast
pomijać diagnostykę.
Możesz to nadpisać w `~/.openclaw/openclaw.json`:
@ -49,7 +49,7 @@ Możesz to nadpisać w `~/.openclaw/openclaw.json`:
### CLI: śledzenie na żywo (zalecane)
Użyj CLI, aby śledzić plik dziennika gatewaya przez RPC:
Użyj CLI, aby śledzić plik dziennika Gateway przez RPC:
```bash
openclaw logs --follow
@ -59,18 +59,18 @@ Przydatne bieżące opcje:
- `--local-time`: renderuje znaczniki czasu w Twojej lokalnej strefie czasowej
- `--url <url>` / `--token <token>` / `--timeout <ms>`: standardowe flagi RPC Gateway
- `--expect-final`: flaga oczekiwania na końcową odpowiedź RPC obsługiwaną przez agenta (akceptowana tutaj przez wspólną warstwę klienta)
- `--expect-final`: flaga oczekiwania na końcową odpowiedź RPC obsługiwaną przez agenta (akceptowana tutaj przez współdzieloną warstwę klienta)
Tryby wyjścia:
- **Sesje TTY**: estetyczne, kolorowane, ustrukturyzowane wiersze dziennika.
- **Sesje TTY**: czytelne, kolorowane, ustrukturyzowane wiersze dziennika.
- **Sesje inne niż TTY**: zwykły tekst.
- `--json`: JSON rozdzielany wierszami (jedno zdarzenie dziennika na wiersz).
- `--plain`: wymusza zwykły tekst w sesjach TTY.
- `--no-color`: wyłącza kolory ANSI.
Gdy przekażesz jawne `--url`, CLI nie stosuje automatycznie konfiguracji ani
poświadczeń ze środowiska; dodaj samodzielnie `--token`, jeśli docelowy Gateway
Gdy przekażesz jawne `--url`, CLI nie stosuje automatycznie poświadczeń z konfiguracji ani
środowiska; dołącz samodzielnie `--token`, jeśli docelowy Gateway
wymaga uwierzytelnienia.
W trybie JSON CLI emituje obiekty oznaczone polem `type`:
@ -80,12 +80,12 @@ W trybie JSON CLI emituje obiekty oznaczone polem `type`:
- `notice`: wskazówki dotyczące obcięcia / rotacji
- `raw`: niesparsowany wiersz dziennika
Jeśli niejawny lokalny Gateway przez local loopback poprosi o parowanie, zamknie połączenie
podczas łączenia albo przekroczy limit czasu przed odpowiedzią `logs.tail`,
`openclaw logs` automatycznie przełączy się awaryjnie na skonfigurowany plik dziennika
Gateway. Jawne cele `--url` nie używają tego mechanizmu awaryjnego.
Jeśli niejawny Gateway przez local loopback poprosi o parowanie, zamknie połączenie podczas łączenia
albo przekroczy limit czasu, zanim `logs.tail` odpowie, `openclaw logs` automatycznie przełączy się na
skonfigurowany plik dziennika Gateway. Jawne cele `--url` nie używają
tego mechanizmu awaryjnego.
Jeśli Gateway jest nieosiągalny, CLI wyświetli krótką wskazówkę, aby uruchomić:
Jeśli Gateway jest nieosiągalny, CLI wypisze krótką wskazówkę, aby uruchomić:
```bash
openclaw doctor
@ -93,12 +93,12 @@ openclaw doctor
### Control UI (web)
Karta **Logs** w Control UI śledzi ten sam plik za pomocą `logs.tail`.
Karta **Dzienniki** w Control UI śledzi ten sam plik przy użyciu `logs.tail`.
Zobacz [/web/control-ui](/pl/web/control-ui), aby dowiedzieć się, jak ją otworzyć.
### Dzienniki tylko kanałów
Aby filtrować aktywność kanałów (WhatsApp/Telegram/itp.), użyj:
Aby filtrować aktywność kanałów (WhatsApp/Telegram/itd.), użyj:
```bash
openclaw channels logs --channel whatsapp
@ -109,21 +109,21 @@ openclaw channels logs --channel whatsapp
### Dzienniki plikowe (JSONL)
Każdy wiersz w pliku dziennika jest obiektem JSON. CLI i Control UI parsują te
wpisy, aby renderować ustrukturyzowane wyjście (czas, poziom, podsystem, komunikat).
wpisy, aby renderować ustrukturyzowane dane wyjściowe (czas, poziom, podsystem, komunikat).
Rekordy JSONL dziennika plikowego zawierają też możliwe do filtrowania maszynowo pola
najwyższego poziomu, gdy są dostępne:
Rekordy JSONL dziennika plikowego zawierają też filtrowalne maszynowo pola najwyższego poziomu, gdy
są dostępne:
- `hostname`: nazwa hosta gatewaya.
- `hostname`: nazwa hosta Gateway.
- `message`: spłaszczony tekst komunikatu dziennika do wyszukiwania pełnotekstowego.
- `agent_id`: identyfikator aktywnego agenta, gdy wywołanie dziennika niesie kontekst agenta.
- `session_id`: identyfikator/klucz aktywnej sesji, gdy wywołanie dziennika niesie kontekst sesji.
- `channel`: aktywny kanał, gdy wywołanie dziennika niesie kontekst kanału.
- `agent_id`: identyfikator aktywnego agenta, gdy wywołanie logowania przenosi kontekst agenta.
- `session_id`: identyfikator/klucz aktywnej sesji, gdy wywołanie logowania przenosi kontekst sesji.
- `channel`: aktywny kanał, gdy wywołanie logowania przenosi kontekst kanału.
OpenClaw zachowuje oryginalne ustrukturyzowane argumenty dziennika obok tych pól,
dzięki czemu istniejące parsery odczytujące numerowane klucze argumentów tslog nadal działają.
OpenClaw zachowuje oryginalne ustrukturyzowane argumenty logowania obok tych pól,
aby istniejące parsery odczytujące numerowane klucze argumentów tslog nadal działały.
### Wyjście konsoli
### Dane wyjściowe konsoli
Dzienniki konsoli są **świadome TTY** i formatowane pod kątem czytelności:
@ -131,15 +131,15 @@ Dzienniki konsoli są **świadome TTY** i formatowane pod kątem czytelności:
- Kolorowanie poziomów (info/warn/error)
- Opcjonalny tryb kompaktowy lub JSON
Formatowanie konsoli jest kontrolowane przez `logging.consoleStyle`.
Formatowaniem konsoli steruje `logging.consoleStyle`.
### Dzienniki WebSocket Gateway
`openclaw gateway` ma również rejestrowanie protokołu WebSocket dla ruchu RPC:
`openclaw gateway` ma też logowanie protokołu WebSocket dla ruchu RPC:
- tryb normalny: tylko istotne wyniki (błędy, błędy parsowania, wolne wywołania)
- tryb normalny: tylko interesujące wyniki (błędy, błędy parsowania, wolne wywołania)
- `--verbose`: cały ruch żądań/odpowiedzi
- `--ws-log auto|compact|full`: wybiera styl renderowania szczegółowego
- `--ws-log auto|compact|full`: wybór stylu renderowania w trybie szczegółowym
- `--compact`: alias dla `--ws-log compact`
Przykłady:
@ -150,9 +150,9 @@ openclaw gateway --verbose --ws-log compact
openclaw gateway --verbose --ws-log full
```
## Konfigurowanie dzienników
## Konfigurowanie logowania
Cała konfiguracja dzienników znajduje się pod `logging` w `~/.openclaw/openclaw.json`.
Cała konfiguracja logowania znajduje się pod `logging` w `~/.openclaw/openclaw.json`.
```json
{
@ -167,33 +167,33 @@ Cała konfiguracja dzienników znajduje się pod `logging` w `~/.openclaw/opencl
}
```
### Poziomy dzienników
### Poziomy logowania
- `logging.level`: poziom **dzienników plikowych** (JSONL).
- `logging.consoleLevel`: poziom szczegółowości **konsoli**.
Możesz nadpisać oba za pomocą zmiennej środowiskowej **`OPENCLAW_LOG_LEVEL`** (np. `OPENCLAW_LOG_LEVEL=debug`). Zmienna środowiskowa ma pierwszeństwo przed plikiem konfiguracyjnym, dzięki czemu możesz zwiększyć szczegółowość dla pojedynczego uruchomienia bez edytowania `openclaw.json`. Możesz też przekazać globalną opcję CLI **`--log-level <level>`** (na przykład `openclaw --log-level debug gateway run`), która nadpisuje zmienną środowiskową dla tego polecenia.
Możesz nadpisać oba za pomocą zmiennej środowiskowej **`OPENCLAW_LOG_LEVEL`** (np. `OPENCLAW_LOG_LEVEL=debug`). Zmienna środowiskowa ma pierwszeństwo przed plikiem konfiguracji, więc możesz zwiększyć szczegółowość dla pojedynczego uruchomienia bez edytowania `openclaw.json`. Możesz też przekazać globalną opcję CLI **`--log-level <level>`** (na przykład `openclaw --log-level debug gateway run`), która nadpisuje zmienną środowiskową dla tego polecenia.
`--verbose` wpływa tylko na wyjście konsoli i szczegółowość dzienników WS; nie zmienia
`--verbose` wpływa tylko na dane wyjściowe konsoli i szczegółowość dziennika WS; nie zmienia
poziomów dzienników plikowych.
### Korelacja śladów
Dzienniki plikowe są w formacie JSONL. Gdy wywołanie dziennika niesie poprawny kontekst śladu diagnostycznego,
Dzienniki plikowe są w formacie JSONL. Gdy wywołanie logowania przenosi prawidłowy kontekst śladu diagnostycznego,
OpenClaw zapisuje pola śladu jako klucze JSON najwyższego poziomu (`traceId`, `spanId`,
`parentSpanId`, `traceFlags`), aby zewnętrzne procesory dzienników mogły skorelować wiersz
ze spanami OTEL i propagacją `traceparent` dostawcy.
z zakresami OTEL i propagacją `traceparent` dostawcy.
Żądania HTTP Gateway i ramki WebSocket Gateway ustanawiają wewnętrzny zakres śladu żądania.
Dzienniki i zdarzenia diagnostyczne emitowane w tym zakresie asynchronicznym dziedziczą
ślad żądania, gdy nie przekazują jawnego kontekstu śladu. Ślady uruchomienia agenta i
wywołań modelu stają się dziećmi aktywnego śladu żądania, dzięki czemu lokalne dzienniki,
migawki diagnostyczne, spany OTEL i zaufane nagłówki `traceparent` dostawcy można
łączyć po `traceId` bez rejestrowania surowej treści żądania lub modelu.
Żądania HTTP Gateway i ramki WebSocket Gateway ustanawiają wewnętrzny zakres śladu
żądania. Dzienniki i zdarzenia diagnostyczne emitowane wewnątrz tego zakresu asynchronicznego dziedziczą
ślad żądania, gdy nie przekazują jawnego kontekstu śladu. Ślady uruchomień agentów i
wywołań modeli stają się dziećmi aktywnego śladu żądania, dzięki czemu lokalne dzienniki,
migawki diagnostyczne, zakresy OTEL i zaufane nagłówki `traceparent` dostawców mogą
być łączone według `traceId` bez logowania surowej treści żądań lub modeli.
### Rozmiar i czas wywołania modelu
Diagnostyka wywołań modelu zapisuje ograniczone pomiary żądania/odpowiedzi bez
Diagnostyka wywołań modeli rejestruje ograniczone pomiary żądań/odpowiedzi bez
przechwytywania surowej treści promptu lub odpowiedzi:
- `requestPayloadBytes`: rozmiar w bajtach UTF-8 końcowego ładunku żądania modelu
@ -201,61 +201,65 @@ przechwytywania surowej treści promptu lub odpowiedzi:
- `timeToFirstByteMs`: czas, który upłynął przed pierwszym strumieniowanym zdarzeniem odpowiedzi
- `durationMs`: całkowity czas trwania wywołania modelu
Te pola są dostępne dla migawek diagnostycznych, haków pluginów wywołań modelu oraz
spanów/metryk OTEL wywołań modelu, gdy eksport diagnostyki jest włączony.
Te pola są dostępne dla migawek diagnostycznych, hooków Plugin wywołań modeli oraz
zakresów/metryk OTEL wywołań modeli, gdy eksport diagnostyki jest włączony.
### Style konsoli
`logging.consoleStyle`:
- `pretty`: przyjazny dla człowieka, kolorowany, ze znacznikami czasu.
- `compact`: bardziej zwarte wyjście (najlepsze dla długich sesji).
- `compact`: bardziej zwarte dane wyjściowe (najlepsze dla długich sesji).
- `json`: JSON w każdym wierszu (dla procesorów dzienników).
### Redakcja
### Redakcja danych wrażliwych
OpenClaw może redagować wrażliwe tokeny, zanim trafią do wyjścia konsoli, dzienników plikowych,
rekordów dzienników OTLP, utrwalonego tekstu transkryptu sesji lub ładunków zdarzeń narzędzi
w Control UI (argumenty startu narzędzia, częściowe/końcowe ładunki wyników, pochodne
wyjście exec i podsumowania poprawek):
OpenClaw może redagować wrażliwe tokeny, zanim trafią do danych wyjściowych konsoli, dzienników plikowych,
rekordów dziennika OTLP, utrwalonego tekstu transkrypcji sesji lub ładunków zdarzeń narzędzi
Control UI (argumenty rozpoczęcia narzędzia, częściowe/końcowe ładunki wyników, pochodne
dane wyjściowe exec i podsumowania poprawek):
- `logging.redactSensitive`: `off` | `tools` (domyślnie: `tools`)
- `logging.redactPatterns`: lista ciągów regex nadpisująca domyślny zestaw. Własne wzorce są stosowane dodatkowo do wbudowanych ustawień domyślnych dla ładunków narzędzi Control UI, więc dodanie wzorca nigdy nie osłabia redakcji wartości już wychwytywanych przez ustawienia domyślne.
- `logging.redactPatterns`: lista ciągów regex do nadpisania zestawu domyślnego. Niestandardowe wzorce są stosowane dodatkowo względem wbudowanych wartości domyślnych dla ładunków narzędzi Control UI, więc dodanie wzorca nigdy nie osłabia redakcji wartości już wychwytywanych przez wartości domyślne.
Dzienniki plikowe i transkrypty sesji pozostają w formacie JSONL, ale pasujące wartości sekretów są
maskowane przed zapisaniem wiersza lub komunikatu na dysku. Redakcja działa na zasadzie najlepszych starań:
obejmuje treść komunikatów zawierającą tekst i ciągi dzienników, a nie każde
pole identyfikatora lub ładunku binarnego.
Dzienniki plikowe i transkrypcje sesji pozostają w formacie JSONL, ale pasujące wartości sekretów są
maskowane, zanim wiersz lub komunikat zostanie zapisany na dysk. Redakcja jest najlepszym możliwym wysiłkiem:
stosuje się do treści komunikatów zawierających tekst i ciągów dziennika, a nie do każdego
identyfikatora lub pola ładunku binarnego.
`logging.redactSensitive: "off"` wyłącza tylko tę ogólną politykę
dzienników/transkryptów. OpenClaw nadal redaguje ładunki na granicach bezpieczeństwa, które mogą być pokazywane klientom UI,
pakietom wsparcia, obserwatorom diagnostyki, promptom zatwierdzeń lub narzędziom agentów.
Przykłady obejmują zdarzenia wywołań narzędzi Control UI, wyjście `sessions_history`,
eksporty wsparcia diagnostyki, obserwacje błędów dostawcy, wyświetlanie poleceń zatwierdzania exec
oraz dzienniki protokołu WebSocket Gateway. Własne `logging.redactPatterns`
nadal mogą dodawać wzorce specyficzne dla projektu na tych powierzchniach.
Wbudowane wartości domyślne obejmują popularne poświadczenia API i nazwy pól poświadczeń płatniczych,
takie jak numer karty, CVC/CVV, współdzielony token płatności i poświadczenie płatnicze,
gdy pojawiają się jako pola JSON, parametry URL, flagi CLI lub przypisania.
`logging.redactSensitive: "off"` wyłącza tylko tę ogólną politykę dzienników/transkrypcji.
OpenClaw nadal redaguje ładunki granicy bezpieczeństwa, które mogą być pokazywane klientom UI,
pakietom wsparcia, obserwatorom diagnostyki, promptom zatwierdzania lub narzędziom
agentów. Przykłady obejmują zdarzenia wywołań narzędzi Control UI, dane wyjściowe `sessions_history`,
eksporty diagnostyczne dla wsparcia, obserwacje błędów dostawców, wyświetlanie poleceń zatwierdzania exec
oraz dzienniki protokołu WebSocket Gateway. Niestandardowe `logging.redactPatterns`
mogą nadal dodawać wzorce specyficzne dla projektu na tych powierzchniach.
## Diagnostyka i OpenTelemetry
Diagnostyka to ustrukturyzowane, czytelne maszynowo zdarzenia dla uruchomień modelu i
Diagnostyka to ustrukturyzowane, czytelne maszynowo zdarzenia dla uruchomień modeli i
telemetrii przepływu wiadomości (webhooki, kolejkowanie, stan sesji). **Nie**
zastępują dzienników — zasilają metryki, ślady i eksportery. Zdarzenia są emitowane
w procesie niezależnie od tego, czy je eksportujesz.
Dwie sąsiednie powierzchnie:
Dwa sąsiadujące obszary:
- **Eksport OpenTelemetry** — wysyłaj metryki, ślady i dzienniki przez OTLP/HTTP do
- **Eksport OpenTelemetry** — wysyłanie metryk, śladów i dzienników przez OTLP/HTTP do
dowolnego kolektora lub backendu zgodnego z OpenTelemetry (Grafana, Datadog,
Honeycomb, New Relic, Tempo itd.). Pełna konfiguracja, katalog sygnałów,
nazwy metryk/spanów, zmienne środowiskowe i model prywatności znajdują się na dedykowanej stronie:
nazwy metryk/zakresów, zmienne środowiskowe i model prywatności znajdują się na dedykowanej stronie:
[Eksport OpenTelemetry](/pl/gateway/opentelemetry).
- **Flagi diagnostyki** — ukierunkowane flagi dzienników debugowania, które kierują dodatkowe dzienniki do
- **Flagi diagnostyczne** — ukierunkowane flagi dzienników debugowania, które kierują dodatkowe dzienniki do
`logging.file` bez podnoszenia `logging.level`. Flagi nie rozróżniają wielkości liter
i obsługują symbole wieloznaczne (`telegram.*`, `*`). Skonfiguruj je pod `diagnostics.flags`
lub przez nadpisanie zmienną środowiskową `OPENCLAW_DIAGNOSTICS=...`. Pełny przewodnik:
[Flagi diagnostyki](/pl/diagnostics/flags).
[Flagi diagnostyczne](/pl/diagnostics/flags).
Aby włączyć zdarzenia diagnostyczne dla pluginów lub własnych ujść bez eksportu OTLP:
Aby włączyć zdarzenia diagnostyczne dla plugins lub niestandardowych odbiorników bez eksportu OTLP:
```json5
{
@ -267,14 +271,14 @@ Eksport OTLP do kolektora opisuje [Eksport OpenTelemetry](/pl/gateway/openteleme
## Wskazówki dotyczące rozwiązywania problemów
- **Gateway nieosiągalny?** Najpierw uruchom `openclaw doctor`.
- **Dzienniki puste?** Sprawdź, czy Gateway działa i zapisuje do ścieżki pliku
- **Gateway nie jest osiągalny?** Najpierw uruchom `openclaw doctor`.
- **Dzienniki są puste?** Sprawdź, czy Gateway działa i zapisuje do ścieżki pliku
w `logging.file`.
- **Potrzebujesz więcej szczegółów?** Ustaw `logging.level` na `debug` lub `trace` i spróbuj ponownie.
## Powiązane
- [Eksport OpenTelemetry](/pl/gateway/opentelemetry) — eksport OTLP/HTTP, katalog metryk/spanów, model prywatności
- [Flagi diagnostyki](/pl/diagnostics/flags) — ukierunkowane flagi dzienników debugowania
- [Wewnętrzne mechanizmy dzienników Gateway](/pl/gateway/logging) — style dzienników WS, prefiksy podsystemów i przechwytywanie konsoli
- [Eksport OpenTelemetry](/pl/gateway/opentelemetry) — eksport OTLP/HTTP, katalog metryk/zakresów, model prywatności
- [Flagi diagnostyczne](/pl/diagnostics/flags) — ukierunkowane flagi dzienników debugowania
- [Wewnętrzne mechanizmy logowania Gateway](/pl/gateway/logging) — style dzienników WS, prefiksy podsystemów i przechwytywanie konsoli
- [Dokumentacja konfiguracji](/pl/gateway/configuration-reference#diagnostics) — pełna dokumentacja pól `diagnostics.*`

93
docs/pl/platforms/mac/menu-bar.md
View File

@ -1,93 +1,102 @@
---
read_when:
- Dostosowywanie interfejsu mac menu lub logiki statusu
summary: Logika statusu paska menu i to, co jest pokazywane użytkownikom
- Dostosowywanie interfejsu menu Maca lub logiki statusu
summary: Logika stanu paska menu i informacje prezentowane użytkownikom
title: Pasek menu
x-i18n:
generated_at: "2026-04-24T09:21:10Z"
model: gpt-5.4
generated_at: "2026-05-01T10:00:28Z"
model: gpt-5.5
provider: openai
source_hash: 89b03f3b0f9e56057d4cbf10bd1252372c65a2b2ae5e0405a844e9a59b51405d
source_hash: 340b86a2e222fb1fe7fda4f0f0434127af1393a64348ea033ea284ba52866beb
source_path: platforms/mac/menu-bar.md
workflow: 15
workflow: 16
---
# Logika statusu paska menu
# Logika stanu paska menu
## Co jest pokazywane
## Co jest wyświetlane
- W ikonie paska menu i w pierwszym wierszu statusu menu pokazujemy bieżący stan pracy agenta.
- Status kondycji jest ukrywany podczas aktywnej pracy; wraca, gdy wszystkie sesje są bezczynne.
- Blok „Nodes” w menu pokazuje tylko **urządzenia** (sparowane Node przez `node.list`), a nie wpisy klienta/presence.
- Sekcja „Usage” pojawia się pod Context, gdy dostępne są snapshoty użycia dostawcy.
- Pokazujemy bieżący stan pracy agenta w ikonie paska menu oraz w pierwszym wierszu stanu menu.
- Stan kondycji jest ukryty, gdy praca jest aktywna; wraca, gdy wszystkie sesje są bezczynne.
- Główne podmenu „Kontekst” zawiera ostatnie sesje zamiast rozwijania ich bezpośrednio w menu głównym.
- Blok „Nodes” w menu głównym wyświetla tylko **urządzenia** (sparowane węzły przez `node.list`), a nie wpisy klientów/obecności.
- Główna sekcja „Użycie” pojawia się pod Kontekstem, gdy dostępne są migawki użycia dostawcy, a po niej szczegóły kosztów użycia, gdy są dostępne.
## Model stanu
- Sesje: zdarzenia przychodzą z `runId` (per przebieg) oraz `sessionKey` w ładunku. Sesja „main” ma klucz `main`; jeśli go brak, wracamy do ostatnio zaktualizowanej sesji.
- Priorytet: main zawsze wygrywa. Jeśli main jest aktywna, jej stan jest pokazywany natychmiast. Jeśli main jest bezczynna, pokazywana jest ostatnio aktywna sesja niebędąca main. Nie przełączamy się nerwowo w trakcie aktywności; przełączamy się dopiero wtedy, gdy bieżąca sesja przejdzie w bezczynność albo main stanie się aktywna.
- Sesje: zdarzenia przychodzą z `runId` (dla danego uruchomienia) oraz `sessionKey` w ładunku. Sesja „main” ma klucz `main`; jeśli go nie ma, wracamy do ostatnio zaktualizowanej sesji.
- Priorytet: main zawsze wygrywa. Jeśli main jest aktywna, jej stan jest pokazywany natychmiast. Jeśli main jest bezczynna, pokazywana jest ostatnio aktywna sesja inna niż main. Nie przełączamy się tam i z powrotem w trakcie aktywności; przełączamy tylko wtedy, gdy bieżąca sesja staje się bezczynna albo main staje się aktywna.
- Rodzaje aktywności:
- `job`: wykonywanie polecenia wysokiego poziomu (`state: started|streaming|done|error`).
- `tool`: `phase: start|result` z `toolName` i `meta/args`.
## Enum `IconState` (Swift)
## Wyliczenie IconState (Swift)
- `idle`
- `workingMain(ActivityKind)`
- `workingOther(ActivityKind)`
- `overridden(ActivityKind)` (nadpisanie debug)
- `overridden(ActivityKind)` (nadpisanie debugowania)
### `ActivityKind` → glif
### ActivityKind → glif
- `exec` → 💻
- `read` → 📄
- `write` → ✍️
- `edit` → 📝
- `attach` → 📎
- domyślnie → 🛠️
- domyślne → 🛠️
### Mapowanie wizualne
- `idle`: normalny stworek.
- `workingMain`: plakietka z glifem, pełne zabarwienie, animacja „pracujących” nóg.
- `workingOther`: plakietka z glifem, stonowane zabarwienie, bez ruchu.
- `idle`: normalne stworzenie.
- `workingMain`: odznaka z glifem, pełne zabarwienie, animacja „pracy” nóg.
- `workingOther`: odznaka z glifem, przytłumione zabarwienie, bez przebiegania.
- `overridden`: używa wybranego glifu/zabarwienia niezależnie od aktywności.
## Tekst w wierszu statusu (menu)
## Podmenu Kontekst
- Podczas aktywnej pracy: `<Session role> · <activity label>`
- Menu główne pokazuje jeden wiersz „Kontekst” z liczbą/stanem sesji i otwiera podmenu.
- Nagłówek podmenu Kontekst pokazuje liczbę aktywnych sesji z ostatnich 24 godzin.
- Każdy wiersz sesji zachowuje pasek tokenów, wiek, podgląd, myślenie/szczegółowość, resetowanie, kompaktowanie i akcje usuwania.
- Komunikaty ładowania, rozłączenia i błędów ładowania sesji pojawiają się w podmenu Kontekst.
- Użycie dostawcy i szczegóły kosztów użycia pozostają na poziomie głównym pod Kontekstem, aby były widoczne od razu bez otwierania podmenu.
## Tekst wiersza stanu (menu)
- Gdy praca jest aktywna: `<Session role> · <activity label>`
- Przykłady: `Main · exec: pnpm test`, `Other · read: apps/macos/Sources/OpenClaw/AppState.swift`.
- W stanie bezczynności: wraca do podsumowania kondycji.
- Gdy bezczynne: wraca do podsumowania kondycji.
## Pobieranie zdarzeń
- Źródło: zdarzenia `agent` kanału control (`ControlChannel.handleAgentEvent`).
- Źródło: zdarzenia `agent` kanału kontrolnego (`ControlChannel.handleAgentEvent`).
- Parsowane pola:
- `stream: "job"` z `data.state` dla uruchomienia/zatrzymania.
- `stream: "tool"` z `data.phase`, `name`, opcjonalnym `meta`/`args`.
- `stream: "job"` z `data.state` dla startu/zatrzymania.
- `stream: "tool"` z `data.phase`, `name`, opcjonalnie `meta`/`args`.
- Etykiety:
- `exec`: pierwszy wiersz z `args.command`.
- `exec`: pierwszy wiersz `args.command`.
- `read`/`write`: skrócona ścieżka.
- `edit`: ścieżka plus wywnioskowany rodzaj zmiany z `meta`/liczby różnic.
- fallback: nazwa narzędzia.
- `edit`: ścieżka oraz wywnioskowany rodzaj zmiany z `meta`/liczników diff.
- awaryjnie: nazwa narzędzia.
## Nadpisanie debug
## Nadpisanie debugowania
- Settings ▸ Debug ▸ wybór „Icon override”:
- `System (auto)` (domyślnie)
- `Working: main` (per rodzaj narzędzia)
- `Working: other` (per rodzaj narzędzia)
- Ustawienia ▸ Debugowanie ▸ selektor „Nadpisanie ikony”:
- `System (auto)` (domyślne)
- `Working: main` (dla rodzaju narzędzia)
- `Working: other` (dla rodzaju narzędzia)
- `Idle`
- Przechowywane przez `@AppStorage("iconOverride")`; mapowane do `IconState.overridden`.
- Przechowywane przez `@AppStorage("iconOverride")`; mapowane na `IconState.overridden`.
## Lista kontrolna testów
## Lista kontrolna testowania
- Wywołaj job sesji main: sprawdź, czy ikona przełącza się natychmiast, a wiersz statusu pokazuje etykietę main.
- Wywołaj job sesji niebędącej main, gdy main jest bezczynna: ikona/status pokazują sesję niebędącą main; pozostaje stabilna aż do zakończenia.
- Uruchom main, gdy aktywna jest inna sesja: ikona natychmiast przełącza się na main.
- Szybkie serie narzędzi: upewnij się, że plakietka nie miga (okres karencji TTL dla wyników narzędzi).
- Wywołaj zadanie sesji main: sprawdź, czy ikona przełącza się natychmiast, a wiersz stanu pokazuje etykietę main.
- Wywołaj zadanie sesji innej niż main, gdy main jest bezczynna: ikona/stan pokazuje sesję inną niż main; pozostaje stabilne do jej zakończenia.
- Uruchom main, gdy inna sesja jest aktywna: ikona natychmiast przełącza się na main.
- Szybkie serie narzędzi: upewnij się, że odznaka nie migocze (okres karencji TTL przy wynikach narzędzi).
- Wiersz kondycji pojawia się ponownie, gdy wszystkie sesje są bezczynne.
## Powiązane
- [Aplikacja macOS](/pl/platforms/macos)
- [aplikacja macOS](/pl/platforms/macos)
- [Ikona paska menu](/pl/platforms/mac/icon)

955
docs/pl/plugins/codex-harness.md
View File

File diff suppressed because it is too large Load Diff

152
docs/pl/plugins/dependency-resolution.md Normal file
View File

@ -0,0 +1,152 @@
---
read_when:
- Debugujesz naprawę zależności środowiska uruchomieniowego dołączonego Plugin
- Zmieniasz zachowanie uruchamiania Plugin, narzędzia doctor lub instalacji menedżera pakietów
- Utrzymujesz spakowane instalacje OpenClaw lub dołączone manifesty Pluginów
sidebarTitle: Dependencies
summary: Jak OpenClaw planuje, przygotowuje i naprawia zależności środowiska uruchomieniowego dołączonych Pluginów
title: Rozwiązywanie zależności Pluginu
x-i18n:
generated_at: "2026-05-01T10:01:28Z"
model: gpt-5.5
provider: openai
source_hash: e09245c2b7e2f1fb2a61d64f0f9dc77e7df7da58fd71608c391e3865345b7bc9
source_path: plugins/dependency-resolution.md
workflow: 16
---
OpenClaw nie instaluje całego drzewa zależności każdej dołączonej wtyczki podczas instalacji pakietu. Najpierw wyprowadza efektywny plan wtyczek z konfiguracji i metadanych wtyczek, a następnie przygotowuje zależności uruchomieniowe tylko dla dołączonych wtyczek należących do OpenClaw, które plan może faktycznie załadować.
Ta strona opisuje spakowane zależności uruchomieniowe dołączonych wtyczek OpenClaw. Wtyczki firm trzecich i niestandardowe ścieżki wtyczek nadal używają jawnych poleceń instalacji wtyczek, takich jak `openclaw plugins install` i `openclaw plugins update`.
## Podział odpowiedzialności
OpenClaw odpowiada za plan i zasady:
- które wtyczki są aktywne dla tej konfiguracji
- które katalogi główne zależności są zapisywalne lub tylko do odczytu
- kiedy naprawa jest dozwolona
- które identyfikatory wtyczek są przygotowywane do uruchomienia
- końcowe kontrole przed importem modułów uruchomieniowych wtyczek
Menedżer pakietów odpowiada za zbieżność zależności:
- rozwiązywanie grafu pakietów
- obsługę zależności produkcyjnych, opcjonalnych i równorzędnych
- układ `node_modules`
- integralność pakietów
- metadane blokady i instalacji
W praktyce OpenClaw powinien zdecydować, co musi istnieć. `pnpm` lub `npm` powinny sprawić, aby system plików odpowiadał tej decyzji.
OpenClaw odpowiada również za blokadę koordynacji dla każdego katalogu głównego instalacji. Menedżery pakietów chronią własną transakcję instalacji, ale nie serializują zapisów manifestu OpenClaw, kopiowania/zmiany nazwy izolowanego etapu, końcowej walidacji ani importu wtyczki względem innego procesu Gateway, doctor lub CLI dotykającego tego samego katalogu głównego zależności uruchomieniowych.
## Efektywny plan wtyczek
Efektywny plan wtyczek jest wyprowadzany z konfiguracji oraz wykrytych metadanych wtyczek. Te dane wejściowe mogą aktywować zależności uruchomieniowe dołączonych wtyczek:
- `plugins.entries.<id>.enabled`
- `plugins.allow`, `plugins.deny` i `plugins.enabled`
- starsza konfiguracja kanału, taka jak `channels.telegram.enabled`
- skonfigurowani dostawcy, modele lub odwołania do zaplecza CLI, które wymagają wtyczki
- domyślne wartości dołączonego manifestu, takie jak `enabledByDefault`
- indeks zainstalowanych wtyczek i metadane dołączonego manifestu
Jawne wyłączenie ma pierwszeństwo. Wyłączona wtyczka, odrzucony identyfikator wtyczki, wyłączony system wtyczek lub wyłączony kanał nie uruchamiają naprawy zależności uruchomieniowych. Sam utrwalony stan uwierzytelniania również nie aktywuje dołączonego kanału ani dostawcy.
Plan wtyczek jest stabilnym wejściem. Wygenerowana materializacja zależności jest wyjściem tego planu.
## Przepływ uruchamiania
Uruchomienie Gateway analizuje konfigurację i buduje tabelę wyszukiwania wtyczek startowych przed załadowaniem modułów uruchomieniowych wtyczek. Następnie uruchomienie przygotowuje zależności uruchomieniowe tylko dla `startupPluginIds` wybranych przez ten plan.
W instalacjach pakietowych przygotowanie zależności jest dozwolone przed importem wtyczek. Po przygotowaniu loader środowiska uruchomieniowego importuje wtyczki startowe z wyłączoną naprawą instalacji; w tym momencie brak materializacji zależności jest traktowany jako błąd ładowania, a nie kolejna pętla naprawy.
Gdy przygotowanie zależności startowych jest odroczone do czasu po powiązaniu HTTP, gotowość Gateway pozostaje zablokowana z powodu `plugin-runtime-deps`, dopóki zależności wybranych wtyczek startowych nie zostaną zmaterializowane, a środowisko uruchomieniowe wtyczek startowych nie zostanie załadowane.
## Kiedy działa naprawa
Naprawa zależności uruchomieniowych powinna zostać uruchomiona, gdy spełniony jest jeden z tych warunków:
- efektywny plan wtyczek zmienił się i dodaje dołączone wtyczki wymagające zależności uruchomieniowych
- wygenerowany manifest zależności nie odpowiada już efektywnemu planowi
- oczekiwane znaczniki zainstalowanych pakietów są brakujące lub niekompletne
- zażądano `openclaw doctor --fix` lub `openclaw plugins deps --repair`
Naprawa zależności uruchomieniowych nie powinna być uruchamiana tylko dlatego, że OpenClaw wystartował. Normalne uruchomienie z niezmienionym planem i kompletną materializacją zależności powinno pominąć pracę menedżera pakietów.
Polecenia edytujące konfigurację, włączające wtyczki lub naprawiające ustalenia doctor mogą raz wejść w tryb planu wtyczek, zmaterializować nowo wymagane dołączone zależności, a następnie wrócić do normalnego przepływu polecenia. Lokalne `openclaw onboard` i `openclaw configure` robią to automatycznie po pomyślnym zapisaniu konfiguracji, aby następne uruchomienie Gateway nie odkryło brakujących pakietów dołączonych wtyczek już po rozpoczęciu startu. Zdalne onboarding/configure pozostaje tylko do odczytu dla lokalnych zależności uruchomieniowych.
## Reguła gorącego przeładowania
Ścieżki gorącego przeładowania, które mogą zmienić aktywne wtyczki, muszą wrócić przez tryb planu wtyczek przed załadowaniem środowiska uruchomieniowego wtyczki. Przeładowanie powinno porównać nowy efektywny plan wtyczek z poprzednim, przygotować brakujące zależności dla nowo aktywnych dołączonych wtyczek, a następnie załadować lub zrestartować dotknięte środowisko uruchomieniowe.
Jeśli przeładowanie konfiguracji nie zmienia efektywnego planu wtyczek, nie powinno naprawiać dołączonych zależności uruchomieniowych.
## Wykonanie menedżera pakietów
OpenClaw zapisuje wygenerowany manifest instalacji dla wybranych dołączonych zależności uruchomieniowych i uruchamia menedżera pakietów w katalogu głównym instalacji zależności uruchomieniowych. Preferuje `pnpm`, gdy jest dostępny, i wraca do dostarczanego z Node runnera `npm`.
Ścieżka `pnpm` używa zależności produkcyjnych, wyłącza skrypty cyklu życia, ignoruje workspace i utrzymuje magazyn wewnątrz katalogu głównego instalacji:
```bash
pnpm install \
--prod \
--ignore-scripts \
--ignore-workspace \
--config.frozen-lockfile=false \
--config.minimum-release-age=0 \
--config.store-dir=<install-root>/.openclaw-pnpm-store \
--config.node-linker=hoisted \
--config.virtual-store-dir=.pnpm
```
Zapasowa ścieżka `npm` używa bezpiecznego wrappera instalacji npm z zależnościami produkcyjnymi, wyłączonymi skryptami cyklu życia, wyłączonym trybem workspace, wyłączonym audytem, wyłączonym wyjściem fund, starszym zachowaniem zależności równorzędnych i włączonym wyjściem package-lock dla wygenerowanego katalogu głównego instalacji.
Po instalacji OpenClaw waliduje przygotowane drzewo zależności, zanim udostępni je katalogowi głównemu zależności uruchomieniowych. Izolowany etap jest kopiowany do katalogu głównego zależności uruchomieniowych i ponownie walidowany.
Cała sekcja naprawy/materializacji jest chroniona blokadą katalogu głównego instalacji. Bieżący właściciele blokady zapisują PID, czas startu procesu, gdy jest dostępny, oraz czas utworzenia. Starsze blokady bez dowodu czasu startu procesu lub czasu utworzenia są odzyskiwane wyłącznie na podstawie wieku systemu plików, więc blokady z ponownie użytym Docker PID 1 odzyskują się bez wygaszania zwykłych, długotrwałych bieżących instalacji wyłącznie na podstawie wieku.
## Katalogi główne instalacji
Instalacje pakietowe nie mogą modyfikować katalogów pakietów tylko do odczytu. OpenClaw może odczytywać katalogi główne zależności z warstw pakietowych, ale zapisuje wygenerowane zależności uruchomieniowe do zapisywalnego etapu, takiego jak:
- `OPENCLAW_PLUGIN_STAGE_DIR`
- `$STATE_DIRECTORY`
- `~/.openclaw/plugin-runtime-deps`
- `/var/lib/openclaw/plugin-runtime-deps` w instalacjach w stylu kontenerowym
Zapisywalny katalog główny jest końcowym celem materializacji. Starsze katalogi główne tylko do odczytu są zachowywane jako warstwy zgodności tylko wtedy, gdy są potrzebne.
Gdy aktualizacja pakietowego OpenClaw zmienia wersjonowany zapisywalny katalog główny, ale wybrany plan zależności dołączonych wtyczek nadal jest spełniony przez poprzedni przygotowany katalog główny, naprawa ponownie używa poprzedniego drzewa `node_modules` zamiast ponownie uruchamiać menedżera pakietów. Nowy wersjonowany katalog główny nadal otrzymuje własne aktualne lustro środowiska uruchomieniowego pakietu, więc kod wtyczki pochodzi z bieżącego pakietu OpenClaw, a niezmienione drzewa zależności są współdzielone między aktualizacjami. Ponowne użycie pomija poprzednie katalogi główne z aktywną blokadą zależności uruchomieniowych OpenClaw, więc nowy katalog główny nie łączy się z drzewem zależności, które inny proces Gateway, doctor lub CLI właśnie naprawia.
## Polecenia doctor i CLI
Użyj `plugins deps`, aby sprawdzić lub naprawić materializację zależności uruchomieniowych dołączonych wtyczek:
```bash
openclaw plugins deps
openclaw plugins deps --json
openclaw plugins deps --repair
openclaw plugins deps --prune
```
Użyj doctor, gdy stan zależności jest częścią szerszego stanu instalacji:
```bash
openclaw doctor
openclaw doctor --fix
```
`plugins deps` i doctor działają na należących do OpenClaw zależnościach uruchomieniowych dołączonych wtyczek wybranych przez efektywny plan wtyczek. Nie są poleceniami instalacji ani aktualizacji wtyczek firm trzecich.
## Rozwiązywanie problemów
Jeśli instalacja pakietowa zgłasza brakujące dołączone zależności uruchomieniowe:
1. Uruchom `openclaw plugins deps --json`, aby sprawdzić wybrany plan i brakujące pakiety.
2. Uruchom `openclaw plugins deps --repair` lub `openclaw doctor --fix`, aby naprawić zapisywalny etap zależności.
3. Jeśli katalog główny instalacji jest tylko do odczytu, ustaw `OPENCLAW_PLUGIN_STAGE_DIR` na zapisywalną ścieżkę i ponownie uruchom naprawę.
4. Zrestartuj Gateway po naprawie, jeśli brakująca zależność zablokowała ładowanie wtyczki startowej.
W checkoutach źródłowych instalacja workspace zwykle dostarcza zależności dołączonych wtyczek. Uruchom `pnpm install` w celu naprawy zależności źródłowych, zamiast używać naprawy pakietowych zależności uruchomieniowych jako pierwszego kroku.

795
docs/pl/plugins/google-meet.md
View File

File diff suppressed because it is too large Load Diff

295
docs/pl/plugins/sdk-provider-plugins.md
View File

@ -1,41 +1,41 @@
---
read_when:
- Tworzysz nowy Plugin dostawcy modeli
- Chcesz dodać do OpenClaw serwer proxy zgodny z OpenAI lub niestandardowy model LLM
- Musisz zrozumieć uwierzytelnianie dostawców, katalogi i punkty zaczepienia środowiska uruchomieniowego
- Tworzysz nowy Plugin dostawcy modelu
- Chcesz dodać do OpenClaw serwer proxy zgodny z OpenAI lub niestandardowy LLM
- Musisz rozumieć uwierzytelnianie dostawców, katalogi i hooki środowiska wykonawczego
sidebarTitle: Provider plugins
summary: Przewodnik krok po kroku dotyczący tworzenia Plugin dostawcy modeli dla OpenClaw
title: Tworzenie pluginów dostawców
title: Tworzenie Pluginów dostawców
x-i18n:
generated_at: "2026-04-30T10:09:31Z"
generated_at: "2026-05-01T10:01:38Z"
model: gpt-5.5
provider: openai
source_hash: 1404594fe1d1e11a612f903512c1002c8f3a804dee53d4204457b534eae93381
source_hash: 3f9d721673bdfef0b9c1979b4b8b4c86f19d114374d6b941facb928c3574cd1b
source_path: plugins/sdk-provider-plugins.md
workflow: 16
---
Ten przewodnik pokazuje, jak zbudować Plugin dostawcy, który dodaje dostawcę modeli
Ten przewodnik omawia tworzenie Pluginu dostawcy, który dodaje dostawcę modelu
(LLM) do OpenClaw. Na końcu będziesz mieć dostawcę z katalogiem modeli,
uwierzytelnianiem kluczem API i dynamicznym rozpoznawaniem modeli.
<Info>
Jeśli nie masz jeszcze za sobą tworzenia żadnego Plugin OpenClaw, najpierw przeczytaj
Jeśli wcześniej nie zbudowałeś żadnego Pluginu OpenClaw, najpierw przeczytaj
[Pierwsze kroki](/pl/plugins/building-plugins), aby poznać podstawową strukturę
pakietu i konfigurację manifestu.
</Info>
<Tip>
Plugin dostawcy dodają modele do standardowej pętli inferencji OpenClaw. Jeśli model
musi działać przez natywnego demona agenta, który zarządza wątkami, compaction lub
zdarzeniami narzędzi, połącz dostawcę z [wiązką agenta](/pl/plugins/sdk-agent-harness)
zamiast umieszczać szczegóły protokołu demona w core.
Pluginy dostawców dodają modele do normalnej pętli inferencji OpenClaw. Jeśli model
musi działać przez natywnego demona agenta, który zarządza wątkami, Compaction lub
zdarzeniami narzędzi, połącz dostawcę z [uprzężą agenta](/pl/plugins/sdk-agent-harness)
zamiast umieszczać szczegóły protokołu demona w rdzeniu.
</Tip>
## Przewodnik
## Przewodnik krok po kroku
<Steps>
<Step title="Package and manifest">
<Step title="Pakiet i manifest">
<CodeGroup>
```json package.json
{
@ -94,16 +94,16 @@ uwierzytelnianiem kluczem API i dynamicznym rozpoznawaniem modeli.
</CodeGroup>
Manifest deklaruje `providerAuthEnvVars`, aby OpenClaw mógł wykrywać
dane uwierzytelniające bez ładowania runtime Twojego Plugin. Dodaj `providerAuthAliases`,
gdy wariant dostawcy powinien ponownie używać uwierzytelniania z identyfikatora innego dostawcy. `modelSupport`
jest opcjonalne i pozwala OpenClaw automatycznie ładować Twój Plugin dostawcy ze skróconych
identyfikatorów modeli, takich jak `acme-large`, zanim pojawią się hooki runtime. Jeśli publikujesz
poświadczenia bez ładowania środowiska uruchomieniowego Pluginu. Dodaj `providerAuthAliases`,
gdy wariant dostawcy powinien ponownie używać uwierzytelniania identyfikatora innego dostawcy. `modelSupport`
jest opcjonalne i pozwala OpenClaw automatycznie ładować Plugin dostawcy ze skróconych
identyfikatorów modeli, takich jak `acme-large`, zanim będą istnieć haki środowiska uruchomieniowego. Jeśli publikujesz
dostawcę w ClawHub, te pola `openclaw.compat` i `openclaw.build`
są wymagane w `package.json`.
</Step>
<Step title="Register the provider">
<Step title="Zarejestruj dostawcę">
Minimalny dostawca potrzebuje `id`, `label`, `auth` i `catalog`:
```typescript index.ts
@ -175,7 +175,7 @@ uwierzytelnianiem kluczem API i dynamicznym rozpoznawaniem modeli.
});
```
To jest działający dostawca. Użytkownicy mogą teraz uruchomić
To działający dostawca. Użytkownicy mogą teraz uruchomić
`openclaw onboard --acme-ai-api-key <key>` i wybrać
`acme-ai/acme-large` jako swój model.
@ -198,11 +198,11 @@ uwierzytelnianiem kluczem API i dynamicznym rozpoznawaniem modeli.
```
`input` przepisuje końcowy prompt systemowy i treść wiadomości tekstowej przed
transportem. `output` przepisuje delty tekstu asystenta i końcowy tekst, zanim
OpenClaw przeanalizuje własne znaczniki sterujące lub dostarczanie kanału.
transportem. `output` przepisuje delty tekstu asystenta i tekst końcowy, zanim
OpenClaw przeanalizuje własne znaczniki sterujące lub dostarczanie kanałowe.
W przypadku dostawców dołączanych do pakietu, którzy rejestrują tylko jednego dostawcę tekstowego z
uwierzytelnianiem kluczem API oraz pojedynczym runtime opartym na katalogu, preferuj węższy
Dla dołączonych dostawców, którzy rejestrują tylko jednego dostawcę tekstu z uwierzytelnianiem
kluczem API oraz pojedynczym środowiskiem uruchomieniowym opartym na katalogu, preferuj węższy
helper `defineSingleProviderPluginEntry(...)`:
```typescript
@ -245,13 +245,13 @@ uwierzytelnianiem kluczem API i dynamicznym rozpoznawaniem modeli.
`buildProvider` to ścieżka katalogu live używana, gdy OpenClaw może rozpoznać rzeczywiste
uwierzytelnianie dostawcy. Może wykonywać wykrywanie specyficzne dla dostawcy. Używaj
`buildStaticProvider` tylko dla wierszy offline, które można bezpiecznie pokazać przed skonfigurowaniem
uwierzytelniania; nie może wymagać danych uwierzytelniających ani wykonywać żądań sieciowych.
`buildStaticProvider` tylko do wierszy offline, które można bezpiecznie pokazać przed skonfigurowaniem
uwierzytelniania; nie może ona wymagać poświadczeń ani wykonywać żądań sieciowych.
Widok `models list --all` w OpenClaw obecnie wykonuje katalogi statyczne
tylko dla dołączanych Plugin dostawców, z pustą konfiguracją, pustym env i bez
ścieżek agenta/workspace.
tylko dla dołączonych Pluginów dostawców, z pustą konfiguracją, pustym środowiskiem i bez
ścieżek agenta/przestrzeni roboczej.
Jeśli Twój przepływ uwierzytelniania musi też aktualizować `models.providers.*`, aliasy i
Jeśli Twój przepływ uwierzytelniania musi również poprawiać `models.providers.*`, aliasy i
domyślny model agenta podczas onboardingu, użyj helperów presetów z
`openclaw/plugin-sdk/provider-onboard`. Najwęższe helpery to
`createDefaultModelPresetAppliers(...)`,
@ -259,16 +259,16 @@ uwierzytelnianiem kluczem API i dynamicznym rozpoznawaniem modeli.
`createModelCatalogPresetAppliers(...)`.
Gdy natywny endpoint dostawcy obsługuje strumieniowane bloki użycia w
standardowym transporcie `openai-completions`, preferuj współdzielone helpery katalogu w
`openclaw/plugin-sdk/provider-catalog-shared` zamiast kodować na sztywno
sprawdzenia identyfikatorów dostawców. `supportsNativeStreamingUsageCompat(...)` i
`applyProviderNativeStreamingUsageCompat(...)` wykrywają obsługę z mapy
możliwości endpointu, dzięki czemu natywne endpointy w stylu Moonshot/DashScope nadal
włączają się nawet wtedy, gdy Plugin używa niestandardowego identyfikatora dostawcy.
normalnym transporcie `openai-completions`, preferuj współdzielone helpery katalogu z
`openclaw/plugin-sdk/provider-catalog-shared` zamiast hardkodować
sprawdzenia identyfikatora dostawcy. `supportsNativeStreamingUsageCompat(...)` i
`applyProviderNativeStreamingUsageCompat(...)` wykrywają obsługę z
mapy możliwości endpointu, dzięki czemu natywne endpointy w stylu Moonshot/DashScope nadal
włączają tę funkcję nawet wtedy, gdy Plugin używa niestandardowego identyfikatora dostawcy.
</Step>
<Step title="Add dynamic model resolution">
<Step title="Dodaj dynamiczne rozpoznawanie modelu">
Jeśli Twój dostawca akceptuje dowolne identyfikatory modeli (jak proxy lub router),
dodaj `resolveDynamicModel`:
@ -291,17 +291,17 @@ uwierzytelnianiem kluczem API i dynamicznym rozpoznawaniem modeli.
});
```
Jeśli rozpoznanie wymaga wywołania sieciowego, użyj `prepareDynamicModel` do asynchronicznego
rozgrzania — `resolveDynamicModel` uruchomi się ponownie po jego zakończeniu.
Jeśli rozpoznawanie wymaga wywołania sieciowego, użyj `prepareDynamicModel` do asynchronicznego
rozgrzewania — `resolveDynamicModel` uruchomi się ponownie po jego zakończeniu.
</Step>
<Step title="Add runtime hooks (as needed)">
Większość dostawców potrzebuje tylko `catalog` + `resolveDynamicModel`. Dodawaj hooki
stopniowo, gdy Twój dostawca ich wymaga.
<Step title="Dodaj haki środowiska uruchomieniowego (w razie potrzeby)">
Większość dostawców potrzebuje tylko `catalog` + `resolveDynamicModel`. Dodawaj haki
stopniowo, gdy dostawca ich wymaga.
Współdzielone buildery helperów obejmują teraz najczęstsze rodziny zgodności
replay/narzędzi, więc Plugin zwykle nie muszą ręcznie podłączać każdego hooka po kolei:
Współdzielone buildery helperów obejmują teraz najczęstsze rodziny zgodności replay/narzędzi,
więc Pluginy zwykle nie muszą ręcznie podłączać każdego haka po kolei:
```typescript
import { buildProviderReplayFamilyHooks } from "openclaw/plugin-sdk/provider-model-shared";
@ -321,43 +321,43 @@ uwierzytelnianiem kluczem API i dynamicznym rozpoznawaniem modeli.
});
```
Rodziny replay dostępne obecnie:
| Rodzina | Co podłącza | Przykłady dołączone do pakietu |
| --- | --- | --- |
| `openai-compatible` | Współdzielona polityka replay w stylu OpenAI dla transportów zgodnych z OpenAI, w tym sanitacja identyfikatorów wywołań narzędzi, poprawki kolejności assistant-first i ogólna walidacja tur Gemini tam, gdzie transport jej potrzebuje | `moonshot`, `ollama`, `xai`, `zai` |
| `anthropic-by-model` | Polityka replay świadoma Claude wybierana przez `modelId`, dzięki czemu transporty komunikatów Anthropic otrzymują czyszczenie bloków myślenia specyficzne dla Claude tylko wtedy, gdy rozpoznany model faktycznie jest identyfikatorem Claude | `amazon-bedrock`, `anthropic-vertex` |
| `google-gemini` | Natywna polityka replay Gemini oraz sanitacja bootstrap replay i tryb oznakowanego wyjścia rozumowania | `google`, `google-gemini-cli` |
| `passthrough-gemini` | Sanitacja podpisów myśli Gemini dla modeli Gemini działających przez transporty proxy zgodne z OpenAI; nie włącza natywnej walidacji replay Gemini ani przepisywania bootstrap | `openrouter`, `kilocode`, `opencode`, `opencode-go` |
| `hybrid-anthropic-openai` | Polityka hybrydowa dla dostawców, którzy łączą powierzchnie modeli komunikatów Anthropic i zgodne z OpenAI w jednym Plugin; opcjonalne porzucanie bloków myślenia tylko dla Claude pozostaje ograniczone do strony Anthropic | `minimax` |
Rodziny strumieni dostępne obecnie:
Dostępne dziś rodziny replay:
| Rodzina | Co podłącza | Dołączone przykłady |
| --- | --- | --- |
| `google-thinking` | Normalizacja ładunku myślenia Gemini na współdzielonej ścieżce strumienia | `google`, `google-gemini-cli` |
| `kilocode-thinking` | Opakowanie rozumowania Kilo na współdzielonej ścieżce strumienia proxy, z pomijaniem wstrzykniętego myślenia dla `kilo/auto` i nieobsługiwanych identyfikatorów rozumowania proxy | `kilocode` |
| `moonshot-thinking` | Mapowanie natywnego binarnego ładunku myślenia Moonshot z konfiguracji + poziomu `/think` | `moonshot` |
| `openai-compatible` | Współdzielona polityka replay w stylu OpenAI dla transportów zgodnych z OpenAI, obejmująca oczyszczanie identyfikatorów wywołań narzędzi, poprawki kolejności z asystentem jako pierwszym oraz ogólną walidację tur Gemini tam, gdzie transport jej potrzebuje | `moonshot`, `ollama`, `xai`, `zai` |
| `anthropic-by-model` | Polityka replay świadoma Claude wybierana przez `modelId`, dzięki czemu transporty wiadomości Anthropic otrzymują czyszczenie bloków myślenia specyficzne dla Claude tylko wtedy, gdy rozpoznany model jest rzeczywiście identyfikatorem Claude | `amazon-bedrock`, `anthropic-vertex` |
| `google-gemini` | Natywna polityka replay Gemini oraz oczyszczanie bootstrap replay i tryb oznakowanego wyjścia rozumowania | `google`, `google-gemini-cli` |
| `passthrough-gemini` | Oczyszczanie sygnatur myśli Gemini dla modeli Gemini działających przez transporty proxy zgodne z OpenAI; nie włącza natywnej walidacji replay Gemini ani przepisywania bootstrap | `openrouter`, `kilocode`, `opencode`, `opencode-go` |
| `hybrid-anthropic-openai` | Polityka hybrydowa dla dostawców, którzy mieszają powierzchnie modeli wiadomości Anthropic i zgodne z OpenAI w jednym Pluginie; opcjonalne usuwanie bloków myślenia tylko dla Claude pozostaje ograniczone do strony Anthropic | `minimax` |
Dostępne dziś rodziny strumieni:
| Rodzina | Co podłącza | Dołączone przykłady |
| --- | --- | --- |
| `google-thinking` | Normalizacja ładunku rozumowania Gemini na współdzielonej ścieżce strumienia | `google`, `google-gemini-cli` |
| `kilocode-thinking` | Otoczka rozumowania Kilo na współdzielonej ścieżce strumienia proxy, z pomijaniem wstrzykniętego rozumowania dla `kilo/auto` i nieobsługiwanych identyfikatorów rozumowania proxy | `kilocode` |
| `moonshot-thinking` | Mapowanie binarnego ładunku natywnego rozumowania Moonshot z konfiguracji + poziomu `/think` | `moonshot` |
| `minimax-fast-mode` | Przepisywanie modelu trybu szybkiego MiniMax na współdzielonej ścieżce strumienia | `minimax`, `minimax-portal` |
| `openai-responses-defaults` | Współdzielone natywne opakowania OpenAI/Codex Responses: nagłówki atrybucji, `/fast`/`serviceTier`, szczegółowość tekstu, natywne wyszukiwanie w sieci Codex, kształtowanie ładunku zgodne z rozumowaniem oraz zarządzanie kontekstem Responses | `openai`, `openai-codex` |
| `openrouter-thinking` | Opakowanie rozumowania OpenRouter dla tras proxy, z centralną obsługą pominięć nieobsługiwanego modelu/`auto` | `openrouter` |
| `tool-stream-default-on` | Domyślnie włączone opakowanie `tool_stream` dla dostawców takich jak Z.AI, którzy chcą strumieniowania narzędzi, chyba że zostanie jawnie wyłączone | `zai` |
| `openai-responses-defaults` | Współdzielone natywne otoczki OpenAI/Codex Responses: nagłówki atrybucji, `/fast`/`serviceTier`, szczegółowość tekstu, natywne wyszukiwanie w sieci Codex, kształtowanie ładunku zgodności rozumowania i zarządzanie kontekstem Responses | `openai`, `openai-codex` |
| `openrouter-thinking` | Otoczka rozumowania OpenRouter dla tras proxy, z centralną obsługą pomijania nieobsługiwanych modeli/`auto` | `openrouter` |
| `tool-stream-default-on` | Domyślnie włączona otoczka `tool_stream` dla dostawców takich jak Z.AI, którzy chcą strumieniowania narzędzi, chyba że zostanie jawnie wyłączone | `zai` |
<Accordion title="Punkty integracji SDK zasilające konstruktory rodzin">
Każdy konstruktor rodziny składa się z publicznych pomocników niższego poziomu eksportowanych z tego samego pakietu, po które możesz sięgnąć, gdy dostawca musi odejść od wspólnego wzorca:
Każdy konstruktor rodziny składa się z publicznych helperów niższego poziomu eksportowanych z tego samego pakietu, po które możesz sięgnąć, gdy dostawca musi wyjść poza wspólny wzorzec:
- `openclaw/plugin-sdk/provider-model-shared` — `ProviderReplayFamily`, `buildProviderReplayFamilyHooks(...)` oraz surowe konstruktory odtwarzania (`buildOpenAICompatibleReplayPolicy`, `buildAnthropicReplayPolicyForModel`, `buildGoogleGeminiReplayPolicy`, `buildHybridAnthropicOrOpenAIReplayPolicy`). Eksportuje też pomocniki odtwarzania Gemini (`sanitizeGoogleGeminiReplayHistory`, `resolveTaggedReasoningOutputMode`) oraz pomocniki endpointu/modelu (`resolveProviderEndpoint`, `normalizeProviderId`, `normalizeGooglePreviewModelId`, `normalizeNativeXaiModelId`).
- `openclaw/plugin-sdk/provider-stream` — `ProviderStreamFamily`, `buildProviderStreamFamilyHooks(...)`, `composeProviderStreamWrappers(...)`, a także współdzielone opakowania OpenAI/Codex (`createOpenAIAttributionHeadersWrapper`, `createOpenAIFastModeWrapper`, `createOpenAIServiceTierWrapper`, `createOpenAIResponsesContextManagementWrapper`, `createCodexNativeWebSearchWrapper`), zgodne z OpenAI opakowanie DeepSeek V4 (`createDeepSeekV4OpenAICompatibleThinkingWrapper`), czyszczenie wstępnego wypełnienia myślenia Anthropic Messages (`createAnthropicThinkingPrefillPayloadWrapper`) oraz współdzielone opakowania proxy/dostawców (`createOpenRouterWrapper`, `createToolStreamWrapper`, `createMinimaxFastModeWrapper`).
- `openclaw/plugin-sdk/provider-tools` — `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks("gemini")`, bazowe pomocniki schematów Gemini (`normalizeGeminiToolSchemas`, `inspectGeminiToolSchemas`) oraz pomocniki zgodności xAI (`resolveXaiModelCompatPatch()`, `applyXaiModelCompat(model)`). Dołączony Plugin xAI używa `normalizeResolvedModel` + `contributeResolvedModelCompat` razem z nimi, aby reguły xAI pozostały własnością dostawcy.
- `openclaw/plugin-sdk/provider-model-shared` — `ProviderReplayFamily`, `buildProviderReplayFamilyHooks(...)` oraz surowe konstruktory odtwarzania (`buildOpenAICompatibleReplayPolicy`, `buildAnthropicReplayPolicyForModel`, `buildGoogleGeminiReplayPolicy`, `buildHybridAnthropicOrOpenAIReplayPolicy`). Eksportuje też helpery odtwarzania Gemini (`sanitizeGoogleGeminiReplayHistory`, `resolveTaggedReasoningOutputMode`) oraz helpery punktów końcowych/modeli (`resolveProviderEndpoint`, `normalizeProviderId`, `normalizeGooglePreviewModelId`, `normalizeNativeXaiModelId`).
- `openclaw/plugin-sdk/provider-stream` — `ProviderStreamFamily`, `buildProviderStreamFamilyHooks(...)`, `composeProviderStreamWrappers(...)`, a także współdzielone otoczki OpenAI/Codex (`createOpenAIAttributionHeadersWrapper`, `createOpenAIFastModeWrapper`, `createOpenAIServiceTierWrapper`, `createOpenAIResponsesContextManagementWrapper`, `createCodexNativeWebSearchWrapper`), zgodna z OpenAI otoczka DeepSeek V4 (`createDeepSeekV4OpenAICompatibleThinkingWrapper`), czyszczenie wstępnego wypełnienia rozumowania Anthropic Messages (`createAnthropicThinkingPrefillPayloadWrapper`) oraz współdzielone otoczki proxy/dostawców (`createOpenRouterWrapper`, `createToolStreamWrapper`, `createMinimaxFastModeWrapper`).
- `openclaw/plugin-sdk/provider-tools` — `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks("gemini")`, bazowe helpery schematów Gemini (`normalizeGeminiToolSchemas`, `inspectGeminiToolSchemas`) oraz helpery zgodności xAI (`resolveXaiModelCompatPatch()`, `applyXaiModelCompat(model)`). Dołączony plugin xAI używa z nimi `normalizeResolvedModel` + `contributeResolvedModelCompat`, aby reguły xAI pozostawały własnością dostawcy.
Niektóre pomocniki strumienia celowo pozostają lokalne dla dostawcy. `@openclaw/anthropic-provider` trzyma `wrapAnthropicProviderStream`, `resolveAnthropicBetas`, `resolveAnthropicFastMode`, `resolveAnthropicServiceTier` oraz niższopoziomowe konstruktory opakowań Anthropic we własnym publicznym punkcie integracji `api.ts` / `contract-api.ts`, ponieważ kodują obsługę bety OAuth Claude i bramkowanie `context1m`. Plugin xAI podobnie trzyma natywne kształtowanie Responses xAI we własnym `wrapStreamFn` (aliasy `/fast`, domyślny `tool_stream`, czyszczenie nieobsługiwanych narzędzi strict-tool, usuwanie ładunku rozumowania specyficzne dla xAI).
Niektóre helpery strumienia celowo pozostają lokalne dla dostawcy. `@openclaw/anthropic-provider` utrzymuje `wrapAnthropicProviderStream`, `resolveAnthropicBetas`, `resolveAnthropicFastMode`, `resolveAnthropicServiceTier` oraz niższopoziomowe konstruktory otoczek Anthropic we własnym publicznym punkcie integracji `api.ts` / `contract-api.ts`, ponieważ kodują obsługę beta Claude OAuth i bramkowanie `context1m`. Plugin xAI podobnie utrzymuje natywne kształtowanie xAI Responses we własnym `wrapStreamFn` (aliasy `/fast`, domyślne `tool_stream`, czyszczenie nieobsługiwanych narzędzi strict-tool, usuwanie ładunku rozumowania specyficzne dla xAI).
Ten sam wzorzec katalogu głównego pakietu obsługuje też `@openclaw/openai-provider` (konstruktory dostawców, pomocniki modeli domyślnych, konstruktory dostawcy czasu rzeczywistego) oraz `@openclaw/openrouter-provider` (konstruktor dostawcy oraz pomocniki onboardingu/konfiguracji).
Ten sam wzorzec katalogu głównego pakietu wspiera też `@openclaw/openai-provider` (konstruktory dostawców, helpery modeli domyślnych, konstruktory dostawcy realtime) oraz `@openclaw/openrouter-provider` (konstruktor dostawcy plus helpery onboardingu/konfiguracji).
</Accordion>
<Tabs>
<Tab title="Wymiana tokenu">
Dla dostawców, którzy potrzebują wymiany tokenu przed każdym wywołaniem inferencji:
Dla dostawców, którzy wymagają wymiany tokenu przed każdym wywołaniem inferencji:
```typescript
prepareRuntimeAuth: async (ctx) => {
@ -371,7 +371,7 @@ uwierzytelnianiem kluczem API i dynamicznym rozpoznawaniem modeli.
```
</Tab>
<Tab title="Niestandardowe nagłówki">
Dla dostawców, którzy potrzebują niestandardowych nagłówków żądania lub modyfikacji treści:
Dla dostawców, którzy wymagają niestandardowych nagłówków żądania lub modyfikacji treści:
```typescript
// wrapStreamFn returns a StreamFn derived from ctx.streamFn
@ -389,8 +389,8 @@ uwierzytelnianiem kluczem API i dynamicznym rozpoznawaniem modeli.
```
</Tab>
<Tab title="Natywna tożsamość transportu">
Dla dostawców, którzy potrzebują natywnych nagłówków żądania/sesji lub metadanych w
ogólnych transportach HTTP lub WebSocket:
Dla dostawców, którzy wymagają natywnych nagłówków żądania/sesji lub metadanych w
generycznych transportach HTTP albo WebSocket:
```typescript
resolveTransportTurnState: (ctx) => ({
@ -427,77 +427,77 @@ uwierzytelnianiem kluczem API i dynamicznym rozpoznawaniem modeli.
<Accordion title="Wszystkie dostępne hooki dostawcy">
OpenClaw wywołuje hooki w tej kolejności. Większość dostawców używa tylko 2-3:
Pola dostawcy wyłącznie zgodnościowe, których OpenClaw już nie wywołuje, takie jak
Pola dostawcy służące wyłącznie zgodności, których OpenClaw już nie wywołuje, takie jak
`ProviderPlugin.capabilities` i `suppressBuiltInModel`, nie są tutaj wymienione.
| # | Hook | Kiedy używać |
| --- | --- | --- |
| 1 | `catalog` | Katalog modeli lub domyślne wartości bazowego URL |
| 2 | `applyConfigDefaults` | Globalne wartości domyślne będące własnością dostawcy podczas materializacji konfiguracji |
| 3 | `normalizeModelId` | Czyszczenie aliasów identyfikatorów modeli legacy/preview przed wyszukiwaniem |
| 4 | `normalizeTransport` | Czyszczenie `api` / `baseUrl` rodziny dostawcy przed ogólnym złożeniem modelu |
| 1 | `catalog` | Katalog modeli albo domyślne wartości bazowego URL-a |
| 2 | `applyConfigDefaults` | Globalne wartości domyślne należące do dostawcy podczas materializacji konfiguracji |
| 3 | `normalizeModelId` | Czyszczenie aliasów starszych/podglądowych identyfikatorów modeli przed wyszukiwaniem |
| 4 | `normalizeTransport` | Czyszczenie `api` / `baseUrl` rodziny dostawcy przed generycznym składaniem modelu |
| 5 | `normalizeConfig` | Normalizacja konfiguracji `models.providers.<id>` |
| 6 | `applyNativeStreamingUsageCompat` | Przepisywanie zgodności natywnego użycia strumieniowego dla dostawców konfiguracji |
| 7 | `resolveConfigApiKey` | Rozwiązywanie uwierzytelniania markerem env będące własnością dostawcy |
| 8 | `resolveSyntheticAuth` | Syntetyczne uwierzytelnianie lokalne/self-hosted lub oparte na konfiguracji |
| 9 | `shouldDeferSyntheticProfileAuth` | Obniżanie syntetycznych placeholderów przechowywanego profilu za uwierzytelnianiem env/konfiguracji |
| 10 | `resolveDynamicModel` | Akceptowanie dowolnych identyfikatorów modeli upstream |
| 11 | `prepareDynamicModel` | Asynchroniczne pobranie metadanych przed rozwiązywaniem |
| 12 | `normalizeResolvedModel` | Przepisywanie transportu przed runnerem |
| 6 | `applyNativeStreamingUsageCompat` | Natywne przepisywanie zgodności użycia strumieniowego dla dostawców konfiguracji |
| 7 | `resolveConfigApiKey` | Rozwiązywanie uwierzytelniania znacznikami env należące do dostawcy |
| 8 | `resolveSyntheticAuth` | Syntetyczne uwierzytelnianie lokalne/samohostowane albo oparte na konfiguracji |
| 9 | `shouldDeferSyntheticProfileAuth` | Obniżenie priorytetu syntetycznych symboli zastępczych zapisanych profili za uwierzytelnianiem env/konfiguracyjnym |
| 10 | `resolveDynamicModel` | Akceptacja dowolnych nadrzędnych identyfikatorów modeli |
| 11 | `prepareDynamicModel` | Asynchroniczne pobieranie metadanych przed rozwiązaniem |
| 12 | `normalizeResolvedModel` | Przepisywanie transportu przed mechanizmem uruchamiającym |
| 13 | `contributeResolvedModelCompat` | Flagi zgodności dla modeli dostawcy za innym zgodnym transportem |
| 14 | `normalizeToolSchemas` | Czyszczenie schematów narzędzi będące własnością dostawcy przed rejestracją |
| 15 | `inspectToolSchemas` | Diagnostyka schematów narzędzi będąca własnością dostawcy |
| 16 | `resolveReasoningOutputMode` | Kontrakt oznaczonego vs natywnego wyjścia rozumowania |
| 14 | `normalizeToolSchemas` | Czyszczenie schematów narzędzi należące do dostawcy przed rejestracją |
| 15 | `inspectToolSchemas` | Diagnostyka schematów narzędzi należąca do dostawcy |
| 16 | `resolveReasoningOutputMode` | Kontrakt tagowanego vs natywnego wyjścia rozumowania |
| 17 | `prepareExtraParams` | Domyślne parametry żądania |
| 18 | `createStreamFn` | W pełni niestandardowy transport StreamFn |
| 19 | `wrapStreamFn` | Niestandardowe opakowania nagłówków/treści na normalnej ścieżce strumienia |
| 20 | `resolveTransportTurnState` | Natywne nagłówki/metadane per tura |
| 21 | `resolveWebSocketSessionPolicy` | Natywne nagłówki sesji WS/cool-down |
| 22 | `formatApiKey` | Niestandardowy kształt tokenu runtime |
| 19 | `wrapStreamFn` | Niestandardowe otoczki nagłówków/treści na standardowej ścieżce strumienia |
| 20 | `resolveTransportTurnState` | Natywne nagłówki/metadane na turę |
| 21 | `resolveWebSocketSessionPolicy` | Natywne nagłówki sesji WS/okres wyciszenia |
| 22 | `formatApiKey` | Niestandardowy kształt tokenu czasu wykonywania |
| 23 | `refreshOAuth` | Niestandardowe odświeżanie OAuth |
| 24 | `buildAuthDoctorHint` | Wskazówki naprawy uwierzytelniania |
| 25 | `matchesContextOverflowError` | Wykrywanie przepełnienia będące własnością dostawcy |
| 26 | `classifyFailoverReason` | Klasyfikacja limitu szybkości/przeciążenia będąca własnością dostawcy |
| 27 | `isCacheTtlEligible` | Bramkowanie TTL cache promptu |
| 28 | `buildMissingAuthMessage` | Niestandardowa wskazówka brakującego uwierzytelniania |
| 25 | `matchesContextOverflowError` | Wykrywanie przepełnienia należące do dostawcy |
| 26 | `classifyFailoverReason` | Klasyfikacja limitu żądań/przeciążenia należąca do dostawcy |
| 27 | `isCacheTtlEligible` | Bramkowanie TTL pamięci podręcznej promptów |
| 28 | `buildMissingAuthMessage` | Niestandardowa wskazówka o brakującym uwierzytelnieniu |
| 29 | `augmentModelCatalog` | Syntetyczne wiersze zgodności w przód |
| 30 | `resolveThinkingProfile` | Zestaw opcji `/think` specyficzny dla modelu |
| 31 | `isBinaryThinking` | Zgodność włączania/wyłączania binarnego myślenia |
| 31 | `isBinaryThinking` | Zgodność włączania/wyłączania binarnego rozumowania |
| 32 | `supportsXHighThinking` | Zgodność obsługi rozumowania `xhigh` |
| 33 | `resolveDefaultThinkingLevel` | Zgodność domyślnej polityki `/think` |
| 34 | `isModernModelRef` | Dopasowanie modeli live/smoke |
| 34 | `isModernModelRef` | Dopasowywanie modeli na żywo/dymnych |
| 35 | `prepareRuntimeAuth` | Wymiana tokenu przed inferencją |
| 36 | `resolveUsageAuth` | Niestandardowe parsowanie danych uwierzytelniających użycia |
| 37 | `fetchUsageSnapshot` | Niestandardowy endpoint użycia |
| 38 | `createEmbeddingProvider` | Adapter embeddingów będący własnością dostawcy dla pamięci/wyszukiwania |
| 39 | `buildReplayPolicy` | Niestandardowa polityka odtwarzania/Compaction transkrypcji |
| 40 | `sanitizeReplayHistory` | Przepisywanie odtwarzania specyficzne dla dostawcy po ogólnym czyszczeniu |
| 41 | `validateReplayTurns` | Ścisła walidacja tur odtwarzania przed osadzonym runnerem |
| 42 | `onModelSelected` | Callback po wyborze (np. telemetria) |
| 36 | `resolveUsageAuth` | Niestandardowe parsowanie poświadczeń użycia |
| 37 | `fetchUsageSnapshot` | Niestandardowy punkt końcowy użycia |
| 38 | `createEmbeddingProvider` | Adapter embeddingów należący do dostawcy dla pamięci/wyszukiwania |
| 39 | `buildReplayPolicy` | Niestandardowa polityka odtwarzania/kompaktowania transkrypcji |
| 40 | `sanitizeReplayHistory` | Przepisywanie odtwarzania specyficzne dla dostawcy po generycznym czyszczeniu |
| 41 | `validateReplayTurns` | Ścisła walidacja tur odtwarzania przed osadzonym mechanizmem uruchamiającym |
| 42 | `onModelSelected` | Wywołanie zwrotne po wyborze (np. telemetria) |
Notatki dotyczące fallbacku runtime:
Uwagi o zapasowych ścieżkach czasu wykonywania:
- `normalizeConfig` najpierw sprawdza dopasowanego dostawcę, a następnie inne pluginy dostawców obsługujące hooki, aż któryś rzeczywiście zmieni konfigurację. Jeśli żaden hook dostawcy nie przepisze obsługiwanego wpisu konfiguracji z rodziny Google, dołączony normalizator konfiguracji Google nadal zostanie zastosowany.
- `resolveConfigApiKey` używa hooka dostawcy, gdy jest udostępniony. Dołączona ścieżka `amazon-bedrock` ma tutaj także wbudowany resolver markerów env AWS, mimo że samo uwierzytelnianie runtime Bedrock nadal używa domyślnego łańcucha AWS SDK.
- `resolveSystemPromptContribution` pozwala dostawcy wstrzyknąć wskazówki promptu systemowego świadome cache dla rodziny modeli. Preferuj go zamiast `before_prompt_build`, gdy zachowanie należy do jednego dostawcy/rodziny modeli i powinno zachować stabilny/dynamiczny podział cache.
- `normalizeConfig` sprawdza najpierw dopasowanego dostawcę, a potem inne pluginy dostawców obsługujące hooki, dopóki któryś faktycznie nie zmieni konfiguracji. Jeśli żaden hook dostawcy nie przepisze obsługiwanego wpisu konfiguracji z rodziny Google, dołączony normalizator konfiguracji Google nadal zostanie zastosowany.
- `resolveConfigApiKey` używa hooka dostawcy, gdy jest udostępniony. Dołączona ścieżka `amazon-bedrock` ma tutaj też wbudowany resolver znaczników env AWS, mimo że samo uwierzytelnianie runtime Bedrock nadal używa domyślnego łańcucha AWS SDK.
- `resolveSystemPromptContribution` pozwala dostawcy wstrzyknąć świadome pamięci podręcznej wskazówki promptu systemowego dla rodziny modeli. Preferuj je zamiast `before_prompt_build`, gdy zachowanie należy do jednego dostawcy/rodziny modeli i powinno zachować podział pamięci podręcznej na stabilną/dynamiczną część.
Szczegółowe opisy i rzeczywiste przykłady znajdziesz w [Wewnętrzne szczegóły: Hooki runtime dostawcy](/pl/plugins/architecture-internals#provider-runtime-hooks).
Szczegółowe opisy i rzeczywiste przykłady znajdziesz w [Wewnętrzne mechanizmy: hooki czasu wykonywania dostawcy](/pl/plugins/architecture-internals#provider-runtime-hooks).
</Accordion>
</Step>
<Step title="Dodaj dodatkowe możliwości (opcjonalnie)">
Plugin dostawcy może zarejestrować mowę, transkrypcję w czasie rzeczywistym, głos w czasie rzeczywistym, rozumienie mediów, generowanie obrazów, generowanie wideo, pobieranie z sieci
Plugin dostawcy może rejestrować mowę, transkrypcję w czasie rzeczywistym, głos w czasie rzeczywistym, rozumienie mediów, generowanie obrazów, generowanie wideo, pobieranie z sieci
i wyszukiwanie w sieci obok inferencji tekstowej. OpenClaw klasyfikuje to jako
Plugin **hybrid-capability** — zalecany wzorzec dla pluginów firmowych
(jeden Plugin na dostawcę). Zobacz
[Wewnętrzne szczegóły: Własność możliwości](/pl/plugins/architecture#capability-ownership-model).
plugin **hybrid-capability** — zalecany wzorzec dla pluginów firmowych
(jeden plugin na dostawcę). Zobacz
[Wewnętrzne mechanizmy: własność możliwości](/pl/plugins/architecture#capability-ownership-model).
Zarejestruj każdą możliwość w `register(api)` obok istniejącego
Zarejestruj każdą możliwość wewnątrz `register(api)` obok istniejącego
wywołania `api.registerProvider(...)`. Wybierz tylko potrzebne karty:
<Tabs>
<Tab title="Synteza mowy (TTS)">
<Tab title="Speech (TTS)">
```typescript
import {
assertOkOrThrowProviderError,
@ -532,15 +532,15 @@ uwierzytelnianiem kluczem API i dynamicznym rozpoznawaniem modeli.
});
```
Używaj `assertOkOrThrowProviderError(...)` przy błędach HTTP dostawcy, aby
Pluginy współdzieliły ograniczone odczyty treści błędów, parsowanie błędów JSON oraz
Użyj `assertOkOrThrowProviderError(...)` dla błędów HTTP dostawcy, aby
plugins współdzieliły ograniczone odczyty treści błędu, parsowanie błędów JSON oraz
sufiksy identyfikatorów żądań.
</Tab>
<Tab title="Transkrypcja w czasie rzeczywistym">
Preferuj `createRealtimeTranscriptionWebSocketSession(...)` — współdzielona
funkcja pomocnicza obsługuje przechwytywanie proxy, opóźnianie ponownego łączenia, opróżnianie przy zamykaniu, uzgadnianie gotowości,
kolejkowanie audio i diagnostykę zdarzeń zamknięcia. Twój Plugin
tylko mapuje zdarzenia z usługi nadrzędnej.
<Tab title="Realtime transcription">
Preferuj `createRealtimeTranscriptionWebSocketSession(...)` — współdzielony
helper obsługuje przechwytywanie proxy, opóźnienie ponownych połączeń, opróżnianie przy zamknięciu, uzgadnianie
gotowości, kolejkowanie audio oraz diagnostykę zdarzeń zamknięcia. Twój Plugin
tylko mapuje zdarzenia upstream.
```typescript
api.registerRealtimeTranscriptionProvider({
@ -580,11 +580,11 @@ uwierzytelnianiem kluczem API i dynamicznym rozpoznawaniem modeli.
Dostawcy wsadowego STT, którzy wysyłają wieloczęściowe audio metodą POST, powinni używać
`buildAudioTranscriptionFormData(...)` z
`openclaw/plugin-sdk/provider-http`. Funkcja pomocnicza normalizuje nazwy przesyłanych
plików, w tym przesyłane pliki AAC, które wymagają nazwy pliku w stylu M4A dla
`openclaw/plugin-sdk/provider-http`. Helper normalizuje nazwy plików przesyłanych
plików, w tym przesyłania AAC, które wymagają nazwy pliku w stylu M4A dla
zgodnych API transkrypcji.
</Tab>
<Tab title="Głos w czasie rzeczywistym">
<Tab title="Realtime voice">
```typescript
api.registerRealtimeVoiceProvider({
id: "acme-ai",
@ -598,6 +598,7 @@ uwierzytelnianiem kluczem API i dynamicznym rozpoznawaniem modeli.
connect: async () => {},
sendAudio: () => {},
setMediaTimestamp: () => {},
handleBargeIn: () => {},
submitToolResult: () => {},
acknowledgeMark: () => {},
close: () => {},
@ -605,8 +606,12 @@ uwierzytelnianiem kluczem API i dynamicznym rozpoznawaniem modeli.
}),
});
```
Zaimplementuj `handleBargeIn`, gdy transport potrafi wykryć, że człowiek
przerywa odtwarzanie asystenta, a dostawca obsługuje przycinanie lub
czyszczenie aktywnej odpowiedzi audio.
</Tab>
<Tab title="Rozumienie multimediów">
<Tab title="Media understanding">
```typescript
api.registerMediaUnderstandingProvider({
id: "acme-ai",
@ -616,12 +621,12 @@ uwierzytelnianiem kluczem API i dynamicznym rozpoznawaniem modeli.
});
```
</Tab>
<Tab title="Generowanie obrazów i wideo">
Możliwości wideo używają struktury **uwzględniającej tryb**: `generate`,
<Tab title="Image and video generation">
Funkcje wideo używają kształtu **świadomego trybu**: `generate`,
`imageToVideo` i `videoToVideo`. Płaskie pola agregujące, takie jak
`maxInputImages` / `maxInputVideos` / `maxDurationSeconds`, nie
wystarczają, aby czytelnie deklarować obsługę trybu transformacji lub wyłączone tryby.
Generowanie muzyki korzysta z tego samego wzorca z jawnymi blokami `generate` /
wystarczają, aby jasno ogłosić obsługę trybu transformacji lub wyłączone tryby.
Generowanie muzyki stosuje ten sam wzorzec z jawnymi blokami `generate` /
`edit`.
```typescript
@ -649,7 +654,7 @@ uwierzytelnianiem kluczem API i dynamicznym rozpoznawaniem modeli.
});
```
</Tab>
<Tab title="Pobieranie i wyszukiwanie w sieci">
<Tab title="Web fetch and search">
```typescript
api.registerWebFetchProvider({
id: "acme-ai-fetch",
@ -718,14 +723,14 @@ uwierzytelnianiem kluczem API i dynamicznym rozpoznawaniem modeli.
## Publikowanie w ClawHub
Pluginy dostawców publikuje się tak samo jak każdy inny zewnętrzny Plugin kodu:
Plugins dostawców publikuje się tak samo jak każdy inny zewnętrzny Plugin kodu:
```bash
clawhub package publish your-org/your-plugin --dry-run
clawhub package publish your-org/your-plugin
```
Nie używaj tutaj starszego aliasu publikowania przeznaczonego tylko dla Skills; pakiety Pluginów powinny używać
Nie używaj tutaj starszego aliasu publikowania przeznaczonego tylko dla skill; pakiety Plugin powinny używać
`clawhub package publish`.
## Struktura plików
@ -740,27 +745,27 @@ Nie używaj tutaj starszego aliasu publikowania przeznaczonego tylko dla Skills;
└── usage.ts # Usage endpoint (optional)
```
## Informacje o kolejności katalogu
## Odwołanie do kolejności katalogu
`catalog.order` określa, kiedy Twój katalog jest scalany względem wbudowanych
`catalog.order` kontroluje, kiedy Twój katalog jest scalany względem wbudowanych
dostawców:
| Kolejność | Kiedy | Przypadek użycia |
| --------- | ------------- | -------------------------------------------- |
| `simple` | Pierwszy przebieg | Prości dostawcy z kluczem API |
| `profile` | Po simple | Dostawcy zależni od profili uwierzytelniania |
| `paired` | Po profile | Syntetyzowanie wielu powiązanych wpisów |
| `late` | Ostatni przebieg | Nadpisywanie istniejących dostawców (wygrywa przy kolizji) |
| Kolejność | Kiedy | Przypadek użycia |
| --------- | ------------- | ----------------------------------------------- |
| `simple` | Pierwsze przejście | Prości dostawcy z kluczem API |
| `profile` | Po simple | Dostawcy zależni od profili uwierzytelniania |
| `paired` | Po profile | Syntezowanie wielu powiązanych wpisów |
| `late` | Ostatnie przejście | Zastępowanie istniejących dostawców (wygrywa przy kolizji) |
## Następne kroki
- [Pluginy kanałów](/pl/plugins/sdk-channel-plugins) — jeśli Twój Plugin udostępnia także kanał
- [Środowisko uruchomieniowe SDK](/pl/plugins/sdk-runtime) — funkcje pomocnicze `api.runtime` (TTS, wyszukiwanie, podagent)
- [Omówienie SDK](/pl/plugins/sdk-overview) — pełna dokumentacja importów ze ścieżek podrzędnych
- [Wewnętrzne mechanizmy Pluginów](/pl/plugins/architecture-internals#provider-runtime-hooks) — szczegóły hooków i dołączone przykłady
- [Plugins kanałów](/pl/plugins/sdk-channel-plugins) — jeśli Twój Plugin udostępnia też kanał
- [Środowisko uruchomieniowe SDK](/pl/plugins/sdk-runtime) — helpery `api.runtime` (TTS, wyszukiwanie, podagent)
- [Omówienie SDK](/pl/plugins/sdk-overview) — pełne odwołanie do importów podścieżek
- [Wewnętrzne mechanizmy Plugin](/pl/plugins/architecture-internals#provider-runtime-hooks) — szczegóły hooków i dołączone przykłady
## Powiązane
- [Konfiguracja Plugin SDK](/pl/plugins/sdk-setup)
- [Tworzenie Pluginów](/pl/plugins/building-plugins)
- [Tworzenie Pluginów kanałów](/pl/plugins/sdk-channel-plugins)
- [Tworzenie plugins](/pl/plugins/building-plugins)
- [Tworzenie plugins kanałów](/pl/plugins/sdk-channel-plugins)

406
docs/pl/plugins/voice-call.md
View File

@ -2,44 +2,44 @@
read_when:
- Chcesz wykonać wychodzące połączenie głosowe z OpenClaw
- Konfigurujesz lub rozwijasz Plugin połączeń głosowych
- Potrzebujesz głosu w czasie rzeczywistym lub strumieniowej transkrypcji w telefonii
- Potrzebujesz komunikacji głosowej w czasie rzeczywistym lub strumieniowej transkrypcji w telefonii
sidebarTitle: Voice call
summary: Wykonuj wychodzące i odbieraj przychodzące połączenia głosowe przez Twilio, Telnyx lub Plivo, z opcjonalną obsługą głosu w czasie rzeczywistym i strumieniową transkrypcją
summary: Wykonuj wychodzące i odbieraj przychodzące połączenia głosowe za pośrednictwem Twilio, Telnyx lub Plivo, z opcjonalną obsługą głosu w czasie rzeczywistym oraz transkrypcją strumieniową
title: Plugin połączeń głosowych
x-i18n:
generated_at: "2026-04-30T10:11:14Z"
generated_at: "2026-05-01T10:01:47Z"
model: gpt-5.5
provider: openai
source_hash: 7976b84ce1ee6e29706e595a4a25337632b34a9bb8f7cecdee1d6f833a8ce932
source_hash: 6334e5418e0fb530fc5d372ee1ada06ba987ce86bbf70746ee4ffe4c3ed4844e
source_path: plugins/voice-call.md
workflow: 16
---
Połączenia głosowe dla OpenClaw przez Plugin. Obsługuje powiadomienia wychodzące,
konwersacje wieloturowe, dwukierunkowy głos w czasie rzeczywistym, strumieniową
transkrypcję oraz połączenia przychodzące z zasadami listy dozwolonych.
Połączenia głosowe dla OpenClaw za pośrednictwem plugin. Obsługuje powiadomienia wychodzące,
wieloturowe konwersacje, głos realtime full-duplex, streaming
transkrypcji oraz połączenia przychodzące z zasadami listy dozwolonych.
**Obecni dostawcy:** `twilio` (Programmable Voice + Media Streams),
`telnyx` (Call Control v2), `plivo` (Voice API + XML transfer + GetInput
speech), `mock` (środowisko deweloperskie/bez sieci).
speech), `mock` (dev/bez sieci).
<Note>
Plugin Voice Call działa **wewnątrz procesu Gateway**. Jeśli używasz
zdalnego Gateway, zainstaluj i skonfiguruj Plugin na maszynie uruchamiającej
Gateway, a następnie uruchom ponownie Gateway, aby go załadować.
zdalnego Gateway, zainstaluj i skonfiguruj plugin na maszynie uruchamiającej
Gateway, a następnie zrestartuj Gateway, aby go załadować.
</Note>
## Szybki start
<Steps>
<Step title="Zainstaluj Plugin">
<Step title="Zainstaluj plugin">
<Tabs>
<Tab title="Z npm">
```bash
openclaw plugins install @openclaw/voice-call
```
</Tab>
<Tab title="Z folderu lokalnego (dev)">
<Tab title="Z lokalnego folderu (dev)">
```bash
PLUGIN_SRC=./path/to/local/voice-call-plugin
openclaw plugins install "$PLUGIN_SRC"
@ -49,17 +49,17 @@ Gateway, a następnie uruchom ponownie Gateway, aby go załadować.
</Tabs>
Jeśli npm zgłasza pakiet należący do OpenClaw jako przestarzały, ta wersja pakietu
pochodzi ze starszej zewnętrznej serii pakietów; użyj bieżącego spakowanego buildu OpenClaw
albo ścieżki folderu lokalnego, dopóki nie zostanie opublikowany nowszy pakiet npm.
pochodzi ze starszej zewnętrznej linii pakietów; użyj aktualnego spakowanego buildu
OpenClaw albo ścieżki do lokalnego folderu, dopóki nowszy pakiet npm nie zostanie opublikowany.
Następnie uruchom ponownie Gateway, aby Plugin został załadowany.
Następnie zrestartuj Gateway, aby plugin został załadowany.
</Step>
<Step title="Skonfiguruj dostawcę i webhook">
<Step title="Skonfiguruj dostawcę i Webhook">
Ustaw konfigurację w `plugins.entries.voice-call.config` (pełny kształt znajdziesz
poniżej w sekcji [Konfiguracja](#configuration)). Wymagane minimum to:
`provider`, dane uwierzytelniające dostawcy, `fromNumber` oraz publicznie
osiągalny adres URL webhooka.
poniżej w sekcji [Konfiguracja](#configuration)). Minimum to:
`provider`, poświadczenia dostawcy, `fromNumber` oraz publicznie
osiągalny URL Webhook.
</Step>
<Step title="Zweryfikuj konfigurację">
```bash
@ -67,19 +67,19 @@ Gateway, a następnie uruchom ponownie Gateway, aby go załadować.
```
Domyślne wyjście jest czytelne w logach czatu i terminalach. Sprawdza
włączenie Plugin, dane uwierzytelniające dostawcy, ekspozycję webhooka oraz to,
czy aktywny jest tylko jeden tryb audio (`streaming` albo `realtime`). Użyj
włączenie plugin, poświadczenia dostawcy, ekspozycję Webhook oraz to, czy
aktywny jest tylko jeden tryb audio (`streaming` albo `realtime`). Użyj
`--json` dla skryptów.
</Step>
<Step title="Test smoke">
<Step title="Test dymny">
```bash
openclaw voicecall smoke
openclaw voicecall smoke --to "+15555550123"
```
Oba polecenia domyślnie działają jako przebiegi próbne. Dodaj `--yes`, aby faktycznie wykonać krótkie
wychodzące połączenie powiadamiające:
Oba polecenia domyślnie wykonują przebiegi próbne. Dodaj `--yes`, aby faktycznie
wykonać krótkie wychodzące połączenie z powiadomieniem:
```bash
openclaw voicecall smoke --to "+15555550123" --yes
@ -89,21 +89,21 @@ Gateway, a następnie uruchom ponownie Gateway, aby go załadować.
</Steps>
<Warning>
W przypadku Twilio, Telnyx i Plivo konfiguracja musi wskazywać **publiczny adres URL webhooka**.
Jeśli `publicUrl`, adres URL tunelu, adres URL Tailscale albo zapasowy adres udostępniania
rozwiązuje się na local loopback lub prywatną przestrzeń sieciową, konfiguracja kończy się niepowodzeniem zamiast
uruchamiać dostawcę, który nie może odbierać webhooków operatora.
W przypadku Twilio, Telnyx i Plivo konfiguracja musi prowadzić do **publicznego URL Webhook**.
Jeśli `publicUrl`, URL tunelu, URL Tailscale albo awaryjna ekspozycja `serve`
prowadzi do loopback lub przestrzeni sieci prywatnej, konfiguracja zakończy się błędem zamiast
uruchamiać dostawcę, który nie może odbierać Webhook od operatorów.
</Warning>
## Konfiguracja
Jeśli `enabled: true`, ale wybranemu dostawcy brakuje danych uwierzytelniających,
uruchomienie Gateway zapisuje ostrzeżenie o niekompletnej konfiguracji z brakującymi kluczami i
Jeśli `enabled: true`, ale wybranemu dostawcy brakuje poświadczeń,
uruchamianie Gateway zapisuje ostrzeżenie o niepełnej konfiguracji z brakującymi kluczami i
pomija uruchomienie środowiska wykonawczego. Polecenia, wywołania RPC i narzędzia agenta nadal
zwracają dokładną brakującą konfigurację dostawcy podczas użycia.
<Note>
Dane uwierzytelniające voice-call akceptują SecretRefs. `plugins.entries.voice-call.config.twilio.authToken` oraz `plugins.entries.voice-call.config.tts.providers.*.apiKey` są rozwiązywane przez standardową powierzchnię SecretRef; zobacz [powierzchnię danych uwierzytelniających SecretRef](/pl/reference/secretref-credential-surface).
Poświadczenia voice-call akceptują SecretRefs. `plugins.entries.voice-call.config.twilio.authToken`, `plugins.entries.voice-call.config.realtime.providers.*.apiKey`, `plugins.entries.voice-call.config.streaming.providers.*.apiKey` oraz `plugins.entries.voice-call.config.tts.providers.*.apiKey` są rozwiązywane przez standardową powierzchnię SecretRef; zobacz [powierzchnię poświadczeń SecretRef](/pl/reference/secretref-credential-surface).
</Note>
```json5
@ -164,31 +164,31 @@ Dane uwierzytelniające voice-call akceptują SecretRefs. `plugins.entries.voice
```
<AccordionGroup>
<Accordion title="Uwagi dotyczące ekspozycji dostawcy i zabezpieczeń">
- Twilio, Telnyx i Plivo wymagają **publicznie osiągalnego** adresu URL webhooka.
- `mock` to lokalny dostawca deweloperski (bez wywołań sieciowych).
<Accordion title="Uwagi dotyczące ekspozycji i zabezpieczeń dostawców">
- Twilio, Telnyx i Plivo wymagają **publicznie osiągalnego** URL Webhook.
- `mock` to lokalny dostawca dev (bez wywołań sieciowych).
- Telnyx wymaga `telnyx.publicKey` (albo `TELNYX_PUBLIC_KEY`), chyba że `skipSignatureVerification` ma wartość true.
- `skipSignatureVerification` służy wyłącznie do testów lokalnych.
- W darmowej warstwie ngrok ustaw `publicUrl` na dokładny adres URL ngrok; weryfikacja podpisu jest zawsze egzekwowana.
- `tunnel.allowNgrokFreeTierLoopbackBypass: true` zezwala na webhooki Twilio z nieprawidłowymi podpisami **tylko** wtedy, gdy `tunnel.provider="ngrok"` i `serve.bind` jest local loopback (lokalny agent ngrok). Tylko lokalne środowisko deweloperskie.
- Adresy URL darmowej warstwy ngrok mogą się zmieniać lub dodawać stronę pośrednią; jeśli `publicUrl` się rozjedzie, podpisy Twilio zawiodą. Produkcja: preferuj stabilną domenę albo lejek Tailscale.
- W darmowej warstwie ngrok ustaw `publicUrl` na dokładny URL ngrok; weryfikacja podpisu jest zawsze wymuszana.
- `tunnel.allowNgrokFreeTierLoopbackBypass: true` dopuszcza Webhook Twilio z nieprawidłowymi podpisami **tylko** wtedy, gdy `tunnel.provider="ngrok"` i `serve.bind` jest loopback (lokalny agent ngrok). Tylko lokalny dev.
- URL-e darmowej warstwy ngrok mogą się zmieniać albo dodawać stronę pośrednią; jeśli `publicUrl` się rozjedzie, podpisy Twilio zawiodą. Produkcja: preferuj stabilną domenę albo lejek Tailscale.
</Accordion>
<Accordion title="Limity połączeń strumieniowych">
<Accordion title="Limity połączeń streaming">
- `streaming.preStartTimeoutMs` zamyka gniazda, które nigdy nie wysyłają prawidłowej ramki `start`.
- `streaming.maxPendingConnections` ogranicza łączną liczbę nieuwierzytelnionych gniazd przed startem.
- `streaming.maxPendingConnectionsPerIp` ogranicza nieuwierzytelnione gniazda przed startem na źródłowy adres IP.
- `streaming.maxConnections` ogranicza łączną liczbę otwartych gniazd strumienia multimediów (oczekujące + aktywne).
- `streaming.maxConnections` ogranicza łączną liczbę otwartych gniazd strumienia mediów (oczekujące + aktywne).
</Accordion>
<Accordion title="Migracje starszej konfiguracji">
Starsze konfiguracje używające `provider: "log"`, `twilio.from` albo starszych
kluczy OpenAI w `streaming.*` są przepisywane przez `openclaw doctor --fix`.
Zapasowa ścieżka środowiska wykonawczego nadal na razie akceptuje stare klucze voice-call, ale
kluczy OpenAI `streaming.*` są przepisywane przez `openclaw doctor --fix`.
Awaryjna kompatybilność runtime nadal na razie akceptuje stare klucze voice-call, ale
ścieżką przepisywania jest `openclaw doctor --fix`, a warstwa zgodności jest
tymczasowa.
Automatycznie migrowane klucze strumieniowania:
Automatycznie migrowane klucze streaming:
- `streaming.sttProvider` → `streaming.provider`
- `streaming.openaiApiKey` → `streaming.providers.openai.apiKey`
@ -199,42 +199,43 @@ Dane uwierzytelniające voice-call akceptują SecretRefs. `plugins.entries.voice
</Accordion>
</AccordionGroup>
## Konwersacje głosowe w czasie rzeczywistym
## Konwersacje głosowe realtime
`realtime` wybiera dostawcę dwukierunkowego głosu w czasie rzeczywistym dla audio połączeń
`realtime` wybiera dostawcę głosu realtime full-duplex dla audio połączenia
na żywo. Jest oddzielne od `streaming`, które tylko przekazuje audio do
dostawców transkrypcji w czasie rzeczywistym.
dostawców transkrypcji realtime.
<Warning>
`realtime.enabled` nie można łączyć z `streaming.enabled`. Wybierz jeden
tryb audio na połączenie.
</Warning>
Bieżące zachowanie środowiska wykonawczego:
Obecne zachowanie runtime:
- `realtime.enabled` jest obsługiwane dla Twilio Media Streams.
- `realtime.provider` jest opcjonalne. Jeśli nie jest ustawione, Voice Call używa pierwszego zarejestrowanego dostawcy głosu w czasie rzeczywistym.
- Dołączani dostawcy głosu w czasie rzeczywistym: Google Gemini Live (`google`) oraz OpenAI (`openai`), rejestrowani przez swoje pluginy dostawców.
- Surowa konfiguracja należąca do dostawcy znajduje się pod `realtime.providers.<providerId>`.
- Voice Call domyślnie udostępnia współdzielone narzędzie czasu rzeczywistego `openclaw_agent_consult`. Model czasu rzeczywistego może je wywołać, gdy dzwoniący prosi o głębsze rozumowanie, aktualne informacje albo zwykłe narzędzia OpenClaw.
- Jeśli `realtime.provider` wskazuje niezarejestrowanego dostawcę albo w ogóle nie zarejestrowano żadnego dostawcy głosu w czasie rzeczywistym, Voice Call zapisuje ostrzeżenie i pomija multimedia czasu rzeczywistego zamiast powodować niepowodzenie całego Plugin.
- Klucze sesji konsultacji ponownie używają istniejącej sesji głosowej, gdy jest dostępna, a następnie przechodzą zapasowo na numer telefonu dzwoniącego/odbiorcy, aby kolejne wywołania konsultacji zachowywały kontekst w trakcie połączenia.
- `realtime.provider` jest opcjonalne. Jeśli nie jest ustawione, Voice Call używa pierwszego zarejestrowanego dostawcy głosu realtime.
- Dołączani dostawcy głosu realtime: Google Gemini Live (`google`) i OpenAI (`openai`), rejestrowani przez ich plugin dostawców.
- Surowa konfiguracja należąca do dostawcy znajduje się w `realtime.providers.<providerId>`.
- Voice Call domyślnie udostępnia współdzielone narzędzie realtime `openclaw_agent_consult`. Model realtime może je wywołać, gdy rozmówca prosi o głębsze rozumowanie, aktualne informacje albo zwykłe narzędzia OpenClaw.
- `realtime.fastContext.enabled` jest domyślnie wyłączone. Po włączeniu Voice Call najpierw przeszukuje zindeksowany kontekst pamięci/sesji dla pytania konsultacyjnego i zwraca te fragmenty do modelu realtime w czasie `realtime.fastContext.timeoutMs`, zanim przejdzie awaryjnie do pełnego agenta konsultacyjnego tylko wtedy, gdy `realtime.fastContext.fallbackToConsult` ma wartość true.
- Jeśli `realtime.provider` wskazuje niezarejestrowanego dostawcę albo żaden dostawca głosu realtime nie jest w ogóle zarejestrowany, Voice Call zapisuje ostrzeżenie i pomija media realtime zamiast powodować błąd całego plugin.
- Klucze sesji konsultacyjnej ponownie używają istniejącej sesji głosowej, gdy jest dostępna, a następnie przechodzą awaryjnie do numeru telefonu dzwoniącego/odbiorcy, aby kolejne wywołania konsultacyjne zachowywały kontekst podczas połączenia.
### Zasady narzędzi
### Zasada narzędzi
`realtime.toolPolicy` steruje przebiegiem konsultacji:
`realtime.toolPolicy` kontroluje przebieg konsultacji:
| Zasada | Zachowanie |
| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `safe-read-only` | Udostępnia narzędzie konsultacji i ogranicza zwykłego agenta do `read`, `web_search`, `web_fetch`, `x_search`, `memory_search` oraz `memory_get`. |
| `owner` | Udostępnia narzędzie konsultacji i pozwala zwykłemu agentowi używać normalnych zasad narzędzi agenta. |
| `none` | Nie udostępnia narzędzia konsultacji. Niestandardowe `realtime.tools` nadal są przekazywane do dostawcy czasu rzeczywistego. |
| `owner` | Udostępnia narzędzie konsultacji i pozwala zwykłemu agentowi używać normalnej zasady narzędzi agenta. |
| `none` | Nie udostępnia narzędzia konsultacji. Niestandardowe `realtime.tools` nadal są przekazywane do dostawcy realtime. |
### Przykłady dostawców czasu rzeczywistego
### Przykłady dostawców realtime
<Tabs>
<Tab title="Google Gemini Live">
Wartości domyślne: klucz API z `realtime.providers.google.apiKey`,
Domyślnie: klucz API z `realtime.providers.google.apiKey`,
`GEMINI_API_KEY` albo `GOOGLE_GENERATIVE_AI_API_KEY`; model
`gemini-2.5-flash-native-audio-preview-12-2025`; głos `Kore`.
@ -291,26 +292,27 @@ Bieżące zachowanie środowiska wykonawczego:
</Tab>
</Tabs>
Zobacz [dostawcę Google](/pl/providers/google) oraz
[dostawcę OpenAI](/pl/providers/openai), aby poznać opcje głosu w czasie rzeczywistym
Zobacz [dostawcę Google](/pl/providers/google) i
[dostawcę OpenAI](/pl/providers/openai), aby poznać opcje głosu realtime
specyficzne dla dostawcy.
## Transkrypcja strumieniowa
## Transkrypcja streaming
`streaming` wybiera dostawcę transkrypcji w czasie rzeczywistym dla audio połączenia na żywo.
`streaming` wybiera dostawcę transkrypcji realtime dla audio połączenia na żywo.
Bieżące zachowanie środowiska wykonawczego:
Obecne zachowanie runtime:
- `streaming.provider` jest opcjonalne. Jeśli nie jest ustawione, Voice Call używa pierwszego zarejestrowanego dostawcy transkrypcji w czasie rzeczywistym.
- Dołączani dostawcy transkrypcji w czasie rzeczywistym: Deepgram (`deepgram`), ElevenLabs (`elevenlabs`), Mistral (`mistral`), OpenAI (`openai`) oraz xAI (`xai`), rejestrowani przez swoje pluginy dostawców.
- Surowa konfiguracja należąca do dostawcy znajduje się pod `streaming.providers.<providerId>`.
- Jeśli `streaming.provider` wskazuje niezarejestrowanego dostawcę albo żaden nie jest zarejestrowany, Voice Call zapisuje ostrzeżenie i pomija strumieniowanie multimediów zamiast powodować niepowodzenie całego Plugin.
- Wbudowani dostawcy transkrypcji w czasie rzeczywistym: Deepgram (`deepgram`), ElevenLabs (`elevenlabs`), Mistral (`mistral`), OpenAI (`openai`) i xAI (`xai`), rejestrowani przez ich Pluginy dostawców.
- Surowa konfiguracja należąca do dostawcy znajduje się w `streaming.providers.<providerId>`.
- Po tym, jak Twilio wyśle zaakceptowany komunikat `start` strumienia, Voice Call natychmiast rejestruje strumień, kolejkowuje przychodzące media przez dostawcę transkrypcji, gdy dostawca się łączy, i uruchamia początkowe powitanie dopiero po przygotowaniu transkrypcji w czasie rzeczywistym.
- Jeśli `streaming.provider` wskazuje niezarejestrowanego dostawcę albo żaden nie jest zarejestrowany, Voice Call zapisuje ostrzeżenie w logach i pomija strumieniowanie mediów zamiast powodować awarię całego Pluginu.
### Przykłady dostawców strumieniowania
<Tabs>
<Tab title="OpenAI">
Wartości domyślne: klucz API `streaming.providers.openai.apiKey` albo
Domyślne: klucz API `streaming.providers.openai.apiKey` albo
`OPENAI_API_KEY`; model `gpt-4o-transcribe`; `silenceDurationMs: 800`;
`vadThreshold: 0.5`.
@ -342,8 +344,8 @@ Bieżące zachowanie środowiska wykonawczego:
</Tab>
<Tab title="xAI">
Wartości domyślne: klucz API `streaming.providers.xai.apiKey` albo `XAI_API_KEY`;
endpoint `wss://api.x.ai/v1/stt`; kodowanie `mulaw`; częstotliwość próbkowania `8000`;
Domyślne: klucz API `streaming.providers.xai.apiKey` albo `XAI_API_KEY`;
punkt końcowy `wss://api.x.ai/v1/stt`; kodowanie `mulaw`; częstotliwość próbkowania `8000`;
`endpointingMs: 800`; `interimResults: true`.
```json5
@ -377,8 +379,8 @@ Bieżące zachowanie środowiska wykonawczego:
## TTS dla połączeń
Voice Call używa podstawowej konfiguracji `messages.tts` do strumieniowania
mowy w połączeniach. Możesz ją nadpisać w konfiguracji Plugin przy użyciu
**tego samego kształtu** — jest ona głęboko scalana z `messages.tts`.
mowy podczas połączeń. Możesz ją nadpisać w konfiguracji Pluginu w
**tym samym kształcie** — jest głęboko scalana z `messages.tts`.
```json5
{
@ -395,17 +397,17 @@ mowy w połączeniach. Możesz ją nadpisać w konfiguracji Plugin przy użyciu
```
<Warning>
**Microsoft speech jest ignorowany dla połączeń głosowych.** Dźwięk telefoniczny wymaga PCM;
obecny transport Microsoft nie udostępnia wyjścia telefonicznego PCM.
**Microsoft speech jest ignorowane dla połączeń głosowych.** Dźwięk telefoniczny wymaga PCM;
bieżący transport Microsoft nie udostępnia wyjścia telefonicznego PCM.
</Warning>
Uwagi dotyczące zachowania:
Uwagi dotyczące działania:
- Starsze klucze `tts.<provider>` w konfiguracji Plugin (`openai`, `elevenlabs`, `microsoft`, `edge`) są naprawiane przez `openclaw doctor --fix`; zatwierdzona konfiguracja powinna używać `tts.providers.<provider>`.
- Podstawowy TTS jest używany, gdy włączone jest strumieniowanie multimediów Twilio; w przeciwnym razie połączenia wracają do natywnych głosów dostawcy.
- Jeśli strumień multimediów Twilio jest już aktywny, Voice Call nie wraca do TwiML `<Say>`. Jeśli telefoniczny TTS jest w tym stanie niedostępny, żądanie odtwarzania kończy się niepowodzeniem zamiast mieszać dwie ścieżki odtwarzania.
- Gdy telefoniczny TTS wraca do dostawcy zapasowego, Voice Call zapisuje ostrzeżenie z łańcuchem dostawców (`from`, `to`, `attempts`) do debugowania.
- Gdy wtrącenie Twilio albo zamknięcie strumienia czyści oczekującą kolejkę TTS, zakolejkowane żądania odtwarzania są rozstrzygane zamiast pozostawiać dzwoniących w oczekiwaniu na zakończenie odtwarzania.
- Starsze klucze `tts.<provider>` w konfiguracji Pluginu (`openai`, `elevenlabs`, `microsoft`, `edge`) są naprawiane przez `openclaw doctor --fix`; zatwierdzona konfiguracja powinna używać `tts.providers.<provider>`.
- Podstawowe TTS jest używane, gdy strumieniowanie mediów Twilio jest włączone; w przeciwnym razie połączenia wracają do natywnych głosów dostawcy.
- Jeśli strumień mediów Twilio jest już aktywny, Voice Call nie wraca do TwiML `<Say>`. Jeśli TTS telefoniczne jest w tym stanie niedostępne, żądanie odtwarzania kończy się niepowodzeniem zamiast mieszać dwie ścieżki odtwarzania.
- Gdy TTS telefoniczne wraca do dostawcy zapasowego, Voice Call zapisuje ostrzeżenie z łańcuchem dostawców (`from`, `to`, `attempts`) na potrzeby debugowania.
- Gdy barge-in Twilio albo zamknięcie strumienia czyści oczekującą kolejkę TTS, zakolejkowane żądania odtwarzania zostają rozstrzygnięte zamiast pozostawiać dzwoniących w oczekiwaniu na zakończenie odtwarzania.
### Przykłady TTS
@ -474,7 +476,7 @@ Uwagi dotyczące zachowania:
## Połączenia przychodzące
Domyślna polityka połączeń przychodzących to `disabled`. Aby włączyć połączenia przychodzące, ustaw:
Polityka połączeń przychodzących ma domyślnie wartość `disabled`. Aby włączyć połączenia przychodzące, ustaw:
```json5
{
@ -485,21 +487,20 @@ Domyślna polityka połączeń przychodzących to `disabled`. Aby włączyć po
```
<Warning>
`inboundPolicy: "allowlist"` to ekran identyfikacji dzwoniącego o niskiej pewności. Plugin
normalizuje dostarczoną przez dostawcę wartość `From` i porównuje ją z
`allowFrom`. Weryfikacja Webhook uwierzytelnia dostarczenie przez dostawcę oraz
`inboundPolicy: "allowlist"` to ekranowanie identyfikatora dzwoniącego o niskiej pewności. Plugin
normalizuje wartość `From` dostarczoną przez dostawcę i porównuje ją z
`allowFrom`. Weryfikacja Webhook uwierzytelnia dostarczenie przez dostawcę i
integralność ładunku, ale **nie** dowodzi własności numeru dzwoniącego
PSTN/VoIP. Traktuj `allowFrom` jako filtrowanie identyfikacji dzwoniącego, a nie silną
PSTN/VoIP. Traktuj `allowFrom` jako filtrowanie identyfikatora dzwoniącego, a nie silną
tożsamość dzwoniącego.
</Warning>
Automatyczne odpowiedzi używają systemu agenta. Dostosuj za pomocą `responseModel`,
Automatyczne odpowiedzi używają systemu agentów. Dostosuj je za pomocą `responseModel`,
`responseSystemPrompt` i `responseTimeoutMs`.
### Kontrakt wypowiedzi głosowej
Dla automatycznych odpowiedzi Voice Call dołącza ścisły kontrakt wypowiedzi głosowej do
promptu systemowego:
Dla automatycznych odpowiedzi Voice Call dołącza do monitu systemowego ścisły kontrakt wypowiedzi głosowej:
```text
{"spoken":"..."}
@ -507,42 +508,41 @@ promptu systemowego:
Voice Call defensywnie wyodrębnia tekst mowy:
- Ignoruje ładunki oznaczone jako treści rozumowania/błędu.
- Parsuje bezpośredni JSON, JSON w bloku kodu albo wbudowane klucze `"spoken"`.
- Wraca do zwykłego tekstu i usuwa prawdopodobne akapity wprowadzające z planowaniem/metadanymi.
- Ignoruje ładunki oznaczone jako treść rozumowania/błędu.
- Parsuje bezpośredni JSON, JSON w bloku kodu albo klucze `"spoken"` w wierszu.
- Wraca do zwykłego tekstu i usuwa prawdopodobne akapity wprowadzające związane z planowaniem/metadanymi.
Dzięki temu odtwarzana mowa pozostaje skupiona na tekście dla dzwoniącego i unika
wycieku tekstu planowania do dźwięku.
Dzięki temu odtwarzanie mowy skupia się na tekście przeznaczonym dla dzwoniącego i unika
ujawniania tekstu planowania w dźwięku.
### Zachowanie uruchamiania rozmowy
W przypadku wychodzących połączeń `conversation` obsługa pierwszej wiadomości jest powiązana ze stanem
odtwarzania na żywo:
Dla wychodzących połączeń `conversation` obsługa pierwszej wiadomości jest powiązana ze stanem odtwarzania na żywo:
- Czyszczenie kolejki po wtrąceniu i automatyczna odpowiedź są wstrzymywane tylko wtedy, gdy początkowe powitanie jest aktywnie wypowiadane.
- Czyszczenie kolejki po barge-in i automatyczna odpowiedź są wstrzymywane tylko wtedy, gdy początkowe powitanie jest aktywnie wypowiadane.
- Jeśli początkowe odtwarzanie się nie powiedzie, połączenie wraca do stanu `listening`, a początkowa wiadomość pozostaje w kolejce do ponowienia.
- Początkowe odtwarzanie dla strumieniowania Twilio zaczyna się przy połączeniu strumienia bez dodatkowego opóźnienia.
- Wtrącenie przerywa aktywne odtwarzanie i czyści zakolejkowane, ale jeszcze nieodtwarzane wpisy Twilio TTS. Wyczyszczone wpisy są rozstrzygane jako pominięte, więc logika kolejnej odpowiedzi może kontynuować bez czekania na dźwięk, który nigdy nie zostanie odtworzony.
- Rozmowy głosowe w czasie rzeczywistym używają własnej początkowej tury strumienia czasu rzeczywistego. Voice Call **nie** publikuje starszej aktualizacji TwiML `<Say>` dla tej początkowej wiadomości, więc wychodzące sesje `<Connect><Stream>` pozostają podłączone.
- Barge-in przerywa aktywne odtwarzanie i czyści zakolejkowane, ale jeszcze nieodtwarzane wpisy TTS Twilio. Wyczyszczone wpisy są rozstrzygane jako pominięte, więc logika kolejnej odpowiedzi może działać dalej bez czekania na dźwięk, który nigdy nie zostanie odtworzony.
- Rozmowy głosowe w czasie rzeczywistym używają własnej tury otwierającej strumienia w czasie rzeczywistym. Voice Call **nie** wysyła starszej aktualizacji TwiML `<Say>` dla tej początkowej wiadomości, więc wychodzące sesje `<Connect><Stream>` pozostają podłączone.
### Okres karencji po rozłączeniu strumienia Twilio
### Okres karencji rozłączenia strumienia Twilio
Gdy strumień multimediów Twilio się rozłącza, Voice Call czeka **2000 ms** przed
Gdy strumień mediów Twilio zostanie rozłączony, Voice Call czeka **2000 ms** przed
automatycznym zakończeniem połączenia:
- Jeśli strumień połączy się ponownie w tym oknie, automatyczne zakończenie zostaje anulowane.
- Jeśli po okresie karencji żaden strumień nie zarejestruje się ponownie, połączenie zostaje zakończone, aby zapobiec zablokowanym aktywnym połączeniom.
- Jeśli strumień połączy się ponownie w tym oknie, automatyczne zakończenie zostanie anulowane.
- Jeśli po okresie karencji żaden strumień nie zarejestruje się ponownie, połączenie zostanie zakończone, aby zapobiec zablokowanym aktywnym połączeniom.
## Czyszczenie nieaktualnych połączeń
## Usuwanie nieaktualnych połączeń
Użyj `staleCallReaperSeconds`, aby kończyć połączenia, które nigdy nie otrzymują końcowego
Webhook (na przykład połączenia w trybie powiadamiania, które nigdy się nie kończą). Wartość domyślna
Webhook (na przykład połączenia w trybie powiadomień, które nigdy się nie kończą). Wartość domyślna
to `0` (wyłączone).
Zalecane zakresy:
- **Produkcja:** `120`–`300` sekund dla przepływów typu powiadomienie.
- Utrzymuj tę wartość **wyższą niż `maxDurationSeconds`**, aby zwykłe połączenia mogły się zakończyć. Dobry punkt wyjścia to `maxDurationSeconds + 30–60` sekund.
- **Produkcja:** `120`–`300` sekund dla przepływów typu powiadomienia.
- Utrzymuj tę wartość **wyższą niż `maxDurationSeconds`**, aby zwykłe połączenia mogły się zakończyć. Dobrym punktem startowym jest `maxDurationSeconds + 30–60` sekund.
```json5
{
@ -561,26 +561,26 @@ Zalecane zakresy:
## Bezpieczeństwo Webhook
Gdy proxy lub tunel znajduje się przed Gateway, Plugin
Gdy przed Gateway znajduje się proxy lub tunel, Plugin
rekonstruuje publiczny URL do weryfikacji podpisu. Te opcje
kontrolują, którym przekazywanym nagłówkom można ufać:
kontrolują, którym przekazanym nagłówkom można ufać:
<ParamField path="webhookSecurity.allowedHosts" type="string[]">
Lista dozwolonych hostów z nagłówków przekazywania.
</ParamField>
<ParamField path="webhookSecurity.trustForwardingHeaders" type="boolean">
Ufaj przekazywanym nagłówkom bez listy dozwolonych.
Ufaj przekazanym nagłówkom bez listy dozwolonych.
</ParamField>
<ParamField path="webhookSecurity.trustedProxyIPs" type="string[]">
Ufaj przekazywanym nagłówkom tylko wtedy, gdy zdalny adres IP żądania pasuje do listy.
Ufaj przekazanym nagłówkom tylko wtedy, gdy zdalny adres IP żądania pasuje do listy.
</ParamField>
Dodatkowe zabezpieczenia:
- Ochrona przed **powtórzeniem Webhook** jest włączona dla Twilio i Plivo. Powtórzone poprawne żądania Webhook są potwierdzane, ale pomijane pod kątem skutków ubocznych.
- Tury rozmowy Twilio zawierają token dla każdej tury w callbackach `<Gather>`, więc nieaktualne/powtórzone callbacki mowy nie mogą zaspokoić nowszej oczekującej tury transkrypcji.
- Nieuwierzytelnione żądania Webhook są odrzucane przed odczytem treści, gdy brakuje wymaganych przez dostawcę nagłówków podpisu.
- Webhook voice-call używa współdzielonego profilu treści przed uwierzytelnieniem (64 KB / 5 sekund) oraz limitu trwających żądań na adres IP przed weryfikacją podpisu.
- **Ochrona przed powtórzeniem** Webhook jest włączona dla Twilio i Plivo. Powtórzone prawidłowe żądania Webhook są potwierdzane, ale pomijane pod kątem skutków ubocznych.
- Tury rozmowy Twilio zawierają token dla każdej tury w wywołaniach zwrotnych `<Gather>`, więc przestarzałe/powtórzone wywołania zwrotne mowy nie mogą spełnić nowszej oczekującej tury transkrypcji.
- Nieuwierzytelnione żądania Webhook są odrzucane przed odczytami treści, gdy brakuje wymaganych przez dostawcę nagłówków podpisu.
- Webhook voice-call używa współdzielonego profilu treści przed uwierzytelnieniem (64 KB / 5 sekund) oraz limitu równoległych żądań dla adresu IP przed weryfikacją podpisu.
Przykład ze stabilnym publicznym hostem:
@ -616,39 +616,177 @@ openclaw voicecall latency # summarize turn latency from lo
openclaw voicecall expose --mode funnel
```
Gdy Gateway już działa, operacyjne polecenia `voicecall` delegują
do środowiska wykonawczego voice-call należącego do Gateway, więc CLI nie wiąże drugiego
serwera Webhook. Jeśli żaden Gateway nie jest osiągalny, polecenia wracają do
samodzielnego środowiska wykonawczego CLI.
`latency` odczytuje `calls.jsonl` z domyślnej ścieżki przechowywania voice-call.
Użyj `--file <path>`, aby wskazać inny dziennik, oraz `--last <n>`, aby ograniczyć
analizę do ostatnich N rekordów (domyślnie 200). Dane wyjściowe zawierają p50/p90/p99
Użyj `--file <path>`, aby wskazać inny log, oraz `--last <n>`, aby ograniczyć
analizę do ostatnich N rekordów (domyślnie 200). Wynik zawiera p50/p90/p99
dla opóźnienia tury i czasów oczekiwania na nasłuchiwanie.
## Narzędzie agenta
Nazwa narzędzia: `voice_call`.
| Akcja | Argumenty |
| --------------- | ------------------------- |
| `initiate_call` | `message`, `to?`, `mode?` |
| `continue_call` | `callId`, `message` |
| `speak_to_user` | `callId`, `message` |
| `send_dtmf` | `callId`, `digits` |
| `end_call` | `callId` |
| `get_status` | `callId` |
| Akcja | Argumenty |
| --------------- | ------------------------------------------ |
| `initiate_call` | `message`, `to?`, `mode?`, `dtmfSequence?` |
| `continue_call` | `callId`, `message` |
| `speak_to_user` | `callId`, `message` |
| `send_dtmf` | `callId`, `digits` |
| `end_call` | `callId` |
| `get_status` | `callId` |
To repozytorium dostarcza pasującą dokumentację skill pod adresem `skills/voice-call/SKILL.md`.
To repozytorium dostarcza pasujący dokument Skills pod `skills/voice-call/SKILL.md`.
## RPC Gateway
## Gateway RPC
| Metoda | Argumenty |
| -------------------- | ------------------------- |
| `voicecall.initiate` | `to?`, `message`, `mode?` |
| `voicecall.continue` | `callId`, `message` |
| `voicecall.speak` | `callId`, `message` |
| `voicecall.dtmf` | `callId`, `digits` |
| `voicecall.end` | `callId` |
| `voicecall.status` | `callId` |
| Metoda | Argumenty |
| -------------------- | ------------------------------------------ |
| `voicecall.initiate` | `to?`, `message`, `mode?`, `dtmfSequence?` |
| `voicecall.continue` | `callId`, `message` |
| `voicecall.speak` | `callId`, `message` |
| `voicecall.dtmf` | `callId`, `digits` |
| `voicecall.end` | `callId` |
| `voicecall.status` | `callId` |
`dtmfSequence` jest prawidłowe tylko z `mode: "conversation"`. Połączenia w trybie powiadomień
powinny używać `voicecall.dtmf` po utworzeniu połączenia, jeśli potrzebują cyfr
po połączeniu.
## Rozwiązywanie problemów
### Konfiguracja nie udostępnia Webhook
Uruchom konfigurację z tego samego środowiska, w którym działa Gateway:
```bash
openclaw voicecall setup
openclaw voicecall setup --json
```
Dla `twilio`, `telnyx` i `plivo` parametr `webhook-exposure` musi być zielony. Skonfigurowany `publicUrl` nadal zakończy się niepowodzeniem, jeśli wskazuje na lokalną lub prywatną przestrzeń sieciową, ponieważ operator nie może wywołać tych adresów zwrotnie. Nie używaj `localhost`, `127.0.0.1`, `0.0.0.0`, `10.x`, `172.16.x`-`172.31.x`, `192.168.x`, `169.254.x`, `fc00::/7` ani `fd00::/8` jako `publicUrl`.
Użyj jednej publicznej ścieżki ekspozycji:
```json5
{
plugins: {
entries: {
"voice-call": {
config: {
publicUrl: "https://voice.example.com/voice/webhook",
// or
tunnel: { provider: "ngrok" },
// or
tailscale: { mode: "funnel", path: "/voice/webhook" },
},
},
},
},
}
```
Po zmianie konfiguracji zrestartuj lub przeładuj Gateway, a następnie uruchom:
```bash
openclaw voicecall setup
openclaw voicecall smoke
```
`voicecall smoke` jest przebiegiem próbnym, chyba że przekażesz `--yes`.
### Dane uwierzytelniające dostawcy kończą się niepowodzeniem
Sprawdź wybranego dostawcę i wymagane pola danych uwierzytelniających:
- Twilio: `twilio.accountSid`, `twilio.authToken` oraz `fromNumber` albo
`TWILIO_ACCOUNT_SID`, `TWILIO_AUTH_TOKEN` i `TWILIO_FROM_NUMBER`.
- Telnyx: `telnyx.apiKey`, `telnyx.connectionId`, `telnyx.publicKey` oraz
`fromNumber`.
- Plivo: `plivo.authId`, `plivo.authToken` oraz `fromNumber`.
Dane uwierzytelniające muszą istnieć na hoście Gateway. Edycja lokalnego profilu powłoki nie wpływa na już działający Gateway, dopóki nie zostanie on zrestartowany lub nie przeładuje swojego środowiska.
### Połączenia się rozpoczynają, ale webhooks dostawcy nie docierają
Upewnij się, że konsola dostawcy wskazuje dokładny publiczny URL webhooka:
```text
https://voice.example.com/voice/webhook
```
Następnie sprawdź stan środowiska uruchomieniowego:
```bash
openclaw voicecall status --call-id <id>
openclaw voicecall tail
openclaw logs --follow
```
Typowe przyczyny:
- `publicUrl` wskazuje inną ścieżkę niż `serve.path`.
- URL tunelu zmienił się po uruchomieniu Gateway.
- Proxy przekazuje żądanie, ale usuwa lub przepisuje nagłówki host/proto.
- Zapora lub DNS kieruje publiczną nazwę hosta w inne miejsce niż Gateway.
- Gateway został zrestartowany bez włączonego Plugin Voice Call.
Gdy przed Gateway znajduje się odwrotne proxy lub tunel, ustaw `webhookSecurity.allowedHosts` na publiczną nazwę hosta albo użyj `webhookSecurity.trustedProxyIPs` dla znanego adresu proxy. Używaj `webhookSecurity.trustForwardingHeaders` tylko wtedy, gdy granica proxy jest pod Twoją kontrolą.
### Weryfikacja podpisu kończy się niepowodzeniem
Podpisy dostawcy są sprawdzane względem publicznego URL, który OpenClaw odtwarza z przychodzącego żądania. Jeśli podpisy zawodzą:
- Upewnij się, że URL webhooka dostawcy dokładnie odpowiada `publicUrl`, łącznie ze schematem, hostem i ścieżką.
- Dla URL-i ngrok w darmowym planie zaktualizuj `publicUrl`, gdy zmieni się nazwa hosta tunelu.
- Upewnij się, że proxy zachowuje oryginalne nagłówki host i proto, albo skonfiguruj `webhookSecurity.allowedHosts`.
- Nie włączaj `skipSignatureVerification` poza lokalnym testowaniem.
### Dołączenia Google Meet przez Twilio kończą się niepowodzeniem
Google Meet używa tego pluginu do dołączania przez połączenie telefoniczne Twilio. Najpierw zweryfikuj Voice Call:
```bash
openclaw voicecall setup
openclaw voicecall smoke --to "+15555550123"
```
Następnie jawnie zweryfikuj transport Google Meet:
```bash
openclaw googlemeet setup --transport twilio
```
Jeśli Voice Call jest zielony, ale uczestnik Meet nigdy nie dołącza, sprawdź numer połączenia telefonicznego Meet, PIN oraz `--dtmf-sequence`. Połączenie telefoniczne może być sprawne, podczas gdy spotkanie odrzuca lub ignoruje nieprawidłową sekwencję DTMF.
Google Meet przekazuje sekwencję DTMF Meet i tekst wprowadzenia do `voicecall.start`. W przypadku połączeń Twilio Voice Call najpierw udostępnia DTMF TwiML, przekierowuje z powrotem do webhooka, a potem otwiera strumień multimediów w czasie rzeczywistym, aby zapisane wprowadzenie zostało wygenerowane po dołączeniu uczestnika telefonicznego do spotkania.
Użyj `openclaw logs --follow`, aby śledzić fazę na żywo. Poprawne dołączenie Twilio Meet zapisuje zdarzenia w tej kolejności:
- Google Meet deleguje dołączenie Twilio do Voice Call.
- Voice Call zapisuje DTMF TwiML przed połączeniem.
- Początkowy TwiML Twilio zostaje użyty i udostępniony przed obsługą w czasie rzeczywistym.
- Voice Call udostępnia TwiML w czasie rzeczywistym dla połączenia Twilio.
- Most w czasie rzeczywistym uruchamia się z początkowym powitaniem w kolejce.
`openclaw voicecall tail` nadal pokazuje utrwalone rekordy połączeń; jest przydatne do stanu połączenia i transkrypcji, ale nie każde przejście webhooka lub czasu rzeczywistego pojawia się tam.
### Połączenie w czasie rzeczywistym nie ma mowy
Upewnij się, że włączony jest tylko jeden tryb audio. `realtime.enabled` i `streaming.enabled` nie mogą jednocześnie mieć wartości true.
Dla połączeń Twilio w czasie rzeczywistym sprawdź także:
- Plugin dostawcy czasu rzeczywistego jest załadowany i zarejestrowany.
- `realtime.provider` jest nieustawiony albo wskazuje zarejestrowanego dostawcę.
- Klucz API dostawcy jest dostępny dla procesu Gateway.
- `openclaw logs --follow` pokazuje udostępnienie TwiML w czasie rzeczywistym, uruchomienie mostu w czasie rzeczywistym oraz dodanie początkowego powitania do kolejki.
## Powiązane
- [Tryb rozmowy](/pl/nodes/talk)
- [Tekst na mowę](/pl/tools/tts)
- [Zamiana tekstu na mowę](/pl/tools/tts)
- [Wybudzanie głosem](/pl/nodes/voicewake)

513
docs/pl/reference/RELEASING.md
View File

@ -2,14 +2,14 @@
read_when:
- Szukam definicji publicznych kanałów wydań
- Uruchamianie walidacji wydania lub akceptacji pakietu
- Szukasz informacji o nazewnictwie wersji i cyklu wydań
summary: Ścieżki wydań, lista kontrolna operatora, środowiska walidacyjne, nazewnictwo wersji i kadencja
- Szukasz nazewnictwa wersji i harmonogramu wydań
summary: Ścieżki wydań, lista kontrolna operatora, środowiska walidacyjne, nazewnictwo wersji i harmonogram
title: Polityka wydań
x-i18n:
generated_at: "2026-04-30T10:16:39Z"
generated_at: "2026-05-01T10:01:50Z"
model: gpt-5.5
provider: openai
source_hash: 54dc9ad7918ac95ec535a0404bbcbc04461a2b977151db0c2039b91e7e69c15c
source_hash: dfe579099a9580e2d0400cd0b24f26d3fa3ee917899423604ebc13aa2519b4ee
source_path: reference/RELEASING.md
workflow: 16
---
@ -22,221 +22,142 @@ OpenClaw ma trzy publiczne ścieżki wydań:
## Nazewnictwo wersji
- Wersja wydania stable: `YYYY.M.D`
- Wersja wydania stabilnego: `YYYY.M.D`
- Tag Git: `vYYYY.M.D`
- Wersja wydania korygującego stable: `YYYY.M.D-N`
- Wersja stabilnego wydania poprawkowego: `YYYY.M.D-N`
- Tag Git: `vYYYY.M.D-N`
- Wersja przedpremierowa beta: `YYYY.M.D-beta.N`
- Tag Git: `vYYYY.M.D-beta.N`
- Nie dodawaj zer wiodących do miesiąca ani dnia
- `latest` oznacza bieżące promowane wydanie stable npm
- `latest` oznacza bieżące promowane stabilne wydanie npm
- `beta` oznacza bieżący cel instalacji beta
- Wydania stable i korygujące stable domyślnie publikują do npm `beta`; operatorzy wydania mogą jawnie wskazać `latest` albo później promować sprawdzoną kompilację beta
- Każde wydanie stable OpenClaw dostarcza razem pakiet npm i aplikację macOS;
wydania beta zwykle najpierw walidują i publikują ścieżkę npm/pakietu, a
kompilacja/podpisywanie/notaryzacja aplikacji mac są zarezerwowane dla stable, chyba że wyraźnie zażądano inaczej
- Wydania stabilne i stabilne wydania poprawkowe domyślnie publikują do npm `beta`; operatorzy wydania mogą jawnie wskazać `latest` albo później promować sprawdzoną kompilację beta
- Każde stabilne wydanie OpenClaw dostarcza razem pakiet npm i aplikację macOS;
wydania beta zwykle najpierw weryfikują i publikują ścieżkę npm/pakietu, a
budowanie/podpisywanie/notaryzację aplikacji na Maca rezerwują dla wydań stabilnych, chyba że zostanie to wyraźnie zażądane
## Rytm wydań
- Wydania przechodzą najpierw przez beta
- Stable następuje dopiero po zwalidowaniu najnowszej wersji beta
- Maintainerzy zwykle tworzą wydania z gałęzi `release/YYYY.M.D` utworzonej
- Stabilne wydanie następuje dopiero po zweryfikowaniu najnowszej wersji beta
- Maintainerzy zwykle przygotowują wydania z gałęzi `release/YYYY.M.D` utworzonej
z bieżącego `main`, aby walidacja wydania i poprawki nie blokowały nowego
rozwoju na `main`
- Jeśli tag beta został wypchnięty lub opublikowany i wymaga poprawki, maintainerzy tworzą
następny tag `-beta.N` zamiast usuwać lub odtwarzać stary tag beta
- Szczegółowa procedura wydania, zgody, poświadczenia i notatki dotyczące odzyskiwania
są dostępne tylko dla maintainerów
- Szczegółowa procedura wydania, zgody, poświadczenia i notatki dotyczące odzyskiwania są
dostępne tylko dla maintainerów
## Lista kontrolna operatora wydania
Ta lista kontrolna pokazuje publiczny kształt przepływu wydania. Prywatne poświadczenia,
podpisywanie, notaryzacja, odzyskiwanie dist-tag i szczegóły awaryjnego wycofania pozostają w
runbooku wydania dostępnym tylko dla maintainerów.
runbooku wydawniczym dostępnym tylko dla maintainerów.
1. Zacznij od bieżącego `main`: pobierz najnowsze zmiany, potwierdź, że docelowy commit został wypchnięty,
i potwierdź, że bieżące CI `main` jest wystarczająco zielone, aby utworzyć z niego gałąź.
2. Przepisz górną sekcję `CHANGELOG.md` na podstawie rzeczywistej historii commitów za pomocą
`/changelog`, pozostaw wpisy zorientowane na użytkownika, zacommituj je, wypchnij i wykonaj rebase/pull
2. Przepisz najwyższą sekcję `CHANGELOG.md` na podstawie rzeczywistej historii commitów za pomocą
`/changelog`, zachowaj wpisy zorientowane na użytkownika, zacommituj ją, wypchnij i wykonaj rebase/pull
jeszcze raz przed utworzeniem gałęzi.
3. Przejrzyj rekordy kompatybilności wydania w
`src/plugins/compat/registry.ts` oraz
`src/commands/doctor/shared/deprecation-compat.ts`. Usuń wygasłą
kompatybilność tylko wtedy, gdy ścieżka aktualizacji pozostaje pokryta, albo zapisz, dlaczego jest
celowo zachowywana.
4. Utwórz `release/YYYY.M.D` z bieżącego `main`; nie wykonuj normalnej pracy nad wydaniem
`src/plugins/compat/registry.ts` i
`src/commands/doctor/shared/deprecation-compat.ts`. Usuwaj wygasłą
kompatybilność tylko wtedy, gdy ścieżka aktualizacji pozostaje objęta obsługą, albo zapisz, dlaczego jest
celowo utrzymywana.
4. Utwórz `release/YYYY.M.D` z bieżącego `main`; nie wykonuj zwykłych prac wydawniczych
bezpośrednio na `main`.
5. Podbij każdą wymaganą lokalizację wersji dla zamierzonego tagu, a następnie uruchom
lokalną deterministyczną kontrolę wstępną:
lokalny deterministyczny preflight:
`pnpm check:test-types`, `pnpm check:architecture`,
`pnpm build && pnpm ui:build` oraz `pnpm release:check`.
6. Uruchom `OpenClaw NPM Release` z `preflight_only=true`. Zanim tag istnieje,
pełny 40-znakowy SHA gałęzi wydania jest dozwolony do kontroli wstępnej tylko na potrzeby walidacji.
pełny 40-znakowy SHA gałęzi wydania jest dozwolony dla preflight tylko walidacyjnego.
Zapisz pomyślny `preflight_run_id`.
7. Uruchom wszystkie testy przedwydaniowe za pomocą `Full Release Validation` dla
gałęzi wydania, tagu lub pełnego SHA commita. To jest jeden ręczny punkt wejścia
dla czterech dużych pól testowych wydania: Vitest, Docker, QA Lab i Package.
8. Jeśli walidacja się nie powiedzie, napraw na gałęzi wydania i ponownie uruchom najmniejszy nieudany
plik, ścieżkę, zadanie workflow, profil pakietu, providera lub listę dozwolonych modeli, które
dowodzą poprawki. Ponownie uruchamiaj pełny parasol tylko wtedy, gdy zmieniona powierzchnia sprawia,
gałęzi wydania, tagu albo pełnego SHA commita. To jest jedyny ręczny punkt wejścia
dla czterech dużych maszyn testowych wydania: Vitest, Docker, QA Lab i Package.
8. Jeśli walidacja się nie powiedzie, napraw problem na gałęzi wydania i uruchom ponownie najmniejszy nieudany
plik, ścieżkę, zadanie workflow, profil pakietu, dostawcę albo listę dozwolonych modeli, które
potwierdzają poprawkę. Uruchamiaj ponownie pełny parasol tylko wtedy, gdy zmieniony zakres powoduje,
że wcześniejsze dowody są nieaktualne.
9. Dla beta otaguj `vYYYY.M.D-beta.N`, opublikuj z npm dist-tag `beta`, a następnie uruchom
akceptację pakietu po publikacji wobec opublikowanego pakietu `openclaw@YYYY.M.D-beta.N`
lub `openclaw@beta`. Jeśli wypchnięta lub opublikowana beta wymaga poprawki, utwórz
następne `-beta.N`; nie usuwaj ani nie przepisuj starej bety.
10. Dla stable kontynuuj dopiero po tym, jak sprawdzona beta lub kandydat do wydania ma
wymagane dowody walidacji. Publikacja stable npm ponownie używa pomyślnego
artefaktu kontroli wstępnej przez `preflight_run_id`; gotowość wydania stable macOS
wymaga też spakowanych `.zip`, `.dmg`, `.dSYM.zip` oraz zaktualizowanego
9. Dla beta oznacz tagiem `vYYYY.M.D-beta.N`, opublikuj z dist-tag npm `beta`, a następnie uruchom
powydaniową akceptację pakietu względem opublikowanego pakietu `openclaw@YYYY.M.D-beta.N`
albo `openclaw@beta`. Jeśli wypchnięta lub opublikowana beta wymaga poprawki, utwórz
następny `-beta.N`; nie usuwaj ani nie przepisuj starej bety.
10. Dla wydania stabilnego kontynuuj dopiero po tym, jak sprawdzona beta lub kandydat do wydania ma
wymagane dowody walidacji. Stabilna publikacja npm ponownie używa pomyślnego
artefaktu preflight przez `preflight_run_id`; gotowość stabilnego wydania macOS
wymaga również spakowanych `.zip`, `.dmg`, `.dSYM.zip` oraz zaktualizowanego
`appcast.xml` na `main`.
11. Po publikacji uruchom weryfikator npm po publikacji, opcjonalny samodzielny
opublikowany-npm Telegram E2E, gdy potrzebujesz dowodu kanału po publikacji,
promocję dist-tag, gdy jest potrzebna, notatki GitHub release/prerelease z
kompletnej pasującej sekcji `CHANGELOG.md` oraz kroki ogłoszenia wydania.
11. Po publikacji uruchom weryfikator npm po publikacji, opcjonalne samodzielne
E2E Telegram z opublikowanego npm, gdy potrzebujesz powydaniowego potwierdzenia kanału,
promocję dist-tag, gdy jest potrzebna, notatki wydania/przedpremierowe GitHub z
pełnej pasującej sekcji `CHANGELOG.md` oraz kroki ogłoszenia wydania.
## Kontrola wstępna wydania
## Preflight wydania
- Uruchom `pnpm check:test-types` przed preflightem wydania, aby testowy TypeScript pozostawał
objęty poza szybszą lokalną bramką `pnpm check`
- Uruchom `pnpm check:architecture` przed preflightem wydania, aby szersze kontrole cykli
importów i granic architektury były zielone poza szybszą lokalną bramką
- Uruchom `pnpm build && pnpm ui:build` przed `pnpm release:check`, aby oczekiwane
artefakty wydania `dist/*` i pakiet Control UI istniały dla etapu walidacji
paczki
- Uruchom ręczny workflow `Full Release Validation` przed zatwierdzeniem wydania, aby
uruchomić wszystkie przedwydaniowe test boxes z jednego punktu wejścia. Przyjmuje on gałąź,
tag albo pełny SHA commita, wywołuje ręczny `CI` oraz wywołuje
`OpenClaw Release Checks` dla install smoke, package acceptance, zestawów ścieżki
wydania Docker, live/E2E, OpenWebUI, parytetu QA Lab, Matrix i ścieżek Telegram.
Podaj `npm_telegram_package_spec` tylko po opublikowaniu paczki i gdy powydaniowe
Telegram E2E też ma zostać uruchomione. Podaj
`evidence_package_spec`, gdy prywatny raport dowodowy ma udowodnić, że
walidacja odpowiada opublikowanej paczce npm bez wymuszania Telegram E2E.
- Uruchom `pnpm check:test-types` przed wstępną kontrolą wydania, aby testowy TypeScript pozostał objęty sprawdzaniem poza szybszą lokalną bramką `pnpm check`
- Uruchom `pnpm check:architecture` przed wstępną kontrolą wydania, aby szersze kontrole cykli importów i granic architektury były zielone poza szybszą lokalną bramką
- Uruchom `pnpm build && pnpm ui:build` przed `pnpm release:check`, aby oczekiwane artefakty wydania `dist/*` i pakiet Control UI istniały na potrzeby kroku walidacji pakowania
- Uruchom ręczny workflow `Full Release Validation` przed zatwierdzeniem wydania, aby zainicjować wszystkie przedwydaniowe pola testowe z jednego punktu wejścia. Przyjmuje gałąź, tag albo pełny SHA commita, uruchamia ręcznie `CI` oraz uruchamia `OpenClaw Release Checks` dla smoke testu instalacji, akceptacji pakietu, zestawów ścieżki wydania Dockera, live/E2E, OpenWebUI, parytetu QA Lab, Matrix i ścieżek Telegram. Podaj `npm_telegram_package_spec` dopiero po opublikowaniu pakietu, gdy po publikacji ma też zostać uruchomione Telegram E2E. Podaj `evidence_package_spec`, gdy prywatny raport dowodowy ma potwierdzić, że walidacja odpowiada opublikowanemu pakietowi npm bez wymuszania Telegram E2E.
Przykład:
`gh workflow run full-release-validation.yml --ref main -f ref=release/YYYY.M.D`
- Uruchom ręczny workflow `Package Acceptance`, gdy chcesz uzyskać dowód z kanału bocznego
dla kandydata paczki, podczas gdy prace wydaniowe trwają dalej. Użyj `source=npm` dla
`openclaw@beta`, `openclaw@latest` albo dokładnej wersji wydania; `source=ref`,
aby spakować zaufaną gałąź/tag/SHA `package_ref` z bieżącym harness
`workflow_ref`; `source=url` dla archiwum tarball HTTPS z wymaganym
SHA-256; albo `source=artifact` dla archiwum tarball przesłanego przez inny przebieg
GitHub Actions. Workflow rozwiązuje kandydata do
`package-under-test`, ponownie używa planisty wydania Docker E2E względem tego
archiwum tarball i może uruchomić Telegram QA względem tego samego archiwum tarball z
`telegram_mode=mock-openai` albo `telegram_mode=live-frontier`.
Przykład: `gh workflow run package-acceptance.yml --ref main -f workflow_ref=main -f source=npm -f package_spec=openclaw@beta -f suite_profile=product -f telegram_mode=mock-openai`
- Uruchom ręczny workflow `Package Acceptance`, gdy potrzebujesz dowodu kanałem bocznym dla kandydata pakietu, podczas gdy prace nad wydaniem trwają dalej. Użyj `source=npm` dla `openclaw@beta`, `openclaw@latest` albo dokładnej wersji wydania; `source=ref`, aby spakować zaufaną gałąź/tag/SHA `package_ref` z aktualnym zestawem `workflow_ref`; `source=url` dla tarballa HTTPS z wymaganym SHA-256; albo `source=artifact` dla tarballa przesłanego przez inny przebieg GitHub Actions. Workflow rozwiązuje kandydata do `package-under-test`, ponownie używa harmonogramu wydania Docker E2E wobec tego tarballa i może uruchomić Telegram QA wobec tego samego tarballa z `telegram_mode=mock-openai` albo `telegram_mode=live-frontier`. Gdy wybrane ścieżki Dockera obejmują `published-upgrade-survivor`, artefakt pakietu jest kandydatem, a `published_upgrade_survivor_baseline` wybiera opublikowaną bazę.
Przykład: `gh workflow run package-acceptance.yml --ref main -f workflow_ref=main -f source=npm -f package_spec=openclaw@beta -f suite_profile=product -f published_upgrade_survivor_baseline=openclaw@2026.4.26 -f telegram_mode=mock-openai`
Typowe profile:
- `smoke`: ścieżki instalacji/kanału/agenta, sieci Gateway i przeładowania konfiguracji
- `package`: natywne dla artefaktu ścieżki paczki/aktualizacji/Plugin bez OpenWebUI ani live ClawHub
- `product`: profil paczki plus kanały MCP, czyszczenie cron/subagent,
wyszukiwanie webowe OpenAI i OpenWebUI
- `full`: fragmenty ścieżki wydania Docker z OpenWebUI
- `package`: natywne dla artefaktu ścieżki pakietu/aktualizacji/pluginu bez OpenWebUI ani live ClawHub
- `product`: profil pakietu plus kanały MCP, czyszczenie cron/subagent, wyszukiwanie internetowe OpenAI i OpenWebUI
- `full`: fragmenty ścieżki wydania Dockera z OpenWebUI
- `custom`: dokładny wybór `docker_lanes` dla ukierunkowanego ponownego uruchomienia
- Uruchom ręczny workflow `CI` bezpośrednio, gdy potrzebujesz tylko pełnego zwykłego pokrycia CI
dla kandydata wydania. Ręczne wywołania CI omijają zakresowanie zmian
i wymuszają shardy Linux Node, shardy bundled-plugin, kontrakty kanałów,
zgodność Node 22, `check`, `check-additional`, build smoke,
kontrole dokumentacji, Python skills, Windows, macOS, Android i ścieżki i18n
Control UI.
- Uruchom ręczny workflow `CI` bezpośrednio, gdy potrzebujesz tylko pełnego normalnego pokrycia CI dla kandydata wydania. Ręczne uruchomienia CI omijają zawężanie według zmian i wymuszają ścieżki shardów Linux Node, shardów dołączonych pluginów, kontraktów kanałów, zgodności Node 22, `check`, `check-additional`, smoke testu budowania, kontroli dokumentacji, Python skills, Windows, macOS, Android i i18n Control UI.
Przykład: `gh workflow run ci.yml --ref release/YYYY.M.D`
- Uruchom `pnpm qa:otel:smoke` podczas walidacji telemetrii wydania. Ćwiczy on
QA-lab przez lokalny odbiornik OTLP/HTTP i weryfikuje wyeksportowane nazwy spanów
śledzenia, ograniczone atrybuty oraz redakcję treści/identyfikatorów bez
wymagania Opik, Langfuse ani innego zewnętrznego collectora.
- Uruchom `pnpm qa:otel:smoke` podczas walidacji telemetrii wydania. Testuje QA-lab przez lokalny odbiornik OTLP/HTTP i weryfikuje eksportowane nazwy spanów trace, ograniczone atrybuty oraz redakcję treści/identyfikatorów bez wymagania Opik, Langfuse ani innego zewnętrznego kolektora.
- Uruchom `pnpm release:check` przed każdym tagowanym wydaniem
- Kontrole wydania działają teraz w osobnym ręcznym workflow:
`OpenClaw Release Checks`
- `OpenClaw Release Checks` uruchamia też bramkę parytetu mock QA Lab oraz szybki
profil live Matrix i ścieżkę Telegram QA przed zatwierdzeniem wydania. Ścieżki live
używają środowiska `qa-live-shared`; Telegram używa też dzierżaw poświadczeń Convex CI.
Uruchom ręczny workflow `QA-Lab - All Lanes` z
`matrix_profile=all` i `matrix_shards=true`, gdy chcesz pełny inwentarz transportu,
mediów i E2EE Matrix równolegle.
- Walidacja uruchomieniowa instalacji i aktualizacji między systemami operacyjnymi jest częścią publicznych
`OpenClaw Release Checks` i `Full Release Validation`, które wywołują
reusable workflow
`.github/workflows/openclaw-cross-os-release-checks-reusable.yml` bezpośrednio
- Ten podział jest celowy: utrzymuje rzeczywistą ścieżkę wydania npm krótką,
deterministyczną i skoncentrowaną na artefaktach, podczas gdy wolniejsze kontrole live pozostają
we własnej ścieżce, aby nie wstrzymywały ani nie blokowały publikacji
- Kontrole wydania zawierające sekrety powinny być wywoływane przez `Full Release
Validation` albo z refa workflow `main`/release, aby logika workflow i
sekrety pozostawały kontrolowane
- `OpenClaw Release Checks` przyjmuje gałąź, tag albo pełny SHA commita, o ile
rozwiązany commit jest osiągalny z gałęzi OpenClaw albo tagu wydania
- Preflight tylko walidacyjny `OpenClaw NPM Release` przyjmuje też bieżący
pełny 40-znakowy SHA commita gałęzi workflow bez wymagania wypchniętego tagu
- Ta ścieżka SHA jest tylko walidacyjna i nie może zostać promowana do rzeczywistej publikacji
- W trybie SHA workflow syntetyzuje `v<package.json version>` tylko dla kontroli
metadanych paczki; rzeczywista publikacja nadal wymaga prawdziwego tagu wydania
- Oba workflow utrzymują rzeczywistą ścieżkę publikacji i promocji na runnerach
hostowanych przez GitHub, podczas gdy niemutująca ścieżka walidacji może używać większych
runnerów Blacksmith Linux
- `OpenClaw Release Checks` uruchamia także bramkę parytetu mock QA Lab oraz szybki profil live Matrix i ścieżkę Telegram QA przed zatwierdzeniem wydania. Ścieżki live używają środowiska `qa-live-shared`; Telegram używa także dzierżaw poświadczeń Convex CI. Uruchom ręczny workflow `QA-Lab - All Lanes` z `matrix_profile=all` i `matrix_shards=true`, gdy chcesz uzyskać pełny spis transportu, mediów i E2EE Matrix równolegle.
- Walidacja środowiska uruchomieniowego instalacji i aktualizacji między systemami operacyjnymi jest częścią publicznych `OpenClaw Release Checks` i `Full Release Validation`, które wywołują bezpośrednio wielokrotnego użytku workflow `.github/workflows/openclaw-cross-os-release-checks-reusable.yml`
- Ten podział jest celowy: utrzymuje rzeczywistą ścieżkę wydania npm krótką, deterministyczną i skupioną na artefaktach, podczas gdy wolniejsze kontrole live pozostają we własnej ścieżce, aby nie opóźniały ani nie blokowały publikacji
- Kontrole wydania zawierające sekrety powinny być uruchamiane przez `Full Release Validation` albo z referencji workflow `main`/release, aby logika workflow i sekrety pozostały kontrolowane
- `OpenClaw Release Checks` akceptuje gałąź, tag albo pełny SHA commita, o ile rozwiązany commit jest osiągalny z gałęzi OpenClaw albo tagu wydania
- Wstępna kontrola `OpenClaw NPM Release` tylko do walidacji akceptuje również bieżący pełny 40-znakowy SHA commita gałęzi workflow bez wymagania wypchniętego tagu
- Ta ścieżka SHA służy wyłącznie do walidacji i nie może zostać awansowana do rzeczywistej publikacji
- W trybie SHA workflow syntetyzuje `v<package.json version>` tylko na potrzeby kontroli metadanych pakietu; rzeczywista publikacja nadal wymaga prawdziwego tagu wydania
- Oba workflow utrzymują rzeczywistą ścieżkę publikacji i promocji na runnerach hostowanych przez GitHub, podczas gdy niemodyfikująca ścieżka walidacji może używać większych runnerów Blacksmith Linux
- Ten workflow uruchamia
`OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_CACHE_TEST=1 pnpm test:live:cache`
z użyciem sekretów workflow `OPENAI_API_KEY` i `ANTHROPIC_API_KEY`
- Preflight wydania npm nie czeka już na osobną ścieżkę kontroli wydania
- Wstępna kontrola wydania npm nie czeka już na osobną ścieżkę kontroli wydania
- Uruchom `RELEASE_TAG=vYYYY.M.D node --import tsx scripts/openclaw-npm-release-check.ts`
(albo odpowiadający tag beta/korekty) przed zatwierdzeniem
(albo odpowiadający tag beta/poprawki) przed zatwierdzeniem
- Po publikacji npm uruchom
`node --import tsx scripts/openclaw-npm-postpublish-verify.ts YYYY.M.D`
(albo odpowiadającą wersję beta/korekty), aby zweryfikować opublikowaną ścieżkę
instalacji z rejestru w świeżym prefiksie tymczasowym
- Po publikacji beta uruchom `OPENCLAW_NPM_TELEGRAM_PACKAGE_SPEC=openclaw@YYYY.M.D-beta.N OPENCLAW_NPM_TELEGRAM_CREDENTIAL_SOURCE=convex OPENCLAW_NPM_TELEGRAM_CREDENTIAL_ROLE=ci pnpm test:docker:npm-telegram-live`
aby zweryfikować onboarding zainstalowanej paczki, konfigurację Telegram i rzeczywiste Telegram E2E
względem opublikowanej paczki npm z użyciem współdzielonej puli dzierżawionych poświadczeń Telegram.
Lokalne jednorazowe uruchomienia maintainerów mogą pominąć zmienne Convex i przekazać trzy
poświadczenia env `OPENCLAW_QA_TELEGRAM_*` bezpośrednio.
- Maintainerzy mogą uruchomić tę samą kontrolę powydaniową z GitHub Actions przez
ręczny workflow `NPM Telegram Beta E2E`. Jest on celowo wyłącznie ręczny i
nie uruchamia się przy każdym mergu.
- Automatyzacja wydań maintainerów używa teraz schematu preflight-potem-promocja:
- rzeczywista publikacja npm musi przejść pomyślny npm `preflight_run_id`
- rzeczywista publikacja npm musi zostać wywołana z tej samej gałęzi `main` albo
`release/YYYY.M.D` co pomyślny przebieg preflight
- stabilne wydania npm domyślnie trafiają do `beta`
(albo odpowiadającą wersję beta/poprawki), aby zweryfikować ścieżkę instalacji opublikowanego rejestru w świeżym tymczasowym prefiksie
- Po publikacji beta uruchom `OPENCLAW_NPM_TELEGRAM_PACKAGE_SPEC=openclaw@YYYY.M.D-beta.N OPENCLAW_NPM_TELEGRAM_CREDENTIAL_SOURCE=convex OPENCLAW_NPM_TELEGRAM_CREDENTIAL_ROLE=ci pnpm test:docker:npm-telegram-live`, aby zweryfikować onboarding zainstalowanego pakietu, konfigurację Telegram i rzeczywiste Telegram E2E wobec opublikowanego pakietu npm z użyciem współdzielonej puli dzierżawionych poświadczeń Telegram. Jednorazowe lokalne uruchomienia maintainerów mogą pominąć zmienne Convex i przekazać trzy poświadczenia środowiskowe `OPENCLAW_QA_TELEGRAM_*` bezpośrednio.
- Maintainerzy mogą uruchomić tę samą kontrolę po publikacji z GitHub Actions przez ręczny workflow `NPM Telegram Beta E2E`. Jest celowo wyłącznie ręczny i nie uruchamia się przy każdym scaleniu.
- Automatyzacja wydań maintainerów używa teraz modelu wstępna kontrola, potem promocja:
- rzeczywista publikacja npm musi przejść pomyślny `preflight_run_id` npm
- rzeczywista publikacja npm musi zostać uruchomiona z tej samej gałęzi `main` albo `release/YYYY.M.D`, co udany przebieg wstępnej kontroli
- stabilne wydania npm domyślnie wskazują `beta`
- stabilna publikacja npm może jawnie wskazać `latest` przez wejście workflow
- mutacja npm dist-tag oparta na tokenie znajduje się teraz w
`openclaw/releases-private/.github/workflows/openclaw-npm-dist-tags.yml`
ze względów bezpieczeństwa, ponieważ `npm dist-tag add` nadal potrzebuje `NPM_TOKEN`, podczas gdy
publiczne repo utrzymuje publikację wyłącznie przez OIDC
- publiczne `macOS Release` jest tylko walidacyjne
- rzeczywista prywatna publikacja mac musi przejść pomyślne prywatne mac
`preflight_run_id` i `validate_run_id`
- rzeczywiste ścieżki publikacji promują przygotowane artefakty zamiast budować
je ponownie
- Dla stabilnych wydań korygujących takich jak `YYYY.M.D-N` weryfikator powydaniowy
sprawdza też tę samą ścieżkę aktualizacji w prefiksie tymczasowym z `YYYY.M.D` do `YYYY.M.D-N`,
aby korekty wydań nie mogły po cichu pozostawić starszych globalnych instalacji na
bazowym stabilnym ładunku
- Preflight wydania npm kończy się niepowodzeniem w trybie zamkniętym, jeśli archiwum tarball nie zawiera zarówno
`dist/control-ui/index.html`, jak i niepustego ładunku `dist/control-ui/assets/`,
abyśmy ponownie nie wysłali pustego dashboardu przeglądarkowego
- Weryfikacja powydaniowa sprawdza też, czy opublikowana instalacja z rejestru
zawiera niepuste zależności runtime bundled plugin pod głównym układem `dist/*`.
Wydanie wysłane z brakującymi albo pustymi ładunkami zależności bundled plugin
nie przechodzi weryfikatora postpublish i nie może zostać promowane
do `latest`.
- `pnpm test:install:smoke` wymusza też budżet `unpackedSize` npm pack na
archiwum tarball kandydata aktualizacji, dzięki czemu installer e2e wykrywa przypadkowy rozrost paczki
przed ścieżką publikacji wydania
- Jeśli prace wydaniowe dotknęły planowania CI, manifestów timingów rozszerzeń albo
macierzy testów rozszerzeń, wygeneruj ponownie i przejrzyj należące do planisty
wyjścia macierzy `plugin-prerelease-extension-shard` z
`.github/workflows/plugin-prerelease.yml` przed zatwierdzeniem, aby notatki wydania nie
opisywały nieaktualnego układu CI
- mutacja tokenowego npm dist-tag znajduje się teraz w `openclaw/releases-private/.github/workflows/openclaw-npm-dist-tags.yml` ze względów bezpieczeństwa, ponieważ `npm dist-tag add` nadal wymaga `NPM_TOKEN`, podczas gdy publiczne repo zachowuje publikację wyłącznie OIDC
- publiczny `macOS Release` służy wyłącznie do walidacji; gdy tag istnieje tylko na gałęzi wydania, ale workflow jest uruchamiany z `main`, ustaw `public_release_branch=release/YYYY.M.D`
- rzeczywista prywatna publikacja mac musi przejść pomyślny prywatny mac `preflight_run_id` i `validate_run_id`
- rzeczywiste ścieżki publikacji promują przygotowane artefakty zamiast budować je ponownie
- Dla stabilnych wydań poprawek, takich jak `YYYY.M.D-N`, weryfikator po publikacji sprawdza też tę samą ścieżkę aktualizacji w tymczasowym prefiksie z `YYYY.M.D` do `YYYY.M.D-N`, aby poprawki wydania nie mogły po cichu pozostawić starszych globalnych instalacji na bazowym stabilnym ładunku
- Wstępna kontrola wydania npm kończy się niepowodzeniem w sposób zamknięty, chyba że tarball zawiera zarówno `dist/control-ui/index.html`, jak i niepusty ładunek `dist/control-ui/assets/`, abyśmy ponownie nie wysłali pustego panelu przeglądarkowego
- Weryfikacja po publikacji sprawdza także, czy opublikowana instalacja z rejestru zawiera niepuste zależności uruchomieniowe dołączonych pluginów w głównym układzie `dist/*`. Wydanie dostarczone z brakującymi lub pustymi ładunkami zależności dołączonych pluginów nie przechodzi weryfikatora po publikacji i nie może zostać awansowane do `latest`.
- `pnpm test:install:smoke` egzekwuje również budżet `unpackedSize` pakietu npm wobec tarballa kandydata aktualizacji, więc installer e2e wychwytuje przypadkowe rozdęcie pakietu przed ścieżką publikacji wydania
- Jeśli prace nad wydaniem dotknęły planowania CI, manifestów czasowych rozszerzeń albo macierzy testów rozszerzeń, wygeneruj ponownie i przejrzyj należące do planera wyjścia macierzy `plugin-prerelease-extension-shard` z `.github/workflows/plugin-prerelease.yml` przed zatwierdzeniem, aby informacje o wydaniu nie opisywały nieaktualnego układu CI
- Gotowość stabilnego wydania macOS obejmuje też powierzchnie aktualizatora:
- wydanie GitHub musi ostatecznie zawierać spakowane `.zip`, `.dmg` i `.dSYM.zip`
- `appcast.xml` na `main` musi wskazywać nowy stabilny zip po publikacji
- spakowana aplikacja musi zachować niedebugowy bundle id, niepusty URL feedu Sparkle
oraz `CFBundleVersion` na poziomie albo powyżej kanonicznego progu buildu Sparkle
dla tej wersji wydania
- `appcast.xml` na `main` musi po publikacji wskazywać nowy stabilny zip
- spakowana aplikacja musi zachować niedebugowy identyfikator pakietu, niepusty URL feedu Sparkle oraz `CFBundleVersion` równy lub wyższy od kanonicznego minimalnego buildu Sparkle dla tej wersji wydania
## Release test boxes
## Pola testowe wydania
`Full Release Validation` to sposób, w jaki operatorzy uruchamiają wszystkie testy przedwydaniowe z
jednego punktu wejścia. Uruchom go z zaufanego refa workflow `main` i przekaż gałąź
wydania, tag albo pełny SHA commita jako `ref`:
`Full Release Validation` to sposób, w jaki operatorzy inicjują wszystkie testy przedwydaniowe z jednego punktu wejścia. Uruchom go z zaufanej referencji workflow `main` i przekaż gałąź wydania, tag albo pełny SHA commita jako `ref`:
```bash
gh workflow run full-release-validation.yml \
@ -244,40 +165,28 @@ gh workflow run full-release-validation.yml \
-f ref=release/YYYY.M.D \
-f provider=openai \
-f mode=both \
-f release_profile=full \
-f release_profile=stable \
-f evidence_package_spec=openclaw@YYYY.M.D-beta.N
```
Workflow rozwiązuje docelowy ref, wywołuje ręczny `CI` z
`target_ref=<release-ref>`, wywołuje `OpenClaw Release Checks` oraz
opcjonalnie wywołuje samodzielne powydaniowe Telegram E2E, gdy
`npm_telegram_package_spec` jest ustawione. `OpenClaw Release Checks` następnie rozgałęzia
install smoke, kontrole wydania cross-OS, pokrycie live/E2E Docker release-path,
Package Acceptance z Telegram package QA, parytet QA Lab, live Matrix i
live Telegram. Pełny przebieg jest akceptowalny tylko wtedy, gdy podsumowanie `Full Release Validation`
pokazuje `normal_ci` i `release_checks` jako pomyślne, a każdy opcjonalny
potomny `npm_telegram` jest pomyślny albo celowo pominięty. Końcowe
podsumowanie weryfikatora zawiera tabele najwolniejszych zadań dla każdego przebiegu potomnego, aby release
manager mógł zobaczyć bieżącą ścieżkę krytyczną bez pobierania logów.
Potomne workflow są wywoływane z zaufanego refa, który uruchamia `Full Release
Validation`, zwykle `--ref main`, nawet gdy docelowy `ref` wskazuje na
starszą gałąź wydania albo tag. Nie ma osobnego wejścia workflow-ref dla Full Release Validation;
wybierz zaufany harness, wybierając ref uruchomienia workflow.
Workflow rozwiązuje docelową referencję, uruchamia ręczne `CI` z `target_ref=<release-ref>`, uruchamia `OpenClaw Release Checks` i opcjonalnie uruchamia samodzielne Telegram E2E po publikacji, gdy ustawione jest `npm_telegram_package_spec`. `OpenClaw Release Checks` następnie rozdziela się na smoke test instalacji, międzyplatformowe kontrole wydania, pokrycie ścieżki wydania Docker live/E2E, Package Acceptance z QA pakietu Telegram, parytet QA Lab, live Matrix i live Telegram. Pełny przebieg jest akceptowalny tylko wtedy, gdy podsumowanie `Full Release Validation` pokazuje `normal_ci` i `release_checks` jako udane, a każde opcjonalne dziecko `npm_telegram` jest udane albo celowo pominięte. Końcowe podsumowanie weryfikatora zawiera tabele najwolniejszych zadań dla każdego przebiegu podrzędnego, aby release manager mógł zobaczyć aktualną ścieżkę krytyczną bez pobierania logów.
Zobacz [Pełna walidacja wydania](/pl/reference/full-release-validation), aby uzyskać kompletną macierz etapów, dokładne nazwy zadań workflow, różnice między profilami stabilnym i pełnym, artefakty oraz uchwyty do ukierunkowanego ponownego uruchomienia.
Workflow podrzędne są uruchamiane z zaufanej referencji, która uruchamia `Full Release Validation`, zwykle `--ref main`, nawet gdy docelowy `ref` wskazuje starszą gałąź wydania albo tag. Nie ma osobnego wejścia referencji workflow Full Release Validation; wybierz zaufany zestaw, wybierając referencję przebiegu workflow.
Użyj `release_profile`, aby wybrać szerokość live/provider:
Użyj `release_profile`, aby wybrać zakres live/providera:
- `minimum`: najszybsza krytyczna dla wydania ścieżka OpenAI/core live i Docker
- `stable`: minimum plus stabilne pokrycie provider/backend do zatwierdzenia wydania
- `full`: stable plus szerokie doradcze pokrycie provider/media
- `full`: stable plus szerokie pokrycie doradcze provider/media
`OpenClaw Release Checks` używa zaufanego refa workflow, aby raz rozwiązać docelowy
ref jako `release-package-under-test`, i ponownie używa tego artefaktu zarówno w
kontrolach Docker release-path, jak i Package Acceptance. Utrzymuje to wszystkie
test boxes skierowane na paczkę na tych samych bajtach i unika powtarzania buildów paczki.
Cross-OS OpenAI install smoke używa `OPENCLAW_CROSS_OS_OPENAI_MODEL`, gdy
zmienna repo/org jest ustawiona, w przeciwnym razie `openai/gpt-5.4-mini`, ponieważ ta ścieżka
udowadnia instalację paczki, onboarding, start Gateway i jedną turę live agenta
zamiast benchmarkować najwolniejszy model domyślny. Szersza macierz live provider
`OpenClaw Release Checks` używa zaufanego odwołania workflow do jednokrotnego rozwiązania docelowego
odwołania jako `release-package-under-test` i ponownie używa tego artefaktu zarówno w
sprawdzeniach Dockera dla ścieżki wydania, jak i w Akceptacji pakietu. Dzięki temu wszystkie
środowiska dotyczące pakietu pracują na tych samych bajtach i unika się wielokrotnego budowania pakietu.
Cross-OS smoke test instalacji OpenAI używa `OPENCLAW_CROSS_OS_OPENAI_MODEL`, gdy ustawiona jest
zmienna repozytorium/organizacji, w przeciwnym razie `openai/gpt-5.4-mini`, ponieważ ta ścieżka
potwierdza instalację pakietu, onboarding, uruchomienie gatewaya i jedną żywą turę agenta,
a nie benchmark najwolniejszego modelu domyślnego. Szersza macierz żywych providerów
pozostaje miejscem dla pokrycia specyficznego dla modeli.
Użyj tych wariantów zależnie od etapu wydania:
@ -310,39 +219,39 @@ gh workflow run full-release-validation.yml \
```
Nie używaj pełnego parasola jako pierwszego ponownego uruchomienia po ukierunkowanej poprawce. Jeśli jedno środowisko
zawiedzie, użyj nieudanego przepływu podrzędnego, zadania, ścieżki Docker, profilu pakietu, dostawcy
modelu albo ścieżki QA jako następnego dowodu. Uruchom pełny parasol ponownie tylko wtedy, gdy
poprawka zmieniła wspólną orkiestrację wydania albo sprawiła, że wcześniejsze dowody ze wszystkich środowisk
zawiedzie, użyj nieudanego workflow podrzędnego, zadania, ścieżki Dockera, profilu pakietu, providera
modelu lub ścieżki QA jako kolejnego potwierdzenia. Uruchom pełny parasol ponownie tylko wtedy, gdy
poprawka zmieniła współdzieloną orkiestrację wydania albo sprawiła, że wcześniejsze dowody ze wszystkich środowisk
stały się nieaktualne. Końcowy weryfikator parasola ponownie sprawdza zapisane identyfikatory uruchomień
podrzędnych przepływów, więc po pomyślnym ponownym uruchomieniu podrzędnego przepływu uruchom ponownie tylko nieudane
nadrzędne zadanie `Verify full validation`.
workflow podrzędnych, więc po pomyślnym ponownym uruchomieniu workflow podrzędnego uruchom ponownie tylko nieudane
zadanie nadrzędne `Verify full validation`.
W celu ograniczonego odzyskiwania przekaż `rerun_group` do parasola. `all` to rzeczywiste
uruchomienie kandydata do wydania, `ci` uruchamia tylko zwykły podrzędny CI, `plugin-prerelease`
uruchamia tylko podrzędny release-only plugin, `release-checks` uruchamia każde środowisko wydaniowe,
a węższe grupy wydaniowe to `install-smoke`, `cross-os`,
Dla ograniczonego odzyskiwania przekaż `rerun_group` do parasola. `all` to właściwe
uruchomienie kandydata do wydania, `ci` uruchamia tylko zwykłe podrzędne CI, `plugin-prerelease`
uruchamia tylko podrzędne zadanie pluginu właściwe dla wydania, `release-checks` uruchamia każde środowisko
wydania, a węższe grupy wydania to `install-smoke`, `cross-os`,
`live-e2e`, `package`, `qa`, `qa-parity`, `qa-live` i `npm-telegram`, gdy
dostarczona jest samodzielna ścieżka pakietowa Telegram.
dostarczona jest samodzielna ścieżka pakietu Telegram.
### Vitest
Środowisko Vitest to ręczny podrzędny przepływ `CI`. Ręczne CI celowo
omija zakresowanie zmian i wymusza zwykły graf testów dla kandydata do wydania:
shardy Linux Node, shardy bundled-plugin, kontrakty kanałów, zgodność Node 22,
`check`, `check-additional`, build smoke, sprawdzenia dokumentacji, Python
skills, Windows, macOS, Android i Control UI i18n.
Środowisko Vitest to ręczny podrzędny workflow `CI`. Ręczne CI celowo
pomija zakresowanie zmian i wymusza zwykły graf testów dla kandydata
do wydania: shardy Linux Node, shardy bundled-plugin, kontrakty kanałów, zgodność z Node 22,
`check`, `check-additional`, smoke test buildu, sprawdzenia dokumentacji, Python
skills, Windows, macOS, Android i i18n Control UI.
Użyj tego środowiska, aby odpowiedzieć na pytanie „czy drzewo źródeł przeszło pełny zwykły zestaw testów?”.
To nie jest to samo co walidacja produktu ścieżki wydaniowej. Zachowaj dowody:
Użyj tego środowiska, aby odpowiedzieć na pytanie „czy drzewo źródeł przeszło pełny normalny zestaw testów?”.
Nie jest to to samo co walidacja produktu na ścieżce wydania. Dowody do zachowania:
- podsumowanie `Full Release Validation` pokazujące URL uruchomionego `CI`
- zielony przebieg `CI` na dokładnym docelowym SHA
- zielone uruchomienie `CI` na dokładnym docelowym SHA
- nazwy nieudanych lub wolnych shardów z zadań CI podczas badania regresji
- artefakty czasów Vitest, takie jak `.artifacts/vitest-shard-timings.json`, gdy
uruchomienie wymaga analizy wydajności
Uruchamiaj ręczne CI bezpośrednio tylko wtedy, gdy wydanie potrzebuje deterministycznego zwykłego CI, ale
nie środowisk Docker, QA Lab, live, cross-OS ani pakietowych:
nie środowisk Dockera, QA Lab, live, cross-OS ani pakietowych:
```bash
gh workflow run ci.yml --ref main -f target_ref=release/YYYY.M.D
@ -351,17 +260,17 @@ gh workflow run ci.yml --ref main -f target_ref=release/YYYY.M.D
### Docker
Środowisko Docker znajduje się w `OpenClaw Release Checks` przez
`openclaw-live-and-e2e-checks-reusable.yml`, plus przepływ `install-smoke`
w trybie wydaniowym. Waliduje ono kandydata do wydania przez spakowane
środowiska Docker, a nie wyłącznie testy na poziomie źródeł.
`openclaw-live-and-e2e-checks-reusable.yml` oraz workflow `install-smoke`
w trybie wydania. Waliduje ono kandydata do wydania przez spakowane
środowiska Dockera, a nie tylko testy na poziomie źródeł.
Zakres wydaniowy Docker obejmuje:
Pokrycie Dockera dla wydania obejmuje:
- pełny install smoke z włączonym wolnym Bun global install smoke
- pełny smoke test instalacji z włączonym wolnym smoke testem globalnej instalacji Bun
- przygotowanie/ponowne użycie obrazu smoke głównego Dockerfile według docelowego SHA, z zadaniami QR,
root/gateway oraz installer/Bun smoke uruchamianymi jako osobne shardy install-smoke
- ścieżki E2E repozytorium
- wydaniowe fragmenty Docker: `core`, `package-update-openai`,
- części Dockera dla ścieżki wydania: `core`, `package-update-openai`,
`package-update-anthropic`, `package-update-core`, `plugins-runtime-plugins`,
`plugins-runtime-services`,
`plugins-runtime-install-a`, `plugins-runtime-install-b`,
@ -371,82 +280,82 @@ Zakres wydaniowy Docker obejmuje:
`bundled-channels-core`, `bundled-channels-update-a`,
`bundled-channels-update-discord`, `bundled-channels-update-b` i
`bundled-channels-contracts`
- pokrycie OpenWebUI we fragmencie `plugins-runtime-services`, gdy jest wymagane
- podzielone ścieżki zależności bundled-channel między fragmenty channel-smoke, update-target
i kontraktów setup/runtime zamiast jednego dużego zadania bundled-channel
- podzielone ścieżki instalacji/odinstalowania bundled plugin
`bundled-plugin-install-uninstall-0` do
- pokrycie OpenWebUI wewnątrz części `plugins-runtime-services`, gdy jest wymagane
- podzielone ścieżki zależności bundled-channel na channel-smoke, update-target
i części kontraktów setup/runtime zamiast jednego dużego zadania bundled-channel
- podzielone ścieżki instalacji/deinstalacji bundled pluginów
od `bundled-plugin-install-uninstall-0` do
`bundled-plugin-install-uninstall-23`
- zestawy dostawców live/E2E i pokrycie modelu live Docker, gdy sprawdzenia wydaniowe
- zestawy live/E2E providerów oraz pokrycie modeli Docker live, gdy sprawdzenia wydania
obejmują zestawy live
Użyj artefaktów Docker przed ponownym uruchomieniem. Harmonogram ścieżki wydaniowej przesyła
Użyj artefaktów Dockera przed ponownym uruchomieniem. Harmonogram ścieżki wydania przesyła
`.artifacts/docker-tests/` z logami ścieżek, `summary.json`, `failures.json`,
czasami faz, JSON planu harmonogramu i poleceniami ponownego uruchomienia. Do ukierunkowanego odzyskiwania
użyj `docker_lanes=<lane[,lane]>` w wielokrotnego użytku przepływie live/E2E zamiast
ponownego uruchamiania wszystkich fragmentów wydaniowych. Wygenerowane polecenia ponownego uruchomienia zawierają wcześniejsze
`package_artifact_run_id` i przygotowane dane wejściowe obrazu Docker, gdy są dostępne, dzięki czemu
nieudana ścieżka może ponownie użyć tej samej paczki tarball i obrazów GHCR.
czasami faz, JSON-em planu harmonogramu i poleceniami ponownego uruchomienia. Do ukierunkowanego odzyskiwania
użyj `docker_lanes=<lane[,lane]>` w wielokrotnego użytku workflow live/E2E zamiast
ponownie uruchamiać wszystkie części wydania. Wygenerowane polecenia ponownego uruchomienia zawierają wcześniejsze
`package_artifact_run_id` i przygotowane wejścia obrazu Dockera, gdy są dostępne, więc
nieudana ścieżka może ponownie użyć tego samego tarballa i obrazów GHCR.
### QA Lab
Środowisko QA Lab jest również częścią `OpenClaw Release Checks`. Jest to agentic
bramka wydaniowa zachowania i poziomu kanałów, oddzielna od Vitest i mechaniki pakietów Docker.
Środowisko QA Lab jest także częścią `OpenClaw Release Checks`. Jest to bramka wydania
dla zachowania agentowego i poziomu kanałów, oddzielna od mechaniki pakietów Vitest i Docker.
Zakres wydaniowy QA Lab obejmuje:
Pokrycie QA Lab dla wydania obejmuje:
- bramkę mock parity porównującą ścieżkę kandydata OpenAI z bazą Opus 4.6
przy użyciu pakietu agentic parity
- bramkę parytetu mock porównującą kandydującą ścieżkę OpenAI z bazą Opus 4.6
przy użyciu agentowego pakietu parytetu
- szybki profil live Matrix QA używający środowiska `qa-live-shared`
- ścieżkę live Telegram QA używającą dzierżaw poświadczeń Convex CI
- `pnpm qa:otel:smoke`, gdy telemetria wydania wymaga jawnego lokalnego dowodu
- `pnpm qa:otel:smoke`, gdy telemetria wydania wymaga jawnego lokalnego potwierdzenia
Użyj tego środowiska, aby odpowiedzieć na pytanie „czy wydanie zachowuje się poprawnie w scenariuszach QA i
przepływach kanałów live?”. Zachowaj URL-e artefaktów dla ścieżek parity, Matrix i Telegram
przepływach kanałów live?” Zachowaj URL-e artefaktów dla ścieżek parytetu, Matrix i Telegram
podczas zatwierdzania wydania. Pełne pokrycie Matrix pozostaje dostępne jako
ręczne shardowane uruchomienie QA-Lab, a nie domyślna ścieżka krytyczna dla wydania.
ręczny shardowany przebieg QA-Lab, a nie domyślna ścieżka krytyczna dla wydania.
### Package
### Pakiet
Środowisko Package to bramka produktu instalowalnego. Jest obsługiwane przez
Środowisko pakietu jest bramką produktu instalowalnego. Jest obsługiwane przez
`Package Acceptance` i resolver
`scripts/resolve-openclaw-package-candidate.mjs`. Resolver normalizuje
kandydata do tarballa `package-under-test` używanego przez Docker E2E, waliduje
kandydata do tarballa `package-under-test` konsumowanego przez Docker E2E, waliduje
inwentarz pakietu, zapisuje wersję pakietu i SHA-256 oraz utrzymuje
ref uprzęży przepływu oddzielnie od ref źródła pakietu.
odwołanie uprzęży workflow oddzielnie od odwołania źródła pakietu.
Obsługiwane źródła kandydatów:
- `source=npm`: `openclaw@beta`, `openclaw@latest` albo dokładna wersja wydania OpenClaw
- `source=ref`: spakuj zaufaną gałąź `package_ref`, tag albo pełny SHA commita
- `source=ref`: spakuj zaufaną gałąź `package_ref`, tag albo pełne SHA commita
z wybraną uprzężą `workflow_ref`
- `source=url`: pobierz HTTPS `.tgz` z wymaganym `package_sha256`
- `source=artifact`: użyj ponownie `.tgz` przesłanego przez inne uruchomienie GitHub Actions
- `source=artifact`: ponownie użyj `.tgz` przesłanego przez inne uruchomienie GitHub Actions
`OpenClaw Release Checks` uruchamia Package Acceptance z `source=ref`,
`OpenClaw Release Checks` uruchamia Akceptację pakietu z `source=ref`,
`package_ref=<release-ref>`, `suite_profile=custom`,
`docker_lanes=bundled-channel-deps-compat plugins-offline` oraz
`telegram_mode=mock-openai`. Wydaniowe fragmenty Docker pokrywają
nakładające się ścieżki instalacji, aktualizacji i aktualizacji pluginów; Package Acceptance utrzymuje
natywną dla artefaktów zgodność bundled-channel, offline'owe fixture'y pluginów oraz Telegram
package QA względem tego samego rozwiązanego tarballa. Jest to natywny dla GitHub
zamiennik większości pokrycia pakietów/aktualizacji, które wcześniej wymagało
Parallels. Sprawdzenia wydaniowe cross-OS nadal mają znaczenie dla specyficznego dla OS onboardingu,
instalatora i zachowania platformy, ale walidacja produktu pakietu/aktualizacji powinna
preferować Package Acceptance.
`docker_lanes=bundled-channel-deps-compat plugins-offline` i
`telegram_mode=mock-openai`. Części Dockera na ścieżce wydania pokrywają
nakładające się ścieżki instalacji, aktualizacji i aktualizacji pluginów; Akceptacja pakietu zachowuje
natywną dla artefaktów zgodność bundled-channel, offline fixtures pluginów oraz pakietowe QA Telegram
wobec tego samego rozwiązanego tarballa. Jest to natywny dla GitHuba
zamiennik większości pokrycia pakiet/aktualizacja, które wcześniej wymagało
Parallels. Cross-OS checks wydania nadal mają znaczenie dla onboardingu,
instalatora i zachowania platformy specyficznych dla OS, ale walidacja produktu pakiet/aktualizacja powinna
preferować Akceptację pakietu.
Łagodność starszego package-acceptance jest celowo ograniczona czasowo. Pakiety do
Dziedziczna pobłażliwość package-acceptance jest celowo ograniczona czasowo. Pakiety do
`2026.4.25` mogą używać ścieżki zgodności dla luk metadanych już opublikowanych
do npm: prywatne wpisy inwentarza QA brakujące w tarballu, brakujące
`gateway install --wrapper`, brakujące pliki łatek w fixture git pochodzącym z tarballa,
brak utrwalonego `update.channel`, starsze lokalizacje rekordów instalacji pluginów,
brak utrwalania rekordów instalacji marketplace oraz migracja metadanych konfiguracji
w npm: prywatnych wpisów inwentarza QA brakujących w tarballu, brakującego
`gateway install --wrapper`, brakujących plików łatek w fixture git pochodzącym z tarballa,
brakującego utrwalonego `update.channel`, dziedzicznych lokalizacji rekordów instalacji pluginów,
brakującego utrwalania rekordów instalacji marketplace oraz migracji metadanych konfiguracji
podczas `plugins update`. Opublikowany pakiet `2026.4.26` może ostrzegać
dla lokalnych plików stempli metadanych builda, które zostały już wysłane. Późniejsze pakiety
o lokalnych plikach znaczników metadanych buildu, które zostały już wydane. Późniejsze pakiety
muszą spełniać nowoczesne kontrakty pakietów; te same luki powodują niepowodzenie walidacji
wydania.
Użyj szerszych profili Package Acceptance, gdy pytanie wydaniowe dotyczy
Używaj szerszych profili Akceptacji pakietu, gdy pytanie wydania dotyczy
rzeczywistego instalowalnego pakietu:
```bash
@ -455,87 +364,91 @@ gh workflow run package-acceptance.yml \
-f workflow_ref=main \
-f source=npm \
-f package_spec=openclaw@beta \
-f suite_profile=product
-f suite_profile=product \
-f published_upgrade_survivor_baseline=openclaw@2026.4.26
```
Typowe profile pakietów:
- `smoke`: szybkie ścieżki instalacji pakietu/kanału/agenta, sieci Gateway i przeładowania
konfiguracji
- `package`: kontrakty instalacji/aktualizacji/pakietów pluginów bez live ClawHub; to jest domyślne
sprawdzenie wydaniowe
- `smoke`: szybkie ścieżki instalacji pakietu/kanału/agenta, sieci gatewaya i
przeładowania konfiguracji
- `package`: kontrakty instalacji/aktualizacji/pakietów pluginów bez live ClawHub; to jest domyślna wartość
release-check
- `product`: `package` plus kanały MCP, czyszczenie cron/subagent, wyszukiwanie webowe OpenAI
i OpenWebUI
- `full`: wydaniowe fragmenty Docker z OpenWebUI
- `custom`: dokładna lista `docker_lanes` do ukierunkowanych ponownych uruchomień
- `full`: części ścieżki wydania Docker z OpenWebUI
- `custom`: dokładna lista `docker_lanes` dla ukierunkowanych ponownych uruchomień
Dla dowodu Telegram kandydata pakietu włącz `telegram_mode=mock-openai` albo
`telegram_mode=live-frontier` w Package Acceptance. Przepływ przekazuje
Dla pakietowego potwierdzenia Telegram kandydata włącz `telegram_mode=mock-openai` albo
`telegram_mode=live-frontier` w Akceptacji pakietu. Workflow przekazuje
rozwiązany tarball `package-under-test` do ścieżki Telegram; samodzielny
przepływ Telegram nadal akceptuje opublikowaną specyfikację npm do sprawdzeń po publikacji.
workflow Telegram nadal akceptuje opublikowaną specyfikację npm dla sprawdzeń po publikacji.
## Dane wejściowe przepływu NPM
## Wejścia workflow NPM
`OpenClaw NPM Release` przyjmuje te dane wejściowe kontrolowane przez operatora:
`OpenClaw NPM Release` akceptuje te wejścia kontrolowane przez operatora:
- `tag`: wymagany tag wydania, taki jak `v2026.4.2`, `v2026.4.2-1` albo
`v2026.4.2-beta.1`; gdy `preflight_only=true`, może to być także bieżący
pełny 40-znakowy SHA commita gałęzi przepływu do preflightu wyłącznie walidacyjnego
- `preflight_only`: `true` dla samej walidacji/builda/pakietu, `false` dla
`v2026.4.2-beta.1`; gdy `preflight_only=true`, może to być także obecne
pełne 40-znakowe SHA commita gałęzi workflow do preflight wyłącznie walidacyjnego
- `preflight_only`: `true` dla samej walidacji/buildu/pakietu, `false` dla
rzeczywistej ścieżki publikacji
- `preflight_run_id`: wymagane na rzeczywistej ścieżce publikacji, aby przepływ ponownie użył
przygotowanego tarballa z udanego uruchomienia preflight
- `preflight_run_id`: wymagane na rzeczywistej ścieżce publikacji, aby workflow ponownie użył
przygotowanego tarballa z pomyślnego uruchomienia preflight
- `npm_dist_tag`: docelowy tag npm dla ścieżki publikacji; domyślnie `beta`
`OpenClaw Release Checks` przyjmuje te dane wejściowe kontrolowane przez operatora:
`OpenClaw Release Checks` akceptuje te wejścia kontrolowane przez operatora:
- `ref`: gałąź, tag albo pełny SHA commita do zwalidowania. Sprawdzenia używające sekretów
- `ref`: gałąź, tag albo pełne SHA commita do walidacji. Sprawdzenia zawierające sekrety
wymagają, aby rozwiązany commit był osiągalny z gałęzi OpenClaw albo
tagu wydania.
Reguły:
Zasady:
- Stabilne tagi i tagi poprawek mogą publikować do `beta` albo `latest`
- Tagi przedwydań beta mogą publikować tylko do `beta`
- Tagi stabilne i korekcyjne mogą publikować do `beta` albo `latest`
- Tagi prerelease beta mogą publikować tylko do `beta`
- Dla `OpenClaw NPM Release` wejście pełnego SHA commita jest dozwolone tylko wtedy, gdy
`preflight_only=true`
- `OpenClaw Release Checks` i `Full Release Validation` są zawsze
wyłącznie walidacyjne
- Rzeczywista ścieżka publikacji musi używać tego samego `npm_dist_tag`, którego użyto podczas preflightu;
przepływ weryfikuje te metadane przed kontynuacją publikacji
- Rzeczywista ścieżka publikacji musi używać tego samego `npm_dist_tag`, który był użyty podczas preflight;
workflow weryfikuje te metadane przed kontynuowaniem publikacji
## Sekwencja stabilnego wydania npm
Podczas przygotowywania stabilnego wydania npm:
1. Uruchom `OpenClaw NPM Release` z `preflight_only=true`
- Zanim istnieje tag, możesz użyć bieżącego pełnego SHA commita gałęzi przepływu
do walidacyjnego suchego przebiegu przepływu preflight
2. Wybierz `npm_dist_tag=beta` dla zwykłego przepływu najpierw-beta albo `latest` tylko
- Zanim istnieje tag, możesz użyć bieżącego pełnego SHA commita gałęzi
workflow do suchego przebiegu walidacyjnego workflow preflight-only
2. Wybierz `npm_dist_tag=beta` dla normalnego przepływu beta-first albo `latest` tylko
wtedy, gdy celowo chcesz bezpośrednio opublikować stabilne wydanie
3. Uruchom `Full Release Validation` na gałęzi wydania, tagu wydania albo pełnym
SHA commita, gdy chcesz zwykłego CI plus pokrycia live prompt cache, Docker, QA Lab,
Matrix i Telegram z jednego ręcznego przepływu
4. Jeśli celowo potrzebujesz tylko deterministycznego zwykłego grafu testów, uruchom
ręczny przepływ `CI` na ref wydania
5. Zapisz udany `preflight_run_id`
SHA commita, gdy chcesz normalne CI oraz pokrycie live prompt cache, Docker, QA Lab,
Matrix i Telegram z jednego ręcznego workflow
4. Jeśli celowo potrzebujesz tylko deterministycznego normalnego grafu testów, uruchom
zamiast tego ręczny workflow `CI` na refie wydania
5. Zapisz pomyślny `preflight_run_id`
6. Uruchom `OpenClaw NPM Release` ponownie z `preflight_only=false`, tym samym
`tag`, tym samym `npm_dist_tag` i zapisanym `preflight_run_id`
7. Jeśli wydanie trafiło na `beta`, użyj prywatnego przepływu
7. Jeśli wydanie trafiło na `beta`, użyj prywatnego workflow
`openclaw/releases-private/.github/workflows/openclaw-npm-dist-tags.yml`,
aby wypromować tę stabilną wersję z `beta` do `latest`
8. Jeśli wydanie celowo opublikowano bezpośrednio do `latest`, a `beta`
ma natychmiast wskazywać ten sam stabilny build, użyj tego samego prywatnego
przepływu, aby skierować oba dist-tagi na stabilną wersję, albo pozwól jego zaplanowanej
powinna od razu wskazywać tę samą stabilną kompilację, użyj tego samego prywatnego
workflow, aby skierować oba dist-tagi na stabilną wersję, albo pozwól jego zaplanowanej
samonaprawiającej synchronizacji przenieść `beta` później
Mutacja dist-tag znajduje się w prywatnym repozytorium ze względów bezpieczeństwa, ponieważ nadal
wymaga `NPM_TOKEN`, podczas gdy repozytorium publiczne utrzymuje publikowanie wyłącznie przez OIDC.
Mutacja dist-tagów znajduje się w prywatnym repo ze względów bezpieczeństwa, ponieważ nadal
wymaga `NPM_TOKEN`, podczas gdy publiczne repo zachowuje publikowanie wyłącznie przez OIDC.
Dzięki temu zarówno bezpośrednia ścieżka publikacji, jak i ścieżka promocji najpierw-beta
pozostają udokumentowane i widoczne dla operatora.
Dzięki temu zarówno ścieżka bezpośredniej publikacji, jak i ścieżka promocji beta-first
są udokumentowane i widoczne dla operatora.
Jeśli opiekun musi awaryjnie użyć lokalnego uwierzytelniania npm, uruchamiaj wszystkie polecenia CLI 1Password (`op`) tylko w dedykowanej sesji tmux. Nie wywołuj `op` bezpośrednio z głównej powłoki agenta; utrzymanie go w tmux sprawia, że monity, alerty i obsługa OTP są obserwowalne oraz zapobiega powtarzającym się alertom hosta.
Jeśli maintainer musi awaryjnie użyć lokalnego uwierzytelniania npm, uruchamiaj wszystkie
polecenia CLI 1Password (`op`) tylko w dedykowanej sesji tmux. Nie wywołuj `op`
bezpośrednio z głównej powłoki agenta; trzymanie go w tmux sprawia, że prompty,
alerty i obsługa OTP są obserwowalne oraz zapobiega powtarzającym się alertom hosta.
## Publiczne odwołania
@ -549,9 +462,9 @@ Jeśli opiekun musi awaryjnie użyć lokalnego uwierzytelniania npm, uruchamiaj
- [`scripts/package-mac-dist.sh`](https://github.com/openclaw/openclaw/blob/main/scripts/package-mac-dist.sh)
- [`scripts/make_appcast.sh`](https://github.com/openclaw/openclaw/blob/main/scripts/make_appcast.sh)
Opiekunowie używają prywatnej dokumentacji wydań w
Maintainerzy używają prywatnej dokumentacji wydań w
[`openclaw/maintainers/release/README.md`](https://github.com/openclaw/maintainers/blob/main/release/README.md)
jako właściwej instrukcji operacyjnej.
jako właściwego runbooka.
## Powiązane

162
docs/pl/reference/full-release-validation.md Normal file
View File

@ -0,0 +1,162 @@
---
read_when:
- Uruchamianie lub ponowne uruchamianie pełnej walidacji wydania
- Porównanie stabilnego i pełnego profilu walidacji wydania
- Debugowanie niepowodzeń etapu walidacji wydania
summary: Etapy pełnej walidacji wydania, podrzędne przepływy pracy, profile wydania, uchwyty ponownego uruchamiania i dowody
title: Pełna walidacja wydania
x-i18n:
generated_at: "2026-05-01T10:02:27Z"
model: gpt-5.5
provider: openai
source_hash: dcbfafd744437c160c09a9c508a639781549193669b300e5249023f9f5dd4afe
source_path: reference/full-release-validation.md
workflow: 16
---
`Full Release Validation` jest nadrzędnym procesem wydania. Jest to pojedynczy ręczny
punkt wejścia dla potwierdzenia przedwydaniowego, ale większość pracy odbywa się w przepływach potomnych, aby
nieudaną maszynę można było uruchomić ponownie bez restartowania całego wydania.
Uruchom go z zaufanego odwołania przepływu pracy, zwykle `main`, i przekaż gałąź wydania,
tag lub pełny SHA commita jako `ref`:
```bash
gh workflow run full-release-validation.yml \
--ref main \
-f ref=release/YYYY.M.D \
-f provider=openai \
-f mode=both \
-f release_profile=stable
```
Przepływy potomne używają zaufanego odwołania przepływu pracy dla uprzęży oraz wejściowego
`ref` dla testowanego kandydata. Dzięki temu nowa logika walidacji pozostaje dostępna
podczas walidowania starszej gałęzi wydania lub tagu.
## Etapy najwyższego poziomu
| Etap | Szczegóły |
| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Rozwiązywanie celu | **Zadanie:** `Resolve target ref`<br />**Przepływ potomny:** brak<br />**Potwierdza:** rozwiązuje gałąź wydania, tag lub pełny SHA commita i zapisuje wybrane dane wejściowe.<br />**Ponowne uruchomienie:** uruchom ponownie proces nadrzędny, jeśli to się nie powiedzie. |
| Vitest i zwykłe CI | **Zadanie:** `Run normal full CI`<br />**Przepływ potomny:** `CI`<br />**Potwierdza:** ręczny pełny graf CI względem docelowego ref, w tym ścieżki Linux Node, shardy wbudowanych Plugin, kontrakty kanałów, zgodność z Node 22, `check`, `check-additional`, smoke test kompilacji, kontrole dokumentacji, Python skills, Windows, macOS, i18n Control UI oraz Android przez proces nadrzędny.<br />**Ponowne uruchomienie:** `rerun_group=ci`. |
| Przedwydanie Plugin | **Zadanie:** `Run plugin prerelease validation`<br />**Przepływ potomny:** `Plugin Prerelease`<br />**Potwierdza:** kontrole statyczne Plugin tylko dla wydania, agentowe pokrycie Plugin, pełne shardy partii rozszerzeń oraz ścieżki Docker przedwydania Plugin.<br />**Ponowne uruchomienie:** `rerun_group=plugin-prerelease`. |
| Kontrole wydania | **Zadanie:** `Run release/live/Docker/QA validation`<br />**Przepływ potomny:** `OpenClaw Release Checks`<br />**Potwierdza:** smoke test instalacji, kontrole pakietów między systemami, zestawy live/E2E, fragmenty ścieżki wydania Docker, Package Acceptance, parytet QA Lab, live Matrix oraz live Telegram.<br />**Ponowne uruchomienie:** `rerun_group=release-checks` lub węższy uchwyt release-checks. |
| Telegram po publikacji | **Zadanie:** `Run post-publish Telegram E2E`<br />**Przepływ potomny:** `NPM Telegram Beta E2E`<br />**Potwierdza:** opcjonalne potwierdzenie Telegram dla opublikowanego pakietu, gdy ustawiono `npm_telegram_package_spec`.<br />**Ponowne uruchomienie:** `rerun_group=npm-telegram`. |
| Weryfikator nadrzędny | **Zadanie:** `Verify full validation`<br />**Przepływ potomny:** brak<br />**Potwierdza:** ponownie sprawdza zapisane wyniki przebiegów potomnych i dołącza tabele najwolniejszych zadań z przepływów potomnych.<br />**Ponowne uruchomienie:** uruchom ponownie tylko to zadanie po doprowadzeniu nieudanego przepływu potomnego do stanu zielonego. |
Dla `ref=main` i `rerun_group=all` nowszy proces nadrzędny zastępuje starszy.
Gdy rodzic zostanie anulowany, jego monitor anuluje każdy przepływ potomny, który już
uruchomił. Przebiegi walidacji gałęzi wydania i tagów domyślnie nie anulują się wzajemnie.
## Etapy kontroli wydania
`OpenClaw Release Checks` to największy przepływ potomny. Raz rozwiązuje cel
i przygotowuje współdzielony artefakt `release-package-under-test`, gdy potrzebują go etapy
związane z pakietem lub Dockerem.
| Etap | Szczegóły |
| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Cel wydania | **Zadanie:** `Resolve target ref`<br />**Przepływ bazowy:** brak<br />**Testuje:** wybrany ref, opcjonalny oczekiwany SHA, profil, grupę ponownego uruchomienia oraz ukierunkowany filtr zestawu live.<br />**Ponowne uruchomienie:** `rerun_group=release-checks`. |
| Artefakt pakietu | **Zadanie:** `Prepare release package artifact`<br />**Przepływ bazowy:** brak<br />**Testuje:** pakuje lub rozwiązuje jeden kandydacki tarball i przesyła `release-package-under-test` dla dalszych kontroli związanych z pakietem.<br />**Ponowne uruchomienie:** dotknięta grupa pakietu, cross-OS lub live/E2E. |
| Smoke test instalacji | **Zadanie:** `Run install smoke`<br />**Przepływ bazowy:** `Install Smoke`<br />**Testuje:** pełną ścieżkę instalacji z ponownym użyciem obrazu smoke z głównego Dockerfile, instalację pakietu QR, smoke testy głównego i gateway Docker, testy Docker instalatora, smoke test globalnej instalacji Bun z dostawcą obrazu oraz szybkie Docker E2E wbudowanych Plugin.<br />**Ponowne uruchomienie:** `rerun_group=install-smoke`. |
| Cross-OS | **Zadanie:** `cross_os_release_checks`<br />**Przepływ bazowy:** `OpenClaw Cross-OS Release Checks (Reusable)`<br />**Testuje:** ścieżki świeżej instalacji i aktualizacji na Linux, Windows i macOS dla wybranego dostawcy i trybu, używając kandydackiego tarballa oraz pakietu bazowego.<br />**Ponowne uruchomienie:** `rerun_group=cross-os`. |
| Repozytorium i live E2E | **Zadanie:** `Run repo/live E2E validation`<br />**Przepływ bazowy:** `OpenClaw Live And E2E Checks (Reusable)`<br />**Testuje:** repozytoryjne E2E, cache live, streaming websocket OpenAI, natywnego dostawcę live i shardy Plugin oraz uprzęże live model/backend/gateway oparte na Dockerze wybrane przez `release_profile`.<br />**Ponowne uruchomienie:** `rerun_group=live-e2e`, opcjonalnie z `live_suite_filter`. |
| Ścieżka wydania Docker | **Zadanie:** `Run Docker release-path validation`<br />**Przepływ bazowy:** `OpenClaw Live And E2E Checks (Reusable)`<br />**Testuje:** fragmenty Docker ścieżki wydania względem współdzielonego artefaktu pakietu.<br />**Ponowne uruchomienie:** `rerun_group=live-e2e`. |
| Package Acceptance | **Zadanie:** `Run package acceptance`<br />**Przepływ bazowy:** `Package Acceptance`<br />**Testuje:** natywną dla artefaktu zgodność zależności wbudowanych kanałów, offline'owe fixture'y pakietów Plugin oraz akceptację pakietu Telegram mock-OpenAI względem tego samego tarballa.<br />**Ponowne uruchomienie:** `rerun_group=package`. |
| Parytet QA | **Zadanie:** `Run QA Lab parity lane` i `Run QA Lab parity report`<br />**Przepływ bazowy:** bezpośrednie zadania<br />**Testuje:** agentowe pakiety parytetu kandydata i baseline, a następnie raport parytetu.<br />**Ponowne uruchomienie:** `rerun_group=qa-parity` lub `rerun_group=qa`. |
| Live Matrix QA | **Zadanie:** `Run QA Lab live Matrix lane`<br />**Przepływ bazowy:** bezpośrednie zadanie<br />**Testuje:** szybki profil live Matrix QA w środowisku `qa-live-shared`.<br />**Ponowne uruchomienie:** `rerun_group=qa-live` lub `rerun_group=qa`. |
| Live Telegram QA | **Zadanie:** `Run QA Lab live Telegram lane`<br />**Przepływ bazowy:** bezpośrednie zadanie<br />**Testuje:** live Telegram QA z dzierżawami poświadczeń Convex CI.<br />**Ponowne uruchomienie:** `rerun_group=qa-live` lub `rerun_group=qa`. |
| Weryfikator wydania | **Zadanie:** `Verify release checks`<br />**Przepływ bazowy:** brak<br />**Testuje:** wymagane zadania kontroli wydania dla wybranej grupy ponownego uruchomienia.<br />**Ponowne uruchomienie:** uruchom ponownie po przejściu ukierunkowanych zadań potomnych. |
## Fragmenty ścieżki wydania Docker
Etap ścieżki wydania Docker uruchamia te fragmenty, gdy `live_suite_filter` jest
pusty:
| Fragment | Pokrycie |
| ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
| `core` | Główne ścieżki smoke wydania Docker. |
| `package-update-openai` | Instalacja pakietu OpenAI i zachowanie aktualizacji. |
| `package-update-anthropic` | Instalacja pakietu Anthropic i zachowanie aktualizacji. |
| `package-update-core` | Neutralny względem dostawcy pakiet i zachowanie aktualizacji. |
| `plugins-runtime-plugins` | Ścieżki środowiska uruchomieniowego Plugin, które ćwiczą zachowanie Plugin. |
| `plugins-runtime-services` | Ścieżki środowiska uruchomieniowego Plugin oparte na usługach; obejmuje OpenWebUI, gdy jest wymagane. |
| `plugins-runtime-install-a` przez `plugins-runtime-install-h` | Partie instalacji/środowiska uruchomieniowego Plugin podzielone dla równoległej walidacji wydania. |
| `bundled-channels-core` | Zachowanie Docker wbudowanego kanału. |
| `bundled-channels-update-a`, `bundled-channels-update-discord`, `bundled-channels-update-b` | Zachowanie aktualizacji wbudowanego kanału. |
| `bundled-channels-contracts` | Kontrole kontraktów wbudowanego kanału w ścieżce wydania Docker. |
Użyj ukierunkowanego `docker_lanes=<lane[,lane]>` w wielokrotnego użytku przepływie pracy live/E2E, gdy nie powiodła się tylko jedna ścieżka Docker. Artefakty wydania zawierają polecenia ponownego uruchomienia dla poszczególnych ścieżek z wejściami ponownego użycia artefaktu pakietu i obrazu, gdy są dostępne.
## Profile wydania
`release_profile` kontroluje tylko zakres live/dostawcy w ramach kontroli wydania. Nie usuwa normalnego pełnego CI, Plugin Prerelease, testu instalacji, akceptacji pakietu, QA Lab ani fragmentów ścieżki wydania Docker.
| Profil | Zamierzone użycie | Uwzględniony zakres live/dostawcy |
| --------- | ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `minimum` | Najszybszy krytyczny test wydania. | Ścieżka live OpenAI/core, modele live Docker dla OpenAI, natywny rdzeń Gateway, natywny profil Gateway OpenAI, natywny plugin OpenAI oraz Gateway live Docker OpenAI. |
| `stable` | Domyślny profil zatwierdzania wydania. | `minimum` plus Anthropic, Google, MiniMax, backend, natywna uprząż testów live, backend CLI live Docker, powiązanie ACP Docker, uprząż Codex Docker oraz fragment testu OpenCode Go. |
| `full` | Szeroki przegląd doradczy. | `stable` plus dostawcy doradczy, fragmenty live pluginów oraz fragmenty live multimediów. |
## Dodatki tylko dla full
Te zestawy są pomijane przez `stable` i uwzględniane przez `full`:
| Obszar | Zakres tylko dla full |
| -------------------------------- | ------------------------------------------------------------------------------- |
| Modele live Docker | OpenCode Go, OpenRouter, xAI, Z.ai oraz Fireworks. |
| Gateway live Docker | Fragment doradczy dla DeepSeek, Fireworks, OpenCode Go, OpenRouter, xAI oraz Z.ai. |
| Natywne profile dostawców Gateway | Fireworks, DeepSeek, pełne fragmenty modeli OpenCode Go, OpenRouter, xAI oraz Z.ai. |
| Natywne fragmenty live pluginów | Pluginy A-K, L-N, O-Z inne, Moonshot oraz xAI. |
| Natywne fragmenty live multimediów | Audio, muzyka Google, muzyka MiniMax oraz grupy wideo A-D. |
`stable` obejmuje `native-live-src-gateway-profiles-opencode-go-smoke`; `full`
zamiast tego używa szerszych fragmentów modeli OpenCode Go.
## Ukierunkowane ponowne uruchomienia
Użyj `rerun_group`, aby uniknąć powtarzania niepowiązanych środowisk wydania:
| Identyfikator | Zakres |
| ------------------ | ------------------------------------------------- |
| `all` | Wszystkie etapy Full Release Validation. |
| `ci` | Tylko podrzędny ręczny pełny CI. |
| `plugin-prerelease` | Tylko podrzędny Plugin Prerelease. |
| `release-checks` | Wszystkie etapy OpenClaw Release Checks. |
| `install-smoke` | Install Smoke przez kontrole wydania. |
| `cross-os` | Kontrole wydania Cross-OS. |
| `live-e2e` | Repo/live E2E i walidacja ścieżki wydania Docker. |
| `package` | Package Acceptance. |
| `qa` | Parytet QA plus ścieżki live QA. |
| `qa-parity` | Tylko ścieżki parytetu QA i raport. |
| `qa-live` | Tylko Matrix live QA i Telegram. |
| `npm-telegram` | Tylko opcjonalne E2E Telegram po publikacji. |
Użyj `live_suite_filter` z `rerun_group=live-e2e`, gdy nie powiódł się jeden zestaw live. Prawidłowe identyfikatory filtrów są zdefiniowane w wielokrotnego użytku przepływie pracy live/E2E, w tym `docker-live-models`, `live-gateway-docker`,
`live-gateway-anthropic-docker`, `live-gateway-google-docker`,
`live-gateway-minimax-docker`, `live-gateway-advisory-docker`,
`live-cli-backend-docker`, `live-acp-bind-docker` oraz
`live-codex-harness-docker`.
## Dowody do zachowania
Zachowaj podsumowanie `Full Release Validation` jako indeks na poziomie wydania. Zawiera linki do identyfikatorów podrzędnych uruchomień i obejmuje tabele najwolniejszych zadań. W przypadku awarii najpierw sprawdź podrzędny przepływ pracy, a następnie ponownie uruchom najmniejszy pasujący identyfikator powyżej.
Przydatne artefakty:
- `release-package-under-test` z `OpenClaw Release Checks`
- Artefakty ścieżki wydania Docker w `.artifacts/docker-tests/`
- `package-under-test` z Package Acceptance oraz artefakty akceptacji Docker
- Artefakty kontroli wydania Cross-OS dla każdego systemu operacyjnego i zestawu
- Artefakty parytetu QA, Matrix i Telegram
## Pliki przepływów pracy
- `.github/workflows/full-release-validation.yml`
- `.github/workflows/openclaw-release-checks.yml`
- `.github/workflows/openclaw-live-and-e2e-checks-reusable.yml`
- `.github/workflows/plugin-prerelease.yml`
- `.github/workflows/install-smoke.yml`
- `.github/workflows/openclaw-cross-os-release-checks-reusable.yml`
- `.github/workflows/package-acceptance.yml`

151
docs/pl/reference/secretref-credential-surface.md
View File

@ -3,24 +3,163 @@ read_when:
- Weryfikowanie pokrycia poświadczeń SecretRef
- Audytowanie, czy poświadczenie kwalifikuje się do `secrets configure` lub `secrets apply`
- Weryfikowanie, dlaczego poświadczenie znajduje się poza obsługiwanym zakresem
summary: Kanoniczny zakres obsługiwanych i nieobsługiwanych poświadczeń SecretRef
summary: Kanoniczna obsługiwana i nieobsługiwana powierzchnia poświadczeń SecretRef
title: Interfejs poświadczeń SecretRef
x-i18n:
generated_at: "2026-04-30T10:17:20Z"
generated_at: "2026-05-01T10:03:23Z"
model: gpt-5.5
provider: openai
source_hash: b04902427e9851cc36c1dfd07ed44b46b55450c251075e9955af6696f08bc334
source_hash: 41111ac82142c906005e0f585c86f2ff0b454afdaec07343c295e6b83571718e
source_path: reference/secretref-credential-surface.md
workflow: 16
---
Ta strona definiuje kanoniczną powierzchnię poświadczeń SecretRef.
Zakres:
Intencja zakresu:
- W zakresie: wyłącznie poświadczenia dostarczone przez użytkownika, których OpenClaw nie tworzy ani nie rotuje.
- Poza zakresem: poświadczenia tworzone lub rotowane w czasie działania, materiały odświeżania OAuth oraz artefakty podobne do sesji.
- W zakresie: wyłącznie poświadczenia dostarczone przez użytkownika, których OpenClaw nie wydaje ani nie rotuje.
- Poza zakresem: poświadczenia wydawane w czasie wykonywania lub rotowane, materiały odświeżania OAuth oraz artefakty podobne do sesji.
## Obsługiwane poświadczenia
### Cele `openclaw.json` (`secrets configure` + `secrets apply` + `secrets audit`)
[//]: # "secretref-supported-list-start"
- `models.providers.*.apiKey`
- `models.providers.*.headers.*`
- `models.providers.*.request.auth.token`
- `models.providers.*.request.auth.value`
- `models.providers.*.request.headers.*`
- `models.providers.*.request.proxy.tls.ca`
- `models.providers.*.request.proxy.tls.cert`
- `models.providers.*.request.proxy.tls.key`
- `models.providers.*.request.proxy.tls.passphrase`
- `models.providers.*.request.tls.ca`
- `models.providers.*.request.tls.cert`
- `models.providers.*.request.tls.key`
- `models.providers.*.request.tls.passphrase`
- `skills.entries.*.apiKey`
- `agents.defaults.memorySearch.remote.apiKey`
- `agents.list[].tts.providers.*.apiKey`
- `agents.list[].memorySearch.remote.apiKey`
- `talk.providers.*.apiKey`
- `messages.tts.providers.*.apiKey`
- `tools.web.fetch.firecrawl.apiKey`
- `plugins.entries.acpx.config.mcpServers.*.env.*`
- `plugins.entries.brave.config.webSearch.apiKey`
- `plugins.entries.exa.config.webSearch.apiKey`
- `plugins.entries.google.config.webSearch.apiKey`
- `plugins.entries.xai.config.webSearch.apiKey`
- `plugins.entries.moonshot.config.webSearch.apiKey`
- `plugins.entries.perplexity.config.webSearch.apiKey`
- `plugins.entries.firecrawl.config.webSearch.apiKey`
- `plugins.entries.minimax.config.webSearch.apiKey`
- `plugins.entries.tavily.config.webSearch.apiKey`
- `plugins.entries.voice-call.config.realtime.providers.*.apiKey`
- `plugins.entries.voice-call.config.streaming.providers.*.apiKey`
- `plugins.entries.voice-call.config.tts.providers.*.apiKey`
- `plugins.entries.voice-call.config.twilio.authToken`
- `tools.web.search.apiKey`
- `gateway.auth.password`
- `gateway.auth.token`
- `gateway.remote.token`
- `gateway.remote.password`
- `cron.webhookToken`
- `channels.telegram.botToken`
- `channels.telegram.webhookSecret`
- `channels.telegram.accounts.*.botToken`
- `channels.telegram.accounts.*.webhookSecret`
- `channels.slack.botToken`
- `channels.slack.appToken`
- `channels.slack.userToken`
- `channels.slack.signingSecret`
- `channels.slack.accounts.*.botToken`
- `channels.slack.accounts.*.appToken`
- `channels.slack.accounts.*.userToken`
- `channels.slack.accounts.*.signingSecret`
- `channels.discord.token`
- `channels.discord.pluralkit.token`
- `channels.discord.voice.tts.providers.*.apiKey`
- `channels.discord.accounts.*.token`
- `channels.discord.accounts.*.pluralkit.token`
- `channels.discord.accounts.*.voice.tts.providers.*.apiKey`
- `channels.irc.password`
- `channels.irc.nickserv.password`
- `channels.irc.accounts.*.password`
- `channels.irc.accounts.*.nickserv.password`
- `channels.bluebubbles.password`
- `channels.bluebubbles.accounts.*.password`
- `channels.feishu.appSecret`
- `channels.feishu.encryptKey`
- `channels.feishu.verificationToken`
- `channels.feishu.accounts.*.appSecret`
- `channels.feishu.accounts.*.encryptKey`
- `channels.feishu.accounts.*.verificationToken`
- `channels.msteams.appPassword`
- `channels.mattermost.botToken`
- `channels.mattermost.accounts.*.botToken`
- `channels.matrix.accessToken`
- `channels.matrix.password`
- `channels.matrix.accounts.*.accessToken`
- `channels.matrix.accounts.*.password`
- `channels.nextcloud-talk.botSecret`
- `channels.nextcloud-talk.apiPassword`
- `channels.nextcloud-talk.accounts.*.botSecret`
- `channels.nextcloud-talk.accounts.*.apiPassword`
- `channels.zalo.botToken`
- `channels.zalo.webhookSecret`
- `channels.zalo.accounts.*.botToken`
- `channels.zalo.accounts.*.webhookSecret`
- `channels.googlechat.serviceAccount` za pośrednictwem sąsiedniego `serviceAccountRef` (wyjątek zgodności)
- `channels.googlechat.accounts.*.serviceAccount` za pośrednictwem sąsiedniego `serviceAccountRef` (wyjątek zgodności)
### Cele `auth-profiles.json` (`secrets configure` + `secrets apply` + `secrets audit`)
- `profiles.*.keyRef` (`type: "api_key"`; nieobsługiwane, gdy `auth.profiles.<id>.mode = "oauth"`)
- `profiles.*.tokenRef` (`type: "token"`; nieobsługiwane, gdy `auth.profiles.<id>.mode = "oauth"`)
[//]: # "secretref-supported-list-end"
Uwagi:
- Cele planu profilu uwierzytelniania wymagają `agentId`.
- Wpisy planu celują w `profiles.*.key` / `profiles.*.token` i zapisują sąsiednie odwołania (`keyRef` / `tokenRef`).
- Odwołania profilu uwierzytelniania są uwzględnione w rozwiązywaniu w czasie wykonywania i w pokryciu audytu.
- W `openclaw.json` SecretRefs muszą używać ustrukturyzowanych obiektów, takich jak `{"source":"env","provider":"default","id":"DISCORD_BOT_TOKEN"}`. Starsze ciągi znaczników `secretref-env:<ENV_VAR>` są odrzucane na ścieżkach poświadczeń SecretRef; uruchom `openclaw doctor --fix`, aby zmigrować prawidłowe znaczniki.
- Strażnik zasad OAuth: `auth.profiles.<id>.mode = "oauth"` nie może być łączone z danymi wejściowymi SecretRef dla tego profilu. Uruchomienie/przeładowanie oraz rozwiązywanie profilu uwierzytelniania kończą się szybko błędem, gdy ta zasada zostanie naruszona.
- Dla dostawców modeli zarządzanych przez SecretRef wygenerowane wpisy `agents/*/agent/models.json` utrwalają znaczniki niebędące sekretami (nie rozwiązane wartości sekretów) dla powierzchni `apiKey`/nagłówków.
- Utrwalanie znaczników jest autorytatywne względem źródła: OpenClaw zapisuje znaczniki z aktywnej migawki konfiguracji źródłowej (przed rozwiązaniem), a nie z rozwiązanych wartości sekretów w czasie wykonywania.
- Dla wyszukiwania w sieci:
- W trybie jawnego dostawcy (ustawione `tools.web.search.provider`) aktywny jest tylko klucz wybranego dostawcy.
- W trybie automatycznym (nieustawione `tools.web.search.provider`) aktywny jest tylko pierwszy klucz dostawcy rozwiązany według priorytetu.
- W trybie automatycznym odwołania niewybranych dostawców są traktowane jako nieaktywne, dopóki nie zostaną wybrane.
- Starsze ścieżki dostawców `tools.web.search.*` nadal są rozwiązywane w okresie zgodności, ale kanoniczną powierzchnią SecretRef jest `plugins.entries.<plugin>.config.webSearch.*`.
## Nieobsługiwane poświadczenia
Poświadczenia poza zakresem obejmują:
[//]: # "secretref-unsupported-list-start"
- `commands.ownerDisplaySecret`
- `hooks.token`
- `hooks.gmail.pushToken`
- `hooks.mappings[].sessionKey`
- `auth-profiles.oauth.*`
- `channels.discord.threadBindings.webhookToken`
- `channels.discord.accounts.*.threadBindings.webhookToken`
- `channels.whatsapp.creds.json`
- `channels.whatsapp.accounts.*.creds.json`
[//]: # "secretref-unsupported-list-end"
Uzasadnienie:
- Te poświadczenia należą do klas wydawanych, rotowanych, przenoszących sesję lub trwałych dla OAuth, które nie pasują do zewnętrznego rozwiązywania SecretRef tylko do odczytu.
## Powiązane
- [Zarządzanie sekretami](/pl/gateway/secrets)
- [Semantyka poświadczeń uwierzytelniania](/pl/auth-credential-semantics)

113
docs/pl/reference/test.md
View File

@ -4,56 +4,57 @@ read_when:
summary: Jak uruchamiać testy lokalnie (vitest) i kiedy używać trybów force/coverage
title: Testy
x-i18n:
generated_at: "2026-04-30T18:38:59Z"
generated_at: "2026-05-01T10:03:15Z"
model: gpt-5.5
provider: openai
source_hash: 131f2bad3b2806d28394213cec38d632d106ddbf8ff04d06345ab8046fb8bcf2
source_hash: 07ca45e6c21016ad403ea010bd2e5460acc059c004138e04a714a3506f0e5cda
source_path: reference/test.md
workflow: 16
---
- Pełny zestaw testowy (zestawy, na żywo, Docker): [Testowanie](/pl/help/testing)
- Pełny zestaw testowy (zestawy testów, testy na żywo, Docker): [Testowanie](/pl/help/testing)
- `pnpm test:force`: Zabija wszelkie pozostające procesy Gateway trzymające domyślny port kontrolny, a następnie uruchamia pełny zestaw Vitest z odizolowanym portem Gateway, aby testy serwera nie kolidowały z uruchomioną instancją. Użyj tego, gdy wcześniejsze uruchomienie Gateway pozostawiło port 18789 zajęty.
- `pnpm test:coverage`: Uruchamia zestaw jednostkowy z pokryciem V8 (przez `vitest.unit.config.ts`). To bramka pokrycia jednostkowego załadowanych plików, a nie pokrycie wszystkich plików w całym repozytorium. Progi wynoszą 70% dla wierszy/funkcji/instrukcji i 55% dla gałęzi. Ponieważ `coverage.all` ma wartość false, bramka mierzy pliki załadowane przez zestaw pokrycia jednostkowego zamiast traktować każdy plik źródłowy z podzielonych torów jako niepokryty.
- `pnpm test:force`: Zabija każdy pozostający proces Gateway zajmujący domyślny port kontrolny, a następnie uruchamia pełny zestaw Vitest z izolowanym portem Gateway, aby testy serwera nie kolidowały z działającą instancją. Użyj tego, gdy wcześniejsze uruchomienie Gateway pozostawiło zajęty port 18789.
- `pnpm test:coverage`: Uruchamia zestaw testów jednostkowych z pokryciem V8 (przez `vitest.unit.config.ts`). To bramka pokrycia jednostkowego dla załadowanych plików, a nie pokrycie wszystkich plików w całym repozytorium. Progi wynoszą 70% dla wierszy/funkcji/instrukcji i 55% dla gałęzi. Ponieważ `coverage.all` ma wartość false, bramka mierzy pliki załadowane przez zestaw pokrycia jednostkowego zamiast traktować każdy plik źródłowy z podzielonych torów jako niepokryty.
- `pnpm test:coverage:changed`: Uruchamia pokrycie jednostkowe tylko dla plików zmienionych od `origin/main`.
- `pnpm test:changed`: tani, inteligentny przebieg testów zmian. Uruchamia precyzyjne cele z bezpośrednich edycji testów, sąsiednich plików `*.test.ts`, jawnych mapowań źródeł oraz lokalnego grafu importów. Szerokie zmiany konfiguracji/pakietów są pomijane, chyba że mapują się na precyzyjne testy.
- `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed`: jawny szeroki przebieg testów zmian. Użyj go, gdy edycja uprzęży testowej/konfiguracji/pakietu powinna wrócić do szerszego zachowania testów zmian Vitest.
- `pnpm changed:lanes`: pokazuje tory architektoniczne uruchamiane przez różnicę względem `origin/main`.
- `pnpm check:changed`: uruchamia inteligentną bramkę sprawdzania zmian dla różnicy względem `origin/main`. Uruchamia typecheck, lint i polecenia strażników dla dotkniętych torów architektonicznych, ale nie uruchamia testów Vitest. Użyj `pnpm test:changed` albo jawnego `pnpm test <target>` jako dowodu testowego.
- `pnpm test`: kieruje jawne cele plików/katalogów przez zakresowe tory Vitest. Uruchomienia bez celu używają stałych grup shardów i rozwijają się do konfiguracji liści dla lokalnego wykonania równoległego; grupa rozszerzeń zawsze rozwija się do konfiguracji shardów per rozszerzenie zamiast jednego ogromnego procesu projektu głównego.
- Uruchomienia wrappera testów kończą się krótkim podsumowaniem `[test] passed|failed|skipped ... in ...`. Własny wiersz czasu trwania Vitest pozostaje szczegółem per shard.
- Współdzielony stan testów OpenClaw: użyj `src/test-utils/openclaw-test-state.ts` z Vitest, gdy test potrzebuje odizolowanego `HOME`, `OPENCLAW_STATE_DIR`, `OPENCLAW_CONFIG_PATH`, fikstury konfiguracji, workspace, katalogu agenta albo magazynu profili auth.
- Pomocniki E2E procesów: użyj `test/helpers/openclaw-test-instance.ts`, gdy test E2E na poziomie procesu Vitest potrzebuje działającego Gateway, środowiska CLI, przechwytywania logów i sprzątania w jednym miejscu.
- Pomocniki E2E Docker/Bash: tory, które źródłują `scripts/lib/docker-e2e-image.sh`, mogą przekazać `docker_e2e_test_state_shell_b64 <label> <scenario>` do kontenera i zdekodować go przez `scripts/lib/openclaw-e2e-instance.sh`; skrypty multi-home mogą przekazać `docker_e2e_test_state_function_b64` i wywołać `openclaw_test_state_create <label> <scenario>` w każdym przepływie. Wywołujący niższego poziomu mogą użyć `scripts/lib/openclaw-test-state.mjs shell --label <name> --scenario <name>` dla fragmentu powłoki w kontenerze albo `node scripts/lib/openclaw-test-state.mjs -- create --label <name> --scenario <name> --env-file <path> --json` dla źródłowalnego pliku środowiska hosta. `--` przed `create` powstrzymuje nowsze runtime'y Node przed traktowaniem `--env-file` jako flagi Node. Tory Docker/Bash uruchamiające Gateway mogą źródłować `scripts/lib/openclaw-e2e-instance.sh` wewnątrz kontenera dla rozwiązywania entrypointu, startu mock OpenAI, uruchamiania Gateway na pierwszym planie/w tle, prób gotowości, eksportu środowiska stanu, zrzutów logów i sprzątania procesów.
- Pełne, rozszerzeniowe i include-pattern uruchomienia shardów aktualizują lokalne dane czasów w `.artifacts/vitest-shard-timings.json`; późniejsze uruchomienia całych konfiguracji używają tych czasów do równoważenia wolnych i szybkich shardów. Shardy CI include-pattern dopisują nazwę sharda do klucza czasu, co utrzymuje widoczność czasów filtrowanych shardów bez zastępowania danych czasów całej konfiguracji. Ustaw `OPENCLAW_TEST_PROJECTS_TIMINGS=0`, aby zignorować lokalny artefakt czasów.
- Wybrane pliki testowe `plugin-sdk` i `commands` są teraz kierowane przez dedykowane lekkie tory, które zachowują tylko `test/setup.ts`, pozostawiając przypadki ciężkie runtime'owo na ich istniejących torach.
- Pliki źródłowe z sąsiednimi testami mapują się najpierw na ten sąsiedni test, zanim wrócą do szerszych globów katalogów. Edycje pomocników pod `src/channels/plugins/contracts/test-helpers`, `src/plugin-sdk/test-helpers` i `src/plugins/contracts` używają lokalnego grafu importów, aby uruchamiać testy importujące zamiast szeroko uruchamiać każdy shard, gdy ścieżka zależności jest precyzyjna.
- `auto-reply` dzieli się teraz także na trzy dedykowane konfiguracje (`core`, `top-level`, `reply`), aby uprząż odpowiedzi nie dominowała lżejszych testów statusu/tokenów/pomocników najwyższego poziomu.
- Bazowa konfiguracja Vitest ma teraz domyślnie `pool: "threads"` i `isolate: false`, ze współdzielonym nieizolowanym runnerem włączonym w konfiguracjach repozytorium.
- `pnpm test:changed`: tani inteligentny przebieg testów zmian. Uruchamia precyzyjne cele z bezpośrednich edycji testów, sąsiednich plików `*.test.ts`, jawnych mapowań źródeł i lokalnego grafu importów. Szerokie zmiany konfiguracji/pakietów są pomijane, chyba że mapują się na precyzyjne testy.
- `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed`: jawny szeroki przebieg testów zmian. Użyj go, gdy edycja uprzęży testowej/konfiguracji/pakietu powinna wrócić do szerszego zachowania Vitest dla testów zmian.
- `pnpm changed:lanes`: pokazuje tory architektoniczne wyzwolone przez diff względem `origin/main`.
- `pnpm check:changed`: uruchamia inteligentną bramkę sprawdzania zmian dla diffu względem `origin/main`. Uruchamia polecenia typecheck, lint i guard dla dotkniętych torów architektonicznych, ale nie uruchamia testów Vitest. Użyj `pnpm test:changed` albo jawnego `pnpm test <target>` jako dowodu testowego.
- `pnpm test`: kieruje jawne cele plików/katalogów przez zakresowe tory Vitest. Uruchomienia bez celu używają stałych grup shardów i rozszerzają się do konfiguracji liści na potrzeby lokalnego wykonania równoległego; grupa rozszerzeń zawsze rozszerza się do konfiguracji shardów per rozszerzenie zamiast jednego ogromnego procesu projektu głównego.
- Uruchomienia opakowania testów kończą się krótkim podsumowaniem `[test] passed|failed|skipped ... in ...`. Własny wiersz czasu trwania Vitest pozostaje szczegółem per shard.
- Współdzielony stan testowy OpenClaw: używaj `src/test-utils/openclaw-test-state.ts` z Vitest, gdy test potrzebuje izolowanego `HOME`, `OPENCLAW_STATE_DIR`, `OPENCLAW_CONFIG_PATH`, fixture konfiguracji, workspace, katalogu agenta albo magazynu profili uwierzytelniania.
- Pomocniki E2E procesu: używaj `test/helpers/openclaw-test-instance.ts`, gdy test E2E na poziomie procesu Vitest potrzebuje działającego Gateway, środowiska CLI, przechwytywania logów i sprzątania w jednym miejscu.
- Pomocniki E2E Docker/Bash: tory, które źródłują `scripts/lib/docker-e2e-image.sh`, mogą przekazać `docker_e2e_test_state_shell_b64 <label> <scenario>` do kontenera i zdekodować to za pomocą `scripts/lib/openclaw-e2e-instance.sh`; skrypty z wieloma katalogami home mogą przekazać `docker_e2e_test_state_function_b64` i wywołać `openclaw_test_state_create <label> <scenario>` w każdym przepływie. Wywołujący niższego poziomu mogą użyć `scripts/lib/openclaw-test-state.mjs shell --label <name> --scenario <name>` dla fragmentu powłoki w kontenerze albo `node scripts/lib/openclaw-test-state.mjs -- create --label <name> --scenario <name> --env-file <path> --json` dla możliwego do zsource’owania pliku środowiska hosta. `--` przed `create` powstrzymuje nowsze środowiska uruchomieniowe Node przed traktowaniem `--env-file` jako flagi Node. Tory Docker/Bash uruchamiające Gateway mogą źródłować `scripts/lib/openclaw-e2e-instance.sh` wewnątrz kontenera na potrzeby rozwiązywania entrypointu, startu mock OpenAI, uruchamiania Gateway na pierwszym planie/w tle, sond gotowości, eksportu środowiska stanu, zrzutów logów i sprzątania procesów.
- Pełne przebiegi shardów, przebiegi rozszerzeń i przebiegi ze wzorcem include aktualizują lokalne dane czasów w `.artifacts/vitest-shard-timings.json`; późniejsze przebiegi całej konfiguracji używają tych czasów do równoważenia wolnych i szybkich shardów. Shardy CI ze wzorcem include dopisują nazwę sharda do klucza czasu, dzięki czemu czasy filtrowanych shardów pozostają widoczne bez zastępowania danych czasów całej konfiguracji. Ustaw `OPENCLAW_TEST_PROJECTS_TIMINGS=0`, aby ignorować lokalny artefakt czasów.
- Wybrane pliki testowe `plugin-sdk` i `commands` są teraz kierowane przez dedykowane lekkie tory, które zachowują tylko `test/setup.ts`, pozostawiając przypadki obciążające runtime na ich istniejących torach.
- Pliki źródłowe z sąsiednimi testami mapują się najpierw na ten sąsiedni test, zanim przejdą do szerszych globów katalogów. Edycje pomocników pod `src/channels/plugins/contracts/test-helpers`, `src/plugin-sdk/test-helpers` i `src/plugins/contracts` używają lokalnego grafu importów do uruchamiania importujących testów zamiast szerokiego uruchamiania każdego sharda, gdy ścieżka zależności jest precyzyjna.
- `auto-reply` dzieli się teraz także na trzy dedykowane konfiguracje (`core`, `top-level`, `reply`), aby uprząż odpowiedzi nie dominowała nad lżejszymi testami statusu/tokenów/pomocników najwyższego poziomu.
- Bazowa konfiguracja Vitest domyślnie używa teraz `pool: "threads"` i `isolate: false`, ze współdzielonym nieizolowanym runnerem włączonym we wszystkich konfiguracjach repozytorium.
- `pnpm test:channels` uruchamia `vitest.channels.config.ts`.
- `pnpm test:extensions` i `pnpm test extensions` uruchamiają wszystkie shardy rozszerzeń/pluginów. Ciężkie pluginy kanałów, plugin przeglądarki i OpenAI działają jako dedykowane shardy; inne grupy pluginów pozostają batched. Użyj `pnpm test extensions/<id>` dla jednego toru bundled plugin.
- `pnpm test:perf:imports`: włącza raportowanie czasu trwania importów Vitest i rozbicia importów, nadal używając zakresowego kierowania torów dla jawnych celów plików/katalogów.
- `pnpm test:extensions` i `pnpm test extensions` uruchamiają wszystkie shardy rozszerzeń/pluginów. Ciężkie pluginy kanałów, plugin przeglądarki i OpenAI działają jako dedykowane shardy; inne grupy pluginów pozostają wsadowe. Użyj `pnpm test extensions/<id>` dla jednego toru dołączonego pluginu.
- `pnpm test:perf:imports`: włącza raportowanie czasu trwania importów Vitest i podziału importów, nadal używając zakresowego routingu torów dla jawnych celów plików/katalogów.
- `pnpm test:perf:imports:changed`: to samo profilowanie importów, ale tylko dla plików zmienionych od `origin/main`.
- `pnpm test:perf:changed:bench -- --ref <git-ref>` benchmarkuje ścieżkę kierowanego trybu zmian względem natywnego uruchomienia projektu głównego dla tej samej zatwierdzonej różnicy git.
- `pnpm test:perf:changed:bench -- --worktree` benchmarkuje bieżący zestaw zmian worktree bez wcześniejszego commitu.
- `pnpm test:perf:changed:bench -- --ref <git-ref>` benchmarkuje routowaną ścieżkę trybu zmian względem natywnego uruchomienia projektu głównego dla tego samego zatwierdzonego diffu git.
- `pnpm test:perf:changed:bench -- --worktree` benchmarkuje bieżący zestaw zmian w worktree bez wcześniejszego commitowania.
- `pnpm test:perf:profile:main`: zapisuje profil CPU dla głównego wątku Vitest (`.artifacts/vitest-main-profile`).
- `pnpm test:perf:profile:runner`: zapisuje profile CPU i heap dla runnera jednostkowego (`.artifacts/vitest-runner-profile`).
- `pnpm test:perf:groups --full-suite --allow-failures --output .artifacts/test-perf/baseline-before.json`: uruchamia każdą liściową konfigurację Vitest pełnego zestawu szeregowo i zapisuje pogrupowane dane czasów oraz artefakty JSON/log per konfiguracja. Test Performance Agent używa tego jako swojej bazowej linii przed próbą napraw wolnych testów.
- `pnpm test:perf:groups:compare .artifacts/test-perf/baseline-before.json .artifacts/test-perf/after-agent.json`: porównuje pogrupowane raporty po zmianie skupionej na wydajności.
- Integracja Gateway: opt-in przez `OPENCLAW_TEST_INCLUDE_GATEWAY=1 pnpm test` albo `pnpm test:gateway`.
- `pnpm test:e2e`: Uruchamia end-to-end smoke testy Gateway (parowanie multi-instance WS/HTTP/node). Domyślnie używa `threads` + `isolate: false` z adaptacyjnymi workerami w `vitest.e2e.config.ts`; dostrój przez `OPENCLAW_E2E_WORKERS=<n>` i ustaw `OPENCLAW_E2E_VERBOSE=1` dla szczegółowych logów.
- `pnpm test:live`: Uruchamia testy live providerów (minimax/zai). Wymaga kluczy API i `LIVE=1` (albo provider-specific `*_LIVE_TEST=1`), aby odblokować pominięcie.
- `pnpm test:docker:all`: Buduje współdzielony obraz live-test, pakuje OpenClaw raz jako tarball npm, buduje/używa ponownie gołego obrazu runnera Node/Git oraz obrazu funkcjonalnego instalującego ten tarball do `/app`, a następnie uruchamia tory smoke Docker z `OPENCLAW_SKIP_DOCKER_BUILD=1` przez ważony scheduler. Goły obraz (`OPENCLAW_DOCKER_E2E_BARE_IMAGE`) jest używany dla torów instalatora/aktualizacji/zależności pluginów; te tory montują wstępnie zbudowany tarball zamiast używać skopiowanych źródeł repozytorium. Obraz funkcjonalny (`OPENCLAW_DOCKER_E2E_FUNCTIONAL_IMAGE`) jest używany dla zwykłych torów funkcjonalności zbudowanej aplikacji. `scripts/package-openclaw-for-docker.mjs` jest pojedynczym lokalnym/CI packerem pakietu i waliduje tarball oraz `dist/postinstall-inventory.json`, zanim Docker go użyje. Definicje torów Docker znajdują się w `scripts/lib/docker-e2e-scenarios.mjs`; logika planera znajduje się w `scripts/lib/docker-e2e-plan.mjs`; `scripts/test-docker-all.mjs` wykonuje wybrany plan. `node scripts/test-docker-all.mjs --plan-json` emituje plan CI należący do schedulera dla wybranych torów, rodzajów obrazów, potrzeb pakietu/obrazu live, scenariuszy stanu i sprawdzeń poświadczeń bez budowania ani uruchamiania Docker. `OPENCLAW_DOCKER_ALL_PARALLELISM=<n>` kontroluje sloty procesów i domyślnie wynosi 10; `OPENCLAW_DOCKER_ALL_TAIL_PARALLELISM=<n>` kontroluje pulę końcową wrażliwą na providerów i domyślnie wynosi 10. Limity ciężkich torów domyślnie wynoszą `OPENCLAW_DOCKER_ALL_LIVE_LIMIT=9`, `OPENCLAW_DOCKER_ALL_NPM_LIMIT=10` i `OPENCLAW_DOCKER_ALL_SERVICE_LIMIT=7`; limity providerów domyślnie dopuszczają jeden ciężki tor na providera przez `OPENCLAW_DOCKER_ALL_LIVE_CLAUDE_LIMIT=4`, `OPENCLAW_DOCKER_ALL_LIVE_CODEX_LIMIT=4` i `OPENCLAW_DOCKER_ALL_LIVE_GEMINI_LIMIT=4`. Użyj `OPENCLAW_DOCKER_ALL_WEIGHT_LIMIT` albo `OPENCLAW_DOCKER_ALL_DOCKER_LIMIT` dla większych hostów. Jeśli jeden tor przekracza efektywny limit wagi lub zasobów na hoście o niskiej równoległości, może nadal wystartować z pustej puli i będzie działał sam, dopóki nie zwolni pojemności. Starty torów są domyślnie rozłożone co 2 sekundy, aby uniknąć lokalnych burz tworzenia w demonie Docker; nadpisz przez `OPENCLAW_DOCKER_ALL_START_STAGGER_MS=<ms>`. Runner domyślnie wykonuje preflight Docker, czyści stare kontenery E2E OpenClaw, emituje status aktywnego toru co 30 sekund, współdzieli cache narzędzi CLI providerów między kompatybilnymi torami, domyślnie ponawia przejściowe błędy live-provider raz (`OPENCLAW_DOCKER_ALL_LIVE_RETRIES=<n>`) i przechowuje czasy torów w `.artifacts/docker-tests/lane-timings.json` dla kolejności od najdłuższych w późniejszych uruchomieniach. Użyj `OPENCLAW_DOCKER_ALL_DRY_RUN=1`, aby wypisać manifest torów bez uruchamiania Docker, `OPENCLAW_DOCKER_ALL_STATUS_INTERVAL_MS=<ms>`, aby dostroić wyjście statusu, albo `OPENCLAW_DOCKER_ALL_TIMINGS=0`, aby wyłączyć ponowne użycie czasów. Użyj `OPENCLAW_DOCKER_ALL_LIVE_MODE=skip` tylko dla deterministycznych/lokalnych torów albo `OPENCLAW_DOCKER_ALL_LIVE_MODE=only` tylko dla torów live-provider; aliasy pakietów to `pnpm test:docker:local:all` i `pnpm test:docker:live:all`. Tryb live-only scala główne i końcowe tory live w jedną pulę od najdłuższych, aby kubełki providerów mogły pakować razem pracę Claude, Codex i Gemini. Runner przestaje planować nowe tory z puli po pierwszym błędzie, chyba że ustawiono `OPENCLAW_DOCKER_ALL_FAIL_FAST=0`, a każdy tor ma 120-minutowy fallback timeout możliwy do nadpisania przez `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS`; wybrane tory live/tail używają ciaśniejszych limitów per tor. Polecenia konfiguracji Docker backendu CLI mają własny timeout przez `OPENCLAW_LIVE_CLI_BACKEND_SETUP_TIMEOUT_SECONDS` (domyślnie 180). Logi per tor, `summary.json`, `failures.json` i czasy faz są zapisywane pod `.artifacts/docker-tests/<run-id>/`; użyj `pnpm test:docker:timings <summary.json>`, aby sprawdzić wolne tory, oraz `pnpm test:docker:rerun <run-id|summary.json|failures.json>`, aby wypisać tanie ukierunkowane polecenia ponownego uruchomienia.
- `pnpm test:docker:browser-cdp-snapshot`: Buduje źródłowy kontener E2E oparty na Chromium, uruchamia surowe CDP oraz odizolowany Gateway, uruchamia `browser doctor --deep` i weryfikuje, że snapshoty ról CDP zawierają URL-e linków, promowane przez kursor elementy klikalne, referencje iframe i metadane ramek.
- Live sondy Docker backendu CLI można uruchamiać jako skupione tory, na przykład `pnpm test:docker:live-cli-backend:codex`, `pnpm test:docker:live-cli-backend:codex:resume` albo `pnpm test:docker:live-cli-backend:codex:mcp`. Claude i Gemini mają odpowiadające aliasy `:resume` i `:mcp`.
- `pnpm test:docker:openwebui`: Uruchamia zdockeryzowane OpenClaw + Open WebUI, loguje się przez Open WebUI, sprawdza `/api/models`, a następnie uruchamia prawdziwy proxied chat przez `/api/chat/completions`. Wymaga używalnego klucza modelu live (na przykład OpenAI w `~/.profile`), pobiera zewnętrzny obraz Open WebUI i nie oczekuje się, że będzie stabilne w CI tak jak zwykłe zestawy unit/e2e.
- `pnpm test:docker:mcp-channels`: Uruchamia kontener Gateway z seedem i drugi kontener klienta, który spawnuje `openclaw mcp serve`, a następnie weryfikuje wykrywanie kierowanych rozmów, odczyty transkrypcji, metadane załączników, zachowanie kolejki zdarzeń live, kierowanie wysyłki wychodzącej oraz powiadomienia kanału i uprawnień w stylu Claude przez prawdziwy most stdio. Asercja powiadomienia Claude odczytuje bezpośrednio surowe ramki stdio MCP, aby smoke odzwierciedlał to, co most faktycznie emituje.
- `pnpm test:docker:upgrade-survivor`: Instaluje spakowane archiwum tar OpenClaw na zabrudzonym fixture starego użytkownika, uruchamia aktualizację pakietu oraz nieinteraktywne polecenie doctor bez kluczy dostawcy ani kanału live, następnie uruchamia Gateway loopback i sprawdza, czy agenci, konfiguracja kanału, listy dozwolonych Plugin, pliki obszaru roboczego/sesji, przestarzały stan zależności wykonawczych Plugin, uruchamianie oraz status RPC pozostają zachowane.
- `pnpm test:perf:profile:runner`: zapisuje profile CPU i sterty dla runnera jednostkowego (`.artifacts/vitest-runner-profile`).
- `pnpm test:perf:groups --full-suite --allow-failures --output .artifacts/test-perf/baseline-before.json`: uruchamia seryjnie każdą konfigurację liścia pełnego zestawu Vitest i zapisuje zgrupowane dane czasu trwania oraz artefakty JSON/log per konfiguracja. Test Performance Agent używa tego jako swojej bazy przed próbą napraw wolnych testów.
- `pnpm test:perf:groups:compare .artifacts/test-perf/baseline-before.json .artifacts/test-perf/after-agent.json`: porównuje zgrupowane raporty po zmianie ukierunkowanej na wydajność.
- Integracja Gateway: włączana jawnie przez `OPENCLAW_TEST_INCLUDE_GATEWAY=1 pnpm test` albo `pnpm test:gateway`.
- `pnpm test:e2e`: Uruchamia testy dymne end-to-end Gateway (parowanie wielu instancji WS/HTTP/node). Domyślnie używa `threads` + `isolate: false` z adaptacyjnymi workerami w `vitest.e2e.config.ts`; dostrój za pomocą `OPENCLAW_E2E_WORKERS=<n>` i ustaw `OPENCLAW_E2E_VERBOSE=1` dla szczegółowych logów.
- `pnpm test:live`: Uruchamia testy live dostawców (minimax/zai). Wymaga kluczy API i `LIVE=1` (albo specyficznego dla dostawcy `*_LIVE_TEST=1`), aby przestać je pomijać.
- `pnpm test:docker:all`: Buduje współdzielony obraz testów live, pakuje OpenClaw raz jako tarball npm, buduje/ponownie używa bazowego obrazu runnera Node/Git oraz obrazu funkcjonalnego, który instaluje ten tarball do `/app`, a następnie uruchamia tory dymne Docker z `OPENCLAW_SKIP_DOCKER_BUILD=1` przez ważony harmonogram. Obraz bazowy (`OPENCLAW_DOCKER_E2E_BARE_IMAGE`) jest używany dla torów instalatora/aktualizacji/zależności pluginów; te tory montują wcześniej zbudowany tarball zamiast używać skopiowanych źródeł repozytorium. Obraz funkcjonalny (`OPENCLAW_DOCKER_E2E_FUNCTIONAL_IMAGE`) jest używany dla zwykłych torów funkcjonalności zbudowanej aplikacji. `scripts/package-openclaw-for-docker.mjs` jest pojedynczym lokalnym/CI pakerem pakietu i waliduje tarball oraz `dist/postinstall-inventory.json`, zanim Docker go użyje. Definicje torów Docker znajdują się w `scripts/lib/docker-e2e-scenarios.mjs`; logika planisty znajduje się w `scripts/lib/docker-e2e-plan.mjs`; `scripts/test-docker-all.mjs` wykonuje wybrany plan. `node scripts/test-docker-all.mjs --plan-json` emituje należący do harmonogramu plan CI dla wybranych torów, rodzajów obrazów, potrzeb pakietu/obrazu live, scenariuszy stanu i kontroli poświadczeń bez budowania ani uruchamiania Docker. `OPENCLAW_DOCKER_ALL_PARALLELISM=<n>` kontroluje sloty procesów i domyślnie wynosi 10; `OPENCLAW_DOCKER_ALL_TAIL_PARALLELISM=<n>` kontroluje pulę końcową wrażliwą na dostawcę i domyślnie wynosi 10. Limity ciężkich torów domyślnie wynoszą `OPENCLAW_DOCKER_ALL_LIVE_LIMIT=9`, `OPENCLAW_DOCKER_ALL_NPM_LIMIT=10` i `OPENCLAW_DOCKER_ALL_SERVICE_LIMIT=7`; limity dostawców domyślnie ustawiają jeden ciężki tor na dostawcę przez `OPENCLAW_DOCKER_ALL_LIVE_CLAUDE_LIMIT=4`, `OPENCLAW_DOCKER_ALL_LIVE_CODEX_LIMIT=4` i `OPENCLAW_DOCKER_ALL_LIVE_GEMINI_LIMIT=4`. Użyj `OPENCLAW_DOCKER_ALL_WEIGHT_LIMIT` albo `OPENCLAW_DOCKER_ALL_DOCKER_LIMIT` dla większych hostów. Jeśli jeden tor przekroczy efektywny limit wagi lub zasobów na hoście o małej równoległości, nadal może wystartować z pustej puli i będzie działać sam, dopóki nie zwolni pojemności. Starty torów są domyślnie rozłożone co 2 sekundy, aby uniknąć lokalnych burz tworzenia w demonie Docker; nadpisz za pomocą `OPENCLAW_DOCKER_ALL_START_STAGGER_MS=<ms>`. Runner domyślnie wykonuje preflight Docker, czyści przestarzałe kontenery OpenClaw E2E, emituje status aktywnego toru co 30 sekund, współdzieli cache narzędzi CLI dostawców między zgodnymi torami, domyślnie ponawia przejściowe awarie dostawcy live raz (`OPENCLAW_DOCKER_ALL_LIVE_RETRIES=<n>`) i przechowuje czasy torów w `.artifacts/docker-tests/lane-timings.json` dla kolejności od najdłuższych przy późniejszych uruchomieniach. Użyj `OPENCLAW_DOCKER_ALL_DRY_RUN=1`, aby wypisać manifest torów bez uruchamiania Docker, `OPENCLAW_DOCKER_ALL_STATUS_INTERVAL_MS=<ms>`, aby dostroić wyjście statusu, albo `OPENCLAW_DOCKER_ALL_TIMINGS=0`, aby wyłączyć ponowne użycie czasów. Użyj `OPENCLAW_DOCKER_ALL_LIVE_MODE=skip` tylko dla deterministycznych/lokalnych torów albo `OPENCLAW_DOCKER_ALL_LIVE_MODE=only` tylko dla torów dostawców live; aliasy pakietów to `pnpm test:docker:local:all` i `pnpm test:docker:live:all`. Tryb tylko live scala główne i końcowe tory live w jedną pulę od najdłuższych, aby koszyki dostawców mogły pakować razem prace Claude, Codex i Gemini. Runner przestaje planować nowe tory z puli po pierwszej awarii, chyba że ustawiono `OPENCLAW_DOCKER_ALL_FAIL_FAST=0`, a każdy tor ma zapasowy limit czasu 120 minut, który można nadpisać za pomocą `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS`; wybrane tory live/końcowe używają ściślejszych limitów per tor. Polecenia konfiguracji Docker backendu CLI mają własny limit czasu przez `OPENCLAW_LIVE_CLI_BACKEND_SETUP_TIMEOUT_SECONDS` (domyślnie 180). Logi per tor, `summary.json`, `failures.json` i czasy faz są zapisywane pod `.artifacts/docker-tests/<run-id>/`; użyj `pnpm test:docker:timings <summary.json>`, aby sprawdzić wolne tory, oraz `pnpm test:docker:rerun <run-id|summary.json|failures.json>`, aby wypisać tanie ukierunkowane polecenia ponownego uruchomienia.
- `pnpm test:docker:browser-cdp-snapshot`: Buduje źródłowy kontener E2E oparty na Chromium, uruchamia surowy CDP oraz izolowany Gateway, uruchamia `browser doctor --deep` i weryfikuje, że snapshoty ról CDP zawierają URL-e linków, elementy klikalne wypromowane przez kursor, referencje iframe i metadane ramek.
- Sondy live Docker backendu CLI można uruchamiać jako skupione tory, na przykład `pnpm test:docker:live-cli-backend:codex`, `pnpm test:docker:live-cli-backend:codex:resume` albo `pnpm test:docker:live-cli-backend:codex:mcp`. Claude i Gemini mają odpowiadające aliasy `:resume` i `:mcp`.
- `pnpm test:docker:openwebui`: Uruchamia zdockeryzowane OpenClaw + Open WebUI, loguje się przez Open WebUI, sprawdza `/api/models`, a następnie uruchamia prawdziwy proksowany czat przez `/api/chat/completions`. Wymaga używalnego klucza modelu live (na przykład OpenAI w `~/.profile`), pobiera zewnętrzny obraz Open WebUI i nie oczekuje się, że będzie stabilne w CI tak jak zwykłe zestawy unit/e2e.
- `pnpm test:docker:mcp-channels`: Uruchamia zaszczepiony kontener Gateway oraz drugi kontener klienta, który spawnuję `openclaw mcp serve`, a następnie weryfikuje odkrywanie routowanych konwersacji, odczyty transkrypcji, metadane załączników, zachowanie kolejki zdarzeń live, routing wysyłania wychodzącego oraz powiadomienia kanałów i uprawnień w stylu Claude przez prawdziwy most stdio. Asercja powiadomień Claude odczytuje surowe ramki stdio MCP bezpośrednio, aby test dymny odzwierciedlał to, co most faktycznie emituje.
- `pnpm test:docker:upgrade-survivor`: Instaluje spakowany tarball OpenClaw na zabrudzonym fiksturze starego użytkownika, uruchamia aktualizację pakietu oraz nieinteraktywne `doctor` bez kluczy aktywnego dostawcy ani kanału, następnie uruchamia Gateway local loopback i sprawdza, czy agenci, konfiguracja kanału, listy dozwolonych Pluginów, pliki workspace/sesji, nieaktualny stan runtime-deps Pluginu, uruchamianie oraz status RPC przetrwają.
- `pnpm test:docker:published-upgrade-survivor`: Domyślnie instaluje `openclaw@latest`, zasiewa realistyczne pliki istniejącego użytkownika bez kluczy aktywnego dostawcy ani kanału, konfiguruje ten punkt bazowy za pomocą wbudowanej receptury polecenia `openclaw config set`, aktualizuje tę opublikowaną instalację do spakowanego tarballa OpenClaw, uruchamia nieinteraktywne `doctor`, zapisuje `.artifacts/upgrade-survivor/summary.json`, następnie uruchamia Gateway local loopback i sprawdza, czy skonfigurowane intencje, pliki workspace/sesji, nieaktualny stan konfiguracji/runtime-deps Pluginu, uruchamianie, `/healthz`, `/readyz` oraz status RPC przetrwają albo zostaną poprawnie naprawione. Nadpisz jeden punkt bazowy za pomocą `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPEC`, rozszerz dokładną macierz za pomocą `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPECS` albo dodaj fikstury scenariuszy za pomocą `OPENCLAW_UPGRADE_SURVIVOR_SCENARIOS=reported-issues`; Package Acceptance udostępnia je jako `published_upgrade_survivor_baseline`, `published_upgrade_survivor_baselines` i `published_upgrade_survivor_scenarios`.
## Lokalna bramka PR
W przypadku lokalnych kontroli scalenia/bramki PR uruchom:
W przypadku lokalnych kontroli przed land/gate PR uruchom:
- `pnpm check:changed`
- `pnpm check`
@ -62,12 +63,12 @@ W przypadku lokalnych kontroli scalenia/bramki PR uruchom:
- `pnpm test`
- `pnpm check:docs`
Jeśli `pnpm test` niestabilnie zawiedzie na obciążonym hoście, uruchom ponownie raz, zanim uznasz to za regresję, a następnie odizoluj problem za pomocą `pnpm test <path/to/test>`. Dla hostów z ograniczoną pamięcią użyj:
Jeśli `pnpm test` działa niestabilnie na obciążonym hoście, uruchom go ponownie raz, zanim uznasz to za regresję, a następnie odizoluj problem poleceniem `pnpm test <path/to/test>`. Na hostach z ograniczoną pamięcią użyj:
- `OPENCLAW_VITEST_MAX_WORKERS=1 pnpm test`
- `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/tmp/openclaw-vitest-cache pnpm test:changed`
## Test opóźnień modelu (lokalne klucze)
## Benchmark opóźnień modelu (lokalne klucze)
Skrypt: [`scripts/bench-model.ts`](https://github.com/openclaw/openclaw/blob/main/scripts/bench-model.ts)
@ -75,14 +76,14 @@ Użycie:
- `source ~/.profile && pnpm tsx scripts/bench-model.ts --runs 10`
- Opcjonalne zmienne środowiskowe: `MINIMAX_API_KEY`, `MINIMAX_BASE_URL`, `MINIMAX_MODEL`, `ANTHROPIC_API_KEY`
- Domyślne polecenie: „Odpowiedz jednym słowem: ok. Bez interpunkcji ani dodatkowego tekstu.”
- Domyślny prompt: „Odpowiedz jednym słowem: ok. Bez interpunkcji ani dodatkowego tekstu.”
Ostatnie uruchomienie (2025-12-31, 20 przebiegów):
Ostatnie uruchomienie (2025-12-31, 20 uruchomień):
- mediana minimax 1279 ms (min. 1114, maks. 2431)
- mediana opus 2454 ms (min. 1224, maks. 3170)
## Test startu CLI
## Benchmark startu CLI
Skrypt: [`scripts/bench-cli-startup.ts`](https://github.com/openclaw/openclaw/blob/main/scripts/bench-cli-startup.ts)
@ -104,29 +105,29 @@ Użycie:
- `pnpm tsx scripts/bench-cli-startup.ts --preset real --cpu-prof-dir .artifacts/cli-cpu`
- `pnpm tsx scripts/bench-cli-startup.ts --json`
Zestawy ustawień:
Ustawienia wstępne:
- `startup`: `--version`, `--help`, `health`, `health --json`, `status --json`, `status`
- `real`: `health`, `status`, `status --json`, `sessions`, `sessions --json`, `tasks --json`, `tasks list --json`, `tasks audit --json`, `agents list --json`, `gateway status`, `gateway status --json`, `gateway health --json`, `config get gateway.port`
- `all`: oba zestawy ustawień
- `all`: oba ustawienia wstępne
Dane wyjściowe obejmują `sampleCount`, średnią, p50, p95, min./maks., rozkład kodów wyjścia/sygnałów oraz podsumowania maksymalnego RSS dla każdego polecenia. Opcjonalne `--cpu-prof-dir` / `--heap-prof-dir` zapisuje profile V8 dla każdego przebiegu, dzięki czemu pomiar czasu i przechwytywanie profili używają tego samego środowiska testowego.
Dane wyjściowe obejmują `sampleCount`, średnią, p50, p95, minimum/maksimum, rozkład kodów zakończenia/sygnałów oraz podsumowania maksymalnego RSS dla każdego polecenia. Opcjonalne `--cpu-prof-dir` / `--heap-prof-dir` zapisują profile V8 dla każdego uruchomienia, aby pomiar czasu i przechwytywanie profilu korzystały z tej samej uprzęży.
Konwencje zapisywanych danych wyjściowych:
Konwencje zapisanych danych wyjściowych:
- `pnpm test:startup:bench:smoke` zapisuje ukierunkowany artefakt smoke w `.artifacts/cli-startup-bench-smoke.json`
- `pnpm test:startup:bench:save` zapisuje artefakt pełnego zestawu w `.artifacts/cli-startup-bench-all.json` z użyciem `runs=5` i `warmup=1`
- `pnpm test:startup:bench:update` odświeża zatwierdzoną w repozytorium bazową fiksturę w `test/fixtures/cli-startup-bench.json` z użyciem `runs=5` i `warmup=1`
- `pnpm test:startup:bench:smoke` zapisuje docelowy artefakt testu dymnego w `.artifacts/cli-startup-bench-smoke.json`
- `pnpm test:startup:bench:save` zapisuje artefakt pełnego zestawu testów w `.artifacts/cli-startup-bench-all.json`, używając `runs=5` i `warmup=1`
- `pnpm test:startup:bench:update` odświeża wzorzec testowy zapisany w repozytorium w `test/fixtures/cli-startup-bench.json`, używając `runs=5` i `warmup=1`
Zatwierdzona w repozytorium fikstura:
Wzorzec testowy zapisany w repozytorium:
- `test/fixtures/cli-startup-bench.json`
- Odśwież za pomocą `pnpm test:startup:bench:update`
- Porównaj bieżące wyniki z fiksturą za pomocą `pnpm test:startup:bench:check`
- Odśwież poleceniem `pnpm test:startup:bench:update`
- Porównaj bieżące wyniki z wzorcem poleceniem `pnpm test:startup:bench:check`
## Onboarding E2E (Docker)
## E2E onboardingu (Docker)
Docker jest opcjonalny; jest to potrzebne tylko do skonteneryzowanych testów smoke onboardingu.
Docker jest opcjonalny; jest to potrzebne tylko do konteneryzowanych testów dymnych onboardingu.
Pełny przepływ zimnego startu w czystym kontenerze Linux:
@ -134,11 +135,11 @@ Pełny przepływ zimnego startu w czystym kontenerze Linux:
scripts/e2e/onboard-docker.sh
```
Ten skrypt steruje interaktywnym kreatorem przez pseudo-tty, weryfikuje pliki konfiguracji/przestrzeni roboczej/sesji, a następnie uruchamia Gateway i wykonuje `openclaw health`.
Ten skrypt obsługuje interaktywny kreator przez pseudo-tty, weryfikuje pliki konfiguracji/przestrzeni roboczej/sesji, a następnie uruchamia Gateway i wykonuje `openclaw health`.
## Smoke importu QR (Docker)
## Test dymny importu QR (Docker)
Zapewnia, że utrzymywany pomocnik runtime QR ładuje się w obsługiwanych środowiskach runtime Docker Node (domyślnie Node 24, zgodne Node 22):
Zapewnia, że utrzymywany pomocnik środowiska wykonawczego QR ładuje się w obsługiwanych środowiskach wykonawczych Docker Node (domyślnie Node 24, zgodnie z kompatybilnością Node 22):
```bash
pnpm test:docker:qr

170
docs/pl/security/network-proxy.md
View File

@ -1,40 +1,40 @@
---
read_when:
- Chcesz ochrony warstwowej przed atakami SSRF i atakami polegającymi na ponownym wiązaniu DNS
- Konfigurowanie zewnętrznego serwera proxy typu forward dla ruchu środowiska uruchomieniowego OpenClaw
summary: Jak kierować ruch HTTP i WebSocket środowiska uruchomieniowego OpenClaw przez filtrujący serwer proxy zarządzany przez operatora
title: Proxy sieciowy
- Chcesz wielowarstwowej ochrony przed atakami SSRF i DNS rebinding
- Konfigurowanie zewnętrznego serwera proxy dla ruchu wychodzącego środowiska wykonawczego OpenClaw
summary: Jak kierować ruch HTTP i WebSocket środowiska uruchomieniowego OpenClaw przez zarządzany przez operatora filtrujący serwer proxy
title: Proxy sieciowe
x-i18n:
generated_at: "2026-04-30T10:19:00Z"
generated_at: "2026-05-01T10:03:36Z"
model: gpt-5.5
provider: openai
source_hash: c4e879f787571410acdda55dcdbb5fd77aef1d24045af5c9208cba51330a70ca
source_hash: 9207d349e4410e38631ae7665be19b536e4a4128a4e80dd095e802804dfd66a3
source_path: security/network-proxy.md
workflow: 16
---
# Proxy sieciowy
OpenClaw może kierować ruch HTTP i WebSocket środowiska uruchomieniowego przez zarządzany przez operatora proxy przekazujący. To opcjonalna warstwa obrony w głąb dla wdrożeń, które wymagają centralnej kontroli ruchu wychodzącego, silniejszej ochrony przed SSRF i lepszej audytowalności sieci.
OpenClaw może kierować ruch HTTP i WebSocket środowiska wykonawczego przez zarządzany przez operatora proxy przekazujący. Jest to opcjonalna obrona warstwowa dla wdrożeń, które potrzebują centralnej kontroli ruchu wychodzącego, silniejszej ochrony przed SSRF i lepszej audytowalności sieci.
OpenClaw nie dostarcza, nie pobiera, nie uruchamia, nie konfiguruje ani nie certyfikuje proxy. Uruchamiasz technologię proxy pasującą do swojego środowiska, a OpenClaw kieruje przez nie zwykłych lokalnych dla procesu klientów HTTP i WebSocket.
OpenClaw nie dostarcza, nie pobiera, nie uruchamia, nie konfiguruje ani nie certyfikuje proxy. Uruchamiasz technologię proxy pasującą do Twojego środowiska, a OpenClaw kieruje przez nią zwykłe lokalne dla procesu klienty HTTP i WebSocket.
## Dlaczego warto używać proxy?
## Dlaczego używać proxy?
Proxy daje operatorom jeden punkt kontroli sieci dla wychodzącego ruchu HTTP i WebSocket. Może to być przydatne nawet poza wzmacnianiem ochrony przed SSRF:
- Centralna polityka: utrzymuj jedną politykę ruchu wychodzącego zamiast polegać na tym, że każde miejsce wywołania HTTP w aplikacji poprawnie zastosuje reguły sieciowe.
- Kontrole w czasie łączenia: oceniaj miejsce docelowe po rozwiązaniu DNS i bezpośrednio przed otwarciem przez proxy połączenia do usługi nadrzędnej.
- Obrona przed DNS rebinding: zmniejsz lukę między sprawdzeniem DNS na poziomie aplikacji a faktycznym połączeniem wychodzącym.
- Szersze pokrycie JavaScript: kieruj zwykłe `fetch`, `node:http`, `node:https`, WebSocket, axios, got, node-fetch i podobnych klientów tą samą ścieżką.
- Kontrole w czasie połączenia: oceń miejsce docelowe po rozwiązaniu DNS i bezpośrednio przed otwarciem przez proxy połączenia nadrzędnego.
- Ochrona przed DNS rebinding: zmniejsz lukę między kontrolą DNS na poziomie aplikacji a faktycznym połączeniem wychodzącym.
- Szersze pokrycie JavaScript: kieruj zwykłe klienty `fetch`, `node:http`, `node:https`, WebSocket, axios, got, node-fetch i podobne tą samą ścieżką.
- Audytowalność: rejestruj dozwolone i odrzucone miejsca docelowe na granicy ruchu wychodzącego.
- Kontrola operacyjna: egzekwuj reguły miejsc docelowych, segmentację sieci, limity szybkości lub listy dozwolonych miejsc docelowych bez przebudowywania OpenClaw.
- Kontrola operacyjna: egzekwuj reguły miejsc docelowych, segmentację sieci, limity szybkości lub listy dozwolonego ruchu wychodzącego bez przebudowy OpenClaw.
Kierowanie przez proxy to zabezpieczenie na poziomie procesu dla zwykłego wychodzącego ruchu HTTP i WebSocket. Daje operatorom ścieżkę domyślnie zamkniętą do kierowania obsługiwanych klientów HTTP JavaScript przez własne filtrujące proxy, ale nie jest piaskownicą sieciową na poziomie systemu operacyjnego i nie sprawia, że OpenClaw certyfikuje politykę miejsc docelowych tego proxy.
Trasowanie przez proxy jest zabezpieczeniem na poziomie procesu dla zwykłego wychodzącego ruchu HTTP i WebSocket. Daje operatorom ścieżkę fail-closed do kierowania obsługiwanych klientów HTTP JavaScript przez własny filtrujący proxy, ale nie jest piaskownicą sieciową na poziomie systemu operacyjnego i nie sprawia, że OpenClaw certyfikuje politykę miejsc docelowych proxy.
## Jak OpenClaw kieruje ruch
Gdy `proxy.enabled=true` i skonfigurowano URL proxy, chronione procesy środowiska uruchomieniowego, takie jak `openclaw gateway run`, `openclaw node run` i `openclaw agent --local`, kierują zwykły wychodzący ruch HTTP i WebSocket przez skonfigurowane proxy:
Gdy `proxy.enabled=true` i skonfigurowano URL proxy, chronione procesy środowiska wykonawczego, takie jak `openclaw gateway run`, `openclaw node run` i `openclaw agent --local`, kierują zwykły wychodzący ruch HTTP i WebSocket przez skonfigurowany proxy:
```text
OpenClaw process
@ -43,27 +43,27 @@ OpenClaw process
WebSocket clients -> operator-managed filtering proxy -> public internet
```
Publicznym kontraktem jest zachowanie kierowania ruchu, a nie wewnętrzne haki Node użyte do jego wdrożenia. Klienci WebSocket płaszczyzny sterowania OpenClaw Gateway używają wąskiej ścieżki bezpośredniej dla ruchu RPC Gateway local loopback, gdy URL Gateway używa `localhost` albo dosłownego adresu IP pętli zwrotnej, takiego jak `127.0.0.1` lub `[::1]`. Ta ścieżka płaszczyzny sterowania musi móc docierać do Gateway na pętli zwrotnej nawet wtedy, gdy proxy operatora blokuje miejsca docelowe pętli zwrotnej. Zwykłe żądania HTTP i WebSocket środowiska uruchomieniowego nadal używają skonfigurowanego proxy.
Publicznym kontraktem jest zachowanie trasowania, a nie wewnętrzne haki Node używane do jego implementacji. Klienty WebSocket płaszczyzny sterowania OpenClaw Gateway używają wąskiej ścieżki bezpośredniej dla ruchu RPC Gateway przez local loopback, gdy URL Gateway używa `localhost` albo dosłownego adresu IP pętli zwrotnej, takiego jak `127.0.0.1` lub `[::1]`. Ta ścieżka płaszczyzny sterowania musi móc dotrzeć do Gateway przez pętlę zwrotną nawet wtedy, gdy proxy operatora blokuje miejsca docelowe pętli zwrotnej. Zwykłe żądania HTTP i WebSocket środowiska wykonawczego nadal używają skonfigurowanego proxy.
Wewnętrznie OpenClaw używa dwóch haków kierowania na poziomie procesu dla tej funkcji:
Wewnętrznie OpenClaw używa dwóch haków trasowania na poziomie procesu dla tej funkcji:
- Kierowanie przez dispatcher Undici obejmuje `fetch`, klientów opartych na undici oraz transporty, które udostępniają własny dispatcher undici.
- Kierowanie `global-agent` obejmuje wywołujących Node core `node:http` i `node:https`, w tym wiele bibliotek zbudowanych na `http.request`, `https.request`, `http.get` i `https.get`. Tryb zarządzanego proxy wymusza tego globalnego agenta, aby jawni agenci HTTP Node nie omijali przypadkowo proxy operatora.
- Trasowanie dyspozytora Undici obejmuje `fetch`, klientów opartych na undici oraz transporty, które udostępniają własny dyspozytor undici.
- Trasowanie `global-agent` obejmuje wywołujących z rdzenia Node `node:http` i `node:https`, w tym wiele bibliotek zbudowanych na `http.request`, `https.request`, `http.get` i `https.get`. Tryb zarządzanego proxy wymusza tego globalnego agenta, aby jawni agenci HTTP Node nie omijali przypadkowo proxy operatora.
Niektóre Pluginy posiadają własne niestandardowe transporty, które wymagają jawnego podłączenia proxy nawet wtedy, gdy istnieje kierowanie na poziomie procesu. Na przykład transport Bot API Telegram używa własnego dispatchera HTTP/1 undici i dlatego respektuje środowisko proxy procesu oraz zarządzany awaryjny mechanizm `OPENCLAW_PROXY_URL` w tej ścieżce transportu specyficznej dla właściciela.
Niektóre pluginy posiadają własne transporty, które wymagają jawnego podłączenia proxy nawet wtedy, gdy istnieje trasowanie na poziomie procesu. Na przykład transport Bot API Telegram używa własnego dyspozytora HTTP/1 undici, dlatego respektuje środowisko proxy procesu oraz zarządzany awaryjny `OPENCLAW_PROXY_URL` w tej ścieżce transportu należącej do konkretnego właściciela.
Sam URL proxy musi używać `http://`. Miejsca docelowe HTTPS nadal są obsługiwane przez proxy z użyciem HTTP `CONNECT`; oznacza to jedynie, że OpenClaw oczekuje zwykłego nasłuchującego proxy przekazującego HTTP, takiego jak `http://127.0.0.1:3128`.
Sam URL proxy musi używać `http://`. Miejsca docelowe HTTPS nadal są obsługiwane przez proxy za pomocą HTTP `CONNECT`; oznacza to tylko, że OpenClaw oczekuje zwykłego nasłuchującego proxy przekazującego HTTP, takiego jak `http://127.0.0.1:3128`.
Gdy proxy jest aktywne, OpenClaw czyści `no_proxy`, `NO_PROXY` i `GLOBAL_AGENT_NO_PROXY`. Te listy obejść są oparte na miejscach docelowych, więc pozostawienie tam `localhost` lub `127.0.0.1` pozwoliłoby celom SSRF wysokiego ryzyka pominąć filtrujące proxy.
Gdy proxy jest aktywny, OpenClaw czyści `no_proxy`, `NO_PROXY` i `GLOBAL_AGENT_NO_PROXY`. Te listy obejść są oparte na miejscach docelowych, więc pozostawienie tam `localhost` lub `127.0.0.1` pozwoliłoby celom SSRF wysokiego ryzyka ominąć filtrujący proxy.
Podczas zamykania OpenClaw przywraca poprzednie środowisko proxy i resetuje zbuforowany stan kierowania procesu.
Podczas zamykania OpenClaw przywraca poprzednie środowisko proxy i resetuje zbuforowany stan trasowania procesu.
## Powiązane terminy proxy
- `proxy.enabled` / `proxy.proxyUrl`: kierowanie wychodzącego ruchu OpenClaw środowiska uruchomieniowego przez proxy przekazujące. Ta strona dokumentuje tę funkcję.
- `gateway.auth.mode: "trusted-proxy"`: przychodzące uwierzytelnianie reverse proxy świadome tożsamości dla dostępu do Gateway. Zobacz [Uwierzytelnianie zaufanego proxy](/pl/gateway/trusted-proxy-auth).
- `openclaw proxy`: lokalne proxy debugowania i inspektor przechwytywania do rozwoju i wsparcia. Zobacz [openclaw proxy](/pl/cli/proxy).
- Ustawienia proxy specyficzne dla kanału lub dostawcy: nadpisania specyficzne dla właściciela dla konkretnego transportu. Preferuj zarządzane proxy sieciowe, gdy celem jest centralna kontrola ruchu wychodzącego w całym środowisku uruchomieniowym.
- `proxy.enabled` / `proxy.proxyUrl`: trasowanie ruchu wychodzącego środowiska wykonawczego OpenClaw przez proxy przekazujący. Ta strona dokumentuje tę funkcję.
- `gateway.auth.mode: "trusted-proxy"`: uwierzytelnianie przychodzące z uwzględnieniem tożsamości przez reverse proxy dla dostępu do Gateway. Zobacz [Uwierzytelnianie zaufanego proxy](/pl/gateway/trusted-proxy-auth).
- `openclaw proxy`: lokalny debugujący proxy i inspektor przechwytywania do rozwoju i wsparcia. Zobacz [openclaw proxy](/pl/cli/proxy).
- Ustawienia proxy specyficzne dla kanału lub dostawcy: nadpisania należące do konkretnego właściciela dla danego transportu. Preferuj zarządzany proxy sieciowy, gdy celem jest centralna kontrola ruchu wychodzącego w całym środowisku wykonawczym.
## Konfiguracja
@ -73,7 +73,7 @@ proxy:
proxyUrl: http://127.0.0.1:3128
```
Możesz też podać URL przez środowisko, zachowując `proxy.enabled=true` w konfiguracji:
Możesz także podać URL przez środowisko, zachowując `proxy.enabled=true` w konfiguracji:
```bash
OPENCLAW_PROXY_URL=http://127.0.0.1:3128 openclaw gateway run
@ -81,7 +81,7 @@ OPENCLAW_PROXY_URL=http://127.0.0.1:3128 openclaw gateway run
`proxy.proxyUrl` ma pierwszeństwo przed `OPENCLAW_PROXY_URL`.
Jeśli `enabled=true`, ale nie skonfigurowano prawidłowego URL proxy, chronione polecenia kończą uruchamianie niepowodzeniem zamiast przechodzić awaryjnie na bezpośredni dostęp do sieci.
Jeśli `enabled=true`, ale nie skonfigurowano prawidłowego URL proxy, chronione polecenia przerywają uruchamianie zamiast wracać do bezpośredniego dostępu do sieci.
W przypadku zarządzanych usług gateway uruchamianych przez `openclaw gateway start` preferuj przechowywanie URL w konfiguracji:
@ -92,65 +92,95 @@ openclaw gateway install --force
openclaw gateway start
```
Awaryjny mechanizm środowiskowy najlepiej sprawdza się w uruchomieniach pierwszoplanowych. Jeśli używasz go z zainstalowaną usługą, umieść `OPENCLAW_PROXY_URL` w trwałym środowisku usługi, takim jak `$OPENCLAW_STATE_DIR/.env` lub `~/.openclaw/.env`, a następnie zainstaluj usługę ponownie, aby launchd, systemd lub Scheduled Tasks uruchamiały gateway z tą wartością.
Awaryjne użycie środowiska najlepiej sprawdza się przy uruchomieniach pierwszoplanowych. Jeśli używasz go z zainstalowaną usługą, umieść `OPENCLAW_PROXY_URL` w trwałym środowisku usługi, takim jak `$OPENCLAW_STATE_DIR/.env` lub `~/.openclaw/.env`, a następnie zainstaluj usługę ponownie, aby launchd, systemd lub Zaplanowane zadania uruchamiały gateway z tą wartością.
W przypadku poleceń `openclaw --container ...` OpenClaw przekazuje `OPENCLAW_PROXY_URL` do potomnego CLI przeznaczonego dla kontenera, gdy jest ustawiony. URL musi być osiągalny z wnętrza kontenera; `127.0.0.1` odnosi się do samego kontenera, a nie hosta. OpenClaw odrzuca URL proxy pętli zwrotnej dla poleceń przeznaczonych dla kontenera, chyba że jawnie nadpiszesz tę kontrolę bezpieczeństwa.
Dla poleceń `openclaw --container ...` OpenClaw przekazuje `OPENCLAW_PROXY_URL` do podrzędnego CLI skierowanego na kontener, gdy jest ustawiony. URL musi być osiągalny z wnętrza kontenera; `127.0.0.1` odnosi się do samego kontenera, a nie hosta. OpenClaw odrzuca URL proxy pętli zwrotnej dla poleceń skierowanych na kontener, chyba że jawnie nadpiszesz tę kontrolę bezpieczeństwa.
## Wymagania dotyczące proxy
## Wymagania proxy
Polityka proxy jest granicą bezpieczeństwa. OpenClaw nie może zweryfikować, czy proxy blokuje właściwe cele.
Polityka proxy jest granicą bezpieczeństwa. OpenClaw nie może zweryfikować, że proxy blokuje właściwe cele.
Skonfiguruj proxy tak, aby:
- Wiązało się tylko z pętlą zwrotną lub prywatnym zaufanym interfejsem.
- Ograniczało dostęp tak, aby mogły go używać tylko proces OpenClaw, host, kontener lub konto usługi.
- Samodzielnie rozwiązywało miejsca docelowe i blokowało docelowe adresy IP po rozwiązaniu DNS.
- Stosowało politykę w czasie łączenia zarówno dla zwykłych żądań HTTP, jak i tuneli HTTPS `CONNECT`.
- Odrzucało obejścia oparte na miejscach docelowych dla pętli zwrotnej, zakresów prywatnych, link-local, metadanych, multicast, zarezerwowanych lub dokumentacyjnych.
- Unikało list dozwolonych nazw hostów, chyba że w pełni ufasz ścieżce rozwiązywania DNS.
- Rejestrowało miejsce docelowe, decyzję, status i powód bez rejestrowania treści żądań, nagłówków autoryzacji, plików cookie ani innych sekretów.
- Utrzymywało politykę proxy pod kontrolą wersji i przeglądało zmiany tak jak konfigurację wrażliwą pod kątem bezpieczeństwa.
- Wiązał się tylko z pętlą zwrotną albo prywatnym zaufanym interfejsem.
- Ograniczał dostęp tak, aby mógł go używać tylko proces, host, kontener lub konto usługi OpenClaw.
- Samodzielnie rozwiązywał miejsca docelowe i blokował adresy IP miejsc docelowych po rozwiązaniu DNS.
- Stosował politykę w czasie połączenia zarówno dla zwykłych żądań HTTP, jak i tuneli HTTPS `CONNECT`.
- Odrzucał obejścia oparte na miejscu docelowym dla zakresów pętli zwrotnej, prywatnych, link-local, metadanych, multicast, zarezerwowanych lub dokumentacyjnych.
- Unikał list dozwolonych nazw hostów, chyba że w pełni ufasz ścieżce rozwiązywania DNS.
- Rejestrował miejsce docelowe, decyzję, status i powód bez rejestrowania treści żądań, nagłówków autoryzacji, plików cookie ani innych sekretów.
- Przechowywał politykę proxy w kontroli wersji i przeglądał zmiany jak konfigurację wrażliwą pod względem bezpieczeństwa.
## Zalecane blokowane miejsca docelowe
Użyj tej listy odmów jako punktu wyjścia dla dowolnego proxy przekazującego, zapory lub polityki ruchu wychodzącego.
Użyj tej listy zablokowanych jako punktu wyjścia dla dowolnego proxy przekazującego, zapory lub polityki ruchu wychodzącego.
Logika klasyfikatora na poziomie aplikacji OpenClaw znajduje się w `src/infra/net/ssrf.ts` i `src/shared/net/ip.ts`. Odpowiednie haki zgodności to `BLOCKED_HOSTNAMES`, `BLOCKED_IPV4_SPECIAL_USE_RANGES`, `BLOCKED_IPV6_SPECIAL_USE_RANGES`, `RFC2544_BENCHMARK_PREFIX` oraz osadzona obsługa wartownika IPv4 dla NAT64, 6to4, Teredo, ISATAP i form mapowanych na IPv4. Te pliki są przydatnymi odniesieniami podczas utrzymywania zewnętrznej polityki proxy, ale OpenClaw nie eksportuje ani nie egzekwuje automatycznie tych reguł w Twoim proxy.
Logika klasyfikatora na poziomie aplikacji OpenClaw znajduje się w `src/infra/net/ssrf.ts` i `src/shared/net/ip.ts`. Odpowiednie haki zgodności to `BLOCKED_HOSTNAMES`, `BLOCKED_IPV4_SPECIAL_USE_RANGES`, `BLOCKED_IPV6_SPECIAL_USE_RANGES`, `RFC2544_BENCHMARK_PREFIX` oraz wbudowana obsługa sentinel IPv4 dla NAT64, 6to4, Teredo, ISATAP i form mapowanych na IPv4. Te pliki są przydatnymi odniesieniami podczas utrzymywania zewnętrznej polityki proxy, ale OpenClaw nie eksportuje ani nie egzekwuje automatycznie tych reguł w Twoim proxy.
| Zakres lub host | Dlaczego blokować |
| ------------------------------------------------------------------------------------ | --------------------------------------------------- |
| `127.0.0.0/8`, `localhost`, `localhost.localdomain` | Pętla zwrotna IPv4 |
| `::1/128` | Pętla zwrotna IPv6 |
| `0.0.0.0/8`, `::/128` | Adresy nieokreślone i adresy tej sieci |
| `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16` | Sieci prywatne RFC1918 |
| `169.254.0.0/16`, `fe80::/10` | Adresy link-local i typowe ścieżki metadanych chmur |
| `169.254.169.254`, `metadata.google.internal` | Usługi metadanych chmur |
| Zakres lub host | Dlaczego blokować |
| ------------------------------------------------------------------------------------ | -------------------------------------------------- |
| `127.0.0.0/8`, `localhost`, `localhost.localdomain` | Pętla zwrotna IPv4 |
| `::1/128` | Pętla zwrotna IPv6 |
| `0.0.0.0/8`, `::/128` | Adresy nieokreślone i adresy tej sieci |
| `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16` | Sieci prywatne RFC1918 |
| `169.254.0.0/16`, `fe80::/10` | Adresy link-local i typowe ścieżki metadanych chmurowych |
| `169.254.169.254`, `metadata.google.internal` | Usługi metadanych chmurowych |
| `100.64.0.0/10` | Współdzielona przestrzeń adresowa NAT klasy operatorskiej |
| `198.18.0.0/15`, `2001:2::/48` | Zakresy testów wydajnościowych |
| `192.0.0.0/24`, `192.0.2.0/24`, `198.51.100.0/24`, `203.0.113.0/24`, `2001:db8::/32` | Zakresy specjalnego użycia i dokumentacyjne |
| `224.0.0.0/4`, `ff00::/8` | Multicast |
| `240.0.0.0/4` | Zarezerwowane IPv4 |
| `fc00::/7`, `fec0::/10` | Lokalne/prywatne zakresy IPv6 |
| `100::/64`, `2001:20::/28` | Zakresy IPv6 discard i ORCHIDv2 |
| `64:ff9b::/96`, `64:ff9b:1::/48` | Prefiksy NAT64 z osadzonym IPv4 |
| `2002::/16`, `2001::/32` | 6to4 i Teredo z osadzonym IPv4 |
| `::/96`, `::ffff:0:0/96` | IPv6 zgodne z IPv4 i IPv6 mapowane na IPv4 |
| `198.18.0.0/15`, `2001:2::/48` | Zakresy testów wydajnościowych |
| `192.0.0.0/24`, `192.0.2.0/24`, `198.51.100.0/24`, `203.0.113.0/24`, `2001:db8::/32` | Zakresy specjalnego użycia i dokumentacyjne |
| `224.0.0.0/4`, `ff00::/8` | Multicast |
| `240.0.0.0/4` | Zarezerwowane IPv4 |
| `fc00::/7`, `fec0::/10` | Lokalne/prywatne zakresy IPv6 |
| `100::/64`, `2001:20::/28` | Zakresy IPv6 discard i ORCHIDv2 |
| `64:ff9b::/96`, `64:ff9b:1::/48` | Prefiksy NAT64 z osadzonym IPv4 |
| `2002::/16`, `2001::/32` | 6to4 i Teredo z osadzonym IPv4 |
| `::/96`, `::ffff:0:0/96` | IPv6 zgodne z IPv4 i IPv6 mapowane na IPv4 |
Jeśli Twój dostawca chmury lub platforma sieciowa dokumentuje dodatkowe hosty metadanych albo zarezerwowane zakresy, dodaj je również.
Jeśli Twój dostawca chmury lub platforma sieciowa dokumentuje dodatkowe hosty metadanych albo zarezerwowane zakresy, także je dodaj.
## Walidacja
Zweryfikuj proxy z tego samego hosta, kontenera lub konta usługi, które uruchamia OpenClaw:
```bash
openclaw proxy validate --proxy-url http://127.0.0.1:3128
```
Domyślnie, gdy nie podano niestandardowych miejsc docelowych, polecenie sprawdza, czy `https://example.com/` kończy się powodzeniem, i uruchamia tymczasowy kanarek pętli zwrotnej, do którego proxy nie może dotrzeć. Domyślna kontrola odmowy przechodzi, gdy proxy zwraca odpowiedź odmowy spoza zakresu 2xx albo blokuje kanarka błędem transportu; kończy się niepowodzeniem, jeśli udana odpowiedź dotrze do kanarka. Jeśli żaden proxy nie jest włączony i skonfigurowany, walidacja zgłasza problem z konfiguracją; użyj `--proxy-url` do jednorazowego sprawdzenia przed zmianą konfiguracji. Użyj `--allowed-url` i `--denied-url`, aby przetestować oczekiwania specyficzne dla wdrożenia. Niestandardowe odrzucane miejsca docelowe działają fail-closed: dowolna odpowiedź HTTP oznacza, że miejsce docelowe było osiągalne przez proxy, a każdy błąd transportu jest zgłaszany jako nierozstrzygający, ponieważ OpenClaw nie może udowodnić, że proxy zablokował osiągalne źródło. W przypadku niepowodzenia walidacji polecenie kończy działanie kodem 1.
Użyj `--json` do automatyzacji. Wynik JSON zawiera ogólny rezultat, efektywne źródło konfiguracji proxy, wszelkie błędy konfiguracji oraz każdą kontrolę miejsca docelowego. Dane uwierzytelniające URL proxy są redagowane w wyniku tekstowym i JSON:
```json
{
"ok": true,
"config": {
"enabled": true,
"proxyUrl": "http://127.0.0.1:3128/",
"source": "override",
"errors": []
},
"checks": [
{
"kind": "allowed",
"url": "https://example.com/",
"ok": true,
"status": 200
}
]
}
```
Możesz też zweryfikować ręcznie za pomocą `curl`:
```bash
curl -x http://127.0.0.1:3128 https://example.com/
curl -x http://127.0.0.1:3128 http://127.0.0.1/
curl -x http://127.0.0.1:3128 http://169.254.169.254/
```
Żądanie publiczne powinno się powieść. Żądania do pętli zwrotnej i metadanych powinny zakończyć się niepowodzeniem na proxy.
Żądanie publiczne powinno się powieść. Żądania loopback i do metadanych powinny zostać zablokowane przez proxy. W przypadku `openclaw proxy validate` wbudowany kanarek loopback potrafi odróżnić odmowę proxy od osiągalnego źródła. Niestandardowe sprawdzenia `--denied-url` nie mają tego kanarka, więc traktuj zarówno odpowiedzi HTTP, jak i niejednoznaczne awarie transportu jako niepowodzenia walidacji, chyba że Twoje proxy udostępnia specyficzny dla wdrożenia sygnał odmowy, który możesz zweryfikować osobno.
Następnie włącz kierowanie OpenClaw przez proxy:
Następnie włącz routing proxy OpenClaw:
```bash
openclaw config set proxy.enabled true
@ -158,7 +188,7 @@ openclaw config set proxy.proxyUrl http://127.0.0.1:3128
openclaw gateway run
```
albo ustaw:
lub ustaw:
```yaml
proxy:
@ -168,9 +198,9 @@ proxy:
## Ograniczenia
- Proxy poprawia pokrycie dla lokalnych dla procesu klientów HTTP i WebSocket JavaScript, ale nie jest piaskownicą sieciową na poziomie systemu operacyjnego.
- Surowe gniazda `net`, `tls` i `http2`, natywne dodatki oraz procesy potomne mogą omijać kierowanie przez proxy na poziomie Node, chyba że dziedziczą i respektują zmienne środowiskowe proxy.
- Lokalne WebUI użytkownika i lokalne serwery modeli powinny zostać dodane do listy dozwolonych w polityce proxy operatora, gdy jest to potrzebne; OpenClaw nie udostępnia dla nich ogólnego obejścia sieci lokalnej.
- Obejście proxy płaszczyzny sterowania Gateway jest celowo ograniczone do `localhost` i dosłownych URL z adresami IP pętli zwrotnej. Użyj `ws://127.0.0.1:18789`, `ws://[::1]:18789` lub `ws://localhost:18789` dla lokalnych bezpośrednich połączeń z płaszczyzną sterowania Gateway; inne nazwy hostów są kierowane jak zwykły ruch oparty na nazwach hostów.
- OpenClaw nie sprawdza, nie testuje ani nie certyfikuje Twojej polityki proxy.
- Traktuj zmiany polityki proxy jako operacyjne zmiany wrażliwe pod kątem bezpieczeństwa.
- Proxy zwiększa pokrycie dla lokalnych w procesie klientów HTTP i WebSocket JavaScript, ale nie jest sandboxem sieciowym na poziomie systemu operacyjnego.
- Surowe gniazda `net`, `tls` i `http2`, natywne dodatki oraz procesy podrzędne mogą omijać routing proxy na poziomie Node, chyba że dziedziczą i respektują zmienne środowiskowe proxy.
- Lokalne WebUI użytkownika i lokalne serwery modeli powinny zostać dodane do listy dozwolonych w zasadach proxy operatora, gdy jest to potrzebne; OpenClaw nie udostępnia dla nich ogólnego obejścia sieci lokalnej.
- Obejście proxy płaszczyzny sterowania Gateway jest celowo ograniczone do `localhost` i dosłownych adresów URL IP loopback. Użyj `ws://127.0.0.1:18789`, `ws://[::1]:18789` lub `ws://localhost:18789` dla lokalnych bezpośrednich połączeń z płaszczyzną sterowania Gateway; inne nazwy hostów są trasowane jak zwykły ruch oparty na nazwie hosta.
- OpenClaw nie sprawdza, nie testuje ani nie certyfikuje Twoich zasad proxy.
- Zmiany zasad proxy traktuj jako wrażliwe operacyjnie zmiany dotyczące bezpieczeństwa.

660
docs/pl/tools/acp-agents.md
View File

File diff suppressed because it is too large Load Diff

514
docs/pl/tools/plugin.md
View File

@ -1,29 +1,27 @@
---
read_when:
- Instalowanie lub konfigurowanie pluginów
- Zrozumienie reguł wykrywania i ładowania pluginów
- Omówienie reguł wykrywania i ładowania Pluginów
- Praca z pakietami Plugin zgodnymi z Codex/Claude
sidebarTitle: Install and Configure
summary: Instalowanie, konfigurowanie i zarządzanie pluginami OpenClaw
summary: Instalowanie, konfigurowanie i zarządzanie Pluginami OpenClaw
title: Pluginy
x-i18n:
generated_at: "2026-04-30T10:23:55Z"
generated_at: "2026-05-01T10:04:15Z"
model: gpt-5.5
provider: openai
source_hash: 7a12d158053c13b47a56d8d6b382818962e9b5109fdf8ededd3ecf92b83089e6
source_hash: 2df8aca086aafbd8f268820f1ccc2425079c69f1a673a4c2ea163aba1358ff51
source_path: tools/plugin.md
workflow: 16
---
Pluginy rozszerzają OpenClaw o nowe możliwości: kanały, dostawców modeli,
wiązki agentów, narzędzia, Skills, mowę, transkrypcję w czasie rzeczywistym,
głos w czasie rzeczywistym, rozumienie multimediów, generowanie obrazów,
generowanie wideo, pobieranie z sieci, wyszukiwanie w sieci i więcej. Niektóre
pluginy są **core** (dostarczane z OpenClaw), inne są **zewnętrzne**. Większość
zewnętrznych pluginów jest publikowana i odkrywana przez
[ClawHub](/pl/tools/clawhub). Npm pozostaje obsługiwane dla bezpośrednich instalacji
oraz dla tymczasowego zestawu pakietów pluginów należących do OpenClaw, dopóki
ta migracja się nie zakończy.
środowiska agentów, narzędzia, skills, mowę, transkrypcję w czasie rzeczywistym, głos
w czasie rzeczywistym, rozumienie mediów, generowanie obrazów, generowanie wideo, pobieranie
z sieci, wyszukiwanie w sieci i nie tylko. Niektóre Pluginy są **podstawowe** (dostarczane z OpenClaw), inne
są **zewnętrzne**. Większość zewnętrznych Pluginów jest publikowana i odkrywana przez
[ClawHub](/pl/tools/clawhub). Npm pozostaje obsługiwane przy instalacjach bezpośrednich oraz dla
tymczasowego zestawu pakietów Pluginów należących do OpenClaw do czasu zakończenia tej migracji.
## Szybki start
@ -51,7 +49,7 @@ ta migracja się nie zakończy.
openclaw gateway restart
```
Następnie skonfiguruj w `plugins.entries.\<id\>.config` w pliku konfiguracyjnym.
Następnie skonfiguruj pod `plugins.entries.\<id\>.config` w swoim pliku konfiguracyjnym.
</Step>
</Steps>
@ -64,76 +62,72 @@ Jeśli wolisz sterowanie natywne dla czatu, włącz `commands.plugins: true` i u
/plugin enable <plugin-id>
```
Ścieżka instalacji używa tego samego resolvera co CLI: ścieżka lokalna/archiwum,
jawne `clawhub:<pkg>`, jawne `npm:<pkg>` albo specyfikacja samego pakietu
(najpierw ClawHub, potem fallback npm).
Ścieżka instalacji używa tego samego resolvera co CLI: lokalna ścieżka/archiwum, jawne
`clawhub:<pkg>`, jawne `npm:<pkg>` albo specyfikacja samego pakietu (najpierw ClawHub, potem
awaryjnie npm).
Jeśli konfiguracja jest nieprawidłowa, instalacja zwykle kończy się bezpiecznym
niepowodzeniem i wskazuje `openclaw doctor --fix`. Jedynym wyjątkiem odzyskiwania
jest wąska ścieżka ponownej instalacji dołączonego pluginu dla pluginów, które
wybierają `openclaw.install.allowInvalidConfigRecovery`.
Podczas uruchamiania Gateway nieprawidłowa konfiguracja jednego pluginu jest
izolowana do tego pluginu: uruchamianie zapisuje w logach problem
`plugins.entries.<id>.config`, pomija ten plugin podczas ładowania i utrzymuje
pozostałe pluginy oraz kanały online. Uruchom `openclaw doctor --fix`, aby
poddać złą konfigurację pluginu kwarantannie przez wyłączenie tego wpisu pluginu
i usunięcie jego nieprawidłowego ładunku konfiguracji; zwykła kopia zapasowa
konfiguracji zachowuje poprzednie wartości. Gdy konfiguracja kanału odwołuje się
do pluginu, którego nie da się już odkryć, ale ten sam nieaktualny identyfikator
pluginu pozostaje w konfiguracji pluginów lub rekordach instalacji, uruchamianie
Gateway zapisuje ostrzeżenia i pomija ten kanał, zamiast blokować wszystkie inne
kanały. Uruchom `openclaw doctor --fix`, aby usunąć nieaktualne wpisy
kanału/pluginu; nieznane klucze kanałów bez dowodów na nieaktualny plugin nadal
powodują niepowodzenie walidacji, dzięki czemu literówki pozostają widoczne.
Jeśli ustawiono `plugins.enabled: false`, nieaktualne odwołania do pluginów są
traktowane jako bezczynne: uruchamianie Gateway pomija odkrywanie/ładowanie
pluginów, a `openclaw doctor` zachowuje wyłączoną konfigurację pluginów zamiast
automatycznie ją usuwać. Włącz pluginy ponownie przed uruchomieniem czyszczenia
przez doctor, jeśli chcesz usunąć nieaktualne identyfikatory pluginów.
Jeśli konfiguracja jest nieprawidłowa, instalacja zwykle kończy się zamknięciem i wskazuje
`openclaw doctor --fix`. Jedynym wyjątkiem odzyskiwania jest wąska ścieżka
ponownej instalacji dołączonego Pluginu dla Pluginów, które włączają
`openclaw.install.allowInvalidConfigRecovery`.
Podczas uruchamiania Gateway nieprawidłowa konfiguracja jednego Pluginu jest izolowana do tego Pluginu:
uruchamianie zapisuje problem `plugins.entries.<id>.config` w logach, pomija ten Plugin podczas
ładowania i utrzymuje pozostałe Pluginy oraz kanały online. Uruchom `openclaw doctor --fix`,
aby poddać złą konfigurację Pluginu kwarantannie przez wyłączenie tego wpisu Pluginu i usunięcie
jego nieprawidłowego ładunku konfiguracyjnego; normalna kopia zapasowa konfiguracji zachowuje poprzednie wartości.
Gdy konfiguracja kanału odwołuje się do Pluginu, którego nie da się już odkryć, ale ten sam
przestarzały identyfikator Pluginu pozostaje w konfiguracji Pluginu lub rekordach instalacji, uruchamianie Gateway
zapisuje ostrzeżenia i pomija ten kanał zamiast blokować wszystkie inne kanały.
Uruchom `openclaw doctor --fix`, aby usunąć przestarzałe wpisy kanału/Pluginu; nieznane
klucze kanałów bez dowodów na przestarzały Plugin nadal powodują błąd walidacji, aby literówki pozostały
widoczne.
Jeśli ustawiono `plugins.enabled: false`, przestarzałe odwołania do Pluginów są traktowane jako nieaktywne:
uruchamianie Gateway pomija odkrywanie/ładowanie Pluginów, a `openclaw doctor` zachowuje
wyłączoną konfigurację Pluginu zamiast automatycznie ją usuwać. Włącz Pluginy ponownie przed
uruchomieniem czyszczenia przez doctor, jeśli chcesz usunąć przestarzałe identyfikatory Pluginów.
Pakietowe instalacje OpenClaw nie instalują zachłannie drzewa zależności
uruchomieniowych każdego dołączonego pluginu. Gdy dołączony plugin należący do
OpenClaw jest aktywny z konfiguracji pluginów, starszej konfiguracji kanału albo
domyślnie włączonego manifestu, uruchamianie naprawia tylko zadeklarowane
zależności uruchomieniowe tego pluginu przed jego importem. Sam utrwalony stan
uwierzytelnienia kanału nie aktywuje dołączonego kanału na potrzeby naprawy
zależności uruchomieniowych podczas uruchamiania Gateway.
Pakietowe instalacje OpenClaw nie instalują z wyprzedzeniem pełnego drzewa
zależności runtime każdego dołączonego Pluginu. Gdy dołączony, należący do OpenClaw Plugin jest aktywny z
konfiguracji Pluginów, starszej konfiguracji kanału albo domyślnie włączonego manifestu, uruchamianie
naprawia tylko zadeklarowane zależności runtime tego Pluginu przed jego zaimportowaniem.
Sam utrwalony stan uwierzytelniania kanału nie aktywuje dołączonego kanału na potrzeby
naprawy zależności runtime podczas uruchamiania Gateway.
Jawne wyłączenie nadal ma pierwszeństwo: `plugins.entries.<id>.enabled: false`,
`plugins.deny`, `plugins.enabled: false` i `channels.<id>.enabled: false`
zapobiegają automatycznej naprawie dołączonych zależności uruchomieniowych dla
tego pluginu/kanału. Niepusta lista `plugins.allow` także ogranicza naprawę
domyślnie włączonych dołączonych zależności uruchomieniowych; jawne włączenie
dołączonego kanału (`channels.<id>.enabled: true`) nadal może naprawić zależności
pluginu tego kanału.
Zewnętrzne pluginy i niestandardowe ścieżki ładowania nadal trzeba instalować
przez `openclaw plugins install`.
zapobiegają automatycznej naprawie dołączonych zależności runtime dla tego Pluginu/kanału.
Niepusta lista `plugins.allow` również ogranicza domyślnie włączoną naprawę dołączonych zależności
runtime; jawne włączenie dołączonego kanału (`channels.<id>.enabled: true`) nadal może
naprawić zależności Pluginu tego kanału.
Zewnętrzne Pluginy i niestandardowe ścieżki ładowania nadal muszą być instalowane przez
`openclaw plugins install`.
Zobacz [Rozwiązywanie zależności Pluginów](/pl/plugins/dependency-resolution), aby poznać pełny
cykl planowania i przygotowania.
## Typy Plugin
## Typy Pluginów
OpenClaw rozpoznaje dwa formaty pluginów:
OpenClaw rozpoznaje dwa formaty Pluginów:
| Format | Jak działa | Przykłady |
| ------------ | ------------------------------------------------------------------- | ------------------------------------------------------- |
| **Natywny** | `openclaw.plugin.json` + moduł uruchomieniowy; wykonuje się w procesie | Oficjalne pluginy, społecznościowe pakiety npm |
| **Bundle** | Układ zgodny z Codex/Claude/Cursor; mapowany na funkcje OpenClaw | `.codex-plugin/`, `.claude-plugin/`, `.cursor-plugin/` |
| Format | Jak działa | Przykłady |
| ---------- | ----------------------------------------------------------------- | ------------------------------------------------------- |
| **Natywny** | `openclaw.plugin.json` + moduł runtime; wykonuje się w procesie | Oficjalne Pluginy, społecznościowe pakiety npm |
| **Bundle** | Układ zgodny z Codex/Claude/Cursor; mapowany na funkcje OpenClaw | `.codex-plugin/`, `.claude-plugin/`, `.cursor-plugin/` |
Oba pojawiają się w `openclaw plugins list`. Szczegóły bundle znajdziesz w [Plugin Bundles](/pl/plugins/bundles).
Oba pojawiają się w `openclaw plugins list`. Zobacz [Pakiety Pluginów](/pl/plugins/bundles), aby poznać szczegóły pakietów.
Jeśli piszesz natywny plugin, zacznij od [Building Plugins](/pl/plugins/building-plugins)
i [Plugin SDK Overview](/pl/plugins/sdk-overview).
Jeśli piszesz natywny Plugin, zacznij od [Tworzenia Pluginów](/pl/plugins/building-plugins)
oraz [Przeglądu Plugin SDK](/pl/plugins/sdk-overview).
## Punkty wejścia pakietu
Natywne pakiety npm pluginów muszą deklarować `openclaw.extensions` w `package.json`.
Natywne pakiety npm Pluginów muszą deklarować `openclaw.extensions` w `package.json`.
Każdy wpis musi pozostać wewnątrz katalogu pakietu i rozwiązywać się do czytelnego
pliku uruchomieniowego albo do pliku źródłowego TypeScript z wywnioskowanym
zbudowanym odpowiednikiem JavaScript, takim jak `src/index.ts` do `dist/index.js`.
pliku runtime albo do pliku źródłowego TypeScript z wywnioskowanym zbudowanym odpowiednikiem JavaScript,
takim jak `src/index.ts` do `dist/index.js`.
Użyj `openclaw.runtimeExtensions`, gdy opublikowane pliki uruchomieniowe nie
znajdują się w tych samych ścieżkach co wpisy źródłowe. Gdy `runtimeExtensions`
jest obecne, musi zawierać dokładnie jeden wpis dla każdego wpisu `extensions`.
Niedopasowane listy powodują niepowodzenie instalacji i odkrywania pluginów
zamiast cichego fallbacku do ścieżek źródłowych.
Użyj `openclaw.runtimeExtensions`, gdy opublikowane pliki runtime nie znajdują się w
tych samych ścieżkach co wpisy źródłowe. Gdy jest obecne, `runtimeExtensions` musi zawierać
dokładnie jeden wpis dla każdego wpisu `extensions`. Niedopasowane listy powodują błąd instalacji i
odkrywania Pluginów zamiast cichego powrotu do ścieżek źródłowych.
```json
{
@ -145,23 +139,21 @@ zamiast cichego fallbacku do ścieżek źródłowych.
}
```
## Oficjalne pluginy
## Oficjalne Pluginy
### Pakiety npm należące do OpenClaw podczas migracji
ClawHub jest podstawową ścieżką dystrybucji dla większości pluginów. Obecne
pakietowe wydania OpenClaw już zawierają wiele oficjalnych pluginów, więc w
normalnych konfiguracjach nie wymagają one osobnych instalacji npm. Dopóki każdy
plugin należący do OpenClaw nie zostanie zmigrowany do ClawHub, OpenClaw nadal
publikuje niektóre pakiety pluginów `@openclaw/*` w npm dla starszych/niestandardowych
instalacji oraz bezpośrednich przepływów pracy npm.
ClawHub jest podstawową ścieżką dystrybucji dla większości Pluginów. Obecne pakietowe
wydania OpenClaw zawierają już wiele oficjalnych Pluginów, więc w typowych konfiguracjach nie wymagają one
osobnych instalacji npm. Dopóki każdy Plugin należący do OpenClaw nie zostanie
przeniesiony do ClawHub, OpenClaw nadal dostarcza niektóre pakiety Pluginów `@openclaw/*` w
npm dla starszych/niestandardowych instalacji i bezpośrednich przepływów npm.
Jeśli npm zgłasza pakiet pluginu `@openclaw/*` jako przestarzały, ta wersja
pakietu pochodzi ze starszego zewnętrznego toru pakietów. Użyj dołączonego pluginu
z bieżącego OpenClaw albo lokalnego checkoutu, dopóki nie zostanie opublikowany
nowszy pakiet npm.
Jeśli npm zgłasza pakiet Pluginu `@openclaw/*` jako przestarzały, ta wersja pakietu
pochodzi ze starszej zewnętrznej linii pakietów. Użyj dołączonego Pluginu z
obecnego OpenClaw albo lokalnego checkoutu, dopóki nie zostanie opublikowany nowszy pakiet npm.
| Plugin | Pakiet | Dokumentacja |
| Plugin | Pakiet | Dokumentacja |
| --------------- | -------------------------- | ------------------------------------------ |
| BlueBubbles | `@openclaw/bluebubbles` | [BlueBubbles](/pl/channels/bluebubbles) |
| Discord | `@openclaw/discord` | [Discord](/pl/channels/discord) |
@ -177,7 +169,7 @@ nowszy pakiet npm.
| Zalo | `@openclaw/zalo` | [Zalo](/pl/channels/zalo) |
| Zalo Personal | `@openclaw/zalouser` | [Zalo Personal](/pl/plugins/zalouser) |
### Core (dostarczane z OpenClaw)
### Podstawowe (dostarczane z OpenClaw)
<AccordionGroup>
<Accordion title="Model providers (enabled by default)">
@ -189,12 +181,11 @@ nowszy pakiet npm.
</Accordion>
<Accordion title="Memory plugins">
- `memory-core` — dołączone wyszukiwanie pamięci (domyślnie przez `plugins.slots.memory`)
- `memory-lancedb` — instalowana na żądanie pamięć długoterminowa z automatycznym przywoływaniem/przechwytywaniem (ustaw `plugins.slots.memory = "memory-lancedb"`)
- `memory-core` — dołączone wyszukiwanie w pamięci (domyślnie przez `plugins.slots.memory`)
- `memory-lancedb` — instalowana na żądanie pamięć długoterminowa z automatycznym przypominaniem/przechwytywaniem (ustaw `plugins.slots.memory = "memory-lancedb"`)
Zobacz [Memory LanceDB](/pl/plugins/memory-lancedb), aby poznać konfigurację
osadzania zgodną z OpenAI, przykłady Ollama, limity przywoływania i
rozwiązywanie problemów.
Zobacz [Memory LanceDB](/pl/plugins/memory-lancedb), aby poznać konfigurację osadzania zgodną z OpenAI,
przykłady Ollama, limity przypominania i rozwiązywanie problemów.
</Accordion>
@ -203,13 +194,13 @@ nowszy pakiet npm.
</Accordion>
<Accordion title="Other">
- `browser` — dołączony plugin przeglądarki dla narzędzia przeglądarki, CLI `openclaw browser`, metody Gateway `browser.request`, środowiska uruchomieniowego przeglądarki i domyślnej usługi sterowania przeglądarką (włączony domyślnie; wyłącz przed zastąpieniem)
- `browser` — dołączony Plugin przeglądarki dla narzędzia przeglądarki, CLI `openclaw browser`, metody Gateway `browser.request`, runtime przeglądarki i domyślnej usługi sterowania przeglądarką (włączony domyślnie; wyłącz przed zastąpieniem)
- `copilot-proxy` — most VS Code Copilot Proxy (domyślnie wyłączony)
</Accordion>
</AccordionGroup>
Szukasz pluginów zewnętrznych? Zobacz [Community Plugins](/pl/plugins/community).
Szukasz Pluginów firm trzecich? Zobacz [Pluginy społeczności](/pl/plugins/community).
## Konfiguracja
@ -230,109 +221,112 @@ Szukasz pluginów zewnętrznych? Zobacz [Community Plugins](/pl/plugins/communit
| Pole | Opis |
| ---------------- | --------------------------------------------------------- |
| `enabled` | Główny przełącznik (domyślnie: `true`) |
| `allow` | Lista dozwolonych pluginów (opcjonalna) |
| `deny` | Lista zablokowanych pluginów (opcjonalna; blokada wygrywa) |
| `load.paths` | Dodatkowe pliki/katalogi pluginów |
| `slots` | Selektory wyłącznych slotów (np. `memory`, `contextEngine`) |
| `entries.\<id\>` | Przełączniki i konfiguracja per plugin |
| `allow` | Lista dozwolonych Pluginów (opcjonalnie) |
| `deny` | Lista zabronionych Pluginów (opcjonalnie; deny wygrywa) |
| `load.paths` | Dodatkowe pliki/katalogi Pluginów |
| `slots` | Wyłączne selektory slotów (np. `memory`, `contextEngine`) |
| `entries.\<id\>` | Przełączniki i konfiguracja dla poszczególnych Pluginów |
Zmiany konfiguracji **wymagają ponownego uruchomienia gatewaya**. Jeśli Gateway
działa z obserwowaniem konfiguracji i włączonym ponownym uruchamianiem w procesie
(domyślna ścieżka `openclaw gateway`), to ponowne uruchomienie jest zwykle
wykonywane automatycznie chwilę po zapisaniu konfiguracji. Nie ma obsługiwanej
ścieżki hot-reloadu dla natywnego kodu uruchomieniowego pluginu ani haków cyklu
życia; uruchom ponownie proces Gateway obsługujący kanał live, zanim oczekujesz,
że zaktualizowany kod `register(api)`, haki `api.on(...)`, narzędzia, usługi albo
haki provider/runtime zaczną działać.
`plugins.allow` jest wyłączne. Gdy nie jest puste, tylko wymienione Pluginy mogą się ładować
lub udostępniać narzędzia, nawet jeśli `tools.allow` zawiera `"*"` albo konkretną nazwę
narzędzia należącego do Pluginu. Jeśli lista dozwolonych narzędzi odwołuje się do narzędzi Pluginu, dodaj identyfikatory
posiadających je Pluginów do `plugins.allow` albo usuń `plugins.allow`; `openclaw doctor` ostrzega o takim
kształcie.
`openclaw plugins list` to lokalna migawka rejestru/konfiguracji pluginów. Plugin
oznaczony tam jako `enabled` oznacza, że utrwalony rejestr i bieżąca konfiguracja
pozwalają pluginowi uczestniczyć. Nie dowodzi to, że już działający zdalny proces
potomny Gateway został ponownie uruchomiony do tego samego kodu pluginu. W
konfiguracjach VPS/kontenerowych z procesami opakowującymi wysyłaj ponowne
uruchomienia do rzeczywistego procesu `openclaw gateway run` albo użyj
`openclaw gateway restart` wobec działającego Gateway.
Zmiany konfiguracji **wymagają restartu Gateway**. Jeśli Gateway działa z włączonym obserwowaniem konfiguracji
i restartem w procesie (domyślna ścieżka `openclaw gateway`), taki
restart jest zwykle wykonywany automatycznie chwilę po zapisaniu konfiguracji.
Nie ma obsługiwanej ścieżki hot-reload dla natywnego kodu runtime Pluginu ani hooków cyklu życia;
zrestartuj proces Gateway obsługujący kanał na żywo, zanim będziesz oczekiwać uruchomienia
zaktualizowanego kodu `register(api)`, hooków `api.on(...)`, narzędzi, usług albo
hooków dostawcy/runtime.
`openclaw plugins list` to lokalna migawka rejestru/konfiguracji Pluginów.
Włączony tam Plugin oznacza, że utrwalony rejestr i obecna konfiguracja pozwalają
Pluginowi uczestniczyć. Nie dowodzi to, że już działające zdalne dziecko Gateway
zrestartowało się do tego samego kodu Pluginu. W konfiguracjach VPS/kontenerowych z
procesami opakowującymi wysyłaj restarty do właściwego procesu `openclaw gateway run`
albo użyj `openclaw gateway restart` względem działającego Gateway.
<Accordion title="Plugin states: disabled vs missing vs invalid">
- **Wyłączony**: plugin istnieje, ale reguły włączania go wyłączyły. Konfiguracja jest zachowywana.
- **Brakujący**: konfiguracja odwołuje się do identyfikatora pluginu, którego odkrywanie nie znalazło.
- **Nieprawidłowy**: plugin istnieje, ale jego konfiguracja nie pasuje do zadeklarowanego schematu. Uruchamianie Gateway pomija tylko ten plugin; `openclaw doctor --fix` może poddać nieprawidłowy wpis kwarantannie przez wyłączenie go i usunięcie jego ładunku konfiguracji.
- **Wyłączony**: Plugin istnieje, ale reguły włączania go wyłączyły. Konfiguracja jest zachowana.
- **Brakujący**: konfiguracja odwołuje się do identyfikatora Pluginu, którego odkrywanie nie znalazło.
- **Nieprawidłowy**: Plugin istnieje, ale jego konfiguracja nie pasuje do zadeklarowanego schematu. Uruchamianie Gateway pomija tylko ten Plugin; `openclaw doctor --fix` może poddać nieprawidłowy wpis kwarantannie przez jego wyłączenie i usunięcie jego ładunku konfiguracyjnego.
</Accordion>
## Odkrywanie i pierwszeństwo
OpenClaw skanuje pluginy w tej kolejności (pierwsze dopasowanie wygrywa):
OpenClaw skanuje Pluginy w tej kolejności (pierwsze dopasowanie wygrywa):
<Steps>
<Step title="Config paths">
`plugins.load.paths` — jawne ścieżki plików lub katalogów. Ścieżki, które
wskazują z powrotem na własne pakietowe katalogi dołączonych pluginów
OpenClaw, są ignorowane; uruchom `openclaw doctor --fix`, aby usunąć te
nieaktualne aliasy.
<Step title="Ścieżki konfiguracji">
`plugins.load.paths` — jawne ścieżki plików lub katalogów. Ścieżki wskazujące
z powrotem na własne spakowane katalogi wbudowanych pluginów OpenClaw są ignorowane;
uruchom `openclaw doctor --fix`, aby usunąć te nieaktualne aliasy.
</Step>
<Step title="Workspace plugins">
<Step title="Pluginy obszaru roboczego">
`\<workspace\>/.openclaw/<plugin-root>/*.ts` i `\<workspace\>/.openclaw/<plugin-root>/*/index.ts`.
</Step>
<Step title="Global plugins">
<Step title="Pluginy globalne">
`~/.openclaw/<plugin-root>/*.ts` i `~/.openclaw/<plugin-root>/*/index.ts`.
</Step>
<Step title="Dołączone pluginy">
<Step title="Pluginy wbudowane">
Dostarczane z OpenClaw. Wiele z nich jest domyślnie włączonych (dostawcy modeli, mowa).
Inne wymagają jawnego włączenia.
</Step>
</Steps>
Instalacje pakietowe i obrazy Docker zwykle rozpoznają dołączone pluginy z
drzewa skompilowanego `dist/extensions`. Jeśli katalog źródłowy dołączonego pluginu jest
podmontowany bind mountem na odpowiadającej mu spakowanej ścieżce źródłowej, na przykład
`/app/extensions/synology-chat`, OpenClaw traktuje ten podmontowany katalog źródłowy
jako nakładkę źródeł dołączonego pluginu i wykrywa go przed spakowanym pakietem
`/app/dist/extensions/synology-chat`. Dzięki temu kontenerowe pętle pracy maintainerów
działają bez przełączania każdego dołączonego pluginu z powrotem na źródła TypeScript.
Instalacje pakietowe i obrazy Docker zwykle rozwiązują wbudowane pluginy z
skompilowanego drzewa `dist/extensions`. Jeśli katalog źródłowy wbudowanego pluginu
zostanie podmontowany przez bind mount nad odpowiadającą mu spakowaną ścieżką źródłową, na przykład
`/app/extensions/synology-chat`, OpenClaw traktuje ten zamontowany katalog źródłowy
jako nakładkę źródeł wbudowanych i wykrywa go przed spakowanym pakietem
`/app/dist/extensions/synology-chat`. Dzięki temu pętle kontenerowe maintainerów
działają bez przełączania każdego wbudowanego pluginu z powrotem na źródła TypeScript.
Ustaw `OPENCLAW_DISABLE_BUNDLED_SOURCE_OVERLAYS=1`, aby wymusić spakowane pakiety dist
nawet wtedy, gdy obecne są montowania nakładek źródłowych.
### Reguły włączania
- `plugins.enabled: false` wyłącza wszystkie pluginy i pomija wykrywanie oraz ładowanie pluginów
- `plugins.deny` zawsze ma pierwszeństwo przed allow
- `plugins.enabled: false` wyłącza wszystkie pluginy i pomija wykrywanie/ładowanie pluginów
- `plugins.deny` zawsze ma pierwszeństwo przed listą dozwolonych
- `plugins.entries.\<id\>.enabled: false` wyłącza ten plugin
- Pluginy pochodzące z obszaru roboczego są **domyślnie wyłączone** (muszą zostać jawnie włączone)
- Dołączone pluginy stosują wbudowany zestaw domyślnie włączony, chyba że zostanie nadpisany
- Wyłączne sloty mogą wymusić włączenie wybranego pluginu dla danego slotu
- Niektóre dołączone pluginy opt-in są włączane automatycznie, gdy konfiguracja wskazuje
powierzchnię należącą do pluginu, taką jak odwołanie do modelu dostawcy, konfigurację kanału lub
środowisko uruchomieniowe harness
- Nieaktualna konfiguracja pluginu jest zachowywana, gdy aktywne jest `plugins.enabled: false`;
ponownie włącz pluginy przed uruchomieniem czyszczenia doctor, jeśli chcesz usunąć nieaktualne identyfikatory
- Pluginy pochodzące z obszaru roboczego są **domyślnie wyłączone** (muszą być jawnie włączone)
- Wbudowane pluginy używają wbudowanego zestawu domyślnie włączonych, chyba że zostanie to nadpisane
- Ekskluzywne sloty mogą wymusić włączenie wybranego pluginu dla danego slotu
- Niektóre wbudowane pluginy opt-in są włączane automatycznie, gdy konfiguracja wskazuje
powierzchnię należącą do pluginu, taką jak referencja modelu dostawcy, konfiguracja kanału lub runtime
harnessu
- Nieaktualna konfiguracja pluginu jest zachowywana, gdy `plugins.enabled: false` jest aktywne;
włącz ponownie pluginy przed uruchomieniem czyszczenia przez doctor, jeśli chcesz usunąć nieaktualne identyfikatory
- Trasy Codex z rodziny OpenAI zachowują oddzielne granice pluginów:
`openai-codex/*` należy do pluginu OpenAI, natomiast dołączony plugin serwera aplikacji Codex
jest wybierany przez `agentRuntime.id: "codex"` albo starsze odwołania do modeli
`openai-codex/*` należy do pluginu OpenAI, natomiast wbudowany plugin serwera aplikacji Codex
jest wybierany przez `agentRuntime.id: "codex"` lub starsze referencje modeli
`codex/*`
## Rozwiązywanie problemów z hookami środowiska uruchomieniowego
## Rozwiązywanie problemów z hookami runtime
Jeśli plugin pojawia się w `plugins list`, ale efekty uboczne lub hooki `register(api)`
nie uruchamiają się w ruchu czatu na żywo, najpierw sprawdź te elementy:
Jeśli plugin pojawia się w `plugins list`, ale efekty uboczne lub hooki
`register(api)` nie uruchamiają się w ruchu czatu live, najpierw sprawdź:
- Uruchom `openclaw gateway status --deep --require-rpc` i potwierdź, że aktywny
adres URL Gateway, profil, ścieżka konfiguracji i proces są tymi, które edytujesz.
- Uruchom ponownie działający Gateway po zmianach instalacji, konfiguracji lub kodu pluginu. W kontenerach
opakowujących PID 1 może być tylko supervisorem; uruchom ponownie albo wyślij sygnał do procesu potomnego
- Uruchom ponownie Gateway live po zmianach instalacji/konfiguracji/kodu pluginu. W kontenerach
wrapperów PID 1 może być tylko supervisorem; uruchom ponownie albo wyślij sygnał do procesu potomnego
`openclaw gateway run`.
- Użyj `openclaw plugins inspect <id> --json`, aby potwierdzić rejestracje hooków i
diagnostykę. Niedostarczane w pakiecie hooki konwersacji, takie jak `llm_input`,
- Użyj `openclaw plugins inspect <id> --runtime --json`, aby potwierdzić rejestracje hooków i
diagnostykę. Niewbudowane hooki konwersacji, takie jak `llm_input`,
`llm_output`, `before_agent_finalize` i `agent_end`, wymagają
`plugins.entries.<id>.hooks.allowConversationAccess=true`.
- Do przełączania modeli preferuj `before_model_resolve`. Działa przed rozpoznaniem modelu
dla tur agenta; `llm_output` działa dopiero po tym, jak próba modelu
- Do przełączania modeli preferuj `before_model_resolve`. Uruchamia się przed
rozwiązywaniem modelu dla tur agenta; `llm_output` uruchamia się dopiero po tym, jak próba modelu
wygeneruje wynik asystenta.
- Jako dowodu efektywnego modelu sesji użyj `openclaw sessions` albo powierzchni
sesji/statusu Gateway, a podczas debugowania ładunków dostawcy uruchom
- Jako dowód efektywnego modelu sesji użyj `openclaw sessions` albo powierzchni
sesji/statusu Gateway, a podczas debugowania payloadów dostawcy uruchom
Gateway z `--raw-stream --raw-stream-path <path>`.
### Zduplikowana własność kanału lub narzędzia
@ -344,33 +338,33 @@ Objawy:
- `plugin tool name conflict (<plugin-id>): <tool-name>`
Oznacza to, że więcej niż jeden włączony plugin próbuje posiadać ten sam kanał,
przepływ konfiguracji albo nazwę narzędzia. Najczęstszą przyczyną jest zewnętrzny plugin kanału
zainstalowany obok dołączonego pluginu, który teraz zapewnia ten sam identyfikator kanału.
przepływ konfiguracji lub nazwę narzędzia. Najczęstszą przyczyną jest zewnętrzny plugin kanału
zainstalowany obok wbudowanego pluginu, który teraz zapewnia ten sam identyfikator kanału.
Kroki debugowania:
- Uruchom `openclaw plugins list --enabled --verbose`, aby zobaczyć każdy włączony plugin
i jego pochodzenie.
- Uruchom `openclaw plugins inspect <id> --json` dla każdego podejrzanego pluginu i
- Uruchom `openclaw plugins inspect <id> --runtime --json` dla każdego podejrzanego pluginu i
porównaj `channels`, `channelConfigs`, `tools` oraz diagnostykę.
- Uruchom `openclaw plugins registry --refresh` po zainstalowaniu albo usunięciu
- Uruchom `openclaw plugins registry --refresh` po zainstalowaniu lub usunięciu
pakietów pluginów, aby utrwalone metadane odzwierciedlały bieżącą instalację.
- Uruchom ponownie Gateway po zmianach instalacji, rejestru albo konfiguracji.
- Uruchom ponownie Gateway po zmianach instalacji, rejestru lub konfiguracji.
Opcje naprawy:
- Jeśli jeden plugin celowo zastępuje inny dla tego samego identyfikatora kanału, preferowany
plugin powinien zadeklarować `channelConfigs.<channel-id>.preferOver` z
- Jeśli jeden plugin celowo zastępuje inny dla tego samego identyfikatora kanału,
preferowany plugin powinien zadeklarować `channelConfigs.<channel-id>.preferOver` z
identyfikatorem pluginu o niższym priorytecie. Zobacz [/plugins/manifest#replacing-another-channel-plugin](/pl/plugins/manifest#replacing-another-channel-plugin).
- Jeśli duplikat jest przypadkowy, wyłącz jedną stronę za pomocą
`plugins.entries.<plugin-id>.enabled: false` albo usuń nieaktualną instalację pluginu.
- Jeśli jawnie włączono oba pluginy, OpenClaw zachowuje to żądanie i
zgłasza konflikt. Wybierz jednego właściciela kanału albo zmień nazwy narzędzi należących do pluginu,
aby powierzchnia środowiska uruchomieniowego była jednoznaczna.
aby powierzchnia runtime była jednoznaczna.
## Sloty pluginów (kategorie wyłączne)
## Sloty pluginów (kategorie ekskluzywne)
Niektóre kategorie są wyłączne (aktywna może być tylko jedna naraz):
Niektóre kategorie są ekskluzywne (aktywna może być tylko jedna naraz):
```json5
{
@ -383,9 +377,9 @@ Niektóre kategorie są wyłączne (aktywna może być tylko jedna naraz):
}
```
| Slot | Co kontroluje | Domyślnie |
| --------------- | ------------------------ | -------------------- |
| `memory` | Aktywny plugin pamięci | `memory-core` |
| Slot | Co kontroluje | Domyślne |
| --------------- | ---------------------- | ------------------- |
| `memory` | Plugin aktywnej pamięci | `memory-core` |
| `contextEngine` | Aktywny silnik kontekstu | `legacy` (wbudowany) |
## Dokumentacja CLI
@ -395,7 +389,8 @@ openclaw plugins list # compact inventory
openclaw plugins list --enabled # only enabled plugins
openclaw plugins list --verbose # per-plugin detail lines
openclaw plugins list --json # machine-readable inventory
openclaw plugins inspect <id> # deep detail
openclaw plugins inspect <id> # static detail
openclaw plugins inspect <id> --runtime # registered hooks/tools/diagnostics
openclaw plugins inspect <id> --json # machine-readable
openclaw plugins inspect --all # fleet-wide table
openclaw plugins info <id> # inspect alias
@ -426,78 +421,79 @@ openclaw plugins enable <id>
openclaw plugins disable <id>
```
Dołączone pluginy są dostarczane z OpenClaw. Wiele z nich jest domyślnie włączonych (na przykład
dołączeni dostawcy modeli, dołączeni dostawcy mowy i dołączony plugin przeglądarki).
Inne dołączone pluginy nadal wymagają `openclaw plugins enable <id>`.
Wbudowane pluginy są dostarczane z OpenClaw. Wiele z nich jest domyślnie włączonych (na przykład
wbudowani dostawcy modeli, wbudowani dostawcy mowy i wbudowany plugin przeglądarki).
Inne wbudowane pluginy nadal wymagają `openclaw plugins enable <id>`.
`--force` nadpisuje istniejący zainstalowany plugin albo pakiet hooków w miejscu. Użyj
`--force` nadpisuje istniejący zainstalowany plugin lub pakiet hooków w miejscu. Użyj
`openclaw plugins update <id-or-npm-spec>` do rutynowych aktualizacji śledzonych pluginów npm.
Nie jest obsługiwane z `--link`, które ponownie używa ścieżki źródłowej zamiast
kopiować ją do zarządzanego celu instalacji.
Nie jest obsługiwane z `--link`, który ponownie używa ścieżki źródłowej zamiast
kopiować do zarządzanego celu instalacji.
Gdy `plugins.allow` jest już ustawione, `openclaw plugins install` dodaje
identyfikator zainstalowanego pluginu do tej listy dozwolonych przed jego włączeniem. Jeśli ten sam identyfikator pluginu
jest obecny w `plugins.deny`, instalacja usuwa ten nieaktualny wpis deny, aby
jawna instalacja była możliwa do załadowania natychmiast po restarcie.
OpenClaw utrzymuje utrwalony lokalny rejestr pluginów jako model zimnego odczytu dla
inwentaryzacji pluginów, własności wkładów i planowania uruchamiania. Przepływy instalacji, aktualizacji,
OpenClaw utrzymuje trwały lokalny rejestr pluginów jako model zimnego odczytu dla
inwentarza pluginów, własności kontrybucji i planowania startu. Przepływy instalacji, aktualizacji,
odinstalowania, włączania i wyłączania odświeżają ten rejestr po zmianie stanu pluginu.
Ten sam plik `plugins/installs.json` przechowuje trwałe metadane instalacji w
górnopoziomowym `installRecords` oraz odtwarzalne metadane manifestu w `plugins`. Jeśli
rejestru brakuje, jest nieaktualny albo nieprawidłowy, `openclaw plugins registry
--refresh` odbudowuje jego widok manifestu z rekordów instalacji, zasad konfiguracji oraz
metadanych manifestu/pakietu bez ładowania modułów środowiska uruchomieniowego pluginów.
najwyższego poziomu `installRecords` oraz odbudowywalne metadane manifestów w `plugins`. Jeśli
rejestru brakuje, jest nieaktualny lub nieprawidłowy, `openclaw plugins registry
--refresh` odbudowuje jego widok manifestów z rekordów instalacji, polityki konfiguracji i
metadanych manifestu/pakietu bez ładowania modułów runtime pluginów.
`openclaw plugins update <id-or-npm-spec>` dotyczy śledzonych instalacji. Przekazanie
specyfikacji pakietu npm z tagiem dist-tag albo dokładną wersją rozpoznaje nazwę pakietu
z powrotem do śledzonego rekordu pluginu i zapisuje nową specyfikację dla przyszłych aktualizacji.
Przekazanie nazwy pakietu bez wersji przenosi dokładnie przypiętą instalację z powrotem na
domyślną linię wydań rejestru. Jeśli zainstalowany plugin npm już pasuje do
rozpoznanej wersji i zapisanej tożsamości artefaktu, OpenClaw pomija aktualizację
specyfikacji pakietu npm z dist-tag lub dokładną wersją rozwiązuje nazwę pakietu
z powrotem do rekordu śledzonego pluginu i zapisuje nową specyfikację do przyszłych aktualizacji.
Przekazanie nazwy pakietu bez wersji przenosi dokładnie przypiętą instalację z powrotem do
domyślnej linii wydań rejestru. Jeśli zainstalowany plugin npm już odpowiada
rozwiązanej wersji i zapisanej tożsamości artefaktu, OpenClaw pomija aktualizację
bez pobierania, ponownej instalacji ani przepisywania konfiguracji.
`--pin` działa tylko z npm. Nie jest obsługiwane z `--marketplace`, ponieważ
`--pin` dotyczy tylko npm. Nie jest obsługiwane z `--marketplace`, ponieważ
instalacje z marketplace utrwalają metadane źródła marketplace zamiast specyfikacji npm.
`--dangerously-force-unsafe-install` to awaryjne obejście dla fałszywych alarmów
z wbudowanego skanera niebezpiecznego kodu. Pozwala kontynuować instalacje pluginów
i aktualizacje pluginów mimo wbudowanych ustaleń `critical`, ale nadal
nie omija blokad zasad pluginu `before_install` ani blokowania przy niepowodzeniu skanowania.
Skany instalacyjne ignorują typowe pliki i katalogi testowe, takie jak `tests/`,
`--dangerously-force-unsafe-install` to awaryjne obejście fałszywych
alarmów z wbudowanego skanera niebezpiecznego kodu. Pozwala instalacjom pluginów
i aktualizacjom pluginów kontynuować mimo wbudowanych wyników `critical`, ale nadal
nie omija blokad polityki `before_install` pluginu ani blokowania po niepowodzeniu skanowania.
Skany instalacji ignorują typowe pliki i katalogi testowe, takie jak `tests/`,
`__tests__/`, `*.test.*` i `*.spec.*`, aby uniknąć blokowania spakowanych mocków testowych;
zadeklarowane punkty wejścia środowiska uruchomieniowego pluginu są nadal skanowane, nawet jeśli używają jednej z
zadeklarowane punkty wejścia runtime pluginu nadal są skanowane, nawet jeśli używają jednej z
tych nazw.
Ta flaga CLI dotyczy tylko przepływów instalacji/aktualizacji pluginów. Instalacje zależności Skills
obsługiwane przez Gateway używają zamiast tego odpowiadającego nadpisania żądania
`dangerouslyForceUnsafeInstall`, natomiast `openclaw skills install` pozostaje oddzielnym przepływem
pobierania/instalacji Skills z ClawHub.
obsługiwane przez Gateway używają zamiast tego odpowiadającego override żądania
`dangerouslyForceUnsafeInstall`, natomiast `openclaw skills install` pozostaje oddzielnym
przepływem pobierania/instalacji Skills z ClawHub.
Jeśli plugin opublikowany przez ciebie w ClawHub jest ukryty albo zablokowany przez skan, otwórz
Jeśli plugin opublikowany przez Ciebie w ClawHub jest ukryty lub zablokowany przez skan, otwórz
panel ClawHub albo uruchom `clawhub package rescan <name>`, aby poprosić ClawHub o ponowne
sprawdzenie. `--dangerously-force-unsafe-install` wpływa tylko na instalacje na twojej własnej
maszynie; nie prosi ClawHub o ponowne skanowanie pluginu ani o upublicznienie zablokowanego wydania.
sprawdzenie go. `--dangerously-force-unsafe-install` wpływa tylko na instalacje na Twoim własnym
komputerze; nie prosi ClawHub o ponowne przeskanowanie pluginu ani nie sprawia, że zablokowane wydanie
staje się publiczne.
Zgodne pakiety uczestniczą w tym samym przepływie list/inspekcji/włączania/wyłączania pluginów.
Bieżąca obsługa środowiska uruchomieniowego obejmuje pakietowe Skills, command-skills Claude,
Zgodne pakiety uczestniczą w tym samym przepływie list/inspect/enable/disable
pluginów. Bieżące wsparcie runtime obejmuje Skills pakietu, command-skills Claude,
domyślne ustawienia Claude `settings.json`, domyślne ustawienia Claude `.lsp.json` oraz zadeklarowane w manifeście
`lspServers`, command-skills Cursor oraz zgodne katalogi hooków Codex.
`lspServers`, command-skills Cursor i zgodne katalogi hooków Codex.
`openclaw plugins inspect <id>` zgłasza też wykryte możliwości pakietu oraz
`openclaw plugins inspect <id>` zgłasza również wykryte możliwości pakietu oraz
obsługiwane lub nieobsługiwane wpisy serwerów MCP i LSP dla pluginów opartych na pakietach.
Źródłami marketplace mogą być znana nazwa marketplace Claude z
`~/.claude/plugins/known_marketplaces.json`, lokalny katalog główny marketplace albo ścieżka
`marketplace.json`, skrót GitHub taki jak `owner/repo`, adres URL repozytorium GitHub
albo adres URL git. W przypadku zdalnych marketplace wpisy pluginów muszą pozostać wewnątrz
Źródła marketplace mogą być znaną nazwą marketplace Claude z
`~/.claude/plugins/known_marketplaces.json`, lokalnym katalogiem głównym marketplace albo
ścieżką `marketplace.json`, skrótem GitHub takim jak `owner/repo`, adresem URL repozytorium
GitHub albo adresem URL git. W przypadku zdalnych marketplace wpisy pluginów muszą pozostać wewnątrz
sklonowanego repozytorium marketplace i używać wyłącznie względnych źródeł ścieżek.
Zobacz [dokumentację CLI `openclaw plugins`](/pl/cli/plugins), aby poznać pełne szczegóły.
Zobacz [dokumentację CLI `openclaw plugins`](/pl/cli/plugins), aby uzyskać pełne szczegóły.
## Przegląd API pluginów
Natywne pluginy eksportują obiekt wejściowy, który udostępnia `register(api)`. Starsze
pluginy mogą nadal używać `activate(api)` jako starszego aliasu, ale nowe pluginy powinny
Natywne plugins eksportują obiekt wejścia, który udostępnia `register(api)`. Starsze
plugins mogą nadal używać `activate(api)` jako starszego aliasu, ale nowe plugins powinny
używać `register`.
```typescript
@ -518,75 +514,75 @@ export default definePluginEntry({
});
```
OpenClaw ładuje obiekt wejściowy i wywołuje `register(api)` podczas
aktywacji pluginu. Loader nadal wraca do `activate(api)` dla starszych pluginów,
ale dołączone pluginy i nowe zewnętrzne pluginy powinny traktować `register` jako
OpenClaw ładuje obiekt wejścia i wywołuje `register(api)` podczas aktywacji
plugin. Loader nadal awaryjnie używa `activate(api)` dla starszych plugins,
ale dołączone plugins i nowe zewnętrzne plugins powinny traktować `register` jako
publiczny kontrakt.
`api.registrationMode` informuje plugin, dlaczego jego punkt wejścia jest ładowany:
`api.registrationMode` informuje plugin, dlaczego jego wejście jest ładowane:
| Tryb | Znaczenie |
| --------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `full` | Aktywacja środowiska uruchomieniowego. Rejestruje narzędzia, haki, usługi, polecenia, trasy i inne aktywne efekty uboczne. |
| `discovery` | Odkrywanie możliwości tylko do odczytu. Rejestruje dostawców i metadane; zaufany kod wejściowy pluginu może zostać załadowany, ale aktywne efekty uboczne są pomijane. |
| `setup-only` | Ładowanie metadanych konfiguracji kanału przez lekkie wejście konfiguracji. |
| `setup-runtime` | Ładowanie konfiguracji kanału, które wymaga także wejścia środowiska uruchomieniowego. |
| `cli-metadata` | Tylko zbieranie metadanych poleceń CLI. |
| --------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `full` | Aktywacja w czasie działania. Rejestruje narzędzia, hooks, usługi, polecenia, trasy i inne aktywne efekty uboczne. |
| `discovery` | Odkrywanie możliwości tylko do odczytu. Rejestruje providers i metadane; zaufany kod wejścia plugin może zostać załadowany, ale należy pominąć aktywne efekty uboczne. |
| `setup-only` | Ładowanie metadanych konfiguracji kanału przez lekkie wejście konfiguracji. |
| `setup-runtime` | Ładowanie konfiguracji kanału, które wymaga także wejścia czasu działania. |
| `cli-metadata` | Tylko zbieranie metadanych poleceń CLI. |
Wpisy pluginów, które otwierają gniazda, bazy danych, procesy robocze w tle lub długotrwałe
klienty, powinny chronić te efekty uboczne warunkiem `api.registrationMode === "full"`.
Wejścia plugin, które otwierają sockets, bazy danych, workers w tle lub długotrwałe
clients, powinny zabezpieczać te efekty uboczne warunkiem `api.registrationMode === "full"`.
Ładowania odkrywania są buforowane oddzielnie od ładowań aktywujących i nie zastępują
działającego rejestru Gateway. Odkrywanie nie aktywuje, ale nie oznacza braku importów:
OpenClaw może wykonać zaufany wpis pluginu lub moduł pluginu kanału, aby zbudować
migawkę. Utrzymuj najwyższe poziomy modułów jako lekkie i wolne od efektów ubocznych, a
klientów sieciowych, podprocesy, nasłuchiwacze, odczyty poświadczeń i uruchamianie usług
przenieś za ścieżki pełnego środowiska uruchomieniowego.
działającego rejestru Gateway. Odkrywanie jest nieaktywujące, ale nie jest wolne od importów:
OpenClaw może ocenić zaufane wejście plugin lub moduł plugin kanału, aby zbudować
snapshot. Utrzymuj najwyższe poziomy modułów lekkie i wolne od efektów ubocznych, a klientów
sieciowych, podprocesy, listeners, odczyty poświadczeń i uruchamianie usług przenieś
za ścieżki pełnego czasu działania.
Typowe metody rejestracji:
| Metoda | Co rejestruje |
| --------------------------------------- | ---------------------------- |
| `registerProvider` | Dostawca modelu (LLM) |
| `registerChannel` | Kanał czatu |
| `registerTool` | Narzędzie agenta |
| `registerHook` / `on(...)` | Haki cyklu życia |
| `registerSpeechProvider` | Tekst na mowę / STT |
| `registerRealtimeTranscriptionProvider` | Strumieniowe STT |
| `registerRealtimeVoiceProvider` | Dwukierunkowy głos w czasie rzeczywistym |
| `registerMediaUnderstandingProvider` | Analiza obrazów/audio |
| `registerImageGenerationProvider` | Generowanie obrazów |
| `registerMusicGenerationProvider` | Generowanie muzyki |
| Metoda | Co rejestruje |
| --------------------------------------- | --------------------------- |
| `registerProvider` | Model provider (LLM) |
| `registerChannel` | Kanał czatu |
| `registerTool` | Narzędzie agenta |
| `registerHook` / `on(...)` | Hooks cyklu życia |
| `registerSpeechProvider` | Text-to-speech / STT |
| `registerRealtimeTranscriptionProvider` | Strumieniowe STT |
| `registerRealtimeVoiceProvider` | Dwukierunkowy głos w czasie rzeczywistym |
| `registerMediaUnderstandingProvider` | Analiza obrazu/audio |
| `registerImageGenerationProvider` | Generowanie obrazów |
| `registerMusicGenerationProvider` | Generowanie muzyki |
| `registerVideoGenerationProvider` | Generowanie wideo |
| `registerWebFetchProvider` | Dostawca pobierania / scrapingu WWW |
| `registerWebSearchProvider` | Wyszukiwanie w sieci |
| `registerHttpRoute` | Punkt końcowy HTTP |
| `registerWebFetchProvider` | Provider pobierania / scrapingu z sieci |
| `registerWebSearchProvider` | Wyszukiwanie w sieci |
| `registerHttpRoute` | Punkt końcowy HTTP |
| `registerCommand` / `registerCli` | Polecenia CLI |
| `registerContextEngine` | Silnik kontekstu |
| `registerService` | Usługa w tle |
| `registerContextEngine` | Silnik kontekstu |
| `registerService` | Usługa w tle |
Zachowanie osłon haków dla typowanych haków cyklu życia:
Zachowanie guard hooks dla typowanych hooks cyklu życia:
- `before_tool_call`: `{ block: true }` jest końcowe; procedury obsługi o niższym priorytecie są pomijane.
- `before_tool_call`: `{ block: false }` nic nie robi i nie usuwa wcześniejszej blokady.
- `before_install`: `{ block: true }` jest końcowe; procedury obsługi o niższym priorytecie są pomijane.
- `before_install`: `{ block: false }` nic nie robi i nie usuwa wcześniejszej blokady.
- `message_sending`: `{ cancel: true }` jest końcowe; procedury obsługi o niższym priorytecie są pomijane.
- `message_sending`: `{ cancel: false }` nic nie robi i nie usuwa wcześniejszego anulowania.
- `before_tool_call`: `{ block: true }` jest terminalne; handlers o niższym priorytecie są pomijane.
- `before_tool_call`: `{ block: false }` jest operacją bez efektu i nie usuwa wcześniejszej blokady.
- `before_install`: `{ block: true }` jest terminalne; handlers o niższym priorytecie są pomijane.
- `before_install`: `{ block: false }` jest operacją bez efektu i nie usuwa wcześniejszej blokady.
- `message_sending`: `{ cancel: true }` jest terminalne; handlers o niższym priorytecie są pomijane.
- `message_sending`: `{ cancel: false }` jest operacją bez efektu i nie usuwa wcześniejszego anulowania.
Natywny serwer aplikacji Codex przekazuje natywne zdarzenia narzędzi Codex z powrotem do tej
powierzchni haków. Pluginy mogą blokować natywne narzędzia Codex przez `before_tool_call`,
obserwować wyniki przez `after_tool_call` i uczestniczyć w zatwierdzaniu Codex
`PermissionRequest`. Most nie przepisuje jeszcze argumentów natywnych narzędzi Codex.
Dokładna granica obsługi środowiska uruchomieniowego Codex znajduje się w
Natywny serwer aplikacji Codex mostkuje natywne zdarzenia narzędzi Codex z powrotem do tej
powierzchni hook. Plugins mogą blokować natywne narzędzia Codex przez `before_tool_call`,
obserwować wyniki przez `after_tool_call` i uczestniczyć w zatwierdzeniach
`PermissionRequest` Codex. Mostek nie przepisuje jeszcze natywnych argumentów narzędzi
Codex. Dokładna granica obsługi runtime Codex znajduje się w
[kontrakcie obsługi Codex harness v1](/pl/plugins/codex-harness#v1-support-contract).
Pełne zachowanie typowanych haków opisuje [omówienie SDK](/pl/plugins/sdk-overview#hook-decision-semantics).
Pełne zachowanie typowanych hooks opisano w [omówieniu SDK](/pl/plugins/sdk-overview#hook-decision-semantics).
## Powiązane
- [Tworzenie pluginów](/pl/plugins/building-plugins) — utwórz własny plugin
- [Pakiety pluginów](/pl/plugins/bundles) — zgodność pakietów Codex/Claude/Cursor
- [Manifest pluginu](/pl/plugins/manifest) — schemat manifestu
- [Rejestrowanie narzędzi](/pl/plugins/building-plugins#registering-agent-tools) — dodaj narzędzia agenta w pluginie
- [Wewnętrzna architektura pluginów](/pl/plugins/architecture) — model możliwości i potok ładowania
- [Pluginy społecznościowe](/pl/plugins/community) — listy zewnętrznych pluginów
- [Tworzenie plugins](/pl/plugins/building-plugins) — utwórz własny plugin
- [Pakiety plugin](/pl/plugins/bundles) — zgodność pakietów Codex/Claude/Cursor
- [Manifest plugin](/pl/plugins/manifest) — schemat manifestu
- [Rejestrowanie narzędzi](/pl/plugins/building-plugins#registering-agent-tools) — dodawanie narzędzi agenta w plugin
- [Wewnętrzna architektura plugin](/pl/plugins/architecture) — model możliwości i pipeline ładowania
- [Społecznościowe plugins](/pl/plugins/community) — listy rozwiązań zewnętrznych