From c09c2eaea13af6288d7244d30eee02b815a38c73 Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Thu, 9 Apr 2026 01:33:10 +0000 Subject: [PATCH] chore(i18n): refresh pl translations --- docs/pl/channels/matrix.md | 713 ++++----- docs/pl/concepts/agent-loop.md | 161 +- docs/pl/concepts/dreaming.md | 169 +- docs/pl/concepts/memory.md | 140 +- docs/pl/concepts/model-providers.md | 551 +++---- docs/pl/concepts/qa-e2e-automation.md | 114 +- docs/pl/gateway/cli-backends.md | 165 +- docs/pl/gateway/configuration-reference.md | 920 +++++------ docs/pl/gateway/doctor.md | 459 +++--- docs/pl/help/testing.md | 674 ++++---- ...refactor-real-plugin-sdk-workspace-plan.md | 579 ------- docs/pl/plugins/architecture.md | 1368 +++++++++-------- docs/pl/plugins/manifest.md | 365 ++--- docs/pl/plugins/sdk-migration.md | 472 +++--- docs/pl/plugins/sdk-overview.md | 508 +++--- docs/pl/plugins/sdk-provider-plugins.md | 281 ++-- docs/pl/providers/inferrs.md | 71 +- docs/pl/providers/qwen.md | 138 +- 18 files changed, 3714 insertions(+), 4134 deletions(-) delete mode 100644 docs/pl/plans/2026-04-05-002-refactor-real-plugin-sdk-workspace-plan.md diff --git a/docs/pl/channels/matrix.md b/docs/pl/channels/matrix.md index 1e5c69f22..07d67777f 100644 --- a/docs/pl/channels/matrix.md +++ b/docs/pl/channels/matrix.md @@ -5,34 +5,34 @@ read_when: summary: Stan obsługi Matrix, konfiguracja i przykłady ustawień title: Matrix x-i18n: - generated_at: "2026-04-08T02:17:08Z" + generated_at: "2026-04-09T01:32:55Z" model: gpt-5.4 provider: openai - source_hash: ec926df79a41fa296d63f0ec7219d0f32e075628d76df9ea490e93e4c5030f83 + source_hash: 28fc13c7620c1152200315ae69c94205da6de3180c53c814dd8ce03b5cb1758f source_path: channels/matrix.md workflow: 15 --- # Matrix -Matrix to dołączona wtyczka kanału Matrix dla OpenClaw. -Korzysta z oficjalnego `matrix-js-sdk` i obsługuje wiadomości prywatne, pokoje, wątki, multimedia, reakcje, ankiety, lokalizację oraz E2EE. +Matrix jest dołączoną wtyczką kanału dla OpenClaw. +Używa oficjalnego `matrix-js-sdk` i obsługuje wiadomości prywatne, pokoje, wątki, multimedia, reakcje, ankiety, lokalizację oraz E2EE. ## Dołączona wtyczka -Matrix jest dostarczany jako dołączona wtyczka w aktualnych wydaniach OpenClaw, więc zwykłe +Matrix jest dostarczany jako dołączona wtyczka w bieżących wydaniach OpenClaw, więc zwykłe spakowane kompilacje nie wymagają osobnej instalacji. Jeśli używasz starszej kompilacji lub niestandardowej instalacji, która nie zawiera Matrix, zainstaluj go ręcznie: -Instalacja z npm: +Zainstaluj z npm: ```bash openclaw plugins install @openclaw/matrix ``` -Instalacja z lokalnego checkoutu: +Zainstaluj z lokalnego checkoutu: ```bash openclaw plugins install ./path/to/local/matrix-plugin @@ -43,56 +43,52 @@ Zobacz [Wtyczki](/pl/tools/plugin), aby poznać zachowanie wtyczek i zasady inst ## Konfiguracja 1. Upewnij się, że wtyczka Matrix jest dostępna. - - Aktualne spakowane wydania OpenClaw już ją zawierają. + - Bieżące spakowane wydania OpenClaw już ją zawierają. - Starsze/niestandardowe instalacje mogą dodać ją ręcznie za pomocą powyższych poleceń. 2. Utwórz konto Matrix na swoim homeserverze. -3. Skonfiguruj `channels.matrix`, używając jednego z wariantów: +3. Skonfiguruj `channels.matrix` z użyciem: - `homeserver` + `accessToken`, lub - `homeserver` + `userId` + `password`. 4. Uruchom ponownie gateway. -5. Rozpocznij wiadomość prywatną z botem albo zaproś go do pokoju. - - Nowe zaproszenia Matrix działają tylko wtedy, gdy `channels.matrix.autoJoin` na to pozwala. +5. Rozpocznij wiadomość prywatną z botem lub zaproś go do pokoju. + - Nowe zaproszenia Matrix działają tylko wtedy, gdy pozwala na to `channels.matrix.autoJoin`. -Ścieżki konfiguracji interaktywnej: +Ścieżki interaktywnej konfiguracji: ```bash openclaw channels add openclaw configure --section channels ``` -O co dokładnie pyta kreator Matrix: +Kreator Matrix pyta o: - URL homeservera -- metoda uwierzytelniania: token dostępu lub hasło -- identyfikator użytkownika tylko wtedy, gdy wybierzesz uwierzytelnianie hasłem -- opcjonalna nazwa urządzenia +- metodę uwierzytelniania: access token lub hasło +- ID użytkownika (tylko przy uwierzytelnianiu hasłem) +- opcjonalną nazwę urządzenia - czy włączyć E2EE -- czy skonfigurować teraz dostęp do pokojów Matrix -- czy skonfigurować teraz automatyczne dołączanie do zaproszeń Matrix -- gdy automatyczne dołączanie do zaproszeń jest włączone, czy ma mieć wartość `allowlist`, `always` czy `off` +- czy skonfigurować dostęp do pokoi i automatyczne dołączanie do zaproszeń -Istotne zachowanie kreatora: +Kluczowe zachowania kreatora: -- Jeśli zmienne środowiskowe uwierzytelniania Matrix już istnieją dla wybranego konta, a to konto nie ma jeszcze zapisanego uwierzytelniania w konfiguracji, kreator oferuje skrót do env, dzięki czemu konfiguracja może pozostawić uwierzytelnianie w zmiennych środowiskowych zamiast kopiować sekrety do konfiguracji. -- Gdy interaktywnie dodajesz kolejne konto Matrix, wprowadzona nazwa konta jest normalizowana do identyfikatora konta używanego w konfiguracji i zmiennych środowiskowych. Na przykład `Ops Bot` staje się `ops-bot`. -- Monity listy dozwolonych dla wiadomości prywatnych od razu akceptują pełne wartości `@user:server`. Nazwy wyświetlane działają tylko wtedy, gdy wyszukiwanie w katalogu na żywo znajdzie jedno dokładne dopasowanie; w przeciwnym razie kreator poprosi o ponowną próbę z pełnym identyfikatorem Matrix. -- Monity listy dozwolonych dla pokojów bezpośrednio akceptują identyfikatory pokojów i aliasy. Mogą też na żywo rozwiązywać nazwy dołączonych pokojów, ale nierozwiązane nazwy są podczas konfiguracji zachowywane tylko w postaci wpisanej i później są ignorowane przez runtime przy rozwiązywaniu listy dozwolonych. Preferuj `!room:server` lub `#alias:server`. -- Kreator wyświetla teraz jawne ostrzeżenie przed krokiem automatycznego dołączania do zaproszeń, ponieważ domyślna wartość `channels.matrix.autoJoin` to `off`; agenty nie dołączą do zaproszonych pokojów ani nowych zaproszeń w stylu wiadomości prywatnej, dopóki tego nie ustawisz. -- W trybie listy dozwolonych dla automatycznego dołączania do zaproszeń używaj wyłącznie stabilnych celów zaproszeń: `!roomId:server`, `#alias:server` lub `*`. Zwykłe nazwy pokojów są odrzucane. -- Tożsamość pokoju/sesji w runtime używa stabilnego identyfikatora pokoju Matrix. Aliasy zadeklarowane przez pokój są używane tylko jako dane wejściowe do wyszukiwania, a nie jako długoterminowy klucz sesji lub stabilna tożsamość grupy. -- Aby rozwiązać nazwy pokojów przed ich zapisaniem, użyj `openclaw channels resolve --channel matrix "Project Room"`. +- Jeśli zmienne środowiskowe uwierzytelniania Matrix już istnieją, a dla tego konta nie zapisano jeszcze uwierzytelniania w konfiguracji, kreator zaproponuje skrót do użycia zmiennych środowiskowych, aby zachować uwierzytelnianie w env vars. +- Nazwy kont są normalizowane do ID konta. Na przykład `Ops Bot` staje się `ops-bot`. +- Wpisy allowlist dla wiadomości prywatnych akceptują bezpośrednio `@user:server`; nazwy wyświetlane działają tylko wtedy, gdy wyszukiwanie w katalogu na żywo znajdzie dokładnie jedno dopasowanie. +- Wpisy allowlist dla pokoi akceptują bezpośrednio ID pokoi i aliasy. Preferuj `!room:server` lub `#alias:server`; nierozwiązane nazwy są ignorowane w czasie działania podczas rozwiązywania allowlist. +- W trybie allowlist dla automatycznego dołączania do zaproszeń używaj wyłącznie stabilnych celów zaproszeń: `!roomId:server`, `#alias:server` lub `*`. Zwykłe nazwy pokoi są odrzucane. +- Aby rozwiązać nazwy pokoi przed zapisaniem, użyj `openclaw channels resolve --channel matrix "Project Room"`. -Domyślna wartość `channels.matrix.autoJoin` to `off`. +`channels.matrix.autoJoin` ma domyślnie wartość `off`. -Jeśli pozostawisz tę opcję nieustawioną, bot nie będzie dołączał do zaproszonych pokojów ani nowych zaproszeń w stylu wiadomości prywatnej, więc nie pojawi się w nowych grupach ani zaproszonych wiadomościach prywatnych, chyba że najpierw dołączysz ręcznie. +Jeśli pozostawisz tę opcję nieustawioną, bot nie będzie dołączać do zaproszonych pokoi ani nowych zaproszeń w stylu wiadomości prywatnych, więc nie pojawi się w nowych grupach ani zaproszonych wiadomościach prywatnych, chyba że najpierw dołączysz ręcznie. Ustaw `autoJoin: "allowlist"` razem z `autoJoinAllowlist`, aby ograniczyć, które zaproszenia są akceptowane, albo ustaw `autoJoin: "always"`, jeśli ma dołączać do każdego zaproszenia. -W trybie `allowlist` opcja `autoJoinAllowlist` akceptuje tylko `!roomId:server`, `#alias:server` lub `*`. +W trybie `allowlist` `autoJoinAllowlist` akceptuje tylko `!roomId:server`, `#alias:server` lub `*`. -Przykład listy dozwolonych: +Przykład allowlist: ```json5 { @@ -154,10 +150,10 @@ Konfiguracja oparta na haśle (token jest buforowany po zalogowaniu): ``` Matrix przechowuje zbuforowane poświadczenia w `~/.openclaw/credentials/matrix/`. -Konto domyślne używa `credentials.json`; nazwane konta używają `credentials-.json`. -Gdy znajdują się tam zbuforowane poświadczenia, OpenClaw traktuje Matrix jako skonfigurowany na potrzeby konfiguracji, doctor i wykrywania stanu kanału, nawet jeśli bieżące uwierzytelnianie nie jest ustawione bezpośrednio w konfiguracji. +Konto domyślne używa `credentials.json`; konta nazwane używają `credentials-.json`. +Jeśli w tej lokalizacji istnieją zbuforowane poświadczenia, OpenClaw traktuje Matrix jako skonfigurowany na potrzeby konfiguracji, doctor i wykrywania statusu kanału, nawet jeśli bieżące uwierzytelnianie nie jest ustawione bezpośrednio w konfiguracji. -Odpowiedniki w zmiennych środowiskowych (używane, gdy klucz konfiguracyjny nie jest ustawiony): +Odpowiedniki zmiennych środowiskowych (używane, gdy klucz konfiguracji nie jest ustawiony): - `MATRIX_HOMESERVER` - `MATRIX_ACCESS_TOKEN` @@ -166,7 +162,7 @@ Odpowiedniki w zmiennych środowiskowych (używane, gdy klucz konfiguracyjny nie - `MATRIX_DEVICE_ID` - `MATRIX_DEVICE_NAME` -Dla kont innych niż domyślne użyj zmiennych środowiskowych przypisanych do konta: +Dla kont innych niż domyślne użyj zmiennych środowiskowych z zakresem konta: - `MATRIX__HOMESERVER` - `MATRIX__ACCESS_TOKEN` @@ -180,19 +176,19 @@ Przykład dla konta `ops`: - `MATRIX_OPS_HOMESERVER` - `MATRIX_OPS_ACCESS_TOKEN` -Dla znormalizowanego identyfikatora konta `ops-bot` użyj: +Dla znormalizowanego ID konta `ops-bot` użyj: - `MATRIX_OPS_X2D_BOT_HOMESERVER` - `MATRIX_OPS_X2D_BOT_ACCESS_TOKEN` -Matrix zamienia znaki interpunkcyjne w identyfikatorach kont, aby uniknąć kolizji w zmiennych środowiskowych przypisanych do kont. +Matrix escapuje znaki interpunkcyjne w ID kont, aby zmienne środowiskowe z zakresem konta nie kolidowały ze sobą. Na przykład `-` staje się `_X2D_`, więc `ops-prod` mapuje się na `MATRIX_OPS_X2D_PROD_*`. -Interaktywny kreator oferuje skrót do zmiennych środowiskowych tylko wtedy, gdy te zmienne uwierzytelniania już istnieją i wybrane konto nie ma jeszcze zapisanego uwierzytelniania Matrix w konfiguracji. +Interaktywny kreator oferuje skrót do zmiennych środowiskowych tylko wtedy, gdy te zmienne uwierzytelniania są już obecne, a wybrane konto nie ma jeszcze zapisanego uwierzytelniania Matrix w konfiguracji. ## Przykład konfiguracji -To praktyczna bazowa konfiguracja z parowaniem wiadomości prywatnych, listą dozwolonych pokojów i włączonym E2EE: +To praktyczna bazowa konfiguracja z parowaniem wiadomości prywatnych, allowlistą pokoi i włączonym E2EE: ```json5 { @@ -227,20 +223,17 @@ To praktyczna bazowa konfiguracja z parowaniem wiadomości prywatnych, listą do } ``` -`autoJoin` dotyczy ogólnie zaproszeń Matrix, a nie tylko zaproszeń do pokojów/grup. -Obejmuje to także nowe zaproszenia w stylu wiadomości prywatnej. W momencie zaproszenia OpenClaw nie wie -wiarygodnie, czy zaproszony pokój zostanie ostatecznie potraktowany jako wiadomość prywatna czy grupa, -dlatego wszystkie zaproszenia najpierw przechodzą przez tę samą decyzję `autoJoin`. `dm.policy` nadal -ma zastosowanie po dołączeniu bota i sklasyfikowaniu pokoju jako wiadomość prywatna, więc `autoJoin` -steruje zachowaniem dołączania, a `dm.policy` steruje zachowaniem odpowiedzi/dostępu. +`autoJoin` dotyczy wszystkich zaproszeń Matrix, w tym zaproszeń w stylu wiadomości prywatnych. OpenClaw nie może niezawodnie +określić, czy zaproszony pokój jest wiadomością prywatną czy grupą w momencie zaproszenia, więc wszystkie zaproszenia przechodzą najpierw przez `autoJoin`. +`dm.policy` ma zastosowanie po dołączeniu bota i sklasyfikowaniu pokoju jako wiadomości prywatnej. -## Podglądy streamingu +## Podglądy strumieniowe -Streaming odpowiedzi Matrix jest opcjonalny. +Strumieniowanie odpowiedzi Matrix jest opcjonalne. -Ustaw `channels.matrix.streaming` na `"partial"`, jeśli chcesz, aby OpenClaw wysyłał pojedynczą -odpowiedź z podglądem na żywo, edytował ten podgląd na miejscu podczas generowania tekstu przez model, -a następnie finalizował go po zakończeniu odpowiedzi: +Ustaw `channels.matrix.streaming` na `"partial"`, jeśli chcesz, aby OpenClaw wysłał pojedynczą odpowiedź +z podglądem na żywo, edytował ten podgląd na miejscu podczas generowania tekstu przez model, a następnie sfinalizował go po +zakończeniu odpowiedzi: ```json5 { @@ -252,38 +245,38 @@ a następnie finalizował go po zakończeniu odpowiedzi: } ``` -- `streaming: "off"` to ustawienie domyślne. OpenClaw czeka na końcową odpowiedź i wysyła ją jednorazowo. -- `streaming: "partial"` tworzy jedną edytowalną wiadomość podglądu dla bieżącego bloku odpowiedzi asystenta, używając zwykłych wiadomości tekstowych Matrix. Zachowuje to starsze zachowanie Matrix polegające na powiadamianiu najpierw o podglądzie, więc standardowe klienty mogą powiadamiać na podstawie pierwszego przesłanego tekstu podglądu zamiast gotowego bloku. -- `streaming: "quiet"` tworzy jedno edytowalne ciche powiadomienie podglądu dla bieżącego bloku odpowiedzi asystenta. Używaj tego tylko wtedy, gdy skonfigurujesz też reguły push odbiorcy dla sfinalizowanych edycji podglądu. -- `blockStreaming: true` włącza osobne wiadomości postępu Matrix. Gdy streaming podglądu jest włączony, Matrix zachowuje wersję roboczą na żywo dla bieżącego bloku i zachowuje ukończone bloki jako oddzielne wiadomości. -- Gdy streaming podglądu jest włączony, a `blockStreaming` jest wyłączone, Matrix edytuje wersję roboczą na żywo na miejscu i finalizuje to samo zdarzenie po zakończeniu bloku lub tury. -- Jeśli podgląd przestaje mieścić się w jednym zdarzeniu Matrix, OpenClaw zatrzymuje streaming podglądu i wraca do normalnego końcowego dostarczenia. -- Odpowiedzi z multimediami nadal wysyłają załączniki normalnie. Jeśli starego podglądu nie da się już bezpiecznie ponownie użyć, OpenClaw usuwa go przed wysłaniem końcowej odpowiedzi z multimediami. -- Edycje podglądu generują dodatkowe wywołania API Matrix. Pozostaw streaming wyłączony, jeśli chcesz zachować najbardziej ostrożne zachowanie względem limitów szybkości. +- `streaming: "off"` to wartość domyślna. OpenClaw czeka na końcową odpowiedź i wysyła ją tylko raz. +- `streaming: "partial"` tworzy jedną edytowalną wiadomość podglądu dla bieżącego bloku odpowiedzi asystenta z użyciem zwykłych wiadomości tekstowych Matrix. Zachowuje to starsze zachowanie Matrix polegające na powiadamianiu najpierw o podglądzie, więc standardowe klienty mogą powiadamiać o pierwszym strumieniowanym tekście podglądu zamiast o ukończonym bloku. +- `streaming: "quiet"` tworzy jeden edytowalny cichy komunikat podglądu dla bieżącego bloku odpowiedzi asystenta. Używaj tego tylko wtedy, gdy skonfigurujesz także reguły push odbiorców dla sfinalizowanych edycji podglądu. +- `blockStreaming: true` włącza osobne komunikaty postępu Matrix. Gdy strumieniowanie podglądu jest włączone, Matrix zachowuje wersję roboczą na żywo dla bieżącego bloku i pozostawia ukończone bloki jako osobne wiadomości. +- Gdy podgląd strumieniowy jest włączony, a `blockStreaming` jest wyłączone, Matrix edytuje wersję roboczą na żywo na miejscu i finalizuje to samo zdarzenie po zakończeniu bloku lub tury. +- Jeśli podgląd nie mieści się już w jednym zdarzeniu Matrix, OpenClaw zatrzymuje strumieniowanie podglądu i wraca do zwykłego końcowego dostarczania. +- Odpowiedzi multimedialne nadal wysyłają załączniki normalnie. Jeśli nieaktualnego podglądu nie da się już bezpiecznie ponownie użyć, OpenClaw usuwa go przed wysłaniem końcowej odpowiedzi multimedialnej. +- Edycje podglądu generują dodatkowe wywołania API Matrix. Pozostaw strumieniowanie wyłączone, jeśli chcesz zachować najbardziej konserwatywne zachowanie względem limitów szybkości. `blockStreaming` samo w sobie nie włącza podglądów wersji roboczych. -Użyj `streaming: "partial"` lub `streaming: "quiet"` do edycji podglądu; dopiero potem dodaj `blockStreaming: true`, jeśli chcesz także, by ukończone bloki asystenta pozostawały widoczne jako oddzielne wiadomości postępu. +Użyj `streaming: "partial"` lub `streaming: "quiet"` dla edycji podglądu; następnie dodaj `blockStreaming: true` tylko wtedy, gdy chcesz również, aby ukończone bloki asystenta pozostawały widoczne jako osobne komunikaty postępu. -Jeśli potrzebujesz standardowych powiadomień Matrix bez niestandardowych reguł push, użyj `streaming: "partial"` dla zachowania „najpierw podgląd” albo pozostaw `streaming` wyłączone dla dostarczania tylko końcowej odpowiedzi. Gdy `streaming: "off"`: +Jeśli potrzebujesz standardowych powiadomień Matrix bez niestandardowych reguł push, użyj `streaming: "partial"` dla zachowania „najpierw podgląd” albo pozostaw `streaming` wyłączone dla dostarczania wyłącznie finalnej odpowiedzi. Przy `streaming: "off"`: - `blockStreaming: true` wysyła każdy ukończony blok jako zwykłą powiadamiającą wiadomość Matrix. - `blockStreaming: false` wysyła tylko końcową ukończoną odpowiedź jako zwykłą powiadamiającą wiadomość Matrix. -### Samodzielnie hostowane reguły push dla cichych sfinalizowanych podglądów +### Samohostowane reguły push dla cichych sfinalizowanych podglądów -Jeśli utrzymujesz własną infrastrukturę Matrix i chcesz, aby ciche podglądy wysyłały powiadomienie dopiero po zakończeniu bloku lub +Jeśli uruchamiasz własną infrastrukturę Matrix i chcesz, aby ciche podglądy wysyłały powiadomienie tylko po zakończeniu bloku lub końcowej odpowiedzi, ustaw `streaming: "quiet"` i dodaj regułę push per użytkownik dla sfinalizowanych edycji podglądu. Zwykle jest to konfiguracja po stronie użytkownika-odbiorcy, a nie globalna zmiana konfiguracji homeservera: Szybka mapa przed rozpoczęciem: -- użytkownik odbiorca = osoba, która ma otrzymywać powiadomienie -- użytkownik bota = konto Matrix OpenClaw wysyłające odpowiedź -- do poniższych wywołań API użyj tokena dostępu użytkownika odbiorcy -- dopasuj `sender` w regule push do pełnego MXID użytkownika bota +- użytkownik odbiorca = osoba, która ma otrzymać powiadomienie +- użytkownik bota = konto Matrix OpenClaw, które wysyła odpowiedź +- do poniższych wywołań API użyj access tokena użytkownika odbiorcy +- w regule push dopasuj `sender` do pełnego MXID użytkownika bota -1. Skonfiguruj OpenClaw tak, aby używał cichych podglądów: +1. Skonfiguruj OpenClaw do używania cichych podglądów: ```json5 { @@ -295,12 +288,12 @@ Szybka mapa przed rozpoczęciem: } ``` -2. Upewnij się, że konto odbiorcy już otrzymuje zwykłe powiadomienia push Matrix. Reguły cichych podglądów - działają tylko wtedy, gdy ten użytkownik ma już działające pushery/urządzenia. +2. Upewnij się, że konto odbiorcy już otrzymuje zwykłe powiadomienia push Matrix. Reguły + cichych podglądów działają tylko wtedy, gdy ten użytkownik ma już działające pushery/urządzenia. -3. Pobierz token dostępu użytkownika odbiorcy. +3. Pobierz access token użytkownika odbiorcy. - Użyj tokena użytkownika odbierającego, a nie tokena bota. - - Najłatwiej zwykle ponownie użyć tokena istniejącej sesji klienta. + - Najłatwiej zwykle ponownie wykorzystać istniejący token sesji klienta. - Jeśli musisz wygenerować nowy token, możesz zalogować się przez standardowe API Matrix Client-Server: ```bash @@ -325,10 +318,10 @@ curl -sS \ "https://matrix.example.org/_matrix/client/v3/pushers" ``` -Jeśli to zwraca brak aktywnych pusherów/urządzeń, najpierw napraw zwykłe powiadomienia Matrix, zanim dodasz -poniższą regułę OpenClaw. +Jeśli to zwraca brak aktywnych pusherów/urządzeń, najpierw napraw zwykłe powiadomienia Matrix przed dodaniem +poniższej reguły OpenClaw. -OpenClaw oznacza sfinalizowane edycje podglądu tylko tekstowego znacznikiem: +OpenClaw oznacza sfinalizowane edycje tekstowych podglądów za pomocą: ```json { @@ -366,17 +359,17 @@ curl -sS -X PUT \ }' ``` -Zastąp te wartości przed uruchomieniem polecenia: +Przed uruchomieniem polecenia zastąp te wartości: -- `https://matrix.example.org`: bazowy URL twojego homeservera -- `$USER_ACCESS_TOKEN`: token dostępu użytkownika odbierającego -- `openclaw-finalized-preview-botname`: identyfikator reguły unikalny dla tego bota dla tego użytkownika odbierającego -- `@bot:example.org`: MXID twojego bota Matrix OpenClaw, a nie MXID użytkownika odbierającego +- `https://matrix.example.org`: podstawowy URL Twojego homeservera +- `$USER_ACCESS_TOKEN`: access token użytkownika odbierającego +- `openclaw-finalized-preview-botname`: ID reguły unikalne dla tego bota i tego użytkownika odbierającego +- `@bot:example.org`: MXID bota Matrix OpenClaw, a nie MXID użytkownika odbierającego -Ważne w konfiguracjach z wieloma botami: +Ważne dla konfiguracji z wieloma botami: -- Reguły push są kluczowane przez `ruleId`. Ponowne uruchomienie `PUT` względem tego samego identyfikatora reguły aktualizuje tę jedną regułę. -- Jeśli jeden użytkownik odbierający ma otrzymywać powiadomienia od wielu kont botów Matrix OpenClaw, utwórz jedną regułę na bota z unikalnym identyfikatorem reguły dla każdego dopasowania nadawcy. +- Reguły push są kluczowane według `ruleId`. Ponowne uruchomienie `PUT` względem tego samego ID reguły aktualizuje tę jedną regułę. +- Jeśli jeden użytkownik odbierający ma otrzymywać powiadomienia dla wielu kont botów Matrix OpenClaw, utwórz jedną regułę na bota z unikalnym ID reguły dla każdego dopasowania nadawcy. - Prostym wzorcem jest `openclaw-finalized-preview-`, na przykład `openclaw-finalized-preview-ops` lub `openclaw-finalized-preview-support`. Reguła jest oceniana względem nadawcy zdarzenia: @@ -392,10 +385,10 @@ curl -sS \ "https://matrix.example.org/_matrix/client/v3/pushrules/global/override/openclaw-finalized-preview-botname" ``` -7. Przetestuj odpowiedź strumieniowaną. W trybie quiet pokój powinien pokazać cichy podgląd wersji roboczej, a końcowa +7. Przetestuj odpowiedź strumieniowaną. W trybie cichym pokój powinien pokazać cichy podgląd wersji roboczej, a końcowa edycja na miejscu powinna wysłać powiadomienie po zakończeniu bloku lub tury. -Jeśli później chcesz usunąć regułę, usuń ten sam identyfikator reguły tokenem użytkownika odbierającego: +Jeśli później będziesz potrzebować usunąć regułę, usuń to samo ID reguły tokenem użytkownika odbierającego: ```bash curl -sS -X DELETE \ @@ -405,37 +398,33 @@ curl -sS -X DELETE \ Uwagi: -- Utwórz regułę z użyciem tokena dostępu użytkownika odbierającego, a nie bota. +- Utwórz regułę tokenem dostępu użytkownika odbierającego, a nie tokenem bota. - Nowe reguły `override` zdefiniowane przez użytkownika są wstawiane przed domyślnymi regułami wyciszającymi, więc nie jest potrzebny dodatkowy parametr kolejności. -- Dotyczy to tylko edycji podglądu tylko tekstowego, które OpenClaw może bezpiecznie sfinalizować na miejscu. Fallbacki dla multimediów i starych podglądów nadal używają normalnego dostarczania Matrix. -- Jeśli `GET /_matrix/client/v3/pushers` nie pokazuje żadnych pusherów, użytkownik nie ma jeszcze działającego dostarczania powiadomień push Matrix dla tego konta/urządzenia. +- Dotyczy to tylko tekstowych edycji podglądu, które OpenClaw może bezpiecznie sfinalizować na miejscu. Fallbacki multimedialne i fallbacki nieaktualnych podglądów nadal używają zwykłego dostarczania Matrix. +- Jeśli `GET /_matrix/client/v3/pushers` pokazuje brak pusherów, użytkownik nie ma jeszcze działającego dostarczania powiadomień push Matrix dla tego konta/urządzenia. #### Synapse W przypadku Synapse powyższa konfiguracja zwykle sama w sobie wystarcza: -- Żadna specjalna zmiana w `homeserver.yaml` nie jest wymagana dla sfinalizowanych powiadomień o podglądzie OpenClaw. -- Jeśli twoje wdrożenie Synapse już wysyła zwykłe powiadomienia push Matrix, token użytkownika + wywołanie `pushrules` powyżej to główny krok konfiguracji. -- Jeśli uruchamiasz Synapse za reverse proxy lub workerami, upewnij się, że `/_matrix/client/.../pushrules/` trafia poprawnie do Synapse. -- Jeśli używasz workerów Synapse, upewnij się, że pushery są sprawne. Dostarczanie push jest obsługiwane przez proces główny lub `synapse.app.pusher` / skonfigurowane workery pusherów. +- Nie jest wymagana żadna specjalna zmiana w `homeserver.yaml` dla sfinalizowanych powiadomień podglądu OpenClaw. +- Jeśli wdrożenie Synapse już wysyła zwykłe powiadomienia push Matrix, głównym krokiem konfiguracji jest token użytkownika + powyższe wywołanie `pushrules`. +- Jeśli uruchamiasz Synapse za reverse proxy lub workerami, upewnij się, że `/_matrix/client/.../pushrules/` poprawnie dociera do Synapse. +- Jeśli używasz workerów Synapse, upewnij się, że pushery działają prawidłowo. Dostarczaniem powiadomień push zajmuje się proces główny albo `synapse.app.pusher` / skonfigurowane workery pusherów. #### Tuwunel -Dla Tuwunel użyj tego samego przepływu konfiguracji i wywołania API `pushrules`, które pokazano powyżej: +W przypadku Tuwunel użyj tego samego przebiegu konfiguracji i wywołania API `pushrules`, które pokazano powyżej: -- Żadna konfiguracja specyficzna dla Tuwunel nie jest wymagana dla samego znacznika sfinalizowanego podglądu. -- Jeśli zwykłe powiadomienia Matrix już działają dla tego użytkownika, token użytkownika + wywołanie `pushrules` powyżej to główny krok konfiguracji. -- Jeśli wydaje się, że powiadomienia znikają, gdy użytkownik jest aktywny na innym urządzeniu, sprawdź, czy włączono `suppress_push_when_active`. Tuwunel dodał tę opcję w Tuwunel 1.4.2 12 września 2025 r. i może ona celowo wyciszać powiadomienia push na innych urządzeniach, gdy jedno urządzenie jest aktywne. +- Nie jest wymagana żadna konfiguracja specyficzna dla Tuwunel dla samego znacznika sfinalizowanego podglądu. +- Jeśli zwykłe powiadomienia Matrix już działają dla tego użytkownika, głównym krokiem konfiguracji jest token użytkownika + powyższe wywołanie `pushrules`. +- Jeśli powiadomienia wydają się znikać, gdy użytkownik jest aktywny na innym urządzeniu, sprawdź, czy włączono `suppress_push_when_active`. Tuwunel dodał tę opcję w Tuwunel 1.4.2 12 września 2025 roku i może ona celowo wyciszać powiadomienia push na innych urządzeniach, gdy jedno urządzenie jest aktywne. -## Szyfrowanie i weryfikacja +## Pokoje bot-do-bota -W zaszyfrowanych pokojach (E2EE) wychodzące zdarzenia obrazów używają `thumbnail_file`, dzięki czemu podglądy obrazów są szyfrowane razem z pełnym załącznikiem. Niezaszyfrowane pokoje nadal używają zwykłego `thumbnail_url`. Nie jest wymagana żadna konfiguracja — wtyczka automatycznie wykrywa stan E2EE. +Domyślnie wiadomości Matrix z innych skonfigurowanych kont Matrix OpenClaw są ignorowane. -### Pokoje bot-bot - -Domyślnie wiadomości Matrix od innych skonfigurowanych kont Matrix OpenClaw są ignorowane. - -Użyj `allowBots`, gdy celowo chcesz dopuścić ruch Matrix między agentami: +Użyj `allowBots`, jeśli celowo chcesz dopuścić ruch Matrix między agentami: ```json5 { @@ -452,13 +441,17 @@ Użyj `allowBots`, gdy celowo chcesz dopuścić ruch Matrix między agentami: } ``` -- `allowBots: true` akceptuje wiadomości od innych skonfigurowanych kont botów Matrix w dozwolonych pokojach i wiadomościach prywatnych. +- `allowBots: true` akceptuje wiadomości z innych skonfigurowanych kont botów Matrix w dozwolonych pokojach i wiadomościach prywatnych. - `allowBots: "mentions"` akceptuje te wiadomości tylko wtedy, gdy w pokojach wyraźnie wspominają tego bota. Wiadomości prywatne są nadal dozwolone. - `groups..allowBots` nadpisuje ustawienie na poziomie konta dla jednego pokoju. -- OpenClaw nadal ignoruje wiadomości od tego samego identyfikatora użytkownika Matrix, aby uniknąć pętli odpowiedzi do samego siebie. -- Matrix nie udostępnia tu natywnej flagi bota; OpenClaw traktuje „napisane przez bota” jako „wysłane przez inne skonfigurowane konto Matrix na tym gatewayu OpenClaw”. +- OpenClaw nadal ignoruje wiadomości z tego samego ID użytkownika Matrix, aby uniknąć pętli odpowiedzi do samego siebie. +- Matrix nie udostępnia tutaj natywnej flagi bota; OpenClaw traktuje „wiadomość autorstwa bota” jako „wysłaną przez inne skonfigurowane konto Matrix na tym gatewayu OpenClaw”. -Przy włączaniu ruchu bot-bot w pokojach współdzielonych używaj ścisłych list dozwolonych pokojów i wymagań wzmianki. +Używaj ścisłych allowlist pokoi i wymagań wzmianki podczas włączania ruchu bot-do-bota we współdzielonych pokojach. + +## Szyfrowanie i weryfikacja + +W szyfrowanych pokojach (E2EE) wychodzące zdarzenia obrazów używają `thumbnail_file`, dzięki czemu podglądy obrazów są szyfrowane razem z pełnym załącznikiem. Nieszyfrowane pokoje nadal używają zwykłego `thumbnail_url`. Nie jest wymagana żadna konfiguracja — wtyczka automatycznie wykrywa stan E2EE. Włącz szyfrowanie: @@ -476,19 +469,19 @@ Włącz szyfrowanie: } ``` -Sprawdź stan weryfikacji: +Sprawdź status weryfikacji: ```bash openclaw matrix verify status ``` -Szczegółowy stan (pełna diagnostyka): +Szczegółowy status (pełna diagnostyka): ```bash openclaw matrix verify status --verbose ``` -Dołącz zapisany klucz odzyskiwania w wyniku czytelnym maszynowo: +Uwzględnij zapisany klucz odzyskiwania w wyjściu do odczytu maszynowego: ```bash openclaw matrix verify status --include-recovery-key --json @@ -500,8 +493,6 @@ Zainicjalizuj cross-signing i stan weryfikacji: openclaw matrix verify bootstrap ``` -Obsługa wielu kont: użyj `channels.matrix.accounts` z poświadczeniami per konto i opcjonalnym `name`. Zobacz [Dokumentację konfiguracji](/pl/gateway/configuration-reference#multi-account-all-channels), aby poznać wspólny wzorzec. - Szczegółowa diagnostyka bootstrap: ```bash @@ -526,19 +517,19 @@ Szczegółowe informacje o weryfikacji urządzenia: openclaw matrix verify device "" --verbose ``` -Sprawdź kondycję kopii zapasowej kluczy pokojów: +Sprawdź stan kopii zapasowej kluczy pokojów: ```bash openclaw matrix verify backup status ``` -Szczegółowa diagnostyka kondycji kopii zapasowej: +Szczegółowa diagnostyka stanu kopii zapasowej: ```bash openclaw matrix verify backup status --verbose ``` -Przywróć klucze pokojów z kopii zapasowej na serwerze: +Przywróć klucze pokojów z kopii zapasowej serwera: ```bash openclaw matrix verify backup restore @@ -550,20 +541,20 @@ Szczegółowa diagnostyka przywracania: openclaw matrix verify backup restore --verbose ``` -Usuń bieżącą kopię zapasową na serwerze i utwórz nową bazę kopii zapasowej. Jeśli zapisany -klucz kopii zapasowej nie może zostać poprawnie wczytany, ten reset może także odtworzyć magazyn sekretów, aby -przyszłe zimne starty mogły wczytać nowy klucz kopii zapasowej: +Usuń bieżącą kopię zapasową z serwera i utwórz nową bazową kopię zapasową. Jeśli zapisany +klucz kopii zapasowej nie daje się poprawnie wczytać, ten reset może także odtworzyć secret storage, aby +przyszłe zimne starty mogły załadować nowy klucz kopii zapasowej: ```bash openclaw matrix verify backup reset --yes ``` -Wszystkie polecenia `verify` są domyślnie zwięzłe (łącznie z cichym wewnętrznym logowaniem SDK) i pokazują szczegółową diagnostykę tylko z `--verbose`. -Przy skryptowaniu użyj `--json`, aby otrzymać pełny wynik czytelny maszynowo. +Wszystkie polecenia `verify` są domyślnie zwięzłe (w tym ciche wewnętrzne logowanie SDK) i pokazują szczegółową diagnostykę tylko z `--verbose`. +Do skryptów używaj `--json`, aby uzyskać pełne dane do odczytu maszynowego. -W konfiguracjach z wieloma kontami polecenia CLI Matrix używają domyślnego niejawnego konta Matrix, chyba że przekażesz `--account `. +W konfiguracjach wielokontowych polecenia Matrix CLI używają domyślnego niejawnego konta Matrix, chyba że przekażesz `--account `. Jeśli skonfigurujesz wiele nazwanych kont, najpierw ustaw `channels.matrix.defaultAccount`, w przeciwnym razie te niejawne operacje CLI zatrzymają się i poproszą o jawny wybór konta. -Używaj `--account`, gdy chcesz, aby operacje weryfikacji lub urządzenia były jawnie kierowane do konkretnego nazwanego konta: +Używaj `--account`, gdy chcesz, aby operacje weryfikacji lub urządzeń były jawnie kierowane do nazwanego konta: ```bash openclaw matrix verify status --account assistant @@ -571,42 +562,43 @@ openclaw matrix verify backup restore --account assistant openclaw matrix devices list --account assistant ``` -Gdy szyfrowanie jest wyłączone lub niedostępne dla nazwanego konta, ostrzeżenia Matrix i błędy weryfikacji wskazują na klucz konfiguracji tego konta, na przykład `channels.matrix.accounts.assistant.encryption`. +Gdy szyfrowanie jest wyłączone lub niedostępne dla nazwanego konta, ostrzeżenia Matrix i błędy weryfikacji wskazują klucz konfiguracji tego konta, na przykład `channels.matrix.accounts.assistant.encryption`. ### Co oznacza „zweryfikowane” -OpenClaw traktuje to urządzenie Matrix jako zweryfikowane tylko wtedy, gdy zostało zweryfikowane przez twoją własną tożsamość cross-signing. -W praktyce `openclaw matrix verify status --verbose` ujawnia trzy sygnały zaufania: +OpenClaw traktuje to urządzenie Matrix jako zweryfikowane tylko wtedy, gdy jest ono zweryfikowane przez Twoją własną tożsamość cross-signing. +W praktyce `openclaw matrix verify status --verbose` pokazuje trzy sygnały zaufania: - `Locally trusted`: to urządzenie jest zaufane tylko przez bieżącego klienta -- `Cross-signing verified`: SDK zgłasza urządzenie jako zweryfikowane przez cross-signing -- `Signed by owner`: urządzenie jest podpisane przez twój własny klucz self-signing +- `Cross-signing verified`: SDK zgłasza to urządzenie jako zweryfikowane przez cross-signing +- `Signed by owner`: urządzenie jest podpisane przez Twój własny klucz self-signing -`Verified by owner` przyjmuje wartość `yes` tylko wtedy, gdy obecna jest weryfikacja cross-signing lub podpis właściciela. +`Verified by owner` przyjmuje wartość `yes` tylko wtedy, gdy istnieje weryfikacja cross-signing lub podpis właściciela. Samo lokalne zaufanie nie wystarcza, aby OpenClaw traktował urządzenie jako w pełni zweryfikowane. ### Co robi bootstrap -`openclaw matrix verify bootstrap` to polecenie naprawy i konfiguracji dla zaszyfrowanych kont Matrix. -Wykonuje po kolei wszystkie poniższe działania: +`openclaw matrix verify bootstrap` to polecenie naprawy i konfiguracji dla szyfrowanych kont Matrix. +Wykonuje kolejno wszystkie poniższe czynności: -- inicjalizuje magazyn sekretów, ponownie używając istniejącego klucza odzyskiwania, gdy to możliwe -- inicjalizuje cross-signing i wysyła brakujące publiczne klucze cross-signing -- próbuje oznaczyć i podpisać bieżące urządzenie przez cross-signing +- inicjalizuje secret storage, ponownie używając istniejącego klucza odzyskiwania, gdy to możliwe +- inicjalizuje cross-signing i przesyła brakujące publiczne klucze cross-signing +- próbuje oznaczyć i podpisać krzyżowo bieżące urządzenie - tworzy nową kopię zapasową kluczy pokojów po stronie serwera, jeśli jeszcze nie istnieje -Jeśli homeserver wymaga uwierzytelniania interaktywnego do wysłania kluczy cross-signing, OpenClaw próbuje najpierw bez uwierzytelniania, potem z `m.login.dummy`, a następnie z `m.login.password`, gdy skonfigurowano `channels.matrix.password`. +Jeśli homeserver wymaga interaktywnego uwierzytelniania do przesłania kluczy cross-signing, OpenClaw najpierw próbuje przesłania bez uwierzytelniania, potem z `m.login.dummy`, a następnie z `m.login.password`, gdy skonfigurowano `channels.matrix.password`. -Używaj `--force-reset-cross-signing` tylko wtedy, gdy celowo chcesz porzucić bieżącą tożsamość cross-signing i utworzyć nową. +Używaj `--force-reset-cross-signing` tylko wtedy, gdy świadomie chcesz odrzucić bieżącą tożsamość cross-signing i utworzyć nową. -Jeśli celowo chcesz porzucić bieżącą kopię zapasową kluczy pokojów i rozpocząć nową +Jeśli świadomie chcesz porzucić bieżącą kopię zapasową kluczy pokojów i rozpocząć nową bazę kopii zapasowej dla przyszłych wiadomości, użyj `openclaw matrix verify backup reset --yes`. -Rób to tylko wtedy, gdy akceptujesz, że niemożliwa do odzyskania stara zaszyfrowana historia pozostanie -niedostępna i że OpenClaw może odtworzyć magazyn sekretów, jeśli bieżącego sekretu kopii zapasowej nie da się bezpiecznie wczytać. +Rób to tylko wtedy, gdy akceptujesz, że nieodwracalnie utracona stara zaszyfrowana historia pozostanie +niedostępna oraz że OpenClaw może odtworzyć secret storage, jeśli bieżącego sekretu kopii zapasowej +nie da się bezpiecznie załadować. ### Nowa baza kopii zapasowej -Jeśli chcesz zachować działanie przyszłych zaszyfrowanych wiadomości i akceptujesz utratę niemożliwej do odzyskania starej historii, uruchom po kolei te polecenia: +Jeśli chcesz zachować działanie przyszłych zaszyfrowanych wiadomości i akceptujesz utratę nieodzyskiwalnej starej historii, uruchom te polecenia po kolei: ```bash openclaw matrix verify backup reset --yes @@ -614,64 +606,71 @@ openclaw matrix verify backup status --verbose openclaw matrix verify status ``` -Dodaj `--account ` do każdego polecenia, gdy chcesz jawnie wskazać nazwane konto Matrix. +Dodaj `--account ` do każdego polecenia, jeśli chcesz jawnie wskazać nazwane konto Matrix. ### Zachowanie przy uruchamianiu -Gdy `encryption: true`, domyślna wartość `startupVerification` w Matrix to `"if-unverified"`. -Przy uruchamianiu, jeśli to urządzenie nadal nie jest zweryfikowane, Matrix poprosi o samoweryfikację w innym kliencie Matrix, -pominie duplikaty żądań, gdy jedno jest już w toku, i zastosuje lokalny okres karencji przed ponowieniem po restarcie. -Nieudane próby wysłania żądania są domyślnie ponawiane szybciej niż udane utworzenie żądania. +Gdy `encryption: true`, Matrix domyślnie ustawia `startupVerification` na `"if-unverified"`. +Przy uruchamianiu, jeśli to urządzenie nadal nie jest zweryfikowane, Matrix wyśle żądanie samoweryfikacji w innym kliencie Matrix, +pominie duplikaty żądań, gdy jedno jest już oczekujące, i zastosuje lokalny cooldown przed ponowną próbą po restartach. +Domyślnie nieudane próby żądania są ponawiane szybciej niż skuteczne utworzenie żądania. Ustaw `startupVerification: "off"`, aby wyłączyć automatyczne żądania przy uruchamianiu, lub dostosuj `startupVerificationCooldownHours`, -jeśli chcesz krótsze albo dłuższe okno ponawiania. +jeśli chcesz krótsze lub dłuższe okno ponawiania. -Uruchamianie wykonuje też automatycznie ostrożny przebieg bootstrapu kryptograficznego. -Ten przebieg najpierw próbuje ponownie użyć bieżącego magazynu sekretów i tożsamości cross-signing oraz unika resetowania cross-signing, chyba że uruchomisz jawny przepływ naprawczy bootstrapu. +Przy uruchamianiu automatycznie wykonywany jest także konserwatywny przebieg bootstrap kryptografii. +Ten przebieg najpierw próbuje ponownie użyć bieżącego secret storage i tożsamości cross-signing oraz unika resetowania cross-signing, chyba że uruchomisz jawny przepływ naprawy bootstrap. -Jeśli podczas uruchamiania zostanie wykryty uszkodzony stan bootstrapu i skonfigurowano `channels.matrix.password`, OpenClaw może spróbować bardziej restrykcyjnej ścieżki naprawczej. +Jeśli przy uruchamianiu zostanie wykryty uszkodzony stan bootstrap i skonfigurowano `channels.matrix.password`, OpenClaw może spróbować bardziej rygorystycznej ścieżki naprawy. Jeśli bieżące urządzenie jest już podpisane przez właściciela, OpenClaw zachowuje tę tożsamość zamiast resetować ją automatycznie. -Uaktualnianie z poprzedniej publicznej wtyczki Matrix: +Zobacz [Migracja Matrix](/pl/install/migrating-matrix), aby poznać pełny przebieg aktualizacji, ograniczenia, polecenia odzyskiwania i typowe komunikaty migracyjne. -- OpenClaw automatycznie ponownie używa tego samego konta Matrix, tokena dostępu i tożsamości urządzenia, gdy to możliwe. -- Zanim zostaną uruchomione jakiekolwiek istotne zmiany migracyjne Matrix, OpenClaw tworzy lub ponownie używa migawki odzyskiwania w `~/Backups/openclaw-migrations/`. -- Jeśli używasz wielu kont Matrix, ustaw `channels.matrix.defaultAccount` przed aktualizacją ze starego płaskiego układu store, aby OpenClaw wiedział, które konto ma otrzymać ten współdzielony stan legacy. -- Jeśli poprzednia wtyczka przechowywała lokalnie klucz deszyfrujący kopii zapasowej kluczy pokojów Matrix, uruchamianie lub `openclaw doctor --fix` automatycznie zaimportuje go do nowego przepływu klucza odzyskiwania. -- Jeśli token dostępu Matrix zmienił się po przygotowaniu migracji, uruchamianie teraz skanuje sąsiednie katalogi główne przechowywania według skrótu tokena w poszukiwaniu oczekującego stanu przywracania legacy, zanim zrezygnuje z automatycznego przywracania kopii zapasowej. -- Jeśli token dostępu Matrix zmieni się później dla tego samego konta, homeservera i użytkownika, OpenClaw woli teraz ponownie użyć najbardziej kompletnego istniejącego katalogu głównego według skrótu tokena zamiast rozpoczynać od pustego katalogu stanu Matrix. -- Przy następnym uruchomieniu gatewaya klucze pokojów z kopii zapasowej zostaną automatycznie przywrócone do nowego store kryptograficznego. -- Jeśli stara wtyczka miała lokalne klucze pokojów, których nigdy nie zarchiwizowano, OpenClaw wyświetli wyraźne ostrzeżenie. Tych kluczy nie można automatycznie wyeksportować z poprzedniego rust crypto store, więc część starej zaszyfrowanej historii może pozostać niedostępna, dopóki nie zostanie odzyskana ręcznie. -- Zobacz [Migracja Matrix](/pl/install/migrating-matrix), aby poznać pełny przepływ aktualizacji, ograniczenia, polecenia odzyskiwania i typowe komunikaty migracyjne. +### Komunikaty weryfikacji -Stan zaszyfrowanego runtime jest zorganizowany pod katalogami głównymi per konto, per użytkownik, według skrótu tokena w +Matrix publikuje komunikaty dotyczące cyklu życia weryfikacji bezpośrednio w ścisłym pokoju wiadomości prywatnych do weryfikacji jako wiadomości `m.notice`. +Obejmuje to: + +- komunikaty żądania weryfikacji +- komunikaty gotowości weryfikacji (z jawną wskazówką „Zweryfikuj przez emoji”) +- komunikaty rozpoczęcia i zakończenia weryfikacji +- szczegóły SAS (emoji i liczby), gdy są dostępne + +Przychodzące żądania weryfikacji z innego klienta Matrix są śledzone i automatycznie akceptowane przez OpenClaw. +W przypadku przepływów samoweryfikacji OpenClaw automatycznie uruchamia także przepływ SAS, gdy weryfikacja emoji staje się dostępna, i potwierdza swoją własną stronę. +W przypadku żądań weryfikacji z innego użytkownika/urządzenia Matrix OpenClaw automatycznie akceptuje żądanie, a następnie czeka, aż przepływ SAS będzie kontynuowany normalnie. +Aby zakończyć weryfikację, nadal musisz porównać emoji lub dziesiętny SAS w swoim kliencie Matrix i potwierdzić tam „Pasują”. + +OpenClaw nie akceptuje bezrefleksyjnie samoinicjowanych zduplikowanych przepływów. Przy uruchamianiu pomijane jest tworzenie nowego żądania, jeśli żądanie samoweryfikacji jest już oczekujące. + +Komunikaty protokołowe/systemowe weryfikacji nie są przekazywane do potoku czatu agenta, więc nie powodują `NO_REPLY`. + +### Higiena urządzeń + +Na koncie mogą gromadzić się stare urządzenia Matrix zarządzane przez OpenClaw, co utrudnia ocenę zaufania w szyfrowanych pokojach. +Wyświetl ich listę za pomocą: + +```bash +openclaw matrix devices list +``` + +Usuń nieaktualne urządzenia zarządzane przez OpenClaw za pomocą: + +```bash +openclaw matrix devices prune-stale +``` + +### Magazyn kryptograficzny + +Matrix E2EE używa oficjalnej ścieżki kryptograficznej Rust z `matrix-js-sdk` w Node, z `fake-indexeddb` jako shimem IndexedDB. Stan kryptograficzny jest utrwalany w pliku migawki (`crypto-idb-snapshot.json`) i przywracany podczas uruchamiania. Plik migawki to wrażliwy stan czasu działania przechowywany z restrykcyjnymi uprawnieniami plików. + +Zaszyfrowany stan czasu działania znajduje się w katalogach per konto i per hash tokena użytkownika w `~/.openclaw/matrix/accounts//__//`. -Ten katalog zawiera store synchronizacji (`bot-storage.json`), store kryptograficzny (`crypto/`), +Ten katalog zawiera magazyn synchronizacji (`bot-storage.json`), magazyn kryptograficzny (`crypto/`), plik klucza odzyskiwania (`recovery-key.json`), migawkę IndexedDB (`crypto-idb-snapshot.json`), -powiązania wątków (`thread-bindings.json`) i stan weryfikacji przy uruchamianiu (`startup-verification.json`), -gdy te funkcje są używane. -Gdy token zmienia się, ale tożsamość konta pozostaje taka sama, OpenClaw ponownie używa najlepszego istniejącego -katalogu głównego dla krotki konto/homeserver/użytkownik, aby poprzedni stan synchronizacji, stan kryptograficzny, powiązania wątków -i stan weryfikacji przy uruchamianiu pozostały widoczne. - -### Model Node crypto store - -Matrix E2EE w tej wtyczce używa oficjalnej ścieżki Rust crypto `matrix-js-sdk` w Node. -Ta ścieżka oczekuje trwałości opartej na IndexedDB, jeśli chcesz, aby stan kryptograficzny przetrwał restarty. - -OpenClaw obecnie zapewnia to w Node przez: - -- używanie `fake-indexeddb` jako shimu API IndexedDB oczekiwanego przez SDK -- przywracanie zawartości IndexedDB Rust crypto z `crypto-idb-snapshot.json` przed `initRustCrypto` -- utrwalanie zaktualizowanej zawartości IndexedDB z powrotem do `crypto-idb-snapshot.json` po inicjalizacji i podczas runtime -- serializowanie przywracania i utrwalania migawki względem `crypto-idb-snapshot.json` za pomocą doradczego blokowania pliku, aby utrwalanie runtime gatewaya i konserwacja CLI nie ścigały się o ten sam plik migawki - -To warstwa zgodności/przechowywania, a nie niestandardowa implementacja kryptografii. -Plik migawki jest wrażliwym stanem runtime i jest przechowywany z restrykcyjnymi uprawnieniami do pliku. -W modelu bezpieczeństwa OpenClaw host gatewaya i lokalny katalog stanu OpenClaw już znajdują się wewnątrz granicy zaufanego operatora, więc jest to przede wszystkim kwestia operacyjnej trwałości, a nie osobna zdalna granica zaufania. - -Planowane ulepszenie: - -- dodać obsługę SecretRef dla trwałego materiału kluczy Matrix, aby klucze odzyskiwania i powiązane sekrety szyfrowania store mogły pochodzić od dostawców sekretów OpenClaw zamiast wyłącznie z plików lokalnych +powiązania wątków (`thread-bindings.json`) oraz stan weryfikacji przy uruchamianiu (`startup-verification.json`). +Gdy token się zmienia, ale tożsamość konta pozostaje taka sama, OpenClaw ponownie używa najlepszego istniejącego +katalogu głównego dla tej krotki konto/homeserver/użytkownik, dzięki czemu wcześniejszy stan synchronizacji, stan kryptograficzny, powiązania wątków +i stan weryfikacji przy uruchamianiu pozostają dostępne. ## Zarządzanie profilem @@ -682,94 +681,38 @@ openclaw matrix profile set --name "OpenClaw Assistant" openclaw matrix profile set --avatar-url https://cdn.example.org/avatar.png ``` -Dodaj `--account `, gdy chcesz jawnie wskazać nazwane konto Matrix. +Dodaj `--account `, jeśli chcesz jawnie wskazać nazwane konto Matrix. -Matrix bezpośrednio akceptuje adresy URL awatarów `mxc://`. Gdy przekażesz adres URL awatara `http://` lub `https://`, OpenClaw najpierw prześle go do Matrix i zapisze rozwiązany adres URL `mxc://` z powrotem do `channels.matrix.avatarUrl` (lub nadpisania wybranego konta). - -## Automatyczne powiadomienia o weryfikacji - -Matrix publikuje teraz powiadomienia o cyklu życia weryfikacji bezpośrednio w ścisłym pokoju wiadomości prywatnych do weryfikacji jako wiadomości `m.notice`. -Obejmuje to: - -- powiadomienia o żądaniu weryfikacji -- powiadomienia o gotowości do weryfikacji (z jawną wskazówką „Zweryfikuj przez emoji”) -- powiadomienia o rozpoczęciu i zakończeniu weryfikacji -- szczegóły SAS (emoji i liczby dziesiętne), gdy są dostępne - -Przychodzące żądania weryfikacji z innego klienta Matrix są śledzone i automatycznie akceptowane przez OpenClaw. -W przepływach samoweryfikacji OpenClaw także automatycznie rozpoczyna przepływ SAS, gdy weryfikacja emoji staje się dostępna, i potwierdza swoją stronę. -W przypadku żądań weryfikacji od innego użytkownika/urządzenia Matrix OpenClaw automatycznie akceptuje żądanie, a następnie czeka, aż przepływ SAS przebiegnie normalnie. -Aby zakończyć weryfikację, nadal musisz porównać emoji lub dziesiętny SAS w swoim kliencie Matrix i potwierdzić tam „Pasują”. - -OpenClaw nie akceptuje bezrefleksyjnie samodzielnie zainicjowanych zduplikowanych przepływów. Podczas uruchamiania pomija tworzenie nowego żądania, jeśli żądanie samoweryfikacji jest już oczekujące. - -Powiadomienia protokołu/systemu weryfikacji nie są przekazywane do potoku czatu agenta, więc nie powodują `NO_REPLY`. - -### Higiena urządzeń - -Na koncie mogą gromadzić się stare urządzenia Matrix zarządzane przez OpenClaw, co utrudnia interpretację zaufania w zaszyfrowanych pokojach. -Wyświetl ich listę poleceniem: - -```bash -openclaw matrix devices list -``` - -Usuń nieaktualne urządzenia Matrix zarządzane przez OpenClaw poleceniem: - -```bash -openclaw matrix devices prune-stale -``` - -### Naprawa pokoju bezpośredniego - -Jeśli stan wiadomości prywatnych się rozjedzie, OpenClaw może skończyć ze starymi mapowaniami `m.direct`, które wskazują na dawne pokoje solo zamiast aktywnej wiadomości prywatnej. Sprawdź bieżące mapowanie dla partnera za pomocą: - -```bash -openclaw matrix direct inspect --user-id @alice:example.org -``` - -Napraw je poleceniem: - -```bash -openclaw matrix direct repair --user-id @alice:example.org -``` - -Naprawa zachowuje logikę specyficzną dla Matrix wewnątrz wtyczki: - -- preferuje ścisłą wiadomość prywatną 1:1, która jest już zmapowana w `m.direct` -- w przeciwnym razie przechodzi do dowolnej aktualnie dołączonej ścisłej wiadomości prywatnej 1:1 z tym użytkownikiem -- jeśli nie istnieje zdrowa wiadomość prywatna, tworzy nowy pokój bezpośredni i przepisuje `m.direct`, aby wskazywało na niego - -Przepływ naprawy nie usuwa automatycznie starych pokojów. Wybiera tylko zdrową wiadomość prywatną i aktualizuje mapowanie, tak aby nowe wysyłki Matrix, powiadomienia o weryfikacji i inne przepływy wiadomości bezpośrednich znów trafiały do właściwego pokoju. +Matrix akceptuje bezpośrednio URL-e awatarów `mxc://`. Gdy przekażesz URL awatara `http://` lub `https://`, OpenClaw najpierw prześle go do Matrix i zapisze rozwiązany URL `mxc://` z powrotem w `channels.matrix.avatarUrl` (lub w nadpisaniu dla wybranego konta). ## Wątki -Matrix obsługuje natywne wątki Matrix zarówno dla odpowiedzi automatycznych, jak i wysyłek narzędzia wiadomości. +Matrix obsługuje natywne wątki Matrix zarówno dla odpowiedzi automatycznych, jak i wysyłek przez narzędzie wiadomości. -- `dm.sessionScope: "per-user"` (domyślnie) utrzymuje routowanie wiadomości prywatnych Matrix w zakresie nadawcy, dzięki czemu wiele pokojów wiadomości prywatnych może współdzielić jedną sesję, jeśli rozwiążą się do tego samego partnera. -- `dm.sessionScope: "per-room"` izoluje każdy pokój wiadomości prywatnych Matrix we własnym kluczu sesji, nadal używając zwykłych kontroli uwierzytelniania i list dozwolonych dla wiadomości prywatnych. -- Jawne powiązania konwersacji Matrix nadal mają pierwszeństwo przed `dm.sessionScope`, więc powiązane pokoje i wątki zachowują wybrany docelowy identyfikator sesji. -- `threadReplies: "off"` utrzymuje odpowiedzi na poziomie głównym i zachowuje przychodzące wiadomości wątkowane na sesji nadrzędnej. -- `threadReplies: "inbound"` odpowiada wewnątrz wątku tylko wtedy, gdy wiadomość przychodząca była już w tym wątku. -- `threadReplies: "always"` utrzymuje odpowiedzi pokojów we wątku zakorzenionym w wiadomości wyzwalającej i prowadzi tę konwersację przez odpowiadającą jej sesję o zakresie wątku od pierwszej wiadomości wyzwalającej. -- `dm.threadReplies` nadpisuje ustawienie najwyższego poziomu tylko dla wiadomości prywatnych. Na przykład możesz izolować wątki w pokojach, a jednocześnie zachować płaskie wiadomości prywatne. -- Przychodzące wiadomości wątkowane zawierają wiadomość główną wątku jako dodatkowy kontekst agenta. -- Wysyłki narzędzia wiadomości teraz automatycznie dziedziczą bieżący wątek Matrix, gdy celem jest ten sam pokój lub ten sam użytkownik docelowy wiadomości prywatnej, chyba że jawnie podano `threadId`. -- Ponowne użycie celu użytkownika wiadomości prywatnej dla tej samej sesji działa tylko wtedy, gdy bieżące metadane sesji potwierdzają tego samego partnera wiadomości prywatnej na tym samym koncie Matrix; w przeciwnym razie OpenClaw wraca do normalnego routowania w zakresie użytkownika. -- Gdy OpenClaw zauważy, że pokój wiadomości prywatnych Matrix koliduje z innym pokojem wiadomości prywatnych w tej samej współdzielonej sesji Matrix DM, publikuje w tym pokoju jednorazowe `m.notice` z furtką awaryjną `/focus`, gdy powiązania wątków są włączone, oraz wskazówką `dm.sessionScope`. -- Powiązania wątków w runtime są obsługiwane dla Matrix. `/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age` i powiązane z wątkiem `/acp spawn` działają teraz w pokojach i wiadomościach prywatnych Matrix. -- Główne `/focus` w pokoju/wiadomości prywatnej Matrix tworzy nowy wątek Matrix i wiąże go z docelową sesją, gdy `threadBindings.spawnSubagentSessions=true`. +- `dm.sessionScope: "per-user"` (domyślnie) utrzymuje routowanie wiadomości prywatnych Matrix w zakresie nadawcy, dzięki czemu wiele pokoi wiadomości prywatnych może współdzielić jedną sesję, gdy odnoszą się do tego samego peer. +- `dm.sessionScope: "per-room"` izoluje każdy pokój wiadomości prywatnych Matrix do własnego klucza sesji, nadal używając zwykłego uwierzytelniania wiadomości prywatnych i kontroli allowlist. +- Jawne powiązania konwersacji Matrix nadal mają pierwszeństwo przed `dm.sessionScope`, więc powiązane pokoje i wątki zachowują wybraną sesję docelową. +- `threadReplies: "off"` utrzymuje odpowiedzi na poziomie głównym i zachowuje przychodzące wiadomości z wątku w sesji nadrzędnej. +- `threadReplies: "inbound"` odpowiada w wątku tylko wtedy, gdy przychodząca wiadomość była już w tym wątku. +- `threadReplies: "always"` utrzymuje odpowiedzi w pokojach w wątku zakorzenionym w wiadomości wyzwalającej i kieruje tę konwersację przez odpowiadającą jej sesję w zakresie wątku od pierwszej wiadomości wyzwalającej. +- `dm.threadReplies` nadpisuje ustawienie najwyższego poziomu tylko dla wiadomości prywatnych. Na przykład możesz utrzymać izolację wątków w pokojach, zachowując płaskie wiadomości prywatne. +- Przychodzące wiadomości z wątków zawierają główną wiadomość wątku jako dodatkowy kontekst agenta. +- Wysyłki przez narzędzie wiadomości automatycznie dziedziczą bieżący wątek Matrix, gdy celem jest ten sam pokój albo ten sam docelowy użytkownik wiadomości prywatnej, chyba że podano jawne `threadId`. +- Ponowne użycie celu tego samego użytkownika wiadomości prywatnej w tej samej sesji uruchamia się tylko wtedy, gdy bieżące metadane sesji potwierdzają tego samego peera wiadomości prywatnej na tym samym koncie Matrix; w przeciwnym razie OpenClaw wraca do zwykłego routowania w zakresie użytkownika. +- Gdy OpenClaw wykryje kolizję pokoju wiadomości prywatnych Matrix z innym pokojem wiadomości prywatnych w tej samej współdzielonej sesji wiadomości prywatnych Matrix, publikuje jednorazowe `m.notice` w tym pokoju z mechanizmem awaryjnym `/focus`, gdy powiązania wątków są włączone, oraz z podpowiedzią `dm.sessionScope`. +- Powiązania wątków w czasie działania są obsługiwane dla Matrix. `/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age` i powiązane z wątkiem `/acp spawn` działają w pokojach Matrix i wiadomościach prywatnych. +- Najwyższego poziomu `/focus` w pokoju/DM Matrix tworzy nowy wątek Matrix i wiąże go z sesją docelową, gdy `threadBindings.spawnSubagentSessions=true`. - Uruchomienie `/focus` lub `/acp spawn --thread here` wewnątrz istniejącego wątku Matrix wiąże zamiast tego bieżący wątek. ## Powiązania konwersacji ACP -Pokoje Matrix, wiadomości prywatne i istniejące wątki Matrix można przekształcić w trwałe przestrzenie robocze ACP bez zmiany powierzchni czatu. +Pokoje Matrix, wiadomości prywatne i istniejące wątki Matrix mogą zostać przekształcone w trwałe przestrzenie robocze ACP bez zmiany powierzchni czatu. Szybki przepływ dla operatora: -- Uruchom `/acp spawn codex --bind here` wewnątrz wiadomości prywatnej, pokoju lub istniejącego wątku Matrix, którego chcesz nadal używać. -- W głównej wiadomości prywatnej lub pokoju Matrix bieżąca wiadomość prywatna/pokój pozostaje powierzchnią czatu, a przyszłe wiadomości są kierowane do uruchomionej sesji ACP. -- W istniejącym wątku Matrix `--bind here` wiąże ten bieżący wątek na miejscu. +- Uruchom `/acp spawn codex --bind here` wewnątrz wiadomości prywatnej Matrix, pokoju lub istniejącego wątku, którego chcesz nadal używać. +- W wiadomości prywatnej Matrix lub pokoju najwyższego poziomu bieżąca wiadomość prywatna/pokój pozostaje powierzchnią czatu, a przyszłe wiadomości są kierowane do utworzonej sesji ACP. +- W istniejącym wątku Matrix `--bind here` wiąże bieżący wątek na miejscu. - `/new` i `/reset` resetują tę samą powiązaną sesję ACP na miejscu. - `/acp close` zamyka sesję ACP i usuwa powiązanie. @@ -780,7 +723,7 @@ Uwagi: ### Konfiguracja powiązań wątków -Matrix dziedziczy globalne wartości domyślne z `session.threadBindings`, a także obsługuje nadpisania per kanał: +Matrix dziedziczy globalne ustawienia domyślne z `session.threadBindings`, a także obsługuje nadpisania per kanał: - `threadBindings.enabled` - `threadBindings.idleHours` @@ -788,67 +731,66 @@ Matrix dziedziczy globalne wartości domyślne z `session.threadBindings`, a tak - `threadBindings.spawnSubagentSessions` - `threadBindings.spawnAcpSessions` -Flagi uruchamiania powiązanego z wątkiem Matrix są opcjonalne: +Flagi uruchamiania powiązane z wątkami Matrix są opt-in: -- Ustaw `threadBindings.spawnSubagentSessions: true`, aby pozwolić głównemu `/focus` tworzyć i wiązać nowe wątki Matrix. +- Ustaw `threadBindings.spawnSubagentSessions: true`, aby pozwolić najwyższemu poziomowi `/focus` tworzyć i wiązać nowe wątki Matrix. - Ustaw `threadBindings.spawnAcpSessions: true`, aby pozwolić `/acp spawn --thread auto|here` wiązać sesje ACP z wątkami Matrix. ## Reakcje -Matrix obsługuje wychodzące działania reakcji, przychodzące powiadomienia o reakcjach i przychodzące reakcje potwierdzające. +Matrix obsługuje wychodzące akcje reakcji, przychodzące powiadomienia o reakcjach oraz przychodzące reakcje potwierdzeń. -- Narzędzia wychodzących reakcji są kontrolowane przez `channels["matrix"].actions.reactions`. +- Funkcje reakcji wychodzących są kontrolowane przez `channels["matrix"].actions.reactions`. - `react` dodaje reakcję do konkretnego zdarzenia Matrix. - `reactions` wyświetla bieżące podsumowanie reakcji dla konkretnego zdarzenia Matrix. - `emoji=""` usuwa własne reakcje konta bota na tym zdarzeniu. -- `remove: true` usuwa z konta bota tylko wskazaną reakcję emoji. +- `remove: true` usuwa tylko wskazaną reakcję emoji z konta bota. -Zakres reakcji potwierdzających jest rozwiązywany w standardowej kolejności OpenClaw: +Zakres wyszukiwania reakcji potwierdzeń jest rozstrzygany według standardowej kolejności OpenClaw: - `channels["matrix"].accounts..ackReaction` - `channels["matrix"].ackReaction` - `messages.ackReaction` -- zapasowe emoji tożsamości agenta +- fallback do emoji tożsamości agenta -Zakres reakcji potwierdzających jest rozwiązywany w tej kolejności: +Zakres reakcji potwierdzeń jest rozstrzygany w tej kolejności: - `channels["matrix"].accounts..ackReactionScope` - `channels["matrix"].ackReactionScope` - `messages.ackReactionScope` -Tryb powiadomień o reakcjach jest rozwiązywany w tej kolejności: +Tryb powiadomień o reakcjach jest rozstrzygany w tej kolejności: - `channels["matrix"].accounts..reactionNotifications` - `channels["matrix"].reactionNotifications` - domyślnie: `own` -Bieżące zachowanie: +Zachowanie: -- `reactionNotifications: "own"` przekazuje dodane zdarzenia `m.reaction`, gdy są skierowane do wiadomości Matrix napisanych przez bota. +- `reactionNotifications: "own"` przekazuje dodane zdarzenia `m.reaction`, gdy odnoszą się do wiadomości Matrix napisanych przez bota. - `reactionNotifications: "off"` wyłącza systemowe zdarzenia reakcji. -- Usunięcia reakcji nadal nie są syntetyzowane do zdarzeń systemowych, ponieważ Matrix udostępnia je jako redakcje, a nie jako samodzielne usunięcia `m.reaction`. +- Usunięcia reakcji nie są syntetyzowane do zdarzeń systemowych, ponieważ Matrix pokazuje je jako redakcje, a nie jako samodzielne usunięcia `m.reaction`. ## Kontekst historii -- `channels.matrix.historyLimit` kontroluje liczbę ostatnich wiadomości z pokoju dołączanych jako `InboundHistory`, gdy wiadomość z pokoju Matrix wyzwala agenta. -- Wartość zapasowa pochodzi z `messages.groupChat.historyLimit`. Jeśli obie wartości nie są ustawione, efektywna wartość domyślna to `0`, więc wiadomości z pokoju wymagające wzmianki nie są buforowane. Ustaw `0`, aby wyłączyć. +- `channels.matrix.historyLimit` kontroluje, ile ostatnich wiadomości z pokoju jest dołączanych jako `InboundHistory`, gdy wiadomość z pokoju Matrix wyzwala agenta. Przechodzi na `messages.groupChat.historyLimit`; jeśli oba są nieustawione, efektywna wartość domyślna to `0`. Ustaw `0`, aby wyłączyć. - Historia pokoju Matrix dotyczy tylko pokoju. Wiadomości prywatne nadal używają zwykłej historii sesji. -- Historia pokoju Matrix obejmuje tylko stan oczekujący: OpenClaw buforuje wiadomości z pokoju, które nie wywołały jeszcze odpowiedzi, a następnie robi migawkę tego okna, gdy nadejdzie wzmianka lub inny wyzwalacz. -- Bieżąca wiadomość wyzwalająca nie jest dołączana do `InboundHistory`; pozostaje w głównej treści przychodzącej tej tury. -- Ponowienia dla tego samego zdarzenia Matrix używają pierwotnej migawki historii zamiast przesuwać się do przodu do nowszych wiadomości z pokoju. +- Historia pokoju Matrix jest tylko dla oczekujących: OpenClaw buforuje wiadomości z pokoju, które jeszcze nie wywołały odpowiedzi, a następnie zapisuje migawkę tego okna, gdy nadejdzie wzmianka lub inny trigger. +- Bieżąca wiadomość wyzwalająca nie jest uwzględniona w `InboundHistory`; pozostaje w głównej treści przychodzącej tej tury. +- Ponowienia tego samego zdarzenia Matrix używają ponownie oryginalnej migawki historii zamiast przesuwać się do przodu wraz z nowszymi wiadomościami pokoju. ## Widoczność kontekstu -Matrix obsługuje wspólną kontrolę `contextVisibility` dla uzupełniającego kontekstu pokoju, takiego jak pobrany tekst odpowiedzi, korzenie wątków i oczekująca historia. +Matrix obsługuje współdzieloną kontrolę `contextVisibility` dla dodatkowego kontekstu pokoju, takiego jak pobrany tekst odpowiedzi, korzenie wątków i oczekująca historia. -- `contextVisibility: "all"` to ustawienie domyślne. Uzupełniający kontekst jest zachowywany w otrzymanej postaci. -- `contextVisibility: "allowlist"` filtruje uzupełniający kontekst do nadawców dozwolonych przez aktywne sprawdzanie list dozwolonych pokoju/użytkownika. +- `contextVisibility: "all"` to wartość domyślna. Dodatkowy kontekst jest zachowywany bez zmian. +- `contextVisibility: "allowlist"` filtruje dodatkowy kontekst do nadawców dozwolonych przez aktywne sprawdzenia allowlist pokoju/użytkownika. - `contextVisibility: "allowlist_quote"` działa jak `allowlist`, ale nadal zachowuje jedną jawną cytowaną odpowiedź. -To ustawienie wpływa na widoczność kontekstu uzupełniającego, a nie na to, czy sama wiadomość przychodząca może wywołać odpowiedź. -Autoryzacja wyzwolenia nadal pochodzi z ustawień `groupPolicy`, `groups`, `groupAllowFrom` i zasad wiadomości prywatnych. +To ustawienie wpływa na widoczność dodatkowego kontekstu, a nie na to, czy sama wiadomość przychodząca może wywołać odpowiedź. +Autoryzacja triggera nadal wynika z ustawień `groupPolicy`, `groups`, `groupAllowFrom` i zasad wiadomości prywatnych. -## Przykład zasad wiadomości prywatnych i pokojów +## Zasady wiadomości prywatnych i pokoi ```json5 { @@ -871,7 +813,7 @@ Autoryzacja wyzwolenia nadal pochodzi z ustawień `groupPolicy`, `groups`, `grou } ``` -Zobacz [Grupy](/pl/channels/groups), aby dowiedzieć się więcej o wymuszaniu wzmianki i zachowaniu listy dozwolonych. +Zobacz [Grupy](/pl/channels/groups), aby poznać zachowanie związane z wymaganiem wzmianki i allowlistą. Przykład parowania dla wiadomości prywatnych Matrix: @@ -880,47 +822,67 @@ openclaw pairing list matrix openclaw pairing approve matrix ``` -Jeśli niezatwierdzony użytkownik Matrix nadal wysyła wiadomości przed zatwierdzeniem, OpenClaw ponownie użyje tego samego oczekującego kodu parowania i może po krótkim czasie odnowienia ponownie wysłać przypomnienie zamiast generować nowy kod. +Jeśli niezatwierdzony użytkownik Matrix wciąż wysyła Ci wiadomości przed zatwierdzeniem, OpenClaw ponownie używa tego samego oczekującego kodu parowania i może po krótkim cooldownie ponownie wysłać odpowiedź-przypomnienie zamiast generować nowy kod. -Zobacz [Parowanie](/pl/channels/pairing), aby poznać wspólny przepływ parowania wiadomości prywatnych i układ przechowywania. +Zobacz [Parowanie](/pl/channels/pairing), aby poznać współdzielony przepływ parowania wiadomości prywatnych i układ przechowywania. + +## Naprawa bezpośredniego pokoju + +Jeśli stan wiadomości bezpośrednich przestanie być zsynchronizowany, OpenClaw może skończyć ze starymi mapowaniami `m.direct`, które wskazują na stare pokoje solo zamiast na aktywną wiadomość prywatną. Sprawdź bieżące mapowanie dla peera za pomocą: + +```bash +openclaw matrix direct inspect --user-id @alice:example.org +``` + +Napraw je za pomocą: + +```bash +openclaw matrix direct repair --user-id @alice:example.org +``` + +Przepływ naprawy: + +- preferuje ścisłą wiadomość prywatną 1:1, która jest już zmapowana w `m.direct` +- w przeciwnym razie przechodzi do dowolnej aktualnie dołączonej ścisłej wiadomości prywatnej 1:1 z tym użytkownikiem +- tworzy nowy pokój direct i przepisuje `m.direct`, jeśli nie istnieje żaden zdrowy DM + +Przepływ naprawy nie usuwa automatycznie starych pokoi. Wybiera tylko zdrową wiadomość prywatną i aktualizuje mapowanie, aby nowe wysyłki Matrix, komunikaty weryfikacyjne i inne przepływy wiadomości bezpośrednich znów trafiały do właściwego pokoju. ## Zatwierdzenia exec Matrix może działać jako natywny klient zatwierdzeń dla konta Matrix. Natywne -przełączniki routowania wiadomości prywatnych/kanałów nadal znajdują się w konfiguracji zatwierdzeń exec: +przełączniki routingu wiadomości prywatnych/kanałów nadal znajdują się w konfiguracji zatwierdzeń exec: - `channels.matrix.execApprovals.enabled` -- `channels.matrix.execApprovals.approvers` (opcjonalne; wartość zapasowa pochodzi z `channels.matrix.dm.allowFrom`) +- `channels.matrix.execApprovals.approvers` (opcjonalnie; fallback do `channels.matrix.dm.allowFrom`) - `channels.matrix.execApprovals.target` (`dm` | `channel` | `both`, domyślnie: `dm`) - `channels.matrix.execApprovals.agentFilter` - `channels.matrix.execApprovals.sessionFilter` -Zatwierdzający muszą być identyfikatorami użytkowników Matrix, takimi jak `@owner:example.org`. Matrix automatycznie włącza natywne zatwierdzenia, gdy `enabled` nie jest ustawione lub ma wartość `"auto"` i można rozwiązać co najmniej jednego zatwierdzającego. Zatwierdzenia exec najpierw używają `execApprovals.approvers` i mogą wracać do `channels.matrix.dm.allowFrom`. Zatwierdzenia wtyczek autoryzują przez `channels.matrix.dm.allowFrom`. Ustaw `enabled: false`, aby jawnie wyłączyć Matrix jako natywnego klienta zatwierdzeń. W przeciwnym razie żądania zatwierdzenia wracają do innych skonfigurowanych tras zatwierdzeń lub do zapasowej polityki zatwierdzeń. +Zatwierdzający muszą być identyfikatorami użytkowników Matrix, takimi jak `@owner:example.org`. Matrix automatycznie włącza natywne zatwierdzenia, gdy `enabled` jest nieustawione lub ma wartość `"auto"` i można rozwiązać co najmniej jednego zatwierdzającego. Zatwierdzenia exec używają najpierw `execApprovals.approvers` i mogą przejść do `channels.matrix.dm.allowFrom`. Zatwierdzenia wtyczek autoryzują przez `channels.matrix.dm.allowFrom`. Ustaw `enabled: false`, aby jawnie wyłączyć Matrix jako natywnego klienta zatwierdzeń. W przeciwnym razie żądania zatwierdzeń wracają do innych skonfigurowanych tras zatwierdzeń lub do polityki fallback zatwierdzeń. -Natywne routowanie Matrix obsługuje teraz oba rodzaje zatwierdzeń: +Natywne routowanie Matrix obsługuje oba typy zatwierdzeń: -- `channels.matrix.execApprovals.*` kontroluje natywny tryb fanoutu wiadomości prywatnych/kanałów dla promptów zatwierdzeń Matrix. +- `channels.matrix.execApprovals.*` kontroluje natywny tryb rozsyłania do wiadomości prywatnych/kanałów dla promptów zatwierdzeń Matrix. - Zatwierdzenia exec używają zbioru zatwierdzających exec z `execApprovals.approvers` lub `channels.matrix.dm.allowFrom`. -- Zatwierdzenia wtyczek używają listy dozwolonych wiadomości prywatnych Matrix z `channels.matrix.dm.allowFrom`. -- Skróty reakcji Matrix i aktualizacje wiadomości dotyczą zarówno zatwierdzeń exec, jak i zatwierdzeń wtyczek. +- Zatwierdzenia wtyczek używają allowlist wiadomości prywatnych Matrix z `channels.matrix.dm.allowFrom`. +- Skróty reakcji Matrix i aktualizacje wiadomości mają zastosowanie zarówno do zatwierdzeń exec, jak i zatwierdzeń wtyczek. Zasady dostarczania: - `target: "dm"` wysyła prompty zatwierdzeń do wiadomości prywatnych zatwierdzających -- `target: "channel"` wysyła prompt z powrotem do źródłowego pokoju lub wiadomości prywatnej Matrix -- `target: "both"` wysyła do wiadomości prywatnych zatwierdzających oraz do źródłowego pokoju lub wiadomości prywatnej Matrix +- `target: "channel"` wysyła prompt z powrotem do źródłowego pokoju Matrix lub wiadomości prywatnej +- `target: "both"` wysyła do wiadomości prywatnych zatwierdzających oraz do źródłowego pokoju Matrix lub wiadomości prywatnej Prompty zatwierdzeń Matrix inicjalizują skróty reakcji na głównej wiadomości zatwierdzenia: -- `✅` = zezwól jednorazowo -- `❌` = odmów +- `✅` = zezwól raz +- `❌` = odrzuć - `♾️` = zezwól zawsze, gdy taka decyzja jest dozwolona przez efektywną politykę exec -Zatwierdzający mogą reagować na tę wiadomość albo użyć zapasowych poleceń ukośnikowych: `/approve allow-once`, `/approve allow-always` lub `/approve deny`. +Zatwierdzający mogą zareagować na tę wiadomość lub użyć zapasowych poleceń ukośnikowych: `/approve allow-once`, `/approve allow-always` albo `/approve deny`. -Tylko rozwiązani zatwierdzający mogą zatwierdzać lub odrzucać. Dla zatwierdzeń exec dostarczanie kanałowe zawiera tekst polecenia, więc włączaj `channel` lub `both` tylko w zaufanych pokojach. - -Prompty zatwierdzeń Matrix ponownie używają wspólnego rdzeniowego planera zatwierdzeń. Natywna powierzchnia specyficzna dla Matrix obsługuje routowanie pokój/wiadomość prywatna, reakcje i zachowanie wysyłania/aktualizacji/usuwania wiadomości zarówno dla zatwierdzeń exec, jak i zatwierdzeń wtyczek. +Tylko rozwiązani zatwierdzający mogą zatwierdzać lub odrzucać. W przypadku zatwierdzeń exec dostarczanie kanałowe zawiera tekst polecenia, więc włączaj `channel` lub `both` tylko w zaufanych pokojach. Nadpisanie per konto: @@ -928,7 +890,7 @@ Nadpisanie per konto: Powiązana dokumentacja: [Zatwierdzenia exec](/pl/tools/exec-approvals) -## Przykład wielu kont +## Wiele kont ```json5 { @@ -958,21 +920,23 @@ Powiązana dokumentacja: [Zatwierdzenia exec](/pl/tools/exec-approvals) } ``` -Wartości najwyższego poziomu `channels.matrix` działają jako wartości domyślne dla nazwanych kont, chyba że konto je nadpisze. -Możesz ograniczyć odziedziczone wpisy pokojów do jednego konta Matrix za pomocą `groups..account` (lub starszego `rooms..account`). -Wpisy bez `account` pozostają współdzielone przez wszystkie konta Matrix, a wpisy z `account: "default"` nadal działają, gdy konto domyślne jest skonfigurowane bezpośrednio na najwyższym poziomie `channels.matrix.*`. -Częściowe współdzielone wartości domyślne uwierzytelniania same z siebie nie tworzą osobnego niejawnego konta domyślnego. OpenClaw syntetyzuje najwyższego poziomu konto `default` tylko wtedy, gdy to konto domyślne ma świeże uwierzytelnianie (`homeserver` plus `accessToken` albo `homeserver` plus `userId` i `password`); nazwane konta mogą nadal pozostawać wykrywalne na podstawie `homeserver` plus `userId`, gdy zbuforowane poświadczenia później spełnią wymagania uwierzytelniania. -Jeśli Matrix ma już dokładnie jedno nazwane konto albo `defaultAccount` wskazuje istniejący klucz nazwanego konta, promocja naprawy/konfiguracji z jednego konta do wielu zachowuje to konto zamiast tworzyć nowy wpis `accounts.default`. Do tego promowanego konta przenoszone są tylko klucze uwierzytelniania/bootstrap Matrix; współdzielone klucze polityki dostarczania pozostają na najwyższym poziomie. -Ustaw `defaultAccount`, jeśli chcesz, aby OpenClaw preferował jedno nazwane konto Matrix do niejawnego routowania, sondowania i operacji CLI. -Jeśli skonfigurujesz wiele nazwanych kont, ustaw `defaultAccount` albo przekazuj `--account ` dla poleceń CLI zależnych od niejawnego wyboru konta. -Przekaż `--account ` do `openclaw matrix verify ...` i `openclaw matrix devices ...`, gdy chcesz nadpisać ten niejawny wybór dla pojedynczego polecenia. +Wartości najwyższego poziomu `channels.matrix` działają jako domyślne dla nazwanych kont, chyba że konto je nadpisze. +Możesz zawęzić dziedziczone wpisy pokoi do jednego konta Matrix za pomocą `groups..account`. +Wpisy bez `account` pozostają współdzielone między wszystkimi kontami Matrix, a wpisy z `account: "default"` nadal działają, gdy konto domyślne jest skonfigurowane bezpośrednio na najwyższym poziomie `channels.matrix.*`. +Częściowe współdzielone domyślne ustawienia uwierzytelniania same w sobie nie tworzą osobnego niejawnego konta domyślnego. OpenClaw syntetyzuje konto najwyższego poziomu `default` tylko wtedy, gdy to domyślne konto ma świeże uwierzytelnianie (`homeserver` plus `accessToken` lub `homeserver` plus `userId` i `password`); nazwane konta mogą nadal pozostawać wykrywalne z `homeserver` plus `userId`, gdy zbuforowane poświadczenia później spełnią wymagania uwierzytelniania. +Jeśli Matrix ma już dokładnie jedno nazwane konto albo `defaultAccount` wskazuje istniejący klucz nazwanego konta, promocja naprawy/konfiguracji z jednego konta do wielu zachowuje to konto zamiast tworzyć nowy wpis `accounts.default`. Tylko klucze uwierzytelniania/bootstrap Matrix są przenoszone do promowanego konta; współdzielone klucze polityki dostarczania pozostają na najwyższym poziomie. +Ustaw `defaultAccount`, jeśli chcesz, aby OpenClaw preferował jedno nazwane konto Matrix do niejawnego routingu, sondowania i operacji CLI. +Jeśli skonfigurujesz wiele nazwanych kont, ustaw `defaultAccount` lub przekazuj `--account ` dla poleceń CLI zależnych od niejawnego wyboru konta. +Przekaż `--account ` do `openclaw matrix verify ...` i `openclaw matrix devices ...`, jeśli chcesz nadpisać ten niejawny wybór dla jednego polecenia. + +Zobacz [Dokumentacja referencyjna konfiguracji](/pl/gateway/configuration-reference#multi-account-all-channels), aby poznać współdzielony wzorzec wielu kont. ## Prywatne/LAN homeservery -Domyślnie OpenClaw blokuje prywatne/wewnętrzne homeservery Matrix dla ochrony SSRF, chyba że -jawnie włączysz wyjątek per konto. +Domyślnie OpenClaw blokuje prywatne/wewnętrzne homeservery Matrix w celu ochrony przed SSRF, chyba że +jawnie włączysz je per konto. -Jeśli twój homeserver działa na localhost, adresie LAN/Tailscale albo wewnętrznej nazwie hosta, włącz +Jeśli Twój homeserver działa na localhost, adresie LAN/Tailscale albo wewnętrznej nazwie hosta, włącz `network.dangerouslyAllowPrivateNetwork` dla tego konta Matrix: ```json5 @@ -989,7 +953,7 @@ Jeśli twój homeserver działa na localhost, adresie LAN/Tailscale albo wewnęt } ``` -Przykład konfiguracji w CLI: +Przykład konfiguracji przez CLI: ```bash openclaw matrix account add \ @@ -999,12 +963,12 @@ openclaw matrix account add \ --access-token syt_ops_xxx ``` -Ten wyjątek pozwala tylko na zaufane cele prywatne/wewnętrzne. Publiczne homeservery bez TLS, takie jak -`http://matrix.example.org:8008`, nadal są blokowane. Gdy to możliwe, preferuj `https://`. +To ustawienie opt-in pozwala tylko na zaufane prywatne/wewnętrzne cele. Publiczne homeservery cleartext takie jak +`http://matrix.example.org:8008` pozostają blokowane. Gdy to możliwe, preferuj `https://`. -## Ruch Matrix przez proxy +## Proxy dla ruchu Matrix -Jeśli twoje wdrożenie Matrix wymaga jawnego wychodzącego proxy HTTP(S), ustaw `channels.matrix.proxy`: +Jeśli wdrożenie Matrix wymaga jawnego wychodzącego proxy HTTP(S), ustaw `channels.matrix.proxy`: ```json5 { @@ -1018,87 +982,86 @@ Jeśli twoje wdrożenie Matrix wymaga jawnego wychodzącego proxy HTTP(S), ustaw } ``` -Nazwane konta mogą nadpisać domyślną wartość najwyższego poziomu przez `channels.matrix.accounts..proxy`. -OpenClaw używa tego samego ustawienia proxy zarówno dla ruchu runtime Matrix, jak i sond stanu konta. +Nazwane konta mogą nadpisywać domyślne ustawienie najwyższego poziomu za pomocą `channels.matrix.accounts..proxy`. +OpenClaw używa tego samego ustawienia proxy zarówno dla ruchu Matrix w czasie działania, jak i dla sond stanu konta. ## Rozwiązywanie celów -Matrix akceptuje następujące formy celu wszędzie tam, gdzie OpenClaw prosi o cel pokoju lub użytkownika: +Matrix akceptuje następujące formy celu wszędzie tam, gdzie OpenClaw prosi o pokój lub cel użytkownika: - Użytkownicy: `@user:server`, `user:@user:server` lub `matrix:user:@user:server` - Pokoje: `!room:server`, `room:!room:server` lub `matrix:room:!room:server` - Aliasy: `#alias:server`, `channel:#alias:server` lub `matrix:channel:#alias:server` -Wyszukiwanie katalogu na żywo używa zalogowanego konta Matrix: +Wyszukiwanie w katalogu na żywo używa zalogowanego konta Matrix: -- Wyszukiwania użytkowników odpytyją katalog użytkowników Matrix na tym homeserverze. -- Wyszukiwania pokojów bezpośrednio akceptują jawne identyfikatory pokojów i aliasy, a następnie wracają do przeszukiwania nazw pokojów dołączonych dla tego konta. -- Wyszukiwanie nazw dołączonych pokojów jest realizowane najlepiej jak się da. Jeśli nazwy pokoju nie da się rozwiązać do identyfikatora ani aliasu, jest ignorowana przez runtime przy rozwiązywaniu listy dozwolonych. +- Wyszukiwanie użytkowników odpytuje katalog użytkowników Matrix na tym homeserverze. +- Wyszukiwanie pokoi akceptuje bezpośrednio jawne ID pokoi i aliasy, a następnie przechodzi do wyszukiwania nazw dołączonych pokoi dla tego konta. +- Wyszukiwanie nazw dołączonych pokoi jest best-effort. Jeśli nazwy pokoju nie da się rozwiązać do ID ani aliasu, jest ignorowana podczas rozwiązywania allowlist w czasie działania. -## Dokumentacja konfiguracji +## Dokumentacja referencyjna konfiguracji - `enabled`: włącza lub wyłącza kanał. - `name`: opcjonalna etykieta konta. -- `defaultAccount`: preferowany identyfikator konta, gdy skonfigurowano wiele kont Matrix. +- `defaultAccount`: preferowane ID konta, gdy skonfigurowano wiele kont Matrix. - `homeserver`: URL homeservera, na przykład `https://matrix.example.org`. -- `network.dangerouslyAllowPrivateNetwork`: pozwala temu kontu Matrix łączyć się z prywatnymi/wewnętrznymi homeserverami. Włącz tę opcję, gdy homeserver rozwiązuje się do `localhost`, adresu LAN/Tailscale albo wewnętrznego hosta, takiego jak `matrix-synapse`. -- `proxy`: opcjonalny URL proxy HTTP(S) dla ruchu Matrix. Nazwane konta mogą nadpisać domyślną wartość najwyższego poziomu własnym `proxy`. -- `userId`: pełny identyfikator użytkownika Matrix, na przykład `@bot:example.org`. -- `accessToken`: token dostępu dla uwierzytelniania opartego na tokenie. Dla `channels.matrix.accessToken` i `channels.matrix.accounts..accessToken` obsługiwane są zarówno wartości jawne, jak i SecretRef, w dostawcach env/file/exec. Zobacz [Zarządzanie sekretami](/pl/gateway/secrets). -- `password`: hasło do logowania hasłem. Obsługiwane są zarówno wartości jawne, jak i SecretRef. -- `deviceId`: jawny identyfikator urządzenia Matrix. -- `deviceName`: wyświetlana nazwa urządzenia przy logowaniu hasłem. -- `avatarUrl`: zapisany URL własnego awatara do synchronizacji profilu i aktualizacji `set-profile`. -- `initialSyncLimit`: limit zdarzeń synchronizacji przy uruchamianiu. +- `network.dangerouslyAllowPrivateNetwork`: pozwala temu kontu Matrix łączyć się z prywatnymi/wewnętrznymi homeserverami. Włącz to, gdy homeserver rozwiązuje się do `localhost`, adresu LAN/Tailscale albo wewnętrznego hosta, takiego jak `matrix-synapse`. +- `proxy`: opcjonalny URL proxy HTTP(S) dla ruchu Matrix. Nazwane konta mogą nadpisywać domyślne ustawienie najwyższego poziomu własnym `proxy`. +- `userId`: pełne ID użytkownika Matrix, na przykład `@bot:example.org`. +- `accessToken`: access token do uwierzytelniania opartego na tokenie. Zwykłe wartości tekstowe i wartości SecretRef są obsługiwane dla `channels.matrix.accessToken` i `channels.matrix.accounts..accessToken` w providerach env/file/exec. Zobacz [Zarządzanie sekretami](/pl/gateway/secrets). +- `password`: hasło do logowania opartego na haśle. Zwykłe wartości tekstowe i wartości SecretRef są obsługiwane. +- `deviceId`: jawne ID urządzenia Matrix. +- `deviceName`: nazwa wyświetlana urządzenia przy logowaniu hasłem. +- `avatarUrl`: zapisany URL własnego awatara do synchronizacji profilu i aktualizacji `profile set`. +- `initialSyncLimit`: maksymalna liczba zdarzeń pobieranych podczas synchronizacji przy uruchamianiu. - `encryption`: włącza E2EE. -- `allowlistOnly`: wymusza zachowanie tylko według listy dozwolonych dla wiadomości prywatnych i pokojów. -- `allowBots`: pozwala na wiadomości od innych skonfigurowanych kont Matrix OpenClaw (`true` lub `"mentions"`). -- `groupPolicy`: `open`, `allowlist` albo `disabled`. -- `contextVisibility`: tryb widoczności uzupełniającego kontekstu pokoju (`all`, `allowlist`, `allowlist_quote`). -- `groupAllowFrom`: lista dozwolonych identyfikatorów użytkowników dla ruchu w pokojach. -- Wpisy `groupAllowFrom` powinny być pełnymi identyfikatorami użytkowników Matrix. Nierozwiązane nazwy są ignorowane w runtime. -- `historyLimit`: maksymalna liczba wiadomości z pokoju do dołączenia jako kontekst historii grupy. Wartość zapasowa pochodzi z `messages.groupChat.historyLimit`; jeśli obie wartości nie są ustawione, efektywna wartość domyślna to `0`. Ustaw `0`, aby wyłączyć. -- `replyToMode`: `off`, `first`, `all` albo `batched`. +- `allowlistOnly`: gdy ma wartość `true`, podnosi otwartą politykę pokoju `open` do `allowlist` i wymusza `allowlist` dla wszystkich aktywnych zasad wiadomości prywatnych poza `disabled` (w tym `pairing` i `open`). Nie wpływa na zasady `disabled`. +- `allowBots`: pozwala na wiadomości z innych skonfigurowanych kont Matrix OpenClaw (`true` lub `"mentions"`). +- `groupPolicy`: `open`, `allowlist` lub `disabled`. +- `contextVisibility`: tryb widoczności dodatkowego kontekstu pokoju (`all`, `allowlist`, `allowlist_quote`). +- `groupAllowFrom`: allowlista ID użytkowników dla ruchu w pokojach. Wpisy powinny być pełnymi ID użytkowników Matrix; nierozwiązane nazwy są ignorowane w czasie działania. +- `historyLimit`: maksymalna liczba wiadomości z pokoju uwzględnianych jako kontekst historii grupy. Fallback do `messages.groupChat.historyLimit`; jeśli oba są nieustawione, efektywna wartość domyślna to `0`. Ustaw `0`, aby wyłączyć. +- `replyToMode`: `off`, `first`, `all` lub `batched`. - `markdown`: opcjonalna konfiguracja renderowania Markdown dla wychodzącego tekstu Matrix. -- `streaming`: `off` (domyślnie), `partial`, `quiet`, `true` lub `false`. `partial` i `true` włączają aktualizacje wersji roboczej „najpierw podgląd” przy użyciu zwykłych wiadomości tekstowych Matrix. `quiet` używa niepowiadamiających powiadomień podglądu dla samodzielnie hostowanych konfiguracji z regułami push. -- `blockStreaming`: `true` włącza osobne wiadomości postępu dla ukończonych bloków asystenta, gdy aktywny jest streaming wersji roboczej podglądu. -- `threadReplies`: `off`, `inbound` albo `always`. -- `threadBindings`: nadpisania per kanał dla routowania i cyklu życia sesji powiązanych z wątkami. -- `startupVerification`: tryb automatycznego żądania samoweryfikacji przy uruchamianiu (`if-unverified`, `off`). -- `startupVerificationCooldownHours`: czas karencji przed ponowieniem automatycznych żądań weryfikacji przy uruchamianiu. -- `textChunkLimit`: rozmiar fragmentu wiadomości wychodzącej. -- `chunkMode`: `length` lub `newline`. -- `responsePrefix`: opcjonalny prefiks wiadomości dla odpowiedzi wychodzących. -- `ackReaction`: opcjonalne nadpisanie reakcji potwierdzającej dla tego kanału/konta. -- `ackReactionScope`: opcjonalne nadpisanie zakresu reakcji potwierdzającej (`group-mentions`, `group-all`, `direct`, `all`, `none`, `off`). +- `streaming`: `off` (domyślnie), `"partial"`, `"quiet"`, `true` lub `false`. `"partial"` i `true` włączają aktualizacje wersji roboczej „najpierw podgląd” przy użyciu zwykłych wiadomości tekstowych Matrix. `"quiet"` używa niepowiadamiających komunikatów podglądu dla samohostowanych konfiguracji reguł push. `false` jest równoważne `"off"`. +- `blockStreaming`: `true` włącza osobne komunikaty postępu dla ukończonych bloków asystenta, gdy aktywne jest strumieniowanie podglądu wersji roboczej. +- `threadReplies`: `off`, `inbound` lub `always`. +- `threadBindings`: nadpisania per kanał dla routingu i cyklu życia sesji powiązanych z wątkami. +- `startupVerification`: tryb automatycznych żądań samoweryfikacji przy uruchamianiu (`if-unverified`, `off`). +- `startupVerificationCooldownHours`: cooldown przed ponowieniem automatycznych żądań weryfikacji przy uruchamianiu. +- `textChunkLimit`: rozmiar chunków wiadomości wychodzących w znakach (ma zastosowanie, gdy `chunkMode` ma wartość `length`). +- `chunkMode`: `length` dzieli wiadomości według liczby znaków; `newline` dzieli na granicach linii. +- `responsePrefix`: opcjonalny ciąg znaków dodawany na początku wszystkich odpowiedzi wychodzących dla tego kanału. +- `ackReaction`: opcjonalne nadpisanie reakcji potwierdzenia dla tego kanału/konta. +- `ackReactionScope`: opcjonalne nadpisanie zakresu reakcji potwierdzenia (`group-mentions`, `group-all`, `direct`, `all`, `none`, `off`). - `reactionNotifications`: tryb przychodzących powiadomień o reakcjach (`own`, `off`). -- `mediaMaxMb`: limit rozmiaru multimediów w MB dla obsługi multimediów Matrix. Dotyczy wysyłek wychodzących i przetwarzania multimediów przychodzących. -- `autoJoin`: polityka automatycznego dołączania do zaproszeń (`always`, `allowlist`, `off`). Domyślnie: `off`. Dotyczy ogólnie zaproszeń Matrix, w tym zaproszeń w stylu wiadomości prywatnej, a nie tylko zaproszeń do pokojów/grup. OpenClaw podejmuje tę decyzję w momencie zaproszenia, zanim może wiarygodnie sklasyfikować dołączony pokój jako wiadomość prywatną lub grupę. -- `autoJoinAllowlist`: pokoje/aliasy dozwolone, gdy `autoJoin` ma wartość `allowlist`. Wpisy aliasów są rozwiązywane do identyfikatorów pokojów podczas obsługi zaproszenia; OpenClaw nie ufa stanowi aliasu deklarowanemu przez zaproszony pokój. +- `mediaMaxMb`: limit rozmiaru multimediów w MB dla wysyłek wychodzących i przetwarzania multimediów przychodzących. +- `autoJoin`: polityka automatycznego dołączania do zaproszeń (`always`, `allowlist`, `off`). Domyślnie: `off`. Dotyczy wszystkich zaproszeń Matrix, w tym zaproszeń w stylu wiadomości prywatnych. +- `autoJoinAllowlist`: pokoje/aliasy dozwolone, gdy `autoJoin` ma wartość `allowlist`. Wpisy aliasów są rozwiązywane do ID pokoi podczas obsługi zaproszeń; OpenClaw nie ufa stanowi aliasu deklarowanemu przez zaproszony pokój. - `dm`: blok polityki wiadomości prywatnych (`enabled`, `policy`, `allowFrom`, `sessionScope`, `threadReplies`). -- `dm.policy`: kontroluje dostęp do wiadomości prywatnych po tym, jak OpenClaw dołączył do pokoju i sklasyfikował go jako wiadomość prywatną. Nie zmienia tego, czy do zaproszenia nastąpi automatyczne dołączenie. -- Wpisy `dm.allowFrom` powinny być pełnymi identyfikatorami użytkowników Matrix, chyba że zostały już rozwiązane przez wyszukiwanie katalogu na żywo. -- `dm.sessionScope`: `per-user` (domyślnie) albo `per-room`. Użyj `per-room`, jeśli chcesz, aby każdy pokój wiadomości prywatnych Matrix zachowywał osobny kontekst, nawet jeśli partner jest ten sam. -- `dm.threadReplies`: nadpisanie polityki wątków tylko dla wiadomości prywatnych (`off`, `inbound`, `always`). Nadpisuje najwyższego poziomu ustawienie `threadReplies` zarówno dla umieszczania odpowiedzi, jak i izolacji sesji w wiadomościach prywatnych. -- `execApprovals`: natywne dostarczanie zatwierdzeń exec przez Matrix (`enabled`, `approvers`, `target`, `agentFilter`, `sessionFilter`). -- `execApprovals.approvers`: identyfikatory użytkowników Matrix uprawnionych do zatwierdzania żądań exec. Opcjonalne, gdy `dm.allowFrom` już identyfikuje zatwierdzających. +- `dm.policy`: kontroluje dostęp do wiadomości prywatnych po dołączeniu OpenClaw do pokoju i sklasyfikowaniu go jako wiadomości prywatnej. Nie zmienia tego, czy zaproszenie zostanie automatycznie zaakceptowane przez dołączenie. +- `dm.allowFrom`: wpisy powinny być pełnymi ID użytkowników Matrix, chyba że zostały już rozwiązane przez wyszukiwanie katalogu na żywo. +- `dm.sessionScope`: `per-user` (domyślnie) lub `per-room`. Użyj `per-room`, gdy chcesz, aby każdy pokój wiadomości prywatnych Matrix zachowywał oddzielny kontekst, nawet jeśli peer jest ten sam. +- `dm.threadReplies`: nadpisanie polityki wątków tylko dla wiadomości prywatnych (`off`, `inbound`, `always`). Nadpisuje ustawienie najwyższego poziomu `threadReplies` zarówno dla umieszczania odpowiedzi, jak i izolacji sesji w wiadomościach prywatnych. +- `execApprovals`: natywne dostarczanie zatwierdzeń exec w Matrix (`enabled`, `approvers`, `target`, `agentFilter`, `sessionFilter`). +- `execApprovals.approvers`: ID użytkowników Matrix, którzy mogą zatwierdzać żądania exec. Opcjonalne, gdy `dm.allowFrom` już identyfikuje zatwierdzających. - `execApprovals.target`: `dm | channel | both` (domyślnie: `dm`). - `accounts`: nazwane nadpisania per konto. Wartości najwyższego poziomu `channels.matrix` działają jako wartości domyślne dla tych wpisów. -- `groups`: mapa zasad per pokój. Preferuj identyfikatory pokojów lub aliasy; nierozwiązane nazwy pokojów są ignorowane w runtime. Tożsamość sesji/grupy po rozwiązaniu używa stabilnego identyfikatora pokoju, podczas gdy etykiety czytelne dla ludzi nadal pochodzą z nazw pokojów. -- `groups..account`: ogranicza jeden odziedziczony wpis pokoju do konkretnego konta Matrix w konfiguracjach z wieloma kontami. +- `groups`: mapa polityk per pokój. Preferuj ID pokoi lub aliasy; nierozwiązane nazwy pokoi są ignorowane w czasie działania. Tożsamość sesji/grupy używa stabilnego ID pokoju po rozwiązaniu. +- `groups..account`: ogranicza jeden dziedziczony wpis pokoju do konkretnego konta Matrix w konfiguracjach wielokontowych. - `groups..allowBots`: nadpisanie na poziomie pokoju dla nadawców będących skonfigurowanymi botami (`true` lub `"mentions"`). -- `groups..users`: lista dozwolonych nadawców dla pokoju. -- `groups..tools`: nadpisania dozwolenia/odmowy narzędzi dla pokoju. -- `groups..autoReply`: nadpisanie wymuszania wzmianki na poziomie pokoju. `true` wyłącza wymaganie wzmianki dla tego pokoju; `false` wymusza je ponownie. +- `groups..users`: allowlista nadawców per pokój. +- `groups..tools`: nadpisania per pokój dla dozwalania/odmawiania narzędzi. +- `groups..autoReply`: nadpisanie wymagania wzmianki na poziomie pokoju. `true` wyłącza wymaganie wzmianki dla tego pokoju; `false` wymusza je ponownie. - `groups..skills`: opcjonalny filtr Skills na poziomie pokoju. -- `groups..systemPrompt`: opcjonalny fragment promptu systemowego na poziomie pokoju. +- `groups..systemPrompt`: opcjonalny fragment system promptu na poziomie pokoju. - `rooms`: starszy alias dla `groups`. -- `actions`: kontrola narzędzi per działanie (`messages`, `reactions`, `pins`, `profile`, `memberInfo`, `channelInfo`, `verification`). +- `actions`: kontrola użycia narzędzi per akcja (`messages`, `reactions`, `pins`, `profile`, `memberInfo`, `channelInfo`, `verification`). ## Powiązane - [Przegląd kanałów](/pl/channels) — wszystkie obsługiwane kanały - [Parowanie](/pl/channels/pairing) — uwierzytelnianie wiadomości prywatnych i przepływ parowania -- [Grupy](/pl/channels/groups) — zachowanie czatu grupowego i wymuszanie wzmianki -- [Routowanie kanałów](/pl/channels/channel-routing) — routowanie sesji dla wiadomości +- [Grupy](/pl/channels/groups) — zachowanie czatu grupowego i wymaganie wzmianki +- [Routing kanałów](/pl/channels/channel-routing) — routing sesji dla wiadomości - [Bezpieczeństwo](/pl/gateway/security) — model dostępu i utwardzanie diff --git a/docs/pl/concepts/agent-loop.md b/docs/pl/concepts/agent-loop.md index 6eec89e99..6ebfbf364 100644 --- a/docs/pl/concepts/agent-loop.md +++ b/docs/pl/concepts/agent-loop.md @@ -4,143 +4,145 @@ read_when: summary: Cykl życia pętli agenta, strumienie i semantyka oczekiwania title: Pętla agenta x-i18n: - generated_at: "2026-04-05T13:50:05Z" + generated_at: "2026-04-09T01:27:54Z" model: gpt-5.4 provider: openai - source_hash: 8e562e63c494881e9c345efcb93c5f972d69aaec61445afc3d4ad026b2d26883 + source_hash: 32d3a73df8dabf449211a6183a70dcfd2a9b6f584dc76d0c4c9147582b2ca6a1 source_path: concepts/agent-loop.md workflow: 15 --- # Pętla agenta (OpenClaw) -Pętla agentowa to pełny „rzeczywisty” przebieg działania agenta: przyjęcie wejścia → złożenie kontekstu → inferencja modelu → -wykonanie narzędzi → strumieniowanie odpowiedzi → utrwalenie. To autorytatywna ścieżka, która zamienia wiadomość +Pętla agentowa to pełny „rzeczywisty” przebieg działania agenta: przyjęcie danych wejściowych → złożenie kontekstu → wnioskowanie modelu → +wykonanie narzędzi → strumieniowanie odpowiedzi → utrwalenie. To autorytatywna ścieżka, która przekształca wiadomość w działania i końcową odpowiedź, jednocześnie utrzymując spójny stan sesji. W OpenClaw pętla to pojedynczy, serializowany przebieg na sesję, który emituje zdarzenia cyklu życia i strumieni -podczas myślenia modelu, wywoływania narzędzi i strumieniowania danych wyjściowych. Ten dokument wyjaśnia, jak ta autentyczna pętla jest połączona od początku do końca. +gdy model myśli, wywołuje narzędzia i strumieniuje dane wyjściowe. Ten dokument wyjaśnia, jak ta rzeczywista pętla +jest połączona od początku do końca. ## Punkty wejścia - Gateway RPC: `agent` i `agent.wait`. - CLI: polecenie `agent`. -## Jak to działa (wysoki poziom) +## Jak to działa (na wysokim poziomie) 1. RPC `agent` weryfikuje parametry, rozwiązuje sesję (sessionKey/sessionId), utrwala metadane sesji i natychmiast zwraca `{ runId, acceptedAt }`. 2. `agentCommand` uruchamia agenta: - - rozwiązuje model + domyślne ustawienia thinking/verbose + - rozwiązuje domyślne wartości modelu + thinking/verbose - ładuje migawkę Skills - wywołuje `runEmbeddedPiAgent` (środowisko uruchomieniowe pi-agent-core) - - emituje **lifecycle end/error**, jeśli osadzona pętla tego nie wyemituje + - emituje **koniec/błąd cyklu życia**, jeśli osadzona pętla tego nie wyemituje 3. `runEmbeddedPiAgent`: - - serializuje przebiegi przez kolejki per sesja + globalne - - rozwiązuje model + profil uwierzytelniania i buduje sesję pi - - subskrybuje zdarzenia pi i strumieniuje delty assistant/tool - - wymusza timeout -> przerywa przebieg po przekroczeniu + - serializuje przebiegi przez kolejki per sesja i globalne + - rozwiązuje profil modelu + auth i buduje sesję pi + - subskrybuje zdarzenia pi i strumieniuje delty asystenta/narzędzi + - wymusza limit czasu -> przerywa przebieg po jego przekroczeniu - zwraca ładunki + metadane użycia 4. `subscribeEmbeddedPiSession` mostkuje zdarzenia pi-agent-core do strumienia OpenClaw `agent`: - zdarzenia narzędzi => `stream: "tool"` - delty asystenta => `stream: "assistant"` - zdarzenia cyklu życia => `stream: "lifecycle"` (`phase: "start" | "end" | "error"`) 5. `agent.wait` używa `waitForAgentRun`: - - czeka na **lifecycle end/error** dla `runId` + - czeka na **koniec/błąd cyklu życia** dla `runId` - zwraca `{ status: ok|error|timeout, startedAt, endedAt, error? }` ## Kolejkowanie + współbieżność -- Przebiegi są serializowane per klucz sesji (pas sesji) i opcjonalnie przez pas globalny. -- To zapobiega wyścigom narzędzi/sesji i utrzymuje spójną historię sesji. -- Kanały wiadomości mogą wybierać tryby kolejkowania (collect/steer/followup), które zasilają ten system pasów. - Zobacz [Command Queue](/concepts/queue). +- Przebiegi są serializowane dla każdego klucza sesji (pas sesji) i opcjonalnie przez pas globalny. +- Zapobiega to wyścigom narzędzi/sesji i utrzymuje spójną historię sesji. +- Kanały wiadomości mogą wybierać tryby kolejki (collect/steer/followup), które zasilają ten system pasów. + Zobacz [Kolejka poleceń](/pl/concepts/queue). -## Przygotowanie sesji + workspace +## Przygotowanie sesji + przestrzeni roboczej -- Workspace jest rozwiązywany i tworzony; przebiegi w sandboxie mogą zostać przekierowane do głównego katalogu workspace sandboxa. +- Przestrzeń robocza jest rozwiązywana i tworzona; przebiegi sandboxowane mogą przekierowywać do katalogu głównego przestrzeni roboczej sandboxa. - Skills są ładowane (lub ponownie używane z migawki) i wstrzykiwane do env oraz promptu. -- Pliki bootstrap/kontekstu są rozwiązywane i wstrzykiwane do raportu system prompt. -- Uzyskiwana jest blokada zapisu sesji; `SessionManager` jest otwierany i przygotowywany przed rozpoczęciem strumieniowania. +- Pliki bootstrap/kontekstu są rozwiązywane i wstrzykiwane do raportu promptu systemowego. +- Uzyskiwana jest blokada zapisu sesji; `SessionManager` jest otwierany i przygotowywany przed strumieniowaniem. -## Składanie promptu + system prompt +## Składanie promptu + prompt systemowy -- System prompt jest budowany z promptu bazowego OpenClaw, promptu Skills, kontekstu bootstrap oraz nadpisań dla danego przebiegu. -- Wymuszane są ograniczenia specyficzne dla modelu oraz tokeny rezerwowe dla kompaktowania. -- Zobacz [System prompt](/concepts/system-prompt), aby sprawdzić, co widzi model. +- Prompt systemowy jest budowany z bazowego promptu OpenClaw, promptu Skills, kontekstu bootstrap i nadpisań dla przebiegu. +- Wymuszane są limity specyficzne dla modelu i tokeny rezerwowe dla kompaktowania. +- Zobacz [Prompt systemowy](/pl/concepts/system-prompt), aby sprawdzić, co widzi model. -## Punkty hooków (gdzie można przechwytywać) +## Punkty hooków (gdzie można przechwycić) OpenClaw ma dwa systemy hooków: -- **Wewnętrzne hooki** (hooki Gateway): skrypty sterowane zdarzeniami dla poleceń i zdarzeń cyklu życia. -- **Hooki pluginów**: punkty rozszerzeń wewnątrz pętli agenta/narzędzi i potoku gateway. +- **Hooki wewnętrzne** (hooki Gateway): skrypty sterowane zdarzeniami dla poleceń i zdarzeń cyklu życia. +- **Hooki pluginów**: punkty rozszerzeń wewnątrz cyklu życia agenta/narzędzi i potoku gateway. -### Wewnętrzne hooki (hooki Gateway) +### Hooki wewnętrzne (hooki Gateway) -- **`agent:bootstrap`**: uruchamia się podczas budowania plików bootstrap, zanim system prompt zostanie sfinalizowany. +- **`agent:bootstrap`**: uruchamia się podczas budowania plików bootstrap przed finalizacją promptu systemowego. Użyj tego, aby dodawać/usuwać pliki kontekstu bootstrap. -- **Hooki poleceń**: `/new`, `/reset`, `/stop` i inne zdarzenia poleceń (zobacz dokumentację Hooków). +- **Hooki poleceń**: `/new`, `/reset`, `/stop` i inne zdarzenia poleceń (zobacz dokumentację hooków). -Zobacz [Hooks](/pl/automation/hooks), aby poznać konfigurację i przykłady. +Zobacz [Hooki](/pl/automation/hooks), aby sprawdzić konfigurację i przykłady. ### Hooki pluginów (cykl życia agenta + gateway) -Działają one wewnątrz pętli agenta lub potoku gateway: +Uruchamiają się wewnątrz pętli agenta lub potoku gateway: -- **`before_model_resolve`**: uruchamia się przed sesją (bez `messages`), aby deterministycznie nadpisać provider/model przed rozstrzygnięciem modelu. -- **`before_prompt_build`**: uruchamia się po załadowaniu sesji (z `messages`), aby wstrzyknąć `prependContext`, `systemPrompt`, `prependSystemContext` lub `appendSystemContext` przed wysłaniem promptu. Używaj `prependContext` dla dynamicznego tekstu na turę, a pól kontekstu systemowego dla stabilnych wskazówek, które powinny znajdować się w przestrzeni system prompt. -- **`before_agent_start`**: przestarzały hook zgodności, który może uruchamiać się w obu fazach; preferuj powyższe jawne hooki. -- **`before_agent_reply`**: uruchamia się po działaniach inline i przed wywołaniem LLM, pozwalając pluginowi przejąć turę i zwrócić syntetyczną odpowiedź albo całkowicie wyciszyć turę. +- **`before_model_resolve`**: uruchamia się przed sesją (bez `messages`), aby deterministycznie nadpisać dostawcę/model przed rozwiązywaniem modelu. +- **`before_prompt_build`**: uruchamia się po załadowaniu sesji (z `messages`), aby wstrzyknąć `prependContext`, `systemPrompt`, `prependSystemContext` lub `appendSystemContext` przed wysłaniem promptu. Używaj `prependContext` dla dynamicznego tekstu per tura, a pól kontekstu systemowego dla stabilnych wskazówek, które powinny znajdować się w przestrzeni promptu systemowego. +- **`before_agent_start`**: hook zgodności wstecznej; może uruchamiać się w obu fazach; preferuj powyższe jawne hooki. +- **`before_agent_reply`**: uruchamia się po działaniach inline i przed wywołaniem LLM, pozwalając pluginowi przejąć turę i zwrócić syntetyczną odpowiedź lub całkowicie wyciszyć turę. - **`agent_end`**: sprawdza końcową listę wiadomości i metadane przebiegu po zakończeniu. -- **`before_compaction` / `after_compaction`**: obserwują lub adnotują cykle kompaktowania. +- **`before_compaction` / `after_compaction`**: obserwują lub opisują cykle kompaktowania. - **`before_tool_call` / `after_tool_call`**: przechwytują parametry/wyniki narzędzi. -- **`before_install`**: sprawdza wyniki skanowania wbudowanych elementów i opcjonalnie blokuje instalacje Skills lub pluginów. -- **`tool_result_persist`**: synchronicznie przekształca wyniki narzędzi, zanim zostaną zapisane do transkryptu sesji. +- **`before_install`**: sprawdza wbudowane wyniki skanowania i opcjonalnie blokuje instalacje skillów lub pluginów. +- **`tool_result_persist`**: synchronicznie przekształca wyniki narzędzi przed zapisaniem ich do transkryptu sesji. - **`message_received` / `message_sending` / `message_sent`**: hooki wiadomości przychodzących i wychodzących. - **`session_start` / `session_end`**: granice cyklu życia sesji. - **`gateway_start` / `gateway_stop`**: zdarzenia cyklu życia gateway. -Zasady decyzji hooków dla ochrony wysyłania/narzędzi: +Zasady decyzji hooków dla zabezpieczeń wychodzących/narzędzi: -- `before_tool_call`: `{ block: true }` jest terminalne i zatrzymuje handlery o niższym priorytecie. -- `before_tool_call`: `{ block: false }` nic nie robi i nie czyści wcześniejszej blokady. -- `before_install`: `{ block: true }` jest terminalne i zatrzymuje handlery o niższym priorytecie. -- `before_install`: `{ block: false }` nic nie robi i nie czyści wcześniejszej blokady. -- `message_sending`: `{ cancel: true }` jest terminalne i zatrzymuje handlery o niższym priorytecie. -- `message_sending`: `{ cancel: false }` nic nie robi i nie czyści wcześniejszego anulowania. +- `before_tool_call`: `{ block: true }` jest końcowe i zatrzymuje handlery o niższym priorytecie. +- `before_tool_call`: `{ block: false }` nic nie robi i nie usuwa wcześniejszej blokady. +- `before_install`: `{ block: true }` jest końcowe i zatrzymuje handlery o niższym priorytecie. +- `before_install`: `{ block: false }` nic nie robi i nie usuwa wcześniejszej blokady. +- `message_sending`: `{ cancel: true }` jest końcowe i zatrzymuje handlery o niższym priorytecie. +- `message_sending`: `{ cancel: false }` nic nie robi i nie usuwa wcześniejszego anulowania. -Zobacz [Plugin hooks](/plugins/architecture#provider-runtime-hooks), aby poznać API hooków i szczegóły rejestracji. +Zobacz [Hooki pluginów](/pl/plugins/architecture#provider-runtime-hooks), aby sprawdzić API hooków i szczegóły rejestracji. ## Strumieniowanie + odpowiedzi częściowe - Delty asystenta są strumieniowane z pi-agent-core i emitowane jako zdarzenia `assistant`. -- Strumieniowanie bloków może emitować odpowiedzi częściowe przy `text_end` albo `message_end`. -- Strumieniowanie reasoning może być emitowane jako osobny strumień albo jako odpowiedzi blokowe. -- Zobacz [Streaming](/concepts/streaming), aby poznać zachowanie chunkingu i odpowiedzi blokowych. +- Strumieniowanie bloków może emitować odpowiedzi częściowe na `text_end` lub `message_end`. +- Strumieniowanie rozumowania może być emitowane jako osobny strumień lub jako odpowiedzi blokowe. +- Zobacz [Strumieniowanie](/pl/concepts/streaming), aby sprawdzić dzielenie na fragmenty i zachowanie odpowiedzi blokowych. -## Wykonywanie narzędzi + narzędzia wiadomości +## Wykonanie narzędzi + narzędzia do wiadomości -- Zdarzenia rozpoczęcia/aktualizacji/zakończenia narzędzia są emitowane w strumieniu `tool`. -- Wyniki narzędzi są oczyszczane pod kątem rozmiaru i ładunków obrazów przed logowaniem/emisją. -- Wysłania przez narzędzia wiadomości są śledzone, aby tłumić zduplikowane potwierdzenia asystenta. +- Zdarzenia start/aktualizacja/koniec narzędzi są emitowane w strumieniu `tool`. +- Wyniki narzędzi są sanitizowane pod kątem rozmiaru i ładunków obrazów przed logowaniem/emisją. +- Wysłania narzędzi do wiadomości są śledzone, aby wyeliminować zduplikowane potwierdzenia asystenta. -## Kształtowanie odpowiedzi + tłumienie +## Kształtowanie odpowiedzi + wyciszanie - Końcowe ładunki są składane z: - - tekstu asystenta (oraz opcjonalnie reasoning) + - tekstu asystenta (i opcjonalnie rozumowania) - podsumowań narzędzi inline (gdy verbose + dozwolone) - tekstu błędu asystenta, gdy model zwraca błąd -- Dokładny cichy token `NO_REPLY` / `no_reply` jest filtrowany z wychodzących +- Dokładny token wyciszenia `NO_REPLY` / `no_reply` jest odfiltrowywany z wychodzących ładunków. -- Duplikaty z narzędzi wiadomości są usuwane z końcowej listy ładunków. -- Jeśli nie pozostaną żadne renderowalne ładunki, a narzędzie zwróciło błąd, emitowana jest awaryjna odpowiedź o błędzie narzędzia - (chyba że narzędzie wiadomości wysłało już odpowiedź widoczną dla użytkownika). +- Duplikaty narzędzi do wiadomości są usuwane z końcowej listy ładunków. +- Jeśli nie pozostaną żadne renderowalne ładunki, a narzędzie zwróciło błąd, emitowana jest + zapasowa odpowiedź błędu narzędzia + (chyba że narzędzie do wiadomości już wysłało widoczną dla użytkownika odpowiedź). -## Kompaktowanie + ponowne próby +## Kompaktowanie + ponowienia -- Automatyczne kompaktowanie emituje zdarzenia strumienia `compaction` i może wywołać ponowną próbę. -- Przy ponownej próbie bufory w pamięci i podsumowania narzędzi są resetowane, aby uniknąć zduplikowanego wyjścia. -- Zobacz [Compaction](/concepts/compaction), aby poznać potok kompaktowania. +- Automatyczne kompaktowanie emituje zdarzenia strumienia `compaction` i może wywołać ponowienie. +- Przy ponowieniu bufory w pamięci i podsumowania narzędzi są resetowane, aby uniknąć zduplikowanego wyjścia. +- Zobacz [Kompaktowanie](/pl/concepts/compaction), aby sprawdzić potok kompaktowania. ## Strumienie zdarzeń (obecnie) @@ -148,27 +150,28 @@ Zobacz [Plugin hooks](/plugins/architecture#provider-runtime-hooks), aby poznać - `assistant`: strumieniowane delty z pi-agent-core - `tool`: strumieniowane zdarzenia narzędzi z pi-agent-core -## Obsługa kanałów czatu +## Obsługa kanału czatu -- Delty asystenta są buforowane jako wiadomości czatu `delta`. -- `final` czatu jest emitowane przy **lifecycle end/error**. +- Delty asystenta są buforowane do wiadomości czatu `delta`. +- Końcowa wiadomość czatu `final` jest emitowana przy **końcu/błędzie cyklu życia**. ## Limity czasu -- Domyślnie `agent.wait`: 30 s (tylko samo oczekiwanie). Parametr `timeoutMs` nadpisuje. -- Czas działania agenta: domyślnie `agents.defaults.timeoutSeconds` to 172800 s (48 godzin); wymuszane przez timer przerwania w `runEmbeddedPiAgent`. +- Domyślnie `agent.wait`: 30 s (tylko oczekiwanie). Parametr `timeoutMs` nadpisuje tę wartość. +- Czas działania agenta: domyślnie `agents.defaults.timeoutSeconds` to 172800 s (48 godzin); wymuszany przez licznik przerwania w `runEmbeddedPiAgent`. +- Limit bezczynności LLM: `agents.defaults.llm.idleTimeoutSeconds` przerywa żądanie modelu, gdy przed upływem okna bezczynności nie nadejdą żadne fragmenty odpowiedzi. Ustaw tę wartość jawnie dla wolnych modeli lokalnych lub dostawców rozumowania/wywołań narzędzi; ustaw `0`, aby wyłączyć. Jeśli nie jest ustawiona, OpenClaw używa `agents.defaults.timeoutSeconds`, gdy jest skonfigurowane, w przeciwnym razie 60 s. Przebiegi wyzwalane przez cron bez jawnego limitu czasu LLM lub agenta wyłączają mechanizm bezczynności i polegają na zewnętrznym limicie czasu crona. -## Gdzie rzeczy mogą zakończyć się wcześniej +## Gdzie wszystko może zakończyć się wcześniej -- Timeout agenta (przerwanie) +- Limit czasu agenta (przerwanie) - AbortSignal (anulowanie) -- Rozłączenie Gateway lub timeout RPC -- Timeout `agent.wait` (dotyczy tylko oczekiwania, nie zatrzymuje agenta) +- Rozłączenie gateway lub limit czasu RPC +- Limit czasu `agent.wait` (tylko oczekiwanie, nie zatrzymuje agenta) ## Powiązane -- [Tools](/tools) — dostępne narzędzia agenta -- [Hooks](/pl/automation/hooks) — skrypty sterowane zdarzeniami wywoływane przez zdarzenia cyklu życia agenta -- [Compaction](/concepts/compaction) — jak długie rozmowy są podsumowywane -- [Exec Approvals](/tools/exec-approvals) — bramki zatwierdzania dla poleceń powłoki -- [Thinking](/tools/thinking) — konfiguracja poziomu thinking/reasoning +- [Narzędzia](/pl/tools) — dostępne narzędzia agenta +- [Hooki](/pl/automation/hooks) — skrypty sterowane zdarzeniami wyzwalane przez zdarzenia cyklu życia agenta +- [Kompaktowanie](/pl/concepts/compaction) — jak podsumowywane są długie rozmowy +- [Zgody exec](/pl/tools/exec-approvals) — bramki zatwierdzania dla poleceń powłoki +- [Thinking](/pl/tools/thinking) — konfiguracja poziomu myślenia/rozumowania diff --git a/docs/pl/concepts/dreaming.md b/docs/pl/concepts/dreaming.md index ef708543a..23394dab9 100644 --- a/docs/pl/concepts/dreaming.md +++ b/docs/pl/concepts/dreaming.md @@ -1,124 +1,138 @@ --- read_when: - Chcesz, aby promowanie pamięci uruchamiało się automatycznie - - Chcesz zrozumieć, co robi każda faza śnienia + - Chcesz zrozumieć, co robi każda faza dreaming - Chcesz dostroić konsolidację bez zaśmiecania `MEMORY.md` -summary: Konsolidacja pamięci w tle z fazami lekką, głęboką i REM oraz Dziennikiem snów -title: Śnienie (eksperymentalne) +summary: Konsolidacja pamięci w tle z fazami light, deep i REM oraz Dream Diary +title: Dreaming (eksperymentalne) x-i18n: - generated_at: "2026-04-08T09:44:09Z" + generated_at: "2026-04-09T01:27:48Z" model: gpt-5.4 provider: openai - source_hash: 0254f3b0949158264e583c12f36f2b1a83d1b44dc4da01a1b272422d38e8655d + source_hash: 26476eddb8260e1554098a6adbb069cf7f5e284cf2e09479c6d9d8f8b93280ef source_path: concepts/dreaming.md workflow: 15 --- -# Śnienie (eksperymentalne) +# Dreaming (eksperymentalne) -Śnienie to system konsolidacji pamięci działający w tle w `memory-core`. -Pomaga OpenClaw przenosić silne sygnały pamięci krótkoterminowej do trwałej pamięci, -jednocześnie zachowując przejrzystość i możliwość przeglądu tego procesu. +Dreaming to system konsolidacji pamięci w tle w `memory-core`. +Pomaga OpenClaw przenosić silne krótkoterminowe sygnały do trwałej pamięci, jednocześnie +zachowując przejrzystość i możliwość przeglądu procesu. -Śnienie jest **opcjonalne** i domyślnie wyłączone. +Dreaming jest funkcją **opt-in** i domyślnie jest wyłączone. -## Co zapisuje śnienie +## Co zapisuje dreaming -Śnienie przechowuje dwa rodzaje danych wyjściowych: +Dreaming utrzymuje dwa rodzaje danych wyjściowych: -- **Stan maszyny** w `memory/.dreams/` (magazyn przywołań, sygnały faz, punkty kontrolne przetwarzania, blokady). +- **Stan maszyny** w `memory/.dreams/` (magazyn przypomnień, sygnały faz, punkty kontrolne ingestii, blokady). - **Dane czytelne dla człowieka** w `DREAMS.md` (lub istniejącym `dreams.md`) oraz opcjonalne pliki raportów faz w `memory/dreaming//YYYY-MM-DD.md`. -Promowanie do pamięci długoterminowej nadal zapisuje dane wyłącznie do `MEMORY.md`. +Promowanie do pamięci długoterminowej nadal zapisuje wyłącznie do `MEMORY.md`. ## Model faz -Śnienie używa trzech współpracujących faz: +Dreaming używa trzech współpracujących faz: -| Faza | Cel | Trwały zapis | -| ----- | ---------------------------------------- | ----------------- | -| Lekka | Sortowanie i przygotowywanie ostatnich materiałów krótkoterminowych | Nie | -| Głęboka | Ocenianie i promowanie trwałych kandydatów | Tak (`MEMORY.md`) | -| REM | Refleksja nad motywami i powracającymi pomysłami | Nie | +| Faza | Cel | Trwały zapis | +| ----- | ----------------------------------------- | ----------------- | +| Light | Sortowanie i przygotowanie ostatnich materiałów krótkoterminowych | Nie | +| Deep | Ocenianie i promowanie trwałych kandydatów | Tak (`MEMORY.md`) | +| REM | Refleksja nad tematami i powracającymi ideami | Nie | -Te fazy są wewnętrznymi szczegółami implementacji, a nie osobnymi +Te fazy są wewnętrznymi szczegółami implementacji, a nie oddzielnymi konfigurowanymi przez użytkownika „trybami”. -### Faza lekka +### Faza light -Faza lekka przetwarza ostatnie sygnały dziennej pamięci i ślady przywołań, usuwa duplikaty -i przygotowuje linie kandydatów. +Faza light pobiera ostatnie dzienne sygnały pamięci i ślady przypomnień, usuwa duplikaty +i przygotowuje wiersze kandydatów. -- Odczytuje stan przywołań krótkoterminowych, ostatnie dzienne pliki pamięci oraz zredagowane transkrypty sesji, jeśli są dostępne. -- Zapisuje zarządzany blok `## Light Sleep`, gdy magazyn zawiera dane wyjściowe osadzone w pliku. -- Rejestruje sygnały wzmocnienia do późniejszego rankingu głębokiego. +- Odczytuje stan krótkoterminowych przypomnień, ostatnie dzienne pliki pamięci oraz zredagowane transkrypty sesji, gdy są dostępne. +- Zapisuje zarządzany blok `## Light Sleep`, gdy magazyn zawiera dane wyjściowe inline. +- Rejestruje sygnały wzmacniające na potrzeby późniejszego rankingu deep. - Nigdy nie zapisuje do `MEMORY.md`. -### Faza głęboka +### Faza deep -Faza głęboka decyduje, co trafia do pamięci długoterminowej. +Faza deep decyduje, co staje się pamięcią długoterminową. - Ustala ranking kandydatów przy użyciu ważonej punktacji i progów. -- Wymaga spełnienia `minScore`, `minRecallCount` oraz `minUniqueQueries`. -- Przed zapisem ponownie pobiera fragmenty z bieżących plików dziennych, więc nieaktualne lub usunięte fragmenty są pomijane. +- Wymaga spełnienia wartości `minScore`, `minRecallCount` i `minUniqueQueries`. +- Przed zapisem ponownie pobiera fragmenty z aktywnych plików dziennych, więc nieaktualne/usunięte fragmenty są pomijane. - Dopisuje promowane wpisy do `MEMORY.md`. -- Zapisuje podsumowanie `## Deep Sleep` w `DREAMS.md` i opcjonalnie zapisuje `memory/dreaming/deep/YYYY-MM-DD.md`. +- Zapisuje podsumowanie `## Deep Sleep` do `DREAMS.md` i opcjonalnie zapisuje `memory/dreaming/deep/YYYY-MM-DD.md`. ### Faza REM Faza REM wyodrębnia wzorce i sygnały refleksyjne. -- Buduje podsumowania motywów i refleksji na podstawie ostatnich śladów krótkoterminowych. -- Zapisuje zarządzany blok `## REM Sleep`, gdy magazyn zawiera dane wyjściowe osadzone w pliku. -- Rejestruje sygnały wzmocnienia REM używane przez ranking głęboki. +- Buduje podsumowania tematów i refleksji na podstawie ostatnich krótkoterminowych śladów. +- Zapisuje zarządzany blok `## REM Sleep`, gdy magazyn zawiera dane wyjściowe inline. +- Rejestruje sygnały wzmacniające REM używane przez ranking deep. - Nigdy nie zapisuje do `MEMORY.md`. -## Przetwarzanie transkryptów sesji +## Ingestia transkryptów sesji -Śnienie może przetwarzać zredagowane transkrypty sesji do korpusu śnienia. Gdy -transkrypty są dostępne, są przekazywane do fazy lekkiej razem z dziennymi -sygnałami pamięci i śladami przywołań. Treści osobiste i wrażliwe są redagowane -przed przetworzeniem. +Dreaming może pobierać zredagowane transkrypty sesji do korpusu dreaming. Gdy +transkrypty są dostępne, są przekazywane do fazy light razem z dziennymi +sygnałami pamięci i śladami przypomnień. Treści osobiste i wrażliwe są redagowane +przed ingestą. -## Dziennik snów +## Dream Diary -Śnienie prowadzi również narracyjny **Dziennik snów** w `DREAMS.md`. -Gdy po każdej fazie zbierze się wystarczająco dużo materiału, `memory-core` uruchamia -w tle, w trybie best-effort, turę podagenta (z użyciem domyślnego modelu runtime) +Dreaming prowadzi także narracyjny **Dream Diary** w `DREAMS.md`. +Gdy po każdej fazie zgromadzi się wystarczająco dużo materiału, `memory-core` uruchamia w tle +podrzędny turn subagenta typu best-effort (przy użyciu domyślnego modelu runtime) i dopisuje krótki wpis do dziennika. -Ten dziennik służy do czytania przez człowieka w interfejsie Dreams, a nie jako źródło promocji. +Ten dziennik jest przeznaczony do odczytu przez człowieka w interfejsie Dreams, a nie jako źródło promocji. -## Sygnały rankingu głębokiego +Istnieje również ugruntowana ścieżka historycznego backfill dla przeglądu i odzyskiwania: -Ranking głęboki używa sześciu ważonych sygnałów bazowych oraz wzmocnienia faz: +- `memory rem-harness --path ... --grounded` wyświetla podgląd ugruntowanych wpisów dziennika na podstawie historycznych notatek `YYYY-MM-DD.md`. +- `memory rem-backfill --path ...` zapisuje odwracalne ugruntowane wpisy dziennika do `DREAMS.md`. +- `memory rem-backfill --path ... --stage-short-term` przygotowuje ugruntowanych trwałych kandydatów w tym samym magazynie dowodów krótkoterminowych, którego używa już normalna faza deep. +- `memory rem-backfill --rollback` i `--rollback-short-term` usuwają te przygotowane artefakty backfill bez naruszania zwykłych wpisów dziennika ani aktywnych krótkoterminowych przypomnień. -| Sygnał | Waga | Opis | +Control UI udostępnia ten sam przepływ backfill/reset dziennika, dzięki czemu możesz sprawdzić +wyniki w scenie Dreams przed podjęciem decyzji, czy ugruntowani kandydaci +zasługują na promocję. Scena pokazuje też odrębny ugruntowany tor, aby było widać, +które przygotowane wpisy krótkoterminowe pochodzą z historycznego odtworzenia, które promowane +elementy były prowadzone przez grounded, oraz umożliwia wyczyszczenie tylko ugruntowanych przygotowanych wpisów bez +naruszania zwykłego aktywnego stanu krótkoterminowego. + +## Sygnały rankingu deep + +Ranking deep używa sześciu ważonych sygnałów bazowych oraz wzmocnienia fazowego: + +| Sygnał | Waga | Opis | | ------------------- | ------ | ------------------------------------------------- | -| Częstotliwość | 0.24 | Ile sygnałów krótkoterminowych zgromadził wpis | -| Trafność | 0.30 | Średnia jakość pobierania dla wpisu | -| Różnorodność zapytań | 0.15 | Różne konteksty zapytań/dni, w których się pojawił | -| Aktualność | 0.15 | Wynik świeżości z zanikiem w czasie | -| Konsolidacja | 0.10 | Siła nawrotów w wielu dniach | -| Bogactwo pojęciowe | 0.06 | Gęstość tagów pojęciowych z fragmentu/ścieżki | +| Częstotliwość | 0.24 | Ile krótkoterminowych sygnałów zgromadził wpis | +| Trafność | 0.30 | Średnia jakość odzyskiwania dla wpisu | +| Różnorodność zapytań | 0.15 | Odrębne konteksty zapytania/dnia, które go ujawniły | +| Aktualność | 0.15 | Wynik świeżości z zanikiem w czasie | +| Konsolidacja | 0.10 | Siła nawrotów w wielu dniach | +| Bogactwo pojęciowe | 0.06 | Gęstość tagów pojęciowych z fragmentu/ścieżki | -Trafienia fazy lekkiej i REM dodają niewielkie wzmocnienie z zanikiem aktualności z +Trafienia w fazach light i REM dodają niewielkie wzmocnienie z zanikiem aktualności z `memory/.dreams/phase-signals.json`. ## Harmonogram Po włączeniu `memory-core` automatycznie zarządza jednym zadaniem cron dla pełnego -przebiegu śnienia. Każdy przebieg uruchamia fazy w kolejności: lekka -> REM -> głęboka. +przebiegu dreaming. Każdy przebieg uruchamia fazy po kolei: light -> REM -> deep. -Domyślne zachowanie harmonogramu: +Domyślne zachowanie kadencji: -| Ustawienie | Domyślna wartość | -| -------------------- | ----------- | +| Ustawienie | Domyślnie | +| ------------------- | ---------- | | `dreaming.frequency` | `0 3 * * *` | ## Szybki start -Włącz śnienie: +Włącz dreaming: ```json { @@ -136,7 +150,7 @@ Włącz śnienie: } ``` -Włącz śnienie z niestandardowym harmonogramem przebiegów: +Włącz dreaming z niestandardową kadencją przebiegu: ```json { @@ -156,7 +170,7 @@ Włącz śnienie z niestandardowym harmonogramem przebiegów: } ``` -## Polecenie ukośnikowe +## Komenda slash ``` /dreaming status @@ -167,7 +181,7 @@ Włącz śnienie z niestandardowym harmonogramem przebiegów: ## Przepływ pracy CLI -Użyj promocji w CLI do podglądu lub ręcznego zastosowania: +Użyj promowania przez CLI do podglądu lub ręcznego zastosowania: ```bash openclaw memory promote @@ -176,7 +190,7 @@ openclaw memory promote --limit 5 openclaw memory status --deep ``` -Ręczne `memory promote` domyślnie używa progów fazy głębokiej, o ile nie zostaną nadpisane +Ręczne `memory promote` domyślnie używa progów fazy deep, chyba że zostaną nadpisane flagami CLI. Wyjaśnij, dlaczego konkretny kandydat zostałby lub nie zostałby promowany: @@ -186,7 +200,7 @@ openclaw memory promote-explain "router vlan" openclaw memory promote-explain "router vlan" --json ``` -Wyświetl podgląd refleksji REM, prawd kandydatów i danych wyjściowych promocji głębokiej bez +Wyświetl podgląd refleksji REM, prawd kandydatów i danych wyjściowych promocji deep bez zapisywania czegokolwiek: ```bash @@ -198,29 +212,30 @@ openclaw memory rem-harness --json Wszystkie ustawienia znajdują się w `plugins.entries.memory-core.config.dreaming`. -| Klucz | Domyślna wartość | -| ----------- | ----------- | +| Klucz | Domyślnie | +| ---------- | ---------- | | `enabled` | `false` | | `frequency` | `0 3 * * *` | Polityka faz, progi i zachowanie magazynu są wewnętrznymi szczegółami implementacji -(i nie stanowią konfiguracji dostępnej dla użytkownika). +(nie są to ustawienia dostępne dla użytkownika). -Pełną listę kluczy znajdziesz w [Dokumentacji konfiguracji pamięci](/pl/reference/memory-config#dreaming-experimental). +Pełną listę kluczy znajdziesz w [Memory configuration reference](/pl/reference/memory-config#dreaming-experimental). ## Interfejs Dreams Po włączeniu karta **Dreams** w Gateway pokazuje: -- bieżący stan włączenia śnienia -- stan na poziomie faz i obecność zarządzanego przebiegu -- liczbę elementów krótkoterminowych, długoterminowych i promowanych dzisiaj +- bieżący stan włączenia dreaming +- stan na poziomie faz oraz obecność zarządzanego przebiegu +- liczby elementów krótkoterminowych, ugruntowanych, sygnałów i promowanych dzisiaj - czas następnego zaplanowanego uruchomienia -- rozwijany czytnik Dziennika snów oparty na `doctor.memory.dreamDiary` +- odrębny ugruntowany tor sceny dla przygotowanych wpisów historycznego odtworzenia +- rozwijany czytnik Dream Diary oparty na `doctor.memory.dreamDiary` ## Powiązane -- [Pamięć](/pl/concepts/memory) -- [Wyszukiwanie w pamięci](/pl/concepts/memory-search) -- [CLI pamięci](/cli/memory) -- [Dokumentacja konfiguracji pamięci](/pl/reference/memory-config) +- [Memory](/pl/concepts/memory) +- [Memory Search](/pl/concepts/memory-search) +- [memory CLI](/cli/memory) +- [Memory configuration reference](/pl/reference/memory-config) diff --git a/docs/pl/concepts/memory.md b/docs/pl/concepts/memory.md index 6e5de01a2..f278e4d96 100644 --- a/docs/pl/concepts/memory.md +++ b/docs/pl/concepts/memory.md @@ -1,23 +1,23 @@ --- read_when: - Chcesz zrozumieć, jak działa pamięć - - Chcesz wiedzieć, jakie pliki pamięci zapisywać + - Chcesz wiedzieć, które pliki pamięci zapisywać summary: Jak OpenClaw zapamiętuje rzeczy między sesjami title: Przegląd pamięci x-i18n: - generated_at: "2026-04-08T06:01:02Z" + generated_at: "2026-04-09T01:27:50Z" model: gpt-5.4 provider: openai - source_hash: 3bb8552341b0b651609edaaae826a22fdc535d240aed4fad4af4b069454004af + source_hash: 2fe47910f5bf1c44be379e971c605f1cb3a29befcf2a7ee11fb3833cbe3b9059 source_path: concepts/memory.md workflow: 15 --- # Przegląd pamięci -OpenClaw zapamiętuje rzeczy, zapisując **zwykłe pliki Markdown** w przestrzeni -roboczej Twojego agenta. Model „pamięta” tylko to, co zostanie zapisane na dysku — -nie ma żadnego ukrytego stanu. +OpenClaw zapamiętuje rzeczy, zapisując **zwykłe pliki Markdown** w obszarze roboczym +Twojego agenta. Model „pamięta” tylko to, co zostanie zapisane na dysku — nie ma +żadnego ukrytego stanu. ## Jak to działa @@ -26,77 +26,78 @@ Twój agent ma trzy pliki związane z pamięcią: - **`MEMORY.md`** — pamięć długoterminowa. Trwałe fakty, preferencje i decyzje. Wczytywany na początku każdej sesji DM. - **`memory/YYYY-MM-DD.md`** — codzienne notatki. Bieżący kontekst i obserwacje. - Dzisiejsze i wczorajsze notatki są wczytywane automatycznie. -- **`DREAMS.md`** (eksperymentalny, opcjonalny) — Dream Diary i podsumowania - przebiegów śnienia do przeglądu przez człowieka. + Notatki z dziś i z wczoraj są wczytywane automatycznie. +- **`DREAMS.md`** (eksperymentalny, opcjonalny) — Dream Diary oraz podsumowania + przebiegów dreaming do przeglądu przez człowieka, w tym ugruntowane wpisy + historycznego backfill. -Te pliki znajdują się w przestrzeni roboczej agenta (domyślnie `~/.openclaw/workspace`). +Te pliki znajdują się w obszarze roboczym agenta (domyślnie `~/.openclaw/workspace`). -Jeśli chcesz, aby Twój agent coś zapamiętał, po prostu mu to powiedz: „Pamiętaj, -że wolę TypeScript.” Zapisze to do odpowiedniego pliku. +Jeśli chcesz, aby Twój agent coś zapamiętał, po prostu go o to poproś: „Zapamiętaj, że +preferuję TypeScript.” Zapisze to do odpowiedniego pliku. ## Narzędzia pamięci Agent ma dwa narzędzia do pracy z pamięcią: -- **`memory_search`** — znajduje odpowiednie notatki za pomocą wyszukiwania semantycznego, nawet gdy - sformułowanie różni się od oryginału. -- **`memory_get`** — odczytuje konkretny plik pamięci lub zakres wierszy. +- **`memory_search`** — znajduje odpowiednie notatki za pomocą wyszukiwania + semantycznego, nawet gdy sformułowanie różni się od oryginału. +- **`memory_get`** — odczytuje określony plik pamięci lub zakres wierszy. Oba narzędzia są dostarczane przez aktywny plugin pamięci (domyślnie: `memory-core`). -## Plugin towarzyszący Memory Wiki +## Towarzyszący plugin Memory Wiki Jeśli chcesz, aby trwała pamięć działała bardziej jak utrzymywana baza wiedzy niż tylko surowe notatki, użyj dołączonego pluginu `memory-wiki`. -`memory-wiki` kompiluje trwałą wiedzę do skarbca wiki z: +`memory-wiki` kompiluje trwałą wiedzę do wiki vault z: - deterministyczną strukturą stron -- uporządkowanymi twierdzeniami i dowodami +- ustrukturyzowanymi twierdzeniami i dowodami - śledzeniem sprzeczności i aktualności - generowanymi pulpitami -- skompilowanymi skrótami dla agentów/środowiska uruchomieniowego -- narzędziami natywnymi dla wiki, takimi jak `wiki_search`, `wiki_get`, `wiki_apply` i `wiki_lint` +- skompilowanymi skrótami dla konsumentów agent/runtime +- natywnymi dla wiki narzędziami, takimi jak `wiki_search`, `wiki_get`, `wiki_apply` i `wiki_lint` Nie zastępuje aktywnego pluginu pamięci. Aktywny plugin pamięci nadal -odpowiada za przywoływanie, promowanie i śnienie. `memory-wiki` dodaje obok niego -warstwę wiedzy bogatą w informacje o pochodzeniu. +odpowiada za przypominanie, promowanie i dreaming. `memory-wiki` dodaje +warstwę wiedzy bogatą w pochodzenie obok niego. Zobacz [Memory Wiki](/pl/plugins/memory-wiki). ## Wyszukiwanie w pamięci -Gdy skonfigurowany jest dostawca osadzeń, `memory_search` używa **wyszukiwania -hybrydowego** — łącząc podobieństwo wektorowe (znaczenie semantyczne) z dopasowaniem słów kluczowych -(dokładne terminy, takie jak identyfikatory i symbole kodu). Działa to od razu po -dodaniu klucza API dla dowolnego obsługiwanego dostawcy. +Gdy skonfigurowany jest dostawca embeddingów, `memory_search` używa **wyszukiwania +hybrydowego** — łączącego podobieństwo wektorowe (znaczenie semantyczne) z dopasowaniem +słów kluczowych (dokładne terminy, takie jak identyfikatory i symbole kodu). +Działa to od razu po skonfigurowaniu klucza API dla dowolnego obsługiwanego dostawcy. -OpenClaw automatycznie wykrywa dostawcę osadzeń na podstawie dostępnych kluczy API. Jeśli +OpenClaw automatycznie wykrywa dostawcę embeddingów na podstawie dostępnych kluczy API. Jeśli masz skonfigurowany klucz OpenAI, Gemini, Voyage lub Mistral, wyszukiwanie w pamięci jest włączane automatycznie. -Szczegółowe informacje o działaniu wyszukiwania, opcjach dostrajania i konfiguracji dostawców znajdziesz w -[Memory Search](/pl/concepts/memory-search). +Szczegółowe informacje o działaniu wyszukiwania, opcjach dostrajania i konfiguracji +dostawców znajdziesz w [Memory Search](/pl/concepts/memory-search). ## Backendy pamięci -Oparty na SQLite. Działa od razu z wyszukiwaniem po słowach kluczowych, podobieństwem wektorowym i +Oparty na SQLite. Działa od razu z wyszukiwaniem słów kluczowych, podobieństwem wektorowym i wyszukiwaniem hybrydowym. Bez dodatkowych zależności. Lokalny sidecar z rerankingiem, rozszerzaniem zapytań i możliwością indeksowania -katalogów poza przestrzenią roboczą. +katalogów poza obszarem roboczym. Natywna dla AI pamięć między sesjami z modelowaniem użytkownika, wyszukiwaniem semantycznym i -świadomością wielu agentów. Instalacja pluginu. +świadomością wielu agentów. Wymaga instalacji pluginu. @@ -104,48 +105,83 @@ Natywna dla AI pamięć między sesjami z modelowaniem użytkownika, wyszukiwani -Kompiluje trwałą pamięć do skarbca wiki bogatego w informacje o pochodzeniu, z twierdzeniami, -pulpitami, trybem bridge i przepływami pracy przyjaznymi dla Obsidian. +Kompiluje trwałą pamięć do wiki vault bogatego w pochodzenie z twierdzeniami, +pulpitami, trybem mostu i przepływami pracy przyjaznymi dla Obsidian. ## Automatyczne opróżnianie pamięci Zanim [kompaktowanie](/pl/concepts/compaction) podsumuje Twoją rozmowę, OpenClaw -uruchamia cichą turę, która przypomina agentowi o zapisaniu ważnego kontekstu do plików -pamięci. Jest to domyślnie włączone — nie musisz niczego konfigurować. +uruchamia cichą turę, która przypomina agentowi o zapisaniu ważnego kontekstu w plikach +pamięci. Jest to domyślnie włączone — nie musisz nic konfigurować. Opróżnianie pamięci zapobiega utracie kontekstu podczas kompaktowania. Jeśli Twój agent ma -w rozmowie ważne fakty, które nie zostały jeszcze zapisane do pliku, -zostaną zapisane automatycznie przed utworzeniem podsumowania. +w rozmowie ważne fakty, które nie zostały jeszcze zapisane do pliku, zostaną one +zapisane automatycznie, zanim nastąpi podsumowanie. -## Śnienie (eksperymentalne) +## Dreaming (eksperymentalne) -Śnienie to opcjonalny proces konsolidacji pamięci działający w tle. Zbiera -sygnały krótkoterminowe, ocenia kandydatów i promuje tylko kwalifikujące się elementy do -pamięci długoterminowej (`MEMORY.md`). +Dreaming to opcjonalny przebieg konsolidacji pamięci w tle. Zbiera +sygnały krótkoterminowe, ocenia kandydatów i promuje do pamięci +długoterminowej (`MEMORY.md`) tylko elementy spełniające kryteria. -Zostało zaprojektowane tak, aby utrzymywać wysoki stosunek sygnału do szumu w pamięci długoterminowej: +Został zaprojektowany tak, aby utrzymywać wysoki stosunek sygnału do szumu w pamięci długoterminowej: - **Opt-in**: domyślnie wyłączone. -- **Zaplanowane**: po włączeniu `memory-core` automatycznie zarządza jednym cyklicznym zadaniem cron - dla pełnego przebiegu śnienia. -- **Progowe**: promocje muszą przejść progi punktacji, częstotliwości przywołań i +- **Harmonogram**: po włączeniu `memory-core` automatycznie zarządza jednym cyklicznym zadaniem cron + dla pełnego przebiegu dreaming. +- **Progowe**: promocje muszą przejść progi wyniku, częstotliwości przypominania i różnorodności zapytań. - **Możliwe do przeglądu**: podsumowania faz i wpisy dziennika są zapisywane do `DREAMS.md` do przeglądu przez człowieka. -Informacje o zachowaniu faz, sygnałach punktacji i szczegółach Dream Diary znajdziesz w +Informacje o zachowaniu faz, sygnałach oceniania i szczegółach Dream Diary znajdziesz w [Dreaming (experimental)](/pl/concepts/dreaming). +## Ugruntowany backfill i promocja na żywo + +System dreaming ma teraz dwa ściśle powiązane tory przeglądu: + +- **Live dreaming** działa na podstawie krótkoterminowego magazynu dreaming w + `memory/.dreams/` i to właśnie z niego korzysta normalna głęboka faza przy podejmowaniu decyzji, co + może zostać przeniesione do `MEMORY.md`. +- **Grounded backfill** odczytuje historyczne notatki `memory/YYYY-MM-DD.md` jako + samodzielne pliki dzienne i zapisuje ustrukturyzowany wynik przeglądu do `DREAMS.md`. + +Grounded backfill jest przydatny, gdy chcesz ponownie przeanalizować starsze notatki i sprawdzić, +co system uważa za trwałe, bez ręcznego edytowania `MEMORY.md`. + +Gdy użyjesz: + +```bash +openclaw memory rem-backfill --path ./memory --stage-short-term +``` + +ugruntowani kandydaci trwałej pamięci nie są promowani bezpośrednio. Są etapowani do +tego samego krótkoterminowego magazynu dreaming, z którego korzysta już normalna głęboka faza. To +oznacza, że: + +- `DREAMS.md` pozostaje powierzchnią przeglądu dla człowieka. +- magazyn krótkoterminowy pozostaje powierzchnią rankingową dla maszyn. +- `MEMORY.md` nadal jest zapisywany wyłącznie przez głęboką promocję. + +Jeśli uznasz, że ponowne odtworzenie nie było przydatne, możesz usunąć etapowane artefakty +bez naruszania zwykłych wpisów dziennika ani normalnego stanu przypominania: + +```bash +openclaw memory rem-backfill --rollback +openclaw memory rem-backfill --rollback-short-term +``` + ## CLI ```bash openclaw memory status # Sprawdź stan indeksu i dostawcę -openclaw memory search "query" # Wyszukuj z wiersza poleceń -openclaw memory index --force # Przebuduj indeks +openclaw memory search "query" # Wyszukiwanie z wiersza poleceń +openclaw memory index --force # Odbuduj indeks ``` ## Dalsza lektura @@ -153,10 +189,10 @@ openclaw memory index --force # Przebuduj indeks - [Builtin Memory Engine](/pl/concepts/memory-builtin) — domyślny backend SQLite - [QMD Memory Engine](/pl/concepts/memory-qmd) — zaawansowany lokalny sidecar - [Honcho Memory](/pl/concepts/memory-honcho) — natywna dla AI pamięć między sesjami -- [Memory Wiki](/pl/plugins/memory-wiki) — skompilowany skarbiec wiedzy i narzędzia natywne dla wiki +- [Memory Wiki](/pl/plugins/memory-wiki) — skompilowany sejf wiedzy i narzędzia natywne dla wiki - [Memory Search](/pl/concepts/memory-search) — potok wyszukiwania, dostawcy i dostrajanie -- [Dreaming (experimental)](/pl/concepts/dreaming) — promowanie w tle - z krótkoterminowego przywoływania do pamięci długoterminowej +- [Dreaming (experimental)](/pl/concepts/dreaming) — promocja w tle + z krótkoterminowego przypominania do pamięci długoterminowej - [Memory configuration reference](/pl/reference/memory-config) — wszystkie opcje konfiguracji - [Compaction](/pl/concepts/compaction) — jak kompaktowanie współdziała z pamięcią diff --git a/docs/pl/concepts/model-providers.md b/docs/pl/concepts/model-providers.md index a2edfa37a..eb2509b15 100644 --- a/docs/pl/concepts/model-providers.md +++ b/docs/pl/concepts/model-providers.md @@ -1,14 +1,14 @@ --- read_when: - Potrzebujesz referencji konfiguracji modeli dla poszczególnych dostawców - - Chcesz zobaczyć przykładowe konfiguracje lub polecenia wdrożeniowe CLI dla dostawców modeli -summary: Przegląd dostawców modeli z przykładowymi konfiguracjami + przepływami CLI + - Chcesz zobaczyć przykładowe konfiguracje lub polecenia CLI do onboardingu dostawców modeli +summary: Przegląd dostawców modeli z przykładowymi konfiguracjami i przepływami CLI title: Dostawcy modeli x-i18n: - generated_at: "2026-04-08T06:02:51Z" + generated_at: "2026-04-09T01:29:30Z" model: gpt-5.4 provider: openai - source_hash: 558ac9e34b67fcc3dd6791a01bebc17e1c34152fa6c5611593d681e8cfa532d9 + source_hash: 53e3141256781002bbe1d7e7b78724a18d061fcf36a203baae04a091b8c9ea1b source_path: concepts/model-providers.md workflow: 15 --- @@ -16,25 +16,27 @@ x-i18n: # Dostawcy modeli Ta strona opisuje **dostawców LLM/modeli** (a nie kanały czatu, takie jak WhatsApp/Telegram). -Zasady wyboru modeli znajdziesz na stronie [/concepts/models](/pl/concepts/models). +Zasady wyboru modeli znajdziesz w [/concepts/models](/pl/concepts/models). ## Szybkie zasady - Referencje modeli używają formatu `provider/model` (przykład: `opencode/claude-opus-4-6`). - Jeśli ustawisz `agents.defaults.models`, stanie się to listą dozwolonych modeli. -- Narzędzia pomocnicze CLI: `openclaw onboard`, `openclaw models list`, `openclaw models set `. -- Zasady awaryjne środowiska uruchomieniowego, sondy cooldown oraz trwałość nadpisań sesji - są udokumentowane na stronie [/concepts/model-failover](/pl/concepts/model-failover). +- Pomocnicze polecenia CLI: `openclaw onboard`, `openclaw models list`, `openclaw models set `. +- Zasady awaryjnego działania w runtime, sondy cooldown oraz trwałość nadpisywania sesji + są udokumentowane w [/concepts/model-failover](/pl/concepts/model-failover). - `models.providers.*.models[].contextWindow` to natywne metadane modelu; - `models.providers.*.models[].contextTokens` to efektywny limit środowiska uruchomieniowego. + `models.providers.*.models[].contextTokens` to efektywny limit runtime. - Wtyczki dostawców mogą wstrzykiwać katalogi modeli przez `registerProvider({ catalog })`; - OpenClaw scala to wyjście z `models.providers` przed zapisaniem + OpenClaw scala ten wynik z `models.providers` przed zapisaniem `models.json`. -- Manifesty dostawców mogą deklarować `providerAuthEnvVars`, aby ogólne sondy - uwierzytelniania oparte na zmiennych środowiskowych nie musiały ładować środowiska uruchomieniowego wtyczki. Pozostała mapowanie zmiennych środowiskowych w rdzeniu - służy teraz tylko dostawcom spoza wtyczek/z rdzenia oraz kilku przypadkom - ogólnego priorytetu, takim jak wdrażanie Anthropic z preferencją klucza API. -- Wtyczki dostawców mogą również przejmować zachowanie dostawcy w środowisku uruchomieniowym przez +- Manifesty dostawców mogą deklarować `providerAuthEnvVars` oraz + `providerAuthAliases`, aby ogólne sondy uwierzytelniania opartego na env i warianty dostawców + nie musiały ładować runtime wtyczki. Pozostała mapowanie zmiennych env po stronie core + służy teraz tylko + dostawcom niebędącym wtyczkami/core oraz kilku przypadkom ogólnego priorytetu, takim + jak onboarding Anthropic z priorytetem klucza API. +- Wtyczki dostawców mogą także przejmować zachowanie dostawcy w runtime przez `normalizeModelId`, `normalizeTransport`, `normalizeConfig`, `applyNativeStreamingUsageCompat`, `resolveConfigApiKey`, `resolveSyntheticAuth`, `shouldDeferSyntheticProfileAuth`, @@ -52,8 +54,8 @@ Zasady wyboru modeli znajdziesz na stronie [/concepts/models](/pl/concepts/model `resolveDefaultThinkingLevel`, `applyConfigDefaults`, `isModernModelRef`, `prepareRuntimeAuth`, `resolveUsageAuth`, `fetchUsageSnapshot`, oraz `onModelSelected`. -- Uwaga: środowiskowe `capabilities` dostawcy to współdzielone metadane wykonawcy (rodzina dostawcy, - niuanse transkryptu/narzędzi, wskazówki dotyczące transportu/pamięci podręcznej). To nie jest +- Uwaga: `capabilities` runtime dostawcy to współdzielone metadane runnera (rodzina dostawcy, + specyfika transkryptu/narzędzi, wskazówki dotyczące transportu/cache). To nie jest to samo co [publiczny model możliwości](/pl/plugins/architecture#public-capability-model), który opisuje, co rejestruje wtyczka (wnioskowanie tekstowe, mowa itd.). @@ -64,204 +66,206 @@ ogólną pętlę wnioskowania. Typowy podział: -- `auth[].run` / `auth[].runNonInteractive`: dostawca odpowiada za przepływy wdrożenia/logowania - dla `openclaw onboard`, `openclaw models auth` i konfiguracji bezobsługowej -- `wizard.setup` / `wizard.modelPicker`: dostawca odpowiada za etykiety wyboru uwierzytelniania, - starsze aliasy, wskazówki dotyczące listy dozwolonych modeli podczas wdrażania oraz wpisy konfiguracji w selektorach wdrażania/modeli +- `auth[].run` / `auth[].runNonInteractive`: dostawca obsługuje onboarding/logowanie + dla `openclaw onboard`, `openclaw models auth` i konfiguracji bez interakcji +- `wizard.setup` / `wizard.modelPicker`: dostawca obsługuje etykiety wyboru uwierzytelniania, + stare aliasy, wskazówki dotyczące listy dozwolonych modeli podczas onboardingu oraz wpisy konfiguracji w selektorach onboardingu/modeli - `catalog`: dostawca pojawia się w `models.providers` -- `normalizeModelId`: dostawca normalizuje starsze/poglądowe identyfikatory modeli przed +- `normalizeModelId`: dostawca normalizuje stare/podglądowe identyfikatory modeli przed wyszukiwaniem lub kanonizacją -- `normalizeTransport`: dostawca normalizuje rodzinę transportu `api` / `baseUrl` - przed ogólnym składaniem modelu; OpenClaw sprawdza najpierw dopasowanego dostawcę, - a następnie inne wtyczki dostawców obsługujące hooki, aż jedna rzeczywiście zmieni - transport -- `normalizeConfig`: dostawca normalizuje konfigurację `models.providers.` zanim - środowisko uruchomieniowe jej użyje; OpenClaw sprawdza najpierw dopasowanego dostawcę, a potem inne - wtyczki dostawców obsługujące hooki, aż jedna rzeczywiście zmieni konfigurację. Jeśli żadna - wtyczka dostawcy nie przepisze konfiguracji, dołączone helpery rodziny Google nadal +- `normalizeTransport`: dostawca normalizuje `api` / `baseUrl` rodziny transportu + przed ogólnym składaniem modelu; OpenClaw najpierw sprawdza dopasowanego dostawcę, + a następnie inne wtyczki dostawców obsługujące hooki, dopóki jedna z nich rzeczywiście nie zmieni + transportu +- `normalizeConfig`: dostawca normalizuje konfigurację `models.providers.` przed + użyciem jej przez runtime; OpenClaw najpierw sprawdza dopasowanego dostawcę, a potem inne + wtyczki dostawców obsługujące hooki, dopóki jedna z nich rzeczywiście nie zmieni konfiguracji. Jeśli żaden + hook dostawcy nie przepisze konfiguracji, dołączone helpery rodziny Google nadal normalizują obsługiwane wpisy dostawców Google. -- `applyNativeStreamingUsageCompat`: dostawca stosuje przepisania zgodności natywnego użycia strumieniowania oparte na punktach końcowych dla dostawców konfiguracyjnych -- `resolveConfigApiKey`: dostawca rozwiązuje uwierzytelnianie znacznikami zmiennych środowiskowych dla dostawców konfiguracyjnych - bez wymuszania pełnego ładowania uwierzytelniania w środowisku uruchomieniowym. `amazon-bedrock` ma tutaj również - wbudowany resolver znaczników środowiskowych AWS, mimo że uwierzytelnianie środowiska uruchomieniowego Bedrock korzysta z +- `applyNativeStreamingUsageCompat`: dostawca stosuje zgodnościowe przepisania natywnego zużycia strumieniowego oparte na endpointach dla dostawców konfiguracyjnych +- `resolveConfigApiKey`: dostawca rozwiązuje uwierzytelnianie oparte na markerach env dla dostawców konfiguracyjnych + bez wymuszania pełnego ładowania auth runtime. `amazon-bedrock` ma tu także + wbudowany resolver markerów env AWS, mimo że uwierzytelnianie runtime Bedrock używa domyślnego łańcucha AWS SDK. -- `resolveSyntheticAuth`: dostawca może ujawniać dostępność uwierzytelniania lokalnego/samohostowanego lub innego - opartego na konfiguracji bez utrwalania jawnych sekretów -- `shouldDeferSyntheticProfileAuth`: dostawca może oznaczać zapisane syntetyczne profile-zastępniki - jako niższy priorytet niż uwierzytelnianie oparte na środowisku/konfiguracji -- `resolveDynamicModel`: dostawca akceptuje identyfikatory modeli, których nie ma jeszcze w lokalnym - statycznym katalogu -- `prepareDynamicModel`: dostawca potrzebuje odświeżenia metadanych przed ponowną próbą - dynamicznego rozwiązania modelu -- `normalizeResolvedModel`: dostawca wymaga przepisania transportu lub bazowego URL -- `contributeResolvedModelCompat`: dostawca wnosi flagi zgodności dla swoich - modeli dostawcy, nawet gdy docierają one przez inny zgodny transport -- `capabilities`: dostawca publikuje niuanse transkryptu/narzędzi/rodziny dostawcy -- `normalizeToolSchemas`: dostawca czyści schematy narzędzi, zanim zobaczy je - osadzony wykonawca -- `inspectToolSchemas`: dostawca ujawnia ostrzeżenia dotyczące schematu specyficzne dla transportu +- `resolveSyntheticAuth`: dostawca może ujawniać dostępność lokalnego/self-hosted lub innego + uwierzytelniania opartego na konfiguracji bez utrwalania sekretów w postaci jawnego tekstu +- `shouldDeferSyntheticProfileAuth`: dostawca może oznaczyć zapisane syntetyczne placeholdery profili + jako mające niższy priorytet niż uwierzytelnianie oparte na env/konfiguracji +- `resolveDynamicModel`: dostawca akceptuje identyfikatory modeli, których nie ma jeszcze + w lokalnym statycznym katalogu +- `prepareDynamicModel`: dostawca wymaga odświeżenia metadanych przed ponowną próbą + dynamicznego rozpoznania +- `normalizeResolvedModel`: dostawca wymaga przepisania transportu lub base URL +- `contributeResolvedModelCompat`: dostawca dodaje flagi zgodności dla swoich + modeli producenta nawet wtedy, gdy docierają przez inny zgodny transport +- `capabilities`: dostawca publikuje specyfikę transkryptu/narzędzi/rodziny dostawców +- `normalizeToolSchemas`: dostawca czyści schematy narzędzi, zanim zobaczy je osadzony + runner +- `inspectToolSchemas`: dostawca ujawnia ostrzeżenia dotyczące schematów specyficznych dla transportu po normalizacji -- `resolveReasoningOutputMode`: dostawca wybiera natywne lub tagowane - kontrakty wyjścia rozumowania -- `prepareExtraParams`: dostawca ustawia domyślnie lub normalizuje parametry żądania dla poszczególnych modeli -- `createStreamFn`: dostawca zastępuje zwykłą ścieżkę strumienia całkowicie +- `resolveReasoningOutputMode`: dostawca wybiera natywne lub otagowane + kontrakty wyjścia reasoning +- `prepareExtraParams`: dostawca ustawia wartości domyślne lub normalizuje parametry żądań dla danego modelu +- `createStreamFn`: dostawca zastępuje zwykłą ścieżkę strumieniowania całkowicie niestandardowym transportem -- `wrapStreamFn`: dostawca stosuje opakowania zgodności nagłówków/treści/modelu żądania -- `resolveTransportTurnState`: dostawca dostarcza natywne nagłówki lub metadane transportu - dla poszczególnych tur +- `wrapStreamFn`: dostawca stosuje opakowania zgodności żądania/nagłówków/body/modelu +- `resolveTransportTurnState`: dostawca dostarcza natywne nagłówki transportu + lub metadane dla pojedynczego turnu - `resolveWebSocketSessionPolicy`: dostawca dostarcza natywne nagłówki sesji WebSocket lub politykę cooldown sesji -- `createEmbeddingProvider`: dostawca przejmuje zachowanie osadzeń pamięci, gdy - należy ono do wtyczki dostawcy zamiast do przełącznika osadzeń rdzenia -- `formatApiKey`: dostawca formatuje zapisane profile uwierzytelniania do postaci - ciągu `apiKey` oczekiwanego przez transport w środowisku uruchomieniowym -- `refreshOAuth`: dostawca przejmuje odświeżanie OAuth, gdy współdzielone - mechanizmy odświeżania `pi-ai` nie wystarczają -- `buildAuthDoctorHint`: dostawca dołącza wskazówki naprawcze, gdy odświeżanie OAuth - kończy się niepowodzeniem -- `matchesContextOverflowError`: dostawca rozpoznaje błędy przepełnienia - okna kontekstu specyficzne dla dostawcy, których ogólne heurystyki by nie wykryły +- `createEmbeddingProvider`: dostawca przejmuje zachowanie embeddingów pamięci, gdy + powinno ono należeć do wtyczki dostawcy zamiast do przełącznika embeddingów w core +- `formatApiKey`: dostawca formatuje zapisane profile auth do postaci ciągu + `apiKey`, której oczekuje transport w runtime +- `refreshOAuth`: dostawca obsługuje odświeżanie OAuth, gdy współdzielone + refreshery `pi-ai` nie wystarczają +- `buildAuthDoctorHint`: dostawca dopisuje wskazówki naprawcze, gdy odświeżenie OAuth + się nie powiedzie +- `matchesContextOverflowError`: dostawca rozpoznaje błędy przepełnienia okna kontekstu + specyficzne dla dostawcy, które umknęłyby ogólnym heurystykom - `classifyFailoverReason`: dostawca mapuje surowe błędy transportu/API specyficzne dla dostawcy - na przyczyny przełączenia awaryjnego, takie jak limit szybkości lub przeciążenie -- `isCacheTtlEligible`: dostawca decyduje, które identyfikatory modeli upstream obsługują TTL pamięci podręcznej promptów -- `buildMissingAuthMessage`: dostawca zastępuje ogólny błąd magazynu uwierzytelniania + na przyczyny failover, takie jak limit szybkości lub przeciążenie +- `isCacheTtlEligible`: dostawca decyduje, które identyfikatory modeli upstream obsługują TTL cache promptów +- `buildMissingAuthMessage`: dostawca zastępuje ogólny błąd magazynu auth wskazówką odzyskiwania specyficzną dla dostawcy - `suppressBuiltInModel`: dostawca ukrywa nieaktualne wiersze upstream i może zwrócić - błąd należący do dostawcy w przypadku bezpośrednich niepowodzeń rozwiązywania -- `augmentModelCatalog`: dostawca dołącza syntetyczne/końcowe wiersze katalogu po - wykryciu i scaleniu konfiguracji -- `isBinaryThinking`: dostawca przejmuje UX binarnego myślenia włącz/wyłącz -- `supportsXHighThinking`: dostawca włącza wybrane modele do `xhigh` -- `resolveDefaultThinkingLevel`: dostawca przejmuje domyślną politykę `/think` dla + błąd należący do producenta przy bezpośrednich niepowodzeniach rozpoznania +- `augmentModelCatalog`: dostawca dopisuje syntetyczne/końcowe wiersze katalogu po + odkryciu i scaleniu konfiguracji +- `isBinaryThinking`: dostawca obsługuje UX binarnego thinking w trybie włącz/wyłącz +- `supportsXHighThinking`: dostawca włącza `xhigh` dla wybranych modeli +- `resolveDefaultThinkingLevel`: dostawca ustala domyślną politykę `/think` dla rodziny modeli -- `applyConfigDefaults`: dostawca stosuje globalne domyślne wartości specyficzne dla dostawcy - podczas materializacji konfiguracji na podstawie trybu uwierzytelniania, środowiska lub rodziny modeli -- `isModernModelRef`: dostawca przejmuje dopasowywanie preferowanych modeli live/smoke +- `applyConfigDefaults`: dostawca stosuje globalne wartości domyślne specyficzne dla dostawcy + podczas materializacji konfiguracji na podstawie trybu auth, env lub rodziny modeli +- `isModernModelRef`: dostawca obsługuje dopasowanie preferowanych modeli dla live/smoke - `prepareRuntimeAuth`: dostawca zamienia skonfigurowane poświadczenie na krótkożyjący - token środowiska uruchomieniowego -- `resolveUsageAuth`: dostawca rozwiązuje poświadczenia użycia/limitu dla `/usage` + token runtime +- `resolveUsageAuth`: dostawca rozwiązuje poświadczenia użycia/kwoty dla `/usage` i powiązanych powierzchni statusu/raportowania -- `fetchUsageSnapshot`: dostawca przejmuje pobieranie/parsowanie punktu końcowego użycia, podczas gdy - rdzeń nadal odpowiada za powłokę podsumowania i formatowanie -- `onModelSelected`: dostawca uruchamia skutki uboczne po wyborze modelu, takie jak - telemetria lub księgowanie sesji należące do dostawcy +- `fetchUsageSnapshot`: dostawca obsługuje pobieranie/parsing endpointu użycia, podczas gdy + core nadal obsługuje powłokę podsumowania i formatowanie +- `onModelSelected`: dostawca uruchamia efekty uboczne po wyborze modelu, takie jak + telemetria lub bookkeeping sesji należący do dostawcy -Aktualne dołączone przykłady: +Obecne dołączone przykłady: -- `anthropic`: zgodne w przód przejście awaryjne dla Claude 4.6, wskazówki naprawy uwierzytelniania, pobieranie z - punktu końcowego użycia, metadane TTL pamięci podręcznej/rodziny dostawcy oraz - globalne domyślne wartości konfiguracji zależne od uwierzytelniania -- `amazon-bedrock`: należące do dostawcy dopasowywanie przepełnienia kontekstu i klasyfikacja - przyczyn przełączenia awaryjnego dla specyficznych dla Bedrock błędów throttling/not-ready, plus - współdzielona rodzina odtwarzania `anthropic-by-model` dla ochrony zasad odtwarzania tylko-Claude +- `anthropic`: fallback zgodności przyszłej dla Claude 4.6, wskazówki naprawy auth, pobieranie + endpointu użycia, metadane cache-TTL/rodziny dostawców oraz globalne + wartości domyślne konfiguracji zależne od auth +- `amazon-bedrock`: należące do dostawcy dopasowanie przepełnienia kontekstu i klasyfikacja + przyczyn failover dla błędów throttle/not-ready specyficznych dla Bedrock, a także + współdzielona rodzina replay `anthropic-by-model` dla ochrony polityki replay wyłącznie dla Claude na ruchu Anthropic -- `anthropic-vertex`: ochrona zasad odtwarzania tylko-Claude na ruchu +- `anthropic-vertex`: zabezpieczenia polityki replay tylko dla Claude na ruchu `anthropic-message` - `openrouter`: przekazywane identyfikatory modeli, opakowania żądań, wskazówki dotyczące możliwości dostawcy, - sanityzacja sygnatur myślenia Gemini na ruchu proxy Gemini, wstrzykiwanie rozumowania proxy przez rodzinę strumienia `openrouter-thinking`, - przekazywanie metadanych routingu oraz polityka TTL pamięci podręcznej -- `github-copilot`: wdrażanie/logowanie urządzenia, zgodne w przód przejście awaryjne modeli, - wskazówki transkryptu myślenia Claude, wymiana tokenów środowiska uruchomieniowego oraz pobieranie z - punktu końcowego użycia -- `openai`: zgodne w przód przejście awaryjne dla GPT-5.4, bezpośrednia normalizacja transportu OpenAI, - wskazówki brakującego uwierzytelniania uwzględniające Codex, tłumienie Spark, syntetyczne - wiersze katalogu OpenAI/Codex, polityka myślenia/modeli live, normalizacja aliasów tokenów użycia - (`input` / `output` oraz rodziny `prompt` / `completion`), współdzielona rodzina strumienia `openai-responses-defaults` - dla natywnych opakowań OpenAI/Codex, metadane rodziny dostawcy, dołączona rejestracja dostawcy generowania obrazów + sanityzacja podpisów thought Gemini na ruchu proxy Gemini, proxy + wstrzykiwanie reasoning przez rodzinę strumienia `openrouter-thinking`, przekazywanie + metadanych routingu oraz polityka cache-TTL +- `github-copilot`: onboarding/logowanie urządzenia, fallback zgodności przyszłej modeli, + wskazówki transkryptu Claude-thinking, wymiana tokena runtime oraz pobieranie endpointu + użycia +- `openai`: fallback zgodności przyszłej dla GPT-5.4, bezpośrednia normalizacja + transportu OpenAI, wskazówki brakującego auth świadome Codex, tłumienie Spark, syntetyczne + wiersze katalogu OpenAI/Codex, polityka thinking/live-model, normalizacja aliasów tokenów użycia + (`input` / `output` oraz rodziny `prompt` / `completion`), współdzielona + rodzina strumienia `openai-responses-defaults` dla natywnych wrapperów OpenAI/Codex, + metadane rodziny dostawcy, dołączona rejestracja dostawcy generowania obrazów dla `gpt-image-1` oraz dołączona rejestracja dostawcy generowania wideo dla `sora-2` -- `google` i `google-gemini-cli`: zgodne w przód przejście awaryjne dla Gemini 3.1, - natywna walidacja odtwarzania Gemini, sanityzacja odtwarzania rozruchowego, tagowany - tryb wyjścia rozumowania, dopasowywanie nowoczesnych modeli, dołączona rejestracja dostawcy generowania obrazów +- `google` i `google-gemini-cli`: fallback zgodności przyszłej dla Gemini 3.1, + natywna walidacja replay Gemini, sanityzacja replay podczas bootstrapu, tryb + otagowanego wyjścia reasoning, dopasowanie nowoczesnych modeli, dołączona rejestracja dostawcy generowania obrazów dla modeli Gemini image-preview oraz dołączona - rejestracja dostawcy generowania wideo dla modeli Veo; OAuth Gemini CLI również - przejmuje formatowanie tokenów profilu uwierzytelniania, parsowanie tokenów użycia oraz pobieranie z - punktu końcowego limitów dla powierzchni użycia -- `moonshot`: współdzielony transport, normalizacja ładunku myślenia należąca do wtyczki -- `kilocode`: współdzielony transport, nagłówki żądań należące do wtyczki, normalizacja ładunku rozumowania, - sanityzacja sygnatur myślenia proxy-Gemini oraz polityka TTL pamięci podręcznej -- `zai`: zgodne w przód przejście awaryjne dla GLM-5, domyślne `tool_stream`, polityka TTL pamięci podręcznej, - polityka binarnego myślenia/modeli live oraz uwierzytelnianie użycia + pobieranie limitów; - nieznane identyfikatory `glm-5*` są syntetyzowane z dołączonego szablonu `glm-4.7` + rejestracja dostawcy generowania wideo dla modeli Veo; Gemini CLI OAuth także + obsługuje formatowanie tokenów profilu auth, parsowanie tokenów użycia oraz pobieranie endpointu kwot + dla powierzchni użycia +- `moonshot`: współdzielony transport, normalizacja payload thinking należąca do wtyczki +- `kilocode`: współdzielony transport, nagłówki żądań należące do wtyczki, normalizacja payload + reasoning, sanityzacja podpisów thought proxy-Gemini oraz polityka cache-TTL +- `zai`: fallback zgodności przyszłej dla GLM-5, domyślne `tool_stream`, polityka cache-TTL, + polityka binarnego thinking/live-model oraz auth użycia + pobieranie kwot; + nieznane identyfikatory `glm-5*` są syntetyzowane na podstawie dołączonego szablonu `glm-4.7` - `xai`: natywna normalizacja transportu Responses, przepisania aliasów `/fast` dla - szybkich wariantów Grok, domyślne `tool_stream`, porządkowanie schematu narzędzi / - ładunku rozumowania specyficzne dla xAI oraz dołączona rejestracja dostawcy generowania wideo + szybkich wariantów Grok, domyślne `tool_stream`, czyszczenie schematów narzędzi / + payload reasoning specyficzne dla xAI oraz dołączona rejestracja dostawcy generowania wideo dla `grok-imagine-video` - `mistral`: metadane możliwości należące do wtyczki - `opencode` i `opencode-go`: metadane możliwości należące do wtyczki oraz - sanityzacja sygnatur myślenia proxy-Gemini -- `alibaba`: należący do wtyczki katalog generowania wideo dla bezpośrednich referencji modeli Wan + sanityzacja podpisów thought proxy-Gemini +- `alibaba`: katalog wideo należący do wtyczki dla bezpośrednich referencji modeli Wan takich jak `alibaba/wan2.6-t2v` - `byteplus`: katalogi należące do wtyczki oraz dołączona rejestracja dostawcy generowania wideo - dla modeli Seedance text-to-video/image-to-video -- `fal`: dołączona rejestracja dostawcy generowania wideo dla hostowanych modeli innych firm - oraz rejestracja dostawcy generowania obrazów dla modeli FLUX, plus dołączona + dla modeli text-to-video/image-to-video Seedance +- `fal`: dołączona rejestracja dostawcy generowania wideo dla hostowanych modeli wideo innych firm + oraz rejestracja dostawcy generowania obrazów dla modeli obrazów FLUX, a także dołączona rejestracja dostawcy generowania wideo dla hostowanych modeli wideo innych firm - `cloudflare-ai-gateway`, `huggingface`, `kimi`, `nvidia`, `qianfan`, `stepfun`, `synthetic`, `venice`, `vercel-ai-gateway` i `volcengine`: tylko katalogi należące do wtyczki - `qwen`: katalogi należące do wtyczki dla modeli tekstowych oraz współdzielone - rejestracje dostawców rozumienia mediów i generowania wideo dla jego - powierzchni multimodalnych; generowanie wideo Qwen korzysta ze standardowych punktów końcowych wideo DashScope + rejestracje dostawców media-understanding i generowania wideo dla ich + powierzchni multimodalnych; generowanie wideo Qwen używa standardowych endpointów DashScope video z dołączonymi modelami Wan, takimi jak `wan2.6-t2v` i `wan2.7-r2v` -- `runway`: należąca do wtyczki rejestracja dostawcy generowania wideo dla natywnych - modeli zadaniowych Runway, takich jak `gen4.5` +- `runway`: rejestracja dostawcy generowania wideo należąca do wtyczki dla natywnych + modeli opartych na zadaniach Runway, takich jak `gen4.5` - `minimax`: katalogi należące do wtyczki, dołączona rejestracja dostawcy generowania wideo - dla modeli Hailuo, dołączona rejestracja dostawcy generowania obrazów - dla `image-01`, hybrydowy wybór zasad odtwarzania Anthropic/OpenAI - oraz logika uwierzytelniania/migawki użycia + dla modeli wideo Hailuo, dołączona rejestracja dostawcy generowania obrazów + dla `image-01`, hybrydowy wybór polityki replay Anthropic/OpenAI + oraz logika auth/snapshot użycia - `together`: katalogi należące do wtyczki oraz dołączona rejestracja dostawcy generowania wideo dla modeli wideo Wan -- `xiaomi`: katalogi należące do wtyczki oraz logika uwierzytelniania/migawki użycia +- `xiaomi`: katalogi należące do wtyczki oraz logika auth/snapshot użycia -Dołączona wtyczka `openai` obsługuje teraz oba identyfikatory dostawców: `openai` i +Dołączona wtyczka `openai` obsługuje teraz oba identyfikatory dostawcy: `openai` i `openai-codex`. -To obejmuje dostawców, którzy nadal mieszczą się w zwykłych transportach OpenClaw. Dostawca, -który potrzebuje całkowicie niestandardowego wykonawcy żądań, to osobna, głębsza powierzchnia -rozszerzeń. +To obejmuje dostawców, którzy nadal mieszczą się w normalnych transportach OpenClaw. Dostawca, +który potrzebuje całkowicie niestandardowego wykonawcy żądań, to osobna, głębsza +powierzchnia rozszerzeń. ## Rotacja kluczy API -- Obsługuje ogólną rotację dostawcy dla wybranych dostawców. +- Obsługuje ogólną rotację dla wybranych dostawców. - Skonfiguruj wiele kluczy przez: - - `OPENCLAW_LIVE__KEY` (pojedyncze aktywne nadpisanie, najwyższy priorytet) + - `OPENCLAW_LIVE__KEY` (pojedyncze nadpisanie live, najwyższy priorytet) - `_API_KEYS` (lista rozdzielana przecinkami lub średnikami) - - `_API_KEY` (klucz podstawowy) + - `_API_KEY` (główny klucz) - `_API_KEY_*` (lista numerowana, np. `_API_KEY_1`) -- Dla dostawców Google `GOOGLE_API_KEY` jest również uwzględniany jako rozwiązanie awaryjne. -- Kolejność wyboru kluczy zachowuje priorytet i usuwa zduplikowane wartości. -- Żądania są ponawiane z następnym kluczem tylko w odpowiedzi na ograniczenia szybkości - (na przykład `429`, `rate_limit`, `quota`, `resource exhausted`, `Too many +- Dla dostawców Google jako fallback uwzględniany jest także `GOOGLE_API_KEY`. +- Kolejność wyboru kluczy zachowuje priorytet i deduplikuje wartości. +- Żądania są ponawiane z następnym kluczem tylko przy odpowiedziach z limitem szybkości (na + przykład `429`, `rate_limit`, `quota`, `resource exhausted`, `Too many concurrent requests`, `ThrottlingException`, `concurrency limit reached`, - `workers_ai ... quota limit exceeded` lub okresowe komunikaty o limicie użycia). -- Błędy niezwiązane z limitem szybkości kończą się natychmiastowym niepowodzeniem; nie podejmuje się rotacji kluczy. + `workers_ai ... quota limit exceeded` lub okresowych komunikatach o limicie użycia). +- Błędy inne niż limit szybkości kończą się natychmiast; nie podejmuje się rotacji kluczy. - Gdy wszystkie kandydackie klucze zawiodą, zwracany jest końcowy błąd z ostatniej próby. ## Wbudowani dostawcy (katalog pi-ai) OpenClaw jest dostarczany z katalogiem pi‑ai. Ci dostawcy nie wymagają -konfiguracji `models.providers`; wystarczy ustawić uwierzytelnianie i wybrać model. +konfiguracji `models.providers`; wystarczy ustawić auth i wybrać model. ### OpenAI - Dostawca: `openai` -- Uwierzytelnianie: `OPENAI_API_KEY` -- Opcjonalna rotacja: `OPENAI_API_KEYS`, `OPENAI_API_KEY_1`, `OPENAI_API_KEY_2`, plus `OPENCLAW_LIVE_OPENAI_KEY` (pojedyncze nadpisanie) +- Auth: `OPENAI_API_KEY` +- Opcjonalna rotacja: `OPENAI_API_KEYS`, `OPENAI_API_KEY_1`, `OPENAI_API_KEY_2`, oraz `OPENCLAW_LIVE_OPENAI_KEY` (pojedyncze nadpisanie) - Przykładowe modele: `openai/gpt-5.4`, `openai/gpt-5.4-pro` - CLI: `openclaw onboard --auth-choice openai-api-key` -- Domyślny transport to `auto` (najpierw WebSocket, awaryjnie SSE) +- Domyślny transport to `auto` (najpierw WebSocket, fallback do SSE) - Nadpisanie dla modelu przez `agents.defaults.models["openai/"].params.transport` (`"sse"`, `"websocket"` lub `"auto"`) -- Rozgrzewanie WebSocket OpenAI Responses jest domyślnie włączone przez `params.openaiWsWarmup` (`true`/`false`) -- Priorytetowe przetwarzanie OpenAI można włączyć przez `agents.defaults.models["openai/"].params.serviceTier` -- `/fast` i `params.fastMode` mapują bezpośrednie żądania Responses `openai/*` na `service_tier=priority` w `api.openai.com` -- Użyj `params.serviceTier`, jeśli chcesz jawnego poziomu zamiast współdzielonego przełącznika `/fast` +- Rozgrzewanie OpenAI Responses WebSocket jest domyślnie włączone przez `params.openaiWsWarmup` (`true`/`false`) +- Przetwarzanie priorytetowe OpenAI można włączyć przez `agents.defaults.models["openai/"].params.serviceTier` +- `/fast` i `params.fastMode` mapują bezpośrednie żądania Responses `openai/*` do `service_tier=priority` na `api.openai.com` +- Użyj `params.serviceTier`, jeśli chcesz jawnie ustawić poziom zamiast używać współdzielonego przełącznika `/fast` - Ukryte nagłówki atrybucji OpenClaw (`originator`, `version`, `User-Agent`) są stosowane tylko do natywnego ruchu OpenAI do `api.openai.com`, a nie - do ogólnych serwerów proxy zgodnych z OpenAI -- Natywne trasy OpenAI zachowują również `store` w Responses, wskazówki pamięci podręcznej promptów oraz - kształtowanie ładunku zgodności rozumowania OpenAI; trasy proxy tego nie robią -- `openai/gpt-5.3-codex-spark` jest celowo ukryty w OpenClaw, ponieważ aktywne API OpenAI go odrzuca; Spark jest traktowany jako tylko-Codex + do ogólnych proxy zgodnych z OpenAI +- Natywne trasy OpenAI zachowują też `store` dla Responses, wskazówki cache promptów oraz + kształtowanie payload zgodności reasoning OpenAI; trasy proxy tego nie robią +- `openai/gpt-5.3-codex-spark` jest celowo ukryty w OpenClaw, ponieważ live API OpenAI go odrzuca; Spark jest traktowany wyłącznie jako Codex ```json5 { @@ -272,13 +276,13 @@ konfiguracji `models.providers`; wystarczy ustawić uwierzytelnianie i wybrać m ### Anthropic - Dostawca: `anthropic` -- Uwierzytelnianie: `ANTHROPIC_API_KEY` -- Opcjonalna rotacja: `ANTHROPIC_API_KEYS`, `ANTHROPIC_API_KEY_1`, `ANTHROPIC_API_KEY_2`, plus `OPENCLAW_LIVE_ANTHROPIC_KEY` (pojedyncze nadpisanie) +- Auth: `ANTHROPIC_API_KEY` +- Opcjonalna rotacja: `ANTHROPIC_API_KEYS`, `ANTHROPIC_API_KEY_1`, `ANTHROPIC_API_KEY_2`, oraz `OPENCLAW_LIVE_ANTHROPIC_KEY` (pojedyncze nadpisanie) - Przykładowy model: `anthropic/claude-opus-4-6` - CLI: `openclaw onboard --auth-choice apiKey` -- Bezpośrednie publiczne żądania Anthropic obsługują współdzielony przełącznik `/fast` i `params.fastMode`, w tym ruch uwierzytelniony kluczem API i OAuth wysyłany do `api.anthropic.com`; OpenClaw mapuje to na Anthropic `service_tier` (`auto` vs `standard_only`) -- Uwaga dotycząca 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 zatwierdzone dla tej integracji, chyba że Anthropic opublikuje nową politykę. -- Token konfiguracji Anthropic pozostaje dostępną obsługiwaną ścieżką tokena OpenClaw, ale OpenClaw preferuje teraz ponowne użycie Claude CLI i `claude -p`, gdy są dostępne. +- Bezpośrednie publiczne żądania Anthropic obsługują współdzielony przełącznik `/fast` i `params.fastMode`, zarówno dla ruchu uwierzytelnionego kluczem API, jak i OAuth wysyłanego do `api.anthropic.com`; OpenClaw mapuje to na `service_tier` Anthropic (`auto` vs `standard_only`) +- Uwaga dotycząca 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 dozwolone dla tej integracji, chyba że Anthropic opublikuje nową politykę. +- Token konfiguracyjny Anthropic pozostaje dostępną i wspieraną ścieżką tokenu OpenClaw, ale OpenClaw teraz preferuje ponowne użycie Claude CLI i `claude -p`, gdy są dostępne. ```json5 { @@ -289,19 +293,19 @@ konfiguracji `models.providers`; wystarczy ustawić uwierzytelnianie i wybrać m ### OpenAI Code (Codex) - Dostawca: `openai-codex` -- Uwierzytelnianie: OAuth (ChatGPT) +- Auth: OAuth (ChatGPT) - Przykładowy model: `openai-codex/gpt-5.4` - CLI: `openclaw onboard --auth-choice openai-codex` lub `openclaw models auth login --provider openai-codex` -- Domyślny transport to `auto` (najpierw WebSocket, awaryjnie SSE) +- Domyślny transport to `auto` (najpierw WebSocket, fallback do SSE) - Nadpisanie dla modelu przez `agents.defaults.models["openai-codex/"].params.transport` (`"sse"`, `"websocket"` lub `"auto"`) -- `params.serviceTier` jest również przekazywane w natywnych żądaniach Codex Responses (`chatgpt.com/backend-api`) +- `params.serviceTier` jest także przekazywane w natywnych żądaniach Codex Responses (`chatgpt.com/backend-api`) - Ukryte nagłówki atrybucji OpenClaw (`originator`, `version`, `User-Agent`) są dołączane tylko do natywnego ruchu Codex do - `chatgpt.com/backend-api`, a nie do ogólnych serwerów proxy zgodnych z OpenAI + `chatgpt.com/backend-api`, a nie do ogólnych proxy zgodnych z OpenAI - Współdzieli ten sam przełącznik `/fast` i konfigurację `params.fastMode` co bezpośrednie `openai/*`; OpenClaw mapuje to na `service_tier=priority` -- `openai-codex/gpt-5.3-codex-spark` pozostaje dostępny, gdy katalog OAuth Codex go ujawnia; zależne od uprawnień -- `openai-codex/gpt-5.4` zachowuje natywne `contextWindow = 1050000` i domyślne środowiskowe `contextTokens = 272000`; nadpisz limit środowiska przez `models.providers.openai-codex.models[].contextTokens` -- Uwaga dotycząca zasad: OAuth OpenAI Codex jest jawnie obsługiwany dla zewnętrznych narzędzi/przepływów pracy, takich jak OpenClaw. +- `openai-codex/gpt-5.3-codex-spark` pozostaje dostępny, gdy katalog OAuth Codex go udostępnia; zależy od uprawnień +- `openai-codex/gpt-5.4` zachowuje natywne `contextWindow = 1050000` i domyślne runtime `contextTokens = 272000`; nadpisz limit runtime przez `models.providers.openai-codex.models[].contextTokens` +- Uwaga dotycząca polityki: OAuth OpenAI Codex jest jawnie wspierany dla zewnętrznych narzędzi/przepływów pracy, takich jak OpenClaw. ```json5 { @@ -323,15 +327,15 @@ konfiguracji `models.providers`; wystarczy ustawić uwierzytelnianie i wybrać m ### Inne hostowane opcje w stylu subskrypcyjnym -- [Qwen Cloud](/pl/providers/qwen): powierzchnia dostawcy Qwen Cloud oraz mapowanie punktów końcowych Alibaba DashScope i Coding Plan -- [MiniMax](/pl/providers/minimax): dostęp OAuth lub kluczem API do MiniMax Coding Plan -- [GLM Models](/pl/providers/glm): Z.AI Coding Plan lub ogólne punkty końcowe API +- [Qwen Cloud](/pl/providers/qwen): powierzchnia dostawcy Qwen Cloud oraz mapowanie endpointów Alibaba DashScope i Coding Plan +- [MiniMax](/pl/providers/minimax): dostęp przez OAuth MiniMax Coding Plan lub klucz API +- [GLM Models](/pl/providers/glm): Z.AI Coding Plan lub ogólne endpointy API ### OpenCode -- Uwierzytelnianie: `OPENCODE_API_KEY` (lub `OPENCODE_ZEN_API_KEY`) -- Dostawca środowiska uruchomieniowego Zen: `opencode` -- Dostawca środowiska uruchomieniowego Go: `opencode-go` +- Auth: `OPENCODE_API_KEY` (lub `OPENCODE_ZEN_API_KEY`) +- Dostawca runtime Zen: `opencode` +- Dostawca runtime Go: `opencode-go` - Przykładowe modele: `opencode/claude-opus-4-6`, `opencode-go/kimi-k2.5` - CLI: `openclaw onboard --auth-choice opencode-zen` lub `openclaw onboard --auth-choice opencode-go` @@ -344,88 +348,87 @@ konfiguracji `models.providers`; wystarczy ustawić uwierzytelnianie i wybrać m ### Google Gemini (klucz API) - Dostawca: `google` -- Uwierzytelnianie: `GEMINI_API_KEY` -- Opcjonalna rotacja: `GEMINI_API_KEYS`, `GEMINI_API_KEY_1`, `GEMINI_API_KEY_2`, rozwiązanie awaryjne `GOOGLE_API_KEY` oraz `OPENCLAW_LIVE_GEMINI_KEY` (pojedyncze nadpisanie) +- Auth: `GEMINI_API_KEY` +- Opcjonalna rotacja: `GEMINI_API_KEYS`, `GEMINI_API_KEY_1`, `GEMINI_API_KEY_2`, fallback `GOOGLE_API_KEY` oraz `OPENCLAW_LIVE_GEMINI_KEY` (pojedyncze nadpisanie) - Przykładowe modele: `google/gemini-3.1-pro-preview`, `google/gemini-3-flash-preview` - Zgodność: starsza konfiguracja OpenClaw używająca `google/gemini-3.1-flash-preview` jest normalizowana do `google/gemini-3-flash-preview` - CLI: `openclaw onboard --auth-choice gemini-api-key` -- Bezpośrednie uruchomienia Gemini akceptują również `agents.defaults.models["google/"].params.cachedContent` +- Bezpośrednie uruchomienia Gemini akceptują także `agents.defaults.models["google/"].params.cachedContent` (lub starsze `cached_content`) do przekazania natywnego dla dostawcy - uchwytu `cachedContents/...`; trafienia pamięci podręcznej Gemini są widoczne jako OpenClaw `cacheRead` + uchwytu `cachedContents/...`; trafienia cache Gemini są ujawniane jako OpenClaw `cacheRead` ### Google Vertex i Gemini CLI - Dostawcy: `google-vertex`, `google-gemini-cli` -- Uwierzytelnianie: Vertex używa gcloud ADC; Gemini CLI używa własnego przepływu OAuth -- Uwaga: OAuth Gemini CLI w OpenClaw to nieoficjalna integracja. Niektórzy użytkownicy zgłaszali ograniczenia kont Google po użyciu klientów innych firm. Zapoznaj się z warunkami Google i użyj niekrytycznego konta, jeśli zdecydujesz się kontynuować. -- OAuth Gemini CLI jest dostarczany jako część dołączonej wtyczki `google`. +- Auth: Vertex używa gcloud ADC; Gemini CLI używa własnego przepływu OAuth +- Ostrzeżenie: OAuth Gemini CLI w OpenClaw to nieoficjalna integracja. Niektórzy użytkownicy zgłaszali ograniczenia kont Google po używaniu klientów zewnętrznych. Zapoznaj się z warunkami Google i używaj konta niekrytycznego, jeśli zdecydujesz się kontynuować. +- OAuth Gemini CLI jest dostarczane jako część dołączonej wtyczki `google`. - Najpierw zainstaluj Gemini CLI: - `brew install gemini-cli` - lub `npm install -g @google/gemini-cli` - Włącz: `openclaw plugins enable google` - - Zaloguj się: `openclaw models auth login --provider google-gemini-cli --set-default` - - Model domyślny: `google-gemini-cli/gemini-3-flash-preview` - - Uwaga: **nie** wklejasz identyfikatora klienta ani sekretu do `openclaw.json`. Przepływ logowania CLI zapisuje - tokeny w profilach uwierzytelniania na hoście bramy. - - Jeśli żądania nie działają po zalogowaniu, ustaw `GOOGLE_CLOUD_PROJECT` lub `GOOGLE_CLOUD_PROJECT_ID` na hoście bramy. - - Odpowiedzi JSON Gemini CLI są parsowane z `response`; użycie awaryjnie korzysta z + - Zaloguj: `openclaw models auth login --provider google-gemini-cli --set-default` + - Domyślny model: `google-gemini-cli/gemini-3-flash-preview` + - Uwaga: **nie** wklejasz client id ani secret do `openclaw.json`. Przepływ logowania CLI zapisuje + tokeny w profilach auth na hoście gateway. + - Jeśli żądania nie działają po zalogowaniu, ustaw `GOOGLE_CLOUD_PROJECT` lub `GOOGLE_CLOUD_PROJECT_ID` na hoście gateway. + - Odpowiedzi JSON Gemini CLI są parsowane z `response`; użycie korzysta z fallback do `stats`, a `stats.cached` jest normalizowane do OpenClaw `cacheRead`. ### Z.AI (GLM) - Dostawca: `zai` -- Uwierzytelnianie: `ZAI_API_KEY` +- Auth: `ZAI_API_KEY` - Przykładowy model: `zai/glm-5.1` - CLI: `openclaw onboard --auth-choice zai-api-key` - Aliasy: `z.ai/*` i `z-ai/*` są normalizowane do `zai/*` - - `zai-api-key` automatycznie wykrywa pasujący punkt końcowy Z.AI; `zai-coding-global`, `zai-coding-cn`, `zai-global` i `zai-cn` wymuszają określoną powierzchnię + - `zai-api-key` automatycznie wykrywa pasujący endpoint Z.AI; `zai-coding-global`, `zai-coding-cn`, `zai-global` i `zai-cn` wymuszają konkretną powierzchnię ### Vercel AI Gateway - Dostawca: `vercel-ai-gateway` -- Uwierzytelnianie: `AI_GATEWAY_API_KEY` +- Auth: `AI_GATEWAY_API_KEY` - Przykładowy model: `vercel-ai-gateway/anthropic/claude-opus-4.6` - CLI: `openclaw onboard --auth-choice ai-gateway-api-key` ### Kilo Gateway - Dostawca: `kilocode` -- Uwierzytelnianie: `KILOCODE_API_KEY` +- Auth: `KILOCODE_API_KEY` - Przykładowy model: `kilocode/kilo/auto` - CLI: `openclaw onboard --auth-choice kilocode-api-key` -- Bazowy URL: `https://api.kilo.ai/api/gateway/` -- Statyczny katalog awaryjny zawiera `kilocode/kilo/auto`; aktywne - wykrywanie `https://api.kilo.ai/api/gateway/models` może dalej rozszerzyć katalog - środowiska uruchomieniowego. +- Base URL: `https://api.kilo.ai/api/gateway/` +- Statyczny katalog fallback zawiera `kilocode/kilo/auto`; live + odkrywanie pod `https://api.kilo.ai/api/gateway/models` może dalej rozszerzać katalog runtime. - Dokładny routing upstream za `kilocode/kilo/auto` należy do Kilo Gateway, - a nie jest zakodowany na stałe w OpenClaw. + a nie jest zakodowany na sztywno w OpenClaw. -Szczegóły konfiguracji znajdziesz na stronie [/providers/kilocode](/pl/providers/kilocode). +Szczegóły konfiguracji znajdziesz w [/providers/kilocode](/pl/providers/kilocode). ### Inne dołączone wtyczki dostawców - OpenRouter: `openrouter` (`OPENROUTER_API_KEY`) - Przykładowy model: `openrouter/auto` - OpenClaw stosuje udokumentowane nagłówki atrybucji aplikacji OpenRouter tylko wtedy, gdy - żądanie rzeczywiście trafia do `openrouter.ai` + żądanie faktycznie trafia do `openrouter.ai` - Specyficzne dla OpenRouter znaczniki Anthropic `cache_control` są podobnie ograniczone do zweryfikowanych tras OpenRouter, a nie dowolnych adresów proxy - OpenRouter pozostaje na ścieżce proxy zgodnej z OpenAI, więc natywne - kształtowanie żądań tylko dla OpenAI (`serviceTier`, `store` w Responses, - wskazówki pamięci podręcznej promptów, ładunki zgodności rozumowania OpenAI) nie jest przekazywane -- Referencje OpenRouter oparte na Gemini zachowują tylko sanityzację sygnatur myślenia proxy-Gemini; - natywna walidacja odtwarzania Gemini i przepisania rozruchowe pozostają wyłączone + kształtowanie żądań tylko dla OpenAI (`serviceTier`, `store` dla Responses, + wskazówki cache promptów, payloady zgodności reasoning OpenAI) nie jest przekazywane +- Referencje OpenRouter oparte na Gemini zachowują tylko sanityzację podpisów thought proxy-Gemini; + natywna walidacja replay Gemini i przepisania bootstrap pozostają wyłączone - Kilo Gateway: `kilocode` (`KILOCODE_API_KEY`) - Przykładowy model: `kilocode/kilo/auto` -- Referencje Kilo oparte na Gemini zachowują tę samą ścieżkę sanityzacji sygnatur myślenia - proxy-Gemini; `kilocode/kilo/auto` i inne wskazówki proxy bez obsługi rozumowania - pomijają wstrzykiwanie rozumowania proxy +- Referencje Kilo oparte na Gemini zachowują tę samą ścieżkę sanityzacji podpisów thought + proxy-Gemini; `kilocode/kilo/auto` i inne wskazówki proxy bez obsługi reasoning + pomijają wstrzykiwanie reasoning do proxy - MiniMax: `minimax` (klucz API) i `minimax-portal` (OAuth) -- Uwierzytelnianie: `MINIMAX_API_KEY` dla `minimax`; `MINIMAX_OAUTH_TOKEN` lub `MINIMAX_API_KEY` dla `minimax-portal` +- Auth: `MINIMAX_API_KEY` dla `minimax`; `MINIMAX_OAUTH_TOKEN` lub `MINIMAX_API_KEY` dla `minimax-portal` - Przykładowy model: `minimax/MiniMax-M2.7` lub `minimax-portal/MiniMax-M2.7` -- Wdrożenie MiniMax/konfiguracja klucza API zapisuje jawne definicje modeli M2.7 z - `input: ["text", "image"]`; dołączony katalog dostawcy zachowuje referencje czatu - jako tylko tekstowe, dopóki ta konfiguracja dostawcy nie zostanie zmaterializowana +- Onboarding MiniMax/konfiguracja klucza API zapisuje jawne definicje modeli M2.7 z + `input: ["text", "image"]`; dołączony katalog dostawcy utrzymuje referencje czatu + jako tylko tekstowe, dopóki konfiguracja tego dostawcy nie zostanie zmaterializowana - Moonshot: `moonshot` (`MOONSHOT_API_KEY`) - Przykładowy model: `moonshot/kimi-k2.5` - Kimi Coding: `kimi` (`KIMI_API_KEY` lub `KIMICODE_API_KEY`) @@ -453,7 +456,7 @@ Szczegóły konfiguracji znajdziesz na stronie [/providers/kilocode](/pl/provide - xAI: `xai` (`XAI_API_KEY`) - Natywne dołączone żądania xAI używają ścieżki xAI Responses - `/fast` lub `params.fastMode: true` przepisuje `grok-3`, `grok-3-mini`, - `grok-4` i `grok-4-0709` na ich warianty `*-fast` + `grok-4` i `grok-4-0709` do ich wariantów `*-fast` - `tool_stream` jest domyślnie włączone; ustaw `agents.defaults.models["xai/"].params.tool_stream` na `false`, aby je wyłączyć @@ -463,27 +466,27 @@ Szczegóły konfiguracji znajdziesz na stronie [/providers/kilocode](/pl/provide - Groq: `groq` (`GROQ_API_KEY`) - Cerebras: `cerebras` (`CEREBRAS_API_KEY`) - Modele GLM w Cerebras używają identyfikatorów `zai-glm-4.7` i `zai-glm-4.6`. - - Bazowy URL zgodny z OpenAI: `https://api.cerebras.ai/v1`. + - Base URL zgodny z OpenAI: `https://api.cerebras.ai/v1`. - GitHub Copilot: `github-copilot` (`COPILOT_GITHUB_TOKEN` / `GH_TOKEN` / `GITHUB_TOKEN`) - Przykładowy model Hugging Face Inference: `huggingface/deepseek-ai/DeepSeek-R1`; CLI: `openclaw onboard --auth-choice huggingface-api-key`. Zobacz [Hugging Face (Inference)](/pl/providers/huggingface). -## Dostawcy przez `models.providers` (niestandardowy/bazowy URL) +## Dostawcy przez `models.providers` (własny/base URL) -Użyj `models.providers` (lub `models.json`), aby dodać **niestandardowych** dostawców lub +Użyj `models.providers` (lub `models.json`), aby dodać **własnych** dostawców lub proxy zgodne z OpenAI/Anthropic. -Wiele z poniższych dołączonych wtyczek dostawców publikuje już domyślny katalog. +Wiele dołączonych poniżej wtyczek dostawców publikuje już domyślny katalog. Używaj jawnych wpisów `models.providers.` tylko wtedy, gdy chcesz nadpisać -domyślny bazowy URL, nagłówki lub listę modeli. +domyślny base URL, nagłówki lub listę modeli. ### Moonshot AI (Kimi) -Moonshot jest dostarczany jako dołączona wtyczka dostawcy. Domyślnie używaj wbudowanego dostawcy, -a jawny wpis `models.providers.moonshot` dodawaj tylko wtedy, gdy -musisz nadpisać bazowy URL lub metadane modelu: +Moonshot jest dostarczany jako dołączona wtyczka dostawcy. Używaj wbudowanego dostawcy +domyślnie i dodawaj jawny wpis `models.providers.moonshot` tylko wtedy, gdy +musisz nadpisać base URL lub metadane modelu: - Dostawca: `moonshot` -- Uwierzytelnianie: `MOONSHOT_API_KEY` +- Auth: `MOONSHOT_API_KEY` - Przykładowy model: `moonshot/kimi-k2.5` - CLI: `openclaw onboard --auth-choice moonshot-api-key` lub `openclaw onboard --auth-choice moonshot-api-key-cn` @@ -519,10 +522,10 @@ Identyfikatory modeli Kimi K2: ### Kimi Coding -Kimi Coding używa zgodnego z Anthropic punktu końcowego Moonshot AI: +Kimi Coding używa endpointu Moonshot AI zgodnego z Anthropic: - Dostawca: `kimi` -- Uwierzytelnianie: `KIMI_API_KEY` +- Auth: `KIMI_API_KEY` - Przykładowy model: `kimi/kimi-code` ```json5 @@ -534,14 +537,14 @@ Kimi Coding używa zgodnego z Anthropic punktu końcowego Moonshot AI: } ``` -Starszy `kimi/k2p5` pozostaje akceptowanym identyfikatorem modelu ze względów zgodności. +Starszy `kimi/k2p5` pozostaje akceptowanym identyfikatorem modelu dla zgodności. ### Volcano Engine (Doubao) Volcano Engine (火山引擎) zapewnia dostęp do Doubao i innych modeli w Chinach. -- Dostawca: `volcengine` (kodowanie: `volcengine-plan`) -- Uwierzytelnianie: `VOLCANO_ENGINE_API_KEY` +- Dostawca: `volcengine` (coding: `volcengine-plan`) +- Auth: `VOLCANO_ENGINE_API_KEY` - Przykładowy model: `volcengine-plan/ark-code-latest` - CLI: `openclaw onboard --auth-choice volcengine-api-key` @@ -553,12 +556,12 @@ Volcano Engine (火山引擎) zapewnia dostęp do Doubao i innych modeli w China } ``` -Wdrożenie domyślnie używa powierzchni coding, ale ogólny katalog `volcengine/*` -jest rejestrowany w tym samym czasie. +Onboarding domyślnie używa powierzchni coding, ale ogólny katalog `volcengine/*` +jest rejestrowany jednocześnie. -W selektorach modeli wdrażania/konfiguracji wybór uwierzytelniania Volcengine preferuje zarówno +W selektorach modeli onboarding/configure model wybór auth Volcengine preferuje zarówno wiersze `volcengine/*`, jak i `volcengine-plan/*`. Jeśli te modele nie są jeszcze załadowane, -OpenClaw wraca do nieprzefiltrowanego katalogu zamiast pokazywać pusty +OpenClaw wraca do niefiltrowanego katalogu zamiast pokazywać pusty selektor ograniczony do dostawcy. Dostępne modele: @@ -577,12 +580,12 @@ Modele coding (`volcengine-plan`): - `volcengine-plan/kimi-k2-thinking` - `volcengine-plan/glm-4.7` -### BytePlus (międzynarodowy) +### BytePlus (International) BytePlus ARK zapewnia międzynarodowym użytkownikom dostęp do tych samych modeli co Volcano Engine. -- Dostawca: `byteplus` (kodowanie: `byteplus-plan`) -- Uwierzytelnianie: `BYTEPLUS_API_KEY` +- Dostawca: `byteplus` (coding: `byteplus-plan`) +- Auth: `BYTEPLUS_API_KEY` - Przykładowy model: `byteplus-plan/ark-code-latest` - CLI: `openclaw onboard --auth-choice byteplus-api-key` @@ -594,12 +597,12 @@ BytePlus ARK zapewnia międzynarodowym użytkownikom dostęp do tych samych mode } ``` -Wdrożenie domyślnie używa powierzchni coding, ale ogólny katalog `byteplus/*` -jest rejestrowany w tym samym czasie. +Onboarding domyślnie używa powierzchni coding, ale ogólny katalog `byteplus/*` +jest rejestrowany jednocześnie. -W selektorach modeli wdrażania/konfiguracji wybór uwierzytelniania BytePlus preferuje zarówno +W selektorach modeli onboarding/configure model wybór auth BytePlus preferuje zarówno wiersze `byteplus/*`, jak i `byteplus-plan/*`. Jeśli te modele nie są jeszcze załadowane, -OpenClaw wraca do nieprzefiltrowanego katalogu zamiast pokazywać pusty +OpenClaw wraca do niefiltrowanego katalogu zamiast pokazywać pusty selektor ograniczony do dostawcy. Dostępne modele: @@ -621,7 +624,7 @@ Modele coding (`byteplus-plan`): Synthetic udostępnia modele zgodne z Anthropic za dostawcą `synthetic`: - Dostawca: `synthetic` -- Uwierzytelnianie: `SYNTHETIC_API_KEY` +- Auth: `SYNTHETIC_API_KEY` - Przykładowy model: `synthetic/hf:MiniMaxAI/MiniMax-M2.5` - CLI: `openclaw onboard --auth-choice synthetic-api-key` @@ -646,39 +649,39 @@ Synthetic udostępnia modele zgodne z Anthropic za dostawcą `synthetic`: ### MiniMax -MiniMax jest konfigurowany przez `models.providers`, ponieważ używa niestandardowych punktów końcowych: +MiniMax jest konfigurowany przez `models.providers`, ponieważ używa niestandardowych endpointów: -- MiniMax OAuth (globalny): `--auth-choice minimax-global-oauth` +- MiniMax OAuth (Global): `--auth-choice minimax-global-oauth` - MiniMax OAuth (CN): `--auth-choice minimax-cn-oauth` -- Klucz API MiniMax (globalny): `--auth-choice minimax-global-api` -- Klucz API MiniMax (CN): `--auth-choice minimax-cn-api` -- Uwierzytelnianie: `MINIMAX_API_KEY` dla `minimax`; `MINIMAX_OAUTH_TOKEN` lub +- MiniMax klucz API (Global): `--auth-choice minimax-global-api` +- MiniMax klucz API (CN): `--auth-choice minimax-cn-api` +- Auth: `MINIMAX_API_KEY` dla `minimax`; `MINIMAX_OAUTH_TOKEN` lub `MINIMAX_API_KEY` dla `minimax-portal` -Szczegóły konfiguracji, opcje modeli i fragmenty konfiguracji znajdziesz na stronie [/providers/minimax](/pl/providers/minimax). +Szczegóły konfiguracji, opcje modeli i fragmenty konfiguracji znajdziesz w [/providers/minimax](/pl/providers/minimax). -Na ścieżce strumieniowania MiniMax zgodnej z Anthropic OpenClaw domyślnie wyłącza myślenie, -chyba że ustawisz je jawnie, a `/fast on` przepisuje +Na ścieżce strumieniowania MiniMax zgodnej z Anthropic OpenClaw domyślnie wyłącza thinking, +chyba że jawnie go ustawisz, a `/fast on` przepisuje `MiniMax-M2.7` na `MiniMax-M2.7-highspeed`. Podział możliwości należących do wtyczki: -- Domyślne ustawienia tekstu/czatu pozostają na `minimax/MiniMax-M2.7` +- Domyślne ustawienia tekst/czat pozostają na `minimax/MiniMax-M2.7` - Generowanie obrazów to `minimax/image-01` lub `minimax-portal/image-01` -- Rozumienie obrazów to należący do wtyczki `MiniMax-VL-01` na obu ścieżkach uwierzytelniania MiniMax +- Rozumienie obrazów to należący do wtyczki `MiniMax-VL-01` na obu ścieżkach auth MiniMax - Wyszukiwanie w sieci pozostaje przy identyfikatorze dostawcy `minimax` ### Ollama -Ollama jest dostarczana jako dołączona wtyczka dostawcy i używa natywnego API Ollama: +Ollama jest dostarczany jako dołączona wtyczka dostawcy i używa natywnego API Ollama: - Dostawca: `ollama` -- Uwierzytelnianie: nie jest wymagane (serwer lokalny) +- Auth: niewymagane (serwer lokalny) - Przykładowy model: `ollama/llama3.3` - Instalacja: [https://ollama.com/download](https://ollama.com/download) ```bash -# Install Ollama, then pull a model: +# Zainstaluj Ollama, a następnie pobierz model: ollama pull llama3.3 ``` @@ -690,27 +693,27 @@ ollama pull llama3.3 } ``` -Ollama jest wykrywana lokalnie pod adresem `http://127.0.0.1:11434`, gdy włączysz ją przez +Ollama jest wykrywany lokalnie pod `http://127.0.0.1:11434`, gdy włączysz go przez `OLLAMA_API_KEY`, a dołączona wtyczka dostawcy dodaje Ollama bezpośrednio do `openclaw onboard` i selektora modeli. Zobacz [/providers/ollama](/pl/providers/ollama), -aby poznać szczegóły wdrażania, trybu chmurowego/lokalnego i konfiguracji niestandardowej. +aby poznać onboarding, tryb chmura/lokalny i konfigurację niestandardową. ### vLLM -vLLM jest dostarczane jako dołączona wtyczka dostawcy dla lokalnych/samohostowanych +vLLM jest dostarczany jako dołączona wtyczka dostawcy dla lokalnych/self-hosted serwerów zgodnych z OpenAI: - Dostawca: `vllm` -- Uwierzytelnianie: opcjonalne (zależy od serwera) -- Domyślny bazowy URL: `http://127.0.0.1:8000/v1` +- Auth: opcjonalne (zależy od serwera) +- Domyślny base URL: `http://127.0.0.1:8000/v1` -Aby lokalnie włączyć automatyczne wykrywanie (dowolna wartość działa, jeśli serwer nie wymusza uwierzytelniania): +Aby włączyć lokalne auto-discovery (dowolna wartość działa, jeśli serwer nie wymusza auth): ```bash export VLLM_API_KEY="vllm-local" ``` -Następnie ustaw model (zamień na jeden z identyfikatorów zwróconych przez `/v1/models`): +Następnie ustaw model (zamień na jeden z identyfikatorów zwracanych przez `/v1/models`): ```json5 { @@ -720,25 +723,25 @@ Następnie ustaw model (zamień na jeden z identyfikatorów zwróconych przez `/ } ``` -Szczegóły znajdziesz na stronie [/providers/vllm](/pl/providers/vllm). +Szczegóły znajdziesz w [/providers/vllm](/pl/providers/vllm). ### SGLang -SGLang jest dostarczany jako dołączona wtyczka dostawcy dla szybkich, samohostowanych -serwerów zgodnych z OpenAI: +SGLang jest dostarczany jako dołączona wtyczka dostawcy dla szybkich serwerów self-hosted +zgodnych z OpenAI: - Dostawca: `sglang` -- Uwierzytelnianie: opcjonalne (zależy od serwera) -- Domyślny bazowy URL: `http://127.0.0.1:30000/v1` +- Auth: opcjonalne (zależy od serwera) +- Domyślny base URL: `http://127.0.0.1:30000/v1` -Aby lokalnie włączyć automatyczne wykrywanie (dowolna wartość działa, jeśli serwer nie -wymusza uwierzytelniania): +Aby włączyć lokalne auto-discovery (dowolna wartość działa, jeśli serwer nie +wymusza auth): ```bash export SGLANG_API_KEY="sglang-local" ``` -Następnie ustaw model (zamień na jeden z identyfikatorów zwróconych przez `/v1/models`): +Następnie ustaw model (zamień na jeden z identyfikatorów zwracanych przez `/v1/models`): ```json5 { @@ -748,7 +751,7 @@ Następnie ustaw model (zamień na jeden z identyfikatorów zwróconych przez `/ } ``` -Szczegóły znajdziesz na stronie [/providers/sglang](/pl/providers/sglang). +Szczegóły znajdziesz w [/providers/sglang](/pl/providers/sglang). ### Lokalne proxy (LM Studio, vLLM, LiteLLM itd.) @@ -759,7 +762,7 @@ Przykład (zgodny z OpenAI): agents: { defaults: { model: { primary: "lmstudio/my-local-model" }, - models: { "lmstudio/my-local-model": { alias: "Local" } }, + models: { "lmstudio/my-local-model": { alias: "Lokalny" } }, }, }, models: { @@ -787,21 +790,21 @@ Przykład (zgodny z OpenAI): Uwagi: -- W przypadku dostawców niestandardowych `reasoning`, `input`, `cost`, `contextWindow` i `maxTokens` są opcjonalne. - Gdy zostaną pominięte, OpenClaw domyślnie przyjmuje: +- Dla niestandardowych dostawców `reasoning`, `input`, `cost`, `contextWindow` i `maxTokens` są opcjonalne. + Po pominięciu OpenClaw przyjmuje domyślnie: - `reasoning: false` - `input: ["text"]` - `cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }` - `contextWindow: 200000` - `maxTokens: 8192` -- Zalecane: ustaw jawne wartości odpowiadające limitom Twojego proxy/modelu. -- Dla `api: "openai-completions"` na nienatywnych punktach końcowych (dowolny niepusty `baseUrl`, którego host nie jest `api.openai.com`) OpenClaw wymusza `compat.supportsDeveloperRole: false`, aby uniknąć błędów 400 dostawcy dla nieobsługiwanych ról `developer`. +- Zalecane: ustaw jawne wartości zgodne z limitami Twojego proxy/modelu. +- Dla `api: "openai-completions"` na nienatywnych endpointach (dowolny niepusty `baseUrl`, którego host nie jest `api.openai.com`), OpenClaw wymusza `compat.supportsDeveloperRole: false`, aby uniknąć błędów dostawcy 400 dla nieobsługiwanych ról `developer`. - Trasy proxy zgodne z OpenAI również pomijają natywne kształtowanie żądań tylko dla OpenAI: - brak `service_tier`, brak `store` w Responses, brak wskazówek pamięci podręcznej promptów, brak - kształtowania ładunku zgodności rozumowania OpenAI i brak ukrytych nagłówków + brak `service_tier`, brak `store` dla Responses, brak wskazówek cache promptów, brak + kształtowania payload zgodności reasoning OpenAI i brak ukrytych nagłówków atrybucji OpenClaw. -- Jeśli `baseUrl` jest pusty/pominięty, OpenClaw zachowuje domyślne zachowanie OpenAI (które rozwiązuje się do `api.openai.com`). -- Dla bezpieczeństwa jawne `compat.supportsDeveloperRole: true` jest nadal nadpisywane na nienatywnych punktach końcowych `openai-completions`. +- Jeśli `baseUrl` jest pusty/pominięty, OpenClaw zachowuje domyślne zachowanie OpenAI (które jest rozwiązywane do `api.openai.com`). +- Dla bezpieczeństwa jawne `compat.supportsDeveloperRole: true` nadal jest nadpisywane na nienatywnych endpointach `openai-completions`. ## Przykłady CLI @@ -811,11 +814,11 @@ openclaw models set opencode/claude-opus-4-6 openclaw models list ``` -Zobacz także: [/gateway/configuration](/pl/gateway/configuration), aby poznać pełne przykłady konfiguracji. +Zobacz też: [/gateway/configuration](/pl/gateway/configuration), aby poznać pełne przykłady konfiguracji. ## Powiązane - [Models](/pl/concepts/models) — konfiguracja modeli i aliasy -- [Model Failover](/pl/concepts/model-failover) — łańcuchy przełączeń awaryjnych i zachowanie ponawiania prób +- [Model Failover](/pl/concepts/model-failover) — łańcuchy fallback i zachowanie ponownych prób - [Configuration Reference](/pl/gateway/configuration-reference#agent-defaults) — klucze konfiguracji modeli - [Providers](/pl/providers) — przewodniki konfiguracji dla poszczególnych dostawców diff --git a/docs/pl/concepts/qa-e2e-automation.md b/docs/pl/concepts/qa-e2e-automation.md index 4d37a8617..055d6cb0b 100644 --- a/docs/pl/concepts/qa-e2e-automation.md +++ b/docs/pl/concepts/qa-e2e-automation.md @@ -1,15 +1,15 @@ --- read_when: - Rozszerzanie qa-lab lub qa-channel - - Dodawanie scenariuszy QA wspieranych przez repozytorium - - Budowanie bardziej realistycznej automatyzacji QA wokół panelu Gateway -summary: Prywatna struktura automatyzacji QA dla qa-lab, qa-channel, scenariuszy seedowanych i raportów protokołu + - Dodawanie scenariuszy QA opartych na repozytorium + - Tworzenie bardziej realistycznej automatyzacji QA wokół panelu Gateway +summary: Prywatna struktura automatyzacji QA dla qa-lab, qa-channel, scenariuszy seed i raportów protokołu title: Automatyzacja QA E2E x-i18n: - generated_at: "2026-04-08T06:00:49Z" + generated_at: "2026-04-09T01:27:48Z" model: gpt-5.4 provider: openai - source_hash: 57da147dc06abf9620290104e01a83b42182db1806514114fd9e8467492cda99 + source_hash: c922607d67e0f3a2489ac82bc9f510f7294ced039c1014c15b676d826441d833 source_path: concepts/qa-e2e-automation.md workflow: 15 --- @@ -17,35 +17,35 @@ x-i18n: # Automatyzacja QA E2E Prywatny stos QA ma na celu testowanie OpenClaw w bardziej realistyczny, -ukształtowany przez kanały sposób, niż może to zrobić pojedynczy test jednostkowy. +zbliżony do kanałów sposób, niż może to zapewnić pojedynczy test jednostkowy. Obecne elementy: -- `extensions/qa-channel`: syntetyczny kanał wiadomości z powierzchniami DM, kanału, wątku, +- `extensions/qa-channel`: syntetyczny kanał wiadomości z obsługą DM, kanałów, wątków, reakcji, edycji i usuwania. -- `extensions/qa-lab`: interfejs debugowania i magistrala QA do obserwowania transkryptu, - wstrzykiwania wiadomości przychodzących oraz eksportowania raportu Markdown. -- `qa/`: zasoby seedowane wspierane przez repozytorium dla zadania startowego i bazowych +- `extensions/qa-lab`: interfejs debuggera i magistrala QA do obserwowania transkryptu, + wstrzykiwania wiadomości przychodzących i eksportowania raportu Markdown. +- `qa/`: zasoby seed oparte na repozytorium dla zadania startowego i bazowych scenariuszy QA. -Obecny przepływ pracy operatora QA to dwupanelowa strona QA: +Obecny przepływ pracy operatora QA to dwupanelowa witryna QA: -- Po lewej: panel Gateway (Control UI) z agentem. -- Po prawej: QA Lab, pokazujące transkrypt w stylu Slacka i plan scenariusza. +- Lewy panel: panel Gateway (Control UI) z agentem. +- Prawy panel: QA Lab, pokazujący transkrypt w stylu Slacka i plan scenariusza. -Uruchom to za pomocą: +Uruchom za pomocą: ```bash pnpm qa:lab:up ``` -To buduje stronę QA, uruchamia ścieżkę gateway opartą na Dockerze i udostępnia -stronę QA Lab, na której operator lub pętla automatyzacji może przydzielić agentowi misję QA, -obserwować rzeczywiste zachowanie kanału oraz zapisywać, co zadziałało, co się nie udało lub -co pozostało zablokowane. +To buduje witrynę QA, uruchamia ścieżkę Gateway opartą na Dockerze i udostępnia +stronę QA Lab, na której operator lub pętla automatyzacji może przekazać agentowi +misję QA, obserwować rzeczywiste zachowanie kanału oraz zapisywać, co działało, +co zawiodło lub co pozostało zablokowane. Aby szybciej iterować nad interfejsem QA Lab bez przebudowywania obrazu Dockera za każdym razem, -uruchom stos z bind-montowanym bundtem QA Lab: +uruchom stos z bind-mountowanym bundlem QA Lab: ```bash pnpm openclaw qa docker-build-image @@ -54,13 +54,14 @@ pnpm qa:lab:up:fast pnpm qa:lab:watch ``` -`qa:lab:up:fast` utrzymuje usługi Docker na wstępnie zbudowanym obrazie i bind-montuje +`qa:lab:up:fast` utrzymuje usługi Dockera na wcześniej zbudowanym obrazie i bind-mountuje `extensions/qa-lab/web/dist` do kontenera `qa-lab`. `qa:lab:watch` -przebudowuje ten bundel przy zmianach, a przeglądarka automatycznie przeładowuje się, gdy hash zasobu QA Lab się zmieni. +przebudowuje ten bundle po zmianach, a przeglądarka automatycznie przeładowuje się, +gdy hash zasobu QA Lab ulegnie zmianie. -## Zasoby seedowane wspierane przez repozytorium +## Seedy oparte na repozytorium -Zasoby seedowane znajdują się w `qa/`: +Zasoby seed znajdują się w `qa/`: - `qa/scenarios/index.md` - `qa/scenarios/*.md` @@ -68,27 +69,80 @@ Zasoby seedowane znajdują się w `qa/`: Są one celowo przechowywane w git, aby plan QA był widoczny zarówno dla ludzi, jak i dla agenta. Lista bazowa powinna pozostać na tyle szeroka, aby obejmować: -- czat DM i kanałowy +- czat w DM i na kanałach - zachowanie wątków -- cykl życia akcji wiadomości +- cykl życia akcji na wiadomościach - wywołania cron - przywoływanie pamięci - przełączanie modeli - przekazanie do subagenta -- odczyt repozytorium i dokumentacji +- odczytywanie repozytorium i dokumentacji - jedno małe zadanie build, takie jak Lobster Invaders ## Raportowanie -`qa-lab` eksportuje raport protokołu Markdown na podstawie obserwowanej osi czasu magistrali. +`qa-lab` eksportuje raport protokołu w Markdown na podstawie obserwowanej osi czasu magistrali. Raport powinien odpowiadać na pytania: -- Co zadziałało -- Co się nie udało +- Co działało +- Co zawiodło - Co pozostało zablokowane - Jakie scenariusze uzupełniające warto dodać -## Powiązane dokumenty +W przypadku kontroli charakteru i stylu uruchom ten sam scenariusz dla wielu aktywnych +referencji modeli i zapisz oceniany raport Markdown: + +```bash +pnpm openclaw qa character-eval \ + --model openai/gpt-5.4,thinking=xhigh \ + --model openai/gpt-5.2,thinking=xhigh \ + --model openai/gpt-5,thinking=xhigh \ + --model anthropic/claude-opus-4-6,thinking=high \ + --model anthropic/claude-sonnet-4-6,thinking=high \ + --model zai/glm-5.1,thinking=high \ + --model moonshot/kimi-k2.5,thinking=high \ + --model google/gemini-3.1-pro-preview,thinking=high \ + --judge-model openai/gpt-5.4,thinking=xhigh,fast \ + --judge-model anthropic/claude-opus-4-6,thinking=high \ + --blind-judge-models \ + --concurrency 16 \ + --judge-concurrency 16 +``` + +Polecenie uruchamia lokalne podrzędne procesy QA Gateway, a nie Docker. Scenariusze +oceny charakteru powinny ustawiać personę przez `SOUL.md`, a następnie wykonywać zwykłe +tury użytkownika, takie jak czat, pomoc dotyczącą workspace i małe zadania na plikach. Modelowi +kandydującemu nie należy mówić, że jest oceniany. Polecenie zachowuje każdy pełny +transkrypt, rejestruje podstawowe statystyki uruchomienia, a następnie prosi modele oceniające +w trybie fast z rozumowaniem `xhigh` o uszeregowanie uruchomień według naturalności, klimatu i humoru. +Użyj `--blind-judge-models` podczas porównywania providerów: prompt oceniający nadal otrzymuje +każdy transkrypt i status uruchomienia, ale referencje kandydatów są zastępowane neutralnymi +etykietami, takimi jak `candidate-01`; raport mapuje rankingi z powrotem na rzeczywiste referencje po +parsowaniu. +Uruchomienia kandydatów domyślnie używają poziomu myślenia `high`, a dla modeli OpenAI, +które go obsługują, `xhigh`. Zastąp ustawienie dla konkretnego kandydata inline za pomocą +`--model provider/model,thinking=`. `--thinking ` nadal ustawia +globalne ustawienie zapasowe, a starsza forma `--model-thinking ` jest +zachowana dla zgodności. +Referencje kandydatów OpenAI domyślnie używają trybu fast, aby tam, gdzie provider to obsługuje, +korzystać z przetwarzania priorytetowego. Dodaj inline `,fast`, `,no-fast` lub `,fast=false`, gdy +pojedynczy kandydat lub sędzia wymaga nadpisania. Przekaż `--fast` tylko wtedy, gdy chcesz +wymusić tryb fast dla każdego modelu kandydującego. Czasy trwania dla kandydatów i modeli +oceniających są zapisywane w raporcie do analizy benchmarków, ale prompty oceniające wyraźnie +mówią, aby nie tworzyć rankingu na podstawie szybkości. +Zarówno uruchomienia modeli kandydujących, jak i oceniających domyślnie używają współbieżności 16. Zmniejsz +`--concurrency` lub `--judge-concurrency`, gdy limity providera lub obciążenie lokalnego Gateway +powodują, że uruchomienie staje się zbyt zaszumione. +Gdy nie zostanie przekazany żaden kandydat `--model`, ocena charakteru domyślnie używa +`openai/gpt-5.4`, `openai/gpt-5.2`, `openai/gpt-5`, `anthropic/claude-opus-4-6`, +`anthropic/claude-sonnet-4-6`, `zai/glm-5.1`, +`moonshot/kimi-k2.5` oraz +`google/gemini-3.1-pro-preview`, gdy nie zostanie przekazany parametr `--model`. +Gdy nie zostanie przekazany żaden `--judge-model`, modele oceniające domyślnie używają +`openai/gpt-5.4,thinking=xhigh,fast` oraz +`anthropic/claude-opus-4-6,thinking=high`. + +## Powiązana dokumentacja - [Testing](/pl/help/testing) - [QA Channel](/pl/channels/qa-channel) diff --git a/docs/pl/gateway/cli-backends.md b/docs/pl/gateway/cli-backends.md index c9c67afdb..1294c7178 100644 --- a/docs/pl/gateway/cli-backends.md +++ b/docs/pl/gateway/cli-backends.md @@ -1,38 +1,38 @@ --- read_when: - - Chcesz mieć niezawodny fallback, gdy dostawcy API zawodzą + - Chcesz mieć niezawodne rozwiązanie awaryjne, gdy dostawcy API zawodzą - Uruchamiasz Codex CLI lub inne lokalne AI CLI i chcesz używać ich ponownie - - Chcesz zrozumieć most loopback MCP do dostępu narzędzi backendu CLI -summary: 'Backendy CLI: lokalny awaryjny fallback AI CLI z opcjonalnym mostem narzędzi MCP' + - Chcesz zrozumieć most local loopback MCP zapewniający dostęp backendu CLI do narzędzi +summary: 'Backendy CLI: lokalne awaryjne przełączenie na AI CLI z opcjonalnym mostem narzędzi MCP' title: Backendy CLI x-i18n: - generated_at: "2026-04-07T09:44:57Z" + generated_at: "2026-04-09T01:28:04Z" model: gpt-5.4 provider: openai - source_hash: b0e8c41f5f5a8e34466f6b765e5c08585ef1788fa9e9d953257324bcc6cbc414 + source_hash: 9b458f9fe6fa64c47864c8c180f3dedfd35c5647de470a2a4d31c26165663c20 source_path: gateway/cli-backends.md workflow: 15 --- -# Backendy CLI (awaryjny runtime) +# Backendy CLI (awaryjne środowisko uruchomieniowe) -OpenClaw może uruchamiać **lokalne AI CLI** jako **tekstowy fallback** gdy dostawcy API są niedostępni, -ograniczani limitami lub tymczasowo działają nieprawidłowo. To podejście jest celowo zachowawcze: +OpenClaw może uruchamiać **lokalne AI CLI** jako **awaryjne rozwiązanie tylko tekstowe**, gdy dostawcy API są niedostępni, +ograniczani limitami lub tymczasowo działają nieprawidłowo. To rozwiązanie jest celowo zachowawcze: - **Narzędzia OpenClaw nie są wstrzykiwane bezpośrednio**, ale backendy z `bundleMcp: true` - mogą otrzymywać narzędzia gateway przez most loopback MCP. + mogą otrzymywać narzędzia bramy przez most MCP typu loopback. - **Strumieniowanie JSONL** dla CLI, które je obsługują. -- **Sesje są obsługiwane** (więc kolejne tury pozostają spójne). +- **Sesje są obsługiwane** (dzięki temu kolejne tury pozostają spójne). - **Obrazy mogą być przekazywane dalej**, jeśli CLI akceptuje ścieżki do obrazów. -To rozwiązanie zostało zaprojektowane jako **siatka bezpieczeństwa**, a nie główna ścieżka. Używaj go, gdy -chcesz mieć odpowiedzi tekstowe typu „zawsze działa” bez polegania na zewnętrznych API. +To rozwiązanie pełni rolę **siatki bezpieczeństwa**, a nie głównej ścieżki. Używaj go, gdy +chcesz uzyskiwać tekstowe odpowiedzi typu „zawsze działa” bez polegania na zewnętrznych API. -Jeśli chcesz mieć pełny runtime harness z kontrolą sesji ACP, zadaniami w tle, -powiązaniem wątku/konwersacji i trwałymi zewnętrznymi sesjami kodowania, użyj +Jeśli chcesz pełnego środowiska z kontrolą sesji ACP, zadaniami w tle, +powiązaniem wątków/konwersacji i trwałymi zewnętrznymi sesjami kodowania, użyj [ACP Agents](/pl/tools/acp-agents). Backendy CLI nie są ACP. -## Przyjazny dla początkujących szybki start +## Szybki start dla początkujących Możesz używać Codex CLI **bez żadnej konfiguracji** (dołączona wtyczka OpenAI rejestruje domyślny backend): @@ -41,8 +41,8 @@ rejestruje domyślny backend): openclaw agent --message "hi" --model codex-cli/gpt-5.4 ``` -Jeśli Twój gateway działa pod launchd/systemd i PATH jest minimalny, dodaj tylko -ścieżkę polecenia: +Jeśli Twoja brama działa pod launchd/systemd, a `PATH` jest minimalne, dodaj tylko +ścieżkę do polecenia: ```json5 { @@ -61,13 +61,13 @@ Jeśli Twój gateway działa pod launchd/systemd i PATH jest minimalny, dodaj ty To wszystko. Nie są potrzebne żadne klucze ani dodatkowa konfiguracja uwierzytelniania poza samym CLI. Jeśli używasz dołączonego backendu CLI jako **głównego dostawcy wiadomości** na -hoście gateway, OpenClaw teraz automatycznie ładuje odpowiednią dołączoną wtyczkę, gdy Twoja konfiguracja -jawnie odwołuje się do tego backendu w odwołaniu do modelu lub w +hoście bramy, OpenClaw teraz automatycznie ładuje odpowiednią dołączoną wtyczkę, gdy Twoja konfiguracja +jawnie odwołuje się do tego backendu w odwołaniu do modelu albo w `agents.defaults.cliBackends`. -## Używanie jako fallback +## Używanie jako rozwiązania awaryjnego -Dodaj backend CLI do listy fallbacków, aby był uruchamiany tylko wtedy, gdy modele podstawowe zawiodą: +Dodaj backend CLI do listy awaryjnej, aby był uruchamiany tylko wtedy, gdy główne modele zawiodą: ```json5 { @@ -88,8 +88,8 @@ Dodaj backend CLI do listy fallbacków, aby był uruchamiany tylko wtedy, gdy mo Uwagi: -- Jeśli używasz `agents.defaults.models` (listy dozwolonych), musisz uwzględnić tam również modele backendu CLI. -- Jeśli podstawowy dostawca zawiedzie (uwierzytelnianie, limity, timeouty), OpenClaw +- Jeśli używasz `agents.defaults.models` (lista dozwolonych), musisz uwzględnić tam także modele backendu CLI. +- Jeśli główny dostawca zawiedzie (uwierzytelnianie, limity, limity czasu), OpenClaw spróbuje następnie użyć backendu CLI. ## Przegląd konfiguracji @@ -100,8 +100,8 @@ Wszystkie backendy CLI znajdują się pod: agents.defaults.cliBackends ``` -Każdy wpis jest kluczowany przez **id dostawcy** (np. `codex-cli`, `my-cli`). -Id dostawcy staje się lewą stroną odwołania do modelu: +Każdy wpis jest kluczowany przez **identyfikator dostawcy** (na przykład `codex-cli`, `my-cli`). +Identyfikator dostawcy staje się lewą stroną odwołania do modelu: ``` / @@ -131,6 +131,9 @@ Id dostawcy staje się lewą stroną odwołania do modelu: sessionMode: "existing", sessionIdFields: ["session_id", "conversation_id"], systemPromptArg: "--system", + // CLI w stylu Codex mogą zamiast tego wskazywać plik promptu: + // systemPromptFileConfigArg: "-c", + // systemPromptFileConfigKey: "model_instructions_file", systemPromptWhen: "first", imageArg: "--image", imageMode: "repeat", @@ -145,38 +148,44 @@ Id dostawcy staje się lewą stroną odwołania do modelu: ## Jak to działa 1. **Wybiera backend** na podstawie prefiksu dostawcy (`codex-cli/...`). -2. **Buduje system prompt** przy użyciu tego samego promptu OpenClaw + kontekstu workspace. -3. **Uruchamia CLI** z id sesji (jeśli jest obsługiwane), aby historia pozostała spójna. -4. **Parsuje wyjście** (JSON lub zwykły tekst) i zwraca końcowy tekst. -5. **Utrwala id sesji** dla każdego backendu, aby kolejne tury używały tej samej sesji CLI. +2. **Buduje prompt systemowy** z użyciem tego samego promptu OpenClaw i kontekstu obszaru roboczego. +3. **Uruchamia CLI** z identyfikatorem sesji (jeśli jest obsługiwany), aby zachować spójność historii. +4. **Parsuje dane wyjściowe** (JSON lub zwykły tekst) i zwraca końcowy tekst. +5. **Utrwala identyfikatory sesji** dla każdego backendu, dzięki czemu kolejne tury używają tej samej sesji CLI. Dołączony backend Anthropic `claude-cli` jest ponownie obsługiwany. Pracownicy Anthropic -powiedzieli nam, że użycie Claude CLI w stylu OpenClaw jest znowu dozwolone, więc OpenClaw traktuje -użycie `claude -p` jako usankcjonowane dla tej integracji, chyba że Anthropic opublikuje +poinformowali nas, że użycie Claude CLI w stylu OpenClaw jest znów dozwolone, więc OpenClaw traktuje +użycie `claude -p` jako zatwierdzone dla tej integracji, chyba że Anthropic opublikuje nową politykę. +Dołączony backend OpenAI `codex-cli` przekazuje prompt systemowy OpenClaw przez +nadpisanie konfiguracji `model_instructions_file` w Codex (`-c +model_instructions_file="..."`). Codex nie udostępnia flagi w stylu Claude +`--append-system-prompt`, więc OpenClaw zapisuje złożony prompt do +pliku tymczasowego dla każdej nowej sesji Codex CLI. + ## Sesje -- Jeśli CLI obsługuje sesje, ustaw `sessionArg` (np. `--session-id`) albo - `sessionArgs` (placeholder `{sessionId}`), gdy ID trzeba wstawić +- Jeśli CLI obsługuje sesje, ustaw `sessionArg` (na przykład `--session-id`) albo + `sessionArgs` (symbol zastępczy `{sessionId}`), gdy identyfikator trzeba wstawić do wielu flag. -- Jeśli CLI używa **podpolecenia resume** z innymi flagami, ustaw +- Jeśli CLI używa **podpolecenia wznawiania** z innymi flagami, ustaw `resumeArgs` (zastępuje `args` przy wznawianiu) i opcjonalnie `resumeOutput` (dla wznowień innych niż JSON). - `sessionMode`: - - `always`: zawsze wysyłaj id sesji (nowe UUID, jeśli nic nie zapisano). - - `existing`: wysyłaj id sesji tylko wtedy, gdy było wcześniej zapisane. - - `none`: nigdy nie wysyłaj id sesji. + - `always`: zawsze wysyłaj identyfikator sesji (nowy UUID, jeśli nic nie zapisano). + - `existing`: wysyłaj identyfikator sesji tylko wtedy, gdy został wcześniej zapisany. + - `none`: nigdy nie wysyłaj identyfikatora sesji. Uwagi dotyczące serializacji: -- `serialize: true` utrzymuje uporządkowaną kolejność uruchomień w tym samym przebiegu. -- Większość CLI serializuje na jednym przebiegu dostawcy. -- OpenClaw porzuca ponowne użycie zapisanej sesji CLI, gdy zmienia się stan uwierzytelnienia backendu, w tym po ponownym logowaniu, rotacji tokena lub zmianie poświadczeń profilu uwierzytelniania. +- `serialize: true` utrzymuje uporządkowanie uruchomień w tym samym torze. +- Większość CLI serializuje na jednym torze dostawcy. +- OpenClaw porzuca ponowne użycie zapisanej sesji CLI, gdy stan uwierzytelnienia backendu się zmienia, w tym po ponownym logowaniu, rotacji tokena lub zmianie poświadczenia profilu uwierzytelniania. -## Obrazy (pass-through) +## Obrazy (przekazywanie dalej) Jeśli Twoje CLI akceptuje ścieżki do obrazów, ustaw `imageArg`: @@ -186,15 +195,15 @@ imageMode: "repeat" ``` OpenClaw zapisze obrazy base64 do plików tymczasowych. Jeśli ustawiono `imageArg`, te -ścieżki są przekazywane jako argumenty CLI. Jeśli brakuje `imageArg`, OpenClaw dopisuje +ścieżki są przekazywane jako argumenty CLI. Jeśli `imageArg` nie jest ustawione, OpenClaw dołącza ścieżki plików do promptu (wstrzykiwanie ścieżek), co wystarcza dla CLI, które automatycznie -ładują lokalne pliki ze zwykłych ścieżek. +ładują pliki lokalne ze zwykłych ścieżek. ## Wejścia / wyjścia -- `output: "json"` (domyślnie) próbuje sparsować JSON i wyodrębnić tekst + id sesji. -- Dla wyjścia JSON Gemini CLI OpenClaw odczytuje tekst odpowiedzi z `response`, a - informacje o zużyciu z `stats`, gdy `usage` nie istnieje lub jest puste. +- `output: "json"` (domyślnie) próbuje sparsować JSON i wyodrębnić tekst oraz identyfikator sesji. +- Dla wyjścia JSON Gemini CLI OpenClaw odczytuje tekst odpowiedzi z `response` oraz + użycie ze `stats`, gdy `usage` nie istnieje lub jest puste. - `output: "jsonl"` parsuje strumienie JSONL (na przykład Codex CLI `--json`) i wyodrębnia końcową wiadomość agenta oraz identyfikatory sesji, jeśli są obecne. - `output: "text"` traktuje stdout jako końcową odpowiedź. @@ -203,11 +212,11 @@ Tryby wejścia: - `input: "arg"` (domyślnie) przekazuje prompt jako ostatni argument CLI. - `input: "stdin"` wysyła prompt przez stdin. -- Jeśli prompt jest bardzo długi i ustawiono `maxPromptArgChars`, używany jest stdin. +- Jeśli prompt jest bardzo długi i ustawiono `maxPromptArgChars`, używane jest stdin. -## Wartości domyślne (należące do wtyczki) +## Domyślne ustawienia (należące do wtyczki) -Dołączona wtyczka OpenAI rejestruje także wartość domyślną dla `codex-cli`: +Dołączona wtyczka OpenAI rejestruje również ustawienia domyślne dla `codex-cli`: - `command: "codex"` - `args: ["exec","--json","--color","never","--sandbox","workspace-write","--skip-git-repo-check"]` @@ -218,7 +227,7 @@ Dołączona wtyczka OpenAI rejestruje także wartość domyślną dla `codex-cli - `imageArg: "--image"` - `sessionMode: "existing"` -Dołączona wtyczka Google rejestruje także wartość domyślną dla `google-gemini-cli`: +Dołączona wtyczka Google rejestruje również ustawienia domyślne dla `google-gemini-cli`: - `command: "gemini"` - `args: ["--output-format", "json", "--prompt", "{prompt}"]` @@ -229,69 +238,69 @@ Dołączona wtyczka Google rejestruje także wartość domyślną dla `google-ge - `sessionMode: "existing"` - `sessionIdFields: ["session_id", "sessionId"]` -Wymaganie wstępne: lokalne Gemini CLI musi być zainstalowane i dostępne jako +Wymaganie wstępne: lokalny Gemini CLI musi być zainstalowany i dostępny jako `gemini` w `PATH` (`brew install gemini-cli` lub `npm install -g @google/gemini-cli`). -Uwagi o JSON Gemini CLI: +Uwagi dotyczące JSON Gemini CLI: - Tekst odpowiedzi jest odczytywany z pola JSON `response`. -- Zużycie korzysta z `stats` jako fallbacku, gdy `usage` nie istnieje lub jest puste. +- Użycie przechodzi awaryjnie na `stats`, gdy `usage` jest nieobecne lub puste. - `stats.cached` jest normalizowane do OpenClaw `cacheRead`. -- Jeśli brakuje `stats.input`, OpenClaw wyprowadza tokeny wejściowe z +- Jeśli `stats.input` nie istnieje, OpenClaw wyprowadza tokeny wejściowe z `stats.input_tokens - stats.cached`. Nadpisuj tylko wtedy, gdy to potrzebne (najczęściej: bezwzględna ścieżka `command`). -## Wartości domyślne należące do wtyczki +## Ustawienia domyślne należące do wtyczki -Wartości domyślne backendu CLI są teraz częścią powierzchni wtyczki: +Domyślne ustawienia backendów CLI są teraz częścią powierzchni wtyczki: - Wtyczki rejestrują je przez `api.registerCliBackend(...)`. -- Backend `id` staje się prefiksem dostawcy w odwołaniach do modeli. -- Konfiguracja użytkownika w `agents.defaults.cliBackends.` nadal nadpisuje wartość domyślną wtyczki. -- Czyszczenie konfiguracji specyficznej dla backendu pozostaje po stronie wtyczki przez opcjonalny hook - `normalizeConfig`. +- `id` backendu staje się prefiksem dostawcy w odwołaniach do modeli. +- Konfiguracja użytkownika w `agents.defaults.cliBackends.` nadal nadpisuje ustawienie domyślne wtyczki. +- Czyszczenie konfiguracji specyficznej dla backendu pozostaje po stronie wtyczki dzięki opcjonalnemu + hookowi `normalizeConfig`. -## Nakładki bundle MCP +## Nakładki Bundle MCP Backendy CLI **nie** otrzymują bezpośrednio wywołań narzędzi OpenClaw, ale backend może włączyć wygenerowaną nakładkę konfiguracji MCP przez `bundleMcp: true`. -Obecne zachowanie dla dołączonych backendów: +Bieżące dołączone zachowanie: -- `claude-cli`: wygenerowany ścisły plik konfiguracji MCP +- `claude-cli`: wygenerowany ścisły plik konfiguracyjny MCP - `codex-cli`: wbudowane nadpisania konfiguracji dla `mcp_servers` - `google-gemini-cli`: wygenerowany plik ustawień systemowych Gemini Gdy bundle MCP jest włączone, OpenClaw: -- uruchamia serwer HTTP MCP loopback, który udostępnia narzędzia gateway procesowi CLI -- uwierzytelnia most tokenem na sesję (`OPENCLAW_MCP_TOKEN`) +- uruchamia serwer HTTP MCP typu loopback, który udostępnia narzędzia bramy procesowi CLI +- uwierzytelnia most za pomocą tokena per sesja (`OPENCLAW_MCP_TOKEN`) - ogranicza dostęp do narzędzi do bieżącej sesji, konta i kontekstu kanału -- ładuje włączone serwery bundle-MCP dla bieżącego workspace +- ładuje włączone serwery bundle-MCP dla bieżącego obszaru roboczego - scala je z dowolnym istniejącym kształtem konfiguracji/ustawień MCP backendu -- przepisuje konfigurację uruchomienia przy użyciu trybu integracji należącego do backendu z odpowiedniego rozszerzenia +- przepisuje konfigurację uruchamiania przy użyciu trybu integracji należącego do backendu z rozszerzenia będącego jego właścicielem -Jeśli nie są włączone żadne serwery MCP, OpenClaw nadal wstrzykuje ścisłą konfigurację, gdy -backend włącza bundle MCP, aby uruchomienia w tle pozostały odizolowane. +Jeśli żadne serwery MCP nie są włączone, OpenClaw nadal wstrzykuje ścisłą konfigurację, gdy +backend korzysta z bundle MCP, aby uruchomienia w tle pozostawały odizolowane. ## Ograniczenia - **Brak bezpośrednich wywołań narzędzi OpenClaw.** OpenClaw nie wstrzykuje wywołań narzędzi do - protokołu backendu CLI. Backendy widzą narzędzia gateway tylko wtedy, gdy włączają + protokołu backendu CLI. Backendy widzą narzędzia bramy tylko wtedy, gdy wybiorą `bundleMcp: true`. - **Strumieniowanie jest zależne od backendu.** Niektóre backendy strumieniują JSONL; inne buforują - do zakończenia działania. -- **Wyjścia strukturalne** zależą od formatu JSON danego CLI. -- **Sesje Codex CLI** są wznawiane przez wyjście tekstowe (bez JSONL), co jest mniej - ustrukturyzowane niż początkowe uruchomienie `--json`. Sesje OpenClaw nadal działają + do momentu zakończenia. +- **Ustrukturyzowane dane wyjściowe** zależą od formatu JSON danego CLI. +- **Sesje Codex CLI** są wznawiane przez wyjście tekstowe (bez JSONL), co jest + mniej ustrukturyzowane niż początkowe uruchomienie `--json`. Sesje OpenClaw nadal działają normalnie. ## Rozwiązywanie problemów - **Nie znaleziono CLI**: ustaw `command` na pełną ścieżkę. -- **Nieprawidłowa nazwa modelu**: użyj `modelAliases`, aby mapować `provider/model` → model CLI. -- **Brak ciągłości sesji**: upewnij się, że ustawiono `sessionArg` i `sessionMode` nie jest - `none` (Codex CLI obecnie nie potrafi wznawiać z wyjściem JSON). -- **Obrazy są ignorowane**: ustaw `imageArg` (i sprawdź, czy CLI obsługuje ścieżki plików). +- **Nieprawidłowa nazwa modelu**: użyj `modelAliases`, aby zmapować `provider/model` → model CLI. +- **Brak ciągłości sesji**: upewnij się, że ustawiono `sessionArg`, a `sessionMode` nie ma wartości + `none` (Codex CLI obecnie nie może wznawiać z wyjściem JSON). +- **Obrazy są ignorowane**: ustaw `imageArg` (i sprawdź, czy CLI obsługuje ścieżki do plików). diff --git a/docs/pl/gateway/configuration-reference.md b/docs/pl/gateway/configuration-reference.md index 599524774..954ce69f7 100644 --- a/docs/pl/gateway/configuration-reference.md +++ b/docs/pl/gateway/configuration-reference.md @@ -1,43 +1,43 @@ --- read_when: - Potrzebujesz dokładnej semantyki pól konfiguracji lub wartości domyślnych - - Weryfikujesz bloki konfiguracji kanałów, modeli, gateway lub narzędzi -summary: Odwołanie do konfiguracji Gateway dla podstawowych kluczy OpenClaw, wartości domyślnych i linków do dedykowanych odwołań podsystemów -title: Odwołanie do konfiguracji + - Weryfikujesz bloki konfiguracji kanałów, modeli, bramy lub narzędzi +summary: Dokumentacja referencyjna konfiguracji bramy dla podstawowych kluczy OpenClaw, wartości domyślnych i linków do dedykowanych dokumentacji podsystemów +title: Dokumentacja referencyjna konfiguracji x-i18n: - generated_at: "2026-04-08T09:50:46Z" + generated_at: "2026-04-09T01:33:09Z" model: gpt-5.4 provider: openai - source_hash: fd5f69050455e610fc7c825d95f546a16aa867b8a9c0d692a48de36419b0afc2 + source_hash: a9d6d0c542b9874809491978fdcf8e1a7bb35a4873db56aa797963d03af4453c source_path: gateway/configuration-reference.md workflow: 15 --- -# Odwołanie do konfiguracji +# Dokumentacja referencyjna konfiguracji -Podstawowe odwołanie do konfiguracji dla `~/.openclaw/openclaw.json`. Przegląd zorientowany na zadania znajdziesz w [Configuration](/pl/gateway/configuration). +Dokumentacja podstawowej konfiguracji dla `~/.openclaw/openclaw.json`. Przegląd zorientowany na zadania znajdziesz w [Configuration](/pl/gateway/configuration). -Ta strona opisuje główne powierzchnie konfiguracji OpenClaw i odsyła dalej, gdy podsystem ma własne, bardziej szczegółowe odwołanie. **Nie** próbuje umieszczać w jednym miejscu każdego katalogu poleceń należącego do kanału/pluginu ani każdej zaawansowanej opcji pamięci/QMD. +Ta strona opisuje główne powierzchnie konfiguracji OpenClaw i zawiera odnośniki tam, gdzie dany podsystem ma własną, bardziej szczegółową dokumentację. **Nie** próbuje wstawiać na jednej stronie każdego katalogu poleceń należącego do kanału/pluginu ani każdego szczegółowego parametru pamięci/QMD. Źródło prawdy w kodzie: -- `openclaw config schema` wypisuje aktywny JSON Schema używany do walidacji i Control UI, z dołączonymi metadanymi bundled/plugin/channel, gdy są dostępne -- `config.schema.lookup` zwraca pojedynczy węzeł schematu ograniczony do ścieżki dla narzędzi do szczegółowej analizy -- `pnpm config:docs:check` / `pnpm config:docs:gen` weryfikują skrót bazowy dokumentacji konfiguracji względem bieżącej powierzchni schematu +- `openclaw config schema` wypisuje aktualny schemat JSON Schema używany do walidacji i przez UI Control, z dołączonymi metadanymi bundled/plugin/channel, gdy są dostępne +- `config.schema.lookup` zwraca jeden węzeł schematu ograniczony do ścieżki dla narzędzi do szczegółowej analizy +- `pnpm config:docs:check` / `pnpm config:docs:gen` weryfikują hash bazowy dokumentacji konfiguracji względem bieżącej powierzchni schematu -Dedykowane szczegółowe odwołania: +Dedykowane szczegółowe dokumentacje: -- [Odwołanie do konfiguracji pamięci](/pl/reference/memory-config) dla `agents.defaults.memorySearch.*`, `memory.qmd.*`, `memory.citations` oraz konfiguracji dreaming w `plugins.entries.memory-core.config.dreaming` +- [Memory configuration reference](/pl/reference/memory-config) dla `agents.defaults.memorySearch.*`, `memory.qmd.*`, `memory.citations` i konfiguracji dreaming w `plugins.entries.memory-core.config.dreaming` - [Slash Commands](/pl/tools/slash-commands) dla bieżącego katalogu wbudowanych + bundled poleceń - strony właściciela kanału/pluginu dla powierzchni poleceń specyficznych dla kanału -Format konfiguracji to **JSON5** (dozwolone komentarze + przecinki końcowe). Wszystkie pola są opcjonalne — OpenClaw używa bezpiecznych wartości domyślnych, gdy zostały pominięte. +Format konfiguracji to **JSON5** (dozwolone komentarze i końcowe przecinki). Wszystkie pola są opcjonalne — OpenClaw używa bezpiecznych wartości domyślnych, gdy są pominięte. --- ## Kanały -Każdy kanał uruchamia się automatycznie, gdy jego sekcja konfiguracji istnieje (chyba że `enabled: false`). +Każdy kanał uruchamia się automatycznie, gdy istnieje jego sekcja konfiguracji (chyba że `enabled: false`). ### Dostęp do DM i grup @@ -45,26 +45,26 @@ Wszystkie kanały obsługują zasady DM i zasady grup: | Zasada DM | Zachowanie | | ------------------- | -------------------------------------------------------------- | -| `pairing` (domyślna) | Nieznani nadawcy otrzymują jednorazowy kod parowania; właściciel musi zatwierdzić | -| `allowlist` | Tylko nadawcy z `allowFrom` (lub sparowanego magazynu zezwoleń) | -| `open` | Zezwalaj na wszystkie przychodzące DM (wymaga `allowFrom: ["*"]`) | -| `disabled` | Ignoruj wszystkie przychodzące DM | +| `pairing` (domyślna) | Nieznani nadawcy dostają jednorazowy kod parowania; właściciel musi zatwierdzić | +| `allowlist` | Tylko nadawcy z `allowFrom` (lub sparowanego magazynu dozwolonych) | +| `open` | Zezwól na wszystkie przychodzące DM (wymaga `allowFrom: ["*"]`) | +| `disabled` | Ignoruj wszystkie przychodzące DM | -| Zasada grupy | Zachowanie | -| --------------------- | ----------------------------------------------------- | -| `allowlist` (domyślna) | Tylko grupy pasujące do skonfigurowanej listy zezwoleń | -| `open` | Pomijaj listy zezwoleń grup (nadal obowiązuje wymóg wzmianki) | -| `disabled` | Blokuj wszystkie wiadomości grupowe/pokojów | +| Zasada grup | Zachowanie | +| --------------------- | ------------------------------------------------------ | +| `allowlist` (domyślna) | Tylko grupy pasujące do skonfigurowanej listy dozwolonych | +| `open` | Pomija listy dozwolonych grup (nadal obowiązuje bramkowanie wzmiankami) | +| `disabled` | Blokuje wszystkie wiadomości w grupach/pokojach | `channels.defaults.groupPolicy` ustawia wartość domyślną, gdy `groupPolicy` dostawcy nie jest ustawione. -Kody parowania wygasają po 1 godzinie. Oczekujące prośby o parowanie DM są ograniczone do **3 na kanał**. -Jeśli blok dostawcy całkowicie nie istnieje (`channels.` nieobecne), zasada grupy w czasie działania wraca do `allowlist` (fail-closed) z ostrzeżeniem przy uruchamianiu. +Kody parowania wygasają po 1 godzinie. Oczekujące żądania parowania DM są ograniczone do **3 na kanał**. +Jeśli blok dostawcy całkowicie nie istnieje (`channels.` nieobecne), zasada grup w czasie działania wraca do `allowlist` (fail-closed) z ostrzeżeniem przy uruchomieniu. -### Nadpisania modelu dla kanałów +### Nadpisania modelu dla kanału -Użyj `channels.modelByChannel`, aby przypiąć określone identyfikatory kanałów do modelu. Wartości akceptują `provider/model` lub skonfigurowane aliasy modeli. Mapowanie kanałów ma zastosowanie, gdy sesja nie ma już nadpisania modelu (na przykład ustawionego przez `/model`). +Użyj `channels.modelByChannel`, aby przypisać określone identyfikatory kanałów do modelu. Wartości akceptują `provider/model` lub skonfigurowane aliasy modeli. Mapowanie kanałów jest stosowane, gdy sesja nie ma już nadpisania modelu (na przykład ustawionego przez `/model`). ```json5 { @@ -87,7 +87,7 @@ Użyj `channels.modelByChannel`, aby przypiąć określone identyfikatory kanał ### Domyślne ustawienia kanałów i heartbeat -Użyj `channels.defaults` dla współdzielonych zasad grup i zachowania heartbeat między dostawcami: +Użyj `channels.defaults` dla współdzielonych zachowań zasad grup i heartbeat między dostawcami: ```json5 { @@ -106,14 +106,14 @@ Użyj `channels.defaults` dla współdzielonych zasad grup i zachowania heartbea ``` - `channels.defaults.groupPolicy`: zapasowa zasada grup, gdy `groupPolicy` na poziomie dostawcy nie jest ustawione. -- `channels.defaults.contextVisibility`: domyślny tryb widoczności uzupełniającego kontekstu dla wszystkich kanałów. Wartości: `all` (domyślnie, uwzględnij cały kontekst cytatów/wątków/historii), `allowlist` (uwzględnij tylko kontekst od nadawców z listy zezwoleń), `allowlist_quote` (jak allowlist, ale zachowaj jawny kontekst cytatu/odpowiedzi). Nadpisanie per kanał: `channels..contextVisibility`. -- `channels.defaults.heartbeat.showOk`: uwzględnij zdrowe statusy kanałów w wyjściu heartbeat. -- `channels.defaults.heartbeat.showAlerts`: uwzględnij pogorszone/błędne statusy kanałów w wyjściu heartbeat. -- `channels.defaults.heartbeat.useIndicator`: renderuj kompaktowe wyjście heartbeat w stylu wskaźnika. +- `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 allowlist, ale zachowuje jawny kontekst cytatu/odpowiedzi). Nadpisanie per kanał: `channels..contextVisibility`. +- `channels.defaults.heartbeat.showOk`: uwzględnia zdrowe statusy kanałów w wyjściu heartbeat. +- `channels.defaults.heartbeat.showAlerts`: uwzględnia statusy pogorszone/błędów w wyjściu heartbeat. +- `channels.defaults.heartbeat.useIndicator`: renderuje zwarty heartbeat w stylu wskaźnika. ### WhatsApp -WhatsApp działa przez kanał web gateway (`Baileys Web`). Uruchamia się automatycznie, gdy istnieje powiązana sesja. +WhatsApp działa przez kanał web bramy (Baileys Web). Uruchamia się automatycznie, gdy istnieje połączona sesja. ```json5 { @@ -165,7 +165,7 @@ WhatsApp działa przez kanał web gateway (`Baileys Web`). Uruchamia się automa ``` - 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 domyślny wybór zapasowego konta, gdy pasuje do skonfigurowanego identyfikatora konta. +- Opcjonalne `channels.whatsapp.defaultAccount` nadpisuje ten domyślny wybór zapasowy, gdy pasuje do skonfigurowanego identyfikatora konta. - Starszy katalog autoryzacji Baileys dla pojedynczego konta jest migrowany przez `openclaw doctor` do `whatsapp/default`. - Nadpisania per konto: `channels.whatsapp.accounts..sendReadReceipts`, `channels.whatsapp.accounts..dmPolicy`, `channels.whatsapp.accounts..allowFrom`. @@ -185,24 +185,24 @@ WhatsApp działa przez kanał web gateway (`Baileys Web`). Uruchamia się automa "*": { requireMention: true }, "-1001234567890": { allowFrom: ["@admin"], - systemPrompt: "Zachowuj zwięzłość odpowiedzi.", + systemPrompt: "Keep answers brief.", topics: { "99": { requireMention: false, skills: ["search"], - systemPrompt: "Trzymaj się tematu.", + systemPrompt: "Stay on topic.", }, }, }, }, customCommands: [ - { command: "backup", description: "Kopia zapasowa Git" }, - { command: "generate", description: "Utwórz obraz" }, + { command: "backup", description: "Git backup" }, + { command: "generate", description: "Create an image" }, ], historyLimit: 50, replyToMode: "first", // off | first | all | batched linkPreview: true, - streaming: "partial", // off | partial | block | progress (domyślnie: off; włącz jawnie, aby uniknąć limitów szybkości podglądu-edycji) + streaming: "partial", // off | partial | block | progress (default: off; opt in explicitly to avoid preview-edit rate limits) actions: { reactions: true, sendMessage: true }, reactionNotifications: "own", // off | own | all mediaMaxMb: 100, @@ -225,12 +225,12 @@ WhatsApp działa przez kanał web gateway (`Baileys Web`). Uruchamia się automa } ``` -- Token bota: `channels.telegram.botToken` lub `channels.telegram.tokenFile` (tylko zwykły plik; symlinki są odrzucane), z `TELEGRAM_BOT_TOKEN` jako wartością zapasową dla konta domyślnego. +- Token bota: `channels.telegram.botToken` lub `channels.telegram.tokenFile` (tylko zwykły plik; symlinki odrzucane), z `TELEGRAM_BOT_TOKEN` jako zapasowym źródłem dla konta domyślnego. - Opcjonalne `channels.telegram.defaultAccount` nadpisuje domyślny wybór konta, gdy pasuje do skonfigurowanego identyfikatora konta. -- W konfiguracjach wielokontowych (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 lub jest nieprawidłowe. -- `configWrites: false` blokuje zapisy konfiguracji inicjowane z Telegrama (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 [ACP Agents](/pl/tools/acp-agents#channel-specific-settings). -- Podglądy strumieni Telegram używają `sendMessage` + `editMessageText` (działa w czatach bezpośrednich i grupowych). +- W konfiguracjach wielokontowych (2+ identyfikatory kont) ustaw jawny domyślny wybór (`channels.telegram.defaultAccount` lub `channels.telegram.accounts.default`), aby uniknąć routingu zapasowego; `openclaw doctor` ostrzega, gdy tego brakuje lub 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 forów (użyj kanonicznego `chatId:topic:topicId` w `match.peer.id`). Semantyka pól jest współdzielona w [ACP Agents](/pl/tools/acp-agents#channel-specific-settings). +- Podglądy strumieni w Telegramie używają `sendMessage` + `editMessageText` (działa w czatach bezpośrednich i grupowych). - Zasady ponawiania: zobacz [Retry policy](/pl/concepts/retry). ### Discord @@ -278,7 +278,7 @@ WhatsApp działa przez kanał web gateway (`Baileys Web`). Uruchamia się automa requireMention: true, users: ["987654321098765432"], skills: ["docs"], - systemPrompt: "Tylko krótkie odpowiedzi.", + systemPrompt: "Short answers only.", }, }, }, @@ -286,7 +286,7 @@ WhatsApp działa przez kanał web gateway (`Baileys Web`). Uruchamia się automa historyLimit: 20, textChunkLimit: 2000, chunkMode: "length", // length | newline - streaming: "off", // off | partial | block | progress (progress mapuje się do partial na Discordzie) + streaming: "off", // off | partial | block | progress (progress maps to partial on Discord) maxLinesPerMessage: 17, ui: { components: { @@ -333,36 +333,36 @@ WhatsApp działa przez kanał web gateway (`Baileys Web`). Uruchamia się automa } ``` -- 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 `token` Discorda, używają tego tokenu do wywołania; ustawienia ponawiania/polityk konta nadal pochodzą z wybranego konta w aktywnej migawce runtime. +- Token: `channels.discord.token`, z `DISCORD_BOT_TOKEN` jako zapasowym źródłem dla konta domyślnego. +- Bezpośrednie wywołania wychodzące, które podają jawny `token` Discorda, używają tego tokena do wywołania; ustawienia ponawiania/zasad konta nadal pochodzą z wybranego konta w aktywnej migawce środowiska wykonawczego. - Opcjonalne `channels.discord.defaultAccount` nadpisuje domyślny wybór konta, gdy pasuje do skonfigurowanego identyfikatora konta. -- Używaj `user:` (DM) lub `channel:` (kanał guild); same identyfikatory numeryczne są odrzucane. -- Slugi guild są pisane małymi literami, a spacje zastępowane przez `-`; klucze kanałów używają wersji slug nazwy (bez `#`). Preferuj identyfikatory guild. -- Wiadomości napisane przez boty są domyślnie ignorowane. `allowBots: true` je włącza; użyj `allowBots: "mentions"`, aby akceptować tylko wiadomości od botów, które wzmiankują bota (własne wiadomości nadal są filtrowane). -- `channels.discord.guilds..ignoreOtherMentions` (oraz nadpisania kanałów) odrzuca wiadomości, które wzmiankują innego użytkownika lub rolę, ale nie bota (z wyłączeniem @everyone/@here). +- Użyj `user:` (DM) lub `channel:` (kanał guild) dla celów dostarczania; same numeryczne identyfikatory są odrzucane. +- Slugi guild są małymi literami ze spacjami zamienionymi na `-`; klucze kanałów używają nazwy w postaci slug (bez `#`). Preferuj identyfikatory guild. +- 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 filtrowane). +- `channels.discord.guilds..ignoreOtherMentions` (i 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ą mniej niż 2000 znaków. -- `channels.discord.threadBindings` steruje routingiem powiązanym z wątkami Discorda: - - `enabled`: nadpisanie Discorda dla funkcji sesji powiązanych z wątkiem (`/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age` oraz powiązane dostarczanie/routing) - - `idleHours`: nadpisanie Discorda dla automatycznego odpinania po bezczynności w godzinach (`0` wyłącza) - - `maxAgeHours`: nadpisanie Discorda dla sztywnego maksymalnego wieku w godzinach (`0` wyłącza) - - `spawnSubagentSessions`: przełącznik opt-in dla automatycznego tworzenia/powiązania wątku przez `sessions_spawn({ thread: true })` +- `channels.discord.threadBindings` steruje routingiem związanym z wątkami Discord: + - `enabled`: nadpisanie Discorda dla funkcji sesji związanych z wątkiem (`/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age` i dostarczanie/routing związany z wątkiem) + - `idleHours`: nadpisanie Discorda dla automatycznego odwiązywania po bezczynności w godzinach (`0` wyłącza) + - `maxAgeHours`: nadpisanie Discorda dla twardego maksymalnego wieku w godzinach (`0` wyłącza) + - `spawnSubagentSessions`: przełącznik opt-in dla automatycznego tworzenia/powiązywania wątków 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ółdzielona w [ACP Agents](/pl/tools/acp-agents#channel-specific-settings). - `channels.discord.ui.components.accentColor` ustawia kolor akcentu dla kontenerów Discord components v2. -- `channels.discord.voice` włącza rozmowy głosowe w kanałach Discorda oraz opcjonalne automatyczne dołączanie + nadpisania TTS. +- `channels.discord.voice` włącza rozmowy w kanałach głosowych Discord i opcjonalne auto-join + nadpisania TTS. - `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 odzyskać odbiór głosu przez opuszczenie i ponowne dołączenie do sesji głosowej po wielokrotnych błędach odszyfrowania. -- `channels.discord.streaming` to kanoniczny klucz trybu strumieniowania. Starsze wartości `streamMode` i boolowskie `streaming` są automatycznie migrowane. -- `channels.discord.autoPresence` mapuje dostępność runtime na obecność bota (healthy => online, degraded => idle, exhausted => dnd) i umożliwia opcjonalne nadpisania tekstu statusu. -- `channels.discord.dangerouslyAllowNameMatching` ponownie włącza dopasowywanie po zmiennej nazwie/tagu (tryb zgodności break-glass). -- `channels.discord.execApprovals`: natywne dla Discorda dostarczanie zatwierdzeń exec i autoryzacja zatwierdzających. +- OpenClaw dodatkowo próbuje odzyskać odbiór głosu przez opuszczenie i ponowne dołączenie do sesji głosowej po powtarzających się błędach deszyfrowania. +- `channels.discord.streaming` jest kanonicznym kluczem trybu strumieniowania. Starsze wartości `streamMode` i logiczne `streaming` są migrowane automatycznie. +- `channels.discord.autoPresence` mapuje dostępność środowiska wykonawczego na obecność bota (healthy => online, degraded => idle, exhausted => dnd) i pozwala na opcjonalne nadpisania tekstu statusu. +- `channels.discord.dangerouslyAllowNameMatching` ponownie włącza dopasowywanie po zmiennych nazwach/tagach (tryb zgodności typu break-glass). +- `channels.discord.execApprovals`: natywne dostarczanie zatwierdzeń exec w Discordzie i autoryzacja zatwierdzających. - `enabled`: `true`, `false` lub `"auto"` (domyślnie). W trybie auto zatwierdzenia exec aktywują się, gdy zatwierdzających można rozwiązać z `approvers` lub `commands.ownerAllowFrom`. - `approvers`: identyfikatory użytkowników Discorda uprawnionych do zatwierdzania żądań exec. Gdy pominięte, używane jest `commands.ownerAllowFrom`. - - `agentFilter`: opcjonalna lista zezwoleń identyfikatorów agentów. Pomiń, aby przekazywać zatwierdzenia dla wszystkich agentów. - - `sessionFilter`: opcjonalne wzorce kluczy sesji (podciąg lub regex). - - `target`: gdzie wysyłać prompty zatwierdzeń. `"dm"` (domyślnie) wysyła do DM zatwierdzających, `"channel"` wysyła do kanału źródłowego, `"both"` wysyła do obu. Gdy target obejmuje `"channel"`, przyciski mogą być używane tylko przez rozpoznanych zatwierdzających. - - `cleanupAfterResolve`: gdy `true`, usuwa DM zatwierdzeń po zatwierdzeniu, odrzuceniu lub przekroczeniu czasu. + - `agentFilter`: opcjonalna lista dozwolonych identyfikatorów agentów. Pomiń, aby przekazywać zatwierdzenia dla wszystkich agentów. + - `sessionFilter`: opcjonalne wzorce kluczy sesji (substring lub regex). + - `target`: gdzie wysyłać prośby o zatwierdzenie. `"dm"` (domyślnie) wysyła do DM zatwierdzających, `"channel"` wysyła do kanału źródłowego, `"both"` wysyła do obu. Gdy target zawiera `"channel"`, przyciski mogą być używane tylko przez rozwiązanych zatwierdzających. + - `cleanupAfterResolve`: gdy `true`, usuwa DM z zatwierdzeniami po zatwierdzeniu, odrzuceniu lub przekroczeniu czasu. -**Tryby powiadomień o reakcjach:** `off` (brak), `own` (wiadomości bota, domyślnie), `all` (wszystkie wiadomości), `allowlist` (od `guilds..users` we wszystkich wiadomościach). +**Tryby powiadomień o reakcjach:** `off` (brak), `own` (wiadomości bota, domyślnie), `all` (wszystkie wiadomości), `allowlist` (od `guilds..users` dla wszystkich wiadomości). ### Google Chat @@ -393,11 +393,11 @@ WhatsApp działa przez kanał web gateway (`Baileys Web`). Uruchamia się automa } ``` -- JSON konta usługi: inline (`serviceAccount`) lub z pliku (`serviceAccountFile`). -- Obsługiwany jest także SecretRef konta usługi (`serviceAccountRef`). -- Zapasowe wartości z env: `GOOGLE_CHAT_SERVICE_ACCOUNT` lub `GOOGLE_CHAT_SERVICE_ACCOUNT_FILE`. -- Używaj `spaces/` lub `users/` jako celów dostarczania. -- `channels.googlechat.dangerouslyAllowNameMatching` ponownie włącza dopasowywanie po zmiennym principalu email (tryb zgodności break-glass). +- JSON konta usługi: wbudowany (`serviceAccount`) lub oparty na pliku (`serviceAccountFile`). +- Obsługiwany jest także SecretRef dla konta usługi (`serviceAccountRef`). +- Zapasowe źródła z env: `GOOGLE_CHAT_SERVICE_ACCOUNT` lub `GOOGLE_CHAT_SERVICE_ACCOUNT_FILE`. +- Użyj `spaces/` lub `users/` dla celów dostarczania. +- `channels.googlechat.dangerouslyAllowNameMatching` ponownie włącza dopasowywanie po zmiennym adresie e-mail principal (tryb zgodności typu break-glass). ### Slack @@ -419,7 +419,7 @@ WhatsApp działa przez kanał web gateway (`Baileys Web`). Uruchamia się automa allowBots: false, users: ["U123"], skills: ["docs"], - systemPrompt: "Tylko krótkie odpowiedzi.", + systemPrompt: "Short answers only.", }, }, historyLimit: 50, @@ -449,7 +449,7 @@ WhatsApp działa przez kanał web gateway (`Baileys Web`). Uruchamia się automa chunkMode: "length", streaming: { mode: "partial", // off | partial | block | progress - nativeTransport: true, // używaj natywnego API strumieniowania Slacka, gdy mode=partial + nativeTransport: true, // użyj natywnego API strumieniowego Slacka, gdy mode=partial }, mediaMaxMb: 20, execApprovals: { @@ -464,34 +464,34 @@ WhatsApp działa przez kanał web gateway (`Baileys Web`). Uruchamia się automa } ``` -- **Tryb Socket** wymaga zarówno `botToken`, jak i `appToken` (`SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN` jako zapasowe wartości env dla konta domyślnego). -- **Tryb HTTP** wymaga `botToken` oraz `signingSecret` (na poziomie głównym lub per konto). +- **Socket mode** wymaga zarówno `botToken`, jak i `appToken` (`SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN` jako zapasowe źródło env dla konta domyślnego). +- **HTTP mode** wymaga `botToken` plus `signingSecret` (na poziomie głównym lub per konto). - `botToken`, `appToken`, `signingSecret` i `userToken` akceptują zwykłe - ciągi znaków lub obiekty SecretRef. -- Migawki kont Slacka udostępniają pola źródła/statusu per poświadczenie, takie jak - `botTokenSource`, `botTokenStatus`, `appTokenStatus` oraz, w trybie HTTP, + stringi lub obiekty SecretRef. +- Migawki kont Slacka 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/runtime nie mogła + skonfigurowane przez SecretRef, ale bieżąca ścieżka polecenia/środowiska wykonawczego nie mogła rozwiązać wartości sekretu. -- `configWrites: false` blokuje zapisy konfiguracji inicjowane ze Slacka. +- `configWrites: false` blokuje zapisy konfiguracji inicjowane przez Slacka. - Opcjonalne `channels.slack.defaultAccount` nadpisuje domyślny wybór konta, gdy pasuje do skonfigurowanego identyfikatora konta. -- `channels.slack.streaming.mode` to kanoniczny klucz trybu strumieniowania Slacka. `channels.slack.streaming.nativeTransport` steruje natywnym transportem strumieniowania Slacka. Starsze wartości `streamMode`, boolowskie `streaming` i `nativeStreaming` są automatycznie migrowane. -- Używaj `user:` (DM) lub `channel:` jako celów dostarczania. +- `channels.slack.streaming.mode` jest kanonicznym kluczem trybu strumieniowania Slacka. `channels.slack.streaming.nativeTransport` steruje natywnym transportem strumieniowym Slacka. Starsze wartości `streamMode`, logiczne `streaming` i `nativeStreaming` są migrowane automatycznie. +- Użyj `user:` (DM) lub `channel:` dla celów dostarczania. **Tryby powiadomień o reakcjach:** `off`, `own` (domyślnie), `all`, `allowlist` (z `reactionAllowlist`). -**Izolacja sesji wątków:** `thread.historyScope` jest per wątek (domyślnie) lub współdzielone w ramach kanału. `thread.inheritParent` kopiuje transkrypt kanału nadrzędnego do nowych wątków. +**Izolacja sesji wątków:** `thread.historyScope` jest per wątek (domyślnie) lub współdzielone w ramach kanału. `thread.inheritParent` kopiuje transkrypcję kanału nadrzędnego do nowych wątków. -- Natywne strumieniowanie Slacka oraz status wątku Slacka w stylu „is typing...” wymagają docelowego wątku odpowiedzi. DM najwyższego poziomu domyślnie pozostają poza wątkiem, więc używają `typingReaction` lub zwykłego dostarczania zamiast podglądu w stylu wątku. -- `typingReaction` dodaje tymczasową reakcję do przychodzącej wiadomości Slacka podczas generowania odpowiedzi, a następnie usuwa ją po zakończeniu. Użyj shortcode emoji Slacka, na przykład `"hourglass_flowing_sand"`. -- `channels.slack.execApprovals`: natywne dla Slacka dostarczanie zatwierdzeń exec i autoryzacja zatwierdzających. Ten sam schemat co Discord: `enabled` (`true`/`false`/`"auto"`), `approvers` (identyfikatory użytkowników Slacka), `agentFilter`, `sessionFilter` i `target` (`"dm"`, `"channel"` lub `"both"`). +- Natywne strumieniowanie Slacka wraz ze statusem wątku Slacka w stylu asystenta „is typing...” wymaga celu odpowiedzi w wątku. Górnopoziomowe DM domyślnie pozostają poza wątkiem, więc zamiast podglądu w stylu wątku używają `typingReaction` lub zwykłego dostarczenia. +- `typingReaction` dodaje tymczasową reakcję do przychodzącej wiadomości Slacka podczas generowania odpowiedzi, a następnie usuwa ją po zakończeniu. Użyj shortcode emoji Slacka, np. `"hourglass_flowing_sand"`. +- `channels.slack.execApprovals`: natywne dostarczanie zatwierdzeń exec w Slacku i autoryzacja zatwierdzających. Ten sam schemat co Discord: `enabled` (`true`/`false`/`"auto"`), `approvers` (identyfikatory użytkowników Slacka), `agentFilter`, `sessionFilter` i `target` (`"dm"`, `"channel"` lub `"both"`). -| Grupa akcji | Domyślnie | Uwagi | -| ----------- | --------- | ---------------------- | +| Grupa akcji | Domyślnie | Uwagi | +| ----------- | --------- | --------------------- | | reactions | włączone | Reagowanie + lista reakcji | | messages | włączone | Odczyt/wysyłanie/edycja/usuwanie | | pins | włączone | Przypnij/odepnij/lista | -| memberInfo | włączone | Informacje o członku | +| memberInfo | włączone | Informacje o członku | | emojiList | włączone | Lista niestandardowych emoji | ### Mattermost @@ -516,7 +516,7 @@ Mattermost jest dostarczany jako plugin: `openclaw plugins install @openclaw/mat native: true, // opt-in nativeSkills: true, callbackPath: "/api/channels/mattermost/command", - // Opcjonalny jawny URL dla wdrożeń za reverse proxy/publicznych + // Opcjonalny jawny URL dla wdrożeń z reverse proxy/publicznych callbackUrl: "https://gateway.example.com/api/channels/mattermost/command", }, textChunkLimit: 4000, @@ -526,22 +526,22 @@ Mattermost jest dostarczany jako plugin: `openclaw plugins install @openclaw/mat } ``` -Tryby czatu: `oncall` (odpowiada na wzmiankę @, domyślnie), `onmessage` (każda wiadomość), `onchar` (wiadomości zaczynające się od prefiksu wyzwalającego). +Tryby czatu: `oncall` (odpowiada przy wzmiance @, domyślnie), `onmessage` (każda wiadomość), `onchar` (wiadomości zaczynające się od prefiksu wyzwalacza). Gdy natywne polecenia Mattermost są włączone: - `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 wywołania slash callback są uwierzytelniane przy użyciu tokenów per polecenie zwracanych - przez Mattermost podczas rejestracji poleceń slash. Jeśli rejestracja się nie powiedzie lub żadne - polecenia nie zostaną aktywowane, OpenClaw odrzuci callbacki z komunikatem +- `commands.callbackUrl` musi wskazywać na endpoint bramy OpenClaw i być osiągalny z serwera Mattermost. +- Natywne wywołania slash callbacks są uwierzytelniane przy użyciu tokenów per polecenie zwracanych + przez Mattermost podczas rejestracji slash command. Jeśli rejestracja się nie powiedzie lub żadne + polecenia nie zostaną aktywowane, OpenClaw odrzuci callbacki z błędem `Unauthorized: invalid command token.` -- Dla prywatnych/tailnet/wewnętrznych hostów callback Mattermost może wymagać, +- Dla prywatnych/tailnet/wewnętrznych hostów callbacków Mattermost może wymagać, aby `ServiceSettings.AllowedUntrustedInternalConnections` zawierało host/domenę callbacku. Używaj wartości host/domena, a nie pełnych URL-i. -- `channels.mattermost.configWrites`: zezwalaj lub odmawiaj zapisów konfiguracji inicjowanych z Mattermost. -- `channels.mattermost.requireMention`: wymagaj `@mention` przed odpowiedzią na kanałach. -- `channels.mattermost.groups..requireMention`: nadpisanie wymogu wzmianki per kanał (`"*"` dla domyślnego). +- `channels.mattermost.configWrites`: zezwala lub zabrania zapisów konfiguracji inicjowanych przez Mattermost. +- `channels.mattermost.requireMention`: wymaga `@mention` przed odpowiedzią w kanałach. +- `channels.mattermost.groups..requireMention`: nadpisanie bramkowania wzmiankami per kanał (`"*"` dla domyślnego). - Opcjonalne `channels.mattermost.defaultAccount` nadpisuje domyślny wybór konta, gdy pasuje do skonfigurowanego identyfikatora konta. ### Signal @@ -551,7 +551,7 @@ Gdy natywne polecenia Mattermost są włączone: channels: { signal: { enabled: true, - account: "+15555550123", // opcjonalne powiązanie konta + account: "+15555550123", // opcjonalne powiązanie z kontem dmPolicy: "pairing", allowFrom: ["+15551234567", "uuid:123e4567-e89b-12d3-a456-426614174000"], configWrites: true, @@ -565,8 +565,8 @@ Gdy natywne polecenia Mattermost są włączone: **Tryby powiadomień o reakcjach:** `off`, `own` (domyślnie), `all`, `allowlist` (z `reactionAllowlist`). -- `channels.signal.account`: przypina uruchomienie kanału do określonej tożsamości konta Signal. -- `channels.signal.configWrites`: zezwalaj lub odmawiaj zapisów konfiguracji inicjowanych z Signal. +- `channels.signal.account`: przypina uruchamianie kanału do określonej tożsamości konta Signal. +- `channels.signal.configWrites`: zezwala lub zabrania zapisów konfiguracji inicjowanych przez Signal. - Opcjonalne `channels.signal.defaultAccount` nadpisuje domyślny wybór konta, gdy pasuje do skonfigurowanego identyfikatora konta. ### BlueBubbles @@ -588,8 +588,8 @@ BlueBubbles to zalecana ścieżka iMessage (oparta na pluginie, konfigurowana w - Podstawowe ścieżki kluczy opisane tutaj: `channels.bluebubbles`, `channels.bluebubbles.dmPolicy`. - Opcjonalne `channels.bluebubbles.defaultAccount` nadpisuje domyślny wybór konta, gdy pasuje do skonfigurowanego identyfikatora konta. -- Wpisy najwyższego poziomu `bindings[]` z `type: "acp"` mogą wiązać rozmowy BlueBubbles z trwałymi sesjami ACP. Użyj uchwytu BlueBubbles lub ciągu docelowego (`chat_id:*`, `chat_guid:*`, `chat_identifier:*`) w `match.peer.id`. Współdzielona semantyka pól: [ACP Agents](/pl/tools/acp-agents#channel-specific-settings). -- Pełna konfiguracja kanału BlueBubbles jest opisana w [BlueBubbles](/pl/channels/bluebubbles). +- Wpisy najwyższego poziomu `bindings[]` z `type: "acp"` mogą wiązać konwersacje BlueBubbles z trwałymi sesjami ACP. Użyj uchwytu BlueBubbles lub ciągu celu (`chat_id:*`, `chat_guid:*`, `chat_identifier:*`) w `match.peer.id`. Współdzielona semantyka pól: [ACP Agents](/pl/tools/acp-agents#channel-specific-settings). +- Pełna konfiguracja kanału BlueBubbles jest udokumentowana w [BlueBubbles](/pl/channels/bluebubbles). ### iMessage @@ -621,11 +621,11 @@ OpenClaw uruchamia `imsg rpc` (JSON-RPC przez stdio). Nie jest wymagany daemon a - Wymaga Full Disk Access do bazy danych Messages. - Preferuj cele `chat_id:`. Użyj `imsg chats --limit 20`, aby wyświetlić listę czatów. -- `cliPath` może wskazywać na wrapper SSH; ustaw `remoteHost` (`host` lub `user@host`) dla pobierania załączników przez SCP. +- `cliPath` może wskazywać na wrapper SSH; ustaw `remoteHost` (`host` lub `user@host`) do pobierania załączników SCP. - `attachmentRoots` i `remoteAttachmentRoots` ograniczają ścieżki przychodzących załączników (domyślnie: `/Users/*/Library/Messages/Attachments`). -- SCP używa ścisłego sprawdzania klucza hosta, więc upewnij się, że klucz hosta pośredniczącego już istnieje w `~/.ssh/known_hosts`. -- `channels.imessage.configWrites`: zezwalaj lub odmawiaj zapisów konfiguracji inicjowanych z iMessage. -- Wpisy najwyższego poziomu `bindings[]` z `type: "acp"` mogą wiązać rozmowy iMessage z trwałymi sesjami ACP. Użyj znormalizowanego uchwytu lub jawnego celu czatu (`chat_id:*`, `chat_guid:*`, `chat_identifier:*`) w `match.peer.id`. Współdzielona semantyka pól: [ACP Agents](/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 lub zabrania zapisów konfiguracji inicjowanych przez iMessage. +- Wpisy najwyższego poziomu `bindings[]` z `type: "acp"` mogą wiązać konwersacje iMessage z trwałymi sesjami ACP. Użyj znormalizowanego uchwytu lub jawnego celu czatu (`chat_id:*`, `chat_guid:*`, `chat_identifier:*`) w `match.peer.id`. Współdzielona semantyka pól: [ACP Agents](/pl/tools/acp-agents#channel-specific-settings). @@ -638,7 +638,7 @@ exec ssh -T gateway-host imsg "$@" ### Matrix -Matrix jest rozszerzeniem i jest konfigurowany w `channels.matrix`. +Matrix jest obsługiwany przez rozszerzenie i konfigurowany w `channels.matrix`. ```json5 { @@ -669,24 +669,24 @@ Matrix jest rozszerzeniem i jest konfigurowany w `channels.matrix`. ``` - Uwierzytelnianie tokenem używa `accessToken`; uwierzytelnianie hasłem używa `userId` + `password`. -- `channels.matrix.proxy` kieruje ruch HTTP Matrix przez jawny proxy HTTP(S). Nazwane konta mogą to nadpisać przez `channels.matrix.accounts..proxy`. -- `channels.matrix.network.dangerouslyAllowPrivateNetwork` pozwala na prywatne/wewnętrzne homeservery. `proxy` i to opt-in sieciowe są niezależnymi kontrolami. +- `channels.matrix.proxy` kieruje ruch HTTP Matrix przez jawny proxy HTTP(S). Nazwane konta mogą go nadpisywać przez `channels.matrix.accounts..proxy`. +- `channels.matrix.network.dangerouslyAllowPrivateNetwork` zezwala na prywatne/wewnętrzne homeserwery. `proxy` i ten opt-in sieciowy są niezależnymi mechanizmami. - `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` lub `autoJoin: "always"`. -- `channels.matrix.execApprovals`: natywne dla Matrix dostarczanie zatwierdzeń exec i autoryzacja zatwierdzających. +- `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 dostarczanie zatwierdzeń exec w Matrix i autoryzacja zatwierdzających. - `enabled`: `true`, `false` lub `"auto"` (domyślnie). W trybie auto zatwierdzenia exec aktywują się, gdy zatwierdzających można rozwiązać z `approvers` lub `commands.ownerAllowFrom`. - `approvers`: identyfikatory użytkowników Matrix (np. `@owner:example.org`) uprawnionych do zatwierdzania żądań exec. - - `agentFilter`: opcjonalna lista zezwoleń identyfikatorów agentów. Pomiń, aby przekazywać zatwierdzenia dla wszystkich agentów. - - `sessionFilter`: opcjonalne wzorce kluczy sesji (podciąg lub regex). - - `target`: gdzie wysyłać prompty zatwierdzeń. `"dm"` (domyślnie), `"channel"` (pokój źródłowy) lub `"both"`. + - `agentFilter`: opcjonalna lista dozwolonych identyfikatorów agentów. Pomiń, aby przekazywać zatwierdzenia dla wszystkich agentów. + - `sessionFilter`: opcjonalne wzorce kluczy sesji (substring lub regex). + - `target`: gdzie wysyłać prośby o zatwierdzenie. `"dm"` (domyślnie), `"channel"` (pokój źródłowy) lub `"both"`. - Nadpisania per konto: `channels.matrix.accounts..execApprovals`. -- `channels.matrix.dm.sessionScope` steruje tym, jak DM Matrix grupują się w sesje: `per-user` (domyślnie) współdzieli według routowanego peer, podczas gdy `per-room` izoluje każdy pokój DM. -- Sondy statusu Matrix i wyszukiwania katalogowe na żywo używają tych samych zasad proxy co ruch runtime. -- Pełna konfiguracja Matrix, zasady kierowania i przykłady konfiguracji są opisane w [Matrix](/pl/channels/matrix). +- `channels.matrix.dm.sessionScope` kontroluje, jak DM Matrix są grupowane w sesje: `per-user` (domyślnie) współdzieli według routowanego peera, podczas gdy `per-room` izoluje każdy pokój DM. +- Sondy statusu Matrix i wyszukiwania w aktywnym katalogu używają tych samych zasad proxy co ruch środowiska wykonawczego. +- Pełna konfiguracja Matrix, reguły kierowania i przykłady konfiguracji są udokumentowane w [Matrix](/pl/channels/matrix). ### Microsoft Teams -Microsoft Teams jest rozszerzeniem i jest konfigurowany w `channels.msteams`. +Microsoft Teams jest obsługiwany przez rozszerzenie i konfigurowany w `channels.msteams`. ```json5 { @@ -694,7 +694,7 @@ Microsoft Teams jest rozszerzeniem i jest konfigurowany w `channels.msteams`. msteams: { enabled: true, configWrites: true, - // appId, appPassword, tenantId, webhook, zasady zespołu/kanału: + // appId, appPassword, tenantId, webhook, zasady zespołów/kanałów: // zobacz /channels/msteams }, }, @@ -702,11 +702,11 @@ Microsoft Teams jest rozszerzeniem i jest konfigurowany w `channels.msteams`. ``` - Podstawowe ścieżki kluczy opisane tutaj: `channels.msteams`, `channels.msteams.configWrites`. -- Pełna konfiguracja Teams (poświadczenia, webhook, zasady DM/grup, nadpisania per zespół/per kanał) jest opisana w [Microsoft Teams](/pl/channels/msteams). +- Pełna konfiguracja Teams (poświadczenia, webhook, zasady DM/grup, nadpisania per zespół/per kanał) jest udokumentowana w [Microsoft Teams](/pl/channels/msteams). ### IRC -IRC jest rozszerzeniem i jest konfigurowany w `channels.irc`. +IRC jest obsługiwany przez rozszerzenie i konfigurowany w `channels.irc`. ```json5 { @@ -729,11 +729,11 @@ IRC jest rozszerzeniem i jest konfigurowany w `channels.irc`. - Podstawowe ścieżki kluczy opisane tutaj: `channels.irc`, `channels.irc.dmPolicy`, `channels.irc.configWrites`, `channels.irc.nickserv.*`. - Opcjonalne `channels.irc.defaultAccount` nadpisuje domyślny wybór konta, gdy pasuje do skonfigurowanego identyfikatora konta. -- Pełna konfiguracja kanału IRC (host/port/TLS/kanały/listy zezwoleń/wymóg wzmianki) jest opisana w [IRC](/pl/channels/irc). +- Pełna konfiguracja kanału IRC (host/port/TLS/kanały/listy dozwolonych/bramkowanie wzmiankami) jest udokumentowana w [IRC](/pl/channels/irc). ### Wiele kont (wszystkie kanały) -Uruchamiaj wiele kont na kanał (każde z własnym `accountId`): +Uruchom wiele kont na kanał (każde z własnym `accountId`): ```json5 { @@ -741,11 +741,11 @@ Uruchamiaj wiele kont na kanał (każde z własnym `accountId`): telegram: { accounts: { default: { - name: "Główny bot", + name: "Primary bot", botToken: "123456:ABC...", }, alerts: { - name: "Bot alertów", + name: "Alerts bot", botToken: "987654:XYZ...", }, }, @@ -755,27 +755,27 @@ Uruchamiaj wiele kont na kanał (każde z własnym `accountId`): ``` - `default` jest używane, gdy `accountId` jest pominięte (CLI + routing). -- Tokeny env dotyczą tylko konta **default**. -- Bazowe ustawienia kanału mają zastosowanie do wszystkich kont, chyba że zostaną nadpisane per konto. +- Tokeny z env dotyczą tylko konta **default**. +- Bazowe ustawienia kanału dotyczą wszystkich kont, chyba że zostaną nadpisane 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` (lub onboarding kanału), gdy nadal masz konfigurację kanału najwyższego poziomu dla pojedynczego konta, OpenClaw najpierw promuje wartości najwyższego poziomu dotyczące pojedynczego konta do mapy kont kanału, aby oryginalne konto nadal działało. Większość kanałów przenosi je do `channels..accounts.default`; Matrix może zamiast tego zachować istniejący pasujący nazwany/domyslny cel. -- Istniejące powiązania tylko kanałowe (bez `accountId`) nadal będą pasować do konta domyślnego; powiązania zakresowane kontem pozostają opcjonalne. -- `openclaw doctor --fix` również naprawia mieszane kształty, przenosząc wartości najwyższego poziomu dotyczące pojedynczego 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/domyslny cel. +- Jeśli dodasz konto inne niż domyślne przez `openclaw channels add` (lub onboarding kanału), nadal mając jednokontową konfigurację na najwyższym poziomie, OpenClaw najpierw promuje wartości najwyższego poziomu specyficzne dla pojedynczego konta do mapy kont kanału, aby oryginalne konto nadal działało. Większość kanałów przenosi je do `channels..accounts.default`; Matrix może zamiast tego zachować istniejący pasujący nazwany/domyslny cel. +- Istniejące powiązania tylko kanałowe (bez `accountId`) nadal pasują do konta domyślnego; powiązania z zakresem konta pozostają opcjonalne. +- `openclaw doctor --fix` także naprawia mieszane kształty, przenosząc wartości najwyższego poziomu specyficzne dla pojedynczego 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/domyslny cel. ### Inne kanały rozszerzeń Wiele kanałów rozszerzeń jest konfigurowanych jako `channels.` i opisanych na ich dedykowanych stronach kanałów (na przykład Feishu, Matrix, LINE, Nostr, Zalo, Nextcloud Talk, Synology Chat i Twitch). Zobacz pełny indeks kanałów: [Channels](/pl/channels). -### Wymóg wzmianki w czatach grupowych +### Bramkowanie wzmiankami w czatach grupowych -Wiadomości grupowe domyślnie **wymagają wzmianki** (wzmianka z metadanych lub bezpieczne wzorce regex). Dotyczy WhatsApp, Telegram, Discord, Google Chat i czatów grupowych iMessage. +Wiadomości grupowe domyślnie **wymagają wzmianki** (wzmianka w metadanych lub bezpieczne wzorce regex). Dotyczy czatów grupowych WhatsApp, Telegram, Discord, Google Chat i iMessage. **Typy wzmianek:** -- **Wzmianki z metadanych**: natywne wzmianki @ platformy. Ignorowane w trybie self-chat WhatsApp. +- **Wzmianki w metadanych**: natywne wzmianki @ platformy. Ignorowane w trybie self-chat WhatsApp. - **Wzorce tekstowe**: bezpieczne wzorce regex w `agents.list[].groupChat.mentionPatterns`. Nieprawidłowe wzorce i niebezpieczne zagnieżdżone powtórzenia są ignorowane. -- Wymóg wzmianki jest egzekwowany tylko wtedy, gdy wykrycie jest możliwe (natywne wzmianki lub co najmniej jeden wzorzec). +- Bramkowanie wzmiankami jest egzekwowane tylko wtedy, gdy wykrywanie jest możliwe (natywne wzmianki lub co najmniej jeden wzorzec). ```json5 { @@ -788,7 +788,7 @@ Wiadomości grupowe domyślnie **wymagają wzmianki** (wzmianka z metadanych lub } ``` -`messages.groupChat.historyLimit` ustawia globalną wartość domyślną. Kanały mogą to nadpisać przez `channels..historyLimit` (lub per konto). Ustaw `0`, aby wyłączyć. +`messages.groupChat.historyLimit` ustawia globalną wartość domyślną. Kanały mogą ją nadpisywać przez `channels..historyLimit` (lub per konto). Ustaw `0`, aby wyłączyć. #### Limity historii DM @@ -805,7 +805,7 @@ Wiadomości grupowe domyślnie **wymagają wzmianki** (wzmianka z metadanych lub } ``` -Rozwiązywanie: nadpisanie per DM → domyślne dostawcy → brak limitu (zachowaj wszystko). +Rozstrzyganie: nadpisanie per DM → domyślna wartość dostawcy → brak limitu (zachowywane wszystko). Obsługiwane: `telegram`, `whatsapp`, `discord`, `slack`, `signal`, `imessage`, `msteams`. @@ -832,21 +832,21 @@ Dodaj własny numer do `allowFrom`, aby włączyć tryb self-chat (ignoruje naty } ``` -### Commands (obsługa poleceń na czacie) +### Commands (obsługa poleceń czatu) ```json5 { commands: { native: "auto", // rejestruj natywne polecenia, gdy są obsługiwane - nativeSkills: "auto", // rejestruj natywne polecenia Skills, gdy są obsługiwane - text: true, // analizuj /commands w wiadomościach czatu - bash: false, // zezwól na ! (alias: /bash) + nativeSkills: "auto", // rejestruj natywne polecenia skill, gdy są obsługiwane + text: true, // parsuj /commands w wiadomościach czatu + bash: false, // zezwalaj na ! (alias: /bash) bashForegroundMs: 2000, - config: false, // zezwól na /config - mcp: false, // zezwól na /mcp - plugins: false, // zezwól na /plugins - debug: false, // zezwól na /debug - restart: true, // zezwól na /restart + narzędzie restartu gateway + config: false, // zezwalaj na /config + mcp: false, // zezwalaj na /mcp + plugins: false, // zezwalaj na /plugins + debug: false, // zezwalaj na /debug + restart: true, // zezwalaj na /restart + narzędzie restartu bramy ownerAllowFrom: ["discord:123456789012345678"], ownerDisplay: "raw", // raw | hash ownerDisplaySecret: "${OWNER_ID_HASH_SECRET}", @@ -862,26 +862,26 @@ Dodaj własny numer do `allowFrom`, aby włączyć tryb self-chat (ignoruje naty - Ten blok konfiguruje powierzchnie poleceń. Bieżący katalog wbudowanych + bundled poleceń znajdziesz w [Slash Commands](/pl/tools/slash-commands). -- Ta strona jest **odwołaniem do kluczy konfiguracji**, a nie pełnym katalogiem poleceń. Polecenia należące do kanału/pluginu, takie jak QQ Bot `/bot-ping` `/bot-help` `/bot-logs`, LINE `/card`, device-pair `/pair`, memory `/dreaming`, phone-control `/phone` i Talk `/voice`, są opisane na ich stronach kanałów/pluginów oraz w [Slash Commands](/pl/tools/slash-commands). -- Polecenia tekstowe muszą być **samodzielnymi** wiadomościami z wiodącym `/`. +- Ta strona jest **dokumentacją referencyjną 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` i Talk `/voice`, są dokumentowane na ich stronach kanałów/pluginów oraz w [Slash Commands](/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. -- `nativeSkills: "auto"` włącza natywne polecenia Skills dla Discord/Telegram, pozostawia Slack wyłączony. +- `nativeSkills: "auto"` włącza natywne polecenia skill dla Discord/Telegram, pozostawia Slack wyłączony. - Nadpisanie per kanał: `channels.discord.commands.native` (bool lub `"auto"`). `false` czyści wcześniej zarejestrowane polecenia. -- Nadpisz rejestrację natywnych poleceń Skills per kanał przez `channels..commands.nativeSkills`. +- Nadpisz rejestrację natywnych skill per kanał przez `channels..commands.nativeSkills`. - `channels.telegram.customCommands` dodaje dodatkowe wpisy menu bota Telegram. -- `bash: true` włącza `! ` dla powłoki hosta. Wymaga `tools.elevated.enabled` i nadawcy w `tools.elevated.allowFrom.`. -- `config: true` włącza `/config` (odczyt/zapis `openclaw.json`). Dla klientów gateway `chat.send` trwałe zapisy `/config set|unset` wymagają także `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ądzanej przez OpenClaw w `mcp.servers`. +- `bash: true` włącza `! ` dla powłoki hosta. Wymaga `tools.elevated.enabled` oraz nadawcy w `tools.elevated.allowFrom.`. +- `config: true` włącza `/config` (odczyt/zapis `openclaw.json`). Dla klientów bramy `chat.send`, trwałe zapisy `/config set|unset` wymagają także `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` dla wykrywania pluginów, instalacji i sterowania włączaniem/wyłączaniem. -- `channels..configWrites` steruje mutacjami konfiguracji per kanał (domyślnie: true). -- Dla kanałów wielokontowych `channels..accounts..configWrites` także steruje zapisami kierowanymi do tego konta (na przykład `/allowlist --config --account ` lub `/config set channels..accounts....`). -- `restart: false` wyłącza `/restart` i akcje narzędzia restartu gateway. Domyślnie: `true`. -- `ownerAllowFrom` to jawna lista zezwoleń właściciela dla poleceń/narzędzi tylko dla właściciela. Jest oddzielna od `allowFrom`. -- `ownerDisplay: "hash"` hashuje identyfikatory właściciela w system prompt. Ustaw `ownerDisplaySecret`, aby sterować hashowaniem. -- `allowFrom` jest per dostawca. Gdy jest ustawione, jest **jedynym** źródłem autoryzacji (listy zezwoleń/parowanie kanału oraz `useAccessGroups` są ignorowane). +- `channels..configWrites` bramkuje mutacje konfiguracji per kanał (domyślnie: true). +- Dla kanałów wielokontowych `channels..accounts..configWrites` także bramkuje zapisy, które dotyczą tego konta (na przykład `/allowlist --config --account ` lub `/config set channels..accounts....`). +- `restart: false` wyłącza `/restart` i akcje narzędzia restartu bramy. Domyślnie: `true`. +- `ownerAllowFrom` to jawna lista dozwolonych właściciela dla poleceń/narzędzi tylko dla właściciela. Jest oddzielna od `allowFrom`. +- `ownerDisplay: "hash"` hashuje identyfikatory właścicieli w system prompt. Ustaw `ownerDisplaySecret`, aby sterować hashowaniem. +- `allowFrom` jest per dostawca. Jeśli jest ustawione, jest **jedynym** źródłem autoryzacji (listy dozwolonych/parowanie kanału i `useAccessGroups` są ignorowane). - `useAccessGroups: false` pozwala poleceniom omijać zasady grup dostępu, gdy `allowFrom` nie jest ustawione. - Mapa dokumentacji poleceń: - - wbudowany + bundled katalog: [Slash Commands](/pl/tools/slash-commands) + - katalog wbudowany + bundled: [Slash Commands](/pl/tools/slash-commands) - powierzchnie poleceń specyficzne dla kanału: [Channels](/pl/channels) - polecenia QQ Bot: [QQ Bot](/pl/channels/qqbot) - polecenia parowania: [Pairing](/pl/channels/pairing) @@ -896,7 +896,7 @@ Dodaj własny numer do `allowFrom`, aby włączyć tryb self-chat (ignoruje naty ### `agents.defaults.workspace` -Domyślnie: `~/.openclaw/workspace`. +Wartość domyślna: `~/.openclaw/workspace`. ```json5 { @@ -906,7 +906,7 @@ Domyślnie: `~/.openclaw/workspace`. ### `agents.defaults.repoRoot` -Opcjonalny katalog główny repozytorium pokazywany w wierszu Runtime w system prompt. Jeśli nie jest ustawiony, OpenClaw wykrywa go automatycznie, idąc w górę od workspace. +Opcjonalny katalog główny repozytorium pokazywany w wierszu Runtime system prompt. Jeśli nie jest ustawiony, OpenClaw wykrywa go automatycznie, przechodząc w górę od workspace. ```json5 { @@ -916,7 +916,7 @@ Opcjonalny katalog główny repozytorium pokazywany w wierszu Runtime w system p ### `agents.defaults.skills` -Opcjonalna domyślna lista zezwoleń Skills dla agentów, które nie ustawiają +Opcjonalna domyślna lista dozwolonych Skills dla agentów, które nie ustawiają `agents.list[].skills`. ```json5 @@ -926,16 +926,16 @@ Opcjonalna domyślna lista zezwoleń Skills dla agentów, które nie ustawiają list: [ { id: "writer" }, // dziedziczy github, weather { id: "docs", skills: ["docs-search"] }, // zastępuje wartości domyślne - { id: "locked-down", skills: [] }, // bez Skills + { id: "locked-down", skills: [] }, // bez skills ], }, } ``` - Pomiń `agents.defaults.skills`, aby domyślnie nie ograniczać Skills. -- Pomiń `agents.list[].skills`, aby dziedziczyć wartości domyślne. +- Pomiń `agents.list[].skills`, aby odziedziczyć wartości domyślne. - Ustaw `agents.list[].skills: []`, aby nie mieć żadnych Skills. -- Niepusta lista `agents.list[].skills` jest ostatecznym zbiorem dla tego agenta; nie +- Niepusta lista `agents.list[].skills` jest ostatecznym zestawem dla tego agenta; nie łączy się z wartościami domyślnymi. ### `agents.defaults.skipBootstrap` @@ -950,9 +950,9 @@ Wyłącza automatyczne tworzenie plików bootstrap workspace (`AGENTS.md`, `SOUL ### `agents.defaults.contextInjection` -Steruje tym, kiedy pliki bootstrap workspace są wstrzykiwane do system prompt. Domyślnie: `"always"`. +Określa, kiedy pliki bootstrap workspace są wstrzykiwane do system prompt. Domyślnie: `"always"`. -- `"continuation-skip"`: bezpieczne tury kontynuacji (po zakończonej odpowiedzi asystenta) pomijają ponowne wstrzykiwanie bootstrap workspace, zmniejszając rozmiar promptu. Uruchomienia heartbeat i ponowne próby po kompaktowaniu nadal odbudowują kontekst. +- `"continuation-skip"`: bezpieczne tury kontynuacji (po zakończonej odpowiedzi asystenta) pomijają ponowne wstrzykiwanie bootstrap workspace, zmniejszając rozmiar prompt. Uruchomienia heartbeat i ponowne próby po kompaktacji nadal odbudowują kontekst. ```json5 { @@ -962,7 +962,7 @@ Steruje tym, kiedy pliki bootstrap workspace są wstrzykiwane do system prompt. ### `agents.defaults.bootstrapMaxChars` -Maksymalna liczba znaków na plik bootstrap workspace przed obcięciem. Domyślnie: `20000`. +Maksymalna liczba znaków na plik bootstrap workspace przed przycięciem. Domyślnie: `20000`. ```json5 { @@ -972,7 +972,7 @@ Maksymalna liczba znaków na plik bootstrap workspace przed obcięciem. Domyśln ### `agents.defaults.bootstrapTotalMaxChars` -Maksymalna łączna liczba znaków wstrzykiwanych ze wszystkich plików bootstrap workspace. Domyślnie: `150000`. +Maksymalna łączna liczba znaków wstrzykniętych we wszystkich plikach bootstrap workspace. Domyślnie: `150000`. ```json5 { @@ -982,12 +982,12 @@ Maksymalna łączna liczba znaków wstrzykiwanych ze wszystkich plików bootstra ### `agents.defaults.bootstrapPromptTruncationWarning` -Steruje widocznym dla agenta tekstem ostrzegawczym, gdy kontekst bootstrap zostanie obcięty. +Steruje widocznym dla agenta tekstem ostrzeżenia, gdy kontekst bootstrap jest przycinany. Domyślnie: `"once"`. -- `"off"`: nigdy nie wstrzykuj tekstu ostrzegawczego do system prompt. -- `"once"`: wstrzyknij ostrzeżenie raz dla każdej unikalnej sygnatury obcięcia (zalecane). -- `"always"`: wstrzykuj ostrzeżenie przy każdym uruchomieniu, gdy istnieje obcięcie. +- `"off"`: nigdy nie wstrzykuje tekstu ostrzeżenia do system prompt. +- `"once"`: wstrzykuje ostrzeżenie raz dla każdej unikalnej sygnatury przycięcia (zalecane). +- `"always"`: wstrzykuje ostrzeżenie przy każdym uruchomieniu, gdy występuje przycięcie. ```json5 { @@ -997,10 +997,10 @@ Domyślnie: `"once"`. ### `agents.defaults.imageMaxDimensionPx` -Maksymalny rozmiar w pikselach dłuższego boku obrazu w blokach obrazu transkryptu/narzędzi przed wywołaniami dostawcy. +Maksymalny rozmiar w pikselach najdłuższego boku obrazu w blokach obrazu transcript/tool przed wywołaniami dostawców. Domyślnie: `1200`. -Niższe wartości zwykle zmniejszają użycie vision-tokenów i rozmiar ładunku żądania dla przebiegów z dużą liczbą zrzutów ekranu. +Niższe wartości zwykle zmniejszają użycie vision-token i rozmiar ładunku żądania przy sesjach z dużą liczbą zrzutów ekranu. Wyższe wartości zachowują więcej szczegółów wizualnych. ```json5 @@ -1011,7 +1011,7 @@ Wyższe wartości zachowują więcej szczegółów wizualnych. ### `agents.defaults.userTimezone` -Strefa czasowa dla kontekstu system prompt (nie dla znaczników czasu wiadomości). Wartość zapasowa to strefa czasowa hosta. +Strefa czasowa dla kontekstu system prompt (nie dla znaczników czasu wiadomości). Zapasowo używana jest strefa czasowa hosta. ```json5 { @@ -1021,7 +1021,7 @@ Strefa czasowa dla kontekstu system prompt (nie dla znaczników czasu wiadomośc ### `agents.defaults.timeFormat` -Format czasu w system prompt. Domyślnie: `auto` (preferencja systemu). +Format czasu w system prompt. Domyślnie: `auto` (preferencja systemu operacyjnego). ```json5 { @@ -1074,43 +1074,43 @@ Format czasu w system prompt. Domyślnie: `auto` (preferencja systemu). } ``` -- `model`: akceptuje ciąg (`"provider/model"`) albo obiekt (`{ primary, fallbacks }`). - - Forma ciągu ustawia tylko model główny. - - Forma obiektu ustawia model główny oraz uporządkowane modele failover. -- `imageModel`: akceptuje ciąg (`"provider/model"`) albo obiekt (`{ primary, fallbacks }`). +- `model`: akceptuje string (`"provider/model"`) lub obiekt (`{ primary, fallbacks }`). + - Forma string ustawia tylko model podstawowy. + - Forma obiektu ustawia model podstawowy plus uporządkowane modele zapasowe. +- `imageModel`: akceptuje string (`"provider/model"`) lub obiekt (`{ primary, fallbacks }`). - Używany przez ścieżkę narzędzia `image` jako konfiguracja modelu vision. - - Używany także jako routing zapasowy, gdy wybrany/domyslny model nie może przyjąć wejścia obrazowego. -- `imageGenerationModel`: akceptuje ciąg (`"provider/model"`) albo obiekt (`{ primary, fallbacks }`). - - Używany przez współdzieloną funkcję generowania obrazów oraz każdą przyszłą powierzchnię narzędzia/pluginu generującą obrazy. + - Używany także jako routing zapasowy, gdy wybrany/domyslny model nie może przyjąć obrazu jako wejścia. +- `imageGenerationModel`: akceptuje string (`"provider/model"`) lub obiekt (`{ primary, fallbacks }`). + - Używany przez współdzieloną funkcję generowania obrazów i każdą przyszłą powierzchnię narzędzia/pluginu 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 lub `openai/gpt-image-1` dla OpenAI Images. - - Jeśli wybierzesz bezpośrednio `provider/model`, skonfiguruj też pasujące uwierzytelnienie/klucz API dostawcy (na przykład `GEMINI_API_KEY` lub `GOOGLE_API_KEY` dla `google/*`, `OPENAI_API_KEY` dla `openai/*`, `FAL_KEY` dla `fal/*`). - - Jeśli pominięte, `image_generate` nadal może wywnioskować domyślny dostawca oparty na auth. Najpierw próbuje bieżącego domyślnego dostawcy, a potem pozostałych zarejestrowanych dostawców generowania obrazów w kolejności identyfikatorów dostawców. -- `musicGenerationModel`: akceptuje ciąg (`"provider/model"`) albo obiekt (`{ primary, fallbacks }`). - - Używany przez współdzieloną funkcję generowania muzyki oraz wbudowane narzędzie `music_generate`. + - Jeśli wybierzesz bezpośrednio provider/model, skonfiguruj także odpowiadające uwierzytelnienie/klucz API dostawcy (na przykład `GEMINI_API_KEY` lub `GOOGLE_API_KEY` dla `google/*`, `OPENAI_API_KEY` dla `openai/*`, `FAL_KEY` dla `fal/*`). + - Jeśli pole jest pominięte, `image_generate` nadal może wywnioskować domyślnego dostawcę z uwierzytelnieniem. Najpierw próbuje bieżącego domyślnego dostawcy, potem pozostałych zarejestrowanych dostawców generowania obrazów w kolejności identyfikatorów dostawców. +- `musicGenerationModel`: akceptuje string (`"provider/model"`) lub obiekt (`{ primary, fallbacks }`). + - Używany przez współdzieloną funkcję generowania muzyki i wbudowane narzędzie `music_generate`. - Typowe wartości: `google/lyria-3-clip-preview`, `google/lyria-3-pro-preview` lub `minimax/music-2.5+`. - - Jeśli pominięte, `music_generate` nadal może wywnioskować domyślny dostawca oparty na auth. Najpierw próbuje bieżącego domyślnego dostawcy, a potem pozostałych zarejestrowanych dostawców generowania muzyki w kolejności identyfikatorów dostawców. - - Jeśli wybierzesz bezpośrednio `provider/model`, skonfiguruj też pasujące uwierzytelnienie/klucz API dostawcy. -- `videoGenerationModel`: akceptuje ciąg (`"provider/model"`) albo obiekt (`{ primary, fallbacks }`). - - Używany przez współdzieloną funkcję generowania wideo oraz wbudowane narzędzie `video_generate`. + - Jeśli pole jest pominięte, `music_generate` nadal może wywnioskować domyślnego dostawcę z uwierzytelnieniem. Najpierw próbuje bieżącego domyślnego dostawcy, potem pozostałych zarejestrowanych dostawców generowania muzyki w kolejności identyfikatorów dostawców. + - Jeśli wybierzesz bezpośrednio provider/model, skonfiguruj także odpowiadające uwierzytelnienie/klucz API dostawcy. +- `videoGenerationModel`: akceptuje string (`"provider/model"`) lub obiekt (`{ primary, fallbacks }`). + - Używany przez współdzieloną funkcję generowania wideo i 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` lub `qwen/wan2.7-r2v`. - - Jeśli pominięte, `video_generate` nadal może wywnioskować domyślny dostawca oparty na auth. Najpierw próbuje bieżącego domyślnego dostawcy, a potem pozostałych zarejestrowanych dostawców generowania wideo w kolejności identyfikatorów dostawców. - - Jeśli wybierzesz bezpośrednio `provider/model`, skonfiguruj też pasujące uwierzytelnienie/klucz API dostawcy. - - Bundled dostawca generowania wideo Qwen obecnie obsługuje maksymalnie 1 wyjściowe wideo, 1 wejściowy obraz, 4 wejściowe wideo, czas trwania 10 sekund oraz opcje na poziomie dostawcy `size`, `aspectRatio`, `resolution`, `audio` i `watermark`. -- `pdfModel`: akceptuje ciąg (`"provider/model"`) albo obiekt (`{ primary, fallbacks }`). + - Jeśli pole jest pominięte, `video_generate` nadal może wywnioskować domyślnego dostawcę z uwierzytelnieniem. Najpierw próbuje bieżącego domyślnego dostawcy, potem pozostałych zarejestrowanych dostawców generowania wideo w kolejności identyfikatorów dostawców. + - Jeśli wybierzesz bezpośrednio provider/model, skonfiguruj także odpowiadające uwierzytelnienie/klucz API dostawcy. + - Bundled dostawca generowania wideo Qwen obsługuje maksymalnie 1 wyjściowe wideo, 1 wejściowy obraz, 4 wejściowe wideo, 10 sekund czasu trwania oraz opcje na poziomie dostawcy `size`, `aspectRatio`, `resolution`, `audio` i `watermark`. +- `pdfModel`: akceptuje string (`"provider/model"`) lub obiekt (`{ primary, fallbacks }`). - Używany przez narzędzie `pdf` do routingu modelu. - - Jeśli pominięte, narzędzie PDF wraca do `imageModel`, a potem do rozwiązanego modelu sesji/domyslnego. -- `pdfMaxBytesMb`: domyślny limit rozmiaru PDF dla narzędzia `pdf`, gdy `maxBytesMb` nie jest przekazane przy wywołaniu. -- `pdfMaxPages`: domyślna maksymalna liczba stron brana pod uwagę przez tryb zapasowej ekstrakcji w narzędziu `pdf`. + - Jeśli pominięte, narzędzie PDF wraca do `imageModel`, a następnie do rozwiązanego modelu sesji/domyslnego. +- `pdfMaxBytesMb`: domyślny limit rozmiaru PDF dla narzędzia `pdf`, gdy `maxBytesMb` nie jest przekazane w momencie wywołania. +- `pdfMaxPages`: domyślna maksymalna liczba stron uwzględnianych przez tryb zapasowy ekstrakcji w narzędziu `pdf`. - `verboseDefault`: domyślny poziom verbose dla agentów. Wartości: `"off"`, `"on"`, `"full"`. Domyślnie: `"off"`. -- `elevatedDefault`: domyślny poziom wyjścia elevated dla agentów. Wartości: `"off"`, `"on"`, `"ask"`, `"full"`. Domyślnie: `"on"`. -- `model.primary`: format `provider/model` (np. `openai/gpt-5.4`). Jeśli pominiesz dostawcę, OpenClaw najpierw próbuje aliasu, następnie 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 zgłaszać nieaktualny domyślny model usuniętego dostawcy. -- `models`: skonfigurowany katalog modeli i lista zezwoleń dla `/model`. Każdy wpis może zawierać `alias` (skrót) i `params` (specyficzne dla dostawcy, np. `temperature`, `maxTokens`, `cacheRetention`, `context1m`). +- `elevatedDefault`: domyślny poziom elevated-output dla agentów. Wartości: `"off"`, `"on"`, `"ask"`, `"full"`. Domyślnie: `"on"`. +- `model.primary`: format `provider/model` (np. `openai/gpt-5.4`). Jeśli pominiesz dostawcę, OpenClaw najpierw próbuje aliasu, potem unikalnego dopasowania skonfigurowanego dostawcy dla tego dokładnego identyfikatora modelu, a dopiero potem wraca do skonfigurowanego dostawcy domyślnego (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ć nieaktualny domyślny model 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, np. `temperature`, `maxTokens`, `cacheRetention`, `context1m`). - `params`: globalne domyślne parametry dostawcy stosowane do wszystkich modeli. Ustawiane w `agents.defaults.params` (np. `{ cacheRetention: "long" }`). -- Priorytet scalania `params` (konfiguracja): `agents.defaults.params` (globalna baza) jest nadpisywane przez `agents.defaults.models["provider/model"].params` (per model), a następnie `agents.list[].params` (pasujący identyfikator agenta) nadpisuje po kluczu. Szczegóły znajdziesz w [Prompt Caching](/pl/reference/prompt-caching). -- Zapisywacze konfiguracji mutujące te pola (na przykład `/models set`, `/models set-image` oraz polecenia dodawania/usuwania fallbacków) zapisują kanoniczną formę obiektu i w miarę możliwości zachowują istniejące listy fallbacków. -- `maxConcurrent`: maksymalna liczba równoległych przebiegów agentów między sesjami (każda sesja nadal jest serializowana). Domyślnie: 4. +- Priorytet scalania `params` (konfiguracja): `agents.defaults.params` (globalna baza) jest nadpisywane przez `agents.defaults.models["provider/model"].params` (per model), a następnie `agents.list[].params` (pasujący identyfikator agenta) nadpisuje po kluczach. Szczegóły znajdziesz w [Prompt Caching](/pl/reference/prompt-caching). +- Narzędzia zapisu konfiguracji, które modyfikują te pola (na przykład `/models set`, `/models set-image` oraz polecenia dodawania/usuwania fallbacków), zapisują kanoniczną formę obiektową i w miarę możliwości zachowują istniejące listy fallbacków. +- `maxConcurrent`: maksymalna liczba równoległych uruchomień agentów między sesjami (każda sesja nadal jest serializowana). Domyślnie: 4. -**Wbudowane skróty aliasów** (działają tylko wtedy, gdy model znajduje się w `agents.defaults.models`): +**Wbudowane skróty aliasów** (mają zastosowanie tylko wtedy, gdy model znajduje się w `agents.defaults.models`): | Alias | Model | | ------------------- | -------------------------------------- | @@ -1125,13 +1125,13 @@ Format czasu w system prompt. Domyślnie: `auto` (preferencja systemu). Twoje skonfigurowane aliasy zawsze mają pierwszeństwo przed domyślnymi. -Modele Z.AI GLM-4.x automatycznie włączają tryb thinking, chyba że ustawisz `--thinking off` lub samodzielnie zdefiniujesz `agents.defaults.models["zai/"].params.thinking`. +Modele Z.AI GLM-4.x automatycznie włączają tryb myślenia, chyba że ustawisz `--thinking off` lub samodzielnie zdefiniujesz `agents.defaults.models["zai/"].params.thinking`. Modele Z.AI domyślnie włączają `tool_stream` dla strumieniowania wywołań narzędzi. Ustaw `agents.defaults.models["zai/"].params.tool_stream` na `false`, aby to wyłączyć. -Modele Anthropic Claude 4.6 domyślnie używają thinking `adaptive`, gdy nie ustawiono jawnego poziomu thinking. +Modele Anthropic Claude 4.6 domyślnie używają myślenia `adaptive`, gdy nie jest ustawiony jawny poziom myślenia. ### `agents.defaults.cliBackends` -Opcjonalne backendy CLI dla zapasowych przebiegów tylko tekstowych (bez wywołań narzędzi). Przydatne jako kopia zapasowa, gdy dostawcy API zawodzą. +Opcjonalne backendy CLI dla awaryjnych uruchomień tylko tekstowych (bez wywołań narzędzi). Przydatne jako zapas, gdy dostawcy API zawodzą. ```json5 { @@ -1160,18 +1160,18 @@ Opcjonalne backendy CLI dla zapasowych przebiegów tylko tekstowych (bez wywoła ``` - Backendy CLI są nastawione na tekst; narzędzia są zawsze wyłączone. -- Sesje są obsługiwane, gdy ustawiono `sessionArg`. -- Przekazywanie obrazów jest obsługiwane, gdy `imageArg` akceptuje ścieżki do plików. +- Sesje są obsługiwane, gdy ustawione jest `sessionArg`. +- Przekazywanie obrazów jest obsługiwane, gdy `imageArg` akceptuje ścieżki plików. ### `agents.defaults.systemPromptOverride` -Zastępuje cały system prompt złożony przez OpenClaw stałym ciągiem. Ustaw na poziomie domyślnym (`agents.defaults.systemPromptOverride`) lub per agent (`agents.list[].systemPromptOverride`). Wartości per agent mają pierwszeństwo; pusta lub zawierająca tylko białe znaki wartość jest ignorowana. Przydatne do kontrolowanych eksperymentów z promptami. +Zastępuje cały system prompt złożony przez OpenClaw stałym stringiem. Ustawiane na poziomie domyślnym (`agents.defaults.systemPromptOverride`) lub per agent (`agents.list[].systemPromptOverride`). Wartości per agent mają pierwszeństwo; wartość pusta lub zawierająca tylko białe znaki jest ignorowana. Przydatne do kontrolowanych eksperymentów z promptami. ```json5 { agents: { defaults: { - systemPromptOverride: "Jesteś pomocnym asystentem.", + systemPromptOverride: "You are a helpful assistant.", }, }, } @@ -1189,14 +1189,14 @@ Okresowe uruchomienia heartbeat. every: "30m", // 0m wyłącza model: "openai/gpt-5.4-mini", includeReasoning: false, - includeSystemPromptSection: true, // domyślnie: true; false pomija sekcję Heartbeat w system prompt + includeSystemPromptSection: true, // domyślnie: true; false pomija sekcję Heartbeat z system prompt lightContext: false, // domyślnie: false; true zachowuje tylko HEARTBEAT.md z plików bootstrap workspace - isolatedSession: false, // domyślnie: false; true uruchamia każdy heartbeat w świeżej sesji (bez historii rozmowy) + isolatedSession: false, // domyślnie: false; true uruchamia każdy heartbeat w nowej sesji (bez historii rozmowy) session: "main", to: "+15555550123", directPolicy: "allow", // allow (domyślnie) | block target: "none", // domyślnie: none | opcje: last | whatsapp | telegram | discord | ... - prompt: "Przeczytaj HEARTBEAT.md, jeśli istnieje...", + prompt: "Read HEARTBEAT.md if it exists...", ackMaxChars: 300, suppressToolErrorWarnings: false, }, @@ -1205,14 +1205,14 @@ Okresowe uruchomienia heartbeat. } ``` -- `every`: ciąg czasu trwania (ms/s/m/h). Domyślnie: `30m` (uwierzytelnianie kluczem API) lub `1h` (uwierzytelnianie OAuth). Ustaw `0m`, aby wyłączyć. -- `includeSystemPromptSection`: gdy false, pomija sekcję Heartbeat w system prompt i pomija wstrzykiwanie `HEARTBEAT.md` do kontekstu bootstrap. Domyślnie: `true`. -- `suppressToolErrorWarnings`: gdy true, tłumi ładunki ostrzeżeń o błędach narzędzi podczas przebiegów heartbeat. -- `directPolicy`: zasada dostarczania bezpośredniego/DM. `allow` (domyślnie) zezwala na dostarczanie do celu bezpośredniego. `block` tłumi dostarczanie do celu bezpośredniego i emituje `reason=dm-blocked`. -- `lightContext`: gdy true, przebiegi heartbeat używają lekkiego kontekstu bootstrap i zachowują tylko `HEARTBEAT.md` z plików bootstrap workspace. -- `isolatedSession`: gdy true, każdy heartbeat działa w świeżej sesji bez wcześniejszej historii rozmowy. Taki sam wzorzec izolacji jak `sessionTarget: "isolated"` w cron. Zmniejsza koszt tokenów per heartbeat z ~100K do ~2-5K tokenów. -- Per agent: ustaw `agents.list[].heartbeat`. Gdy którykolwiek agent definiuje `heartbeat`, heartbeaty uruchamiają **tylko ci agenci**. -- Heartbeaty wykonują pełne tury agenta — krótsze interwały spalają więcej tokenów. +- `every`: string czasu trwania (ms/s/m/h). Domyślnie: `30m` (uwierzytelnianie kluczem API) lub `1h` (uwierzytelnianie OAuth). Ustaw `0m`, aby wyłączyć. +- `includeSystemPromptSection`: gdy false, pomija sekcję Heartbeat z system prompt i pomija wstrzykiwanie `HEARTBEAT.md` do kontekstu bootstrap. Domyślnie: `true`. +- `suppressToolErrorWarnings`: gdy true, wycisza ładunki ostrzeżeń o błędach narzędzi podczas uruchomień heartbeat. +- `directPolicy`: zasada dostarczania bezpośredniego/DM. `allow` (domyślnie) pozwala na dostarczanie do celu bezpośredniego. `block` tłumi dostarczanie do celu bezpośredniego i emituje `reason=dm-blocked`. +- `lightContext`: gdy true, uruchomienia heartbeat używają lekkiego kontekstu bootstrap i zachowują tylko `HEARTBEAT.md` z plików bootstrap workspace. +- `isolatedSession`: gdy 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 pojedynczego heartbeat z ~100K do ~2-5K tokenów. +- Per agent: ustaw `agents.list[].heartbeat`. Gdy dowolny agent definiuje `heartbeat`, heartbeat uruchamiają **tylko ci agenci**. +- Heartbeat wykonuje pełne tury agenta — krótsze interwały zużywają więcej tokenów. ### `agents.defaults.compaction` @@ -1222,19 +1222,19 @@ Okresowe uruchomienia heartbeat. defaults: { compaction: { mode: "safeguard", // default | safeguard - provider: "my-provider", // id zarejestrowanego pluginu dostawcy kompaktowania (opcjonalne) + provider: "my-provider", // id zarejestrowanego pluginu dostawcy kompaktacji (opcjonalnie) timeoutSeconds: 900, reserveTokensFloor: 24000, identifierPolicy: "strict", // strict | off | custom - identifierInstructions: "Zachowaj identyfikatory wdrożeń, identyfikatory ticketów i pary host:port dokładnie.", // używane gdy identifierPolicy=custom + identifierInstructions: "Preserve deployment IDs, ticket IDs, and host:port pairs exactly.", // używane, gdy identifierPolicy=custom postCompactionSections: ["Session Startup", "Red Lines"], // [] wyłącza ponowne wstrzykiwanie - model: "openrouter/anthropic/claude-sonnet-4-6", // opcjonalne nadpisanie modelu tylko dla kompaktowania - notifyUser: true, // wyślij krótkie powiadomienie, gdy zaczyna się kompaktowanie (domyślnie: false) + model: "openrouter/anthropic/claude-sonnet-4-6", // opcjonalne nadpisanie modelu tylko dla kompaktacji + notifyUser: true, // wyślij krótkie powiadomienie, gdy kompaktacja się rozpocznie (domyślnie: false) memoryFlush: { enabled: true, softThresholdTokens: 6000, - systemPrompt: "Sesja zbliża się do kompaktowania. Zapisz teraz trwałe wspomnienia.", - prompt: "Zapisz wszelkie trwałe notatki do memory/YYYY-MM-DD.md; odpowiedz dokładnym cichym tokenem NO_REPLY, jeśli nie ma nic do zapisania.", + systemPrompt: "Session nearing compaction. Store durable memories now.", + prompt: "Write any lasting notes to memory/YYYY-MM-DD.md; reply with the exact silent token NO_REPLY if nothing to store.", }, }, }, @@ -1242,19 +1242,19 @@ Okresowe uruchomienia heartbeat. } ``` -- `mode`: `default` lub `safeguard` (sumaryzacja fragmentami dla długich historii). Zobacz [Compaction](/pl/concepts/compaction). -- `provider`: identyfikator zarejestrowanego pluginu dostawcy kompaktowania. Gdy ustawiony, `summarize()` dostawcy jest wywoływane zamiast wbudowanej sumaryzacji LLM. W razie awarii wraca do wbudowanej. Ustawienie dostawcy wymusza `mode: "safeguard"`. Zobacz [Compaction](/pl/concepts/compaction). -- `timeoutSeconds`: maksymalna liczba sekund dozwolona dla pojedynczej operacji kompaktowania, po której OpenClaw ją przerywa. Domyślnie: `900`. -- `identifierPolicy`: `strict` (domyślnie), `off` lub `custom`. `strict` dodaje wbudowane wskazówki zachowania nieprzezroczystych identyfikatorów podczas sumaryzacji kompaktowania. -- `identifierInstructions`: opcjonalny własny tekst zachowania identyfikatorów używany, gdy `identifierPolicy=custom`. -- `postCompactionSections`: opcjonalne nazwy sekcji H2/H3 z AGENTS.md do ponownego wstrzyknięcia po kompaktowaniu. Domyślnie `["Session Startup", "Red Lines"]`; ustaw `[]`, aby wyłączyć ponowne wstrzykiwanie. Gdy nieustawione lub jawnie ustawione na tę domyślną parę, starsze nagłówki `Every Session`/`Safety` są także akceptowane jako starszy fallback. -- `model`: opcjonalne nadpisanie `provider/model-id` tylko dla sumaryzacji kompaktowania. Użyj tego, gdy główna sesja ma pozostać przy jednym modelu, ale podsumowania kompaktowania mają działać na innym; gdy nieustawione, kompaktowanie używa głównego modelu sesji. -- `notifyUser`: gdy `true`, wysyła krótkie powiadomienie do użytkownika, gdy zaczyna się kompaktowanie (na przykład „Compacting context...”). Domyślnie wyłączone, aby kompaktowanie pozostawało ciche. -- `memoryFlush`: cicha tura agentowa przed automatycznym kompaktowaniem w celu zapisania trwałych wspomnień. Pomijana, gdy workspace jest tylko do odczytu. +- `mode`: `default` lub `safeguard` (sumaryzacja porcjowana dla długich historii). Zobacz [Compaction](/pl/concepts/compaction). +- `provider`: id zarejestrowanego pluginu dostawcy kompaktacji. Gdy ustawione, wywoływane jest `summarize()` dostawcy zamiast wbudowanej sumaryzacji LLM. W razie błędu następuje powrót do wbudowanej. Ustawienie dostawcy wymusza `mode: "safeguard"`. Zobacz [Compaction](/pl/concepts/compaction). +- `timeoutSeconds`: maksymalna liczba sekund dozwolona dla pojedynczej operacji kompaktacji, po której OpenClaw ją przerywa. Domyślnie: `900`. +- `identifierPolicy`: `strict` (domyślnie), `off` lub `custom`. `strict` poprzedza sumaryzację kompaktacji wbudowanymi wskazówkami dotyczącymi zachowywania nieprzezroczystych identyfikatorów. +- `identifierInstructions`: opcjonalny własny tekst zachowywania identyfikatorów używany, gdy `identifierPolicy=custom`. +- `postCompactionSections`: opcjonalne nazwy sekcji H2/H3 z AGENTS.md do ponownego wstrzyknięcia po kompaktacji. Domyślnie `["Session Startup", "Red Lines"]`; ustaw `[]`, aby wyłączyć ponowne wstrzykiwanie. Gdy nieustawione lub jawnie ustawione na tę domyślną parę, starsze nagłówki `Every Session`/`Safety` są także akceptowane jako zgodność wsteczna. +- `model`: opcjonalne nadpisanie `provider/model-id` tylko dla sumaryzacji kompaktacji. Użyj tego, gdy główna sesja ma pozostać przy jednym modelu, ale sumaryzacje kompaktacji mają działać na innym; gdy nieustawione, kompaktacja używa podstawowego modelu sesji. +- `notifyUser`: gdy `true`, wysyła krótką informację do użytkownika, gdy kompaktacja się rozpoczyna (na przykład „Compacting context...” ). Domyślnie wyłączone, aby kompaktacja pozostawała cicha. +- `memoryFlush`: cicha tura agentyczna przed automatyczną kompaktacją w celu zapisania trwałych wspomnień. Pomijana, gdy workspace jest tylko do odczytu. ### `agents.defaults.contextPruning` -Przycina **stare wyniki narzędzi** z kontekstu w pamięci przed wysłaniem do LLM. **Nie** modyfikuje historii sesji zapisanej na dysku. +Przycina **stare wyniki narzędzi** z kontekstu w pamięci przed wysłaniem do LLM. **Nie** modyfikuje historii sesji na dysku. ```json5 { @@ -1268,7 +1268,7 @@ Przycina **stare wyniki narzędzi** z kontekstu w pamięci przed wysłaniem do L hardClearRatio: 0.5, minPrunableToolChars: 50000, softTrim: { maxChars: 4000, headChars: 1500, tailChars: 1500 }, - hardClear: { enabled: true, placeholder: "[Zawartość starego wyniku narzędzia wyczyszczona]" }, + hardClear: { enabled: true, placeholder: "[Old tool result content cleared]" }, tools: { deny: ["browser", "canvas"] }, }, }, @@ -1279,17 +1279,17 @@ Przycina **stare wyniki narzędzi** z kontekstu w pamięci przed wysłaniem do L - `mode: "cache-ttl"` włącza przebiegi przycinania. -- `ttl` steruje tym, jak często przycinanie może uruchomić się ponownie (po ostatnim dotknięciu cache). -- Przycinanie najpierw miękko przycina zbyt duże wyniki narzędzi, a potem w razie potrzeby twardo czyści starsze wyniki narzędzi. +- `ttl` określa, jak często przycinanie może uruchomić się ponownie (po ostatnim dotknięciu cache). +- Przycinanie najpierw miękko skraca zbyt duże wyniki narzędzi, a potem twardo czyści starsze wyniki narzędzi, jeśli to konieczne. -**Miękkie przycięcie** zachowuje początek + koniec i wstawia `...` pośrodku. +**Miękkie przycinanie** zachowuje początek + koniec i wstawia `...` w środku. **Twarde czyszczenie** zastępuje cały wynik narzędzia placeholderem. Uwagi: - Bloki obrazów nigdy nie są przycinane/czyszczone. -- Współczynniki są oparte na znakach (w przybliżeniu), a nie dokładnej liczbie tokenów. +- Proporcje są oparte na znakach (przybliżenie), a nie dokładnej liczbie tokenów. - Jeśli istnieje mniej niż `keepLastAssistants` wiadomości asystenta, przycinanie jest pomijane. @@ -1313,10 +1313,10 @@ Szczegóły zachowania znajdziesz w [Session Pruning](/pl/concepts/session-pruni ``` - Kanały inne niż Telegram wymagają jawnego `*.blockStreaming: true`, aby włączyć odpowiedzi blokowe. -- Nadpisania kanału: `channels..blockStreamingCoalesce` (oraz warianty per konto). Signal/Slack/Discord/Google Chat domyślnie używają `minChars: 1500`. +- Nadpisania kanałów: `channels..blockStreamingCoalesce` (i warianty per konto). Signal/Slack/Discord/Google Chat domyślnie używają `minChars: 1500`. - `humanDelay`: losowa pauza między odpowiedziami blokowymi. `natural` = 800–2500 ms. Nadpisanie per agent: `agents.list[].humanDelay`. -Szczegóły zachowania + chunkowania znajdziesz w [Streaming](/pl/concepts/streaming). +Zobacz [Streaming](/pl/concepts/streaming), aby poznać zachowanie i szczegóły chunkowania. ### Wskaźniki pisania @@ -1331,7 +1331,7 @@ Szczegóły zachowania + chunkowania znajdziesz w [Streaming](/pl/concepts/strea } ``` -- Domyślnie: `instant` dla czatów bezpośrednich/wzmianek, `message` dla niewzmiankowanych czatów grupowych. +- Domyślnie: `instant` dla czatów bezpośrednich/wzmianek, `message` dla niewspomnianych czatów grupowych. - Nadpisania per sesja: `session.typingMode`, `session.typingIntervalSeconds`. Zobacz [Typing Indicators](/pl/concepts/typing-indicators). @@ -1340,7 +1340,7 @@ Zobacz [Typing Indicators](/pl/concepts/typing-indicators). ### `agents.defaults.sandbox` -Opcjonalny sandboxing dla osadzonego agenta. Pełny przewodnik znajdziesz w [Sandboxing](/pl/gateway/sandboxing). +Opcjonalne sandboxing dla osadzonego agenta. Pełny przewodnik znajdziesz w [Sandboxing](/pl/gateway/sandboxing). ```json5 { @@ -1386,7 +1386,7 @@ Opcjonalny sandboxing dla osadzonego agenta. Pełny przewodnik znajdziesz w [San identityFile: "~/.ssh/id_ed25519", certificateFile: "~/.ssh/id_ed25519-cert.pub", knownHostsFile: "~/.ssh/known_hosts", - // Obsługiwane są też SecretRefs / zawartości inline: + // SecretRefs / treści inline także są obsługiwane: // identityData: { source: "env", provider: "default", id: "SSH_IDENTITY" }, // certificateData: { source: "env", provider: "default", id: "SSH_CERTIFICATE" }, // knownHostsData: { source: "env", provider: "default", id: "SSH_KNOWN_HOSTS" }, @@ -1439,44 +1439,44 @@ Opcjonalny sandboxing dla osadzonego agenta. Pełny przewodnik znajdziesz w [San **Backend:** -- `docker`: lokalny runtime Docker (domyślny) -- `ssh`: ogólny zdalny runtime oparty na SSH -- `openshell`: runtime OpenShell +- `docker`: lokalne środowisko Docker (domyślnie) +- `ssh`: ogólne zdalne środowisko oparte na SSH +- `openshell`: środowisko OpenShell -Gdy wybrane jest `backend: "openshell"`, ustawienia specyficzne dla runtime przenoszą się do +Gdy wybrano `backend: "openshell"`, ustawienia specyficzne dla środowiska wykonawczego przechodzą do `plugins.entries.openshell.config`. **Konfiguracja backendu SSH:** - `target`: cel SSH w formie `user@host[:port]` - `command`: polecenie klienta SSH (domyślnie: `ssh`) -- `workspaceRoot`: absolutny zdalny katalog główny używany dla workspace per zakres +- `workspaceRoot`: bezwzględny zdalny katalog główny używany dla workspace per scope - `identityFile` / `certificateFile` / `knownHostsFile`: istniejące lokalne pliki przekazywane do OpenSSH -- `identityData` / `certificateData` / `knownHostsData`: zawartości inline lub SecretRefs, które OpenClaw materializuje do plików tymczasowych podczas działania -- `strictHostKeyChecking` / `updateHostKeys`: ustawienia polityki kluczy hosta OpenSSH +- `identityData` / `certificateData` / `knownHostsData`: treści inline lub SecretRef, które OpenClaw materializuje do plików tymczasowych w czasie działania +- `strictHostKeyChecking` / `updateHostKeys`: przełączniki zasad klucza hosta OpenSSH **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 runtime sekretów przed rozpoczęciem sesji sandbox +- Wartości `*Data` oparte na SecretRef są rozwiązywane z aktywnej migawki środowiska sekretów przed rozpoczęciem sesji sandbox **Zachowanie backendu SSH:** -- inicjuje zdalny workspace raz po utworzeniu lub odtworzeniu +- zasiewa zdalny workspace raz po utworzeniu lub ponownym utworzeniu - następnie utrzymuje zdalny workspace SSH jako kanoniczny - kieruje `exec`, narzędzia plikowe i ścieżki mediów przez SSH -- nie synchronizuje automatycznie zdalnych zmian z powrotem na hosta -- nie obsługuje kontenerów przeglądarki sandbox +- nie synchronizuje automatycznie zdalnych zmian z powrotem do hosta +- nie obsługuje kontenerów przeglądarki w sandboxie **Dostęp do workspace:** -- `none`: workspace sandbox per zakres w `~/.openclaw/sandboxes` -- `ro`: workspace sandbox w `/workspace`, workspace agenta montowany tylko do odczytu w `/agent` -- `rw`: workspace agenta montowany do odczytu/zapisu w `/workspace` +- `none`: workspace sandbox per scope w `~/.openclaw/sandboxes` +- `ro`: workspace sandbox pod `/workspace`, workspace agenta zamontowany tylko do odczytu pod `/agent` +- `rw`: workspace agenta zamontowany do odczytu/zapisu pod `/workspace` -**Zakres:** +**Scope:** - `session`: kontener + workspace per sesja - `agent`: jeden kontener + workspace per agent (domyślnie) @@ -1495,10 +1495,10 @@ Gdy wybrane jest `backend: "openshell"`, ustawienia specyficzne dla runtime prze from: "openclaw", remoteWorkspaceDir: "/sandbox", remoteAgentWorkspaceDir: "/agent", - gateway: "lab", // opcjonalne - gatewayEndpoint: "https://lab.example", // opcjonalne + gateway: "lab", // opcjonalnie + gatewayEndpoint: "https://lab.example", // opcjonalnie policy: "strict", // opcjonalny identyfikator polityki OpenShell - providers: ["openai"], // opcjonalne + providers: ["openai"], // opcjonalnie autoProviders: true, timeoutSeconds: 120, }, @@ -1510,30 +1510,30 @@ Gdy wybrane jest `backend: "openshell"`, ustawienia specyficzne dla runtime prze **Tryb OpenShell:** -- `mirror`: zasil zdalne z lokalnego przed exec, zsynchronizuj z powrotem po exec; lokalny workspace pozostaje kanoniczny -- `remote`: zasil zdalne raz przy tworzeniu sandbox, a potem utrzymuj zdalny workspace jako kanoniczny +- `mirror`: zasiej zdalne z lokalnego przed exec, synchronizuj z powrotem po exec; lokalny workspace pozostaje kanoniczny +- `remote`: zasiej zdalne raz podczas tworzenia sandbox, następnie utrzymuj zdalny workspace jako kanoniczny -W trybie `remote` edycje lokalnego hosta wykonane poza OpenClaw nie są automatycznie synchronizowane do sandbox po kroku zasilenia. -Transport odbywa się przez SSH do sandbox OpenShell, ale plugin zarządza cyklem życia sandbox oraz opcjonalną synchronizacją mirror. +W trybie `remote` lokalne edycje hosta wykonane poza OpenClaw nie są automatycznie synchronizowane do sandbox po kroku zasiewania. +Transport odbywa się przez SSH do sandbox OpenShell, ale plugin zarządza cyklem życia sandbox i opcjonalną synchronizacją mirror. -**`setupCommand`** uruchamia się raz po utworzeniu kontenera (przez `sh -lc`). Wymaga wychodzącego dostępu do sieci, zapisywalnego katalogu głównego i użytkownika root. +**`setupCommand`** uruchamia się raz po utworzeniu kontenera (przez `sh -lc`). Wymaga wyjścia sieciowego, zapisywalnego katalogu głównego i użytkownika root. -**Kontenery domyślnie mają `network: "none"`** — ustaw `"bridge"` (lub własną sieć bridge), jeśli agent potrzebuje dostępu wychodzącego. +**Kontenery domyślnie używają `network: "none"`** — ustaw `"bridge"` (lub własną sieć bridge), jeśli agent potrzebuje dostępu wychodzącego. `"host"` jest blokowane. `"container:"` jest domyślnie blokowane, chyba że jawnie ustawisz `sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true` (break-glass). -**Przychodzące załączniki** są umieszczane tymczasowo w `media/inbound/*` w aktywnym workspace. +**Załączniki przychodzące** są stagingowane do `media/inbound/*` w aktywnym workspace. **`docker.binds`** montuje dodatkowe katalogi hosta; globalne i per-agent binds są scalane. -**Sandboxowana przeglądarka** (`sandbox.browser.enabled`): Chromium + CDP w kontenerze. URL noVNC jest wstrzykiwany do system prompt. Nie wymaga `browser.enabled` w `openclaw.json`. +**Sandboxed browser** (`sandbox.browser.enabled`): Chromium + CDP w kontenerze. URL noVNC jest wstrzykiwany do system prompt. Nie wymaga `browser.enabled` w `openclaw.json`. Dostęp obserwatora noVNC domyślnie używa uwierzytelniania VNC, a OpenClaw emituje URL z krótkotrwałym tokenem (zamiast ujawniać hasło we współdzielonym URL). -- `allowHostControl: false` (domyślnie) blokuje sandboxowanym sesjom kierowanie do przeglądarki hosta. -- `network` domyślnie to `openclaw-sandbox-browser` (dedykowana sieć bridge). Ustaw `bridge` tylko wtedy, gdy jawnie chcesz globalną łączność 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 sandboxowanej przeglądarki. Gdy ustawione (w tym `[]`), zastępuje `docker.binds` dla kontenera przeglądarki. -- Domyślne parametry uruchomienia są zdefiniowane w `scripts/sandbox-browser-entrypoint.sh` i dostrojone dla hostów kontenerowych: +- `allowHostControl: false` (domyślnie) blokuje sesjom sandbox kierowanie do przeglądarki hosta. +- `network` domyślnie ma wartość `openclaw-sandbox-browser` (dedykowana sieć bridge). Ustaw `bridge` tylko wtedy, gdy jawnie chcesz globalnej łączności bridge. +- `cdpSourceRange` opcjonalnie ogranicza wejście CDP na granicy kontenera do zakresu CIDR (na przykład `172.21.0.1/32`). +- `sandbox.browser.binds` montuje dodatkowe katalogi hosta tylko do kontenera przeglądarki sandbox. Gdy jest ustawione (w tym `[]`), zastępuje `docker.binds` dla kontenera przeglądarki. +- Domyślne parametry uruchomienia są zdefiniowane w `scripts/sandbox-browser-entrypoint.sh` i dostrojone pod hosty kontenerowe: - `--remote-debugging-address=127.0.0.1` - `--remote-debugging-port=` - `--user-data-dir=${HOME}/.chrome` @@ -1555,17 +1555,17 @@ Dostęp obserwatora noVNC domyślnie używa uwierzytelniania VNC, a OpenClaw emi domyślnie włączone i można je wyłączyć przez `OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0`, jeśli użycie WebGL/3D tego wymaga. - `OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0` ponownie włącza rozszerzenia, jeśli od nich - zależy Twój przepływ pracy. + zależy Twój workflow. - `--renderer-process-limit=2` można zmienić przez `OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=`; ustaw `0`, aby użyć domyślnego limitu procesów Chromium. - - oraz `--no-sandbox` i `--disable-setuid-sandbox`, gdy włączone jest `noSandbox`. - - Domyślne ustawienia są bazą obrazu kontenera; użyj własnego obrazu przeglądarki z własnym - entrypointem, aby zmienić domyślne ustawienia kontenera. + - plus `--no-sandbox` i `--disable-setuid-sandbox`, gdy włączone jest `noSandbox`. + - Ustawienia domyślne są bazą obrazu kontenera; użyj własnego obrazu przeglądarki z własnym + entrypointem, aby zmienić domyślne zachowanie kontenera. -Sandboxing przeglądarki i `sandbox.docker.binds` są obecnie dostępne tylko dla Docker. +Sandboxing przeglądarki i `sandbox.docker.binds` są dostępne tylko dla Docker. Budowanie obrazów: @@ -1583,18 +1583,18 @@ scripts/sandbox-browser-setup.sh # opcjonalny obraz przeglądarki { id: "main", default: true, - name: "Główny agent", + name: "Main Agent", workspace: "~/.openclaw/workspace", agentDir: "~/.openclaw/agents/main/agent", model: "anthropic/claude-opus-4-6", // lub { primary, fallbacks } - thinkingDefault: "high", // nadpisanie poziomu thinking per agent - reasoningDefault: "on", // nadpisanie widoczności reasoning per agent + thinkingDefault: "high", // nadpisanie domyślnego poziomu myślenia per agent + reasoningDefault: "on", // nadpisanie domyślnej widoczności reasoning per agent fastModeDefault: false, // nadpisanie fast mode per agent - params: { cacheRetention: "none" }, // nadpisuje pasujące defaults.models params po kluczu + params: { cacheRetention: "none" }, // nadpisuje matching defaults.models params po kluczach skills: ["docs-search"], // zastępuje agents.defaults.skills, gdy ustawione identity: { name: "Samantha", - theme: "pomocny leniwiec", + theme: "helpful sloth", emoji: "🦥", avatar: "avatars/samantha.png", }, @@ -1624,24 +1624,24 @@ scripts/sandbox-browser-setup.sh # opcjonalny obraz przeglądarki - `id`: stabilny identyfikator agenta (wymagany). - `default`: gdy ustawionych jest wiele, wygrywa pierwszy (zapisywane jest ostrzeżenie). Jeśli żaden nie jest ustawiony, domyślny jest pierwszy wpis listy. -- `model`: forma ciągu nadpisuje tylko `primary`; forma obiektu `{ primary, fallbacks }` nadpisuje oba (`[]` wyłącza globalne fallbacki). Zadania cron, które nadpisują tylko `primary`, nadal dziedziczą domyślne fallbacki, chyba że ustawisz `fallbacks: []`. -- `params`: parametry strumienia per agent scalane na wybrany wpis modelu w `agents.defaults.models`. Użyj tego dla nadpisań specyficznych dla agenta, takich jak `cacheRetention`, `temperature` lub `maxTokens`, bez duplikowania całego katalogu modeli. -- `skills`: opcjonalna lista zezwoleń Skills per agent. Jeśli pominięta, agent dziedziczy `agents.defaults.skills`, gdy są ustawione; jawna lista zastępuje wartości domyślne zamiast je scalać, a `[]` oznacza brak Skills. -- `thinkingDefault`: opcjonalny domyślny poziom thinking per agent (`off | minimal | low | medium | high | xhigh | adaptive`). Nadpisuje `agents.defaults.thinkingDefault` dla tego agenta, gdy nie ustawiono nadpisania per wiadomość lub sesję. -- `reasoningDefault`: opcjonalna domyślna widoczność reasoning per agent (`on | off | stream`). Obowiązuje, gdy nie ustawiono nadpisania reasoning per wiadomość lub sesję. -- `fastModeDefault`: opcjonalna domyślna wartość fast mode per agent (`true | false`). Obowiązuje, gdy nie ustawiono nadpisania fast mode per wiadomość lub sesję. -- `runtime`: opcjonalny deskryptor runtime per agent. Użyj `type: "acp"` z wartościami domyślnymi `runtime.acp` (`agent`, `backend`, `mode`, `cwd`), gdy agent ma domyślnie używać sesji harness ACP. +- `model`: forma string nadpisuje tylko `primary`; forma obiektu `{ primary, fallbacks }` nadpisuje oba (`[]` wyłącza globalne fallbacki). Zadania cron, które nadpisują tylko `primary`, nadal dziedziczą domyślne fallbacki, chyba że ustawisz `fallbacks: []`. +- `params`: parametry strumienia per agent scalane na wpis wybranego 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. +- `skills`: opcjonalna lista dozwolonych Skills per agent. Jeśli pominięta, agent dziedziczy `agents.defaults.skills`, gdy jest ustawione; jawna lista zastępuje wartości domyślne zamiast się z nimi scalać, a `[]` oznacza brak Skills. +- `thinkingDefault`: opcjonalny domyślny poziom myślenia per agent (`off | minimal | low | medium | high | xhigh | adaptive`). Nadpisuje `agents.defaults.thinkingDefault` dla tego agenta, gdy nie jest ustawione nadpisanie per wiadomość lub sesję. +- `reasoningDefault`: opcjonalna domyślna widoczność reasoning per agent (`on | off | stream`). Stosowana, gdy nie jest ustawione nadpisanie reasoning per wiadomość lub sesję. +- `fastModeDefault`: opcjonalna domyślna wartość fast mode per agent (`true | false`). Stosowana, gdy nie jest ustawione nadpisanie fast-mode per wiadomość lub sesję. +- `runtime`: opcjonalny deskryptor środowiska wykonawczego per agent. Użyj `type: "acp"` z domyślnymi ustawieniami `runtime.acp` (`agent`, `backend`, `mode`, `cwd`), gdy agent ma domyślnie używać sesji harness ACP. - `identity.avatar`: ścieżka względem workspace, URL `http(s)` lub URI `data:`. - `identity` wyprowadza wartości domyślne: `ackReaction` z `emoji`, `mentionPatterns` z `name`/`emoji`. -- `subagents.allowAgents`: lista zezwoleń identyfikatorów agentów dla `sessions_spawn` (`["*"]` = dowolny; domyślnie: tylko ten sam agent). -- Ochrona dziedziczenia sandbox: jeśli sesja żądająca jest w sandboxie, `sessions_spawn` odrzuca cele, które działałyby bez sandboxa. +- `subagents.allowAgents`: lista dozwolonych identyfikatorów agentów dla `sessions_spawn` (`["*"]` = dowolny; domyślnie: tylko ten sam agent). +- Ochrona dziedziczenia sandbox: jeśli sesja żądająca jest sandboxowana, `sessions_spawn` odrzuca cele, które działałyby bez sandbox. - `subagents.requireAgentId`: gdy true, blokuje wywołania `sessions_spawn`, które pomijają `agentId` (wymusza jawny wybór profilu; domyślnie: false). --- ## Routing wielu agentów -Uruchamiaj wielu izolowanych agentów w jednym Gateway. Zobacz [Multi-Agent](/pl/concepts/multi-agent). +Uruchamiaj wielu izolowanych agentów w jednej bramie. Zobacz [Multi-Agent](/pl/concepts/multi-agent). ```json5 { @@ -1658,14 +1658,14 @@ Uruchamiaj wielu izolowanych agentów w jednym Gateway. Zobacz [Multi-Agent](/pl } ``` -### Pola dopasowania powiązań +### Pola dopasowania binding -- `type` (opcjonalne): `route` dla normalnego routingu (brak typu domyślnie oznacza route), `acp` dla trwałych powiązań rozmów ACP. +- `type` (opcjonalnie): `route` dla zwykłego routingu (brak typu oznacza route), `acp` dla trwałych powiązań konwersacji ACP. - `match.channel` (wymagane) - `match.accountId` (opcjonalne; `*` = dowolne konto; pominięte = konto domyślne) - `match.peer` (opcjonalne; `{ kind: direct|group|channel, id }`) - `match.guildId` / `match.teamId` (opcjonalne; specyficzne dla kanału) -- `acp` (opcjonalne; tylko dla `type: "acp"`): `{ mode, label, cwd, backend }` +- `acp` (opcjonalne; tylko dla wpisów `type: "acp"`): `{ mode, label, cwd, backend }` **Deterministyczna kolejność dopasowania:** @@ -1673,12 +1673,12 @@ Uruchamiaj wielu izolowanych agentów w jednym Gateway. Zobacz [Multi-Agent](/pl 2. `match.guildId` 3. `match.teamId` 4. `match.accountId` (dokładne, bez peer/guild/team) -5. `match.accountId: "*"` (dla całego kanału) +5. `match.accountId: "*"` (w całym kanale) 6. Agent domyślny -W ramach każdego poziomu wygrywa pierwszy pasujący wpis `bindings`. +W obrębie każdego poziomu wygrywa pierwszy pasujący wpis `bindings`. -Dla wpisów `type: "acp"` OpenClaw rozwiązuje po 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. +Dla wpisów `type: "acp"` OpenClaw rozwiązuje po dokładnej tożsamości konwersacji (`match.channel` + konto + `match.peer.id`) i nie używa powyższej hierarchii routingu route binding. ### Profile dostępu per agent @@ -1729,7 +1729,7 @@ Dla wpisów `type: "acp"` OpenClaw rozwiązuje po dokładnej tożsamości rozmow - + ```json5 { @@ -1775,7 +1775,7 @@ Dla wpisów `type: "acp"` OpenClaw rozwiązuje po dokładnej tożsamości rozmow -Szczegóły priorytetów znajdziesz w [Multi-Agent Sandbox & Tools](/pl/tools/multi-agent-sandbox-tools). +Szczegóły pierwszeństwa znajdziesz w [Multi-Agent Sandbox & Tools](/pl/tools/multi-agent-sandbox-tools). --- @@ -1801,20 +1801,20 @@ Szczegóły priorytetów znajdziesz w [Multi-Agent Sandbox & Tools](/pl/tools/mu }, resetTriggers: ["/new", "/reset"], store: "~/.openclaw/agents/{agentId}/sessions/sessions.json", - parentForkMaxTokens: 100000, // pomiń rozwidlenie wątku nadrzędnego powyżej tej liczby tokenów (0 wyłącza) + parentForkMaxTokens: 100000, // pomiń fork wątku nadrzędnego powyżej tej liczby tokenów (0 wyłącza) maintenance: { mode: "warn", // warn | enforce pruneAfter: "30d", maxEntries: 500, rotateBytes: "10mb", resetArchiveRetention: "30d", // czas trwania lub false - maxDiskBytes: "500mb", // opcjonalny sztywny budżet - highWaterBytes: "400mb", // opcjonalny cel czyszczenia + maxDiskBytes: "500mb", // opcjonalny twardy budżet + highWaterBytes: "400mb", // opcjonalny cel cleanup }, threadBindings: { enabled: true, - idleHours: 24, // domyślna automatyczna dezaktywacja po bezczynności w godzinach (`0` wyłącza) - maxAgeHours: 0, // domyślny sztywny maksymalny wiek w godzinach (`0` wyłącza) + idleHours: 24, // domyślne automatyczne odwiązywanie po bezczynności w godzinach (`0` wyłącza) + maxAgeHours: 0, // domyślny twardy maksymalny wiek w godzinach (`0` wyłącza) }, mainKey: "main", // starsze (runtime zawsze używa "main") agentToAgent: { maxPingPongTurns: 5 }, @@ -1828,35 +1828,35 @@ Szczegóły priorytetów znajdziesz w [Multi-Agent Sandbox & Tools](/pl/tools/mu -- **`scope`**: bazowa strategia grupowania sesji dla kontekstów czatów grupowych. - - `per-sender` (domyślnie): każdy nadawca otrzymuje izolowaną sesję w obrębie kontekstu kanału. - - `global`: wszyscy uczestnicy w kontekście kanału współdzielą jedną sesję (używaj tylko wtedy, gdy zamierzony jest współdzielony kontekst). +- **`scope`**: bazowa 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 zamierzony jest wspólny kontekst). - **`dmScope`**: sposób grupowania DM. - `main`: wszystkie DM współdzielą główną sesję. - `per-peer`: izolacja według identyfikatora nadawcy między kanałami. - `per-channel-peer`: izolacja per kanał + nadawca (zalecane dla wieloużytkownikowych skrzynek odbiorczych). - `per-account-channel-peer`: izolacja per konto + kanał + nadawca (zalecane dla wielu kont). -- **`identityLinks`**: mapuje identyfikatory kanoniczne do peerów z prefiksem dostawcy w celu współdzielenia sesji między kanałami. -- **`reset`**: podstawowa zasada resetu. `daily` resetuje o `atHour` czasu lokalnego; `idle` resetuje po `idleMinutes`. Gdy skonfigurowane są oba, wygrywa to, które wygaśnie pierwsze. -- **`resetByType`**: nadpisania per typ (`direct`, `group`, `thread`). Starsze `dm` jest akceptowane jako alias dla `direct`. -- **`parentForkMaxTokens`**: maksymalna liczba `totalTokens` sesji nadrzędnej dozwolona przy tworzeniu rozwidlonej sesji wątku (domyślnie `100000`). - - Jeśli `totalTokens` rodzica 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 rozwidlenie od rodzica. -- **`mainKey`**: starsze pole. Runtime teraz zawsze używa `"main"` dla głównego koszyka czatu bezpośredniego. -- **`agentToAgent.maxPingPongTurns`**: maksymalna liczba tur odpowiedzi zwrotnej między agentami podczas wymiany agent-agent (liczba całkowita, zakres: `0`–`5`). `0` wyłącza łańcuch ping-pong. -- **`sendPolicy`**: dopasowuje po `channel`, `chatType` (`direct|group|channel`, ze starszym aliasem `dm`), `keyPrefix` lub `rawKeyPrefix`. Pierwsze deny wygrywa. -- **`maintenance`**: czyszczenie magazynu sesji + kontrola retencji. - - `mode`: `warn` emituje tylko ostrzeżenia; `enforce` stosuje czyszczenie. - - `pruneAfter`: granica wieku dla nieaktualnych wpisów (domyślnie `30d`). +- **`identityLinks`**: mapuje kanoniczne identyfikatory do peerów z prefiksem dostawcy dla współdzielenia sesji między kanałami. +- **`reset`**: główna zasada resetu. `daily` resetuje o `atHour` czasu lokalnego; `idle` resetuje po `idleMinutes`. Gdy skonfigurowane są oba, wygrywa ten, który wygaśnie wcześniej. +- **`resetByType`**: nadpisania per typ (`direct`, `group`, `thread`). Starsze `dm` jest akceptowane jako alias `direct`. +- **`parentForkMaxTokens`**: maksymalne `totalTokens` sesji nadrzędnej dozwolone przy tworzeniu rozwidlonej sesji wątku (domyślnie `100000`). + - Jeśli `totalTokens` rodzica jest powyżej tej wartości, OpenClaw uruchamia świeżą sesję wątku zamiast dziedziczyć historię transkrypcji rodzica. + - Ustaw `0`, aby wyłączyć to zabezpieczenie i zawsze pozwalać na forki rodzica. +- **`mainKey`**: starsze pole. Runtime zawsze używa `"main"` dla głównego bucketu 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ńcuchy ping-pong. +- **`sendPolicy`**: dopasowanie po `channel`, `chatType` (`direct|group|channel`, ze starszym aliasem `dm`), `keyPrefix` lub `rawKeyPrefix`. Pierwsze deny wygrywa. +- **`maintenance`**: kontrola cleanup + retencji magazynu sesji. + - `mode`: `warn` emituje tylko ostrzeżenia; `enforce` stosuje cleanup. + - `pruneAfter`: próg wieku dla nieaktualnych wpisów (domyślnie `30d`). - `maxEntries`: maksymalna liczba wpisów w `sessions.json` (domyślnie `500`). - - `rotateBytes`: rotuj `sessions.json`, gdy przekroczy ten rozmiar (domyślnie `10mb`). - - `resetArchiveRetention`: retencja dla archiwów transkryptów `*.reset.`. Domyślnie odpowiada `pruneAfter`; ustaw `false`, aby wyłączyć. - - `maxDiskBytes`: opcjonalny budżet miejsca na dysku dla katalogu sesji. W trybie `warn` zapisuje ostrzeżenia; w trybie `enforce` najpierw usuwa najstarsze artefakty/sesje. - - `highWaterBytes`: opcjonalny cel po czyszczeniu budżetu. Domyślnie `80%` z `maxDiskBytes`. -- **`threadBindings`**: globalne domyślne ustawienia funkcji sesji powiązanych z wątkiem. + - `rotateBytes`: rotuje `sessions.json`, gdy przekroczy ten rozmiar (domyślnie `10mb`). + - `resetArchiveRetention`: retencja dla archiwów transkryptów `*.reset.`. Domyślnie zgodna z `pruneAfter`; ustaw `false`, aby wyłączyć. + - `maxDiskBytes`: opcjonalny budżet dyskowy katalogu sesji. W trybie `warn` zapisuje ostrzeżenia; w trybie `enforce` usuwa najstarsze artefakty/sesje w pierwszej kolejności. + - `highWaterBytes`: opcjonalny cel po cleanup budżetu. Domyślnie `80%` z `maxDiskBytes`. +- **`threadBindings`**: globalne wartości domyślne dla funkcji sesji związanych z wątkiem. - `enabled`: główny domyślny przełącznik (dostawcy mogą nadpisywać; Discord używa `channels.discord.threadBindings.enabled`) - - `idleHours`: domyślna automatyczna dezaktywacja po bezczynności w godzinach (`0` wyłącza; dostawcy mogą nadpisywać) - - `maxAgeHours`: domyślny sztywny maksymalny wiek w godzinach (`0` wyłącza; dostawcy mogą nadpisywać) + - `idleHours`: domyślne automatyczne odwiązywanie 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ć) @@ -1896,34 +1896,34 @@ Szczegóły priorytetów znajdziesz w [Multi-Agent Sandbox & Tools](/pl/tools/mu Nadpisania per kanał/konto: `channels..responsePrefix`, `channels..accounts..responsePrefix`. -Rozwiązywanie (wygrywa najbardziej szczegółowe): konto → kanał → globalne. `""` wyłącza i zatrzymuje kaskadę. `"auto"` wyprowadza `[{identity.name}]`. +Rozstrzyganie (wygrywa najbardziej szczegółowe): konto → kanał → globalne. `""` wyłącza i zatrzymuje kaskadę. `"auto"` wyprowadza `[{identity.name}]`. **Zmienne szablonu:** -| Zmienna | Opis | Przykład | -| ---------------- | --------------------- | --------------------------- | -| `{model}` | Krótka nazwa modelu | `claude-opus-4-6` | +| 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 thinking | `high`, `low`, `off` | -| `{identity.name}` | Nazwa tożsamości agenta | (to samo co `"auto"`) | +| `{provider}` | Nazwa dostawcy | `anthropic` | +| `{thinkingLevel}` | Bieżący poziom myślenia | `high`, `low`, `off` | +| `{identity.name}` | Nazwa tożsamości agenta | (tak samo jak `"auto"`) | -Zmienne są niewrażliwe na wielkość liter. `{think}` jest aliasem dla `{thinkingLevel}`. +Zmienne nie rozróżniają wielkości liter. `{think}` jest aliasem dla `{thinkingLevel}`. ### Reakcja ack -- Domyślnie używa `identity.emoji` aktywnego agenta, w przeciwnym razie `"👀"`. Ustaw `""`, aby wyłączyć. +- Domyślnie aktywna jest `identity.emoji` aktywnego agenta, w przeciwnym razie `"👀"`. Ustaw `""`, aby wyłączyć. - Nadpisania per kanał: `channels..ackReaction`, `channels..accounts..ackReaction`. -- Kolejność rozwiązywania: konto → kanał → `messages.ackReaction` → fallback tożsamości. +- Kolejność rozstrzygania: konto → kanał → `messages.ackReaction` → fallback identity. - Zakres: `group-mentions` (domyślnie), `group-all`, `direct`, `all`. -- `removeAckAfterReply`: usuwa ack po odpowiedzi na Slack, Discord i Telegram. -- `messages.statusReactions.enabled`: włącza reakcje statusu cyklu życia na Slack, Discord i Telegram. - Na Slack i Discord brak ustawienia pozostawia reakcje statusu włączone, gdy aktywne są reakcje ack. - Na Telegram ustaw jawnie `true`, aby włączyć reakcje statusu cyklu życia. +- `removeAckAfterReply`: usuwa ack po odpowiedzi w Slack, Discord i Telegram. +- `messages.statusReactions.enabled`: włącza reakcje statusu cyklu życia w Slack, Discord i Telegram. + W Slacku i Discordzie nieustawiona wartość zachowuje reakcje statusu włączone, gdy aktywne są reakcje ack. + W Telegramie ustaw jawnie `true`, aby włączyć reakcje statusu cyklu życia. -### Debounce przychodzących wiadomości +### Debounce przychodzący -Łączy szybkie wiadomości tekstowe od tego samego nadawcy w jedną turę agenta. Media/załączniki opróżniają kolejkę natychmiast. Polecenia sterujące omijają debounce. +Łączy szybkie wiadomości tekstowe od tego samego nadawcy w jedną turę agenta. Media/załączniki powodują natychmiastowy flush. Polecenia sterujące omijają debounce. ### TTS (text-to-speech) @@ -1967,17 +1967,17 @@ Zmienne są niewrażliwe na wielkość liter. `{think}` jest aliasem dla `{think ``` - `auto` steruje domyślnym trybem auto-TTS: `off`, `always`, `inbound` lub `tagged`. `/tts on|off` może nadpisać lokalne preferencje, a `/tts status` pokazuje stan efektywny. -- `summaryModel` nadpisuje `agents.defaults.model.primary` dla automatycznego podsumowania. +- `summaryModel` nadpisuje `agents.defaults.model.primary` dla auto-summary. - `modelOverrides` jest domyślnie włączone; `modelOverrides.allowProvider` domyślnie ma wartość `false` (opt-in). -- Klucze API mają wartości zapasowe `ELEVENLABS_API_KEY`/`XI_API_KEY` oraz `OPENAI_API_KEY`. -- `openai.baseUrl` nadpisuje endpoint OpenAI TTS. Kolejność rozwiązywania to konfiguracja, następnie `OPENAI_TTS_BASE_URL`, a potem `https://api.openai.com/v1`. +- Klucze API mają fallback do `ELEVENLABS_API_KEY`/`XI_API_KEY` oraz `OPENAI_API_KEY`. +- `openai.baseUrl` nadpisuje endpoint OpenAI TTS. Kolejność rozstrzygania to konfiguracja, potem `OPENAI_TTS_BASE_URL`, potem `https://api.openai.com/v1`. - Gdy `openai.baseUrl` wskazuje na endpoint inny niż OpenAI, OpenClaw traktuje go jako serwer TTS zgodny z OpenAI i łagodzi walidację modelu/głosu. --- ## Talk -Ustawienia domyślne dla trybu Talk (macOS/iOS/Android). +Wartości domyślne dla trybu Talk (macOS/iOS/Android). ```json5 { @@ -2002,12 +2002,12 @@ Ustawienia domyślne dla 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ą obsługiwane wyłącznie dla zgodności i są automatycznie migrowane do `talk.providers.`. -- Identyfikatory głosów mają wartości zapasowe `ELEVENLABS_VOICE_ID` lub `SAG_VOICE_ID`. -- `providers.*.apiKey` akceptuje zwykłe ciągi znaków lub obiekty SecretRef. -- Zapasowa wartość `ELEVENLABS_API_KEY` ma zastosowanie tylko wtedy, gdy nie skonfigurowano klucza API Talk. +- Starsze płaskie klucze Talk (`talk.voiceId`, `talk.voiceAliases`, `talk.modelId`, `talk.outputFormat`, `talk.apiKey`) są tylko zgodnościowe i są automatycznie migrowane do `talk.providers.`. +- Voice ID mają fallback do `ELEVENLABS_VOICE_ID` lub `SAG_VOICE_ID`. +- `providers.*.apiKey` akceptuje zwykłe stringi lub obiekty SecretRef. +- Fallback `ELEVENLABS_API_KEY` ma zastosowanie tylko wtedy, gdy nie skonfigurowano klucza API Talk. - `providers.*.voiceAliases` pozwala dyrektywom Talk używać przyjaznych nazw. -- `silenceTimeoutMs` steruje tym, jak długo tryb Talk czeka po ciszy użytkownika, zanim wyśle transkrypt. Brak ustawienia zachowuje domyślne okno pauzy platformy (`700 ms na macOS i Androidzie, 900 ms na iOS`). +- `silenceTimeoutMs` określa, jak długo tryb Talk czeka po ciszy użytkownika, zanim wyśle transkrypt. Wartość nieustawiona zachowuje domyślne okno pauzy platformy (`700 ms na macOS i Android, 900 ms na iOS`). --- @@ -2015,37 +2015,37 @@ Ustawienia domyślne dla trybu Talk (macOS/iOS/Android). ### Profile narzędzi -`tools.profile` ustawia bazową listę zezwoleń przed `tools.allow`/`tools.deny`: +`tools.profile` ustawia bazową listę dozwolonych przed `tools.allow`/`tools.deny`: -Lokalny onboarding domyślnie ustawia nowe lokalne konfiguracje na `tools.profile: "coding"`, gdy nie jest ustawione (istniejące jawne profile są zachowywane). +Lokalny onboarding domyślnie ustawia nowe lokalne konfiguracje na `tools.profile: "coding"`, gdy wartość nie jest ustawiona (istniejące jawne profile są zachowywane). -| Profil | Obejmuje | -| ----------- | -------------------------------------------------------------------------------------------------------------------------------- | -| `minimal` | tylko `session_status` | +| Profil | Zawiera | +| ----------- | ------------------------------------------------------------------------------------------------------------------------------- | +| `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` | Brak ograniczeń (to samo co brak ustawienia) | +| `messaging` | `group:messaging`, `sessions_list`, `sessions_history`, `sessions_send`, `session_status` | +| `full` | Bez 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: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` | -| `group:web` | `web_search`, `x_search`, `web_fetch` | -| `group:ui` | `browser`, `canvas` | -| `group:automation` | `cron`, `gateway` | -| `group:messaging` | `message` | -| `group:nodes` | `nodes` | -| `group:agents` | `agents_list` | -| `group:media` | `image`, `image_generate`, `video_generate`, `tts` | -| `group:openclaw` | Wszystkie wbudowane narzędzia (wyklucza pluginy dostawców) | +| Grupa | Narzędzia | +| ------------------ | ------------------------------------------------------------------------------------------------------------------------ | +| `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` | +| `group:web` | `web_search`, `x_search`, `web_fetch` | +| `group:ui` | `browser`, `canvas` | +| `group:automation` | `cron`, `gateway` | +| `group:messaging` | `message` | +| `group:nodes` | `nodes` | +| `group:agents` | `agents_list` | +| `group:media` | `image`, `image_generate`, `video_generate`, `tts` | +| `group:openclaw` | Wszystkie wbudowane narzędzia (nie obejmuje pluginów dostawców) | ### `tools.allow` / `tools.deny` -Globalna polityka zezwalania/odmawiania narzędzi (deny wygrywa). Niewrażliwa na wielkość liter, obsługuje wildcardy `*`. Stosowana nawet wtedy, gdy sandbox Docker jest wyłączony. +Globalna zasada allow/deny dla narzędzi (deny wygrywa). Bez rozróżniania wielkości liter, obsługuje wildcardy `*`. Stosowane nawet wtedy, gdy sandbox Docker jest wyłączony. ```json5 { @@ -2055,7 +2055,7 @@ Globalna polityka zezwalania/odmawiania narzędzi (deny wygrywa). Niewrażliwa n ### `tools.byProvider` -Dodatkowo ogranicza narzędzia dla określonych dostawców lub modeli. Kolejność: profil bazowy → profil dostawcy → allow/deny. +Dalsze ograniczenia narzędzi dla określonych dostawców lub modeli. Kolejność: profil bazowy → profil dostawcy → allow/deny. ```json5 { @@ -2071,7 +2071,7 @@ Dodatkowo ogranicza narzędzia dla określonych dostawców lub modeli. Kolejnoś ### `tools.elevated` -Steruje podniesionym dostępem exec poza sandboxem: +Steruje podwyższonym dostępem exec poza sandboxem: ```json5 { @@ -2088,8 +2088,8 @@ Steruje podniesionym dostępem exec poza sandboxem: ``` - Nadpisanie per agent (`agents.list[].tools.elevated`) może tylko dodatkowo ograniczać. -- `/elevated on|off|ask|full` zapisuje stan per sesja; dyrektywy inline dotyczą pojedynczej wiadomości. -- Podniesione `exec` omija sandboxing i używa skonfigurowanej ścieżki ucieczki (`gateway` domyślnie albo `node`, gdy celem exec jest `node`). +- `/elevated on|off|ask|full` zapisuje stan per sesja; dyrektywy inline mają zastosowanie do pojedynczej wiadomości. +- Podwyższony `exec` omija sandbox i używa skonfigurowanej ścieżki ucieczki (`gateway` domyślnie lub `node`, gdy celem exec jest `node`). ### `tools.exec` @@ -2114,7 +2114,7 @@ Steruje podniesionym dostępem exec poza sandboxem: ### `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`. +Ustawienia można definiować globalnie w `tools.loopDetection` i nadpisywać per agent w `agents.list[].tools.loopDetection`. ```json5 { @@ -2136,13 +2136,13 @@ Ustawienia można zdefiniować globalnie w `tools.loopDetection` i nadpisać per ``` - `historySize`: maksymalna historia wywołań narzędzi zachowywana do analizy pętli. -- `warningThreshold`: próg powtarzającego się wzorca bez postępu dla ostrzeżeń. -- `criticalThreshold`: wyższy próg powtarzania do blokowania krytycznych pętli. -- `globalCircuitBreakerThreshold`: twardy próg zatrzymania dla każdego przebiegu bez postępu. -- `detectors.genericRepeat`: ostrzegaj o powtarzanych wywołaniach tego samego narzędzia/z tymi samymi argumentami. -- `detectors.knownPollNoProgress`: ostrzegaj/blokuj znane narzędzia poll (`process.poll`, `command_status` itd.). -- `detectors.pingPong`: ostrzegaj/blokuj naprzemienne wzorce par bez postępu. -- Jeśli `warningThreshold >= criticalThreshold` lub `criticalThreshold >= globalCircuitBreakerThreshold`, walidacja kończy się błędem. +- `warningThreshold`: próg powtarzających się wzorców bez postępu dla ostrzeżeń. +- `criticalThreshold`: wyższy próg powtórzeń dla blokowania krytycznych pętli. +- `globalCircuitBreakerThreshold`: próg twardego zatrzymania dla dowolnego przebiegu bez postępu. +- `detectors.genericRepeat`: ostrzega o powtarzanych wywołaniach tego samego narzędzia z tymi samymi argumentami. +- `detectors.knownPollNoProgress`: ostrzega/blokuje znane narzędzia odpytywania (`process.poll`, `command_status` itd.). +- `detectors.pingPong`: ostrzega/blokuje naprzemienne wzorce par bez postępu. +- Jeśli `warningThreshold >= criticalThreshold` lub `criticalThreshold >= globalCircuitBreakerThreshold`, walidacja kończy się niepowodzeniem. ### `tools.web` @@ -2159,7 +2159,7 @@ Ustawienia można zdefiniować globalnie w `tools.loopDetection` i nadpisać per }, fetch: { enabled: true, - provider: "firecrawl", // opcjonalne; pomiń dla auto-detect + provider: "firecrawl", // opcjonalnie; pomiń dla auto-detect maxChars: 50000, maxCharsCap: 50000, maxResponseBytes: 2000000, @@ -2176,7 +2176,7 @@ Ustawienia można zdefiniować globalnie w `tools.loopDetection` i nadpisać per ### `tools.media` -Konfiguruje rozumienie przychodzących mediów (obraz/audio/wideo): +Konfiguruje rozumienie mediów przychodzących (obraz/audio/wideo): ```json5 { @@ -2184,7 +2184,7 @@ Konfiguruje rozumienie przychodzących mediów (obraz/audio/wideo): media: { concurrency: 2, asyncCompletion: { - directSend: false, // opt-in: wyślij ukończone asynchroniczne music/video bezpośrednio do kanału + directSend: false, // opt-in: wyślij ukończone async music/video bezpośrednio do kanału }, audio: { enabled: true, @@ -2208,11 +2208,11 @@ Konfiguruje rozumienie przychodzących mediów (obraz/audio/wideo): } ``` - + **Wpis dostawcy** (`type: "provider"` lub pominięte): -- `provider`: identyfikator dostawcy API (`openai`, `anthropic`, `google`/`gemini`, `groq` itd.) +- `provider`: id dostawcy API (`openai`, `anthropic`, `google`/`gemini`, `groq` itd.) - `model`: nadpisanie identyfikatora modelu - `profile` / `preferredProfile`: wybór profilu `auth-profiles.json` @@ -2221,7 +2221,7 @@ Konfiguruje rozumienie przychodzących mediów (obraz/audio/wideo): - `command`: wykonywalne polecenie do uruchomienia - `args`: argumenty szablonowe (obsługuje `{{MediaPath}}`, `{{Prompt}}`, `{{MaxChars}}` itd.) -**Wspólne pola:** +**Pola wspólne:** - `capabilities`: opcjonalna lista (`image`, `audio`, `video`). Domyślnie: `openai`/`anthropic`/`minimax` → image, `google` → image+audio+video, `groq` → audio. - `prompt`, `maxChars`, `maxBytes`, `timeoutSeconds`, `language`: nadpisania per wpis. @@ -2229,11 +2229,11 @@ Konfiguruje rozumienie przychodzących mediów (obraz/audio/wideo): Uwierzytelnianie dostawcy używa standardowej kolejności: `auth-profiles.json` → zmienne env → `models.providers.*.apiKey`. -**Pola asynchronicznego ukończenia:** +**Pola async completion:** -- `asyncCompletion.directSend`: gdy `true`, ukończone asynchroniczne zadania `music_generate` - i `video_generate` najpierw próbują bezpośredniego dostarczenia do kanału. Domyślnie: `false` - (starsza ścieżka budzenia sesji żądającej/dostarczania modelu). +- `asyncCompletion.directSend`: gdy `true`, ukończone zadania async `music_generate` + i `video_generate` najpierw próbują bezpośredniego dostarczenia kanałowego. Domyślnie: `false` + (starsza ścieżka wybudzania sesji żądającego/dostarczenia modelowego). @@ -2252,7 +2252,7 @@ Uwierzytelnianie dostawcy używa standardowej kolejności: `auth-profiles.json` ### `tools.sessions` -Steruje tym, które sesje mogą być celem narzędzi sesji (`sessions_list`, `sessions_history`, `sessions_send`). +Steruje tym, które sesje mogą być celem dla narzędzi sesji (`sessions_list`, `sessions_history`, `sessions_send`). Domyślnie: `tree` (bieżąca sesja + sesje utworzone przez nią, takie jak subagenci). @@ -2273,7 +2273,7 @@ Uwagi: - `tree`: bieżąca sesja + sesje utworzone 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 per nadawca pod tym samym identyfikatorem agenta). - `all`: dowolna sesja. Kierowanie między agentami nadal wymaga `tools.agentToAgent`. -- Ograniczenie sandbox: gdy bieżąca sesja jest w sandboxie, a `agents.defaults.sandbox.sessionToolsVisibility="spawned"`, widoczność jest wymuszana do `tree`, nawet jeśli `tools.sessions.visibility="all"`. +- Ograniczenie sandbox: gdy bieżąca sesja jest sandboxowana i `agents.defaults.sandbox.sessionToolsVisibility="spawned"`, widoczność jest wymuszana do `tree`, nawet jeśli `tools.sessions.visibility="all"`. ### `tools.sessions_spawn` @@ -2284,11 +2284,11 @@ Steruje obsługą załączników inline dla `sessions_spawn`. tools: { sessions_spawn: { attachments: { - enabled: false, // opt-in: ustaw true, aby zezwolić na załączniki plikowe inline + enabled: false, // opt-in: ustaw true, aby zezwolić na inline file attachments maxTotalBytes: 5242880, // 5 MB łącznie dla wszystkich plików maxFiles: 50, maxFileBytes: 1048576, // 1 MB na plik - retainOnSessionKeep: false, // zachowuj załączniki, gdy cleanup="keep" + retainOnSessionKeep: false, // zachowaj załączniki, gdy cleanup="keep" }, }, }, @@ -2298,15 +2298,15 @@ Steruje obsługą załączników inline dla `sessions_spawn`. Uwagi: - Załączniki są obsługiwane tylko dla `runtime: "subagent"`. Runtime ACP je odrzuca. -- Pliki są materializowane w workspace dziecka pod `.openclaw/attachments//` z `.manifest.json`. -- Zawartość załączników jest automatycznie redagowana z trwałości transkryptu. -- Wejścia base64 są walidowane z rygorystycznym sprawdzaniem alfabetu/dopełnienia i zabezpieczeniem rozmiaru przed dekodowaniem. +- Pliki są materializowane do workspace potomnego w `.openclaw/attachments//` z `.manifest.json`. +- Zawartość załączników jest automatycznie redagowana z trwałości transcript. +- Wejścia base64 są walidowane przy użyciu ścisłych reguł alfabetu/padding oraz ochrony rozmiaru przed dekodowaniem. - Uprawnienia plików to `0700` dla katalogów i `0600` dla plików. -- Czyszczenie podąża za polityką `cleanup`: `delete` zawsze usuwa załączniki; `keep` zachowuje je tylko, gdy `retainOnSessionKeep: true`. +- Cleanup podąża za polityką `cleanup`: `delete` zawsze usuwa załączniki; `keep` zachowuje je tylko wtedy, gdy `retainOnSessionKeep: true`. ### `tools.experimental` -Eksperymentalne flagi wbudowanych narzędzi. Domyślnie wyłączone, chyba że obowiązuje reguła automatycznego włączania specyficzna dla runtime. +Flagi eksperymentalnych wbudowanych narzędzi. Domyślnie wyłączone, chyba że obowiązuje reguła auto-enable zależna od runtime. ```json5 { @@ -2320,9 +2320,9 @@ Eksperymentalne flagi wbudowanych narzędzi. Domyślnie wyłączone, chyba że o Uwagi: -- `planTool`: włącza strukturalne narzędzie `update_plan` do śledzenia nietrywialnej pracy wieloetapowej. -- Domyślnie: `false` dla dostawców innych niż OpenAI. Przebiegi OpenAI i OpenAI Codex włączają je automatycznie, gdy nie jest ustawione; ustaw `false`, aby wyłączyć automatyczne włączanie. -- Gdy jest włączone, system prompt dodaje także wskazówki użycia, aby model używał go tylko do istotnej pracy i utrzymywał najwyżej jeden krok `in_progress`. +- `planTool`: włącza strukturalne narzędzie `update_plan` do śledzenia nietrywialnych prac wieloetapowych. +- Domyślnie: `false` dla dostawców innych niż OpenAI. Uruchomienia OpenAI i OpenAI Codex automatycznie je włączają, gdy wartość nie jest ustawiona; ustaw `false`, aby wyłączyć to automatyczne włączenie. +- Gdy jest włączone, system prompt dodaje także wskazówki użycia, aby model korzystał z niego tylko przy istotnej pracy i utrzymywał najwyżej jeden krok `in_progress`. ### `agents.defaults.subagents` @@ -2342,10 +2342,10 @@ Uwagi: } ``` -- `model`: domyślny model dla tworzonych subagentów. Jeśli pominięty, subagenci dziedziczą model wywołującego. -- `allowAgents`: domyślna lista zezwoleń 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ęty, subagenci 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). - `runTimeoutSeconds`: domyślny timeout (sekundy) dla `sessions_spawn`, gdy wywołanie narzędzia pomija `runTimeoutSeconds`. `0` oznacza brak timeoutu. -- Polityka narzędzi per subagent: `tools.subagents.tools.allow` / `tools.subagents.tools.deny`. +- Zasada narzędzi per subagent: `tools.subagents.tools.allow` / `tools.subagents.tools.deny`. --- @@ -2383,42 +2383,42 @@ OpenClaw używa wbudowanego katalogu modeli. Dodaj własnych dostawców przez `m - Użyj `authHeader: true` + `headers` dla własnych potrzeb uwierzytelniania. - Nadpisz katalog główny konfiguracji agenta przez `OPENCLAW_AGENT_DIR` (lub `PI_CODING_AGENT_DIR`, starszy alias zmiennej środowiskowej). - Priorytet scalania dla pasujących identyfikatorów dostawców: - - Niepuste wartości `baseUrl` z agenta w `models.json` mają pierwszeństwo. - - Niepuste wartości `apiKey` z agenta mają pierwszeństwo tylko wtedy, gdy ten dostawca nie jest zarządzany przez SecretRef w bieżącym kontekście config/auth-profile. - - Wartości `apiKey` dostawców zarządzanych przez SecretRef są odświeżane ze znaczników źródła (`ENV_VAR_NAME` dla odwołań env, `secretref-managed` dla odwołań file/exec) zamiast utrwalać rozwiązane sekrety. + - Niepuste wartości `baseUrl` z `models.json` agenta wygrywają. + - Niepuste wartości `apiKey` agenta wygrywają tylko wtedy, gdy dany dostawca nie jest zarządzany przez SecretRef w bieżącym kontekście config/auth-profile. + - Wartości `apiKey` dostawców zarządzanych przez SecretRef są odświeżane ze znaczników źródła (`ENV_VAR_NAME` dla odwołań env, `secretref-managed` dla odwołań file/exec) zamiast zapisywania rozwiązanych sekretów. - Wartości nagłówków dostawców zarządzanych przez SecretRef są odświeżane ze znaczników źródła (`secretref-env:ENV_VAR_NAME` dla odwołań env, `secretref-managed` dla odwołań file/exec). - - Puste lub brakujące `apiKey`/`baseUrl` po stronie agenta wracają do `models.providers` w konfiguracji. + - Puste lub brakujące `apiKey`/`baseUrl` agenta wracają do `models.providers` w konfiguracji. - Pasujące `contextWindow`/`maxTokens` modelu używają wyższej wartości między jawną konfiguracją a niejawnymi wartościami katalogu. - Pasujące `contextTokens` modelu zachowuje jawny limit runtime, gdy jest obecny; użyj go, aby ograniczyć efektywny kontekst bez zmiany natywnych metadanych modelu. - - Użyj `models.mode: "replace"`, gdy chcesz, by konfiguracja całkowicie nadpisała `models.json`. - - Trwałość znaczników jest autorytatywna 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 runtime. + - Użyj `models.mode: "replace"`, gdy chcesz, aby konfiguracja całkowicie przepisała `models.json`. + - Trwałość znaczników jest źródłowo-autorytatywna: znaczniki są zapisywane z aktywnej migawki konfiguracji źródłowej (przed rozwiązaniem), a nie z rozwiązanych wartości sekretów runtime. ### Szczegóły pól dostawcy - `models.mode`: zachowanie katalogu dostawców (`merge` lub `replace`). -- `models.providers`: mapa własnych dostawców kluczowana identyfikatorem dostawcy. -- `models.providers.*.api`: adapter żądań (`openai-completions`, `openai-responses`, `anthropic-messages`, `google-generative-ai` itd). -- `models.providers.*.apiKey`: poświadczenie dostawcy (preferuj podstawianie SecretRef/env). +- `models.providers`: mapa własnych dostawców indeksowana przez id dostawcy. +- `models.providers.*.api`: adapter żądań (`openai-completions`, `openai-responses`, `anthropic-messages`, `google-generative-ai` itd.). +- `models.providers.*.apiKey`: poświadczenie dostawcy (preferuj SecretRef/podstawienie env). - `models.providers.*.auth`: strategia uwierzytelniania (`api-key`, `token`, `oauth`, `aws-sdk`). -- `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.*.baseUrl`: bazowy URL upstream API. -- `models.providers.*.headers`: dodatkowe statyczne nagłówki dla routingu proxy/dzierżawy. -- `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`). +- `models.providers.*.injectNumCtxForOpenAICompat`: dla Ollama + `openai-completions`, wstrzykuje `options.num_ctx` do żądań (domyślnie: `true`). +- `models.providers.*.authHeader`: wymusza transport poświadczenia w nagłówku `Authorization`, gdy jest to wymagane. +- `models.providers.*.baseUrl`: base URL API upstream. +- `models.providers.*.headers`: dodatkowe statyczne nagłówki dla routingu proxy/tenant. +- `models.providers.*.request`: nadpisania transportu dla żądań HTTP model-provider. + - `request.headers`: dodatkowe nagłówki (scalane z domyślnymi nagłówkami dostawcy). Wartości akceptują SecretRef. + - `request.auth`: nadpisanie strategii uwierzytelniania. Tryby: `"provider-default"` (użyj wbudowanego auth dostawcy), `"authorization-bearer"` (z `token`), `"header"` (z `headerName`, `value`, opcjonalnie `prefix`). - `request.proxy`: nadpisanie proxy HTTP. Tryby: `"env-proxy"` (użyj zmiennych env `HTTP_PROXY`/`HTTPS_PROXY`), `"explicit-proxy"` (z `url`). Oba tryby akceptują opcjonalny pod-obiekt `tls`. - `request.tls`: nadpisanie TLS dla połączeń bezpośrednich. Pola: `ca`, `cert`, `key`, `passphrase` (wszystkie akceptują SecretRef), `serverName`, `insecureSkipVerify`. - `models.providers.*.models`: jawne wpisy katalogu modeli dostawcy. - `models.providers.*.models.*.contextWindow`: natywne metadane okna kontekstu modelu. - `models.providers.*.models.*.contextTokens`: opcjonalny limit kontekstu runtime. Użyj tego, gdy chcesz mniejszy efektywny budżet kontekstu niż natywne `contextWindow` modelu. -- `models.providers.*.models.*.compat.supportsDeveloperRole`: opcjonalna wskazówka zgodności. Dla `api: "openai-completions"` z niepustym, nienatywnym `baseUrl` (host nie jest `api.openai.com`), OpenClaw wymusza w runtime `false`. Puste/pominięte `baseUrl` zachowuje domyślne zachowanie OpenAI. -- `models.providers.*.models.*.compat.requiresStringContent`: opcjonalna wskazówka zgodności dla endpointów czatu zgodnych z OpenAI obsługujących tylko ciągi. Gdy `true`, OpenClaw spłaszcza czysto tekstowe tablice `messages[].content` do zwykłych ciągów przed wysłaniem żądania. -- `plugins.entries.amazon-bedrock.config.discovery`: główny katalog ustawień auto-discovery Bedrock. -- `plugins.entries.amazon-bedrock.config.discovery.enabled`: włącz/wyłącz niejawne discovery. -- `plugins.entries.amazon-bedrock.config.discovery.region`: region AWS dla discovery. -- `plugins.entries.amazon-bedrock.config.discovery.providerFilter`: opcjonalny filtr identyfikatorów dostawców dla celowanego discovery. -- `plugins.entries.amazon-bedrock.config.discovery.refreshInterval`: interwał odpytywania odświeżania discovery. +- `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 działania. Puste/pominięte `baseUrl` zachowuje domyślne zachowanie OpenAI. +- `models.providers.*.models.*.compat.requiresStringContent`: opcjonalna wskazówka zgodności dla endpointów czatu zgodnych z OpenAI, które obsługują tylko stringi. Gdy `true`, OpenClaw spłaszcza czysto tekstowe tablice `messages[].content` do zwykłych stringów przed wysłaniem żądania. +- `plugins.entries.amazon-bedrock.config.discovery`: katalog główny ustawień auto-discovery Bedrock. +- `plugins.entries.amazon-bedrock.config.discovery.enabled`: włącz/wyłącz niejawne wykrywanie. +- `plugins.entries.amazon-bedrock.config.discovery.region`: region AWS dla wykrywania. +- `plugins.entries.amazon-bedrock.config.discovery.providerFilter`: opcjonalny filtr provider-id dla ukierunkowanego wykrywania. +- `plugins.entries.amazon-bedrock.config.discovery.refreshInterval`: interwał odpytywania dla odświeżania wykrywania. - `plugins.entries.amazon-bedrock.config.discovery.defaultContextWindow`: zapasowe okno kontekstu dla wykrytych modeli. - `plugins.entries.amazon-bedrock.config.discovery.defaultMaxTokens`: zapasowa maksymalna liczba tokenów wyjściowych dla wykrytych modeli. @@ -2495,7 +2495,7 @@ Ustaw `OPENCODE_API_KEY` (lub `OPENCODE_ZEN_API_KEY`). Używaj odwołań `openco Ustaw `ZAI_API_KEY`. `z.ai/*` i `z-ai/*` są akceptowanymi aliasami. Skrót: `openclaw onboard --auth-choice zai-api-key`. - Ogólny endpoint: `https://api.z.ai/api/paas/v4` -- Endpoint do programowania (domyślny): `https://api.z.ai/api/coding/paas/v4` +- Endpoint kodowania (domyślny): `https://api.z.ai/api/coding/paas/v4` - Dla ogólnego endpointu zdefiniuj własnego dostawcę z nadpisaniem base URL. @@ -2538,8 +2538,8 @@ Ustaw `ZAI_API_KEY`. `z.ai/*` i `z-ai/*` są akceptowanymi aliasami. Skrót: `op Dla endpointu China: `baseUrl: "https://api.moonshot.cn/v1"` lub `openclaw onboard --auth-choice moonshot-api-key-cn`. Natywne endpointy Moonshot deklarują zgodność użycia strumieniowania na współdzielonym -transporcie `openai-completions`, a OpenClaw teraz opiera to na możliwościach endpointu, -a nie wyłącznie na wbudowanym identyfikatorze dostawcy. +transporcie `openai-completions`, a OpenClaw opiera się tutaj na możliwościach endpointu, +a nie tylko na samym wbudowanym identyfikatorze dostawcy. @@ -2550,4 +2550,20 @@ a nie wyłącznie na wbudowanym identyfikatorze dostawcy. env: { KIMI_API_KEY: "sk-..." }, agents: { defaults: { - model: { primary: "kimi/kimi-code" }, \ No newline at end of file + model: { primary: "kimi/kimi-code" }, + models: { "kimi/kimi-code": { alias: "Kimi Code" } }, + }, + }, +} +``` + +Zgodny z Anthropic, wbudowany dostawca. Skrót: `openclaw onboard --auth-choice kimi-code-api-key`. + + + + + +```json5 +{ + env: { SYNTHETIC_API_KEY: "sk-..." }, + agents \ No newline at end of file diff --git a/docs/pl/gateway/doctor.md b/docs/pl/gateway/doctor.md index e8d2556ac..4fa987018 100644 --- a/docs/pl/gateway/doctor.md +++ b/docs/pl/gateway/doctor.md @@ -1,23 +1,22 @@ --- read_when: - - Dodawanie lub modyfikowanie migracji doctor - - Wprowadzanie niekompatybilnych zmian konfiguracji -summary: 'Polecenie Doctor: kontrole stanu, migracje konfiguracji i kroki naprawcze' + - Dodajesz lub modyfikujesz migracje Doctor + - Wprowadzasz niekompatybilne zmiany konfiguracji +summary: 'Komenda Doctor: kontrole kondycji, migracje konfiguracji i kroki naprawcze' title: Doctor x-i18n: - generated_at: "2026-04-08T02:15:39Z" + generated_at: "2026-04-09T01:29:21Z" model: gpt-5.4 provider: openai - source_hash: 3761a222d9db7088f78215575fa84e5896794ad701aa716e8bf9039a4424dca6 + source_hash: 75d321bd1ad0e16c29f2382e249c51edfc3a8d33b55bdceea39e7dbcd4901fce source_path: gateway/doctor.md workflow: 15 --- # Doctor -`openclaw doctor` to narzędzie naprawy i migracji dla OpenClaw. Naprawia -nieaktualną konfigurację i stan, sprawdza kondycję systemu oraz podaje -konkretne kroki naprawcze. +`openclaw doctor` to narzędzie naprawy i migracji dla OpenClaw. Naprawia nieaktualną +konfigurację i stan, sprawdza kondycję oraz podaje konkretne kroki naprawcze. ## Szybki start @@ -31,13 +30,13 @@ openclaw doctor openclaw doctor --yes ``` -Akceptuje domyślne opcje bez pytań (w tym kroki naprawy restartu/usługi/sandboxa, gdy mają zastosowanie). +Akceptuje wartości domyślne bez pytania (w tym kroki naprawy restartu/usługi/sandboxa, gdy mają zastosowanie). ```bash openclaw doctor --repair ``` -Stosuje zalecane naprawy bez pytań (naprawy + restarty tam, gdzie jest to bezpieczne). +Stosuje zalecane naprawy bez pytania (naprawy + restarty tam, gdzie to bezpieczne). ```bash openclaw doctor --repair --force @@ -49,14 +48,14 @@ Stosuje także agresywne naprawy (nadpisuje niestandardowe konfiguracje supervis openclaw doctor --non-interactive ``` -Uruchamia bez pytań i stosuje tylko bezpieczne migracje (normalizacja konfiguracji + przenoszenie stanu na dysku). Pomija działania restartu/usługi/sandboxa, które wymagają potwierdzenia człowieka. -Migracje starszego stanu są uruchamiane automatycznie po ich wykryciu. +Uruchamia bez monitów i stosuje tylko bezpieczne migracje (normalizacja konfiguracji + przenoszenie stanu na dysku). Pomija działania restartu/usługi/sandboxa wymagające potwierdzenia człowieka. +Migracje starszego stanu uruchamiają się automatycznie po ich wykryciu. ```bash openclaw doctor --deep ``` -Skanuje usługi systemowe pod kątem dodatkowych instalacji gatewaya (launchd/systemd/schtasks). +Skanuje usługi systemowe w poszukiwaniu dodatkowych instalacji gateway (launchd/systemd/schtasks). Jeśli chcesz przejrzeć zmiany przed zapisaniem, najpierw otwórz plik konfiguracji: @@ -66,46 +65,79 @@ cat ~/.openclaw/openclaw.json ## Co robi (podsumowanie) -- Opcjonalna aktualizacja przed uruchomieniem dla instalacji z gita (tylko interaktywnie). -- Sprawdzenie aktualności protokołu UI (przebudowuje Control UI, gdy schemat protokołu jest nowszy). -- Kontrola stanu + monit o restart. -- Podsumowanie stanu Skills (kwalifikujące się/brakujące/zablokowane) oraz stanu pluginów. +- Opcjonalna aktualizacja przed uruchomieniem dla instalacji git (tylko interaktywnie). +- Kontrola aktualności protokołu UI (przebudowuje Control UI, gdy schemat protokołu jest nowszy). +- Kontrola kondycji + monit o restart. +- Podsumowanie stanu Skills (kwalifikujące się/brakujące/zablokowane) i stanu pluginów. - Normalizacja konfiguracji dla starszych wartości. - Migracja konfiguracji Talk ze starszych płaskich pól `talk.*` do `talk.provider` + `talk.providers.`. - Kontrole migracji przeglądarki dla starszych konfiguracji rozszerzenia Chrome i gotowości Chrome MCP. -- Ostrzeżenia o nadpisaniu dostawcy OpenCode (`models.providers.opencode` / `models.providers.opencode-go`). -- Ostrzeżenia o przesłanianiu Codex OAuth (`models.providers.openai-codex`). -- Sprawdzenie wymagań TLS OAuth dla profili OpenAI Codex OAuth. -- 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 na najwyższym poziomie, `provider` w payload, proste zadania zapasowe webhooka z `notify: true`). -- Inspekcja plików blokady sesji i czyszczenie nieaktualnych blokad. -- Kontrole integralności i uprawnień stanu (sesje, transkrypty, katalog stanu). -- Kontrole uprawnień pliku konfiguracji (`chmod 600`) przy uruchomieniu lokalnym. -- Kondycja uwierzytelniania modeli: sprawdza wygaśnięcie OAuth, może odświeżyć wygasające tokeny i raportuje stany cooldown/wyłączenia profilu uwierzytelniania. +- Ostrzeżenia o nadpisaniach dostawcy OpenCode (`models.providers.opencode` / `models.providers.opencode-go`). +- Ostrzeżenia o przysłanianiu OAuth Codex (`models.providers.openai-codex`). +- Kontrola wymagań wstępnych TLS dla profili OAuth OpenAI Codex. +- Migracja starszego stanu na dysku (sessions/agent dir/uwierzytelnianie WhatsApp). +- Migracja starszych kluczy kontraktów manifestu pluginów (`speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, `webSearchProviders` → `contracts`). +- Migracja starszego magazynu cron (`jobId`, `schedule.cron`, pola delivery/payload na najwyższym poziomie, `provider` w payload, proste zadania zapasowe webhook z `notify: true`). +- Kontrola plików blokady sesji i czyszczenie przeterminowanych blokad. +- Kontrole integralności i uprawnień stanu (sessions, transcripts, katalog stanu). +- Kontrole uprawnień pliku konfiguracji (`chmod 600`) przy uruchamianiu lokalnie. +- Kondycja uwierzytelniania modeli: sprawdza wygaśnięcie OAuth, może odświeżać tokeny bliskie wygaśnięcia i raportuje stany cooldown/wyłączenia profilów uwierzytelniania. - Wykrywanie dodatkowego katalogu workspace (`~/openclaw`). - Naprawa obrazu sandboxa, gdy sandboxing jest włączony. -- Migracja starszych usług i wykrywanie dodatkowych gatewayów. +- Migracja starszych usług i wykrywanie dodatkowych gateway. - Migracja starszego stanu kanału Matrix (w trybie `--fix` / `--repair`). -- Kontrole środowiska uruchomieniowego gatewaya (usługa zainstalowana, ale nie działa; zapisany w pamięci podręcznej label launchd). -- Ostrzeżenia o stanie kanałów (sondowane z działającego gatewaya). +- Kontrole runtime gateway (usługa zainstalowana, ale nieuruchomiona; zapisany w pamięci podręcznej label launchd). +- Ostrzeżenia o stanie kanałów (sprawdzane z działającego gateway). - Audyt konfiguracji supervisora (launchd/systemd/schtasks) z opcjonalną naprawą. -- Kontrole dobrych praktyk środowiska uruchomieniowego gatewaya (Node vs Bun, ścieżki menedżera wersji). -- Diagnostyka kolizji portu gatewaya (domyślnie `18789`). -- Ostrzeżenia bezpieczeństwa dla otwartych zasad DM. -- Kontrole uwierzytelniania gatewaya dla lokalnego trybu tokena (oferuje wygenerowanie tokena, gdy nie istnieje żadne źródło tokena; nie nadpisuje konfiguracji tokenów SecretRef). -- Sprawdzenie `systemd linger` w systemie Linux. -- Sprawdzenie rozmiaru plików bootstrap workspace (ostrzeżenia o obcięciu / zbliżaniu się do limitu dla plików kontekstowych). -- Sprawdzenie stanu autouzupełniania powłoki i automatyczna instalacja/aktualizacja. -- Sprawdzenie gotowości dostawcy embeddingów wyszukiwania pamięci (model lokalny, zdalny klucz API lub binarka QMD). +- Kontrole dobrych praktyk runtime gateway (Node vs Bun, ścieżki menedżera wersji). +- Diagnostyka konfliktów portu gateway (domyślnie `18789`). +- Ostrzeżenia bezpieczeństwa dla otwartych polityk DM. +- Kontrole uwierzytelniania gateway dla lokalnego trybu tokena (oferuje wygenerowanie tokena, gdy nie istnieje jego źródło; nie nadpisuje konfiguracji tokenów SecretRef). +- Kontrola `systemd linger` w Linuxie. +- Kontrola rozmiaru plików bootstrap workspace (ostrzeżenia o obcięciu / blisko limitu dla plików kontekstu). +- Kontrola stanu shell completion oraz automatyczna instalacja/aktualizacja. +- Kontrola gotowości dostawcy embeddingów do wyszukiwania pamięci (model lokalny, zdalny klucz API lub binarka QMD). - Kontrole instalacji ze źródeł (niezgodność workspace pnpm, brakujące zasoby UI, brakująca binarka tsx). - Zapisuje zaktualizowaną konfigurację + metadane kreatora. -## Szczegółowe działanie i uzasadnienie +## Backfill i reset Dreams UI -### 0) Opcjonalna aktualizacja (instalacje z gita) +Scena Dreams w Control UI zawiera działania **Backfill**, **Reset** i **Clear Grounded** +dla ugruntowanego przepływu dreaming. Te działania używają metod RPC +w stylu doctor gateway, ale **nie** są częścią naprawy/migracji w CLI `openclaw doctor`. -Jeśli jest to checkout z gita i doctor działa interaktywnie, oferuje +Co robią: + +- **Backfill** skanuje historyczne pliki `memory/YYYY-MM-DD.md` w aktywnym + workspace, uruchamia ugruntowany przebieg dziennika REM i zapisuje odwracalne wpisy + backfill do `DREAMS.md`. +- **Reset** usuwa z `DREAMS.md` tylko te oznaczone wpisy dziennika backfill. +- **Clear Grounded** usuwa tylko przygotowane wpisy krótkoterminowe typu grounded-only, + które pochodzą z historycznego odtworzenia i nie zgromadziły jeszcze aktywnego wsparcia + z przypomnień ani z dziennych danych. + +Czego same z siebie **nie** robią: + +- nie edytują `MEMORY.md` +- nie uruchamiają pełnych migracji doctor +- nie przygotowują automatycznie ugruntowanych kandydatów w aktywnym magazynie + promocji krótkoterminowej, chyba że najpierw jawnie uruchomisz ścieżkę CLI z przygotowaniem + +Jeśli chcesz, aby ugruntowane historyczne odtworzenie wpływało na zwykłą ścieżkę +promocji deep, użyj zamiast tego przepływu CLI: + +```bash +openclaw memory rem-backfill --path ./memory --stage-short-term +``` + +To przygotowuje ugruntowanych trwałych kandydatów w krótkoterminowym magazynie dreaming, pozostawiając +`DREAMS.md` jako powierzchnię do przeglądu. + +## Szczegółowe zachowanie i uzasadnienie + +### 0) Opcjonalna aktualizacja (instalacje git) + +Jeśli jest to checkout git, a doctor działa interaktywnie, oferuje aktualizację (fetch/rebase/build) przed uruchomieniem doctor. ### 1) Normalizacja konfiguracji @@ -114,25 +146,24 @@ Jeśli konfiguracja zawiera starsze kształty wartości (na przykład `messages. bez nadpisania specyficznego dla kanału), doctor normalizuje je do bieżącego schematu. -Dotyczy to także starszych płaskich pól Talk. Obecna publiczna konfiguracja Talk to -`talk.provider` + `talk.providers.`. Doctor przepisuje stare kształty -`talk.voiceId` / `talk.voiceAliases` / `talk.modelId` / `talk.outputFormat` / -`talk.apiKey` do mapy dostawców. +Obejmuje to starsze płaskie pola Talk. Bieżąca publiczna konfiguracja Talk to +`talk.provider` + `talk.providers.`. Doctor przepisuje stare +kształty `talk.voiceId` / `talk.voiceAliases` / `talk.modelId` / `talk.outputFormat` / +`talk.apiKey` do mapy dostawcy. ### 2) Migracje starszych kluczy konfiguracji -Gdy konfiguracja zawiera przestarzałe klucze, inne polecenia odmawiają działania i proszą, -aby uruchomić `openclaw doctor`. +Gdy konfiguracja zawiera przestarzałe klucze, inne polecenia odmawiają uruchomienia i proszą +o uruchomienie `openclaw doctor`. -Doctor wykona wtedy: +Doctor: -- Wyjaśni, które starsze klucze zostały znalezione. -- Pokaże zastosowaną migrację. -- Przepisze `~/.openclaw/openclaw.json` z użyciem zaktualizowanego schematu. +- Wyjaśnia, które starsze klucze zostały znalezione. +- Pokazuje zastosowaną migrację. +- Przepisuje `~/.openclaw/openclaw.json` z użyciem zaktualizowanego schematu. -Gateway uruchamia także migracje doctor automatycznie przy starcie, gdy wykryje -starszy format konfiguracji, dzięki czemu nieaktualne konfiguracje są naprawiane -bez ręcznej interwencji. +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 są obsługiwane przez `openclaw doctor --fix`. Bieżące migracje: @@ -157,7 +188,7 @@ Bieżące migracje: - `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 z pozostałymi jednokontowymi wartościami kanału na najwyższym poziomie, przenieś te wartości przypisane do konta do wybranego promowanego konta dla tego kanału (`accounts.default` dla większości kanałów; Matrix może zachować istniejący pasujący nazwany/domyslny cel) +- Dla kanałów z nazwanymi `accounts`, ale z pozostawionymi na najwyższym poziomie wartościami kanału dla pojedynczego konta, przenieś te wartości ograniczone do konta do promowanego 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) - `identity` → `agents.list[].identity` - `agent.*` → `agents.defaults` + `tools.*` (tools/elevated/exec/sandbox/subagents) - `agent.model`/`allowedModels`/`modelAliases`/`modelFallbacks`/`imageModelFallbacks` @@ -166,77 +197,77 @@ Bieżące migracje: - `browser.profiles.*.driver: "extension"` → `"existing-session"` - usuń `browser.relayBindHost` (starsze ustawienie relay rozszerzenia) -Ostrzeżenia doctor obejmują też wskazówki dotyczące domyślnego konta dla kanałów wielokontowych: +Ostrzeżenia doctor obejmują także wskazówki dotyczące domyślnego konta dla kanałów wielokontowych: -- Jeśli skonfigurowano dwa lub więcej wpisów `channels..accounts` bez `channels..defaultAccount` lub `accounts.default`, doctor ostrzega, że routing zapasowy może wybrać nieoczekiwane konto. -- Jeśli ustawiono `channels..defaultAccount` na nieznany identyfikator konta, doctor ostrzega i wyświetla listę skonfigurowanych identyfikatorów kont. +- Jeśli skonfigurowano co najmniej dwa wpisy `channels..accounts` bez `channels..defaultAccount` lub `accounts.default`, doctor ostrzega, że routowanie zapasowe może wybrać nieoczekiwane konto. +- Jeśli `channels..defaultAccount` jest ustawione na nieznany identyfikator konta, doctor ostrzega i wypisuje skonfigurowane identyfikatory kont. ### 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ć użycie niewłaściwego API dla modeli albo wyzerować koszty. Doctor ostrzega, aby -można było usunąć nadpisanie i przywrócić routing API oraz koszty dla każdego modelu. +Może to wymusić przypisanie modeli do niewłaściwego API albo wyzerować koszty. Doctor ostrzega, aby można było +usunąć nadpisanie i przywrócić routowanie API oraz koszty per model. ### 2c) Migracja przeglądarki i gotowość Chrome MCP -Jeśli konfiguracja przeglądarki nadal wskazuje na usuniętą ścieżkę rozszerzenia Chrome, doctor -normalizuje ją do obecnego modelu dołączania Chrome MCP lokalnego dla hosta: +Jeśli konfiguracja przeglądarki nadal wskazuje usuniętą ścieżkę rozszerzenia Chrome, doctor +normalizuje ją do obecnego modelu dołączania Chrome MCP host-local: - `browser.profiles.*.driver: "extension"` zmienia się na `"existing-session"` - `browser.relayBindHost` jest usuwane -Doctor audytuje też lokalną dla hosta ścieżkę Chrome MCP, gdy używasz `defaultProfile: -"user"` albo skonfigurowanego profilu `existing-session`: +Doctor audytuje też ścieżkę Chrome MCP host-local, 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, czy Google Chrome jest zainstalowane na tym samym hoście dla domyślnych + profili auto-connect - 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 +- przypomina o włączeniu zdalnego debugowania na stronie inspect przeglądarki (na przykład `chrome://inspect/#remote-debugging`, `brave://inspect/#remote-debugging`, lub `edge://inspect/#remote-debugging`) -Doctor nie może włączyć ustawienia po stronie Chrome za Ciebie. Lokalny dla hosta Chrome MCP +Doctor nie może włączyć za Ciebie ustawienia po stronie Chrome. Chrome MCP host-local nadal wymaga: -- przeglądarki opartej na Chromium 144+ na hoście gatewaya/noda +- przeglądarki opartej na Chromium 144+ na hoście gateway/node - lokalnie uruchomionej przeglądarki - włączonego zdalnego debugowania w tej przeglądarce -- zatwierdzenia pierwszego monitu o zgodę na dołączenie w przeglądarce +- zatwierdzenia pierwszego monitu o zgodę na połączenie w przeglądarce -Gotowość w tym miejscu dotyczy wyłącznie wymagań wstępnych lokalnego dołączania. Existing-session zachowuje -obecne ograniczenia tras Chrome MCP; zaawansowane trasy, takie jak `responsebody`, eksport PDF, +Gotowość tutaj dotyczy wyłącznie lokalnych wymagań wstępnych dołączenia. Existing-session zachowuje +bieżące ograniczenia tras Chrome MCP; zaawansowane trasy, takie jak `responsebody`, eksport PDF, przechwytywanie pobierania i działania wsadowe, nadal wymagają zarządzanej przeglądarki lub surowego profilu CDP. -To sprawdzenie **nie** dotyczy Docker, sandbox, remote-browser ani innych -przepływów bezgłowych. One nadal używają surowego CDP. +Ta kontrola **nie** dotyczy Docker, sandbox, remote-browser ani innych +przepływów bezgłowych. Nadal używają one surowego CDP. -### 2d) Wymagania TLS OAuth +### 2d) Wymagania wstępne OAuth TLS -Gdy skonfigurowany jest profil OpenAI Codex OAuth, doctor sonduje punkt końcowy +Gdy skonfigurowany jest profil OAuth OpenAI Codex, doctor sonduje endpoint autoryzacji OpenAI, aby sprawdzić, czy lokalny stos TLS Node/OpenSSL potrafi -zweryfikować łańcuch certyfikatów. Jeśli sonda zakończy się błędem certyfikatu (na -przykład `UNABLE_TO_GET_ISSUER_CERT_LOCALLY`, wygasły certyfikat lub certyfikat własny), -doctor wyświetla wskazówki naprawcze specyficzne dla platformy. W systemie macOS z Node z Homebrew -naprawą jest zwykle `brew postinstall ca-certificates`. Z `--deep` sonda działa -nawet wtedy, gdy gateway jest zdrowy. +zweryfikować łańcuch certyfikatów. Jeśli sonda kończy się błędem certyfikatu (na +przykład `UNABLE_TO_GET_ISSUER_CERT_LOCALLY`, wygasły certyfikat lub certyfikat samopodpisany), +doctor wypisuje wskazówki naprawy specyficzne dla platformy. W macOS z Node z Homebrew +naprawą jest zwykle `brew postinstall ca-certificates`. Z `--deep` sonda uruchamia się +nawet wtedy, gdy gateway jest w dobrym stanie. -### 2c) Nadpisania dostawcy Codex OAuth +### 2c) Nadpisania dostawcy OAuth Codex Jeśli wcześniej dodano starsze ustawienia transportu OpenAI w -`models.providers.openai-codex`, mogą one przesłaniać wbudowaną ścieżkę -dostawcy Codex OAuth, której nowsze wydania używają automatycznie. Doctor ostrzega, gdy wykryje -te stare ustawienia transportu razem z Codex OAuth, aby można było usunąć lub przepisać -nieaktualne nadpisanie transportu i odzyskać wbudowane zachowanie routingu/fallbacku. -Niestandardowe proxy i nadpisania samych nagłówków są nadal obsługiwane i nie +`models.providers.openai-codex`, mogą one przysł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ć +nieaktualne nadpisanie transportu i odzyskać wbudowane zachowanie routingu/fallbacków. +Niestandardowe proxy i nadpisania tylko nagłówków są nadal wspierane i nie wywołują tego ostrzeżenia. ### 3) Migracje starszego stanu (układ na dysku) Doctor może migrować starsze układy na dysku do bieżącej struktury: -- Magazyn sesji + transkrypty: +- Magazyn sessions + transcripts: - z `~/.openclaw/sessions/` do `~/.openclaw/agents//sessions/` - Katalog agenta: - z `~/.openclaw/agent/` do `~/.openclaw/agents//agent/` @@ -244,13 +275,13 @@ Doctor może migrować starsze układy na dysku do bieżącej struktury: - ze starszego `~/.openclaw/credentials/*.json` (z wyjątkiem `oauth.json`) - do `~/.openclaw/credentials/whatsapp//...` (domyślny identyfikator konta: `default`) -Te migracje są realizowane w trybie best-effort i są idempotentne; doctor wyemituje ostrzeżenia, gdy -pozostawi jakiekolwiek starsze foldery jako kopie zapasowe. Gateway/CLI również automatycznie migruje -starsze sesje + katalog agenta przy starcie, dzięki czemu historia/uwierzytelnianie/modele trafiają do -ścieżki per-agent bez ręcznego uruchamiania doctor. Uwierzytelnianie WhatsApp jest celowo -migrowane tylko przez `openclaw doctor`. Normalizacja dostawcy/mapy dostawców Talk porównuje teraz +Te migracje są wykonywane w trybie best-effort i są idempotentne; doctor będzie emitować ostrzeżenia, gdy +pozostawi jakiekolwiek starsze foldery jako kopie zapasowe. Gateway/CLI także automatycznie migruje +starsze sessions + katalog agenta przy starcie, dzięki czemu historia/uwierzytelnianie/modele trafiają do +ścieżki per agent bez ręcznego uruchamiania doctor. Uwierzytelnianie WhatsApp jest celowo migrowane wyłącznie +przez `openclaw doctor`. Normalizacja Talk provider/provider-map porównuje teraz według równości strukturalnej, więc różnice wyłącznie w kolejności kluczy nie wywołują już -powtarzanych zmian bez efektu przez `doctor --fix`. +powtarzających się, pustych zmian `doctor --fix`. ### 3a) Migracje starszych manifestów pluginów @@ -259,15 +290,15 @@ możliwości na najwyższym poziomie (`speechProviders`, `realtimeTranscriptionP `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, `webSearchProviders`). Gdy je znajdzie, 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 +i przepisanie pliku manifestu na miejscu. Ta migracja jest idempotentna; +jeśli klucz `contracts` zawiera już te same wartości, starszy klucz jest usuwany bez duplikowania danych. ### 3b) Migracje starszego magazynu cron -Doctor sprawdza także magazyn zadań cron (`~/.openclaw/cron/jobs.json` domyślnie, -lub `cron.store`, jeśli został nadpisany) pod kątem starych kształtów zadań, które harmonogram -nadal akceptuje ze względów kompatybilności. +Doctor sprawdza też magazyn zadań cron (`~/.openclaw/cron/jobs.json` domyślnie, +lub `cron.store`, jeśli został nadpisany) pod kątem starych kształtów zadań, które scheduler nadal +akceptuje dla zgodności. Bieżące porządki cron obejmują: @@ -276,66 +307,71 @@ Bieżące porządki cron obejmują: - pola payload na najwyższym poziomie (`message`, `model`, `thinking`, ...) → `payload` - pola delivery na najwyższym poziomie (`deliver`, `channel`, `to`, `provider`, ...) → `delivery` - aliasy delivery `provider` w payload → jawne `delivery.channel` -- proste starsze zadania zapasowe webhooka `notify: true` → jawne `delivery.mode="webhook"` z `delivery.to=cron.webhook` +- proste starsze zadania zapasowe 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 zapasowy mechanizm notify z istniejącym +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. ### 3c) Czyszczenie blokad sesji -Doctor skanuje każdy katalog sesji agenta w poszukiwaniu nieaktualnych plików blokady zapisu — plików -pozostawionych po nieprawidłowym zakończeniu sesji. Dla każdego znalezionego pliku blokady raportuje: -ścieżkę, PID, czy PID nadal żyje, wiek blokady i czy jest -uznawana za nieaktualną (martwy PID lub więcej niż 30 minut). W trybie `--fix` / `--repair` -automatycznie usuwa nieaktualne pliki blokady; w przeciwnym razie wyświetla notatkę i -instrukcję, aby uruchomić ponownie z `--fix`. +Doctor skanuje każdy katalog sesji agenta w poszukiwaniu przeterminowanych 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 przeterminowaną (martwy PID lub starsza niż 30 minut). W trybie `--fix` / `--repair` +automatycznie usuwa przeterminowane pliki blokad; w przeciwnym razie wypisuje uwagę i +poleca ponowne uruchomienie z `--fix`. ### 4) Kontrole integralności stanu (trwałość sesji, routing i bezpieczeństwo) -Katalog stanu to operacyjny pień mózgu systemu. Jeśli zniknie, stracisz -sesje, poświadczenia, logi i konfigurację (chyba że masz kopie zapasowe gdzie indziej). +Katalog stanu to operacyjny pień mózgu. Jeśli zniknie, tracisz +sessions, credentials, logi i konfigurację (chyba że masz kopie zapasowe gdzie indziej). Doctor sprawdza: -- **Brak katalogu stanu**: ostrzega o katastrofalnej utracie stanu, proponuje odtworzenie +- **Brak katalogu stanu**: ostrzega o katastrofalnej utracie stanu, prosi o odtworzenie katalogu i przypomina, że nie może odzyskać brakujących danych. - **Uprawnienia katalogu stanu**: weryfikuje możliwość zapisu; oferuje naprawę uprawnień - (i wyświetla wskazówkę `chown`, gdy wykryje niezgodność właściciela/grupy). -- **Katalog stanu synchronizowany z chmurą w macOS**: ostrzega, gdy stan znajduje się pod iCloud Drive + (i emituje wskazówkę `chown`, gdy wykryje niezgodność właściciela/grupy). +- **Katalog stanu synchronizowany przez chmurę w macOS**: ostrzega, gdy stan rozwiązuje się do 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 na Linux na SD lub eMMC**: ostrzega, gdy stan znajduje się na źródle montowania `mmcblk*`, + i wyścigi blokad/synchronizacji. +- **Katalog stanu na SD lub eMMC w Linuxie**: ostrzega, gdy stan rozwiązuje się do źródła montowania `mmcblk*`, ponieważ losowe I/O na nośnikach SD lub eMMC może być wolniejsze i szybciej zużywać nośnik - przy zapisie sesji i poświadczeń. + przy zapisach sesji i credentials. - **Brak katalogów sesji**: `sessions/` i katalog magazynu sesji są - wymagane do trwałego zapisywania historii i unikania awarii `ENOENT`. -- **Niezgodność transkryptu**: ostrzega, gdy ostatnie wpisy sesji mają brakujące - pliki transkryptu. -- **Główna sesja „1-wierszowy JSONL”**: sygnalizuje, gdy główny transkrypt ma tylko jeden - wiersz (historia się nie gromadzi). + wymagane do utrwalenia historii i unikania awarii `ENOENT`. +- **Niezgodność transcript**: ostrzega, gdy ostatnie wpisy sesji mają brakujące + pliki transcript. +- **Główna sesja „1-line JSONL”**: oznacza sytuację, gdy główny transcript ma tylko jedną + linię (historia się nie kumuluje). - **Wiele katalogów stanu**: ostrzega, gdy istnieje wiele folderów `~/.openclaw` w różnych - katalogach domowych lub gdy `OPENCLAW_STATE_DIR` wskazuje inne miejsce (historia może się - rozdzielać między instalacjami). -- **Przypomnienie o trybie zdalnym**: jeśli `gateway.mode=remote`, doctor przypomina, aby uruchomić - go na zdalnym hoście (tam znajduje się stan). + katalogach domowych lub gdy `OPENCLAW_STATE_DIR` wskazuje inne miejsce (historia może + zostać rozdzielona między instalacje). +- **Przypomnienie o trybie zdalnym**: jeśli `gateway.mode=remote`, doctor przypomina o jego uruchomieniu + na zdalnym hoście (tam znajduje się stan). - **Uprawnienia pliku konfiguracji**: ostrzega, jeśli `~/.openclaw/openclaw.json` jest - czytelny dla grupy/świata i oferuje zaostrzenie do `600`. + czytelny dla grupy/świata, i oferuje zaostrzenie do `600`. ### 5) Kondycja uwierzytelniania modeli (wygaśnięcie OAuth) Doctor sprawdza profile OAuth w magazynie uwierzytelniania, ostrzega, gdy tokeny wygasają lub wygasły, i może je odświeżyć, gdy jest to bezpieczne. Jeśli profil -OAuth/token Anthropic jest nieaktualny, sugeruje użycie klucza API Anthropic albo -ścieżki setup-token Anthropic. +OAuth/token Anthropic jest nieaktualny, sugeruje klucz API Anthropic lub +ścieżkę setup-token Anthropic. Monity o odświeżenie pojawiają się tylko w trybie interaktywnym (TTY); `--non-interactive` -pomija próby odświeżenia. +pomija próby odświeżania. -Doctor raportuje też profile uwierzytelniania, które są tymczasowo nieużywalne z powodu: +Gdy odświeżenie OAuth kończy się trwałym niepowodzeniem (na przykład `refresh_token_reused`, +`invalid_grant` lub dostawca informuje, że trzeba zalogować się ponownie), doctor zgłasza, +że wymagana jest ponowna autoryzacja, i wypisuje dokładną komendę `openclaw models auth login --provider ...`, +którą należy uruchomić. -- krótkich cooldownów (rate limits/timeouts/błędy uwierzytelniania) -- dłuższych wyłączeń (problemy z rozliczeniami/kredytem) +Doctor raportuje także profile uwierzytelniania, które są tymczasowo nieużywalne z powodu: + +- krótkich cooldownów (limity szybkości/timeouty/błędy uwierzytelniania) +- dłuższych wyłączeń (problemy z rozliczeniami/kredytami) ### 6) Walidacja modelu hooks @@ -345,36 +381,35 @@ katalogu i listy dozwolonych modeli oraz ostrzega, gdy nie będzie się rozwiąz ### 7) Naprawa obrazu sandboxa Gdy sandboxing jest włączony, doctor sprawdza obrazy Docker i oferuje ich zbudowanie lub -przełączenie na starsze nazwy, jeśli obecny obraz nie istnieje. +przełączenie na starsze nazwy, jeśli bieżący obraz jest niedostępny. -### 7b) Zależności uruchomieniowe bundlowanych pluginów +### 7b) Zależności runtime bundlowanych pluginów -Doctor weryfikuje, czy zależności uruchomieniowe bundlowanych pluginów (na przykład -pakiety uruchomieniowe pluginu Discord) są obecne w katalogu głównym instalacji OpenClaw. -Jeśli którychś brakuje, doctor raportuje pakiety i instaluje je w trybie -`openclaw doctor --fix` / `openclaw doctor --repair`. +Doctor weryfikuje, czy zależności runtime bundlowanych pluginów (na przykład +pakiety runtime pluginu Discord) są obecne w katalogu głównym instalacji OpenClaw. +Jeśli którychkolwiek brakuje, doctor raportuje pakiety i instaluje je w +trybie `openclaw doctor --fix` / `openclaw doctor --repair`. -### 8) Migracje usług gatewaya i wskazówki dotyczące czyszczenia +### 8) Migracje usług gateway i wskazówki czyszczenia -Doctor wykrywa starsze usługi gatewaya (launchd/systemd/schtasks) i -oferuje ich usunięcie oraz instalację usługi OpenClaw z użyciem bieżącego portu gatewaya. -Może też skanować w poszukiwaniu dodatkowych usług podobnych do gatewaya i wyświetlać wskazówki porządkowe. -Usługi gatewaya OpenClaw nazwane według profilu są traktowane jako pełnoprawne i nie są +Doctor wykrywa starsze usługi gateway (launchd/systemd/schtasks) i +oferuje ich usunięcie oraz instalację usługi OpenClaw z użyciem bieżącego portu gateway. +Może też skanować w poszukiwaniu dodatkowych usług podobnych do gateway i wypisywać wskazówki czyszczenia. +Usługi gateway OpenClaw nazwane profilem są traktowane jako pełnoprawne i nie są oznaczane jako „dodatkowe”. -### 8b) Migracja Matrix przy starcie +### 8b) Migracja Matrix przy uruchamianiu Gdy konto kanału Matrix ma oczekującą lub możliwą do wykonania migrację starszego stanu, doctor (w trybie `--fix` / `--repair`) tworzy snapshot przed migracją, a następnie -uruchamia kroki migracji w trybie best-effort: migrację starszego stanu Matrix oraz 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. +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 i +uruchamianie trwa dalej. W trybie tylko do odczytu (`openclaw doctor` bez `--fix`) ta kontrola +jest całkowicie pomijana. ### 9) Ostrzeżenia bezpieczeństwa Doctor emituje ostrzeżenia, gdy dostawca jest otwarty na DM bez listy dozwolonych, -albo gdy zasada jest skonfigurowana w niebezpieczny sposób. +lub gdy polityka jest skonfigurowana w niebezpieczny sposób. ### 10) systemd linger (Linux) @@ -383,80 +418,80 @@ gateway pozostał aktywny po wylogowaniu. ### 11) Stan workspace (Skills, pluginy i starsze katalogi) -Doctor wyświetla podsumowanie stanu workspace dla domyślnego agenta: +Doctor wypisuje podsumowanie stanu workspace dla domyślnego agenta: -- **Stan Skills**: liczba skills kwalifikujących się, z brakującymi wymaganiami i zablokowanych przez allowlistę. +- **Stan Skills**: liczba Skills kwalifikujących się, z brakującymi wymaganiami i zablokowanych przez allowlist. - **Starsze katalogi workspace**: ostrzega, gdy `~/openclaw` lub inne starsze katalogi workspace istnieją obok bieżącego workspace. -- **Stan pluginów**: liczba załadowanych/wyłączonych/pluginów z błędami; wyświetla identyfikatory pluginów dla wszystkich - błędów; raportuje możliwości bundlowanych pluginów. -- **Ostrzeżenia o zgodności pluginów**: oznacza pluginy, które mają problemy ze zgodnością z - bieżącym środowiskiem uruchomieniowym. +- **Stan pluginów**: liczby pluginów załadowanych/wyłączonych/z błędami; wypisuje identyfikatory pluginów dla + błędów; raportuje możliwości bundle plugin. +- **Ostrzeżenia o zgodności pluginów**: oznacza pluginy, które mają problemy zgodności z + bieżącym runtime. - **Diagnostyka pluginów**: pokazuje wszelkie ostrzeżenia lub błędy z czasu ładowania emitowane przez rejestr pluginów. ### 11b) Rozmiar pliku bootstrap Doctor sprawdza, czy pliki bootstrap workspace (na przykład `AGENTS.md`, -`CLAUDE.md` lub inne wstrzykiwane pliki kontekstowe) są blisko skonfigurowanego -limitu znaków lub go przekraczają. Raportuje dla każdego pliku liczbę surowych i wstrzykniętych 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 wyświetla wskazówki dotyczące dostrojenia `agents.defaults.bootstrapMaxChars` +`CLAUDE.md` lub inne wstrzykiwane pliki kontekstowe) są blisko lub powyżej skonfigurowanego +budżetu znaków. Raportuje dla każdego pliku liczbę znaków surowych vs. wstrzykniętych, 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`. -### 11c) Autouzupełnianie powłoki +### 11c) Shell completion -Doctor sprawdza, czy autouzupełnianie tabulatorem jest zainstalowane dla bieżącej powłoki +Doctor sprawdza, czy autouzupełnianie jest zainstalowane dla bieżącej powłoki (zsh, bash, fish lub PowerShell): -- Jeśli profil powłoki używa wolnego dynamicznego wzorca autouzupełniania +- Jeśli profil powłoki używa wolnego wzorca dynamic completion (`source <(openclaw completion ...)`), doctor aktualizuje go do szybszego - wariantu z plikiem cache. -- Jeśli autouzupełnianie jest skonfigurowane w profilu, ale brakuje pliku cache, - doctor automatycznie odtwarza cache. -- Jeśli autouzupełnianie nie jest w ogóle skonfigurowane, doctor proponuje jego instalację - (tylko w trybie interaktywnym; pomijane z `--non-interactive`). + wariantu z buforowanym plikiem. +- Jeśli completion jest skonfigurowane w profilu, ale brakuje pliku cache, + doctor automatycznie regeneruje cache. +- Jeśli completion w ogóle nie jest skonfigurowane, doctor pyta o instalację + (tylko w trybie interaktywnym; pomijane przy `--non-interactive`). -Uruchom `openclaw completion --write-state`, aby ręcznie odtworzyć cache. +Uruchom `openclaw completion --write-state`, aby ręcznie zregenerować cache. -### 12) Kontrole uwierzytelniania gatewaya (lokalny token) +### 12) Kontrole uwierzytelniania gateway (lokalny token) -Doctor sprawdza gotowość lokalnego uwierzytelniania tokenem gatewaya. +Doctor sprawdza gotowość uwierzytelniania lokalnego tokena gateway. -- Jeśli tryb tokena potrzebuje tokena i nie istnieje żadne źródło tokena, doctor proponuje jego wygenerowanie. +- Jeśli tryb tokena wymaga tokena, a nie istnieje jego źródło, doctor oferuje jego wygenerowanie. - Jeśli `gateway.auth.token` jest zarządzany przez SecretRef, ale niedostępny, doctor ostrzega i nie nadpisuje go jawnym tekstem. -- `openclaw doctor --generate-gateway-token` wymusza generowanie tylko wtedy, gdy nie skonfigurowano tokena SecretRef. +- `openclaw doctor --generate-gateway-token` wymusza generowanie tylko wtedy, gdy nie skonfigurowano SecretRef tokena. -### 12b) Naprawy świadome SecretRef w trybie tylko do odczytu +### 12b) Naprawy tylko do odczytu uwzględniające SecretRef -Niektóre ścieżki naprawy muszą sprawdzać skonfigurowane poświadczenia bez osłabiania zachowania fail-fast w runtime. +Niektóre przepływy naprawcze muszą sprawdzać skonfigurowane credentials bez osłabiania zachowania fail-fast w runtime. -- `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, jeśli 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 kończyć się awarią lub błędnie raportować brak tokena. +- `openclaw doctor --fix` używa teraz tego samego modelu podsumowania SecretRef tylko do odczytu, co polecenia z rodziny status, do ukierunkowanych napraw konfiguracji. +- Przykład: naprawa `allowFrom` / `groupAllowFrom` Telegram z `@username` próbuje użyć skonfigurowanych credentials 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 credential jest skonfigurowany, ale niedostępny, i pomija automatyczne rozwiązywanie zamiast kończyć się awarią lub błędnie raportować brak tokena. -### 13) Kontrola stanu gatewaya + restart +### 13) Kontrola kondycji gateway + restart -Doctor uruchamia kontrolę stanu i oferuje restart gatewaya, gdy wygląda on na -niezdrowy. +Doctor uruchamia kontrolę kondycji i oferuje restart gateway, gdy wygląda +na niezdrowy. ### 13b) Gotowość wyszukiwania pamięci -Doctor sprawdza, czy skonfigurowany dostawca embeddingów wyszukiwania pamięci jest gotowy +Doctor sprawdza, czy skonfigurowany dostawca embeddingów do wyszukiwania pamięci jest gotowy dla domyślnego agenta. Zachowanie zależy od skonfigurowanego backendu i dostawcy: -- **Backend QMD**: sonduje, czy binarka `qmd` jest dostępna i daje się uruchomić. - Jeśli nie, wyświetla wskazówki naprawcze, w tym pakiet npm i opcję ręcznej ścieżki do binarki. -- **Jawny dostawca lokalny**: sprawdza istnienie lokalnego pliku modelu lub rozpoznanego +- **Backend QMD**: sonduje, czy binarka `qmd` jest dostępna i da się ją uruchomić. + Jeśli nie, wypisuje wskazówki naprawy, w tym pakiet npm i opcję ręcznej ścieżki do binarki. +- **Jawny dostawca lokalny**: sprawdza obecność lokalnego pliku modelu lub rozpoznawanego zdalnego/pobieralnego URL modelu. Jeśli go brakuje, sugeruje przełączenie na zdalnego dostawcę. -- **Jawny dostawca zdalny** (`openai`, `voyage` itd.): weryfikuje, czy klucz API jest - obecny w środowisku lub magazynie uwierzytelniania. Jeśli go brakuje, wyświetla praktyczne wskazówki naprawcze. -- **Dostawca automatyczny**: najpierw sprawdza dostępność modelu lokalnego, a następnie próbuje każdego zdalnego - dostawcę w kolejności automatycznego wyboru. +- **Jawny dostawca zdalny** (`openai`, `voyage` itp.): sprawdza, czy klucz API jest + obecny w środowisku lub magazynie uwierzytelniania. W razie braku wypisuje konkretne wskazówki naprawy. +- **Dostawca auto**: najpierw sprawdza dostępność modelu lokalnego, a następnie próbuje każdego zdalnego + dostawcy w kolejności automatycznego wyboru. -Gdy wynik sondy gatewaya jest dostępny (gateway był zdrowy w momencie -sprawdzenia), doctor porównuje go z konfiguracją widoczną z CLI i odnotowuje +Gdy wynik sondy gateway jest dostępny (gateway był zdrowy w momencie +kontroli), doctor porównuje go z konfiguracją widoczną dla CLI i odnotowuje wszelkie rozbieżności. Użyj `openclaw memory status --deep`, aby zweryfikować gotowość embeddingów w runtime. @@ -464,51 +499,51 @@ Użyj `openclaw memory status --deep`, aby zweryfikować gotowość embeddingów ### 14) Ostrzeżenia o stanie kanałów Jeśli gateway jest zdrowy, doctor uruchamia sondę stanu kanałów i zgłasza -ostrzeżenia wraz z sugerowanymi poprawkami. +ostrzeżenia wraz z proponowanymi poprawkami. ### 15) Audyt konfiguracji supervisora + naprawa Doctor sprawdza zainstalowaną konfigurację supervisora (launchd/systemd/schtasks) pod kątem -brakujących lub nieaktualnych ustawień domyślnych (np. zależności systemd od network-online i -opóźnienia restartu). Gdy wykryje niezgodność, rekomenduje aktualizację i może -przepisać plik usługi/zadanie do bieżących ustawień domyślnych. +brakujących lub nieaktualnych wartości domyślnych (np. zależności systemd od network-online oraz +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 naprawy. -- `openclaw doctor --repair` stosuje zalecane poprawki bez pytań. +- `openclaw doctor --repair` stosuje zalecane poprawki bez monitów. - `openclaw doctor --repair --force` nadpisuje niestandardowe konfiguracje supervisora. -- Jeśli uwierzytelnianie tokenem wymaga tokena, a `gateway.auth.token` jest zarządzany przez SecretRef, doctor podczas instalacji/naprawy usługi waliduje SecretRef, ale nie zapisuje rozwiązanych jawnych wartości tokena do metadanych środowiska usługi supervisora. -- Jeśli uwierzytelnianie tokenem wymaga tokena, a skonfigurowany token SecretRef nie jest rozwiązany, doctor blokuje ścieżkę instalacji/naprawy z konkretnymi 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. -- W przypadku jednostek user-systemd w Linux, kontrole dryfu tokena w doctor obejmują teraz zarówno źródła `Environment=`, jak i `EnvironmentFile=` przy porównywaniu metadanych uwierzytelniania usługi. +- Jeśli uwierzytelnianie tokenem wymaga tokena, a `gateway.auth.token` jest zarządzany przez SecretRef, doctor przy instalacji/naprawie usługi waliduje SecretRef, ale nie zapisuje rozwiązanych wartości tokena w jawnym tekście w metadanych środowiska usługi supervisora. +- Jeśli uwierzytelnianie tokenem wymaga tokena, a skonfigurowany SecretRef tokena nie jest rozwiązany, doctor blokuje ścieżkę instalacji/naprawy i podaje konkretne wskazówki. +- Jeśli skonfigurowano zarówno `gateway.auth.token`, jak i `gateway.auth.password`, a `gateway.auth.mode` nie jest ustawione, doctor blokuje instalację/naprawę do czasu jawnego ustawienia trybu. +- W przypadku jednostek user-systemd w Linuxie kontrole dryfu tokena w doctor obejmują teraz zarówno źródła `Environment=`, jak i `EnvironmentFile=` przy porównywaniu metadanych uwierzytelniania usługi. - Zawsze możesz wymusić pełne przepisanie przez `openclaw gateway install --force`. -### 16) Diagnostyka środowiska uruchomieniowego gatewaya + portu +### 16) Diagnostyka runtime gateway i portu -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 portu -gatewaya (domyślnie `18789`) i raportuje prawdopodobne przyczyny (gateway już +Doctor sprawdza runtime usługi (PID, ostatni status wyjścia) i ostrzega, gdy +usługa jest zainstalowana, ale faktycznie nie działa. Sprawdza też konflikty portu +na porcie gateway (domyślnie `18789`) i raportuje prawdopodobne przyczyny (gateway już działa, tunel SSH). -### 17) Najlepsze praktyki środowiska uruchomieniowego gatewaya +### 17) Dobre praktyki runtime gateway -Doctor ostrzega, gdy usługa gatewaya działa na Bun lub na ścieżce Node zarządzanej przez menedżer wersji -(`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 +Doctor ostrzega, gdy usługa gateway działa na Bun lub na ścieżce Node zarządzanej przez menedżer wersji +(`nvm`, `fnm`, `volta`, `asdf` itd.). Kanały WhatsApp i Telegram wymagają Node, +a ścieżki menedżera wersji mogą przestać działać po aktualizacjach, ponieważ usługa nie ładuje inicjalizacji powłoki. Doctor oferuje migrację do systemowej instalacji Node, gdy jest dostępna (Homebrew/apt/choco). ### 18) Zapis konfiguracji + metadane kreatora -Doctor utrwala wszystkie zmiany konfiguracji i zapisuje metadane kreatora, aby odnotować +Doctor zapisuje wszelkie zmiany konfiguracji i oznacza metadane kreatora, aby zarejestrować uruchomienie doctor. -### 19) Wskazówki dotyczące workspace (kopia zapasowa + system pamięci) +### 19) Wskazówki dotyczące workspace (backup + system pamięci) -Doctor sugeruje system pamięci workspace, jeśli go brakuje, i wyświetla wskazówkę dotyczącą kopii zapasowej, -jeśli workspace nie jest już pod kontrolą gita. +Doctor sugeruje system pamięci workspace, jeśli go brakuje, i wypisuje wskazówkę dotyczącą backupu, +jeśli workspace nie jest już pod kontrolą git. Zobacz [/concepts/agent-workspace](/pl/concepts/agent-workspace), aby przeczytać pełny przewodnik po -strukturze workspace i kopiach zapasowych w git (zalecane prywatne GitHub lub GitLab). +strukturze workspace i backupie git (zalecany prywatny GitHub lub GitLab). diff --git a/docs/pl/help/testing.md b/docs/pl/help/testing.md index 0ae7fbdcd..e3a9e0cd9 100644 --- a/docs/pl/help/testing.md +++ b/docs/pl/help/testing.md @@ -1,259 +1,261 @@ --- read_when: - Uruchamianie testów lokalnie lub w CI - - Dodawanie regresji dla błędów modeli/dostawców + - Dodawanie regresji dla błędów modeli/providerów - Debugowanie zachowania gateway + agenta -summary: 'Pakiet testów: zestawy unit/e2e/live, uruchamianie w Dockerze i zakres każdego testu' +summary: 'Zestaw testowy: pakiety unit/e2e/live, uruchamianie w Dockerze i zakres poszczególnych testów' title: Testowanie x-i18n: - generated_at: "2026-04-08T02:17:20Z" + generated_at: "2026-04-09T01:31:02Z" model: gpt-5.4 provider: openai - source_hash: ace2c19bfc350780475f4348264a4b55be2b4ccbb26f0d33b4a6af34510943b5 + source_hash: 01117f41d8b171a4f1da11ed78486ee700e70ae70af54eb6060c57baf64ab21b source_path: help/testing.md workflow: 15 --- # Testowanie -OpenClaw ma trzy zestawy Vitest (unit/integration, e2e, live) oraz niewielki zestaw uruchomień w Dockerze. +OpenClaw ma trzy pakiety Vitest (unit/integration, e2e, live) oraz niewielki zestaw uruchomień w Dockerze. -Ten dokument to przewodnik „jak testujemy”: +Ten dokument jest przewodnikiem „jak testujemy”: -- Co obejmuje każdy zestaw (i czego celowo _nie_ obejmuje) -- Jakie polecenia uruchamiać w typowych przepływach pracy (lokalnie, przed pushem, debugowanie) -- Jak testy live wykrywają poświadczenia i wybierają modele/dostawców -- Jak dodawać regresje dla rzeczywistych problemów modeli/dostawców +- Co obejmuje każdy pakiet testów (i czego celowo _nie_ obejmuje) +- Jakie polecenia uruchamiać w typowych przepływach pracy (lokalnie, przed push, debugowanie) +- Jak testy live wykrywają poświadczenia oraz wybierają modele/providery +- Jak dodawać regresje dla rzeczywistych problemów modeli/providerów ## Szybki start -W większość dni: +Na co dzień: -- Pełna bramka (oczekiwana przed pushem): `pnpm build && pnpm check && pnpm test` -- Szybsze lokalne uruchomienie pełnego zestawu na wydajnej maszynie: `pnpm test:max` +- Pełna bramka (oczekiwana przed push): `pnpm build && pnpm check && pnpm test` +- Szybsze lokalne uruchomienie pełnego pakietu na wydajnej maszynie: `pnpm test:max` - Bezpośrednia pętla watch Vitest: `pnpm test:watch` -- Bezpośrednie kierowanie na plik teraz obsługuje też ścieżki extension/channel: `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` -- Strona QA wsparta Dockerem: `pnpm qa:lab:up` +- Bezpośrednie wskazywanie pliku obsługuje teraz również ścieżki rozszerzeń/kanałów: `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` +- Witryna QA oparta na Dockerze: `pnpm qa:lab:up` Gdy dotykasz testów lub chcesz mieć większą pewność: - Bramka pokrycia: `pnpm test:coverage` -- Zestaw E2E: `pnpm test:e2e` +- Pakiet E2E: `pnpm test:e2e` -Podczas debugowania rzeczywistych dostawców/modeli (wymaga prawdziwych poświadczeń): +Podczas debugowania rzeczywistych providerów/modeli (wymaga prawdziwych poświadczeń): -- Zestaw live (modele + sondy narzędzi/obrazów gateway): `pnpm test:live` +- Pakiet live (modele + sondy narzędzi/obrazów gateway): `pnpm test:live` - Ciche uruchomienie jednego pliku live: `pnpm test:live -- src/agents/models.profiles.live.test.ts` -Wskazówka: gdy potrzebujesz tylko jednego nieudanego przypadku, zawęź testy live za pomocą zmiennych środowiskowych allowlist opisanych poniżej. +Wskazówka: gdy potrzebujesz tylko jednego nieudanego przypadku, zawężaj testy live za pomocą zmiennych środowiskowych allowlist opisanych poniżej. -## Zestawy testów (co uruchamia się gdzie) +## Pakiety testów (co uruchamia się gdzie) -Potraktuj zestawy jako „rosnący realizm” (i rosnącą niestabilność/koszt): +Najlepiej myśleć o pakietach jako o „rosnącym realizmie” (i rosnącej niestabilności/koszcie): -### Unit / integration (domyślne) +### Unit / integration (domyślnie) - Polecenie: `pnpm test` -- Konfiguracja: dziesięć sekwencyjnych uruchomień shardów (`vitest.full-*.config.ts`) na istniejących zakresowych projektach Vitest -- Pliki: inwentarze core/unit w `src/**/*.test.ts`, `packages/**/*.test.ts`, `test/**/*.test.ts` oraz dozwolone testy node `ui` objęte przez `vitest.unit.config.ts` +- Konfiguracja: dziesięć sekwencyjnych uruchomień shardów (`vitest.full-*.config.ts`) na istniejących zakresowanych projektach Vitest +- Pliki: podstawowe inwentarze unit w `src/**/*.test.ts`, `packages/**/*.test.ts`, `test/**/*.test.ts` oraz dozwolone testy node w `ui` objęte przez `vitest.unit.config.ts` - Zakres: - - Czyste testy jednostkowe - - Testy integracyjne w procesie (auth gateway, routing, narzędzia, parsowanie, konfiguracja) - - Deterministyczne regresje znanych błędów + - Czyste testy unit + - Testy integracyjne in-process (auth gateway, routing, narzędzia, parsowanie, konfiguracja) + - Deterministyczne regresje dla znanych błędów - Oczekiwania: - - Uruchamiają się w CI + - Uruchamiane w CI - Nie wymagają prawdziwych kluczy - Powinny być szybkie i stabilne - Uwaga o projektach: - - Niekierowane `pnpm test` uruchamia teraz jedenaście mniejszych konfiguracji shardów (`core-unit-src`, `core-unit-security`, `core-unit-ui`, `core-unit-support`, `core-support-boundary`, `core-contracts`, `core-bundled`, `core-runtime`, `agentic`, `auto-reply`, `extensions`) zamiast jednego ogromnego natywnego procesu root-project. Zmniejsza to szczytowe RSS na obciążonych maszynach i zapobiega temu, by prace `auto-reply`/extension blokowały niezwiązane zestawy. - - `pnpm test --watch` nadal używa natywnego grafu projektów root `vitest.config.ts`, ponieważ wieloszardowa pętla watch nie jest praktyczna. - - `pnpm test`, `pnpm test:watch` i `pnpm test:perf:imports` kierują jawne cele plików/katalogów najpierw przez zakresowe ścieżki, więc `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` unika kosztu pełnego startu root project. - - `pnpm test:changed` rozwija zmienione ścieżki git do tych samych zakresowych ścieżek, gdy diff dotyczy tylko routowalnych plików źródłowych/testowych; edycje config/setup nadal wracają do szerokiego ponownego uruchomienia root-project. - - Wybrane testy `plugin-sdk` i `commands` także są kierowane przez dedykowane lekkie ścieżki, które pomijają `test/setup-openclaw-runtime.ts`; pliki stanowe/ciężkie runtime pozostają na istniejących ścieżkach. - - Wybrane pliki źródłowe helperów `plugin-sdk` i `commands` także mapują uruchomienia w trybie changed do jawnych testów sąsiednich w tych lekkich ścieżkach, więc edycje helperów unikają ponownego uruchamiania pełnego ciężkiego zestawu dla tego katalogu. - - `auto-reply` ma teraz trzy dedykowane koszyki: helpery najwyższego poziomu rdzenia, integracyjne testy najwyższego poziomu `reply.*` oraz poddrzewo `src/auto-reply/reply/**`. Dzięki temu najcięższa praca harnessu reply nie trafia do tanich testów status/chunk/token. -- Uwaga o osadzonym runnerze: - - Gdy zmieniasz wejścia wykrywania narzędzi wiadomości lub kontekst runtime kompaktowania, + - Niezawężone `pnpm test` uruchamia teraz jedenaście mniejszych konfiguracji shardów (`core-unit-src`, `core-unit-security`, `core-unit-ui`, `core-unit-support`, `core-support-boundary`, `core-contracts`, `core-bundled`, `core-runtime`, `agentic`, `auto-reply`, `extensions`) zamiast jednego ogromnego natywnego procesu root-project. To zmniejsza szczytowe RSS na obciążonych maszynach i zapobiega temu, by prace `auto-reply`/rozszerzeń zagłodziły niezwiązane pakiety. + - `pnpm test --watch` nadal używa natywnego grafu projektów root `vitest.config.ts`, ponieważ pętla watch z wieloma shardami nie jest praktyczna. + - `pnpm test`, `pnpm test:watch` i `pnpm test:perf:imports` najpierw kierują jawne cele plików/katalogów do zakresowanych ścieżek, więc `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` unika kosztu uruchamiania pełnego projektu root. + - `pnpm test:changed` rozwija zmienione ścieżki git do tych samych zakresowanych ścieżek, gdy diff dotyka tylko routowalnych plików źródłowych/testowych; edycje konfiguracji/ustawień nadal wracają do szerokiego ponownego uruchomienia root-project. + - Wybrane testy `plugin-sdk` i `commands` są również kierowane przez dedykowane lekkie ścieżki, które pomijają `test/setup-openclaw-runtime.ts`; pliki stanowe / ciężkie runtime pozostają na istniejących ścieżkach. + - Wybrane pliki pomocnicze źródeł `plugin-sdk` i `commands` również mapują uruchomienia trybu changed na jawne testy sąsiednie w tych lekkich ścieżkach, tak aby edycje helperów nie powodowały ponownego uruchamiania całego ciężkiego pakietu dla tego katalogu. + - `auto-reply` ma teraz trzy dedykowane koszyki: helpery główne top-level, testy integracyjne top-level `reply.*` oraz poddrzewo `src/auto-reply/reply/**`. Dzięki temu najcięższa praca harnessu reply nie trafia do tanich testów status/chunk/token. +- Uwaga o embedded runner: + - Gdy zmieniasz wejścia wykrywania message-tool lub kontekst runtime compaction, zachowaj oba poziomy pokrycia. - - Dodaj ukierunkowane regresje helperów dla czystych granic routingu/normalizacji. - - Utrzymuj też w zdrowiu osadzone zestawy integracyjne: + - Dodawaj ukierunkowane regresje helperów dla czystych granic routingu/normalizacji. + - Utrzymuj też w dobrej kondycji pakiety integracyjne embedded runner: `src/agents/pi-embedded-runner/compact.hooks.test.ts`, `src/agents/pi-embedded-runner/run.overflow-compaction.test.ts` oraz `src/agents/pi-embedded-runner/run.overflow-compaction.loop.test.ts`. - - Te zestawy weryfikują, że zakresowe identyfikatory i zachowanie kompaktowania nadal przepływają - przez rzeczywiste ścieżki `run.ts` / `compact.ts`; testy tylko helperów nie są + - Te pakiety sprawdzają, że zakresowane identyfikatory i zachowanie compaction nadal przepływają + przez rzeczywiste ścieżki `run.ts` / `compact.ts`; testy samych helperów nie są wystarczającym zamiennikiem dla tych ścieżek integracyjnych. - Uwaga o puli: - Bazowa konfiguracja Vitest domyślnie używa teraz `threads`. - - Współdzielona konfiguracja Vitest ustawia też `isolate: false` i używa nieizolowanego runnera w root projects, konfiguracjach e2e i live. - - Ścieżka root UI zachowuje konfigurację i optymalizator `jsdom`, ale teraz działa również na współdzielonym nieizolowanym runnerze. - - Każdy shard `pnpm test` dziedziczy te same ustawienia `threads` + `isolate: false` ze współdzielonej konfiguracji Vitest. - - Współdzielony launcher `scripts/run-vitest.mjs` domyślnie dodaje teraz także `--no-maglev` dla podrzędnych procesów Node Vitest, aby zmniejszyć churn kompilacji V8 podczas dużych lokalnych uruchomień. Ustaw `OPENCLAW_VITEST_ENABLE_MAGLEV=1`, jeśli chcesz porównać zachowanie ze standardowym V8. -- Uwaga o szybkiej lokalnej iteracji: - - `pnpm test:changed` kieruje przez zakresowe ścieżki, gdy zmienione ścieżki dają się czysto zmapować na mniejszy zestaw. - - `pnpm test:max` i `pnpm test:changed:max` zachowują to samo kierowanie, tylko z wyższym limitem workerów. - - Lokalne automatyczne skalowanie workerów jest teraz celowo konserwatywne i także wycofuje się, gdy średnie obciążenie hosta jest już wysokie, więc wiele równoległych uruchomień Vitest domyślnie powoduje mniej szkód. - - Bazowa konfiguracja Vitest oznacza pliki projektów/konfiguracji jako `forceRerunTriggers`, aby ponowne uruchomienia w trybie changed były poprawne, gdy zmienia się okablowanie testów. - - Konfiguracja utrzymuje `OPENCLAW_VITEST_FS_MODULE_CACHE` w stanie włączonym na obsługiwanych hostach; ustaw `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/abs/path`, jeśli chcesz jedną jawną lokalizację cache do bezpośredniego profilowania. + - Współdzielona konfiguracja Vitest ustawia też `isolate: false` i używa nieizolowanego runnera w projektach root, konfiguracjach e2e i live. + - Główna ścieżka UI zachowuje ustawienia `jsdom` i optymalizator, ale teraz również działa na współdzielonym nieizolowanym runnerze. + - Każdy shard `pnpm test` dziedziczy te same domyślne ustawienia `threads` + `isolate: false` ze współdzielonej konfiguracji Vitest. + - Współdzielony launcher `scripts/run-vitest.mjs` domyślnie dodaje teraz także `--no-maglev` dla podrzędnych procesów Node Vitest, aby ograniczyć churn kompilacji V8 podczas dużych lokalnych uruchomień. Ustaw `OPENCLAW_VITEST_ENABLE_MAGLEV=1`, jeśli chcesz porównać zachowanie ze standardowym V8. +- Uwaga o szybkiej iteracji lokalnej: + - `pnpm test:changed` kieruje przez zakresowane ścieżki, gdy zmienione ścieżki da się jednoznacznie przypisać do mniejszego pakietu. + - `pnpm test:max` i `pnpm test:changed:max` zachowują to samo routowanie, tylko z wyższym limitem workerów. + - Lokalna automatyczna skala workerów jest teraz celowo konserwatywna i również wycofuje się, gdy średnie obciążenie hosta jest już wysokie, więc wiele równoległych uruchomień Vitest domyślnie powoduje mniej szkód. + - Bazowa konfiguracja Vitest oznacza projekty/pliki konfiguracyjne jako `forceRerunTriggers`, aby ponowne uruchomienia w trybie changed pozostawały poprawne po zmianach w okablowaniu testów. + - Konfiguracja utrzymuje włączone `OPENCLAW_VITEST_FS_MODULE_CACHE` na obsługiwanych hostach; ustaw `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/abs/path`, jeśli chcesz mieć jedną jawną lokalizację cache do bezpośredniego profilowania. - Uwaga o debugowaniu wydajności: - - `pnpm test:perf:imports` włącza raportowanie czasu importów Vitest oraz wyjście rozbicia importów. - - `pnpm test:perf:imports:changed` zawęża ten sam widok profilowania do plików zmienionych względem `origin/main`. -- `pnpm test:perf:changed:bench -- --ref ` porównuje routowane `test:changed` z natywną ścieżką root-project dla tego zatwierdzonego diffu i wypisuje wall time oraz maksymalne RSS na macOS. -- `pnpm test:perf:changed:bench -- --worktree` benchmarkuje bieżące brudne drzewo, kierując listę zmienionych plików przez `scripts/test-projects.mjs` i konfigurację root Vitest. - - `pnpm test:perf:profile:main` zapisuje profil CPU głównego wątku dla narzutu startu i transformacji Vitest/Vite. - - `pnpm test:perf:profile:runner` zapisuje profile CPU+heap runnera dla zestawu unit przy wyłączonej równoległości plików. + - `pnpm test:perf:imports` włącza raportowanie czasu importu Vitest oraz wyjście z rozbiciem importów. + - `pnpm test:perf:imports:changed` zawęża ten sam widok profilowania do plików zmienionych od `origin/main`. +- `pnpm test:perf:changed:bench -- --ref ` porównuje kierowane `test:changed` z natywną ścieżką root-project dla tego zatwierdzonego diffu i wypisuje wall time oraz macOS max RSS. +- `pnpm test:perf:changed:bench -- --worktree` benchmarkuje bieżące brudne drzewo, kierując listę zmienionych plików przez `scripts/test-projects.mjs` i główną konfigurację Vitest. + - `pnpm test:perf:profile:main` zapisuje profil CPU głównego wątku dla kosztów uruchamiania i transformacji Vitest/Vite. + - `pnpm test:perf:profile:runner` zapisuje profile CPU+heap runnera dla pakietu unit z wyłączoną równoległością plików. -### E2E (smoke gateway) +### E2E (gateway smoke) - Polecenie: `pnpm test:e2e` - Konfiguracja: `vitest.e2e.config.ts` - Pliki: `src/**/*.e2e.test.ts`, `test/**/*.e2e.test.ts` - Domyślne ustawienia runtime: - - Używa `threads` Vitest z `isolate: false`, zgodnie z resztą repozytorium. - - Używa adaptacyjnych workerów (CI: do 2, lokalnie: domyślnie 1). - - Domyślnie działa w trybie silent, aby zmniejszyć narzut I/O konsoli. + - Używa Vitest `threads` z `isolate: false`, zgodnie z resztą repozytorium. + - Używa workerów adaptacyjnych (CI: do 2, lokalnie: domyślnie 1). + - Domyślnie działa w trybie cichym, aby zmniejszyć narzut I/O konsoli. - Przydatne nadpisania: - `OPENCLAW_E2E_WORKERS=` aby wymusić liczbę workerów (maksymalnie 16). - `OPENCLAW_E2E_VERBOSE=1` aby ponownie włączyć szczegółowe wyjście konsoli. - Zakres: - - Zachowanie end-to-end wielu instancji gateway - - Powierzchnie WebSocket/HTTP, parowanie węzłów i cięższa komunikacja sieciowa + - Wieloinstancyjne zachowanie gateway end-to-end + - Powierzchnie WebSocket/HTTP, parowanie węzłów i cięższy networking - Oczekiwania: - - Uruchamia się w CI (gdy włączone w pipeline) - - Nie wymaga prawdziwych kluczy - - Ma więcej ruchomych części niż testy jednostkowe (może być wolniejszy) + - Uruchamiane w CI (gdy są włączone w pipeline) + - Nie wymagają prawdziwych kluczy + - Mają więcej ruchomych części niż testy unit (mogą być wolniejsze) ### E2E: smoke backendu OpenShell - Polecenie: `pnpm test:e2e:openshell` - Plik: `test/openshell-sandbox.e2e.test.ts` - Zakres: - - Uruchamia odizolowany gateway OpenShell na hoście przez Docker + - Uruchamia izolowany gateway OpenShell na hoście za pomocą Dockera - Tworzy sandbox z tymczasowego lokalnego Dockerfile - - Testuje backend OpenShell OpenClaw przez prawdziwe `sandbox ssh-config` + SSH exec - - Weryfikuje zdalnie kanoniczne zachowanie systemu plików przez most fs sandboxa + - Testuje backend OpenShell w OpenClaw przez rzeczywiste `sandbox ssh-config` + wykonanie SSH + - Weryfikuje zdalne kanoniczne zachowanie systemu plików przez most fs sandboxa - Oczekiwania: - Tylko opt-in; nie jest częścią domyślnego uruchomienia `pnpm test:e2e` - - Wymaga lokalnego CLI `openshell` oraz działającego demona Docker - - Używa odizolowanych `HOME` / `XDG_CONFIG_HOME`, a następnie niszczy testowy gateway i sandbox + - Wymaga lokalnego CLI `openshell` oraz działającego demona Dockera + - Używa izolowanych `HOME` / `XDG_CONFIG_HOME`, a następnie niszczy testowy gateway i sandbox - Przydatne nadpisania: - - `OPENCLAW_E2E_OPENSHELL=1` aby włączyć test podczas ręcznego uruchamiania szerszego zestawu e2e - - `OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell` aby wskazać niestandardowy binarny plik CLI lub skrypt opakowujący + - `OPENCLAW_E2E_OPENSHELL=1` aby włączyć test podczas ręcznego uruchamiania szerszego pakietu e2e + - `OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell` aby wskazać niestandardowy binarny plik CLI lub skrypt wrapper -### Live (prawdziwi dostawcy + prawdziwe modele) +### Live (prawdziwi providerzy + prawdziwe modele) - Polecenie: `pnpm test:live` - Konfiguracja: `vitest.live.config.ts` - Pliki: `src/**/*.live.test.ts` - Domyślnie: **włączone** przez `pnpm test:live` (ustawia `OPENCLAW_LIVE_TEST=1`) - Zakres: - - „Czy ten dostawca/model naprawdę działa _dzisiaj_ z prawdziwymi poświadczeniami?” - - Wykrywanie zmian formatów dostawców, osobliwości wywołań narzędzi, problemów auth i zachowania limitów szybkości + - „Czy ten provider/model rzeczywiście działa _dzisiaj_ z prawdziwymi poświadczeniami?” + - Wychwytywanie zmian formatów providerów, specyfiki wywoływania narzędzi, problemów z auth i zachowania limitów szybkości - Oczekiwania: - - Z założenia niestabilne w CI (prawdziwe sieci, prawdziwe zasady dostawców, limity, awarie) - - Kosztują pieniądze / zużywają limity szybkości + - Z założenia niestabilne w CI (prawdziwe sieci, rzeczywiste polityki providerów, limity, awarie) + - Kosztują pieniądze / zużywają limity - Lepiej uruchamiać zawężone podzbiory niż „wszystko” -- Uruchomienia live wczytują `~/.profile`, aby pobrać brakujące klucze API. -- Domyślnie uruchomienia live nadal izolują `HOME` i kopiują materiał config/auth do tymczasowego katalogu domowego testu, tak aby fixture unit nie mogły modyfikować twojego prawdziwego `~/.openclaw`. -- Ustaw `OPENCLAW_LIVE_USE_REAL_HOME=1` tylko wtedy, gdy świadomie chcesz, aby testy live używały twojego prawdziwego katalogu domowego. -- `pnpm test:live` domyślnie działa teraz ciszej: zachowuje wyjście postępu `[live] ...`, ale wycisza dodatkową informację o `~/.profile` i wyłącza logi bootstrapu gateway / szum Bonjour. Ustaw `OPENCLAW_LIVE_TEST_QUIET=0`, jeśli chcesz przywrócić pełne logi startowe. -- Rotacja kluczy API (specyficzna dla dostawcy): ustaw `*_API_KEYS` w formacie z przecinkami/średnikami albo `*_API_KEY_1`, `*_API_KEY_2` (na przykład `OPENAI_API_KEYS`, `ANTHROPIC_API_KEYS`, `GEMINI_API_KEYS`) albo per-live override przez `OPENCLAW_LIVE_*_KEY`; testy ponawiają próby po odpowiedziach z limitem szybkości. -- Wyjście postępu/heartbeatów: - - Zestawy live wypisują teraz linie postępu do stderr, aby długie wywołania dostawców były widocznie aktywne nawet wtedy, gdy przechwytywanie konsoli Vitest jest ciche. - - `vitest.live.config.ts` wyłącza przechwytywanie konsoli Vitest, więc linie postępu dostawcy/gateway są strumieniowane natychmiast podczas uruchomień live. - - Dostosuj heartbeaty bezpośredniego modelu przez `OPENCLAW_LIVE_HEARTBEAT_MS`. - - Dostosuj heartbeaty gateway/probe przez `OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS`. +- Uruchomienia live pobierają `~/.profile`, aby uzupełnić brakujące klucze API. +- Domyślnie uruchomienia live nadal izolują `HOME` i kopiują materiały konfiguracyjne/auth do tymczasowego katalogu domowego testów, aby fixtury unit nie mogły modyfikować twojego prawdziwego `~/.openclaw`. +- Ustaw `OPENCLAW_LIVE_USE_REAL_HOME=1` tylko wtedy, gdy celowo chcesz, aby testy live używały twojego prawdziwego katalogu domowego. +- `pnpm test:live` działa teraz domyślnie w cichszym trybie: zachowuje wyjście postępu `[live] ...`, ale ukrywa dodatkowy komunikat o `~/.profile` i wycisza logi bootstrap gateway / hałas Bonjour. Ustaw `OPENCLAW_LIVE_TEST_QUIET=0`, jeśli chcesz przywrócić pełne logi uruchomieniowe. +- Rotacja kluczy API (specyficzna dla providera): ustaw `*_API_KEYS` w formacie oddzielanym przecinkami/średnikami lub `*_API_KEY_1`, `*_API_KEY_2` (na przykład `OPENAI_API_KEYS`, `ANTHROPIC_API_KEYS`, `GEMINI_API_KEYS`) albo nadpisanie per-live przez `OPENCLAW_LIVE_*_KEY`; testy ponawiają próby po odpowiedziach rate limit. +- Wyjście postępu/heartbeat: + - Pakiety live emitują teraz linie postępu na stderr, więc długie wywołania providerów są widocznie aktywne nawet wtedy, gdy przechwytywanie konsoli Vitest jest ciche. + - `vitest.live.config.ts` wyłącza przechwytywanie konsoli Vitest, aby linie postępu provider/gateway były natychmiast streamowane podczas uruchomień live. + - Czas heartbeat dla bezpośrednich modeli regulujesz przez `OPENCLAW_LIVE_HEARTBEAT_MS`. + - Czas heartbeat dla gateway/probe regulujesz przez `OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS`. -## Który zestaw powinienem uruchomić? +## Który pakiet powinienem uruchomić? -Użyj tej tabeli decyzyjnej: +Skorzystaj z tej tabeli decyzyjnej: -- Edycja logiki/testów: uruchom `pnpm test` (oraz `pnpm test:coverage`, jeśli zmieniło się dużo) -- Dotykanie komunikacji gateway / protokołu WS / parowania: dodaj `pnpm test:e2e` -- Debugowanie „mój bot nie działa” / awarii specyficznych dla dostawcy / wywoływania narzędzi: uruchom zawężone `pnpm test:live` +- Edycja logiki/testów: uruchom `pnpm test` (oraz `pnpm test:coverage`, jeśli zmieniłeś dużo) +- Zmiany w sieci gateway / protokole WS / parowaniu: dodaj `pnpm test:e2e` +- Debugowanie „mój bot nie działa” / błędów specyficznych dla providera / wywoływania narzędzi: uruchom zawężone `pnpm test:live` -## Live: przegląd możliwości węzła Androida +## Live: przegląd możliwości węzła Android - Test: `src/gateway/android-node.capabilities.live.test.ts` - Skrypt: `pnpm android:test:integration` -- Cel: wywołać **każde aktualnie reklamowane polecenie** podłączonego węzła Androida i potwierdzić zachowanie kontraktu poleceń. +- Cel: wywołać **każde polecenie aktualnie ogłaszane** przez podłączony węzeł Android i potwierdzić zachowanie kontraktu poleceń. - Zakres: - - Konfiguracja wstępna/ręczna (zestaw nie instaluje, nie uruchamia ani nie paruje aplikacji). - - Walidacja `node.invoke` gateway polecenie po poleceniu dla wybranego węzła Androida. -- Wymagana wstępna konfiguracja: - - Aplikacja Android jest już połączona i sparowana z gateway. - - Aplikacja pozostaje na pierwszym planie. - - Uprawnienia/zgoda na przechwytywanie są przyznane dla możliwości, które mają przejść. + - Ustawienia wstępne/ręczne (pakiet nie instaluje, nie uruchamia ani nie paruje aplikacji). + - Walidacja `node.invoke` gateway polecenie po poleceniu dla wybranego węzła Android. +- Wymagane przygotowanie: + - Aplikacja Android już połączona i sparowana z gateway. + - Aplikacja utrzymywana na pierwszym planie. + - Uprawnienia/zgody na przechwytywanie przyznane dla możliwości, które mają przejść. - Opcjonalne nadpisania celu: - `OPENCLAW_ANDROID_NODE_ID` lub `OPENCLAW_ANDROID_NODE_NAME`. - `OPENCLAW_ANDROID_GATEWAY_URL` / `OPENCLAW_ANDROID_GATEWAY_TOKEN` / `OPENCLAW_ANDROID_GATEWAY_PASSWORD`. -- Pełne szczegóły konfiguracji Androida: [Aplikacja Android](/pl/platforms/android) +- Pełne szczegóły konfiguracji Android: [Android App](/pl/platforms/android) -## Live: smoke modeli (klucze profilu) +## Live: smoke modeli (klucze profili) -Testy live są podzielone na dwie warstwy, aby można było izolować awarie: +Testy live są podzielone na dwie warstwy, aby łatwiej izolować awarie: -- „Model bezpośredni” mówi nam, czy dostawca/model w ogóle potrafi odpowiedzieć z danym kluczem. -- „Smoke gateway” mówi nam, czy pełny pipeline gateway+agent działa dla tego modelu (sesje, historia, narzędzia, polityka sandboxa itd.). +- „Direct model” mówi nam, czy provider/model w ogóle potrafi odpowiedzieć przy danym kluczu. +- „Gateway smoke” mówi nam, czy działa pełny pipeline gateway+agent dla tego modelu (sesje, historia, narzędzia, polityka sandboxa itp.). -### Warstwa 1: bezpośrednie completion modelu (bez gateway) +### Warstwa 1: Bezpośrednie completion modelu (bez gateway) - Test: `src/agents/models.profiles.live.test.ts` - Cel: - Wyliczyć wykryte modele - - Użyć `getApiKeyForModel` do wyboru modeli, do których masz poświadczenia + - Użyć `getApiKeyForModel` do wybrania modeli, do których masz poświadczenia - Wykonać małe completion dla każdego modelu (oraz ukierunkowane regresje tam, gdzie potrzeba) - Jak włączyć: - `pnpm test:live` (lub `OPENCLAW_LIVE_TEST=1`, jeśli wywołujesz Vitest bezpośrednio) -- Ustaw `OPENCLAW_LIVE_MODELS=modern` (lub `all`, alias dla modern), aby faktycznie uruchomić ten zestaw; w przeciwnym razie jest pomijany, aby `pnpm test:live` pozostawało skupione na smoke gateway +- Ustaw `OPENCLAW_LIVE_MODELS=modern` (lub `all`, alias dla modern), aby faktycznie uruchomić ten pakiet; w przeciwnym razie zostanie pominięty, aby `pnpm test:live` pozostawało skupione na gateway smoke - Jak wybierać modele: - - `OPENCLAW_LIVE_MODELS=modern`, aby uruchomić nowoczesną allowlist (Opus/Sonnet 4.6+, GPT-5.x + Codex, Gemini 3, GLM 4.7, MiniMax M2.7, Grok 4) - - `OPENCLAW_LIVE_MODELS=all` jest aliasem dla nowoczesnej allowlist - - albo `OPENCLAW_LIVE_MODELS="openai/gpt-5.4,anthropic/claude-opus-4-6,..."` (allowlist rozdzielana przecinkami) -- Jak wybierać dostawców: - - `OPENCLAW_LIVE_PROVIDERS="google,google-antigravity,google-gemini-cli"` (allowlist rozdzielana przecinkami) + - `OPENCLAW_LIVE_MODELS=modern` aby uruchomić nowoczesną allowlist (Opus/Sonnet 4.6+, GPT-5.x + Codex, Gemini 3, GLM 4.7, MiniMax M2.7, Grok 4) + - `OPENCLAW_LIVE_MODELS=all` jest aliasem dla nowoczesnej allowlisty + - albo `OPENCLAW_LIVE_MODELS="openai/gpt-5.4,anthropic/claude-opus-4-6,..."` (allowlista rozdzielana przecinkami) + - Przeglądy modern/all domyślnie używają dobranego limitu o wysokim sygnale; ustaw `OPENCLAW_LIVE_MAX_MODELS=0` dla wyczerpującego przeglądu modern lub liczbę dodatnią dla mniejszego limitu. +- Jak wybierać providery: + - `OPENCLAW_LIVE_PROVIDERS="google,google-antigravity,google-gemini-cli"` (allowlista rozdzielana przecinkami) - Skąd pochodzą klucze: - - Domyślnie: magazyn profili i zapasowe zmienne środowiskowe - - Ustaw `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, aby wymusić użycie **wyłącznie magazynu profili** + - Domyślnie: ze store profili i fallbacków env + - Ustaw `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, aby wymusić wyłącznie **store profili** - Dlaczego to istnieje: - - Oddziela „API dostawcy jest uszkodzone / klucz jest nieprawidłowy” od „pipeline agenta gateway jest uszkodzony” + - Oddziela „API providera jest zepsute / klucz jest nieprawidłowy” od „pipeline agenta gateway jest zepsuty” - Zawiera małe, izolowane regresje (przykład: OpenAI Responses/Codex Responses reasoning replay + przepływy tool-call) -### Warstwa 2: smoke gateway + dev agent (to, co faktycznie robi „@openclaw”) +### Warstwa 2: Gateway + smoke agenta deweloperskiego (to, co naprawdę robi "@openclaw") - Test: `src/gateway/gateway-models.profiles.live.test.ts` - Cel: - - Uruchomić gateway w procesie - - Utworzyć/poprawić sesję `agent:dev:*` (nadpisanie modelu na każde uruchomienie) + - Uruchomić in-process gateway + - Utworzyć/załatać sesję `agent:dev:*` (nadpisanie modelu dla każdego uruchomienia) - Iterować po modelach-z-kluczami i potwierdzać: - „sensowną” odpowiedź (bez narzędzi) - - że działa prawdziwe wywołanie narzędzia (sonda read) - - opcjonalne dodatkowe sondy narzędzi (sonda exec+read) - - że ścieżki regresji OpenAI (tylko tool-call → follow-up) nadal działają -- Szczegóły sond (aby dało się szybko wyjaśnić awarie): - - sonda `read`: test zapisuje plik nonce w workspace i prosi agenta, aby go `read` i odesłał nonce. + - że działa prawdziwe wywołanie narzędzia (`read` probe) + - opcjonalne dodatkowe sondy narzędzi (`exec+read` probe) + - że ścieżki regresji OpenAI (samo tool-call → follow-up) nadal działają +- Szczegóły sond (aby szybciej wyjaśniać awarie): + - sonda `read`: test zapisuje plik nonce w workspace i prosi agenta, aby go `read` oraz odesłał nonce. - sonda `exec+read`: test prosi agenta, aby zapisał nonce do pliku tymczasowego przez `exec`, a następnie odczytał go przez `read`. - sonda obrazu: test dołącza wygenerowany PNG (kot + losowy kod) i oczekuje, że model zwróci `cat `. - - Odniesienie implementacyjne: `src/gateway/gateway-models.profiles.live.test.ts` oraz `src/gateway/live-image-probe.ts`. + - Referencja implementacji: `src/gateway/gateway-models.profiles.live.test.ts` oraz `src/gateway/live-image-probe.ts`. - Jak włączyć: - `pnpm test:live` (lub `OPENCLAW_LIVE_TEST=1`, jeśli wywołujesz Vitest bezpośrednio) - Jak wybierać modele: - - Domyślnie: nowoczesna allowlist (Opus/Sonnet 4.6+, GPT-5.x + Codex, Gemini 3, GLM 4.7, MiniMax M2.7, Grok 4) - - `OPENCLAW_LIVE_GATEWAY_MODELS=all` jest aliasem dla nowoczesnej allowlist + - Domyślnie: nowoczesna allowlista (Opus/Sonnet 4.6+, GPT-5.x + Codex, Gemini 3, GLM 4.7, MiniMax M2.7, Grok 4) + - `OPENCLAW_LIVE_GATEWAY_MODELS=all` jest aliasem dla nowoczesnej allowlisty - Albo ustaw `OPENCLAW_LIVE_GATEWAY_MODELS="provider/model"` (lub listę rozdzielaną przecinkami), aby zawęzić -- Jak wybierać dostawców (unikaj „wszystko z OpenRouter”): - - `OPENCLAW_LIVE_GATEWAY_PROVIDERS="google,google-antigravity,google-gemini-cli,openai,anthropic,zai,minimax"` (allowlist rozdzielana przecinkami) -- Sondy narzędzi + obrazów są zawsze włączone w tym teście live: - - sonda `read` + sonda `exec+read` (obciążenie narzędzi) - - sonda obrazu uruchamia się, gdy model reklamuje obsługę wejścia obrazowego - - Przepływ (na wysokim poziomie): + - Przeglądy gateway modern/all domyślnie używają dobranego limitu o wysokim sygnale; ustaw `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=0` dla wyczerpującego przeglądu modern lub liczbę dodatnią dla mniejszego limitu. +- Jak wybierać providery (aby uniknąć „wszystkiego z OpenRouter”): + - `OPENCLAW_LIVE_GATEWAY_PROVIDERS="google,google-antigravity,google-gemini-cli,openai,anthropic,zai,minimax"` (allowlista rozdzielana przecinkami) +- Sondy narzędzi + obrazu są zawsze włączone w tym teście live: + - sonda `read` + sonda `exec+read` (stress test narzędzi) + - sonda obrazu działa, gdy model ogłasza obsługę wejścia obrazowego + - Przepływ (wysoki poziom): - Test generuje mały PNG z „CAT” + losowym kodem (`src/gateway/live-image-probe.ts`) - Wysyła go przez `agent` `attachments: [{ mimeType: "image/png", content: "" }]` - Gateway parsuje załączniki do `images[]` (`src/gateway/server-methods/agent.ts` + `src/gateway/chat-attachments.ts`) - - Osadzony agent przekazuje multimodalną wiadomość użytkownika do modelu - - Potwierdzenie: odpowiedź zawiera `cat` + kod (tolerancja OCR: drobne błędy są dopuszczalne) + - Embedded agent przekazuje do modelu multimodalną wiadomość użytkownika + - Asercja: odpowiedź zawiera `cat` + kod (tolerancja OCR: dopuszczalne drobne pomyłki) -Wskazówka: aby zobaczyć, co możesz testować na swojej maszynie (i dokładne identyfikatory `provider/model`), uruchom: +Wskazówka: aby zobaczyć, co możesz testować na swojej maszynie (oraz dokładne identyfikatory `provider/model`), uruchom: ```bash openclaw models list @@ -263,23 +265,23 @@ openclaw models list --json ## Live: smoke backendu CLI (Claude, Codex, Gemini lub inne lokalne CLI) - Test: `src/gateway/gateway-cli-backend.live.test.ts` -- Cel: zweryfikować pipeline Gateway + agent z użyciem lokalnego backendu CLI, bez dotykania domyślnej konfiguracji. -- Domyślne ustawienia smoke specyficzne dla backendu znajdują się przy definicji `cli-backend.ts` należącej do danej extension. +- Cel: zweryfikować pipeline Gateway + agent przy użyciu lokalnego backendu CLI, bez dotykania domyślnej konfiguracji. +- Domyślne ustawienia smoke specyficzne dla backendu znajdują się w definicji `cli-backend.ts` należącej do odpowiedniego rozszerzenia. - Włączenie: - `pnpm test:live` (lub `OPENCLAW_LIVE_TEST=1`, jeśli wywołujesz Vitest bezpośrednio) - `OPENCLAW_LIVE_CLI_BACKEND=1` -- Domyślne wartości: - - Domyślny dostawca/model: `claude-cli/claude-sonnet-4-6` - - Zachowanie polecenia/argumentów/obrazu pochodzi z metadanych wtyczki backendu CLI. +- Domyślne ustawienia: + - Domyślny provider/model: `claude-cli/claude-sonnet-4-6` + - Zachowanie polecenia/argumentów/obrazów pochodzi z metadanych odpowiedniego pluginu backendu CLI. - Nadpisania (opcjonalne): - `OPENCLAW_LIVE_CLI_BACKEND_MODEL="codex-cli/gpt-5.4"` - `OPENCLAW_LIVE_CLI_BACKEND_COMMAND="/full/path/to/codex"` - `OPENCLAW_LIVE_CLI_BACKEND_ARGS='["exec","--json","--color","never","--sandbox","read-only","--skip-git-repo-check"]'` - - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_PROBE=1`, aby wysłać prawdziwy załącznik obrazu (ścieżki są wstrzykiwane do promptu). - - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_ARG="--image"`, aby przekazywać ścieżki plików obrazu jako argumenty CLI zamiast przez wstrzykiwanie do promptu. - - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_MODE="repeat"` (lub `"list"`), aby kontrolować sposób przekazywania argumentów obrazu, gdy ustawiono `IMAGE_ARG`. - - `OPENCLAW_LIVE_CLI_BACKEND_RESUME_PROBE=1`, aby wysłać drugą turę i zweryfikować przepływ wznowienia. - - `OPENCLAW_LIVE_CLI_BACKEND_MODEL_SWITCH_PROBE=0`, aby wyłączyć domyślną sondę ciągłości tej samej sesji Claude Sonnet -> Opus (ustaw `1`, aby wymusić ją, gdy wybrany model obsługuje cel przełączenia). + - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_PROBE=1` aby wysłać prawdziwy załącznik obrazu (ścieżki są wstrzykiwane do promptu). + - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_ARG="--image"` aby przekazywać ścieżki plików obrazów jako argumenty CLI zamiast przez wstrzyknięcie do promptu. + - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_MODE="repeat"` (lub `"list"`) aby kontrolować sposób przekazywania argumentów obrazów, gdy ustawione jest `IMAGE_ARG`. + - `OPENCLAW_LIVE_CLI_BACKEND_RESUME_PROBE=1` aby wysłać drugą turę i zweryfikować przepływ wznowienia. + - `OPENCLAW_LIVE_CLI_BACKEND_MODEL_SWITCH_PROBE=0` aby wyłączyć domyślną sondę ciągłości tej samej sesji Claude Sonnet -> Opus (ustaw `1`, aby wymusić ją, gdy wybrany model obsługuje cel przełączenia). Przykład: @@ -289,13 +291,13 @@ OPENCLAW_LIVE_CLI_BACKEND=1 \ pnpm test:live src/gateway/gateway-cli-backend.live.test.ts ``` -Przepis Docker: +Recepta Docker: ```bash pnpm test:docker:live-cli-backend ``` -Przepisy Docker dla pojedynczego dostawcy: +Recepty Docker dla pojedynczego providera: ```bash pnpm test:docker:live-cli-backend:claude @@ -305,27 +307,27 @@ pnpm test:docker:live-cli-backend:gemini Uwagi: -- Runner Docker znajduje się w `scripts/test-live-cli-backend-docker.sh`. -- Uruchamia smoke live backendu CLI wewnątrz obrazu Docker repozytorium jako nieuprzywilejowany użytkownik `node`. -- Rozwiązuje metadane smoke CLI z należącej do niego extension, a następnie instaluje odpowiadający pakiet Linux CLI (`@anthropic-ai/claude-code`, `@openai/codex` lub `@google/gemini-cli`) do zapisywalnego prefiksu cache w `OPENCLAW_DOCKER_CLI_TOOLS_DIR` (domyślnie: `~/.cache/openclaw/docker-cli-tools`). -- Smoke live backendu CLI testuje teraz ten sam pełny przepływ end-to-end dla Claude, Codex i Gemini: tura tekstowa, tura klasyfikacji obrazu, a następnie wywołanie narzędzia MCP `cron` zweryfikowane przez gateway CLI. -- Domyślny smoke Claude dodatkowo poprawia sesję z Sonnet do Opus i weryfikuje, że wznowiona sesja nadal pamięta wcześniejszą notatkę. +- Runner Dockera znajduje się w `scripts/test-live-cli-backend-docker.sh`. +- Uruchamia smoke live backendu CLI wewnątrz obrazu Docker repo jako nieuprzywilejowany użytkownik `node`. +- Rozwiązuje metadane smoke CLI z odpowiedniego rozszerzenia, a następnie instaluje odpowiedni pakiet Linux CLI (`@anthropic-ai/claude-code`, `@openai/codex` lub `@google/gemini-cli`) do zapisywalnego prefiksu cache w `OPENCLAW_DOCKER_CLI_TOOLS_DIR` (domyślnie: `~/.cache/openclaw/docker-cli-tools`). +- Smoke live backendu CLI testuje teraz ten sam przepływ end-to-end dla Claude, Codex i Gemini: tura tekstowa, tura klasyfikacji obrazu, a następnie wywołanie narzędzia MCP `cron` zweryfikowane przez CLI gateway. +- Domyślny smoke Claude dodatkowo łata sesję z Sonnet do Opus i sprawdza, że wznowiona sesja nadal pamięta wcześniejszą notatkę. -## Live: smoke powiązania ACP (`/acp spawn ... --bind here`) +## Live: smoke ACP bind (`/acp spawn ... --bind here`) - Test: `src/gateway/gateway-acp-bind.live.test.ts` -- Cel: zweryfikować rzeczywisty przepływ bind rozmowy ACP z live agentem ACP: +- Cel: zweryfikować rzeczywisty przepływ conversation-bind ACP z aktywnym agentem ACP: - wysłać `/acp spawn --bind here` - - powiązać syntetyczną rozmowę kanału wiadomości w miejscu - - wysłać zwykły follow-up w tej samej rozmowie + - powiązać syntetyczną konwersację kanału wiadomości w miejscu + - wysłać zwykły follow-up w tej samej konwersacji - zweryfikować, że follow-up trafia do transkryptu powiązanej sesji ACP - Włączenie: - `pnpm test:live src/gateway/gateway-acp-bind.live.test.ts` - `OPENCLAW_LIVE_ACP_BIND=1` -- Domyślne wartości: +- Domyślne ustawienia: - Agenci ACP w Dockerze: `claude,codex,gemini` - Agent ACP dla bezpośredniego `pnpm test:live ...`: `claude` - - Syntetyczny kanał: kontekst rozmowy w stylu Slack DM + - Syntetyczny kanał: kontekst konwersacji w stylu DM Slacka - Backend ACP: `acpx` - Nadpisania: - `OPENCLAW_LIVE_ACP_BIND_AGENT=claude` @@ -334,8 +336,8 @@ Uwagi: - `OPENCLAW_LIVE_ACP_BIND_AGENTS=claude,codex,gemini` - `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND='npx -y @agentclientprotocol/claude-agent-acp@'` - Uwagi: - - Ta ścieżka używa powierzchni gateway `chat.send` z polami syntetycznej ścieżki źródłowej dostępnymi tylko dla administratora, dzięki czemu testy mogą dołączać kontekst kanału wiadomości bez udawania dostarczenia zewnętrznego. - - Gdy `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND` nie jest ustawione, test używa wbudowanego rejestru agentów wtyczki `acpx` dla wybranego agenta harness ACP. + - Ta ścieżka używa powierzchni gateway `chat.send` z polami synthetic originating-route tylko dla administratora, aby testy mogły dołączać kontekst kanału wiadomości bez udawania dostarczenia na zewnątrz. + - Gdy `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND` nie jest ustawione, test używa wbudowanego rejestru agentów pluginu `acpx` dla wybranego agenta harness ACP. Przykład: @@ -345,13 +347,13 @@ OPENCLAW_LIVE_ACP_BIND=1 \ pnpm test:live src/gateway/gateway-acp-bind.live.test.ts ``` -Przepis Docker: +Recepta Docker: ```bash pnpm test:docker:live-acp-bind ``` -Przepisy Docker dla pojedynczego agenta: +Recepty Docker dla pojedynczego agenta: ```bash pnpm test:docker:live-acp-bind:claude @@ -359,25 +361,25 @@ pnpm test:docker:live-acp-bind:codex pnpm test:docker:live-acp-bind:gemini ``` -Uwagi Docker: +Uwagi dotyczące Dockera: -- Runner Docker znajduje się w `scripts/test-live-acp-bind-docker.sh`. -- Domyślnie uruchamia smoke bind ACP dla wszystkich obsługiwanych live agentów CLI po kolei: `claude`, `codex`, potem `gemini`. +- Runner Dockera znajduje się w `scripts/test-live-acp-bind-docker.sh`. +- Domyślnie uruchamia smoke ACP bind kolejno dla wszystkich obsługiwanych agentów live CLI: `claude`, `codex`, a następnie `gemini`. - Użyj `OPENCLAW_LIVE_ACP_BIND_AGENTS=claude`, `OPENCLAW_LIVE_ACP_BIND_AGENTS=codex` lub `OPENCLAW_LIVE_ACP_BIND_AGENTS=gemini`, aby zawęzić macierz. -- Wczytuje `~/.profile`, przygotowuje odpowiadający materiał auth CLI do kontenera, instaluje `acpx` do zapisywalnego prefiksu npm, a następnie instaluje wymagane live CLI (`@anthropic-ai/claude-code`, `@openai/codex` lub `@google/gemini-cli`), jeśli go brakuje. -- Wewnątrz Dockera runner ustawia `OPENCLAW_LIVE_ACP_BIND_ACPX_COMMAND=$HOME/.npm-global/bin/acpx`, aby `acpx` zachował zmienne środowiskowe dostawcy z wczytanego profilu dostępne dla podrzędnego CLI harnessu. +- Pobiera `~/.profile`, przygotowuje odpowiednie materiały auth CLI w kontenerze, instaluje `acpx` do zapisywalnego prefiksu npm, a następnie instaluje wymagane live CLI (`@anthropic-ai/claude-code`, `@openai/codex` lub `@google/gemini-cli`), jeśli go brakuje. +- Wewnątrz Dockera runner ustawia `OPENCLAW_LIVE_ACP_BIND_ACPX_COMMAND=$HOME/.npm-global/bin/acpx`, aby `acpx` zachował zmienne env providera z pobranego profilu dostępne dla potomnego harnessu CLI. -### Zalecane przepisy live +### Zalecane recepty live -Wąskie, jawne allowlisty są najszybsze i najmniej podatne na niestabilność: +Wąskie, jawne allowlisty są najszybsze i najmniej podatne na błędy: -- Pojedynczy model, bezpośrednio (bez gateway): +- Pojedynczy model, direct (bez gateway): - `OPENCLAW_LIVE_MODELS="openai/gpt-5.4" pnpm test:live src/agents/models.profiles.live.test.ts` -- Pojedynczy model, smoke gateway: +- Pojedynczy model, gateway smoke: - `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` -- Wywoływanie narzędzi przez kilku dostawców: +- Wywoływanie narzędzi u kilku providerów: - `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4,anthropic/claude-opus-4-6,google/gemini-3-flash-preview,zai/glm-4.7,minimax/MiniMax-M2.7" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` - Skupienie na Google (klucz API Gemini + Antigravity): @@ -386,35 +388,35 @@ Wąskie, jawne allowlisty są najszybsze i najmniej podatne na niestabilność: Uwagi: -- `google/...` używa Gemini API (klucz API). -- `google-antigravity/...` używa mostu OAuth Antigravity (punkt końcowy agenta w stylu Cloud Code Assist). -- `google-gemini-cli/...` używa lokalnego Gemini CLI na twojej maszynie (osobne auth + osobliwości narzędzi). +- `google/...` używa API Gemini (klucz API). +- `google-antigravity/...` używa mostu OAuth Antigravity (endpoint agenta w stylu Cloud Code Assist). +- `google-gemini-cli/...` używa lokalnego Gemini CLI na twojej maszynie (osobne auth + specyfika narzędzi). - Gemini API vs Gemini CLI: - - API: OpenClaw wywołuje hostowane Gemini API Google przez HTTP (auth przez klucz API / profil); to właśnie większość użytkowników ma na myśli, mówiąc „Gemini”. - - CLI: OpenClaw wywołuje lokalny binarny plik `gemini`; ma własne auth i może zachowywać się inaczej (streaming/obsługa narzędzi/rozjazd wersji). + - API: OpenClaw wywołuje hostowane API Gemini Google przez HTTP (auth kluczem API / profilem); to właśnie większość użytkowników ma na myśli, mówiąc „Gemini”. + - CLI: OpenClaw wykonuje lokalny binarny plik `gemini`; ma własne auth i może zachowywać się inaczej (streaming/obsługa narzędzi/rozjazd wersji). ## Live: macierz modeli (co obejmujemy) -Nie ma stałej „listy modeli CI” (live jest opt-in), ale to są **zalecane** modele do regularnego obejmowania na maszynie deweloperskiej z kluczami. +Nie ma stałej „listy modeli CI” (live jest opt-in), ale to są **zalecane** modele do regularnego pokrywania na maszynie deweloperskiej z kluczami. -### Zestaw smoke nowoczesny (wywoływanie narzędzi + obraz) +### Nowoczesny zestaw smoke (wywoływanie narzędzi + obraz) -To jest uruchomienie „typowych modeli”, które oczekujemy utrzymywać jako działające: +To jest uruchomienie „typowych modeli”, które powinno stale działać: - OpenAI (nie-Codex): `openai/gpt-5.4` (opcjonalnie: `openai/gpt-5.4-mini`) - OpenAI Codex: `openai-codex/gpt-5.4` - Anthropic: `anthropic/claude-opus-4-6` (lub `anthropic/claude-sonnet-4-6`) -- Google (Gemini API): `google/gemini-3.1-pro-preview` i `google/gemini-3-flash-preview` (unikaj starszych modeli Gemini 2.x) -- Google (Antigravity): `google-antigravity/claude-opus-4-6-thinking` i `google-antigravity/gemini-3-flash` +- Google (Gemini API): `google/gemini-3.1-pro-preview` oraz `google/gemini-3-flash-preview` (unikaj starszych modeli Gemini 2.x) +- Google (Antigravity): `google-antigravity/claude-opus-4-6-thinking` oraz `google-antigravity/gemini-3-flash` - Z.AI (GLM): `zai/glm-4.7` - MiniMax: `minimax/MiniMax-M2.7` -Uruchom smoke gateway z narzędziami + obrazem: +Uruchom gateway smoke z narzędziami + obrazem: `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4,openai-codex/gpt-5.4,anthropic/claude-opus-4-6,google/gemini-3.1-pro-preview,google/gemini-3-flash-preview,google-antigravity/claude-opus-4-6-thinking,google-antigravity/gemini-3-flash,zai/glm-4.7,minimax/MiniMax-M2.7" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` -### Bazowa linia: wywoływanie narzędzi (Read + opcjonalny Exec) +### Bazowe: wywoływanie narzędzi (Read + opcjonalnie Exec) -Wybierz co najmniej jeden model z każdej rodziny dostawców: +Wybierz co najmniej jeden model z każdej rodziny providerów: - OpenAI: `openai/gpt-5.4` (lub `openai/gpt-5.4-mini`) - Anthropic: `anthropic/claude-opus-4-6` (lub `anthropic/claude-sonnet-4-6`) @@ -422,44 +424,44 @@ Wybierz co najmniej jeden model z każdej rodziny dostawców: - Z.AI (GLM): `zai/glm-4.7` - MiniMax: `minimax/MiniMax-M2.7` -Opcjonalne dodatkowe pokrycie (mile widziane): +Opcjonalne dodatkowe pokrycie (warto mieć): - xAI: `xai/grok-4` (lub najnowszy dostępny) -- Mistral: `mistral/`… (wybierz jeden model z obsługą „tools”, który masz włączony) +- Mistral: `mistral/`… (wybierz jeden model z obsługą narzędzi, który masz włączony) - Cerebras: `cerebras/`… (jeśli masz dostęp) -- LM Studio: `lmstudio/`… (lokalne; wywoływanie narzędzi zależy od trybu API) +- LM Studio: `lmstudio/`… (lokalnie; wywoływanie narzędzi zależy od trybu API) -### Vision: wysyłanie obrazów (załącznik → wiadomość multimodalna) +### Vision: wysyłanie obrazu (załącznik → wiadomość multimodalna) -Uwzględnij co najmniej jeden model obsługujący obrazy w `OPENCLAW_LIVE_GATEWAY_MODELS` (Claude/Gemini/warianty OpenAI z obsługą vision itd.), aby przetestować sondę obrazu. +Uwzględnij przynajmniej jeden model obsługujący obrazy w `OPENCLAW_LIVE_GATEWAY_MODELS` (Claude/Gemini/warianty OpenAI z obsługą vision itd.), aby przetestować sondę obrazu. ### Agregatory / alternatywne gateway Jeśli masz włączone klucze, obsługujemy też testowanie przez: -- OpenRouter: `openrouter/...` (setki modeli; użyj `openclaw models scan`, aby znaleźć kandydatów z obsługą narzędzi+obrazów) +- OpenRouter: `openrouter/...` (setki modeli; użyj `openclaw models scan`, aby znaleźć kandydatów z obsługą narzędzi i obrazów) - OpenCode: `opencode/...` dla Zen oraz `opencode-go/...` dla Go (auth przez `OPENCODE_API_KEY` / `OPENCODE_ZEN_API_KEY`) -Więcej dostawców, których możesz dodać do macierzy live (jeśli masz poświadczenia/konfigurację): +Więcej providerów, których możesz dodać do macierzy live (jeśli masz poświadczenia/konfigurację): - Wbudowani: `openai`, `openai-codex`, `anthropic`, `google`, `google-vertex`, `google-antigravity`, `google-gemini-cli`, `zai`, `openrouter`, `opencode`, `opencode-go`, `xai`, `groq`, `cerebras`, `mistral`, `github-copilot` -- Przez `models.providers` (niestandardowe punkty końcowe): `minimax` (cloud/API) oraz dowolny proxy zgodny z OpenAI/Anthropic (LM Studio, vLLM, LiteLLM itd.) +- Przez `models.providers` (własne endpointy): `minimax` (cloud/API), plus dowolny proxy zgodny z OpenAI/Anthropic (LM Studio, vLLM, LiteLLM itd.) -Wskazówka: nie próbuj wpisywać na sztywno „wszystkich modeli” w dokumentacji. Autorytatywną listą jest to, co zwraca `discoverModels(...)` na twojej maszynie + jakie klucze są dostępne. +Wskazówka: nie próbuj na sztywno wpisywać „wszystkich modeli” w dokumentacji. Autorytatywną listą jest to, co zwraca `discoverModels(...)` na twojej maszynie + jakie klucze są dostępne. ## Poświadczenia (nigdy nie commituj) Testy live wykrywają poświadczenia tak samo jak CLI. W praktyce oznacza to: - Jeśli CLI działa, testy live powinny znaleźć te same klucze. -- Jeśli test live mówi „brak poświadczeń”, debuguj to tak samo, jak debugowałbyś `openclaw models list` / wybór modelu. +- Jeśli test live zgłasza „no creds”, debuguj to tak samo, jak debugowałbyś `openclaw models list` / wybór modelu. -- Profile auth per agent: `~/.openclaw/agents//agent/auth-profiles.json` (to właśnie oznaczają „klucze profilu” w testach live) +- Profile auth per agent: `~/.openclaw/agents//agent/auth-profiles.json` (to właśnie oznaczają „profile keys” w testach live) - Konfiguracja: `~/.openclaw/openclaw.json` (lub `OPENCLAW_CONFIG_PATH`) -- Starszy katalog stanu: `~/.openclaw/credentials/` (kopiowany do przygotowanego katalogu domowego live, jeśli istnieje, ale nie jest głównym magazynem kluczy profilu) -- Lokalne uruchomienia live domyślnie kopiują aktywną konfigurację, pliki `auth-profiles.json` wszystkich agentów, starszy katalog `credentials/` oraz obsługiwane zewnętrzne katalogi auth CLI do tymczasowego katalogu domowego testu; przygotowane katalogi live pomijają `workspace/` i `sandboxes/`, a nadpisania ścieżek `agents.*.workspace` / `agentDir` są usuwane, aby sondy nie trafiały do twojego prawdziwego host workspace. +- Starszy katalog stanu: `~/.openclaw/credentials/` (kopiowany do przygotowanego katalogu live home, jeśli istnieje, ale nie jest głównym store kluczy profili) +- Lokalne uruchomienia live domyślnie kopiują aktywną konfigurację, pliki `auth-profiles.json` per agent, starsze `credentials/` oraz obsługiwane zewnętrzne katalogi auth CLI do tymczasowego katalogu domowego testów; przygotowane katalogi live home pomijają `workspace/` i `sandboxes/`, a nadpisania ścieżek `agents.*.workspace` / `agentDir` są usuwane, aby sondy nie działały na twoim rzeczywistym workspace hosta. -Jeśli chcesz polegać na kluczach środowiskowych (np. wyeksportowanych w `~/.profile`), uruchamiaj lokalne testy po `source ~/.profile` albo użyj runnerów Docker poniżej (mogą montować `~/.profile` do kontenera). +Jeśli chcesz polegać na kluczach env (np. wyeksportowanych w `~/.profile`), uruchamiaj testy lokalne po `source ~/.profile` albo użyj poniższych runnerów Docker (mogą zamontować `~/.profile` do kontenera). ## Deepgram live (transkrypcja audio) @@ -477,9 +479,9 @@ Jeśli chcesz polegać na kluczach środowiskowych (np. wyeksportowanych w `~/.p - Test: `extensions/comfy/comfy.live.test.ts` - Włączenie: `OPENCLAW_LIVE_TEST=1 COMFY_LIVE_TEST=1 pnpm test:live -- extensions/comfy/comfy.live.test.ts` - Zakres: - - Testuje dołączone ścieżki comfy dla obrazów, wideo i `music_generate` + - Testuje wbudowane ścieżki comfy dla obrazów, wideo i `music_generate` - Pomija każdą możliwość, jeśli `models.providers.comfy.` nie jest skonfigurowane - - Przydatne po zmianie wysyłania workflow comfy, odpytywania, pobierania lub rejestracji wtyczki + - Przydatne po zmianach w przesyłaniu workflow comfy, odpytywaniu, pobieraniu lub rejestracji pluginu ## Live generowania obrazów @@ -487,24 +489,24 @@ Jeśli chcesz polegać na kluczach środowiskowych (np. wyeksportowanych w `~/.p - Polecenie: `pnpm test:live src/image-generation/runtime.live.test.ts` - Harness: `pnpm test:live:media image` - Zakres: - - Wylicza każdą zarejestrowaną wtyczkę dostawcy generowania obrazów - - Przed sondowaniem wczytuje brakujące zmienne środowiskowe dostawcy z twojej powłoki logowania (`~/.profile`) - - Domyślnie używa kluczy API live/env przed zapisanymi profilami auth, dzięki czemu stare testowe klucze w `auth-profiles.json` nie maskują prawdziwych poświadczeń z powłoki - - Pomija dostawców bez użytecznego auth/profilu/modelu + - Wylicza każdy zarejestrowany plugin providera generowania obrazów + - Ładuje brakujące zmienne env providera z twojego login shell (`~/.profile`) przed wykonaniem sond + - Domyślnie używa aktywnych/env kluczy API przed zapisanymi profilami auth, aby stare klucze testowe w `auth-profiles.json` nie maskowały rzeczywistych poświadczeń shell + - Pomija providerów bez użytecznego auth/profilu/modelu - Uruchamia standardowe warianty generowania obrazów przez współdzieloną możliwość runtime: - `google:flash-generate` - `google:pro-generate` - `google:pro-edit` - `openai:default-generate` -- Aktualnie objęci dołączeni dostawcy: +- Aktualnie objęci wbudowani providerzy: - `openai` - `google` -- Opcjonalne zawężenie: +- Opcjonalne zawężanie: - `OPENCLAW_LIVE_IMAGE_GENERATION_PROVIDERS="openai,google"` - `OPENCLAW_LIVE_IMAGE_GENERATION_MODELS="openai/gpt-image-1,google/gemini-3.1-flash-image-preview"` - `OPENCLAW_LIVE_IMAGE_GENERATION_CASES="google:flash-generate,google:pro-edit"` - Opcjonalne zachowanie auth: - - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, aby wymusić auth z magazynu profili i ignorować nadpisania tylko-env + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` aby wymusić auth ze store profili i ignorować nadpisania tylko-env ## Live generowania muzyki @@ -512,23 +514,23 @@ Jeśli chcesz polegać na kluczach środowiskowych (np. wyeksportowanych w `~/.p - Włączenie: `OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/music-generation-providers.live.test.ts` - Harness: `pnpm test:live:media music` - Zakres: - - Testuje współdzieloną ścieżkę dołączonych dostawców generowania muzyki + - Testuje współdzieloną wbudowaną ścieżkę providera generowania muzyki - Obecnie obejmuje Google i MiniMax - - Przed sondowaniem wczytuje zmienne środowiskowe dostawców z twojej powłoki logowania (`~/.profile`) - - Domyślnie używa kluczy API live/env przed zapisanymi profilami auth, dzięki czemu stare testowe klucze w `auth-profiles.json` nie maskują prawdziwych poświadczeń z powłoki - - Pomija dostawców bez użytecznego auth/profilu/modelu + - Ładuje zmienne env providera z twojego login shell (`~/.profile`) przed wykonaniem sond + - Domyślnie używa aktywnych/env kluczy API przed zapisanymi profilami auth, aby stare klucze testowe w `auth-profiles.json` nie maskowały rzeczywistych poświadczeń shell + - Pomija providerów bez użytecznego auth/profilu/modelu - Uruchamia oba zadeklarowane tryby runtime, gdy są dostępne: - - `generate` z wejściem opartym tylko na prompt - - `edit`, gdy dostawca deklaruje `capabilities.edit.enabled` - - Aktualne pokrycie współdzielonej ścieżki: + - `generate` z wejściem opartym wyłącznie na prompt + - `edit`, gdy provider deklaruje `capabilities.edit.enabled` + - Obecne pokrycie współdzielonej ścieżki: - `google`: `generate`, `edit` - `minimax`: `generate` - - `comfy`: osobny plik live Comfy, nie ten współdzielony przegląd -- Opcjonalne zawężenie: + - `comfy`: osobny plik Comfy live, nie ten współdzielony przegląd +- Opcjonalne zawężanie: - `OPENCLAW_LIVE_MUSIC_GENERATION_PROVIDERS="google,minimax"` - `OPENCLAW_LIVE_MUSIC_GENERATION_MODELS="google/lyria-3-clip-preview,minimax/music-2.5+"` - Opcjonalne zachowanie auth: - - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, aby wymusić auth z magazynu profili i ignorować nadpisania tylko-env + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` aby wymusić auth ze store profili i ignorować nadpisania tylko-env ## Live generowania wideo @@ -536,223 +538,223 @@ Jeśli chcesz polegać na kluczach środowiskowych (np. wyeksportowanych w `~/.p - Włączenie: `OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/video-generation-providers.live.test.ts` - Harness: `pnpm test:live:media video` - Zakres: - - Testuje współdzieloną ścieżkę dołączonych dostawców generowania wideo - - Przed sondowaniem wczytuje zmienne środowiskowe dostawców z twojej powłoki logowania (`~/.profile`) - - Domyślnie używa kluczy API live/env przed zapisanymi profilami auth, dzięki czemu stare testowe klucze w `auth-profiles.json` nie maskują prawdziwych poświadczeń z powłoki - - Pomija dostawców bez użytecznego auth/profilu/modelu + - Testuje współdzieloną wbudowaną ścieżkę providera generowania wideo + - Ładuje zmienne env providera z twojego login shell (`~/.profile`) przed wykonaniem sond + - Domyślnie używa aktywnych/env kluczy API przed zapisanymi profilami auth, aby stare klucze testowe w `auth-profiles.json` nie maskowały rzeczywistych poświadczeń shell + - Pomija providerów bez użytecznego auth/profilu/modelu - Uruchamia oba zadeklarowane tryby runtime, gdy są dostępne: - - `generate` z wejściem opartym tylko na prompt - - `imageToVideo`, gdy dostawca deklaruje `capabilities.imageToVideo.enabled` i wybrany dostawca/model akceptuje wejście lokalnego obrazu opartego na buforze we współdzielonym przeglądzie - - `videoToVideo`, gdy dostawca deklaruje `capabilities.videoToVideo.enabled` i wybrany dostawca/model akceptuje wejście lokalnego wideo opartego na buforze we współdzielonym przeglądzie - - Aktualni dostawcy `imageToVideo` zadeklarowani, ale pomijani we współdzielonym przeglądzie: - - `vydra`, ponieważ dołączony `veo3` obsługuje tylko tekst, a dołączony `kling` wymaga zdalnego URL obrazu - - Pokrycie Vydra specyficzne dla dostawcy: + - `generate` z wejściem opartym wyłącznie na prompt + - `imageToVideo`, gdy provider deklaruje `capabilities.imageToVideo.enabled` i wybrany provider/model akceptuje lokalne wejście obrazu oparte na buforze we współdzielonym przeglądzie + - `videoToVideo`, gdy provider deklaruje `capabilities.videoToVideo.enabled` i wybrany provider/model akceptuje lokalne wejście wideo oparte na buforze we współdzielonym przeglądzie + - Aktualnie zadeklarowani, ale pomijani providerzy `imageToVideo` we współdzielonym przeglądzie: + - `vydra`, ponieważ wbudowane `veo3` jest tylko tekstowe, a wbudowany `kling` wymaga zdalnego URL obrazu + - Pokrycie specyficzne dla providera Vydra: - `OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_VYDRA_VIDEO=1 pnpm test:live -- extensions/vydra/vydra.live.test.ts` - - ten plik uruchamia `veo3` text-to-video oraz ścieżkę `kling`, która domyślnie używa fixture zdalnego URL obrazu + - ten plik uruchamia `veo3` text-to-video oraz ścieżkę `kling`, która domyślnie używa fixtury ze zdalnym URL obrazu - Aktualne pokrycie live `videoToVideo`: - - tylko `runway`, gdy wybrany model to `runway/gen4_aleph` - - Aktualni dostawcy `videoToVideo` zadeklarowani, ale pomijani we współdzielonym przeglądzie: - - `alibaba`, `qwen`, `xai`, ponieważ te ścieżki obecnie wymagają zdalnych referencyjnych URL `http(s)` / MP4 + - tylko `runway`, gdy wybranym modelem jest `runway/gen4_aleph` + - Aktualnie zadeklarowani, ale pomijani providerzy `videoToVideo` we współdzielonym przeglądzie: + - `alibaba`, `qwen`, `xai`, ponieważ te ścieżki wymagają obecnie zdalnych referencyjnych URL `http(s)` / MP4 - `google`, ponieważ obecna współdzielona ścieżka Gemini/Veo używa lokalnego wejścia opartego na buforze i ta ścieżka nie jest akceptowana we współdzielonym przeglądzie - `openai`, ponieważ obecna współdzielona ścieżka nie gwarantuje dostępu do specyficznych dla organizacji funkcji video inpaint/remix -- Opcjonalne zawężenie: +- Opcjonalne zawężanie: - `OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="google,openai,runway"` - `OPENCLAW_LIVE_VIDEO_GENERATION_MODELS="google/veo-3.1-fast-generate-preview,openai/sora-2,runway/gen4_aleph"` - Opcjonalne zachowanie auth: - - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, aby wymusić auth z magazynu profili i ignorować nadpisania tylko-env + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` aby wymusić auth ze store profili i ignorować nadpisania tylko-env -## Harness live dla mediów +## Harness live mediów - Polecenie: `pnpm test:live:media` - Cel: - - Uruchamia współdzielone zestawy live dla obrazów, muzyki i wideo przez jeden natywny dla repo entrypoint - - Automatycznie wczytuje brakujące zmienne środowiskowe dostawców z `~/.profile` - - Domyślnie automatycznie zawęża każdy zestaw do dostawców, którzy aktualnie mają użyteczne auth - - Ponownie używa `scripts/test-live.mjs`, więc zachowanie heartbeatów i trybu cichego pozostaje spójne + - Uruchamia współdzielone pakiety live dla obrazów, muzyki i wideo przez jedno natywne wejście repo + - Automatycznie ładuje brakujące zmienne env providera z `~/.profile` + - Domyślnie automatycznie zawęża każdy pakiet do providerów, którzy aktualnie mają użyteczne auth + - Ponownie używa `scripts/test-live.mjs`, dzięki czemu zachowanie heartbeat i quiet mode pozostaje spójne - Przykłady: - `pnpm test:live:media` - `pnpm test:live:media image video --providers openai,google,minimax` - `pnpm test:live:media video --video-providers openai,runway --all-providers` - `pnpm test:live:media music --quiet` -## Uruchomienia w Dockerze (opcjonalne sprawdzenia typu „działa w Linuksie”) +## Runnery Docker (opcjonalne kontrole „działa w Linuxie”) -Te uruchomienia Dockera dzielą się na dwa koszyki: +Te runnery Docker dzielą się na dwa koszyki: -- Uruchomienia live modeli: `test:docker:live-models` i `test:docker:live-gateway` uruchamiają tylko odpowiadający im plik live z kluczami profilu wewnątrz obrazu Docker repozytorium (`src/agents/models.profiles.live.test.ts` i `src/gateway/gateway-models.profiles.live.test.ts`), montując lokalny katalog config i workspace (oraz wczytując `~/.profile`, jeśli został zamontowany). Odpowiadające lokalne entrypointy to `test:live:models-profiles` i `test:live:gateway-profiles`. -- Uruchomienia Docker live domyślnie mają mniejszy limit smoke, aby pełny przegląd Dockera pozostawał praktyczny: +- Runnery live-model: `test:docker:live-models` i `test:docker:live-gateway` uruchamiają tylko odpowiadający im plik live z kluczami profili wewnątrz obrazu Docker repo (`src/agents/models.profiles.live.test.ts` i `src/gateway/gateway-models.profiles.live.test.ts`), montując lokalny katalog konfiguracji i workspace (oraz pobierając `~/.profile`, jeśli jest zamontowany). Odpowiadające im lokalne entrypointy to `test:live:models-profiles` i `test:live:gateway-profiles`. +- Runnery Docker live domyślnie używają mniejszego limitu smoke, aby pełny przegląd Docker pozostawał praktyczny: `test:docker:live-models` domyślnie ustawia `OPENCLAW_LIVE_MAX_MODELS=12`, a `test:docker:live-gateway` domyślnie ustawia `OPENCLAW_LIVE_GATEWAY_SMOKE=1`, `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=8`, `OPENCLAW_LIVE_GATEWAY_STEP_TIMEOUT_MS=45000` oraz - `OPENCLAW_LIVE_GATEWAY_MODEL_TIMEOUT_MS=90000`. Nadpisz te zmienne środowiskowe, gdy - świadomie chcesz większego, wyczerpującego skanu. -- `test:docker:all` buduje obraz Docker live tylko raz przez `test:docker:live-build`, a następnie ponownie używa go dla dwóch ścieżek live Docker. -- Runnery smoke kontenerów: `test:docker:openwebui`, `test:docker:onboard`, `test:docker:gateway-network`, `test:docker:mcp-channels` oraz `test:docker:plugins` uruchamiają jeden lub więcej prawdziwych kontenerów i weryfikują ścieżki integracji wyższego poziomu. + `OPENCLAW_LIVE_GATEWAY_MODEL_TIMEOUT_MS=90000`. Nadpisz te zmienne env, gdy + jawnie chcesz uruchomić większy, wyczerpujący przegląd. +- `test:docker:all` buduje obraz live Docker jeden raz przez `test:docker:live-build`, a następnie ponownie używa go dla dwóch ścieżek Docker live. +- Runnery smoke kontenerów: `test:docker:openwebui`, `test:docker:onboard`, `test:docker:gateway-network`, `test:docker:mcp-channels` oraz `test:docker:plugins` uruchamiają jeden lub więcej rzeczywistych kontenerów i weryfikują ścieżki integracji wyższego poziomu. -Runnery Docker live modeli także montują tylko potrzebne katalogi auth CLI (lub wszystkie obsługiwane, gdy uruchomienie nie jest zawężone), a następnie kopiują je do katalogu domowego kontenera przed startem, tak aby OAuth zewnętrznego CLI mógł odświeżać tokeny bez modyfikowania hostowego magazynu auth: +Runnery Docker live-model bind-mountują też tylko potrzebne katalogi auth CLI (lub wszystkie obsługiwane, gdy uruchomienie nie jest zawężone), a następnie kopiują je do katalogu domowego kontenera przed startem, aby zewnętrzny OAuth CLI mógł odświeżać tokeny bez modyfikowania store auth hosta: -- Modele bezpośrednie: `pnpm test:docker:live-models` (skrypt: `scripts/test-live-models-docker.sh`) -- Smoke bind ACP: `pnpm test:docker:live-acp-bind` (skrypt: `scripts/test-live-acp-bind-docker.sh`) +- Direct models: `pnpm test:docker:live-models` (skrypt: `scripts/test-live-models-docker.sh`) +- Smoke ACP bind: `pnpm test:docker:live-acp-bind` (skrypt: `scripts/test-live-acp-bind-docker.sh`) - Smoke backendu CLI: `pnpm test:docker:live-cli-backend` (skrypt: `scripts/test-live-cli-backend-docker.sh`) -- Gateway + dev agent: `pnpm test:docker:live-gateway` (skrypt: `scripts/test-live-gateway-models-docker.sh`) +- Gateway + agent deweloperski: `pnpm test:docker:live-gateway` (skrypt: `scripts/test-live-gateway-models-docker.sh`) - Live smoke Open WebUI: `pnpm test:docker:openwebui` (skrypt: `scripts/e2e/openwebui-docker.sh`) - Kreator onboardingu (TTY, pełne scaffoldowanie): `pnpm test:docker:onboard` (skrypt: `scripts/e2e/onboard-docker.sh`) - Sieć gateway (dwa kontenery, auth WS + health): `pnpm test:docker:gateway-network` (skrypt: `scripts/e2e/gateway-network-docker.sh`) -- Most kanałów MCP (zainicjalizowany Gateway + most stdio + smoke surowej ramki powiadomień Claude): `pnpm test:docker:mcp-channels` (skrypt: `scripts/e2e/mcp-channels-docker.sh`) -- Wtyczki (smoke instalacji + alias `/plugin` + semantyka restartu pakietu Claude): `pnpm test:docker:plugins` (skrypt: `scripts/e2e/plugins-docker.sh`) +- Most kanałów MCP (seedowany Gateway + most stdio + smoke surowych ramek powiadomień Claude): `pnpm test:docker:mcp-channels` (skrypt: `scripts/e2e/mcp-channels-docker.sh`) +- Plugins (smoke instalacji + alias `/plugin` + semantyka restartu pakietu Claude): `pnpm test:docker:plugins` (skrypt: `scripts/e2e/plugins-docker.sh`) -Runnery Docker live modeli także montują bieżący checkout tylko do odczytu i -przygotowują go w tymczasowym katalogu roboczym wewnątrz kontenera. Dzięki temu obraz runtime -pozostaje mały, a mimo to Vitest działa na twoich dokładnych lokalnych źródłach/configu. -Krok przygotowania pomija duże lokalne cache i wyniki buildów aplikacji, takie jak +Runnery Docker live-model bind-mountują też bieżący checkout tylko do odczytu i +przygotowują go do tymczasowego katalogu roboczego wewnątrz kontenera. Dzięki temu obraz runtime +pozostaje lekki, a Vitest nadal działa na dokładnie twoich lokalnych źródłach/konfiguracji. +Etap przygotowania pomija duże lokalne cache i wyniki buildów aplikacji, takie jak `.pnpm-store`, `.worktrees`, `__openclaw_vitest__` oraz lokalne dla aplikacji katalogi `.build` lub -wyniki Gradle, dzięki czemu uruchomienia Docker live nie tracą minut na kopiowanie +wyniki Gradle, aby uruchomienia Docker live nie traciły minut na kopiowanie artefaktów specyficznych dla maszyny. -Ustawiają też `OPENCLAW_SKIP_CHANNELS=1`, aby sondy gateway live nie uruchamiały -prawdziwych workerów kanałów Telegram/Discord/itd. wewnątrz kontenera. -`test:docker:live-models` nadal uruchamia `pnpm test:live`, więc przekazuj także -`OPENCLAW_LIVE_GATEWAY_*`, gdy chcesz zawęzić lub wykluczyć pokrycie gateway -live z tej ścieżki Docker. -`test:docker:openwebui` to smoke kompatybilności wyższego poziomu: uruchamia -kontener gateway OpenClaw z włączonymi punktami końcowymi HTTP zgodnymi z OpenAI, -uruchamia przypięty kontener Open WebUI przeciwko temu gateway, loguje się przez +Ustawiają one również `OPENCLAW_SKIP_CHANNELS=1`, aby sondy gateway live nie uruchamiały +rzeczywistych workerów kanałów Telegram/Discord/itd. wewnątrz kontenera. +`test:docker:live-models` nadal uruchamia `pnpm test:live`, więc przekaż także +`OPENCLAW_LIVE_GATEWAY_*`, gdy musisz zawęzić lub wykluczyć pokrycie gateway +live w tej ścieżce Docker. +`test:docker:openwebui` jest smoke kompatybilności wyższego poziomu: uruchamia +kontener gateway OpenClaw z włączonymi endpointami HTTP zgodnymi z OpenAI, +uruchamia przypięty kontener Open WebUI względem tego gateway, loguje się przez Open WebUI, weryfikuje, że `/api/models` udostępnia `openclaw/default`, a następnie wysyła -prawdziwe żądanie czatu przez proxy `/api/chat/completions` Open WebUI. +rzeczywiste żądanie czatu przez proxy `/api/chat/completions` Open WebUI. Pierwsze uruchomienie może być zauważalnie wolniejsze, ponieważ Docker może potrzebować pobrać -obraz Open WebUI, a Open WebUI może potrzebować dokończyć własną konfigurację cold-start. -Ta ścieżka oczekuje działającego klucza live modelu, a `OPENCLAW_PROFILE_FILE` -(`~/.profile` domyślnie) jest podstawowym sposobem dostarczenia go w uruchomieniach z Dockerem. +obraz Open WebUI, a Open WebUI może potrzebować zakończyć własną konfigurację cold-start. +Ta ścieżka oczekuje użytecznego klucza modelu live, a `OPENCLAW_PROFILE_FILE` +(domyslnie `~/.profile`) jest podstawowym sposobem dostarczenia go w uruchomieniach Docker. Udane uruchomienia wypisują mały ładunek JSON, taki jak `{ "ok": true, "model": "openclaw/default", ... }`. -`test:docker:mcp-channels` jest celowo deterministyczny i nie wymaga -prawdziwego konta Telegram, Discord ani iMessage. Uruchamia zainicjalizowany kontener -Gateway, uruchamia drugi kontener, który startuje `openclaw mcp serve`, a następnie -weryfikuje wykrywanie routowanych rozmów, odczyty transkryptów, metadane załączników, -zachowanie kolejki zdarzeń live, routing wysyłek wychodzących oraz powiadomienia w stylu Claude o kanałach + -uprawnieniach przez prawdziwy most stdio MCP. Kontrola powiadomień -bada bezpośrednio surowe ramki stdio MCP, więc smoke weryfikuje to, co most -faktycznie emituje, a nie tylko to, co akurat udostępnia konkretny SDK klienta. +`test:docker:mcp-channels` jest celowo deterministyczny i nie potrzebuje +prawdziwego konta Telegram, Discord ani iMessage. Uruchamia seedowany kontener Gateway, +startuje drugi kontener, który uruchamia `openclaw mcp serve`, a następnie +weryfikuje wykrywanie routowanych konwersacji, odczyty transkryptów, metadane załączników, +zachowanie kolejki zdarzeń live, routing wysyłki wychodzącej oraz powiadomienia w stylu Claude o kanałach + +uprawnieniach przez rzeczywisty most stdio MCP. Kontrola powiadomień +sprawdza bezpośrednio surowe ramki stdio MCP, więc smoke weryfikuje to, co most +rzeczywiście emituje, a nie tylko to, co akurat udostępnia konkretne SDK klienta. -Ręczny smoke zwykłego wątku ACP w naturalnym języku (nie CI): +Ręczny smoke wątku ACP w plain language (nie CI): - `bun scripts/dev/discord-acp-plain-language-smoke.ts --channel ...` -- Zachowaj ten skrypt do przepływów regresji/debugowania. Może znów być potrzebny do walidacji routingu wątków ACP, więc go nie usuwaj. +- Zachowaj ten skrypt do przepływów regresji/debugowania. Może być ponownie potrzebny do walidacji routingu wątków ACP, więc nie usuwaj go. -Przydatne zmienne środowiskowe: +Przydatne zmienne env: - `OPENCLAW_CONFIG_DIR=...` (domyślnie: `~/.openclaw`) montowane do `/home/node/.openclaw` - `OPENCLAW_WORKSPACE_DIR=...` (domyślnie: `~/.openclaw/workspace`) montowane do `/home/node/.openclaw/workspace` -- `OPENCLAW_PROFILE_FILE=...` (domyślnie: `~/.profile`) montowane do `/home/node/.profile` i wczytywane przed uruchomieniem testów -- `OPENCLAW_DOCKER_CLI_TOOLS_DIR=...` (domyślnie: `~/.cache/openclaw/docker-cli-tools`) montowane do `/home/node/.npm-global` dla buforowanych instalacji CLI wewnątrz Dockera -- Zewnętrzne katalogi/pliki auth CLI w `$HOME` są montowane tylko do odczytu pod `/host-auth...`, a następnie kopiowane do `/home/node/...` przed startem testów +- `OPENCLAW_PROFILE_FILE=...` (domyślnie: `~/.profile`) montowane do `/home/node/.profile` i pobierane przed uruchomieniem testów +- `OPENCLAW_DOCKER_CLI_TOOLS_DIR=...` (domyślnie: `~/.cache/openclaw/docker-cli-tools`) montowane do `/home/node/.npm-global` dla cache instalacji CLI wewnątrz Dockera +- Zewnętrzne katalogi/pliki auth CLI pod `$HOME` są montowane tylko do odczytu pod `/host-auth...`, a następnie kopiowane do `/home/node/...` przed uruchomieniem testów - Domyślne katalogi: `.minimax` - Domyślne pliki: `~/.codex/auth.json`, `~/.codex/config.toml`, `.claude.json`, `~/.claude/.credentials.json`, `~/.claude/settings.json`, `~/.claude/settings.local.json` - - Zawężone uruchomienia dostawców montują tylko potrzebne katalogi/pliki wywnioskowane z `OPENCLAW_LIVE_PROVIDERS` / `OPENCLAW_LIVE_GATEWAY_PROVIDERS` - - Ręczne nadpisanie: `OPENCLAW_DOCKER_AUTH_DIRS=all`, `OPENCLAW_DOCKER_AUTH_DIRS=none` lub lista rozdzielana przecinkami, np. `OPENCLAW_DOCKER_AUTH_DIRS=.claude,.codex` -- `OPENCLAW_LIVE_GATEWAY_MODELS=...` / `OPENCLAW_LIVE_MODELS=...`, aby zawęzić uruchomienie -- `OPENCLAW_LIVE_GATEWAY_PROVIDERS=...` / `OPENCLAW_LIVE_PROVIDERS=...`, aby filtrować dostawców wewnątrz kontenera -- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, aby upewnić się, że poświadczenia pochodzą z magazynu profili (a nie ze środowiska) -- `OPENCLAW_OPENWEBUI_MODEL=...`, aby wybrać model udostępniany przez gateway dla smoke Open WebUI -- `OPENCLAW_OPENWEBUI_PROMPT=...`, aby nadpisać prompt kontroli nonce używany przez smoke Open WebUI -- `OPENWEBUI_IMAGE=...`, aby nadpisać przypięty tag obrazu Open WebUI + - Zawężone uruchomienia providerów montują tylko potrzebne katalogi/pliki wywnioskowane z `OPENCLAW_LIVE_PROVIDERS` / `OPENCLAW_LIVE_GATEWAY_PROVIDERS` + - Nadpisanie ręczne: `OPENCLAW_DOCKER_AUTH_DIRS=all`, `OPENCLAW_DOCKER_AUTH_DIRS=none` lub lista rozdzielana przecinkami, np. `OPENCLAW_DOCKER_AUTH_DIRS=.claude,.codex` +- `OPENCLAW_LIVE_GATEWAY_MODELS=...` / `OPENCLAW_LIVE_MODELS=...` aby zawęzić uruchomienie +- `OPENCLAW_LIVE_GATEWAY_PROVIDERS=...` / `OPENCLAW_LIVE_PROVIDERS=...` aby filtrować providerów w kontenerze +- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` aby upewnić się, że poświadczenia pochodzą ze store profili (a nie z env) +- `OPENCLAW_OPENWEBUI_MODEL=...` aby wybrać model udostępniany przez gateway dla smoke Open WebUI +- `OPENCLAW_OPENWEBUI_PROMPT=...` aby nadpisać prompt kontroli nonce używany przez smoke Open WebUI +- `OPENWEBUI_IMAGE=...` aby nadpisać przypięty tag obrazu Open WebUI -## Kontrola dokumentacji +## Spójność dokumentacji -Po edycji dokumentacji uruchom kontrole dokumentów: `pnpm check:docs`. -Uruchom pełną walidację anchorów Mintlify, gdy potrzebujesz też kontroli nagłówków w obrębie strony: `pnpm docs:check-links:anchors`. +Po edycji dokumentacji uruchom kontrolę dokumentacji: `pnpm check:docs`. +Uruchom pełną walidację anchorów Mintlify, gdy potrzebujesz również kontroli nagłówków na stronie: `pnpm docs:check-links:anchors`. -## Regresja offline (bezpieczna dla CI) +## Regresje offline (bezpieczne dla CI) -To są regresje „rzeczywistego pipeline” bez prawdziwych dostawców: +Są to regresje „rzeczywistego pipeline” bez prawdziwych providerów: -- Wywoływanie narzędzi gateway (mock OpenAI, prawdziwa pętla gateway + agent): `src/gateway/gateway.test.ts` (przypadek: "runs a mock OpenAI tool call end-to-end via gateway agent loop") -- Kreator gateway (WS `wizard.start`/`wizard.next`, zapis config + wymuszone auth): `src/gateway/gateway.test.ts` (przypadek: "runs wizard over ws and writes auth token config") +- Wywoływanie narzędzi gateway (mock OpenAI, rzeczywista pętla gateway + agent): `src/gateway/gateway.test.ts` (przypadek: "runs a mock OpenAI tool call end-to-end via gateway agent loop") +- Kreator gateway (WS `wizard.start`/`wizard.next`, zapisuje config + wymuszone auth): `src/gateway/gateway.test.ts` (przypadek: "runs wizard over ws and writes auth token config") ## Ewalucje niezawodności agenta (Skills) -Mamy już kilka bezpiecznych dla CI testów, które działają jak „ewaluacje niezawodności agenta”: +Mamy już kilka bezpiecznych dla CI testów, które zachowują się jak „ewaluacje niezawodności agenta”: -- Mock wywoływania narzędzi przez prawdziwą pętlę gateway + agent (`src/gateway/gateway.test.ts`). -- Pełne przepływy kreatora, które walidują okablowanie sesji i efekty konfiguracji (`src/gateway/gateway.test.ts`). +- Mock wywoływania narzędzi przez rzeczywistą pętlę gateway + agent (`src/gateway/gateway.test.ts`). +- Przepływy kreatora end-to-end, które walidują okablowanie sesji i efekty konfiguracji (`src/gateway/gateway.test.ts`). Czego nadal brakuje dla Skills (zobacz [Skills](/pl/tools/skills)): -- **Podejmowanie decyzji:** gdy skille są wymienione w promptcie, czy agent wybiera właściwy skill (albo unika nieistotnych)? -- **Zgodność:** czy agent odczytuje `SKILL.md` przed użyciem i wykonuje wymagane kroki/argumenty? -- **Kontrakty workflow:** scenariusze wieloturowe potwierdzające kolejność narzędzi, przenoszenie historii sesji i granice sandboxa. +- **Decisioning:** gdy Skills są wymienione w prompcie, czy agent wybiera właściwy skill (albo unika nieistotnych)? +- **Compliance:** czy agent czyta `SKILL.md` przed użyciem i wykonuje wymagane kroki/argumenty? +- **Kontrakty przepływu pracy:** scenariusze wieloturowe, które potwierdzają kolejność narzędzi, przenoszenie historii sesji i granice sandboxa. Przyszłe ewaluacje powinny najpierw pozostać deterministyczne: -- Runner scenariuszy używający mockowanych dostawców do potwierdzania wywołań narzędzi + kolejności, odczytów plików skillów i okablowania sesji. -- Mały zestaw scenariuszy skupionych na skillach (użyć vs unikać, bramkowanie, wstrzykiwanie promptu). -- Opcjonalne ewaluacje live (opt-in, bramkowane env) dopiero po wdrożeniu zestawu bezpiecznego dla CI. +- Runner scenariuszy używający mock providerów do potwierdzania wywołań narzędzi + kolejności, odczytów plików skill i okablowania sesji. +- Mały pakiet scenariuszy skupionych na skillach (użyj vs unikaj, gating, prompt injection). +- Opcjonalne ewaluacje live (opt-in, sterowane env) dopiero po wdrożeniu pakietu bezpiecznego dla CI. -## Testy kontraktów (kształt wtyczek i kanałów) +## Testy kontraktowe (kształt pluginów i kanałów) -Testy kontraktów weryfikują, że każda zarejestrowana wtyczka i każdy kanał są zgodne ze swoim -kontraktem interfejsu. Iterują po wszystkich wykrytych wtyczkach i uruchamiają zestaw +Testy kontraktowe weryfikują, że każdy zarejestrowany plugin i kanał jest zgodny ze swoim +kontraktem interfejsu. Iterują po wszystkich wykrytych pluginach i uruchamiają pakiet asercji kształtu i zachowania. Domyślna ścieżka unit `pnpm test` celowo pomija te współdzielone pliki seam i smoke; uruchamiaj polecenia kontraktów jawnie, -gdy dotykasz współdzielonych powierzchni kanałów lub dostawców. +gdy dotykasz współdzielonych powierzchni kanałów lub providerów. ### Polecenia - Wszystkie kontrakty: `pnpm test:contracts` - Tylko kontrakty kanałów: `pnpm test:contracts:channels` -- Tylko kontrakty dostawców: `pnpm test:contracts:plugins` +- Tylko kontrakty providerów: `pnpm test:contracts:plugins` ### Kontrakty kanałów Znajdują się w `src/channels/plugins/contracts/*.contract.test.ts`: -- **plugin** - Podstawowy kształt wtyczki (id, nazwa, możliwości) +- **plugin** - Podstawowy kształt pluginu (id, name, capabilities) - **setup** - Kontrakt kreatora konfiguracji - **session-binding** - Zachowanie wiązania sesji - **outbound-payload** - Struktura ładunku wiadomości - **inbound** - Obsługa wiadomości przychodzących - **actions** - Handlery akcji kanału - **threading** - Obsługa identyfikatorów wątków -- **directory** - API katalogu/listy +- **directory** - API katalogu/listy kontaktów - **group-policy** - Egzekwowanie polityki grup -### Kontrakty statusu dostawców +### Kontrakty statusu providerów Znajdują się w `src/plugins/contracts/*.contract.test.ts`. - **status** - Sondy statusu kanału -- **registry** - Kształt rejestru wtyczek +- **registry** - Kształt rejestru pluginów -### Kontrakty dostawców +### Kontrakty providerów Znajdują się w `src/plugins/contracts/*.contract.test.ts`: - **auth** - Kontrakt przepływu auth - **auth-choice** - Wybór/selekcja auth - **catalog** - API katalogu modeli -- **discovery** - Wykrywanie wtyczek -- **loader** - Ładowanie wtyczek -- **runtime** - Runtime dostawcy -- **shape** - Kształt/interfejs wtyczki +- **discovery** - Wykrywanie pluginów +- **loader** - Ładowanie pluginów +- **runtime** - Runtime providera +- **shape** - Kształt/interfejs pluginu - **wizard** - Kreator konfiguracji ### Kiedy uruchamiać -- Po zmianie eksportów lub subpathów `plugin-sdk` -- Po dodaniu lub modyfikacji kanału albo wtyczki dostawcy -- Po refaktoryzacji rejestracji lub wykrywania wtyczek +- Po zmianie eksportów lub subpaths `plugin-sdk` +- Po dodaniu lub modyfikacji pluginu kanału lub providera +- Po refaktoryzacji rejestracji pluginów lub wykrywania -Testy kontraktów uruchamiają się w CI i nie wymagają prawdziwych kluczy API. +Testy kontraktowe uruchamiają się w CI i nie wymagają prawdziwych kluczy API. ## Dodawanie regresji (wskazówki) -Gdy naprawiasz problem dostawcy/modelu wykryty w live: +Gdy naprawiasz problem providera/modelu wykryty w live: -- Jeśli to możliwe, dodaj regresję bezpieczną dla CI (mock/stub dostawcy albo uchwycenie dokładnej transformacji kształtu żądania) -- Jeśli z natury jest to tylko live (limity szybkości, polityki auth), utrzymaj test live wąski i opt-in przez zmienne środowiskowe -- Preferuj celowanie w najmniejszą warstwę, która wykryje błąd: - - błąd konwersji/odtwarzania żądania dostawcy → test modeli bezpośrednich - - błąd pipeline sesji/historii/narzędzi gateway → live smoke gateway albo bezpieczny dla CI test mock gateway +- Jeśli to możliwe, dodaj regresję bezpieczną dla CI (mock/stub providera albo przechwycenie dokładnej transformacji kształtu żądania) +- Jeśli problem z natury występuje tylko live (rate limit, polityki auth), utrzymaj test live wąski i opt-in przez zmienne env +- Staraj się celować w najmniejszą warstwę, która wychwytuje błąd: + - błąd konwersji/odtwarzania żądania providera → test direct models + - błąd pipeline sesji/historii/narzędzi gateway → gateway live smoke albo bezpieczny dla CI test mock gateway - Zabezpieczenie przechodzenia SecretRef: - - `src/secrets/exec-secret-ref-id-parity.test.ts` wyprowadza jeden przykładowy cel na klasę SecretRef z metadanych rejestru (`listSecretTargetRegistryEntries()`), a następnie potwierdza, że identyfikatory exec z segmentami przejścia są odrzucane. - - Jeśli dodasz nową rodzinę celów SecretRef `includeInPlan` w `src/secrets/target-registry-data.ts`, zaktualizuj `classifyTargetClass` w tym teście. Test celowo kończy się niepowodzeniem dla niesklasyfikowanych identyfikatorów celów, aby nie dało się po cichu pominąć nowych klas. + - `src/secrets/exec-secret-ref-id-parity.test.ts` wyprowadza jeden przykładowy cel dla każdej klasy SecretRef z metadanych rejestru (`listSecretTargetRegistryEntries()`), a następnie potwierdza, że identyfikatory exec segmentów przejścia są odrzucane. + - Jeśli dodasz nową rodzinę celów SecretRef `includeInPlan` w `src/secrets/target-registry-data.ts`, zaktualizuj `classifyTargetClass` w tym teście. Test celowo kończy się niepowodzeniem dla niesklasyfikowanych identyfikatorów celów, aby nowe klasy nie mogły zostać po cichu pominięte. diff --git a/docs/pl/plans/2026-04-05-002-refactor-real-plugin-sdk-workspace-plan.md b/docs/pl/plans/2026-04-05-002-refactor-real-plugin-sdk-workspace-plan.md deleted file mode 100644 index 32446cefe..000000000 --- a/docs/pl/plans/2026-04-05-002-refactor-real-plugin-sdk-workspace-plan.md +++ /dev/null @@ -1,579 +0,0 @@ ---- -date: 2026-04-05T00:00:00Z -status: active -title: 'refactor: Stopniowe przekształcenie plugin-sdk w rzeczywisty pakiet workspace' -type: refactor -x-i18n: - generated_at: "2026-04-07T09:47:02Z" - model: gpt-5.4 - provider: openai - source_hash: ea1ca41846363c506a0db6dbca746e840d7c71ca82bbfc5277af9e2ae7f6b070 - source_path: plans/2026-04-05-002-refactor-real-plugin-sdk-workspace-plan.md - workflow: 15 ---- - -# refactor: Stopniowe przekształcenie plugin-sdk w rzeczywisty pakiet workspace - -## Przegląd - -Ten plan wprowadza rzeczywisty pakiet workspace dla SDK wtyczek w -`packages/plugin-sdk` i używa go do objęcia małej pierwszej fali rozszerzeń -wymuszanymi przez kompilator granicami pakietów. Celem jest sprawienie, aby -niedozwolone importy względne kończyły się błędem przy zwykłym `tsc` dla -wybranego zestawu dołączonych rozszerzeń dostawców, bez wymuszania migracji w -całym repozytorium ani tworzenia ogromnej powierzchni konfliktów merge. - -Kluczowym ruchem przyrostowym jest przez pewien czas równoległe uruchamianie dwóch trybów: - -| Tryb | Kształt importu | Kto go używa | Wymuszanie | -| ----------- | ------------------------ | ------------------------------------- | -------------------------------------------- | -| Tryb starszy | `openclaw/plugin-sdk/*` | wszystkie istniejące rozszerzenia nieobjęte migracją | obecne permisywne zachowanie pozostaje | -| Tryb opt-in | `@openclaw/plugin-sdk/*` | tylko rozszerzenia z pierwszej fali | lokalny dla pakietu `rootDir` + referencje projektów | - -## Ramy problemu - -Obecne repozytorium eksportuje dużą publiczną powierzchnię SDK wtyczek, ale nie jest to rzeczywisty -pakiet workspace. Zamiast tego: - -- główny `tsconfig.json` mapuje `openclaw/plugin-sdk/*` bezpośrednio na - `src/plugin-sdk/*.ts` -- rozszerzenia, które nie zostały objęte poprzednim eksperymentem, nadal współdzielą - to globalne zachowanie aliasów źródła -- dodanie `rootDir` działa tylko wtedy, gdy dozwolone importy SDK przestają rozwiązywać się do surowego - źródła repozytorium - -To oznacza, że repozytorium może opisywać pożądaną politykę granic, ale TypeScript -nie wymusza jej w czysty sposób dla większości rozszerzeń. - -Potrzebujesz ścieżki przyrostowej, która: - -- uczyni `plugin-sdk` rzeczywistym -- przeniesie SDK w kierunku pakietu workspace o nazwie `@openclaw/plugin-sdk` -- zmieni tylko około 10 rozszerzeń w pierwszym PR -- pozostawi resztę drzewa rozszerzeń przy starym schemacie do czasu późniejszego porządkowania -- uniknie przepływu pracy `tsconfig.plugin-sdk.dts.json` + deklaracji generowanych po instalacji jako podstawowego mechanizmu dla wdrożenia pierwszej fali - -## Ślad wymagań - -- R1. Utworzyć rzeczywisty pakiet workspace dla SDK wtyczek w `packages/`. -- R2. Nazwać nowy pakiet `@openclaw/plugin-sdk`. -- R3. Nadać nowemu pakietowi SDK własne `package.json` i `tsconfig.json`. -- R4. Zachować działanie starszych importów `openclaw/plugin-sdk/*` dla rozszerzeń nieobjętych migracją - w czasie okna migracyjnego. -- R5. W pierwszym PR objąć tylko małą pierwszą falę rozszerzeń. -- R6. Rozszerzenia z pierwszej fali muszą być fail-closed dla importów względnych, które wychodzą - poza katalog główny ich pakietu. -- R7. Rozszerzenia z pierwszej fali muszą korzystać z SDK przez zależność pakietu - i referencję projektu TS, a nie przez główne aliasy `paths`. -- R8. Plan musi unikać obowiązkowego, ogólnorepozytoryjnego kroku generowania po instalacji dla - poprawności w edytorze. -- R9. Wdrożenie pierwszej fali musi nadawać się do przeglądu i scalenia jako umiarkowany PR, - a nie refaktor obejmujący ponad 300 plików w całym repozytorium. - -## Granice zakresu - -- Brak pełnej migracji wszystkich dołączonych rozszerzeń w pierwszym PR. -- Brak wymogu usunięcia `src/plugin-sdk` w pierwszym PR. -- Brak wymogu natychmiastowego przełączenia każdej głównej ścieżki build/test na użycie nowego pakietu. -- Brak próby wymuszenia podkreśleń błędów w VS Code dla każdego rozszerzenia nieobjętego migracją. -- Brak szerokiego porządkowania lint dla reszty drzewa rozszerzeń. -- Brak dużych zmian zachowania w czasie wykonywania poza rozwiązywaniem importów, własnością pakietów - i wymuszaniem granic dla rozszerzeń objętych migracją. - -## Kontekst i badania - -### Istotny kod i wzorce - -- `pnpm-workspace.yaml` już zawiera `packages/*` i `extensions/*`, więc nowy - pakiet workspace w `packages/plugin-sdk` pasuje do istniejącego układu - repozytorium. -- Istniejące pakiety workspace, takie jak `packages/memory-host-sdk/package.json` - i `packages/plugin-package-contract/package.json`, już używają lokalnych dla pakietu - map `exports` zakorzenionych w `src/*.ts`. -- Główny `package.json` obecnie publikuje powierzchnię SDK przez `./plugin-sdk` - i eksporty `./plugin-sdk/*` oparte na `dist/plugin-sdk/*.js` oraz - `dist/plugin-sdk/*.d.ts`. -- `src/plugin-sdk/entrypoints.ts` i `scripts/lib/plugin-sdk-entrypoints.json` - już działają jako kanoniczny spis punktów wejścia dla powierzchni SDK. -- Główny `tsconfig.json` obecnie mapuje: - - `openclaw/plugin-sdk` -> `src/plugin-sdk/index.ts` - - `openclaw/plugin-sdk/*` -> `src/plugin-sdk/*.ts` -- Poprzedni eksperyment z granicami pokazał, że lokalny dla pakietu `rootDir` działa w przypadku - niedozwolonych importów względnych dopiero wtedy, gdy dozwolone importy SDK przestają rozwiązywać się do surowego - źródła spoza pakietu rozszerzenia. - -### Zestaw rozszerzeń pierwszej fali - -Ten plan zakłada, że pierwszą falą jest zestaw cięższych od strony dostawców, który z najmniejszym prawdopodobieństwem -wciągnie złożone przypadki brzegowe związane z runtime kanałów: - -- `extensions/anthropic` -- `extensions/exa` -- `extensions/firecrawl` -- `extensions/groq` -- `extensions/mistral` -- `extensions/openai` -- `extensions/perplexity` -- `extensions/tavily` -- `extensions/together` -- `extensions/xai` - -### Spis powierzchni SDK dla pierwszej fali - -Rozszerzenia z pierwszej fali obecnie importują możliwy do opanowania podzbiór ścieżek podrzędnych SDK. -Początkowy pakiet `@openclaw/plugin-sdk` musi pokrywać tylko te: - -- `agent-runtime` -- `cli-runtime` -- `config-runtime` -- `core` -- `image-generation` -- `media-runtime` -- `media-understanding` -- `plugin-entry` -- `plugin-runtime` -- `provider-auth` -- `provider-auth-api-key` -- `provider-auth-login` -- `provider-auth-runtime` -- `provider-catalog-shared` -- `provider-entry` -- `provider-http` -- `provider-model-shared` -- `provider-onboard` -- `provider-stream-family` -- `provider-stream-shared` -- `provider-tools` -- `provider-usage` -- `provider-web-fetch` -- `provider-web-search` -- `realtime-transcription` -- `realtime-voice` -- `runtime-env` -- `secret-input` -- `security-runtime` -- `speech` -- `testing` - -### Wnioski instytucjonalne - -- W tym drzewie roboczym nie było istotnych wpisów `docs/solutions/`. - -### Referencje zewnętrzne - -- Do tego planu nie były potrzebne badania zewnętrzne. Repozytorium już zawiera - odpowiednie wzorce pakietów workspace i eksportów SDK. - -## Kluczowe decyzje techniczne - -- Wprowadzić `@openclaw/plugin-sdk` jako nowy pakiet workspace przy jednoczesnym zachowaniu - starszej powierzchni głównej `openclaw/plugin-sdk/*` podczas migracji. - Uzasadnienie: pozwala to przenieść zestaw rozszerzeń z pierwszej fali na rzeczywiste - rozwiązywanie pakietów bez wymuszania jednoczesnych zmian we wszystkich rozszerzeniach i wszystkich głównych ścieżkach budowania. - -- Użyć dedykowanej bazowej konfiguracji granic opt-in, takiej jak - `extensions/tsconfig.package-boundary.base.json`, zamiast zastępować - istniejącą bazę rozszerzeń dla wszystkich. - Uzasadnienie: repozytorium musi jednocześnie wspierać starszy i opt-in tryb rozszerzeń podczas migracji. - -- Użyć referencji projektów TS z rozszerzeń pierwszej fali do - `packages/plugin-sdk/tsconfig.json` i ustawić - `disableSourceOfProjectReferenceRedirect` dla trybu granic opt-in. - Uzasadnienie: daje to `tsc` rzeczywisty graf pakietów, jednocześnie zniechęcając edytor i kompilator - do przechodzenia z powrotem do surowego źródła. - -- Zachować `@openclaw/plugin-sdk` jako prywatny w pierwszej fali. - Uzasadnienie: bezpośrednim celem jest wewnętrzne wymuszanie granic i bezpieczeństwo migracji, - a nie publikowanie drugiego zewnętrznego kontraktu SDK, zanim powierzchnia stanie się stabilna. - -- Przenieść w pierwszym wycinku implementacji tylko ścieżki podrzędne SDK z pierwszej fali i - zachować mosty zgodności dla reszty. - Uzasadnienie: fizyczne przeniesienie wszystkich 315 plików `src/plugin-sdk/*.ts` w jednym PR to - dokładnie ta powierzchnia konfliktów merge, której ten plan próbuje uniknąć. - -- Nie polegać na `scripts/postinstall-bundled-plugins.mjs` przy budowaniu deklaracji SDK - dla pierwszej fali. - Uzasadnienie: jawne przepływy build/reference są łatwiejsze do zrozumienia i sprawiają, że zachowanie repozytorium jest bardziej przewidywalne. - -## Otwarte pytania - -### Rozstrzygnięte podczas planowania - -- Które rozszerzenia powinny wejść do pierwszej fali? - Użyć wymienionych wyżej 10 rozszerzeń dostawców/wyszukiwania w sieci, ponieważ są - strukturalnie bardziej odizolowane niż cięższe pakiety kanałów. - -- Czy pierwszy PR powinien zastąpić całe drzewo rozszerzeń? - Nie. Pierwszy PR powinien wspierać dwa tryby równolegle i objąć migracją tylko - pierwszą falę. - -- Czy pierwsza fala powinna wymagać budowania deklaracji po instalacji? - Nie. Graf pakietów/referencji powinien być jawny, a CI powinno celowo uruchamiać - odpowiednie lokalne dla pakietu sprawdzanie typów. - -### Odłożone do implementacji - -- Czy pakiet pierwszej fali może wskazywać bezpośrednio na lokalne dla pakietu `src/*.ts` - wyłącznie przez referencje projektów, czy też nadal potrzebny jest mały krok emisji deklaracji - dla pakietu `@openclaw/plugin-sdk`. - To należące do implementacji pytanie dotyczące walidacji grafu TS. - -- Czy główny pakiet `openclaw` powinien natychmiast pośredniczyć w ścieżkach podrzędnych SDK pierwszej fali do - wyników `packages/plugin-sdk`, czy nadal używać generowanych - shimów zgodności w `src/plugin-sdk`. - To szczegół zgodności i kształtu builda zależny od minimalnej - ścieżki implementacji, która utrzyma zielony stan CI. - -## Projekt techniczny wysokiego poziomu - -> To ilustruje zamierzone podejście i stanowi wskazówki kierunkowe do przeglądu, a nie specyfikację implementacji. Agent implementujący powinien traktować to jako kontekst, a nie kod do odtworzenia. - -```mermaid -flowchart TB - subgraph Legacy["Starsze rozszerzenia (bez zmian)"] - L1["extensions/*\nopenclaw/plugin-sdk/*"] - L2["główne ścieżki tsconfig"] - L1 --> L2 - L2 --> L3["src/plugin-sdk/*"] - end - - subgraph OptIn["Rozszerzenia pierwszej fali"] - O1["10 rozszerzeń objętych migracją"] - O2["extensions/tsconfig.package-boundary.base.json"] - O3["rootDir = '.'\nreferencja projektu"] - O4["@openclaw/plugin-sdk"] - O1 --> O2 - O2 --> O3 - O3 --> O4 - end - - subgraph SDK["Nowy pakiet workspace"] - P1["packages/plugin-sdk/package.json"] - P2["packages/plugin-sdk/tsconfig.json"] - P3["packages/plugin-sdk/src/.ts"] - P1 --> P2 - P2 --> P3 - end - - O4 --> SDK -``` - -## Jednostki implementacyjne - -- [ ] **Jednostka 1: Wprowadzenie rzeczywistego pakietu workspace `@openclaw/plugin-sdk`** - -**Cel:** Utworzyć rzeczywisty pakiet workspace dla SDK, który może być właścicielem -powierzchni ścieżek podrzędnych pierwszej fali bez wymuszania migracji całego repozytorium. - -**Wymagania:** R1, R2, R3, R8, R9 - -**Zależności:** Brak - -**Pliki:** - -- Utwórz: `packages/plugin-sdk/package.json` -- Utwórz: `packages/plugin-sdk/tsconfig.json` -- Utwórz: `packages/plugin-sdk/src/index.ts` -- Utwórz: `packages/plugin-sdk/src/*.ts` dla ścieżek podrzędnych SDK z pierwszej fali -- Zmodyfikuj: `pnpm-workspace.yaml` tylko jeśli potrzebne są korekty globów pakietów -- Zmodyfikuj: `package.json` -- Zmodyfikuj: `src/plugin-sdk/entrypoints.ts` -- Zmodyfikuj: `scripts/lib/plugin-sdk-entrypoints.json` -- Test: `src/plugins/contracts/plugin-sdk-workspace-package.contract.test.ts` - -**Podejście:** - -- Dodaj nowy pakiet workspace o nazwie `@openclaw/plugin-sdk`. -- Zacznij tylko od ścieżek podrzędnych SDK z pierwszej fali, a nie od całego drzewa 315 plików. -- Jeśli bezpośrednie przeniesienie punktu wejścia z pierwszej fali stworzyłoby zbyt duży diff, - pierwszy PR może najpierw wprowadzić tę ścieżkę podrzędną w `packages/plugin-sdk/src` jako cienki - wrapper pakietu, a następnie przełączyć źródło prawdy na pakiet w kolejnym PR dla tego klastra ścieżek podrzędnych. -- Użyj ponownie istniejącej mechaniki spisu punktów wejścia, aby powierzchnia pakietu pierwszej fali - była zadeklarowana w jednym kanonicznym miejscu. -- Zachowaj eksporty głównego pakietu dla starszych użytkowników, podczas gdy pakiet workspace - stanie się nowym kontraktem opt-in. - -**Wzorce do naśladowania:** - -- `packages/memory-host-sdk/package.json` -- `packages/plugin-package-contract/package.json` -- `src/plugin-sdk/entrypoints.ts` - -**Scenariusze testowe:** - -- Ścieżka szczęśliwa: pakiet workspace eksportuje każdą ścieżkę podrzędną pierwszej fali wymienioną - w planie i nie brakuje żadnego wymaganego eksportu pierwszej fali. -- Przypadek brzegowy: metadane eksportu pakietu pozostają stabilne, gdy lista wpisów pierwszej fali - jest ponownie generowana lub porównywana z kanonicznym spisem. -- Integracja: starsze eksporty SDK głównego pakietu pozostają obecne po wprowadzeniu nowego - pakietu workspace. - -**Weryfikacja:** - -- Repozytorium zawiera prawidłowy pakiet workspace `@openclaw/plugin-sdk` z - stabilną mapą eksportów pierwszej fali i bez regresji starszych eksportów w głównym - `package.json`. - -- [ ] **Jednostka 2: Dodanie trybu granic TS opt-in dla rozszerzeń z wymuszaniem pakietowym** - -**Cel:** Zdefiniować tryb konfiguracji TS, którego będą używać rozszerzenia objęte migracją, -przy pozostawieniu istniejącego zachowania TS dla rozszerzeń bez zmian dla wszystkich pozostałych. - -**Wymagania:** R4, R6, R7, R8, R9 - -**Zależności:** Jednostka 1 - -**Pliki:** - -- Utwórz: `extensions/tsconfig.package-boundary.base.json` -- Utwórz: `tsconfig.boundary-optin.json` -- Zmodyfikuj: `extensions/xai/tsconfig.json` -- Zmodyfikuj: `extensions/openai/tsconfig.json` -- Zmodyfikuj: `extensions/anthropic/tsconfig.json` -- Zmodyfikuj: `extensions/mistral/tsconfig.json` -- Zmodyfikuj: `extensions/groq/tsconfig.json` -- Zmodyfikuj: `extensions/together/tsconfig.json` -- Zmodyfikuj: `extensions/perplexity/tsconfig.json` -- Zmodyfikuj: `extensions/tavily/tsconfig.json` -- Zmodyfikuj: `extensions/exa/tsconfig.json` -- Zmodyfikuj: `extensions/firecrawl/tsconfig.json` -- Test: `src/plugins/contracts/extension-package-project-boundaries.test.ts` -- Test: `test/extension-package-tsc-boundary.test.ts` - -**Podejście:** - -- Pozostaw `extensions/tsconfig.base.json` dla starszych rozszerzeń. -- Dodaj nową bazową konfigurację opt-in, która: - - ustawia `rootDir: "."` - - referuje `packages/plugin-sdk` - - włącza `composite` - - wyłącza przekierowanie źródła referencji projektu, gdy to potrzebne -- Dodaj dedykowaną konfigurację rozwiązania dla grafu sprawdzania typów pierwszej fali zamiast - przebudowywania głównego projektu TS repozytorium w tym samym PR. - -**Uwaga wykonawcza:** Zacznij od nieprzechodzącego lokalnego dla pakietu kontrolnego sprawdzania typów dla jednego -rozszerzenia objętego migracją, zanim zastosujesz wzorzec do wszystkich 10. - -**Wzorce do naśladowania:** - -- Istniejący wzorzec lokalnego dla pakietu `tsconfig.json` dla rozszerzeń z wcześniejszych - prac nad granicami -- Wzorzec pakietu workspace z `packages/memory-host-sdk` - -**Scenariusze testowe:** - -- Ścieżka szczęśliwa: każde rozszerzenie objęte migracją pomyślnie przechodzi sprawdzanie typów przez - konfigurację TS granic pakietu. -- Ścieżka błędu: kontrolny import względny z `../../src/cli/acp-cli.ts` kończy się - `TS6059` dla rozszerzenia objętego migracją. -- Integracja: rozszerzenia nieobjęte migracją pozostają nietknięte i nie muszą - uczestniczyć w nowej konfiguracji rozwiązania. - -**Weryfikacja:** - -- Istnieje dedykowany graf sprawdzania typów dla 10 rozszerzeń objętych migracją i błędne - importy względne z jednego z nich kończą się błędem przez zwykłe `tsc`. - -- [ ] **Jednostka 3: Migracja rozszerzeń pierwszej fali do `@openclaw/plugin-sdk`** - -**Cel:** Przestawić rozszerzenia pierwszej fali na korzystanie z rzeczywistego pakietu SDK -przez metadane zależności, referencje projektów i importy po nazwie pakietu. - -**Wymagania:** R5, R6, R7, R9 - -**Zależności:** Jednostka 2 - -**Pliki:** - -- Zmodyfikuj: `extensions/anthropic/package.json` -- Zmodyfikuj: `extensions/exa/package.json` -- Zmodyfikuj: `extensions/firecrawl/package.json` -- Zmodyfikuj: `extensions/groq/package.json` -- Zmodyfikuj: `extensions/mistral/package.json` -- Zmodyfikuj: `extensions/openai/package.json` -- Zmodyfikuj: `extensions/perplexity/package.json` -- Zmodyfikuj: `extensions/tavily/package.json` -- Zmodyfikuj: `extensions/together/package.json` -- Zmodyfikuj: `extensions/xai/package.json` -- Zmodyfikuj: importy produkcyjne i testowe w każdym z 10 katalogów głównych rozszerzeń, które - obecnie odwołują się do `openclaw/plugin-sdk/*` - -**Podejście:** - -- Dodaj `@openclaw/plugin-sdk: workspace:*` do `devDependencies` rozszerzeń - z pierwszej fali. -- Zamień w tych pakietach importy `openclaw/plugin-sdk/*` na - `@openclaw/plugin-sdk/*`. -- Zachowaj lokalne importy wewnętrzne rozszerzeń przy lokalnych barrelach, takich jak `./api.ts` i - `./runtime-api.ts`. -- Nie zmieniaj rozszerzeń nieobjętych migracją w tym PR. - -**Wzorce do naśladowania:** - -- Istniejące lokalne barrele importów rozszerzeń (`api.ts`, `runtime-api.ts`) -- Kształt zależności pakietów używany przez inne pakiety workspace `@openclaw/*` - -**Scenariusze testowe:** - -- Ścieżka szczęśliwa: każde zmigrowane rozszerzenie nadal rejestruje się/ładuje przez swoje istniejące - testy wtyczek po przepisaniu importów. -- Przypadek brzegowy: importy SDK tylko testowe w zestawie rozszerzeń objętych migracją nadal rozwiązują się - poprawnie przez nowy pakiet. -- Integracja: zmigrowane rozszerzenia nie wymagają głównych aliasów `openclaw/plugin-sdk/*` - do sprawdzania typów. - -**Weryfikacja:** - -- Rozszerzenia z pierwszej fali budują się i testują względem `@openclaw/plugin-sdk` - bez potrzeby używania starszej ścieżki aliasu głównego SDK. - -- [ ] **Jednostka 4: Zachowanie starszej zgodności podczas częściowej migracji** - -**Cel:** Utrzymać działanie reszty repozytorium, gdy SDK istnieje równocześnie w postaci starszej -i nowego pakietu podczas migracji. - -**Wymagania:** R4, R8, R9 - -**Zależności:** Jednostki 1-3 - -**Pliki:** - -- Zmodyfikuj: `src/plugin-sdk/*.ts` pod kątem shimów zgodności pierwszej fali w razie potrzeby -- Zmodyfikuj: `package.json` -- Zmodyfikuj: elementy builda lub eksportu składające artefakty SDK -- Test: `src/plugins/contracts/plugin-sdk-runtime-api-guardrails.test.ts` -- Test: `src/plugins/contracts/plugin-sdk-index.bundle.test.ts` - -**Podejście:** - -- Zachowaj główne `openclaw/plugin-sdk/*` jako powierzchnię zgodności dla starszych - rozszerzeń i dla zewnętrznych użytkowników, którzy jeszcze nie przechodzą migracji. -- Użyj albo generowanych shimów, albo pośredniczącego routingu eksportów głównych dla - ścieżek podrzędnych pierwszej fali, które zostały przeniesione do `packages/plugin-sdk`. -- Nie próbuj wycofywać głównej powierzchni SDK na tym etapie. - -**Wzorce do naśladowania:** - -- Istniejące generowanie eksportów głównego SDK przez `src/plugin-sdk/entrypoints.ts` -- Istniejąca zgodność eksportów pakietu w głównym `package.json` - -**Scenariusze testowe:** - -- Ścieżka szczęśliwa: starszy import głównego SDK nadal rozwiązuje się dla rozszerzenia - nieobjętego migracją po wprowadzeniu nowego pakietu. -- Przypadek brzegowy: ścieżka podrzędna pierwszej fali działa zarówno przez starszą powierzchnię główną, jak i - przez nową powierzchnię pakietu podczas okna migracyjnego. -- Integracja: testy kontraktowe indeksu/bundle plugin-sdk nadal widzą spójną - publiczną powierzchnię. - -**Weryfikacja:** - -- Repozytorium wspiera zarówno starszy, jak i opt-in tryb korzystania z SDK bez - psucia niezmienionych rozszerzeń. - -- [ ] **Jednostka 5: Dodanie ograniczonego wymuszania i udokumentowanie kontraktu migracji** - -**Cel:** Wdrożyć w CI i wskazówkach dla współtwórców nowe zachowanie dla -pierwszej fali, bez udawania, że całe drzewo rozszerzeń zostało zmigrowane. - -**Wymagania:** R5, R6, R8, R9 - -**Zależności:** Jednostki 1-4 - -**Pliki:** - -- Zmodyfikuj: `package.json` -- Zmodyfikuj: pliki workflow CI, które powinny uruchamiać sprawdzanie typów granic opt-in -- Zmodyfikuj: `AGENTS.md` -- Zmodyfikuj: `docs/plugins/sdk-overview.md` -- Zmodyfikuj: `docs/plugins/sdk-entrypoints.md` -- Zmodyfikuj: `docs/plans/2026-04-05-001-refactor-extension-package-resolution-boundary-plan.md` - -**Podejście:** - -- Dodaj jawny gate pierwszej fali, taki jak dedykowane uruchomienie `tsc -b` dla rozwiązania - `packages/plugin-sdk` plus 10 rozszerzeń objętych migracją. -- Udokumentuj, że repozytorium wspiera teraz zarówno starszy, jak i opt-in tryb rozszerzeń, - oraz że nowe prace nad granicami rozszerzeń powinny preferować nową ścieżkę pakietową. -- Zapisz regułę migracji kolejnych fal, aby późniejsze PR-y mogły dodawać więcej rozszerzeń - bez ponownego rozstrzygania kwestii architektury. - -**Wzorce do naśladowania:** - -- Istniejące testy kontraktowe w `src/plugins/contracts/` -- Istniejące aktualizacje dokumentacji wyjaśniające etapowe migracje - -**Scenariusze testowe:** - -- Ścieżka szczęśliwa: nowy gate sprawdzania typów dla pierwszej fali przechodzi dla pakietu workspace - i rozszerzeń objętych migracją. -- Ścieżka błędu: wprowadzenie nowego niedozwolonego importu względnego w rozszerzeniu objętym migracją - powoduje błąd w ograniczonym gate sprawdzania typów. -- Integracja: CI nie wymaga jeszcze od rozszerzeń nieobjętych migracją spełniania nowego - trybu granic pakietu. - -**Weryfikacja:** - -- Ścieżka wymuszania dla pierwszej fali jest udokumentowana, przetestowana i możliwa do uruchomienia bez - wymuszania migracji całego drzewa rozszerzeń. - -## Wpływ na cały system - -- **Graf interakcji:** ta praca dotyka źródła prawdy SDK, eksportów głównego pakietu, - metadanych pakietów rozszerzeń, układu grafu TS i weryfikacji CI. -- **Propagacja błędów:** głównym zamierzonym trybem błędu stają się błędy TS czasu kompilacji - (`TS6059`) w rozszerzeniach objętych migracją zamiast niestandardowych błędów tylko skryptowych. -- **Ryzyka cyklu życia stanu:** migracja z dwiema powierzchniami wprowadza ryzyko dryfu między - eksportami zgodności w głównym pakiecie a nowym pakietem workspace. -- **Parzystość powierzchni API:** ścieżki podrzędne pierwszej fali muszą pozostać semantycznie identyczne - zarówno przez `openclaw/plugin-sdk/*`, jak i `@openclaw/plugin-sdk/*` podczas - przejścia. -- **Pokrycie integracyjne:** testy jednostkowe nie wystarczą; potrzebne są ograniczone - sprawdzania typów grafu pakietów, aby udowodnić granicę. -- **Niezmienione niezmienniki:** rozszerzenia nieobjęte migracją zachowują swoje obecne zachowanie - w PR 1. Ten plan nie twierdzi, że zapewnia wymuszanie granic importu w całym repozytorium. - -## Ryzyka i zależności - -| Ryzyko | Ograniczenie | -| -------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | -| Pakiet pierwszej fali nadal rozwiązuje się z powrotem do surowego źródła i `rootDir` faktycznie nie działa fail-closed | Uczyń pierwszym krokiem implementacji kontrolę referencji pakietu na jednym rozszerzeniu objętym migracją przed rozszerzeniem na cały zestaw | -| Przeniesienie zbyt dużej części źródła SDK naraz odtwarza pierwotny problem konfliktów merge | Przenieś tylko ścieżki podrzędne pierwszej fali w pierwszym PR i zachowaj mosty zgodności głównego pakietu | -| Starsza i nowa powierzchnia SDK dryfują semantycznie | Zachowaj jeden spis punktów wejścia, dodaj testy kontraktu zgodności i jawnie wymagaj parzystości dwóch powierzchni | -| Główne ścieżki build/test repozytorium przypadkowo zaczynają zależeć od nowego pakietu w niekontrolowany sposób | Użyj dedykowanej konfiguracji rozwiązania opt-in i nie wprowadzaj zmian w ogólnym grafie TS repozytorium w pierwszym PR | - -## Dostarczanie etapowe - -### Faza 1 - -- Wprowadzić `@openclaw/plugin-sdk` -- Zdefiniować powierzchnię ścieżek podrzędnych pierwszej fali -- Udowodnić, że jedno rozszerzenie objęte migracją może działać fail-closed przez `rootDir` - -### Faza 2 - -- Objąć migracją 10 rozszerzeń z pierwszej fali -- Zachować główną zgodność dla wszystkich pozostałych - -### Faza 3 - -- Dodawać kolejne rozszerzenia w późniejszych PR-ach -- Przenosić więcej ścieżek podrzędnych SDK do pakietu workspace -- Wycofać główną zgodność dopiero po zniknięciu zestawu starszych rozszerzeń - -## Uwagi dokumentacyjne / operacyjne - -- Pierwszy PR powinien wyraźnie opisywać siebie jako migrację w dwóch trybach, a nie - jako ukończenie wymuszania w całym repozytorium. -- Przewodnik migracji powinien ułatwiać późniejszym PR-om dodawanie kolejnych rozszerzeń - według tego samego wzorca pakiet/zależność/referencja. - -## Źródła i referencje - -- Poprzedni plan: `docs/plans/2026-04-05-001-refactor-extension-package-resolution-boundary-plan.md` -- Konfiguracja workspace: `pnpm-workspace.yaml` -- Istniejący spis punktów wejścia SDK: `src/plugin-sdk/entrypoints.ts` -- Istniejące eksporty głównego SDK: `package.json` -- Istniejące wzorce pakietów workspace: - - `packages/memory-host-sdk/package.json` - - `packages/plugin-package-contract/package.json` diff --git a/docs/pl/plugins/architecture.md b/docs/pl/plugins/architecture.md index 33849450b..c27026d29 100644 --- a/docs/pl/plugins/architecture.md +++ b/docs/pl/plugins/architecture.md @@ -1,17 +1,17 @@ --- read_when: - - Tworzenie lub debugowanie natywnych pluginów OpenClaw - - Zrozumienie modelu możliwości pluginów lub granic własności - - Praca nad potokiem ładowania pluginów lub rejestrem - - Implementowanie haków runtime dostawców lub pluginów kanałów + - Tworzysz lub debugujesz natywne pluginy OpenClaw + - Chcesz zrozumieć model capability pluginów lub granice własności + - Pracujesz nad pipeline ładowania pluginów lub rejestrem + - Implementujesz hooki runtime dostawcy lub pluginy kanałów sidebarTitle: Internals -summary: 'Wnętrze pluginów: model możliwości, własność, kontrakty, potok ładowania i pomocniki runtime' +summary: 'Wnętrze pluginów: model capability, własność, kontrakty, pipeline ładowania i helpery runtime' title: Wnętrze pluginów x-i18n: - generated_at: "2026-04-08T02:21:29Z" + generated_at: "2026-04-09T01:32:33Z" model: gpt-5.4 provider: openai - source_hash: c40ecf14e2a0b2b8d332027aed939cd61fb4289a489f4cd4c076c96d707d1138 + source_hash: 2575791f835990589219bb06d8ca92e16a8c38b317f0bfe50b421682f253ef18 source_path: plugins/architecture.md workflow: 15 --- @@ -19,168 +19,170 @@ x-i18n: # Wnętrze pluginów - To jest **szczegółowe odniesienie do architektury**. Praktyczne przewodniki znajdziesz tutaj: - - [Instalowanie i używanie pluginów](/pl/tools/plugin) — przewodnik użytkownika - - [Pierwsze kroki](/pl/plugins/building-plugins) — samouczek pierwszego pluginu - - [Pluginy kanałów](/pl/plugins/sdk-channel-plugins) — budowanie kanału wiadomości - - [Pluginy dostawców](/pl/plugins/sdk-provider-plugins) — budowanie dostawcy modeli - - [Przegląd SDK](/pl/plugins/sdk-overview) — mapa importów i API rejestracji + To jest **dogłębna dokumentacja architektury**. Praktyczne przewodniki znajdziesz tutaj: + - [Install and use plugins](/pl/tools/plugin) — przewodnik użytkownika + - [Getting Started](/pl/plugins/building-plugins) — samouczek tworzenia pierwszego pluginu + - [Channel Plugins](/pl/plugins/sdk-channel-plugins) — zbuduj kanał komunikacyjny + - [Provider Plugins](/pl/plugins/sdk-provider-plugins) — zbuduj dostawcę modeli + - [SDK Overview](/pl/plugins/sdk-overview) — mapa importów i API rejestracji Ta strona opisuje wewnętrzną architekturę systemu pluginów OpenClaw. -## Publiczny model możliwości +## Publiczny model capability -Możliwości to publiczny model **natywnych pluginów** w OpenClaw. Każdy -natywny plugin OpenClaw rejestruje się względem co najmniej jednego typu możliwości: +Capabilities to publiczny model **natywnych pluginów** w OpenClaw. Każdy +natywny plugin OpenClaw rejestruje się względem co najmniej jednego typu capability: -| Możliwość | Metoda rejestracji | Przykładowe pluginy | -| --------------------- | ---------------------------------------------- | ---------------------------------- | -| Wnioskowanie tekstowe | `api.registerProvider(...)` | `openai`, `anthropic` | +| Capability | Metoda rejestracji | Przykładowe pluginy | +| ---------------------- | --------------------------------------------- | ---------------------------------- | +| Wnioskowanie tekstowe | `api.registerProvider(...)` | `openai`, `anthropic` | | Backend wnioskowania CLI | `api.registerCliBackend(...)` | `openai`, `anthropic` | -| Mowa | `api.registerSpeechProvider(...)` | `elevenlabs`, `microsoft` | -| Transkrypcja w czasie rzeczywistym | `api.registerRealtimeTranscriptionProvider(...)` | `openai` | -| Głos w czasie rzeczywistym | `api.registerRealtimeVoiceProvider(...)` | `openai` | -| Rozumienie mediów | `api.registerMediaUnderstandingProvider(...)` | `openai`, `google` | -| Generowanie obrazów | `api.registerImageGenerationProvider(...)` | `openai`, `google`, `fal`, `minimax` | -| Generowanie muzyki | `api.registerMusicGenerationProvider(...)` | `google`, `minimax` | -| Generowanie wideo | `api.registerVideoGenerationProvider(...)` | `qwen` | -| Pobieranie z sieci | `api.registerWebFetchProvider(...)` | `firecrawl` | -| Wyszukiwanie w sieci | `api.registerWebSearchProvider(...)` | `google` | -| Kanał / wiadomości | `api.registerChannel(...)` | `msteams`, `matrix` | +| Mowa | `api.registerSpeechProvider(...)` | `elevenlabs`, `microsoft` | +| Transkrypcja realtime | `api.registerRealtimeTranscriptionProvider(...)` | `openai` | +| Głos realtime | `api.registerRealtimeVoiceProvider(...)` | `openai` | +| Rozumienie mediów | `api.registerMediaUnderstandingProvider(...)` | `openai`, `google` | +| Generowanie obrazów | `api.registerImageGenerationProvider(...)` | `openai`, `google`, `fal`, `minimax` | +| Generowanie muzyki | `api.registerMusicGenerationProvider(...)` | `google`, `minimax` | +| Generowanie wideo | `api.registerVideoGenerationProvider(...)` | `qwen` | +| Pobieranie z sieci | `api.registerWebFetchProvider(...)` | `firecrawl` | +| Wyszukiwanie w sieci | `api.registerWebSearchProvider(...)` | `google` | +| Kanał / komunikacja | `api.registerChannel(...)` | `msteams`, `matrix` | -Plugin, który rejestruje zero możliwości, ale udostępnia hooki, narzędzia lub -usługi, jest **starszym pluginem tylko z hookami**. Ten wzorzec nadal jest w pełni wspierany. +Plugin, który rejestruje zero capabilities, ale dostarcza hooki, narzędzia lub +usługi, jest pluginem **legacy hook-only**. Ten wzorzec jest nadal w pełni wspierany. -### Stanowisko wobec zgodności zewnętrznej +### Stan kompatybilności zewnętrznej -Model możliwości jest wdrożony w rdzeniu i używany przez pluginy -bundlowane/natywne już dziś, ale zgodność zewnętrznych pluginów nadal wymaga -wyższego progu niż „jest eksportowane, więc jest zamrożone”. +Model capability jest wdrożony w core i używany dziś przez dołączone/natywne +pluginy, ale kompatybilność z pluginami zewnętrznymi nadal wymaga wyższego progu +niż „jest eksportowane, więc jest zamrożone”. -Obecne wytyczne: +Aktualne wytyczne: -- **istniejące pluginy zewnętrzne:** utrzymuj działanie integracji opartych na hookach; traktuj - to jako bazowy poziom zgodności -- **nowe pluginy bundlowane/natywne:** preferuj jawną rejestrację możliwości zamiast - dostępu przez reach-in specyficzny dla dostawcy lub nowych projektów wyłącznie hookowych -- **zewnętrzne pluginy przyjmujące rejestrację możliwości:** dozwolone, ale - traktuj powierzchnie pomocnicze specyficzne dla możliwości jako rozwijające się, chyba że dokumentacja jawnie oznacza - dany kontrakt jako stabilny +- **istniejące pluginy zewnętrzne:** zachowuj działanie integracji opartych na hookach; traktuj + to jako bazowy poziom kompatybilności +- **nowe dołączone/natywne pluginy:** preferuj jawną rejestrację capability zamiast + zależności od konkretnego dostawcy lub nowych projektów hook-only +- **pluginy zewnętrzne przyjmujące rejestrację capability:** dozwolone, ale traktuj + helpery specyficzne dla capability jako rozwijające się, chyba że dokumentacja + wyraźnie oznacza kontrakt jako stabilny Praktyczna zasada: -- API rejestracji możliwości to zamierzony kierunek -- starsze hooki pozostają najbezpieczniejszą ścieżką bez zrywania zgodności dla pluginów zewnętrznych w czasie +- API rejestracji capability jest docelowym kierunkiem +- legacy hooks pozostają najbezpieczniejszą ścieżką bez ryzyka złamania dla pluginów zewnętrznych podczas przejścia -- eksportowane podścieżki pomocnicze nie są sobie równe; preferuj wąski udokumentowany - kontrakt, a nie przypadkowe eksporty pomocnicze +- eksportowane subścieżki helperów nie są równoważne; preferuj wąski, udokumentowany + kontrakt, a nie przypadkowe eksporty helperów ### Kształty pluginów -OpenClaw klasyfikuje każdy załadowany plugin do jednego z kształtów na podstawie jego rzeczywistego -zachowania rejestracyjnego (a nie tylko statycznych metadanych): +OpenClaw klasyfikuje każdy załadowany plugin do jednego z kształtów na podstawie +jego rzeczywistego zachowania rejestracyjnego (a nie tylko statycznych metadanych): -- **plain-capability** -- rejestruje dokładnie jeden typ możliwości (na przykład - plugin tylko dostawcy, taki jak `mistral`) -- **hybrid-capability** -- rejestruje wiele typów możliwości (na przykład - `openai` obsługuje wnioskowanie tekstowe, mowę, rozumienie mediów oraz generowanie +- **plain-capability** -- rejestruje dokładnie jeden typ capability (na przykład + plugin tylko-dostawca, taki jak `mistral`) +- **hybrid-capability** -- rejestruje wiele typów capability (na przykład + `openai` obsługuje wnioskowanie tekstowe, mowę, rozumienie mediów i generowanie obrazów) -- **hook-only** -- rejestruje tylko hooki (typowane lub niestandardowe), bez możliwości, - narzędzi, poleceń ani usług -- **non-capability** -- rejestruje narzędzia, polecenia, usługi lub trasy, ale nie - możliwości +- **hook-only** -- rejestruje wyłącznie hooki (typowane lub niestandardowe), bez capabilities, + narzędzi, komend ani usług +- **non-capability** -- rejestruje narzędzia, komendy, usługi lub trasy, ale bez + capabilities -Użyj `openclaw plugins inspect `, aby zobaczyć kształt pluginu i rozkład -możliwości. Szczegóły znajdziesz w [odniesieniu do CLI](/cli/plugins#inspect). +Użyj `openclaw plugins inspect `, aby zobaczyć kształt pluginu i podział capability. +Szczegóły znajdziesz w [CLI reference](/cli/plugins#inspect). -### Starsze hooki +### Legacy hooks -Hook `before_agent_start` pozostaje wspierany jako ścieżka zgodności dla -pluginów tylko z hookami. Starsze rzeczywiste pluginy nadal od niego zależą. +Hook `before_agent_start` pozostaje wspierany jako ścieżka kompatybilności dla +pluginów hook-only. Legacy pluginy używane w praktyce nadal od niego zależą. Kierunek: -- utrzymać jego działanie -- udokumentować go jako starszy -- preferować `before_model_resolve` do pracy nad nadpisywaniem modelu/dostawcy -- preferować `before_prompt_build` do modyfikacji promptu -- usunąć dopiero wtedy, gdy rzeczywiste użycie spadnie, a pokrycie fixture’ów potwierdzi bezpieczeństwo migracji +- zachowaj jego działanie +- dokumentuj go jako legacy +- dla pracy z nadpisywaniem modelu/dostawcy preferuj `before_model_resolve` +- dla modyfikacji promptów preferuj `before_prompt_build` +- usuń go dopiero wtedy, gdy realne użycie spadnie, a pokrycie przez fixture potwierdzi + bezpieczeństwo migracji -### Sygnały zgodności +### Sygnały kompatybilności -Po uruchomieniu `openclaw doctor` albo `openclaw plugins inspect ` możesz zobaczyć +Po uruchomieniu `openclaw doctor` lub `openclaw plugins inspect ` możesz zobaczyć jedną z tych etykiet: -| Sygnał | Znaczenie | -| -------------------------- | ----------------------------------------------------------- | +| Sygnał | Znaczenie | +| -------------------------- | ------------------------------------------------------------ | | **config valid** | Konfiguracja parsuje się poprawnie, a pluginy są rozwiązywane | | **compatibility advisory** | Plugin używa wspieranego, ale starszego wzorca (np. `hook-only`) | -| **legacy warning** | Plugin używa `before_agent_start`, które jest przestarzałe | -| **hard error** | Konfiguracja jest nieprawidłowa albo plugin nie załadował się | +| **legacy warning** | Plugin używa `before_agent_start`, który jest przestarzały | +| **hard error** | Konfiguracja jest nieprawidłowa lub plugin nie załadował się | Ani `hook-only`, ani `before_agent_start` nie zepsują dziś Twojego pluginu -- -`hook-only` ma charakter doradczy, a `before_agent_start` wywołuje tylko ostrzeżenie. Te -sygnały pojawiają się także w `openclaw status --all` i `openclaw plugins doctor`. +`hook-only` ma charakter informacyjny, a `before_agent_start` wywołuje tylko ostrzeżenie. Te +sygnały pojawiają się również w `openclaw status --all` i `openclaw plugins doctor`. ## Przegląd architektury System pluginów OpenClaw ma cztery warstwy: 1. **Manifest + wykrywanie** - OpenClaw znajduje kandydackie pluginy na podstawie skonfigurowanych ścieżek, korzeni - workspace, globalnych korzeni rozszerzeń i bundlowanych rozszerzeń. Wykrywanie najpierw odczytuje natywne + OpenClaw znajduje kandydackie pluginy na podstawie skonfigurowanych ścieżek, katalogów + workspace, globalnych katalogów rozszerzeń i dołączonych rozszerzeń. Wykrywanie najpierw odczytuje natywne manifesty `openclaw.plugin.json` oraz wspierane manifesty bundle. 2. **Włączanie + walidacja** - Rdzeń decyduje, czy wykryty plugin jest włączony, wyłączony, zablokowany, czy + Core decyduje, czy wykryty plugin jest włączony, wyłączony, zablokowany czy wybrany do ekskluzywnego slotu, takiego jak pamięć. 3. **Ładowanie runtime** - Natywne pluginy OpenClaw są ładowane w tym samym procesie przez jiti i rejestrują - możliwości w centralnym rejestrze. Zgodne bundle są normalizowane do + Natywne pluginy OpenClaw są ładowane wewnątrz procesu przez jiti i rejestrują + capabilities w centralnym rejestrze. Kompatybilne bundle są normalizowane do rekordów rejestru bez importowania kodu runtime. -4. **Konsumpcja powierzchni** +4. **Korzystanie z powierzchni** Reszta OpenClaw odczytuje rejestr, aby udostępniać narzędzia, kanały, konfigurację - dostawców, hooki, trasy HTTP, polecenia CLI i usługi. + dostawców, hooki, trasy HTTP, komendy CLI i usługi. -Konkretnie dla CLI pluginów, wykrywanie poleceń głównych jest podzielone na dwie fazy: +W szczególności dla pluginowego CLI wykrywanie komend głównych jest podzielone na dwa etapy: - metadane czasu parsowania pochodzą z `registerCli(..., { descriptors: [...] })` -- właściwy moduł CLI pluginu może pozostać leniwy i zarejestrować się przy pierwszym wywołaniu +- właściwy moduł CLI pluginu może pozostać lazy i zarejestrować się przy pierwszym wywołaniu -Dzięki temu kod CLI należący do pluginu pozostaje w pluginie, a OpenClaw nadal może -zarezerwować nazwy poleceń głównych przed parsowaniem. +Dzięki temu kod CLI należący do pluginu pozostaje w pluginie, a jednocześnie OpenClaw może +zarezerwować nazwy komend głównych przed parsowaniem. -Istotna granica projektowa: +Ważna granica projektowa: - wykrywanie + walidacja konfiguracji powinny działać na podstawie **metadanych manifestu/schematu** bez wykonywania kodu pluginu - natywne zachowanie runtime pochodzi ze ścieżki `register(api)` modułu pluginu Ten podział pozwala OpenClaw walidować konfigurację, wyjaśniać brakujące/wyłączone pluginy i -budować podpowiedzi UI/schematu zanim pełne runtime stanie się aktywne. +budować wskazówki dla UI/schematu, zanim pełny runtime stanie się aktywny. -### Pluginy kanałów i współdzielone narzędzie message +### Pluginy kanałów i współdzielone narzędzie wiadomości Pluginy kanałów nie muszą rejestrować osobnego narzędzia send/edit/react dla -zwykłych działań czatu. OpenClaw utrzymuje jedno współdzielone narzędzie `message` w rdzeniu, a -pluginy kanałów odpowiadają za specyficzne dla kanału wykrywanie i wykonanie za nim. +zwykłych działań czatu. OpenClaw utrzymuje jedno współdzielone narzędzie `message` w core, a +pluginy kanałów obsługują wykrywanie i wykonanie specyficzne dla kanału za nim. -Obecna granica jest następująca: +Obecna granica wygląda tak: -- rdzeń odpowiada za host współdzielonego narzędzia `message`, integrację promptu, księgowanie - sesji/wątków i dyspozycję wykonania -- pluginy kanałów odpowiadają za wykrywanie działań w zakresie, wykrywanie możliwości i wszelkie +- core zarządza hostem współdzielonego narzędzia `message`, podłączaniem promptów, prowadzeniem + sesji/wątków i dyspozycją wykonania +- pluginy kanałów obsługują wykrywanie działań z zakresem, wykrywanie capabilities i wszelkie fragmenty schematu specyficzne dla kanału -- pluginy kanałów odpowiadają za gramatykę konwersacji sesji specyficzną dla dostawcy, na przykład - za to, jak identyfikatory konwersacji kodują identyfikatory wątków lub dziedziczą po konwersacjach nadrzędnych +- pluginy kanałów obsługują gramatykę konwersacji sesji specyficzną dla dostawcy, np. + sposób, w jaki identyfikatory konwersacji kodują identyfikatory wątków lub dziedziczą po + konwersacjach nadrzędnych - pluginy kanałów wykonują końcowe działanie przez swój adapter działań Dla pluginów kanałów powierzchnią SDK jest `ChannelMessageActionAdapter.describeMessageTool(...)`. To ujednolicone wywołanie wykrywania -pozwala pluginowi zwrócić widoczne działania, możliwości i wkład do schematu -razem, aby te elementy nie zaczęły się rozjeżdżać. +pozwala pluginowi zwrócić widoczne działania, capabilities i wkłady do schematu +razem, tak aby te elementy nie rozjeżdżały się z czasem. -Rdzeń przekazuje zakres runtime do tego kroku wykrywania. Ważne pola to: +Core przekazuje zakres runtime do tego kroku wykrywania. Ważne pola obejmują: - `accountId` - `currentChannelId` @@ -189,124 +191,126 @@ Rdzeń przekazuje zakres runtime do tego kroku wykrywania. Ważne pola to: - `sessionKey` - `sessionId` - `agentId` -- zaufany przychodzący `requesterSenderId` +- zaufane przychodzące `requesterSenderId` -Ma to znaczenie dla pluginów zależnych od kontekstu. Kanał może ukrywać lub ujawniać -działania message na podstawie aktywnego konta, bieżącego pokoju/wątku/wiadomości albo -zaufanej tożsamości nadawcy żądania bez twardego kodowania gałęzi specyficznych dla kanału w -narzędziu rdzeniowym `message`. +To ma znaczenie dla pluginów zależnych od kontekstu. Kanał może ukrywać lub ujawniać +działania wiadomości na podstawie aktywnego konta, bieżącego pokoju/wątku/wiadomości lub +zaufanej tożsamości nadawcy, bez hardcodowania gałęzi specyficznych dla kanału w +core'owym narzędziu `message`. -Dlatego zmiany routingu embedded-runner nadal należą do pracy pluginu: runner jest -odpowiedzialny za przekazywanie bieżącej tożsamości czatu/sesji do granicy wykrywania pluginu, -aby współdzielone narzędzie `message` ujawniało właściwą powierzchnię należącą do kanału -dla bieżącego kroku. +To dlatego zmiany routingu embedded-runner nadal są pracą po stronie pluginu: runner +odpowiada za przekazanie bieżącej tożsamości czatu/sesji do granicy wykrywania pluginu, +tak aby współdzielone narzędzie `message` ujawniało właściwą powierzchnię należącą do kanału +dla bieżącej tury. -W przypadku pomocników wykonania należących do kanału, bundlowane pluginy powinny utrzymywać runtime wykonania -we własnych modułach rozszerzeń. Rdzeń nie odpowiada już za runtime działań wiadomości Discord, -Slack, Telegram ani WhatsApp w `src/agents/tools`. -Nie publikujemy oddzielnych podścieżek `plugin-sdk/*-action-runtime`, a bundlowane +W przypadku helperów wykonania należących do kanału dołączone pluginy powinny trzymać runtime +wykonania we własnych modułach rozszerzeń. Core nie zarządza już runtime'ami działań wiadomości dla +Discord, Slack, Telegram ani WhatsApp w `src/agents/tools`. +Nie publikujemy osobnych subścieżek `plugin-sdk/*-action-runtime`, a dołączone pluginy powinny importować własny lokalny kod runtime bezpośrednio ze swoich -modułów rozszerzeń. +modułów należących do rozszerzenia. -Ta sama granica dotyczy ogólnie nazwanych przez dostawcę szczelin SDK: rdzeń nie powinien -importować wygodnych barrelów specyficznych dla kanału dla Slack, Discord, Signal, -WhatsApp ani podobnych rozszerzeń. Jeśli rdzeń potrzebuje jakiegoś zachowania, powinien albo -skorzystać z własnego barrela `api.ts` / `runtime-api.ts` bundlowanego pluginu, albo awansować tę potrzebę -do wąskiej ogólnej możliwości we współdzielonym SDK. +Ta sama granica dotyczy ogólnie nazwanych według dostawców granic SDK: core nie powinien +importować wygodnych barrelów specyficznych dla kanałów takich jak Slack, Discord, Signal, +WhatsApp ani podobnych rozszerzeń. Jeśli core potrzebuje danego zachowania, powinien albo +korzystać z własnego `api.ts` / `runtime-api.ts` dołączonego pluginu, albo promować tę potrzebę +do wąskiej, ogólnej capability w współdzielonym SDK. -Konkretnie dla ankiet istnieją dwie ścieżki wykonania: +W przypadku ankiet istnieją obecnie dwie ścieżki wykonania: -- `outbound.sendPoll` to współdzielona baza dla kanałów, które pasują do wspólnego +- `outbound.sendPoll` jest współdzieloną bazą dla kanałów pasujących do wspólnego modelu ankiet -- `actions.handleAction("poll")` to preferowana ścieżka dla semantyki ankiet specyficznej dla kanału - albo dodatkowych parametrów ankiet +- `actions.handleAction("poll")` jest preferowaną ścieżką dla semantyki ankiet + specyficznej dla kanału lub dodatkowych parametrów ankiet -Rdzeń odracza teraz współdzielone parsowanie ankiet do momentu, gdy dyspozycja ankiety pluginu odrzuci -działanie, dzięki czemu obsługujące ankiety należące do pluginu mogą akceptować pola ankiet specyficzne dla kanału -bez wcześniejszego blokowania przez ogólny parser ankiet. +Core odracza teraz współdzielone parsowanie ankiet do momentu, aż pluginowa dyspozycja ankiety +odrzuci działanie, tak aby należące do pluginu handlery ankiet mogły akceptować pola ankiet +specyficzne dla kanału bez wcześniejszego zablokowania przez ogólny parser ankiet. -Pełną sekwencję uruchamiania znajdziesz w [Potoku ładowania](#load-pipeline). +Pełną sekwencję uruchamiania znajdziesz w [Load pipeline](#load-pipeline). -## Model własności możliwości +## Model własności capability OpenClaw traktuje natywny plugin jako granicę własności dla **firmy** albo -**funkcji**, a nie jako zbiór niezwiązanych integracji. +**funkcji**, a nie jako worek na niepowiązane integracje. To oznacza, że: -- plugin firmy powinien zwykle posiadać wszystkie powierzchnie OpenClaw-facing tej firmy -- plugin funkcji powinien zwykle posiadać pełną powierzchnię funkcji, którą wprowadza -- kanały powinny korzystać ze współdzielonych możliwości rdzenia zamiast doraźnie ponownie implementować - zachowanie dostawcy +- plugin firmowy powinien zwykle obsługiwać wszystkie powierzchnie OpenClaw skierowane do tej firmy +- plugin funkcjonalny powinien zwykle obsługiwać pełną powierzchnię funkcji, którą wprowadza +- kanały powinny korzystać ze współdzielonych capabilities core zamiast implementować + zachowanie dostawców ad hoc Przykłady: -- bundlowany plugin `openai` obsługuje zachowanie dostawcy modeli OpenAI oraz OpenAI - speech + realtime-voice + media-understanding + image-generation -- bundlowany plugin `elevenlabs` obsługuje zachowanie mowy ElevenLabs -- bundlowany plugin `microsoft` obsługuje zachowanie mowy Microsoft -- bundlowany plugin `google` obsługuje zachowanie dostawcy modeli Google oraz Google +- dołączony plugin `openai` obsługuje zachowanie dostawcy modeli OpenAI oraz + zachowanie OpenAI dla mowy + realtime voice + rozumienia mediów + generowania obrazów +- dołączony plugin `elevenlabs` obsługuje zachowanie mowy ElevenLabs +- dołączony plugin `microsoft` obsługuje zachowanie mowy Microsoft +- dołączony plugin `google` obsługuje zachowanie dostawcy modeli Google oraz Google media-understanding + image-generation + web-search -- bundlowany plugin `firecrawl` obsługuje zachowanie web-fetch Firecrawl -- bundlowane pluginy `minimax`, `mistral`, `moonshot` i `zai` obsługują swoje +- dołączony plugin `firecrawl` obsługuje zachowanie web-fetch Firecrawl +- dołączone pluginy `minimax`, `mistral`, `moonshot` i `zai` obsługują własne backendy media-understanding -- plugin `voice-call` jest pluginem funkcji: obsługuje transport połączeń, narzędzia, - CLI, trasy i mostkowanie strumieni mediów Twilio, ale korzysta ze współdzielonych możliwości speech - oraz realtime-transcription i realtime-voice zamiast bezpośrednio importować pluginy dostawców +- dołączony plugin `qwen` obsługuje zachowanie dostawcy tekstu Qwen oraz + media-understanding i video-generation +- plugin `voice-call` jest pluginem funkcjonalnym: obsługuje transport połączeń, narzędzia, + CLI, trasy i mostkowanie strumieni mediów Twilio, ale korzysta ze współdzielonych capabilities speech + oraz realtime-transcription i realtime-voice zamiast importować pluginy dostawców bezpośrednio -Zamierzony stan końcowy jest następujący: +Docelowy stan to: -- OpenAI znajduje się w jednym pluginie, nawet jeśli obejmuje modele tekstowe, mowę, obrazy i +- OpenAI znajduje się w jednym pluginie nawet wtedy, gdy obejmuje modele tekstowe, mowę, obrazy i przyszłe wideo -- inny dostawca może zrobić to samo dla własnego obszaru -- kanały nie obchodzą szczegóły tego, który plugin dostawcy obsługuje danego providera; korzystają ze - współdzielonego kontraktu możliwości udostępnianego przez rdzeń +- inny dostawca może zrobić to samo dla własnej powierzchni +- kanały nie obchodzą, który plugin dostawcy obsługuje provider; korzystają ze + współdzielonego kontraktu capability udostępnionego przez core To jest kluczowe rozróżnienie: - **plugin** = granica własności -- **możliwość** = kontrakt rdzenia, który może być implementowany lub używany przez wiele pluginów +- **capability** = kontrakt core, który może być implementowany lub używany przez wiele pluginów -Jeśli więc OpenClaw doda nową domenę, taką jak wideo, pierwszym pytaniem nie jest -„który dostawca powinien na sztywno obsłużyć wideo?”. Pierwsze pytanie brzmi: „jaki jest -rdzeniowy kontrakt możliwości wideo?”. Gdy ten kontrakt istnieje, pluginy dostawców +Jeśli więc OpenClaw dodaje nową domenę, taką jak wideo, pierwsze pytanie nie brzmi +„który dostawca powinien na sztywno obsłużyć wideo?”. Pierwsze pytanie brzmi „jaki jest +kontrakt core capability dla wideo?”. Gdy taki kontrakt istnieje, pluginy dostawców mogą się względem niego rejestrować, a pluginy kanałów/funkcji mogą z niego korzystać. -Jeśli możliwość jeszcze nie istnieje, właściwy ruch to zwykle: +Jeśli capability jeszcze nie istnieje, właściwym krokiem jest zwykle: -1. zdefiniować brakującą możliwość w rdzeniu -2. udostępnić ją przez API/runtime pluginów w sposób typowany -3. podłączyć kanały/funkcje do tej możliwości -4. pozwolić pluginom dostawców rejestrować implementacje +1. zdefiniować brakującą capability w core +2. udostępnić ją w typowany sposób przez API/runtime pluginu +3. podłączyć kanały/funkcje do tej capability +4. pozwolić pluginom dostawców zarejestrować implementacje -Dzięki temu własność pozostaje jawna, a jednocześnie unika się zachowania rdzenia zależnego od -jednego dostawcy albo jednorazowej ścieżki kodu specyficznej dla pluginu. +To utrzymuje jawną własność, jednocześnie unikając zachowania core zależnego od +jednego dostawcy lub jednorazowej ścieżki kodu specyficznej dla pluginu. -### Warstwowanie możliwości +### Warstwowanie capability -Użyj tego modelu mentalnego przy decydowaniu, gdzie powinien znajdować się kod: +Używaj tego modelu mentalnego przy podejmowaniu decyzji, gdzie powinien znajdować się kod: -- **warstwa możliwości rdzenia**: współdzielona orkiestracja, polityka, fallback, zasady +- **warstwa capability core**: współdzielona orkiestracja, polityka, fallback, zasady łączenia konfiguracji, semantyka dostarczania i typowane kontrakty - **warstwa pluginu dostawcy**: API specyficzne dla dostawcy, auth, katalogi modeli, synteza mowy, generowanie obrazów, przyszłe backendy wideo, endpointy użycia -- **warstwa pluginu kanału/funkcji**: integracja Slack/Discord/voice-call itd., - która zużywa możliwości rdzenia i prezentuje je na powierzchni +- **warstwa pluginu kanału/funkcji**: integracja Slack/Discord/voice-call/etc., + która korzysta z capabilities core i wystawia je na zewnątrz -Na przykład TTS ma następującą strukturę: +Na przykład TTS ma taki kształt: -- rdzeń obsługuje politykę TTS podczas odpowiedzi, kolejność fallback, preferencje i dostarczanie na kanał +- core zarządza polityką TTS przy odpowiedzi, kolejnością fallbacków, preferencjami i dostarczaniem do kanału - `openai`, `elevenlabs` i `microsoft` obsługują implementacje syntezy -- `voice-call` korzysta z pomocnika runtime TTS dla telefonii +- `voice-call` korzysta z helpera runtime TTS dla telefonii -Ten sam wzorzec należy preferować dla przyszłych możliwości. +Ten sam wzorzec powinien być preferowany dla przyszłych capabilities. -### Przykład pluginu firmy z wieloma możliwościami +### Przykład firmowego pluginu z wieloma capabilities -Plugin firmy powinien sprawiać wrażenie spójnego z zewnątrz. Jeśli OpenClaw ma współdzielone -kontrakty dla modeli, mowy, transkrypcji w czasie rzeczywistym, głosu w czasie rzeczywistym, rozumienia -mediów, generowania obrazów, generowania wideo, web fetch i web search, -dostawca może posiadać wszystkie swoje powierzchnie w jednym miejscu: +Plugin firmowy powinien z zewnątrz sprawiać spójne wrażenie. Jeśli OpenClaw ma współdzielone +kontrakty dla modeli, mowy, transkrypcji realtime, głosu realtime, rozumienia mediów, +generowania obrazów, generowania wideo, web fetch i web search, dostawca może +obsługiwać wszystkie swoje powierzchnie w jednym miejscu: ```ts import type { OpenClawPluginDefinition } from "openclaw/plugin-sdk/plugin-entry"; @@ -321,12 +325,12 @@ const plugin: OpenClawPluginDefinition = { register(api) { api.registerProvider({ id: "exampleai", - // hooki auth/katalogu modeli/runtime + // auth/model catalog/runtime hooks }); api.registerSpeechProvider({ id: "exampleai", - // konfiguracja mowy dostawcy — zaimplementuj bezpośrednio interfejs SpeechProviderPlugin + // vendor speech config — implement the SpeechProviderPlugin interface directly }); api.registerMediaUnderstandingProvider({ @@ -351,7 +355,7 @@ const plugin: OpenClawPluginDefinition = { api.registerWebSearchProvider( createPluginBackedWebSearchProvider({ id: "exampleai-search", - // logika poświadczeń + pobierania + // credential + fetch logic }), ); }, @@ -360,31 +364,31 @@ const plugin: OpenClawPluginDefinition = { export default plugin; ``` -Nie są istotne dokładne nazwy pomocników. Liczy się kształt: +Liczą się nie tyle dokładne nazwy helperów, co sam kształt: -- jeden plugin posiada powierzchnię dostawcy -- rdzeń nadal posiada kontrakty możliwości -- kanały i pluginy funkcji korzystają z pomocników `api.runtime.*`, a nie z kodu dostawcy -- testy kontraktowe mogą potwierdzić, że plugin zarejestrował możliwości, które - deklaruje jako własne +- jeden plugin obsługuje powierzchnię dostawcy +- core nadal obsługuje kontrakty capability +- kanały i pluginy funkcjonalne korzystają z helperów `api.runtime.*`, a nie z kodu dostawcy +- testy kontraktów mogą potwierdzić, że plugin zarejestrował capabilities, których + twierdzi, że jest właścicielem -### Przykład możliwości: rozumienie wideo +### Przykład capability: rozumienie wideo OpenClaw już traktuje rozumienie obrazów/audio/wideo jako jedną współdzieloną -możliwość. Ten sam model własności ma tu zastosowanie: +capability. Ten sam model własności ma tu zastosowanie: -1. rdzeń definiuje kontrakt media-understanding +1. core definiuje kontrakt media-understanding 2. pluginy dostawców rejestrują `describeImage`, `transcribeAudio` i - `describeVideo` w zależności od potrzeb -3. kanały i pluginy funkcji korzystają ze współdzielonego zachowania rdzenia zamiast - podpinać się bezpośrednio do kodu dostawcy + `describeVideo`, stosownie do możliwości +3. kanały i pluginy funkcjonalne korzystają ze współdzielonego zachowania core zamiast + bezpośrednio podłączać kod dostawcy -To zapobiega wbudowywaniu założeń jednego dostawcy dotyczących wideo do rdzenia. Plugin posiada -powierzchnię dostawcy; rdzeń posiada kontrakt możliwości i zachowanie fallback. +To zapobiega wpisaniu założeń jednego dostawcy o wideo na stałe do core. Plugin obsługuje +powierzchnię dostawcy; core obsługuje kontrakt capability i zachowanie fallback. -Generowanie wideo już używa tej samej sekwencji: rdzeń posiada typowany -kontrakt możliwości i pomocnik runtime, a pluginy dostawców rejestrują -implementacje `api.registerVideoGenerationProvider(...)` względem niego. +Generowanie wideo używa już tej samej sekwencji: core obsługuje typowany +kontrakt capability i helper runtime, a pluginy dostawców rejestrują +implementacje `api.registerVideoGenerationProvider(...)`. Potrzebujesz konkretnej listy wdrożeniowej? Zobacz [Capability Cookbook](/pl/plugins/architecture). @@ -392,31 +396,31 @@ Potrzebujesz konkretnej listy wdrożeniowej? Zobacz ## Kontrakty i egzekwowanie Powierzchnia API pluginów jest celowo typowana i scentralizowana w -`OpenClawPluginApi`. Ten kontrakt definiuje wspierane punkty rejestracji i -pomocniki runtime, na których plugin może polegać. +`OpenClawPluginApi`. Ten kontrakt definiuje wspierane punkty rejestracji oraz +helpery runtime, na których plugin może polegać. Dlaczego to ważne: - autorzy pluginów dostają jeden stabilny wewnętrzny standard -- rdzeń może odrzucić duplikaty własności, na przykład dwa pluginy rejestrujące ten sam +- core może odrzucać zduplikowaną własność, na przykład dwa pluginy rejestrujące ten sam identyfikator dostawcy -- uruchamianie może pokazać praktyczną diagnostykę dla błędnej rejestracji -- testy kontraktowe mogą egzekwować własność bundlowanych pluginów i zapobiegać cichemu dryfowi +- podczas uruchamiania można pokazać użyteczne diagnostyki dla nieprawidłowej rejestracji +- testy kontraktów mogą egzekwować własność dołączonych pluginów i zapobiegać cichemu driftowi Istnieją dwie warstwy egzekwowania: -1. **egzekwowanie rejestracji runtime** +1. **egzekwowanie rejestracji w runtime** Rejestr pluginów waliduje rejestracje podczas ładowania pluginów. Przykłady: - duplikaty identyfikatorów dostawców, duplikaty identyfikatorów dostawców mowy i błędne - rejestracje generują diagnostykę pluginów zamiast niezdefiniowanego zachowania. -2. **testy kontraktowe** - Bundlowane pluginy są przechwytywane w rejestrach kontraktów podczas uruchomień testów, aby - OpenClaw mógł jawnie potwierdzać własność. Dziś jest to używane dla - dostawców modeli, dostawców mowy, dostawców web search i własności bundlowanej rejestracji. + zduplikowane identyfikatory providerów, zduplikowane identyfikatory dostawców mowy i nieprawidłowe + rejestracje powodują diagnostyki pluginów zamiast niezdefiniowanego zachowania. +2. **testy kontraktów** + Dołączone pluginy są przechwytywane w rejestrach kontraktów podczas uruchamiania testów, aby + OpenClaw mógł jawnie potwierdzać własność. Obecnie używa się tego dla + providerów modeli, dostawców mowy, dostawców web search i własności rejestracji dołączonych pluginów. -Praktyczny efekt jest taki, że OpenClaw z góry wie, który plugin odpowiada za którą -powierzchnię. To pozwala rdzeniowi i kanałom płynnie się składać, bo własność jest -zadeklarowana, typowana i testowalna, a nie ukryta. +Praktyczny efekt jest taki, że OpenClaw wie z góry, który plugin obsługuje którą +powierzchnię. Dzięki temu core i kanały mogą składać się bezproblemowo, ponieważ własność jest +zadeklarowana, typowana i testowalna, a nie dorozumiana. ### Co należy do kontraktu @@ -424,155 +428,155 @@ Dobre kontrakty pluginów są: - typowane - małe -- specyficzne dla możliwości -- należące do rdzenia -- wielokrotnego użytku przez wiele pluginów -- używalne przez kanały/funkcje bez wiedzy o dostawcy +- specyficzne dla capability +- należące do core +- możliwe do ponownego użycia przez wiele pluginów +- możliwe do użycia przez kanały/funkcje bez wiedzy o dostawcy Złe kontrakty pluginów to: -- polityka specyficzna dla dostawcy ukryta w rdzeniu -- jednorazowe furtki ucieczki specyficzne dla pluginu, które omijają rejestr +- polityka specyficzna dla dostawcy ukryta w core +- jednorazowe furtki dla pluginów omijające rejestr - kod kanału sięgający bezpośrednio do implementacji dostawcy -- doraźne obiekty runtime, które nie są częścią `OpenClawPluginApi` ani +- ad hoc obiekty runtime, które nie są częścią `OpenClawPluginApi` ani `api.runtime` -W razie wątpliwości podnieś poziom abstrakcji: najpierw zdefiniuj możliwość, a potem -pozwól pluginom się do niej podłączać. +W razie wątpliwości podnieś poziom abstrakcji: najpierw zdefiniuj capability, a potem +pozwól pluginom się do niej podłączyć. ## Model wykonania -Natywne pluginy OpenClaw działają **w tym samym procesie** co Gateway. Nie są +Natywne pluginy OpenClaw działają **wewnątrz procesu** razem z Gateway. Nie są sandboxowane. Załadowany natywny plugin ma tę samą granicę zaufania na poziomie procesu co -kod rdzenia. +kod core. -Konsekwencje: +Implikacje: - natywny plugin może rejestrować narzędzia, handlery sieciowe, hooki i usługi -- błąd natywnego pluginu może spowodować awarię lub destabilizację gatewaya +- błąd natywnego pluginu może zawiesić lub zdestabilizować gateway - złośliwy natywny plugin jest równoważny dowolnemu wykonaniu kodu wewnątrz procesu OpenClaw -Zgodne bundle są bezpieczniejsze domyślnie, bo OpenClaw obecnie traktuje je -jako pakiety metadanych/treści. W bieżących wydaniach oznacza to głównie bundlowane +Kompatybilne bundle są domyślnie bezpieczniejsze, ponieważ OpenClaw obecnie traktuje je +jako paczki metadanych/treści. W obecnych wydaniach oznacza to głównie dołączone Skills. -Dla pluginów niebundlowanych używaj allowlist i jawnych ścieżek instalacji/ładowania. Traktuj -pluginy workspace jako kod deweloperski, a nie produkcyjne ustawienia domyślne. +Dla pluginów niedołączonych używaj allowlist i jawnych ścieżek instalacji/ładowania. Traktuj +pluginy workspace jako kod deweloperski, a nie domyślne ustawienie produkcyjne. -Dla nazw pakietów bundlowanego workspace utrzymuj identyfikator pluginu zakotwiczony w nazwie -npm: domyślnie `@openclaw/` albo zatwierdzony typowany sufiks taki jak -`-provider`, `-plugin`, `-speech`, `-sandbox` albo `-media-understanding`, gdy +Dla nazw pakietów dołączonych pluginów workspace utrzymuj identyfikator pluginu zakotwiczony w nazwie npm: +domyślnie `@openclaw/` albo zatwierdzony sufiks typowany, taki jak +`-provider`, `-plugin`, `-speech`, `-sandbox` lub `-media-understanding`, gdy pakiet celowo wystawia węższą rolę pluginu. -Ważna uwaga o zaufaniu: +Ważna uwaga dotycząca zaufania: - `plugins.allow` ufa **identyfikatorom pluginów**, a nie pochodzeniu źródła. -- Plugin workspace z tym samym identyfikatorem co bundlowany plugin celowo przesłania - bundlowaną kopię, gdy ten plugin workspace jest włączony/na allowliście. -- Jest to normalne i przydatne dla lokalnego rozwoju, testów łatek i hotfixów. +- Plugin workspace o tym samym identyfikatorze co dołączony plugin celowo przesłania + dołączoną kopię, gdy ten plugin workspace jest włączony/na allowliście. +- To normalne i przydatne przy lokalnym rozwoju, testowaniu poprawek i hotfixach. ## Granica eksportu -OpenClaw eksportuje możliwości, a nie wygodę implementacji. +OpenClaw eksportuje capabilities, a nie implementacyjne ułatwienia. -Utrzymuj publiczną rejestrację możliwości. Ogranicz eksport pomocników niebędących kontraktem: +Utrzymuj publiczną rejestrację capability. Ograniczaj eksport helperów, które nie są częścią kontraktu: -- podścieżki specyficzne dla bundlowanych pluginów -- podścieżki mechaniki runtime nieprzeznaczone jako publiczne API -- pomocniki wygodne specyficzne dla dostawcy -- pomocniki setup/onboarding będące szczegółami implementacji +- subścieżki helperów specyficznych dla dołączonych pluginów +- subścieżki infrastruktury runtime, które nie są przeznaczone jako publiczne API +- helpery wygodne specyficzne dla dostawców +- helpery konfiguracji/onboardingu będące szczegółami implementacji -Niektóre podścieżki pomocnicze bundlowanych pluginów nadal pozostają w wygenerowanej mapie -eksportów SDK ze względu na zgodność i utrzymanie bundlowanych pluginów. Obecne przykłady obejmują +Niektóre subścieżki helperów dołączonych pluginów nadal pozostają w wygenerowanej mapie eksportów SDK +ze względów kompatybilności i utrzymania dołączonych pluginów. Aktualne przykłady to `plugin-sdk/feishu`, `plugin-sdk/feishu-setup`, `plugin-sdk/zalo`, -`plugin-sdk/zalo-setup` oraz kilka szczelin `plugin-sdk/matrix*`. Traktuj je jako -zastrzeżone eksporty szczegółów implementacyjnych, a nie zalecany wzorzec SDK dla -nowych zewnętrznych pluginów. +`plugin-sdk/zalo-setup` oraz kilka granic `plugin-sdk/matrix*`. Traktuj je jako +zastrzeżone eksporty będące szczegółami implementacji, a nie jako zalecany wzorzec SDK dla +nowych pluginów zewnętrznych. -## Potok ładowania +## Pipeline ładowania -Podczas uruchamiania OpenClaw wykonuje w przybliżeniu następujące kroki: +Podczas uruchamiania OpenClaw robi w przybliżeniu to: -1. wykrywa kandydackie korzenie pluginów -2. odczytuje natywne albo zgodne manifesty bundle oraz metadane pakietów +1. wykrywa katalogi główne kandydackich pluginów +2. odczytuje natywne lub kompatybilne manifesty bundle i metadane pakietów 3. odrzuca niebezpiecznych kandydatów 4. normalizuje konfigurację pluginów (`plugins.enabled`, `allow`, `deny`, `entries`, `slots`, `load.paths`) 5. decyduje o włączeniu dla każdego kandydata 6. ładuje włączone natywne moduły przez jiti -7. wywołuje natywne hooki `register(api)` (lub `activate(api)` — starszy alias) i zbiera rejestracje do rejestru pluginów -8. udostępnia rejestr powierzchniom poleceń/runtime +7. wywołuje hooki natywnego `register(api)` (lub `activate(api)` — legacy alias) i zbiera rejestracje do rejestru pluginów +8. udostępnia rejestr komendom/powierzchniom runtime -`activate` jest starszym aliasem dla `register` — loader rozwiązuje to, co jest obecne (`def.register ?? def.activate`) i wywołuje w tym samym miejscu. Wszystkie bundlowane pluginy używają `register`; dla nowych pluginów preferuj `register`. +`activate` jest legacy aliasem `register` — loader rozwiązuje to, co jest obecne (`def.register ?? def.activate`) i wywołuje je w tym samym miejscu. Wszystkie dołączone pluginy używają `register`; dla nowych pluginów preferuj `register`. Bramki bezpieczeństwa działają **przed** wykonaniem runtime. Kandydaci są blokowani, -gdy entry wychodzi poza korzeń pluginu, ścieżka jest zapisywalna dla wszystkich albo -własność ścieżki wygląda podejrzanie w przypadku pluginów niebundlowanych. +gdy entry wychodzi poza katalog główny pluginu, ścieżka ma uprawnienia world-writable albo +własność ścieżki wygląda podejrzanie dla pluginów niedołączonych. ### Zachowanie manifest-first -Manifest jest źródłem prawdy warstwy control-plane. OpenClaw używa go do: +Manifest jest źródłem prawdy dla control plane. OpenClaw używa go do: - identyfikacji pluginu -- wykrywania zadeklarowanych kanałów/Skills/schematu konfiguracji lub możliwości bundle +- wykrywania deklarowanych kanałów/Skills/schematu konfiguracji lub capabilities bundle - walidacji `plugins.entries..config` -- rozszerzania etykiet/placeholderów w Control UI +- rozszerzania etykiet/placeholderów Control UI - wyświetlania metadanych instalacji/katalogu -W przypadku natywnych pluginów moduł runtime jest częścią data-plane. Rejestruje -rzeczywiste zachowania, takie jak hooki, narzędzia, polecenia albo przepływy dostawcy. +Dla natywnych pluginów moduł runtime jest częścią data plane. Rejestruje +rzeczywiste zachowania, takie jak hooki, narzędzia, komendy lub przepływy providerów. ### Co loader przechowuje w cache -OpenClaw utrzymuje krótkie cache w pamięci procesu dla: +OpenClaw utrzymuje krótkie cache'e wewnątrz procesu dla: - wyników wykrywania - danych rejestru manifestów - załadowanych rejestrów pluginów -Te cache zmniejszają koszt gwałtownego uruchamiania i powtarzanych poleceń. Są bezpieczne -do traktowania jako krótkotrwałe cache wydajnościowe, a nie trwałe przechowywanie. +Te cache'e zmniejszają koszt gwałtownych startów i powtarzanych komend. Można o nich myśleć +jako o krótkotrwałych cache'ach wydajnościowych, a nie o trwałym stanie. -Uwaga o wydajności: +Uwaga dotycząca wydajności: - Ustaw `OPENCLAW_DISABLE_PLUGIN_DISCOVERY_CACHE=1` albo - `OPENCLAW_DISABLE_PLUGIN_MANIFEST_CACHE=1`, aby wyłączyć te cache. -- Dostosuj okna cache za pomocą `OPENCLAW_PLUGIN_DISCOVERY_CACHE_MS` i + `OPENCLAW_DISABLE_PLUGIN_MANIFEST_CACHE=1`, aby wyłączyć te cache'e. +- Okna cache można stroić przez `OPENCLAW_PLUGIN_DISCOVERY_CACHE_MS` i `OPENCLAW_PLUGIN_MANIFEST_CACHE_MS`. ## Model rejestru -Załadowane pluginy nie mutują bezpośrednio losowych globali rdzenia. Rejestrują się w +Załadowane pluginy nie mutują bezpośrednio losowych globali core. Rejestrują się w centralnym rejestrze pluginów. Rejestr śledzi: - rekordy pluginów (tożsamość, źródło, pochodzenie, status, diagnostyka) - narzędzia -- starsze hooki i typowane hooki +- legacy hooks i hooki typowane - kanały -- dostawców +- providerów - handlery Gateway RPC - trasy HTTP - rejestratory CLI - usługi w tle -- polecenia należące do pluginów +- komendy należące do pluginów -Funkcje rdzenia następnie odczytują z tego rejestru zamiast komunikować się z modułami pluginów -bezpośrednio. Dzięki temu ładowanie pozostaje jednokierunkowe: +Funkcje core odczytują następnie z tego rejestru zamiast komunikować się bezpośrednio z modułami pluginów. +Dzięki temu ładowanie pozostaje jednokierunkowe: - moduł pluginu -> rejestracja w rejestrze -- runtime rdzenia -> konsumpcja rejestru +- runtime core -> korzystanie z rejestru -To rozdzielenie ma znaczenie dla utrzymywalności. Oznacza, że większość powierzchni rdzenia potrzebuje -tylko jednego punktu integracji: „odczytaj rejestr”, a nie „obsłuż specjalnie każdy moduł pluginu”. +To rozdzielenie ma znaczenie dla utrzymywalności. Oznacza, że większość powierzchni core +potrzebuje tylko jednego punktu integracji: „odczytaj rejestr”, a nie „obsługuj osobno każdy moduł pluginu”. ## Callbacki powiązania konwersacji -Pluginy, które wiążą konwersację, mogą reagować, gdy zatwierdzenie zostanie rozstrzygnięte. +Pluginy, które wiążą konwersację, mogą reagować po rozstrzygnięciu zatwierdzenia. Użyj `api.onConversationBindingResolved(...)`, aby otrzymać callback po zatwierdzeniu lub odrzuceniu żądania powiązania: @@ -583,38 +587,39 @@ export default { register(api) { api.onConversationBindingResolved(async (event) => { if (event.status === "approved") { - // Powiązanie istnieje teraz dla tego pluginu + konwersacji. + // A binding now exists for this plugin + conversation. console.log(event.binding?.conversationId); return; } - // Żądanie zostało odrzucone; wyczyść lokalny stan oczekujący. + // The request was denied; clear any local pending state. console.log(event.request.conversation.conversationId); }); }, }; ``` -Pola payload callbacka: +Pola ładunku callbacka: -- `status`: `"approved"` albo `"denied"` -- `decision`: `"allow-once"`, `"allow-always"` albo `"deny"` +- `status`: `"approved"` lub `"denied"` +- `decision`: `"allow-once"`, `"allow-always"` lub `"deny"` - `binding`: rozstrzygnięte powiązanie dla zatwierdzonych żądań -- `request`: oryginalne podsumowanie żądania, wskazówka odłączenia, identyfikator nadawcy i +- `request`: oryginalne podsumowanie żądania, wskazówka odłączenia, identyfikator nadawcy oraz metadane konwersacji -Ten callback służy wyłącznie do powiadomień. Nie zmienia tego, kto może powiązać -konwersację, i uruchamia się po zakończeniu obsługi zatwierdzenia przez rdzeń. +Ten callback służy wyłącznie do powiadamiania. Nie zmienia tego, kto może powiązać +konwersację, i uruchamia się po zakończeniu obsługi zatwierdzenia przez core. -## Hooki runtime dostawców +## Hooki runtime dostawcy Pluginy dostawców mają teraz dwie warstwy: -- metadane manifestu: `providerAuthEnvVars` dla taniego wyszukiwania auth dostawcy w env - przed załadowaniem runtime, `channelEnvVars` dla taniego wyszukiwania env/setup kanału - przed załadowaniem runtime oraz `providerAuthChoices` dla tanich etykiet - onboarding/auth-choice i metadanych flag CLI przed załadowaniem runtime -- hooki czasu konfiguracji: `catalog` / starsze `discovery` oraz `applyConfigDefaults` +- metadane manifestu: `providerAuthEnvVars` dla taniego sprawdzania auth dostawcy z env + przed załadowaniem runtime, `providerAuthAliases` dla wariantów dostawców współdzielących + auth, `channelEnvVars` dla taniego sprawdzania env/konfiguracji kanału przed + załadowaniem runtime oraz `providerAuthChoices` dla tanich etykiet onboardingu/wyboru auth i + metadanych flag CLI przed załadowaniem runtime +- hooki czasu konfiguracji: `catalog` / legacy `discovery` oraz `applyConfigDefaults` - hooki runtime: `normalizeModelId`, `normalizeTransport`, `normalizeConfig`, `applyNativeStreamingUsageCompat`, `resolveConfigApiKey`, @@ -635,86 +640,88 @@ Pluginy dostawców mają teraz dwie warstwy: `buildReplayPolicy`, `sanitizeReplayHistory`, `validateReplayTurns`, `onModelSelected` -OpenClaw nadal odpowiada za ogólną pętlę agenta, failover, obsługę transkryptów i +OpenClaw nadal obsługuje ogólną pętlę agenta, failover, obsługę transkryptów i politykę narzędzi. Te hooki są powierzchnią rozszerzeń dla zachowań specyficznych dla dostawcy bez -potrzeby posiadania całkowicie własnego transportu wnioskowania. +potrzeby budowania całkowicie niestandardowego transportu inferencyjnego. Używaj manifestowego `providerAuthEnvVars`, gdy dostawca ma poświadczenia oparte na env, -które ogólne ścieżki auth/status/model-picker powinny widzieć bez ładowania runtime pluginu. -Używaj manifestowego `providerAuthChoices`, gdy powierzchnie onboarding/auth-choice CLI -powinny znać identyfikator wyboru dostawcy, etykiety grup i proste -uwierzytelnianie jednym przełącznikiem bez ładowania runtime dostawcy. Runtime dostawcy -`envVars` zachowaj dla wskazówek skierowanych do operatora, takich jak etykiety onboardingu albo -zmienne setup dla OAuth client-id/client-secret. +które ogólne ścieżki auth/status/wyboru modelu powinny widzieć bez ładowania runtime pluginu. +Używaj manifestowego `providerAuthAliases`, gdy jeden identyfikator dostawcy ma ponownie używać +zmiennych env, profili auth, auth opartego na konfiguracji oraz wyboru onboardingu klucza API +innego identyfikatora dostawcy. Używaj manifestowego `providerAuthChoices`, gdy powierzchnie +CLI onboardingu/wyboru auth powinny znać identyfikator wyboru dostawcy, etykiety grup i prostą +obsługę auth przez pojedynczą flagę bez ładowania runtime dostawcy. Zachowaj runtime'owe +`envVars` dostawcy dla wskazówek operatora, takich jak etykiety onboardingowe lub zmienne +konfiguracji OAuth client-id/client-secret. -Używaj manifestowego `channelEnvVars`, gdy kanał ma auth lub setup sterowane przez env, które -ogólny fallback shell-env, kontrole config/status albo prompty setup powinny widzieć +Używaj manifestowego `channelEnvVars`, gdy kanał ma auth lub konfigurację opartą na env, które +ogólny fallback z shell-env, sprawdzania config/status albo prompty konfiguracji powinny widzieć bez ładowania runtime kanału. -### Kolejność hooków i zastosowanie +### Kolejność hooków i ich użycie -W przypadku pluginów modeli/dostawców OpenClaw wywołuje hooki mniej więcej w tej kolejności. +Dla pluginów model/provider OpenClaw wywołuje hooki mniej więcej w tej kolejności. Kolumna „Kiedy używać” to szybki przewodnik decyzyjny. -| # | Hook | Co robi | Kiedy używać | -| --- | --------------------------------- | ------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | -| 1 | `catalog` | Publikuje konfigurację dostawcy do `models.providers` podczas generowania `models.json` | Dostawca posiada katalog albo wartości domyślne `baseUrl` | -| 2 | `applyConfigDefaults` | Stosuje globalne wartości domyślne konfiguracji należące do dostawcy podczas materializacji konfiguracji | Wartości domyślne zależą od trybu auth, env albo semantyki rodziny modeli dostawcy | -| -- | _(wbudowane wyszukiwanie modeli)_ | OpenClaw najpierw próbuje zwykłej ścieżki rejestru/katalogu | _(to nie jest hook pluginu)_ | -| 3 | `normalizeModelId` | Normalizuje starsze albo preview aliasy `model-id` przed wyszukaniem | Dostawca posiada czyszczenie aliasów przed kanonicznym rozstrzyganiem modelu | -| 4 | `normalizeTransport` | Normalizuje rodzinę dostawców `api` / `baseUrl` przed ogólnym składaniem modelu | Dostawca posiada czyszczenie transportu dla niestandardowych identyfikatorów dostawców w tej samej rodzinie transportu | -| 5 | `normalizeConfig` | Normalizuje `models.providers.` przed rozstrzygnięciem runtime/dostawcy | Dostawca potrzebuje czyszczenia konfiguracji, które powinno żyć wraz z pluginem; bundlowane pomocniki rodziny Google dodatkowo wspierają wspierane wpisy konfiguracji Google | -| 6 | `applyNativeStreamingUsageCompat` | Stosuje przepisywanie zgodności z użyciem natywnego streamingu do dostawców konfiguracji | Dostawca potrzebuje poprawek metadanych użycia natywnego streamingu zależnych od endpointu | -| 7 | `resolveConfigApiKey` | Rozwiązuje auth typu env-marker dla dostawców konfiguracji przed załadowaniem runtime auth | Dostawca ma własne rozwiązywanie klucza API env-marker; `amazon-bedrock` ma tu również wbudowany resolver env-marker AWS | -| 8 | `resolveSyntheticAuth` | Ujawnia lokalne/self-hosted lub oparte na konfiguracji auth bez utrwalania jawnego tekstu | Dostawca może działać z syntetycznym/lokalnym markerem poświadczeń | -| 9 | `resolveExternalAuthProfiles` | Nakłada zewnętrzne profile auth należące do dostawcy; domyślne `persistence` to `runtime-only` dla poświadczeń należących do CLI/aplikacji | Dostawca ponownie używa zewnętrznych poświadczeń auth bez utrwalania skopiowanych tokenów odświeżania | -| 10 | `shouldDeferSyntheticProfileAuth` | Obniża priorytet przechowywanych placeholderów syntetycznych profili względem auth opartego na env/config | Dostawca przechowuje syntetyczne placeholdery profili, które nie powinny mieć pierwszeństwa | -| 11 | `resolveDynamicModel` | Synchroniczny fallback dla identyfikatorów modeli należących do dostawcy, których nie ma jeszcze w lokalnym rejestrze | Dostawca akceptuje dowolne upstreamowe identyfikatory modeli | -| 12 | `prepareDynamicModel` | Asynchroniczne rozgrzanie, po czym `resolveDynamicModel` uruchamia się ponownie | Dostawca potrzebuje metadanych sieciowych przed rozstrzygnięciem nieznanych identyfikatorów | -| 13 | `normalizeResolvedModel` | Końcowe przepisanie przed użyciem rozstrzygniętego modelu przez embedded runner | Dostawca potrzebuje przepisań transportu, ale nadal używa transportu rdzenia | -| 14 | `contributeResolvedModelCompat` | Dodaje flagi zgodności dla modeli dostawcy za innym zgodnym transportem | Dostawca rozpoznaje własne modele na transportach proxy bez przejmowania roli dostawcy | -| 15 | `capabilities` | Metadane transkryptów/narzędzi należące do dostawcy używane przez współdzieloną logikę rdzenia | Dostawca potrzebuje specyficznych zachowań transkryptu/rodziny dostawcy | -| 16 | `normalizeToolSchemas` | Normalizuje schematy narzędzi przed przekazaniem ich do embedded runnera | Dostawca potrzebuje czyszczenia schematu rodziny transportu | -| 17 | `inspectToolSchemas` | Ujawnia diagnostykę schematów należącą do dostawcy po normalizacji | Dostawca chce ostrzeżeń o słowach kluczowych bez uczenia rdzenia reguł specyficznych dla dostawcy | -| 18 | `resolveReasoningOutputMode` | Wybiera natywny albo oznaczany kontrakt wyjścia reasoning | Dostawca potrzebuje oznaczanego reasoning/końcowego wyjścia zamiast natywnych pól | -| 19 | `prepareExtraParams` | Normalizacja parametrów żądania przed ogólnymi wrapperami opcji streamu | Dostawca potrzebuje domyślnych parametrów żądania albo czyszczenia parametrów per dostawca | -| 20 | `createStreamFn` | W pełni zastępuje zwykłą ścieżkę streamu niestandardowym transportem | Dostawca potrzebuje niestandardowego protokołu na przewodzie, a nie tylko wrappera | -| 21 | `wrapStreamFn` | Wrapper streamu po zastosowaniu ogólnych wrapperów | Dostawca potrzebuje wrapperów nagłówków/treści/zgodności modelu bez niestandardowego transportu | -| 22 | `resolveTransportTurnState` | Dołącza natywne nagłówki lub metadane transportu per turn | Dostawca chce, aby ogólne transporty wysyłały natywną tożsamość tury dostawcy | -| 23 | `resolveWebSocketSessionPolicy` | Dołącza natywne nagłówki WebSocket lub politykę cooldown sesji | Dostawca chce, aby ogólne transporty WS dostrajały nagłówki sesji albo politykę fallback | -| 24 | `formatApiKey` | Formater profilu auth: zapisany profil staje się runtime stringiem `apiKey` | Dostawca przechowuje dodatkowe metadane auth i potrzebuje niestandardowego kształtu tokena runtime | -| 25 | `refreshOAuth` | Nadpisanie odświeżania OAuth dla niestandardowych endpointów odświeżania albo polityki błędów odświeżania | Dostawca nie pasuje do współdzielonych mechanizmów odświeżania `pi-ai` | -| 26 | `buildAuthDoctorHint` | Wskazówka naprawcza dołączana po niepowodzeniu odświeżania OAuth | Dostawca potrzebuje własnych wskazówek naprawy auth po błędzie odświeżenia | -| 27 | `matchesContextOverflowError` | Dopasowywanie przepełnienia okna kontekstu należące do dostawcy | Dostawca ma surowe błędy przepełnienia, których ogólne heurystyki nie wykryją | -| 28 | `classifyFailoverReason` | Klasyfikacja przyczyny failover należąca do dostawcy | Dostawca może mapować surowe błędy API/transportu na rate-limit/przeciążenie itd. | -| 29 | `isCacheTtlEligible` | Polityka prompt-cache dla dostawców proxy/backhaul | Dostawca potrzebuje bramkowania TTL cache specyficznego dla proxy | -| 30 | `buildMissingAuthMessage` | Zastąpienie ogólnego komunikatu odzyskiwania przy braku auth | Dostawca potrzebuje komunikatu odzyskiwania przy braku auth specyficznego dla dostawcy | -| 31 | `suppressBuiltInModel` | Tłumienie nieaktualnych modeli upstream plus opcjonalna wskazówka błędu dla użytkownika | Dostawca musi ukryć nieaktualne wiersze upstream albo zastąpić je wskazówką dostawcy | -| 32 | `augmentModelCatalog` | Syntetyczne/końcowe wiersze katalogu dołączane po wykryciu | Dostawca potrzebuje syntetycznych wierszy zgodności z przyszłością w `models list` i pickerach | -| 33 | `isBinaryThinking` | Przełącznik on/off reasoning dla dostawców binarnego thinking | Dostawca udostępnia tylko binarne włącz/wyłącz thinking | -| 34 | `supportsXHighThinking` | Wsparcie reasoning `xhigh` dla wybranych modeli | Dostawca chce `xhigh` tylko dla podzbioru modeli | -| 35 | `resolveDefaultThinkingLevel` | Domyślny poziom `/think` dla konkretnej rodziny modeli | Dostawca posiada domyślną politykę `/think` dla rodziny modeli | -| 36 | `isModernModelRef` | Dopasowywanie nowoczesnych modeli dla filtrów live profili i wyboru smoke | Dostawca posiada preferowane dopasowywanie modeli live/smoke | -| 37 | `prepareRuntimeAuth` | Wymienia skonfigurowane poświadczenie na właściwy token/klucz runtime tuż przed wnioskowaniem | Dostawca potrzebuje wymiany tokena lub krótkotrwałego poświadczenia żądania | -| 38 | `resolveUsageAuth` | Rozwiązuje poświadczenia użycia/rozliczeń dla `/usage` i pokrewnych powierzchni statusu | Dostawca potrzebuje niestandardowego parsowania tokena użycia/kwoty albo innych poświadczeń użycia | -| 39 | `fetchUsageSnapshot` | Pobiera i normalizuje snapshoty użycia/kwot specyficzne dla dostawcy po rozstrzygnięciu auth | Dostawca potrzebuje endpointu użycia specyficznego dla dostawcy albo parsera payloadu | -| 40 | `createEmbeddingProvider` | Buduje adapter embeddingów należący do dostawcy dla pamięci/wyszukiwania | Zachowanie embeddingów pamięci należy do pluginu dostawcy | -| 41 | `buildReplayPolicy` | Zwraca politykę replay kontrolującą obsługę transkryptu dla dostawcy | Dostawca potrzebuje niestandardowej polityki transkryptu (na przykład usuwania bloków thinking) | -| 42 | `sanitizeReplayHistory` | Przepisuje historię replay po ogólnym czyszczeniu transkryptu | Dostawca potrzebuje przepisań replay specyficznych dla dostawcy wykraczających poza współdzielone pomocniki kompaktowania | -| 43 | `validateReplayTurns` | Końcowa walidacja albo przekształcenie tur replay przed embedded runnerem | Transport dostawcy potrzebuje bardziej rygorystycznej walidacji tur po ogólnej sanityzacji | -| 44 | `onModelSelected` | Uruchamia skutki uboczne po wyborze modelu należące do dostawcy | Dostawca potrzebuje telemetrii albo stanu należącego do dostawcy, gdy model staje się aktywny | +| # | Hook | Co robi | Kiedy używać | +| --- | --------------------------------- | -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | +| 1 | `catalog` | Publikuje konfigurację dostawcy do `models.providers` podczas generowania `models.json` | Dostawca posiada katalog albo domyślne wartości `baseUrl` | +| 2 | `applyConfigDefaults` | Stosuje globalne domyślne ustawienia konfiguracji należące do dostawcy podczas materializacji konfiguracji | Ustawienia domyślne zależą od trybu auth, env lub semantyki rodziny modeli dostawcy | +| -- | _(wbudowane wyszukiwanie modelu)_ | OpenClaw najpierw próbuje normalnej ścieżki rejestru/katalogu | _(to nie jest hook pluginu)_ | +| 3 | `normalizeModelId` | Normalizuje legacy aliasy identyfikatorów modeli lub wersji preview przed wyszukaniem | Dostawca zarządza porządkowaniem aliasów przed kanonicznym rozstrzygnięciem modelu | +| 4 | `normalizeTransport` | Normalizuje `api` / `baseUrl` dla rodziny dostawców przed ogólnym składaniem modelu | Dostawca zarządza porządkowaniem transportu dla niestandardowych identyfikatorów dostawców w tej samej rodzinie transportu | +| 5 | `normalizeConfig` | Normalizuje `models.providers.` przed rozstrzygnięciem runtime/dostawcy | Dostawca potrzebuje porządkowania konfiguracji, które powinno znajdować się w pluginie; dołączone helpery rodziny Google również wspierają tu wspierane wpisy konfiguracji Google | +| 6 | `applyNativeStreamingUsageCompat` | Stosuje kompatybilnościowe przepisywanie natywnego użycia streaming do providerów konfiguracji | Dostawca potrzebuje poprawek metadanych natywnego użycia streaming zależnych od endpointu | +| 7 | `resolveConfigApiKey` | Rozstrzyga auth typu env-marker dla providerów konfiguracji przed ładowaniem auth runtime | Dostawca ma własne rozstrzyganie klucza API przez env-marker; `amazon-bedrock` ma tu także wbudowany resolver env-marker AWS | +| 8 | `resolveSyntheticAuth` | Ujawnia auth lokalny/self-hosted albo oparty na konfiguracji bez utrwalania jawnego tekstu | Dostawca może działać z syntetycznym/lokalnym markerem poświadczeń | +| 9 | `resolveExternalAuthProfiles` | Nakłada profile zewnętrznego auth należące do dostawcy; domyślne `persistence` to `runtime-only` dla poświadczeń należących do CLI/aplikacji | Dostawca ponownie używa poświadczeń zewnętrznego auth bez utrwalania skopiowanych refresh tokenów | +| 10 | `shouldDeferSyntheticProfileAuth` | Obniża priorytet zapisanych syntetycznych placeholderów profili względem auth opartego na env/konfiguracji | Dostawca przechowuje syntetyczne placeholdery profili, które nie powinny mieć pierwszeństwa | +| 11 | `resolveDynamicModel` | Synchroniczny fallback dla identyfikatorów modeli należących do dostawcy, których nie ma jeszcze w lokalnym rejestrze | Dostawca akceptuje dowolne identyfikatory modeli upstream | +| 12 | `prepareDynamicModel` | Asynchroniczne rozgrzanie, po czym `resolveDynamicModel` uruchamia się ponownie | Dostawca potrzebuje metadanych z sieci przed rozstrzyganiem nieznanych identyfikatorów | +| 13 | `normalizeResolvedModel` | Ostateczne przepisanie przed użyciem rozstrzygniętego modelu przez embedded runner | Dostawca potrzebuje przepisań transportu, ale nadal używa transportu core | +| 14 | `contributeResolvedModelCompat` | Dostarcza flagi kompatybilności dla modeli dostawcy działających przez inny kompatybilny transport | Dostawca rozpoznaje własne modele na transportach proxy bez przejmowania roli dostawcy | +| 15 | `capabilities` | Metadane transkryptów/narzędzi należące do dostawcy, używane przez współdzieloną logikę core | Dostawca potrzebuje niuansów związanych z transkryptem/rodziną dostawców | +| 16 | `normalizeToolSchemas` | Normalizuje schematy narzędzi, zanim zobaczy je embedded runner | Dostawca potrzebuje porządkowania schematów dla rodziny transportu | +| 17 | `inspectToolSchemas` | Ujawnia diagnostykę schematów należącą do dostawcy po normalizacji | Dostawca chce ostrzeżeń o słowach kluczowych bez uczenia core zasad specyficznych dla dostawcy | +| 18 | `resolveReasoningOutputMode` | Wybiera natywny albo tagowany kontrakt wyjścia reasoning | Dostawca potrzebuje tagowanego reasoning/final output zamiast natywnych pól | +| 19 | `prepareExtraParams` | Normalizacja parametrów żądania przed ogólnymi wrapperami opcji stream | Dostawca potrzebuje domyślnych parametrów żądania lub porządkowania parametrów dla konkretnego dostawcy | +| 20 | `createStreamFn` | W pełni zastępuje normalną ścieżkę stream własnym transportem | Dostawca potrzebuje własnego protokołu wire, a nie tylko wrappera | +| 21 | `wrapStreamFn` | Wrapper stream po zastosowaniu ogólnych wrapperów | Dostawca potrzebuje wrapperów zgodności nagłówków/ciała/modelu bez własnego transportu | +| 22 | `resolveTransportTurnState` | Dołącza natywne nagłówki per-turn transportu lub metadane | Dostawca chce, aby ogólne transporty wysyłały natywną tożsamość tury dostawcy | +| 23 | `resolveWebSocketSessionPolicy` | Dołącza natywne nagłówki WebSocket albo politykę cool-down sesji | Dostawca chce, by ogólne transporty WS stroiły nagłówki sesji lub politykę fallback | +| 24 | `formatApiKey` | Formatter profilu auth: zapisany profil staje się runtime'owym ciągiem `apiKey` | Dostawca przechowuje dodatkowe metadane auth i potrzebuje niestandardowego kształtu tokenu runtime | +| 25 | `refreshOAuth` | Nadpisanie odświeżania OAuth dla niestandardowych endpointów odświeżania lub polityki błędów odświeżania | Dostawca nie pasuje do współdzielonych odświeżaczy `pi-ai` | +| 26 | `buildAuthDoctorHint` | Wskazówka naprawcza dołączana po niepowodzeniu odświeżenia OAuth | Dostawca potrzebuje własnych wskazówek naprawy auth po błędzie odświeżenia | +| 27 | `matchesContextOverflowError` | Matcher przepełnienia okna kontekstu należący do dostawcy | Dostawca ma surowe błędy przepełnienia, których ogólne heurystyki nie wychwycą | +| 28 | `classifyFailoverReason` | Klasyfikacja przyczyn failover należąca do dostawcy | Dostawca potrafi mapować surowe błędy API/transportu na rate-limit/przeciążenie itp. | +| 29 | `isCacheTtlEligible` | Polityka prompt-cache dla dostawców proxy/backhaul | Dostawca potrzebuje bramkowania TTL cache specyficznego dla proxy | +| 30 | `buildMissingAuthMessage` | Zastępstwo dla ogólnego komunikatu odzyskiwania po braku auth | Dostawca potrzebuje specyficznej dla siebie wskazówki odzyskiwania po braku auth | +| 31 | `suppressBuiltInModel` | Tłumienie przestarzałych modeli upstream plus opcjonalna wskazówka błędu dla użytkownika | Dostawca musi ukrywać przestarzałe wiersze upstream lub zastąpić je wskazówką dostawcy | +| 32 | `augmentModelCatalog` | Syntetyczne/końcowe wiersze katalogu dodawane po wykryciu | Dostawca potrzebuje syntetycznych wierszy zgodnych z przyszłością w `models list` i selektorach | +| 33 | `isBinaryThinking` | Przełącznik on/off reasoning dla providerów binary-thinking | Dostawca udostępnia tylko binarne włączenie/wyłączenie thinking | +| 34 | `supportsXHighThinking` | Obsługa reasoning `xhigh` dla wybranych modeli | Dostawca chce `xhigh` tylko dla podzbioru modeli | +| 35 | `resolveDefaultThinkingLevel` | Domyślny poziom `/think` dla konkretnej rodziny modeli | Dostawca zarządza domyślną polityką `/think` dla rodziny modeli | +| 36 | `isModernModelRef` | Matcher nowoczesnych modeli do filtrów live profile i wyboru smoke | Dostawca zarządza dopasowaniem preferowanych modeli live/smoke | +| 37 | `prepareRuntimeAuth` | Wymienia skonfigurowane poświadczenie na właściwy token/klucz runtime tuż przed inferencją | Dostawca potrzebuje wymiany tokenu albo krótkotrwałego poświadczenia dla żądania | +| 38 | `resolveUsageAuth` | Rozstrzyga poświadczenia użycia/rozliczeń dla `/usage` i powiązanych powierzchni statusu | Dostawca potrzebuje własnego parsowania tokenów użycia/kwot lub innego poświadczenia użycia | +| 39 | `fetchUsageSnapshot` | Pobiera i normalizuje snapshoty użycia/kwot specyficzne dla dostawcy po rozstrzygnięciu auth | Dostawca potrzebuje endpointu użycia lub parsera ładunku specyficznego dla dostawcy | +| 40 | `createEmbeddingProvider` | Buduje adapter embeddingów należący do dostawcy dla pamięci/wyszukiwania | Zachowanie embeddingów pamięci należy do pluginu dostawcy | +| 41 | `buildReplayPolicy` | Zwraca politykę replay kontrolującą obsługę transkryptu dla dostawcy | Dostawca potrzebuje własnej polityki transkryptów (na przykład usuwania bloków thinking) | +| 42 | `sanitizeReplayHistory` | Przepisuje historię replay po ogólnym czyszczeniu transkryptu | Dostawca potrzebuje własnych przepisań replay wykraczających poza współdzielone helpery kompaktowania | +| 43 | `validateReplayTurns` | Ostateczna walidacja lub przekształcenie tur replay przed embedded runnerem | Transport dostawcy wymaga surowszej walidacji tur po ogólnej sanitacji | +| 44 | `onModelSelected` | Uruchamia skutki uboczne należące do dostawcy po wybraniu modelu | Dostawca potrzebuje telemetrii lub stanu należącego do dostawcy, gdy model staje się aktywny | `normalizeModelId`, `normalizeTransport` i `normalizeConfig` najpierw sprawdzają -dopasowany plugin dostawcy, a następnie przechodzą do innych pluginów dostawców zdolnych do obsługi hooków, +dopasowany plugin dostawcy, a następnie przechodzą do innych pluginów dostawców zdolnych do hooków, dopóki któryś faktycznie nie zmieni identyfikatora modelu albo transportu/konfiguracji. Dzięki temu -shimy aliasów/zgodności dostawców działają bez konieczności wiedzy po stronie wywołującego, który -bundlowany plugin jest właścicielem przepisywania. Jeśli żaden hook dostawcy nie przepisze wspieranego -wpisu konfiguracji rodziny Google, bundlowany normalizator konfiguracji Google nadal stosuje -to czyszczenie zgodności. +shimy aliasów/kompatybilności providerów nadal działają bez wymagania, aby wywołujący wiedział, +który dołączony plugin obsługuje przepisanie. Jeśli żaden hook dostawcy nie przepisze +wspieranego wpisu konfiguracji rodziny Google, dołączony normalizator konfiguracji Google nadal +stosuje tę poprawkę kompatybilności. -Jeśli dostawca potrzebuje w pełni niestandardowego protokołu na przewodzie albo własnego wykonawcy żądań, -to jest to inna klasa rozszerzenia. Te hooki są przeznaczone dla zachowań dostawcy, -które nadal działają na zwykłej pętli wnioskowania OpenClaw. +Jeśli dostawca potrzebuje w pełni niestandardowego protokołu wire albo niestandardowego wykonawcy żądań, +to jest inna klasa rozszerzenia. Te hooki są przeznaczone dla zachowań dostawców, +które nadal działają na normalnej pętli inferencyjnej OpenClaw. ### Przykład dostawcy @@ -776,111 +783,113 @@ api.registerProvider({ `resolveUsageAuth`, `fetchUsageSnapshot`, `isCacheTtlEligible`, `resolveDefaultThinkingLevel`, `applyConfigDefaults`, `isModernModelRef` i `wrapStreamFn`, ponieważ obsługuje zgodność z przyszłością Claude 4.6, - wskazówki dotyczące rodziny dostawcy, wskazówki naprawy auth, integrację z endpointem użycia, - kwalifikowalność prompt-cache, domyślne ustawienia konfiguracji świadome auth, domyślną/adaptacyjną - politykę thinking Claude oraz kształtowanie streamu specyficzne dla Anthropic dla - nagłówków beta, `/fast` / `serviceTier` i `context1m`. -- Pomocniki streamów specyficzne dla Claude w Anthropic pozostają na razie w - publicznej szczelinie `api.ts` / `contract-api.ts` należącej do bundlowanego pluginu. Ta - powierzchnia pakietu eksportuje `wrapAnthropicProviderStream`, `resolveAnthropicBetas`, - `resolveAnthropicFastMode`, `resolveAnthropicServiceTier` oraz niższego poziomu - buildery wrapperów Anthropic zamiast rozszerzać ogólne SDK wokół reguł nagłówków beta jednego + wskazówki dla rodziny providerów, wskazówki naprawy auth, integrację + endpointu użycia, kwalifikowalność prompt-cache, domyślne ustawienia konfiguracji zależne od auth, + politykę domyślnego/adaptacyjnego thinking dla Claude oraz kształtowanie streamu specyficzne dla Anthropic + dla nagłówków beta, `/fast` / `serviceTier` i `context1m`. +- Helpery streamów specyficznych dla Claude w Anthropic pozostają na razie + w publicznej granicy `api.ts` / `contract-api.ts` należącej do dołączonego pluginu. Ta powierzchnia + pakietu eksportuje `wrapAnthropicProviderStream`, `resolveAnthropicBetas`, + `resolveAnthropicFastMode`, `resolveAnthropicServiceTier` oraz niższopoziomowe + buildery wrapperów Anthropic zamiast poszerzać ogólne SDK o reguły nagłówków beta jednego dostawcy. - OpenAI używa `resolveDynamicModel`, `normalizeResolvedModel` i `capabilities` oraz `buildMissingAuthMessage`, `suppressBuiltInModel`, `augmentModelCatalog`, `supportsXHighThinking` i `isModernModelRef`, ponieważ obsługuje zgodność z przyszłością GPT-5.4, bezpośrednią normalizację OpenAI - `openai-completions` -> `openai-responses`, wskazówki auth świadome Codex, - tłumienie Spark, syntetyczne wiersze list OpenAI oraz politykę thinking / modeli live GPT-5; - rodzina streamów `openai-responses-defaults` obsługuje współdzielone natywne wrappery OpenAI Responses dla - nagłówków atrybucji, `/fast`/`serviceTier`, gadatliwości tekstu, natywnego Codex web search, - kształtowania payload zgodności reasoning oraz zarządzania kontekstem Responses. + `openai-completions` -> `openai-responses`, wskazówki auth uwzględniające Codex, + tłumienie Spark, syntetyczne wiersze list OpenAI oraz politykę thinking / + modeli live dla GPT-5; rodzina streamów `openai-responses-defaults` obsługuje + współdzielone natywne wrappery OpenAI Responses dla nagłówków atrybucji, + `/fast`/`serviceTier`, szczegółowości tekstu, natywnego wyszukiwania w sieci Codex, + kształtowania ładunku reasoning-compat oraz zarządzania kontekstem Responses. - OpenRouter używa `catalog` oraz `resolveDynamicModel` i - `prepareDynamicModel`, ponieważ dostawca jest pass-through i może ujawniać nowe - identyfikatory modeli zanim zaktualizuje się statyczny katalog OpenClaw; używa też - `capabilities`, `wrapStreamFn` i `isCacheTtlEligible`, aby trzymać - specyficzne dla dostawcy nagłówki żądań, metadane routingu, poprawki reasoning i - politykę prompt-cache poza rdzeniem. Jego polityka replay pochodzi z rodziny - `passthrough-gemini`, podczas gdy rodzina streamów `openrouter-thinking` - obsługuje wstrzykiwanie proxy reasoning oraz pomijanie nieobsługiwanych modeli i `auto`. + `prepareDynamicModel`, ponieważ dostawca jest pass-through i może wystawiać nowe + identyfikatory modeli przed aktualizacją statycznego katalogu OpenClaw; używa też + `capabilities`, `wrapStreamFn` i `isCacheTtlEligible`, aby utrzymać + nagłówki żądań specyficzne dla dostawcy, metadane routingu, łatki reasoning i politykę prompt-cache + poza core. Jego polityka replay pochodzi z rodziny + `passthrough-gemini`, a rodzina streamów `openrouter-thinking` obsługuje + wstrzykiwanie reasoning proxy oraz pomijanie nieobsługiwanych modeli i `auto`. - GitHub Copilot używa `catalog`, `auth`, `resolveDynamicModel` i `capabilities` oraz `prepareRuntimeAuth` i `fetchUsageSnapshot`, ponieważ - potrzebuje logowania urządzenia należącego do dostawcy, zachowania fallback modeli, - specyficznych zachowań transkryptu Claude, wymiany tokena GitHub -> token Copilot oraz - endpointu użycia należącego do dostawcy. + potrzebuje własnego logowania urządzenia, zachowania fallback modeli, niuansów transkryptów Claude, + wymiany tokenu GitHub -> token Copilot oraz własnego endpointu użycia. - OpenAI Codex używa `catalog`, `resolveDynamicModel`, `normalizeResolvedModel`, `refreshOAuth` i `augmentModelCatalog` oraz `prepareExtraParams`, `resolveUsageAuth` i `fetchUsageSnapshot`, ponieważ - nadal działa na transportach rdzeniowych OpenAI, ale obsługuje własną normalizację - transportu/base URL, politykę fallback odświeżania OAuth, domyślny wybór transportu, + nadal działa na transportach OpenAI core, ale obsługuje własną normalizację transportu/base URL, + politykę fallback odświeżania OAuth, domyślny wybór transportu, syntetyczne wiersze katalogu Codex oraz integrację z endpointem użycia ChatGPT; współdzieli - tę samą rodzinę streamów `openai-responses-defaults` co bezpośrednie OpenAI. + tę samą rodzinę streamów `openai-responses-defaults` co bezpośredni OpenAI. - Google AI Studio i Gemini CLI OAuth używają `resolveDynamicModel`, `buildReplayPolicy`, `sanitizeReplayHistory`, - `resolveReasoningOutputMode`, `wrapStreamFn` i `isModernModelRef`, ponieważ - rodzina replay `google-gemini` obsługuje fallback zgodności z przyszłością Gemini 3.1, - natywną walidację replay Gemini, sanityzację replay bootstrap, - tryb oznaczanego wyjścia reasoning oraz dopasowanie nowoczesnych modeli, podczas gdy - rodzina streamów `google-thinking` obsługuje normalizację payload thinking Gemini; - Gemini CLI OAuth używa też `formatApiKey`, `resolveUsageAuth` i - `fetchUsageSnapshot` do formatowania tokena, parsowania tokena i - podłączania endpointu quota. + `resolveReasoningOutputMode`, `wrapStreamFn` i `isModernModelRef`, ponieważ rodzina replay + `google-gemini` obsługuje fallback zgodności z przyszłością Gemini 3.1, + natywną walidację replay Gemini, sanitację replay bootstrap, tagowany tryb + reasoning-output i dopasowywanie nowoczesnych modeli, natomiast rodzina streamów + `google-thinking` obsługuje normalizację ładunku thinking Gemini; + Gemini CLI OAuth używa również `formatApiKey`, `resolveUsageAuth` i + `fetchUsageSnapshot` do formatowania tokenu, parsowania tokenu i podłączenia + endpointu kwot. - Anthropic Vertex używa `buildReplayPolicy` przez rodzinę replay - `anthropic-by-model`, aby czyszczenie replay specyficzne dla Claude pozostało + `anthropic-by-model`, aby czyszczenie replay specyficzne dla Claude pozostawało ograniczone do identyfikatorów Claude zamiast każdego transportu `anthropic-messages`. - Amazon Bedrock używa `buildReplayPolicy`, `matchesContextOverflowError`, `classifyFailoverReason` i `resolveDefaultThinkingLevel`, ponieważ obsługuje klasyfikację błędów throttle/not-ready/context-overflow specyficzną dla Bedrock - dla ruchu Anthropic-on-Bedrock; jego polityka replay nadal współdzieli tę samą - osłonę `anthropic-by-model` tylko dla Claude. + dla ruchu Anthropic-on-Bedrock; jego polityka replay nadal współdzieli to samo + zabezpieczenie `anthropic-by-model` tylko dla Claude. - OpenRouter, Kilocode, Opencode i Opencode Go używają `buildReplayPolicy` - przez rodzinę replay `passthrough-gemini`, ponieważ pośredniczą modele Gemini - przez transporty zgodne z OpenAI i potrzebują sanityzacji - thought-signature Gemini bez natywnej walidacji replay Gemini ani + przez rodzinę replay `passthrough-gemini`, ponieważ proxy'ują modele Gemini + przez transporty kompatybilne z OpenAI i potrzebują sanitacji + thought-signature Gemini bez natywnej walidacji replay Gemini lub przepisań bootstrap. - MiniMax używa `buildReplayPolicy` przez rodzinę replay - `hybrid-anthropic-openai`, ponieważ jeden dostawca obsługuje zarówno semantykę - Anthropic-message, jak i zgodną z OpenAI; zachowuje usuwanie bloków thinking - tylko dla Claude po stronie Anthropic, a jednocześnie nadpisuje tryb wyjścia reasoning z powrotem na natywny, zaś rodzina streamów `minimax-fast-mode` obsługuje - przepisywania modeli trybu fast na współdzielonej ścieżce streamu. -- Moonshot używa `catalog` oraz `wrapStreamFn`, ponieważ nadal używa współdzielonego - transportu OpenAI, ale potrzebuje normalizacji payload thinking należącej do dostawcy; rodzina streamów - `moonshot-thinking` mapuje konfigurację oraz stan `/think` na swój - natywny binarny payload thinking. + `hybrid-anthropic-openai`, ponieważ jeden dostawca obsługuje semantykę zarówno + Anthropic-message, jak i kompatybilną z OpenAI; utrzymuje usuwanie bloków + thinking tylko dla Claude po stronie Anthropic, jednocześnie nadpisując tryb reasoning + output z powrotem na natywny, a rodzina streamów `minimax-fast-mode` obsługuje + przepisywanie modeli fast-mode na współdzielonej ścieżce stream. +- Moonshot używa `catalog` oraz `wrapStreamFn`, ponieważ nadal korzysta ze współdzielonego + transportu OpenAI, ale potrzebuje normalizacji ładunku thinking należącej do dostawcy; rodzina + streamów `moonshot-thinking` mapuje konfigurację oraz stan `/think` na + natywny binarny ładunek thinking. - Kilocode używa `catalog`, `capabilities`, `wrapStreamFn` i `isCacheTtlEligible`, ponieważ potrzebuje nagłówków żądań należących do dostawcy, - normalizacji payload reasoning, wskazówek dla transkryptu Gemini oraz bramkowania - cache-TTL Anthropic; rodzina streamów `kilocode-thinking` utrzymuje wstrzykiwanie - Kilo thinking na współdzielonej ścieżce streamu proxy, jednocześnie pomijając `kilo/auto` i - inne identyfikatory modeli proxy, które nie obsługują jawnych payloadów reasoning. + normalizacji ładunku reasoning, wskazówek dla transkryptów Gemini oraz bramkowania + cache-TTL dla Anthropic; rodzina streamów `kilocode-thinking` utrzymuje + wstrzykiwanie Kilo thinking na współdzielonej ścieżce stream proxy, pomijając `kilo/auto` + i inne identyfikatory modeli proxy, które nie wspierają jawnych ładunków reasoning. - Z.AI używa `resolveDynamicModel`, `prepareExtraParams`, `wrapStreamFn`, `isCacheTtlEligible`, `isBinaryThinking`, `isModernModelRef`, `resolveUsageAuth` i `fetchUsageSnapshot`, ponieważ obsługuje fallback GLM-5, - domyślne `tool_stream`, UX binarnego thinking, dopasowywanie nowoczesnych modeli oraz zarówno - usage auth, jak i pobieranie quota; rodzina streamów `tool-stream-default-on` utrzymuje - wrapper `tool_stream` włączony domyślnie poza ręcznie pisanym glue per dostawca. + domyślne `tool_stream`, UX binarnego thinking, dopasowywanie nowoczesnych modeli oraz + zarówno auth użycia, jak i pobieranie kwot; rodzina streamów `tool-stream-default-on` + utrzymuje wrapper `tool_stream` włączony domyślnie poza ręcznie pisanym klejem dla poszczególnych dostawców. - xAI używa `normalizeResolvedModel`, `normalizeTransport`, `contributeResolvedModelCompat`, `prepareExtraParams`, `wrapStreamFn`, `resolveSyntheticAuth`, `resolveDynamicModel` i `isModernModelRef`, ponieważ obsługuje natywną normalizację transportu xAI Responses, przepisywanie aliasów - trybu fast Grok, domyślne `tool_stream`, czyszczenie strict-tool / reasoning-payload, - ponowne użycie fallback auth dla narzędzi należących do pluginu, rozstrzyganie modeli Grok zgodne z przyszłością - oraz poprawki zgodności należące do dostawcy, takie jak profil schematu narzędzi xAI, - nieobsługiwane słowa kluczowe schematu, natywne `web_search` i dekodowanie argumentów wywołań narzędzi z encji HTML. -- Mistral, OpenCode Zen i OpenCode Go używają tylko `capabilities`, aby trzymać - specyficzne zachowania transkryptów/narzędzi poza rdzeniem. -- Bundlowani dostawcy tylko katalogowi, tacy jak `byteplus`, `cloudflare-ai-gateway`, + Grok fast-mode, domyślne `tool_stream`, porządkowanie strict-tool / reasoning-payload, + ponowne użycie fallback auth dla narzędzi należących do pluginu, zgodne z przyszłością rozstrzyganie modeli Grok + oraz łatki kompatybilności należące do dostawcy, takie jak profil schematu narzędzi xAI, + nieobsługiwane słowa kluczowe schematu, natywne `web_search` i dekodowanie argumentów + wywołań narzędzi z encji HTML. +- Mistral, OpenCode Zen i OpenCode Go używają wyłącznie `capabilities`, aby + utrzymać niuanse transkryptów/narzędzi poza core. +- Dołączone providery tylko-katalogowe, takie jak `byteplus`, `cloudflare-ai-gateway`, `huggingface`, `kimi-coding`, `nvidia`, `qianfan`, `synthetic`, `together`, `venice`, `vercel-ai-gateway` i `volcengine`, używają - tylko `catalog`. + wyłącznie `catalog`. - Qwen używa `catalog` dla swojego dostawcy tekstu oraz współdzielonych rejestracji - media-understanding i video-generation dla swoich powierzchni multimodalnych. + media-understanding i video-generation dla swoich multimodalnych powierzchni. - MiniMax i Xiaomi używają `catalog` oraz hooków użycia, ponieważ ich zachowanie `/usage` - należy do pluginu, mimo że wnioskowanie nadal działa przez współdzielone transporty. + należy do pluginu, mimo że inferencja nadal działa przez współdzielone transporty. -## Pomocniki runtime +## Helpery runtime -Pluginy mogą uzyskać dostęp do wybranych pomocników rdzenia przez `api.runtime`. Dla TTS: +Pluginy mogą uzyskiwać dostęp do wybranych helperów core przez `api.runtime`. Dla TTS: ```ts const clip = await api.runtime.tts.textToSpeech({ @@ -901,14 +910,14 @@ const voices = await api.runtime.tts.listVoices({ Uwagi: -- `textToSpeech` zwraca zwykły payload wyjściowy TTS rdzenia dla powierzchni plików/notatek głosowych. -- Używa konfiguracji rdzeniowej `messages.tts` oraz wyboru dostawcy. -- Zwraca bufor audio PCM + częstotliwość próbkowania. Pluginy muszą przeskalować/zakodować je dla dostawców. -- `listVoices` jest opcjonalne per dostawca. Używaj go w pickerach głosów lub przepływach setup należących do dostawcy. -- Listy głosów mogą zawierać bogatsze metadane, takie jak locale, płeć i tagi osobowości dla pickerów świadomych dostawcy. -- OpenAI i ElevenLabs obsługują dziś telefonię. Microsoft nie. +- `textToSpeech` zwraca standardowy ładunek wyjściowy TTS core dla powierzchni plików/notatek głosowych. +- Używa konfiguracji core `messages.tts` i wyboru dostawcy. +- Zwraca bufor audio PCM + częstotliwość próbkowania. Pluginy muszą wykonać resampling/kodowanie dla dostawców. +- `listVoices` jest opcjonalne per dostawca. Używaj tego dla selektorów głosów lub przepływów konfiguracji należących do dostawcy. +- Listy głosów mogą zawierać bogatsze metadane, takie jak locale, gender i tagi personality dla selektorów świadomych dostawcy. +- OpenAI i ElevenLabs wspierają dziś telefonię. Microsoft nie. -Pluginy mogą też rejestrować dostawców mowy przez `api.registerSpeechProvider(...)`. +Pluginy mogą również rejestrować dostawców mowy przez `api.registerSpeechProvider(...)`. ```ts api.registerSpeechProvider({ @@ -928,15 +937,15 @@ api.registerSpeechProvider({ Uwagi: -- Zachowaj politykę TTS, fallback i dostarczanie odpowiedzi w rdzeniu. -- Używaj dostawców mowy do zachowań syntezy należących do dostawcy. -- Starsze wejście Microsoft `edge` jest normalizowane do identyfikatora dostawcy `microsoft`. -- Preferowany model własności jest zorientowany na firmę: jeden plugin dostawcy może posiadać - dostawców tekstu, mowy, obrazów i przyszłych mediów, gdy OpenClaw dodaje te - kontrakty możliwości. +- Utrzymuj politykę TTS, fallback i dostarczanie odpowiedzi w core. +- Używaj dostawców mowy dla zachowań syntezy należących do dostawcy. +- Legacy wartość wejściowa Microsoft `edge` jest normalizowana do identyfikatora dostawcy `microsoft`. +- Preferowany model własności jest zorientowany firmowo: jeden plugin dostawcy może obsługiwać + tekst, mowę, obraz i przyszłych dostawców mediów, gdy OpenClaw doda ich + kontrakty capability. -W przypadku rozumienia obrazów/audio/wideo pluginy rejestrują jednego typowanego -dostawcę media-understanding zamiast ogólnego worka klucz/wartość: +Dla rozumienia obrazów/audio/wideo pluginy rejestrują jednego typowanego +dostawcę media-understanding zamiast ogólnej torby klucz/wartość: ```ts api.registerMediaUnderstandingProvider({ @@ -950,16 +959,16 @@ api.registerMediaUnderstandingProvider({ Uwagi: -- Zachowaj orkiestrację, fallback, konfigurację i integrację kanałów w rdzeniu. -- Zachowaj zachowanie dostawcy w pluginie dostawcy. +- Utrzymuj orkiestrację, fallback, konfigurację i podłączenie kanałów w core. +- Utrzymuj zachowanie dostawcy w pluginie dostawcy. - Rozszerzanie addytywne powinno pozostać typowane: nowe opcjonalne metody, nowe opcjonalne - pola wyniku, nowe opcjonalne możliwości. -- Generowanie wideo już podąża za tym samym wzorcem: - - rdzeń posiada kontrakt możliwości i pomocnik runtime + pola wyników, nowe opcjonalne capabilities. +- Generowanie wideo już podąża tym samym wzorcem: + - core obsługuje kontrakt capability i helper runtime - pluginy dostawców rejestrują `api.registerVideoGenerationProvider(...)` - - pluginy funkcji/kanałów korzystają z `api.runtime.videoGeneration.*` + - pluginy funkcjonalne/kanałów korzystają z `api.runtime.videoGeneration.*` -Dla pomocników runtime media-understanding pluginy mogą wywoływać: +Dla helperów runtime media-understanding pluginy mogą wywoływać: ```ts const image = await api.runtime.mediaUnderstanding.describeImageFile({ @@ -974,27 +983,27 @@ const video = await api.runtime.mediaUnderstanding.describeVideoFile({ }); ``` -W przypadku transkrypcji audio pluginy mogą używać albo runtime media-understanding, +Dla transkrypcji audio pluginy mogą używać albo runtime media-understanding, albo starszego aliasu STT: ```ts const { text } = await api.runtime.mediaUnderstanding.transcribeAudioFile({ filePath: "/tmp/inbound-audio.ogg", cfg: api.config, - // Opcjonalne, gdy nie można wiarygodnie wywnioskować MIME: + // Optional when MIME cannot be inferred reliably: mime: "audio/ogg", }); ``` Uwagi: -- `api.runtime.mediaUnderstanding.*` to preferowana współdzielona powierzchnia dla +- `api.runtime.mediaUnderstanding.*` jest preferowaną współdzieloną powierzchnią dla rozumienia obrazów/audio/wideo. -- Używa konfiguracji audio media-understanding rdzenia (`tools.media.audio`) oraz kolejności fallback dostawców. -- Zwraca `{ text: undefined }`, gdy nie został wygenerowany wynik transkrypcji (na przykład przy pominiętym/nieobsługiwanym wejściu). -- `api.runtime.stt.transcribeAudioFile(...)` pozostaje aliasem zgodności. +- Używa konfiguracji audio media-understanding core (`tools.media.audio`) oraz kolejności fallback dostawców. +- Zwraca `{ text: undefined }`, gdy nie zostanie wygenerowany wynik transkrypcji (na przykład dla pominiętego/nieobsługiwanego wejścia). +- `api.runtime.stt.transcribeAudioFile(...)` pozostaje aliasem kompatybilności. -Pluginy mogą także uruchamiać w tle przebiegi subagenta przez `api.runtime.subagent`: +Pluginy mogą również uruchamiać podrzędne przebiegi subagentów w tle przez `api.runtime.subagent`: ```ts const result = await api.runtime.subagent.run({ @@ -1008,14 +1017,14 @@ const result = await api.runtime.subagent.run({ Uwagi: -- `provider` i `model` to opcjonalne nadpisania per uruchomienie, a nie trwałe zmiany sesji. -- OpenClaw honoruje te pola nadpisania tylko dla zaufanych wywołujących. -- W przypadku przebiegów fallback należących do pluginu operatorzy muszą wyrazić zgodę przez `plugins.entries..subagent.allowModelOverride: true`. -- Użyj `plugins.entries..subagent.allowedModels`, aby ograniczyć zaufane pluginy do określonych kanonicznych celów `provider/model`, albo `"*"`, aby jawnie zezwolić na dowolny cel. -- Przebiegi subagentów z niezaufanych pluginów nadal działają, ale żądania nadpisania są odrzucane zamiast cicho przechodzić na fallback. +- `provider` i `model` są opcjonalnymi nadpisaniami dla pojedynczego uruchomienia, a nie trwałymi zmianami sesji. +- OpenClaw honoruje te pola nadpisania wyłącznie dla zaufanych wywołujących. +- Dla przebiegów fallback należących do pluginu operatorzy muszą jawnie wyrazić zgodę przez `plugins.entries..subagent.allowModelOverride: true`. +- Użyj `plugins.entries..subagent.allowedModels`, aby ograniczyć zaufane pluginy do konkretnych kanonicznych celów `provider/model`, albo `"*"`, aby jawnie dopuścić dowolny cel. +- Niezaufane przebiegi subagentów nadal działają, ale żądania nadpisania są odrzucane zamiast cicho przechodzić do fallback. -W przypadku web search pluginy mogą korzystać ze współdzielonego pomocnika runtime zamiast -sięgać do integracji narzędzia agenta: +Dla web search pluginy mogą korzystać ze współdzielonego helpera runtime zamiast +sięgać do podłączenia narzędzia agenta: ```ts const providers = api.runtime.webSearch.listProviders({ @@ -1031,14 +1040,14 @@ const result = await api.runtime.webSearch.search({ }); ``` -Pluginy mogą też rejestrować dostawców web-search przez +Pluginy mogą również rejestrować dostawców web-search przez `api.registerWebSearchProvider(...)`. Uwagi: -- Zachowaj wybór dostawcy, rozwiązywanie poświadczeń i współdzieloną semantykę żądań w rdzeniu. +- Utrzymuj wybór dostawcy, rozstrzyganie poświadczeń i współdzieloną semantykę żądań w core. - Używaj dostawców web-search dla transportów wyszukiwania specyficznych dla dostawcy. -- `api.runtime.webSearch.*` to preferowana współdzielona powierzchnia dla pluginów funkcji/kanałów, które potrzebują zachowania wyszukiwania bez zależności od wrappera narzędzia agenta. +- `api.runtime.webSearch.*` jest preferowaną współdzieloną powierzchnią dla pluginów funkcjonalnych/kanałów, które potrzebują zachowania wyszukiwania bez zależności od wrappera narzędzia agenta. ### `api.runtime.imageGeneration` @@ -1053,12 +1062,12 @@ const providers = api.runtime.imageGeneration.listProviders({ }); ``` -- `generate(...)`: generuje obraz z użyciem skonfigurowanego łańcucha dostawców generowania obrazów. -- `listProviders(...)`: wyświetla dostępnych dostawców generowania obrazów i ich możliwości. +- `generate(...)`: wygeneruj obraz przy użyciu skonfigurowanego łańcucha dostawców generowania obrazów. +- `listProviders(...)`: wyświetl dostępnych dostawców generowania obrazów i ich capabilities. -## Trasy HTTP Gatewaya +## Trasy HTTP Gateway -Pluginy mogą udostępniać endpointy HTTP przez `api.registerHttpRoute(...)`. +Pluginy mogą wystawiać endpointy HTTP przez `api.registerHttpRoute(...)`. ```ts api.registerHttpRoute({ @@ -1075,32 +1084,32 @@ api.registerHttpRoute({ Pola trasy: -- `path`: ścieżka trasy pod serwerem HTTP gatewaya. -- `auth`: wymagane. Użyj `"gateway"`, aby wymagać zwykłego auth gatewaya, albo `"plugin"` dla auth/weryfikacji webhooka zarządzanych przez plugin. +- `path`: ścieżka trasy pod serwerem HTTP gateway. +- `auth`: wymagane. Użyj `"gateway"`, aby wymagać zwykłego auth gateway, albo `"plugin"` dla auth zarządzanego przez plugin / weryfikacji webhooka. - `match`: opcjonalne. `"exact"` (domyślnie) albo `"prefix"`. - `replaceExisting`: opcjonalne. Pozwala temu samemu pluginowi zastąpić własną istniejącą rejestrację trasy. -- `handler`: zwraca `true`, gdy trasa obsłużyła żądanie. +- `handler`: zwróć `true`, gdy trasa obsłużyła żądanie. Uwagi: -- `api.registerHttpHandler(...)` zostało usunięte i spowoduje błąd ładowania pluginu. Użyj zamiast tego `api.registerHttpRoute(...)`. +- `api.registerHttpHandler(...)` zostało usunięte i spowoduje błąd ładowania pluginu. Używaj `api.registerHttpRoute(...)`. - Trasy pluginów muszą jawnie deklarować `auth`. -- Konflikty dokładnych `path + match` są odrzucane, chyba że `replaceExisting: true`, a jeden plugin nie może zastąpić trasy innego pluginu. -- Nakładające się trasy z różnymi poziomami `auth` są odrzucane. Łańcuchy przejść `exact`/`prefix` utrzymuj tylko na tym samym poziomie auth. -- Trasy `auth: "plugin"` **nie** otrzymują automatycznie operatorowych zakresów runtime. Służą do webhooków/weryfikacji podpisów zarządzanych przez plugin, a nie uprzywilejowanych wywołań pomocników Gatewaya. -- Trasy `auth: "gateway"` działają wewnątrz zakresu runtime żądania Gatewaya, ale ten zakres jest celowo konserwatywny: - - uwierzytelnianie bearer współdzielonym sekretem (`gateway.auth.mode = "token"` / `"password"`) utrzymuje zakresy runtime trasy pluginu przypięte do `operator.write`, nawet jeśli wywołujący wysyła `x-openclaw-scopes` - - zaufane tryby HTTP niosące tożsamość (na przykład `trusted-proxy` albo `gateway.auth.mode = "none"` na prywatnym ingressie) honorują `x-openclaw-scopes` tylko wtedy, gdy nagłówek jest jawnie obecny - - jeśli `x-openclaw-scopes` jest nieobecny w takich żądaniach trasy pluginu niosących tożsamość, zakres runtime wraca do `operator.write` -- Praktyczna zasada: nie zakładaj, że trasa pluginu z auth gatewaya jest domyślnie powierzchnią administracyjną. Jeśli Twoja trasa wymaga zachowania tylko dla admina, wymagaj trybu auth niosącego tożsamość i udokumentuj jawny kontrakt nagłówka `x-openclaw-scopes`. +- Konflikty dokładnego `path + match` są odrzucane, chyba że ustawiono `replaceExisting: true`, i jeden plugin nie może zastąpić trasy innego pluginu. +- Nakładające się trasy z różnymi poziomami `auth` są odrzucane. Utrzymuj łańcuchy przejścia `exact`/`prefix` tylko na tym samym poziomie auth. +- Trasy `auth: "plugin"` **nie** otrzymują automatycznie zakresów runtime operatora. Służą do webhooków / weryfikacji podpisów zarządzanych przez plugin, a nie do uprzywilejowanych wywołań helperów Gateway. +- Trasy `auth: "gateway"` działają wewnątrz zakresu runtime żądania Gateway, ale ten zakres jest celowo zachowawczy: + - bearer auth oparty na współdzielonym sekrecie (`gateway.auth.mode = "token"` / `"password"`) utrzymuje zakresy runtime tras pluginów przypięte do `operator.write`, nawet jeśli wywołujący wysyła `x-openclaw-scopes` + - zaufane tryby HTTP z tożsamością (na przykład `trusted-proxy` albo `gateway.auth.mode = "none"` na prywatnym ingressie) honorują `x-openclaw-scopes` tylko wtedy, gdy nagłówek jest jawnie obecny + - jeśli w takich żądaniach tras pluginów z tożsamością brakuje `x-openclaw-scopes`, zakres runtime wraca do `operator.write` +- Praktyczna zasada: nie zakładaj, że trasa pluginu z auth gateway jest domyślnie powierzchnią administracyjną. Jeśli trasa wymaga zachowania tylko dla administratora, wymagaj trybu auth z tożsamością i udokumentuj jawny kontrakt nagłówka `x-openclaw-scopes`. ## Ścieżki importu Plugin SDK -Podczas tworzenia pluginów używaj podścieżek SDK zamiast monolitycznego importu `openclaw/plugin-sdk`: +Przy tworzeniu pluginów używaj subścieżek SDK zamiast monolitycznego importu `openclaw/plugin-sdk`: - `openclaw/plugin-sdk/plugin-entry` dla prymitywów rejestracji pluginów. - `openclaw/plugin-sdk/core` dla ogólnego współdzielonego kontraktu skierowanego do pluginów. -- `openclaw/plugin-sdk/config-schema` dla eksportu schematu Zod głównego `openclaw.json` +- `openclaw/plugin-sdk/config-schema` dla eksportu głównego schematu Zod `openclaw.json` (`OpenClawSchema`). - Stabilne prymitywy kanałów, takie jak `openclaw/plugin-sdk/channel-setup`, `openclaw/plugin-sdk/setup-runtime`, @@ -1114,18 +1123,17 @@ Podczas tworzenia pluginów używaj podścieżek SDK zamiast monolitycznego impo `openclaw/plugin-sdk/channel-reply-pipeline`, `openclaw/plugin-sdk/command-auth`, `openclaw/plugin-sdk/secret-input` i - `openclaw/plugin-sdk/webhook-ingress` dla współdzielonej integracji setup/auth/reply/webhook. - `channel-inbound` to współdzielony dom dla debounce, dopasowywania wzmianek, - pomocników polityki wzmianek przychodzących, formatowania kopert i pomocników - kontekstu kopert przychodzących. - `channel-setup` to wąska szczelina setup z opcjonalną instalacją. - `setup-runtime` to bezpieczna dla runtime powierzchnia setup używana przez `setupEntry` / - odroczone uruchamianie, w tym adaptery łatek setup bezpieczne przy imporcie. - `setup-adapter-runtime` to szczelina adaptera setup kont świadoma env. - `setup-tools` to mała szczelina pomocników CLI/archive/docs (`formatCliCommand`, + `openclaw/plugin-sdk/webhook-ingress` dla współdzielonego podłączania + konfiguracji/auth/odpowiedzi/webhooków. `channel-inbound` jest współdzielonym domem dla debounce, dopasowywania mention, + helperów polityki mention przychodzących, formatowania kopert oraz helperów kontekstu kopert przychodzących. + `channel-setup` to wąska granica konfiguracji opcjonalnej instalacji. + `setup-runtime` to bezpieczna w runtime powierzchnia konfiguracji używana przez `setupEntry` / + odroczony start, w tym bezpieczne importowo adaptery łatek konfiguracji. + `setup-adapter-runtime` to granica adaptera konfiguracji kont świadoma env. + `setup-tools` to mała granica helperów CLI/archiwów/dokumentacji (`formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR`). -- Podścieżki domenowe, takie jak `openclaw/plugin-sdk/channel-config-helpers`, +- Subścieżki domenowe, takie jak `openclaw/plugin-sdk/channel-config-helpers`, `openclaw/plugin-sdk/allow-from`, `openclaw/plugin-sdk/channel-config-schema`, `openclaw/plugin-sdk/telegram-command-config`, @@ -1143,128 +1151,130 @@ Podczas tworzenia pluginów używaj podścieżek SDK zamiast monolitycznego impo `openclaw/plugin-sdk/status-helpers`, `openclaw/plugin-sdk/text-runtime`, `openclaw/plugin-sdk/runtime-store` i - `openclaw/plugin-sdk/directory-runtime` dla współdzielonych pomocników runtime/config. - `telegram-command-config` to wąska publiczna szczelina do normalizacji/walidacji niestandardowych - poleceń Telegram i pozostaje dostępna nawet wtedy, gdy powierzchnia kontraktu bundlowanego - Telegram jest tymczasowo niedostępna. - `text-runtime` to współdzielona szczelina tekst/markdown/logowanie, w tym - usuwanie tekstu widocznego dla asystenta, pomocniki renderowania/dzielenia markdown, - pomocniki redakcji, pomocniki tagów dyrektyw i bezpieczne narzędzia tekstowe. -- Szczeliny kanałów specyficzne dla zatwierdzeń powinny preferować jeden kontrakt - `approvalCapability` na pluginie. Rdzeń odczytuje wtedy auth zatwierdzeń, dostarczanie, renderowanie, - natywne routowanie i leniwe zachowanie natywnego handlera przez tę jedną możliwość - zamiast mieszać zachowanie zatwierdzeń z niezwiązanymi polami pluginu. + `openclaw/plugin-sdk/directory-runtime` dla współdzielonych helperów runtime/konfiguracji. + `telegram-command-config` to wąska publiczna granica dla normalizacji/walidacji niestandardowych komend Telegram + i pozostaje dostępna nawet wtedy, gdy dołączona powierzchnia kontraktu Telegram jest tymczasowo niedostępna. + `text-runtime` to współdzielona granica tekst/markdown/logowanie, obejmująca + usuwanie tekstu widocznego dla asystenta, helpery renderowania/dzielenia markdown, + helpery redakcji, helpery tagów dyrektyw i bezpieczne narzędzia tekstowe. +- Granice kanałów specyficzne dla zatwierdzeń powinny preferować jeden kontrakt + `approvalCapability` na pluginie. Core odczytuje wtedy auth zatwierdzeń, dostarczanie, renderowanie, + routing natywny i leniwe zachowanie natywnych handlerów przez tę jedną capability + zamiast mieszać zachowanie zatwierdzeń z niepowiązanymi polami pluginu. - `openclaw/plugin-sdk/channel-runtime` jest przestarzałe i pozostaje jedynie jako - shim zgodności dla starszych pluginów. Nowy kod powinien importować węższe ogólne prymitywy, a kod repo nie powinien dodawać nowych importów tego shimu. -- Wnętrza bundlowanych rozszerzeń pozostają prywatne. Zewnętrzne pluginy powinny używać wyłącznie podścieżek `openclaw/plugin-sdk/*`. Kod rdzenia/testów OpenClaw może używać publicznych punktów wejścia repo pod korzeniem pakietu pluginu, takich jak `index.js`, `api.js`, - `runtime-api.js`, `setup-entry.js` oraz wąsko zakresowanych plików takich jak - `login-qr-api.js`. Nigdy nie importuj `src/*` pakietu pluginu z rdzenia ani z - innego rozszerzenia. + shim kompatybilności dla starszych pluginów. Nowy kod powinien importować węższe + ogólne prymitywy, a kod repo nie powinien dodawać nowych importów tego shima. +- Wnętrza dołączonych rozszerzeń pozostają prywatne. Pluginy zewnętrzne powinny używać wyłącznie + subścieżek `openclaw/plugin-sdk/*`. Kod/testy core OpenClaw mogą używać publicznych punktów wejścia repo + pod katalogiem głównym pakietu pluginu, takich jak `index.js`, `api.js`, + `runtime-api.js`, `setup-entry.js` oraz wąsko wyspecjalizowanych plików takich jak + `login-qr-api.js`. Nigdy nie importuj `src/*` pakietu pluginu z core ani z innego rozszerzenia. - Podział punktów wejścia repo: - `/api.js` to barrel pomocników/typów, - `/runtime-api.js` to barrel tylko runtime, - `/index.js` to punkt wejścia bundlowanego pluginu, - a `/setup-entry.js` to punkt wejścia pluginu setup. -- Obecne przykłady bundlowanych dostawców: - - Anthropic używa `api.js` / `contract-api.js` dla pomocników streamów Claude, takich - jak `wrapAnthropicProviderStream`, pomocników nagłówków beta i parsowania `service_tier`. - - OpenAI używa `api.js` dla builderów dostawców, pomocników modeli domyślnych i - builderów dostawców realtime. - - OpenRouter używa `api.js` dla swojego buildera dostawcy oraz pomocników onboarding/config, - podczas gdy `register.runtime.js` może nadal reeksportować ogólne - pomocniki `plugin-sdk/provider-stream` do lokalnego użycia w repo. + `/api.js` jest barrelem helperów/typów, + `/runtime-api.js` jest barrelem tylko runtime, + `/index.js` jest punktem wejścia dołączonego pluginu, + a `/setup-entry.js` jest punktem wejścia pluginu konfiguracji. +- Aktualne przykłady dołączonych dostawców: + - Anthropic używa `api.js` / `contract-api.js` dla helperów strumieni Claude, takich + jak `wrapAnthropicProviderStream`, helpery nagłówków beta i parsowanie `service_tier`. + - OpenAI używa `api.js` dla builderów providerów, helperów modeli domyślnych i + builderów providerów realtime. + - OpenRouter używa `api.js` dla swojego buildera providera oraz helperów onboardingu/konfiguracji, + podczas gdy `register.runtime.js` może nadal re-eksportować ogólne + helpery `plugin-sdk/provider-stream` do użytku lokalnego w repo. - Publiczne punkty wejścia ładowane przez fasadę preferują aktywny snapshot konfiguracji runtime, - jeśli istnieje, a następnie wracają do rozstrzygniętego pliku konfiguracji na dysku, gdy + gdy taki istnieje, a następnie wracają do rozstrzygniętego pliku konfiguracji na dysku, gdy OpenClaw nie udostępnia jeszcze snapshotu runtime. - Ogólne współdzielone prymitywy pozostają preferowanym publicznym kontraktem SDK. Nadal istnieje mały - zastrzeżony zestaw zgodności pomocniczych szczelin markowanych przez bundlowane kanały. Traktuj je jako - szczeliny utrzymania bundli/zgodności, a nie nowe cele importu dla stron trzecich; nowe kontrakty - międzykanałowe powinny nadal trafiać do ogólnych podścieżek `plugin-sdk/*` albo do lokalnych barrelów pluginu `api.js` / - `runtime-api.js`. + zastrzeżony zestaw granic helperów dołączonych kanałów oznaczonych marką kanału. Traktuj je jako + granice utrzymaniowe/kompatybilnościowe dołączonych pluginów, a nie nowe cele importu dla stron trzecich; nowe kontrakty międzykanałowe nadal powinny trafiać do + ogólnych subścieżek `plugin-sdk/*` albo do lokalnych barrelów `api.js` / + `runtime-api.js` pluginu. -Uwaga o zgodności: +Uwaga dotycząca kompatybilności: -- Unikaj głównego barrela `openclaw/plugin-sdk` w nowym kodzie. -- Najpierw preferuj wąskie stabilne prymitywy. Nowsze podścieżki setup/pairing/reply/ +- Dla nowego kodu unikaj głównego barrelu `openclaw/plugin-sdk`. +- Najpierw preferuj wąskie stabilne prymitywy. Nowsze subścieżki setup/pairing/reply/ feedback/contract/inbound/threading/command/secret-input/webhook/infra/ - allowlist/status/message-tool to zamierzony kontrakt dla nowych - bundlowanych i zewnętrznych pluginów. - Parsowanie/dopasowywanie celów należy do `openclaw/plugin-sdk/channel-targets`. - Bramki działań message i pomocniki identyfikatora wiadomości reakcji należą do + allowlist/status/message-tool są docelowym kontraktem dla nowych + prac nad dołączonymi i zewnętrznymi pluginami. + Parsowanie/dopasowywanie targetów należy do `openclaw/plugin-sdk/channel-targets`. + Bramki działań wiadomości i helpery identyfikatorów wiadomości reakcji należą do `openclaw/plugin-sdk/channel-actions`. -- Barrels pomocnicze specyficzne dla bundlowanych rozszerzeń nie są domyślnie stabilne. Jeśli - jakiś pomocnik jest potrzebny tylko bundlowanemu rozszerzeniu, trzymaj go za lokalną szczeliną - `api.js` albo `runtime-api.js` tego rozszerzenia zamiast promować go do +- Barrele helperów specyficznych dla dołączonych rozszerzeń nie są domyślnie stabilne. Jeśli + helper jest potrzebny tylko dołączonemu rozszerzeniu, trzymaj go za lokalną granicą + `api.js` lub `runtime-api.js` rozszerzenia zamiast promować go do `openclaw/plugin-sdk/`. -- Nowe współdzielone szczeliny pomocnicze powinny być ogólne, a nie markowane przez kanał. Współdzielone parsowanie celów należy do `openclaw/plugin-sdk/channel-targets`; wnętrza specyficzne dla kanału pozostają za lokalną szczeliną `api.js` albo `runtime-api.js` - należącą do odpowiedniego pluginu. -- Podścieżki specyficzne dla możliwości, takie jak `image-generation`, - `media-understanding` i `speech`, istnieją, ponieważ bundlowane/natywne pluginy używają - ich już dziś. Ich obecność nie oznacza sama w sobie, że każdy eksportowany pomocnik jest +- Nowe współdzielone granice helperów powinny być ogólne, a nie oznaczone marką kanału. Współdzielone parsowanie + targetów należy do `openclaw/plugin-sdk/channel-targets`; wnętrza specyficzne dla kanału + pozostają za lokalną granicą `api.js` lub `runtime-api.js` należącego pluginu. +- Subścieżki specyficzne dla capability, takie jak `image-generation`, + `media-understanding` i `speech`, istnieją, ponieważ dołączone/natywne pluginy używają + ich dziś. Ich obecność sama w sobie nie oznacza, że każdy eksportowany helper jest długoterminowym zamrożonym kontraktem zewnętrznym. -## Schematy narzędzia message +## Schematy narzędzia wiadomości -Pluginy powinny posiadać wkład do schematu `describeMessageTool(...)` specyficzny dla kanału. -Pola specyficzne dla dostawcy trzymaj w pluginie, a nie we współdzielonym rdzeniu. +Pluginy powinny obsługiwać wkłady do schematu `describeMessageTool(...)` +specyficzne dla kanału. Pola specyficzne dla dostawcy trzymaj w pluginie, a nie we współdzielonym core. -Dla współdzielonych przenośnych fragmentów schematu używaj ogólnych pomocników eksportowanych przez +Dla współdzielonych, przenośnych fragmentów schematu używaj ponownie ogólnych helperów eksportowanych przez `openclaw/plugin-sdk/channel-actions`: -- `createMessageToolButtonsSchema()` dla payloadów w stylu siatki przycisków -- `createMessageToolCardSchema()` dla payloadów ustrukturyzowanych kart +- `createMessageToolButtonsSchema()` dla ładunków w stylu siatki przycisków +- `createMessageToolCardSchema()` dla ustrukturyzowanych ładunków kart -Jeśli jakiś kształt schematu ma sens tylko dla jednego dostawcy, definiuj go w -własnym źródle tego pluginu, zamiast promować go do współdzielonego SDK. +Jeśli dany kształt schematu ma sens tylko dla jednego dostawcy, zdefiniuj go w +kodzie źródłowym tego pluginu zamiast promować go do współdzielonego SDK. -## Rozstrzyganie celów kanału +## Rozstrzyganie targetów kanałów -Pluginy kanałów powinny posiadać semantykę celów specyficzną dla kanału. Zachowaj -współdzielonego hosta outbound jako ogólnego i używaj powierzchni adaptera wiadomości dla reguł dostawcy: +Pluginy kanałów powinny obsługiwać semantykę targetów specyficzną dla kanału. Utrzymuj +wspólny host outbound jako ogólny i używaj powierzchni adaptera komunikacji dla reguł dostawcy: -- `messaging.inferTargetChatType({ to })` decyduje, czy znormalizowany cel - powinien być traktowany jako `direct`, `group` czy `channel` przed wyszukaniem w katalogu. -- `messaging.targetResolver.looksLikeId(raw, normalized)` mówi rdzeniowi, czy dane +- `messaging.inferTargetChatType({ to })` decyduje, czy znormalizowany target + ma być traktowany jako `direct`, `group` czy `channel` przed wyszukaniem w katalogu. +- `messaging.targetResolver.looksLikeId(raw, normalized)` informuje core, czy dane wejście powinno od razu przejść do rozstrzygania podobnego do identyfikatora zamiast do wyszukiwania w katalogu. -- `messaging.targetResolver.resolveTarget(...)` to fallback pluginu, gdy - rdzeń potrzebuje ostatecznego rozstrzygnięcia należącego do dostawcy po normalizacji albo po - braku trafienia w katalogu. -- `messaging.resolveOutboundSessionRoute(...)` obsługuje budowę trasy sesji - specyficznej dla dostawcy po rozstrzygnięciu celu. +- `messaging.targetResolver.resolveTarget(...)` jest fallbackiem pluginu, gdy + core potrzebuje końcowego rozstrzygnięcia należącego do dostawcy po normalizacji albo po + nieudanym wyszukaniu w katalogu. +- `messaging.resolveOutboundSessionRoute(...)` obsługuje budowę trasy sesji specyficznej dla dostawcy po rozstrzygnięciu targetu. Zalecany podział: -- Używaj `inferTargetChatType` do decyzji kategorycznych, które powinny nastąpić przed +- Używaj `inferTargetChatType` dla decyzji kategorialnych, które powinny zapaść przed wyszukiwaniem peerów/grup. -- Używaj `looksLikeId` do sprawdzeń typu „traktuj to jako jawny/natywny identyfikator celu”. -- Używaj `resolveTarget` jako fallback normalizacji specyficzny dla dostawcy, a nie do +- Używaj `looksLikeId` dla sprawdzeń typu „traktuj to jako jawny/natywny identyfikator targetu”. +- Używaj `resolveTarget` jako fallbacku normalizacji specyficznego dla dostawcy, a nie do szerokiego wyszukiwania katalogowego. -- Natywne identyfikatory dostawcy, takie jak identyfikatory czatu, identyfikatory wątków, JID-y, handle i identyfikatory pokojów trzymaj w wartościach `target` albo parametrach specyficznych dla dostawcy, a nie w ogólnych polach SDK. +- Natywne identyfikatory dostawcy, takie jak chat ids, thread ids, JIDs, handles i room + ids, trzymaj w wartościach `target` albo parametrach specyficznych dla dostawcy, a nie w ogólnych polach SDK. ## Katalogi oparte na konfiguracji -Pluginy, które wyprowadzają wpisy katalogu z konfiguracji, powinny utrzymywać tę logikę w -pluginie i ponownie wykorzystywać współdzielone pomocniki z +Pluginy, które wyprowadzają wpisy katalogowe z konfiguracji, powinny utrzymywać tę logikę w +pluginie i używać ponownie współdzielonych helperów z `openclaw/plugin-sdk/directory-runtime`. Używaj tego, gdy kanał potrzebuje peerów/grup opartych na konfiguracji, takich jak: - peery DM oparte na allowliście - skonfigurowane mapy kanałów/grup -- statyczne fallbacki katalogu w zakresie konta +- statyczne fallbacki katalogowe zależne od konta -Współdzielone pomocniki w `directory-runtime` obsługują tylko operacje ogólne: +Współdzielone helpery w `directory-runtime` obsługują tylko ogólne operacje: - filtrowanie zapytań - stosowanie limitów -- pomocniki deduplikacji/normalizacji +- helpery deduplikacji/normalizacji - budowanie `ChannelDirectoryEntry[]` -Inspekcja kont specyficzna dla kanału i normalizacja identyfikatorów powinny pozostać w implementacji pluginu. +Inspekcja kont i normalizacja identyfikatorów specyficzna dla kanału powinna pozostać w implementacji pluginu. ## Katalogi dostawców -Pluginy dostawców mogą definiować katalogi modeli dla wnioskowania przez +Pluginy dostawców mogą definiować katalogi modeli do inferencji przez `registerProvider({ catalog: { run(...) { ... } } })`. `catalog.run(...)` zwraca ten sam kształt, który OpenClaw zapisuje do @@ -1273,53 +1283,56 @@ Pluginy dostawców mogą definiować katalogi modeli dla wnioskowania przez - `{ provider }` dla jednego wpisu dostawcy - `{ providers }` dla wielu wpisów dostawców -Używaj `catalog`, gdy plugin posiada identyfikatory modeli specyficzne dla dostawcy, wartości domyślne `baseUrl` albo metadane modeli chronione auth. +Używaj `catalog`, gdy plugin obsługuje identyfikatory modeli specyficzne dla dostawcy, domyślne wartości base URL +lub metadane modeli zależne od auth. -`catalog.order` steruje tym, kiedy katalog pluginu łączy się względem -wbudowanych niejawnych dostawców OpenClaw: +`catalog.order` kontroluje, kiedy katalog pluginu jest scalany względem wbudowanych +niejawnych providerów OpenClaw: -- `simple`: zwykli dostawcy oparci na kluczu API albo env +- `simple`: zwykli dostawcy opierający się na kluczu API lub env - `profile`: dostawcy pojawiający się, gdy istnieją profile auth -- `paired`: dostawcy, którzy syntetyzują wiele powiązanych wpisów dostawców -- `late`: ostatnie przejście, po innych niejawnych dostawcach +- `paired`: dostawcy syntetyzujący wiele powiązanych wpisów providerów +- `late`: ostatni przebieg, po innych niejawnych dostawcach -Późniejsi dostawcy wygrywają przy kolizji kluczy, więc pluginy mogą celowo nadpisywać -wbudowany wpis dostawcy z tym samym identyfikatorem dostawcy. +Późniejsze providery wygrywają przy kolizji kluczy, więc pluginy mogą celowo nadpisywać +wbudowany wpis providera o tym samym identyfikatorze. -Zgodność: +Kompatybilność: -- `discovery` nadal działa jako starszy alias +- `discovery` nadal działa jako legacy alias - jeśli zarejestrowano zarówno `catalog`, jak i `discovery`, OpenClaw używa `catalog` -## Inspekcja kanałów tylko do odczytu +## Odczytowa inspekcja kanałów Jeśli Twój plugin rejestruje kanał, preferuj implementację `plugin.config.inspectAccount(cfg, accountId)` obok `resolveAccount(...)`. Dlaczego: -- `resolveAccount(...)` to ścieżka runtime. Może zakładać, że poświadczenia - są w pełni zmaterializowane i może szybko kończyć się błędem, gdy brakuje wymaganych sekretów. -- Ścieżki poleceń tylko do odczytu, takie jak `openclaw status`, `openclaw status --all`, - `openclaw channels status`, `openclaw channels resolve` i przepływy doctor/naprawy konfiguracji +- `resolveAccount(...)` jest ścieżką runtime. Może zakładać, że poświadczenia + są w pełni zmaterializowane, i może szybko zwracać błąd, gdy brakuje wymaganych sekretów. +- Ścieżki komend tylko do odczytu, takie jak `openclaw status`, `openclaw status --all`, + `openclaw channels status`, `openclaw channels resolve` oraz przepływy napraw doctor/config nie powinny wymagać materializacji poświadczeń runtime tylko po to, by opisać konfigurację. Zalecane zachowanie `inspectAccount(...)`: - Zwracaj tylko opisowy stan konta. - Zachowuj `enabled` i `configured`. -- Dołączaj pola źródła/statusu poświadczeń, gdy to istotne, na przykład: +- Dołączaj pola źródła/statusu poświadczeń, gdy to istotne, takie jak: - `tokenSource`, `tokenStatus` - `botTokenSource`, `botTokenStatus` - `appTokenSource`, `appTokenStatus` - `signingSecretSource`, `signingSecretStatus` -- Nie musisz zwracać surowych wartości tokenów tylko po to, by raportować dostępność tylko do odczytu. Zwrócenie `tokenStatus: "available"` (i pasującego pola źródła) wystarczy dla poleceń w stylu statusu. -- Używaj `configured_unavailable`, gdy poświadczenie jest skonfigurowane przez SecretRef, ale niedostępne - w bieżącej ścieżce polecenia. +- Nie musisz zwracać surowych wartości tokenów tylko po to, aby zgłaszać dostępność + w trybie tylko do odczytu. Wystarczy zwrócić `tokenStatus: "available"` (oraz odpowiadające pole źródła). +- Używaj `configured_unavailable`, gdy poświadczenie jest skonfigurowane przez SecretRef, ale + niedostępne w bieżącej ścieżce komendy. -Dzięki temu polecenia tylko do odczytu mogą raportować „skonfigurowane, ale niedostępne w tej ścieżce polecenia” zamiast kończyć się awarią albo błędnie zgłaszać, że konto nie jest skonfigurowane. +Dzięki temu komendy tylko do odczytu mogą zgłaszać „skonfigurowane, ale niedostępne w tej ścieżce komendy” +zamiast powodować awarię albo błędnie raportować konto jako nieskonfigurowane. -## Pakiety pack +## Package packs Katalog pluginu może zawierać `package.json` z `openclaw.extensions`: @@ -1333,60 +1346,61 @@ Katalog pluginu może zawierać `package.json` z `openclaw.extensions`: } ``` -Każdy wpis staje się pluginem. Jeśli pack zawiera wiele rozszerzeń, identyfikator pluginu +Każdy wpis staje się pluginem. Jeśli paczka zawiera wiele rozszerzeń, identyfikator pluginu przyjmuje postać `name/`. Jeśli Twój plugin importuje zależności npm, zainstaluj je w tym katalogu, aby `node_modules` było dostępne (`npm install` / `pnpm install`). -Bariera bezpieczeństwa: każdy wpis `openclaw.extensions` musi pozostać wewnątrz katalogu pluginu +Zabezpieczenie bezpieczeństwa: każdy wpis `openclaw.extensions` musi pozostać wewnątrz katalogu pluginu po rozstrzygnięciu symlinków. Wpisy wychodzące poza katalog pakietu są odrzucane. Uwaga bezpieczeństwa: `openclaw plugins install` instaluje zależności pluginu przez -`npm install --omit=dev --ignore-scripts` (bez skryptów cyklu życia, bez zależności deweloperskich w runtime). Utrzymuj drzewa zależności pluginów jako „czyste JS/TS” i unikaj pakietów wymagających buildów `postinstall`. +`npm install --omit=dev --ignore-scripts` (bez skryptów lifecycle i bez zależności dev w runtime). Utrzymuj drzewa zależności pluginów jako „czyste JS/TS” i unikaj pakietów, które wymagają buildów `postinstall`. -Opcjonalnie: `openclaw.setupEntry` może wskazywać lekki moduł tylko do setup. -Gdy OpenClaw potrzebuje powierzchni setup dla wyłączonego pluginu kanału albo -gdy plugin kanału jest włączony, ale nadal nieskonfigurowany, ładuje `setupEntry` zamiast pełnego wpisu pluginu. Dzięki temu uruchamianie i setup są lżejsze, -gdy główny wpis pluginu rejestruje również narzędzia, hooki lub inny kod tylko runtime. +Opcjonalnie: `openclaw.setupEntry` może wskazywać lekki moduł tylko-konfiguracyjny. +Gdy OpenClaw potrzebuje powierzchni konfiguracji dla wyłączonego pluginu kanału albo +gdy plugin kanału jest włączony, ale nadal nieskonfigurowany, ładuje `setupEntry` +zamiast pełnego entry pluginu. Dzięki temu uruchamianie i konfiguracja są lżejsze, +gdy główne entry pluginu podłącza też narzędzia, hooki lub inny kod wyłącznie runtime. Opcjonalnie: `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` -może włączyć plugin kanału do tej samej ścieżki `setupEntry` podczas fazy -uruchamiania gatewaya przed nasłuchem, nawet gdy kanał jest już skonfigurowany. +pozwala pluginowi kanału skorzystać z tej samej ścieżki `setupEntry` podczas +fazy uruchamiania gateway przed nasłuchem, nawet gdy kanał jest już skonfigurowany. -Używaj tego tylko wtedy, gdy `setupEntry` w pełni pokrywa powierzchnię uruchamiania, która musi istnieć -zanim gateway zacznie nasłuchiwać. W praktyce oznacza to, że wpis setup -musi rejestrować każdą możliwość należącą do kanału, od której zależy uruchamianie, taką jak: +Używaj tego tylko wtedy, gdy `setupEntry` w pełni pokrywa powierzchnię startową, która musi istnieć +przed rozpoczęciem nasłuchiwania przez gateway. W praktyce oznacza to, że entry konfiguracji +musi rejestrować każdą capability należącą do kanału, od której zależy start, taką jak: - sama rejestracja kanału -- wszelkie trasy HTTP, które muszą być dostępne, zanim gateway zacznie nasłuchiwać -- wszelkie metody gatewaya, narzędzia lub usługi, które muszą istnieć w tym samym oknie +- wszelkie trasy HTTP, które muszą być dostępne przed rozpoczęciem nasłuchiwania przez gateway +- wszelkie metody gateway, narzędzia lub usługi, które muszą istnieć w tym samym oknie czasu -Jeśli Twój pełny wpis nadal posiada jakąkolwiek wymaganą możliwość uruchamiania, nie włączaj -tej flagi. Pozostaw plugin przy zachowaniu domyślnym i pozwól OpenClaw załadować -pełny wpis podczas uruchamiania. +Jeśli Twoje pełne entry nadal obsługuje jakąkolwiek wymaganą capability startową, nie włączaj +tej flagi. Zachowaj domyślne zachowanie pluginu i pozwól OpenClaw ładować +pełne entry podczas startu. -Bundlowane kanały mogą także publikować pomocniki powierzchni kontraktowej tylko do setup, z których rdzeń -może korzystać przed załadowaniem pełnego runtime kanału. Obecna powierzchnia promocji setup to: +Dołączone kanały mogą także publikować helpery powierzchni kontraktowej tylko-konfiguracyjnej, z których core +może korzystać przed załadowaniem pełnego runtime kanału. Aktualna powierzchnia promowania konfiguracji to: - `singleAccountKeysToMove` - `namedAccountPromotionKeys` - `resolveSingleAccountPromotionTarget(...)` -Rdzeń używa tej powierzchni, gdy musi awansować starszą konfigurację kanału z jednym kontem do -`channels..accounts.*` bez ładowania pełnego wpisu pluginu. -Matrix jest obecnym bundlowanym przykładem: przenosi tylko klucze auth/bootstrap do -nazwanego awansowanego konta, gdy nazwane konta już istnieją, i może zachować +Core używa tej powierzchni, gdy musi wypromować legacy konfigurację kanału z jednym kontem do +`channels..accounts.*` bez ładowania pełnego entry pluginu. +Matrix jest aktualnym dołączonym przykładem: przenosi tylko klucze auth/bootstrap do +nazwanego wypromowanego konta, gdy nazwane konta już istnieją, i może zachować skonfigurowany niekanoniczny klucz konta domyślnego zamiast zawsze tworzyć `accounts.default`. -Te adaptery łatek setup utrzymują leniwe wykrywanie powierzchni kontraktowej bundli. Czas -importu pozostaje lekki; powierzchnia promocji jest ładowana dopiero przy pierwszym użyciu zamiast -ponownie wchodzić w uruchamianie bundlowanego kanału przy imporcie modułu. +Te adaptery łatek konfiguracji utrzymują leniwe wykrywanie powierzchni kontraktowej dołączonych pluginów. +Czas importu pozostaje niski; powierzchnia promowania jest ładowana dopiero przy pierwszym użyciu, zamiast +ponownie wchodzić w start dołączonego kanału przy imporcie modułu. -Gdy te powierzchnie uruchamiania obejmują metody Gateway RPC, utrzymuj je pod -prefiksem specyficznym dla pluginu. Przestrzenie nazw administracyjnych rdzenia (`config.*`, +Gdy te powierzchnie startowe zawierają metody Gateway RPC, trzymaj je pod +prefiksem specyficznym dla pluginu. Przestrzenie nazw administracyjnych core (`config.*`, `exec.approvals.*`, `wizard.*`, `update.*`) pozostają zastrzeżone i zawsze są rozstrzygane do `operator.admin`, nawet jeśli plugin żąda węższego zakresu. @@ -1405,10 +1419,10 @@ Przykład: } ``` -### Metadane katalogu kanału +### Metadane katalogu kanałów -Pluginy kanałów mogą reklamować metadane setup/wykrywania przez `openclaw.channel` oraz -wskazówki instalacyjne przez `openclaw.install`. Dzięki temu dane katalogu rdzenia pozostają wolne od danych. +Pluginy kanałów mogą reklamować metadane konfiguracji/wykrywania przez `openclaw.channel` oraz +wskazówki instalacyjne przez `openclaw.install`. Dzięki temu dane katalogu core pozostają puste. Przykład: @@ -1436,41 +1450,41 @@ Przykład: } ``` -Przydatne pola `openclaw.channel` wykraczające poza minimalny przykład: +Przydatne pola `openclaw.channel` poza minimalnym przykładem: - `detailLabel`: etykieta pomocnicza dla bogatszych powierzchni katalogu/statusu -- `docsLabel`: nadpisanie tekstu linku do dokumentacji +- `docsLabel`: nadpisuje tekst linku do dokumentacji - `preferOver`: identyfikatory pluginów/kanałów o niższym priorytecie, które ten wpis katalogu powinien wyprzedzać -- `selectionDocsPrefix`, `selectionDocsOmitLabel`, `selectionExtras`: kontrolki tekstu dla powierzchni wyboru -- `markdownCapable`: oznacza kanał jako zdolny do markdown na potrzeby decyzji o formatowaniu outbound -- `exposure.configured`: ukrywa kanał przed powierzchniami listowania skonfigurowanych kanałów, gdy ustawione na `false` -- `exposure.setup`: ukrywa kanał przed interaktywnymi pickerami setup/configure, gdy ustawione na `false` +- `selectionDocsPrefix`, `selectionDocsOmitLabel`, `selectionExtras`: kontrolki treści dla powierzchni wyboru +- `markdownCapable`: oznacza kanał jako obsługujący markdown dla decyzji o formatowaniu outbound +- `exposure.configured`: ukrywa kanał z powierzchni listy skonfigurowanych kanałów po ustawieniu na `false` +- `exposure.setup`: ukrywa kanał z interaktywnych selektorów konfiguracji/ustawiania po ustawieniu na `false` - `exposure.docs`: oznacza kanał jako wewnętrzny/prywatny dla powierzchni nawigacji dokumentacji -- `showConfigured` / `showInSetup`: starsze aliasy nadal akceptowane dla zgodności; preferuj `exposure` -- `quickstartAllowFrom`: włącza kanał do standardowego przepływu szybkiego startu `allowFrom` +- `showConfigured` / `showInSetup`: legacy aliasy nadal akceptowane ze względów kompatybilności; preferuj `exposure` +- `quickstartAllowFrom`: włącza kanał do standardowego przepływu quickstart `allowFrom` - `forceAccountBinding`: wymaga jawnego powiązania konta nawet wtedy, gdy istnieje tylko jedno konto -- `preferSessionLookupForAnnounceTarget`: preferuje wyszukiwanie sesji przy rozstrzyganiu celów announce +- `preferSessionLookupForAnnounceTarget`: preferuje wyszukiwanie sesji przy rozstrzyganiu targetów ogłoszeń -OpenClaw może też łączyć **zewnętrzne katalogi kanałów** (na przykład eksport rejestru MPM). +OpenClaw może także scalać **zewnętrzne katalogi kanałów** (na przykład eksport rejestru MPM). Umieść plik JSON w jednej z lokalizacji: - `~/.openclaw/mpm/plugins.json` - `~/.openclaw/mpm/catalog.json` - `~/.openclaw/plugins/catalog.json` -Albo ustaw `OPENCLAW_PLUGIN_CATALOG_PATHS` (lub `OPENCLAW_MPM_CATALOG_PATHS`) na -jeden lub więcej plików JSON (rozdzielanych przecinkiem/średnikiem/`PATH`). Każdy plik powinien -zawierać `{ "entries": [ { "name": "@scope/pkg", "openclaw": { "channel": {...}, "install": {...} } } ] }`. Parser akceptuje także `"packages"` albo `"plugins"` jako starsze aliasy klucza `"entries"`. +Albo wskaż `OPENCLAW_PLUGIN_CATALOG_PATHS` (lub `OPENCLAW_MPM_CATALOG_PATHS`) na +jeden lub więcej plików JSON (rozdzielonych przecinkiem/średnikiem/formatem `PATH`). Każdy plik powinien +zawierać `{ "entries": [ { "name": "@scope/pkg", "openclaw": { "channel": {...}, "install": {...} } } ] }`. Parser akceptuje także `"packages"` lub `"plugins"` jako legacy aliasy klucza `"entries"`. ## Pluginy silnika kontekstu -Pluginy silnika kontekstu posiadają orkiestrację kontekstu sesji dla ingestu, składania -i kompaktowania. Rejestruj je z poziomu pluginu przez -`api.registerContextEngine(id, factory)`, a następnie wybieraj aktywny silnik przez +Pluginy silnika kontekstu obsługują orkiestrację kontekstu sesji dla ingest, składania +i kompaktowania. Rejestruj je ze swojego pluginu przez +`api.registerContextEngine(id, factory)`, a następnie wybierz aktywny silnik przez `plugins.slots.contextEngine`. -Używaj tego, gdy Twój plugin musi zastąpić lub rozszerzyć domyślny potok kontekstu -zamiast tylko dodawać memory search albo hooki. +Używaj tego, gdy Twój plugin musi zastąpić lub rozszerzyć domyślny pipeline kontekstu, +a nie tylko dodać wyszukiwanie pamięci lub hooki. ```ts import { buildMemorySystemPromptAddition } from "openclaw/plugin-sdk/core"; @@ -1498,8 +1512,8 @@ export default function (api) { } ``` -Jeśli Twój silnik **nie** posiada algorytmu kompaktowania, zachowaj implementację `compact()` -i jawnie do niego deleguj: +Jeśli Twój silnik **nie** obsługuje algorytmu kompaktowania, pozostaw `compact()` +zaimplementowane i jawnie je deleguj: ```ts import { @@ -1534,62 +1548,62 @@ export default function (api) { } ``` -## Dodawanie nowej możliwości +## Dodawanie nowej capability Gdy plugin potrzebuje zachowania, które nie mieści się w obecnym API, nie omijaj -systemu pluginów przez prywatny reach-in. Dodaj brakującą możliwość. +systemu pluginów prywatnym reach-in. Dodaj brakującą capability. Zalecana sekwencja: -1. zdefiniuj kontrakt rdzenia - Zdecyduj, jakie współdzielone zachowanie powinien posiadać rdzeń: polityka, fallback, łączenie konfiguracji, - cykl życia, semantyka skierowana do kanałów i kształt pomocników runtime. -2. dodaj typowane powierzchnie rejestracji/runtime pluginów +1. zdefiniuj kontrakt core + Ustal, jakie współdzielone zachowanie powinien obsługiwać core: politykę, fallback, łączenie konfiguracji, + cykl życia, semantykę skierowaną do kanałów i kształt helperów runtime. +2. dodaj typowane powierzchnie rejestracji/runtime pluginu Rozszerz `OpenClawPluginApi` i/lub `api.runtime` o najmniejszą użyteczną - typowaną powierzchnię możliwości. -3. podłącz konsumentów rdzenia i kanałów/funkcji - Kanały i pluginy funkcji powinny korzystać z nowej możliwości przez rdzeń, - a nie przez bezpośredni import implementacji dostawcy. + typowaną powierzchnię capability. +3. podłącz konsumentów core + kanałów/funkcji + Kanały i pluginy funkcjonalne powinny korzystać z nowej capability przez core, + a nie importować bezpośrednio implementacji dostawcy. 4. zarejestruj implementacje dostawców - Pluginy dostawców następnie rejestrują swoje backendy względem tej możliwości. + Pluginy dostawców rejestrują następnie swoje backendy względem tej capability. 5. dodaj pokrycie kontraktowe - Dodaj testy, aby własność i kształt rejestracji pozostawały jawne w czasie. + Dodaj testy, aby własność i kształt rejestracji pozostawały z czasem jawne. -Tak OpenClaw pozostaje opiniotwórczy bez twardego zakodowania jednego -światopoglądu dostawcy. Zobacz [Capability Cookbook](/pl/plugins/architecture), -aby znaleźć konkretną listę plików i gotowy przykład. +Tak OpenClaw zachowuje opiniotwórczość bez twardego zakodowania światopoglądu jednego +dostawcy. Zobacz [Capability Cookbook](/pl/plugins/architecture), +aby znaleźć konkretną listę plików i opracowany przykład. -### Lista kontrolna możliwości +### Lista kontrolna capability -Gdy dodajesz nową możliwość, implementacja zwykle powinna wspólnie dotknąć tych -powierzchni: +Gdy dodajesz nową capability, implementacja zwykle powinna dotykać tych +powierzchni jednocześnie: -- typów kontraktu rdzenia w `src//types.ts` -- runnera/pomocnika runtime rdzenia w `src//runtime.ts` -- powierzchni rejestracji API pluginów w `src/plugins/types.ts` -- integracji rejestru pluginów w `src/plugins/registry.ts` -- udostępnienia runtime pluginów w `src/plugins/runtime/*`, gdy pluginy funkcji/kanałów - muszą z tego korzystać -- pomocników przechwytywania/testów w `src/test-utils/plugin-registration.ts` -- asercji własności/kontraktu w `src/plugins/contracts/registry.ts` -- dokumentacji operatora/pluginów w `docs/` +- typy kontraktu core w `src//types.ts` +- helper runner/runtime core w `src//runtime.ts` +- powierzchnia rejestracji API pluginu w `src/plugins/types.ts` +- podłączenie rejestru pluginów w `src/plugins/registry.ts` +- udostępnienie runtime pluginów w `src/plugins/runtime/*`, gdy pluginy funkcjonalne/kanałów + muszą z niego korzystać +- helpery przechwytywania/testów w `src/test-utils/plugin-registration.ts` +- asercje własności/kontraktu w `src/plugins/contracts/registry.ts` +- dokumentacja operatora/pluginów w `docs/` -Jeśli którejś z tych powierzchni brakuje, zwykle oznacza to, że możliwość nie jest jeszcze -w pełni zintegrowana. +Jeśli którejś z tych powierzchni brakuje, zwykle jest to znak, że capability nie jest +jeszcze w pełni zintegrowana. -### Szablon możliwości +### Szablon capability Minimalny wzorzec: ```ts -// kontrakt rdzenia +// core contract export type VideoGenerationProviderPlugin = { id: string; label: string; generateVideo: (req: VideoGenerationRequest) => Promise; }; -// API pluginu +// plugin API api.registerVideoGenerationProvider({ id: "openai", label: "OpenAI", @@ -1598,14 +1612,14 @@ api.registerVideoGenerationProvider({ }, }); -// współdzielony pomocnik runtime dla pluginów funkcji/kanałów +// shared runtime helper for feature/channel plugins const clip = await api.runtime.videoGeneration.generate({ prompt: "Show the robot walking through the lab.", cfg, }); ``` -Wzorzec testu kontraktowego: +Wzorzec testu kontraktu: ```ts expect(findVideoGenerationProviderIdsForPlugin("openai")).toEqual(["openai"]); @@ -1613,7 +1627,7 @@ expect(findVideoGenerationProviderIdsForPlugin("openai")).toEqual(["openai"]); To utrzymuje prostą zasadę: -- rdzeń posiada kontrakt możliwości + orkiestrację -- pluginy dostawców posiadają implementacje dostawców -- pluginy funkcji/kanałów korzystają z pomocników runtime -- testy kontraktowe utrzymują jawną własność +- core obsługuje kontrakt capability + orkiestrację +- pluginy dostawców obsługują implementacje dostawców +- pluginy funkcjonalne/kanałów korzystają z helperów runtime +- testy kontraktów utrzymują jawną własność diff --git a/docs/pl/plugins/manifest.md b/docs/pl/plugins/manifest.md index 059c94a91..b401d7226 100644 --- a/docs/pl/plugins/manifest.md +++ b/docs/pl/plugins/manifest.md @@ -1,75 +1,75 @@ --- read_when: - Tworzysz plugin OpenClaw - - Musisz dostarczyć schemat konfiguracji pluginu lub debugujesz błędy walidacji pluginu + - Musisz dostarczyć schemat konfiguracji pluginu lub debugować błędy walidacji pluginu summary: Manifest pluginu + wymagania schematu JSON (ścisła walidacja konfiguracji) title: Manifest pluginu x-i18n: - generated_at: "2026-04-07T09:47:43Z" + generated_at: "2026-04-09T01:29:09Z" model: gpt-5.4 provider: openai - source_hash: 22d41b9f8748b1b1b066ee856be4a8f41e88b9a8bc073d74fc79d2bb0982f01a + source_hash: 9a7ee4b621a801d2a8f32f8976b0e1d9433c7810eb360aca466031fc0ffb286a source_path: plugins/manifest.md workflow: 15 --- -# Manifest pluginu (`openclaw.plugin.json`) +# Manifest pluginu (openclaw.plugin.json) Ta strona dotyczy wyłącznie **natywnego manifestu pluginu OpenClaw**. -Informacje o zgodnych układach bundle znajdziesz w [Plugin bundles](/pl/plugins/bundles). +Informacje o zgodnych układach bundli znajdziesz w [Bundlach pluginów](/pl/plugins/bundles). -Zgodne formaty bundle używają innych plików manifestu: +Zgodne formaty bundli używają innych plików manifestu: -- Bundle Codex: `.codex-plugin/plugin.json` -- Bundle Claude: `.claude-plugin/plugin.json` lub domyślny układ komponentu Claude +- Bundel Codex: `.codex-plugin/plugin.json` +- Bundel Claude: `.claude-plugin/plugin.json` lub domyślny układ komponentu Claude bez manifestu -- Bundle Cursor: `.cursor-plugin/plugin.json` +- Bundel Cursor: `.cursor-plugin/plugin.json` -OpenClaw automatycznie wykrywa także te układy bundle, ale nie są one walidowane +OpenClaw automatycznie wykrywa również te układy bundli, ale nie są one walidowane względem schematu `openclaw.plugin.json` opisanego tutaj. -W przypadku zgodnych bundle OpenClaw obecnie odczytuje metadane bundle oraz zadeklarowane -korzenie Skills, korzenie poleceń Claude, domyślne wartości `settings.json` bundle Claude, -domyślne wartości LSP bundle Claude oraz obsługiwane pakiety hooków, gdy układ jest zgodny -z oczekiwaniami runtime OpenClaw. +Dla zgodnych bundli OpenClaw obecnie odczytuje metadane bundla oraz zadeklarowane +korzenie skillów, korzenie poleceń Claude, domyślne wartości `settings.json` bundla Claude, +domyślne wartości LSP bundla Claude oraz obsługiwane zestawy hooków, gdy układ odpowiada +oczekiwaniom środowiska uruchomieniowego OpenClaw. Każdy natywny plugin OpenClaw **musi** dostarczać plik `openclaw.plugin.json` w **katalogu głównym pluginu**. OpenClaw używa tego manifestu do walidacji konfiguracji **bez wykonywania kodu pluginu**. Brakujące lub nieprawidłowe manifesty są traktowane jako błędy pluginu i blokują walidację konfiguracji. -Zobacz pełny przewodnik po systemie pluginów: [Plugins](/pl/tools/plugin). -Aby poznać natywny model możliwości i bieżące wskazówki dotyczące zgodności zewnętrznej: -[Capability model](/pl/plugins/architecture#public-capability-model). +Pełny przewodnik po systemie pluginów znajdziesz tutaj: [Pluginy](/pl/tools/plugin). +Informacje o natywnym modelu możliwości i aktualnych wskazówkach dotyczących zgodności zewnętrznej: +[Model możliwości](/pl/plugins/architecture#public-capability-model). ## Do czego służy ten plik -`openclaw.plugin.json` to metadane, które OpenClaw odczytuje, zanim załaduje kod -Twojego pluginu. +`openclaw.plugin.json` to metadane, które OpenClaw odczytuje przed załadowaniem +kodu Twojego pluginu. Używaj go do: - tożsamości pluginu - walidacji konfiguracji -- metadanych uwierzytelniania i onboardingu, które powinny być dostępne bez uruchamiania - runtime pluginu -- metadanych aliasów i automatycznego włączania, które powinny być rozstrzygane przed załadowaniem runtime pluginu +- metadanych auth i onboardingu, które powinny być dostępne bez uruchamiania + środowiska uruchomieniowego pluginu +- metadanych aliasów i automatycznego włączania, które powinny być rozstrzygane przed załadowaniem środowiska uruchomieniowego pluginu - skróconych metadanych własności rodzin modeli, które powinny automatycznie aktywować - plugin przed załadowaniem runtime -- statycznych migawek własności możliwości używanych do bundlowanego okablowania zgodności i + plugin przed załadowaniem środowiska uruchomieniowego +- statycznych migawek własności możliwości używanych do zgodnego okablowania bundli i pokrycia kontraktów - metadanych konfiguracji specyficznych dla kanału, które powinny być scalane z powierzchniami katalogu i walidacji - bez ładowania runtime -- wskazówek dla UI konfiguracji + bez ładowania środowiska uruchomieniowego +- wskazówek UI konfiguracji Nie używaj go do: -- rejestrowania zachowania runtime -- deklarowania entrypointów kodu +- rejestrowania zachowań środowiska uruchomieniowego +- deklarowania punktów wejścia kodu - metadanych instalacji npm -Te elementy należą do kodu pluginu i `package.json`. +To należy do kodu pluginu i `package.json`. ## Minimalny przykład @@ -90,7 +90,7 @@ Te elementy należą do kodu pluginu i `package.json`. { "id": "openrouter", "name": "OpenRouter", - "description": "OpenRouter provider plugin", + "description": "Plugin dostawcy OpenRouter", "version": "1.0.0", "providers": ["openrouter"], "modelSupport": { @@ -100,6 +100,9 @@ Te elementy należą do kodu pluginu i `package.json`. "providerAuthEnvVars": { "openrouter": ["OPENROUTER_API_KEY"] }, + "providerAuthAliases": { + "openrouter-coding": "openrouter" + }, "channelEnvVars": { "openrouter-chatops": ["OPENROUTER_CHATOPS_TOKEN"] }, @@ -108,19 +111,19 @@ Te elementy należą do kodu pluginu i `package.json`. "provider": "openrouter", "method": "api-key", "choiceId": "openrouter-api-key", - "choiceLabel": "OpenRouter API key", + "choiceLabel": "Klucz API OpenRouter", "groupId": "openrouter", "groupLabel": "OpenRouter", "optionKey": "openrouterApiKey", "cliFlag": "--openrouter-api-key", "cliOption": "--openrouter-api-key ", - "cliDescription": "OpenRouter API key", + "cliDescription": "Klucz API OpenRouter", "onboardingScopes": ["text-inference"] } ], "uiHints": { "apiKey": { - "label": "API key", + "label": "Klucz API", "placeholder": "sk-or-v1-...", "sensitive": true } @@ -137,65 +140,66 @@ Te elementy należą do kodu pluginu i `package.json`. } ``` -## Opis pól najwyższego poziomu +## Dokumentacja pól najwyższego poziomu -| Pole | Wymagane | Typ | Znaczenie | +| Field | Required | Type | What it means | | ----------------------------------- | -------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `id` | Tak | `string` | Kanoniczny identyfikator pluginu. To identyfikator używany w `plugins.entries.`. | -| `configSchema` | Tak | `object` | Wbudowany schemat JSON Schema dla konfiguracji tego pluginu. | -| `enabledByDefault` | Nie | `true` | Oznacza bundlowany plugin jako domyślnie włączony. Pomiń to pole lub ustaw dowolną wartość inną niż `true`, aby pozostawić plugin domyślnie wyłączony. | +| `id` | Tak | `string` | Kanoniczny identyfikator pluginu. To identyfikator używany w `plugins.entries.`. | +| `configSchema` | Tak | `object` | Wbudowany schemat JSON dla konfiguracji tego pluginu. | +| `enabledByDefault` | Nie | `true` | Oznacza bundlowany plugin jako domyślnie włączony. Pomiń to pole albo ustaw dowolną wartość inną niż `true`, aby pozostawić plugin domyślnie wyłączony. | | `legacyPluginIds` | Nie | `string[]` | Starsze identyfikatory normalizowane do tego kanonicznego identyfikatora pluginu. | -| `autoEnableWhenConfiguredProviders` | Nie | `string[]` | Identyfikatory dostawców, które powinny automatycznie włączać ten plugin, gdy uwierzytelnianie, konfiguracja lub odwołania do modeli o nich wspominają. | -| `kind` | Nie | `"memory"` \| `"context-engine"` | Deklaruje wyłączny rodzaj pluginu używany przez `plugins.slots.*`. | +| `autoEnableWhenConfiguredProviders` | Nie | `string[]` | Identyfikatory dostawców, które powinny automatycznie włączać ten plugin, gdy auth, konfiguracja lub odwołania do modeli o nich wspominają. | +| `kind` | Nie | `"memory"` \| `"context-engine"` | Deklaruje wyłączny rodzaj pluginu używany przez `plugins.slots.*`. | | `channels` | Nie | `string[]` | Identyfikatory kanałów należących do tego pluginu. Używane do wykrywania i walidacji konfiguracji. | | `providers` | Nie | `string[]` | Identyfikatory dostawców należących do tego pluginu. | -| `modelSupport` | Nie | `object` | Należące do manifestu skrócone metadane rodzin modeli używane do automatycznego ładowania pluginu przed runtime. | -| `cliBackends` | Nie | `string[]` | Identyfikatory backendów inferencji CLI należących do tego pluginu. Używane do automatycznej aktywacji przy starcie na podstawie jawnych odwołań w konfiguracji. | -| `providerAuthEnvVars` | Nie | `Record` | Lekkie metadane środowiskowe uwierzytelniania dostawcy, które OpenClaw może sprawdzić bez ładowania kodu pluginu. | -| `channelEnvVars` | Nie | `Record` | Lekkie metadane środowiskowe kanału, które OpenClaw może sprawdzić bez ładowania kodu pluginu. Używaj ich dla konfiguracji kanałów sterowanych przez env lub powierzchni uwierzytelniania, które powinny być widoczne dla ogólnych helperów startu/konfiguracji. | -| `providerAuthChoices` | Nie | `object[]` | Lekkie metadane opcji uwierzytelniania dla selektorów onboardingu, rozstrzygania preferowanego dostawcy i prostego okablowania flag CLI. | -| `contracts` | Nie | `object` | Statyczna migawka bundlowanych możliwości dla mowy, transkrypcji realtime, głosu realtime, rozumienia mediów, generowania obrazów, generowania muzyki, generowania wideo, web-fetch, web search i własności narzędzi. | -| `channelConfigs` | Nie | `Record` | Należące do manifestu metadane konfiguracji kanału scalane z powierzchniami wykrywania i walidacji przed załadowaniem runtime. | -| `skills` | Nie | `string[]` | Katalogi Skills do załadowania, względne względem katalogu głównego pluginu. | +| `modelSupport` | Nie | `object` | Należące do manifestu skrócone metadane rodzin modeli używane do automatycznego ładowania pluginu przed środowiskiem uruchomieniowym. | +| `cliBackends` | Nie | `string[]` | Identyfikatory backendów inferencji CLI należących do tego pluginu. Używane do automatycznej aktywacji przy uruchomieniu na podstawie jawnych odwołań w konfiguracji. | +| `providerAuthEnvVars` | Nie | `Record` | Tanie metadane env dla auth dostawcy, które OpenClaw może sprawdzać bez ładowania kodu pluginu. | +| `providerAuthAliases` | Nie | `Record` | Identyfikatory dostawców, które powinny ponownie używać innego identyfikatora dostawcy do wyszukiwania auth, na przykład dostawca do kodowania współdzielący bazowy klucz API dostawcy i profile auth. | +| `channelEnvVars` | Nie | `Record` | Tanie metadane env kanału, które OpenClaw może sprawdzać bez ładowania kodu pluginu. Używaj tego dla konfiguracji kanału opartej na env lub powierzchni auth, które powinny być widoczne dla ogólnych pomocników uruchamiania/konfiguracji. | +| `providerAuthChoices` | Nie | `object[]` | Tanie metadane wyboru auth dla selektorów onboardingu, rozstrzygania preferowanych dostawców i prostego mapowania flag CLI. | +| `contracts` | Nie | `object` | Statyczna migawka możliwości bundli dla mowy, transkrypcji czasu rzeczywistego, głosu czasu rzeczywistego, rozumienia mediów, generowania obrazów, generowania muzyki, generowania wideo, web-fetch, wyszukiwania w sieci i własności narzędzi. | +| `channelConfigs` | Nie | `Record` | Należące do manifestu metadane konfiguracji kanałów scalane z powierzchniami wykrywania i walidacji przed załadowaniem środowiska uruchomieniowego. | +| `skills` | Nie | `string[]` | Katalogi Skills do załadowania, względem katalogu głównego pluginu. | | `name` | Nie | `string` | Czytelna dla człowieka nazwa pluginu. | -| `description` | Nie | `string` | Krótkie podsumowanie pokazywane na powierzchniach pluginu. | +| `description` | Nie | `string` | Krótkie podsumowanie wyświetlane na powierzchniach pluginu. | | `version` | Nie | `string` | Informacyjna wersja pluginu. | -| `uiHints` | Nie | `Record` | Etykiety UI, placeholdery i wskazówki dotyczące wrażliwości pól konfiguracji. | +| `uiHints` | Nie | `Record` | Etykiety UI, placeholdery i wskazówki dotyczące wrażliwości dla pól konfiguracji. | -## Opis `providerAuthChoices` +## Dokumentacja `providerAuthChoices` -Każdy wpis `providerAuthChoices` opisuje jedną opcję onboardingu lub uwierzytelniania. -OpenClaw odczytuje to przed załadowaniem runtime dostawcy. +Każdy wpis `providerAuthChoices` opisuje jeden wybór onboardingu lub auth. +OpenClaw odczytuje to przed załadowaniem środowiska uruchomieniowego dostawcy. -| Pole | Wymagane | Typ | Znaczenie | -| --------------------- | -------- | ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | -| `provider` | Tak | `string` | Identyfikator dostawcy, do którego należy ta opcja. | -| `method` | Tak | `string` | Identyfikator metody uwierzytelniania, do której należy przekazać sterowanie. | -| `choiceId` | Tak | `string` | Stabilny identyfikator opcji uwierzytelniania używany przez onboarding i przepływy CLI. | -| `choiceLabel` | Nie | `string` | Etykieta widoczna dla użytkownika. Jeśli zostanie pominięta, OpenClaw użyje `choiceId`. | -| `choiceHint` | Nie | `string` | Krótki tekst pomocniczy dla selektora. | -| `assistantPriority` | Nie | `number` | Niższe wartości są sortowane wcześniej w interaktywnych selektorach sterowanych przez asystenta. | -| `assistantVisibility` | Nie | `"visible"` \| `"manual-only"` | Ukrywa opcję w selektorach asystenta, nadal pozwalając na ręczny wybór w CLI. | -| `deprecatedChoiceIds` | Nie | `string[]` | Starsze identyfikatory opcji, które powinny przekierowywać użytkowników do tej opcji zastępczej. | -| `groupId` | Nie | `string` | Opcjonalny identyfikator grupy do grupowania powiązanych opcji. | -| `groupLabel` | Nie | `string` | Etykieta widoczna dla użytkownika dla tej grupy. | -| `groupHint` | Nie | `string` | Krótki tekst pomocniczy dla grupy. | -| `optionKey` | Nie | `string` | Wewnętrzny klucz opcji dla prostych przepływów uwierzytelniania z jedną flagą. | -| `cliFlag` | Nie | `string` | Nazwa flagi CLI, na przykład `--openrouter-api-key`. | -| `cliOption` | Nie | `string` | Pełny kształt opcji CLI, na przykład `--openrouter-api-key `. | -| `cliDescription` | Nie | `string` | Opis używany w pomocy CLI. | -| `onboardingScopes` | Nie | `Array<"text-inference" \| "image-generation">` | Na których powierzchniach onboardingu ta opcja powinna się pojawiać. Jeśli pole zostanie pominięte, domyślnie używane jest `["text-inference"]`. | +| Field | Required | Type | What it means | +| --------------------- | -------- | ----------------------------------------------- | -------------------------------------------------------------------------------------------------------- | +| `provider` | Tak | `string` | Identyfikator dostawcy, do którego należy ten wybór. | +| `method` | Tak | `string` | Identyfikator metody auth, do której należy przekierować. | +| `choiceId` | Tak | `string` | Stabilny identyfikator wyboru auth używany przez onboarding i przepływy CLI. | +| `choiceLabel` | Nie | `string` | Etykieta widoczna dla użytkownika. Jeśli zostanie pominięta, OpenClaw użyje `choiceId`. | +| `choiceHint` | Nie | `string` | Krótki tekst pomocniczy dla selektora. | +| `assistantPriority` | Nie | `number` | Niższe wartości są sortowane wcześniej w interaktywnych selektorach sterowanych przez asystenta. | +| `assistantVisibility` | Nie | `"visible"` \| `"manual-only"` | Ukrywa wybór w selektorach asystenta, nadal pozwalając na ręczny wybór w CLI. | +| `deprecatedChoiceIds` | Nie | `string[]` | Starsze identyfikatory wyborów, które powinny przekierowywać użytkowników do tego wyboru zastępczego. | +| `groupId` | Nie | `string` | Opcjonalny identyfikator grupy do grupowania powiązanych wyborów. | +| `groupLabel` | Nie | `string` | Etykieta tej grupy widoczna dla użytkownika. | +| `groupHint` | Nie | `string` | Krótki tekst pomocniczy dla grupy. | +| `optionKey` | Nie | `string` | Wewnętrzny klucz opcji dla prostych przepływów auth opartych na jednej fladze. | +| `cliFlag` | Nie | `string` | Nazwa flagi CLI, np. `--openrouter-api-key`. | +| `cliOption` | Nie | `string` | Pełny kształt opcji CLI, np. `--openrouter-api-key `. | +| `cliDescription` | Nie | `string` | Opis używany w pomocy CLI. | +| `onboardingScopes` | Nie | `Array<"text-inference" \| "image-generation">` | Na których powierzchniach onboardingu ten wybór powinien się pojawiać. Jeśli pole zostanie pominięte, domyślnie używane jest `["text-inference"]`. | -## Opis `uiHints` +## Dokumentacja `uiHints` -`uiHints` to mapa z nazw pól konfiguracji na małe wskazówki renderowania. +`uiHints` to mapa od nazw pól konfiguracji do małych wskazówek renderowania. ```json { "uiHints": { "apiKey": { - "label": "API key", - "help": "Used for OpenRouter requests", + "label": "Klucz API", + "help": "Używany do żądań OpenRouter", "placeholder": "sk-or-v1-...", "sensitive": true } @@ -203,9 +207,9 @@ OpenClaw odczytuje to przed załadowaniem runtime dostawcy. } ``` -Każda wskazówka dla pola może zawierać: +Wskazówka dla każdego pola może zawierać: -| Pole | Typ | Znaczenie | +| Field | Type | What it means | | ------------- | ---------- | --------------------------------------- | | `label` | `string` | Etykieta pola widoczna dla użytkownika. | | `help` | `string` | Krótki tekst pomocniczy. | @@ -214,10 +218,10 @@ Każda wskazówka dla pola może zawierać: | `sensitive` | `boolean` | Oznacza pole jako sekretne lub wrażliwe. | | `placeholder` | `string` | Tekst placeholdera dla pól formularza. | -## Opis `contracts` +## Dokumentacja `contracts` -Używaj `contracts` tylko do statycznych metadanych własności możliwości, które OpenClaw może -odczytać bez importowania runtime pluginu. +Używaj `contracts` tylko dla statycznych metadanych własności możliwości, które OpenClaw może +odczytać bez importowania środowiska uruchomieniowego pluginu. ```json { @@ -237,22 +241,22 @@ odczytać bez importowania runtime pluginu. Każda lista jest opcjonalna: -| Pole | Typ | Znaczenie | -| -------------------------------- | ---------- | ---------------------------------------------------------- | -| `speechProviders` | `string[]` | Identyfikatory dostawców mowy należące do tego pluginu. | -| `realtimeTranscriptionProviders` | `string[]` | Identyfikatory dostawców transkrypcji realtime należące do tego pluginu. | -| `realtimeVoiceProviders` | `string[]` | Identyfikatory dostawców głosu realtime należące do tego pluginu. | -| `mediaUnderstandingProviders` | `string[]` | Identyfikatory dostawców rozumienia mediów należące do tego pluginu. | -| `imageGenerationProviders` | `string[]` | Identyfikatory dostawców generowania obrazów należące do tego pluginu. | -| `videoGenerationProviders` | `string[]` | Identyfikatory dostawców generowania wideo należące do tego pluginu. | -| `webFetchProviders` | `string[]` | Identyfikatory dostawców web-fetch należące do tego pluginu. | -| `webSearchProviders` | `string[]` | Identyfikatory dostawców web search należące do tego pluginu. | -| `tools` | `string[]` | Nazwy narzędzi agenta należących do tego pluginu dla bundlowanych kontroli kontraktów. | +| Field | Type | What it means | +| -------------------------------- | ---------- | -------------------------------------------------------------- | +| `speechProviders` | `string[]` | Identyfikatory dostawców mowy należących do tego pluginu. | +| `realtimeTranscriptionProviders` | `string[]` | Identyfikatory dostawców transkrypcji czasu rzeczywistego należących do tego pluginu. | +| `realtimeVoiceProviders` | `string[]` | Identyfikatory dostawców głosu czasu rzeczywistego należących do tego pluginu. | +| `mediaUnderstandingProviders` | `string[]` | Identyfikatory dostawców rozumienia mediów należących do tego pluginu. | +| `imageGenerationProviders` | `string[]` | Identyfikatory dostawców generowania obrazów należących do tego pluginu. | +| `videoGenerationProviders` | `string[]` | Identyfikatory dostawców generowania wideo należących do tego pluginu. | +| `webFetchProviders` | `string[]` | Identyfikatory dostawców web-fetch należących do tego pluginu. | +| `webSearchProviders` | `string[]` | Identyfikatory dostawców wyszukiwania w sieci należących do tego pluginu. | +| `tools` | `string[]` | Nazwy narzędzi agenta należących do tego pluginu do sprawdzania kontraktów bundli. | -## Opis `channelConfigs` +## Dokumentacja `channelConfigs` -Używaj `channelConfigs`, gdy plugin kanału potrzebuje lekkich metadanych konfiguracji przed -załadowaniem runtime. +Używaj `channelConfigs`, gdy plugin kanału potrzebuje tanich metadanych konfiguracji przed +załadowaniem środowiska uruchomieniowego. ```json { @@ -267,12 +271,12 @@ załadowaniem runtime. }, "uiHints": { "homeserverUrl": { - "label": "Homeserver URL", + "label": "URL homeservera", "placeholder": "https://matrix.example.com" } }, "label": "Matrix", - "description": "Matrix homeserver connection", + "description": "Połączenie z homeserverem Matrix", "preferOver": ["matrix-legacy"] } } @@ -281,18 +285,18 @@ załadowaniem runtime. Każdy wpis kanału może zawierać: -| Pole | Typ | Znaczenie | -| ------------- | ------------------------ | ------------------------------------------------------------------------------------------ | -| `schema` | `object` | JSON Schema dla `channels.`. Wymagane dla każdego zadeklarowanego wpisu konfiguracji kanału. | -| `uiHints` | `Record` | Opcjonalne etykiety UI/placeholdery/wskazówki wrażliwości dla tej sekcji konfiguracji kanału. | -| `label` | `string` | Etykieta kanału scalana z powierzchniami selektora i inspekcji, gdy metadane runtime nie są gotowe. | -| `description` | `string` | Krótki opis kanału dla powierzchni inspekcji i katalogu. | -| `preferOver` | `string[]` | Starsze lub mniej priorytetowe identyfikatory pluginów, które ten kanał powinien wyprzedzać na powierzchniach wyboru. | +| Field | Type | What it means | +| ------------- | ------------------------ | ----------------------------------------------------------------------------------------- | +| `schema` | `object` | Schemat JSON dla `channels.`. Wymagany dla każdego zadeklarowanego wpisu konfiguracji kanału. | +| `uiHints` | `Record` | Opcjonalne etykiety UI/placeholdery/wskazówki dotyczące wrażliwości dla tej sekcji konfiguracji kanału. | +| `label` | `string` | Etykieta kanału scalana z powierzchniami selektora i inspekcji, gdy metadane środowiska uruchomieniowego nie są gotowe. | +| `description` | `string` | Krótki opis kanału dla powierzchni inspekcji i katalogu. | +| `preferOver` | `string[]` | Starsze lub niższe priorytetowo identyfikatory pluginów, które ten kanał powinien wyprzedzać na powierzchniach wyboru. | -## Opis `modelSupport` +## Dokumentacja `modelSupport` -Używaj `modelSupport`, gdy OpenClaw ma wywnioskować plugin dostawcy na podstawie -skróconych identyfikatorów modeli, takich jak `gpt-5.4` lub `claude-sonnet-4.6`, zanim załaduje się runtime pluginu. +Używaj `modelSupport`, gdy OpenClaw powinien wywnioskować plugin Twojego dostawcy na podstawie +skrótowych identyfikatorów modeli, takich jak `gpt-5.4` lub `claude-sonnet-4.6`, przed załadowaniem środowiska uruchomieniowego pluginu. ```json { @@ -305,73 +309,73 @@ skróconych identyfikatorów modeli, takich jak `gpt-5.4` lub `claude-sonnet-4.6 OpenClaw stosuje następujący priorytet: -- jawne odwołania `provider/model` używają metadanych `providers` należących do manifestu właściciela +- jawne odwołania `provider/model` używają należących do manifestu metadanych `providers` - `modelPatterns` mają pierwszeństwo przed `modelPrefixes` -- jeśli pasują jednocześnie jeden plugin zewnętrzny i jeden bundlowany, wygrywa - plugin zewnętrzny -- pozostała niejednoznaczność jest ignorowana, dopóki użytkownik lub konfiguracja nie wskażą dostawcy +- jeśli jeden plugin niebundlowany i jeden plugin bundlowany pasują jednocześnie, wygrywa plugin niebundlowany +- pozostała niejednoznaczność jest ignorowana, dopóki użytkownik lub konfiguracja nie określi dostawcy Pola: -| Pole | Typ | Znaczenie | -| --------------- | ---------- | ---------------------------------------------------------------------------- | -| `modelPrefixes` | `string[]` | Prefiksy dopasowywane przez `startsWith` do skróconych identyfikatorów modeli. | -| `modelPatterns` | `string[]` | Źródła wyrażeń regularnych dopasowywane do skróconych identyfikatorów modeli po usunięciu sufiksu profilu. | +| Field | Type | What it means | +| --------------- | ---------- | ------------------------------------------------------------------------------- | +| `modelPrefixes` | `string[]` | Prefiksy dopasowywane przez `startsWith` do skrótowych identyfikatorów modeli. | +| `modelPatterns` | `string[]` | Źródła regex dopasowywane do skrótowych identyfikatorów modeli po usunięciu sufiksu profilu. | Starsze klucze możliwości na najwyższym poziomie są przestarzałe. Użyj `openclaw doctor --fix`, aby przenieść `speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, -`webFetchProviders` i `webSearchProviders` do `contracts`; zwykłe +`webFetchProviders` i `webSearchProviders` do `contracts`; standardowe ładowanie manifestu nie traktuje już tych pól najwyższego poziomu jako własności możliwości. ## Manifest a package.json -Te dwa pliki służą do różnych zadań: +Te dwa pliki pełnią różne role: -| Plik | Zastosowanie | -| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | -| `openclaw.plugin.json` | Wykrywanie, walidacja konfiguracji, metadane opcji uwierzytelniania i wskazówki UI, które muszą istnieć przed uruchomieniem kodu pluginu | -| `package.json` | Metadane npm, instalacja zależności i blok `openclaw` używany dla entrypointów, kontroli instalacji, konfiguracji lub metadanych katalogu | +| File | Use it for | +| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------- | +| `openclaw.plugin.json` | Wykrywanie, walidacja konfiguracji, metadane wyboru auth i wskazówki UI, które muszą istnieć przed uruchomieniem kodu pluginu | +| `package.json` | Metadane npm, instalacja zależności i blok `openclaw` używany dla punktów wejścia, bramkowania instalacji, konfiguracji lub metadanych katalogu | -Jeśli nie masz pewności, gdzie powinien trafić dany element metadanych, kieruj się tą zasadą: +Jeśli nie masz pewności, gdzie powinien trafić dany element metadanych, użyj tej zasady: -- jeśli OpenClaw musi wiedzieć o nim przed załadowaniem kodu pluginu, umieść go w `openclaw.plugin.json` -- jeśli dotyczy pakowania, plików wejściowych lub zachowania instalacji npm, umieść go w `package.json` +- jeśli OpenClaw musi znać tę informację przed załadowaniem kodu pluginu, umieść ją w `openclaw.plugin.json` +- jeśli dotyczy pakowania, plików wejściowych lub zachowania instalacji npm, umieść ją w `package.json` -### Pola `package.json`, które wpływają na wykrywanie +### Pola package.json wpływające na wykrywanie -Część metadanych pluginu sprzed uruchomienia runtime celowo znajduje się w `package.json` w bloku +Niektóre metadane pluginu sprzed uruchomienia celowo znajdują się w `package.json` w bloku `openclaw`, a nie w `openclaw.plugin.json`. Ważne przykłady: -| Pole | Znaczenie | +| Field | What it means | | ----------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | -| `openclaw.extensions` | Deklaruje natywne entrypointy pluginów. | -| `openclaw.setupEntry` | Lekki entrypoint tylko do konfiguracji używany podczas onboardingu i odroczonego uruchamiania kanału. | -| `openclaw.channel` | Lekkie metadane katalogu kanału, takie jak etykiety, ścieżki dokumentacji, aliasy i tekst wyboru. | -| `openclaw.channel.configuredState` | Lekkie metadane sprawdzania stanu konfiguracji, które mogą odpowiedzieć na pytanie „czy konfiguracja tylko z env już istnieje?” bez ładowania pełnego runtime kanału. | -| `openclaw.channel.persistedAuthState` | Lekkie metadane sprawdzania zapisanego stanu auth, które mogą odpowiedzieć na pytanie „czy cokolwiek jest już zalogowane?” bez ładowania pełnego runtime kanału. | -| `openclaw.install.npmSpec` / `openclaw.install.localPath` | Wskazówki instalacji/aktualizacji dla bundlowanych i zewnętrznie publikowanych pluginów. | -| `openclaw.install.defaultChoice` | Preferowana ścieżka instalacji, gdy dostępnych jest wiele źródeł instalacji. | -| `openclaw.install.minHostVersion` | Minimalna obsługiwana wersja hosta OpenClaw, z dolną granicą semver, taką jak `>=2026.3.22`. | -| `openclaw.install.allowInvalidConfigRecovery` | Umożliwia wąską ścieżkę odzyskiwania przez ponowną instalację bundlowanego pluginu, gdy konfiguracja jest nieprawidłowa. | -| `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` | Umożliwia ładowanie powierzchni kanału tylko do konfiguracji przed pełnym pluginem kanału podczas startu. | +| `openclaw.extensions` | Deklaruje punkty wejścia natywnych pluginów. | +| `openclaw.setupEntry` | Lekki punkt wejścia tylko do konfiguracji używany podczas onboardingu i odroczonego uruchamiania kanału. | +| `openclaw.channel` | Tanie metadane katalogu kanałów, takie jak etykiety, ścieżki dokumentacji, aliasy i teksty wyboru. | +| `openclaw.channel.configuredState` | Lekkie metadane sprawdzania stanu konfiguracji, które mogą odpowiedzieć na pytanie „czy konfiguracja oparta tylko na env już istnieje?” bez ładowania pełnego środowiska uruchomieniowego kanału. | +| `openclaw.channel.persistedAuthState` | Lekkie metadane sprawdzania utrwalonego stanu auth, które mogą odpowiedzieć na pytanie „czy coś jest już zalogowane?” bez ładowania pełnego środowiska uruchomieniowego kanału. | +| `openclaw.install.npmSpec` / `openclaw.install.localPath` | Wskazówki instalacji/aktualizacji dla bundlowanych i zewnętrznie publikowanych pluginów. | +| `openclaw.install.defaultChoice` | Preferowana ścieżka instalacji, gdy dostępnych jest wiele źródeł instalacji. | +| `openclaw.install.minHostVersion` | Minimalna obsługiwana wersja hosta OpenClaw, z użyciem dolnej granicy semver, np. `>=2026.3.22`. | +| `openclaw.install.allowInvalidConfigRecovery` | Pozwala na wąską ścieżkę odzyskiwania przez ponowną instalację bundlowanego pluginu, gdy konfiguracja jest nieprawidłowa. | +| `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` | Pozwala na ładowanie powierzchni kanału tylko do konfiguracji przed pełnym pluginem kanału podczas uruchamiania. | -`openclaw.install.minHostVersion` jest egzekwowane podczas instalacji i ładowania rejestru -manifestów. Nieprawidłowe wartości są odrzucane; poprawne, ale nowsze wartości powodują pominięcie +`openclaw.install.minHostVersion` jest wymuszane podczas instalacji i ładowania rejestru +manifestów. Nieprawidłowe wartości są odrzucane; nowsze, ale poprawne wartości powodują pominięcie pluginu na starszych hostach. `openclaw.install.allowInvalidConfigRecovery` jest celowo wąskie. Nie -sprawia, że dowolnie uszkodzone konfiguracje stają się instalowalne. Obecnie pozwala jedynie ścieżkom instalacji -odzyskać działanie po określonych błędach aktualizacji nieaktualnych bundlowanych pluginów, takich jak +sprawia, że dowolnie uszkodzone konfiguracje stają się możliwe do zainstalowania. Dziś pozwala tylko przepływom instalacji +odzyskać sprawność po określonych nieaktualnych błędach aktualizacji bundlowanego pluginu, takich jak brakująca ścieżka bundlowanego pluginu lub nieaktualny wpis `channels.` dla tego samego bundlowanego pluginu. Niezwiązane błędy konfiguracji nadal blokują instalację i kierują operatorów do `openclaw doctor --fix`. -`openclaw.channel.persistedAuthState` to metadane pakietu dla małego modułu sprawdzającego: +`openclaw.channel.persistedAuthState` to metadane pakietu dla małego modułu +sprawdzającego: ```json { @@ -387,12 +391,13 @@ do `openclaw doctor --fix`. } ``` -Używaj go, gdy konfiguracja, doctor lub przepływy configured-state potrzebują lekkiej sondy auth typu tak/nie -przed załadowaniem pełnego pluginu kanału. Docelowy eksport powinien być małą -funkcją odczytującą wyłącznie zapisany stan; nie kieruj jej przez pełny barrel runtime kanału. +Używaj tego, gdy konfiguracja, doctor lub przepływy stanu skonfigurowania potrzebują taniego sprawdzenia auth typu tak/nie +przed załadowaniem pełnego pluginu kanału. Eksport docelowy powinien być małą +funkcją, która odczytuje wyłącznie stan utrwalony; nie kieruj tego przez pełny +barrel środowiska uruchomieniowego kanału. -`openclaw.channel.configuredState` ma ten sam kształt dla lekkich kontroli -stanu konfiguracji opartych wyłącznie na env: +`openclaw.channel.configuredState` ma ten sam kształt dla tanich sprawdzeń +stanu skonfigurowania opartych wyłącznie na env: ```json { @@ -408,61 +413,63 @@ stanu konfiguracji opartych wyłącznie na env: } ``` -Używaj go, gdy kanał może odpowiedzieć na pytanie o stan konfiguracji na podstawie env lub innych małych -wejść niezwiązanych z runtime. Jeśli kontrola wymaga pełnego rozstrzygania konfiguracji lub rzeczywistego -runtime kanału, pozostaw tę logikę w hooku pluginu `config.hasConfiguredState`. +Używaj tego, gdy kanał może odpowiedzieć na pytanie o stan skonfigurowania na podstawie env lub innych małych +wejść niezwiązanych ze środowiskiem uruchomieniowym. Jeśli sprawdzenie wymaga pełnego rozstrzygania konfiguracji lub rzeczywistego +środowiska uruchomieniowego kanału, pozostaw tę logikę w hooku pluginu `config.hasConfiguredState`. -## Wymagania JSON Schema +## Wymagania schematu JSON -- **Każdy plugin musi dostarczać JSON Schema**, nawet jeśli nie akceptuje żadnej konfiguracji. +- **Każdy plugin musi dostarczać schemat JSON**, nawet jeśli nie akceptuje żadnej konfiguracji. - Pusty schemat jest akceptowalny (na przykład `{ "type": "object", "additionalProperties": false }`). -- Schematy są walidowane podczas odczytu/zapisu konfiguracji, a nie w runtime. +- Schematy są walidowane podczas odczytu/zapisu konfiguracji, a nie w czasie działania. ## Zachowanie walidacji -- Nieznane klucze `channels.*` są **błędami**, chyba że identyfikator kanału jest zadeklarowany przez +- Nieznane klucze `channels.*` są **błędami**, chyba że identyfikator kanału jest deklarowany przez manifest pluginu. - `plugins.entries.`, `plugins.allow`, `plugins.deny` i `plugins.slots.*` - muszą wskazywać **wykrywalne** identyfikatory pluginów. Nieznane identyfikatory są **błędami**. + muszą odwoływać się do **wykrywalnych** identyfikatorów pluginów. Nieznane identyfikatory są **błędami**. - Jeśli plugin jest zainstalowany, ale ma uszkodzony lub brakujący manifest albo schemat, - walidacja kończy się niepowodzeniem, a Doctor raportuje błąd pluginu. -- Jeśli konfiguracja pluginu istnieje, ale plugin jest **wyłączony**, konfiguracja jest zachowywana i + walidacja kończy się niepowodzeniem, a Doctor zgłasza błąd pluginu. +- Jeśli konfiguracja pluginu istnieje, ale plugin jest **wyłączony**, konfiguracja zostaje zachowana i w Doctor + logach pojawia się **ostrzeżenie**. -Pełny schemat `plugins.*` znajdziesz w [Configuration reference](/pl/gateway/configuration). +Pełny schemat `plugins.*` znajdziesz w [Dokumentacji konfiguracji](/pl/gateway/configuration). ## Uwagi -- Manifest jest **wymagany dla natywnych pluginów OpenClaw**, w tym ładowanych z lokalnego systemu plików. -- Runtime nadal ładuje moduł pluginu osobno; manifest służy wyłącznie do +- Manifest jest **wymagany dla natywnych pluginów OpenClaw**, także przy ładowaniu z lokalnego systemu plików. +- Środowisko uruchomieniowe nadal ładuje moduł pluginu osobno; manifest służy wyłącznie do wykrywania + walidacji. -- Natywne manifesty są parsowane jako JSON5, więc komentarze, końcowe przecinki i +- Natywne manifesty są parsowane przy użyciu JSON5, więc komentarze, końcowe przecinki i klucze bez cudzysłowów są akceptowane, o ile końcowa wartość nadal jest obiektem. -- Loader manifestu odczytuje wyłącznie udokumentowane pola manifestu. Unikaj dodawania - tutaj własnych kluczy najwyższego poziomu. -- `providerAuthEnvVars` to lekka ścieżka metadanych dla sond auth, walidacji znaczników env - i podobnych powierzchni uwierzytelniania dostawcy, które nie powinny uruchamiać runtime pluginu +- Loader manifestu odczytuje tylko udokumentowane pola manifestu. Unikaj dodawania + tutaj niestandardowych kluczy najwyższego poziomu. +- `providerAuthEnvVars` to tania ścieżka metadanych dla sond auth, walidacji znaczników env + i podobnych powierzchni auth dostawców, które nie powinny uruchamiać środowiska uruchomieniowego pluginu tylko po to, aby sprawdzić nazwy env. +- `providerAuthAliases` pozwala wariantom dostawców ponownie używać zmiennych env auth + innego dostawcy, profili auth, auth opartych na konfiguracji oraz wyboru onboardingu klucza API + bez kodowania tej relacji na sztywno w rdzeniu. +- `channelEnvVars` to tania ścieżka metadanych dla fallbacku shell-env, promptów konfiguracji + i podobnych powierzchni kanałów, które nie powinny uruchamiać środowiska uruchomieniowego pluginu tylko po to, aby sprawdzić nazwy env. -- `channelEnvVars` to lekka ścieżka metadanych dla rezerwowego użycia shell-env, promptów konfiguracji - i podobnych powierzchni kanału, które nie powinny uruchamiać runtime pluginu - tylko po to, aby sprawdzić nazwy env. -- `providerAuthChoices` to lekka ścieżka metadanych dla selektorów opcji uwierzytelniania, - rozstrzygania `--auth-choice`, mapowania preferowanego dostawcy i prostego rejestrowania flag CLI - podczas onboardingu przed załadowaniem runtime dostawcy. Metadane kreatora runtime, - które wymagają kodu dostawcy, znajdziesz w - [Provider runtime hooks](/pl/plugins/architecture#provider-runtime-hooks). +- `providerAuthChoices` to tania ścieżka metadanych dla selektorów wyboru auth, + rozstrzygania `--auth-choice`, mapowania preferowanych dostawców i prostej rejestracji + flag CLI onboardingu przed załadowaniem środowiska uruchomieniowego dostawcy. Dla metadanych + kreatora środowiska uruchomieniowego, które wymagają kodu dostawcy, zobacz + [Hooki środowiska uruchomieniowego dostawcy](/pl/plugins/architecture#provider-runtime-hooks). - Wyłączne rodzaje pluginów są wybierane przez `plugins.slots.*`. - `kind: "memory"` jest wybierane przez `plugins.slots.memory`. - `kind: "context-engine"` jest wybierane przez `plugins.slots.contextEngine` - (domyślnie: wbudowany `legacy`). -- `channels`, `providers`, `cliBackends` i `skills` mogą zostać pominięte, jeśli + (domyślnie: wbudowane `legacy`). +- `channels`, `providers`, `cliBackends` i `skills` można pominąć, gdy plugin ich nie potrzebuje. -- Jeśli Twój plugin zależy od modułów natywnych, udokumentuj kroki budowania oraz wszelkie - wymagania dotyczące allowlisty menedżera pakietów (na przykład pnpm `allow-build-scripts` +- Jeśli Twój plugin zależy od modułów natywnych, udokumentuj kroki budowania i wszelkie + wymagania dotyczące listy dozwolonych menedżera pakietów (na przykład pnpm `allow-build-scripts` - `pnpm rebuild `). ## Powiązane -- [Building Plugins](/pl/plugins/building-plugins) — rozpoczęcie pracy z pluginami -- [Plugin Architecture](/pl/plugins/architecture) — architektura wewnętrzna -- [SDK Overview](/pl/plugins/sdk-overview) — dokumentacja Plugin SDK +- [Tworzenie pluginów](/pl/plugins/building-plugins) — rozpoczęcie pracy z pluginami +- [Architektura pluginów](/pl/plugins/architecture) — architektura wewnętrzna +- [Przegląd SDK](/pl/plugins/sdk-overview) — dokumentacja Plugin SDK diff --git a/docs/pl/plugins/sdk-migration.md b/docs/pl/plugins/sdk-migration.md index 85de99b8a..9deaaa47d 100644 --- a/docs/pl/plugins/sdk-migration.md +++ b/docs/pl/plugins/sdk-migration.md @@ -2,111 +2,106 @@ read_when: - Widzisz ostrzeżenie OPENCLAW_PLUGIN_SDK_COMPAT_DEPRECATED - Widzisz ostrzeżenie OPENCLAW_EXTENSION_API_DEPRECATED - - Aktualizujesz plugin do nowoczesnej architektury pluginów - - Utrzymujesz zewnętrzny plugin OpenClaw + - Aktualizujesz wtyczkę do nowoczesnej architektury wtyczek OpenClaw + - Utrzymujesz zewnętrzną wtyczkę OpenClaw sidebarTitle: Migrate to SDK -summary: Przejdź ze starszej warstwy zgodności wstecznej na nowoczesny Plugin SDK +summary: Migracja ze starszej warstwy zgodności wstecznej do nowoczesnego Plugin SDK title: Migracja Plugin SDK x-i18n: - generated_at: "2026-04-08T09:45:41Z" + generated_at: "2026-04-09T01:29:55Z" model: gpt-5.4 provider: openai - source_hash: d9a2ce7f5553563516a549ca87e776a6a71e8dd8533a773c5ddbecfae43e7b77 + source_hash: 60cbb6c8be30d17770887d490c14e3a4538563339a5206fb419e51e0558bbc07 source_path: plugins/sdk-migration.md workflow: 15 --- # Migracja Plugin SDK -OpenClaw przeszedł od szerokiej warstwy zgodności wstecznej do nowoczesnej -architektury pluginów z ukierunkowanymi, udokumentowanymi importami. Jeśli -Twój plugin powstał przed wprowadzeniem nowej architektury, ten przewodnik -pomoże Ci przeprowadzić migrację. +OpenClaw przeszedł z szerokiej warstwy zgodności wstecznej na nowoczesną +architekturę wtyczek z ukierunkowanymi, udokumentowanymi importami. Jeśli Twoja wtyczka została zbudowana przed +wprowadzeniem nowej architektury, ten przewodnik pomoże Ci przeprowadzić migrację. ## Co się zmienia -Stary system pluginów udostępniał dwie szeroko otwarte powierzchnie, które -pozwalały pluginom importować wszystko, czego potrzebowały, z jednego punktu -wejścia: +Stary system wtyczek udostępniał dwie bardzo szerokie powierzchnie, które pozwalały wtyczkom importować +wszystko, czego potrzebowały, z jednego punktu wejścia: -- **`openclaw/plugin-sdk/compat`** — pojedynczy import, który reeksportował - dziesiątki helperów. Został wprowadzony po to, aby starsze pluginy oparte na - hookach nadal działały, podczas gdy budowano nową architekturę pluginów. -- **`openclaw/extension-api`** — most, który dawał pluginom bezpośredni dostęp - do helperów po stronie hosta, takich jak osadzony runner agenta. +- **`openclaw/plugin-sdk/compat`** — pojedynczy import, który reeksportował dziesiątki + pomocniczych elementów. Został wprowadzony po to, aby starsze wtyczki oparte na hookach nadal działały, gdy + budowana była nowa architektura wtyczek. +- **`openclaw/extension-api`** — pomost, który dawał wtyczkom bezpośredni dostęp do + pomocników po stronie hosta, takich jak osadzony runner agenta. -Obie te powierzchnie są teraz **przestarzałe**. Nadal działają w runtime, ale -nowe pluginy nie mogą już z nich korzystać, a istniejące pluginy powinny -przeprowadzić migrację, zanim kolejna główna wersja je usunie. +Obie powierzchnie są teraz **przestarzałe**. Nadal działają w środowisku uruchomieniowym, ale nowe +wtyczki nie mogą z nich korzystać, a istniejące wtyczki powinny przeprowadzić migrację przed kolejnym +głównym wydaniem, które je usunie. - Warstwa zgodności wstecznej zostanie usunięta w jednej z przyszłych głównych wersji. - Pluginy, które nadal importują z tych powierzchni, przestaną działać, gdy to nastąpi. + Warstwa zgodności wstecznej zostanie usunięta w jednym z przyszłych głównych wydań. + Wtyczki, które nadal importują z tych powierzchni, przestaną działać, gdy to nastąpi. ## Dlaczego to się zmieniło Stare podejście powodowało problemy: -- **Powolne uruchamianie** — zaimportowanie jednego helpera ładowało dziesiątki - niepowiązanych modułów +- **Wolne uruchamianie** — zaimportowanie jednego pomocnika ładowało dziesiątki niepowiązanych modułów - **Zależności cykliczne** — szerokie reeksporty ułatwiały tworzenie cykli importu -- **Niejasna powierzchnia API** — nie było sposobu, by stwierdzić, które eksporty - są stabilne, a które wewnętrzne +- **Niejasna powierzchnia API** — nie było sposobu, aby rozróżnić, które eksporty były stabilne, a które wewnętrzne -Nowoczesny Plugin SDK rozwiązuje ten problem: każda ścieżka importu (`openclaw/plugin-sdk/\`) -to mały, samodzielny moduł z jasnym przeznaczeniem i udokumentowanym kontraktem. +Nowoczesne Plugin SDK to naprawia: każda ścieżka importu (`openclaw/plugin-sdk/\`) +jest małym, samodzielnym modułem o jasno określonym celu i udokumentowanym kontrakcie. -Starsze wygodne powierzchnie providerów dla wbudowanych kanałów również zostały usunięte. Importy +Starsze wygodne punkty integracji dostawców dla dołączonych kanałów również zniknęły. Importy takie jak `openclaw/plugin-sdk/slack`, `openclaw/plugin-sdk/discord`, `openclaw/plugin-sdk/signal`, `openclaw/plugin-sdk/whatsapp`, -powierzchnie helperów oznaczone marką kanału oraz +pomocnicze punkty integracji oznaczone marką kanału oraz `openclaw/plugin-sdk/telegram-core` były prywatnymi skrótami mono-repo, a nie -stabilnymi kontraktami pluginów. Zamiast nich używaj wąskich, ogólnych podścieżek SDK. Wewnątrz -workspace wbudowanych pluginów przechowuj helpery należące do providera we własnym -`api.ts` lub `runtime-api.ts` tego pluginu. +stabilnymi kontraktami wtyczek. Zamiast tego używaj wąskich, ogólnych podścieżek SDK. W obrębie +dołączonego obszaru roboczego wtyczek trzymaj pomocniki należące do dostawcy we własnym +`api.ts` lub `runtime-api.ts` tej wtyczki. -Bieżące przykłady wbudowanych providerów: +Bieżące przykłady dołączonych dostawców: -- Anthropic przechowuje helpery strumieni specyficzne dla Claude we własnej powierzchni `api.ts` / +- Anthropic trzyma pomocniki strumieni specyficzne dla Claude we własnym punkcie integracji `api.ts` / `contract-api.ts` -- OpenAI przechowuje buildery providerów, helpery modeli domyślnych i buildery providerów - realtime we własnym `api.ts` -- OpenRouter przechowuje builder providera oraz helpery onboardingu/konfiguracji we własnym +- OpenAI trzyma konstruktory dostawców, pomocniki modeli domyślnych i konstruktory dostawców realtime + we własnym `api.ts` +- OpenRouter trzyma konstruktor dostawcy oraz pomocniki onboardingu/konfiguracji we własnym `api.ts` ## Jak przeprowadzić migrację - - Pluginy kanałów obsługujące zatwierdzanie udostępniają teraz natywne zachowanie zatwierdzania przez - `approvalCapability.nativeRuntime` oraz współdzielony rejestr runtime-context. + + Wtyczki kanałów obsługujące zatwierdzanie udostępniają teraz natywne zachowanie zatwierdzania przez + `approvalCapability.nativeRuntime` oraz współdzielony rejestr kontekstu runtime. Najważniejsze zmiany: - Zastąp `approvalCapability.handler.loadRuntime(...)` przez `approvalCapability.nativeRuntime` - - Przenieś uwierzytelnianie i dostarczanie specyficzne dla zatwierdzeń ze starszego powiązania `plugin.auth` / + - Przenieś uwierzytelnianie/dostarczanie specyficzne dla zatwierdzeń z przestarzałego połączenia `plugin.auth` / `plugin.approvals` do `approvalCapability` - `ChannelPlugin.approvals` zostało usunięte z publicznego kontraktu - pluginu kanału; przenieś pola delivery/native/render do `approvalCapability` - - `plugin.auth` pozostaje wyłącznie dla przepływów logowania/wylogowania kanału; hooki + wtyczek kanałów; przenieś pola delivery/native/render do `approvalCapability` + - `plugin.auth` pozostaje tylko dla przepływów logowania/wylogowania kanału; hooki uwierzytelniania zatwierdzeń w tym miejscu nie są już odczytywane przez core - - Rejestruj obiekty runtime należące do kanału, takie jak klienci, tokeny lub aplikacje + - Rejestruj obiekty runtime należące do kanału, takie jak klienci, tokeny czy aplikacje Bolt, przez `openclaw/plugin-sdk/channel-runtime-context` - - Nie wysyłaj komunikatów o przekierowaniu należących do pluginu z natywnych handlerów zatwierdzeń; - core zarządza teraz komunikatami o dostarczeniu w inne miejsce na podstawie rzeczywistych wyników delivery + - Nie wysyłaj komunikatów o przekierowaniu należących do wtyczki z natywnych handlerów zatwierdzeń; + komunikaty o dostarczeniu gdzie indziej na podstawie rzeczywistych wyników dostarczenia są teraz obsługiwane przez core - Przy przekazywaniu `channelRuntime` do `createChannelManager(...)` podaj rzeczywistą powierzchnię `createPluginRuntime().channel`. Częściowe stuby są odrzucane. - Aktualny układ capability zatwierdzeń znajdziesz w - `/plugins/sdk-channel-plugins`. + Zobacz `/plugins/sdk-channel-plugins`, aby poznać bieżący układ możliwości zatwierdzania. - - Jeśli Twój plugin używa `openclaw/plugin-sdk/windows-spawn`, nierozwiązane wrappery Windows - `.cmd`/`.bat` teraz kończą się bezpieczną porażką, chyba że jawnie przekażesz + + Jeśli Twoja wtyczka używa `openclaw/plugin-sdk/windows-spawn`, nierozwiązane wrappery Windows + `.cmd`/`.bat` kończą się teraz zamknięciem awaryjnym, chyba że jawnie przekażesz `allowShellFallback: true`. ```typescript @@ -116,19 +111,19 @@ Bieżące przykłady wbudowanych providerów: // Po const program = applyWindowsSpawnProgramPolicy({ candidate, - // Ustaw to tylko dla zaufanych wywołujących zgodności, którzy świadomie - // akceptują zapasowe wywołanie przez shell. + // Ustawiaj to tylko dla zaufanych wywołań zgodności, które celowo + // akceptują awaryjne przejście przez powłokę. allowShellFallback: true, }); ``` - Jeśli Twój kod wywołujący nie polega świadomie na zapasowym wywołaniu przez shell, nie ustawiaj - `allowShellFallback` i zamiast tego obsłuż zgłaszany błąd. + Jeśli Twój kod wywołujący nie polega celowo na awaryjnym przejściu przez powłokę, nie ustawiaj + `allowShellFallback` i zamiast tego obsłuż wyrzucany błąd. - Przeszukaj plugin pod kątem importów z którejkolwiek z przestarzałych powierzchni: + Wyszukaj w swojej wtyczce importy z którejkolwiek z przestarzałych powierzchni: ```bash grep -r "plugin-sdk/compat" my-plugin/ @@ -137,8 +132,8 @@ Bieżące przykłady wbudowanych providerów: - - Każdy eksport ze starej powierzchni odpowiada konkretnej nowoczesnej ścieżce importu: + + Każdy eksport ze starej powierzchni ma odpowiednik w konkretnej nowoczesnej ścieżce importu: ```typescript // Przed (przestarzała warstwa zgodności wstecznej) @@ -148,17 +143,17 @@ Bieżące przykłady wbudowanych providerów: resolveControlCommandGate, } from "openclaw/plugin-sdk/compat"; - // Po (nowoczesne ukierunkowane importy) + // Po (nowoczesne, ukierunkowane importy) import { createChannelReplyPipeline } from "openclaw/plugin-sdk/channel-reply-pipeline"; import { createPluginRuntimeStore } from "openclaw/plugin-sdk/runtime-store"; import { resolveControlCommandGate } from "openclaw/plugin-sdk/command-auth"; ``` - W przypadku helperów po stronie hosta używaj wstrzykniętego runtime pluginu zamiast importować je - bezpośrednio: + W przypadku pomocników po stronie hosta użyj wstrzykniętego runtime wtyczki zamiast importować + je bezpośrednio: ```typescript - // Przed (przestarzały most extension-api) + // Przed (przestarzały pomost extension-api) import { runEmbeddedPiAgent } from "openclaw/extension-api"; const result = await runEmbeddedPiAgent({ sessionId, prompt }); @@ -166,7 +161,7 @@ Bieżące przykłady wbudowanych providerów: const result = await api.runtime.agent.runEmbeddedPiAgent({ sessionId, prompt }); ``` - Ten sam wzorzec dotyczy innych starszych helperów mostu: + Ten sam wzorzec dotyczy innych starszych pomocników pomostu: | Stary import | Nowoczesny odpowiednik | | --- | --- | @@ -176,7 +171,7 @@ Bieżące przykłady wbudowanych providerów: | `resolveThinkingDefault` | `api.runtime.agent.resolveThinkingDefault` | | `resolveAgentTimeoutMs` | `api.runtime.agent.resolveAgentTimeoutMs` | | `ensureAgentWorkspace` | `api.runtime.agent.ensureAgentWorkspace` | - | helpery magazynu sesji | `api.runtime.agent.session.*` | + | pomocniki magazynu sesji | `api.runtime.agent.session.*` | @@ -193,204 +188,205 @@ Bieżące przykłady wbudowanych providerów: | Ścieżka importu | Przeznaczenie | Kluczowe eksporty | | --- | --- | --- | - | `plugin-sdk/plugin-entry` | Kanoniczny helper punktu wejścia pluginu | `definePluginEntry` | - | `plugin-sdk/core` | Starszy zbiorczy reeksport definicji/builderów wejść kanałów | `defineChannelPluginEntry`, `createChatChannelPlugin` | - | `plugin-sdk/config-schema` | Eksport schematu głównej konfiguracji | `OpenClawSchema` | - | `plugin-sdk/provider-entry` | Helper punktu wejścia pojedynczego providera | `defineSingleProviderPluginEntry` | - | `plugin-sdk/channel-core` | Ukierunkowane definicje i buildery wejść kanałów | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` | - | `plugin-sdk/setup` | Współdzielone helpery kreatora konfiguracji | Prompty allowlist i buildery statusu konfiguracji | - | `plugin-sdk/setup-runtime` | Helpery runtime dla konfiguracji | Bezpieczne przy imporcie adaptery poprawek konfiguracji, helpery notatek lookup, `promptResolvedAllowFrom`, `splitSetupEntries`, delegowane proxy konfiguracji | - | `plugin-sdk/setup-adapter-runtime` | Helpery adaptera konfiguracji | `createEnvPatchedAccountSetupAdapter` | - | `plugin-sdk/setup-tools` | Helpery narzędzi konfiguracji | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` | - | `plugin-sdk/account-core` | Helpery wielu kont | Helpery listy kont/konfiguracji/bramek akcji | - | `plugin-sdk/account-id` | Helpery account-id | `DEFAULT_ACCOUNT_ID`, normalizacja account-id | - | `plugin-sdk/account-resolution` | Helpery wyszukiwania kont | Helpery wyszukiwania kont i domyślnego fallbacku | - | `plugin-sdk/account-helpers` | Wąskie helpery kont | Helpery listy kont/akcji na kontach | + | `plugin-sdk/plugin-entry` | Kanoniczny pomocnik punktu wejścia wtyczki | `definePluginEntry` | + | `plugin-sdk/core` | Starszy zbiorczy reeksport definicji/budowniczych wejść kanałów | `defineChannelPluginEntry`, `createChatChannelPlugin` | + | `plugin-sdk/config-schema` | Eksport głównego schematu konfiguracji | `OpenClawSchema` | + | `plugin-sdk/provider-entry` | Pomocnik punktu wejścia pojedynczego dostawcy | `defineSingleProviderPluginEntry` | + | `plugin-sdk/channel-core` | Ukierunkowane definicje i konstruktory wejść kanałów | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` | + | `plugin-sdk/setup` | Współdzielone pomocniki kreatora konfiguracji | Prompty listy dozwolonych, konstruktory statusu konfiguracji | + | `plugin-sdk/setup-runtime` | Pomocniki runtime dla czasu konfiguracji | Bezpieczne importowo adaptery łatek konfiguracji, pomocniki notatek wyszukiwania, `promptResolvedAllowFrom`, `splitSetupEntries`, delegowane proxy konfiguracji | + | `plugin-sdk/setup-adapter-runtime` | Pomocniki adaptera konfiguracji | `createEnvPatchedAccountSetupAdapter` | + | `plugin-sdk/setup-tools` | Pomocniki narzędzi konfiguracji | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` | + | `plugin-sdk/account-core` | Pomocniki wielu kont | Pomocniki listy kont/konfiguracji/bramek akcji | + | `plugin-sdk/account-id` | Pomocniki identyfikatora konta | `DEFAULT_ACCOUNT_ID`, normalizacja identyfikatora konta | + | `plugin-sdk/account-resolution` | Pomocniki wyszukiwania kont | Wyszukiwanie kont + pomocniki awaryjnego użycia wartości domyślnej | + | `plugin-sdk/account-helpers` | Wąskie pomocniki kont | Pomocniki listy kont/akcji na koncie | | `plugin-sdk/channel-setup` | Adaptery kreatora konfiguracji | `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, `createOptionalChannelSetupWizard`, plus `DEFAULT_ACCOUNT_ID`, `createTopLevelChannelDmPolicy`, `setSetupChannelEnabled`, `splitSetupEntries` | - | `plugin-sdk/channel-pairing` | Prymitywy parowania DM | `createChannelPairingController` | - | `plugin-sdk/channel-reply-pipeline` | Powiązanie prefiksu odpowiedzi i wskaźnika pisania | `createChannelReplyPipeline` | + | `plugin-sdk/channel-pairing` | Podstawy parowania DM | `createChannelPairingController` | + | `plugin-sdk/channel-reply-pipeline` | Prefiks odpowiedzi + logika wpisywania | `createChannelReplyPipeline` | | `plugin-sdk/channel-config-helpers` | Fabryki adapterów konfiguracji | `createHybridChannelConfigAdapter` | - | `plugin-sdk/channel-config-schema` | Buildery schematu konfiguracji | Typy schematu konfiguracji kanału | - | `plugin-sdk/telegram-command-config` | Helpery konfiguracji poleceń Telegram | Normalizacja nazw poleceń, przycinanie opisów, walidacja duplikatów/konfliktów | - | `plugin-sdk/channel-policy` | Rozwiązywanie polityk grup/DM | `resolveChannelGroupRequireMention` | - | `plugin-sdk/channel-lifecycle` | Śledzenie statusu kont | `createAccountStatusSink` | - | `plugin-sdk/inbound-envelope` | Helpery kopert wejściowych | Współdzielone helpery routingu i budowania kopert | - | `plugin-sdk/inbound-reply-dispatch` | Helpery odpowiedzi wejściowych | Współdzielone helpery zapisu i dispatch | - | `plugin-sdk/messaging-targets` | Parsowanie celów wiadomości | Helpery parsowania/dopasowania celów | - | `plugin-sdk/outbound-media` | Helpery mediów wychodzących | Współdzielone ładowanie mediów wychodzących | - | `plugin-sdk/outbound-runtime` | Helpery runtime dla wyjścia | Helpery tożsamości wychodzącej/delegatów wysyłki | - | `plugin-sdk/thread-bindings-runtime` | Helpery powiązań wątków | Helpery cyklu życia powiązań wątków i adapterów | - | `plugin-sdk/agent-media-payload` | Starsze helpery payloadu mediów | Builder payloadu mediów agenta dla starszych układów pól | + | `plugin-sdk/channel-config-schema` | Konstruktory schematów konfiguracji | Typy schematów konfiguracji kanału | + | `plugin-sdk/telegram-command-config` | Pomocniki konfiguracji poleceń Telegram | Normalizacja nazw poleceń, przycinanie opisów, walidacja duplikatów/konfliktów | + | `plugin-sdk/channel-policy` | Rozstrzyganie polityki grup/DM | `resolveChannelGroupRequireMention` | + | `plugin-sdk/channel-lifecycle` | Śledzenie statusu konta | `createAccountStatusSink` | + | `plugin-sdk/inbound-envelope` | Pomocniki kopert wejściowych | Współdzielone pomocniki trasy + konstruktora koperty | + | `plugin-sdk/inbound-reply-dispatch` | Pomocniki odpowiedzi wejściowych | Współdzielone pomocniki zapisu i wysyłki | + | `plugin-sdk/messaging-targets` | Parsowanie celów wiadomości | Pomocniki parsowania/dopasowywania celów | + | `plugin-sdk/outbound-media` | Pomocniki mediów wychodzących | Współdzielone ładowanie mediów wychodzących | + | `plugin-sdk/outbound-runtime` | Pomocniki runtime dla ruchu wychodzącego | Pomocniki tożsamości wychodzącej/delegata wysyłki | + | `plugin-sdk/thread-bindings-runtime` | Pomocniki powiązań wątków | Cykl życia powiązań wątków i pomocniki adapterów | + | `plugin-sdk/agent-media-payload` | Starsze pomocniki ładunku mediów | Konstruktor ładunku mediów agenta dla starszych układów pól | | `plugin-sdk/channel-runtime` | Przestarzały shim zgodności | Tylko starsze narzędzia runtime kanału | | `plugin-sdk/channel-send-result` | Typy wyników wysyłki | Typy wyników odpowiedzi | - | `plugin-sdk/runtime-store` | Trwałe przechowywanie pluginu | `createPluginRuntimeStore` | - | `plugin-sdk/runtime` | Szerokie helpery runtime | Helpery runtime/logowania/backupu/instalacji pluginów | - | `plugin-sdk/runtime-env` | Wąskie helpery środowiska runtime | Logger/runtime env, helpery timeoutów, retry i backoff | - | `plugin-sdk/plugin-runtime` | Współdzielone helpery runtime pluginów | Helpery poleceń/hooków/http/interaktywnych funkcji pluginu | - | `plugin-sdk/hook-runtime` | Helpery pipeline hooków | Współdzielone helpery pipeline webhooków/wewnętrznych hooków | - | `plugin-sdk/lazy-runtime` | Helpery lazy runtime | `createLazyRuntimeModule`, `createLazyRuntimeMethod`, `createLazyRuntimeMethodBinder`, `createLazyRuntimeNamedExport`, `createLazyRuntimeSurface` | - | `plugin-sdk/process-runtime` | Helpery procesów | Współdzielone helpery exec | - | `plugin-sdk/cli-runtime` | Helpery runtime CLI | Formatowanie poleceń, oczekiwania, helpery wersji | - | `plugin-sdk/gateway-runtime` | Helpery Gateway | Klient Gateway i helpery poprawek statusu kanału | - | `plugin-sdk/config-runtime` | Helpery konfiguracji | Helpery ładowania/zapisu konfiguracji | - | `plugin-sdk/telegram-command-config` | Helpery poleceń Telegram | Stabilne fallbackowe helpery walidacji poleceń Telegram, gdy powierzchnia kontraktu wbudowanego Telegrama jest niedostępna | - | `plugin-sdk/approval-runtime` | Helpery promptów zatwierdzania | Payload zatwierdzeń exec/pluginu, helpery capability/profile zatwierdzeń, natywny routing/runtime zatwierdzeń | - | `plugin-sdk/approval-auth-runtime` | Helpery uwierzytelniania zatwierdzeń | Rozwiązywanie approvera, autoryzacja akcji w tym samym czacie | - | `plugin-sdk/approval-client-runtime` | Helpery klienta zatwierdzeń | Helpery profilu/filtra natywnych zatwierdzeń exec | - | `plugin-sdk/approval-delivery-runtime` | Helpery dostarczania zatwierdzeń | Adaptery capability/delivery natywnych zatwierdzeń | - | `plugin-sdk/approval-gateway-runtime` | Helpery Gateway dla zatwierdzeń | Współdzielony helper rozwiązywania approval gateway | - | `plugin-sdk/approval-handler-adapter-runtime` | Helpery adaptera zatwierdzeń | Lekkie helpery ładowania natywnych adapterów zatwierdzeń dla gorących punktów wejścia kanałów | - | `plugin-sdk/approval-handler-runtime` | Helpery handlerów zatwierdzeń | Szersze helpery runtime handlerów zatwierdzeń; preferuj węższe powierzchnie adaptera/gateway, gdy są wystarczające | - | `plugin-sdk/approval-native-runtime` | Helpery celu zatwierdzeń | Helpery natywnego celu zatwierdzeń/powiązania kont | - | `plugin-sdk/approval-reply-runtime` | Helpery odpowiedzi zatwierdzeń | Helpery payloadu odpowiedzi zatwierdzeń exec/pluginu | - | `plugin-sdk/channel-runtime-context` | Helpery runtime-context kanału | Ogólne helpery register/get/watch dla runtime-context kanału | - | `plugin-sdk/security-runtime` | Helpery bezpieczeństwa | Współdzielone helpery zaufania, bramek DM, treści zewnętrznych i zbierania sekretów | - | `plugin-sdk/ssrf-policy` | Helpery polityki SSRF | Helpery allowlist hostów i polityki sieci prywatnych | - | `plugin-sdk/ssrf-runtime` | Helpery runtime SSRF | Pinned-dispatcher, guarded fetch, helpery polityki SSRF | - | `plugin-sdk/collection-runtime` | Helpery ograniczonego cache | `pruneMapToMaxSize` | - | `plugin-sdk/diagnostic-runtime` | Helpery bramkowania diagnostyki | `isDiagnosticFlagEnabled`, `isDiagnosticsEnabled` | - | `plugin-sdk/error-runtime` | Helpery formatowania błędów | `formatUncaughtError`, `isApprovalNotFoundError`, helpery grafu błędów | - | `plugin-sdk/fetch-runtime` | Opakowane helpery fetch/proxy | `resolveFetch`, helpery proxy | - | `plugin-sdk/host-runtime` | Helpery normalizacji hosta | `normalizeHostname`, `normalizeScpRemoteHost` | - | `plugin-sdk/retry-runtime` | Helpery retry | `RetryConfig`, `retryAsync`, executory polityk | - | `plugin-sdk/allow-from` | Formatowanie allowlist | `formatAllowFromLowercase` | - | `plugin-sdk/allowlist-resolution` | Mapowanie danych wejściowych allowlist | `mapAllowlistResolutionInputs` | - | `plugin-sdk/command-auth` | Bramkowanie poleceń i helpery powierzchni poleceń | `resolveControlCommandGate`, helpery autoryzacji nadawcy, helpery rejestru poleceń | - | `plugin-sdk/secret-input` | Parsowanie wejścia sekretów | Helpery wejścia sekretów | - | `plugin-sdk/webhook-ingress` | Helpery żądań webhook | Narzędzia celu webhook | - | `plugin-sdk/webhook-request-guards` | Helpery guardów treści webhook | Helpery odczytu/limitów treści żądania | - | `plugin-sdk/reply-runtime` | Współdzielony runtime odpowiedzi | Dispatch wejściowy, heartbeat, planer odpowiedzi, chunking | - | `plugin-sdk/reply-dispatch-runtime` | Wąskie helpery dispatch odpowiedzi | Helpery finalize i dispatch providera | - | `plugin-sdk/reply-history` | Helpery historii odpowiedzi | `buildHistoryContext`, `buildPendingHistoryContextFromMap`, `recordPendingHistoryEntry`, `clearHistoryEntriesIfEnabled` | - | `plugin-sdk/reply-reference` | Planowanie referencji odpowiedzi | `createReplyReferencePlanner` | - | `plugin-sdk/reply-chunking` | Helpery chunków odpowiedzi | Helpery chunkingu tekstu/markdown | - | `plugin-sdk/session-store-runtime` | Helpery magazynu sesji | Helpery ścieżki magazynu i updated-at | - | `plugin-sdk/state-paths` | Helpery ścieżek stanu | Helpery katalogów stanu i OAuth | - | `plugin-sdk/routing` | Helpery routingu/kluczy sesji | `resolveAgentRoute`, `buildAgentSessionKey`, `resolveDefaultAgentBoundAccountId`, helpery normalizacji kluczy sesji | - | `plugin-sdk/status-helpers` | Helpery statusu kanału | Buildery podsumowania statusu kanału/konta, domyślne wartości stanu runtime, helpery metadanych problemów | - | `plugin-sdk/target-resolver-runtime` | Helpery rozwiązywania celu | Współdzielone helpery target resolver | - | `plugin-sdk/string-normalization-runtime` | Helpery normalizacji ciągów | Helpery normalizacji slugów/ciągów | - | `plugin-sdk/request-url` | Helpery URL żądania | Wyodrębnianie URL-i jako stringów z danych wejściowych podobnych do request | - | `plugin-sdk/run-command` | Helpery poleceń z limitem czasu | Uruchamianie poleceń z limitem czasu i znormalizowanym stdout/stderr | + | `plugin-sdk/runtime-store` | Trwałe przechowywanie wtyczek | `createPluginRuntimeStore` | + | `plugin-sdk/runtime` | Szerokie pomocniki runtime | Pomocniki runtime/logowania/kopii zapasowej/instalacji wtyczek | + | `plugin-sdk/runtime-env` | Wąskie pomocniki środowiska runtime | Logger/pomocniki środowiska runtime, timeout, retry i backoff | + | `plugin-sdk/plugin-runtime` | Współdzielone pomocniki runtime wtyczek | Pomocniki poleceń/hooków/http/interaktywnych dla wtyczek | + | `plugin-sdk/hook-runtime` | Pomocniki potoku hooków | Współdzielone pomocniki potoku webhooków/wewnętrznych hooków | + | `plugin-sdk/lazy-runtime` | Pomocniki leniwego runtime | `createLazyRuntimeModule`, `createLazyRuntimeMethod`, `createLazyRuntimeMethodBinder`, `createLazyRuntimeNamedExport`, `createLazyRuntimeSurface` | + | `plugin-sdk/process-runtime` | Pomocniki procesów | Współdzielone pomocniki `exec` | + | `plugin-sdk/cli-runtime` | Pomocniki runtime CLI | Formatowanie poleceń, oczekiwania, pomocniki wersji | + | `plugin-sdk/gateway-runtime` | Pomocniki bramy | Klient bramy i pomocniki łatek statusu kanału | + | `plugin-sdk/config-runtime` | Pomocniki konfiguracji | Pomocniki ładowania/zapisu konfiguracji | + | `plugin-sdk/telegram-command-config` | Pomocniki poleceń Telegram | Pomocniki walidacji poleceń Telegram ze stabilnym fallbackiem, gdy powierzchnia kontraktu dołączonego Telegrama jest niedostępna | + | `plugin-sdk/approval-runtime` | Pomocniki promptów zatwierdzania | Ładunek zatwierdzania exec/wtyczki, pomocniki możliwości/profili zatwierdzania, natywne pomocniki routingu/runtime zatwierdzania | + | `plugin-sdk/approval-auth-runtime` | Pomocniki uwierzytelniania zatwierdzeń | Rozstrzyganie zatwierdzających, uwierzytelnianie akcji w tym samym czacie | + | `plugin-sdk/approval-client-runtime` | Pomocniki klienta zatwierdzeń | Pomocniki profilu/filtrów natywnego zatwierdzania exec | + | `plugin-sdk/approval-delivery-runtime` | Pomocniki dostarczania zatwierdzeń | Adaptery możliwości/dostarczania natywnych zatwierdzeń | + | `plugin-sdk/approval-gateway-runtime` | Pomocniki bramy zatwierdzeń | Współdzielony pomocnik rozstrzygania bramy zatwierdzeń | + | `plugin-sdk/approval-handler-adapter-runtime` | Pomocniki adaptera zatwierdzeń | Lekkie pomocniki ładowania natywnych adapterów zatwierdzania dla gorących punktów wejścia kanału | + | `plugin-sdk/approval-handler-runtime` | Pomocniki handlera zatwierdzeń | Szersze pomocniki runtime handlera zatwierdzeń; preferuj węższe punkty integracji adaptera/bramy, gdy są wystarczające | + | `plugin-sdk/approval-native-runtime` | Pomocniki celu zatwierdzeń | Pomocniki natywnego wiązania celu/konta dla zatwierdzeń | + | `plugin-sdk/approval-reply-runtime` | Pomocniki odpowiedzi zatwierdzeń | Pomocniki ładunku odpowiedzi zatwierdzeń exec/wtyczki | + | `plugin-sdk/channel-runtime-context` | Pomocniki kontekstu runtime kanału | Ogólne pomocniki register/get/watch dla kontekstu runtime kanału | + | `plugin-sdk/security-runtime` | Pomocniki bezpieczeństwa | Współdzielone pomocniki zaufania, bramek DM, treści zewnętrznych i zbierania sekretów | + | `plugin-sdk/ssrf-policy` | Pomocniki polityki SSRF | Pomocniki listy dozwolonych hostów i polityki sieci prywatnej | + | `plugin-sdk/ssrf-runtime` | Pomocniki runtime SSRF | Przypięty dispatcher, strzeżony fetch, pomocniki polityki SSRF | + | `plugin-sdk/collection-runtime` | Pomocniki ograniczonego cache | `pruneMapToMaxSize` | + | `plugin-sdk/diagnostic-runtime` | Pomocniki bramek diagnostycznych | `isDiagnosticFlagEnabled`, `isDiagnosticsEnabled` | + | `plugin-sdk/error-runtime` | Pomocniki formatowania błędów | `formatUncaughtError`, `isApprovalNotFoundError`, pomocniki grafu błędów | + | `plugin-sdk/fetch-runtime` | Pomocniki opakowanego fetch/proxy | `resolveFetch`, pomocniki proxy | + | `plugin-sdk/host-runtime` | Pomocniki normalizacji hosta | `normalizeHostname`, `normalizeScpRemoteHost` | + | `plugin-sdk/retry-runtime` | Pomocniki ponawiania | `RetryConfig`, `retryAsync`, uruchamiacze polityk | + | `plugin-sdk/allow-from` | Formatowanie listy dozwolonych | `formatAllowFromLowercase` | + | `plugin-sdk/allowlist-resolution` | Mapowanie wejść listy dozwolonych | `mapAllowlistResolutionInputs` | + | `plugin-sdk/command-auth` | Bramkowanie poleceń i pomocniki powierzchni poleceń | `resolveControlCommandGate`, pomocniki autoryzacji nadawcy, pomocniki rejestru poleceń | + | `plugin-sdk/command-status` | Renderery statusu/pomocy poleceń | `buildCommandsMessage`, `buildCommandsMessagePaginated`, `buildHelpMessage` | + | `plugin-sdk/secret-input` | Parsowanie wejść sekretów | Pomocniki wejść sekretów | + | `plugin-sdk/webhook-ingress` | Pomocniki żądań webhooków | Narzędzia celu webhooka | + | `plugin-sdk/webhook-request-guards` | Pomocniki guardów żądań webhooków | Pomocniki odczytu/limitów treści żądania | + | `plugin-sdk/reply-runtime` | Współdzielony runtime odpowiedzi | Wysyłka wejściowa, heartbeat, planista odpowiedzi, dzielenie na części | + | `plugin-sdk/reply-dispatch-runtime` | Wąskie pomocniki wysyłki odpowiedzi | Pomocniki finalizacji + wysyłki dostawcy | + | `plugin-sdk/reply-history` | Pomocniki historii odpowiedzi | `buildHistoryContext`, `buildPendingHistoryContextFromMap`, `recordPendingHistoryEntry`, `clearHistoryEntriesIfEnabled` | + | `plugin-sdk/reply-reference` | Planowanie odwołań odpowiedzi | `createReplyReferencePlanner` | + | `plugin-sdk/reply-chunking` | Pomocniki dzielenia odpowiedzi | Pomocniki dzielenia tekstu/markdownu | + | `plugin-sdk/session-store-runtime` | Pomocniki magazynu sesji | Ścieżka magazynu + pomocniki `updated-at` | + | `plugin-sdk/state-paths` | Pomocniki ścieżek stanu | Pomocniki katalogów stanu i OAuth | + | `plugin-sdk/routing` | Pomocniki routingu/klucza sesji | `resolveAgentRoute`, `buildAgentSessionKey`, `resolveDefaultAgentBoundAccountId`, pomocniki normalizacji klucza sesji | + | `plugin-sdk/status-helpers` | Pomocniki statusu kanału | Konstruktory podsumowań statusu kanału/konta, domyślne wartości stanu runtime, pomocniki metadanych problemów | + | `plugin-sdk/target-resolver-runtime` | Pomocniki rozstrzygania celu | Współdzielone pomocniki rozstrzygania celu | + | `plugin-sdk/string-normalization-runtime` | Pomocniki normalizacji ciągów | Pomocniki normalizacji slugów/ciągów | + | `plugin-sdk/request-url` | Pomocniki URL żądania | Wyodrębnianie tekstowych URL z danych wejściowych podobnych do żądania | + | `plugin-sdk/run-command` | Pomocniki poleceń z limitem czasu | Uruchamiacz poleceń z znormalizowanym stdout/stderr | | `plugin-sdk/param-readers` | Odczyt parametrów | Typowe odczyty parametrów narzędzi/CLI | - | `plugin-sdk/tool-payload` | Wyodrębnianie payloadu narzędzi | Wyodrębnianie znormalizowanych payloadów z obiektów wyników narzędzi | - | `plugin-sdk/tool-send` | Wyodrębnianie wysyłki narzędzi | Wyodrębnianie kanonicznych pól celu wysyłki z argumentów narzędzi | - | `plugin-sdk/temp-path` | Helpery ścieżek tymczasowych | Współdzielone helpery ścieżek tymczasowego pobierania | - | `plugin-sdk/logging-core` | Helpery logowania | Logger podsystemu i helpery redakcji | - | `plugin-sdk/markdown-table-runtime` | Helpery tabel Markdown | Helpery trybu tabel Markdown | - | `plugin-sdk/reply-payload` | Typy odpowiedzi wiadomości | Typy payloadu odpowiedzi | - | `plugin-sdk/provider-setup` | Kuratorowane helpery konfiguracji lokalnych/samohostowanych providerów | Helpery wykrywania/konfiguracji samohostowanych providerów | - | `plugin-sdk/self-hosted-provider-setup` | Ukierunkowane helpery konfiguracji samohostowanych providerów zgodnych z OpenAI | Te same helpery wykrywania/konfiguracji samohostowanych providerów | - | `plugin-sdk/provider-auth-runtime` | Helpery uwierzytelniania providera w runtime | Helpery rozwiązywania kluczy API w runtime | - | `plugin-sdk/provider-auth-api-key` | Helpery konfiguracji klucza API providera | Helpery onboardingu/zapisu profilu klucza API | - | `plugin-sdk/provider-auth-result` | Helpery wyniku uwierzytelniania providera | Standardowy builder wyniku uwierzytelniania OAuth | - | `plugin-sdk/provider-auth-login` | Helpery interaktywnego logowania providera | Współdzielone helpery interaktywnego logowania | - | `plugin-sdk/provider-env-vars` | Helpery zmiennych środowiskowych providera | Helpery wyszukiwania zmiennych środowiskowych do uwierzytelniania providera | - | `plugin-sdk/provider-model-shared` | Współdzielone helpery modeli/odtwarzania providera | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`, współdzielone buildery polityki replay, helpery endpointów providera i helpery normalizacji model-id | - | `plugin-sdk/provider-catalog-shared` | Współdzielone helpery katalogu providera | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat` | - | `plugin-sdk/provider-onboard` | Poprawki onboardingu providera | Helpery konfiguracji onboardingu | - | `plugin-sdk/provider-http` | Helpery HTTP providera | Ogólne helpery HTTP/zdolności endpointów providera | - | `plugin-sdk/provider-web-fetch` | Helpery web-fetch providera | Helpery rejestracji/cache providera web-fetch | - | `plugin-sdk/provider-web-search-config-contract` | Helpery konfiguracji web-search providera | Wąskie helpery konfiguracji/poświadczeń web-search dla providerów, które nie wymagają powiązania włączania pluginu | - | `plugin-sdk/provider-web-search-contract` | Helpery kontraktu web-search providera | Wąskie helpery kontraktu konfiguracji/poświadczeń web-search, takie jak `createWebSearchProviderContractFields`, `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig` oraz zakresowe settery/gettery poświadczeń | - | `plugin-sdk/provider-web-search` | Helpery web-search providera | Helpery rejestracji/cache/runtime providera web-search | - | `plugin-sdk/provider-tools` | Helpery zgodności narzędzi/schematów providera | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, czyszczenie schematów Gemini + diagnostyka oraz helpery zgodności xAI, takie jak `resolveXaiModelCompatPatch` / `applyXaiModelCompat` | - | `plugin-sdk/provider-usage` | Helpery użycia providera | `fetchClaudeUsage`, `fetchGeminiUsage`, `fetchGithubCopilotUsage` i inne helpery użycia providera | - | `plugin-sdk/provider-stream` | Helpery opakowań strumienia providera | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`, typy opakowań strumienia oraz współdzielone helpery opakowań Anthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot | + | `plugin-sdk/tool-payload` | Wyodrębnianie ładunku narzędzia | Wyodrębnianie znormalizowanych ładunków z obiektów wyników narzędzi | + | `plugin-sdk/tool-send` | Wyodrębnianie wysyłki narzędzia | Wyodrębnianie kanonicznych pól celu wysyłki z argumentów narzędzia | + | `plugin-sdk/temp-path` | Pomocniki ścieżek tymczasowych | Współdzielone pomocniki ścieżek tymczasowego pobierania | + | `plugin-sdk/logging-core` | Pomocniki logowania | Logger podsystemu i pomocniki redakcji danych | + | `plugin-sdk/markdown-table-runtime` | Pomocniki tabel markdown | Pomocniki trybów tabel markdown | + | `plugin-sdk/reply-payload` | Typy odpowiedzi wiadomości | Typy ładunku odpowiedzi | + | `plugin-sdk/provider-setup` | Kuratorowane pomocniki konfiguracji lokalnych/samohostowanych dostawców | Pomocniki wykrywania/konfiguracji samohostowanych dostawców | + | `plugin-sdk/self-hosted-provider-setup` | Ukierunkowane pomocniki konfiguracji samohostowanych dostawców zgodnych z OpenAI | Te same pomocniki wykrywania/konfiguracji samohostowanych dostawców | + | `plugin-sdk/provider-auth-runtime` | Pomocniki uwierzytelniania runtime dostawców | Pomocniki runtime rozstrzygania klucza API | + | `plugin-sdk/provider-auth-api-key` | Pomocniki konfiguracji klucza API dostawcy | Pomocniki onboardingu/zapisu profilu dla klucza API | + | `plugin-sdk/provider-auth-result` | Pomocniki wyniku uwierzytelnienia dostawcy | Standardowy konstruktor wyniku uwierzytelnienia OAuth | + | `plugin-sdk/provider-auth-login` | Pomocniki interaktywnego logowania dostawcy | Współdzielone pomocniki logowania interaktywnego | + | `plugin-sdk/provider-env-vars` | Pomocniki zmiennych środowiskowych dostawcy | Pomocniki wyszukiwania zmiennych środowiskowych uwierzytelniania dostawcy | + | `plugin-sdk/provider-model-shared` | Współdzielone pomocniki modeli/odtwarzania dostawców | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`, współdzielone konstruktory polityk odtwarzania, pomocniki endpointów dostawców oraz normalizacja identyfikatorów modeli | + | `plugin-sdk/provider-catalog-shared` | Współdzielone pomocniki katalogu dostawców | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat` | + | `plugin-sdk/provider-onboard` | Łatki onboardingu dostawców | Pomocniki konfiguracji onboardingu | + | `plugin-sdk/provider-http` | Pomocniki HTTP dostawców | Ogólne pomocniki HTTP/zdolności endpointów dostawców | + | `plugin-sdk/provider-web-fetch` | Pomocniki web-fetch dostawców | Pomocniki rejestracji/cache dostawcy web-fetch | + | `plugin-sdk/provider-web-search-config-contract` | Pomocniki konfiguracji wyszukiwania w sieci dla dostawców | Wąskie pomocniki konfiguracji/poświadczeń wyszukiwania w sieci dla dostawców, którzy nie potrzebują logiki włączania wtyczki | + | `plugin-sdk/provider-web-search-contract` | Pomocniki kontraktu wyszukiwania w sieci dla dostawców | Wąskie pomocniki kontraktu konfiguracji/poświadczeń wyszukiwania w sieci, takie jak `createWebSearchProviderContractFields`, `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig` oraz funkcje ustawiania/pobierania poświadczeń o ograniczonym zakresie | + | `plugin-sdk/provider-web-search` | Pomocniki wyszukiwania w sieci dla dostawców | Pomocniki rejestracji/cache/runtime dostawcy wyszukiwania w sieci | + | `plugin-sdk/provider-tools` | Pomocniki zgodności narzędzi/schematów dostawców | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, czyszczenie schematu Gemini + diagnostyka oraz pomocniki zgodności xAI, takie jak `resolveXaiModelCompatPatch` / `applyXaiModelCompat` | + | `plugin-sdk/provider-usage` | Pomocniki użycia dostawców | `fetchClaudeUsage`, `fetchGeminiUsage`, `fetchGithubCopilotUsage` i inne pomocniki użycia dostawców | + | `plugin-sdk/provider-stream` | Pomocniki opakowań strumieni dostawców | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`, typy opakowań strumieni oraz współdzielone opakowania Anthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot | | `plugin-sdk/keyed-async-queue` | Uporządkowana kolejka async | `KeyedAsyncQueue` | - | `plugin-sdk/media-runtime` | Współdzielone helpery mediów | Helpery pobierania/przekształcania/przechowywania mediów oraz buildery payloadów mediów | - | `plugin-sdk/media-generation-runtime` | Współdzielone helpery generowania mediów | Współdzielone helpery failover, wybór kandydatów i komunikaty o brakującym modelu dla generowania obrazów/wideo/muzyki | - | `plugin-sdk/media-understanding` | Helpery rozumienia mediów | Typy providerów rozumienia mediów oraz eksporty helperów obrazów/audio dla providerów | - | `plugin-sdk/text-runtime` | Współdzielone helpery tekstowe | Usuwanie tekstu widocznego dla asystenta, helpery renderowania/chunkingu/tabel markdown, helpery redakcji, helpery tagów dyrektyw, narzędzia bezpiecznego tekstu i pokrewne helpery tekstu/logowania | - | `plugin-sdk/text-chunking` | Helpery chunkingu tekstu | Helper chunkingu tekstu wychodzącego | - | `plugin-sdk/speech` | Helpery mowy | Typy providerów mowy oraz eksporty helperów dyrektyw, rejestru i walidacji dla providerów | - | `plugin-sdk/speech-core` | Współdzielony rdzeń mowy | Typy providerów mowy, rejestr, dyrektywy, normalizacja | - | `plugin-sdk/realtime-transcription` | Helpery transkrypcji realtime | Typy providerów i helpery rejestru | - | `plugin-sdk/realtime-voice` | Helpery głosu realtime | Typy providerów i helpery rejestru | - | `plugin-sdk/image-generation-core` | Współdzielony rdzeń generowania obrazów | Typy generowania obrazów, failover, uwierzytelnianie i helpery rejestru | - | `plugin-sdk/music-generation` | Helpery generowania muzyki | Typy providera/żądania/wyniku generowania muzyki | - | `plugin-sdk/music-generation-core` | Współdzielony rdzeń generowania muzyki | Typy generowania muzyki, helpery failover, wyszukiwanie providera i parsowanie model-ref | - | `plugin-sdk/video-generation` | Helpery generowania wideo | Typy providera/żądania/wyniku generowania wideo | - | `plugin-sdk/video-generation-core` | Współdzielony rdzeń generowania wideo | Typy generowania wideo, helpery failover, wyszukiwanie providera i parsowanie model-ref | - | `plugin-sdk/interactive-runtime` | Helpery interaktywnych odpowiedzi | Normalizacja/redukcja payloadu interaktywnych odpowiedzi | - | `plugin-sdk/channel-config-primitives` | Prymitywy konfiguracji kanału | Wąskie prymitywy channel config-schema | - | `plugin-sdk/channel-config-writes` | Helpery zapisu konfiguracji kanału | Helpery autoryzacji zapisu konfiguracji kanału | - | `plugin-sdk/channel-plugin-common` | Współdzielone preludium kanału | Współdzielone eksporty preludium pluginu kanału | - | `plugin-sdk/channel-status` | Helpery statusu kanału | Współdzielone helpery snapshotu/podsumowania statusu kanału | - | `plugin-sdk/allowlist-config-edit` | Helpery konfiguracji allowlist | Helpery edycji/odczytu konfiguracji allowlist | - | `plugin-sdk/group-access` | Helpery dostępu do grup | Współdzielone helpery decyzji dostępu do grup | - | `plugin-sdk/direct-dm` | Helpery bezpośrednich DM | Współdzielone helpery autoryzacji/guardów bezpośrednich DM | - | `plugin-sdk/extension-shared` | Współdzielone helpery rozszerzeń | Prymitywy helperów kanałów pasywnych/statusu i ambient proxy | - | `plugin-sdk/webhook-targets` | Helpery celów webhook | Rejestr celów webhook i helpery instalacji rout | - | `plugin-sdk/webhook-path` | Helpery ścieżek webhook | Helpery normalizacji ścieżek webhook | - | `plugin-sdk/web-media` | Współdzielone helpery web media | Helpery ładowania mediów zdalnych/lokalnych | - | `plugin-sdk/zod` | Reeksport zod | Reeksportowany `zod` dla użytkowników Plugin SDK | - | `plugin-sdk/memory-core` | Helpery wbudowanego memory-core | Powierzchnia helperów menedżera pamięci/konfiguracji/plików/CLI | - | `plugin-sdk/memory-core-engine-runtime` | Fasada runtime silnika pamięci | Fasada runtime indeksu/wyszukiwania pamięci | - | `plugin-sdk/memory-core-host-engine-foundation` | Silnik hosta foundation dla pamięci | Eksporty silnika hosta foundation dla pamięci | - | `plugin-sdk/memory-core-host-engine-embeddings` | Silnik embeddingów hosta dla pamięci | Eksporty silnika embeddingów hosta dla pamięci | - | `plugin-sdk/memory-core-host-engine-qmd` | Silnik QMD hosta dla pamięci | Eksporty silnika QMD hosta dla pamięci | - | `plugin-sdk/memory-core-host-engine-storage` | Silnik storage hosta dla pamięci | Eksporty silnika storage hosta dla pamięci | - | `plugin-sdk/memory-core-host-multimodal` | Helpery multimodalnego hosta pamięci | Helpery multimodalnego hosta pamięci | - | `plugin-sdk/memory-core-host-query` | Helpery zapytań hosta pamięci | Helpery zapytań hosta pamięci | - | `plugin-sdk/memory-core-host-secret` | Helpery sekretów hosta pamięci | Helpery sekretów hosta pamięci | - | `plugin-sdk/memory-core-host-events` | Helpery dziennika zdarzeń hosta pamięci | Helpery dziennika zdarzeń hosta pamięci | - | `plugin-sdk/memory-core-host-status` | Helpery statusu hosta pamięci | Helpery statusu hosta pamięci | - | `plugin-sdk/memory-core-host-runtime-cli` | Runtime CLI hosta pamięci | Helpery runtime CLI hosta pamięci | - | `plugin-sdk/memory-core-host-runtime-core` | Główny runtime hosta pamięci | Helpery głównego runtime hosta pamięci | - | `plugin-sdk/memory-core-host-runtime-files` | Helpery plików/runtime hosta pamięci | Helpery plików/runtime hosta pamięci | - | `plugin-sdk/memory-host-core` | Alias głównego runtime hosta pamięci | Neutralny wobec dostawcy alias helperów głównego runtime hosta pamięci | - | `plugin-sdk/memory-host-events` | Alias dziennika zdarzeń hosta pamięci | Neutralny wobec dostawcy alias helperów dziennika zdarzeń hosta pamięci | - | `plugin-sdk/memory-host-files` | Alias plików/runtime hosta pamięci | Neutralny wobec dostawcy alias helperów plików/runtime hosta pamięci | - | `plugin-sdk/memory-host-markdown` | Helpery zarządzanego markdown | Współdzielone helpery zarządzanego markdown dla pluginów sąsiadujących z pamięcią | + | `plugin-sdk/media-runtime` | Współdzielone pomocniki mediów | Pomocniki pobierania/przekształcania/przechowywania mediów oraz konstruktory ładunków mediów | + | `plugin-sdk/media-generation-runtime` | Współdzielone pomocniki generowania mediów | Współdzielone pomocniki failover, wyboru kandydatów i komunikatów o brakujących modelach dla generowania obrazów/wideo/muzyki | + | `plugin-sdk/media-understanding` | Pomocniki media-understanding | Typy dostawców media-understanding oraz eksporty pomocników obrazów/audio dla dostawców | + | `plugin-sdk/text-runtime` | Współdzielone pomocniki tekstowe | Usuwanie tekstu widocznego dla asystenta, renderowanie/dzielenie/tabele markdown, pomocniki redakcji, pomocniki tagów dyrektyw, bezpieczny tekst i powiązane pomocniki tekstu/logowania | + | `plugin-sdk/text-chunking` | Pomocniki dzielenia tekstu | Pomocnik dzielenia tekstu wychodzącego | + | `plugin-sdk/speech` | Pomocniki mowy | Typy dostawców mowy oraz eksporty pomocników dyrektyw, rejestru i walidacji dla dostawców | + | `plugin-sdk/speech-core` | Współdzielony rdzeń mowy | Typy dostawców mowy, rejestr, dyrektywy, normalizacja | + | `plugin-sdk/realtime-transcription` | Pomocniki transkrypcji realtime | Typy dostawców i pomocniki rejestru | + | `plugin-sdk/realtime-voice` | Pomocniki głosu realtime | Typy dostawców i pomocniki rejestru | + | `plugin-sdk/image-generation-core` | Współdzielony rdzeń generowania obrazów | Typy generowania obrazów, failover, uwierzytelnianie i pomocniki rejestru | + | `plugin-sdk/music-generation` | Pomocniki generowania muzyki | Typy dostawcy/żądania/wyniku generowania muzyki | + | `plugin-sdk/music-generation-core` | Współdzielony rdzeń generowania muzyki | Typy generowania muzyki, pomocniki failover, wyszukiwanie dostawcy i parsowanie model-ref | + | `plugin-sdk/video-generation` | Pomocniki generowania wideo | Typy dostawcy/żądania/wyniku generowania wideo | + | `plugin-sdk/video-generation-core` | Współdzielony rdzeń generowania wideo | Typy generowania wideo, pomocniki failover, wyszukiwanie dostawcy i parsowanie model-ref | + | `plugin-sdk/interactive-runtime` | Pomocniki odpowiedzi interaktywnych | Normalizacja/redukcja ładunku odpowiedzi interaktywnych | + | `plugin-sdk/channel-config-primitives` | Prymitywy konfiguracji kanału | Wąskie prymitywy schematu konfiguracji kanału | + | `plugin-sdk/channel-config-writes` | Pomocniki zapisów konfiguracji kanału | Pomocniki autoryzacji zapisu konfiguracji kanału | + | `plugin-sdk/channel-plugin-common` | Współdzielone preludium kanału | Eksporty współdzielonego preludium wtyczki kanału | + | `plugin-sdk/channel-status` | Pomocniki statusu kanału | Współdzielone pomocniki migawek/podsumowań statusu kanału | + | `plugin-sdk/allowlist-config-edit` | Pomocniki konfiguracji listy dozwolonych | Pomocniki edycji/odczytu konfiguracji listy dozwolonych | + | `plugin-sdk/group-access` | Pomocniki dostępu grupowego | Współdzielone pomocniki decyzji o dostępie grupowym | + | `plugin-sdk/direct-dm` | Pomocniki bezpośrednich DM | Współdzielone pomocniki uwierzytelniania/guardów bezpośrednich DM | + | `plugin-sdk/extension-shared` | Współdzielone pomocniki rozszerzeń | Prymitywy pomocników pasywnego kanału/statusu i proxy otoczenia | + | `plugin-sdk/webhook-targets` | Pomocniki celów webhooków | Rejestr celów webhooków i pomocniki instalacji tras | + | `plugin-sdk/webhook-path` | Pomocniki ścieżek webhooków | Pomocniki normalizacji ścieżek webhooków | + | `plugin-sdk/web-media` | Współdzielone pomocniki mediów webowych | Pomocniki ładowania mediów zdalnych/lokalnych | + | `plugin-sdk/zod` | Reeksport zod | Reeksport `zod` dla odbiorców Plugin SDK | + | `plugin-sdk/memory-core` | Pomocniki dołączonego memory-core | Powierzchnia pomocników menedżera pamięci/konfiguracji/plików/CLI | + | `plugin-sdk/memory-core-engine-runtime` | Fasada runtime silnika pamięci | Fasada runtime indeksowania/wyszukiwania pamięci | + | `plugin-sdk/memory-core-host-engine-foundation` | Hostowy silnik podstawowy pamięci | Eksporty hostowego silnika podstawowego pamięci | + | `plugin-sdk/memory-core-host-engine-embeddings` | Hostowy silnik embeddingów pamięci | Eksporty hostowego silnika embeddingów pamięci | + | `plugin-sdk/memory-core-host-engine-qmd` | Hostowy silnik QMD pamięci | Eksporty hostowego silnika QMD pamięci | + | `plugin-sdk/memory-core-host-engine-storage` | Hostowy silnik przechowywania pamięci | Eksporty hostowego silnika przechowywania pamięci | + | `plugin-sdk/memory-core-host-multimodal` | Pomocniki multimodalne hosta pamięci | Pomocniki multimodalne hosta pamięci | + | `plugin-sdk/memory-core-host-query` | Pomocniki zapytań hosta pamięci | Pomocniki zapytań hosta pamięci | + | `plugin-sdk/memory-core-host-secret` | Pomocniki sekretów hosta pamięci | Pomocniki sekretów hosta pamięci | + | `plugin-sdk/memory-core-host-events` | Pomocniki dziennika zdarzeń hosta pamięci | Pomocniki dziennika zdarzeń hosta pamięci | + | `plugin-sdk/memory-core-host-status` | Pomocniki statusu hosta pamięci | Pomocniki statusu hosta pamięci | + | `plugin-sdk/memory-core-host-runtime-cli` | Runtime CLI hosta pamięci | Pomocniki runtime CLI hosta pamięci | + | `plugin-sdk/memory-core-host-runtime-core` | Główny runtime hosta pamięci | Pomocniki głównego runtime hosta pamięci | + | `plugin-sdk/memory-core-host-runtime-files` | Pomocniki plików/runtime hosta pamięci | Pomocniki plików/runtime hosta pamięci | + | `plugin-sdk/memory-host-core` | Alias głównego runtime hosta pamięci | Neutralny względem dostawcy alias pomocników głównego runtime hosta pamięci | + | `plugin-sdk/memory-host-events` | Alias dziennika zdarzeń hosta pamięci | Neutralny względem dostawcy alias pomocników dziennika zdarzeń hosta pamięci | + | `plugin-sdk/memory-host-files` | Alias plików/runtime hosta pamięci | Neutralny względem dostawcy alias pomocników plików/runtime hosta pamięci | + | `plugin-sdk/memory-host-markdown` | Pomocniki zarządzanego markdownu | Współdzielone pomocniki zarządzanego markdownu dla wtyczek powiązanych z pamięcią | | `plugin-sdk/memory-host-search` | Fasada wyszukiwania aktywnej pamięci | Leniwa fasada runtime menedżera wyszukiwania aktywnej pamięci | - | `plugin-sdk/memory-host-status` | Alias statusu hosta pamięci | Neutralny wobec dostawcy alias helperów statusu hosta pamięci | - | `plugin-sdk/memory-lancedb` | Helpery wbudowanego memory-lancedb | Powierzchnia helperów memory-lancedb | - | `plugin-sdk/testing` | Narzędzia testowe | Helpery testowe i mocki | + | `plugin-sdk/memory-host-status` | Alias statusu hosta pamięci | Neutralny względem dostawcy alias pomocników statusu hosta pamięci | + | `plugin-sdk/memory-lancedb` | Pomocniki dołączonego memory-lancedb | Powierzchnia pomocników memory-lancedb | + | `plugin-sdk/testing` | Narzędzia testowe | Pomocniki testowe i mocki | -Ta tabela celowo zawiera typowy podzbiór migracyjny, a nie pełną -powierzchnię SDK. Pełna lista ponad 200 punktów wejścia znajduje się w +Ta tabela celowo obejmuje typowy podzbiór do migracji, a nie pełną powierzchnię +SDK. Pełna lista ponad 200 punktów wejścia znajduje się w `scripts/lib/plugin-sdk-entrypoints.json`. -Ta lista nadal zawiera niektóre powierzchnie helperów wbudowanych pluginów, takie jak +Ta lista nadal zawiera niektóre pomocnicze punkty integracji dołączonych wtyczek, takie jak `plugin-sdk/feishu`, `plugin-sdk/feishu-setup`, `plugin-sdk/zalo`, -`plugin-sdk/zalo-setup` i `plugin-sdk/matrix*`. Pozostają one eksportowane na potrzeby -utrzymania i zgodności wbudowanych pluginów, ale celowo -pominięto je w typowej tabeli migracyjnej i nie są zalecanym celem dla -nowego kodu pluginów. +`plugin-sdk/zalo-setup` oraz `plugin-sdk/matrix*`. Nadal są one eksportowane na potrzeby +utrzymania dołączonych wtyczek i zgodności, ale celowo +pominięto je w tabeli typowej migracji i nie są zalecanym celem dla +nowego kodu wtyczek. -Ta sama zasada dotyczy innych rodzin helperów wbudowanych pluginów, takich jak: +Ta sama zasada dotyczy innych rodzin dołączonych pomocników, takich jak: -- helpery obsługi przeglądarki: `plugin-sdk/browser-cdp`, `plugin-sdk/browser-config-runtime`, `plugin-sdk/browser-config-support`, `plugin-sdk/browser-control-auth`, `plugin-sdk/browser-node-runtime`, `plugin-sdk/browser-profiles`, `plugin-sdk/browser-security-runtime`, `plugin-sdk/browser-setup-tools`, `plugin-sdk/browser-support` +- pomocniki obsługi przeglądarki: `plugin-sdk/browser-cdp`, `plugin-sdk/browser-config-runtime`, `plugin-sdk/browser-config-support`, `plugin-sdk/browser-control-auth`, `plugin-sdk/browser-node-runtime`, `plugin-sdk/browser-profiles`, `plugin-sdk/browser-security-runtime`, `plugin-sdk/browser-setup-tools`, `plugin-sdk/browser-support` - Matrix: `plugin-sdk/matrix*` - LINE: `plugin-sdk/line*` - IRC: `plugin-sdk/irc*` -- powierzchnie wbudowanych helperów/pluginów, takie jak `plugin-sdk/googlechat`, +- powierzchnie dołączonych pomocników/wtyczek, takie jak `plugin-sdk/googlechat`, `plugin-sdk/zalouser`, `plugin-sdk/bluebubbles*`, `plugin-sdk/mattermost*`, `plugin-sdk/msteams`, `plugin-sdk/nextcloud-talk`, `plugin-sdk/nostr`, `plugin-sdk/tlon`, `plugin-sdk/twitch`, `plugin-sdk/github-copilot-login`, `plugin-sdk/github-copilot-token`, `plugin-sdk/diagnostics-otel`, `plugin-sdk/diffs`, `plugin-sdk/llm-task`, - `plugin-sdk/thread-ownership` i `plugin-sdk/voice-call` + `plugin-sdk/thread-ownership` oraz `plugin-sdk/voice-call` `plugin-sdk/github-copilot-token` obecnie udostępnia wąską -powierzchnię helperów tokenów `DEFAULT_COPILOT_API_BASE_URL`, -`deriveCopilotApiBaseUrlFromToken` i `resolveCopilotApiToken`. +powierzchnię pomocników tokenów `DEFAULT_COPILOT_API_BASE_URL`, +`deriveCopilotApiBaseUrlFromToken` oraz `resolveCopilotApiToken`. Używaj najwęższego importu, który pasuje do zadania. Jeśli nie możesz znaleźć eksportu, -sprawdź źródło w `src/plugin-sdk/` lub zapytaj na Discord. +sprawdź źródło w `src/plugin-sdk/` albo zapytaj na Discord. ## Harmonogram usunięcia -| Kiedy | Co się dzieje | -| ---------------------- | ---------------------------------------------------------------------- | -| **Teraz** | Przestarzałe powierzchnie emitują ostrzeżenia w runtime | -| **Następna główna wersja** | Przestarzałe powierzchnie zostaną usunięte; pluginy nadal z nich korzystające przestaną działać | +| Kiedy | Co się stanie | +| ---------------------- | ----------------------------------------------------------------------- | +| **Teraz** | Przestarzałe powierzchnie emitują ostrzeżenia runtime | +| **Następne główne wydanie** | Przestarzałe powierzchnie zostaną usunięte; wtyczki, które nadal z nich korzystają, przestaną działać | -Wszystkie podstawowe pluginy zostały już zmigrowane. Zewnętrzne pluginy powinny -przeprowadzić migrację przed następną główną wersją. +Wszystkie główne wtyczki zostały już zmigrowane. Zewnętrzne wtyczki powinny przeprowadzić +migrację przed następnym głównym wydaniem. ## Tymczasowe wyciszanie ostrzeżeń @@ -401,13 +397,13 @@ OPENCLAW_SUPPRESS_PLUGIN_SDK_COMPAT_WARNING=1 openclaw gateway run OPENCLAW_SUPPRESS_EXTENSION_API_WARNING=1 openclaw gateway run ``` -To tymczasowa furtka awaryjna, a nie trwałe rozwiązanie. +To tymczasowe wyjście awaryjne, a nie trwałe rozwiązanie. ## Powiązane -- [Pierwsze kroki](/pl/plugins/building-plugins) — zbuduj swój pierwszy plugin +- [Pierwsze kroki](/pl/plugins/building-plugins) — zbuduj swoją pierwszą wtyczkę - [Przegląd SDK](/pl/plugins/sdk-overview) — pełne odniesienie do importów podścieżek -- [Pluginy kanałów](/pl/plugins/sdk-channel-plugins) — tworzenie pluginów kanałów -- [Pluginy providerów](/pl/plugins/sdk-provider-plugins) — tworzenie pluginów providerów -- [Wnętrze pluginów](/pl/plugins/architecture) — szczegółowe omówienie architektury -- [Manifest pluginu](/pl/plugins/manifest) — odniesienie do schematu manifestu +- [Wtyczki kanałów](/pl/plugins/sdk-channel-plugins) — tworzenie wtyczek kanałów +- [Wtyczki dostawców](/pl/plugins/sdk-provider-plugins) — tworzenie wtyczek dostawców +- [Wewnętrzne elementy wtyczek](/pl/plugins/architecture) — szczegółowe omówienie architektury +- [Manifest wtyczki](/pl/plugins/manifest) — odniesienie do schematu manifestu diff --git a/docs/pl/plugins/sdk-overview.md b/docs/pl/plugins/sdk-overview.md index 6d4e39250..1403e66b0 100644 --- a/docs/pl/plugins/sdk-overview.md +++ b/docs/pl/plugins/sdk-overview.md @@ -1,16 +1,16 @@ --- read_when: - Musisz wiedzieć, z której ścieżki podrzędnej SDK importować - - Chcesz uzyskać dokumentację referencyjną wszystkich metod rejestracji w `OpenClawPluginApi` + - Chcesz mieć dokumentację wszystkich metod rejestracji w OpenClawPluginApi - Szukasz konkretnego eksportu SDK sidebarTitle: SDK Overview -summary: Mapa importów, dokumentacja referencyjna API rejestracji i architektura SDK +summary: Mapa importów, dokumentacja API rejestracji i architektura SDK title: Przegląd Plugin SDK x-i18n: - generated_at: "2026-04-08T09:45:54Z" + generated_at: "2026-04-09T01:30:58Z" model: gpt-5.4 provider: openai - source_hash: 6e7b420eb0f3faa8916357d52df949f6c9a46f1c843a1e6a0c0b8bb26db6cbff + source_hash: bf205af060971931df97dca4af5110ce173d2b7c12f56ad7c62d664a402f2381 source_path: plugins/sdk-overview.md workflow: 15 --- @@ -22,7 +22,7 @@ dokumentacją referencyjną dla **tego, co importować** i **co można rejestrow **Szukasz przewodnika krok po kroku?** - - Pierwszy plugin? Zacznij od [Wprowadzenia](/pl/plugins/building-plugins) + - Pierwszy plugin? Zacznij od [Pierwsze kroki](/pl/plugins/building-plugins) - Plugin kanału? Zobacz [Pluginy kanałów](/pl/plugins/sdk-channel-plugins) - Plugin dostawcy? Zobacz [Pluginy dostawców](/pl/plugins/sdk-provider-plugins) @@ -36,269 +36,268 @@ import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry"; import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core"; ``` -Każda ścieżka podrzędna to mały, samodzielny moduł. Dzięki temu uruchamianie -jest szybkie i można uniknąć problemów z cyklicznymi zależnościami. W przypadku -pomocników wejścia/budowania specyficznych dla kanałów preferuj -`openclaw/plugin-sdk/channel-core`; zachowaj `openclaw/plugin-sdk/core` dla -szerszej powierzchni parasolowej i współdzielonych helperów, takich jak +Każda ścieżka podrzędna jest małym, samowystarczalnym modułem. Dzięki temu uruchamianie pozostaje szybkie i +zapobiega to problemom z zależnościami cyklicznymi. W przypadku helperów wejścia/budowania specyficznych dla kanałów +preferuj `openclaw/plugin-sdk/channel-core`; `openclaw/plugin-sdk/core` zachowaj dla +szerszej powierzchni zbiorczej i współdzielonych helperów, takich jak `buildChannelConfigSchema`. Nie dodawaj ani nie polegaj na wygodnych warstwach nazwanych od dostawców, takich jak `openclaw/plugin-sdk/slack`, `openclaw/plugin-sdk/discord`, `openclaw/plugin-sdk/signal`, `openclaw/plugin-sdk/whatsapp` ani -warstwach helperów markowanych kanałem. Zestawione pluginy powinny składać -ogólne ścieżki podrzędne SDK we własnych barrelach `api.ts` lub `runtime-api.ts`, a rdzeń -powinien albo używać tych lokalnych barrelów pluginu, albo dodać wąski ogólny -kontrakt SDK, gdy potrzeba jest rzeczywiście międzykanałowa. +helperowych warstwach oznaczonych marką kanału. Bundlowane pluginy powinny składać ogólne +ścieżki podrzędne SDK we własnych barrelach `api.ts` lub `runtime-api.ts`, a rdzeń +powinien albo używać tych lokalnych barrelów pluginu, albo dodać wąski ogólny kontrakt SDK, +gdy potrzeba rzeczywiście dotyczy wielu kanałów. -Wygenerowana mapa eksportów nadal zawiera mały zestaw warstw helperów -zestawionych pluginów, takich jak `plugin-sdk/feishu`, `plugin-sdk/feishu-setup`, +Wygenerowana mapa eksportów nadal zawiera mały zestaw helperowych warstw bundlowanych pluginów, +takich jak `plugin-sdk/feishu`, `plugin-sdk/feishu-setup`, `plugin-sdk/zalo`, `plugin-sdk/zalo-setup` i `plugin-sdk/matrix*`. Te -ścieżki podrzędne istnieją wyłącznie na potrzeby utrzymania i zgodności zestawionych pluginów; -celowo pominięto je w typowej tabeli poniżej i nie są zalecaną -ścieżką importu dla nowych pluginów zewnętrznych. +ścieżki podrzędne istnieją wyłącznie dla utrzymania i zgodności bundlowanych pluginów; celowo pominięto je +w standardowej tabeli poniżej i nie są zalecaną ścieżką importu dla nowych pluginów zewnętrznych. -## Dokumentacja referencyjna ścieżek podrzędnych +## Dokumentacja ścieżek podrzędnych Najczęściej używane ścieżki podrzędne, pogrupowane według przeznaczenia. Wygenerowana pełna lista ponad 200 ścieżek podrzędnych znajduje się w `scripts/lib/plugin-sdk-entrypoints.json`. -Zarezerwowane ścieżki podrzędne helperów zestawionych pluginów nadal pojawiają się na tej wygenerowanej liście. -Traktuj je jako szczegół implementacyjny/powierzchnie zgodności, chyba że dana strona dokumentacji +Zarezerwowane helperowe ścieżki podrzędne bundlowanych pluginów nadal pojawiają się na tej wygenerowanej liście. +Traktuj je jako szczegóły implementacyjne/powierzchnie zgodności, chyba że strona dokumentacji wyraźnie promuje którąś z nich jako publiczną. ### Wejście pluginu -| Ścieżka podrzędna | Kluczowe eksporty | -| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | -| `plugin-sdk/plugin-entry` | `definePluginEntry` | +| Subpath | Key exports | +| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | +| `plugin-sdk/plugin-entry` | `definePluginEntry` | | `plugin-sdk/core` | `defineChannelPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase`, `defineSetupPluginEntry`, `buildChannelConfigSchema` | -| `plugin-sdk/config-schema` | `OpenClawSchema` | -| `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` | +| `plugin-sdk/config-schema` | `OpenClawSchema` | +| `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` | - | Ścieżka podrzędna | Kluczowe eksporty | + | Subpath | Key exports | | --- | --- | | `plugin-sdk/channel-core` | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` | | `plugin-sdk/config-schema` | Eksport głównego schematu Zod `openclaw.json` (`OpenClawSchema`) | - | `plugin-sdk/channel-setup` | `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, `createOptionalChannelSetupWizard`, plus `DEFAULT_ACCOUNT_ID`, `createTopLevelChannelDmPolicy`, `setSetupChannelEnabled`, `splitSetupEntries` | - | `plugin-sdk/setup` | Współdzielone helpery kreatora konfiguracji, prompty allowlist i kreatory statusu konfiguracji | + | `plugin-sdk/channel-setup` | `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, `createOptionalChannelSetupWizard`, a także `DEFAULT_ACCOUNT_ID`, `createTopLevelChannelDmPolicy`, `setSetupChannelEnabled`, `splitSetupEntries` | + | `plugin-sdk/setup` | Współdzielone helpery kreatora konfiguracji, prompty allowlist i konstruktory statusu konfiguracji | | `plugin-sdk/setup-runtime` | `createPatchedAccountSetupAdapter`, `createEnvPatchedAccountSetupAdapter`, `createSetupInputPresenceValidator`, `noteChannelLookupFailure`, `noteChannelLookupSummary`, `promptResolvedAllowFrom`, `splitSetupEntries`, `createAllowlistSetupWizardProxy`, `createDelegatedSetupWizardProxy` | | `plugin-sdk/setup-adapter-runtime` | `createEnvPatchedAccountSetupAdapter` | | `plugin-sdk/setup-tools` | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` | - | `plugin-sdk/account-core` | Helpery konfiguracji/wielu kont/bramki akcji oraz helpery awaryjnego wyboru konta domyślnego | + | `plugin-sdk/account-core` | Helpery konfiguracji/wymuszania działań dla wielu kont oraz helpery zapasowego użycia konta domyślnego | | `plugin-sdk/account-id` | `DEFAULT_ACCOUNT_ID`, helpery normalizacji identyfikatora konta | - | `plugin-sdk/account-resolution` | Helpery wyszukiwania kont i awaryjnego wyboru domyślnego | - | `plugin-sdk/account-helpers` | Wąskie helpery list kont/akcji na kontach | + | `plugin-sdk/account-resolution` | Helpery wyszukiwania konta i zapasowego użycia wartości domyślnej | + | `plugin-sdk/account-helpers` | Wąskie helpery list działań/kont | | `plugin-sdk/channel-pairing` | `createChannelPairingController` | | `plugin-sdk/channel-reply-pipeline` | `createChannelReplyPipeline` | | `plugin-sdk/channel-config-helpers` | `createHybridChannelConfigAdapter` | | `plugin-sdk/channel-config-schema` | Typy schematu konfiguracji kanału | - | `plugin-sdk/telegram-command-config` | Helpery normalizacji/walidacji niestandardowych poleceń Telegram z awaryjną obsługą kontraktu zestawionego | + | `plugin-sdk/telegram-command-config` | Helpery normalizacji/walidacji niestandardowych poleceń Telegram z zapasową obsługą kontraktu bundlowanego | | `plugin-sdk/channel-policy` | `resolveChannelGroupRequireMention` | | `plugin-sdk/channel-lifecycle` | `createAccountStatusSink` | - | `plugin-sdk/inbound-envelope` | Współdzielone helpery budowania tras przychodzących i kopert | - | `plugin-sdk/inbound-reply-dispatch` | Współdzielone helpery zapisu i dyspozycji wiadomości przychodzących | + | `plugin-sdk/inbound-envelope` | Współdzielone helpery tras przychodzących i konstruktora kopert | + | `plugin-sdk/inbound-reply-dispatch` | Współdzielone helpery zapisu i wysyłania odpowiedzi przychodzących | | `plugin-sdk/messaging-targets` | Helpery parsowania/dopasowywania celów | | `plugin-sdk/outbound-media` | Współdzielone helpery ładowania mediów wychodzących | - | `plugin-sdk/outbound-runtime` | Helpery tożsamości wychodzącej/delegowania wysyłki | - | `plugin-sdk/thread-bindings-runtime` | Helpery cyklu życia i adapterów powiązań wątków | - | `plugin-sdk/agent-media-payload` | Starszy kreator payloadów mediów agenta | - | `plugin-sdk/conversation-runtime` | Powiązania konwersacji/wątków, parowanie i helpery skonfigurowanych powiązań | - | `plugin-sdk/runtime-config-snapshot` | Helper migawki konfiguracji środowiska wykonawczego | - | `plugin-sdk/runtime-group-policy` | Helpery rozstrzygania zasad grupowych środowiska wykonawczego | + | `plugin-sdk/outbound-runtime` | Helpery tożsamości wychodzącej i delegowania wysyłki | + | `plugin-sdk/thread-bindings-runtime` | Helpery cyklu życia i adapterów wiązań wątków | + | `plugin-sdk/agent-media-payload` | Starszy konstruktor ładunku multimediów agenta | + | `plugin-sdk/conversation-runtime` | Helpery wiązania rozmów/wątków, parowania i skonfigurowanych wiązań | + | `plugin-sdk/runtime-config-snapshot` | Helper migawki konfiguracji runtime | + | `plugin-sdk/runtime-group-policy` | Helpery rozstrzygania polityki grup runtime | | `plugin-sdk/channel-status` | Współdzielone helpery migawek/podsumowań statusu kanału | | `plugin-sdk/channel-config-primitives` | Wąskie prymitywy schematu konfiguracji kanału | | `plugin-sdk/channel-config-writes` | Helpery autoryzacji zapisu konfiguracji kanału | - | `plugin-sdk/channel-plugin-common` | Współdzielone eksporty preludium pluginów kanałów | + | `plugin-sdk/channel-plugin-common` | Współdzielone eksporty preludium pluginu kanału | | `plugin-sdk/allowlist-config-edit` | Helpery odczytu/edycji konfiguracji allowlist | - | `plugin-sdk/group-access` | Współdzielone helpery decyzji o dostępie grupowym | - | `plugin-sdk/direct-dm` | Współdzielone helpery uwierzytelniania/ochrony bezpośrednich DM | - | `plugin-sdk/interactive-runtime` | Helpery normalizacji/redukcji payloadów odpowiedzi interaktywnych | - | `plugin-sdk/channel-inbound` | Pomocniki debounce dla ruchu przychodzącego, dopasowywania wzmianek, zasad wzmianek i helpery kopert | + | `plugin-sdk/group-access` | Współdzielone helpery decyzji dostępu do grup | + | `plugin-sdk/direct-dm` | Współdzielone helpery auth i ochrony direct-DM | + | `plugin-sdk/interactive-runtime` | Helpery normalizacji/redukcji ładunków odpowiedzi interaktywnych | + | `plugin-sdk/channel-inbound` | Helpery debounce wiadomości przychodzących, dopasowania mention, polityki mention i kopert | | `plugin-sdk/channel-send-result` | Typy wyników odpowiedzi | | `plugin-sdk/channel-actions` | `createMessageToolButtonsSchema`, `createMessageToolCardSchema` | | `plugin-sdk/channel-targets` | Helpery parsowania/dopasowywania celów | | `plugin-sdk/channel-contract` | Typy kontraktu kanału | - | `plugin-sdk/channel-feedback` | Łączenie informacji zwrotnych/reakcji | - | `plugin-sdk/channel-secret-runtime` | Wąskie helpery kontraktu sekretów, takie jak `collectSimpleChannelFieldAssignments`, `getChannelSurface`, `pushAssignment` oraz typy celów sekretów | + | `plugin-sdk/channel-feedback` | Okablowanie feedbacku/reakcji | + | `plugin-sdk/channel-secret-runtime` | Wąskie helpery kontraktu sekretów, takie jak `collectSimpleChannelFieldAssignments`, `getChannelSurface`, `pushAssignment`, oraz typy celów sekretów | - | Ścieżka podrzędna | Kluczowe eksporty | + | Subpath | Key exports | | --- | --- | | `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` | - | `plugin-sdk/provider-setup` | Kuratorowane helpery konfiguracji lokalnych/samohostowanych dostawców | - | `plugin-sdk/self-hosted-provider-setup` | Skoncentrowane helpery konfiguracji samohostowanych dostawców zgodnych z OpenAI | - | `plugin-sdk/cli-backend` | Domyślne ustawienia backendu CLI + stałe watchdog | - | `plugin-sdk/provider-auth-runtime` | Helpery rozstrzygania kluczy API w czasie działania dla pluginów dostawców | + | `plugin-sdk/provider-setup` | Wyselekcjonowane helpery konfiguracji lokalnych/samohostowanych dostawców | + | `plugin-sdk/self-hosted-provider-setup` | Ukierunkowane helpery konfiguracji samohostowanego dostawcy zgodnego z OpenAI | + | `plugin-sdk/cli-backend` | Domyślne wartości backendu CLI i stałe watchdog | + | `plugin-sdk/provider-auth-runtime` | Helpery runtime do rozstrzygania kluczy API dla pluginów dostawców | | `plugin-sdk/provider-auth-api-key` | Helpery onboardingu/zapisu profilu klucza API, takie jak `upsertApiKeyProfile` | - | `plugin-sdk/provider-auth-result` | Standardowy kreator wyniku uwierzytelniania OAuth | + | `plugin-sdk/provider-auth-result` | Standardowy konstruktor wyniku auth OAuth | | `plugin-sdk/provider-auth-login` | Współdzielone interaktywne helpery logowania dla pluginów dostawców | - | `plugin-sdk/provider-env-vars` | Helpery wyszukiwania zmiennych środowiskowych uwierzytelniania dostawców | + | `plugin-sdk/provider-env-vars` | Helpery wyszukiwania zmiennych env auth dostawcy | | `plugin-sdk/provider-auth` | `createProviderApiKeyAuthMethod`, `ensureApiKeyFromOptionEnvOrPrompt`, `upsertAuthProfile`, `upsertApiKeyProfile`, `writeOAuthCredentials` | - | `plugin-sdk/provider-model-shared` | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`, współdzielone kreatory zasad powtórzeń, helpery punktów końcowych dostawców oraz helpery normalizacji identyfikatorów modeli, takie jak `normalizeNativeXaiModelId` | + | `plugin-sdk/provider-model-shared` | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`, współdzielone konstruktory polityki replay, helpery endpointów dostawców oraz helpery normalizacji identyfikatorów modeli, takie jak `normalizeNativeXaiModelId` | | `plugin-sdk/provider-catalog-shared` | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat` | - | `plugin-sdk/provider-http` | Ogólne helpery HTTP/możliwości punktów końcowych dostawców | + | `plugin-sdk/provider-http` | Ogólne helpery możliwości HTTP/endpointów dostawców | | `plugin-sdk/provider-web-fetch-contract` | Wąskie helpery kontraktu konfiguracji/wyboru web-fetch, takie jak `enablePluginInConfig` i `WebFetchProviderPlugin` | - | `plugin-sdk/provider-web-fetch` | Helpery rejestracji/pamięci podręcznej dostawców web-fetch | - | `plugin-sdk/provider-web-search-config-contract` | Wąskie helpery konfiguracji/danych uwierzytelniających web-search dla dostawców, którzy nie potrzebują mechanizmu włączania pluginu | - | `plugin-sdk/provider-web-search-contract` | Wąskie helpery kontraktu konfiguracji/danych uwierzytelniających web-search, takie jak `createWebSearchProviderContractFields`, `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig` oraz zakresowane settery/gettery danych uwierzytelniających | - | `plugin-sdk/provider-web-search` | Helpery rejestracji/pamięci podręcznej/środowiska wykonawczego dostawców web-search | - | `plugin-sdk/provider-tools` | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, czyszczenie schematów Gemini + diagnostyka oraz helpery zgodności xAI, takie jak `resolveXaiModelCompatPatch` / `applyXaiModelCompat` | + | `plugin-sdk/provider-web-fetch` | Helpery rejestracji/cache dostawców web-fetch | + | `plugin-sdk/provider-web-search-config-contract` | Wąskie helpery konfiguracji/poświadczeń web search dla dostawców, którzy nie potrzebują okablowania włączania pluginu | + | `plugin-sdk/provider-web-search-contract` | Wąskie helpery kontraktu konfiguracji/poświadczeń web search, takie jak `createWebSearchProviderContractFields`, `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig` oraz zakresowane settery/gettery poświadczeń | + | `plugin-sdk/provider-web-search` | Helpery rejestracji/cache/runtime dostawców web search | + | `plugin-sdk/provider-tools` | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, czyszczenie schematu Gemini + diagnostyka oraz helpery zgodności xAI, takie jak `resolveXaiModelCompatPatch` / `applyXaiModelCompat` | | `plugin-sdk/provider-usage` | `fetchClaudeUsage` i podobne | - | `plugin-sdk/provider-stream` | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`, typy opakowań strumieni oraz współdzielone helpery opakowań Anthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot | + | `plugin-sdk/provider-stream` | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`, typy wrapperów strumieni oraz współdzielone helpery wrapperów Anthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot | | `plugin-sdk/provider-onboard` | Helpery łatania konfiguracji onboardingu | - | `plugin-sdk/global-singleton` | Helpery singletonów/map/pamięci podręcznej lokalnych dla procesu | + | `plugin-sdk/global-singleton` | Helpery singletonów/map/cache lokalnych dla procesu | - - | Ścieżka podrzędna | Kluczowe eksporty | + + | Subpath | Key exports | | --- | --- | | `plugin-sdk/command-auth` | `resolveControlCommandGate`, helpery rejestru poleceń, helpery autoryzacji nadawcy | - | `plugin-sdk/approval-auth-runtime` | Helpery rozstrzygania zatwierdzających i uwierzytelniania akcji w tym samym czacie | - | `plugin-sdk/approval-client-runtime` | Helpery profili/filtrów zatwierdzania dla natywnego wykonania | - | `plugin-sdk/approval-delivery-runtime` | Adaptery możliwości/dostarczania natywnego zatwierdzania | - | `plugin-sdk/approval-gateway-runtime` | Współdzielony helper rozstrzygania bramy zatwierdzania | - | `plugin-sdk/approval-handler-adapter-runtime` | Lekkie helpery ładowania adapterów natywnego zatwierdzania dla gorących punktów wejścia kanałów | - | `plugin-sdk/approval-handler-runtime` | Szersze helpery środowiska wykonawczego obsługi zatwierdzeń; gdy to wystarcza, preferuj węższe warstwy adapter/gateway | - | `plugin-sdk/approval-native-runtime` | Helpery celów natywnego zatwierdzania + powiązań kont | - | `plugin-sdk/approval-reply-runtime` | Helpery payloadów odpowiedzi zatwierdzeń exec/pluginów | - | `plugin-sdk/command-auth-native` | Natywne helpery uwierzytelniania poleceń + helpery celów sesji natywnych | + | `plugin-sdk/command-status` | Konstruktory wiadomości poleceń/pomocy, takie jak `buildCommandsMessagePaginated` i `buildHelpMessage` | + | `plugin-sdk/approval-auth-runtime` | Helpery rozstrzygania approvera i auth działań w tym samym czacie | + | `plugin-sdk/approval-client-runtime` | Natywne helpery profili/filtrów zatwierdzania exec | + | `plugin-sdk/approval-delivery-runtime` | Natywne adaptery możliwości/dostarczania zatwierdzeń | + | `plugin-sdk/approval-gateway-runtime` | Współdzielony helper rozstrzygania gateway zatwierdzeń | + | `plugin-sdk/approval-handler-adapter-runtime` | Lekkie helpery ładowania natywnych adapterów zatwierdzeń dla gorących punktów wejścia kanałów | + | `plugin-sdk/approval-handler-runtime` | Szersze helpery runtime obsługi zatwierdzeń; gdy wystarczą, preferuj węższe warstwy adapter/gateway | + | `plugin-sdk/approval-native-runtime` | Natywne helpery celów zatwierdzeń i wiązania kont | + | `plugin-sdk/approval-reply-runtime` | Helpery ładunku odpowiedzi zatwierdzeń exec/pluginów | + | `plugin-sdk/command-auth-native` | Natywne helpery auth poleceń i natywnych celów sesji | | `plugin-sdk/command-detection` | Współdzielone helpery wykrywania poleceń | - | `plugin-sdk/command-surface` | Normalizacja treści poleceń i helpery powierzchni poleceń | + | `plugin-sdk/command-surface` | Helpery normalizacji treści poleceń i powierzchni poleceń | | `plugin-sdk/allow-from` | `formatAllowFromLowercase` | - | `plugin-sdk/channel-secret-runtime` | Wąskie helpery zbierania kontraktu sekretów dla powierzchni sekretów kanału/pluginu | - | `plugin-sdk/secret-ref-runtime` | Wąskie helpery `coerceSecretRef` i typowania SecretRef do parsowania kontraktów sekretów/konfiguracji | - | `plugin-sdk/security-runtime` | Współdzielone helpery zaufania, ograniczania DM, treści zewnętrznych i zbierania sekretów | - | `plugin-sdk/ssrf-policy` | Helpery allowlist hostów i zasad SSRF dla sieci prywatnych | - | `plugin-sdk/ssrf-runtime` | Helpery pinned-dispatcher, fetch chronionego przez SSRF i zasad SSRF | + | `plugin-sdk/channel-secret-runtime` | Wąskie helpery zbierania kontraktów sekretów dla powierzchni sekretów kanałów/pluginów | + | `plugin-sdk/secret-ref-runtime` | Wąskie helpery `coerceSecretRef` i typowania SecretRef dla parsowania kontraktów sekretów/konfiguracji | + | `plugin-sdk/security-runtime` | Współdzielone helpery zaufania, bramkowania DM, treści zewnętrznych i zbierania sekretów | + | `plugin-sdk/ssrf-policy` | Helpery allowlist hostów i polityki SSRF dla sieci prywatnych | + | `plugin-sdk/ssrf-runtime` | Helpery pinned-dispatcher, fetch chronionego przez SSRF i polityki SSRF | | `plugin-sdk/secret-input` | Helpery parsowania wejść sekretów | | `plugin-sdk/webhook-ingress` | Helpery żądań/celów webhooków | - | `plugin-sdk/webhook-request-guards` | Helpery rozmiaru treści/timeoutów żądań | + | `plugin-sdk/webhook-request-guards` | Helpery rozmiaru ciała żądania/timeoutu | - - | Ścieżka podrzędna | Kluczowe eksporty | + + | Subpath | Key exports | | --- | --- | - | `plugin-sdk/runtime` | Szerokie helpery środowiska wykonawczego/logowania/kopii zapasowych/instalacji pluginów | - | `plugin-sdk/runtime-env` | Wąskie helpery środowiska wykonawczego env, loggera, timeoutów, ponowień i backoff | - | `plugin-sdk/channel-runtime-context` | Ogólne helpery rejestracji i wyszukiwania kontekstu środowiska wykonawczego kanału | + | `plugin-sdk/runtime` | Szerokie helpery runtime/logowania/kopii zapasowych/instalacji pluginów | + | `plugin-sdk/runtime-env` | Wąskie helpery env runtime, loggera, timeoutu, retry i backoff | + | `plugin-sdk/channel-runtime-context` | Ogólne helpery rejestracji i wyszukiwania kontekstu runtime kanałów | | `plugin-sdk/runtime-store` | `createPluginRuntimeStore` | - | `plugin-sdk/plugin-runtime` | Współdzielone helpery poleceń/hooków/HTTP/interaktywne pluginu | + | `plugin-sdk/plugin-runtime` | Współdzielone helpery poleceń/hooków/http/interaktywności pluginów | | `plugin-sdk/hook-runtime` | Współdzielone helpery potoku webhooków/wewnętrznych hooków | - | `plugin-sdk/lazy-runtime` | Helpery opóźnionego importu/powiązań środowiska wykonawczego, takie jak `createLazyRuntimeModule`, `createLazyRuntimeMethod` i `createLazyRuntimeSurface` | + | `plugin-sdk/lazy-runtime` | Helpery leniwego importu/powiązań runtime, takie jak `createLazyRuntimeModule`, `createLazyRuntimeMethod` i `createLazyRuntimeSurface` | | `plugin-sdk/process-runtime` | Helpery wykonywania procesów | | `plugin-sdk/cli-runtime` | Helpery formatowania CLI, oczekiwania i wersji | - | `plugin-sdk/gateway-runtime` | Helpery klienta gateway i łatania statusu kanału | + | `plugin-sdk/gateway-runtime` | Helpery klienta Gateway i łatania statusu kanałów | | `plugin-sdk/config-runtime` | Helpery ładowania/zapisu konfiguracji | - | `plugin-sdk/telegram-command-config` | Normalizacja nazw/opisów poleceń Telegram oraz sprawdzanie duplikatów/konfliktów, nawet gdy powierzchnia kontraktu zestawionego Telegram jest niedostępna | - | `plugin-sdk/approval-runtime` | Helpery zatwierdzeń exec/pluginów, kreatory możliwości zatwierdzania, helpery auth/profili, helpery natywnego routingu/środowiska wykonawczego | - | `plugin-sdk/reply-runtime` | Współdzielone helpery środowiska wykonawczego ruchu przychodzącego/odpowiedzi, dzielenia, dyspozycji, heartbeat, planisty odpowiedzi | - | `plugin-sdk/reply-dispatch-runtime` | Wąskie helpery dyspozycji/finalizacji odpowiedzi | - | `plugin-sdk/reply-history` | Współdzielone helpery historii odpowiedzi dla krótkiego okna, takie jak `buildHistoryContext`, `recordPendingHistoryEntry` i `clearHistoryEntriesIfEnabled` | + | `plugin-sdk/telegram-command-config` | Helpery normalizacji nazw/opisów poleceń Telegram oraz sprawdzania duplikatów/konfliktów, nawet gdy bundlowana powierzchnia kontraktu Telegram jest niedostępna | + | `plugin-sdk/approval-runtime` | Helpery zatwierdzeń exec/pluginów, konstruktory możliwości zatwierdzeń, helpery auth/profili, natywne helpery routingu/runtime | + | `plugin-sdk/reply-runtime` | Współdzielone helpery runtime dla wejścia/odpowiedzi, chunking, wysyłka, heartbeat, planer odpowiedzi | + | `plugin-sdk/reply-dispatch-runtime` | Wąskie helpery wysyłki/finalizacji odpowiedzi | + | `plugin-sdk/reply-history` | Współdzielone helpery krótkookresowej historii odpowiedzi, takie jak `buildHistoryContext`, `recordPendingHistoryEntry` i `clearHistoryEntriesIfEnabled` | | `plugin-sdk/reply-reference` | `createReplyReferencePlanner` | - | `plugin-sdk/reply-chunking` | Wąskie helpery dzielenia tekstu/Markdown | - | `plugin-sdk/session-store-runtime` | Helpery ścieżek magazynu sesji + `updated-at` | + | `plugin-sdk/reply-chunking` | Wąskie helpery chunkingu tekstu/Markdown | + | `plugin-sdk/session-store-runtime` | Helpery ścieżek updated-at i magazynu sesji | | `plugin-sdk/state-paths` | Helpery ścieżek katalogów stanu/OAuth | - | `plugin-sdk/routing` | Helpery tras/kluczy sesji/powiązań kont, takie jak `resolveAgentRoute`, `buildAgentSessionKey` i `resolveDefaultAgentBoundAccountId` | - | `plugin-sdk/status-helpers` | Współdzielone helpery podsumowań statusu kanałów/kont, domyślne stany środowiska wykonawczego i helpery metadanych problemów | + | `plugin-sdk/routing` | Helpery tras/kluczy sesji/wiązania kont, takie jak `resolveAgentRoute`, `buildAgentSessionKey` i `resolveDefaultAgentBoundAccountId` | + | `plugin-sdk/status-helpers` | Współdzielone helpery podsumowania statusu kanału/konta, domyślne stany runtime i helpery metadanych problemów | | `plugin-sdk/target-resolver-runtime` | Współdzielone helpery rozstrzygania celów | | `plugin-sdk/string-normalization-runtime` | Helpery normalizacji slugów/ciągów | - | `plugin-sdk/request-url` | Wyodrębnianie URL-i tekstowych z danych wejściowych typu fetch/request | + | `plugin-sdk/request-url` | Wyodrębniaj URL-e tekstowe z danych wejściowych podobnych do fetch/request | | `plugin-sdk/run-command` | Uruchamianie poleceń z limitem czasu i znormalizowanymi wynikami stdout/stderr | | `plugin-sdk/param-readers` | Typowe czytniki parametrów narzędzi/CLI | - | `plugin-sdk/tool-payload` | Wyodrębnianie znormalizowanych payloadów z obiektów wyników narzędzi | - | `plugin-sdk/tool-send` | Wyodrębnianie kanonicznych pól celu wysyłki z argumentów narzędzi | + | `plugin-sdk/tool-payload` | Wyodrębnia znormalizowane ładunki z obiektów wyników narzędzi | + | `plugin-sdk/tool-send` | Wyodrębnia kanoniczne pola celu wysyłki z argumentów narzędzi | | `plugin-sdk/temp-path` | Współdzielone helpery ścieżek tymczasowego pobierania | - | `plugin-sdk/logging-core` | Helpery loggera podsystemu i redakcji | + | `plugin-sdk/logging-core` | Helpery loggera subsystemu i redakcji | | `plugin-sdk/markdown-table-runtime` | Helpery trybu tabel Markdown | | `plugin-sdk/json-store` | Małe helpery odczytu/zapisu stanu JSON | - | `plugin-sdk/file-lock` | Helpery re-entrant file-lock | - | `plugin-sdk/persistent-dedupe` | Helpery pamięci podręcznej deduplikacji na dysku | - | `plugin-sdk/acp-runtime` | Helpery środowiska wykonawczego/sesji ACP i dyspozycji odpowiedzi | - | `plugin-sdk/agent-config-primitives` | Wąskie prymitywy schematu konfiguracji środowiska wykonawczego agenta | - | `plugin-sdk/boolean-param` | Czytnik parametrów luźnych wartości logicznych | - | `plugin-sdk/dangerous-name-runtime` | Helpery rozstrzygania dopasowań niebezpiecznych nazw | + | `plugin-sdk/file-lock` | Helpery reentrant file-lock | + | `plugin-sdk/persistent-dedupe` | Helpery cache deduplikacji opartej na dysku | + | `plugin-sdk/acp-runtime` | Helpery ACP runtime/sesji i wysyłki odpowiedzi | + | `plugin-sdk/agent-config-primitives` | Wąskie prymitywy schematu konfiguracji runtime agenta | + | `plugin-sdk/boolean-param` | Luźny czytnik parametrów boolean | + | `plugin-sdk/dangerous-name-runtime` | Helpery rozstrzygania dopasowania niebezpiecznych nazw | | `plugin-sdk/device-bootstrap` | Helpery bootstrapu urządzenia i tokenów parowania | | `plugin-sdk/extension-shared` | Współdzielone prymitywy helperów kanałów pasywnych, statusu i ambient proxy | - | `plugin-sdk/models-provider-runtime` | Helpery odpowiedzi polecenia `/models` i dostawców | + | `plugin-sdk/models-provider-runtime` | Helpery odpowiedzi dostawcy/polecenia `/models` | | `plugin-sdk/skill-commands-runtime` | Helpery listowania poleceń Skills | - | `plugin-sdk/native-command-registry` | Helpery rejestru/budowania/serializacji natywnych poleceń | - | `plugin-sdk/provider-zai-endpoint` | Helpery wykrywania punktów końcowych Z.AI | + | `plugin-sdk/native-command-registry` | Natywne helpery rejestracji/budowy/serializacji poleceń | + | `plugin-sdk/provider-zai-endpoint` | Helpery wykrywania endpointu Z.A.I | | `plugin-sdk/infra-runtime` | Helpery zdarzeń systemowych/heartbeat | - | `plugin-sdk/collection-runtime` | Małe helpery ograniczonej pamięci podręcznej | + | `plugin-sdk/collection-runtime` | Małe helpery cache z ograniczonym rozmiarem | | `plugin-sdk/diagnostic-runtime` | Helpery flag i zdarzeń diagnostycznych | - | `plugin-sdk/error-runtime` | Graf błędów, formatowanie, współdzielone helpery klasyfikacji błędów, `isApprovalNotFoundError` | - | `plugin-sdk/fetch-runtime` | Opakowany fetch, proxy i helpery pinned lookup | + | `plugin-sdk/error-runtime` | Helpery grafu błędów, formatowania, współdzielonej klasyfikacji błędów, `isApprovalNotFoundError` | + | `plugin-sdk/fetch-runtime` | Opakowane helpery fetch, proxy i pinned lookup | | `plugin-sdk/host-runtime` | Helpery normalizacji nazw hostów i hostów SCP | - | `plugin-sdk/retry-runtime` | Helpery konfiguracji ponowień i uruchamiania ponowień | - | `plugin-sdk/agent-runtime` | Helpery katalogów/tożsamości/obszarów roboczych agenta | - | `plugin-sdk/directory-runtime` | Zapytania/deduplikacja katalogów na podstawie konfiguracji | + | `plugin-sdk/retry-runtime` | Helpery konfiguracji retry i wykonawcy retry | + | `plugin-sdk/agent-runtime` | Helpery katalogu/tożsamości/przestrzeni roboczej agenta | + | `plugin-sdk/directory-runtime` | Zapytania/deduplikacja katalogów opartych na konfiguracji | | `plugin-sdk/keyed-async-queue` | `KeyedAsyncQueue` | - | Ścieżka podrzędna | Kluczowe eksporty | + | Subpath | Key exports | | --- | --- | - | `plugin-sdk/media-runtime` | Współdzielone helpery pobierania/przekształcania/przechowywania mediów oraz kreatory payloadów mediów | - | `plugin-sdk/media-generation-runtime` | Współdzielone helpery failover generowania mediów, wybór kandydatów i komunikaty o brakujących modelach | - | `plugin-sdk/media-understanding` | Typy dostawców rozumienia mediów oraz eksporty helperów obrazu/audio skierowane do dostawców | - | `plugin-sdk/text-runtime` | Współdzielone helpery tekstu/Markdown/logowania, takie jak usuwanie tekstu widocznego dla asystenta, renderowanie/dzielenie/tabele Markdown, helpery redakcji, helpery tagów dyrektyw i narzędzia bezpiecznego tekstu | - | `plugin-sdk/text-chunking` | Helper dzielenia tekstu wychodzącego | - | `plugin-sdk/speech` | Typy dostawców mowy oraz helpery dyrektyw, rejestru i walidacji skierowane do dostawców | - | `plugin-sdk/speech-core` | Współdzielone typy dostawców mowy, rejestr, dyrektywy i helpery normalizacji | - | `plugin-sdk/realtime-transcription` | Typy dostawców transkrypcji w czasie rzeczywistym i helpery rejestru | - | `plugin-sdk/realtime-voice` | Typy dostawców głosu w czasie rzeczywistym i helpery rejestru | + | `plugin-sdk/media-runtime` | Współdzielone helpery pobierania/przekształcania/przechowywania mediów oraz konstruktory ładunków mediów | + | `plugin-sdk/media-generation-runtime` | Współdzielone helpery failover generowania mediów, wybór kandydatów i komunikaty o brakującym modelu | + | `plugin-sdk/media-understanding` | Typy dostawców rozumienia mediów oraz eksporty helperów obrazów/audio po stronie dostawcy | + | `plugin-sdk/text-runtime` | Współdzielone helpery tekstu/Markdown/logowania, takie jak usuwanie tekstu widocznego dla asystenta, helpery renderowania/chunkingu/tabel Markdown, helpery redakcji, helpery tagów dyrektyw i bezpieczne narzędzia tekstowe | + | `plugin-sdk/text-chunking` | Helper chunkingu tekstu wychodzącego | + | `plugin-sdk/speech` | Typy dostawców mowy oraz helpery dyrektyw, rejestru i walidacji po stronie dostawcy | + | `plugin-sdk/speech-core` | Współdzielone typy dostawców mowy, rejestru, dyrektyw i helpery normalizacji | + | `plugin-sdk/realtime-transcription` | Typy dostawców transkrypcji czasu rzeczywistego i helpery rejestru | + | `plugin-sdk/realtime-voice` | Typy dostawców głosu czasu rzeczywistego i helpery rejestru | | `plugin-sdk/image-generation` | Typy dostawców generowania obrazów | - | `plugin-sdk/image-generation-core` | Współdzielone typy generowania obrazów, helpery failover, auth i rejestru | - | `plugin-sdk/music-generation` | Typy dostawców/żądań/wyników generowania muzyki | - | `plugin-sdk/music-generation-core` | Współdzielone typy generowania muzyki, helpery failover, wyszukiwanie dostawców i parsowanie model-ref | - | `plugin-sdk/video-generation` | Typy dostawców/żądań/wyników generowania wideo | - | `plugin-sdk/video-generation-core` | Współdzielone typy generowania wideo, helpery failover, wyszukiwanie dostawców i parsowanie model-ref | + | `plugin-sdk/image-generation-core` | Współdzielone typy generowania obrazów, failover, auth i helpery rejestru | + | `plugin-sdk/music-generation` | Typy żądań/wyników/dostawców generowania muzyki | + | `plugin-sdk/music-generation-core` | Współdzielone typy generowania muzyki, helpery failover, wyszukiwania dostawców i parsowania model-ref | + | `plugin-sdk/video-generation` | Typy żądań/wyników/dostawców generowania wideo | + | `plugin-sdk/video-generation-core` | Współdzielone typy generowania wideo, helpery failover, wyszukiwania dostawców i parsowania model-ref | | `plugin-sdk/webhook-targets` | Rejestr celów webhooków i helpery instalacji tras | | `plugin-sdk/webhook-path` | Helpery normalizacji ścieżek webhooków | | `plugin-sdk/web-media` | Współdzielone helpery ładowania zdalnych/lokalnych mediów | - | `plugin-sdk/zod` | Reeksport `zod` dla odbiorców Plugin SDK | + | `plugin-sdk/zod` | Ponownie eksportowany `zod` dla użytkowników Plugin SDK | | `plugin-sdk/testing` | `installCommonResolveTargetErrorCases`, `shouldAckReaction` | - | Ścieżka podrzędna | Kluczowe eksporty | + | Subpath | Key exports | | --- | --- | - | `plugin-sdk/memory-core` | Powierzchnia helperów zestawionego memory-core dla helperów managera/konfiguracji/plików/CLI | - | `plugin-sdk/memory-core-engine-runtime` | Fasada środowiska wykonawczego indeksowania/wyszukiwania pamięci | - | `plugin-sdk/memory-core-host-engine-foundation` | Eksporty silnika fundamentów hosta pamięci | + | `plugin-sdk/memory-core` | Powierzchnia helperów bundlowanego memory-core dla helperów managera/konfiguracji/plików/CLI | + | `plugin-sdk/memory-core-engine-runtime` | Fasada runtime indeksowania/wyszukiwania pamięci | + | `plugin-sdk/memory-core-host-engine-foundation` | Eksporty silnika foundation hosta pamięci | | `plugin-sdk/memory-core-host-engine-embeddings` | Eksporty silnika embeddingów hosta pamięci | | `plugin-sdk/memory-core-host-engine-qmd` | Eksporty silnika QMD hosta pamięci | | `plugin-sdk/memory-core-host-engine-storage` | Eksporty silnika przechowywania hosta pamięci | - | `plugin-sdk/memory-core-host-multimodal` | Helpery multimodalne hosta pamięci | + | `plugin-sdk/memory-core-host-multimodal` | Wielomodalne helpery hosta pamięci | | `plugin-sdk/memory-core-host-query` | Helpery zapytań hosta pamięci | | `plugin-sdk/memory-core-host-secret` | Helpery sekretów hosta pamięci | | `plugin-sdk/memory-core-host-events` | Helpery dziennika zdarzeń hosta pamięci | | `plugin-sdk/memory-core-host-status` | Helpery statusu hosta pamięci | - | `plugin-sdk/memory-core-host-runtime-cli` | Helpery środowiska wykonawczego CLI hosta pamięci | - | `plugin-sdk/memory-core-host-runtime-core` | Helpery głównego środowiska wykonawczego hosta pamięci | - | `plugin-sdk/memory-core-host-runtime-files` | Helpery plików/środowiska wykonawczego hosta pamięci | - | `plugin-sdk/memory-host-core` | Neutralny wobec dostawcy alias dla helperów głównego środowiska wykonawczego hosta pamięci | + | `plugin-sdk/memory-core-host-runtime-cli` | Helpery runtime CLI hosta pamięci | + | `plugin-sdk/memory-core-host-runtime-core` | Helpery głównego runtime hosta pamięci | + | `plugin-sdk/memory-core-host-runtime-files` | Helpery plików/runtime hosta pamięci | + | `plugin-sdk/memory-host-core` | Neutralny wobec dostawcy alias dla helperów głównego runtime hosta pamięci | | `plugin-sdk/memory-host-events` | Neutralny wobec dostawcy alias dla helperów dziennika zdarzeń hosta pamięci | - | `plugin-sdk/memory-host-files` | Neutralny wobec dostawcy alias dla helperów plików/środowiska wykonawczego hosta pamięci | - | `plugin-sdk/memory-host-markdown` | Współdzielone helpery managed-markdown dla pluginów powiązanych z pamięcią | - | `plugin-sdk/memory-host-search` | Aktywna fasada środowiska wykonawczego pamięci do dostępu do search-manager | + | `plugin-sdk/memory-host-files` | Neutralny wobec dostawcy alias dla helperów plików/runtime hosta pamięci | + | `plugin-sdk/memory-host-markdown` | Współdzielone helpery zarządzanego Markdown dla pluginów sąsiadujących z pamięcią | + | `plugin-sdk/memory-host-search` | Aktywna fasada runtime pamięci do dostępu do menedżera wyszukiwania | | `plugin-sdk/memory-host-status` | Neutralny wobec dostawcy alias dla helperów statusu hosta pamięci | - | `plugin-sdk/memory-lancedb` | Powierzchnia helperów zestawionego memory-lancedb | + | `plugin-sdk/memory-lancedb` | Powierzchnia helperów bundlowanego memory-lancedb | - - | Rodzina | Bieżące ścieżki podrzędne | Zamierzone użycie | + + | Family | Current subpaths | Intended use | | --- | --- | --- | - | Browser | `plugin-sdk/browser-cdp`, `plugin-sdk/browser-config-runtime`, `plugin-sdk/browser-config-support`, `plugin-sdk/browser-control-auth`, `plugin-sdk/browser-node-runtime`, `plugin-sdk/browser-profiles`, `plugin-sdk/browser-security-runtime`, `plugin-sdk/browser-setup-tools`, `plugin-sdk/browser-support` | Helpery wsparcia zestawionego pluginu browser (`browser-support` pozostaje barrelem zgodności) | - | Matrix | `plugin-sdk/matrix`, `plugin-sdk/matrix-helper`, `plugin-sdk/matrix-runtime-heavy`, `plugin-sdk/matrix-runtime-shared`, `plugin-sdk/matrix-runtime-surface`, `plugin-sdk/matrix-surface`, `plugin-sdk/matrix-thread-bindings` | Powierzchnia helperów/środowiska wykonawczego zestawionego Matrix | - | Line | `plugin-sdk/line`, `plugin-sdk/line-core`, `plugin-sdk/line-runtime`, `plugin-sdk/line-surface` | Powierzchnia helperów/środowiska wykonawczego zestawionego LINE | - | IRC | `plugin-sdk/irc`, `plugin-sdk/irc-surface` | Powierzchnia helperów zestawionego IRC | - | Helpery specyficzne dla kanałów | `plugin-sdk/googlechat`, `plugin-sdk/zalouser`, `plugin-sdk/bluebubbles`, `plugin-sdk/bluebubbles-policy`, `plugin-sdk/mattermost`, `plugin-sdk/mattermost-policy`, `plugin-sdk/feishu-conversation`, `plugin-sdk/msteams`, `plugin-sdk/nextcloud-talk`, `plugin-sdk/nostr`, `plugin-sdk/tlon`, `plugin-sdk/twitch` | Warstwy zgodności/helperów zestawionych kanałów | - | Helpery specyficzne dla auth/pluginów | `plugin-sdk/github-copilot-login`, `plugin-sdk/github-copilot-token`, `plugin-sdk/diagnostics-otel`, `plugin-sdk/diffs`, `plugin-sdk/llm-task`, `plugin-sdk/thread-ownership`, `plugin-sdk/voice-call` | Warstwy helperów zestawionych funkcji/pluginów; `plugin-sdk/github-copilot-token` obecnie eksportuje `DEFAULT_COPILOT_API_BASE_URL`, `deriveCopilotApiBaseUrlFromToken` i `resolveCopilotApiToken` | + | Browser | `plugin-sdk/browser-cdp`, `plugin-sdk/browser-config-runtime`, `plugin-sdk/browser-config-support`, `plugin-sdk/browser-control-auth`, `plugin-sdk/browser-node-runtime`, `plugin-sdk/browser-profiles`, `plugin-sdk/browser-security-runtime`, `plugin-sdk/browser-setup-tools`, `plugin-sdk/browser-support` | Helpery wsparcia bundlowanego pluginu przeglądarki (`browser-support` pozostaje barrelem zgodności) | + | Matrix | `plugin-sdk/matrix`, `plugin-sdk/matrix-helper`, `plugin-sdk/matrix-runtime-heavy`, `plugin-sdk/matrix-runtime-shared`, `plugin-sdk/matrix-runtime-surface`, `plugin-sdk/matrix-surface`, `plugin-sdk/matrix-thread-bindings` | Powierzchnia helperów/runtime bundlowanego Matrix | + | Line | `plugin-sdk/line`, `plugin-sdk/line-core`, `plugin-sdk/line-runtime`, `plugin-sdk/line-surface` | Powierzchnia helperów/runtime bundlowanego LINE | + | IRC | `plugin-sdk/irc`, `plugin-sdk/irc-surface` | Powierzchnia helperów bundlowanego IRC | + | Channel-specific helpers | `plugin-sdk/googlechat`, `plugin-sdk/zalouser`, `plugin-sdk/bluebubbles`, `plugin-sdk/bluebubbles-policy`, `plugin-sdk/mattermost`, `plugin-sdk/mattermost-policy`, `plugin-sdk/feishu-conversation`, `plugin-sdk/msteams`, `plugin-sdk/nextcloud-talk`, `plugin-sdk/nostr`, `plugin-sdk/tlon`, `plugin-sdk/twitch` | Warstwy zgodności/helperów bundlowanych kanałów | + | Auth/plugin-specific helpers | `plugin-sdk/github-copilot-login`, `plugin-sdk/github-copilot-token`, `plugin-sdk/diagnostics-otel`, `plugin-sdk/diffs`, `plugin-sdk/llm-task`, `plugin-sdk/thread-ownership`, `plugin-sdk/voice-call` | Warstwy helperów bundlowanych funkcji/pluginów; `plugin-sdk/github-copilot-token` obecnie eksportuje `DEFAULT_COPILOT_API_BASE_URL`, `deriveCopilotApiBaseUrlFromToken` i `resolveCopilotApiToken` | @@ -309,57 +308,57 @@ metodami: ### Rejestracja możliwości -| Metoda | Co rejestruje | -| ------------------------------------------------ | ------------------------------ | -| `api.registerProvider(...)` | Wnioskowanie tekstowe (LLM) | +| Method | What it registers | +| ------------------------------------------------ | -------------------------------- | +| `api.registerProvider(...)` | Wnioskowanie tekstowe (LLM) | | `api.registerCliBackend(...)` | Lokalny backend wnioskowania CLI | -| `api.registerChannel(...)` | Kanał wiadomości | -| `api.registerSpeechProvider(...)` | Synteza text-to-speech / STT | -| `api.registerRealtimeTranscriptionProvider(...)` | Strumieniowa transkrypcja w czasie rzeczywistym | -| `api.registerRealtimeVoiceProvider(...)` | Dwukierunkowe sesje głosowe w czasie rzeczywistym | -| `api.registerMediaUnderstandingProvider(...)` | Analiza obrazu/audio/wideo | -| `api.registerImageGenerationProvider(...)` | Generowanie obrazów | -| `api.registerMusicGenerationProvider(...)` | Generowanie muzyki | -| `api.registerVideoGenerationProvider(...)` | Generowanie wideo | -| `api.registerWebFetchProvider(...)` | Dostawca web fetch / scrapingu | -| `api.registerWebSearchProvider(...)` | Web search | +| `api.registerChannel(...)` | Kanał wiadomości | +| `api.registerSpeechProvider(...)` | Synteza text-to-speech / STT | +| `api.registerRealtimeTranscriptionProvider(...)` | Strumieniowa transkrypcja czasu rzeczywistego | +| `api.registerRealtimeVoiceProvider(...)` | Dwukierunkowe sesje głosu czasu rzeczywistego | +| `api.registerMediaUnderstandingProvider(...)` | Analiza obrazów/audio/wideo | +| `api.registerImageGenerationProvider(...)` | Generowanie obrazów | +| `api.registerMusicGenerationProvider(...)` | Generowanie muzyki | +| `api.registerVideoGenerationProvider(...)` | Generowanie wideo | +| `api.registerWebFetchProvider(...)` | Dostawca web fetch / scrape | +| `api.registerWebSearchProvider(...)` | Wyszukiwanie w sieci | ### Narzędzia i polecenia -| Metoda | Co rejestruje | +| Method | What it registers | | ------------------------------- | --------------------------------------------- | | `api.registerTool(tool, opts?)` | Narzędzie agenta (wymagane lub `{ optional: true }`) | | `api.registerCommand(def)` | Niestandardowe polecenie (omija LLM) | ### Infrastruktura -| Metoda | Co rejestruje | -| ---------------------------------------------- | -------------------------------- | -| `api.registerHook(events, handler, opts?)` | Hook zdarzeń | -| `api.registerHttpRoute(params)` | Punkt końcowy HTTP gateway | -| `api.registerGatewayMethod(name, handler)` | Metoda RPC gateway | -| `api.registerCli(registrar, opts?)` | Podpolecenie CLI | -| `api.registerService(service)` | Usługa działająca w tle | -| `api.registerInteractiveHandler(registration)` | Handler interaktywny | -| `api.registerMemoryPromptSupplement(builder)` | Dodatkowa sekcja promptu związana z pamięcią | -| `api.registerMemoryCorpusSupplement(adapter)` | Dodatkowy korpus wyszukiwania/odczytu pamięci | +| Method | What it registers | +| ---------------------------------------------- | --------------------------------------- | +| `api.registerHook(events, handler, opts?)` | Hook zdarzenia | +| `api.registerHttpRoute(params)` | Punkt końcowy HTTP Gateway | +| `api.registerGatewayMethod(name, handler)` | Metoda RPC Gateway | +| `api.registerCli(registrar, opts?)` | Podpolecenie CLI | +| `api.registerService(service)` | Usługa w tle | +| `api.registerInteractiveHandler(registration)` | Handler interaktywny | +| `api.registerMemoryPromptSupplement(builder)` | Addytywna sekcja promptu sąsiadująca z pamięcią | +| `api.registerMemoryCorpusSupplement(adapter)` | Addytywny korpus wyszukiwania/odczytu pamięci | Zarezerwowane przestrzenie nazw administracyjnych rdzenia (`config.*`, `exec.approvals.*`, `wizard.*`, `update.*`) zawsze pozostają `operator.admin`, nawet jeśli plugin próbuje przypisać -węższy zakres metod gateway. Dla metod należących do pluginu preferuj +węższy zakres metody gateway. Dla metod należących do pluginu preferuj prefiksy specyficzne dla pluginu. ### Metadane rejestracji CLI -`api.registerCli(registrar, opts?)` przyjmuje dwa rodzaje metadanych najwyższego poziomu: +`api.registerCli(registrar, opts?)` akceptuje dwa rodzaje metadanych najwyższego poziomu: -- `commands`: jawne korzenie poleceń należące do rejestratora -- `descriptors`: deskryptory poleceń w czasie parsowania używane dla głównej pomocy CLI, +- `commands`: jawne korzenie poleceń należące do registrara +- `descriptors`: deskryptory poleceń używane na etapie parsowania dla głównej pomocy CLI, routingu i leniwej rejestracji CLI pluginów -Jeśli chcesz, aby polecenie pluginu pozostało ładowane leniwie w normalnej ścieżce głównego CLI, -podaj `descriptors`, które obejmują każdy korzeń polecenia najwyższego poziomu udostępniany przez ten -rejestrator. +Jeśli chcesz, aby polecenie pluginu pozostawało ładowane leniwie w normalnej ścieżce głównego CLI, +podaj `descriptors`, które obejmują każdy korzeń polecenia najwyższego poziomu udostępniany przez tego +registrara. ```typescript api.registerCli( @@ -380,133 +379,132 @@ api.registerCli( ``` Używaj samego `commands` tylko wtedy, gdy nie potrzebujesz leniwej rejestracji głównego CLI. -Ta ścieżka zgodności z eager loading pozostaje wspierana, ale nie instaluje -placeholderów opartych na descriptorach dla leniwego ładowania w czasie parsowania. +Ta zgodna ścieżka eager nadal jest obsługiwana, ale nie instaluje +placeholderów opartych na deskryptorach dla leniwego ładowania na etapie parsowania. ### Rejestracja backendu CLI -`api.registerCliBackend(...)` pozwala pluginowi posiadać domyślną konfigurację lokalnego -backendu CLI AI, takiego jak `codex-cli`. +`api.registerCliBackend(...)` pozwala pluginowi zarządzać domyślną konfiguracją lokalnego +backendu AI CLI, takiego jak `codex-cli`. -- `id` backendu staje się prefiksem dostawcy w odwołaniach do modeli, takich jak `codex-cli/gpt-5`. +- `id` backendu staje się prefiksem dostawcy w odwołaniach do modeli takich jak `codex-cli/gpt-5`. - `config` backendu używa tego samego kształtu co `agents.defaults.cliBackends.`. - Konfiguracja użytkownika nadal ma pierwszeństwo. OpenClaw scala `agents.defaults.cliBackends.` z - domyślną konfiguracją pluginu przed uruchomieniem CLI. -- Użyj `normalizeConfig`, gdy backend potrzebuje przekształceń zgodności po scaleniu + domyślną wartością pluginu przed uruchomieniem CLI. +- Używaj `normalizeConfig`, gdy backend potrzebuje przekształceń zgodności po scaleniu (na przykład normalizacji starych kształtów flag). -### Sloty wyłączne +### Wyłączne sloty -| Metoda | Co rejestruje | -| ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------- | -| `api.registerContextEngine(id, factory)` | Silnik kontekstu (aktywny tylko jeden naraz). Callback `assemble()` otrzymuje `availableTools` i `citationsMode`, aby silnik mógł dostosować dodatki do promptu. | -| `api.registerMemoryCapability(capability)` | Ujednolicona możliwość pamięci | -| `api.registerMemoryPromptSection(builder)` | Kreator sekcji promptu pamięci | -| `api.registerMemoryFlushPlan(resolver)` | Resolver planu opróżniania pamięci | -| `api.registerMemoryRuntime(runtime)` | Adapter środowiska wykonawczego pamięci | +| Method | What it registers | +| ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `api.registerContextEngine(id, factory)` | Silnik kontekstu (aktywny może być tylko jeden naraz). Callback `assemble()` otrzymuje `availableTools` i `citationsMode`, aby silnik mógł dostosować dodatki do promptu. | +| `api.registerMemoryCapability(capability)` | Ujednolicona możliwość pamięci | +| `api.registerMemoryPromptSection(builder)` | Konstruktor sekcji promptu pamięci | +| `api.registerMemoryFlushPlan(resolver)` | Resolver planu opróżniania pamięci | +| `api.registerMemoryRuntime(runtime)` | Adapter runtime pamięci | ### Adaptery embeddingów pamięci -| Metoda | Co rejestruje | -| ---------------------------------------------- | ------------------------------------------ | +| Method | What it registers | +| ---------------------------------------------- | ---------------------------------------------- | | `api.registerMemoryEmbeddingProvider(adapter)` | Adapter embeddingów pamięci dla aktywnego pluginu | -- `registerMemoryCapability` to preferowane wyłączne API pluginów pamięci. -- `registerMemoryCapability` może także udostępniać `publicArtifacts.listArtifacts(...)`, - aby pluginy towarzyszące mogły korzystać z eksportowanych artefaktów pamięci przez - `openclaw/plugin-sdk/memory-host-core` zamiast sięgać do prywatnego - układu konkretnego pluginu pamięci. +- `registerMemoryCapability` to preferowane API wyłącznego pluginu pamięci. +- `registerMemoryCapability` może również udostępniać `publicArtifacts.listArtifacts(...)`, + aby pluginy towarzyszące mogły używać eksportowanych artefaktów pamięci przez + `openclaw/plugin-sdk/memory-host-core` zamiast sięgać do prywatnego układu konkretnego + pluginu pamięci. - `registerMemoryPromptSection`, `registerMemoryFlushPlan` i - `registerMemoryRuntime` to starsze, nadal zgodne wyłączne API pluginów pamięci. + `registerMemoryRuntime` to starsze, zgodne wstecz API wyłącznych pluginów pamięci. - `registerMemoryEmbeddingProvider` pozwala aktywnemu pluginowi pamięci zarejestrować jeden - lub więcej identyfikatorów adapterów embeddingów (na przykład `openai`, `gemini` lub własny identyfikator zdefiniowany przez plugin). + lub więcej identyfikatorów adapterów embeddingów (na przykład `openai`, `gemini` lub niestandardowy identyfikator zdefiniowany przez plugin). - Konfiguracja użytkownika, taka jak `agents.defaults.memorySearch.provider` i `agents.defaults.memorySearch.fallback`, jest rozstrzygana względem tych zarejestrowanych identyfikatorów adapterów. ### Zdarzenia i cykl życia -| Metoda | Co robi | +| Method | What it does | | -------------------------------------------- | ----------------------------- | | `api.on(hookName, handler, opts?)` | Typowany hook cyklu życia | -| `api.onConversationBindingResolved(handler)` | Callback rozwiązania powiązania konwersacji | +| `api.onConversationBindingResolved(handler)` | Callback rozstrzygnięcia wiązania rozmowy | ### Semantyka decyzji hooków -- `before_tool_call`: zwrócenie `{ block: true }` jest końcowe. Gdy którykolwiek handler to ustawi, handlery o niższym priorytecie są pomijane. +- `before_tool_call`: zwrócenie `{ block: true }` jest końcowe. Gdy dowolny handler to ustawi, handlery o niższym priorytecie są pomijane. - `before_tool_call`: zwrócenie `{ block: false }` jest traktowane jako brak decyzji (tak samo jak pominięcie `block`), a nie jako nadpisanie. -- `before_install`: zwrócenie `{ block: true }` jest końcowe. Gdy którykolwiek handler to ustawi, handlery o niższym priorytecie są pomijane. +- `before_install`: zwrócenie `{ block: true }` jest końcowe. Gdy dowolny handler to ustawi, handlery o niższym priorytecie są pomijane. - `before_install`: zwrócenie `{ block: false }` jest traktowane jako brak decyzji (tak samo jak pominięcie `block`), a nie jako nadpisanie. -- `reply_dispatch`: zwrócenie `{ handled: true, ... }` jest końcowe. Gdy którykolwiek handler przejmie dyspozycję, handlery o niższym priorytecie i domyślna ścieżka dyspozycji modelu są pomijane. -- `message_sending`: zwrócenie `{ cancel: true }` jest końcowe. Gdy którykolwiek handler to ustawi, handlery o niższym priorytecie są pomijane. +- `reply_dispatch`: zwrócenie `{ handled: true, ... }` jest końcowe. Gdy dowolny handler przejmie wysyłkę, handlery o niższym priorytecie i domyślna ścieżka wysyłki modelu są pomijane. +- `message_sending`: zwrócenie `{ cancel: true }` jest końcowe. Gdy dowolny handler to ustawi, handlery o niższym priorytecie są pomijane. - `message_sending`: zwrócenie `{ cancel: false }` jest traktowane jako brak decyzji (tak samo jak pominięcie `cancel`), a nie jako nadpisanie. ### Pola obiektu API -| Pole | Typ | Opis | -| ------------------------ | ------------------------- | ------------------------------------------------------------------------------------------ | -| `api.id` | `string` | Identyfikator pluginu | -| `api.name` | `string` | Nazwa wyświetlana | -| `api.version` | `string?` | Wersja pluginu (opcjonalna) | -| `api.description` | `string?` | Opis pluginu (opcjonalny) | -| `api.source` | `string` | Ścieżka źródłowa pluginu | -| `api.rootDir` | `string?` | Katalog główny pluginu (opcjonalny) | -| `api.config` | `OpenClawConfig` | Bieżąca migawka konfiguracji (aktywna migawka środowiska wykonawczego w pamięci, gdy jest dostępna) | -| `api.pluginConfig` | `Record` | Konfiguracja specyficzna dla pluginu z `plugins.entries..config` | -| `api.runtime` | `PluginRuntime` | [Helpery środowiska wykonawczego](/pl/plugins/sdk-runtime) | -| `api.logger` | `PluginLogger` | Logger z zakresem (`debug`, `info`, `warn`, `error`) | -| `api.registrationMode` | `PluginRegistrationMode` | Bieżący tryb ładowania; `"setup-runtime"` to lekkie okno uruchamiania/konfiguracji przed pełnym wejściem | -| `api.resolvePath(input)` | `(string) => string` | Rozwiązywanie ścieżki względem katalogu głównego pluginu | +| Field | Type | Description | +| ------------------------ | ------------------------- | ------------------------------------------------------------------------------------------- | +| `api.id` | `string` | Identyfikator pluginu | +| `api.name` | `string` | Nazwa wyświetlana | +| `api.version` | `string?` | Wersja pluginu (opcjonalnie) | +| `api.description` | `string?` | Opis pluginu (opcjonalnie) | +| `api.source` | `string` | Ścieżka źródłowa pluginu | +| `api.rootDir` | `string?` | Katalog główny pluginu (opcjonalnie) | +| `api.config` | `OpenClawConfig` | Bieżąca migawka konfiguracji (aktywny migawkowy stan runtime w pamięci, gdy jest dostępny) | +| `api.pluginConfig` | `Record` | Konfiguracja specyficzna dla pluginu z `plugins.entries..config` | +| `api.runtime` | `PluginRuntime` | [Helpery runtime](/pl/plugins/sdk-runtime) | +| `api.logger` | `PluginLogger` | Logger z zakresem (`debug`, `info`, `warn`, `error`) | +| `api.registrationMode` | `PluginRegistrationMode` | Bieżący tryb ładowania; `"setup-runtime"` to lekki etap uruchamiania/konfiguracji przed pełnym wejściem | +| `api.resolvePath(input)` | `(string) => string` | Rozstrzyga ścieżkę względem katalogu głównego pluginu | -## Wewnętrzna konwencja modułów +## Konwencja modułów wewnętrznych -Wewnątrz pluginu używaj lokalnych plików barrel dla importów wewnętrznych: +Wewnątrz swojego pluginu używaj lokalnych plików barrel dla importów wewnętrznych: ``` my-plugin/ - api.ts # Public exports for external consumers - runtime-api.ts # Internal-only runtime exports - index.ts # Plugin entry point - setup-entry.ts # Lightweight setup-only entry (optional) + api.ts # Eksporty publiczne dla zewnętrznych użytkowników + runtime-api.ts # Eksporty runtime tylko do użytku wewnętrznego + index.ts # Punkt wejścia pluginu + setup-entry.ts # Lekki punkt wejścia tylko do konfiguracji (opcjonalnie) ``` Nigdy nie importuj własnego pluginu przez `openclaw/plugin-sdk/` - z kodu produkcyjnego. Kieruj importy wewnętrzne przez `./api.ts` lub + w kodzie produkcyjnym. Kieruj importy wewnętrzne przez `./api.ts` lub `./runtime-api.ts`. Ścieżka SDK jest wyłącznie kontraktem zewnętrznym. -Powierzchnie publiczne zestawionych pluginów ładowane przez fasady (`api.ts`, `runtime-api.ts`, +Ładowane przez fasadę publiczne powierzchnie bundlowanych pluginów (`api.ts`, `runtime-api.ts`, `index.ts`, `setup-entry.ts` i podobne publiczne pliki wejściowe) teraz preferują -aktywną migawkę konfiguracji środowiska wykonawczego, gdy OpenClaw już działa. Jeśli migawka środowiska -wykonawczego jeszcze nie istnieje, wracają do rozstrzygniętego pliku konfiguracji na dysku. +aktywną migawkę konfiguracji runtime, gdy OpenClaw już działa. Jeśli migawka runtime jeszcze nie istnieje, +używają w zamian rozstrzygniętego pliku konfiguracji z dysku. -Pluginy dostawców mogą również udostępniać wąski lokalny barrel kontraktu pluginu, gdy helper -jest celowo specyficzny dla dostawcy i jeszcze nie należy do ogólnej ścieżki podrzędnej SDK. -Bieżący zestawiony przykład: dostawca Anthropic przechowuje helpery strumieni Claude -we własnej publicznej warstwie `api.ts` / `contract-api.ts`, zamiast promować logikę -nagłówków beta Anthropic i `service_tier` do ogólnego kontraktu -`plugin-sdk/*`. +Pluginy dostawców mogą także udostępniać wąski, lokalny barrel kontraktu pluginu, gdy helper jest +celowo specyficzny dla dostawcy i jeszcze nie należy do ogólnej ścieżki podrzędnej SDK. +Obecny bundlowany przykład: dostawca Anthropic przechowuje helpery strumieni Claude we +własnej publicznej warstwie `api.ts` / `contract-api.ts` zamiast promować logikę nagłówków beta Anthropic i `service_tier` +do ogólnego kontraktu `plugin-sdk/*`. -Inne bieżące zestawione przykłady: +Inne obecne bundlowane przykłady: -- `@openclaw/openai-provider`: `api.ts` eksportuje kreatory dostawców, - helpery modeli domyślnych i kreatory dostawców realtime -- `@openclaw/openrouter-provider`: `api.ts` eksportuje kreator dostawcy oraz +- `@openclaw/openai-provider`: `api.ts` eksportuje konstruktory dostawców, + helpery domyślnych modeli i konstruktory dostawców realtime +- `@openclaw/openrouter-provider`: `api.ts` eksportuje konstruktor dostawcy oraz helpery onboardingu/konfiguracji - Kod produkcyjny rozszerzeń powinien również unikać importów `openclaw/plugin-sdk/`. + Kod produkcyjny rozszerzeń powinien także unikać importów `openclaw/plugin-sdk/`. Jeśli helper jest rzeczywiście współdzielony, przenieś go do neutralnej ścieżki podrzędnej SDK, takiej jak `openclaw/plugin-sdk/speech`, `.../provider-model-shared` lub innej - powierzchni zorientowanej na możliwości, zamiast wiązać dwa pluginy ze sobą. + powierzchni zorientowanej na możliwości, zamiast łączyć ze sobą dwa pluginy. ## Powiązane - [Punkty wejścia](/pl/plugins/sdk-entrypoints) — opcje `definePluginEntry` i `defineChannelPluginEntry` -- [Helpery środowiska wykonawczego](/pl/plugins/sdk-runtime) — pełna dokumentacja referencyjna przestrzeni nazw `api.runtime` +- [Helpery runtime](/pl/plugins/sdk-runtime) — pełna dokumentacja przestrzeni nazw `api.runtime` - [Konfiguracja i config](/pl/plugins/sdk-setup) — pakowanie, manifesty, schematy konfiguracji - [Testowanie](/pl/plugins/sdk-testing) — narzędzia testowe i reguły lint -- [Migracja SDK](/pl/plugins/sdk-migration) — migracja z przestarzałych powierzchni +- [Migracja SDK](/pl/plugins/sdk-migration) — migracja ze starszych powierzchni - [Wnętrze pluginów](/pl/plugins/architecture) — szczegółowa architektura i model możliwości diff --git a/docs/pl/plugins/sdk-provider-plugins.md b/docs/pl/plugins/sdk-provider-plugins.md index 868cbc640..89dd76891 100644 --- a/docs/pl/plugins/sdk-provider-plugins.md +++ b/docs/pl/plugins/sdk-provider-plugins.md @@ -1,33 +1,33 @@ --- read_when: - Tworzysz nowy plugin dostawcy modeli - - Chcesz dodać do OpenClaw proxy zgodne z OpenAI lub niestandardowy LLM - - Musisz zrozumieć uwierzytelnianie dostawcy, katalogi i hooki runtime + - Chcesz dodać do OpenClaw proxy zgodne z OpenAI lub własny LLM + - Musisz zrozumieć uwierzytelnianie dostawców, katalogi i hooki runtime sidebarTitle: Provider Plugins summary: Przewodnik krok po kroku po tworzeniu pluginu dostawcy modeli dla OpenClaw title: Tworzenie pluginów dostawców x-i18n: - generated_at: "2026-04-07T09:49:08Z" + generated_at: "2026-04-09T01:30:52Z" model: gpt-5.4 provider: openai - source_hash: 4da82a353e1bf4fe6dc09e14b8614133ac96565679627de51415926014bd3990 + source_hash: 38d9af522dc19e49c81203a83a4096f01c2398b1df771c848a30ad98f251e9e1 source_path: plugins/sdk-provider-plugins.md workflow: 15 --- # Tworzenie pluginów dostawców -Ten przewodnik przeprowadza przez tworzenie pluginu dostawcy, który dodaje do OpenClaw dostawcę modeli -(LLM). Na końcu będziesz mieć dostawcę z katalogiem modeli, -uwierzytelnianiem kluczem API i dynamicznym rozpoznawaniem modeli. +Ten przewodnik prowadzi przez tworzenie pluginu dostawcy, który dodaje dostawcę modeli +(LLM) do OpenClaw. Na końcu będziesz mieć dostawcę z katalogiem modeli, +uwierzytelnianiem kluczem API i dynamicznym rozwiązywaniem modeli. - Jeśli nie tworzono wcześniej żadnego pluginu OpenClaw, najpierw przeczytaj + Jeśli nie tworzyłeś wcześniej żadnego pluginu OpenClaw, najpierw przeczytaj [Getting Started](/pl/plugins/building-plugins), aby poznać podstawową strukturę pakietu i konfigurację manifestu. -## Instrukcja krok po kroku +## Przewodnik @@ -65,6 +65,9 @@ uwierzytelnianiem kluczem API i dynamicznym rozpoznawaniem modeli. "providerAuthEnvVars": { "acme-ai": ["ACME_AI_API_KEY"] }, + "providerAuthAliases": { + "acme-ai-coding": "acme-ai" + }, "providerAuthChoices": [ { "provider": "acme-ai", @@ -87,16 +90,17 @@ uwierzytelnianiem kluczem API i dynamicznym rozpoznawaniem modeli. Manifest deklaruje `providerAuthEnvVars`, aby OpenClaw mógł wykrywać - poświadczenia bez ładowania runtime Twojego pluginu. `modelSupport` jest opcjonalne - i pozwala OpenClaw automatycznie ładować plugin dostawcy na podstawie skróconych identyfikatorów modeli, - takich jak `acme-large`, zanim pojawią się hooki runtime. Jeśli publikujesz + poświadczenia bez ładowania runtime Twojego pluginu. Dodaj `providerAuthAliases`, + gdy wariant dostawcy ma ponownie używać uwierzytelniania innego identyfikatora dostawcy. `modelSupport` + jest opcjonalne i pozwala OpenClaw automatycznie ładować plugin dostawcy na podstawie skróconych + identyfikatorów modeli, takich jak `acme-large`, zanim hooki runtime zaczną istnieć. Jeśli publikujesz dostawcę w ClawHub, pola `openclaw.compat` i `openclaw.build` są wymagane w `package.json`. - Minimalny dostawca potrzebuje pól `id`, `label`, `auth` i `catalog`: + Minimalny dostawca potrzebuje `id`, `label`, `auth` i `catalog`: ```typescript index.ts import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry"; @@ -167,13 +171,13 @@ uwierzytelnianiem kluczem API i dynamicznym rozpoznawaniem modeli. }); ``` - To jest działający dostawca. Użytkownicy mogą teraz użyć - `openclaw onboard --acme-ai-api-key ` i wybrać + To jest działający dostawca. Użytkownicy mogą teraz + użyć `openclaw onboard --acme-ai-api-key ` i wybrać `acme-ai/acme-large` jako swój model. - Dla bundlowanych dostawców, którzy rejestrują tylko jednego dostawcę tekstowego z - uwierzytelnianiem kluczem API oraz pojedynczym runtime opartym na katalogu, preferuj węższy - helper `defineSingleProviderPluginEntry(...)`: + W przypadku bundlowanych dostawców, którzy rejestrują tylko jednego dostawcę tekstowego z + uwierzytelnianiem kluczem API oraz pojedynczym runtime opartym na katalogu, wybierz raczej + węższy helper `defineSingleProviderPluginEntry(...)`: ```typescript import { defineSingleProviderPluginEntry } from "openclaw/plugin-sdk/provider-entry"; @@ -208,8 +212,8 @@ uwierzytelnianiem kluczem API i dynamicznym rozpoznawaniem modeli. }); ``` - Jeśli przepływ uwierzytelniania musi także modyfikować `models.providers.*`, aliasy i - domyślny model agenta podczas onboardingu, użyj helperów presetów z + Jeśli przepływ uwierzytelniania wymaga także modyfikacji `models.providers.*`, aliasów oraz + domyślnego modelu agenta podczas onboardingu, użyj preset helperów z `openclaw/plugin-sdk/provider-onboard`. Najwęższe helpery to `createDefaultModelPresetAppliers(...)`, `createDefaultModelsPresetAppliers(...)` oraz @@ -217,15 +221,15 @@ uwierzytelnianiem kluczem API i dynamicznym rozpoznawaniem modeli. Gdy natywny endpoint dostawcy obsługuje strumieniowane bloki użycia na zwykłym transporcie `openai-completions`, preferuj współdzielone helpery katalogu z - `openclaw/plugin-sdk/provider-catalog-shared` zamiast hardkodować sprawdzenia identyfikatorów - dostawców. `supportsNativeStreamingUsageCompat(...)` i + `openclaw/plugin-sdk/provider-catalog-shared` zamiast wpisywania na sztywno kontroli identyfikatora + dostawcy. `supportsNativeStreamingUsageCompat(...)` i `applyProviderNativeStreamingUsageCompat(...)` wykrywają obsługę na podstawie mapy możliwości endpointu, - więc natywne endpointy w stylu Moonshot/DashScope nadal optują się do tego mechanizmu, - nawet gdy plugin używa niestandardowego identyfikatora dostawcy. + dzięki czemu natywne endpointy w stylu Moonshot/DashScope nadal się kwalifikują, nawet jeśli + plugin używa niestandardowego identyfikatora dostawcy. - + Jeśli dostawca akceptuje dowolne identyfikatory modeli (jak proxy lub router), dodaj `resolveDynamicModel`: @@ -248,17 +252,17 @@ uwierzytelnianiem kluczem API i dynamicznym rozpoznawaniem modeli. }); ``` - Jeśli rozpoznanie wymaga wywołania sieciowego, użyj `prepareDynamicModel` do asynchronicznego - rozgrzania — po jego zakończeniu `resolveDynamicModel` uruchamia się ponownie. + Jeśli rozwiązywanie wymaga wywołania sieciowego, użyj `prepareDynamicModel` do asynchronicznego + warm-upu — `resolveDynamicModel` uruchomi się ponownie po jego zakończeniu. Większość dostawców potrzebuje tylko `catalog` + `resolveDynamicModel`. Dodawaj hooki - stopniowo, zależnie od wymagań dostawcy. + stopniowo, w miarę jak dostawca ich wymaga. Współdzielone buildery helperów obejmują teraz najczęstsze rodziny zgodności replay/tool, - więc pluginy zwykle nie muszą ręcznie okablowywać każdego hooka jeden po drugim: + więc pluginy zwykle nie muszą ręcznie podłączać każdego hooka osobno: ```typescript import { buildProviderReplayFamilyHooks } from "openclaw/plugin-sdk/provider-model-shared"; @@ -278,17 +282,17 @@ uwierzytelnianiem kluczem API i dynamicznym rozpoznawaniem modeli. }); ``` - Obecnie dostępne rodziny replay: + Dostępne dziś rodziny replay: - | Rodzina | Co okablowuje | + | Family | Co podłącza | | --- | --- | - | `openai-compatible` | Współdzielona polityka replay w stylu OpenAI dla transportów zgodnych z OpenAI, w tym sanityzację `tool-call-id`, poprawki kolejności assistant-first oraz ogólną walidację tur Gemini tam, gdzie transport tego wymaga | - | `anthropic-by-model` | Świadoma Claude polityka replay wybierana według `modelId`, dzięki czemu transporty wiadomości Anthropic dostają czyszczenie bloków thinking specyficzne dla Claude tylko wtedy, gdy rozpoznany model jest rzeczywiście identyfikatorem Claude | - | `google-gemini` | Natywna polityka replay Gemini plus sanityzacja replay bootstrap i oznaczony tryb wyjścia reasoning | - | `passthrough-gemini` | Sanityzacja sygnatur thought Gemini dla modeli Gemini uruchamianych przez transporty proxy zgodne z OpenAI; nie włącza natywnej walidacji replay Gemini ani przepisywania bootstrap | - | `hybrid-anthropic-openai` | Hybrydowa polityka dla dostawców, którzy mieszają powierzchnie modeli wiadomości Anthropic i transportów zgodnych z OpenAI w jednym pluginie; opcjonalne usuwanie bloków thinking tylko dla Claude pozostaje ograniczone do strony Anthropic | + | `openai-compatible` | Współdzielona polityka replay w stylu OpenAI dla transportów zgodnych z OpenAI, w tym sanityzacja `tool-call-id`, poprawki kolejności assistant-first oraz ogólna walidacja tur Gemini tam, gdzie transport tego wymaga | + | `anthropic-by-model` | Polityka replay świadoma Claude, wybierana według `modelId`, dzięki czemu transporty wiadomości Anthropic dostają czyszczenie bloków thinking specyficzne dla Claude tylko wtedy, gdy rozwiązany model rzeczywiście ma identyfikator Claude | + | `google-gemini` | Natywna polityka replay Gemini oraz sanityzacja replay bootstrap i tryb oznaczonego wyjścia reasoning | + | `passthrough-gemini` | Sanityzacja sygnatur myśli Gemini dla modeli Gemini uruchamianych przez transporty proxy zgodne z OpenAI; nie włącza natywnej walidacji replay Gemini ani przepisania bootstrap | + | `hybrid-anthropic-openai` | Hybrydowa polityka dla dostawców, którzy łączą powierzchnie modeli wiadomości Anthropic i kompatybilnych z OpenAI w jednym pluginie; opcjonalne usuwanie bloków thinking tylko dla Claude pozostaje ograniczone do strony Anthropic | - Rzeczywiste bundlowane przykłady: + Rzeczywiste przykłady bundlowane: - `google` i `google-gemini-cli`: `google-gemini` - `openrouter`, `kilocode`, `opencode` i `opencode-go`: `passthrough-gemini` @@ -296,19 +300,19 @@ uwierzytelnianiem kluczem API i dynamicznym rozpoznawaniem modeli. - `minimax`: `hybrid-anthropic-openai` - `moonshot`, `ollama`, `xai` i `zai`: `openai-compatible` - Obecnie dostępne rodziny stream: + Dostępne dziś rodziny stream: - | Rodzina | Co okablowuje | + | Family | Co podłącza | | --- | --- | - | `google-thinking` | Normalizację ładunku thinking Gemini we współdzielonej ścieżce stream | - | `kilocode-thinking` | Wrapper reasoning Kilo we współdzielonej ścieżce stream proxy, przy czym `kilo/auto` i nieobsługiwane identyfikatory reasoning proxy pomijają wstrzykiwane thinking | - | `moonshot-thinking` | Mapowanie natywnego binarnego ładunku thinking Moonshot na podstawie konfiguracji + poziomu `/think` | - | `minimax-fast-mode` | Przepisywanie modelu MiniMax fast-mode we współdzielonej ścieżce stream | - | `openai-responses-defaults` | Współdzielone natywne wrappery OpenAI/Codex Responses: nagłówki atrybucji, `/fast`/`serviceTier`, szczegółowość tekstu, natywne wyszukiwanie w sieci Codex, kształtowanie ładunku zgodności reasoning oraz zarządzanie kontekstem Responses | - | `openrouter-thinking` | Wrapper reasoning OpenRouter dla tras proxy, z centralnie obsługiwanym pomijaniem dla nieobsługiwanych modeli/`auto` | - | `tool-stream-default-on` | Wrapper domyślnie włączający `tool_stream` dla dostawców takich jak Z.AI, którzy chcą strumieniowania narzędzi, o ile nie zostanie ono jawnie wyłączone | + | `google-thinking` | Normalizacja payload thinking Gemini na współdzielonej ścieżce stream | + | `kilocode-thinking` | Opakowanie reasoning Kilo na współdzielonej ścieżce stream proxy, z pomijaniem wstrzykiwanego thinking dla `kilo/auto` i nieobsługiwanych identyfikatorów reasoning proxy | + | `moonshot-thinking` | Mapowanie natywnego binarnego payload thinking Moonshot z konfiguracji + poziomu `/think` | + | `minimax-fast-mode` | Przepisanie modelu MiniMax fast-mode na współdzielonej ścieżce stream | + | `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 payload zgodności reasoning oraz zarządzanie kontekstem Responses | + | `openrouter-thinking` | Opakowanie reasoning OpenRouter dla tras proxy, z centralnie obsługiwanym pomijaniem modeli nieobsługiwanych/`auto` | + | `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 to jawnie wyłączone | - Rzeczywiste bundlowane przykłady: + Rzeczywiste przykłady bundlowane: - `google` i `google-gemini-cli`: `google-thinking` - `kilocode`: `kilocode-thinking` @@ -318,7 +322,7 @@ uwierzytelnianiem kluczem API i dynamicznym rozpoznawaniem modeli. - `openrouter`: `openrouter-thinking` - `zai`: `tool-stream-default-on` - `openclaw/plugin-sdk/provider-model-shared` eksportuje też enum rodziny replay + `openclaw/plugin-sdk/provider-model-shared` eksportuje także enum rodziny replay oraz współdzielone helpery, z których te rodziny są zbudowane. Typowe publiczne eksporty obejmują: @@ -335,7 +339,7 @@ uwierzytelnianiem kluczem API i dynamicznym rozpoznawaniem modeli. `normalizeNativeXaiModelId(...)` `openclaw/plugin-sdk/provider-stream` udostępnia zarówno builder rodziny, jak i - publiczne helpery wrapperów, których te rodziny używają ponownie. Typowe publiczne eksporty + publiczne helpery wrapperów ponownie używane przez te rodziny. Typowe publiczne eksporty obejmują: - `ProviderStreamFamily` @@ -348,51 +352,51 @@ uwierzytelnianiem kluczem API i dynamicznym rozpoznawaniem modeli. `createOpenAIResponsesContextManagementWrapper(...)` oraz `createCodexNativeWebSearchWrapper(...)` - współdzielone wrappery proxy/dostawców, takie jak `createOpenRouterWrapper(...)`, - `createToolStreamWrapper(...)` oraz `createMinimaxFastModeWrapper(...)` + `createToolStreamWrapper(...)` i `createMinimaxFastModeWrapper(...)` - Niektóre helpery stream celowo pozostają lokalne dla dostawcy. Obecny bundlowany - przykład: `@openclaw/anthropic-provider` eksportuje + Niektóre helpery stream celowo pozostają lokalne dla dostawcy. Obecny + bundlowany przykład: `@openclaw/anthropic-provider` eksportuje `wrapAnthropicProviderStream`, `resolveAnthropicBetas`, `resolveAnthropicFastMode`, `resolveAnthropicServiceTier` oraz - buildery wrapperów Anthropic niższego poziomu przez publiczny interfejs `api.ts` / + wrappery Anthropic niższego poziomu przez swój publiczny punkt styku `api.ts` / `contract-api.ts`. Te helpery pozostają specyficzne dla Anthropic, ponieważ - kodują też obsługę beta dla Claude OAuth i bramkowanie `context1m`. + kodują także obsługę beta Claude OAuth i bramkowanie `context1m`. - Inni bundlowani dostawcy również trzymają wrappery specyficzne dla transportu lokalnie, gdy - zachowanie nie daje się czysto współdzielić między rodzinami. Obecny przykład: bundlowany - plugin xAI przechowuje natywne kształtowanie xAI Responses we własnym - `wrapStreamFn`, w tym przepisywanie aliasów `/fast`, domyślne `tool_stream`, - czyszczenie nieobsługiwanych strict-tool oraz usuwanie - ładunku reasoning specyficznego dla xAI. + Inni bundlowani dostawcy także zachowują wrappery specyficzne dla transportu lokalnie, gdy + zachowanie nie jest współdzielone w czysty sposób między rodzinami. Obecny przykład: bundlowany + plugin xAI zachowuje natywne kształtowanie xAI Responses we własnym + `wrapStreamFn`, w tym przepisania aliasów `/fast`, domyślne `tool_stream`, + czyszczenie nieobsługiwanych strict-tool oraz usuwanie payload reasoning + specyficznego dla xAI. - `openclaw/plugin-sdk/provider-tools` obecnie udostępnia jedną współdzieloną - rodzinę schematów narzędzi oraz współdzielone helpery schematów/zgodności: + `openclaw/plugin-sdk/provider-tools` udostępnia obecnie jedną współdzieloną + rodzinę schematu narzędzi oraz współdzielone helpery schematów/zgodności: - - `ProviderToolCompatFamily` dokumentuje obecny zestaw współdzielonych rodzin. - - `buildProviderToolCompatFamilyHooks("gemini")` okablowuje czyszczenie - schematów Gemini + diagnostykę dla dostawców, którzy potrzebują schematów narzędzi bezpiecznych dla Gemini. + - `ProviderToolCompatFamily` dokumentuje dzisiejszy współdzielony zbiór rodzin. + - `buildProviderToolCompatFamilyHooks("gemini")` podłącza czyszczenie schematów Gemini + + diagnostykę dla dostawców, którzy potrzebują schematów narzędzi bezpiecznych dla Gemini. - `normalizeGeminiToolSchemas(...)` i `inspectGeminiToolSchemas(...)` - to bazowe publiczne helpery schematów Gemini. - - `resolveXaiModelCompatPatch()` zwraca bundlowaną łatkę zgodności xAI: - `toolSchemaProfile: "xai"`, nieobsługiwane słowa kluczowe schematu, natywne wsparcie - `web_search` oraz dekodowanie argumentów wywołań narzędzi z encji HTML. - - `applyXaiModelCompat(model)` stosuje tę samą łatkę zgodności xAI do rozpoznanego - modelu, zanim trafi on do runnera. + to bazowe publiczne helpery schematu Gemini. + - `resolveXaiModelCompatPatch()` zwraca bundlowany patch zgodności xAI: + `toolSchemaProfile: "xai"`, nieobsługiwane słowa kluczowe schematu, natywne + wsparcie `web_search` oraz dekodowanie argumentów wywołań narzędzi z encjami HTML. + - `applyXaiModelCompat(model)` stosuje ten sam patch zgodności xAI do + rozwiązanego modelu, zanim trafi on do runnera. Rzeczywisty bundlowany przykład: plugin xAI używa `normalizeResolvedModel` oraz - `contributeResolvedModelCompat`, aby zachować metadane zgodności po stronie dostawcy - zamiast hardkodować reguły xAI w rdzeniu. + `contributeResolvedModelCompat`, aby zachować metadane zgodności po stronie + dostawcy zamiast wpisywać reguły xAI na sztywno w core. - Ten sam wzorzec katalogu głównego pakietu wspiera też innych bundlowanych dostawców: + Ten sam wzorzec katalogu głównego pakietu stanowi też podstawę dla innych bundlowanych dostawców: - `@openclaw/openai-provider`: `api.ts` eksportuje buildery dostawców, - helpery modeli domyślnych i buildery dostawców realtime + helpery modeli domyślnych oraz buildery dostawców realtime - `@openclaw/openrouter-provider`: `api.ts` eksportuje builder dostawcy oraz helpery onboardingu/konfiguracji - - Dla dostawców, którzy potrzebują wymiany tokenu przed każdym wywołaniem inferencji: + + Dla dostawców, którzy wymagają wymiany tokena przed każdym wywołaniem inferencji: ```typescript prepareRuntimeAuth: async (ctx) => { @@ -406,7 +410,7 @@ uwierzytelnianiem kluczem API i dynamicznym rozpoznawaniem modeli. ``` - Dla dostawców, którzy potrzebują niestandardowych nagłówków żądania lub modyfikacji body: + Dla dostawców, którzy wymagają niestandardowych nagłówków żądań lub modyfikacji treści żądania: ```typescript // wrapStreamFn returns a StreamFn derived from ctx.streamFn @@ -424,8 +428,8 @@ uwierzytelnianiem kluczem API i dynamicznym rozpoznawaniem modeli. ``` - Dla dostawców, którzy potrzebują natywnych nagłówków lub metadanych żądania/sesji - przy ogólnych transportach HTTP lub WebSocket: + Dla dostawców, którzy potrzebują natywnych nagłówków lub metadanych żądania/sesji w + ogólnych transportach HTTP lub WebSocket: ```typescript resolveTransportTurnState: (ctx) => ({ @@ -461,7 +465,7 @@ uwierzytelnianiem kluczem API i dynamicznym rozpoznawaniem modeli. - OpenClaw wywołuje hooki w tej kolejności. Większość dostawców używa tylko 2–3: + OpenClaw wywołuje hooki w tej kolejności. Większość dostawców używa tylko 2-3: | # | Hook | Kiedy używać | | --- | --- | --- | @@ -469,64 +473,65 @@ uwierzytelnianiem kluczem API i dynamicznym rozpoznawaniem modeli. | 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` dla rodziny dostawców przed ogólnym składaniem modelu | - | 5 | `normalizeConfig` | Normalizuje konfigurację `models.providers.` | - | 6 | `applyNativeStreamingUsageCompat` | Przepisania zgodności natywnego użycia strumieniowego dla dostawców konfiguracyjnych | - | 7 | `resolveConfigApiKey` | Rozpoznawanie auth z markerów env należące do dostawcy | - | 8 | `resolveSyntheticAuth` | Syntetyczne auth lokalne/self-hosted lub oparte na konfiguracji | - | 9 | `shouldDeferSyntheticProfileAuth` | Obniża priorytet syntetycznych placeholderów zapisanych profili względem auth z env/konfiguracji | - | 10 | `resolveDynamicModel` | Akceptuje dowolne identyfikatory modeli upstream | - | 11 | `prepareDynamicModel` | Asynchroniczne pobieranie metadanych przed rozpoznaniem | + | 5 | `normalizeConfig` | Normalizacja konfiguracji `models.providers.` | + | 6 | `applyNativeStreamingUsageCompat` | Przepisania zgodności natywnego strumieniowanego użycia dla dostawców konfiguracyjnych | + | 7 | `resolveConfigApiKey` | Rozwiązywanie uwierzytelniania markerów środowiska należące do dostawcy | + | 8 | `resolveSyntheticAuth` | Syntetyczne uwierzytelnianie lokalne/self-hosted lub oparte na konfiguracji | + | 9 | `shouldDeferSyntheticProfileAuth` | Obniżanie priorytetu syntetycznych placeholderów profili zapisanych względem uwierzytelniania env/config | + | 10 | `resolveDynamicModel` | Akceptowanie dowolnych nadrzędnych identyfikatorów modeli | + | 11 | `prepareDynamicModel` | Asynchroniczne pobieranie metadanych przed rozwiązaniem | | 12 | `normalizeResolvedModel` | Przepisania transportu przed runnerem | - Uwagi o fallback runtime: + Uwagi o fallbacku runtime: - - `normalizeConfig` najpierw sprawdza dopasowanego dostawcę, a potem inne - pluginy dostawców z hookami, dopóki któryś rzeczywiście nie zmieni konfiguracji. + - `normalizeConfig` najpierw sprawdza dopasowanego dostawcę, a potem innych + dostawców z hookami, aż któryś faktycznie zmieni konfigurację. Jeśli żaden hook dostawcy nie przepisze obsługiwanego wpisu konfiguracji rodziny Google, - nadal zostanie zastosowany bundlowany normalizator konfiguracji Google. - - `resolveConfigApiKey` używa hooka dostawcy, gdy jest on udostępniony. Bundlowana - ścieżka `amazon-bedrock` ma też tutaj wbudowany resolver auth z markerów env AWS, - mimo że auth runtime Bedrock nadal używa domyślnego łańcucha AWS SDK. - | 13 | `contributeResolvedModelCompat` | Flagi zgodności dla modeli dostawców działających za innym zgodnym transportem | - | 14 | `capabilities` | Starszy statyczny zestaw możliwości; tylko zgodność | + nadal zastosowany zostanie bundlowany normalizator konfiguracji Google. + - `resolveConfigApiKey` używa hooka dostawcy, gdy jest udostępniony. Bundlowana + ścieżka `amazon-bedrock` ma tutaj również wbudowany resolver markerów środowiska AWS, + mimo że samo uwierzytelnianie runtime Bedrock nadal używa domyślnego + łańcucha AWS SDK. + | 13 | `contributeResolvedModelCompat` | Flagi zgodności dla modeli dostawców działających przez inny zgodny transport | + | 14 | `capabilities` | Starszy statyczny zbiór możliwości; tylko dla zgodności | | 15 | `normalizeToolSchemas` | Czyszczenie schematów narzędzi należące do dostawcy przed rejestracją | | 16 | `inspectToolSchemas` | Diagnostyka schematów narzędzi należąca do dostawcy | | 17 | `resolveReasoningOutputMode` | Kontrakt oznaczonego vs natywnego wyjścia reasoning | - | 18 | `prepareExtraParams` | Domyślne parametry żądań | + | 18 | `prepareExtraParams` | Domyślne parametry żądania | | 19 | `createStreamFn` | W pełni niestandardowy transport StreamFn | - | 20 | `wrapStreamFn` | Wrappery niestandardowych nagłówków/body na zwykłej ścieżce stream | - | 21 | `resolveTransportTurnState` | Natywne nagłówki/metadane dla każdej tury | - | 22 | `resolveWebSocketSessionPolicy` | Natywne nagłówki sesji WS/cool-down | - | 23 | `formatApiKey` | Niestandardowy kształt tokenu runtime | + | 20 | `wrapStreamFn` | Wrappery niestandardowych nagłówków/treści na zwykłej ścieżce stream | + | 21 | `resolveTransportTurnState` | Natywne nagłówki/metadane per turn | + | 22 | `resolveWebSocketSessionPolicy` | Natywne nagłówki sesji WS / cooldown | + | 23 | `formatApiKey` | Niestandardowy kształt tokena runtime | | 24 | `refreshOAuth` | Niestandardowe odświeżanie OAuth | - | 25 | `buildAuthDoctorHint` | Wskazówki naprawy auth | - | 26 | `matchesContextOverflowError` | Wykrywanie przepełnienia należące do dostawcy | + | 25 | `buildAuthDoctorHint` | Wskazówki naprawy uwierzytelniania | + | 26 | `matchesContextOverflowError` | Wykrywanie overflow należące do dostawcy | | 27 | `classifyFailoverReason` | Klasyfikacja rate-limit/overload należąca do dostawcy | - | 28 | `isCacheTtlEligible` | Bramka TTL cache promptów | - | 29 | `buildMissingAuthMessage` | Niestandardowa wskazówka braku auth | - | 30 | `suppressBuiltInModel` | Ukrywa nieaktualne wiersze upstream | + | 28 | `isCacheTtlEligible` | Bramka TTL dla cache promptów | + | 29 | `buildMissingAuthMessage` | Niestandardowa wskazówka brakującego uwierzytelniania | + | 30 | `suppressBuiltInModel` | Ukrywanie nieaktualnych wierszy upstream | | 31 | `augmentModelCatalog` | Syntetyczne wiersze forward-compat | | 32 | `isBinaryThinking` | Binarne włączanie/wyłączanie thinking | | 33 | `supportsXHighThinking` | Obsługa reasoning `xhigh` | | 34 | `resolveDefaultThinkingLevel` | Domyślna polityka `/think` | | 35 | `isModernModelRef` | Dopasowanie modeli live/smoke | - | 36 | `prepareRuntimeAuth` | Wymiana tokenu przed inferencją | + | 36 | `prepareRuntimeAuth` | Wymiana tokena przed inferencją | | 37 | `resolveUsageAuth` | Niestandardowe parsowanie poświadczeń użycia | | 38 | `fetchUsageSnapshot` | Niestandardowy endpoint użycia | | 39 | `createEmbeddingProvider` | Adapter embeddingów należący do dostawcy dla memory/search | | 40 | `buildReplayPolicy` | Niestandardowa polityka replay/kompaktowania transkryptu | | 41 | `sanitizeReplayHistory` | Przepisania replay specyficzne dla dostawcy po ogólnym czyszczeniu | | 42 | `validateReplayTurns` | Ścisła walidacja tur replay przed osadzonym runnerem | - | 43 | `onModelSelected` | Callback po wyborze modelu (np. telemetria) | + | 43 | `onModelSelected` | Callback po wyborze modelu (np. telemetry) | Uwaga o dostrajaniu promptów: - - `resolveSystemPromptContribution` pozwala dostawcy wstrzykiwać świadome cache - wskazówki do promptu systemowego dla rodziny modeli. Preferuj to zamiast + - `resolveSystemPromptContribution` pozwala dostawcy wstrzykiwać wskazówki + do system promptu świadome cache dla rodziny modeli. Preferuj je zamiast `before_prompt_build`, gdy zachowanie należy do jednej rodziny dostawcy/modeli i powinno zachować stabilny/dynamiczny podział cache. - Szczegółowe opisy i rzeczywiste przykłady znajdziesz w + Szczegółowe opisy i przykłady z rzeczywistego użycia znajdziesz w [Internals: Provider Runtime Hooks](/pl/plugins/architecture#provider-runtime-hooks). @@ -534,9 +539,9 @@ uwierzytelnianiem kluczem API i dynamicznym rozpoznawaniem modeli. - Plugin dostawcy może rejestrować mowę, transkrypcję realtime, głos realtime, - rozumienie mediów, generowanie obrazów, generowanie wideo, web fetch - i web search obok inferencji tekstowej: + Plugin dostawcy może rejestrować dostawców speech, realtime transcription, realtime + voice, media understanding, image generation, video generation, web fetch + i web search równolegle z inferencją tekstową: ```typescript register(api) { @@ -644,20 +649,20 @@ uwierzytelnianiem kluczem API i dynamicznym rozpoznawaniem modeli. } ``` - OpenClaw klasyfikuje to jako plugin **hybrid-capability**. Jest to + OpenClaw klasyfikuje to jako plugin **hybrid-capability**. To zalecany wzorzec dla pluginów firmowych (jeden plugin na dostawcę). Zobacz [Internals: Capability Ownership](/pl/plugins/architecture#capability-ownership-model). - Dla generowania wideo preferuj pokazany wyżej kształt możliwości świadomy trybów: - `generate`, `imageToVideo` i `videoToVideo`. Płaskie pola zagregowane, takie + W przypadku generowania wideo preferuj pokazany powyżej kształt możliwości świadomy trybu: + `generate`, `imageToVideo` i `videoToVideo`. Płaskie pola zbiorcze, takie jak `maxInputImages`, `maxInputVideos` i `maxDurationSeconds`, nie - wystarczają, aby czytelnie reklamować obsługę trybów transformacji lub wyłączonych trybów. + wystarczają, aby w czytelny sposób reklamować obsługę trybów transformacji lub tryby wyłączone. Dostawcy generowania muzyki powinni stosować ten sam wzorzec: - `generate` dla generowania wyłącznie z promptu oraz `edit` dla - generowania na podstawie obrazu referencyjnego. Płaskie pola zagregowane, takie jak `maxInputImages`, - `supportsLyrics` i `supportsFormat`, nie wystarczają do reklamowania obsługi - edycji; oczekiwanym kontraktem są jawne bloki `generate` / `edit`. + `generate` dla generowania tylko z promptu oraz `edit` dla generowania + opartego na obrazie referencyjnym. Płaskie pola zbiorcze, takie jak `maxInputImages`, + `supportsLyrics` i `supportsFormat`, nie wystarczają do reklamowania obsługi edycji; + oczekiwanym kontraktem są jawne bloki `generate` / `edit`. @@ -696,7 +701,7 @@ uwierzytelnianiem kluczem API i dynamicznym rozpoznawaniem modeli. -## Publikacja w ClawHub +## Publikowanie w ClawHub Pluginy dostawców publikuje się tak samo jak każdy inny zewnętrzny plugin kodu: @@ -705,36 +710,36 @@ clawhub package publish your-org/your-plugin --dry-run clawhub package publish your-org/your-plugin ``` -Nie używaj tutaj starszego aliasu publikacji tylko dla Skills; pakiety pluginów powinny używać +Nie używaj tutaj starszego aliasu publikowania tylko dla Skills; pakiety pluginów powinny używać `clawhub package publish`. ## Struktura plików ``` /acme-ai/ -├── package.json # openclaw.providers metadata -├── openclaw.plugin.json # Manifest with providerAuthEnvVars +├── package.json # metadane openclaw.providers +├── openclaw.plugin.json # Manifest z metadanymi uwierzytelniania dostawcy ├── index.ts # definePluginEntry + registerProvider └── src/ - ├── provider.test.ts # Tests - └── usage.ts # Usage endpoint (optional) + ├── provider.test.ts # Testy + └── usage.ts # Endpoint użycia (opcjonalnie) ``` -## Opis kolejności katalogu +## Informacje o kolejności katalogu -`catalog.order` określa, kiedy katalog jest scalany względem wbudowanych +`catalog.order` kontroluje, kiedy katalog jest scalany względem wbudowanych dostawców: -| Kolejność | Kiedy | Przypadek użycia | -| --------- | ------------ | --------------------------------------------- | -| `simple` | Pierwsze przejście | Prości dostawcy z kluczem API | -| `profile` | Po `simple` | Dostawcy zależni od profili auth | -| `paired` | Po `profile` | Syntetyzowanie wielu powiązanych wpisów | +| Order | Kiedy | Przypadek użycia | +| --------- | ------------ | ----------------------------------------------- | +| `simple` | Pierwsze przejście | Zwykli 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 | Nadpisywanie istniejących dostawców (wygrywa przy kolizji) | ## Kolejne kroki -- [Channel Plugins](/pl/plugins/sdk-channel-plugins) — jeśli plugin dostarcza także kanał +- [Channel Plugins](/pl/plugins/sdk-channel-plugins) — jeśli plugin udostępnia także kanał - [SDK Runtime](/pl/plugins/sdk-runtime) — helpery `api.runtime` (TTS, search, subagent) -- [SDK Overview](/pl/plugins/sdk-overview) — pełne odniesienie do importów subpath +- [SDK Overview](/pl/plugins/sdk-overview) — pełne odwołanie do importów podścieżek - [Plugin Internals](/pl/plugins/architecture#provider-runtime-hooks) — szczegóły hooków i bundlowane przykłady diff --git a/docs/pl/providers/inferrs.md b/docs/pl/providers/inferrs.md index 4c2dacbb5..80e3c30dd 100644 --- a/docs/pl/providers/inferrs.md +++ b/docs/pl/providers/inferrs.md @@ -3,13 +3,13 @@ read_when: - Chcesz uruchomić OpenClaw z lokalnym serwerem inferrs - Udostępniasz Gemma lub inny model przez inferrs - Potrzebujesz dokładnych flag zgodności OpenClaw dla inferrs -summary: Uruchamianie OpenClaw przez inferrs (lokalny serwer zgodny z OpenAI) +summary: Uruchamiaj OpenClaw przez inferrs (lokalny serwer zgodny z OpenAI) title: inferrs x-i18n: - generated_at: "2026-04-08T02:17:28Z" + generated_at: "2026-04-09T01:29:49Z" model: gpt-5.4 provider: openai - source_hash: d84f660d49a682d0c0878707eebe1bc1e83dd115850687076ea3938b9f9c86c6 + source_hash: 03b9d5a9935c75fd369068bacb7807a5308cd0bd74303b664227fb664c3a2098 source_path: providers/inferrs.md workflow: 15 --- @@ -20,8 +20,8 @@ x-i18n: interfejsem API `/v1` zgodnym z OpenAI. OpenClaw współpracuje z `inferrs` przez ogólną ścieżkę `openai-completions`. -`inferrs` najlepiej obecnie traktować jako niestandardowy, samodzielnie hostowany backend -zgodny z OpenAI, a nie dedykowaną wtyczkę dostawcy OpenClaw. +`inferrs` najlepiej obecnie traktować jako niestandardowy, self-hosted +backend zgodny z OpenAI, a nie dedykowaną wtyczkę dostawcy OpenClaw. ## Szybki start @@ -30,7 +30,7 @@ zgodny z OpenAI, a nie dedykowaną wtyczkę dostawcy OpenClaw. Przykład: ```bash -inferrs serve gg-hf-gg/gemma-4-E2B-it \ +inferrs serve google/gemma-4-E2B-it \ --host 127.0.0.1 \ --port 8080 \ --device metal @@ -43,7 +43,7 @@ curl http://127.0.0.1:8080/health curl http://127.0.0.1:8080/v1/models ``` -3. Dodaj jawny wpis dostawcy OpenClaw i skieruj na niego swój model domyślny. +3. Dodaj jawny wpis dostawcy OpenClaw i skieruj na niego swój domyślny model. ## Pełny przykład konfiguracji @@ -53,9 +53,9 @@ Ten przykład używa Gemma 4 na lokalnym serwerze `inferrs`. { agents: { defaults: { - model: { primary: "inferrs/gg-hf-gg/gemma-4-E2B-it" }, + model: { primary: "inferrs/google/gemma-4-E2B-it" }, models: { - "inferrs/gg-hf-gg/gemma-4-E2B-it": { + "inferrs/google/gemma-4-E2B-it": { alias: "Gemma 4 (inferrs)", }, }, @@ -70,7 +70,7 @@ Ten przykład używa Gemma 4 na lokalnym serwerze `inferrs`. api: "openai-completions", models: [ { - id: "gg-hf-gg/gemma-4-E2B-it", + id: "google/gemma-4-E2B-it", name: "Gemma 4 E2B (inferrs)", reasoning: false, input: ["text"], @@ -90,8 +90,8 @@ Ten przykład używa Gemma 4 na lokalnym serwerze `inferrs`. ## Dlaczego `requiresStringContent` ma znaczenie -Niektóre ścieżki Chat Completions w `inferrs` akceptują tylko ciąg znaków w -`messages[].content`, a nie strukturalne tablice części treści. +Niektóre trasy Chat Completions w `inferrs` akceptują tylko ciąg znaków w +`messages[].content`, a nie ustrukturyzowane tablice części treści. Jeśli uruchomienia OpenClaw kończą się błędem takim jak: @@ -107,13 +107,13 @@ compat: { } ``` -OpenClaw spłaszczy części treści zawierające wyłącznie tekst do zwykłych ciągów znaków przed wysłaniem -żądania. +OpenClaw spłaszczy części treści zawierające wyłącznie tekst do zwykłych ciągów +przed wysłaniem żądania. ## Zastrzeżenie dotyczące Gemma i schematu narzędzi Niektóre obecne kombinacje `inferrs` + Gemma akceptują małe, bezpośrednie -żądania `/v1/chat/completions`, ale nadal kończą się niepowodzeniem przy pełnych turach +żądania do `/v1/chat/completions`, ale nadal kończą się błędem przy pełnych turnach runtime agenta OpenClaw. Jeśli tak się dzieje, najpierw spróbuj tego: @@ -125,55 +125,56 @@ compat: { } ``` -To wyłącza powierzchnię schematu narzędzi OpenClaw dla modelu i może zmniejszyć presję promptu +To wyłącza powierzchnię schematu narzędzi OpenClaw dla modelu i może zmniejszyć nacisk promptu na bardziej restrykcyjnych lokalnych backendach. -Jeśli małe bezpośrednie żądania nadal działają, ale zwykłe tury agenta OpenClaw wciąż -powodują awarie wewnątrz `inferrs`, pozostały problem zwykle leży po stronie zachowania modelu/serwera upstream, a nie warstwy transportowej OpenClaw. +Jeśli małe bezpośrednie żądania nadal działają, ale zwykłe turny agenta OpenClaw dalej +powodują awarie wewnątrz `inferrs`, pozostały problem zwykle dotyczy zachowania +upstream modelu/serwera, a nie warstwy transportu OpenClaw. ## Ręczny test smoke -Po konfiguracji przetestuj obie warstwy: +Po skonfigurowaniu przetestuj obie warstwy: ```bash curl http://127.0.0.1:8080/v1/chat/completions \ -H 'content-type: application/json' \ - -d '{"model":"gg-hf-gg/gemma-4-E2B-it","messages":[{"role":"user","content":"What is 2 + 2?"}],"stream":false}' + -d '{"model":"google/gemma-4-E2B-it","messages":[{"role":"user","content":"What is 2 + 2?"}],"stream":false}' openclaw infer model run \ - --model inferrs/gg-hf-gg/gemma-4-E2B-it \ + --model inferrs/google/gemma-4-E2B-it \ --prompt "What is 2 + 2? Reply with one short sentence." \ --json ``` -Jeśli pierwsze polecenie działa, ale drugie kończy się niepowodzeniem, skorzystaj z poniższych uwag -dotyczących rozwiązywania problemów. +Jeśli pierwsze polecenie działa, ale drugie kończy się błędem, skorzystaj z poniższych +wskazówek rozwiązywania problemów. ## Rozwiązywanie problemów -- `curl /v1/models` kończy się niepowodzeniem: `inferrs` nie działa, nie jest osiągalny lub nie - jest powiązany z oczekiwanym hostem/portem. +- `curl /v1/models` kończy się błędem: `inferrs` nie działa, nie jest osiągalny lub nie + jest zbindowany do oczekiwanego hosta/portu. - `messages[].content ... expected a string`: ustaw `compat.requiresStringContent: true`. - Bezpośrednie małe wywołania `/v1/chat/completions` przechodzą, ale `openclaw infer model run` - kończy się niepowodzeniem: spróbuj `compat.supportsTools: false`. + kończy się błędem: spróbuj `compat.supportsTools: false`. - OpenClaw nie dostaje już błędów schematu, ale `inferrs` nadal ulega awarii przy większych - turach agenta: potraktuj to jako ograniczenie `inferrs` lub modelu upstream i zmniejsz - presję promptu albo zmień lokalny backend/model. + turnach agenta: potraktuj to jako ograniczenie `inferrs` lub modelu upstream i zmniejsz + nacisk promptu albo zmień lokalny backend/model. ## Zachowanie w stylu proxy `inferrs` jest traktowany jako backend `/v1` zgodny z OpenAI w stylu proxy, a nie natywny endpoint OpenAI. -- natywne kształtowanie żądań tylko dla OpenAI nie ma tu zastosowania -- brak `service_tier`, brak `store` dla Responses, brak wskazówek prompt-cache i brak - kształtowania ładunku zgodności reasoning OpenAI +- natywne kształtowanie żądań wyłącznie dla OpenAI nie ma tu zastosowania +- brak `service_tier`, brak `store` dla Responses, brak wskazówek cache promptów i brak + kształtowania payload zgodności reasoning OpenAI - ukryte nagłówki atrybucji OpenClaw (`originator`, `version`, `User-Agent`) - nie są wstrzykiwane do niestandardowych adresów `inferrs` base URLs + nie są wstrzykiwane dla niestandardowych base URL `inferrs` ## Zobacz też -- [Modele lokalne](/pl/gateway/local-models) -- [Rozwiązywanie problemów z gatewayem](/pl/gateway/troubleshooting#local-openai-compatible-backend-passes-direct-probes-but-agent-runs-fail) -- [Dostawcy modeli](/pl/concepts/model-providers) +- [Local models](/pl/gateway/local-models) +- [Gateway troubleshooting](/pl/gateway/troubleshooting#local-openai-compatible-backend-passes-direct-probes-but-agent-runs-fail) +- [Model providers](/pl/concepts/model-providers) diff --git a/docs/pl/providers/qwen.md b/docs/pl/providers/qwen.md index d813edd76..b442c9939 100644 --- a/docs/pl/providers/qwen.md +++ b/docs/pl/providers/qwen.md @@ -2,13 +2,13 @@ read_when: - Chcesz używać Qwen z OpenClaw - Wcześniej używałeś OAuth Qwen -summary: Używaj Qwen Cloud przez wbudowanego providera qwen w OpenClaw +summary: Używaj Qwen Cloud przez dołączonego dostawcę qwen w OpenClaw title: Qwen x-i18n: - generated_at: "2026-04-06T03:12:03Z" + generated_at: "2026-04-09T01:30:16Z" model: gpt-5.4 provider: openai - source_hash: f175793693ab6a4c3f1f4d42040e673c15faf7603a500757423e9e06977c989d + source_hash: 4786df2cb6ec1ab29d191d012c61dcb0e5468bf0f8561fbbb50eed741efad325 source_path: providers/qwen.md workflow: 15 --- @@ -17,25 +17,25 @@ x-i18n: -**OAuth Qwen został usunięty.** Integracja OAuth w warstwie darmowej +**OAuth Qwen został usunięty.** Integracja OAuth w bezpłatnym planie (`qwen-portal`), która używała endpointów `portal.qwen.ai`, nie jest już dostępna. -Szczegóły znajdziesz w [Issue #49557](https://github.com/openclaw/openclaw/issues/49557). +Kontekst znajdziesz w [Issue #49557](https://github.com/openclaw/openclaw/issues/49557). ## Zalecane: Qwen Cloud -OpenClaw traktuje teraz Qwen jako pełnoprawnego wbudowanego providera z kanonicznym identyfikatorem -`qwen`. Wbudowany provider kieruje ruch do endpointów Qwen Cloud / Alibaba DashScope oraz -Coding Plan i zachowuje starsze identyfikatory `modelstudio` jako alias -zgodności. +OpenClaw traktuje teraz Qwen jako pełnoprawnego dołączonego dostawcę z kanonicznym identyfikatorem +`qwen`. Dołączony dostawca obsługuje endpointy Qwen Cloud / Alibaba DashScope oraz +Coding Plan i zachowuje działanie starszych identyfikatorów `modelstudio` jako +aliasu zgodności. -- Provider: `qwen` -- Preferowana zmienna środowiskowa: `QWEN_API_KEY` -- Akceptowane również dla zgodności: `MODELSTUDIO_API_KEY`, `DASHSCOPE_API_KEY` +- Dostawca: `qwen` +- Preferowana zmienna env: `QWEN_API_KEY` +- Akceptowane także dla zgodności: `MODELSTUDIO_API_KEY`, `DASHSCOPE_API_KEY` - Styl API: zgodny z OpenAI -Jeśli chcesz używać `qwen3.6-plus`, preferuj endpoint **Standard (pay-as-you-go)**. +Jeśli chcesz używać `qwen3.6-plus`, wybierz endpoint **Standard (pay-as-you-go)**. Obsługa Coding Plan może być opóźniona względem publicznego katalogu. ```bash @@ -52,9 +52,9 @@ openclaw onboard --auth-choice qwen-standard-api-key openclaw onboard --auth-choice qwen-standard-api-key-cn ``` -Starsze identyfikatory `modelstudio-*` dla `auth-choice` oraz odwołania do modeli `modelstudio/...` nadal -działają jako aliasy zgodności, ale nowe przepływy konfiguracji powinny preferować kanoniczne -identyfikatory `qwen-*` dla `auth-choice` oraz odwołania do modeli `qwen/...`. +Starsze identyfikatory `auth-choice` `modelstudio-*` oraz referencje modeli `modelstudio/...` +nadal działają jako aliasy zgodności, ale nowe przepływy konfiguracji powinny preferować kanoniczne +identyfikatory `auth-choice` z rodziny `qwen-*` oraz referencje modeli `qwen/...`. Po onboardingu ustaw model domyślny: @@ -70,22 +70,22 @@ Po onboardingu ustaw model domyślny: ## Typy planów i endpointy -| Plan | Region | Auth choice | Endpoint | +| Plan | Region | Wybór auth | Endpoint | | -------------------------- | ------ | -------------------------- | ------------------------------------------------ | -| Standard (pay-as-you-go) | Chiny | `qwen-standard-api-key-cn` | `dashscope.aliyuncs.com/compatible-mode/v1` | +| Standard (pay-as-you-go) | China | `qwen-standard-api-key-cn` | `dashscope.aliyuncs.com/compatible-mode/v1` | | Standard (pay-as-you-go) | Global | `qwen-standard-api-key` | `dashscope-intl.aliyuncs.com/compatible-mode/v1` | -| Coding Plan (subskrypcja) | Chiny | `qwen-api-key-cn` | `coding.dashscope.aliyuncs.com/v1` | -| Coding Plan (subskrypcja) | Global | `qwen-api-key` | `coding-intl.dashscope.aliyuncs.com/v1` | +| Coding Plan (subscription) | China | `qwen-api-key-cn` | `coding.dashscope.aliyuncs.com/v1` | +| Coding Plan (subscription) | Global | `qwen-api-key` | `coding-intl.dashscope.aliyuncs.com/v1` | -Provider automatycznie wybiera endpoint na podstawie Twojego wyboru auth. Kanoniczne -wybory używają rodziny `qwen-*`; `modelstudio-*` pozostaje wyłącznie warstwą zgodności. +Dostawca automatycznie wybiera endpoint na podstawie wybranego auth. Kanoniczne +opcje używają rodziny `qwen-*`; `modelstudio-*` pozostaje wyłącznie dla zgodności. Możesz nadpisać to własnym `baseUrl` w konfiguracji. -Natywne endpointy Model Studio sygnalizują zgodność użycia streamingu na -współdzielonym transporcie `openai-completions`. OpenClaw opiera to teraz na możliwościach endpointu, więc -niestandardowe identyfikatory providerów zgodne z DashScope, kierujące ruch na te same -natywne hosty, dziedziczą to samo zachowanie użycia streamingu zamiast -wymagać konkretnie wbudowanego identyfikatora providera `qwen`. +Natywne endpointy Model Studio deklarują zgodność użycia strumieniowego na +współdzielonym transporcie `openai-completions`. OpenClaw opiera to teraz na możliwościach endpointu, +więc niestandardowe identyfikatory dostawców zgodnych z DashScope, kierujące na te same +natywne hosty, dziedziczą to samo zachowanie użycia strumieniowego zamiast +wymagać konkretnie wbudowanego identyfikatora dostawcy `qwen`. ## Pobierz swój klucz API @@ -94,24 +94,26 @@ wymagać konkretnie wbudowanego identyfikatora providera `qwen`. ## Wbudowany katalog -OpenClaw obecnie dostarcza ten wbudowany katalog Qwen: +OpenClaw obecnie dostarcza ten dołączony katalog Qwen. Skonfigurowany katalog jest +świadomy endpointu: konfiguracje Coding Plan pomijają modele, o których wiadomo, że działają +tylko na endpointach Standard. -| Model ref | Input | Context | Notes | -| --------------------------- | ----------- | --------- | -------------------------------------------------- | -| `qwen/qwen3.5-plus` | text, image | 1,000,000 | Model domyślny | -| `qwen/qwen3.6-plus` | text, image | 1,000,000 | Preferuj endpointy Standard, jeśli potrzebujesz tego modelu | -| `qwen/qwen3-max-2026-01-23` | text | 262,144 | Linia Qwen Max | -| `qwen/qwen3-coder-next` | text | 262,144 | Coding | -| `qwen/qwen3-coder-plus` | text | 1,000,000 | Coding | -| `qwen/MiniMax-M2.5` | text | 1,000,000 | Reasoning włączony | -| `qwen/glm-5` | text | 202,752 | GLM | -| `qwen/glm-4.7` | text | 202,752 | GLM | -| `qwen/kimi-k2.5` | text, image | 262,144 | Moonshot AI przez Alibaba | +| Referencja modelu | Wejście | Kontekst | Uwagi | +| -------------------------- | ----------- | --------- | -------------------------------------------------- | +| `qwen/qwen3.5-plus` | text, image | 1,000,000 | Model domyślny | +| `qwen/qwen3.6-plus` | text, image | 1,000,000 | Przy tym modelu preferuj endpointy Standard | +| `qwen/qwen3-max-2026-01-23`| text | 262,144 | Linia Qwen Max | +| `qwen/qwen3-coder-next` | text | 262,144 | Coding | +| `qwen/qwen3-coder-plus` | text | 1,000,000 | Coding | +| `qwen/MiniMax-M2.5` | text | 1,000,000 | Reasoning włączony | +| `qwen/glm-5` | text | 202,752 | GLM | +| `qwen/glm-4.7` | text | 202,752 | GLM | +| `qwen/kimi-k2.5` | text, image | 262,144 | Moonshot AI przez Alibaba | -Dostępność może nadal różnić się w zależności od endpointu i planu rozliczeń, nawet jeśli model -jest obecny we wbudowanym katalogu. +Dostępność może nadal zależeć od endpointu i planu rozliczeniowego, nawet jeśli model +jest obecny w dołączonym katalogu. -Zgodność użycia native-streaming dotyczy zarówno hostów Coding Plan, jak i +Zgodność użycia natywnego strumieniowania dotyczy zarówno hostów Coding Plan, jak i hostów Standard zgodnych z DashScope: - `https://coding.dashscope.aliyuncs.com/v1` @@ -123,31 +125,31 @@ hostów Standard zgodnych z DashScope: `qwen3.6-plus` jest dostępny na endpointach Model Studio Standard (pay-as-you-go): -- Chiny: `dashscope.aliyuncs.com/compatible-mode/v1` +- China: `dashscope.aliyuncs.com/compatible-mode/v1` - Global: `dashscope-intl.aliyuncs.com/compatible-mode/v1` Jeśli endpointy Coding Plan zwracają błąd „unsupported model” dla `qwen3.6-plus`, przełącz się na Standard (pay-as-you-go) zamiast używać pary -endpoint/klucz dla Coding Plan. +endpoint/klucz Coding Plan. ## Plan możliwości -Rozszerzenie `qwen` jest pozycjonowane jako docelowe miejsce dostawcy dla całej powierzchni Qwen +Rozszerzenie `qwen` jest pozycjonowane jako dom producenta dla pełnej powierzchni Qwen Cloud, a nie tylko modeli coding/text. -- Modele text/chat: już wbudowane -- Tool calling, structured output, thinking: dziedziczone z transportu zgodnego z OpenAI -- Image generation: planowane na warstwie pluginu providera -- Image/video understanding: już wbudowane na endpointach Standard -- Speech/audio: planowane na warstwie pluginu providera -- Embeddingi/reranking pamięci: planowane przez powierzchnię adaptera embeddingów -- Video generation: już wbudowane przez współdzieloną możliwość generowania wideo +- Modele text/chat: dołączone już teraz +- Wywoływanie narzędzi, output strukturalny, thinking: dziedziczone z transportu zgodnego z OpenAI +- Generowanie obrazów: planowane na warstwie wtyczki dostawcy +- Rozumienie obrazów/wideo: dołączone już teraz na endpointach Standard +- Speech/audio: planowane na warstwie wtyczki dostawcy +- Embeddingi pamięci/reranking: planowane przez powierzchnię adaptera embeddingów +- Generowanie wideo: dołączone już teraz przez współdzieloną możliwość generowania wideo ## Dodatki multimodalne Rozszerzenie `qwen` udostępnia teraz także: -- Video understanding przez `qwen-vl-max-latest` +- Rozumienie wideo przez `qwen-vl-max-latest` - Generowanie wideo Wan przez: - `wan2.6-t2v` (domyślnie) - `wan2.6-i2v` @@ -158,20 +160,20 @@ Rozszerzenie `qwen` udostępnia teraz także: Te powierzchnie multimodalne używają endpointów DashScope **Standard**, a nie endpointów Coding Plan. -- Globalny/międzynarodowy podstawowy URL Standard: `https://dashscope-intl.aliyuncs.com/compatible-mode/v1` -- Chiński podstawowy URL Standard: `https://dashscope.aliyuncs.com/compatible-mode/v1` +- Global/Intl Standard base URL: `https://dashscope-intl.aliyuncs.com/compatible-mode/v1` +- China Standard base URL: `https://dashscope.aliyuncs.com/compatible-mode/v1` -Dla generowania wideo OpenClaw mapuje skonfigurowany region Qwen na odpowiadający mu -host DashScope AIGC przed wysłaniem zadania: +Dla generowania wideo OpenClaw mapuje skonfigurowany region Qwen na odpowiadający +mu host DashScope AIGC przed wysłaniem zadania: - Global/Intl: `https://dashscope-intl.aliyuncs.com` -- Chiny: `https://dashscope.aliyuncs.com` +- China: `https://dashscope.aliyuncs.com` Oznacza to, że zwykłe `models.providers.qwen.baseUrl` wskazujące na hosty Qwen Coding Plan lub Standard nadal utrzymuje generowanie wideo na poprawnym -regionalnym endpointzie wideo DashScope. +regionalnym endpointcie wideo DashScope. -Dla generowania wideo ustaw model domyślny jawnie: +Dla generowania wideo ustaw jawnie model domyślny: ```json5 { @@ -183,22 +185,22 @@ Dla generowania wideo ustaw model domyślny jawnie: } ``` -Bieżące ograniczenia wbudowanego generowania wideo Qwen: +Obecne limity generowania wideo dla dołączonego Qwen: - Maksymalnie **1** wyjściowe wideo na żądanie - Maksymalnie **1** obraz wejściowy - Maksymalnie **4** wejściowe wideo -- Maksymalnie **10 sekund** czasu trwania +- Maksymalny czas trwania **10 sekund** - Obsługuje `size`, `aspectRatio`, `resolution`, `audio` i `watermark` -- Tryb obrazu/wideo referencyjnego obecnie wymaga **zdalnych URL `http(s)`**. Lokalne +- Tryb obrazu/wideo referencyjnego obecnie wymaga **zdalnych adresów URL http(s)**. Lokalne ścieżki plików są odrzucane od razu, ponieważ endpoint wideo DashScope nie - akceptuje przesyłanych lokalnych buforów dla tych referencji. + akceptuje przesyłanych lokalnych buforów dla takich referencji. -Zobacz [Generowanie wideo](/tools/video-generation), aby poznać współdzielone -parametry narzędzia, wybór providera i zachowanie failover. +Zobacz [Video Generation](/pl/tools/video-generation), aby poznać współdzielone parametry +narzędzia, wybór dostawcy i zachowanie failover. ## Uwaga dotycząca środowiska -Jeśli Gateway działa jako daemon (launchd/systemd), upewnij się, że `QWEN_API_KEY` jest -dostępny dla tego procesu (na przykład w `~/.openclaw/.env` lub przez +Jeśli Gateway działa jako demon (launchd/systemd), upewnij się, że `QWEN_API_KEY` jest +dostępne dla tego procesu (na przykład w `~/.openclaw/.env` lub przez `env.shellEnv`).