From 0422aa9d1db8087ae293fc7d166f103716637e1a Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Wed, 15 Apr 2026 09:56:22 +0000 Subject: [PATCH] chore(i18n): refresh pl translations --- docs/pl/channels/matrix.md | 573 ++++---- docs/pl/concepts/dreaming.md | 168 +-- docs/pl/concepts/memory-search.md | 85 +- docs/pl/gateway/local-models.md | 79 +- docs/pl/help/testing.md | 721 ++++----- docs/pl/plugins/architecture.md | 1298 +++++++++-------- docs/pl/plugins/manifest.md | 505 ++++--- docs/pl/plugins/sdk-channel-plugins.md | 323 ++-- docs/pl/providers/github-copilot.md | 110 +- docs/pl/reference/RELEASING.md | 203 +-- docs/pl/reference/memory-config.md | 372 ++--- .../reference/secretref-credential-surface.md | 39 +- docs/pl/start/showcase.md | 349 +++-- docs/pl/tools/video-generation.md | 284 ++-- 14 files changed, 2650 insertions(+), 2459 deletions(-) diff --git a/docs/pl/channels/matrix.md b/docs/pl/channels/matrix.md index 07d67777f..f4fffb24c 100644 --- a/docs/pl/channels/matrix.md +++ b/docs/pl/channels/matrix.md @@ -2,25 +2,25 @@ read_when: - Konfigurowanie Matrix w OpenClaw - Konfigurowanie E2EE i weryfikacji Matrix -summary: Stan obsługi Matrix, konfiguracja i przykłady ustawień +summary: Status wsparcia Matrix, konfiguracja i przykłady konfiguracji title: Matrix x-i18n: - generated_at: "2026-04-09T01:32:55Z" + generated_at: "2026-04-15T09:51:04Z" model: gpt-5.4 provider: openai - source_hash: 28fc13c7620c1152200315ae69c94205da6de3180c53c814dd8ce03b5cb1758f + source_hash: 631f6fdcfebc23136c1a66b04851a25c047535d13cceba5650b8b421bc3afcf8 source_path: channels/matrix.md workflow: 15 --- # Matrix -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. +Matrix to dołączony Plugin kanałowy dla OpenClaw. +Używa oficjalnego `matrix-js-sdk` i obsługuje DM-y, pokoje, wątki, multimedia, reakcje, ankiety, lokalizację oraz E2EE. -## Dołączona wtyczka +## Dołączony Plugin -Matrix jest dostarczany jako dołączona wtyczka w bieżących wydaniach OpenClaw, więc zwykłe +Matrix jest dostarczany jako dołączony Plugin 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 @@ -38,22 +38,22 @@ Zainstaluj z lokalnego checkoutu: openclaw plugins install ./path/to/local/matrix-plugin ``` -Zobacz [Wtyczki](/pl/tools/plugin), aby poznać zachowanie wtyczek i zasady instalacji. +Zobacz [Plugins](/pl/tools/plugin), aby poznać zachowanie Pluginów i zasady instalacji. ## Konfiguracja -1. Upewnij się, że wtyczka Matrix jest dostępna. - - Bieżące spakowane wydania OpenClaw już ją zawierają. - - Starsze/niestandardowe instalacje mogą dodać ją ręcznie za pomocą powyższych poleceń. +1. Upewnij się, że Plugin Matrix jest dostępny. + - Bieżące spakowane wydania OpenClaw zawierają go już domyślnie. + - Starsze/niestandardowe instalacje mogą dodać go ręcznie za pomocą powyższych poleceń. 2. Utwórz konto Matrix na swoim homeserverze. -3. Skonfiguruj `channels.matrix` z użyciem: +3. Skonfiguruj `channels.matrix`, używając jednego z wariantów: - `homeserver` + `accessToken`, lub - `homeserver` + `userId` + `password`. -4. Uruchom ponownie gateway. -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`. +4. Uruchom ponownie Gateway. +5. Rozpocznij DM z botem lub zaproś go do pokoju. + - Nowe zaproszenia Matrix działają tylko wtedy, gdy zezwala na to `channels.matrix.autoJoin`. -Ścieżki interaktywnej konfiguracji: +Interaktywne ścieżki konfiguracji: ```bash openclaw channels add @@ -63,32 +63,32 @@ openclaw configure --section channels Kreator Matrix pyta o: - URL homeservera -- metodę uwierzytelniania: access token lub hasło -- ID użytkownika (tylko przy uwierzytelnianiu hasłem) +- metodę uwierzytelniania: token dostępu lub hasło +- ID użytkownika (tylko uwierzytelnianie hasłem) - opcjonalną nazwę urządzenia - czy włączyć E2EE - czy skonfigurować dostęp do pokoi i automatyczne dołączanie do zaproszeń -Kluczowe zachowania kreatora: +Najważniejsze zachowania kreatora: -- 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. +- Jeśli zmienne środowiskowe uwierzytelniania Matrix już istnieją, a dla tego konta nie zapisano jeszcze uwierzytelniania w konfiguracji, kreator oferuje skrót env, aby zachować dane uwierzytelniania w zmiennych środowiskowych. - 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. +- Wpisy listy dozwolonych DM akceptują bezpośrednio `@user:server`; nazwy wyświetlane działają tylko wtedy, gdy wyszukiwanie w katalogu na żywo znajdzie dokładnie jedno dopasowanie. +- Wpisy listy dozwolonych 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 listy dozwolonych. +- W trybie listy dozwolonych dla automatycznego dołączania do zaproszeń używaj tylko 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"`. -`channels.matrix.autoJoin` ma domyślnie wartość `off`. +Domyślna wartość `channels.matrix.autoJoin` to `off`. -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. +Jeśli pozostawisz ją nieustawioną, bot nie będzie dołączał do zaproszonych pokoi ani nowych zaproszeń w stylu DM, więc nie pojawi się w nowych grupach ani zaproszonych DM-ach, 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. +Ustaw `autoJoin: "allowlist"` razem z `autoJoinAllowlist`, aby ograniczyć, które zaproszenia akceptuje, albo ustaw `autoJoin: "always"`, jeśli ma dołączać do każdego zaproszenia. -W trybie `allowlist` `autoJoinAllowlist` akceptuje tylko `!roomId:server`, `#alias:server` lub `*`. +W trybie `allowlist` pole `autoJoinAllowlist` akceptuje tylko `!roomId:server`, `#alias:server` lub `*`. -Przykład allowlist: +Przykład listy dozwolonych: ```json5 { @@ -149,11 +149,11 @@ 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`; 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. +Matrix przechowuje buforowane poświadczenia w `~/.openclaw/credentials/matrix/`. +Konto domyślne używa `credentials.json`; nazwane konta używają `credentials-.json`. +Jeśli w tej lokalizacji istnieją buforowane 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 zmiennych środowiskowych (używane, gdy klucz konfiguracji nie jest ustawiony): +Odpowiedniki w postaci zmiennych środowiskowych (używane, gdy klucz konfiguracji nie jest ustawiony): - `MATRIX_HOMESERVER` - `MATRIX_ACCESS_TOKEN` @@ -162,7 +162,7 @@ Odpowiedniki zmiennych środowiskowych (używane, gdy klucz konfiguracji nie jes - `MATRIX_DEVICE_ID` - `MATRIX_DEVICE_NAME` -Dla kont innych niż domyślne użyj zmiennych środowiskowych z zakresem konta: +Dla kont innych niż domyślne użyj zmiennych środowiskowych przypisanych do konta: - `MATRIX__HOMESERVER` - `MATRIX__ACCESS_TOKEN` @@ -181,14 +181,14 @@ Dla znormalizowanego ID konta `ops-bot` użyj: - `MATRIX_OPS_X2D_BOT_HOMESERVER` - `MATRIX_OPS_X2D_BOT_ACCESS_TOKEN` -Matrix escapuje znaki interpunkcyjne w ID kont, aby zmienne środowiskowe z zakresem konta nie kolidowały ze sobą. +Matrix ucieka znaki interpunkcyjne w ID kont, aby uniknąć kolizji przypisanych zmiennych środowiskowych. 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 są już obecne, a wybrane konto nie ma jeszcze zapisanego uwierzytelniania Matrix w konfiguracji. +Interaktywny kreator oferuje skrót do zmiennych środowiskowych tylko wtedy, gdy te zmienne uwierzytelniania już istnieją, a wybrane konto nie ma jeszcze zapisanego uwierzytelniania Matrix w konfiguracji. ## Przykład konfiguracji -To praktyczna bazowa konfiguracja z parowaniem wiadomości prywatnych, allowlistą pokoi i włączonym E2EE: +To praktyczna bazowa konfiguracja z parowaniem DM, listą dozwolonych pokoi i włączonym E2EE: ```json5 { @@ -223,16 +223,16 @@ To praktyczna bazowa konfiguracja z parowaniem wiadomości prywatnych, allowlist } ``` -`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. +`autoJoin` dotyczy wszystkich zaproszeń Matrix, w tym zaproszeń w stylu DM. OpenClaw nie może niezawodnie +sklasyfikować zaproszonego pokoju jako DM lub grupy w momencie zaproszenia, więc wszystkie zaproszenia przechodzą najpierw przez `autoJoin`. +`dm.policy` ma zastosowanie po dołączeniu bota i sklasyfikowaniu pokoju jako DM. ## Podglądy strumieniowe Strumieniowanie odpowiedzi Matrix jest opcjonalne. -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 +Ustaw `channels.matrix.streaming` na `"partial"`, jeśli chcesz, aby OpenClaw wysyłał pojedynczą odpowiedź +z podglądem na żywo, edytował ten podgląd w miejscu podczas generowania tekstu przez model, a następnie finalizował go po zakończeniu odpowiedzi: ```json5 @@ -245,27 +245,27 @@ zakończeniu odpowiedzi: } ``` -- `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. +- `streaming: "off"` jest wartością domyślną. 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 przy użyciu 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 podgląd dla bieżącego bloku odpowiedzi asystenta. Używaj tego tylko wtedy, gdy jednocześnie skonfigurujesz reguły push odbiorcy dla finalizowanych edycji podglądu. +- `blockStreaming: true` włącza oddzielne komunikaty postępu Matrix. Gdy strumieniowanie podglądu jest włączone, Matrix zachowuje aktywny szkic 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 aktywny szkic w miejscu i finalizuje to samo zdarzenie po zakończeniu bloku lub całej tury. +- Jeśli podgląd przestanie mieścić się w jednym zdarzeniu Matrix, OpenClaw zatrzymuje strumieniowanie podglądu i wraca do zwykłego końcowego dostarczenia. +- Odpowiedzi multimedialne nadal wysyłają załączniki normalnie. Jeśli nieaktualny podgląd nie może już zostać bezpiecznie ponownie użyty, OpenClaw redaguje go przed wysłaniem końcowej odpowiedzi multimedialnej. +- Edycje podglądu generują dodatkowe wywołania API Matrix. Pozostaw strumieniowanie wyłączone, jeśli chcesz najbardziej zachowawczego zachowania 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"` 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. +`blockStreaming` samo w sobie nie włącza podglądów szkicu. +Użyj `streaming: "partial"` lub `streaming: "quiet"` dla edycji podglądu; następnie dodaj `blockStreaming: true` tylko wtedy, gdy chcesz także, aby ukończone bloki odpowiedzi asystenta pozostał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 wyłącznie finalnej odpowiedzi. Przy `streaming: "off"`: +Jeśli potrzebujesz standardowych powiadomień Matrix bez niestandardowych reguł push, użyj `streaming: "partial"` dla zachowania „najpierw podgląd” lub pozostaw `streaming` wyłączone dla dostarczania tylko końcowej 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. +- `blockStreaming: true` wysyła każdy ukończony blok jako zwykłą wiadomość Matrix generującą powiadomienie. +- `blockStreaming: false` wysyła tylko końcową ukończoną odpowiedź jako zwykłą wiadomość Matrix generującą powiadomienie. -### Samohostowane reguły push dla cichych sfinalizowanych podglądów +### Samohostowane reguły push dla cichych finalizowanych podglądów -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. +Jeśli uruchamiasz własną infrastrukturę Matrix i chcesz, aby ciche podglądy wysyłały powiadomienie dopiero po zakończeniu bloku lub +końcowej odpowiedzi, ustaw `streaming: "quiet"` i dodaj regułę push per użytkownik dla finalizowanych edycji podglądu. Zwykle jest to konfiguracja po stronie użytkownika-odbiorcy, a nie globalna zmiana konfiguracji homeservera: @@ -273,10 +273,10 @@ Szybka mapa przed rozpoczęciem: - 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 +- do poniższych wywołań API użyj tokenu dostępu użytkownika odbiorcy +- dopasuj `sender` w regule push do pełnego MXID użytkownika bota -1. Skonfiguruj OpenClaw do używania cichych podglądów: +1. Skonfiguruj OpenClaw tak, aby używał cichych podglądów: ```json5 { @@ -288,13 +288,13 @@ 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 access token użytkownika odbiorcy. - - Użyj tokena użytkownika odbierającego, a nie tokena bota. - - 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: +3. Pobierz token dostępu użytkownika odbiorcy. + - Użyj tokenu użytkownika odbierającego, a nie tokenu bota. + - Najłatwiej zwykle ponownie użyć tokenu istniejącej sesji klienta. + - Jeśli musisz wygenerować nowy token, możesz zalogować się przez standardowe API Client-Server Matrix: ```bash curl -sS -X POST \ @@ -318,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 przed dodaniem -poniższej reguły OpenClaw. +Jeśli to nie zwraca żadnych aktywnych pusherów/urządzeń, najpierw napraw zwykłe powiadomienia Matrix, zanim dodasz +poniższą regułę OpenClaw. -OpenClaw oznacza sfinalizowane edycje tekstowych podglądów za pomocą: +OpenClaw oznacza sfinalizowane edycje podglądu tylko tekstowego następująco: ```json { @@ -359,16 +359,16 @@ curl -sS -X PUT \ }' ``` -Przed uruchomieniem polecenia zastąp te wartości: +Zastąp te wartości przed uruchomieniem polecenia: -- `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 +- `https://matrix.example.org`: bazowy URL Twojego homeservera +- `$USER_ACCESS_TOKEN`: token dostępu użytkownika odbierającego +- `openclaw-finalized-preview-botname`: ID reguły unikalne dla tego bota dla tego użytkownika odbierającego +- `@bot:example.org`: MXID Twojego bota Matrix OpenClaw, a nie MXID użytkownika odbierającego -Ważne dla konfiguracji z wieloma botami: +Ważne w konfiguracjach z wieloma botami: -- Reguły push są kluczowane według `ruleId`. Ponowne uruchomienie `PUT` względem tego samego ID reguły aktualizuje tę jedną regułę. +- Reguły push są identyfikowane przez `ruleId`. Ponowne uruchomienie `PUT` dla 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`. @@ -385,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 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. +7. Przetestuj odpowiedź strumieniowaną. W trybie cichym pokój powinien wyświetlić cichy szkic podglądu, a końcowa + edycja w miejscu powinna wysłać powiadomienie po zakończeniu bloku lub tury. -Jeśli później będziesz potrzebować usunąć regułę, usuń to samo ID reguły tokenem użytkownika odbierającego: +Jeśli później będziesz musiał usunąć regułę, usuń to samo ID reguły tokenem użytkownika odbierającego: ```bash curl -sS -X DELETE \ @@ -398,33 +398,33 @@ curl -sS -X DELETE \ Uwagi: -- 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 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. +- Utwórz regułę przy użyciu tokenu dostępu użytkownika odbierającego, a nie tokenu bota. +- Nowe reguły `override` zdefiniowane przez użytkownika są wstawiane przed domyślnymi regułami tłumiącymi, więc nie jest potrzebny dodatkowy parametr kolejności. +- Dotyczy to tylko edycji podglądu wyłącznie tekstowego, które OpenClaw może bezpiecznie sfinalizować w miejscu. Awaryjne przełączenia dla multimediów i nieaktualnych podglądów nadal używają zwykłego 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. #### Synapse W przypadku Synapse powyższa konfiguracja zwykle sama w sobie wystarcza: -- Nie jest wymagana żadna specjalna zmiana w `homeserver.yaml` dla sfinalizowanych powiadomień podglądu OpenClaw. +- Nie jest wymagana żadna specjalna zmiana w `homeserver.yaml` dla powiadomień o sfinalizowanych podglądach 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. +- Jeśli uruchamiasz Synapse za reverse proxy lub workerami, upewnij się, że `/_matrix/client/.../pushrules/` poprawnie trafia do Synapse. +- Jeśli używasz workerów Synapse, upewnij się, że pushery działają prawidłowo. Dostarczanie powiadomień push jest obsługiwane przez proces główny lub `synapse.app.pusher` / skonfigurowane workery pusherów. #### Tuwunel -W przypadku Tuwunel użyj tego samego przebiegu konfiguracji i wywołania API `pushrules`, które pokazano powyżej: +W przypadku Tuwunel użyj tego samego przepływu konfiguracji i wywołania API `pushrules`, które pokazano powyżej: - 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. +- Jeśli wygląda na to, ż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 tłumić powiadomienia push do innych urządzeń, gdy jedno urządzenie jest aktywne. ## Pokoje bot-do-bota Domyślnie wiadomości Matrix z innych skonfigurowanych kont Matrix OpenClaw są ignorowane. -Użyj `allowBots`, jeśli celowo chcesz dopuścić ruch Matrix między agentami: +Użyj `allowBots`, jeśli celowo chcesz zezwolić na ruch Matrix między agentami: ```json5 { @@ -441,17 +441,17 @@ Użyj `allowBots`, jeśli celowo chcesz dopuścić ruch Matrix między agentami: } ``` -- `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. +- `allowBots: true` akceptuje wiadomości z innych skonfigurowanych kont botów Matrix w dozwolonych pokojach i DM-ach. +- `allowBots: "mentions"` akceptuje te wiadomości tylko wtedy, gdy w pokojach wyraźnie wspominają tego bota. DM-y są nadal dozwolone. +- `groups..allowBots` zastępuje ustawienie na poziomie konta dla jednego pokoju. - 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”. +- Matrix nie udostępnia tutaj natywnej flagi bota; OpenClaw traktuje „napisane przez bota” jako „wysłane przez inne skonfigurowane konto Matrix na tej bramie OpenClaw”. -Używaj ścisłych allowlist pokoi i wymagań wzmianki podczas włączania ruchu bot-do-bota we współdzielonych pokojach. +Używaj ścisłych list dozwolonych pokoi i wymagań dotyczących wzmianek 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 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 — Plugin automatycznie wykrywa stan E2EE. Włącz szyfrowanie: @@ -481,7 +481,7 @@ Szczegółowy status (pełna diagnostyka): openclaw matrix verify status --verbose ``` -Uwzględnij zapisany klucz odzyskiwania w wyjściu do odczytu maszynowego: +Uwzględnij zapisany klucz odzyskiwania w wyjściu czytelnym maszynowo: ```bash openclaw matrix verify status --include-recovery-key --json @@ -493,13 +493,13 @@ Zainicjalizuj cross-signing i stan weryfikacji: openclaw matrix verify bootstrap ``` -Szczegółowa diagnostyka bootstrap: +Szczegółowa diagnostyka bootstrapu: ```bash openclaw matrix verify bootstrap --verbose ``` -Wymuś reset tożsamości cross-signing przed bootstrapem: +Wymuś nowy reset tożsamości cross-signing przed bootstrapem: ```bash openclaw matrix verify bootstrap --force-reset-cross-signing @@ -541,18 +541,18 @@ Szczegółowa diagnostyka przywracania: openclaw matrix verify backup restore --verbose ``` -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: +Usuń bieżącą kopię zapasową serwera i utwórz nową bazę kopii zapasowej. Jeśli zapisany +klucz kopii zapasowej nie może zostać poprawnie załadowany, ten reset może również odtworzyć sekretne przechowywanie, tak aby +przyszłe zimne uruchomienia mogły załadować nowy klucz kopii zapasowej: ```bash openclaw matrix verify backup reset --yes ``` -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. +Wszystkie polecenia `verify` są domyślnie zwięzłe (łącznie z cichym wewnętrznym logowaniem SDK) i pokazują szczegółową diagnostykę tylko z `--verbose`. +Użyj `--json`, aby uzyskać pełne wyjście czytelne maszynowo podczas skryptowania. -W konfiguracjach wielokontowych polecenia Matrix CLI używają domyślnego niejawnego konta Matrix, chyba że przekażesz `--account `. +W konfiguracjach wielokontowych polecenia CLI Matrix używają niejawnego domyślnego 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ądzeń były jawnie kierowane do nazwanego konta: @@ -562,39 +562,39 @@ 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ą 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ą na 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 jest ono zweryfikowane przez Twoją własną tożsamość cross-signing. +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` pokazuje trzy sygnały zaufania: - `Locally trusted`: to urządzenie jest zaufane tylko przez bieżącego klienta - `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 +- `Signed by owner`: urządzenie jest podpisane Twoim własnym kluczem self-signing -`Verified by owner` przyjmuje wartość `yes` tylko wtedy, gdy istnieje weryfikacja cross-signing lub podpis właściciela. +`Verified by owner` przyjmuje wartość `yes` tylko wtedy, gdy obecna jest 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 szyfrowanych kont Matrix. -Wykonuje kolejno wszystkie poniższe czynności: +`openclaw matrix verify bootstrap` to polecenie naprawy i konfiguracji dla zaszyfrowanych kont Matrix. +Wykonuje kolejno wszystkie poniższe działania: -- inicjalizuje secret storage, ponownie używając istniejącego klucza odzyskiwania, gdy to możliwe +- inicjalizuje sekretne przechowywanie, 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 +- próbuje oznaczyć i podpisać bieżące urządzenie metodą cross-signing +- tworzy nową kopię zapasową kluczy pokojów po stronie serwera, jeśli taka jeszcze nie istnieje -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`. +Jeśli homeserver wymaga interaktywnego uwierzytelniania do przesłania kluczy cross-signing, OpenClaw najpierw próbuje przesłać je 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 świadomie chcesz odrzucić bieżącą tożsamość cross-signing i utworzyć nową. +Używaj `--force-reset-cross-signing` tylko wtedy, gdy celowo chcesz odrzucić bieżącą tożsamość cross-signing i utworzyć nową. -Jeśli świadomie chcesz porzucić bieżącą kopię zapasową kluczy pokojów i rozpocząć nową +Jeśli celowo chcesz odrzucić 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 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ć. +Rób to tylko wtedy, gdy akceptujesz, że nieodzyskiwalna stara zaszyfrowana historia pozostanie +niedostępna i że OpenClaw może odtworzyć sekretne przechowywanie, jeśli bieżący sekret +kopii zapasowej nie może zostać bezpiecznie załadowany. ### Nowa baza kopii zapasowej @@ -606,54 +606,54 @@ openclaw matrix verify backup status --verbose openclaw matrix verify status ``` -Dodaj `--account ` do każdego polecenia, jeśli chcesz jawnie wskazać nazwane konto Matrix. +Dodaj `--account ` do każdego polecenia, gdy chcesz jawnie wskazać nazwane konto Matrix. ### Zachowanie przy uruchamianiu 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`, +Przy uruchamianiu, jeśli to urządzenie nadal nie jest zweryfikowane, Matrix zażąda samoweryfikacji w innym kliencie Matrix, +pominie duplikaty żądań, jeśli jedno już oczekuje, i zastosuje lokalny czas odczekania przed ponowną próbą po restartach. +Domyślnie próby żądań zakończone niepowodzeniem są ponawiane szybciej niż pomyślne utworzenie żądania. +Ustaw `startupVerification: "off"`, aby wyłączyć automatyczne żądania przy uruchamianiu, albo dostosuj `startupVerificationCooldownHours`, jeśli chcesz krótsze lub dłuższe okno ponawiania. -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. +Przy uruchamianiu automatycznie wykonywany jest także zachowawczy przebieg bootstrapu kryptograficznego. +Najpierw próbuje on ponownie użyć bieżącego sekretnego przechowywania i tożsamości cross-signing oraz unika resetowania cross-signing, chyba że uruchomisz jawny przepływ naprawy bootstrapu. -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. +Jeśli podczas uruchamiania zostanie wykryty uszkodzony stan bootstrapu 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 zachowa tę tożsamość zamiast resetować ją automatycznie. -Zobacz [Migracja Matrix](/pl/install/migrating-matrix), aby poznać pełny przebieg aktualizacji, ograniczenia, polecenia odzyskiwania i typowe komunikaty migracyjne. +Zobacz [migrację Matrix](/pl/install/migrating-matrix), aby poznać pełny przepływ aktualizacji, ograniczenia, polecenia odzyskiwania i typowe komunikaty migracji. -### Komunikaty weryfikacji +### Powiadomienia o weryfikacji -Matrix publikuje komunikaty dotyczące cyklu życia weryfikacji bezpośrednio w ścisłym pokoju wiadomości prywatnych do weryfikacji jako wiadomości `m.notice`. +Matrix publikuje powiadomienia o cyklu życia weryfikacji bezpośrednio w ścisłym pokoju DM 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 +- powiadomienia o żądaniu weryfikacji +- powiadomienia o gotowości do weryfikacji (z jawną wskazówką „Zweryfikuj za pomocą 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 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ą”. +W przypadku przepływów samoweryfikacji OpenClaw automatycznie uruchamia też 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 przebiegał normalnie. +Nadal musisz porównać emoji lub dziesiętny SAS w swoim kliencie Matrix i potwierdzić tam „Pasują”, aby zakończyć weryfikację. -OpenClaw nie akceptuje bezrefleksyjnie samoinicjowanych zduplikowanych przepływów. Przy uruchamianiu pomijane jest tworzenie nowego żądania, jeśli żądanie samoweryfikacji jest już oczekujące. +OpenClaw nie akceptuje ślepo automatycznie duplikatów przepływów zainicjowanych samodzielnie. Przy uruchamianiu pomijane jest tworzenie nowego żądania, jeśli żądanie samoweryfikacji już oczekuje. -Komunikaty protokołowe/systemowe weryfikacji nie są przekazywane do potoku czatu agenta, więc nie powodują `NO_REPLY`. +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 ocenę zaufania w szyfrowanych pokojach. -Wyświetl ich listę za pomocą: +Stare urządzenia Matrix zarządzane przez OpenClaw mogą gromadzić się na koncie i utrudniać ocenę zaufania w zaszyfrowanych pokojach. +Wyświetl je poleceniem: ```bash openclaw matrix devices list ``` -Usuń nieaktualne urządzenia zarządzane przez OpenClaw za pomocą: +Usuń nieaktualne urządzenia Matrix zarządzane przez OpenClaw poleceniem: ```bash openclaw matrix devices prune-stale @@ -661,16 +661,16 @@ 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. +Matrix E2EE używa oficjalnej ścieżki Rust crypto 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 przy uruchamianiu. Plik migawki to wrażliwy stan środowiska uruchomieniowego przechowywany z restrykcyjnymi uprawnieniami do pliku. -Zaszyfrowany stan czasu działania znajduje się w katalogach per konto i per hash tokena użytkownika w +Zaszyfrowany stan środowiska uruchomieniowego znajduje się w korzeniach per konto, per użytkownik, per hash tokenu w `~/.openclaw/matrix/accounts//__//`. 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`) 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. +korzenia dla 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ą widoczne. ## Zarządzanie profilem @@ -681,39 +681,39 @@ openclaw matrix profile set --name "OpenClaw Assistant" openclaw matrix profile set --avatar-url https://cdn.example.org/avatar.png ``` -Dodaj `--account `, jeśli chcesz jawnie wskazać nazwane konto Matrix. +Dodaj `--account `, gdy chcesz jawnie wskazać nazwane konto Matrix. -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). +Matrix akceptuje bezpośrednio adresy URL awatarów `mxc://`. Gdy przekażesz adres URL awatara `http://` lub `https://`, OpenClaw najpierw przesyła go do Matrix, a następnie zapisuje rozwiązany adres URL `mxc://` z powrotem do `channels.matrix.avatarUrl` (lub wybranego nadpisania konta). ## Wątki -Matrix obsługuje natywne wątki Matrix zarówno dla odpowiedzi automatycznych, jak i wysyłek przez narzędzie wiadomości. +Matrix obsługuje natywne wątki Matrix zarówno dla odpowiedzi automatycznych, jak i wysyłek przez narzędzia wiadomości. -- `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. +- `dm.sessionScope: "per-user"` (domyślnie) utrzymuje routowanie DM Matrix w zakresie nadawcy, więc wiele pokoi DM może współdzielić jedną sesję, jeśli rozwiązują się do tego samego partnera. +- `dm.sessionScope: "per-room"` izoluje każdy pokój DM Matrix do własnego klucza sesji, nadal używając zwykłego uwierzytelniania DM i kontroli listy dozwolonych. - 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`. +- `threadReplies: "off"` utrzymuje odpowiedzi na poziomie głównym i zachowuje przychodzące wiadomości we wątkach w sesji nadrzędnej. +- `threadReplies: "inbound"` odpowiada wewnątrz wątku tylko wtedy, gdy przychodząca wiadomość już była w tym wątku. +- `threadReplies: "always"` utrzymuje odpowiedzi w pokojach we wątku zakorzenionym w wiadomości wyzwalającej i kieruje tę konwersację przez pasującą sesję o zakresie wątku od pierwszej wiadomości wyzwalającej. +- `dm.threadReplies` zastępuje ustawienie najwyższego poziomu tylko dla DM. Na przykład możesz utrzymać izolację wątków pokojów, a DM-y pozostawić płaskie. +- Przychodzące wiadomości we wątkach zawierają główną wiadomość wątku jako dodatkowy kontekst agenta. +- Wysyłki przez narzędzia wiadomości automatycznie dziedziczą bieżący wątek Matrix, gdy celem jest ten sam pokój lub ten sam cel użytkownika DM, chyba że podano jawne `threadId`. +- Ponowne użycie celu użytkownika DM w tej samej sesji działa tylko wtedy, gdy metadane bieżącej sesji potwierdzają tego samego partnera DM na tym samym koncie Matrix; w przeciwnym razie OpenClaw wraca do zwykłego routowania w zakresie użytkownika. +- Gdy OpenClaw wykryje, że pokój DM Matrix koliduje z innym pokojem DM w tej samej współdzielonej sesji DM Matrix, publikuje w tym pokoju jednorazowe `m.notice` z furtką `/focus`, gdy powiązania wątków są włączone, oraz wskazówką `dm.sessionScope`. +- Powiązania wątków środowiska uruchomieniowego są obsługiwane w Matrix. `/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age` oraz związane z wątkami `/acp spawn` działają w pokojach i DM-ach Matrix. +- Polecenie `/focus` na najwyższym poziomie 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 mogą zostać przekształcone w trwałe przestrzenie robocze ACP bez zmiany powierzchni czatu. +Pokoje, DM-y i istniejące wątki Matrix można przekształcić 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 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. +- Uruchom `/acp spawn codex --bind here` wewnątrz DM Matrix, pokoju lub istniejącego wątku, którego chcesz dalej używać. +- W DM lub pokoju Matrix na najwyższym poziomie bieżący DM/pokój pozostaje powierzchnią czatu, a przyszłe wiadomości są kierowane do utworzonej sesji ACP. +- Wewnątrz istniejącego wątku Matrix `--bind here` wiąże bieżący wątek w miejscu. +- `/new` i `/reset` resetują tę samą powiązaną sesję ACP w miejscu. - `/acp close` zamyka sesję ACP i usuwa powiązanie. Uwagi: @@ -723,7 +723,7 @@ Uwagi: ### Konfiguracja powiązań wątków -Matrix dziedziczy globalne ustawienia domyślne z `session.threadBindings`, a także obsługuje nadpisania per kanał: +Matrix dziedziczy globalne wartości domyślne z `session.threadBindings`, a także obsługuje nadpisania per kanał: - `threadBindings.enabled` - `threadBindings.idleHours` @@ -731,35 +731,35 @@ Matrix dziedziczy globalne ustawienia domyślne z `session.threadBindings`, a ta - `threadBindings.spawnSubagentSessions` - `threadBindings.spawnAcpSessions` -Flagi uruchamiania powiązane z wątkami Matrix są opt-in: +Flagi uruchamiania związane z wątkami Matrix są opcjonalne: -- 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. +- Ustaw `threadBindings.spawnSubagentSessions: true`, aby zezwolić, by `/focus` na najwyższym poziomie tworzył i wiązał nowe wątki Matrix. +- Ustaw `threadBindings.spawnAcpSessions: true`, aby zezwolić, by `/acp spawn --thread auto|here` wiązał sesje ACP z wątkami Matrix. ## Reakcje -Matrix obsługuje wychodzące akcje reakcji, przychodzące powiadomienia o reakcjach oraz przychodzące reakcje potwierdzeń. +Matrix obsługuje wychodzące akcje reakcji, przychodzące powiadomienia o reakcjach oraz przychodzące reakcje potwierdzenia. -- 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 tylko wskazaną reakcję emoji z konta bota. +- Narzędzia wychodzących reakcji są kontrolowane przez `channels["matrix"].actions.reactions`. +- `react` dodaje reakcję do określonego zdarzenia Matrix. +- `reactions` wyświetla bieżące podsumowanie reakcji dla określonego zdarzenia Matrix. +- `emoji=""` usuwa własne reakcje konta bota dla tego zdarzenia. +- `remove: true` usuwa tylko określoną reakcję emoji z konta bota. -Zakres wyszukiwania reakcji potwierdzeń jest rozstrzygany według standardowej kolejności OpenClaw: +Zakres reakcji potwierdzenia jest rozwiązywany według standardowej kolejności OpenClaw: - `channels["matrix"].accounts..ackReaction` - `channels["matrix"].ackReaction` - `messages.ackReaction` -- fallback do emoji tożsamości agenta +- emoji tożsamości agenta jako wartość zapasowa -Zakres reakcji potwierdzeń jest rozstrzygany w tej kolejności: +Zakres reakcji potwierdzenia jest rozwiązywany w tej kolejności: - `channels["matrix"].accounts..ackReactionScope` - `channels["matrix"].ackReactionScope` - `messages.ackReactionScope` -Tryb powiadomień o reakcjach jest rozstrzygany w tej kolejności: +Tryb powiadomień o reakcjach jest rozwiązywany w tej kolejności: - `channels["matrix"].accounts..reactionNotifications` - `channels["matrix"].reactionNotifications` @@ -767,30 +767,30 @@ Tryb powiadomień o reakcjach jest rozstrzygany w tej kolejności: Zachowanie: -- `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 nie są syntetyzowane do zdarzeń systemowych, ponieważ Matrix pokazuje je jako redakcje, a nie jako samodzielne usunięcia `m.reaction`. +- `reactionNotifications: "own"` przekazuje dodane zdarzenia `m.reaction`, gdy są skierowane do wiadomości Matrix napisanych przez bota. +- `reactionNotifications: "off"` wyłącza zdarzenia systemowe reakcji. +- Usunięcia reakcji nie są syntetyzowane do zdarzeń systemowych, ponieważ Matrix przedstawia je jako redakcje, a nie jako samodzielne usunięcia `m.reaction`. ## Kontekst historii -- `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 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. +- `channels.matrix.historyLimit` określa, ile ostatnich wiadomości z pokoju jest dołączanych jako `InboundHistory`, gdy wiadomość w pokoju Matrix wyzwala agenta. Wartość zapasowa pochodzi z `messages.groupChat.historyLimit`; jeśli oba ustawienia są nieustawione, efektywna wartość domyślna to `0`. Ustaw `0`, aby wyłączyć. +- Historia pokoju Matrix dotyczy tylko pokoju. DM-y nadal używają zwykłej historii sesji. +- Historia pokoju Matrix dotyczy tylko oczekujących wiadomości: OpenClaw buforuje wiadomości z pokoju, które jeszcze nie wywołały odpowiedzi, a następnie wykonuje migawkę tego okna, gdy nadejdzie wzmianka lub inny wyzwalacz. +- Bieżąca wiadomość wyzwalająca nie jest uwzględniana w `InboundHistory`; pozostaje w głównej treści wejściowej tej tury. +- Ponowne próby tego samego zdarzenia Matrix ponownie używają oryginalnej migawki historii zamiast przesuwać się naprzód do nowszych wiadomości z pokoju. ## Widoczność kontekstu -Matrix obsługuje współdzieloną kontrolę `contextVisibility` dla dodatkowego kontekstu pokoju, takiego jak pobrany tekst odpowiedzi, korzenie wątków i oczekująca historia. +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. -- `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: "all"` jest wartością domyślną. Uzupełniający kontekst jest zachowywany bez zmian. +- `contextVisibility: "allowlist"` filtruje uzupełniający kontekst do nadawców dozwolonych przez aktywne kontrole listy dozwolonych pokoju/użytkownika. - `contextVisibility: "allowlist_quote"` działa jak `allowlist`, ale nadal zachowuje jedną jawną cytowaną odpowiedź. -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. +To ustawienie wpływa na widoczność uzupełniającego kontekstu, a nie na to, czy sama wiadomość przychodząca może wywołać odpowiedź. +Autoryzacja wyzwalacza nadal pochodzi z ustawień `groupPolicy`, `groups`, `groupAllowFrom` i polityki DM. -## Zasady wiadomości prywatnych i pokoi +## Zasady DM i pokoi ```json5 { @@ -813,22 +813,22 @@ Autoryzacja triggera nadal wynika z ustawień `groupPolicy`, `groups`, `groupAll } ``` -Zobacz [Grupy](/pl/channels/groups), aby poznać zachowanie związane z wymaganiem wzmianki i allowlistą. +Zobacz [Groups](/pl/channels/groups), aby poznać działanie bramkowania wzmiankami i listy dozwolonych. -Przykład parowania dla wiadomości prywatnych Matrix: +Przykład parowania dla DM-ów Matrix: ```bash openclaw pairing list matrix openclaw pairing approve matrix ``` -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. +Jeśli niezatwierdzony użytkownik Matrix będzie nadal wysyłać Ci wiadomości przed zatwierdzeniem, OpenClaw ponownie użyje tego samego oczekującego kodu parowania i może ponownie wysłać odpowiedź-przypomnienie po krótkim czasie odczekania zamiast generować nowy kod. -Zobacz [Parowanie](/pl/channels/pairing), aby poznać współdzielony przepływ parowania wiadomości prywatnych i układ przechowywania. +Zobacz [Pairing](/pl/channels/pairing), aby poznać współdzielony przepływ parowania DM i układ pamięci. -## Naprawa bezpośredniego pokoju +## Naprawa pokoju bezpośredniego -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ą: +Jeśli stan wiadomości bezpośrednich ulegnie rozjechaniu, OpenClaw może skończyć ze starymi mapowaniami `m.direct`, które wskazują na stare pokoje solo zamiast na aktywny DM. Sprawdź bieżące mapowanie dla partnera za pomocą: ```bash openclaw matrix direct inspect --user-id @alice:example.org @@ -842,53 +842,53 @@ 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 +- preferuje ścisły DM 1:1, który jest już zmapowany w `m.direct` +- w przeciwnym razie wybiera dowolny aktualnie dołączony ścisły DM 1:1 z tym użytkownikiem +- tworzy nowy pokój bezpośredni 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. +Przepływ naprawy nie usuwa automatycznie starych pokoi. Wybiera tylko zdrowy DM i aktualizuje mapowanie, 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. ## Zatwierdzenia exec Matrix może działać jako natywny klient zatwierdzeń dla konta Matrix. Natywne -przełączniki routingu wiadomości prywatnych/kanałów nadal znajdują się w konfiguracji zatwierdzeń exec: +ustawienia routowania DM/kanału nadal znajdują się w konfiguracji zatwierdzeń exec: - `channels.matrix.execApprovals.enabled` -- `channels.matrix.execApprovals.approvers` (opcjonalnie; fallback do `channels.matrix.dm.allowFrom`) +- `channels.matrix.execApprovals.approvers` (opcjonalnie; wartość zapasowa to `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` 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ń. +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ą wrócić do `channels.matrix.dm.allowFrom`. Zatwierdzenia Pluginów 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 ścieżek zatwierdzania lub zasad awaryjnych zatwierdzeń. -Natywne routowanie Matrix obsługuje oba typy zatwierdzeń: +Natywne routowanie Matrix obsługuje oba rodzaje zatwierdzeń: -- `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ą 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. +- `channels.matrix.execApprovals.*` kontroluje natywny tryb rozsyłania DM/kanału dla promptów zatwierdzeń Matrix. +- Zatwierdzenia exec używają zestawu zatwierdzających exec z `execApprovals.approvers` lub `channels.matrix.dm.allowFrom`. +- Zatwierdzenia Pluginów używają listy dozwolonych DM Matrix z `channels.matrix.dm.allowFrom`. +- Skróty reakcji Matrix i aktualizacje wiadomości mają zastosowanie zarówno do zatwierdzeń exec, jak i Pluginów. 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 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 +- `target: "dm"` wysyła prompty zatwierdzeń do DM-ów zatwierdzających +- `target: "channel"` wysyła prompt z powrotem do źródłowego pokoju lub DM Matrix +- `target: "both"` wysyła do DM-ów zatwierdzających oraz do źródłowego pokoju lub DM Matrix -Prompty zatwierdzeń Matrix inicjalizują skróty reakcji na głównej wiadomości zatwierdzenia: +Prompty zatwierdzeń Matrix inicjalizują skróty reakcji w głównej wiadomości zatwierdzenia: -- `✅` = zezwól raz -- `❌` = odrzuć +- `✅` = zezwól jednorazowo +- `❌` = odmów - `♾️` = zezwól zawsze, gdy taka decyzja jest dozwolona przez efektywną politykę exec -Zatwierdzający mogą zareagować na tę wiadomość lub użyć zapasowych poleceń ukośnikowych: `/approve allow-once`, `/approve allow-always` albo `/approve deny`. +Zatwierdzający mogą reagować na tę wiadomość lub używać zapasowych poleceń slash: `/approve allow-once`, `/approve allow-always` albo `/approve deny`. -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. +Tylko rozwiązani zatwierdzający mogą zatwierdzać lub odmawiać. W przypadku zatwierdzeń exec dostarczanie kanałowe zawiera tekst polecenia, więc włączaj `channel` lub `both` tylko w zaufanych pokojach. Nadpisanie per konto: - `channels.matrix.accounts..execApprovals` -Powiązana dokumentacja: [Zatwierdzenia exec](/pl/tools/exec-approvals) +Powiązana dokumentacja: [Exec approvals](/pl/tools/exec-approvals) ## Wiele kont @@ -920,23 +920,24 @@ Powiązana dokumentacja: [Zatwierdzenia exec](/pl/tools/exec-approvals) } ``` -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. +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ć dziedziczone wpisy pokoi do jednego konta Matrix za pomocą `groups..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 domyślne ustawienia uwierzytelniania same z siebie nie tworzą osobnego niejawnego konta domyślnego. OpenClaw syntetyzuje konto najwyższego poziomu `default` tylko wtedy, gdy to konto domyślne ma aktualne uwierzytelnianie (`homeserver` plus `accessToken` albo `homeserver` plus `userId` i `password`); nazwane konta mogą nadal pozostać wykrywalne z `homeserver` plus `userId`, gdy buforowane 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 kont zachowuje to konto zamiast tworzyć nowy wpis `accounts.default`. Tylko klucze uwierzytelniania/bootstrapu 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 dla niejawnego routowania, sondowania i operacji CLI. +Jeśli skonfigurowano wiele kont Matrix i jedno ID konta to `default`, OpenClaw używa tego konta niejawnie, nawet jeśli `defaultAccount` nie jest ustawione. +Jeśli skonfigurujesz wiele nazwanych kont, ustaw `defaultAccount` albo przekazuj `--account ` dla poleceń CLI, które opierają się na niejawnym wyborze konta. +Przekazuj `--account ` do `openclaw matrix verify ...` i `openclaw matrix devices ...`, gdy 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. +Zobacz [Configuration reference](/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 w celu ochrony przed SSRF, chyba że -jawnie włączysz je per konto. +Domyślnie OpenClaw blokuje prywatne/wewnętrzne homeservery Matrix jako ochronę przed SSRF, chyba że +jawnie włączysz zgodę 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 IP LAN/Tailscale albo wewnętrznej nazwie hosta, włącz `network.dangerouslyAllowPrivateNetwork` dla tego konta Matrix: ```json5 @@ -963,12 +964,12 @@ openclaw matrix account add \ --access-token syt_ops_xxx ``` -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://`. +Ta zgoda obejmuje tylko zaufane cele prywatne/wewnętrzne. Publiczne homeservery cleartext, takie jak +`http://matrix.example.org:8008`, pozostają zablokowane. Jeśli to możliwe, preferuj `https://`. -## Proxy dla ruchu Matrix +## Przekazywanie ruchu Matrix przez proxy -Jeśli wdrożenie Matrix wymaga jawnego wychodzącego proxy HTTP(S), ustaw `channels.matrix.proxy`: +Jeśli Twoje wdrożenie Matrix wymaga jawnego wychodzącego proxy HTTP(S), ustaw `channels.matrix.proxy`: ```json5 { @@ -982,86 +983,86 @@ Jeśli wdrożenie Matrix wymaga jawnego wychodzącego proxy HTTP(S), ustaw `chan } ``` -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. +Nazwane konta mogą nadpisywać domyślną wartość najwyższego poziomu za pomocą `channels.matrix.accounts..proxy`. +OpenClaw używa tego samego ustawienia proxy dla ruchu Matrix w środowisku uruchomieniowym oraz dla sond statusu konta. ## Rozwiązywanie celów -Matrix akceptuje następujące formy celu wszędzie tam, gdzie OpenClaw prosi o pokój lub cel użytkownika: +Matrix akceptuje te formy celów wszędzie tam, gdzie OpenClaw prosi o cel pokoju lub 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 w katalogu na żywo używa zalogowanego konta Matrix: +Wyszukiwanie na żywo w katalogu używa zalogowanego konta Matrix: -- 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. +- Wyszukiwania użytkowników odpytują katalog użytkowników Matrix na tym homeserverze. +- Wyszukiwania pokoi bezpośrednio akceptują jawne ID pokoi i aliasy, a następnie wracają do przeszukiwania nazw dołączonych pokoi dla tego konta. +- Wyszukiwanie nazw dołączonych pokoi jest best-effort. Jeśli nazwy pokoju nie można rozwiązać do ID ani aliasu, jest ona ignorowana podczas rozwiązywania listy dozwolonych w środowisku uruchomieniowym. -## Dokumentacja referencyjna konfiguracji +## Dokumentacja konfiguracji - `enabled`: włącza lub wyłącza kanał. - `name`: opcjonalna etykieta konta. - `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 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`. +- `network.dangerouslyAllowPrivateNetwork`: pozwala temu kontu Matrix łączyć się z prywatnymi/wewnętrznymi homeserverami. Włącz to, gdy homeserver rozwiązuje się do `localhost`, adresu IP LAN/Tailscale lub wewnętrznego hosta, takiego jak `matrix-synapse`. +- `proxy`: opcjonalny URL proxy HTTP(S) dla ruchu Matrix. Nazwane konta mogą nadpisywać domyślną wartość 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. +- `accessToken`: token dostępu dla uwierzytelniania opartego na tokenie. Dla `channels.matrix.accessToken` oraz `channels.matrix.accounts..accessToken` obsługiwane są zwykłe wartości tekstowe i wartości SecretRef w providerach env/file/exec. Zobacz [Secrets Management](/pl/gateway/secrets). +- `password`: hasło dla logowania opartego na haśle. Obsługiwane są zwykłe wartości tekstowe i wartości SecretRef. - `deviceId`: jawne ID urządzenia Matrix. -- `deviceName`: nazwa wyświetlana urządzenia przy logowaniu hasłem. +- `deviceName`: nazwa wyświetlana urządzenia dla logowania 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`: 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`. +- `allowlistOnly`: gdy ma wartość `true`, podnosi politykę pokoi `open` do `allowlist` i wymusza dla wszystkich aktywnych polityk DM poza `disabled` (w tym `pairing` i `open`) wartość `allowlist`. Nie wpływa na polityki `disabled`. +- `allowBots`: zezwala na wiadomości z 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 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 do uwzględnienia jako kontekst historii grupy. Wartość zapasowa pochodzi z `messages.groupChat.historyLimit`; jeśli oba ustawienia są nieustawione, efektywna wartość domyślna to `0`. Ustaw `0`, aby wyłączyć. +- `replyToMode`: `off`, `first`, `all` albo `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 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`). +- `streaming`: `off` (domyślnie), `"partial"`, `"quiet"`, `true` albo `false`. `"partial"` i `true` włączają aktualizacje szkicu „najpierw podgląd” przy użyciu zwykłych wiadomości tekstowych Matrix. `"quiet"` używa podglądów notice bez powiadomień dla samohostowanych konfiguracji reguł push. `false` jest równoważne z `"off"`. +- `blockStreaming`: `true` włącza oddzielne komunikaty postępu dla ukończonych bloków odpowiedzi asystenta, gdy aktywne jest strumieniowanie szkicu podglądu. +- `threadReplies`: `off`, `inbound` albo `always`. +- `threadBindings`: nadpisania per kanał dla routowania sesji związanych z wątkami i ich cyklu życia. +- `startupVerification`: tryb automatycznego żądania samoweryfikacji przy uruchamianiu (`if-unverified`, `off`). +- `startupVerificationCooldownHours`: czas odczekania przed ponowną próbą automatycznych żądań weryfikacji przy uruchamianiu. +- `textChunkLimit`: rozmiar fragmentu wiadomości wychodzącej w znakach (ma zastosowanie, gdy `chunkMode` to `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. +- `responsePrefix`: opcjonalny ciąg poprzedzający wszystkie odpowiedzi wychodzące 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`). +- `reactionNotifications`: tryb powiadomień o reakcjach przychodzących (`own`, `off`). - `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. +- `autoJoin`: polityka automatycznego dołączania do zaproszeń (`always`, `allowlist`, `off`). Domyślnie: `off`. Dotyczy wszystkich zaproszeń Matrix, w tym zaproszeń w stylu DM. - `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 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. +- `dm`: blok polityki DM (`enabled`, `policy`, `allowFrom`, `sessionScope`, `threadReplies`). +- `dm.policy`: kontroluje dostęp do DM po tym, jak OpenClaw dołączył do pokoju i sklasyfikował go jako DM. Nie zmienia tego, czy zaproszenie jest automatycznie przyjmowane. +- `dm.allowFrom`: wpisy powinny być pełnymi ID użytkowników Matrix, chyba że zostały już rozwiązane przez wyszukiwanie katalogowe na żywo. +- `dm.sessionScope`: `per-user` (domyślnie) albo `per-room`. Użyj `per-room`, gdy chcesz, aby każdy pokój DM Matrix zachowywał osobny kontekst, nawet jeśli partner jest ten sam. +- `dm.threadReplies`: nadpisanie polityki wątków tylko dla DM (`off`, `inbound`, `always`). Nadpisuje ustawienie najwyższego poziomu `threadReplies` zarówno dla umiejscowienia odpowiedzi, jak i izolacji sesji w DM-ach. +- `execApprovals`: natywne dostarczanie zatwierdzeń exec Matrix (`enabled`, `approvers`, `target`, `agentFilter`, `sessionFilter`). +- `execApprovals.approvers`: ID użytkowników Matrix uprawnionych do zatwierdzania żądań 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 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`: 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..allowBots`: nadpisanie na poziomie pokoju dla nadawców będących skonfigurowanymi botami (`true` albo `"mentions"`). +- `groups..users`: lista dozwolonych nadawców per pokój. +- `groups..tools`: nadpisania zezwalania/zabraniania narzędzi per pokój. +- `groups..autoReply`: nadpisanie na poziomie pokoju dla bramkowania wzmiankami. `true` wyłącza wymagania dotyczące wzmianek dla tego pokoju; `false` wymusza ich ponowne włączenie. - `groups..skills`: opcjonalny filtr Skills na poziomie pokoju. -- `groups..systemPrompt`: opcjonalny fragment system promptu na poziomie pokoju. +- `groups..systemPrompt`: opcjonalny fragment systemPrompt na poziomie pokoju. - `rooms`: starszy alias dla `groups`. -- `actions`: kontrola użycia narzędzi per akcja (`messages`, `reactions`, `pins`, `profile`, `memberInfo`, `channelInfo`, `verification`). +- `actions`: bramkowanie 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 wymaganie wzmianki -- [Routing kanałów](/pl/channels/channel-routing) — routing sesji dla wiadomości -- [Bezpieczeństwo](/pl/gateway/security) — model dostępu i utwardzanie +- [Channels Overview](/pl/channels) — wszystkie obsługiwane kanały +- [Pairing](/pl/channels/pairing) — uwierzytelnianie DM i przepływ parowania +- [Groups](/pl/channels/groups) — zachowanie czatu grupowego i bramkowanie wzmiankami +- [Channel Routing](/pl/channels/channel-routing) — routowanie sesji dla wiadomości +- [Security](/pl/gateway/security) — model dostępu i utwardzanie diff --git a/docs/pl/concepts/dreaming.md b/docs/pl/concepts/dreaming.md index 23394dab9..bc95f1e48 100644 --- a/docs/pl/concepts/dreaming.md +++ b/docs/pl/concepts/dreaming.md @@ -1,35 +1,35 @@ --- read_when: - - Chcesz, aby promowanie pamięci uruchamiało się automatycznie - - Chcesz zrozumieć, co robi każda faza dreaming + - Chcesz, aby promocja pamięci uruchamiała się automatycznie + - Chcesz zrozumieć, co robi każda faza Dreaming - Chcesz dostroić konsolidację bez zaśmiecania `MEMORY.md` -summary: Konsolidacja pamięci w tle z fazami light, deep i REM oraz Dream Diary +summary: Konsolidacja pamięci w tle z fazami lekkiego, głębokiego i REM snu oraz Dziennikiem snów title: Dreaming (eksperymentalne) x-i18n: - generated_at: "2026-04-09T01:27:48Z" + generated_at: "2026-04-15T09:51:05Z" model: gpt-5.4 provider: openai - source_hash: 26476eddb8260e1554098a6adbb069cf7f5e284cf2e09479c6d9d8f8b93280ef + source_hash: 5882a5068f2eabe54ca9893184e5385330a432b921870c38626399ce11c31e25 source_path: concepts/dreaming.md workflow: 15 --- # Dreaming (eksperymentalne) -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. +Dreaming to system konsolidacji pamięci działający w tle w `memory-core`. +Pomaga OpenClaw przenosić silne sygnały krótkoterminowe do trwałej pamięci, +zachowując przy tym przejrzystość i możliwość przeglądu procesu. -Dreaming jest funkcją **opt-in** i domyślnie jest wyłączone. +Dreaming jest **opcjonalne** i domyślnie wyłączone. -## Co zapisuje dreaming +## Co zapisuje Dreaming -Dreaming utrzymuje dwa rodzaje danych wyjściowych: +Dreaming utrzymuje dwa rodzaje wyników: -- **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`. +- **Stan maszyny** w `memory/.dreams/` (magazyn recall, sygnały faz, punkty kontrolne ingestii, blokady). +- **Czytelne dla człowieka dane wyjściowe** w `DREAMS.md` (lub istniejącym `dreams.md`) oraz opcjonalnych plikach raportów faz w `memory/dreaming//YYYY-MM-DD.md`. -Promowanie do pamięci długoterminowej nadal zapisuje wyłącznie do `MEMORY.md`. +Promocja do pamięci długoterminowej nadal zapisuje wyłącznie do `MEMORY.md`. ## Model faz @@ -37,102 +37,106 @@ Dreaming używa trzech współpracujących faz: | 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 | +| Lekka | Sortowanie i przygotowanie ostatnich materiałów krótkoterminowych | Nie | +| Głęboka | 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 oddzielnymi konfigurowanymi przez użytkownika „trybami”. -### Faza light +### Faza lekka -Faza light pobiera ostatnie dzienne sygnały pamięci i ślady przypomnień, usuwa duplikaty -i przygotowuje wiersze kandydatów. +Faza lekka pobiera ostatnie dzienne sygnały pamięci i ślady recall, usuwa duplikaty +i przygotowuje kandydackie linie. -- Odczytuje stan krótkoterminowych przypomnień, ostatnie dzienne pliki pamięci oraz zredagowane transkrypty sesji, gdy są dostępne. +- Odczytuje dane ze stanu recall krótkoterminowego, ostatnich dziennych plików pamięci oraz zredagowanych transkrypcji sesji, jeśli 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. +- Rejestruje sygnały wzmacniające do późniejszego rankingu fazy głębokiej. - Nigdy nie zapisuje do `MEMORY.md`. -### Faza deep +### Faza głęboka -Faza deep decyduje, co staje się pamięcią długoterminową. +Faza głęboka decyduje, co staje się pamięcią długoterminową. -- Ustala ranking kandydatów przy użyciu ważonej punktacji i progów. -- 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. +- Klasyfikuje kandydatów przy użyciu ważonego scoringu i progów granicznych. +- Wymaga spełnienia `minScore`, `minRecallCount` i `minUniqueQueries`. +- Przed zapisem ponownie odtwarza fragmenty z aktywnych plików dziennych, więc nieaktualne lub usunięte fragmenty są pomijane. - Dopisuje promowane wpisy do `MEMORY.md`. -- Zapisuje podsumowanie `## Deep Sleep` do `DREAMS.md` i opcjonalnie zapisuje `memory/dreaming/deep/YYYY-MM-DD.md`. +- Zapisuje podsumowanie `## Deep Sleep` w `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 tematów i refleksji na podstawie ostatnich krótkoterminowych śladów. +- Buduje podsumowania tematów i refleksji na podstawie ostatnich śladów krótkoterminowych. - Zapisuje zarządzany blok `## REM Sleep`, gdy magazyn zawiera dane wyjściowe inline. -- Rejestruje sygnały wzmacniające REM używane przez ranking deep. +- Rejestruje sygnały wzmacniające REM używane przez ranking fazy głębokiej. - Nigdy nie zapisuje do `MEMORY.md`. -## Ingestia transkryptów sesji +## Ingestia transkrypcji sesji -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 +Dreaming może pobierać zredagowane transkrypcje sesji do korpusu Dreaming. Gdy +transkrypcje są dostępne, są przekazywane do fazy lekkiej razem z dziennymi +sygnałami pamięci i śladami recall. Treści osobiste i wrażliwe są redagowane przed ingestą. ## Dream Diary -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) +Dreaming prowadzi również narracyjny **Dream Diary** 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ę subagenta (z użyciem domyślnego modelu runtime) i dopisuje krótki wpis do dziennika. -Ten dziennik jest przeznaczony do odczytu przez człowieka w interfejsie Dreams, a nie jako źródło promocji. +Ten dziennik służy do czytania przez człowieka w interfejsie Dreams, a nie jako +źródło promocji. +Artefakty dziennika/raportów generowane przez Dreaming są wykluczone z promocji +krótkoterminowej. Do promocji do `MEMORY.md` kwalifikują się wyłącznie +ugruntowane fragmenty pamięci. -Istnieje również ugruntowana ścieżka historycznego backfill dla przeglądu i odzyskiwania: +Istnieje również ugruntowana ścieżka historycznego backfillu do prac przeglądowych i odzyskiwania: -- `memory rem-harness --path ... --grounded` wyświetla podgląd ugruntowanych wpisów dziennika na podstawie historycznych notatek `YYYY-MM-DD.md`. +- `memory rem-harness --path ... --grounded` wyświetla podgląd ugruntowanych danych wyjściowych 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ń. +- `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ż zwykła faza głęboka. +- `memory rem-backfill --rollback` i `--rollback-short-term` usuwają te przygotowane artefakty backfillu bez naruszania zwykłych wpisów dziennika ani aktywnego recall krótkoterminowego. -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ć, +Control UI udostępnia ten sam przepływ backfillu/resetu dziennika, dzięki czemu możesz sprawdzić +wyniki w scenie Dreams, zanim zdecydujesz, czy ugruntowani kandydaci +zasługują na promocję. Scena pokazuje również odrębny ugruntowany tor, dzięki czemu możesz zobaczyć, 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. +elementy były prowadzone przez dane ugruntowane, i czyścić tylko przygotowane wpisy wyłącznie ugruntowane +bez naruszania zwykłego aktywnego stanu krótkoterminowego. -## Sygnały rankingu deep +## Sygnały rankingu fazy głębokiej -Ranking deep używa sześciu ważonych sygnałów bazowych oraz wzmocnienia fazowego: +Ranking fazy głębokiej wykorzystuje sześć ważonych sygnałów bazowych oraz wzmocnienie fazowe: -| Sygnał | Waga | Opis | +| Sygnał | Waga | Opis | | ------------------- | ------ | ------------------------------------------------- | -| 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 | +| Częstotliwość | 0.24 | Ile sygnałów krótkoterminowych zgromadził wpis | +| Trafność | 0.30 | Średnia jakość odzyskiwania dla wpisu | +| Różnorodność zapytań | 0.15 | Różne konteksty zapytań/dni, w których się pojawił | +| Świeżość | 0.15 | Wynik świeżości osłabiany w czasie | +| Konsolidacja | 0.10 | Siła powtarzalności między dniami | +| Bogactwo pojęciowe | 0.06 | Gęstość tagów pojęciowych z fragmentu/ścieżki | -Trafienia w fazach light i REM dodają niewielkie wzmocnienie z zanikiem aktualności z +Trafienia fazy lekkiej i REM dodają niewielkie wzmocnienie osłabiane w czasie z `memory/.dreams/phase-signals.json`. ## Harmonogram -Po włączeniu `memory-core` automatycznie zarządza jednym zadaniem cron dla pełnego -przebiegu dreaming. Każdy przebieg uruchamia fazy po kolei: light -> REM -> deep. +Po włączeniu `memory-core` automatycznie zarządza jednym zadaniem Cron dla pełnego +przebiegu Dreaming. Każdy przebieg uruchamia fazy po kolei: lekka -> REM -> głęboka. -Domyślne zachowanie kadencji: +Domyślne zachowanie harmonogramu: -| Ustawienie | Domyślnie | -| ------------------- | ---------- | +| Ustawienie | Domyślnie | +| -------------------- | ----------- | | `dreaming.frequency` | `0 3 * * *` | ## Szybki start -Włącz dreaming: +Włącz Dreaming: ```json { @@ -150,7 +154,7 @@ Włącz dreaming: } ``` -Włącz dreaming z niestandardową kadencją przebiegu: +Włącz Dreaming z własnym harmonogramem przebiegu: ```json { @@ -170,7 +174,7 @@ Włącz dreaming z niestandardową kadencją przebiegu: } ``` -## Komenda slash +## Polecenie slash ``` /dreaming status @@ -181,7 +185,7 @@ Włącz dreaming z niestandardową kadencją przebiegu: ## Przepływ pracy CLI -Użyj promowania przez CLI do podglądu lub ręcznego zastosowania: +Użyj promocji CLI do podglądu lub ręcznego zastosowania: ```bash openclaw memory promote @@ -190,17 +194,17 @@ openclaw memory promote --limit 5 openclaw memory status --deep ``` -Ręczne `memory promote` domyślnie używa progów fazy deep, chyba że zostaną nadpisane +Ręczne `memory promote` domyślnie używa progów fazy głębokiej, chyba że zostaną nadpisane flagami CLI. -Wyjaśnij, dlaczego konkretny kandydat zostałby lub nie zostałby promowany: +Wyjaśnij, dlaczego konkretny kandydat zostałby albo nie zostałby promowany: ```bash 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 deep bez +Wyświetl podgląd refleksji REM, prawd kandydatów i wyników promocji fazy głębokiej bez zapisywania czegokolwiek: ```bash @@ -210,32 +214,32 @@ openclaw memory rem-harness --json ## Kluczowe wartości domyślne -Wszystkie ustawienia znajdują się w `plugins.entries.memory-core.config.dreaming`. +Wszystkie ustawienia znajdują się pod `plugins.entries.memory-core.config.dreaming`. -| Klucz | Domyślnie | -| ---------- | ---------- | +| Key | Domyślnie | +| ----------- | ----------- | | `enabled` | `false` | | `frequency` | `0 3 * * *` | Polityka faz, progi i zachowanie magazynu są wewnętrznymi szczegółami implementacji -(nie są to ustawienia dostępne dla użytkownika). +(a nie konfiguracją dostępną dla użytkownika). -Pełną listę kluczy znajdziesz w [Memory configuration reference](/pl/reference/memory-config#dreaming-experimental). +Pełną listę kluczy znajdziesz w [referencji konfiguracji pamięci](/pl/reference/memory-config#dreaming-experimental). ## Interfejs Dreams Po włączeniu karta **Dreams** w Gateway pokazuje: -- bieżący stan włączenia dreaming -- stan na poziomie faz oraz obecność zarządzanego przebiegu +- bieżący stan włączenia Dreaming +- stan na poziomie faz i obecność zarządzanego przebiegu - liczby elementów krótkoterminowych, ugruntowanych, sygnałów i promowanych dzisiaj -- czas następnego zaplanowanego uruchomienia -- odrębny ugruntowany tor sceny dla przygotowanych wpisów historycznego odtworzenia +- czas do następnego zaplanowanego uruchomienia +- odrębny tor sceny ugruntowanej dla przygotowanych wpisów historycznego odtworzenia - rozwijany czytnik Dream Diary oparty na `doctor.memory.dreamDiary` ## Powiązane -- [Memory](/pl/concepts/memory) -- [Memory Search](/pl/concepts/memory-search) -- [memory CLI](/cli/memory) -- [Memory configuration reference](/pl/reference/memory-config) +- [Pamięć](/pl/concepts/memory) +- [Wyszukiwanie w pamięci](/pl/concepts/memory-search) +- [CLI memory](/cli/memory) +- [Referencja konfiguracji pamięci](/pl/reference/memory-config) diff --git a/docs/pl/concepts/memory-search.md b/docs/pl/concepts/memory-search.md index bad240818..7f83da6eb 100644 --- a/docs/pl/concepts/memory-search.md +++ b/docs/pl/concepts/memory-search.md @@ -6,51 +6,56 @@ read_when: summary: Jak wyszukiwanie pamięci znajduje odpowiednie notatki za pomocą embeddingów i wyszukiwania hybrydowego title: Wyszukiwanie pamięci x-i18n: - generated_at: "2026-04-12T23:28:04Z" + generated_at: "2026-04-15T09:51:03Z" model: gpt-5.4 provider: openai - source_hash: 71fde251b7d2dc455574aa458e7e09136f30613609ad8dafeafd53b2729a0310 + source_hash: f5757aa8fe8f7fec30ef5c826f72230f591ce4cad591d81a091189d50d4262ed source_path: concepts/memory-search.md workflow: 15 --- # Wyszukiwanie pamięci -`memory_search` znajduje odpowiednie notatki z Twoich plików pamięci, nawet gdy sformułowania różnią się od oryginalnego tekstu. Działa przez indeksowanie pamięci w małych fragmentach i przeszukiwanie ich za pomocą embeddingów, słów kluczowych albo obu tych metod. +`memory_search` znajduje odpowiednie notatki z Twoich plików pamięci, nawet gdy +sformułowanie różni się od oryginalnego tekstu. Działa przez indeksowanie pamięci w małych +fragmentach i przeszukiwanie ich za pomocą embeddingów, słów kluczowych albo obu metod naraz. ## Szybki start -Jeśli masz skonfigurowany klucz API OpenAI, Gemini, Voyage lub Mistral, wyszukiwanie pamięci działa automatycznie. Aby jawnie ustawić dostawcę: +Jeśli masz subskrypcję GitHub Copilot albo skonfigurowany klucz API OpenAI, Gemini, Voyage lub Mistral, +wyszukiwanie pamięci działa automatycznie. Aby jawnie ustawić dostawcę: ```json5 { agents: { defaults: { memorySearch: { - provider: "openai", // lub "gemini", "local", "ollama" itp. + provider: "openai", // lub "gemini", "local", "ollama" itd. }, }, }, } ``` -W przypadku lokalnych embeddingów bez klucza API użyj `provider: "local"` (wymaga `node-llama-cpp`). +Do lokalnych embeddingów bez klucza API użyj `provider: "local"` (wymaga +node-llama-cpp). ## Obsługiwani dostawcy -| Dostawca | ID | Wymaga klucza API | Uwagi | -| -------- | --------- | ----------------- | ---------------------------------------------------- | -| OpenAI | `openai` | Tak | Wykrywany automatycznie, szybki | -| Gemini | `gemini` | Tak | Obsługuje indeksowanie obrazów i dźwięku | -| Voyage | `voyage` | Tak | Wykrywany automatycznie | -| Mistral | `mistral` | Tak | Wykrywany automatycznie | -| Bedrock | `bedrock` | Nie | Wykrywany automatycznie, gdy łańcuch poświadczeń AWS zostanie rozwiązany | -| Ollama | `ollama` | Nie | Lokalny, trzeba ustawić jawnie | -| Local | `local` | Nie | Model GGUF, pobieranie ~0,6 GB | +| Dostawca | ID | Wymaga klucza API | Uwagi | +| -------------- | ---------------- | ----------------- | ---------------------------------------------------- | +| Bedrock | `bedrock` | Nie | Wykrywany automatycznie, gdy łańcuch poświadczeń AWS zostanie rozwiązany | +| Gemini | `gemini` | Tak | Obsługuje indeksowanie obrazów/dźwięku | +| GitHub Copilot | `github-copilot` | Nie | Wykrywany automatycznie, używa subskrypcji Copilot | +| Local | `local` | Nie | Model GGUF, pobranie ~0,6 GB | +| Mistral | `mistral` | Tak | Wykrywany automatycznie | +| Ollama | `ollama` | Nie | Lokalny, trzeba ustawić jawnie | +| OpenAI | `openai` | Tak | Wykrywany automatycznie, szybki | +| Voyage | `voyage` | Tak | Wykrywany automatycznie | ## Jak działa wyszukiwanie -OpenClaw uruchamia równolegle dwie ścieżki wyszukiwania i scala wyniki: +OpenClaw uruchamia równolegle dwie ścieżki pobierania i scala wyniki: ```mermaid flowchart LR @@ -63,12 +68,14 @@ flowchart LR M --> R["Top Results"] ``` -- **Wyszukiwanie wektorowe** znajduje notatki o podobnym znaczeniu („gateway host” pasuje do „maszyna, na której działa OpenClaw”). -- **Wyszukiwanie słów kluczowych BM25** znajduje dokładne dopasowania (ID, ciągi błędów, klucze konfiguracji). +- **Wyszukiwanie wektorowe** znajduje notatki o podobnym znaczeniu (`"gateway host"` pasuje + do `"the machine running OpenClaw"`). +- **Wyszukiwanie słów kluczowych BM25** znajduje dokładne dopasowania (ID, ciągi błędów, klucze + konfiguracji). -Jeśli dostępna jest tylko jedna ścieżka (brak embeddingów albo brak FTS), działa tylko ta jedna. +Jeśli dostępna jest tylko jedna ścieżka (brak embeddingów albo brak FTS), działa tylko ta druga. -Gdy embeddingi są niedostępne, OpenClaw nadal używa rankingu leksykalnego na wynikach FTS zamiast sprowadzać się wyłącznie do surowego porządku dokładnych dopasowań. Ten tryb obniżonej jakości wzmacnia fragmenty z lepszym pokryciem terminów zapytania i odpowiednimi ścieżkami plików, co pomaga zachować użyteczny recall nawet bez `sqlite-vec` lub dostawcy embeddingów. +Gdy embeddingi są niedostępne, OpenClaw nadal używa rankingu leksykalnego względem wyników FTS zamiast wracać wyłącznie do surowego porządku dokładnych dopasowań. Ten tryb obniżonej jakości wzmacnia fragmenty z lepszym pokryciem terminów zapytania i odpowiednimi ścieżkami plików, co pomaga zachować użyteczną trafność nawet bez `sqlite-vec` albo dostawcy embeddingów. ## Poprawa jakości wyszukiwania @@ -76,18 +83,23 @@ Dwie opcjonalne funkcje pomagają, gdy masz dużą historię notatek: ### Zanikanie czasowe -Stare notatki stopniowo tracą wagę rankingową, dzięki czemu nowsze informacje pojawiają się wyżej. Przy domyślnym okresie połowicznego zaniku wynoszącym 30 dni notatka z zeszłego miesiąca zachowuje 50% swojej pierwotnej wagi. Pliki trwałe, takie jak `MEMORY.md`, nigdy nie podlegają zanikowi. +Stare notatki stopniowo tracą wagę rankingową, dzięki czemu najpierw pojawiają się nowsze informacje. +Przy domyślnym okresie połowicznego zaniku wynoszącym 30 dni notatka z zeszłego miesiąca ma wynik równy 50% +swojej pierwotnej wagi. Pliki stałe, takie jak `MEMORY.md`, nigdy nie podlegają zanikaniu. -Włącz zanikanie czasowe, jeśli Twój agent ma miesiące codziennych notatek, a nieaktualne informacje stale wyprzedzają nowszy kontekst. +Włącz zanikanie czasowe, jeśli Twój agent ma miesiące codziennych notatek, a nieaktualne +informacje stale wyprzedzają nowszy kontekst. ### MMR (różnorodność) -Ogranicza redundantne wyniki. Jeśli pięć notatek wspomina tę samą konfigurację routera, MMR sprawia, że najwyższe wyniki obejmują różne tematy zamiast się powtarzać. +Ogranicza powtarzające się wyniki. Jeśli pięć notatek wspomina tę samą konfigurację routera, MMR +sprawia, że najwyższe wyniki obejmują różne tematy zamiast się powtarzać. -Włącz MMR, jeśli `memory_search` stale zwraca niemal identyczne fragmenty z różnych codziennych notatek. +Włącz MMR, jeśli `memory_search` stale zwraca niemal identyczne fragmenty z +różnych codziennych notatek. ### Włącz oba @@ -111,22 +123,31 @@ Włącz MMR, jeśli `memory_search` stale zwraca niemal identyczne fragmenty z r ## Pamięć multimodalna -Dzięki Gemini Embedding 2 możesz indeksować obrazy i pliki audio obok Markdownu. Zapytania wyszukiwania nadal pozostają tekstowe, ale dopasowują się do treści wizualnych i dźwiękowych. Informacje o konfiguracji znajdziesz w [referencji konfiguracji pamięci](/pl/reference/memory-config). +Z Gemini Embedding 2 możesz indeksować obrazy i pliki audio razem z +Markdownem. Zapytania wyszukiwania nadal pozostają tekstowe, ale dopasowują się do +treści wizualnych i audio. Zobacz [odnośnik do konfiguracji pamięci](/pl/reference/memory-config), aby poznać +konfigurację. -## Wyszukiwanie pamięci sesji +## Wyszukiwanie w pamięci sesji -Możesz opcjonalnie indeksować transkrypcje sesji, aby `memory_search` mogło przywoływać wcześniejsze rozmowy. Jest to funkcja opt-in przez `memorySearch.experimental.sessionMemory`. Szczegóły znajdziesz w [referencji konfiguracji](/pl/reference/memory-config). +Możesz opcjonalnie indeksować transkrypty sesji, aby `memory_search` mógł przywoływać +wcześniejsze rozmowy. To funkcja opt-in przez +`memorySearch.experimental.sessionMemory`. Szczegóły znajdziesz w +[odnośniku do konfiguracji](/pl/reference/memory-config). ## Rozwiązywanie problemów -**Brak wyników?** Uruchom `openclaw memory status`, aby sprawdzić indeks. Jeśli jest pusty, uruchom `openclaw memory index --force`. +**Brak wyników?** Uruchom `openclaw memory status`, aby sprawdzić indeks. Jeśli jest pusty, uruchom +`openclaw memory index --force`. -**Tylko dopasowania słów kluczowych?** Twój dostawca embeddingów może nie być skonfigurowany. Sprawdź `openclaw memory status --deep`. +**Tylko dopasowania słów kluczowych?** Twój dostawca embeddingów może nie być skonfigurowany. Sprawdź +`openclaw memory status --deep`. -**Nie znajduje tekstu CJK?** Przebuduj indeks FTS za pomocą `openclaw memory index --force`. +**Nie znajduje tekstu CJK?** Odbuduj indeks FTS za pomocą +`openclaw memory index --force`. ## Dalsza lektura -- [Active Memory](/pl/concepts/active-memory) -- pamięć podagenta dla interaktywnych sesji czatu +- [Active Memory](/pl/concepts/active-memory) -- pamięć subagenta dla interaktywnych sesji czatu - [Pamięć](/pl/concepts/memory) -- układ plików, backendy, narzędzia -- [Referencja konfiguracji pamięci](/pl/reference/memory-config) -- wszystkie opcje konfiguracji +- [Odnośnik do konfiguracji pamięci](/pl/reference/memory-config) -- wszystkie opcje konfiguracji diff --git a/docs/pl/gateway/local-models.md b/docs/pl/gateway/local-models.md index 3295d1878..024ac03bf 100644 --- a/docs/pl/gateway/local-models.md +++ b/docs/pl/gateway/local-models.md @@ -2,27 +2,27 @@ read_when: - Chcesz udostępniać modele z własnej maszyny z GPU - Konfigurujesz LM Studio lub proxy zgodne z OpenAI - - Potrzebujesz najbezpieczniejszych wskazówek dotyczących modeli lokalnych -summary: Uruchamiaj OpenClaw na lokalnych LLM-ach (LM Studio, vLLM, LiteLLM, niestandardowe endpointy OpenAI) -title: Modele lokalne + - Potrzebujesz najbezpieczniejszych wskazówek dotyczących lokalnych modeli +summary: Uruchamiaj OpenClaw na lokalnych modelach LLM (LM Studio, vLLM, LiteLLM, niestandardowe endpointy OpenAI) +title: Lokalne modele x-i18n: - generated_at: "2026-04-14T09:50:55Z" + generated_at: "2026-04-15T09:51:03Z" model: gpt-5.4 provider: openai - source_hash: 1544c522357ba4b18dfa6d05ea8d60c7c6262281b53863d9aee7002464703ca7 + source_hash: 8778cc1c623a356ff3cf306c494c046887f9417a70ec71e659e4a8aae912a780 source_path: gateway/local-models.md workflow: 15 --- -# Modele lokalne +# Lokalne modele -Lokalnie da się to zrobić, ale OpenClaw oczekuje dużego kontekstu + silnych zabezpieczeń przed prompt injection. Małe karty obcinają kontekst i osłabiają bezpieczeństwo. Celuj wysoko: **≥2 w pełni wyposażone Mac Studio lub równoważny zestaw GPU (~30 tys. USD+)**. Pojedyncze GPU **24 GB** działa tylko przy lżejszych promptach i z większymi opóźnieniami. Używaj **największego / pełnowymiarowego wariantu modelu, jaki jesteś w stanie uruchomić**; agresywnie kwantyzowane lub „małe” checkpointy zwiększają ryzyko prompt injection (zobacz [Bezpieczeństwo](/pl/gateway/security)). +Lokalnie da się to uruchomić, ale OpenClaw oczekuje dużego kontekstu oraz silnych zabezpieczeń przed prompt injection. Małe karty obcinają kontekst i osłabiają bezpieczeństwo. Celuj wysoko: **≥2 w pełni wyposażone Mac Studio lub równoważny zestaw GPU (~30 tys. USD+)**. Pojedynczy procesor GPU z **24 GB** działa tylko przy lżejszych promptach i z większymi opóźnieniami. Używaj **największego / pełnowymiarowego wariantu modelu, jaki jesteś w stanie uruchomić**; mocno kwantyzowane lub „małe” checkpointy zwiększają ryzyko prompt injection (zobacz [Bezpieczeństwo](/pl/gateway/security)). -Jeśli chcesz najprostszej konfiguracji lokalnej, zacznij od [LM Studio](/pl/providers/lmstudio) lub [Ollama](/pl/providers/ollama) i `openclaw onboard`. Ta strona to praktyczny przewodnik po bardziej zaawansowanych stosach lokalnych i niestandardowych lokalnych serwerach zgodnych z OpenAI. +Jeśli chcesz najprostszej lokalnej konfiguracji, zacznij od [LM Studio](/pl/providers/lmstudio) lub [Ollama](/pl/providers/ollama) i `openclaw onboard`. Ta strona to opiniotwórczy przewodnik po bardziej zaawansowanych lokalnych stosach i niestandardowych lokalnych serwerach zgodnych z OpenAI. -## Zalecane: LM Studio + duży model lokalny (Responses API) +## Zalecane: LM Studio + duży lokalny model (Responses API) -Obecnie najlepszy lokalny stos. Załaduj duży model w LM Studio (na przykład pełnowymiarową wersję Qwen, DeepSeek lub Llama), włącz serwer lokalny (domyślnie `http://127.0.0.1:1234`), i użyj Responses API, aby oddzielić rozumowanie od końcowego tekstu. +Obecnie najlepszy lokalny stos. Załaduj duży model w LM Studio (na przykład pełnowymiarową wersję Qwen, DeepSeek lub Llama), włącz lokalny serwer (domyślnie `http://127.0.0.1:1234`) i użyj Responses API, aby oddzielić rozumowanie od końcowego tekstu. ```json5 { @@ -65,10 +65,10 @@ Obecnie najlepszy lokalny stos. Załaduj duży model w LM Studio (na przykład p - W LM Studio pobierz **największą dostępną wersję modelu** (unikaj wariantów „small” / mocno kwantyzowanych), uruchom serwer i potwierdź, że `http://127.0.0.1:1234/v1/models` go wyświetla. - Zastąp `my-local-model` rzeczywistym identyfikatorem modelu widocznym w LM Studio. - Utrzymuj model załadowany; zimne ładowanie zwiększa opóźnienie startu. -- Dostosuj `contextWindow` / `maxTokens`, jeśli Twoja wersja LM Studio różni się od tej tutaj. +- Dostosuj `contextWindow`/`maxTokens`, jeśli Twoja wersja LM Studio różni się od tej opisanej tutaj. - W przypadku WhatsApp trzymaj się Responses API, aby wysyłany był tylko końcowy tekst. -Zachowaj też konfigurację modeli hostowanych, nawet jeśli działasz lokalnie; użyj `models.mode: "merge"`, aby fallbacki pozostały dostępne. +Nawet przy pracy lokalnej zachowaj konfigurację modeli hostowanych; użyj `models.mode: "merge"`, aby fallbacki nadal były dostępne. ### Konfiguracja hybrydowa: hostowany model główny, lokalny fallback @@ -111,18 +111,18 @@ Zachowaj też konfigurację modeli hostowanych, nawet jeśli działasz lokalnie; } ``` -### Podejście local-first z hostowaną siatką bezpieczeństwa +### Najpierw lokalnie, z hostowaną siatką bezpieczeństwa -Zamień miejscami kolejność modelu głównego i fallbacków; zachowaj ten sam blok providerów oraz `models.mode: "merge"`, aby móc przełączyć się na Sonnet lub Opus, gdy lokalna maszyna będzie niedostępna. +Zamień kolejność modelu głównego i fallbacku; zachowaj ten sam blok providers oraz `models.mode: "merge"`, aby móc wrócić do Sonnet lub Opus, gdy lokalna maszyna będzie niedostępna. ### Hosting regionalny / trasowanie danych -- Hostowane warianty MiniMax / Kimi / GLM są też dostępne w OpenRouter z endpointami przypiętymi do regionu (np. hostowanymi w USA). Wybierz tam wariant regionalny, aby utrzymać ruch w wybranej jurysdykcji, jednocześnie nadal używając `models.mode: "merge"` dla fallbacków Anthropic / OpenAI. -- Podejście wyłącznie lokalne pozostaje najlepszą ścieżką prywatności; hostowane trasowanie regionalne to rozwiązanie pośrednie, gdy potrzebujesz funkcji dostawcy, ale chcesz zachować kontrolę nad przepływem danych. +- Hostowane warianty MiniMax/Kimi/GLM są też dostępne w OpenRouter z endpointami przypiętymi do regionu (np. hostowanymi w USA). Wybierz tam wariant regionalny, aby utrzymać ruch w wybranej jurysdykcji, nadal używając `models.mode: "merge"` dla fallbacków Anthropic/OpenAI. +- Tryb wyłącznie lokalny pozostaje najlepszą ścieżką pod względem prywatności; hostowane trasowanie regionalne to rozwiązanie pośrednie, gdy potrzebujesz funkcji dostawcy, ale chcesz kontrolować przepływ danych. ## Inne lokalne proxy zgodne z OpenAI -vLLM, LiteLLM, OAI-proxy lub niestandardowe Gateway działają, jeśli udostępniają endpoint `/v1` w stylu OpenAI. Zastąp powyższy blok providera swoim endpointem i identyfikatorem modelu: +vLLM, LiteLLM, OAI-proxy lub niestandardowe Gateway działają, jeśli udostępniają endpoint `/v1` w stylu OpenAI. Zastąp powyższy blok provider swoim endpointem i identyfikatorem modelu: ```json5 { @@ -152,40 +152,41 @@ vLLM, LiteLLM, OAI-proxy lub niestandardowe Gateway działają, jeśli udostępn Zachowaj `models.mode: "merge"`, aby hostowane modele nadal były dostępne jako fallbacki. -Uwaga dotycząca działania backendów lokalnych / proxowanych `/v1`: +Uwaga dotycząca działania lokalnych/proksowanych backendów `/v1`: -- OpenClaw traktuje je jako trasy zgodne z OpenAI w stylu proxy, a nie natywne endpointy OpenAI -- natywne formatowanie żądań przeznaczone wyłącznie dla OpenAI nie ma tu zastosowania: brak - `service_tier`, brak `store` w Responses, brak formatowania payloadu zgodności rozumowania OpenAI - i brak wskazówek dotyczących pamięci podręcznej promptów +- OpenClaw traktuje je jako trasy proxy zgodne z OpenAI, a nie natywne endpointy OpenAI +- natywne dla OpenAI kształtowanie żądań nie ma tu zastosowania: brak + `service_tier`, brak `store` w Responses, brak kształtowania payloadu + zgodności z rozumowaniem OpenAI oraz brak wskazówek dla prompt cache - ukryte nagłówki atrybucji OpenClaw (`originator`, `version`, `User-Agent`) - nie są wstrzykiwane do tych niestandardowych URL-i proxy + nie są wstrzykiwane do tych niestandardowych adresów URL proxy -Uwagi dotyczące zgodności z bardziej restrykcyjnymi backendami zgodnymi z OpenAI: +Uwagi o zgodności dla bardziej rygorystycznych backendów zgodnych z OpenAI: -- Niektóre serwery akceptują tylko ciąg znaków w `messages[].content` dla Chat Completions, a nie - ustrukturyzowane tablice części treści. Ustaw +- Niektóre serwery akceptują wyłącznie ciąg znaków w `messages[].content` w Chat Completions, a nie + uporządkowane tablice części treści. Ustaw `models.providers..models[].compat.requiresStringContent: true` dla takich endpointów. -- Niektóre mniejsze lub bardziej restrykcyjne lokalne backendy są niestabilne przy pełnym - kształcie promptu środowiska uruchomieniowego agenta OpenClaw, zwłaszcza gdy dołączone są schematy narzędzi. Jeśli - backend działa dla małych bezpośrednich wywołań `/v1/chat/completions`, ale zawodzi przy zwykłych +- Niektóre mniejsze lub bardziej rygorystyczne lokalne backendy są niestabilne z pełnym + kształtem promptu środowiska uruchomieniowego agenta w OpenClaw, zwłaszcza gdy dołączone są schematy narzędzi. Jeśli + backend działa przy małych bezpośrednich wywołaniach `/v1/chat/completions`, ale nie działa przy zwykłych turach agenta OpenClaw, najpierw spróbuj + `agents.defaults.localModelMode: "lean"`, aby usunąć cięższe domyślne narzędzia + takie jak `browser`, `cron` i `message`; jeśli to nadal nie pomoże, spróbuj `models.providers..models[].compat.supportsTools: false`. -- Jeśli backend nadal zawodzi tylko przy większych uruchomieniach OpenClaw, pozostały problem - zwykle leży po stronie pojemności modelu / serwera albo błędu backendu, a nie warstwy - transportowej OpenClaw. +- Jeśli backend nadal zawodzi tylko przy większych uruchomieniach OpenClaw, + pozostały problem zwykle leży po stronie pojemności modelu/serwera upstream albo błędu backendu, a nie warstwy transportowej OpenClaw. ## Rozwiązywanie problemów - Gateway może połączyć się z proxy? `curl http://127.0.0.1:1234/v1/models`. - Model LM Studio został wyładowany? Załaduj go ponownie; zimny start to częsta przyczyna „zawieszania się”. -- OpenClaw ostrzega, gdy wykryte okno kontekstu jest mniejsze niż **32k**, i blokuje działanie poniżej **16k**. Jeśli trafisz na ten preflight, zwiększ limit kontekstu serwera / modelu albo wybierz większy model. +- OpenClaw ostrzega, gdy wykryte okno kontekstu jest mniejsze niż **32k**, i blokuje działanie poniżej **16k**. Jeśli trafiasz na ten wstępny test, zwiększ limit kontekstu serwera/modelu albo wybierz większy model. - Błędy kontekstu? Zmniejsz `contextWindow` albo zwiększ limit serwera. - Serwer zgodny z OpenAI zwraca `messages[].content ... expected a string`? - Dodaj `compat.requiresStringContent: true` do wpisu tego modelu. -- Bezpośrednie małe wywołania `/v1/chat/completions` działają, ale `openclaw infer model run` - zawodzi na Gemma lub innym modelu lokalnym? Najpierw wyłącz schematy narzędzi przez - `compat.supportsTools: false`, a potem przetestuj ponownie. Jeśli serwer nadal zawiesza się tylko - przy większych promptach OpenClaw, traktuj to jako ograniczenie modelu / serwera po stronie upstream. -- Bezpieczeństwo: modele lokalne pomijają filtry po stronie dostawcy; ograniczaj zakres agentów i pozostaw Compaction włączone, aby zmniejszyć skutki prompt injection. + Dodaj `compat.requiresStringContent: true` w tym wpisie modelu. +- Małe bezpośrednie wywołania `/v1/chat/completions` działają, ale `openclaw infer model run` + nie działa na Gemma lub innym lokalnym modelu? Najpierw wyłącz schematy narzędzi przez + `compat.supportsTools: false`, a potem przetestuj ponownie. Jeśli serwer nadal się wyłącza tylko + przy większych promptach OpenClaw, traktuj to jako ograniczenie modelu/serwera upstream. +- Bezpieczeństwo: lokalne modele pomijają filtry po stronie dostawcy; utrzymuj agentów w wąskim zakresie i pozostaw Compaction włączone, aby ograniczyć zasięg prompt injection. diff --git a/docs/pl/help/testing.md b/docs/pl/help/testing.md index 03cca89f2..2aa06fdd3 100644 --- a/docs/pl/help/testing.md +++ b/docs/pl/help/testing.md @@ -2,14 +2,14 @@ read_when: - Uruchamianie testów lokalnie lub w CI - Dodawanie testów regresji dla błędów modeli/dostawców - - Debugowanie zachowania Gateway i agenta -summary: 'Zestaw testowy: pakiety testów unit/e2e/live, uruchamiacze Docker i zakres pokrycia poszczególnych testów' + - Debugowanie zachowania Gateway + agenta +summary: 'Zestaw testowy: pakiety testów unit/e2e/live, uruchamiacze Docker i co obejmuje każdy test' title: Testowanie x-i18n: - generated_at: "2026-04-13T08:50:41Z" + generated_at: "2026-04-15T09:51:05Z" model: gpt-5.4 provider: openai - source_hash: 3db91b4bc36f626cd014958ec66b08b9cecd9faaa20a5746cd3a49ad4b0b1c38 + source_hash: fbf647a5cf13b5861a3ba0cb367dc816c57f0e9c60d3cd6320da193bfadf5609 source_path: help/testing.md workflow: 15 --- @@ -20,24 +20,24 @@ OpenClaw ma trzy pakiety Vitest (unit/integration, e2e, live) oraz niewielki zes Ten dokument jest przewodnikiem „jak testujemy”: -- Co obejmuje każdy pakiet testów (i czego celowo _nie_ obejmuje) -- Jakie polecenia uruchamiać w typowych przepływach pracy (lokalnie, przed pushem, debugowanie) +- Co obejmuje każdy pakiet (i czego celowo _nie_ obejmuje) +- Jakie polecenia uruchamiać w typowych przepływach pracy (lokalnie, przed wypchnięciem, debugowanie) - Jak testy live wykrywają poświadczenia oraz wybierają modele/dostawców -- Jak dodawać testy regresji dla rzeczywistych problemów modeli/dostawców +- Jak dodawać testy regresji dla rzeczywistych problemów z modelami/dostawcami ## Szybki start -W większości dni: +Na co dzień: -- Pełna bramka (oczekiwana przed pushem): `pnpm build && pnpm check && pnpm test` -- Szybsze lokalne uruchomienie całego pakietu na wydajnej maszynie: `pnpm test:max` -- Bezpośrednia pętla obserwacji Vitest: `pnpm test:watch` -- Bezpośrednie wskazanie pliku teraz obsługuje także ścieżki rozszerzeń/kanałów: `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` +- 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 dla Vitest: `pnpm test:watch` +- Bezpośrednie wskazywanie pliku obsługuje teraz także ścieżki extension/channel: `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` - Gdy iterujesz nad pojedynczym błędem, najpierw preferuj uruchomienia ukierunkowane. - Witryna QA oparta na Docker: `pnpm qa:lab:up` - Linia QA oparta na Linux VM: `pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline` -Gdy modyfikujesz testy lub chcesz uzyskać większą pewność: +Gdy dotykasz testów lub chcesz mieć większą pewność: - Bramka pokrycia: `pnpm test:coverage` - Pakiet E2E: `pnpm test:e2e` @@ -45,57 +45,60 @@ Gdy modyfikujesz testy lub chcesz uzyskać większą pewność: Podczas debugowania rzeczywistych dostawców/modeli (wymaga prawdziwych poświadczeń): - Pakiet live (modele + sondy narzędzi/obrazów Gateway): `pnpm test:live` -- Ciche uruchomienie pojedynczego pliku live: `pnpm test:live -- src/agents/models.profiles.live.test.ts` +- Ciche uruchomienie jednego pliku live: `pnpm test:live -- src/agents/models.profiles.live.test.ts` Wskazówka: gdy potrzebujesz tylko jednego nieudanego przypadku, zawężaj testy live za pomocą zmiennych środowiskowych allowlist opisanych poniżej. ## Uruchamiacze specyficzne dla QA -Te polecenia działają obok głównych pakietów testów, gdy potrzebujesz realizmu qa-lab: +Te polecenia działają obok głównych pakietów testowych, gdy potrzebujesz realizmu qa-lab: - `pnpm openclaw qa suite` - - Uruchamia scenariusze QA wspierane przez repozytorium bezpośrednio na hoście. - - Domyślnie uruchamia równolegle wiele wybranych scenariuszy z izolowanymi workerami Gateway, maksymalnie do 64 workerów lub liczby wybranych scenariuszy. Użyj `--concurrency `, aby dostroić liczbę workerów, albo `--concurrency 1` dla starszej linii sekwencyjnej. + - Uruchamia scenariusze QA oparte o repo bezpośrednio na hoście. + - Domyślnie uruchamia równolegle wiele wybranych scenariuszy z izolowanymi workerami Gateway, do 64 workerów lub liczby wybranych scenariuszy. Użyj `--concurrency `, aby dostroić liczbę workerów, albo `--concurrency 1` dla starszej linii sekwencyjnej. - `pnpm openclaw qa suite --runner multipass` - - Uruchamia ten sam pakiet QA wewnątrz jednorazowej maszyny wirtualnej Linux Multipass. - - Zachowuje ten sam sposób wyboru scenariuszy co `qa suite` na hoście. - - Używa tych samych flag wyboru dostawcy/modelu co `qa suite`. - - Uruchomienia live przekazują do gościa obsługiwane wejścia uwierzytelniania QA, które są praktyczne dla środowiska gościa: + - Uruchamia ten sam pakiet QA wewnątrz tymczasowej maszyny Linux Multipass. + - Zachowuje to samo zachowanie wyboru scenariuszy co `qa suite` na hoście. + - Ponownie używa tych samych flag wyboru dostawcy/modelu co `qa suite`. + - Uruchomienia live przekazują obsługiwane wejścia uwierzytelniania QA, które są praktyczne dla maszyny gościa: klucze dostawców oparte na env, ścieżkę konfiguracji dostawcy QA live oraz `CODEX_HOME`, jeśli jest obecne. - - Katalogi wyjściowe muszą pozostawać pod korzeniem repozytorium, aby gość mógł zapisywać dane z powrotem przez zamontowany obszar roboczy. - - Zapisuje zwykły raport + podsumowanie QA oraz logi Multipass w `.artifacts/qa-e2e/...`. + - Katalogi wyjściowe muszą pozostawać pod katalogiem głównym repo, aby maszyna gościa mogła zapisywać dane przez zamontowany workspace. + - Zapisuje standardowy raport + podsumowanie QA oraz logi Multipass w + `.artifacts/qa-e2e/...`. - `pnpm qa:lab:up` - Uruchamia witrynę QA opartą na Docker do pracy QA w stylu operatorskim. - `pnpm openclaw qa matrix` - - Uruchamia linię live QA Matrix na jednorazowym homeserverze Tuwunel opartym na Docker. - - Tworzy trzy tymczasowe konta użytkowników Matrix (`driver`, `sut`, `observer`) oraz jeden prywatny pokój, a następnie uruchamia podrzędny proces QA Gateway z rzeczywistym Plugin Matrix jako transportem SUT. - - Domyślnie używa przypiętego stabilnego obrazu Tuwunel `ghcr.io/matrix-construct/tuwunel:v1.5.1`. Zastąp przez `OPENCLAW_QA_MATRIX_TUWUNEL_IMAGE`, gdy musisz przetestować inny obraz. - - Matrix obecnie obsługuje tylko `--credential-source env`, ponieważ linia tworzy tymczasowych użytkowników lokalnie. - - Zapisuje raport QA Matrix, podsumowanie oraz artefakt obserwowanych zdarzeń w `.artifacts/qa-e2e/...`. + - Uruchamia linię live QA dla Matrix względem tymczasowego homeservera Tuwunel uruchomionego przez Docker. + - Ten host QA jest dziś przeznaczony wyłącznie do repo/dev. Spakowane instalacje OpenClaw nie dostarczają `qa-lab`, więc nie udostępniają `openclaw qa`. + - Klony repo ładują dołączony runner bezpośrednio; nie jest potrzebny oddzielny krok instalacji Plugin. + - Tworzy trzech tymczasowych użytkowników Matrix (`driver`, `sut`, `observer`) oraz jeden prywatny pokój, a następnie uruchamia podrzędny proces Gateway QA z rzeczywistym Plugin Matrix jako transportem SUT. + - Domyślnie używa przypiętego stabilnego obrazu Tuwunel `ghcr.io/matrix-construct/tuwunel:v1.5.1`. Zastąp przez `OPENCLAW_QA_MATRIX_TUWUNEL_IMAGE`, jeśli chcesz przetestować inny obraz. + - Matrix nie udostępnia współdzielonych flag źródła poświadczeń, ponieważ ta linia tworzy tymczasowych użytkowników lokalnie. + - Zapisuje raport QA dla Matrix, podsumowanie oraz artefakt zaobserwowanych zdarzeń w `.artifacts/qa-e2e/...`. - `pnpm openclaw qa telegram` - - Uruchamia linię live QA Telegram na rzeczywistej prywatnej grupie przy użyciu tokenów botów driver i SUT z env. - - Wymaga `OPENCLAW_QA_TELEGRAM_GROUP_ID`, `OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN` oraz `OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN`. Identyfikator grupy musi być numerycznym identyfikatorem czatu Telegram. - - Obsługuje `--credential-source convex` dla współdzielonych poświadczeń z puli. Domyślnie używaj trybu env albo ustaw `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`, aby włączyć dzierżawy z puli. + - Uruchamia linię live QA dla Telegram względem rzeczywistej prywatnej grupy przy użyciu tokenów bota driver i SUT z env. + - Wymaga `OPENCLAW_QA_TELEGRAM_GROUP_ID`, `OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN` oraz `OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN`. Id grupy musi być numerycznym identyfikatorem czatu Telegram. + - Obsługuje `--credential-source convex` dla współdzielonych poświadczeń z puli. Domyślnie używaj trybu env albo ustaw `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`, aby włączyć współdzielone dzierżawy. - Wymaga dwóch różnych botów w tej samej prywatnej grupie, przy czym bot SUT musi udostępniać nazwę użytkownika Telegram. - - Aby zapewnić stabilną obserwację bot-bot, włącz Bot-to-Bot Communication Mode w `@BotFather` dla obu botów i upewnij się, że bot driver może obserwować ruch botów w grupie. - - Zapisuje raport QA Telegram, podsumowanie oraz artefakt obserwowanych wiadomości w `.artifacts/qa-e2e/...`. + - Aby zapewnić stabilną obserwację bot-do-bot, włącz Bot-to-Bot Communication Mode w `@BotFather` dla obu botów i upewnij się, że bot driver może obserwować ruch botów w grupie. + - Zapisuje raport QA dla Telegram, podsumowanie i artefakt obserwowanych wiadomości w `.artifacts/qa-e2e/...`. -Linie live dla transportów współdzielą jeden standardowy kontrakt, aby nowe transporty nie dryfowały. +Linie live transportu współdzielą jeden standardowy kontrakt, aby nowe transporty nie rozjeżdżały się: -`qa-channel` pozostaje szerokim syntetycznym pakietem QA i nie jest częścią macierzy pokrycia live dla transportów. +`qa-channel` pozostaje szerokim syntetycznym pakietem QA i nie jest częścią macierzy pokrycia live transportu. -| Linia | Canary | Bramka wzmianek | Blokada allowlist | Odpowiedź najwyższego poziomu | Wznowienie po restarcie | Kontynuacja wątku | Izolacja wątku | Obserwacja reakcji | Polecenie pomocy | -| -------- | ------ | --------------- | ----------------- | ----------------------------- | ----------------------- | ----------------- | -------------- | ------------------ | ---------------- | -| Matrix | x | x | x | x | x | x | x | x | | -| Telegram | x | | | | | | | | x | +| Linia | Canary | Gating wzmianek | Blokada allowlist | Odpowiedź najwyższego poziomu | Wznowienie po restarcie | Dalszy ciąg w wątku | Izolacja wątku | Obserwacja reakcji | Polecenie pomocy | +| -------- | ------ | ---------------- | ----------------- | ----------------------------- | ----------------------- | ------------------- | -------------- | ------------------ | ---------------- | +| Matrix | x | x | x | x | x | x | x | x | | +| Telegram | x | | | | | | | | x | ### Współdzielone poświadczenia Telegram przez Convex (v1) -Gdy `--credential-source convex` (lub `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`) jest włączone dla -`openclaw qa telegram`, laboratorium QA pobiera wyłączną dzierżawę z puli opartej na Convex, wysyła Heartbeat -tej dzierżawy, gdy linia działa, i zwalnia dzierżawę przy zamykaniu. +Gdy dla `openclaw qa telegram` włączone jest `--credential-source convex` (lub `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`), +QA lab pobiera wyłączną dzierżawę z puli opartej na Convex, wysyła Heartbeat +tej dzierżawy podczas działania linii i zwalnia ją przy zamknięciu. -Referencyjny szkielet projektu Convex: +Szkielet referencyjnego projektu Convex: - `qa/convex-credential-broker/` @@ -116,10 +119,10 @@ Opcjonalne zmienne środowiskowe: - `OPENCLAW_QA_CREDENTIAL_ACQUIRE_TIMEOUT_MS` (domyślnie `90000`) - `OPENCLAW_QA_CREDENTIAL_HTTP_TIMEOUT_MS` (domyślnie `15000`) - `OPENCLAW_QA_CONVEX_ENDPOINT_PREFIX` (domyślnie `/qa-credentials/v1`) -- `OPENCLAW_QA_CREDENTIAL_OWNER_ID` (opcjonalny identyfikator śledzenia) -- `OPENCLAW_QA_ALLOW_INSECURE_HTTP=1` pozwala na adresy URL Convex `http://` w local loopback wyłącznie do lokalnego developmentu. +- `OPENCLAW_QA_CREDENTIAL_OWNER_ID` (opcjonalny trace id) +- `OPENCLAW_QA_ALLOW_INSECURE_HTTP=1` pozwala na adresy Convex `http://` na loopback tylko do lokalnego developmentu. -`OPENCLAW_QA_CONVEX_SITE_URL` powinien używać `https://` w normalnej pracy. +`OPENCLAW_QA_CONVEX_SITE_URL` powinno używać `https://` podczas normalnej pracy. Polecenia administracyjne maintainera (dodawanie/usuwanie/listowanie puli) wymagają konkretnie `OPENCLAW_QA_CONVEX_SECRET_MAINTAINER`. @@ -139,7 +142,7 @@ Domyślny kontrakt endpointu (`OPENCLAW_QA_CONVEX_SITE_URL` + `/qa-credentials/v - `POST /acquire` - Żądanie: `{ kind, ownerId, actorRole, leaseTtlMs, heartbeatIntervalMs }` - Sukces: `{ status: "ok", credentialId, leaseToken, payload, leaseTtlMs?, heartbeatIntervalMs? }` - - Wyczerpanie/możliwość ponowienia: `{ status: "error", code: "POOL_EXHAUSTED" | "NO_CREDENTIAL_AVAILABLE", ... }` + - Wyczerpane/możliwe do ponowienia: `{ status: "error", code: "POOL_EXHAUSTED" | "NO_CREDENTIAL_AVAILABLE", ... }` - `POST /heartbeat` - Żądanie: `{ kind, ownerId, actorRole, credentialId, leaseToken, leaseTtlMs }` - Sukces: `{ status: "ok" }` (lub puste `2xx`) @@ -160,7 +163,7 @@ Domyślny kontrakt endpointu (`OPENCLAW_QA_CONVEX_SITE_URL` + `/qa-credentials/v Kształt payload dla rodzaju Telegram: - `{ groupId: string, driverToken: string, sutToken: string }` -- `groupId` musi być ciągiem znaków będącym numerycznym identyfikatorem czatu Telegram. +- `groupId` musi być ciągiem znaków z numerycznym identyfikatorem czatu Telegram. - `admin/add` waliduje ten kształt dla `kind: "telegram"` i odrzuca nieprawidłowy payload. ### Dodawanie kanału do QA @@ -170,45 +173,50 @@ Dodanie kanału do markdownowego systemu QA wymaga dokładnie dwóch rzeczy: 1. Adaptera transportu dla kanału. 2. Pakietu scenariuszy, który testuje kontrakt kanału. -Nie dodawaj uruchamiacza QA specyficznego dla kanału, jeśli wspólny uruchamiacz `qa-lab` +Nie dodawaj nowego głównego korzenia poleceń QA, jeśli współdzielony host `qa-lab` może obsłużyć ten przepływ. -`qa-lab` odpowiada za wspólną mechanikę: +`qa-lab` jest właścicielem współdzielonej mechaniki hosta: -- uruchamianie i zamykanie pakietu -- współbieżność workerów -- zapisywanie artefaktów -- generowanie raportów -- wykonywanie scenariuszy -- aliasy zgodności dla starszych scenariuszy `qa-channel` +- korzenia poleceń `openclaw qa` +- uruchamiania i zamykania pakietu +- współbieżności workerów +- zapisu artefaktów +- generowania raportów +- wykonywania scenariuszy +- aliasów kompatybilności dla starszych scenariuszy `qa-channel` -Adapter kanału odpowiada za kontrakt transportu: +Plugin runnera są właścicielem kontraktu transportu: +- jak `openclaw qa ` jest montowane pod współdzielonym korzeniem `qa` - jak Gateway jest konfigurowany dla tego transportu - jak sprawdzana jest gotowość - jak wstrzykiwane są zdarzenia przychodzące - jak obserwowane są wiadomości wychodzące -- jak udostępniane są transkrypcje i znormalizowany stan transportu +- jak udostępniane są transkrypty i znormalizowany stan transportu - jak wykonywane są akcje oparte na transporcie -- jak obsługiwany jest reset lub czyszczenie specyficzne dla transportu +- jak obsługiwany jest reset lub cleanup specyficzny dla transportu Minimalny próg wdrożenia dla nowego kanału to: -1. Zaimplementować adapter transportu na wspólnej granicy `qa-lab`. -2. Zarejestrować adapter w rejestrze transportów. -3. Zachować mechanikę specyficzną dla transportu wewnątrz adaptera lub harnessu kanału. -4. Napisać lub dostosować scenariusze markdown w `qa/scenarios/`. -5. Używać ogólnych helperów scenariuszy dla nowych scenariuszy. -6. Zachować działanie istniejących aliasów zgodności, chyba że repozytorium przeprowadza zamierzoną migrację. +1. Zachować `qa-lab` jako właściciela współdzielonego korzenia `qa`. +2. Zaimplementować runner transportu na współdzielonym seam hosta `qa-lab`. +3. Zachować mechanikę specyficzną dla transportu wewnątrz Plugin runnera lub harness kanału. +4. Montować runner jako `openclaw qa ` zamiast rejestrować konkurencyjny korzeń poleceń. + Plugin runnera powinny deklarować `qaRunners` w `openclaw.plugin.json` oraz eksportować odpowiadającą tablicę `qaRunnerCliRegistrations` z `runtime-api.ts`. + `runtime-api.ts` powinien pozostać lekki; leniwe wykonanie CLI i runnera powinno być ukryte za oddzielnymi punktami wejścia. +5. Tworzyć lub adaptować scenariusze markdown w `qa/scenarios/`. +6. Używać generycznych helperów scenariuszy dla nowych scenariuszy. +7. Zachować działanie istniejących aliasów kompatybilności, chyba że repo przechodzi celową migrację. -Zasada decyzyjna jest ścisła: +Reguła decyzyjna jest ścisła: - Jeśli zachowanie można wyrazić raz w `qa-lab`, umieść je w `qa-lab`. -- Jeśli zachowanie zależy od jednego transportu kanału, zachowaj je w tym adapterze lub harnessie Plugin. -- Jeśli scenariusz wymaga nowej możliwości, z której może skorzystać więcej niż jeden kanał, dodaj ogólny helper zamiast gałęzi specyficznej dla kanału w `suite.ts`. -- Jeśli zachowanie ma sens tylko dla jednego transportu, zachowaj scenariusz jako specyficzny dla tego transportu i zaznacz to wyraźnie w kontrakcie scenariusza. +- Jeśli zachowanie zależy od transportu jednego kanału, pozostaw je w Plugin runnera lub harness transportu. +- Jeśli scenariusz potrzebuje nowej możliwości, z której może skorzystać więcej niż jeden kanał, dodaj generyczny helper zamiast gałęzi specyficznej dla kanału w `suite.ts`. +- Jeśli zachowanie ma sens tylko dla jednego transportu, pozostaw scenariusz specyficzny dla tego transportu i jasno zaznacz to w kontrakcie scenariusza. -Preferowane nazwy ogólnych helperów dla nowych scenariuszy to: +Preferowane nazwy generycznych helperów dla nowych scenariuszy to: - `waitForTransportReady` - `waitForChannelReady` @@ -223,7 +231,7 @@ Preferowane nazwy ogólnych helperów dla nowych scenariuszy to: - `formatTransportTranscript` - `resetTransport` -Aliasy zgodności pozostają dostępne dla istniejących scenariuszy, w tym: +Aliasy kompatybilności pozostają dostępne dla istniejących scenariuszy, w tym: - `waitForQaChannelReady` - `waitForOutboundMessage` @@ -231,65 +239,65 @@ Aliasy zgodności pozostają dostępne dla istniejących scenariuszy, w tym: - `formatConversationTranscript` - `resetBus` -Nowa praca nad kanałami powinna używać ogólnych nazw helperów. -Aliasy zgodności istnieją po to, aby uniknąć migracji typu flag day, a nie jako model +Nowe prace nad kanałami powinny używać generycznych nazw helperów. +Aliasy kompatybilności istnieją po to, aby uniknąć migracji typu flag day, a nie jako model dla tworzenia nowych scenariuszy. -## Pakiety testów (co uruchamia się gdzie) +## Pakiety testowe (co uruchamia się gdzie) -O pakietach warto myśleć jako o „rosnącym realizmie” (oraz rosnącej podatności na błędy/niestabilność i koszcie): +O pakietach myśl jak o „rosnącym realizmie” (oraz rosnącej niestabilności/koszcie): ### Unit / integration (domyślne) - Polecenie: `pnpm test` - Konfiguracja: dziesięć sekwencyjnych uruchomień shardów (`vitest.full-*.config.ts`) na istniejących zakresowanych projektach Vitest -- Pliki: inwentarze core/unit w `src/**/*.test.ts`, `packages/**/*.test.ts`, `test/**/*.test.ts` oraz umieszczone na allowliście testy node w `ui`, objęte przez `vitest.unit.config.ts` +- Pliki: inwentarze core/unit w `src/**/*.test.ts`, `packages/**/*.test.ts`, `test/**/*.test.ts` oraz dopuszczone testy node w `ui` objęte przez `vitest.unit.config.ts` - Zakres: - Czyste testy unit - - Testy integracyjne in-process (uwierzytelnianie Gateway, routing, narzędzia, parsowanie, konfiguracja) - - Deterministyczne testy regresji dla znanych błędów + - Testy integracyjne w procesie (uwierzytelnianie Gateway, routing, narzędzia, parsowanie, konfiguracja) + - Deterministyczne regresje dla znanych błędów - Oczekiwania: - Uruchamia się w CI - Nie wymaga prawdziwych kluczy - - Powinno być szybkie i stabilne + - Powinien być szybki i stabilny - Uwaga o projektach: - - Niekierunkowane `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`/rozszerzeń zagłodziły niezwiązane pakiety. - - `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 zakresowane linie, dzięki czemu `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` nie płaci kosztu uruchomienia pełnego root project. - - `pnpm test:changed` rozwija zmienione ścieżki git do tych samych zakresowanych linii, gdy diff dotyczy tylko routowalnych plików źródłowych/testowych; edycje konfiguracji/ustawień nadal przechodzą do szerokiego ponownego uruchomienia root project. - - Lekkie importowo testy unit z agentów, poleceń, pluginów, helperów `auto-reply`, `plugin-sdk` i podobnych czystych obszarów narzędziowych są kierowane przez linię `unit-fast`, która pomija `test/setup-openclaw-runtime.ts`; pliki stanowe/ciężkie runtime pozostają na istniejących liniach. - - Wybrane pliki źródłowe helperów `plugin-sdk` i `commands` również mapują uruchomienia trybu changed do jawnych sąsiednich testów w tych lekkich liniach, dzięki czemu edycje helperów nie wymuszają ponownego uruchamiania całego ciężkiego pakietu dla tego katalogu. - - `auto-reply` ma teraz trzy dedykowane koszyki: helpery core najwyższego poziomu, testy integracyjne najwyższego poziomu `reply.*` oraz poddrzewo `src/auto-reply/reply/**`. Dzięki temu najcięższa praca harnessu odpowiedzi nie trafia do tanich testów status/chunk/token. -- Uwaga o osadzonym uruchamiaczu: + - Niezakresowane `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 projektu głównego. To zmniejsza szczytowe RSS na obciążonych maszynach i zapobiega temu, by prace auto-reply/extension zagłodziły niezwiązane pakiety. + - `pnpm test --watch` nadal używa natywnego grafu projektów głównego `vitest.config.ts`, ponieważ wieloshardowa 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 zakresowane linie, więc `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` unika kosztu uruchamiania pełnego projektu głównego. + - `pnpm test:changed` rozwija zmienione ścieżki git do tych samych zakresowanych linii, gdy diff dotyczy wyłącznie routowalnych plików źródłowych/testowych; edycje konfiguracji/setup nadal wracają do szerokiego ponownego uruchomienia projektu głównego. + - Lekkie importowo testy unit z agents, commands, plugins, helperów auto-reply, `plugin-sdk` i podobnych czysto narzędziowych obszarów są kierowane do linii `unit-fast`, która pomija `test/setup-openclaw-runtime.ts`; pliki stanowe/ciężkie runtime pozostają na istniejących liniach. + - Wybrane pliki źródłowe helperów `plugin-sdk` i `commands` mapują również uruchomienia changed-mode do jawnych testów sąsiednich w tych lekkich liniach, więc edycje helperów nie powodują ponownego uruchamiania pełnego ciężkiego pakietu dla tego katalogu. + - `auto-reply` ma teraz trzy dedykowane koszyki: helpery core najwyższego poziomu, testy integracyjne `reply.*` najwyższego poziomu oraz poddrzewo `src/auto-reply/reply/**`. Dzięki temu najcięższa praca harness reply nie trafia do tanich testów status/chunk/token. +- Uwaga o osadzonym runnerze: - Gdy zmieniasz wejścia wykrywania message-tool lub kontekst runtime Compaction, utrzymuj oba poziomy pokrycia. - - Dodawaj ukierunkowane testy regresji helperów dla czystych granic routingu/normalizacji. - - Utrzymuj też w dobrej kondycji pakiety integracyjne osadzonego uruchamiacza: + - Dodawaj skoncentrowane regresje helperów dla czystych granic routingu/normalizacji. + - Utrzymuj też w dobrym stanie osadzone pakiety integracyjne runnera: `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 pakiety weryfikują, że zakresowane identyfikatory i zachowanie Compaction nadal przepływają - przez rzeczywiste ścieżki `run.ts` / `compact.ts`; same testy helperów nie są - wystarczającym zamiennikiem dla tych ścieżek integracyjnych. + przez rzeczywiste ścieżki `run.ts` / `compact.ts`; testy samych helperów nie są + wystarczającym substytutem dla tych ścieżek integracyjnych. - Uwaga o puli: - Bazowa konfiguracja Vitest domyślnie używa teraz `threads`. - - Współdzielona konfiguracja Vitest ustawia również `isolate: false` i używa nieizolowanego uruchamiacza w projektach root, konfiguracjach e2e i live. - - Główna linia UI zachowuje konfigurację `jsdom` i optimizer, ale teraz również działa na współdzielonym nieizolowanym uruchamiaczu. + - Współdzielona konfiguracja Vitest ustawia także `isolate: false` i używa nieizolowanego runnera w projektach głównych, konfiguracjach e2e oraz live. + - Główna linia UI zachowuje swój setup `jsdom` i optimizer, 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ć narzut kompilacji V8 podczas dużych lokalnych uruchomień. Ustaw `OPENCLAW_VITEST_ENABLE_MAGLEV=1`, jeśli chcesz porównać zachowanie z domyślnym V8. -- Uwaga o szybkiej iteracji lokalnej: - - `pnpm test:changed` kieruje przez zakresowane linie, gdy zmienione ścieżki czysto mapują się na mniejszy pakiet. - - `pnpm test:max` i `pnpm test:changed:max` zachowują to samo kierowanie, tylko z wyższym limitem workerów. - - Automatyczne skalowanie lokalnych workerów jest teraz celowo konserwatywne i dodatkowo zwalnia, gdy średnie obciążenie hosta jest już wysokie, dzięki czemu wiele równoczesnych 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, gdy zmienia się okablowanie 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 jeden jawny katalog cache do bezpośredniego profilowania. + - 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 zakresowane linie, gdy zmienione ścieżki da się jednoznacznie odwzorować na mniejszy pakiet. + - `pnpm test:max` i `pnpm test:changed:max` zachowują to samo zachowanie routingu, tylko z wyższym limitem workerów. + - Automatyczne skalowanie lokalnych workerów jest teraz celowo zachowawcze i dodatkowo wycofuje się, gdy średnie obciążenie hosta jest już wysokie, dzięki czemu wiele równoległych uruchomień Vitest domyślnie wyrządza mniej szkód. + - Bazowa konfiguracja Vitest oznacza projekty/pliki konfiguracyjne jako `forceRerunTriggers`, aby ponowne uruchomienia w trybie changed pozostawały poprawne po zmianach okablowania 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ą jawnie wskazaną lokalizację cache do bezpośredniego profilowania. - Uwaga o debugowaniu wydajności: - - `pnpm test:perf:imports` włącza raportowanie czasu importu Vitest oraz wynik z podziałem importów. + - `pnpm test:perf:imports` włącza raportowanie czasu importu przez Vitest oraz wynik z podziałem 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 czas ścienny 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` oraz główną konfigurację Vitest. +- `pnpm test:perf:changed:bench -- --ref ` porównuje routowane `test:changed` z natywną ścieżką projektu głównego dla diffu tego commita i wypisuje wall time oraz maksymalne RSS na macOS. +- `pnpm test:perf:changed:bench -- --worktree` wykonuje benchmark bieżącego brudnego drzewa, 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 narzutu uruchamiania i transformacji Vitest/Vite. - - `pnpm test:perf:profile:runner` zapisuje profile CPU+heap uruchamiacza dla pakietu unit z wyłączoną równoległością plików. + - `pnpm test:perf:profile:runner` zapisuje profile CPU+heap runnera dla pakietu unit przy wyłączonej równoległości plików. ### E2E (smoke Gateway) @@ -297,35 +305,35 @@ O pakietach warto myśleć jako o „rosnącym realizmie” (oraz rosnącej poda - Konfiguracja: `vitest.e2e.config.ts` - Pliki: `src/**/*.e2e.test.ts`, `test/**/*.e2e.test.ts` - Domyślne ustawienia runtime: - - Używa Vitest `threads` z `isolate: false`, zgodnie z resztą repozytorium. - - Używa adaptacyjnej liczby workerów (CI: do 2, lokalnie: domyślnie 1). - - Domyślnie działa w trybie cichym, aby ograniczyć narzut I/O konsoli. + - Używa Vitest `threads` z `isolate: false`, zgodnie z resztą repo. + - Używa adaptacyjnych workerów (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ółowy wynik konsoli. + - `OPENCLAW_E2E_WORKERS=`, aby wymusić liczbę workerów (limit do 16). + - `OPENCLAW_E2E_VERBOSE=1`, aby ponownie włączyć szczegółowy output konsoli. - Zakres: - - Zachowanie end-to-end Gateway z wieloma instancjami - - Powierzchnie WebSocket/HTTP, parowanie Node oraz cięższa komunikacja sieciowa + - Zachowanie end-to-end Gateway w wielu instancjach + - Powierzchnie WebSocket/HTTP, parowanie node i cięższa sieć - Oczekiwania: - Uruchamia się w CI (gdy jest włączone w pipeline) - Nie wymaga prawdziwych kluczy - - Ma więcej ruchomych części niż testy unit (może być wolniejsze) + - Ma więcej ruchomych części niż testy unit (może być wolniejszy) ### E2E: smoke backendu OpenShell - Polecenie: `pnpm test:e2e:openshell` - Plik: `test/openshell-sandbox.e2e.test.ts` - Zakres: - - Uruchamia na hoście izolowany Gateway OpenShell przez Docker + - Uruchamia izolowany Gateway OpenShell na hoście przez Docker - Tworzy sandbox z tymczasowego lokalnego Dockerfile - - Testuje backend OpenShell w OpenClaw przez rzeczywiste `sandbox ssh-config` + wykonanie SSH - - Weryfikuje zdalnie kanoniczne zachowanie systemu plików przez most fs sandboxa + - Testuje backend OpenShell OpenClaw przez rzeczywiste `sandbox ssh-config` + wykonanie SSH + - Weryfikuje zdalno-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 izolowanych `HOME` / `XDG_CONFIG_HOME`, a następnie niszczy testowy Gateway i sandbox - Przydatne nadpisania: - - `OPENCLAW_E2E_OPENSHELL=1`, aby włączyć test przy ręcznym uruchamianiu szerszego pakietu e2e + - `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 wrappera ### Live (rzeczywiści dostawcy + rzeczywiste modele) @@ -335,109 +343,109 @@ O pakietach warto myśleć jako o „rosnącym realizmie” (oraz rosnącej poda - 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?” - - Wychwytywanie zmian formatu dostawcy, niuansów wywołań narzędzi, problemów z uwierzytelnianiem oraz zachowania limitów szybkości + - „Czy ten dostawca/model rzeczywiście działa _dzisiaj_ z prawdziwymi poświadczeniami?” + - Wychwytywanie zmian formatu po stronie dostawcy, osobliwości wywoływania narzędzi, problemów z uwierzytelnianiem i zachowania limitów szybkości - Oczekiwania: - Z założenia niestabilne w CI (rzeczywiste sieci, rzeczywiste polityki dostawców, limity, awarie) - - Kosztują pieniądze / zużywają limity szybkości - - Lepiej uruchamiać zawężone podzbiory zamiast „wszystkiego” -- Uruchomienia live pobierają `~/.profile`, aby przejąć brakujące klucze API. -- Domyślnie uruchomienia live nadal izolują `HOME` i kopiują materiały konfiguracji/uwierzytelniania do tymczasowego katalogu testowego, aby fixture unit nie mogły modyfikować twojego rzeczywistego `~/.openclaw`. -- Ustaw `OPENCLAW_LIVE_USE_REAL_HOME=1` tylko wtedy, gdy celowo chcesz, by testy live używały twojego rzeczywistego katalogu domowego. -- `pnpm test:live` domyślnie działa teraz w cichszym trybie: zachowuje wynik postępu `[live] ...`, ale ukrywa dodatkowy komunikat o `~/.profile` i wycisza logi bootstrapu Gateway/hałas Bonjour. Ustaw `OPENCLAW_LIVE_TEST_QUIET=0`, jeśli chcesz z powrotem pełne logi startowe. -- Rotacja kluczy API (specyficzna dla dostawcy): ustaw `*_API_KEYS` w formacie rozdzielanym przecinkami/średnikami albo `*_API_KEY_1`, `*_API_KEY_2` (na przykład `OPENAI_API_KEYS`, `ANTHROPIC_API_KEYS`, `GEMINI_API_KEYS`) lub nadpisanie per-live przez `OPENCLAW_LIVE_*_KEY`; testy ponawiają próby przy odpowiedziach z limitem szybkości. -- Wynik postępu/Heartbeat: - - Pakiety live emitują teraz linie postępu do stderr, dzięki czemu długie wywołania dostawców są widocznie aktywne, nawet gdy przechwytywanie konsoli Vitest jest wyciszone. - - `vitest.live.config.ts` wyłącza przechwytywanie konsoli przez Vitest, dzięki czemu linie postępu dostawcy/Gateway są strumieniowane natychmiast podczas uruchomień live. - - Dostosuj Heartbeat dla bezpośrednich modeli przez `OPENCLAW_LIVE_HEARTBEAT_MS`. - - Dostosuj Heartbeat dla Gateway/sond przez `OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS`. + - Kosztuje pieniądze / zużywa limity szybkości + - Lepiej uruchamiać zawężone podzbiory niż „wszystko” +- Uruchomienia live pobierają `~/.profile`, aby przechwycić brakujące klucze API. +- Domyślnie uruchomienia live nadal izolują `HOME` i kopiują materiał konfiguracyjny/uwierzytelniający do tymczasowego katalogu testowego, tak aby fixture unit nie mogły modyfikować rzeczywistego `~/.openclaw`. +- Ustaw `OPENCLAW_LIVE_USE_REAL_HOME=1` tylko wtedy, gdy świadomie chcesz, aby testy live używały twojego rzeczywistego katalogu domowego. +- `pnpm test:live` domyślnie używa teraz cichszego trybu: zachowuje output postępu `[live] ...`, ale ukrywa dodatkowy komunikat o `~/.profile` i wycisza logi bootstrapu Gateway oraz komunikaty Bonjour. Ustaw `OPENCLAW_LIVE_TEST_QUIET=0`, jeśli chcesz z powrotem pełne logi uruchomieniowe. +- Rotacja kluczy API (specyficzna dla dostawcy): ustaw `*_API_KEYS` w formacie rozdzielanym przecinkami/średnikami albo `*_API_KEY_1`, `*_API_KEY_2` (na przykład `OPENAI_API_KEYS`, `ANTHROPIC_API_KEYS`, `GEMINI_API_KEYS`) lub nadpisanie per-live przez `OPENCLAW_LIVE_*_KEY`; testy ponawiają próbę po odpowiedziach z limitem szybkości. +- Output postępu/Heartbeat: + - Pakiety live emitują teraz linie postępu na 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, aby linie postępu dostawcy/Gateway były przesyłane natychmiast podczas uruchomień live. + - Dostosuj Heartbeat bezpośredniego modelu przez `OPENCLAW_LIVE_HEARTBEAT_MS`. + - Dostosuj Heartbeat Gateway/sond przez `OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS`. ## Który pakiet powinienem uruchomić? Użyj tej tabeli decyzyjnej: -- Edycja logiki/testów: uruchom `pnpm test` (oraz `pnpm test:coverage`, jeśli zmieniłeś dużo) -- Zmiany w komunikacji sieciowej Gateway / protokole WS / parowaniu: dodaj `pnpm test:e2e` -- Debugowanie „mój bot nie działa” / błędów specyficznych dla dostawcy / wywołań narzędzi: uruchom zawężone `pnpm test:live` +- Edycja logiki/testów: uruchom `pnpm test` (oraz `pnpm test:coverage`, jeśli zmieniło się dużo) +- Dotykanie sieci 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` -## Live: przegląd możliwości Android Node +## Live: przegląd możliwości node Android - Test: `src/gateway/android-node.capabilities.live.test.ts` - Skrypt: `pnpm android:test:integration` -- Cel: wywołać **każde polecenie aktualnie ogłaszane** przez podłączony Android Node i sprawdzić zachowanie kontraktu poleceń. +- Cel: wywołać **każde polecenie aktualnie reklamowane** przez podłączony node Android i sprawdzić zachowanie kontraktu polecenia. - Zakres: - Wstępnie przygotowana/ręczna konfiguracja (pakiet nie instaluje, nie uruchamia ani nie paruje aplikacji). - - Walidacja `node.invoke` Gateway polecenie po poleceniu dla wybranego Android Node. -- Wymagane przygotowanie: + - Walidacja `node.invoke` Gateway polecenie po poleceniu dla wybranego node Android. +- Wymagana wcześniejsza konfiguracja: - Aplikacja Android jest już połączona i sparowana z Gateway. - Aplikacja pozostaje na pierwszym planie. - - Uprawnienia/zgody na przechwytywanie zostały przyznane dla możliwości, które mają przechodzić. + - Uprawnienia/zgoda na przechwytywanie zostały 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 Android: [Android App](/pl/platforms/android) +- Pełne szczegóły konfiguracji Androida: [Android App](/pl/platforms/android) -## Live: smoke modeli (klucze profili) +## Live: smoke modelu (klucze profilu) Testy live są podzielone na dwie warstwy, aby można było izolować błędy: -- „Direct model” mówi nam, czy dostawca/model w ogóle potrafi odpowiedzieć przy danym kluczu. -- „Gateway smoke” mówi nam, czy pełny pipeline gateway+agent działa dla tego modelu (sesje, historia, narzędzia, polityka sandbox itd.). +- „Direct model” mówi nam, czy dostawca/model w ogóle potrafi odpowiedzieć przy użyciu danego klucza. +- „Gateway smoke” mówi nam, czy pełny pipeline gateway+agent działa dla tego modelu (sesje, historia, narzędzia, polityka sandboxa itd.). ### Warstwa 1: bezpośrednie ukończenie modelu (bez Gateway) - Test: `src/agents/models.profiles.live.test.ts` - Cel: - - Wyliczać wykryte modele - - Używać `getApiKeyForModel` do wyboru modeli, dla których masz poświadczenia - - Wykonywać małe ukończenie dla każdego modelu (oraz ukierunkowane testy regresji tam, gdzie to potrzebne) + - Wyliczyć wykryte modele + - Użyć `getApiKeyForModel` do wyboru modeli, dla których masz poświadczenia + - Uruchomić małe ukończenie dla każdego modelu (oraz ukierunkowane regresje tam, gdzie to potrzebne) - 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 pakiet; w przeciwnym razie zostanie pominięty, aby `pnpm test:live` było skupione na smoke Gateway + - `pnpm test:live` (albo `OPENCLAW_LIVE_TEST=1`, jeśli wywołujesz Vitest bezpośrednio) +- Ustaw `OPENCLAW_LIVE_MODELS=modern` (lub `all`, alias dla modern), aby rzeczywiście uruchomić ten pakiet; w przeciwnym razie zostanie pominięty, aby `pnpm test:live` pozostawało skupione na smoke Gateway - 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 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ą kuratorowanego limitu o wysokim sygnale; ustaw `OPENCLAW_LIVE_MAX_MODELS=0` dla wyczerpującego przeglądu modern albo dodatnią liczbę dla mniejszego limitu. + - `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) + - Przeglądy modern/all domyślnie używają wyselekcjonowanego limitu o wysokim sygnale; ustaw `OPENCLAW_LIVE_MAX_MODELS=0` dla wyczerpującego przeglądu modern lub dodatnią liczbę dla mniejszego limitu. - Jak wybierać dostawców: - - `OPENCLAW_LIVE_PROVIDERS="google,google-antigravity,google-gemini-cli"` (allowlista rozdzielana przecinkami) + - `OPENCLAW_LIVE_PROVIDERS="google,google-antigravity,google-gemini-cli"` (allowlist rozdzielana przecinkami) - Skąd pochodzą klucze: - - Domyślnie: magazyn profili i fallbacki env - - Ustaw `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, aby wymusić wyłącznie **magazyn profili** -- Po co to istnieje: + - Domyślnie: store profili i zapasowe wartości z env + - Ustaw `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, aby wymusić wyłącznie **store profili** +- Dlaczego to istnieje: - Oddziela „API dostawcy jest zepsute / klucz jest nieprawidłowy” od „pipeline agenta Gateway jest zepsuty” - - Zawiera małe, izolowane testy regresji (przykład: replay rozumowania OpenAI Responses/Codex Responses + przepływy wywołań narzędzi) + - Zawiera małe, izolowane regresje (przykład: replay rozumowania OpenAI Responses/Codex Responses + przepływy tool-call) -### Warstwa 2: smoke Gateway + agenta developerskiego (to, co faktycznie robi „@openclaw”) +### Warstwa 2: Gateway + smoke agenta dev (to, co faktycznie robi „@openclaw”) - Test: `src/gateway/gateway-models.profiles.live.test.ts` - Cel: - - Uruchomić in-process Gateway - - Utworzyć/spatchować sesję `agent:dev:*` (nadpisanie modelu dla każdego uruchomienia) - - Iterować po modelach-z-kluczami i sprawdzać: + - Uruchomić Gateway w procesie + - Utworzyć/zmodyfikować sesję `agent:dev:*` (nadpisanie modelu dla każdego uruchomienia) + - Iterować po modelach-z-kluczami i potwierdzić: - „sensowną” odpowiedź (bez narzędzi) - - że rzeczywiste wywołanie narzędzia działa (sonda odczytu) + - że działa rzeczywiste wywołanie narzędzia (sonda odczytu) - opcjonalne dodatkowe sondy narzędzi (sonda exec+read) - - że ścieżki regresji OpenAI (tylko tool-call → follow-up) nadal działają + - że ścieżki regresji OpenAI (tylko tool-call → dalszy ciąg) nadal działają - Szczegóły sond (aby można było szybko wyjaśniać błędy): - - sonda `read`: test zapisuje plik nonce w obszarze roboczym i prosi agenta o jego `read` oraz odesłanie nonce. - - sonda `exec+read`: test prosi agenta o zapisanie nonce do pliku tymczasowego przez `exec`, a następnie o jego odczytanie przez `read`. + - sonda `read`: test zapisuje plik nonce w workspace i prosi agenta, aby go `read` i odesłał nonce. + - sonda `exec+read`: test prosi agenta o zapisanie nonce do pliku tymczasowego przez `exec`, a następnie o odczytanie go przez `read`. - sonda obrazu: test dołącza wygenerowany PNG (kot + losowy kod) i oczekuje, że model zwróci `cat `. - - Referencja implementacyjna: `src/gateway/gateway-models.profiles.live.test.ts` oraz `src/gateway/live-image-probe.ts`. + - Referencja implementacyjna: `src/gateway/gateway-models.profiles.live.test.ts` i `src/gateway/live-image-probe.ts`. - Jak włączyć: - - `pnpm test:live` (lub `OPENCLAW_LIVE_TEST=1`, jeśli wywołujesz Vitest bezpośrednio) + - `pnpm test:live` (albo `OPENCLAW_LIVE_TEST=1`, jeśli wywołujesz Vitest bezpośrednio) - Jak wybierać modele: - - 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 + - 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 - Albo ustaw `OPENCLAW_LIVE_GATEWAY_MODELS="provider/model"` (lub listę rozdzielaną przecinkami), aby zawęzić - - Przeglądy gateway modern/all domyślnie używają kuratorowanego limitu o wysokim sygnale; ustaw `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=0` dla wyczerpującego przeglądu modern albo dodatnią liczbę dla mniejszego limitu. -- Jak wybierać dostawców (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: + - Przeglądy Gateway modern/all domyślnie używają wyselekcjonowanego limitu o wysokim sygnale; ustaw `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=0` dla wyczerpującego przeglądu modern lub dodatnią liczbę dla mniejszego limitu. +- Jak wybierać dostawców (unikaj „całego OpenRouter”): + - `OPENCLAW_LIVE_GATEWAY_PROVIDERS="google,google-antigravity,google-gemini-cli,openai,anthropic,zai,minimax"` (allowlist rozdzielana przecinkami) +- Sondy narzędzi + obrazu są w tym teście live zawsze włączone: - sonda `read` + sonda `exec+read` (obciążenie narzędzi) - - sonda obrazu działa, gdy model deklaruje obsługę wejścia obrazowego + - sonda obrazu uruchamia się, gdy model reklamuje obsługę wejścia obrazowego - Przepływ (na wysokim poziomie): - - Test generuje mały PNG z napisem „CAT” + losowym kodem (`src/gateway/live-image-probe.ts`) + - 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 do modelu multimodalną wiadomość użytkownika @@ -453,22 +461,22 @@ 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 przy użyciu lokalnego backendu CLI, bez naruszania domyślnej konfiguracji. -- Domyślne ustawienia smoke specyficzne dla backendu znajdują się w definicji `cli-backend.ts` należącej do odpowiedniego rozszerzenia. +- 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 extension. - Włączanie: - - `pnpm test:live` (lub `OPENCLAW_LIVE_TEST=1`, jeśli wywołujesz Vitest bezpośrednio) + - `pnpm test:live` (albo `OPENCLAW_LIVE_TEST=1`, jeśli wywołujesz Vitest bezpośrednio) - `OPENCLAW_LIVE_CLI_BACKEND=1` -- Domyślne ustawienia: +- Domyślne wartości: - Domyślny dostawca/model: `claude-cli/claude-sonnet-4-6` - - Zachowanie polecenia/argumentów/obrazu pochodzi z metadanych Plugin odpowiedzialnego za backend CLI. + - Zachowanie poleceń/argumentów/obrazów pochodzi z metadanych Plugin backendu CLI będącego właścicielem. - 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ć rzeczywisty 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 wstrzykiwanie 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 sterować sposobem przekazywania argumentów obrazów, 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_RESUME_PROBE=1`, aby wysłać drugą turę i zweryfikować przepływ wznawiania. - `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ć jej włączenie, gdy wybrany model obsługuje cel przełączenia). Przykład: @@ -496,28 +504,28 @@ pnpm test:docker:live-cli-backend:gemini Uwagi: -- Uruchamiacz Docker znajduje się w `scripts/test-live-cli-backend-docker.sh`. -- Uruchamia smoke live backendu CLI wewnątrz obrazu Docker repozytorium jako użytkownik nieuprzywilejowany `node`. -- Rozwiązuje metadane smoke CLI z odpowiedniego rozszerzenia, a następnie instaluje pasujący pakiet Linux CLI (`@anthropic-ai/claude-code`, `@openai/codex` lub `@google/gemini-cli`) do cache’owanego zapisywalnego prefiksu w `OPENCLAW_DOCKER_CLI_TOOLS_DIR` (domyślnie: `~/.cache/openclaw/docker-cli-tools`). -- `pnpm test:docker:live-cli-backend:claude-subscription` wymaga przenośnego OAuth subskrypcji Claude Code przez `~/.claude/.credentials.json` z `claudeAiOauth.subscriptionType` lub `CLAUDE_CODE_OAUTH_TOKEN` z `claude setup-token`. Najpierw potwierdza bezpośrednie `claude -p` w Docker, a następnie uruchamia dwie tury backendu CLI Gateway bez zachowywania zmiennych env z kluczem API Anthropic. Ta linia subskrypcyjna domyślnie wyłącza sondy Claude MCP/tool i obrazu, ponieważ Claude obecnie rozlicza użycie aplikacji zewnętrznych przez billing extra-usage zamiast zwykłych limitów planu subskrypcji. -- 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 patchuje sesję z Sonnet do Opus i sprawdza, czy wznowiona sesja nadal pamięta wcześniejszą notatkę. +- Runner Docker znajduje się w `scripts/test-live-cli-backend-docker.sh`. +- Uruchamia smoke live CLI-backend wewnątrz obrazu Docker repo jako nieuprzywilejowany użytkownik `node`. +- Rozpoznaje metadane smoke CLI od odpowiedniego extension, a następnie instaluje pasujący pakiet Linux CLI (`@anthropic-ai/claude-code`, `@openai/codex` lub `@google/gemini-cli`) do cache’owanego zapisywalnego prefiksu w `OPENCLAW_DOCKER_CLI_TOOLS_DIR` (domyślnie: `~/.cache/openclaw/docker-cli-tools`). +- `pnpm test:docker:live-cli-backend:claude-subscription` wymaga przenośnego OAuth subskrypcji Claude Code przez `~/.claude/.credentials.json` z `claudeAiOauth.subscriptionType` lub `CLAUDE_CODE_OAUTH_TOKEN` z `claude setup-token`. Najpierw potwierdza bezpośrednie `claude -p` w Docker, a następnie uruchamia dwie tury Gateway CLI-backend bez zachowywania zmiennych env klucza API Anthropic. Ta linia subskrypcyjna domyślnie wyłącza sondy Claude MCP/tool i obrazu, ponieważ Claude obecnie rozlicza użycie aplikacji firm trzecich przez dodatkowe opłaty usage zamiast zwykłych limitów planu subskrypcji. +- Smoke live CLI-backend 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 modyfikuje sesję z Sonnet na Opus i weryfikuje, że wznowiona sesja nadal pamięta wcześniejszą notatkę. ## Live: smoke powiązania ACP (`/acp spawn ... --bind here`) - Test: `src/gateway/gateway-acp-bind.live.test.ts` -- Cel: zweryfikować rzeczywisty przepływ powiązania rozmowy ACP z aktywnym agentem ACP: +- Cel: zweryfikować rzeczywisty przepływ bindowania konwersacji ACP z żywym 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 - - zweryfikować, że follow-up trafia do transkryptu powiązanej sesji ACP + - związać syntetyczną konwersację kanału wiadomości w miejscu + - wysłać zwykły dalszy ciąg w tej samej konwersacji + - zweryfikować, że dalszy ciąg trafia do transkryptu powiązanej sesji ACP - Włączanie: - `pnpm test:live src/gateway/gateway-acp-bind.live.test.ts` - `OPENCLAW_LIVE_ACP_BIND=1` -- Domyślne ustawienia: +- Domyślne wartości: - Agenci ACP w Docker: `claude,codex,gemini` - Agent ACP dla bezpośredniego `pnpm test:live ...`: `claude` - - Syntetyczny kanał: kontekst rozmowy w stylu Slack DM + - Kanał syntetyczny: kontekst konwersacji w stylu Slack DM - Backend ACP: `acpx` - Nadpisania: - `OPENCLAW_LIVE_ACP_BIND_AGENT=claude` @@ -526,8 +534,8 @@ Uwagi: - `OPENCLAW_LIVE_ACP_BIND_AGENTS=claude,codex,gemini` - `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND='npx -y @agentclientprotocol/claude-agent-acp@'` - Uwagi: - - Ta linia używa powierzchni `chat.send` Gateway z polami synthetic originating-route dostępnymi tylko dla administratora, dzięki czemu testy mogą dołączać kontekst kanału wiadomości bez udawania zewnętrznego dostarczenia. - - Gdy `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND` nie jest ustawione, test używa wbudowanego rejestru agentów Plugin `acpx` dla wybranego agenta harnessu ACP. + - Ta linia używa powierzchni gateway `chat.send` z polami synthetic originating-route tylko dla administratora, tak aby testy mogły dołączać kontekst kanału wiadomości bez udawania zewnętrznego dostarczenia. + - Gdy `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND` nie jest ustawione, test używa wbudowanego rejestru agentów Plugin `acpx` dla wybranego agenta harness ACP. Przykład: @@ -553,30 +561,30 @@ pnpm test:docker:live-acp-bind:gemini Uwagi dotyczące Docker: -- Uruchamiacz Docker znajduje się w `scripts/test-live-acp-bind-docker.sh`. -- Domyślnie uruchamia smoke powiązania ACP kolejno dla wszystkich obsługiwanych aktywnych agentów CLI: `claude`, `codex`, a następnie `gemini`. +- Runner Docker znajduje się w `scripts/test-live-acp-bind-docker.sh`. +- Domyślnie uruchamia smoke bind ACP względem wszystkich obsługiwanych żywych agentów CLI po kolei: `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. -- Pobiera `~/.profile`, przygotowuje pasujące materiały uwierzytelniające CLI w kontenerze, instaluje `acpx` do zapisywalnego prefiksu npm, a następnie instaluje żądane aktywne CLI (`@anthropic-ai/claude-code`, `@openai/codex` lub `@google/gemini-cli`), jeśli go brakuje. -- Wewnątrz Docker uruchamiacz ustawia `OPENCLAW_LIVE_ACP_BIND_ACPX_COMMAND=$HOME/.npm-global/bin/acpx`, aby `acpx` zachował zmienne env dostawcy z pobranego profilu dostępne dla podrzędnego CLI harnessu. +- Ładuje `~/.profile`, przygotowuje pasujący materiał uwierzytelniający CLI w kontenerze, instaluje `acpx` do zapisywalnego prefiksu npm, a następnie instaluje żądane live CLI (`@anthropic-ai/claude-code`, `@openai/codex` lub `@google/gemini-cli`), jeśli go brakuje. +- Wewnątrz Docker runner ustawia `OPENCLAW_LIVE_ACP_BIND_ACPX_COMMAND=$HOME/.npm-global/bin/acpx`, aby acpx zachował zmienne env dostawcy z załadowanego profilu dostępne dla podrzędnego CLI harness. -## Live: smoke harnessu app-server Codex +## Live: smoke harness app-server Codex -- Cel: zweryfikować należący do Plugin harness Codex przez normalną - metodę `agent` Gateway: - - załadować bundlowany Plugin `codex` +- Cel: zweryfikować należący do Plugin harness Codex przez zwykłą + metodę gateway `agent`: + - załadować dołączony Plugin `codex` - wybrać `OPENCLAW_AGENT_RUNTIME=codex` - - wysłać pierwszą turę agenta Gateway do `codex/gpt-5.4` - - wysłać drugą turę do tej samej sesji OpenClaw i zweryfikować, że wątek - app-server może zostać wznowiony - - uruchomić `/codex status` oraz `/codex models` przez tę samą ścieżkę - poleceń Gateway + - wysłać pierwszą turę agenta gateway do `codex/gpt-5.4` + - wysłać drugą turę do tej samej sesji OpenClaw i zweryfikować, że wątek app-server + może zostać wznowiony + - uruchomić `/codex status` i `/codex models` przez tę samą ścieżkę + poleceń gateway - Test: `src/gateway/gateway-codex-harness.live.test.ts` - Włączanie: `OPENCLAW_LIVE_CODEX_HARNESS=1` - Domyślny model: `codex/gpt-5.4` - Opcjonalna sonda obrazu: `OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=1` - Opcjonalna sonda MCP/tool: `OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=1` -- Ten smoke ustawia `OPENCLAW_AGENT_HARNESS_FALLBACK=none`, aby uszkodzony - harness Codex nie mógł przejść przez cichy fallback do PI. +- Ten smoke ustawia `OPENCLAW_AGENT_HARNESS_FALLBACK=none`, aby uszkodzony harness Codex + nie mógł przejść przez ciche przełączenie awaryjne na PI. - Uwierzytelnianie: `OPENAI_API_KEY` z powłoki/profilu oraz opcjonalnie skopiowane `~/.codex/auth.json` i `~/.codex/config.toml` @@ -600,18 +608,20 @@ pnpm test:docker:live-codex-harness Uwagi dotyczące Docker: -- Uruchamiacz Docker znajduje się w `scripts/test-live-codex-harness-docker.sh`. -- Pobiera zamontowane `~/.profile`, przekazuje `OPENAI_API_KEY`, kopiuje pliki - uwierzytelniające CLI Codex, gdy są dostępne, instaluje `@openai/codex` do zapisywalnego zamontowanego prefiksu npm, - przygotowuje drzewo źródłowe, a następnie uruchamia tylko test live harnessu Codex. +- Runner Docker znajduje się w `scripts/test-live-codex-harness-docker.sh`. +- Ładuje zamontowane `~/.profile`, przekazuje `OPENAI_API_KEY`, kopiuje pliki + uwierzytelniające CLI Codex, gdy są obecne, instaluje `@openai/codex` do zapisywalnego zamontowanego prefiksu npm, + przygotowuje drzewo źródłowe, a następnie uruchamia tylko test live Codex-harness. - Docker domyślnie włącza sondy obrazu oraz MCP/tool. Ustaw `OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=0` lub - `OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=0`, gdy potrzebujesz węższego uruchomienia debugowego. -- Docker eksportuje również `OPENCLAW_AGENT_HARNESS_FALLBACK=none`, zgodnie z konfiguracją testu live, aby fallback `openai-codex/*` lub PI nie mógł ukryć regresji harnessu Codex. + `OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=0`, gdy potrzebujesz węższego uruchomienia debugującego. +- Docker eksportuje także `OPENCLAW_AGENT_HARNESS_FALLBACK=none`, zgodnie z konfiguracją + testu live, tak aby przełączenie awaryjne `openai-codex/*` lub PI nie mogło ukryć regresji + harnessu Codex. ### Zalecane recepty live -Wąskie, jawne allowlisty są najszybsze i najmniej podatne na niestabilność: +Wąskie, jawne allowlist są najszybsze i najmniej niestabilne: - Pojedynczy model, bezpośrednio (bez Gateway): - `OPENCLAW_LIVE_MODELS="openai/gpt-5.4" pnpm test:live src/agents/models.profiles.live.test.ts` @@ -628,12 +638,12 @@ Wąskie, jawne allowlisty są najszybsze i najmniej podatne na niestabilność: Uwagi: -- `google/...` używa Gemini API (klucz API). +- `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 uwierzytelnianie + niuanse narzędzi). -- Gemini API vs Gemini CLI: - - API: OpenClaw wywołuje hostowane Gemini API Google przez HTTP (uwierzytelnianie kluczem API / profilem); 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 uwierzytelnianie i może zachowywać się inaczej (streaming/obsługa narzędzi/rozbieżność wersji). +- `google-gemini-cli/...` używa lokalnego CLI Gemini na twojej maszynie (oddzielne uwierzytelnianie + osobliwości narzędzi). +- API Gemini vs CLI Gemini: + - API: OpenClaw wywołuje hostowane API Gemini Google przez HTTP (klucz API / uwierzytelnianie profilu); 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 uwierzytelnianie i może zachowywać się inaczej (streaming/obsługa narzędzi/rozjazd wersji). ## Live: macierz modeli (co obejmujemy) @@ -641,22 +651,22 @@ Nie ma stałej „listy modeli CI” (live jest opt-in), ale to są **zalecane** ### Nowoczesny zestaw smoke (wywoływanie narzędzi + obraz) -To jest uruchomienie „typowych modeli”, które oczekujemy utrzymać w działaniu: +To jest uruchomienie „wspólnych modeli”, które powinno stale działać: - OpenAI (bez 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` 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` +- Google (API Gemini): `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` - Z.AI (GLM): `zai/glm-4.7` - MiniMax: `minimax/MiniMax-M2.7` Uruchom smoke Gateway 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` -### Linia bazowa: wywoływanie narzędzi (Read + opcjonalnie Exec) +### Bazowy zestaw: wywoływanie narzędzi (Read + opcjonalnie Exec) -Wybierz co najmniej jeden model z każdej rodziny dostawców: +Wybierz przynajmniej jeden model z każdej rodziny dostawców: - OpenAI: `openai/gpt-5.4` (lub `openai/gpt-5.4-mini`) - Anthropic: `anthropic/claude-opus-4-6` (lub `anthropic/claude-sonnet-4-6`) @@ -667,278 +677,281 @@ Wybierz co najmniej jeden model z każdej rodziny dostawców: Opcjonalne dodatkowe pokrycie (warto mieć): - xAI: `xai/grok-4` (lub najnowszy dostępny) -- Mistral: `mistral/`… (wybierz jeden model z włączoną obsługą „tools”, do którego masz dostęp) +- Mistral: `mistral/`… (wybierz jeden model zdolny do pracy z narzędziami, który masz włączony) - Cerebras: `cerebras/`… (jeśli masz dostęp) - LM Studio: `lmstudio/`… (lokalnie; wywoływanie narzędzi zależy od trybu API) ### Vision: wysyłanie obrazu (załącznik → wiadomość multimodalna) -Uwzględnij co najmniej jeden model z obsługą obrazu w `OPENCLAW_LIVE_GATEWAY_MODELS` (warianty Claude/Gemini/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 uruchomić sondę obrazu. ### Agregatory / alternatywne Gateway -Jeśli masz włączone klucze, obsługujemy też testowanie przez: +Jeśli masz włączone klucze, obsługujemy także testowanie przez: -- OpenRouter: `openrouter/...` (setki modeli; użyj `openclaw models scan`, aby znaleźć kandydatów z obsługą narzędzi+obrazu) +- OpenRouter: `openrouter/...` (setki modeli; użyj `openclaw models scan`, aby znaleźć kandydatów obsługujących narzędzia+obrazy) - OpenCode: `opencode/...` dla Zen i `opencode-go/...` dla Go (uwierzytelnianie przez `OPENCODE_API_KEY` / `OPENCODE_ZEN_API_KEY`) -Więcej dostawców, których możesz uwzględnić w macierzy live (jeśli masz poświadczenia/konfigurację): +Więcej dostawcó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` (własne endpointy): `minimax` (cloud/API), plus dowolny proxy zgodny z OpenAI/Anthropic (LM Studio, vLLM, LiteLLM itd.) +- Przez `models.providers` (niestandardowe endpointy): `minimax` (cloud/API) oraz dowolny proxy zgodny z OpenAI/Anthropic (LM Studio, vLLM, LiteLLM itd.) -Wskazówka: nie próbuj wpisywać na stałe „wszystkich modeli” w dokumentacji. Autorytatywna lista to to, co `discoverModels(...)` zwraca na twojej maszynie + jakie klucze są dostępne. +Wskazówka: nie próbuj kodować na sztywno „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 w ten sam sposób, co CLI. Praktyczne konsekwencje: +Testy live wykrywają poświadczenia tak samo jak CLI. W praktyce oznacza to: - Jeśli działa CLI, 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. - Profile uwierzytelniania 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 profili) -- Lokalne uruchomienia live domyślnie kopiują aktywną konfigurację, pliki `auth-profiles.json` per agent, starszy katalog `credentials/` oraz obsługiwane zewnętrzne katalogi uwierzytelniania CLI do tymczasowego katalogu domowego testu; przygotowane katalogi domowe live pomijają `workspace/` i `sandboxes/`, a nadpisania ścieżek `agents.*.workspace` / `agentDir` są usuwane, aby sondy nie działały w twoim rzeczywistym obszarze roboczym hosta. +- Starszy katalog stanu: `~/.openclaw/credentials/` (kopiowany do przygotowanego katalogu domowego live, jeśli istnieje, ale nie jest głównym store kluczy profilu) +- Lokalne uruchomienia live domyślnie kopiują aktywną konfigurację, pliki `auth-profiles.json` per agent, starszy katalog `credentials/` oraz obsługiwane zewnętrzne katalogi uwierzytelniania CLI do tymczasowego katalogu domowego testu; przygotowane katalogi domowe live pomijają `workspace/` i `sandboxes/`, a nadpisania ścieżek `agents.*.workspace` / `agentDir` są usuwane, tak aby sondy nie działały na twoim rzeczywistym workspace hosta. -Jeśli chcesz polegać na kluczach env (np. wyeksportowanych w `~/.profile`), uruchamiaj testy lokalne po `source ~/.profile` albo użyj poniższych uruchamiaczy Docker (mogą montować `~/.profile` do kontenera). +Jeśli chcesz polegać na kluczach z env (np. wyeksportowanych w `~/.profile`), uruchamiaj testy lokalne po `source ~/.profile`, albo użyj poniższych runnerów Docker (mogą zamontować `~/.profile` do kontenera). -## Live: Deepgram (transkrypcja audio) +## Deepgram live (transkrypcja audio) - Test: `src/media-understanding/providers/deepgram/audio.live.test.ts` - Włączanie: `DEEPGRAM_API_KEY=... DEEPGRAM_LIVE_TEST=1 pnpm test:live src/media-understanding/providers/deepgram/audio.live.test.ts` -## Live: plan kodowania BytePlus +## BytePlus live dla planu kodowania - Test: `src/agents/byteplus.live.test.ts` - Włączanie: `BYTEPLUS_API_KEY=... BYTEPLUS_LIVE_TEST=1 pnpm test:live src/agents/byteplus.live.test.ts` - Opcjonalne nadpisanie modelu: `BYTEPLUS_CODING_MODEL=ark-code-latest` -## Live: media workflow ComfyUI +## ComfyUI workflow media live - Test: `extensions/comfy/comfy.live.test.ts` - Włączanie: `OPENCLAW_LIVE_TEST=1 COMFY_LIVE_TEST=1 pnpm test:live -- extensions/comfy/comfy.live.test.ts` - Zakres: - - Testuje bundlowane ścieżki obrazu, wideo i `music_generate` comfy + - Testuje dołączone ścieżki comfy dla obrazu, wideo oraz `music_generate` - Pomija każdą możliwość, jeśli `models.providers.comfy.` nie jest skonfigurowane - - Przydatne po zmianach w wysyłaniu workflow comfy, odpytywaniu, pobieraniu lub rejestracji Plugin + - Przydatne po zmianach w przesyłaniu workflow comfy, polling, pobieraniu lub rejestracji Plugin -## Live: generowanie obrazów +## Live generowania obrazów - Test: `src/image-generation/runtime.live.test.ts` - Polecenie: `pnpm test:live src/image-generation/runtime.live.test.ts` - Harness: `pnpm test:live:media image` - Zakres: - Wylicza każdy zarejestrowany Plugin dostawcy generowania obrazów - - Ładuje brakujące zmienne env dostawców z twojej powłoki logowania (`~/.profile`) przed sondowaniem - - Domyślnie używa aktywnych/env kluczy API przed zapisanymi profilami uwierzytelniania, aby nieaktualne klucze testowe w `auth-profiles.json` nie maskowały rzeczywistych poświadczeń powłoki - - Pomija dostawców bez użytecznego uwierzytelniania/profilu/modelu + - Przed wykonaniem sond ładuje brakujące zmienne env dostawców z twojej powłoki logowania (`~/.profile`) + - Domyślnie używa kluczy API live/env przed zapisanymi profilami uwierzytelniania, tak aby nieaktualne klucze testowe w `auth-profiles.json` nie maskowały rzeczywistych poświadczeń z powłoki + - Pomija dostawców bez używalnego uwierzytelniania/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` -- Obecnie objęci bundlowani dostawcy: +- Aktualnie objęci dołączeni dostawcy: - `openai` - `google` -- Opcjonalne zawężanie: +- Opcjonalne zawężenie: - `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 uwierzytelniania: - - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, aby wymusić uwierzytelnianie z magazynu profili i ignorować nadpisania tylko z env + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, aby wymusić uwierzytelnianie ze store profili i ignorować nadpisania wyłącznie z env -## Live: generowanie muzyki +## Live generowania muzyki - Test: `extensions/music-generation-providers.live.test.ts` - Włączanie: `OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/music-generation-providers.live.test.ts` - Harness: `pnpm test:live:media music` - Zakres: - - Testuje współdzieloną bundlowaną ścieżkę dostawcy generowania muzyki + - Testuje współdzieloną ścieżkę dołączonych dostawców generowania muzyki - Obecnie obejmuje Google i MiniMax - - Ładuje zmienne env dostawców z twojej powłoki logowania (`~/.profile`) przed sondowaniem - - Domyślnie używa aktywnych/env kluczy API przed zapisanymi profilami uwierzytelniania, aby nieaktualne klucze testowe w `auth-profiles.json` nie maskowały rzeczywistych poświadczeń powłoki - - Pomija dostawców bez użytecznego uwierzytelniania/profilu/modelu + - Przed wykonaniem sond ładuje zmienne env dostawców z twojej powłoki logowania (`~/.profile`) + - Domyślnie używa kluczy API live/env przed zapisanymi profilami uwierzytelniania, tak aby nieaktualne klucze testowe w `auth-profiles.json` nie maskowały rzeczywistych poświadczeń z powłoki + - Pomija dostawców bez używalnego uwierzytelniania/profilu/modelu - Uruchamia oba zadeklarowane tryby runtime, gdy są dostępne: - `generate` z wejściem opartym wyłącznie na prompcie - `edit`, gdy dostawca deklaruje `capabilities.edit.enabled` - - Obecne pokrycie współdzielonej linii: + - Aktualne pokrycie współdzielonej linii: - `google`: `generate`, `edit` - `minimax`: `generate` - - `comfy`: osobny plik live Comfy, nie ten współdzielony przegląd -- Opcjonalne zawężanie: + - `comfy`: osobny plik live Comfy, nie ten wspólny przegląd +- Opcjonalne zawężenie: - `OPENCLAW_LIVE_MUSIC_GENERATION_PROVIDERS="google,minimax"` - `OPENCLAW_LIVE_MUSIC_GENERATION_MODELS="google/lyria-3-clip-preview,minimax/music-2.5+"` - Opcjonalne zachowanie uwierzytelniania: - - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, aby wymusić uwierzytelnianie z magazynu profili i ignorować nadpisania tylko z env + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, aby wymusić uwierzytelnianie ze store profili i ignorować nadpisania wyłącznie z env -## Live: generowanie wideo +## Live generowania wideo - Test: `extensions/video-generation-providers.live.test.ts` - Włączanie: `OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/video-generation-providers.live.test.ts` - Harness: `pnpm test:live:media video` - Zakres: - - Testuje współdzieloną bundlowaną ścieżkę dostawcy generowania wideo - - Ładuje zmienne env dostawców z twojej powłoki logowania (`~/.profile`) przed sondowaniem - - Domyślnie używa aktywnych/env kluczy API przed zapisanymi profilami uwierzytelniania, aby nieaktualne klucze testowe w `auth-profiles.json` nie maskowały rzeczywistych poświadczeń powłoki - - Pomija dostawców bez użytecznego uwierzytelniania/profilu/modelu - - Uruchamia oba zadeklarowane tryby runtime, gdy są dostępne: - - `generate` z wejściem opartym wyłącznie na prompcie - - `imageToVideo`, gdy dostawca deklaruje `capabilities.imageToVideo.enabled` i wybrany dostawca/model akceptuje wejście lokalnego obrazu oparte na buforze we współdzielonym przeglądzie - - `videoToVideo`, gdy dostawca deklaruje `capabilities.videoToVideo.enabled` i wybrany dostawca/model akceptuje wejście lokalnego wideo oparte na buforze we współdzielonym przeglądzie - - Obecni zadeklarowani, ale pomijani dostawcy `imageToVideo` we współdzielonym przeglądzie: - - `vydra`, ponieważ bundlowany `veo3` jest tylko tekstowy, a bundlowany `kling` wymaga zdalnego adresu URL obrazu + - Testuje współdzieloną ścieżkę dołączonych dostawców generowania wideo + - Domyślnie używa bezpiecznej dla wydania ścieżki smoke: dostawcy spoza FAL, jedno żądanie text-to-video na dostawcę, jednosekundowy prompt lobster oraz limit operacji per dostawca z `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS` (domyślnie `180000`) + - Domyślnie pomija FAL, ponieważ opóźnienie kolejek po stronie dostawcy może dominować nad czasem wydania; przekaż `--video-providers fal` lub `OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="fal"`, aby uruchomić go jawnie + - Przed wykonaniem sond ładuje zmienne env dostawców z twojej powłoki logowania (`~/.profile`) + - Domyślnie używa kluczy API live/env przed zapisanymi profilami uwierzytelniania, tak aby nieaktualne klucze testowe w `auth-profiles.json` nie maskowały rzeczywistych poświadczeń z powłoki + - Pomija dostawców bez używalnego uwierzytelniania/profilu/modelu + - Domyślnie uruchamia tylko `generate` + - Ustaw `OPENCLAW_LIVE_VIDEO_GENERATION_FULL_MODES=1`, aby uruchamiać także zadeklarowane tryby transformacji, jeśli są dostępne: + - `imageToVideo`, gdy dostawca deklaruje `capabilities.imageToVideo.enabled`, a wybrany dostawca/model akceptuje lokalne wejście obrazu oparte na buforze we współdzielonym przeglądzie + - `videoToVideo`, gdy dostawca deklaruje `capabilities.videoToVideo.enabled`, a wybrany dostawca/model akceptuje lokalne wejście wideo oparte 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: - `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 linię `kling`, która domyślnie używa fixture zdalnego adresu URL obrazu - - Obecne pokrycie live `videoToVideo`: + - ten plik uruchamia `veo3` text-to-video oraz linię `kling`, która domyślnie używa fixture zdalnego URL obrazu + - Aktualne pokrycie live `videoToVideo`: - tylko `runway`, gdy wybrany model to `runway/gen4_aleph` - - Obecni zadeklarowani, ale pomijani dostawcy `videoToVideo` we współdzielonym przeglądzie: - - `alibaba`, `qwen`, `xai`, ponieważ te ścieżki obecnie wymagają zdalnych referencyjnych adresów URL `http(s)` / MP4 + - Aktualni dostawcy `videoToVideo` zadeklarowani, ale pomijani we współdzielonym przeglądzie: + - `alibaba`, `qwen`, `xai`, ponieważ te ścieżki obecnie wymagają zdalnych URL referencyjnych `http(s)` / MP4 - `google`, ponieważ obecna współdzielona linia 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 linia nie gwarantuje organizacyjnego dostępu do video inpaint/remix -- Opcjonalne zawężanie: + - `openai`, ponieważ obecna współdzielona linia nie gwarantuje dostępu specyficznego dla organizacji do inpaint/remix wideo +- Opcjonalne zawężenie: - `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"` + - `OPENCLAW_LIVE_VIDEO_GENERATION_SKIP_PROVIDERS=""`, aby uwzględnić każdego dostawcę w domyślnym przeglądzie, w tym FAL + - `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS=60000`, aby zmniejszyć limit operacji każdego dostawcy na potrzeby agresywnego uruchomienia smoke - Opcjonalne zachowanie uwierzytelniania: - - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, aby wymusić uwierzytelnianie z magazynu profili i ignorować nadpisania tylko z env + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, aby wymusić uwierzytelnianie ze store profili i ignorować nadpisania wyłącznie z env ## Harness live dla mediów - Polecenie: `pnpm test:live:media` - Cel: - - Uruchamia współdzielone pakiety live dla obrazów, muzyki i wideo przez jedno natywne wejście repozytorium + - Uruchamia współdzielone pakiety live dla obrazu, muzyki i wideo przez jeden natywny punkt wejścia repo - Automatycznie ładuje brakujące zmienne env dostawców z `~/.profile` - - Domyślnie automatycznie zawęża każdy pakiet do dostawców, którzy aktualnie mają użyteczne uwierzytelnianie - - Ponownie używa `scripts/test-live.mjs`, więc zachowanie Heartbeat i trybu cichego pozostaje spójne + - Domyślnie automatycznie zawęża każdy pakiet do dostawców, którzy obecnie mają używalne uwierzytelnianie + - Ponownie używa `scripts/test-live.mjs`, dzięki czemu zachowanie Heartbeat i trybu cichego 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` -## Uruchamiacze Docker (opcjonalne testy „działa w Linux”) +## Uruchamiacze Docker (opcjonalne kontrole „działa w Linux”) -Te uruchamiacze Docker dzielą się na dwie kategorie: +Te uruchamiacze Docker dzielą się na dwa koszyki: -- Uruchamiacze 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 repozytorium (`src/agents/models.profiles.live.test.ts` i `src/gateway/gateway-models.profiles.live.test.ts`), montując lokalny katalog konfiguracji i obszar roboczy (oraz pobierając `~/.profile`, jeśli jest zamontowany). Odpowiadające im lokalne punkty wejścia to `test:live:models-profiles` i `test:live:gateway-profiles`. -- Uruchamiacze Docker live domyślnie używają mniejszego limitu smoke, aby pełny przegląd Docker pozostawał praktyczny: +- Uruchamiacze live-model: `test:docker:live-models` i `test:docker:live-gateway` uruchamiają tylko odpowiadający im plik live z kluczami profilu 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 ładując `~/.profile`, jeśli jest zamontowane). Odpowiadające lokalne punkty wejścia to `test:live:models-profiles` i `test:live:gateway-profiles`. +- Uruchamiacze live Docker 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 env, gdy - celowo chcesz większego, wyczerpującego przeglądu. -- `test:docker:all` buduje obraz Docker live raz przez `test:docker:live-build`, a następnie ponownie używa go dla dwóch linii Docker live. + świadomie chcesz uruchomić większy, wyczerpujący przegląd. +- `test:docker:all` buduje obraz live Docker raz przez `test:docker:live-build`, a następnie używa go ponownie dla dwóch linii live Docker. - Uruchamiacze 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. -Uruchamiacze Docker live-model montują też tylko potrzebne katalogi domowe uwierzytelniania CLI (albo wszystkie obsługiwane, gdy uruchomienie nie jest zawężone), a następnie kopiują je do katalogu domowego kontenera przed uruchomieniem, aby zewnętrzny OAuth CLI mógł odświeżać tokeny bez modyfikowania magazynu uwierzytelniania hosta: +Uruchamiacze Docker live-model dodatkowo montują tylko potrzebne katalogi domowe uwierzytelniania CLI (lub wszystkie obsługiwane, jeśli uruchomienie nie jest zawężone), a następnie kopiują je do katalogu domowego kontenera przed startem, tak aby zewnętrzny OAuth CLI mógł odświeżać tokeny bez modyfikowania store uwierzytelniania hosta: - Bezpośrednie modele: `pnpm test:docker:live-models` (skrypt: `scripts/test-live-models-docker.sh`) -- Smoke powiązania ACP: `pnpm test:docker:live-acp-bind` (skrypt: `scripts/test-live-acp-bind-docker.sh`) +- Smoke bind ACP: `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`) - Smoke harnessu app-server Codex: `pnpm test:docker:live-codex-harness` (skrypt: `scripts/test-live-codex-harness-docker.sh`) -- Gateway + agent developerski: `pnpm test:docker:live-gateway` (skrypt: `scripts/test-live-gateway-models-docker.sh`) -- Smoke live Open WebUI: `pnpm test:docker:openwebui` (skrypt: `scripts/e2e/openwebui-docker.sh`) +- Gateway + agent dev: `pnpm test:docker:live-gateway` (skrypt: `scripts/test-live-gateway-models-docker.sh`) +- Open WebUI live smoke: `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, uwierzytelnianie WS + health): `pnpm test:docker:gateway-network` (skrypt: `scripts/e2e/gateway-network-docker.sh`) -- Most kanałów MCP (seedowany Gateway + most stdio + smoke surowej ramki powiadomień Claude): `pnpm test:docker:mcp-channels` (skrypt: `scripts/e2e/mcp-channels-docker.sh`) -- Pluginy (smoke instalacji + alias `/plugin` + semantyka restartu bundla Claude): `pnpm test:docker:plugins` (skrypt: `scripts/e2e/plugins-docker.sh`) +- Most kanałów MCP (zasiany Gateway + most stdio + smoke surowej ramki powiadomienia Claude): `pnpm test:docker:mcp-channels` (skrypt: `scripts/e2e/mcp-channels-docker.sh`) +- Pluginy (smoke instalacji + alias `/plugin` + semantyka restartu pakietu Claude): `pnpm test:docker:plugins` (skrypt: `scripts/e2e/plugins-docker.sh`) -Uruchamiacze Docker live-model montują też bieżący checkout tylko do odczytu i -przygotowują go w tymczasowym katalogu roboczym wewnątrz kontenera. Dzięki temu obraz runtime -pozostaje lekki, a jednocześnie Vitest działa na dokładnie twojej lokalnej konfiguracji/źródłach. -Krok przygotowania pomija duże lokalne cache oraz wyniki buildów aplikacji, takie jak -`.pnpm-store`, `.worktrees`, `__openclaw_vitest__` oraz lokalne dla aplikacji katalogi `.build` lub -wyjścia Gradle, dzięki czemu uruchomienia Docker live nie tracą minut na kopiowanie +Uruchamiacze Docker live-model montują także bieżący checkout tylko do odczytu i +przygotowują go w tymczasowym katalogu roboczym wewnątrz kontenera. Dzięki temu runtime +image pozostaje lekki, a jednocześnie Vitest działa względem dokładnie twojego lokalnego źródła/konfiguracji. +Krok przygotowania pomija duże lokalne cache oraz buildy aplikacji, takie jak +`.pnpm-store`, `.worktrees`, `__openclaw_vitest__` oraz lokalne katalogi `.build` lub +wyjścia Gradle, dzięki czemu uruchomienia live Docker nie tracą minut na kopiowanie artefaktów specyficznych dla maszyny. -Ustawiają też `OPENCLAW_SKIP_CHANNELS=1`, aby aktywne sondy Gateway nie uruchamiały +Ustawiają też `OPENCLAW_SKIP_CHANNELS=1`, aby sondy live Gateway 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 przekazuj także -`OPENCLAW_LIVE_GATEWAY_*`, gdy chcesz zawęzić lub wykluczyć pokrycie Gateway -live z tej linii Docker. -`test:docker:openwebui` jest smoke zgodności wyższego poziomu: uruchamia +`test:docker:live-models` nadal uruchamia `pnpm test:live`, więc przekazuj również +`OPENCLAW_LIVE_GATEWAY_*`, gdy chcesz zawęzić lub wykluczyć pokrycie live Gateway z tej linii Docker. +`test:docker:openwebui` to smoke kompatybilności wyższego poziomu: uruchamia kontener Gateway OpenClaw z włączonymi endpointami HTTP zgodnymi z OpenAI, -uruchamia przypięty kontener Open WebUI przeciwko temu Gateway, loguje się przez +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 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 samo Open WebUI może potrzebować dokończyć własną konfigurację cold-start. -Ta linia oczekuje użytecznego klucza modelu live, a `OPENCLAW_PROFILE_FILE` -(domyślnie `~/.profile`) jest podstawowym sposobem jego dostarczenia w uruchomieniach konteneryzowanych. -Udane uruchomienia wypisują mały payload JSON, taki jak `{ "ok": true, "model": +obraz Open WebUI, a samo Open WebUI może potrzebować zakończyć własny cold start. +Ta linia oczekuje używalnego klucza live modelu, a `OPENCLAW_PROFILE_FILE` +(domyślnie `~/.profile`) jest podstawowym sposobem dostarczenia go w uruchomieniach z Docker. +Udane uruchomienia wypisują niewielki payload JSON, na przykład `{ "ok": true, "model": "openclaw/default", ... }`. `test:docker:mcp-channels` jest celowo deterministyczny i nie wymaga -rzeczywistego konta Telegram, Discord ani iMessage. Uruchamia seedowany kontener -Gateway, startuje drugi kontener uruchamiający `openclaw mcp serve`, a następnie -weryfikuje wykrywanie routowanych rozmów, odczyty transkryptów, metadane załączników, -zachowanie kolejki zdarzeń live, routing wysyłania wychodzącego oraz powiadomienia -w stylu Claude dla kanałów + uprawnień przez rzeczywisty most stdio MCP. Kontrola powiadomień -sprawdza bezpośrednio surowe ramki stdio MCP, dzięki czemu smoke weryfikuje to, co -most rzeczywiście emituje, a nie tylko to, co akurat ujawnia określony klient SDK. +rzeczywistego konta Telegram, Discord ani iMessage. Uruchamia zasiany kontener +Gateway, startuje drugi kontener, który uruchamia `openclaw mcp serve`, a następnie +weryfikuje routowane wykrywanie konwersacji, odczyty transkryptów, metadane załączników, +zachowanie kolejki zdarzeń live, routing wysyłki wychodzącej oraz powiadomienia kanału + +uprawnień w stylu Claude przez rzeczywisty most MCP stdio. Kontrola powiadomień +sprawdza bezpośrednio surowe ramki stdio MCP, tak aby smoke walidował to, co most +rzeczywiście emituje, a nie tylko to, co akurat udostępnia określony klient SDK. -Ręczny smoke wątku ACP w plain language (nie w CI): +Ręczny smoke wątku ACP plain-language (nie CI): - `bun scripts/dev/discord-acp-plain-language-smoke.ts --channel ...` -- Zachowaj ten skrypt do przepływów pracy regresji/debugowania. Może być znów potrzebny do walidacji routingu wątków ACP, więc go nie usuwaj. +- 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. 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 pobierane przed uruchomieniem testów +- `OPENCLAW_PROFILE_FILE=...` (domyślnie: `~/.profile`) montowane do `/home/node/.profile` i ładowane przed uruchomieniem testów - `OPENCLAW_DOCKER_CLI_TOOLS_DIR=...` (domyślnie: `~/.cache/openclaw/docker-cli-tools`) montowane do `/home/node/.npm-global` dla cache’owanych instalacji CLI wewnątrz Docker -- Zewnętrzne katalogi/pliki uwierzytelniania CLI pod `$HOME` są montowane tylko do odczytu pod `/host-auth...`, a następnie kopiowane do `/home/node/...` przed rozpoczęciem testów +- Zewnętrzne katalogi/pliki uwierzytelniania 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` + - 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ć dostawców wewnątrz kontenera - `OPENCLAW_SKIP_DOCKER_BUILD=1`, aby ponownie użyć istniejącego obrazu `openclaw:local-live` przy ponownych uruchomieniach, które nie wymagają przebudowy -- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, aby upewnić się, że poświadczenia pochodzą z magazynu profili (a nie z env) +- `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 sprawdzania nonce używany przez 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 poprawności dokumentacji +## Sprawdzenie dokumentacji -Po edycjach dokumentacji uruchom sprawdzenia dokumentacji: `pnpm check:docs`. -Uruchom pełną walidację anchorów Mintlify, gdy potrzebujesz także sprawdzania nagłówków w obrębie strony: `pnpm docs:check-links:anchors`. +Po edycji dokumentacji uruchom kontrole dokumentacji: `pnpm check:docs`. +Gdy potrzebujesz też sprawdzenia nagłówków w obrębie strony, uruchom pełną walidację anchorów Mintlify: `pnpm docs:check-links:anchors`. -## Regresje offline (bezpieczne dla CI) +## Regresja offline (bezpieczna dla CI) To regresje „rzeczywistego pipeline” bez rzeczywistych dostawców: - Wywoływanie narzędzi Gateway (mock OpenAI, rzeczywisty Gateway + pętla agenta): `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`, wymuszone zapisywanie konfiguracji + auth): `src/gateway/gateway.test.ts` (przypadek: "runs wizard over ws and writes auth token config") +- Kreator Gateway (WS `wizard.start`/`wizard.next`, zapisuje konfigurację + wymuszone uwierzytelnianie): `src/gateway/gateway.test.ts` (przypadek: "runs wizard over ws and writes auth token config") ## Ewaluacje niezawodności agenta (Skills) -Mamy już kilka testów bezpiecznych dla CI, które zachowują się jak „ewaluacje niezawodności agenta”: +Mamy już kilka testów bezpiecznych dla CI, które działają jak „ewaluacje niezawodności agenta”: -- Mock wywoływania narzędzi przez rzeczywistą pętlę Gateway + agenta (`src/gateway/gateway.test.ts`). -- Przepływy kreatora end-to-end, które walidują okablowanie sesji i efekty konfiguracji (`src/gateway/gateway.test.ts`). +- Mock wywoływania narzędzi przez rzeczywisty Gateway + pętlę agenta (`src/gateway/gateway.test.ts`). +- Przepływy kreatora end-to-end, które walidują okablowanie sesji i skutki konfiguracji (`src/gateway/gateway.test.ts`). -Czego nadal brakuje dla Skills (zobacz [Skills](/pl/tools/skills)): +Czego nadal brakuje dla Skills (zob. [Skills](/pl/tools/skills)): -- **Decisioning:** gdy Skills są wymienione w prompcie, czy agent wybiera właściwy Skill (albo unika nieistotnych)? -- **Compliance:** czy agent odczytuje `SKILL.md` przed użyciem i wykonuje wymagane kroki/argumenty? -- **Workflow contracts:** scenariusze wieloturowe, które sprawdzają 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 sprawdzające kolejność narzędzi, przenoszenie historii sesji i granice sandboxa. Przyszłe ewaluacje powinny najpierw pozostać deterministyczne: -- Uruchamiacz scenariuszy używający mock dostawców do sprawdzania wywołań narzędzi + kolejności, odczytów plików Skill i okablowania sesji. -- Niewielki pakiet scenariuszy skupionych na Skills (użycie vs unikanie, bramkowanie, prompt injection). -- Opcjonalne ewaluacje live (opt-in, bramkowane env) dopiero po wdrożeniu pakietu bezpiecznego dla CI. +- Runner scenariuszy używający mock dostawców do sprawdzania wywołań narzędzi + ich kolejności, odczytów plików skill oraz okablowania sesji. +- Niewielki pakiet scenariuszy skupionych na skillach (użycie vs unikanie, gating, prompt injection). +- Opcjonalne ewaluacje live (opt-in, sterowane env) dopiero po wdrożeniu pakietu bezpiecznego dla CI. -## Testy kontraktowe (kształt Plugin i kanałów) +## Testy kontraktowe (kształt Plugin i kanału) -Testy kontraktowe weryfikują, że każdy zarejestrowany Plugin i kanał jest zgodny ze swoim -kontraktem interfejsu. Iterują po wszystkich wykrytych Plugin i uruchamiają pakiet -asercji kształtu i zachowania. Domyślna linia unit `pnpm test` celowo +Testy kontraktowe weryfikują, że każdy zarejestrowany Plugin i kanał spełnia swój +kontrakt interfejsu. Iterują po wszystkich wykrytych Plugin i uruchamiają pakiet +asercji dotyczących kształtu i zachowania. Domyślna linia unit `pnpm test` celowo pomija te współdzielone pliki seam i smoke; uruchamiaj polecenia kontraktowe jawnie, -gdy modyfikujesz współdzielone powierzchnie kanałów lub dostawców. +gdy dotykasz współdzielonych powierzchni kanałów lub dostawców. ### Polecenia @@ -950,21 +963,21 @@ gdy modyfikujesz współdzielone powierzchnie kanałów lub dostawców. Znajdują się w `src/channels/plugins/contracts/*.contract.test.ts`: -- **plugin** - Podstawowy kształt Plugin (id, nazwa, capabilities) +- **plugin** - Podstawowy kształt Plugin (id, nazwa, możliwości) - **setup** - Kontrakt kreatora konfiguracji - **session-binding** - Zachowanie wiązania sesji - **outbound-payload** - Struktura payload wiadomości - **inbound** - Obsługa wiadomości przychodzących - **actions** - Handlery akcji kanału -- **threading** - Obsługa identyfikatorów wątków +- **threading** - Obsługa identyfikatora wątku - **directory** - API katalogu/listy -- **group-policy** - Egzekwowanie zasad grup +- **group-policy** - Egzekwowanie polityki grupowej ### Kontrakty statusu dostawców Znajdują się w `src/plugins/contracts/*.contract.test.ts`. -- **status** - Sondy statusu kanałów +- **status** - Sondy statusu kanału - **registry** - Kształt rejestru Plugin ### Kontrakty dostawców @@ -990,13 +1003,13 @@ 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 dostawcy/modelu odkryty w live: -- Jeśli to możliwe, dodaj regresję bezpieczną dla CI (mock/stub dostawcy albo przechwycenie dokładnej transformacji kształtu żądania) -- Jeśli z natury jest to problem tylko live (limity szybkości, polityki uwierzytelniania), utrzymaj test live wąski i opt-in przez zmienne env -- Preferuj celowanie w najmniejszą warstwę, która wychwytuje błąd: +- Jeśli to możliwe, dodaj regresję bezpieczną dla CI (mock/stub dostawcy albo przechwyć dokładną transformację kształtu żądania) +- Jeśli z natury jest to problem wyłącznie live (limity szybkości, polityki uwierzytelniania), zachowaj test live jako wąski i opt-in przez zmienne env +- Preferuj najmniejszą warstwę, która wychwytuje błąd: - błąd konwersji/replay żądania dostawcy → test bezpośrednich modeli - - błąd pipeline sesji/historii/narzędzi Gateway → smoke Gateway live albo bezpieczny dla CI mock test 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 sprawdza, że identyfikatory exec segmentów przechodzenia są odrzucane. - - Jeśli dodajesz nową rodzinę celów SecretRef `includeInPlan` w `src/secrets/target-registry-data.ts`, zaktualizuj `classifyTargetClass` w tym teście. Test celowo kończy się błędem przy niesklasyfikowanych identyfikatorach celów, aby nowe klasy nie mogły zostać pominięte po cichu. + - błąd pipeline sesji/historii/narzędzi Gateway → smoke live Gateway lub bezpieczny dla CI test mock Gateway +- Ochrona przechodzenia SecretRef: + - `src/secrets/exec-secret-ref-id-parity.test.ts` wyprowadza jeden przykładowy target na klasę SecretRef z metadanych rejestru (`listSecretTargetRegistryEntries()`), a następnie sprawdza, że identyfikatory exec segmentów przejścia są odrzucane. + - Jeśli dodasz nową rodzinę targetó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 targetów, aby nowych klas nie można było pominąć po cichu. diff --git a/docs/pl/plugins/architecture.md b/docs/pl/plugins/architecture.md index 406c1c480..b249d411d 100644 --- a/docs/pl/plugins/architecture.md +++ b/docs/pl/plugins/architecture.md @@ -1,46 +1,46 @@ --- 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 hooków środowiska uruchomieniowego dostawców lub Pluginów kanałów + - 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 hooków środowiska uruchomieniowego dostawcy lub pluginów kanałów sidebarTitle: Internals -summary: 'Wnętrze Pluginów: model możliwości, własność, kontrakty, potok ładowania i pomocniki środowiska uruchomieniowego' -title: Wnętrze Pluginów +summary: 'Wewnętrzne elementy Plugin: model możliwości, własność, kontrakty, potok ładowania i narzędzia pomocnicze środowiska uruchomieniowego' +title: Wewnętrzne elementy Plugin x-i18n: - generated_at: "2026-04-12T23:28:40Z" + generated_at: "2026-04-15T09:51:09Z" model: gpt-5.4 provider: openai - source_hash: 37361c1e9d2da57c77358396f19dfc7f749708b66ff68f1bf737d051b5d7675d + source_hash: f86798b5d2b0ad82d2397a52a6c21ed37fe6eee1dd3d124a9e4150c4f630b841 source_path: plugins/architecture.md workflow: 15 --- -# Wnętrze Pluginów +# Wewnętrzne elementy Plugin - To jest **szczegółowe odniesienie architektoniczne**. Praktyczne przewodniki znajdziesz tutaj: - - [Instalowanie i używanie pluginów](/pl/tools/plugin) — przewodnik użytkownika - - [Pierwsze kroki](/pl/plugins/building-plugins) — pierwszy samouczek Pluginu - - [Pluginy kanałów](/pl/plugins/sdk-channel-plugins) — tworzenie kanału wiadomości - - [Pluginy dostawców](/pl/plugins/sdk-provider-plugins) — tworzenie dostawcy modeli + To jest **szczegółowe odniesienie do architektury**. Praktyczne przewodniki znajdziesz tutaj: + - [Zainstaluj i używaj pluginów](/pl/tools/plugin) — przewodnik użytkownika + - [Pierwsze kroki](/pl/plugins/building-plugins) — samouczek tworzenia pierwszego pluginu + - [Pluginy kanałów](/pl/plugins/sdk-channel-plugins) — zbuduj kanał wiadomości + - [Pluginy dostawców](/pl/plugins/sdk-provider-plugins) — zbuduj dostawcę modeli - [Przegląd SDK](/pl/plugins/sdk-overview) — mapa importów i API rejestracji -Ta strona opisuje wewnętrzną architekturę systemu Pluginów OpenClaw. +Ta strona opisuje wewnętrzną architekturę systemu pluginów OpenClaw. ## Publiczny model możliwości -Możliwości to publiczny model **natywnych Pluginów** w OpenClaw. Każdy -natywny Plugin OpenClaw rejestruje się względem jednego lub większej liczby typów możliwości: +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: -| Możliwość | Metoda rejestracji | Przykładowe Pluginy | +| Możliwość | Metoda rejestracji | Przykładowe pluginy | | --------------------- | ----------------------------------------------- | ------------------------------------ | | Wnioskowanie tekstowe | `api.registerProvider(...)` | `openai`, `anthropic` | -| Backend wnioskowania CLI | `api.registerCliBackend(...)` | `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` | +| 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` | @@ -49,63 +49,62 @@ natywny Plugin OpenClaw rejestruje się względem jednego lub większej liczby t | Wyszukiwanie w sieci | `api.registerWebSearchProvider(...)` | `google` | | Kanał / wiadomości | `api.registerChannel(...)` | `msteams`, `matrix` | -Plugin, który rejestruje zero możliwości, ale udostępnia hooki, narzędzia lub -usługi, to **starszy Plugin wyłącznie z hookami**. Ten wzorzec nadal jest w pełni wspierany. +Plugin, który rejestruje zero możliwości, ale dostarcza hooki, narzędzia lub +usługi, jest pluginem **legacy tylko z hookami**. Ten wzorzec jest nadal w pełni obsługiwany. -### Podejście do kompatybilności zewnętrznej +### Stan kompatybilności zewnętrznej -Model możliwości jest wdrożony w core i używany dziś przez bundlowane/natywne Pluginy, -ale kompatybilność zewnętrznych Pluginów nadal wymaga wyższego progu niż „jest -eksportowane, więc jest zamrożone”. +Model możliwości jest już wdrożony w core i używany dziś przez pluginy +bundled/natywne, ale zgodność zewnętrznych pluginów nadal wymaga wyższego +progu niż „jest eksportowane, więc jest zamrożone”. -Obecne wytyczne: +Aktualne wytyczne: -- **istniejące zewnętrzne Pluginy:** zachowuj działanie integracji opartych na hookach; traktuj +- **istniejące zewnętrzne pluginy:** zachowaj działanie integracji opartych na hookach; traktuj to jako bazowy poziom kompatybilności -- **nowe bundlowane/natywne Pluginy:** preferuj jawną rejestrację możliwości zamiast - podejść specyficznych dla dostawcy lub nowych projektów wyłącznie opartych na hookach -- **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 wyraźnie oznacza +- **nowe pluginy bundled/natywne:** preferuj jawną rejestrację możliwości zamiast + zależnych od dostawcy wejść w implementację lub nowych projektów tylko z hookami +- **zewnętrzne pluginy przyjmujące rejestrację możliwości:** dozwolone, ale traktuj + pomocnicze powierzchnie specyficzne dla możliwości jako ewoluujące, chyba że dokumentacja wyraźnie oznacza dany kontrakt jako stabilny Praktyczna zasada: -- API rejestracji możliwości są zamierzonym kierunkiem -- starsze hooki pozostają najbezpieczniejszą ścieżką bez ryzyka zepsucia dla zewnętrznych Pluginów w czasie +- API rejestracji możliwości to zamierzony kierunek +- legacy hooki pozostają najbezpieczniejszą ścieżką bez naruszania zgodności dla zewnętrznych pluginów w trakcie przejścia -- eksportowane podścieżki pomocnicze nie są równoważne; preferuj wąski, udokumentowany - kontrakt, a nie przypadkowo wyeksportowane pomocniki +- eksportowane podścieżki pomocnicze nie są równorzędne; preferuj wąski, udokumentowany + kontrakt, a nie przypadkowe eksporty pomocnicze -### Kształty Pluginów +### Kształty pluginów -OpenClaw klasyfikuje każdy załadowany Plugin do określonego kształtu na podstawie jego rzeczywistego -zachowania rejestracyjnego (a nie tylko statycznych metadanych): +OpenClaw klasyfikuje każdy załadowany plugin do określonego kształtu 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`) + plugin tylko dostawcy, taki jak `mistral`) - **hybrid-capability** -- rejestruje wiele typów możliwości (na przykład - `openai` odpowiada za wnioskowanie tekstowe, mowę, rozumienie mediów i - generowanie obrazów) -- **hook-only** -- rejestruje tylko hooki (typowane lub niestandardowe), bez możliwości, + `openai` obsługuje wnioskowanie tekstowe, mowę, rozumienie mediów i generowanie obrazów) +- **hook-only** -- rejestruje tylko hooki (typowane lub własne), bez możliwości, narzędzi, poleceń ani usług - **non-capability** -- rejestruje narzędzia, polecenia, usługi lub trasy, ale bez możliwości -Użyj `openclaw plugins inspect `, aby zobaczyć kształt Pluginu i rozkład jego możliwości. -Szczegóły znajdziesz w [referencji CLI](/cli/plugins#inspect). +Użyj `openclaw plugins inspect `, aby zobaczyć kształt pluginu i podział +możliwości. Szczegóły znajdziesz w [dokumentacji CLI](/cli/plugins#inspect). -### Starsze hooki +### Legacy hooki -Hook `before_agent_start` pozostaje wspierany jako ścieżka kompatybilności dla -Pluginów wyłącznie z hookami. Nadal zależą od niego starsze Pluginy używane w rzeczywistych wdrożeniach. +Hook `before_agent_start` pozostaje obsługiwany jako ścieżka kompatybilności dla +pluginów tylko z hookami. Nadal zależą od niego starsze pluginy używane w praktyce. Kierunek: -- utrzymywać jego działanie -- dokumentować go jako starszy -- dla nadpisywania modelu/dostawcy preferować `before_model_resolve` -- dla modyfikacji promptu preferować `before_prompt_build` -- usuwać dopiero wtedy, gdy rzeczywiste użycie spadnie, a pokrycie fixture potwierdzi bezpieczeństwo migracji +- utrzymać jego działanie +- dokumentować go jako legacy +- dla pracy z nadpisywaniem modelu/dostawcy preferować `before_model_resolve` +- dla modyfikacji promptów preferować `before_prompt_build` +- usunąć dopiero wtedy, gdy realne użycie spadnie, a pokrycie fixture potwierdzi bezpieczeństwo migracji ### Sygnały kompatybilności @@ -114,73 +113,82 @@ jedną z tych etykiet: | Sygnał | Znaczenie | | -------------------------- | ------------------------------------------------------------ | -| **config valid** | Konfiguracja poprawnie się parsuje, a Pluginy są rozwiązywane | +| **config valid** | Konfiguracja poprawnie się parsuje, 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 lub Plugin nie załadował się | +| **hard error** | Konfiguracja jest nieprawidłowa lub nie udało się załadować pluginu | -Ani `hook-only`, ani `before_agent_start` nie zepsują dziś Twojego Pluginu -- +Ani `hook-only`, ani `before_agent_start` nie spowodują dziś uszkodzenia pluginu -- `hook-only` ma charakter doradczy, a `before_agent_start` wywołuje jedynie 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: +System pluginów OpenClaw ma cztery warstwy: 1. **Manifest + wykrywanie** - OpenClaw znajduje kandydatów na Pluginy na podstawie skonfigurowanych ścieżek, katalogów workspace, - globalnych katalogów rozszerzeń i bundlowanych rozszerzeń. Wykrywanie najpierw odczytuje natywne - manifesty `openclaw.plugin.json` oraz wspierane manifesty bundli. + OpenClaw znajduje kandydackie pluginy w skonfigurowanych ścieżkach, katalogach głównych workspace, + globalnych katalogach rozszerzeń i bundled extensions. Wykrywanie najpierw odczytuje natywne + manifesty `openclaw.plugin.json` oraz obsługiwane manifesty pakietów. 2. **Włączanie + walidacja** - Core decyduje, czy wykryty Plugin jest włączony, wyłączony, zablokowany lub - wybrany dla ekskluzywnego slotu, takiego jak pamięć. + Core decyduje, czy wykryty plugin jest włączony, wyłączony, zablokowany czy + wybrany do ekskluzywnego slotu, takiego jak pamięć. 3. **Ładowanie środowiska uruchomieniowego** - Natywne Pluginy OpenClaw są ładowane w procesie przez jiti i rejestrują - możliwości w centralnym rejestrze. Zgodne bundle są normalizowane do + Natywne pluginy OpenClaw są ładowane w procesie przez jiti i rejestrują + możliwości w centralnym rejestrze. Zgodne pakiety są normalizowane do rekordów rejestru bez importowania kodu środowiska uruchomieniowego. 4. **Konsumpcja powierzchni** - Reszta OpenClaw odczytuje rejestr, aby udostępniać narzędzia, kanały, konfigurację + Pozostała część OpenClaw odczytuje rejestr, aby udostępniać narzędzia, kanały, konfigurację dostawców, hooki, trasy HTTP, polecenia CLI i usługi. -W przypadku CLI Pluginów wykrywanie poleceń głównych jest dodatkowo podzielone na dwa etapy: +Konkretnie dla CLI pluginów odkrywanie komend głównych jest podzielone na dwa etapy: - metadane na etapie parsowania pochodzą z `registerCli(..., { descriptors: [...] })` -- właściwy moduł CLI Pluginu może pozostać leniwy i rejestrować się przy pierwszym wywołaniu +- rzeczywisty moduł CLI pluginu może pozostać lazy i zarejestrować się przy pierwszym wywołaniu -Dzięki temu kod CLI należący do Pluginu pozostaje wewnątrz Pluginu, a OpenClaw nadal może -zarezerwować nazwy poleceń głównych przed parsowaniem. +Dzięki temu kod CLI należący do pluginu pozostaje wewnątrz pluginu, a jednocześnie OpenClaw +może zarezerwować nazwy komend głównych przed parsowaniem. -Najważniejsza granica projektowa: +Ważna granica projektowa: - wykrywanie + walidacja konfiguracji powinny działać na podstawie **metadanych manifestu/schematu** - bez wykonywania kodu Pluginu -- natywne zachowanie środowiska uruchomieniowego pochodzi ze ścieżki modułu Pluginu `register(api)` + bez wykonywania kodu pluginu +- natywne zachowanie środowiska uruchomieniowego pochodzi ze ścieżki modułu pluginu `register(api)` -Ten podział pozwala OpenClaw walidować konfigurację, wyjaśniać brakujące/wyłączone Pluginy i -budować wskazówki dla UI/schematu, zanim pełne środowisko uruchomieniowe stanie się aktywne. +Ten podział pozwala OpenClaw walidować konfigurację, wyjaśniać brakujące/wyłączone pluginy i +budować wskazówki UI/schematu, zanim pełne środowisko uruchomieniowe stanie się aktywne. -### 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 core, -a Pluginy kanałów odpowiadają za wykrywanie specyficzne dla kanału i wykonanie za nim. +zwykłych działań czatu. OpenClaw utrzymuje jedno współdzielone narzędzie `message` w core, a +pluginy kanałów odpowiadają za specyficzne dla kanału wykrywanie i wykonanie za nim. Obecna granica wygląda tak: -- core odpowiada za host współdzielonego narzędzia `message`, połączenie z promptem, prowadzenie księgowości sesji/wątków - oraz dyspozycję wykonania -- Pluginy kanałów odpowiadają za wykrywanie działań w ograniczonym zakresie, wykrywanie możliwości i wszelkie +- core odpowiada za host współdzielonego narzędzia `message`, połączenie z promptami, prowadzenie + sesji/wątków i dyspozycję wykonania +- pluginy kanałów odpowiadają za wykrywanie działań w danym zakresie, wykrywanie możliwości oraz wszelkie fragmenty schematu specyficzne dla kanału -- Pluginy kanałów odpowiadają za gramatykę rozmów sesji specyficzną dla dostawcy, na przykład - za sposób, w jaki identyfikatory rozmów kodują identyfikatory wątków lub dziedziczą z rozmów nadrzędnych -- Pluginy kanałów wykonują końcowe działanie przez swój adapter działań +- pluginy kanałów odpowiadają za gramatykę rozmów sesji specyficzną dla dostawcy, na przykład + 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ć razem widoczne działania, możliwości i wkłady do schematu, -aby te elementy nie rozjeżdżały się względem siebie. +Dla pluginów kanałów powierzchnią SDK jest +`ChannelMessageActionAdapter.describeMessageTool(...)`. To zunifikowane wywołanie wykrywania +pozwala pluginowi zwrócić widoczne działania, możliwości i wkłady do schematu +razem, aby te elementy nie rozjeżdżały się między sobą. -Core przekazuje zakres środowiska uruchomieniowego do tego kroku wykrywania. Ważne pola to: +Gdy parametr narzędzia wiadomości specyficzny dla kanału zawiera źródło mediów, takie jak +lokalna ścieżka lub zdalny URL mediów, plugin powinien również zwrócić +`mediaSourceParams` z `describeMessageTool(...)`. Core używa tej jawnej +listy, aby stosować normalizację ścieżek sandbox i wskazówki dotyczące wychodzącego dostępu do mediów +bez hardkodowania nazw parametrów należących do pluginu. +Preferuj tam mapy ograniczone do działań, a nie jedną płaską listę dla całego kanału, aby +parametr mediów przeznaczony tylko dla profilu nie był normalizowany przy niezwiązanych działaniach, takich jak +`send`. + +Core przekazuje zakres środowiska uruchomieniowego do tego kroku wykrywania. Ważne pola obejmują: - `accountId` - `currentChannelId` @@ -191,96 +199,98 @@ Core przekazuje zakres środowiska uruchomieniowego do tego kroku wykrywania. Wa - `agentId` - zaufane przychodzące `requesterSenderId` -Ma to znaczenie dla Pluginów zależnych od kontekstu. Kanał może ukrywać lub ujawniać -działania wiadomości w zależności od aktywnego konta, bieżącego pokoju/wątku/wiadomości lub -tożsamości zaufanego żądającego, bez zakodowanych na sztywno gałęzi specyficznych dla kanału w +Ma to 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 żądania bez hardkodowania gałęzi specyficznych dla kanału w narzędziu `message` w core. -To dlatego zmiany routingu embedded-runner nadal są pracą po stronie Pluginu: runner -odpowiada za przekazywanie bieżącej tożsamości czatu/sesji do granicy wykrywania Pluginu, -aby współdzielone narzędzie `message` udostępniało właściwą powierzchnię należącą do kanału dla bieżącej tury. +Właśnie dlatego zmiany routingu embedded-runner nadal należą do pracy nad pluginami: runner +odpowiada 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. -W przypadku pomocników wykonania należących do kanału, bundlowane Pluginy powinny utrzymywać środowisko uruchomieniowe wykonania -wewnątrz własnych modułów rozszerzeń. Core nie odpowiada już za środowiska uruchomieniowe działań wiadomości Discord, -Slack, Telegram czy WhatsApp w `src/agents/tools`. -Nie publikujemy oddzielnych podścieżek `plugin-sdk/*-action-runtime`, a bundlowane -Pluginy powinny importować własny lokalny kod środowiska uruchomieniowego bezpośrednio ze swoich -modułów należących do rozszerzenia. +W przypadku narzędzi pomocniczych wykonania należących do kanału, bundled pluginy powinny utrzymywać +środowisko uruchomieniowe wykonania wewnątrz własnych modułów rozszerzeń. Core nie odpowiada już za +środowiska uruchomieniowe działań wiadomości Discord, Slack, Telegram czy WhatsApp pod `src/agents/tools`. +Nie publikujemy osobnych podścieżek `plugin-sdk/*-action-runtime`, a bundled +pluginy powinny importować swój lokalny kod środowiska uruchomieniowego bezpośrednio z modułów +należących do ich rozszerzeń. -Ta sama granica dotyczy ogólnie powierzchni SDK nazwanych od dostawców: core nie powinien -importować wygodnych barrelów specyficznych dla kanałów dla Slack, Discord, Signal, -WhatsApp ani podobnych rozszerzeń. Jeśli core potrzebuje jakiegoś zachowania, powinien albo użyć -własnego barrela `api.ts` / `runtime-api.ts` bundlowanego Pluginu, albo wynieść tę potrzebę +Ta sama granica dotyczy ogólnie ścieżek SDK nazwanych według dostawców: core nie powinien +importować wygodnych barrelów specyficznych dla kanałów takich jak Slack, Discord, Signal, +WhatsApp lub podobnych rozszerzeń. Jeśli core potrzebuje jakiegoś zachowania, powinien albo +zużyć własny barrel `api.ts` / `runtime-api.ts` danego bundled pluginu, albo wynieść tę potrzebę do wąskiej, ogólnej możliwości we współdzielonym SDK. -W przypadku ankiet istnieją konkretnie dwie ścieżki wykonania: +Konkretnie dla ankiet istnieją dwie ścieżki wykonania: -- `outbound.sendPoll` to współdzielona baza dla kanałów, które pasują do wspólnego +- `outbound.sendPoll` to współdzielona baza dla kanałów pasujących do wspólnego modelu ankiet - `actions.handleAction("poll")` to preferowana ścieżka dla semantyki ankiet specyficznej dla kanału lub dodatkowych parametrów ankiet -Core odkłada teraz współdzielone parsowanie ankiet do czasu, aż 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, -nie będąc wcześniej blokowane przez ogólny parser ankiet. +Core odracza teraz wspólne parsowanie ankiet do chwili, gdy dyspozycja ankiety pluginu odrzuci +działanie, dzięki czemu obsługujące ankiety pluginu mogą akceptować pola ankiet specyficzne dla kanału +bez wcześniejszego blokowania przez ogólny parser ankiet. -Pełną sekwencję uruchamiania znajdziesz w [Potoku ładowania](#load-pipeline). +Pełną sekwencję uruchamiania znajdziesz w sekcji [Potok ładowania](#load-pipeline). ## Model własności możliwości -OpenClaw traktuje natywny Plugin jako granicę własności dla **firmy** albo -**funkcji**, a nie jako zbiór niepowiązanych integracji. +OpenClaw traktuje natywny plugin jako granicę własności dla **firmy** lub +**funkcji**, a nie jako zbiór przypadkowo powiązanych integracji. Oznacza to, że: -- Plugin firmy powinien zwykle odpowiadać za wszystkie powierzchnie OpenClaw skierowane do tej firmy -- Plugin funkcji powinien zwykle odpowiadać za pełną powierzchnię wprowadzanej przez siebie funkcji +- 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 możliwości core zamiast doraźnie ponownie implementować zachowanie dostawców Przykłady: -- bundlowany Plugin `openai` odpowiada za zachowanie dostawcy modeli OpenAI oraz za zachowanie OpenAI dotyczące +- bundled plugin `openai` odpowiada za zachowanie dostawcy modeli OpenAI oraz za zachowanie OpenAI dotyczące mowy + głosu w czasie rzeczywistym + rozumienia mediów + generowania obrazów -- bundlowany Plugin `elevenlabs` odpowiada za zachowanie mowy ElevenLabs -- bundlowany Plugin `microsoft` odpowiada za zachowanie mowy Microsoft -- bundlowany Plugin `google` odpowiada za zachowanie dostawcy modeli Google oraz za Google - w obszarze rozumienia mediów + generowania obrazów + wyszukiwania w sieci -- bundlowany Plugin `firecrawl` odpowiada za zachowanie Firecrawl dotyczące pobierania z sieci -- bundlowane Pluginy `minimax`, `mistral`, `moonshot` i `zai` odpowiadają za swoje +- bundled plugin `elevenlabs` odpowiada za zachowanie ElevenLabs dotyczące mowy +- bundled plugin `microsoft` odpowiada za zachowanie Microsoft dotyczące mowy +- bundled plugin `google` odpowiada za zachowanie dostawcy modeli Google oraz za zachowanie Google dotyczące + rozumienia mediów + generowania obrazów + wyszukiwania w sieci +- bundled plugin `firecrawl` odpowiada za zachowanie Firecrawl dotyczące pobierania z sieci +- bundled pluginy `minimax`, `mistral`, `moonshot` i `zai` odpowiadają za swoje backendy rozumienia mediów -- bundlowany Plugin `qwen` odpowiada za zachowanie dostawcy tekstu Qwen oraz +- bundled plugin `qwen` odpowiada za zachowanie dostawcy tekstowego Qwen oraz za rozumienie mediów i generowanie wideo -- Plugin `voice-call` jest Pluginem funkcji: odpowiada za transport połączeń, narzędzia, - CLI, trasy i mostkowanie strumieni mediów Twilio, ale korzysta ze współdzielonych możliwości mowy - oraz transkrypcji i głosu w czasie rzeczywistym zamiast bezpośrednio importować Pluginy dostawców +- plugin `voice-call` jest pluginem funkcjonalnym: odpowiada za transport połączeń, narzędzia, + CLI, trasy i mostkowanie strumienia mediów Twilio, ale korzysta ze współdzielonych możliwości mowy + oraz transkrypcji w czasie rzeczywistym i głosu w czasie rzeczywistym zamiast + bezpośrednio importować pluginy dostawców -Docelowy stan to: +Zamierzony stan końcowy jest następujący: -- OpenAI znajduje się w jednym Pluginie, nawet jeśli obejmuje modele tekstowe, mowę, obrazy i +- OpenAI znajduje się w jednym pluginie, nawet jeśli obejmuje modele tekstowe, mowę, obrazy i przyszłe wideo - inny dostawca może zrobić to samo dla własnego obszaru funkcjonalnego -- kanały nie muszą wiedzieć, który Plugin dostawcy jest właścicielem dostawcy; korzystają ze +- kanały nie muszą wiedzieć, który plugin dostawcy jest właścicielem dostawcy; korzystają ze współdzielonego kontraktu możliwości udostępnianego przez core To jest kluczowe rozróżnienie: - **plugin** = granica własności -- **capability** = kontrakt core, który wiele Pluginów może implementować lub wykorzystywać +- **możliwość** = kontrakt core, który wiele pluginów może implementować lub wykorzystywać -Jeśli więc OpenClaw dodaje nową dziedzinę, taką jak wideo, pierwsze pytanie nie brzmi -„który dostawca powinien mieć na sztywno zakodowaną obsługę wideo?”. Pierwsze pytanie brzmi: „jaki jest -kontrakt możliwości wideo w core?”. Gdy taki kontrakt istnieje, Pluginy dostawców -mogą się względem niego rejestrować, a Pluginy kanałów/funkcji mogą z niego korzystać. +Jeśli więc OpenClaw doda nową domenę, taką jak wideo, pierwsze pytanie nie brzmi +„który dostawca powinien na sztywno obsługiwać wideo?”. Pierwsze pytanie brzmi „jaki jest +kontrakt możliwości wideo w core?”. Gdy ten kontrakt już 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ściwym krokiem jest zwykle: +Jeśli taka możliwość jeszcze nie istnieje, właściwym krokiem jest zwykle: 1. zdefiniowanie brakującej możliwości w core -2. udostępnienie jej przez API/runtime Pluginów w sposób typowany +2. udostępnienie jej przez API/runtime pluginów w sposób typowany 3. podłączenie kanałów/funkcji do tej możliwości -4. pozwolenie Pluginom dostawców na rejestrowanie implementacji +4. pozwolenie pluginom dostawców na rejestrowanie implementacji -Dzięki temu własność pozostaje jawna, a jednocześnie unika się zachowania core zależnego od -jednego dostawcy lub jednorazowej ścieżki kodu specyficznej dla jednego Pluginu. +Pozwala to zachować jawną własność, a jednocześnie unika zachowania core, które zależy od +jednego dostawcy lub jednorazowej ścieżki kodu specyficznej dla pluginu. ### Warstwowanie możliwości @@ -288,25 +298,25 @@ Używaj tego modelu mentalnego przy podejmowaniu decyzji, gdzie powinien znajdow - **warstwa możliwości core**: współdzielona orkiestracja, polityka, fallback, reguły scalania konfiguracji, semantyka dostarczania i typowane kontrakty -- **warstwa Pluginu dostawcy**: API specyficzne dla dostawcy, uwierzytelnianie, katalogi modeli, synteza mowy, +- **warstwa pluginów dostawców**: API specyficzne dla dostawcy, autoryzacja, 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. - korzystająca z możliwości core i prezentująca je na określonej powierzchni +- **warstwa pluginów kanałów/funkcji**: integracje Slack/Discord/voice-call itd., + które wykorzystują możliwości core i prezentują je na określonej powierzchni Na przykład TTS ma taki układ: -- core odpowiada za politykę TTS podczas odpowiedzi, kolejność fallbacków, preferencje i dostarczanie do kanałów +- core odpowiada za politykę TTS w czasie odpowiedzi, kolejność fallbacków, preferencje i dostarczanie przez kanały - `openai`, `elevenlabs` i `microsoft` odpowiadają za implementacje syntezy -- `voice-call` korzysta z pomocnika runtime TTS dla telefonii +- `voice-call` wykorzystuje pomocnik środowiska uruchomieniowego TTS dla telefonii Ten sam wzorzec powinien być preferowany dla przyszłych możliwości. -### Przykład firmowego Pluginu z wieloma możliwościami +### Przykład pluginu firmy z wieloma możliwościami Plugin firmy powinien z zewnątrz sprawiać wrażenie spójnego. 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, pobierania z sieci i wyszukiwania w sieci, -dostawca może zarządzać wszystkimi swoimi powierzchniami w jednym miejscu: +dostawca może obsługiwać wszystkie swoje powierzchnie w jednym miejscu: ```ts import type { OpenClawPluginDefinition } from "openclaw/plugin-sdk/plugin-entry"; @@ -360,240 +370,242 @@ const plugin: OpenClawPluginDefinition = { export default plugin; ``` -Ważne nie są dokładne nazwy pomocników. Liczy się kształt: +Znaczenie nie mają dokładne nazwy helperów. Znaczenie ma kształt: -- jeden Plugin zarządza powierzchnią dostawcy -- core nadal zarządza kontraktami możliwości -- kanały i Pluginy funkcji korzystają z pomocników `api.runtime.*`, a nie z kodu dostawcy -- testy kontraktowe mogą sprawdzać, że Plugin zarejestrował możliwości, które - deklaruje jako własne +- jeden plugin jest właścicielem powierzchni dostawcy +- core nadal jest właścicielem kontraktów możliwości +- kanały i pluginy funkcjonalne wykorzystują helpery `api.runtime.*`, a nie kod dostawcy +- testy kontraktowe mogą sprawdzać, że plugin zarejestrował możliwości, do których + przyznaje się jako właściciel ### Przykład możliwości: rozumienie wideo -OpenClaw już traktuje rozumienie obrazów/audio/wideo jako jedną współdzieloną -możliwość. Ten sam model własności obowiązuje także tutaj: +OpenClaw już teraz traktuje rozumienie obrazów/audio/wideo jako jedną współdzieloną +możliwość. Obowiązuje tu ten sam model własności: 1. core definiuje kontrakt rozumienia mediów -2. Pluginy dostawców rejestrują odpowiednio `describeImage`, `transcribeAudio` i - `describeVideo` -3. kanały i Pluginy funkcji korzystają ze współdzielonego zachowania core zamiast +2. pluginy dostawców rejestrują `describeImage`, `transcribeAudio` i + `describeVideo`, jeśli dotyczy +3. kanały i pluginy funkcjonalne wykorzystują współdzielone zachowanie core zamiast podłączać się bezpośrednio do kodu dostawcy -Dzięki temu założenia dotyczące wideo jednego dostawcy nie zostają wpisane na stałe do core. Plugin zarządza -powierzchnią dostawcy; core zarządza kontraktem możliwości i zachowaniem fallback. +Pozwala to uniknąć utrwalania założeń jednego dostawcy dotyczących wideo w core. Plugin odpowiada za +powierzchnię dostawcy; core odpowiada za kontrakt możliwości i zachowanie fallback. -Generowanie wideo już wykorzystuje tę samą sekwencję: core zarządza typowanym -kontraktem możliwości i pomocnikiem runtime, a Pluginy dostawców rejestrują -implementacje `api.registerVideoGenerationProvider(...)` względem tego kontraktu. +Generowanie wideo już używa tej samej sekwencji: core odpowiada za typowany +kontrakt możliwości i helper środowiska uruchomieniowego, a pluginy dostawców rejestrują +implementacje `api.registerVideoGenerationProvider(...)` względem niego. -Potrzebujesz konkretnej listy wdrożeniowej? Zobacz +Potrzebujesz konkretnej listy kontrolnej wdrożenia? Zobacz [Capability Cookbook](/pl/plugins/architecture). ## 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ć. +Powierzchnia API pluginów jest celowo typowana i scentralizowana w +`OpenClawPluginApi`. Ten kontrakt definiuje obsługiwane punkty rejestracji oraz +pomocniki środowiska uruchomieniowego, na których plugin może polegać. Dlaczego to ma znaczenie: -- autorzy Pluginów otrzymują jeden stabilny wewnętrzny standard -- core może odrzucać zduplikowaną własność, na przykład dwa Pluginy rejestrujące ten sam - identyfikator dostawcy -- podczas uruchamiania mogą być prezentowane użyteczne diagnostyki dla nieprawidłowej rejestracji -- testy kontraktowe mogą egzekwować własność bundlowanych Pluginów i zapobiegać cichemu dryfowi +- autorzy pluginów otrzymują jeden stabilny wewnętrzny standard +- core może odrzucać duplikaty własności, na przykład gdy dwa pluginy rejestrują ten sam identyfikator + dostawcy +- uruchamianie może pokazywać użyteczne diagnostyki dla nieprawidłowej rejestracji +- testy kontraktowe mogą wymuszać własność bundled pluginów i zapobiegać cichemu dryfowi Istnieją dwie warstwy egzekwowania: -1. **egzekwowanie rejestracji w runtime** - Rejestr Pluginów waliduje rejestracje podczas ładowania Pluginów. Przykłady: +1. **egzekwowanie rejestracji w czasie działania** + Rejestr pluginów waliduje rejestracje podczas ładowania pluginów. Przykłady: zduplikowane identyfikatory dostawców, zduplikowane identyfikatory dostawców mowy i nieprawidłowe - rejestracje generują diagnostyki Pluginów zamiast niezdefiniowanego zachowania. + rejestracje powodują diagnostyki pluginów zamiast niezdefiniowanego zachowania. 2. **testy kontraktowe** - Bundlowane Pluginy są przechwytywane w rejestrach kontraktowych podczas uruchamiania testów, aby - OpenClaw mógł jawnie sprawdzać własność. Dziś jest to używane dla - dostawców modeli, dostawców mowy, dostawców wyszukiwania w sieci i własności bundlowanej rejestracji. + Bundled pluginy są przechwytywane w rejestrach kontraktowych podczas uruchamiania testów, dzięki czemu + OpenClaw może jawnie sprawdzać własność. Dziś jest to używane dla dostawców modeli, + dostawców mowy, dostawców wyszukiwania w sieci oraz własności rejestracji bundled + pluginów. -Praktyczny efekt jest taki, że OpenClaw z góry wie, który Plugin jest właścicielem której -powierzchni. Dzięki temu core i kanały mogą się płynnie składać, ponieważ własność jest -zadeklarowana, typowana i testowalna, a nie domyślna. +Praktyczny efekt jest taki, że OpenClaw z góry wie, który plugin jest właścicielem której +powierzchni. Dzięki temu core i kanały mogą płynnie się składać, ponieważ własność jest +zadeklarowana, typowana i testowalna, a nie dorozumiana. -### Co powinno należeć do kontraktu +### Co należy do kontraktu -Dobre kontrakty Pluginów są: +Dobre kontrakty pluginów są: - typowane - małe - specyficzne dla możliwości - należące do core -- możliwe do ponownego użycia przez wiele Pluginów +- wielokrotnego użytku przez wiele pluginów - możliwe do wykorzystania przez kanały/funkcje bez wiedzy o dostawcy -Złe kontrakty Pluginów to: +Złe kontrakty pluginów to: - polityka specyficzna dla dostawcy ukryta w core -- jednorazowe furtki dla Pluginów, które omijają rejestr +- jednorazowe furtki dla pluginów, które omijają rejestr - kod kanału sięgający bezpośrednio do implementacji dostawcy -- doraźne obiekty runtime, które nie są częścią `OpenClawPluginApi` ani +- doraźne obiekty środowiska uruchomieniowego, 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ć. +pozwól pluginom podłączyć się do niej. ## Model wykonania -Natywne Pluginy OpenClaw działają **w tym samym procesie** co Gateway. Nie są -sandboxowane. Załadowany natywny Plugin ma taki sam poziom zaufania na granicy procesu jak +Natywne pluginy OpenClaw działają **w procesie** razem z Gateway. Nie są +sandboxowane. Załadowany natywny plugin ma tę samą granicę zaufania na poziomie procesu co kod core. Konsekwencje: -- natywny Plugin może rejestrować narzędzia, handlery sieciowe, hooki i usługi -- błąd natywnego Pluginu może spowodować awarię Gateway lub destabilizację -- złośliwy natywny Plugin jest równoważny dowolnemu wykonaniu kodu wewnątrz procesu OpenClaw +- natywny plugin może rejestrować narzędzia, handlery sieciowe, hooki i usługi +- błąd natywnego pluginu może spowodować awarię lub destabilizację gateway +- złośliwy natywny plugin jest równoważny dowolnemu wykonaniu kodu wewnątrz + procesu OpenClaw -Zgodne bundle są domyślnie bezpieczniejsze, ponieważ OpenClaw obecnie traktuje je -jako pakiety metadanych/treści. W obecnych wydaniach oznacza to głównie bundlowane +Zgodne pakiety są domyślnie bezpieczniejsze, ponieważ OpenClaw obecnie traktuje je +jako pakiety metadanych/treści. W obecnych wydaniach dotyczy to głównie bundled Skills. -W przypadku Pluginów niebundlowanych używaj allowlist i jawnych ścieżek instalacji/ładowania. Traktuj -Pluginy workspace jako kod czasu programowania, a nie produkcyjne ustawienia domyślne. +W przypadku pluginów innych niż bundled używaj allowlist i jawnych ścieżek instalacji/ładowania. Traktuj +pluginy workspace jako kod czasu programowania, a nie domyślne rozwiązania produkcyjne. -W przypadku nazw pakietów bundlowanego workspace zachowuj identyfikator Pluginu zakotwiczony w nazwie npm: -domyślnie `@openclaw/` albo zatwierdzony typowany sufiks, taki jak +W przypadku nazw pakietów bundled workspace identyfikator pluginu powinien być zakotwiczony w nazwie npm: +domyślnie `@openclaw/` lub zatwierdzony typowany sufiks, taki jak `-provider`, `-plugin`, `-speech`, `-sandbox` lub `-media-understanding`, gdy -pakiet celowo udostępnia węższą rolę Pluginu. +pakiet celowo udostępnia węższą rolę pluginu. Ważna uwaga dotycząca zaufania: -- `plugins.allow` ufa **identyfikatorom Pluginów**, a nie pochodzeniu źródła. -- Plugin workspace o tym samym identyfikatorze co bundlowany Plugin celowo przesłania - bundlowaną kopię, gdy taki Plugin workspace jest włączony/na allowliście. -- To normalne i przydatne przy lokalnym programowaniu, testowaniu poprawek i hotfixach. +- `plugins.allow` ufa **identyfikatorom pluginów**, a nie pochodzeniu źródła. +- Plugin workspace z tym samym identyfikatorem co bundled plugin celowo przesłania + bundled kopię, gdy taki plugin workspace jest włączony/znajduje się na allowliście. +- To normalne i przydatne dla lokalnego programowania, testowania poprawek i hotfixów. ## Granica eksportu OpenClaw eksportuje możliwości, a nie wygodne implementacje. -Rejestrację możliwości należy utrzymywać jako publiczną. Należy ograniczać eksport pomocników niebędących kontraktami: +Zachowaj publiczną rejestrację możliwości. Ogranicz eksporty helperów spoza kontraktu: -- podścieżki pomocnicze specyficzne dla bundlowanych Pluginów +- podścieżki pomocnicze specyficzne dla bundled pluginów - podścieżki infrastruktury runtime, które nie są przeznaczone jako publiczne API -- wygodne pomocniki specyficzne dla dostawcy -- pomocniki konfiguracji/onboardingu, które są szczegółami implementacyjnymi +- helpery wygody specyficzne dla dostawców +- helpery konfiguracji/onboardingu, które są szczegółami implementacji -Niektóre podścieżki pomocnicze bundlowanych Pluginów nadal pozostają w wygenerowanej mapie eksportów SDK -ze względu na kompatybilność i utrzymanie bundlowanych Pluginów. Obecne przykłady obejmują +Niektóre podścieżki pomocnicze bundled pluginów nadal pozostają w wygenerowanej mapie eksportów SDK +ze względu na kompatybilność i utrzymanie bundled pluginów. Aktualne przykłady to `plugin-sdk/feishu`, `plugin-sdk/feishu-setup`, `plugin-sdk/zalo`, -`plugin-sdk/zalo-setup` oraz kilka powierzchni `plugin-sdk/matrix*`. Traktuj je jako +`plugin-sdk/zalo-setup` oraz kilka ścieżek `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. +nowych pluginów zewnętrznych. ## Potok ładowania -Podczas uruchamiania OpenClaw wykonuje w przybliżeniu to: +Podczas uruchamiania OpenClaw wykonuje w przybliżeniu następujące kroki: -1. wykrywa katalogi główne kandydatów na Pluginy -2. odczytuje natywne lub zgodne manifesty bundli oraz metadane pakietów +1. wykrywa katalogi główne kandydackich pluginów +2. odczytuje natywne lub zgodne manifesty pakietów i metadane pakietów 3. odrzuca niebezpiecznych kandydatów -4. normalizuje konfigurację Pluginów (`plugins.enabled`, `allow`, `deny`, `entries`, +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 +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 -`activate` jest starszym aliasem dla `register` — loader rozwiązuje to, co jest obecne (`def.register ?? def.activate`), i wywołuje to w tym samym miejscu. Wszystkie bundlowane Pluginy używają `register`; dla nowych Pluginów preferuj `register`. +`activate` to starszy alias dla `register` — loader rozwiązuje, który z nich jest obecny (`def.register ?? def.activate`) i wywołuje go w tym samym miejscu. Wszystkie bundled pluginy używają `register`; dla nowych pluginów preferuj `register`. Bramki bezpieczeństwa działają **przed** wykonaniem runtime. Kandydaci są blokowani, -gdy punkt wejścia wychodzi poza katalog główny Pluginu, ścieżka jest zapisywalna globalnie albo -własność ścieżki wygląda podejrzanie dla Pluginów niebundlowanych. +gdy entry wychodzi poza katalog główny pluginu, ścieżka ma uprawnienia world-writable lub +w przypadku pluginów innych niż bundled własność ścieżki wygląda podejrzanie. -### Zachowanie oparte na manifeście +### Zachowanie manifest-first -Manifest jest źródłem prawdy płaszczyzny sterowania. OpenClaw używa go do: +Manifest jest źródłem prawdy dla płaszczyzny sterowania. OpenClaw używa go do: -- identyfikacji Pluginu -- wykrywania zadeklarowanych kanałów/Skills/schematu konfiguracji lub możliwości bundla +- identyfikacji pluginu +- wykrywania zadeklarowanych kanałów/Skills/schematu konfiguracji lub możliwości pakietu - walidacji `plugins.entries..config` -- wzbogacania etykiet/placeholderów w Control UI +- uzupełniania etykiet/placeholderów w Control UI - wyświetlania metadanych instalacji/katalogu -- zachowania taniej aktywacji i deskryptorów konfiguracji bez ładowania runtime Pluginu +- zachowania tanich deskryptorów aktywacji i konfiguracji bez ładowania runtime pluginu -W przypadku natywnych Pluginów moduł runtime jest częścią płaszczyzny danych. Rejestruje +W przypadku natywnych pluginów moduł runtime jest częścią płaszczyzny danych. Rejestruje rzeczywiste zachowanie, takie jak hooki, narzędzia, polecenia czy przepływy dostawców. Opcjonalne bloki manifestu `activation` i `setup` pozostają w płaszczyźnie sterowania. -Są to deskryptory wyłącznie z metadanymi dla planowania aktywacji i wykrywania konfiguracji; +Są to wyłącznie deskryptory metadanych dla planowania aktywacji i wykrywania konfiguracji; nie zastępują rejestracji runtime, `register(...)` ani `setupEntry`. -Pierwsi aktywni konsumenci aktywacji używają teraz wskazówek manifestu dotyczących poleceń, kanałów i dostawców, -aby zawężać ładowanie Pluginów przed szerszą materializacją rejestru: +Pierwsi konsumenci aktywacji na żywo używają teraz wskazówek manifestu dotyczących poleceń, kanałów i dostawców, +aby zawężać ładowanie pluginów przed szerszą materializacją rejestru: -- ładowanie CLI zawęża się do Pluginów, które są właścicielami żądanego polecenia głównego -- rozwiązywanie konfiguracji kanału/Pluginu zawęża się do Pluginów, które są właścicielami żądanego +- ładowanie CLI zawęża się do pluginów, które są właścicielami żądanej głównej komendy +- rozwiązywanie konfiguracji kanałów/pluginów zawęża się do pluginów, które są właścicielami żądanego identyfikatora kanału -- jawne rozwiązywanie konfiguracji/runtime dostawcy zawęża się do Pluginów, które są właścicielami +- jawne rozwiązywanie konfiguracji/runtime dostawców zawęża się do pluginów, które są właścicielami żądanego identyfikatora dostawcy Wykrywanie konfiguracji preferuje teraz identyfikatory należące do deskryptorów, takie jak `setup.providers` i -`setup.cliBackends`, aby zawężać kandydatów na Pluginy, zanim nastąpi fallback do -`setup-api` dla Pluginów, które nadal potrzebują hooków runtime na etapie konfiguracji. Jeśli więcej niż -jeden wykryty Plugin deklaruje ten sam znormalizowany identyfikator dostawcy konfiguracji lub backendu CLI, -wyszukiwanie konfiguracji odmawia wyboru niejednoznacznego właściciela zamiast polegać na kolejności wykrycia. +`setup.cliBackends`, aby zawężać kandydackie pluginy, zanim nastąpi powrót do +`setup-api` dla pluginów, które nadal potrzebują hooków runtime w czasie konfiguracji. Jeśli więcej niż +jeden wykryty plugin zgłasza ten sam znormalizowany identyfikator dostawcy konfiguracji lub backendu CLI, +wyszukiwanie konfiguracji odrzuca niejednoznacznego właściciela zamiast polegać na kolejności wykrywania. -### Co loader przechowuje w cache +### Co loader przechowuje w pamięci podręcznej -OpenClaw utrzymuje krótkotrwałe cache w procesie dla: +OpenClaw utrzymuje krótkotrwałe pamięci podręczne w procesie dla: - wyników wykrywania - danych rejestru manifestów -- załadowanych rejestrów Pluginów +- załadowanych rejestrów pluginów -Te cache zmniejszają skokowy koszt uruchamiania i powtarzanych poleceń. Można o nich bezpiecznie myśleć -jako o krótkotrwałych cache wydajnościowych, a nie trwałym przechowywaniu. +Te pamięci podręczne zmniejszają koszt skokowego uruchamiania i wielokrotnego wykonywania poleceń. Można o nich +bezpiecznie myśleć jako o krótkotrwałych pamięciach podręcznych wydajności, a nie o trwałym stanie. Uwaga dotycząca wydajności: - Ustaw `OPENCLAW_DISABLE_PLUGIN_DISCOVERY_CACHE=1` lub - `OPENCLAW_DISABLE_PLUGIN_MANIFEST_CACHE=1`, aby wyłączyć te cache. -- Dostosuj okna cache przez `OPENCLAW_PLUGIN_DISCOVERY_CACHE_MS` i + `OPENCLAW_DISABLE_PLUGIN_MANIFEST_CACHE=1`, aby wyłączyć te pamięci podręczne. +- Dostosuj okna pamięci podręcznej za pomocą `OPENCLAW_PLUGIN_DISCOVERY_CACHE_MS` i `OPENCLAW_PLUGIN_MANIFEST_CACHE_MS`. ## Model rejestru -Załadowane Pluginy nie mutują bezpośrednio przypadkowych globali core. Rejestrują się w -centralnym rejestrze Pluginów. +Załadowane pluginy nie modyfikują bezpośrednio przypadkowych globalnych elementów core. Rejestrują się w +centralnym rejestrze pluginów. Rejestr śledzi: -- rekordy Pluginów (tożsamość, źródło, pochodzenie, status, diagnostyka) +- rekordy pluginów (tożsamość, źródło, pochodzenie, status, diagnostyka) - narzędzia -- starsze hooki i hooki typowane +- legacy hooki i hooki typowane - kanały -- dostawcy -- handlery Gateway RPC +- dostawców +- handlery RPC Gateway - trasy HTTP - rejestratory CLI - usługi działające w tle -- polecenia należące do Pluginów +- polecenia należące do pluginów -Funkcje core odczytują następnie z tego rejestru zamiast komunikować się -bezpośrednio z modułami Pluginów. Dzięki temu ładowanie pozostaje jednokierunkowe: +Funkcje core następnie odczytują dane 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 core -> korzystanie z rejestru +- moduł pluginu -> rejestracja w rejestrze +- runtime core -> konsumpcja rejestru -To rozdzielenie ma znaczenie dla utrzymywalności. Oznacza, że większość powierzchni core potrzebuje -tylko jednego punktu integracji: „odczytaj rejestr”, a nie „dodaj specjalny przypadek dla każdego modułu Pluginu”. +To rozdzielenie ma znaczenie dla łatwości utrzymania. Oznacza, że większość powierzchni core potrzebuje +tylko jednego punktu integracji: „odczytaj rejestr”, a nie „obsłuż specjalnie każdy moduł pluginu”. -## Callbacki wiązania rozmowy +## Callbacki powiązania konwersacji -Pluginy, które wiążą rozmowę, mogą reagować, gdy zatwierdzenie zostanie rozstrzygnięte. +Pluginy, które wiążą konwersację, mogą reagować, gdy zatwierdzenie zostanie rozstrzygnięte. Użyj `api.onConversationBindingResolved(...)`, aby otrzymać callback po zatwierdzeniu lub odrzuceniu -żądania wiązania: +żądania powiązania: ```ts export default { @@ -618,20 +630,20 @@ Pola ładunku callbacku: - `status`: `"approved"` lub `"denied"` - `decision`: `"allow-once"`, `"allow-always"` lub `"deny"` - `binding`: rozstrzygnięte powiązanie dla zatwierdzonych żądań -- `request`: podsumowanie pierwotnego żądania, wskazówka odłączenia, identyfikator nadawcy oraz - metadane rozmowy +- `request`: podsumowanie oryginalnego żądania, wskazówka odłączenia, identyfikator nadawcy oraz + metadane konwersacji -Ten callback służy wyłącznie do powiadamiania. Nie zmienia tego, kto może wiązać -rozmowę, i uruchamia się po zakończeniu obsługi zatwierdzenia przez core. +Ten callback służy wyłącznie do powiadamiania. Nie zmienia tego, kto może powiązać +konwersację, i działa po zakończeniu obsługi zatwierdzenia przez core. -## Hooki runtime dostawców +## Hooki środowiska uruchomieniowego dostawcy Pluginy dostawców mają teraz dwie warstwy: -- metadane manifestu: `providerAuthEnvVars` do taniego wyszukiwania uwierzytelniania dostawcy przez zmienne środowiskowe +- metadane manifestu: `providerAuthEnvVars` dla taniego wyszukiwania uwierzytelniania dostawcy przez env przed załadowaniem runtime, `providerAuthAliases` dla wariantów dostawcy współdzielących - uwierzytelnianie, `channelEnvVars` do taniego wyszukiwania środowiska/konfiguracji kanału przed - załadowaniem runtime, oraz `providerAuthChoices` do tanich etykiet onboardingu/wyboru uwierzytelniania i + uwierzytelnianie, `channelEnvVars` dla taniego wyszukiwania env/konfiguracji kanału przed + załadowaniem runtime oraz `providerAuthChoices` dla tanich etykiet onboardingu/wyboru uwierzytelniania i metadanych flag CLI przed załadowaniem runtime - hooki czasu konfiguracji: `catalog` / starsze `discovery` oraz `applyConfigDefaults` - hooki runtime: `normalizeModelId`, `normalizeTransport`, @@ -655,86 +667,86 @@ Pluginy dostawców mają teraz dwie warstwy: `sanitizeReplayHistory`, `validateReplayTurns`, `onModelSelected` OpenClaw nadal odpowiada za ogólną pętlę agenta, failover, obsługę transkryptu i -politykę narzędzi. Te hooki są powierzchnią rozszerzeń dla zachowania specyficznego dla dostawcy bez -potrzeby tworzenia całego niestandardowego transportu wnioskowania. +politykę narzędzi. Te hooki stanowią powierzchnię rozszerzeń dla zachowań specyficznych dla dostawcy bez +konieczności tworzenia całkowicie własnego transportu wnioskowania. -Używaj manifestu `providerAuthEnvVars`, gdy dostawca ma poświadczenia oparte na zmiennych środowiskowych, -które ogólne ścieżki uwierzytelniania/statusu/wyboru modelu powinny widzieć bez ładowania runtime Pluginu. -Używaj manifestu `providerAuthAliases`, gdy jeden identyfikator dostawcy powinien ponownie używać -zmiennych środowiskowych, profili uwierzytelniania, uwierzytelniania opartego na konfiguracji i opcji onboardingu z kluczem API -innego identyfikatora dostawcy. Używaj manifestu `providerAuthChoices`, gdy powierzchnie CLI onboardingu/wyboru uwierzytelniania -powinny znać identyfikator opcji dostawcy, etykiety grup i prostą obsługę uwierzytelniania jedną flagą -bez ładowania runtime dostawcy. Zachowaj runtime dostawcy `envVars` dla wskazówek skierowanych do operatora, -takich jak etykiety onboardingu lub zmienne konfiguracji OAuth `client-id`/`client-secret`. +Użyj manifestu `providerAuthEnvVars`, gdy dostawca ma poświadczenia oparte na env, +które ogólne ścieżki auth/status/wyboru modelu powinny widzieć bez ładowania runtime pluginu. Użyj manifestu +`providerAuthAliases`, gdy jeden identyfikator dostawcy ma ponownie używać zmiennych env innego +identyfikatora dostawcy, profili auth, auth opartego na konfiguracji i opcji onboardingu klucza API. Użyj manifestu +`providerAuthChoices`, gdy powierzchnie CLI onboardingu/wyboru auth powinny znać identyfikator opcji dostawcy, +etykiety grup i proste połączenie auth z użyciem jednej flagi bez ładowania runtime dostawcy. Zachowaj runtime dostawcy +`envVars` dla wskazówek skierowanych do operatora, takich jak etykiety onboardingu lub zmienne konfiguracji +client-id/client-secret dla OAuth. -Używaj manifestu `channelEnvVars`, gdy kanał ma uwierzytelnianie lub konfigurację sterowane przez zmienne środowiskowe, które -ogólny fallback do zmiennych środowiskowych powłoki, sprawdzanie konfiguracji/statusu lub prompty konfiguracji powinny widzieć +Użyj manifestu `channelEnvVars`, gdy kanał ma auth lub konfigurację sterowaną przez env, które +ogólny fallback shell-env, kontrole config/status lub prompty konfiguracji powinny widzieć bez ładowania runtime kanału. -### Kolejność hooków i ich użycie +### Kolejność hooków i sposób użycia -Dla Pluginów modeli/dostawców OpenClaw wywołuje hooki mniej więcej w tej kolejności. +W przypadku pluginów modeli/dostawców 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 zarządza katalogiem lub domyślnymi wartościami `baseUrl` | -| 2 | `applyConfigDefaults` | Stosuje globalne domyślne ustawienia konfiguracji należące do dostawcy podczas materializacji konfiguracji | Wartości domyślne zależą od trybu uwierzytelniania, zmiennych środowiskowych lub semantyki rodziny modeli dostawcy | -| -- | _(built-in model lookup)_ | OpenClaw najpierw próbuje normalnej ścieżki rejestru/katalogu | _(to nie jest hook Pluginu)_ | -| 3 | `normalizeModelId` | Normalizuje starsze aliasy lub aliasy identyfikatorów modeli w wersji preview przed wyszukaniem | Dostawca zarządza porządkowaniem aliasów przed rozwiązaniem kanonicznego 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 rozwiązaniem runtime/dostawcy | Dostawca potrzebuje porządkowania konfiguracji, które powinno znajdować się razem z Pluginem; bundlowane pomocniki rodziny Google dodatkowo zabezpieczają wspierane wpisy konfiguracji Google | -| 6 | `applyNativeStreamingUsageCompat` | Stosuje przepisy zgodności natywnego użycia streamingu do dostawców konfiguracji | Dostawca potrzebuje poprawek metadanych natywnego użycia streamingu zależnych od endpointu | -| 7 | `resolveConfigApiKey` | Rozwiązuje uwierzytelnianie markerem środowiskowym dla dostawców konfiguracji przed załadowaniem uwierzytelniania runtime | Dostawca ma własne rozwiązywanie klucza API markera środowiskowego; `amazon-bedrock` ma tu również wbudowany resolver markera środowiskowego AWS | -| 8 | `resolveSyntheticAuth` | Ujawnia lokalne/samohostowane lub oparte na konfiguracji uwierzytelnianie bez utrwalania jawnego tekstu | Dostawca może działać z syntetycznym/lokalnym markerem poświadczeń | -| 9 | `resolveExternalAuthProfiles` | Nakłada zewnętrzne profile uwierzytelniania 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 uwierzytelniania bez utrwalania skopiowanych tokenów odświeżania | -| 10 | `shouldDeferSyntheticProfileAuth` | Obniża priorytet zapisanych syntetycznych placeholderów profili względem uwierzytelniania opartego na zmiennych środowiskowych/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 którym `resolveDynamicModel` uruchamia się ponownie | Dostawca potrzebuje metadanych sieciowych przed rozwiązaniem nieznanych identyfikatorów | -| 13 | `normalizeResolvedModel` | Ostateczne przepisanie przed użyciem rozwiązanego modelu przez embedded runner | Dostawca potrzebuje przepisania transportu, ale nadal używa transportu core | -| 14 | `contributeResolvedModelCompat` | Dostarcza 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 transkryptu/narzędzi należące do dostawcy, używane przez współdzieloną logikę core | Dostawca potrzebuje niestandardowych zachowań transkryptu/rodziny dostawcy | -| 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 reguł specyficznych dla dostawcy | -| 18 | `resolveReasoningOutputMode` | Wybiera natywny lub tagowany kontrakt wyjścia rozumowania | Dostawca potrzebuje tagowanego wyjścia rozumowania/końcowego zamiast natywnych pól | -| 19 | `prepareExtraParams` | Normalizacja parametrów żądania przed ogólnymi wrapperami opcji strumienia | Dostawca potrzebuje domyślnych parametrów żądania lub porządkowania parametrów specyficznych dla dostawcy | -| 20 | `createStreamFn` | Całkowicie zastępuje normalną ścieżkę strumienia niestandardowym transportem | Dostawca potrzebuje niestandardowego protokołu przewodowego, a nie tylko wrappera | -| 21 | `wrapStreamFn` | Wrapper strumienia po zastosowaniu ogólnych wrapperów | Dostawca potrzebuje wrapperów zgodności nagłówków/treści żądania/modelu bez niestandardowego transportu | -| 22 | `resolveTransportTurnState` | Dołącza natywne nagłówki transportu lub metadane dla każdej tury | Dostawca chce, aby ogólne transporty wysyłały natywną tożsamość tury dostawcy | -| 23 | `resolveWebSocketSessionPolicy` | Dołącza natywne nagłówki WebSocket lub politykę schładzania sesji | Dostawca chce, aby ogólne transporty WS dostrajały nagłówki sesji lub politykę fallback | -| 24 | `formatApiKey` | Formater profilu uwierzytelniania: zapisany profil staje się łańcuchem `apiKey` dla runtime | Dostawca przechowuje dodatkowe metadane uwierzytelniania 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 mechanizmów odświeżania `pi-ai` | -| 26 | `buildAuthDoctorHint` | Wskazówka naprawcza dołączana, gdy odświeżanie OAuth się nie powiedzie | Dostawca potrzebuje własnych wskazówek naprawy uwierzytelniania po błędzie odświeżania | -| 27 | `matchesContextOverflowError` | Matcher przepełnienia okna kontekstowego należący 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/overload/itd. | -| 29 | `isCacheTtlEligible` | Polityka cache promptów dla dostawców proxy/backhaul | Dostawca potrzebuje bramkowania TTL cache specyficznego dla proxy | -| 30 | `buildMissingAuthMessage` | Zastępuje ogólny komunikat odzyskiwania po braku uwierzytelnienia | Dostawca potrzebuje własnej wskazówki odzyskiwania po braku uwierzytelnienia | -| 31 | `suppressBuiltInModel` | Tłumienie nieaktualnych modeli upstream oraz opcjonalna wskazówka błędu dla użytkownika | Dostawca musi ukryć nieaktualne wiersze upstream lub zastąpić je wskazówką dostawcy | -| 32 | `augmentModelCatalog` | Syntetyczne/końcowe wiersze katalogu dołączane po wykrywaniu | Dostawca potrzebuje syntetycznych wierszy zgodności przyszłej w `models list` i selektorach | -| 33 | `isBinaryThinking` | Przełącznik rozumowania w trybie włącz/wyłącz dla dostawców z binarnym myśleniem | Dostawca udostępnia wyłącznie binarne myślenie włącz/wyłącz | -| 34 | `supportsXHighThinking` | Obsługa rozumowania `xhigh` dla wybranych modeli | Dostawca chce `xhigh` tylko dla podzbioru modeli | -| 35 | `resolveDefaultThinkingLevel` | Domyślny poziom `/think` dla określonej rodziny modeli | Dostawca zarządza domyślną polityką `/think` dla rodziny modeli | -| 36 | `isModernModelRef` | Matcher nowoczesnych modeli dla filtrów profili live i wyboru smoke | Dostawca zarządza dopasowaniem preferowanych modeli dla live/smoke | -| 37 | `prepareRuntimeAuth` | Zamienia skonfigurowane poświadczenie na rzeczywisty token/klucz runtime tuż przed wnioskowaniem | Dostawca potrzebuje wymiany tokenu lub krótkotrwałego poświadczenia żądania | -| 38 | `resolveUsageAuth` | Rozwiązuje poświadczenia użycia/rozliczeń dla `/usage` i powiązanych powierzchni statusu | Dostawca potrzebuje niestandardowego parsowania tokenu użycia/limitu lub innych poświadczeń użycia | -| 39 | `fetchUsageSnapshot` | Pobiera i normalizuje snapshoty użycia/limitów specyficzne dla dostawcy po rozwiązaniu uwierzytelnienia | Dostawca potrzebuje własnego endpointu użycia lub parsera ładunku | -| 40 | `createEmbeddingProvider` | Buduje adapter embeddingów należący do dostawcy dla pamięci/wyszukiwania | Zachowanie embeddingów pamięci powinno należeć do Pluginu dostawcy | -| 41 | `buildReplayPolicy` | Zwraca politykę replay sterującą obsługą transkryptu dla dostawcy | Dostawca potrzebuje niestandardowej polityki transkryptu (na przykład usuwania bloków myślenia) | -| 42 | `sanitizeReplayHistory` | Przepisuje historię replay po ogólnym czyszczeniu transkryptu | Dostawca potrzebuje przepisów replay specyficznych dla dostawcy wykraczających poza współdzielone pomocniki Compaction | -| 43 | `validateReplayTurns` | Ostateczna walidacja lub przekształcenie tur replay przed embedded runnerem | Transport dostawcy wymaga bardziej rygorystycznej walidacji tur po ogólnej sanitacji | -| 44 | `onModelSelected` | Uruchamia skutki uboczne po wyborze modelu należące do dostawcy | Dostawca potrzebuje telemetrii lub stanu należącego do dostawcy, gdy model staje się aktywny | +| --- | --------------------------------- | -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | +| 1 | `catalog` | Publikuje konfigurację dostawcy do `models.providers` podczas generowania `models.json` | Dostawca jest właścicielem katalogu lub domyślnych wartości `base URL` | +| 2 | `applyConfigDefaults` | Stosuje globalne domyślne wartości konfiguracji należące do dostawcy podczas materializacji konfiguracji | Wartości domyślne zależą od trybu auth, env lub semantyki rodziny modeli dostawcy | +| -- | _(built-in model lookup)_ | OpenClaw najpierw próbuje zwykłej ścieżki rejestru/katalogu | _(to nie jest hook pluginu)_ | +| 3 | `normalizeModelId` | Normalizuje starsze aliasy identyfikatorów modeli lub aliasy wersji preview przed wyszukaniem | Dostawca jest właścicielem czyszczenia aliasów przed rozstrzygnięciem kanonicznego modelu | +| 4 | `normalizeTransport` | Normalizuje `api` / `baseUrl` rodziny dostawców przed ogólnym składaniem modelu | Dostawca odpowiada za 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 znajdować się razem z pluginem; bundled helpery rodziny Google pełnią też rolę zabezpieczenia dla obsługiwanych wpisów konfiguracji Google | +| 6 | `applyNativeStreamingUsageCompat` | Stosuje zgodnościowe przekształcenia użycia natywnego streamingu do dostawców konfiguracji | Dostawca potrzebuje poprawek metadanych użycia natywnego streamingu zależnych od endpointu | +| 7 | `resolveConfigApiKey` | Rozstrzyga auth typu env-marker dla dostawców konfiguracji przed załadowaniem auth runtime | Dostawca ma własne rozstrzyganie klucza API env-marker; `amazon-bedrock` ma tu również wbudowany resolver env-marker AWS | +| 8 | `resolveSyntheticAuth` | Udostępnia auth lokalne/self-hosted lub oparte na konfiguracji bez utrwalania jawnego tekstu | Dostawca może działać z syntetycznym/lokalnym znacznikiem 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 zapisanych syntetycznych placeholderów profili względem auth opartego na env/konfiguracji | Dostawca przechowuje syntetyczne profile-placeholdery, które nie powinny mieć pierwszeństwa | +| 11 | `resolveDynamicModel` | Synchroniczny fallback dla należących do dostawcy identyfikatorów modeli, których nie ma jeszcze w lokalnym rejestrze | Dostawca akceptuje dowolne identyfikatory modeli z upstreamu | +| 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 przekształceń transportu, ale nadal używa transportu core | +| 14 | `contributeResolvedModelCompat` | Dodaje flagi zgodności dla modeli dostawcy działających za innym zgodnym transportem | Dostawca rozpoznaje własne modele na transportach proxy bez przejmowania własności dostawcy | +| 15 | `capabilities` | Metadane transkryptu/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 czyszczenia schematów na poziomie rodziny transportu | +| 17 | `inspectToolSchemas` | Udostępnia diagnostykę schematów należącą do dostawcy po normalizacji | Dostawca chce ostrzeżeń o słowach kluczowych bez uczenia core reguł specyficznych dla dostawcy | +| 18 | `resolveReasoningOutputMode` | Wybiera kontrakt wyjścia rozumowania: natywny lub otagowany | Dostawca potrzebuje otagowanego rozumowania/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 lub czyszczenia parametrów dla konkretnego dostawcy | +| 20 | `createStreamFn` | Całkowicie zastępuje zwykłą ścieżkę streamu niestandardowym transportem | Dostawca potrzebuje własnego protokołu przewodowego, a nie tylko wrappera | +| 21 | `wrapStreamFn` | Wrapper streamu po zastosowaniu wrapperów ogólnych | Dostawca potrzebuje wrapperów zgodności dla nagłówków/treści/modelu żądania bez własnego transportu | +| 22 | `resolveTransportTurnState` | Dołącza natywne nagłówki transportu na turę lub metadane | 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 lub politykę fallback | +| 24 | `formatApiKey` | Formater profilu auth: zapisany profil staje się ciągiem `apiKey` w runtime | Dostawca przechowuje dodatkowe metadane auth i potrzebuje niestandardowego kształtu tokenu w 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 mechanizmów odświeżania `pi-ai` | +| 26 | `buildAuthDoctorHint` | Wskazówka naprawcza dołączana po nieudanym odświeżeniu OAuth | Dostawca potrzebuje własnych wskazówek naprawy auth po błędzie odświeżania | +| 27 | `matchesContextOverflowError` | Matcher przepełnienia okna kontekstu należący do dostawcy | Dostawca ma surowe błędy przepełnienia, których nie wykryją ogólne heurystyki | +| 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ępstwo dla ogólnego komunikatu odzyskiwania po brakującym auth | Dostawca potrzebuje własnej wskazówki odzyskiwania po brakującym auth | +| 31 | `suppressBuiltInModel` | Tłumienie nieaktualnych modeli z upstreamu plus opcjonalna wskazówka błędu dla użytkownika | Dostawca musi ukryć nieaktualne wiersze upstreamu lub zastąpić je wskazówką od dostawcy | +| 32 | `augmentModelCatalog` | Syntetyczne/końcowe wiersze katalogu dodawane po wykryciu | Dostawca potrzebuje syntetycznych wierszy forward-compat w `models list` i selektorach | +| 33 | `isBinaryThinking` | Przełącznik rozumowania włącz/wyłącz dla dostawców binary-thinking | Dostawca udostępnia tylko binarne włączanie/wyłączanie rozumowania | +| 34 | `supportsXHighThinking` | Obsługa rozumowania `xhigh` dla wybranych modeli | Dostawca chce `xhigh` tylko dla części modeli | +| 35 | `resolveDefaultThinkingLevel` | Domyślny poziom `/think` dla konkretnej rodziny modeli | Dostawca odpowiada za domyślną politykę `/think` dla rodziny modeli | +| 36 | `isModernModelRef` | Matcher nowoczesnych modeli dla filtrów profili live i wyboru smoke | Dostawca odpowiada za dopasowywanie preferowanych modeli live/smoke | +| 37 | `prepareRuntimeAuth` | Wymienia skonfigurowane poświadczenie na rzeczywisty token/klucz runtime tuż przed wnioskowaniem | Dostawca potrzebuje wymiany tokenu lub krótkotrwałego poświadczenia żądania | +| 38 | `resolveUsageAuth` | Rozstrzyga poświadczenia użycia/rozliczeń dla `/usage` i powiązanych powierzchni statusu | Dostawca potrzebuje niestandardowego parsowania tokenu użycia/limitu lub innego poświadczenia użycia | +| 39 | `fetchUsageSnapshot` | Pobiera i normalizuje snapshoty użycia/limitów specyficzne dla dostawcy po rozstrzygnięciu auth | Dostawca potrzebuje endpointu użycia specyficznego dla dostawcy lub parsera ładunku | +| 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 transkryptu (na przykład usuwania bloków rozumowania) | +| 42 | `sanitizeReplayHistory` | Przepisuje historię replay po ogólnym czyszczeniu transkryptu | Dostawca potrzebuje przekształceń replay specyficznych dla dostawcy wykraczających poza współdzielone helpery Compaction | +| 43 | `validateReplayTurns` | Końcowa walidacja lub przekształcanie 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 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 obsługujących hooki, -dopóki któryś faktycznie nie zmieni identyfikatora modelu albo transportu/konfiguracji. Dzięki temu -shimy aliasów/zgodności dostawców nadal działają bez konieczności, by wywołujący wiedział, -który bundlowany Plugin jest właścicielem danego przepisania. Jeśli żaden hook dostawcy nie przepisze -wspieranego wpisu konfiguracji z rodziny Google, bundlowany normalizator konfiguracji Google nadal zastosuje -to porządkowanie zgodności. +dopasowany plugin dostawcy, a następnie przechodzą do innych pluginów dostawców obsługujących hooki, +dopóki któryś rzeczywiście nie zmieni identyfikatora modelu albo transportu/konfiguracji. Dzięki temu +shimy aliasów/zgodności dostawców nadal działają bez wymagania, aby wywołujący wiedział, który +bundled plugin jest właścicielem przepisania. Jeśli żaden hook dostawcy nie przepisze obsługiwanego +wpisu konfiguracji z rodziny Google, bundled normalizator konfiguracji Google nadal zastosuje +to czyszczenie zgodności. -Jeśli dostawca potrzebuje w pełni niestandardowego protokołu przewodowego lub niestandardowego wykonawcy żądań, -to jest to inna klasa rozszerzenia. Te hooki służą do zachowania dostawcy, które nadal działa -na normalnej pętli wnioskowania OpenClaw. +Jeśli dostawca potrzebuje w pełni niestandardowego protokołu przewodowego lub własnego wykonawcy żądań, +jest to inna klasa rozszerzenia. Te hooki służą do zachowań dostawcy, które nadal działają +w zwykłej pętli wnioskowania OpenClaw. ### Przykład dostawcy @@ -795,115 +807,109 @@ api.registerProvider({ - Anthropic używa `resolveDynamicModel`, `capabilities`, `buildAuthDoctorHint`, `resolveUsageAuth`, `fetchUsageSnapshot`, `isCacheTtlEligible`, `resolveDefaultThinkingLevel`, `applyConfigDefaults`, `isModernModelRef` - oraz `wrapStreamFn`, ponieważ odpowiada za zgodność w przód Claude 4.6, - wskazówki dotyczące rodziny dostawcy, wskazówki naprawy uwierzytelniania, integrację - endpointu użycia, kwalifikowalność cache promptów, wartości domyślne konfiguracji zależne od uwierzytelniania, domyślną/adaptacyjną - politykę myślenia Claude oraz kształtowanie strumienia specyficzne dla Anthropic dla + i `wrapStreamFn`, ponieważ odpowiada za zgodność forward-compat Claude 4.6, + wskazówki dotyczące rodziny dostawców, wskazówki naprawy auth, integrację + endpointu użycia, kwalifikowalność prompt-cache, domyślne wartości konfiguracji zależne od auth, domyślną/adaptacyjną + politykę rozumowania Claude oraz kształtowanie streamu specyficzne dla Anthropic dla nagłówków beta, `/fast` / `serviceTier` i `context1m`. -- Pomocniki strumienia specyficzne dla Claude w Anthropic pozostają na razie we - własnej publicznej powierzchni `api.ts` / `contract-api.ts` bundlowanego Pluginu. Ta powierzchnia pakietu +- Helpery streamu Anthropic specyficzne dla Claude pozostają na razie we własnej + publicznej powierzchni `api.ts` / `contract-api.ts` bundled pluginu. Ta powierzchnia pakietu eksportuje `wrapAnthropicProviderStream`, `resolveAnthropicBetas`, - `resolveAnthropicFastMode`, `resolveAnthropicServiceTier` oraz bardziej niskopoziomowe - konstruktory wrapperów Anthropic zamiast rozszerzać ogólne SDK wokół reguł nagłówków beta jednego - dostawcy. + `resolveAnthropicFastMode`, `resolveAnthropicServiceTier` oraz niższopoziomowe + konstruktory wrapperów Anthropic zamiast rozszerzać ogólne SDK o reguły nagłówków beta + jednego dostawcy. - OpenAI używa `resolveDynamicModel`, `normalizeResolvedModel` i - `capabilities` oraz `buildMissingAuthMessage`, `suppressBuiltInModel`, + `capabilities`, a także `buildMissingAuthMessage`, `suppressBuiltInModel`, `augmentModelCatalog`, `supportsXHighThinking` i `isModernModelRef`, - ponieważ odpowiada za zgodność w przód GPT-5.4, bezpośrednią normalizację OpenAI - `openai-completions` -> `openai-responses`, wskazówki uwierzytelniania świadome Codex, - tłumienie Spark, syntetyczne wiersze listy OpenAI oraz politykę myślenia GPT-5 / - modeli live; rodzina strumienia `openai-responses-defaults` odpowiada za - współdzielone natywne wrappery OpenAI Responses dla nagłówków atrybucji, - `/fast`/`serviceTier`, szczegółowości tekstu, natywnego web search Codex, - kształtowania ładunku zgodności rozumowania oraz zarządzania kontekstem Responses. -- OpenRouter używa `catalog` oraz `resolveDynamicModel` i - `prepareDynamicModel`, ponieważ dostawca jest pass-through i może udostępniać nowe - identyfikatory modeli, zanim statyczny katalog OpenClaw zostanie zaktualizowany; używa też - `capabilities`, `wrapStreamFn` i `isCacheTtlEligible`, aby zachować + ponieważ odpowiada za zgodność forward-compat GPT-5.4, bezpośrednią normalizację OpenAI + `openai-completions` -> `openai-responses`, wskazówki auth świadome Codex, + tłumienie Spark, syntetyczne wiersze listy OpenAI oraz politykę rozumowania / modeli live GPT-5; rodzina streamów + `openai-responses-defaults` odpowiada za 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`, a także `resolveDynamicModel` i + `prepareDynamicModel`, ponieważ dostawca działa jako pass-through i może udostępniać nowe + identyfikatory modeli przed aktualizacją statycznego katalogu OpenClaw; używa także + `capabilities`, `wrapStreamFn` i `isCacheTtlEligible`, aby utrzymać nagłówki żądań specyficzne dla dostawcy, metadane routingu, poprawki rozumowania i - politykę cache promptów poza core. Jego polityka replay pochodzi z rodziny - `passthrough-gemini`, natomiast rodzina strumienia `openrouter-thinking` - odpowiada za wstrzykiwanie rozumowania proxy i pomijanie nieobsługiwanych modeli / `auto`. + politykę prompt-cache poza core. Jego polityka replay pochodzi z rodziny + `passthrough-gemini`, podczas gdy rodzina streamów `openrouter-thinking` + odpowiada za wstrzykiwanie rozumowania proxy oraz pomijanie nieobsługiwanych modeli / `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, - niestandardowych zachowań transkryptu Claude, wymiany tokenu GitHub -> token Copilot oraz - endpointu użycia należącego do dostawcy. + `capabilities`, a także `prepareRuntimeAuth` i `fetchUsageSnapshot`, ponieważ + potrzebuje logowania urządzenia należącego do dostawcy, zachowania fallback modeli, niuansów + transkryptu Claude, wymiany tokenu GitHub -> token Copilot oraz endpointu użycia należącego do dostawcy. - OpenAI Codex używa `catalog`, `resolveDynamicModel`, - `normalizeResolvedModel`, `refreshOAuth` i `augmentModelCatalog` oraz - `prepareExtraParams`, `resolveUsageAuth` i `fetchUsageSnapshot`, ponieważ nadal - działa na transportach OpenAI core, ale odpowiada za własną normalizację - transportu/`baseUrl`, politykę fallback odświeżania OAuth, domyślny wybór transportu, + `normalizeResolvedModel`, `refreshOAuth` i `augmentModelCatalog`, a także + `prepareExtraParams`, `resolveUsageAuth` i `fetchUsageSnapshot`, ponieważ + nadal działa na transportach core OpenAI, ale odpowiada za własną normalizację + transportu/base URL, politykę fallback odświeżania OAuth, domyślny wybór transportu, syntetyczne wiersze katalogu Codex oraz integrację endpointu użycia ChatGPT; współdzieli - tę samą rodzinę strumienia `openai-responses-defaults`, co bezpośrednie OpenAI. + tę samą rodzinę streamów `openai-responses-defaults` co bezpośrednie OpenAI. - Google AI Studio i Gemini CLI OAuth używają `resolveDynamicModel`, `buildReplayPolicy`, `sanitizeReplayHistory`, `resolveReasoningOutputMode`, `wrapStreamFn` i `isModernModelRef`, ponieważ - rodzina replay `google-gemini` odpowiada za fallback zgodności w przód Gemini 3.1, - natywną walidację replay Gemini, sanitację bootstrap replay, tagowany - tryb wyjścia rozumowania i dopasowywanie nowoczesnych modeli, podczas gdy - rodzina strumienia `google-thinking` odpowiada za normalizację ładunku myślenia Gemini; - Gemini CLI OAuth używa też `formatApiKey`, `resolveUsageAuth` i - `fetchUsageSnapshot` do formatowania tokenu, parsowania tokenu i podłączenia - endpointu limitu. + rodzina replay `google-gemini` odpowiada za fallback zgodności forward-compat Gemini 3.1, + natywną walidację replay Gemini, sanityzację bootstrap replay, tryb wyjścia rozumowania z tagami + oraz dopasowywanie nowoczesnych modeli, podczas gdy rodzina streamów + `google-thinking` odpowiada za normalizację ładunku rozumowania Gemini; + Gemini CLI OAuth używa również `formatApiKey`, `resolveUsageAuth` i + `fetchUsageSnapshot` do formatowania tokenu, parsowania tokenu i połączenia + endpointu limitów. - Anthropic Vertex używa `buildReplayPolicy` przez rodzinę replay - `anthropic-by-model`, dzięki czemu porządkowanie replay specyficzne dla Claude pozostaje - ograniczone do identyfikatorów Claude, a nie każdego transportu `anthropic-messages`. + `anthropic-by-model`, dzięki czemu czyszczenie replay specyficzne dla Claude pozostaje + ograniczone do identyfikatorów Claude, a nie do każdego transportu `anthropic-messages`. - Amazon Bedrock używa `buildReplayPolicy`, `matchesContextOverflowError`, `classifyFailoverReason` i `resolveDefaultThinkingLevel`, ponieważ odpowiada za - klasyfikację błędów throttle/not-ready/context-overflow specyficzną dla Bedrock + klasyfikację błędów throttle/not-ready/context-overflow specyficznych dla Bedrock dla ruchu Anthropic-on-Bedrock; jego polityka replay nadal współdzieli tę samą - ochronę `anthropic-by-model` tylko dla Claude. + ochronę tylko dla Claude `anthropic-by-model`. - OpenRouter, Kilocode, Opencode i Opencode Go używają `buildReplayPolicy` - przez rodzinę replay `passthrough-gemini`, ponieważ pośredniczą dla modeli Gemini - przez transporty zgodne z OpenAI i potrzebują sanitacji - thought-signature Gemini bez natywnej walidacji replay Gemini ani - przepisów bootstrap. + przez rodzinę replay `passthrough-gemini`, ponieważ przekazują modele Gemini + przez transporty zgodne z OpenAI i potrzebują sanityzacji sygnatur myśli Gemini + bez natywnej walidacji replay Gemini ani przekształceń bootstrap. - MiniMax używa `buildReplayPolicy` przez rodzinę replay `hybrid-anthropic-openai`, ponieważ jeden dostawca odpowiada zarówno za semantykę - wiadomości Anthropic, jak i zgodność z OpenAI; zachowuje odrzucanie bloków myślenia - tylko dla Claude po stronie Anthropic, jednocześnie nadpisując tryb wyjścia rozumowania z powrotem na natywny, - a rodzina strumienia `minimax-fast-mode` odpowiada za przepisywanie modeli w trybie fast - na współdzielonej ścieżce strumienia. + wiadomości Anthropic, jak i zgodność z OpenAI; zachowuje usuwanie bloków rozumowania tylko dla Claude + po stronie Anthropic, jednocześnie nadpisując tryb wyjścia rozumowania z powrotem na natywny, a rodzina streamów + `minimax-fast-mode` odpowiada za przepisania modeli trybu fast na współdzielonej ścieżce streamu. - Moonshot używa `catalog` oraz `wrapStreamFn`, ponieważ nadal korzysta ze współdzielonego - transportu OpenAI, ale potrzebuje normalizacji ładunku myślenia należącej do dostawcy; rodzina strumienia - `moonshot-thinking` mapuje konfigurację oraz stan `/think` na swój - natywny binarny ładunek myślenia. + transportu OpenAI, ale potrzebuje normalizacji ładunku rozumowania należącej do dostawcy; rodzina streamów + `moonshot-thinking` mapuje konfigurację oraz stan `/think` na swój natywny binarny ładunek rozumowania. - Kilocode używa `catalog`, `capabilities`, `wrapStreamFn` i `isCacheTtlEligible`, ponieważ potrzebuje nagłówków żądań należących do dostawcy, - normalizacji ładunku rozumowania, wskazówek transkryptu Gemini i bramkowania - TTL cache Anthropic; rodzina strumienia `kilocode-thinking` utrzymuje wstrzykiwanie myślenia Kilo - na współdzielonej ścieżce strumienia proxy, jednocześnie pomijając `kilo/auto` i + normalizacji ładunku rozumowania, wskazówek transkryptu Gemini oraz + bramkowania cache-TTL Anthropic; rodzina streamów `kilocode-thinking` utrzymuje wstrzykiwanie rozumowania Kilo + na współdzielonej ścieżce streamu proxy, jednocześnie pomijając `kilo/auto` i inne identyfikatory modeli proxy, które nie obsługują jawnych ładunków rozumowania. - Z.AI używa `resolveDynamicModel`, `prepareExtraParams`, `wrapStreamFn`, `isCacheTtlEligible`, `isBinaryThinking`, `isModernModelRef`, `resolveUsageAuth` i `fetchUsageSnapshot`, ponieważ odpowiada za fallback GLM-5, - domyślne `tool_stream`, UX binarnego myślenia, dopasowywanie nowoczesnych modeli oraz oba - elementy: uwierzytelnianie użycia + pobieranie limitu; rodzina strumienia `tool-stream-default-on` - utrzymuje wrapper `tool_stream` domyślnie włączony poza ręcznie pisanym klejem per dostawca. + domyślne wartości `tool_stream`, UX binary thinking, dopasowywanie nowoczesnych modeli oraz zarówno + auth użycia, jak i pobieranie limitów; rodzina streamów `tool-stream-default-on` utrzymuje + wrapper `tool_stream` domyślnie włączony poza ręcznie pisanym kodem specyficznym dla dostawcy. - xAI używa `normalizeResolvedModel`, `normalizeTransport`, `contributeResolvedModelCompat`, `prepareExtraParams`, `wrapStreamFn`, `resolveSyntheticAuth`, `resolveDynamicModel` i `isModernModelRef`, - ponieważ odpowiada za normalizację natywnego transportu xAI Responses, przepisywanie - aliasów Grok w trybie fast, domyślne `tool_stream`, porządkowanie strict-tool / - ładunku rozumowania, ponowne użycie fallback uwierzytelniania dla narzędzi należących do Pluginu, - rozwiązywanie modeli Grok zgodne w przód oraz poprawki zgodności należące do dostawcy, takie jak profil - schematu narzędzi xAI, nieobsługiwane słowa kluczowe schematu, natywne `web_search` oraz dekodowanie - argumentów wywołań narzędzi z encji HTML. -- Mistral, OpenCode Zen i OpenCode Go używają wyłącznie `capabilities`, aby utrzymać - niestandardowe zachowania transkryptu/narzędzi poza core. -- Bundlowani dostawcy tylko katalogowi, tacy jak `byteplus`, `cloudflare-ai-gateway`, + ponieważ odpowiada za normalizację natywnego transportu xAI Responses, przepisania + aliasów trybu fast Grok, domyślne `tool_stream`, czyszczenie strict-tool / ładunku rozumowania, + ponowne użycie auth fallback dla narzędzi należących do pluginu, rozstrzyganie modeli Grok zgodne z forward-compat + 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 utrzymać + niuanse transkryptu/narzędzi poza core. +- Bundled dostawcy tylko katalogowi, tacy jak `byteplus`, `cloudflare-ai-gateway`, `huggingface`, `kimi-coding`, `nvidia`, `qianfan`, `synthetic`, `together`, `venice`, `vercel-ai-gateway` i `volcengine`, używają - wyłącznie `catalog`. -- Qwen używa `catalog` dla swojego dostawcy tekstu oraz współdzielonych rejestracji rozumienia mediów i generowania wideo - dla swoich powierzchni multimodalnych. + tylko `catalog`. +- Qwen używa `catalog` dla swojego dostawcy tekstowego oraz współdzielonych rejestracji rozumienia mediów i + generowania wideo dla swoich powierzchni multimodalnych. - 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 wnioskowanie nadal działa przez współdzielone transporty. -## Pomocniki runtime +## Narzędzia pomocnicze środowiska uruchomieniowego -Pluginy mogą uzyskiwać dostęp do wybranych pomocników core 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({ @@ -924,11 +930,11 @@ const voices = await api.runtime.tts.listVoices({ Uwagi: -- `textToSpeech` zwraca normalny ładunek wyjściowy TTS core dla powierzchni plików/notatek głosowych. +- `textToSpeech` zwraca zwykły ładunek wyjściowy TTS z 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ą ponownie próbkować/kodować dla dostawców. -- `listVoices` jest opcjonalne dla każdego dostawcy. Używaj go dla selektorów głosów należących do dostawcy lub przepływów konfiguracji. -- Listy głosów mogą zawierać bogatsze metadane, takie jak lokalizacja, płeć i tagi osobowości dla selektorów świadomych dostawcy. +- Zwraca bufor dźwięku PCM + częstotliwość próbkowania. Pluginy muszą przeprowadzić resampling/kodowanie dla dostawców. +- `listVoices` jest opcjonalne dla każdego dostawcy. Używaj go 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, płeć i tagi osobowości dla selektorów świadomych dostawcy. - OpenAI i ElevenLabs obsługują dziś telefonię. Microsoft nie. Pluginy mogą także rejestrować dostawców mowy przez `api.registerSpeechProvider(...)`. @@ -951,14 +957,14 @@ api.registerSpeechProvider({ Uwagi: -- Politykę TTS, fallback i dostarczanie odpowiedzi należy utrzymywać w core. -- Dostawców mowy należy używać dla zachowania syntezy należącego do dostawcy. +- Zachowaj politykę TTS, fallback i dostarczanie odpowiedzi w core. +- Używaj dostawców mowy dla zachowania syntezy należącego 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 zarządzać - tekstem, mową, obrazem i przyszłymi dostawcami mediów, gdy OpenClaw dodaje te +- Preferowany model własności jest zorientowany na firmę: jeden plugin dostawcy może obsługiwać + tekst, mowę, obrazy i przyszłych dostawców mediów, gdy OpenClaw dodaje te kontrakty możliwości. -W przypadku rozumienia obrazów/audio/wideo Pluginy rejestrują jednego typowanego +W przypadku rozumienia obrazów/audio/wideo pluginy rejestrują jednego typowanego dostawcę rozumienia mediów zamiast ogólnego worka klucz/wartość: ```ts @@ -973,16 +979,16 @@ api.registerMediaUnderstandingProvider({ Uwagi: -- Orkiestrację, fallback, konfigurację i połączenie z kanałami należy utrzymywać w core. -- Zachowanie dostawcy należy utrzymywać w Pluginie dostawcy. +- Zachowaj orkiestrację, fallback, konfigurację i podłączenie kanałów w core. +- Zachowaj zachowanie dostawcy w pluginie dostawcy. - Rozszerzanie addytywne powinno pozostać typowane: nowe opcjonalne metody, nowe opcjonalne pola wyników, nowe opcjonalne możliwości. - Generowanie wideo już stosuje ten sam wzorzec: - - core odpowiada za kontrakt możliwości i pomocnik runtime - - Pluginy dostawców rejestrują `api.registerVideoGenerationProvider(...)` - - Pluginy funkcji/kanałów korzystają z `api.runtime.videoGeneration.*` + - core jest właścicielem kontraktu możliwości i helpera runtime + - pluginy dostawców rejestrują `api.registerVideoGenerationProvider(...)` + - pluginy funkcjonalne/kanałowe wykorzystują `api.runtime.videoGeneration.*` -W przypadku pomocników runtime rozumienia mediów Pluginy mogą wywoływać: +W przypadku helperów runtime rozumienia mediów pluginy mogą wywoływać: ```ts const image = await api.runtime.mediaUnderstanding.describeImageFile({ @@ -997,8 +1003,8 @@ const video = await api.runtime.mediaUnderstanding.describeVideoFile({ }); ``` -W przypadku transkrypcji audio Pluginy mogą używać albo runtime -rozumienia mediów, albo starszego aliasu STT: +W przypadku transkrypcji audio pluginy mogą używać albo runtime rozumienia mediów, +albo starszego aliasu STT: ```ts const { text } = await api.runtime.mediaUnderstanding.transcribeAudioFile({ @@ -1013,11 +1019,11 @@ Uwagi: - `api.runtime.mediaUnderstanding.*` to preferowana współdzielona powierzchnia dla rozumienia obrazów/audio/wideo. -- Używa konfiguracji audio rozumienia mediów core (`tools.media.audio`) oraz kolejności fallbacków dostawców. -- Zwraca `{ text: undefined }`, gdy nie powstanie wynik transkrypcji (na przykład dla pominiętego/nieobsługiwanego wejścia). +- Używa konfiguracji audio rozumienia mediów z core (`tools.media.audio`) oraz kolejności fallback dostawców. +- Zwraca `{ text: undefined }`, gdy nie powstanie wynik transkrypcji (na przykład w przypadku pominiętego/nieobsługiwanego wejścia). - `api.runtime.stt.transcribeAudioFile(...)` pozostaje aliasem zgodności. -Pluginy mogą także uruchamiać subagentów działających w tle przez `api.runtime.subagent`: +Pluginy mogą również uruchamiać podrzędne przebiegi subagenta w tle przez `api.runtime.subagent`: ```ts const result = await api.runtime.subagent.run({ @@ -1031,14 +1037,14 @@ const result = await api.runtime.subagent.run({ Uwagi: -- `provider` i `model` to opcjonalne nadpisania dla danego uruchomienia, a nie trwałe zmiany sesji. -- OpenClaw uwzględnia te pola nadpisania tylko dla zaufanych wywołujących. -- W przypadku uruchomień 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. -- Uruchomienia subagentów z niezaufanych Pluginów nadal działają, ale żądania nadpisania są odrzucane zamiast po cichu przechodzić do fallbacku. +- `provider` i `model` to opcjonalne nadpisania dla pojedynczego przebiegu, 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`, lub `"*"` aby jawnie dopuścić dowolny cel. +- Niezaufane przebiegi subagenta pluginów nadal działają, ale żądania nadpisania są odrzucane zamiast po cichu przechodzić do fallback. -W przypadku web search Pluginy mogą korzystać ze współdzielonego pomocnika runtime zamiast -sięgać do połączenia narzędzia agenta: +W przypadku wyszukiwania w sieci pluginy mogą korzystać ze współdzielonego helpera runtime zamiast +sięgać do podłączenia narzędzia agenta: ```ts const providers = api.runtime.webSearch.listProviders({ @@ -1054,14 +1060,14 @@ const result = await api.runtime.webSearch.search({ }); ``` -Pluginy mogą też rejestrować dostawców web search przez +Pluginy mogą także rejestrować dostawców wyszukiwania w sieci przez `api.registerWebSearchProvider(...)`. Uwagi: -- Wybór dostawcy, rozwiązywanie poświadczeń i współdzieloną semantykę żądań należy utrzymywać w core. -- Dostawców web search należy używać 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. +- Zachowaj wybór dostawcy, rozstrzyganie poświadczeń i współdzieloną semantykę żądań w core. +- Używaj dostawców wyszukiwania w sieci dla transportów wyszukiwania specyficznych dla dostawcy. +- `api.runtime.webSearch.*` to preferowana współdzielona powierzchnia dla pluginów funkcjonalnych/kanałowych, które potrzebują zachowania wyszukiwania bez zależności od wrappera narzędzia agenta. ### `api.runtime.imageGeneration` @@ -1081,7 +1087,7 @@ const providers = api.runtime.imageGeneration.listProviders({ ## Trasy HTTP Gateway -Pluginy mogą udostępniać endpointy HTTP przez `api.registerHttpRoute(...)`. +Pluginy mogą udostępniać endpointy HTTP za pomocą `api.registerHttpRoute(...)`. ```ts api.registerHttpRoute({ @@ -1098,31 +1104,31 @@ api.registerHttpRoute({ Pola trasy: -- `path`: ścieżka trasy pod serwerem HTTP Gateway. -- `auth`: wymagane. Użyj `"gateway"`, aby wymagać zwykłego uwierzytelniania Gateway, albo `"plugin"` dla uwierzytelniania zarządzanego przez Plugin / weryfikacji Webhooków. -- `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. +- `path`: ścieżka trasy pod serwerem HTTP gateway. +- `auth`: wymagane. Użyj `"gateway"`, aby wymagać zwykłego auth gateway, lub `"plugin"` dla auth zarządzanego przez plugin / weryfikacji Webhook. +- `match`: opcjonalne. `"exact"` (domyślnie) lub `"prefix"`. +- `replaceExisting`: opcjonalne. Pozwala temu samemu pluginowi zastąpić własną istniejącą rejestrację trasy. +- `handler`: zwróć `true`, gdy trasa obsłużyła żądanie. Uwagi: -- `api.registerHttpHandler(...)` zostało usunięte i spowoduje błąd ładowania Pluginu. Zamiast tego używaj `api.registerHttpRoute(...)`. -- Trasy Pluginów muszą jawnie deklarować `auth`. -- 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. Łańcuchy przejścia `exact`/`prefix` należy utrzymywać tylko na tym samym poziomie uwierzytelniania. -- Trasy `auth: "plugin"` **nie** otrzymują automatycznie zakresów runtime operatora. Są przeznaczone do Webhooków / weryfikacji podpisów zarządzanych przez Plugin, a nie do uprzywilejowanych wywołań pomocników Gateway. +- `api.registerHttpHandler(...)` zostało usunięte i spowoduje błąd ładowania pluginu. Zamiast tego użyj `api.registerHttpRoute(...)`. +- Trasy pluginów muszą jawnie deklarować `auth`. +- Konflikty dokładnych `path + match` są odrzucane, chyba że ustawiono `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ścia `exact`/`prefix` utrzymuj 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 konserwatywny: - - uwierzytelnianie bearer oparte 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 przenoszące tożsamość (na przykład `trusted-proxy` albo `gateway.auth.mode = "none"` na prywatnym wejściu) honorują `x-openclaw-scopes` tylko wtedy, gdy nagłówek jest jawnie obecny - - jeśli `x-openclaw-scopes` jest nieobecny w takich żądaniach tras Pluginów przenoszących tożsamość, zakres runtime wraca do `operator.write` -- Praktyczna zasada: nie zakładaj, że trasa Pluginu z uwierzytelnianiem Gateway jest domyślnie powierzchnią administratora. Jeśli Twoja trasa potrzebuje zachowania dostępnego wyłącznie dla administratora, wymagaj trybu uwierzytelniania przenoszącego tożsamość i udokumentuj jawny kontrakt nagłówka `x-openclaw-scopes`. + - auth bearer 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 przekazujące tożsamość (na przykład `trusted-proxy` lub `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 tras pluginów z przekazywaną tożsamością, zakres runtime wraca do `operator.write` +- Praktyczna zasada: nie zakładaj, że trasa pluginu z auth gateway jest niejawnie powierzchnią administracyjną. Jeśli twoja trasa potrzebuje zachowania tylko dla administratora, wymagaj trybu auth przekazującego tożsamość i udokumentuj jawny kontrakt nagłówka `x-openclaw-scopes`. ## Ścieżki importu Plugin SDK -Tworząc Pluginy, używaj podścieżek SDK zamiast monolitycznego importu `openclaw/plugin-sdk`: +Podczas tworzenia pluginów używaj podś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/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 głównego schematu Zod `openclaw.json` (`OpenClawSchema`). - Stabilne prymitywy kanałów, takie jak `openclaw/plugin-sdk/channel-setup`, @@ -1136,16 +1142,16 @@ Tworząc Pluginy, używaj podścieżek SDK zamiast monolitycznego importu `openc `openclaw/plugin-sdk/channel-lifecycle`, `openclaw/plugin-sdk/channel-reply-pipeline`, `openclaw/plugin-sdk/command-auth`, - `openclaw/plugin-sdk/secret-input` oraz - `openclaw/plugin-sdk/webhook-ingress` dla współdzielonego połączenia - konfiguracji/uwierzytelniania/odpowiedzi/Webhooków. `channel-inbound` to współdzielone miejsce dla debounce, dopasowywania wzmianek, - pomocników polityki wzmianek przychodzących, formatowania kopert oraz pomocników kontekstu + `openclaw/plugin-sdk/secret-input` i + `openclaw/plugin-sdk/webhook-ingress` dla współdzielonego podłączenia + konfiguracji/auth/odpowiedzi/Webhook. `channel-inbound` jest wspólnym miejscem dla debounce, dopasowywania wzmianek, + helperów polityki wzmianek przychodzących, formatowania kopert przychodzących oraz helperów kontekstu kopert przychodzących. - `channel-setup` to wąska powierzchnia konfiguracji opcjonalnej instalacji. + `channel-setup` to wąska ścieżka konfiguracji opcjonalnej instalacji. `setup-runtime` to bezpieczna dla runtime powierzchnia konfiguracji używana przez `setupEntry` / odroczone uruchamianie, w tym bezpieczne importowo adaptery łatek konfiguracji. - `setup-adapter-runtime` to świadoma środowiska powierzchnia adaptera konfiguracji konta. - `setup-tools` to mała powierzchnia pomocników CLI/archiwów/dokumentacji (`formatCliCommand`, + `setup-adapter-runtime` to świadoma env ścieżka adaptera konfiguracji konta. + `setup-tools` to mała ścieżka 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`, @@ -1165,137 +1171,133 @@ Tworząc Pluginy, używaj podścieżek SDK zamiast monolitycznego importu `openc `openclaw/plugin-sdk/routing`, `openclaw/plugin-sdk/status-helpers`, `openclaw/plugin-sdk/text-runtime`, - `openclaw/plugin-sdk/runtime-store` oraz - `openclaw/plugin-sdk/directory-runtime` dla współdzielonych pomocników runtime/konfiguracji. - `telegram-command-config` to wąska publiczna powierzchnia dla normalizacji/walidacji niestandardowych - poleceń Telegram i pozostaje dostępna nawet wtedy, gdy bundlowana + `openclaw/plugin-sdk/runtime-store` i + `openclaw/plugin-sdk/directory-runtime` dla współdzielonych helperów runtime/konfiguracji. + `telegram-command-config` to wąska publiczna ścieżka dla normalizacji/walidacji niestandardowych poleceń Telegram i pozostaje dostępna nawet wtedy, gdy bundled powierzchnia kontraktu Telegram jest tymczasowo niedostępna. - `text-runtime` to współdzielona powierzchnia tekst/Markdown/logowanie, w tym - usuwanie tekstu widocznego dla asystenta, pomocniki renderowania/dzielenia Markdown, pomocniki redakcji, - pomocniki tagów dyrektyw i narzędzia bezpiecznego tekstu. -- Powierzchnie kanałów specyficzne dla zatwierdzeń powinny preferować jeden kontrakt `approvalCapability` - na Pluginie. Core odczytuje następnie uwierzytelnianie zatwierdzeń, dostarczanie, renderowanie, - natywny routing i leniwe zachowanie natywnego handlera przez tę jedną możliwość - zamiast mieszać zachowanie zatwierdzeń z niepowiązanymi polami Pluginu. -- `openclaw/plugin-sdk/channel-runtime` jest przestarzałe i pozostaje wyłącznie 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ętrze bundlowanych rozszerzeń pozostaje prywatne. Zewnętrzne Pluginy powinny używać wyłącznie podścieżek `openclaw/plugin-sdk/*`. - Kod core/testów OpenClaw może używać publicznych punktów wejścia repo - w katalogu głównym pakietu Pluginu, takich jak `index.js`, `api.js`, - `runtime-api.js`, `setup-entry.js` oraz wąsko ograniczonych plików, takich jak - `login-qr-api.js`. Nigdy nie importuj `src/*` pakietu Pluginu z core ani z + `text-runtime` to współdzielona ścieżka tekstu/Markdown/logowania, obejmująca + usuwanie tekstu widocznego dla asystenta, helpery renderowania/dzielenia Markdown, helpery redakcji, + helpery tagów dyrektyw oraz bezpieczne narzędzia tekstowe. +- Powierzchnie kanałów specyficzne dla zatwierdzeń powinny preferować jeden kontrakt + `approvalCapability` w pluginie. Core 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/channel-runtime` jest przestarzałe i pozostaje jedynie + jako shima zgodności dla starszych pluginów. Nowy kod powinien importować węższe + prymitywy ogólne, a kod repo nie powinien dodawać nowych importów tej shimy. +- Wewnętrzne elementy bundled extensions pozostają prywatne. Zewnętrzne pluginy powinny używać tylko podścieżek `openclaw/plugin-sdk/*`. Kod core/testów OpenClaw może 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 ukierunkowane pliki, takie 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, + `/api.js` to barrel helperó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 konfiguracji. -- Obecne przykłady bundlowanych dostawców: - - Anthropic używa `api.js` / `contract-api.js` dla pomocników strumienia Claude, takich - jak `wrapAnthropicProviderStream`, pomocniki nagłówków beta i parsowanie - `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 onboardingu/konfiguracji, + `/index.js` to punkt wejścia bundled pluginu, + a `/setup-entry.js` to punkt wejścia pluginu konfiguracji. +- Aktualne przykłady bundled dostawców: + - Anthropic używa `api.js` / `contract-api.js` dla helperów streamu Claude, takich + jak `wrapAnthropicProviderStream`, helpery nagłówków beta i parsowanie `service_tier`. + - OpenAI używa `api.js` dla konstruktorów dostawców, helperów modeli domyślnych i + konstruktorów dostawców realtime. + - OpenRouter używa `api.js` dla swojego konstruktora dostawcy oraz helperów onboardingu/konfiguracji, podczas gdy `register.runtime.js` może nadal ponownie eksportować ogólne - pomocniki `plugin-sdk/provider-stream` do użytku lokalnego w repo. + 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 rozwiązanej konfiguracji z pliku 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 powierzchni bundlowanych kanałów opatrzonych marką. Traktuj je jako - powierzchnie utrzymaniowe/zgodnościowe dla bundli, a nie nowe cele importu dla zewnętrznych Pluginów; nowe - kontrakty międzykanałowe nadal powinny trafiać do ogólnych podścieżek `plugin-sdk/*` albo lokalnych barrelów Pluginu `api.js` / + zastrzeżony zestaw zgodności helperów oznaczonych marką bundled kanałów. Traktuj je jako + powierzchnie utrzymaniowe/zgodnościowe dla bundled, a nie nowe cele importu dla podmiotów trzecich; nowe kontrakty międzykanałowe powinny nadal trafiać do + ogólnych podścieżek `plugin-sdk/*` albo lokalnych barrelów pluginu `api.js` / `runtime-api.js`. -Uwaga dotycząca 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/ +- Unikaj głównego barrelu `openclaw/plugin-sdk` w nowym kodzie. +- Najpierw preferuj wąskie, stabilne prymitywy. Nowsze podścieżki setup/pairing/reply/ feedback/contract/inbound/threading/command/secret-input/webhook/infra/ - allowlist/status/message-tool stanowią zamierzony kontrakt dla nowych - bundlowanych i zewnętrznych Pluginów. - Parsowanie/dopasowywanie celu należy umieszczać w `openclaw/plugin-sdk/channel-targets`. - Bramki działań wiadomości i pomocniki identyfikatorów wiadomości reakcji należą do + allowlist/status/message-tool są zamierzonym kontraktem dla nowych prac nad + bundled i zewnętrznymi pluginami. + Parsowanie/dopasowywanie celó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 pomocników specyficznych dla bundlowanych rozszerzeń nie są domyślnie stabilne. Jeśli - pomocnik jest potrzebny tylko bundlowanemu rozszerzeniu, trzymaj go za lokalną powierzchnią - `api.js` lub `runtime-api.js` tego rozszerzenia zamiast promować go do +- Barrele helperów specyficznych dla bundled extensions nie są domyślnie stabilne. Jeśli + helper jest potrzebny tylko bundled extension, trzymaj go za lokalną + warstwą `api.js` lub `runtime-api.js` tego rozszerzenia zamiast promować go do `openclaw/plugin-sdk/`. -- Nowe współdzielone powierzchnie pomocników powinny być ogólne, a nie oznaczone marką kanału. Współdzielone parsowanie celu - należy umieszczać w `openclaw/plugin-sdk/channel-targets`; wnętrze specyficzne dla kanału - powinno pozostawać za lokalną powierzchnią `api.js` lub `runtime-api.js` należącą do danego Pluginu. +- Nowe współdzielone ścieżki helperów powinny być ogólne, a nie oznaczone marką kanału. Wspólne parsowanie + celów należy do `openclaw/plugin-sdk/channel-targets`; elementy wewnętrzne specyficzne dla kanału + pozostają za lokalną warstwą `api.js` lub `runtime-api.js` należącego pluginu. - Podścieżki specyficzne dla możliwości, takie jak `image-generation`, - `media-understanding` i `speech`, istnieją, ponieważ używają ich dziś - bundlowane/natywne Pluginy. Ich obecność sama w sobie nie oznacza, że każdy eksportowany pomocnik jest + `media-understanding` i `speech`, istnieją, ponieważ bundled/natywne pluginy używają + ich już 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 zarządzać wkładami do schematu `describeMessageTool(...)` -specyficznymi dla kanału. Pola specyficzne dla dostawcy należy trzymać w Pluginie, a nie we współdzielonym core. +Pluginy powinny być właścicielami wkładów do schematu `describeMessageTool(...)` specyficznych dla kanału. +Pola specyficzne dla dostawcy trzymaj w pluginie, a nie we współdzielonym core. -W przypadku współdzielonych przenośnych fragmentów schematu używaj ponownie 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 ładunków w stylu siatki przycisków -- `createMessageToolCardSchema()` dla ładunków uporządkowanych kart +- `createMessageToolCardSchema()` dla strukturalnych ładunków kart -Jeśli dany kształt schematu ma sens tylko dla jednego dostawcy, zdefiniuj go we 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 we +własnym kodzie źródłowym tego pluginu zamiast promować go do współdzielonego SDK. -## Rozwiązywanie celu kanału +## Rozstrzyganie celów kanału -Pluginy kanałów powinny zarządzać semantyką celu specyficzną dla kanału. Współdzielony -host outbound powinien pozostać ogólny, a dla reguł dostawcy należy używać powierzchni adaptera wiadomości: +Pluginy kanałów powinny być właścicielami semantyki celów specyficznych dla kanału. Zachowaj współdzielony +host outbound jako ogólny i używaj powierzchni adaptera wiadomości dla reguł dostawcy: - `messaging.inferTargetChatType({ to })` decyduje, czy znormalizowany cel - powinien być traktowany jako `direct`, `group` czy `channel` przed wyszukiwaniem w katalogu. -- `messaging.targetResolver.looksLikeId(raw, normalized)` informuje core, czy dane - wejście powinno od razu przejść do rozwiązywania podobnego do identyfikatora zamiast do wyszukiwania w katalogu. -- `messaging.targetResolver.resolveTarget(...)` to fallback Pluginu, gdy - core potrzebuje końcowego rozwiązywania należącego do dostawcy po normalizacji albo po + powinien być traktowany jako `direct`, `group` czy `channel` przed wyszukaniem w katalogu. +- `messaging.targetResolver.looksLikeId(raw, normalized)` mówi core, czy dane + wejście powinno pominąć bezpośrednio do rozstrzygania podobnego do identyfikatora zamiast wyszukiwania w katalogu. +- `messaging.targetResolver.resolveTarget(...)` to fallback pluginu, gdy + core potrzebuje końcowego rozstrzygnięcia należącego do dostawcy po normalizacji lub po braku trafienia w katalogu. -- `messaging.resolveOutboundSessionRoute(...)` zarządza budowaniem trasy sesji - specyficznej dla dostawcy po rozwiązaniu celu. +- `messaging.resolveOutboundSessionRoute(...)` odpowiada za konstruowanie trasy sesji + specyficzne dla dostawcy po rozstrzygnięciu celu. Zalecany podział: -- Używaj `inferTargetChatType` dla decyzji kategorialnych, które powinny zapaść przed - przeszukiwaniem peerów/grup. -- Używaj `looksLikeId` dla sprawdzeń typu „traktuj to jako jawny/natywny identyfikator celu”. -- Używaj `resolveTarget` dla fallbacku normalizacji specyficznej dla dostawcy, a nie dla +- Używaj `inferTargetChatType` dla decyzji kategorialnych, które powinny zapadać przed + wyszukiwaniem peerów/grup. +- Używaj `looksLikeId` do sprawdzeń typu „traktuj to jako jawny/natywny identyfikator celu”. +- Używaj `resolveTarget` dla fallbacku normalizacji specyficznego dla dostawcy, a nie dla szerokiego wyszukiwania w katalogu. -- Natywne identyfikatory dostawcy, takie jak identyfikatory czatów, wątków, JID, handle i identyfikatory pokojów, - należy trzymać wewnątrz wartości `target` albo parametrów specyficznych dla dostawcy, a nie w ogólnych polach SDK. +- Natywne identyfikatory dostawcy, takie jak identyfikatory czatów, identyfikatory wątków, JID-y, handle i + identyfikatory pokoi, przechowuj wewnątrz wartości `target` lub parametrów specyficznych dla dostawcy, a nie w ogólnych polach SDK. ## Katalogi oparte na konfiguracji Pluginy, które wyprowadzają wpisy katalogu z konfiguracji, powinny trzymać tę logikę w -Pluginie i ponownie używać współdzielonych pomocników z +pluginie i wykorzystywać współdzielone helpery z `openclaw/plugin-sdk/directory-runtime`. Używaj tego, gdy kanał potrzebuje peerów/grup opartych na konfiguracji, takich jak: -- peery DM sterowane przez allowlistę +- peery DM sterowane allowlistą - skonfigurowane mapy kanałów/grup - statyczne fallbacki katalogów ograniczone do konta -Współdzielone pomocniki w `directory-runtime` obsługują tylko ogólne operacje: +Współdzielone helpery w `directory-runtime` obsługują tylko ogólne operacje: - filtrowanie zapytań - stosowanie limitów -- deduplikację/pomocniki normalizacji +- deduplikację/helpery normalizacji - budowanie `ChannelDirectoryEntry[]` -Inspekcja kont specyficzna dla kanału i normalizacja identyfikatorów powinny pozostać w -implementacji Pluginu. +Inspekcja konta specyficzna dla kanału i normalizacja identyfikatorów powinny 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 wnioskowania za pomocą `registerProvider({ catalog: { run(...) { ... } } })`. `catalog.run(...)` zwraca ten sam kształt, który OpenClaw zapisuje do @@ -1304,59 +1306,60 @@ 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 zarządza identyfikatorami modeli specyficznymi dla dostawcy, wartościami domyślnymi `baseUrl` -lub metadanymi modeli chronionymi uwierzytelnianiem. +Używaj `catalog`, gdy plugin jest właścicielem identyfikatorów modeli specyficznych dla dostawcy, domyślnych +wartości `base URL` lub metadanych modeli zależnych od auth. -`catalog.order` kontroluje, kiedy katalog Pluginu jest scalany względem -wbudowanych domyślnych dostawców OpenClaw: +`catalog.order` kontroluje, kiedy katalog pluginu jest scalany względem +wbudowanych niejawnych dostawców OpenClaw: -- `simple`: zwykli dostawcy sterowani kluczem API lub zmiennymi środowiskowymi -- `profile`: dostawcy pojawiający się, gdy istnieją profile uwierzytelniania +- `simple`: dostawcy używający zwykłego klucza API lub env +- `profile`: dostawcy pojawiający się, gdy istnieją profile auth - `paired`: dostawcy syntetyzujący wiele powiązanych wpisów dostawców -- `late`: ostatnie przejście, po innych domyślnych dostawcach +- `late`: ostatni przebieg, po innych niejawnych dostawcach -Późniejsi dostawcy wygrywają przy kolizji kluczy, więc Pluginy mogą celowo nadpisywać -wbudowany wpis dostawcy o tym samym identyfikatorze dostawcy. +Późniejsi dostawcy wygrywają w przypadku kolizji kluczy, więc pluginy mogą celowo nadpisać +wbudowany wpis dostawcy tym samym identyfikatorem dostawcy. Kompatybilność: - `discovery` nadal działa jako starszy alias -- jeśli zarejestrowane są zarówno `catalog`, jak i `discovery`, OpenClaw używa `catalog` +- jeśli zarejestrowano zarówno `catalog`, jak i `discovery`, OpenClaw używa `catalog` -## Inspekcja kanału tylko do odczytu +## Kanałowa inspekcja tylko do odczytu -Jeśli Twój Plugin rejestruje kanał, preferuj implementację +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. + są w pełni zmaterializowane i może szybko zakoń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` oraz przepływy doctor/naprawy - konfiguracji, nie powinny wymagać materializacji poświadczeń runtime tylko po to, - aby opisać konfigurację. + `openclaw channels status`, `openclaw channels resolve` oraz przepływy + naprawy 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`. -- Dodawaj pola źródła/statusu poświadczeń, gdy są istotne, takie jak: +- Dołączaj pola źródła/statusu poświadczeń, gdy ma to znaczenie, 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"` (oraz odpowiadającego mu pola źródła) wystarcza dla poleceń w stylu statusu. +- Nie musisz zwracać surowych wartości tokenów tylko po to, by raportować dostępność + tylko do odczytu. Zwrócenie `tokenStatus: "available"` (oraz odpowiadającego mu pola źródła) + wystarcza dla poleceń typu status. - Używaj `configured_unavailable`, gdy poświadczenie jest skonfigurowane przez SecretRef, ale niedostępne w bieżącej ścieżce polecenia. -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 raportować konto jako nieskonfigurowane. +Pozwala to poleceniom tylko do odczytu raportować „skonfigurowane, ale niedostępne w tej ścieżce polecenia” +zamiast powodować awarię lub błędnie raportować konto jako nieskonfigurowane. -## Pakiety zbiorcze +## Package packi -Katalog Pluginu może zawierać `package.json` z `openclaw.extensions`: +Katalog pluginu może zawierać `package.json` z `openclaw.extensions`: ```json { @@ -1368,63 +1371,64 @@ Katalog Pluginu może zawierać `package.json` z `openclaw.extensions`: } ``` -Każdy wpis staje się Pluginem. Jeśli pakiet zbiorczy zawiera wiele rozszerzeń, identyfikator Pluginu +Każdy wpis staje się pluginem. Jeśli pack zawiera wiele rozszerzeń, identyfikator pluginu przyjmuje postać `name/`. -Jeśli Twój Plugin importuje zależności npm, zainstaluj je w tym katalogu, aby +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`). -Barierka bezpieczeństwa: każdy wpis `openclaw.extensions` musi pozostać wewnątrz katalogu Pluginu -po rozwiązaniu symlinków. Wpisy wychodzące poza katalog pakietu są +Barierka 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 Pluginów przez -`npm install --omit=dev --ignore-scripts` (bez skryptów cyklu życia i bez zależności deweloperskich w runtime). Drzewa zależności Pluginów powinny pozostać „czystym JS/TS” i unikać pakietów wymagających kompilacji `postinstall`. +Uwaga dotycząca bezpieczeństwa: `openclaw plugins install` instaluje zależności pluginów za pomocą +`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 kompilacji przez `postinstall`. -Opcjonalnie: `openclaw.setupEntry` może wskazywać na lekki moduł tylko do konfiguracji. -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 punktu wejścia Pluginu. Dzięki temu uruchamianie i konfiguracja są lżejsze, -gdy główny punkt wejścia Pluginu podłącza też narzędzia, hooki lub inny kod tylko runtime. +Opcjonalnie: `openclaw.setupEntry` może wskazywać lekki moduł tylko do konfiguracji. +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 punktu wejścia pluginu. Dzięki temu uruchamianie i konfiguracja są lżejsze, +gdy główny punkt wejścia pluginu podłącza również narzędzia, hooki lub inny kod tylko runtime. Opcjonalnie: `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` -może włączyć dla Pluginu kanału tę samą ścieżkę `setupEntry` podczas fazy -uruchamiania Gateway przed nasłuchiwaniem, nawet gdy kanał jest już skonfigurowany. +może włączyć plugin kanału do tej samej ścieżki `setupEntry` w fazie +uruchamiania gateway przed `listen`, nawet gdy kanał jest już skonfigurowany. -Używaj tego tylko wtedy, gdy `setupEntry` w pełni pokrywa powierzchnię uruchomieniową, która musi istnieć -przed rozpoczęciem nasłuchiwania przez Gateway. W praktyce oznacza to, że punkt wejścia konfiguracji +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 punkt wejścia konfiguracji musi rejestrować każdą możliwość należącą do kanału, od której zależy uruchamianie, taką jak: - sama rejestracja kanału -- wszelkie trasy HTTP, które muszą być dostępne przed rozpoczęciem nasłuchiwania przez Gateway +- wszelkie trasy HTTP, które muszą być dostępne zanim gateway zacznie nasłuchiwać - wszelkie metody Gateway, narzędzia lub usługi, które muszą istnieć w tym samym oknie czasowym -Jeśli Twój pełny punkt wejścia nadal odpowiada za jakąkolwiek wymaganą możliwość uruchomieniową, nie włączaj -tej flagi. Pozostaw Plugin przy domyślnym zachowaniu i pozwól OpenClaw ładować +Jeśli twój pełny punkt wejścia nadal jest właścicielem jakiejkolwiek wymaganej możliwości uruchamiania, nie włączaj +tej flagi. Pozostaw plugin przy domyślnym zachowaniu i pozwól OpenClaw ładować pełny punkt wejścia podczas uruchamiania. -Bundlowane kanały mogą też publikować pomocniki powierzchni kontraktowej tylko do konfiguracji, z których core -może korzystać przed załadowaniem pełnego runtime kanału. Obecna powierzchnia promocji konfiguracji to: +Bundled kanały mogą także publikować helpery powierzchni kontraktowej tylko do konfiguracji, z których core +może korzystać przed załadowaniem pełnego runtime kanału. Obecna powierzchnia +promocji konfiguracji to: - `singleAccountKeysToMove` - `namedAccountPromotionKeys` - `resolveSingleAccountPromotionTarget(...)` -Core używa tej powierzchni, gdy musi promować starszą konfigurację kanału z jednym kontem -do `channels..accounts.*` bez ładowania pełnego punktu wejścia Pluginu. -Matrix jest obecnym bundlowanym przykładem: przenosi tylko klucze auth/bootstrap do +Core używa tej powierzchni, gdy musi promować starszą konfigurację kanału z pojedynczym kontem +do `channels..accounts.*` bez ładowania pełnego punktu wejścia pluginu. +Matrix jest obecnym bundled przykładem: przenosi tylko klucze auth/bootstrap do nazwanego promowanego konta, gdy nazwane konta już istnieją, i może zachować skonfigurowany niekanoniczny klucz konta domyślnego zamiast zawsze tworzyć `accounts.default`. -Te adaptery łatek konfiguracji utrzymują leniwe wykrywanie powierzchni kontraktowej bundli. Czas -importu pozostaje niski; powierzchnia promocji jest ładowana dopiero przy pierwszym użyciu zamiast -ponownego wchodzenia w uruchamianie bundlowanego kanału podczas importu modułu. +Te adaptery łatek konfiguracji utrzymują leniwe wykrywanie powierzchni kontraktowej bundled. Czas +importu pozostaje lekki; powierzchnia promocji jest ładowana tylko przy pierwszym użyciu zamiast +ponownie wchodzić w uruchamianie bundled kanału podczas importu modułu. -Gdy te powierzchnie uruchomieniowe obejmują metody Gateway RPC, utrzymuj je pod -prefiksem specyficznym dla Pluginu. Przestrzenie nazw administracyjnych core (`config.*`, -`exec.approvals.*`, `wizard.*`, `update.*`) pozostają zastrzeżone i zawsze są rozwiązywane -do `operator.admin`, nawet jeśli Plugin żąda węższego zakresu. +Gdy te powierzchnie uruchamiania zawierają metody RPC Gateway, utrzymuj je pod +prefiksem specyficznym dla pluginu. Przestrzenie nazw administratora core (`config.*`, +`exec.approvals.*`, `wizard.*`, `update.*`) pozostają zastrzeżone i zawsze rozstrzygają się +do `operator.admin`, nawet jeśli plugin żąda węższego zakresu. Przykład: @@ -1441,7 +1445,7 @@ Przykład: } ``` -### Metadane katalogu kanału +### Metadane katalogu kanałów Pluginy kanałów mogą reklamować metadane konfiguracji/wykrywania przez `openclaw.channel` oraz wskazówki instalacji przez `openclaw.install`. Dzięki temu dane katalogu core pozostają wolne od danych. @@ -1474,39 +1478,39 @@ Przykład: Przydatne pola `openclaw.channel` poza minimalnym przykładem: -- `detailLabel`: etykieta pomocnicza dla bogatszych powierzchni katalogu/statusu +- `detailLabel`: etykieta dodatkowa dla bogatszych powierzchni katalogu/statusu - `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 powierzchni wyboru -- `markdownCapable`: oznacza kanał jako obsługujący Markdown na potrzeby decyzji o formatowaniu outbound -- `exposure.configured`: ukrywa kanał na powierzchniach list skonfigurowanych kanałów, gdy ustawione na `false` -- `exposure.setup`: ukrywa kanał w interaktywnych selektorach konfiguracji, gdy ustawione na `false` +- `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 obsługujący Markdown dla decyzji o formatowaniu outbound +- `exposure.configured`: ukrywa kanał z powierzchni listowania skonfigurowanych kanałów, gdy ustawiono `false` +- `exposure.setup`: ukrywa kanał z interaktywnych selektorów konfiguracji/ustawiania, gdy ustawiono `false` - `exposure.docs`: oznacza kanał jako wewnętrzny/prywatny dla powierzchni nawigacji dokumentacji - `showConfigured` / `showInSetup`: starsze aliasy nadal akceptowane dla kompatybilności; preferuj `exposure` -- `quickstartAllowFrom`: włącza kanał do standardowego przepływu szybkiego startu `allowFrom` +- `quickstartAllowFrom`: włącza kanał do standardowego przepływu `allowFrom` szybkiego startu - `forceAccountBinding`: wymaga jawnego powiązania konta nawet wtedy, gdy istnieje tylko jedno konto -- `preferSessionLookupForAnnounceTarget`: preferuje wyszukiwanie sesji podczas rozwiązywania celów ogłoszeń +- `preferSessionLookupForAnnounceTarget`: preferuje wyszukiwanie sesji przy rozstrzyganiu celów ogłoszeń -OpenClaw może też scalać **zewnętrzne katalogi kanałów** (na przykład eksport rejestru MPM). -Umieść plik JSON w jednej z lokalizacji: +OpenClaw może także scalać **zewnętrzne katalogi kanałów** (na przykład eksport +rejestru MPM). Umieść plik JSON w jednej z poniższych lokalizacji: - `~/.openclaw/mpm/plugins.json` - `~/.openclaw/mpm/catalog.json` - `~/.openclaw/plugins/catalog.json` -Albo wskaż `OPENCLAW_PLUGIN_CATALOG_PATHS` (lub `OPENCLAW_MPM_CATALOG_PATHS`) na -jeden lub więcej plików JSON (rozdzielanych przecinkiem/średnikiem/jak w `PATH`). Każdy plik powinien -zawierać `{ "entries": [ { "name": "@scope/pkg", "openclaw": { "channel": {...}, "install": {...} } } ] }`. Parser akceptuje też `"packages"` lub `"plugins"` jako starsze aliasy dla klucza `"entries"`. +Lub wskaż `OPENCLAW_PLUGIN_CATALOG_PATHS` (albo `OPENCLAW_MPM_CATALOG_PATHS`) na +jeden lub więcej plików JSON (rozdzielanych przecinkami/średnikami/`PATH`). Każdy plik powinien +zawierać `{ "entries": [ { "name": "@scope/pkg", "openclaw": { "channel": {...}, "install": {...} } } ] }`. Parser akceptuje również `"packages"` lub `"plugins"` jako starsze aliasy klucza `"entries"`. ## Pluginy silnika kontekstu -Pluginy silnika kontekstu zarządzają orkiestracją kontekstu sesji dla ingestu, składania -i Compaction. Zarejestruj je ze swojego Pluginu przez -`api.registerContextEngine(id, factory)`, a następnie wybierz aktywny silnik przez +Pluginy silnika kontekstu są właścicielami orkiestracji kontekstu sesji dla ingestu, składania +i Compaction. Rejestruj je z pluginu przez +`api.registerContextEngine(id, factory)`, a następnie wybierz aktywny silnik za pomocą `plugins.slots.contextEngine`. -Używaj tego, gdy Twój Plugin musi zastąpić lub rozszerzyć domyślny potok -kontekstu, a nie tylko dodać wyszukiwanie pamięci lub hooki. +Użyj tego, gdy plugin musi zastąpić lub rozszerzyć domyślny +potok kontekstu, zamiast jedynie dodawać wyszukiwanie pamięci lub hooki. ```ts import { buildMemorySystemPromptAddition } from "openclaw/plugin-sdk/core"; @@ -1534,8 +1538,8 @@ export default function (api) { } ``` -Jeśli Twój silnik **nie** zarządza algorytmem Compaction, pozostaw -zaimplementowane `compact()` i jawnie deleguj je dalej: +Jeśli twój silnik **nie** jest właścicielem algorytmu Compaction, pozostaw `compact()` +zaimplementowane i jawnie deleguj je dalej: ```ts import { @@ -1572,45 +1576,45 @@ export default function (api) { ## Dodawanie nowej możliwości -Gdy Plugin potrzebuje zachowania, które nie mieści się w obecnym API, nie omijaj -systemu Pluginów przez prywatne sięganie do wnętrza. Dodaj brakującą możliwość. +Gdy plugin potrzebuje zachowania, które nie pasuje do obecnego API, nie omijaj +systemu pluginów przez prywatne sięgnięcie do środka. Dodaj brakującą możliwość. Zalecana sekwencja: 1. zdefiniuj kontrakt core Zdecyduj, jakim współdzielonym zachowaniem powinien zarządzać core: polityką, fallbackiem, scalaniem konfiguracji, - cyklem życia, semantyką skierowaną do kanałów i kształtem pomocnika runtime. -2. dodaj typowane powierzchnie rejestracji/runtime Pluginów + cyklem życia, semantyką skierowaną do kanałów i kształtem helpera runtime. +2. dodaj typowane powierzchnie rejestracji/runtime pluginów Rozszerz `OpenClawPluginApi` i/lub `api.runtime` o najmniejszą użyteczną typowaną powierzchnię możliwości. -3. podłącz core + konsumentów kanałów/funkcji - Kanały i Pluginy funkcji powinny korzystać z nowej możliwości przez core, +3. podłącz konsumentów core + kanałów/funkcji + Kanały i pluginy funkcjonalne powinny korzystać z nowej możliwości przez core, a nie przez bezpośredni import implementacji dostawcy. 4. zarejestruj implementacje dostawców - Pluginy dostawców rejestrują następnie swoje backendy względem tej możliwości. + Pluginy dostawców następnie rejestrują swoje backendy względem tej możliwości. 5. dodaj pokrycie kontraktowe - Dodaj testy, aby własność i kształt rejestracji pozostawały z czasem jawne. + Dodaj testy, aby własność i kształt rejestracji pozostawały jawne w czasie. -W ten sposób OpenClaw zachowuje wyraziste podejście, nie stając się na sztywno powiązanym -ze światopoglądem jednego dostawcy. Zobacz [Capability Cookbook](/pl/plugins/architecture), -aby uzyskać konkretną listę plików i opracowany przykład. +W ten sposób OpenClaw zachowuje zdecydowane podejście bez stawania się rozwiązaniem zakodowanym pod +światopogląd jednego dostawcy. Zobacz [Capability Cookbook](/pl/plugins/architecture), +aby uzyskać konkretną listę plików i gotowy przykład. ### Lista kontrolna możliwości Gdy dodajesz nową możliwość, implementacja powinna zwykle dotykać tych -powierzchni razem: +powierzchni jednocześnie: -- typów kontraktu core w `src//types.ts` -- runnera/pomocnika runtime core w `src//runtime.ts` -- powierzchni rejestracji API Pluginów w `src/plugins/types.ts` -- połączenia 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/kontraktów w `src/plugins/contracts/registry.ts` -- dokumentacji operatora/Pluginów w `docs/` +- typy kontraktów core w `src//types.ts` +- helper runtime/runner core w `src//runtime.ts` +- powierzchnia rejestracji API pluginów 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łowe + muszą z niej korzystać +- helpery przechwytywania/testów w `src/test-utils/plugin-registration.ts` +- asercje własności/kontraktów w `src/plugins/contracts/registry.ts` +- dokumentacja operatora/pluginów w `docs/` -Jeśli którejś z tych powierzchni brakuje, zwykle jest to znak, że możliwość nie została +Jeśli którejś z tych powierzchni brakuje, zwykle oznacza to, że możliwość nie jest jeszcze w pełni zintegrowana. ### Szablon możliwości @@ -1649,7 +1653,7 @@ expect(findVideoGenerationProviderIdsForPlugin("openai")).toEqual(["openai"]); To utrzymuje prostą zasadę: -- core zarządza kontraktem możliwości + orkiestracją -- Pluginy dostawców zarządzają implementacjami dostawców -- Pluginy funkcji/kanałów korzystają z pomocników runtime -- testy kontraktowe utrzymują własność jako jawną +- core jest właścicielem kontraktu możliwości + orkiestracji +- pluginy dostawców są właścicielami implementacji dostawców +- pluginy funkcjonalne/kanałowe korzystają z helperów runtime +- testy kontraktowe utrzymują jawną własność diff --git a/docs/pl/plugins/manifest.md b/docs/pl/plugins/manifest.md index 7cd8dc93b..9b5a84a1d 100644 --- a/docs/pl/plugins/manifest.md +++ b/docs/pl/plugins/manifest.md @@ -1,75 +1,74 @@ --- read_when: - Tworzysz Plugin OpenClaw - - Musisz dostarczyć schemat konfiguracji Pluginu albo debugować błędy walidacji Pluginu -summary: Manifest Pluginu + wymagania schematu JSON (ścisła walidacja konfiguracji) -title: Manifest Pluginu + - Musisz dostarczyć schemat konfiguracji Plugin lub debugować błędy walidacji Plugin +summary: Wymagania dotyczące manifestu Plugin + schematu JSON (ścisła walidacja konfiguracji) +title: Manifest Plugin x-i18n: - generated_at: "2026-04-12T23:28:43Z" + generated_at: "2026-04-15T09:51:04Z" model: gpt-5.4 provider: openai - source_hash: 93b57c7373e4ccd521b10945346db67991543bd2bed4cc8b6641e1f215b48579 + source_hash: ba2183bfa8802871e4ef33a0ebea290606e8351e9e83e25ee72456addb768730 source_path: plugins/manifest.md workflow: 15 --- -# Manifest Pluginu (`openclaw.plugin.json`) +# Manifest Plugin (`openclaw.plugin.json`) -Ta strona dotyczy wyłącznie **natywnego manifestu Pluginu OpenClaw**. +Ta strona dotyczy wyłącznie **natywnego manifestu Plugin OpenClaw**. -Informacje o zgodnych układach bundli znajdziesz tutaj: [Bundle Pluginów](/pl/plugins/bundles). +Informacje o zgodnych układach bundli znajdziesz w [Plugin bundles](/pl/plugins/bundles). Zgodne formaty bundli używają innych plików manifestu: -- Bundle Codex: `.codex-plugin/plugin.json` -- Bundle Claude: `.claude-plugin/plugin.json` albo domyślny układ komponentów Claude +- bundle Codex: `.codex-plugin/plugin.json` +- bundle Claude: `.claude-plugin/plugin.json` lub domyślny układ komponentu Claude bez manifestu -- Bundle Cursor: `.cursor-plugin/plugin.json` +- bundle Cursor: `.cursor-plugin/plugin.json` -OpenClaw automatycznie wykrywa również te układy bundli, ale nie są one walidowane -względem opisanego tutaj schematu `openclaw.plugin.json`. +OpenClaw również automatycznie wykrywa te układy bundli, ale nie są one walidowane +względem schematu `openclaw.plugin.json` opisanego tutaj. W przypadku zgodnych bundli OpenClaw obecnie odczytuje metadane bundla oraz zadeklarowane -korzenie Skills, korzenie poleceń Claude, domyślne wartości `settings.json` bundla Claude, -domyślne wartości LSP bundla Claude oraz obsługiwane pakiety hooków, gdy układ odpowiada +korzenie skilli, korzenie poleceń Claude, domyślne wartości `settings.json` bundla Claude, +domyślne ustawienia LSP bundla Claude oraz obsługiwane pakiety 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. +**katalogu głównym Plugin**. OpenClaw używa tego manifestu do walidacji konfiguracji +**bez wykonywania kodu Plugin**. Brakujące lub nieprawidłowe manifesty są traktowane jako +błędy Plugin i blokują walidację konfiguracji. -Zobacz pełny przewodnik po systemie Pluginów: [Pluginy](/pl/tools/plugin). -Informacje o natywnym modelu capabilities i aktualnych wskazówkach dotyczących zgodności zewnętrznej: -[Model capabilities](/pl/plugins/architecture#public-capability-model). +Zobacz pełny przewodnik po systemie Plugin: [Plugins](/pl/tools/plugin). +Informacje o natywnym modelu możliwości i aktualnych wytycznych dotyczących zewnętrznej kompatybilności: +[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 Plugin. Używaj go do: -- tożsamości Pluginu +- tożsamości Plugin - walidacji konfiguracji -- metadanych auth i onboardingu, które powinny być dostępne bez uruchamiania środowiska uruchomieniowego Pluginu -- lekkich wskazówek aktywacji, które powierzchnie płaszczyzny sterowania mogą sprawdzać przed załadowaniem środowiska uruchomieniowego -- lekkich deskryptorów konfiguracji, które powierzchnie konfiguracji/onboardingu mogą sprawdzać przed załadowaniem środowiska uruchomieniowego -- metadanych aliasów i auto-enable, które powinny zostać rozstrzygnięte przed załadowaniem środowiska uruchomieniowego Pluginu -- skróconych metadanych własności rodzin modeli, które powinny auto-activate - Plugin przed załadowaniem środowiska uruchomieniowego -- statycznych snapshotów własności capabilities używanych do zgodnego okablowania bundli i pokrycia kontraktów -- metadanych konfiguracji specyficznych dla kanału, które powinny zostać scalone z powierzchniami katalogu i walidacji - bez ładowania środowiska uruchomieniowego +- metadanych uwierzytelniania i onboardingu, które powinny być dostępne bez uruchamiania środowiska uruchomieniowego Plugin +- tanich wskazówek aktywacji, które powierzchnie płaszczyzny sterowania mogą sprawdzać przed załadowaniem środowiska uruchomieniowego +- tanich deskryptorów konfiguracji, które powierzchnie konfiguracji/onboardingu mogą sprawdzać przed załadowaniem środowiska uruchomieniowego +- metadanych aliasów i automatycznego włączania, które powinny być rozstrzygane przed załadowaniem środowiska uruchomieniowego Plugin +- skróconych metadanych własności rodziny modeli, które powinny automatycznie aktywować Plugin przed załadowaniem środowiska uruchomieniowego +- statycznych migawek własności możliwości używanych do zgodnego okablowania bundli i pokrycia kontraktów +- tanich metadanych runnera QA, które współdzielony host `openclaw qa` może sprawdzać przed załadowaniem środowiska uruchomieniowego Plugin +- metadanych konfiguracji specyficznych dla kanału, które powinny zostać scalone z powierzchniami katalogu i walidacji bez ładowania środowiska uruchomieniowego - wskazówek UI konfiguracji Nie używaj go do: -- rejestrowania zachowania środowiska uruchomieniowego -- deklarowania entrypointów kodu +- rejestrowania zachowania w czasie wykonywania +- deklarowania punktów wejścia kodu - metadanych instalacji npm -To należy do kodu Pluginu i `package.json`. +Te elementy należą do kodu Plugin i `package.json`. ## Minimalny przykład @@ -140,64 +139,65 @@ To należy do kodu Pluginu i `package.json`. } ``` -## Informacje o polach najwyższego poziomu +## Opis pól najwyższego poziomu -| Pole | Wymagane | Typ | Co oznacza | +| Pole | Wymagane | Typ | Znaczenie | | ----------------------------------- | -------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `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 bundlowy 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, które są normalizowane do tego kanonicznego identyfikatora Pluginu. | -| `autoEnableWhenConfiguredProviders` | Nie | `string[]` | Identyfikatory dostawców, które powinny automatycznie włączać ten Plugin, gdy auth, konfiguracja lub odwołania do modeli na nie wskazują. | -| `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 zał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. | -| `commandAliases` | Nie | `object[]` | Nazwy poleceń należące do tego Pluginu, które powinny generować diagnostykę konfiguracji i CLI uwzględniającą Plugin jeszcze przed załadowaniem środowiska uruchomieniowego. | -| `providerAuthEnvVars` | Nie | `Record` | Lekkie metadane env dla auth dostawców, 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 kodowania, który współdzieli bazowy klucz API dostawcy i profile auth. | -| `channelEnvVars` | Nie | `Record` | Lekkie metadane env dla kanałów, które OpenClaw może sprawdzać bez ładowania kodu Pluginu. Używaj tego dla konfiguracji kanałów sterowanej przez env albo powierzchni auth, które powinny widzieć ogólne pomocniki uruchamiania/konfiguracji. | -| `providerAuthChoices` | Nie | `object[]` | Lekkie metadane wyboru auth dla selektorów onboardingu, rozstrzygania preferowanego dostawcy i prostego okablowania flag CLI. | -| `activation` | Nie | `object` | Lekkie wskazówki aktywacji dla ładowania wyzwalanego przez dostawcę, polecenie, kanał, trasę i capability. Tylko metadane; rzeczywiste zachowanie nadal należy do środowiska uruchomieniowego Pluginu. | -| `setup` | Nie | `object` | Lekkie deskryptory konfiguracji/onboardingu, które powierzchnie wykrywania i konfiguracji mogą sprawdzać bez ładowania środowiska uruchomieniowego Pluginu. | -| `contracts` | Nie | `object` | Statyczny snapshot bundlowych capabilities dla speech, realtime transcription, realtime voice, media-understanding, image-generation, music-generation, video-generation, web-fetch, web search i własności narzędzi. | -| `channelConfigs` | Nie | `Record` | Metadane konfiguracji kanału należące do manifestu, scalane z powierzchniami wykrywania i walidacji przed załadowaniem środowiska uruchomieniowego. | -| `skills` | Nie | `string[]` | Katalogi Skills do załadowania, względne względem katalogu głównego Pluginu. | -| `name` | Nie | `string` | Przyjazna dla człowieka nazwa Pluginu. | -| `description` | Nie | `string` | Krótkie podsumowanie wyświetlane na powierzchniach Pluginu. | -| `version` | Nie | `string` | Informacyjna wersja Pluginu. | +| `id` | Tak | `string` | Kanoniczny identyfikator Plugin. Jest to identyfikator używany w `plugins.entries.`. | +| `configSchema` | Tak | `object` | Wbudowany schemat JSON Schema dla konfiguracji tego Plugin. | +| `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. | +| `legacyPluginIds` | Nie | `string[]` | Starsze identyfikatory normalizowane do tego kanonicznego identyfikatora Plugin. | +| `autoEnableWhenConfiguredProviders` | Nie | `string[]` | Identyfikatory dostawców, które powinny automatycznie włączyć ten Plugin, gdy uwierzytelnianie, konfiguracja lub odwołania do modeli o nich wspominają. | +| `kind` | Nie | `"memory"` \| `"context-engine"` | Deklaruje wyłączny rodzaj Plugin używany przez `plugins.slots.*`. | +| `channels` | Nie | `string[]` | Identyfikatory kanałów należących do tego Plugin. Używane do wykrywania i walidacji konfiguracji. | +| `providers` | Nie | `string[]` | Identyfikatory dostawców należących do tego Plugin. | +| `modelSupport` | Nie | `object` | Należące do manifestu skrócone metadane rodziny modeli używane do automatycznego ładowania Plugin przed uruchomieniem środowiska wykonawczego. | +| `cliBackends` | Nie | `string[]` | Identyfikatory backendów inferencji CLI należących do tego Plugin. Używane do automatycznej aktywacji przy uruchomieniu na podstawie jawnych odwołań w konfiguracji. | +| `commandAliases` | Nie | `object[]` | Nazwy poleceń należących do tego Plugin, które powinny generować diagnostykę konfiguracji i CLI świadomą Plugin przed załadowaniem środowiska uruchomieniowego. | +| `providerAuthEnvVars` | Nie | `Record` | Lekkie metadane zmiennych środowiskowych uwierzytelniania dostawcy, które OpenClaw może sprawdzać bez ładowania kodu Plugin. | +| `providerAuthAliases` | Nie | `Record` | Identyfikatory dostawców, które powinny ponownie używać innego identyfikatora dostawcy do wyszukiwania uwierzytelniania, na przykład dostawca kodowania współdzielący bazowy klucz API i profile auth. | +| `channelEnvVars` | Nie | `Record` | Lekkie metadane zmiennych środowiskowych kanału, które OpenClaw może sprawdzać bez ładowania kodu Plugin. Użyj tego dla konfiguracji kanału sterowanej przez env lub powierzchni auth, które powinny być widoczne dla generycznych pomocników uruchamiania/konfiguracji. | +| `providerAuthChoices` | Nie | `object[]` | Lekkie metadane wyboru uwierzytelniania dla selektorów onboardingu, rozstrzygania preferowanego dostawcy i prostego mapowania flag CLI. | +| `activation` | Nie | `object` | Lekkie wskazówki aktywacji dla ładowania wyzwalanego przez dostawcę, polecenie, kanał, trasę i możliwości. Tylko metadane; rzeczywiste zachowanie nadal należy do środowiska uruchomieniowego Plugin. | +| `setup` | Nie | `object` | Lekkie deskryptory konfiguracji/onboardingu, które powierzchnie wykrywania i konfiguracji mogą sprawdzać bez ładowania środowiska uruchomieniowego Plugin. | +| `qaRunners` | Nie | `object[]` | Lekkie deskryptory runnerów QA używane przez współdzielony host `openclaw qa` przed załadowaniem środowiska uruchomieniowego Plugin. | +| `contracts` | Nie | `object` | Statyczna migawka możliwości bundla dla speech, realtime transcription, realtime voice, media-understanding, image-generation, music-generation, video-generation, 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 środowiska uruchomieniowego. | +| `skills` | Nie | `string[]` | Katalogi Skills do załadowania, względne względem katalogu głównego Plugin. | +| `name` | Nie | `string` | Czytelna dla człowieka nazwa Plugin. | +| `description` | Nie | `string` | Krótkie podsumowanie wyświetlane na powierzchniach Plugin. | +| `version` | Nie | `string` | Informacyjna wersja Plugin. | | `uiHints` | Nie | `Record` | Etykiety UI, placeholdery i wskazówki dotyczące wrażliwości dla pól konfiguracji. | -## Informacje o `providerAuthChoices` +## Opis `providerAuthChoices` -Każdy wpis `providerAuthChoices` opisuje jeden wybór onboardingu lub auth. -OpenClaw odczytuje to, zanim załaduje się środowisko uruchomieniowe dostawcy. +Każdy wpis `providerAuthChoices` opisuje jeden wybór onboardingu lub uwierzytelniania. +OpenClaw odczytuje to przed załadowaniem środowiska uruchomieniowego dostawcy. -| Pole | Wymagane | Typ | Co oznacza | -| --------------------- | -------- | ----------------------------------------------- | -------------------------------------------------------------------------------------------------------- | -| `provider` | Tak | `string` | Identyfikator dostawcy, do którego należy ten wybór. | -| `method` | Tak | `string` | Identyfikator metody auth, do której należy przekazać sterowanie. | -| `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 wyboru, 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 z jedną flagą. | -| `cliFlag` | Nie | `string` | Nazwa flagi CLI, taka jak `--openrouter-api-key`. | -| `cliOption` | Nie | `string` | Pełna postać opcji CLI, taka jak `--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 zostanie pominięte, domyślnie używane jest `["text-inference"]`. | +| Pole | Wymagane | Typ | Znaczenie | +| --------------------- | -------- | ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | +| `provider` | Tak | `string` | Identyfikator dostawcy, do którego należy ten wybór. | +| `method` | Tak | `string` | Identyfikator metody uwierzytelniania, do której należy przekazać sterowanie. | +| `choiceId` | Tak | `string` | Stabilny identyfikator wyboru 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 wybór przed selektorami asystenta, nadal pozwalając na ręczny wybór w CLI. | +| `deprecatedChoiceIds` | Nie | `string[]` | Starsze identyfikatory wyboru, 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 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">` | Określa, na których powierzchniach onboardingu ten wybór powinien się pojawiać. Jeśli zostanie pominięte, domyślnie używane jest `["text-inference"]`. | -## Informacje o `commandAliases` +## Opis `commandAliases` -Używaj `commandAliases`, gdy Plugin posiada nazwę polecenia środowiska uruchomieniowego, którą użytkownicy mogą -omyłkowo umieścić w `plugins.allow` albo próbować uruchomić jako główne polecenie CLI. OpenClaw -używa tych metadanych do diagnostyki bez importowania kodu środowiska uruchomieniowego Pluginu. +Używaj `commandAliases`, gdy Plugin jest właścicielem nazwy polecenia czasu wykonywania, którą użytkownicy mogą +omyłkowo umieścić w `plugins.allow` lub próbować uruchomić jako główne polecenie CLI. OpenClaw +używa tych metadanych do diagnostyki bez importowania kodu środowiska uruchomieniowego Plugin. ```json { @@ -211,22 +211,45 @@ używa tych metadanych do diagnostyki bez importowania kodu środowiska uruchomi } ``` -| Pole | Wymagane | Typ | Co oznacza | -| ------------ | -------- | ----------------- | ----------------------------------------------------------------------------------- | -| `name` | Tak | `string` | Nazwa polecenia należąca do tego Pluginu. | -| `kind` | Nie | `"runtime-slash"` | Oznacza alias jako polecenie ukośnikowe czatu, a nie główne polecenie CLI. | -| `cliCommand` | Nie | `string` | Powiązane główne polecenie CLI, które należy zasugerować dla operacji CLI, jeśli istnieje. | +| Pole | Wymagane | Typ | Znaczenie | +| ------------ | -------- | ----------------- | ---------------------------------------------------------------------- | +| `name` | Tak | `string` | Nazwa polecenia należąca do tego Plugin. | +| `kind` | Nie | `"runtime-slash"` | Oznacza alias jako polecenie slash czatu, a nie główne polecenie CLI. | +| `cliCommand` | Nie | `string` | Powiązane główne polecenie CLI sugerowane dla operacji CLI, jeśli istnieje. | -## Informacje o `activation` +## Opis `activation` Używaj `activation`, gdy Plugin może w prosty sposób zadeklarować, które zdarzenia płaszczyzny sterowania powinny aktywować go później. -Ten blok zawiera wyłącznie metadane. Nie rejestruje zachowania środowiska uruchomieniowego i nie -zastępuje `register(...)`, `setupEntry` ani innych entrypointów środowiska uruchomieniowego/Pluginu. -Obecni konsumenci używają go jako wskazówki zawężającej przed szerszym ładowaniem Pluginów, więc -brak metadanych aktywacji zwykle wpływa tylko na wydajność; nie powinien zmieniać -poprawności, dopóki nadal istnieją starsze fallbacki własności manifestu. +## Opis `qaRunners` + +Używaj `qaRunners`, gdy Plugin dodaje jeden lub więcej runnerów transportu pod +wspólnym korzeniem `openclaw qa`. Zachowaj te metadane jako lekkie i statyczne; środowisko uruchomieniowe Plugin +nadal odpowiada za faktyczną rejestrację CLI przez lekką powierzchnię +`runtime-api.ts`, która eksportuje `qaRunnerCliRegistrations`. + +```json +{ + "qaRunners": [ + { + "commandName": "matrix", + "description": "Uruchom wspieraną przez Docker ścieżkę live QA Matrix na jednorazowym homeserverze" + } + ] +} +``` + +| Pole | Wymagane | Typ | Znaczenie | +| ------------- | -------- | -------- | ------------------------------------------------------------------- | +| `commandName` | Tak | `string` | Podpolecenie montowane pod `openclaw qa`, na przykład `matrix`. | +| `description` | Nie | `string` | Zapasowy tekst pomocy używany, gdy współdzielony host potrzebuje polecenia zastępczego. | + +Ten blok to tylko metadane. Nie rejestruje zachowania w czasie wykonywania i nie +zastępuje `register(...)`, `setupEntry` ani innych punktów wejścia runtime/Plugin. +Obecni konsumenci używają go jako wskazówki zawężającej przed szerszym ładowaniem Plugin, więc +brak metadanych aktywacji zwykle wpływa tylko na wydajność; nie powinien +zmieniać poprawności, dopóki istnieją jeszcze starsze fallbacki własności manifestu. ```json { @@ -240,27 +263,26 @@ poprawności, dopóki nadal istnieją starsze fallbacki własności manifestu. } ``` -| Pole | Wymagane | Typ | Co oznacza | -| ---------------- | -------- | ---------------------------------------------------- | ------------------------------------------------------------------- | -| `onProviders` | Nie | `string[]` | Identyfikatory dostawców, które powinny aktywować ten Plugin po zażądaniu. | -| `onCommands` | Nie | `string[]` | Identyfikatory poleceń, które powinny aktywować ten Plugin. | -| `onChannels` | Nie | `string[]` | Identyfikatory kanałów, które powinny aktywować ten Plugin. | -| `onRoutes` | Nie | `string[]` | Rodzaje tras, które powinny aktywować ten Plugin. | -| `onCapabilities` | Nie | `Array<"provider" \| "channel" \| "tool" \| "hook">` | Szerokie wskazówki capabilities używane przez planowanie aktywacji płaszczyzny sterowania. | +| Pole | Wymagane | Typ | Znaczenie | +| ---------------- | -------- | ---------------------------------------------------- | ------------------------------------------------------------------ | +| `onProviders` | Nie | `string[]` | Identyfikatory dostawców, które powinny aktywować ten Plugin po żądaniu. | +| `onCommands` | Nie | `string[]` | Identyfikatory poleceń, które powinny aktywować ten Plugin. | +| `onChannels` | Nie | `string[]` | Identyfikatory kanałów, które powinny aktywować ten Plugin. | +| `onRoutes` | Nie | `string[]` | Rodzaje tras, które powinny aktywować ten Plugin. | +| `onCapabilities` | Nie | `Array<"provider" \| "channel" \| "tool" \| "hook">` | Szerokie wskazówki dotyczące możliwości używane przez planowanie aktywacji płaszczyzny sterowania. | Obecni aktywni konsumenci: -- planowanie CLI wyzwalane poleceniem wraca awaryjnie do starszych - `commandAliases[].cliCommand` albo `commandAliases[].name` -- planowanie konfiguracji/kanałów wyzwalane kanałem wraca awaryjnie do starszej własności - `channels[]`, gdy brakuje jawnych metadanych aktywacji kanału -- planowanie konfiguracji/środowiska uruchomieniowego wyzwalane dostawcą wraca awaryjnie do starszej - własności `providers[]` i `cliBackends[]` najwyższego poziomu, gdy brakuje jawnych metadanych - aktywacji dostawcy +- planowanie CLI wyzwalane poleceniem korzysta awaryjnie ze starszego + `commandAliases[].cliCommand` lub `commandAliases[].name` +- planowanie konfiguracji/kanału wyzwalane kanałem korzysta awaryjnie ze starszej + własności `channels[]`, gdy brakuje jawnych metadanych aktywacji kanału +- planowanie konfiguracji/runtime wyzwalane dostawcą korzysta awaryjnie ze starszej + własności `providers[]` i najwyższego poziomu `cliBackends[]`, gdy brakuje jawnych metadanych aktywacji dostawcy -## Informacje o `setup` +## Opis `setup` -Używaj `setup`, gdy powierzchnie konfiguracji i onboardingu potrzebują lekkich metadanych należących do Pluginu +Używaj `setup`, gdy powierzchnie konfiguracji i onboardingu potrzebują lekkich metadanych należących do Plugin przed załadowaniem środowiska uruchomieniowego. ```json @@ -280,41 +302,41 @@ przed załadowaniem środowiska uruchomieniowego. } ``` -`cliBackends` najwyższego poziomu pozostaje prawidłowe i nadal opisuje backendy +Najwyższego poziomu `cliBackends` pozostaje prawidłowe i nadal opisuje backendy inferencji CLI. `setup.cliBackends` to powierzchnia deskryptorów specyficzna dla konfiguracji dla przepływów płaszczyzny sterowania/konfiguracji, które powinny pozostać wyłącznie metadanymi. Jeśli są obecne, `setup.providers` i `setup.cliBackends` są preferowaną -powierzchnią wyszukiwania najpierw po deskryptorach dla wykrywania konfiguracji. Jeśli deskryptor tylko -zawęża kandydujący Plugin, a konfiguracja nadal potrzebuje bogatszych hooków środowiska uruchomieniowego w czasie konfiguracji, +powierzchnią wyszukiwania konfiguracji w modelu descriptor-first dla wykrywania konfiguracji. Jeśli deskryptor tylko +zawęża kandydujący Plugin, a konfiguracja nadal potrzebuje bogatszych hooków runtime na etapie konfiguracji, ustaw `requiresRuntime: true` i pozostaw `setup-api` jako -awaryjną ścieżkę wykonania. +zapasową ścieżkę wykonania. -Ponieważ wyszukiwanie konfiguracji może wykonywać należący do Pluginu kod `setup-api`, -znormalizowane wartości `setup.providers[].id` i `setup.cliBackends[]` muszą pozostać unikalne globalnie -wśród wykrytych Pluginów. Niejednoznaczna własność kończy się bez wyboru zwycięzcy -według kolejności wykrycia. +Ponieważ wyszukiwanie konfiguracji może wykonywać należący do Plugin kod `setup-api`, +znormalizowane wartości `setup.providers[].id` i `setup.cliBackends[]` muszą pozostać unikalne +we wszystkich wykrytych Plugin. Niejednoznaczna własność kończy się bezpieczną odmową zamiast wybierania +zwycięzcy na podstawie kolejności wykrywania. -### Informacje o `setup.providers` +### Opis `setup.providers` -| Pole | Wymagane | Typ | Co oznacza | -| ------------- | -------- | ---------- | -------------------------------------------------------------------------------------------- | -| `id` | Tak | `string` | Identyfikator dostawcy udostępniany podczas konfiguracji lub onboardingu. Znormalizowane identyfikatory muszą być globalnie unikalne. | -| `authMethods` | Nie | `string[]` | Identyfikatory metod konfiguracji/auth obsługiwanych przez tego dostawcę bez ładowania pełnego środowiska uruchomieniowego. | -| `envVars` | Nie | `string[]` | Zmienne env, które ogólne powierzchnie konfiguracji/statusu mogą sprawdzać przed załadowaniem środowiska uruchomieniowego Pluginu. | +| Pole | Wymagane | Typ | Znaczenie | +| ------------- | -------- | ---------- | ------------------------------------------------------------------------------------------ | +| `id` | Tak | `string` | Identyfikator dostawcy ujawniany podczas konfiguracji lub onboardingu. Zachowaj globalnie unikalne znormalizowane identyfikatory. | +| `authMethods` | Nie | `string[]` | Identyfikatory metod konfiguracji/uwierzytelniania, które ten dostawca obsługuje bez ładowania pełnego runtime. | +| `envVars` | Nie | `string[]` | Zmienne środowiskowe, które generyczne powierzchnie konfiguracji/statusu mogą sprawdzać przed załadowaniem środowiska uruchomieniowego Plugin. | ### Pola `setup` -| Pole | Wymagane | Typ | Co oznacza | -| ------------------ | -------- | ---------- | ---------------------------------------------------------------------------------------------------- | -| `providers` | Nie | `object[]` | Deskryptory konfiguracji dostawców udostępniane podczas konfiguracji i onboardingu. | -| `cliBackends` | Nie | `string[]` | Identyfikatory backendów czasu konfiguracji używane do wyszukiwania konfiguracji najpierw po deskryptorach. Znormalizowane identyfikatory muszą być globalnie unikalne. | -| `configMigrations` | Nie | `string[]` | Identyfikatory migracji konfiguracji należące do powierzchni konfiguracji tego Pluginu. | -| `requiresRuntime` | Nie | `boolean` | Czy konfiguracja nadal wymaga wykonania `setup-api` po wyszukaniu deskryptora. | +| Pole | Wymagane | Typ | Znaczenie | +| ------------------ | -------- | ---------- | ----------------------------------------------------------------------------------------------------- | +| `providers` | Nie | `object[]` | Deskryptory konfiguracji dostawców ujawniane podczas konfiguracji i onboardingu. | +| `cliBackends` | Nie | `string[]` | Identyfikatory backendów czasu konfiguracji używane do wyszukiwania konfiguracji w modelu descriptor-first. Zachowaj globalnie unikalne znormalizowane identyfikatory. | +| `configMigrations` | Nie | `string[]` | Identyfikatory migracji konfiguracji należące do powierzchni konfiguracji tego Plugin. | +| `requiresRuntime` | Nie | `boolean` | Czy konfiguracja nadal wymaga wykonania `setup-api` po wyszukaniu deskryptora. | -## Informacje o `uiHints` +## Opis `uiHints` -`uiHints` to mapa od nazw pól konfiguracji do małych wskazówek renderowania. +`uiHints` to mapa nazw pól konfiguracji do małych wskazówek renderowania. ```json { @@ -331,7 +353,7 @@ według kolejności wykrycia. Każda wskazówka pola może zawierać: -| Pole | Typ | Co oznacza | +| Pole | Typ | Znaczenie | | ------------- | ---------- | ---------------------------------------- | | `label` | `string` | Etykieta pola widoczna dla użytkownika. | | `help` | `string` | Krótki tekst pomocniczy. | @@ -340,10 +362,10 @@ Każda wskazówka pola może zawierać: | `sensitive` | `boolean` | Oznacza pole jako sekretne lub wrażliwe. | | `placeholder` | `string` | Tekst placeholdera dla pól formularza. | -## Informacje o `contracts` +## Opis `contracts` -Używaj `contracts` wyłącznie dla statycznych metadanych własności capabilities, które OpenClaw może -odczytać bez importowania środowiska uruchomieniowego Pluginu. +Używaj `contracts` tylko dla statycznych metadanych własności możliwości, które OpenClaw może +odczytać bez importowania środowiska uruchomieniowego Plugin. ```json { @@ -363,21 +385,21 @@ odczytać bez importowania środowiska uruchomieniowego Pluginu. Każda lista jest opcjonalna: -| Pole | Typ | Co oznacza | -| -------------------------------- | ---------- | ------------------------------------------------------------ | -| `speechProviders` | `string[]` | Identyfikatory dostawców speech należących do tego Pluginu. | -| `realtimeTranscriptionProviders` | `string[]` | Identyfikatory dostawców realtime transcription należących do tego Pluginu. | -| `realtimeVoiceProviders` | `string[]` | Identyfikatory dostawców realtime voice należących do tego Pluginu. | -| `mediaUnderstandingProviders` | `string[]` | Identyfikatory dostawców media-understanding należących do tego Pluginu. | -| `imageGenerationProviders` | `string[]` | Identyfikatory dostawców image-generation należących do tego Pluginu. | -| `videoGenerationProviders` | `string[]` | Identyfikatory dostawców video-generation należących do tego Pluginu. | -| `webFetchProviders` | `string[]` | Identyfikatory dostawców web-fetch należących do tego Pluginu. | -| `webSearchProviders` | `string[]` | Identyfikatory dostawców web search należących do tego Pluginu. | -| `tools` | `string[]` | Nazwy narzędzi agenta należących do tego Pluginu dla bundlowych kontroli kontraktów. | +| Pole | Typ | Znaczenie | +| -------------------------------- | ---------- | ------------------------------------------------------------------- | +| `speechProviders` | `string[]` | Identyfikatory dostawców speech należących do tego Plugin. | +| `realtimeTranscriptionProviders` | `string[]` | Identyfikatory dostawców realtime transcription należących do tego Plugin. | +| `realtimeVoiceProviders` | `string[]` | Identyfikatory dostawców realtime voice należących do tego Plugin. | +| `mediaUnderstandingProviders` | `string[]` | Identyfikatory dostawców media-understanding należących do tego Plugin. | +| `imageGenerationProviders` | `string[]` | Identyfikatory dostawców image-generation należących do tego Plugin. | +| `videoGenerationProviders` | `string[]` | Identyfikatory dostawców video-generation należących do tego Plugin. | +| `webFetchProviders` | `string[]` | Identyfikatory dostawców web-fetch należących do tego Plugin. | +| `webSearchProviders` | `string[]` | Identyfikatory dostawców web search należących do tego Plugin. | +| `tools` | `string[]` | Nazwy narzędzi agenta należących do tego Plugin dla sprawdzania kontraktów bundli. | -## Informacje o `channelConfigs` +## Opis `channelConfigs` -Używaj `channelConfigs`, gdy Plugin kanału potrzebuje lekkich metadanych konfiguracji przed +Używaj `channelConfigs`, gdy kanałowy Plugin potrzebuje lekkich metadanych konfiguracji przed załadowaniem środowiska uruchomieniowego. ```json @@ -393,12 +415,12 @@ załadowaniem środowiska uruchomieniowego. }, "uiHints": { "homeserverUrl": { - "label": "URL Homeservera", + "label": "URL homeserwera", "placeholder": "https://matrix.example.com" } }, "label": "Matrix", - "description": "Połączenie z homeserverem Matrix", + "description": "Połączenie z homeserwerem Matrix", "preferOver": ["matrix-legacy"] } } @@ -407,18 +429,18 @@ załadowaniem środowiska uruchomieniowego. Każdy wpis kanału może zawierać: -| Pole | Typ | Co oznacza | -| ------------- | ------------------------ | -------------------------------------------------------------------------------------------- | -| `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 wyboru i inspekcji, gdy metadane środowiska uruchomieniowego nie są jeszcze 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. | +| 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 wyboru i inspekcji, gdy metadane runtime nie są gotowe. | +| `description` | `string` | Krótki opis kanału dla powierzchni inspekcji i katalogu. | +| `preferOver` | `string[]` | Starsze lub niższopriorytetowe identyfikatory Plugin, które ten kanał powinien wyprzedzać na powierzchniach wyboru. | -## Informacje o `modelSupport` +## Opis `modelSupport` -Używaj `modelSupport`, gdy OpenClaw powinien wywnioskować Plugin dostawcy na podstawie -skróconych identyfikatorów modeli, takich jak `gpt-5.4` albo `claude-sonnet-4.6`, zanim załaduje się środowisko uruchomieniowe Pluginu. +Używaj `modelSupport`, gdy OpenClaw powinien wywnioskować Twój Plugin dostawcy na podstawie +skrótowych identyfikatorów modeli takich jak `gpt-5.4` lub `claude-sonnet-4.6` przed załadowaniem runtime Plugin. ```json { @@ -431,73 +453,73 @@ skróconych identyfikatorów modeli, takich jak `gpt-5.4` albo `claude-sonnet-4. OpenClaw stosuje następujący priorytet: -- jawne odwołania `provider/model` używają należących do właściciela metadanych manifestu `providers` -- `modelPatterns` mają wyższy priorytet niż `modelPrefixes` -- jeśli pasuje jeden Plugin zewnętrzny i jeden Plugin bundlowy, wygrywa Plugin zewnętrzny -- pozostała niejednoznaczność jest ignorowana, dopóki użytkownik lub konfiguracja nie wskaże dostawcy +- jawne odwołania `provider/model` używają metadanych manifestu `providers` właściciela +- `modelPatterns` mają pierwszeństwo przed `modelPrefixes` +- jeśli pasują jednocześnie jeden Plugin niebundlowany i jeden bundlowany, wygrywa Plugin + niebundlowany +- pozostała niejednoznaczność jest ignorowana, dopóki użytkownik lub konfiguracja nie określi dostawcy Pola: -| Pole | Typ | Co oznacza | +| Pole | Typ | Znaczenie | | --------------- | ---------- | ------------------------------------------------------------------------------ | -| `modelPrefixes` | `string[]` | Prefiksy dopasowywane przez `startsWith` do skróconych identyfikatorów modeli. | -| `modelPatterns` | `string[]` | Źródła regex dopasowywane do skróconych identyfikatorów modeli po usunięciu sufiksu profilu. | +| `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 capabilities najwyższego poziomu są przestarzałe. Użyj `openclaw doctor --fix`, aby +Starsze klucze możliwości najwyższego poziomu są przestarzałe. Użyj `openclaw doctor --fix`, aby przenieść `speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders` i `webSearchProviders` do `contracts`; zwykłe ładowanie manifestu nie traktuje już tych pól najwyższego poziomu jako -własności capabilities. +własności możliwości. -## Manifest a `package.json` +## Manifest a package.json -Te dwa pliki służą do różnych zadań: +Te dwa pliki pełnią różne role: -| Plik | Używaj go do | -| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | -| `openclaw.plugin.json` | Wykrywania, walidacji konfiguracji, metadanych wyboru auth i wskazówek UI, które muszą istnieć przed uruchomieniem kodu Pluginu | -| `package.json` | Metadanych npm, instalacji zależności oraz bloku `openclaw` używanego do entrypointów, bramek instalacji, konfiguracji lub metadanych katalogu | +| Plik | Użycie | +| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | +| `openclaw.plugin.json` | Wykrywanie, walidacja konfiguracji, metadane wyboru uwierzytelniania i wskazówki UI, które muszą istnieć przed uruchomieniem kodu Plugin | +| `package.json` | Metadane npm, instalacja zależności oraz blok `openclaw` używany dla punktów wejścia, blokowania instalacji, konfiguracji lub metadanych katalogu | -Jeśli nie masz pewności, gdzie powinien trafić dany fragment metadanych, stosuj tę zasadę: +Jeśli nie masz pewności, gdzie powinien należeć dany fragment metadanych, użyj tej zasady: -- jeśli OpenClaw musi znać go przed załadowaniem kodu Pluginu, umieść go w `openclaw.plugin.json` -- jeśli dotyczy pakowania, plików wejściowych albo zachowania instalacji npm, umieść go w `package.json` +- jeśli OpenClaw musi znać go przed załadowaniem kodu Plugin, umieść go w `openclaw.plugin.json` +- jeśli dotyczy pakowania, plików wejściowych lub zachowania instalacji npm, umieść go w `package.json` -### Pola `package.json`, które wpływają na wykrywanie +### Pola package.json wpływające na wykrywanie -Niektóre metadane Pluginów przed uruchomieniem celowo znajdują się w `package.json` w bloku +Część metadanych Plugin używanych przed uruchomieniem celowo znajduje się w `package.json` w bloku `openclaw`, a nie w `openclaw.plugin.json`. Ważne przykłady: -| Pole | Co oznacza | -| ----------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | -| `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łów, takie jak etykiety, ścieżki do dokumentacji, aliasy i tekst wyboru. | -| `openclaw.channel.configuredState` | Lekkie metadane sprawdzania stanu konfiguracji, które mogą odpowiedzieć na pytanie „czy konfiguracja oparta wyłącznie na env już istnieje?” bez ładowania pełnego środowiska uruchomieniowego kanału. | -| `openclaw.channel.persistedAuthState` | Lekkie metadane sprawdzania trwałego stanu auth, które mogą odpowiedzieć na pytanie „czy cokolwiek jest już zalogowane?” bez ładowania pełnego środowiska uruchomieniowego kanału. | -| `openclaw.install.npmSpec` / `openclaw.install.localPath` | Wskazówki instalacji/aktualizacji dla Pluginów bundlowych i publikowanych zewnętrznie. | +| Pole | Znaczenie | +| ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | +| `openclaw.extensions` | Deklaruje natywne punkty wejścia Plugin. | +| `openclaw.setupEntry` | Lekki punkt wejścia 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 teksty wyboru. | +| `openclaw.channel.configuredState` | Lekkie metadane sprawdzania stanu skonfigurowania, które potrafią odpowiedzieć na pytanie „czy konfiguracja tylko z env już istnieje?” bez ładowania pełnego runtime kanału. | +| `openclaw.channel.persistedAuthState` | Lekkie metadane sprawdzania utrwalonego stanu auth, które potrafią 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 Plugin bundlowanych i publikowanych zewnętrznie. | | `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 dolnego ograniczenia semver, takiego jak `>=2026.3.22`. | -| `openclaw.install.allowInvalidConfigRecovery` | Umożliwia wąską ścieżkę odzyskiwania po ponownej instalacji bundlowego Pluginu, gdy konfiguracja jest nieprawidłowa. | -| `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` | Pozwala powierzchniom kanałów tylko do konfiguracji załadować się przed pełnym Pluginem kanału podczas uruchamiania. | +| `openclaw.install.minHostVersion` | Minimalna obsługiwana wersja hosta OpenClaw, używająca dolnego ograniczenia semver, na przykład `>=2026.3.22`. | +| `openclaw.install.allowInvalidConfigRecovery` | Pozwala na wąską ścieżkę odzyskiwania przez ponowną instalację bundlowanego Plugin, gdy konfiguracja jest nieprawidłowa. | +| `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` | Pozwala ładować powierzchnie kanału tylko do konfiguracji przed pełnym Plugin kanału podczas uruchamiania. | -`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.minHostVersion` jest wymuszane podczas instalacji i ładowania +rejestru manifestu. Nieprawidłowe wartości są odrzucane; nowsze, ale prawidłowe wartości powodują pominięcie +Plugin na starszych hostach. `openclaw.install.allowInvalidConfigRecovery` jest celowo wąskie. Nie -sprawia, że dowolnie uszkodzone konfiguracje stają się możliwe do zainstalowania. Obecnie pozwala tylko -przepływom instalacji odzyskać sprawność po określonych niepowodzeniach aktualizacji bundlowych Pluginów, takich jak -brak ścieżki bundlowego Pluginu albo nieaktualny wpis `channels.` dla tego samego -bundlowego Pluginu. Niezwiązane błędy konfiguracji nadal blokują instalację i kierują operatorów +sprawia, że dowolnie uszkodzone konfiguracje stają się możliwe do zainstalowania. Obecnie pozwala jedynie przepływom instalacji +odzyskać działanie po określonych nieaktualnych błędach aktualizacji bundlowanego Plugin, takich jak +brakująca ścieżka bundlowanego Plugin lub nieaktualny wpis `channels.` dla tego samego +bundlowanego Plugin. Niepowią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 { @@ -513,12 +535,12 @@ sprawdzającego: } ``` -Używaj tego, gdy przepływy konfiguracji, doctor albo configured-state potrzebują prostego -sprawdzenia auth typu tak/nie, zanim załaduje się pełny Plugin kanału. Docelowy eksport powinien być małą -funkcją, która odczytuje wyłącznie stan trwały; nie kieruj tego przez pełny barrel środowiska uruchomieniowego kanału. +Używaj tego, gdy przepływy konfiguracji, doctor lub configured-state potrzebują lekkiego sprawdzenia auth +typu tak/nie przed załadowaniem pełnego Plugin kanału. Docelowy eksport powinien być małą +funkcją, która odczytuje wyłącznie stan utrwalony; nie kieruj go przez pełny barrel runtime kanału. -`openclaw.channel.configuredState` ma taki sam kształt dla lekkich sprawdzeń -konfiguracji opartych wyłącznie na env: +`openclaw.channel.configuredState` ma ten sam kształt dla lekkich sprawdzeń +skonfigurowania opartych wyłącznie na env: ```json { @@ -534,56 +556,57 @@ konfiguracji opartych wyłącznie na env: } ``` -Używaj tego, gdy kanał może odpowiedzieć o stanie konfiguracji na podstawie env lub innych małych -wejść niezwiązanych ze środowiskiem uruchomieniowym. Jeśli sprawdzenie wymaga pełnego rozstrzygnięcia konfiguracji albo rzeczywistego -środowiska uruchomieniowego 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ść nieruntime. Jeśli sprawdzenie wymaga pełnego rozstrzygnięcia konfiguracji lub rzeczywistego +runtime kanału, zachowaj tę logikę w hooku Plugin `config.hasConfiguredState`. -## Wymagania schematu JSON +## Wymagania JSON Schema -- **Każdy Plugin musi dostarczać schemat JSON**, nawet jeśli nie przyjmuje żadnej konfiguracji. -- Pusty schemat jest akceptowalny (na przykład `{ "type": "object", "additionalProperties": false }`). -- Schematy są walidowane podczas odczytu/zapisu konfiguracji, a nie w czasie działania. +- **Każdy Plugin musi dostarczać JSON Schema**, nawet jeśli nie przyjmuje żadnej konfiguracji. +- Pusty schemat jest dopuszczalny (na przykład `{ "type": "object", "additionalProperties": false }`). +- Schematy są walidowane podczas odczytu/zapisu konfiguracji, a nie w czasie wykonywania. ## Zachowanie walidacji -- Nieznane klucze `channels.*` są **błędami**, chyba że identyfikator kanału jest zadeklarowany przez - manifest Pluginu. +- Nieznane klucze `channels.*` to **błędy**, chyba że identyfikator kanału został zadeklarowany przez + manifest Plugin. - `plugins.entries.`, `plugins.allow`, `plugins.deny` i `plugins.slots.*` - muszą odwoływać się do **wykrywalnych** identyfikatorów Pluginów. Nieznane identyfikatory są **błędami**. + muszą odwoływać się do **wykrywalnych** identyfikatorów Plugin. Nieznane identyfikatory to **błędy**. - Jeśli Plugin jest zainstalowany, ale ma uszkodzony lub brakujący manifest albo schemat, - walidacja kończy się niepowodzeniem, a Doctor zgłasza błąd Pluginu. -- Jeśli konfiguracja Pluginu istnieje, ale Plugin jest **wyłączony**, konfiguracja jest zachowywana i - w Doctor + logach wyświetlane jest **ostrzeżenie**. + walidacja kończy się niepowodzeniem, a Doctor zgłasza błąd Plugin. +- Jeśli konfiguracja Plugin istnieje, ale Plugin jest **wyłączony**, konfiguracja jest zachowywana i + pojawia się **ostrzeżenie** w Doctor + logach. -Pełny schemat `plugins.*` znajdziesz tutaj: [Informacje o konfiguracji](/pl/gateway/configuration). +Pełny schemat `plugins.*` znajdziesz w [Configuration reference](/pl/gateway/configuration). ## Uwagi -- Manifest jest **wymagany dla natywnych Pluginów OpenClaw**, w tym dla ładowania z lokalnego systemu plików. -- Środowisko uruchomieniowe nadal ładuje moduł Pluginu osobno; manifest służy tylko do +- Manifest jest **wymagany dla natywnych Plugin OpenClaw**, w tym dla ładowań z lokalnego systemu plików. +- Runtime nadal ładuje moduł Plugin osobno; manifest służy wyłącznie do wykrywania + walidacji. - Natywne manifesty są parsowane przy użyciu JSON5, więc komentarze, końcowe przecinki i - klucze bez cudzysłowów są akceptowane, o ile wartość końcowa nadal jest obiektem. + klucze bez cudzysłowów są akceptowane, o ile końcowa wartość nadal jest obiektem. - Loader manifestu odczytuje tylko 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 auth dostawców, które nie powinny uruchamiać środowiska uruchomieniowego Pluginu tylko po to, by sprawdzić nazwy env. -- `providerAuthAliases` pozwala wariantom dostawców ponownie używać zmiennych env auth, - profili auth, auth opartych na konfiguracji oraz wyboru onboardingu klucza API innego dostawcy - bez kodowania tej relacji na sztywno w core. + tutaj niestandardowych kluczy najwyższego poziomu. +- `providerAuthEnvVars` to lekka ścieżka metadanych dla sprawdzeń auth, walidacji znaczników env + i podobnych powierzchni auth dostawcy, które nie powinny uruchamiać runtime Plugin + tylko po to, by sprawdzić nazwy env. +- `providerAuthAliases` pozwala wariantom dostawców ponownie używać zmiennych env auth innego dostawcy, + profili auth, auth opartego na konfiguracji i wyboru onboardingu klucza API + bez hardkodowania tej relacji w core. - `channelEnvVars` to lekka ścieżka metadanych dla fallbacku shell-env, promptów konfiguracji - i podobnych powierzchni kanałów, które nie powinny uruchamiać środowiska uruchomieniowego Pluginu + i podobnych powierzchni kanału, które nie powinny uruchamiać runtime Plugin tylko po to, by sprawdzić nazwy env. - `providerAuthChoices` to lekka ścieżka metadanych dla selektorów wyboru auth, rozstrzygania `--auth-choice`, mapowania preferowanego dostawcy i prostej rejestracji flag CLI - onboardingu przed załadowaniem środowiska uruchomieniowego dostawcy. W przypadku 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.*`. + onboardingu przed załadowaniem runtime dostawcy. Metadane kreatora runtime, + które wymagają kodu dostawcy, opisano w + [Provider runtime hooks](/pl/plugins/architecture#provider-runtime-hooks). +- Wyłączne rodzaje Plugin są wybierane przez `plugins.slots.*`. - `kind: "memory"` jest wybierany przez `plugins.slots.memory`. - `kind: "context-engine"` jest wybierany przez `plugins.slots.contextEngine` (domyślnie: wbudowany `legacy`). -- `channels`, `providers`, `cliBackends` i `skills` można pominąć, jeśli +- `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 allowlist menedżera pakietów (na przykład pnpm `allow-build-scripts` @@ -591,6 +614,6 @@ Pełny schemat `plugins.*` znajdziesz tutaj: [Informacje o konfiguracji](/pl/gat ## Powiązane -- [Tworzenie Pluginów](/pl/plugins/building-plugins) — pierwsze kroki z Pluginami -- [Architektura Pluginów](/pl/plugins/architecture) — architektura wewnętrzna -- [Przegląd SDK](/pl/plugins/sdk-overview) — dokumentacja Plugin SDK +- [Building Plugins](/pl/plugins/building-plugins) — pierwsze kroki z Plugin +- [Plugin Architecture](/pl/plugins/architecture) — architektura wewnętrzna +- [SDK Overview](/pl/plugins/sdk-overview) — opis Plugin SDK diff --git a/docs/pl/plugins/sdk-channel-plugins.md b/docs/pl/plugins/sdk-channel-plugins.md index 2f5cf9e4f..62c6ac4ca 100644 --- a/docs/pl/plugins/sdk-channel-plugins.md +++ b/docs/pl/plugins/sdk-channel-plugins.md @@ -1,105 +1,89 @@ --- read_when: - - Tworzysz nowy plugin kanału wiadomości - - Chcesz połączyć OpenClaw z platformą komunikacyjną - - Musisz zrozumieć powierzchnię adaptera ChannelPlugin + - Tworzysz nowy Plugin kanału wiadomości. + - Chcesz połączyć OpenClaw z platformą komunikacyjną. + - Musisz zrozumieć powierzchnię adaptera ChannelPlugin. sidebarTitle: Channel Plugins -summary: Przewodnik krok po kroku po tworzeniu pluginu kanału wiadomości dla OpenClaw -title: Tworzenie pluginów kanałów +summary: Przewodnik krok po kroku dotyczący tworzenia Pluginu kanału wiadomości dla OpenClaw +title: Tworzenie Pluginów kanałów x-i18n: - generated_at: "2026-04-11T02:46:34Z" + generated_at: "2026-04-15T09:51:14Z" model: gpt-5.4 provider: openai - source_hash: 8a026e924f9ae8a3ddd46287674443bcfccb0247be504261522b078e1f440aef + source_hash: a7f4c746fe3163a8880e14c433f4db4a1475535d91716a53fb879551d8d62f65 source_path: plugins/sdk-channel-plugins.md workflow: 15 --- -# Tworzenie pluginów kanałów +# Tworzenie Pluginów kanałów -Ten przewodnik przeprowadza przez tworzenie pluginu kanału, który łączy OpenClaw z -platformą komunikacyjną. Na końcu będziesz mieć działający kanał z zabezpieczeniami DM, -parowaniem, wątkowaniem odpowiedzi i wiadomościami wychodzącymi. +Ten przewodnik krok po kroku pokazuje, jak zbudować Plugin kanału, który łączy OpenClaw z platformą komunikacyjną. Po jego ukończeniu będziesz mieć działający kanał z zabezpieczeniami DM, parowaniem, wątkowaniem odpowiedzi oraz wiadomościami wychodzącymi. - Jeśli nie utworzono jeszcze żadnego pluginu OpenClaw, - najpierw przeczytaj - [Pierwsze kroki](/pl/plugins/building-plugins), aby poznać podstawową - strukturę pakietu i konfigurację manifestu. + Jeśli nie zbudowano jeszcze żadnego Pluginu OpenClaw, najpierw przeczytaj + [Pierwsze kroki](/pl/plugins/building-plugins), aby poznać podstawową strukturę + pakietu i konfigurację manifestu. -## Jak działają pluginy kanałów +## Jak działają Pluginy kanałów -Pluginy kanałów nie potrzebują własnych narzędzi send/edit/react. OpenClaw utrzymuje jedno -wspólne narzędzie `message` w rdzeniu. Twój plugin odpowiada za: +Pluginy kanałów nie potrzebują własnych narzędzi do wysyłania/edytowania/reakcji. OpenClaw utrzymuje jedno współdzielone narzędzie `message` w rdzeniu. Twój Plugin odpowiada za: -- **Konfigurację** — rozstrzyganie kont i kreator konfiguracji -- **Bezpieczeństwo** — politykę DM i listy dozwolonych -- **Parowanie** — przepływ zatwierdzania DM -- **Gramatykę sesji** — sposób, w jaki identyfikatory konwersacji specyficzne dla dostawcy mapują się na czaty bazowe, identyfikatory wątków i zapasowe elementy nadrzędne -- **Ruch wychodzący** — wysyłanie tekstu, multimediów i ankiet na platformę -- **Wątkowanie** — sposób wątkowania odpowiedzi +- **Config** — rozpoznawanie kont i kreator konfiguracji +- **Security** — politykę DM i listy dozwolonych +- **Pairing** — przepływ zatwierdzania DM +- **Session grammar** — sposób, w jaki identyfikatory rozmów specyficzne dla dostawcy mapują się na bazowe czaty, identyfikatory wątków i rezerwy nadrzędne +- **Outbound** — wysyłanie tekstu, multimediów i ankiet na platformę +- **Threading** — sposób wątkowania odpowiedzi -Rdzeń odpowiada za wspólne narzędzie wiadomości, łączenie monitów, zewnętrzny kształt klucza sesji, -ogólne księgowanie `:thread:` i wysyłkę. +Rdzeń odpowiada za współdzielone narzędzie wiadomości, połączenia z promptami, zewnętrzny kształt klucza sesji, ogólne księgowanie `:thread:` oraz dyspozycję. -Jeśli twoja platforma przechowuje dodatkowy zakres w identyfikatorach konwersacji, zachowaj to parsowanie -w pluginie za pomocą `messaging.resolveSessionConversation(...)`. To jest -kanoniczny hook do mapowania `rawId` na bazowy identyfikator konwersacji, opcjonalny identyfikator wątku, -jawny `baseConversationId` i dowolne `parentConversationCandidates`. -Gdy zwracasz `parentConversationCandidates`, zachowaj ich kolejność od -najwęższego elementu nadrzędnego do najszerszej/bazowej konwersacji. +Jeśli Twój kanał dodaje parametry narzędzia wiadomości, które przenoszą źródła multimediów, ujawnij nazwy tych parametrów przez `describeMessageTool(...).mediaSourceParams`. Rdzeń używa tej jawnej listy do normalizacji ścieżek w sandboxie i polityki dostępu do multimediów wychodzących, więc Pluginy nie potrzebują wyjątków specyficznych dla dostawcy we współdzielonym rdzeniu dla parametrów awatara, załączników lub obrazów okładki. +Preferuj zwracanie mapy kluczowanej akcjami, takiej jak +`{ "set-profile": ["avatarUrl", "avatarPath"] }`, aby niezwiązane akcje nie dziedziczyły argumentów multimedialnych innej akcji. Płaska tablica nadal działa dla parametrów, które celowo są współdzielone przez każdą ujawnioną akcję. -Bundlowane pluginy, które potrzebują tego samego parsowania przed uruchomieniem rejestru kanałów, -mogą też udostępniać plik najwyższego poziomu `session-key-api.ts` z pasującym -eksportem `resolveSessionConversation(...)`. Rdzeń używa tej bezpiecznej dla bootstrapu powierzchni -tylko wtedy, gdy rejestr pluginów środowiska uruchomieniowego nie jest jeszcze dostępny. +Jeśli Twoja platforma przechowuje dodatkowy zakres w identyfikatorach rozmów, pozostaw to parsowanie w Pluginie za pomocą `messaging.resolveSessionConversation(...)`. To kanoniczny hak do mapowania `rawId` na bazowy identyfikator rozmowy, opcjonalny identyfikator wątku, jawne `baseConversationId` oraz wszelkie `parentConversationCandidates`. +Gdy zwracasz `parentConversationCandidates`, zachowaj ich kolejność od najwęższego rodzica do najszerszej/bazowej rozmowy. -`messaging.resolveParentConversationCandidates(...)` pozostaje dostępne jako -starszy awaryjny mechanizm zgodności, gdy plugin potrzebuje tylko zapasowych elementów nadrzędnych -na bazie ogólnego/surowego identyfikatora. Jeśli istnieją oba hooki, rdzeń używa najpierw -`resolveSessionConversation(...).parentConversationCandidates`, a do -`resolveParentConversationCandidates(...)` wraca tylko wtedy, gdy hook kanoniczny -ich nie zwraca. +Bundlowane Pluginy, które potrzebują tego samego parsowania przed uruchomieniem rejestru kanałów, mogą też udostępniać plik najwyższego poziomu `session-key-api.ts` z pasującym eksportem `resolveSessionConversation(...)`. Rdzeń używa tej bezpiecznej dla bootstrapu powierzchni tylko wtedy, gdy rejestr Pluginów runtime nie jest jeszcze dostępny. + +`messaging.resolveParentConversationCandidates(...)` pozostaje dostępne jako starsza rezerwa zgodności, gdy Plugin potrzebuje jedynie rezerw nadrzędnych ponad ogólnym/surowym identyfikatorem. Jeśli istnieją oba haki, rdzeń najpierw używa `resolveSessionConversation(...).parentConversationCandidates`, a do `resolveParentConversationCandidates(...)` wraca tylko wtedy, gdy kanoniczny hak ich nie zwraca. ## Zatwierdzenia i możliwości kanału -Większość pluginów kanałów nie potrzebuje kodu specyficznego dla zatwierdzeń. +Większość Pluginów kanałów nie potrzebuje kodu specyficznego dla zatwierdzeń. -- Rdzeń odpowiada za `/approve` w tym samym czacie, wspólne ładunki przycisków zatwierdzania oraz ogólne dostarczanie awaryjne. -- Gdy kanał potrzebuje zachowania specyficznego dla zatwierdzeń, preferuj pojedynczy obiekt `approvalCapability` w pluginie kanału. -- `ChannelPlugin.approvals` zostało usunięte. Fakty dotyczące dostarczania/renderowania/natywności/uwierzytelniania zatwierdzeń umieszczaj w `approvalCapability`. -- `plugin.auth` służy tylko do login/logout; rdzeń nie odczytuje już hooków uwierzytelniania zatwierdzeń z tego obiektu. -- `approvalCapability.authorizeActorAction` oraz `approvalCapability.getActionAvailabilityState` to kanoniczna powierzchnia dla uwierzytelniania zatwierdzeń. -- Użyj `approvalCapability.getActionAvailabilityState` dla dostępności uwierzytelniania zatwierdzeń w tym samym czacie. -- Jeśli kanał udostępnia natywne zatwierdzanie exec, użyj `approvalCapability.getExecInitiatingSurfaceState` dla stanu powierzchni inicjującej/klienta natywnego, gdy różni się od uwierzytelniania zatwierdzeń w tym samym czacie. Rdzeń używa tego hooka specyficznego dla exec, aby odróżnić `enabled` od `disabled`, zdecydować, czy kanał inicjujący obsługuje natywne zatwierdzenia exec, i uwzględnić kanał w instrukcjach awaryjnych dla klienta natywnego. `createApproverRestrictedNativeApprovalCapability(...)` wypełnia to dla typowego przypadku. -- Użyj `outbound.shouldSuppressLocalPayloadPrompt` lub `outbound.beforeDeliverPayload` dla zachowań cyklu życia ładunku specyficznych dla kanału, takich jak ukrywanie zduplikowanych lokalnych monitów zatwierdzania lub wysyłanie wskaźników pisania przed dostarczeniem. -- Używaj `approvalCapability.delivery` tylko do natywnego routingu zatwierdzeń lub tłumienia dostarczania awaryjnego. -- Używaj `approvalCapability.nativeRuntime` dla natywnych faktów zatwierdzania należących do kanału. Utrzymuj je w trybie lazy na gorących entrypointach kanału za pomocą `createLazyChannelApprovalNativeRuntimeAdapter(...)`, które może importować moduł środowiska uruchomieniowego na żądanie, jednocześnie pozwalając rdzeniowi złożyć cykl życia zatwierdzania. -- Używaj `approvalCapability.render` tylko wtedy, gdy kanał rzeczywiście potrzebuje własnych ładunków zatwierdzania zamiast wspólnego renderera. -- Użyj `approvalCapability.describeExecApprovalSetup`, gdy kanał chce, aby odpowiedź dla ścieżki wyłączonej wyjaśniała dokładnie, jakie przełączniki konfiguracji są potrzebne do włączenia natywnych zatwierdzeń exec. Hook otrzymuje `{ channel, channelLabel, accountId }`; kanały z nazwanymi kontami powinny renderować ścieżki ograniczone do konta, takie jak `channels..accounts..execApprovals.*`, zamiast domyślnych ścieżek najwyższego poziomu. -- Jeśli kanał potrafi wywnioskować stabilne tożsamości DM podobne do właściciela z istniejącej konfiguracji, użyj `createResolvedApproverActionAuthAdapter` z `openclaw/plugin-sdk/approval-runtime`, aby ograniczyć `/approve` w tym samym czacie bez dodawania logiki specyficznej dla zatwierdzeń do rdzenia. -- Jeśli kanał potrzebuje natywnego dostarczania zatwierdzeń, utrzymuj kod kanału skupiony na normalizacji celu oraz faktach dotyczących transportu/prezentacji. Użyj `createChannelExecApprovalProfile`, `createChannelNativeOriginTargetResolver`, `createChannelApproverDmTargetResolver` i `createApproverRestrictedNativeApprovalCapability` z `openclaw/plugin-sdk/approval-runtime`. Fakty specyficzne dla kanału umieść za `approvalCapability.nativeRuntime`, najlepiej przez `createChannelApprovalNativeRuntimeAdapter(...)` lub `createLazyChannelApprovalNativeRuntimeAdapter(...)`, aby rdzeń mógł złożyć obsługę i przejąć filtrowanie żądań, routing, deduplikację, wygasanie, subskrypcję bramy oraz komunikaty „przekierowano gdzie indziej”. `nativeRuntime` jest podzielone na kilka mniejszych powierzchni: +- Rdzeń odpowiada za `/approve` w tym samym czacie, współdzielone ładunki przycisków zatwierdzania oraz ogólne dostarczanie rezerwowe. +- Preferuj pojedynczy obiekt `approvalCapability` w Pluginie kanału, gdy kanał potrzebuje zachowania specyficznego dla zatwierdzeń. +- `ChannelPlugin.approvals` zostało usunięte. Umieść fakty dotyczące dostarczania/natywnego/renderowania/uwierzytelniania zatwierdzeń w `approvalCapability`. +- `plugin.auth` służy tylko do logowania/wylogowania; rdzeń nie odczytuje już haków uwierzytelniania zatwierdzeń z tego obiektu. +- `approvalCapability.authorizeActorAction` i `approvalCapability.getActionAvailabilityState` to kanoniczna powierzchnia uwierzytelniania zatwierdzeń. +- Używaj `approvalCapability.getActionAvailabilityState` dla dostępności uwierzytelniania zatwierdzeń w tym samym czacie. +- Jeśli Twój kanał udostępnia natywne zatwierdzenia exec, użyj `approvalCapability.getExecInitiatingSurfaceState` dla stanu powierzchni inicjującej/klienta natywnego, gdy różni się on od uwierzytelniania zatwierdzeń w tym samym czacie. Rdzeń używa tego haka specyficznego dla exec, aby rozróżnić `enabled` i `disabled`, zdecydować, czy kanał inicjujący obsługuje natywne zatwierdzenia exec, oraz uwzględnić ten kanał w wskazówkach dotyczących rezerwy klienta natywnego. `createApproverRestrictedNativeApprovalCapability(...)` wypełnia to dla typowego przypadku. +- Używaj `outbound.shouldSuppressLocalPayloadPrompt` lub `outbound.beforeDeliverPayload` do zachowań cyklu życia ładunku specyficznych dla kanału, takich jak ukrywanie zduplikowanych lokalnych promptów zatwierdzeń lub wysyłanie wskaźników pisania przed dostarczeniem. +- Używaj `approvalCapability.delivery` tylko do natywnego routingu zatwierdzeń lub wyciszania rezerwy. +- Używaj `approvalCapability.nativeRuntime` dla faktów natywnych zatwierdzeń należących do kanału. Zachowaj leniwe ładowanie na gorących punktach wejścia kanału za pomocą `createLazyChannelApprovalNativeRuntimeAdapter(...)`, które może importować moduł runtime na żądanie, a jednocześnie pozwala rdzeniowi składać cykl życia zatwierdzeń. +- Używaj `approvalCapability.render` tylko wtedy, gdy kanał naprawdę potrzebuje niestandardowych ładunków zatwierdzeń zamiast współdzielonego renderera. +- Używaj `approvalCapability.describeExecApprovalSetup`, gdy kanał chce, aby odpowiedź dla ścieżki wyłączonej wyjaśniała dokładne pokrętła konfiguracji potrzebne do włączenia natywnych zatwierdzeń exec. Hak otrzymuje `{ channel, channelLabel, accountId }`; kanały z nazwanymi kontami powinny renderować ścieżki z zakresem konta, takie jak `channels..accounts..execApprovals.*`, zamiast domyślnych ścieżek najwyższego poziomu. +- Jeśli kanał może wnioskować o stabilnych tożsamościach DM podobnych do właściciela na podstawie istniejącej konfiguracji, użyj `createResolvedApproverActionAuthAdapter` z `openclaw/plugin-sdk/approval-runtime`, aby ograniczyć `/approve` w tym samym czacie bez dodawania logiki specyficznej dla zatwierdzeń do rdzenia. +- Jeśli kanał potrzebuje natywnego dostarczania zatwierdzeń, skup kod kanału na normalizacji celu oraz faktach transportu/prezentacji. Użyj `createChannelExecApprovalProfile`, `createChannelNativeOriginTargetResolver`, `createChannelApproverDmTargetResolver` i `createApproverRestrictedNativeApprovalCapability` z `openclaw/plugin-sdk/approval-runtime`. Umieść fakty specyficzne dla kanału za `approvalCapability.nativeRuntime`, najlepiej przez `createChannelApprovalNativeRuntimeAdapter(...)` lub `createLazyChannelApprovalNativeRuntimeAdapter(...)`, aby rdzeń mógł złożyć obsługę i przejąć filtrowanie żądań, routing, usuwanie duplikatów, wygaśnięcie, subskrypcję Gateway oraz powiadomienia o przekierowaniu. `nativeRuntime` jest podzielone na kilka mniejszych powierzchni: - `availability` — czy konto jest skonfigurowane i czy żądanie powinno zostać obsłużone -- `presentation` — mapowanie wspólnego modelu widoku zatwierdzenia na oczekujące/rozstrzygnięte/wygasłe ładunki natywne lub działania końcowe -- `transport` — przygotowanie celów oraz wysyłanie/aktualizowanie/usuwanie natywnych wiadomości zatwierdzania -- `interactions` — opcjonalne hooki bind/unbind/clear-action dla natywnych przycisków lub reakcji -- `observe` — opcjonalne hooki diagnostyki dostarczania -- Jeśli kanał potrzebuje obiektów należących do środowiska uruchomieniowego, takich jak klient, token, aplikacja Bolt lub odbiornik webhooka, zarejestruj je przez `openclaw/plugin-sdk/channel-runtime-context`. Ogólny rejestr runtime-context pozwala rdzeniowi uruchamiać handlery oparte na możliwościach na podstawie stanu startowego kanału bez dodawania kodu klejącego specyficznego dla zatwierdzeń. -- Sięgaj po niższopoziomowe `createChannelApprovalHandler` lub `createChannelNativeApprovalRuntime` tylko wtedy, gdy powierzchnia oparta na możliwościach nie jest jeszcze wystarczająco ekspresyjna. -- Kanały z natywnymi zatwierdzeniami muszą przekazywać przez te helpery zarówno `accountId`, jak i `approvalKind`. `accountId` utrzymuje politykę zatwierdzeń dla wielu kont w zakresie właściwego konta bota, a `approvalKind` utrzymuje zachowanie zatwierdzeń exec vs plugin dostępne dla kanału bez zakodowanych na sztywno gałęzi w rdzeniu. -- Rdzeń odpowiada teraz także za komunikaty o przekierowaniu zatwierdzeń. Pluginy kanałów nie powinny wysyłać własnych wiadomości uzupełniających typu „zatwierdzenie trafiło do DM / innego kanału” z `createChannelNativeApprovalRuntime`; zamiast tego udostępnij poprawny routing pochodzenia + DM zatwierdzającego przez wspólne helpery możliwości zatwierdzania i pozwól rdzeniowi agregować rzeczywiste dostarczenia przed opublikowaniem ewentualnego komunikatu z powrotem do czatu inicjującego. -- Zachowuj rodzaj dostarczonego identyfikatora zatwierdzenia od początku do końca. Klienci natywni nie powinni - zgadywać ani przepisywać routingu zatwierdzeń exec vs plugin na podstawie lokalnego stanu kanału. -- Różne rodzaje zatwierdzeń mogą celowo udostępniać różne powierzchnie natywne. - Bieżące przykłady bundlowane: - - Slack zachowuje dostępny natywny routing zatwierdzeń zarówno dla identyfikatorów exec, jak i plugin. - - Matrix utrzymuje ten sam natywny routing DM/kanał i UX reakcji dla zatwierdzeń exec - i plugin, jednocześnie pozwalając, by uwierzytelnianie różniło się zależnie od rodzaju zatwierdzenia. -- `createApproverRestrictedNativeApprovalAdapter` nadal istnieje jako opakowanie zgodności, ale nowy kod powinien preferować konstruktor możliwości i udostępniać `approvalCapability` w pluginie. +- `presentation` — mapowanie współdzielonego modelu widoku zatwierdzenia na oczekujące/rozwiązane/wygasłe ładunki natywne lub działania końcowe +- `transport` — przygotowanie celów oraz wysyłanie/aktualizowanie/usuwanie natywnych wiadomości zatwierdzeń +- `interactions` — opcjonalne haki bind/unbind/clear-action dla natywnych przycisków lub reakcji +- `observe` — opcjonalne haki diagnostyki dostarczania +- Jeśli kanał potrzebuje obiektów należących do runtime, takich jak klient, token, aplikacja Bolt lub odbiornik Webhook, zarejestruj je przez `openclaw/plugin-sdk/channel-runtime-context`. Ogólny rejestr kontekstu runtime pozwala rdzeniowi bootstrapować handlery sterowane możliwościami na podstawie stanu uruchomienia kanału bez dodawania kleju opakowującego specyficznego dla zatwierdzeń. +- Sięgaj po niższopoziomowe `createChannelApprovalHandler` lub `createChannelNativeApprovalRuntime` tylko wtedy, gdy powierzchnia sterowana możliwościami nie jest jeszcze wystarczająco ekspresyjna. +- Kanały natywnych zatwierdzeń muszą routować zarówno `accountId`, jak i `approvalKind` przez te helpery. `accountId` utrzymuje politykę zatwierdzeń dla wielu kont w zakresie właściwego konta bota, a `approvalKind` zachowuje dla kanału dostępność zachowania zatwierdzeń exec vs Plugin bez zakodowanych na sztywno gałęzi w rdzeniu. +- Rdzeń odpowiada teraz także za powiadomienia o przekierowaniu zatwierdzeń. Pluginy kanałów nie powinny wysyłać własnych wiadomości uzupełniających typu „zatwierdzenie trafiło do DM / innego kanału” z `createChannelNativeApprovalRuntime`; zamiast tego ujawnij dokładny routing źródła i DM zatwierdzającego przez współdzielone helpery możliwości zatwierdzeń i pozwól rdzeniowi agregować rzeczywiste dostarczenia przed opublikowaniem powiadomienia z powrotem do czatu inicjującego. +- Zachowuj rodzaj identyfikatora dostarczonego zatwierdzenia od początku do końca. Klienci natywni nie powinni zgadywać ani przepisywać routingu zatwierdzeń exec vs Plugin na podstawie lokalnego stanu kanału. +- Różne rodzaje zatwierdzeń mogą celowo ujawniać różne powierzchnie natywne. + Obecne przykłady bundlowane: + - Slack zachowuje dostępny natywny routing zatwierdzeń zarówno dla identyfikatorów exec, jak i Plugin. + - Matrix zachowuje ten sam natywny routing DM/kanału i UX reakcji dla zatwierdzeń exec i Plugin, nadal pozwalając, by uwierzytelnianie różniło się zależnie od rodzaju zatwierdzenia. +- `createApproverRestrictedNativeApprovalAdapter` nadal istnieje jako opakowanie zgodności, ale nowy kod powinien preferować kreator możliwości i ujawniać `approvalCapability` w Pluginie. -Dla gorących entrypointów kanału preferuj węższe podścieżki środowiska uruchomieniowego, gdy potrzebujesz tylko -jednej części tej rodziny: +Dla gorących punktów wejścia kanału preferuj węższe podścieżki runtime, gdy potrzebujesz tylko jednej części tej rodziny: - `openclaw/plugin-sdk/approval-auth-runtime` - `openclaw/plugin-sdk/approval-client-runtime` @@ -116,94 +100,86 @@ Podobnie preferuj `openclaw/plugin-sdk/setup-runtime`, `openclaw/plugin-sdk/reply-runtime`, `openclaw/plugin-sdk/reply-dispatch-runtime`, `openclaw/plugin-sdk/reply-reference` oraz -`openclaw/plugin-sdk/reply-chunking`, gdy nie potrzebujesz szerszej -powierzchni parasolowej. +`openclaw/plugin-sdk/reply-chunking`, gdy nie potrzebujesz szerszej powierzchni parasolowej. -Konkretnie dla konfiguracji: +W przypadku konfiguracji w szczególności: -- `openclaw/plugin-sdk/setup-runtime` obejmuje bezpieczne dla środowiska uruchomieniowego helpery konfiguracji: - bezpieczne przy imporcie adaptery łatania konfiguracji (`createPatchedAccountSetupAdapter`, +- `openclaw/plugin-sdk/setup-runtime` obejmuje bezpieczne dla runtime helpery konfiguracji: + bezpieczne dla importu adaptery łatania konfiguracji (`createPatchedAccountSetupAdapter`, `createEnvPatchedAccountSetupAdapter`, - `createSetupInputPresenceValidator`), dane wyjściowe notatek lookup, + `createSetupInputPresenceValidator`), wyjście notatek wyszukiwania, `promptResolvedAllowFrom`, `splitSetupEntries` oraz delegowane - konstruktory proxy konfiguracji -- `openclaw/plugin-sdk/setup-adapter-runtime` to wąska, świadoma środowiska surface adaptera - dla `createEnvPatchedAccountSetupAdapter` -- `openclaw/plugin-sdk/channel-setup` obejmuje konstruktory konfiguracji z opcjonalną instalacją + kreatory proxy konfiguracji +- `openclaw/plugin-sdk/setup-adapter-runtime` to wąska, świadoma środowiska powierzchnia + adaptera dla `createEnvPatchedAccountSetupAdapter` +- `openclaw/plugin-sdk/channel-setup` obejmuje kreatory konfiguracji opcjonalnej instalacji oraz kilka prymitywów bezpiecznych dla konfiguracji: `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, -Jeśli twój kanał obsługuje konfigurację lub uwierzytelnianie sterowane przez env, a ogólne przepływy uruchamiania/konfiguracji -powinny znać te nazwy zmiennych env przed załadowaniem środowiska uruchomieniowego, zadeklaruj je w -manifeście pluginu za pomocą `channelEnvVars`. Zachowaj runtime `envVars` kanału lub lokalne -stałe wyłącznie dla tekstów operatora. +Jeśli Twój kanał obsługuje konfigurację lub uwierzytelnianie sterowane środowiskiem i ogólne przepływy uruchamiania/konfiguracji powinny znać te nazwy zmiennych środowiskowych przed załadowaniem runtime, zadeklaruj je w manifeście Pluginu za pomocą `channelEnvVars`. Zachowaj runtime `envVars` kanału lub lokalne stałe tylko dla kopii skierowanej do operatora. `createOptionalChannelSetupWizard`, `DEFAULT_ACCOUNT_ID`, `createTopLevelChannelDmPolicy`, `setSetupChannelEnabled` oraz `splitSetupEntries` -- używaj szerszej powierzchni `openclaw/plugin-sdk/setup` tylko wtedy, gdy potrzebujesz także - cięższych wspólnych helperów konfiguracji/ustawień, takich jak +- używaj szerszej powierzchni `openclaw/plugin-sdk/setup` tylko wtedy, gdy potrzebujesz również + cięższych współdzielonych helperów konfiguracji/ustawień, takich jak `moveSingleAccountChannelSectionToDefaultAccount(...)` -Jeśli kanał chce tylko reklamować „najpierw zainstaluj ten plugin” w powierzchniach konfiguracji, -preferuj `createOptionalChannelSetupSurface(...)`. Wygenerowany -adapter/kreator domyślnie blokuje zapis konfiguracji i finalizację, a także ponownie używa -tego samego komunikatu o wymaganej instalacji w walidacji, finalizacji i tekstach z linkiem do dokumentacji. +Jeśli Twój kanał chce jedynie reklamować „najpierw zainstaluj ten Plugin” w powierzchniach konfiguracji, preferuj `createOptionalChannelSetupSurface(...)`. Wygenerowany adapter/kreator domyślnie odmawia zapisów konfiguracji i finalizacji oraz ponownie wykorzystuje ten sam komunikat o wymaganej instalacji w walidacji, finalizacji i treści linku do dokumentacji. -Dla innych gorących ścieżek kanału preferuj wąskie helpery zamiast szerszych starszych -powierzchni: +Dla innych gorących ścieżek kanału preferuj wąskie helpery zamiast szerszych starszych powierzchni: - `openclaw/plugin-sdk/account-core`, `openclaw/plugin-sdk/account-id`, `openclaw/plugin-sdk/account-resolution` oraz `openclaw/plugin-sdk/account-helpers` dla konfiguracji wielu kont i - awaryjnego powrotu do konta domyślnego + rezerwy konta domyślnego - `openclaw/plugin-sdk/inbound-envelope` oraz - `openclaw/plugin-sdk/inbound-reply-dispatch` dla routingu/koperty wejściowej i - łączenia zapisu z wysyłką -- `openclaw/plugin-sdk/messaging-targets` do parsowania/dopasowywania celów + `openclaw/plugin-sdk/inbound-reply-dispatch` dla routingu/koperty wejściowej oraz + połączeń rejestrowania i dyspozycji +- `openclaw/plugin-sdk/messaging-targets` dla parsowania/dopasowywania celów - `openclaw/plugin-sdk/outbound-media` oraz - `openclaw/plugin-sdk/outbound-runtime` do ładowania multimediów oraz delegatów + `openclaw/plugin-sdk/outbound-runtime` dla ładowania multimediów oraz delegatów tożsamości/wysyłania wychodzącego - `openclaw/plugin-sdk/thread-bindings-runtime` dla cyklu życia powiązań wątków i rejestracji adapterów - `openclaw/plugin-sdk/agent-media-payload` tylko wtedy, gdy nadal wymagany jest - starszy układ pól ładunku agenta/multimediów -- `openclaw/plugin-sdk/telegram-command-config` do normalizacji niestandardowych poleceń Telegram, - walidacji duplikatów/konfliktów oraz stabilnego awaryjnie kontraktu konfiguracji poleceń + starszy układ pól ładunku agent/media +- `openclaw/plugin-sdk/telegram-command-config` dla normalizacji niestandardowych komend Telegram, + walidacji duplikatów/konfliktów oraz stabilnego dla rezerw kontraktu konfiguracji komend -Kanały wyłącznie uwierzytelniające zwykle mogą zatrzymać się na ścieżce domyślnej: rdzeń obsługuje zatwierdzenia, a plugin jedynie udostępnia możliwości outbound/auth. Kanały z natywnymi zatwierdzeniami, takie jak Matrix, Slack, Telegram i niestandardowe transporty czatu, powinny używać wspólnych helperów natywnych zamiast implementować własny cykl życia zatwierdzeń. +Kanały tylko z uwierzytelnianiem zwykle mogą zatrzymać się na ścieżce domyślnej: rdzeń obsługuje zatwierdzenia, a Plugin jedynie udostępnia możliwości outbound/auth. Kanały natywnych zatwierdzeń, takie jak Matrix, Slack, Telegram i niestandardowe transporty czatu, powinny używać współdzielonych helperów natywnych zamiast implementować własny cykl życia zatwierdzeń. -## Polityka wzmianek przychodzących +## Zasady wzmianek przychodzących -Obsługę wzmianek przychodzących utrzymuj rozdzieloną na dwie warstwy: +Obsługę wzmianek przychodzących utrzymuj w podziale na dwie warstwy: -- gromadzenie danych należące do pluginu -- współdzieloną ocenę polityki +- gromadzenie danych należące do Pluginu +- współdzielona ocena zasad Dla warstwy współdzielonej używaj `openclaw/plugin-sdk/channel-inbound`. -Dobre zastosowania dla logiki lokalnej pluginu: +Dobre dopasowanie do logiki lokalnej dla Pluginu: - wykrywanie odpowiedzi do bota -- wykrywanie cytatu bota -- sprawdzanie uczestnictwa w wątku -- wykluczenia wiadomości usługowych/systemowych -- natywne dla platformy pamięci podręczne potrzebne do potwierdzenia uczestnictwa bota +- wykrywanie cytatów bota +- sprawdzanie uczestnictwa we wątku +- wykluczanie wiadomości usługowych/systemowych +- natywne dla platformy cache potrzebne do udowodnienia uczestnictwa bota -Dobre zastosowania dla wspólnego helpera: +Dobre dopasowanie do współdzielonego helpera: - `requireMention` - jawny wynik wzmianki -- lista dozwolonych wzmianek niejawnych -- obejście dla poleceń -- końcowa decyzja o pominięciu +- lista dozwolonych niejawnych wzmianek +- obejście komend +- ostateczna decyzja o pominięciu Preferowany przepływ: -1. Oblicz lokalne fakty dotyczące wzmianki. +1. Oblicz lokalne fakty dotyczące wzmianek. 2. Przekaż te fakty do `resolveInboundMentionDecision({ facts, policy })`. -3. Użyj `decision.effectiveWasMentioned`, `decision.shouldBypassMention` i `decision.shouldSkip` w bramce wejściowej. +3. Użyj `decision.effectiveWasMentioned`, `decision.shouldBypassMention` i `decision.shouldSkip` w swojej bramce wejściowej. ```typescript import { @@ -242,8 +218,8 @@ const decision = resolveInboundMentionDecision({ if (decision.shouldSkip) return; ``` -`api.runtime.channel.mentions` udostępnia te same wspólne helpery wzmiankowania dla -bundlowanych pluginów kanałów, które już zależą od wstrzykiwania środowiska uruchomieniowego: +`api.runtime.channel.mentions` udostępnia te same współdzielone helpery wzmianek dla +bundlowanych Pluginów kanałów, które już zależą od wstrzykiwania runtime: - `buildMentionRegexes` - `matchesMentionPatterns` @@ -252,17 +228,17 @@ bundlowanych pluginów kanałów, które już zależą od wstrzykiwania środowi - `resolveInboundMentionDecision` Starsze helpery `resolveMentionGating*` pozostają w -`openclaw/plugin-sdk/channel-inbound` wyłącznie jako eksporty zgodności. Nowy kod +`openclaw/plugin-sdk/channel-inbound` jedynie jako eksporty zgodności. Nowy kod powinien używać `resolveInboundMentionDecision({ facts, policy })`. -## Instrukcja krok po kroku +## Omówienie - Utwórz standardowe pliki pluginu. Pole `channel` w `package.json` sprawia, - że jest to plugin kanału. Aby zobaczyć pełną powierzchnię metadanych pakietu, - zobacz [Konfiguracja pluginu i ustawienia](/pl/plugins/sdk-setup#openclaw-channel): + Utwórz standardowe pliki Pluginu. Pole `channel` w `package.json` + sprawia, że jest to Plugin kanału. Pełną powierzchnię metadanych pakietu + znajdziesz w [Konfiguracja i ustawienia Pluginu](/pl/plugins/sdk-setup#openclaw-channel): ```json package.json @@ -311,9 +287,9 @@ powinien używać `resolveInboundMentionDecision({ facts, policy })`. - + Interfejs `ChannelPlugin` ma wiele opcjonalnych powierzchni adapterów. Zacznij od - minimum — `id` i `setup` — a następnie dodawaj adaptery według potrzeb. + minimum — `id` i `setup` — i dodawaj adaptery w miarę potrzeb. Utwórz `src/channel.ts`: @@ -410,22 +386,22 @@ powinien używać `resolveInboundMentionDecision({ facts, policy })`. Zamiast ręcznie implementować niskopoziomowe interfejsy adapterów, przekazujesz - opcje deklaratywne, a konstruktor je składa: + deklaratywne opcje, a kreator je składa: - | Opcja | Co jest podłączane | + | Opcja | Co podłącza | | --- | --- | - | `security.dm` | Resolver bezpieczeństwa DM ograniczony do konfiguracji pól | - | `pairing.text` | Tekstowy przepływ parowania DM z wymianą kodu | - | `threading` | Resolver trybu reply-to (stały, ograniczony do konta lub niestandardowy) | - | `outbound.attachedResults` | Funkcje wysyłania, które zwracają metadane wyniku (identyfikatory wiadomości) | + | `security.dm` | Rozpoznawanie zabezpieczeń DM z zakresem z pól konfiguracji | + | `pairing.text` | Przepływ parowania DM oparty na tekście z wymianą kodów | + | `threading` | Rozpoznawanie trybu reply-to (stały, z zakresem konta lub niestandardowy) | + | `outbound.attachedResults` | Funkcje wysyłania zwracające metadane wyniku (identyfikatory wiadomości) | - Możesz także przekazać surowe obiekty adapterów zamiast opcji deklaratywnych, + Możesz również przekazać surowe obiekty adapterów zamiast opcji deklaratywnych, jeśli potrzebujesz pełnej kontroli. - + Utwórz `index.ts`: ```typescript index.ts @@ -462,20 +438,19 @@ powinien używać `resolveInboundMentionDecision({ facts, policy })`. ``` Umieść deskryptory CLI należące do kanału w `registerCliMetadata(...)`, aby OpenClaw - mógł pokazywać je w pomocy głównej bez aktywowania pełnego środowiska uruchomieniowego kanału, - podczas gdy zwykłe pełne ładowanie nadal pobiera te same deskryptory do rzeczywistej - rejestracji poleceń. Zachowaj `registerFull(...)` dla prac tylko środowiska uruchomieniowego. - Jeśli `registerFull(...)` rejestruje metody RPC bramy, użyj - prefiksu specyficznego dla pluginu. Przestrzenie nazw administracyjnych rdzenia (`config.*`, + mógł pokazywać je w pomocy głównej bez aktywowania pełnego runtime kanału, + podczas gdy zwykłe pełne ładowania nadal pobierają te same deskryptory do rzeczywistej + rejestracji komend. Zachowaj `registerFull(...)` dla pracy tylko w runtime. + Jeśli `registerFull(...)` rejestruje metody RPC Gateway, użyj prefiksu + specyficznego dla Pluginu. Przestrzenie nazw administratora rdzenia (`config.*`, `exec.approvals.*`, `wizard.*`, `update.*`) pozostają zarezerwowane i zawsze - są rozstrzygane do `operator.admin`. - `defineChannelPluginEntry` automatycznie obsługuje podział trybu rejestracji. Zobacz - [Entry Points](/pl/plugins/sdk-entrypoints#definechannelpluginentry), aby poznać wszystkie - opcje. + rozwiązują się do `operator.admin`. + `defineChannelPluginEntry` automatycznie obsługuje podział trybów rejestracji. Wszystkie + opcje znajdziesz w [Punkty wejścia](/pl/plugins/sdk-entrypoints#definechannelpluginentry). - + Utwórz `setup-entry.ts` do lekkiego ładowania podczas onboardingu: ```typescript setup-entry.ts @@ -485,16 +460,16 @@ powinien używać `resolveInboundMentionDecision({ facts, policy })`. export default defineSetupPluginEntry(acmeChatPlugin); ``` - OpenClaw ładuje to zamiast pełnego entry, gdy kanał jest wyłączony - lub nieskonfigurowany. Pozwala to uniknąć pobierania ciężkiego kodu środowiska uruchomieniowego podczas przepływów konfiguracji. + OpenClaw ładuje to zamiast pełnego punktu wejścia, gdy kanał jest wyłączony + lub nieskonfigurowany. Pozwala to uniknąć wciągania ciężkiego kodu runtime podczas przepływów konfiguracji. Szczegóły znajdziesz w [Konfiguracja i ustawienia](/pl/plugins/sdk-setup#setup-entry). - Twój plugin musi odbierać wiadomości z platformy i przekazywać je do - OpenClaw. Typowy wzorzec to webhook, który weryfikuje żądanie i - wysyła je przez handler wejściowy twojego kanału: + Twój Plugin musi odbierać wiadomości z platformy i przekazywać je do + OpenClaw. Typowy wzorzec to Webhook, który weryfikuje żądanie i + dyspozytuje je przez handler wejściowy Twojego kanału: ```typescript registerFull(api) { @@ -518,16 +493,16 @@ powinien używać `resolveInboundMentionDecision({ facts, policy })`. ``` - Obsługa wiadomości przychodzących jest specyficzna dla kanału. Każdy plugin kanału odpowiada - za własny potok wejściowy. Zobacz bundlowane pluginy kanałów - (na przykład pakiet pluginu Microsoft Teams lub Google Chat), aby poznać rzeczywiste wzorce. + Obsługa wiadomości przychodzących jest specyficzna dla kanału. Każdy Plugin kanału + odpowiada za własny pipeline wejściowy. Zobacz bundlowane Pluginy kanałów + (na przykład pakiet Pluginu Microsoft Teams lub Google Chat), aby poznać rzeczywiste wzorce. - -Napisz testy współlokowane w `src/channel.test.ts`: + +Napisz testy kolokowane w `src/channel.test.ts`: ```typescript src/channel.test.ts import { describe, it, expect } from "vitest"; @@ -565,7 +540,7 @@ Napisz testy współlokowane w `src/channel.test.ts`: pnpm test -- /acme-chat/ ``` - Informacje o współdzielonych helperach testowych znajdziesz w [Testowanie](/pl/plugins/sdk-testing). + Informacje o współdzielonych helperach testowych znajdziesz w sekcji [Testowanie](/pl/plugins/sdk-testing). @@ -579,41 +554,41 @@ Napisz testy współlokowane w `src/channel.test.ts`: ├── index.ts # defineChannelPluginEntry ├── setup-entry.ts # defineSetupPluginEntry ├── api.ts # Eksporty publiczne (opcjonalnie) -├── runtime-api.ts # Wewnętrzne eksporty środowiska uruchomieniowego (opcjonalnie) +├── runtime-api.ts # Wewnętrzne eksporty runtime (opcjonalnie) └── src/ ├── channel.ts # ChannelPlugin przez createChatChannelPlugin ├── channel.test.ts # Testy ├── client.ts # Klient API platformy - └── runtime.ts # Magazyn środowiska uruchomieniowego (w razie potrzeby) + └── runtime.ts # Magazyn runtime (w razie potrzeby) ``` ## Tematy zaawansowane - Stałe, ograniczone do konta lub niestandardowe tryby odpowiedzi + Stałe, z zakresem konta lub niestandardowe tryby odpowiedzi - - describeMessageTool i wykrywanie działań + + describeMessageTool i wykrywanie akcji - + inferTargetChatType, looksLikeId, resolveTarget - - TTS, STT, multimedia, podagent przez api.runtime + + TTS, STT, multimedia, subagent przez api.runtime -Niektóre bundlowane powierzchnie helperów nadal istnieją na potrzeby utrzymania bundlowanych pluginów i -zgodności. Nie są one zalecanym wzorcem dla nowych pluginów kanałów; +Niektóre bundlowane powierzchnie helperów nadal istnieją na potrzeby utrzymania +bundlowanych Pluginów i zgodności. Nie są one zalecanym wzorcem dla nowych Pluginów kanałów; preferuj ogólne podścieżki channel/setup/reply/runtime ze wspólnej -powierzchni SDK, chyba że bezpośrednio utrzymujesz tę rodzinę bundlowanych pluginów. +powierzchni SDK, chyba że bezpośrednio utrzymujesz tę rodzinę bundlowanych Pluginów. -## Kolejne kroki +## Następne kroki -- [Pluginy dostawców](/pl/plugins/sdk-provider-plugins) — jeśli twój plugin udostępnia także modele -- [Przegląd SDK](/pl/plugins/sdk-overview) — pełna dokumentacja importów podścieżek +- [Pluginy dostawców](/pl/plugins/sdk-provider-plugins) — jeśli Twój Plugin udostępnia także modele +- [Przegląd SDK](/pl/plugins/sdk-overview) — pełne odniesienie do importów podścieżek - [Testowanie SDK](/pl/plugins/sdk-testing) — narzędzia testowe i testy kontraktowe -- [Manifest pluginu](/pl/plugins/manifest) — pełny schemat manifestu +- [Manifest Pluginu](/pl/plugins/manifest) — pełny schemat manifestu diff --git a/docs/pl/providers/github-copilot.md b/docs/pl/providers/github-copilot.md index a3c0cb19a..085f81f27 100644 --- a/docs/pl/providers/github-copilot.md +++ b/docs/pl/providers/github-copilot.md @@ -2,28 +2,28 @@ read_when: - Chcesz używać GitHub Copilot jako dostawcy modeli - Potrzebujesz przepływu `openclaw models auth login-github-copilot` -summary: Zaloguj się do GitHub Copilot z OpenClaw przy użyciu device flow +summary: Zaloguj się do GitHub Copilot z OpenClaw za pomocą przepływu urządzenia title: GitHub Copilot x-i18n: - generated_at: "2026-04-12T23:31:02Z" + generated_at: "2026-04-15T09:51:32Z" model: gpt-5.4 provider: openai - source_hash: 51fee006e7d4e78e37b0c29356b0090b132de727d99b603441767d3fb642140b + source_hash: b8258fecff22fb73b057de878462941f6eb86d0c5f775c5eac4840e95ba5eccf source_path: providers/github-copilot.md workflow: 15 --- # GitHub Copilot -GitHub Copilot to asystent kodowania AI od GitHub. Zapewnia dostęp do modeli -Copilot dla Twojego konta i planu GitHub. OpenClaw może używać Copilot jako -dostawcy modeli na dwa różne sposoby. +GitHub Copilot to asystent kodowania AI od GitHub. Zapewnia dostęp do modeli Copilot +dla Twojego konta i planu GitHub. OpenClaw może używać Copilot jako dostawcy modeli +na dwa różne sposoby. ## Dwa sposoby używania Copilot w OpenClaw - Użyj natywnego przepływu logowania przez urządzenie, aby uzyskać token GitHub, a następnie wymieniaj go na + Użyj natywnego przepływu logowania urządzenia, aby uzyskać token GitHub, a następnie wymienić go na tokeny API Copilot podczas działania OpenClaw. To **domyślna** i najprostsza ścieżka, ponieważ nie wymaga VS Code. @@ -33,15 +33,15 @@ dostawcy modeli na dwa różne sposoby. openclaw models auth login-github-copilot ``` - Zostaniesz poproszony o przejście pod URL i wpisanie jednorazowego kodu. Pozostaw - terminal otwarty do czasu zakończenia procesu. + Zostaniesz poproszony o odwiedzenie adresu URL i wpisanie jednorazowego kodu. Pozostaw + terminal otwarty, aż proces się zakończy. ```bash openclaw models set github-copilot/gpt-4o ``` - Albo w konfiguracji: + Lub w konfiguracji: ```json5 { @@ -55,60 +55,60 @@ dostawcy modeli na dwa różne sposoby. Użyj rozszerzenia VS Code **Copilot Proxy** jako lokalnego mostu. OpenClaw komunikuje się z - endpointem `/v1` serwera proxy i używa listy modeli skonfigurowanej tam przez Ciebie. + endpointem `/v1` proxy i używa listy modeli skonfigurowanej w tym miejscu. - Wybierz to, jeśli już uruchamiasz Copilot Proxy w VS Code lub potrzebujesz kierować ruch - przez niego. Musisz włączyć Plugin i utrzymywać uruchomione rozszerzenie VS Code. + Wybierz tę opcję, jeśli już używasz Copilot Proxy w VS Code albo musisz kierować ruch + przez niego. Musisz włączyć Plugin i pozostawić uruchomione rozszerzenie VS Code. -## Opcjonalne flagi +## Flagi opcjonalne -| Flaga | Opis | -| -------------- | ----------------------------------------------------- | -| `--yes` | Pomija monit o potwierdzenie | -| `--set-default` | Ustawia także zalecany domyślny model tego dostawcy | +| Flaga | Opis | +| --------------- | --------------------------------------------------- | +| `--yes` | Pomiń monit o potwierdzenie | +| `--set-default` | Zastosuj także zalecany domyślny model dostawcy | ```bash # Pomiń potwierdzenie openclaw models auth login-github-copilot --yes -# Zaloguj się i ustaw model domyślny w jednym kroku +# Zaloguj i ustaw model domyślny w jednym kroku openclaw models auth login --provider github-copilot --method device --set-default ``` - Przepływ logowania przez urządzenie wymaga interaktywnego TTY. Uruchom go bezpośrednio w + Przepływ logowania urządzenia wymaga interaktywnego TTY. Uruchom go bezpośrednio w terminalu, a nie w nieinteraktywnym skrypcie ani potoku CI. - Dostępność modeli Copilot zależy od Twojego planu GitHub. Jeśli model - zostanie odrzucony, spróbuj innego identyfikatora (na przykład `github-copilot/gpt-4.1`). + Dostępność modeli Copilot zależy od Twojego planu GitHub. Jeśli model zostanie + odrzucony, spróbuj użyć innego ID (na przykład `github-copilot/gpt-4.1`). - Identyfikatory modeli Claude automatycznie używają transportu Anthropic Messages. Modele GPT, - serii o i Gemini zachowują transport OpenAI Responses. OpenClaw + ID modeli Claude automatycznie używają transportu Anthropic Messages. Modele GPT, + o-series i Gemini zachowują transport OpenAI Responses. OpenClaw wybiera właściwy transport na podstawie odwołania do modelu. - - OpenClaw rozpoznaje uwierzytelnianie Copilot ze zmiennych środowiskowych w następującej + + OpenClaw rozwiązuje uwierzytelnianie Copilot ze zmiennych środowiskowych w następującej kolejności priorytetów: - | Priorytet | Zmienna | Uwagi | - | --------- | -------------------- | ------------------------------------- | + | Priorytet | Zmienna | Uwagi | + | --------- | -------------------- | -------------------------------------- | | 1 | `COPILOT_GITHUB_TOKEN` | Najwyższy priorytet, specyficzna dla Copilot | - | 2 | `GH_TOKEN` | Token GitHub CLI (awaryjnie) | - | 3 | `GITHUB_TOKEN` | Standardowy token GitHub (najniższy) | + | 2 | `GH_TOKEN` | Token GitHub CLI (zapasowy) | + | 3 | `GITHUB_TOKEN` | Standardowy token GitHub (najniższy) | - Gdy ustawionych jest kilka zmiennych, OpenClaw używa tej o najwyższym priorytecie. - Przepływ logowania przez urządzenie (`openclaw models auth login-github-copilot`) zapisuje + Gdy ustawionych jest wiele zmiennych, OpenClaw używa tej o najwyższym priorytecie. + Przepływ logowania urządzenia (`openclaw models auth login-github-copilot`) zapisuje swój token w magazynie profili uwierzytelniania i ma pierwszeństwo przed wszystkimi zmiennymi środowiskowymi. @@ -122,15 +122,55 @@ openclaw models auth login --provider github-copilot --method device --set-defau -Wymaga interaktywnego TTY. Uruchom polecenie logowania bezpośrednio w terminalu, a nie -wewnątrz bezobsługowego skryptu ani zadania CI. +Wymagany jest interaktywny TTY. Uruchom polecenie logowania bezpośrednio w terminalu, a nie +wewnątrz skryptu bez interfejsu ani zadania CI. +## Embeddingi wyszukiwania pamięci + +GitHub Copilot może również służyć jako dostawca embeddingów dla +[wyszukiwania pamięci](/pl/concepts/memory-search). Jeśli masz subskrypcję Copilot i +się zalogowałeś, OpenClaw może używać go do embeddingów bez osobnego klucza API. + +### Automatyczne wykrywanie + +Gdy `memorySearch.provider` ma wartość `"auto"` (domyślnie), GitHub Copilot jest sprawdzany +z priorytetem 15 — po lokalnych embeddingach, ale przed OpenAI i innymi płatnymi +dostawcami. Jeśli token GitHub jest dostępny, OpenClaw wykrywa dostępne +modele embeddingów z API Copilot i automatycznie wybiera najlepszy. + +### Jawna konfiguracja + +```json5 +{ + agents: { + defaults: { + memorySearch: { + provider: "github-copilot", + // Opcjonalnie: zastąp automatycznie wykryty model + model: "text-embedding-3-small", + }, + }, + }, +} +``` + +### Jak to działa + +1. OpenClaw rozwiązuje Twój token GitHub (ze zmiennych środowiskowych lub profilu uwierzytelniania). +2. Wymienia go na krótkotrwały token API Copilot. +3. Odpytuje endpoint Copilot `/models`, aby wykryć dostępne modele embeddingów. +4. Wybiera najlepszy model (preferuje `text-embedding-3-small`). +5. Wysyła żądania embeddingów do endpointu Copilot `/embeddings`. + +Dostępność modeli zależy od Twojego planu GitHub. Jeśli żadne modele embeddingów nie są +dostępne, OpenClaw pomija Copilot i próbuje użyć następnego dostawcy. + ## Powiązane - Wybór dostawców, odwołań do modeli i zachowania failover. + Wybór dostawców, odwołań do modeli i zachowania awaryjnego. Szczegóły uwierzytelniania i zasady ponownego użycia poświadczeń. diff --git a/docs/pl/reference/RELEASING.md b/docs/pl/reference/RELEASING.md index d3ddddcdc..2414657d1 100644 --- a/docs/pl/reference/RELEASING.md +++ b/docs/pl/reference/RELEASING.md @@ -1,25 +1,25 @@ --- read_when: - - Szukasz definicji publicznych kanałów wydań + - Szukasz publicznych definicji kanałów wydań - Szukasz nazewnictwa wersji i harmonogramu wydań -summary: Publiczne kanały wydań, nazewnictwo wersji i harmonogram wydawniczy -title: Zasady wydań +summary: Publiczne kanały wydań, nazewnictwo wersji i harmonogram publikacji +title: Polityka wydań x-i18n: - generated_at: "2026-04-14T09:50:55Z" + generated_at: "2026-04-15T09:51:33Z" model: gpt-5.4 provider: openai - source_hash: 3eaf9f1786b8c9fd4f5a9c657b623cb69d1a485958e1a9b8f108511839b63587 + source_hash: 88724307269ab783a9fbf8a0540fea198d8a3add68457f4e64d5707114fa518c source_path: reference/RELEASING.md workflow: 15 --- -# Zasady wydań +# Polityka wydań -OpenClaw ma trzy publiczne kanały wydań: +OpenClaw ma trzy publiczne ścieżki wydań: -- stable: tagowane wydania, które domyślnie publikują do npm `beta`, albo do npm `latest`, gdy zostanie to wyraźnie wskazane -- beta: tagi wydań przedpremierowych, które publikują do npm `beta` -- dev: ruchoma głowa gałęzi `main` +- stable: oznaczone tagami wydania, które domyślnie publikują do npm `beta`, albo do npm `latest`, gdy zostanie to wyraźnie wskazane +- beta: tagi wydań wstępnych publikowane do npm `beta` +- dev: ruchoma głowa `main` ## Nazewnictwo wersji @@ -27,125 +27,162 @@ OpenClaw ma trzy publiczne kanały wydań: - Tag Git: `vYYYY.M.D` - Wersja poprawkowego wydania stable: `YYYY.M.D-N` - Tag Git: `vYYYY.M.D-N` -- Wersja wydania przedpremierowego beta: `YYYY.M.D-beta.N` +- Wersja beta prerelease: `YYYY.M.D-beta.N` - Tag Git: `vYYYY.M.D-beta.N` -- Nie dodawaj zer wiodących do miesiąca ani dnia -- `latest` oznacza aktualne promowane stabilne wydanie npm -- `beta` oznacza aktualny cel instalacji beta -- Wydania stable i poprawkowe wydania stable domyślnie publikują do npm `beta`; operatorzy wydań mogą jawnie wskazać `latest` albo później promować zweryfikowaną kompilację beta +- Nie dopełniaj miesiąca ani dnia zerami z przodu +- `latest` oznacza aktualnie promowane stabilne wydanie npm +- `beta` oznacza bieżący docelowy kanał instalacji beta +- Wydania stable i poprawkowe wydania stable domyślnie publikują do npm `beta`; operatorzy wydań mogą jawnie wskazać `latest` albo później wypromować zweryfikowaną wersję beta - Każde wydanie OpenClaw obejmuje jednocześnie pakiet npm i aplikację macOS ## Harmonogram wydań -- Wydania przechodzą najpierw przez beta -- Stable pojawia się dopiero po zweryfikowaniu najnowszej bety -- Szczegółowa procedura wydania, zatwierdzenia, poświadczenia i uwagi dotyczące odzyskiwania są przeznaczone wyłącznie dla maintainerów +- Wydania najpierw trafiają do beta +- Stable pojawia się dopiero po zweryfikowaniu najnowszej wersji beta +- Szczegółowa procedura wydania, zatwierdzenia, poświadczenia i notatki dotyczące odzyskiwania są + dostępne wyłącznie dla maintainerów -## Kontrola przed wydaniem +## Wstępna walidacja wydania -- Uruchom `pnpm build && pnpm ui:build` przed `pnpm release:check`, aby oczekiwane artefakty wydania `dist/*` oraz pakiet Control UI istniały na potrzeby kroku walidacji pakietu -- Uruchom `pnpm release:check` przed każdym tagowanym wydaniem -- Kontrole wydania są teraz uruchamiane w osobnym ręcznym workflow: +- Uruchom `pnpm build && pnpm ui:build` przed `pnpm release:check`, aby oczekiwane + artefakty wydania `dist/*` i bundle Control UI istniały na potrzeby kroku + walidacji paczki +- Uruchom `pnpm release:check` przed każdym wydaniem oznaczonym tagiem +- Kontrole wydań są teraz uruchamiane w osobnym ręcznym workflow: `OpenClaw Release Checks` -- Ten podział jest celowy: rzeczywista ścieżka wydania npm ma pozostać krótka, deterministyczna i skoncentrowana na artefaktach, podczas gdy wolniejsze testy live mają pozostać w osobnym kanale, aby nie opóźniały ani nie blokowały publikacji -- Kontrole wydania muszą być uruchamiane z referencji workflow `main`, aby logika workflow i sekrety pozostały kanoniczne -- Ten workflow akceptuje istniejący tag wydania albo bieżący pełny 40-znakowy SHA commita `main` -- W trybie commit-SHA akceptowany jest tylko bieżący HEAD `origin/main`; dla starszych commitów wydania użyj tagu wydania -- Walidacyjny preflight `OpenClaw NPM Release` również akceptuje bieżący pełny 40-znakowy SHA commita `main` bez wymagania wypchniętego tagu -- Ścieżka SHA jest tylko walidacyjna i nie może zostać promowana do rzeczywistej publikacji -- W trybie SHA workflow syntetyzuje `v` wyłącznie na potrzeby sprawdzenia metadanych pakietu; rzeczywista publikacja nadal wymaga prawdziwego tagu wydania -- Oba workflow utrzymują rzeczywistą ścieżkę publikacji i promocji na runnerach hostowanych przez GitHub, podczas gdy niemutująca ścieżka walidacji może używać większych runnerów Blacksmith Linux +- Międzyplatformowa walidacja instalacji i aktualizacji w czasie działania jest wywoływana z + prywatnego workflow wywołującego + `openclaw/releases-private/.github/workflows/openclaw-cross-os-release-checks.yml`, + który uruchamia wielokrotnego użytku publiczny workflow + `.github/workflows/openclaw-cross-os-release-checks-reusable.yml` +- Ten podział jest celowy: prawdziwa ścieżka wydania npm ma pozostać krótka, + deterministyczna i skupiona na artefaktach, podczas gdy wolniejsze kontrole na żywo pozostają w + osobnym torze, aby nie opóźniały ani nie blokowały publikacji +- Kontrole wydań muszą być uruchamiane z referencji workflow `main`, aby logika + workflow i sekrety pozostawały kanoniczne +- Ten workflow akceptuje albo istniejący tag wydania, albo bieżący pełny + 40-znakowy SHA commita `main` +- W trybie commit-SHA akceptowany jest tylko bieżący HEAD `origin/main`; dla + starszych commitów wydania użyj tagu wydania +- Wstępna walidacja `OpenClaw NPM Release` w trybie tylko walidacji także akceptuje bieżący + pełny 40-znakowy SHA commita `main` bez wymogu wypchniętego tagu +- Ta ścieżka SHA służy wyłącznie do walidacji i nie może zostać wypromowana do rzeczywistej publikacji +- W trybie SHA workflow syntetyzuje `v` wyłącznie na potrzeby + sprawdzenia metadanych pakietu; prawdziwa publikacja nadal wymaga rzeczywistego tagu wydania +- Oba workflow utrzymują rzeczywistą ścieżkę publikacji i promocji na runnerach hostowanych przez GitHub, podczas gdy niezmieniająca stanu + ścieżka walidacji może korzystać z większych + runnerów Blacksmith Linux - Ten workflow uruchamia `OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_CACHE_TEST=1 pnpm test:live:cache` z użyciem sekretów workflow `OPENAI_API_KEY` i `ANTHROPIC_API_KEY` -- Preflight wydania npm nie czeka już na osobny kanał kontroli wydania -- Przed zatwierdzeniem uruchom `RELEASE_TAG=vYYYY.M.D node --import tsx scripts/openclaw-npm-release-check.ts` - (albo odpowiadający tag beta/poprawkowy) -- Po publikacji do npm uruchom +- Wstępna walidacja wydania npm nie czeka już na oddzielny tor kontroli wydań +- Przed zatwierdzeniem uruchom + `RELEASE_TAG=vYYYY.M.D node --import tsx scripts/openclaw-npm-release-check.ts` + (lub odpowiadający tag beta/poprawkowy) +- Po publikacji npm uruchom `node --import tsx scripts/openclaw-npm-postpublish-verify.ts YYYY.M.D` - (albo odpowiadającą wersję beta/poprawkową), aby zweryfikować opublikowaną ścieżkę instalacji z rejestru w świeżym tymczasowym prefiksie -- Automatyzacja wydań maintainerów używa teraz modelu preflight-then-promote: + (lub odpowiadającą wersję beta/poprawkową), aby zweryfikować opublikowaną ścieżkę + instalacji z rejestru w świeżym tymczasowym prefiksie +- Automatyzacja wydań maintainerów używa teraz podejścia preflight-then-promote: - rzeczywista publikacja npm musi przejść pomyślny npm `preflight_run_id` - - wydania stable do npm domyślnie trafiają do `beta` - - publikacja stable do npm może jawnie wskazać `latest` przez input workflow - - promocja stable w npm z `beta` do `latest` nadal jest dostępna jako jawny tryb ręczny w zaufanym workflow `OpenClaw NPM Release` - - bezpośrednie publikacje stable mogą także uruchamiać jawny tryb synchronizacji dist-tag, który kieruje zarówno `latest`, jak i `beta` na już opublikowaną wersję stable - - te tryby dist-tag nadal wymagają poprawnego `NPM_TOKEN` w środowisku `npm-release`, ponieważ zarządzanie `npm dist-tag` jest oddzielne od zaufanej publikacji + - stabilne wydania npm domyślnie trafiają do `beta` + - stabilna publikacja npm może jawnie kierować do `latest` przez input workflow + - zmiana npm dist-tag oparta na tokenie znajduje się teraz w + `openclaw/releases-private/.github/workflows/openclaw-npm-dist-tags.yml` + ze względów bezpieczeństwa, ponieważ `npm dist-tag add` nadal wymaga `NPM_TOKEN`, podczas gdy + publiczne repo zachowuje publikację wyłącznie przez OIDC - publiczne `macOS Release` służy wyłącznie do walidacji - - rzeczywista prywatna publikacja mac musi przejść pomyślne prywatne mac + - rzeczywista prywatna publikacja mac musi przejść pomyślne prywatne uruchomienia mac `preflight_run_id` i `validate_run_id` - - rzeczywiste ścieżki publikacji promują przygotowane artefakty zamiast ponownie je budować -- W przypadku poprawkowych wydań stable, takich jak `YYYY.M.D-N`, weryfikator po publikacji sprawdza również tę samą ścieżkę aktualizacji w tymczasowym prefiksie z `YYYY.M.D` do `YYYY.M.D-N`, aby poprawki wydań nie mogły po cichu pozostawić starszych globalnych instalacji przy bazowym ładunku stable -- Preflight wydania npm kończy się błędem w trybie fail-closed, chyba że tarball zawiera zarówno `dist/control-ui/index.html`, jak i niepustą zawartość `dist/control-ui/assets/`, abyśmy nie wysłali ponownie pustego panelu przeglądarkowego -- `pnpm test:install:smoke` wymusza również limit `unpackedSize` dla `npm pack` na kandydacie tarballa aktualizacji, dzięki czemu e2e instalatora wychwytuje przypadkowe zwiększenie rozmiaru pakietu przed ścieżką publikacji wydania -- Jeśli prace nad wydaniem dotyczyły planowania CI, manifestów czasu rozszerzeń albo macierzy testów rozszerzeń, przed zatwierdzeniem zregeneruj i przejrzyj należące do planera wyjścia macierzy workflow `checks-node-extensions` z `.github/workflows/ci.yml`, aby informacje o wydaniu nie opisywały nieaktualnego układu CI + - rzeczywiste ścieżki publikacji promują przygotowane artefakty zamiast budować + je ponownie +- Dla poprawkowych wydań stable takich jak `YYYY.M.D-N`, weryfikator po publikacji + sprawdza także tę samą ścieżkę aktualizacji w tymczasowym prefiksie z `YYYY.M.D` do `YYYY.M.D-N`, + aby poprawki wydań nie mogły po cichu pozostawić starszych globalnych instalacji na + bazowym stabilnym payloadzie +- Wstępna walidacja wydania npm kończy się błędem domyślnie, jeśli tarball nie zawiera zarówno + `dist/control-ui/index.html`, jak i niepustego payloadu `dist/control-ui/assets/`, + abyśmy nie wysłali ponownie pustego panelu przeglądarkowego +- `pnpm test:install:smoke` wymusza także budżet `unpackedSize` dla paczki npm na + kandydackim tarballu aktualizacji, dzięki czemu e2e instalatora wychwytuje przypadkowy wzrost + rozmiaru paczki przed ścieżką publikacji wydania +- Jeśli prace nad wydaniem dotyczyły planowania CI, manifestów czasowych rozszerzeń albo + macierzy testów rozszerzeń, przed zatwierdzeniem zregeneruj i sprawdź + należące do planera wyniki macierzy workflow `checks-node-extensions` z `.github/workflows/ci.yml`, + aby notatki do wydania nie opisywały nieaktualnego układu CI - Gotowość stabilnego wydania macOS obejmuje także powierzchnie aktualizatora: - - wydanie GitHub musi ostatecznie zawierać spakowane `.zip`, `.dmg` i `.dSYM.zip` + - wydanie GitHub musi ostatecznie zawierać spakowane pliki `.zip`, `.dmg` i `.dSYM.zip` - `appcast.xml` na `main` musi po publikacji wskazywać nowy stabilny plik zip - - spakowana aplikacja musi zachować niedebugowe bundle id, niepusty adres URL kanału Sparkle oraz `CFBundleVersion` równy lub wyższy od kanonicznego minimalnego poziomu kompilacji Sparkle dla tej wersji wydania + - spakowana aplikacja musi zachować niedebugowy bundle id, niepusty URL kanału Sparkle + oraz `CFBundleVersion` nie niższy niż kanoniczny minimalny poziom builda Sparkle + dla tej wersji wydania -## Inputy workflow NPM +## Wejścia workflow NPM -`OpenClaw NPM Release` akceptuje następujące inputy sterowane przez operatora: +`OpenClaw NPM Release` akceptuje następujące wejścia sterowane przez operatora: - `tag`: wymagany tag wydania, taki jak `v2026.4.2`, `v2026.4.2-1` albo `v2026.4.2-beta.1`; gdy `preflight_only=true`, może to być również bieżący pełny 40-znakowy SHA commita `main` dla walidacyjnego preflightu -- `preflight_only`: `true` dla samej walidacji/budowania/pakowania, `false` dla rzeczywistej ścieżki publikacji -- `preflight_run_id`: wymagany w rzeczywistej ścieżce publikacji, aby workflow ponownie wykorzystał przygotowany tarball z pomyślnego uruchomienia preflightu +- `preflight_only`: `true` tylko dla walidacji/budowy/pakowania, `false` dla + rzeczywistej ścieżki publikacji +- `preflight_run_id`: wymagane w rzeczywistej ścieżce publikacji, aby workflow ponownie użył + przygotowanego tarballa z pomyślnego uruchomienia preflightu - `npm_dist_tag`: docelowy tag npm dla ścieżki publikacji; domyślnie `beta` -- `promote_beta_to_latest`: `true`, aby pominąć publikację i przenieść już opublikowaną stabilną kompilację `beta` na `latest` -- `sync_stable_dist_tags`: `true`, aby pominąć publikację i skierować zarówno `latest`, jak i `beta` na już opublikowaną stabilną wersję -`OpenClaw Release Checks` akceptuje następujące inputy sterowane przez operatora: +`OpenClaw Release Checks` akceptuje następujące wejścia sterowane przez operatora: -- `ref`: istniejący tag wydania albo bieżący pełny 40-znakowy SHA commita `main` do zweryfikowania +- `ref`: istniejący tag wydania albo bieżący pełny 40-znakowy SHA commita `main` + do zwalidowania -Reguły: +Zasady: -- Tagi stable i poprawkowe mogą publikować zarówno do `beta`, jak i do `latest` -- Tagi wydań przedpremierowych beta mogą publikować wyłącznie do `beta` -- Pełny input SHA commita jest dozwolony tylko wtedy, gdy `preflight_only=true` -- Tryb commit-SHA kontroli wydania wymaga również bieżącego HEAD `origin/main` -- Rzeczywista ścieżka publikacji musi używać tego samego `npm_dist_tag`, który został użyty podczas preflightu; workflow weryfikuje te metadane przed kontynuacją publikacji -- Tryb promocji musi używać tagu stable albo poprawkowego, `preflight_only=false`, - pustego `preflight_run_id` oraz `npm_dist_tag=beta` -- Tryb synchronizacji dist-tag musi używać tagu stable albo poprawkowego, - `preflight_only=false`, pustego `preflight_run_id`, `npm_dist_tag=latest` - oraz `promote_beta_to_latest=false` -- Tryby promocji i synchronizacji dist-tag również wymagają poprawnego `NPM_TOKEN`, ponieważ `npm dist-tag add` nadal wymaga zwykłego uwierzytelnienia npm; zaufana publikacja obejmuje tylko ścieżkę publikacji pakietu +- Tagi stable i poprawkowe mogą publikować albo do `beta`, albo do `latest` +- Tagi beta prerelease mogą publikować wyłącznie do `beta` +- Pełny SHA commita jest dozwolony tylko wtedy, gdy `preflight_only=true` +- Tryb commit-SHA w kontrolach wydań również wymaga bieżącego HEAD `origin/main` +- Rzeczywista ścieżka publikacji musi używać tego samego `npm_dist_tag`, którego użyto podczas preflightu; + workflow weryfikuje te metadane, zanim publikacja będzie kontynuowana -## Sekwencja wydania stable npm +## Sekwencja stabilnego wydania npm Podczas przygotowywania stabilnego wydania npm: 1. Uruchom `OpenClaw NPM Release` z `preflight_only=true` - - Zanim tag będzie istniał, możesz użyć bieżącego pełnego SHA commita `main` - do walidacyjnego próbnego uruchomienia workflow preflight -2. Wybierz `npm_dist_tag=beta` dla zwykłego przepływu beta-first albo `latest` tylko wtedy, gdy celowo chcesz wykonać bezpośrednią publikację stable -3. Uruchom osobno `OpenClaw Release Checks` z tym samym tagiem albo pełnym bieżącym SHA `main`, gdy chcesz uzyskać pokrycie live dla cache promptów - - To rozdzielenie jest celowe, aby pokrycie live pozostawało dostępne bez ponownego łączenia długotrwałych albo niestabilnych kontroli z workflow publikacji -4. Zapisz pomyślny `preflight_run_id` + - Zanim pojawi się tag, możesz użyć bieżącego pełnego SHA commita `main` do + walidacyjnego dry run workflow preflight +2. Wybierz `npm_dist_tag=beta` dla normalnego przepływu beta-first albo `latest` tylko + wtedy, gdy celowo chcesz bezpośrednio opublikować stabilne wydanie +3. Uruchom oddzielnie `OpenClaw Release Checks` z tym samym tagiem albo + pełnym bieżącym SHA `main`, jeśli chcesz objąć testami prompt cache na żywo + - To rozdzielenie jest celowe, aby pokrycie na żywo pozostawało dostępne bez + ponownego łączenia długotrwałych lub niestabilnych kontroli z workflow publikacji +4. Zachowaj pomyślne `preflight_run_id` 5. Uruchom ponownie `OpenClaw NPM Release` z `preflight_only=false`, tym samym `tag`, tym samym `npm_dist_tag` i zapisanym `preflight_run_id` -6. Jeśli wydanie trafiło do `beta`, uruchom później `OpenClaw NPM Release` z tym samym stabilnym `tag`, `promote_beta_to_latest=true`, `preflight_only=false`, - pustym `preflight_run_id` i `npm_dist_tag=beta`, gdy chcesz przenieść tę - opublikowaną kompilację do `latest` +6. Jeśli wydanie trafiło do `beta`, użyj prywatnego workflow + `openclaw/releases-private/.github/workflows/openclaw-npm-dist-tags.yml`, + aby wypromować tę stabilną wersję z `beta` do `latest` 7. Jeśli wydanie zostało celowo opublikowane bezpośrednio do `latest` i `beta` - powinno wskazywać tę samą stabilną kompilację, uruchom `OpenClaw NPM Release` z tym samym stabilnym `tag`, `sync_stable_dist_tags=true`, `promote_beta_to_latest=false`, `preflight_only=false`, pustym `preflight_run_id` i `npm_dist_tag=latest` + powinno od razu wskazywać ten sam stabilny build, użyj tego samego prywatnego + workflow, aby skierować oba dist-tagi na stabilną wersję, albo pozwól, aby jego zaplanowana + samonaprawcza synchronizacja przesunęła `beta` później -Tryby promocji i synchronizacji dist-tag nadal wymagają zatwierdzenia środowiska `npm-release` oraz poprawnego `NPM_TOKEN` dostępnego dla tego uruchomienia workflow. +Zmiana dist-tag znajduje się w prywatnym repo ze względów bezpieczeństwa, ponieważ nadal +wymaga `NPM_TOKEN`, podczas gdy publiczne repo zachowuje publikację wyłącznie przez OIDC. -Dzięki temu zarówno ścieżka bezpośredniej publikacji, jak i ścieżka promocji beta-first pozostają udokumentowane i widoczne dla operatora. +To sprawia, że zarówno ścieżka publikacji bezpośredniej, jak i ścieżka promocji beta-first są +udokumentowane i widoczne dla operatora. ## Publiczne odniesienia - [`.github/workflows/openclaw-npm-release.yml`](https://github.com/openclaw/openclaw/blob/main/.github/workflows/openclaw-npm-release.yml) - [`.github/workflows/openclaw-release-checks.yml`](https://github.com/openclaw/openclaw/blob/main/.github/workflows/openclaw-release-checks.yml) +- [`.github/workflows/openclaw-cross-os-release-checks-reusable.yml`](https://github.com/openclaw/openclaw/blob/main/.github/workflows/openclaw-cross-os-release-checks-reusable.yml) - [`scripts/openclaw-npm-release-check.ts`](https://github.com/openclaw/openclaw/blob/main/scripts/openclaw-npm-release-check.ts) - [`scripts/package-mac-dist.sh`](https://github.com/openclaw/openclaw/blob/main/scripts/package-mac-dist.sh) - [`scripts/make_appcast.sh`](https://github.com/openclaw/openclaw/blob/main/scripts/make_appcast.sh) -Maintainerzy używają prywatnej dokumentacji wydań w +Maintainerzy korzystają z prywatnej dokumentacji wydań w [`openclaw/maintainers/release/README.md`](https://github.com/openclaw/maintainers/blob/main/release/README.md) jako właściwego runbooka. diff --git a/docs/pl/reference/memory-config.md b/docs/pl/reference/memory-config.md index 546e98566..32a5caa4b 100644 --- a/docs/pl/reference/memory-config.md +++ b/docs/pl/reference/memory-config.md @@ -4,92 +4,93 @@ read_when: - Chcesz skonfigurować backend QMD - Chcesz dostroić wyszukiwanie hybrydowe, MMR lub zanik czasowy - Chcesz włączyć multimodalne indeksowanie pamięci -summary: Wszystkie opcje konfiguracji dotyczące wyszukiwania pamięci, dostawców embeddingów, QMD, wyszukiwania hybrydowego i indeksowania multimodalnego -title: Dokumentacja konfiguracji pamięci +summary: Wszystkie opcje konfiguracji wyszukiwania w pamięci, dostawców embeddingów, QMD, wyszukiwania hybrydowego i indeksowania multimodalnego +title: Referencja konfiguracji pamięci x-i18n: - generated_at: "2026-04-12T23:33:59Z" + generated_at: "2026-04-15T09:51:45Z" model: gpt-5.4 provider: openai - source_hash: 299ca9b69eea292ea557a2841232c637f5c1daf2bc0f73c0a42f7c0d8d566ce2 + source_hash: a13f6e982ee47401cc9a71bf2ee6a5305d06158b806a04703bcdcd92e340e4d5 source_path: reference/memory-config.md workflow: 15 --- -# Dokumentacja konfiguracji pamięci +# Referencja konfiguracji pamięci -Ta strona zawiera wszystkie opcje konfiguracji wyszukiwania pamięci OpenClaw. Aby zapoznać się z omówieniami koncepcyjnymi, zobacz: +Ta strona zawiera wszystkie opcje konfiguracji wyszukiwania pamięci w OpenClaw. Omówienia koncepcyjne znajdziesz tutaj: - [Przegląd pamięci](/pl/concepts/memory) -- jak działa pamięć - [Wbudowany silnik](/pl/concepts/memory-builtin) -- domyślny backend SQLite -- [Silnik QMD](/pl/concepts/memory-qmd) -- lokalny sidecar działający lokalnie w pierwszej kolejności -- [Wyszukiwanie pamięci](/pl/concepts/memory-search) -- pipeline wyszukiwania i dostrajanie -- [Active Memory](/pl/concepts/active-memory) -- włączanie sub-agenta pamięci dla interaktywnych sesji +- [Silnik QMD](/pl/concepts/memory-qmd) -- lokalny sidecar +- [Wyszukiwanie w pamięci](/pl/concepts/memory-search) -- pipeline wyszukiwania i dostrajanie +- [Active Memory](/pl/concepts/active-memory) -- włączanie subagenta pamięci dla interaktywnych sesji Wszystkie ustawienia wyszukiwania pamięci znajdują się w `agents.defaults.memorySearch` w `openclaw.json`, o ile nie zaznaczono inaczej. -Jeśli szukasz przełącznika funkcji **Active Memory** i konfiguracji sub-agenta, +Jeśli szukasz przełącznika funkcji **Active Memory** i konfiguracji subagenta, znajdują się one w `plugins.entries.active-memory`, a nie w `memorySearch`. Active Memory używa modelu dwóch bramek: -1. Plugin musi być włączony i wskazywać bieżący identyfikator agenta -2. Żądanie musi być kwalifikującą się interaktywną trwałą sesją czatu +1. Plugin musi być włączony i kierowany na bieżący identyfikator agenta +2. Żądanie musi dotyczyć kwalifikującej się interaktywnej trwałej sesji czatu -Zobacz [Active Memory](/pl/concepts/active-memory), aby poznać model aktywacji, -konfigurację należącą do Pluginu, trwałość transkryptów i bezpieczny wzorzec wdrażania. +Model aktywacji, konfigurację należącą do Pluginu, trwałość transkryptów i bezpieczny wzorzec wdrażania opisano w [Active Memory](/pl/concepts/active-memory). --- ## Wybór dostawcy -| Klucz | Typ | Domyślnie | Opis | -| --------- | --------- | --------------- | ------------------------------------------------------------------------------------------ | -| `provider` | `string` | wykrywane automatycznie | Id adaptera embeddingów: `openai`, `gemini`, `voyage`, `mistral`, `bedrock`, `ollama`, `local` | -| `model` | `string` | domyślny dla dostawcy | Nazwa modelu embeddingów | -| `fallback` | `string` | `"none"` | Id adaptera zapasowego, gdy główny zawiedzie | -| `enabled` | `boolean` | `true` | Włącza lub wyłącza wyszukiwanie pamięci | +| Key | Type | Default | Opis | +| ---------- | --------- | ---------------- | ------------------------------------------------------------------------------------------------------------- | +| `provider` | `string` | wykrywany automatycznie | Identyfikator adaptera embeddingów: `bedrock`, `gemini`, `github-copilot`, `local`, `mistral`, `ollama`, `openai`, `voyage` | +| `model` | `string` | domyślny dostawcy | Nazwa modelu embeddingów | +| `fallback` | `string` | `"none"` | Identyfikator adaptera zapasowego, gdy podstawowy zawiedzie | +| `enabled` | `boolean` | `true` | Włącza lub wyłącza wyszukiwanie pamięci | ### Kolejność automatycznego wykrywania Gdy `provider` nie jest ustawiony, OpenClaw wybiera pierwszy dostępny: -1. `local` -- jeśli skonfigurowano `memorySearch.local.modelPath` i plik istnieje. -2. `openai` -- jeśli można rozwiązać klucz OpenAI. -3. `gemini` -- jeśli można rozwiązać klucz Gemini. -4. `voyage` -- jeśli można rozwiązać klucz Voyage. -5. `mistral` -- jeśli można rozwiązać klucz Mistral. -6. `bedrock` -- jeśli łańcuch poświadczeń AWS SDK zostanie rozwiązany (rola instancji, klucze dostępu, profil, SSO, tożsamość web lub współdzielona konfiguracja). +1. `local` -- jeśli `memorySearch.local.modelPath` jest skonfigurowane i plik istnieje. +2. `github-copilot` -- jeśli można rozwiązać token GitHub Copilot (zmienna środowiskowa lub profil uwierzytelniania). +3. `openai` -- jeśli można rozwiązać klucz OpenAI. +4. `gemini` -- jeśli można rozwiązać klucz Gemini. +5. `voyage` -- jeśli można rozwiązać klucz Voyage. +6. `mistral` -- jeśli można rozwiązać klucz Mistral. +7. `bedrock` -- jeśli łańcuch poświadczeń AWS SDK zostanie rozwiązany (rola instancji, klucze dostępu, profil, SSO, tożsamość webowa lub współdzielona konfiguracja). `ollama` jest obsługiwane, ale nie jest wykrywane automatycznie (ustaw je jawnie). ### Rozwiązywanie klucza API -Zdalne embeddingi wymagają klucza API. Bedrock używa zamiast tego domyślnego +Zdalne embeddingi wymagają klucza API. Bedrock zamiast tego używa domyślnego łańcucha poświadczeń AWS SDK (role instancji, SSO, klucze dostępu). -| Dostawca | Zmienna env | Klucz konfiguracji | -| -------- | ---------------------------- | -------------------------------- | -| OpenAI | `OPENAI_API_KEY` | `models.providers.openai.apiKey` | -| Gemini | `GEMINI_API_KEY` | `models.providers.google.apiKey` | -| Voyage | `VOYAGE_API_KEY` | `models.providers.voyage.apiKey` | -| Mistral | `MISTRAL_API_KEY` | `models.providers.mistral.apiKey` | -| Bedrock | łańcuch poświadczeń AWS | Klucz API nie jest potrzebny | -| Ollama | `OLLAMA_API_KEY` (placeholder) | -- | +| Provider | Env var | Config key | +| -------------- | -------------------------------------------------- | --------------------------------- | +| Bedrock | łańcuch poświadczeń AWS | Klucz API nie jest wymagany | +| Gemini | `GEMINI_API_KEY` | `models.providers.google.apiKey` | +| GitHub Copilot | `COPILOT_GITHUB_TOKEN`, `GH_TOKEN`, `GITHUB_TOKEN` | Profil uwierzytelniania przez logowanie urządzenia | +| Mistral | `MISTRAL_API_KEY` | `models.providers.mistral.apiKey` | +| Ollama | `OLLAMA_API_KEY` (symbol zastępczy) | -- | +| OpenAI | `OPENAI_API_KEY` | `models.providers.openai.apiKey` | +| Voyage | `VOYAGE_API_KEY` | `models.providers.voyage.apiKey` | -Codex OAuth obejmuje tylko chat/completions i nie spełnia wymagań żądań embeddingów. +OAuth Codex obejmuje tylko czat/completions i nie spełnia wymagań żądań embeddingów. --- -## Konfiguracja zdalnego punktu końcowego +## Konfiguracja zdalnego endpointu -Dla niestandardowych punktów końcowych zgodnych z OpenAI lub nadpisywania wartości domyślnych dostawcy: +Dla własnych endpointów zgodnych z OpenAI lub nadpisywania ustawień domyślnych dostawcy: -| Klucz | Typ | Opis | -| ---------------- | -------- | ---------------------------------------------------- | -| `remote.baseUrl` | `string` | Niestandardowy bazowy URL API | -| `remote.apiKey` | `string` | Nadpisanie klucza API | -| `remote.headers` | `object` | Dodatkowe nagłówki HTTP (łączone z domyślnymi dostawcy) | +| Key | Type | Opis | +| ---------------- | -------- | -------------------------------------------------- | +| `remote.baseUrl` | `string` | Własny bazowy URL API | +| `remote.apiKey` | `string` | Nadpisanie klucza API | +| `remote.headers` | `object` | Dodatkowe nagłówki HTTP (łączone z domyślnymi ustawieniami dostawcy) | ```json5 { @@ -112,13 +113,13 @@ Dla niestandardowych punktów końcowych zgodnych z OpenAI lub nadpisywania wart ## Konfiguracja specyficzna dla Gemini -| Klucz | Typ | Domyślnie | Opis | +| Key | Type | Default | Opis | | ---------------------- | -------- | ---------------------- | ------------------------------------------ | | `model` | `string` | `gemini-embedding-001` | Obsługuje także `gemini-embedding-2-preview` | | `outputDimensionality` | `number` | `3072` | Dla Embedding 2: 768, 1536 lub 3072 | -Zmiana modelu lub `outputDimensionality` uruchamia automatyczne pełne ponowne indeksowanie. +Zmiana modelu lub `outputDimensionality` powoduje automatyczne pełne przeindeksowanie. --- @@ -126,7 +127,7 @@ Zmiana modelu lub `outputDimensionality` uruchamia automatyczne pełne ponowne i ## Konfiguracja embeddingów Bedrock Bedrock używa domyślnego łańcucha poświadczeń AWS SDK -- nie są potrzebne klucze API. -Jeśli OpenClaw działa na EC2 z rolą instancji z włączonym Bedrock, po prostu ustaw +Jeśli OpenClaw działa na EC2 z rolą instancji z włączonym Bedrock, wystarczy ustawić dostawcę i model: ```json5 @@ -142,28 +143,28 @@ dostawcę i model: } ``` -| Klucz | Typ | Domyślnie | Opis | -| ---------------------- | -------- | ----------------------------- | --------------------------------- | -| `model` | `string` | `amazon.titan-embed-text-v2:0` | Dowolny identyfikator modelu embeddingów Bedrock | -| `outputDimensionality` | `number` | domyślna dla modelu | Dla Titan V2: 256, 512 lub 1024 | +| Key | Type | Default | Opis | +| ---------------------- | -------- | ------------------------------ | ------------------------------- | +| `model` | `string` | `amazon.titan-embed-text-v2:0` | Dowolny identyfikator modelu embeddingów Bedrock | +| `outputDimensionality` | `number` | domyślna wartość modelu | Dla Titan V2: 256, 512 lub 1024 | ### Obsługiwane modele Obsługiwane są następujące modele (z wykrywaniem rodziny i domyślnymi wymiarami): -| Id modelu | Dostawca | Domyślne wymiary | Konfigurowalne wymiary | -| ------------------------------------------ | ---------- | ---------------- | ---------------------- | -| `amazon.titan-embed-text-v2:0` | Amazon | 1024 | 256, 512, 1024 | -| `amazon.titan-embed-text-v1` | Amazon | 1536 | -- | -| `amazon.titan-embed-g1-text-02` | Amazon | 1536 | -- | -| `amazon.titan-embed-image-v1` | Amazon | 1024 | -- | -| `amazon.nova-2-multimodal-embeddings-v1:0` | Amazon | 1024 | 256, 384, 1024, 3072 | -| `cohere.embed-english-v3` | Cohere | 1024 | -- | -| `cohere.embed-multilingual-v3` | Cohere | 1024 | -- | -| `cohere.embed-v4:0` | Cohere | 1536 | 256-1536 | -| `twelvelabs.marengo-embed-3-0-v1:0` | TwelveLabs | 512 | -- | -| `twelvelabs.marengo-embed-2-7-v1:0` | TwelveLabs | 1024 | -- | +| Model ID | Provider | Default Dims | Configurable Dims | +| ------------------------------------------ | ---------- | ------------ | -------------------- | +| `amazon.titan-embed-text-v2:0` | Amazon | 1024 | 256, 512, 1024 | +| `amazon.titan-embed-text-v1` | Amazon | 1536 | -- | +| `amazon.titan-embed-g1-text-02` | Amazon | 1536 | -- | +| `amazon.titan-embed-image-v1` | Amazon | 1024 | -- | +| `amazon.nova-2-multimodal-embeddings-v1:0` | Amazon | 1024 | 256, 384, 1024, 3072 | +| `cohere.embed-english-v3` | Cohere | 1024 | -- | +| `cohere.embed-multilingual-v3` | Cohere | 1024 | -- | +| `cohere.embed-v4:0` | Cohere | 1536 | 256-1536 | +| `twelvelabs.marengo-embed-3-0-v1:0` | TwelveLabs | 512 | -- | +| `twelvelabs.marengo-embed-2-7-v1:0` | TwelveLabs | 1024 | -- | Warianty z sufiksem przepustowości (np. `amazon.titan-embed-text-v1:2:8k`) dziedziczą konfigurację modelu bazowego. @@ -174,12 +175,12 @@ Uwierzytelnianie Bedrock używa standardowej kolejności rozwiązywania poświad 1. Zmienne środowiskowe (`AWS_ACCESS_KEY_ID` + `AWS_SECRET_ACCESS_KEY`) 2. Pamięć podręczna tokenów SSO -3. Poświadczenia tokenu tożsamości web +3. Poświadczenia tokena tożsamości webowej 4. Współdzielone pliki poświadczeń i konfiguracji 5. Poświadczenia metadanych ECS lub EC2 -Region jest rozwiązywany z `AWS_REGION`, `AWS_DEFAULT_REGION`, `baseUrl` -dostawcy `amazon-bedrock` lub domyślnie przyjmuje wartość `us-east-1`. +Region jest rozwiązywany na podstawie `AWS_REGION`, `AWS_DEFAULT_REGION`, +`baseUrl` dostawcy `amazon-bedrock` lub domyślnie przyjmuje wartość `us-east-1`. ### Uprawnienia IAM @@ -201,14 +202,14 @@ arn:aws:bedrock:*::foundation-model/amazon.titan-embed-text-v2:0 --- -## Konfiguracja lokalnych embeddingów +## Konfiguracja embeddingów lokalnych -| Klucz | Typ | Domyślnie | Opis | -| --------------------- | -------- | ----------------------- | ----------------------------------- | -| `local.modelPath` | `string` | pobierany automatycznie | Ścieżka do pliku modelu GGUF | -| `local.modelCacheDir` | `string` | domyślna dla node-llama-cpp | Katalog cache dla pobranych modeli | +| Key | Type | Default | Opis | +| --------------------- | -------- | ---------------------- | ------------------------------- | +| `local.modelPath` | `string` | pobierany automatycznie | Ścieżka do pliku modelu GGUF | +| `local.modelCacheDir` | `string` | domyślna wartość node-llama-cpp | Katalog pamięci podręcznej dla pobranych modeli | -Domyślny model: `embeddinggemma-300m-qat-Q8_0.gguf` (~0,6 GB, pobierany automatycznie). +Domyślny model: `embeddinggemma-300m-qat-Q8_0.gguf` (~0.6 GB, pobierany automatycznie). Wymaga natywnego builda: `pnpm approve-builds`, a następnie `pnpm rebuild node-llama-cpp`. --- @@ -217,26 +218,26 @@ Wymaga natywnego builda: `pnpm approve-builds`, a następnie `pnpm rebuild node- Wszystko w `memorySearch.query.hybrid`: -| Klucz | Typ | Domyślnie | Opis | -| --------------------- | --------- | --------- | ------------------------------------ | -| `enabled` | `boolean` | `true` | Włącza hybrydowe wyszukiwanie BM25 + wektorowe | -| `vectorWeight` | `number` | `0.7` | Waga dla wyników wektorowych (0-1) | -| `textWeight` | `number` | `0.3` | Waga dla wyników BM25 (0-1) | -| `candidateMultiplier` | `number` | `4` | Mnożnik rozmiaru puli kandydatów | +| Key | Type | Default | Opis | +| --------------------- | --------- | ------- | ---------------------------------- | +| `enabled` | `boolean` | `true` | Włącza wyszukiwanie hybrydowe BM25 + wektorowe | +| `vectorWeight` | `number` | `0.7` | Waga dla wyników wektorowych (0-1) | +| `textWeight` | `number` | `0.3` | Waga dla wyników BM25 (0-1) | +| `candidateMultiplier` | `number` | `4` | Mnożnik rozmiaru puli kandydatów | ### MMR (różnorodność) -| Klucz | Typ | Domyślnie | Opis | -| ------------- | --------- | --------- | ----------------------------------------- | -| `mmr.enabled` | `boolean` | `false` | Włącza ponowne rangowanie MMR | -| `mmr.lambda` | `number` | `0.7` | 0 = maks. różnorodność, 1 = maks. trafność | +| Key | Type | Default | Opis | +| ------------- | --------- | ------- | ------------------------------------ | +| `mmr.enabled` | `boolean` | `false` | Włącza ponowne rankingowanie MMR | +| `mmr.lambda` | `number` | `0.7` | 0 = maksymalna różnorodność, 1 = maksymalna trafność | ### Zanik czasowy (świeżość) -| Klucz | Typ | Domyślnie | Opis | -| ---------------------------- | --------- | --------- | ------------------------------- | -| `temporalDecay.enabled` | `boolean` | `false` | Włącza wzmocnienie świeżości | -| `temporalDecay.halfLifeDays` | `number` | `30` | Wynik spada o połowę co N dni | +| Key | Type | Default | Opis | +| ---------------------------- | --------- | ------- | ------------------------- | +| `temporalDecay.enabled` | `boolean` | `false` | Włącza zwiększenie wyniku za świeżość | +| `temporalDecay.halfLifeDays` | `number` | `30` | Wynik zmniejsza się o połowę co N dni | Pliki evergreen (`MEMORY.md`, pliki bez daty w `memory/`) nigdy nie podlegają zanikowi. @@ -265,8 +266,8 @@ Pliki evergreen (`MEMORY.md`, pliki bez daty w `memory/`) nigdy nie podlegają z ## Dodatkowe ścieżki pamięci -| Klucz | Typ | Opis | -| ----------- | ---------- | ----------------------------------------- | +| Key | Type | Opis | +| ------------ | ---------- | ---------------------------------------- | | `extraPaths` | `string[]` | Dodatkowe katalogi lub pliki do indeksowania | ```json5 @@ -281,31 +282,33 @@ Pliki evergreen (`MEMORY.md`, pliki bez daty w `memory/`) nigdy nie podlegają z } ``` -Ścieżki mogą być bezwzględne lub względne względem obszaru roboczego. Katalogi są skanowane -rekurencyjnie w poszukiwaniu plików `.md`. Obsługa symlinków zależy od aktywnego backendu: -wbudowany silnik ignoruje symlinki, natomiast QMD stosuje zachowanie skanera QMD. +Ścieżki mogą być bezwzględne lub względne względem workspace. Katalogi są skanowane +rekurencyjnie w poszukiwaniu plików `.md`. Obsługa dowiązań symbolicznych zależy od aktywnego backendu: +wbudowany silnik ignoruje dowiązania symboliczne, podczas gdy QMD stosuje zachowanie +bazowego skanera QMD. -W przypadku wyszukiwania transkryptów między agentami o zakresie agenta użyj +W przypadku wyszukiwania transkryptów między agentami w zakresie agenta użyj `agents.list[].memorySearch.qmd.extraCollections` zamiast `memory.qmd.paths`. -Te dodatkowe kolekcje używają tego samego kształtu `{ path, name, pattern? }`, ale -są scalane per agent i mogą zachować jawne współdzielone nazwy, gdy ścieżka -wskazuje poza bieżący obszar roboczy. -Jeśli ta sama rozwiązana ścieżka pojawia się zarówno w `memory.qmd.paths`, jak i -`memorySearch.qmd.extraCollections`, QMD zachowuje pierwszy wpis i pomija duplikat. +Te dodatkowe kolekcje mają ten sam kształt `{ path, name, pattern? }`, ale +są scalane dla każdego agenta i mogą zachować jawne współdzielone nazwy, gdy ścieżka +wskazuje poza bieżący workspace. +Jeśli ta sama rozwiązana ścieżka pojawi się zarówno w `memory.qmd.paths`, jak i w +`memorySearch.qmd.extraCollections`, QMD zachowuje pierwszy wpis i pomija +duplikat. --- ## Pamięć multimodalna (Gemini) -Indeksuj obrazy i audio obok Markdown przy użyciu Gemini Embedding 2: +Indeksuj obrazy i audio razem z Markdownem za pomocą Gemini Embedding 2: -| Klucz | Typ | Domyślnie | Opis | -| ------------------------- | ---------- | ---------- | ---------------------------------------- | -| `multimodal.enabled` | `boolean` | `false` | Włącza indeksowanie multimodalne | -| `multimodal.modalities` | `string[]` | -- | `["image"]`, `["audio"]` lub `["all"]` | -| `multimodal.maxFileBytes` | `number` | `10000000` | Maksymalny rozmiar pliku do indeksowania | +| Key | Type | Default | Opis | +| ------------------------- | ---------- | ---------- | -------------------------------------- | +| `multimodal.enabled` | `boolean` | `false` | Włącza indeksowanie multimodalne | +| `multimodal.modalities` | `string[]` | -- | `["image"]`, `["audio"]` lub `["all"]` | +| `multimodal.maxFileBytes` | `number` | `10000000` | Maksymalny rozmiar pliku do indeksowania | -Dotyczy tylko plików w `extraPaths`. Domyślne katalogi główne pamięci pozostają tylko dla Markdown. +Dotyczy tylko plików w `extraPaths`. Domyślne korzenie pamięci pozostają tylko dla Markdowna. Wymaga `gemini-embedding-2-preview`. `fallback` musi mieć wartość `"none"`. Obsługiwane formaty: `.jpg`, `.jpeg`, `.png`, `.webp`, `.gif`, `.heic`, `.heif` @@ -315,64 +318,64 @@ Obsługiwane formaty: `.jpg`, `.jpeg`, `.png`, `.webp`, `.gif`, `.heic`, `.heif` ## Cache embeddingów -| Klucz | Typ | Domyślnie | Opis | -| ------------------ | --------- | --------- | ----------------------------------- | -| `cache.enabled` | `boolean` | `false` | Buforuje embeddingi chunków w SQLite | -| `cache.maxEntries` | `number` | `50000` | Maksymalna liczba buforowanych embeddingów | +| Key | Type | Default | Opis | +| ------------------ | --------- | ------- | -------------------------------- | +| `cache.enabled` | `boolean` | `false` | Buforuje embeddingi chunków w SQLite | +| `cache.maxEntries` | `number` | `50000` | Maksymalna liczba buforowanych embeddingów | -Zapobiega ponownemu tworzeniu embeddingów dla niezmienionego tekstu podczas ponownego indeksowania lub aktualizacji transkryptów. +Zapobiega ponownemu tworzeniu embeddingów dla niezmienionego tekstu podczas przeindeksowania lub aktualizacji transkryptów. --- ## Indeksowanie wsadowe -| Klucz | Typ | Domyślnie | Opis | -| ----------------------------- | --------- | --------- | ---------------------------- | -| `remote.batch.enabled` | `boolean` | `false` | Włącza API embeddingów wsadowych | -| `remote.batch.concurrency` | `number` | `2` | Równoległe zadania wsadowe | -| `remote.batch.wait` | `boolean` | `true` | Czeka na zakończenie wsadu | -| `remote.batch.pollIntervalMs` | `number` | -- | Interwał odpytywania | -| `remote.batch.timeoutMinutes` | `number` | -- | Limit czasu wsadu | +| Key | Type | Default | Opis | +| ----------------------------- | --------- | ------- | -------------------------- | +| `remote.batch.enabled` | `boolean` | `false` | Włącza wsadowe API embeddingów | +| `remote.batch.concurrency` | `number` | `2` | Równoległe zadania wsadowe | +| `remote.batch.wait` | `boolean` | `true` | Czeka na zakończenie wsadu | +| `remote.batch.pollIntervalMs` | `number` | -- | Interwał odpytywania | +| `remote.batch.timeoutMinutes` | `number` | -- | Limit czasu wsadu | -Dostępne dla `openai`, `gemini` i `voyage`. Wsad OpenAI jest zazwyczaj -najszybszy i najtańszy przy dużych uzupełnieniach danych. +Dostępne dla `openai`, `gemini` i `voyage`. Wsady OpenAI są zazwyczaj +najszybsze i najtańsze przy dużych backfillach. --- ## Wyszukiwanie pamięci sesji (eksperymentalne) -Indeksuj transkrypcje sesji i udostępniaj je przez `memory_search`: +Indeksuj transkrypty sesji i udostępniaj je przez `memory_search`: -| Klucz | Typ | Domyślnie | Opis | -| --------------------------- | ---------- | ------------ | ------------------------------------------ | -| `experimental.sessionMemory` | `boolean` | `false` | Włącza indeksowanie sesji | -| `sources` | `string[]` | `["memory"]` | Dodaj `"sessions"`, aby uwzględnić transkrypty | -| `sync.sessions.deltaBytes` | `number` | `100000` | Próg bajtów dla ponownego indeksowania | -| `sync.sessions.deltaMessages` | `number` | `50` | Próg liczby wiadomości dla ponownego indeksowania | +| Key | Type | Default | Opis | +| ----------------------------- | ---------- | ------------ | --------------------------------------- | +| `experimental.sessionMemory` | `boolean` | `false` | Włącza indeksowanie sesji | +| `sources` | `string[]` | `["memory"]` | Dodaj `"sessions"`, aby uwzględnić transkrypty | +| `sync.sessions.deltaBytes` | `number` | `100000` | Próg bajtów do przeindeksowania | +| `sync.sessions.deltaMessages` | `number` | `50` | Próg wiadomości do przeindeksowania | -Indeksowanie sesji jest opt-in i działa asynchronicznie. Wyniki mogą być nieco -nieaktualne. Logi sesji są przechowywane na dysku, więc traktuj dostęp do systemu plików jako granicę zaufania. +Indeksowanie sesji jest opcjonalne i działa asynchronicznie. Wyniki mogą być nieco +nieaktualne. Logi sesji są przechowywane na dysku, więc dostęp do systemu plików należy traktować jako granicę zaufania. --- -## Przyspieszenie wektorowe SQLite (`sqlite-vec`) +## Akceleracja wektorowa SQLite (`sqlite-vec`) -| Klucz | Typ | Domyślnie | Opis | -| ------------------------ | --------- | --------- | ------------------------------------- | -| `store.vector.enabled` | `boolean` | `true` | Używa `sqlite-vec` do zapytań wektorowych | -| `store.vector.extensionPath` | `string` | bundlowane | Nadpisuje ścieżkę `sqlite-vec` | +| Key | Type | Default | Opis | +| ---------------------------- | --------- | ------- | --------------------------------- | +| `store.vector.enabled` | `boolean` | `true` | Używa `sqlite-vec` do zapytań wektorowych | +| `store.vector.extensionPath` | `string` | bundled | Nadpisuje ścieżkę `sqlite-vec` | -Gdy `sqlite-vec` nie jest dostępne, OpenClaw automatycznie przechodzi na obliczanie -podobieństwa cosinusowego w procesie. +Gdy `sqlite-vec` jest niedostępne, OpenClaw automatycznie przechodzi na +podobieństwo cosinusowe w procesie. --- -## Przechowywanie indeksu +## Magazyn indeksu -| Klucz | Typ | Domyślnie | Opis | -| -------------------- | -------- | ------------------------------------- | -------------------------------------------- | -| `store.path` | `string` | `~/.openclaw/memory/{agentId}.sqlite` | Lokalizacja indeksu (obsługuje token `{agentId}`) | -| `store.fts.tokenizer` | `string` | `unicode61` | Tokenizer FTS5 (`unicode61` lub `trigram`) | +| Key | Type | Default | Opis | +| --------------------- | -------- | ------------------------------------- | ------------------------------------------- | +| `store.path` | `string` | `~/.openclaw/memory/{agentId}.sqlite` | Lokalizacja indeksu (obsługuje token `{agentId}`) | +| `store.fts.tokenizer` | `string` | `unicode61` | Tokenizer FTS5 (`unicode61` lub `trigram`) | --- @@ -381,45 +384,46 @@ podobieństwa cosinusowego w procesie. Ustaw `memory.backend = "qmd"`, aby włączyć. Wszystkie ustawienia QMD znajdują się w `memory.qmd`: -| Klucz | Typ | Domyślnie | Opis | -| ----------------------- | --------- | --------- | --------------------------------------------- | -| `command` | `string` | `qmd` | Ścieżka wykonywalna QMD | -| `searchMode` | `string` | `search` | Polecenie wyszukiwania: `search`, `vsearch`, `query` | -| `includeDefaultMemory` | `boolean` | `true` | Automatycznie indeksuje `MEMORY.md` + `memory/**/*.md` | -| `paths[]` | `array` | -- | Dodatkowe ścieżki: `{ name, path, pattern? }` | -| `sessions.enabled` | `boolean` | `false` | Indeksuje transkrypty sesji | -| `sessions.retentionDays` | `number` | -- | Retencja transkryptów | -| `sessions.exportDir` | `string` | -- | Katalog eksportu | +| Key | Type | Default | Opis | +| ------------------------ | --------- | -------- | -------------------------------------------- | +| `command` | `string` | `qmd` | Ścieżka do pliku wykonywalnego QMD | +| `searchMode` | `string` | `search` | Polecenie wyszukiwania: `search`, `vsearch`, `query` | +| `includeDefaultMemory` | `boolean` | `true` | Automatycznie indeksuje `MEMORY.md` + `memory/**/*.md` | +| `paths[]` | `array` | -- | Dodatkowe ścieżki: `{ name, path, pattern? }` | +| `sessions.enabled` | `boolean` | `false` | Indeksuje transkrypty sesji | +| `sessions.retentionDays` | `number` | -- | Retencja transkryptów | +| `sessions.exportDir` | `string` | -- | Katalog eksportu | -OpenClaw preferuje bieżące kształty kolekcji QMD i zapytań MCP, ale utrzymuje -zgodność ze starszymi wydaniami QMD, przechodząc awaryjnie na starsze flagi kolekcji `--mask` -i starsze nazwy narzędzi MCP, gdy jest to potrzebne. +OpenClaw preferuje bieżące kształty kolekcji QMD i zapytań MCP, ale nadal +obsługuje starsze wydania QMD, wracając w razie potrzeby do starszych flag kolekcji `--mask` +i starszych nazw narzędzi MCP. Nadpisania modeli QMD pozostają po stronie QMD, a nie w konfiguracji OpenClaw. Jeśli chcesz globalnie nadpisać modele QMD, ustaw zmienne środowiskowe takie jak -`QMD_EMBED_MODEL`, `QMD_RERANK_MODEL` i `QMD_GENERATE_MODEL` w środowisku uruchomieniowym Gateway. +`QMD_EMBED_MODEL`, `QMD_RERANK_MODEL` i `QMD_GENERATE_MODEL` w środowisku +runtime Gateway. ### Harmonogram aktualizacji -| Klucz | Typ | Domyślnie | Opis | -| ------------------------- | --------- | --------- | ----------------------------------------- | -| `update.interval` | `string` | `5m` | Interwał odświeżania | -| `update.debounceMs` | `number` | `15000` | Debounce zmian plików | -| `update.onBoot` | `boolean` | `true` | Odświeżanie przy starcie | -| `update.waitForBootSync` | `boolean` | `false` | Blokuje start do zakończenia odświeżenia | -| `update.embedInterval` | `string` | -- | Osobny harmonogram embeddingów | -| `update.commandTimeoutMs` | `number` | -- | Limit czasu dla poleceń QMD | -| `update.updateTimeoutMs` | `number` | -- | Limit czasu dla operacji aktualizacji QMD | -| `update.embedTimeoutMs` | `number` | -- | Limit czasu dla operacji embeddingów QMD | +| Key | Type | Default | Opis | +| ------------------------- | --------- | ------- | ------------------------------------- | +| `update.interval` | `string` | `5m` | Interwał odświeżania | +| `update.debounceMs` | `number` | `15000` | Debounce zmian plików | +| `update.onBoot` | `boolean` | `true` | Odświeża przy starcie | +| `update.waitForBootSync` | `boolean` | `false` | Blokuje start do czasu zakończenia odświeżenia | +| `update.embedInterval` | `string` | -- | Oddzielny harmonogram embeddingu | +| `update.commandTimeoutMs` | `number` | -- | Limit czasu dla poleceń QMD | +| `update.updateTimeoutMs` | `number` | -- | Limit czasu dla operacji aktualizacji QMD | +| `update.embedTimeoutMs` | `number` | -- | Limit czasu dla operacji embeddingu QMD | ### Limity -| Klucz | Typ | Domyślnie | Opis | -| ------------------------- | -------- | --------- | ------------------------------- | -| `limits.maxResults` | `number` | `6` | Maksymalna liczba wyników wyszukiwania | -| `limits.maxSnippetChars` | `number` | -- | Ogranicza długość fragmentu | -| `limits.maxInjectedChars` | `number` | -- | Ogranicza łączną liczbę wstrzykniętych znaków | -| `limits.timeoutMs` | `number` | `4000` | Limit czasu wyszukiwania | +| Key | Type | Default | Opis | +| ------------------------- | -------- | ------- | -------------------------- | +| `limits.maxResults` | `number` | `6` | Maksymalna liczba wyników wyszukiwania | +| `limits.maxSnippetChars` | `number` | -- | Ogranicza długość fragmentu | +| `limits.maxInjectedChars` | `number` | -- | Ogranicza łączną liczbę wstrzykniętych znaków | +| `limits.timeoutMs` | `number` | `4000` | Limit czasu wyszukiwania | ### Zakres @@ -439,21 +443,21 @@ Kontroluje, które sesje mogą otrzymywać wyniki wyszukiwania QMD. Ten sam sche } ``` -Dostarczana domyślna konfiguracja dopuszcza sesje bezpośrednie i kanałowe, nadal odrzucając +Dostarczana domyślna konfiguracja dopuszcza sesje direct i channel, nadal odrzucając grupy. -Domyślnie tylko DM. `match.keyPrefix` dopasowuje znormalizowany klucz sesji; -`match.rawKeyPrefix` dopasowuje surowy klucz, włącznie z `agent::`. +Wartością domyślną jest tylko DM. `match.keyPrefix` dopasowuje znormalizowany klucz sesji; +`match.rawKeyPrefix` dopasowuje surowy klucz, w tym `agent::`. ### Cytowania `memory.citations` dotyczy wszystkich backendów: -| Wartość | Zachowanie | -| ---------------- | -------------------------------------------------- | -| `auto` (domyślnie) | Dodaje stopkę `Source: ` w fragmentach | -| `on` | Zawsze dodaje stopkę | -| `off` | Pomija stopkę (ścieżka nadal jest wewnętrznie przekazywana agentowi) | +| Value | Behavior | +| ---------------- | --------------------------------------------------- | +| `auto` (domyślnie) | Dołącza stopkę `Source: ` do fragmentów | +| `on` | Zawsze dołącza stopkę | +| `off` | Pomija stopkę (ścieżka nadal jest przekazywana wewnętrznie do agenta) | ### Pełny przykład QMD @@ -483,17 +487,17 @@ Domyślnie tylko DM. `match.keyPrefix` dopasowuje znormalizowany klucz sesji; Dreaming jest konfigurowane w `plugins.entries.memory-core.config.dreaming`, a nie w `agents.defaults.memorySearch`. -Dreaming działa jako jeden zaplanowany przebieg i wykorzystuje wewnętrzne fazy light/deep/REM jako -szczegół implementacyjny. +Dreaming działa jako jeden zaplanowany przebieg i używa wewnętrznych faz light/deep/REM jako +szczegółu implementacyjnego. -Aby poznać zachowanie koncepcyjne i polecenia slash, zobacz [Dreaming](/pl/concepts/dreaming). +Opis zachowania koncepcyjnego i poleceń slash znajdziesz w [Dreaming](/pl/concepts/dreaming). ### Ustawienia użytkownika -| Klucz | Typ | Domyślnie | Opis | -| ---------- | --------- | ------------ | -------------------------------------------------- | -| `enabled` | `boolean` | `false` | Całkowicie włącza lub wyłącza Dreaming | -| `frequency` | `string` | `0 3 * * *` | Opcjonalna składnia Cron dla pełnego przebiegu Dreaming | +| Key | Type | Default | Opis | +| ----------- | --------- | ----------- | ------------------------------------------------- | +| `enabled` | `boolean` | `false` | Włącza lub wyłącza Dreaming całkowicie | +| `frequency` | `string` | `0 3 * * *` | Opcjonalny harmonogram Cron dla pełnego przebiegu Dreaming | ### Przykład @@ -517,5 +521,5 @@ Aby poznać zachowanie koncepcyjne i polecenia slash, zobacz [Dreaming](/pl/conc Uwagi: - Dreaming zapisuje stan maszyny do `memory/.dreams/`. -- Dreaming zapisuje czytelne dla człowieka wyjście narracyjne do `DREAMS.md` (lub istniejącego `dreams.md`). -- Zasady i progi faz light/deep/REM są zachowaniem wewnętrznym, a nie konfiguracją skierowaną do użytkownika. +- Dreaming zapisuje czytelne dla człowieka dane narracyjne do `DREAMS.md` (lub istniejącego `dreams.md`). +- Polityka faz light/deep/REM i progi są zachowaniem wewnętrznym, a nie konfiguracją dostępną dla użytkownika. diff --git a/docs/pl/reference/secretref-credential-surface.md b/docs/pl/reference/secretref-credential-surface.md index ff25c468c..126a8646d 100644 --- a/docs/pl/reference/secretref-credential-surface.md +++ b/docs/pl/reference/secretref-credential-surface.md @@ -1,15 +1,15 @@ --- read_when: - - Weryfikowanie zakresu poświadczeń SecretRef + - Weryfikowanie zakresu obsługi poświadczeń SecretRef - Sprawdzanie, czy poświadczenie kwalifikuje się do `secrets configure` lub `secrets apply` - - Weryfikowanie, dlaczego poświadczenie jest poza obsługiwaną powierzchnią -summary: Kanoniczna powierzchnia obsługiwanych i nieobsługiwanych poświadczeń SecretRef + - Weryfikowanie, dlaczego poświadczenie znajduje się poza obsługiwaną powierzchnią +summary: Kanoniczna obsługiwana i nieobsługiwana powierzchnia poświadczeń SecretRef title: Powierzchnia poświadczeń SecretRef x-i18n: - generated_at: "2026-04-07T09:49:31Z" + generated_at: "2026-04-15T09:52:14Z" model: gpt-5.4 provider: openai - source_hash: 211f4b504c5808f7790683066fc2c8b700c705c598f220a264daf971b81cc593 + source_hash: dd0b9c379236b17a72f552d6360b8b5a2269009e019c138c6bb50f4f7328ddaf source_path: reference/secretref-credential-surface.md workflow: 15 --- @@ -18,10 +18,10 @@ x-i18n: Ta strona definiuje kanoniczną powierzchnię poświadczeń SecretRef. -Cel zakresu: +Zakres: -- W zakresie: ściśle poświadczenia dostarczane przez użytkownika, których OpenClaw nie tworzy ani nie rotuje. -- Poza zakresem: poświadczenia tworzone w runtime lub rotowane, materiały odświeżania OAuth oraz artefakty podobne do sesji. +- W zakresie: wyłącznie poświadczenia dostarczane przez użytkownika, których OpenClaw nie wystawia ani nie rotuje. +- Poza zakresem: poświadczenia wystawiane lub rotowane w czasie działania, materiały odświeżania OAuth oraz artefakty podobne do sesji. ## Obsługiwane poświadczenia @@ -49,6 +49,7 @@ Cel zakresu: - `messages.tts.providers.*.apiKey` - `tools.web.fetch.firecrawl.apiKey` - `plugins.entries.brave.config.webSearch.apiKey` +- `plugins.entries.exa.config.webSearch.apiKey` - `plugins.entries.google.config.webSearch.apiKey` - `plugins.entries.xai.config.webSearch.apiKey` - `plugins.entries.moonshot.config.webSearch.apiKey` @@ -107,8 +108,8 @@ Cel zakresu: - `channels.zalo.webhookSecret` - `channels.zalo.accounts.*.botToken` - `channels.zalo.accounts.*.webhookSecret` -- `channels.googlechat.serviceAccount` przez sąsiedni `serviceAccountRef` (wyjątek zgodności) -- `channels.googlechat.accounts.*.serviceAccount` przez sąsiedni `serviceAccountRef` (wyjątek zgodności) +- `channels.googlechat.serviceAccount` przez sąsiednie `serviceAccountRef` (wyjątek zgodności) +- `channels.googlechat.accounts.*.serviceAccount` przez sąsiednie `serviceAccountRef` (wyjątek zgodności) ### Cele `auth-profiles.json` (`secrets configure` + `secrets apply` + `secrets audit`) @@ -120,16 +121,16 @@ Cel zakresu: Uwagi: - Cele planu profili uwierzytelniania wymagają `agentId`. -- Wpisy planu są kierowane do `profiles.*.key` / `profiles.*.token` i zapisują sąsiednie referencje (`keyRef` / `tokenRef`). -- Referencje profili uwierzytelniania są uwzględnione w rozwiązywaniu runtime i zakresie audytu. -- Ochrona polityki OAuth: `auth.profiles..mode = "oauth"` nie może być łączone z wejściami SecretRef dla tego profilu. Uruchomienie/przeładowanie oraz rozwiązywanie profilu uwierzytelniania kończą się błędem natychmiast po naruszeniu tej polityki. -- Dla dostawców modeli zarządzanych przez SecretRef wygenerowane wpisy `agents/*/agent/models.json` zapisują znaczniki niebędące sekretami (a nie rozpoznane wartości sekretów) dla powierzchni `apiKey`/nagłówków. -- Trwałość znaczników jest źródłowo autorytatywna: OpenClaw zapisuje znaczniki z aktywnego snapshotu konfiguracji źródłowej (przed rozpoznaniem), a nie z rozpoznanych wartości sekretów runtime. +- Wpisy planu wskazują na `profiles.*.key` / `profiles.*.token` i zapisują sąsiednie referencje (`keyRef` / `tokenRef`). +- Referencje profili uwierzytelniania są uwzględniane podczas rozwiązywania w czasie działania i w zakresie audytu. +- Ograniczenie zasad OAuth: `auth.profiles..mode = "oauth"` nie może być łączone z wejściami SecretRef dla tego profilu. Uruchomienie/przeładowanie oraz rozwiązywanie profilu uwierzytelniania kończą się błędem natychmiast po naruszeniu tej zasady. +- Dla dostawców modeli zarządzanych przez SecretRef wygenerowane wpisy `agents/*/agent/models.json` zapisują znaczniki niesekretne (a nie rozwiązane wartości sekretów) dla powierzchni `apiKey`/nagłówków. +- Trwałość znaczników jest autorytatywna względem źródła: OpenClaw zapisuje znaczniki z aktywnego snapshotu konfiguracji źródłowej (przed rozwiązaniem), a nie z rozwiązanych wartości sekretów w czasie działania. - Dla wyszukiwania w sieci: - W trybie jawnego dostawcy (ustawione `tools.web.search.provider`) aktywny jest tylko klucz wybranego dostawcy. - - W trybie auto (nieustawione `tools.web.search.provider`) aktywny jest tylko pierwszy klucz dostawcy, który zostanie rozpoznany zgodnie z priorytetem. - - W trybie auto referencje niewybranych dostawców są traktowane jako nieaktywne, dopóki nie zostaną wybrane. - - Starsze ścieżki dostawców `tools.web.search.*` nadal są rozpoznawane w oknie zgodności, ale kanoniczną powierzchnią SecretRef jest `plugins.entries..config.webSearch.*`. + - W trybie automatycznym (nieustawione `tools.web.search.provider`) aktywny jest tylko pierwszy klucz dostawcy, który rozwiąże się zgodnie z kolejnością pierwszeństwa. + - W trybie automatycznym referencje niewybranych dostawców są traktowane jako nieaktywne do momentu wyboru. + - Starsze ścieżki dostawców `tools.web.search.*` nadal rozwiązują się w okresie zgodności, ale kanoniczną powierzchnią SecretRef jest `plugins.entries..config.webSearch.*`. ## Nieobsługiwane poświadczenia @@ -151,4 +152,4 @@ Poświadczenia poza zakresem obejmują: Uzasadnienie: -- Te poświadczenia są tworzone, rotowane, niosą stan sesji albo należą do trwałych klas OAuth, które nie pasują do wyłącznie odczytowego zewnętrznego rozwiązywania SecretRef. +- Te poświadczenia należą do klas wystawianych, rotowanych, sesyjnych lub trwałych OAuth, które nie pasują do rozwiązywania zewnętrznego SecretRef tylko do odczytu. diff --git a/docs/pl/start/showcase.md b/docs/pl/start/showcase.md index bfacc712a..264c79afa 100644 --- a/docs/pl/start/showcase.md +++ b/docs/pl/start/showcase.md @@ -1,130 +1,157 @@ --- +description: Real-world OpenClaw projects from the community read_when: - - Szukasz prawdziwych przykładów użycia OpenClaw - - Aktualizujesz wyróżnienia projektów społeczności -summary: Projekty i integracje stworzone przez społeczność z użyciem OpenClaw -title: Prezentacje + - Szukasz rzeczywistych przykładów użycia OpenClaw + - Aktualizowanie wyróżnionych projektów społecznościowych +summary: Projekty i integracje tworzone przez społeczność, oparte na OpenClaw +title: Prezentacja x-i18n: - generated_at: "2026-04-05T14:07:03Z" + generated_at: "2026-04-15T09:52:26Z" model: gpt-5.4 provider: openai - source_hash: 2917e9a476ef527ddb3e51c610bbafbd145e705c9cc29f191639fb63d238ef70 + source_hash: 797d0b85c9eca920240c79d870eb9636216714f3eba871c5ebd0f7f40cf7bbf1 source_path: start/showcase.md workflow: 15 --- -# Prezentacje + -Prawdziwe projekty społeczności. Zobacz, co ludzie budują z OpenClaw. +# Prezentacja + +
+

Tworzone w czatach, terminalach, przeglądarkach i salonach

+

+ Projekty OpenClaw to nie są zabawkowe dema. Ludzie wdrażają pętle przeglądu PR, aplikacje mobilne, automatykę domową, + systemy głosowe, narzędzia deweloperskie i przepływy pracy intensywnie korzystające z pamięci z kanałów, których już używają. +

+ +
+
+ Tworzenie natywne dla czatu + Telegram, WhatsApp, Discord, Beeper, czat webowy i przepływy pracy z terminalem na pierwszym planie. +
+
+ Prawdziwa automatyzacja + Rezerwacje, zakupy, wsparcie, raportowanie i sterowanie przeglądarką bez czekania na API. +
+
+ Świat lokalny i fizyczny + Drukarki, odkurzacze, kamery, dane zdrowotne, systemy domowe i osobiste bazy wiedzy. +
+
+
-**Chcesz się tu znaleźć?** Udostępnij swój projekt w [#self-promotion na Discordzie](https://discord.gg/clawd) lub [oznacz @openclaw na X](https://x.com/openclaw). +**Chcesz zostać wyróżniony?** Udostępnij swój projekt w [#self-promotion na Discordzie](https://discord.gg/clawd) albo [oznacz @openclaw na X](https://x.com/openclaw). -## 🎥 OpenClaw w akcji - -Pełny przewodnik konfiguracji (28 min) autorstwa VelvetShark. - -
-