From b31940bd086c5006e3e0bd772f22767eb0cb6eef Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Wed, 8 Apr 2026 02:21:30 +0000 Subject: [PATCH] chore(i18n): refresh pl translations --- docs/pl/channels/matrix.md | 666 +++---- docs/pl/concepts/compaction.md | 145 +- docs/pl/concepts/qa-e2e-automation.md | 68 +- docs/pl/concepts/system-prompt.md | 169 +- docs/pl/gateway/configuration-reference.md | 988 +++++------ docs/pl/gateway/doctor.md | 411 ++--- docs/pl/gateway/heartbeat.md | 315 ++-- docs/pl/gateway/local-models.md | 76 +- docs/pl/gateway/protocol.md | 430 ++--- docs/pl/gateway/troubleshooting.md | 301 ++-- docs/pl/help/faq.md | 1541 ++++++++--------- docs/pl/help/scripts.md | 48 +- docs/pl/help/testing.md | 643 +++---- docs/pl/help/troubleshooting.md | 255 +-- docs/pl/plugins/architecture.md | 1290 +++++++------- docs/pl/plugins/sdk-channel-plugins.md | 352 ++-- docs/pl/plugins/sdk-migration.md | 470 ++--- docs/pl/plugins/sdk-overview.md | 506 +++--- docs/pl/providers/index.md | 45 +- docs/pl/providers/inferrs.md | 179 ++ docs/pl/providers/nvidia.md | 33 +- docs/pl/providers/ollama.md | 126 +- docs/pl/refactor/qa.md | 534 ++++++ .../session-management-compaction.md | 237 +-- docs/pl/tools/acp-agents.md | 515 +++--- docs/pl/tools/exec-approvals.md | 431 ++--- 26 files changed, 5843 insertions(+), 4931 deletions(-) create mode 100644 docs/pl/providers/inferrs.md create mode 100644 docs/pl/refactor/qa.md diff --git a/docs/pl/channels/matrix.md b/docs/pl/channels/matrix.md index 4779aa8a6..1e5c69f22 100644 --- a/docs/pl/channels/matrix.md +++ b/docs/pl/channels/matrix.md @@ -1,59 +1,59 @@ --- read_when: - Konfigurowanie Matrix w OpenClaw - - Konfigurowanie E2EE i weryfikacji w Matrix -summary: Status obsługi Matrix, konfiguracja i przykłady ustawień + - Konfigurowanie E2EE i weryfikacji Matrix +summary: Stan obsługi Matrix, konfiguracja i przykłady ustawień title: Matrix x-i18n: - generated_at: "2026-04-07T09:46:36Z" + generated_at: "2026-04-08T02:17:08Z" model: gpt-5.4 provider: openai - source_hash: d53baa2ea5916cd00a99cae0ded3be41ffa13c9a69e8ea8461eb7baa6a99e13c + source_hash: ec926df79a41fa296d63f0ec7219d0f32e075628d76df9ea490e93e4c5030f83 source_path: channels/matrix.md workflow: 15 --- # Matrix -Matrix to dołączony plugin kanału Matrix dla OpenClaw. -Używa oficjalnego `matrix-js-sdk` i obsługuje DM-y, pokoje, wątki, multimedia, reakcje, ankiety, lokalizację oraz E2EE. +Matrix to dołączona wtyczka kanału Matrix dla OpenClaw. +Korzysta z oficjalnego `matrix-js-sdk` i obsługuje wiadomości prywatne, pokoje, wątki, multimedia, reakcje, ankiety, lokalizację oraz E2EE. -## Dołączony plugin +## Dołączona wtyczka -Matrix jest dostarczany jako dołączony plugin w bieżących wydaniach OpenClaw, więc zwykłe -spakowane buildy nie wymagają osobnej instalacji. +Matrix jest dostarczany jako dołączona wtyczka w aktualnych wydaniach OpenClaw, więc zwykłe +spakowane kompilacje nie wymagają osobnej instalacji. -Jeśli używasz starszego builda lub niestandardowej instalacji, która nie zawiera Matrix, zainstaluj +Jeśli używasz starszej kompilacji lub niestandardowej instalacji, która nie zawiera Matrix, zainstaluj go ręcznie: -Zainstaluj z npm: +Instalacja z npm: ```bash openclaw plugins install @openclaw/matrix ``` -Zainstaluj z lokalnego checkoutu: +Instalacja z lokalnego checkoutu: ```bash openclaw plugins install ./path/to/local/matrix-plugin ``` -Zobacz [Plugins](/pl/tools/plugin), aby poznać zachowanie pluginów i zasady instalacji. +Zobacz [Wtyczki](/pl/tools/plugin), aby poznać zachowanie wtyczek i zasady instalacji. ## Konfiguracja -1. Upewnij się, że plugin Matrix jest dostępny. - - Bieżące spakowane wydania OpenClaw już go zawierają. - - Starsze/niestandardowe instalacje mogą dodać go ręcznie za pomocą powyższych poleceń. +1. Upewnij się, że wtyczka Matrix jest dostępna. + - Aktualne spakowane wydania OpenClaw już ją zawierają. + - Starsze/niestandardowe instalacje mogą dodać ją ręcznie za pomocą powyższych poleceń. 2. Utwórz konto Matrix na swoim homeserverze. 3. Skonfiguruj `channels.matrix`, używając jednego z wariantów: - - `homeserver` + `accessToken`, albo + - `homeserver` + `accessToken`, lub - `homeserver` + `userId` + `password`. 4. Uruchom ponownie gateway. -5. Rozpocznij DM z botem albo zaproś go do pokoju. - - Nowe zaproszenia w Matrix działają tylko wtedy, gdy zezwala na to `channels.matrix.autoJoin`. +5. Rozpocznij wiadomość prywatną z botem albo zaproś go do pokoju. + - Nowe zaproszenia Matrix działają tylko wtedy, gdy `channels.matrix.autoJoin` na to pozwala. -Interaktywne ścieżki konfiguracji: +Ścieżki konfiguracji interaktywnej: ```bash openclaw channels add @@ -63,36 +63,36 @@ openclaw configure --section channels O co dokładnie pyta kreator Matrix: - URL homeservera -- metoda uwierzytelniania: access token albo hasło -- ID użytkownika tylko wtedy, gdy wybierzesz uwierzytelnianie hasłem +- metoda uwierzytelniania: token dostępu lub hasło +- identyfikator użytkownika tylko wtedy, gdy wybierzesz uwierzytelnianie hasłem - opcjonalna nazwa urządzenia - czy włączyć E2EE -- czy skonfigurować teraz dostęp do pokoju Matrix +- czy skonfigurować teraz dostęp do pokojów Matrix - czy skonfigurować teraz automatyczne dołączanie do zaproszeń Matrix -- gdy automatyczne dołączanie do zaproszeń jest włączone, czy ma to być `allowlist`, `always`, czy `off` +- gdy automatyczne dołączanie do zaproszeń jest włączone, czy ma mieć wartość `allowlist`, `always` czy `off` -Ważne zachowanie kreatora: +Istotne zachowanie kreatora: -- Jeśli dla wybranego konta istnieją już zmienne środowiskowe uwierzytelniania Matrix, a to konto nie ma jeszcze zapisanych danych uwierzytelniających w configu, kreator oferuje skrót przez env, aby konfiguracja mogła zachować uwierzytelnianie w zmiennych środowiskowych zamiast kopiować sekrety do configu. -- Gdy interaktywnie dodajesz kolejne konto Matrix, wpisana nazwa konta jest normalizowana do ID konta używanego w configu i zmiennych środowiskowych. Na przykład `Ops Bot` staje się `ops-bot`. -- Prompty allowlisty dla DM akceptują od razu pełne wartości `@user:server`. Same nazwy wyświetlane działają tylko wtedy, gdy wyszukiwanie w katalogu na żywo znajdzie dokładnie jedno dopasowanie; w przeciwnym razie kreator poprosi o ponowną próbę z pełnym ID Matrix. -- Prompty allowlisty pokoju akceptują bezpośrednio ID pokoi i aliasy. Mogą także rozwiązywać nazwy dołączonych pokoi na żywo, ale nierozwiązane nazwy są podczas konfiguracji zachowywane tylko w wpisanej postaci i później są ignorowane przez rozwiązywanie allowlisty w runtime. Preferuj `!room:server` lub `#alias:server`. -- Kreator pokazuje teraz wyraźne ostrzeżenie przed krokiem automatycznego dołączania do zaproszeń, ponieważ `channels.matrix.autoJoin` domyślnie ma wartość `off`; agenty nie dołączą do zaproszonych pokoi ani nowych zaproszeń typu DM, jeśli tego nie ustawisz. -- W trybie allowlisty dla automatycznego dołączania do zaproszeń używaj tylko stabilnych celów zaproszeń: `!roomId:server`, `#alias:server` lub `*`. Zwykłe nazwy pokoi są odrzucane. -- Tożsamość pokoju/sesji w runtime używa stabilnego ID pokoju Matrix. Aliasy zadeklarowane przez pokój są używane tylko jako dane wejściowe do wyszukiwania, a nie jako długoterminowy klucz sesji lub stabilna tożsamość grupy. -- Aby rozwiązać nazwy pokoi przed ich zapisaniem, użyj `openclaw channels resolve --channel matrix "Project Room"`. +- Jeśli zmienne środowiskowe uwierzytelniania Matrix już istnieją dla wybranego konta, a to konto nie ma jeszcze zapisanego uwierzytelniania w konfiguracji, kreator oferuje skrót do env, dzięki czemu konfiguracja może pozostawić uwierzytelnianie w zmiennych środowiskowych zamiast kopiować sekrety do konfiguracji. +- Gdy interaktywnie dodajesz kolejne konto Matrix, wprowadzona nazwa konta jest normalizowana do identyfikatora konta używanego w konfiguracji i zmiennych środowiskowych. Na przykład `Ops Bot` staje się `ops-bot`. +- Monity listy dozwolonych dla wiadomości prywatnych od razu akceptują pełne wartości `@user:server`. Nazwy wyświetlane działają tylko wtedy, gdy wyszukiwanie w katalogu na żywo znajdzie jedno dokładne dopasowanie; w przeciwnym razie kreator poprosi o ponowną próbę z pełnym identyfikatorem Matrix. +- Monity listy dozwolonych dla pokojów bezpośrednio akceptują identyfikatory pokojów i aliasy. Mogą też na żywo rozwiązywać nazwy dołączonych pokojów, ale nierozwiązane nazwy są podczas konfiguracji zachowywane tylko w postaci wpisanej i później są ignorowane przez runtime przy rozwiązywaniu listy dozwolonych. Preferuj `!room:server` lub `#alias:server`. +- Kreator wyświetla teraz jawne ostrzeżenie przed krokiem automatycznego dołączania do zaproszeń, ponieważ domyślna wartość `channels.matrix.autoJoin` to `off`; agenty nie dołączą do zaproszonych pokojów ani nowych zaproszeń w stylu wiadomości prywatnej, dopóki tego nie ustawisz. +- W trybie listy dozwolonych dla automatycznego dołączania do zaproszeń używaj wyłącznie stabilnych celów zaproszeń: `!roomId:server`, `#alias:server` lub `*`. Zwykłe nazwy pokojów są odrzucane. +- Tożsamość pokoju/sesji w runtime używa stabilnego identyfikatora pokoju Matrix. Aliasy zadeklarowane przez pokój są używane tylko jako dane wejściowe do wyszukiwania, a nie jako długoterminowy klucz sesji lub stabilna tożsamość grupy. +- Aby rozwiązać nazwy pokojów przed ich zapisaniem, użyj `openclaw channels resolve --channel matrix "Project Room"`. -`channels.matrix.autoJoin` domyślnie ma wartość `off`. +Domyślna wartość `channels.matrix.autoJoin` to `off`. -Jeśli pozostawisz to pole nieustawione, bot nie będzie dołączać do zaproszonych pokoi ani nowych zaproszeń typu DM, więc nie pojawi się w nowych grupach ani zaproszonych DM-ach, chyba że najpierw dołączysz ręcznie. +Jeśli pozostawisz tę opcję nieustawioną, bot nie będzie dołączał do zaproszonych pokojów ani nowych zaproszeń w stylu wiadomości prywatnej, więc nie pojawi się w nowych grupach ani zaproszonych wiadomościach prywatnych, chyba że najpierw dołączysz ręcznie. -Ustaw `autoJoin: "allowlist"` razem z `autoJoinAllowlist`, aby ograniczyć, które zaproszenia akceptuje, albo ustaw `autoJoin: "always"`, jeśli chcesz, aby dołączał do każdego zaproszenia. +Ustaw `autoJoin: "allowlist"` razem z `autoJoinAllowlist`, aby ograniczyć, które zaproszenia są akceptowane, albo ustaw `autoJoin: "always"`, jeśli ma dołączać do każdego zaproszenia. -W trybie `allowlist` `autoJoinAllowlist` akceptuje tylko `!roomId:server`, `#alias:server` lub `*`. +W trybie `allowlist` opcja `autoJoinAllowlist` akceptuje tylko `!roomId:server`, `#alias:server` lub `*`. -Przykład allowlisty: +Przykład listy dozwolonych: ```json5 { @@ -110,7 +110,7 @@ Przykład allowlisty: } ``` -Dołącz do każdego zaproszenia: +Dołączaj do każdego zaproszenia: ```json5 { @@ -155,9 +155,9 @@ Konfiguracja oparta na haśle (token jest buforowany po zalogowaniu): Matrix przechowuje zbuforowane poświadczenia w `~/.openclaw/credentials/matrix/`. Konto domyślne używa `credentials.json`; nazwane konta używają `credentials-.json`. -Gdy znajdują się tam zbuforowane poświadczenia, OpenClaw traktuje Matrix jako skonfigurowany na potrzeby setupu, doctor i wykrywania statusu kanału, nawet jeśli bieżące uwierzytelnianie nie jest ustawione bezpośrednio w configu. +Gdy znajdują się tam zbuforowane poświadczenia, OpenClaw traktuje Matrix jako skonfigurowany na potrzeby konfiguracji, doctor i wykrywania stanu kanału, nawet jeśli bieżące uwierzytelnianie nie jest ustawione bezpośrednio w konfiguracji. -Odpowiedniki w zmiennych środowiskowych (używane, gdy klucz configu nie jest ustawiony): +Odpowiedniki w zmiennych środowiskowych (używane, gdy klucz konfiguracyjny nie jest ustawiony): - `MATRIX_HOMESERVER` - `MATRIX_ACCESS_TOKEN` @@ -166,7 +166,7 @@ Odpowiedniki w zmiennych środowiskowych (używane, gdy klucz configu nie jest u - `MATRIX_DEVICE_ID` - `MATRIX_DEVICE_NAME` -Dla kont innych niż domyślne używaj zmiennych środowiskowych z zakresem konta: +Dla kont innych niż domyślne użyj zmiennych środowiskowych przypisanych do konta: - `MATRIX__HOMESERVER` - `MATRIX__ACCESS_TOKEN` @@ -180,19 +180,19 @@ Przykład dla konta `ops`: - `MATRIX_OPS_HOMESERVER` - `MATRIX_OPS_ACCESS_TOKEN` -Dla znormalizowanego ID konta `ops-bot` użyj: +Dla znormalizowanego identyfikatora konta `ops-bot` użyj: - `MATRIX_OPS_X2D_BOT_HOMESERVER` - `MATRIX_OPS_X2D_BOT_ACCESS_TOKEN` -Matrix zmienia interpunkcję w ID kont, aby zmienne środowiskowe z zakresem konta nie kolidowały ze sobą. +Matrix zamienia znaki interpunkcyjne w identyfikatorach kont, aby uniknąć kolizji w zmiennych środowiskowych przypisanych do kont. Na przykład `-` staje się `_X2D_`, więc `ops-prod` mapuje się na `MATRIX_OPS_X2D_PROD_*`. -Interaktywny kreator oferuje skrót ze zmiennymi środowiskowymi tylko wtedy, gdy te zmienne uwierzytelniania już istnieją, a wybrane konto nie ma jeszcze zapisanych danych uwierzytelniających Matrix w configu. +Interaktywny kreator oferuje skrót do zmiennych środowiskowych tylko wtedy, gdy te zmienne uwierzytelniania już istnieją i wybrane konto nie ma jeszcze zapisanego uwierzytelniania Matrix w konfiguracji. ## Przykład konfiguracji -To praktyczna bazowa konfiguracja z parowaniem DM, allowlistą pokojów i włączonym E2EE: +To praktyczna bazowa konfiguracja z parowaniem wiadomości prywatnych, listą dozwolonych pokojów i włączonym E2EE: ```json5 { @@ -227,19 +227,20 @@ To praktyczna bazowa konfiguracja z parowaniem DM, allowlistą pokojów i włąc } ``` -`autoJoin` dotyczy ogólnie zaproszeń Matrix, nie tylko zaproszeń do pokoi/grup. -Obejmuje to także nowe zaproszenia typu DM. W momencie zaproszenia OpenClaw nie wie jeszcze -wiarygodnie, czy zaproszony pokój zostanie ostatecznie potraktowany jako DM czy grupa, więc wszystkie -zaproszenia najpierw przechodzą przez to samo rozstrzygnięcie `autoJoin`. `dm.policy` nadal ma -zastosowanie po dołączeniu bota i sklasyfikowaniu pokoju jako DM, więc `autoJoin` kontroluje zachowanie -dołączania, a `dm.policy` kontroluje zachowanie odpowiedzi/dostępu. +`autoJoin` dotyczy ogólnie zaproszeń Matrix, a nie tylko zaproszeń do pokojów/grup. +Obejmuje to także nowe zaproszenia w stylu wiadomości prywatnej. W momencie zaproszenia OpenClaw nie wie +wiarygodnie, czy zaproszony pokój zostanie ostatecznie potraktowany jako wiadomość prywatna czy grupa, +dlatego wszystkie zaproszenia najpierw przechodzą przez tę samą decyzję `autoJoin`. `dm.policy` nadal +ma zastosowanie po dołączeniu bota i sklasyfikowaniu pokoju jako wiadomość prywatna, więc `autoJoin` +steruje zachowaniem dołączania, a `dm.policy` steruje zachowaniem odpowiedzi/dostępu. -## Podgląd streamingu +## Podglądy streamingu -Streaming odpowiedzi w Matrix jest włączany opcjonalnie. +Streaming odpowiedzi Matrix jest opcjonalny. -Ustaw `channels.matrix.streaming` na `"partial"`, jeśli chcesz, aby OpenClaw wysyłał jedną odpowiedź -podglądu na żywo, edytował ten podgląd na bieżąco podczas generowania tekstu przez model, a następnie finalizował go po zakończeniu odpowiedzi: +Ustaw `channels.matrix.streaming` na `"partial"`, jeśli chcesz, aby OpenClaw wysyłał pojedynczą +odpowiedź z podglądem na żywo, edytował ten podgląd na miejscu podczas generowania tekstu przez model, +a następnie finalizował go po zakończeniu odpowiedzi: ```json5 { @@ -251,35 +252,35 @@ podglądu na żywo, edytował ten podgląd na bieżąco podczas generowania teks } ``` -- `streaming: "off"` to ustawienie domyślne. OpenClaw czeka na końcową odpowiedź i wysyła ją raz. -- `streaming: "partial"` tworzy jeden edytowalny komunikat podglądu dla bieżącego bloku odpowiedzi asystenta przy użyciu zwykłych wiadomości tekstowych Matrix. Zachowuje to starsze zachowanie powiadomień Matrix oparte na pierwszym podglądzie, więc standardowi klienci mogą powiadamiać przy pierwszym strumieniowanym tekście podglądu zamiast przy 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 streaming podglądu jest włączony, Matrix utrzymuje szkic na żywo dla bieżącego bloku i zachowuje ukończone bloki jako osobne wiadomości. -- Gdy podgląd streamingu jest włączony, a `blockStreaming` jest wyłączone, Matrix edytuje szkic na żywo w miejscu i finalizuje to samo zdarzenie po zakończeniu bloku lub tury. -- Jeśli podgląd przestaje mieścić się w jednym zdarzeniu Matrix, OpenClaw zatrzymuje streaming podglądu i wraca do zwykłego końcowego dostarczenia. -- Odpowiedzi z mediami nadal wysyłają załączniki normalnie. Jeśli nie da się już bezpiecznie ponownie użyć nieaktualnego podglądu, OpenClaw redaguje go przed wysłaniem końcowej odpowiedzi z mediami. -- Edycje podglądu generują dodatkowe wywołania API Matrix. Pozostaw streaming wyłączony, jeśli chcesz najbardziej zachowawcze zachowanie względem limitów szybkości. +- `streaming: "off"` to ustawienie domyślne. OpenClaw czeka na końcową odpowiedź i wysyła ją jednorazowo. +- `streaming: "partial"` tworzy jedną edytowalną wiadomość podglądu dla bieżącego bloku odpowiedzi asystenta, używając zwykłych wiadomości tekstowych Matrix. Zachowuje to starsze zachowanie Matrix polegające na powiadamianiu najpierw o podglądzie, więc standardowe klienty mogą powiadamiać na podstawie pierwszego przesłanego tekstu podglądu zamiast gotowego bloku. +- `streaming: "quiet"` tworzy jedno edytowalne ciche powiadomienie podglądu dla bieżącego bloku odpowiedzi asystenta. Używaj tego tylko wtedy, gdy skonfigurujesz też reguły push odbiorcy dla sfinalizowanych edycji podglądu. +- `blockStreaming: true` włącza osobne wiadomości postępu Matrix. Gdy streaming podglądu jest włączony, Matrix zachowuje wersję roboczą na żywo dla bieżącego bloku i zachowuje ukończone bloki jako oddzielne wiadomości. +- Gdy streaming podglądu jest włączony, a `blockStreaming` jest wyłączone, Matrix edytuje wersję roboczą na żywo na miejscu i finalizuje to samo zdarzenie po zakończeniu bloku lub tury. +- Jeśli podgląd przestaje mieścić się w jednym zdarzeniu Matrix, OpenClaw zatrzymuje streaming podglądu i wraca do normalnego końcowego dostarczenia. +- Odpowiedzi z multimediami nadal wysyłają załączniki normalnie. Jeśli starego podglądu nie da się już bezpiecznie ponownie użyć, OpenClaw usuwa go przed wysłaniem końcowej odpowiedzi z multimediami. +- Edycje podglądu generują dodatkowe wywołania API Matrix. Pozostaw streaming wyłączony, jeśli chcesz zachować najbardziej ostrożne zachowanie względem limitów szybkości. -`blockStreaming` samo w sobie nie włącza podglądów szkicu. -Użyj `streaming: "partial"` albo `streaming: "quiet"` dla edycji podglądu; następnie dodaj `blockStreaming: true` tylko wtedy, gdy chcesz także, aby ukończone bloki asystenta pozostawały widoczne jako osobne komunikaty postępu. +`blockStreaming` samo w sobie nie włącza podglądów wersji roboczych. +Użyj `streaming: "partial"` lub `streaming: "quiet"` do edycji podglądu; dopiero potem dodaj `blockStreaming: true`, jeśli chcesz także, by ukończone bloki asystenta pozostawały widoczne jako oddzielne wiadomości postępu. -Jeśli potrzebujesz standardowych powiadomień Matrix bez niestandardowych reguł push, użyj `streaming: "partial"` dla zachowania opartego na pierwszym podglądzie albo pozostaw `streaming` wyłączone dla dostarczania tylko końcowego. Gdy `streaming: "off"`: +Jeśli potrzebujesz standardowych powiadomień Matrix bez niestandardowych reguł push, użyj `streaming: "partial"` dla zachowania „najpierw podgląd” albo pozostaw `streaming` wyłączone dla dostarczania tylko końcowej odpowiedzi. Gdy `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. -### Samohostowane reguły push dla cichych sfinalizowanych podglądów +### Samodzielnie hostowane reguły push dla cichych sfinalizowanych podglądów -Jeśli uruchamiasz własną infrastrukturę Matrix i chcesz, aby ciche podglądy powiadamiały dopiero po zakończeniu bloku lub +Jeśli utrzymujesz 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 sfinalizowanych edycji podglądu. Zwykle jest to konfiguracja po stronie użytkownika-odbiorcy, a nie globalna zmiana konfiguracji homeservera: Szybka mapa przed rozpoczęciem: -- użytkownik-odbiorca = osoba, która ma otrzymywać powiadomienie -- użytkownik bota = konto Matrix OpenClaw, które wysyła odpowiedź -- dla poniższych wywołań API użyj access tokenu użytkownika-odbiorcy +- użytkownik odbiorca = osoba, która ma otrzymywać powiadomienie +- użytkownik bota = konto Matrix OpenClaw wysyłające odpowiedź +- do poniższych wywołań API użyj tokena dostępu użytkownika odbiorcy - dopasuj `sender` w regule push do pełnego MXID użytkownika bota 1. Skonfiguruj OpenClaw tak, aby używał cichych podglądów: @@ -294,13 +295,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 tokenu użytkownika odbierającego, 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: +3. Pobierz token dostępu użytkownika odbiorcy. + - Użyj tokena użytkownika odbierającego, a nie tokena bota. + - Najłatwiej zwykle ponownie użyć tokena istniejącej sesji klienta. + - Jeśli musisz wygenerować nowy token, możesz zalogować się przez standardowe API Matrix Client-Server: ```bash curl -sS -X POST \ @@ -324,10 +325,10 @@ curl -sS \ "https://matrix.example.org/_matrix/client/v3/pushers" ``` -Jeśli to zwróci brak aktywnych pusherów/urządzeń, najpierw napraw zwykłe powiadomienia Matrix, zanim dodasz +Jeśli to zwraca brak aktywnych pusherów/urządzeń, najpierw napraw zwykłe powiadomienia Matrix, zanim dodasz poniższą regułę OpenClaw. -OpenClaw oznacza sfinalizowane edycje podglądu zawierające wyłącznie tekst przez: +OpenClaw oznacza sfinalizowane edycje podglądu tylko tekstowego znacznikiem: ```json { @@ -368,19 +369,19 @@ curl -sS -X PUT \ Zastąp te wartości przed uruchomieniem polecenia: - `https://matrix.example.org`: bazowy URL twojego homeservera -- `$USER_ACCESS_TOKEN`: access token użytkownika odbierającego -- `openclaw-finalized-preview-botname`: ID reguły unikalne dla tego bota dla tego użytkownika odbierającego +- `$USER_ACCESS_TOKEN`: token dostępu użytkownika odbierającego +- `openclaw-finalized-preview-botname`: identyfikator reguły unikalny dla tego bota dla tego użytkownika odbierającego - `@bot:example.org`: MXID twojego bota Matrix OpenClaw, a nie MXID użytkownika odbierającego -Ważne dla konfiguracji z wieloma botami: +Ważne w konfiguracjach z wieloma botami: -- Kluczem reguł push jest `ruleId`. Ponowne uruchomienie `PUT` dla tego samego ID reguły aktualizuje tę jedną regułę. -- Jeśli jeden użytkownik odbierający ma otrzymywać powiadomienia od wielu kont botów Matrix OpenClaw, utwórz jedną regułę na bota z unikalnym ID reguły dla każdego dopasowania nadawcy. -- Prosty wzorzec to `openclaw-finalized-preview-`, na przykład `openclaw-finalized-preview-ops` albo `openclaw-finalized-preview-support`. +- Reguły push są kluczowane przez `ruleId`. Ponowne uruchomienie `PUT` względem tego samego identyfikatora reguły aktualizuje tę jedną regułę. +- Jeśli jeden użytkownik odbierający ma otrzymywać powiadomienia od wielu kont botów Matrix OpenClaw, utwórz jedną regułę na bota z unikalnym identyfikatorem reguły dla każdego dopasowania nadawcy. +- Prostym wzorcem jest `openclaw-finalized-preview-`, na przykład `openclaw-finalized-preview-ops` lub `openclaw-finalized-preview-support`. Reguła jest oceniana względem nadawcy zdarzenia: -- uwierzytelnij się przy użyciu tokenu użytkownika odbierającego +- uwierzytelnij się tokenem użytkownika odbierającego - dopasuj `sender` do MXID bota OpenClaw 6. Zweryfikuj, że reguła istnieje: @@ -391,10 +392,10 @@ curl -sS \ "https://matrix.example.org/_matrix/client/v3/pushrules/global/override/openclaw-finalized-preview-botname" ``` -7. Przetestuj odpowiedź strumieniowaną. W trybie quiet pokój powinien pokazywać cichy szkic podglądu, a końcowa - edycja w miejscu powinna wysłać powiadomienie po zakończeniu bloku lub tury. +7. Przetestuj odpowiedź strumieniowaną. W trybie quiet pokój powinien pokazać cichy podgląd wersji roboczej, a końcowa + edycja na miejscu powinna wysłać powiadomienie po zakończeniu bloku lub tury. -Jeśli później będziesz potrzebować usunąć regułę, usuń to samo ID reguły przy użyciu tokenu użytkownika odbierającego: +Jeśli później chcesz usunąć regułę, usuń ten sam identyfikator reguły tokenem użytkownika odbierającego: ```bash curl -sS -X DELETE \ @@ -404,37 +405,37 @@ curl -sS -X DELETE \ Uwagi: -- Utwórz regułę przy użyciu access tokenu użytkownika odbierającego, a nie tokenu bota. -- Nowe zdefiniowane przez użytkownika reguły `override` są wstawiane przed domyślnymi regułami wyciszającymi, więc nie jest potrzebny dodatkowy parametr kolejności. -- Dotyczy to tylko edycji podglądu zawierających wyłącznie tekst, które OpenClaw może bezpiecznie sfinalizować w miejscu. Fallbacki dla mediów i fallbacki dla nieaktualnych podglądów nadal używają zwykłego dostarczania Matrix. -- Jeśli `GET /_matrix/client/v3/pushers` nie pokazuje pusherów, użytkownik nie ma jeszcze działającego dostarczania powiadomień push Matrix dla tego konta/urządzenia. +- Utwórz regułę z użyciem tokena dostępu użytkownika odbierającego, a nie bota. +- Nowe reguły `override` zdefiniowane przez użytkownika są wstawiane przed domyślnymi regułami wyciszającymi, więc nie jest potrzebny dodatkowy parametr kolejności. +- Dotyczy to tylko edycji podglądu tylko tekstowego, które OpenClaw może bezpiecznie sfinalizować na miejscu. Fallbacki dla multimediów i starych podglądów nadal używają normalnego dostarczania Matrix. +- Jeśli `GET /_matrix/client/v3/pushers` nie pokazuje żadnych pusherów, użytkownik nie ma jeszcze działającego dostarczania powiadomień push Matrix dla tego konta/urządzenia. #### Synapse W przypadku Synapse powyższa konfiguracja zwykle sama w sobie wystarcza: -- Nie jest wymagana specjalna zmiana `homeserver.yaml` dla sfinalizowanych powiadomień o podglądzie OpenClaw. -- Jeśli twoje 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 trafia do Synapse. -- Jeśli używasz workerów Synapse, upewnij się, że pushery są sprawne. Dostarczaniem push zajmuje się proces główny albo `synapse.app.pusher` / skonfigurowane workery pushera. +- Żadna specjalna zmiana w `homeserver.yaml` nie jest wymagana dla sfinalizowanych powiadomień o podglądzie OpenClaw. +- Jeśli twoje wdrożenie Synapse już wysyła zwykłe powiadomienia push Matrix, token użytkownika + wywołanie `pushrules` powyżej to główny krok konfiguracji. +- Jeśli uruchamiasz Synapse za reverse proxy lub workerami, upewnij się, że `/_matrix/client/.../pushrules/` trafia poprawnie do Synapse. +- Jeśli używasz workerów Synapse, upewnij się, że pushery są sprawne. Dostarczanie push jest obsługiwane przez proces główny lub `synapse.app.pusher` / skonfigurowane workery pusherów. #### Tuwunel -W przypadku Tuwunel użyj tego samego przepływu konfiguracji i wywołania API `pushrules`, które pokazano wyżej: +Dla Tuwunel użyj tego samego przepływu konfiguracji i wywołania API `pushrules`, które pokazano powyżej: -- Nie jest wymagana 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 i może ona celowo wyciszać powiadomienia push na innych urządzeniach, gdy jedno urządzenie jest aktywne. +- Żadna konfiguracja specyficzna dla Tuwunel nie jest wymagana dla samego znacznika sfinalizowanego podglądu. +- Jeśli zwykłe powiadomienia Matrix już działają dla tego użytkownika, token użytkownika + wywołanie `pushrules` powyżej to główny krok konfiguracji. +- Jeśli wydaje się, że powiadomienia znikają, gdy użytkownik jest aktywny na innym urządzeniu, sprawdź, czy włączono `suppress_push_when_active`. Tuwunel dodał tę opcję w Tuwunel 1.4.2 12 września 2025 r. i może ona celowo wyciszać powiadomienia push na innych urządzeniach, gdy jedno urządzenie jest aktywne. ## Szyfrowanie i weryfikacja -W zaszyfrowanych pokojach (E2EE) wychodzące zdarzenia obrazów używają `thumbnail_file`, więc 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 zaszyfrowanych pokojach (E2EE) wychodzące zdarzenia obrazów używają `thumbnail_file`, dzięki czemu podglądy obrazów są szyfrowane razem z pełnym załącznikiem. Niezaszyfrowane pokoje nadal używają zwykłego `thumbnail_url`. Nie jest wymagana żadna konfiguracja — wtyczka automatycznie wykrywa stan E2EE. -### Pokoje bot-do-bota +### Pokoje bot-bot -Domyślnie wiadomości Matrix pochodzące od innych skonfigurowanych kont Matrix OpenClaw są ignorowane. +Domyślnie wiadomości Matrix od innych skonfigurowanych kont Matrix OpenClaw są ignorowane. -Użyj `allowBots`, jeśli celowo chcesz zezwolić na ruch Matrix między agentami: +Użyj `allowBots`, gdy celowo chcesz dopuścić ruch Matrix między agentami: ```json5 { @@ -451,13 +452,13 @@ Użyj `allowBots`, jeśli celowo chcesz zezwolić na ruch Matrix między agentam } ``` -- `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 widocznie wspominają tego bota. DM-y są nadal dozwolone. +- `allowBots: true` akceptuje wiadomości od innych skonfigurowanych kont botów Matrix w dozwolonych pokojach i wiadomościach prywatnych. +- `allowBots: "mentions"` akceptuje te wiadomości tylko wtedy, gdy w pokojach wyraźnie wspominają tego bota. Wiadomości prywatne są nadal dozwolone. - `groups..allowBots` nadpisuje ustawienie na poziomie konta dla jednego pokoju. -- OpenClaw nadal ignoruje wiadomości od tego samego ID użytkownika Matrix, aby uniknąć pętli odpowiedzi do siebie. -- Matrix nie udostępnia tutaj natywnej flagi bota; OpenClaw traktuje „napisane przez bota” jako „wysłane przez inne skonfigurowane konto Matrix na tym gateway OpenClaw”. +- OpenClaw nadal ignoruje wiadomości od tego samego identyfikatora użytkownika Matrix, aby uniknąć pętli odpowiedzi do samego siebie. +- Matrix nie udostępnia tu natywnej flagi bota; OpenClaw traktuje „napisane przez bota” jako „wysłane przez inne skonfigurowane konto Matrix na tym gatewayu OpenClaw”. -Przy włączaniu ruchu bot-do-bota we wspólnych pokojach używaj ścisłych allowlist pokojów i wymagań wzmianki. +Przy włączaniu ruchu bot-bot w pokojach współdzielonych używaj ścisłych list dozwolonych pokojów i wymagań wzmianki. Włącz szyfrowanie: @@ -475,31 +476,31 @@ Włącz szyfrowanie: } ``` -Sprawdź status weryfikacji: +Sprawdź stan weryfikacji: ```bash openclaw matrix verify status ``` -Status szczegółowy (pełna diagnostyka): +Szczegółowy stan (pełna diagnostyka): ```bash openclaw matrix verify status --verbose ``` -Dołącz zapisany recovery key w danych wyjściowych czytelnych maszynowo: +Dołącz zapisany klucz odzyskiwania w wyniku czytelnym maszynowo: ```bash openclaw matrix verify status --include-recovery-key --json ``` -Zainicjuj cross-signing i stan weryfikacji: +Zainicjalizuj cross-signing i stan weryfikacji: ```bash openclaw matrix verify bootstrap ``` -Obsługa wielu kont: użyj `channels.matrix.accounts` z poświadczeniami per konto i opcjonalnym `name`. Wspólny wzorzec opisano w [Configuration reference](/pl/gateway/configuration-reference#multi-account-all-channels). +Obsługa wielu kont: użyj `channels.matrix.accounts` z poświadczeniami per konto i opcjonalnym `name`. Zobacz [Dokumentację konfiguracji](/pl/gateway/configuration-reference#multi-account-all-channels), aby poznać wspólny wzorzec. Szczegółowa diagnostyka bootstrap: @@ -507,37 +508,37 @@ Szczegółowa diagnostyka bootstrap: openclaw matrix verify bootstrap --verbose ``` -Wymuś nowy reset tożsamości cross-signing przed bootstrapowaniem: +Wymuś reset tożsamości cross-signing przed bootstrapem: ```bash openclaw matrix verify bootstrap --force-reset-cross-signing ``` -Zweryfikuj to urządzenie za pomocą recovery key: +Zweryfikuj to urządzenie za pomocą klucza odzyskiwania: ```bash openclaw matrix verify device "" ``` -Szczegóły szczegółowej weryfikacji urządzenia: +Szczegółowe informacje o weryfikacji urządzenia: ```bash openclaw matrix verify device "" --verbose ``` -Sprawdź stan kopii zapasowej room key: +Sprawdź kondycję kopii zapasowej kluczy pokojów: ```bash openclaw matrix verify backup status ``` -Szczegółowa diagnostyka stanu kopii zapasowej: +Szczegółowa diagnostyka kondycji kopii zapasowej: ```bash openclaw matrix verify backup status --verbose ``` -Przywróć room key z kopii zapasowej na serwerze: +Przywróć klucze pokojów z kopii zapasowej na serwerze: ```bash openclaw matrix verify backup restore @@ -549,20 +550,20 @@ Szczegółowa diagnostyka przywracania: openclaw matrix verify backup restore --verbose ``` -Usuń bieżącą kopię zapasową na serwerze i utwórz nową bazową kopię zapasową. Jeśli zapisany -klucz kopii zapasowej nie może zostać poprawnie załadowany, ten reset może również odtworzyć secret storage, aby -przyszłe cold starty mogły załadować nowy klucz kopii zapasowej: +Usuń bieżącą kopię zapasową na serwerze i utwórz nową bazę kopii zapasowej. Jeśli zapisany +klucz kopii zapasowej nie może zostać poprawnie wczytany, ten reset może także odtworzyć magazyn sekretów, aby +przyszłe zimne starty mogły wczytać nowy klucz kopii zapasowej: ```bash openclaw matrix verify backup reset --yes ``` -Wszystkie polecenia `verify` są domyślnie zwięzłe (w tym z cichym wewnętrznym logowaniem SDK) i pokazują szczegółową diagnostykę tylko z `--verbose`. -Przy skryptowaniu użyj `--json`, aby uzyskać pełne dane wyjściowe czytelne maszynowo. +Wszystkie polecenia `verify` są domyślnie zwięzłe (łącznie z cichym wewnętrznym logowaniem SDK) i pokazują szczegółową diagnostykę tylko z `--verbose`. +Przy skryptowaniu użyj `--json`, aby otrzymać pełny wynik czytelny maszynowo. -W konfiguracjach wielokontowych polecenia CLI Matrix używają domyślnego niejawnego konta Matrix, chyba że przekażesz `--account `. +W konfiguracjach z wieloma kontami polecenia CLI Matrix używają domyślnego niejawnego konta Matrix, chyba że przekażesz `--account `. Jeśli skonfigurujesz wiele nazwanych kont, najpierw ustaw `channels.matrix.defaultAccount`, w przeciwnym razie te niejawne operacje CLI zatrzymają się i poproszą o jawny wybór konta. -Używaj `--account` zawsze wtedy, gdy chcesz, aby operacje weryfikacji lub urządzeń jawnie kierowały się do nazwanego konta: +Używaj `--account`, gdy chcesz, aby operacje weryfikacji lub urządzenia były jawnie kierowane do konkretnego nazwanego konta: ```bash openclaw matrix verify status --account assistant @@ -570,16 +571,16 @@ 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 configu 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 „verified” +### Co oznacza „zweryfikowane” -OpenClaw traktuje to urządzenie Matrix jako zweryfikowane tylko wtedy, gdy jest zweryfikowane przez twoją własną tożsamość cross-signing. -W praktyce `openclaw matrix verify status --verbose` pokazuje trzy sygnały zaufania: +OpenClaw traktuje to urządzenie Matrix jako zweryfikowane tylko wtedy, gdy zostało zweryfikowane przez twoją własną tożsamość cross-signing. +W praktyce `openclaw matrix verify status --verbose` ujawnia trzy sygnały zaufania: -- `Locally trusted`: temu urządzeniu ufa tylko bieżący klient +- `Locally trusted`: to urządzenie jest zaufane tylko przez bieżącego klienta - `Cross-signing verified`: SDK zgłasza urządzenie jako zweryfikowane przez cross-signing -- `Signed by owner`: urządzenie jest podpisane twoim własnym kluczem self-signing +- `Signed by owner`: urządzenie jest podpisane przez twój własny klucz self-signing `Verified by owner` przyjmuje wartość `yes` tylko wtedy, gdy obecna jest weryfikacja cross-signing lub podpis właściciela. Samo lokalne zaufanie nie wystarcza, aby OpenClaw traktował urządzenie jako w pełni zweryfikowane. @@ -587,26 +588,25 @@ Samo lokalne zaufanie nie wystarcza, aby OpenClaw traktował urządzenie jako w ### Co robi bootstrap `openclaw matrix verify bootstrap` to polecenie naprawy i konfiguracji dla zaszyfrowanych kont Matrix. -Wykonuje po kolei wszystkie poniższe czynności: +Wykonuje po kolei wszystkie poniższe działania: -- inicjalizuje secret storage, ponownie używając istniejącego recovery key, gdy to możliwe +- inicjalizuje magazyn sekretów, ponownie używając istniejącego klucza odzyskiwania, gdy to możliwe - inicjalizuje cross-signing i wysyła brakujące publiczne klucze cross-signing - próbuje oznaczyć i podpisać bieżące urządzenie przez cross-signing -- tworzy nową kopię zapasową room key po stronie serwera, jeśli jeszcze nie istnieje +- tworzy nową kopię zapasową kluczy pokojów po stronie serwera, jeśli jeszcze nie istnieje -Jeśli homeserver wymaga interaktywnego uwierzytelnienia do wysłania kluczy cross-signing, OpenClaw próbuje najpierw wysłać je bez uwierzytelnienia, potem z `m.login.dummy`, a następnie z `m.login.password`, gdy skonfigurowano `channels.matrix.password`. +Jeśli homeserver wymaga uwierzytelniania interaktywnego do wysłania kluczy cross-signing, OpenClaw próbuje najpierw bez uwierzytelniania, potem z `m.login.dummy`, a następnie z `m.login.password`, gdy skonfigurowano `channels.matrix.password`. -Używaj `--force-reset-cross-signing` tylko wtedy, gdy celowo chcesz odrzucić bieżącą tożsamość cross-signing i utworzyć nową. +Używaj `--force-reset-cross-signing` tylko wtedy, gdy celowo chcesz porzucić bieżącą tożsamość cross-signing i utworzyć nową. -Jeśli celowo chcesz odrzucić bieżącą kopię zapasową room key i rozpocząć nową +Jeśli celowo chcesz porzucić bieżącą kopię zapasową kluczy pokojów i rozpocząć nową bazę kopii zapasowej dla przyszłych wiadomości, użyj `openclaw matrix verify backup reset --yes`. -Rób to tylko wtedy, gdy akceptujesz, że nieodwracalnie utracona stara zaszyfrowana historia pozostanie -niedostępna i że OpenClaw może odtworzyć secret storage, jeśli nie da się bezpiecznie załadować -bieżącego sekretu kopii zapasowej. +Rób to tylko wtedy, gdy akceptujesz, że niemożliwa do odzyskania stara zaszyfrowana historia pozostanie +niedostępna i że OpenClaw może odtworzyć magazyn sekretów, jeśli bieżącego sekretu kopii zapasowej nie da się bezpiecznie wczytać. ### Nowa baza kopii zapasowej -Jeśli chcesz zachować działanie przyszłych zaszyfrowanych wiadomości i akceptujesz utratę niemożliwej do odzyskania starej historii, uruchom te polecenia po kolei: +Jeśli chcesz zachować działanie przyszłych zaszyfrowanych wiadomości i akceptujesz utratę niemożliwej do odzyskania starej historii, uruchom po kolei te polecenia: ```bash openclaw matrix verify backup reset --yes @@ -614,163 +614,163 @@ openclaw matrix verify backup status --verbose openclaw matrix verify status ``` -Dodaj `--account ` do każdego polecenia, jeśli chcesz jawnie kierować je do nazwanego konta Matrix. +Dodaj `--account ` do każdego polecenia, gdy chcesz jawnie wskazać nazwane konto Matrix. -### Zachowanie przy uruchomieniu +### Zachowanie przy uruchamianiu -Gdy `encryption: true`, Matrix domyślnie ustawia `startupVerification` na `"if-unverified"`. -Przy uruchomieniu, jeśli to urządzenie nadal nie jest zweryfikowane, Matrix wyśle prośbę o samoweryfikację do innego klienta Matrix, -pominie duplikaty próśb, gdy jedna jest już oczekująca, i zastosuje lokalny cooldown przed ponowną próbą po restartach. -Domyślnie nieudane próby wysłania są ponawiane szybciej niż pomyślne utworzenie prośby. -Ustaw `startupVerification: "off"`, aby wyłączyć automatyczne prośby przy uruchomieniu, albo dostosuj `startupVerificationCooldownHours`, -jeśli chcesz krótsze lub dłuższe okno ponawiania. +Gdy `encryption: true`, domyślna wartość `startupVerification` w Matrix to `"if-unverified"`. +Przy uruchamianiu, jeśli to urządzenie nadal nie jest zweryfikowane, Matrix poprosi o samoweryfikację w innym kliencie Matrix, +pominie duplikaty żądań, gdy jedno jest już w toku, i zastosuje lokalny okres karencji przed ponowieniem po restarcie. +Nieudane próby wysłania żądania są domyślnie ponawiane szybciej niż udane utworzenie żądania. +Ustaw `startupVerification: "off"`, aby wyłączyć automatyczne żądania przy uruchamianiu, lub dostosuj `startupVerificationCooldownHours`, +jeśli chcesz krótsze albo dłuższe okno ponawiania. -Podczas uruchomienia automatycznie wykonywany jest również zachowawczy 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 naprawczy bootstrap. +Uruchamianie wykonuje też automatycznie ostrożny przebieg bootstrapu kryptograficznego. +Ten przebieg najpierw próbuje ponownie użyć bieżącego magazynu sekretów i tożsamości cross-signing oraz unika resetowania cross-signing, chyba że uruchomisz jawny przepływ naprawczy bootstrapu. -Jeśli przy uruchomieniu zostanie wykryty uszkodzony stan bootstrap i skonfigurowano `channels.matrix.password`, OpenClaw może spróbować bardziej rygorystycznej ścieżki naprawy. +Jeśli podczas uruchamiania zostanie wykryty uszkodzony stan bootstrapu i skonfigurowano `channels.matrix.password`, OpenClaw może spróbować bardziej restrykcyjnej ścieżki naprawczej. Jeśli bieżące urządzenie jest już podpisane przez właściciela, OpenClaw zachowuje tę tożsamość zamiast resetować ją automatycznie. -Uaktualnianie z poprzedniego publicznego pluginu Matrix: +Uaktualnianie z poprzedniej publicznej wtyczki Matrix: -- OpenClaw automatycznie ponownie używa tego samego konta Matrix, access tokenu i tożsamości urządzenia, gdy to możliwe. -- Zanim zostaną uruchomione jakiekolwiek działania migracyjne dotyczące Matrix, OpenClaw tworzy lub ponownie używa snapshotu odzyskiwania w `~/Backups/openclaw-migrations/`. -- Jeśli używasz wielu kont Matrix, ustaw `channels.matrix.defaultAccount` przed aktualizacją ze starego układu flat-store, aby OpenClaw wiedział, które konto ma otrzymać ten współdzielony stary stan. -- Jeśli poprzedni plugin przechowywał lokalnie klucz deszyfrujący kopii zapasowej room key Matrix, uruchomienie lub `openclaw doctor --fix` automatycznie zaimportuje go do nowego przepływu recovery key. -- Jeśli access token Matrix zmienił się po przygotowaniu migracji, uruchomienie skanuje teraz sąsiednie katalogi główne storage oparte o hash tokenu w poszukiwaniu oczekującego starego stanu do przywrócenia, zanim zrezygnuje z automatycznego przywracania kopii zapasowej. -- Jeśli access token Matrix zmieni się później dla tego samego konta, homeservera i użytkownika, OpenClaw będzie teraz preferować ponowne użycie najbardziej kompletnego istniejącego katalogu głównego storage opartego o hash tokenu zamiast zaczynać od pustego katalogu stanu Matrix. -- Przy następnym uruchomieniu gateway klucze pokojów z kopii zapasowej zostaną automatycznie przywrócone do nowego store kryptograficznego. -- Jeśli stary plugin miał tylko lokalne room key, których nigdy nie zarchiwizowano, OpenClaw wyraźnie ostrzeże. Tych kluczy nie da się automatycznie wyeksportować z poprzedniego rust crypto store, więc część starej zaszyfrowanej historii może pozostać niedostępna do czasu ręcznego odzyskania. -- Zobacz [Matrix migration](/pl/install/migrating-matrix), aby poznać pełny przepływ aktualizacji, ograniczenia, polecenia odzyskiwania i częste komunikaty migracji. +- OpenClaw automatycznie ponownie używa tego samego konta Matrix, tokena dostępu i tożsamości urządzenia, gdy to możliwe. +- Zanim zostaną uruchomione jakiekolwiek istotne zmiany migracyjne Matrix, OpenClaw tworzy lub ponownie używa migawki odzyskiwania w `~/Backups/openclaw-migrations/`. +- Jeśli używasz wielu kont Matrix, ustaw `channels.matrix.defaultAccount` przed aktualizacją ze starego płaskiego układu store, aby OpenClaw wiedział, które konto ma otrzymać ten współdzielony stan legacy. +- Jeśli poprzednia wtyczka przechowywała lokalnie klucz deszyfrujący kopii zapasowej kluczy pokojów Matrix, uruchamianie lub `openclaw doctor --fix` automatycznie zaimportuje go do nowego przepływu klucza odzyskiwania. +- Jeśli token dostępu Matrix zmienił się po przygotowaniu migracji, uruchamianie teraz skanuje sąsiednie katalogi główne przechowywania według skrótu tokena w poszukiwaniu oczekującego stanu przywracania legacy, zanim zrezygnuje z automatycznego przywracania kopii zapasowej. +- Jeśli token dostępu Matrix zmieni się później dla tego samego konta, homeservera i użytkownika, OpenClaw woli teraz ponownie użyć najbardziej kompletnego istniejącego katalogu głównego według skrótu tokena zamiast rozpoczynać od pustego katalogu stanu Matrix. +- Przy następnym uruchomieniu gatewaya klucze pokojów z kopii zapasowej zostaną automatycznie przywrócone do nowego store kryptograficznego. +- Jeśli stara wtyczka miała lokalne klucze pokojów, których nigdy nie zarchiwizowano, OpenClaw wyświetli wyraźne ostrzeżenie. Tych kluczy nie można automatycznie wyeksportować z poprzedniego rust crypto store, więc część starej zaszyfrowanej historii może pozostać niedostępna, dopóki nie zostanie odzyskana ręcznie. +- Zobacz [Migracja Matrix](/pl/install/migrating-matrix), aby poznać pełny przepływ aktualizacji, ograniczenia, polecenia odzyskiwania i typowe komunikaty migracyjne. -Zaszyfrowany stan runtime jest zorganizowany w katalogach głównych per konto, per użytkownik, opartych o hash tokenu w +Stan zaszyfrowanego runtime jest zorganizowany pod katalogami głównymi per konto, per użytkownik, według skrótu tokena w `~/.openclaw/matrix/accounts//__//`. -Ten katalog zawiera sync store (`bot-storage.json`), crypto store (`crypto/`), -plik recovery key (`recovery-key.json`), snapshot IndexedDB (`crypto-idb-snapshot.json`), -powiązania wątków (`thread-bindings.json`) oraz stan weryfikacji przy uruchomieniu (`startup-verification.json`), +Ten katalog zawiera store synchronizacji (`bot-storage.json`), store kryptograficzny (`crypto/`), +plik klucza odzyskiwania (`recovery-key.json`), migawkę IndexedDB (`crypto-idb-snapshot.json`), +powiązania wątków (`thread-bindings.json`) i stan weryfikacji przy uruchamianiu (`startup-verification.json`), gdy te funkcje są używane. Gdy token zmienia się, ale tożsamość konta pozostaje taka sama, OpenClaw ponownie używa najlepszego istniejącego -katalogu głównego dla tej krotki konto/homeserver/użytkownik, aby wcześniejszy stan synchronizacji, stan kryptograficzny, powiązania wątków -i stan weryfikacji przy uruchomieniu pozostawały widoczne. +katalogu głównego dla krotki konto/homeserver/użytkownik, aby poprzedni stan synchronizacji, stan kryptograficzny, powiązania wątków +i stan weryfikacji przy uruchamianiu pozostały widoczne. ### Model Node crypto store -Matrix E2EE w tym pluginie używa oficjalnej ścieżki Rust crypto `matrix-js-sdk` w Node. +Matrix E2EE w tej wtyczce używa oficjalnej ścieżki Rust crypto `matrix-js-sdk` w Node. Ta ścieżka oczekuje trwałości opartej na IndexedDB, jeśli chcesz, aby stan kryptograficzny przetrwał restarty. OpenClaw obecnie zapewnia to w Node przez: -- użycie `fake-indexeddb` jako shima API IndexedDB oczekiwanego przez SDK -- przywracanie zawartości Rust crypto IndexedDB z `crypto-idb-snapshot.json` przed `initRustCrypto` +- używanie `fake-indexeddb` jako shimu API IndexedDB oczekiwanego przez SDK +- przywracanie zawartości IndexedDB Rust crypto z `crypto-idb-snapshot.json` przed `initRustCrypto` - utrwalanie zaktualizowanej zawartości IndexedDB z powrotem do `crypto-idb-snapshot.json` po inicjalizacji i podczas runtime -- serializowanie przywracania i utrwalania snapshotów względem `crypto-idb-snapshot.json` za pomocą doradczego blokowania pliku, aby utrwalanie w runtime gateway i utrzymanie przez CLI nie ścigały się o ten sam plik snapshotu +- serializowanie przywracania i utrwalania migawki względem `crypto-idb-snapshot.json` za pomocą doradczego blokowania pliku, aby utrwalanie runtime gatewaya i konserwacja CLI nie ścigały się o ten sam plik migawki -To jest warstwa zgodności/przechowywania, a nie niestandardowa implementacja kryptografii. -Plik snapshotu jest wrażliwym stanem runtime i jest przechowywany z restrykcyjnymi uprawnieniami do pliku. -W modelu bezpieczeństwa OpenClaw host gateway i lokalny katalog stanu OpenClaw już znajdują się wewnątrz granicy zaufanego operatora, więc jest to przede wszystkim kwestia operacyjnej trwałości, a nie osobna granica zaufania zdalnego. +To warstwa zgodności/przechowywania, a nie niestandardowa implementacja kryptografii. +Plik migawki jest wrażliwym stanem runtime i jest przechowywany z restrykcyjnymi uprawnieniami do pliku. +W modelu bezpieczeństwa OpenClaw host gatewaya i lokalny katalog stanu OpenClaw już znajdują się wewnątrz granicy zaufanego operatora, więc jest to przede wszystkim kwestia operacyjnej trwałości, a nie osobna zdalna granica zaufania. -Planowane usprawnienie: +Planowane ulepszenie: -- dodać obsługę SecretRef dla trwałego materiału kluczy Matrix, aby recovery key i powiązane sekrety szyfrowania store mogły pochodzić z providerów sekretów OpenClaw zamiast wyłącznie z lokalnych plików +- dodać obsługę SecretRef dla trwałego materiału kluczy Matrix, aby klucze odzyskiwania i powiązane sekrety szyfrowania store mogły pochodzić od dostawców sekretów OpenClaw zamiast wyłącznie z plików lokalnych ## Zarządzanie profilem -Zaktualizuj profil własny Matrix dla wybranego konta za pomocą: +Zaktualizuj własny profil Matrix dla wybranego konta za pomocą: ```bash 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 avatarów `mxc://`. Gdy przekażesz URL avatara `http://` lub `https://`, OpenClaw najpierw prześle go do Matrix i zapisze rozwiązany URL `mxc://` z powrotem do `channels.matrix.avatarUrl` (lub wybranego nadpisania konta). +Matrix bezpośrednio akceptuje adresy URL awatarów `mxc://`. Gdy przekażesz adres URL awatara `http://` lub `https://`, OpenClaw najpierw prześle go do Matrix i zapisze rozwiązany adres URL `mxc://` z powrotem do `channels.matrix.avatarUrl` (lub nadpisania wybranego konta). ## Automatyczne powiadomienia o weryfikacji -Matrix publikuje teraz powiadomienia o cyklu życia weryfikacji bezpośrednio w ścisłym pokoju DM weryfikacji jako wiadomości `m.notice`. +Matrix publikuje teraz powiadomienia o cyklu życia weryfikacji bezpośrednio w ścisłym pokoju wiadomości prywatnych do weryfikacji jako wiadomości `m.notice`. Obejmuje to: -- powiadomienia o prośbie o weryfikację -- powiadomienia o gotowości do weryfikacji (z wyraźną wskazówką „Zweryfikuj przez emoji”) +- powiadomienia o żądaniu weryfikacji +- powiadomienia o gotowości do weryfikacji (z jawną wskazówką „Zweryfikuj przez emoji”) - powiadomienia o rozpoczęciu i zakończeniu weryfikacji - szczegóły SAS (emoji i liczby dziesiętne), gdy są dostępne -Przychodzące prośby o weryfikację z innego klienta Matrix są śledzone i automatycznie akceptowane przez OpenClaw. -W przepływach samoweryfikacji OpenClaw automatycznie rozpoczyna też przepływ SAS, gdy weryfikacja emoji staje się dostępna, i potwierdza swoją stronę. -W przypadku próśb o weryfikację od innego użytkownika/urządzenia Matrix OpenClaw automatycznie akceptuje prośbę, a następnie czeka na normalny przebieg przepływu SAS. +Przychodzące żądania weryfikacji z innego klienta Matrix są śledzone i automatycznie akceptowane przez OpenClaw. +W przepływach samoweryfikacji OpenClaw także automatycznie rozpoczyna przepływ SAS, gdy weryfikacja emoji staje się dostępna, i potwierdza swoją stronę. +W przypadku żądań weryfikacji od innego użytkownika/urządzenia Matrix OpenClaw automatycznie akceptuje żądanie, a następnie czeka, aż przepływ SAS przebiegnie normalnie. Aby zakończyć weryfikację, nadal musisz porównać emoji lub dziesiętny SAS w swoim kliencie Matrix i potwierdzić tam „Pasują”. -OpenClaw nie akceptuje bezrefleksyjnie duplikatów przepływów inicjowanych przez siebie. Przy uruchomieniu pomija tworzenie nowej prośby, jeśli prośba o samoweryfikację już oczekuje. +OpenClaw nie akceptuje bezrefleksyjnie samodzielnie zainicjowanych zduplikowanych przepływów. Podczas uruchamiania pomija tworzenie nowego żądania, jeśli żądanie samoweryfikacji jest już oczekujące. -Powiadomienia protokołowe/systemowe weryfikacji nie są przekazywane do pipeline czatu agenta, więc nie generują `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 zaszyfrowanych pokojach. -Wyświetl je poleceniem: +Na koncie mogą gromadzić się stare urządzenia Matrix zarządzane przez OpenClaw, co utrudnia interpretację zaufania w zaszyfrowanych pokojach. +Wyświetl ich listę poleceniem: ```bash openclaw matrix devices list ``` -Usuń nieaktualne urządzenia zarządzane przez OpenClaw poleceniem: +Usuń nieaktualne urządzenia Matrix zarządzane przez OpenClaw poleceniem: ```bash openclaw matrix devices prune-stale ``` -### Naprawa Direct Room +### Naprawa pokoju bezpośredniego -Jeśli stan wiadomości bezpośrednich się rozjedzie, OpenClaw może skończyć ze starymi mapowaniami `m.direct`, które wskazują stare pokoje solo zamiast aktywnego DM. Sprawdź bieżące mapowanie dla partnera przez: +Jeśli stan wiadomości prywatnych się rozjedzie, OpenClaw może skończyć ze starymi mapowaniami `m.direct`, które wskazują na dawne pokoje solo zamiast aktywnej wiadomości prywatnej. Sprawdź bieżące mapowanie dla partnera za pomocą: ```bash openclaw matrix direct inspect --user-id @alice:example.org ``` -Napraw je przez: +Napraw je poleceniem: ```bash openclaw matrix direct repair --user-id @alice:example.org ``` -Naprawa zachowuje logikę specyficzną dla Matrix wewnątrz pluginu: +Naprawa zachowuje logikę specyficzną dla Matrix wewnątrz wtyczki: -- preferuje ścisły DM 1:1, który jest już zmapowany w `m.direct` -- w przeciwnym razie wraca do dowolnego aktualnie dołączonego ścisłego DM 1:1 z tym użytkownikiem -- jeśli nie istnieje żaden zdrowy DM, tworzy nowy pokój bezpośredni i przepisuje `m.direct`, aby na niego wskazywało +- preferuje ścisłą wiadomość prywatną 1:1, która jest już zmapowana w `m.direct` +- w przeciwnym razie przechodzi do dowolnej aktualnie dołączonej ścisłej wiadomości prywatnej 1:1 z tym użytkownikiem +- jeśli nie istnieje zdrowa wiadomość prywatna, tworzy nowy pokój bezpośredni i przepisuje `m.direct`, aby wskazywało na niego -Przepływ naprawy nie usuwa automatycznie starych pokoi. Po prostu wybiera zdrowy DM i aktualizuje mapowanie, aby nowe wysyłki Matrix, powiadomienia weryfikacyjne i inne przepływy wiadomości bezpośrednich znów kierowały się do właściwego pokoju. +Przepływ naprawy nie usuwa automatycznie starych pokojów. Wybiera tylko zdrową wiadomość prywatną i aktualizuje mapowanie, tak aby nowe wysyłki Matrix, powiadomienia o weryfikacji i inne przepływy wiadomości bezpośrednich znów trafiały do właściwego pokoju. ## 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 narzędzia wiadomości. -- `dm.sessionScope: "per-user"` (domyślnie) utrzymuje routowanie DM Matrix w zakresie nadawcy, więc wiele pokoi DM może współdzielić jedną sesję, gdy rozwiążą 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łych kontroli uwierzytelniania DM i allowlisty. -- Jawne powiązania rozmów Matrix nadal mają pierwszeństwo przed `dm.sessionScope`, więc powiązane pokoje i wątki zachowują wybrany docelowy target sesji. -- `threadReplies: "off"` utrzymuje odpowiedzi na poziomie głównym i pozostawia przychodzące wiadomości w wątkach w sesji nadrzędnej. +- `dm.sessionScope: "per-user"` (domyślnie) utrzymuje routowanie wiadomości prywatnych Matrix w zakresie nadawcy, dzięki czemu wiele pokojów wiadomości prywatnych może współdzielić jedną sesję, jeśli rozwiążą się do tego samego partnera. +- `dm.sessionScope: "per-room"` izoluje każdy pokój wiadomości prywatnych Matrix we własnym kluczu sesji, nadal używając zwykłych kontroli uwierzytelniania i list dozwolonych dla wiadomości prywatnych. +- Jawne powiązania konwersacji Matrix nadal mają pierwszeństwo przed `dm.sessionScope`, więc powiązane pokoje i wątki zachowują wybrany docelowy identyfikator sesji. +- `threadReplies: "off"` utrzymuje odpowiedzi na poziomie głównym i zachowuje przychodzące wiadomości wątkowane na sesji nadrzędnej. - `threadReplies: "inbound"` odpowiada wewnątrz wątku tylko wtedy, gdy wiadomość przychodząca była już w tym wątku. -- `threadReplies: "always"` utrzymuje odpowiedzi pokojowe w wątku zakorzenionym w wiadomości wyzwalającej i kieruje tę rozmowę przez odpowiadającą jej sesję o zakresie wątku od pierwszej wiadomości wyzwalającej. -- `dm.threadReplies` nadpisuje ustawienie najwyższego poziomu tylko dla DM. Na przykład możesz utrzymać izolację wątków pokojowych, a jednocześnie pozostawić DM-y płaskie. -- Przychodzące wiadomości w wątkach zawierają wiadomość główną wątku jako dodatkowy kontekst agenta. -- Wysyłki przez narzędzie wiadomości teraz automatycznie dziedziczą bieżący wątek Matrix, gdy celem jest ten sam pokój albo ten sam target użytkownika DM, chyba że podano jawne `threadId`. -- Ponowne użycie targetu 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 o 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 awaryjną komendą `/focus`, gdy włączone są powiązania wątków i podpowiedź `dm.sessionScope`. -- Powiązania wątków w runtime są obsługiwane w Matrix. `/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age` oraz związane z wątkiem `/acp spawn` działają teraz w pokojach i DM-ach Matrix. -- Najwyższego poziomu `/focus` w pokoju/DM Matrix tworzy nowy wątek Matrix i wiąże go z docelową sesją, gdy `threadBindings.spawnSubagentSessions=true`. +- `threadReplies: "always"` utrzymuje odpowiedzi pokojów we wątku zakorzenionym w wiadomości wyzwalającej i prowadzi tę konwersację przez odpowiadającą jej sesję o zakresie wątku od pierwszej wiadomości wyzwalającej. +- `dm.threadReplies` nadpisuje ustawienie najwyższego poziomu tylko dla wiadomości prywatnych. Na przykład możesz izolować wątki w pokojach, a jednocześnie zachować płaskie wiadomości prywatne. +- Przychodzące wiadomości wątkowane zawierają wiadomość główną wątku jako dodatkowy kontekst agenta. +- Wysyłki narzędzia wiadomości teraz automatycznie dziedziczą bieżący wątek Matrix, gdy celem jest ten sam pokój lub ten sam użytkownik docelowy wiadomości prywatnej, chyba że jawnie podano `threadId`. +- Ponowne użycie celu użytkownika wiadomości prywatnej dla tej samej sesji działa tylko wtedy, gdy bieżące metadane sesji potwierdzają tego samego partnera wiadomości prywatnej na tym samym koncie Matrix; w przeciwnym razie OpenClaw wraca do normalnego routowania w zakresie użytkownika. +- Gdy OpenClaw zauważy, że pokój wiadomości prywatnych Matrix koliduje z innym pokojem wiadomości prywatnych w tej samej współdzielonej sesji Matrix DM, publikuje w tym pokoju jednorazowe `m.notice` z furtką awaryjną `/focus`, gdy powiązania wątków są włączone, oraz wskazówką `dm.sessionScope`. +- Powiązania wątków w runtime są obsługiwane dla Matrix. `/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age` i powiązane z wątkiem `/acp spawn` działają teraz w pokojach i wiadomościach prywatnych Matrix. +- Główne `/focus` w pokoju/wiadomości prywatnej Matrix tworzy nowy wątek Matrix i wiąże go z docelową sesją, gdy `threadBindings.spawnSubagentSessions=true`. - Uruchomienie `/focus` lub `/acp spawn --thread here` wewnątrz istniejącego wątku Matrix wiąże zamiast tego bieżący wątek. -## Powiązania rozmów ACP +## Powiązania konwersacji ACP -Pokoje Matrix, DM-y i istniejące wątki Matrix można przekształcić w trwałe obszary robocze ACP bez zmiany powierzchni czatu. +Pokoje Matrix, wiadomości prywatne i istniejące wątki Matrix można przekształcić w trwałe przestrzenie robocze ACP bez zmiany powierzchni czatu. Szybki przepływ dla operatora: -- Uruchom `/acp spawn codex --bind here` wewnątrz DM Matrix, pokoju lub istniejącego wątku, którego chcesz nadal używać. -- W najwyższego poziomu DM lub pokoju Matrix bieżący DM/pokój pozostaje powierzchnią czatu, a przyszłe wiadomości są kierowane do uruchomionej sesji ACP. -- W istniejącym wątku Matrix `--bind here` wiąże bieżący wątek w miejscu. -- `/new` i `/reset` resetują tę samą powiązaną sesję ACP w miejscu. +- Uruchom `/acp spawn codex --bind here` wewnątrz wiadomości prywatnej, pokoju lub istniejącego wątku Matrix, którego chcesz nadal używać. +- W głównej wiadomości prywatnej lub pokoju Matrix bieżąca wiadomość prywatna/pokój pozostaje powierzchnią czatu, a przyszłe wiadomości są kierowane do uruchomionej sesji ACP. +- W istniejącym wątku Matrix `--bind here` wiąże ten bieżący wątek na miejscu. +- `/new` i `/reset` resetują tę samą powiązaną sesję ACP na miejscu. - `/acp close` zamyka sesję ACP i usuwa powiązanie. Uwagi: @@ -788,35 +788,35 @@ Matrix dziedziczy globalne wartości domyślne z `session.threadBindings`, a tak - `threadBindings.spawnSubagentSessions` - `threadBindings.spawnAcpSessions` -Flagi uruchamiania powiązanego z wątkiem w Matrix są opcjonalne: +Flagi uruchamiania powiązanego z wątkiem Matrix są opcjonalne: -- Ustaw `threadBindings.spawnSubagentSessions: true`, aby pozwolić najwyższego poziomu `/focus` tworzyć i wiązać nowe wątki Matrix. +- Ustaw `threadBindings.spawnSubagentSessions: true`, aby pozwolić głównemu `/focus` tworzyć i wiązać nowe wątki Matrix. - Ustaw `threadBindings.spawnAcpSessions: true`, aby pozwolić `/acp spawn --thread auto|here` wiązać sesje ACP z wątkami Matrix. ## Reakcje -Matrix obsługuje wychodzące akcje reakcji, przychodzące powiadomienia o reakcjach i przychodzące reakcje potwierdzające. +Matrix obsługuje wychodzące działania reakcji, przychodzące powiadomienia o reakcjach i przychodzące reakcje potwierdzające. -- Narzędzia wychodzących reakcji są bramkowane przez `channels["matrix"].actions.reactions`. +- Narzędzia wychodzących reakcji 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 dla tego zdarzenia. -- `remove: true` usuwa tylko określoną reakcję emoji z konta bota. +- `emoji=""` usuwa własne reakcje konta bota na tym zdarzeniu. +- `remove: true` usuwa z konta bota tylko wskazaną reakcję emoji. -Zakres reakcji potwierdzających jest rozstrzygany w standardowej kolejności OpenClaw: +Zakres reakcji potwierdzających jest rozwiązywany w standardowej kolejności OpenClaw: - `channels["matrix"].accounts..ackReaction` - `channels["matrix"].ackReaction` - `messages.ackReaction` - zapasowe emoji tożsamości agenta -Zakres reakcji potwierdzających jest rozstrzygany w tej kolejności: +Zakres reakcji potwierdzających 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` @@ -824,31 +824,31 @@ Tryb powiadomień o reakcjach jest rozstrzygany w tej kolejności: Bieżące zachowanie: -- `reactionNotifications: "own"` przekazuje dodane zdarzenia `m.reaction`, gdy są kierowane do wiadomości Matrix napisanych przez bota. -- `reactionNotifications: "off"` wyłącza zdarzenia systemowe reakcji. -- Usunięcia reakcji nadal 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 systemowe zdarzenia reakcji. +- Usunięcia reakcji nadal nie są syntetyzowane do zdarzeń systemowych, ponieważ Matrix udostępnia je jako redakcje, a nie jako samodzielne usunięcia `m.reaction`. ## Kontekst historii -- `channels.matrix.historyLimit` kontroluje, ile ostatnich wiadomości pokoju jest dołączanych jako `InboundHistory`, gdy wiadomość w pokoju Matrix wyzwoli agenta. -- Pole to wraca do `messages.groupChat.historyLimit`. Jeśli oba są nieustawione, efektywna wartość domyślna to `0`, więc wiadomości pokojowe bramkowane wzmianką nie są buforowane. 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 pokojowe, które jeszcze nie wywołały odpowiedzi, a następnie wykonuje snapshot tego okna, gdy nadejdzie wzmianka lub inny trigger. -- Bieżąca wiadomość wyzwalająca nie jest dołączana do `InboundHistory`; pozostaje w głównej treści przychodzącej dla tej tury. -- Ponowne próby tego samego zdarzenia Matrix ponownie używają oryginalnego snapshotu historii zamiast przesuwać się do przodu do nowszych wiadomości pokoju. +- `channels.matrix.historyLimit` kontroluje liczbę ostatnich wiadomości z pokoju dołączanych jako `InboundHistory`, gdy wiadomość z pokoju Matrix wyzwala agenta. +- Wartość zapasowa pochodzi z `messages.groupChat.historyLimit`. Jeśli obie wartości nie są ustawione, efektywna wartość domyślna to `0`, więc wiadomości z pokoju wymagające wzmianki nie są buforowane. Ustaw `0`, aby wyłączyć. +- Historia pokoju Matrix dotyczy tylko pokoju. Wiadomości prywatne nadal używają zwykłej historii sesji. +- Historia pokoju Matrix obejmuje tylko stan oczekujący: OpenClaw buforuje wiadomości z pokoju, które nie wywołały jeszcze odpowiedzi, a następnie robi migawkę tego okna, gdy nadejdzie wzmianka lub inny wyzwalacz. +- Bieżąca wiadomość wyzwalająca nie jest dołączana do `InboundHistory`; pozostaje w głównej treści przychodzącej tej tury. +- Ponowienia dla tego samego zdarzenia Matrix używają pierwotnej migawki historii zamiast przesuwać się do przodu do nowszych wiadomości z pokoju. ## Widoczność kontekstu Matrix obsługuje wspólną kontrolę `contextVisibility` dla uzupełniającego kontekstu pokoju, takiego jak pobrany tekst odpowiedzi, korzenie wątków i oczekująca historia. -- `contextVisibility: "all"` jest ustawieniem domyślnym. Uzupełniający kontekst jest zachowywany w otrzymanej postaci. -- `contextVisibility: "allowlist"` filtruje uzupełniający kontekst do nadawców dozwolonych przez aktywne kontrole allowlisty pokoju/użytkownika. +- `contextVisibility: "all"` to ustawienie domyślne. Uzupełniający kontekst jest zachowywany w otrzymanej postaci. +- `contextVisibility: "allowlist"` filtruje uzupełniający kontekst do nadawców dozwolonych przez aktywne sprawdzanie list dozwolonych pokoju/użytkownika. - `contextVisibility: "allowlist_quote"` działa jak `allowlist`, ale nadal zachowuje jedną jawną cytowaną odpowiedź. -To ustawienie wpływa na widoczność uzupełniającego kontekstu, a nie na to, czy sama wiadomość przychodząca może wyzwolić odpowiedź. -Autoryzacja wyzwalaczy nadal pochodzi z ustawień `groupPolicy`, `groups`, `groupAllowFrom` i polityki DM. +To ustawienie wpływa na widoczność kontekstu uzupełniającego, a nie na to, czy sama wiadomość przychodząca może wywołać odpowiedź. +Autoryzacja wyzwolenia nadal pochodzi z ustawień `groupPolicy`, `groups`, `groupAllowFrom` i zasad wiadomości prywatnych. -## Przykład polityki DM i pokoju +## Przykład zasad wiadomości prywatnych i pokojów ```json5 { @@ -871,60 +871,62 @@ Autoryzacja wyzwalaczy nadal pochodzi z ustawień `groupPolicy`, `groups`, `grou } ``` -Zobacz [Groups](/pl/channels/groups), aby poznać zachowanie bramkowania wzmiankami i allowlisty. +Zobacz [Grupy](/pl/channels/groups), aby dowiedzieć się więcej o wymuszaniu wzmianki i zachowaniu listy dozwolonych. -Przykład parowania dla DM-ów Matrix: +Przykład parowania dla wiadomości prywatnych Matrix: ```bash openclaw pairing list matrix openclaw pairing approve matrix ``` -Jeśli niezatwierdzony użytkownik Matrix nadal do ciebie pisze 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 nadal wysyła wiadomości przed zatwierdzeniem, OpenClaw ponownie użyje tego samego oczekującego kodu parowania i może po krótkim czasie odnowienia ponownie wysłać przypomnienie zamiast generować nowy kod. -Zobacz [Pairing](/pl/channels/pairing), aby poznać wspólny przepływ parowania DM i układ przechowywania. +Zobacz [Parowanie](/pl/channels/pairing), aby poznać wspólny przepływ parowania wiadomości prywatnych i układ przechowywania. ## Zatwierdzenia exec -Matrix może działać jako klient zatwierdzeń exec dla konta Matrix. +Matrix może działać jako natywny klient zatwierdzeń dla konta Matrix. Natywne +przełączniki routowania wiadomości prywatnych/kanałów nadal znajdują się w konfiguracji zatwierdzeń exec: - `channels.matrix.execApprovals.enabled` -- `channels.matrix.execApprovals.approvers` (opcjonalne; wraca do `channels.matrix.dm.allowFrom`) +- `channels.matrix.execApprovals.approvers` (opcjonalne; wartość zapasowa pochodzi z `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 exec, gdy `enabled` jest nieustawione lub ma wartość `"auto"` i można rozwiązać co najmniej jednego zatwierdzającego, albo z `execApprovals.approvers`, albo z `channels.matrix.dm.allowFrom`. Ustaw `enabled: false`, aby jawnie wyłączyć Matrix jako natywnego klienta zatwierdzeń. W przeciwnym razie prośby o zatwierdzenie wracają do innych skonfigurowanych ścieżek zatwierdzania lub do polityki fallback zatwierdzeń exec. +Zatwierdzający muszą być identyfikatorami użytkowników Matrix, takimi jak `@owner:example.org`. Matrix automatycznie włącza natywne zatwierdzenia, gdy `enabled` nie jest ustawione lub ma wartość `"auto"` i można rozwiązać co najmniej jednego zatwierdzającego. Zatwierdzenia exec najpierw używają `execApprovals.approvers` i mogą wracać do `channels.matrix.dm.allowFrom`. Zatwierdzenia wtyczek autoryzują przez `channels.matrix.dm.allowFrom`. Ustaw `enabled: false`, aby jawnie wyłączyć Matrix jako natywnego klienta zatwierdzeń. W przeciwnym razie żądania zatwierdzenia wracają do innych skonfigurowanych tras zatwierdzeń lub do zapasowej polityki zatwierdzeń. -Natywne routowanie Matrix dotyczy dziś tylko exec: +Natywne routowanie Matrix obsługuje teraz oba rodzaje zatwierdzeń: -- `channels.matrix.execApprovals.*` kontroluje natywne routowanie DM/kanału dla zatwierdzeń exec. -- Zatwierdzenia pluginów nadal używają współdzielonego `/approve` w tym samym czacie oraz dowolnego skonfigurowanego przekazywania `approvals.plugin`. -- Matrix może nadal ponownie używać `channels.matrix.dm.allowFrom` do autoryzacji zatwierdzania pluginów, gdy może bezpiecznie wywnioskować zatwierdzających, ale nie udostępnia osobnej natywnej ścieżki rozsyłania DM/kanału dla zatwierdzeń pluginów. +- `channels.matrix.execApprovals.*` kontroluje natywny tryb fanoutu wiadomości prywatnych/kanałów dla promptów zatwierdzeń Matrix. +- Zatwierdzenia exec używają zbioru zatwierdzających exec z `execApprovals.approvers` lub `channels.matrix.dm.allowFrom`. +- Zatwierdzenia wtyczek używają listy dozwolonych wiadomości prywatnych Matrix z `channels.matrix.dm.allowFrom`. +- Skróty reakcji Matrix i aktualizacje wiadomości dotyczą zarówno zatwierdzeń exec, jak i zatwierdzeń wtyczek. Zasady dostarczania: -- `target: "dm"` wysyła prompty zatwierdzeń do DM-ów zatwierdzających -- `target: "channel"` odsyła prompt do źródłowego pokoju lub DM Matrix -- `target: "both"` wysyła do DM-ów zatwierdzających i do źródłowego pokoju lub DM Matrix +- `target: "dm"` wysyła prompty zatwierdzeń do wiadomości prywatnych zatwierdzających +- `target: "channel"` wysyła prompt z powrotem do źródłowego pokoju lub wiadomości prywatnej Matrix +- `target: "both"` wysyła do wiadomości prywatnych zatwierdzających oraz do źródłowego pokoju lub wiadomości prywatnej Matrix Prompty zatwierdzeń Matrix inicjalizują skróty reakcji na głównej wiadomości zatwierdzenia: -- `✅` = zezwól raz +- `✅` = zezwól jednorazowo - `❌` = odmów - `♾️` = zezwól zawsze, gdy taka decyzja jest dozwolona przez efektywną politykę exec -Zatwierdzający mogą reagować na tę wiadomość albo użyć awaryjnych komend slash: `/approve allow-once`, `/approve allow-always` lub `/approve deny`. +Zatwierdzający mogą reagować na tę wiadomość albo użyć zapasowych poleceń ukośnikowych: `/approve allow-once`, `/approve allow-always` lub `/approve deny`. -Tylko rozwiązani zatwierdzający mogą zatwierdzać lub odmawiać. Dostarczanie do kanału zawiera tekst polecenia, więc `channel` lub `both` włączaj tylko w zaufanych pokojach. +Tylko rozwiązani zatwierdzający mogą zatwierdzać lub odrzucać. Dla zatwierdzeń exec dostarczanie kanałowe zawiera tekst polecenia, więc włączaj `channel` lub `both` tylko w zaufanych pokojach. -Prompty zatwierdzeń Matrix ponownie używają wspólnego planera zatwierdzeń z core. Natywna powierzchnia specyficzna dla Matrix jest tylko transportem dla zatwierdzeń exec: routowaniem pokoju/DM oraz zachowaniem wysyłania/aktualizacji/usuwania wiadomości. +Prompty zatwierdzeń Matrix ponownie używają wspólnego rdzeniowego planera zatwierdzeń. Natywna powierzchnia specyficzna dla Matrix obsługuje routowanie pokój/wiadomość prywatna, reakcje i zachowanie wysyłania/aktualizacji/usuwania wiadomości zarówno dla zatwierdzeń exec, jak i zatwierdzeń wtyczek. Nadpisanie per konto: - `channels.matrix.accounts..execApprovals` -Powiązana dokumentacja: [Exec approvals](/pl/tools/exec-approvals) +Powiązana dokumentacja: [Zatwierdzenia exec](/pl/tools/exec-approvals) ## Przykład wielu kont @@ -956,21 +958,21 @@ Powiązana dokumentacja: [Exec approvals](/pl/tools/exec-approvals) } ``` -Wartości najwyższego poziomu `channels.matrix` działają jako ustawienia domyślne dla nazwanych kont, chyba że konto je nadpisze. -Możesz ograniczyć dziedziczony wpis pokoju do jednego konta Matrix za pomocą `groups..account` (lub starszego `rooms..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 z siebie nie tworzą osobnego niejawnego konta domyślnego. OpenClaw syntetyzuje najwyższego poziomu konto `default` tylko wtedy, gdy to domyślne konto ma świeże uwierzytelnianie (`homeserver` plus `accessToken` albo `homeserver` plus `userId` i `password`); nazwane konta mogą nadal pozostawać wykrywalne przy użyciu `homeserver` plus `userId`, gdy zbuforowane poświadczenia później spełnią warunki uwierzytelnienia. -Jeśli Matrix ma już dokładnie jedno nazwane konto albo `defaultAccount` wskazuje istniejący klucz nazwanego konta, promocja naprawy/konfiguracji z pojedynczego konta do wielu kont 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. +Wartości najwyższego poziomu `channels.matrix` działają jako wartości domyślne dla nazwanych kont, chyba że konto je nadpisze. +Możesz ograniczyć odziedziczone wpisy pokojów do jednego konta Matrix za pomocą `groups..account` (lub starszego `rooms..account`). +Wpisy bez `account` pozostają współdzielone przez wszystkie konta Matrix, a wpisy z `account: "default"` nadal działają, gdy konto domyślne jest skonfigurowane bezpośrednio na najwyższym poziomie `channels.matrix.*`. +Częściowe współdzielone wartości domyślne uwierzytelniania same z siebie nie tworzą osobnego niejawnego konta domyślnego. OpenClaw syntetyzuje najwyższego poziomu konto `default` tylko wtedy, gdy to konto domyślne ma świeże uwierzytelnianie (`homeserver` plus `accessToken` albo `homeserver` plus `userId` i `password`); nazwane konta mogą nadal pozostawać wykrywalne na podstawie `homeserver` plus `userId`, gdy zbuforowane poświadczenia później spełnią wymagania uwierzytelniania. +Jeśli Matrix ma już dokładnie jedno nazwane konto albo `defaultAccount` wskazuje istniejący klucz nazwanego konta, promocja naprawy/konfiguracji z jednego konta do wielu zachowuje to konto zamiast tworzyć nowy wpis `accounts.default`. Do tego promowanego konta przenoszone są tylko klucze uwierzytelniania/bootstrap Matrix; współdzielone klucze polityki dostarczania pozostają na najwyższym poziomie. Ustaw `defaultAccount`, jeśli chcesz, aby OpenClaw preferował jedno nazwane konto Matrix do niejawnego routowania, sondowania i operacji CLI. -Jeśli skonfigurujesz wiele nazwanych kont, ustaw `defaultAccount` lub przekazuj `--account ` w poleceniach CLI, które polegają na niejawnym wyborze konta. -Przekazuj `--account ` do `openclaw matrix verify ...` i `openclaw matrix devices ...`, gdy chcesz nadpisać ten niejawny wybór dla pojedynczego polecenia. +Jeśli skonfigurujesz wiele nazwanych kont, ustaw `defaultAccount` albo przekazuj `--account ` dla poleceń CLI zależnych od niejawnego wyboru konta. +Przekaż `--account ` do `openclaw matrix verify ...` i `openclaw matrix devices ...`, gdy chcesz nadpisać ten niejawny wybór dla pojedynczego polecenia. ## Prywatne/LAN homeservery -Domyślnie OpenClaw blokuje prywatne/wewnętrzne homeservery Matrix jako ochronę przed SSRF, chyba że -jawnie włączysz je per konto. +Domyślnie OpenClaw blokuje prywatne/wewnętrzne homeservery Matrix dla ochrony SSRF, chyba że +jawnie włączysz wyjątek per konto. -Jeśli twój homeserver działa na localhost, adresie LAN/Tailscale lub wewnętrznej nazwie hosta, włącz +Jeśli twój homeserver działa na localhost, adresie LAN/Tailscale albo wewnętrznej nazwie hosta, włącz `network.dangerouslyAllowPrivateNetwork` dla tego konta Matrix: ```json5 @@ -987,7 +989,7 @@ Jeśli twój homeserver działa na localhost, adresie LAN/Tailscale lub wewnętr } ``` -Przykład konfiguracji przez CLI: +Przykład konfiguracji w CLI: ```bash openclaw matrix account add \ @@ -997,10 +999,10 @@ openclaw matrix account add \ --access-token syt_ops_xxx ``` -To włączenie akceptuje tylko zaufane prywatne/wewnętrzne cele. Publiczne homeservery cleartext, takie jak +Ten wyjątek pozwala tylko na zaufane cele prywatne/wewnętrzne. Publiczne homeservery bez TLS, takie jak `http://matrix.example.org:8008`, nadal są blokowane. Gdy to możliwe, preferuj `https://`. -## Proxy dla ruchu Matrix +## Ruch Matrix przez proxy Jeśli twoje wdrożenie Matrix wymaga jawnego wychodzącego proxy HTTP(S), ustaw `channels.matrix.proxy`: @@ -1016,87 +1018,87 @@ Jeśli twoje wdrożenie Matrix wymaga jawnego wychodzącego proxy HTTP(S), ustaw } ``` -Nazwane konta mogą nadpisać domyślną wartość najwyższego poziomu za pomocą `channels.matrix.accounts..proxy`. -OpenClaw używa tego samego ustawienia proxy zarówno dla ruchu Matrix w runtime, jak i dla sond statusu konta. +Nazwane konta mogą nadpisać domyślną wartość najwyższego poziomu przez `channels.matrix.accounts..proxy`. +OpenClaw używa tego samego ustawienia proxy zarówno dla ruchu runtime Matrix, jak i sond stanu konta. -## Rozwiązywanie targetów +## Rozwiązywanie celów -Matrix akceptuje te formy targetów wszędzie tam, gdzie OpenClaw prosi o target pokoju lub użytkownika: +Matrix akceptuje następujące formy celu 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 katalogowe na żywo używa zalogowanego konta Matrix: +Wyszukiwanie katalogu na żywo używa zalogowanego konta Matrix: -- Wyszukiwania użytkowników odpytują katalog użytkowników Matrix na tym homeserverze. -- Wyszukiwania pokoi akceptują bezpośrednio 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 da się rozwiązać do ID lub aliasu, jest ignorowana przez rozwiązywanie allowlisty w runtime. +- Wyszukiwania użytkowników odpytyją katalog użytkowników Matrix na tym homeserverze. +- Wyszukiwania pokojów bezpośrednio akceptują jawne identyfikatory pokojów i aliasy, a następnie wracają do przeszukiwania nazw pokojów dołączonych dla tego konta. +- Wyszukiwanie nazw dołączonych pokojów jest realizowane najlepiej jak się da. Jeśli nazwy pokoju nie da się rozwiązać do identyfikatora ani aliasu, jest ignorowana przez runtime przy rozwiązywaniu listy dozwolonych. -## Configuration reference +## Dokumentacja konfiguracji - `enabled`: włącza lub wyłącza kanał. - `name`: opcjonalna etykieta konta. -- `defaultAccount`: preferowane ID konta, gdy skonfigurowano wiele kont Matrix. +- `defaultAccount`: preferowany identyfikator 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 IP LAN/Tailscale albo wewnętrznego hosta, takiego jak `matrix-synapse`. +- `network.dangerouslyAllowPrivateNetwork`: pozwala temu kontu Matrix łączyć się z prywatnymi/wewnętrznymi homeserverami. Włącz tę opcję, gdy homeserver rozwiązuje się do `localhost`, adresu LAN/Tailscale albo wewnętrznego hosta, takiego jak `matrix-synapse`. - `proxy`: opcjonalny URL proxy HTTP(S) dla ruchu Matrix. Nazwane konta mogą nadpisać domyślną wartość najwyższego poziomu własnym `proxy`. -- `userId`: pełne ID użytkownika Matrix, na przykład `@bot:example.org`. -- `accessToken`: access token dla uwierzytelniania opartego na tokenie. Obsługiwane są wartości plaintext i wartości SecretRef dla `channels.matrix.accessToken` oraz `channels.matrix.accounts..accessToken` w providerach env/file/exec. Zobacz [Secrets Management](/pl/gateway/secrets). -- `password`: hasło do logowania opartego na haśle. Obsługiwane są wartości plaintext i wartości SecretRef. -- `deviceId`: jawne ID urządzenia Matrix. -- `deviceName`: wyświetlana nazwa urządzenia dla logowania hasłem. -- `avatarUrl`: zapisany URL własnego avatara do synchronizacji profilu i aktualizacji `set-profile`. -- `initialSyncLimit`: limit zdarzeń synchronizacji przy uruchomieniu. +- `userId`: pełny identyfikator użytkownika Matrix, na przykład `@bot:example.org`. +- `accessToken`: token dostępu dla uwierzytelniania opartego na tokenie. Dla `channels.matrix.accessToken` i `channels.matrix.accounts..accessToken` obsługiwane są zarówno wartości jawne, jak i SecretRef, w dostawcach env/file/exec. Zobacz [Zarządzanie sekretami](/pl/gateway/secrets). +- `password`: hasło do logowania hasłem. Obsługiwane są zarówno wartości jawne, jak i SecretRef. +- `deviceId`: jawny identyfikator urządzenia Matrix. +- `deviceName`: wyświetlana nazwa urządzenia przy logowaniu hasłem. +- `avatarUrl`: zapisany URL własnego awatara do synchronizacji profilu i aktualizacji `set-profile`. +- `initialSyncLimit`: limit zdarzeń synchronizacji przy uruchamianiu. - `encryption`: włącza E2EE. -- `allowlistOnly`: wymusza zachowanie wyłącznie allowlisty dla DM-ów i pokoi. -- `allowBots`: zezwala na wiadomości z innych skonfigurowanych kont Matrix OpenClaw (`true` lub `"mentions"`). -- `groupPolicy`: `open`, `allowlist` lub `disabled`. +- `allowlistOnly`: wymusza zachowanie tylko według listy dozwolonych dla wiadomości prywatnych i pokojów. +- `allowBots`: pozwala na wiadomości od innych skonfigurowanych kont Matrix OpenClaw (`true` lub `"mentions"`). +- `groupPolicy`: `open`, `allowlist` albo `disabled`. - `contextVisibility`: tryb widoczności uzupełniającego kontekstu pokoju (`all`, `allowlist`, `allowlist_quote`). -- `groupAllowFrom`: allowlista ID użytkowników dla ruchu pokojowego. -- Wpisy `groupAllowFrom` powinny być pełnymi ID użytkowników Matrix. Nierozwiązane nazwy są ignorowane w runtime. -- `historyLimit`: maksymalna liczba wiadomości pokoju do dołączenia jako kontekst historii grupy. Wartość wraca do `messages.groupChat.historyLimit`; jeśli oba pola są nieustawione, efektywna wartość domyślna to `0`. Ustaw `0`, aby wyłączyć. -- `replyToMode`: `off`, `first`, `all` lub `batched`. +- `groupAllowFrom`: lista dozwolonych identyfikatorów użytkowników dla ruchu w pokojach. +- Wpisy `groupAllowFrom` powinny być pełnymi identyfikatorami użytkowników Matrix. Nierozwiązane nazwy są ignorowane w runtime. +- `historyLimit`: maksymalna liczba wiadomości z pokoju do dołączenia jako kontekst historii grupy. Wartość zapasowa pochodzi z `messages.groupChat.historyLimit`; jeśli obie wartości nie są ustawione, efektywna wartość domyślna to `0`. Ustaw `0`, aby wyłączyć. +- `replyToMode`: `off`, `first`, `all` albo `batched`. - `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 szkiców oparte na pierwszym podglądzie przy użyciu zwykłych wiadomości tekstowych Matrix. `quiet` używa niepowiadamiających komunikatów podglądu dla samohostowanych konfiguracji z regułami push. -- `blockStreaming`: `true` włącza osobne komunikaty postępu dla ukończonych bloków asystenta, gdy aktywny jest streaming podglądu szkicu. -- `threadReplies`: `off`, `inbound` lub `always`. -- `threadBindings`: nadpisania per kanał dla routowania i cyklu życia sesji powiązanych z wątkiem. -- `startupVerification`: tryb automatycznej prośby o samoweryfikację przy uruchomieniu (`if-unverified`, `off`). -- `startupVerificationCooldownHours`: cooldown przed ponowną próbą automatycznych próśb o weryfikację przy uruchomieniu. -- `textChunkLimit`: rozmiar chunków wiadomości wychodzących. +- `streaming`: `off` (domyślnie), `partial`, `quiet`, `true` lub `false`. `partial` i `true` włączają aktualizacje wersji roboczej „najpierw podgląd” przy użyciu zwykłych wiadomości tekstowych Matrix. `quiet` używa niepowiadamiających powiadomień podglądu dla samodzielnie hostowanych konfiguracji z regułami push. +- `blockStreaming`: `true` włącza osobne wiadomości postępu dla ukończonych bloków asystenta, gdy aktywny jest streaming wersji roboczej podglądu. +- `threadReplies`: `off`, `inbound` albo `always`. +- `threadBindings`: nadpisania per kanał dla routowania i cyklu życia sesji powiązanych z wątkami. +- `startupVerification`: tryb automatycznego żądania samoweryfikacji przy uruchamianiu (`if-unverified`, `off`). +- `startupVerificationCooldownHours`: czas karencji przed ponowieniem automatycznych żądań weryfikacji przy uruchamianiu. +- `textChunkLimit`: rozmiar fragmentu wiadomości wychodzącej. - `chunkMode`: `length` lub `newline`. - `responsePrefix`: opcjonalny prefiks wiadomości dla odpowiedzi wychodzących. - `ackReaction`: opcjonalne nadpisanie reakcji potwierdzającej dla tego kanału/konta. - `ackReactionScope`: opcjonalne nadpisanie zakresu reakcji potwierdzającej (`group-mentions`, `group-all`, `direct`, `all`, `none`, `off`). - `reactionNotifications`: tryb przychodzących powiadomień o reakcjach (`own`, `off`). -- `mediaMaxMb`: limit rozmiaru mediów w MB dla obsługi mediów Matrix. Dotyczy wysyłek wychodzących i przetwarzania mediów przychodzących. -- `autoJoin`: polityka automatycznego dołączania do zaproszeń (`always`, `allowlist`, `off`). Domyślnie: `off`. Dotyczy to ogólnie zaproszeń Matrix, w tym zaproszeń typu DM, a nie tylko zaproszeń do pokoi/grup. OpenClaw podejmuje tę decyzję w chwili zaproszenia, zanim może wiarygodnie sklasyfikować dołączony pokój jako DM albo grupę. -- `autoJoinAllowlist`: pokoje/aliasy dozwolone, gdy `autoJoin` ma wartość `allowlist`. Wpisy aliasów są rozwiązywane do ID pokoi podczas obsługi zaproszenia; OpenClaw nie ufa stanowi aliasu deklarowanemu przez zaproszony pokój. -- `dm`: blok polityki DM (`enabled`, `policy`, `allowFrom`, `sessionScope`, `threadReplies`). -- `dm.policy`: kontroluje dostęp do DM po dołączeniu OpenClaw do pokoju i sklasyfikowaniu go jako DM. Nie zmienia tego, czy zaproszenie zostanie automatycznie przyjęte. -- Wpisy `dm.allowFrom` 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`, jeśli chcesz, aby każdy pokój DM Matrix zachowywał osobny kontekst, nawet gdy 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 umieszczania odpowiedzi, jak i izolacji sesji w DM-ach. -- `execApprovals`: natywne dostarczanie zatwierdzeń exec w Matrix (`enabled`, `approvers`, `target`, `agentFilter`, `sessionFilter`). -- `execApprovals.approvers`: ID użytkowników Matrix, którzy mogą zatwierdzać prośby exec. Opcjonalne, gdy `dm.allowFrom` już identyfikuje zatwierdzających. +- `mediaMaxMb`: limit rozmiaru multimediów w MB dla obsługi multimediów Matrix. Dotyczy wysyłek wychodzących i przetwarzania multimediów przychodzących. +- `autoJoin`: polityka automatycznego dołączania do zaproszeń (`always`, `allowlist`, `off`). Domyślnie: `off`. Dotyczy ogólnie zaproszeń Matrix, w tym zaproszeń w stylu wiadomości prywatnej, a nie tylko zaproszeń do pokojów/grup. OpenClaw podejmuje tę decyzję w momencie zaproszenia, zanim może wiarygodnie sklasyfikować dołączony pokój jako wiadomość prywatną lub grupę. +- `autoJoinAllowlist`: pokoje/aliasy dozwolone, gdy `autoJoin` ma wartość `allowlist`. Wpisy aliasów są rozwiązywane do identyfikatorów pokojów podczas obsługi zaproszenia; OpenClaw nie ufa stanowi aliasu deklarowanemu przez zaproszony pokój. +- `dm`: blok polityki wiadomości prywatnych (`enabled`, `policy`, `allowFrom`, `sessionScope`, `threadReplies`). +- `dm.policy`: kontroluje dostęp do wiadomości prywatnych po tym, jak OpenClaw dołączył do pokoju i sklasyfikował go jako wiadomość prywatną. Nie zmienia tego, czy do zaproszenia nastąpi automatyczne dołączenie. +- Wpisy `dm.allowFrom` powinny być pełnymi identyfikatorami użytkowników Matrix, chyba że zostały już rozwiązane przez wyszukiwanie katalogu na żywo. +- `dm.sessionScope`: `per-user` (domyślnie) albo `per-room`. Użyj `per-room`, jeśli chcesz, aby każdy pokój wiadomości prywatnych Matrix zachowywał osobny kontekst, nawet jeśli partner jest ten sam. +- `dm.threadReplies`: nadpisanie polityki wątków tylko dla wiadomości prywatnych (`off`, `inbound`, `always`). Nadpisuje najwyższego poziomu ustawienie `threadReplies` zarówno dla umieszczania odpowiedzi, jak i izolacji sesji w wiadomościach prywatnych. +- `execApprovals`: natywne dostarczanie zatwierdzeń exec przez Matrix (`enabled`, `approvers`, `target`, `agentFilter`, `sessionFilter`). +- `execApprovals.approvers`: identyfikatory użytkowników Matrix uprawnionych do zatwierdzania żądań exec. Opcjonalne, gdy `dm.allowFrom` już identyfikuje zatwierdzających. - `execApprovals.target`: `dm | channel | both` (domyślnie: `dm`). -- `accounts`: nazwane nadpisania per konto. Wartości najwyższego poziomu `channels.matrix` działają jako domyślne dla tych wpisów. -- `groups`: mapa polityk per pokój. Preferuj ID pokoi lub aliasy; nierozwiązane nazwy pokoi są ignorowane w runtime. Tożsamość sesji/grupy po rozwiązywaniu używa stabilnego ID pokoju, podczas gdy etykiety czytelne dla człowieka nadal pochodzą z nazw pokoi. -- `groups..account`: ogranicza jeden dziedziczony wpis pokoju do konkretnego konta Matrix w konfiguracjach wielokontowych. +- `accounts`: nazwane nadpisania per konto. Wartości najwyższego poziomu `channels.matrix` działają jako wartości domyślne dla tych wpisów. +- `groups`: mapa zasad per pokój. Preferuj identyfikatory pokojów lub aliasy; nierozwiązane nazwy pokojów są ignorowane w runtime. Tożsamość sesji/grupy po rozwiązaniu używa stabilnego identyfikatora pokoju, podczas gdy etykiety czytelne dla ludzi nadal pochodzą z nazw pokojów. +- `groups..account`: ogranicza jeden odziedziczony wpis pokoju do konkretnego konta Matrix w konfiguracjach z wieloma kontami. - `groups..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 dozwalania/odmawiania narzędzi per pokój. -- `groups..autoReply`: nadpisanie bramkowania wzmiankami na poziomie pokoju. `true` wyłącza wymagania wzmianki dla tego pokoju; `false` wymusza je ponownie. +- `groups..users`: lista dozwolonych nadawców dla pokoju. +- `groups..tools`: nadpisania dozwolenia/odmowy narzędzi dla pokoju. +- `groups..autoReply`: nadpisanie wymuszania wzmianki na poziomie pokoju. `true` wyłącza wymaganie wzmianki dla tego pokoju; `false` wymusza je ponownie. - `groups..skills`: opcjonalny filtr Skills na poziomie pokoju. -- `groups..systemPrompt`: opcjonalny fragment system promptu na poziomie pokoju. +- `groups..systemPrompt`: opcjonalny fragment promptu systemowego na poziomie pokoju. - `rooms`: starszy alias dla `groups`. -- `actions`: bramkowanie narzędzi per akcja (`messages`, `reactions`, `pins`, `profile`, `memberInfo`, `channelInfo`, `verification`). +- `actions`: kontrola narzędzi per działanie (`messages`, `reactions`, `pins`, `profile`, `memberInfo`, `channelInfo`, `verification`). ## Powiązane -- [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 hardening +- [Przegląd kanałów](/pl/channels) — wszystkie obsługiwane kanały +- [Parowanie](/pl/channels/pairing) — uwierzytelnianie wiadomości prywatnych i przepływ parowania +- [Grupy](/pl/channels/groups) — zachowanie czatu grupowego i wymuszanie wzmianki +- [Routowanie kanałów](/pl/channels/channel-routing) — routowanie sesji dla wiadomości +- [Bezpieczeństwo](/pl/gateway/security) — model dostępu i utwardzanie diff --git a/docs/pl/concepts/compaction.md b/docs/pl/concepts/compaction.md index 1ac77b3b7..ed5cf9374 100644 --- a/docs/pl/concepts/compaction.md +++ b/docs/pl/concepts/compaction.md @@ -1,19 +1,19 @@ --- read_when: - - Chcesz zrozumieć automatyczne kompaktowanie i /compact + - Chcesz zrozumieć automatyczną kompakcję i /compact - Debugujesz długie sesje osiągające limity kontekstu -summary: Jak OpenClaw podsumowuje długie rozmowy, aby zmieścić się w limitach modelu -title: Kompaktowanie +summary: Jak OpenClaw streszcza długie rozmowy, aby mieścić się w limitach modelu +title: Kompakcja x-i18n: - generated_at: "2026-04-05T13:50:10Z" + generated_at: "2026-04-08T02:14:29Z" model: gpt-5.4 provider: openai - source_hash: 4c6dbd6ebdcd5f918805aafdc153925efef3e130faa3fab3c630832e938219fc + source_hash: e6590b82a8c3a9c310998d653459ca4d8612495703ca0a8d8d306d7643142fd1 source_path: concepts/compaction.md workflow: 15 --- -# Kompaktowanie +# Kompakcja Każdy model ma okno kontekstu — maksymalną liczbę tokenów, które może przetworzyć. Gdy rozmowa zbliża się do tego limitu, OpenClaw **kompaktuje** starsze wiadomości @@ -21,23 +21,23 @@ do postaci podsumowania, aby czat mógł być kontynuowany. ## Jak to działa -1. Starsze tury rozmowy są podsumowywane do zwartego wpisu. +1. Starsze tury rozmowy są streszczane do zwartego wpisu. 2. Podsumowanie jest zapisywane w transkrypcie sesji. 3. Ostatnie wiadomości pozostają nienaruszone. -Gdy OpenClaw dzieli historię na fragmenty do kompaktowania, utrzymuje wywołania -narzędzi asystenta sparowane z odpowiadającymi im wpisami `toolResult`. Jeśli punkt podziału -wypada wewnątrz bloku narzędzia, OpenClaw przesuwa granicę tak, aby para pozostała razem, a -bieżący niepodsumowany ogon został zachowany. +Gdy OpenClaw dzieli historię na fragmenty do kompaktowania, zachowuje wywołania +narzędzi asystenta sparowane z odpowiadającymi im wpisami `toolResult`. Jeśli punkt +podziału wypada wewnątrz bloku narzędzia, OpenClaw przesuwa granicę tak, aby para +pozostała razem, a bieżący niepodsumowany ogon został zachowany. -Pełna historia rozmowy pozostaje na dysku. Kompaktowanie zmienia tylko to, -co model widzi w następnej turze. +Pełna historia rozmowy pozostaje na dysku. Kompakcja zmienia tylko to, co model +widzi w następnej turze. -## Automatyczne kompaktowanie +## Automatyczna kompakcja -Automatyczne kompaktowanie jest domyślnie włączone. Uruchamia się, gdy sesja zbliża się do limitu -kontekstu albo gdy model zwróci błąd przepełnienia kontekstu (w takim przypadku -OpenClaw kompaktuje i ponawia próbę). Typowe sygnatury przepełnienia obejmują +Automatyczna kompakcja jest domyślnie włączona. Uruchamia się, gdy sesja zbliża się do limitu +kontekstu albo gdy model zwraca błąd przepełnienia kontekstu (w takim przypadku +OpenClaw wykonuje kompakcję i ponawia próbę). Typowe sygnatury przepełnienia to `request_too_large`, `context length exceeded`, `input exceeds the maximum number of tokens`, `input token count exceeds the maximum number of input tokens`, `input is too long for the model` oraz `ollama error: context length @@ -45,21 +45,86 @@ exceeded`. Przed kompaktowaniem OpenClaw automatycznie przypomina agentowi o zapisaniu ważnych -notatek do plików [memory](/concepts/memory). Zapobiega to utracie kontekstu. +notatek do plików [memory](/pl/concepts/memory). Zapobiega to utracie kontekstu. -## Ręczne kompaktowanie +Użyj ustawienia `agents.defaults.compaction` w pliku `openclaw.json`, aby skonfigurować zachowanie kompaktowania (tryb, docelową liczbę tokenów itd.). +Streszczanie podczas kompaktowania domyślnie zachowuje nieprzezroczyste identyfikatory (`identifierPolicy: "strict"`). Możesz to zmienić za pomocą `identifierPolicy: "off"` albo podać własny tekst przy użyciu `identifierPolicy: "custom"` i `identifierInstructions`. -Wpisz `/compact` w dowolnym czacie, aby wymusić kompaktowanie. Dodaj instrukcje, -aby ukierunkować podsumowanie: +Opcjonalnie możesz określić inny model do streszczania podczas kompaktowania za pomocą `agents.defaults.compaction.model`. Jest to przydatne, gdy podstawowy model jest lokalny lub mały, a chcesz, aby podsumowania kompaktowania były tworzone przez bardziej zaawansowany model. To ustawienie przyjmuje dowolny ciąg `provider/model-id`: + +```json +{ + "agents": { + "defaults": { + "compaction": { + "model": "openrouter/anthropic/claude-sonnet-4-6" + } + } + } +} +``` + +Działa to również z modelami lokalnymi, na przykład z drugim modelem Ollama przeznaczonym do streszczania albo specjalistycznym modelem dostrojonym do kompaktowania: + +```json +{ + "agents": { + "defaults": { + "compaction": { + "model": "ollama/llama3.1:8b" + } + } + } +} +``` + +Jeśli nie jest ustawione, kompaktowanie używa podstawowego modelu agenta. + +## Wtyczkowi dostawcy kompaktowania + +Plugins mogą rejestrować niestandardowego dostawcę kompaktowania za pomocą `registerCompactionProvider()` w API pluginu. Gdy dostawca jest zarejestrowany i skonfigurowany, OpenClaw deleguje streszczanie do niego zamiast do wbudowanego potoku LLM. + +Aby użyć zarejestrowanego dostawcy, ustaw identyfikator dostawcy w konfiguracji: + +```json +{ + "agents": { + "defaults": { + "compaction": { + "provider": "my-provider" + } + } + } +} +``` + +Ustawienie `provider` automatycznie wymusza `mode: "safeguard"`. Dostawcy otrzymują te same instrukcje kompaktowania i tę samą politykę zachowywania identyfikatorów co ścieżka wbudowana, a OpenClaw nadal zachowuje kontekst sufiksu ostatnich tur i podzielonych tur po wyniku dostawcy. Jeśli dostawca zakończy się niepowodzeniem albo zwróci pusty wynik, OpenClaw wraca do wbudowanego streszczania przez LLM. + +## Automatyczna kompakcja (domyślnie włączona) + +Gdy sesja zbliża się do okna kontekstu modelu lub je przekracza, OpenClaw uruchamia automatyczną kompakcję i może ponowić pierwotne żądanie, używając skompaktowanego kontekstu. + +Zobaczysz: + +- `🧹 Auto-compaction complete` w trybie verbose +- `/status` pokazujące `🧹 Compactions: ` + +Przed kompaktowaniem OpenClaw może uruchomić **ciche opróżnienie pamięci** tury, aby zapisać +trwałe notatki na dysk. Szczegóły i konfigurację znajdziesz w sekcji [Memory](/pl/concepts/memory). + +## Ręczna kompakcja + +Wpisz `/compact` w dowolnym czacie, aby wymusić kompakcję. Dodaj instrukcje, aby ukierunkować +podsumowanie: ``` -/compact Skup się na decyzjach projektowych dotyczących API +/compact Focus on the API design decisions ``` ## Używanie innego modelu -Domyślnie kompaktowanie używa głównego modelu agenta. Możesz użyć bardziej +Domyślnie kompaktowanie używa podstawowego modelu agenta. Możesz użyć bardziej zaawansowanego modelu, aby uzyskać lepsze podsumowania: ```json5 @@ -91,39 +156,39 @@ się rozpoczyna, włącz `notifyUser`: } ``` -Po włączeniu użytkownik widzi krótki komunikat (na przykład „Kompaktowanie +Po włączeniu użytkownik zobaczy krótki komunikat (na przykład „Kompaktowanie kontekstu...”) na początku każdego uruchomienia kompaktowania. -## Kompaktowanie a przycinanie +## Kompakcja a przycinanie -| | Kompaktowanie | Przycinanie | +| | Kompakcja | Przycinanie | | ---------------- | ----------------------------- | -------------------------------- | -| **Co robi** | Podsumowuje starszą rozmowę | Przycina stare wyniki narzędzi | +| **Co robi** | Streszcza starszą rozmowę | Przycina stare wyniki narzędzi | | **Zapisywane?** | Tak (w transkrypcie sesji) | Nie (tylko w pamięci, na żądanie) | | **Zakres** | Cała rozmowa | Tylko wyniki narzędzi | -[Przycinanie sesji](/concepts/session-pruning) to lżejsze uzupełnienie, które -przycina dane wyjściowe narzędzi bez tworzenia podsumowania. +[Przycinanie sesji](/pl/concepts/session-pruning) to lżejsze uzupełnienie, które +przycina dane wyjściowe narzędzi bez streszczania. ## Rozwiązywanie problemów -**Kompaktowanie uruchamia się zbyt często?** Okno kontekstu modelu może być małe albo -dane wyjściowe narzędzi mogą być duże. Spróbuj włączyć -[przycinanie sesji](/concepts/session-pruning). +**Kompaktowanie występuje zbyt często?** Okno kontekstu modelu może być małe albo wyniki +narzędzi mogą być duże. Spróbuj włączyć +[przycinanie sesji](/pl/concepts/session-pruning). -**Czy po kompaktowaniu kontekst wydaje się nieaktualny?** Użyj `/compact Skup się na `, aby -ukierunkować podsumowanie, albo włącz [opróżnianie memory](/concepts/memory), aby notatki +**Czy po kompaktowaniu kontekst wydaje się nieaktualny?** Użyj `/compact Focus on `, aby +ukierunkować podsumowanie, albo włącz [opróżnianie pamięci](/pl/concepts/memory), aby notatki zostały zachowane. **Potrzebujesz czystego startu?** `/new` rozpoczyna nową sesję bez kompaktowania. -Zaawansowaną konfigurację (rezerwowe tokeny, zachowanie identyfikatorów, niestandardowe -silniki kontekstu, kompaktowanie po stronie serwera OpenAI) opisano w -[Dogłębne omówienie zarządzania sesją](/reference/session-management-compaction). +Zaawansowaną konfigurację (rezerwę tokenów, zachowywanie identyfikatorów, niestandardowe +silniki kontekstu, kompaktowanie po stronie serwera OpenAI) znajdziesz w +[szczegółowym omówieniu zarządzania sesją](/pl/reference/session-management-compaction). ## Powiązane -- [Session](/concepts/session) — zarządzanie sesją i jej cykl życia -- [Session Pruning](/concepts/session-pruning) — przycinanie wyników narzędzi -- [Context](/concepts/context) — jak budowany jest kontekst dla tur agenta +- [Session](/pl/concepts/session) — zarządzanie sesją i jej cykl życia +- [Session Pruning](/pl/concepts/session-pruning) — przycinanie wyników narzędzi +- [Context](/pl/concepts/context) — jak budowany jest kontekst dla tur agenta - [Hooks](/pl/automation/hooks) — hooki cyklu życia kompaktowania (before_compaction, after_compaction) diff --git a/docs/pl/concepts/qa-e2e-automation.md b/docs/pl/concepts/qa-e2e-automation.md index ffba7675c..47985aba2 100644 --- a/docs/pl/concepts/qa-e2e-automation.md +++ b/docs/pl/concepts/qa-e2e-automation.md @@ -1,50 +1,51 @@ --- read_when: - - Rozszerzasz qa-lab lub qa-channel - - Dodajesz scenariusze QA oparte na repozytorium - - Budujesz automatyzację QA o większym realizmie wokół dashboardu Gateway -summary: Kształt prywatnej automatyzacji QA dla qa-lab, qa-channel, scenariuszy seed i raportów protokołu + - Rozszerzanie qa-lab lub qa-channel + - Dodawanie scenariuszy QA wspieranych przez repozytorium + - Tworzenie bardziej realistycznej automatyzacji QA wokół panelu Gateway +summary: Prywatna struktura automatyzacji QA dla qa-lab, qa-channel, scenariuszy seed i raportów protokołu title: Automatyzacja QA E2E x-i18n: - generated_at: "2026-04-07T09:44:13Z" + generated_at: "2026-04-08T02:14:14Z" model: gpt-5.4 provider: openai - source_hash: b68cfcfb50532dbda93ba62e1ed8dc6a7ddd4214cb1db8c9a84a7bc0b32b3060 + source_hash: 3b4aa5acc8e77303f4045d4f04372494cae21b89d2fdaba856dbb4855ced9d27 source_path: concepts/qa-e2e-automation.md workflow: 15 --- # Automatyzacja QA E2E -Prywatny stos QA ma testować OpenClaw w bardziej realistyczny, -kanałowy sposób niż pojedynczy test jednostkowy. +Prywatny stos QA ma na celu testowanie OpenClaw w bardziej realistyczny, +kanałowy sposób niż może to zrobić pojedynczy test jednostkowy. Obecne elementy: - `extensions/qa-channel`: syntetyczny kanał wiadomości z powierzchniami DM, kanału, wątku, reakcji, edycji i usuwania. -- `extensions/qa-lab`: interfejs debugowania i magistrala QA do obserwacji transkryptu, +- `extensions/qa-lab`: interfejs debuggera i magistrala QA do obserwowania transkryptu, wstrzykiwania wiadomości przychodzących i eksportowania raportu Markdown. -- `qa/`: zasoby seed oparte na repozytorium dla zadania startowego i bazowych scenariuszy QA. +- `qa/`: zasoby seed wspierane przez repozytorium dla zadania startowego i bazowych + scenariuszy QA. Obecny przepływ pracy operatora QA to dwupanelowa witryna QA: -- Po lewej: dashboard Gateway (Control UI) z agentem. -- Po prawej: QA Lab, pokazujący transkrypt w stylu Slack i plan scenariusza. +- Po lewej: panel Gateway (Control UI) z agentem. +- Po prawej: QA Lab, pokazujący transkrypt w stylu Slacka i plan scenariusza. -Uruchom ją poleceniem: +Uruchom za pomocą: ```bash pnpm qa:lab:up ``` -To buduje witrynę QA, uruchamia obsługiwaną przez Docker ścieżkę gateway i udostępnia -stronę QA Lab, na której operator lub pętla automatyzacji może dać agentowi misję -QA, obserwować rzeczywiste zachowanie kanału oraz rejestrować, co działało, co się nie powiodło -i co pozostało zablokowane. +To buduje witrynę QA, uruchamia ścieżkę Gateway opartą na Dockerze i udostępnia +stronę QA Lab, na której operator lub pętla automatyzacji może przekazać agentowi +misję QA, obserwować rzeczywiste zachowanie kanału oraz rejestrować, co zadziałało, +co się nie powiodło i co pozostało zablokowane. -Aby szybciej iterować nad interfejsem QA Lab bez przebudowywania obrazu Dockera za każdym razem, -uruchom stos z bind-mountowanym bundle QA Lab: +Aby szybciej iterować nad interfejsem QA Lab bez każdorazowego przebudowywania obrazu Docker, +uruchom stos z pakietem QA Lab montowanym przez bind mount: ```bash pnpm openclaw qa docker-build-image @@ -53,36 +54,35 @@ pnpm qa:lab:up:fast pnpm qa:lab:watch ``` -`qa:lab:up:fast` utrzymuje usługi Dockera na wcześniej zbudowanym obrazie i bind-mountuje +`qa:lab:up:fast` utrzymuje usługi Dockera na wstępnie zbudowanym obrazie i montuje przez bind mount `extensions/qa-lab/web/dist` do kontenera `qa-lab`. `qa:lab:watch` -przebudowuje ten bundle po zmianach, a przeglądarka automatycznie się przeładowuje, gdy hash zasobów QA Lab się zmieni. +przebudowuje ten pakiet przy zmianach, a przeglądarka automatycznie przeładowuje się, gdy hash zasobu QA Lab się zmienia. -## Seedy oparte na repozytorium +## Seedy wspierane przez repozytorium Zasoby seed znajdują się w `qa/`: -- `qa/QA_KICKOFF_TASK.md` -- `qa/seed-scenarios.json` +- `qa/scenarios.md` -Celowo znajdują się one w git, aby plan QA był widoczny zarówno dla ludzi, jak i dla -agenta. Lista bazowa powinna pozostać wystarczająco szeroka, aby obejmować: +Są one celowo przechowywane w git, aby plan QA był widoczny zarówno dla ludzi, jak i dla +agenta. Lista bazowa powinna pozostać na tyle szeroka, aby obejmować: -- czat DM i kanałowy +- rozmowy DM i kanałowe - zachowanie wątków -- cykl życia akcji na wiadomościach -- wywołania zwrotne cron +- cykl życia działań na wiadomościach +- wywołania cron - przywoływanie pamięci - przełączanie modeli - przekazanie do subagenta -- odczyt repozytorium i dokumentacji +- czytanie repozytorium i dokumentacji - jedno małe zadanie build, takie jak Lobster Invaders ## Raportowanie -`qa-lab` eksportuje raport protokołu Markdown na podstawie obserwowanej osi czasu magistrali. +`qa-lab` eksportuje raport protokołu w Markdown na podstawie obserwowanej osi czasu magistrali. Raport powinien odpowiadać na pytania: -- Co działało +- Co zadziałało - Co się nie powiodło - Co pozostało zablokowane - Jakie scenariusze uzupełniające warto dodać @@ -90,5 +90,5 @@ Raport powinien odpowiadać na pytania: ## Powiązana dokumentacja - [Testowanie](/pl/help/testing) -- [QA Channel](/pl/channels/qa-channel) -- [Dashboard](/web/dashboard) +- [Kanał QA](/pl/channels/qa-channel) +- [Panel](/web/dashboard) diff --git a/docs/pl/concepts/system-prompt.md b/docs/pl/concepts/system-prompt.md index 336e9a44f..430478c2a 100644 --- a/docs/pl/concepts/system-prompt.md +++ b/docs/pl/concepts/system-prompt.md @@ -1,102 +1,99 @@ --- read_when: - - Edytujesz tekst promptu systemowego, listę narzędzi albo sekcje czasu/heartbeat - - Zmieniasz zachowanie bootstrapu workspace lub wstrzykiwania Skills + - Edytowanie tekstu promptu systemowego, listy narzędzi lub sekcji czasu/heartbeatów + - Zmiana zachowania bootstrapu workspace lub wstrzykiwania Skills summary: Co zawiera prompt systemowy OpenClaw i jak jest składany title: Prompt systemowy x-i18n: - generated_at: "2026-04-05T13:52:10Z" + generated_at: "2026-04-08T02:14:35Z" model: gpt-5.4 provider: openai - source_hash: f14ba7f16dda81ac973d72be05931fa246bdfa0e1068df1a84d040ebd551c236 + source_hash: e55fc886bc8ec47584d07c9e60dfacd964dc69c7db976ea373877dc4fe09a79a source_path: concepts/system-prompt.md workflow: 15 --- # Prompt systemowy -OpenClaw buduje niestandardowy prompt systemowy dla każdego uruchomienia agenta. Prompt jest **własnością OpenClaw** i nie używa domyślnego promptu pi-coding-agent. +OpenClaw tworzy niestandardowy prompt systemowy dla każdego uruchomienia agenta. Prompt jest **własnością OpenClaw** i nie używa domyślnego promptu pi-coding-agent. Prompt jest składany przez OpenClaw i wstrzykiwany do każdego uruchomienia agenta. -Provider plugins mogą dodawać świadome pamięci podręcznej wskazówki do promptu bez zastępowania -pełnego promptu należącego do OpenClaw. Runtime dostawcy może: +Wtyczki dostawców mogą dodawać wskazówki do promptu uwzględniające pamięć podręczną bez zastępowania pełnego promptu należącego do OpenClaw. Środowisko wykonawcze dostawcy może: -- zastąpić mały zestaw nazwanych sekcji rdzeniowych (`interaction_style`, +- zastąpić mały zestaw nazwanych sekcji rdzenia (`interaction_style`, `tool_call_style`, `execution_bias`) - wstrzyknąć **stabilny prefiks** powyżej granicy pamięci podręcznej promptu - wstrzyknąć **dynamiczny sufiks** poniżej granicy pamięci podręcznej promptu -Używaj wkładów należących do dostawcy do dostrajania specyficznego dla rodziny modeli. Zachowaj starszą -mutację promptu `before_prompt_build` dla zgodności albo dla naprawdę globalnych zmian promptu, a nie dla zwykłego zachowania dostawcy. +Używaj wkładów należących do dostawcy do strojenia specyficznego dla rodziny modeli. Zachowaj starszą mutację promptu `before_prompt_build` dla zgodności lub naprawdę globalnych zmian promptu, a nie dla typowego zachowania dostawcy. ## Struktura Prompt jest celowo zwięzły i używa stałych sekcji: -- **Tooling**: przypomnienie o źródle prawdy dla narzędzi strukturalnych oraz wskazówki runtime dotyczące użycia narzędzi. -- **Safety**: krótkie przypomnienie o zasadach bezpieczeństwa, aby unikać zachowań nastawionych na zdobywanie władzy lub omijanie nadzoru. -- **Skills** (gdy dostępne): mówi modelowi, jak w razie potrzeby ładować instrukcje umiejętności. -- **OpenClaw Self-Update**: jak bezpiecznie sprawdzać konfigurację za pomocą - `config.schema.lookup`, poprawiać konfigurację przez `config.patch`, zastępować pełną - konfigurację przez `config.apply` oraz uruchamiać `update.run` tylko na wyraźne żądanie użytkownika. Narzędzie `gateway`, dostępne wyłącznie dla właściciela, również odmawia przepisywania +- **Narzędzia**: przypomnienie o źródle prawdy dla narzędzi strukturalnych oraz wskazówki środowiska wykonawczego dotyczące użycia narzędzi. +- **Bezpieczeństwo**: krótkie przypomnienie o zabezpieczeniach, aby unikać zachowań dążących do przejęcia kontroli lub obchodzenia nadzoru. +- **Skills** (gdy są dostępne): informuje model, jak na żądanie wczytywać instrukcje skillów. +- **Samoaktualizacja OpenClaw**: jak bezpiecznie sprawdzać konfigurację za pomocą + `config.schema.lookup`, poprawiać konfigurację za pomocą `config.patch`, zastępować pełną + konfigurację za pomocą `config.apply` oraz uruchamiać `update.run` tylko na wyraźną prośbę użytkownika. Narzędzie `gateway`, dostępne tylko dla właściciela, również odmawia przepisywania `tools.exec.ask` / `tools.exec.security`, w tym starszych aliasów `tools.bash.*`, - które normalizują się do tych chronionych ścieżek exec. + które są normalizowane do tych chronionych ścieżek exec. - **Workspace**: katalog roboczy (`agents.defaults.workspace`). -- **Documentation**: lokalna ścieżka do dokumentacji OpenClaw (repozytorium lub pakiet npm) oraz kiedy ją czytać. -- **Workspace Files (injected)**: wskazuje, że pliki bootstrap są dołączone poniżej. -- **Sandbox** (gdy włączony): wskazuje środowisko sandbox, ścieżki sandboxu i to, czy dostępny jest exec z podwyższonymi uprawnieniami. -- **Current Date & Time**: lokalny czas użytkownika, strefa czasowa i format czasu. -- **Reply Tags**: opcjonalna składnia tagów odpowiedzi dla obsługiwanych dostawców. -- **Heartbeats**: prompt heartbeat i zachowanie potwierdzeń. -- **Runtime**: host, system operacyjny, node, model, katalog główny repozytorium (gdy wykryty), poziom myślenia (jedna linia). -- **Reasoning**: bieżący poziom widoczności + wskazówka dotycząca przełączania /reasoning. +- **Dokumentacja**: lokalna ścieżka do dokumentacji OpenClaw (repozytorium lub pakiet npm) oraz informacja, kiedy ją czytać. +- **Pliki workspace (wstrzyknięte)**: wskazuje, że pliki bootstrap są dołączone poniżej. +- **Sandbox** (gdy włączony): wskazuje środowisko uruchomieniowe sandbox, ścieżki sandboxa oraz to, czy podwyższone exec jest dostępne. +- **Bieżąca data i godzina**: lokalny czas użytkownika, strefa czasowa i format czasu. +- **Tagi odpowiedzi**: opcjonalna składnia tagów odpowiedzi dla obsługiwanych dostawców. +- **Heartbeaty**: prompt heartbeatów i zachowanie potwierdzeń, gdy heartbeaty są włączone dla domyślnego agenta. +- **Środowisko wykonawcze**: host, system operacyjny, node, katalog główny repozytorium (gdy wykryty), poziom myślenia (jedna linia). +- **Rozumowanie**: bieżący poziom widoczności + podpowiedź przełączania `/reasoning`. -Sekcja Tooling zawiera również wskazówki runtime dotyczące długotrwałej pracy: +Sekcja Narzędzia zawiera również wskazówki środowiska wykonawczego dla długotrwałej pracy: - używaj cron do przyszłych działań następczych (`check back later`, przypomnienia, praca cykliczna) - zamiast pętli `exec` ze `sleep`, sztuczek opóźnienia `yieldMs` lub wielokrotnego odpytywania `process` + zamiast pętli uśpienia `exec`, sztuczek opóźniania `yieldMs` lub powtarzanego odpytywania `process` - używaj `exec` / `process` tylko dla poleceń, które uruchamiają się teraz i dalej działają w tle -- gdy włączone jest automatyczne budzenie po zakończeniu, uruchom polecenie raz i polegaj na - ścieżce budzenia opartej na push, gdy wygeneruje dane wyjściowe lub zakończy się błędem -- używaj `process` do logów, stanu, danych wejściowych lub interwencji, gdy musisz +- gdy włączone jest automatyczne wybudzanie po zakończeniu, uruchom polecenie tylko raz i polegaj na + ścieżce wybudzania opartej na push, gdy zwróci dane wyjściowe lub zakończy się błędem +- używaj `process` do logów, statusu, wejścia lub interwencji, gdy musisz sprawdzić działające polecenie -- jeśli zadanie jest większe, preferuj `sessions_spawn`; zakończenie sub-agenta działa - w trybie push i automatycznie ogłasza się z powrotem do zlecającego -- nie odpytuj w pętli `subagents list` / `sessions_list` tylko po to, by czekać na +- jeśli zadanie jest większe, preferuj `sessions_spawn`; zakończenie podagenta działa + w trybie push i jest automatycznie ogłaszane z powrotem do zgłaszającego +- nie odpytywać `subagents list` / `sessions_list` w pętli tylko po to, aby czekać na zakończenie -Gdy eksperymentalne narzędzie `update_plan` jest włączone, Tooling mówi też modelowi, -aby używał go tylko do nietrywialnej wieloetapowej pracy, utrzymywał dokładnie jeden krok +Gdy eksperymentalne narzędzie `update_plan` jest włączone, sekcja Narzędzia mówi też modelowi, +aby używał go tylko do nietrywialnej pracy wieloetapowej, utrzymywał dokładnie jeden krok `in_progress` i unikał powtarzania całego planu po każdej aktualizacji. -Zasady bezpieczeństwa w promptcie systemowym mają charakter doradczy. Kierują zachowaniem modelu, ale nie wymuszają polityki. Do twardego egzekwowania używaj polityki narzędzi, zatwierdzeń exec, sandboxingu i list dozwolonych kanałów; operatorzy mogą je celowo wyłączyć. +Zabezpieczenia w promptcie systemowym mają charakter doradczy. Kierują zachowaniem modelu, ale nie wymuszają zasad. Do twardego egzekwowania używaj polityki narzędzi, zgód exec, sandboxingu i list dozwolonych kanałów; operatorzy mogą je celowo wyłączyć. -Na kanałach z natywnymi kartami/przyciskami zatwierdzania prompt runtime informuje teraz -agenta, aby najpierw polegał na tym natywnym interfejsie zatwierdzania. Powinien dołączać ręczne -polecenie `/approve` tylko wtedy, gdy wynik narzędzia mówi, że zatwierdzanie na czacie jest niedostępne lub -jedyną ścieżką jest ręczne zatwierdzenie. +W kanałach z natywnymi kartami/przyciskami zatwierdzania prompt środowiska wykonawczego informuje teraz +agenta, aby najpierw polegał na tym natywnym interfejsie zatwierdzania. Powinien dołączać ręczne polecenie +`/approve` tylko wtedy, gdy wynik narzędzia mówi, że zatwierdzenia na czacie są niedostępne lub +ręczne zatwierdzenie jest jedyną drogą. ## Tryby promptu -OpenClaw może renderować mniejsze prompty systemowe dla sub-agentów. Runtime ustawia +OpenClaw może renderować mniejsze prompty systemowe dla podagentów. Środowisko wykonawcze ustawia `promptMode` dla każdego uruchomienia (nie jest to konfiguracja widoczna dla użytkownika): - `full` (domyślnie): zawiera wszystkie powyższe sekcje. -- `minimal`: używany dla sub-agentów; pomija **Skills**, **Memory Recall**, **OpenClaw - Self-Update**, **Model Aliases**, **User Identity**, **Reply Tags**, - **Messaging**, **Silent Replies** i **Heartbeats**. Tooling, **Safety**, - Workspace, Sandbox, Current Date & Time (gdy znane), Runtime oraz wstrzyknięty +- `minimal`: używany dla podagentów; pomija **Skills**, **Przywoływanie pamięci**, **Samoaktualizację OpenClaw**, **Aliasy modeli**, **Tożsamość użytkownika**, **Tagi odpowiedzi**, + **Wiadomości**, **Ciche odpowiedzi** i **Heartbeaty**. Narzędzia, **Bezpieczeństwo**, + Workspace, Sandbox, Bieżąca data i godzina (gdy znane), Środowisko wykonawcze oraz wstrzyknięty kontekst pozostają dostępne. - `none`: zwraca tylko podstawową linię tożsamości. -Gdy `promptMode=minimal`, dodatkowe wstrzyknięte prompty są oznaczane jako **Subagent -Context** zamiast **Group Chat Context**. +Gdy `promptMode=minimal`, dodatkowe wstrzyknięte prompty są oznaczane jako **Kontekst podagenta** +zamiast **Kontekst czatu grupowego**. ## Wstrzykiwanie bootstrapu workspace -Pliki bootstrap są przycinane i dołączane w sekcji **Project Context**, aby model widział kontekst tożsamości i profilu bez potrzeby jawnego odczytu: +Pliki bootstrap są przycinane i dołączane w sekcji **Kontekst projektu**, aby model widział kontekst tożsamości i profilu bez potrzeby jawnego odczytu: - `AGENTS.md` - `SOUL.md` @@ -104,63 +101,66 @@ Pliki bootstrap są przycinane i dołączane w sekcji **Project Context**, aby m - `IDENTITY.md` - `USER.md` - `HEARTBEAT.md` -- `BOOTSTRAP.md` (tylko w zupełnie nowych workspace) -- `MEMORY.md`, gdy istnieje, w przeciwnym razie `memory.md` jako zapasowa wersja małymi literami +- `BOOTSTRAP.md` (tylko w całkowicie nowych workspace'ach) +- `MEMORY.md`, jeśli istnieje, w przeciwnym razie `memory.md` jako rezerwowy wariant pisany małymi literami -Wszystkie te pliki są **wstrzykiwane do okna kontekstu** przy każdej turze, co -oznacza, że zużywają tokeny. Zachowuj je w zwięzłej formie — szczególnie `MEMORY.md`, który może -rosnąć z czasem i prowadzić do nieoczekiwanie wysokiego użycia kontekstu oraz częstszego -kompaktowania. +Wszystkie te pliki są **wstrzykiwane do okna kontekstu** przy każdym kroku, chyba że obowiązuje +bramka specyficzna dla pliku. `HEARTBEAT.md` jest pomijany przy normalnych uruchomieniach, gdy +heartbeaty są wyłączone dla domyślnego agenta lub +`agents.defaults.heartbeat.includeSystemPromptSection` ma wartość false. Zachowaj zwięzłość +wstrzykiwanych plików — zwłaszcza `MEMORY.md`, który może z czasem rosnąć i prowadzić do +nieoczekiwanie wysokiego zużycia kontekstu oraz częstszego kompaktowania. -> **Uwaga:** dzienne pliki `memory/*.md` **nie** są wstrzykiwane automatycznie. -> Są dostępne na żądanie przez narzędzia `memory_search` i `memory_get`, więc -> nie wliczają się do okna kontekstu, dopóki model ich jawnie nie odczyta. +> **Uwaga:** dzienne pliki `memory/*.md` **nie** są wstrzykiwane automatycznie. Są +> dostępne na żądanie przez narzędzia `memory_search` i `memory_get`, więc nie +> wliczają się do okna kontekstu, chyba że model jawnie je odczyta. -Duże pliki są obcinane z markerem. Maksymalny rozmiar pojedynczego pliku jest kontrolowany przez +Duże pliki są obcinane z użyciem znacznika. Maksymalny rozmiar pojedynczego pliku jest kontrolowany przez `agents.defaults.bootstrapMaxChars` (domyślnie: 20000). Łączna zawartość wstrzykniętego bootstrapu we wszystkich plikach jest ograniczona przez `agents.defaults.bootstrapTotalMaxChars` -(domyślnie: 150000). Brakujące pliki wstrzykują krótki marker brakującego pliku. Gdy nastąpi obcięcie, -OpenClaw może wstrzyknąć blok ostrzegawczy w Project Context; kontroluje to +(domyślnie: 150000). Brakujące pliki wstrzykują krótki znacznik brakującego pliku. Gdy wystąpi obcięcie, +OpenClaw może wstrzyknąć blok ostrzeżenia w Kontekście projektu; sterujesz tym przez `agents.defaults.bootstrapPromptTruncationWarning` (`off`, `once`, `always`; domyślnie: `once`). -Sesje sub-agentów wstrzykują tylko `AGENTS.md` i `TOOLS.md` (inne pliki bootstrap -są odfiltrowywane, aby kontekst sub-agenta był mały). +Sesje podagentów wstrzykują tylko `AGENTS.md` i `TOOLS.md` (pozostałe pliki bootstrapu +są odfiltrowywane, aby zachować mały kontekst podagenta). Wewnętrzne hooki mogą przechwycić ten krok przez `agent:bootstrap`, aby mutować lub zastępować -wstrzyknięte pliki bootstrap (na przykład zamieniając `SOUL.md` na alternatywną personę). +wstrzyknięte pliki bootstrapu (na przykład zamieniając `SOUL.md` na alternatywną personę). Jeśli chcesz, aby agent brzmiał mniej generycznie, zacznij od -[Przewodnika po osobowości SOUL.md](/concepts/soul). +[Przewodnika osobowości SOUL.md](/pl/concepts/soul). -Aby sprawdzić, jaki wkład wnosi każdy wstrzyknięty plik (surowy vs wstrzyknięty, obcięcie, a także narzut schematu narzędzi), użyj `/context list` lub `/context detail`. Zobacz [Context](/concepts/context). +Aby sprawdzić, jaki wkład ma każdy wstrzyknięty plik (surowy vs wstrzyknięty, obcięcie oraz narzut schematu narzędzi), użyj `/context list` lub `/context detail`. Zobacz [Kontekst](/pl/concepts/context). ## Obsługa czasu -Prompt systemowy zawiera dedykowaną sekcję **Current Date & Time**, gdy znana jest +Prompt systemowy zawiera osobną sekcję **Bieżąca data i godzina**, gdy znana jest strefa czasowa użytkownika. Aby zachować stabilność pamięci podręcznej promptu, zawiera teraz tylko **strefę czasową** (bez dynamicznego zegara ani formatu czasu). -Używaj `session_status`, gdy agent potrzebuje aktualnego czasu; karta stanu -zawiera wiersz ze znacznikiem czasu. To samo narzędzie może opcjonalnie ustawić nadpisanie modelu -dla danej sesji (`model=default` je usuwa). +Użyj `session_status`, gdy agent potrzebuje bieżącego czasu; karta statusu +zawiera wiersz ze znacznikiem czasu. To samo narzędzie może opcjonalnie ustawić zastąpienie modelu +dla sesji (`model=default` je czyści). -Konfiguracja: +Skonfiguruj za pomocą: - `agents.defaults.userTimezone` - `agents.defaults.timeFormat` (`auto` | `12` | `24`) -Pełne szczegóły zachowania znajdziesz w [Data i czas](/date-time). +Pełne szczegóły zachowania znajdziesz w [Data i godzina](/pl/date-time). ## Skills -Gdy istnieją kwalifikujące się Skills, OpenClaw wstrzykuje zwartą **listę dostępnych umiejętności** -(`formatSkillsForPrompt`), która zawiera **ścieżkę do pliku** dla każdej umiejętności. Prompt instruuje model, aby używał `read` do ładowania pliku SKILL.md w podanej lokalizacji -(workspace, zarządzanej lub bundlowanej). Jeśli nie ma kwalifikujących się Skills, sekcja -Skills jest pomijana. +Gdy istnieją kwalifikujące się skille, OpenClaw wstrzykuje zwięzłą **listę dostępnych skillów** +(`formatSkillsForPrompt`), która zawiera **ścieżkę pliku** dla każdego skilla. Prompt +instruuje model, aby użył `read` do wczytania SKILL.md z podanej +lokalizacji (workspace, zarządzanej lub dołączonej). Jeśli żadne skille się nie kwalifikują, +sekcja Skills jest pomijana. -Kwalifikacja obejmuje bramki metadanych umiejętności, sprawdzenia środowiska runtime/konfiguracji -oraz efektywną listę dozwolonych umiejętności agenta, gdy skonfigurowano `agents.defaults.skills` lub +Kwalifikowalność obejmuje bramki metadanych skilli, kontrole środowiska wykonawczego/konfiguracji +oraz efektywną listę dozwolonych skillów agenta, gdy skonfigurowano `agents.defaults.skills` lub `agents.list[].skills`. ``` @@ -173,12 +173,13 @@ oraz efektywną listę dozwolonych umiejętności agenta, gdy skonfigurowano `ag ``` -Dzięki temu bazowy prompt pozostaje mały, a jednocześnie umożliwia ukierunkowane użycie umiejętności. +Dzięki temu podstawowy prompt pozostaje mały, a jednocześnie umożliwia użycie ukierunkowanych skillów. -## Documentation +## Dokumentacja -Gdy jest dostępna, prompt systemowy zawiera sekcję **Documentation**, która wskazuje -lokalny katalog dokumentacji OpenClaw (`docs/` w workspace repozytorium albo dokumentację -z bundlowanego pakietu npm) i zawiera też informację o publicznym lustrze, repozytorium źródłowym, społecznościowym Discordzie oraz ClawHub ([https://clawhub.ai](https://clawhub.ai)) do odkrywania Skills. Prompt instruuje model, aby w pierwszej kolejności korzystał z lokalnej dokumentacji -w sprawach dotyczących zachowania OpenClaw, poleceń, konfiguracji lub architektury, oraz aby -w miarę możliwości sam uruchamiał `openclaw status` (pytając użytkownika tylko wtedy, gdy nie ma dostępu). +Gdy jest dostępna, prompt systemowy zawiera sekcję **Dokumentacja**, która wskazuje +lokalny katalog dokumentacji OpenClaw (albo `docs/` w workspace repozytorium, albo dołączoną dokumentację pakietu npm) +oraz wspomina także o publicznym mirrorze, repozytorium źródłowym, społeczności Discord i +ClawHub ([https://clawhub.ai](https://clawhub.ai)) do odkrywania skillów. Prompt instruuje model, aby najpierw konsultował lokalną dokumentację +w sprawach dotyczących zachowania OpenClaw, poleceń, konfiguracji lub architektury oraz aby +samodzielnie uruchamiał `openclaw status`, gdy to możliwe (prosząc użytkownika tylko wtedy, gdy nie ma dostępu). diff --git a/docs/pl/gateway/configuration-reference.md b/docs/pl/gateway/configuration-reference.md index a72dfd35a..e5b75c0c2 100644 --- a/docs/pl/gateway/configuration-reference.md +++ b/docs/pl/gateway/configuration-reference.md @@ -1,51 +1,51 @@ --- read_when: - Potrzebujesz dokładnej semantyki pól konfiguracji lub wartości domyślnych - - Weryfikujesz bloki konfiguracji kanału, modelu, gateway lub narzędzi -summary: Kompletna dokumentacja referencyjna każdego klucza konfiguracji OpenClaw, wartości domyślnych i ustawień kanałów -title: Dokumentacja referencyjna konfiguracji + - Weryfikujesz bloki konfiguracji kanałów, modeli, bramy lub narzędzi +summary: Kompletny opis każdego klucza konfiguracji OpenClaw, wartości domyślnych i ustawień kanałów +title: Dokumentacja konfiguracji x-i18n: - generated_at: "2026-04-07T09:50:33Z" + generated_at: "2026-04-08T02:20:02Z" model: gpt-5.4 provider: openai - source_hash: 7768cb77e1d3fc483c66f655ea891d2c32f21b247e3c1a56a919b28a37f9b128 + source_hash: 2c7991b948cbbb7954a3e26280089ab00088e7f4878ec0b0540c3c9acf222ebb source_path: gateway/configuration-reference.md workflow: 15 --- -# Dokumentacja referencyjna konfiguracji +# Dokumentacja konfiguracji -Każde pole dostępne w `~/.openclaw/openclaw.json`. Przegląd zorientowany na zadania znajdziesz w [Konfiguracja](/pl/gateway/configuration). +Każde pole dostępne w `~/.openclaw/openclaw.json`. Aby zobaczyć przegląd zorientowany na zadania, przejdź do [Configuration](/pl/gateway/configuration). -Format konfiguracji to **JSON5** (dozwolone komentarze + przecinki końcowe). Wszystkie pola są opcjonalne — OpenClaw używa bezpiecznych wartości domyślnych, gdy są pominięte. +Format konfiguracji to **JSON5** (dozwolone komentarze + przecinki końcowe). Wszystkie pola są opcjonalne — OpenClaw używa bezpiecznych wartości domyślnych, gdy zostaną pominięte. --- ## Kanały -Każdy kanał uruchamia się automatycznie, gdy istnieje jego sekcja konfiguracji (chyba że `enabled: false`). +Każdy kanał uruchamia się automatycznie, gdy istnieje jego sekcja konfiguracji (chyba że ustawiono `enabled: false`). -### Dostęp DM i grupowy +### Dostęp do wiadomości prywatnych i grup -Wszystkie kanały obsługują polityki DM i polityki grup: +Wszystkie kanały obsługują zasady dla wiadomości prywatnych i grup: -| Polityka DM | Zachowanie | -| ------------------- | --------------------------------------------------------------- | -| `pairing` (domyślnie) | Nieznani nadawcy dostają jednorazowy kod parowania; właściciel musi go zatwierdzić | -| `allowlist` | Tylko nadawcy z `allowFrom` (lub sparowanego allow store) | -| `open` | Zezwól na wszystkie przychodzące DM (wymaga `allowFrom: ["*"]`) | -| `disabled` | Ignoruj wszystkie przychodzące DM | +| Zasada DM | Zachowanie | +| -------------------- | -------------------------------------------------------------- | +| `pairing` (domyślna) | Nieznani nadawcy otrzymują jednorazowy kod parowania; właściciel musi zatwierdzić | +| `allowlist` | Tylko nadawcy z `allowFrom` (lub sparowanego magazynu dozwolonych) | +| `open` | Zezwalaj na wszystkie przychodzące wiadomości prywatne (wymaga `allowFrom: ["*"]`) | +| `disabled` | Ignoruj wszystkie przychodzące wiadomości prywatne | -| Polityka grup | Zachowanie | -| -------------------- | ------------------------------------------------------ | -| `allowlist` (domyślnie) | Tylko grupy pasujące do skonfigurowanej allowlisty | -| `open` | Pomija allowlisty grupowe (bramka wzmianek nadal obowiązuje) | -| `disabled` | Blokuje wszystkie wiadomości grupowe/pokojów | +| Zasada grupowa | Zachowanie | +| ---------------------- | ----------------------------------------------------- | +| `allowlist` (domyślna) | Tylko grupy pasujące do skonfigurowanej listy dozwolonych | +| `open` | Pomija listy dozwolonych dla grup (nadal obowiązuje wymuszanie wzmianki) | +| `disabled` | Blokuje wszystkie wiadomości grupowe/pokojów | `channels.defaults.groupPolicy` ustawia wartość domyślną, gdy `groupPolicy` dostawcy nie jest ustawione. -Kody parowania wygasają po 1 godzinie. Liczba oczekujących próśb o parowanie DM jest ograniczona do **3 na kanał**. -Jeśli blok dostawcy całkowicie nie istnieje (`channels.` nieobecne), polityka grup w czasie działania wraca do `allowlist` (fail-closed) z ostrzeżeniem przy starcie. +Kody parowania wygasają po 1 godzinie. Oczekujące żądania parowania DM są ograniczone do **3 na kanał**. +Jeśli blok dostawcy całkowicie nie istnieje (`channels.` nieobecne), zasada grupowa w czasie działania wraca do `allowlist` (fail-closed) z ostrzeżeniem przy uruchamianiu. ### Nadpisania modelu dla kanałów @@ -73,7 +73,7 @@ Użyj `channels.modelByChannel`, aby przypiąć określone identyfikatory kanał ### Domyślne ustawienia kanałów i heartbeat -Użyj `channels.defaults` do współdzielonej polityki grup i zachowania heartbeat między dostawcami: +Użyj `channels.defaults` do wspólnego zachowania zasad grupowych i heartbeat we wszystkich dostawcach: ```json5 { @@ -91,15 +91,15 @@ Użyj `channels.defaults` do współdzielonej polityki grup i zachowania heartbe } ``` -- `channels.defaults.groupPolicy`: zapasowa polityka grup, gdy `groupPolicy` na poziomie dostawcy nie jest ustawione. -- `channels.defaults.contextVisibility`: domyślny tryb widoczności kontekstu uzupełniającego dla wszystkich kanałów. Wartości: `all` (domyślnie, uwzględnia cały cytowany/wątkowy/historyczny kontekst), `allowlist` (uwzględnia tylko kontekst od nadawców z allowlisty), `allowlist_quote` (jak allowlist, ale zachowuje jawny kontekst cytatu/odpowiedzi). Nadpisanie per kanał: `channels..contextVisibility`. +- `channels.defaults.groupPolicy`: zapasowa zasada grupowa, gdy `groupPolicy` na poziomie dostawcy nie jest ustawione. +- `channels.defaults.contextVisibility`: domyślny tryb widoczności kontekstu uzupełniającego dla wszystkich kanałów. Wartości: `all` (domyślnie, uwzględnia cały cytowany/wątkowy/historyczny kontekst), `allowlist` (uwzględnia tylko kontekst od nadawców z listy dozwolonych), `allowlist_quote` (jak allowlist, ale zachowuje jawny kontekst cytatu/odpowiedzi). Nadpisanie per kanał: `channels..contextVisibility`. - `channels.defaults.heartbeat.showOk`: uwzględnia zdrowe statusy kanałów w wyjściu heartbeat. -- `channels.defaults.heartbeat.showAlerts`: uwzględnia statusy zdegradowane/błędów w wyjściu heartbeat. -- `channels.defaults.heartbeat.useIndicator`: renderuje kompaktowe wyjście heartbeat w stylu wskaźnika. +- `channels.defaults.heartbeat.showAlerts`: uwzględnia statusy pogorszone/błędne w wyjściu heartbeat. +- `channels.defaults.heartbeat.useIndicator`: renderuje zwarte wyjście heartbeat w stylu wskaźnika. ### WhatsApp -WhatsApp działa przez kanał web gateway (`Baileys Web`). Uruchamia się automatycznie, gdy istnieje połączona sesja. +WhatsApp działa przez kanał web bramy (Baileys Web). Uruchamia się automatycznie, gdy istnieje połączona sesja. ```json5 { @@ -110,7 +110,7 @@ WhatsApp działa przez kanał web gateway (`Baileys Web`). Uruchamia się automa textChunkLimit: 4000, chunkMode: "length", // length | newline mediaMaxMb: 50, - sendReadReceipts: true, // niebieskie ptaszki (false w trybie self-chat) + sendReadReceipts: true, // niebieskie haczyki (false w trybie self-chat) groups: { "*": { requireMention: true }, }, @@ -132,7 +132,7 @@ WhatsApp działa przez kanał web gateway (`Baileys Web`). Uruchamia się automa } ``` - + ```json5 { @@ -151,7 +151,7 @@ WhatsApp działa przez kanał web gateway (`Baileys Web`). Uruchamia się automa ``` - Polecenia wychodzące domyślnie używają konta `default`, jeśli istnieje; w przeciwnym razie pierwszego skonfigurowanego identyfikatora konta (posortowanego). -- Opcjonalne `channels.whatsapp.defaultAccount` nadpisuje ten wybór domyślnego konta zapasowego, jeśli pasuje do skonfigurowanego identyfikatora konta. +- Opcjonalne `channels.whatsapp.defaultAccount` nadpisuje ten domyślny wybór konta zapasowego, jeśli pasuje do skonfigurowanego identyfikatora konta. - Starszy katalog uwierzytelniania Baileys dla pojedynczego konta jest migrowany przez `openclaw doctor` do `whatsapp/default`. - Nadpisania per konto: `channels.whatsapp.accounts..sendReadReceipts`, `channels.whatsapp.accounts..dmPolicy`, `channels.whatsapp.accounts..allowFrom`. @@ -171,24 +171,24 @@ WhatsApp działa przez kanał web gateway (`Baileys Web`). Uruchamia się automa "*": { requireMention: true }, "-1001234567890": { allowFrom: ["@admin"], - systemPrompt: "Keep answers brief.", + systemPrompt: "Zachowuj zwięzłość odpowiedzi.", topics: { "99": { requireMention: false, skills: ["search"], - systemPrompt: "Stay on topic.", + systemPrompt: "Trzymaj się tematu.", }, }, }, }, customCommands: [ - { command: "backup", description: "Git backup" }, - { command: "generate", description: "Create an image" }, + { command: "backup", description: "Kopia zapasowa Git" }, + { command: "generate", description: "Utwórz obraz" }, ], historyLimit: 50, replyToMode: "first", // off | first | all | batched linkPreview: true, - streaming: "partial", // off | partial | block | progress (default: off; opt in explicitly to avoid preview-edit rate limits) + streaming: "partial", // off | partial | block | progress (domyślnie: off; jawnie włącz, aby uniknąć limitów szybkości edycji podglądu) actions: { reactions: true, sendMessage: true }, reactionNotifications: "own", // off | own | all mediaMaxMb: 100, @@ -211,13 +211,13 @@ WhatsApp działa przez kanał web gateway (`Baileys Web`). Uruchamia się automa } ``` -- Token bota: `channels.telegram.botToken` lub `channels.telegram.tokenFile` (tylko zwykły plik; symlinki są odrzucane), z `TELEGRAM_BOT_TOKEN` jako wartością zapasową dla konta domyślnego. +- Token bota: `channels.telegram.botToken` lub `channels.telegram.tokenFile` (tylko zwykły plik; symlinki odrzucane), z `TELEGRAM_BOT_TOKEN` jako wartością zapasową dla konta domyślnego. - Opcjonalne `channels.telegram.defaultAccount` nadpisuje domyślny wybór konta, jeśli pasuje do skonfigurowanego identyfikatora konta. -- W konfiguracjach wielokontowych (2+ identyfikatory kont) ustaw jawne konto domyślne (`channels.telegram.defaultAccount` lub `channels.telegram.accounts.default`), aby uniknąć routowania zapasowego; `openclaw doctor` ostrzega, gdy go brakuje lub jest nieprawidłowe. -- `configWrites: false` blokuje zapisy konfiguracji inicjowane przez Telegram (migracje identyfikatorów supergrup, `/config set|unset`). -- Wpisy najwyższego poziomu `bindings[]` z `type: "acp"` konfigurują trwałe powiązania ACP dla tematów forum (użyj kanonicznego `chatId:topic:topicId` w `match.peer.id`). Semantyka pól jest współdzielona w [Agenci ACP](/pl/tools/acp-agents#channel-specific-settings). -- Podglądy streamingu Telegram używają `sendMessage` + `editMessageText` (działa w czatach bezpośrednich i grupowych). -- Polityka ponawiania: zobacz [Polityka ponawiania](/pl/concepts/retry). +- W konfiguracjach wielokontowych (2+ identyfikatory kont), ustaw jawne konto domyślne (`channels.telegram.defaultAccount` lub `channels.telegram.accounts.default`), aby uniknąć routingu zapasowego; `openclaw doctor` ostrzega, gdy tego brakuje lub jest nieprawidłowe. +- `configWrites: false` blokuje zapisy konfiguracji inicjowane z Telegrama (migracje ID supergrup, `/config set|unset`). +- Wpisy najwyższego poziomu `bindings[]` z `type: "acp"` konfigurują trwałe powiązania ACP dla tematów forum (użyj kanonicznego `chatId:topic:topicId` w `match.peer.id`). Semantyka pól jest współdzielona w [ACP Agents](/pl/tools/acp-agents#channel-specific-settings). +- Podglądy strumieniowania Telegrama używają `sendMessage` + `editMessageText` (działa w czatach prywatnych i grupowych). +- Zasada ponawiania: zobacz [Retry policy](/pl/concepts/retry). ### Discord @@ -264,7 +264,7 @@ WhatsApp działa przez kanał web gateway (`Baileys Web`). Uruchamia się automa requireMention: true, users: ["987654321098765432"], skills: ["docs"], - systemPrompt: "Short answers only.", + systemPrompt: "Tylko krótkie odpowiedzi.", }, }, }, @@ -272,7 +272,7 @@ WhatsApp działa przez kanał web gateway (`Baileys Web`). Uruchamia się automa historyLimit: 20, textChunkLimit: 2000, chunkMode: "length", // length | newline - streaming: "off", // off | partial | block | progress (progress maps to partial on Discord) + streaming: "off", // off | partial | block | progress (progress jest mapowane na partial w Discord) maxLinesPerMessage: 17, ui: { components: { @@ -283,7 +283,7 @@ WhatsApp działa przez kanał web gateway (`Baileys Web`). Uruchamia się automa enabled: true, idleHours: 24, maxAgeHours: 0, - spawnSubagentSessions: false, // opt-in for sessions_spawn({ thread: true }) + spawnSubagentSessions: false, // opt-in dla sessions_spawn({ thread: true }) }, voice: { enabled: true, @@ -320,33 +320,33 @@ WhatsApp działa przez kanał web gateway (`Baileys Web`). Uruchamia się automa ``` - Token: `channels.discord.token`, z `DISCORD_BOT_TOKEN` jako wartością zapasową dla konta domyślnego. -- Bezpośrednie wywołania wychodzące, które podają jawny `token` Discord, używają tego tokena dla wywołania; ustawienia retry/polityki konta nadal pochodzą z wybranego konta w aktywnej migawce runtime. +- Bezpośrednie wywołania wychodzące, które podają jawny `token` Discorda, używają tego tokena do wywołania; ustawienia ponawiania/zasad konta nadal pochodzą z wybranego konta w aktywnej migawce czasu działania. - Opcjonalne `channels.discord.defaultAccount` nadpisuje domyślny wybór konta, jeśli pasuje do skonfigurowanego identyfikatora konta. -- Użyj `user:` (DM) lub `channel:` (kanał serwera) jako celów dostarczenia; same identyfikatory numeryczne są odrzucane. -- Slugi serwerów są pisane małymi literami, a spacje są zastępowane przez `-`; klucze kanałów używają nazwy w formie slugu (bez `#`). Preferuj identyfikatory serwerów. -- Wiadomości napisane przez boty są domyślnie ignorowane. `allowBots: true` je włącza; użyj `allowBots: "mentions"`, aby akceptować tylko wiadomości botów, które wzmiankują bota (własne wiadomości nadal są filtrowane). -- `channels.discord.guilds..ignoreOtherMentions` (oraz nadpisania kanału) odrzuca wiadomości, które wzmiankują innego użytkownika lub rolę, ale nie bota (z wyłączeniem @everyone/@here). +- Użyj `user:` (DM) lub `channel:` (kanał guildy) jako celów dostarczenia; same numeryczne identyfikatory są odrzucane. +- Slugi guild są pisane małymi literami, a spacje zastępowane przez `-`; klucze kanałów używają nazwy w formie slugu (bez `#`). Preferuj identyfikatory guild. +- Wiadomości autorstwa botów są domyślnie ignorowane. `allowBots: true` je włącza; użyj `allowBots: "mentions"`, aby akceptować tylko wiadomości botów, które wspominają bota (własne wiadomości nadal filtrowane). +- `channels.discord.guilds..ignoreOtherMentions` (oraz nadpisania kanałów) odrzuca wiadomości, które wspominają innego użytkownika lub rolę, ale nie bota (z wyłączeniem @everyone/@here). - `maxLinesPerMessage` (domyślnie 17) dzieli wysokie wiadomości nawet wtedy, gdy mają mniej niż 2000 znaków. -- `channels.discord.threadBindings` kontroluje routowanie związane z wątkami Discord: - - `enabled`: nadpisanie Discord dla funkcji sesji związanych z wątkami (`/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age` oraz dostarczanie/routowanie związane z wątkiem) - - `idleHours`: nadpisanie Discord dla automatycznego odfokusowania po bezczynności w godzinach (`0` wyłącza) - - `maxAgeHours`: nadpisanie Discord dla twardego maksymalnego wieku w godzinach (`0` wyłącza) +- `channels.discord.threadBindings` kontroluje routing związany z wątkami Discorda: + - `enabled`: nadpisanie Discorda dla funkcji sesji związanych z wątkami (`/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age` oraz dostarczanie/routing związane z powiązaniem) + - `idleHours`: nadpisanie Discorda dla automatycznego wyłączania focusa po bezczynności w godzinach (`0` wyłącza) + - `maxAgeHours`: nadpisanie Discorda dla sztywnego maksymalnego wieku w godzinach (`0` wyłącza) - `spawnSubagentSessions`: przełącznik opt-in dla automatycznego tworzenia/powiązywania wątków przez `sessions_spawn({ thread: true })` -- Wpisy najwyższego poziomu `bindings[]` z `type: "acp"` konfigurują trwałe powiązania ACP dla kanałów i wątków (użyj identyfikatora kanału/wątku w `match.peer.id`). Semantyka pól jest współdzielona w [Agenci ACP](/pl/tools/acp-agents#channel-specific-settings). +- Wpisy najwyższego poziomu `bindings[]` z `type: "acp"` konfigurują trwałe powiązania ACP dla kanałów i wątków (użyj id kanału/wątku w `match.peer.id`). Semantyka pól jest współdzielona w [ACP Agents](/pl/tools/acp-agents#channel-specific-settings). - `channels.discord.ui.components.accentColor` ustawia kolor akcentu dla kontenerów Discord components v2. -- `channels.discord.voice` włącza rozmowy w kanałach głosowych Discord oraz opcjonalne auto-dołączanie + nadpisania TTS. -- `channels.discord.voice.daveEncryption` i `channels.discord.voice.decryptionFailureTolerance` są przekazywane do opcji DAVE `@discordjs/voice` (domyślnie `true` i `24`). -- OpenClaw dodatkowo próbuje odzyskać odbiór głosu przez opuszczenie i ponowne dołączenie do sesji głosowej po powtarzających się błędach odszyfrowania. -- `channels.discord.streaming` to kanoniczny klucz trybu streamingu. Starsze `streamMode` i wartości logiczne `streaming` są automatycznie migrowane. -- `channels.discord.autoPresence` mapuje dostępność runtime na obecność bota (healthy => online, degraded => idle, exhausted => dnd) i pozwala na opcjonalne nadpisania tekstu statusu. -- `channels.discord.dangerouslyAllowNameMatching` ponownie włącza dopasowywanie po zmienialnej nazwie/tagu (tryb zgodności break-glass). -- `channels.discord.execApprovals`: natywne dla Discord dostarczanie akceptacji exec i autoryzacja zatwierdzających. - - `enabled`: `true`, `false` lub `"auto"` (domyślnie). W trybie auto akceptacje exec aktywują się, gdy zatwierdzający mogą zostać rozwiązani z `approvers` lub `commands.ownerAllowFrom`. - - `approvers`: identyfikatory użytkowników Discord, którzy mogą zatwierdzać żądania exec. Po pominięciu używa `commands.ownerAllowFrom`. - - `agentFilter`: opcjonalna allowlista identyfikatorów agentów. Pomiń, aby przekazywać akceptacje dla wszystkich agentów. +- `channels.discord.voice` włącza rozmowy w kanałach głosowych Discord oraz opcjonalne automatyczne dołączanie + nadpisania TTS. +- `channels.discord.voice.daveEncryption` i `channels.discord.voice.decryptionFailureTolerance` są przekazywane do opcji DAVE w `@discordjs/voice` (domyślnie `true` i `24`). +- OpenClaw dodatkowo próbuje odzyskać odbiór głosu przez opuszczenie i ponowne dołączenie do sesji głosowej po powtarzających się błędach deszyfrowania. +- `channels.discord.streaming` to kanoniczny klucz trybu strumieniowania. Starsze wartości `streamMode` i logiczne `streaming` są automatycznie migrowane. +- `channels.discord.autoPresence` mapuje dostępność czasu działania na status bota (healthy => online, degraded => idle, exhausted => dnd) i pozwala na opcjonalne nadpisania tekstu statusu. +- `channels.discord.dangerouslyAllowNameMatching` ponownie włącza dopasowywanie po zmiennej nazwie/tagu (tryb zgodności break-glass). +- `channels.discord.execApprovals`: natywne dla Discorda dostarczanie zatwierdzeń exec i autoryzacja zatwierdzających. + - `enabled`: `true`, `false` lub `"auto"` (domyślnie). W trybie auto zatwierdzenia exec aktywują się, gdy zatwierdzających można rozpoznać z `approvers` lub `commands.ownerAllowFrom`. + - `approvers`: identyfikatory użytkowników Discorda, którzy mogą zatwierdzać żądania exec. Gdy pominięte, używa `commands.ownerAllowFrom`. + - `agentFilter`: opcjonalna lista dozwolonych identyfikatorów agentów. Pomiń, aby przekazywać zatwierdzenia dla wszystkich agentów. - `sessionFilter`: opcjonalne wzorce kluczy sesji (podciąg lub regex). - - `target`: gdzie wysyłać prośby o akceptację. `"dm"` (domyślnie) wysyła do DM zatwierdzających, `"channel"` wysyła do kanału źródłowego, `"both"` wysyła do obu. Gdy target zawiera `"channel"`, przyciski mogą być używane tylko przez rozwiązanych zatwierdzających. - - `cleanupAfterResolve`: gdy `true`, usuwa DM z akceptacją po zatwierdzeniu, odrzuceniu lub przekroczeniu czasu. + - `target`: gdzie wysyłać prompty zatwierdzeń. `"dm"` (domyślnie) wysyła do DM zatwierdzających, `"channel"` wysyła do kanału źródłowego, `"both"` wysyła do obu. Gdy target obejmuje `"channel"`, przyciski mogą być używane tylko przez rozpoznanych zatwierdzających. + - `cleanupAfterResolve`: gdy `true`, usuwa DM z zatwierdzeniem po akceptacji, odrzuceniu lub przekroczeniu czasu. **Tryby powiadomień o reakcjach:** `off` (brak), `own` (wiadomości bota, domyślnie), `all` (wszystkie wiadomości), `allowlist` (z `guilds..users` dla wszystkich wiadomości). @@ -380,10 +380,10 @@ WhatsApp działa przez kanał web gateway (`Baileys Web`). Uruchamia się automa ``` - JSON konta usługi: inline (`serviceAccount`) lub z pliku (`serviceAccountFile`). -- Obsługiwany jest także SecretRef dla konta usługi (`serviceAccountRef`). -- Wartości zapasowe z env: `GOOGLE_CHAT_SERVICE_ACCOUNT` lub `GOOGLE_CHAT_SERVICE_ACCOUNT_FILE`. +- Obsługiwany jest również SecretRef dla konta usługi (`serviceAccountRef`). +- Zapasowe wartości z env: `GOOGLE_CHAT_SERVICE_ACCOUNT` lub `GOOGLE_CHAT_SERVICE_ACCOUNT_FILE`. - Użyj `spaces/` lub `users/` jako celów dostarczenia. -- `channels.googlechat.dangerouslyAllowNameMatching` ponownie włącza dopasowywanie po zmienialnym e-mail principal (tryb zgodności break-glass). +- `channels.googlechat.dangerouslyAllowNameMatching` ponownie włącza dopasowywanie po zmiennym principalu e-mail (tryb zgodności break-glass). ### Slack @@ -405,7 +405,7 @@ WhatsApp działa przez kanał web gateway (`Baileys Web`). Uruchamia się automa allowBots: false, users: ["U123"], skills: ["docs"], - systemPrompt: "Short answers only.", + systemPrompt: "Tylko krótkie odpowiedzi.", }, }, historyLimit: 50, @@ -433,8 +433,8 @@ WhatsApp działa przez kanał web gateway (`Baileys Web`). Uruchamia się automa typingReaction: "hourglass_flowing_sand", textChunkLimit: 4000, chunkMode: "length", - streaming: "partial", // off | partial | block | progress (preview mode) - nativeStreaming: true, // use Slack native streaming API when streaming=partial + streaming: "partial", // off | partial | block | progress (tryb podglądu) + nativeStreaming: true, // użyj natywnego API strumieniowania Slacka, gdy streaming=partial mediaMaxMb: 20, execApprovals: { enabled: "auto", // true | false | "auto" @@ -448,32 +448,32 @@ WhatsApp działa przez kanał web gateway (`Baileys Web`). Uruchamia się automa } ``` -- **Socket mode** wymaga zarówno `botToken`, jak i `appToken` (`SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN` jako zapasowy env dla konta domyślnego). -- **HTTP mode** wymaga `botToken` plus `signingSecret` (na poziomie głównym lub per konto). -- `botToken`, `appToken`, `signingSecret` i `userToken` akceptują jawne - ciągi znaków lub obiekty SecretRef. -- Migawki kont Slack pokazują pola źródła/statusu per poświadczenie, takie jak - `botTokenSource`, `botTokenStatus`, `appTokenStatus`, a w trybie HTTP - `signingSecretStatus`. `configured_unavailable` oznacza, że konto jest - skonfigurowane przez SecretRef, ale bieżąca ścieżka polecenia/runtime nie mogła +- **Tryb Socket** wymaga zarówno `botToken`, jak i `appToken` (`SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN` jako zapasowe wartości środowiskowe dla konta domyślnego). +- **Tryb HTTP** wymaga `botToken` oraz `signingSecret` (na poziomie głównym lub per konto). +- `botToken`, `appToken`, `signingSecret` i `userToken` akceptują zwykłe + łańcuchy znaków lub obiekty SecretRef. +- Migawki kont Slacka ujawniają pola źródła/statusu dla poszczególnych poświadczeń, takie jak + `botTokenSource`, `botTokenStatus`, `appTokenStatus` oraz, w trybie HTTP, + `signingSecretStatus`. `configured_unavailable` oznacza, że konto zostało + skonfigurowane przez SecretRef, ale bieżąca ścieżka polecenia/czasu działania nie mogła rozwiązać wartości sekretu. -- `configWrites: false` blokuje zapisy konfiguracji inicjowane przez Slack. +- `configWrites: false` blokuje zapisy konfiguracji inicjowane ze Slacka. - Opcjonalne `channels.slack.defaultAccount` nadpisuje domyślny wybór konta, jeśli pasuje do skonfigurowanego identyfikatora konta. -- `channels.slack.streaming` to kanoniczny klucz trybu streamingu. Starsze `streamMode` i wartości logiczne `streaming` są automatycznie migrowane. +- `channels.slack.streaming` to kanoniczny klucz trybu strumieniowania. Starsze wartości `streamMode` i logiczne `streaming` są automatycznie migrowane. - Użyj `user:` (DM) lub `channel:` jako celów dostarczenia. **Tryby powiadomień o reakcjach:** `off`, `own` (domyślnie), `all`, `allowlist` (z `reactionAllowlist`). -**Izolacja sesji wątków:** `thread.historyScope` jest per wątek (domyślnie) lub współdzielone w obrębie kanału. `thread.inheritParent` kopiuje transkrypt kanału nadrzędnego do nowych wątków. +**Izolacja sesji wątków:** `thread.historyScope` jest per wątek (domyślnie) lub współdzielony w obrębie kanału. `thread.inheritParent` kopiuje transkrypt kanału nadrzędnego do nowych wątków. -- `typingReaction` dodaje tymczasową reakcję do przychodzącej wiadomości Slack podczas generowania odpowiedzi, a następnie usuwa ją po zakończeniu. Użyj shortcode emoji Slack, np. `"hourglass_flowing_sand"`. -- `channels.slack.execApprovals`: natywne dla Slack dostarczanie akceptacji exec i autoryzacja zatwierdzających. Ten sam schemat co w Discord: `enabled` (`true`/`false`/`"auto"`), `approvers` (identyfikatory użytkowników Slack), `agentFilter`, `sessionFilter` i `target` (`"dm"`, `"channel"` lub `"both"`). +- `typingReaction` dodaje tymczasową reakcję do przychodzącej wiadomości Slacka, gdy odpowiedź jest przetwarzana, a następnie usuwa ją po zakończeniu. Użyj shortcodu emoji Slacka, takiego jak `"hourglass_flowing_sand"`. +- `channels.slack.execApprovals`: natywne dla Slacka dostarczanie zatwierdzeń exec i autoryzacja zatwierdzających. Ten sam schemat co w Discordzie: `enabled` (`true`/`false`/`"auto"`), `approvers` (identyfikatory użytkowników Slacka), `agentFilter`, `sessionFilter` oraz `target` (`"dm"`, `"channel"` lub `"both"`). | Grupa akcji | Domyślnie | Uwagi | | ----------- | --------- | --------------------- | | reactions | włączone | Reagowanie + lista reakcji | | messages | włączone | Odczyt/wysyłanie/edycja/usuwanie | -| pins | włączone | Przypinanie/odpinanie/lista | +| pins | włączone | Przypinanie/odpinanie/listowanie | | memberInfo | włączone | Informacje o członku | | emojiList | włączone | Lista niestandardowych emoji | @@ -499,7 +499,7 @@ Mattermost jest dostarczany jako plugin: `openclaw plugins install @openclaw/mat native: true, // opt-in nativeSkills: true, callbackPath: "/api/channels/mattermost/command", - // Optional explicit URL for reverse-proxy/public deployments + // Opcjonalny jawny URL dla wdrożeń reverse-proxy/publicznych callbackUrl: "https://gateway.example.com/api/channels/mattermost/command", }, textChunkLimit: 4000, @@ -509,22 +509,22 @@ Mattermost jest dostarczany jako plugin: `openclaw plugins install @openclaw/mat } ``` -Tryby czatu: `oncall` (odpowiada na wzmiankę @, domyślnie), `onmessage` (na każdą wiadomość), `onchar` (na wiadomości zaczynające się od prefiksu wyzwalającego). +Tryby czatu: `oncall` (odpowiada na wzmiankę @, domyślnie), `onmessage` (każda wiadomość), `onchar` (wiadomości zaczynające się od prefiksu wyzwalającego). Gdy natywne polecenia Mattermost są włączone: -- `commands.callbackPath` musi być ścieżką (na przykład `/api/channels/mattermost/command`), a nie pełnym URL. -- `commands.callbackUrl` musi wskazywać endpoint gateway OpenClaw i być osiągalny z serwera Mattermost. -- Natywne callbacki slash są uwierzytelniane tokenami per polecenie zwróconymi - przez Mattermost podczas rejestracji poleceń slash. Jeśli rejestracja się nie powiedzie lub nie - zostaną aktywowane żadne polecenia, OpenClaw odrzuca callbacki z +- `commands.callbackPath` musi być ścieżką (na przykład `/api/channels/mattermost/command`), a nie pełnym URL-em. +- `commands.callbackUrl` musi wskazywać endpoint bramy OpenClaw i być osiągalny z serwera Mattermost. +- Natywne callbacki slash są uwierzytelniane przy użyciu tokenów per polecenie zwracanych + przez Mattermost podczas rejestracji polecenia slash. Jeśli rejestracja się nie powiedzie lub żadne + polecenia nie zostaną aktywowane, OpenClaw odrzuci callbacki komunikatem `Unauthorized: invalid command token.` -- Dla prywatnych/tailnet/wewnętrznych hostów callbacków Mattermost może wymagać, +- Dla prywatnych/tailnetowych/wewnętrznych hostów callbacków Mattermost może wymagać, aby `ServiceSettings.AllowedUntrustedInternalConnections` zawierało host/domenę callbacku. - Używaj wartości host/domena, a nie pełnych URL. -- `channels.mattermost.configWrites`: zezwala lub odmawia zapisów konfiguracji inicjowanych przez Mattermost. -- `channels.mattermost.requireMention`: wymaga `@mention` przed odpowiedzią w kanałach. -- `channels.mattermost.groups..requireMention`: nadpisanie bramki wzmianki per kanał (`"*"` jako domyślne). + Używaj wartości host/domena, a nie pełnych URL-i. +- `channels.mattermost.configWrites`: zezwalaj lub zabraniaj zapisów konfiguracji inicjowanych z Mattermost. +- `channels.mattermost.requireMention`: wymagaj `@mention` przed odpowiedzią w kanałach. +- `channels.mattermost.groups..requireMention`: nadpisanie wymuszania wzmianki per kanał (`"*"` dla domyślnego). - Opcjonalne `channels.mattermost.defaultAccount` nadpisuje domyślny wybór konta, jeśli pasuje do skonfigurowanego identyfikatora konta. ### Signal @@ -534,7 +534,7 @@ Gdy natywne polecenia Mattermost są włączone: channels: { signal: { enabled: true, - account: "+15555550123", // optional account binding + account: "+15555550123", // opcjonalne powiązanie z kontem dmPolicy: "pairing", allowFrom: ["+15551234567", "uuid:123e4567-e89b-12d3-a456-426614174000"], configWrites: true, @@ -548,13 +548,13 @@ Gdy natywne polecenia Mattermost są włączone: **Tryby powiadomień o reakcjach:** `off`, `own` (domyślnie), `all`, `allowlist` (z `reactionAllowlist`). -- `channels.signal.account`: przypina uruchomienie kanału do konkretnej tożsamości konta Signal. -- `channels.signal.configWrites`: zezwala lub odmawia zapisów konfiguracji inicjowanych przez Signal. +- `channels.signal.account`: przypina uruchamianie kanału do określonej tożsamości konta Signal. +- `channels.signal.configWrites`: zezwalaj lub zabraniaj zapisów konfiguracji inicjowanych z Signal. - Opcjonalne `channels.signal.defaultAccount` nadpisuje domyślny wybór konta, jeśli pasuje do skonfigurowanego identyfikatora konta. ### BlueBubbles -BlueBubbles to zalecana ścieżka dla iMessage (oparta na pluginie, konfigurowana w `channels.bluebubbles`). +BlueBubbles to zalecana ścieżka dla iMessage (oparta na pluginie, konfigurowana pod `channels.bluebubbles`). ```json5 { @@ -562,16 +562,16 @@ BlueBubbles to zalecana ścieżka dla iMessage (oparta na pluginie, konfigurowan bluebubbles: { enabled: true, dmPolicy: "pairing", - // serverUrl, password, webhookPath, group controls, and advanced actions: - // see /channels/bluebubbles + // serverUrl, password, webhookPath, kontrola grup i zaawansowane akcje: + // zobacz /channels/bluebubbles }, }, } ``` -- Główne ścieżki kluczy opisane tutaj: `channels.bluebubbles`, `channels.bluebubbles.dmPolicy`. +- Kluczowe ścieżki z core opisane tutaj: `channels.bluebubbles`, `channels.bluebubbles.dmPolicy`. - Opcjonalne `channels.bluebubbles.defaultAccount` nadpisuje domyślny wybór konta, jeśli pasuje do skonfigurowanego identyfikatora konta. -- Wpisy najwyższego poziomu `bindings[]` z `type: "acp"` mogą powiązać konwersacje BlueBubbles z trwałymi sesjami ACP. Użyj uchwytu BlueBubbles lub ciągu docelowego (`chat_id:*`, `chat_guid:*`, `chat_identifier:*`) w `match.peer.id`. Współdzielona semantyka pól: [Agenci ACP](/pl/tools/acp-agents#channel-specific-settings). +- Wpisy najwyższego poziomu `bindings[]` z `type: "acp"` mogą wiązać konwersacje BlueBubbles z trwałymi sesjami ACP. Użyj uchwytu BlueBubbles lub ciągu docelowego (`chat_id:*`, `chat_guid:*`, `chat_identifier:*`) w `match.peer.id`. Współdzielona semantyka pól: [ACP Agents](/pl/tools/acp-agents#channel-specific-settings). - Pełna konfiguracja kanału BlueBubbles jest opisana w [BlueBubbles](/pl/channels/bluebubbles). ### iMessage @@ -604,11 +604,11 @@ OpenClaw uruchamia `imsg rpc` (JSON-RPC przez stdio). Nie jest wymagany daemon a - Wymaga Full Disk Access do bazy danych Messages. - Preferuj cele `chat_id:`. Użyj `imsg chats --limit 20`, aby wyświetlić listę czatów. -- `cliPath` może wskazywać wrapper SSH; ustaw `remoteHost` (`host` lub `user@host`) do pobierania załączników przez SCP. +- `cliPath` może wskazywać na wrapper SSH; ustaw `remoteHost` (`host` lub `user@host`) dla pobierania załączników przez SCP. - `attachmentRoots` i `remoteAttachmentRoots` ograniczają ścieżki przychodzących załączników (domyślnie: `/Users/*/Library/Messages/Attachments`). - SCP używa ścisłego sprawdzania klucza hosta, więc upewnij się, że klucz hosta przekaźnika już istnieje w `~/.ssh/known_hosts`. -- `channels.imessage.configWrites`: zezwala lub odmawia zapisów konfiguracji inicjowanych przez iMessage. -- Wpisy najwyższego poziomu `bindings[]` z `type: "acp"` mogą powiązać konwersacje iMessage z trwałymi sesjami ACP. Użyj znormalizowanego uchwytu lub jawnego celu czatu (`chat_id:*`, `chat_guid:*`, `chat_identifier:*`) w `match.peer.id`. Współdzielona semantyka pól: [Agenci ACP](/pl/tools/acp-agents#channel-specific-settings). +- `channels.imessage.configWrites`: zezwalaj lub zabraniaj zapisów konfiguracji inicjowanych z iMessage. +- Wpisy najwyższego poziomu `bindings[]` z `type: "acp"` mogą wiązać konwersacje iMessage z trwałymi sesjami ACP. Użyj znormalizowanego uchwytu lub jawnego celu czatu (`chat_id:*`, `chat_guid:*`, `chat_identifier:*`) w `match.peer.id`. Współdzielona semantyka pól: [ACP Agents](/pl/tools/acp-agents#channel-specific-settings). @@ -621,7 +621,7 @@ exec ssh -T gateway-host imsg "$@" ### Matrix -Matrix jest obsługiwany przez rozszerzenie i konfigurowany w `channels.matrix`. +Matrix jest obsługiwany przez rozszerzenie i konfigurowany pod `channels.matrix`. ```json5 { @@ -653,23 +653,23 @@ Matrix jest obsługiwany przez rozszerzenie i konfigurowany w `channels.matrix`. - Uwierzytelnianie tokenem używa `accessToken`; uwierzytelnianie hasłem używa `userId` + `password`. - `channels.matrix.proxy` kieruje ruch HTTP Matrix przez jawny proxy HTTP(S). Nazwane konta mogą go nadpisywać przez `channels.matrix.accounts..proxy`. -- `channels.matrix.network.dangerouslyAllowPrivateNetwork` pozwala na prywatne/wewnętrzne homeservery. `proxy` i ten opt-in sieciowy są niezależnymi mechanizmami sterowania. +- `channels.matrix.network.dangerouslyAllowPrivateNetwork` zezwala na prywatne/wewnętrzne homeservery. `proxy` i ten opt-in sieciowy to niezależne mechanizmy. - `channels.matrix.defaultAccount` wybiera preferowane konto w konfiguracjach wielokontowych. -- `channels.matrix.autoJoin` ma domyślnie wartość `off`, więc zaproszone pokoje i nowe zaproszenia w stylu DM są ignorowane, dopóki nie ustawisz `autoJoin: "allowlist"` z `autoJoinAllowlist` lub `autoJoin: "always"`. -- `channels.matrix.execApprovals`: natywne dla Matrix dostarczanie akceptacji exec i autoryzacja zatwierdzających. - - `enabled`: `true`, `false` lub `"auto"` (domyślnie). W trybie auto akceptacje exec aktywują się, gdy zatwierdzający mogą zostać rozwiązani z `approvers` lub `commands.ownerAllowFrom`. +- `channels.matrix.autoJoin` domyślnie ma wartość `off`, więc zaproszone pokoje i nowe zaproszenia w stylu DM są ignorowane, dopóki nie ustawisz `autoJoin: "allowlist"` z `autoJoinAllowlist` lub `autoJoin: "always"`. +- `channels.matrix.execApprovals`: natywne dla Matrix dostarczanie zatwierdzeń exec i autoryzacja zatwierdzających. + - `enabled`: `true`, `false` lub `"auto"` (domyślnie). W trybie auto zatwierdzenia exec aktywują się, gdy zatwierdzających można rozpoznać z `approvers` lub `commands.ownerAllowFrom`. - `approvers`: identyfikatory użytkowników Matrix (np. `@owner:example.org`), którzy mogą zatwierdzać żądania exec. - - `agentFilter`: opcjonalna allowlista identyfikatorów agentów. Pomiń, aby przekazywać akceptacje dla wszystkich agentów. + - `agentFilter`: opcjonalna lista dozwolonych identyfikatorów agentów. Pomiń, aby przekazywać zatwierdzenia dla wszystkich agentów. - `sessionFilter`: opcjonalne wzorce kluczy sesji (podciąg lub regex). - - `target`: gdzie wysyłać prośby o akceptację. `"dm"` (domyślnie), `"channel"` (pokój źródłowy) lub `"both"`. + - `target`: gdzie wysyłać prompty zatwierdzeń. `"dm"` (domyślnie), `"channel"` (pokój źródłowy) lub `"both"`. - Nadpisania per konto: `channels.matrix.accounts..execApprovals`. -- `channels.matrix.dm.sessionScope` kontroluje sposób grupowania DM Matrix w sesje: `per-user` (domyślnie) współdzieli według zroute’owanego peera, natomiast `per-room` izoluje każdy pokój DM. -- Sondy statusu Matrix i wyszukiwania w katalogu na żywo używają tej samej polityki proxy co ruch runtime. -- Pełna konfiguracja Matrix, zasady targetowania i przykłady konfiguracji są opisane w [Matrix](/pl/channels/matrix). +- `channels.matrix.dm.sessionScope` kontroluje, jak DM Matrix są grupowane w sesje: `per-user` (domyślnie) współdzieli według routowanego peera, a `per-room` izoluje każdy pokój DM. +- Status probes Matrix i wyszukiwania katalogu na żywo używają tej samej polityki proxy co ruch czasu działania. +- Pełna konfiguracja Matrix, reguły targetowania i przykłady konfiguracji są opisane w [Matrix](/pl/channels/matrix). ### Microsoft Teams -Microsoft Teams jest obsługiwany przez rozszerzenie i konfigurowany w `channels.msteams`. +Microsoft Teams jest obsługiwany przez rozszerzenie i konfigurowany pod `channels.msteams`. ```json5 { @@ -677,19 +677,19 @@ Microsoft Teams jest obsługiwany przez rozszerzenie i konfigurowany w `channels msteams: { enabled: true, configWrites: true, - // appId, appPassword, tenantId, webhook, team/channel policies: - // see /channels/msteams + // appId, appPassword, tenantId, webhook, zasady zespołów/kanałów: + // zobacz /channels/msteams }, }, } ``` -- Główne ścieżki kluczy opisane tutaj: `channels.msteams`, `channels.msteams.configWrites`. -- Pełna konfiguracja Teams (poświadczenia, webhook, polityka DM/grup, nadpisania per zespół/per kanał) jest opisana w [Microsoft Teams](/pl/channels/msteams). +- Kluczowe ścieżki z core opisane tutaj: `channels.msteams`, `channels.msteams.configWrites`. +- Pełna konfiguracja Teams (poświadczenia, webhook, zasady DM/grup, nadpisania per zespół/per kanał) jest opisana w [Microsoft Teams](/pl/channels/msteams). ### IRC -IRC jest obsługiwany przez rozszerzenie i konfigurowany w `channels.irc`. +IRC jest obsługiwany przez rozszerzenie i konfigurowany pod `channels.irc`. ```json5 { @@ -710,9 +710,9 @@ IRC jest obsługiwany przez rozszerzenie i konfigurowany w `channels.irc`. } ``` -- Główne ścieżki kluczy opisane tutaj: `channels.irc`, `channels.irc.dmPolicy`, `channels.irc.configWrites`, `channels.irc.nickserv.*`. +- Kluczowe ścieżki z core opisane tutaj: `channels.irc`, `channels.irc.dmPolicy`, `channels.irc.configWrites`, `channels.irc.nickserv.*`. - Opcjonalne `channels.irc.defaultAccount` nadpisuje domyślny wybór konta, jeśli pasuje do skonfigurowanego identyfikatora konta. -- Pełna konfiguracja kanału IRC (host/port/TLS/kanały/allowlisty/bramka wzmianek) jest opisana w [IRC](/pl/channels/irc). +- Pełna konfiguracja kanału IRC (host/port/TLS/kanały/listy dozwolonych/wymuszanie wzmianki) jest opisana w [IRC](/pl/channels/irc). ### Wiele kont (wszystkie kanały) @@ -724,11 +724,11 @@ Uruchamiaj wiele kont na kanał (każde z własnym `accountId`): telegram: { accounts: { default: { - name: "Primary bot", + name: "Główny bot", botToken: "123456:ABC...", }, alerts: { - name: "Alerts bot", + name: "Bot alertów", botToken: "987654:XYZ...", }, }, @@ -738,27 +738,27 @@ Uruchamiaj wiele kont na kanał (każde z własnym `accountId`): ``` - `default` jest używane, gdy `accountId` jest pominięte (CLI + routing). -- Tokeny z env dotyczą tylko konta **default**. -- Bazowe ustawienia kanału dotyczą wszystkich kont, chyba że zostaną nadpisane per konto. -- Użyj `bindings[].match.accountId`, aby routować każde konto do innego agenta. -- Jeśli dodasz konto inne niż domyślne przez `openclaw channels add` (lub onboarding kanału), mając nadal konfigurację pojedynczego konta na najwyższym poziomie, OpenClaw najpierw promuje wartości najwyższego poziomu dotyczące pojedynczego konta do mapy kont kanału, aby oryginalne konto nadal działało. Większość kanałów przenosi je do `channels..accounts.default`; Matrix może zamiast tego zachować istniejący pasujący nazwany/domyslny cel. +- Tokeny środowiskowe mają zastosowanie tylko do konta **default**. +- Bazowe ustawienia kanału mają zastosowanie do wszystkich kont, chyba że zostaną nadpisane per konto. +- Użyj `bindings[].match.accountId`, aby kierować każde konto do innego agenta. +- Jeśli dodasz konto inne niż domyślne przez `openclaw channels add` (lub onboarding kanału), będąc nadal w top-levelowej konfiguracji kanału dla pojedynczego konta, OpenClaw najpierw promuje wartości top-level dla pojedynczego konta związane z tym kontem do mapy kont kanału, tak aby oryginalne konto nadal działało. Większość kanałów przenosi je do `channels..accounts.default`; Matrix może zachować istniejący pasujący nazwany/docelowy wpis domyślny. - Istniejące powiązania tylko kanałowe (bez `accountId`) nadal pasują do konta domyślnego; powiązania z zakresem konta pozostają opcjonalne. -- `openclaw doctor --fix` również naprawia mieszane kształty, przenosząc wartości najwyższego poziomu dotyczące pojedynczego konta do promowanego konta wybranego dla tego kanału. Większość kanałów używa `accounts.default`; Matrix może zamiast tego zachować istniejący pasujący nazwany/domyslny cel. +- `openclaw doctor --fix` także naprawia mieszane kształty, przenosząc top-levelowe wartości pojedynczego konta związane z kontem do promowanego konta wybranego dla danego kanału. Większość kanałów używa `accounts.default`; Matrix może zachować istniejący pasujący nazwany/docelowy wpis domyślny. ### Inne kanały rozszerzeń -Wiele kanałów rozszerzeń jest konfigurowanych jako `channels.` i opisanych na dedykowanych stronach kanałów (na przykład Feishu, Matrix, LINE, Nostr, Zalo, Nextcloud Talk, Synology Chat i Twitch). -Zobacz pełny indeks kanałów: [Kanały](/pl/channels). +Wiele kanałów rozszerzeń jest konfigurowanych jako `channels.` i opisanych na ich dedykowanych stronach kanałów (na przykład Feishu, Matrix, LINE, Nostr, Zalo, Nextcloud Talk, Synology Chat i Twitch). +Zobacz pełny indeks kanałów: [Channels](/pl/channels). -### Bramka wzmianek w czacie grupowym +### Wymuszanie wzmianki w czatach grupowych Wiadomości grupowe domyślnie **wymagają wzmianki** (wzmianka w metadanych lub bezpieczne wzorce regex). Dotyczy czatów grupowych WhatsApp, Telegram, Discord, Google Chat i iMessage. **Typy wzmianek:** -- **Wzmianki w metadanych**: natywne wzmianki @ platformy. Ignorowane w trybie self-chat WhatsApp. +- **Wzmianki w metadanych**: natywne wzmianki @ danej platformy. Ignorowane w trybie self-chat WhatsApp. - **Wzorce tekstowe**: bezpieczne wzorce regex w `agents.list[].groupChat.mentionPatterns`. Nieprawidłowe wzorce i niebezpieczne zagnieżdżone powtórzenia są ignorowane. -- Bramka wzmianek jest egzekwowana tylko wtedy, gdy wykrywanie jest możliwe (natywne wzmianki lub co najmniej jeden wzorzec). +- Wymuszanie wzmianki jest stosowane tylko wtedy, gdy wykrycie jest możliwe (natywne wzmianki lub co najmniej jeden wzorzec). ```json5 { @@ -788,7 +788,7 @@ Wiadomości grupowe domyślnie **wymagają wzmianki** (wzmianka w metadanych lub } ``` -Rozwiązywanie: nadpisanie per DM → domyślna wartość dostawcy → brak limitu (zachowywane jest wszystko). +Rozstrzyganie: nadpisanie per DM → wartość domyślna dostawcy → brak limitu (zachowywane wszystko). Obsługiwane: `telegram`, `whatsapp`, `discord`, `slack`, `signal`, `imessage`, `msteams`. @@ -820,13 +820,13 @@ Uwzględnij własny numer w `allowFrom`, aby włączyć tryb self-chat (ignoruje ```json5 { commands: { - native: "auto", // register native commands when supported - text: true, // parse /commands in chat messages - bash: false, // allow ! (alias: /bash) + native: "auto", // rejestruj natywne polecenia, gdy są obsługiwane + text: true, // parsuj /commands w wiadomościach czatu + bash: false, // zezwalaj na ! (alias: /bash) bashForegroundMs: 2000, - config: false, // allow /config - debug: false, // allow /debug - restart: false, // allow /restart + gateway restart tool + config: false, // zezwalaj na /config + debug: false, // zezwalaj na /debug + restart: false, // zezwalaj na /restart + narzędzie restartu bramy allowFrom: { "*": ["user1"], discord: ["user:123"], @@ -839,21 +839,21 @@ Uwzględnij własny numer w `allowFrom`, aby włączyć tryb self-chat (ignoruje - Polecenia tekstowe muszą być **samodzielnymi** wiadomościami zaczynającymi się od `/`. -- `native: "auto"` włącza natywne polecenia dla Discord/Telegram, pozostawia Slack wyłączony. +- `native: "auto"` włącza natywne polecenia dla Discorda/Telegrama, a w Slacku pozostawia wyłączone. - Nadpisanie per kanał: `channels.discord.commands.native` (bool lub `"auto"`). `false` czyści wcześniej zarejestrowane polecenia. - `channels.telegram.customCommands` dodaje dodatkowe wpisy menu bota Telegram. - `bash: true` włącza `! ` dla powłoki hosta. Wymaga `tools.elevated.enabled` i nadawcy w `tools.elevated.allowFrom.`. -- `config: true` włącza `/config` (odczytuje/zapisuje `openclaw.json`). Dla klientów gateway `chat.send` trwałe zapisy `/config set|unset` wymagają również `operator.admin`; tylko do odczytu `/config show` pozostaje dostępne dla zwykłych klientów operatora z zakresem zapisu. -- `channels..configWrites` ogranicza mutacje konfiguracji per kanał (domyślnie: true). -- Dla kanałów wielokontowych `channels..accounts..configWrites` również ogranicza zapisy kierowane do tego konta (na przykład `/allowlist --config --account ` lub `/config set channels..accounts....`). -- `allowFrom` jest per dostawca. Gdy jest ustawione, jest to **jedyne** źródło autoryzacji (allowlisty/parowanie kanału i `useAccessGroups` są ignorowane). -- `useAccessGroups: false` pozwala poleceniom omijać polityki grup dostępu, gdy `allowFrom` nie jest ustawione. +- `config: true` włącza `/config` (odczyty/zapisy `openclaw.json`). Dla klientów bramy `chat.send`, trwałe zapisy `/config set|unset` wymagają także `operator.admin`; tylko do odczytu `/config show` pozostaje dostępne dla zwykłych klientów operatora z uprawnieniem zapisu. +- `channels..configWrites` steruje mutacjami konfiguracji per kanał (domyślnie: true). +- Dla kanałów wielokontowych `channels..accounts..configWrites` również blokuje zapisy kierowane do tego konta (na przykład `/allowlist --config --account ` lub `/config set channels..accounts....`). +- `allowFrom` jest per dostawca. Gdy jest ustawione, jest to **jedyne** źródło autoryzacji (listy dozwolonych/parowanie kanału i `useAccessGroups` są ignorowane). +- `useAccessGroups: false` pozwala poleceniom omijać zasady grup dostępu, gdy `allowFrom` nie jest ustawione. --- -## Domyślne ustawienia agenta +## Domyślne ustawienia agentów ### `agents.defaults.workspace` @@ -867,7 +867,7 @@ Domyślnie: `~/.openclaw/workspace`. ### `agents.defaults.repoRoot` -Opcjonalny katalog główny repozytorium pokazywany w wierszu Runtime w system prompt. Jeśli nie jest ustawiony, OpenClaw wykrywa go automatycznie, idąc w górę od workspace. +Opcjonalny katalog główny repozytorium pokazywany w linii Runtime promptu systemowego. Jeśli nie jest ustawiony, OpenClaw wykrywa go automatycznie, przechodząc w górę od workspace. ```json5 { @@ -877,7 +877,7 @@ Opcjonalny katalog główny repozytorium pokazywany w wierszu Runtime w system p ### `agents.defaults.skills` -Opcjonalna domyślna allowlista Skills dla agentów, które nie ustawiają +Opcjonalna domyślna lista dozwolonych Skills dla agentów, które nie ustawiają `agents.list[].skills`. ```json5 @@ -885,9 +885,9 @@ Opcjonalna domyślna allowlista Skills dla agentów, które nie ustawiają agents: { defaults: { skills: ["github", "weather"] }, list: [ - { id: "writer" }, // inherits github, weather - { id: "docs", skills: ["docs-search"] }, // replaces defaults - { id: "locked-down", skills: [] }, // no skills + { id: "writer" }, // dziedziczy github, weather + { id: "docs", skills: ["docs-search"] }, // zastępuje domyślne + { id: "locked-down", skills: [] }, // bez Skills ], }, } @@ -895,8 +895,9 @@ Opcjonalna domyślna allowlista Skills dla agentów, które nie ustawiają - Pomiń `agents.defaults.skills`, aby domyślnie nie ograniczać Skills. - Pomiń `agents.list[].skills`, aby dziedziczyć wartości domyślne. -- Ustaw `agents.list[].skills: []`, aby nie mieć żadnych Skills. -- Niepusta lista `agents.list[].skills` jest ostatecznym zestawem dla tego agenta; nie jest scalana z wartościami domyślnymi. +- Ustaw `agents.list[].skills: []`, aby wyłączyć Skills. +- Niepusta lista `agents.list[].skills` jest końcowym zbiorem dla danego agenta; + nie jest łączona z wartościami domyślnymi. ### `agents.defaults.skipBootstrap` @@ -910,9 +911,9 @@ Wyłącza automatyczne tworzenie plików bootstrap workspace (`AGENTS.md`, `SOUL ### `agents.defaults.contextInjection` -Steruje tym, kiedy pliki bootstrap workspace są wstrzykiwane do system prompt. Domyślnie: `"always"`. +Steruje, kiedy pliki bootstrap workspace są wstrzykiwane do promptu systemowego. Domyślnie: `"always"`. -- `"continuation-skip"`: bezpieczne tury kontynuacyjne (po zakończonej odpowiedzi asystenta) pomijają ponowne wstrzykiwanie bootstrap workspace, zmniejszając rozmiar promptu. Uruchomienia heartbeat i ponowne próby po kompaktowaniu nadal przebudowują kontekst. +- `"continuation-skip"`: bezpieczne tury kontynuacji (po zakończonej odpowiedzi asystenta) pomijają ponowne wstrzykiwanie bootstrap workspace, zmniejszając rozmiar promptu. Uruchomienia heartbeat i ponowne próby po kompakcji nadal odbudowują kontekst. ```json5 { @@ -932,7 +933,7 @@ Maksymalna liczba znaków na plik bootstrap workspace przed obcięciem. Domyśln ### `agents.defaults.bootstrapTotalMaxChars` -Maksymalna łączna liczba znaków wstrzykiwanych ze wszystkich plików bootstrap workspace. Domyślnie: `150000`. +Maksymalna łączna liczba znaków wstrzykniętych ze wszystkich plików bootstrap workspace. Domyślnie: `150000`. ```json5 { @@ -942,10 +943,10 @@ Maksymalna łączna liczba znaków wstrzykiwanych ze wszystkich plików bootstra ### `agents.defaults.bootstrapPromptTruncationWarning` -Steruje tekstem ostrzeżenia widocznym dla agenta, gdy kontekst bootstrap jest obcięty. +Steruje widocznym dla agenta tekstem ostrzegawczym, gdy kontekst bootstrap jest obcinany. Domyślnie: `"once"`. -- `"off"`: nigdy nie wstrzykuje tekstu ostrzeżenia do system prompt. +- `"off"`: nigdy nie wstrzykuje tekstu ostrzeżenia do promptu systemowego. - `"once"`: wstrzykuje ostrzeżenie raz dla każdej unikalnej sygnatury obcięcia (zalecane). - `"always"`: wstrzykuje ostrzeżenie przy każdym uruchomieniu, gdy istnieje obcięcie. @@ -957,10 +958,10 @@ Domyślnie: `"once"`. ### `agents.defaults.imageMaxDimensionPx` -Maksymalny rozmiar w pikselach dla dłuższego boku obrazu w blokach obrazów transcript/tool przed wywołaniami do dostawcy. +Maksymalny rozmiar pikselowy dłuższego boku obrazu w blokach obrazu transcript/tool przed wywołaniami dostawcy. Domyślnie: `1200`. -Niższe wartości zwykle zmniejszają użycie tokenów vision i rozmiar payloadu żądania dla przebiegów z dużą liczbą zrzutów ekranu. +Niższe wartości zwykle zmniejszają użycie vision-tokenów i rozmiar ładunku żądania przy przebiegach z dużą liczbą zrzutów ekranu. Wyższe wartości zachowują więcej szczegółów wizualnych. ```json5 @@ -971,7 +972,7 @@ Wyższe wartości zachowują więcej szczegółów wizualnych. ### `agents.defaults.userTimezone` -Strefa czasowa dla kontekstu system prompt (nie dla znaczników czasu wiadomości). Wartość zapasowa pochodzi ze strefy czasowej hosta. +Strefa czasowa dla kontekstu promptu systemowego (nie dla znaczników czasu wiadomości). Wartość zapasowa to strefa czasowa hosta. ```json5 { @@ -981,7 +982,7 @@ Strefa czasowa dla kontekstu system prompt (nie dla znaczników czasu wiadomośc ### `agents.defaults.timeFormat` -Format czasu w system prompt. Domyślnie: `auto` (preferencja systemu operacyjnego). +Format czasu w prompcie systemowym. Domyślnie: `auto` (preferencje systemu operacyjnego). ```json5 { @@ -1019,7 +1020,7 @@ Format czasu w system prompt. Domyślnie: `auto` (preferencja systemu operacyjne primary: "anthropic/claude-opus-4-6", fallbacks: ["openai/gpt-5.4-mini"], }, - params: { cacheRetention: "long" }, // global default provider params + params: { cacheRetention: "long" }, // globalne domyślne parametry dostawcy pdfMaxBytesMb: 10, pdfMaxPages: 20, thinkingDefault: "low", @@ -1034,43 +1035,43 @@ Format czasu w system prompt. Domyślnie: `auto` (preferencja systemu operacyjne } ``` -- `model`: akceptuje albo ciąg znaków (`"provider/model"`), albo obiekt (`{ primary, fallbacks }`). +- `model`: akceptuje albo ciąg (`"provider/model"`), albo obiekt (`{ primary, fallbacks }`). - Forma ciągu ustawia tylko model główny. - - Forma obiektu ustawia model główny oraz uporządkowane modele zapasowe. -- `imageModel`: akceptuje albo ciąg znaków (`"provider/model"`), albo obiekt (`{ primary, fallbacks }`). + - Forma obiektu ustawia model główny oraz uporządkowane modele zapasowe failover. +- `imageModel`: akceptuje albo ciąg (`"provider/model"`), albo obiekt (`{ primary, fallbacks }`). - Używany przez ścieżkę narzędzia `image` jako konfiguracja modelu vision. - - Używany również jako routowanie zapasowe, gdy wybrany/domyslny model nie akceptuje wejścia obrazowego. -- `imageGenerationModel`: akceptuje albo ciąg znaków (`"provider/model"`), albo obiekt (`{ primary, fallbacks }`). - - Używany przez współdzieloną funkcję generowania obrazów i wszelkie przyszłe powierzchnie narzędzi/pluginów, które generują obrazy. + - Używany także jako routing zapasowy, gdy wybrany/domyslny model nie obsługuje wejścia obrazów. +- `imageGenerationModel`: akceptuje albo ciąg (`"provider/model"`), albo obiekt (`{ primary, fallbacks }`). + - Używany przez współdzieloną możliwość generowania obrazów i wszelkie przyszłe powierzchnie narzędzi/pluginów generujące obrazy. - Typowe wartości: `google/gemini-3.1-flash-image-preview` dla natywnego generowania obrazów Gemini, `fal/fal-ai/flux/dev` dla fal lub `openai/gpt-image-1` dla OpenAI Images. - - Jeśli wybierzesz bezpośrednio dostawcę/model, skonfiguruj też pasujące uwierzytelnienie/klucz API dostawcy (na przykład `GEMINI_API_KEY` lub `GOOGLE_API_KEY` dla `google/*`, `OPENAI_API_KEY` dla `openai/*`, `FAL_KEY` dla `fal/*`). - - Gdy jest pominięty, `image_generate` nadal może wywnioskować domyślnego dostawcę na podstawie uwierzytelnienia. Najpierw próbuje bieżącego domyślnego dostawcy, a potem pozostałych zarejestrowanych dostawców generowania obrazów w kolejności identyfikatorów dostawców. -- `musicGenerationModel`: akceptuje albo ciąg znaków (`"provider/model"`), albo obiekt (`{ primary, fallbacks }`). - - Używany przez współdzieloną funkcję generowania muzyki i wbudowane narzędzie `music_generate`. + - Jeśli wybierzesz bezpośrednio dostawcę/model, skonfiguruj też odpowiadające uwierzytelnianie/API key dostawcy (na przykład `GEMINI_API_KEY` lub `GOOGLE_API_KEY` dla `google/*`, `OPENAI_API_KEY` dla `openai/*`, `FAL_KEY` dla `fal/*`). + - Jeśli pominięte, `image_generate` nadal może wywnioskować domyślnego dostawcę z uwierzytelnianiem. Najpierw próbuje bieżącego domyślnego dostawcy, a następnie pozostałych zarejestrowanych dostawców generowania obrazów w kolejności identyfikatorów dostawców. +- `musicGenerationModel`: akceptuje albo ciąg (`"provider/model"`), albo obiekt (`{ primary, fallbacks }`). + - Używany przez współdzieloną możliwość generowania muzyki i wbudowane narzędzie `music_generate`. - Typowe wartości: `google/lyria-3-clip-preview`, `google/lyria-3-pro-preview` lub `minimax/music-2.5+`. - - Gdy jest pominięty, `music_generate` nadal może wywnioskować domyślnego dostawcę na podstawie uwierzytelnienia. Najpierw próbuje bieżącego domyślnego dostawcy, a potem pozostałych zarejestrowanych dostawców generowania muzyki w kolejności identyfikatorów dostawców. - - Jeśli wybierzesz bezpośrednio dostawcę/model, skonfiguruj też pasujące uwierzytelnienie/klucz API dostawcy. -- `videoGenerationModel`: akceptuje albo ciąg znaków (`"provider/model"`), albo obiekt (`{ primary, fallbacks }`). - - Używany przez współdzieloną funkcję generowania wideo i wbudowane narzędzie `video_generate`. + - Jeśli pominięte, `music_generate` nadal może wywnioskować domyślnego dostawcę z uwierzytelnianiem. Najpierw próbuje bieżącego domyślnego dostawcy, a następnie pozostałych zarejestrowanych dostawców generowania muzyki w kolejności identyfikatorów dostawców. + - Jeśli wybierzesz bezpośrednio dostawcę/model, skonfiguruj też odpowiadające uwierzytelnianie/API key dostawcy. +- `videoGenerationModel`: akceptuje albo ciąg (`"provider/model"`), albo obiekt (`{ primary, fallbacks }`). + - Używany przez współdzieloną możliwość generowania wideo i wbudowane narzędzie `video_generate`. - Typowe wartości: `qwen/wan2.6-t2v`, `qwen/wan2.6-i2v`, `qwen/wan2.6-r2v`, `qwen/wan2.6-r2v-flash` lub `qwen/wan2.7-r2v`. - - Gdy jest pominięty, `video_generate` nadal może wywnioskować domyślnego dostawcę na podstawie uwierzytelnienia. Najpierw próbuje bieżącego domyślnego dostawcy, a potem pozostałych zarejestrowanych dostawców generowania wideo w kolejności identyfikatorów dostawców. - - Jeśli wybierzesz bezpośrednio dostawcę/model, skonfiguruj też pasujące uwierzytelnienie/klucz API dostawcy. - - Dołączony dostawca generowania wideo Qwen obsługuje obecnie maksymalnie 1 wyjściowe wideo, 1 wejściowy obraz, 4 wejściowe wideo, czas trwania 10 sekund oraz opcje na poziomie dostawcy `size`, `aspectRatio`, `resolution`, `audio` i `watermark`. -- `pdfModel`: akceptuje albo ciąg znaków (`"provider/model"`), albo obiekt (`{ primary, fallbacks }`). - - Używany przez narzędzie `pdf` do routowania modelu. - - Gdy jest pominięty, narzędzie PDF wraca do `imageModel`, a następnie do rozwiązanego modelu sesji/domyslnego. -- `pdfMaxBytesMb`: domyślny limit rozmiaru PDF dla narzędzia `pdf`, gdy `maxBytesMb` nie jest przekazywane w czasie wywołania. -- `pdfMaxPages`: domyślna maksymalna liczba stron uwzględnianych przez zapasowy tryb ekstrakcji w narzędziu `pdf`. + - Jeśli pominięte, `video_generate` nadal może wywnioskować domyślnego dostawcę z uwierzytelnianiem. Najpierw próbuje bieżącego domyślnego dostawcy, a następnie pozostałych zarejestrowanych dostawców generowania wideo w kolejności identyfikatorów dostawców. + - Jeśli wybierzesz bezpośrednio dostawcę/model, skonfiguruj też odpowiadające uwierzytelnianie/API key dostawcy. + - Dołączony dostawca generowania wideo Qwen obsługuje obecnie maksymalnie 1 wyjściowe wideo, 1 wejściowy obraz, 4 wejściowe wideo, czas trwania 10 sekund oraz opcje dostawcy `size`, `aspectRatio`, `resolution`, `audio` i `watermark`. +- `pdfModel`: akceptuje albo ciąg (`"provider/model"`), albo obiekt (`{ primary, fallbacks }`). + - Używany przez narzędzie `pdf` do routingu modelu. + - Jeśli pominięte, narzędzie PDF wraca do `imageModel`, a następnie do rozstrzygniętego modelu sesji/domyslnego. +- `pdfMaxBytesMb`: domyślny limit rozmiaru PDF dla narzędzia `pdf`, gdy `maxBytesMb` nie jest przekazane przy wywołaniu. +- `pdfMaxPages`: domyślna maksymalna liczba stron brana pod uwagę przez tryb zapasowy ekstrakcji w narzędziu `pdf`. - `verboseDefault`: domyślny poziom verbose dla agentów. Wartości: `"off"`, `"on"`, `"full"`. Domyślnie: `"off"`. -- `elevatedDefault`: domyślny poziom elevated-output dla agentów. Wartości: `"off"`, `"on"`, `"ask"`, `"full"`. Domyślnie: `"on"`. -- `model.primary`: format `provider/model` (np. `openai/gpt-5.4`). Jeśli pominiesz dostawcę, OpenClaw najpierw próbuje aliasu, następnie unikalnego dopasowania skonfigurowanego dostawcy dla dokładnego identyfikatora modelu, a dopiero potem wraca do skonfigurowanego dostawcy domyślnego (przestarzałe zachowanie zgodności, więc preferuj jawne `provider/model`). Jeśli ten dostawca nie udostępnia już skonfigurowanego modelu domyślnego, OpenClaw wraca do pierwszego skonfigurowanego dostawcy/modelu zamiast zgłaszać nieaktualną wartość domyślną usuniętego dostawcy. -- `models`: skonfigurowany katalog modeli i allowlista dla `/model`. Każdy wpis może zawierać `alias` (skrót) oraz `params` (specyficzne dla dostawcy, np. `temperature`, `maxTokens`, `cacheRetention`, `context1m`). +- `elevatedDefault`: domyślny poziom wyjścia elevated dla agentów. Wartości: `"off"`, `"on"`, `"ask"`, `"full"`. Domyślnie: `"on"`. +- `model.primary`: format `provider/model` (np. `openai/gpt-5.4`). Jeśli pominiesz dostawcę, OpenClaw najpierw próbuje aliasu, potem unikalnego dopasowania dokładnego id modelu wśród skonfigurowanych dostawców, a dopiero na końcu wraca do skonfigurowanego domyślnego dostawcy (przestarzałe zachowanie zgodności, więc preferuj jawne `provider/model`). Jeśli ten dostawca nie udostępnia już skonfigurowanego modelu domyślnego, OpenClaw wraca do pierwszego skonfigurowanego dostawcy/modelu zamiast zgłaszać nieaktualną domyślną wartość usuniętego dostawcy. +- `models`: skonfigurowany katalog modeli i lista dozwolonych dla `/model`. Każdy wpis może zawierać `alias` (skrót) oraz `params` (specyficzne dla dostawcy, na przykład `temperature`, `maxTokens`, `cacheRetention`, `context1m`). - `params`: globalne domyślne parametry dostawcy stosowane do wszystkich modeli. Ustawiane w `agents.defaults.params` (np. `{ cacheRetention: "long" }`). -- Priorytet scalania `params` (konfiguracja): `agents.defaults.params` (globalna baza) jest nadpisywane przez `agents.defaults.models["provider/model"].params` (per model), a potem `agents.list[].params` (pasujący identyfikator agenta) nadpisuje po kluczu. Szczegóły w [Cache promptów](/pl/reference/prompt-caching). -- Zapisywacze konfiguracji, które modyfikują te pola (na przykład `/models set`, `/models set-image` oraz polecenia dodawania/usuwania fallbacków), zapisują kanoniczną formę obiektu i w miarę możliwości zachowują istniejące listy fallbacków. +- Priorytet scalania `params` (konfiguracja): `agents.defaults.params` (globalna baza) jest nadpisywane przez `agents.defaults.models["provider/model"].params` (per model), a następnie `agents.list[].params` (pasujący identyfikator agenta) nadpisuje po kluczu. Szczegóły: [Prompt Caching](/pl/reference/prompt-caching). +- Narzędzia zapisujące konfigurację, które mutują te pola (na przykład `/models set`, `/models set-image` i polecenia dodawania/usuwania zapasowych), zapisują kanoniczną formę obiektu i zachowują istniejące listy fallbacków, gdy to możliwe. - `maxConcurrent`: maksymalna liczba równoległych uruchomień agentów między sesjami (każda sesja nadal jest serializowana). Domyślnie: 4. -**Wbudowane skróty aliasów** (obowiązują tylko wtedy, gdy model znajduje się w `agents.defaults.models`): +**Wbudowane skróty aliasów** (obowiązują tylko wtedy, gdy model jest w `agents.defaults.models`): | Alias | Model | | ------------------- | -------------------------------------- | @@ -1083,15 +1084,15 @@ Format czasu w system prompt. Domyślnie: `auto` (preferencja systemu operacyjne | `gemini-flash` | `google/gemini-3-flash-preview` | | `gemini-flash-lite` | `google/gemini-3.1-flash-lite-preview` | -Twoje skonfigurowane aliasy zawsze mają pierwszeństwo przed domyślnymi. +Skonfigurowane aliasy zawsze mają pierwszeństwo przed domyślnymi. Modele Z.AI GLM-4.x automatycznie włączają tryb thinking, chyba że ustawisz `--thinking off` lub samodzielnie zdefiniujesz `agents.defaults.models["zai/"].params.thinking`. -Modele Z.AI domyślnie włączają `tool_stream` dla streamingu wywołań narzędzi. Ustaw `agents.defaults.models["zai/"].params.tool_stream` na `false`, aby to wyłączyć. +Modele Z.AI domyślnie włączają `tool_stream` dla strumieniowania wywołań narzędzi. Ustaw `agents.defaults.models["zai/"].params.tool_stream` na `false`, aby to wyłączyć. Modele Anthropic Claude 4.6 domyślnie używają thinking `adaptive`, gdy nie ustawiono jawnego poziomu thinking. ### `agents.defaults.cliBackends` -Opcjonalne backendy CLI dla awaryjnych przebiegów tylko tekstowych (bez wywołań narzędzi). Przydatne jako zapas, gdy dostawcy API zawodzą. +Opcjonalne backendy CLI dla tekstowych przebiegów zapasowych (bez wywołań narzędzi). Przydatne jako kopia zapasowa, gdy dostawcy API zawodzą. ```json5 { @@ -1119,9 +1120,9 @@ Opcjonalne backendy CLI dla awaryjnych przebiegów tylko tekstowych (bez wywoła } ``` -- Backendy CLI są zorientowane na tekst; narzędzia są zawsze wyłączone. -- Sesje są obsługiwane, gdy ustawiono `sessionArg`. -- Przekazywanie obrazów jest obsługiwane, gdy `imageArg` akceptuje ścieżki plików. +- Backendy CLI są przede wszystkim tekstowe; narzędzia są zawsze wyłączone. +- Sesje są obsługiwane, gdy ustawione jest `sessionArg`. +- Przekazywanie obrazów jest obsługiwane, gdy `imageArg` akceptuje ścieżki do plików. ### `agents.defaults.heartbeat` @@ -1132,16 +1133,16 @@ Okresowe uruchomienia heartbeat. agents: { defaults: { heartbeat: { - every: "30m", // 0m disables + every: "30m", // 0m wyłącza model: "openai/gpt-5.4-mini", includeReasoning: false, - lightContext: false, // default: false; true keeps only HEARTBEAT.md from workspace bootstrap files - isolatedSession: false, // default: false; true runs each heartbeat in a fresh session (no conversation history) + lightContext: false, // domyślnie: false; true zachowuje tylko HEARTBEAT.md z plików bootstrap workspace + isolatedSession: false, // domyślnie: false; true uruchamia każdy heartbeat w świeżej sesji (bez historii rozmowy) session: "main", to: "+15555550123", - directPolicy: "allow", // allow (default) | block - target: "none", // default: none | options: last | whatsapp | telegram | discord | ... - prompt: "Read HEARTBEAT.md if it exists...", + directPolicy: "allow", // allow (domyślnie) | block + target: "none", // domyślnie: none | opcje: last | whatsapp | telegram | discord | ... + prompt: "Przeczytaj HEARTBEAT.md, jeśli istnieje...", ackMaxChars: 300, suppressToolErrorWarnings: false, }, @@ -1150,13 +1151,13 @@ Okresowe uruchomienia heartbeat. } ``` -- `every`: ciąg czasu trwania (ms/s/m/h). Domyślnie: `30m` (uwierzytelnienie kluczem API) lub `1h` (uwierzytelnienie OAuth). Ustaw `0m`, aby wyłączyć. -- `suppressToolErrorWarnings`: gdy true, tłumi payloady ostrzeżeń o błędach narzędzi podczas uruchomień heartbeat. -- `directPolicy`: polityka dostarczania bezpośredniego/DM. `allow` (domyślnie) pozwala na dostarczanie bezpośrednio do celu. `block` tłumi dostarczanie bezpośrednio do celu i emituje `reason=dm-blocked`. -- `lightContext`: gdy true, uruchomienia heartbeat używają lekkiego kontekstu bootstrap i zachowują tylko `HEARTBEAT.md` z plików bootstrap workspace. -- `isolatedSession`: gdy true, każde uruchomienie heartbeat działa w nowej sesji bez wcześniejszej historii rozmowy. Ten sam wzorzec izolacji co `sessionTarget: "isolated"` w cronie. Zmniejsza koszt tokenów na heartbeat z około 100K do około 2-5K tokenów. -- Per agent: ustaw `agents.list[].heartbeat`. Gdy jakikolwiek agent definiuje `heartbeat`, heartbeat uruchamiane są **tylko dla tych agentów**. -- Heartbeat uruchamia pełne tury agenta — krótsze interwały zużywają więcej tokenów. +- `every`: ciąg czasu trwania (ms/s/m/h). Domyślnie: `30m` (uwierzytelnianie API-key) lub `1h` (uwierzytelnianie OAuth). Ustaw `0m`, aby wyłączyć. +- `suppressToolErrorWarnings`: gdy true, tłumi ładunki ostrzeżeń o błędach narzędzi podczas przebiegów heartbeat. +- `directPolicy`: zasada dostarczania bezpośredniego/DM. `allow` (domyślnie) pozwala na dostarczanie do celu bezpośredniego. `block` tłumi dostarczanie do celu bezpośredniego i emituje `reason=dm-blocked`. +- `lightContext`: gdy true, przebiegi heartbeat używają lekkiego kontekstu bootstrap i zachowują tylko `HEARTBEAT.md` z plików bootstrap workspace. +- `isolatedSession`: gdy true, każdy heartbeat działa w świeżej sesji bez wcześniejszej historii rozmowy. Ten sam wzorzec izolacji co cron `sessionTarget: "isolated"`. Zmniejsza koszt tokenów na heartbeat z ~100K do ~2-5K tokenów. +- Per agent: ustaw `agents.list[].heartbeat`. Gdy dowolny agent definiuje `heartbeat`, heartbeat uruchamiane są **tylko dla tych agentów**. +- Heartbeat uruchamiają pełne tury agenta — krótsze interwały zużywają więcej tokenów. ### `agents.defaults.compaction` @@ -1166,18 +1167,19 @@ Okresowe uruchomienia heartbeat. defaults: { compaction: { mode: "safeguard", // default | safeguard + provider: "my-provider", // id zarejestrowanego pluginu dostawcy kompakcji (opcjonalnie) timeoutSeconds: 900, reserveTokensFloor: 24000, identifierPolicy: "strict", // strict | off | custom - identifierInstructions: "Preserve deployment IDs, ticket IDs, and host:port pairs exactly.", // used when identifierPolicy=custom - postCompactionSections: ["Session Startup", "Red Lines"], // [] disables reinjection - model: "openrouter/anthropic/claude-sonnet-4-6", // optional compaction-only model override - notifyUser: true, // send a brief notice when compaction starts (default: false) + identifierInstructions: "Zachowaj dokładnie identyfikatory wdrożeń, identyfikatory zgłoszeń i pary host:port.", // używane, gdy identifierPolicy=custom + postCompactionSections: ["Session Startup", "Red Lines"], // [] wyłącza ponowne wstrzykiwanie + model: "openrouter/anthropic/claude-sonnet-4-6", // opcjonalne nadpisanie modelu tylko dla kompakcji + notifyUser: true, // wyślij krótkie powiadomienie, gdy rozpocznie się kompakcja (domyślnie: false) memoryFlush: { enabled: true, softThresholdTokens: 6000, - systemPrompt: "Session nearing compaction. Store durable memories now.", - prompt: "Write any lasting notes to memory/YYYY-MM-DD.md; reply with the exact silent token NO_REPLY if nothing to store.", + systemPrompt: "Sesja zbliża się do kompakcji. Zapisz teraz trwałe wspomnienia.", + prompt: "Zapisz wszelkie trwałe notatki do memory/YYYY-MM-DD.md; odpowiedz dokładnym cichym tokenem NO_REPLY, jeśli nie ma nic do zapisania.", }, }, }, @@ -1185,18 +1187,19 @@ Okresowe uruchomienia heartbeat. } ``` -- `mode`: `default` lub `safeguard` (sumaryzacja porcjowana dla długich historii). Zobacz [Kompaktowanie](/pl/concepts/compaction). -- `timeoutSeconds`: maksymalna liczba sekund dozwolona dla pojedynczej operacji kompaktowania, zanim OpenClaw ją przerwie. Domyślnie: `900`. -- `identifierPolicy`: `strict` (domyślnie), `off` lub `custom`. `strict` dodaje wbudowane wskazówki zachowania nieprzezroczystych identyfikatorów podczas sumaryzacji kompaktowania. -- `identifierInstructions`: opcjonalny niestandardowy tekst o zachowaniu identyfikatorów używany, gdy `identifierPolicy=custom`. -- `postCompactionSections`: opcjonalne nazwy sekcji H2/H3 z AGENTS.md do ponownego wstrzyknięcia po kompaktowaniu. Domyślnie `["Session Startup", "Red Lines"]`; ustaw `[]`, aby wyłączyć ponowne wstrzykiwanie. Gdy nie jest ustawione lub jawnie ustawione na tę domyślną parę, starsze nagłówki `Every Session`/`Safety` są również akceptowane jako zgodność wsteczna. -- `model`: opcjonalne nadpisanie `provider/model-id` tylko dla sumaryzacji kompaktowania. Użyj tego, gdy główna sesja ma pozostać przy jednym modelu, ale podsumowania kompaktowania mają działać na innym; gdy nieustawione, kompaktowanie używa głównego modelu sesji. -- `notifyUser`: gdy `true`, wysyła użytkownikowi krótkie powiadomienie, gdy rozpoczyna się kompaktowanie (na przykład „Compacting context...” ). Domyślnie wyłączone, aby kompaktowanie pozostawało ciche. -- `memoryFlush`: cicha tura agentowa przed automatycznym kompaktowaniem, aby zapisać trwałe wspomnienia. Pomijana, gdy workspace jest tylko do odczytu. +- `mode`: `default` lub `safeguard` (sumaryzacja porcjami dla długich historii). Zobacz [Compaction](/pl/concepts/compaction). +- `provider`: id zarejestrowanego pluginu dostawcy kompakcji. Gdy ustawione, wywoływane jest `summarize()` dostawcy zamiast wbudowanej sumaryzacji LLM. W przypadku błędu wraca do wbudowanej. Ustawienie dostawcy wymusza `mode: "safeguard"`. Zobacz [Compaction](/pl/concepts/compaction). +- `timeoutSeconds`: maksymalna liczba sekund dozwolona dla pojedynczej operacji kompakcji, zanim OpenClaw ją przerwie. Domyślnie: `900`. +- `identifierPolicy`: `strict` (domyślnie), `off` lub `custom`. `strict` poprzedza sumaryzację kompakcji wbudowaną instrukcją zachowania nieprzezroczystych identyfikatorów. +- `identifierInstructions`: opcjonalny niestandardowy tekst zachowania identyfikatorów używany, gdy `identifierPolicy=custom`. +- `postCompactionSections`: opcjonalne nazwy sekcji H2/H3 z AGENTS.md do ponownego wstrzyknięcia po kompakcji. Domyślnie `["Session Startup", "Red Lines"]`; ustaw `[]`, aby wyłączyć ponowne wstrzykiwanie. Gdy nieustawione lub jawnie ustawione na tę domyślną parę, starsze nagłówki `Every Session`/`Safety` są także akceptowane jako zapasowa zgodność. +- `model`: opcjonalne nadpisanie `provider/model-id` tylko dla sumaryzacji kompakcji. Użyj tego, gdy główna sesja ma zachować jeden model, ale podsumowania kompakcji mają działać na innym; gdy nieustawione, kompakcja używa modelu głównego sesji. +- `notifyUser`: gdy `true`, wysyła użytkownikowi krótkie powiadomienie przy rozpoczęciu kompakcji (na przykład „Kompaktowanie kontekstu...”). Domyślnie wyłączone, aby kompakcja była cicha. +- `memoryFlush`: cicha tura agentowa przed automatyczną kompakcją, aby zapisać trwałe wspomnienia. Pomijana, gdy workspace jest tylko do odczytu. ### `agents.defaults.contextPruning` -Przycina **stare wyniki narzędzi** z kontekstu w pamięci przed wysłaniem do LLM. **Nie** modyfikuje historii sesji na dysku. +Przycina **stare wyniki narzędzi** z kontekstu w pamięci przed wysłaniem do LLM. **Nie** modyfikuje historii sesji zapisanej na dysku. ```json5 { @@ -1204,13 +1207,13 @@ Przycina **stare wyniki narzędzi** z kontekstu w pamięci przed wysłaniem do L defaults: { contextPruning: { mode: "cache-ttl", // off | cache-ttl - ttl: "1h", // duration (ms/s/m/h), default unit: minutes + ttl: "1h", // czas trwania (ms/s/m/h), domyślna jednostka: minuty keepLastAssistants: 3, softTrimRatio: 0.3, hardClearRatio: 0.5, minPrunableToolChars: 50000, softTrim: { maxChars: 4000, headChars: 1500, tailChars: 1500 }, - hardClear: { enabled: true, placeholder: "[Old tool result content cleared]" }, + hardClear: { enabled: true, placeholder: "[Treść starego wyniku narzędzia została wyczyszczona]" }, tools: { deny: ["browser", "canvas"] }, }, }, @@ -1221,24 +1224,24 @@ Przycina **stare wyniki narzędzi** z kontekstu w pamięci przed wysłaniem do L - `mode: "cache-ttl"` włącza przebiegi przycinania. -- `ttl` określa, jak często przycinanie może zostać uruchomione ponownie (po ostatnim dotknięciu cache). -- Przycinanie najpierw miękko przycina zbyt duże wyniki narzędzi, a następnie twardo czyści starsze wyniki narzędzi, jeśli to konieczne. +- `ttl` kontroluje, jak często przycinanie może zostać uruchomione ponownie (po ostatnim dotknięciu cache). +- Przycinanie najpierw miękko skraca zbyt duże wyniki narzędzi, a następnie, jeśli potrzeba, twardo czyści starsze wyniki narzędzi. -**Miękkie przycięcie** zachowuje początek + koniec i wstawia `...` pośrodku. +**Soft-trim** zachowuje początek + koniec i wstawia `...` w środku. -**Twarde czyszczenie** zastępuje cały wynik narzędzia placeholderem. +**Hard-clear** zastępuje cały wynik narzędzia placeholderem. Uwagi: - Bloki obrazów nigdy nie są przycinane/czyszczone. -- Współczynniki są oparte na znakach (w przybliżeniu), a nie na dokładnej liczbie tokenów. +- Współczynniki są oparte na znakach (orientacyjnie), a nie na dokładnych liczbach tokenów. - Jeśli istnieje mniej niż `keepLastAssistants` wiadomości asystenta, przycinanie jest pomijane. -Szczegóły działania: [Przycinanie sesji](/pl/concepts/session-pruning). +Szczegóły zachowania: [Session Pruning](/pl/concepts/session-pruning). -### Block streaming +### Strumieniowanie blokowe ```json5 { @@ -1248,17 +1251,17 @@ Szczegóły działania: [Przycinanie sesji](/pl/concepts/session-pruning). blockStreamingBreak: "text_end", // text_end | message_end blockStreamingChunk: { minChars: 800, maxChars: 1200 }, blockStreamingCoalesce: { idleMs: 1000 }, - humanDelay: { mode: "natural" }, // off | natural | custom (use minMs/maxMs) + humanDelay: { mode: "natural" }, // off | natural | custom (użyj minMs/maxMs) }, }, } ``` - Kanały inne niż Telegram wymagają jawnego `*.blockStreaming: true`, aby włączyć odpowiedzi blokowe. -- Nadpisania kanału: `channels..blockStreamingCoalesce` (oraz warianty per konto). Signal/Slack/Discord/Google Chat domyślnie używają `minChars: 1500`. -- `humanDelay`: losowa przerwa między odpowiedziami blokowymi. `natural` = 800–2500 ms. Nadpisanie per agent: `agents.list[].humanDelay`. +- Nadpisania kanałów: `channels..blockStreamingCoalesce` (oraz warianty per konto). Signal/Slack/Discord/Google Chat domyślnie mają `minChars: 1500`. +- `humanDelay`: losowa pauza między odpowiedziami blokowymi. `natural` = 800–2500 ms. Nadpisanie per agent: `agents.list[].humanDelay`. -Szczegóły zachowania i dzielenia: [Streaming](/pl/concepts/streaming). +Szczegóły zachowania i porcjowania: [Streaming](/pl/concepts/streaming). ### Wskaźniki pisania @@ -1273,10 +1276,10 @@ Szczegóły zachowania i dzielenia: [Streaming](/pl/concepts/streaming). } ``` -- Domyślnie: `instant` dla czatów bezpośrednich/wzmianek, `message` dla grupowych czatów bez wzmianki. +- Domyślnie: `instant` dla czatów prywatnych/wzmianek, `message` dla niewspomnianych czatów grupowych. - Nadpisania per sesja: `session.typingMode`, `session.typingIntervalSeconds`. -Zobacz [Wskaźniki pisania](/pl/concepts/typing-indicators). +Zobacz [Typing Indicators](/pl/concepts/typing-indicators). @@ -1328,7 +1331,7 @@ Opcjonalny sandboxing dla osadzonego agenta. Pełny przewodnik: [Sandboxing](/pl identityFile: "~/.ssh/id_ed25519", certificateFile: "~/.ssh/id_ed25519-cert.pub", knownHostsFile: "~/.ssh/known_hosts", - // SecretRefs / inline contents also supported: + // Obsługiwane są też SecretRef / treści inline: // identityData: { source: "env", provider: "default", id: "SSH_IDENTITY" }, // certificateData: { source: "env", provider: "default", id: "SSH_CERTIFICATE" }, // knownHostsData: { source: "env", provider: "default", id: "SSH_KNOWN_HOSTS" }, @@ -1377,52 +1380,52 @@ Opcjonalny sandboxing dla osadzonego agenta. Pełny przewodnik: [Sandboxing](/pl } ``` - + **Backend:** -- `docker`: lokalny runtime Docker (domyślnie) -- `ssh`: ogólny zdalny runtime oparty na SSH -- `openshell`: runtime OpenShell +- `docker`: lokalne środowisko Docker (domyślnie) +- `ssh`: generyczne zdalne środowisko oparte na SSH +- `openshell`: środowisko OpenShell -Gdy wybrane jest `backend: "openshell"`, ustawienia specyficzne dla runtime przenoszą się do +Gdy wybrane jest `backend: "openshell"`, ustawienia specyficzne dla środowiska przenoszą się do `plugins.entries.openshell.config`. **Konfiguracja backendu SSH:** - `target`: cel SSH w formie `user@host[:port]` - `command`: polecenie klienta SSH (domyślnie: `ssh`) -- `workspaceRoot`: absolutny zdalny katalog główny używany dla workspace per zakres +- `workspaceRoot`: bezwzględny zdalny katalog główny używany dla workspace per zakres - `identityFile` / `certificateFile` / `knownHostsFile`: istniejące lokalne pliki przekazywane do OpenSSH -- `identityData` / `certificateData` / `knownHostsData`: zawartość inline lub SecretRef, którą OpenClaw materializuje do plików tymczasowych w runtime -- `strictHostKeyChecking` / `updateHostKeys`: parametry polityki kluczy hosta OpenSSH +- `identityData` / `certificateData` / `knownHostsData`: treści inline lub SecretRefs, które OpenClaw materializuje do plików tymczasowych w czasie działania +- `strictHostKeyChecking` / `updateHostKeys`: pokrętła polityki kluczy hosta OpenSSH **Priorytet uwierzytelniania SSH:** - `identityData` ma pierwszeństwo przed `identityFile` - `certificateData` ma pierwszeństwo przed `certificateFile` - `knownHostsData` ma pierwszeństwo przed `knownHostsFile` -- Wartości `*Data` oparte na SecretRef są rozwiązywane z aktywnej migawki runtime sekretów przed rozpoczęciem sesji sandbox +- Wartości `*Data` oparte na SecretRef są rozwiązywane z aktywnej migawki sekretów przed rozpoczęciem sesji sandboxa **Zachowanie backendu SSH:** -- zasiewa zdalny workspace raz po utworzeniu lub odtworzeniu +- inicjalizuje zdalny workspace raz po utworzeniu lub odtworzeniu - następnie utrzymuje zdalny workspace SSH jako kanoniczny - kieruje `exec`, narzędzia plikowe i ścieżki mediów przez SSH -- nie synchronizuje automatycznie zmian zdalnych z powrotem na hosta -- nie obsługuje kontenerów przeglądarki sandbox +- nie synchronizuje automatycznie zmian zdalnych z powrotem do hosta +- nie obsługuje kontenerów przeglądarki sandboxa **Dostęp do workspace:** -- `none`: workspace sandbox per zakres w `~/.openclaw/sandboxes` -- `ro`: workspace sandbox pod `/workspace`, workspace agenta montowany tylko do odczytu pod `/agent` +- `none`: workspace sandboxa per zakres pod `~/.openclaw/sandboxes` +- `ro`: workspace sandboxa pod `/workspace`, workspace agenta montowany tylko do odczytu pod `/agent` - `rw`: workspace agenta montowany do odczytu/zapisu pod `/workspace` **Zakres:** - `session`: kontener + workspace per sesja -- `agent`: jeden kontener + workspace na agenta (domyślnie) -- `shared`: współdzielony kontener i workspace (bez izolacji między sesjami) +- `agent`: jeden kontener + workspace per agent (domyślnie) +- `shared`: współdzielony kontener i workspace (brak izolacji między sesjami) **Konfiguracja pluginu OpenShell:** @@ -1437,10 +1440,10 @@ Gdy wybrane jest `backend: "openshell"`, ustawienia specyficzne dla runtime prze from: "openclaw", remoteWorkspaceDir: "/sandbox", remoteAgentWorkspaceDir: "/agent", - gateway: "lab", // optional - gatewayEndpoint: "https://lab.example", // optional - policy: "strict", // optional OpenShell policy id - providers: ["openai"], // optional + gateway: "lab", // opcjonalnie + gatewayEndpoint: "https://lab.example", // opcjonalnie + policy: "strict", // opcjonalny identyfikator polityki OpenShell + providers: ["openai"], // opcjonalnie autoProviders: true, timeoutSeconds: 120, }, @@ -1452,32 +1455,32 @@ Gdy wybrane jest `backend: "openshell"`, ustawienia specyficzne dla runtime prze **Tryb OpenShell:** -- `mirror`: zasiewa zdalny stan z lokalnego przed exec, synchronizuje z powrotem po exec; lokalny workspace pozostaje kanoniczny -- `remote`: zasiewa zdalny stan raz przy tworzeniu sandbox, następnie utrzymuje zdalny workspace jako kanoniczny +- `mirror`: inicjalizuj zdalnie z lokalnego przed exec, synchronizuj z powrotem po exec; lokalny workspace pozostaje kanoniczny +- `remote`: zainicjalizuj zdalnie raz przy tworzeniu sandboxa, a następnie utrzymuj zdalny workspace jako kanoniczny -W trybie `remote` lokalne edycje hosta wykonane poza OpenClaw nie są automatycznie synchronizowane do sandbox po kroku zasiewania. -Transport odbywa się przez SSH do sandbox OpenShell, ale plugin zarządza cyklem życia sandbox i opcjonalną synchronizacją mirror. +W trybie `remote` lokalne edycje hosta wykonane poza OpenClaw nie są automatycznie synchronizowane do sandboxa po kroku inicjalizacji. +Transport odbywa się przez SSH do sandboxa OpenShell, ale plugin zarządza cyklem życia sandboxa i opcjonalną synchronizacją mirror. -**`setupCommand`** uruchamia się raz po utworzeniu kontenera (przez `sh -lc`). Wymaga wychodzącego dostępu do sieci, zapisywalnego roota i użytkownika root. +**`setupCommand`** uruchamia się raz po utworzeniu kontenera (przez `sh -lc`). Wymaga wyjścia do sieci, zapisywalnego root i użytkownika root. **Kontenery domyślnie używają `network: "none"`** — ustaw `"bridge"` (lub własną sieć bridge), jeśli agent potrzebuje dostępu wychodzącego. `"host"` jest blokowane. `"container:"` jest domyślnie blokowane, chyba że jawnie ustawisz `sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true` (break-glass). -**Załączniki przychodzące** są stagingowane do `media/inbound/*` w aktywnym workspace. +**Przychodzące załączniki** są umieszczane w `media/inbound/*` w aktywnym workspace. -**`docker.binds`** montuje dodatkowe katalogi hosta; globalne i per-agent `binds` są scalane. +**`docker.binds`** montuje dodatkowe katalogi hosta; globalne i per-agent bindy są scalane. -**Sandboxed browser** (`sandbox.browser.enabled`): Chromium + CDP w kontenerze. URL noVNC jest wstrzykiwany do system prompt. Nie wymaga `browser.enabled` w `openclaw.json`. -Dostęp obserwatora noVNC domyślnie używa uwierzytelniania VNC, a OpenClaw emituje URL z krótkotrwałym tokenem (zamiast ujawniać hasło we współdzielonym URL). +**Sandboxed browser** (`sandbox.browser.enabled`): Chromium + CDP w kontenerze. URL noVNC jest wstrzykiwany do promptu systemowego. Nie wymaga `browser.enabled` w `openclaw.json`. +Dostęp obserwatora noVNC domyślnie używa uwierzytelniania VNC, a OpenClaw emituje URL z krótkotrwałym tokenem (zamiast ujawniać hasło we współdzielonym URL-u). -- `allowHostControl: false` (domyślnie) blokuje sesjom sandbox targetowanie przeglądarki hosta. +- `allowHostControl: false` (domyślnie) blokuje sesjom sandboxa kierowanie do przeglądarki hosta. - `network` domyślnie ma wartość `openclaw-sandbox-browser` (dedykowana sieć bridge). Ustaw `bridge` tylko wtedy, gdy jawnie chcesz globalnej łączności bridge. -- `cdpSourceRange` opcjonalnie ogranicza ruch przychodzący CDP na krawędzi kontenera do zakresu CIDR (na przykład `172.21.0.1/32`). -- `sandbox.browser.binds` montuje dodatkowe katalogi hosta tylko do kontenera przeglądarki sandbox. Gdy jest ustawione (w tym `[]`), zastępuje `docker.binds` dla kontenera przeglądarki. -- Domyślne flagi uruchamiania są zdefiniowane w `scripts/sandbox-browser-entrypoint.sh` i dostrojone dla hostów kontenerowych: +- `cdpSourceRange` opcjonalnie ogranicza wejście CDP na krawędzi kontenera do zakresu CIDR (na przykład `172.21.0.1/32`). +- `sandbox.browser.binds` montuje dodatkowe katalogi hosta tylko do kontenera przeglądarki sandboxa. Gdy ustawione (w tym `[]`), zastępuje `docker.binds` dla kontenera przeglądarki. +- Domyślne opcje uruchamiania są zdefiniowane w `scripts/sandbox-browser-entrypoint.sh` i dostrojone pod hosty kontenerowe: - `--remote-debugging-address=127.0.0.1` - - `--remote-debugging-port=` + - `--remote-debugging-port=` - `--user-data-dir=${HOME}/.chrome` - `--no-first-run` - `--no-default-browser-check` @@ -1496,24 +1499,24 @@ Dostęp obserwatora noVNC domyślnie używa uwierzytelniania VNC, a OpenClaw emi - `--disable-3d-apis`, `--disable-software-rasterizer` i `--disable-gpu` są domyślnie włączone i można je wyłączyć przez `OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0`, jeśli użycie WebGL/3D tego wymaga. - - `OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0` ponownie włącza rozszerzenia, jeśli Twój workflow - ich wymaga. + - `OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0` ponownie włącza rozszerzenia, jeśli od nich + zależy Twój przepływ pracy. - `--renderer-process-limit=2` można zmienić przez `OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=`; ustaw `0`, aby użyć domyślnego limitu procesów Chromium. - - oraz `--no-sandbox` i `--disable-setuid-sandbox`, gdy `noSandbox` jest włączone. - - Wartości domyślne są linią bazową obrazu kontenera; użyj niestandardowego obrazu przeglądarki z własnym + - plus `--no-sandbox` i `--disable-setuid-sandbox`, gdy `noSandbox` jest włączone. + - Domyślne wartości są bazą obrazu kontenera; użyj własnego obrazu przeglądarki z własnym entrypointem, aby zmienić domyślne ustawienia kontenera. -Sandboxing przeglądarki i `sandbox.docker.binds` są obecnie dostępne tylko dla Docker. +Sandboxing przeglądarki i `sandbox.docker.binds` są obecnie dostępne tylko dla Dockera. -Budowanie obrazów: +Zbuduj obrazy: ```bash -scripts/sandbox-setup.sh # main sandbox image -scripts/sandbox-browser-setup.sh # optional browser image +scripts/sandbox-setup.sh # główny obraz sandboxa +scripts/sandbox-browser-setup.sh # opcjonalny obraz przeglądarki ``` ### `agents.list` (nadpisania per agent) @@ -1525,18 +1528,18 @@ scripts/sandbox-browser-setup.sh # optional browser image { id: "main", default: true, - name: "Main Agent", + name: "Główny agent", workspace: "~/.openclaw/workspace", agentDir: "~/.openclaw/agents/main/agent", - model: "anthropic/claude-opus-4-6", // or { primary, fallbacks } - thinkingDefault: "high", // per-agent thinking level override - reasoningDefault: "on", // per-agent reasoning visibility override - fastModeDefault: false, // per-agent fast mode override - params: { cacheRetention: "none" }, // overrides matching defaults.models params by key - skills: ["docs-search"], // replaces agents.defaults.skills when set + model: "anthropic/claude-opus-4-6", // lub { primary, fallbacks } + thinkingDefault: "high", // nadpisanie domyślnego poziomu thinking per agent + reasoningDefault: "on", // nadpisanie domyślnej widoczności reasoning per agent + fastModeDefault: false, // nadpisanie trybu szybkiego per agent + params: { cacheRetention: "none" }, // nadpisuje params z matching defaults.models po kluczu + skills: ["docs-search"], // zastępuje agents.defaults.skills, gdy ustawione identity: { name: "Samantha", - theme: "helpful sloth", + theme: "pomocny leniwiec", emoji: "🦥", avatar: "avatars/samantha.png", }, @@ -1565,25 +1568,25 @@ scripts/sandbox-browser-setup.sh # optional browser image ``` - `id`: stabilny identyfikator agenta (wymagany). -- `default`: gdy ustawiono wiele, wygrywa pierwszy (logowane jest ostrzeżenie). Jeśli żaden nie jest ustawiony, domyślny jest pierwszy wpis listy. +- `default`: gdy ustawionych jest wiele, wygrywa pierwszy (logowane jest ostrzeżenie). Jeśli żaden nie jest ustawiony, domyślny jest pierwszy wpis listy. - `model`: forma ciągu nadpisuje tylko `primary`; forma obiektu `{ primary, fallbacks }` nadpisuje oba (`[]` wyłącza globalne fallbacki). Zadania cron, które nadpisują tylko `primary`, nadal dziedziczą domyślne fallbacki, chyba że ustawisz `fallbacks: []`. -- `params`: parametry strumienia per agent scalane na wybranym wpisie modelu w `agents.defaults.models`. Użyj tego do nadpisań specyficznych dla agenta, takich jak `cacheRetention`, `temperature` lub `maxTokens`, bez duplikowania całego katalogu modeli. -- `skills`: opcjonalna allowlista Skills per agent. Jeśli pominięta, agent dziedziczy `agents.defaults.skills`, gdy jest ustawione; jawna lista zastępuje wartości domyślne zamiast je scalać, a `[]` oznacza brak Skills. -- `thinkingDefault`: opcjonalny domyślny poziom thinking per agent (`off | minimal | low | medium | high | xhigh | adaptive`). Nadpisuje `agents.defaults.thinkingDefault` dla tego agenta, gdy nie jest ustawione żadne nadpisanie per wiadomość lub per sesja. -- `reasoningDefault`: opcjonalna domyślna widoczność reasoning per agent (`on | off | stream`). Stosowana, gdy nie jest ustawione żadne nadpisanie reasoning per wiadomość lub per sesja. -- `fastModeDefault`: opcjonalna domyślna wartość fast mode per agent (`true | false`). Stosowana, gdy nie jest ustawione żadne nadpisanie fast-mode per wiadomość lub per sesja. -- `runtime`: opcjonalny deskryptor runtime per agent. Użyj `type: "acp"` z domyślnymi `runtime.acp` (`agent`, `backend`, `mode`, `cwd`), gdy agent ma domyślnie używać sesji harness ACP. -- `identity.avatar`: ścieżka względna do workspace, URL `http(s)` lub URI `data:`. +- `params`: parametry strumienia per agent scalane nad wybranym wpisem modelu w `agents.defaults.models`. Użyj tego do nadpisań specyficznych dla agenta, takich jak `cacheRetention`, `temperature` lub `maxTokens`, bez duplikowania całego katalogu modeli. +- `skills`: opcjonalna lista dozwolonych Skills per agent. Jeśli pominięta, agent dziedziczy `agents.defaults.skills`, gdy są ustawione; jawna lista zastępuje wartości domyślne zamiast się z nimi łączyć, a `[]` oznacza brak Skills. +- `thinkingDefault`: opcjonalny domyślny poziom thinking per agent (`off | minimal | low | medium | high | xhigh | adaptive`). Nadpisuje `agents.defaults.thinkingDefault` dla tego agenta, gdy nie ma nadpisania per wiadomość ani per sesja. +- `reasoningDefault`: opcjonalna domyślna widoczność reasoning per agent (`on | off | stream`). Stosowana, gdy nie ma nadpisania reasoning per wiadomość ani per sesja. +- `fastModeDefault`: opcjonalna domyślna wartość trybu szybkiego per agent (`true | false`). Stosowana, gdy nie ma nadpisania trybu szybkiego per wiadomość ani per sesja. +- `runtime`: opcjonalny deskryptor runtime per agent. Użyj `type: "acp"` z domyślnymi wartościami `runtime.acp` (`agent`, `backend`, `mode`, `cwd`), gdy agent ma domyślnie korzystać z sesji harness ACP. +- `identity.avatar`: ścieżka względna względem workspace, URL `http(s)` lub URI `data:`. - `identity` wyprowadza wartości domyślne: `ackReaction` z `emoji`, `mentionPatterns` z `name`/`emoji`. -- `subagents.allowAgents`: allowlista identyfikatorów agentów dla `sessions_spawn` (`["*"]` = dowolny; domyślnie: tylko ten sam agent). -- Ochrona dziedziczenia sandbox: jeśli sesja żądająca jest w sandbox, `sessions_spawn` odrzuca cele, które uruchomiłyby się poza sandboxem. +- `subagents.allowAgents`: lista dozwolonych identyfikatorów agentów dla `sessions_spawn` (`["*"]` = dowolny; domyślnie: tylko ten sam agent). +- Ochrona dziedziczenia sandboxa: jeśli sesja żądająca jest sandboxowana, `sessions_spawn` odrzuca cele, które działałyby bez sandboxa. - `subagents.requireAgentId`: gdy true, blokuje wywołania `sessions_spawn`, które pomijają `agentId` (wymusza jawny wybór profilu; domyślnie: false). --- -## Routowanie wielu agentów +## Routing wieloagentowy -Uruchamiaj wielu izolowanych agentów w jednym Gateway. Zobacz [Wiele agentów](/pl/concepts/multi-agent). +Uruchamiaj wiele izolowanych agentów w jednej bramie. Zobacz [Multi-Agent](/pl/concepts/multi-agent). ```json5 { @@ -1602,12 +1605,12 @@ Uruchamiaj wielu izolowanych agentów w jednym Gateway. Zobacz [Wiele agentów]( ### Pola dopasowania powiązań -- `type` (opcjonalnie): `route` dla normalnego routowania (brak typu domyślnie oznacza route), `acp` dla trwałych powiązań konwersacji ACP. +- `type` (opcjonalnie): `route` dla zwykłego routingu (brak type domyślnie oznacza route), `acp` dla trwałych powiązań konwersacji ACP. - `match.channel` (wymagane) - `match.accountId` (opcjonalnie; `*` = dowolne konto; pominięte = konto domyślne) - `match.peer` (opcjonalnie; `{ kind: direct|group|channel, id }`) - `match.guildId` / `match.teamId` (opcjonalnie; specyficzne dla kanału) -- `acp` (opcjonalnie; tylko dla wpisów `type: "acp"`): `{ mode, label, cwd, backend }` +- `acp` (opcjonalnie; tylko dla `type: "acp"`): `{ mode, label, cwd, backend }` **Deterministyczna kolejność dopasowania:** @@ -1615,16 +1618,16 @@ Uruchamiaj wielu izolowanych agentów w jednym Gateway. Zobacz [Wiele agentów]( 2. `match.guildId` 3. `match.teamId` 4. `match.accountId` (dokładne, bez peer/guild/team) -5. `match.accountId: "*"` (na cały kanał) -6. Domyślny agent +5. `match.accountId: "*"` (w całym kanale) +6. Agent domyślny W obrębie każdego poziomu wygrywa pierwszy pasujący wpis `bindings`. -Dla wpisów `type: "acp"` OpenClaw rozwiązuje po dokładnej tożsamości konwersacji (`match.channel` + konto + `match.peer.id`) i nie używa powyższej kolejności poziomów route. +Dla wpisów `type: "acp"` OpenClaw rozstrzyga na podstawie dokładnej tożsamości konwersacji (`match.channel` + konto + `match.peer.id`) i nie używa powyższej warstwowej kolejności routingu. ### Profile dostępu per agent - + ```json5 { @@ -1642,7 +1645,7 @@ Dla wpisów `type: "acp"` OpenClaw rozwiązuje po dokładnej tożsamości konwer - + ```json5 { @@ -1717,7 +1720,7 @@ Dla wpisów `type: "acp"` OpenClaw rozwiązuje po dokładnej tożsamości konwer -Szczegóły priorytetów: [Sandbox i narzędzia dla wielu agentów](/pl/tools/multi-agent-sandbox-tools). +Szczegóły pierwszeństwa: [Multi-Agent Sandbox & Tools](/pl/tools/multi-agent-sandbox-tools). --- @@ -1743,22 +1746,22 @@ Szczegóły priorytetów: [Sandbox i narzędzia dla wielu agentów](/pl/tools/mu }, resetTriggers: ["/new", "/reset"], store: "~/.openclaw/agents/{agentId}/sessions/sessions.json", - parentForkMaxTokens: 100000, // skip parent-thread fork above this token count (0 disables) + parentForkMaxTokens: 100000, // pomiń rozwidlenie wątku nadrzędnego powyżej tej liczby tokenów (0 wyłącza) maintenance: { mode: "warn", // warn | enforce pruneAfter: "30d", maxEntries: 500, rotateBytes: "10mb", - resetArchiveRetention: "30d", // duration or false - maxDiskBytes: "500mb", // optional hard budget - highWaterBytes: "400mb", // optional cleanup target + resetArchiveRetention: "30d", // czas trwania lub false + maxDiskBytes: "500mb", // opcjonalny twardy budżet + highWaterBytes: "400mb", // opcjonalny cel po czyszczeniu }, threadBindings: { enabled: true, - idleHours: 24, // default inactivity auto-unfocus in hours (`0` disables) - maxAgeHours: 0, // default hard max age in hours (`0` disables) + idleHours: 24, // domyślna automatyczna utrata focusa po bezczynności w godzinach (`0` wyłącza) + maxAgeHours: 0, // domyślny sztywny maksymalny wiek w godzinach (`0` wyłącza) }, - mainKey: "main", // legacy (runtime always uses "main") + mainKey: "main", // starsze pole (czas działania zawsze używa "main") agentToAgent: { maxPingPongTurns: 5 }, sendPolicy: { rules: [{ action: "deny", match: { channel: "discord", chatType: "group" } }], @@ -1771,34 +1774,34 @@ Szczegóły priorytetów: [Sandbox i narzędzia dla wielu agentów](/pl/tools/mu - **`scope`**: bazowa strategia grupowania sesji dla kontekstów czatów grupowych. - - `per-sender` (domyślnie): każdy nadawca otrzymuje izolowaną sesję w kontekście kanału. - - `global`: wszyscy uczestnicy w kontekście kanału współdzielą jedną sesję (używaj tylko, gdy zamierzony jest wspólny kontekst). + - `per-sender` (domyślnie): każdy nadawca dostaje izolowaną sesję w obrębie kontekstu kanału. + - `global`: wszyscy uczestnicy w kontekście kanału współdzielą jedną sesję (używaj tylko wtedy, gdy współdzielony kontekst jest zamierzony). - **`dmScope`**: sposób grupowania DM. - - `main`: wszystkie DM współdzielą sesję główną. + - `main`: wszystkie DM współdzielą główną sesję. - `per-peer`: izolacja według identyfikatora nadawcy między kanałami. - - `per-channel-peer`: izolacja per kanał + nadawca (zalecane dla skrzynek odbiorczych wieloużytkownikowych). + - `per-channel-peer`: izolacja per kanał + nadawca (zalecane dla skrzynek wieloużytkownikowych). - `per-account-channel-peer`: izolacja per konto + kanał + nadawca (zalecane dla wielu kont). -- **`identityLinks`**: mapuje identyfikatory kanoniczne na peery z prefiksem dostawcy do współdzielenia sesji między kanałami. -- **`reset`**: podstawowa polityka resetu. `daily` resetuje o `atHour` czasu lokalnego; `idle` resetuje po `idleMinutes`. Gdy skonfigurowane są oba, wygrywa ten, który wygaśnie wcześniej. -- **`resetByType`**: nadpisania per typ (`direct`, `group`, `thread`). Starsze `dm` jest akceptowane jako alias dla `direct`. -- **`parentForkMaxTokens`**: maksymalne `totalTokens` sesji nadrzędnej dozwolone przy tworzeniu rozwidlonej sesji wątku (domyślnie `100000`). - - Jeśli `totalTokens` rodzica przekracza tę wartość, OpenClaw rozpoczyna nową sesję wątku zamiast dziedziczyć historię transcriptu rodzica. - - Ustaw `0`, aby wyłączyć tę ochronę i zawsze pozwalać na rozwidlenie od rodzica. -- **`mainKey`**: starsze pole. Runtime zawsze używa teraz `"main"` dla głównego bucketu czatu bezpośredniego. +- **`identityLinks`**: mapuje kanoniczne identyfikatory na peerów z prefiksem dostawcy dla współdzielenia sesji między kanałami. +- **`reset`**: główna zasada resetu. `daily` resetuje o `atHour` czasu lokalnego; `idle` resetuje po `idleMinutes`. Gdy skonfigurowane są oba, wygrywa to, co wygaśnie wcześniej. +- **`resetByType`**: nadpisania per typ (`direct`, `group`, `thread`). Starsze `dm` akceptowane jako alias `direct`. +- **`parentForkMaxTokens`**: maksymalna liczba `totalTokens` sesji nadrzędnej dozwolona przy tworzeniu rozwidlonej sesji wątku (domyślnie `100000`). + - Jeśli `totalTokens` sesji nadrzędnej przekracza tę wartość, OpenClaw uruchamia świeżą sesję wątku zamiast dziedziczyć historię transkryptu sesji nadrzędnej. + - Ustaw `0`, aby wyłączyć ten mechanizm ochronny i zawsze zezwalać na rozwidlenie z sesji nadrzędnej. +- **`mainKey`**: starsze pole. Czas działania zawsze używa teraz `"main"` dla głównego koszyka czatu prywatnego. - **`agentToAgent.maxPingPongTurns`**: maksymalna liczba tur odpowiedzi zwrotnych między agentami podczas wymian agent-agent (liczba całkowita, zakres: `0`–`5`). `0` wyłącza łańcuchowanie ping-pong. -- **`sendPolicy`**: dopasowanie według `channel`, `chatType` (`direct|group|channel`, ze starszym aliasem `dm`), `keyPrefix` lub `rawKeyPrefix`. Pierwszy deny wygrywa. +- **`sendPolicy`**: dopasowanie po `channel`, `chatType` (`direct|group|channel`, ze starszym aliasem `dm`), `keyPrefix` lub `rawKeyPrefix`. Pierwsze deny wygrywa. - **`maintenance`**: czyszczenie magazynu sesji + kontrola retencji. - `mode`: `warn` emituje tylko ostrzeżenia; `enforce` stosuje czyszczenie. - - `pruneAfter`: granica wieku dla starych wpisów (domyślnie `30d`). + - `pruneAfter`: granica wieku dla nieaktualnych wpisów (domyślnie `30d`). - `maxEntries`: maksymalna liczba wpisów w `sessions.json` (domyślnie `500`). - `rotateBytes`: obraca `sessions.json`, gdy przekroczy ten rozmiar (domyślnie `10mb`). - - `resetArchiveRetention`: retencja dla archiwów transcriptów `*.reset.`. Domyślnie przyjmuje `pruneAfter`; ustaw `false`, aby wyłączyć. - - `maxDiskBytes`: opcjonalny twardy budżet dyskowy dla katalogu sesji. W trybie `warn` loguje ostrzeżenia; w trybie `enforce` najpierw usuwa najstarsze artefakty/sesje. - - `highWaterBytes`: opcjonalny cel po czyszczeniu budżetu. Domyślnie `80%` `maxDiskBytes`. -- **`threadBindings`**: globalne ustawienia domyślne dla funkcji sesji związanych z wątkami. + - `resetArchiveRetention`: retencja dla archiwów transkryptów `*.reset.`. Domyślnie taka sama jak `pruneAfter`; ustaw `false`, aby wyłączyć. + - `maxDiskBytes`: opcjonalny budżet dyskowy katalogu sesji. W trybie `warn` loguje ostrzeżenia; w trybie `enforce` najpierw usuwa najstarsze artefakty/sesje. + - `highWaterBytes`: opcjonalny cel po czyszczeniu budżetu. Domyślnie `80%` z `maxDiskBytes`. +- **`threadBindings`**: globalne wartości domyślne dla funkcji sesji związanych z wątkami. - `enabled`: główny domyślny przełącznik (dostawcy mogą nadpisywać; Discord używa `channels.discord.threadBindings.enabled`) - - `idleHours`: domyślne automatyczne odfokusowanie po bezczynności w godzinach (`0` wyłącza; dostawcy mogą nadpisywać) - - `maxAgeHours`: domyślny twardy maksymalny wiek w godzinach (`0` wyłącza; dostawcy mogą nadpisywać) + - `idleHours`: domyślna automatyczna utrata focusa po bezczynności w godzinach (`0` wyłącza; dostawcy mogą nadpisywać) + - `maxAgeHours`: domyślny sztywny maksymalny wiek w godzinach (`0` wyłącza; dostawcy mogą nadpisywać) @@ -1809,7 +1812,7 @@ Szczegóły priorytetów: [Sandbox i narzędzia dla wielu agentów](/pl/tools/mu ```json5 { messages: { - responsePrefix: "🦞", // or "auto" + responsePrefix: "🦞", // lub "auto" ackReaction: "👀", ackReactionScope: "group-mentions", // group-mentions | group-all | direct | all removeAckAfterReply: false, @@ -1824,7 +1827,7 @@ Szczegóły priorytetów: [Sandbox i narzędzia dla wielu agentów](/pl/tools/mu }, }, inbound: { - debounceMs: 2000, // 0 disables + debounceMs: 2000, // 0 wyłącza byChannel: { whatsapp: 5000, slack: 1500, @@ -1838,34 +1841,34 @@ Szczegóły priorytetów: [Sandbox i narzędzia dla wielu agentów](/pl/tools/mu Nadpisania per kanał/konto: `channels..responsePrefix`, `channels..accounts..responsePrefix`. -Rozwiązywanie (wygrywa najbardziej specyficzne): konto → kanał → globalne. `""` wyłącza i zatrzymuje kaskadę. `"auto"` wyprowadza `[{identity.name}]`. +Rozstrzyganie (wygrywa najbardziej szczegółowe): konto → kanał → globalne. `""` wyłącza i zatrzymuje kaskadę. `"auto"` wyprowadza `[{identity.name}]`. **Zmienne szablonu:** -| Zmienna | Opis | Przykład | -| ---------------- | ----------------------- | --------------------------- | -| `{model}` | Krótka nazwa modelu | `claude-opus-4-6` | +| Zmienna | Opis | Przykład | +| ---------------- | ---------------------- | --------------------------- | +| `{model}` | Krótka nazwa modelu | `claude-opus-4-6` | | `{modelFull}` | Pełny identyfikator modelu | `anthropic/claude-opus-4-6` | -| `{provider}` | Nazwa dostawcy | `anthropic` | -| `{thinkingLevel}` | Bieżący poziom thinking | `high`, `low`, `off` | -| `{identity.name}` | Nazwa tożsamości agenta | (to samo co `"auto"`) | +| `{provider}` | Nazwa dostawcy | `anthropic` | +| `{thinkingLevel}` | Bieżący poziom thinking | `high`, `low`, `off` | +| `{identity.name}` | Nazwa tożsamości agenta | (to samo co `"auto"`) | -Zmienne są nieczułe na wielkość liter. `{think}` jest aliasem dla `{thinkingLevel}`. +Zmienne są niewrażliwe na wielkość liter. `{think}` jest aliasem dla `{thinkingLevel}`. -### Reakcja potwierdzająca +### Reakcja ack - Domyślnie używa `identity.emoji` aktywnego agenta, w przeciwnym razie `"👀"`. Ustaw `""`, aby wyłączyć. - Nadpisania per kanał: `channels..ackReaction`, `channels..accounts..ackReaction`. -- Kolejność rozwiązywania: konto → kanał → `messages.ackReaction` → wartość zapasowa z identity. +- Kolejność rozstrzygania: konto → kanał → `messages.ackReaction` → zapasowa wartość z tożsamości. - Zakres: `group-mentions` (domyślnie), `group-all`, `direct`, `all`. - `removeAckAfterReply`: usuwa ack po odpowiedzi w Slack, Discord i Telegram. -- `messages.statusReactions.enabled`: włącza reakcje statusowe cyklu życia w Slack, Discord i Telegram. - W Slack i Discord brak ustawienia zachowuje reakcje statusowe włączone, gdy aktywne są reakcje ack. - W Telegram ustaw jawnie `true`, aby włączyć reakcje statusowe cyklu życia. +- `messages.statusReactions.enabled`: włącza reakcje statusu cyklu życia w Slack, Discord i Telegram. + W Slacku i Discordzie brak ustawienia zachowuje reakcje statusu włączone, gdy aktywne są reakcje ack. + W Telegramie ustaw to jawnie na `true`, aby włączyć reakcje statusu cyklu życia. -### Debounce wejścia +### Debounce przychodzących wiadomości -Łączy szybkie wiadomości tekstowe od tego samego nadawcy w jedną turę agenta. Media/załączniki wymuszają natychmiastowe opróżnienie. Polecenia sterujące omijają debouncing. +Łączy szybkie wiadomości tekstowe od tego samego nadawcy w jedną turę agenta. Media/załączniki opróżniają kolejkę natychmiast. Polecenia sterujące omijają debounce. ### TTS (text-to-speech) @@ -1908,18 +1911,18 @@ Zmienne są nieczułe na wielkość liter. `{think}` jest aliasem dla `{thinking } ``` -- `auto` kontroluje automatyczny TTS. `/tts off|always|inbound|tagged` nadpisuje per sesja. -- `summaryModel` nadpisuje `agents.defaults.model.primary` dla automatycznego podsumowania. -- `modelOverrides` jest domyślnie włączone; `modelOverrides.allowProvider` domyślnie ma wartość `false` (opt-in). -- Klucze API korzystają z wartości zapasowych `ELEVENLABS_API_KEY`/`XI_API_KEY` i `OPENAI_API_KEY`. -- `openai.baseUrl` nadpisuje endpoint OpenAI TTS. Kolejność rozwiązywania to konfiguracja, potem `OPENAI_TTS_BASE_URL`, a następnie `https://api.openai.com/v1`. -- Gdy `openai.baseUrl` wskazuje endpoint inny niż OpenAI, OpenClaw traktuje go jako serwer TTS kompatybilny z OpenAI i łagodzi walidację modelu/głosu. +- `auto` steruje auto-TTS. `/tts off|always|inbound|tagged` nadpisuje to per sesja. +- `summaryModel` nadpisuje `agents.defaults.model.primary` dla auto-podsumowania. +- `modelOverrides` jest domyślnie włączone; `modelOverrides.allowProvider` domyślnie ma `false` (opt-in). +- Klucze API wracają do `ELEVENLABS_API_KEY`/`XI_API_KEY` oraz `OPENAI_API_KEY`. +- `openai.baseUrl` nadpisuje endpoint OpenAI TTS. Kolejność rozstrzygania to: konfiguracja, potem `OPENAI_TTS_BASE_URL`, potem `https://api.openai.com/v1`. +- Gdy `openai.baseUrl` wskazuje na endpoint inny niż OpenAI, OpenClaw traktuje go jako serwer TTS kompatybilny z OpenAI i łagodzi walidację modelu/głosu. --- ## Talk -Domyślne ustawienia trybu Talk (macOS/iOS/Android). +Domyślne ustawienia dla trybu Talk (macOS/iOS/Android). ```json5 { @@ -1943,13 +1946,13 @@ Domyślne ustawienia trybu Talk (macOS/iOS/Android). } ``` -- `talk.provider` musi odpowiadać kluczowi w `talk.providers`, gdy skonfigurowano wielu dostawców Talk. -- Starsze płaskie klucze Talk (`talk.voiceId`, `talk.voiceAliases`, `talk.modelId`, `talk.outputFormat`, `talk.apiKey`) służą tylko zgodności i są automatycznie migrowane do `talk.providers.`. -- Identyfikatory głosów korzystają z wartości zapasowych `ELEVENLABS_VOICE_ID` lub `SAG_VOICE_ID`. -- `providers.*.apiKey` akceptuje jawne ciągi znaków lub obiekty SecretRef. -- Wartość zapasowa `ELEVENLABS_API_KEY` jest stosowana tylko wtedy, gdy nie skonfigurowano klucza API Talk. +- `talk.provider` musi pasować do klucza w `talk.providers`, gdy skonfigurowanych jest wielu dostawców Talk. +- Starsze płaskie klucze Talk (`talk.voiceId`, `talk.voiceAliases`, `talk.modelId`, `talk.outputFormat`, `talk.apiKey`) są przeznaczone wyłącznie dla zgodności i są automatycznie migrowane do `talk.providers.`. +- Identyfikatory głosów wracają do `ELEVENLABS_VOICE_ID` lub `SAG_VOICE_ID`. +- `providers.*.apiKey` akceptuje zwykłe ciągi znaków lub obiekty SecretRef. +- Zapasowe `ELEVENLABS_API_KEY` ma zastosowanie tylko wtedy, gdy nie skonfigurowano klucza API Talk. - `providers.*.voiceAliases` pozwala dyrektywom Talk używać przyjaznych nazw. -- `silenceTimeoutMs` określa, jak długo tryb Talk czeka po ciszy użytkownika, zanim wyśle transkrypt. Brak ustawienia zachowuje domyślne okno pauzy platformy (`700 ms na macOS i Android, 900 ms na iOS`). +- `silenceTimeoutMs` określa, jak długo tryb Talk czeka po ciszy użytkownika, zanim wyśle transkrypt. Brak ustawienia zachowuje domyślne okno pauzy platformy (`700 ms na macOS i Androidzie, 900 ms na iOS`). --- @@ -1957,37 +1960,37 @@ Domyślne ustawienia trybu Talk (macOS/iOS/Android). ### Profile narzędzi -`tools.profile` ustawia bazową allowlistę przed `tools.allow`/`tools.deny`: +`tools.profile` ustawia bazową listę dozwolonych przed `tools.allow`/`tools.deny`: -Lokalny onboarding domyślnie ustawia `tools.profile: "coding"` w nowych lokalnych konfiguracjach, gdy nie jest ustawione (istniejące jawne profile są zachowywane). +Lokalny onboarding domyślnie ustawia nowe lokalne konfiguracje na `tools.profile: "coding"`, gdy nie jest ustawione (istniejące jawne profile są zachowywane). | Profil | Zawiera | | ----------- | ------------------------------------------------------------------------------------------------------------------------------- | | `minimal` | tylko `session_status` | | `coding` | `group:fs`, `group:runtime`, `group:web`, `group:sessions`, `group:memory`, `cron`, `image`, `image_generate`, `video_generate` | | `messaging` | `group:messaging`, `sessions_list`, `sessions_history`, `sessions_send`, `session_status` | -| `full` | Bez ograniczeń (to samo co brak ustawienia) | +| `full` | Brak ograniczeń (to samo co brak ustawienia) | ### Grupy narzędzi -| Grupa | Narzędzia | -| ----------------- | ----------------------------------------------------------------------------------------------------------------------- | -| `group:runtime` | `exec`, `process`, `code_execution` (`bash` jest akceptowany jako alias dla `exec`) | -| `group:fs` | `read`, `write`, `edit`, `apply_patch` | -| `group:sessions` | `sessions_list`, `sessions_history`, `sessions_send`, `sessions_spawn`, `sessions_yield`, `subagents`, `session_status` | -| `group:memory` | `memory_search`, `memory_get` | -| `group:web` | `web_search`, `x_search`, `web_fetch` | -| `group:ui` | `browser`, `canvas` | -| `group:automation` | `cron`, `gateway` | -| `group:messaging` | `message` | -| `group:nodes` | `nodes` | -| `group:agents` | `agents_list` | -| `group:media` | `image`, `image_generate`, `video_generate`, `tts` | -| `group:openclaw` | Wszystkie wbudowane narzędzia (bez pluginów dostawców) | +| Grupa | Narzędzia | +| ------------------ | ----------------------------------------------------------------------------------------------------------------------- | +| `group:runtime` | `exec`, `process`, `code_execution` (`bash` jest akceptowany jako alias dla `exec`) | +| `group:fs` | `read`, `write`, `edit`, `apply_patch` | +| `group:sessions` | `sessions_list`, `sessions_history`, `sessions_send`, `sessions_spawn`, `sessions_yield`, `subagents`, `session_status` | +| `group:memory` | `memory_search`, `memory_get` | +| `group:web` | `web_search`, `x_search`, `web_fetch` | +| `group:ui` | `browser`, `canvas` | +| `group:automation` | `cron`, `gateway` | +| `group:messaging` | `message` | +| `group:nodes` | `nodes` | +| `group:agents` | `agents_list` | +| `group:media` | `image`, `image_generate`, `video_generate`, `tts` | +| `group:openclaw` | Wszystkie wbudowane narzędzia (bez pluginów dostawców) | ### `tools.allow` / `tools.deny` -Globalna polityka allow/deny dla narzędzi (deny wygrywa). Niezależna od wielkości liter, obsługuje wildcardy `*`. Stosowana nawet wtedy, gdy sandbox Docker jest wyłączony. +Globalna polityka allow/deny dla narzędzi (deny wygrywa). Niewrażliwa na wielkość liter, obsługuje wildcardy `*`. Stosowana nawet wtedy, gdy sandbox Docker jest wyłączony. ```json5 { @@ -1997,7 +2000,7 @@ Globalna polityka allow/deny dla narzędzi (deny wygrywa). Niezależna od wielko ### `tools.byProvider` -Dalsze ograniczanie narzędzi dla określonych dostawców lub modeli. Kolejność: profil bazowy → profil dostawcy → allow/deny. +Dodatkowo ogranicza narzędzia dla określonych dostawców lub modeli. Kolejność: profil bazowy → profil dostawcy → allow/deny. ```json5 { @@ -2029,9 +2032,9 @@ Steruje podwyższonym dostępem exec poza sandboxem: } ``` -- Nadpisanie per agent (`agents.list[].tools.elevated`) może tylko dalej ograniczać. -- `/elevated on|off|ask|full` zapisuje stan per sesja; dyrektywy inline dotyczą pojedynczej wiadomości. -- Podwyższone `exec` omija sandboxing i używa skonfigurowanej ścieżki ucieczki (`gateway` domyślnie lub `node`, gdy celem exec jest `node`). +- Nadpisanie per agent (`agents.list[].tools.elevated`) może jedynie dodatkowo ograniczać. +- `/elevated on|off|ask|full` zapisuje stan per sesja; dyrektywy inline mają zastosowanie do pojedynczej wiadomości. +- Podwyższone `exec` omija sandboxing i używa skonfigurowanej ścieżki wyjścia (`gateway` domyślnie lub `node`, gdy celem exec jest `node`). ### `tools.exec` @@ -2055,8 +2058,8 @@ Steruje podwyższonym dostępem exec poza sandboxem: ### `tools.loopDetection` -Kontrole bezpieczeństwa pętli narzędzi są **domyślnie wyłączone**. Ustaw `enabled: true`, aby włączyć wykrywanie. -Ustawienia mogą być zdefiniowane globalnie w `tools.loopDetection` i nadpisane per agent w `agents.list[].tools.loopDetection`. +Kontrole bezpieczeństwa pętli narzędzi są **domyślnie wyłączone**. Ustaw `enabled: true`, aby aktywować wykrywanie. +Ustawienia można definiować globalnie w `tools.loopDetection` i nadpisywać per agent w `agents.list[].tools.loopDetection`. ```json5 { @@ -2078,12 +2081,12 @@ Ustawienia mogą być zdefiniowane globalnie w `tools.loopDetection` i nadpisane ``` - `historySize`: maksymalna historia wywołań narzędzi zachowywana do analizy pętli. -- `warningThreshold`: próg powtarzającego się wzorca bez postępu dla ostrzeżeń. -- `criticalThreshold`: wyższy próg powtarzania dla blokowania krytycznych pętli. +- `warningThreshold`: próg ostrzeżeń dla powtarzającego się wzorca bez postępu. +- `criticalThreshold`: wyższy próg dla blokowania krytycznych pętli. - `globalCircuitBreakerThreshold`: próg twardego zatrzymania dla dowolnego przebiegu bez postępu. -- `detectors.genericRepeat`: ostrzega przy powtarzanych wywołaniach tego samego narzędzia z tymi samymi argumentami. -- `detectors.knownPollNoProgress`: ostrzega/blokuje przy znanych narzędziach pollingowych (`process.poll`, `command_status` itd.). -- `detectors.pingPong`: ostrzega/blokuje przy naprzemiennych wzorcach par bez postępu. +- `detectors.genericRepeat`: ostrzegaj o powtarzanych wywołaniach tego samego narzędzia z tymi samymi argumentami. +- `detectors.knownPollNoProgress`: ostrzegaj/blokuj znane narzędzia odpytywania (`process.poll`, `command_status` itd.). +- `detectors.pingPong`: ostrzegaj/blokuj naprzemienne wzorce par bez postępu. - Jeśli `warningThreshold >= criticalThreshold` lub `criticalThreshold >= globalCircuitBreakerThreshold`, walidacja kończy się niepowodzeniem. ### `tools.web` @@ -2094,14 +2097,14 @@ Ustawienia mogą być zdefiniowane globalnie w `tools.loopDetection` i nadpisane web: { search: { enabled: true, - apiKey: "brave_api_key", // or BRAVE_API_KEY env + apiKey: "brave_api_key", // lub BRAVE_API_KEY env maxResults: 5, timeoutSeconds: 30, cacheTtlMinutes: 15, }, fetch: { enabled: true, - provider: "firecrawl", // optional; omit for auto-detect + provider: "firecrawl", // opcjonalnie; pomiń dla auto-detect maxChars: 50000, maxCharsCap: 50000, maxResponseBytes: 2000000, @@ -2126,7 +2129,7 @@ Konfiguruje rozumienie mediów przychodzących (obraz/audio/wideo): media: { concurrency: 2, asyncCompletion: { - directSend: false, // opt-in: send finished async music/video directly to the channel + directSend: false, // opt-in: wyślij zakończone asynchroniczne music/video bezpośrednio do kanału }, audio: { enabled: true, @@ -2161,21 +2164,21 @@ Konfiguruje rozumienie mediów przychodzących (obraz/audio/wideo): **Wpis CLI** (`type: "cli"`): - `command`: wykonywalne polecenie do uruchomienia -- `args`: argumenty szablonizowane (obsługuje `{{MediaPath}}`, `{{Prompt}}`, `{{MaxChars}}` itd.) +- `args`: sparametryzowane argumenty (obsługuje `{{MediaPath}}`, `{{Prompt}}`, `{{MaxChars}}` itd.) **Wspólne pola:** - `capabilities`: opcjonalna lista (`image`, `audio`, `video`). Domyślnie: `openai`/`anthropic`/`minimax` → image, `google` → image+audio+video, `groq` → audio. - `prompt`, `maxChars`, `maxBytes`, `timeoutSeconds`, `language`: nadpisania per wpis. -- Błędy powodują przejście do następnego wpisu. +- W przypadku błędów używany jest następny wpis. -Uwierzytelnianie dostawcy używa standardowej kolejności: `auth-profiles.json` → zmienne env → `models.providers.*.apiKey`. +Uwierzytelnianie dostawcy stosuje standardową kolejność: `auth-profiles.json` → zmienne środowiskowe → `models.providers.*.apiKey`. -**Pola async completion:** +**Pola asynchronicznego zakończenia:** - `asyncCompletion.directSend`: gdy `true`, zakończone asynchroniczne zadania `music_generate` i `video_generate` najpierw próbują bezpośredniego dostarczenia do kanału. Domyślnie: `false` - (starsza ścieżka wzbudzania sesji żądającej/dostarczenia modelu). + (starsza ścieżka wybudzenia sesji żądającej/dostarczenia modelu). @@ -2194,7 +2197,7 @@ Uwierzytelnianie dostawcy używa standardowej kolejności: `auth-profiles.json` ### `tools.sessions` -Steruje tym, które sesje mogą być celem narzędzi sesji (`sessions_list`, `sessions_history`, `sessions_send`). +Steruje, które sesje mogą być wskazywane przez narzędzia sesji (`sessions_list`, `sessions_history`, `sessions_send`). Domyślnie: `tree` (bieżąca sesja + sesje uruchomione przez nią, takie jak subagenci). @@ -2215,7 +2218,7 @@ Uwagi: - `tree`: bieżąca sesja + sesje uruchomione przez bieżącą sesję (subagenci). - `agent`: dowolna sesja należąca do bieżącego identyfikatora agenta (może obejmować innych użytkowników, jeśli uruchamiasz sesje per nadawca pod tym samym identyfikatorem agenta). - `all`: dowolna sesja. Targetowanie między agentami nadal wymaga `tools.agentToAgent`. -- Ograniczenie sandbox: gdy bieżąca sesja jest w sandbox i `agents.defaults.sandbox.sessionToolsVisibility="spawned"`, widoczność jest wymuszana na `tree`, nawet jeśli `tools.sessions.visibility="all"`. +- Ograniczenie sandboxa: gdy bieżąca sesja jest sandboxowana i `agents.defaults.sandbox.sessionToolsVisibility="spawned"`, widoczność jest wymuszana na `tree`, nawet jeśli `tools.sessions.visibility="all"`. ### `tools.sessions_spawn` @@ -2226,11 +2229,11 @@ Steruje obsługą załączników inline dla `sessions_spawn`. tools: { sessions_spawn: { attachments: { - enabled: false, // opt-in: set true to allow inline file attachments - maxTotalBytes: 5242880, // 5 MB total across all files + enabled: false, // opt-in: ustaw true, aby zezwolić na inline file attachments + maxTotalBytes: 5242880, // 5 MB łącznie dla wszystkich plików maxFiles: 50, - maxFileBytes: 1048576, // 1 MB per file - retainOnSessionKeep: false, // keep attachments when cleanup="keep" + maxFileBytes: 1048576, // 1 MB na plik + retainOnSessionKeep: false, // zachowaj załączniki, gdy cleanup="keep" }, }, }, @@ -2240,11 +2243,11 @@ Steruje obsługą załączników inline dla `sessions_spawn`. Uwagi: - Załączniki są obsługiwane tylko dla `runtime: "subagent"`. Runtime ACP je odrzuca. -- Pliki są materializowane w workspace dziecka pod `.openclaw/attachments//` z `.manifest.json`. -- Zawartość załączników jest automatycznie redagowana z trwałości transcriptu. -- Wejścia base64 są walidowane z użyciem ścisłych kontroli alfabetu/dopełnienia oraz ochrony rozmiaru przed dekodowaniem. +- Pliki są materializowane w child workspace pod `.openclaw/attachments//` z `.manifest.json`. +- Zawartość załączników jest automatycznie redagowana z trwałego zapisu transcriptu. +- Wejścia Base64 są walidowane z rygorystycznym sprawdzaniem alfabetu/dopełnienia oraz zabezpieczeniem rozmiaru przed dekodowaniem. - Uprawnienia plików to `0700` dla katalogów i `0600` dla plików. -- Czyszczenie podąża za polityką `cleanup`: `delete` zawsze usuwa załączniki; `keep` zachowuje je tylko wtedy, gdy `retainOnSessionKeep: true`. +- Czyszczenie podąża za polityką `cleanup`: `delete` zawsze usuwa załączniki; `keep` zachowuje je tylko, gdy `retainOnSessionKeep: true`. ### `tools.experimental` @@ -2254,7 +2257,7 @@ Eksperymentalne flagi wbudowanych narzędzi. Domyślnie wyłączone, chyba że o { tools: { experimental: { - planTool: true, // enable experimental update_plan + planTool: true, // włącz eksperymentalne update_plan }, }, } @@ -2262,9 +2265,9 @@ Eksperymentalne flagi wbudowanych narzędzi. Domyślnie wyłączone, chyba że o Uwagi: -- `planTool`: włącza strukturalne narzędzie `update_plan` do śledzenia nietrywialnych wieloetapowych zadań. +- `planTool`: włącza ustrukturyzowane narzędzie `update_plan` do śledzenia nietrywialnej pracy wieloetapowej. - Domyślnie: `false` dla dostawców innych niż OpenAI. Przebiegi OpenAI i OpenAI Codex włączają je automatycznie. -- Gdy jest włączone, system prompt dodaje też wskazówki użycia, aby model używał go tylko do istotnej pracy i utrzymywał co najwyżej jeden krok `in_progress`. +- Gdy włączone, prompt systemowy dodaje też wskazówki użycia, aby model używał go tylko do istotnej pracy i utrzymywał co najwyżej jeden krok `in_progress`. ### `agents.defaults.subagents` @@ -2285,7 +2288,7 @@ Uwagi: ``` - `model`: domyślny model dla uruchamianych subagentów. Jeśli pominięty, subagenci dziedziczą model wywołującego. -- `allowAgents`: domyślna allowlista docelowych identyfikatorów agentów dla `sessions_spawn`, gdy agent żądający nie ustawia własnego `subagents.allowAgents` (`["*"]` = dowolny; domyślnie: tylko ten sam agent). +- `allowAgents`: domyślna lista dozwolonych identyfikatorów agentów docelowych dla `sessions_spawn`, gdy agent żądający nie ustawia własnego `subagents.allowAgents` (`["*"]` = dowolny; domyślnie: tylko ten sam agent). - `runTimeoutSeconds`: domyślny timeout (sekundy) dla `sessions_spawn`, gdy wywołanie narzędzia pomija `runTimeoutSeconds`. `0` oznacza brak timeoutu. - Polityka narzędzi per subagent: `tools.subagents.tools.allow` / `tools.subagents.tools.deny`. @@ -2293,12 +2296,12 @@ Uwagi: ## Niestandardowi dostawcy i base URL -OpenClaw używa wbudowanego katalogu modeli. Dodaj niestandardowych dostawców przez `models.providers` w konfiguracji lub `~/.openclaw/agents//agent/models.json`. +OpenClaw używa wbudowanego katalogu modeli. Dodawaj niestandardowych dostawców przez `models.providers` w konfiguracji lub `~/.openclaw/agents//agent/models.json`. ```json5 { models: { - mode: "merge", // merge (default) | replace + mode: "merge", // merge (domyślnie) | replace providers: { "custom-proxy": { baseUrl: "http://localhost:4000/v1", @@ -2325,15 +2328,15 @@ OpenClaw używa wbudowanego katalogu modeli. Dodaj niestandardowych dostawców p - Użyj `authHeader: true` + `headers` dla niestandardowych potrzeb uwierzytelniania. - Nadpisz katalog główny konfiguracji agenta przez `OPENCLAW_AGENT_DIR` (lub `PI_CODING_AGENT_DIR`, starszy alias zmiennej środowiskowej). - Priorytet scalania dla pasujących identyfikatorów dostawców: - - Niepuste wartości `baseUrl` z `models.json` agenta mają pierwszeństwo. - - Niepuste wartości `apiKey` agenta mają pierwszeństwo tylko wtedy, gdy dany dostawca nie jest zarządzany przez SecretRef w bieżącym kontekście config/auth-profile. - - Wartości `apiKey` dostawcy zarządzane przez SecretRef są odświeżane na podstawie znaczników źródła (`ENV_VAR_NAME` dla odwołań env, `secretref-managed` dla odwołań file/exec) zamiast utrwalania rozwiązanych sekretów. - - Wartości nagłówków dostawcy zarządzane przez SecretRef są odświeżane na podstawie znaczników źródła (`secretref-env:ENV_VAR_NAME` dla odwołań env, `secretref-managed` dla odwołań file/exec). + - Niepuste wartości `baseUrl` z agent `models.json` mają pierwszeństwo. + - Niepuste wartości `apiKey` agenta mają pierwszeństwo tylko wtedy, gdy ten dostawca nie jest zarządzany przez SecretRef w bieżącym kontekście config/auth-profile. + - Wartości `apiKey` dostawcy zarządzane przez SecretRef są odświeżane z markerów źródła (`ENV_VAR_NAME` dla odwołań env, `secretref-managed` dla odwołań file/exec) zamiast utrwalać rozwiązane sekrety. + - Wartości nagłówków dostawcy zarządzane przez SecretRef są odświeżane z markerów źródła (`secretref-env:ENV_VAR_NAME` dla odwołań env, `secretref-managed` dla odwołań file/exec). - Puste lub brakujące `apiKey`/`baseUrl` agenta wracają do `models.providers` w konfiguracji. - - Dopasowane `contextWindow`/`maxTokens` modelu używają wyższej wartości z jawnej konfiguracji i niejawnych wartości katalogowych. - - Dopasowane `contextTokens` zachowuje jawny limit runtime, gdy jest obecny; użyj tego, aby ograniczyć efektywny kontekst bez zmiany natywnych metadanych modelu. + - Pasujące `contextWindow`/`maxTokens` modelu używają wyższej wartości z jawnej konfiguracji i domyślnych wartości katalogowych. + - Pasujące `contextTokens` modelu zachowuje jawnie ustawiony limit runtime, gdy jest obecny; użyj tego, by ograniczyć efektywny kontekst bez zmiany natywnych metadanych modelu. - Użyj `models.mode: "replace"`, gdy chcesz, aby konfiguracja całkowicie przepisała `models.json`. - - Trwałość znaczników jest autorytatywna względem źródła: znaczniki są zapisywane z aktywnej migawki konfiguracji źródłowej (przed rozwiązaniem), a nie z rozwiązanych wartości sekretów runtime. + - Trwałość markerów jest źródłowo autorytatywna: markery są zapisywane z aktywnej migawki konfiguracji źródłowej (przed rozwiązaniem), a nie z rozwiązanych wartości sekretów czasu działania. ### Szczegóły pól dostawcy @@ -2343,25 +2346,26 @@ OpenClaw używa wbudowanego katalogu modeli. Dodaj niestandardowych dostawców p - `models.providers.*.apiKey`: poświadczenie dostawcy (preferuj SecretRef/podstawianie env). - `models.providers.*.auth`: strategia uwierzytelniania (`api-key`, `token`, `oauth`, `aws-sdk`). - `models.providers.*.injectNumCtxForOpenAICompat`: dla Ollama + `openai-completions`, wstrzykuje `options.num_ctx` do żądań (domyślnie: `true`). -- `models.providers.*.authHeader`: wymusza transport poświadczenia w nagłówku `Authorization`, gdy jest to wymagane. -- `models.providers.*.baseUrl`: bazowy URL upstream API. -- `models.providers.*.headers`: dodatkowe statyczne nagłówki dla routowania proxy/dzierżawy. -- `models.providers.*.request`: nadpisania transportu dla żądań HTTP dostawcy modeli. +- `models.providers.*.authHeader`: wymusza transport poświadczeń w nagłówku `Authorization`, gdy jest to wymagane. +- `models.providers.*.baseUrl`: base URL upstream API. +- `models.providers.*.headers`: dodatkowe statyczne nagłówki dla routingu proxy/tenant. +- `models.providers.*.request`: nadpisania transportu dla żądań HTTP model-provider. - `request.headers`: dodatkowe nagłówki (scalane z domyślnymi dostawcy). Wartości akceptują SecretRef. - - `request.auth`: nadpisanie strategii uwierzytelniania. Tryby: `"provider-default"` (użyj wbudowanego uwierzytelniania dostawcy), `"authorization-bearer"` (z `token`), `"header"` (z `headerName`, `value`, opcjonalnym `prefix`). + - `request.auth`: nadpisanie strategii auth. Tryby: `"provider-default"` (użyj wbudowanego auth dostawcy), `"authorization-bearer"` (z `token`), `"header"` (z `headerName`, `value`, opcjonalnym `prefix`). - `request.proxy`: nadpisanie proxy HTTP. Tryby: `"env-proxy"` (użyj zmiennych env `HTTP_PROXY`/`HTTPS_PROXY`), `"explicit-proxy"` (z `url`). Oba tryby akceptują opcjonalny pod-obiekt `tls`. - `request.tls`: nadpisanie TLS dla połączeń bezpośrednich. Pola: `ca`, `cert`, `key`, `passphrase` (wszystkie akceptują SecretRef), `serverName`, `insecureSkipVerify`. - `models.providers.*.models`: jawne wpisy katalogu modeli dostawcy. - `models.providers.*.models.*.contextWindow`: metadane natywnego okna kontekstu modelu. -- `models.providers.*.models.*.contextTokens`: opcjonalny limit kontekstu runtime. Użyj go, gdy chcesz mniejszego efektywnego budżetu kontekstu niż natywne `contextWindow` modelu. -- `models.providers.*.models.*.compat.supportsDeveloperRole`: opcjonalna wskazówka zgodności. Dla `api: "openai-completions"` z niepustym, nienatywnym `baseUrl` (host nie jest `api.openai.com`) OpenClaw wymusza to na `false` w runtime. Puste/pominięte `baseUrl` zachowuje domyślne zachowanie OpenAI. -- `plugins.entries.amazon-bedrock.config.discovery`: katalog główny ustawień auto-discovery Bedrock. -- `plugins.entries.amazon-bedrock.config.discovery.enabled`: włącza/wyłącza niejawne odkrywanie. -- `plugins.entries.amazon-bedrock.config.discovery.region`: region AWS do odkrywania. -- `plugins.entries.amazon-bedrock.config.discovery.providerFilter`: opcjonalny filtr identyfikatorów dostawców do ukierunkowanego odkrywania. -- `plugins.entries.amazon-bedrock.config.discovery.refreshInterval`: interwał odpytywania dla odświeżania odkrywania. -- `plugins.entries.amazon-bedrock.config.discovery.defaultContextWindow`: zapasowe okno kontekstu dla odkrytych modeli. -- `plugins.entries.amazon-bedrock.config.discovery.defaultMaxTokens`: zapasowa maksymalna liczba tokenów wyjściowych dla odkrytych modeli. +- `models.providers.*.models.*.contextTokens`: opcjonalny limit kontekstu czasu działania. Użyj tego, gdy chcesz mieć mniejszy efektywny budżet kontekstu niż natywne `contextWindow` modelu. +- `models.providers.*.models.*.compat.supportsDeveloperRole`: opcjonalna wskazówka zgodności. Dla `api: "openai-completions"` z niepustym nienatywnym `baseUrl` (host inny niż `api.openai.com`) OpenClaw wymusza w runtime wartość `false`. Puste/pominięte `baseUrl` zachowuje domyślne zachowanie OpenAI. +- `models.providers.*.models.*.compat.requiresStringContent`: opcjonalna wskazówka zgodności dla punktów końcowych czatu kompatybilnych z OpenAI, które obsługują tylko stringi. Gdy `true`, OpenClaw spłaszcza czysto tekstowe tablice `messages[].content` do zwykłych stringów przed wysłaniem żądania. +- `plugins.entries.amazon-bedrock.config.discovery`: główny węzeł ustawień automatycznego wykrywania Bedrock. +- `plugins.entries.amazon-bedrock.config.discovery.enabled`: włącza/wyłącza niejawne wykrywanie. +- `plugins.entries.amazon-bedrock.config.discovery.region`: region AWS dla wykrywania. +- `plugins.entries.amazon-bedrock.config.discovery.providerFilter`: opcjonalny filtr provider-id dla celowanego wykrywania. +- `plugins.entries.amazon-bedrock.config.discovery.refreshInterval`: interwał odpytywania dla odświeżania wykrywania. +- `plugins.entries.amazon-bedrock.config.discovery.defaultContextWindow`: zapasowe okno kontekstu dla wykrytych modeli. +- `plugins.entries.amazon-bedrock.config.discovery.defaultMaxTokens`: zapasowa maksymalna liczba tokenów wyjściowych dla wykrytych modeli. ### Przykłady dostawców @@ -2416,7 +2420,7 @@ Użyj `cerebras/zai-glm-4.7` dla Cerebras; `zai/glm-4.7` dla bezpośredniego Z.A } ``` -Ustaw `OPENCODE_API_KEY` (lub `OPENCODE_ZEN_API_KEY`). Używaj referencji `opencode/...` dla katalogu Zen lub `opencode-go/...` dla katalogu Go. Skrót: `openclaw onboard --auth-choice opencode-zen` lub `openclaw onboard --auth-choice opencode-go`. +Ustaw `OPENCODE_API_KEY` (lub `OPENCODE_ZEN_API_KEY`). Używaj odwołań `opencode/...` dla katalogu Zen lub `opencode-go/...` dla katalogu Go. Skrót: `openclaw onboard --auth-choice opencode-zen` lub `openclaw onboard --auth-choice opencode-go`. @@ -2435,9 +2439,9 @@ Ustaw `OPENCODE_API_KEY` (lub `OPENCODE_ZEN_API_KEY`). Używaj referencji `openc Ustaw `ZAI_API_KEY`. `z.ai/*` i `z-ai/*` są akceptowanymi aliasami. Skrót: `openclaw onboard --auth-choice zai-api-key`. -- Ogólny endpoint: `https://api.z.ai/api/paas/v4` -- Endpoint coding (domyślnie): `https://api.z.ai/api/coding/paas/v4` -- Dla ogólnego endpointu zdefiniuj niestandardowego dostawcę z nadpisaniem base URL. +- Główny endpoint: `https://api.z.ai/api/paas/v4` +- Endpoint coding (domyślny): `https://api.z.ai/api/coding/paas/v4` +- Dla głównego endpointu zdefiniuj niestandardowego dostawcę z nadpisaniem base URL. @@ -2478,9 +2482,9 @@ Ustaw `ZAI_API_KEY`. `z.ai/*` i `z-ai/*` są akceptowanymi aliasami. Skrót: `op Dla endpointu China: `baseUrl: "https://api.moonshot.cn/v1"` lub `openclaw onboard --auth-choice moonshot-api-key-cn`. -Natywne endpointy Moonshot reklamują zgodność streamingu na współdzielonym -transporcie `openai-completions`, a OpenClaw wiąże to teraz z możliwościami endpointu, -zamiast wyłącznie z wbudowanym identyfikatorem dostawcy. +Natywne endpointy Moonshot deklarują zgodność użycia strumieniowania na współdzielonym +transporcie `openai-completions`, a OpenClaw opiera to teraz na możliwościach +endpointu, a nie wyłącznie na wbudowanym identyfikatorze dostawcy. @@ -2498,7 +2502,7 @@ zamiast wyłącznie z wbudowanym identyfikatorem dostawcy. } ``` -Wbudowany dostawca kompatybilny z Anthropic. Skrót: `openclaw onboard --auth-choice kimi-code-api-key`. +Kompatybilny z Anthropic, wbudowany dostawca. Skrót: `openclaw onboard --auth-choice kimi-code-api-key`. @@ -2537,7 +2541,7 @@ Wbudowany dostawca kompatybilny z Anthropic. Skrót: `openclaw onboard --auth-ch } ``` -Base URL powinien pomijać `/v1` (klient Anthropic sam je dopisuje). Skrót: `openclaw onboard --auth-choice synthetic-api-key`. +Base URL powinien pomijać `/v1` (klient Anthropic dopisuje je sam). Skrót: `openclaw onboard --auth-choice synthetic-api-key`. @@ -2580,8 +2584,8 @@ Base URL powinien pomijać `/v1` (klient Anthropic sam je dopisuje). Skrót: `op Ustaw `MINIMAX_API_KEY`. Skróty: `openclaw onboard --auth-choice minimax-global-api` lub `openclaw onboard --auth-choice minimax-cn-api`. -Katalog modeli domyślnie używa teraz tylko M2.7. -Na ścieżce streamingu kompatybilnej z Anthropic OpenClaw domyślnie wyłącza thinking MiniMax, +Katalog modeli domyślnie obejmuje teraz tylko M2.7. +Na ścieżce strumieniowania kompatybilnej z Anthropic OpenClaw domyślnie wyłącza thinking MiniMax, chyba że jawnie ustawisz `thinking` samodzielnie. `/fast on` lub `params.fastMode: true` przepisuje `MiniMax-M2.7` na `MiniMax-M2.7-highspeed`. @@ -2590,7 +2594,7 @@ chyba że jawnie ustawisz `thinking` samodzielnie. `/fast on` lub -Zobacz [Modele lokalne](/pl/gateway/local-models). W skrócie: uruchamiaj duży model lokalny przez LM Studio Responses API na odpowiednio mocnym sprzęcie; zachowaj hostowane modele scalone jako fallback. +Zobacz [Local Models](/pl/gateway/local-models). W skrócie: uruchamiaj duży model lokalny przez LM Studio Responses API na wydajnym sprzęcie; zachowaj hostowane modele w trybie merge jako fallback. @@ -2611,7 +2615,7 @@ Zobacz [Modele lokalne](/pl/gateway/local-models). W skrócie: uruchamiaj duży }, entries: { "image-lab": { - apiKey: { source: "env", provider: "default", id: "GEMINI_API_KEY" }, // or plaintext string + apiKey: { source: "env", provider: "default", id: "GEMINI_API_KEY" }, // lub zwykły ciąg znaków env: { GEMINI_API_KEY: "GEMINI_KEY_HERE" }, }, peekaboo: { enabled: true }, @@ -2621,57 +2625,11 @@ Zobacz [Modele lokalne](/pl/gateway/local-models). W skrócie: uruchamiaj duży } ``` -- `allowBundled`: opcjonalna allowlista tylko dla dołączonych Skills (zarządzane/workspace Skills pozostają bez zmian). +- `allowBundled`: opcjonalna lista dozwolonych tylko dla Skills dołączonych do pakietu (zarządzane/workspace Skills bez zmian). - `load.extraDirs`: dodatkowe współdzielone katalogi główne Skills (najniższy priorytet). -- `install.preferBrew`: gdy true, preferuje instalatory Homebrew, jeśli `brew` jest - dostępne, zanim wróci do innych typów instalatorów. +- `install.preferBrew`: gdy true, preferuje instalatory Homebrew, gdy `brew` jest + dostępne, zanim wróci do innych rodzajów instalatorów. - `install.nodeManager`: preferencja instalatora node dla specyfikacji `metadata.openclaw.install` (`npm` | `pnpm` | `yarn` | `bun`). -- `entries..enabled: false` wyłącza Skill nawet jeśli jest dołączony/zainstalowany. -- `entries..apiKey`: wygodne pole klucza API dla Skills deklarujących podstawową zmienną env (jawny ciąg znaków lub obiekt SecretRef). - ---- - -## Pluginy - -```json5 -{ - plugins: { - enabled: true, - allow: ["voice-call"], - deny: [], - load: { - paths: ["~/Projects/oss/voice-call-extension"], - }, - entries: { - "voice-call": { - enabled: true, - hooks: { - allowPromptInjection: false, - }, - config: { provider: "twilio" }, - }, - }, - }, -} -``` - -- Ładowane z `~/.openclaw/extensions`, `/.openclaw/extensions` oraz `plugins.load.paths`. -- Discovery akceptuje natywne pluginy OpenClaw oraz kompatybilne bundlery Codex i Claude, w tym bundlery Claude o domyślnym układzie bez manifestu. -- **Zmiany konfiguracji wymagają restartu gateway.** -- `allow`: opcjonalna allowlista (ładowane są tylko wymienione pluginy). `deny` wygrywa. -- `plugins.entries..apiKey`: wygodne pole klucza API na poziomie pluginu (gdy plugin to obsługuje). -- `plugins.entries..env`: mapa zmiennych env w zakresie pluginu. -- `plugins.entries..hooks.allowPromptInjection`: gdy `false`, core blokuje `before_prompt_build` i ignoruje pola mutujące prompt ze starszego `before_agent_start`, zachowując starsze `modelOverride` i `providerOverride`. Dotyczy natywnych hooków pluginów i wspieranych katalogów hooków dostarczanych przez bundle. -- `plugins.entries..subagent.allowModelOverride`: jawnie ufa temu pluginowi w żądaniu nadpisań `provider` i `model` per uruchomienie dla przebiegów subagenta w tle. -- `plugins.entries..subagent.allowedModels`: opcjonalna allowlista kanonicznych celów `provider/model` dla zaufanych nadpisań subagenta. Użyj `"*"`, tylko jeśli świadomie chcesz dopuścić dowolny model. -- `plugins.entries..config`: obiekt konfiguracji zdefiniowany przez plugin (walidowany przez natywny schemat pluginów OpenClaw, gdy jest dostępny). -- `plugins.entries.firecrawl.config.webFetch`: ustawienia dostawcy web-fetch Firecrawl. - - `apiKey`: klucz API Firecrawl (akceptuje SecretRef). Wartość zapasowa pochodzi z `plugins.entries.firecrawl.config.webSearch.apiKey`, starszego `tools.web.fetch.firecrawl.apiKey` lub zmiennej env `FIRECRAWL_API_KEY`. - - `baseUrl`: bazowy URL API Firecrawl (domyślnie: `https://api.firecrawl.dev`). - - `onlyMainContent`: ekstrakcja tylko głównej treści stron (domyślnie: `true`). - - `maxAgeMs`: maksymalny wiek cache w milisekundach (domyślnie: `172800000` / 2 dni). - - `timeoutSeconds`: timeout żądania scrape w sekundach (domyślnie: `60`). -- `plugins.entries.xai.config.xSearch`: ustawienia xAI X Search (wyszukiwanie web Grok). - - `enabled`: włącza dostawcę X Search. - - `model`: model Grok używany do wyszukiwania (np. `" \ No newline at end of file +- `entries..enabled: false` wyłącza Skill nawet wtedy, gdy jest dołączony/zainstalowany. +- `entries..apiKey`: wygodne pole klucza API dla Skills deklarujących podstawową \ No newline at end of file diff --git a/docs/pl/gateway/doctor.md b/docs/pl/gateway/doctor.md index 681b48796..e8d2556ac 100644 --- a/docs/pl/gateway/doctor.md +++ b/docs/pl/gateway/doctor.md @@ -1,22 +1,23 @@ --- read_when: - - Dodajesz lub modyfikujesz migracje doctor - - Wprowadzasz niezgodne wstecz zmiany konfiguracji + - Dodawanie lub modyfikowanie migracji doctor + - Wprowadzanie niekompatybilnych zmian konfiguracji summary: 'Polecenie Doctor: kontrole stanu, migracje konfiguracji i kroki naprawcze' title: Doctor x-i18n: - generated_at: "2026-04-07T09:45:53Z" + generated_at: "2026-04-08T02:15:39Z" model: gpt-5.4 provider: openai - source_hash: a834dc7aec79c20d17bc23d37fb5f5e99e628d964d55bd8cf24525a7ee57130c + source_hash: 3761a222d9db7088f78215575fa84e5896794ad701aa716e8bf9039a4424dca6 source_path: gateway/doctor.md workflow: 15 --- # Doctor -`openclaw doctor` to narzędzie naprawcze i migracyjne dla OpenClaw. Naprawia nieaktualną -konfigurację i stan, sprawdza kondycję systemu oraz podaje konkretne kroki naprawcze. +`openclaw doctor` to narzędzie naprawy i migracji dla OpenClaw. Naprawia +nieaktualną konfigurację i stan, sprawdza kondycję systemu oraz podaje +konkretne kroki naprawcze. ## Szybki start @@ -24,19 +25,19 @@ konfigurację i stan, sprawdza kondycję systemu oraz podaje konkretne kroki nap openclaw doctor ``` -### Tryb headless / automatyzacja +### Tryb bezgłowy / automatyzacja ```bash openclaw doctor --yes ``` -Akceptuje wartości domyślne bez pytań (w tym kroki naprawcze związane z restartem/usługą/sandboxem, gdy mają zastosowanie). +Akceptuje domyślne opcje bez pytań (w tym kroki naprawy restartu/usługi/sandboxa, gdy mają zastosowanie). ```bash openclaw doctor --repair ``` -Stosuje zalecane naprawy bez pytań (naprawy + restarty tam, gdzie to bezpieczne). +Stosuje zalecane naprawy bez pytań (naprawy + restarty tam, gdzie jest to bezpieczne). ```bash openclaw doctor --repair --force @@ -48,16 +49,16 @@ Stosuje także agresywne naprawy (nadpisuje niestandardowe konfiguracje supervis openclaw doctor --non-interactive ``` -Uruchamia się bez pytań i stosuje tylko bezpieczne migracje (normalizacja konfiguracji + przenoszenie stanu na dysku). Pomija działania dotyczące restartu/usług/sandboxa, które wymagają potwierdzenia człowieka. -Migracje starszego stanu są uruchamiane automatycznie po wykryciu. +Uruchamia bez pytań i stosuje tylko bezpieczne migracje (normalizacja konfiguracji + przenoszenie stanu na dysku). Pomija działania restartu/usługi/sandboxa, które wymagają potwierdzenia człowieka. +Migracje starszego stanu są uruchamiane automatycznie po ich wykryciu. ```bash openclaw doctor --deep ``` -Skanuje usługi systemowe pod kątem dodatkowych instalacji gateway (`launchd/systemd/schtasks`). +Skanuje usługi systemowe pod kątem dodatkowych instalacji gatewaya (launchd/systemd/schtasks). -Jeśli chcesz przejrzeć zmiany przed zapisem, najpierw otwórz plik konfiguracji: +Jeśli chcesz przejrzeć zmiany przed zapisaniem, najpierw otwórz plik konfiguracji: ```bash cat ~/.openclaw/openclaw.json @@ -65,45 +66,46 @@ cat ~/.openclaw/openclaw.json ## Co robi (podsumowanie) -- Opcjonalna aktualizacja przed uruchomieniem dla instalacji git (tylko interaktywnie). +- Opcjonalna aktualizacja przed uruchomieniem dla instalacji z gita (tylko interaktywnie). - Sprawdzenie aktualności protokołu UI (przebudowuje Control UI, gdy schemat protokołu jest nowszy). -- Kontrola stanu + propozycja restartu. -- Podsumowanie stanu Skills (kwalifikujące się/brakujące/zablokowane) i stanu pluginów. +- Kontrola stanu + monit o restart. +- Podsumowanie stanu Skills (kwalifikujące się/brakujące/zablokowane) oraz stanu pluginów. - Normalizacja konfiguracji dla starszych wartości. - Migracja konfiguracji Talk ze starszych płaskich pól `talk.*` do `talk.provider` + `talk.providers.`. - Kontrole migracji przeglądarki dla starszych konfiguracji rozszerzenia Chrome i gotowości Chrome MCP. -- Ostrzeżenia o nadpisaniach dostawcy OpenCode (`models.providers.opencode` / `models.providers.opencode-go`). -- Sprawdzenie wymagań wstępnych TLS dla OAuth OpenAI Codex. +- Ostrzeżenia o nadpisaniu dostawcy OpenCode (`models.providers.opencode` / `models.providers.opencode-go`). +- Ostrzeżenia o przesłanianiu Codex OAuth (`models.providers.openai-codex`). +- Sprawdzenie wymagań TLS OAuth dla profili OpenAI Codex OAuth. - Migracja starszego stanu na dysku (sesje/katalog agenta/uwierzytelnianie WhatsApp). -- Migracja starszych kluczy kontraktów manifestów pluginów (`speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, `webSearchProviders` → `contracts`). -- Migracja starszego magazynu zadań cron (`jobId`, `schedule.cron`, pola delivery/payload na poziomie głównym, `provider` w payload, proste zadania zapasowe webhook z `notify: true`). -- Inspekcja plików blokad sesji i usuwanie nieaktualnych blokad. -- Kontrole integralności stanu i uprawnień (sesje, transkrypty, katalog stanu). +- Migracja starszych kluczy kontraktu manifestu pluginu (`speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, `webSearchProviders` → `contracts`). +- Migracja starszego magazynu cron (`jobId`, `schedule.cron`, pola delivery/payload na najwyższym poziomie, `provider` w payload, proste zadania zapasowe webhooka z `notify: true`). +- Inspekcja plików blokady sesji i czyszczenie nieaktualnych blokad. +- Kontrole integralności i uprawnień stanu (sesje, transkrypty, katalog stanu). - Kontrole uprawnień pliku konfiguracji (`chmod 600`) przy uruchomieniu lokalnym. -- Kondycja uwierzytelniania modeli: sprawdza wygaśnięcie OAuth, może odświeżyć tokeny bliskie wygaśnięcia i raportuje stany cooldown/disabled profili auth. +- Kondycja uwierzytelniania modeli: sprawdza wygaśnięcie OAuth, może odświeżyć wygasające tokeny i raportuje stany cooldown/wyłączenia profilu uwierzytelniania. - Wykrywanie dodatkowego katalogu workspace (`~/openclaw`). - Naprawa obrazu sandboxa, gdy sandboxing jest włączony. -- Migracja starszych usług i wykrywanie dodatkowych gateway. +- Migracja starszych usług i wykrywanie dodatkowych gatewayów. - Migracja starszego stanu kanału Matrix (w trybie `--fix` / `--repair`). -- Kontrole środowiska uruchomieniowego gateway (usługa zainstalowana, ale nie działa; zapisany label `launchd`). -- Ostrzeżenia o stanie kanałów (sondowane z działającego gateway). -- Audyt konfiguracji supervisora (`launchd/systemd/schtasks`) z opcjonalną naprawą. -- Kontrole dobrych praktyk środowiska uruchomieniowego gateway (Node vs Bun, ścieżki menedżerów wersji). -- Diagnostyka kolizji portu gateway (domyślnie `18789`). -- Ostrzeżenia bezpieczeństwa dla otwartych polityk wiadomości prywatnych. -- Kontrole uwierzytelniania gateway dla lokalnego trybu tokenu (oferuje wygenerowanie tokenu, gdy nie istnieje jego źródło; nie nadpisuje konfiguracji tokenu opartych na SecretRef). -- Sprawdzenie `systemd linger` na Linuksie. -- Kontrola rozmiaru plików bootstrap workspace (ostrzeżenia o obcięciu/blisko limitu dla plików kontekstu). -- Kontrola stanu autouzupełniania powłoki oraz automatyczna instalacja/aktualizacja. -- Kontrola gotowości dostawcy embeddingów dla wyszukiwania pamięci (model lokalny, zdalny klucz API lub binarka QMD). -- Kontrole instalacji ze źródeł (niedopasowanie workspace pnpm, brak zasobów UI, brak binarki tsx). -- Zapisuje zaktualizowaną konfigurację i metadane kreatora. +- Kontrole środowiska uruchomieniowego gatewaya (usługa zainstalowana, ale nie działa; zapisany w pamięci podręcznej label launchd). +- Ostrzeżenia o stanie kanałów (sondowane z działającego gatewaya). +- Audyt konfiguracji supervisora (launchd/systemd/schtasks) z opcjonalną naprawą. +- Kontrole dobrych praktyk środowiska uruchomieniowego gatewaya (Node vs Bun, ścieżki menedżera wersji). +- Diagnostyka kolizji portu gatewaya (domyślnie `18789`). +- Ostrzeżenia bezpieczeństwa dla otwartych zasad DM. +- Kontrole uwierzytelniania gatewaya dla lokalnego trybu tokena (oferuje wygenerowanie tokena, gdy nie istnieje żadne źródło tokena; nie nadpisuje konfiguracji tokenów SecretRef). +- Sprawdzenie `systemd linger` w systemie Linux. +- Sprawdzenie rozmiaru plików bootstrap workspace (ostrzeżenia o obcięciu / zbliżaniu się do limitu dla plików kontekstowych). +- Sprawdzenie stanu autouzupełniania powłoki i automatyczna instalacja/aktualizacja. +- Sprawdzenie gotowości dostawcy embeddingów wyszukiwania pamięci (model lokalny, zdalny klucz API lub binarka QMD). +- Kontrole instalacji ze źródeł (niezgodność workspace pnpm, brakujące zasoby UI, brakująca binarka tsx). +- Zapisuje zaktualizowaną konfigurację + metadane kreatora. ## Szczegółowe działanie i uzasadnienie -### 0) Opcjonalna aktualizacja (instalacje git) +### 0) Opcjonalna aktualizacja (instalacje z gita) -Jeśli to checkout git i doctor działa interaktywnie, oferuje +Jeśli jest to checkout z gita i doctor działa interaktywnie, oferuje aktualizację (fetch/rebase/build) przed uruchomieniem doctor. ### 1) Normalizacja konfiguracji @@ -112,9 +114,9 @@ Jeśli konfiguracja zawiera starsze kształty wartości (na przykład `messages. bez nadpisania specyficznego dla kanału), doctor normalizuje je do bieżącego schematu. -Dotyczy to także starszych płaskich pól Talk. Aktualny publiczny model konfiguracji Talk to -`talk.provider` + `talk.providers.`. Doctor przepisuje starsze -kształty `talk.voiceId` / `talk.voiceAliases` / `talk.modelId` / `talk.outputFormat` / +Dotyczy to także starszych płaskich pól Talk. Obecna publiczna konfiguracja Talk to +`talk.provider` + `talk.providers.`. Doctor przepisuje stare kształty +`talk.voiceId` / `talk.voiceAliases` / `talk.modelId` / `talk.outputFormat` / `talk.apiKey` do mapy dostawców. ### 2) Migracje starszych kluczy konfiguracji @@ -122,14 +124,15 @@ kształty `talk.voiceId` / `talk.voiceAliases` / `talk.modelId` / `talk.outputFo Gdy konfiguracja zawiera przestarzałe klucze, inne polecenia odmawiają działania i proszą, aby uruchomić `openclaw doctor`. -Doctor: +Doctor wykona wtedy: -- wyjaśnia, które starsze klucze zostały znalezione, -- pokazuje zastosowaną migrację, -- przepisuje `~/.openclaw/openclaw.json` do zaktualizowanego schematu. +- Wyjaśni, które starsze klucze zostały znalezione. +- Pokaże zastosowaną migrację. +- Przepisze `~/.openclaw/openclaw.json` z użyciem zaktualizowanego schematu. -Gateway także automatycznie uruchamia migracje doctor przy starcie, gdy wykryje -starszy format konfiguracji, więc nieaktualne konfiguracje są naprawiane bez ręcznej interwencji. +Gateway uruchamia także migracje doctor automatycznie przy starcie, gdy wykryje +starszy format konfiguracji, dzięki czemu nieaktualne konfiguracje są naprawiane +bez ręcznej interwencji. Migracje magazynu zadań cron są obsługiwane przez `openclaw doctor --fix`. Bieżące migracje: @@ -139,7 +142,7 @@ Bieżące migracje: - `routing.groupChat.historyLimit` → `messages.groupChat.historyLimit` - `routing.groupChat.mentionPatterns` → `messages.groupChat.mentionPatterns` - `routing.queue` → `messages.queue` -- `routing.bindings` → `bindings` na poziomie głównym +- `routing.bindings` → najwyższy poziom `bindings` - `routing.agents`/`routing.defaultAgentId` → `agents.list` + `agents.list[].default` - starsze `talk.voiceId`/`talk.voiceAliases`/`talk.modelId`/`talk.outputFormat`/`talk.apiKey` → `talk.provider` + `talk.providers.` - `routing.agentToAgent` → `tools.agentToAgent` @@ -154,71 +157,81 @@ Bieżące migracje: - `plugins.entries.voice-call.config.streaming.openaiApiKey|sttModel|silenceDurationMs|vadThreshold` → `plugins.entries.voice-call.config.streaming.providers.openai.*` - `bindings[].match.accountID` → `bindings[].match.accountId` -- Dla kanałów z nazwanymi `accounts`, ale z pozostawionymi wartościami kanału na najwyższym poziomie dla pojedynczego konta, przenieś te wartości przypisane do zakresu konta do promowanego konta wybranego dla tego kanału (`accounts.default` dla większości kanałów; Matrix może zachować istniejący pasujący nazwany/dom yślny cel) +- Dla kanałów z nazwanymi `accounts`, ale z pozostałymi jednokontowymi wartościami kanału na najwyższym poziomie, przenieś te wartości przypisane do konta do wybranego promowanego konta dla tego kanału (`accounts.default` dla większości kanałów; Matrix może zachować istniejący pasujący nazwany/domyslny cel) - `identity` → `agents.list[].identity` - `agent.*` → `agents.defaults` + `tools.*` (tools/elevated/exec/sandbox/subagents) - `agent.model`/`allowedModels`/`modelAliases`/`modelFallbacks`/`imageModelFallbacks` → `agents.defaults.models` + `agents.defaults.model.primary/fallbacks` + `agents.defaults.imageModel.primary/fallbacks` - `browser.ssrfPolicy.allowPrivateNetwork` → `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork` - `browser.profiles.*.driver: "extension"` → `"existing-session"` -- usuwa `browser.relayBindHost` (starsze ustawienie relay rozszerzenia) +- usuń `browser.relayBindHost` (starsze ustawienie relay rozszerzenia) -Ostrzeżenia doctor zawierają też wskazówki dotyczące kont domyślnych w kanałach wielokontowych: +Ostrzeżenia doctor obejmują też wskazówki dotyczące domyślnego konta dla kanałów wielokontowych: -- Jeśli skonfigurowano co najmniej dwa wpisy `channels..accounts` bez `channels..defaultAccount` lub `accounts.default`, doctor ostrzega, że routing awaryjny może wybrać nieoczekiwane konto. -- Jeśli `channels..defaultAccount` jest ustawione na nieznany identyfikator konta, doctor ostrzega i wyświetla skonfigurowane identyfikatory kont. +- Jeśli skonfigurowano dwa lub więcej wpisów `channels..accounts` bez `channels..defaultAccount` lub `accounts.default`, doctor ostrzega, że routing zapasowy może wybrać nieoczekiwane konto. +- Jeśli ustawiono `channels..defaultAccount` na nieznany identyfikator konta, doctor ostrzega i wyświetla listę skonfigurowanych identyfikatorów kont. ### 2b) Nadpisania dostawcy OpenCode Jeśli ręcznie dodano `models.providers.opencode`, `opencode-zen` lub `opencode-go`, nadpisuje to wbudowany katalog OpenCode z `@mariozechner/pi-ai`. -Może to wymuszać używanie niewłaściwego API przez modele albo zerować koszty. Doctor ostrzega, aby -usunąć nadpisanie i przywrócić routing API oraz koszty per model. +Może to wymusić użycie niewłaściwego API dla modeli albo wyzerować koszty. Doctor ostrzega, aby +można było usunąć nadpisanie i przywrócić routing API oraz koszty dla każdego modelu. ### 2c) Migracja przeglądarki i gotowość Chrome MCP Jeśli konfiguracja przeglądarki nadal wskazuje na usuniętą ścieżkę rozszerzenia Chrome, doctor -normalizuje ją do aktualnego modelu podłączania host-local Chrome MCP: +normalizuje ją do obecnego modelu dołączania Chrome MCP lokalnego dla hosta: -- `browser.profiles.*.driver: "extension"` staje się `"existing-session"` +- `browser.profiles.*.driver: "extension"` zmienia się na `"existing-session"` - `browser.relayBindHost` jest usuwane -Doctor audytuje też ścieżkę host-local Chrome MCP, gdy używasz `defaultProfile: -"user"` lub skonfigurowanego profilu `existing-session`: +Doctor audytuje też lokalną dla hosta ścieżkę Chrome MCP, gdy używasz `defaultProfile: +"user"` albo skonfigurowanego profilu `existing-session`: - sprawdza, czy Google Chrome jest zainstalowany na tym samym hoście dla domyślnych - profili automatycznego łączenia, -- sprawdza wykrytą wersję Chrome i ostrzega, gdy jest niższa niż Chrome 144, + profili automatycznego łączenia +- sprawdza wykrytą wersję Chrome i ostrzega, gdy jest niższa niż Chrome 144 - przypomina o włączeniu zdalnego debugowania na stronie inspekcji przeglądarki (na - przykład `chrome://inspect/#remote-debugging`, `brave://inspect/#remote-debugging` + przykład `chrome://inspect/#remote-debugging`, `brave://inspect/#remote-debugging`, lub `edge://inspect/#remote-debugging`) -Doctor nie może włączyć tego ustawienia po stronie Chrome za Ciebie. Host-local Chrome MCP +Doctor nie może włączyć ustawienia po stronie Chrome za Ciebie. Lokalny dla hosta Chrome MCP nadal wymaga: -- przeglądarki opartej na Chromium 144+ na hoście gateway/node, -- lokalnie uruchomionej przeglądarki, -- włączonego zdalnego debugowania w tej przeglądarce, -- zaakceptowania pierwszego monitu o zgodę na podłączenie w przeglądarce. +- przeglądarki opartej na Chromium 144+ na hoście gatewaya/noda +- lokalnie uruchomionej przeglądarki +- włączonego zdalnego debugowania w tej przeglądarce +- zatwierdzenia pierwszego monitu o zgodę na dołączenie w przeglądarce -Gotowość w tym miejscu dotyczy wyłącznie lokalnych wymagań wstępnych dla podłączania. Existing-session zachowuje +Gotowość w tym miejscu dotyczy wyłącznie wymagań wstępnych lokalnego dołączania. Existing-session zachowuje obecne ograniczenia tras Chrome MCP; zaawansowane trasy, takie jak `responsebody`, eksport PDF, przechwytywanie pobierania i działania wsadowe, nadal wymagają zarządzanej przeglądarki lub surowego profilu CDP. -Ta kontrola **nie** dotyczy przepływów Docker, sandbox, remote-browser ani innych -trybów headless. One nadal używają surowego CDP. +To sprawdzenie **nie** dotyczy Docker, sandbox, remote-browser ani innych +przepływów bezgłowych. One nadal używają surowego CDP. -### 2d) Wymagania wstępne TLS dla OAuth +### 2d) Wymagania TLS OAuth -Gdy skonfigurowany jest profil OAuth OpenAI Codex, doctor sonduje punkt autoryzacji OpenAI, -aby sprawdzić, czy lokalny stos TLS Node/OpenSSL potrafi +Gdy skonfigurowany jest profil OpenAI Codex OAuth, doctor sonduje punkt końcowy +autoryzacji OpenAI, aby sprawdzić, czy lokalny stos TLS Node/OpenSSL potrafi zweryfikować łańcuch certyfikatów. Jeśli sonda zakończy się błędem certyfikatu (na -przykład `UNABLE_TO_GET_ISSUER_CERT_LOCALLY`, wygasły certyfikat lub certyfikat self-signed), -doctor wyświetla wskazówki naprawcze specyficzne dla platformy. Na macOS z Node z Homebrew -naprawą jest zwykle `brew postinstall ca-certificates`. Przy `--deep` sonda działa +przykład `UNABLE_TO_GET_ISSUER_CERT_LOCALLY`, wygasły certyfikat lub certyfikat własny), +doctor wyświetla wskazówki naprawcze specyficzne dla platformy. W systemie macOS z Node z Homebrew +naprawą jest zwykle `brew postinstall ca-certificates`. Z `--deep` sonda działa nawet wtedy, gdy gateway jest zdrowy. +### 2c) Nadpisania dostawcy Codex OAuth + +Jeśli wcześniej dodano starsze ustawienia transportu OpenAI w +`models.providers.openai-codex`, mogą one przesłaniać wbudowaną ścieżkę +dostawcy Codex OAuth, której nowsze wydania używają automatycznie. Doctor ostrzega, gdy wykryje +te stare ustawienia transportu razem z Codex OAuth, aby można było usunąć lub przepisać +nieaktualne nadpisanie transportu i odzyskać wbudowane zachowanie routingu/fallbacku. +Niestandardowe proxy i nadpisania samych nagłówków są nadal obsługiwane i nie +wywołują tego ostrzeżenia. + ### 3) Migracje starszego stanu (układ na dysku) Doctor może migrować starsze układy na dysku do bieżącej struktury: @@ -228,58 +241,59 @@ Doctor może migrować starsze układy na dysku do bieżącej struktury: - Katalog agenta: - z `~/.openclaw/agent/` do `~/.openclaw/agents//agent/` - Stan uwierzytelniania WhatsApp (Baileys): - - ze starszego `~/.openclaw/credentials/*.json` (oprócz `oauth.json`) + - ze starszego `~/.openclaw/credentials/*.json` (z wyjątkiem `oauth.json`) - do `~/.openclaw/credentials/whatsapp//...` (domyślny identyfikator konta: `default`) -Te migracje są wykonywane w trybie best-effort i są idempotentne; doctor wyemituje ostrzeżenia, jeśli -pozostawi starsze katalogi jako kopie zapasowe. Gateway/CLI także automatycznie migrują -starsze sesje + katalog agenta przy starcie, aby historia/auth/modele trafiły do ścieżki -per agent bez ręcznego uruchamiania doctor. Uwierzytelnianie WhatsApp jest celowo migrowane tylko przez `openclaw doctor`. Normalizacja dostawcy/mapy dostawców Talk -porównuje teraz równość strukturalną, więc różnice wyłącznie w kolejności kluczy nie powodują już -powtarzających się, pustych zmian `doctor --fix`. +Te migracje są realizowane w trybie best-effort i są idempotentne; doctor wyemituje ostrzeżenia, gdy +pozostawi jakiekolwiek starsze foldery jako kopie zapasowe. Gateway/CLI również automatycznie migruje +starsze sesje + katalog agenta przy starcie, dzięki czemu historia/uwierzytelnianie/modele trafiają do +ścieżki per-agent bez ręcznego uruchamiania doctor. Uwierzytelnianie WhatsApp jest celowo +migrowane tylko przez `openclaw doctor`. Normalizacja dostawcy/mapy dostawców Talk porównuje teraz +według równości strukturalnej, więc różnice wyłącznie w kolejności kluczy nie wywołują już +powtarzanych zmian bez efektu przez `doctor --fix`. ### 3a) Migracje starszych manifestów pluginów Doctor skanuje wszystkie zainstalowane manifesty pluginów pod kątem przestarzałych kluczy -możliwości na poziomie głównym (`speechProviders`, `realtimeTranscriptionProviders`, +możliwości na najwyższym poziomie (`speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, -`webSearchProviders`). Po ich znalezieniu oferuje przeniesienie ich do obiektu `contracts` +`webSearchProviders`). Gdy je znajdzie, oferuje przeniesienie ich do obiektu `contracts` i przepisanie pliku manifestu w miejscu. Ta migracja jest idempotentna; -jeśli klucz `contracts` zawiera już te same wartości, starszy klucz jest usuwany +jeśli klucz `contracts` ma już te same wartości, starszy klucz jest usuwany bez duplikowania danych. ### 3b) Migracje starszego magazynu cron -Doctor sprawdza też magazyn zadań cron (`~/.openclaw/cron/jobs.json` domyślnie, -lub `cron.store`, jeśli został nadpisany) pod kątem starych kształtów zadań, które scheduler -nadal akceptuje ze względów zgodności. +Doctor sprawdza także magazyn zadań cron (`~/.openclaw/cron/jobs.json` domyślnie, +lub `cron.store`, jeśli został nadpisany) pod kątem starych kształtów zadań, które harmonogram +nadal akceptuje ze względów kompatybilności. Bieżące porządki cron obejmują: - `jobId` → `id` - `schedule.cron` → `schedule.expr` -- pola payload na poziomie głównym (`message`, `model`, `thinking`, ...) → `payload` -- pola delivery na poziomie głównym (`deliver`, `channel`, `to`, `provider`, ...) → `delivery` +- pola payload na najwyższym poziomie (`message`, `model`, `thinking`, ...) → `payload` +- pola delivery na najwyższym poziomie (`deliver`, `channel`, `to`, `provider`, ...) → `delivery` - aliasy delivery `provider` w payload → jawne `delivery.channel` -- proste starsze zadania zapasowe webhook z `notify: true` → jawne `delivery.mode="webhook"` z `delivery.to=cron.webhook` +- proste starsze zadania zapasowe webhooka `notify: true` → jawne `delivery.mode="webhook"` z `delivery.to=cron.webhook` Doctor automatycznie migruje zadania `notify: true` tylko wtedy, gdy może to zrobić bez -zmiany zachowania. Jeśli zadanie łączy starszy mechanizm zapasowy notify z istniejącym -trybem delivery innym niż webhook, doctor ostrzega i pozostawia takie zadanie do ręcznego przeglądu. +zmiany zachowania. Jeśli zadanie łączy starszy zapasowy mechanizm notify z istniejącym +trybem delivery innym niż webhook, doctor ostrzega i pozostawia to zadanie do ręcznego przeglądu. ### 3c) Czyszczenie blokad sesji -Doctor skanuje katalog sesji każdego agenta w poszukiwaniu nieaktualnych plików blokad zapisu — plików +Doctor skanuje każdy katalog sesji agenta w poszukiwaniu nieaktualnych plików blokady zapisu — plików pozostawionych po nieprawidłowym zakończeniu sesji. Dla każdego znalezionego pliku blokady raportuje: -ścieżkę, PID, czy PID nadal działa, wiek blokady oraz czy -jest uznawana za nieaktualną (martwy PID lub starsza niż 30 minut). W trybie `--fix` / `--repair` -automatycznie usuwa nieaktualne pliki blokad; w przeciwnym razie wyświetla uwagę i -poleca ponownie uruchomić z `--fix`. +ścieżkę, PID, czy PID nadal żyje, wiek blokady i czy jest +uznawana za nieaktualną (martwy PID lub więcej niż 30 minut). W trybie `--fix` / `--repair` +automatycznie usuwa nieaktualne pliki blokady; w przeciwnym razie wyświetla notatkę i +instrukcję, aby uruchomić ponownie z `--fix`. -### 4) Kontrole integralności stanu (utrwalanie sesji, routing i bezpieczeństwo) +### 4) Kontrole integralności stanu (trwałość sesji, routing i bezpieczeństwo) -Katalog stanu to operacyjny pień mózgu systemu. Jeśli zniknie, tracisz +Katalog stanu to operacyjny pień mózgu systemu. Jeśli zniknie, stracisz sesje, poświadczenia, logi i konfigurację (chyba że masz kopie zapasowe gdzie indziej). Doctor sprawdza: @@ -287,105 +301,106 @@ Doctor sprawdza: - **Brak katalogu stanu**: ostrzega o katastrofalnej utracie stanu, proponuje odtworzenie katalogu i przypomina, że nie może odzyskać brakujących danych. - **Uprawnienia katalogu stanu**: weryfikuje możliwość zapisu; oferuje naprawę uprawnień - (i wyświetla wskazówkę `chown`, gdy wykryje niedopasowanie właściciela/grupy). -- **Katalog stanu zsynchronizowany z chmurą na macOS**: ostrzega, gdy stan rozwiązuje się pod iCloud Drive + (i wyświetla wskazówkę `chown`, gdy wykryje niezgodność właściciela/grupy). +- **Katalog stanu synchronizowany z chmurą w macOS**: ostrzega, gdy stan znajduje się pod iCloud Drive (`~/Library/Mobile Documents/com~apple~CloudDocs/...`) lub `~/Library/CloudStorage/...`, ponieważ ścieżki oparte na synchronizacji mogą powodować wolniejsze I/O oraz wyścigi blokad/synchronizacji. -- **Katalog stanu na Linux na SD lub eMMC**: ostrzega, gdy stan rozwiązuje się do źródła montowania `mmcblk*`, - ponieważ losowe I/O na kartach SD lub eMMC może być wolniejsze i szybciej zużywać nośnik - przy zapisach sesji i poświadczeń. +- **Katalog stanu na Linux na SD lub eMMC**: ostrzega, gdy stan znajduje się na źródle montowania `mmcblk*`, + ponieważ losowe I/O na nośnikach SD lub eMMC może być wolniejsze i szybciej zużywać nośnik + przy zapisie sesji i poświadczeń. - **Brak katalogów sesji**: `sessions/` i katalog magazynu sesji są - wymagane do utrwalania historii i unikania awarii `ENOENT`. -- **Niedopasowanie transkryptów**: ostrzega, gdy ostatnie wpisy sesji mają brakujące - pliki transkryptów. -- **Główna sesja „1-line JSONL”**: sygnalizuje, gdy główny transkrypt ma tylko jedną - linię (historia się nie kumuluje). + wymagane do trwałego zapisywania historii i unikania awarii `ENOENT`. +- **Niezgodność transkryptu**: ostrzega, gdy ostatnie wpisy sesji mają brakujące + pliki transkryptu. +- **Główna sesja „1-wierszowy JSONL”**: sygnalizuje, gdy główny transkrypt ma tylko jeden + wiersz (historia się nie gromadzi). - **Wiele katalogów stanu**: ostrzega, gdy istnieje wiele folderów `~/.openclaw` w różnych - katalogach domowych lub gdy `OPENCLAW_STATE_DIR` wskazuje gdzie indziej (historia może się rozdzielić między instalacje). + katalogach domowych lub gdy `OPENCLAW_STATE_DIR` wskazuje inne miejsce (historia może się + rozdzielać między instalacjami). - **Przypomnienie o trybie zdalnym**: jeśli `gateway.mode=remote`, doctor przypomina, aby uruchomić go na zdalnym hoście (tam znajduje się stan). -- **Uprawnienia pliku konfiguracji**: ostrzega, jeśli `~/.openclaw/openclaw.json` ma prawa - odczytu dla grupy/wszystkich, i oferuje ich zaostrzenie do `600`. +- **Uprawnienia pliku konfiguracji**: ostrzega, jeśli `~/.openclaw/openclaw.json` jest + czytelny dla grupy/świata i oferuje zaostrzenie do `600`. ### 5) Kondycja uwierzytelniania modeli (wygaśnięcie OAuth) -Doctor analizuje profile OAuth w magazynie auth, ostrzega, gdy tokeny -wygasają lub już wygasły, i może je odświeżyć, gdy jest to bezpieczne. Jeśli profil +Doctor sprawdza profile OAuth w magazynie uwierzytelniania, ostrzega, gdy tokeny +wygasają lub wygasły, i może je odświeżyć, gdy jest to bezpieczne. Jeśli profil OAuth/token Anthropic jest nieaktualny, sugeruje użycie klucza API Anthropic albo -ścieżki Anthropic setup-token. -Monity o odświeżenie pojawiają się tylko podczas uruchomienia interaktywnego (TTY); `--non-interactive` -pomija próby odświeżania. +ścieżki setup-token Anthropic. +Monity o odświeżenie pojawiają się tylko w trybie interaktywnym (TTY); `--non-interactive` +pomija próby odświeżenia. -Doctor raportuje także profile auth, które są tymczasowo niedostępne z powodu: +Doctor raportuje też profile uwierzytelniania, które są tymczasowo nieużywalne z powodu: -- krótkich cooldownów (rate limits/timeouts/błędy auth), -- dłuższych wyłączeń (błędy rozliczeń/braku środków). +- krótkich cooldownów (rate limits/timeouts/błędy uwierzytelniania) +- dłuższych wyłączeń (problemy z rozliczeniami/kredytem) ### 6) Walidacja modelu hooks Jeśli ustawiono `hooks.gmail.model`, doctor waliduje odwołanie do modelu względem -katalogu i allowlisty oraz ostrzega, gdy nie zostanie rozwiązane albo jest niedozwolone. +katalogu i listy dozwolonych modeli oraz ostrzega, gdy nie będzie się rozwiązywać lub jest niedozwolone. ### 7) Naprawa obrazu sandboxa -Gdy sandboxing jest włączony, doctor sprawdza obrazy Docker i oferuje ich zbudowanie albo -przełączenie na starsze nazwy, jeśli bieżący obraz nie istnieje. +Gdy sandboxing jest włączony, doctor sprawdza obrazy Docker i oferuje ich zbudowanie lub +przełączenie na starsze nazwy, jeśli obecny obraz nie istnieje. -### 7b) Zależności runtime pakietów pluginów bundlowanych +### 7b) Zależności uruchomieniowe bundlowanych pluginów -Doctor weryfikuje, czy zależności runtime bundlowanych pluginów (na przykład pakiety -runtime pluginu Discord) są obecne w katalogu głównym instalacji OpenClaw. -Jeśli którychś brakuje, doctor raportuje te pakiety i instaluje je w trybie +Doctor weryfikuje, czy zależności uruchomieniowe bundlowanych pluginów (na przykład +pakiety uruchomieniowe pluginu Discord) są obecne w katalogu głównym instalacji OpenClaw. +Jeśli którychś brakuje, doctor raportuje pakiety i instaluje je w trybie `openclaw doctor --fix` / `openclaw doctor --repair`. -### 8) Migracje usług gateway i wskazówki dotyczące czyszczenia +### 8) Migracje usług gatewaya i wskazówki dotyczące czyszczenia -Doctor wykrywa starsze usługi gateway (`launchd/systemd/schtasks`) i -oferuje ich usunięcie oraz instalację usługi OpenClaw przy użyciu bieżącego portu gateway. -Może też skanować w poszukiwaniu dodatkowych usług podobnych do gateway i wyświetlać wskazówki czyszczenia. -Usługi OpenClaw gateway nazwane według profilu są traktowane jako pełnoprawne i nie są +Doctor wykrywa starsze usługi gatewaya (launchd/systemd/schtasks) i +oferuje ich usunięcie oraz instalację usługi OpenClaw z użyciem bieżącego portu gatewaya. +Może też skanować w poszukiwaniu dodatkowych usług podobnych do gatewaya i wyświetlać wskazówki porządkowe. +Usługi gatewaya OpenClaw nazwane według profilu są traktowane jako pełnoprawne i nie są oznaczane jako „dodatkowe”. ### 8b) Migracja Matrix przy starcie Gdy konto kanału Matrix ma oczekującą lub możliwą do wykonania migrację starszego stanu, -doctor (w trybie `--fix` / `--repair`) tworzy migawkę przed migracją, a następnie -uruchamia kroki migracji best-effort: migrację starszego stanu Matrix oraz przygotowanie -starszego stanu zaszyfrowanego. Oba kroki nie są krytyczne; błędy są logowane, a -start jest kontynuowany. W trybie tylko do odczytu (`openclaw doctor` bez `--fix`) ta kontrola -jest całkowicie pomijana. +doctor (w trybie `--fix` / `--repair`) tworzy snapshot przed migracją, a następnie +uruchamia kroki migracji w trybie best-effort: migrację starszego stanu Matrix oraz przygotowanie starszego +stanu szyfrowanego. Oba kroki nie są krytyczne; błędy są logowane, a +uruchamianie jest kontynuowane. W trybie tylko do odczytu (`openclaw doctor` bez `--fix`) to sprawdzenie +jest całkowicie pomijane. ### 9) Ostrzeżenia bezpieczeństwa -Doctor emituje ostrzeżenia, gdy dostawca jest otwarty na wiadomości prywatne bez allowlisty lub -gdy polityka jest skonfigurowana w niebezpieczny sposób. +Doctor emituje ostrzeżenia, gdy dostawca jest otwarty na DM bez listy dozwolonych, +albo gdy zasada jest skonfigurowana w niebezpieczny sposób. ### 10) systemd linger (Linux) -Jeśli działa jako usługa użytkownika systemd, doctor upewnia się, że włączone jest lingering, -aby gateway pozostał aktywny po wylogowaniu. +Jeśli działa jako usługa użytkownika systemd, doctor upewnia się, że lingering jest włączony, aby +gateway pozostał aktywny po wylogowaniu. ### 11) Stan workspace (Skills, pluginy i starsze katalogi) Doctor wyświetla podsumowanie stanu workspace dla domyślnego agenta: -- **Stan Skills**: zlicza Skills kwalifikujące się, z brakującymi wymaganiami i zablokowane przez allowlistę. +- **Stan Skills**: liczba skills kwalifikujących się, z brakującymi wymaganiami i zablokowanych przez allowlistę. - **Starsze katalogi workspace**: ostrzega, gdy `~/openclaw` lub inne starsze katalogi workspace istnieją obok bieżącego workspace. -- **Stan pluginów**: zlicza pluginy załadowane/wyłączone/z błędami; wyświetla identyfikatory pluginów dla - błędów; raportuje możliwości bundle pluginów. -- **Ostrzeżenia o zgodności pluginów**: oznacza pluginy mające problemy zgodności z - bieżącym runtime. +- **Stan pluginów**: liczba załadowanych/wyłączonych/pluginów z błędami; wyświetla identyfikatory pluginów dla wszystkich + błędów; raportuje możliwości bundlowanych pluginów. +- **Ostrzeżenia o zgodności pluginów**: oznacza pluginy, które mają problemy ze zgodnością z + bieżącym środowiskiem uruchomieniowym. - **Diagnostyka pluginów**: pokazuje wszelkie ostrzeżenia lub błędy z czasu ładowania emitowane przez rejestr pluginów. ### 11b) Rozmiar pliku bootstrap Doctor sprawdza, czy pliki bootstrap workspace (na przykład `AGENTS.md`, -`CLAUDE.md` lub inne wstrzykiwane pliki kontekstu) są blisko skonfigurowanego -limitu znaków albo go przekraczają. Raportuje dla każdego pliku liczbę surowych i wstrzykniętych znaków, procent obcięcia, -przyczynę obcięcia (`max/file` lub `max/total`) oraz łączną liczbę wstrzykniętych +`CLAUDE.md` lub inne wstrzykiwane pliki kontekstowe) są blisko skonfigurowanego +limitu znaków lub go przekraczają. Raportuje dla każdego pliku liczbę surowych i wstrzykniętych znaków, +procent obcięcia, przyczynę obcięcia (`max/file` lub `max/total`) oraz łączną liczbę wstrzykniętych znaków jako ułamek całkowitego budżetu. Gdy pliki są obcięte lub blisko limitu, doctor wyświetla wskazówki dotyczące dostrojenia `agents.defaults.bootstrapMaxChars` i `agents.defaults.bootstrapTotalMaxChars`. @@ -399,101 +414,101 @@ Doctor sprawdza, czy autouzupełnianie tabulatorem jest zainstalowane dla bież (`source <(openclaw completion ...)`), doctor aktualizuje go do szybszego wariantu z plikiem cache. - Jeśli autouzupełnianie jest skonfigurowane w profilu, ale brakuje pliku cache, - doctor automatycznie regeneruje cache. + doctor automatycznie odtwarza cache. - Jeśli autouzupełnianie nie jest w ogóle skonfigurowane, doctor proponuje jego instalację - (tylko w trybie interaktywnym; pomijane przy `--non-interactive`). + (tylko w trybie interaktywnym; pomijane z `--non-interactive`). Uruchom `openclaw completion --write-state`, aby ręcznie odtworzyć cache. -### 12) Kontrole uwierzytelniania gateway (lokalny token) +### 12) Kontrole uwierzytelniania gatewaya (lokalny token) -Doctor sprawdza gotowość uwierzytelniania tokenem lokalnego gateway. +Doctor sprawdza gotowość lokalnego uwierzytelniania tokenem gatewaya. -- Jeśli tryb tokenu wymaga tokenu i nie istnieje jego źródło, doctor proponuje jego wygenerowanie. +- Jeśli tryb tokena potrzebuje tokena i nie istnieje żadne źródło tokena, doctor proponuje jego wygenerowanie. - Jeśli `gateway.auth.token` jest zarządzany przez SecretRef, ale niedostępny, doctor ostrzega i nie nadpisuje go jawnym tekstem. -- `openclaw doctor --generate-gateway-token` wymusza wygenerowanie tylko wtedy, gdy nie skonfigurowano SecretRef tokenu. +- `openclaw doctor --generate-gateway-token` wymusza generowanie tylko wtedy, gdy nie skonfigurowano tokena SecretRef. -### 12b) Naprawy tylko do odczytu, świadome SecretRef +### 12b) Naprawy świadome SecretRef w trybie tylko do odczytu -Niektóre przepływy naprawcze muszą sprawdzać skonfigurowane poświadczenia bez osłabiania zachowania fail-fast w runtime. +Niektóre ścieżki naprawy muszą sprawdzać skonfigurowane poświadczenia bez osłabiania zachowania fail-fast w runtime. -- `openclaw doctor --fix` używa teraz tego samego modelu podsumowania SecretRef tylko do odczytu, co polecenia z rodziny status, do ukierunkowanych napraw konfiguracji. -- Przykład: naprawa `allowFrom` / `groupAllowFrom` z `@username` w Telegram próbuje użyć skonfigurowanych poświadczeń bota, gdy są dostępne. -- Jeśli token bota Telegram jest skonfigurowany przez SecretRef, ale niedostępny w bieżącej ścieżce polecenia, doctor zgłasza, że poświadczenie jest skonfigurowane, ale niedostępne, i pomija automatyczne rozwiązanie zamiast kończyć się awarią lub błędnie raportować brak tokenu. +- `openclaw doctor --fix` używa teraz tego samego modelu podsumowania SecretRef tylko do odczytu co polecenia z rodziny status dla ukierunkowanych napraw konfiguracji. +- Przykład: naprawa Telegram `allowFrom` / `groupAllowFrom` `@username` próbuje użyć skonfigurowanych poświadczeń bota, jeśli są dostępne. +- Jeśli token bota Telegram jest skonfigurowany przez SecretRef, ale niedostępny w bieżącej ścieżce polecenia, doctor zgłasza, że poświadczenie jest skonfigurowane-ale-niedostępne, i pomija automatyczne rozwiązywanie zamiast kończyć się awarią lub błędnie raportować brak tokena. -### 13) Kontrola stanu gateway + restart +### 13) Kontrola stanu gatewaya + restart -Doctor uruchamia kontrolę stanu i oferuje restart gateway, gdy wygląda -na niezdatny do pracy. +Doctor uruchamia kontrolę stanu i oferuje restart gatewaya, gdy wygląda on na +niezdrowy. ### 13b) Gotowość wyszukiwania pamięci -Doctor sprawdza, czy skonfigurowany dostawca embeddingów dla wyszukiwania pamięci jest gotowy +Doctor sprawdza, czy skonfigurowany dostawca embeddingów wyszukiwania pamięci jest gotowy dla domyślnego agenta. Zachowanie zależy od skonfigurowanego backendu i dostawcy: - **Backend QMD**: sonduje, czy binarka `qmd` jest dostępna i daje się uruchomić. Jeśli nie, wyświetla wskazówki naprawcze, w tym pakiet npm i opcję ręcznej ścieżki do binarki. -- **Jawny dostawca lokalny**: sprawdza obecność lokalnego pliku modelu albo rozpoznawanego +- **Jawny dostawca lokalny**: sprawdza istnienie lokalnego pliku modelu lub rozpoznanego zdalnego/pobieralnego URL modelu. Jeśli go brakuje, sugeruje przełączenie na zdalnego dostawcę. - **Jawny dostawca zdalny** (`openai`, `voyage` itd.): weryfikuje, czy klucz API jest - obecny w środowisku lub magazynie auth. Jeśli go brakuje, wyświetla konkretne wskazówki naprawcze. -- **Dostawca automatyczny**: najpierw sprawdza dostępność modelu lokalnego, a potem próbuje każdego zdalnego - dostawcy zgodnie z kolejnością automatycznego wyboru. + obecny w środowisku lub magazynie uwierzytelniania. Jeśli go brakuje, wyświetla praktyczne wskazówki naprawcze. +- **Dostawca automatyczny**: najpierw sprawdza dostępność modelu lokalnego, a następnie próbuje każdego zdalnego + dostawcę w kolejności automatycznego wyboru. -Gdy wynik sondy gateway jest dostępny (gateway był zdrowy w momencie -sprawdzenia), doctor porównuje go z konfiguracją widoczną dla CLI i odnotowuje +Gdy wynik sondy gatewaya jest dostępny (gateway był zdrowy w momencie +sprawdzenia), doctor porównuje go z konfiguracją widoczną z CLI i odnotowuje wszelkie rozbieżności. Użyj `openclaw memory status --deep`, aby zweryfikować gotowość embeddingów w runtime. ### 14) Ostrzeżenia o stanie kanałów -Jeśli gateway jest zdrowy, doctor uruchamia sondę stanu kanałów i raportuje +Jeśli gateway jest zdrowy, doctor uruchamia sondę stanu kanałów i zgłasza ostrzeżenia wraz z sugerowanymi poprawkami. ### 15) Audyt konfiguracji supervisora + naprawa -Doctor sprawdza zainstalowaną konfigurację supervisora (`launchd/systemd/schtasks`) pod kątem -brakujących lub nieaktualnych ustawień domyślnych (np. zależności `network-online` w systemd oraz -opóźnienia restartu). Po wykryciu niedopasowania rekomenduje aktualizację i może -przepisać plik usługi/zadanie do bieżących wartości domyślnych. +Doctor sprawdza zainstalowaną konfigurację supervisora (launchd/systemd/schtasks) pod kątem +brakujących lub nieaktualnych ustawień domyślnych (np. zależności systemd od network-online i +opóźnienia restartu). Gdy wykryje niezgodność, rekomenduje aktualizację i może +przepisać plik usługi/zadanie do bieżących ustawień domyślnych. Uwagi: -- `openclaw doctor` pyta o potwierdzenie przed przepisaniem konfiguracji supervisora. -- `openclaw doctor --yes` akceptuje domyślne monity naprawcze. +- `openclaw doctor` pyta przed przepisaniem konfiguracji supervisora. +- `openclaw doctor --yes` akceptuje domyślne monity naprawy. - `openclaw doctor --repair` stosuje zalecane poprawki bez pytań. - `openclaw doctor --repair --force` nadpisuje niestandardowe konfiguracje supervisora. -- Jeśli uwierzytelnianie tokenem wymaga tokenu, a `gateway.auth.token` jest zarządzany przez SecretRef, ścieżka instalacji/naprawy usługi w doctor weryfikuje SecretRef, ale nie zapisuje rozwiązanego tokenu w postaci jawnego tekstu do metadanych środowiska usługi supervisora. -- Jeśli uwierzytelnianie tokenem wymaga tokenu, a skonfigurowany SecretRef tokenu nie został rozwiązany, doctor blokuje ścieżkę instalacji/naprawy i wyświetla konkretne wskazówki. -- Jeśli skonfigurowano jednocześnie `gateway.auth.token` i `gateway.auth.password`, a `gateway.auth.mode` nie jest ustawione, doctor blokuje instalację/naprawę, dopóki tryb nie zostanie jawnie ustawiony. -- Dla jednostek user-systemd na Linuksie kontrole rozjazdu tokenów w doctor obejmują teraz zarówno źródła `Environment=`, jak i `EnvironmentFile=` podczas porównywania metadanych uwierzytelniania usługi. +- Jeśli uwierzytelnianie tokenem wymaga tokena, a `gateway.auth.token` jest zarządzany przez SecretRef, doctor podczas instalacji/naprawy usługi waliduje SecretRef, ale nie zapisuje rozwiązanych jawnych wartości tokena do metadanych środowiska usługi supervisora. +- Jeśli uwierzytelnianie tokenem wymaga tokena, a skonfigurowany token SecretRef nie jest rozwiązany, doctor blokuje ścieżkę instalacji/naprawy z konkretnymi wskazówkami. +- Jeśli skonfigurowano zarówno `gateway.auth.token`, jak i `gateway.auth.password`, a `gateway.auth.mode` nie jest ustawione, doctor blokuje instalację/naprawę, dopóki tryb nie zostanie ustawiony jawnie. +- W przypadku jednostek user-systemd w Linux, kontrole dryfu tokena w doctor obejmują teraz zarówno źródła `Environment=`, jak i `EnvironmentFile=` przy porównywaniu metadanych uwierzytelniania usługi. - Zawsze możesz wymusić pełne przepisanie przez `openclaw gateway install --force`. -### 16) Diagnostyka runtime gateway i portu +### 16) Diagnostyka środowiska uruchomieniowego gatewaya + portu -Doctor analizuje runtime usługi (PID, ostatni status zakończenia) i ostrzega, gdy -usługa jest zainstalowana, ale faktycznie nie działa. Sprawdza także kolizje portu -gateway (domyślnie `18789`) i raportuje prawdopodobne przyczyny (gateway już działa, -tunel SSH). +Doctor sprawdza środowisko uruchomieniowe usługi (PID, ostatni status zakończenia) i ostrzega, gdy +usługa jest zainstalowana, ale faktycznie nie działa. Sprawdza też kolizje portu +gatewaya (domyślnie `18789`) i raportuje prawdopodobne przyczyny (gateway już +działa, tunel SSH). -### 17) Dobre praktyki runtime gateway +### 17) Najlepsze praktyki środowiska uruchomieniowego gatewaya -Doctor ostrzega, gdy usługa gateway działa na Bun albo na ścieżce Node zarządzanej przez menedżer wersji -(`nvm`, `fnm`, `volta`, `asdf` itd.). Kanały WhatsApp i Telegram wymagają Node, +Doctor ostrzega, gdy usługa gatewaya działa na Bun lub na ścieżce Node zarządzanej przez menedżer wersji +(`nvm`, `fnm`, `volta`, `asdf` itd.). Kanały WhatsApp + Telegram wymagają Node, a ścieżki menedżerów wersji mogą przestać działać po aktualizacjach, ponieważ usługa nie -ładuje inicjalizacji powłoki użytkownika. Doctor oferuje migrację do systemowej instalacji Node, jeśli +ładuje inicjalizacji powłoki. Doctor oferuje migrację do systemowej instalacji Node, gdy jest dostępna (Homebrew/apt/choco). ### 18) Zapis konfiguracji + metadane kreatora -Doctor zapisuje wszystkie zmiany konfiguracji i oznacza metadane kreatora, aby odnotować +Doctor utrwala wszystkie zmiany konfiguracji i zapisuje metadane kreatora, aby odnotować uruchomienie doctor. -### 19) Wskazówki dotyczące workspace (backup + system pamięci) +### 19) Wskazówki dotyczące workspace (kopia zapasowa + system pamięci) Doctor sugeruje system pamięci workspace, jeśli go brakuje, i wyświetla wskazówkę dotyczącą kopii zapasowej, -jeśli workspace nie jest już pod kontrolą git. +jeśli workspace nie jest już pod kontrolą gita. -Zobacz [/concepts/agent-workspace](/pl/concepts/agent-workspace), aby uzyskać pełny przewodnik po -strukturze workspace i kopiach zapasowych git (zalecane prywatne GitHub lub GitLab). +Zobacz [/concepts/agent-workspace](/pl/concepts/agent-workspace), aby przeczytać pełny przewodnik po +strukturze workspace i kopiach zapasowych w git (zalecane prywatne GitHub lub GitLab). diff --git a/docs/pl/gateway/heartbeat.md b/docs/pl/gateway/heartbeat.md index 06e8c0b17..96701245f 100644 --- a/docs/pl/gateway/heartbeat.md +++ b/docs/pl/gateway/heartbeat.md @@ -1,41 +1,41 @@ --- read_when: - Dostosowywanie częstotliwości heartbeat lub komunikatów - - Podejmowanie decyzji między heartbeat a cron dla zaplanowanych zadań + - Wybór między heartbeat a cron dla zaplanowanych zadań summary: Komunikaty odpytywania heartbeat i reguły powiadomień title: Heartbeat x-i18n: - generated_at: "2026-04-05T13:53:47Z" + generated_at: "2026-04-08T02:15:24Z" model: gpt-5.4 provider: openai - source_hash: f417b0d4453bed9022144d364521a59dec919d44cca8f00f0def005cd38b146f + source_hash: a8021d747637060eacb91ec5f75904368a08790c19f4fca32acda8c8c0a25e41 source_path: gateway/heartbeat.md workflow: 15 --- # Heartbeat (Gateway) -> **Heartbeat czy Cron?** Zobacz [Automation & Tasks](/pl/automation), aby uzyskać wskazówki, kiedy używać każdego z nich. +> **Heartbeat czy Cron?** Zobacz [Automatyzacja i zadania](/pl/automation), aby dowiedzieć się, kiedy używać każdego z nich. -Heartbeat uruchamia **okresowe tury agenta** w głównej sesji, dzięki czemu model może -pokazać wszystko, co wymaga uwagi, bez spamowania Cię. +Heartbeat uruchamia **okresowe tury agenta** w głównej sesji, aby model mógł +zwracać uwagę na wszystko, co wymaga uwagi, bez spamowania Cię. -Heartbeat to zaplanowana tura głównej sesji — **nie** tworzy rekordów [background task](/pl/automation/tasks). +Heartbeat to zaplanowana tura głównej sesji — **nie** tworzy rekordów [zadań w tle](/pl/automation/tasks). Rekordy zadań służą do pracy odłączonej (uruchomienia ACP, subagenci, izolowane zadania cron). -Rozwiązywanie problemów: [Scheduled Tasks](/pl/automation/cron-jobs#troubleshooting) +Rozwiązywanie problemów: [Zaplanowane zadania](/pl/automation/cron-jobs#troubleshooting) ## Szybki start (dla początkujących) -1. Pozostaw heartbeat włączony (domyślnie `30m` albo `1h` dla uwierzytelniania Anthropic OAuth/token, w tym ponownego użycia Claude CLI) albo ustaw własną częstotliwość. -2. Utwórz małą listę kontrolną `HEARTBEAT.md` lub blok `tasks:` w workspace agenta (opcjonalne, ale zalecane). -3. Zdecyduj, dokąd mają trafiać komunikaty heartbeat (`target: "none"` jest wartością domyślną; ustaw `target: "last"`, aby kierować je do ostatniego kontaktu). -4. Opcjonalnie włącz dostarczanie rozumowania heartbeat dla większej przejrzystości. -5. Opcjonalnie użyj lekkiego kontekstu bootstrap, jeśli uruchomienia heartbeat potrzebują tylko `HEARTBEAT.md`. -6. Opcjonalnie włącz izolowane sesje, aby nie wysyłać pełnej historii rozmowy przy każdym heartbeat. -7. Opcjonalnie ogranicz heartbeat do aktywnych godzin (czas lokalny). +1. Pozostaw heartbeat włączony (domyślnie `30m` lub `1h` dla uwierzytelniania Anthropic OAuth/token, w tym ponownego użycia Claude CLI) albo ustaw własną częstotliwość. +2. Utwórz małą listę kontrolną `HEARTBEAT.md` lub blok `tasks:` w obszarze roboczym agenta (opcjonalne, ale zalecane). +3. Zdecyduj, gdzie mają trafiać komunikaty heartbeat (`target: "none"` jest domyślne; ustaw `target: "last"`, aby kierować je do ostatniego kontaktu). +4. Opcjonalnie: włącz dostarczanie rozumowania heartbeat dla większej przejrzystości. +5. Opcjonalnie: użyj lekkiego kontekstu początkowego, jeśli uruchomienia heartbeat potrzebują tylko `HEARTBEAT.md`. +6. Opcjonalnie: włącz izolowane sesje, aby nie wysyłać całej historii rozmowy przy każdym heartbeat. +7. Opcjonalnie: ogranicz heartbeat do aktywnych godzin (czas lokalny). -Przykładowy config: +Przykładowa konfiguracja: ```json5 { @@ -43,58 +43,61 @@ Przykładowy config: defaults: { heartbeat: { every: "30m", - target: "last", // jawne dostarczanie do ostatniego kontaktu (domyślnie jest "none") - directPolicy: "allow", // domyślnie: zezwalaj na cele direct/DM; ustaw "block", aby wyciszyć - lightContext: true, // opcjonalnie: wstrzykuj tylko HEARTBEAT.md z plików bootstrap - isolatedSession: true, // opcjonalnie: nowa sesja przy każdym uruchomieniu (bez historii rozmowy) + target: "last", // jawne dostarczanie do ostatniego kontaktu (domyślnie "none") + directPolicy: "allow", // domyślnie: zezwalaj na cele bezpośrednie/DM; ustaw "block", aby je wyciszyć + lightContext: true, // opcjonalne: wstrzykuj tylko HEARTBEAT.md z plików bootstrap kontekstu + isolatedSession: true, // opcjonalne: świeża sesja przy każdym uruchomieniu (bez historii rozmowy) // activeHours: { start: "08:00", end: "24:00" }, - // includeReasoning: true, // opcjonalnie: wyślij też osobny komunikat `Reasoning:` + // includeReasoning: true, // opcjonalne: wysyłaj też osobny komunikat `Reasoning:` }, }, }, } ``` -## Wartości domyślne +## Ustawienia domyślne -- Interwał: `30m` (albo `1h`, gdy wykrytym trybem uwierzytelniania jest Anthropic OAuth/token, w tym ponowne użycie Claude CLI). Ustaw `agents.defaults.heartbeat.every` albo per agent `agents.list[].heartbeat.every`; użyj `0m`, aby wyłączyć. +- Interwał: `30m` (lub `1h`, gdy wykrytym trybem uwierzytelniania jest Anthropic OAuth/token, w tym ponowne użycie Claude CLI). Ustaw `agents.defaults.heartbeat.every` lub dla konkretnego agenta `agents.list[].heartbeat.every`; użyj `0m`, aby wyłączyć. - Treść promptu (konfigurowalna przez `agents.defaults.heartbeat.prompt`): `Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.` - Prompt heartbeat jest wysyłany **dosłownie** jako wiadomość użytkownika. Prompt - systemowy zawiera sekcję „Heartbeat”, a uruchomienie jest oznaczane wewnętrznie. + systemowy zawiera sekcję „Heartbeat” tylko wtedy, gdy heartbeat jest włączony dla + domyślnego agenta, a uruchomienie jest oznaczone wewnętrznie. +- Gdy heartbeat jest wyłączony przez `0m`, zwykłe uruchomienia także pomijają `HEARTBEAT.md` + z kontekstu bootstrap, aby model nie widział instrukcji przeznaczonych wyłącznie dla heartbeat. - Aktywne godziny (`heartbeat.activeHours`) są sprawdzane w skonfigurowanej strefie czasowej. - Poza oknem heartbeat są pomijane aż do następnego tyknięcia wewnątrz okna. + Poza tym oknem heartbeat jest pomijany aż do następnego tyknięcia w obrębie okna. ## Do czego służy prompt heartbeat Domyślny prompt jest celowo szeroki: -- **Background tasks**: „Consider outstanding tasks” skłania agenta do przeglądania - zadań do wykonania (skrzynka odbiorcza, kalendarz, przypomnienia, kolejka pracy) i sygnalizowania wszystkiego, co pilne. -- **Sprawdzenie u człowieka**: „Checkup sometimes on your human during day time” skłania do - okazjonalnego lekkiego komunikatu „czy czegoś potrzebujesz?”, ale unika nocnego spamu - dzięki użyciu Twojej skonfigurowanej lokalnej strefy czasowej (zobacz [/concepts/timezone](/concepts/timezone)). +- **Zadania w tle**: „Rozważ zaległe zadania” zachęca agenta do przeglądu + działań następczych (skrzynka odbiorcza, kalendarz, przypomnienia, kolejka pracy) i sygnalizowania wszystkiego, co pilne. +- **Kontakt z człowiekiem**: „Sprawdź czasem swojego człowieka w ciągu dnia” zachęca do + okazjonalnego lekkiego komunikatu w rodzaju „czy czegoś potrzebujesz?”, ale unika nocnego spamu + dzięki użyciu skonfigurowanej lokalnej strefy czasowej (zobacz [/concepts/timezone](/pl/concepts/timezone)). -Heartbeat może reagować na ukończone [background tasks](/pl/automation/tasks), ale samo uruchomienie heartbeat nie tworzy rekordu zadania. +Heartbeat może reagować na ukończone [zadania w tle](/pl/automation/tasks), ale samo uruchomienie heartbeat nie tworzy rekordu zadania. Jeśli chcesz, aby heartbeat robił coś bardzo konkretnego (np. „sprawdź statystyki Gmail PubSub” -albo „zweryfikuj stan gateway”), ustaw `agents.defaults.heartbeat.prompt` (lub -`agents.list[].heartbeat.prompt`) na niestandardową treść (wysyłaną dosłownie). +lub „zweryfikuj stan gateway”), ustaw `agents.defaults.heartbeat.prompt` (lub +`agents.list[].heartbeat.prompt`) na własną treść (wysyłaną dosłownie). ## Kontrakt odpowiedzi - Jeśli nic nie wymaga uwagi, odpowiedz **`HEARTBEAT_OK`**. - Podczas uruchomień heartbeat OpenClaw traktuje `HEARTBEAT_OK` jako potwierdzenie, gdy pojawia się - na **początku lub końcu** odpowiedzi. Token jest usuwany, a odpowiedź jest + na **początku lub końcu** odpowiedzi. Token jest usuwany, a odpowiedź odrzucana, jeśli pozostała treść ma **≤ `ackMaxChars`** (domyślnie: 300). -- Jeśli `HEARTBEAT_OK` pojawia się **w środku** odpowiedzi, nie jest traktowane - w specjalny sposób. -- W przypadku alertów **nie** dołączaj `HEARTBEAT_OK`; zwróć tylko tekst alertu. +- Jeśli `HEARTBEAT_OK` pojawia się **w środku** odpowiedzi, nie jest traktowany + specjalnie. +- W przypadku alertów **nie** dołączaj `HEARTBEAT_OK`; zwróć tylko treść alertu. Poza heartbeat przypadkowe `HEARTBEAT_OK` na początku/końcu wiadomości jest usuwane -i logowane; wiadomość zawierająca wyłącznie `HEARTBEAT_OK` jest odrzucana. +i logowane; wiadomość będąca wyłącznie `HEARTBEAT_OK` jest odrzucana. -## Config +## Konfiguracja ```json5 { @@ -103,14 +106,14 @@ i logowane; wiadomość zawierająca wyłącznie `HEARTBEAT_OK` jest odrzucana. heartbeat: { every: "30m", // domyślnie: 30m (0m wyłącza) model: "anthropic/claude-opus-4-6", - includeReasoning: false, // domyślnie: false (dostarczaj osobny komunikat Reasoning: gdy dostępny) - lightContext: false, // domyślnie: false; true zachowuje tylko HEARTBEAT.md z plików bootstrap workspace - isolatedSession: false, // domyślnie: false; true uruchamia każdy heartbeat w nowej sesji (bez historii rozmowy) - target: "last", // domyślnie: none | opcje: last | none | (core lub wtyczka, np. "bluebubbles") + includeReasoning: false, // domyślnie: false (dostarczaj osobny komunikat Reasoning:, gdy dostępny) + lightContext: false, // domyślnie: false; true zachowuje tylko HEARTBEAT.md z plików bootstrap obszaru roboczego + isolatedSession: false, // domyślnie: false; true uruchamia każdy heartbeat w świeżej sesji (bez historii rozmowy) + target: "last", // domyślnie: none | opcje: last | none | (rdzeń lub plugin, np. "bluebubbles") to: "+15551234567", // opcjonalne nadpisanie specyficzne dla kanału - accountId: "ops-bot", // opcjonalny identyfikator kanału wielokontowego + accountId: "ops-bot", // opcjonalny identyfikator kanału dla wielu kont prompt: "Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.", - ackMaxChars: 300, // maks. liczba znaków dozwolona po HEARTBEAT_OK + ackMaxChars: 300, // maksymalna liczba znaków dozwolona po HEARTBEAT_OK }, }, }, @@ -120,18 +123,18 @@ i logowane; wiadomość zawierająca wyłącznie `HEARTBEAT_OK` jest odrzucana. ### Zakres i pierwszeństwo - `agents.defaults.heartbeat` ustawia globalne zachowanie heartbeat. -- `agents.list[].heartbeat` scala się na wierzchu; jeśli którykolwiek agent ma blok `heartbeat`, **tylko ci agenci** uruchamiają heartbeat. -- `channels.defaults.heartbeat` ustawia domyślne ustawienia widoczności dla wszystkich kanałów. -- `channels..heartbeat` nadpisuje domyślne ustawienia kanału. -- `channels..accounts..heartbeat` (kanały wielokontowe) nadpisuje ustawienia per kanał. +- `agents.list[].heartbeat` nakłada się na to; jeśli jakikolwiek agent ma blok `heartbeat`, heartbeat uruchamiają **tylko ci agenci**. +- `channels.defaults.heartbeat` ustawia domyślną widoczność dla wszystkich kanałów. +- `channels..heartbeat` nadpisuje ustawienia domyślne kanałów. +- `channels..accounts..heartbeat` (kanały z wieloma kontami) nadpisuje ustawienia dla danego kanału. -### Heartbeat per agent +### Heartbeat dla konkretnego agenta -Jeśli którykolwiek wpis `agents.list[]` zawiera blok `heartbeat`, **tylko ci agenci** -uruchamiają heartbeat. Blok per agent scala się na wierzchu `agents.defaults.heartbeat` -(dzięki czemu możesz ustawić wspólne wartości domyślne raz i nadpisać je per agent). +Jeśli dowolny wpis `agents.list[]` zawiera blok `heartbeat`, heartbeat uruchamiają +**tylko ci agenci**. Blok per-agent nakłada się na `agents.defaults.heartbeat` +(dzięki czemu możesz raz ustawić wspólne wartości domyślne i nadpisać je dla poszczególnych agentów). -Przykład: dwóch agentów, tylko drugi agent uruchamia heartbeat. +Przykład: dwóch agentów, heartbeat uruchamia tylko drugi agent. ```json5 { @@ -139,7 +142,7 @@ Przykład: dwóch agentów, tylko drugi agent uruchamia heartbeat. defaults: { heartbeat: { every: "30m", - target: "last", // jawne dostarczanie do ostatniego kontaktu (domyślnie jest "none") + target: "last", // jawne dostarczanie do ostatniego kontaktu (domyślnie "none") }, }, list: [ @@ -168,11 +171,11 @@ Ogranicz heartbeat do godzin pracy w określonej strefie czasowej: defaults: { heartbeat: { every: "30m", - target: "last", // jawne dostarczanie do ostatniego kontaktu (domyślnie jest "none") + target: "last", // jawne dostarczanie do ostatniego kontaktu (domyślnie "none") activeHours: { start: "09:00", end: "22:00", - timezone: "America/New_York", // opcjonalne; używa userTimezone, jeśli ustawiono, w przeciwnym razie strefy hosta + timezone: "America/New_York", // opcjonalne; używa userTimezone, jeśli jest ustawione, w przeciwnym razie strefy hosta }, }, }, @@ -180,21 +183,21 @@ Ogranicz heartbeat do godzin pracy w określonej strefie czasowej: } ``` -Poza tym oknem (przed 9:00 lub po 22:00 czasu wschodniego) heartbeat są pomijane. Następne zaplanowane tyknięcie wewnątrz okna uruchomi się normalnie. +Poza tym oknem (przed 9:00 lub po 22:00 czasu wschodniego) heartbeat jest pomijany. Następne zaplanowane tyknięcie w obrębie okna uruchomi się normalnie. ### Konfiguracja 24/7 -Jeśli chcesz, aby heartbeat działał przez cały dzień, użyj jednego z tych wzorców: +Jeśli chcesz, aby heartbeat działał przez całą dobę, użyj jednego z tych wzorców: -- Pomiń `activeHours` całkowicie (brak ograniczenia oknem czasowym; to zachowanie domyślne). -- Ustaw okno całodniowe: `activeHours: { start: "00:00", end: "24:00" }`. +- Całkowicie pomiń `activeHours` (brak ograniczenia okna czasowego; to zachowanie domyślne). +- Ustaw pełnodobowe okno: `activeHours: { start: "00:00", end: "24:00" }`. -Nie ustawiaj tej samej godziny `start` i `end` (na przykład `08:00` do `08:00`). -Jest to traktowane jako okno o zerowej szerokości, więc heartbeat są zawsze pomijane. +Nie ustawiaj tej samej godziny dla `start` i `end` (na przykład `08:00` do `08:00`). +Jest to traktowane jako okno o zerowej szerokości, więc heartbeat jest zawsze pomijany. ### Przykład wielu kont -Użyj `accountId`, aby kierować na konkretne konto w kanałach wielokontowych, takich jak Telegram: +Użyj `accountId`, aby kierować do konkretnego konta w kanałach z wieloma kontami, takich jak Telegram: ```json5 { @@ -205,7 +208,7 @@ Użyj `accountId`, aby kierować na konkretne konto w kanałach wielokontowych, heartbeat: { every: "1h", target: "telegram", - to: "12345678:topic:42", // opcjonalnie: kieruj do konkretnego tematu/wątku + to: "12345678:topic:42", // opcjonalne: kierowanie do konkretnego tematu/wątku accountId: "ops-bot", }, }, @@ -221,58 +224,58 @@ Użyj `accountId`, aby kierować na konkretne konto w kanałach wielokontowych, } ``` -### Uwagi dotyczące pól +### Uwagi do pól - `every`: interwał heartbeat (ciąg czasu trwania; domyślna jednostka = minuty). - `model`: opcjonalne nadpisanie modelu dla uruchomień heartbeat (`provider/model`). -- `includeReasoning`: gdy włączone, dostarcza również osobny komunikat `Reasoning:` gdy jest dostępny (ten sam kształt co `/reasoning on`). -- `lightContext`: gdy true, uruchomienia heartbeat używają lekkiego kontekstu bootstrap i zachowują tylko `HEARTBEAT.md` z plików bootstrap workspace. -- `isolatedSession`: gdy true, każdy heartbeat działa w nowej sesji bez wcześniejszej historii rozmowy. Używa tego samego wzorca izolacji co cron `sessionTarget: "isolated"`. Radykalnie obniża koszt tokenów per heartbeat. Połącz z `lightContext: true`, aby uzyskać maksymalne oszczędności. Routing dostarczania nadal używa kontekstu głównej sesji. +- `includeReasoning`: gdy włączone, dostarcza też osobny komunikat `Reasoning:`, gdy jest dostępny (ten sam format co `/reasoning on`). +- `lightContext`: gdy true, uruchomienia heartbeat używają lekkiego kontekstu bootstrap i zachowują tylko `HEARTBEAT.md` z plików bootstrap obszaru roboczego. +- `isolatedSession`: gdy true, każdy heartbeat działa w świeżej sesji bez wcześniejszej historii rozmowy. Używa tego samego wzorca izolacji co cron `sessionTarget: "isolated"`. Drastycznie zmniejsza koszt tokenów na jeden heartbeat. Połącz z `lightContext: true`, aby uzyskać maksymalne oszczędności. Routowanie dostarczania nadal używa kontekstu głównej sesji. - `session`: opcjonalny klucz sesji dla uruchomień heartbeat. - `main` (domyślnie): główna sesja agenta. - - Jawny klucz sesji (skopiuj z `openclaw sessions --json` lub z [CLI sesji](/cli/sessions)). - - Formaty kluczy sesji: zobacz [Sessions](/concepts/session) i [Groups](/pl/channels/groups). + - Jawny klucz sesji (skopiuj z `openclaw sessions --json` lub z [sessions CLI](/cli/sessions)). + - Formaty kluczy sesji: zobacz [Sesje](/pl/concepts/session) i [Grupy](/pl/channels/groups). - `target`: - `last`: dostarczaj do ostatnio użytego zewnętrznego kanału. - - jawny kanał: dowolny skonfigurowany kanał lub identyfikator wtyczki, na przykład `discord`, `matrix`, `telegram` albo `whatsapp`. - - `none` (domyślnie): uruchom heartbeat, ale **nie dostarczaj** niczego na zewnątrz. -- `directPolicy`: steruje zachowaniem dostarczania direct/DM: - - `allow` (domyślnie): zezwalaj na dostarczanie heartbeat do celów direct/DM. - - `block`: wycisz dostarczanie direct/DM (`reason=dm-blocked`). -- `to`: opcjonalne nadpisanie odbiorcy (identyfikator specyficzny dla kanału, np. E.164 dla WhatsApp albo identyfikator czatu Telegram). Dla tematów/wątków Telegram użyj `:topic:`. -- `accountId`: opcjonalny identyfikator konta dla kanałów wielokontowych. Gdy `target: "last"`, identyfikator konta ma zastosowanie do rozpoznanego ostatniego kanału, jeśli obsługuje konta; w przeciwnym razie jest ignorowany. Jeśli identyfikator konta nie pasuje do skonfigurowanego konta dla rozpoznanego kanału, dostarczenie jest pomijane. + - jawny kanał: dowolny skonfigurowany kanał lub identyfikator pluginu, na przykład `discord`, `matrix`, `telegram` lub `whatsapp`. + - `none` (domyślnie): uruchom heartbeat, ale **nie dostarczaj** go na zewnątrz. +- `directPolicy`: steruje zachowaniem dostarczania bezpośredniego/DM: + - `allow` (domyślnie): zezwalaj na bezpośrednie/DM dostarczanie heartbeat. + - `block`: wycisz dostarczanie bezpośrednie/DM (`reason=dm-blocked`). +- `to`: opcjonalne nadpisanie odbiorcy (identyfikator specyficzny dla kanału, np. E.164 dla WhatsApp lub identyfikator czatu Telegram). Dla tematów/wątków Telegram użyj `:topic:`. +- `accountId`: opcjonalny identyfikator konta dla kanałów z wieloma kontami. Gdy `target: "last"`, identyfikator konta ma zastosowanie do rozstrzygniętego ostatniego kanału, jeśli obsługuje konta; w przeciwnym razie jest ignorowany. Jeśli identyfikator konta nie pasuje do skonfigurowanego konta dla rozstrzygniętego kanału, dostarczenie jest pomijane. - `prompt`: nadpisuje domyślną treść promptu (bez scalania). -- `ackMaxChars`: maks. liczba znaków dozwolona po `HEARTBEAT_OK` przed dostarczeniem. +- `ackMaxChars`: maksymalna liczba znaków dozwolona po `HEARTBEAT_OK` przed dostarczeniem. - `suppressToolErrorWarnings`: gdy true, wycisza ładunki ostrzeżeń o błędach narzędzi podczas uruchomień heartbeat. -- `activeHours`: ogranicza uruchomienia heartbeat do okna czasowego. Obiekt z `start` (HH:MM, włącznie; użyj `00:00` dla początku dnia), `end` (HH:MM, wyłącznie; `24:00` jest dozwolone dla końca dnia) oraz opcjonalnym `timezone`. - - Pominięte lub `"user"`: używa Twojego `agents.defaults.userTimezone`, jeśli ustawiono, w przeciwnym razie wraca do strefy czasowej systemu hosta. +- `activeHours`: ogranicza uruchomienia heartbeat do okna czasowego. Obiekt z `start` (HH:MM, włącznie; użyj `00:00` dla początku dnia), `end` (HH:MM, wyłącznie; `24:00` dozwolone dla końca dnia) oraz opcjonalnym `timezone`. + - Pominięte lub `"user"`: używa Twojego `agents.defaults.userTimezone`, jeśli jest ustawione, w przeciwnym razie wraca do strefy czasowej systemu hosta. - `"local"`: zawsze używa strefy czasowej systemu hosta. - - Dowolny identyfikator IANA (np. `America/New_York`): używany bezpośrednio; jeśli jest nieprawidłowy, następuje fallback do zachowania `"user"` opisanego powyżej. + - Dowolny identyfikator IANA (np. `America/New_York`): używany bezpośrednio; jeśli jest nieprawidłowy, wraca do zachowania `"user"` opisanego wyżej. - `start` i `end` nie mogą być równe dla aktywnego okna; równe wartości są traktowane jako zerowa szerokość (zawsze poza oknem). - - Poza aktywnym oknem heartbeat są pomijane aż do następnego tyknięcia wewnątrz okna. + - Poza aktywnym oknem heartbeat jest pomijany aż do następnego tyknięcia w obrębie okna. ## Zachowanie dostarczania -- Heartbeat są domyślnie uruchamiane w głównej sesji agenta (`agent::`), - albo `global`, gdy `session.scope = "global"`. Ustaw `session`, aby nadpisać na - konkretną sesję kanału (Discord/WhatsApp/itd.). +- Heartbeat domyślnie działa w głównej sesji agenta (`agent::`), + lub `global`, gdy `session.scope = "global"`. Ustaw `session`, aby nadpisać na + konkretną sesję kanału (Discord/WhatsApp/itp.). - `session` wpływa tylko na kontekst uruchomienia; dostarczaniem sterują `target` i `to`. -- Aby dostarczyć do konkretnego kanału/odbiorcy, ustaw `target` + `to`. Przy - `target: "last"` dostarczenie używa ostatniego zewnętrznego kanału dla tej sesji. -- Dostarczanie heartbeat domyślnie zezwala na cele direct/DM. Ustaw `directPolicy: "block"`, aby wyciszyć wysyłanie do celów direct przy jednoczesnym zachowaniu tury heartbeat. +- Aby dostarczać do konkretnego kanału/odbiorcy, ustaw `target` + `to`. Przy + `target: "last"` dostarczanie używa ostatniego zewnętrznego kanału dla tej sesji. +- Dostarczenia heartbeat domyślnie zezwalają na cele bezpośrednie/DM. Ustaw `directPolicy: "block"`, aby wyciszyć wysyłki do celów bezpośrednich, nadal uruchamiając turę heartbeat. - Jeśli główna kolejka jest zajęta, heartbeat jest pomijany i ponawiany później. -- Jeśli `target` nie rozpozna żadnego zewnętrznego miejsca docelowego, uruchomienie nadal następuje, ale żadna +- Jeśli `target` nie rozstrzyga się do zewnętrznego miejsca docelowego, uruchomienie nadal następuje, ale wiadomość wychodząca nie jest wysyłana. -- Jeśli `showOk`, `showAlerts` i `useIndicator` są wszystkie wyłączone, uruchomienie jest pomijane od razu z `reason=alerts-disabled`. -- Jeśli wyłączone jest tylko dostarczanie alertów, OpenClaw nadal może uruchomić heartbeat, zaktualizować znaczniki czasu zadań wymagających wykonania, przywrócić znacznik bezczynności sesji i wyciszyć zewnętrzny ładunek alertu. -- Odpowiedzi tylko-heartbeat **nie** utrzymują sesji przy życiu; ostatnie `updatedAt` - jest przywracane, aby wygaśnięcie bezczynności zachowywało się normalnie. -- Odłączone [background tasks](/pl/automation/tasks) mogą umieścić zdarzenie systemowe w kolejce i wybudzić heartbeat, gdy główna sesja powinna szybko coś zauważyć. To wybudzenie nie sprawia, że heartbeat staje się background task. +- Jeśli `showOk`, `showAlerts` i `useIndicator` są wszystkie wyłączone, uruchomienie jest od razu pomijane jako `reason=alerts-disabled`. +- Jeśli wyłączone jest tylko dostarczanie alertów, OpenClaw nadal może uruchomić heartbeat, zaktualizować znaczniki czasu zadań należnych, przywrócić znacznik bezczynności sesji i wyciszyć zewnętrzny ładunek alertu. +- Odpowiedzi wyłącznie heartbeat **nie** utrzymują sesji przy życiu; ostatnie `updatedAt` + jest przywracane, aby wygaśnięcie bezczynności działało normalnie. +- Odłączone [zadania w tle](/pl/automation/tasks) mogą umieszczać zdarzenie systemowe w kolejce i wybudzać heartbeat, gdy główna sesja powinna szybko coś zauważyć. Takie wybudzenie nie sprawia, że heartbeat staje się zadaniem w tle. -## Sterowanie widocznością +## Kontrola widoczności -Domyślnie potwierdzenia `HEARTBEAT_OK` są ukrywane, podczas gdy treść alertów jest -dostarczana. Możesz to dostosować per kanał lub per konto: +Domyślnie potwierdzenia `HEARTBEAT_OK` są wyciszane, a treść alertów jest +dostarczana. Możesz dostosować to dla kanału lub konta: ```yaml channels: @@ -283,7 +286,7 @@ channels: useIndicator: true # Emituj zdarzenia wskaźnika (domyślnie) telegram: heartbeat: - showOk: true # Pokazuj potwierdzenia OK na Telegramie + showOk: true # Pokazuj potwierdzenia OK w Telegramie whatsapp: accounts: work: @@ -291,17 +294,17 @@ channels: showAlerts: false # Wycisz dostarczanie alertów dla tego konta ``` -Pierwszeństwo: per konto → per kanał → domyślne kanału → wbudowane wartości domyślne. +Pierwszeństwo: per-account → per-channel → domyślne kanału → wbudowane wartości domyślne. ### Co robi każda flaga -- `showOk`: wysyła potwierdzenie `HEARTBEAT_OK`, gdy model zwraca odpowiedź zawierającą wyłącznie OK. +- `showOk`: wysyła potwierdzenie `HEARTBEAT_OK`, gdy model zwraca odpowiedź zawierającą tylko OK. - `showAlerts`: wysyła treść alertu, gdy model zwraca odpowiedź inną niż OK. - `useIndicator`: emituje zdarzenia wskaźnika dla powierzchni statusu UI. Jeśli **wszystkie trzy** mają wartość false, OpenClaw całkowicie pomija uruchomienie heartbeat (bez wywołania modelu). -### Przykłady per kanał vs per konto +### Przykłady per-channel i per-account ```yaml channels: @@ -324,39 +327,44 @@ channels: ### Typowe wzorce -| Cel | Config | +| Cel | Konfiguracja | | ---------------------------------------- | ---------------------------------------------------------------------------------------- | -| Domyślne zachowanie (ciche OK, alerty włączone) | _(brak wymaganego config)_ | -| Całkowicie cicho (bez wiadomości, bez wskaźnika) | `channels.defaults.heartbeat: { showOk: false, showAlerts: false, useIndicator: false }` | +| Zachowanie domyślne (ciche OK, alerty włączone) | _(nie jest wymagana konfiguracja)_ | +| Pełna cisza (bez wiadomości, bez wskaźnika) | `channels.defaults.heartbeat: { showOk: false, showAlerts: false, useIndicator: false }` | | Tylko wskaźnik (bez wiadomości) | `channels.defaults.heartbeat: { showOk: false, showAlerts: false, useIndicator: true }` | | OK tylko w jednym kanale | `channels.telegram.heartbeat: { showOk: true }` | -## HEARTBEAT.md (opcjonalne) +## HEARTBEAT.md (opcjonalnie) -Jeśli plik `HEARTBEAT.md` istnieje w workspace, domyślny prompt instruuje -agenta, aby go odczytał. Pomyśl o nim jak o swojej „liście kontrolnej heartbeat”: małej, stabilnej i -bezpiecznej do dołączania co 30 minut. +Jeśli plik `HEARTBEAT.md` istnieje w obszarze roboczym, domyślny prompt mówi +agentowi, aby go przeczytał. Potraktuj go jako swoją „listę kontrolną heartbeat”: małą, stabilną i +bezpieczną do dołączania co 30 minut. -Jeśli `HEARTBEAT.md` istnieje, ale jest praktycznie pusty (tylko puste linie i nagłówki markdown -takie jak `# Heading`), OpenClaw pomija uruchomienie heartbeat, aby oszczędzić wywołania API. -To pominięcie jest raportowane jako `reason=empty-heartbeat-file`. -Jeśli plik nie istnieje, heartbeat nadal działa, a model sam decyduje, co zrobić. +Przy zwykłych uruchomieniach `HEARTBEAT.md` jest wstrzykiwany tylko wtedy, gdy wskazówki heartbeat są +włączone dla domyślnego agenta. Wyłączenie częstotliwości heartbeat przez `0m` lub +ustawienie `includeSystemPromptSection: false` pomija go w zwykłym kontekście +bootstrap. -Utrzymuj go w małym rozmiarze (krótka lista kontrolna albo przypomnienia), aby uniknąć rozrostu promptu. +Jeśli `HEARTBEAT.md` istnieje, ale jest w praktyce pusty (tylko puste linie i nagłówki +Markdown takie jak `# Heading`), OpenClaw pomija uruchomienie heartbeat, aby oszczędzić wywołania API. +Takie pominięcie jest zgłaszane jako `reason=empty-heartbeat-file`. +Jeśli pliku brakuje, heartbeat nadal działa, a model decyduje, co zrobić. + +Utrzymuj go w małym rozmiarze (krótka lista kontrolna lub przypomnienia), aby uniknąć rozrostu promptu. Przykładowy `HEARTBEAT.md`: ```md -# Heartbeat checklist +# Lista kontrolna heartbeat -- Quick scan: anything urgent in inboxes? -- If it’s daytime, do a lightweight check-in if nothing else is pending. -- If a task is blocked, write down _what is missing_ and ask Peter next time. +- Szybki przegląd: czy w skrzynkach odbiorczych jest coś pilnego? +- Jeśli jest dzień, wykonaj lekki check-in, jeśli nic innego nie czeka. +- Jeśli zadanie jest zablokowane, zapisz _czego brakuje_ i zapytaj Petera następnym razem. ``` ### Bloki `tasks:` -`HEARTBEAT.md` obsługuje także mały ustrukturyzowany blok `tasks:` dla kontroli +`HEARTBEAT.md` obsługuje także mały strukturalny blok `tasks:` dla sprawdzeń opartych na interwałach wewnątrz samego heartbeat. Przykład: @@ -366,77 +374,76 @@ tasks: - name: inbox-triage interval: 30m - prompt: "Check for urgent unread emails and flag anything time sensitive." + prompt: "Sprawdź pilne nieprzeczytane e-maile i oznacz wszystko, co jest wrażliwe czasowo." - name: calendar-scan interval: 2h - prompt: "Check for upcoming meetings that need prep or follow-up." + prompt: "Sprawdź nadchodzące spotkania, które wymagają przygotowania lub działań następczych." -# Additional instructions +# Dodatkowe instrukcje -- Keep alerts short. -- If nothing needs attention after all due tasks, reply HEARTBEAT_OK. +- Utrzymuj alerty krótkie. +- Jeśli po wszystkich należnych zadaniach nic nie wymaga uwagi, odpowiedz HEARTBEAT_OK. ``` Zachowanie: -- OpenClaw parsuje blok `tasks:` i sprawdza każde zadanie względem własnego `interval`. -- Do promptu heartbeat dla danego tyknięcia są dołączane tylko zadania, które **mają termin wykonania**. -- Jeśli żadne zadania nie mają terminu wykonania, heartbeat jest całkowicie pomijany (`reason=no-tasks-due`), aby uniknąć zmarnowanego wywołania modelu. -- Treść spoza zadań w `HEARTBEAT.md` jest zachowywana i dołączana jako dodatkowy kontekst po liście zadań wymagających wykonania. +- OpenClaw analizuje blok `tasks:` i sprawdza każde zadanie względem jego własnego `interval`. +- Tylko **należne** zadania są dołączane do promptu heartbeat dla danego tyknięcia. +- Jeśli żadne zadania nie są należne, heartbeat jest całkowicie pomijany (`reason=no-tasks-due`), aby uniknąć zmarnowanego wywołania modelu. +- Treść spoza zadań w `HEARTBEAT.md` jest zachowywana i dołączana jako dodatkowy kontekst po liście należnych zadań. - Znaczniki czasu ostatniego uruchomienia zadań są przechowywane w stanie sesji (`heartbeatTaskState`), więc interwały przetrwają zwykłe restarty. -- Znaczniki czasu zadań są przesuwane dopiero po tym, jak uruchomienie heartbeat przejdzie normalną ścieżkę odpowiedzi. Pominięte uruchomienia `empty-heartbeat-file` / `no-tasks-due` nie oznaczają zadań jako ukończonych. +- Znaczniki czasu zadań są przesuwane dopiero po tym, jak uruchomienie heartbeat zakończy normalną ścieżkę odpowiedzi. Pominięte uruchomienia `empty-heartbeat-file` / `no-tasks-due` nie oznaczają zadań jako ukończonych. -Tryb zadań jest przydatny, gdy chcesz, aby jeden plik heartbeat zawierał kilka okresowych kontroli bez płacenia za wszystkie przy każdym tyknięciu. +Tryb zadań jest przydatny, jeśli chcesz, aby jeden plik heartbeat zawierał kilka okresowych sprawdzeń bez płacenia za wszystkie przy każdym tyknięciu. ### Czy agent może aktualizować HEARTBEAT.md? -Tak — jeśli go o to poprosisz. +Tak — jeśli mu to zlecisz. -`HEARTBEAT.md` to po prostu zwykły plik w workspace agenta, więc możesz powiedzieć -agentowi (na zwykłym czacie) coś takiego: +`HEARTBEAT.md` to po prostu zwykły plik w obszarze roboczym agenta, więc możesz powiedzieć +agentowi (w zwykłym czacie) coś w rodzaju: -- „Zaktualizuj `HEARTBEAT.md`, aby dodać codzienną kontrolę kalendarza.” -- „Przepisz `HEARTBEAT.md`, aby był krótszy i skupiał się na zadaniach związanych ze skrzynką odbiorczą.” +- „Zaktualizuj `HEARTBEAT.md`, aby dodać codzienne sprawdzenie kalendarza.” +- „Przeredaguj `HEARTBEAT.md`, aby był krótszy i skupiał się na działaniach następczych ze skrzynki odbiorczej.” -Jeśli chcesz, aby działo się to proaktywnie, możesz także dołączyć jawną linię w -prompt heartbeat, na przykład: „If the checklist becomes stale, update HEARTBEAT.md -with a better one.” +Jeśli chcesz, aby działo się to proaktywnie, możesz także dodać jawną linię do +promptu heartbeat, na przykład: „Jeśli lista kontrolna się zestarzeje, zaktualizuj HEARTBEAT.md +na lepszą.” Uwaga dotycząca bezpieczeństwa: nie umieszczaj sekretów (kluczy API, numerów telefonów, prywatnych tokenów) w `HEARTBEAT.md` — staje się częścią kontekstu promptu. ## Ręczne wybudzenie (na żądanie) -Możesz dodać zdarzenie systemowe do kolejki i natychmiast uruchomić heartbeat poleceniem: +Możesz umieścić zdarzenie systemowe w kolejce i natychmiast wyzwolić heartbeat poleceniem: ```bash openclaw system event --text "Check for urgent follow-ups" --mode now ``` -Jeśli wiele agentów ma skonfigurowany `heartbeat`, ręczne wybudzenie natychmiast uruchamia heartbeat każdego z tych -agentów. +Jeśli wielu agentów ma skonfigurowany `heartbeat`, ręczne wybudzenie natychmiast uruchamia heartbeat każdego z nich. -Użyj `--mode next-heartbeat`, aby poczekać na następne zaplanowane tyknięcie. +Użyj `--mode next-heartbeat`, aby zaczekać do następnego zaplanowanego tyknięcia. -## Dostarczanie rozumowania (opcjonalne) +## Dostarczanie rozumowania (opcjonalnie) -Domyślnie heartbeat dostarcza tylko końcowy ładunek „odpowiedzi”. +Domyślnie heartbeat dostarcza tylko końcowy ładunek „answer”. Jeśli chcesz większej przejrzystości, włącz: - `agents.defaults.heartbeat.includeReasoning: true` -Po włączeniu heartbeat będą również dostarczać osobny komunikat poprzedzony -`Reasoning:` (ten sam kształt co `/reasoning on`). Może to być przydatne, gdy agent -zarządza wieloma sesjami/codexami i chcesz zobaczyć, dlaczego zdecydował się Cię -powiadomić — ale może to także ujawnić więcej szczegółów wewnętrznych, niż chcesz. W czatach grupowych lepiej pozostawić tę opcję -wyłączoną. +Po włączeniu heartbeat będzie również dostarczał osobną wiadomość z prefiksem +`Reasoning:` (ten sam format co `/reasoning on`). Może to być przydatne, gdy agent +zarządza wieloma sesjami/codexami i chcesz zobaczyć, dlaczego zdecydował się do Ciebie odezwać +— ale może też ujawniać więcej szczegółów wewnętrznych, niż chcesz. Lepiej pozostawić to +wyłączone w czatach grupowych. ## Świadomość kosztów Heartbeat uruchamia pełne tury agenta. Krótsze interwały zużywają więcej tokenów. Aby obniżyć koszt: -- Użyj `isolatedSession: true`, aby uniknąć wysyłania pełnej historii rozmowy (~100K tokenów spada do ~2-5K na uruchomienie). +- Użyj `isolatedSession: true`, aby uniknąć wysyłania pełnej historii rozmowy (~100K tokenów do ~2-5K na uruchomienie). - Użyj `lightContext: true`, aby ograniczyć pliki bootstrap tylko do `HEARTBEAT.md`. - Ustaw tańszy `model` (np. `ollama/llama3.2:1b`). - Utrzymuj `HEARTBEAT.md` w małym rozmiarze. @@ -444,7 +451,7 @@ Heartbeat uruchamia pełne tury agenta. Krótsze interwały zużywają więcej t ## Powiązane -- [Automation & Tasks](/pl/automation) — wszystkie mechanizmy automatyzacji w skrócie -- [Background Tasks](/pl/automation/tasks) — jak śledzona jest praca odłączona -- [Timezone](/concepts/timezone) — jak strefa czasowa wpływa na harmonogram heartbeat -- [Troubleshooting](/pl/automation/cron-jobs#troubleshooting) — debugowanie problemów z automatyzacją +- [Automatyzacja i zadania](/pl/automation) — wszystkie mechanizmy automatyzacji w skrócie +- [Zadania w tle](/pl/automation/tasks) — jak śledzona jest praca odłączona +- [Strefa czasowa](/pl/concepts/timezone) — jak strefa czasowa wpływa na planowanie heartbeat +- [Rozwiązywanie problemów](/pl/automation/cron-jobs#troubleshooting) — debugowanie problemów z automatyzacją diff --git a/docs/pl/gateway/local-models.md b/docs/pl/gateway/local-models.md index 69b37f141..7066c986d 100644 --- a/docs/pl/gateway/local-models.md +++ b/docs/pl/gateway/local-models.md @@ -1,28 +1,28 @@ --- read_when: - Chcesz udostępniać modele z własnej maszyny GPU - - Podłączasz LM Studio lub proxy zgodne z OpenAI + - 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) +summary: Uruchamianie OpenClaw na lokalnych modelach LLM (LM Studio, vLLM, LiteLLM, niestandardowe endpointy OpenAI) title: Modele lokalne x-i18n: - generated_at: "2026-04-05T13:53:24Z" + generated_at: "2026-04-08T02:14:31Z" model: gpt-5.4 provider: openai - source_hash: 3b99c8fb57f65c0b765fc75bd36933221b5aeb94c4a3f3428f92640ae064f8b6 + source_hash: d619d72b0e06914ebacb7e9f38b746caf1b9ce8908c9c6638c3acdddbaa025e8 source_path: gateway/local-models.md workflow: 15 --- # Modele lokalne -Tryb lokalny jest możliwy, ale OpenClaw oczekuje dużego kontekstu i silnej ochrony przed prompt injection. Małe karty obcinają kontekst i osłabiają bezpieczeństwo. Celuj wysoko: **≥2 maksymalnie wyposażone Mac Studio lub równoważny zestaw GPU (~30 tys. USD+)**. Pojedynczy GPU **24 GB** działa tylko przy lżejszych promptach i większych opóźnieniach. Używaj **największego / pełnowymiarowego wariantu modelu, jaki możesz uruchomić**; agresywnie kwantyzowane lub „małe” checkpointy zwiększają ryzyko prompt injection (zobacz [Security](/gateway/security)). +Uruchamianie lokalne jest możliwe, ale OpenClaw oczekuje dużego kontekstu oraz silnych zabezpieczeń przed prompt injection. Małe karty skracają 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 **24 GB** sprawdzi się tylko przy lżejszych promptach i większych opóźnieniach. Używaj **największego / pełnowymiarowego wariantu modelu, jaki możesz uruchomić**; agresywnie kwantyzowane lub „małe” checkpointy zwiększają ryzyko prompt injection (zobacz [Bezpieczeństwo](/pl/gateway/security)). -Jeśli chcesz lokalnej konfiguracji z najmniejszym tarciem, zacznij od [Ollama](/providers/ollama) i `openclaw onboard`. Ta strona to praktyczny przewodnik dla bardziej zaawansowanych lokalnych stosów i niestandardowych lokalnych serwerów zgodnych z OpenAI. +Jeśli chcesz skonfigurować lokalne środowisko z jak najmniejszym tarciem, zacznij od [Ollama](/pl/providers/ollama) i `openclaw onboard`. Ta strona to opiniotwórczy przewodnik po bardziej zaawansowanych lokalnych stosach oraz niestandardowych lokalnych serwerach zgodnych z OpenAI. ## Zalecane: LM Studio + duży model lokalny (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 lokalny serwer (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 do LM Studio (na przykład pełnowymiarową kompilację 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 tekstu końcowego. ```json5 { @@ -62,15 +62,15 @@ Obecnie najlepszy lokalny stos. Załaduj duży model w LM Studio (na przykład p **Lista kontrolna konfiguracji** - Zainstaluj LM Studio: [https://lmstudio.ai](https://lmstudio.ai) -- 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. +- W LM Studio pobierz **największą dostępną kompilację 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 uruchamiania. -- Dostosuj `contextWindow` / `maxTokens`, jeśli Twoja wersja LM Studio się różni. -- W przypadku WhatsApp trzymaj się Responses API, aby wysyłany był tylko końcowy tekst. +- Utrzymuj model załadowany; zimne ładowanie zwiększa opóźnienie startu. +- Dostosuj `contextWindow`/`maxTokens`, jeśli Twoja kompilacja LM Studio się różni. +- W przypadku WhatsApp trzymaj się Responses API, aby wysyłany był tylko tekst końcowy. -Nawet przy pracy lokalnej pozostaw skonfigurowane modele hostowane; użyj `models.mode: "merge"`, aby fallbacki nadal były dostępne. +Nawet przy uruchamianiu lokalnym pozostaw skonfigurowane modele hostowane; użyj `models.mode: "merge"`, aby fallbacki pozostały dostępne. -### Konfiguracja hybrydowa: hostowany model główny, lokalny fallback +### Konfiguracja hybrydowa: hostowany model podstawowy, lokalny fallback ```json5 { @@ -113,16 +113,16 @@ Nawet przy pracy lokalnej pozostaw skonfigurowane modele hostowane; użyj `model ### Najpierw lokalnie, z hostowaną siatką bezpieczeństwa -Zamień kolejność modelu głównego i fallbacków; zachowaj ten sam blok dostawców i `models.mode: "merge"`, aby móc wrócić do Sonnet lub Opus, gdy lokalna maszyna będzie niedostępna. +Zamień kolejność modelu podstawowego i fallbacku; zachowaj ten sam blok providerów oraz `models.mode: "merge"`, aby móc przełączyć się awaryjnie na Sonnet lub Opus, gdy lokalna maszyna będzie niedostępna. ### Hosting regionalny / routing danych -- Hostowane warianty MiniMax/Kimi/GLM istnieją także w OpenRouter z endpointami przypiętymi do regionu (np. hostowane 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 najsilniejszą ścieżką prywatności; hostowany routing regionalny to rozwiązanie pośrednie, gdy potrzebujesz funkcji dostawcy, ale chcesz kontrolować przepływ danych. +- Hostowane warianty MiniMax/Kimi/GLM są również 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 najmocniejszą ścieżką pod względem prywatności; hostowany routing regionalny to rozwiązanie pośrednie, gdy potrzebujesz funkcji dostawcy, ale chcesz zachować kontrolę nad przepływem danych. ## Inne lokalne proxy zgodne z OpenAI -vLLM, LiteLLM, OAI-proxy lub niestandardowe gatewaye działają, jeśli udostępniają endpoint `/v1` w stylu OpenAI. Zastąp powyższy blok dostawcy swoim endpointem i identyfikatorem modelu: +vLLM, LiteLLM, OAI-proxy lub niestandardowe bramy działają, jeśli udostępniają endpoint `/v1` w stylu OpenAI. Zastąp powyższy blok providera swoim endpointem i identyfikatorem modelu: ```json5 { @@ -152,19 +152,39 @@ vLLM, LiteLLM, OAI-proxy lub niestandardowe gatewaye działają, jeśli udostęp Zachowaj `models.mode: "merge"`, aby hostowane modele nadal były dostępne jako fallbacki. -Uwaga dotycząca działania dla lokalnych / proxowanych backendów `/v1`: +Uwagi dotyczące działania dla lokalnych / proxowanych backendów `/v1`: -- OpenClaw traktuje je jako trasy proxy zgodne z OpenAI, a nie natywne - endpointy OpenAI -- nie stosuje się tutaj kształtowania żądań przeznaczonego wyłącznie dla natywnego OpenAI: brak - `service_tier`, brak Responses `store`, brak kształtowania ładunku zgodności z reasoning OpenAI - i brak wskazówek prompt-cache +- OpenClaw traktuje je jako trasy proxy zgodne z OpenAI, a nie natywne endpointy OpenAI +- natywne kształtowanie żądań tylko dla OpenAI nie ma tu zastosowania: brak + `service_tier`, brak Responses `store`, brak kształtowania payloadu zgodności z rozumowaniem OpenAI + oraz brak wskazówek dotyczących cache promptów - ukryte nagłówki atrybucji OpenClaw (`originator`, `version`, `User-Agent`) - nie są wstrzykiwane do tych niestandardowych URL-i proxy + nie są wstrzykiwane dla tych niestandardowych adresów URL proxy + +Uwagi o zgodności dla bardziej rygorystycznych backendów zgodnych z OpenAI: + +- Niektóre serwery akceptują w Chat Completions tylko string `messages[].content`, a nie + ustrukturyzowane tablice części treści. Ustaw + `models.providers..models[].compat.requiresStringContent: true` dla + takich endpointów. +- Niektóre mniejsze lub bardziej rygorystyczne lokalne backendy są niestabilne przy pełnym + kształcie promptu środowiska uruchomieniowego agenta OpenClaw, szczególnie gdy dołączone są schematy narzędzi. Jeśli + backend działa dla małych bezpośrednich wywołań `/v1/chat/completions`, ale nie działa przy zwykłych + turach agenta OpenClaw, najpierw 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 przepustowoś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 „zawieszenia”. -- Błędy kontekstu? Zmniejsz `contextWindow` lub zwiększ limit serwera. -- Bezpieczeństwo: modele lokalne pomijają filtry po stronie dostawcy; utrzymuj agentów w wąskim zakresie i włącz kompaktowanie, aby ograniczyć skutki prompt injection. +- Brama 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 jest częstą przyczyną „zawieszania się”. +- Błędy kontekstu? Obniż `contextWindow` lub 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` + nie działa na Gemma lub innym modelu lokalnym? Najpierw wyłącz schematy narzędzi za pomocą + `compat.supportsTools: false`, a następnie przetestuj ponownie. Jeśli serwer nadal ulega awarii tylko + przy większych promptach OpenClaw, traktuj to jako ograniczenie modelu/serwera upstream. +- Bezpieczeństwo: modele lokalne pomijają filtry po stronie dostawcy; utrzymuj agentów w wąskim zakresie i włącz kompaktowanie, aby ograniczyć zasięg prompt injection. diff --git a/docs/pl/gateway/protocol.md b/docs/pl/gateway/protocol.md index 429b89a31..8de9647df 100644 --- a/docs/pl/gateway/protocol.md +++ b/docs/pl/gateway/protocol.md @@ -1,32 +1,32 @@ --- read_when: - Implementowanie lub aktualizowanie klientów WS gateway - - Debugowanie niezgodności protokołu lub błędów połączenia + - Debugowanie niedopasowań protokołu lub niepowodzeń połączenia - Ponowne generowanie schematu/modeli protokołu -summary: 'Protokół WebSocket Gateway: handshake, ramki, wersjonowanie' +summary: 'Protokół Gateway WebSocket: uzgadnianie połączenia, ramki, wersjonowanie' title: Protokół Gateway x-i18n: - generated_at: "2026-04-05T13:55:25Z" + generated_at: "2026-04-08T02:15:42Z" model: gpt-5.4 provider: openai - source_hash: c37f5b686562dda3ba3516ac6982ad87b2f01d8148233284e9917099c6e96d87 + source_hash: 8635e3ac1dd311dbd3a770b088868aa1495a8d53b3ebc1eae0dfda3b2bf4694a source_path: gateway/protocol.md workflow: 15 --- # Protokół Gateway (WebSocket) -Protokół Gateway WS to **pojedyncza płaszczyzna sterowania + transport węzłów** dla -OpenClaw. Wszyscy klienci (CLI, web UI, aplikacja macOS, węzły iOS/Android, bezgłowe -węzły) łączą się przez WebSocket i deklarują swoją **rolę** + **zakres** w momencie -handshake. +Protokół Gateway WS jest **pojedynczą płaszczyzną sterowania + transportem węzłów** dla +OpenClaw. Wszyscy klienci (CLI, interfejs webowy, aplikacja macOS, węzły iOS/Android, bezgłowe +węzły) łączą się przez WebSocket i deklarują swoją **rolę** + **zakres** w czasie +uzgadniania połączenia. ## Transport - WebSocket, ramki tekstowe z ładunkami JSON. - Pierwsza ramka **musi** być żądaniem `connect`. -## Handshake (`connect`) +## Uzgadnianie połączenia (connect) Gateway → klient (wyzwanie przed połączeniem): @@ -84,7 +84,7 @@ Gateway → klient: } ``` -Gdy wydawany jest token urządzenia, `hello-ok` zawiera także: +Gdy zostanie wydany token urządzenia, `hello-ok` zawiera także: ```json { @@ -96,7 +96,7 @@ Gdy wydawany jest token urządzenia, `hello-ok` zawiera także: } ``` -Podczas wbudowanego zaufanego przekazania bootstrap `hello-ok.auth` może również zawierać dodatkowe +Podczas przekazania w zaufanym przepływie bootstrap, `hello-ok.auth` może także zawierać dodatkowe ograniczone wpisy ról w `deviceTokens`: ```json @@ -116,12 +116,12 @@ ograniczone wpisy ról w `deviceTokens`: } ``` -Dla wbudowanego przepływu bootstrap node/operator podstawowy token węzła pozostaje z -`scopes: []`, a każdy przekazany token operatora pozostaje ograniczony do bootstrapowej -listy dozwolonych operatora (`operator.approvals`, `operator.read`, -`operator.talk.secrets`, `operator.write`). Kontrole zakresu bootstrap pozostają +W przypadku wbudowanego przepływu bootstrap węzła/operatora podstawowy token węzła pozostaje +`scopes: []`, a każdy przekazany token operatora pozostaje ograniczony do listy dozwolonych zakresów +operatora bootstrap (`operator.approvals`, `operator.read`, +`operator.talk.secrets`, `operator.write`). Sprawdzenia zakresu bootstrap pozostają prefiksowane rolą: wpisy operatora spełniają tylko żądania operatora, a role inne niż operator -nadal wymagają zakresów z własnym prefiksem roli. +nadal wymagają zakresów pod własnym prefiksem roli. ### Przykład węzła @@ -158,13 +158,13 @@ nadal wymagają zakresów z własnym prefiksem roli. } ``` -## Ramki +## Ramkowanie - **Żądanie**: `{type:"req", id, method, params}` - **Odpowiedź**: `{type:"res", id, ok, payload|error}` - **Zdarzenie**: `{type:"event", event, payload, seq?, stateVersion?}` -Metody powodujące skutki uboczne wymagają **kluczy idempotencyjnych** (zobacz schemat). +Metody powodujące skutki uboczne wymagają **kluczy idempotencji** (zobacz schemat). ## Role + zakresy @@ -173,7 +173,7 @@ Metody powodujące skutki uboczne wymagają **kluczy idempotencyjnych** (zobacz - `operator` = klient płaszczyzny sterowania (CLI/UI/automatyzacja). - `node` = host możliwości (`camera/screen/canvas/system.run`). -### Zakresy (`operator`) +### Zakresy (operator) Typowe zakresy: @@ -187,93 +187,93 @@ Typowe zakresy: `talk.config` z `includeSecrets: true` wymaga `operator.talk.secrets` (lub `operator.admin`). -Metody Gateway RPC zarejestrowane przez pluginy mogą żądać własnego zakresu operatora, ale +Metody Gateway RPC rejestrowane przez pluginy mogą żądać własnego zakresu operatora, ale zastrzeżone prefiksy administracyjne rdzenia (`config.*`, `exec.approvals.*`, `wizard.*`, -`update.*`) zawsze są rozwiązywane do `operator.admin`. +`update.*`) zawsze są mapowane na `operator.admin`. -Zakres metody jest tylko pierwszą bramką. Niektóre polecenia slash osiągane przez -`chat.send` stosują na dodatek bardziej rygorystyczne kontrole na poziomie polecenia. Na przykład trwałe +Zakres metody to tylko pierwszy próg kontroli. Niektóre polecenia slash osiągane przez +`chat.send` nakładają dodatkowo bardziej rygorystyczne kontrole na poziomie polecenia. Na przykład trwałe zapisy `/config set` i `/config unset` wymagają `operator.admin`. `node.pair.approve` ma także dodatkową kontrolę zakresu w momencie zatwierdzania ponad -podstawowy zakres metody: +bazowy zakres metody: -- żądania bez polecenia: `operator.pairing` +- żądania bez poleceń: `operator.pairing` - żądania z poleceniami węzła innymi niż exec: `operator.pairing` + `operator.write` -- żądania zawierające `system.run`, `system.run.prepare` lub `system.which`: +- żądania obejmujące `system.run`, `system.run.prepare` lub `system.which`: `operator.pairing` + `operator.admin` -### `caps`/`commands`/`permissions` (`node`) +### Caps/commands/permissions (node) -Węzły deklarują roszczenia możliwości w momencie połączenia: +Węzły deklarują roszczenia możliwości w czasie połączenia: -- `caps`: kategorie możliwości wysokiego poziomu. +- `caps`: wysokopoziomowe kategorie możliwości. - `commands`: lista dozwolonych poleceń dla invoke. - `permissions`: szczegółowe przełączniki (np. `screen.record`, `camera.capture`). -Gateway traktuje je jako **roszczenia** i wymusza listy dozwolonych po stronie serwera. +Gateway traktuje je jako **roszczenia** i egzekwuje listy dozwolonych po stronie serwera. -## Presence +## Obecność - `system-presence` zwraca wpisy kluczowane tożsamością urządzenia. -- Wpisy presence zawierają `deviceId`, `roles` i `scopes`, dzięki czemu UI może pokazywać jeden wiersz na urządzenie - nawet wtedy, gdy łączy się ono zarówno jako **operator**, jak i **node**. +- Wpisy obecności zawierają `deviceId`, `roles` i `scopes`, aby interfejsy mogły pokazywać jeden wiersz na urządzenie, + nawet gdy łączy się ono zarówno jako **operator**, jak i **node**. ## Typowe rodziny metod RPC -Ta strona nie jest wygenerowanym pełnym zrzutem, ale publiczna powierzchnia WS jest -szersza niż powyższe przykłady handshake/auth. To główne rodziny metod, które +Ta strona nie jest wygenerowanym pełnym zrzutem, ale publiczna powierzchnia WS jest szersza +niż przykłady uzgadniania połączenia/uwierzytelniania powyżej. To są główne rodziny metod, które Gateway udostępnia obecnie. `hello-ok.features.methods` to zachowawcza lista wykrywania zbudowana z `src/gateway/server-methods-list.ts` oraz załadowanych eksportów metod pluginów/kanałów. -Traktuj ją jako wykrywanie funkcji, a nie jako wygenerowany zrzut każdej wywoływalnej funkcji pomocniczej -zaimplementowanej w `src/gateway/server-methods/*.ts`. +Traktuj ją jako wykrywanie funkcji, a nie wygenerowany zrzut każdego pomocniczego wywołania +zaimplementowanego w `src/gateway/server-methods/*.ts`. ### System i tożsamość -- `health` zwraca buforowaną lub świeżo sprawdzoną migawkę stanu gateway. +- `health` zwraca buforowany lub świeżo sprawdzony snapshot kondycji gateway. - `status` zwraca podsumowanie gateway w stylu `/status`; pola wrażliwe są - uwzględniane tylko dla klientów operatora o zakresie admin. + dołączane tylko dla klientów operatora z zakresem admin. - `gateway.identity.get` zwraca tożsamość urządzenia gateway używaną przez przepływy relay i parowania. -- `system-presence` zwraca bieżącą migawkę presence dla połączonych - urządzeń operator/node. -- `system-event` dopisuje zdarzenie systemowe i może aktualizować/rozgłaszać - kontekst presence. -- `last-heartbeat` zwraca najnowsze utrwalone zdarzenie heartbeat. -- `set-heartbeats` przełącza przetwarzanie heartbeat na gateway. +- `system-presence` zwraca bieżący snapshot obecności dla połączonych + urządzeń operatora/węzła. +- `system-event` dopisuje zdarzenie systemowe i może aktualizować/rozgłaszać kontekst + obecności. +- `last-heartbeat` zwraca najnowsze zapisane zdarzenie heartbeat. +- `set-heartbeats` przełącza przetwarzanie heartbeat w gateway. -### Models i użycie +### Modele i użycie -- `models.list` zwraca katalog modeli dozwolonych w runtime. -- `usage.status` zwraca okna użycia dostawców/podsumowania pozostałego limitu. -- `usage.cost` zwraca zagregowane podsumowania użycia kosztów dla zakresu dat. -- `doctor.memory.status` zwraca gotowość pamięci wektorowej / osadzeń dla - aktywnego domyślnego workspace agenta. +- `models.list` zwraca katalog modeli dozwolonych w czasie działania. +- `usage.status` zwraca okna użycia dostawcy/podsumowania pozostałego limitu. +- `usage.cost` zwraca zagregowane podsumowania kosztów użycia dla zakresu dat. +- `doctor.memory.status` zwraca gotowość pamięci wektorowej / embeddingów dla + aktywnego domyślnego obszaru roboczego agenta. - `sessions.usage` zwraca podsumowania użycia dla poszczególnych sesji. - `sessions.usage.timeseries` zwraca szereg czasowy użycia dla jednej sesji. -- `sessions.usage.logs` zwraca wpisy logu użycia dla jednej sesji. +- `sessions.usage.logs` zwraca wpisy dziennika użycia dla jednej sesji. ### Kanały i pomocniki logowania -- `channels.status` zwraca podsumowania stanu wbudowanych + dołączonych kanałów/pluginów. -- `channels.logout` wylogowuje konkretne konto kanału, jeśli kanał +- `channels.status` zwraca podsumowania statusu wbudowanych + dołączonych kanałów/pluginów. +- `channels.logout` wylogowuje z określonego kanału/konta tam, gdzie kanał obsługuje wylogowanie. - `web.login.start` uruchamia przepływ logowania QR/web dla bieżącego dostawcy kanału web obsługującego QR. -- `web.login.wait` czeka na zakończenie tego przepływu logowania QR/web i uruchamia - kanał po powodzeniu. -- `push.test` wysyła testowy push APNs do zarejestrowanego węzła iOS. -- `voicewake.get` zwraca zapisane wyzwalacze wake word. -- `voicewake.set` aktualizuje wyzwalacze wake word i rozgłasza zmianę. +- `web.login.wait` czeka na zakończenie tego przepływu logowania QR/web i przy powodzeniu uruchamia + kanał. +- `push.test` wysyła testowe powiadomienie APNs do zarejestrowanego węzła iOS. +- `voicewake.get` zwraca zapisane wyzwalacze słowa aktywującego. +- `voicewake.set` aktualizuje wyzwalacze słowa aktywującego i rozgłasza zmianę. ### Wiadomości i logi -- `send` to bezpośrednie RPC dostarczania wychodzącego dla wysyłek kierowanych do - kanału/konta/wątku poza runnerem czatu. -- `logs.tail` zwraca ogon skonfigurowanego logu plikowego gateway z kontrolą kursora/limitu i - maksymalnej liczby bajtów. +- `send` jest bezpośrednim wywołaniem RPC dostarczania wychodzącego dla + wysyłek kierowanych do kanału/konta/wątku poza runnerem czatu. +- `logs.tail` zwraca ogon skonfigurowanego dziennika plikowego gateway z kursorem/limitem oraz + kontrolami maksymalnej liczby bajtów. ### Talk i TTS @@ -281,58 +281,58 @@ zaimplementowanej w `src/gateway/server-methods/*.ts`. wymaga `operator.talk.secrets` (lub `operator.admin`). - `talk.mode` ustawia/rozgłasza bieżący stan trybu Talk dla klientów WebChat/Control UI. -- `talk.speak` syntezuje mowę przez aktywnego dostawcę mowy Talk. +- `talk.speak` syntetyzuje mowę przez aktywnego dostawcę mowy Talk. - `tts.status` zwraca stan włączenia TTS, aktywnego dostawcę, dostawców zapasowych oraz stan konfiguracji dostawcy. -- `tts.providers` zwraca widoczny inwentarz dostawców TTS. +- `tts.providers` zwraca widoczny spis dostawców TTS. - `tts.enable` i `tts.disable` przełączają stan preferencji TTS. - `tts.setProvider` aktualizuje preferowanego dostawcę TTS. -- `tts.convert` uruchamia jednorazową konwersję text-to-speech. +- `tts.convert` uruchamia jednorazową konwersję tekstu na mowę. -### Secrets, config, update i wizard +### Sekrety, konfiguracja, aktualizacja i kreator -- `secrets.reload` ponownie rozwiązuje aktywne SecretRef i podmienia stan sekretów runtime +- `secrets.reload` ponownie rozwiązuje aktywne SecretRef i podmienia stan sekretów w czasie działania tylko przy pełnym powodzeniu. -- `secrets.resolve` rozwiązuje przypisania sekretów docelowych dla poleceń dla konkretnego +- `secrets.resolve` rozwiązuje przypisania sekretów docelowych poleceń dla określonego zestawu poleceń/celów. -- `config.get` zwraca bieżącą migawkę konfiguracji i hash. +- `config.get` zwraca bieżący snapshot konfiguracji i hash. - `config.set` zapisuje zwalidowany ładunek konfiguracji. - `config.patch` scala częściową aktualizację konfiguracji. -- `config.apply` waliduje + zastępuje pełny ładunek konfiguracji. -- `config.schema` zwraca aktywny ładunek schematu konfiguracji używany przez Control UI i - narzędzia CLI: schemat, `uiHints`, wersję i metadane generowania, w tym - metadane schematów pluginów + kanałów, gdy runtime może je załadować. Schemat - zawiera metadane pól `title` / `description` wyprowadzone z tych samych etykiet - i tekstu pomocy używanych przez UI, w tym dla zagnieżdżonych obiektów, wildcard, - elementów tablic i gałęzi kompozycji `anyOf` / `oneOf` / `allOf`, gdy istnieje - pasująca dokumentacja pól. -- `config.schema.lookup` zwraca ładunek wyszukiwania o zakresie ścieżki dla jednej ścieżki konfiguracji: - znormalizowaną ścieżkę, płytki węzeł schematu, dopasowaną podpowiedź + `hintPath` oraz - podsumowania bezpośrednich elementów potomnych dla UI/CLI drill-down. - - Węzły schematu lookup zachowują dokumentację widoczną dla użytkownika i typowe pola walidacji: +- `config.apply` waliduje i zastępuje pełny ładunek konfiguracji. +- `config.schema` zwraca ładunek aktywnego schematu konfiguracji używany przez Control UI i + narzędzia CLI: schemat, `uiHints`, wersję oraz metadane generowania, w tym + metadane schematu pluginów + kanałów, gdy środowisko wykonawcze może je załadować. Schemat + zawiera metadane pól `title` / `description` pochodzące z tych samych etykiet + i tekstów pomocy używanych przez UI, w tym zagnieżdżone obiekty, wildcard, elementy tablic + oraz gałęzie kompozycji `anyOf` / `oneOf` / `allOf`, gdy istnieje odpowiadająca + dokumentacja pól. +- `config.schema.lookup` zwraca ładunek wyszukiwania ograniczony do ścieżki dla jednej ścieżki konfiguracji: + znormalizowaną ścieżkę, płytki węzeł schematu, dopasowaną wskazówkę + `hintPath` oraz + podsumowania bezpośrednich elementów potomnych do drążenia w UI/CLI. + - Węzły schematu wyszukiwania zachowują dokumentację skierowaną do użytkownika i typowe pola walidacji: `title`, `description`, `type`, `enum`, `const`, `format`, `pattern`, - ograniczenia liczb/stringów/tablic/obiektów oraz flagi boolowskie, takie jak + ograniczenia liczb/ciągów/tablic/obiektów oraz flagi logiczne takie jak `additionalProperties`, `deprecated`, `readOnly`, `writeOnly`. - - Podsumowania dzieci ujawniają `key`, znormalizowaną `path`, `type`, `required`, - `hasChildren`, a także dopasowane `hint` / `hintPath`. + - Podsumowania elementów potomnych udostępniają `key`, znormalizowaną `path`, `type`, `required`, + `hasChildren` oraz dopasowane `hint` / `hintPath`. - `update.run` uruchamia przepływ aktualizacji gateway i planuje restart tylko wtedy, - gdy sama aktualizacja zakończyła się powodzeniem. + gdy sama aktualizacja się powiodła. - `wizard.start`, `wizard.next`, `wizard.status` i `wizard.cancel` udostępniają - kreator onboardingu przez WS RPC. + kreator wdrożenia przez WS RPC. ### Istniejące główne rodziny -#### Pomocniki agentów i workspace +#### Pomocniki agenta i obszaru roboczego - `agents.list` zwraca skonfigurowane wpisy agentów. -- `agents.create`, `agents.update` i `agents.delete` zarządzają rekordami agentów i - połączeniem workspace. +- `agents.create`, `agents.update` i `agents.delete` zarządzają rekordami agentów oraz + powiązaniami obszaru roboczego. - `agents.files.list`, `agents.files.get` i `agents.files.set` zarządzają - plikami bootstrapowego workspace udostępnianymi dla agenta. + plikami obszaru roboczego bootstrap udostępnianymi dla agenta. - `agent.identity.get` zwraca efektywną tożsamość asystenta dla agenta lub sesji. -- `agent.wait` czeka na zakończenie uruchomienia i zwraca końcową migawkę, gdy - jest dostępna. +- `agent.wait` czeka na zakończenie uruchomienia i zwraca końcowy snapshot, gdy + jest dostępny. #### Sterowanie sesją @@ -341,252 +341,252 @@ zaimplementowanej w `src/gateway/server-methods/*.ts`. dla bieżącego klienta WS. - `sessions.messages.subscribe` i `sessions.messages.unsubscribe` przełączają subskrypcje zdarzeń transkryptu/wiadomości dla jednej sesji. -- `sessions.preview` zwraca ograniczone podglądy transkryptu dla określonych kluczy - sesji. +- `sessions.preview` zwraca ograniczone podglądy transkryptu dla określonych + kluczy sesji. - `sessions.resolve` rozwiązuje lub kanonizuje cel sesji. - `sessions.create` tworzy nowy wpis sesji. - `sessions.send` wysyła wiadomość do istniejącej sesji. -- `sessions.steer` to wariant przerwania i sterowania dla aktywnej sesji. +- `sessions.steer` jest wariantem przerwania i sterowania dla aktywnej sesji. - `sessions.abort` przerywa aktywną pracę dla sesji. - `sessions.patch` aktualizuje metadane/nadpisania sesji. -- `sessions.reset`, `sessions.delete` i `sessions.compact` wykonują konserwację - sesji. +- `sessions.reset`, `sessions.delete` i `sessions.compact` wykonują + konserwację sesji. - `sessions.get` zwraca pełny zapisany wiersz sesji. - wykonywanie czatu nadal używa `chat.history`, `chat.send`, `chat.abort` i `chat.inject`. -- `chat.history` jest znormalizowane do wyświetlania dla klientów UI: inline tagi dyrektyw są - usuwane z widocznego tekstu, ładunki XML wywołań narzędzi w czystym tekście (w tym +- `chat.history` jest znormalizowane pod kątem wyświetlania dla klientów UI: wbudowane tagi dyrektyw są + usuwane z widocznego tekstu, ładunki XML wywołań narzędzi w zwykłym tekście (w tym `...`, `...`, `...`, `...` oraz - obcięte bloki wywołań narzędzi) i wyciekające tokeny sterujące modelu ASCII/full-width - są usuwane, czyste wiersze asystenta ze znacznikami silent-token, takie jak dokładne `NO_REPLY` / - `no_reply`, są pomijane, a zbyt duże wiersze mogą być zastępowane placeholderami. + obcięte bloki wywołań narzędzi) i wyciekłe tokeny sterowania modelem ASCII/full-width + są usuwane, czyste wiersze asystenta z cichymi tokenami, takie jak dokładne `NO_REPLY` / + `no_reply`, są pomijane, a zbyt duże wiersze mogą zostać zastąpione placeholderami. #### Parowanie urządzeń i tokeny urządzeń - `device.pair.list` zwraca oczekujące i zatwierdzone sparowane urządzenia. - `device.pair.approve`, `device.pair.reject` i `device.pair.remove` zarządzają rekordami parowania urządzeń. -- `device.token.rotate` obraca token sparowanego urządzenia w granicach jego zatwierdzonej roli +- `device.token.rotate` obraca token sparowanego urządzenia w granicach zatwierdzonej roli i zakresów. - `device.token.revoke` unieważnia token sparowanego urządzenia. #### Parowanie węzłów, invoke i oczekująca praca - `node.pair.request`, `node.pair.list`, `node.pair.approve`, - `node.pair.reject` i `node.pair.verify` obejmują parowanie węzłów i weryfikację - bootstrap. + `node.pair.reject` i `node.pair.verify` obejmują parowanie węzłów i bootstrap + verification. - `node.list` i `node.describe` zwracają stan znanych/połączonych węzłów. - `node.rename` aktualizuje etykietę sparowanego węzła. - `node.invoke` przekazuje polecenie do połączonego węzła. - `node.invoke.result` zwraca wynik żądania invoke. - `node.event` przenosi zdarzenia pochodzące z węzła z powrotem do gateway. -- `node.canvas.capability.refresh` odświeża tokeny możliwości canvas o określonym zakresie. -- `node.pending.pull` i `node.pending.ack` to API kolejki dla połączonych węzłów. +- `node.canvas.capability.refresh` odświeża ograniczone tokeny możliwości canvas. +- `node.pending.pull` i `node.pending.ack` to interfejsy API kolejki połączonych węzłów. - `node.pending.enqueue` i `node.pending.drain` zarządzają trwałą oczekującą pracą dla węzłów offline/rozłączonych. #### Rodziny zatwierdzeń -- `exec.approval.request` i `exec.approval.resolve` obejmują jednorazowe - żądania zatwierdzenia exec. -- `exec.approval.waitDecision` czeka na jedną oczekującą decyzję zatwierdzenia exec i zwraca - ostateczną decyzję (lub `null` przy limicie czasu). -- `exec.approvals.get` i `exec.approvals.set` zarządzają migawkami polityki - zatwierdzeń exec gateway. -- `exec.approvals.node.get` i `exec.approvals.node.set` zarządzają lokalną polityką exec - węzła przez polecenia relay węzła. -- `plugin.approval.request`, `plugin.approval.waitDecision` i - `plugin.approval.resolve` obejmują przepływy zatwierdzeń definiowane przez pluginy. +- `exec.approval.request`, `exec.approval.get`, `exec.approval.list` i + `exec.approval.resolve` obejmują jednorazowe żądania zatwierdzenia exec oraz oczekujące + wyszukiwanie/odtwarzanie zatwierdzeń. +- `exec.approval.waitDecision` czeka na jedno oczekujące zatwierdzenie exec i zwraca + ostateczną decyzję (lub `null` przy przekroczeniu czasu). +- `exec.approvals.get` i `exec.approvals.set` zarządzają snapshotami polityki zatwierdzeń exec + gateway. +- `exec.approvals.node.get` i `exec.approvals.node.set` zarządzają lokalną dla węzła + polityką zatwierdzeń exec przez polecenia relay węzła. +- `plugin.approval.request`, `plugin.approval.list`, + `plugin.approval.waitDecision` i `plugin.approval.resolve` obejmują + przepływy zatwierdzeń definiowane przez pluginy. #### Inne główne rodziny - automatyzacja: - - `wake` planuje natychmiastowe lub najbliższe wstrzyknięcie tekstu wake przy heartbeat + - `wake` planuje natychmiastowe lub przy następnym heartbeat wstrzyknięcie tekstu wybudzającego - `cron.list`, `cron.status`, `cron.add`, `cron.update`, `cron.remove`, `cron.run`, `cron.runs` -- Skills/narzędzia: `skills.*`, `tools.catalog`, `tools.effective` +- skills/tools: `skills.*`, `tools.catalog`, `tools.effective` ### Typowe rodziny zdarzeń - `chat`: aktualizacje czatu UI, takie jak `chat.inject` i inne zdarzenia czatu - dotyczące wyłącznie transkryptu. + tylko dla transkryptu. - `session.message` i `session.tool`: aktualizacje transkryptu/strumienia zdarzeń dla subskrybowanej sesji. -- `sessions.changed`: indeks sesji lub metadane uległy zmianie. -- `presence`: aktualizacje migawki presence systemu. -- `tick`: okresowe zdarzenie keepalive / liveness. -- `health`: aktualizacja migawki stanu gateway. +- `sessions.changed`: zmienił się indeks sesji lub metadane. +- `presence`: aktualizacje snapshotu obecności systemu. +- `tick`: okresowe zdarzenie keepalive / żywotności. +- `health`: aktualizacja snapshotu kondycji gateway. - `heartbeat`: aktualizacja strumienia zdarzeń heartbeat. - `cron`: zdarzenie zmiany uruchomienia/zadania cron. -- `shutdown`: powiadomienie o zamknięciu gateway. -- `node.pair.requested` / `node.pair.resolved`: cykl życia parowania węzła. +- `shutdown`: powiadomienie o wyłączeniu gateway. +- `node.pair.requested` / `node.pair.resolved`: cykl życia parowania węzłów. - `node.invoke.request`: rozgłoszenie żądania invoke węzła. -- `device.pair.requested` / `device.pair.resolved`: cykl życia sparowanego urządzenia. -- `voicewake.changed`: zmieniono konfigurację wyzwalaczy wake word. -- `exec.approval.requested` / `exec.approval.resolved`: cykl życia - zatwierdzenia exec. -- `plugin.approval.requested` / `plugin.approval.resolved`: cykl życia zatwierdzenia pluginu. +- `device.pair.requested` / `device.pair.resolved`: cykl życia sparowanych urządzeń. +- `voicewake.changed`: zmieniła się konfiguracja wyzwalacza słowa aktywującego. +- `exec.approval.requested` / `exec.approval.resolved`: cykl życia zatwierdzeń exec. +- `plugin.approval.requested` / `plugin.approval.resolved`: cykl życia zatwierdzeń pluginów. -### Metody pomocnicze węzła +### Metody pomocnicze węzłów -- Węzły mogą wywoływać `skills.bins`, aby pobrać bieżącą listę wykonywalnych plików Skill - do kontroli auto-allow. +- Węzły mogą wywoływać `skills.bins`, aby pobrać bieżącą listę plików wykonywalnych skill + na potrzeby automatycznych kontroli listy dozwolonych. ### Metody pomocnicze operatora -- Operatorzy mogą wywoływać `tools.catalog` (`operator.read`), aby pobrać katalog narzędzi runtime dla +- Operatorzy mogą wywoływać `tools.catalog` (`operator.read`), aby pobrać katalog narzędzi środowiska wykonawczego dla agenta. Odpowiedź zawiera pogrupowane narzędzia i metadane pochodzenia: - `source`: `core` lub `plugin` - `pluginId`: właściciel pluginu, gdy `source="plugin"` - `optional`: czy narzędzie pluginu jest opcjonalne -- Operatorzy mogą wywoływać `tools.effective` (`operator.read`), aby pobrać efektywny inwentarz narzędzi runtime - dla sesji. +- Operatorzy mogą wywoływać `tools.effective` (`operator.read`), aby pobrać efektywny w czasie działania + spis narzędzi dla sesji. - `sessionKey` jest wymagane. - - Gateway wyprowadza zaufany kontekst runtime po stronie serwera z sesji zamiast akceptować - auth lub kontekst dostarczenia dostarczony przez wywołującego. - - Odpowiedź ma zakres sesji i odzwierciedla to, czego aktywna rozmowa może używać w tej chwili, - w tym narzędzi rdzenia, pluginów i kanałów. + - Gateway wyprowadza zaufany kontekst środowiska wykonawczego po stronie serwera z sesji zamiast akceptować + kontekst uwierzytelniania lub dostarczenia dostarczony przez wywołującego. + - Odpowiedź jest ograniczona do sesji i odzwierciedla to, czego aktywna rozmowa może użyć w danej chwili, + w tym narzędzia rdzenia, pluginów i kanałów. - Operatorzy mogą wywoływać `skills.status` (`operator.read`), aby pobrać widoczny - inwentarz Skill dla agenta. - - `agentId` jest opcjonalne; pomiń je, aby odczytać domyślny workspace agenta. - - Odpowiedź zawiera kwalifikowalność, brakujące wymagania, kontrole konfiguracji i - oczyszczone opcje instalacji bez ujawniania surowych wartości sekretów. + spis skills dla agenta. + - `agentId` jest opcjonalne; pomiń je, aby odczytać domyślny obszar roboczy agenta. + - Odpowiedź zawiera kwalifikowalność, brakujące wymagania, kontrole konfiguracji oraz + zsanityzowane opcje instalacji bez ujawniania surowych wartości sekretów. - Operatorzy mogą wywoływać `skills.search` i `skills.detail` (`operator.read`) dla metadanych wykrywania ClawHub. - Operatorzy mogą wywoływać `skills.install` (`operator.admin`) w dwóch trybach: - Tryb ClawHub: `{ source: "clawhub", slug, version?, force? }` instaluje - folder Skill do katalogu `skills/` domyślnego workspace agenta. + folder skill w katalogu `skills/` domyślnego obszaru roboczego agenta. - Tryb instalatora Gateway: `{ name, installId, dangerouslyForceUnsafeInstall?, timeoutMs? }` uruchamia zadeklarowaną akcję `metadata.openclaw.install` na hoście gateway. - Operatorzy mogą wywoływać `skills.update` (`operator.admin`) w dwóch trybach: - Tryb ClawHub aktualizuje jeden śledzony slug lub wszystkie śledzone instalacje ClawHub w - domyślnym workspace agenta. - - Tryb config łata wartości `skills.entries.`, takie jak `enabled`, + domyślnym obszarze roboczym agenta. + - Tryb konfiguracji łata wartości `skills.entries.`, takie jak `enabled`, `apiKey` i `env`. ## Zatwierdzenia exec - Gdy żądanie exec wymaga zatwierdzenia, gateway rozgłasza `exec.approval.requested`. -- Klienci operatora rozwiązują to przez wywołanie `exec.approval.resolve` (wymaga zakresu `operator.approvals`). +- Klienci operatora rozwiązują je przez wywołanie `exec.approval.resolve` (wymaga zakresu `operator.approvals`). - Dla `host=node`, `exec.approval.request` musi zawierać `systemRunPlan` (kanoniczne `argv`/`cwd`/`rawCommand`/metadane sesji). Żądania bez `systemRunPlan` są odrzucane. -- Po zatwierdzeniu przekazane wywołania `node.invoke system.run` używają ponownie tego kanonicznego +- Po zatwierdzeniu przekazane wywołania `node.invoke system.run` ponownie używają tego kanonicznego `systemRunPlan` jako autorytatywnego kontekstu polecenia/cwd/sesji. - Jeśli wywołujący zmieni `command`, `rawCommand`, `cwd`, `agentId` lub - `sessionKey` między prepare a końcowym zatwierdzonym przekazaniem `system.run`, gateway odrzuci uruchomienie zamiast ufać zmodyfikowanemu ładunkowi. + `sessionKey` między prepare a końcowym zatwierdzonym przekazaniem `system.run`, + gateway odrzuci uruchomienie zamiast ufać zmodyfikowanemu ładunkowi. -## Zapasowe dostarczenie agenta +## Zapasowe dostarczanie agenta - Żądania `agent` mogą zawierać `deliver=true`, aby zażądać dostarczenia wychodzącego. -- `bestEffortDeliver=false` zachowuje ścisłe działanie: nierozwiązane lub wyłącznie wewnętrzne cele dostarczenia zwracają `INVALID_REQUEST`. -- `bestEffortDeliver=true` pozwala na przejście do wykonania wyłącznie w sesji, gdy nie można rozwiązać zewnętrznej trasy dostarczalnej (na przykład sesje internal/webchat lub niejednoznaczne konfiguracje wielokanałowe). +- `bestEffortDeliver=false` zachowuje rygorystyczne działanie: nierozwiązane lub wyłącznie wewnętrzne cele dostarczenia zwracają `INVALID_REQUEST`. +- `bestEffortDeliver=true` umożliwia przejście awaryjne do wykonania tylko w sesji, gdy nie można rozwiązać żadnej zewnętrznej trasy dostarczenia (na przykład sesje internal/webchat lub niejednoznaczne konfiguracje wielu kanałów). ## Wersjonowanie - `PROTOCOL_VERSION` znajduje się w `src/gateway/protocol/schema.ts`. -- Klienci wysyłają `minProtocol` + `maxProtocol`; serwer odrzuca niezgodności. +- Klienci wysyłają `minProtocol` + `maxProtocol`; serwer odrzuca niedopasowania. - Schematy + modele są generowane z definicji TypeBox: - `pnpm protocol:gen` - `pnpm protocol:gen:swift` - `pnpm protocol:check` -## Auth +## Uwierzytelnianie -- Uwierzytelnianie gateway przy użyciu współdzielonego sekretu używa `connect.params.auth.token` lub - `connect.params.auth.password`, zależnie od skonfigurowanego trybu auth. -- Tryby przenoszące tożsamość, takie jak Tailscale Serve - (`gateway.auth.allowTailscale: true`) lub `gateway.auth.mode: "trusted-proxy"` poza loopback, - spełniają kontrolę auth dla connect na podstawie nagłówków żądania zamiast - `connect.params.auth.*`. -- Prywatny ingress `gateway.auth.mode: "none"` całkowicie pomija uwierzytelnianie connect współdzielonym sekretem; - nie wystawiaj tego trybu na publiczny/niezaufany ingress. -- Po sparowaniu Gateway wydaje **token urządzenia** o zakresie zgodnym z rolą + zakresami połączenia. - Jest on zwracany w `hello-ok.auth.deviceToken` i powinien zostać - utrwalony przez klienta do przyszłych połączeń. +- Uwierzytelnianie gateway współdzielonym sekretem używa `connect.params.auth.token` lub + `connect.params.auth.password`, zależnie od skonfigurowanego trybu uwierzytelniania. +- Tryby niosące tożsamość, takie jak Tailscale Serve + (`gateway.auth.allowTailscale: true`) lub `gateway.auth.mode: "trusted-proxy"` inne niż + local loopback, spełniają kontrolę uwierzytelniania connect na podstawie + nagłówków żądania zamiast `connect.params.auth.*`. +- Prywatny ingress `gateway.auth.mode: "none"` całkowicie pomija uwierzytelnianie connect współdzielonym sekretem; nie wystawiaj tego trybu na publiczny/niezaufany ingress. +- Po sparowaniu Gateway wydaje **token urządzenia** ograniczony do roli + zakresów połączenia. + Jest on zwracany w `hello-ok.auth.deviceToken` i powinien być + utrwalony przez klienta na potrzeby przyszłych połączeń. - Klienci powinni utrwalać podstawowy `hello-ok.auth.deviceToken` po każdym udanym połączeniu. -- Ponowne połączenie z tym **zapisanym** tokenem urządzenia powinno również ponownie używać zapisanego - zestawu zatwierdzonych zakresów dla tego tokena. Pozwala to zachować już przyznany - dostęp do odczytu/sond/statusu i unika cichego zawężania ponownych połączeń do - węższego domyślnego zakresu wyłącznie admin. -- Normalna kolejność auth dla connect to najpierw jawny współdzielony token/hasło, potem - jawne `deviceToken`, potem zapisany token per urządzenie, a następnie token bootstrap. +- Ponowne łączenie z tym **zapisanym** tokenem urządzenia powinno także ponownie używać zapisanego + zatwierdzonego zestawu zakresów dla tego tokenu. Pozwala to zachować już przyznany + dostęp do odczytu/sprawdzeń/statusu i unika cichego zawężenia ponownych połączeń do + węższego, domyślnego zakresu tylko admin. +- Zwykła kolejność pierwszeństwa uwierzytelniania connect to najpierw jawny współdzielony token/hasło, potem + jawny `deviceToken`, potem zapisany token per urządzenie, a następnie token bootstrap. - Dodatkowe wpisy `hello-ok.auth.deviceTokens` to tokeny przekazania bootstrap. - Utrwalaj je tylko wtedy, gdy połączenie używało auth bootstrap na zaufanym transporcie, + Utrwalaj je tylko wtedy, gdy połączenie użyło uwierzytelniania bootstrap na zaufanym transporcie, takim jak `wss://` lub loopback/local pairing. -- Jeśli klient dostarcza **jawne** `deviceToken` lub jawne `scopes`, ten - zestaw zakresów żądany przez wywołującego pozostaje autorytatywny; buforowane zakresy są ponownie używane tylko wtedy, - gdy klient używa zapisanego tokena per urządzenie. -- Tokeny urządzeń mogą być obracane/unieważniane przez `device.token.rotate` i +- Jeśli klient dostarczy **jawny** `deviceToken` lub jawne `scopes`, ten + żądany przez wywołującego zestaw zakresów pozostaje autorytatywny; zakresy z pamięci podręcznej są ponownie używane tylko wtedy, gdy klient ponownie używa zapisanego tokenu per urządzenie. +- Tokeny urządzeń można obracać/unieważniać przez `device.token.rotate` i `device.token.revoke` (wymaga zakresu `operator.pairing`). -- Wydawanie/obracanie tokenów pozostaje ograniczone do zatwierdzonego zestawu ról zapisanego we - wpisie parowania tego urządzenia; obrót tokena nie może rozszerzyć urządzenia do - roli, której zatwierdzenie parowania nigdy nie przyznało. -- Dla sesji tokenów sparowanych urządzeń zarządzanie urządzeniem ma zakres własny, chyba że - wywołujący ma również `operator.admin`: wywołujący bez admin może usuwać/unieważniać/obracać +- Wydawanie/obracanie tokenów pozostaje ograniczone do zatwierdzonego zestawu ról zapisanych w + wpisie parowania tego urządzenia; obrót tokenu nie może rozszerzyć urządzenia do + roli, której zatwierdzenie parowania nigdy nie nadało. +- Dla sesji tokenów sparowanych urządzeń zarządzanie urządzeniem jest ograniczone do własnego zakresu, chyba że + wywołujący ma także `operator.admin`: użytkownicy bez admina mogą usuwać/unieważniać/obracać tylko **własny** wpis urządzenia. - `device.token.rotate` sprawdza także żądany zestaw zakresów operatora względem - bieżących zakresów sesji wywołującego. Wywołujący bez admin nie może obrócić tokena do - szerszego zestawu zakresów operatora, niż już posiada. -- Błędy auth zawierają `error.details.code` oraz podpowiedzi naprawcze: + bieżących zakresów sesji wywołującego. Użytkownicy bez admina nie mogą obracać tokenu do + szerszego zestawu zakresów operatora, niż już posiadają. +- Niepowodzenia uwierzytelniania zawierają `error.details.code` oraz wskazówki odzyskiwania: - `error.details.canRetryWithDeviceToken` (boolean) - `error.details.recommendedNextStep` (`retry_with_device_token`, `update_auth_configuration`, `update_auth_credentials`, `wait_then_retry`, `review_auth_configuration`) - Zachowanie klienta dla `AUTH_TOKEN_MISMATCH`: - - Zaufani klienci mogą podjąć jedną ograniczoną próbę ponowną z buforowanym tokenem per urządzenie. - - Jeśli ta próba się nie powiedzie, klienci powinni zatrzymać automatyczne pętle ponownego łączenia i wyświetlić operatorowi wskazówki wymagające działania. + - Zaufani klienci mogą podjąć jedną ograniczoną próbę ponowienia z tokenem per urządzenie z pamięci podręcznej. + - Jeśli to ponowienie się nie powiedzie, klienci powinni zatrzymać automatyczne pętle ponownego łączenia i wyświetlić operatorowi wskazówki dotyczące działania. ## Tożsamość urządzenia + parowanie - Węzły powinny zawierać stabilną tożsamość urządzenia (`device.id`) wyprowadzoną z - fingerprintu pary kluczy. -- Gateway wydaje tokeny per urządzenie + rola. -- Dla nowych `deviceId` wymagane są zatwierdzenia parowania, chyba że włączono lokalne auto-zatwierdzanie. -- Auto-zatwierdzanie parowania jest skoncentrowane na bezpośrednich lokalnych połączeniach loopback. -- OpenClaw ma także wąską ścieżkę backend/container-local self-connect dla + odcisku palca pary kluczy. +- Gateway wydaje tokeny dla każdego urządzenia + roli. +- Zatwierdzenia parowania są wymagane dla nowych identyfikatorów urządzeń, chyba że włączono + lokalne automatyczne zatwierdzanie. +- Automatyczne zatwierdzanie parowania jest skoncentrowane na bezpośrednich lokalnych połączeniach local loopback. +- OpenClaw ma także wąską ścieżkę samopołączenia backend/kontener-local dla zaufanych przepływów pomocniczych ze współdzielonym sekretem. -- Połączenia tailnet lub LAN z tego samego hosta nadal są traktowane jako zdalne w kontekście parowania i +- Połączenia tailnet lub LAN z tego samego hosta są nadal traktowane jako zdalne na potrzeby parowania i wymagają zatwierdzenia. -- Wszyscy klienci WS muszą zawierać tożsamość `device` podczas `connect` (operator + node). +- Wszyscy klienci WS muszą dołączać tożsamość `device` podczas `connect` (operator + node). Control UI może ją pominąć tylko w tych trybach: - - `gateway.controlUi.allowInsecureAuth=true` dla zgodności z niezabezpieczonym HTTP tylko dla localhost. - - udane auth operatora `gateway.auth.mode: "trusted-proxy"` dla Control UI. + - `gateway.controlUi.allowInsecureAuth=true` dla zgodności z niezabezpieczonym HTTP tylko na localhost. + - udane uwierzytelnianie operatora Control UI z `gateway.auth.mode: "trusted-proxy"`. - `gateway.controlUi.dangerouslyDisableDeviceAuth=true` (tryb awaryjny, poważne obniżenie bezpieczeństwa). -- Wszystkie połączenia muszą podpisywać dostarczony przez serwer nonce `connect.challenge`. +- Wszystkie połączenia muszą podpisywać nonce dostarczone przez serwer w `connect.challenge`. -### Diagnostyka migracji auth urządzeń +### Diagnostyka migracji uwierzytelniania urządzenia -Dla starszych klientów, którzy nadal używają zachowania podpisywania sprzed wyzwania, `connect` zwraca teraz +Dla starszych klientów, którzy nadal używają zachowania podpisywania sprzed wyzwania, `connect` teraz zwraca kody szczegółów `DEVICE_AUTH_*` pod `error.details.code` ze stabilnym `error.details.reason`. -Typowe błędy migracji: +Typowe niepowodzenia migracji: -| Komunikat | details.code | details.reason | Znaczenie | +| Komunikat | details.code | details.reason | Znaczenie | | --------------------------- | -------------------------------- | ------------------------ | -------------------------------------------------- | -| `device nonce required` | `DEVICE_AUTH_NONCE_REQUIRED` | `device-nonce-missing` | Klient pominął `device.nonce` (lub wysłał pusty). | -| `device nonce mismatch` | `DEVICE_AUTH_NONCE_MISMATCH` | `device-nonce-mismatch` | Klient podpisał przy użyciu nieaktualnego/błędnego nonce. | -| `device signature invalid` | `DEVICE_AUTH_SIGNATURE_INVALID` | `device-signature` | Ładunek podpisu nie odpowiada ładunkowi v2. | -| `device signature expired` | `DEVICE_AUTH_SIGNATURE_EXPIRED` | `device-signature-stale` | Podpisany znacznik czasu jest poza dozwolonym odchyleniem. | -| `device identity mismatch` | `DEVICE_AUTH_DEVICE_ID_MISMATCH` | `device-id-mismatch` | `device.id` nie pasuje do fingerprintu klucza publicznego. | -| `device public key invalid` | `DEVICE_AUTH_PUBLIC_KEY_INVALID` | `device-public-key` | Format/kanonizacja klucza publicznego nie powiodły się. | +| `device nonce required` | `DEVICE_AUTH_NONCE_REQUIRED` | `device-nonce-missing` | Klient pominął `device.nonce` (lub wysłał pusty). | +| `device nonce mismatch` | `DEVICE_AUTH_NONCE_MISMATCH` | `device-nonce-mismatch` | Klient podpisał starym/błędnym nonce. | +| `device signature invalid` | `DEVICE_AUTH_SIGNATURE_INVALID` | `device-signature` | Ładunek podpisu nie pasuje do ładunku v2. | +| `device signature expired` | `DEVICE_AUTH_SIGNATURE_EXPIRED` | `device-signature-stale` | Podpisany znacznik czasu jest poza dozwolonym odchyleniem. | +| `device identity mismatch` | `DEVICE_AUTH_DEVICE_ID_MISMATCH` | `device-id-mismatch` | `device.id` nie pasuje do odcisku palca klucza publicznego. | +| `device public key invalid` | `DEVICE_AUTH_PUBLIC_KEY_INVALID` | `device-public-key` | Format/kanonikalizacja klucza publicznego nie powiodły się. | Cel migracji: - Zawsze czekaj na `connect.challenge`. - Podpisuj ładunek v2, który zawiera nonce serwera. -- Wysyłaj ten sam nonce w `connect.params.device.nonce`. +- Wyślij ten sam nonce w `connect.params.device.nonce`. - Preferowany ładunek podpisu to `v3`, który wiąże `platform` i `deviceFamily` oprócz pól device/client/role/scopes/token/nonce. -- Starsze podpisy `v2` pozostają akceptowane dla zgodności, ale przypinanie metadanych - sparowanych urządzeń nadal steruje polityką poleceń przy ponownym połączeniu. +- Starsze podpisy `v2` pozostają akceptowane ze względu na zgodność, ale przypinanie metadanych sparowanego urządzenia nadal kontroluje politykę poleceń przy ponownym połączeniu. ## TLS + pinning - TLS jest obsługiwany dla połączeń WS. -- Klienci mogą opcjonalnie przypinać fingerprint certyfikatu gateway (zobacz konfigurację `gateway.tls` +- Klienci mogą opcjonalnie przypiąć odcisk palca certyfikatu gateway (zobacz konfigurację `gateway.tls` oraz `gateway.remote.tlsFingerprint` lub flagę CLI `--tls-fingerprint`). ## Zakres -Ten protokół udostępnia **pełne API gateway** (status, kanały, models, chat, -agent, sessions, nodes, approvals itd.). Dokładna powierzchnia jest definiowana przez +Ten protokół udostępnia **pełne API gateway** (status, kanały, modele, czat, +agent, sesje, węzły, zatwierdzenia itd.). Dokładna powierzchnia jest zdefiniowana przez schematy TypeBox w `src/gateway/protocol/schema.ts`. diff --git a/docs/pl/gateway/troubleshooting.md b/docs/pl/gateway/troubleshooting.md index b52b3e088..72733fad3 100644 --- a/docs/pl/gateway/troubleshooting.md +++ b/docs/pl/gateway/troubleshooting.md @@ -1,26 +1,26 @@ --- read_when: - - Centrum rozwiązywania problemów skierowało Cię tutaj w celu głębszej diagnostyki - - Potrzebujesz stabilnych sekcji podręcznika opartych na objawach z dokładnymi poleceniami -summary: Szczegółowy podręcznik rozwiązywania problemów dotyczących gateway, kanałów, automatyzacji, węzłów i przeglądarki + - Centrum rozwiązywania problemów skierowało Cię tutaj w celu głębszej diagnozy + - Potrzebujesz stabilnych sekcji poradnika opartych na objawach z dokładnymi poleceniami +summary: Szczegółowy poradnik rozwiązywania problemów z gateway, kanałami, automatyzacją, węzłami i przeglądarką title: Rozwiązywanie problemów x-i18n: - generated_at: "2026-04-07T09:46:00Z" + generated_at: "2026-04-08T02:16:03Z" model: gpt-5.4 provider: openai - source_hash: e0202e8858310a0bfc1c994cd37b01c3b2d6c73c8a74740094e92dc3c4c36729 + source_hash: 02c9537845248db0c9d315bf581338a93215fe6fe3688ed96c7105cbb19fe6ba source_path: gateway/troubleshooting.md workflow: 15 --- # Rozwiązywanie problemów z gateway -Ta strona to szczegółowy podręcznik. -Zacznij od [/help/troubleshooting](/pl/help/troubleshooting), jeśli najpierw chcesz skorzystać z szybkiego przepływu triage. +Ta strona to szczegółowy poradnik. +Zacznij od [/help/troubleshooting](/pl/help/troubleshooting), jeśli najpierw chcesz skorzystać z szybkiego procesu diagnostycznego. ## Drabina poleceń -Uruchom najpierw te polecenia, w tej kolejności: +Uruchom te polecenia najpierw, w tej kolejności: ```bash openclaw status @@ -33,11 +33,11 @@ openclaw channels status --probe Oczekiwane sygnały zdrowego działania: - `openclaw gateway status` pokazuje `Runtime: running` i `RPC probe: ok`. -- `openclaw doctor` nie zgłasza blokujących problemów z konfiguracją/usługą. -- `openclaw channels status --probe` pokazuje stan transportu dla każdego konta na żywo oraz, - tam gdzie jest to obsługiwane, wyniki probe/audytu, takie jak `works` lub `audit ok`. +- `openclaw doctor` nie zgłasza blokujących problemów z konfiguracją ani usługą. +- `openclaw channels status --probe` pokazuje bieżący stan transportu dla każdego konta oraz, + tam gdzie jest to obsługiwane, wyniki sondy/audytu, takie jak `works` lub `audit ok`. -## Anthropic 429: dodatkowe użycie wymagane dla długiego kontekstu +## Anthropic 429: wymagane dodatkowe użycie dla długiego kontekstu Użyj tego, gdy logi/błędy zawierają: `HTTP 429: rate_limit_error: Extra usage is required for long context requests`. @@ -48,17 +48,17 @@ openclaw models status openclaw config get agents.defaults.models ``` -Poszukaj: +Szukaj: - Wybrany model Anthropic Opus/Sonnet ma `params.context1m: true`. - Bieżące poświadczenie Anthropic nie kwalifikuje się do użycia długiego kontekstu. -- Żądania zawodzą tylko w długich sesjach/uruchomieniach modelu, które wymagają ścieżki beta 1M. +- Żądania kończą się niepowodzeniem tylko w długich sesjach/uruchomieniach modelu, które wymagają ścieżki 1M beta. Opcje naprawy: 1. Wyłącz `context1m` dla tego modelu, aby wrócić do zwykłego okna kontekstu. 2. Użyj poświadczenia Anthropic, które kwalifikuje się do żądań długiego kontekstu, albo przełącz się na klucz API Anthropic. -3. Skonfiguruj modele zapasowe, aby uruchomienia były kontynuowane, gdy żądania Anthropic dla długiego kontekstu są odrzucane. +3. Skonfiguruj modele zapasowe, aby uruchomienia były kontynuowane, gdy żądania długiego kontekstu Anthropic są odrzucane. Powiązane: @@ -66,9 +66,60 @@ Powiązane: - [/reference/token-use](/pl/reference/token-use) - [/help/faq#why-am-i-seeing-http-429-ratelimiterror-from-anthropic](/pl/help/faq#why-am-i-seeing-http-429-ratelimiterror-from-anthropic) +## Lokalny backend zgodny z OpenAI przechodzi bezpośrednie sondy, ale uruchomienia agenta kończą się niepowodzeniem + +Użyj tego, gdy: + +- `curl ... /v1/models` działa +- małe bezpośrednie wywołania `/v1/chat/completions` działają +- uruchomienia modeli OpenClaw kończą się niepowodzeniem tylko podczas zwykłych tur agenta + +```bash +curl http://127.0.0.1:1234/v1/models +curl http://127.0.0.1:1234/v1/chat/completions \ + -H 'content-type: application/json' \ + -d '{"model":"","messages":[{"role":"user","content":"hi"}],"stream":false}' +openclaw infer model run --model --prompt "hi" --json +openclaw logs --follow +``` + +Szukaj: + +- małe bezpośrednie wywołania kończą się powodzeniem, ale uruchomienia OpenClaw kończą się niepowodzeniem tylko przy większych promptach +- błędów backendu dotyczących tego, że `messages[].content` ma oczekiwać ciągu znaków +- awarii backendu, które pojawiają się tylko przy większej liczbie tokenów promptu lub pełnych promptach środowiska uruchomieniowego agenta + +Typowe sygnatury: + +- `messages[...].content: invalid type: sequence, expected a string` → backend + odrzuca strukturalne części treści Chat Completions. Poprawka: ustaw + `models.providers..models[].compat.requiresStringContent: true`. +- małe bezpośrednie żądania kończą się powodzeniem, ale uruchomienia agenta OpenClaw kończą się niepowodzeniem z awariami backendu/modelu + (na przykład Gemma w niektórych kompilacjach `inferrs`) → transport OpenClaw + jest prawdopodobnie już poprawny; to backend zawodzi przy większym kształcie promptu środowiska uruchomieniowego agenta. +- niepowodzenia zmniejszają się po wyłączeniu narzędzi, ale nie znikają → schematy narzędzi + były częścią obciążenia, ale pozostały problem nadal dotyczy pojemności modelu/serwera po stronie upstream albo błędu backendu. + +Opcje naprawy: + +1. Ustaw `compat.requiresStringContent: true` dla backendów Chat Completions obsługujących wyłącznie ciągi znaków. +2. Ustaw `compat.supportsTools: false` dla modeli/backendów, które nie są w stanie + niezawodnie obsłużyć powierzchni schematu narzędzi OpenClaw. +3. Ogranicz obciążenie promptu tam, gdzie to możliwe: mniejszy bootstrap obszaru roboczego, krótsza + historia sesji, lżejszy model lokalny lub backend z lepszym wsparciem dla długiego kontekstu. +4. Jeśli małe bezpośrednie żądania nadal przechodzą, a tury agenta OpenClaw wciąż ulegają awarii + wewnątrz backendu, potraktuj to jako ograniczenie serwera/modelu po stronie upstream i zgłoś tam + reprodukcję z zaakceptowanym kształtem ładunku. + +Powiązane: + +- [/gateway/local-models](/pl/gateway/local-models) +- [/gateway/configuration#models](/pl/gateway/configuration#models) +- [/gateway/configuration-reference#openai-compatible-endpoints](/pl/gateway/configuration-reference#openai-compatible-endpoints) + ## Brak odpowiedzi -Jeśli kanały działają, ale nic nie odpowiada, sprawdź routing i zasady przed ponownym łączeniem czegokolwiek. +Jeśli kanały działają, ale nic nie odpowiada, sprawdź routing i politykę, zanim cokolwiek ponownie połączysz. ```bash openclaw status @@ -78,17 +129,17 @@ openclaw config get channels openclaw logs --follow ``` -Poszukaj: +Szukaj: -- Oczekującego parowania dla nadawców DM. -- Bramek wzmianek w grupie (`requireMention`, `mentionPatterns`). -- Niezgodności list dozwolonych kanałów/grup. +- Oczekiwania na parowanie dla nadawców wiadomości prywatnych. +- Wymogu wspomnienia w grupie (`requireMention`, `mentionPatterns`). +- Niezgodności z listą dozwolonych kanałów/grup. Typowe sygnatury: -- `drop guild message (mention required` → wiadomość grupowa ignorowana do czasu wzmianki. +- `drop guild message (mention required` → wiadomość grupowa została zignorowana do czasu wspomnienia. - `pairing request` → nadawca wymaga zatwierdzenia. -- `blocked` / `allowlist` → nadawca/kanał został odfiltrowany przez zasady. +- `blocked` / `allowlist` → nadawca/kanał został odfiltrowany przez politykę. Powiązane: @@ -98,7 +149,7 @@ Powiązane: ## Łączność dashboard/control UI -Gdy dashboard/control UI nie chce się połączyć, zweryfikuj URL, tryb auth i założenia dotyczące secure context. +Gdy dashboard/control UI nie chce się połączyć, sprawdź adres URL, tryb uwierzytelniania i założenia dotyczące bezpiecznego kontekstu. ```bash openclaw gateway status @@ -108,50 +159,50 @@ openclaw doctor openclaw gateway status --json ``` -Poszukaj: +Szukaj: -- Prawidłowego adresu probe i adresu dashboard. -- Niezgodności trybu auth/tokenu między klientem a gateway. +- Poprawnego adresu URL sondy i adresu URL dashboardu. +- Niezgodności trybu/tokena uwierzytelniania między klientem a gateway. - Użycia HTTP tam, gdzie wymagana jest tożsamość urządzenia. Typowe sygnatury: -- `device identity required` → niebezpieczny kontekst lub brak auth urządzenia. +- `device identity required` → niezabezpieczony kontekst lub brak uwierzytelnienia urządzenia. - `origin not allowed` → `Origin` przeglądarki nie znajduje się w `gateway.controlUi.allowedOrigins` (albo łączysz się z pochodzenia przeglądarki innego niż loopback bez jawnej listy dozwolonych). - `device nonce required` / `device nonce mismatch` → klient nie kończy - przepływu auth urządzenia opartego na wyzwaniu (`connect.challenge` + `device.nonce`). -- `device signature invalid` / `device signature expired` → klient podpisał niewłaściwy - ładunek (albo użył nieaktualnego znacznika czasu) dla bieżącego handshake. -- `AUTH_TOKEN_MISMATCH` z `canRetryWithDeviceToken=true` → klient może wykonać jedną zaufaną ponowną próbę z buforowanym tokenem urządzenia. -- Ta ponowna próba z buforowanym tokenem ponownie używa buforowanego zestawu zakresów przechowywanego z sparowanym - tokenem urządzenia. Wywołania z jawnym `deviceToken` / jawnymi `scopes` zachowują - swój żądany zestaw zakresów. -- Poza tą ścieżką ponownej próby kolejność auth przy połączeniu to najpierw jawny współdzielony - token/hasło, potem jawny `deviceToken`, potem zapisany token urządzenia, - a na końcu token bootstrap. -- W asynchronicznej ścieżce Tailscale Serve Control UI nieudane próby dla tego samego - `{scope, ip}` są serializowane, zanim limiter zarejestruje niepowodzenie. Dwie błędne - równoczesne ponowne próby od tego samego klienta mogą więc skutkować komunikatem `retry later` - przy drugiej próbie zamiast dwóch zwykłych niezgodności. -- `too many failed authentication attempts (retry later)` z klienta loopback - o pochodzeniu przeglądarki → powtarzające się niepowodzenia z tego samego znormalizowanego `Origin` są tymczasowo blokowane; inne pochodzenie localhost używa oddzielnego bucketu. -- powtarzające się `unauthorized` po tej ponownej próbie → rozjazd współdzielonego tokenu/tokenu urządzenia; odśwież konfigurację tokenu i ponownie zatwierdź/obróć token urządzenia, jeśli to potrzebne. -- `gateway connect failed:` → nieprawidłowy host/port/docelowy URL. + przepływu uwierzytelniania urządzenia opartego na wyzwaniu (`connect.challenge` + `device.nonce`). +- `device signature invalid` / `device signature expired` → klient podpisał nieprawidłowy + ładunek (albo użył nieaktualnego znacznika czasu) dla bieżącego uzgadniania. +- `AUTH_TOKEN_MISMATCH` z `canRetryWithDeviceToken=true` → klient może wykonać jedną zaufaną ponowną próbę z użyciem buforowanego tokena urządzenia. +- Ta ponowna próba z użyciem tokena z pamięci podręcznej wykorzystuje zestaw zakresów przechowywany z powiązanym + tokenem urządzenia. Wywołujący z jawnym `deviceToken` / jawnymi `scopes` zachowują zamiast tego + żądany zestaw zakresów. +- Poza tą ścieżką ponownej próby pierwszeństwo uwierzytelniania połączenia jest następujące: jawny współdzielony + token/hasło najpierw, potem jawny `deviceToken`, potem zapisany token urządzenia, + a następnie token bootstrap. +- Na asynchronicznej ścieżce Tailscale Serve Control UI nieudane próby dla tego samego + `{scope, ip}` są serializowane, zanim ogranicznik zarejestruje niepowodzenie. Dwie błędne + równoczesne ponowne próby od tego samego klienta mogą więc skutkować `retry later` + przy drugiej próbie zamiast dwóch zwykłych niedopasowań. +- `too many failed authentication attempts (retry later)` z klienta loopback o pochodzeniu przeglądarki + → powtarzające się niepowodzenia z tego samego znormalizowanego `Origin` są tymczasowo blokowane; inne pochodzenie localhost używa osobnego zasobnika. +- powtarzające się `unauthorized` po tej ponownej próbie → rozjazd współdzielonego tokena/tokena urządzenia; odśwież konfigurację tokena i ponownie zatwierdź/obróć token urządzenia, jeśli to konieczne. +- `gateway connect failed:` → nieprawidłowy host/port/docelowy adres URL. -### Szybka mapa kodów szczegółów auth +### Szybka mapa szczegółowych kodów uwierzytelniania -Użyj `error.details.code` z nieudanego response `connect`, aby wybrać następne działanie: +Użyj `error.details.code` z nieudanego połączenia `connect`, aby wybrać następne działanie: -| Detail code | Meaning | Recommended action | -| ---------------------------- | ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `AUTH_TOKEN_MISSING` | Klient nie wysłał wymaganego współdzielonego tokenu. | Wklej/ustaw token w kliencie i spróbuj ponownie. Dla ścieżek dashboard: `openclaw config get gateway.auth.token`, a następnie wklej do ustawień Control UI. | -| `AUTH_TOKEN_MISMATCH` | Współdzielony token nie pasował do tokenu auth gateway. | Jeśli `canRetryWithDeviceToken=true`, pozwól na jedną zaufaną ponowną próbę. Ponowne próby z buforowanym tokenem używają zapisanych zatwierdzonych zakresów; wywołania z jawnym `deviceToken` / `scopes` zachowują żądane zakresy. Jeśli nadal się nie udaje, uruchom [listę kontrolną odzyskiwania po rozjeździe tokenu](/cli/devices#token-drift-recovery-checklist). | -| `AUTH_DEVICE_TOKEN_MISMATCH` | Buforowany token per urządzenie jest nieaktualny lub cofnięty. | Obróć/ponownie zatwierdź token urządzenia za pomocą [CLI urządzeń](/cli/devices), a następnie połącz ponownie. | -| `PAIRING_REQUIRED` | Tożsamość urządzenia jest znana, ale niezatwierdzona dla tej roli. | Zatwierdź oczekujące żądanie: `openclaw devices list`, a następnie `openclaw devices approve `. | +| Detail code | Znaczenie | Zalecane działanie | +| ---------------------------- | -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `AUTH_TOKEN_MISSING` | Klient nie wysłał wymaganego współdzielonego tokena. | Wklej/ustaw token w kliencie i spróbuj ponownie. Dla ścieżek dashboardu: `openclaw config get gateway.auth.token`, a następnie wklej go do ustawień Control UI. | +| `AUTH_TOKEN_MISMATCH` | Współdzielony token nie pasował do tokena auth gateway. | Jeśli `canRetryWithDeviceToken=true`, zezwól na jedną zaufaną ponowną próbę. Ponowne próby z tokenem z pamięci podręcznej wykorzystują zapisane zatwierdzone zakresy; wywołujący z jawnym `deviceToken` / `scopes` zachowują żądane zakresy. Jeśli nadal się nie powiedzie, wykonaj [listę kontrolną odzyskiwania po rozjeździe tokena](/cli/devices#token-drift-recovery-checklist). | +| `AUTH_DEVICE_TOKEN_MISMATCH` | Buforowany token dla urządzenia jest nieaktualny lub cofnięty. | Obróć/ponownie zatwierdź token urządzenia za pomocą [CLI urządzeń](/cli/devices), a następnie połącz się ponownie. | +| `PAIRING_REQUIRED` | Tożsamość urządzenia jest znana, ale niezatwierdzona dla tej roli. | Zatwierdź oczekujące żądanie: `openclaw devices list`, a następnie `openclaw devices approve `. | -Kontrola migracji auth urządzeń v2: +Sprawdzenie migracji uwierzytelniania urządzenia v2: ```bash openclaw --version @@ -159,23 +210,23 @@ openclaw doctor openclaw gateway status ``` -Jeśli logi pokazują błędy nonce/signature, zaktualizuj klienta łączącego się i zweryfikuj, że: +Jeśli logi pokazują błędy nonce/podpisu, zaktualizuj łączącego się klienta i sprawdź, czy: 1. czeka na `connect.challenge` -2. podpisuje ładunek związany z wyzwaniem +2. podpisuje ładunek powiązany z wyzwaniem 3. wysyła `connect.params.device.nonce` z tym samym nonce wyzwania Jeśli `openclaw devices rotate` / `revoke` / `remove` jest nieoczekiwanie odrzucane: -- sesje tokenów sparowanych urządzeń mogą zarządzać tylko **własnym** urządzeniem, chyba że +- sesje tokena sparowanego urządzenia mogą zarządzać tylko **własnym** urządzeniem, chyba że wywołujący ma również `operator.admin` -- `openclaw devices rotate --scope ...` może żądać tylko takich zakresów operatora, - które sesja wywołująca już posiada +- `openclaw devices rotate --scope ...` może żądać tylko zakresów operatora, które + sesja wywołującego już posiada Powiązane: - [/web/control-ui](/web/control-ui) -- [/gateway/configuration](/pl/gateway/configuration) (tryby auth gateway) +- [/gateway/configuration](/pl/gateway/configuration) (tryby uwierzytelniania gateway) - [/gateway/trusted-proxy-auth](/pl/gateway/trusted-proxy-auth) - [/gateway/remote](/pl/gateway/remote) - [/cli/devices](/cli/devices) @@ -189,23 +240,23 @@ openclaw gateway status openclaw status openclaw logs --follow openclaw doctor -openclaw gateway status --deep # skanuje też usługi na poziomie systemu +openclaw gateway status --deep # also scan system-level services ``` -Poszukaj: +Szukaj: -- `Runtime: stopped` ze wskazówkami dotyczącymi zakończenia. +- `Runtime: stopped` z podpowiedziami dotyczącymi zakończenia. - Niezgodności konfiguracji usługi (`Config (cli)` vs `Config (service)`). - Konfliktów portów/listenerów. -- Dodatkowych instalacji launchd/systemd/schtasks, gdy użyto `--deep`. +- Dodatkowych instalacji launchd/systemd/schtasks przy użyciu `--deep`. - Wskazówek czyszczenia `Other gateway-like services detected (best effort)`. Typowe sygnatury: -- `Gateway start blocked: set gateway.mode=local` lub `existing config is missing gateway.mode` → lokalny tryb gateway nie jest włączony albo plik konfiguracji został nadpisany i utracił `gateway.mode`. Naprawa: ustaw `gateway.mode="local"` w konfiguracji albo uruchom ponownie `openclaw onboard --mode local` / `openclaw setup`, aby ponownie zapisać oczekiwaną konfigurację trybu lokalnego. Jeśli uruchamiasz OpenClaw przez Podman, domyślną ścieżką konfiguracji jest `~/.openclaw/openclaw.json`. -- `refusing to bind gateway ... without auth` → powiązanie inne niż loopback bez prawidłowej ścieżki auth gateway (token/hasło lub trusted-proxy, jeśli skonfigurowano). +- `Gateway start blocked: set gateway.mode=local` lub `existing config is missing gateway.mode` → tryb lokalny gateway nie jest włączony albo plik konfiguracji został uszkodzony i utracił `gateway.mode`. Poprawka: ustaw `gateway.mode="local"` w konfiguracji albo uruchom ponownie `openclaw onboard --mode local` / `openclaw setup`, aby ponownie zapisać oczekiwaną konfigurację trybu lokalnego. Jeśli uruchamiasz OpenClaw przez Podman, domyślna ścieżka konfiguracji to `~/.openclaw/openclaw.json`. +- `refusing to bind gateway ... without auth` → powiązanie inne niż loopback bez prawidłowej ścieżki uwierzytelniania gateway (token/hasło albo trusted-proxy tam, gdzie jest skonfigurowane). - `another gateway instance is already listening` / `EADDRINUSE` → konflikt portu. -- `Other gateway-like services detected (best effort)` → istnieją nieaktualne lub równoległe jednostki launchd/systemd/schtasks. Większość konfiguracji powinna utrzymywać jeden gateway na maszynę; jeśli rzeczywiście potrzebujesz więcej niż jednego, odizoluj porty + konfigurację/stan/workspace. Zobacz [/gateway#multiple-gateways-same-host](/pl/gateway#multiple-gateways-same-host). +- `Other gateway-like services detected (best effort)` → istnieją nieaktualne lub równoległe jednostki launchd/systemd/schtasks. Większość konfiguracji powinna utrzymywać jeden gateway na maszynę; jeśli faktycznie potrzebujesz więcej niż jednego, odizoluj porty + konfigurację/stan/obszar roboczy. Zobacz [/gateway#multiple-gateways-same-host](/pl/gateway#multiple-gateways-same-host). Powiązane: @@ -213,9 +264,9 @@ Powiązane: - [/gateway/configuration](/pl/gateway/configuration) - [/gateway/doctor](/pl/gateway/doctor) -## Ostrzeżenia probe gateway +## Ostrzeżenia sondy gateway -Użyj tego, gdy `openclaw gateway probe` do czegoś dociera, ale nadal wyświetla blok ostrzeżenia. +Użyj tego, gdy `openclaw gateway probe` dociera do celu, ale mimo to wyświetla blok ostrzeżenia. ```bash openclaw gateway probe @@ -223,17 +274,17 @@ openclaw gateway probe --json openclaw gateway probe --ssh user@gateway-host ``` -Poszukaj: +Szukaj: -- `warnings[].code` i `primaryTargetId` w wyjściu JSON. -- Czy ostrzeżenie dotyczy zapasowej ścieżki SSH, wielu gateway, brakujących zakresów czy nierozwiązanych odwołań auth. +- `warnings[].code` i `primaryTargetId` w danych wyjściowych JSON. +- Czy ostrzeżenie dotyczy zapasowej ścieżki SSH, wielu gateway, brakujących zakresów, czy nierozwiązanych odwołań auth. Typowe sygnatury: - `SSH tunnel failed to start; falling back to direct probes.` → konfiguracja SSH nie powiodła się, ale polecenie nadal próbowało bezpośrednich skonfigurowanych/docelowych loopback. -- `multiple reachable gateways detected` → odpowiedziało więcej niż jedno miejsce docelowe. Zwykle oznacza to zamierzoną konfigurację wielu gateway albo nieaktualne/zduplikowane listenery. -- `Probe diagnostics are limited by gateway scopes (missing operator.read)` → połączenie działa, ale szczegóły RPC są ograniczone zakresem; sparuj tożsamość urządzenia albo użyj poświadczeń z `operator.read`. -- nierozwiązany tekst ostrzeżenia `gateway.auth.*` / `gateway.remote.*` SecretRef → materiał auth był niedostępny w tej ścieżce polecenia dla nieudanego celu. +- `multiple reachable gateways detected` → odpowiedział więcej niż jeden cel. Zwykle oznacza to celową konfigurację wielu gateway albo nieaktualne/zduplikowane listenery. +- `Probe diagnostics are limited by gateway scopes (missing operator.read)` → połączenie zadziałało, ale szczegółowe RPC jest ograniczone zakresem; sparuj tożsamość urządzenia albo użyj poświadczeń z `operator.read`. +- nierozwiązany tekst ostrzeżenia `gateway.auth.*` / `gateway.remote.*` SecretRef → materiał uwierzytelniający był niedostępny na tej ścieżce polecenia dla nieudanego celu. Powiązane: @@ -241,9 +292,9 @@ Powiązane: - [/gateway#multiple-gateways-same-host](/pl/gateway#multiple-gateways-same-host) - [/gateway/remote](/pl/gateway/remote) -## Kanał jest połączony, ale wiadomości nie płyną +## Kanał jest połączony, ale wiadomości nie przepływają -Jeśli stan kanału pokazuje połączenie, ale przepływ wiadomości nie działa, skup się na zasadach, uprawnieniach i regułach dostarczania specyficznych dla kanału. +Jeśli stan kanału to connected, ale przepływ wiadomości nie działa, skup się na polityce, uprawnieniach i regułach dostarczania specyficznych dla kanału. ```bash openclaw channels status --probe @@ -253,17 +304,17 @@ openclaw logs --follow openclaw config get channels ``` -Poszukaj: +Szukaj: -- Zasad DM (`pairing`, `allowlist`, `open`, `disabled`). -- Listy dozwolonych grup i wymagań wzmianek. +- Polityki DM (`pairing`, `allowlist`, `open`, `disabled`). +- Listy dozwolonych grup i wymogów wspomnienia. - Brakujących uprawnień/zakresów API kanału. Typowe sygnatury: -- `mention required` → wiadomość zignorowana przez zasady wzmianek grupowych. -- ślady `pairing` / oczekującego zatwierdzenia → nadawca nie jest zatwierdzony. -- `missing_scope`, `not_in_channel`, `Forbidden`, `401/403` → problem z auth/uprawnieniami kanału. +- `mention required` → wiadomość została zignorowana przez politykę wspomnień grupowych. +- `pairing` / ślady oczekującego zatwierdzenia → nadawca nie jest zatwierdzony. +- `missing_scope`, `not_in_channel`, `Forbidden`, `401/403` → problem z uwierzytelnianiem/uprawnieniami kanału. Powiązane: @@ -274,7 +325,7 @@ Powiązane: ## Dostarczanie cron i heartbeat -Jeśli cron lub heartbeat nie uruchomiły się albo nic nie dostarczyły, najpierw zweryfikuj stan harmonogramu, a potem cel dostarczania. +Jeśli cron lub heartbeat nie uruchomił się albo nie dostarczył wyniku, najpierw sprawdź stan harmonogramu, a następnie cel dostarczenia. ```bash openclaw cron status @@ -284,21 +335,21 @@ openclaw system heartbeat last openclaw logs --follow ``` -Poszukaj: +Szukaj: -- Włączonego cron i obecności następnego wybudzenia. +- Czy cron jest włączony i czy ma zaplanowane następne wybudzenie. - Statusu historii uruchomień zadania (`ok`, `skipped`, `error`). - Powodów pominięcia heartbeat (`quiet-hours`, `requests-in-flight`, `alerts-disabled`, `empty-heartbeat-file`, `no-tasks-due`). Typowe sygnatury: -- `cron: scheduler disabled; jobs will not run automatically` → cron wyłączony. -- `cron: timer tick failed` → tick harmonogramu nie powiódł się; sprawdź błędy pliku/logów/runtime. +- `cron: scheduler disabled; jobs will not run automatically` → cron jest wyłączony. +- `cron: timer tick failed` → tyknięcie harmonogramu nie powiodło się; sprawdź błędy plików/logów/runtime. - `heartbeat skipped` z `reason=quiet-hours` → poza oknem aktywnych godzin. - `heartbeat skipped` z `reason=empty-heartbeat-file` → `HEARTBEAT.md` istnieje, ale zawiera tylko puste linie / nagłówki markdown, więc OpenClaw pomija wywołanie modelu. -- `heartbeat skipped` z `reason=no-tasks-due` → `HEARTBEAT.md` zawiera blok `tasks:`, ale żadne zadania nie są należne przy tym ticku. -- `heartbeat: unknown accountId` → nieprawidłowy account id dla celu dostarczania heartbeat. -- `heartbeat skipped` z `reason=dm-blocked` → cel heartbeat został rozwiązany do miejsca docelowego w stylu DM, podczas gdy `agents.defaults.heartbeat.directPolicy` (lub nadpisanie per agent) ma wartość `block`. +- `heartbeat skipped` z `reason=no-tasks-due` → `HEARTBEAT.md` zawiera blok `tasks:`, ale żadne zadanie nie jest wymagalne przy tym tyknięciu. +- `heartbeat: unknown accountId` → nieprawidłowy identyfikator konta dla celu dostarczenia heartbeat. +- `heartbeat skipped` z `reason=dm-blocked` → cel heartbeat został rozpoznany jako miejsce docelowe w stylu DM, podczas gdy `agents.defaults.heartbeat.directPolicy` (lub nadpisanie dla konkretnego agenta) ma ustawienie `block`. Powiązane: @@ -306,7 +357,7 @@ Powiązane: - [/automation/cron-jobs](/pl/automation/cron-jobs) - [/gateway/heartbeat](/pl/gateway/heartbeat) -## Narzędzie sparowanego węzła nie działa +## Narzędzie sparowanego węzła kończy się niepowodzeniem Jeśli węzeł jest sparowany, ale narzędzia nie działają, odizoluj stan pierwszego planu, uprawnień i zatwierdzeń. @@ -318,18 +369,18 @@ openclaw logs --follow openclaw status ``` -Poszukaj: +Szukaj: -- Czy węzeł jest online i ma oczekiwane możliwości. -- Czy przyznano uprawnienia systemu operacyjnego do kamery/mikrofonu/lokalizacji/ekranu. -- Stanu zatwierdzeń exec i listy dozwolonych. +- Czy węzeł jest online z oczekiwanymi możliwościami. +- Przyznanych uprawnień systemu operacyjnego do kamery/mikrofonu/lokalizacji/ekranu. +- Stanu zatwierdzeń wykonania i listy dozwolonych. Typowe sygnatury: - `NODE_BACKGROUND_UNAVAILABLE` → aplikacja węzła musi być na pierwszym planie. -- `*_PERMISSION_REQUIRED` / `LOCATION_PERMISSION_REQUIRED` → brak wymaganego uprawnienia systemowego. -- `SYSTEM_RUN_DENIED: approval required` → oczekujące zatwierdzenie exec. -- `SYSTEM_RUN_DENIED: allowlist miss` → polecenie zablokowane przez listę dozwolonych. +- `*_PERMISSION_REQUIRED` / `LOCATION_PERMISSION_REQUIRED` → brak uprawnienia systemowego. +- `SYSTEM_RUN_DENIED: approval required` → oczekuje zatwierdzenie wykonania. +- `SYSTEM_RUN_DENIED: allowlist miss` → polecenie zostało zablokowane przez listę dozwolonych. Powiązane: @@ -337,9 +388,9 @@ Powiązane: - [/nodes/index](/pl/nodes/index) - [/tools/exec-approvals](/pl/tools/exec-approvals) -## Narzędzie przeglądarki nie działa +## Narzędzie przeglądarki kończy się niepowodzeniem -Użyj tego, gdy działania narzędzia przeglądarki zawodzą, mimo że sam gateway działa poprawnie. +Użyj tego, gdy działania narzędzia przeglądarki kończą się niepowodzeniem, mimo że sam gateway działa prawidłowo. ```bash openclaw browser status @@ -349,10 +400,10 @@ openclaw logs --follow openclaw doctor ``` -Poszukaj: +Szukaj: - Czy `plugins.allow` jest ustawione i zawiera `browser`. -- Prawidłowej ścieżki do pliku wykonywalnego przeglądarki. +- Prawidłowej ścieżki do wykonywalnego pliku przeglądarki. - Osiągalności profilu CDP. - Dostępności lokalnego Chrome dla profili `existing-session` / `user`. @@ -362,19 +413,19 @@ Typowe sygnatury: - brak / niedostępność narzędzia przeglądarki przy `browser.enabled=true` → `plugins.allow` wyklucza `browser`, więc plugin nigdy się nie załadował. - `Failed to start Chrome CDP on port` → proces przeglądarki nie uruchomił się. - `browser.executablePath not found` → skonfigurowana ścieżka jest nieprawidłowa. -- `browser.cdpUrl must be http(s) or ws(s)` → skonfigurowany URL CDP używa nieobsługiwanego schematu, takiego jak `file:` lub `ftp:`. -- `browser.cdpUrl has invalid port` → skonfigurowany URL CDP ma błędny lub spoza zakresu port. +- `browser.cdpUrl must be http(s) or ws(s)` → skonfigurowany adres URL CDP używa nieobsługiwanego schematu, takiego jak `file:` lub `ftp:`. +- `browser.cdpUrl has invalid port` → skonfigurowany adres URL CDP ma nieprawidłowy lub wykraczający poza zakres port. - `No Chrome tabs found for profile="user"` → profil dołączania Chrome MCP nie ma otwartych lokalnych kart Chrome. -- `Remote CDP for profile "" is not reachable` → skonfigurowany zdalny endpoint CDP jest nieosiągalny z hosta gateway. -- `Browser attachOnly is enabled ... not reachable` lub `Browser attachOnly is enabled and CDP websocket ... is not reachable` → profil tylko-do-dołączenia nie ma osiągalnego celu albo endpoint HTTP odpowiedział, ale nadal nie udało się otworzyć WebSocket CDP. -- `Playwright is not available in this gateway build; '' is unsupported.` → bieżąca instalacja gateway nie zawiera pełnego pakietu Playwright; migawki ARIA i podstawowe zrzuty ekranu strony nadal mogą działać, ale nawigacja, migawki AI, zrzuty ekranu elementów według selektorów CSS i eksport PDF pozostają niedostępne. -- `fullPage is not supported for element screenshots` → żądanie zrzutu ekranu połączyło `--full-page` z `--ref` lub `--element`. +- `Remote CDP for profile "" is not reachable` → skonfigurowany zdalny punkt końcowy CDP nie jest osiągalny z hosta gateway. +- `Browser attachOnly is enabled ... not reachable` lub `Browser attachOnly is enabled and CDP websocket ... is not reachable` → profil tylko dołączania nie ma osiągalnego celu albo punkt końcowy HTTP odpowiedział, ale nadal nie udało się otworzyć gniazda WebSocket CDP. +- `Playwright is not available in this gateway build; '' is unsupported.` → bieżąca instalacja gateway nie zawiera pełnego pakietu Playwright; migawki ARIA i podstawowe zrzuty ekranu strony nadal mogą działać, ale nawigacja, migawki AI, zrzuty elementów według selektora CSS i eksport PDF pozostają niedostępne. +- `fullPage is not supported for element screenshots` → żądanie zrzutu ekranu łączyło `--full-page` z `--ref` lub `--element`. - `element screenshots are not supported for existing-session profiles; use ref from snapshot.` → wywołania zrzutów ekranu Chrome MCP / `existing-session` muszą używać przechwycenia strony albo `--ref` z migawki, a nie CSS `--element`. -- `existing-session file uploads do not support element selectors; use ref/inputRef.` → hooki przesyłania plików Chrome MCP wymagają odwołań do migawek, a nie selektorów CSS. -- `existing-session file uploads currently support one file at a time.` → w profilach Chrome MCP wysyłaj jedno przesłanie na wywołanie. -- `existing-session dialog handling does not support timeoutMs.` → hooki dialogów w profilach Chrome MCP nie obsługują nadpisania timeoutów. +- `existing-session file uploads do not support element selectors; use ref/inputRef.` → haki przesyłania plików Chrome MCP wymagają odwołań do migawek, a nie selektorów CSS. +- `existing-session file uploads currently support one file at a time.` → wysyłaj po jednym przesłaniu na wywołanie w profilach Chrome MCP. +- `existing-session dialog handling does not support timeoutMs.` → haki okien dialogowych w profilach Chrome MCP nie obsługują nadpisywania limitu czasu. - `response body is not supported for existing-session profiles yet.` → `responsebody` nadal wymaga zarządzanej przeglądarki albo surowego profilu CDP. -- nieaktualne nadpisania viewport / dark-mode / locale / offline w profilach tylko-do-dołączenia lub zdalnego CDP → uruchom `openclaw browser stop --browser-profile `, aby zamknąć aktywną sesję sterowania i zwolnić stan emulacji Playwright/CDP bez restartowania całego gateway. +- nieaktualne nadpisania viewportu / trybu ciemnego / ustawień regionalnych / trybu offline w profilach tylko dołączania lub zdalnych CDP → uruchom `openclaw browser stop --browser-profile `, aby zamknąć aktywną sesję sterowania i zwolnić stan emulacji Playwright/CDP bez restartowania całego gateway. Powiązane: @@ -383,9 +434,9 @@ Powiązane: ## Jeśli po aktualizacji coś nagle przestało działać -Większość problemów po aktualizacji wynika z rozjazdu konfiguracji albo z bardziej rygorystycznie egzekwowanych wartości domyślnych. +Większość problemów po aktualizacji to dryf konfiguracji albo egzekwowanie bardziej rygorystycznych ustawień domyślnych. -### 1) Zmieniło się zachowanie auth i nadpisywania URL +### 1) Zmieniło się zachowanie uwierzytelniania i nadpisywania URL ```bash openclaw gateway status @@ -396,15 +447,15 @@ openclaw config get gateway.auth.mode Co sprawdzić: -- Jeśli `gateway.mode=remote`, wywołania CLI mogą trafiać zdalnie, mimo że lokalna usługa działa poprawnie. +- Jeśli `gateway.mode=remote`, wywołania CLI mogą trafiać do zdalnego celu, podczas gdy lokalna usługa działa poprawnie. - Jawne wywołania `--url` nie wracają do zapisanych poświadczeń. Typowe sygnatury: - `gateway connect failed:` → nieprawidłowy docelowy URL. -- `unauthorized` → endpoint jest osiągalny, ale auth jest błędne. +- `unauthorized` → punkt końcowy jest osiągalny, ale uwierzytelnianie jest błędne. -### 2) Guardraile bind i auth są bardziej rygorystyczne +### 2) Ograniczenia dotyczące powiązań i uwierzytelniania są bardziej rygorystyczne ```bash openclaw config get gateway.bind @@ -416,13 +467,13 @@ openclaw logs --follow Co sprawdzić: -- Powiązania inne niż loopback (`lan`, `tailnet`, `custom`) wymagają prawidłowej ścieżki auth gateway: współdzielonego auth tokenem/hasłem albo poprawnie skonfigurowanego wdrożenia `trusted-proxy` bez loopback. +- Powiązania inne niż loopback (`lan`, `tailnet`, `custom`) wymagają prawidłowej ścieżki uwierzytelniania gateway: współdzielonego tokena/hasła albo poprawnie skonfigurowanego wdrożenia `trusted-proxy` bez loopback. - Stare klucze, takie jak `gateway.token`, nie zastępują `gateway.auth.token`. Typowe sygnatury: -- `refusing to bind gateway ... without auth` → powiązanie inne niż loopback bez prawidłowej ścieżki auth gateway. -- `RPC probe: failed` mimo że runtime działa → gateway działa, ale jest niedostępny przy bieżącym auth/url. +- `refusing to bind gateway ... without auth` → powiązanie inne niż loopback bez prawidłowej ścieżki uwierzytelniania gateway. +- `RPC probe: failed` przy działającym runtime → gateway działa, ale jest niedostępny przy bieżącym auth/url. ### 3) Zmienił się stan parowania i tożsamości urządzenia @@ -435,15 +486,15 @@ openclaw doctor Co sprawdzić: -- Oczekujące zatwierdzenia urządzeń dla dashboard/węzłów. -- Oczekujące zatwierdzenia parowania DM po zmianach zasad lub tożsamości. +- Oczekujące zatwierdzenia urządzeń dla dashboardu/węzłów. +- Oczekujące zatwierdzenia parowania DM po zmianach polityki lub tożsamości. Typowe sygnatury: -- `device identity required` → auth urządzenia nie jest spełnione. +- `device identity required` → uwierzytelnienie urządzenia nie zostało spełnione. - `pairing required` → nadawca/urządzenie musi zostać zatwierdzone. -Jeśli po sprawdzeniu konfiguracja usługi i runtime nadal się nie zgadzają, zainstaluj ponownie metadane usługi z tego samego katalogu profilu/stanu: +Jeśli po sprawdzeniach konfiguracja usługi i runtime nadal się różnią, zainstaluj ponownie metadane usługi z tego samego katalogu profilu/stanu: ```bash openclaw gateway install --force diff --git a/docs/pl/help/faq.md b/docs/pl/help/faq.md index a43cd9ae5..b170cf801 100644 --- a/docs/pl/help/faq.md +++ b/docs/pl/help/faq.md @@ -2,38 +2,38 @@ read_when: - Odpowiadasz na typowe pytania dotyczące konfiguracji, instalacji, onboardingu lub wsparcia środowiska uruchomieniowego - Triagujesz problemy zgłaszane przez użytkowników przed głębszym debugowaniem -summary: Najczęściej zadawane pytania dotyczące konfiguracji, ustawiania i używania OpenClaw +summary: Często zadawane pytania dotyczące konfiguracji, ustawień i używania OpenClaw title: FAQ x-i18n: - generated_at: "2026-04-07T09:51:45Z" + generated_at: "2026-04-08T02:21:00Z" model: gpt-5.4 provider: openai - source_hash: b2ad2fc35fb5b1d6c8fb75e7c0c409089dff033a9810c863c3f7ef64834a9b77 + source_hash: 001b4605966b45b08108606f76ae937ec348c2179b04cf6fb34fef94833705e6 source_path: help/faq.md workflow: 15 --- # FAQ -Szybkie odpowiedzi oraz bardziej szczegółowe rozwiązywanie problemów dla rzeczywistych konfiguracji (lokalny development, VPS, multi-agent, OAuth/klucze API, failover modeli). Diagnostykę runtime znajdziesz w [Troubleshooting](/pl/gateway/troubleshooting). Pełne odniesienie do konfiguracji znajdziesz w [Configuration](/pl/gateway/configuration). +Szybkie odpowiedzi oraz głębsze wskazówki dotyczące rozwiązywania problemów dla rzeczywistych konfiguracji (lokalny development, VPS, wiele agentów, OAuth/klucze API, failover modeli). W przypadku diagnostyki środowiska uruchomieniowego zobacz [Rozwiązywanie problemów](/pl/gateway/troubleshooting). Pełny opis konfiguracji znajdziesz w [Konfiguracji](/pl/gateway/configuration). -## Pierwsze 60 sekund, jeśli coś jest zepsute +## Pierwsze 60 sekund, jeśli coś nie działa -1. **Szybki status (pierwsze sprawdzenie)** +1. **Szybki status (pierwsza kontrola)** ```bash openclaw status ``` - Szybkie lokalne podsumowanie: OS + aktualizacja, dostępność gateway/usługi, agenci/sesje, konfiguracja dostawcy + problemy runtime (gdy gateway jest osiągalny). + Szybkie lokalne podsumowanie: system operacyjny + aktualizacja, dostępność gatewaya/usługi, agenci/sesje, konfiguracja providera + problemy środowiska uruchomieniowego (gdy gateway jest osiągalny). -2. **Raport gotowy do wklejenia (bezpieczny do udostępnienia)** +2. **Raport do wklejenia (bezpieczny do udostępnienia)** ```bash openclaw status --all ``` - Diagnostyka tylko do odczytu z ogonem logów (tokeny są zamaskowane). + Diagnostyka tylko do odczytu z końcówką logu (tokeny zredagowane). 3. **Stan demona + portu** @@ -41,7 +41,7 @@ Szybkie odpowiedzi oraz bardziej szczegółowe rozwiązywanie problemów dla rze openclaw gateway status ``` - Pokazuje runtime nadzorcy względem dostępności RPC, docelowy URL sondy oraz której konfiguracji usługa prawdopodobnie użyła. + Pokazuje środowisko uruchomieniowe supervisora względem osiągalności RPC, docelowy adres URL sondy oraz której konfiguracji usługa prawdopodobnie użyła. 4. **Głębokie sondy** @@ -49,22 +49,22 @@ Szybkie odpowiedzi oraz bardziej szczegółowe rozwiązywanie problemów dla rze openclaw status --deep ``` - Uruchamia aktywną sondę stanu gateway, w tym sondy kanałów, gdy są obsługiwane - (wymaga osiągalnego gateway). Zobacz [Health](/pl/gateway/health). + Uruchamia aktywną sondę kondycji gatewaya, w tym sondy kanałów tam, gdzie są obsługiwane + (wymaga osiągalnego gatewaya). Zobacz [Kondycja](/pl/gateway/health). -5. **Podgląd najnowszego logu** +5. **Podejrzyj najnowszy log** ```bash openclaw logs --follow ``` - Jeśli RPC nie działa, przełącz się na: + Jeśli RPC nie działa, użyj zamiast tego: ```bash tail -f "$(ls -t /tmp/openclaw/openclaw-*.log | head -1)" ``` - Logi plikowe są oddzielne od logów usługi; zobacz [Logging](/pl/logging) i [Troubleshooting](/pl/gateway/troubleshooting). + Logi plikowe są oddzielone od logów usługi; zobacz [Logowanie](/pl/logging) i [Rozwiązywanie problemów](/pl/gateway/troubleshooting). 6. **Uruchom Doctor (naprawy)** @@ -72,48 +72,48 @@ Szybkie odpowiedzi oraz bardziej szczegółowe rozwiązywanie problemów dla rze openclaw doctor ``` - Naprawia/migruje config i stan + uruchamia kontrole zdrowia. Zobacz [Doctor](/pl/gateway/doctor). + Naprawia/migruje konfigurację i stan + uruchamia kontrole kondycji. Zobacz [Doctor](/pl/gateway/doctor). -7. **Migawka gateway** +7. **Migawka gatewaya** ```bash openclaw health --json - openclaw health --verbose # pokazuje docelowy URL + ścieżkę configu przy błędach + openclaw health --verbose # pokazuje docelowy URL + ścieżkę konfiguracji przy błędach ``` - Pyta działający gateway o pełną migawkę (tylko WS). Zobacz [Health](/pl/gateway/health). + Prosi uruchomiony gateway o pełną migawkę (tylko WS). Zobacz [Kondycja](/pl/gateway/health). ## Szybki start i konfiguracja przy pierwszym uruchomieniu - - Użyj lokalnego agenta AI, który może **widzieć Twoją maszynę**. To jest znacznie skuteczniejsze niż pytanie - na Discordzie, ponieważ większość przypadków „utknąłem” to **lokalne problemy z configiem lub środowiskiem**, + + Użyj lokalnego agenta AI, który potrafi **widzieć Twój komputer**. To jest znacznie skuteczniejsze niż pytanie + na Discordzie, ponieważ większość przypadków typu „utknąłem” to **lokalne problemy z konfiguracją lub środowiskiem**, których zdalni pomocnicy nie mogą sprawdzić. - **Claude Code**: [https://www.anthropic.com/claude-code/](https://www.anthropic.com/claude-code/) - **OpenAI Codex**: [https://openai.com/codex/](https://openai.com/codex/) - Te narzędzia mogą czytać repo, uruchamiać polecenia, sprawdzać logi i pomagać naprawić konfigurację - na poziomie maszyny (PATH, usługi, uprawnienia, pliki auth). Daj im **pełne checkout źródeł** przez - instalację hackable (git): + Te narzędzia mogą odczytać repozytorium, uruchamiać polecenia, sprawdzać logi i pomagać naprawić konfigurację + na poziomie maszyny (PATH, usługi, uprawnienia, pliki uwierzytelniania). Przekaż im **pełne checkout źródeł** + przez instalację hackowalną (git): ```bash curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git ``` - To instaluje OpenClaw **z checkoutu git**, dzięki czemu agent może czytać kod + dokumentację - i analizować dokładnie tę wersję, której używasz. Zawsze możesz później wrócić do stable, + To instaluje OpenClaw **z checkoutu git**, dzięki czemu agent może czytać kod + dokumentację i + analizować dokładnie tę wersję, której używasz. Zawsze możesz później wrócić do wersji stable, uruchamiając instalator ponownie bez `--install-method git`. - Wskazówka: poproś agenta, aby **zaplanował i nadzorował** naprawę (krok po kroku), a potem wykonał tylko - potrzebne polecenia. Dzięki temu zmiany pozostają małe i łatwiejsze do przejrzenia. + Wskazówka: poproś agenta, aby **zaplanował i nadzorował** naprawę (krok po kroku), a następnie wykonał tylko + niezbędne polecenia. Dzięki temu zmiany są mniejsze i łatwiejsze do audytu. - Jeśli odkryjesz rzeczywisty błąd lub poprawkę, zgłoś issue na GitHubie albo wyślij PR: + Jeśli odkryjesz prawdziwy błąd lub poprawkę, zgłoś issue na GitHubie albo wyślij PR: [https://github.com/openclaw/openclaw/issues](https://github.com/openclaw/openclaw/issues) [https://github.com/openclaw/openclaw/pulls](https://github.com/openclaw/openclaw/pulls) - Zacznij od tych poleceń (udostępnij wyniki, gdy prosisz o pomoc): + Zacznij od tych poleceń (udostępnij ich wyniki, gdy prosisz o pomoc): ```bash openclaw status @@ -123,30 +123,30 @@ Szybkie odpowiedzi oraz bardziej szczegółowe rozwiązywanie problemów dla rze Co robią: - - `openclaw status`: szybka migawka zdrowia gateway/agenta + podstawowy config. - - `openclaw models status`: sprawdza auth dostawcy + dostępność modeli. - - `openclaw doctor`: weryfikuje i naprawia typowe problemy z configiem/stanem. + - `openclaw status`: szybka migawka kondycji gatewaya/agenta + podstawowej konfiguracji. + - `openclaw models status`: sprawdza uwierzytelnienie providera + dostępność modeli. + - `openclaw doctor`: sprawdza poprawność i naprawia typowe problemy z konfiguracją/stanem. - Inne przydatne kontrole CLI: `openclaw status --all`, `openclaw logs --follow`, + Inne przydatne kontrole w CLI: `openclaw status --all`, `openclaw logs --follow`, `openclaw gateway status`, `openclaw health --verbose`. - Szybka pętla debugowania: [Pierwsze 60 sekund, jeśli coś jest zepsute](#pierwsze-60-sekund-jesli-cos-jest-zepsute). - Dokumentacja instalacji: [Install](/pl/install), [Flagi instalatora](/pl/install/installer), [Updating](/pl/install/updating). + Szybka pętla debugowania: [Pierwsze 60 sekund, jeśli coś nie działa](#pierwsze-60-sekund-jeśli-coś-nie-działa). + Dokumentacja instalacji: [Instalacja](/pl/install), [Flagi instalatora](/pl/install/installer), [Aktualizacja](/pl/install/updating). - Typowe powody pominięcia heartbeat: + Typowe powody pomijania heartbeat: - - `quiet-hours`: poza skonfigurowanym oknem active-hours - - `empty-heartbeat-file`: `HEARTBEAT.md` istnieje, ale zawiera tylko pusty/szkieletowy nagłówek - - `no-tasks-due`: tryb zadań `HEARTBEAT.md` jest aktywny, ale żaden z interwałów zadań jeszcze nie nadszedł + - `quiet-hours`: poza skonfigurowanym oknem aktywnych godzin + - `empty-heartbeat-file`: `HEARTBEAT.md` istnieje, ale zawiera tylko pustą strukturę/nagłówki + - `no-tasks-due`: tryb zadań `HEARTBEAT.md` jest aktywny, ale żaden interwał zadania nie jest jeszcze należny - `alerts-disabled`: cała widoczność heartbeat jest wyłączona (`showOk`, `showAlerts` i `useIndicator` są wyłączone) - W trybie zadań znaczniki czasu wykonania są przesuwane dopiero po zakończeniu rzeczywistego uruchomienia heartbeat. - Pominięte uruchomienia nie oznaczają zadań jako ukończonych. + W trybie zadań znaczniki czasu należności są przesuwane dopiero po zakończeniu + rzeczywistego uruchomienia heartbeat. Pominięte uruchomienia nie oznaczają zadań jako wykonanych. - Dokumentacja: [Heartbeat](/pl/gateway/heartbeat), [Automation & Tasks](/pl/automation). + Dokumentacja: [Heartbeat](/pl/gateway/heartbeat), [Automatyzacja i zadania](/pl/automation). @@ -158,7 +158,7 @@ Szybkie odpowiedzi oraz bardziej szczegółowe rozwiązywanie problemów dla rze openclaw onboard --install-daemon ``` - Kreator może też automatycznie zbudować zasoby UI. Po onboardingu zazwyczaj uruchamiasz Gateway na porcie **18789**. + Kreator może także automatycznie zbudować zasoby UI. Po onboardingu zwykle uruchamiasz Gateway na porcie **18789**. Ze źródeł (współtwórcy/dev): @@ -176,85 +176,85 @@ Szybkie odpowiedzi oraz bardziej szczegółowe rozwiązywanie problemów dla rze - Kreator otwiera przeglądarkę z czystym adresem dashboardu (bez tokenu) zaraz po onboardingu i wypisuje też link w podsumowaniu. Zostaw tę kartę otwartą; jeśli się nie uruchomiła, skopiuj/wklej wypisany URL na tej samej maszynie. + Kreator otwiera przeglądarkę z czystym (bez tokenu w URL) adresem dashboardu zaraz po onboardingu i wypisuje także link w podsumowaniu. Zachowaj tę kartę otwartą; jeśli się nie uruchomiła, skopiuj/wklej wypisany URL na tej samej maszynie. **Localhost (ta sama maszyna):** - Otwórz `http://127.0.0.1:18789/`. - - Jeśli prosi o auth ze wspólnym sekretem, wklej skonfigurowany token lub hasło w ustawieniach Control UI. + - Jeśli pojawi się prośba o uwierzytelnienie wspólnym sekretem, wklej skonfigurowany token lub hasło w ustawieniach Control UI. - Źródło tokenu: `gateway.auth.token` (lub `OPENCLAW_GATEWAY_TOKEN`). - Źródło hasła: `gateway.auth.password` (lub `OPENCLAW_GATEWAY_PASSWORD`). - - Jeśli wspólny sekret nie jest jeszcze skonfigurowany, wygeneruj token przez `openclaw doctor --generate-gateway-token`. + - Jeśli wspólny sekret nie jest jeszcze skonfigurowany, wygeneruj token poleceniem `openclaw doctor --generate-gateway-token`. - **Nie na localhost:** + **Poza localhost:** - - **Tailscale Serve** (zalecane): zostaw bind loopback, uruchom `openclaw gateway --tailscale serve`, otwórz `https:///`. Jeśli `gateway.auth.allowTailscale` ma wartość `true`, nagłówki tożsamości spełniają wymagania auth dla Control UI/WebSocket (bez wklejania wspólnego sekretu, zakłada zaufanego hosta gateway); HTTP API nadal wymagają auth ze wspólnym sekretem, chyba że celowo używasz private-ingress `none` lub trusted-proxy HTTP auth. - Nieudane równoczesne próby auth Serve z tego samego klienta są serializowane, zanim ogranicznik failed-auth je zarejestruje, więc druga zła próba może już pokazać `retry later`. - - **Bind tailnet**: uruchom `openclaw gateway --bind tailnet --token ""` (lub skonfiguruj auth hasłem), otwórz `http://:18789/`, a następnie wklej pasujący wspólny sekret w ustawieniach dashboardu. - - **Identity-aware reverse proxy**: pozostaw Gateway za trusted proxy bez loopback, skonfiguruj `gateway.auth.mode: "trusted-proxy"`, a następnie otwórz URL proxy. - - **Tunel SSH**: `ssh -N -L 18789:127.0.0.1:18789 user@host`, a następnie otwórz `http://127.0.0.1:18789/`. Auth ze wspólnym sekretem nadal obowiązuje przez tunel; wklej skonfigurowany token lub hasło, jeśli pojawi się monit. + - **Tailscale Serve** (zalecane): pozostaw bindowanie loopback, uruchom `openclaw gateway --tailscale serve`, otwórz `https:///`. Jeśli `gateway.auth.allowTailscale` ma wartość `true`, nagłówki tożsamości spełniają wymagania uwierzytelniania Control UI/WebSocket (bez wklejania wspólnego sekretu, przy założeniu zaufanego hosta gatewaya); interfejsy HTTP API nadal wymagają uwierzytelnienia wspólnym sekretem, chyba że celowo używasz prywatnego ingress `none` albo uwierzytelnienia HTTP przez zaufane proxy. + Nieudane równoległe próby uwierzytelnienia Serve z tego samego klienta są serializowane, zanim ogranicznik nieudanego uwierzytelnienia je zarejestruje, więc druga błędna próba może już pokazać `retry later`. + - **Tailnet bind**: uruchom `openclaw gateway --bind tailnet --token ""` (albo skonfiguruj uwierzytelnianie hasłem), otwórz `http://:18789/`, a następnie wklej pasujący wspólny sekret w ustawieniach dashboardu. + - **Reverse proxy świadome tożsamości**: trzymaj Gateway za zaufanym proxy non-loopback, skonfiguruj `gateway.auth.mode: "trusted-proxy"`, a następnie otwórz URL proxy. + - **Tunel SSH**: `ssh -N -L 18789:127.0.0.1:18789 user@host`, a następnie otwórz `http://127.0.0.1:18789/`. Uwierzytelnianie wspólnym sekretem nadal obowiązuje przez tunel; jeśli pojawi się monit, wklej skonfigurowany token lub hasło. - Zobacz [Dashboard](/web/dashboard) i [Web surfaces](/web), aby poznać tryby bind i szczegóły auth. + Zobacz [Dashboard](/web/dashboard) i [Powierzchnie webowe](/web), aby poznać tryby bindowania i szczegóły uwierzytelniania. - + Sterują różnymi warstwami: - - `approvals.exec`: przekazuje prompty zatwierdzeń do miejsc docelowych na czacie - - `channels..execApprovals`: sprawia, że dany kanał działa jako natywny klient zatwierdzeń dla zatwierdzeń exec + - `approvals.exec`: przekazuje prompty zatwierdzania do miejsc docelowych czatu + - `channels..execApprovals`: sprawia, że ten kanał działa jako natywny klient zatwierdzania dla zatwierdzeń exec - Polityka host exec nadal jest rzeczywistą bramką zatwierdzania. Konfiguracja czatu steruje tylko tym, - gdzie pojawiają się prompty zatwierdzeń i jak ludzie mogą na nie odpowiadać. + Zasada exec hosta nadal pozostaje faktyczną bramką zatwierdzania. Konfiguracja czatu steruje tylko tym, + gdzie pojawiają się prompty zatwierdzania i jak ludzie mogą na nie odpowiadać. W większości konfiguracji **nie** potrzebujesz obu: - - Jeśli czat już obsługuje polecenia i odpowiedzi, `/approve` w tym samym czacie działa przez ścieżkę współdzieloną. - - Jeśli obsługiwany kanał natywny może bezpiecznie wywnioskować zatwierdzających, OpenClaw teraz automatycznie włącza natywne zatwierdzenia DM-first, gdy `channels..execApprovals.enabled` nie jest ustawione lub ma wartość `"auto"`. - - Gdy dostępne są natywne karty/przyciski zatwierdzeń, ta natywna ścieżka UI jest podstawowa; agent powinien dołączać ręczne polecenie `/approve` tylko wtedy, gdy wynik narzędzia mówi, że zatwierdzenia na czacie są niedostępne lub ręczne zatwierdzenie jest jedyną ścieżką. - - Użyj `approvals.exec` tylko wtedy, gdy prompty mają być też przekazywane do innych czatów lub jawnych pokoi ops. - - Użyj `channels..execApprovals.target: "channel"` lub `"both"` tylko wtedy, gdy jawnie chcesz, by prompty zatwierdzeń były publikowane z powrotem w pokoju/wątku źródłowym. - - Zatwierdzenia pluginów są znów oddzielne: domyślnie używają `/approve` w tym samym czacie, opcjonalnego przekazywania `approvals.plugin`, a tylko niektóre kanały natywne zachowują dodatkowo natywną obsługę plugin approvals. + - Jeśli czat już obsługuje polecenia i odpowiedzi, `/approve` w tym samym czacie działa przez współdzieloną ścieżkę. + - Jeśli obsługiwany kanał natywny potrafi bezpiecznie wywnioskować osoby zatwierdzające, OpenClaw teraz automatycznie włącza natywne zatwierdzenia DM-first, gdy `channels..execApprovals.enabled` jest nieustawione albo ma wartość `"auto"`. + - Gdy dostępne są natywne karty/przyciski zatwierdzania, to właśnie natywny interfejs jest główną ścieżką; agent powinien dołączać ręczne polecenie `/approve` tylko wtedy, gdy wynik narzędzia mówi, że zatwierdzenia na czacie są niedostępne albo ręczne zatwierdzenie jest jedyną drogą. + - Używaj `approvals.exec` tylko wtedy, gdy prompty muszą być także przekazywane do innych czatów lub wyraźnie wskazanych pokoi operacyjnych. + - Używaj `channels..execApprovals.target: "channel"` lub `"both"` tylko wtedy, gdy wyraźnie chcesz publikować prompty zatwierdzenia z powrotem do pokoju/wątku źródłowego. + - Zatwierdzenia pluginów są znowu oddzielne: domyślnie używają `/approve` w tym samym czacie, opcjonalnego przekazywania `approvals.plugin`, a tylko niektóre kanały natywne zachowują dodatkową obsługę plugin-approval-native. - W skrócie: forwarding służy do routingu, a konfiguracja natywnego klienta do bogatszego UX specyficznego dla kanału. - Zobacz [Exec Approvals](/pl/tools/exec-approvals). + W skrócie: przekazywanie służy do routingu, a konfiguracja natywnego klienta służy do bogatszego UX specyficznego dla kanału. + Zobacz [Zatwierdzenia exec](/pl/tools/exec-approvals). - - Wymagany jest Node **>= 22**. Zalecany jest `pnpm`. Bun **nie jest zalecany** dla Gateway. + + Wymagany jest Node **>= 22**. Zalecany jest `pnpm`. Bun **nie jest zalecany** dla Gatewaya. - - Tak. Gateway jest lekki — dokumentacja podaje, że do użytku osobistego wystarcza **512MB-1GB RAM**, **1 rdzeń** i około **500MB** - miejsca na dysku, oraz zaznacza, że **Raspberry Pi 4 może go uruchomić**. + + Tak. Gateway jest lekki — dokumentacja podaje, że do użytku osobistego wystarczy **512 MB-1 GB RAM**, **1 rdzeń** i około **500 MB** + miejsca na dysku, i zaznacza, że **Raspberry Pi 4 może go uruchomić**. - Jeśli chcesz mieć większy zapas (logi, media, inne usługi), zalecane jest **2GB**, + Jeśli chcesz trochę większy zapas (logi, media, inne usługi), **zalecane jest 2 GB**, ale nie jest to twarde minimum. - Wskazówka: mały Pi/VPS może hostować Gateway, a Ty możesz sparować **nodes** na laptopie/telefonie, - aby mieć lokalny ekran/kamerę/canvas lub wykonywanie poleceń. Zobacz [Nodes](/pl/nodes). + Wskazówka: mały Pi/VPS może hostować Gateway, a Ty możesz sparować **nodes** na laptopie/telefonie dla + lokalnego ekranu/kamery/canvas albo wykonywania poleceń. Zobacz [Nodes](/pl/nodes). - - Krótko: działa, ale spodziewaj się pewnych niedoskonałości. + + Krótka odpowiedź: działa, ale spodziewaj się ostrych krawędzi. - Używaj systemu **64-bitowego** i utrzymuj Node >= 22. - - Preferuj **instalację hackable (git)**, aby móc widzieć logi i szybko aktualizować. - - Zacznij bez kanałów/Skills, a potem dodawaj je po kolei. + - Preferuj **instalację hackowalną (git)**, aby móc oglądać logi i szybko aktualizować. + - Zacznij bez kanałów/Skills, a potem dodawaj je jeden po drugim. - Jeśli trafisz na dziwne problemy binarne, zwykle jest to problem **zgodności z ARM**. - Dokumentacja: [Linux](/pl/platforms/linux), [Install](/pl/install). + Dokumentacja: [Linux](/pl/platforms/linux), [Instalacja](/pl/install). - - Ten ekran zależy od tego, czy Gateway jest osiągalny i uwierzytelniony. TUI automatycznie wysyła też - „Wake up, my friend!” przy pierwszym hatch. Jeśli widzisz ten wiersz **bez odpowiedzi** - i tokeny pozostają na 0, agent nigdy się nie uruchomił. + + Ten ekran zależy od tego, czy Gateway jest osiągalny i uwierzytelniony. TUI wysyła też + „Wake up, my friend!” automatycznie przy pierwszym hatch. Jeśli widzisz tę linię i **brak odpowiedzi**, + a liczba tokenów pozostaje 0, agent nigdy się nie uruchomił. 1. Zrestartuj Gateway: @@ -262,7 +262,7 @@ Szybkie odpowiedzi oraz bardziej szczegółowe rozwiązywanie problemów dla rze openclaw gateway restart ``` - 2. Sprawdź status + auth: + 2. Sprawdź status + uwierzytelnienie: ```bash openclaw status @@ -270,67 +270,67 @@ Szybkie odpowiedzi oraz bardziej szczegółowe rozwiązywanie problemów dla rze openclaw logs --follow ``` - 3. Jeśli nadal wisi, uruchom: + 3. Jeśli nadal się zawiesza, uruchom: ```bash openclaw doctor ``` Jeśli Gateway jest zdalny, upewnij się, że tunel/połączenie Tailscale działa i że UI - wskazuje właściwy Gateway. Zobacz [Remote access](/pl/gateway/remote). + wskazuje właściwy Gateway. Zobacz [Dostęp zdalny](/pl/gateway/remote). - - Tak. Skopiuj **katalog stanu** i **workspace**, a następnie uruchom Doctor raz. To - zachowa Twojego bota „dokładnie takiego samego” (pamięć, historię sesji, auth i stan - kanałów), o ile skopiujesz **obie** lokalizacje: + + Tak. Skopiuj **katalog stanu** i **workspace**, a następnie uruchom raz Doctor. To + zachowuje bota „dokładnie takim samym” (pamięć, historia sesji, uwierzytelnienie i + stan kanałów), o ile skopiujesz **obie** lokalizacje: 1. Zainstaluj OpenClaw na nowej maszynie. 2. Skopiuj `$OPENCLAW_STATE_DIR` (domyślnie: `~/.openclaw`) ze starej maszyny. - 3. Skopiuj swój workspace (domyślnie: `~/.openclaw/workspace`). + 3. Skopiuj workspace (domyślnie: `~/.openclaw/workspace`). 4. Uruchom `openclaw doctor` i zrestartuj usługę Gateway. - To zachowuje config, profile auth, poświadczenia WhatsApp, sesje i pamięć. Jeśli używasz - trybu zdalnego, pamiętaj, że host gateway jest właścicielem magazynu sesji i workspace. + To zachowuje konfigurację, profile uwierzytelniania, dane uwierzytelniające WhatsApp, sesje i pamięć. Jeśli działasz w + trybie zdalnym, pamiętaj, że host gatewaya jest właścicielem magazynu sesji i workspace. - **Ważne:** jeśli tylko commitujesz/pushujesz swój workspace do GitHuba, tworzysz kopię - zapasową **pamięci + plików bootstrap**, ale **nie** historii sesji ani auth. One znajdują się - w `~/.openclaw/` (na przykład `~/.openclaw/agents//sessions/`). + **Ważne:** jeśli tylko commitujesz/pushujesz workspace do GitHuba, tworzysz kopię zapasową + **pamięci + plików bootstrap**, ale **nie** historii sesji ani uwierzytelnienia. To znajduje się + pod `~/.openclaw/` (na przykład `~/.openclaw/agents//sessions/`). - Powiązane: [Migrating](/pl/install/migrating), [Gdzie rzeczy znajdują się na dysku](#gdzie-rzeczy-znajduja-sie-na-dysku), - [Agent workspace](/pl/concepts/agent-workspace), [Doctor](/pl/gateway/doctor), - [Remote mode](/pl/gateway/remote). + Powiązane: [Migracja](/pl/install/migrating), [Gdzie rzeczy znajdują się na dysku](#gdzie-rzeczy-znajdują-się-na-dysku), + [Workspace agenta](/pl/concepts/agent-workspace), [Doctor](/pl/gateway/doctor), + [Tryb zdalny](/pl/gateway/remote). - + Sprawdź changelog na GitHubie: [https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md](https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md) - Najnowsze wpisy są na górze. Jeśli najwyższa sekcja jest oznaczona jako **Unreleased**, następna datowana - sekcja to najnowsza wydana wersja. Wpisy są pogrupowane jako **Highlights**, **Changes** i - **Fixes** (oraz w razie potrzeby sekcje docs/inne). + Najnowsze wpisy są na górze. Jeśli górna sekcja jest oznaczona jako **Unreleased**, następna sekcja z datą + jest najnowszą wydaną wersją. Wpisy są grupowane na **Highlights**, **Changes** i + **Fixes** (oraz sekcje docs/inne, jeśli są potrzebne). - + Niektóre połączenia Comcast/Xfinity błędnie blokują `docs.openclaw.ai` przez Xfinity - Advanced Security. Wyłącz ją albo dodaj `docs.openclaw.ai` do allowlist, a potem spróbuj ponownie. - Pomóż nam odblokować tę domenę, zgłaszając to tutaj: [https://spa.xfinity.com/check_url_status](https://spa.xfinity.com/check_url_status). + Advanced Security. Wyłącz to albo dodaj `docs.openclaw.ai` do allowlisty, a następnie spróbuj ponownie. + Pomóż nam to odblokować, zgłaszając tutaj: [https://spa.xfinity.com/check_url_status](https://spa.xfinity.com/check_url_status). - Jeśli nadal nie możesz otworzyć witryny, dokumentacja jest mirrorowana na GitHubie: + Jeśli nadal nie możesz dotrzeć do strony, dokumentacja jest mirrorowana na GitHubie: [https://github.com/openclaw/openclaw/tree/main/docs](https://github.com/openclaw/openclaw/tree/main/docs) - **Stable** i **beta** to **dist-tagi npm**, a nie oddzielne linie kodu: + **Stable** i **beta** to **npm dist-tags**, a nie osobne linie kodu: - `latest` = stable - - `beta` = wczesny build do testów + - `beta` = wczesna kompilacja do testów - Zwykle wydanie stable trafia najpierw na **beta**, a potem jawny + Zwykle wydanie stable trafia najpierw na **beta**, a następnie jawny krok promocji przenosi tę samą wersję do `latest`. Maintainerzy mogą też publikować bezpośrednio do `latest`, gdy jest to potrzebne. Dlatego beta i stable mogą wskazywać na **tę samą wersję** po promocji. @@ -338,13 +338,13 @@ Szybkie odpowiedzi oraz bardziej szczegółowe rozwiązywanie problemów dla rze Zobacz, co się zmieniło: [https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md](https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md) - Jednolinijkowce instalacyjne i różnicę między beta a dev znajdziesz w akordeonie poniżej. + Jednolinijkowe polecenia instalacji i różnicę między beta a dev znajdziesz w akordeonie poniżej. - **Beta** to dist-tag npm `beta` (może odpowiadać `latest` po promocji). - **Dev** to ruchoma głowa `main` (git); po publikacji używa dist-tagu npm `dev`. + **Beta** to npm dist-tag `beta` (może odpowiadać `latest` po promocji). + **Dev** to ruchoma głowa `main` (git); po publikacji używa npm dist-tag `dev`. Jednolinijkowce (macOS/Linux): @@ -359,12 +359,12 @@ Szybkie odpowiedzi oraz bardziej szczegółowe rozwiązywanie problemów dla rze Instalator Windows (PowerShell): [https://openclaw.ai/install.ps1](https://openclaw.ai/install.ps1) - Więcej szczegółów: [Development channels](/pl/install/development-channels) i [Flagi instalatora](/pl/install/installer). + Więcej szczegółów: [Kanały developerskie](/pl/install/development-channels) i [Flagi instalatora](/pl/install/installer). - Są dwie opcje: + Masz dwie opcje: 1. **Kanał dev (checkout git):** @@ -374,13 +374,13 @@ Szybkie odpowiedzi oraz bardziej szczegółowe rozwiązywanie problemów dla rze To przełącza na gałąź `main` i aktualizuje ze źródeł. - 2. **Instalacja hackable (ze strony instalatora):** + 2. **Instalacja hackowalna (ze strony instalatora):** ```bash curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git ``` - Dzięki temu dostajesz lokalne repo, które możesz edytować, a potem aktualizować przez git. + To daje Ci lokalne repozytorium, które możesz edytować, a następnie aktualizować przez git. Jeśli wolisz ręcznie wykonać czysty clone, użyj: @@ -391,19 +391,19 @@ Szybkie odpowiedzi oraz bardziej szczegółowe rozwiązywanie problemów dla rze pnpm build ``` - Dokumentacja: [Update](/cli/update), [Development channels](/pl/install/development-channels), - [Install](/pl/install). + Dokumentacja: [Aktualizacja](/cli/update), [Kanały developerskie](/pl/install/development-channels), + [Instalacja](/pl/install). - - Orientacyjnie: + + Przybliżony przewodnik: - **Instalacja:** 2-5 minut - - **Onboarding:** 5-15 minut, w zależności od liczby kanałów/modeli, które konfigurujesz + - **Onboarding:** 5-15 minut, zależnie od liczby konfigurowanych kanałów/modeli - Jeśli proces się zawiesza, użyj [Problem z instalatorem](#quick-start-and-first-run-setup) - oraz szybkiej pętli debugowania z [Utknąłem](#quick-start-and-first-run-setup). + Jeśli się zawiesza, użyj [Instalator utknął](#quick-start-and-first-run-setup) + i szybkiej pętli debugowania z [Utknąłem](#quick-start-and-first-run-setup). @@ -420,13 +420,13 @@ Szybkie odpowiedzi oraz bardziej szczegółowe rozwiązywanie problemów dla rze curl -fsSL https://openclaw.ai/install.sh | bash -s -- --beta --verbose ``` - Dla instalacji hackable (git): + Dla instalacji hackowalnej (git): ```bash curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git --verbose ``` - Odpowiednik w Windows (PowerShell): + Odpowiednik dla Windows (PowerShell): ```powershell # install.ps1 nie ma jeszcze dedykowanej flagi -Verbose. @@ -440,36 +440,36 @@ Szybkie odpowiedzi oraz bardziej szczegółowe rozwiązywanie problemów dla rze - Dwa typowe problemy w Windows: + Dwa częste problemy na Windows: **1) błąd npm spawn git / git not found** - - Zainstaluj **Git for Windows** i upewnij się, że `git` jest na Twoim PATH. - - Zamknij i ponownie otwórz PowerShell, a następnie uruchom instalator ponownie. + - Zainstaluj **Git for Windows** i upewnij się, że `git` jest w Twoim PATH. + - Zamknij i ponownie otwórz PowerShell, a potem ponownie uruchom instalator. **2) openclaw is not recognized po instalacji** - - Twój globalny katalog bin npm nie jest na PATH. + - Twój globalny katalog bin npm nie jest w PATH. - Sprawdź ścieżkę: ```powershell npm config get prefix ``` - - Dodaj ten katalog do swojego user PATH (na Windows nie potrzeba sufiksu `\bin`; w większości systemów jest to `%AppData%\npm`). - - Zamknij i ponownie otwórz PowerShell po zaktualizowaniu PATH. + - Dodaj ten katalog do PATH użytkownika (na Windows nie potrzebujesz sufiksu `\bin`; w większości systemów jest to `%AppData%\npm`). + - Zamknij i ponownie otwórz PowerShell po aktualizacji PATH. - Jeśli chcesz uzyskać możliwie najpłynniejszą konfigurację Windows, używaj **WSL2** zamiast natywnego Windows. + Jeśli chcesz możliwie najpłynniejszej konfiguracji na Windows, używaj **WSL2** zamiast natywnego Windows. Dokumentacja: [Windows](/pl/platforms/windows). - + Zwykle oznacza to niedopasowanie strony kodowej konsoli w natywnych powłokach Windows. Objawy: - - wynik `system.run`/`exec` renderuje chiński tekst jako mojibake + - wyjście `system.run`/`exec` renderuje chiński jako mojibake - to samo polecenie wygląda poprawnie w innym profilu terminala Szybkie obejście w PowerShell: @@ -481,72 +481,72 @@ Szybkie odpowiedzi oraz bardziej szczegółowe rozwiązywanie problemów dla rze $OutputEncoding = [System.Text.UTF8Encoding]::new($false) ``` - Następnie zrestartuj Gateway i spróbuj ponownie: + Następnie zrestartuj Gateway i ponów próbę polecenia: ```powershell openclaw gateway restart ``` - Jeśli nadal odtwarzasz ten problem na najnowszym OpenClaw, śledź/zgłoś go tutaj: + Jeśli nadal odtwarzasz ten problem w najnowszym OpenClaw, śledź/zgłoś go tutaj: - [Issue #30640](https://github.com/openclaw/openclaw/issues/30640) - - Użyj **instalacji hackable (git)**, aby mieć lokalnie pełne źródła i dokumentację, a potem zapytaj - swojego bota (lub Claude/Codex) _z tego folderu_, aby mógł czytać repo i odpowiedzieć precyzyjnie. + + Użyj **instalacji hackowalnej (git)**, aby mieć lokalnie pełne źródła i dokumentację, a następnie zapytaj + swojego bota (albo Claude/Codex) _z tego folderu_, aby mógł czytać repozytorium i odpowiedzieć precyzyjnie. ```bash curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git ``` - Więcej szczegółów: [Install](/pl/install) i [Flagi instalatora](/pl/install/installer). + Więcej szczegółów: [Instalacja](/pl/install) i [Flagi instalatora](/pl/install/installer). - Krótka odpowiedź: postępuj zgodnie z przewodnikiem dla Linuxa, a potem uruchom onboarding. + Krótka odpowiedź: postępuj zgodnie z przewodnikiem dla Linuksa, a następnie uruchom onboarding. - Szybka ścieżka Linux + instalacja usługi: [Linux](/pl/platforms/linux). - - Pełny przewodnik: [Getting Started](/pl/start/getting-started). - - Instalator + aktualizacje: [Install & updates](/pl/install/updating). + - Pełny przewodnik: [Pierwsze kroki](/pl/start/getting-started). + - Instalator + aktualizacje: [Instalacja i aktualizacje](/pl/install/updating). - Działa każdy VPS z Linuxem. Zainstaluj na serwerze, a potem użyj SSH/Tailscale, aby dostać się do Gateway. + Każdy VPS z Linuksem działa. Zainstaluj na serwerze, a następnie użyj SSH/Tailscale, aby połączyć się z Gatewayem. Przewodniki: [exe.dev](/pl/install/exe-dev), [Hetzner](/pl/install/hetzner), [Fly.io](/pl/install/fly). - Zdalny dostęp: [Gateway remote](/pl/gateway/remote). + Dostęp zdalny: [Gateway remote](/pl/gateway/remote). - Utrzymujemy **hub hostingowy** z typowymi dostawcami. Wybierz jednego z nich i postępuj zgodnie z przewodnikiem: + Mamy **hub hostingowy** z najczęściej używanymi providerami. Wybierz jeden i postępuj zgodnie z przewodnikiem: - - [Hosting VPS](/pl/vps) (wszyscy dostawcy w jednym miejscu) + - [Hosting VPS](/pl/vps) (wszyscy providerzy w jednym miejscu) - [Fly.io](/pl/install/fly) - [Hetzner](/pl/install/hetzner) - [exe.dev](/pl/install/exe-dev) Jak to działa w chmurze: **Gateway działa na serwerze**, a Ty uzyskujesz do niego dostęp - z laptopa/telefonu przez Control UI (lub Tailscale/SSH). Twój stan + workspace - żyją na serwerze, więc traktuj host jako źródło prawdy i twórz jego kopie zapasowe. + z laptopa/telefonu przez Control UI (albo Tailscale/SSH). Twój stan + workspace + znajdują się na serwerze, więc traktuj host jako źródło prawdy i twórz jego kopie zapasowe. - Możesz sparować **nodes** (Mac/iOS/Android/headless) z tym chmurowym Gateway, aby uzyskać dostęp - do lokalnego ekranu/kamery/canvas lub uruchamiać polecenia na laptopie, trzymając + Możesz sparować **nodes** (Mac/iOS/Android/headless) z tym chmurowym Gatewayem, aby uzyskać dostęp do + lokalnego ekranu/kamery/canvas lub uruchamiać polecenia na swoim laptopie, jednocześnie trzymając Gateway w chmurze. - Hub: [Platforms](/pl/platforms). Zdalny dostęp: [Gateway remote](/pl/gateway/remote). + Hub: [Platformy](/pl/platforms). Dostęp zdalny: [Gateway remote](/pl/gateway/remote). Nodes: [Nodes](/pl/nodes), [Nodes CLI](/cli/nodes). - - Krótka odpowiedź: **możliwe, ale niezalecane**. Przepływ aktualizacji może zrestartować - Gateway (co zrywa aktywną sesję), może wymagać czystego checkoutu git - i może prosić o potwierdzenie. Bezpieczniej jest uruchamiać aktualizacje z powłoki jako operator. + + Krótka odpowiedź: **to możliwe, ale niezalecane**. Proces aktualizacji może zrestartować + Gateway (co zrywa aktywną sesję), może wymagać czystego checkoutu git i + może poprosić o potwierdzenie. Bezpieczniej: uruchamiaj aktualizacje z powłoki jako operator. Użyj CLI: @@ -558,250 +558,250 @@ Szybkie odpowiedzi oraz bardziej szczegółowe rozwiązywanie problemów dla rze openclaw update --no-restart ``` - Jeśli musisz zautomatyzować to z agenta: + Jeśli musisz zautomatyzować to z poziomu agenta: ```bash openclaw update --yes --no-restart openclaw gateway restart ``` - Dokumentacja: [Update](/cli/update), [Updating](/pl/install/updating). + Dokumentacja: [Aktualizacja](/cli/update), [Aktualizacje](/pl/install/updating). - `openclaw onboard` to zalecana ścieżka konfiguracji. W **trybie local** prowadzi Cię przez: + `openclaw onboard` to zalecana ścieżka konfiguracji. W **trybie lokalnym** przeprowadza Cię przez: - - **Konfigurację modelu/auth** (OAuth dostawcy, klucze API, setup-token Anthropic oraz lokalne opcje modeli, takie jak LM Studio) - - lokalizację **workspace** + pliki bootstrap - - **ustawienia Gateway** (bind/port/auth/tailscale) - - **kanały** (WhatsApp, Telegram, Discord, Mattermost, Signal, iMessage oraz bundlowane plugins kanałów, takie jak QQ Bot) - - **instalację demona** (LaunchAgent na macOS; user unit systemd na Linux/WSL2) - - **kontrole zdrowia** oraz wybór **Skills** + - **Konfigurację modelu/uwierzytelniania** (OAuth providera, klucze API, Anthropic setup-token oraz lokalne opcje modeli, takie jak LM Studio) + - Lokalizację **workspace** + pliki bootstrap + - **Ustawienia Gatewaya** (bind/port/auth/tailscale) + - **Kanały** (WhatsApp, Telegram, Discord, Mattermost, Signal, iMessage oraz bundlowane pluginy kanałów, takie jak QQ Bot) + - **Instalację demona** (LaunchAgent na macOS; systemd user unit na Linux/WSL2) + - **Kontrole kondycji** oraz wybór **Skills** - Ostrzega też, jeśli skonfigurowany model jest nieznany lub brakuje dla niego auth. + Ostrzega też, jeśli skonfigurowany model jest nieznany albo brakuje dla niego uwierzytelnienia. - - Nie. Możesz uruchamiać OpenClaw z **kluczami API** (Anthropic/OpenAI/inne) albo z - **lokalnymi modelami**, dzięki czemu dane pozostają na Twoim urządzeniu. Subskrypcje (Claude - Pro/Max lub OpenAI Codex) to opcjonalne sposoby uwierzytelniania u tych dostawców. + + Nie. Możesz uruchamiać OpenClaw za pomocą **kluczy API** (Anthropic/OpenAI/inni) albo z + **wyłącznie lokalnymi modelami**, aby Twoje dane pozostawały na urządzeniu. Subskrypcje (Claude + Pro/Max lub OpenAI Codex) są opcjonalnymi sposobami uwierzytelniania tych providerów. - Dla Anthropic w OpenClaw praktyczny podział wygląda tak: + W praktyce podział dla Anthropic w OpenClaw wygląda tak: - - **Klucz API Anthropic**: zwykłe rozliczanie API Anthropic - - **Claude CLI / auth subskrypcji Claude w OpenClaw**: personel Anthropic - poinformował nas, że to użycie jest ponownie dozwolone, a OpenClaw traktuje użycie `claude -p` - jako zaakceptowane dla tej integracji, chyba że Anthropic opublikuje nowe - zasady + - **Klucz API Anthropic**: normalne rozliczanie API Anthropic + - **Uwierzytelnienie Claude CLI / subskrypcja Claude w OpenClaw**: pracownicy Anthropic + powiedzieli nam, że to użycie jest ponownie dozwolone, a OpenClaw traktuje użycie `claude -p` + jako usankcjonowane dla tej integracji, chyba że Anthropic opublikuje nową + politykę - Dla długo działających hostów gateway klucze API Anthropic są nadal bardziej - przewidywalną konfiguracją. OAuth OpenAI Codex jest jawnie obsługiwany dla zewnętrznych + Dla długowiecznych hostów gatewaya klucze API Anthropic pozostają bardziej + przewidywalnym rozwiązaniem. OpenAI Codex OAuth jest wyraźnie wspierany dla zewnętrznych narzędzi takich jak OpenClaw. - OpenClaw obsługuje też inne hostowane opcje w stylu subskrypcyjnym, w tym - **Qwen Cloud Coding Plan**, **MiniMax Coding Plan** oraz + OpenClaw obsługuje także inne hostowane opcje subskrypcyjne, w tym + **Qwen Cloud Coding Plan**, **MiniMax Coding Plan** i **Z.AI / GLM Coding Plan**. Dokumentacja: [Anthropic](/pl/providers/anthropic), [OpenAI](/pl/providers/openai), [Qwen Cloud](/pl/providers/qwen), - [MiniMax](/pl/providers/minimax), [GLM Models](/pl/providers/glm), - [Local models](/pl/gateway/local-models), [Models](/pl/concepts/models). + [MiniMax](/pl/providers/minimax), [Modele GLM](/pl/providers/glm), + [Modele lokalne](/pl/gateway/local-models), [Modele](/pl/concepts/models). Tak. - Personel Anthropic poinformował nas, że użycie Claude CLI w stylu OpenClaw jest znowu dozwolone, więc - OpenClaw traktuje auth subskrypcji Claude i użycie `claude -p` jako zaakceptowane - dla tej integracji, chyba że Anthropic opublikuje nowe zasady. Jeśli chcesz - najbardziej przewidywalną konfigurację po stronie serwera, użyj zamiast tego klucza API Anthropic. + Pracownicy Anthropic powiedzieli nam, że użycie Claude CLI w stylu OpenClaw jest znowu dozwolone, więc + OpenClaw traktuje uwierzytelnianie subskrypcją Claude i użycie `claude -p` jako usankcjonowane + dla tej integracji, chyba że Anthropic opublikuje nową politykę. Jeśli chcesz + najbardziej przewidywalnego rozwiązania po stronie serwera, użyj zamiast tego klucza API Anthropic. - + Tak. - Personel Anthropic poinformował nas, że to użycie jest ponownie dozwolone, więc OpenClaw traktuje - ponowne użycie Claude CLI i użycie `claude -p` jako zaakceptowane dla tej integracji, - chyba że Anthropic opublikuje nowe zasady. + Pracownicy Anthropic powiedzieli nam, że to użycie jest znowu dozwolone, więc OpenClaw traktuje + ponowne użycie Claude CLI oraz użycie `claude -p` jako usankcjonowane dla tej integracji, + chyba że Anthropic opublikuje nową politykę. - Setup-token Anthropic jest nadal dostępny jako obsługiwana ścieżka tokenu OpenClaw, ale OpenClaw teraz preferuje ponowne użycie Claude CLI i `claude -p`, gdy są dostępne. - Dla środowisk produkcyjnych lub wieloużytkownikowych auth kluczem API Anthropic nadal jest - bezpieczniejszym, bardziej przewidywalnym wyborem. Jeśli chcesz w OpenClaw innych hostowanych opcji - w stylu subskrypcyjnym, zobacz [OpenAI](/pl/providers/openai), [Qwen / Model - Cloud](/pl/providers/qwen), [MiniMax](/pl/providers/minimax) i [GLM - Models](/pl/providers/glm). + Anthropic setup-token jest nadal dostępny jako obsługiwana ścieżka tokenu OpenClaw, ale OpenClaw teraz preferuje ponowne użycie Claude CLI i `claude -p`, gdy są dostępne. + Dla środowisk produkcyjnych lub obciążeń wieloużytkownikowych uwierzytelnianie kluczem API Anthropic pozostaje + bezpieczniejszym i bardziej przewidywalnym wyborem. Jeśli chcesz inne hostowane opcje + subskrypcyjne w OpenClaw, zobacz [OpenAI](/pl/providers/openai), [Qwen / Model + Cloud](/pl/providers/qwen), [MiniMax](/pl/providers/minimax) i [Modele + GLM](/pl/providers/glm). - -To oznacza, że Twój **limit/quota Anthropic** wyczerpał się w bieżącym oknie. Jeśli + +To oznacza, że Twój **limit/quota Anthropic** został wyczerpany dla bieżącego okna. Jeśli używasz **Claude CLI**, poczekaj, aż okno się zresetuje, albo podnieś plan. Jeśli -używasz **klucza API Anthropic**, sprawdź Anthropic Console -pod kątem użycia/rozliczeń i w razie potrzeby zwiększ limity. +używasz **klucza API Anthropic**, sprawdź konsolę Anthropic +pod kątem użycia/rozliczeń i w razie potrzeby podnieś limity. - Jeśli komunikat brzmi konkretnie: - `Extra usage is required for long context requests`, żądanie próbuje użyć - bety 1M context Anthropic (`context1m: true`). To działa tylko wtedy, gdy Twoje - poświadczenie kwalifikuje się do rozliczania long-context (rozliczanie kluczem API lub + Jeśli komunikat brzmi dokładnie: + `Extra usage is required for long context requests`, to żądanie próbuje użyć + wersji beta 1M kontekstu Anthropic (`context1m: true`). To działa tylko wtedy, gdy Twoje + poświadczenie kwalifikuje się do rozliczania długiego kontekstu (rozliczenie kluczem API lub ścieżka logowania Claude w OpenClaw z włączonym Extra Usage). - Wskazówka: ustaw **fallback model**, aby OpenClaw mógł dalej odpowiadać, gdy dostawca jest ograniczony przez rate limit. - Zobacz [Models](/cli/models), [OAuth](/pl/concepts/oauth) oraz + Wskazówka: ustaw **model fallback**, aby OpenClaw mógł nadal odpowiadać, gdy provider jest objęty rate limitingiem. + Zobacz [Modele](/cli/models), [OAuth](/pl/concepts/oauth) i [/gateway/troubleshooting#anthropic-429-extra-usage-required-for-long-context](/pl/gateway/troubleshooting#anthropic-429-extra-usage-required-for-long-context). - - Tak. OpenClaw ma bundlowanego dostawcę **Amazon Bedrock (Converse)**. Gdy obecne są markery env AWS, OpenClaw może automatycznie wykryć katalog Bedrock dla streamingu/tekstu i scalić go jako niejawnego dostawcę `amazon-bedrock`; w przeciwnym razie możesz jawnie włączyć `plugins.entries.amazon-bedrock.config.discovery.enabled` lub dodać ręczny wpis dostawcy. Zobacz [Amazon Bedrock](/pl/providers/bedrock) i [Model providers](/pl/providers/models). Jeśli wolisz zarządzany przepływ z kluczem, zgodny z OpenAI proxy przed Bedrock nadal jest poprawną opcją. + + Tak. OpenClaw ma bundlowanego providera **Amazon Bedrock (Converse)**. Gdy obecne są znaczniki środowiskowe AWS, OpenClaw może automatycznie wykryć katalog streaming/text Bedrock i scalić go jako niejawnego providera `amazon-bedrock`; w przeciwnym razie możesz jawnie włączyć `plugins.entries.amazon-bedrock.config.discovery.enabled` albo dodać ręczny wpis providera. Zobacz [Amazon Bedrock](/pl/providers/bedrock) i [Providerzy modeli](/pl/providers/models). Jeśli wolisz zarządzany przepływ kluczy, proxy zgodne z OpenAI przed Bedrock nadal jest poprawną opcją. - - OpenClaw obsługuje **OpenAI Code (Codex)** przez OAuth (logowanie ChatGPT). Onboarding może uruchomić przepływ OAuth i ustawi domyślny model na `openai-codex/gpt-5.4`, gdy będzie to odpowiednie. Zobacz [Model providers](/pl/concepts/model-providers) i [Onboarding (CLI)](/pl/start/wizard). + + OpenClaw obsługuje **OpenAI Code (Codex)** przez OAuth (logowanie ChatGPT). Onboarding może uruchomić przepływ OAuth i ustawi domyślny model na `openai-codex/gpt-5.4`, gdy będzie to właściwe. Zobacz [Providerzy modeli](/pl/concepts/model-providers) i [Onboarding (CLI)](/pl/start/wizard). OpenClaw traktuje te dwie ścieżki osobno: - `openai-codex/gpt-5.4` = OAuth ChatGPT/Codex - - `openai/gpt-5.4` = bezpośrednie API OpenAI Platform + - `openai/gpt-5.4` = bezpośrednie API platformy OpenAI W OpenClaw logowanie ChatGPT/Codex jest podłączone do ścieżki `openai-codex/*`, - a nie do bezpośredniej ścieżki `openai/*`. Jeśli chcesz w - OpenClaw bezpośredniej ścieżki API, ustaw `OPENAI_API_KEY` (lub równoważny config dostawcy OpenAI). - Jeśli chcesz logowanie ChatGPT/Codex w OpenClaw, użyj `openai-codex/*`. + a nie bezpośredniej ścieżki `openai/*`. Jeśli chcesz w + OpenClaw korzystać z bezpośredniej ścieżki API, ustaw `OPENAI_API_KEY` (lub równoważną konfigurację providera OpenAI). + Jeśli chcesz logowania ChatGPT/Codex w OpenClaw, używaj `openai-codex/*`. - - `openai-codex/*` używa ścieżki OAuth Codex, a jego używalne okna quota są - zarządzane przez OpenAI i zależne od planu. W praktyce te limity mogą różnić się od - doświadczenia na stronie/aplikacji ChatGPT, nawet jeśli oba są powiązane z tym samym kontem. + + `openai-codex/*` używa ścieżki OAuth Codex, a jego użyteczne okna quota są + zarządzane przez OpenAI i zależne od planu. W praktyce limity te mogą różnić się od + doświadczenia w witrynie/aplikacji ChatGPT, nawet gdy oba są powiązane z tym samym kontem. - OpenClaw może pokazywać aktualnie widoczne okna użycia/quota dostawcy w + OpenClaw może pokazać aktualnie widoczne okna użycia/quota providera w `openclaw models status`, ale nie wymyśla ani nie normalizuje uprawnień ChatGPT-web - do bezpośredniego dostępu do API. Jeśli chcesz bezpośredniej ścieżki rozliczeń/limitów OpenAI Platform, + do bezpośredniego dostępu do API. Jeśli chcesz bezpośredniej ścieżki rozliczeń/limitów platformy OpenAI, użyj `openai/*` z kluczem API. - - Tak. OpenClaw w pełni obsługuje **OAuth subskrypcji OpenAI Code (Codex)**. - OpenAI jawnie zezwala na użycie OAuth subskrypcji w zewnętrznych narzędziach/przepływach - takich jak OpenClaw. Onboarding może uruchomić ten przepływ za Ciebie. + + Tak. OpenClaw w pełni wspiera **subskrypcyjny OAuth OpenAI Code (Codex)**. + OpenAI wyraźnie pozwala na używanie subskrypcyjnego OAuth w zewnętrznych narzędziach/przepływach pracy + takich jak OpenClaw. Onboarding może przeprowadzić ten przepływ OAuth za Ciebie. - Zobacz [OAuth](/pl/concepts/oauth), [Model providers](/pl/concepts/model-providers) i [Onboarding (CLI)](/pl/start/wizard). + Zobacz [OAuth](/pl/concepts/oauth), [Providerzy modeli](/pl/concepts/model-providers) i [Onboarding (CLI)](/pl/start/wizard). - Gemini CLI używa **przepływu auth pluginu**, a nie client id lub secret w `openclaw.json`. + Gemini CLI używa **przepływu uwierzytelniania pluginu**, a nie client id ani secret w `openclaw.json`. Kroki: - 1. Zainstaluj lokalnie Gemini CLI, tak aby `gemini` było na `PATH` + 1. Zainstaluj lokalnie Gemini CLI, aby `gemini` było w `PATH` - Homebrew: `brew install gemini-cli` - npm: `npm install -g @google/gemini-cli` 2. Włącz plugin: `openclaw plugins enable google` 3. Zaloguj się: `openclaw models auth login --provider google-gemini-cli --set-default` 4. Domyślny model po zalogowaniu: `google-gemini-cli/gemini-3-flash-preview` - 5. Jeśli żądania kończą się błędem, ustaw `GOOGLE_CLOUD_PROJECT` lub `GOOGLE_CLOUD_PROJECT_ID` na hoście gateway + 5. Jeśli żądania kończą się błędem, ustaw `GOOGLE_CLOUD_PROJECT` lub `GOOGLE_CLOUD_PROJECT_ID` na hoście gatewaya - To zapisuje tokeny OAuth w profilach auth na hoście gateway. Szczegóły: [Model providers](/pl/concepts/model-providers). + To zapisuje tokeny OAuth w profilach uwierzytelniania na hoście gatewaya. Szczegóły: [Providerzy modeli](/pl/concepts/model-providers). - - Zwykle nie. OpenClaw potrzebuje dużego kontekstu + silnego bezpieczeństwa; małe karty przycinają i przeciekają. Jeśli musisz, uruchom lokalnie **największy** build modelu, jaki możesz (LM Studio), i zobacz [/gateway/local-models](/pl/gateway/local-models). Mniejsze/kwantyzowane modele zwiększają ryzyko prompt injection — zobacz [Security](/pl/gateway/security). + + Zwykle nie. OpenClaw potrzebuje dużego kontekstu i silnego bezpieczeństwa; małe karty obcinają kontekst i osłabiają ochronę. Jeśli musisz, uruchom lokalnie **największą** kompilację modelu, jaką możesz (LM Studio), i zobacz [/gateway/local-models](/pl/gateway/local-models). Mniejsze/kwantyzowane modele zwiększają ryzyko prompt injection — zobacz [Bezpieczeństwo](/pl/gateway/security). - Wybieraj endpointy przypięte do regionu. OpenRouter udostępnia opcje hostowane w USA dla MiniMax, Kimi i GLM; wybierz wariant hostowany w USA, aby utrzymać dane w regionie. Nadal możesz wymienić Anthropic/OpenAI obok nich, używając `models.mode: "merge"`, tak aby fallbacki pozostały dostępne przy jednoczesnym poszanowaniu wybranego dostawcy regionalnego. + Wybieraj endpointy przypięte do regionu. OpenRouter udostępnia opcje hostowane w USA dla MiniMax, Kimi i GLM; wybierz wariant hostowany w USA, aby utrzymać dane w regionie. Nadal możesz wymieniać obok nich Anthropic/OpenAI, używając `models.mode: "merge"`, aby fallbacki pozostały dostępne przy jednoczesnym poszanowaniu wybranego providera regionalnego. Nie. OpenClaw działa na macOS lub Linuxie (Windows przez WSL2). Mac mini jest opcjonalny — niektórzy - kupują go jako stale działającego hosta, ale mały VPS, serwer domowy albo urządzenie klasy Raspberry Pi też się nadaje. + kupują go jako host zawsze włączony, ale mały VPS, serwer domowy lub urządzenie klasy Raspberry Pi też się nada. - Potrzebujesz Maca tylko do **narzędzi wyłącznie dla macOS**. Dla iMessage użyj [BlueBubbles](/pl/channels/bluebubbles) (zalecane) — serwer BlueBubbles działa na dowolnym Macu, a Gateway może działać na Linuxie lub gdzie indziej. Jeśli chcesz innych narzędzi tylko dla macOS, uruchom Gateway na Macu albo sparuj node macOS. + Maca potrzebujesz tylko do **narzędzi wyłącznie dla macOS**. Dla iMessage użyj [BlueBubbles](/pl/channels/bluebubbles) (zalecane) — serwer BlueBubbles działa na dowolnym Macu, a Gateway może działać na Linuxie lub gdzie indziej. Jeśli chcesz innych narzędzi tylko dla macOS, uruchom Gateway na Macu albo sparuj node macOS. - Dokumentacja: [BlueBubbles](/pl/channels/bluebubbles), [Nodes](/pl/nodes), [Mac remote mode](/pl/platforms/mac/remote). + Dokumentacja: [BlueBubbles](/pl/channels/bluebubbles), [Nodes](/pl/nodes), [Zdalny tryb Mac](/pl/platforms/mac/remote). - - Potrzebujesz **jakiegoś urządzenia macOS** zalogowanego do Messages. To **nie** musi być Mac mini — - dowolny Mac wystarczy. **Użyj [BlueBubbles](/pl/channels/bluebubbles)** (zalecane) dla iMessage — serwer BlueBubbles działa na macOS, a Gateway może działać na Linuxie lub gdzie indziej. + + Potrzebujesz **jakiegoś urządzenia z macOS** zalogowanego do Wiadomości. **Nie** musi to być Mac mini — + każdy Mac się nada. Dla iMessage **użyj [BlueBubbles](/pl/channels/bluebubbles)** (zalecane) — serwer BlueBubbles działa na macOS, podczas gdy Gateway może działać na Linuxie lub gdzie indziej. Typowe konfiguracje: - - Uruchom Gateway na Linuxie/VPS, a serwer BlueBubbles na dowolnym Macu zalogowanym do Messages. - - Uruchom wszystko na Macu, jeśli chcesz najprostszą konfigurację na jednej maszynie. + - Uruchamiaj Gateway na Linuxie/VPS, a serwer BlueBubbles na dowolnym Macu zalogowanym do Wiadomości. + - Uruchamiaj wszystko na Macu, jeśli chcesz najprostszą konfigurację na jednej maszynie. Dokumentacja: [BlueBubbles](/pl/channels/bluebubbles), [Nodes](/pl/nodes), - [Mac remote mode](/pl/platforms/mac/remote). + [Zdalny tryb Mac](/pl/platforms/mac/remote). - - Tak. **Mac mini może uruchamiać Gateway**, a Twój MacBook Pro może łączyć się jako - **node** (urządzenie towarzyszące). Nodes nie uruchamiają Gateway — zapewniają dodatkowe - możliwości, takie jak screen/camera/canvas oraz `system.run` na tym urządzeniu. + + Tak. **Mac mini może uruchamiać Gateway**, a Twój MacBook Pro może połączyć się jako + **node** (urządzenie towarzyszące). Nodes nie uruchamiają Gatewaya — zapewniają dodatkowe + możliwości, takie jak screen/camera/canvas i `system.run` na tym urządzeniu. Typowy wzorzec: - Gateway na Mac mini (zawsze włączony). - - MacBook Pro uruchamia aplikację macOS lub host node i paruje się z Gateway. - - Używaj `openclaw nodes status` / `openclaw nodes list`, aby to zobaczyć. + - MacBook Pro uruchamia aplikację macOS lub host node i paruje się z Gatewayem. + - Użyj `openclaw nodes status` / `openclaw nodes list`, aby go zobaczyć. Dokumentacja: [Nodes](/pl/nodes), [Nodes CLI](/cli/nodes). - Bun **nie jest zalecany**. Widzimy błędy runtime, szczególnie z WhatsApp i Telegram. - Do stabilnych gateway używaj **Node**. + Bun **nie jest zalecany**. Widzimy błędy środowiska uruchomieniowego, szczególnie z WhatsApp i Telegram. + Dla stabilnych gatewayów używaj **Node**. - Jeśli mimo to chcesz eksperymentować z Bun, rób to na nieprodukcyjnym gateway + Jeśli mimo to chcesz eksperymentować z Bun, rób to na nieprodukcyjnym gatewayu bez WhatsApp/Telegram. - - `channels.telegram.allowFrom` to **Telegram user ID ludzkiego nadawcy** (liczbowe). To nie jest nazwa użytkownika bota. + + `channels.telegram.allowFrom` to **identyfikator użytkownika Telegram osoby wysyłającej** (liczbowy). To nie jest nazwa użytkownika bota. - Onboarding akceptuje wejście `@username` i rozwiązuje je do ID numerycznego, ale autoryzacja OpenClaw używa wyłącznie ID numerycznych. + Onboarding przyjmuje wejście `@username` i rozwiązuje je do identyfikatora liczbowego, ale autoryzacja OpenClaw używa wyłącznie identyfikatorów liczbowych. - Bezpieczniej (bez zewnętrznego bota): + Bezpieczniej (bez bota zewnętrznego): - - Napisz DM do swojego bota, a potem uruchom `openclaw logs --follow` i odczytaj `from.id`. + - Wyślij DM do swojego bota, a następnie uruchom `openclaw logs --follow` i odczytaj `from.id`. Oficjalne Bot API: - - Napisz DM do swojego bota, a potem wywołaj `https://api.telegram.org/bot/getUpdates` i odczytaj `message.from.id`. + - Wyślij DM do swojego bota, a następnie wywołaj `https://api.telegram.org/bot/getUpdates` i odczytaj `message.from.id`. - Zewnętrzne narzędzia (mniej prywatne): + Zewnętrznie (mniejsza prywatność): - - Napisz DM do `@userinfobot` lub `@getidsbot`. + - Wyślij DM do `@userinfobot` lub `@getidsbot`. Zobacz [/channels/telegram](/pl/channels/telegram#access-control-and-activation). - Tak, przez **multi-agent routing**. Powiąż DM WhatsApp każdego nadawcy (**peer** `kind: "direct"`, nadawca E.164 jak `+15551234567`) z innym `agentId`, aby każda osoba miała własny workspace i magazyn sesji. Odpowiedzi nadal będą wychodziły z **tego samego konta WhatsApp**, a kontrola dostępu do DM (`channels.whatsapp.dmPolicy` / `channels.whatsapp.allowFrom`) jest globalna dla danego konta WhatsApp. Zobacz [Multi-Agent Routing](/pl/concepts/multi-agent) i [WhatsApp](/pl/channels/whatsapp). + Tak, przez **routing wielu agentów**. Powiąż DM WhatsApp każdego nadawcy (**DM**) (peer `kind: "direct"`, nadawca E.164 jak `+15551234567`) z innym `agentId`, aby każda osoba miała własny workspace i magazyn sesji. Odpowiedzi nadal będą pochodzić z **tego samego konta WhatsApp**, a kontrola dostępu do DM (`channels.whatsapp.dmPolicy` / `channels.whatsapp.allowFrom`) jest globalna dla danego konta WhatsApp. Zobacz [Routing wielu agentów](/pl/concepts/multi-agent) i [WhatsApp](/pl/channels/whatsapp). - - Tak. Użyj multi-agent routing: przypisz każdemu agentowi własny model domyślny, a potem powiąż przychodzące trasy (konto dostawcy lub konkretne peer) z każdym agentem. Przykładowa konfiguracja znajduje się w [Multi-Agent Routing](/pl/concepts/multi-agent). Zobacz też [Models](/pl/concepts/models) i [Configuration](/pl/gateway/configuration). + + Tak. Użyj routingu wielu agentów: daj każdemu agentowi własny domyślny model, a następnie powiąż trasy wejściowe (konto providera albo określonych peerów) z każdym agentem. Przykładowa konfiguracja znajduje się w [Routing wielu agentów](/pl/concepts/multi-agent). Zobacz także [Modele](/pl/concepts/models) i [Konfiguracja](/pl/gateway/configuration). - Tak. Homebrew obsługuje Linuxa (Linuxbrew). Szybka konfiguracja: + Tak. Homebrew wspiera Linuksa (Linuxbrew). Szybka konfiguracja: ```bash /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" @@ -810,23 +810,23 @@ pod kątem użycia/rozliczeń i w razie potrzeby zwiększ limity. brew install ``` - Jeśli uruchamiasz OpenClaw przez systemd, upewnij się, że PATH usługi zawiera `/home/linuxbrew/.linuxbrew/bin` (lub Twój prefiks brew), aby narzędzia zainstalowane przez `brew` były rozwiązywane w powłokach niebędących login shell. - Ostatnie buildy poprzedzają też typowe katalogi bin użytkownika w usługach Linux systemd (na przykład `~/.local/bin`, `~/.npm-global/bin`, `~/.local/share/pnpm`, `~/.bun/bin`) oraz honorują `PNPM_HOME`, `NPM_CONFIG_PREFIX`, `BUN_INSTALL`, `VOLTA_HOME`, `ASDF_DATA_DIR`, `NVM_DIR` i `FNM_DIR`, jeśli są ustawione. + Jeśli uruchamiasz OpenClaw przez systemd, upewnij się, że PATH usługi zawiera `/home/linuxbrew/.linuxbrew/bin` (lub Twój prefiks brew), aby narzędzia zainstalowane przez `brew` były rozwiązywane w powłokach bez logowania. + Najnowsze kompilacje dodają też na początku typowe katalogi user bin w usługach systemd na Linuxie (na przykład `~/.local/bin`, `~/.npm-global/bin`, `~/.local/share/pnpm`, `~/.bun/bin`) i honorują `PNPM_HOME`, `NPM_CONFIG_PREFIX`, `BUN_INSTALL`, `VOLTA_HOME`, `ASDF_DATA_DIR`, `NVM_DIR` oraz `FNM_DIR`, gdy są ustawione. - - - **Instalacja hackable (git):** pełny checkout źródeł, edytowalny, najlepszy dla współtwórców. - Buildy uruchamiasz lokalnie i możesz poprawiać kod/dokumentację. - - **npm install:** globalna instalacja CLI, bez repo, najlepsza do „po prostu uruchom”. - Aktualizacje pochodzą z dist-tagów npm. + + - **Instalacja hackowalna (git):** pełny checkout źródeł, możliwość edycji, najlepsza dla współtwórców. + Budujesz lokalnie i możesz poprawiać kod/dokumentację. + - **npm install:** globalna instalacja CLI, bez repozytorium, najlepsza do „po prostu uruchom”. + Aktualizacje pochodzą z npm dist-tags. - Dokumentacja: [Getting started](/pl/start/getting-started), [Updating](/pl/install/updating). + Dokumentacja: [Pierwsze kroki](/pl/start/getting-started), [Aktualizacja](/pl/install/updating). - - Tak. Zainstaluj drugi wariant, a potem uruchom Doctor, aby usługa gateway wskazywała na nowy entrypoint. + + Tak. Zainstaluj drugi wariant, a następnie uruchom Doctor, aby usługa gatewaya wskazywała nowy entrypoint. To **nie usuwa Twoich danych** — zmienia tylko instalację kodu OpenClaw. Twój stan (`~/.openclaw`) i workspace (`~/.openclaw/workspace`) pozostają nietknięte. @@ -849,68 +849,68 @@ pod kątem użycia/rozliczeń i w razie potrzeby zwiększ limity. openclaw gateway restart ``` - Doctor wykrywa niedopasowanie entrypointu usługi gateway i proponuje przepisanie konfiguracji usługi tak, aby odpowiadała bieżącej instalacji (użyj `--repair` w automatyzacji). + Doctor wykrywa niedopasowanie entrypointu usługi gatewaya i proponuje przepisanie konfiguracji usługi tak, aby pasowała do bieżącej instalacji (w automatyzacji użyj `--repair`). - Wskazówki dotyczące kopii zapasowych: zobacz [Strategia kopii zapasowych](#gdzie-rzeczy-znajduja-sie-na-dysku). + Wskazówki dotyczące kopii zapasowych: zobacz [Strategia kopii zapasowych](#gdzie-rzeczy-znajdują-się-na-dysku). - - Krótka odpowiedź: **jeśli chcesz niezawodności 24/7, użyj VPS**. Jeśli zależy Ci na - najmniejszym tarciu i akceptujesz usypianie/restarty, uruchamiaj lokalnie. + + Krótka odpowiedź: **jeśli chcesz niezawodności 24/7, użyj VPS**. Jeśli chcesz + najmniejszego tarcia i akceptujesz uśpienia/restarty, uruchamiaj lokalnie. **Laptop (lokalny Gateway)** - - **Zalety:** brak kosztu serwera, bezpośredni dostęp do lokalnych plików, widoczne okno przeglądarki. - - **Wady:** uśpienie/zerwanie sieci = rozłączenia, aktualizacje/rebooty OS przerywają pracę, maszyna musi być stale aktywna. + - **Plusy:** brak kosztów serwera, bezpośredni dostęp do lokalnych plików, widoczne okno przeglądarki. + - **Minusy:** uśpienie/zaniki sieci = rozłączenia, aktualizacje/restarty systemu przerywają, maszyna musi pozostać wybudzona. **VPS / chmura** - - **Zalety:** zawsze włączony, stabilna sieć, brak problemów z uśpieniem laptopa, łatwiej utrzymać działanie. - - **Wady:** często działa headless (używaj screenshotów), dostęp tylko do zdalnych plików, do aktualizacji potrzebujesz SSH. + - **Plusy:** zawsze włączony, stabilna sieć, brak problemów z uśpieniem laptopa, łatwiej utrzymać działanie. + - **Minusy:** często działa headless (używaj zrzutów ekranu), tylko zdalny dostęp do plików, aktualizacje wymagają SSH. - **Uwaga specyficzna dla OpenClaw:** WhatsApp/Telegram/Slack/Mattermost/Discord działają dobrze z VPS. Jedyny realny kompromis to **przeglądarka headless** vs widoczne okno. Zobacz [Browser](/pl/tools/browser). + **Uwaga specyficzna dla OpenClaw:** WhatsApp/Telegram/Slack/Mattermost/Discord działają dobrze z VPS. Jedyny realny kompromis to **przeglądarka headless** vs widoczne okno. Zobacz [Przeglądarka](/pl/tools/browser). - **Zalecane domyślne podejście:** VPS, jeśli wcześniej miałeś rozłączenia gateway. Lokalnie jest świetnie, gdy aktywnie używasz Maca i chcesz lokalnego dostępu do plików lub automatyzacji UI z widoczną przeglądarką. + **Zalecany domyślny wybór:** VPS, jeśli wcześniej miałeś rozłączenia gatewaya. Lokalnie jest świetnie, gdy aktywnie używasz Maca i chcesz lokalnego dostępu do plików albo automatyzacji UI z widoczną przeglądarką. - Nie jest to wymagane, ale **zalecane dla niezawodności i izolacji**. + Nie jest wymagane, ale **zalecane dla niezawodności i izolacji**. - - **Dedykowany host (VPS/Mac mini/Pi):** zawsze włączony, mniej przerw przez uśpienie/rebooty, czystsze uprawnienia, łatwiej utrzymać działanie. - - **Współdzielony laptop/desktop:** w pełni OK do testów i aktywnego użycia, ale spodziewaj się przerw, gdy maszyna śpi lub się aktualizuje. + - **Dedykowany host (VPS/Mac mini/Pi):** zawsze włączony, mniej przerw przez uśpienia/restarty, czystsze uprawnienia, łatwiej utrzymać działanie. + - **Współdzielony laptop/desktop:** całkowicie OK do testów i aktywnego użycia, ale spodziewaj się przerw, gdy maszyna śpi lub się aktualizuje. - Jeśli chcesz połączyć oba światy, trzymaj Gateway na dedykowanym hoście i sparuj laptop jako **node** dla lokalnych narzędzi screen/camera/exec. Zobacz [Nodes](/pl/nodes). - Wskazówki bezpieczeństwa znajdziesz w [Security](/pl/gateway/security). + Jeśli chcesz mieć to, co najlepsze z obu światów, trzymaj Gateway na dedykowanym hoście, a laptop sparuj jako **node** dla lokalnych narzędzi screen/camera/exec. Zobacz [Nodes](/pl/nodes). + Wskazówki bezpieczeństwa znajdziesz w [Bezpieczeństwie](/pl/gateway/security). - - OpenClaw jest lekki. Dla podstawowego Gateway + jednego kanału czatu: + + OpenClaw jest lekki. Dla podstawowego Gatewaya + jednego kanału czatu: - - **Bezwzględne minimum:** 1 vCPU, 1GB RAM, ~500MB dysku. - - **Zalecane:** 1-2 vCPU, 2GB RAM lub więcej dla zapasu (logi, media, wiele kanałów). Narzędzia node i automatyzacja przeglądarki mogą być zasobożerne. + - **Absolutne minimum:** 1 vCPU, 1 GB RAM, ~500 MB dysku. + - **Zalecane:** 1-2 vCPU, 2 GB RAM lub więcej dla zapasu (logi, media, wiele kanałów). Narzędzia node i automatyzacja przeglądarki mogą być zasobożerne. - OS: używaj **Ubuntu LTS** (lub dowolnego nowoczesnego Debian/Ubuntu). To najlepiej przetestowana ścieżka instalacji na Linuxie. + System operacyjny: używaj **Ubuntu LTS** (lub dowolnego nowoczesnego Debian/Ubuntu). Ścieżka instalacji Linux jest tam najlepiej przetestowana. - Dokumentacja: [Linux](/pl/platforms/linux), [VPS hosting](/pl/vps). + Dokumentacja: [Linux](/pl/platforms/linux), [Hosting VPS](/pl/vps). - + Tak. Traktuj VM tak samo jak VPS: musi być zawsze włączona, osiągalna i mieć dość - RAM dla Gateway oraz wszystkich włączonych kanałów. + RAM dla Gatewaya i wszystkich włączonych kanałów. - Bazowe wskazówki: + Wskazówki bazowe: - - **Bezwzględne minimum:** 1 vCPU, 1GB RAM. - - **Zalecane:** 2GB RAM lub więcej, jeśli uruchamiasz wiele kanałów, automatyzację przeglądarki lub narzędzia multimedialne. - - **OS:** Ubuntu LTS lub inny nowoczesny Debian/Ubuntu. + - **Absolutne minimum:** 1 vCPU, 1 GB RAM. + - **Zalecane:** 2 GB RAM lub więcej, jeśli uruchamiasz wiele kanałów, automatyzację przeglądarki albo narzędzia multimedialne. + - **System operacyjny:** Ubuntu LTS albo inny nowoczesny Debian/Ubuntu. - Jeśli jesteś na Windows, **WSL2 to najłatwiejsza konfiguracja w stylu VM** i ma najlepszą - zgodność z narzędziami. Zobacz [Windows](/pl/platforms/windows), [VPS hosting](/pl/vps). - Jeśli uruchamiasz macOS w VM, zobacz [macOS VM](/pl/install/macos-vm). + Jeśli używasz Windows, **WSL2 to najłatwiejsza konfiguracja w stylu VM** i ma najlepszą + zgodność z narzędziami. Zobacz [Windows](/pl/platforms/windows), [Hosting VPS](/pl/vps). + Jeśli uruchamiasz macOS w VM, zobacz [VM z macOS](/pl/install/macos-vm). @@ -918,82 +918,82 @@ pod kątem użycia/rozliczeń i w razie potrzeby zwiększ limity. ## Czym jest OpenClaw? - - OpenClaw to osobisty asystent AI, którego uruchamiasz na własnych urządzeniach. Odpowiada na powierzchniach komunikacyjnych, których już używasz (WhatsApp, Telegram, Slack, Mattermost, Discord, Google Chat, Signal, iMessage, WebChat oraz bundlowane plugins kanałów, takie jak QQ Bot) i może też obsługiwać głos + live Canvas na wspieranych platformach. **Gateway** to zawsze włączona płaszczyzna sterowania; produktem jest asystent. + + OpenClaw to osobisty asystent AI uruchamiany na własnych urządzeniach. Odpowiada na powierzchniach wiadomości, których już używasz (WhatsApp, Telegram, Slack, Mattermost, Discord, Google Chat, Signal, iMessage, WebChat oraz bundlowane pluginy kanałów takie jak QQ Bot) i potrafi też obsługiwać głos + live Canvas na wspieranych platformach. **Gateway** to zawsze włączona płaszczyzna sterowania; asystent jest produktem. - OpenClaw to nie „tylko wrapper na Claude”. To **lokalna płaszczyzna sterowania (local-first)**, która pozwala uruchamiać - kompetentnego asystenta na **Twoim własnym sprzęcie**, dostępnego z aplikacji czatu, których już używasz, z - sesjami stanowymi, pamięcią i narzędziami — bez oddawania kontroli nad przepływami pracy hostowanemu + OpenClaw nie jest „po prostu wrapperem na Claude”. To **lokalna płaszczyzna sterowania** pozwalająca uruchamiać + zdolnego asystenta na **własnym sprzęcie**, dostępnego z aplikacji czatowych, których już używasz, z + utrwalonymi sesjami, pamięcią i narzędziami — bez oddawania kontroli nad swoimi przepływami pracy hostowanemu SaaS. - Najważniejsze cechy: + Najważniejsze elementy: - - **Twoje urządzenia, Twoje dane:** uruchamiaj Gateway gdzie chcesz (Mac, Linux, VPS) i trzymaj + - **Twoje urządzenia, Twoje dane:** uruchamiaj Gateway tam, gdzie chcesz (Mac, Linux, VPS), i trzymaj workspace + historię sesji lokalnie. - - **Prawdziwe kanały, nie sandbox webowy:** WhatsApp/Telegram/Slack/Discord/Signal/iMessage itd., + - **Prawdziwe kanały, nie webowy sandbox:** WhatsApp/Telegram/Slack/Discord/Signal/iMessage/etc, plus mobilny głos i Canvas na wspieranych platformach. - - **Niezależność od modelu:** używaj Anthropic, OpenAI, MiniMax, OpenRouter itd., z routingiem - per agent i failover. - - **Opcja tylko lokalna:** uruchamiaj lokalne modele, aby **wszystkie dane mogły pozostać na Twoim urządzeniu**, jeśli chcesz. - - **Multi-agent routing:** oddzielni agenci dla kanału, konta lub zadania, każdy z własnym + - **Niezależność od modelu:** używaj Anthropic, OpenAI, MiniMax, OpenRouter itp., z routingiem + i failoverem per agent. + - **Opcja wyłącznie lokalna:** uruchamiaj modele lokalne, aby **wszystkie dane mogły pozostać na Twoim urządzeniu**, jeśli chcesz. + - **Routing wielu agentów:** oddzielni agenci dla kanału, konta lub zadania, każdy z własnym workspace i ustawieniami domyślnymi. - - **Open source i hackable:** sprawdzaj, rozszerzaj i self-hostuj bez vendor lock-in. + - **Open source i hackowalność:** sprawdzaj, rozszerzaj i self-hostuj bez vendor lock-in. - Dokumentacja: [Gateway](/pl/gateway), [Channels](/pl/channels), [Multi-agent](/pl/concepts/multi-agent), - [Memory](/pl/concepts/memory). + Dokumentacja: [Gateway](/pl/gateway), [Kanały](/pl/channels), [Wieloagentowość](/pl/concepts/multi-agent), + [Pamięć](/pl/concepts/memory). - + Dobre pierwsze projekty: - Zbuduj stronę internetową (WordPress, Shopify albo prostą stronę statyczną). - Stwórz prototyp aplikacji mobilnej (zarys, ekrany, plan API). - - Uporządkuj pliki i foldery (sprzątanie, nazewnictwo, tagowanie). - - Połącz Gmail i zautomatyzuj podsumowania lub follow-upy. + - Zorganizuj pliki i foldery (sprzątanie, nazewnictwo, tagowanie). + - Podłącz Gmail i zautomatyzuj podsumowania albo follow-upy. - Potrafi obsługiwać duże zadania, ale działa najlepiej, gdy podzielisz je na fazy i - używasz subagentów do pracy równoległej. + Potrafi obsługiwać duże zadania, ale działa najlepiej, gdy podzielisz je na etapy i + użyjesz sub agentów do pracy równoległej. Codzienne korzyści zwykle wyglądają tak: - - **Osobiste briefingi:** podsumowania skrzynki odbiorczej, kalendarza i interesujących Cię wiadomości. - - **Research i drafty:** szybki research, podsumowania i pierwsze wersje maili lub dokumentów. - - **Przypomnienia i follow-upy:** szturchnięcia i checklisty sterowane cron lub heartbeat. + - **Osobiste briefingi:** podsumowania skrzynki, kalendarza i interesujących Cię wiadomości. + - **Badania i szkice:** szybkie badania, podsumowania i pierwsze szkice e-maili lub dokumentów. + - **Przypomnienia i follow-upy:** szturchnięcia i checklisty napędzane cronem lub heartbeat. - **Automatyzacja przeglądarki:** wypełnianie formularzy, zbieranie danych i powtarzanie zadań webowych. - - **Koordynacja między urządzeniami:** wyślij zadanie z telefonu, pozwól Gateway uruchomić je na serwerze i odbierz wynik z powrotem na czacie. + - **Koordynacja między urządzeniami:** wyślij zadanie z telefonu, pozwól Gatewayowi wykonać je na serwerze i odbierz wynik z powrotem na czacie. - Tak, jeśli chodzi o **research, kwalifikację i drafty**. Może skanować strony, budować shortlisty, - podsumowywać prospectów i pisać szkice outreachu lub copy reklamowego. + Tak, w zakresie **badań, kwalifikacji i szkicowania**. Potrafi skanować strony, budować krótkie listy, + podsumowywać potencjalnych klientów i pisać szkice outreachu albo tekstów reklamowych. - W przypadku **outreachu lub uruchamiania reklam** trzymaj człowieka w pętli. Unikaj spamu, przestrzegaj lokalnych przepisów i - zasad platform, a wszystko przeglądaj przed wysłaniem. Najbezpieczniejszy wzorzec to - pozwolić OpenClaw przygotować szkic, a Ty go zatwierdzasz. + Przy **outreachu lub uruchamianiu reklam** trzymaj człowieka w pętli. Unikaj spamu, przestrzegaj lokalnych przepisów i + zasad platform, i sprawdzaj wszystko przed wysłaniem. Najbezpieczniejszy wzorzec to: + OpenClaw tworzy szkic, a Ty go zatwierdzasz. - Dokumentacja: [Security](/pl/gateway/security). + Dokumentacja: [Bezpieczeństwo](/pl/gateway/security). - - OpenClaw to **osobisty asystent** i warstwa koordynacji, a nie zamiennik IDE. Używaj - Claude Code lub Codex do najszybszej bezpośredniej pętli kodowania w repo. Używaj OpenClaw, gdy - chcesz trwałej pamięci, dostępu z wielu urządzeń i orkiestracji narzędzi. + + OpenClaw jest **osobistym asystentem** i warstwą koordynacji, a nie zamiennikiem IDE. Używaj + Claude Code lub Codex do najszybszej bezpośredniej pętli kodowania w repozytorium. Używaj OpenClaw, gdy + chcesz trwałej pamięci, dostępu między urządzeniami i orkiestracji narzędzi. Zalety: - **Trwała pamięć + workspace** między sesjami - **Dostęp wieloplatformowy** (WhatsApp, Telegram, TUI, WebChat) - - **Orkiestracja narzędzi** (przeglądarka, pliki, harmonogram, hooks) - - **Gateway zawsze włączony** (uruchamiasz na VPS, wchodzisz z dowolnego miejsca) - - **Nodes** dla lokalnej przeglądarki/ekranu/kamery/exec + - **Orkiestracja narzędzi** (przeglądarka, pliki, harmonogramy, hooki) + - **Gateway zawsze włączony** (uruchamiaj na VPS i korzystaj skądkolwiek) + - **Nodes** do lokalnej przeglądarki/ekranu/kamery/exec Prezentacja: [https://openclaw.ai/showcase](https://openclaw.ai/showcase) @@ -1003,69 +1003,69 @@ pod kątem użycia/rozliczeń i w razie potrzeby zwiększ limity. ## Skills i automatyzacja - - Używaj zarządzanych override’ów zamiast edytować kopię w repo. Umieść swoje zmiany w `~/.openclaw/skills//SKILL.md` (lub dodaj folder przez `skills.load.extraDirs` w `~/.openclaw/openclaw.json`). Priorytet to `/skills` → `/.agents/skills` → `~/.agents/skills` → `~/.openclaw/skills` → bundled → `skills.load.extraDirs`, więc zarządzane override’y nadal wygrywają z bundlowanymi Skills bez dotykania gita. Jeśli Skill ma być zainstalowany globalnie, ale widoczny tylko dla niektórych agentów, trzymaj współdzieloną kopię w `~/.openclaw/skills` i steruj widocznością przez `agents.defaults.skills` i `agents.list[].skills`. Tylko zmiany warte upstreamu powinny trafiać do repo i wychodzić jako PR. + + Używaj zarządzanych override'ów zamiast edytować kopię w repozytorium. Umieść zmiany w `~/.openclaw/skills//SKILL.md` (albo dodaj folder przez `skills.load.extraDirs` w `~/.openclaw/openclaw.json`). Priorytet to `/skills` → `/.agents/skills` → `~/.agents/skills` → `~/.openclaw/skills` → bundlowane → `skills.load.extraDirs`, więc zarządzane override'y nadal wygrywają z bundlowanymi Skills bez dotykania gita. Jeśli potrzebujesz, aby skill był zainstalowany globalnie, ale widoczny tylko dla niektórych agentów, trzymaj współdzieloną kopię w `~/.openclaw/skills` i kontroluj widoczność przez `agents.defaults.skills` i `agents.list[].skills`. Tylko zmiany warte upstreamu powinny trafiać do repozytorium i wychodzić jako PR. - Tak. Dodaj dodatkowe katalogi przez `skills.load.extraDirs` w `~/.openclaw/openclaw.json` (najniższy priorytet). Domyślny priorytet to `/skills` → `/.agents/skills` → `~/.agents/skills` → `~/.openclaw/skills` → bundled → `skills.load.extraDirs`. `clawhub` instaluje domyślnie do `./skills`, które OpenClaw traktuje jako `/skills` w następnej sesji. Jeśli Skill ma być widoczny tylko dla wybranych agentów, połącz to z `agents.defaults.skills` lub `agents.list[].skills`. + Tak. Dodaj dodatkowe katalogi przez `skills.load.extraDirs` w `~/.openclaw/openclaw.json` (najniższy priorytet). Domyślny priorytet to `/skills` → `/.agents/skills` → `~/.agents/skills` → `~/.openclaw/skills` → bundlowane → `skills.load.extraDirs`. `clawhub` domyślnie instaluje do `./skills`, co OpenClaw traktuje jako `/skills` przy następnej sesji. Jeśli skill ma być widoczny tylko dla określonych agentów, połącz to z `agents.defaults.skills` albo `agents.list[].skills`. Obecnie obsługiwane wzorce to: - - **Cron jobs**: odizolowane zadania mogą ustawić override `model` per zadanie. - - **Sub-agents**: kieruj zadania do oddzielnych agentów z różnymi modelami domyślnymi. + - **Zadania cron**: izolowane zadania mogą ustawiać override `model` per zadanie. + - **Sub-agenci**: kieruj zadania do osobnych agentów z różnymi modelami domyślnymi. - **Przełączanie na żądanie**: użyj `/model`, aby w każdej chwili przełączyć model bieżącej sesji. - Zobacz [Cron jobs](/pl/automation/cron-jobs), [Multi-Agent Routing](/pl/concepts/multi-agent) i [Polecenia slash](/pl/tools/slash-commands). + Zobacz [Zadania cron](/pl/automation/cron-jobs), [Routing wielu agentów](/pl/concepts/multi-agent) i [Slash commands](/pl/tools/slash-commands). - - Użyj **sub-agentów** do długich lub równoległych zadań. Sub-agenci działają we własnej sesji, + + Używaj **sub agentów** do długich lub równoległych zadań. Sub-agenci działają we własnej sesji, zwracają podsumowanie i utrzymują responsywność głównego czatu. - Poproś bota, aby „utworzył subagenta do tego zadania” albo użyj `/subagents`. + Poproś bota o „spawn a sub-agent for this task” albo użyj `/subagents`. Użyj `/status` na czacie, aby zobaczyć, co Gateway robi teraz (i czy jest zajęty). - Wskazówka dotycząca tokenów: długie zadania i subagenci zużywają tokeny. Jeśli koszt jest problemem, ustaw - tańszy model dla subagentów przez `agents.defaults.subagents.model`. + Wskazówka dotycząca tokenów: długie zadania i sub-agenci oba zużywają tokeny. Jeśli koszty są problemem, ustaw + tańszy model dla sub agentów przez `agents.defaults.subagents.model`. - Dokumentacja: [Sub-agents](/pl/tools/subagents), [Background Tasks](/pl/automation/tasks). + Dokumentacja: [Sub-agenci](/pl/tools/subagents), [Zadania w tle](/pl/automation/tasks). - - Używaj powiązań wątków. Możesz powiązać wątek Discord z subagentem lub celem sesji, aby kolejne wiadomości w tym wątku pozostawały w tej powiązanej sesji. + + Używaj powiązań wątków. Możesz powiązać wątek Discord z celem subagenta albo sesji, aby kolejne wiadomości w tym wątku pozostawały przy tej powiązanej sesji. Podstawowy przepływ: - - Uruchom przez `sessions_spawn` z `thread: true` (i opcjonalnie `mode: "session"` dla trwałych kolejnych wiadomości). - - Albo powiąż ręcznie przez `/focus `. + - Uruchom przez `sessions_spawn` z `thread: true` (oraz opcjonalnie `mode: "session"` dla trwałego dalszego ciągu). + - Albo ręcznie powiąż przez `/focus `. - Użyj `/agents`, aby sprawdzić stan powiązania. - - Użyj `/session idle ` i `/session max-age `, aby sterować automatycznym odwiązywaniem. + - Użyj `/session idle ` i `/session max-age `, aby kontrolować automatyczne odwiązanie. - Użyj `/unfocus`, aby odłączyć wątek. Wymagana konfiguracja: - - Domyślne globalne: `session.threadBindings.enabled`, `session.threadBindings.idleHours`, `session.threadBindings.maxAgeHours`. - - Override’y Discord: `channels.discord.threadBindings.enabled`, `channels.discord.threadBindings.idleHours`, `channels.discord.threadBindings.maxAgeHours`. - - Automatyczne wiązanie przy spawn: ustaw `channels.discord.threadBindings.spawnSubagentSessions: true`. + - Globalne ustawienia domyślne: `session.threadBindings.enabled`, `session.threadBindings.idleHours`, `session.threadBindings.maxAgeHours`. + - Nadpisania dla Discorda: `channels.discord.threadBindings.enabled`, `channels.discord.threadBindings.idleHours`, `channels.discord.threadBindings.maxAgeHours`. + - Automatyczne powiązanie przy spawn: ustaw `channels.discord.threadBindings.spawnSubagentSessions: true`. - Dokumentacja: [Sub-agents](/pl/tools/subagents), [Discord](/pl/channels/discord), [Configuration Reference](/pl/gateway/configuration-reference), [Polecenia slash](/pl/tools/slash-commands). + Dokumentacja: [Sub-agenci](/pl/tools/subagents), [Discord](/pl/channels/discord), [Opis konfiguracji](/pl/gateway/configuration-reference), [Slash commands](/pl/tools/slash-commands). - + Najpierw sprawdź rozwiązaną trasę requestera: - - Dostarczanie completion-mode subagent preferuje każdy powiązany wątek lub trasę rozmowy, jeśli taka istnieje. - - Jeśli origin ukończenia niesie tylko kanał, OpenClaw wraca do zapisanej trasy sesji requestera (`lastChannel` / `lastTo` / `lastAccountId`), aby bezpośrednie dostarczenie nadal mogło się udać. - - Jeśli nie istnieje ani powiązana trasa, ani użyteczna zapisana trasa, bezpośrednie dostarczenie może się nie udać, a wynik wraca do kolejki dostarczenia sesji zamiast zostać opublikowany od razu na czacie. - - Nieprawidłowe lub nieaktualne cele mogą nadal wymusić fallback do kolejki lub ostateczną porażkę dostarczenia. - - Jeśli ostatnia widoczna odpowiedź asystenta dziecka to dokładnie cichy token `NO_REPLY` / `no_reply` albo dokładnie `ANNOUNCE_SKIP`, OpenClaw celowo tłumi ogłoszenie zamiast publikować starszy, nieaktualny postęp. - - Jeśli dziecko przekroczyło timeout po samych wywołaniach narzędzi, ogłoszenie może zwinąć to do krótkiego podsumowania częściowego postępu zamiast odtwarzać surowe wyniki narzędzi. + - Dostarczanie completion-mode subagenta preferuje każdy powiązany wątek lub trasę rozmowy, jeśli istnieje. + - Jeśli źródło ukończenia zawiera tylko kanał, OpenClaw wraca do zapisanej trasy sesji requestera (`lastChannel` / `lastTo` / `lastAccountId`), aby bezpośrednie dostarczenie nadal mogło się udać. + - Jeśli nie istnieje ani powiązana trasa, ani użyteczna zapisana trasa, bezpośrednie dostarczenie może się nie udać i wynik wraca do kolejkowanego dostarczania sesji zamiast natychmiastowej publikacji na czacie. + - Nieprawidłowe albo przestarzałe cele nadal mogą wymusić fallback do kolejki albo ostateczną porażkę dostarczenia. + - Jeśli ostatnia widoczna odpowiedź asystenta dziecka to dokładnie cichy token `NO_REPLY` / `no_reply` albo dokładnie `ANNOUNCE_SKIP`, OpenClaw celowo tłumi ogłoszenie zamiast publikować przestarzały wcześniejszy postęp. + - Jeśli dziecko przekroczyło timeout po samych wywołaniach narzędzi, ogłoszenie może zwinąć to do krótkiego podsumowania częściowego postępu zamiast odtwarzać surowe wyjście narzędzi. Debugowanie: @@ -1073,19 +1073,19 @@ pod kątem użycia/rozliczeń i w razie potrzeby zwiększ limity. openclaw tasks show ``` - Dokumentacja: [Sub-agents](/pl/tools/subagents), [Background Tasks](/pl/automation/tasks), [Session Tools](/pl/concepts/session-tool). + Dokumentacja: [Sub-agenci](/pl/tools/subagents), [Zadania w tle](/pl/automation/tasks), [Narzędzie sesji](/pl/concepts/session-tool). - + Cron działa wewnątrz procesu Gateway. Jeśli Gateway nie działa bez przerwy, - zaplanowane zadania nie będą się uruchamiały. + zaplanowane zadania nie będą uruchamiane. Lista kontrolna: - - Potwierdź, że cron jest włączony (`cron.enabled`) i że `OPENCLAW_SKIP_CRON` nie jest ustawione. + - Potwierdź, że cron jest włączony (`cron.enabled`) i `OPENCLAW_SKIP_CRON` nie jest ustawione. - Sprawdź, czy Gateway działa 24/7 (bez uśpień/restartów). - - Zweryfikuj ustawienia strefy czasowej zadania (`--tz` vs strefa czasowa hosta). + - Zweryfikuj ustawienia strefy czasowej dla zadania (`--tz` vs strefa czasowa hosta). Debugowanie: @@ -1094,22 +1094,22 @@ pod kątem użycia/rozliczeń i w razie potrzeby zwiększ limity. openclaw cron runs --id --limit 50 ``` - Dokumentacja: [Cron jobs](/pl/automation/cron-jobs), [Automation & Tasks](/pl/automation). + Dokumentacja: [Zadania cron](/pl/automation/cron-jobs), [Automatyzacja i zadania](/pl/automation). - + Najpierw sprawdź tryb dostarczania: - - `--no-deliver` / `delivery.mode: "none"` oznacza, że nie oczekuje się żadnej zewnętrznej wiadomości. - - Brakujący lub nieprawidłowy cel ogłoszenia (`channel` / `to`) oznacza, że runner pominął dostarczanie wychodzące. - - Błędy auth kanału (`unauthorized`, `Forbidden`) oznaczają, że runner próbował dostarczyć, ale poświadczenia to zablokowały. - - Cichy odizolowany wynik (`NO_REPLY` / `no_reply` tylko) jest traktowany jako celowo nienadający się do dostarczenia, więc runner tłumi też fallback do dostarczania z kolejki. + - `--no-deliver` / `delivery.mode: "none"` oznacza, że nie należy oczekiwać zewnętrznej wiadomości. + - Brakujący albo nieprawidłowy cel ogłoszenia (`channel` / `to`) oznacza, że runner pominął dostarczanie wychodzące. + - Błędy uwierzytelniania kanału (`unauthorized`, `Forbidden`) oznaczają, że runner próbował dostarczyć wiadomość, ale poświadczenia to zablokowały. + - Cichy izolowany wynik (`NO_REPLY` / `no_reply` tylko) jest traktowany jako celowo nienadający się do dostarczenia, więc runner tłumi też kolejkowany fallback dostarczania. - W przypadku odizolowanych cron jobs runner zarządza końcowym dostarczeniem. Oczekuje się, że agent - zwróci zwykłe podsumowanie tekstowe do wysłania przez runner. `--no-deliver` zachowuje - ten wynik wewnętrznie; nie pozwala agentowi wysłać go bezpośrednio narzędziem - message. + W przypadku izolowanych zadań cron to runner zarządza końcowym dostarczeniem. Od agenta oczekuje się + zwrócenia zwykłego tekstowego podsumowania, które runner wyśle. `--no-deliver` zatrzymuje + ten wynik wewnętrznie; nie pozwala agentowi wysłać go bezpośrednio za pomocą + narzędzia message. Debugowanie: @@ -1118,27 +1118,27 @@ pod kątem użycia/rozliczeń i w razie potrzeby zwiększ limity. openclaw tasks show ``` - Dokumentacja: [Cron jobs](/pl/automation/cron-jobs), [Background Tasks](/pl/automation/tasks). + Dokumentacja: [Zadania cron](/pl/automation/cron-jobs), [Zadania w tle](/pl/automation/tasks). - - Zwykle jest to ścieżka live model-switch, a nie podwójne planowanie. + + Zwykle jest to ścieżka przełączania żywego modelu, a nie podwójne planowanie. - Odizolowany cron może zapisać runtime handoff modelu i ponowić próbę, gdy aktywne - uruchomienie rzuci `LiveSessionModelSwitchError`. Retry zachowuje przełączonego - dostawcę/model, a jeśli przełączenie niosło nowy override profilu auth, cron - też go zapisuje przed retry. + Izolowany cron może utrwalić przekazanie modelu w trakcie działania i ponowić próbę, gdy aktywne + uruchomienie rzuci `LiveSessionModelSwitchError`. Ponowienie zachowuje przełączonego + providera/model, a jeśli przełączenie zawierało nowe override profilu uwierzytelniania, cron + utrwala to również przed ponowną próbą. - Powiązane zasady wyboru: + Powiązane reguły wyboru: - - Override modelu Gmail hook wygrywa jako pierwszy, gdy ma zastosowanie. - - Następnie `model` per job. - - Następnie dowolny zapisany override modelu sesji cron. + - Override modelu hooka Gmail wygrywa jako pierwszy, gdy ma zastosowanie. + - Następnie per-zadanie `model`. + - Potem każdy zapisany override modelu sesji cron. - Następnie normalny wybór modelu domyślnego/agenta. - Pętla retry jest ograniczona. Po początkowej próbie plus 2 retry przełączenia modelu - cron przerywa zamiast zapętlać się w nieskończoność. + Pętla ponawiania jest ograniczona. Po pierwszej próbie plus 2 ponowieniach przełączenia, + cron przerywa zamiast zapętlać się bez końca. Debugowanie: @@ -1147,12 +1147,12 @@ pod kątem użycia/rozliczeń i w razie potrzeby zwiększ limity. openclaw tasks show ``` - Dokumentacja: [Cron jobs](/pl/automation/cron-jobs), [cron CLI](/cli/cron). + Dokumentacja: [Zadania cron](/pl/automation/cron-jobs), [cron CLI](/cli/cron). - Używaj natywnych poleceń `openclaw skills` albo wrzucaj Skills do swojego workspace. Interfejs Skills dla macOS nie jest dostępny na Linuxie. + Używaj natywnych poleceń `openclaw skills` albo wrzucaj Skills do workspace. Interfejs Skills UI dla macOS nie jest dostępny na Linuxie. Przeglądaj Skills na [https://clawhub.ai](https://clawhub.ai). ```bash @@ -1166,40 +1166,41 @@ pod kątem użycia/rozliczeń i w razie potrzeby zwiększ limity. openclaw skills check ``` - Natywne `openclaw skills install` zapisuje do katalogu `skills/` w aktywnym workspace. - Osobny CLI `clawhub` instaluj tylko wtedy, gdy chcesz publikować albo - synchronizować własne Skills. Dla współdzielonych instalacji między agentami umieść Skill w `~/.openclaw/skills` i użyj `agents.defaults.skills` lub - `agents.list[].skills`, jeśli chcesz zawęzić, którzy agenci mogą go widzieć. + Natywne `openclaw skills install` zapisuje do aktywnego katalogu `skills/` + w workspace. Osobne CLI `clawhub` instaluj tylko wtedy, gdy chcesz publikować albo + synchronizować własne Skills. W przypadku instalacji współdzielonych między agentami umieść skill pod + `~/.openclaw/skills` i użyj `agents.defaults.skills` albo + `agents.list[].skills`, jeśli chcesz ograniczyć, którzy agenci go widzą. - - Tak. Użyj schedulera Gateway: + + Tak. Użyj harmonogramu Gateway: - - **Cron jobs** dla zadań zaplanowanych lub cyklicznych (utrzymują się po restartach). + - **Zadania cron** dla zadań zaplanowanych lub cyklicznych (utrwalane po restartach). - **Heartbeat** dla okresowych kontroli „głównej sesji”. - - **Isolated jobs** dla autonomicznych agentów, którzy publikują podsumowania lub dostarczają je do czatów. + - **Zadania izolowane** dla autonomicznych agentów, które publikują podsumowania albo dostarczają je do czatów. - Dokumentacja: [Cron jobs](/pl/automation/cron-jobs), [Automation & Tasks](/pl/automation), + Dokumentacja: [Zadania cron](/pl/automation/cron-jobs), [Automatyzacja i zadania](/pl/automation), [Heartbeat](/pl/gateway/heartbeat). - - Nie bezpośrednio. Skills macOS są ograniczane przez `metadata.openclaw.os` oraz wymagane binaria, a Skills pojawiają się w system prompcie tylko wtedy, gdy kwalifikują się na **hoście Gateway**. Na Linuxie Skills tylko dla `darwin` (jak `apple-notes`, `apple-reminders`, `things-mac`) nie będą się ładować, chyba że nadpiszesz gating. + + Nie bezpośrednio. Skills dla macOS są ograniczane przez `metadata.openclaw.os` oraz wymagane binarki, a Skills pojawiają się w promcie systemowym tylko wtedy, gdy kwalifikują się na **hoście Gatewaya**. Na Linuxie Skills tylko dla `darwin` (takie jak `apple-notes`, `apple-reminders`, `things-mac`) nie będą ładowane, chyba że nadpiszesz bramkowanie. - Istnieją trzy obsługiwane wzorce: + Masz trzy wspierane wzorce: - **Opcja A — uruchom Gateway na Macu (najprościej).** - Uruchom Gateway tam, gdzie istnieją binaria macOS, a następnie łącz się z Linuxa w [trybie zdalnym](#gateway-ports-already-running-and-remote-mode) albo przez Tailscale. Skills ładują się normalnie, ponieważ host Gateway to macOS. + **Opcja A - uruchom Gateway na Macu (najprościej).** + Uruchamiaj Gateway tam, gdzie istnieją binarki macOS, a następnie łącz się z Linuksa w [trybie zdalnym](#gateway-ports-already-running-and-remote-mode) lub przez Tailscale. Skills ładują się normalnie, ponieważ host Gatewaya to macOS. - **Opcja B — użyj node macOS (bez SSH).** - Uruchom Gateway na Linuxie, sparuj node macOS (aplikacja menubar) i ustaw **Node Run Commands** na „Always Ask” albo „Always Allow” na Macu. OpenClaw może traktować Skills tylko dla macOS jako kwalifikujące się, gdy wymagane binaria istnieją na node. Agent uruchamia te Skills przez narzędzie `nodes`. Jeśli wybierzesz „Always Ask”, zatwierdzenie „Always Allow” w promcie dodaje to polecenie do allowlist. + **Opcja B - użyj node macOS (bez SSH).** + Uruchamiaj Gateway na Linuxie, sparuj node macOS (aplikacja w pasku menu) i ustaw **Node Run Commands** na „Always Ask” lub „Always Allow” na Macu. OpenClaw może traktować Skills tylko dla macOS jako kwalifikujące się, gdy wymagane binarki istnieją na node. Agent uruchamia te Skills przez narzędzie `nodes`. Jeśli wybierzesz „Always Ask”, zatwierdzenie „Always Allow” w monicie doda to polecenie do allowlisty. - **Opcja C — proxy binariów macOS przez SSH (zaawansowane).** - Zachowaj Gateway na Linuxie, ale spraw, aby wymagane binaria CLI były rozwiązywane do wrapperów SSH uruchamianych na Macu. Następnie nadpisz Skill, by dopuścić Linux, tak aby nadal się kwalifikował. + **Opcja C - proxy binarek macOS przez SSH (zaawansowane).** + Trzymaj Gateway na Linuxie, ale spraw, aby wymagane binarki CLI były rozwiązywane do wrapperów SSH uruchamianych na Macu. Następnie nadpisz skill tak, aby dopuszczał Linux, dzięki czemu pozostanie kwalifikujący się. - 1. Utwórz wrapper SSH dla binarnego pliku (przykład: `memo` dla Apple Notes): + 1. Utwórz wrapper SSH dla binarki (przykład: `memo` dla Apple Notes): ```bash #!/usr/bin/env bash @@ -1207,8 +1208,8 @@ pod kątem użycia/rozliczeń i w razie potrzeby zwiększ limity. exec ssh -T user@mac-host /opt/homebrew/bin/memo "$@" ``` - 2. Umieść wrapper na `PATH` na hoście Linux (na przykład `~/bin/memo`). - 3. Nadpisz metadane Skill (workspace lub `~/.openclaw/skills`), aby dopuścić Linux: + 2. Umieść wrapper w `PATH` na hoście Linux (na przykład `~/bin/memo`). + 3. Nadpisz metadane skilla (workspace albo `~/.openclaw/skills`), aby dopuścić Linux: ```markdown --- @@ -1218,25 +1219,25 @@ pod kątem użycia/rozliczeń i w razie potrzeby zwiększ limity. --- ``` - 4. Rozpocznij nową sesję, aby odświeżyć snapshot Skills. + 4. Rozpocznij nową sesję, aby odświeżyć migawkę Skills. - Obecnie nie jako wbudowaną funkcję. + Na dziś nie jest wbudowana. Opcje: - - **Własny Skill / plugin:** najlepsze do niezawodnego dostępu do API (Notion/HeyGen mają API). + - **Własny skill / plugin:** najlepszy dla niezawodnego dostępu do API (zarówno Notion, jak i HeyGen mają API). - **Automatyzacja przeglądarki:** działa bez kodu, ale jest wolniejsza i bardziej krucha. - Jeśli chcesz utrzymywać kontekst per klient (przepływy agencyjne), prosty wzorzec to: + Jeśli chcesz utrzymywać kontekst per klient (przepływy agencyjne), prosty wzorzec jest taki: - Jedna strona Notion na klienta (kontekst + preferencje + aktywna praca). - - Poproś agenta, aby pobierał tę stronę na początku sesji. + - Poproś agenta, aby pobrał tę stronę na początku sesji. - Jeśli chcesz natywnej integracji, otwórz prośbę o funkcję albo zbuduj Skill - korzystający z tych API. + Jeśli chcesz natywnej integracji, otwórz feature request albo zbuduj skill + celujący w te API. Instalacja Skills: @@ -1245,12 +1246,12 @@ pod kątem użycia/rozliczeń i w razie potrzeby zwiększ limity. openclaw skills update --all ``` - Instalacje natywne trafiają do katalogu `skills/` aktywnego workspace. Dla współdzielonych Skills między agentami umieść je w `~/.openclaw/skills//SKILL.md`. Jeśli wspólna instalacja ma być widoczna tylko dla niektórych agentów, skonfiguruj `agents.defaults.skills` lub `agents.list[].skills`. Niektóre Skills oczekują binariów zainstalowanych przez Homebrew; na Linuxie oznacza to Linuxbrew (zobacz wpis FAQ o Homebrew na Linuxie powyżej). Zobacz [Skills](/pl/tools/skills), [Skills config](/pl/tools/skills-config) i [ClawHub](/pl/tools/clawhub). + Natywne instalacje trafiają do aktywnego katalogu `skills/` w workspace. Dla współdzielonych Skills między agentami umieść je w `~/.openclaw/skills//SKILL.md`. Jeśli tylko niektórzy agenci mają widzieć współdzieloną instalację, skonfiguruj `agents.defaults.skills` albo `agents.list[].skills`. Niektóre Skills oczekują binarek instalowanych przez Homebrew; na Linuxie oznacza to Linuxbrew (zobacz wpis FAQ o Homebrew na Linuxie powyżej). Zobacz [Skills](/pl/tools/skills), [Konfiguracja Skills](/pl/tools/skills-config) i [ClawHub](/pl/tools/clawhub). - - Użyj wbudowanego profilu przeglądarki `user`, który łączy się przez Chrome DevTools MCP: + + Użyj wbudowanego profilu przeglądarki `user`, który dołącza się przez Chrome DevTools MCP: ```bash openclaw browser --browser-profile user tabs @@ -1264,12 +1265,12 @@ pod kątem użycia/rozliczeń i w razie potrzeby zwiększ limity. openclaw browser --browser-profile chrome-live tabs ``` - Ta ścieżka jest lokalna dla hosta. Jeśli Gateway działa gdzie indziej, albo uruchom host node na maszynie z przeglądarką, albo użyj zdalnego CDP. + Ta ścieżka jest lokalna dla hosta. Jeśli Gateway działa gdzie indziej, uruchom hosta node na maszynie z przeglądarką albo użyj zdalnego CDP. Obecne ograniczenia `existing-session` / `user`: - - akcje są oparte na ref, a nie selektorach CSS - - uploady wymagają `ref` / `inputRef` i obecnie obsługują jeden plik naraz + - akcje są oparte na refach, a nie selektorach CSS + - uploady wymagają `ref` / `inputRef` i obecnie obsługują tylko jeden plik naraz - `responsebody`, eksport PDF, przechwytywanie pobrań i akcje wsadowe nadal wymagają zarządzanej przeglądarki albo surowego profilu CDP @@ -1278,97 +1279,97 @@ pod kątem użycia/rozliczeń i w razie potrzeby zwiększ limity. ## Sandbox i pamięć - + Tak. Zobacz [Sandboxing](/pl/gateway/sandboxing). Dla konfiguracji specyficznej dla Dockera (pełny gateway w Dockerze albo obrazy sandbox) zobacz [Docker](/pl/install/docker). - + Domyślny obraz stawia bezpieczeństwo na pierwszym miejscu i działa jako użytkownik `node`, więc nie zawiera pakietów systemowych, Homebrew ani bundlowanych przeglądarek. Dla pełniejszej konfiguracji: - - Zachowaj `/home/node` przez `OPENCLAW_HOME_VOLUME`, aby cache przetrwał. - - Wbuduj zależności systemowe do obrazu przez `OPENCLAW_DOCKER_APT_PACKAGES`. + - Utrwal `/home/node` za pomocą `OPENCLAW_HOME_VOLUME`, aby cache przetrwały. + - Wypiecz zależności systemowe do obrazu za pomocą `OPENCLAW_DOCKER_APT_PACKAGES`. - Zainstaluj przeglądarki Playwright przez bundlowane CLI: `node /app/node_modules/playwright-core/cli.js install chromium` - - Ustaw `PLAYWRIGHT_BROWSERS_PATH` i upewnij się, że ścieżka jest trwała. + - Ustaw `PLAYWRIGHT_BROWSERS_PATH` i upewnij się, że ta ścieżka jest utrwalana. - Dokumentacja: [Docker](/pl/install/docker), [Browser](/pl/tools/browser). + Dokumentacja: [Docker](/pl/install/docker), [Przeglądarka](/pl/tools/browser). - - Tak — jeśli prywatny ruch to **DM**, a publiczny ruch to **grupy**. + + Tak — jeśli Twój ruch prywatny to **DM-y**, a publiczny to **grupy**. - Użyj `agents.defaults.sandbox.mode: "non-main"`, aby sesje grup/kanałów (klucze inne niż main) działały w Dockerze, a główna sesja DM pozostawała na hoście. Następnie ogranicz, które narzędzia są dostępne w sesjach sandboxowanych przez `tools.sandbox.tools`. + Użyj `agents.defaults.sandbox.mode: "non-main"`, aby sesje grupowe/kanałowe (klucze non-main) działały w Dockerze, podczas gdy główna sesja DM pozostaje na hoście. Następnie ogranicz dostępne narzędzia w sandboxowanych sesjach przez `tools.sandbox.tools`. - Przewodnik konfiguracji + przykładowy config: [Groups: personal DMs + public groups](/pl/channels/groups#pattern-personal-dms-public-groups-single-agent) + Przewodnik konfiguracji + przykładowa konfiguracja: [Grupy: prywatne DM-y + publiczne grupy](/pl/channels/groups#pattern-personal-dms-public-groups-single-agent) - Kluczowe odniesienie do konfiguracji: [Gateway configuration](/pl/gateway/configuration-reference#agentsdefaultssandbox) + Kluczowy opis konfiguracji: [Konfiguracja Gatewaya](/pl/gateway/configuration-reference#agentsdefaultssandbox) - - Ustaw `agents.defaults.sandbox.docker.binds` na `["host:path:mode"]` (np. `"/home/user/src:/src:ro"`). Globalne bindy i bindy per agent są scalane; bindy per agent są ignorowane, gdy `scope: "shared"`. Używaj `:ro` dla wszystkiego, co wrażliwe, i pamiętaj, że bindy omijają ściany systemu plików sandboxu. + + Ustaw `agents.defaults.sandbox.docker.binds` na `["host:path:mode"]` (np. `"/home/user/src:/src:ro"`). Globalne + per-agent bindy scalają się; bindy per-agent są ignorowane, gdy `scope: "shared"`. Używaj `:ro` dla wszystkiego, co wrażliwe, i pamiętaj, że bindy omijają granice systemu plików sandboxa. - OpenClaw waliduje źródła bind zarówno względem ścieżki znormalizowanej, jak i kanonicznej ścieżki rozwiązywanej przez najgłębszego istniejącego przodka. Oznacza to, że ucieczki przez rodzica będącego symlinkiem nadal kończą się fail closed, nawet gdy ostatni segment ścieżki jeszcze nie istnieje, a kontrole dozwolonych rootów nadal mają zastosowanie po rozwiązaniu symlinków. + OpenClaw sprawdza źródła bind względem zarówno znormalizowanej ścieżki, jak i ścieżki kanonicznej rozwiązywanej przez najgłębszego istniejącego przodka. To oznacza, że ucieczki przez symlink-parent nadal kończą się bezpiecznym zamknięciem, nawet gdy ostatni segment ścieżki jeszcze nie istnieje, a kontrole dozwolonego root nadal obowiązują po rozwiązaniu symlinków. - Zobacz [Sandboxing](/pl/gateway/sandboxing#custom-bind-mounts) i [Sandbox vs Tool Policy vs Elevated](/pl/gateway/sandbox-vs-tool-policy-vs-elevated#bind-mounts-security-quick-check), aby poznać przykłady i uwagi o bezpieczeństwie. + Zobacz [Sandboxing](/pl/gateway/sandboxing#custom-bind-mounts) i [Sandbox vs Tool Policy vs Elevated](/pl/gateway/sandbox-vs-tool-policy-vs-elevated#bind-mounts-security-quick-check), aby poznać przykłady i uwagi dotyczące bezpieczeństwa. Pamięć OpenClaw to po prostu pliki Markdown w workspace agenta: - - Notatki dzienne w `memory/YYYY-MM-DD.md` - - Kuratorowane notatki długoterminowe w `MEMORY.md` (tylko sesje main/prywatne) + - Dzienne notatki w `memory/YYYY-MM-DD.md` + - Wyselekcjonowane notatki długoterminowe w `MEMORY.md` (tylko sesje główne/prywatne) - OpenClaw uruchamia też **cichy flush pamięci przed kompaktowaniem**, aby przypomnieć modelowi - o zapisaniu trwałych notatek przed automatycznym kompaktowaniem. To działa tylko wtedy, gdy workspace - jest zapisywalny (sandboxy tylko do odczytu to pomijają). Zobacz [Memory](/pl/concepts/memory). + OpenClaw uruchamia też **ciche opróżnienie pamięci przed kompaktowaniem**, aby przypomnieć modelowi + o zapisaniu trwałych notatek przed automatycznym kompaktowaniem. Działa to tylko wtedy, gdy workspace + jest zapisywalny (sandboxy tylko do odczytu to pomijają). Zobacz [Pamięć](/pl/concepts/memory). - + Poproś bota, aby **zapisał fakt do pamięci**. Notatki długoterminowe powinny trafiać do `MEMORY.md`, - a krótkoterminowy kontekst do `memory/YYYY-MM-DD.md`. + a kontekst krótkoterminowy do `memory/YYYY-MM-DD.md`. - To wciąż obszar, który ulepszamy. Pomaga przypominanie modelowi, aby zapisywał wspomnienia; - będzie wiedział, co zrobić. Jeśli nadal zapomina, sprawdź, czy Gateway używa tego samego - workspace przy każdym uruchomieniu. + To nadal obszar, który ulepszamy. Pomaga przypominanie modelowi o zapisywaniu wspomnień; + będzie wiedział, co zrobić. Jeśli nadal zapomina, sprawdź, czy Gateway używa + tego samego workspace przy każdym uruchomieniu. - Dokumentacja: [Memory](/pl/concepts/memory), [Agent workspace](/pl/concepts/agent-workspace). + Dokumentacja: [Pamięć](/pl/concepts/memory), [Workspace agenta](/pl/concepts/agent-workspace). - - Pliki pamięci żyją na dysku i utrzymują się, dopóki ich nie usuniesz. Limitem jest - miejsce na dysku, a nie model. **Kontekst sesji** nadal jest ograniczony przez - okno kontekstu modelu, więc długie rozmowy mogą zostać skompaktowane lub przycięte. Dlatego - istnieje wyszukiwanie pamięci — przywraca do kontekstu tylko istotne fragmenty. + + Pliki pamięci znajdują się na dysku i utrzymują się, dopóki ich nie usuniesz. Limitem jest + miejsce na dysku, a nie model. **Kontekst sesji** nadal jest ograniczony oknem kontekstowym modelu, + więc długie rozmowy mogą zostać skompaktowane albo obcięte. Dlatego istnieje + wyszukiwanie w pamięci — przywraca do kontekstu tylko odpowiednie fragmenty. - Dokumentacja: [Memory](/pl/concepts/memory), [Context](/pl/concepts/context). + Dokumentacja: [Pamięć](/pl/concepts/memory), [Kontekst](/pl/concepts/context). - Tylko jeśli używasz **embeddingów OpenAI**. OAuth Codex obejmuje chat/completions i - **nie** daje dostępu do embeddingów, więc **logowanie przez Codex (OAuth lub login - Codex CLI)** nie pomaga przy semantycznym wyszukiwaniu pamięci. Embeddingi OpenAI - nadal wymagają prawdziwego klucza API (`OPENAI_API_KEY` lub `models.providers.openai.apiKey`). + Tylko jeśli używasz **embeddingów OpenAI**. Codex OAuth obejmuje chat/completions i + **nie** daje dostępu do embeddingów, więc **logowanie przez Codex (OAuth albo + logowanie Codex CLI)** nie pomaga w semantycznym wyszukiwaniu pamięci. Embeddingi OpenAI + nadal wymagają prawdziwego klucza API (`OPENAI_API_KEY` albo `models.providers.openai.apiKey`). - Jeśli nie ustawisz jawnie dostawcy, OpenClaw automatycznie wybierze dostawcę, gdy - uda się rozwiązać klucz API (profile auth, `models.providers.*.apiKey` albo zmienne env). - Preferuje OpenAI, jeśli uda się rozwiązać klucz OpenAI, w przeciwnym razie Gemini, potem Voyage, a potem Mistral. - Jeśli nie ma dostępnego zdalnego klucza, wyszukiwanie pamięci - pozostaje wyłączone, dopóki go nie skonfigurujesz. Jeśli masz skonfigurowaną i obecną ścieżkę do modelu lokalnego, OpenClaw - preferuje `local`. Ollama jest obsługiwane, gdy jawnie ustawisz + Jeśli nie ustawisz jawnie providera, OpenClaw automatycznie wybiera providera, kiedy + potrafi rozwiązać klucz API (profile uwierzytelniania, `models.providers.*.apiKey` albo zmienne środowiskowe). + Preferuje OpenAI, jeśli uda się rozwiązać klucz OpenAI, w przeciwnym razie Gemini, jeśli uda się rozwiązać klucz Gemini, + potem Voyage, a następnie Mistral. Jeśli żaden zdalny klucz nie jest dostępny, wyszukiwanie pamięci + pozostaje wyłączone, dopóki go nie skonfigurujesz. Jeśli masz skonfigurowaną i obecną ścieżkę lokalnego modelu, OpenClaw + preferuje `local`. Ollama jest wspierana, gdy jawnie ustawisz `memorySearch.provider = "ollama"`. Jeśli wolisz pozostać lokalnie, ustaw `memorySearch.provider = "local"` (i opcjonalnie - `memorySearch.fallback = "none"`). Jeśli chcesz embeddingi Gemini, ustaw - `memorySearch.provider = "gemini"` i podaj `GEMINI_API_KEY` (lub - `memorySearch.remote.apiKey`). Obsługujemy modele embeddingów **OpenAI, Gemini, Voyage, Mistral, Ollama lub local** — - szczegóły konfiguracji znajdziesz w [Memory](/pl/concepts/memory). + `memorySearch.fallback = "none"`). Jeśli chcesz embeddingów Gemini, ustaw + `memorySearch.provider = "gemini"` i podaj `GEMINI_API_KEY` (albo + `memorySearch.remote.apiKey`). Obsługujemy modele embeddingów **OpenAI, Gemini, Voyage, Mistral, Ollama lub local** + — szczegóły konfiguracji znajdziesz w [Pamięci](/pl/concepts/memory). @@ -1379,46 +1380,46 @@ pod kątem użycia/rozliczeń i w razie potrzeby zwiększ limity. Nie — **stan OpenClaw jest lokalny**, ale **zewnętrzne usługi nadal widzą to, co do nich wysyłasz**. - - **Lokalnie domyślnie:** sesje, pliki pamięci, config i workspace żyją na hoście Gateway - (`~/.openclaw` + Twój katalog workspace). - - **Zdalnie z konieczności:** wiadomości wysyłane do dostawców modeli (Anthropic/OpenAI itd.) trafiają do - ich API, a platformy czatu (WhatsApp/Telegram/Slack itd.) przechowują dane wiadomości na - swoich serwerach. - - **Ty kontrolujesz ślad:** użycie modeli lokalnych trzyma prompty na Twojej maszynie, ale ruch kanałowy + - **Lokalnie domyślnie:** sesje, pliki pamięci, konfiguracja i workspace znajdują się na hoście Gatewaya + (`~/.openclaw` + katalog workspace). + - **Zdalnie z konieczności:** wiadomości wysyłane do providerów modeli (Anthropic/OpenAI/etc.) trafiają do + ich API, a platformy czatowe (WhatsApp/Telegram/Slack/etc.) przechowują dane wiadomości na swoich + serwerach. + - **Ty kontrolujesz ślad:** używanie modeli lokalnych utrzymuje prompty na Twojej maszynie, ale ruch kanałowy nadal przechodzi przez serwery danego kanału. - Powiązane: [Agent workspace](/pl/concepts/agent-workspace), [Memory](/pl/concepts/memory). + Powiązane: [Workspace agenta](/pl/concepts/agent-workspace), [Pamięć](/pl/concepts/memory). Wszystko znajduje się pod `$OPENCLAW_STATE_DIR` (domyślnie: `~/.openclaw`): - | Path | Przeznaczenie | + | Path | Cel | | --------------------------------------------------------------- | ------------------------------------------------------------------ | - | `$OPENCLAW_STATE_DIR/openclaw.json` | Główny config (JSON5) | - | `$OPENCLAW_STATE_DIR/credentials/oauth.json` | Import legacy OAuth (kopiowany do profili auth przy pierwszym użyciu) | - | `$OPENCLAW_STATE_DIR/agents//agent/auth-profiles.json` | Profile auth (OAuth, klucze API i opcjonalne `keyRef`/`tokenRef`) | - | `$OPENCLAW_STATE_DIR/secrets.json` | Opcjonalny payload sekretu w pliku dla dostawców `file` SecretRef | - | `$OPENCLAW_STATE_DIR/agents//agent/auth.json` | Plik zgodności legacy (statyczne wpisy `api_key` są czyszczone) | - | `$OPENCLAW_STATE_DIR/credentials/` | Stan dostawcy (np. `whatsapp//creds.json`) | - | `$OPENCLAW_STATE_DIR/agents/` | Stan per agent (agentDir + sessions) | - | `$OPENCLAW_STATE_DIR/agents//sessions/` | Historia rozmów i stan (per agent) | + | `$OPENCLAW_STATE_DIR/openclaw.json` | Główna konfiguracja (JSON5) | + | `$OPENCLAW_STATE_DIR/credentials/oauth.json` | Starszy import OAuth (kopiowany do profili auth przy pierwszym użyciu) | + | `$OPENCLAW_STATE_DIR/agents//agent/auth-profiles.json` | Profile auth (OAuth, klucze API oraz opcjonalne `keyRef`/`tokenRef`) | + | `$OPENCLAW_STATE_DIR/secrets.json` | Opcjonalny ładunek sekretów oparty na plikach dla providerów `file` SecretRef | + | `$OPENCLAW_STATE_DIR/agents//agent/auth.json` | Starszy plik zgodności (statyczne wpisy `api_key` oczyszczone) | + | `$OPENCLAW_STATE_DIR/credentials/` | Stan providera (np. `whatsapp//creds.json`) | + | `$OPENCLAW_STATE_DIR/agents/` | Stan per agent (agentDir + sesje) | + | `$OPENCLAW_STATE_DIR/agents//sessions/` | Historia i stan rozmów (per agent) | | `$OPENCLAW_STATE_DIR/agents//sessions/sessions.json` | Metadane sesji (per agent) | - Ścieżka legacy dla pojedynczego agenta: `~/.openclaw/agent/*` (migrowana przez `openclaw doctor`). + Starsza ścieżka pojedynczego agenta: `~/.openclaw/agent/*` (migrowana przez `openclaw doctor`). - Twój **workspace** (`AGENTS.md`, pliki pamięci, Skills itd.) jest oddzielny i konfigurowany przez `agents.defaults.workspace` (domyślnie: `~/.openclaw/workspace`). + Twój **workspace** (AGENTS.md, pliki pamięci, Skills itp.) jest oddzielny i konfigurowany przez `agents.defaults.workspace` (domyślnie: `~/.openclaw/workspace`). Te pliki znajdują się w **workspace agenta**, a nie w `~/.openclaw`. - - **Workspace (per agent):** `AGENTS.md`, `SOUL.md`, `IDENTITY.md`, `USER.md`, - `MEMORY.md` (lub fallback legacy `memory.md`, gdy `MEMORY.md` nie istnieje), + - **Workspace (per agent)**: `AGENTS.md`, `SOUL.md`, `IDENTITY.md`, `USER.md`, + `MEMORY.md` (albo starszy fallback `memory.md`, gdy `MEMORY.md` nie istnieje), `memory/YYYY-MM-DD.md`, opcjonalnie `HEARTBEAT.md`. - - **State dir (`~/.openclaw`)**: config, stan kanału/dostawcy, profile auth, sesje, logi + - **State dir (`~/.openclaw`)**: konfiguracja, stan kanałów/providerów, profile auth, sesje, logi i współdzielone Skills (`~/.openclaw/skills`). Domyślny workspace to `~/.openclaw/workspace`, konfigurowalny przez: @@ -1430,43 +1431,43 @@ pod kątem użycia/rozliczeń i w razie potrzeby zwiększ limity. ``` Jeśli bot „zapomina” po restarcie, potwierdź, że Gateway używa tego samego - workspace przy każdym uruchomieniu (i pamiętaj: tryb zdalny używa workspace **hosta gateway**, + workspace przy każdym uruchomieniu (i pamiętaj: tryb zdalny używa **workspace hosta gatewaya**, a nie Twojego lokalnego laptopa). - Wskazówka: jeśli chcesz trwałego zachowania albo preferencji, poproś bota, aby **zapisał je do + Wskazówka: jeśli chcesz utrwalić zachowanie albo preferencję, poproś bota, aby **zapisał to do AGENTS.md albo MEMORY.md**, zamiast polegać na historii czatu. - Zobacz [Agent workspace](/pl/concepts/agent-workspace) i [Memory](/pl/concepts/memory). + Zobacz [Workspace agenta](/pl/concepts/agent-workspace) i [Pamięć](/pl/concepts/memory). - Umieść swój **workspace agenta** w **prywatnym** repo git i twórz jego kopię zapasową gdzieś - prywatnie (na przykład prywatny GitHub). To przechwytuje pamięć + pliki AGENTS/SOUL/USER + Umieść **workspace agenta** w **prywatnym** repozytorium git i twórz jego kopię zapasową w + prywatnym miejscu (na przykład GitHub private). To zapisuje pamięć + pliki AGENTS/SOUL/USER i pozwala później odtworzyć „umysł” asystenta. **Nie** commituj niczego z `~/.openclaw` (poświadczeń, sesji, tokenów ani zaszyfrowanych payloadów sekretów). - Jeśli potrzebujesz pełnego odtworzenia, twórz osobne kopie zapasowe workspace i katalogu stanu - (zobacz pytanie o migrację powyżej). + Jeśli potrzebujesz pełnego odtworzenia, twórz kopie zapasowe zarówno workspace, jak i katalogu stanu + osobno (zobacz pytanie o migrację powyżej). - Dokumentacja: [Agent workspace](/pl/concepts/agent-workspace). + Dokumentacja: [Workspace agenta](/pl/concepts/agent-workspace). - Zobacz osobny przewodnik: [Uninstall](/pl/install/uninstall). + Zobacz osobny przewodnik: [Odinstalowanie](/pl/install/uninstall). - + Tak. Workspace to **domyślny cwd** i kotwica pamięci, a nie twardy sandbox. - Ścieżki względne rozwiązują się wewnątrz workspace, ale ścieżki bezwzględne mogą uzyskiwać dostęp do innych - lokalizacji hosta, chyba że sandboxing jest włączony. Jeśli potrzebujesz izolacji, użyj - [`agents.defaults.sandbox`](/pl/gateway/sandboxing) albo ustawień sandbox per agent. Jeśli - chcesz, aby repo było domyślnym katalogiem roboczym, wskaż `workspace` - tego agenta na root repo. Repo OpenClaw to tylko kod źródłowy; trzymaj - workspace oddzielnie, chyba że celowo chcesz, aby agent pracował w nim. + Ścieżki względne rozwiązywane są wewnątrz workspace, ale ścieżki bezwzględne mogą uzyskać dostęp do innych + lokalizacji hosta, chyba że włączony jest sandboxing. Jeśli potrzebujesz izolacji, użyj + [`agents.defaults.sandbox`](/pl/gateway/sandboxing) albo ustawień sandbox per agent. Jeśli chcesz, + aby repozytorium było domyślnym katalogiem roboczym, wskaż w `workspace` + tego agenta katalog główny repozytorium. Repozytorium OpenClaw to tylko kod źródłowy; trzymaj + workspace osobno, chyba że celowo chcesz, aby agent pracował w nim. - Przykład (repo jako domyślny cwd): + Przykład (repozytorium jako domyślny cwd): ```json5 { @@ -1480,30 +1481,30 @@ pod kątem użycia/rozliczeń i w razie potrzeby zwiększ limity. - - Stan sesji należy do **hosta gateway**. Jeśli jesteś w trybie zdalnym, interesujący Cię magazyn sesji znajduje się na zdalnej maszynie, a nie na Twoim lokalnym laptopie. Zobacz [Session management](/pl/concepts/session). + + Właścicielem stanu sesji jest **host gatewaya**. Jeśli jesteś w trybie zdalnym, magazyn sesji, który Cię interesuje, znajduje się na zdalnej maszynie, a nie na Twoim lokalnym laptopie. Zobacz [Zarządzanie sesją](/pl/concepts/session). ## Podstawy konfiguracji - - OpenClaw odczytuje opcjonalny config **JSON5** z `$OPENCLAW_CONFIG_PATH` (domyślnie: `~/.openclaw/openclaw.json`): + + OpenClaw odczytuje opcjonalną konfigurację **JSON5** z `$OPENCLAW_CONFIG_PATH` (domyślnie: `~/.openclaw/openclaw.json`): ``` $OPENCLAW_CONFIG_PATH ``` - Jeśli plik nie istnieje, używane są dość bezpieczne wartości domyślne (w tym domyślny workspace `~/.openclaw/workspace`). + Jeśli pliku nie ma, używane są dość bezpieczne wartości domyślne (w tym domyślny workspace `~/.openclaw/workspace`). - Bindowanie bez loopback **wymaga poprawnej ścieżki gateway auth**. W praktyce oznacza to: + Bindowanie non-loopback **wymaga poprawnej ścieżki uwierzytelniania gatewaya**. W praktyce oznacza to: - - auth ze wspólnym sekretem: token lub hasło - - `gateway.auth.mode: "trusted-proxy"` za poprawnie skonfigurowanym non-loopback identity-aware reverse proxy + - uwierzytelnianie wspólnym sekretem: token albo hasło + - `gateway.auth.mode: "trusted-proxy"` za poprawnie skonfigurowanym reverse proxy świadomym tożsamości non-loopback ```json5 { @@ -1519,32 +1520,32 @@ pod kątem użycia/rozliczeń i w razie potrzeby zwiększ limity. Uwagi: - - `gateway.remote.token` / `.password` same w sobie **nie** włączają lokalnego gateway auth. + - `gateway.remote.token` / `.password` same z siebie **nie** włączają lokalnego uwierzytelniania gatewaya. - Lokalne ścieżki wywołań mogą używać `gateway.remote.*` jako fallback tylko wtedy, gdy `gateway.auth.*` nie jest ustawione. - - Dla auth hasłem ustaw `gateway.auth.mode: "password"` oraz `gateway.auth.password` (albo `OPENCLAW_GATEWAY_PASSWORD`). - - Jeśli `gateway.auth.token` / `gateway.auth.password` są jawnie skonfigurowane przez SecretRef i nierozwiązane, rozwiązywanie kończy się fail closed (bez maskującego fallbacku zdalnego). - - Konfiguracje Control UI ze wspólnym sekretem uwierzytelniają się przez `connect.params.auth.token` lub `connect.params.auth.password` (przechowywane w ustawieniach aplikacji/UI). Tryby przenoszące tożsamość, takie jak Tailscale Serve lub `trusted-proxy`, używają zamiast tego nagłówków żądania. Unikaj umieszczania wspólnych sekretów w URL. - - Przy `gateway.auth.mode: "trusted-proxy"` reverse proxy z loopback na tym samym hoście nadal **nie** spełnia trusted-proxy auth. Trusted proxy musi być skonfigurowanym źródłem bez loopback. + - Dla uwierzytelniania hasłem ustaw zamiast tego `gateway.auth.mode: "password"` oraz `gateway.auth.password` (albo `OPENCLAW_GATEWAY_PASSWORD`). + - Jeśli `gateway.auth.token` / `gateway.auth.password` są jawnie skonfigurowane przez SecretRef i nierozwiązane, rozwiązywanie kończy się bezpiecznym zamknięciem (bez maskującego zdalnego fallbacku). + - Konfiguracje Control UI ze wspólnym sekretem uwierzytelniają się przez `connect.params.auth.token` lub `connect.params.auth.password` (przechowywane w ustawieniach aplikacji/UI). Tryby przenoszące tożsamość, takie jak Tailscale Serve albo `trusted-proxy`, używają zamiast tego nagłówków żądań. Unikaj umieszczania wspólnych sekretów w URL. + - Przy `gateway.auth.mode: "trusted-proxy"` reverse proxy loopback na tym samym hoście nadal **nie** spełniają uwierzytelniania trusted-proxy. Zaufane proxy musi być skonfigurowanym źródłem non-loopback. - - OpenClaw wymusza gateway auth domyślnie, także dla loopback. W normalnej domyślnej ścieżce oznacza to auth tokenem: jeśli nie skonfigurowano jawnie ścieżki auth, start gateway przechodzi do trybu token i automatycznie go generuje, zapisując do `gateway.auth.token`, więc **lokalni klienci WS muszą się uwierzytelnić**. To blokuje innym lokalnym procesom wywoływanie Gateway. + + OpenClaw domyślnie wymusza uwierzytelnianie gatewaya, również na loopback. W normalnej domyślnej ścieżce oznacza to uwierzytelnianie tokenem: jeśli nie skonfigurowano jawnej ścieżki auth, podczas startu gateway rozwiązuje się to do trybu tokenu i automatycznie generuje token, zapisując go do `gateway.auth.token`, więc **lokalni klienci WS muszą się uwierzytelnić**. Blokuje to innym lokalnym procesom możliwość wywoływania Gatewaya. - Jeśli wolisz inną ścieżkę auth, możesz jawnie wybrać tryb hasła (lub, dla non-loopback identity-aware reverse proxy, `trusted-proxy`). Jeśli **naprawdę** chcesz otwarty loopback, ustaw jawnie `gateway.auth.mode: "none"` w configu. Doctor może wygenerować token w każdej chwili: `openclaw doctor --generate-gateway-token`. + Jeśli wolisz inną ścieżkę auth, możesz jawnie wybrać tryb hasła (lub, dla reverse proxy świadomych tożsamości non-loopback, `trusted-proxy`). Jeśli **naprawdę** chcesz otwartego loopback, ustaw jawnie `gateway.auth.mode: "none"` w konfiguracji. Doctor może w każdej chwili wygenerować Ci token: `openclaw doctor --generate-gateway-token`. - - Gateway obserwuje config i obsługuje hot-reload: + + Gateway obserwuje konfigurację i obsługuje hot-reload: - - `gateway.reload.mode: "hybrid"` (domyślnie): bezpieczne zmiany stosowane na gorąco, krytyczne wymagają restartu - - obsługiwane są także `hot`, `restart`, `off` + - `gateway.reload.mode: "hybrid"` (domyślnie): stosuje bezpieczne zmiany na gorąco, a dla krytycznych wykonuje restart + - obsługiwane są też `hot`, `restart`, `off` - - Ustaw `cli.banner.taglineMode` w configu: + + Ustaw `cli.banner.taglineMode` w konfiguracji: ```json5 { @@ -1556,33 +1557,33 @@ pod kątem użycia/rozliczeń i w razie potrzeby zwiększ limity. } ``` - - `off`: ukrywa tekst tagline, ale pozostawia tytuł banera/linię wersji. + - `off`: ukrywa tekst sloganu, ale zachowuje tytuł banera/linię wersji. - `default`: zawsze używa `All your chats, one OpenClaw.`. - - `random`: rotujące zabawne/sezonowe tagline (zachowanie domyślne). + - `random`: rotacyjne zabawne/sezonowe slogany (domyślne zachowanie). - Jeśli nie chcesz żadnego banera, ustaw env `OPENCLAW_HIDE_BANNER=1`. - + `web_fetch` działa bez klucza API. `web_search` zależy od wybranego - dostawcy: + providera: - - Dostawcy oparci o API, tacy jak Brave, Exa, Firecrawl, Gemini, Grok, Kimi, MiniMax Search, Perplexity i Tavily, wymagają zwykłej konfiguracji klucza API. + - Providerzy oparci na API, tacy jak Brave, Exa, Firecrawl, Gemini, Grok, Kimi, MiniMax Search, Perplexity i Tavily, wymagają normalnej konfiguracji klucza API. - Ollama Web Search nie wymaga klucza, ale używa skonfigurowanego hosta Ollama i wymaga `ollama signin`. - - DuckDuckGo nie wymaga klucza, ale jest to nieoficjalna integracja oparta na HTML. - - SearXNG nie wymaga klucza/jest self-hosted; skonfiguruj `SEARXNG_BASE_URL` albo `plugins.entries.searxng.config.webSearch.baseUrl`. + - DuckDuckGo nie wymaga klucza, ale jest nieoficjalną integracją opartą na HTML. + - SearXNG jest bezkluczowy/self-hosted; skonfiguruj `SEARXNG_BASE_URL` albo `plugins.entries.searxng.config.webSearch.baseUrl`. - **Zalecane:** uruchom `openclaw configure --section web` i wybierz dostawcę. - Alternatywy env: + **Zalecane:** uruchom `openclaw configure --section web` i wybierz providera. + Alternatywy w zmiennych środowiskowych: - Brave: `BRAVE_API_KEY` - Exa: `EXA_API_KEY` - Firecrawl: `FIRECRAWL_API_KEY` - Gemini: `GEMINI_API_KEY` - Grok: `XAI_API_KEY` - - Kimi: `KIMI_API_KEY` lub `MOONSHOT_API_KEY` - - MiniMax Search: `MINIMAX_CODE_PLAN_KEY`, `MINIMAX_CODING_API_KEY` lub `MINIMAX_API_KEY` - - Perplexity: `PERPLEXITY_API_KEY` lub `OPENROUTER_API_KEY` + - Kimi: `KIMI_API_KEY` albo `MOONSHOT_API_KEY` + - MiniMax Search: `MINIMAX_CODE_PLAN_KEY`, `MINIMAX_CODING_API_KEY` albo `MINIMAX_API_KEY` + - Perplexity: `PERPLEXITY_API_KEY` albo `OPENROUTER_API_KEY` - SearXNG: `SEARXNG_BASE_URL` - Tavily: `TAVILY_API_KEY` @@ -1608,65 +1609,65 @@ pod kątem użycia/rozliczeń i w razie potrzeby zwiększ limity. }, fetch: { enabled: true, - provider: "firecrawl", // opcjonalne; pomiń dla auto-detekcji + provider: "firecrawl", // opcjonalne; pomiń dla auto-detect }, }, }, } ``` - Konfiguracja web-search specyficzna dla dostawcy znajduje się teraz pod `plugins.entries..config.webSearch.*`. - Ścieżki dostawców legacy `tools.web.search.*` nadal tymczasowo się ładują dla zgodności, ale nie powinny być używane w nowych configach. + Konfiguracja wyszukiwania webowego specyficzna dla providera znajduje się teraz pod `plugins.entries..config.webSearch.*`. + Starsze ścieżki providera `tools.web.search.*` nadal tymczasowo się ładują ze względu na zgodność, ale nie powinny być używane w nowych konfiguracjach. Konfiguracja fallbacku Firecrawl web-fetch znajduje się pod `plugins.entries.firecrawl.config.webFetch.*`. Uwagi: - Jeśli używasz allowlist, dodaj `web_search`/`web_fetch`/`x_search` albo `group:web`. - - `web_fetch` jest włączone domyślnie (chyba że zostało jawnie wyłączone). - - Jeśli `tools.web.fetch.provider` zostanie pominięte, OpenClaw automatycznie wykryje pierwszego gotowego dostawcę fetch fallback na podstawie dostępnych poświadczeń. Obecnie bundlowanym dostawcą jest Firecrawl. - - Demony odczytują zmienne env z `~/.openclaw/.env` (lub ze środowiska usługi). + - `web_fetch` jest włączone domyślnie (chyba że jawnie je wyłączysz). + - Jeśli `tools.web.fetch.provider` zostanie pominięte, OpenClaw automatycznie wykrywa pierwszego gotowego providera fetch fallback na podstawie dostępnych poświadczeń. Obecnie bundlowanym providerem jest Firecrawl. + - Demony odczytują zmienne środowiskowe z `~/.openclaw/.env` (albo środowiska usługi). - Dokumentacja: [Web tools](/pl/tools/web). + Dokumentacja: [Narzędzia webowe](/pl/tools/web). - - `config.apply` zastępuje **cały config**. Jeśli wyślesz obiekt częściowy, wszystko + + `config.apply` zastępuje **całą konfigurację**. Jeśli wyślesz obiekt częściowy, wszystko inne zostanie usunięte. Odzyskiwanie: - - Przywróć z kopii zapasowej (git albo skopiowany `~/.openclaw/openclaw.json`). - - Jeśli nie masz kopii, uruchom ponownie `openclaw doctor` i ponownie skonfiguruj kanały/modele. - - Jeśli to było nieoczekiwane, zgłoś błąd i dołącz ostatni znany config albo dowolną kopię zapasową. - - Lokalny agent kodujący często potrafi odtworzyć działający config z logów lub historii. + - Przywróć z kopii zapasowej (git albo skopiowane `~/.openclaw/openclaw.json`). + - Jeśli nie masz kopii zapasowej, uruchom ponownie `openclaw doctor` i skonfiguruj kanały/modele. + - Jeśli to było nieoczekiwane, zgłoś błąd i dołącz ostatnią znaną konfigurację albo dowolną kopię zapasową. + - Lokalny agent do kodowania często potrafi odtworzyć działającą konfigurację z logów lub historii. Jak tego uniknąć: - - Używaj `openclaw config set` do małych zmian. + - Używaj `openclaw config set` dla małych zmian. - Używaj `openclaw configure` do edycji interaktywnych. - - Najpierw użyj `config.schema.lookup`, gdy nie jesteś pewien dokładnej ścieżki lub kształtu pola; zwraca płytki węzeł schematu oraz podsumowania bezpośrednich dzieci do dalszego zagłębiania. - - Używaj `config.patch` do częściowych edycji RPC; `config.apply` zostaw wyłącznie do pełnej zamiany configu. - - Jeśli używasz narzędzia `gateway` dostępnego tylko dla ownera podczas uruchomienia agenta, nadal odrzuci ono zapisy do `tools.exec.ask` / `tools.exec.security` (w tym aliasy legacy `tools.bash.*`, które normalizują się do tych samych chronionych ścieżek exec). + - Najpierw użyj `config.schema.lookup`, gdy nie masz pewności co do dokładnej ścieżki lub kształtu pola; zwraca płytki węzeł schematu oraz podsumowania bezpośrednich dzieci do dalszego zagłębiania. + - Używaj `config.patch` do częściowych edycji RPC; `config.apply` zostaw wyłącznie do pełnej wymiany konfiguracji. + - Jeśli używasz narzędzia `gateway` dostępnego tylko dla właściciela z poziomu uruchomienia agenta, nadal będzie ono odrzucać zapisy do `tools.exec.ask` / `tools.exec.security` (w tym starsze aliasy `tools.bash.*`, które normalizują się do tych samych chronionych ścieżek exec). Dokumentacja: [Config](/cli/config), [Configure](/cli/configure), [Doctor](/pl/gateway/doctor). - - Typowy wzorzec to **jeden Gateway** (np. Raspberry Pi) plus **nodes** i **agents**: + + Typowy wzorzec to **jeden Gateway** (np. Raspberry Pi) plus **nodes** i **agenci**: - **Gateway (centralny):** zarządza kanałami (Signal/WhatsApp), routingiem i sesjami. - - **Nodes (urządzenia):** Maki/iOS/Android podłączają się jako urządzenia peryferyjne i udostępniają lokalne narzędzia (`system.run`, `canvas`, `camera`). - - **Agents (workery):** oddzielne „mózgi”/workspace dla wyspecjalizowanych ról (np. „Hetzner ops”, „Dane osobiste”). - - **Sub-agents:** uruchamiają pracę w tle z głównego agenta, gdy chcesz równoległości. - - **TUI:** łączy się z Gateway i przełącza agentów/sesje. + - **Nodes (urządzenia):** Maci/iOS/Android łączą się jako peryferia i udostępniają lokalne narzędzia (`system.run`, `canvas`, `camera`). + - **Agenci (workery):** oddzielne „mózgi”/workspace dla wyspecjalizowanych ról (np. „Hetzner ops”, „Dane osobowe”). + - **Sub-agenci:** uruchamiaj pracę w tle z głównego agenta, gdy chcesz równoległości. + - **TUI:** połącz się z Gatewayem i przełączaj agentów/sesje. - Dokumentacja: [Nodes](/pl/nodes), [Remote access](/pl/gateway/remote), [Multi-Agent Routing](/pl/concepts/multi-agent), [Sub-agents](/pl/tools/subagents), [TUI](/web/tui). + Dokumentacja: [Nodes](/pl/nodes), [Dostęp zdalny](/pl/gateway/remote), [Routing wielu agentów](/pl/concepts/multi-agent), [Sub-agenci](/pl/tools/subagents), [TUI](/web/tui). - + Tak. To opcja konfiguracyjna: ```json5 @@ -1680,59 +1681,59 @@ pod kątem użycia/rozliczeń i w razie potrzeby zwiększ limity. } ``` - Wartość domyślna to `false` (z oknem). Tryb headless częściej wywołuje kontrole antybotowe na niektórych stronach. Zobacz [Browser](/pl/tools/browser). + Domyślnie jest `false` (z widocznym oknem). Tryb headless częściej uruchamia kontrole antybotowe na niektórych stronach. Zobacz [Przeglądarka](/pl/tools/browser). - Headless używa **tego samego silnika Chromium** i działa dla większości automatyzacji (formularze, kliknięcia, scraping, logowania). Główne różnice: + Headless używa **tego samego silnika Chromium** i działa przy większości automatyzacji (formularze, kliknięcia, scraping, logowania). Główne różnice: - - Brak widocznego okna przeglądarki (używaj screenshotów, jeśli potrzebujesz wizualizacji). - - Niektóre strony są bardziej restrykcyjne wobec automatyzacji w trybie headless (CAPTCHA, antybot). + - Brak widocznego okna przeglądarki (jeśli potrzebujesz wizualiów, używaj zrzutów ekranu). + - Niektóre strony są bardziej rygorystyczne wobec automatyzacji w trybie headless (CAPTCHA, antybot). Na przykład X/Twitter często blokuje sesje headless. - Ustaw `browser.executablePath` na binarium Brave (lub dowolnej przeglądarki opartej na Chromium) i zrestartuj Gateway. - Pełne przykłady konfiguracji znajdziesz w [Browser](/pl/tools/browser#use-brave-or-another-chromium-based-browser). + Ustaw `browser.executablePath` na binarkę Brave (lub dowolnej przeglądarki opartej na Chromium) i zrestartuj Gateway. + Pełne przykłady konfiguracji znajdziesz w [Przeglądarce](/pl/tools/browser#use-brave-or-another-chromium-based-browser). -## Zdalne gateway i nodes +## Zdalne gatewaye i nodes - - Wiadomości z Telegrama są obsługiwane przez **gateway**. Gateway uruchamia agenta i + + Wiadomości z Telegrama obsługuje **gateway**. Gateway uruchamia agenta i dopiero potem wywołuje nodes przez **Gateway WebSocket**, gdy potrzebne jest narzędzie node: Telegram → Gateway → Agent → `node.*` → Node → Gateway → Telegram - Nodes nie widzą ruchu przychodzącego od dostawców; otrzymują tylko wywołania RPC node. + Nodes nie widzą ruchu wejściowego providera; otrzymują tylko wywołania node RPC. - Krótka odpowiedź: **sparuj komputer jako node**. Gateway działa gdzie indziej, ale może + Krótka odpowiedź: **sparuj swój komputer jako node**. Gateway działa gdzie indziej, ale może wywoływać narzędzia `node.*` (screen, camera, system) na Twojej lokalnej maszynie przez Gateway WebSocket. Typowa konfiguracja: - 1. Uruchom Gateway na hoście zawsze włączonym (VPS/serwer domowy). - 2. Umieść host Gateway i komputer w tej samej tailnet. - 3. Upewnij się, że WS Gateway jest osiągalny (bind tailnet albo tunel SSH). + 1. Uruchom Gateway na zawsze włączonym hoście (VPS/serwer domowy). + 2. Dodaj host Gatewaya + swój komputer do tego samego tailnetu. + 3. Upewnij się, że Gateway WS jest osiągalny (bind tailnet albo tunel SSH). 4. Otwórz lokalnie aplikację macOS i połącz się w trybie **Remote over SSH** (albo bezpośrednio przez tailnet), aby mogła zarejestrować się jako node. - 5. Zatwierdź node na Gateway: + 5. Zatwierdź node na Gatewayu: ```bash openclaw devices list openclaw devices approve ``` - Nie jest wymagany żaden osobny most TCP; nodes łączą się przez Gateway WebSocket. + Oddzielny most TCP nie jest wymagany; nodes łączą się przez Gateway WebSocket. - Przypomnienie o bezpieczeństwie: sparowanie node macOS umożliwia `system.run` na tej maszynie. Paruj - tylko urządzenia, którym ufasz, i zapoznaj się z [Security](/pl/gateway/security). + Przypomnienie o bezpieczeństwie: sparowanie node macOS pozwala na `system.run` na tej maszynie. Paruj + tylko urządzenia, którym ufasz, i przeczytaj [Bezpieczeństwo](/pl/gateway/security). - Dokumentacja: [Nodes](/pl/nodes), [Gateway protocol](/pl/gateway/protocol), [macOS remote mode](/pl/platforms/mac/remote), [Security](/pl/gateway/security). + Dokumentacja: [Nodes](/pl/nodes), [Protokół Gatewaya](/pl/gateway/protocol), [zdalny tryb macOS](/pl/platforms/mac/remote), [Bezpieczeństwo](/pl/gateway/security). @@ -1740,16 +1741,16 @@ pod kątem użycia/rozliczeń i w razie potrzeby zwiększ limity. Sprawdź podstawy: - Gateway działa: `openclaw gateway status` - - Stan Gateway: `openclaw status` - - Stan kanałów: `openclaw channels status` + - Kondycja Gatewaya: `openclaw status` + - Kondycja kanałów: `openclaw channels status` - Następnie zweryfikuj auth i routing: + Następnie zweryfikuj uwierzytelnianie i routing: - Jeśli używasz Tailscale Serve, upewnij się, że `gateway.auth.allowTailscale` jest ustawione poprawnie. - Jeśli łączysz się przez tunel SSH, potwierdź, że lokalny tunel działa i wskazuje właściwy port. - - Potwierdź, że allowlisty (DM lub grupy) obejmują Twoje konto. + - Potwierdź, że Twoje allowlisty (DM albo grupy) obejmują Twoje konto. - Dokumentacja: [Tailscale](/pl/gateway/tailscale), [Remote access](/pl/gateway/remote), [Channels](/pl/channels). + Dokumentacja: [Tailscale](/pl/gateway/tailscale), [Dostęp zdalny](/pl/gateway/remote), [Kanały](/pl/channels). @@ -1757,77 +1758,77 @@ pod kątem użycia/rozliczeń i w razie potrzeby zwiększ limity. Tak. Nie ma wbudowanego mostu „bot-do-bota”, ale można to spiąć na kilka niezawodnych sposobów: - **Najprościej:** użyj zwykłego kanału czatu, do którego oba boty mają dostęp (Telegram/Slack/WhatsApp). + **Najprościej:** użyj zwykłego kanału czatowego, do którego oba boty mają dostęp (Telegram/Slack/WhatsApp). Niech Bot A wyśle wiadomość do Bota B, a potem Bot B odpowie jak zwykle. - **Most CLI (generyczny):** uruchom skrypt, który wywołuje drugi Gateway przez - `openclaw agent --message ... --deliver`, celując w czat, którego drugi bot - nasłuchuje. Jeśli jeden bot jest na zdalnym VPS, skieruj swoje CLI do tego zdalnego Gateway - przez SSH/Tailscale (zobacz [Remote access](/pl/gateway/remote)). + **Most CLI (ogólny):** uruchom skrypt, który wywoła drugi Gateway przez + `openclaw agent --message ... --deliver`, kierując wiadomość do czatu, którego ten drugi bot + nasłuchuje. Jeśli jeden bot działa na zdalnym VPS, skieruj CLI do tego zdalnego Gatewaya + przez SSH/Tailscale (zobacz [Dostęp zdalny](/pl/gateway/remote)). - Przykładowy wzorzec (uruchom z maszyny, która może dotrzeć do docelowego Gateway): + Przykładowy wzorzec (uruchom z maszyny, która potrafi dotrzeć do docelowego Gatewaya): ```bash openclaw agent --message "Hello from local bot" --deliver --channel telegram --reply-to ``` - Wskazówka: dodaj guardrail, aby oba boty nie zapętliły się bez końca (tylko wzmianki, allowlisty kanałów + Wskazówka: dodaj guardrail, aby oba boty nie zapętlały się bez końca (odpowiedzi tylko po wzmiance, allowlisty kanałów albo reguła „nie odpowiadaj na wiadomości botów”). - Dokumentacja: [Remote access](/pl/gateway/remote), [Agent CLI](/cli/agent), [Agent send](/pl/tools/agent-send). + Dokumentacja: [Dostęp zdalny](/pl/gateway/remote), [Agent CLI](/cli/agent), [Agent send](/pl/tools/agent-send). - + Nie. Jeden Gateway może hostować wielu agentów, każdy z własnym workspace, domyślnymi modelami - i routingiem. To jest normalna konfiguracja i jest dużo tańsza oraz prostsza niż uruchamianie + i routingiem. To jest normalna konfiguracja i jest znacznie tańsza oraz prostsza niż uruchamianie jednego VPS na agenta. - Używaj osobnych VPS-ów tylko wtedy, gdy potrzebujesz twardej izolacji (granice bezpieczeństwa) albo bardzo + Używaj osobnych VPS-ów tylko wtedy, gdy potrzebujesz twardej izolacji (granic bezpieczeństwa) albo bardzo różnych konfiguracji, których nie chcesz współdzielić. W przeciwnym razie trzymaj jeden Gateway i - używaj wielu agentów albo subagentów. + używaj wielu agentów albo sub agentów. - - Tak — nodes to rozwiązanie pierwszej klasy do docierania zdalnym Gateway do Twojego laptopa i - otwierają więcej niż sam dostęp do powłoki. Gateway działa na macOS/Linuxie (Windows przez WSL2) i jest - lekki (mały VPS albo urządzenie klasy Raspberry Pi wystarczą; 4 GB RAM to dużo), więc typowa - konfiguracja to host zawsze włączony plus laptop jako node. + + Tak — nodes to pierwszoklasowy sposób docierania do laptopa ze zdalnego Gatewaya i + odblokowują więcej niż sam dostęp do powłoki. Gateway działa na macOS/Linux (Windows przez WSL2) i jest + lekki (wystarczy mały VPS lub urządzenie klasy Raspberry Pi; 4 GB RAM to aż nadto), więc typową + konfiguracją jest host zawsze włączony plus Twój laptop jako node. - - **Bez przychodzącego SSH.** Nodes łączą się wychodząco do Gateway WebSocket i używają parowania urządzeń. - - **Bezpieczniejsze sterowanie wykonaniem.** `system.run` jest ograniczane przez allowlisty/zatwierdzenia node na tym laptopie. + - **Nie wymaga przychodzącego SSH.** Nodes łączą się wychodząco do Gateway WebSocket i używają parowania urządzeń. + - **Bezpieczniejsze sterowanie wykonaniem.** `system.run` jest bramkowane przez allowlisty/zatwierdzenia node na tym laptopie. - **Więcej narzędzi urządzenia.** Nodes udostępniają `canvas`, `camera` i `screen` oprócz `system.run`. - - **Lokalna automatyzacja przeglądarki.** Trzymaj Gateway na VPS, ale uruchamiaj Chrome lokalnie przez host node na laptopie albo dołączaj do lokalnego Chrome na hoście przez Chrome MCP. + - **Lokalna automatyzacja przeglądarki.** Trzymaj Gateway na VPS, ale uruchamiaj lokalnie Chrome przez hosta node na laptopie albo dołączaj do lokalnego Chrome na hoście przez Chrome MCP. - SSH jest w porządku do doraźnego dostępu do powłoki, ale nodes są prostsze dla ciągłych przepływów pracy agentów i + SSH jest w porządku dla doraźnego dostępu do powłoki, ale nodes są prostsze dla ciągłych przepływów pracy agentów i automatyzacji urządzeń. - Dokumentacja: [Nodes](/pl/nodes), [Nodes CLI](/cli/nodes), [Browser](/pl/tools/browser). + Dokumentacja: [Nodes](/pl/nodes), [Nodes CLI](/cli/nodes), [Przeglądarka](/pl/tools/browser). - Nie. Tylko **jeden gateway** powinien działać na hosta, chyba że celowo uruchamiasz izolowane profile (zobacz [Multiple gateways](/pl/gateway/multiple-gateways)). Nodes są urządzeniami peryferyjnymi, które łączą się - z gateway (nodes iOS/Android albo tryb „node mode” macOS w aplikacji menubar). Dla headless hostów node - i sterowania CLI zobacz [Node host CLI](/cli/node). + Nie. Na hoście powinien działać tylko **jeden gateway**, chyba że celowo uruchamiasz profile izolowane (zobacz [Wiele gatewayów](/pl/gateway/multiple-gateways)). Nodes to peryferia łączące się + z gatewayem (nodes iOS/Android albo macOS „tryb node” w aplikacji menu bar). Informacje o headless + hostach node i sterowaniu z CLI znajdziesz w [Node host CLI](/cli/node). Pełny restart jest wymagany dla zmian `gateway`, `discovery` i `canvasHost`. - + Tak. - - `config.schema.lookup`: sprawdź jedno poddrzewo configu z jego płytkim węzłem schematu, dopasowaną wskazówką UI i podsumowaniami bezpośrednich dzieci przed zapisem - - `config.get`: pobierz bieżącą migawkę + hash - - `config.patch`: bezpieczna częściowa aktualizacja (preferowana dla większości edycji RPC) - - `config.apply`: zweryfikuj + zastąp cały config, a następnie zrestartuj - - Narzędzie runtime `gateway`, dostępne tylko dla ownera, nadal odmawia przepisywania `tools.exec.ask` / `tools.exec.security`; aliasy legacy `tools.bash.*` normalizują się do tych samych chronionych ścieżek exec + - `config.schema.lookup`: sprawdza jedno poddrzewo konfiguracji wraz z jego płytkim węzłem schematu, dopasowaną wskazówką UI i podsumowaniami bezpośrednich dzieci przed zapisem + - `config.get`: pobiera bieżącą migawkę + hash + - `config.patch`: bezpieczna częściowa aktualizacja (zalecana dla większości edycji RPC); wykonuje hot-reload, gdy to możliwe, i restartuje, gdy to wymagane + - `config.apply`: waliduje + zastępuje pełną konfigurację; wykonuje hot-reload, gdy to możliwe, i restartuje, gdy to wymagane + - Narzędzie runtime `gateway` dostępne tylko dla właściciela nadal odmawia przepisania `tools.exec.ask` / `tools.exec.security`; starsze aliasy `tools.bash.*` normalizują się do tych samych chronionych ścieżek exec - + ```json5 { agents: { defaults: { workspace: "~/.openclaw/workspace" } }, @@ -1835,11 +1836,11 @@ pod kątem użycia/rozliczeń i w razie potrzeby zwiększ limity. } ``` - To ustawia Twój workspace i ogranicza, kto może wywołać bota. + To ustawia workspace i ogranicza, kto może wyzwolić bota. - + Minimalne kroki: 1. **Zainstaluj + zaloguj się na VPS** @@ -1850,7 +1851,7 @@ pod kątem użycia/rozliczeń i w razie potrzeby zwiększ limity. ``` 2. **Zainstaluj + zaloguj się na Macu** - - Użyj aplikacji Tailscale i zaloguj się do tej samej tailnet. + - Użyj aplikacji Tailscale i zaloguj się do tego samego tailnetu. 3. **Włącz MagicDNS (zalecane)** - W konsoli administracyjnej Tailscale włącz MagicDNS, aby VPS miał stabilną nazwę. 4. **Użyj nazwy hosta tailnet** @@ -1863,53 +1864,53 @@ pod kątem użycia/rozliczeń i w razie potrzeby zwiększ limity. openclaw gateway --tailscale serve ``` - To utrzymuje gateway przypięty do loopback i wystawia HTTPS przez Tailscale. Zobacz [Tailscale](/pl/gateway/tailscale). + To utrzymuje gateway zbindowany do loopback i wystawia HTTPS przez Tailscale. Zobacz [Tailscale](/pl/gateway/tailscale). - - Serve wystawia **Gateway Control UI + WS**. Nodes łączą się przez ten sam endpoint Gateway WS. + + Serve wystawia **Control UI + WS Gatewaya**. Nodes łączą się przez ten sam endpoint Gateway WS. Zalecana konfiguracja: - 1. **Upewnij się, że VPS i Mac są w tej samej tailnet**. - 2. **Używaj aplikacji macOS w trybie Remote** (celem SSH może być nazwa hosta tailnet). - Aplikacja przetuneluje port Gateway i połączy się jako node. - 3. **Zatwierdź node** na gateway: + 1. **Upewnij się, że VPS + Mac są w tym samym tailnecie**. + 2. **Użyj aplikacji macOS w trybie zdalnym** (celem SSH może być nazwa hosta tailnet). + Aplikacja tuneluje port Gatewaya i połączy się jako node. + 3. **Zatwierdź node** na gatewayu: ```bash openclaw devices list openclaw devices approve ``` - Dokumentacja: [Gateway protocol](/pl/gateway/protocol), [Discovery](/pl/gateway/discovery), [macOS remote mode](/pl/platforms/mac/remote). + Dokumentacja: [Protokół Gatewaya](/pl/gateway/protocol), [Discovery](/pl/gateway/discovery), [zdalny tryb macOS](/pl/platforms/mac/remote). - + Jeśli potrzebujesz tylko **lokalnych narzędzi** (screen/camera/exec) na drugim laptopie, dodaj go jako - **node**. Dzięki temu zachowujesz pojedynczy Gateway i unikasz duplikowania configu. Lokalne narzędzia node są - obecnie dostępne tylko na macOS, ale planujemy rozszerzyć je na inne systemy operacyjne. + **node**. Dzięki temu utrzymujesz jeden Gateway i unikasz duplikowania konfiguracji. Lokalne narzędzia node są + obecnie tylko dla macOS, ale planujemy rozszerzyć je na inne systemy operacyjne. - Instaluj drugi Gateway tylko wtedy, gdy potrzebujesz **twardej izolacji** albo dwóch w pełni oddzielnych botów. + Drugi Gateway instaluj tylko wtedy, gdy potrzebujesz **twardej izolacji** albo dwóch całkowicie osobnych botów. - Dokumentacja: [Nodes](/pl/nodes), [Nodes CLI](/cli/nodes), [Multiple gateways](/pl/gateway/multiple-gateways). + Dokumentacja: [Nodes](/pl/nodes), [Nodes CLI](/cli/nodes), [Wiele gatewayów](/pl/gateway/multiple-gateways). -## Zmienne env i ładowanie .env +## Zmienne środowiskowe i ładowanie .env - OpenClaw odczytuje zmienne env z procesu nadrzędnego (powłoka, launchd/systemd, CI itd.) i dodatkowo ładuje: + OpenClaw odczytuje zmienne środowiskowe z procesu nadrzędnego (powłoka, launchd/systemd, CI itd.) i dodatkowo ładuje: - `.env` z bieżącego katalogu roboczego - globalny fallback `.env` z `~/.openclaw/.env` (czyli `$OPENCLAW_STATE_DIR/.env`) - Żaden z plików `.env` nie nadpisuje istniejących zmiennych env. + Żaden z tych plików `.env` nie nadpisuje istniejących zmiennych środowiskowych. - Możesz też definiować w configu wbudowane zmienne env (stosowane tylko wtedy, gdy brakuje ich w env procesu): + Możesz też zdefiniować inline env vars w konfiguracji (stosowane tylko wtedy, gdy brakuje ich w process env): ```json5 { @@ -1920,15 +1921,15 @@ pod kątem użycia/rozliczeń i w razie potrzeby zwiększ limity. } ``` - Pełny priorytet i źródła znajdziesz w [/environment](/pl/help/environment). + Pełny opis priorytetów i źródeł znajdziesz w [/environment](/pl/help/environment). - - Dwie typowe poprawki: + + Dwie częste poprawki: - 1. Umieść brakujące klucze w `~/.openclaw/.env`, aby były pobierane nawet wtedy, gdy usługa nie dziedziczy Twojego env z powłoki. - 2. Włącz import z powłoki (opcja convenience): + 1. Umieść brakujące klucze w `~/.openclaw/.env`, aby zostały odczytane nawet wtedy, gdy usługa nie dziedziczy env z Twojej powłoki. + 2. Włącz import powłoki (wygoda typu opt-in): ```json5 { @@ -1941,18 +1942,18 @@ pod kątem użycia/rozliczeń i w razie potrzeby zwiększ limity. } ``` - To uruchamia Twoją login shell i importuje tylko brakujące oczekiwane klucze (nigdy nie nadpisuje). Odpowiedniki zmiennych env: + To uruchamia Twoją powłokę logowania i importuje tylko brakujące oczekiwane klucze (nigdy nie nadpisuje). Odpowiedniki w zmiennych środowiskowych: `OPENCLAW_LOAD_SHELL_ENV=1`, `OPENCLAW_SHELL_ENV_TIMEOUT_MS=15000`. `openclaw models status` raportuje, czy **import env z powłoki** jest włączony. „Shell env: off” - **nie** oznacza, że brakuje Twoich zmiennych env — oznacza tylko, że OpenClaw nie będzie - automatycznie ładował Twojej login shell. + **nie** oznacza, że Twoich zmiennych środowiskowych brakuje — oznacza tylko, że OpenClaw nie załaduje + automatycznie Twojej powłoki logowania. - Jeśli Gateway działa jako usługa (launchd/systemd), nie odziedziczy środowiska Twojej powłoki. - Naprawa przez jedno z poniższych: + Jeśli Gateway działa jako usługa (launchd/systemd), nie odziedziczy środowiska + Twojej powłoki. Napraw to jednym z poniższych sposobów: 1. Umieść token w `~/.openclaw/.env`: @@ -1960,8 +1961,8 @@ pod kątem użycia/rozliczeń i w razie potrzeby zwiększ limity. COPILOT_GITHUB_TOKEN=... ``` - 2. Albo włącz import z powłoki (`env.shellEnv.enabled: true`). - 3. Albo dodaj go do bloku `env` w configu (stosowane tylko, gdy brakuje). + 2. Albo włącz import powłoki (`env.shellEnv.enabled: true`). + 3. Albo dodaj go do bloku `env` w konfiguracji (stosuje się tylko, jeśli go brakuje). Następnie zrestartuj gateway i sprawdź ponownie: @@ -1969,7 +1970,7 @@ pod kątem użycia/rozliczeń i w razie potrzeby zwiększ limity. openclaw models status ``` - Tokeny Copilot są odczytywane z `COPILOT_GITHUB_TOKEN` (także `GH_TOKEN` / `GITHUB_TOKEN`). + Tokeny Copilot są odczytywane z `COPILOT_GITHUB_TOKEN` (również `GH_TOKEN` / `GITHUB_TOKEN`). Zobacz [/concepts/model-providers](/pl/concepts/model-providers) i [/environment](/pl/help/environment). @@ -1979,14 +1980,14 @@ pod kątem użycia/rozliczeń i w razie potrzeby zwiększ limity. - Wyślij `/new` albo `/reset` jako samodzielną wiadomość. Zobacz [Session management](/pl/concepts/session). + Wyślij `/new` albo `/reset` jako samodzielną wiadomość. Zobacz [Zarządzanie sesją](/pl/concepts/session). - Sesje mogą wygasać po `session.idleMinutes`, ale ta funkcja jest **domyślnie wyłączona** (domyślnie **0**). - Ustaw wartość dodatnią, aby włączyć wygasanie bezczynności. Gdy jest włączone, **następna** - wiadomość po okresie bezczynności rozpoczyna nowy identyfikator sesji dla tego klucza czatu. - Nie usuwa to transkryptów — po prostu rozpoczyna nową sesję. + Sesje mogą wygasać po `session.idleMinutes`, ale jest to **domyślnie wyłączone** (domyślnie **0**). + Ustaw wartość dodatnią, aby włączyć wygasanie z bezczynności. Gdy jest włączone, **następna** + wiadomość po okresie bezczynności uruchamia nowy identyfikator sesji dla tego klucza czatu. + To nie usuwa transkryptów — po prostu rozpoczyna nową sesję. ```json5 { @@ -1998,41 +1999,41 @@ pod kątem użycia/rozliczeń i w razie potrzeby zwiększ limity. - - Tak, przez **multi-agent routing** i **sub-agents**. Możesz utworzyć jednego - koordynującego agenta i kilku agentów roboczych z własnymi workspace i modelami. + + Tak, przez **routing wielu agentów** i **sub-agentów**. Możesz utworzyć jednego + agenta koordynującego i kilku agentów roboczych z własnymi workspace i modelami. - Mimo to najlepiej traktować to jako **zabawny eksperyment**. Zużywa dużo tokenów i często - jest mniej wydajne niż używanie jednego bota z osobnymi sesjami. Typowy model, który - zakładamy, to jeden bot, z którym rozmawiasz, z różnymi sesjami dla pracy równoległej. Ten - bot może też uruchamiać subagentów, gdy to potrzebne. + Mimo to najlepiej traktować to jako **zabawny eksperyment**. Jest to kosztowne tokenowo i często + mniej efektywne niż używanie jednego bota z oddzielnymi sesjami. Typowy model, jaki + sobie wyobrażamy, to jeden bot, z którym rozmawiasz, z różnymi sesjami do pracy równoległej. Taki + bot może też w razie potrzeby uruchamiać sub-agentów. - Dokumentacja: [Multi-agent routing](/pl/concepts/multi-agent), [Sub-agents](/pl/tools/subagents), [Agents CLI](/cli/agents). + Dokumentacja: [Routing wielu agentów](/pl/concepts/multi-agent), [Sub-agenci](/pl/tools/subagents), [Agents CLI](/cli/agents). - - Kontekst sesji jest ograniczony przez okno modelu. Długie czaty, duże wyniki narzędzi lub wiele - plików mogą wywołać kompaktowanie albo przycinanie. + + Kontekst sesji jest ograniczony oknem modelu. Długie czaty, duże wyjścia narzędzi albo wiele + plików mogą uruchomić kompaktowanie albo obcinanie. Co pomaga: - - Poproś bota, aby podsumował bieżący stan i zapisał go do pliku. - - Użyj `/compact` przed długimi zadaniami, a `/new` przy zmianie tematu. - - Trzymaj ważny kontekst w workspace i poproś bota, aby odczytał go ponownie. - - Używaj subagentów do długiej lub równoległej pracy, aby główny czat był mniejszy. - - Wybierz model z większym oknem kontekstu, jeśli to zdarza się często. + - Poproś bota o podsumowanie bieżącego stanu i zapisanie go do pliku. + - Używaj `/compact` przed długimi zadaniami, a `/new` przy zmianie tematu. + - Trzymaj ważny kontekst w workspace i poproś bota, aby go ponownie odczytał. + - Używaj sub-agentów do długiej lub równoległej pracy, aby główny czat był mniejszy. + - Wybierz model z większym oknem kontekstowym, jeśli dzieje się to często. - + Użyj polecenia reset: ```bash openclaw reset ``` - Nieinteraktywny pełny reset: + Pełny reset bez interakcji: ```bash openclaw reset --scope full --yes --non-interactive @@ -2046,16 +2047,16 @@ pod kątem użycia/rozliczeń i w razie potrzeby zwiększ limity. Uwagi: - - Onboarding również oferuje **Reset**, jeśli wykryje istniejący config. Zobacz [Onboarding (CLI)](/pl/start/wizard). + - Onboarding także oferuje **Reset**, jeśli wykryje istniejącą konfigurację. Zobacz [Onboarding (CLI)](/pl/start/wizard). - Jeśli używałeś profili (`--profile` / `OPENCLAW_PROFILE`), zresetuj każdy katalog stanu (domyślne to `~/.openclaw-`). - - Reset dev: `openclaw gateway --dev --reset` (tylko dev; czyści config dev + poświadczenia + sesje + workspace). + - Dev reset: `openclaw gateway --dev --reset` (tylko dev; czyści konfigurację dev + poświadczenia + sesje + workspace). - - Użyj jednego z poniższych: + + Użyj jednego z tych sposobów: - - **Compact** (zachowuje rozmowę, ale podsumowuje starsze tury): + - **Kompaktowanie** (zachowuje rozmowę, ale podsumowuje starsze tury): ``` /compact @@ -2070,18 +2071,18 @@ pod kątem użycia/rozliczeń i w razie potrzeby zwiększ limity. /reset ``` - Jeśli to ciągle się dzieje: + Jeśli to się powtarza: - - Włącz lub dostrój **session pruning** (`agents.defaults.contextPruning`), aby przycinać stare wyniki narzędzi. - - Użyj modelu z większym oknem kontekstu. + - Włącz albo dostrój **przycinanie sesji** (`agents.defaults.contextPruning`), aby obcinać stare wyjścia narzędzi. + - Użyj modelu z większym oknem kontekstowym. - Dokumentacja: [Compaction](/pl/concepts/compaction), [Session pruning](/pl/concepts/session-pruning), [Session management](/pl/concepts/session). + Dokumentacja: [Kompaktowanie](/pl/concepts/compaction), [Przycinanie sesji](/pl/concepts/session-pruning), [Zarządzanie sesją](/pl/concepts/session). - To błąd walidacji dostawcy: model wyemitował blok `tool_use` bez wymaganego - `input`. Zwykle oznacza to, że historia sesji jest nieaktualna lub uszkodzona (często po długich wątkach + To błąd walidacji providera: model wyemitował blok `tool_use` bez wymaganego + `input`. Zwykle oznacza to, że historia sesji jest stara albo uszkodzona (często po długich wątkach albo zmianie narzędzia/schematu). Naprawa: rozpocznij nową sesję przez `/new` (samodzielna wiadomość). @@ -2089,33 +2090,33 @@ pod kątem użycia/rozliczeń i w razie potrzeby zwiększ limity. - Heartbeat uruchamia się domyślnie co **30m** (**1h** przy użyciu auth OAuth). Dostosuj lub wyłącz: + Heartbeat uruchamia się domyślnie co **30m** (**1h** przy użyciu uwierzytelniania OAuth). Dostosuj albo wyłącz: ```json5 { agents: { defaults: { heartbeat: { - every: "2h", // lub "0m", aby wyłączyć + every: "2h", // albo "0m", aby wyłączyć }, }, }, } ``` - Jeśli `HEARTBEAT.md` istnieje, ale jest w praktyce pusty (tylko puste linie i nagłówki - markdown, takie jak `# Heading`), OpenClaw pomija uruchomienie heartbeat, aby oszczędzić wywołania API. - Jeśli pliku brakuje, heartbeat nadal działa, a model decyduje, co zrobić. + Jeśli `HEARTBEAT.md` istnieje, ale jest w praktyce pusty (tylko puste linie i nagłówki markdown + takie jak `# Heading`), OpenClaw pomija uruchomienie heartbeat, aby oszczędzać wywołania API. + Jeśli pliku brakuje, heartbeat nadal się uruchamia, a model sam decyduje, co zrobić. - Override’y per agent używają `agents.list[].heartbeat`. Dokumentacja: [Heartbeat](/pl/gateway/heartbeat). + Nadpisania per agent używają `agents.list[].heartbeat`. Dokumentacja: [Heartbeat](/pl/gateway/heartbeat). - - Nie. OpenClaw działa na **Twoim własnym koncie**, więc jeśli jesteś w grupie, OpenClaw może ją zobaczyć. - Domyślnie odpowiedzi w grupach są blokowane, dopóki nie dopuścisz nadawców (`groupPolicy: "allowlist"`). + + Nie. OpenClaw działa na **Twoim własnym koncie**, więc jeśli jesteś w grupie, OpenClaw może ją widzieć. + Domyślnie odpowiedzi w grupach są blokowane, dopóki nie zezwolisz nadawcom (`groupPolicy: "allowlist"`). - Jeśli chcesz, aby tylko **Ty** mógł wywoływać odpowiedzi grupowe: + Jeśli chcesz, aby tylko **Ty** mógł wyzwalać odpowiedzi w grupie: ```json5 { @@ -2131,143 +2132,83 @@ pod kątem użycia/rozliczeń i w razie potrzeby zwiększ limity. - Opcja 1 (najszybsza): śledź logi i wyślij testową wiadomość do grupy: + Opcja 1 (najszybciej): podejrzyj logi i wyślij testową wiadomość do grupy: ```bash openclaw logs --follow --json ``` - Szukaj `chatId` (albo `from`) kończącego się na `@g.us`, na przykład: + Szukaj `chatId` (albo `from`) kończącego się na `@g.us`, np.: `1234567890-1234567890@g.us`. - Opcja 2 (jeśli już skonfigurowane/w allowlist): wypisz grupy z configu: + Opcja 2 (jeśli już skonfigurowane/na allowliście): wypisz grupy z konfiguracji: ```bash openclaw directory groups list --channel whatsapp ``` - Dokumentacja: [WhatsApp](/pl/channels/whatsapp), [Directory](/cli/directory), [Logs](/cli/logs). + Dokumentacja: [WhatsApp](/pl/channels/whatsapp), [Directory](/cli/directory), [Logi](/cli/logs). - Dwie typowe przyczyny: + Dwie częste przyczyny: - - Bramka wzmianki jest włączona (domyślnie). Musisz oznaczyć bota przez @mention (albo dopasować `mentionPatterns`). - - Skonfigurowałeś `channels.whatsapp.groups` bez `"*"`, a grupa nie znajduje się na allowlist. + - Włączona jest bramka wzmianki (domyślnie). Musisz oznaczyć bota @wzmianką (albo dopasować `mentionPatterns`). + - Skonfigurowałeś `channels.whatsapp.groups` bez `"*"`, a grupa nie jest na allowliście. - Zobacz [Groups](/pl/channels/groups) i [Group messages](/pl/channels/group-messages). + Zobacz [Grupy](/pl/channels/groups) i [Wiadomości grupowe](/pl/channels/group-messages). - - Czaty bezpośrednie domyślnie zapadają się do sesji głównej. Grupy/kanały mają własne klucze sesji, a tematy Telegrama / wątki Discorda są oddzielnymi sesjami. Zobacz [Groups](/pl/channels/groups) i [Group messages](/pl/channels/group-messages). + + Bezpośrednie czaty domyślnie zapadają się do głównej sesji. Grupy/kanały mają własne klucze sesji, a tematy Telegrama / wątki Discorda są osobnymi sesjami. Zobacz [Grupy](/pl/channels/groups) i [Wiadomości grupowe](/pl/channels/group-messages). Nie ma twardych limitów. Dziesiątki (a nawet setki) są w porządku, ale uważaj na: - - **Wzrost zużycia dysku:** sesje + transkrypty żyją w `~/.openclaw/agents//sessions/`. + - **Wzrost miejsca na dysku:** sesje + transkrypty znajdują się w `~/.openclaw/agents//sessions/`. - **Koszt tokenów:** więcej agentów oznacza więcej równoczesnego użycia modeli. - **Narzut operacyjny:** profile auth per agent, workspace i routing kanałów. Wskazówki: - - Trzymaj jeden **aktywny** workspace per agent (`agents.defaults.workspace`). - - Przycinaj stare sesje (usuń JSONL albo wpisy store), jeśli rośnie zużycie dysku. - - Używaj `openclaw doctor`, aby wykrywać osierocone workspace i niedopasowania profili. + - Utrzymuj jeden **aktywny** workspace na agenta (`agents.defaults.workspace`). + - Przycinaj stare sesje (usuwaj JSONL albo wpisy magazynu), jeśli dysk rośnie. + - Używaj `openclaw doctor`, aby wykrywać zbędne workspace i niedopasowania profili. - - Tak. Użyj **Multi-Agent Routing**, aby uruchamiać wiele izolowanych agentów i kierować wiadomości przychodzące według - kanału/konta/peer. Slack jest obsługiwany jako kanał i może być powiązany z konkretnymi agentami. + + Tak. Użyj **Routingu wielu agentów**, aby uruchamiać wiele izolowanych agentów i kierować wiadomości przychodzące według + kanału/konta/peera. Slack jest obsługiwany jako kanał i może być powiązany z określonymi agentami. - Dostęp przez przeglądarkę jest potężny, ale nie oznacza „zrób wszystko, co może człowiek” — antybot, CAPTCHA i MFA - nadal mogą blokować automatyzację. Dla najbardziej niezawodnego sterowania przeglądarką używaj lokalnego Chrome MCP na hoście, - albo CDP na maszynie, która faktycznie uruchamia przeglądarkę. + Dostęp do przeglądarki jest potężny, ale nie oznacza „zrób wszystko, co człowiek” — antyboty, CAPTCHAs i MFA nadal mogą + blokować automatyzację. Dla najbardziej niezawodnego sterowania przeglądarką używaj lokalnego Chrome MCP na hoście + albo CDP na maszynie, na której faktycznie działa przeglądarka. - Zalecana konfiguracja: + Konfiguracja zgodna z dobrymi praktykami: - - Host Gateway zawsze włączony (VPS/Mac mini). + - Host Gatewaya zawsze włączony (VPS/Mac mini). - Jeden agent na rolę (powiązania). - - Kanały Slack powiązane z tymi agentami. - - Lokalna przeglądarka przez Chrome MCP albo node w razie potrzeby. + - Kanał(y) Slack przypisane do tych agentów. + - Lokalna przeglądarka przez Chrome MCP albo node, gdy to potrzebne. - Dokumentacja: [Multi-Agent Routing](/pl/concepts/multi-agent), [Slack](/pl/channels/slack), - [Browser](/pl/tools/browser), [Nodes](/pl/nodes). + Dokumentacja: [Routing wielu agentów](/pl/concepts/multi-agent), [Slack](/pl/channels/slack), + [Przeglądarka](/pl/tools/browser), [Nodes](/pl/nodes). -## Modele: wartości domyślne, wybór, aliasy, przełączanie +## Modele: ustawienia domyślne, wybór, aliasy, przełączanie - + Domyślny model OpenClaw to to, co ustawisz jako: ``` agents.defaults.model.primary ``` - Do modeli odwołuje się jako `provider/model` (przykład: `openai/gpt-5.4`). Jeśli pominiesz dostawcę, OpenClaw najpierw próbuje aliasu, następnie jednoznacznego dopasowania do skonfigurowanego dostawcy dla dokładnego ID modelu, a dopiero potem wraca do skonfigurowanego dostawcy domyślnego jako przestarzałej ścieżki zgodności. Jeśli ten dostawca nie udostępnia już skonfigurowanego modelu domyślnego, OpenClaw wraca do pierwszego skonfigurowanego dostawcy/modelu zamiast eksponować nieaktualną wartość domyślną usuniętego dostawcy. Nadal jednak powinieneś **jawnie** ustawiać `provider/model`. - - - - - **Zalecany model domyślny:** używaj najmocniejszego modelu najnowszej generacji dostępnego w Twoim stosie dostawców. - **Dla agentów z narzędziami lub niezaufanym wejściem:** stawiaj siłę modelu ponad koszt. - **Dla rutynowego/niskiego ryzyka czatu:** używaj tańszych modeli fallback i kieruj według roli agenta. - - MiniMax ma własną dokumentację: [MiniMax](/pl/providers/minimax) i - [Local models](/pl/gateway/local-models). - - Zasada kciuka: do zadań o wysokiej stawce używaj **najlepszego modelu, na jaki Cię stać**, a tańszego - modelu do rutynowego czatu lub podsumowań. Możesz kierować modele per agent i używać subagentów do - równoleglenia długich zadań (każdy subagent zużywa tokeny). Zobacz [Models](/pl/concepts/models) i - [Sub-agents](/pl/tools/subagents). - - Mocne ostrzeżenie: słabsze/nadmiernie kwantyzowane modele są bardziej podatne na prompt - injection i niebezpieczne zachowanie. Zobacz [Security](/pl/gateway/security). - - Więcej kontekstu: [Models](/pl/concepts/models). - - - - - Używaj **poleceń modelu** albo edytuj tylko pola **modelu**. Unikaj pełnego zastępowania configu. - - Bezpieczne opcje: - - - `/model` na czacie (szybko, per sesja) - - `openclaw models set ...` (aktualizuje tylko config modelu) - - `openclaw configure --section model` (interaktywnie) - - edytuj `agents.defaults.model` w `~/.openclaw/openclaw.json` - - Unikaj `config.apply` z obiektem częściowym, chyba że zamierzasz zastąpić cały config. - Przy edycjach RPC najpierw sprawdzaj przez `config.schema.lookup` i preferuj `config.patch`. Payload lookup daje znormalizowaną ścieżkę, płytką dokumentację/ograniczenia schematu i podsumowania bezpośrednich dzieci - dla częściowych aktualizacji. - Jeśli jednak nadpisałeś config, przywróć go z kopii zapasowej albo uruchom ponownie `openclaw doctor`, aby go naprawić. - - Dokumentacja: [Models](/pl/concepts/models), [Configure](/cli/configure), [Config](/cli/config), [Doctor](/pl/gateway/doctor). - - - - - Tak. Ollama to najłatwiejsza ścieżka dla modeli lokalnych. - - Najszybsza konfiguracja: - - 1. Zainstaluj Ollama z `https://ollama.com/download` - 2. Pobierz lokalny model, np. `ollama pull glm-4.7-flash` - 3. Jeśli chcesz też modele chmurowe, uruchom `ollama signin` - 4. Uruchom `openclaw onboard` i wybierz `Ollama` - 5. Wybierz `Local` albo `Cloud + Local` - - Uwagi: - - - `Cloud + Local` daje Ci modele chmurowe oraz lokalne modele Ollama - - modele chmurowe takie jak `kimi-k2.5:cloud` nie wymagają lokalnego pobrania - - do ręcznego przełączania używaj `openclaw models list` oraz `openclaw models set ollama/` - - Uwaga dotycząca bezpieczeństwa: mniejsze lub mocno kwantyzowane modele są bardziej podatne na \ No newline at end of file + Do modeli odwołuje się jako `provider/model` (przykład: `openai/gpt-5.4`). Jeśli pominiesz providera, OpenClaw najpierw próbuje aliasu, potem unikalnego dopasowania dokładnego identyfikatora modelu wśród skonfigurowanych providerów, a dopiero potem wraca do skonfigurowanego domyślnego providera jako przestarzałej ścieżki zgodności. Jeśli ten provider nie udostępnia już skonfigurowanego modelu domy \ No newline at end of file diff --git a/docs/pl/help/scripts.md b/docs/pl/help/scripts.md index 1e7038294..50d12cee4 100644 --- a/docs/pl/help/scripts.md +++ b/docs/pl/help/scripts.md @@ -1,14 +1,14 @@ --- read_when: - - Uruchamiasz skrypty z repozytorium - - Dodajesz lub zmieniasz skrypty w ./scripts + - Uruchamianie skryptów z repozytorium + - Dodawanie lub zmienianie skryptów w `./scripts` summary: 'Skrypty repozytorium: przeznaczenie, zakres i uwagi dotyczące bezpieczeństwa' title: Skrypty x-i18n: - generated_at: "2026-04-05T13:55:11Z" + generated_at: "2026-04-08T02:14:44Z" model: gpt-5.4 provider: openai - source_hash: de53d64d91c564931bdd4e8b9f4a8e88646332a07cc2a6bf1d517b89debb29cd + source_hash: 3ecf1e9327929948fb75f80e306963af49b353c0aa8d3b6fa532ca964ff8b975 source_path: help/scripts.md workflow: 15 --- @@ -20,15 +20,41 @@ Używaj ich, gdy zadanie jest wyraźnie powiązane ze skryptem; w przeciwnym raz ## Konwencje -- Skrypty są **opcjonalne**, chyba że są wymienione w dokumentacji lub checklistach wydań. -- Preferuj powierzchnie CLI, jeśli istnieją (przykład: monitorowanie uwierzytelniania używa `openclaw models status --check`). -- Zakładaj, że skrypty są zależne od hosta; przeczytaj je przed uruchomieniem na nowej maszynie. +- Skrypty są **opcjonalne**, chyba że odwołuje się do nich dokumentacja lub checklisty wydania. +- Preferuj powierzchnie CLI, gdy istnieją (przykład: monitorowanie uwierzytelniania używa `openclaw models status --check`). +- Zakładaj, że skrypty są specyficzne dla hosta; przeczytaj je przed uruchomieniem na nowej maszynie. ## Skrypty monitorowania uwierzytelniania -Monitorowanie uwierzytelniania opisano w [Uwierzytelnianie](/gateway/authentication). Skrypty w `scripts/` to opcjonalne dodatki dla przepływów systemd/Termux phone. +Monitorowanie uwierzytelniania opisano w [Uwierzytelnianie](/pl/gateway/authentication). Skrypty w `scripts/` to opcjonalne dodatki do przepływów pracy systemd/Termux na telefonie. -## Przy dodawaniu skryptów +## Pomocnik odczytu GitHub -- Utrzymuj skrypty w skupionej formie i dobrze udokumentowane. -- Dodaj krótki wpis w odpowiedniej dokumentacji (lub utwórz ją, jeśli brakuje). +Użyj `scripts/gh-read`, gdy chcesz, aby `gh` używało tokenu instalacji GitHub App do wywołań odczytu ograniczonych do repozytorium, pozostawiając zwykłe `gh` na twoim osobistym loginie do działań zapisu. + +Wymagane zmienne środowiskowe: + +- `OPENCLAW_GH_READ_APP_ID` +- `OPENCLAW_GH_READ_PRIVATE_KEY_FILE` + +Opcjonalne zmienne środowiskowe: + +- `OPENCLAW_GH_READ_INSTALLATION_ID`, gdy chcesz pominąć wyszukiwanie instalacji na podstawie repozytorium +- `OPENCLAW_GH_READ_PERMISSIONS` jako rozdzielane przecinkami zastąpienie podzbioru uprawnień odczytu do zażądania + +Kolejność rozwiązywania repozytorium: + +- `gh ... -R owner/repo` +- `GH_REPO` +- `git remote origin` + +Przykłady: + +- `scripts/gh-read pr view 123` +- `scripts/gh-read run list -R openclaw/openclaw` +- `scripts/gh-read api repos/openclaw/openclaw/pulls/123` + +## Podczas dodawania skryptów + +- Zachowuj skupienie skryptów i dokumentuj je. +- Dodaj krótki wpis w odpowiednim dokumencie (lub utwórz go, jeśli go brakuje). diff --git a/docs/pl/help/testing.md b/docs/pl/help/testing.md index 479fde0c2..0ae7fbdcd 100644 --- a/docs/pl/help/testing.md +++ b/docs/pl/help/testing.md @@ -3,105 +3,105 @@ read_when: - Uruchamianie testów lokalnie lub w CI - Dodawanie regresji dla błędów modeli/dostawców - Debugowanie zachowania gateway + agenta -summary: 'Zestaw testów: pakiety unit/e2e/live, runnery Docker i zakres każdego testu' +summary: 'Pakiet testów: zestawy unit/e2e/live, uruchamianie w Dockerze i zakres każdego testu' title: Testowanie x-i18n: - generated_at: "2026-04-07T09:48:01Z" + generated_at: "2026-04-08T02:17:20Z" model: gpt-5.4 provider: openai - source_hash: c02b5852e8893f76ecbc9a902108099c55764d7a5c9270b55a0fa113cba01bfb + source_hash: ace2c19bfc350780475f4348264a4b55be2b4ccbb26f0d33b4a6af34510943b5 source_path: help/testing.md workflow: 15 --- # Testowanie -OpenClaw ma trzy pakiety Vitest (unit/integration, e2e, live) oraz niewielki zestaw runnerów Docker. +OpenClaw ma trzy zestawy Vitest (unit/integration, e2e, live) oraz niewielki zestaw uruchomień w Dockerze. Ten dokument to przewodnik „jak testujemy”: -- Co obejmuje każdy pakiet testów (i czego celowo _nie_ obejmuje) -- Jakie polecenia uruchamiać w typowych przepływach pracy (lokalnie, przed push, debugowanie) +- Co obejmuje każdy zestaw (i czego celowo _nie_ obejmuje) +- Jakie polecenia uruchamiać w typowych przepływach pracy (lokalnie, przed pushem, debugowanie) - Jak testy live wykrywają poświadczenia i wybierają modele/dostawców - Jak dodawać regresje dla rzeczywistych problemów modeli/dostawców ## Szybki start -Na co dzień: +W większość dni: -- Pełna bramka (oczekiwana przed push): `pnpm build && pnpm check && pnpm test` -- Szybsze lokalne uruchomienie pełnego pakietu na mocniejszej maszynie: `pnpm test:max` +- Pełna bramka (oczekiwana przed pushem): `pnpm build && pnpm check && pnpm test` +- Szybsze lokalne uruchomienie pełnego zestawu na wydajnej maszynie: `pnpm test:max` - Bezpośrednia pętla watch Vitest: `pnpm test:watch` -- Bezpośrednie wskazywanie plików teraz trasuje też ścieżki extension/channel: `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` -- Witryna QA oparta na Dockerze: `pnpm qa:lab:up` +- Bezpośrednie kierowanie na plik teraz obsługuje też ścieżki extension/channel: `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` +- Strona QA wsparta Dockerem: `pnpm qa:lab:up` -Gdy modyfikujesz testy albo chcesz mieć większą pewność: +Gdy dotykasz testów lub chcesz mieć większą pewność: - Bramka pokrycia: `pnpm test:coverage` -- Pakiet E2E: `pnpm test:e2e` +- Zestaw E2E: `pnpm test:e2e` Podczas debugowania rzeczywistych dostawców/modeli (wymaga prawdziwych poświadczeń): -- Pakiet live (modele + testy gateway dla narzędzi/obrazów): `pnpm test:live` -- Uruchom cicho jeden plik live: `pnpm test:live -- src/agents/models.profiles.live.test.ts` +- Zestaw live (modele + sondy narzędzi/obrazów gateway): `pnpm test:live` +- Ciche uruchomienie jednego pliku live: `pnpm test:live -- src/agents/models.profiles.live.test.ts` -Wskazówka: gdy potrzebujesz tylko jednego wadliwego przypadku, zawężaj testy live za pomocą zmiennych środowiskowych allowlist opisanych poniżej. +Wskazówka: gdy potrzebujesz tylko jednego nieudanego przypadku, zawęź testy live za pomocą zmiennych środowiskowych allowlist opisanych poniżej. -## Pakiety testów (co uruchamia się gdzie) +## Zestawy testów (co uruchamia się gdzie) -Traktuj pakiety jako „rosnący realizm” (i rosnącą niestabilność/koszt): +Potraktuj zestawy jako „rosnący realizm” (i rosnącą niestabilność/koszt): -### Unit / integration (domyślnie) +### 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 dopuszczone testy node w `ui`, objęte przez `vitest.unit.config.ts` +- Konfiguracja: dziesięć sekwencyjnych uruchomień shardów (`vitest.full-*.config.ts`) na istniejących zakresowych projektach Vitest +- Pliki: inwentarze core/unit w `src/**/*.test.ts`, `packages/**/*.test.ts`, `test/**/*.test.ts` oraz dozwolone testy node `ui` objęte przez `vitest.unit.config.ts` - Zakres: - Czyste testy jednostkowe - - Testy integracyjne w procesie (uwierzytelnianie gateway, routing, narzędzia, parsowanie, konfiguracja) - - Deterministyczne regresje dla znanych błędów + - Testy integracyjne w procesie (auth gateway, routing, narzędzia, parsowanie, konfiguracja) + - Deterministyczne regresje znanych błędów - Oczekiwania: - - Uruchamiane w CI + - Uruchamiają się w CI - Nie wymagają prawdziwych kluczy - Powinny być szybkie i stabilne - Uwaga o projektach: - - Niezawężone `pnpm test` uruchamia teraz jedenaście mniejszych konfiguracji shardów (`core-unit-src`, `core-unit-security`, `core-unit-ui`, `core-unit-support`, `core-support-boundary`, `core-contracts`, `core-bundled`, `core-runtime`, `agentic`, `auto-reply`, `extensions`) zamiast jednego ogromnego natywnego procesu root-project. Zmniejsza to szczytowe RSS na obciążonych maszynach i zapobiega temu, by praca auto-reply/extension zagłodziła niezwiązane pakiety. + - Niekierowane `pnpm test` uruchamia teraz jedenaście mniejszych konfiguracji shardów (`core-unit-src`, `core-unit-security`, `core-unit-ui`, `core-unit-support`, `core-support-boundary`, `core-contracts`, `core-bundled`, `core-runtime`, `agentic`, `auto-reply`, `extensions`) zamiast jednego ogromnego natywnego procesu root-project. Zmniejsza to szczytowe RSS na obciążonych maszynach i zapobiega temu, by prace `auto-reply`/extension blokowały niezwiązane zestawy. - `pnpm test --watch` nadal używa natywnego grafu projektów root `vitest.config.ts`, ponieważ wieloszardowa pętla watch nie jest praktyczna. - - `pnpm test`, `pnpm test:watch` i `pnpm test:perf:imports` kierują jawne cele plików/katalogów najpierw przez zawężone lane’y, więc `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` nie płaci kosztu pełnego uruchomienia projektu root. - - `pnpm test:changed` rozwija zmienione ścieżki git do tych samych zawężonych lane’ów, gdy diff dotyka tylko trasowalnych plików źródłowych/testowych; zmiany konfiguracji/setup nadal wracają do szerokiego ponownego uruchomienia root-project. - - Wybrane testy `plugin-sdk` i `commands` są także kierowane przez dedykowane lekkie lane’y, które pomijają `test/setup-openclaw-runtime.ts`; pliki stanowe/ciężkie runtime’owo pozostają na istniejących lane’ach. - - Wybrane pliki pomocnicze źródeł `plugin-sdk` i `commands` również mapują przebiegi changed-mode na jawne testy siostrzane w tych lekkich lane’ach, więc edycje helperów nie wymuszają ponownego uruchamiania całego ciężkiego pakietu dla tego katalogu. - - `auto-reply` ma teraz trzy dedykowane koszyki: pomocniki core najwyższego poziomu, integracyjne testy `reply.*` najwyższego poziomu oraz poddrzewo `src/auto-reply/reply/**`. Dzięki temu najcięższa praca harnessu odpowiedzi jest oddzielona od tanich testów status/chunk/token. -- Uwaga o embedded runner: - - Gdy zmieniasz wejścia wykrywania message-tool albo kontekst runtime kompaktowania, - utrzymuj oba poziomy pokrycia. - - Dodawaj ukierunkowane regresje helperów dla czystych granic routingu/normalizacji. - - Utrzymuj też w dobrej kondycji pakiety integracyjne embedded runner: + - `pnpm test`, `pnpm test:watch` i `pnpm test:perf:imports` kierują jawne cele plików/katalogów najpierw przez zakresowe ścieżki, więc `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` unika kosztu pełnego startu root project. + - `pnpm test:changed` rozwija zmienione ścieżki git do tych samych zakresowych ścieżek, gdy diff dotyczy tylko routowalnych plików źródłowych/testowych; edycje config/setup nadal wracają do szerokiego ponownego uruchomienia root-project. + - Wybrane testy `plugin-sdk` i `commands` także są kierowane przez dedykowane lekkie ścieżki, które pomijają `test/setup-openclaw-runtime.ts`; pliki stanowe/ciężkie runtime pozostają na istniejących ścieżkach. + - Wybrane pliki źródłowe helperów `plugin-sdk` i `commands` także mapują uruchomienia w trybie changed do jawnych testów sąsiednich w tych lekkich ścieżkach, więc edycje helperów unikają ponownego uruchamiania pełnego ciężkiego zestawu dla tego katalogu. + - `auto-reply` ma teraz trzy dedykowane koszyki: helpery najwyższego poziomu rdzenia, integracyjne testy najwyższego poziomu `reply.*` oraz poddrzewo `src/auto-reply/reply/**`. Dzięki temu najcięższa praca harnessu reply nie trafia do tanich testów status/chunk/token. +- Uwaga o osadzonym runnerze: + - Gdy zmieniasz wejścia wykrywania narzędzi wiadomości lub kontekst runtime kompaktowania, + zachowaj oba poziomy pokrycia. + - Dodaj ukierunkowane regresje helperów dla czystych granic routingu/normalizacji. + - Utrzymuj też w zdrowiu osadzone zestawy integracyjne: `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 id i zachowanie kompaktowania nadal przechodzą - przez rzeczywiste ścieżki `run.ts` / `compact.ts`; testy samych helperów nie są + - Te zestawy weryfikują, że zakresowe identyfikatory i zachowanie kompaktowania nadal przepływają + przez rzeczywiste ścieżki `run.ts` / `compact.ts`; testy tylko helperów nie są wystarczającym zamiennikiem dla tych ścieżek integracyjnych. -- Uwaga o pool: +- Uwaga o puli: - Bazowa konfiguracja Vitest domyślnie używa teraz `threads`. - - Współdzielona konfiguracja Vitest wymusza także `isolate: false` i używa nieizolowanego runnera w projektach root, konfiguracjach e2e i live. - - Główny lane UI zachowuje ustawienia `jsdom` i optimizer, ale teraz również działa na współdzielonym nieizolowanym runnerze. - - Każdy shard `pnpm test` dziedziczy te same domyślne `threads` + `isolate: false` ze współdzielonej konfiguracji Vitest. - - Współdzielony launcher `scripts/run-vitest.mjs` domyślnie dodaje teraz także `--no-maglev` dla procesów potomnych Node uruchamianych przez Vitest, aby zmniejszyć churn kompilacji V8 przy dużych lokalnych przebiegach. Ustaw `OPENCLAW_VITEST_ENABLE_MAGLEV=1`, jeśli chcesz porównać zachowanie ze standardowym V8. -- Uwaga o szybkiej iteracji lokalnej: - - `pnpm test:changed` kieruje przebiegi przez zawężone lane’y, gdy zmienione ścieżki da się czysto odwzorować na mniejszy pakiet. - - `pnpm test:max` i `pnpm test:changed:max` zachowują to samo trasowanie, tylko z wyższym limitem workerów. - - Lokalne automatyczne skalowanie workerów jest teraz celowo zachowawcze i dodatkowo wycofuje się, gdy średnie obciążenie hosta jest już wysokie, więc wiele równoległych uruchomień Vitest domyślnie robi mniej szkód. - - Bazowa konfiguracja Vitest oznacza pliki projektów/konfiguracji jako `forceRerunTriggers`, aby ponowne uruchomienia changed-mode pozostawały poprawne po zmianie 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ą jawną lokalizację cache do bezpośredniego profilowania. + - Współdzielona konfiguracja Vitest ustawia też `isolate: false` i używa nieizolowanego runnera w root projects, konfiguracjach e2e i live. + - Ścieżka root UI zachowuje konfigurację i optymalizator `jsdom`, ale teraz działa również na współdzielonym nieizolowanym runnerze. + - Każdy shard `pnpm test` dziedziczy te same ustawienia `threads` + `isolate: false` ze współdzielonej konfiguracji Vitest. + - Współdzielony launcher `scripts/run-vitest.mjs` domyślnie dodaje teraz także `--no-maglev` dla podrzędnych procesów Node Vitest, aby zmniejszyć churn kompilacji V8 podczas dużych lokalnych uruchomień. Ustaw `OPENCLAW_VITEST_ENABLE_MAGLEV=1`, jeśli chcesz porównać zachowanie ze standardowym V8. +- Uwaga o szybkiej lokalnej iteracji: + - `pnpm test:changed` kieruje przez zakresowe ścieżki, gdy zmienione ścieżki dają się czysto zmapować na mniejszy zestaw. + - `pnpm test:max` i `pnpm test:changed:max` zachowują to samo kierowanie, tylko z wyższym limitem workerów. + - Lokalne automatyczne skalowanie workerów jest teraz celowo konserwatywne i także wycofuje się, gdy średnie obciążenie hosta jest już wysokie, więc wiele równoległych uruchomień Vitest domyślnie powoduje mniej szkód. + - Bazowa konfiguracja Vitest oznacza pliki projektów/konfiguracji jako `forceRerunTriggers`, aby ponowne uruchomienia w trybie changed były poprawne, gdy zmienia się okablowanie testów. + - Konfiguracja utrzymuje `OPENCLAW_VITEST_FS_MODULE_CACHE` w stanie włączonym na obsługiwanych hostach; ustaw `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/abs/path`, jeśli chcesz jedną jawną lokalizację cache do bezpośredniego profilowania. - Uwaga o debugowaniu wydajności: - - `pnpm test:perf:imports` włącza raportowanie czasu importu Vitest oraz rozbicie importów. + - `pnpm test:perf:imports` włącza raportowanie czasu importów Vitest oraz wyjście rozbicia importów. - `pnpm test:perf:imports:changed` zawęża ten sam widok profilowania do plików zmienionych względem `origin/main`. -- `pnpm test:perf:changed:bench -- --ref ` porównuje trasowane `test:changed` z natywną ścieżką root-project dla tego zatwierdzonego diffu i wypisuje czas ścienny oraz maksymalne RSS w macOS. -- `pnpm test:perf:changed:bench -- --worktree` benchmarkuje bieżące brudne drzewo, trasując listę zmienionych plików przez `scripts/test-projects.mjs` i konfigurację root Vitest. +- `pnpm test:perf:changed:bench -- --ref ` porównuje routowane `test:changed` z natywną ścieżką root-project dla tego zatwierdzonego diffu i wypisuje wall time oraz maksymalne RSS na macOS. +- `pnpm test:perf:changed:bench -- --worktree` benchmarkuje bieżące brudne drzewo, kierując listę zmienionych plików przez `scripts/test-projects.mjs` i konfigurację root Vitest. - `pnpm test:perf:profile:main` zapisuje profil CPU głównego wątku dla narzutu startu i transformacji Vitest/Vite. - - `pnpm test:perf:profile:runner` zapisuje profile CPU+heap runnera dla pakietu unit z wyłączonym parallelismem plików. + - `pnpm test:perf:profile:runner` zapisuje profile CPU+heap runnera dla zestawu unit przy wyłączonej równoległości plików. ### E2E (smoke gateway) @@ -109,19 +109,19 @@ Traktuj pakiety jako „rosnący realizm” (i rosnącą niestabilność/koszt): - 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 `threads` Vitest z `isolate: false`, zgodnie z resztą repozytorium. - Używa adaptacyjnych workerów (CI: do 2, lokalnie: domyślnie 1). - Domyślnie działa w trybie silent, aby zmniejszyć narzut I/O konsoli. - Przydatne nadpisania: - - `OPENCLAW_E2E_WORKERS=` aby wymusić liczbę workerów (ograniczoną do 16). - - `OPENCLAW_E2E_VERBOSE=1` aby ponownie włączyć szczegółowe logi konsoli. + - `OPENCLAW_E2E_WORKERS=` aby wymusić liczbę workerów (maksymalnie 16). + - `OPENCLAW_E2E_VERBOSE=1` aby ponownie włączyć szczegółowe wyjście konsoli. - Zakres: - - Kompletny przebieg end-to-end gateway dla wielu instancji - - Powierzchnie WebSocket/HTTP, parowanie węzłów i cięższe ścieżki sieciowe + - Zachowanie end-to-end wielu instancji gateway + - Powierzchnie WebSocket/HTTP, parowanie węzłów i cięższa komunikacja sieciowa - Oczekiwania: - - Uruchamiane w CI (gdy włączone w pipeline) - - Nie wymagają prawdziwych kluczy - - Więcej ruchomych części niż testy unit (mogą być wolniejsze) + - Uruchamia się w CI (gdy włączone w pipeline) + - Nie wymaga prawdziwych kluczy + - Ma więcej ruchomych części niż testy jednostkowe (może być wolniejszy) ### E2E: smoke backendu OpenShell @@ -130,15 +130,15 @@ Traktuj pakiety jako „rosnący realizm” (i rosnącą niestabilność/koszt): - Zakres: - Uruchamia odizolowany gateway OpenShell na hoście przez Docker - Tworzy sandbox z tymczasowego lokalnego Dockerfile - - Testuje backend OpenShell OpenClaw przez rzeczywiste `sandbox ssh-config` + SSH exec - - Weryfikuje zdalno-kanoniczne zachowanie systemu plików przez most fs sandboxa + - Testuje backend OpenShell OpenClaw przez prawdziwe `sandbox ssh-config` + SSH exec + - Weryfikuje zdalnie kanoniczne zachowanie systemu plików przez most fs sandboxa - Oczekiwania: - - Tylko opt-in; nie jest częścią domyślnego przebiegu `pnpm test:e2e` + - 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 odizolowanego `HOME` / `XDG_CONFIG_HOME`, a następnie niszczy testowy gateway i sandbox + - Używa odizolowanych `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_COMMAND=/path/to/openshell` aby wskazać niestandardowy binarny CLI lub skrypt wrapper + - `OPENCLAW_E2E_OPENSHELL=1` aby włączyć test podczas ręcznego uruchamiania szerszego zestawu e2e + - `OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell` aby wskazać niestandardowy binarny plik CLI lub skrypt opakowujący ### Live (prawdziwi dostawcy + prawdziwe modele) @@ -148,64 +148,64 @@ Traktuj pakiety jako „rosnący realizm” (i rosnącą niestabilność/koszt): - 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?” - - Wychwytuje zmiany formatów dostawców, niuanse wywołań narzędzi, problemy z uwierzytelnianiem i zachowanie limitów + - Wykrywanie zmian formatów dostawców, osobliwości wywołań narzędzi, problemów auth i zachowania limitów szybkości - Oczekiwania: - - Z założenia niestabilne w CI (prawdziwe sieci, prawdziwe polityki dostawców, limity, awarie) - - Kosztują pieniądze / zużywają limity - - Lepiej uruchamiać zawężone podzbiory zamiast „wszystkiego” -- Przebiegi live wykonują `source ~/.profile`, aby pobrać brakujące klucze API. -- Domyślnie przebiegi live nadal izolują `HOME` i kopiują materiał konfiguracyjny/uwierzytelniający do tymczasowego katalogu testowego, aby fixtury unit nie mogły modyfikować Twojego prawdziwego `~/.openclaw`. -- Ustaw `OPENCLAW_LIVE_USE_REAL_HOME=1` tylko wtedy, gdy świadomie chcesz, aby testy live używały Twojego rzeczywistego katalogu domowego. -- `pnpm test:live` domyślnie działa teraz ciszej: zachowuje wyjście postępu `[live] ...`, ale ukrywa dodatkową informację o `~/.profile` i wycisza logi startowe gateway / szum 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 przecinki/średniki lub `*_API_KEY_1`, `*_API_KEY_2` (na przykład `OPENAI_API_KEYS`, `ANTHROPIC_API_KEYS`, `GEMINI_API_KEYS`) albo nadpisanie per-live przez `OPENCLAW_LIVE_*_KEY`; testy ponawiają próby po odpowiedziach o limicie. -- Wyjście postępu/heartbeat: - - Pakiety live emitują teraz linie postępu do stderr, więc długie wywołania dostawców są widocznie aktywne nawet wtedy, gdy przechwytywanie konsoli Vitest jest ciche. - - `vitest.live.config.ts` wyłącza przechwytywanie konsoli przez Vitest, aby linie postępu dostawcy/gateway były strumieniowane natychmiast podczas przebiegów live. - - Heartbeat modeli bezpośrednich można regulować przez `OPENCLAW_LIVE_HEARTBEAT_MS`. - - Heartbeat gateway/probe można regulować przez `OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS`. + - Z założenia niestabilne w CI (prawdziwe sieci, prawdziwe zasady dostawców, limity, awarie) + - Kosztują pieniądze / zużywają limity szybkości + - Lepiej uruchamiać zawężone podzbiory niż „wszystko” +- Uruchomienia live wczytują `~/.profile`, aby pobrać brakujące klucze API. +- Domyślnie uruchomienia live nadal izolują `HOME` i kopiują materiał config/auth do tymczasowego katalogu domowego testu, tak aby fixture unit nie mogły modyfikować twojego prawdziwego `~/.openclaw`. +- Ustaw `OPENCLAW_LIVE_USE_REAL_HOME=1` tylko wtedy, gdy świadomie chcesz, aby testy live używały twojego prawdziwego katalogu domowego. +- `pnpm test:live` domyślnie działa teraz ciszej: zachowuje wyjście postępu `[live] ...`, ale wycisza dodatkową informację o `~/.profile` i wyłącza logi bootstrapu gateway / szum Bonjour. Ustaw `OPENCLAW_LIVE_TEST_QUIET=0`, jeśli chcesz przywrócić pełne logi startowe. +- Rotacja kluczy API (specyficzna dla dostawcy): ustaw `*_API_KEYS` w formacie z przecinkami/średnikami albo `*_API_KEY_1`, `*_API_KEY_2` (na przykład `OPENAI_API_KEYS`, `ANTHROPIC_API_KEYS`, `GEMINI_API_KEYS`) albo per-live override przez `OPENCLAW_LIVE_*_KEY`; testy ponawiają próby po odpowiedziach z limitem szybkości. +- Wyjście postępu/heartbeatów: + - Zestawy live wypisują teraz linie postępu do stderr, aby długie wywołania dostawców były widocznie aktywne nawet wtedy, gdy przechwytywanie konsoli Vitest jest ciche. + - `vitest.live.config.ts` wyłącza przechwytywanie konsoli Vitest, więc linie postępu dostawcy/gateway są strumieniowane natychmiast podczas uruchomień live. + - Dostosuj heartbeaty bezpośredniego modelu przez `OPENCLAW_LIVE_HEARTBEAT_MS`. + - Dostosuj heartbeaty gateway/probe przez `OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS`. -## Który pakiet powinienem uruchomić? +## Który zestaw powinienem uruchomić? Użyj tej tabeli decyzyjnej: -- Edycja logiki/testów: uruchom `pnpm test` (i `pnpm test:coverage`, jeśli zmieniło się dużo) -- Zmiany w sieci gateway / protokole WS / parowaniu: dodaj `pnpm test:e2e` -- Debugowanie „mój bot nie działa” / awarii 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 komunikacji gateway / protokołu WS / parowania: dodaj `pnpm test:e2e` +- Debugowanie „mój bot nie działa” / awarii specyficznych dla dostawcy / wywoływania narzędzi: uruchom zawężone `pnpm test:live` -## Live: przegląd możliwości węzła Android +## Live: przegląd możliwości węzła Androida - Test: `src/gateway/android-node.capabilities.live.test.ts` - Skrypt: `pnpm android:test:integration` -- Cel: wywołać **każde polecenie aktualnie reklamowane** przez podłączony węzeł Android i potwierdzić zachowanie kontraktu poleceń. +- Cel: wywołać **każde aktualnie reklamowane polecenie** podłączonego węzła Androida i potwierdzić zachowanie kontraktu poleceń. - Zakres: - - Ręczny setup wstępny / setup zależny od warunków (pakiet nie instaluje/nie uruchamia/nie paruje aplikacji). - - Walidacja `node.invoke` gateway polecenie po poleceniu dla wybranego węzła Android. -- Wymagany wcześniejszy setup: + - Konfiguracja wstępna/ręczna (zestaw nie instaluje, nie uruchamia ani nie paruje aplikacji). + - Walidacja `node.invoke` gateway polecenie po poleceniu dla wybranego węzła Androida. +- Wymagana wstępna konfiguracja: - Aplikacja Android jest już połączona i sparowana z gateway. - - Aplikacja jest utrzymywana na pierwszym planie. - - Uprawnienia/zgody przechwytywania są przyznane dla możliwości, które mają przejść. + - Aplikacja pozostaje na pierwszym planie. + - Uprawnienia/zgoda na przechwytywanie są przyznane dla możliwości, które mają przejść. - Opcjonalne nadpisania celu: - `OPENCLAW_ANDROID_NODE_ID` lub `OPENCLAW_ANDROID_NODE_NAME`. - `OPENCLAW_ANDROID_GATEWAY_URL` / `OPENCLAW_ANDROID_GATEWAY_TOKEN` / `OPENCLAW_ANDROID_GATEWAY_PASSWORD`. -- Pełne szczegóły konfiguracji Androida: [Android App](/pl/platforms/android) +- Pełne szczegóły konfiguracji Androida: [Aplikacja Android](/pl/platforms/android) -## Live: smoke modeli (klucze profili) +## Live: smoke modeli (klucze profilu) Testy live są podzielone na dwie warstwy, aby można było izolować awarie: -- „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 itp.). +- „Model bezpośredni” mówi nam, czy dostawca/model w ogóle potrafi odpowiedzieć z danym kluczem. +- „Smoke gateway” mówi nam, czy pełny pipeline gateway+agent działa dla tego modelu (sesje, historia, narzędzia, polityka sandboxa itd.). ### Warstwa 1: bezpośrednie completion modelu (bez gateway) - Test: `src/agents/models.profiles.live.test.ts` - Cel: - Wyliczyć wykryte modele - - Użyć `getApiKeyForModel` do wyboru modeli, dla których masz poświadczenia - - Uruchomić małe completion dla każdego modelu (oraz ukierunkowane regresje tam, gdzie potrzeba) + - Użyć `getApiKeyForModel` do wyboru modeli, do których masz poświadczenia + - Wykonać małe completion dla każdego modelu (oraz ukierunkowane regresje tam, gdzie potrzeba) - Jak włączyć: - - `pnpm test:live` (lub `OPENCLAW_LIVE_TEST=1`, jeśli uruchamiasz Vitest bezpośrednio) -- Ustaw `OPENCLAW_LIVE_MODELS=modern` (lub `all`, alias dla modern), aby faktycznie uruchomić ten pakiet; w przeciwnym razie jest pomijany, aby `pnpm test:live` pozostawało skupione na gateway smoke + - `pnpm test:live` (lub `OPENCLAW_LIVE_TEST=1`, jeśli wywołujesz Vitest bezpośrednio) +- Ustaw `OPENCLAW_LIVE_MODELS=modern` (lub `all`, alias dla modern), aby faktycznie uruchomić ten zestaw; w przeciwnym razie jest pomijany, aby `pnpm test:live` pozostawało skupione na smoke gateway - Jak wybierać modele: - `OPENCLAW_LIVE_MODELS=modern`, aby uruchomić nowoczesną allowlist (Opus/Sonnet 4.6+, GPT-5.x + Codex, Gemini 3, GLM 4.7, MiniMax M2.7, Grok 4) - `OPENCLAW_LIVE_MODELS=all` jest aliasem dla nowoczesnej allowlist @@ -213,47 +213,47 @@ Testy live są podzielone na dwie warstwy, aby można było izolować awarie: - Jak wybierać dostawców: - `OPENCLAW_LIVE_PROVIDERS="google,google-antigravity,google-gemini-cli"` (allowlist rozdzielana przecinkami) - Skąd pochodzą klucze: - - Domyślnie: ze store profili i fallbacków env - - Ustaw `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, aby wymusić użycie wyłącznie **store profili** + - Domyślnie: magazyn profili i zapasowe zmienne środowiskowe + - Ustaw `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, aby wymusić użycie **wyłącznie magazynu profili** - Dlaczego to istnieje: - - Rozdziela „API dostawcy jest zepsute / klucz jest nieprawidłowy” od „pipeline agenta gateway jest zepsuty” - - Zawiera małe, odizolowane regresje (przykład: replay reasoning OpenAI Responses/Codex Responses + przepływy wywołań narzędzi) + - Oddziela „API dostawcy jest uszkodzone / klucz jest nieprawidłowy” od „pipeline agenta gateway jest uszkodzony” + - Zawiera małe, izolowane regresje (przykład: OpenAI Responses/Codex Responses reasoning replay + przepływy tool-call) -### Warstwa 2: smoke gateway + agenta dev (czyli to, co naprawdę robi „@openclaw”) +### Warstwa 2: smoke gateway + dev agent (to, co faktycznie robi „@openclaw”) - Test: `src/gateway/gateway-models.profiles.live.test.ts` - Cel: - Uruchomić gateway w procesie - - Utworzyć/spatchować sesję `agent:dev:*` (nadpisanie modelu dla każdego przebiegu) - - Iterować po modelach-z-kluczami i potwierdzić: + - Utworzyć/poprawić sesję `agent:dev:*` (nadpisanie modelu na każde uruchomienie) + - Iterować po modelach-z-kluczami i potwierdzać: - „sensowną” odpowiedź (bez narzędzi) - - działanie rzeczywistego wywołania narzędzia (probe odczytu) - - opcjonalne dodatkowe testy narzędzi (probe exec+read) - - że ścieżki regresji OpenAI (tylko wywołanie narzędzia → follow-up) nadal działają -- Szczegóły probe’ów (aby dało się szybko wyjaśnić awarie): - - probe `read`: test zapisuje plik z nonce w workspace i prosi agenta o jego `read` i odesłanie nonce. - - probe `exec+read`: test prosi agenta o zapisanie nonce przez `exec` do pliku tymczasowego, a następnie odczytanie go przez `read`. - - probe obrazu: test dołącza wygenerowany PNG (kot + zrandomizowany 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`. + - że działa prawdziwe wywołanie narzędzia (sonda read) + - opcjonalne dodatkowe sondy narzędzi (sonda exec+read) + - że ścieżki regresji OpenAI (tylko tool-call → follow-up) nadal działają +- Szczegóły sond (aby dało się szybko wyjaśnić awarie): + - sonda `read`: test zapisuje plik nonce w workspace i prosi agenta, aby go `read` i odesłał nonce. + - sonda `exec+read`: test prosi agenta, aby zapisał nonce do pliku tymczasowego przez `exec`, a następnie odczytał go przez `read`. + - sonda obrazu: test dołącza wygenerowany PNG (kot + losowy kod) i oczekuje, że model zwróci `cat `. + - Odniesienie implementacyjne: `src/gateway/gateway-models.profiles.live.test.ts` oraz `src/gateway/live-image-probe.ts`. - Jak włączyć: - - `pnpm test:live` (lub `OPENCLAW_LIVE_TEST=1`, jeśli uruchamiasz Vitest bezpośrednio) + - `pnpm test:live` (lub `OPENCLAW_LIVE_TEST=1`, jeśli wywołujesz Vitest bezpośrednio) - Jak wybierać modele: - Domyślnie: nowoczesna allowlist (Opus/Sonnet 4.6+, GPT-5.x + Codex, Gemini 3, GLM 4.7, MiniMax M2.7, Grok 4) - `OPENCLAW_LIVE_GATEWAY_MODELS=all` jest aliasem dla nowoczesnej allowlist - - Albo ustaw `OPENCLAW_LIVE_GATEWAY_MODELS="provider/model"` (lub listę rozdzielaną przecinkami), aby zawęzić zakres -- Jak wybierać dostawców (aby uniknąć „wszystkiego z OpenRouter”): + - Albo ustaw `OPENCLAW_LIVE_GATEWAY_MODELS="provider/model"` (lub listę rozdzielaną przecinkami), aby zawęzić +- Jak wybierać dostawców (unikaj „wszystko z OpenRouter”): - `OPENCLAW_LIVE_GATEWAY_PROVIDERS="google,google-antigravity,google-gemini-cli,openai,anthropic,zai,minimax"` (allowlist rozdzielana przecinkami) -- Testy narzędzi + obrazów są zawsze włączone w tym teście live: - - probe `read` + probe `exec+read` (obciążenie narzędzi) - - probe obrazu uruchamia się, gdy model deklaruje obsługę wejścia obrazowego - - Przebieg (wysoki poziom): +- Sondy narzędzi + obrazów są zawsze włączone w tym teście live: + - sonda `read` + sonda `exec+read` (obciążenie narzędzi) + - sonda obrazu uruchamia się, gdy model reklamuje obsługę wejścia obrazowego + - Przepływ (na wysokim poziomie): - 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`) - - Embedded agent przekazuje do modelu multimodalną wiadomość użytkownika - - Asercja: odpowiedź zawiera `cat` + kod (tolerancja OCR: drobne błędy są dopuszczalne) + - Osadzony agent przekazuje multimodalną wiadomość użytkownika do modelu + - Potwierdzenie: odpowiedź zawiera `cat` + kod (tolerancja OCR: drobne błędy są dopuszczalne) -Wskazówka: aby zobaczyć, co możesz testować na swojej maszynie (i dokładne id `provider/model`), uruchom: +Wskazówka: aby zobaczyć, co możesz testować na swojej maszynie (i dokładne identyfikatory `provider/model`), uruchom: ```bash openclaw models list @@ -264,21 +264,22 @@ openclaw models list --json - Test: `src/gateway/gateway-cli-backend.live.test.ts` - Cel: zweryfikować pipeline Gateway + agent z użyciem lokalnego backendu CLI, bez dotykania domyślnej konfiguracji. -- Domyślne ustawienia smoke specyficzne dla backendu znajdują się przy definicji `cli-backend.ts` należącej do odpowiedniego rozszerzenia. -- Włączanie: - - `pnpm test:live` (lub `OPENCLAW_LIVE_TEST=1`, jeśli uruchamiasz Vitest bezpośrednio) +- Domyślne ustawienia smoke specyficzne dla backendu znajdują się przy definicji `cli-backend.ts` należącej do danej extension. +- Włączenie: + - `pnpm test:live` (lub `OPENCLAW_LIVE_TEST=1`, jeśli wywołujesz Vitest bezpośrednio) - `OPENCLAW_LIVE_CLI_BACKEND=1` -- Wartości domyślne: +- Domyślne wartości: - Domyślny dostawca/model: `claude-cli/claude-sonnet-4-6` - - Zachowanie command/args/image pochodzi z metadanych odpowiedniej wtyczki backendu CLI. + - Zachowanie polecenia/argumentów/obrazu pochodzi z metadanych wtyczki backendu CLI. - Nadpisania (opcjonalne): - `OPENCLAW_LIVE_CLI_BACKEND_MODEL="codex-cli/gpt-5.4"` - `OPENCLAW_LIVE_CLI_BACKEND_COMMAND="/full/path/to/codex"` - `OPENCLAW_LIVE_CLI_BACKEND_ARGS='["exec","--json","--color","never","--sandbox","read-only","--skip-git-repo-check"]'` - - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_PROBE=1`, aby wysłać 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 wstrzykiwania do promptu. - - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_MODE="repeat"` (lub `"list"`), aby kontrolować sposób przekazywania argumentów obrazów, gdy ustawiono `IMAGE_ARG`. + - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_PROBE=1`, aby wysłać prawdziwy załącznik obrazu (ścieżki są wstrzykiwane do promptu). + - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_ARG="--image"`, aby przekazywać ścieżki plików obrazu jako argumenty CLI zamiast przez wstrzykiwanie do promptu. + - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_MODE="repeat"` (lub `"list"`), aby kontrolować sposób przekazywania argumentów obrazu, gdy ustawiono `IMAGE_ARG`. - `OPENCLAW_LIVE_CLI_BACKEND_RESUME_PROBE=1`, aby wysłać drugą turę i zweryfikować przepływ wznowienia. + - `OPENCLAW_LIVE_CLI_BACKEND_MODEL_SWITCH_PROBE=0`, aby wyłączyć domyślną sondę ciągłości tej samej sesji Claude Sonnet -> Opus (ustaw `1`, aby wymusić ją, gdy wybrany model obsługuje cel przełączenia). Przykład: @@ -288,13 +289,13 @@ OPENCLAW_LIVE_CLI_BACKEND=1 \ pnpm test:live src/gateway/gateway-cli-backend.live.test.ts ``` -Recepta Docker: +Przepis Docker: ```bash pnpm test:docker:live-cli-backend ``` -Recepty Docker dla pojedynczego dostawcy: +Przepisy Docker dla pojedynczego dostawcy: ```bash pnpm test:docker:live-cli-backend:claude @@ -305,25 +306,26 @@ pnpm test:docker:live-cli-backend:gemini Uwagi: - Runner Docker znajduje się w `scripts/test-live-cli-backend-docker.sh`. -- Uruchamia smoke live backendu CLI wewnątrz obrazu Docker repozytorium jako użytkownik nie-root `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 `OPENCLAW_DOCKER_CLI_TOOLS_DIR` (domyślnie: `~/.cache/openclaw/docker-cli-tools`). +- Uruchamia smoke live backendu CLI wewnątrz obrazu Docker repozytorium jako nieuprzywilejowany użytkownik `node`. +- Rozwiązuje metadane smoke CLI z należącej do niego extension, a następnie instaluje odpowiadający pakiet Linux CLI (`@anthropic-ai/claude-code`, `@openai/codex` lub `@google/gemini-cli`) do zapisywalnego prefiksu cache w `OPENCLAW_DOCKER_CLI_TOOLS_DIR` (domyślnie: `~/.cache/openclaw/docker-cli-tools`). - Smoke live backendu CLI testuje teraz ten sam pełny przepływ end-to-end dla Claude, Codex i Gemini: tura tekstowa, tura klasyfikacji obrazu, a następnie wywołanie narzędzia MCP `cron` zweryfikowane przez gateway CLI. +- Domyślny smoke Claude dodatkowo poprawia sesję z Sonnet do Opus i weryfikuje, że wznowiona sesja nadal pamięta wcześniejszą notatkę. -## Live: smoke ACP bind (`/acp spawn ... --bind here`) +## Live: smoke powiązania ACP (`/acp spawn ... --bind here`) - Test: `src/gateway/gateway-acp-bind.live.test.ts` -- Cel: zweryfikować rzeczywisty przepływ conversation-bind ACP z żywym agentem ACP: +- Cel: zweryfikować rzeczywisty przepływ bind rozmowy ACP z live agentem ACP: - wysłać `/acp spawn --bind here` - - powiązać syntetyczną konwersację kanału wiadomości w miejscu - - wysłać zwykły follow-up w tej samej konwersacji - - sprawdzić, że follow-up trafia do transkryptu powiązanej sesji ACP -- Włączanie: + - 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 +- Włączenie: - `pnpm test:live src/gateway/gateway-acp-bind.live.test.ts` - `OPENCLAW_LIVE_ACP_BIND=1` -- Wartości domyślne: +- Domyślne wartości: - Agenci ACP w Dockerze: `claude,codex,gemini` - Agent ACP dla bezpośredniego `pnpm test:live ...`: `claude` - - Kanał syntetyczny: kontekst konwersacji typu Slack DM + - Syntetyczny kanał: kontekst rozmowy w stylu Slack DM - Backend ACP: `acpx` - Nadpisania: - `OPENCLAW_LIVE_ACP_BIND_AGENT=claude` @@ -332,8 +334,8 @@ Uwagi: - `OPENCLAW_LIVE_ACP_BIND_AGENTS=claude,codex,gemini` - `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND='npx -y @agentclientprotocol/claude-agent-acp@'` - Uwagi: - - Ten lane używa powierzchni gateway `chat.send` z polami syntetycznej trasy źródłowej tylko dla administratora, aby testy mogły dołączyć kontekst kanału wiadomości bez udawania dostarczenia z zewnątrz. - - Gdy `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND` nie jest ustawione, test używa wbudowanego rejestru agentów odpowiedniej wtyczki `acpx` dla wybranego agenta harness ACP. + - Ta ścieżka używa powierzchni gateway `chat.send` z polami syntetycznej ścieżki źródłowej dostępnymi tylko dla administratora, dzięki czemu testy mogą dołączać kontekst kanału wiadomości bez udawania dostarczenia zewnętrznego. + - Gdy `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND` nie jest ustawione, test używa wbudowanego rejestru agentów wtyczki `acpx` dla wybranego agenta harness ACP. Przykład: @@ -343,13 +345,13 @@ OPENCLAW_LIVE_ACP_BIND=1 \ pnpm test:live src/gateway/gateway-acp-bind.live.test.ts ``` -Recepta Docker: +Przepis Docker: ```bash pnpm test:docker:live-acp-bind ``` -Recepty Docker dla pojedynczego agenta: +Przepisy Docker dla pojedynczego agenta: ```bash pnpm test:docker:live-acp-bind:claude @@ -360,19 +362,19 @@ pnpm test:docker:live-acp-bind:gemini Uwagi Docker: - Runner Docker znajduje się w `scripts/test-live-acp-bind-docker.sh`. -- Domyślnie uruchamia smoke ACP bind dla wszystkich obsługiwanych agentów live CLI po kolei: `claude`, `codex`, potem `gemini`. +- Domyślnie uruchamia smoke bind ACP dla wszystkich obsługiwanych live agentów CLI po kolei: `claude`, `codex`, potem `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. -- Wykonuje `source ~/.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. -- W Dockerze runner ustawia `OPENCLAW_LIVE_ACP_BIND_ACPX_COMMAND=$HOME/.npm-global/bin/acpx`, aby acpx zachował zmienne env dostawcy z załadowanego profilu dla podrzędnego CLI harnessu. +- Wczytuje `~/.profile`, przygotowuje odpowiadający materiał auth CLI do kontenera, instaluje `acpx` do zapisywalnego prefiksu npm, a następnie instaluje wymagane live CLI (`@anthropic-ai/claude-code`, `@openai/codex` lub `@google/gemini-cli`), jeśli go brakuje. +- Wewnątrz Dockera runner ustawia `OPENCLAW_LIVE_ACP_BIND_ACPX_COMMAND=$HOME/.npm-global/bin/acpx`, aby `acpx` zachował zmienne środowiskowe dostawcy z wczytanego profilu dostępne dla podrzędnego CLI harnessu. -### Zalecane recepty live +### Zalecane przepisy live -Wąskie, jawne allowlist są najszybsze i najmniej podatne na niestabilność: +Wąskie, jawne allowlisty są najszybsze i najmniej podatne na niestabilność: -- Pojedynczy model, direct (bez gateway): +- Pojedynczy model, bezpośrednio (bez gateway): - `OPENCLAW_LIVE_MODELS="openai/gpt-5.4" pnpm test:live src/agents/models.profiles.live.test.ts` -- Pojedynczy model, gateway smoke: +- Pojedynczy model, smoke gateway: - `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` - Wywoływanie narzędzi przez kilku dostawców: @@ -384,35 +386,35 @@ Wąskie, jawne allowlist są najszybsze i najmniej podatne na niestabilność: Uwagi: -- `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). -- API Gemini vs Gemini CLI: - - API: OpenClaw wywołuje hostowane API Gemini Google przez HTTP (uwierzytelnianie przez klucz API / profil); to właśnie większość użytkowników ma na myśli, mówiąc „Gemini”. - - CLI: OpenClaw uruchamia lokalny binarny `gemini`; ma własne uwierzytelnianie i może zachowywać się inaczej (strumieniowanie/obsługa narzędzi/rozjazd wersji). +- `google/...` używa Gemini API (klucz API). +- `google-antigravity/...` używa mostu OAuth Antigravity (punkt końcowy agenta w stylu Cloud Code Assist). +- `google-gemini-cli/...` używa lokalnego Gemini CLI na twojej maszynie (osobne auth + osobliwości narzędzi). +- Gemini API vs Gemini CLI: + - API: OpenClaw wywołuje hostowane Gemini API Google przez HTTP (auth przez klucz API / profil); to właśnie większość użytkowników ma na myśli, mówiąc „Gemini”. + - CLI: OpenClaw wywołuje lokalny binarny plik `gemini`; ma własne auth i może zachowywać się inaczej (streaming/obsługa narzędzi/rozjazd wersji). ## Live: macierz modeli (co obejmujemy) Nie ma stałej „listy modeli CI” (live jest opt-in), ale to są **zalecane** modele do regularnego obejmowania na maszynie deweloperskiej z kluczami. -### Nowoczesny zestaw smoke (wywoływanie narzędzi + obraz) +### Zestaw smoke nowoczesny (wywoływanie narzędzi + obraz) -To jest przebieg „typowych modeli”, który chcemy utrzymywać w działaniu: +To jest uruchomienie „typowych modeli”, które oczekujemy utrzymywać jako działające: - OpenAI (nie-Codex): `openai/gpt-5.4` (opcjonalnie: `openai/gpt-5.4-mini`) - OpenAI Codex: `openai-codex/gpt-5.4` - Anthropic: `anthropic/claude-opus-4-6` (lub `anthropic/claude-sonnet-4-6`) -- Google (API Gemini): `google/gemini-3.1-pro-preview` i `google/gemini-3-flash-preview` (unikaj starszych modeli Gemini 2.x) +- Google (Gemini API): `google/gemini-3.1-pro-preview` i `google/gemini-3-flash-preview` (unikaj starszych modeli Gemini 2.x) - Google (Antigravity): `google-antigravity/claude-opus-4-6-thinking` i `google-antigravity/gemini-3-flash` - Z.AI (GLM): `zai/glm-4.7` - MiniMax: `minimax/MiniMax-M2.7` -Uruchom gateway smoke z narzędziami + obrazem: +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` ### Bazowa linia: wywoływanie narzędzi (Read + opcjonalny Exec) -Wybierz co najmniej jeden model dla każdej rodziny dostawców: +Wybierz co najmniej 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`) @@ -420,75 +422,75 @@ Wybierz co najmniej jeden model dla każdej rodziny dostawców: - Z.AI (GLM): `zai/glm-4.7` - MiniMax: `minimax/MiniMax-M2.7` -Opcjonalne dodatkowe pokrycie (warto mieć): +Opcjonalne dodatkowe pokrycie (mile widziane): - xAI: `xai/grok-4` (lub najnowszy dostępny) -- Mistral: `mistral/`… (wybierz jeden model z obsługą `tools`, który masz włączony) +- Mistral: `mistral/`… (wybierz jeden model z obsługą „tools”, 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) +- LM Studio: `lmstudio/`… (lokalne; wywoływanie narzędzi zależy od trybu API) ### Vision: wysyłanie obrazów (załącznik → wiadomość multimodalna) -Uwzględnij przynajmniej jeden model obsługujący obrazy w `OPENCLAW_LIVE_GATEWAY_MODELS` (Claude/Gemini/warianty OpenAI z obsługą vision itp.), aby przetestować probe obrazu. +Uwzględnij co najmniej jeden model obsługujący obrazy w `OPENCLAW_LIVE_GATEWAY_MODELS` (Claude/Gemini/warianty OpenAI z obsługą vision itd.), aby przetestować sondę obrazu. ### Agregatory / alternatywne gateway -Jeśli masz włączone klucze, wspieramy też testowanie przez: +Jeśli masz włączone klucze, obsługujemy też testowanie przez: - OpenRouter: `openrouter/...` (setki modeli; użyj `openclaw models scan`, aby znaleźć kandydatów z obsługą narzędzi+obrazów) -- OpenCode: `opencode/...` dla Zen i `opencode-go/...` dla Go (uwierzytelnianie przez `OPENCODE_API_KEY` / `OPENCODE_ZEN_API_KEY`) +- OpenCode: `opencode/...` dla Zen oraz `opencode-go/...` dla Go (auth przez `OPENCODE_API_KEY` / `OPENCODE_ZEN_API_KEY`) -Więcej dostawców, których możesz 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` (niestandardowe endpointy): `minimax` (chmura/API) oraz dowolny proxy zgodny z OpenAI/Anthropic (LM Studio, vLLM, LiteLLM itp.) +- Przez `models.providers` (niestandardowe punkty końcowe): `minimax` (cloud/API) oraz dowolny proxy zgodny z OpenAI/Anthropic (LM Studio, vLLM, LiteLLM itd.) -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. +Wskazówka: nie próbuj wpisywać na sztywno „wszystkich modeli” w dokumentacji. Autorytatywną listą jest to, co zwraca `discoverModels(...)` na twojej maszynie + jakie klucze są dostępne. ## Poświadczenia (nigdy nie commituj) -Testy live wykrywają poświadczenia tak samo jak 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 zgłasza „brak poświadczeń”, debuguj to tak samo jak `openclaw models list` / wybór modelu. +- Jeśli CLI działa, testy live powinny znaleźć te same klucze. +- Jeśli test live mówi „brak poświadczeń”, debuguj to tak samo, jak debugowałbyś `openclaw models list` / wybór modelu. -- Profile uwierzytelniania per agent: `~/.openclaw/agents//agent/auth-profiles.json` (to właśnie znaczą „profile keys” w testach live) +- Profile auth per agent: `~/.openclaw/agents//agent/auth-profiles.json` (to właśnie oznaczają „klucze profilu” w testach live) - Konfiguracja: `~/.openclaw/openclaw.json` (lub `OPENCLAW_CONFIG_PATH`) -- Starszy katalog stanu: `~/.openclaw/credentials/` (kopiowany do przygotowanego katalogu live, jeśli istnieje, ale nie jest głównym store kluczy profili) -- Lokalnie przebiegi live domyślnie kopiują aktywną konfigurację, pliki `auth-profiles.json` per agent, starszy katalog `credentials/` oraz obsługiwane katalogi uwierzytelniające zewnętrznych CLI do tymczasowego katalogu domowego testu; nadpisania ścieżek `agents.*.workspace` / `agentDir` są usuwane w tej przygotowanej konfiguracji, aby probe’y nie działały na Twoim rzeczywistym workspace hosta. +- Starszy katalog stanu: `~/.openclaw/credentials/` (kopiowany do przygotowanego katalogu domowego live, jeśli istnieje, ale nie jest głównym magazynem kluczy profilu) +- Lokalne uruchomienia live domyślnie kopiują aktywną konfigurację, pliki `auth-profiles.json` wszystkich agentów, starszy katalog `credentials/` oraz obsługiwane zewnętrzne katalogi auth CLI do tymczasowego katalogu domowego testu; przygotowane katalogi live pomijają `workspace/` i `sandboxes/`, a nadpisania ścieżek `agents.*.workspace` / `agentDir` są usuwane, aby sondy nie trafiały do twojego prawdziwego host workspace. -Jeśli chcesz polegać na kluczach env (np. eksportowanych w `~/.profile`), uruchamiaj testy lokalne po `source ~/.profile` albo użyj runnerów Docker poniżej (mogą montować `~/.profile` do kontenera). +Jeśli chcesz polegać na kluczach środowiskowych (np. wyeksportowanych w `~/.profile`), uruchamiaj lokalne testy po `source ~/.profile` albo użyj runnerów Docker poniżej (mogą montować `~/.profile` do kontenera). -## 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` +- Włączenie: `DEEPGRAM_API_KEY=... DEEPGRAM_LIVE_TEST=1 pnpm test:live src/media-understanding/providers/deepgram/audio.live.test.ts` -## Live BytePlus coding plan +## BytePlus coding plan live - 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` +- Włączenie: `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 mediów 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` +- Włączenie: `OPENCLAW_LIVE_TEST=1 COMFY_LIVE_TEST=1 pnpm test:live -- extensions/comfy/comfy.live.test.ts` - Zakres: - - Testuje dołączone ścieżki comfy image, video i `music_generate` + - Testuje dołączone ścieżki comfy dla obrazów, wideo i `music_generate` - Pomija każdą możliwość, jeśli `models.providers.comfy.` nie jest skonfigurowane - - Przydatne po zmianach w zgłaszaniu workflow comfy, polling, pobieraniu lub rejestracji wtyczki + - Przydatne po zmianie wysyłania workflow comfy, odpytywania, pobierania lub rejestracji wtyczki -## 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żdą zarejestrowaną wtyczkę dostawcy generowania obrazów - - Ładuje brakujące zmienne env dostawców z Twojej powłoki logowania (`~/.profile`) przed uruchomieniem probe’ów - - Domyślnie używa kluczy API live/env przed zapisanymi profilami uwierzytelniania, aby stare klucze testowe w `auth-profiles.json` nie maskowały rzeczywistych poświadczeń z powłoki - - Pomija dostawców bez użytecznego uwierzytelniania/profilu/modelu + - Przed sondowaniem wczytuje brakujące zmienne środowiskowe dostawcy z twojej powłoki logowania (`~/.profile`) + - Domyślnie używa kluczy API live/env przed zapisanymi profilami auth, dzięki czemu stare testowe klucze w `auth-profiles.json` nie maskują prawdziwych poświadczeń z powłoki + - Pomija dostawców bez użytecznego auth/profilu/modelu - Uruchamia standardowe warianty generowania obrazów przez współdzieloną możliwość runtime: - `google:flash-generate` - `google:pro-generate` @@ -497,200 +499,201 @@ Jeśli chcesz polegać na kluczach env (np. eksportowanych w `~/.profile`), uruc - 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 ze store profili i ignorować nadpisania tylko-env +- Opcjonalne zachowanie auth: + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, aby wymusić auth z magazynu profili i ignorować nadpisania tylko-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` +- Włączenie: `OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/music-generation-providers.live.test.ts` - Harness: `pnpm test:live:media music` - Zakres: - - Testuje współdzieloną dołączoną ś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 uruchomieniem probe’ów - - Domyślnie używa kluczy API live/env przed zapisanymi profilami uwierzytelniania, aby stare klucze testowe w `auth-profiles.json` nie maskowały rzeczywistych poświadczeń z powłoki - - Pomija dostawców bez użytecznego uwierzytelniania/profilu/modelu + - Przed sondowaniem wczytuje zmienne środowiskowe dostawców z twojej powłoki logowania (`~/.profile`) + - Domyślnie używa kluczy API live/env przed zapisanymi profilami auth, dzięki czemu stare testowe klucze w `auth-profiles.json` nie maskują prawdziwych poświadczeń z powłoki + - Pomija dostawców bez użytecznego auth/profilu/modelu - Uruchamia oba zadeklarowane tryby runtime, gdy są dostępne: - - `generate` z wejściem opartym wyłącznie na prompt + - `generate` z wejściem opartym tylko na prompt - `edit`, gdy dostawca deklaruje `capabilities.edit.enabled` - - Aktualne pokrycie współdzielonego lane: + - Aktualne pokrycie współdzielonej ścieżki: - `google`: `generate`, `edit` - `minimax`: `generate` - - `comfy`: osobny plik live Comfy, nie ten współdzielony sweep -- Opcjonalne zawężanie: + - `comfy`: osobny plik live Comfy, nie ten współdzielony 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 ze store profili i ignorować nadpisania tylko-env +- Opcjonalne zachowanie auth: + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, aby wymusić auth z magazynu profili i ignorować nadpisania tylko-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` +- Włączenie: `OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/video-generation-providers.live.test.ts` - Harness: `pnpm test:live:media video` - Zakres: - - Testuje współdzieloną dołączoną ścieżkę dostawcy generowania wideo - - Ładuje zmienne env dostawców z Twojej powłoki logowania (`~/.profile`) przed uruchomieniem probe’ów - - Domyślnie używa kluczy API live/env przed zapisanymi profilami uwierzytelniania, aby stare klucze testowe w `auth-profiles.json` nie maskowały rzeczywistych poświadczeń z powłoki - - Pomija dostawców bez użytecznego uwierzytelniania/profilu/modelu + - Testuje współdzieloną ścieżkę dołączonych dostawców generowania wideo + - Przed sondowaniem wczytuje zmienne środowiskowe dostawców z twojej powłoki logowania (`~/.profile`) + - Domyślnie używa kluczy API live/env przed zapisanymi profilami auth, dzięki czemu stare testowe klucze w `auth-profiles.json` nie maskują prawdziwych poświadczeń z powłoki + - Pomija dostawców bez użytecznego auth/profilu/modelu - Uruchamia oba zadeklarowane tryby runtime, gdy są dostępne: - - `generate` z wejściem opartym wyłącznie na prompt - - `imageToVideo`, gdy dostawca deklaruje `capabilities.imageToVideo.enabled` i wybrany dostawca/model akceptuje lokalne wejście obrazu oparte na buforze we współdzielonym sweepie - - `videoToVideo`, gdy dostawca deklaruje `capabilities.videoToVideo.enabled` i wybrany dostawca/model akceptuje lokalne wejście wideo oparte na buforze we współdzielonym sweepie - - Aktualni dostawcy `imageToVideo` zadeklarowani, ale pomijani we współdzielonym sweepie: - - `vydra`, ponieważ dołączone `veo3` jest tylko tekstowe, a dołączone `kling` wymaga zdalnego URL obrazu - - Pokrycie specyficzne dla dostawcy Vydra: + - `generate` z wejściem opartym tylko na prompt + - `imageToVideo`, gdy dostawca deklaruje `capabilities.imageToVideo.enabled` i wybrany dostawca/model akceptuje wejście lokalnego obrazu opartego na buforze we współdzielonym przeglądzie + - `videoToVideo`, gdy dostawca deklaruje `capabilities.videoToVideo.enabled` i wybrany dostawca/model akceptuje wejście lokalnego wideo opartego na buforze we współdzielonym przeglądzie + - Aktualni dostawcy `imageToVideo` zadeklarowani, ale pomijani we współdzielonym przeglądzie: + - `vydra`, ponieważ dołączony `veo3` obsługuje tylko tekst, a dołączony `kling` wymaga zdalnego URL obrazu + - Pokrycie Vydra specyficzne dla dostawcy: - `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 lane `kling`, który domyślnie używa fixtury zdalnego URL obrazu + - ten plik uruchamia `veo3` text-to-video oraz ścieżkę `kling`, która domyślnie używa fixture zdalnego URL obrazu - Aktualne pokrycie live `videoToVideo`: - tylko `runway`, gdy wybrany model to `runway/gen4_aleph` - - Aktualni dostawcy `videoToVideo` zadeklarowani, ale pomijani we współdzielonym sweepie: + - Aktualni dostawcy `videoToVideo` zadeklarowani, ale pomijani we współdzielonym przeglądzie: - `alibaba`, `qwen`, `xai`, ponieważ te ścieżki obecnie wymagają zdalnych referencyjnych URL `http(s)` / MP4 - - `google`, ponieważ bieżący współdzielony lane Gemini/Veo używa lokalnego wejścia opartego na buforze i ta ścieżka nie jest akceptowana we współdzielonym sweepie - - `openai`, ponieważ bieżący współdzielony lane nie gwarantuje dostępu specyficznego dla organizacji do video inpaint/remix -- Opcjonalne zawężanie: + - `google`, ponieważ obecna współdzielona ścieżka Gemini/Veo używa lokalnego wejścia opartego na buforze i ta ścieżka nie jest akceptowana we współdzielonym przeglądzie + - `openai`, ponieważ obecna współdzielona ścieżka nie gwarantuje dostępu do specyficznych dla organizacji funkcji video inpaint/remix +- Opcjonalne zawężenie: - `OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="google,openai,runway"` - `OPENCLAW_LIVE_VIDEO_GENERATION_MODELS="google/veo-3.1-fast-generate-preview,openai/sora-2,runway/gen4_aleph"` -- Opcjonalne zachowanie uwierzytelniania: - - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, aby wymusić uwierzytelnianie ze store profili i ignorować nadpisania tylko-env +- Opcjonalne zachowanie auth: + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, aby wymusić auth z magazynu profili i ignorować nadpisania tylko-env -## Harness mediów live +## Harness live dla mediów - Polecenie: `pnpm test:live:media` - Cel: - - Uruchamia współdzielone pakiety live dla obrazów, muzyki i wideo przez jeden natywny dla repozytorium entrypoint - - 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 wykorzystuje `scripts/test-live.mjs`, więc heartbeat i tryb quiet pozostają spójne + - Uruchamia współdzielone zestawy live dla obrazów, muzyki i wideo przez jeden natywny dla repo entrypoint + - Automatycznie wczytuje brakujące zmienne środowiskowe dostawców z `~/.profile` + - Domyślnie automatycznie zawęża każdy zestaw do dostawców, którzy aktualnie mają użyteczne auth + - Ponownie używa `scripts/test-live.mjs`, więc zachowanie heartbeatów i trybu cichego pozostaje spójne - 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` -## Runnery Docker (opcjonalne sprawdzenia „działa w Linuxie”) +## Uruchomienia w Dockerze (opcjonalne sprawdzenia typu „działa w Linuksie”) -Te runnery Docker dzielą się na dwie grupy: +Te uruchomienia Dockera dzielą się na dwa koszyki: -- Runnery live-model: `test:docker:live-models` i `test:docker:live-gateway` uruchamiają tylko odpowiadający im plik live oparty o klucze 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 workspace (oraz wykonując `source ~/.profile`, jeśli zamontowano). Odpowiadające lokalne entrypointy to `test:live:models-profiles` i `test:live:gateway-profiles`. -- Runnery Docker live domyślnie używają mniejszego limitu smoke, aby pełny sweep Docker pozostawał praktyczny: +- Uruchomienia live modeli: `test:docker:live-models` i `test:docker:live-gateway` uruchamiają tylko odpowiadający im plik live z kluczami profilu wewnątrz obrazu Docker repozytorium (`src/agents/models.profiles.live.test.ts` i `src/gateway/gateway-models.profiles.live.test.ts`), montując lokalny katalog config i workspace (oraz wczytując `~/.profile`, jeśli został zamontowany). Odpowiadające lokalne entrypointy to `test:live:models-profiles` i `test:live:gateway-profiles`. +- Uruchomienia Docker live domyślnie mają mniejszy limit smoke, aby pełny przegląd Dockera pozostawał praktyczny: `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 - świadomie chcesz większy, wyczerpujący skan. -- `test:docker:all` buduje obraz live Docker raz przez `test:docker:live-build`, a potem używa go ponownie dla dwóch lane’ów live Docker. -- Runnery smoke kontenerów: `test:docker:openwebui`, `test:docker:onboard`, `test:docker:gateway-network`, `test:docker:mcp-channels` i `test:docker:plugins` uruchamiają jeden lub więcej rzeczywistych kontenerów i weryfikują ścieżki integracyjne wyższego poziomu. + `OPENCLAW_LIVE_GATEWAY_MODEL_TIMEOUT_MS=90000`. Nadpisz te zmienne środowiskowe, gdy + świadomie chcesz większego, wyczerpującego skanu. +- `test:docker:all` buduje obraz Docker live tylko raz przez `test:docker:live-build`, a następnie ponownie używa go dla dwóch ścieżek live Docker. +- Runnery smoke kontenerów: `test:docker:openwebui`, `test:docker:onboard`, `test:docker:gateway-network`, `test:docker:mcp-channels` oraz `test:docker:plugins` uruchamiają jeden lub więcej prawdziwych kontenerów i weryfikują ścieżki integracji wyższego poziomu. -Runnery Docker dla live-model dodatkowo bind-montują tylko potrzebne katalogi uwierzytelniające CLI (lub wszystkie obsługiwane, gdy przebieg nie jest zawężony), a następnie kopiują je do katalogu domowego kontenera przed uruchomieniem, aby OAuth zewnętrznych CLI mógł odświeżać tokeny bez modyfikowania store uwierzytelniania hosta: +Runnery Docker live modeli także montują tylko potrzebne katalogi auth CLI (lub wszystkie obsługiwane, gdy uruchomienie nie jest zawężone), a następnie kopiują je do katalogu domowego kontenera przed startem, tak aby OAuth zewnętrznego CLI mógł odświeżać tokeny bez modyfikowania hostowego magazynu auth: - Modele bezpośrednie: `pnpm test:docker:live-models` (skrypt: `scripts/test-live-models-docker.sh`) -- Smoke ACP bind: `pnpm test:docker:live-acp-bind` (skrypt: `scripts/test-live-acp-bind-docker.sh`) +- Smoke 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`) -- Gateway + agent dev: `pnpm test:docker:live-gateway` (skrypt: `scripts/test-live-gateway-models-docker.sh`) +- Gateway + dev agent: `pnpm test:docker:live-gateway` (skrypt: `scripts/test-live-gateway-models-docker.sh`) - Live smoke Open WebUI: `pnpm test:docker:openwebui` (skrypt: `scripts/e2e/openwebui-docker.sh`) - Kreator onboardingu (TTY, pełne scaffoldowanie): `pnpm test:docker:onboard` (skrypt: `scripts/e2e/onboard-docker.sh`) -- Sieć gateway (dwa kontenery, WS auth + health): `pnpm test:docker:gateway-network` (skrypt: `scripts/e2e/gateway-network-docker.sh`) -- Most kanału MCP (zasiany Gateway + most stdio + surowy smoke ramki powiadomień Claude): `pnpm test:docker:mcp-channels` (skrypt: `scripts/e2e/mcp-channels-docker.sh`) +- Sieć gateway (dwa kontenery, auth WS + health): `pnpm test:docker:gateway-network` (skrypt: `scripts/e2e/gateway-network-docker.sh`) +- Most kanałów MCP (zainicjalizowany Gateway + most stdio + smoke surowej ramki powiadomień Claude): `pnpm test:docker:mcp-channels` (skrypt: `scripts/e2e/mcp-channels-docker.sh`) - Wtyczki (smoke instalacji + alias `/plugin` + semantyka restartu pakietu Claude): `pnpm test:docker:plugins` (skrypt: `scripts/e2e/plugins-docker.sh`) -Runnery Docker dla live-model bind-montują także bieżący checkout tylko do odczytu i +Runnery Docker live modeli także montują bieżący checkout tylko do odczytu i przygotowują go w tymczasowym katalogu roboczym wewnątrz kontenera. Dzięki temu obraz runtime -pozostaje mały, a jednocześnie Vitest działa dokładnie na Twoim lokalnym źródle/konfiguracji. -Krok przygotowania pomija duże lokalne cache’e i wyniki buildów aplikacji, takie jak -`.pnpm-store`, `.worktrees`, `__openclaw_vitest__` oraz lokalne dla aplikacji katalogi `.build` lub wyjścia Gradle, aby przebiegi live Docker nie spędzały minut na kopiowaniu +pozostaje mały, a mimo to Vitest działa na twoich dokładnych lokalnych źródłach/configu. +Krok przygotowania pomija duże lokalne cache i wyniki buildów aplikacji, takie jak +`.pnpm-store`, `.worktrees`, `__openclaw_vitest__` oraz lokalne dla aplikacji katalogi `.build` lub +wyniki Gradle, dzięki czemu uruchomienia Docker live nie tracą minut na kopiowanie artefaktów specyficznych dla maszyny. -Ustawiają one także `OPENCLAW_SKIP_CHANNELS=1`, aby probe’y gateway live nie uruchamiały -rzeczywistych workerów kanałów Telegram/Discord/itp. wewnątrz kontenera. +Ustawiają też `OPENCLAW_SKIP_CHANNELS=1`, aby sondy gateway live nie uruchamiały +prawdziwych workerów kanałów Telegram/Discord/itd. wewnątrz kontenera. `test:docker:live-models` nadal uruchamia `pnpm test:live`, więc przekazuj także `OPENCLAW_LIVE_GATEWAY_*`, gdy chcesz zawęzić lub wykluczyć pokrycie gateway -live z tego lane Docker. -`test:docker:openwebui` to smoke zgodności wyższego poziomu: uruchamia kontener -gateway OpenClaw z włączonymi endpointami HTTP zgodnymi z OpenAI, -uruchamia przypięty kontener Open WebUI względem tego gateway, loguje się przez -Open WebUI, sprawdza, że `/api/models` udostępnia `openclaw/default`, a następnie wysyła -rzeczywiste żądanie czatu przez proxy `/api/chat/completions` Open WebUI. +live z tej ścieżki Docker. +`test:docker:openwebui` to smoke kompatybilności wyższego poziomu: uruchamia +kontener gateway OpenClaw z włączonymi punktami końcowymi HTTP zgodnymi z OpenAI, +uruchamia przypięty kontener Open WebUI przeciwko temu gateway, loguje się przez +Open WebUI, weryfikuje, że `/api/models` udostępnia `openclaw/default`, a następnie wysyła +prawdziwe żądanie czatu przez proxy `/api/chat/completions` Open WebUI. Pierwsze uruchomienie może być zauważalnie wolniejsze, ponieważ Docker może potrzebować pobrać -obraz Open WebUI, a samo Open WebUI może potrzebować zakończyć własny cold start. -Ten lane oczekuje użytecznego klucza modelu live, a `OPENCLAW_PROFILE_FILE` -(domyślnie `~/.profile`) jest podstawowym sposobem dostarczenia go w przebiegach dockerowych. -Udane przebiegi wypisują mały ładunek JSON, taki jak `{ "ok": true, "model": +obraz Open WebUI, a Open WebUI może potrzebować dokończyć własną konfigurację cold-start. +Ta ścieżka oczekuje działającego klucza live modelu, a `OPENCLAW_PROFILE_FILE` +(`~/.profile` domyślnie) jest podstawowym sposobem dostarczenia go w uruchomieniach z Dockerem. +Udane uruchomienia wypisują mały ładunek JSON, taki jak `{ "ok": true, "model": "openclaw/default", ... }`. `test:docker:mcp-channels` jest celowo deterministyczny i nie wymaga -rzeczywistego konta Telegram, Discord ani iMessage. Uruchamia zasiany kontener -Gateway, startuje drugi kontener uruchamiający `openclaw mcp serve`, a następnie -weryfikuje routowane wykrywanie konwersacji, odczyty transkryptów, metadane załączników, -zachowanie kolejki zdarzeń live, routing wysyłek wychodzących oraz powiadomienia kanałowe + -uprawnień w stylu Claude przez rzeczywisty most stdio MCP. Sprawdzenie powiadomień -inspektuje bezpośrednio surowe ramki stdio MCP, więc smoke waliduje to, co most -rzeczywiście emituje, a nie tylko to, co akurat ujawnia konkretne SDK klienta. +prawdziwego konta Telegram, Discord ani iMessage. Uruchamia zainicjalizowany kontener +Gateway, uruchamia drugi kontener, który startuje `openclaw mcp serve`, a następnie +weryfikuje wykrywanie routowanych rozmów, odczyty transkryptów, metadane załączników, +zachowanie kolejki zdarzeń live, routing wysyłek wychodzących oraz powiadomienia w stylu Claude o kanałach + +uprawnieniach przez prawdziwy most stdio MCP. Kontrola powiadomień +bada bezpośrednio surowe ramki stdio MCP, więc smoke weryfikuje to, co most +faktycznie emituje, a nie tylko to, co akurat udostępnia konkretny SDK klienta. -Ręczny smoke ACP plain-language thread (nie CI): +Ręczny smoke zwykłego wątku ACP w naturalnym języku (nie CI): - `bun scripts/dev/discord-acp-plain-language-smoke.ts --channel ...` -- Zachowaj ten skrypt do przepływów regresji/debugowania. Może być potrzebny ponownie 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: +Przydatne zmienne środowiskowe: - `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 wykonywane przez `source` 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 uwierzytelniające CLI pod `$HOME` są montowane tylko do odczytu pod `/host-auth...`, a następnie kopiowane do `/home/node/...` przed startem testów +- `OPENCLAW_PROFILE_FILE=...` (domyślnie: `~/.profile`) montowane do `/home/node/.profile` i wczytywane przed uruchomieniem testów +- `OPENCLAW_DOCKER_CLI_TOOLS_DIR=...` (domyślnie: `~/.cache/openclaw/docker-cli-tools`) montowane do `/home/node/.npm-global` dla buforowanych instalacji CLI wewnątrz Dockera +- Zewnętrzne katalogi/pliki auth CLI w `$HOME` są montowane tylko do odczytu pod `/host-auth...`, a następnie kopiowane do `/home/node/...` przed startem testów - 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 przebiegi dostawców montują tylko potrzebne katalogi/pliki wywnioskowane z `OPENCLAW_LIVE_PROVIDERS` / `OPENCLAW_LIVE_GATEWAY_PROVIDERS` - - Nadpisz ręcznie przez `OPENCLAW_DOCKER_AUTH_DIRS=all`, `OPENCLAW_DOCKER_AUTH_DIRS=none` lub listę rozdzielaną przecinkami, np. `OPENCLAW_DOCKER_AUTH_DIRS=.claude,.codex` -- `OPENCLAW_LIVE_GATEWAY_MODELS=...` / `OPENCLAW_LIVE_MODELS=...` aby zawęzić przebieg -- `OPENCLAW_LIVE_GATEWAY_PROVIDERS=...` / `OPENCLAW_LIVE_PROVIDERS=...` aby filtrować dostawców w kontenerze -- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, aby upewnić się, że poświadczenia pochodzą ze store profili (a nie z env) -- `OPENCLAW_OPENWEBUI_MODEL=...` aby wybrać model udostępniany przez gateway dla smoke Open WebUI -- `OPENCLAW_OPENWEBUI_PROMPT=...` aby nadpisać prompt sprawdzania nonce używany przez smoke Open WebUI -- `OPENWEBUI_IMAGE=...` aby nadpisać przypięty tag obrazu Open WebUI + - Zawężone uruchomienia dostawców montują tylko potrzebne katalogi/pliki wywnioskowane z `OPENCLAW_LIVE_PROVIDERS` / `OPENCLAW_LIVE_GATEWAY_PROVIDERS` + - Ręczne nadpisanie: `OPENCLAW_DOCKER_AUTH_DIRS=all`, `OPENCLAW_DOCKER_AUTH_DIRS=none` lub lista rozdzielana przecinkami, np. `OPENCLAW_DOCKER_AUTH_DIRS=.claude,.codex` +- `OPENCLAW_LIVE_GATEWAY_MODELS=...` / `OPENCLAW_LIVE_MODELS=...`, aby zawęzić uruchomienie +- `OPENCLAW_LIVE_GATEWAY_PROVIDERS=...` / `OPENCLAW_LIVE_PROVIDERS=...`, aby filtrować dostawców wewnątrz kontenera +- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, aby upewnić się, że poświadczenia pochodzą z magazynu profili (a nie ze środowiska) +- `OPENCLAW_OPENWEBUI_MODEL=...`, aby wybrać model udostępniany przez gateway dla smoke Open WebUI +- `OPENCLAW_OPENWEBUI_PROMPT=...`, aby nadpisać prompt kontroli nonce używany przez smoke Open WebUI +- `OPENWEBUI_IMAGE=...`, aby nadpisać przypięty tag obrazu Open WebUI ## Kontrola dokumentacji -Uruchamiaj kontrole dokumentacji po zmianach w dokumentach: `pnpm check:docs`. -Uruchamiaj 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 dokumentów: `pnpm check:docs`. +Uruchom pełną walidację anchorów Mintlify, gdy potrzebujesz też kontroli nagłówków w obrębie strony: `pnpm docs:check-links:anchors`. ## Regresja offline (bezpieczna dla CI) -To regresje „rzeczywistego pipeline” bez prawdziwych dostawców: +To są regresje „rzeczywistego pipeline” bez prawdziwych dostawców: -- Wywoływanie narzędzi gateway (mock OpenAI, rzeczywista pętla gateway + agent): `src/gateway/gateway.test.ts` (przypadek: "runs a mock OpenAI tool call end-to-end via gateway agent loop") -- Kreator gateway (WS `wizard.start`/`wizard.next`, zapis konfiguracji + wymuszone uwierzytelnianie): `src/gateway/gateway.test.ts` (przypadek: "runs wizard over ws and writes auth token config") +- Wywoływanie narzędzi gateway (mock OpenAI, prawdziwa pętla gateway + agent): `src/gateway/gateway.test.ts` (przypadek: "runs a mock OpenAI tool call end-to-end via gateway agent loop") +- Kreator gateway (WS `wizard.start`/`wizard.next`, zapis config + wymuszone auth): `src/gateway/gateway.test.ts` (przypadek: "runs wizard over ws and writes auth token config") -## Ewalucje niezawodności agentów (Skills) +## Ewalucje niezawodności agenta (Skills) -Mamy już kilka bezpiecznych dla CI testów, które zachowują się jak „ewaluacje niezawodności agentów”: +Mamy już kilka bezpiecznych dla CI testów, które działają jak „ewaluacje niezawodności agenta”: -- Mock wywoływania narzędzi przez rzeczywistą pętlę gateway + agent (`src/gateway/gateway.test.ts`). -- Przepływy kreatora end-to-end, które walidują okablowanie sesji i skutki konfiguracji (`src/gateway/gateway.test.ts`). +- Mock wywoływania narzędzi przez prawdziwą pętlę gateway + agent (`src/gateway/gateway.test.ts`). +- Pełne przepływy kreatora, które walidują okablowanie sesji i efekty konfiguracji (`src/gateway/gateway.test.ts`). Czego nadal brakuje dla Skills (zobacz [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 potwierdzające kolejność narzędzi, przenoszenie historii sesji i granice sandbox. +- **Podejmowanie decyzji:** gdy skille są wymienione w promptcie, czy agent wybiera właściwy skill (albo unika nieistotnych)? +- **Zgodność:** czy agent odczytuje `SKILL.md` przed użyciem i wykonuje wymagane kroki/argumenty? +- **Kontrakty workflow:** scenariusze wieloturowe potwierdzające kolejność narzędzi, przenoszenie historii sesji i granice sandboxa. Przyszłe ewaluacje powinny najpierw pozostać deterministyczne: -- Runner scenariuszy używający mock dostawców do potwierdzania wywołań narzędzi + ich kolejności, odczytów plików skill i okablowania sesji. -- Mały pakiet scenariuszy skupionych na skillach (użyj vs unikaj, gating, prompt injection). -- Opcjonalne ewaluacje live (opt-in, bramkowane env) dopiero po wdrożeniu pakietu bezpiecznego dla CI. +- Runner scenariuszy używający mockowanych dostawców do potwierdzania wywołań narzędzi + kolejności, odczytów plików skillów i okablowania sesji. +- Mały zestaw scenariuszy skupionych na skillach (użyć vs unikać, bramkowanie, wstrzykiwanie promptu). +- Opcjonalne ewaluacje live (opt-in, bramkowane env) dopiero po wdrożeniu zestawu bezpiecznego dla CI. -## Testy kontraktowe (kształt wtyczek i kanałów) +## Testy kontraktów (kształt wtyczek i kanałów) -Testy kontraktowe weryfikują, że każda zarejestrowana wtyczka i każdy kanał są zgodne ze swoim -kontraktem interfejsu. Iterują po wszystkich wykrytych wtyczkach i uruchamiają pakiet -asercji kształtu i zachowania. Domyślny lane unit `pnpm test` celowo -pomija te współdzielone pliki seam i smoke; uruchamiaj polecenia kontraktowe jawnie, +Testy kontraktów weryfikują, że każda zarejestrowana wtyczka i każdy kanał są zgodne ze swoim +kontraktem interfejsu. Iterują po wszystkich wykrytych wtyczkach i uruchamiają zestaw +asercji kształtu i zachowania. Domyślna ścieżka unit `pnpm test` celowo +pomija te współdzielone pliki seam i smoke; uruchamiaj polecenia kontraktów jawnie, gdy dotykasz współdzielonych powierzchni kanałów lub dostawców. ### Polecenia @@ -709,23 +712,23 @@ Znajdują się w `src/channels/plugins/contracts/*.contract.test.ts`: - **outbound-payload** - Struktura ładunku wiadomości - **inbound** - Obsługa wiadomości przychodzących - **actions** - Handlery akcji kanału -- **threading** - Obsługa ID wątków -- **directory** - API katalogu/listy użytkowników -- **group-policy** - Egzekwowanie zasady grup +- **threading** - Obsługa identyfikatorów wątków +- **directory** - API katalogu/listy +- **group-policy** - Egzekwowanie polityki grup ### Kontrakty statusu dostawców Znajdują się w `src/plugins/contracts/*.contract.test.ts`. -- **status** - Testy status probe kanałów +- **status** - Sondy statusu kanału - **registry** - Kształt rejestru wtyczek ### Kontrakty dostawców Znajdują się w `src/plugins/contracts/*.contract.test.ts`: -- **auth** - Kontrakt przepływu uwierzytelniania -- **auth-choice** - Wybór/selekcja uwierzytelniania +- **auth** - Kontrakt przepływu auth +- **auth-choice** - Wybór/selekcja auth - **catalog** - API katalogu modeli - **discovery** - Wykrywanie wtyczek - **loader** - Ładowanie wtyczek @@ -735,21 +738,21 @@ Znajdują się w `src/plugins/contracts/*.contract.test.ts`: ### Kiedy uruchamiać -- Po zmianie eksportów lub subpathów plugin-sdk -- Po dodaniu lub modyfikacji wtyczki kanału albo dostawcy +- Po zmianie eksportów lub subpathów `plugin-sdk` +- Po dodaniu lub modyfikacji kanału albo wtyczki dostawcy - Po refaktoryzacji rejestracji lub wykrywania wtyczek -Testy kontraktowe działają w CI i nie wymagają prawdziwych kluczy API. +Testy kontraktów uruchamiają się w CI i nie wymagają prawdziwych kluczy API. ## Dodawanie regresji (wskazówki) Gdy naprawiasz problem dostawcy/modelu wykryty w live: -- Jeśli to możliwe, dodaj regresję bezpieczną dla CI (mock/stub dostawcy albo przechwyć dokładną transformację kształtu żądania) -- Jeśli problem z natury występuje tylko w live (limity, polityki uwierzytelniania), utrzymuj test live wąski i opt-in przez zmienne env -- Preferuj celowanie w najmniejszą warstwę, która wychwytuje błąd: - - błąd konwersji/replay żądania dostawcy → test modeli bezpośrednich - - błąd pipeline sesji/historii/narzędzi gateway → gateway live smoke albo bezpieczny dla CI test mock gateway -- Guardrail przechodzenia SecretRef: - - `src/secrets/exec-secret-ref-id-parity.test.ts` wyprowadza jeden próbkowany cel na klasę SecretRef z metadanych rejestru (`listSecretTargetRegistryEntries()`), a następnie potwierdza, że id exec segmentu przechodzenia są odrzucane. - - Jeśli dodasz nową rodzinę celów SecretRef `includeInPlan` w `src/secrets/target-registry-data.ts`, zaktualizuj `classifyTargetClass` w tym teście. Test celowo kończy się niepowodzeniem dla niesklasyfikowanych id celów, aby nowe klasy nie mogły zostać pominięte po cichu. +- Jeśli to możliwe, dodaj regresję bezpieczną dla CI (mock/stub dostawcy albo uchwycenie dokładnej transformacji kształtu żądania) +- Jeśli z natury jest to tylko live (limity szybkości, polityki auth), utrzymaj test live wąski i opt-in przez zmienne środowiskowe +- Preferuj celowanie w najmniejszą warstwę, która wykryje błąd: + - błąd konwersji/odtwarzania żądania dostawcy → test modeli bezpośrednich + - błąd pipeline sesji/historii/narzędzi gateway → live smoke gateway albo bezpieczny dla CI test mock gateway +- Zabezpieczenie przechodzenia SecretRef: + - `src/secrets/exec-secret-ref-id-parity.test.ts` wyprowadza jeden przykładowy cel na klasę SecretRef z metadanych rejestru (`listSecretTargetRegistryEntries()`), a następnie potwierdza, że identyfikatory exec z segmentami przejścia są odrzucane. + - Jeśli dodasz nową rodzinę celów SecretRef `includeInPlan` w `src/secrets/target-registry-data.ts`, zaktualizuj `classifyTargetClass` w tym teście. Test celowo kończy się niepowodzeniem dla niesklasyfikowanych identyfikatorów celów, aby nie dało się po cichu pominąć nowych klas. diff --git a/docs/pl/help/troubleshooting.md b/docs/pl/help/troubleshooting.md index 54348dfe5..58e59a9ec 100644 --- a/docs/pl/help/troubleshooting.md +++ b/docs/pl/help/troubleshooting.md @@ -1,25 +1,25 @@ --- read_when: - - OpenClaw nie działa i potrzebujesz najszybszej drogi do naprawy - - Chcesz przejść przez proces triage, zanim zagłębisz się w szczegółowe runbooki -summary: Hub rozwiązywania problemów OpenClaw z podejściem opartym najpierw na objawach + - OpenClaw nie działa i potrzebujesz najszybszej drogi do rozwiązania + - Chcesz przejść przez proces triage, zanim zagłębisz się w szczegółowe instrukcje +summary: Centrum rozwiązywania problemów OpenClaw zorientowane na objawy title: Ogólne rozwiązywanie problemów x-i18n: - generated_at: "2026-04-05T13:56:11Z" + generated_at: "2026-04-08T02:16:21Z" model: gpt-5.4 provider: openai - source_hash: 23ae9638af5edf5a5e0584ccb15ba404223ac3b16c2d62eb93b2c9dac171c252 + source_hash: 8abda90ef80234c2f91a51c5e1f2c004d4a4da12a5d5631b5927762550c6d5e3 source_path: help/troubleshooting.md workflow: 15 --- # Rozwiązywanie problemów -Jeśli masz tylko 2 minuty, użyj tej strony jako punktu wejścia do triage. +Jeśli masz tylko 2 minuty, potraktuj tę stronę jako punkt wejścia do triage. ## Pierwsze 60 sekund -Uruchom dokładnie tę sekwencję po kolei: +Uruchom dokładnie tę sekwencję, po kolei: ```bash openclaw status @@ -31,32 +31,47 @@ openclaw channels status --probe openclaw logs --follow ``` -Prawidłowy wynik w jednym wierszu: +Prawidłowe dane wyjściowe w jednym wierszu: -- `openclaw status` → pokazuje skonfigurowane kanały i brak oczywistych błędów auth. +- `openclaw status` → pokazuje skonfigurowane kanały i brak oczywistych błędów uwierzytelniania. - `openclaw status --all` → pełny raport jest dostępny i można go udostępnić. -- `openclaw gateway probe` → oczekiwany cel gateway jest osiągalny (`Reachable: yes`). `RPC: limited - missing scope: operator.read` oznacza zdegradowaną diagnostykę, a nie błąd połączenia. -- `openclaw gateway status` → `Runtime: running` oraz `RPC probe: ok`. -- `openclaw doctor` → brak blokujących błędów config/usługi. -- `openclaw channels status --probe` → osiągalna gateway zwraca aktywny stan transportu dla każdego konta oraz wyniki probe/audytu, takie jak `works` lub `audit ok`; jeśli gateway jest nieosiągalna, polecenie wraca do podsumowań opartych tylko na config. -- `openclaw logs --follow` → stabilna aktywność, brak powtarzających się błędów krytycznych. +- `openclaw gateway probe` → oczekiwany cel gateway jest osiągalny (`Reachable: yes`). `RPC: limited - missing scope: operator.read` oznacza pogorszoną diagnostykę, a nie błąd połączenia. +- `openclaw gateway status` → `Runtime: running` i `RPC probe: ok`. +- `openclaw doctor` → brak blokujących błędów konfiguracji/usługi. +- `openclaw channels status --probe` → osiągalny gateway zwraca stan transportu na żywo dla każdego konta oraz wyniki probe/audytu, takie jak `works` lub `audit ok`; jeśli gateway jest nieosiągalny, polecenie wraca do podsumowań opartych wyłącznie na konfiguracji. +- `openclaw logs --follow` → stabilna aktywność, bez powtarzających się błędów krytycznych. ## Anthropic long context 429 Jeśli widzisz: `HTTP 429: rate_limit_error: Extra usage is required for long context requests`, -przejdź do [/gateway/troubleshooting#anthropic-429-extra-usage-required-for-long-context](/gateway/troubleshooting#anthropic-429-extra-usage-required-for-long-context). +przejdź do [/gateway/troubleshooting#anthropic-429-extra-usage-required-for-long-context](/pl/gateway/troubleshooting#anthropic-429-extra-usage-required-for-long-context). -## Instalacja pluginu kończy się błędem z brakującymi rozszerzeniami openclaw +## Lokalny backend zgodny z OpenAI działa bezpośrednio, ale nie działa w OpenClaw + +Jeśli lokalny lub samodzielnie hostowany backend `/v1` odpowiada na małe bezpośrednie +zapytania testowe `/v1/chat/completions`, ale nie działa z `openclaw infer model run` ani podczas zwykłych +tur agenta: + +1. Jeśli błąd wspomina o `messages[].content` oczekującym ciągu znaków, ustaw + `models.providers..models[].compat.requiresStringContent: true`. +2. Jeśli backend nadal zawodzi tylko podczas tur agenta OpenClaw, ustaw + `models.providers..models[].compat.supportsTools: false` i spróbuj ponownie. +3. Jeśli małe bezpośrednie wywołania nadal działają, ale większe prompty OpenClaw powodują awarię + backendu, potraktuj pozostały problem jako ograniczenie modelu/serwera po stronie upstream i + przejdź do szczegółowej instrukcji: + [/gateway/troubleshooting#local-openai-compatible-backend-passes-direct-probes-but-agent-runs-fail](/pl/gateway/troubleshooting#local-openai-compatible-backend-passes-direct-probes-but-agent-runs-fail) + +## Instalacja pluginu kończy się błędem z powodu brakujących rozszerzeń openclaw Jeśli instalacja kończy się błędem `package.json missing openclaw.extensions`, pakiet pluginu -używa starego formatu, którego OpenClaw już nie akceptuje. +używa starej struktury, której OpenClaw już nie akceptuje. -Napraw w pakiecie pluginu: +Naprawa w pakiecie pluginu: 1. Dodaj `openclaw.extensions` do `package.json`. 2. Skieruj wpisy do zbudowanych plików runtime (zwykle `./dist/index.js`). -3. Opublikuj plugin ponownie i jeszcze raz uruchom `openclaw plugins install `. +3. Opublikuj plugin ponownie i uruchom `openclaw plugins install ` jeszcze raz. Przykład: @@ -70,28 +85,28 @@ Przykład: } ``` -Informacje referencyjne: [Plugin architecture](/plugins/architecture) +Odwołanie: [Architektura pluginów](/pl/plugins/architecture) -## Drzewo decyzji +## Drzewo decyzyjne ```mermaid flowchart TD A[OpenClaw nie działa] --> B{Co psuje się jako pierwsze} B --> C[Brak odpowiedzi] - B --> D[Dashboard lub Control UI nie może się połączyć] + B --> D[Dashboard lub Control UI nie łączy się] B --> E[Gateway nie uruchamia się lub usługa nie działa] B --> F[Kanał łączy się, ale wiadomości nie przepływają] B --> G[Cron lub heartbeat nie uruchomił się albo nie dostarczył] - B --> H[Node jest sparowany, ale camera canvas screen exec kończy się błędem] - B --> I[Narzędzie browser nie działa] + B --> H[Node jest sparowany, ale camera canvas screen exec nie działa] + B --> I[Narzędzie przeglądarki nie działa] C --> C1[/Sekcja Brak odpowiedzi/] D --> D1[/Sekcja Control UI/] E --> E1[/Sekcja Gateway/] - F --> F1[/Sekcja przepływu kanału/] - G --> G1[/Sekcja automatyzacji/] - H --> H1[/Sekcja narzędzi node/] - I --> I1[/Sekcja Browser/] + F --> F1[/Sekcja Przepływ kanału/] + G --> G1[/Sekcja Automatyzacja/] + H --> H1[/Sekcja Narzędzia node/] + I --> I1[/Sekcja Przeglądarka/] ``` @@ -104,28 +119,28 @@ flowchart TD openclaw logs --follow ``` - Prawidłowy wynik wygląda tak: + Prawidłowe dane wyjściowe wyglądają tak: - `Runtime: running` - `RPC probe: ok` - - Twój kanał pokazuje połączony transport i, tam gdzie jest to obsługiwane, `works` lub `audit ok` w `channels status --probe` - - Nadawca widnieje jako zatwierdzony (lub polityka DM jest otwarta/allowlist) + - Twój kanał pokazuje podłączony transport oraz, jeśli jest obsługiwane, `works` lub `audit ok` w `channels status --probe` + - Nadawca jest zatwierdzony (lub polityka DM jest otwarta/lista dozwolonych) - Typowe sygnatury w logach: + Typowe sygnatury logów: - - `drop guild message (mention required` → bramka mention zablokowała wiadomość w Discord. - - `pairing request` → nadawca nie jest zatwierdzony i czeka na zatwierdzenie parowania DM. + - `drop guild message (mention required` → bramka wzmianek zablokowała wiadomość w Discord. + - `pairing request` → nadawca jest niezatwierdzony i czeka na zgodę sparowania DM. - `blocked` / `allowlist` w logach kanału → nadawca, pokój lub grupa są filtrowane. Szczegółowe strony: - - [/gateway/troubleshooting#no-replies](/gateway/troubleshooting#no-replies) + - [/gateway/troubleshooting#no-replies](/pl/gateway/troubleshooting#no-replies) - [/channels/troubleshooting](/pl/channels/troubleshooting) - [/channels/pairing](/pl/channels/pairing) - + ```bash openclaw status openclaw gateway status @@ -134,30 +149,28 @@ flowchart TD openclaw channels status --probe ``` - Prawidłowy wynik wygląda tak: + Prawidłowe dane wyjściowe wyglądają tak: - - `Dashboard: http://...` jest pokazywane w `openclaw gateway status` + - `Dashboard: http://...` jest pokazane w `openclaw gateway status` - `RPC probe: ok` - - Brak pętli auth w logach + - Brak pętli uwierzytelniania w logach - Typowe sygnatury w logach: + Typowe sygnatury logów: - - `device identity required` → kontekst HTTP/niebezpieczny nie może zakończyć auth urządzenia. - - `origin not allowed` → `Origin` przeglądarki nie jest dozwolony dla celu gateway w Control UI. - - `AUTH_TOKEN_MISMATCH` ze wskazówkami ponowienia (`canRetryWithDeviceToken=true`) → może automatycznie wystąpić jedna zaufana próba ponowienia z tokenem urządzenia. - - To ponowienie z tokenem z cache używa ponownie zestawu zakresów z cache zapisanego wraz z tokenem sparowanego urządzenia. Wywołujący z jawnym `deviceToken` / jawnymi `scopes` zachowują zamiast tego żądany zestaw zakresów. - - W asynchronicznej ścieżce Tailscale Serve Control UI nieudane próby dla tego samego - `{scope, ip}` są serializowane, zanim limiter zapisze porażkę, więc - druga równoległa zła próba może już pokazać `retry later`. - - `too many failed authentication attempts (retry later)` z originu przeglądarki localhost → powtarzane błędy z tego samego `Origin` są tymczasowo blokowane; inny origin localhost używa osobnego bucketu. - - powtarzające się `unauthorized` po tym ponowieniu → zły token/hasło, niedopasowanie trybu auth albo nieaktualny token sparowanego urządzenia. - - `gateway connect failed:` → UI celuje w zły URL/port albo nieosiągalną gateway. + - `device identity required` → kontekst HTTP/niezabezpieczony nie może ukończyć uwierzytelniania urządzenia. + - `origin not allowed` → przeglądarkowy `Origin` nie jest dozwolony dla celu gateway Control UI. + - `AUTH_TOKEN_MISMATCH` z podpowiedziami ponownej próby (`canRetryWithDeviceToken=true`) → może automatycznie wystąpić jedna ponowna próba z zaufanym tokenem urządzenia. + - Ta ponowna próba z pamięci podręcznej ponownie używa zestawu scope z pamięci podręcznej zapisanego razem ze sparowanym tokenem urządzenia. Wywołania z jawnym `deviceToken` / jawnymi `scopes` zachowują zamiast tego żądany zestaw scope. + - W asynchronicznej ścieżce Tailscale Serve dla Control UI nieudane próby dla tego samego `{scope, ip}` są serializowane, zanim ogranicznik zarejestruje niepowodzenie, więc druga równoległa błędna ponowna próba może już zwrócić `retry later`. + - `too many failed authentication attempts (retry later)` z pochodzenia przeglądarki localhost → powtarzające się niepowodzenia z tego samego `Origin` są tymczasowo blokowane; inne pochodzenie localhost używa osobnego bucketu. + - powtarzające się `unauthorized` po tej ponownej próbie → błędny token/hasło, niedopasowanie trybu uwierzytelniania lub nieaktualny sparowany token urządzenia. + - `gateway connect failed:` → UI kieruje do błędnego URL/portu lub do nieosiągalnego gateway. Szczegółowe strony: - - [/gateway/troubleshooting#dashboard-control-ui-connectivity](/gateway/troubleshooting#dashboard-control-ui-connectivity) + - [/gateway/troubleshooting#dashboard-control-ui-connectivity](/pl/gateway/troubleshooting#dashboard-control-ui-connectivity) - [/web/control-ui](/web/control-ui) - - [/gateway/authentication](/gateway/authentication) + - [/gateway/authentication](/pl/gateway/authentication) @@ -170,23 +183,23 @@ flowchart TD openclaw channels status --probe ``` - Prawidłowy wynik wygląda tak: + Prawidłowe dane wyjściowe wyglądają tak: - `Service: ... (loaded)` - `Runtime: running` - `RPC probe: ok` - Typowe sygnatury w logach: + Typowe sygnatury logów: - - `Gateway start blocked: set gateway.mode=local` lub `existing config is missing gateway.mode` → tryb gateway to remote albo w pliku config brakuje stempla trybu lokalnego i należy go naprawić. - - `refusing to bind gateway ... without auth` → powiązanie inne niż loopback bez prawidłowej ścieżki auth gateway (token/hasło lub trusted-proxy, jeśli skonfigurowano). + - `Gateway start blocked: set gateway.mode=local` lub `existing config is missing gateway.mode` → tryb gateway jest zdalny albo w pliku konfiguracji brakuje oznaczenia trybu lokalnego i należy go naprawić. + - `refusing to bind gateway ... without auth` → powiązanie spoza loopback bez prawidłowej ścieżki uwierzytelniania gateway (token/hasło lub trusted-proxy, jeśli skonfigurowano). - `another gateway instance is already listening` lub `EADDRINUSE` → port jest już zajęty. Szczegółowe strony: - - [/gateway/troubleshooting#gateway-service-not-running](/gateway/troubleshooting#gateway-service-not-running) - - [/gateway/background-process](/gateway/background-process) - - [/gateway/configuration](/gateway/configuration) + - [/gateway/troubleshooting#gateway-service-not-running](/pl/gateway/troubleshooting#gateway-service-not-running) + - [/gateway/background-process](/pl/gateway/background-process) + - [/gateway/configuration](/pl/gateway/configuration) @@ -199,21 +212,21 @@ flowchart TD openclaw channels status --probe ``` - Prawidłowy wynik wygląda tak: + Prawidłowe dane wyjściowe wyglądają tak: - Transport kanału jest połączony. - Kontrole pairing/allowlist przechodzą pomyślnie. - - Wymagane mentions są wykrywane. + - Wzmianki są wykrywane tam, gdzie jest to wymagane. - Typowe sygnatury w logach: + Typowe sygnatury logów: - - `mention required` → bramka mention w grupie zablokowała przetwarzanie. - - `pairing` / `pending` → nadawca DM nie został jeszcze zatwierdzony. + - `mention required` → bramka wzmianek grupowych zablokowała przetwarzanie. + - `pairing` / `pending` → nadawca DM nie jest jeszcze zatwierdzony. - `not_in_channel`, `missing_scope`, `Forbidden`, `401/403` → problem z tokenem uprawnień kanału. Szczegółowe strony: - - [/gateway/troubleshooting#channel-connected-messages-not-flowing](/gateway/troubleshooting#channel-connected-messages-not-flowing) + - [/gateway/troubleshooting#channel-connected-messages-not-flowing](/pl/gateway/troubleshooting#channel-connected-messages-not-flowing) - [/channels/troubleshooting](/pl/channels/troubleshooting) @@ -228,30 +241,30 @@ flowchart TD openclaw logs --follow ``` - Prawidłowy wynik wygląda tak: + Prawidłowe dane wyjściowe wyglądają tak: - - `cron.status` pokazuje włączony stan i następne wybudzenie. + - `cron.status` pokazuje, że jest włączony i ma następne wybudzenie. - `cron runs` pokazuje ostatnie wpisy `ok`. - - Heartbeat jest włączony i nie znajduje się poza godzinami aktywności. + - Heartbeat jest włączony i nie znajduje się poza aktywnymi godzinami. - Typowe sygnatury w logach: + Typowe sygnatury logów: - `cron: scheduler disabled; jobs will not run automatically` → cron jest wyłączony. -- `heartbeat skipped` z `reason=quiet-hours` → poza skonfigurowanymi godzinami aktywności. -- `heartbeat skipped` z `reason=empty-heartbeat-file` → `HEARTBEAT.md` istnieje, ale zawiera tylko pusty/szablonowy nagłówek. -- `heartbeat skipped` z `reason=no-tasks-due` → aktywny jest tryb zadań `HEARTBEAT.md`, ale żaden z interwałów zadań nie jest jeszcze należny. -- `heartbeat skipped` z `reason=alerts-disabled` → cała widoczność heartbeat jest wyłączona (`showOk`, `showAlerts` i `useIndicator` są wszystkie wyłączone). -- `requests-in-flight` → pas main jest zajęty; wybudzenie heartbeat zostało odroczone. - `unknown accountId` → docelowe konto dostarczania heartbeat nie istnieje. +- `heartbeat skipped` z `reason=quiet-hours` → poza skonfigurowanymi aktywnymi godzinami. +- `heartbeat skipped` z `reason=empty-heartbeat-file` → `HEARTBEAT.md` istnieje, ale zawiera tylko puste/nagłówkowe szkielety. +- `heartbeat skipped` z `reason=no-tasks-due` → tryb zadań `HEARTBEAT.md` jest aktywny, ale żaden z interwałów zadań nie jest jeszcze należny. +- `heartbeat skipped` z `reason=alerts-disabled` → cała widoczność heartbeat jest wyłączona (`showOk`, `showAlerts` i `useIndicator` są wyłączone). +- `requests-in-flight` → główna ścieżka jest zajęta; wybudzenie heartbeat zostało odroczone. - `unknown accountId` → docelowe konto dostarczania heartbeat nie istnieje. Szczegółowe strony: - - [/gateway/troubleshooting#cron-and-heartbeat-delivery](/gateway/troubleshooting#cron-and-heartbeat-delivery) + - [/gateway/troubleshooting#cron-and-heartbeat-delivery](/pl/gateway/troubleshooting#cron-and-heartbeat-delivery) - [/automation/cron-jobs#troubleshooting](/pl/automation/cron-jobs#troubleshooting) - - [/gateway/heartbeat](/gateway/heartbeat) + - [/gateway/heartbeat](/pl/gateway/heartbeat) - + ```bash openclaw status openclaw gateway status @@ -260,24 +273,24 @@ flowchart TD openclaw logs --follow ``` - Prawidłowy wynik wygląda tak: + Prawidłowe dane wyjściowe wyglądają tak: - - Node jest pokazany jako połączony i sparowany dla roli `node`. - - Możliwość istnieje dla polecenia, które wywołujesz. + - Node jest wymieniony jako połączony i sparowany dla roli `node`. + - Dla wywoływanego polecenia istnieje capability. - Stan uprawnień jest przyznany dla narzędzia. - Typowe sygnatury w logach: + Typowe sygnatury logów: - `NODE_BACKGROUND_UNAVAILABLE` → przenieś aplikację node na pierwszy plan. - - `*_PERMISSION_REQUIRED` → uprawnienie systemowe zostało odrzucone lub go brakuje. - - `SYSTEM_RUN_DENIED: approval required` → zatwierdzenie exec oczekuje. - - `SYSTEM_RUN_DENIED: allowlist miss` → polecenia nie ma na allowlist exec. + - `*_PERMISSION_REQUIRED` → uprawnienie systemowe zostało odrzucone lub nie istnieje. + - `SYSTEM_RUN_DENIED: approval required` → oczekuje zatwierdzenie exec. + - `SYSTEM_RUN_DENIED: allowlist miss` → polecenia nie ma na liście dozwolonych exec. Szczegółowe strony: - - [/gateway/troubleshooting#node-paired-tool-fails](/gateway/troubleshooting#node-paired-tool-fails) - - [/nodes/troubleshooting](/nodes/troubleshooting) - - [/tools/exec-approvals](/tools/exec-approvals) + - [/gateway/troubleshooting#node-paired-tool-fails](/pl/gateway/troubleshooting#node-paired-tool-fails) + - [/nodes/troubleshooting](/pl/nodes/troubleshooting) + - [/tools/exec-approvals](/pl/tools/exec-approvals) @@ -291,14 +304,14 @@ flowchart TD Co się zmieniło: - - Jeśli `tools.exec.host` nie jest ustawione, domyślna wartość to `auto`. - - `host=auto` rozwiązuje się do `sandbox`, gdy aktywny jest runtime sandboxa, a w przeciwnym razie do `gateway`. - - `host=auto` dotyczy tylko routingu; zachowanie „YOLO” bez pytań wynika z `security=full` plus `ask=off` na gateway/node. - - Dla `gateway` i `node` nieustawione `tools.exec.security` domyślnie przyjmuje `full`. - - Nieustawione `tools.exec.ask` domyślnie przyjmuje `off`. - - Wynik: jeśli widzisz zatwierdzenia, jakaś lokalna dla hosta lub sesji polityka zaostrzyła exec w stosunku do bieżących ustawień domyślnych. + - Jeśli `tools.exec.host` nie jest ustawione, wartością domyślną jest `auto`. + - `host=auto` rozstrzyga się do `sandbox`, gdy aktywne jest środowisko sandbox, w przeciwnym razie do `gateway`. + - `host=auto` dotyczy tylko routingu; zachowanie „YOLO” bez promptu wynika z `security=full` oraz `ask=off` na gateway/node. + - W `gateway` i `node` nieustawione `tools.exec.security` domyślnie przyjmuje wartość `full`. + - Nieustawione `tools.exec.ask` domyślnie przyjmuje wartość `off`. + - Wniosek: jeśli widzisz zatwierdzenia, jakaś lokalna dla hosta lub dla sesji polityka zaostrzyła exec względem obecnych wartości domyślnych. - Przywróć bieżące domyślne zachowanie bez zatwierdzeń: + Przywróć obecne domyślne zachowanie bez zatwierdzeń: ```bash openclaw config set tools.exec.host gateway @@ -310,24 +323,24 @@ flowchart TD Bezpieczniejsze alternatywy: - Ustaw tylko `tools.exec.host=gateway`, jeśli chcesz po prostu stabilnego routingu hosta. - - Użyj `security=allowlist` z `ask=on-miss`, jeśli chcesz exec na hoście, ale nadal chcesz przeglądu przy trafieniu poza allowlist. - - Włącz tryb sandbox, jeśli chcesz, aby `host=auto` znów rozwiązywał się do `sandbox`. + - Użyj `security=allowlist` z `ask=on-miss`, jeśli chcesz exec na hoście, ale nadal chcesz przeglądu przy chybieniach allowlist. + - Włącz tryb sandbox, jeśli chcesz, aby `host=auto` znowu rozstrzygał się do `sandbox`. - Typowe sygnatury w logach: + Typowe sygnatury logów: - `Approval required.` → polecenie czeka na `/approve ...`. - - `SYSTEM_RUN_DENIED: approval required` → zatwierdzenie exec dla hosta node oczekuje. - - `exec host=sandbox requires a sandbox runtime for this session` → niejawny/jawny wybór sandboxa, ale tryb sandbox jest wyłączony. + - `SYSTEM_RUN_DENIED: approval required` → oczekuje zatwierdzenie exec na hoście node. + - `exec host=sandbox requires a sandbox runtime for this session` → niejawny/jawny wybór sandbox, ale tryb sandbox jest wyłączony. Szczegółowe strony: - - [/tools/exec](/tools/exec) - - [/tools/exec-approvals](/tools/exec-approvals) - - [/gateway/security#runtime-expectation-drift](/gateway/security#runtime-expectation-drift) + - [/tools/exec](/pl/tools/exec) + - [/tools/exec-approvals](/pl/tools/exec-approvals) + - [/gateway/security#runtime-expectation-drift](/pl/gateway/security#runtime-expectation-drift) - + ```bash openclaw status openclaw gateway status @@ -336,37 +349,37 @@ flowchart TD openclaw doctor ``` - Prawidłowy wynik wygląda tak: + Prawidłowe dane wyjściowe wyglądają tak: - - Status browser pokazuje `running: true` oraz wybraną przeglądarkę/profil. - - `openclaw` uruchamia się, albo `user` widzi lokalne karty Chrome. + - Status przeglądarki pokazuje `running: true` oraz wybraną przeglądarkę/profil. + - `openclaw` uruchamia się lub `user` widzi lokalne karty Chrome. - Typowe sygnatury w logach: + Typowe sygnatury logów: - `unknown command "browser"` lub `unknown command 'browser'` → ustawiono `plugins.allow` i nie zawiera ono `browser`. - `Failed to start Chrome CDP on port` → nie udało się uruchomić lokalnej przeglądarki. - - `browser.executablePath not found` → skonfigurowana ścieżka binarki jest błędna. + - `browser.executablePath not found` → skonfigurowana ścieżka do pliku binarnego jest błędna. - `browser.cdpUrl must be http(s) or ws(s)` → skonfigurowany URL CDP używa nieobsługiwanego schematu. - - `browser.cdpUrl has invalid port` → skonfigurowany URL CDP ma błędny lub spoza zakresu port. - - `No Chrome tabs found for profile="user"` → profil attach Chrome MCP nie ma otwartych lokalnych kart Chrome. + - `browser.cdpUrl has invalid port` → skonfigurowany URL CDP ma nieprawidłowy port lub port spoza zakresu. + - `No Chrome tabs found for profile="user"` → profil dołączania Chrome MCP nie ma otwartych lokalnych kart Chrome. - `Remote CDP for profile "" is not reachable` → skonfigurowany zdalny endpoint CDP jest nieosiągalny z tego hosta. - - `Browser attachOnly is enabled ... not reachable` lub `Browser attachOnly is enabled and CDP websocket ... is not reachable` → profil tylko dołączania nie ma aktywnego celu CDP. - - nieaktualne nadpisania viewport / dark-mode / locale / offline na profilach attach-only lub remote CDP → uruchom `openclaw browser stop --browser-profile `, aby zamknąć aktywną sesję sterowania i zwolnić stan emulacji bez restartu gateway. + - `Browser attachOnly is enabled ... not reachable` lub `Browser attachOnly is enabled and CDP websocket ... is not reachable` → profil tylko-dołączania nie ma aktywnego celu CDP. + - nieaktualne nadpisania viewport / dark-mode / locale / offline w profilach tylko-dołączania lub zdalnego CDP → uruchom `openclaw browser stop --browser-profile `, aby zamknąć aktywną sesję sterowania i zwolnić stan emulacji bez restartowania gateway. Szczegółowe strony: - - [/gateway/troubleshooting#browser-tool-fails](/gateway/troubleshooting#browser-tool-fails) - - [/tools/browser#missing-browser-command-or-tool](/tools/browser#missing-browser-command-or-tool) - - [/tools/browser-linux-troubleshooting](/tools/browser-linux-troubleshooting) - - [/tools/browser-wsl2-windows-remote-cdp-troubleshooting](/tools/browser-wsl2-windows-remote-cdp-troubleshooting) + - [/gateway/troubleshooting#browser-tool-fails](/pl/gateway/troubleshooting#browser-tool-fails) + - [/tools/browser#missing-browser-command-or-tool](/pl/tools/browser#missing-browser-command-or-tool) + - [/tools/browser-linux-troubleshooting](/pl/tools/browser-linux-troubleshooting) + - [/tools/browser-wsl2-windows-remote-cdp-troubleshooting](/pl/tools/browser-wsl2-windows-remote-cdp-troubleshooting) ## Powiązane -- [FAQ](/help/faq) — często zadawane pytania -- [Gateway Troubleshooting](/gateway/troubleshooting) — problemy specyficzne dla gateway -- [Doctor](/gateway/doctor) — automatyczne kontrole kondycji i naprawy -- [Channel Troubleshooting](/pl/channels/troubleshooting) — problemy z łącznością kanałów -- [Automation Troubleshooting](/pl/automation/cron-jobs#troubleshooting) — problemy z cron i heartbeat +- [FAQ](/pl/help/faq) — często zadawane pytania +- [Rozwiązywanie problemów z Gateway](/pl/gateway/troubleshooting) — problemy specyficzne dla gateway +- [Doctor](/pl/gateway/doctor) — zautomatyzowane kontrole kondycji i naprawy +- [Rozwiązywanie problemów z kanałami](/pl/channels/troubleshooting) — problemy z łącznością kanałów +- [Rozwiązywanie problemów z automatyzacją](/pl/automation/cron-jobs#troubleshooting) — problemy z cron i heartbeat diff --git a/docs/pl/plugins/architecture.md b/docs/pl/plugins/architecture.md index 9128a93a1..33849450b 100644 --- a/docs/pl/plugins/architecture.md +++ b/docs/pl/plugins/architecture.md @@ -1,17 +1,17 @@ --- read_when: - Tworzenie lub debugowanie natywnych pluginów OpenClaw - - Zrozumienie modelu capabilities pluginów lub granic własności - - Praca nad pipeline ładowania pluginów lub rejestrem - - Implementacja hooków runtime dostawców lub pluginów kanałów + - Zrozumienie modelu możliwości pluginów lub granic własności + - Praca nad potokiem ładowania pluginów lub rejestrem + - Implementowanie haków runtime dostawców lub pluginów kanałów sidebarTitle: Internals -summary: 'Wnętrze pluginów: model capabilities, własność, kontrakty, pipeline ładowania i pomocniki runtime' +summary: 'Wnętrze pluginów: model możliwości, własność, kontrakty, potok ładowania i pomocniki runtime' title: Wnętrze pluginów x-i18n: - generated_at: "2026-04-07T09:50:37Z" + generated_at: "2026-04-08T02:21:29Z" model: gpt-5.4 provider: openai - source_hash: a48b387152c5a6a9782c5aaa9d6c215c16adb7cb256302d3e85f80b03f9b6898 + source_hash: c40ecf14e2a0b2b8d332027aed939cd61fb4289a489f4cd4c076c96d707d1138 source_path: plugins/architecture.md workflow: 15 --- @@ -19,108 +19,108 @@ x-i18n: # Wnętrze pluginów - To jest **szczegółowa dokumentacja architektury**. Praktyczne przewodniki znajdziesz tutaj: + To jest **szczegółowe odniesienie do architektury**. Praktyczne przewodniki znajdziesz tutaj: - [Instalowanie i używanie pluginów](/pl/tools/plugin) — przewodnik użytkownika - - [Pierwsze kroki](/pl/plugins/building-plugins) — pierwszy samouczek tworzenia 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 + - [Pierwsze kroki](/pl/plugins/building-plugins) — samouczek pierwszego pluginu + - [Pluginy kanałów](/pl/plugins/sdk-channel-plugins) — budowanie kanału wiadomości + - [Pluginy dostawców](/pl/plugins/sdk-provider-plugins) — budowanie dostawcy modeli - [Przegląd SDK](/pl/plugins/sdk-overview) — mapa importów i API rejestracji Ta strona opisuje wewnętrzną architekturę systemu pluginów OpenClaw. -## Publiczny model capabilities +## Publiczny model możliwości -Capabilities to publiczny model **natywnych pluginów** wewnątrz OpenClaw. Każdy -natywny plugin OpenClaw rejestruje się względem co najmniej jednego typu capability: +Możliwości to publiczny model **natywnych pluginów** w OpenClaw. Każdy +natywny plugin OpenClaw rejestruje się względem co najmniej jednego typu możliwości: -| Capability | Metoda rejestracji | Przykładowe pluginy | -| ---------------------- | --------------------------------------------- | ----------------------------------- | -| Wnioskowanie tekstowe | `api.registerProvider(...)` | `openai`, `anthropic` | -| Backend wnioskowania CLI | `api.registerCliBackend(...)` | `openai`, `anthropic` | -| Mowa | `api.registerSpeechProvider(...)` | `elevenlabs`, `microsoft` | +| Możliwość | Metoda rejestracji | Przykładowe pluginy | +| --------------------- | ---------------------------------------------- | ---------------------------------- | +| Wnioskowanie tekstowe | `api.registerProvider(...)` | `openai`, `anthropic` | +| Backend wnioskowania CLI | `api.registerCliBackend(...)` | `openai`, `anthropic` | +| Mowa | `api.registerSpeechProvider(...)` | `elevenlabs`, `microsoft` | | Transkrypcja w czasie rzeczywistym | `api.registerRealtimeTranscriptionProvider(...)` | `openai` | -| Głos w czasie rzeczywistym | `api.registerRealtimeVoiceProvider(...)` | `openai` | -| Rozumienie mediów | `api.registerMediaUnderstandingProvider(...)` | `openai`, `google` | -| Generowanie obrazów | `api.registerImageGenerationProvider(...)` | `openai`, `google`, `fal`, `minimax` | -| Generowanie muzyki | `api.registerMusicGenerationProvider(...)` | `google`, `minimax` | -| Generowanie wideo | `api.registerVideoGenerationProvider(...)` | `qwen` | -| Pobieranie z sieci | `api.registerWebFetchProvider(...)` | `firecrawl` | -| Wyszukiwanie w sieci | `api.registerWebSearchProvider(...)` | `google` | -| Kanał / wiadomości | `api.registerChannel(...)` | `msteams`, `matrix` | +| Głos w czasie rzeczywistym | `api.registerRealtimeVoiceProvider(...)` | `openai` | +| Rozumienie mediów | `api.registerMediaUnderstandingProvider(...)` | `openai`, `google` | +| Generowanie obrazów | `api.registerImageGenerationProvider(...)` | `openai`, `google`, `fal`, `minimax` | +| Generowanie muzyki | `api.registerMusicGenerationProvider(...)` | `google`, `minimax` | +| Generowanie wideo | `api.registerVideoGenerationProvider(...)` | `qwen` | +| Pobieranie z sieci | `api.registerWebFetchProvider(...)` | `firecrawl` | +| Wyszukiwanie w sieci | `api.registerWebSearchProvider(...)` | `google` | +| Kanał / wiadomości | `api.registerChannel(...)` | `msteams`, `matrix` | -Plugin, który rejestruje zero capabilities, ale dostarcza hooki, narzędzia lub -usługi, to **starszy plugin tylko z hookami**. Ten wzorzec nadal jest w pełni obsługiwany. +Plugin, który rejestruje zero możliwości, ale udostępnia hooki, narzędzia lub +usługi, jest **starszym pluginem tylko z hookami**. Ten wzorzec nadal jest w pełni wspierany. -### Stan kompatybilności zewnętrznej +### Stanowisko wobec zgodności zewnętrznej -Model capabilities jest już wdrożony w core i używany przez dołączone/natywne pluginy -już dziś, ale kompatybilność z zewnętrznymi pluginami nadal wymaga wyższego progu niż „jest -eksportowane, więc jest zamrożone”. +Model możliwości jest wdrożony w rdzeniu i używany przez pluginy +bundlowane/natywne już dziś, ale zgodność zewnętrznych pluginów nadal wymaga +wyższego progu niż „jest eksportowane, więc jest zamrożone”. -Aktualne wytyczne: +Obecne wytyczne: -- **istniejące pluginy zewnętrzne:** utrzymuj integracje oparte na hookach w działaniu; traktuj - to jako bazowy poziom kompatybilności -- **nowe dołączone/natywne pluginy:** preferuj jawną rejestrację capabilities zamiast - zależności specyficznych dla dostawcy lub nowych projektów tylko z hookami -- **zewnętrzne pluginy przyjmujące rejestrację capabilities:** dozwolone, ale traktuj - pomocnicze powierzchnie specyficzne dla capability jako rozwijające się, dopóki dokumentacja - wyraźnie nie oznaczy kontraktu jako stabilnego +- **istniejące pluginy zewnętrzne:** utrzymuj działanie integracji opartych na hookach; traktuj + to jako bazowy poziom zgodności +- **nowe pluginy bundlowane/natywne:** preferuj jawną rejestrację możliwości zamiast + dostępu przez reach-in specyficzny dla dostawcy lub nowych projektów wyłącznie hookowych +- **zewnętrzne pluginy przyjmujące rejestrację możliwości:** dozwolone, ale + traktuj powierzchnie pomocnicze specyficzne dla możliwości jako rozwijające się, chyba że dokumentacja jawnie oznacza + dany kontrakt jako stabilny Praktyczna zasada: -- API rejestracji capabilities to zamierzony kierunek -- starsze hooki pozostają najbezpieczniejszą ścieżką bez ryzyka złamania dla zewnętrznych pluginów w trakcie +- API rejestracji możliwości to zamierzony kierunek +- starsze hooki pozostają najbezpieczniejszą ścieżką bez zrywania zgodności dla pluginów zewnętrznych w czasie przejścia -- eksportowane subścieżki pomocnicze nie są sobie równe; preferuj wąski udokumentowany +- eksportowane podścieżki pomocnicze nie są sobie równe; preferuj wąski udokumentowany kontrakt, a nie przypadkowe eksporty pomocnicze ### Kształty pluginów -OpenClaw klasyfikuje każdy załadowany plugin według jego faktycznego +OpenClaw klasyfikuje każdy załadowany plugin do jednego z kształtów na podstawie jego rzeczywistego zachowania rejestracyjnego (a nie tylko statycznych metadanych): -- **plain-capability** -- rejestruje dokładnie jeden typ capability (na przykład +- **plain-capability** -- rejestruje dokładnie jeden typ możliwości (na przykład plugin tylko dostawcy, taki jak `mistral`) -- **hybrid-capability** -- rejestruje wiele typów capability (na przykład - `openai` obsługuje wnioskowanie tekstowe, mowę, rozumienie mediów i - generowanie obrazów) -- **hook-only** -- rejestruje tylko hooki (typowane lub niestandardowe), bez capabilities, +- **hybrid-capability** -- rejestruje wiele typów możliwości (na przykład + `openai` obsługuje wnioskowanie tekstowe, mowę, rozumienie mediów oraz generowanie + obrazów) +- **hook-only** -- rejestruje tylko hooki (typowane lub niestandardowe), bez możliwości, narzędzi, poleceń ani usług -- **non-capability** -- rejestruje narzędzia, polecenia, usługi lub trasy, ale bez - capabilities +- **non-capability** -- rejestruje narzędzia, polecenia, usługi lub trasy, ale nie + możliwości Użyj `openclaw plugins inspect `, aby zobaczyć kształt pluginu i rozkład -capabilities. Szczegóły znajdziesz w [dokumentacji CLI](/cli/plugins#inspect). +możliwości. Szczegóły znajdziesz w [odniesieniu do CLI](/cli/plugins#inspect). ### Starsze hooki -Hook `before_agent_start` pozostaje obsługiwany jako ścieżka kompatybilności dla -pluginów tylko z hookami. Istniejące rzeczywiste pluginy nadal od niego zależą. +Hook `before_agent_start` pozostaje wspierany jako ścieżka zgodności dla +pluginów tylko z hookami. Starsze rzeczywiste pluginy nadal od niego zależą. Kierunek: -- zachować działanie -- dokumentować jako starszy -- preferować `before_model_resolve` dla pracy z nadpisywaniem modelu/dostawcy -- preferować `before_prompt_build` dla modyfikacji promptów -- usunąć dopiero, gdy rzeczywiste użycie spadnie, a pokrycie testami fixture potwierdzi bezpieczeństwo migracji +- utrzymać jego działanie +- udokumentować go jako starszy +- preferować `before_model_resolve` do pracy nad nadpisywaniem modelu/dostawcy +- preferować `before_prompt_build` do modyfikacji promptu +- usunąć dopiero wtedy, gdy rzeczywiste użycie spadnie, a pokrycie fixture’ów potwierdzi bezpieczeństwo migracji -### Sygnały kompatybilności +### Sygnały zgodności -Gdy uruchamiasz `openclaw doctor` albo `openclaw plugins inspect `, możesz zobaczyć +Po uruchomieniu `openclaw doctor` albo `openclaw plugins inspect ` możesz zobaczyć jedną z tych etykiet: -| Sygnał | Znaczenie | -| -------------------------- | ------------------------------------------------------------- | +| Sygnał | Znaczenie | +| -------------------------- | ----------------------------------------------------------- | | **config valid** | Konfiguracja parsuje się poprawnie, a pluginy są rozwiązywane | -| **compatibility advisory** | Plugin używa obsługiwanego, ale starszego wzorca (np. `hook-only`) | -| **legacy warning** | Plugin używa `before_agent_start`, które jest przestarzałe | +| **compatibility advisory** | Plugin używa wspieranego, ale starszego wzorca (np. `hook-only`) | +| **legacy warning** | Plugin używa `before_agent_start`, które jest przestarzałe | | **hard error** | Konfiguracja jest nieprawidłowa albo plugin nie załadował się | -Ani `hook-only`, ani `before_agent_start` nie złamią dziś Twojego pluginu -- -`hook-only` ma charakter informacyjny, a `before_agent_start` wywołuje tylko ostrzeżenie. Te +Ani `hook-only`, ani `before_agent_start` nie zepsują dziś Twojego pluginu -- +`hook-only` ma charakter doradczy, a `before_agent_start` wywołuje tylko ostrzeżenie. Te sygnały pojawiają się także w `openclaw status --all` i `openclaw plugins doctor`. ## Przegląd architektury @@ -128,59 +128,59 @@ sygnały pojawiają się także w `openclaw status --all` i `openclaw plugins do System pluginów OpenClaw ma cztery warstwy: 1. **Manifest + wykrywanie** - OpenClaw znajduje kandydackie pluginy w skonfigurowanych ścieżkach, korzeniach workspace, - globalnych korzeniach rozszerzeń i wśród dołączonych rozszerzeń. Wykrywanie najpierw odczytuje natywne - manifesty `openclaw.plugin.json` oraz obsługiwane manifesty bundle. + OpenClaw znajduje kandydackie pluginy na podstawie skonfigurowanych ścieżek, korzeni + workspace, globalnych korzeni rozszerzeń i bundlowanych rozszerzeń. Wykrywanie najpierw odczytuje natywne + manifesty `openclaw.plugin.json` oraz wspierane manifesty bundle. 2. **Włączanie + walidacja** - Core decyduje, czy wykryty plugin jest włączony, wyłączony, zablokowany czy + Rdzeń decyduje, czy wykryty plugin jest włączony, wyłączony, zablokowany, czy wybrany do ekskluzywnego slotu, takiego jak pamięć. 3. **Ładowanie runtime** Natywne pluginy OpenClaw są ładowane w tym samym procesie przez jiti i rejestrują - capabilities w centralnym rejestrze. Zgodne bundle są normalizowane do rekordów - rejestru bez importowania kodu runtime. -4. **Zużycie powierzchni** - Reszta OpenClaw odczytuje rejestr, aby udostępnić narzędzia, kanały, konfigurację + możliwości w centralnym rejestrze. Zgodne bundle są normalizowane do + rekordów rejestru bez importowania kodu runtime. +4. **Konsumpcja powierzchni** + Reszta OpenClaw odczytuje rejestr, aby udostępniać narzędzia, kanały, konfigurację dostawców, hooki, trasy HTTP, polecenia CLI i usługi. -W przypadku pluginowego CLI wykrywanie poleceń głównych jest podzielone na dwie fazy: +Konkretnie dla CLI pluginów, wykrywanie poleceń głównych jest podzielone na dwie fazy: - metadane czasu parsowania pochodzą z `registerCli(..., { descriptors: [...] })` -- rzeczywisty moduł CLI pluginu może pozostać leniwy i zarejestrować się przy pierwszym wywołaniu +- właściwy moduł CLI pluginu może pozostać leniwy 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 głównych poleceń przed parsowaniem. +Dzięki temu kod CLI należący do pluginu pozostaje w pluginie, a OpenClaw nadal może +zarezerwować nazwy poleceń głównych przed parsowaniem. -Ważna granica projektowa: +Istotna granica projektowa: - wykrywanie + walidacja konfiguracji powinny działać na podstawie **metadanych manifestu/schematu** bez wykonywania kodu pluginu -- natywne zachowanie runtime pochodzi ze ścieżki modułu pluginu `register(api)` +- natywne zachowanie runtime pochodzi ze ścieżki `register(api)` modułu pluginu Ten podział pozwala OpenClaw walidować konfigurację, wyjaśniać brakujące/wyłączone pluginy i -budować wskazówki UI/schematu, zanim pełny runtime stanie się aktywny. +budować podpowiedzi UI/schematu zanim pełne runtime stanie się aktywne. -### Pluginy kanałów i współdzielone narzędzie wiadomości +### Pluginy kanałów i współdzielone narzędzie message -Pluginy kanałów nie muszą rejestrować osobnego narzędzia wysyłania/edycji/reakcji dla -zwykłych akcji czatu. OpenClaw utrzymuje jedno współdzielone narzędzie `message` w core, a -pluginy kanałów obsługują specyficzne dla kanału wykrywanie i wykonanie za nim. +Pluginy kanałów nie muszą rejestrować osobnego narzędzia send/edit/react dla +zwykłych działań czatu. OpenClaw utrzymuje jedno współdzielone narzędzie `message` w rdzeniu, a +pluginy kanałów odpowiadają za specyficzne dla kanału wykrywanie i wykonanie za nim. -Obecna granica wygląda tak: +Obecna granica jest następująca: -- core odpowiada za host współdzielonego narzędzia `message`, podłączenie promptów, ewidencję - sesji/wątków oraz dyspozycję wykonania -- pluginy kanałów odpowiadają za wykrywanie akcji z odpowiednim zakresem, wykrywanie capabilities oraz - wszelkie fragmenty schematu specyficzne dla kanału +- rdzeń odpowiada za host współdzielonego narzędzia `message`, integrację promptu, księgowanie + sesji/wątków i dyspozycję wykonania +- pluginy kanałów odpowiadają za wykrywanie działań w zakresie, wykrywanie możliwości i wszelkie + fragmenty schematu specyficzne dla kanału - pluginy kanałów odpowiadają za gramatykę konwersacji 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ńcową akcję przez swój adapter akcji + za to, jak 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ń -W przypadku pluginów kanałów powierzchnią SDK jest +Dla pluginów kanałów powierzchnią SDK jest `ChannelMessageActionAdapter.describeMessageTool(...)`. To ujednolicone wywołanie wykrywania -pozwala pluginowi zwrócić widoczne akcje, capabilities i wkłady do schematu -razem, tak aby te elementy nie rozjeżdżały się między sobą. +pozwala pluginowi zwrócić widoczne działania, możliwości i wkład do schematu +razem, aby te elementy nie zaczęły się rozjeżdżać. -Core przekazuje zakres runtime do tego kroku wykrywania. Ważne pola to: +Rdzeń przekazuje zakres runtime do tego kroku wykrywania. Ważne pola to: - `accountId` - `currentChannelId` @@ -192,118 +192,120 @@ Core przekazuje zakres runtime do tego kroku wykrywania. Ważne pola to: - zaufany przychodzący `requesterSenderId` Ma to znaczenie dla pluginów zależnych od kontekstu. Kanał może ukrywać lub ujawniać -akcje wiadomości na podstawie aktywnego konta, bieżącego pokoju/wątku/wiadomości lub -zaufanej tożsamości żądającego, bez twardego kodowania gałęzi specyficznych dla kanału w -narzędziu `message` w core. +działania message na podstawie aktywnego konta, bieżącego pokoju/wątku/wiadomości albo +zaufanej tożsamości nadawcy żądania bez twardego kodowania gałęzi specyficznych dla kanału w +narzędziu rdzeniowym `message`. -Dlatego zmiany routingu embedded-runner nadal są pracą pluginową: runner jest -odpowiedzialny za przekazanie bieżącej tożsamości czatu/sesji do granicy wykrywania pluginu, tak aby współdzielone -narzędzie `message` udostępniało właściwą powierzchnię należącą do kanału dla bieżącej tury. +Dlatego zmiany routingu embedded-runner nadal należą do pracy pluginu: runner jest +odpowiedzialny za przekazywanie bieżącej tożsamości czatu/sesji do granicy wykrywania pluginu, +aby współdzielone narzędzie `message` ujawniało właściwą powierzchnię należącą do kanału +dla bieżącego kroku. -W przypadku pomocników wykonania należących do kanału dołączone pluginy powinny utrzymywać runtime -wykonania we własnych modułach rozszerzenia. Core nie odpowiada już za -runtime akcji wiadomości Discord, Slack, Telegram ani WhatsApp w `src/agents/tools`. -Nie publikujemy osobnych subścieżek `plugin-sdk/*-action-runtime`, a dołączone +W przypadku pomocników wykonania należących do kanału, bundlowane pluginy powinny utrzymywać runtime wykonania +we własnych modułach rozszerzeń. Rdzeń nie odpowiada już za runtime działań wiadomości Discord, +Slack, Telegram ani WhatsApp w `src/agents/tools`. +Nie publikujemy oddzielnych podścieżek `plugin-sdk/*-action-runtime`, a bundlowane pluginy powinny importować własny lokalny kod runtime bezpośrednio ze swoich modułów rozszerzeń. -Ta sama granica dotyczy ogólnie nazwanych po dostawcach szczelin SDK: core nie -powinno importować wygodnych barrelów specyficznych dla kanałów takich jak Slack, Discord, Signal, -WhatsApp ani podobnych rozszerzeń. Jeśli core potrzebuje jakiegoś zachowania, powinno albo -skorzystać z własnego barrela `api.ts` / `runtime-api.ts` dołączonego pluginu, albo podnieść potrzebę -do poziomu wąskiego ogólnego capability we współdzielonym SDK. +Ta sama granica dotyczy ogólnie nazwanych przez dostawcę szczelin SDK: rdzeń nie powinien +importować wygodnych barrelów specyficznych dla kanału dla Slack, Discord, Signal, +WhatsApp ani podobnych rozszerzeń. Jeśli rdzeń potrzebuje jakiegoś zachowania, powinien albo +skorzystać z własnego barrela `api.ts` / `runtime-api.ts` bundlowanego pluginu, albo awansować tę potrzebę +do wąskiej ogólnej możliwości we współdzielonym SDK. -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 pasujących do wspólnego +- `outbound.sendPoll` to współdzielona baza dla kanałów, które pasują do wspólnego modelu ankiet -- `actions.handleAction("poll")` to preferowana ścieżka dla semantyki ankiet specyficznej dla kanału lub dodatkowych parametrów ankiet +- `actions.handleAction("poll")` to preferowana ścieżka dla semantyki ankiet specyficznej dla kanału + albo dodatkowych parametrów ankiet -Core odracza teraz współdzielone parsowanie ankiet do momentu, gdy pluginowa dyspozycja ankiety odrzuci -akcję, aby należące do pluginu handlery ankiet mogły akceptować pola ankiet specyficzne dla kanału -bez blokowania najpierw przez ogólny parser ankiet. +Rdzeń odracza teraz współdzielone parsowanie ankiet do momentu, gdy dyspozycja ankiety pluginu odrzuci +działanie, dzięki czemu obsługujące ankiety należące do pluginu mogą akceptować pola ankiet specyficzne dla kanału +bez wcześniejszego blokowania przez ogólny parser ankiet. -Pełną sekwencję uruchamiania znajdziesz w sekcji [Pipeline ładowania](#load-pipeline). +Pełną sekwencję uruchamiania znajdziesz w [Potoku ładowania](#load-pipeline). -## Model własności capabilities +## Model własności możliwości OpenClaw traktuje natywny plugin jako granicę własności dla **firmy** albo -**funkcji**, a nie jako worek niepowiązanych integracji. +**funkcji**, a nie jako zbiór niezwiązanych integracji. To oznacza, że: -- plugin firmy powinien zazwyczaj posiadać wszystkie powierzchnie OpenClaw-facing tej firmy -- plugin funkcji powinien zazwyczaj posiadać pełną powierzchnię funkcji, którą wprowadza -- kanały powinny korzystać ze współdzielonych capabilities core zamiast doraźnie - ponownie implementować zachowania dostawców +- plugin firmy powinien zwykle posiadać wszystkie powierzchnie OpenClaw-facing tej firmy +- plugin funkcji powinien zwykle posiadać pełną powierzchnię funkcji, którą wprowadza +- kanały powinny korzystać ze współdzielonych możliwości rdzenia zamiast doraźnie ponownie implementować + zachowanie dostawcy Przykłady: -- dołączony plugin `openai` posiada zachowanie dostawcy modeli OpenAI i zachowanie OpenAI - dla mowy + głosu w czasie rzeczywistym + rozumienia mediów + generowania obrazów -- dołączony plugin `elevenlabs` posiada zachowanie mowy ElevenLabs -- dołączony plugin `microsoft` posiada zachowanie mowy Microsoft -- dołączony plugin `google` posiada zachowanie dostawcy modeli Google oraz Google +- bundlowany plugin `openai` obsługuje zachowanie dostawcy modeli OpenAI oraz OpenAI + speech + realtime-voice + media-understanding + image-generation +- bundlowany plugin `elevenlabs` obsługuje zachowanie mowy ElevenLabs +- bundlowany plugin `microsoft` obsługuje zachowanie mowy Microsoft +- bundlowany plugin `google` obsługuje zachowanie dostawcy modeli Google oraz Google media-understanding + image-generation + web-search -- dołączony plugin `firecrawl` posiada zachowanie web-fetch Firecrawl -- dołączone pluginy `minimax`, `mistral`, `moonshot` i `zai` posiadają swoje +- bundlowany plugin `firecrawl` obsługuje zachowanie web-fetch Firecrawl +- bundlowane pluginy `minimax`, `mistral`, `moonshot` i `zai` obsługują swoje backendy media-understanding -- plugin `voice-call` jest pluginem funkcji: posiada transport połączeń, narzędzia, - CLI, trasy i mostkowanie strumieni mediów Twilio, ale korzysta ze współdzielonych capabilities - mowy oraz transkrypcji i głosu w czasie rzeczywistym zamiast bezpośrednio importować pluginy dostawców +- plugin `voice-call` jest pluginem funkcji: obsługuje transport połączeń, narzędzia, + CLI, trasy i mostkowanie strumieni mediów Twilio, ale korzysta ze współdzielonych możliwości speech + oraz realtime-transcription i realtime-voice zamiast bezpośrednio importować pluginy dostawców -Zamierzony stan końcowy jest taki: +Zamierzony stan końcowy jest następujący: - 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 -- kanałów nie obchodzi, który plugin dostawcy posiada dostawcę; korzystają ze - współdzielonego kontraktu capability udostępnianego przez core +- kanały nie obchodzą szczegóły tego, który plugin dostawcy obsługuje danego providera; korzystają ze + współdzielonego kontraktu możliwości udostępnianego przez rdzeń -To kluczowe rozróżnienie: +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 rdzenia, który może być implementowany lub używany przez wiele pluginów -Jeśli więc OpenClaw doda nową domenę, taką jak wideo, pierwsze pytanie nie brzmi -„który dostawca powinien zakodować na sztywno obsługę wideo?”. Pierwsze pytanie brzmi „jaki jest -kontrakt core capability dla wideo?”. Gdy taki kontrakt istnieje, pluginy dostawców +Jeśli więc OpenClaw doda nową domenę, taką jak wideo, pierwszym pytaniem nie jest +„który dostawca powinien na sztywno obsłużyć wideo?”. Pierwsze pytanie brzmi: „jaki jest +rdzeniowy kontrakt możliwości wideo?”. Gdy ten kontrakt istnieje, pluginy dostawców mogą się względem niego rejestrować, a pluginy kanałów/funkcji mogą z niego korzystać. -Jeśli capability jeszcze nie istnieje, właściwym ruchem jest zazwyczaj: +Jeśli możliwość jeszcze nie istnieje, właściwy ruch to zwykle: -1. zdefiniowanie brakującego capability w core -2. udostępnienie go przez API/runtime pluginów w sposób typowany -3. podłączenie kanałów/funkcji do tego capability -4. pozwolenie pluginom dostawców na rejestrowanie implementacji +1. zdefiniować brakującą możliwość w rdzeniu +2. udostępnić ją przez API/runtime pluginów w sposób typowany +3. podłączyć kanały/funkcje do tej możliwości +4. pozwolić pluginom dostawców rejestrować implementacje -Pozwala to zachować jawną własność, unikając jednocześnie zachowań core zależnych od -jednego dostawcy lub jednorazowej ścieżki kodu specyficznej dla pluginu. +Dzięki temu własność pozostaje jawna, a jednocześnie unika się zachowania rdzenia zależnego od +jednego dostawcy albo jednorazowej ścieżki kodu specyficznej dla pluginu. -### Warstwowanie capabilities +### Warstwowanie możliwości -Używaj tego modelu mentalnego przy decydowaniu, gdzie powinien znajdować się kod: +Użyj tego modelu mentalnego przy decydowaniu, gdzie powinien znajdować się kod: -- **warstwa core capability**: współdzielona orkiestracja, zasady, fallback, konfiguracja, - reguły scalania, semantyka dostarczania i typowane kontrakty +- **warstwa możliwości rdzenia**: współdzielona orkiestracja, polityka, fallback, zasady + łączenia konfiguracji, semantyka dostarczania i typowane kontrakty - **warstwa pluginu dostawcy**: API specyficzne dla dostawcy, auth, katalogi modeli, synteza mowy, generowanie obrazów, przyszłe backendy wideo, endpointy użycia -- **warstwa pluginu kanału/funkcji**: integracja Slack/Discord/voice-call/itp., - która korzysta z capabilities core i prezentuje je na określonej powierzchni +- **warstwa pluginu kanału/funkcji**: integracja Slack/Discord/voice-call itd., + która zużywa możliwości rdzenia i prezentuje je na powierzchni -Na przykład TTS wygląda tak: +Na przykład TTS ma następującą strukturę: -- core posiada politykę TTS podczas odpowiedzi, kolejność fallback, preferencje i dostarczanie przez kanały -- `openai`, `elevenlabs` i `microsoft` posiadają implementacje syntezy +- rdzeń obsługuje politykę TTS podczas odpowiedzi, kolejność fallback, preferencje i dostarczanie na kanał +- `openai`, `elevenlabs` i `microsoft` obsługują implementacje syntezy - `voice-call` korzysta z pomocnika runtime TTS dla telefonii -Ten sam wzorzec powinien być preferowany dla przyszłych capabilities. +Ten sam wzorzec należy preferować dla przyszłych możliwości. -### Przykład firmowego pluginu o wielu capabilities +### 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, +Plugin firmy powinien sprawiać wrażenie spójnego z zewnątrz. Jeśli OpenClaw ma współdzielone +kontrakty dla modeli, mowy, transkrypcji w czasie rzeczywistym, głosu w czasie rzeczywistym, rozumienia +mediów, generowania obrazów, generowania wideo, web fetch i web search, dostawca może posiadać wszystkie swoje powierzchnie w jednym miejscu: ```ts @@ -319,12 +321,12 @@ const plugin: OpenClawPluginDefinition = { register(api) { api.registerProvider({ id: "exampleai", - // auth/model catalog/runtime hooks + // hooki auth/katalogu modeli/runtime }); api.registerSpeechProvider({ id: "exampleai", - // vendor speech config — implement the SpeechProviderPlugin interface directly + // konfiguracja mowy dostawcy — zaimplementuj bezpośrednio interfejs SpeechProviderPlugin }); api.registerMediaUnderstandingProvider({ @@ -349,7 +351,7 @@ const plugin: OpenClawPluginDefinition = { api.registerWebSearchProvider( createPluginBackedWebSearchProvider({ id: "exampleai-search", - // credential + fetch logic + // logika poświadczeń + pobierania }), ); }, @@ -358,31 +360,31 @@ const plugin: OpenClawPluginDefinition = { export default plugin; ``` -Ważne nie są dokładne nazwy helperów. Ważny jest kształt: +Nie są istotne dokładne nazwy pomocników. Liczy się kształt: - jeden plugin posiada powierzchnię dostawcy -- core nadal posiada kontrakty capabilities -- kanały i pluginy funkcji korzystają z helperów `api.runtime.*`, a nie z kodu dostawcy -- testy kontraktowe mogą sprawdzać, że plugin zarejestrował capabilities, - których własność deklaruje +- rdzeń nadal posiada kontrakty możliwości +- kanały i pluginy funkcji korzystają z pomocników `api.runtime.*`, a nie z kodu dostawcy +- testy kontraktowe mogą potwierdzić, że plugin zarejestrował możliwości, które + deklaruje jako własne -### Przykład capability: rozumienie wideo +### Przykład możliwości: rozumienie wideo -OpenClaw już traktuje rozumienie obrazu/dźwięku/wideo jako jedno współdzielone -capability. Stosuje się tu ten sam model własności: +OpenClaw już traktuje rozumienie obrazów/audio/wideo jako jedną współdzieloną +możliwość. Ten sam model własności ma tu zastosowanie: -1. core definiuje kontrakt media-understanding -2. pluginy dostawców rejestrują odpowiednio `describeImage`, `transcribeAudio` i - `describeVideo` -3. kanały i pluginy funkcji korzystają ze współdzielonego zachowania core zamiast - podłączać się bezpośrednio do kodu dostawcy +1. rdzeń definiuje kontrakt media-understanding +2. pluginy dostawców rejestrują `describeImage`, `transcribeAudio` i + `describeVideo` w zależności od potrzeb +3. kanały i pluginy funkcji korzystają ze współdzielonego zachowania rdzenia zamiast + podpinać się bezpośrednio do kodu dostawcy -Pozwala to uniknąć wbudowania założeń jednego dostawcy o wideo w core. Plugin posiada -powierzchnię dostawcy; core posiada kontrakt capability i zachowanie fallback. +To zapobiega wbudowywaniu założeń jednego dostawcy dotyczących wideo do rdzenia. Plugin posiada +powierzchnię dostawcy; rdzeń posiada kontrakt możliwości i zachowanie fallback. -Generowanie wideo już używa tej samej sekwencji: core posiada typowany -kontrakt capability i helper runtime, a pluginy dostawców rejestrują implementacje -`api.registerVideoGenerationProvider(...)`. +Generowanie wideo już używa tej samej sekwencji: rdzeń posiada typowany +kontrakt możliwości i pomocnik runtime, a pluginy dostawców rejestrują +implementacje `api.registerVideoGenerationProvider(...)` względem niego. Potrzebujesz konkretnej listy wdrożeniowej? Zobacz [Capability Cookbook](/pl/plugins/architecture). @@ -390,189 +392,190 @@ Potrzebujesz konkretnej listy wdrożeniowej? Zobacz ## Kontrakty i egzekwowanie Powierzchnia API pluginów jest celowo typowana i scentralizowana w -`OpenClawPluginApi`. Ten kontrakt definiuje obsługiwane punkty rejestracji i +`OpenClawPluginApi`. Ten kontrakt definiuje wspierane punkty rejestracji i pomocniki runtime, na których plugin może polegać. Dlaczego to ważne: -- autorzy pluginów dostają jeden stabilny standard wewnętrzny -- core może odrzucać duplikaty własności, na przykład dwa pluginy rejestrujące ten sam +- autorzy pluginów dostają jeden stabilny wewnętrzny standard +- rdzeń może odrzucić duplikaty własności, na przykład dwa pluginy rejestrujące ten sam identyfikator dostawcy -- uruchamianie może pokazywać diagnostykę nadającą się do działania dla błędnych rejestracji -- testy kontraktowe mogą wymuszać własność dołączonych pluginów i zapobiegać cichemu dryfowi +- uruchamianie może pokazać praktyczną diagnostykę dla błędnej rejestracji +- testy kontraktowe mogą egzekwować własność bundlowanych pluginów i zapobiegać cichemu dryfowi -Są tu dwie warstwy egzekwowania: +Istnieją dwie warstwy egzekwowania: -1. **egzekwowanie rejestracji w runtime** +1. **egzekwowanie rejestracji runtime** Rejestr pluginów waliduje rejestracje podczas ładowania pluginów. Przykłady: - zduplikowane identyfikatory dostawców, zduplikowane identyfikatory dostawców mowy i błędne - rejestracje generują diagnostykę pluginu zamiast niezdefiniowanego zachowania. + duplikaty identyfikatorów dostawców, duplikaty identyfikatorów dostawców mowy i błędne + rejestracje generują diagnostykę pluginów zamiast niezdefiniowanego zachowania. 2. **testy kontraktowe** - Dołączone pluginy są przechwytywane do rejestrów kontraktowych podczas uruchamiania testów, aby - OpenClaw mogło 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 rejestracji dołączonych pluginów. + Bundlowane pluginy są przechwytywane w rejestrach kontraktów podczas uruchomień testów, aby + OpenClaw mógł jawnie potwierdzać własność. Dziś jest to używane dla + dostawców modeli, dostawców mowy, dostawców web search i własności bundlowanej rejestracji. -Praktyczny efekt jest taki, że OpenClaw z góry wie, który plugin posiada którą -powierzchnię. Dzięki temu core i kanały mogą komponować się bezproblemowo, ponieważ własność jest +Praktyczny efekt jest taki, że OpenClaw z góry wie, który plugin odpowiada za którą +powierzchnię. To pozwala rdzeniowi i kanałom płynnie się składać, bo własność jest zadeklarowana, typowana i testowalna, a nie ukryta. -### Co powinno należeć do kontraktu +### Co należy do kontraktu Dobre kontrakty pluginów są: - typowane - małe -- specyficzne dla capability -- należące do core +- specyficzne dla możliwości +- należące do rdzenia - wielokrotnego użytku przez wiele pluginów -- możliwe do wykorzystania przez kanały/funkcje bez wiedzy o dostawcy +- używalne przez kanały/funkcje bez wiedzy o dostawcy Złe kontrakty pluginów to: -- zasady specyficzne dla dostawcy ukryte w core -- jednorazowe furtki pluginów omijające rejestr +- polityka specyficzna dla dostawcy ukryta w rdzeniu +- jednorazowe furtki ucieczki specyficzne dla pluginu, które omijają rejestr - kod kanału sięgający bezpośrednio do implementacji dostawcy -- ad hoc obiekty runtime, które nie są częścią `OpenClawPluginApi` ani +- doraźne obiekty runtime, które nie są częścią `OpenClawPluginApi` ani `api.runtime` -W razie wątpliwości podnieś poziom abstrakcji: najpierw zdefiniuj capability, a -potem pozwól pluginom się do niego podłączyć. +W razie wątpliwości podnieś poziom abstrakcji: najpierw zdefiniuj możliwość, a potem +pozwól pluginom się do niej podłączać. ## Model wykonania Natywne pluginy OpenClaw działają **w tym samym procesie** co Gateway. Nie są sandboxowane. Załadowany natywny plugin ma tę samą granicę zaufania na poziomie procesu co -kod core. +kod rdzenia. Konsekwencje: - natywny plugin może rejestrować narzędzia, handlery sieciowe, hooki i usługi -- błąd natywnego pluginu może doprowadzić do awarii albo destabilizacji gateway -- złośliwy natywny plugin jest równoważny wykonaniu dowolnego kodu wewnątrz +- błąd natywnego pluginu może spowodować awarię lub destabilizację gatewaya +- 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 dołączone +Zgodne bundle są bezpieczniejsze domyślnie, bo OpenClaw obecnie traktuje je +jako pakiety metadanych/treści. W bieżących wydaniach oznacza to głównie bundlowane Skills. -W przypadku niedołączonych pluginów używaj list dozwolonych i jawnych ścieżek instalacji/ładowania. Traktuj -pluginy workspace jako kod czasu developmentu, a nie jako domyślne ustawienia produkcyjne. +Dla pluginów niebundlowanych używaj allowlist i jawnych ścieżek instalacji/ładowania. Traktuj +pluginy workspace jako kod deweloperski, a nie produkcyjne ustawienia domyślne. -W przypadku nazw pakietów dołączonych workspace zachowuj identyfikator pluginu zakotwiczony w nazwie npm: -domyślnie `@openclaw/`, albo zatwierdzony typowany sufiks, taki jak -`-provider`, `-plugin`, `-speech`, `-sandbox` lub `-media-understanding`, gdy -pakiet celowo ujawnia węższą rolę pluginu. +Dla nazw pakietów bundlowanego workspace utrzymuj identyfikator pluginu zakotwiczony w nazwie +npm: domyślnie `@openclaw/` albo zatwierdzony typowany sufiks taki jak +`-provider`, `-plugin`, `-speech`, `-sandbox` albo `-media-understanding`, gdy +pakiet celowo wystawia węższą rolę pluginu. -Ważna uwaga dotycząca zaufania: +Ważna uwaga o zaufaniu: - `plugins.allow` ufa **identyfikatorom pluginów**, a nie pochodzeniu źródła. -- Plugin workspace z tym samym identyfikatorem co dołączony plugin celowo przesłania - dołączoną kopię, gdy taki plugin workspace jest włączony/na liście dozwolonych. -- To normalne i przydatne przy lokalnym developmentcie, testowaniu poprawek i hotfixach. +- Plugin workspace z tym samym identyfikatorem co bundlowany plugin celowo przesłania + bundlowaną kopię, gdy ten plugin workspace jest włączony/na allowliście. +- Jest to normalne i przydatne dla lokalnego rozwoju, testów łatek i hotfixów. ## Granica eksportu -OpenClaw eksportuje capabilities, a nie wygodne implementacje. +OpenClaw eksportuje możliwości, a nie wygodę implementacji. -Zachowuj publiczną rejestrację capabilities. Ogranicz eksporty helperów niebędących kontraktem: +Utrzymuj publiczną rejestrację możliwości. Ogranicz eksport pomocników niebędących kontraktem: -- subścieżki helperów specyficznych dla dołączonych pluginów -- subścieżki infrastruktury runtime, które nie są przeznaczone jako publiczne API -- wygodne helpery specyficzne dla dostawcy -- helpery konfiguracji/onboardingu będące szczegółami implementacji +- podścieżki specyficzne dla bundlowanych pluginów +- podścieżki mechaniki runtime nieprzeznaczone jako publiczne API +- pomocniki wygodne specyficzne dla dostawcy +- pomocniki setup/onboarding będące szczegółami implementacji -Niektóre subścieżki helperów dołączonych pluginów nadal pozostają w wygenerowanej mapie eksportu SDK -dla kompatybilności i utrzymania dołączonych pluginów. Obecne przykłady to +Niektóre podścieżki pomocnicze bundlowanych pluginów nadal pozostają w wygenerowanej mapie +eksportów SDK ze względu na zgodność i utrzymanie bundlowanych pluginów. Obecne przykłady obejmują `plugin-sdk/feishu`, `plugin-sdk/feishu-setup`, `plugin-sdk/zalo`, `plugin-sdk/zalo-setup` oraz kilka szczelin `plugin-sdk/matrix*`. Traktuj je jako -zastrzeżone eksporty będące szczegółami implementacji, a nie jako zalecany wzorzec SDK dla -nowych pluginów third-party. +zastrzeżone eksporty szczegółów implementacyjnych, a nie zalecany wzorzec SDK dla +nowych zewnętrznych pluginów. -## Pipeline ładowania +## Potok ładowania -Podczas uruchamiania OpenClaw wykonuje w przybliżeniu to: +Podczas uruchamiania OpenClaw wykonuje w przybliżeniu następujące kroki: -1. wykrywa korzenie kandydackich pluginów -2. odczytuje manifesty natywne lub zgodnych bundle oraz metadane pakietów +1. wykrywa kandydackie korzenie pluginów +2. odczytuje natywne albo zgodne manifesty bundle oraz metadane pakietów 3. odrzuca niebezpiecznych kandydatów 4. normalizuje konfigurację pluginów (`plugins.enabled`, `allow`, `deny`, `entries`, `slots`, `load.paths`) 5. decyduje o włączeniu dla każdego kandydata -6. ładuje włączone moduły natywne przez jiti +6. ładuje włączone natywne moduły przez jiti 7. wywołuje natywne hooki `register(api)` (lub `activate(api)` — starszy alias) i zbiera rejestracje do rejestru pluginów 8. udostępnia rejestr powierzchniom poleceń/runtime -`activate` to starszy alias dla `register` — loader rozwiązuje to, co jest obecne (`def.register ?? def.activate`) i wywołuje w tym samym miejscu. Wszystkie dołączone pluginy używają `register`; w przypadku nowych pluginów preferuj `register`. +`activate` jest starszym aliasem dla `register` — loader rozwiązuje to, co jest obecne (`def.register ?? def.activate`) i wywołuje w tym samym miejscu. Wszystkie bundlowane pluginy używają `register`; dla nowych pluginów preferuj `register`. Bramki bezpieczeństwa działają **przed** wykonaniem runtime. Kandydaci są blokowani, -gdy entry wychodzi poza korzeń pluginu, ścieżka jest zapisywalna globalnie albo -własność ścieżki wygląda podejrzanie w przypadku niedołączonych pluginów. +gdy entry wychodzi poza korzeń pluginu, ścieżka jest zapisywalna dla wszystkich albo +własność ścieżki wygląda podejrzanie w przypadku pluginów niebundlowanych. ### Zachowanie manifest-first -Manifest jest źródłem prawdy dla control plane. OpenClaw używa go do: +Manifest jest źródłem prawdy warstwy control-plane. OpenClaw używa go do: - identyfikacji pluginu -- wykrywania zadeklarowanych kanałów/Skills/schematu konfiguracji lub capabilities bundle +- wykrywania zadeklarowanych kanałów/Skills/schematu konfiguracji lub możliwości bundle - walidacji `plugins.entries..config` -- rozszerzania etykiet/placeholderów Control UI -- pokazywania metadanych instalacji/katalogu +- rozszerzania etykiet/placeholderów w Control UI +- wyświetlania metadanych instalacji/katalogu -Dla natywnych pluginów moduł runtime jest częścią data plane. Rejestruje -rzeczywiste zachowanie, takie jak hooki, narzędzia, polecenia czy przepływy dostawców. +W przypadku natywnych pluginów moduł runtime jest częścią data-plane. Rejestruje +rzeczywiste zachowania, takie jak hooki, narzędzia, polecenia albo przepływy dostawcy. -### Co cache’uje loader +### Co loader przechowuje w cache -OpenClaw utrzymuje krótkie cache w procesie dla: +OpenClaw utrzymuje krótkie cache w pamięci procesu dla: - wyników wykrywania - danych rejestru manifestów - załadowanych rejestrów pluginów -Te cache zmniejszają skokowy koszt uruchamiania i powtarzanych poleceń. Można bezpiecznie -myśleć o nich jako o krótkotrwałych cache wydajnościowych, a nie o trwałym przechowywaniu. +Te cache zmniejszają koszt gwałtownego uruchamiania i powtarzanych poleceń. Są bezpieczne +do traktowania jako krótkotrwałe cache wydajnościowe, a nie trwałe przechowywanie. -Uwaga wydajnościowa: +Uwaga o wydajności: -- Ustaw `OPENCLAW_DISABLE_PLUGIN_DISCOVERY_CACHE=1` lub +- Ustaw `OPENCLAW_DISABLE_PLUGIN_DISCOVERY_CACHE=1` albo `OPENCLAW_DISABLE_PLUGIN_MANIFEST_CACHE=1`, aby wyłączyć te cache. -- Dostrajaj okna cache przez `OPENCLAW_PLUGIN_DISCOVERY_CACHE_MS` i +- Dostosuj okna cache za pomocą `OPENCLAW_PLUGIN_DISCOVERY_CACHE_MS` i `OPENCLAW_PLUGIN_MANIFEST_CACHE_MS`. ## Model rejestru -Załadowane pluginy nie modyfikują bezpośrednio losowych globali core. Rejestrują się do -centralnego rejestru pluginów. +Załadowane pluginy nie mutują bezpośrednio losowych globali rdzenia. Rejestrują się w +centralnym rejestrze pluginów. Rejestr śledzi: - rekordy pluginów (tożsamość, źródło, pochodzenie, status, diagnostyka) - narzędzia -- starsze hooki i hooki typowane +- starsze hooki i typowane hooki - kanały - dostawców -- handlery RPC gateway +- handlery Gateway RPC - trasy HTTP - rejestratory CLI -- usługi działające w tle +- usługi w tle - polecenia należące do pluginów -Funkcje core następnie odczytują z tego rejestru zamiast komunikować się bezpośrednio -z modułami pluginów. Dzięki temu ładowanie pozostaje jednokierunkowe: +Funkcje rdzenia następnie odczytują z tego rejestru zamiast komunikować się z modułami pluginów +bezpośrednio. Dzięki temu ładowanie pozostaje jednokierunkowe: - moduł pluginu -> rejestracja w rejestrze -- runtime core -> korzystanie z rejestru +- runtime rdzenia -> konsumpcja rejestru -To rozdzielenie ma znaczenie dla utrzymywalności. Oznacza, że większość powierzchni core potrzebuje tylko -jednego punktu integracji: „odczytaj rejestr”, a nie „twórz specjalny przypadek dla każdego modułu pluginu”. +To rozdzielenie ma znaczenie dla utrzymywalności. Oznacza, że większość powierzchni rdzenia potrzebuje +tylko jednego punktu integracji: „odczytaj rejestr”, a nie „obsłuż specjalnie każdy moduł pluginu”. -## Callbacki wiązania konwersacji +## Callbacki powiązania konwersacji Pluginy, które wiążą konwersację, mogą reagować, gdy zatwierdzenie zostanie rozstrzygnięte. -Użyj `api.onConversationBindingResolved(...)`, aby otrzymać callback po tym, jak żądanie powiązania zostanie zatwierdzone lub odrzucone: +Użyj `api.onConversationBindingResolved(...)`, aby otrzymać callback po zatwierdzeniu lub odrzuceniu +żądania powiązania: ```ts export default { @@ -580,37 +583,38 @@ export default { register(api) { api.onConversationBindingResolved(async (event) => { if (event.status === "approved") { - // A binding now exists for this plugin + conversation. + // Powiązanie istnieje teraz dla tego pluginu + konwersacji. console.log(event.binding?.conversationId); return; } - // The request was denied; clear any local pending state. + // Żądanie zostało odrzucone; wyczyść lokalny stan oczekujący. console.log(event.request.conversation.conversationId); }); }, }; ``` -Pola ładunku callbacku: +Pola payload callbacka: -- `status`: `"approved"` lub `"denied"` -- `decision`: `"allow-once"`, `"allow-always"` lub `"deny"` -- `binding`: rozwiązane powiązanie dla zatwierdzonych żądań -- `request`: podsumowanie oryginalnego żądania, wskazówka odłączenia, identyfikator nadawcy i +- `status`: `"approved"` albo `"denied"` +- `decision`: `"allow-once"`, `"allow-always"` albo `"deny"` +- `binding`: rozstrzygnięte powiązanie dla zatwierdzonych żądań +- `request`: oryginalne podsumowanie żądania, wskazówka odłączenia, identyfikator nadawcy i metadane konwersacji -Ten callback służy tylko do powiadamiania. Nie zmienia, kto może wiązać konwersację, i działa po zakończeniu obsługi zatwierdzenia przez core. +Ten callback służy wyłącznie do powiadomień. Nie zmienia tego, kto może powiązać +konwersację, i uruchamia się po zakończeniu obsługi zatwierdzenia przez rdzeń. ## Hooki runtime dostawców Pluginy dostawców mają teraz dwie warstwy: -- metadane manifestu: `providerAuthEnvVars` do taniego wyszukiwania auth dostawcy z env - przed załadowaniem runtime, `channelEnvVars` do taniego wyszukiwania env/konfiguracji kanału - przed załadowaniem runtime oraz `providerAuthChoices` do tanich etykiet onboardingu/wyboru auth - i metadanych flag CLI przed załadowaniem runtime -- hooki czasu konfiguracji: `catalog` / starsze `discovery` plus `applyConfigDefaults` +- metadane manifestu: `providerAuthEnvVars` dla taniego wyszukiwania auth dostawcy w env + przed załadowaniem runtime, `channelEnvVars` dla taniego wyszukiwania env/setup kanału + przed załadowaniem runtime oraz `providerAuthChoices` dla tanich etykiet + onboarding/auth-choice i metadanych flag CLI przed załadowaniem runtime +- hooki czasu konfiguracji: `catalog` / starsze `discovery` oraz `applyConfigDefaults` - hooki runtime: `normalizeModelId`, `normalizeTransport`, `normalizeConfig`, `applyNativeStreamingUsageCompat`, `resolveConfigApiKey`, @@ -631,85 +635,86 @@ Pluginy dostawców mają teraz dwie warstwy: `buildReplayPolicy`, `sanitizeReplayHistory`, `validateReplayTurns`, `onModelSelected` -OpenClaw nadal posiada ogólną pętlę agenta, failover, obsługę transkryptu i +OpenClaw nadal odpowiada za ogólną pętlę agenta, failover, obsługę transkryptów i politykę narzędzi. Te hooki są powierzchnią rozszerzeń dla zachowań specyficznych dla dostawcy bez -potrzeby całkowicie niestandardowego transportu wnioskowania. +potrzeby posiadania całkowicie własnego transportu wnioskowania. Używaj manifestowego `providerAuthEnvVars`, gdy dostawca ma poświadczenia oparte na env, które ogólne ścieżki auth/status/model-picker powinny widzieć bez ładowania runtime pluginu. -Używaj manifestowego `providerAuthChoices`, gdy powierzchnie CLI onboardingu/wyboru auth powinny -znać identyfikator wyboru dostawcy, etykiety grup i proste powiązanie auth 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żywaj manifestowego `providerAuthChoices`, gdy powierzchnie onboarding/auth-choice CLI +powinny znać identyfikator wyboru dostawcy, etykiety grup i proste +uwierzytelnianie jednym przełącznikiem bez ładowania runtime dostawcy. Runtime dostawcy +`envVars` zachowaj dla wskazówek skierowanych do operatora, takich jak etykiety onboardingu albo +zmienne setup dla OAuth client-id/client-secret. -Używaj manifestowego `channelEnvVars`, gdy kanał ma auth lub konfigurację opartą na env, które -ogólny fallback shell-env, kontrole konfiguracji/statusu lub prompty konfiguracji powinny widzieć +Używaj manifestowego `channelEnvVars`, gdy kanał ma auth lub setup sterowane przez env, które +ogólny fallback shell-env, kontrole config/status albo prompty setup powinny widzieć bez ładowania runtime kanału. -### Kolejność hooków i użycie +### Kolejność hooków i zastosowanie -Dla pluginów modeli/dostawców OpenClaw wywołuje hooki mniej więcej w tej kolejności. -Kolumna „Kiedy używać” jest szybką wskazówką decyzyjną. +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 posiada katalog albo domyślne `baseUrl` | -| 2 | `applyConfigDefaults` | Stosuje 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 | -| -- | _(wbudowane wyszukiwanie modelu)_ | OpenClaw najpierw próbuje zwykłej ścieżki rejestru/katalogu | _(to nie jest hook pluginu)_ | -| 3 | `normalizeModelId` | Normalizuje starsze lub preview aliasy identyfikatorów modeli przed wyszukaniem | Dostawca posiada czyszczenie aliasów przed rozwiązaniem modelu kanonicznego | -| 4 | `normalizeTransport` | Normalizuje `api` / `baseUrl` rodziny dostawców przed ogólnym składaniem modelu | Dostawca posiada czyszczenie transportu dla niestandardowych identyfikatorów dostawców w tej samej rodzinie transportu | -| 5 | `normalizeConfig` | Normalizuje `models.providers.` przed rozwiązaniem runtime/dostawcy | Dostawca potrzebuje czyszczenia konfiguracji, które powinno znajdować się przy pluginie; dołączone helpery rodziny Google dodatkowo wspierają obsługiwane wpisy konfiguracji Google | -| 6 | `applyNativeStreamingUsageCompat` | Stosuje przepisywania kompatybilnoś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 auth markerów env dla dostawców konfiguracji przed ładowaniem auth runtime | Dostawca ma własne rozwiązywanie kluczy API markerów env; `amazon-bedrock` ma tu także wbudowany resolver markerów env AWS | -| 8 | `resolveSyntheticAuth` | Ujawnia lokalne/self-hosted lub wspierane konfiguracją auth bez utrwalania jawnego tekstu | Dostawca może działać z syntetycznym/lokalnym markerem poświadczenia | -| 9 | `resolveExternalAuthProfiles` | Nakłada należące do dostawcy profile zewnętrznego auth; domyślna `persistence` to `runtime-only` dla poświadczeń należących do CLI/aplikacji | Dostawca ponownie wykorzystuje poświadczenia zewnętrznego auth bez utrwalania skopiowanych refresh tokenów | -| 10 | `shouldDeferSyntheticProfileAuth` | Obniża priorytet zapisanych syntetycznych placeholderów profili względem auth wspieranego przez env/konfigurację | Dostawca przechowuje syntetyczne placeholdery profili, które nie powinny wygrywać priorytetu | -| 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 upstream | -| 12 | `prepareDynamicModel` | Asynchroniczny warm-up, po którym `resolveDynamicModel` uruchamia się ponownie | Dostawca potrzebuje metadanych z sieci przed rozwiązaniem nieznanych identyfikatorów | -| 13 | `normalizeResolvedModel` | Końcowe przepisanie przed użyciem rozwiązanego modelu przez embedded runner | Dostawca potrzebuje przepisania transportu, ale nadal używa transportu core | -| 14 | `contributeResolvedModelCompat` | Dodaje flagi kompatybilności dla modeli dostawcy ukrytych za innym zgodnym transportem | Dostawca rozpoznaje własne modele na transportach proxy bez przejmowania roli dostawcy | -| 15 | `capabilities` | Należące do dostawcy metadane transkryptu/narzędzi używane przez współdzieloną logikę core | Dostawca potrzebuje niuansów transkryptu/rodziny dostawcy | -| 16 | `normalizeToolSchemas` | Normalizuje schematy narzędzi, zanim zobaczy je embedded runner | Dostawca potrzebuje czyszczenia schematów rodziny transportu | -| 17 | `inspectToolSchemas` | Ujawnia diagnostykę schematów należącą do dostawcy po normalizacji | Dostawca chce ostrzeżenia o słowach kluczowych bez uczenia core reguł specyficznych dla dostawcy | -| 18 | `resolveReasoningOutputMode` | Wybiera natywny lub tagowany kontrakt wyniku reasoning | Dostawca potrzebuje tagowanego reasoning/final output 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 per dostawca | -| 20 | `createStreamFn` | Całkowicie zastępuje zwykłą ścieżkę streamu niestandardowym transportem | Dostawca potrzebuje niestandardowego protokołu sieciowego, 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/modelu bez niestandardowego transportu | -| 22 | `resolveTransportTurnState` | Dołącza natywne nagłówki lub metadane transportu per tura | Dostawca chce, aby ogólne transporty wysyłały natywną tożsamość tury dostawcy | -| 23 | `resolveWebSocketSessionPolicy` | Dołącza natywne nagłówki WebSocket lub politykę cooldown sesji | Dostawca chce, aby ogólne transporty WS dostrajały nagłówki sesji albo politykę fallback | -| 24 | `formatApiKey` | Formater profilu auth: zapisany profil staje się ciągiem `apiKey` w runtime | Dostawca przechowuje dodatkowe metadane auth i potrzebuje niestandardowego kształtu tokenu runtime | -| 25 | `refreshOAuth` | Nadpisanie odświeżania OAuth dla niestandardowych endpointów odświeżania lub polityki błędów odświeżania | Dostawca nie pasuje do współdzielonych refresherów `pi-ai` | -| 26 | `buildAuthDoctorHint` | Wskazówka naprawcza dołączana po niepowodzeniu odświeżenia OAuth | Dostawca potrzebuje własnych wskazówek naprawy auth po błędzie odświeżania | -| 27 | `matchesContextOverflowError` | Matcher przepełnienia okna kontekstu należący do dostawcy | Dostawca ma surowe błędy przepełnienia, których ogólne heurystyki nie wykryją | -| 28 | `classifyFailoverReason` | Klasyfikacja przyczyn failover należąca do dostawcy | Dostawca może mapować surowe błędy API/transportu na rate-limit/przeciążenie/itp. | -| 29 | `isCacheTtlEligible` | Polityka prompt-cache dla dostawców proxy/backhaul | Dostawca potrzebuje bramkowania TTL cache specyficznego dla proxy | -| 30 | `buildMissingAuthMessage` | Zamiennik ogólnego komunikatu odzyskiwania przy braku auth | Dostawca potrzebuje własnej wskazówki odzyskiwania po braku auth | -| 31 | `suppressBuiltInModel` | Tłumienie nieaktualnych modeli upstream plus opcjonalna wskazówka błędu dla użytkownika | Dostawca potrzebuje ukryć nieaktualne wiersze upstream albo zastąpić je wskazówką dostawcy | -| 32 | `augmentModelCatalog` | Syntetyczne/końcowe wiersze katalogu dołączane po wykrywaniu | Dostawca potrzebuje syntetycznych wierszy forward-compat w `models list` i pickerach | -| 33 | `isBinaryThinking` | Przełącznik reasoning włącz/wyłącz dla dostawców z binarnym thinking | Dostawca udostępnia tylko binarne thinking włącz/wyłącz | -| 34 | `supportsXHighThinking` | Obsługa reasoning `xhigh` dla wybranych modeli | Dostawca chce `xhigh` tylko dla podzbioru modeli | -| 35 | `resolveDefaultThinkingLevel` | Domyślny poziom `/think` dla określonej rodziny modeli | Dostawca posiada domyślną politykę `/think` dla rodziny modeli | -| 36 | `isModernModelRef` | Matcher nowoczesnych modeli dla filtrów live profile i wyboru smoke | Dostawca posiada dopasowanie 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` | Rozwiązuje poświadczenia użycia/rozliczeń dla `/usage` i powiązanych powierzchni statusu | Dostawca potrzebuje niestandardowego parsowania tokenu użycia/kwoty lub innego poświadczenia użycia | -| 39 | `fetchUsageSnapshot` | Pobiera i normalizuje snapshoty użycia/kwoty specyficzne dla dostawcy po rozwiązaniu auth | Dostawca potrzebuje własnego endpointu użycia lub parsera ładunku | -| 40 | `createEmbeddingProvider` | Buduje należący do dostawcy adapter embeddingów dla memory/search | Zachowanie embeddingów pamięci powinno należeć do pluginu dostawcy | -| 41 | `buildReplayPolicy` | Zwraca politykę replay kontrolującą obsługę transkryptu dla dostawcy | Dostawca potrzebuje niestandardowej polityki transkryptu (na przykład usuwania bloków thinking) | -| 42 | `sanitizeReplayHistory` | Przepisuje historię replay po ogólnym czyszczeniu transkryptu | Dostawca potrzebuje przepisania replay specyficznego dla dostawcy poza współdzielonymi helperami kompaktowania | -| 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 efekty uboczne po wyborze modelu należące do dostawcy | Dostawca potrzebuje telemetrii albo własnego stanu, gdy model staje się aktywny | +| # | Hook | Co robi | Kiedy używać | +| --- | --------------------------------- | ------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | +| 1 | `catalog` | Publikuje konfigurację dostawcy do `models.providers` podczas generowania `models.json` | Dostawca posiada katalog albo wartości domyślne `baseUrl` | +| 2 | `applyConfigDefaults` | Stosuje globalne wartości domyślne konfiguracji należące do dostawcy podczas materializacji konfiguracji | Wartości domyślne zależą od trybu auth, env albo semantyki rodziny modeli dostawcy | +| -- | _(wbudowane wyszukiwanie modeli)_ | OpenClaw najpierw próbuje zwykłej ścieżki rejestru/katalogu | _(to nie jest hook pluginu)_ | +| 3 | `normalizeModelId` | Normalizuje starsze albo preview aliasy `model-id` przed wyszukaniem | Dostawca posiada czyszczenie aliasów przed kanonicznym rozstrzyganiem modelu | +| 4 | `normalizeTransport` | Normalizuje rodzinę dostawców `api` / `baseUrl` przed ogólnym składaniem modelu | Dostawca posiada czyszczenie transportu dla niestandardowych identyfikatorów dostawców w tej samej rodzinie transportu | +| 5 | `normalizeConfig` | Normalizuje `models.providers.` przed rozstrzygnięciem runtime/dostawcy | Dostawca potrzebuje czyszczenia konfiguracji, które powinno żyć wraz z pluginem; bundlowane pomocniki rodziny Google dodatkowo wspierają wspierane wpisy konfiguracji Google | +| 6 | `applyNativeStreamingUsageCompat` | Stosuje przepisywanie zgodności z użyciem natywnego streamingu do dostawców konfiguracji | Dostawca potrzebuje poprawek metadanych użycia natywnego streamingu zależnych od endpointu | +| 7 | `resolveConfigApiKey` | Rozwiązuje auth typu env-marker dla dostawców konfiguracji przed załadowaniem runtime auth | Dostawca ma własne rozwiązywanie klucza API env-marker; `amazon-bedrock` ma tu również wbudowany resolver env-marker AWS | +| 8 | `resolveSyntheticAuth` | Ujawnia lokalne/self-hosted lub oparte na konfiguracji auth bez utrwalania jawnego tekstu | Dostawca może działać z syntetycznym/lokalnym markerem poświadczeń | +| 9 | `resolveExternalAuthProfiles` | Nakłada zewnętrzne profile auth należące do dostawcy; domyślne `persistence` to `runtime-only` dla poświadczeń należących do CLI/aplikacji | Dostawca ponownie używa zewnętrznych poświadczeń auth bez utrwalania skopiowanych tokenów odświeżania | +| 10 | `shouldDeferSyntheticProfileAuth` | Obniża priorytet przechowywanych placeholderów syntetycznych profili względem auth opartego na env/config | Dostawca przechowuje syntetyczne placeholdery profili, które nie powinny mieć pierwszeństwa | +| 11 | `resolveDynamicModel` | Synchroniczny fallback dla identyfikatorów modeli należących do dostawcy, których nie ma jeszcze w lokalnym rejestrze | Dostawca akceptuje dowolne upstreamowe identyfikatory modeli | +| 12 | `prepareDynamicModel` | Asynchroniczne rozgrzanie, po czym `resolveDynamicModel` uruchamia się ponownie | Dostawca potrzebuje metadanych sieciowych przed rozstrzygnięciem nieznanych identyfikatorów | +| 13 | `normalizeResolvedModel` | Końcowe przepisanie przed użyciem rozstrzygniętego modelu przez embedded runner | Dostawca potrzebuje przepisań transportu, ale nadal używa transportu rdzenia | +| 14 | `contributeResolvedModelCompat` | Dodaje flagi zgodności dla modeli dostawcy za innym zgodnym transportem | Dostawca rozpoznaje własne modele na transportach proxy bez przejmowania roli dostawcy | +| 15 | `capabilities` | Metadane transkryptów/narzędzi należące do dostawcy używane przez współdzieloną logikę rdzenia | Dostawca potrzebuje specyficznych zachowań transkryptu/rodziny dostawcy | +| 16 | `normalizeToolSchemas` | Normalizuje schematy narzędzi przed przekazaniem ich do embedded runnera | Dostawca potrzebuje czyszczenia schematu rodziny transportu | +| 17 | `inspectToolSchemas` | Ujawnia diagnostykę schematów należącą do dostawcy po normalizacji | Dostawca chce ostrzeżeń o słowach kluczowych bez uczenia rdzenia reguł specyficznych dla dostawcy | +| 18 | `resolveReasoningOutputMode` | Wybiera natywny albo oznaczany kontrakt wyjścia reasoning | Dostawca potrzebuje oznaczanego reasoning/końcowego wyjścia zamiast natywnych pól | +| 19 | `prepareExtraParams` | Normalizacja parametrów żądania przed ogólnymi wrapperami opcji streamu | Dostawca potrzebuje domyślnych parametrów żądania albo czyszczenia parametrów per dostawca | +| 20 | `createStreamFn` | W pełni zastępuje zwykłą ścieżkę streamu niestandardowym transportem | Dostawca potrzebuje niestandardowego protokołu na przewodzie, a nie tylko wrappera | +| 21 | `wrapStreamFn` | Wrapper streamu po zastosowaniu ogólnych wrapperów | Dostawca potrzebuje wrapperów nagłówków/treści/zgodności modelu bez niestandardowego transportu | +| 22 | `resolveTransportTurnState` | Dołącza natywne nagłówki lub metadane transportu per turn | Dostawca chce, aby ogólne transporty wysyłały natywną tożsamość tury dostawcy | +| 23 | `resolveWebSocketSessionPolicy` | Dołącza natywne nagłówki WebSocket lub politykę cooldown sesji | Dostawca chce, aby ogólne transporty WS dostrajały nagłówki sesji albo politykę fallback | +| 24 | `formatApiKey` | Formater profilu auth: zapisany profil staje się runtime stringiem `apiKey` | Dostawca przechowuje dodatkowe metadane auth i potrzebuje niestandardowego kształtu tokena runtime | +| 25 | `refreshOAuth` | Nadpisanie odświeżania OAuth dla niestandardowych endpointów odświeżania albo polityki błędów odświeżania | Dostawca nie pasuje do współdzielonych mechanizmów odświeżania `pi-ai` | +| 26 | `buildAuthDoctorHint` | Wskazówka naprawcza dołączana po niepowodzeniu odświeżania OAuth | Dostawca potrzebuje własnych wskazówek naprawy auth po błędzie odświeżenia | +| 27 | `matchesContextOverflowError` | Dopasowywanie przepełnienia okna kontekstu należące do dostawcy | Dostawca ma surowe błędy przepełnienia, których ogólne heurystyki nie wykryją | +| 28 | `classifyFailoverReason` | Klasyfikacja przyczyny failover należąca do dostawcy | Dostawca może mapować surowe błędy API/transportu na rate-limit/przeciążenie itd. | +| 29 | `isCacheTtlEligible` | Polityka prompt-cache dla dostawców proxy/backhaul | Dostawca potrzebuje bramkowania TTL cache specyficznego dla proxy | +| 30 | `buildMissingAuthMessage` | Zastąpienie ogólnego komunikatu odzyskiwania przy braku auth | Dostawca potrzebuje komunikatu odzyskiwania przy braku auth specyficznego dla dostawcy | +| 31 | `suppressBuiltInModel` | Tłumienie nieaktualnych modeli upstream plus opcjonalna wskazówka błędu dla użytkownika | Dostawca musi ukryć nieaktualne wiersze upstream albo zastąpić je wskazówką dostawcy | +| 32 | `augmentModelCatalog` | Syntetyczne/końcowe wiersze katalogu dołączane po wykryciu | Dostawca potrzebuje syntetycznych wierszy zgodności z przyszłością w `models list` i pickerach | +| 33 | `isBinaryThinking` | Przełącznik on/off reasoning dla dostawców binarnego thinking | Dostawca udostępnia tylko binarne włącz/wyłącz thinking | +| 34 | `supportsXHighThinking` | Wsparcie reasoning `xhigh` dla wybranych modeli | Dostawca chce `xhigh` tylko dla podzbioru modeli | +| 35 | `resolveDefaultThinkingLevel` | Domyślny poziom `/think` dla konkretnej rodziny modeli | Dostawca posiada domyślną politykę `/think` dla rodziny modeli | +| 36 | `isModernModelRef` | Dopasowywanie nowoczesnych modeli dla filtrów live profili i wyboru smoke | Dostawca posiada preferowane dopasowywanie modeli live/smoke | +| 37 | `prepareRuntimeAuth` | Wymienia skonfigurowane poświadczenie na właściwy token/klucz runtime tuż przed wnioskowaniem | Dostawca potrzebuje wymiany tokena lub krótkotrwałego poświadczenia żądania | +| 38 | `resolveUsageAuth` | Rozwiązuje poświadczenia użycia/rozliczeń dla `/usage` i pokrewnych powierzchni statusu | Dostawca potrzebuje niestandardowego parsowania tokena użycia/kwoty albo innych poświadczeń użycia | +| 39 | `fetchUsageSnapshot` | Pobiera i normalizuje snapshoty użycia/kwot specyficzne dla dostawcy po rozstrzygnięciu auth | Dostawca potrzebuje endpointu użycia specyficznego dla dostawcy albo parsera payloadu | +| 40 | `createEmbeddingProvider` | Buduje adapter embeddingów należący do dostawcy dla pamięci/wyszukiwania | Zachowanie embeddingów pamięci należy do pluginu dostawcy | +| 41 | `buildReplayPolicy` | Zwraca politykę replay kontrolującą obsługę transkryptu dla dostawcy | Dostawca potrzebuje niestandardowej polityki transkryptu (na przykład usuwania bloków thinking) | +| 42 | `sanitizeReplayHistory` | Przepisuje historię replay po ogólnym czyszczeniu transkryptu | Dostawca potrzebuje przepisań replay specyficznych dla dostawcy wykraczających poza współdzielone pomocniki kompaktowania | +| 43 | `validateReplayTurns` | Końcowa walidacja albo przekształcenie tur replay przed embedded runnerem | Transport dostawcy potrzebuje bardziej rygorystycznej walidacji tur po ogólnej sanityzacji | +| 44 | `onModelSelected` | Uruchamia skutki uboczne po wyborze modelu należące do dostawcy | Dostawca potrzebuje telemetrii albo stanu należącego do dostawcy, gdy model staje się aktywny | `normalizeModelId`, `normalizeTransport` i `normalizeConfig` najpierw sprawdzają -dopasowany plugin dostawcy, a następnie przechodzą przez inne pluginy dostawców zdolne do hooków, -dopóki któryś rzeczywiście nie zmieni identyfikatora modelu albo transportu/konfiguracji. Dzięki temu -shim aliasów/kompatybilności dostawców nadal działają bez wymagania, aby wywołujący wiedział, który -dołączony plugin posiada dane przepisanie. Jeśli żaden hook dostawcy nie przepisze obsługiwanego -wpisu konfiguracji rodziny Google, dołączony normalizator konfiguracji Google nadal zastosuje -to czyszczenie kompatybilności. +dopasowany plugin dostawcy, a następnie przechodzą do innych pluginów dostawców zdolnych do obsługi hooków, +dopóki któryś faktycznie nie zmieni identyfikatora modelu albo transportu/konfiguracji. Dzięki temu +shimy aliasów/zgodności dostawców działają bez konieczności wiedzy po stronie wywołującego, który +bundlowany plugin jest właścicielem przepisywania. Jeśli żaden hook dostawcy nie przepisze wspieranego +wpisu konfiguracji rodziny Google, bundlowany normalizator konfiguracji Google nadal stosuje +to czyszczenie zgodności. -Jeśli dostawca potrzebuje w pełni niestandardowego protokołu sieciowego lub niestandardowego wykonawcy żądań, -to jest inna klasa rozszerzenia. Te hooki służą dla zachowań dostawców, które nadal działają na -zwykłej pętli wnioskowania OpenClaw. +Jeśli dostawca potrzebuje w pełni niestandardowego protokołu na przewodzie albo własnego wykonawcy żądań, +to jest to inna klasa rozszerzenia. Te hooki są przeznaczone dla zachowań dostawcy, +które nadal działają na zwykłej pętli wnioskowania OpenClaw. ### Przykład dostawcy @@ -770,111 +775,112 @@ api.registerProvider({ - Anthropic używa `resolveDynamicModel`, `capabilities`, `buildAuthDoctorHint`, `resolveUsageAuth`, `fetchUsageSnapshot`, `isCacheTtlEligible`, `resolveDefaultThinkingLevel`, `applyConfigDefaults`, `isModernModelRef` - i `wrapStreamFn`, ponieważ posiada forward-compat Claude 4.6, - wskazówki 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ę thinking Claude oraz kształtowanie strumienia specyficzne dla Anthropic dla + i `wrapStreamFn`, ponieważ obsługuje zgodność z przyszłością Claude 4.6, + wskazówki dotyczące rodziny dostawcy, wskazówki naprawy auth, integrację z endpointem użycia, + kwalifikowalność prompt-cache, domyślne ustawienia konfiguracji świadome auth, domyślną/adaptacyjną + politykę thinking Claude oraz kształtowanie streamu specyficzne dla Anthropic dla nagłówków beta, `/fast` / `serviceTier` i `context1m`. -- Helpery strumienia specyficzne dla Claude w Anthropic pozostają na razie we własnej - publicznej szczelinie `api.ts` / `contract-api.ts` dołączonego pluginu. Ta powierzchnia pakietu - eksportuje `wrapAnthropicProviderStream`, `resolveAnthropicBetas`, - `resolveAnthropicFastMode`, `resolveAnthropicServiceTier` oraz niższopoziomowe - buildery wrapperów Anthropic zamiast poszerzać ogólne SDK wokół reguł nagłówków beta jednego +- Pomocniki streamów specyficzne dla Claude w Anthropic pozostają na razie w + publicznej szczelinie `api.ts` / `contract-api.ts` należącej do bundlowanego pluginu. Ta + powierzchnia pakietu eksportuje `wrapAnthropicProviderStream`, `resolveAnthropicBetas`, + `resolveAnthropicFastMode`, `resolveAnthropicServiceTier` oraz niższego poziomu + buildery wrapperów Anthropic zamiast rozszerzać ogólne SDK wokół reguł nagłówków beta jednego dostawcy. - OpenAI używa `resolveDynamicModel`, `normalizeResolvedModel` i - `capabilities`, a także `buildMissingAuthMessage`, `suppressBuiltInModel`, + `capabilities` oraz `buildMissingAuthMessage`, `suppressBuiltInModel`, `augmentModelCatalog`, `supportsXHighThinking` i `isModernModelRef`, - ponieważ posiada forward-compat GPT-5.4, bezpośrednią normalizację OpenAI + ponieważ obsługuje zgodność z przyszłością GPT-5.4, bezpośrednią normalizację OpenAI `openai-completions` -> `openai-responses`, wskazówki auth świadome Codex, - tłumienie Spark, syntetyczne wiersze list OpenAI oraz politykę GPT-5 thinking / - live-model; rodzina strumienia `openai-responses-defaults` posiada - współdzielone natywne wrappery OpenAI Responses dla nagłówków atrybucji, - `/fast`/`serviceTier`, szczegółowości tekstu, natywnego wyszukiwania webowego Codex, - kształtowania ładunku reasoning-compat oraz zarządzania kontekstem Responses. + tłumienie Spark, syntetyczne wiersze list OpenAI oraz politykę thinking / modeli live GPT-5; + rodzina streamów `openai-responses-defaults` obsługuje współdzielone natywne wrappery OpenAI Responses dla + nagłówków atrybucji, `/fast`/`serviceTier`, gadatliwości tekstu, natywnego Codex web search, + kształtowania payload zgodności reasoning oraz zarządzania kontekstem Responses. - OpenRouter używa `catalog` oraz `resolveDynamicModel` i `prepareDynamicModel`, ponieważ dostawca jest pass-through i może ujawniać nowe - identyfikatory modeli przed aktualizacją statycznego katalogu OpenClaw; używa także + identyfikatory modeli zanim zaktualizuje się statyczny katalog OpenClaw; używa też `capabilities`, `wrapStreamFn` i `isCacheTtlEligible`, aby trzymać - nagłówki żądań specyficzne dla dostawcy, metadane routingu, poprawki reasoning i - politykę prompt-cache poza core. Jego polityka replay pochodzi z rodziny - `passthrough-gemini`, podczas gdy rodzina strumienia `openrouter-thinking` - posiada wstrzykiwanie proxy reasoning i pomijanie nieobsługiwanych modeli / `auto`. + specyficzne dla dostawcy nagłówki żądań, metadane routingu, poprawki reasoning i + politykę prompt-cache poza rdzeniem. Jego polityka replay pochodzi z rodziny + `passthrough-gemini`, podczas gdy rodzina streamów `openrouter-thinking` + obsługuje wstrzykiwanie proxy reasoning oraz pomijanie nieobsługiwanych modeli i `auto`. - GitHub Copilot używa `catalog`, `auth`, `resolveDynamicModel` i - `capabilities`, a także `prepareRuntimeAuth` i `fetchUsageSnapshot`, ponieważ - potrzebuje własnego logowania urządzenia, zachowania fallback modelu, niuansów - transkryptu Claude, wymiany tokenu GitHub -> token Copilot oraz własnego endpointu użycia. + `capabilities` oraz `prepareRuntimeAuth` i `fetchUsageSnapshot`, ponieważ + potrzebuje logowania urządzenia należącego do dostawcy, zachowania fallback modeli, + specyficznych zachowań transkryptu Claude, wymiany tokena GitHub -> token Copilot oraz + endpointu użycia należącego do dostawcy. - OpenAI Codex używa `catalog`, `resolveDynamicModel`, - `normalizeResolvedModel`, `refreshOAuth` i `augmentModelCatalog`, a także + `normalizeResolvedModel`, `refreshOAuth` i `augmentModelCatalog` oraz `prepareExtraParams`, `resolveUsageAuth` i `fetchUsageSnapshot`, ponieważ - nadal działa na transportach core OpenAI, ale posiada normalizację + nadal działa na transportach rdzeniowych OpenAI, ale obsługuje własną normalizację transportu/base URL, politykę fallback odświeżania OAuth, domyślny wybór transportu, - syntetyczne wiersze katalogu Codex i integrację endpointu użycia ChatGPT; współdzieli - tę samą rodzinę strumienia `openai-responses-defaults` co bezpośredni OpenAI. + syntetyczne wiersze katalogu Codex oraz integrację z endpointem użycia ChatGPT; współdzieli + tę samą rodzinę streamów `openai-responses-defaults` co bezpośrednie OpenAI. - Google AI Studio i Gemini CLI OAuth używają `resolveDynamicModel`, `buildReplayPolicy`, `sanitizeReplayHistory`, `resolveReasoningOutputMode`, `wrapStreamFn` i `isModernModelRef`, ponieważ - rodzina replay `google-gemini` posiada fallback forward-compat Gemini 3.1, - natywną walidację replay Gemini, sanityzację bootstrap replay, tagowany - tryb reasoning-output i dopasowanie nowoczesnych modeli, podczas gdy - rodzina strumienia `google-thinking` posiada normalizację ładunku thinking Gemini; - Gemini CLI OAuth używa także `formatApiKey`, `resolveUsageAuth` i - `fetchUsageSnapshot` do formatowania tokenów, parsowania tokenów i - podłączenia endpointu kwot. + rodzina replay `google-gemini` obsługuje fallback zgodności z przyszłością Gemini 3.1, + natywną walidację replay Gemini, sanityzację replay bootstrap, + tryb oznaczanego wyjścia reasoning oraz dopasowanie nowoczesnych modeli, podczas gdy + rodzina streamów `google-thinking` obsługuje normalizację payload thinking Gemini; + Gemini CLI OAuth używa też `formatApiKey`, `resolveUsageAuth` i + `fetchUsageSnapshot` do formatowania tokena, parsowania tokena i + podłączania endpointu quota. - Anthropic Vertex używa `buildReplayPolicy` przez rodzinę replay - `anthropic-by-model`, dzięki czemu czyszczenie replay specyficzne dla Claude pozostaje - ograniczone do identyfikatorów Claude zamiast obejmować cały transport `anthropic-messages`. + `anthropic-by-model`, aby czyszczenie replay specyficzne dla Claude pozostało + ograniczone do identyfikatorów Claude zamiast każdego transportu `anthropic-messages`. - Amazon Bedrock używa `buildReplayPolicy`, `matchesContextOverflowError`, - `classifyFailoverReason` i `resolveDefaultThinkingLevel`, ponieważ posiada + `classifyFailoverReason` i `resolveDefaultThinkingLevel`, ponieważ obsługuje klasyfikację błędów throttle/not-ready/context-overflow specyficzną dla Bedrock dla ruchu Anthropic-on-Bedrock; jego polityka replay nadal współdzieli tę samą - ochronę `anthropic-by-model` ograniczoną do Claude. + osłonę `anthropic-by-model` tylko dla Claude. - OpenRouter, Kilocode, Opencode i Opencode Go używają `buildReplayPolicy` - przez rodzinę replay `passthrough-gemini`, ponieważ proxy’ują modele Gemini + przez rodzinę replay `passthrough-gemini`, ponieważ pośredniczą modele Gemini przez transporty zgodne z OpenAI i potrzebują sanityzacji - thought-signature Gemini bez natywnej walidacji replay Gemini lub przepisania bootstrapu. -- MiniMax używa `buildReplayPolicy` przez rodzinę - `hybrid-anthropic-openai`, ponieważ jeden dostawca posiada zarówno semantykę - wiadomości Anthropic, jak i zgodną z OpenAI; zachowuje usuwanie bloków thinking - ograniczone do Claude po stronie Anthropic, jednocześnie nadpisując tryb wyniku reasoning z powrotem na natywny, - a rodzina strumienia `minimax-fast-mode` posiada przepisywanie modeli fast-mode na współdzielonej ścieżce strumienia. -- Moonshot używa `catalog` oraz `wrapStreamFn`, ponieważ nadal używa - współdzielonego transportu OpenAI, ale potrzebuje normalizacji ładunku thinking należącej do dostawcy; rodzina - strumienia `moonshot-thinking` mapuje konfigurację oraz stan `/think` na - natywny binarny ładunek thinking. + thought-signature Gemini bez natywnej walidacji replay Gemini ani + przepisań bootstrap. +- MiniMax używa `buildReplayPolicy` przez rodzinę replay + `hybrid-anthropic-openai`, ponieważ jeden dostawca obsługuje zarówno semantykę + Anthropic-message, jak i zgodną z OpenAI; zachowuje usuwanie bloków thinking + tylko dla Claude po stronie Anthropic, a jednocześnie nadpisuje tryb wyjścia reasoning z powrotem na natywny, zaś rodzina streamów `minimax-fast-mode` obsługuje + przepisywania modeli trybu fast na współdzielonej ścieżce streamu. +- Moonshot używa `catalog` oraz `wrapStreamFn`, ponieważ nadal używa współdzielonego + transportu OpenAI, ale potrzebuje normalizacji payload thinking należącej do dostawcy; rodzina streamów + `moonshot-thinking` mapuje konfigurację oraz stan `/think` na swój + natywny binarny payload thinking. - Kilocode używa `catalog`, `capabilities`, `wrapStreamFn` i `isCacheTtlEligible`, ponieważ potrzebuje nagłówków żądań należących do dostawcy, - normalizacji ładunku reasoning, wskazówek transkryptu Gemini i bramkowania - Anthropic cache-TTL; rodzina strumienia `kilocode-thinking` utrzymuje wstrzykiwanie Kilo thinking - na współdzielonej ścieżce strumienia proxy, pomijając `kilo/auto` i - inne identyfikatory modeli proxy, które nie obsługują jawnych ładunków reasoning. + normalizacji payload reasoning, wskazówek dla transkryptu Gemini oraz bramkowania + cache-TTL Anthropic; rodzina streamów `kilocode-thinking` utrzymuje wstrzykiwanie + Kilo thinking na współdzielonej ścieżce streamu proxy, jednocześnie pomijając `kilo/auto` i + inne identyfikatory modeli proxy, które nie obsługują jawnych payloadów reasoning. - Z.AI używa `resolveDynamicModel`, `prepareExtraParams`, `wrapStreamFn`, `isCacheTtlEligible`, `isBinaryThinking`, `isModernModelRef`, - `resolveUsageAuth` i `fetchUsageSnapshot`, ponieważ posiada fallback GLM-5, - domyślne `tool_stream`, UX binarnego thinking, dopasowanie nowoczesnych modeli oraz - zarówno auth użycia, jak i pobieranie kwot; rodzina strumienia `tool-stream-default-on` utrzymuje - domyślnie włączony wrapper `tool_stream` poza ręcznie pisanym klejem per dostawca. + `resolveUsageAuth` i `fetchUsageSnapshot`, ponieważ obsługuje fallback GLM-5, + domyślne `tool_stream`, UX binarnego thinking, dopasowywanie nowoczesnych modeli oraz zarówno + usage auth, jak i pobieranie quota; rodzina streamów `tool-stream-default-on` utrzymuje + wrapper `tool_stream` włączony domyślnie poza ręcznie pisanym glue per dostawca. - xAI używa `normalizeResolvedModel`, `normalizeTransport`, `contributeResolvedModelCompat`, `prepareExtraParams`, `wrapStreamFn`, `resolveSyntheticAuth`, `resolveDynamicModel` i `isModernModelRef`, - ponieważ posiada normalizację natywnego transportu xAI Responses, przepisywanie aliasów - Grok fast-mode, domyślne `tool_stream`, czyszczenie strict-tool / reasoning-payload, - ponowne użycie fallback auth dla narzędzi należących do pluginu, rozwiązywanie modeli Grok - z forward-compat oraz poprawki kompatybilnoś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ą tylko `capabilities`, aby utrzymać - niuanse transkryptu/narzędzi poza core. -- Dołączone dostawcy tylko katalogowi, tacy jak `byteplus`, `cloudflare-ai-gateway`, + ponieważ obsługuje natywną normalizację transportu xAI Responses, przepisywanie aliasów + trybu fast Grok, domyślne `tool_stream`, czyszczenie strict-tool / reasoning-payload, + ponowne użycie fallback auth dla narzędzi należących do pluginu, rozstrzyganie modeli Grok zgodne z przyszłością + oraz poprawki zgodności należące do dostawcy, takie jak profil schematu narzędzi xAI, + nieobsługiwane słowa kluczowe schematu, natywne `web_search` i dekodowanie argumentów wywołań narzędzi z encji HTML. +- Mistral, OpenCode Zen i OpenCode Go używają tylko `capabilities`, aby trzymać + specyficzne zachowania transkryptów/narzędzi poza rdzeniem. +- Bundlowani dostawcy tylko katalogowi, tacy jak `byteplus`, `cloudflare-ai-gateway`, `huggingface`, `kimi-coding`, `nvidia`, `qianfan`, `synthetic`, `together`, `venice`, `vercel-ai-gateway` i `volcengine`, używają tylko `catalog`. -- Qwen używa `catalog` dla swojego dostawcy tekstowego oraz współdzielonych rejestracji +- Qwen używa `catalog` dla swojego dostawcy tekstu oraz współdzielonych rejestracji media-understanding i video-generation 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 samo wnioskowanie nadal działa przez współdzielone transporty. +- 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. ## Pomocniki runtime -Pluginy mogą uzyskać dostęp do wybranych helperów core przez `api.runtime`. Dla TTS: +Pluginy mogą uzyskać dostęp do wybranych pomocników rdzenia przez `api.runtime`. Dla TTS: ```ts const clip = await api.runtime.tts.textToSpeech({ @@ -895,14 +901,14 @@ const voices = await api.runtime.tts.listVoices({ Uwagi: -- `textToSpeech` zwraca zwykły ładunek wyjściowy TTS core dla powierzchni typu plik/voice-note. -- Używa konfiguracji core `messages.tts` i wyboru dostawcy. -- Zwraca bufor audio PCM + częstotliwość próbkowania. Pluginy muszą wykonać resampling/kodowanie dla dostawców. -- `listVoices` jest opcjonalne dla każdego dostawcy. Używaj go do pickerów głosów należących do dostawcy lub przepływów konfiguracji. +- `textToSpeech` zwraca zwykły payload wyjściowy TTS rdzenia dla powierzchni plików/notatek głosowych. +- Używa konfiguracji rdzeniowej `messages.tts` oraz wyboru dostawcy. +- Zwraca bufor audio PCM + częstotliwość próbkowania. Pluginy muszą przeskalować/zakodować je dla dostawców. +- `listVoices` jest opcjonalne per dostawca. Używaj go w pickerach głosów lub przepływach setup należących do dostawcy. - Listy głosów mogą zawierać bogatsze metadane, takie jak locale, płeć i tagi osobowości dla pickerów świadomych dostawcy. - OpenAI i ElevenLabs obsługują dziś telefonię. Microsoft nie. -Pluginy mogą także rejestrować dostawców mowy przez `api.registerSpeechProvider(...)`. +Pluginy mogą też rejestrować dostawców mowy przez `api.registerSpeechProvider(...)`. ```ts api.registerSpeechProvider({ @@ -922,14 +928,14 @@ api.registerSpeechProvider({ Uwagi: -- Zachowaj politykę TTS, fallback i dostarczanie odpowiedzi w core. -- Używaj dostawców mowy dla zachowań syntezy należących do dostawcy. -- Starszy input Microsoft `edge` jest normalizowany do identyfikatora dostawcy `microsoft`. +- Zachowaj politykę TTS, fallback i dostarczanie odpowiedzi w rdzeniu. +- Używaj dostawców mowy do zachowań syntezy należących do dostawcy. +- Starsze wejście Microsoft `edge` jest normalizowane do identyfikatora dostawcy `microsoft`. - Preferowany model własności jest zorientowany na firmę: jeden plugin dostawcy może posiadać - tekst, mowę, obraz i przyszłych dostawców mediów, gdy OpenClaw doda te - kontrakty capability. + dostawców tekstu, mowy, obrazów i przyszłych mediów, gdy OpenClaw dodaje te + kontrakty możliwości. -W przypadku rozumienia obrazu/dźwięku/wideo pluginy rejestrują jednego typowanego +W przypadku rozumienia obrazów/audio/wideo pluginy rejestrują jednego typowanego dostawcę media-understanding zamiast ogólnego worka klucz/wartość: ```ts @@ -944,16 +950,16 @@ api.registerMediaUnderstandingProvider({ Uwagi: -- Zachowaj orkiestrację, fallback, konfigurację i podłączenie kanałów w core. +- Zachowaj orkiestrację, fallback, konfigurację i integrację kanałów w rdzeniu. - Zachowaj zachowanie dostawcy w pluginie dostawcy. - Rozszerzanie addytywne powinno pozostać typowane: nowe opcjonalne metody, nowe opcjonalne - pola wyników, nowe opcjonalne capabilities. -- Generowanie wideo już stosuje ten sam wzorzec: - - core posiada kontrakt capability i helper runtime + pola wyniku, nowe opcjonalne możliwości. +- Generowanie wideo już podąża za tym samym wzorcem: + - rdzeń posiada kontrakt możliwości i pomocnik runtime - pluginy dostawców rejestrują `api.registerVideoGenerationProvider(...)` - pluginy funkcji/kanałów korzystają z `api.runtime.videoGeneration.*` -W przypadku helperów runtime media-understanding pluginy mogą wywoływać: +Dla pomocników runtime media-understanding pluginy mogą wywoływać: ```ts const image = await api.runtime.mediaUnderstanding.describeImageFile({ @@ -975,7 +981,7 @@ albo starszego aliasu STT: const { text } = await api.runtime.mediaUnderstanding.transcribeAudioFile({ filePath: "/tmp/inbound-audio.ogg", cfg: api.config, - // Optional when MIME cannot be inferred reliably: + // Opcjonalne, gdy nie można wiarygodnie wywnioskować MIME: mime: "audio/ogg", }); ``` @@ -983,12 +989,12 @@ const { text } = await api.runtime.mediaUnderstanding.transcribeAudioFile({ Uwagi: - `api.runtime.mediaUnderstanding.*` to preferowana współdzielona powierzchnia dla - rozumienia obrazu/dźwięku/wideo. -- Używa konfiguracji audio media-understanding core (`tools.media.audio`) i kolejności fallback dostawców. -- Zwraca `{ text: undefined }`, gdy nie zostanie utworzony wynik transkrypcji (na przykład przy pominiętym/nieobsługiwanym wejściu). -- `api.runtime.stt.transcribeAudioFile(...)` pozostaje aliasem kompatybilności. + rozumienia obrazów/audio/wideo. +- Używa konfiguracji audio media-understanding rdzenia (`tools.media.audio`) oraz kolejności fallback dostawców. +- Zwraca `{ text: undefined }`, gdy nie został wygenerowany wynik transkrypcji (na przykład przy pominiętym/nieobsługiwanym wejściu). +- `api.runtime.stt.transcribeAudioFile(...)` pozostaje aliasem zgodności. -Pluginy mogą też uruchamiać w tle przebiegi subagentów przez `api.runtime.subagent`: +Pluginy mogą także uruchamiać w tle przebiegi subagenta przez `api.runtime.subagent`: ```ts const result = await api.runtime.subagent.run({ @@ -1002,14 +1008,14 @@ const result = await api.runtime.subagent.run({ Uwagi: -- `provider` i `model` to opcjonalne nadpisania per przebieg, a nie trwałe zmiany sesji. +- `provider` i `model` to opcjonalne nadpisania per uruchomienie, a nie trwałe zmiany sesji. - OpenClaw honoruje te pola nadpisania tylko dla zaufanych wywołujących. -- Dla przebiegów fallback należących do pluginów operatorzy muszą wyrazić zgodę przez `plugins.entries..subagent.allowModelOverride: true`. +- W przypadku przebiegów fallback należących do pluginu operatorzy muszą wyrazić zgodę przez `plugins.entries..subagent.allowModelOverride: true`. - Użyj `plugins.entries..subagent.allowedModels`, aby ograniczyć zaufane pluginy do określonych kanonicznych celów `provider/model`, albo `"*"`, aby jawnie zezwolić na dowolny cel. -- Niezaufane przebiegi subagentów pluginów nadal działają, ale żądania nadpisania są odrzucane zamiast cicho przechodzić na fallback. +- Przebiegi subagentów z niezaufanych pluginów nadal działają, ale żądania nadpisania są odrzucane zamiast cicho przechodzić na fallback. -W przypadku wyszukiwania w sieci pluginy mogą korzystać ze współdzielonego helpera runtime zamiast -sięgać do podłączenia narzędzia agenta: +W przypadku web search pluginy mogą korzystać ze współdzielonego pomocnika runtime zamiast +sięgać do integracji narzędzia agenta: ```ts const providers = api.runtime.webSearch.listProviders({ @@ -1025,13 +1031,13 @@ const result = await api.runtime.webSearch.search({ }); ``` -Pluginy mogą także rejestrować dostawców wyszukiwania w sieci przez +Pluginy mogą też rejestrować dostawców web-search przez `api.registerWebSearchProvider(...)`. Uwagi: -- Zachowaj wybór dostawcy, rozwiązywanie poświadczeń i współdzieloną semantykę żądań w core. -- Używaj dostawców wyszukiwania w sieci dla transportów wyszukiwania specyficznych dla dostawcy. +- Zachowaj wybór dostawcy, rozwiązywanie poświadczeń i współdzieloną semantykę żądań w rdzeniu. +- Używaj dostawców web-search dla transportów wyszukiwania specyficznych dla dostawcy. - `api.runtime.webSearch.*` to preferowana współdzielona powierzchnia dla pluginów funkcji/kanałów, które potrzebują zachowania wyszukiwania bez zależności od wrappera narzędzia agenta. ### `api.runtime.imageGeneration` @@ -1047,10 +1053,10 @@ const providers = api.runtime.imageGeneration.listProviders({ }); ``` -- `generate(...)`: wygeneruj obraz przy użyciu skonfigurowanego łańcucha dostawców generowania obrazów. -- `listProviders(...)`: wyświetl dostępnych dostawców generowania obrazów i ich capabilities. +- `generate(...)`: generuje obraz z użyciem skonfigurowanego łańcucha dostawców generowania obrazów. +- `listProviders(...)`: wyświetla dostępnych dostawców generowania obrazów i ich możliwości. -## Trasy HTTP gateway +## Trasy HTTP Gatewaya Pluginy mogą udostępniać endpointy HTTP przez `api.registerHttpRoute(...)`. @@ -1069,32 +1075,32 @@ api.registerHttpRoute({ Pola trasy: -- `path`: ścieżka trasy pod serwerem HTTP gateway. -- `auth`: wymagane. Użyj `"gateway"`, aby wymagać zwykłego auth gateway, albo `"plugin"` dla auth/weryfikacji webhooków zarządzanych przez plugin. +- `path`: ścieżka trasy pod serwerem HTTP gatewaya. +- `auth`: wymagane. Użyj `"gateway"`, aby wymagać zwykłego auth gatewaya, albo `"plugin"` dla auth/weryfikacji webhooka zarządzanych przez plugin. - `match`: opcjonalne. `"exact"` (domyślnie) albo `"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. +- `handler`: zwraca `true`, gdy trasa obsłużyła żądanie. Uwagi: - `api.registerHttpHandler(...)` zostało usunięte i spowoduje błąd ładowania pluginu. Użyj zamiast tego `api.registerHttpRoute(...)`. - Trasy pluginów muszą jawnie deklarować `auth`. -- Konflikty dokładnego `path + match` są odrzucane, chyba że `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. Zachowuj łańcuchy przejścia `exact`/`prefix` tylko na tym samym poziomie auth. -- Trasy `auth: "plugin"` **nie** otrzymują automatycznie zakresów runtime operatora. Służą do webhooków/weryfikacji podpisów zarządzanych przez plugin, a nie do uprzywilejowanych wywołań helperów Gateway. -- Trasy `auth: "gateway"` działają wewnątrz zakresu runtime żądania Gateway, ale ten zakres jest celowo konserwatywny: - - bearer auth ze współdzielonym sekretem (`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 ingressie) honorują `x-openclaw-scopes` tylko wtedy, gdy nagłówek jest jawnie obecny - - jeśli `x-openclaw-scopes` nie występuje w takich żądaniach trasy pluginu przenoszących tożsamość, zakres runtime wraca do `operator.write` -- Praktyczna zasada: nie zakładaj, że trasa pluginu z auth gateway jest domyślną powierzchnią admina. Jeśli Twoja trasa potrzebuje zachowania tylko dla admina, wymagaj trybu auth przenoszącego tożsamość i udokumentuj jawny kontrakt nagłówka `x-openclaw-scopes`. +- Konflikty dokładnych `path + match` są odrzucane, chyba że `replaceExisting: true`, a jeden plugin nie może zastąpić trasy innego pluginu. +- Nakładające się trasy z różnymi poziomami `auth` są odrzucane. Łańcuchy przejść `exact`/`prefix` utrzymuj tylko na tym samym poziomie auth. +- Trasy `auth: "plugin"` **nie** otrzymują automatycznie operatorowych zakresów runtime. Służą do webhooków/weryfikacji podpisów zarządzanych przez plugin, a nie uprzywilejowanych wywołań pomocników Gatewaya. +- Trasy `auth: "gateway"` działają wewnątrz zakresu runtime żądania Gatewaya, ale ten zakres jest celowo konserwatywny: + - uwierzytelnianie bearer współdzielonym sekretem (`gateway.auth.mode = "token"` / `"password"`) utrzymuje zakresy runtime trasy pluginu przypięte do `operator.write`, nawet jeśli wywołujący wysyła `x-openclaw-scopes` + - zaufane tryby HTTP niosące tożsamość (na przykład `trusted-proxy` albo `gateway.auth.mode = "none"` na prywatnym ingressie) honorują `x-openclaw-scopes` tylko wtedy, gdy nagłówek jest jawnie obecny + - jeśli `x-openclaw-scopes` jest nieobecny w takich żądaniach trasy pluginu niosących tożsamość, zakres runtime wraca do `operator.write` +- Praktyczna zasada: nie zakładaj, że trasa pluginu z auth gatewaya jest domyślnie powierzchnią administracyjną. Jeśli Twoja trasa wymaga zachowania tylko dla admina, wymagaj trybu auth niosącego tożsamość i udokumentuj jawny kontrakt nagłówka `x-openclaw-scopes`. ## Ścieżki importu Plugin SDK -Podczas tworzenia pluginów używaj subś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/config-schema` dla eksportu głównego schematu Zod `openclaw.json` +- `openclaw/plugin-sdk/config-schema` dla eksportu schematu Zod głównego `openclaw.json` (`OpenClawSchema`). - Stabilne prymitywy kanałów, takie jak `openclaw/plugin-sdk/channel-setup`, `openclaw/plugin-sdk/setup-runtime`, @@ -1108,22 +1114,25 @@ Podczas tworzenia pluginów używaj subścieżek SDK zamiast monolitycznego impo `openclaw/plugin-sdk/channel-reply-pipeline`, `openclaw/plugin-sdk/command-auth`, `openclaw/plugin-sdk/secret-input` i - `openclaw/plugin-sdk/webhook-ingress` dla współdzielonego okablowania konfiguracji/auth/odpowiedzi/webhooków. + `openclaw/plugin-sdk/webhook-ingress` dla współdzielonej integracji setup/auth/reply/webhook. `channel-inbound` to współdzielony dom dla debounce, dopasowywania wzmianek, - helperów polityki wzmianek przychodzących, formatowania envelope oraz helperów - kontekstu envelope przychodzącego. - `channel-setup` to wąska szczelina konfiguracji opcjonalnej instalacji. - `setup-runtime` to bezpieczna dla runtime powierzchnia konfiguracji używana przez `setupEntry` / - odroczone uruchamianie, w tym adaptery łatek konfiguracji bezpieczne przy importowaniu. - `setup-adapter-runtime` to świadoma env szczelina adaptera konfiguracji kont. - `setup-tools` to mała szczelina helperów CLI/archive/docs (`formatCliCommand`, + pomocników polityki wzmianek przychodzących, formatowania kopert i pomocników + kontekstu kopert przychodzących. + `channel-setup` to wąska szczelina setup z opcjonalną instalacją. + `setup-runtime` to bezpieczna dla runtime powierzchnia setup używana przez `setupEntry` / + odroczone uruchamianie, w tym adaptery łatek setup bezpieczne przy imporcie. + `setup-adapter-runtime` to szczelina adaptera setup kont świadoma env. + `setup-tools` to mała szczelina pomocników CLI/archive/docs (`formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR`). -- Subścieżki domenowe, takie jak `openclaw/plugin-sdk/channel-config-helpers`, +- Podścieżki domenowe, takie jak `openclaw/plugin-sdk/channel-config-helpers`, `openclaw/plugin-sdk/allow-from`, `openclaw/plugin-sdk/channel-config-schema`, `openclaw/plugin-sdk/telegram-command-config`, `openclaw/plugin-sdk/channel-policy`, + `openclaw/plugin-sdk/approval-gateway-runtime`, + `openclaw/plugin-sdk/approval-handler-adapter-runtime`, + `openclaw/plugin-sdk/approval-handler-runtime`, `openclaw/plugin-sdk/approval-runtime`, `openclaw/plugin-sdk/config-runtime`, `openclaw/plugin-sdk/infra-runtime`, @@ -1134,117 +1143,128 @@ Podczas tworzenia pluginów używaj subścieżek SDK zamiast monolitycznego impo `openclaw/plugin-sdk/status-helpers`, `openclaw/plugin-sdk/text-runtime`, `openclaw/plugin-sdk/runtime-store` i - `openclaw/plugin-sdk/directory-runtime` dla współdzielonych helperów runtime/konfiguracji. - `telegram-command-config` to wąska publiczna szczelina do normalizacji/walidacji - niestandardowych poleceń Telegram i pozostaje dostępna nawet wtedy, gdy - powierzchnia kontraktowa dołączonego Telegram jest tymczasowo niedostępna. - `text-runtime` to współdzielona szczelina tekst/markdown/logowanie, obejmująca - usuwanie tekstu widocznego dla asystenta, helpery renderowania/chunkowania markdown, helpery redakcji, - helpery tagów dyrektyw i narzędzia safe-text. -- Szczeliny kanałów specyficzne dla zatwierdzeń powinny preferować jeden kontrakt `approvalCapability` - na pluginie. Core odczytuje wtedy auth, dostarczanie, renderowanie i - natywne zachowanie routingu zatwierdzeń przez to jedno capability zamiast mieszać - zachowanie zatwierdzeń z niezwiązanymi polami pluginu. -- `openclaw/plugin-sdk/channel-runtime` jest przestarzałe i pozostaje tylko jako shim kompatybilności dla starszych pluginów. Nowy kod powinien importować zamiast tego węższe ogólne prymitywy, a kod repo nie powinien dodawać nowych importów tego shimu. -- Wnętrze dołączonych rozszerzeń pozostaje prywatne. Zewnętrzne pluginy powinny używać tylko subścieżek `openclaw/plugin-sdk/*`. Kod core/testów OpenClaw może używać publicznych punktów wejścia repo pod korzeniem pakietu pluginu, takich jak `index.js`, `api.js`, `runtime-api.js`, `setup-entry.js` i wąsko zakresowanych plików, takich jak `login-qr-api.js`. Nigdy nie importuj `src/*` pakietu pluginu z core ani z innego rozszerzenia. + `openclaw/plugin-sdk/directory-runtime` dla współdzielonych pomocników runtime/config. + `telegram-command-config` to wąska publiczna szczelina do normalizacji/walidacji niestandardowych + poleceń Telegram i pozostaje dostępna nawet wtedy, gdy powierzchnia kontraktu bundlowanego + Telegram jest tymczasowo niedostępna. + `text-runtime` to współdzielona szczelina tekst/markdown/logowanie, w tym + usuwanie tekstu widocznego dla asystenta, pomocniki renderowania/dzielenia markdown, + pomocniki redakcji, pomocniki tagów dyrektyw i bezpieczne narzędzia tekstowe. +- Szczeliny kanałów specyficzne dla zatwierdzeń powinny preferować jeden kontrakt + `approvalCapability` na pluginie. Rdzeń odczytuje wtedy auth zatwierdzeń, dostarczanie, renderowanie, + natywne routowanie i leniwe zachowanie natywnego handlera przez tę jedną możliwość + zamiast mieszać zachowanie zatwierdzeń z niezwiązanymi polami pluginu. +- `openclaw/plugin-sdk/channel-runtime` jest przestarzałe i pozostaje jedynie jako + shim zgodności dla starszych pluginów. Nowy kod powinien importować węższe ogólne prymitywy, a kod repo nie powinien dodawać nowych importów tego shimu. +- Wnętrza bundlowanych rozszerzeń pozostają prywatne. Zewnętrzne pluginy powinny używać wyłącznie podścieżek `openclaw/plugin-sdk/*`. Kod rdzenia/testów OpenClaw może używać publicznych punktów wejścia repo pod korzeniem pakietu pluginu, takich jak `index.js`, `api.js`, + `runtime-api.js`, `setup-entry.js` oraz wąsko zakresowanych plików takich jak + `login-qr-api.js`. Nigdy nie importuj `src/*` pakietu pluginu z rdzenia ani z + innego rozszerzenia. - Podział punktów wejścia repo: - `/api.js` to barrel helperów/typów, - `/runtime-api.js` to barrel tylko dla runtime, - `/index.js` to punkt wejścia dołączonego pluginu, - a `/setup-entry.js` to punkt wejścia pluginu konfiguracji. -- Obecne przykłady dołączonych dostawców: - - Anthropic używa `api.js` / `contract-api.js` dla helperów strumienia Claude, takich - jak `wrapAnthropicProviderStream`, helpery nagłówków beta i parsowanie `service_tier`. - - OpenAI używa `api.js` dla builderów dostawców, helperów modeli domyślnych i builderów dostawców realtime. - - OpenRouter używa `api.js` dla swojego buildera dostawcy oraz helperów onboardingu/konfiguracji, podczas gdy `register.runtime.js` nadal może re-eksportować ogólne helpery `plugin-sdk/provider-stream` do użytku lokalnego w repo. -- Publiczne punkty wejścia ładowane przez fasadę preferują aktywny snapshot konfiguracji runtime, gdy taki istnieje, a w przeciwnym razie wracają do rozwiązanej konfiguracji z pliku 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 kompatybilnościowych szczelin helperów dołączonych kanałów. Traktuj je jako szczeliny utrzymaniowe/kompatybilnościowe dla dołączonych elementów, a nie jako nowe cele importu dla third-party; nowe kontrakty międzykanałowe powinny nadal trafiać do ogólnych subścieżek `plugin-sdk/*` albo lokalnych barrelów pluginu `api.js` / `runtime-api.js`. + `/api.js` to barrel pomocników/typów, + `/runtime-api.js` to barrel tylko runtime, + `/index.js` to punkt wejścia bundlowanego pluginu, + a `/setup-entry.js` to punkt wejścia pluginu setup. +- Obecne przykłady bundlowanych dostawców: + - Anthropic używa `api.js` / `contract-api.js` dla pomocników streamów Claude, takich + jak `wrapAnthropicProviderStream`, pomocników nagłówków beta i parsowania `service_tier`. + - OpenAI używa `api.js` dla builderów dostawców, pomocników modeli domyślnych i + builderów dostawców realtime. + - OpenRouter używa `api.js` dla swojego buildera dostawcy oraz pomocników onboarding/config, + podczas gdy `register.runtime.js` może nadal reeksportować ogólne + pomocniki `plugin-sdk/provider-stream` do lokalnego użycia w repo. +- Publiczne punkty wejścia ładowane przez fasadę preferują aktywny snapshot konfiguracji runtime, + jeśli istnieje, a następnie wracają do rozstrzygniętego pliku konfiguracji na dysku, gdy + OpenClaw nie udostępnia jeszcze snapshotu runtime. +- Ogólne współdzielone prymitywy pozostają preferowanym publicznym kontraktem SDK. Nadal istnieje mały + zastrzeżony zestaw zgodności pomocniczych szczelin markowanych przez bundlowane kanały. Traktuj je jako + szczeliny utrzymania bundli/zgodności, a nie nowe cele importu dla stron trzecich; nowe kontrakty + międzykanałowe powinny nadal trafiać do ogólnych podścieżek `plugin-sdk/*` albo do lokalnych barrelów pluginu `api.js` / + `runtime-api.js`. -Uwaga dotycząca kompatybilności: +Uwaga o zgodności: - Unikaj głównego barrela `openclaw/plugin-sdk` w nowym kodzie. -- Najpierw preferuj wąskie stabilne prymitywy. Nowsze subścieżki konfiguracji/parowania/odpowiedzi/ +- 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 są zamierzonym kontraktem dla nowych - dołączonych i zewnętrznych pluginów. + allowlist/status/message-tool to zamierzony kontrakt dla nowych + bundlowanych i zewnętrznych pluginów. Parsowanie/dopasowywanie celów należy do `openclaw/plugin-sdk/channel-targets`. - Bramki akcji wiadomości i helpery message-id reakcji należą do + Bramki działań message i pomocniki identyfikatora wiadomości reakcji należą do `openclaw/plugin-sdk/channel-actions`. -- Barrels helperów specyficznych dla dołączonych rozszerzeń domyślnie nie są stabilne. Jeśli - helper jest potrzebny tylko dołączonemu rozszerzeniu, trzymaj go za lokalną szczeliną - `api.js` lub `runtime-api.js` tego rozszerzenia zamiast promować go do +- Barrels pomocnicze specyficzne dla bundlowanych rozszerzeń nie są domyślnie stabilne. Jeśli + jakiś pomocnik jest potrzebny tylko bundlowanemu rozszerzeniu, trzymaj go za lokalną szczeliną + `api.js` albo `runtime-api.js` tego rozszerzenia zamiast promować go do `openclaw/plugin-sdk/`. -- Nowe współdzielone szczeliny helperów powinny być ogólne, a nie markowane nazwą kanału. Wspólne - parsowanie celów należy do `openclaw/plugin-sdk/channel-targets`; wnętrza specyficzne dla kanału - pozostają za lokalną szczeliną `api.js` lub `runtime-api.js` właściciela pluginu. -- Subścieżki specyficzne dla capability, takie jak `image-generation`, - `media-understanding` i `speech`, istnieją, ponieważ dołączone/natywne pluginy używają ich dziś. - Sama ich obecność nie oznacza automatycznie, że każdy eksportowany helper jest +- Nowe współdzielone szczeliny pomocnicze powinny być ogólne, a nie markowane przez kanał. Współdzielone parsowanie celów należy do `openclaw/plugin-sdk/channel-targets`; wnętrza specyficzne dla kanału pozostają za lokalną szczeliną `api.js` albo `runtime-api.js` + należącą do odpowiedniego pluginu. +- Podścieżki specyficzne dla możliwości, takie jak `image-generation`, + `media-understanding` i `speech`, istnieją, ponieważ bundlowane/natywne pluginy używają + ich już dziś. Ich obecność nie oznacza sama w sobie, że każdy eksportowany pomocnik jest długoterminowym zamrożonym kontraktem zewnętrznym. -## Schematy narzędzia wiadomości +## Schematy narzędzia message -Pluginy powinny posiadać wkłady do schematu `describeMessageTool(...)` -specyficzne dla kanału. Zachowuj pola specyficzne dla dostawcy w pluginie, a nie we współdzielonym core. +Pluginy powinny posiadać wkład do schematu `describeMessageTool(...)` specyficzny dla kanału. +Pola specyficzne dla dostawcy trzymaj w pluginie, a nie we współdzielonym rdzeniu. -W przypadku współdzielonych przenośnych fragmentów schematu używaj ponownie ogólnych helperów eksportowanych przez +Dla współdzielonych przenośnych fragmentów schematu używaj ogólnych pomocników eksportowanych przez `openclaw/plugin-sdk/channel-actions`: -- `createMessageToolButtonsSchema()` dla ładunków w stylu siatki przycisków -- `createMessageToolCardSchema()` dla strukturalnych ładunków kart +- `createMessageToolButtonsSchema()` dla payloadów w stylu siatki przycisków +- `createMessageToolCardSchema()` dla payloadów ustrukturyzowanych kart -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. +Jeśli jakiś kształt schematu ma sens tylko dla jednego dostawcy, definiuj go w +własnym źródle tego pluginu, zamiast promować go do współdzielonego SDK. -## Rozwiązywanie celów kanału +## Rozstrzyganie celów kanału -Pluginy kanałów powinny posiadać semantykę celów specyficzną dla kanału. Zachowuj -wspólny host outbound jako ogólny i używaj powierzchni adaptera wiadomości do reguł dostawcy: +Pluginy kanałów powinny posiadać semantykę celów specyficzną dla kanału. Zachowaj +współdzielonego hosta outbound jako ogólnego i używaj powierzchni adaptera wiadomości dla reguł dostawcy: - `messaging.inferTargetChatType({ to })` decyduje, czy znormalizowany cel - powinien być traktowany jako `direct`, `group` czy `channel` przed wyszukaniem katalogowym. -- `messaging.targetResolver.looksLikeId(raw, normalized)` informuje core, czy dane wejście - powinno od razu przejść do rozwiązywania podobnego do ID zamiast do wyszukiwania w katalogu. + powinien być traktowany jako `direct`, `group` czy `channel` przed wyszukaniem w katalogu. +- `messaging.targetResolver.looksLikeId(raw, normalized)` mówi rdzeniowi, czy dane + wejście powinno od razu przejść do rozstrzygania podobnego do identyfikatora zamiast do wyszukiwania w katalogu. - `messaging.targetResolver.resolveTarget(...)` to fallback pluginu, gdy - core potrzebuje końcowego rozwiązania należącego do dostawcy po normalizacji lub - po nieudanym wyszukiwaniu katalogowym. -- `messaging.resolveOutboundSessionRoute(...)` posiada tworzenie trasy sesji - specyficznej dla dostawcy po rozwiązaniu celu. + rdzeń potrzebuje ostatecznego rozstrzygnięcia należącego do dostawcy po normalizacji albo po + braku trafienia w katalogu. +- `messaging.resolveOutboundSessionRoute(...)` obsługuje budowę trasy sesji + specyficznej dla dostawcy po rozstrzygnięciu celu. Zalecany podział: -- Używaj `inferTargetChatType` dla decyzji kategorii, które powinny zapaść przed +- Używaj `inferTargetChatType` do decyzji kategorycznych, które powinny nastąpić przed wyszukiwaniem peerów/grup. -- Używaj `looksLikeId` dla kontroli typu „traktuj to jako jawny/natywny identyfikator celu”. -- Używaj `resolveTarget` jako fallbacku normalizacji specyficznego dla dostawcy, a nie do - szerokiego wyszukiwania w katalogu. -- Zachowuj natywne identyfikatory dostawców, takie jak chat ids, thread ids, JID-y, handle i room ids - wewnątrz wartości `target` albo parametrów specyficznych dla dostawcy, a nie w ogólnych polach SDK. +- Używaj `looksLikeId` do sprawdzeń typu „traktuj to jako jawny/natywny identyfikator celu”. +- Używaj `resolveTarget` jako fallback normalizacji specyficzny dla dostawcy, a nie do + szerokiego wyszukiwania katalogowego. +- Natywne identyfikatory dostawcy, takie jak identyfikatory czatu, identyfikatory wątków, JID-y, handle i identyfikatory pokojów trzymaj w wartościach `target` albo parametrach specyficznych dla dostawcy, a nie w ogólnych polach SDK. ## Katalogi oparte na konfiguracji -Pluginy, które wyprowadzają wpisy katalogu z konfiguracji, powinny zachować tę logikę w -pluginie i używać ponownie współdzielonych helperów z +Pluginy, które wyprowadzają wpisy katalogu z konfiguracji, powinny utrzymywać tę logikę w +pluginie i ponownie wykorzystywać współdzielone pomocniki z `openclaw/plugin-sdk/directory-runtime`. Używaj tego, gdy kanał potrzebuje peerów/grup opartych na konfiguracji, takich jak: -- peery DM oparte na liście dozwolonych +- peery DM oparte na allowliście - skonfigurowane mapy kanałów/grup -- statyczne fallbacki katalogowe o zakresie konta +- statyczne fallbacki katalogu w zakresie konta -Współdzielone helpery w `directory-runtime` obsługują tylko operacje ogólne: +Współdzielone pomocniki w `directory-runtime` obsługują tylko operacje ogólne: - filtrowanie zapytań - stosowanie limitów -- helpery deduplikacji/normalizacji +- pomocniki deduplikacji/normalizacji - budowanie `ChannelDirectoryEntry[]` Inspekcja kont specyficzna dla kanału i normalizacja identyfikatorów powinny pozostać w implementacji pluginu. ## Katalogi dostawców -Pluginy dostawców mogą definiować katalogi modeli do wnioskowania przez +Pluginy dostawców mogą definiować katalogi modeli dla wnioskowania przez `registerProvider({ catalog: { run(...) { ... } } })`. `catalog.run(...)` zwraca ten sam kształt, który OpenClaw zapisuje do @@ -1253,25 +1273,25 @@ Pluginy dostawców mogą definiować katalogi modeli do wnioskowania przez - `{ provider }` dla jednego wpisu dostawcy - `{ providers }` dla wielu wpisów dostawców -Używaj `catalog`, gdy plugin posiada identyfikatory modeli specyficzne dla dostawcy, wartości domyślne base URL albo metadane modeli chronione auth. +Używaj `catalog`, gdy plugin posiada identyfikatory modeli specyficzne dla dostawcy, wartości domyślne `baseUrl` albo metadane modeli chronione auth. -`catalog.order` kontroluje, kiedy katalog pluginu scala się względem +`catalog.order` steruje tym, kiedy katalog pluginu łączy się względem wbudowanych niejawnych dostawców OpenClaw: -- `simple`: zwykli dostawcy oparty na kluczu API albo env +- `simple`: zwykli dostawcy oparci na kluczu API albo env - `profile`: dostawcy pojawiający się, gdy istnieją profile auth -- `paired`: dostawcy syntetyzujący wiele powiązanych wpisów dostawców +- `paired`: dostawcy, którzy syntetyzują wiele powiązanych wpisów dostawców - `late`: ostatnie przejście, po innych niejawnych dostawcach Późniejsi dostawcy wygrywają przy kolizji kluczy, więc pluginy mogą celowo nadpisywać wbudowany wpis dostawcy z tym samym identyfikatorem dostawcy. -Kompatybilność: +Zgodność: - `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 +## Inspekcja kanałów tylko do odczytu Jeśli Twój plugin rejestruje kanał, preferuj implementację `plugin.config.inspectAccount(cfg, accountId)` obok `resolveAccount(...)`. @@ -1279,29 +1299,27 @@ Jeśli Twój plugin rejestruje kanał, preferuj implementację 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 wymagane sekrety są niedostępne. + są w pełni zmaterializowane i może szybko kończyć się błędem, gdy brakuje wymaganych sekretów. - Ścieżki poleceń tylko do odczytu, takie jak `openclaw status`, `openclaw status --all`, - `openclaw channels status`, `openclaw channels resolve` oraz przepływy doctor/naprawy konfiguracji + `openclaw channels status`, `openclaw channels resolve` i przepływy doctor/naprawy konfiguracji 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`. -- Uwzględniaj pola źródła/statusu poświadczeń, gdy mają znaczenie, takie jak: +- Dołączaj pola źródła/statusu poświadczeń, gdy to istotne, na przykład: - `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. - Zwrot `tokenStatus: "available"` (i odpowiadającego pola źródła) - wystarczy dla poleceń w stylu statusu. -- Używaj `configured_unavailable`, gdy poświadczenie jest skonfigurowane przez SecretRef, ale - niedostępne w bieżącej ścieżce polecenia. +- Nie musisz zwracać surowych wartości tokenów tylko po to, by raportować dostępność tylko do odczytu. Zwrócenie `tokenStatus: "available"` (i pasującego pola źródła) wystarczy dla poleceń w stylu statusu. +- Używaj `configured_unavailable`, gdy poświadczenie jest skonfigurowane przez SecretRef, ale niedostępne + w bieżącej ścieżce polecenia. -Dzięki temu polecenia tylko do odczytu mogą raportować „skonfigurowane, ale niedostępne w tej ścieżce polecenia” zamiast kończyć się awarią lub błędnie zgłaszać konto jako nieskonfigurowane. +Dzięki temu polecenia tylko do odczytu mogą raportować „skonfigurowane, ale niedostępne w tej ścieżce polecenia” zamiast kończyć się awarią albo błędnie zgłaszać, że konto nie jest skonfigurowane. -## Package packs +## Pakiety pack Katalog pluginu może zawierać `package.json` z `openclaw.extensions`: @@ -1318,56 +1336,58 @@ Katalog pluginu może zawierać `package.json` z `openclaw.extensions`: 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, tak 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`). -Guardrail 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ą +Bariera 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 lifecycle i bez zależności dev w runtime). Utrzymuj drzewa zależności pluginów jako „czyste JS/TS” i unikaj pakietów, które wymagają budowania przez `postinstall`. +Uwaga bezpieczeństwa: `openclaw plugins install` instaluje zależności pluginu przez +`npm install --omit=dev --ignore-scripts` (bez skryptów cyklu życia, bez zależności deweloperskich w runtime). Utrzymuj drzewa zależności pluginów jako „czyste JS/TS” i unikaj pakietów wymagających buildów `postinstall`. -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 także narzędzia, hooki lub inny kod tylko runtime. +Opcjonalnie: `openclaw.setupEntry` może wskazywać lekki moduł tylko do setup. +Gdy OpenClaw potrzebuje powierzchni setup dla wyłączonego pluginu kanału albo +gdy plugin kanału jest włączony, ale nadal nieskonfigurowany, ładuje `setupEntry` zamiast pełnego wpisu pluginu. Dzięki temu uruchamianie i setup są lżejsze, +gdy główny wpis pluginu rejestruje również narzędzia, hooki lub inny kod tylko runtime. Opcjonalnie: `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` -pozwala pluginowi kanału wejść na tę samą ścieżkę `setupEntry` podczas -fazy uruchamiania gateway przed rozpoczęciem nasłuchiwania, nawet gdy kanał jest już skonfigurowany. +może włączyć plugin kanału do tej samej ścieżki `setupEntry` podczas fazy +uruchamiania gatewaya przed nasłuchem, nawet gdy kanał jest już skonfigurowany. -Używaj tego tylko wtedy, gdy `setupEntry` w pełni pokrywa powierzchnię startową, która musi istnieć -zanim gateway zacznie nasłuchiwać. W praktyce oznacza to, że punkt konfiguracji -musi zarejestrować każde capability należące do kanału, od którego zależy start, takie jak: +Używaj tego tylko wtedy, gdy `setupEntry` w pełni pokrywa powierzchnię uruchamiania, która musi istnieć +zanim gateway zacznie nasłuchiwać. W praktyce oznacza to, że wpis setup +musi rejestrować każdą możliwość należącą do kanału, od której zależy uruchamianie, taką jak: - sama rejestracja kanału - 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 +- wszelkie metody gatewaya, narzędzia lub usługi, które muszą istnieć w tym samym oknie -Jeśli Twój pełny punkt wejścia nadal posiada jakiekolwiek wymagane capability startowe, nie włączaj -tej flagi. Pozostaw plugin przy zachowaniu domyślnym i pozwól OpenClaw załadować pełny punkt wejścia podczas uruchamiania. +Jeśli Twój pełny wpis nadal posiada jakąkolwiek wymaganą możliwość uruchamiania, nie włączaj +tej flagi. Pozostaw plugin przy zachowaniu domyślnym i pozwól OpenClaw załadować +pełny wpis podczas uruchamiania. -Dołączone 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: +Bundlowane kanały mogą także publikować pomocniki powierzchni kontraktowej tylko do setup, z których rdzeń +może korzystać przed załadowaniem pełnego runtime kanału. Obecna powierzchnia promocji setup to: - `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 dołączonym przykładem: przenosi tylko klucze auth/bootstrap do -nazwanego promowanego konta, gdy istnieją już nazwane konta, i może zachować +Rdzeń używa tej powierzchni, gdy musi awansować starszą konfigurację kanału z jednym kontem do +`channels..accounts.*` bez ładowania pełnego wpisu pluginu. +Matrix jest obecnym bundlowanym przykładem: przenosi tylko klucze auth/bootstrap do +nazwanego awansowanego konta, gdy nazwane konta już istnieją, i może zachować skonfigurowany niekanoniczny klucz konta domyślnego zamiast zawsze tworzyć `accounts.default`. -Te adaptery łatek konfiguracji utrzymują leniwe wykrywanie powierzchni kontraktowej dołączonych elementów. Czas importu pozostaje niski; powierzchnia promocji jest ładowana tylko przy pierwszym użyciu zamiast ponownie wchodzić w uruchamianie dołączonego kanału przy imporcie modułu. +Te adaptery łatek setup utrzymują leniwe wykrywanie powierzchni kontraktowej bundli. Czas +importu pozostaje lekki; powierzchnia promocji jest ładowana dopiero przy pierwszym użyciu zamiast +ponownie wchodzić w uruchamianie bundlowanego kanału przy imporcie modułu. -Gdy te powierzchnie startowe obejmują metody RPC gateway, utrzymuj je na -prefiksie specyficznym dla pluginu. Przestrzenie nazw admina core (`config.*`, -`exec.approvals.*`, `wizard.*`, `update.*`) pozostają zastrzeżone i zawsze są rozwiązywane +Gdy te powierzchnie uruchamiania obejmują metody Gateway RPC, utrzymuj je pod +prefiksem specyficznym dla pluginu. Przestrzenie nazw administracyjnych rdzenia (`config.*`, +`exec.approvals.*`, `wizard.*`, `update.*`) pozostają zastrzeżone i zawsze są rozstrzygane do `operator.admin`, nawet jeśli plugin żąda węższego zakresu. Przykład: @@ -1385,10 +1405,10 @@ Przykład: } ``` -### Metadane katalogu kanałów +### Metadane katalogu kanału -Pluginy kanałów mogą reklamować metadane konfiguracji/wykrywania przez `openclaw.channel` i -wskazówki instalacyjne przez `openclaw.install`. Dzięki temu dane katalogu core pozostają wolne od twardego kodowania. +Pluginy kanałów mogą reklamować metadane setup/wykrywania przez `openclaw.channel` oraz +wskazówki instalacyjne przez `openclaw.install`. Dzięki temu dane katalogu rdzenia pozostają wolne od danych. Przykład: @@ -1416,40 +1436,41 @@ Przykład: } ``` -Przydatne pola `openclaw.channel` poza minimalnym przykładem: +Przydatne pola `openclaw.channel` wykraczające poza minimalny przykład: - `detailLabel`: etykieta pomocnicza dla bogatszych powierzchni katalogu/statusu -- `docsLabel`: nadpisuje tekst linku do dokumentacji +- `docsLabel`: nadpisanie tekstu 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 dla decyzji formatowania outbound -- `exposure.configured`: ukrywa kanał z powierzchni list kanałów skonfigurowanych, gdy ustawione na `false` -- `exposure.setup`: ukrywa kanał z interaktywnych pickerów konfiguracji, gdy ustawione na `false` +- `selectionDocsPrefix`, `selectionDocsOmitLabel`, `selectionExtras`: kontrolki tekstu dla powierzchni wyboru +- `markdownCapable`: oznacza kanał jako zdolny do markdown na potrzeby decyzji o formatowaniu outbound +- `exposure.configured`: ukrywa kanał przed powierzchniami listowania skonfigurowanych kanałów, gdy ustawione na `false` +- `exposure.setup`: ukrywa kanał przed interaktywnymi pickerami setup/configure, gdy ustawione na `false` - `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 quickstart `allowFrom` +- `showConfigured` / `showInSetup`: starsze aliasy nadal akceptowane dla zgodności; preferuj `exposure` +- `quickstartAllowFrom`: włącza kanał do standardowego przepływu szybkiego startu `allowFrom` - `forceAccountBinding`: wymaga jawnego powiązania konta nawet wtedy, gdy istnieje tylko jedno konto -- `preferSessionLookupForAnnounceTarget`: preferuje wyszukiwanie sesji przy rozwiązywaniu celów ogłaszania +- `preferSessionLookupForAnnounceTarget`: preferuje wyszukiwanie sesji przy rozstrzyganiu celów announce -OpenClaw może także scalać **zewnętrzne katalogi kanałów** (na przykład eksport rejestru MPM). +OpenClaw może też łączyć **zewnętrzne katalogi kanałów** (na przykład eksport rejestru MPM). Umieść plik JSON w jednej z lokalizacji: - `~/.openclaw/mpm/plugins.json` - `~/.openclaw/mpm/catalog.json` - `~/.openclaw/plugins/catalog.json` -Albo wskaż `OPENCLAW_PLUGIN_CATALOG_PATHS` (lub `OPENCLAW_MPM_CATALOG_PATHS`) na +Albo ustaw `OPENCLAW_PLUGIN_CATALOG_PATHS` (lub `OPENCLAW_MPM_CATALOG_PATHS`) na jeden lub więcej plików JSON (rozdzielanych przecinkiem/średnikiem/`PATH`). Każdy plik powinien -zawierać `{ "entries": [ { "name": "@scope/pkg", "openclaw": { "channel": {...}, "install": {...} } } ] }`. Parser akceptuje także `"packages"` lub `"plugins"` jako starsze aliasy klucza `"entries"`. +zawierać `{ "entries": [ { "name": "@scope/pkg", "openclaw": { "channel": {...}, "install": {...} } } ] }`. Parser akceptuje także `"packages"` albo `"plugins"` jako starsze aliasy klucza `"entries"`. ## Pluginy silnika kontekstu Pluginy silnika kontekstu posiadają orkiestrację kontekstu sesji dla ingestu, składania -i kompaktowania. Rejestruj je ze swojego pluginu przez -`api.registerContextEngine(id, factory)`, a następnie wybierz aktywny silnik przez +i kompaktowania. Rejestruj je z poziomu pluginu przez +`api.registerContextEngine(id, factory)`, a następnie wybieraj aktywny silnik przez `plugins.slots.contextEngine`. -Używaj tego, gdy Twój plugin musi zastąpić lub rozszerzyć domyślny pipeline kontekstu, a nie tylko dodawać wyszukiwanie pamięci lub hooki. +Używaj tego, gdy Twój plugin musi zastąpić lub rozszerzyć domyślny potok kontekstu +zamiast tylko dodawać memory search albo hooki. ```ts import { buildMemorySystemPromptAddition } from "openclaw/plugin-sdk/core"; @@ -1478,7 +1499,7 @@ export default function (api) { ``` Jeśli Twój silnik **nie** posiada algorytmu kompaktowania, zachowaj implementację `compact()` -i jawnie ją deleguj: +i jawnie do niego deleguj: ```ts import { @@ -1513,61 +1534,62 @@ export default function (api) { } ``` -## Dodawanie nowego capability +## Dodawanie nowej możliwości -Gdy plugin potrzebuje zachowania, które nie pasuje do obecnego API, nie omijaj -systemu pluginów przez prywatne sięganie do wnętrza. Dodaj brakujące capability. +Gdy plugin potrzebuje zachowania, które nie mieści się w obecnym API, nie omijaj +systemu pluginów przez prywatny reach-in. Dodaj brakującą możliwość. Zalecana sekwencja: -1. zdefiniuj kontrakt core - Zdecyduj, jakie współdzielone zachowanie powinno należeć do core: zasady, fallback, scalanie konfiguracji, - lifecycle, semantyka widoczna dla kanałów i kształt helpera runtime. +1. zdefiniuj kontrakt rdzenia + Zdecyduj, jakie współdzielone zachowanie powinien posiadać rdzeń: polityka, fallback, łączenie konfiguracji, + cykl życia, semantyka skierowana do kanałów i kształt pomocników runtime. 2. dodaj typowane powierzchnie rejestracji/runtime pluginów Rozszerz `OpenClawPluginApi` i/lub `api.runtime` o najmniejszą użyteczną - typowaną powierzchnię capability. -3. podłącz konsumentów core + kanałów/funkcji - Kanały i pluginy funkcji powinny korzystać z nowego capability przez core, + typowaną powierzchnię możliwości. +3. podłącz konsumentów rdzenia i kanałów/funkcji + Kanały i pluginy funkcji powinny korzystać z nowej możliwości przez rdzeń, a nie przez bezpośredni import implementacji dostawcy. 4. zarejestruj implementacje dostawców - Pluginy dostawców rejestrują następnie swoje backendy względem capability. + 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 pozostaje opiniotwórczy, nie stając się jednocześnie zakodowanym na sztywno do -światopoglądu jednego dostawcy. Konkretną listę plików i gotowy przykład znajdziesz w [Capability Cookbook](/pl/plugins/architecture). +Tak OpenClaw pozostaje opiniotwórczy bez twardego zakodowania jednego +światopoglądu dostawcy. Zobacz [Capability Cookbook](/pl/plugins/architecture), +aby znaleźć konkretną listę plików i gotowy przykład. -### Lista kontrolna capability +### Lista kontrolna możliwości -Gdy dodajesz nowe capability, implementacja powinna zwykle dotknąć razem tych +Gdy dodajesz nową możliwość, implementacja zwykle powinna wspólnie dotknąć tych powierzchni: -- typów kontraktów core w `src//types.ts` -- runnera/helpera runtime core w `src//runtime.ts` +- typów kontraktu rdzenia w `src//types.ts` +- runnera/pomocnika runtime rdzenia w `src//runtime.ts` - powierzchni rejestracji API pluginów w `src/plugins/types.ts` -- podłączenia rejestru pluginów w `src/plugins/registry.ts` -- ekspozycji runtime pluginów w `src/plugins/runtime/*`, gdy pluginy funkcji/kanałów - muszą z niego korzystać -- helperów przechwytywania/testów w `src/test-utils/plugin-registration.ts` +- integracji rejestru pluginów w `src/plugins/registry.ts` +- udostępnienia runtime pluginów w `src/plugins/runtime/*`, gdy pluginy funkcji/kanałów + muszą z tego korzystać +- pomocników przechwytywania/testów w `src/test-utils/plugin-registration.ts` - asercji własności/kontraktu w `src/plugins/contracts/registry.ts` - dokumentacji operatora/pluginów w `docs/` -Jeśli którejś z tych powierzchni brakuje, zwykle oznacza to, że capability nie jest -jeszcze w pełni zintegrowane. +Jeśli którejś z tych powierzchni brakuje, zwykle oznacza to, że możliwość nie jest jeszcze +w pełni zintegrowana. -### Szablon capability +### Szablon możliwości Minimalny wzorzec: ```ts -// core contract +// kontrakt rdzenia export type VideoGenerationProviderPlugin = { id: string; label: string; generateVideo: (req: VideoGenerationRequest) => Promise; }; -// plugin API +// API pluginu api.registerVideoGenerationProvider({ id: "openai", label: "OpenAI", @@ -1576,7 +1598,7 @@ api.registerVideoGenerationProvider({ }, }); -// shared runtime helper for feature/channel plugins +// współdzielony pomocnik runtime dla pluginów funkcji/kanałów const clip = await api.runtime.videoGeneration.generate({ prompt: "Show the robot walking through the lab.", cfg, @@ -1591,7 +1613,7 @@ expect(findVideoGenerationProviderIdsForPlugin("openai")).toEqual(["openai"]); To utrzymuje prostą zasadę: -- core posiada kontrakt capability + orkiestrację +- rdzeń posiada kontrakt możliwości + orkiestrację - pluginy dostawców posiadają implementacje dostawców -- pluginy funkcji/kanałów korzystają z helperów runtime -- testy kontraktowe utrzymują własność jako jawną +- pluginy funkcji/kanałów korzystają z pomocników runtime +- testy kontraktowe utrzymują jawną własność diff --git a/docs/pl/plugins/sdk-channel-plugins.md b/docs/pl/plugins/sdk-channel-plugins.md index 6c9920405..0c3b96a18 100644 --- a/docs/pl/plugins/sdk-channel-plugins.md +++ b/docs/pl/plugins/sdk-channel-plugins.md @@ -7,131 +7,147 @@ sidebarTitle: Channel Plugins summary: Przewodnik krok po kroku po tworzeniu pluginu kanału wiadomości dla OpenClaw title: Tworzenie pluginów kanałów x-i18n: - generated_at: "2026-04-07T09:47:54Z" + generated_at: "2026-04-08T02:17:00Z" model: gpt-5.4 provider: openai - source_hash: 0aab6cc835b292c62e33c52ad0c35f989fb1a5b225511e8bdc2972feb3c64f09 + source_hash: d23365b6d92006b30e671f9f0afdba40a2b88c845c5d2299d71c52a52985672f source_path: plugins/sdk-channel-plugins.md workflow: 15 --- # Tworzenie pluginów kanałów -Ten przewodnik prowadzi krok po kroku przez tworzenie pluginu kanału, który łączy OpenClaw z +Ten przewodnik pokazuje, jak zbudować plugin 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. +parowaniem, wątkowaniem odpowiedzi i wysyłaniem wiadomości wychodzących. - Jeśli nie tworzono wcześniej żadnego pluginu OpenClaw, najpierw przeczytaj - [Getting Started](/pl/plugins/building-plugins), aby poznać podstawową strukturę + Jeśli nie tworzyłeś wcześniej ż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 -Pluginy kanałów nie potrzebują własnych narzędzi send/edit/react. OpenClaw utrzymuje jedno -wspólne narzędzie `message` w core. Plugin zarządza: +Pluginy kanałów nie potrzebują własnych narzędzi do wysyłania/edycji/reakcji. OpenClaw utrzymuje +jedno współdzielone narzędzie `message` w rdzeniu. Twój plugin odpowiada za: -- **Config** — rozwiązywaniem kont i kreatorem konfiguracji -- **Security** — polityką DM i allowlistami -- **Pairing** — przepływem zatwierdzania DM -- **Session grammar** — tym, jak identyfikatory rozmów specyficzne dla providera mapują się na czaty bazowe, identyfikatory wątków i fallbacki do elementów nadrzędnych -- **Outbound** — wysyłaniem tekstu, mediów i ankiet na platformę -- **Threading** — sposobem wątkowania odpowiedzi +- **Konfigurację** — rozwiązywanie kont i kreator konfiguracji +- **Bezpieczeństwo** — politykę DM i listy dozwolonych +- **Parowanie** — przepływ zatwierdzania DM +- **Gramatykę sesji** — sposób, w jaki identyfikatory rozmów specyficzne dla dostawcy mapują się na bazowe czaty, identyfikatory wątków i zapasowe relacje nadrzędne +- **Ruch wychodzący** — wysyłanie tekstu, multimediów i ankiet na platformę +- **Wątkowanie** — sposób wątkowania odpowiedzi -Core zarządza wspólnym narzędziem wiadomości, okablowaniem promptów, zewnętrznym kształtem klucza sesji, -ogólnym bookkeepingiem `:thread:` i dispatch. +Rdzeń odpowiada za współdzielone narzędzie wiadomości, połączenia promptów, zewnętrzny kształt klucza sesji, +ogólne prowadzenie ewidencji `:thread:` oraz dispatch. -Jeśli platforma przechowuje dodatkowy zakres wewnątrz identyfikatorów rozmów, utrzymuj to parsowanie -w pluginie za pomocą `messaging.resolveSessionConversation(...)`. To jest +Jeśli Twoja platforma przechowuje dodatkowy zakres w identyfikatorach rozmów, zachowaj to parsowanie +w pluginie przy użyciu `messaging.resolveSessionConversation(...)`. To jest kanoniczny hook do mapowania `rawId` na bazowy identyfikator rozmowy, opcjonalny identyfikator wątku, -jawny `baseConversationId` oraz wszelkie `parentConversationCandidates`. -Gdy zwracasz `parentConversationCandidates`, zachowuj kolejność od -najwęższego elementu nadrzędnego do najszerszej/bazowej rozmowy. +jawny `baseConversationId` oraz ewentualne `parentConversationCandidates`. +Gdy zwracasz `parentConversationCandidates`, zachowaj ich kolejność od +najwęższego nadrzędnego do najszerszej/bazowej rozmowy. -Dołączone 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(...)`. Core używa tej bezpiecznej przy bootstrapie powierzchni -tylko wtedy, gdy rejestr pluginów runtime nie jest jeszcze dostępny. +Bundled plugins, które potrzebują tego samego parsowania przed uruchomieniem rejestru kanałów, +mogą również udostępniać plik najwyższego poziomu `session-key-api.ts` z pasującym +eksportem `resolveSessionConversation(...)`. Rdzeń używa tej bezpiecznej dla bootstrap powierzchni +tylko wtedy, gdy rejestr pluginów środowiska wykonawczego nie jest jeszcze dostępny. -`messaging.resolveParentConversationCandidates(...)` pozostaje dostępne jako -starszy fallback zgodności, gdy plugin potrzebuje tylko fallbacków elementów nadrzędnych -ponad ogólnym/surowym identyfikatorem. Jeśli istnieją oba hooki, core używa najpierw -`resolveSessionConversation(...).parentConversationCandidates` i wraca do -`resolveParentConversationCandidates(...)` tylko wtedy, gdy kanoniczny hook -ich nie poda. +`messaging.resolveParentConversationCandidates(...)` nadal pozostaje dostępne jako +starszy zapasowy mechanizm zgodności, gdy plugin potrzebuje tylko zapasowych relacji nadrzędnych +na bazie ogólnego/surowego identyfikatora. Jeśli istnieją oba hooki, rdzeń używa najpierw +`resolveSessionConversation(...).parentConversationCandidates` i przechodzi do +`resolveParentConversationCandidates(...)` tylko wtedy, gdy hook kanoniczny ich +nie zwraca. -## Zatwierdzenia i możliwości kanału +## Zatwierdzenia i możliwości kanałów Większość pluginów kanałów nie potrzebuje kodu specyficznego dla zatwierdzeń. -- Core zarządza `/approve` w tym samym czacie, współdzielonymi payloadami przycisków zatwierdzania oraz ogólnym dostarczaniem fallback. -- Preferuj jeden obiekt `approvalCapability` na pluginie kanału, gdy kanał potrzebuje zachowania specyficznego dla zatwierdzeń. -- `approvalCapability.authorizeActorAction` i `approvalCapability.getActionAvailabilityState` to kanoniczna szczelina autoryzacji zatwierdzeń. -- Jeśli kanał udostępnia natywne zatwierdzenia exec, zaimplementuj `approvalCapability.getActionAvailabilityState` nawet wtedy, gdy natywny transport znajduje się całkowicie pod `approvalCapability.native`. Core używa tego hooka dostępności, aby odróżnić `enabled` od `disabled`, zdecydować, czy kanał inicjujący obsługuje natywne zatwierdzenia, oraz uwzględnić kanał w wskazówkach fallback dla klientów natywnych. -- Używaj `outbound.shouldSuppressLocalPayloadPrompt` lub `outbound.beforeDeliverPayload` dla zachowań cyklu życia payloadu specyficznych dla kanału, takich jak ukrywanie zduplikowanych lokalnych promptów zatwierdzania lub wysyłanie wskaźników pisania przed dostarczeniem. -- Używaj `approvalCapability.delivery` tylko do natywnego routowania zatwierdzeń lub wyciszania fallbacku. -- Używaj `approvalCapability.render` tylko wtedy, gdy kanał naprawdę potrzebuje niestandardowych payloadów zatwierdzeń zamiast współdzielonego renderera. -- Używaj `approvalCapability.describeExecApprovalSetup`, gdy kanał chce, aby odpowiedź na ścieżce wyłączonej wyjaśniała dokładne klucze configu potrzebne do włączenia natywnych zatwierdzeń exec. Hook 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ł potrafi wywnioskować stabilne tożsamości DM podobne do właściciela na podstawie istniejącego configu, użyj `createResolvedApproverActionAuthAdapter` z `openclaw/plugin-sdk/approval-runtime`, aby ograniczyć `/approve` w tym samym czacie bez dodawania logiki specyficznej dla zatwierdzeń w core. -- Jeśli kanał potrzebuje natywnego dostarczania zatwierdzeń, utrzymuj kod kanału skoncentrowany na normalizacji targetu i hookach transportowych. Użyj `createChannelExecApprovalProfile`, `createChannelNativeOriginTargetResolver`, `createChannelApproverDmTargetResolver`, `createApproverRestrictedNativeApprovalCapability` oraz `createChannelNativeApprovalRuntime` z `openclaw/plugin-sdk/approval-runtime`, aby core zarządzał filtrowaniem żądań, routowaniem, deduplikacją, wygasaniem i subskrypcją gateway. -- Natywne kanały zatwierdzeń muszą routować zarówno `accountId`, jak i `approvalKind` przez te helpery. `accountId` utrzymuje zakres polityki zatwierdzeń dla wielu kont powiązany z właściwym kontem bota, a `approvalKind` utrzymuje zachowanie exec vs plugin dostępne dla kanału bez hardcoded branchy w core. -- Zachowuj dostarczony rodzaj identyfikatora zatwierdzenia end-to-end. Klienci natywni nie powinni - zgadywać ani przepisywać routowania zatwierdzeń exec vs plugin na podstawie lokalnego stanu kanału. -- Różne rodzaje zatwierdzeń mogą celowo udostępniać różne natywne powierzchnie. - Bieżące dołączone przykłady: - - Slack zachowuje natywne routowanie zatwierdzeń dostępne zarówno dla identyfikatorów exec, jak i plugin. - - Matrix zachowuje natywne routowanie DM/kanału tylko dla zatwierdzeń exec i pozostawia - zatwierdzenia pluginów na współdzielonej ścieżce `/approve` w tym samym czacie. +- Rdzeń odpowiada za `/approve` w tym samym czacie, współdzielone ładunki przycisków zatwierdzeń i ogólne zapasowe dostarczanie. +- Preferuj pojedynczy obiekt `approvalCapability` w pluginie kanału, gdy kanał potrzebuje zachowania specyficznego dla zatwierdzeń. +- `ChannelPlugin.approvals` zostało usunięte. Umieszczaj fakty dotyczące dostarczania/natywnego renderowania/uwierzytelniania zatwierdzeń w `approvalCapability`. +- `plugin.auth` służy tylko do logowania/wylogowania; rdzeń nie odczytuje już z tego obiektu hooków uwierzytelniania zatwierdzeń. +- `approvalCapability.authorizeActorAction` i `approvalCapability.getActionAvailabilityState` to kanoniczna powierzchnia dla 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 hooka specyficznego dla exec, aby rozróżniać `enabled` i `disabled`, zdecydować, czy kanał inicjujący obsługuje natywne zatwierdzenia exec, oraz uwzględnić kanał we wskazówkach zapasowych dla klientów natywnych. `createApproverRestrictedNativeApprovalCapability(...)` uzupełnia to dla typowego przypadku. +- Używaj `outbound.shouldSuppressLocalPayloadPrompt` lub `outbound.beforeDeliverPayload` dla zachowań cyklu życia ładunku specyficznych dla kanału, takich jak ukrywanie zduplikowanych lokalnych promptów zatwierdzeń albo wysyłanie wskaźników pisania przed dostarczeniem. +- Używaj `approvalCapability.delivery` tylko do natywnego routingu zatwierdzeń albo wyłączania routingu zapasowego. +- Używaj `approvalCapability.nativeRuntime` do faktów o natywnych zatwierdzeniach należących do kanału. Utrzymuj go jako leniwy w gorących punktach wejścia kanału za pomocą `createLazyChannelApprovalNativeRuntimeAdapter(...)`, który 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 własnych ładunków zatwierdzeń zamiast współdzielonego renderer. +- Używaj `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 ustawień najwyższego poziomu. +- Jeśli kanał może wywnioskować stabilne, podobne do właściciela tożsamości DM 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 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ć handler i przejąć filtrowanie żądań, routing, deduplikację, wygasanie, subskrypcję gateway oraz komunikaty o przekierowaniu gdzie indziej. `nativeRuntime` jest podzielone na kilka mniejszych powierzchni: +- `availability` — czy konto jest skonfigurowane i czy żądanie powinno zostać obsłużone +- `presentation` — mapowanie współdzielonego view model zatwierdzeń na natywne ładunki oczekujące/rozwiązane/wygasłe lub końcowe akcje +- `transport` — przygotowanie celów oraz wysyłanie/aktualizowanie/usuwanie natywnych wiadomości zatwierdzeń +- `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 runtime, takich jak klient, token, aplikacja Bolt lub odbiornik webhooków, zarejestruj je przez `openclaw/plugin-sdk/channel-runtime-context`. Ogólny rejestr kontekstu runtime pozwala rdzeniowi bootstrapować handlery oparte na możliwościach ze stanu uruchomienia kanału bez dodawania glue wrapperów specyficznych dla zatwierdzeń. +- Sięgaj po niższopoziomowe `createChannelApprovalHandler` lub `createChannelNativeApprovalRuntime` tylko wtedy, gdy powierzchnia oparta na możliwościach nie jest jeszcze wystarczająco wyrażalna. +- Kanały z natywnymi zatwierdzeniami muszą przekazywać zarówno `accountId`, jak i `approvalKind` przez te helpery. `accountId` utrzymuje politykę zatwierdzeń dla wielu kont w odpowiednim zakresie konta bota, a `approvalKind` utrzymuje zachowanie zatwierdzeń exec vs plugin dostępne dla kanału bez zakodowanych na sztywno rozgałęzień 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 należy udostępnić poprawny routing źródła + DM zatwierdzającego przez współdzielone helpery możliwości zatwierdzeń i pozwolić rdzeniowi agregować rzeczywiste dostarczenia przed opublikowaniem jakiegokolwiek komunikatu 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 udostępniać różne powierzchnie natywne. + Aktualne przykłady bundled: + - Slack utrzymuje dostępność natywnego routingu zatwierdzeń zarówno dla identyfikatorów exec, jak i plugin. + - Matrix zachowuje ten sam natywny routing DM/kanału i UX oparty na reakcjach dla zatwierdzeń exec + i plugin, jednocześnie nadal pozwalając, aby uwierzytelnianie różniło się w zależności od rodzaju zatwierdzenia. - `createApproverRestrictedNativeApprovalAdapter` nadal istnieje jako wrapper zgodności, ale nowy kod powinien preferować builder możliwości i udostępniać `approvalCapability` w pluginie. -Dla gorących entrypointów kanału preferuj węższe subścieżki runtime, gdy potrzebna -jest tylko jedna część 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` - `openclaw/plugin-sdk/approval-delivery-runtime` +- `openclaw/plugin-sdk/approval-gateway-runtime` +- `openclaw/plugin-sdk/approval-handler-adapter-runtime` +- `openclaw/plugin-sdk/approval-handler-runtime` - `openclaw/plugin-sdk/approval-native-runtime` - `openclaw/plugin-sdk/approval-reply-runtime` +- `openclaw/plugin-sdk/channel-runtime-context` Podobnie preferuj `openclaw/plugin-sdk/setup-runtime`, `openclaw/plugin-sdk/setup-adapter-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, +zbiorczej powierzchni. -Konkretnie dla setupu: +W przypadku konfiguracji w szczególności: -- `openclaw/plugin-sdk/setup-runtime` obejmuje bezpieczne dla runtime helpery setupu: - bezpieczne importowo adaptery patchowania setupu (`createPatchedAccountSetupAdapter`, +- `openclaw/plugin-sdk/setup-runtime` obejmuje bezpieczne dla runtime helpery konfiguracji: + bezpieczne przy importowaniu adaptery łatania konfiguracji (`createPatchedAccountSetupAdapter`, `createEnvPatchedAccountSetupAdapter`, - `createSetupInputPresenceValidator`), wyjście lookup-note, - `promptResolvedAllowFrom`, `splitSetupEntries` oraz delegowane - buildery setup-proxy -- `openclaw/plugin-sdk/setup-adapter-runtime` to wąska, świadoma env - szczelina adaptera dla `createEnvPatchedAccountSetupAdapter` -- `openclaw/plugin-sdk/channel-setup` obejmuje buildery setupu dla opcjonalnej instalacji - oraz kilka prymitywów bezpiecznych dla setupu: + `createSetupInputPresenceValidator`), wyjście notatek wyszukiwania, + `promptResolvedAllowFrom`, `splitSetupEntries` oraz buildery + setup-proxy delegowanych +- `openclaw/plugin-sdk/setup-adapter-runtime` to wąska, świadoma środowiska powierzchnia adaptera + dla `createEnvPatchedAccountSetupAdapter` +- `openclaw/plugin-sdk/channel-setup` obejmuje buildery konfiguracji z opcjonalną instalacją + oraz kilka prymitywów bezpiecznych dla konfiguracji: `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, -Jeśli kanał obsługuje setup lub auth sterowane env i ogólne przepływy startup/config -mają znać te nazwy env przed załadowaniem runtime, zadeklaruj je w -manifeście pluginu za pomocą `channelEnvVars`. Zachowaj runtime `envVars` kanału -lub lokalne stałe tylko do kopii operator-facing. +Jeśli Twój kanał obsługuje konfigurację lub uwierzytelnianie sterowane zmiennymi środowiskowymi i ogólne +przepływy uruchamiania/konfiguracji powinny znać nazwy tych zmiennych przed załadowaniem runtime, zadeklaruj je w +manifeście pluginu przy użyciu `channelEnvVars`. Zachowaj kanałowe `envVars` runtime lub lokalne +stałe tylko dla tekstów skierowanych do operatora. `createOptionalChannelSetupWizard`, `DEFAULT_ACCOUNT_ID`, `createTopLevelChannelDmPolicy`, `setSetupChannelEnabled` oraz `splitSetupEntries` -- używaj szerszej szczeliny `openclaw/plugin-sdk/setup` tylko wtedy, gdy potrzebujesz też - cięższych współdzielonych helperów setup/config, takich jak +- używaj szerszej powierzchni `openclaw/plugin-sdk/setup` tylko wtedy, gdy potrzebujesz również + cięższych współdzielonych helperów konfiguracji, takich jak `moveSingleAccountChannelSectionToDefaultAccount(...)` -Jeśli kanał chce tylko informować w powierzchniach setupu „najpierw zainstaluj ten plugin”, preferuj `createOptionalChannelSetupSurface(...)`. Wygenerowany -adapter/kreator domyślnie blokuje zapisy do configu i finalizację oraz ponownie używa -tego samego komunikatu „wymagana instalacja” w walidacji, finalizacji i tekście -odnośników do dokumentacji. +Jeśli Twój kanał chce jedynie reklamować w powierzchniach konfiguracji komunikat „najpierw zainstaluj ten plugin”, +preferuj `createOptionalChannelSetupSurface(...)`. Wygenerowany +adapter/kreator domyślnie odmawia zapisu konfiguracji i finalizacji oraz ponownie wykorzystuje +ten sam komunikat o wymaganej instalacji w walidacji, finalizacji i tekstach z linkami do dokumentacji. Dla innych gorących ścieżek kanału preferuj wąskie helpery zamiast szerszych starszych powierzchni: @@ -139,55 +155,53 @@ powierzchni: - `openclaw/plugin-sdk/account-core`, `openclaw/plugin-sdk/account-id`, `openclaw/plugin-sdk/account-resolution` oraz - `openclaw/plugin-sdk/account-helpers` dla configu wielu kont i - fallbacku konta domyślnego + `openclaw/plugin-sdk/account-helpers` dla konfiguracji wielu kont i + zapasowego użycia konta domyślnego - `openclaw/plugin-sdk/inbound-envelope` oraz - `openclaw/plugin-sdk/inbound-reply-dispatch` dla okablowania trasy/koperty przychodzącej i - record-and-dispatch -- `openclaw/plugin-sdk/messaging-targets` dla parsowania/dopasowywania targetów + `openclaw/plugin-sdk/inbound-reply-dispatch` dla routingu/koperty wejściowej i + połączenia record-and-dispatch +- `openclaw/plugin-sdk/messaging-targets` dla parsowania/dopasowywania celów - `openclaw/plugin-sdk/outbound-media` oraz - `openclaw/plugin-sdk/outbound-runtime` dla ładowania mediów oraz delegatów tożsamości/wysyłania + `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 payloadu agent/media -- `openclaw/plugin-sdk/telegram-command-config` dla normalizacji niestandardowych poleceń Telegram, - walidacji duplikatów/konfliktów oraz kontraktu configu poleceń - stabilnego względem fallbacku +- `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 agent/media +- `openclaw/plugin-sdk/telegram-command-config` dla normalizacji niestandardowych poleceń Telegram, walidacji duplikatów/konfliktów oraz stabilnego w razie fallback kontraktu konfiguracji poleceń -Kanały tylko-auth zwykle mogą zatrzymać się na ścieżce domyślnej: core 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ółdzielonych helperów natywnych zamiast pisać własny cykl życia zatwierdzeń. +Kanały wyłącznie uwierzytelniające zwykle mogą zakończyć na ścieżce domyślnej: rdzeń obsługuje zatwierdzenia, a plugin po prostu udostępnia możliwości outbound/auth. Kanały z natywnymi zatwierdzeniami, takie jak Matrix, Slack, Telegram oraz niestandardowe transporty czatu, powinny używać współdzielonych helperów natywnych zamiast implementować własny cykl życia zatwierdzeń. -## Polityka wzmianek przychodzących +## Polityka wzmianek przy wiadomościach przychodzących -Obsługę przychodzących wzmianek utrzymuj rozdzieloną na dwie warstwy: +Zachowaj obsługę przychodzących wzmianek rozdzieloną na dwie warstwy: -- gromadzenie dowodów po stronie pluginu -- współdzieloną ocenę polityki +- gromadzenie danych należące do pluginu +- współdzielona ewaluacja polityki -Do warstwy współdzielonej używaj `openclaw/plugin-sdk/channel-inbound`. +Dla warstwy współdzielonej używaj `openclaw/plugin-sdk/channel-inbound`. -Dobre zastosowania logiki lokalnej dla pluginu: +Dobre dopasowanie do logiki lokalnej pluginu: - wykrywanie odpowiedzi do bota - wykrywanie cytatu bota -- sprawdzanie udziału w wątku -- wykluczanie komunikatów usługowych/systemowych -- cache specyficzne dla platformy potrzebne do wykazania udziału bota +- sprawdzanie uczestnictwa wątku +- wykluczanie wiadomości usługowych/systemowych +- natywne dla platformy pamięci podręczne potrzebne do potwierdzenia udziału bota -Dobre zastosowania helpera współdzielonego: +Dobre dopasowanie do helpera współdzielonego: - `requireMention` -- wynik jawnej wzmianki -- allowlista niejawnych wzmianek -- obejście poleceń -- końcowa decyzja o pominięciu +- jawny wynik wzmianki +- lista dozwolonych niejawnych wzmianek +- obejście dla poleceń +- ostateczna decyzja o pominięciu Preferowany przepływ: 1. Oblicz lokalne fakty dotyczące wzmianek. 2. Przekaż te fakty do `resolveInboundMentionDecision({ facts, policy })`. -3. Użyj `decision.effectiveWasMentioned`, `decision.shouldBypassMention` oraz `decision.shouldSkip` w bramce przychodzącej. +3. Użyj `decision.effectiveWasMentioned`, `decision.shouldBypassMention` i `decision.shouldSkip` w bramce wiadomości przychodzących. ```typescript import { @@ -227,7 +241,7 @@ if (decision.shouldSkip) return; ``` `api.runtime.channel.mentions` udostępnia te same współdzielone helpery wzmianek dla -dołączonych pluginów kanałów, które już zależą od wstrzykiwania runtime: +bundled plugins kanałów, które już zależą od wstrzykiwania runtime: - `buildMentionRegexes` - `matchesMentionPatterns` @@ -236,17 +250,17 @@ dołączonych pluginów kanałów, które już zależą od wstrzykiwania runtime - `resolveInboundMentionDecision` Starsze helpery `resolveMentionGating*` pozostają w -`openclaw/plugin-sdk/channel-inbound` tylko jako eksporty zgodności. Nowy kod +`openclaw/plugin-sdk/channel-inbound` wyłącznie jako eksporty zgodności. Nowy kod powinien używać `resolveInboundMentionDecision({ facts, policy })`. -## Instrukcja krok po kroku +## Przewodnik krok po kroku Utwórz standardowe pliki pluginu. Pole `channel` w `package.json` - sprawia, że jest to plugin kanału. Pełny zakres metadanych pakietu - znajdziesz w [Plugin Setup and Config](/pl/plugins/sdk-setup#openclawchannel): + sprawia, że jest to plugin kanału. Pełny zakres metadanych pakietu znajdziesz + w [Konfiguracja pluginu i konfiguracja](/pl/plugins/sdk-setup#openclawchannel): ```json package.json @@ -260,7 +274,7 @@ powinien używać `resolveInboundMentionDecision({ facts, policy })`. "channel": { "id": "acme-chat", "label": "Acme Chat", - "blurb": "Połącz OpenClaw z Acme Chat." + "blurb": "Connect OpenClaw to Acme Chat." } } } @@ -272,7 +286,7 @@ powinien używać `resolveInboundMentionDecision({ facts, policy })`. "kind": "channel", "channels": ["acme-chat"], "name": "Acme Chat", - "description": "Plugin kanału Acme Chat", + "description": "Acme Chat channel plugin", "configSchema": { "type": "object", "additionalProperties": false, @@ -307,7 +321,7 @@ powinien używać `resolveInboundMentionDecision({ facts, policy })`. createChannelPluginBase, } from "openclaw/plugin-sdk/channel-core"; import type { OpenClawConfig } from "openclaw/plugin-sdk/channel-core"; - import { acmeChatApi } from "./client.js"; // klient API twojej platformy + import { acmeChatApi } from "./client.js"; // your platform API client type ResolvedAccount = { accountId: string | null; @@ -348,7 +362,7 @@ powinien używać `resolveInboundMentionDecision({ facts, policy })`. }, }), - // Zabezpieczenia DM: kto może pisać do bota + // DM security: who can message the bot security: { dm: { channelKey: "acme-chat", @@ -358,21 +372,21 @@ powinien używać `resolveInboundMentionDecision({ facts, policy })`. }, }, - // Pairing: przepływ zatwierdzania dla nowych kontaktów DM + // Pairing: approval flow for new DM contacts pairing: { text: { - idLabel: "Nazwa użytkownika Acme Chat", - message: "Wyślij ten kod, aby zweryfikować swoją tożsamość:", + idLabel: "Acme Chat username", + message: "Send this code to verify your identity:", notify: async ({ target, code }) => { await acmeChatApi.sendDm(target, `Pairing code: ${code}`); }, }, }, - // Wątkowanie: jak dostarczane są odpowiedzi + // Threading: how replies are delivered threading: { topLevelReplyToMode: "reply" }, - // Outbound: wysyłanie wiadomości na platformę + // Outbound: send messages to the platform outbound: { attachedResults: { sendText: async (params) => { @@ -392,16 +406,16 @@ powinien używać `resolveInboundMentionDecision({ facts, policy })`. }); ``` - + Zamiast ręcznie implementować niskopoziomowe interfejsy adapterów, - przekazujesz deklaratywne opcje, a builder składa je razem: + przekazujesz deklaratywne opcje, a builder je składa: - | Option | Co jest podłączane | + | Opcja | Co jest podłączane | | --- | --- | - | `security.dm` | Resolver zabezpieczeń DM z zakresem opartym na polach configu | - | `pairing.text` | Tekstowy przepływ pairing DM z wymianą kodów | - | `threading` | Resolver trybu reply-to (stały, z zakresem konta lub niestandardowy) | - | `outbound.attachedResults` | Funkcje wysyłania zwracające metadane wyniku (ID wiadomości) | + | `security.dm` | Resolver zabezpieczeń DM ograniczony do pól konfiguracji | + | `pairing.text` | Tekstowy przepływ parowania DM z wymianą kodów | + | `threading` | Resolver trybu odpowiedzi (stały, ograniczony do konta lub niestandardowy) | + | `outbound.attachedResults` | Funkcje wysyłania zwracające metadane wyniku (identyfikatory wiadomości) | Możesz też przekazać surowe obiekty adapterów zamiast opcji deklaratywnych, jeśli potrzebujesz pełnej kontroli. @@ -409,7 +423,7 @@ powinien używać `resolveInboundMentionDecision({ facts, policy })`. - + Utwórz `index.ts`: ```typescript index.ts @@ -419,20 +433,20 @@ powinien używać `resolveInboundMentionDecision({ facts, policy })`. export default defineChannelPluginEntry({ id: "acme-chat", name: "Acme Chat", - description: "Plugin kanału Acme Chat", + description: "Acme Chat channel plugin", plugin: acmeChatPlugin, registerCliMetadata(api) { api.registerCli( ({ program }) => { program .command("acme-chat") - .description("Zarządzanie Acme Chat"); + .description("Acme Chat management"); }, { descriptors: [ { name: "acme-chat", - description: "Zarządzanie Acme Chat", + description: "Acme Chat management", hasSubcommands: false, }, ], @@ -446,20 +460,20 @@ powinien używać `resolveInboundMentionDecision({ facts, policy })`. ``` Umieszczaj deskryptory CLI należące do kanału w `registerCliMetadata(...)`, aby OpenClaw - mógł je pokazać w głównej pomocy bez aktywowania pełnego runtime kanału, - a zwykłe pełne ładowanie nadal pobierało te same deskryptory do rzeczywistej - rejestracji poleceń. Zachowaj `registerFull(...)` dla pracy tylko runtime. - Jeśli `registerFull(...)` rejestruje metody gateway RPC, użyj - prefiksu specyficznego dla pluginu. Przestrzenie nazw administratora core (`config.*`, - `exec.approvals.*`, `wizard.*`, `update.*`) pozostają zarezerwowane i zawsze - rozwiązują się do `operator.admin`. - `defineChannelPluginEntry` automatycznie obsługuje ten podział trybów rejestracji. Zobacz - [Entry Points](/pl/plugins/sdk-entrypoints#definechannelpluginentry), aby poznać wszystkie + mógł pokazywać je w głównej pomocy bez aktywowania pełnego runtime kanału, + podczas gdy zwykłe pełne ładowania nadal pobierają te same deskryptory do rzeczywistej rejestracji + poleceń. Zachowaj `registerFull(...)` do pracy tylko w runtime. + Jeśli `registerFull(...)` rejestruje metody Gateway RPC, używaj + prefiksu specyficznego dla pluginu. Przestrzenie nazw administratora rdzenia (`config.*`, + `exec.approvals.*`, `wizard.*`, `update.*`) pozostają zastrzeżone i zawsze + są mapowane na `operator.admin`. + `defineChannelPluginEntry` automatycznie obsługuje podział trybów rejestracji. Zobacz + [Punkty wejścia](/pl/plugins/sdk-entrypoints#definechannelpluginentry), aby poznać wszystkie opcje. - + Utwórz `setup-entry.ts` do lekkiego ładowania podczas onboardingu: ```typescript setup-entry.ts @@ -469,28 +483,28 @@ powinien używać `resolveInboundMentionDecision({ facts, policy })`. export default defineSetupPluginEntry(acmeChatPlugin); ``` - OpenClaw ładuje ten plik zamiast pełnego entry, gdy kanał jest wyłączony - albo nieskonfigurowany. Pozwala to uniknąć wciągania ciężkiego kodu runtime podczas przepływów setupu. - Szczegóły znajdziesz w [Setup and Config](/pl/plugins/sdk-setup#setup-entry). + 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). - Plugin musi odbierać wiadomości z platformy i przekazywać je do + Twój plugin musi odbierać wiadomości z platformy i przekazywać je do OpenClaw. Typowy wzorzec to webhook, który weryfikuje żądanie i - dispatchuje je przez przychodzący handler kanału: + dispatchuje je przez handler wejściowy Twojego kanału: ```typescript registerFull(api) { api.registerHttpRoute({ path: "/acme-chat/webhook", - auth: "plugin", // uwierzytelnianie zarządzane przez plugin (zweryfikuj podpisy samodzielnie) + auth: "plugin", // plugin-managed auth (verify signatures yourself) handler: async (req, res) => { const event = parseWebhookPayload(req); - // Twój handler przychodzący dispatchuje wiadomość do OpenClaw. - // Dokładne okablowanie zależy od SDK twojej platformy — - // zobacz rzeczywisty przykład w dołączonym pakiecie pluginu Microsoft Teams lub Google Chat. + // Your inbound handler dispatches the message to OpenClaw. + // The exact wiring depends on your platform SDK — + // see a real example in the bundled Microsoft Teams or Google Chat plugin package. await handleAcmeChatInbound(api, event); res.statusCode = 200; @@ -503,22 +517,22 @@ powinien używać `resolveInboundMentionDecision({ facts, policy })`. Obsługa wiadomości przychodzących jest specyficzna dla kanału. Każdy plugin kanału - zarządza własnym pipeline przychodzącym. Zajrzyj do dołączonych pluginów kanałów - (na przykład do pakietu pluginu Microsoft Teams lub Google Chat), aby zobaczyć rzeczywiste wzorce. + odpowiada za własny pipeline wejściowy. Sprawdź bundled plugins kanałów + (na przykład pakiet pluginów Microsoft Teams lub Google Chat), aby zobaczyć rzeczywiste wzorce. - -Pisz testy współlokowane w `src/channel.test.ts`: + +Napisz testy colocated w `src/channel.test.ts`: ```typescript src/channel.test.ts import { describe, it, expect } from "vitest"; import { acmeChatPlugin } from "./channel.js"; describe("acme-chat plugin", () => { - it("rozwiązuje konto z configu", () => { + it("resolves account from config", () => { const cfg = { channels: { "acme-chat": { token: "test-token", allowFrom: ["user1"] }, @@ -528,7 +542,7 @@ Pisz testy współlokowane w `src/channel.test.ts`: expect(account.token).toBe("test-token"); }); - it("sprawdza konto bez materializowania sekretów", () => { + it("inspects account without materializing secrets", () => { const cfg = { channels: { "acme-chat": { token: "test-token" } }, } as any; @@ -537,7 +551,7 @@ Pisz testy współlokowane w `src/channel.test.ts`: expect(result.tokenStatus).toBe("available"); }); - it("zgłasza brakujący config", () => { + it("reports missing config", () => { const cfg = { channels: {} } as any; const result = acmeChatPlugin.setup!.inspectAccount!(cfg, undefined); expect(result.configured).toBe(false); @@ -549,7 +563,7 @@ Pisz testy współlokowane w `src/channel.test.ts`: pnpm test -- /acme-chat/ ``` - Współdzielone helpery testowe opisano w [Testing](/pl/plugins/sdk-testing). + Współdzielone helpery testowe znajdziesz w [Testowanie](/pl/plugins/sdk-testing). @@ -559,45 +573,45 @@ Pisz testy współlokowane w `src/channel.test.ts`: ``` /acme-chat/ ├── package.json # metadane openclaw.channel -├── openclaw.plugin.json # Manifest ze schematem configu +├── openclaw.plugin.json # Manifest ze schematem konfiguracji ├── index.ts # defineChannelPluginEntry ├── setup-entry.ts # defineSetupPluginEntry -├── api.ts # Eksporty publiczne (opcjonalnie) +├── api.ts # Publiczne eksporty (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 # Store runtime (jeśli potrzebny) + └── runtime.ts # Magazyn runtime (jeśli potrzebny) ``` ## Tematy zaawansowane - Stałe tryby odpowiedzi, tryby z zakresem konta lub niestandardowe + Stałe tryby odpowiedzi, ograniczone do konta lub niestandardowe - + describeMessageTool i wykrywanie akcji - + inferTargetChatType, looksLikeId, resolveTarget - TTS, STT, media, subagent przez api.runtime + TTS, STT, multimedia, subagent przez api.runtime -Niektóre dołączone szczeliny helperów nadal istnieją na potrzeby utrzymania dołączonych pluginów i +Niektóre bundled helper seams nadal istnieją na potrzeby utrzymania bundled plugins i zgodności. Nie są one zalecanym wzorcem dla nowych pluginów kanałów; -preferuj ogólne subścieżki channel/setup/reply/runtime ze wspólnej -powierzchni SDK, chyba że bezpośrednio utrzymujesz tę rodzinę dołączonych pluginów. +preferuj ogólne podścieżki channel/setup/reply/runtime ze wspólnej +powierzchni SDK, chyba że bezpośrednio utrzymujesz tę rodzinę bundled plugins. ## Kolejne kroki -- [Provider Plugins](/pl/plugins/sdk-provider-plugins) — jeśli plugin udostępnia również modele -- [SDK Overview](/pl/plugins/sdk-overview) — pełne odniesienie do importów subścieżek -- [SDK Testing](/pl/plugins/sdk-testing) — narzędzia testowe i testy kontraktowe -- [Plugin Manifest](/pl/plugins/manifest) — pełny schemat manifestu +- [Pluginy dostawców](/pl/plugins/sdk-provider-plugins) — jeśli Twój plugin dostarcza 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 diff --git a/docs/pl/plugins/sdk-migration.md b/docs/pl/plugins/sdk-migration.md index 5f762e3d7..a6167ab35 100644 --- a/docs/pl/plugins/sdk-migration.md +++ b/docs/pl/plugins/sdk-migration.md @@ -2,104 +2,129 @@ read_when: - Widzisz ostrzeżenie OPENCLAW_PLUGIN_SDK_COMPAT_DEPRECATED - Widzisz ostrzeżenie OPENCLAW_EXTENSION_API_DEPRECATED - - Aktualizujesz wtyczkę do nowoczesnej architektury wtyczek - - Utrzymujesz zewnętrzną wtyczkę OpenClaw + - Aktualizujesz plugin do nowoczesnej architektury pluginów OpenClaw + - Utrzymujesz zewnętrzny plugin OpenClaw sidebarTitle: Migrate to SDK -summary: Migracja ze starszej warstwy zgodności wstecznej do nowoczesnego SDK wtyczek +summary: Migracja ze starszej warstwy zgodności wstecznej do nowoczesnego Plugin SDK title: Migracja Plugin SDK x-i18n: - generated_at: "2026-04-07T09:48:40Z" + generated_at: "2026-04-08T02:17:46Z" model: gpt-5.4 provider: openai - source_hash: 3691060e9dc00ca8bee49240a047f0479398691bd14fb96e9204cc9243fdb32c + source_hash: 155a8b14bc345319c8516ebdb8a0ccdea2c5f7fa07dad343442996daee21ecad source_path: plugins/sdk-migration.md workflow: 15 --- # Migracja Plugin SDK -OpenClaw przeszedł od szerokiej warstwy zgodności wstecznej do nowoczesnej -architektury wtyczek z precyzyjnymi, udokumentowanymi importami. Jeśli Twoja -wtyczka została zbudowana przed wprowadzeniem nowej architektury, ten przewodnik -pomoże Ci przeprowadzić migrację. +OpenClaw przeszedł od szerokiej warstwy zgodności wstecznej do nowoczesnej architektury +pluginów z ukierunkowanymi, udokumentowanymi importami. Jeśli Twój plugin powstał przed +nową architekturą, ten przewodnik pomoże Ci przeprowadzić migrację. ## Co się zmienia -Stary system wtyczek udostępniał dwie szeroko otwarte powierzchnie, które pozwalały wtyczkom importować +Stary system pluginów udostępniał dwie bardzo szerokie powierzchnie, które pozwalały pluginom importować wszystko, czego potrzebowały, z jednego punktu wejścia: -- **`openclaw/plugin-sdk/compat`** — pojedynczy import, który re-eksportował dziesiątki - helperów. Został wprowadzony, aby utrzymać działanie starszych wtyczek opartych na hookach, - podczas gdy budowano nową architekturę wtyczek. -- **`openclaw/extension-api`** — most, który dawał wtyczkom bezpośredni dostęp do - helperów po stronie hosta, takich jak osadzony runner agenta. +- **`openclaw/plugin-sdk/compat`** — pojedynczy import, który reeksportował dziesiątki + pomocników. Został wprowadzony po to, aby starsze pluginy oparte na hookach nadal działały + podczas budowy nowej architektury pluginów. +- **`openclaw/extension-api`** — most, który dawał pluginom bezpośredni dostęp do + pomocników po stronie hosta, takich jak osadzony runner agenta. -Obie powierzchnie są teraz **przestarzałe**. Nadal działają w czasie wykonywania, ale nowe -wtyczki nie mogą ich używać, a istniejące wtyczki powinny przeprowadzić migrację, zanim kolejna -główna wersja je usunie. +Obie powierzchnie są teraz **przestarzałe**. Nadal działają w czasie działania, ale nowe +pluginy nie mogą ich używać, a istniejące pluginy powinny przeprowadzić migrację przed następnym +głównym wydaniem, które je usunie. - Warstwa zgodności wstecznej zostanie usunięta w jednej z przyszłych głównych wersji. - Wtyczki, które nadal importują z tych powierzchni, przestaną działać, gdy to nastąpi. + Warstwa zgodności wstecznej zostanie usunięta w jednym z przyszłych głównych wydań. + Pluginy, które nadal importują z tych powierzchni, przestaną działać, gdy to nastąpi. ## Dlaczego to się zmieniło Stare podejście powodowało problemy: -- **Powolny start** — zaimportowanie jednego helpera ładowało dziesiątki niezwiązanych modułów -- **Zależności cykliczne** — szerokie re-eksporty ułatwiały tworzenie cykli importu -- **Niejasna powierzchnia API** — nie było sposobu, aby stwierdzić, które eksporty są stabilne, a które wewnętrzne +- **Powolne uruchamianie** — zaimportowanie jednego pomocnika ładowało dziesiątki niepowiązanych modułów +- **Zależności cykliczne** — szerokie reeksporty ułatwiały tworzenie cykli importów +- **Niejasna powierzchnia API** — nie było sposobu, aby odróżnić stabilne eksporty od wewnętrznych -Nowoczesne SDK wtyczek rozwiązuje ten problem: każda ścieżka importu (`openclaw/plugin-sdk/\`) -jest małym, samodzielnym modułem z jasno określonym przeznaczeniem i udokumentowanym kontraktem. +Nowoczesny Plugin SDK to naprawia: każda ścieżka importu (`openclaw/plugin-sdk/\`) +jest małym, samodzielnym modułem o jasno określonym celu i udokumentowanym kontrakcie. -Starsze wygodne granice dostawców dla dołączonych kanałów również zniknęły. Importy +Starsze wygodne warstwy dostawców dla dołączonych kanałów również zniknęły. Importy takie jak `openclaw/plugin-sdk/slack`, `openclaw/plugin-sdk/discord`, `openclaw/plugin-sdk/signal`, `openclaw/plugin-sdk/whatsapp`, -pomocnicze granice oznaczone marką kanału oraz -`openclaw/plugin-sdk/telegram-core` były prywatnymi skrótami monorepo, a nie -stabilnymi kontraktami wtyczek. Zamiast tego używaj wąskich, generycznych ścieżek podrzędnych SDK. W obrębie -dołączonego workspace wtyczek trzymaj helpery należące do dostawcy we własnym -`api.ts` lub `runtime-api.ts` tej wtyczki. +warstwy pomocnicze oznaczone marką kanału oraz +`openclaw/plugin-sdk/telegram-core` były prywatnymi skrótami mono-repo, a nie +stabilnymi kontraktami pluginów. Zamiast tego używaj wąskich, ogólnych podścieżek SDK. Wewnątrz +dołączonego obszaru roboczego pluginów trzymaj pomocniki należące do dostawcy we własnym +`api.ts` lub `runtime-api.ts` tego pluginu. Aktualne przykłady dołączonych dostawców: -- Anthropic przechowuje helpery strumieni specyficzne dla Claude we własnej granicy `api.ts` / +- Anthropic przechowuje pomocniki strumieni specyficzne dla Claude we własnej warstwie `api.ts` / `contract-api.ts` -- OpenAI przechowuje konstruktory dostawcy, helpery modeli domyślnych i konstruktory - dostawców realtime we własnym `api.ts` -- OpenRouter przechowuje konstruktor dostawcy oraz helpery onboardingu/konfiguracji we własnym +- OpenAI przechowuje konstruktory dostawców, pomocniki modeli domyślnych i konstruktory dostawców realtime + we własnym `api.ts` +- OpenRouter przechowuje konstruktor dostawcy oraz pomocniki onboardingu/konfiguracji we własnym `api.ts` ## Jak przeprowadzić migrację - - Jeśli Twoja wtyczka używa `openclaw/plugin-sdk/windows-spawn`, nierozwiązane wrappery Windows - `.cmd`/`.bat` teraz kończą działanie w trybie fail-closed, chyba że jawnie przekażesz + + Pluginy kanałów obsługujące zatwierdzenia udostępniają teraz natywne zachowanie zatwierdzeń przez + `approvalCapability.nativeRuntime` oraz współdzielony rejestr runtime-context. + + Najważniejsze zmiany: + + - Zamień `approvalCapability.handler.loadRuntime(...)` na + `approvalCapability.nativeRuntime` + - Przenieś uwierzytelnianie/dostarczanie specyficzne dla zatwierdzeń ze starszego okablowania `plugin.auth` / + `plugin.approvals` na `approvalCapability` + - `ChannelPlugin.approvals` zostało usunięte z publicznego kontraktu pluginów kanałowych; + przenieś pola delivery/native/render do `approvalCapability` + - `plugin.auth` pozostaje tylko dla przepływów logowania/wylogowania kanału; hooki + uwierzytelniania zatwierdzeń nie są już tam odczytywane przez core + - Rejestruj obiekty runtime należące do kanału, takie jak klienci, tokeny lub aplikacje + Bolt, przez `openclaw/plugin-sdk/channel-runtime-context` + - Nie wysyłaj komunikatów o przekierowaniu należących do pluginu z natywnych handlerów zatwierdzeń; + core odpowiada teraz za komunikaty „dostarczono gdzie indziej” na podstawie rzeczywistych wyników dostarczenia + - Przy przekazywaniu `channelRuntime` do `createChannelManager(...)` podaj + rzeczywistą powierzchnię `createPluginRuntime().channel`. Częściowe stuby są odrzucane. + + Zobacz `/plugins/sdk-channel-plugins`, aby poznać bieżący układ + approval capability. + + + + + Jeśli Twój plugin używa `openclaw/plugin-sdk/windows-spawn`, nierozwiązane wrappery Windows + `.cmd`/`.bat` teraz domyślnie kończą się błędem, chyba że jawnie przekażesz `allowShellFallback: true`. ```typescript - // Przed + // Before const program = applyWindowsSpawnProgramPolicy({ candidate }); - // Po + // After const program = applyWindowsSpawnProgramPolicy({ candidate, - // Ustaw to tylko dla zaufanych wywołań zgodności, które celowo - // akceptują fallback pośredniczony przez powłokę. + // Only set this for trusted compatibility callers that intentionally + // accept shell-mediated fallback. allowShellFallback: true, }); ``` - Jeśli Twój kod wywołujący nie polega celowo na fallbacku powłoki, nie ustawiaj - `allowShellFallback` i zamiast tego obsłuż zgłoszony błąd. + Jeśli wywołujący nie polega celowo na zapasowym użyciu powłoki, nie ustawiaj + `allowShellFallback`, tylko obsłuż zgłaszany błąd. - Przeszukaj swoją wtyczkę pod kątem importów z jednej z tych przestarzałych powierzchni: + Przeszukaj plugin w poszukiwaniu importów z którejkolwiek z przestarzałych powierzchni: ```bash grep -r "plugin-sdk/compat" my-plugin/ @@ -108,36 +133,36 @@ Aktualne przykłady dołączonych dostawców: - - Każdy eksport ze starej powierzchni mapuje się na konkretną nowoczesną ścieżkę importu: + + Każdy eksport ze starej powierzchni odpowiada konkretnej nowoczesnej ścieżce importu: ```typescript - // Przed (przestarzała warstwa zgodności wstecznej) + // Before (deprecated backwards-compatibility layer) import { createChannelReplyPipeline, createPluginRuntimeStore, resolveControlCommandGate, } from "openclaw/plugin-sdk/compat"; - // Po (nowoczesne precyzyjne importy) + // After (modern focused imports) import { createChannelReplyPipeline } from "openclaw/plugin-sdk/channel-reply-pipeline"; import { createPluginRuntimeStore } from "openclaw/plugin-sdk/runtime-store"; import { resolveControlCommandGate } from "openclaw/plugin-sdk/command-auth"; ``` - W przypadku helperów po stronie hosta użyj wstrzykniętego runtime wtyczki zamiast importować je - bezpośrednio: + W przypadku pomocników po stronie hosta używaj wstrzykniętego runtime pluginu zamiast + bezpośredniego importu: ```typescript - // Przed (przestarzały most extension-api) + // Before (deprecated extension-api bridge) import { runEmbeddedPiAgent } from "openclaw/extension-api"; const result = await runEmbeddedPiAgent({ sessionId, prompt }); - // Po (wstrzyknięty runtime) + // After (injected runtime) const result = await api.runtime.agent.runEmbeddedPiAgent({ sessionId, prompt }); ``` - Ten sam wzorzec dotyczy innych helperów starszego mostu: + Ten sam wzorzec dotyczy innych starszych pomocników mostu: | Stary import | Nowoczesny odpowiednik | | --- | --- | @@ -147,7 +172,7 @@ Aktualne przykłady dołączonych dostawców: | `resolveThinkingDefault` | `api.runtime.agent.resolveThinkingDefault` | | `resolveAgentTimeoutMs` | `api.runtime.agent.resolveAgentTimeoutMs` | | `ensureAgentWorkspace` | `api.runtime.agent.ensureAgentWorkspace` | - | helpery session store | `api.runtime.agent.session.*` | + | pomocniki magazynu sesji | `api.runtime.agent.session.*` | @@ -161,200 +186,205 @@ Aktualne przykłady dołączonych dostawców: ## Dokumentacja ścieżek importu - - | Ścieżka importu | Przeznaczenie | Kluczowe eksporty | + + | Import path | Cel | Kluczowe eksporty | | --- | --- | --- | - | `plugin-sdk/plugin-entry` | Kanoniczny helper punktu wejścia wtyczki | `definePluginEntry` | - | `plugin-sdk/core` | Starszy parasolowy re-eksport dla definicji/builderów punktów wejścia kanału | `defineChannelPluginEntry`, `createChatChannelPlugin` | - | `plugin-sdk/config-schema` | Eksport schematu głównej konfiguracji | `OpenClawSchema` | - | `plugin-sdk/provider-entry` | Helper punktu wejścia pojedynczego dostawcy | `defineSingleProviderPluginEntry` | - | `plugin-sdk/channel-core` | Precyzyjne definicje i buildery punktów wejścia kanału | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` | - | `plugin-sdk/setup` | Wspólne helpery kreatora konfiguracji | Prompty allowlisty, buildery statusu konfiguracji | - | `plugin-sdk/setup-runtime` | Helpery runtime dla czasu konfiguracji | Bezpieczne importowo adaptery poprawek konfiguracji, helpery notatek wyszukiwania, `promptResolvedAllowFrom`, `splitSetupEntries`, delegowane proxy konfiguracji | - | `plugin-sdk/setup-adapter-runtime` | Helpery adaptera konfiguracji | `createEnvPatchedAccountSetupAdapter` | - | `plugin-sdk/setup-tools` | Helpery narzędzi konfiguracji | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` | - | `plugin-sdk/account-core` | Helpery wielu kont | Helpery listy kont/konfiguracji/bramkowania działań | - | `plugin-sdk/account-id` | Helpery identyfikatora konta | `DEFAULT_ACCOUNT_ID`, normalizacja identyfikatora konta | - | `plugin-sdk/account-resolution` | Helpery wyszukiwania konta | Helpery wyszukiwania konta + fallbacku do wartości domyślnej | - | `plugin-sdk/account-helpers` | Wąskie helpery konta | Helpery listy kont/działań na koncie | - | `plugin-sdk/channel-setup` | Adaptery kreatora konfiguracji | `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, `createOptionalChannelSetupWizard`, a także `DEFAULT_ACCOUNT_ID`, `createTopLevelChannelDmPolicy`, `setSetupChannelEnabled`, `splitSetupEntries` | + | `plugin-sdk/plugin-entry` | Kanoniczny pomocnik punktu wejścia pluginu | `definePluginEntry` | + | `plugin-sdk/core` | Starszy zbiorczy reeksport dla definicji/builderów punktów wejścia kanałów | `defineChannelPluginEntry`, `createChatChannelPlugin` | + | `plugin-sdk/config-schema` | Eksport głównego schematu konfiguracji | `OpenClawSchema` | + | `plugin-sdk/provider-entry` | Pomocnik punktu wejścia pojedynczego dostawcy | `defineSingleProviderPluginEntry` | + | `plugin-sdk/channel-core` | Ukierunkowane definicje i buildery punktów wejścia kanałów | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` | + | `plugin-sdk/setup` | Współdzielone pomocniki kreatora konfiguracji | Prompty allowlist, buildery statusu konfiguracji | + | `plugin-sdk/setup-runtime` | Pomocniki runtime na etapie konfiguracji | Bezpieczne importowo adaptery łatek konfiguracji, pomocniki notatek lookup, `promptResolvedAllowFrom`, `splitSetupEntries`, delegowane proxy konfiguracji | + | `plugin-sdk/setup-adapter-runtime` | Pomocniki adaptera konfiguracji | `createEnvPatchedAccountSetupAdapter` | + | `plugin-sdk/setup-tools` | Pomocniki narzędzi konfiguracji | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` | + | `plugin-sdk/account-core` | Pomocniki dla wielu kont | Pomocniki list kont/konfiguracji/bram akcji | + | `plugin-sdk/account-id` | Pomocniki identyfikatorów kont | `DEFAULT_ACCOUNT_ID`, normalizacja identyfikatora konta | + | `plugin-sdk/account-resolution` | Pomocniki wyszukiwania kont | Wyszukiwanie konta + pomocniki zapasowego wyboru domyślnego | + | `plugin-sdk/account-helpers` | Wąskie pomocniki kont | Pomocniki list kont/akcji na kontach | + | `plugin-sdk/channel-setup` | Adaptery kreatora konfiguracji | `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, `createOptionalChannelSetupWizard`, plus `DEFAULT_ACCOUNT_ID`, `createTopLevelChannelDmPolicy`, `setSetupChannelEnabled`, `splitSetupEntries` | | `plugin-sdk/channel-pairing` | Prymitywy parowania DM | `createChannelPairingController` | - | `plugin-sdk/channel-reply-pipeline` | Łączenie prefiksu odpowiedzi i typing | `createChannelReplyPipeline` | + | `plugin-sdk/channel-reply-pipeline` | Okablowanie prefiksu odpowiedzi + typing | `createChannelReplyPipeline` | | `plugin-sdk/channel-config-helpers` | Fabryki adapterów konfiguracji | `createHybridChannelConfigAdapter` | - | `plugin-sdk/channel-config-schema` | Buildery schematów konfiguracji | Typy schematów konfiguracji kanału | - | `plugin-sdk/telegram-command-config` | Helpery konfiguracji poleceń Telegram | Normalizacja nazw poleceń, przycinanie opisów, walidacja duplikatów/konfliktów | - | `plugin-sdk/channel-policy` | Rozstrzyganie polityki grup/DM | `resolveChannelGroupRequireMention` | + | `plugin-sdk/channel-config-schema` | Buildery schematów konfiguracji | Typy schematu konfiguracji kanału | + | `plugin-sdk/telegram-command-config` | Pomocniki konfiguracji poleceń Telegram | Normalizacja nazw poleceń, przycinanie opisów, walidacja duplikatów/konfliktów | + | `plugin-sdk/channel-policy` | Rozstrzyganie polityk grup/DM | `resolveChannelGroupRequireMention` | | `plugin-sdk/channel-lifecycle` | Śledzenie statusu konta | `createAccountStatusSink` | - | `plugin-sdk/inbound-envelope` | Helpery koperty wejściowej | Wspólne helpery routingu i budowania koperty | - | `plugin-sdk/inbound-reply-dispatch` | Helpery odpowiedzi wejściowej | Wspólne helpery zapisu i dyspozycji | - | `plugin-sdk/messaging-targets` | Parsowanie celów wiadomości | Helpery parsowania/dopasowywania celów | - | `plugin-sdk/outbound-media` | Helpery mediów wychodzących | Wspólne ładowanie mediów wychodzących | - | `plugin-sdk/outbound-runtime` | Helpery runtime dla ruchu wychodzącego | Helpery tożsamości wychodzącej/delegatów wysyłki | - | `plugin-sdk/thread-bindings-runtime` | Helpery powiązań wątków | Helpery cyklu życia powiązań wątków i adapterów | - | `plugin-sdk/agent-media-payload` | Starsze helpery ładunku mediów | Builder ładunku mediów agenta dla starszych układów pól | - | `plugin-sdk/channel-runtime` | Przestarzały shim zgodności | Tylko starsze narzędzia runtime kanału | + | `plugin-sdk/inbound-envelope` | Pomocniki kopert wejściowych | Współdzielone pomocniki routingu + buildera kopert | + | `plugin-sdk/inbound-reply-dispatch` | Pomocniki odpowiedzi wejściowych | Współdzielone pomocniki zapisu i dispatchu | + | `plugin-sdk/messaging-targets` | Parsowanie celów wiadomości | Pomocniki parsowania/dopasowywania celów | + | `plugin-sdk/outbound-media` | Pomocniki mediów wychodzących | Współdzielone ładowanie mediów wychodzących | + | `plugin-sdk/outbound-runtime` | Pomocniki runtime wychodzącego | Pomocniki tożsamości wychodzącej/delegatów wysyłki | + | `plugin-sdk/thread-bindings-runtime` | Pomocniki powiązań wątków | Cykl życia powiązań wątków i pomocniki adapterów | + | `plugin-sdk/agent-media-payload` | Starsze pomocniki payloadów mediów | Builder payloadu mediów agenta dla starszych układów pól | + | `plugin-sdk/channel-runtime` | Przestarzały shim zgodności | Tylko starsze narzędzia channel runtime | | `plugin-sdk/channel-send-result` | Typy wyników wysyłki | Typy wyników odpowiedzi | - | `plugin-sdk/runtime-store` | Trwałe przechowywanie wtyczki | `createPluginRuntimeStore` | - | `plugin-sdk/runtime` | Szerokie helpery runtime | Helpery runtime/logowania/kopii zapasowych/instalacji wtyczek | - | `plugin-sdk/runtime-env` | Wąskie helpery środowiska runtime | Logger/środowisko runtime, timeout, retry i helpery backoff | - | `plugin-sdk/plugin-runtime` | Wspólne helpery runtime wtyczek | Helpery poleceń/hooków/http/interaktywne dla wtyczek | - | `plugin-sdk/hook-runtime` | Helpery pipeline hooków | Wspólne helpery pipeline webhooków/wewnętrznych hooków | - | `plugin-sdk/lazy-runtime` | Helpery leniwego runtime | `createLazyRuntimeModule`, `createLazyRuntimeMethod`, `createLazyRuntimeMethodBinder`, `createLazyRuntimeNamedExport`, `createLazyRuntimeSurface` | - | `plugin-sdk/process-runtime` | Helpery procesów | Wspólne helpery exec | - | `plugin-sdk/cli-runtime` | Helpery runtime CLI | Formatowanie poleceń, oczekiwania, helpery wersji | - | `plugin-sdk/gateway-runtime` | Helpery Gateway | Klient Gateway i helpery poprawek statusu kanałów | - | `plugin-sdk/config-runtime` | Helpery konfiguracji | Helpery ładowania/zapisu konfiguracji | - | `plugin-sdk/telegram-command-config` | Helpery poleceń Telegram | Stabilne w fallbacku helpery walidacji poleceń Telegram, gdy dołączona powierzchnia kontraktu Telegram jest niedostępna | - | `plugin-sdk/approval-runtime` | Helpery promptów zatwierdzania | Ładunek zatwierdzania exec/wtyczki, helpery capability/profili zatwierdzania, natywny routing/runtime zatwierdzania | - | `plugin-sdk/approval-auth-runtime` | Helpery uwierzytelniania zatwierdzania | Rozstrzyganie zatwierdzającego, uwierzytelnianie akcji w tym samym czacie | - | `plugin-sdk/approval-client-runtime` | Helpery klienta zatwierdzania | Natywne helpery profili/filtrów zatwierdzania exec | - | `plugin-sdk/approval-delivery-runtime` | Helpery dostarczania zatwierdzania | Natywne adaptery capability/dostarczania zatwierdzania | - | `plugin-sdk/approval-native-runtime` | Helpery celu zatwierdzania | Natywne helpery celu zatwierdzania/powiązania konta | - | `plugin-sdk/approval-reply-runtime` | Helpery odpowiedzi zatwierdzania | Helpery ładunku odpowiedzi zatwierdzania exec/wtyczki | - | `plugin-sdk/security-runtime` | Helpery bezpieczeństwa | Wspólne helpery zaufania, bramkowania DM, treści zewnętrznych i zbierania sekretów | - | `plugin-sdk/ssrf-policy` | Helpery polityki SSRF | Helpery allowlisty hostów i polityki sieci prywatnych | - | `plugin-sdk/ssrf-runtime` | Helpery runtime SSRF | Helpery pinned-dispatcher, guarded fetch i polityki SSRF | - | `plugin-sdk/collection-runtime` | Helpery ograniczonego cache | `pruneMapToMaxSize` | - | `plugin-sdk/diagnostic-runtime` | Helpery bramkowania diagnostyki | `isDiagnosticFlagEnabled`, `isDiagnosticsEnabled` | - | `plugin-sdk/error-runtime` | Helpery formatowania błędów | `formatUncaughtError`, `isApprovalNotFoundError`, helpery grafu błędów | - | `plugin-sdk/fetch-runtime` | Helpery opakowanego fetch/proxy | `resolveFetch`, helpery proxy | - | `plugin-sdk/host-runtime` | Helpery normalizacji hosta | `normalizeHostname`, `normalizeScpRemoteHost` | - | `plugin-sdk/retry-runtime` | Helpery retry | `RetryConfig`, `retryAsync`, wykonawcy polityk | - | `plugin-sdk/allow-from` | Formatowanie allowlisty | `formatAllowFromLowercase` | - | `plugin-sdk/allowlist-resolution` | Mapowanie wejść allowlisty | `mapAllowlistResolutionInputs` | - | `plugin-sdk/command-auth` | Bramkowanie poleceń i helpery powierzchni poleceń | `resolveControlCommandGate`, helpery autoryzacji nadawcy, helpery rejestru poleceń | - | `plugin-sdk/secret-input` | Parsowanie wejścia sekretów | Helpery wejścia sekretów | - | `plugin-sdk/webhook-ingress` | Helpery żądań webhook | Narzędzia celu webhooka | - | `plugin-sdk/webhook-request-guards` | Helpery strażników treści webhooka | Helpery odczytu/limitów treści żądania | - | `plugin-sdk/reply-runtime` | Wspólny runtime odpowiedzi | Dyspozycja wejściowa, heartbeat, planer odpowiedzi, chunking | - | `plugin-sdk/reply-dispatch-runtime` | Wąskie helpery dyspozycji odpowiedzi | Helpery finalizacji i dyspozycji dostawcy | - | `plugin-sdk/reply-history` | Helpery historii odpowiedzi | `buildHistoryContext`, `buildPendingHistoryContextFromMap`, `recordPendingHistoryEntry`, `clearHistoryEntriesIfEnabled` | + | `plugin-sdk/runtime-store` | Trwałe przechowywanie pluginu | `createPluginRuntimeStore` | + | `plugin-sdk/runtime` | Szerokie pomocniki runtime | Pomocniki runtime/logowania/kopii zapasowych/instalacji pluginów | + | `plugin-sdk/runtime-env` | Wąskie pomocniki środowiska runtime | Logger/runtime env, timeout, retry i pomocniki backoff | + | `plugin-sdk/plugin-runtime` | Współdzielone pomocniki runtime pluginów | Pomocniki poleceń/hooków/http/interakcji pluginów | + | `plugin-sdk/hook-runtime` | Pomocniki potoku hooków | Współdzielone pomocniki potoku webhooków/wewnętrznych hooków | + | `plugin-sdk/lazy-runtime` | Pomocniki leniwego runtime | `createLazyRuntimeModule`, `createLazyRuntimeMethod`, `createLazyRuntimeMethodBinder`, `createLazyRuntimeNamedExport`, `createLazyRuntimeSurface` | + | `plugin-sdk/process-runtime` | Pomocniki procesów | Współdzielone pomocniki exec | + | `plugin-sdk/cli-runtime` | Pomocniki runtime CLI | Formatowanie poleceń, oczekiwania, pomocniki wersji | + | `plugin-sdk/gateway-runtime` | Pomocniki gateway | Klient gateway i pomocniki łat statusu kanału | + | `plugin-sdk/config-runtime` | Pomocniki konfiguracji | Pomocniki ładowania/zapisu konfiguracji | + | `plugin-sdk/telegram-command-config` | Pomocniki poleceń Telegram | Pomocniki walidacji poleceń Telegram stabilne jako fallback, gdy powierzchnia kontraktu dołączonego Telegram jest niedostępna | + | `plugin-sdk/approval-runtime` | Pomocniki promptów zatwierdzeń | Payload exec/plugin approval, pomocniki approval capability/profile, natywne pomocniki routingu/runtime zatwierdzeń | + | `plugin-sdk/approval-auth-runtime` | Pomocniki auth zatwierdzeń | Rozstrzyganie osoby zatwierdzającej, uwierzytelnianie akcji w tym samym czacie | + | `plugin-sdk/approval-client-runtime` | Pomocniki klienta zatwierdzeń | Natywne pomocniki profili/filtrów zatwierdzeń exec | + | `plugin-sdk/approval-delivery-runtime` | Pomocniki dostarczania zatwierdzeń | Adaptery natywnych approval capability/delivery | + | `plugin-sdk/approval-gateway-runtime` | Pomocniki gateway zatwierdzeń | Współdzielony pomocnik rozstrzygania approval gateway | + | `plugin-sdk/approval-handler-adapter-runtime` | Pomocniki adaptera zatwierdzeń | Lekkie pomocniki ładowania natywnych adapterów zatwierdzeń dla gorących punktów wejścia kanałów | + | `plugin-sdk/approval-handler-runtime` | Pomocniki handlerów zatwierdzeń | Szersze pomocniki runtime handlerów zatwierdzeń; preferuj węższe warstwy adapter/gateway, gdy wystarczą | + | `plugin-sdk/approval-native-runtime` | Pomocniki celów zatwierdzeń | Pomocniki natywnych powiązań celu/konta zatwierdzeń | + | `plugin-sdk/approval-reply-runtime` | Pomocniki odpowiedzi zatwierdzeń | Pomocniki payloadów odpowiedzi exec/plugin approval | + | `plugin-sdk/channel-runtime-context` | Pomocniki channel runtime-context | Ogólne pomocniki register/get/watch dla channel runtime-context | + | `plugin-sdk/security-runtime` | Pomocniki bezpieczeństwa | Współdzielone pomocniki trust, bramkowania DM, treści zewnętrznych i zbierania sekretów | + | `plugin-sdk/ssrf-policy` | Pomocniki polityki SSRF | Pomocniki allowlist hostów i polityki sieci prywatnych | + | `plugin-sdk/ssrf-runtime` | Pomocniki runtime SSRF | Pinned-dispatcher, guarded fetch, pomocniki polityki SSRF | + | `plugin-sdk/collection-runtime` | Pomocniki ograniczonej pamięci podręcznej | `pruneMapToMaxSize` | + | `plugin-sdk/diagnostic-runtime` | Pomocniki bramkowania diagnostyki | `isDiagnosticFlagEnabled`, `isDiagnosticsEnabled` | + | `plugin-sdk/error-runtime` | Pomocniki formatowania błędów | `formatUncaughtError`, `isApprovalNotFoundError`, pomocniki grafu błędów | + | `plugin-sdk/fetch-runtime` | Pomocniki opakowanego fetch/proxy | `resolveFetch`, pomocniki proxy | + | `plugin-sdk/host-runtime` | Pomocniki normalizacji hosta | `normalizeHostname`, `normalizeScpRemoteHost` | + | `plugin-sdk/retry-runtime` | Pomocniki retry | `RetryConfig`, `retryAsync`, uruchamiacze polityk | + | `plugin-sdk/allow-from` | Formatowanie allowlist | `formatAllowFromLowercase` | + | `plugin-sdk/allowlist-resolution` | Mapowanie wejść allowlist | `mapAllowlistResolutionInputs` | + | `plugin-sdk/command-auth` | Bramkowanie poleceń i pomocniki powierzchni poleceń | `resolveControlCommandGate`, pomocniki autoryzacji nadawcy, pomocniki rejestru poleceń | + | `plugin-sdk/secret-input` | Parsowanie tajnych danych wejściowych | Pomocniki secret input | + | `plugin-sdk/webhook-ingress` | Pomocniki żądań webhooków | Narzędzia celu webhooka | + | `plugin-sdk/webhook-request-guards` | Pomocniki guardów żądań webhooków | Pomocniki odczytu/limitowania treści żądań | + | `plugin-sdk/reply-runtime` | Współdzielony runtime odpowiedzi | Inbound dispatch, heartbeat, planner odpowiedzi, chunking | + | `plugin-sdk/reply-dispatch-runtime` | Wąskie pomocniki dispatchu odpowiedzi | Finalizacja + pomocniki dispatchu dostawcy | + | `plugin-sdk/reply-history` | Pomocniki historii odpowiedzi | `buildHistoryContext`, `buildPendingHistoryContextFromMap`, `recordPendingHistoryEntry`, `clearHistoryEntriesIfEnabled` | | `plugin-sdk/reply-reference` | Planowanie referencji odpowiedzi | `createReplyReferencePlanner` | - | `plugin-sdk/reply-chunking` | Helpery chunków odpowiedzi | Helpery dzielenia tekstu/Markdown | - | `plugin-sdk/session-store-runtime` | Helpery session store | Helpery ścieżki store i updated-at | - | `plugin-sdk/state-paths` | Helpery ścieżek stanu | Helpery katalogów stanu i OAuth | - | `plugin-sdk/routing` | Helpery routingu/kluczy sesji | `resolveAgentRoute`, `buildAgentSessionKey`, `resolveDefaultAgentBoundAccountId`, helpery normalizacji klucza sesji | - | `plugin-sdk/status-helpers` | Helpery statusu kanałów | Buildery podsumowania statusu kanału/konta, domyślne wartości stanu runtime, helpery metadanych problemów | - | `plugin-sdk/target-resolver-runtime` | Helpery rozstrzygania celu | Wspólne helpery rozstrzygania celu | - | `plugin-sdk/string-normalization-runtime` | Helpery normalizacji ciągów | Helpery normalizacji slugów/ciągów | - | `plugin-sdk/request-url` | Helpery URL żądania | Wyodrębnianie tekstowych URL-i z wejść podobnych do żądania | - | `plugin-sdk/run-command` | Helpery poleceń z pomiarem czasu | Runner poleceń z normalizowanym stdout/stderr | - | `plugin-sdk/param-readers` | Odczytywacze parametrów | Typowe odczytywacze parametrów narzędzi/CLI | - | `plugin-sdk/tool-send` | Ekstrakcja wysyłki narzędzia | Wyodrębnianie kanonicznych pól celu wysyłki z argumentów narzędzia | - | `plugin-sdk/temp-path` | Helpery ścieżek tymczasowych | Wspólne helpery ścieżek tymczasowego pobierania | - | `plugin-sdk/logging-core` | Helpery logowania | Logger podsystemu i helpery redakcji | - | `plugin-sdk/markdown-table-runtime` | Helpery tabel Markdown | Helpery trybu tabel Markdown | - | `plugin-sdk/reply-payload` | Typy ładunku odpowiedzi | Typy ładunku odpowiedzi | - | `plugin-sdk/provider-setup` | Kuratorowane helpery konfiguracji lokalnego/self-hosted dostawcy | Helpery wykrywania/konfiguracji self-hosted dostawcy | - | `plugin-sdk/self-hosted-provider-setup` | Precyzyjne helpery konfiguracji self-hosted dostawców zgodnych z OpenAI | Te same helpery wykrywania/konfiguracji self-hosted dostawcy | - | `plugin-sdk/provider-auth-runtime` | Helpery runtime uwierzytelniania dostawcy | Helpery rozstrzygania kluczy API w runtime | - | `plugin-sdk/provider-auth-api-key` | Helpery konfiguracji klucza API dostawcy | Helpery onboardingu/zapisu profilu dla kluczy API | - | `plugin-sdk/provider-auth-result` | Helpery wyniku uwierzytelniania dostawcy | Standardowy builder wyniku uwierzytelniania OAuth | - | `plugin-sdk/provider-auth-login` | Helpery interaktywnego logowania dostawcy | Wspólne helpery interaktywnego logowania | - | `plugin-sdk/provider-env-vars` | Helpery zmiennych środowiskowych dostawcy | Helpery wyszukiwania zmiennych środowiskowych uwierzytelniania dostawcy | - | `plugin-sdk/provider-model-shared` | Wspólne helpery modeli/replay dostawców | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`, wspólne buildery polityki replay, helpery punktów końcowych dostawcy i helpery normalizacji identyfikatorów modeli | - | `plugin-sdk/provider-catalog-shared` | Wspólne helpery katalogu dostawcy | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat` | - | `plugin-sdk/provider-onboard` | Poprawki onboardingu dostawcy | Helpery konfiguracji onboardingu | - | `plugin-sdk/provider-http` | Helpery HTTP dostawcy | Generyczne helpery HTTP/zdolności punktów końcowych dostawcy | - | `plugin-sdk/provider-web-fetch` | Helpery web-fetch dostawcy | Helpery rejestracji/cache dostawcy web-fetch | - | `plugin-sdk/provider-web-search-contract` | Helpery kontraktu web-search dostawcy | Wąskie helpery kontraktu konfiguracji/poświadczeń web-search, takie jak `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig` oraz zakresowane settery/gettery poświadczeń | - | `plugin-sdk/provider-web-search` | Helpery web-search dostawcy | Helpery rejestracji/cache/runtime dostawcy web-search | - | `plugin-sdk/provider-tools` | Helpery zgodności narzędzi/schematów dostawcy | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, czyszczenie schematów Gemini + diagnostyka oraz helpery zgodności xAI, takie jak `resolveXaiModelCompatPatch` / `applyXaiModelCompat` | - | `plugin-sdk/provider-usage` | Helpery użycia dostawcy | `fetchClaudeUsage`, `fetchGeminiUsage`, `fetchGithubCopilotUsage` i inne helpery użycia dostawcy | - | `plugin-sdk/provider-stream` | Helpery wrapperów strumieni dostawcy | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`, typy wrapperów strumieni oraz wspólne helpery wrapperów Anthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot | - | `plugin-sdk/keyed-async-queue` | Uporządkowana kolejka asynchroniczna | `KeyedAsyncQueue` | - | `plugin-sdk/media-runtime` | Wspólne helpery mediów | Helpery pobierania/transformacji/przechowywania mediów oraz buildery ładunków mediów | - | `plugin-sdk/media-generation-runtime` | Wspólne helpery generowania mediów | Wspólne helpery failover, wybór kandydatów i komunikaty o brakującym modelu dla generowania obrazów/wideo/muzyki | - | `plugin-sdk/media-understanding` | Helpery rozumienia mediów | Typy dostawców rozumienia mediów oraz eksporty helperów obrazów/audio dla dostawców | - | `plugin-sdk/text-runtime` | Wspólne helpery tekstu | Usuwanie tekstu widocznego dla asystenta, helpery renderowania/chunkingu/tabel Markdown, helpery redakcji, helpery znaczników dyrektyw, narzędzia bezpiecznego tekstu i powiązane helpery tekstu/logowania | - | `plugin-sdk/text-chunking` | Helpery chunkingu tekstu | Helper dzielenia tekstu wychodzącego na chunki | - | `plugin-sdk/speech` | Helpery mowy | Typy dostawców mowy oraz eksporty helperów dyrektyw, rejestru i walidacji dla dostawców | - | `plugin-sdk/speech-core` | Wspólny rdzeń mowy | Typy dostawców mowy, rejestr, dyrektywy, normalizacja | - | `plugin-sdk/realtime-transcription` | Helpery transkrypcji realtime | Typy dostawców i helpery rejestru | - | `plugin-sdk/realtime-voice` | Helpery głosu realtime | Typy dostawców i helpery rejestru | - | `plugin-sdk/image-generation-core` | Wspólny rdzeń generowania obrazów | Typy generowania obrazów, failover, uwierzytelnianie i helpery rejestru | - | `plugin-sdk/music-generation` | Helpery generowania muzyki | Typy dostawców/żądań/wyników generowania muzyki | - | `plugin-sdk/music-generation-core` | Wspólny rdzeń generowania muzyki | Typy generowania muzyki, helpery failover, wyszukiwanie dostawcy i parsowanie model-ref | - | `plugin-sdk/video-generation` | Helpery generowania wideo | Typy dostawców/żądań/wyników generowania wideo | - | `plugin-sdk/video-generation-core` | Wspólny rdzeń generowania wideo | Typy generowania wideo, helpery failover, wyszukiwanie dostawcy i parsowanie model-ref | - | `plugin-sdk/interactive-runtime` | Helpery odpowiedzi interaktywnych | Normalizacja/redukcja ładunku odpowiedzi interaktywnych | + | `plugin-sdk/reply-chunking` | Pomocniki dzielenia odpowiedzi | Pomocniki dzielenia tekstu/markdown | + | `plugin-sdk/session-store-runtime` | Pomocniki magazynu sesji | Ścieżka magazynu + pomocniki updated-at | + | `plugin-sdk/state-paths` | Pomocniki ścieżek stanu | Pomocniki katalogów stanu i OAuth | + | `plugin-sdk/routing` | Pomocniki routingu/kluczy sesji | `resolveAgentRoute`, `buildAgentSessionKey`, `resolveDefaultAgentBoundAccountId`, pomocniki normalizacji kluczy sesji | + | `plugin-sdk/status-helpers` | Pomocniki statusu kanału | Buildery podsumowań statusu kanału/konta, domyślne stany runtime, pomocniki metadanych problemów | + | `plugin-sdk/target-resolver-runtime` | Pomocniki rozstrzygania celów | Współdzielone pomocniki target resolver | + | `plugin-sdk/string-normalization-runtime` | Pomocniki normalizacji tekstu | Pomocniki normalizacji slugów/ciągów | + | `plugin-sdk/request-url` | Pomocniki URL żądań | Wyodrębnianie URL jako ciągów z danych wejściowych podobnych do żądania | + | `plugin-sdk/run-command` | Pomocniki poleceń z pomiarem czasu | Runner poleceń z normalizowanym stdout/stderr | + | `plugin-sdk/param-readers` | Czytniki parametrów | Typowe czytniki parametrów narzędzi/CLI | + | `plugin-sdk/tool-send` | Wyodrębnianie wysyłki z narzędzia | Wyodrębnianie kanonicznych pól celu wysyłki z argumentów narzędzia | + | `plugin-sdk/temp-path` | Pomocniki ścieżek tymczasowych | Współdzielone pomocniki ścieżek tymczasowych pobrań | + | `plugin-sdk/logging-core` | Pomocniki logowania | Logger podsystemu i pomocniki redakcji | + | `plugin-sdk/markdown-table-runtime` | Pomocniki tabel markdown | Pomocniki trybów tabel markdown | + | `plugin-sdk/reply-payload` | Typy payloadów odpowiedzi | Typy payloadów odpowiedzi wiadomości | + | `plugin-sdk/provider-setup` | Dobrane pomocniki konfiguracji lokalnych/samohostowanych dostawców | Pomocniki wykrywania/konfiguracji samohostowanych dostawców | + | `plugin-sdk/self-hosted-provider-setup` | Ukierunkowane pomocniki konfiguracji samohostowanych dostawców zgodnych z OpenAI | Te same pomocniki wykrywania/konfiguracji samohostowanych dostawców | + | `plugin-sdk/provider-auth-runtime` | Pomocniki auth runtime dostawców | Pomocniki rozstrzygania kluczy API runtime | + | `plugin-sdk/provider-auth-api-key` | Pomocniki konfiguracji kluczy API dostawców | Pomocniki onboardingu/zapisu profilu dla kluczy API | + | `plugin-sdk/provider-auth-result` | Pomocniki wyników auth dostawców | Standardowy builder wyniku auth OAuth | + | `plugin-sdk/provider-auth-login` | Pomocniki interaktywnego logowania dostawców | Współdzielone pomocniki interaktywnego logowania | + | `plugin-sdk/provider-env-vars` | Pomocniki zmiennych środowiskowych dostawców | Pomocniki wyszukiwania zmiennych środowiskowych auth dostawców | + | `plugin-sdk/provider-model-shared` | Współdzielone pomocniki modeli/replay dostawców | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`, współdzielone buildery polityk replay, pomocniki endpointów dostawców i normalizacji identyfikatorów modeli | + | `plugin-sdk/provider-catalog-shared` | Współdzielone pomocniki katalogów dostawców | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat` | + | `plugin-sdk/provider-onboard` | Łatki onboardingu dostawców | Pomocniki konfiguracji onboardingu | + | `plugin-sdk/provider-http` | Pomocniki HTTP dostawców | Ogólne pomocniki HTTP/możliwości endpointów dostawców | + | `plugin-sdk/provider-web-fetch` | Pomocniki web-fetch dostawców | Pomocniki rejestracji/cache dostawców web-fetch | + | `plugin-sdk/provider-web-search-contract` | Pomocniki kontraktu web-search dostawców | Wąskie pomocniki kontraktu konfiguracji/poświadczeń web-search, takie jak `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig` oraz funkcje ustawiania/pobierania poświadczeń o ograniczonym zakresie | + | `plugin-sdk/provider-web-search` | Pomocniki web-search dostawców | Pomocniki rejestracji/cache/runtime dostawców web-search | + | `plugin-sdk/provider-tools` | Pomocniki zgodności narzędzi/schematów dostawców | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, czyszczenie schematów Gemini + diagnostyka oraz pomocniki zgodności xAI, takie jak `resolveXaiModelCompatPatch` / `applyXaiModelCompat` | + | `plugin-sdk/provider-usage` | Pomocniki użycia dostawców | `fetchClaudeUsage`, `fetchGeminiUsage`, `fetchGithubCopilotUsage` i inne pomocniki użycia dostawców | + | `plugin-sdk/provider-stream` | Pomocniki wrapperów strumieni dostawców | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`, typy wrapperów strumieni oraz współdzielone pomocniki wrapperów Anthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot | + | `plugin-sdk/keyed-async-queue` | Uporządkowana kolejka async | `KeyedAsyncQueue` | + | `plugin-sdk/media-runtime` | Współdzielone pomocniki mediów | Pomocniki pobierania/przekształcania/przechowywania mediów oraz buildery payloadów mediów | + | `plugin-sdk/media-generation-runtime` | Współdzielone pomocniki generowania mediów | Współdzielone pomocniki failover, wyboru kandydatów i komunikatów o braku modeli dla generowania obrazów/wideo/muzyki | + | `plugin-sdk/media-understanding` | Pomocniki media-understanding | Typy dostawców media understanding oraz eksporty pomocników obrazów/audio dla dostawców | + | `plugin-sdk/text-runtime` | Współdzielone pomocniki tekstu | Usuwanie tekstu widocznego dla asystenta, pomocniki renderowania/dzielenia/tabel markdown, redakcji, tagów dyrektyw, bezpiecznego tekstu oraz powiązane pomocniki tekstowe/logowania | + | `plugin-sdk/text-chunking` | Pomocniki dzielenia tekstu | Pomocnik dzielenia tekstu wychodzącego | + | `plugin-sdk/speech` | Pomocniki speech | Typy dostawców speech oraz eksporty pomocników dyrektyw, rejestru i walidacji dla dostawców | + | `plugin-sdk/speech-core` | Współdzielony rdzeń speech | Typy dostawców speech, rejestr, dyrektywy, normalizacja | + | `plugin-sdk/realtime-transcription` | Pomocniki transkrypcji realtime | Typy dostawców i pomocniki rejestru | + | `plugin-sdk/realtime-voice` | Pomocniki głosu realtime | Typy dostawców i pomocniki rejestru | + | `plugin-sdk/image-generation-core` | Współdzielony rdzeń generowania obrazów | Pomocniki typów, failover, auth i rejestru generowania obrazów | + | `plugin-sdk/music-generation` | Pomocniki generowania muzyki | Typy dostawców/żądań/wyników generowania muzyki | + | `plugin-sdk/music-generation-core` | Współdzielony rdzeń generowania muzyki | Pomocniki typów, failover, wyszukiwania dostawców i parsowania model-ref dla generowania muzyki | + | `plugin-sdk/video-generation` | Pomocniki generowania wideo | Typy dostawców/żądań/wyników generowania wideo | + | `plugin-sdk/video-generation-core` | Współdzielony rdzeń generowania wideo | Pomocniki typów, failover, wyszukiwania dostawców i parsowania model-ref dla generowania wideo | + | `plugin-sdk/interactive-runtime` | Pomocniki odpowiedzi interaktywnych | Normalizacja/redukcja payloadów odpowiedzi interaktywnych | | `plugin-sdk/channel-config-primitives` | Prymitywy konfiguracji kanału | Wąskie prymitywy channel config-schema | - | `plugin-sdk/channel-config-writes` | Helpery zapisu konfiguracji kanału | Helpery autoryzacji zapisu konfiguracji kanału | - | `plugin-sdk/channel-plugin-common` | Wspólne preludium kanału | Wspólne eksporty preludium wtyczki kanału | - | `plugin-sdk/channel-status` | Helpery statusu kanału | Wspólne helpery snapshotów/podsumowań statusu kanału | - | `plugin-sdk/allowlist-config-edit` | Helpery konfiguracji allowlisty | Helpery edycji/odczytu konfiguracji allowlisty | - | `plugin-sdk/group-access` | Helpery dostępu grupowego | Wspólne helpery decyzji dostępu grupowego | - | `plugin-sdk/direct-dm` | Helpery direct-DM | Wspólne helpery uwierzytelniania/ochrony direct-DM | - | `plugin-sdk/extension-shared` | Wspólne helpery rozszerzeń | Prymitywy pomocnicze dla pasywnego kanału/statusu i ambient proxy | - | `plugin-sdk/webhook-targets` | Helpery celów webhook | Rejestr celów webhook i helpery instalacji tras | - | `plugin-sdk/webhook-path` | Helpery ścieżek webhook | Helpery normalizacji ścieżek webhook | - | `plugin-sdk/web-media` | Wspólne helpery mediów web | Helpery ładowania zdalnych/lokalnych mediów | - | `plugin-sdk/zod` | Re-eksport Zod | Re-eksportowany `zod` dla użytkowników plugin SDK | - | `plugin-sdk/memory-core` | Dołączone helpery memory-core | Powierzchnia helperów menedżera pamięci/konfiguracji/plików/CLI | + | `plugin-sdk/channel-config-writes` | Pomocniki zapisu konfiguracji kanału | Pomocniki autoryzacji zapisu konfiguracji kanału | + | `plugin-sdk/channel-plugin-common` | Wspólny prelude kanału | Eksporty wspólnego preludium pluginu kanału | + | `plugin-sdk/channel-status` | Pomocniki statusu kanału | Współdzielone pomocniki snapshotów/podsumowań statusu kanału | + | `plugin-sdk/allowlist-config-edit` | Pomocniki konfiguracji allowlist | Pomocniki edycji/odczytu konfiguracji allowlist | + | `plugin-sdk/group-access` | Pomocniki dostępu grupowego | Współdzielone pomocniki decyzji o dostępie grupowym | + | `plugin-sdk/direct-dm` | Pomocniki bezpośrednich DM | Współdzielone pomocniki auth/guard bezpośrednich DM | + | `plugin-sdk/extension-shared` | Współdzielone pomocniki rozszerzeń | Prymitywy pomocników pasywnego kanału/statusu i ambient proxy | + | `plugin-sdk/webhook-targets` | Pomocniki celów webhooków | Rejestr celów webhooków i pomocniki instalacji tras | + | `plugin-sdk/webhook-path` | Pomocniki ścieżek webhooków | Pomocniki normalizacji ścieżek webhooków | + | `plugin-sdk/web-media` | Współdzielone pomocniki web media | Pomocniki ładowania zdalnych/lokalnych mediów | + | `plugin-sdk/zod` | Reeksport Zod | Reeksport `zod` dla użytkowników Plugin SDK | + | `plugin-sdk/memory-core` | Dołączone pomocniki memory-core | Powierzchnia pomocników menedżera/konfiguracji/plików/CLI pamięci | | `plugin-sdk/memory-core-engine-runtime` | Fasada runtime silnika pamięci | Fasada runtime indeksu/wyszukiwania pamięci | - | `plugin-sdk/memory-core-host-engine-foundation` | Silnik podstawowy hosta pamięci | Eksporty silnika podstawowego hosta pamięci | + | `plugin-sdk/memory-core-host-engine-foundation` | Bazowy silnik hosta pamięci | Eksporty bazowego silnika hosta pamięci | | `plugin-sdk/memory-core-host-engine-embeddings` | Silnik embeddingów hosta pamięci | Eksporty silnika embeddingów hosta pamięci | | `plugin-sdk/memory-core-host-engine-qmd` | Silnik QMD hosta pamięci | Eksporty silnika QMD hosta pamięci | | `plugin-sdk/memory-core-host-engine-storage` | Silnik przechowywania hosta pamięci | Eksporty silnika przechowywania hosta pamięci | - | `plugin-sdk/memory-core-host-multimodal` | Multimodalne helpery hosta pamięci | Multimodalne helpery hosta pamięci | - | `plugin-sdk/memory-core-host-query` | Helpery zapytań hosta pamięci | Helpery zapytań hosta pamięci | - | `plugin-sdk/memory-core-host-secret` | Helpery sekretów hosta pamięci | Helpery sekretów hosta pamięci | - | `plugin-sdk/memory-core-host-events` | Helpery dziennika zdarzeń hosta pamięci | Helpery dziennika zdarzeń hosta pamięci | - | `plugin-sdk/memory-core-host-status` | Helpery statusu hosta pamięci | Helpery statusu hosta pamięci | - | `plugin-sdk/memory-core-host-runtime-cli` | Runtime CLI hosta pamięci | Helpery runtime CLI hosta pamięci | - | `plugin-sdk/memory-core-host-runtime-core` | Główny runtime hosta pamięci | Helpery głównego runtime hosta pamięci | - | `plugin-sdk/memory-core-host-runtime-files` | Helpery plików/runtime hosta pamięci | Helpery plików/runtime hosta pamięci | - | `plugin-sdk/memory-host-core` | Alias głównego runtime hosta pamięci | Neutralny wobec dostawcy alias helperów głównego runtime hosta pamięci | - | `plugin-sdk/memory-host-events` | Alias dziennika zdarzeń hosta pamięci | Neutralny wobec dostawcy alias helperów dziennika zdarzeń hosta pamięci | - | `plugin-sdk/memory-host-files` | Alias plików/runtime hosta pamięci | Neutralny wobec dostawcy alias helperów plików/runtime hosta pamięci | - | `plugin-sdk/memory-host-markdown` | Helpery zarządzanego Markdown | Wspólne helpery zarządzanego Markdown dla wtyczek związanych z pamięcią | + | `plugin-sdk/memory-core-host-multimodal` | Wielomodalne pomocniki hosta pamięci | Wielomodalne pomocniki hosta pamięci | + | `plugin-sdk/memory-core-host-query` | Pomocniki zapytań hosta pamięci | Pomocniki zapytań hosta pamięci | + | `plugin-sdk/memory-core-host-secret` | Pomocniki sekretów hosta pamięci | Pomocniki sekretów hosta pamięci | + | `plugin-sdk/memory-core-host-events` | Pomocniki dziennika zdarzeń hosta pamięci | Pomocniki dziennika zdarzeń hosta pamięci | + | `plugin-sdk/memory-core-host-status` | Pomocniki statusu hosta pamięci | Pomocniki statusu hosta pamięci | + | `plugin-sdk/memory-core-host-runtime-cli` | Runtime CLI hosta pamięci | Pomocniki runtime CLI hosta pamięci | + | `plugin-sdk/memory-core-host-runtime-core` | Runtime core hosta pamięci | Pomocniki runtime core hosta pamięci | + | `plugin-sdk/memory-core-host-runtime-files` | Pomocniki plików/runtime hosta pamięci | Pomocniki plików/runtime hosta pamięci | + | `plugin-sdk/memory-host-core` | Alias runtime core hosta pamięci | Neutralny względem dostawcy alias pomocników runtime core hosta pamięci | + | `plugin-sdk/memory-host-events` | Alias dziennika zdarzeń hosta pamięci | Neutralny względem dostawcy alias pomocników dziennika zdarzeń hosta pamięci | + | `plugin-sdk/memory-host-files` | Alias plików/runtime hosta pamięci | Neutralny względem dostawcy alias pomocników plików/runtime hosta pamięci | + | `plugin-sdk/memory-host-markdown` | Pomocniki zarządzanego markdown | Współdzielone pomocniki zarządzanego markdown dla pluginów powiązanych z pamięcią | | `plugin-sdk/memory-host-search` | Fasada aktywnego wyszukiwania pamięci | Leniwa fasada runtime menedżera wyszukiwania aktywnej pamięci | - | `plugin-sdk/memory-host-status` | Alias statusu hosta pamięci | Neutralny wobec dostawcy alias helperów statusu hosta pamięci | - | `plugin-sdk/memory-lancedb` | Dołączone helpery memory-lancedb | Powierzchnia helperów memory-lancedb | - | `plugin-sdk/testing` | Narzędzia testowe | Helpery testowe i mocki | + | `plugin-sdk/memory-host-status` | Alias statusu hosta pamięci | Neutralny względem dostawcy alias pomocników statusu hosta pamięci | + | `plugin-sdk/memory-lancedb` | Dołączone pomocniki memory-lancedb | Powierzchnia pomocników memory-lancedb | + | `plugin-sdk/testing` | Narzędzia testowe | Pomocniki testowe i mocki | -Ta tabela celowo obejmuje typowy podzbiór migracyjny, a nie pełną powierzchnię -SDK. Pełna lista ponad 200 punktów wejścia znajduje się w +Ta tabela celowo obejmuje wspólny podzbiór do migracji, a nie pełną powierzchnię SDK. +Pełna lista ponad 200 punktów wejścia znajduje się w `scripts/lib/plugin-sdk-entrypoints.json`. -Ta lista nadal obejmuje niektóre pomocnicze granice dołączonych wtyczek, takie jak +Ta lista nadal zawiera niektóre warstwy pomocnicze dołączonych pluginów, takie jak `plugin-sdk/feishu`, `plugin-sdk/feishu-setup`, `plugin-sdk/zalo`, -`plugin-sdk/zalo-setup` oraz `plugin-sdk/matrix*`. Pozostają one eksportowane na potrzeby -utrzymania i zgodności dołączonych wtyczek, ale są celowo pominięte w typowej tabeli migracyjnej -i nie są zalecanym celem dla nowego kodu wtyczek. +`plugin-sdk/zalo-setup` i `plugin-sdk/matrix*`. Nadal są one eksportowane dla +utrzymania zgodności i konserwacji dołączonych pluginów, ale celowo +pominięto je w tabeli najczęstszych migracji i nie są zalecanym celem dla +nowego kodu pluginów. -Ta sama zasada dotyczy innych rodzin dołączonych helperów, takich jak: +Ta sama zasada dotyczy innych rodzin dołączonych pomocników, takich jak: -- helpery obsługi przeglądarki: `plugin-sdk/browser-cdp`, `plugin-sdk/browser-config-runtime`, `plugin-sdk/browser-config-support`, `plugin-sdk/browser-control-auth`, `plugin-sdk/browser-node-runtime`, `plugin-sdk/browser-profiles`, `plugin-sdk/browser-security-runtime`, `plugin-sdk/browser-setup-tools`, `plugin-sdk/browser-support` +- pomocniki wsparcia przeglądarki: `plugin-sdk/browser-cdp`, `plugin-sdk/browser-config-runtime`, `plugin-sdk/browser-config-support`, `plugin-sdk/browser-control-auth`, `plugin-sdk/browser-node-runtime`, `plugin-sdk/browser-profiles`, `plugin-sdk/browser-security-runtime`, `plugin-sdk/browser-setup-tools`, `plugin-sdk/browser-support` - Matrix: `plugin-sdk/matrix*` - LINE: `plugin-sdk/line*` - IRC: `plugin-sdk/irc*` -- dołączone powierzchnie helperów/wtyczek, takie jak `plugin-sdk/googlechat`, +- dołączone powierzchnie pomocnicze/pluginów, takie jak `plugin-sdk/googlechat`, `plugin-sdk/zalouser`, `plugin-sdk/bluebubbles*`, `plugin-sdk/mattermost*`, `plugin-sdk/msteams`, `plugin-sdk/nextcloud-talk`, `plugin-sdk/nostr`, `plugin-sdk/tlon`, `plugin-sdk/twitch`, `plugin-sdk/github-copilot-login`, `plugin-sdk/github-copilot-token`, `plugin-sdk/diagnostics-otel`, `plugin-sdk/diffs`, `plugin-sdk/llm-task`, - `plugin-sdk/thread-ownership` oraz `plugin-sdk/voice-call` + `plugin-sdk/thread-ownership` i `plugin-sdk/voice-call` -`plugin-sdk/github-copilot-token` obecnie udostępnia wąską powierzchnię -helperów tokena `DEFAULT_COPILOT_API_BASE_URL`, -`deriveCopilotApiBaseUrlFromToken` i `resolveCopilotApiToken`. +`plugin-sdk/github-copilot-token` obecnie udostępnia wąską +powierzchnię pomocników tokenów `DEFAULT_COPILOT_API_BASE_URL`, +`deriveCopilotApiBaseUrlFromToken` oraz `resolveCopilotApiToken`. -Używaj możliwie najwęższego importu, który pasuje do zadania. Jeśli nie możesz znaleźć eksportu, -sprawdź źródło w `src/plugin-sdk/` lub zapytaj na Discord. +Używaj najwęższego importu, który pasuje do zadania. Jeśli nie możesz znaleźć eksportu, +sprawdź źródło w `src/plugin-sdk/` albo zapytaj na Discord. ## Harmonogram usunięcia -| Kiedy | Co się dzieje | +| Kiedy | Co się dzieje | | ---------------------- | ----------------------------------------------------------------------- | -| **Teraz** | Przestarzałe powierzchnie emitują ostrzeżenia w czasie wykonywania | -| **Następna główna wersja** | Przestarzałe powierzchnie zostaną usunięte; wtyczki nadal z nich korzystające przestaną działać | +| **Teraz** | Przestarzałe powierzchnie emitują ostrzeżenia w czasie działania | +| **Następne główne wydanie** | Przestarzałe powierzchnie zostaną usunięte; pluginy nadal z nich korzystające przestaną działać | -Wszystkie główne wtyczki zostały już zmigrowane. Zewnętrzne wtyczki powinny przeprowadzić migrację -przed następną główną wersją. +Wszystkie główne pluginy zostały już zmigrowane. Zewnętrzne pluginy powinny przeprowadzić migrację +przed następnym głównym wydaniem. ## Tymczasowe wyciszenie ostrzeżeń @@ -369,9 +399,9 @@ To tymczasowa furtka awaryjna, a nie trwałe rozwiązanie. ## Powiązane -- [Pierwsze kroki](/pl/plugins/building-plugins) — zbuduj swoją pierwszą wtyczkę -- [Przegląd SDK](/pl/plugins/sdk-overview) — pełna dokumentacja importów ścieżek podrzędnych -- [Wtyczki kanałów](/pl/plugins/sdk-channel-plugins) — budowanie wtyczek kanałów -- [Wtyczki dostawców](/pl/plugins/sdk-provider-plugins) — budowanie wtyczek dostawców -- [Wnętrze wtyczek](/pl/plugins/architecture) — szczegółowe omówienie architektury -- [Manifest wtyczki](/pl/plugins/manifest) — dokumentacja schematu manifestu +- [Getting Started](/pl/plugins/building-plugins) — zbuduj swój pierwszy plugin +- [SDK Overview](/pl/plugins/sdk-overview) — pełna dokumentacja importów podścieżek +- [Channel Plugins](/pl/plugins/sdk-channel-plugins) — budowanie pluginów kanałów +- [Provider Plugins](/pl/plugins/sdk-provider-plugins) — budowanie pluginów dostawców +- [Plugin Internals](/pl/plugins/architecture) — szczegółowe omówienie architektury +- [Plugin Manifest](/pl/plugins/manifest) — dokumentacja schematu manifestu diff --git a/docs/pl/plugins/sdk-overview.md b/docs/pl/plugins/sdk-overview.md index 76220f11f..b4c535129 100644 --- a/docs/pl/plugins/sdk-overview.md +++ b/docs/pl/plugins/sdk-overview.md @@ -1,72 +1,71 @@ --- read_when: - - Musisz wiedzieć, z którego subpath SDK importować - - Chcesz mieć referencję wszystkich metod rejestracji w OpenClawPluginApi + - Musisz wiedzieć, z której ścieżki podrzędnej SDK importować + - Chcesz mieć dokumentację wszystkich metod rejestracji w OpenClawPluginApi - Szukasz konkretnego eksportu SDK sidebarTitle: SDK Overview -summary: Mapa importów, referencja API rejestracji i architektura SDK +summary: Mapa importów, dokumentacja API rejestracji i architektura SDK title: Przegląd Plugin SDK x-i18n: - generated_at: "2026-04-07T09:49:10Z" + generated_at: "2026-04-08T02:18:20Z" model: gpt-5.4 provider: openai - source_hash: 6ba11d1708a117f3872a09fd0bebb0481d36b89b473aec861192e8c2745ef727 + source_hash: c5a41bd82d165dfbb7fbd6e4528cf322e9133a51efe55fa8518a7a0a626d9d30 source_path: plugins/sdk-overview.md workflow: 15 --- # Przegląd Plugin SDK -Plugin SDK to typowany kontrakt między pluginami a core. Ta strona jest -referencją dla **tego, co importować** i **co można rejestrować**. +Plugin SDK to typowany kontrakt między pluginami a rdzeniem. Ta strona jest +dokumentacją tego, **co importować** i **co można rejestrować**. **Szukasz przewodnika krok po kroku?** - - Pierwszy plugin? Zacznij od [Getting Started](/pl/plugins/building-plugins) - - Plugin kanału? Zobacz [Channel Plugins](/pl/plugins/sdk-channel-plugins) - - Plugin dostawcy? Zobacz [Provider Plugins](/pl/plugins/sdk-provider-plugins) + - Pierwszy plugin? Zacznij od [Pierwsze kroki](/pl/plugins/building-plugins) + - Plugin kanału? Zobacz [Pluginy kanałów](/pl/plugins/sdk-channel-plugins) + - Plugin dostawcy? Zobacz [Pluginy dostawców](/pl/plugins/sdk-provider-plugins) ## Konwencja importu -Zawsze importuj z konkretnego subpath: +Zawsze importuj z konkretnej ścieżki podrzędnej: ```typescript import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry"; import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core"; ``` -Każdy subpath to mały, samodzielny moduł. Dzięki temu uruchamianie jest szybkie i -zapobiega to problemom z zależnościami cyklicznymi. Dla helperów wejścia/buildu specyficznych dla kanałów -preferuj `openclaw/plugin-sdk/channel-core`; `openclaw/plugin-sdk/core` zachowaj dla +Każda ścieżka podrzędna to mały, samowystarczalny moduł. Dzięki temu uruchamianie pozostaje szybkie +i zapobiega to problemom z zależnościami cyklicznymi. W przypadku pomocników wejścia/budowania specyficznych dla kanału +preferuj `openclaw/plugin-sdk/channel-core`; zachowaj `openclaw/plugin-sdk/core` dla szerszej powierzchni parasolowej i współdzielonych helperów, takich jak `buildChannelConfigSchema`. -Nie dodawaj ani nie opieraj się na pomocniczych interfejsach nazwanych od dostawców, takich jak +Nie dodawaj ani nie polegaj na pomocniczych ścieżkach wygodnych nazwanych od dostawców, takich jak `openclaw/plugin-sdk/slack`, `openclaw/plugin-sdk/discord`, `openclaw/plugin-sdk/signal`, `openclaw/plugin-sdk/whatsapp` ani -helperowych interfejsach oznaczonych marką kanału. Dołączone pluginy powinny składać ogólne -subpathy SDK we własnych barrelach `api.ts` lub `runtime-api.ts`, a core -powinno albo używać tych lokalnych barreli pluginu, albo dodać wąski ogólny kontrakt SDK, -gdy potrzeba jest rzeczywiście międzykanałowa. +pomocniczych ścieżkach markowanych kanałami. Wbudowane pluginy powinny składać ogólne +ścieżki podrzędne SDK we własnych barrelach `api.ts` lub `runtime-api.ts`, a rdzeń +powinien używać albo tych lokalnych barrelów pluginu, albo dodać wąski ogólny kontrakt SDK, gdy potrzeba jest rzeczywiście międzykanałowa. -Wygenerowana mapa eksportów nadal zawiera mały zestaw helperowych -interfejsów dołączonych pluginów, takich jak `plugin-sdk/feishu`, `plugin-sdk/feishu-setup`, -`plugin-sdk/zalo`, `plugin-sdk/zalo-setup` oraz `plugin-sdk/matrix*`. Te -subpathy istnieją wyłącznie dla utrzymania zgodności i obsługi dołączonych pluginów; są +Wygenerowana mapa eksportów nadal zawiera mały zestaw pomocniczych ścieżek dla wbudowanych pluginów, +takich jak `plugin-sdk/feishu`, `plugin-sdk/feishu-setup`, +`plugin-sdk/zalo`, `plugin-sdk/zalo-setup` i `plugin-sdk/matrix*`. Te +ścieżki podrzędne istnieją wyłącznie dla utrzymania i zgodności wbudowanych pluginów; są celowo pominięte w poniższej wspólnej tabeli i nie są zalecaną -ścieżką importu dla nowych pluginów zewnętrznych. +ścieżką importu dla nowych zewnętrznych pluginów. -## Referencja subpath +## Dokumentacja ścieżek podrzędnych -Najczęściej używane subpathy, pogrupowane według przeznaczenia. Wygenerowana pełna lista -ponad 200 subpath znajduje się w `scripts/lib/plugin-sdk-entrypoints.json`. +Najczęściej używane ścieżki podrzędne, pogrupowane według przeznaczenia. Wygenerowana pełna lista +ponad 200 ścieżek podrzędnych znajduje się w `scripts/lib/plugin-sdk-entrypoints.json`. -Zarezerwowane helperowe subpathy dołączonych pluginów nadal pojawiają się w tej wygenerowanej liście. -Traktuj je jako szczegół implementacyjny/powierzchnie zgodności, chyba że strona dokumentacji -jawnie promuje któryś z nich jako publiczny. +Zarezerwowane pomocnicze ścieżki dla wbudowanych pluginów nadal pojawiają się w tej wygenerowanej liście. +Traktuj je jako powierzchnie szczegółów implementacyjnych/zgodności, chyba że strona dokumentacji +jawnie promuje którąś z nich jako publiczną. -### Punkt wejścia pluginu +### Wejście pluginu | Subpath | Kluczowe eksporty | | --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | @@ -76,222 +75,226 @@ jawnie promuje któryś z nich jako publiczny. | `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` | - + | Subpath | Kluczowe eksporty | | --- | --- | | `plugin-sdk/channel-core` | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` | | `plugin-sdk/config-schema` | Eksport głównego schematu Zod `openclaw.json` (`OpenClawSchema`) | | `plugin-sdk/channel-setup` | `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, `createOptionalChannelSetupWizard`, plus `DEFAULT_ACCOUNT_ID`, `createTopLevelChannelDmPolicy`, `setSetupChannelEnabled`, `splitSetupEntries` | - | `plugin-sdk/setup` | Współdzielone helpery kreatora konfiguracji, prompty list dozwolonych, konstruktory statusu konfiguracji | + | `plugin-sdk/setup` | Współdzielone helpery kreatora konfiguracji, prompty allowlist, konstruktory statusu konfiguracji | | `plugin-sdk/setup-runtime` | `createPatchedAccountSetupAdapter`, `createEnvPatchedAccountSetupAdapter`, `createSetupInputPresenceValidator`, `noteChannelLookupFailure`, `noteChannelLookupSummary`, `promptResolvedAllowFrom`, `splitSetupEntries`, `createAllowlistSetupWizardProxy`, `createDelegatedSetupWizardProxy` | | `plugin-sdk/setup-adapter-runtime` | `createEnvPatchedAccountSetupAdapter` | | `plugin-sdk/setup-tools` | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` | - | `plugin-sdk/account-core` | Helpery konfiguracji/akcyjnych bramek dla wielu kont, helpery fallbacku konta domyślnego | - | `plugin-sdk/account-id` | `DEFAULT_ACCOUNT_ID`, helpery normalizacji identyfikatorów kont | - | `plugin-sdk/account-resolution` | Helpery wyszukiwania kont + fallbacku domyślnego | - | `plugin-sdk/account-helpers` | Wąskie helpery list kont/akcji na kontach | + | `plugin-sdk/account-core` | Helpery konfiguracji/wrót akcji dla wielu kont, helpery fallbacku konta domyślnego | + | `plugin-sdk/account-id` | `DEFAULT_ACCOUNT_ID`, helpery normalizacji identyfikatora konta | + | `plugin-sdk/account-resolution` | Helpery wyszukiwania konta + fallbacku do domyślnego | + | `plugin-sdk/account-helpers` | Wąskie helpery listy kont/akcji na koncie | | `plugin-sdk/channel-pairing` | `createChannelPairingController` | | `plugin-sdk/channel-reply-pipeline` | `createChannelReplyPipeline` | | `plugin-sdk/channel-config-helpers` | `createHybridChannelConfigAdapter` | | `plugin-sdk/channel-config-schema` | Typy schematu konfiguracji kanału | - | `plugin-sdk/telegram-command-config` | Helpery normalizacji/walidacji niestandardowych poleceń Telegram z fallbackiem kontraktu dołączonego | + | `plugin-sdk/telegram-command-config` | Helpery normalizacji/walidacji niestandardowych poleceń Telegram z fallbackiem kontraktu wbudowanego | | `plugin-sdk/channel-policy` | `resolveChannelGroupRequireMention` | | `plugin-sdk/channel-lifecycle` | `createAccountStatusSink` | - | `plugin-sdk/inbound-envelope` | Współdzielone helpery routingu przychodzącego + budowania envelope | - | `plugin-sdk/inbound-reply-dispatch` | Współdzielone helpery zapisu i dispatchu przychodzących wiadomości | + | `plugin-sdk/inbound-envelope` | Współdzielone helpery routingu przychodzącego + budowania kopert | + | `plugin-sdk/inbound-reply-dispatch` | Współdzielone helpery rejestrowania i dispatchu danych przychodzących | | `plugin-sdk/messaging-targets` | Helpery parsowania/dopasowywania celów | | `plugin-sdk/outbound-media` | Współdzielone helpery ładowania mediów wychodzących | - | `plugin-sdk/outbound-runtime` | Helpery tożsamości wychodzącej/delegowania wysyłki | - | `plugin-sdk/thread-bindings-runtime` | Helpery cyklu życia powiązań wątków i adapterów | - | `plugin-sdk/agent-media-payload` | Starszy builder payloadów mediów agenta | - | `plugin-sdk/conversation-runtime` | Helpery konwersacji/powiązań wątków, parowania i skonfigurowanych powiązań | - | `plugin-sdk/runtime-config-snapshot` | Helper snapshotu konfiguracji runtime | - | `plugin-sdk/runtime-group-policy` | Helpery rozwiązywania polityki grup w runtime | - | `plugin-sdk/channel-status` | Współdzielone helpery snapshotu/podsumowania statusu kanału | + | `plugin-sdk/outbound-runtime` | Helpery tożsamości wychodzącej/delegacji wysyłki | + | `plugin-sdk/thread-bindings-runtime` | Helpery cyklu życia i adapterów powiązań wątków | + | `plugin-sdk/agent-media-payload` | Starszy konstruktor ładunku mediów agenta | + | `plugin-sdk/conversation-runtime` | Helpery powiązań rozmowy/wątku, pairingu i skonfigurowanych powiązań | + | `plugin-sdk/runtime-config-snapshot` | Helper migawki konfiguracji runtime | + | `plugin-sdk/runtime-group-policy` | Helpery rozstrzygania polityki grup w runtime | + | `plugin-sdk/channel-status` | Współdzielone helpery migawki/podsumowania statusu kanału | | `plugin-sdk/channel-config-primitives` | Wąskie prymitywy schematu konfiguracji kanału | | `plugin-sdk/channel-config-writes` | Helpery autoryzacji zapisów konfiguracji kanału | - | `plugin-sdk/channel-plugin-common` | Współdzielone eksporty prelude pluginu kanału | + | `plugin-sdk/channel-plugin-common` | Współdzielone eksporty preambuły pluginów kanałów | | `plugin-sdk/allowlist-config-edit` | Helpery edycji/odczytu konfiguracji allowlist | - | `plugin-sdk/group-access` | Współdzielone helpery decyzji dostępu do grup | + | `plugin-sdk/group-access` | Współdzielone helpery decyzji dostępu grupowego | | `plugin-sdk/direct-dm` | Współdzielone helpery uwierzytelniania/ochrony bezpośrednich DM | - | `plugin-sdk/interactive-runtime` | Helpery normalizacji/redukcji interaktywnych payloadów odpowiedzi | - | `plugin-sdk/channel-inbound` | Helpery debounce przychodzących wiadomości, dopasowania wzmianek, polityki wzmianek i helpery envelope | + | `plugin-sdk/interactive-runtime` | Helpery normalizacji/redukcji ładunków odpowiedzi interaktywnych | + | `plugin-sdk/channel-inbound` | Helpery debounce dla wejścia, dopasowywania wzmianek, polityki wzmianek i helpery kopert | | `plugin-sdk/channel-send-result` | Typy wyników odpowiedzi | | `plugin-sdk/channel-actions` | `createMessageToolButtonsSchema`, `createMessageToolCardSchema` | | `plugin-sdk/channel-targets` | Helpery parsowania/dopasowywania celów | | `plugin-sdk/channel-contract` | Typy kontraktu kanału | - | `plugin-sdk/channel-feedback` | Integracja feedbacku/reakcji | - | `plugin-sdk/channel-secret-runtime` | Wąskie helpery kontraktu sekretów, takie jak `collectSimpleChannelFieldAssignments`, `getChannelSurface`, `pushAssignment` oraz typy docelowe sekretów | + | `plugin-sdk/channel-feedback` | Powiązanie feedbacku/reakcji | + | `plugin-sdk/channel-secret-runtime` | Wąskie helpery kontraktu sekretów, takie jak `collectSimpleChannelFieldAssignments`, `getChannelSurface`, `pushAssignment`, oraz typy celu sekretu | - + | Subpath | Kluczowe eksporty | | --- | --- | | `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` | - | `plugin-sdk/provider-setup` | Kuratorowane helpery konfiguracji dostawców local/self-hosted | - | `plugin-sdk/self-hosted-provider-setup` | Skoncentrowane helpery konfiguracji self-hosted dostawców zgodnych z OpenAI | - | `plugin-sdk/cli-backend` | Domyślne ustawienia backendu CLI + stałe watchdog | - | `plugin-sdk/provider-auth-runtime` | Helpery rozwiązywania kluczy API w runtime dla pluginów dostawców | - | `plugin-sdk/provider-auth-api-key` | Helpery onboardingu/zapisu profilu dla kluczy API, takie jak `upsertApiKeyProfile` | - | `plugin-sdk/provider-auth-result` | Standardowy builder wyniku uwierzytelniania OAuth | + | `plugin-sdk/provider-setup` | Kuratorowane helpery konfiguracji lokalnych/samodzielnie hostowanych dostawców | + | `plugin-sdk/self-hosted-provider-setup` | Skoncentrowane helpery konfiguracji samodzielnie hostowanego dostawcy zgodnego z OpenAI | + | `plugin-sdk/cli-backend` | Domyślne ustawienia backendu CLI + stałe watchdoga | + | `plugin-sdk/provider-auth-runtime` | Helpery runtime rozstrzygania klucza API dla pluginów dostawców | + | `plugin-sdk/provider-auth-api-key` | Helpery wdrażania/zapisu profilu klucza API, takie jak `upsertApiKeyProfile` | + | `plugin-sdk/provider-auth-result` | Standardowy konstruktor wyniku uwierzytelniania OAuth | | `plugin-sdk/provider-auth-login` | Współdzielone interaktywne helpery logowania dla pluginów dostawców | | `plugin-sdk/provider-env-vars` | Helpery wyszukiwania zmiennych środowiskowych uwierzytelniania dostawców | | `plugin-sdk/provider-auth` | `createProviderApiKeyAuthMethod`, `ensureApiKeyFromOptionEnvOrPrompt`, `upsertAuthProfile`, `upsertApiKeyProfile`, `writeOAuthCredentials` | - | `plugin-sdk/provider-model-shared` | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`, współdzielone buildery polityk replay, helpery endpointów dostawców i helpery normalizacji identyfikatorów modeli, takie jak `normalizeNativeXaiModelId` | + | `plugin-sdk/provider-model-shared` | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`, współdzielone konstruktory polityki replay, helpery endpointów dostawców oraz helpery normalizacji identyfikatorów modeli, takie jak `normalizeNativeXaiModelId` | | `plugin-sdk/provider-catalog-shared` | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat` | - | `plugin-sdk/provider-http` | Ogólne helpery HTTP/możliwości endpointów dostawców | + | `plugin-sdk/provider-http` | Ogólne helpery HTTP/zdolności endpointów dostawców | | `plugin-sdk/provider-web-fetch-contract` | Wąskie helpery kontraktu konfiguracji/wyboru web-fetch, takie jak `enablePluginInConfig` i `WebFetchProviderPlugin` | - | `plugin-sdk/provider-web-fetch` | Helpery rejestracji/pamięci podręcznej web-fetch | - | `plugin-sdk/provider-web-search-contract` | Wąskie helpery kontraktu konfiguracji/poświadczeń web-search, takie jak `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig` oraz setter/getter poświadczeń o ograniczonym zakresie | - | `plugin-sdk/provider-web-search` | Helpery rejestracji/pamięci podręcznej/runtime dla web-search | - | `plugin-sdk/provider-tools` | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, czyszczenie schematów Gemini + diagnostyka oraz helpery zgodności xAI, takie jak `resolveXaiModelCompatPatch` / `applyXaiModelCompat` | + | `plugin-sdk/provider-web-fetch` | Helpery rejestracji/pamięci podręcznej dostawców web-fetch | + | `plugin-sdk/provider-web-search-contract` | Wąskie helpery kontraktu konfiguracji/poświadczeń web-search, takie jak `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig` oraz ustawiające/pobierające poświadczenia o ograniczonym zakresie | + | `plugin-sdk/provider-web-search` | Helpery rejestracji/pamięci podręcznej/runtime dostawców web-search | + | `plugin-sdk/provider-tools` | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, czyszczenie schematu Gemini + diagnostyka oraz helpery zgodności xAI, takie jak `resolveXaiModelCompatPatch` / `applyXaiModelCompat` | | `plugin-sdk/provider-usage` | `fetchClaudeUsage` i podobne | - | `plugin-sdk/provider-stream` | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`, typy wrapperów streamów oraz współdzielone helpery wrapperów Anthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot | + | `plugin-sdk/provider-stream` | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`, typy wrapperów strumieni oraz współdzielone helpery wrapperów Anthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot | | `plugin-sdk/provider-onboard` | Helpery łatek konfiguracji onboardingu | - | `plugin-sdk/global-singleton` | Lokalne dla procesu helpery singletonów/map/cache | + | `plugin-sdk/global-singleton` | Pomocniki singletonów/map/pamięci podręcznej lokalnych dla procesu | - + | Subpath | Kluczowe eksporty | | --- | --- | - | `plugin-sdk/command-auth` | `resolveControlCommandGate`, helpery rejestru poleceń, helpery autoryzacji nadawców | - | `plugin-sdk/approval-auth-runtime` | Helpery rozwiązywania approvera i uwierzytelniania akcji w tym samym czacie | - | `plugin-sdk/approval-client-runtime` | Helpery natywnego profilu/filtrowania zatwierdzeń exec | - | `plugin-sdk/approval-delivery-runtime` | Natywne adaptery możliwości/dostarczania zatwierdzeń | - | `plugin-sdk/approval-native-runtime` | Helpery natywnych celów zatwierdzeń + powiązań kont | - | `plugin-sdk/approval-reply-runtime` | Helpery payloadów odpowiedzi zatwierdzeń exec/pluginów | - | `plugin-sdk/command-auth-native` | Natywne uwierzytelnianie poleceń + helpery natywnych celów sesji | + | `plugin-sdk/command-auth` | `resolveControlCommandGate`, helpery rejestru poleceń, helpery autoryzacji nadawcy | + | `plugin-sdk/approval-auth-runtime` | Helpery rozstrzygania zatwierdzającego i uwierzytelniania akcji w tym samym czacie | + | `plugin-sdk/approval-client-runtime` | Natywne helpery profilu/filtru zatwierdzeń exec | + | `plugin-sdk/approval-delivery-runtime` | Natywne adaptery zdolności/dostarczania zatwierdzeń | + | `plugin-sdk/approval-gateway-runtime` | Współdzielony helper rozstrzygania gateway zatwierdzeń | + | `plugin-sdk/approval-handler-adapter-runtime` | Lekkie helpery ładowania natywnego adaptera zatwierdzeń dla gorących punktów wejścia kanałów | + | `plugin-sdk/approval-handler-runtime` | Szersze helpery runtime obsługi zatwierdzeń; preferuj węższe ścieżki adapter/gateway, gdy są wystarczające | + | `plugin-sdk/approval-native-runtime` | Natywne helpery celu zatwierdzeń + powiązań kont | + | `plugin-sdk/approval-reply-runtime` | Helpery ładunków odpowiedzi dla zatwierdzeń exec/pluginów | + | `plugin-sdk/command-auth-native` | Natywne uwierzytelnianie poleceń + natywne helpery celu sesji | | `plugin-sdk/command-detection` | Współdzielone helpery wykrywania poleceń | - | `plugin-sdk/command-surface` | Normalizacja treści polecenia i helpery powierzchni poleceń | + | `plugin-sdk/command-surface` | Helpery normalizacji treści poleceń i powierzchni poleceń | | `plugin-sdk/allow-from` | `formatAllowFromLowercase` | - | `plugin-sdk/channel-secret-runtime` | Wąskie helpery zbierania kontraktu sekretów dla powierzchni sekretów kanałów/pluginów | - | `plugin-sdk/secret-ref-runtime` | Wąskie helpery `coerceSecretRef` i typowania SecretRef do parsowania kontraktów sekretów/konfiguracji | - | `plugin-sdk/security-runtime` | Współdzielone helpery zaufania, bramek DM, treści zewnętrznych i zbierania sekretów | + | `plugin-sdk/channel-secret-runtime` | Wąskie helpery zbierania kontraktów sekretów dla powierzchni sekretów kanałów/pluginów | + | `plugin-sdk/secret-ref-runtime` | Wąskie helpery `coerceSecretRef` i typowania SecretRef dla parsowania kontraktów sekretów/konfiguracji | + | `plugin-sdk/security-runtime` | Współdzielone helpery zaufania, bramkowania DM, treści zewnętrznej i zbierania sekretów | | `plugin-sdk/ssrf-policy` | Helpery allowlist hostów i polityki SSRF dla sieci prywatnych | - | `plugin-sdk/ssrf-runtime` | Helpery pinned-dispatcher, fetch chronionego przed SSRF i polityki SSRF | - | `plugin-sdk/secret-input` | Helpery parsowania danych wejściowych sekretów | - | `plugin-sdk/webhook-ingress` | Helpery żądań/celów webhooków | - | `plugin-sdk/webhook-request-guards` | Helpery rozmiaru body/timeoutu żądań | + | `plugin-sdk/ssrf-runtime` | Helpery pinned-dispatcher, fetch chronionego SSRF i polityki SSRF | + | `plugin-sdk/secret-input` | Helpery parsowania wejścia sekretów | + | `plugin-sdk/webhook-ingress` | Helpery requestów/celów webhooków | + | `plugin-sdk/webhook-request-guards` | Helpery rozmiaru body/timeoutu requestów | - + | Subpath | Kluczowe eksporty | | --- | --- | - | `plugin-sdk/runtime` | Szeroka powierzchnia helperów runtime/logowania/kopii zapasowych/instalacji pluginów | - | `plugin-sdk/runtime-env` | Wąskie helpery env runtime, loggera, timeoutu, retry i backoff | + | `plugin-sdk/runtime` | Szerokie helpery runtime/logowania/kopii zapasowych/instalacji pluginów | + | `plugin-sdk/runtime-env` | Wąskie helpery środowiska runtime, loggera, timeoutu, retry i backoff | + | `plugin-sdk/channel-runtime-context` | Ogólne helpery rejestracji i wyszukiwania kontekstu runtime kanału | | `plugin-sdk/runtime-store` | `createPluginRuntimeStore` | - | `plugin-sdk/plugin-runtime` | Współdzielone helpery poleceń/hooków/http/interaktywne pluginów | + | `plugin-sdk/plugin-runtime` | Współdzielone helpery poleceń/hooków/http/interaktywności pluginów | | `plugin-sdk/hook-runtime` | Współdzielone helpery pipeline webhooków/wewnętrznych hooków | - | `plugin-sdk/lazy-runtime` | Helpery leniwego importu/powiązania runtime, takie jak `createLazyRuntimeModule`, `createLazyRuntimeMethod` i `createLazyRuntimeSurface` | - | `plugin-sdk/process-runtime` | Helpery wykonywania procesów | - | `plugin-sdk/cli-runtime` | Helpery formatowania, oczekiwania i wersji CLI | - | `plugin-sdk/gateway-runtime` | Helpery klienta Gateway i łatek statusu kanału | + | `plugin-sdk/lazy-runtime` | Helpery leniwego importu/powiązań runtime, takie jak `createLazyRuntimeModule`, `createLazyRuntimeMethod` i `createLazyRuntimeSurface` | + | `plugin-sdk/process-runtime` | Helpery exec procesów | + | `plugin-sdk/cli-runtime` | Helpery formatowania CLI, oczekiwania i wersji | + | `plugin-sdk/gateway-runtime` | Helpery klienta gateway i łatek statusu kanałów | | `plugin-sdk/config-runtime` | Helpery ładowania/zapisu konfiguracji | - | `plugin-sdk/telegram-command-config` | Helpery normalizacji nazwy/opisu poleceń Telegram i sprawdzania duplikatów/konfliktów, nawet gdy powierzchnia kontraktu dołączonego Telegram nie jest dostępna | - | `plugin-sdk/approval-runtime` | Helpery zatwierdzeń exec/pluginów, buildery możliwości zatwierdzeń, helpery auth/profili, natywne helpery routingu/runtime | - | `plugin-sdk/reply-runtime` | Współdzielone helpery runtime dla wiadomości przychodzących/odpowiedzi, chunking, dispatch, heartbeat, planer odpowiedzi | + | `plugin-sdk/telegram-command-config` | Helpery normalizacji nazw/opisów poleceń Telegram i kontroli duplikatów/konfliktów, nawet gdy powierzchnia kontraktu wbudowanego Telegrama jest niedostępna | + | `plugin-sdk/approval-runtime` | Helpery zatwierdzeń exec/pluginów, konstruktory zdolności zatwierdzeń, helpery auth/profili, natywne helpery routingu/runtime | + | `plugin-sdk/reply-runtime` | Współdzielone helpery runtime wejścia/odpowiedzi, chunkingu, dispatchu, heartbeat i planisty odpowiedzi | | `plugin-sdk/reply-dispatch-runtime` | Wąskie helpery dispatchu/finalizacji odpowiedzi | - | `plugin-sdk/reply-history` | Współdzielone helpery krótkiego okna historii odpowiedzi, takie jak `buildHistoryContext`, `recordPendingHistoryEntry` i `clearHistoryEntriesIfEnabled` | + | `plugin-sdk/reply-history` | Współdzielone helpery historii odpowiedzi dla krótkiego okna, takie jak `buildHistoryContext`, `recordPendingHistoryEntry` i `clearHistoryEntriesIfEnabled` | | `plugin-sdk/reply-reference` | `createReplyReferencePlanner` | | `plugin-sdk/reply-chunking` | Wąskie helpery chunkingu tekstu/Markdown | | `plugin-sdk/session-store-runtime` | Helpery ścieżek magazynu sesji + updated-at | | `plugin-sdk/state-paths` | Helpery ścieżek katalogów stanu/OAuth | - | `plugin-sdk/routing` | Helpery routingu/kluczy sesji/powiązań kont, takie jak `resolveAgentRoute`, `buildAgentSessionKey` i `resolveDefaultAgentBoundAccountId` | + | `plugin-sdk/routing` | Helpery routingu/klucza sesji/powiązania kont, takie jak `resolveAgentRoute`, `buildAgentSessionKey` i `resolveDefaultAgentBoundAccountId` | | `plugin-sdk/status-helpers` | Współdzielone helpery podsumowań statusu kanałów/kont, domyślne stany runtime i helpery metadanych problemów | - | `plugin-sdk/target-resolver-runtime` | Współdzielone helpery rozwiązywania celów | + | `plugin-sdk/target-resolver-runtime` | Współdzielone helpery resolvera celów | | `plugin-sdk/string-normalization-runtime` | Helpery normalizacji slugów/ciągów | - | `plugin-sdk/request-url` | Wyodrębnianie URL-i tekstowych z wejść typu fetch/request | - | `plugin-sdk/run-command` | Runner poleceń z timeoutem i znormalizowanymi wynikami stdout/stderr | - | `plugin-sdk/param-readers` | Wspólni czytelnicy parametrów narzędzi/CLI | - | `plugin-sdk/tool-send` | Wyodrębnianie kanonicznych pól celu wysyłki z argumentów narzędzia | - | `plugin-sdk/temp-path` | Współdzielone helpery ścieżek tymczasowego pobierania | - | `plugin-sdk/logging-core` | Logger podsystemu i helpery redakcji | + | `plugin-sdk/request-url` | Wyodrębnia ciągi URL z wejść podobnych do fetch/request | + | `plugin-sdk/run-command` | Uruchamianie poleceń z limitem czasu i znormalizowanymi wynikami stdout/stderr | + | `plugin-sdk/param-readers` | Typowe czytniki parametrów narzędzi/CLI | + | `plugin-sdk/tool-send` | Wyodrębnia kanoniczne pola celu wysyłki z argumentów narzędzi | + | `plugin-sdk/temp-path` | Współdzielone helpery ścieżek tymczasowych pobrań | + | `plugin-sdk/logging-core` | Logger subsystemu i helpery redakcji | | `plugin-sdk/markdown-table-runtime` | Helpery trybu tabel Markdown | | `plugin-sdk/json-store` | Małe helpery odczytu/zapisu stanu JSON | - | `plugin-sdk/file-lock` | Helpery reentrant file-lock | - | `plugin-sdk/persistent-dedupe` | Helpery pamięci podręcznej deduplikacji opartej na dysku | + | `plugin-sdk/file-lock` | Rekurencyjne helpery blokowania plików | + | `plugin-sdk/persistent-dedupe` | Helpery pamięci podręcznej deduplikacji na dysku | | `plugin-sdk/acp-runtime` | Helpery runtime/sesji ACP i dispatchu odpowiedzi | | `plugin-sdk/agent-config-primitives` | Wąskie prymitywy schematu konfiguracji runtime agenta | - | `plugin-sdk/boolean-param` | Luźny czytnik parametrów bool | - | `plugin-sdk/dangerous-name-runtime` | Helpery rozwiązywania niebezpiecznego dopasowania nazw | - | `plugin-sdk/device-bootstrap` | Helpery bootstrapu urządzenia i tokenów parowania | + | `plugin-sdk/boolean-param` | Elastyczny czytnik parametrów logicznych | + | `plugin-sdk/dangerous-name-runtime` | Helpery rozstrzygania dopasowań niebezpiecznych nazw | + | `plugin-sdk/device-bootstrap` | Helpery bootstrapu urządzenia i tokenów pairingu | | `plugin-sdk/extension-shared` | Współdzielone prymitywy helperów kanałów pasywnych, statusu i ambient proxy | - | `plugin-sdk/models-provider-runtime` | Helpery odpowiedzi dla polecenia `/models` i dostawców | + | `plugin-sdk/models-provider-runtime` | Helpery odpowiedzi polecenia `/models` / dostawców | | `plugin-sdk/skill-commands-runtime` | Helpery listowania poleceń Skills | - | `plugin-sdk/native-command-registry` | Helpery rejestru/build/serializacji natywnych poleceń | - | `plugin-sdk/provider-zai-endpoint` | Helpery wykrywania endpointu Z.AI | + | `plugin-sdk/native-command-registry` | Natywne helpery rejestru/budowania/serializacji poleceń | + | `plugin-sdk/provider-zai-endpoint` | Helpery wykrywania endpointów Z.AI | | `plugin-sdk/infra-runtime` | Helpery zdarzeń systemowych/heartbeat | | `plugin-sdk/collection-runtime` | Małe helpery ograniczonej pamięci podręcznej | | `plugin-sdk/diagnostic-runtime` | Helpery flag i zdarzeń diagnostycznych | | `plugin-sdk/error-runtime` | Graf błędów, formatowanie, współdzielone helpery klasyfikacji błędów, `isApprovalNotFoundError` | | `plugin-sdk/fetch-runtime` | Opakowany fetch, proxy i helpery pinned lookup | - | `plugin-sdk/host-runtime` | Helpery normalizacji hostname i hostów SCP | - | `plugin-sdk/retry-runtime` | Helpery konfiguracji retry i runnera retry | - | `plugin-sdk/agent-runtime` | Helpery katalogu/tożsamości/workspace agenta | - | `plugin-sdk/directory-runtime` | Zapytania/dedup directory oparte na konfiguracji | + | `plugin-sdk/host-runtime` | Helpery normalizacji hostname i hosta SCP | + | `plugin-sdk/retry-runtime` | Helpery konfiguracji retry i wykonawcy retry | + | `plugin-sdk/agent-runtime` | Helpery katalogu/tożsamości/obszaru roboczego agenta | + | `plugin-sdk/directory-runtime` | Zapytania o katalog oparte na konfiguracji/deduplikacja | | `plugin-sdk/keyed-async-queue` | `KeyedAsyncQueue` | - + | Subpath | Kluczowe eksporty | | --- | --- | - | `plugin-sdk/media-runtime` | Współdzielone helpery pobierania/przekształcania/przechowywania mediów oraz buildery payloadów mediów | - | `plugin-sdk/media-generation-runtime` | Współdzielone helpery failover generowania mediów, wybór kandydatów i komunikaty o brakującym modelu | - | `plugin-sdk/media-understanding` | Typy dostawców rozumienia mediów oraz eksporty helperów obrazów/audio dla dostawców | - | `plugin-sdk/text-runtime` | Współdzielone helpery tekstu/Markdown/logowania, takie jak usuwanie tekstu widocznego dla asystenta, renderowanie/chunking/tabele Markdown, helpery redakcji, helpery tagów dyrektyw i bezpieczne narzędzia tekstowe | + | `plugin-sdk/media-runtime` | Współdzielone helpery pobierania/przekształcania/przechowywania mediów oraz konstruktory ładunków mediów | + | `plugin-sdk/media-generation-runtime` | Współdzielone helpery failover generowania mediów, wybór kandydatów i komunikaty o brakujących modelach | + | `plugin-sdk/media-understanding` | Typy dostawców rozumienia mediów oraz eksporty helperów obrazu/audio dla dostawców | + | `plugin-sdk/text-runtime` | Współdzielone helpery tekstu/Markdown/logowania, takie jak usuwanie tekstu widocznego dla asystenta, helpery renderowania/chunkingu/tabel Markdown, helpery redakcji, helpery tagów dyrektyw i narzędzia bezpiecznego tekstu | | `plugin-sdk/text-chunking` | Helper chunkingu tekstu wychodzącego | | `plugin-sdk/speech` | Typy dostawców mowy oraz eksporty helperów dyrektyw, rejestru i walidacji dla dostawców | - | `plugin-sdk/speech-core` | Współdzielone typy dostawców mowy, helpery rejestru, dyrektyw i normalizacji | - | `plugin-sdk/realtime-transcription` | Typy dostawców transkrypcji w czasie rzeczywistym i helpery rejestru | - | `plugin-sdk/realtime-voice` | Typy dostawców głosu w czasie rzeczywistym i helpery rejestru | + | `plugin-sdk/speech-core` | Współdzielone typy dostawców mowy, rejestr, dyrektywy i helpery normalizacji | + | `plugin-sdk/realtime-transcription` | Typy dostawców transkrypcji realtime i helpery rejestru | + | `plugin-sdk/realtime-voice` | Typy dostawców głosu realtime i helpery rejestru | | `plugin-sdk/image-generation` | Typy dostawców generowania obrazów | - | `plugin-sdk/image-generation-core` | Współdzielone typy, failover, helpery auth i rejestru dla generowania obrazów | - | `plugin-sdk/music-generation` | Typy dostawców/żądań/wyników generowania muzyki | - | `plugin-sdk/music-generation-core` | Współdzielone typy generowania muzyki, helpery failover, wyszukiwania dostawców i parsowania referencji modeli | - | `plugin-sdk/video-generation` | Typy dostawców/żądań/wyników generowania wideo | - | `plugin-sdk/video-generation-core` | Współdzielone typy generowania wideo, helpery failover, wyszukiwania dostawców i parsowania referencji modeli | + | `plugin-sdk/image-generation-core` | Współdzielone typy generowania obrazów, failover, uwierzytelnianie i helpery rejestru | + | `plugin-sdk/music-generation` | Typy dostawców/requestów/wyników generowania muzyki | + | `plugin-sdk/music-generation-core` | Współdzielone typy generowania muzyki, helpery failover, wyszukiwanie dostawców i parsowanie model-ref | + | `plugin-sdk/video-generation` | Typy dostawców/requestów/wyników generowania wideo | + | `plugin-sdk/video-generation-core` | Współdzielone typy generowania wideo, helpery failover, wyszukiwanie dostawców i parsowanie model-ref | | `plugin-sdk/webhook-targets` | Rejestr celów webhooków i helpery instalacji tras | | `plugin-sdk/webhook-path` | Helpery normalizacji ścieżek webhooków | | `plugin-sdk/web-media` | Współdzielone helpery ładowania zdalnych/lokalnych mediów | - | `plugin-sdk/zod` | Reeksport `zod` dla użytkowników Plugin SDK | + | `plugin-sdk/zod` | Reeksportowane `zod` dla użytkowników plugin SDK | | `plugin-sdk/testing` | `installCommonResolveTargetErrorCases`, `shouldAckReaction` | - + | Subpath | Kluczowe eksporty | | --- | --- | - | `plugin-sdk/memory-core` | Dołączona pomocnicza powierzchnia memory-core dla helperów managera/konfiguracji/plików/CLI | + | `plugin-sdk/memory-core` | Powierzchnia helperów wbudowanego memory-core dla managera/konfiguracji/plików/CLI | | `plugin-sdk/memory-core-engine-runtime` | Fasada runtime indeksu/wyszukiwania pamięci | - | `plugin-sdk/memory-core-host-engine-foundation` | Eksporty silnika podstawowego hosta pamięci | + | `plugin-sdk/memory-core-host-engine-foundation` | Eksporty silnika bazowego hosta pamięci | | `plugin-sdk/memory-core-host-engine-embeddings` | Eksporty silnika embeddingów hosta pamięci | | `plugin-sdk/memory-core-host-engine-qmd` | Eksporty silnika QMD hosta pamięci | | `plugin-sdk/memory-core-host-engine-storage` | Eksporty silnika storage hosta pamięci | - | `plugin-sdk/memory-core-host-multimodal` | Helpery multimodalne hosta pamięci | + | `plugin-sdk/memory-core-host-multimodal` | Helpery multimodalnego hosta pamięci | | `plugin-sdk/memory-core-host-query` | Helpery zapytań hosta pamięci | | `plugin-sdk/memory-core-host-secret` | Helpery sekretów hosta pamięci | | `plugin-sdk/memory-core-host-events` | Helpery dziennika zdarzeń hosta pamięci | | `plugin-sdk/memory-core-host-status` | Helpery statusu hosta pamięci | | `plugin-sdk/memory-core-host-runtime-cli` | Helpery runtime CLI hosta pamięci | - | `plugin-sdk/memory-core-host-runtime-core` | Helpery podstawowego runtime hosta pamięci | + | `plugin-sdk/memory-core-host-runtime-core` | Helpery głównego runtime hosta pamięci | | `plugin-sdk/memory-core-host-runtime-files` | Helpery plików/runtime hosta pamięci | - | `plugin-sdk/memory-host-core` | Neutralny wobec producenta alias helperów podstawowego runtime hosta pamięci | - | `plugin-sdk/memory-host-events` | Neutralny wobec producenta alias helperów dziennika zdarzeń hosta pamięci | - | `plugin-sdk/memory-host-files` | Neutralny wobec producenta alias helperów plików/runtime hosta pamięci | - | `plugin-sdk/memory-host-markdown` | Współdzielone helpery managed-markdown dla pluginów sąsiadujących z pamięcią | - | `plugin-sdk/memory-host-search` | Fasada aktywnego runtime pamięci dla dostępu do search-manager | - | `plugin-sdk/memory-host-status` | Neutralny wobec producenta alias helperów statusu hosta pamięci | - | `plugin-sdk/memory-lancedb` | Dołączona pomocnicza powierzchnia memory-lancedb | + | `plugin-sdk/memory-host-core` | Neutralny względem dostawcy alias helperów głównego runtime hosta pamięci | + | `plugin-sdk/memory-host-events` | Neutralny względem dostawcy alias helperów dziennika zdarzeń hosta pamięci | + | `plugin-sdk/memory-host-files` | Neutralny względem dostawcy alias helperów plików/runtime hosta pamięci | + | `plugin-sdk/memory-host-markdown` | Współdzielone helpery zarządzanego Markdown dla pluginów sąsiadujących z pamięcią | + | `plugin-sdk/memory-host-search` | Aktywna fasada runtime pamięci dla dostępu do menedżera wyszukiwania | + | `plugin-sdk/memory-host-status` | Neutralny względem dostawcy alias helperów statusu hosta pamięci | + | `plugin-sdk/memory-lancedb` | Powierzchnia helperów wbudowanego memory-lancedb | - - | Rodzina | Aktualne subpathy | Zamierzone użycie | + + | Family | Current subpaths | Intended use | | --- | --- | --- | - | Browser | `plugin-sdk/browser-cdp`, `plugin-sdk/browser-config-runtime`, `plugin-sdk/browser-config-support`, `plugin-sdk/browser-control-auth`, `plugin-sdk/browser-node-runtime`, `plugin-sdk/browser-profiles`, `plugin-sdk/browser-security-runtime`, `plugin-sdk/browser-setup-tools`, `plugin-sdk/browser-support` | Helpery wsparcia dołączonego pluginu browser (`browser-support` pozostaje barrelem zgodności) | - | Matrix | `plugin-sdk/matrix`, `plugin-sdk/matrix-helper`, `plugin-sdk/matrix-runtime-heavy`, `plugin-sdk/matrix-runtime-shared`, `plugin-sdk/matrix-runtime-surface`, `plugin-sdk/matrix-surface`, `plugin-sdk/matrix-thread-bindings` | Powierzchnia helperów/runtime dołączonego Matrix | - | Line | `plugin-sdk/line`, `plugin-sdk/line-core`, `plugin-sdk/line-runtime`, `plugin-sdk/line-surface` | Powierzchnia helperów/runtime dołączonego LINE | - | IRC | `plugin-sdk/irc`, `plugin-sdk/irc-surface` | Powierzchnia helperów dołączonego IRC | - | Helpery specyficzne dla kanału | `plugin-sdk/googlechat`, `plugin-sdk/zalouser`, `plugin-sdk/bluebubbles`, `plugin-sdk/bluebubbles-policy`, `plugin-sdk/mattermost`, `plugin-sdk/mattermost-policy`, `plugin-sdk/feishu-conversation`, `plugin-sdk/msteams`, `plugin-sdk/nextcloud-talk`, `plugin-sdk/nostr`, `plugin-sdk/tlon`, `plugin-sdk/twitch` | Interfejsy zgodności/helperów dołączonych kanałów | - | Helpery specyficzne dla auth/pluginów | `plugin-sdk/github-copilot-login`, `plugin-sdk/github-copilot-token`, `plugin-sdk/diagnostics-otel`, `plugin-sdk/diffs`, `plugin-sdk/llm-task`, `plugin-sdk/thread-ownership`, `plugin-sdk/voice-call` | Interfejsy helperów dołączonych funkcji/pluginów; `plugin-sdk/github-copilot-token` eksportuje obecnie `DEFAULT_COPILOT_API_BASE_URL`, `deriveCopilotApiBaseUrlFromToken` i `resolveCopilotApiToken` | + | Browser | `plugin-sdk/browser-cdp`, `plugin-sdk/browser-config-runtime`, `plugin-sdk/browser-config-support`, `plugin-sdk/browser-control-auth`, `plugin-sdk/browser-node-runtime`, `plugin-sdk/browser-profiles`, `plugin-sdk/browser-security-runtime`, `plugin-sdk/browser-setup-tools`, `plugin-sdk/browser-support` | Helpery wsparcia wbudowanego pluginu przeglądarki (`browser-support` pozostaje barrelem zgodności) | + | Matrix | `plugin-sdk/matrix`, `plugin-sdk/matrix-helper`, `plugin-sdk/matrix-runtime-heavy`, `plugin-sdk/matrix-runtime-shared`, `plugin-sdk/matrix-runtime-surface`, `plugin-sdk/matrix-surface`, `plugin-sdk/matrix-thread-bindings` | Powierzchnia helperów/runtime wbudowanego Matrix | + | Line | `plugin-sdk/line`, `plugin-sdk/line-core`, `plugin-sdk/line-runtime`, `plugin-sdk/line-surface` | Powierzchnia helperów/runtime wbudowanego LINE | + | IRC | `plugin-sdk/irc`, `plugin-sdk/irc-surface` | Powierzchnia helperów wbudowanego IRC | + | Channel-specific helpers | `plugin-sdk/googlechat`, `plugin-sdk/zalouser`, `plugin-sdk/bluebubbles`, `plugin-sdk/bluebubbles-policy`, `plugin-sdk/mattermost`, `plugin-sdk/mattermost-policy`, `plugin-sdk/feishu-conversation`, `plugin-sdk/msteams`, `plugin-sdk/nextcloud-talk`, `plugin-sdk/nostr`, `plugin-sdk/tlon`, `plugin-sdk/twitch` | Wbudowane ścieżki zgodności/helperów kanałów | + | Auth/plugin-specific helpers | `plugin-sdk/github-copilot-login`, `plugin-sdk/github-copilot-token`, `plugin-sdk/diagnostics-otel`, `plugin-sdk/diffs`, `plugin-sdk/llm-task`, `plugin-sdk/thread-ownership`, `plugin-sdk/voice-call` | Wbudowane ścieżki helperów funkcji/pluginów; `plugin-sdk/github-copilot-token` obecnie eksportuje `DEFAULT_COPILOT_API_BASE_URL`, `deriveCopilotApiBaseUrlFromToken` i `resolveCopilotApiToken` | @@ -300,59 +303,58 @@ jawnie promuje któryś z nich jako publiczny. Callback `register(api)` otrzymuje obiekt `OpenClawPluginApi` z następującymi metodami: -### Rejestracja możliwości +### Rejestracja capabilities -| Metoda | Co rejestruje | +| Method | What it registers | | ------------------------------------------------ | -------------------------------- | | `api.registerProvider(...)` | Wnioskowanie tekstowe (LLM) | | `api.registerCliBackend(...)` | Lokalny backend wnioskowania CLI | | `api.registerChannel(...)` | Kanał wiadomości | -| `api.registerSpeechProvider(...)` | Synteza text-to-speech / STT | -| `api.registerRealtimeTranscriptionProvider(...)` | Strumieniową transkrypcję w czasie rzeczywistym | -| `api.registerRealtimeVoiceProvider(...)` | Dwukierunkowe sesje głosowe w czasie rzeczywistym | -| `api.registerMediaUnderstandingProvider(...)` | Analizę obrazu/audio/wideo | +| `api.registerSpeechProvider(...)` | Synteza tekst-na-mowę / STT | +| `api.registerRealtimeTranscriptionProvider(...)` | Strumieniowa transkrypcja realtime | +| `api.registerRealtimeVoiceProvider(...)` | Dwukierunkowe sesje głosu realtime | +| `api.registerMediaUnderstandingProvider(...)` | Analiza obrazu/audio/wideo | | `api.registerImageGenerationProvider(...)` | Generowanie obrazów | | `api.registerMusicGenerationProvider(...)` | Generowanie muzyki | | `api.registerVideoGenerationProvider(...)` | Generowanie wideo | -| `api.registerWebFetchProvider(...)` | Dostawcę web fetch / scrape | +| `api.registerWebFetchProvider(...)` | Dostawca web fetch / scrape | | `api.registerWebSearchProvider(...)` | Wyszukiwanie w sieci | ### Narzędzia i polecenia -| Metoda | Co rejestruje | -| ------------------------------- | -------------------------------------------- | +| Method | What it registers | +| ------------------------------- | --------------------------------------------- | | `api.registerTool(tool, opts?)` | Narzędzie agenta (wymagane lub `{ optional: true }`) | -| `api.registerCommand(def)` | Polecenie niestandardowe (omija LLM) | +| `api.registerCommand(def)` | Polecenie niestandardowe (pomija LLM) | ### Infrastruktura -| Metoda | Co rejestruje | -| ---------------------------------------------- | ----------------------------------- | -| `api.registerHook(events, handler, opts?)` | Hook zdarzeń | -| `api.registerHttpRoute(params)` | Endpoint HTTP Gateway | -| `api.registerGatewayMethod(name, handler)` | Metodę RPC Gateway | -| `api.registerCli(registrar, opts?)` | Podpolecenie CLI | -| `api.registerService(service)` | Usługę działającą w tle | -| `api.registerInteractiveHandler(registration)` | Handler interaktywny | -| `api.registerMemoryPromptSupplement(builder)` | Addytywną sekcję promptu sąsiadującą z pamięcią | -| `api.registerMemoryCorpusSupplement(adapter)` | Addytywny korpus pamięci do wyszukiwania/odczytu | +| Method | What it registers | +| ---------------------------------------------- | --------------------------------------- | +| `api.registerHook(events, handler, opts?)` | Hook zdarzeń | +| `api.registerHttpRoute(params)` | Endpoint HTTP gateway | +| `api.registerGatewayMethod(name, handler)` | Metoda RPC gateway | +| `api.registerCli(registrar, opts?)` | Podpolecenie CLI | +| `api.registerService(service)` | Usługa działająca w tle | +| `api.registerInteractiveHandler(registration)` | Handler interaktywny | +| `api.registerMemoryPromptSupplement(builder)` | Addytywna sekcja promptu sąsiadująca z pamięcią | +| `api.registerMemoryCorpusSupplement(adapter)` | Addytywny korpus wyszukiwania/odczytu pamięci | -Zarezerwowane podstawowe administracyjne przestrzenie nazw (`config.*`, `exec.approvals.*`, `wizard.*`, -`update.*`) zawsze pozostają `operator.admin`, nawet jeśli plugin spróbuje przypisać -węższy zakres metody Gateway. Dla metod należących do pluginu preferuj prefiksy -specyficzne dla pluginu. +Zarezerwowane przestrzenie nazw administracyjnych rdzenia (`config.*`, `exec.approvals.*`, `wizard.*`, +`update.*`) zawsze pozostają `operator.admin`, nawet jeśli plugin próbuje przypisać +węższy zakres metody gateway. Dla metod należących do pluginów preferuj prefiksy specyficzne dla pluginu. ### Metadane rejestracji CLI `api.registerCli(registrar, opts?)` akceptuje dwa rodzaje metadanych najwyższego poziomu: -- `commands`: jawne rooty poleceń należące do registrara -- `descriptors`: deskryptory poleceń używane w czasie parsowania dla głównej pomocy CLI, +- `commands`: jawne korzenie poleceń należące do rejestratora +- `descriptors`: deskryptory poleceń na etapie parsowania używane do pomocy głównego CLI, routingu i leniwej rejestracji CLI pluginów -Jeśli chcesz, aby polecenie pluginu pozostawało leniwie ładowane w normalnej ścieżce głównego CLI, -podaj `descriptors`, które obejmują każdy root polecenia najwyższego poziomu ujawniany przez tego -registrara. +Jeśli chcesz, aby polecenie pluginu pozostało ładowane leniwie w zwykłej ścieżce głównego CLI, +podaj `descriptors`, które obejmują każdy korzeń poleceń najwyższego poziomu udostępniany przez ten +rejestrator. ```typescript api.registerCli( @@ -364,7 +366,7 @@ api.registerCli( descriptors: [ { name: "matrix", - description: "Manage Matrix accounts, verification, devices, and profile state", + description: "Zarządzaj kontami Matrix, weryfikacją, urządzeniami i stanem profilu", hasSubcommands: true, }, ], @@ -374,82 +376,82 @@ api.registerCli( Używaj samego `commands` tylko wtedy, gdy nie potrzebujesz leniwej rejestracji głównego CLI. Ta ścieżka zgodności eager nadal jest obsługiwana, ale nie instaluje -placeholderów opartych na deskryptorach dla leniwego ładowania w czasie parsowania. +placeholderów opartych na deskryptorach dla leniwego ładowania na etapie parsowania. ### Rejestracja backendu CLI `api.registerCliBackend(...)` pozwala pluginowi posiadać domyślną konfigurację lokalnego -backendu AI CLI, takiego jak `codex-cli`. +backendu CLI AI, takiego jak `codex-cli`. -- `id` backendu staje się prefiksem dostawcy w referencjach modeli takich jak `codex-cli/gpt-5`. +- `id` backendu staje się prefiksem dostawcy w odwołaniach do modeli, takich jak `codex-cli/gpt-5`. - `config` backendu używa tego samego kształtu co `agents.defaults.cliBackends.`. -- Konfiguracja użytkownika nadal wygrywa. OpenClaw scala `agents.defaults.cliBackends.` z - domyślną konfiguracją pluginu przed uruchomieniem CLI. -- Użyj `normalizeConfig`, gdy backend wymaga przepisania zgodności po scaleniu +- Konfiguracja użytkownika nadal ma pierwszeństwo. OpenClaw scala `agents.defaults.cliBackends.` z + wartością domyślną pluginu przed uruchomieniem CLI. +- Użyj `normalizeConfig`, gdy backend potrzebuje przeróbek zgodności po scaleniu (na przykład normalizacji starych kształtów flag). -### Sloty wyłączne +### Wyłączne sloty -| Metoda | Co rejestruje | -| ------------------------------------------ | ------------------------------------ | -| `api.registerContextEngine(id, factory)` | Silnik kontekstu (aktywny jeden naraz) | -| `api.registerMemoryCapability(capability)` | Ujednoliconą możliwość pamięci | -| `api.registerMemoryPromptSection(builder)` | Builder sekcji promptu pamięci | -| `api.registerMemoryFlushPlan(resolver)` | Resolver planu flush pamięci | -| `api.registerMemoryRuntime(runtime)` | Adapter runtime pamięci | +| Method | What it registers | +| ------------------------------------------ | ------------------------------------- | +| `api.registerContextEngine(id, factory)` | Silnik kontekstu (aktywny naraz jest jeden) | +| `api.registerMemoryCapability(capability)` | Ujednolicona capability pamięci | +| `api.registerMemoryPromptSection(builder)` | Konstruktor sekcji promptu pamięci | +| `api.registerMemoryFlushPlan(resolver)` | Resolver planu opróżniania pamięci | +| `api.registerMemoryRuntime(runtime)` | Adapter runtime pamięci | ### Adaptery embeddingów pamięci -| Metoda | Co rejestruje | -| ---------------------------------------------- | --------------------------------------------- | +| Method | What it registers | +| ---------------------------------------------- | ---------------------------------------------- | | `api.registerMemoryEmbeddingProvider(adapter)` | Adapter embeddingów pamięci dla aktywnego pluginu | -- `registerMemoryCapability` to preferowane wyłączne API pluginu pamięci. -- `registerMemoryCapability` może również udostępniać `publicArtifacts.listArtifacts(...)`, - aby pluginy towarzyszące mogły korzystać z eksportowanych artefaktów pamięci przez - `openclaw/plugin-sdk/memory-host-core` zamiast sięgać do prywatnego układu konkretnego - pluginu pamięci. -- `registerMemoryPromptSection`, `registerMemoryFlushPlan` oraz - `registerMemoryRuntime` to starsze, zgodne wstecz wyłączne API pluginów pamięci. -- `registerMemoryEmbeddingProvider` pozwala aktywnemu pluginowi pamięci rejestrować jeden +- `registerMemoryCapability` to preferowane wyłączne API pluginów pamięci. +- `registerMemoryCapability` może też udostępniać `publicArtifacts.listArtifacts(...)`, + aby pluginy towarzyszące mogły używać eksportowanych artefaktów pamięci przez + `openclaw/plugin-sdk/memory-host-core` zamiast sięgać do prywatnego układu + konkretnego pluginu pamięci. +- `registerMemoryPromptSection`, `registerMemoryFlushPlan` i + `registerMemoryRuntime` to zgodne wstecz, wyłączne API starszych pluginów pamięci. +- `registerMemoryEmbeddingProvider` pozwala aktywnemu pluginowi pamięci zarejestrować jeden lub więcej identyfikatorów adapterów embeddingów (na przykład `openai`, `gemini` lub własny identyfikator zdefiniowany przez plugin). - Konfiguracja użytkownika, taka jak `agents.defaults.memorySearch.provider` i - `agents.defaults.memorySearch.fallback`, rozwiązuje się względem tych zarejestrowanych + `agents.defaults.memorySearch.fallback`, jest rozstrzygana względem tych zarejestrowanych identyfikatorów adapterów. ### Zdarzenia i cykl życia -| Metoda | Co robi | -| -------------------------------------------- | ------------------------------ | -| `api.on(hookName, handler, opts?)` | Typowany hook cyklu życia | -| `api.onConversationBindingResolved(handler)` | Callback rozwiązania powiązania konwersacji | +| Method | What it does | +| -------------------------------------------- | ----------------------------- | +| `api.on(hookName, handler, opts?)` | Typowany hook cyklu życia | +| `api.onConversationBindingResolved(handler)` | Callback rozstrzygnięcia powiązania rozmowy | ### Semantyka decyzji hooków -- `before_tool_call`: zwrócenie `{ block: true }` jest rozstrzygające. Gdy dowolny handler to ustawi, handlery o niższym priorytecie są pomijane. +- `before_tool_call`: zwrócenie `{ block: true }` jest ostateczne. Gdy dowolny handler to ustawi, handlery o niższym priorytecie są pomijane. - `before_tool_call`: zwrócenie `{ block: false }` jest traktowane jako brak decyzji (tak samo jak pominięcie `block`), a nie jako nadpisanie. -- `before_install`: zwrócenie `{ block: true }` jest rozstrzygające. Gdy dowolny handler to ustawi, handlery o niższym priorytecie są pomijane. +- `before_install`: zwrócenie `{ block: true }` jest ostateczne. Gdy dowolny handler to ustawi, handlery o niższym priorytecie są pomijane. - `before_install`: zwrócenie `{ block: false }` jest traktowane jako brak decyzji (tak samo jak pominięcie `block`), a nie jako nadpisanie. -- `reply_dispatch`: zwrócenie `{ handled: true, ... }` jest rozstrzygające. Gdy dowolny handler przejmie dispatch, handlery o niższym priorytecie i domyślna ścieżka dispatchu modelu są pomijane. -- `message_sending`: zwrócenie `{ cancel: true }` jest rozstrzygające. Gdy dowolny handler to ustawi, handlery o niższym priorytecie są pomijane. +- `reply_dispatch`: zwrócenie `{ handled: true, ... }` jest ostateczne. Gdy dowolny handler przejmie dispatch, handlery o niższym priorytecie i domyślna ścieżka dispatchu modelu są pomijane. +- `message_sending`: zwrócenie `{ cancel: true }` jest ostateczne. Gdy dowolny handler to ustawi, handlery o niższym priorytecie są pomijane. - `message_sending`: zwrócenie `{ cancel: false }` jest traktowane jako brak decyzji (tak samo jak pominięcie `cancel`), a nie jako nadpisanie. ### Pola obiektu API -| Pole | Typ | Opis | -| ------------------------ | ------------------------- | --------------------------------------------------------------------------------------------- | -| `api.id` | `string` | Identyfikator pluginu | -| `api.name` | `string` | Nazwa wyświetlana | -| `api.version` | `string?` | Wersja pluginu (opcjonalnie) | -| `api.description` | `string?` | Opis pluginu (opcjonalnie) | -| `api.source` | `string` | Ścieżka źródłowa pluginu | -| `api.rootDir` | `string?` | Katalog główny pluginu (opcjonalnie) | -| `api.config` | `OpenClawConfig` | Bieżący snapshot konfiguracji (aktywny snapshot runtime w pamięci, gdy dostępny) | -| `api.pluginConfig` | `Record` | Konfiguracja specyficzna dla pluginu z `plugins.entries..config` | -| `api.runtime` | `PluginRuntime` | [Runtime Helpers](/pl/plugins/sdk-runtime) | -| `api.logger` | `PluginLogger` | Logger o ograniczonym zakresie (`debug`, `info`, `warn`, `error`) | +| Field | Type | Description | +| ------------------------ | ------------------------- | ------------------------------------------------------------------------------------------- | +| `api.id` | `string` | Identyfikator pluginu | +| `api.name` | `string` | Nazwa wyświetlana | +| `api.version` | `string?` | Wersja pluginu (opcjonalnie) | +| `api.description` | `string?` | Opis pluginu (opcjonalnie) | +| `api.source` | `string` | Ścieżka źródłowa pluginu | +| `api.rootDir` | `string?` | Katalog główny pluginu (opcjonalnie) | +| `api.config` | `OpenClawConfig` | Bieżąca migawka konfiguracji (aktywna migawka runtime w pamięci, gdy jest dostępna) | +| `api.pluginConfig` | `Record` | Konfiguracja specyficzna dla pluginu z `plugins.entries..config` | +| `api.runtime` | `PluginRuntime` | [Helpery runtime](/pl/plugins/sdk-runtime) | +| `api.logger` | `PluginLogger` | Logger o ograniczonym zakresie (`debug`, `info`, `warn`, `error`) | | `api.registrationMode` | `PluginRegistrationMode` | Bieżący tryb ładowania; `"setup-runtime"` to lekkie okno uruchamiania/konfiguracji przed pełnym wejściem | -| `api.resolvePath(input)` | `(string) => string` | Rozwiązanie ścieżki względem katalogu głównego pluginu | +| `api.resolvePath(input)` | `(string) => string` | Rozstrzyga ścieżkę względem katalogu głównego pluginu | ## Konwencja modułów wewnętrznych @@ -457,7 +459,7 @@ Wewnątrz pluginu używaj lokalnych plików barrel do importów wewnętrznych: ``` my-plugin/ - api.ts # Publiczne eksporty dla zewnętrznych konsumentów + api.ts # Publiczne eksporty dla odbiorców zewnętrznych runtime-api.ts # Eksporty runtime tylko do użytku wewnętrznego index.ts # Punkt wejścia pluginu setup-entry.ts # Lekki punkt wejścia tylko do konfiguracji (opcjonalnie) @@ -465,41 +467,41 @@ my-plugin/ Nigdy nie importuj własnego pluginu przez `openclaw/plugin-sdk/` - w kodzie produkcyjnym. Prowadź importy wewnętrzne przez `./api.ts` lub + z kodu produkcyjnego. Kieruj importy wewnętrzne przez `./api.ts` lub `./runtime-api.ts`. Ścieżka SDK jest wyłącznie kontraktem zewnętrznym. -Publiczne powierzchnie dołączonych pluginów ładowane przez fasady (`api.ts`, `runtime-api.ts`, -`index.ts`, `setup-entry.ts` i podobne publiczne pliki wejściowe) preferują teraz -aktywny snapshot konfiguracji runtime, gdy OpenClaw już działa. Jeśli snapshot runtime -nie istnieje jeszcze, wracają do rozpoznanego pliku konfiguracyjnego na dysku. +Publiczne powierzchnie wbudowanych pluginów ładowane przez fasadę (`api.ts`, `runtime-api.ts`, +`index.ts`, `setup-entry.ts` i podobne publiczne pliki wejściowe) teraz preferują +aktywną migawkę konfiguracji runtime, gdy OpenClaw już działa. Jeśli migawka runtime +jeszcze nie istnieje, wracają do rozstrzygniętego pliku konfiguracji na dysku. -Pluginy dostawców mogą także ujawniać wąski lokalny barrel kontraktu pluginu, gdy -helper jest celowo specyficzny dla dostawcy i jeszcze nie należy do ogólnego subpath SDK. -Aktualny dołączony przykład: dostawca Anthropic przechowuje swoje helpery -strumieni Claude we własnym publicznym interfejsie `api.ts` / `contract-api.ts` zamiast -promować logikę nagłówków beta Anthropic i `service_tier` do ogólnego -kontraktu `plugin-sdk/*`. +Pluginy dostawców mogą także udostępniać wąski lokalny barrel kontraktu pluginu, gdy +helper jest celowo specyficzny dla dostawcy i jeszcze nie należy do ogólnej ścieżki podrzędnej SDK. +Aktualny wbudowany przykład: dostawca Anthropic przechowuje helpery strumienia Claude +we własnej publicznej ścieżce `api.ts` / `contract-api.ts` zamiast promować logikę +nagłówka beta Anthropic i `service_tier` do ogólnego kontraktu +`plugin-sdk/*`. -Inne aktualne dołączone przykłady: +Inne aktualne wbudowane przykłady: -- `@openclaw/openai-provider`: `api.ts` eksportuje buildery dostawców, - helpery modeli domyślnych i buildery dostawców realtime -- `@openclaw/openrouter-provider`: `api.ts` eksportuje builder dostawcy oraz +- `@openclaw/openai-provider`: `api.ts` eksportuje konstruktory dostawców, + helpery modeli domyślnych i konstruktory dostawców realtime +- `@openclaw/openrouter-provider`: `api.ts` eksportuje konstruktor dostawcy oraz helpery onboardingu/konfiguracji - Produkcyjny kod rozszerzeń powinien także unikać importów `openclaw/plugin-sdk/`. - Jeśli helper jest rzeczywiście współdzielony, przenieś go do neutralnego subpath SDK, - takiego jak `openclaw/plugin-sdk/speech`, `.../provider-model-shared` lub innej - powierzchni zorientowanej na możliwości zamiast łączyć dwa pluginy ze sobą. + Kod produkcyjny rozszerzeń powinien też unikać importów `openclaw/plugin-sdk/`. + Jeśli helper jest rzeczywiście współdzielony, przenieś go do neutralnej ścieżki podrzędnej SDK, + takiej jak `openclaw/plugin-sdk/speech`, `.../provider-model-shared` lub innej + powierzchni zorientowanej na capability, zamiast sprzęgać dwa pluginy ze sobą. ## Powiązane -- [Entry Points](/pl/plugins/sdk-entrypoints) — opcje `definePluginEntry` i `defineChannelPluginEntry` -- [Runtime Helpers](/pl/plugins/sdk-runtime) — pełna referencja przestrzeni nazw `api.runtime` -- [Setup and Config](/pl/plugins/sdk-setup) — pakowanie, manifesty, schematy konfiguracji -- [Testing](/pl/plugins/sdk-testing) — narzędzia testowe i reguły lint -- [SDK Migration](/pl/plugins/sdk-migration) — migracja ze starych powierzchni -- [Plugin Internals](/pl/plugins/architecture) — szczegółowa architektura i model możliwości +- [Punkty wejścia](/pl/plugins/sdk-entrypoints) — opcje `definePluginEntry` i `defineChannelPluginEntry` +- [Helpery runtime](/pl/plugins/sdk-runtime) — pełna dokumentacja przestrzeni nazw `api.runtime` +- [Konfiguracja i config](/pl/plugins/sdk-setup) — pakowanie, manifesty, schematy konfiguracji +- [Testowanie](/pl/plugins/sdk-testing) — narzędzia testowe i reguły lint +- [Migracja SDK](/pl/plugins/sdk-migration) — migracja ze zdeprecjonowanych powierzchni +- [Wnętrze pluginów](/pl/plugins/architecture) — szczegółowa architektura i model capabilities diff --git a/docs/pl/providers/index.md b/docs/pl/providers/index.md index bd9294443..e1c41c05a 100644 --- a/docs/pl/providers/index.md +++ b/docs/pl/providers/index.md @@ -1,29 +1,29 @@ --- read_when: - - Chcesz wybrać providera modeli + - Chcesz wybrać dostawcę modelu - Potrzebujesz szybkiego przeglądu obsługiwanych backendów LLM -summary: Providerzy modeli (LLM-y) obsługiwani przez OpenClaw -title: Katalog providerów +summary: Dostawcy modeli (LLM) obsługiwani przez OpenClaw +title: Katalog dostawców x-i18n: - generated_at: "2026-04-07T09:48:56Z" + generated_at: "2026-04-08T02:17:13Z" model: gpt-5.4 provider: openai - source_hash: 39d9ace35fd9452a4fb510fd980d251b6e51480e4647f051020bee2f1f2222e1 + source_hash: e7bee5528b7fc9a982b3d0eaa4930cb77f7bded19a47aec00572b6fcbd823a70 source_path: providers/index.md workflow: 15 --- -# Providerzy modeli +# Dostawcy modeli -OpenClaw może korzystać z wielu providerów LLM. Wybierz providera, uwierzytelnij się, a następnie ustaw -model domyślny jako `provider/model`. +OpenClaw może korzystać z wielu dostawców LLM. Wybierz dostawcę, uwierzytelnij się, a następnie ustaw +domyślny model jako `provider/model`. -Szukasz dokumentacji kanałów czatu (WhatsApp/Telegram/Discord/Slack/Mattermost (plugin)/itd.)? Zobacz [Channels](/pl/channels). +Szukasz dokumentacji kanałów czatu (WhatsApp/Telegram/Discord/Slack/Mattermost (plugin)/itp.)? Zobacz [Kanały](/pl/channels). ## Szybki start -1. Uwierzytelnij się u providera (zwykle przez `openclaw onboard`). -2. Ustaw model domyślny: +1. Uwierzytelnij się u dostawcy (zwykle przez `openclaw onboard`). +2. Ustaw domyślny model: ```json5 { @@ -31,7 +31,7 @@ Szukasz dokumentacji kanałów czatu (WhatsApp/Telegram/Discord/Slack/Mattermost } ``` -## Dokumentacja providerów +## Dokumentacja dostawców - [Alibaba Model Studio](/pl/providers/alibaba) - [Amazon Bedrock](/pl/providers/bedrock) @@ -47,15 +47,16 @@ Szukasz dokumentacji kanałów czatu (WhatsApp/Telegram/Discord/Slack/Mattermost - [GitHub Copilot](/pl/providers/github-copilot) - [Modele GLM](/pl/providers/glm) - [Google (Gemini)](/pl/providers/google) -- [Groq (wnioskowanie LPU)](/pl/providers/groq) -- [Hugging Face (Inference)](/pl/providers/huggingface) +- [Groq (inferencja LPU)](/pl/providers/groq) +- [Hugging Face (inferencja)](/pl/providers/huggingface) +- [inferrs (modele lokalne)](/pl/providers/inferrs) - [Kilocode](/pl/providers/kilocode) -- [LiteLLM (ujednolicony gateway)](/pl/providers/litellm) +- [LiteLLM (ujednolicona brama)](/pl/providers/litellm) - [MiniMax](/pl/providers/minimax) - [Mistral](/pl/providers/mistral) - [Moonshot AI (Kimi + Kimi Coding)](/pl/providers/moonshot) - [NVIDIA](/pl/providers/nvidia) -- [Ollama (modele chmurowe + lokalne)](/pl/providers/ollama) +- [Ollama (chmura + modele lokalne)](/pl/providers/ollama) - [OpenAI (API + Codex)](/pl/providers/openai) - [OpenCode](/pl/providers/opencode) - [OpenCode Go](/pl/providers/opencode-go) @@ -80,16 +81,16 @@ Szukasz dokumentacji kanałów czatu (WhatsApp/Telegram/Discord/Slack/Mattermost ## Wspólne strony przeglądowe - [Dodatkowe dołączone warianty](/pl/providers/models#additional-bundled-provider-variants) - Anthropic Vertex, Copilot Proxy i Gemini CLI OAuth -- [Generowanie obrazów](/pl/tools/image-generation) - Wspólne narzędzie `image_generate`, wybór providera i failover -- [Generowanie muzyki](/pl/tools/music-generation) - Wspólne narzędzie `music_generate`, wybór providera i failover -- [Generowanie wideo](/pl/tools/video-generation) - Wspólne narzędzie `video_generate`, wybór providera i failover +- [Generowanie obrazów](/pl/tools/image-generation) - Współdzielone narzędzie `image_generate`, wybór dostawcy i failover +- [Generowanie muzyki](/pl/tools/music-generation) - Współdzielone narzędzie `music_generate`, wybór dostawcy i failover +- [Generowanie wideo](/pl/tools/video-generation) - Współdzielone narzędzie `video_generate`, wybór dostawcy i failover -## Providerzy transkrypcji +## Dostawcy transkrypcji - [Deepgram (transkrypcja audio)](/pl/providers/deepgram) ## Narzędzia społeczności -- [Claude Max API Proxy](/pl/providers/claude-max-api-proxy) - Proxy społecznościowe dla poświadczeń subskrypcji Claude (przed użyciem zweryfikuj zasady/warunki Anthropic) +- [Claude Max API Proxy](/pl/providers/claude-max-api-proxy) - Społecznościowy proxy dla poświadczeń subskrypcji Claude (przed użyciem zweryfikuj zasady/warunki Anthropic) -Pełny katalog providerów (xAI, Groq, Mistral itd.) oraz zaawansowaną konfigurację znajdziesz w [Model providers](/pl/concepts/model-providers). +Pełny katalog dostawców (xAI, Groq, Mistral itd.) oraz zaawansowaną konfigurację znajdziesz w [Dostawcy modeli](/pl/concepts/model-providers). diff --git a/docs/pl/providers/inferrs.md b/docs/pl/providers/inferrs.md new file mode 100644 index 000000000..4c2dacbb5 --- /dev/null +++ b/docs/pl/providers/inferrs.md @@ -0,0 +1,179 @@ +--- +read_when: + - Chcesz uruchomić OpenClaw z lokalnym serwerem inferrs + - Udostępniasz Gemma lub inny model przez inferrs + - Potrzebujesz dokładnych flag zgodności OpenClaw dla inferrs +summary: Uruchamianie OpenClaw przez inferrs (lokalny serwer zgodny z OpenAI) +title: inferrs +x-i18n: + generated_at: "2026-04-08T02:17:28Z" + model: gpt-5.4 + provider: openai + source_hash: d84f660d49a682d0c0878707eebe1bc1e83dd115850687076ea3938b9f9c86c6 + source_path: providers/inferrs.md + workflow: 15 +--- + +# inferrs + +[inferrs](https://github.com/ericcurtin/inferrs) może udostępniać lokalne modele za +interfejsem API `/v1` zgodnym z OpenAI. OpenClaw współpracuje z `inferrs` przez ogólną +ścieżkę `openai-completions`. + +`inferrs` najlepiej obecnie traktować jako niestandardowy, samodzielnie hostowany backend +zgodny z OpenAI, a nie dedykowaną wtyczkę dostawcy OpenClaw. + +## Szybki start + +1. Uruchom `inferrs` z modelem. + +Przykład: + +```bash +inferrs serve gg-hf-gg/gemma-4-E2B-it \ + --host 127.0.0.1 \ + --port 8080 \ + --device metal +``` + +2. Sprawdź, czy serwer jest osiągalny. + +```bash +curl http://127.0.0.1:8080/health +curl http://127.0.0.1:8080/v1/models +``` + +3. Dodaj jawny wpis dostawcy OpenClaw i skieruj na niego swój model domyślny. + +## Pełny przykład konfiguracji + +Ten przykład używa Gemma 4 na lokalnym serwerze `inferrs`. + +```json5 +{ + agents: { + defaults: { + model: { primary: "inferrs/gg-hf-gg/gemma-4-E2B-it" }, + models: { + "inferrs/gg-hf-gg/gemma-4-E2B-it": { + alias: "Gemma 4 (inferrs)", + }, + }, + }, + }, + models: { + mode: "merge", + providers: { + inferrs: { + baseUrl: "http://127.0.0.1:8080/v1", + apiKey: "inferrs-local", + api: "openai-completions", + models: [ + { + id: "gg-hf-gg/gemma-4-E2B-it", + name: "Gemma 4 E2B (inferrs)", + reasoning: false, + input: ["text"], + cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }, + contextWindow: 131072, + maxTokens: 4096, + compat: { + requiresStringContent: true, + }, + }, + ], + }, + }, + }, +} +``` + +## Dlaczego `requiresStringContent` ma znaczenie + +Niektóre ścieżki Chat Completions w `inferrs` akceptują tylko ciąg znaków w +`messages[].content`, a nie strukturalne tablice części treści. + +Jeśli uruchomienia OpenClaw kończą się błędem takim jak: + +```text +messages[1].content: invalid type: sequence, expected a string +``` + +ustaw: + +```json5 +compat: { + requiresStringContent: true +} +``` + +OpenClaw spłaszczy części treści zawierające wyłącznie tekst do zwykłych ciągów znaków przed wysłaniem +żądania. + +## Zastrzeżenie dotyczące Gemma i schematu narzędzi + +Niektóre obecne kombinacje `inferrs` + Gemma akceptują małe, bezpośrednie +żądania `/v1/chat/completions`, ale nadal kończą się niepowodzeniem przy pełnych turach +runtime agenta OpenClaw. + +Jeśli tak się dzieje, najpierw spróbuj tego: + +```json5 +compat: { + requiresStringContent: true, + supportsTools: false +} +``` + +To wyłącza powierzchnię schematu narzędzi OpenClaw dla modelu i może zmniejszyć presję promptu +na bardziej restrykcyjnych lokalnych backendach. + +Jeśli małe bezpośrednie żądania nadal działają, ale zwykłe tury agenta OpenClaw wciąż +powodują awarie wewnątrz `inferrs`, pozostały problem zwykle leży po stronie zachowania modelu/serwera upstream, a nie warstwy transportowej OpenClaw. + +## Ręczny test smoke + +Po konfiguracji przetestuj obie warstwy: + +```bash +curl http://127.0.0.1:8080/v1/chat/completions \ + -H 'content-type: application/json' \ + -d '{"model":"gg-hf-gg/gemma-4-E2B-it","messages":[{"role":"user","content":"What is 2 + 2?"}],"stream":false}' + +openclaw infer model run \ + --model inferrs/gg-hf-gg/gemma-4-E2B-it \ + --prompt "What is 2 + 2? Reply with one short sentence." \ + --json +``` + +Jeśli pierwsze polecenie działa, ale drugie kończy się niepowodzeniem, skorzystaj z poniższych uwag +dotyczących rozwiązywania problemów. + +## Rozwiązywanie problemów + +- `curl /v1/models` kończy się niepowodzeniem: `inferrs` nie działa, nie jest osiągalny lub nie + jest powiązany z oczekiwanym hostem/portem. +- `messages[].content ... expected a string`: ustaw + `compat.requiresStringContent: true`. +- Bezpośrednie małe wywołania `/v1/chat/completions` przechodzą, ale `openclaw infer model run` + kończy się niepowodzeniem: spróbuj `compat.supportsTools: false`. +- OpenClaw nie dostaje już błędów schematu, ale `inferrs` nadal ulega awarii przy większych + turach agenta: potraktuj to jako ograniczenie `inferrs` lub modelu upstream i zmniejsz + presję promptu albo zmień lokalny backend/model. + +## Zachowanie w stylu proxy + +`inferrs` jest traktowany jako backend `/v1` zgodny z OpenAI w stylu proxy, a nie +natywny endpoint OpenAI. + +- natywne kształtowanie żądań tylko dla OpenAI nie ma tu zastosowania +- brak `service_tier`, brak `store` dla Responses, brak wskazówek prompt-cache i brak + kształtowania ładunku zgodności reasoning OpenAI +- ukryte nagłówki atrybucji OpenClaw (`originator`, `version`, `User-Agent`) + nie są wstrzykiwane do niestandardowych adresów `inferrs` base URLs + +## Zobacz też + +- [Modele lokalne](/pl/gateway/local-models) +- [Rozwiązywanie problemów z gatewayem](/pl/gateway/troubleshooting#local-openai-compatible-backend-passes-direct-probes-but-agent-runs-fail) +- [Dostawcy modeli](/pl/concepts/model-providers) diff --git a/docs/pl/providers/nvidia.md b/docs/pl/providers/nvidia.md index 963a8f67e..20e94b497 100644 --- a/docs/pl/providers/nvidia.md +++ b/docs/pl/providers/nvidia.md @@ -1,21 +1,21 @@ --- read_when: - - Chcesz używać modeli NVIDIA w OpenClaw + - Chcesz używać otwartych modeli w OpenClaw za darmo - Potrzebujesz konfiguracji NVIDIA_API_KEY summary: Używaj zgodnego z OpenAI API NVIDIA w OpenClaw title: NVIDIA x-i18n: - generated_at: "2026-04-05T14:03:12Z" + generated_at: "2026-04-08T02:17:20Z" model: gpt-5.4 provider: openai - source_hash: a24c5e46c0cf0fbc63bf09c772b486dd7f8f4b52e687d3b835bb54a1176b28da + source_hash: b00f8cedaf223a33ba9f6a6dd8cf066d88cebeea52d391b871e435026182228a source_path: providers/nvidia.md workflow: 15 --- # NVIDIA -NVIDIA udostępnia zgodne z OpenAI API pod adresem `https://integrate.api.nvidia.com/v1` dla modeli Nemotron i NeMo. Uwierzytelnianie odbywa się przez klucz API z [NVIDIA NGC](https://catalog.ngc.nvidia.com/). +NVIDIA udostępnia zgodne z OpenAI API pod adresem `https://integrate.api.nvidia.com/v1` dla otwartych modeli za darmo. Uwierzytelnij się za pomocą klucza API z [build.nvidia.com](https://build.nvidia.com/settings/api-keys). ## Konfiguracja CLI @@ -24,12 +24,12 @@ Wyeksportuj klucz raz, a następnie uruchom onboarding i ustaw model NVIDIA: ```bash export NVIDIA_API_KEY="nvapi-..." openclaw onboard --auth-choice skip -openclaw models set nvidia/nvidia/llama-3.1-nemotron-70b-instruct +openclaw models set nvidia/nvidia/nemotron-3-super-120b-a12b ``` -Jeśli nadal przekazujesz `--token`, pamiętaj, że trafia on do historii powłoki i wyjścia `ps`; jeśli to możliwe, preferuj zmienną env. +Jeśli nadal przekazujesz `--token`, pamiętaj, że trafia on do historii powłoki i danych wyjściowych `ps`; jeśli to możliwe, preferuj zmienną środowiskową. -## Fragment config +## Fragment konfiguracji ```json5 { @@ -44,7 +44,7 @@ Jeśli nadal przekazujesz `--token`, pamiętaj, że trafia on do historii powło }, agents: { defaults: { - model: { primary: "nvidia/nvidia/llama-3.1-nemotron-70b-instruct" }, + model: { primary: "nvidia/nvidia/nemotron-3-super-120b-a12b" }, }, }, } @@ -52,14 +52,15 @@ Jeśli nadal przekazujesz `--token`, pamiętaj, że trafia on do historii powło ## Identyfikatory modeli -| Model ref | Name | Context | Max output | -| ---------------------------------------------------- | ---------------------------------------- | ------- | ---------- | -| `nvidia/nvidia/llama-3.1-nemotron-70b-instruct` | NVIDIA Llama 3.1 Nemotron 70B Instruct | 131,072 | 4,096 | -| `nvidia/meta/llama-3.3-70b-instruct` | Meta Llama 3.3 70B Instruct | 131,072 | 4,096 | -| `nvidia/nvidia/mistral-nemo-minitron-8b-8k-instruct` | NVIDIA Mistral NeMo Minitron 8B Instruct | 8,192 | 2,048 | +| Model ref | Nazwa | Kontekst | Maks. wynik | +| ------------------------------------------ | ---------------------------- | -------- | ----------- | +| `nvidia/nvidia/nemotron-3-super-120b-a12b` | NVIDIA Nemotron 3 Super 120B | 262,144 | 8,192 | +| `nvidia/moonshotai/kimi-k2.5` | Kimi K2.5 | 262,144 | 8,192 | +| `nvidia/minimaxai/minimax-m2.5` | Minimax M2.5 | 196,608 | 8,192 | +| `nvidia/z-ai/glm5` | GLM 5 | 202,752 | 8,192 | ## Uwagi -- Endpoint `/v1` zgodny z OpenAI; użyj klucza API z NVIDIA NGC. -- Provider włącza się automatycznie, gdy ustawiono `NVIDIA_API_KEY`. -- Dołączony katalog jest statyczny; koszty domyślnie mają wartość `0` w źródłach. +- Zgodny z OpenAI punkt końcowy `/v1`; użyj klucza API z [build.nvidia.com](https://build.nvidia.com/). +- Dostawca włącza się automatycznie, gdy ustawiono `NVIDIA_API_KEY`. +- Dołączony katalog jest statyczny; koszty domyślnie wynoszą `0` w źródle. diff --git a/docs/pl/providers/ollama.md b/docs/pl/providers/ollama.md index 6874c8955..5f75a3825 100644 --- a/docs/pl/providers/ollama.md +++ b/docs/pl/providers/ollama.md @@ -1,24 +1,24 @@ --- read_when: - Chcesz uruchamiać OpenClaw z modelami chmurowymi lub lokalnymi przez Ollama - - Potrzebujesz wskazówek dotyczących instalacji i konfiguracji Ollama + - Potrzebujesz wskazówek dotyczących konfiguracji i ustawień Ollama summary: Uruchamianie OpenClaw z Ollama (modele chmurowe i lokalne) title: Ollama x-i18n: - generated_at: "2026-04-05T14:04:01Z" + generated_at: "2026-04-08T02:17:58Z" model: gpt-5.4 provider: openai - source_hash: 337b8ec3a7756e591e6d6f82e8ad13417f0f20c394ec540e8fc5756e0fc13c29 + source_hash: 222ec68f7d4bb29cc7796559ddef1d5059f5159e7a51e2baa3a271ddb3abb716 source_path: providers/ollama.md workflow: 15 --- # Ollama -Ollama to lokalne środowisko uruchomieniowe LLM, które ułatwia uruchamianie modeli open source na własnej maszynie. OpenClaw integruje się z natywnym API Ollama (`/api/chat`), obsługuje streaming i wywoływanie narzędzi oraz może automatycznie wykrywać lokalne modele Ollama, gdy włączysz to przez `OLLAMA_API_KEY` (lub profil auth) i nie zdefiniujesz jawnego wpisu `models.providers.ollama`. +Ollama to lokalne środowisko uruchomieniowe LLM, które ułatwia uruchamianie modeli open source na Twoim komputerze. OpenClaw integruje się z natywnym API Ollama (`/api/chat`), obsługuje streaming i wywoływanie narzędzi oraz może automatycznie wykrywać lokalne modele Ollama, gdy włączysz to przez `OLLAMA_API_KEY` (lub profil uwierzytelniania) i nie zdefiniujesz jawnego wpisu `models.providers.ollama`. -**Użytkownicy zdalnego Ollama**: Nie używaj URL zgodnego z OpenAI `/v1` (`http://host:11434/v1`) z OpenClaw. To psuje wywoływanie narzędzi i modele mogą zwracać surowy JSON narzędzi jako zwykły tekst. Zamiast tego użyj natywnego URL API Ollama: `baseUrl: "http://host:11434"` (bez `/v1`). +**Użytkownicy zdalnego Ollama**: Nie używaj zgodnego z OpenAI adresu URL `/v1` (`http://host:11434/v1`) z OpenClaw. Powoduje to uszkodzenie wywoływania narzędzi, a modele mogą zwracać surowy JSON narzędzi jako zwykły tekst. Zamiast tego użyj natywnego adresu URL API Ollama: `baseUrl: "http://host:11434"` (bez `/v1`). ## Szybki start @@ -33,13 +33,13 @@ openclaw onboard Wybierz **Ollama** z listy dostawców. Onboarding: -1. Poprosi o bazowy URL Ollama, pod którym twoja instancja jest dostępna (domyślnie `http://127.0.0.1:11434`). -2. Pozwoli wybrać **Cloud + Local** (modele chmurowe i lokalne) albo **Local** (tylko modele lokalne). -3. Otworzy w przeglądarce przepływ logowania, jeśli wybierzesz **Cloud + Local** i nie jesteś zalogowany w ollama.com. -4. Wykryje dostępne modele i zasugeruje ustawienia domyślne. +1. Poprosi o podstawowy adres URL Ollama, pod którym Twoja instancja jest dostępna (domyślnie `http://127.0.0.1:11434`). +2. Pozwoli wybrać **Cloud + Local** (modele chmurowe i lokalne) lub **Local** (tylko modele lokalne). +3. Otworzy w przeglądarce przepływ logowania, jeśli wybierzesz **Cloud + Local** i nie jesteś zalogowany do ollama.com. +4. Wykryje dostępne modele i zasugeruje wartości domyślne. 5. Automatycznie pobierze wybrany model, jeśli nie jest dostępny lokalnie. -Obsługiwany jest także tryb nieinteraktywny: +Obsługiwany jest również tryb nieinteraktywny: ```bash openclaw onboard --non-interactive \ @@ -47,7 +47,7 @@ openclaw onboard --non-interactive \ --accept-risk ``` -Opcjonalnie możesz podać niestandardowy bazowy URL lub model: +Opcjonalnie podaj niestandardowy podstawowy adres URL lub model: ```bash openclaw onboard --non-interactive \ @@ -61,17 +61,17 @@ openclaw onboard --non-interactive \ 1. Zainstaluj Ollama: [https://ollama.com/download](https://ollama.com/download) -2. Pobierz model lokalny, jeśli chcesz używać inferencji lokalnej: +2. Pobierz lokalny model, jeśli chcesz korzystać z inferencji lokalnej: ```bash -ollama pull glm-4.7-flash +ollama pull gemma4 # lub ollama pull gpt-oss:20b # lub ollama pull llama3.3 ``` -3. Jeśli chcesz także modele chmurowe, zaloguj się: +3. Jeśli chcesz korzystać także z modeli chmurowych, zaloguj się: ```bash ollama signin @@ -84,13 +84,13 @@ openclaw onboard ``` - `Local`: tylko modele lokalne -- `Cloud + Local`: modele lokalne plus modele chmurowe -- Modele chmurowe, takie jak `kimi-k2.5:cloud`, `minimax-m2.5:cloud` i `glm-5:cloud`, **nie** wymagają lokalnego `ollama pull` +- `Cloud + Local`: modele lokalne oraz modele chmurowe +- Modele chmurowe takie jak `kimi-k2.5:cloud`, `minimax-m2.7:cloud` i `glm-5.1:cloud` **nie** wymagają lokalnego `ollama pull` OpenClaw obecnie sugeruje: -- domyślny model lokalny: `glm-4.7-flash` -- domyślne modele chmurowe: `kimi-k2.5:cloud`, `minimax-m2.5:cloud`, `glm-5:cloud` +- domyślny model lokalny: `gemma4` +- domyślne modele chmurowe: `kimi-k2.5:cloud`, `minimax-m2.7:cloud`, `glm-5.1:cloud` 5. Jeśli wolisz konfigurację ręczną, włącz Ollama bezpośrednio dla OpenClaw (dowolna wartość działa; Ollama nie wymaga prawdziwego klucza): @@ -102,36 +102,36 @@ export OLLAMA_API_KEY="ollama-local" openclaw config set models.providers.ollama.apiKey "ollama-local" ``` -6. Sprawdź lub przełącz modele: +6. Sprawdź dostępne modele lub przełącz model: ```bash openclaw models list -openclaw models set ollama/glm-4.7-flash +openclaw models set ollama/gemma4 ``` -7. Lub ustaw domyślny model w konfiguracji: +7. Albo ustaw domyślny model w konfiguracji: ```json5 { agents: { defaults: { - model: { primary: "ollama/glm-4.7-flash" }, + model: { primary: "ollama/gemma4" }, }, }, } ``` -## Wykrywanie modeli (niejawny dostawca) +## Wykrywanie modeli (dostawca niejawny) -Gdy ustawisz `OLLAMA_API_KEY` (lub profil auth) i **nie** zdefiniujesz `models.providers.ollama`, OpenClaw wykrywa modele z lokalnej instancji Ollama pod adresem `http://127.0.0.1:11434`: +Gdy ustawisz `OLLAMA_API_KEY` (lub profil uwierzytelniania) i **nie** zdefiniujesz `models.providers.ollama`, OpenClaw wykryje modele z lokalnej instancji Ollama pod adresem `http://127.0.0.1:11434`: - Odpytuje `/api/tags` -- Używa mechanizmu best-effort do odpytań `/api/show`, aby odczytać `contextWindow`, gdy jest dostępne -- Oznacza `reasoning` przy użyciu heurystyki nazwy modelu (`r1`, `reasoning`, `think`) +- Używa najlepszego możliwego wyszukiwania `/api/show`, aby odczytać `contextWindow`, gdy jest dostępne +- Oznacza `reasoning` za pomocą heurystyki nazwy modelu (`r1`, `reasoning`, `think`) - Ustawia `maxTokens` na domyślny limit maksymalnej liczby tokenów Ollama używany przez OpenClaw - Ustawia wszystkie koszty na `0` -Pozwala to uniknąć ręcznego dodawania modeli, a jednocześnie utrzymuje katalog zgodny z lokalną instancją Ollama. +Pozwala to uniknąć ręcznego wpisywania modeli, jednocześnie utrzymując katalog zgodny z lokalną instancją Ollama. Aby zobaczyć, jakie modele są dostępne: @@ -148,24 +148,24 @@ ollama pull mistral Nowy model zostanie automatycznie wykryty i będzie dostępny do użycia. -Jeśli jawnie ustawisz `models.providers.ollama`, automatyczne wykrywanie zostanie pominięte i modele trzeba będzie zdefiniować ręcznie (patrz niżej). +Jeśli jawnie ustawisz `models.providers.ollama`, automatyczne wykrywanie zostanie pominięte i musisz zdefiniować modele ręcznie (zobacz poniżej). ## Konfiguracja -### Podstawowa konfiguracja (niejawne wykrywanie) +### Podstawowa konfiguracja (wykrywanie niejawne) -Najprostszy sposób włączenia Ollama to użycie zmiennej środowiskowej: +Najprostszym sposobem włączenia Ollama jest użycie zmiennej środowiskowej: ```bash export OLLAMA_API_KEY="ollama-local" ``` -### Jawna konfiguracja (modele ręczne) +### Konfiguracja jawna (ręczne modele) -Użyj jawnej konfiguracji, gdy: +Używaj jawnej konfiguracji, gdy: - Ollama działa na innym hoście lub porcie. -- Chcesz wymusić konkretne okna kontekstu lub listy modeli. +- Chcesz wymusić określone okna kontekstu lub listy modeli. - Chcesz w pełni ręcznie definiować modele. ```json5 @@ -193,9 +193,9 @@ Użyj jawnej konfiguracji, gdy: } ``` -Jeśli ustawiono `OLLAMA_API_KEY`, możesz pominąć `apiKey` we wpisie dostawcy, a OpenClaw uzupełni go na potrzeby sprawdzania dostępności. +Jeśli ustawiono `OLLAMA_API_KEY`, możesz pominąć `apiKey` we wpisie dostawcy, a OpenClaw uzupełni je na potrzeby sprawdzania dostępności. -### Niestandardowy bazowy URL (jawna konfiguracja) +### Niestandardowy podstawowy adres URL (konfiguracja jawna) Jeśli Ollama działa na innym hoście lub porcie (jawna konfiguracja wyłącza automatyczne wykrywanie, więc modele trzeba zdefiniować ręcznie): @@ -205,8 +205,8 @@ Jeśli Ollama działa na innym hoście lub porcie (jawna konfiguracja wyłącza providers: { ollama: { apiKey: "ollama-local", - baseUrl: "http://ollama-host:11434", // Bez /v1 - użyj natywnego URL API Ollama - api: "ollama", // Ustaw jawnie, aby zagwarantować natywne wywoływanie narzędzi + baseUrl: "http://ollama-host:11434", // Bez /v1 - użyj natywnego adresu URL API Ollama + api: "ollama", // Ustaw jawnie, aby zagwarantować natywne zachowanie wywoływania narzędzi }, }, }, @@ -214,12 +214,12 @@ Jeśli Ollama działa na innym hoście lub porcie (jawna konfiguracja wyłącza ``` -Nie dodawaj `/v1` do URL. Ścieżka `/v1` używa trybu zgodnego z OpenAI, w którym wywoływanie narzędzi nie jest niezawodne. Użyj bazowego URL Ollama bez sufiksu ścieżki. +Nie dodawaj `/v1` do adresu URL. Ścieżka `/v1` używa trybu zgodnego z OpenAI, w którym wywoływanie narzędzi nie jest niezawodne. Używaj podstawowego adresu URL Ollama bez sufiksu ścieżki. ### Wybór modelu -Po skonfigurowaniu wszystkie twoje modele Ollama są dostępne: +Po skonfigurowaniu wszystkie modele Ollama są dostępne: ```json5 { @@ -236,24 +236,24 @@ Po skonfigurowaniu wszystkie twoje modele Ollama są dostępne: ## Modele chmurowe -Modele chmurowe pozwalają uruchamiać modele hostowane w chmurze (na przykład `kimi-k2.5:cloud`, `minimax-m2.5:cloud`, `glm-5:cloud`) obok modeli lokalnych. +Modele chmurowe pozwalają uruchamiać modele hostowane w chmurze (na przykład `kimi-k2.5:cloud`, `minimax-m2.7:cloud`, `glm-5.1:cloud`) obok modeli lokalnych. -Aby używać modeli chmurowych, podczas konfiguracji wybierz tryb **Cloud + Local**. Kreator sprawdza, czy jesteś zalogowany, i w razie potrzeby otwiera w przeglądarce przepływ logowania. Jeśli nie można zweryfikować uwierzytelnienia, kreator wraca do domyślnych modeli lokalnych. +Aby używać modeli chmurowych, wybierz tryb **Cloud + Local** podczas konfiguracji. Kreator sprawdza, czy jesteś zalogowany, i w razie potrzeby otwiera w przeglądarce przepływ logowania. Jeśli nie można zweryfikować uwierzytelnienia, kreator przechodzi do domyślnych modeli lokalnych. Możesz też zalogować się bezpośrednio na [ollama.com/signin](https://ollama.com/signin). ## Ollama Web Search -OpenClaw obsługuje także **Ollama Web Search** jako wbudowanego dostawcę +OpenClaw obsługuje także **Ollama Web Search** jako dołączonego dostawcę `web_search`. - Używa skonfigurowanego hosta Ollama (`models.providers.ollama.baseUrl`, jeśli - ustawiono, w przeciwnym razie `http://127.0.0.1:11434`). + jest ustawione, w przeciwnym razie `http://127.0.0.1:11434`). - Nie wymaga klucza. -- Wymaga uruchomionego Ollama oraz zalogowania przez `ollama signin`. +- Wymaga uruchomionego Ollama i zalogowania przez `ollama signin`. -Wybierz **Ollama Web Search** podczas `openclaw onboard` albo -`openclaw configure --section web`, lub ustaw: +Wybierz **Ollama Web Search** podczas `openclaw onboard` lub +`openclaw configure --section web`, albo ustaw: ```json5 { @@ -267,13 +267,13 @@ Wybierz **Ollama Web Search** podczas `openclaw onboard` albo } ``` -Pełne informacje o konfiguracji i zachowaniu znajdziesz w [Ollama Web Search](/tools/ollama-search). +Pełną konfigurację i szczegóły działania znajdziesz w [Ollama Web Search](/pl/tools/ollama-search). ## Zaawansowane ### Modele reasoning -OpenClaw domyślnie traktuje modele o nazwach takich jak `deepseek-r1`, `reasoning` lub `think` jako modele obsługujące reasoning: +OpenClaw domyślnie traktuje modele o nazwach takich jak `deepseek-r1`, `reasoning` lub `think` jako zdolne do reasoning: ```bash ollama pull deepseek-r1:32b @@ -281,11 +281,11 @@ ollama pull deepseek-r1:32b ### Koszty modeli -Ollama jest bezpłatna i działa lokalnie, więc wszystkie koszty modeli są ustawione na $0. +Ollama jest darmowe i działa lokalnie, więc wszystkie koszty modeli są ustawione na $0. ### Konfiguracja streamingu -Integracja OpenClaw z Ollama domyślnie używa **natywnego API Ollama** (`/api/chat`), które w pełni obsługuje jednocześnie streaming i wywoływanie narzędzi. Nie jest wymagana żadna specjalna konfiguracja. +Integracja OpenClaw z Ollama domyślnie używa **natywnego API Ollama** (`/api/chat`), które w pełni obsługuje jednocześnie streaming i wywoływanie narzędzi. Nie jest potrzebna żadna specjalna konfiguracja. #### Starszy tryb zgodny z OpenAI @@ -293,7 +293,7 @@ Integracja OpenClaw z Ollama domyślnie używa **natywnego API Ollama** (`/api/c **Wywoływanie narzędzi nie jest niezawodne w trybie zgodnym z OpenAI.** Używaj tego trybu tylko wtedy, gdy potrzebujesz formatu OpenAI dla proxy i nie polegasz na natywnym zachowaniu wywoływania narzędzi. -Jeśli zamiast tego musisz użyć punktu końcowego zgodnego z OpenAI (na przykład za proxy, które obsługuje tylko format OpenAI), jawnie ustaw `api: "openai-completions"`: +Jeśli zamiast tego musisz używać punktu końcowego zgodnego z OpenAI (np. za proxy, które obsługuje tylko format OpenAI), ustaw jawnie `api: "openai-completions"`: ```json5 { @@ -311,9 +311,9 @@ Jeśli zamiast tego musisz użyć punktu końcowego zgodnego z OpenAI (na przyk } ``` -Ten tryb może nie obsługiwać jednocześnie streamingu i wywoływania narzędzi. Może być konieczne wyłączenie streamingu przez `params: { streaming: false }` w konfiguracji modelu. +Ten tryb może nie obsługiwać jednocześnie streamingu i wywoływania narzędzi. Może być konieczne wyłączenie streamingu za pomocą `params: { streaming: false }` w konfiguracji modelu. -Gdy `api: "openai-completions"` jest używane z Ollama, OpenClaw domyślnie wstrzykuje `options.num_ctx`, aby Ollama nie wracała po cichu do okna kontekstu 4096. Jeśli twoje proxy/upstream odrzuca nieznane pola `options`, wyłącz to zachowanie: +Gdy `api: "openai-completions"` jest używane z Ollama, OpenClaw domyślnie wstrzykuje `options.num_ctx`, aby Ollama nie przechodziło po cichu na okno kontekstu 4096. Jeśli Twoje proxy/upstream odrzuca nieznane pola `options`, wyłącz to zachowanie: ```json5 { @@ -333,19 +333,19 @@ Gdy `api: "openai-completions"` jest używane z Ollama, OpenClaw domyślnie wstr ### Okna kontekstu -Dla modeli wykrytych automatycznie OpenClaw używa okna kontekstu raportowanego przez Ollama, gdy jest dostępne, w przeciwnym razie wraca do domyślnego okna kontekstu Ollama używanego przez OpenClaw. Możesz nadpisać `contextWindow` i `maxTokens` w jawnej konfiguracji dostawcy. +Dla modeli wykrytych automatycznie OpenClaw używa okna kontekstu zgłaszanego przez Ollama, jeśli jest dostępne, w przeciwnym razie przechodzi na domyślne okno kontekstu Ollama używane przez OpenClaw. Możesz nadpisać `contextWindow` i `maxTokens` w jawnej konfiguracji dostawcy. ## Rozwiązywanie problemów ### Nie wykryto Ollama -Upewnij się, że Ollama działa, że ustawiono `OLLAMA_API_KEY` (lub profil auth), i że **nie** zdefiniowano jawnego wpisu `models.providers.ollama`: +Upewnij się, że Ollama działa, że ustawiono `OLLAMA_API_KEY` (lub profil uwierzytelniania) i że **nie** zdefiniowano jawnego wpisu `models.providers.ollama`: ```bash ollama serve ``` -Upewnij się też, że API jest dostępne: +Oraz że API jest dostępne: ```bash curl http://localhost:11434/api/tags @@ -353,16 +353,16 @@ curl http://localhost:11434/api/tags ### Brak dostępnych modeli -Jeśli twojego modelu nie ma na liście, zrób jedną z tych rzeczy: +Jeśli Twojego modelu nie ma na liście, zrób jedno z poniższych: -- Pobierz model lokalnie albo +- Pobierz model lokalnie, lub - Zdefiniuj model jawnie w `models.providers.ollama`. Aby dodać modele: ```bash ollama list # Zobacz, co jest zainstalowane -ollama pull glm-4.7-flash +ollama pull gemma4 ollama pull gpt-oss:20b ollama pull llama3.3 # Lub inny model ``` @@ -375,12 +375,12 @@ Sprawdź, czy Ollama działa na właściwym porcie: # Sprawdź, czy Ollama działa ps aux | grep ollama -# Lub uruchom Ollama ponownie +# Lub uruchom ponownie Ollama ollama serve ``` ## Zobacz także -- [Dostawcy modeli](/pl/concepts/model-providers) - przegląd wszystkich dostawców -- [Wybór modelu](/pl/concepts/models) - jak wybierać modele -- [Konfiguracja](/pl/gateway/configuration) - pełne odniesienie do konfiguracji +- [Dostawcy modeli](/pl/concepts/model-providers) - Przegląd wszystkich dostawców +- [Wybór modeli](/pl/concepts/models) - Jak wybierać modele +- [Konfiguracja](/pl/gateway/configuration) - Pełna dokumentacja konfiguracji diff --git a/docs/pl/refactor/qa.md b/docs/pl/refactor/qa.md new file mode 100644 index 000000000..5af7df008 --- /dev/null +++ b/docs/pl/refactor/qa.md @@ -0,0 +1,534 @@ +--- +x-i18n: + generated_at: "2026-04-08T02:18:06Z" + model: gpt-5.4 + provider: openai + source_hash: 0e156cc8e2fe946a0423862f937754a7caa1fe7e6863b50a80bff49a1c86e1e8 + source_path: refactor/qa.md + workflow: 15 +--- + +# Refaktoryzacja QA + +Status: wdrożono podstawową migrację. + +## Cel + +Przenieść QA OpenClaw z modelu rozdzielonych definicji do jednego źródła prawdy: + +- metadane scenariusza +- prompty wysyłane do modelu +- konfiguracja i czyszczenie +- logika harnessu +- asercje i kryteria sukcesu +- artefakty i wskazówki do raportów + +Pożądanym stanem końcowym jest generyczny harness QA, który wczytuje rozbudowane pliki definicji scenariuszy zamiast kodować większość zachowania na sztywno w TypeScript. + +## Stan obecny + +Główne źródło prawdy znajduje się teraz w `qa/scenarios.md`. + +Zaimplementowano: + +- `qa/scenarios.md` + - kanoniczny pakiet QA + - tożsamość operatora + - misja startowa + - metadane scenariuszy + - powiązania handlerów +- `extensions/qa-lab/src/scenario-catalog.ts` + - parser pakietu Markdown + walidacja zod +- `extensions/qa-lab/src/qa-agent-bootstrap.ts` + - renderowanie planu z pakietu Markdown +- `extensions/qa-lab/src/qa-agent-workspace.ts` + - inicjuje wygenerowane pliki zgodności oraz `QA_SCENARIOS.md` +- `extensions/qa-lab/src/suite.ts` + - wybiera wykonywalne scenariusze przez powiązania handlerów zdefiniowane w Markdown +- Protokół magistrali QA + UI + - generyczne załączniki inline do renderowania obrazów/wideo/audio/plików + +Pozostałe rozdzielone powierzchnie: + +- `extensions/qa-lab/src/suite.ts` + - nadal zawiera większość wykonywalnej niestandardowej logiki handlerów +- `extensions/qa-lab/src/report.ts` + - nadal wyprowadza strukturę raportu z wyników runtime + +Czyli rozdział źródła prawdy został naprawiony, ale wykonanie nadal jest w większości oparte na handlerach, a nie w pełni deklaratywne. + +## Jak naprawdę wygląda powierzchnia scenariuszy + +Odczyt obecnego zestawu pokazuje kilka odrębnych klas scenariuszy. + +### Prosta interakcja + +- bazowy kanał +- bazowe DM +- follow-up w wątku +- przełączanie modelu +- kontynuacja po zatwierdzeniu +- reakcja/edycja/usunięcie + +### Mutacja konfiguracji i runtime + +- wyłączenie skilla przez poprawkę config +- wybudzenie po restarcie po `config apply` +- przełączenie możliwości po restarcie config +- sprawdzenie dryfu inwentarza runtime + +### Asercje systemu plików i repozytorium + +- raport wykrywania source/docs +- zbudowanie Lobster Invaders +- wyszukiwanie artefaktu wygenerowanego obrazu + +### Orkiestracja pamięci + +- przywołanie pamięci +- narzędzia pamięci w kontekście kanału +- fallback po błędzie pamięci +- ranking pamięci sesji +- izolacja pamięci wątków +- przegląd memory dreaming + +### Integracja narzędzi i wtyczek + +- wywołanie MCP plugin-tools +- widoczność skilli +- hot install skilla +- natywne generowanie obrazów +- image roundtrip +- rozumienie obrazu z załącznika + +### Wieloturowe i wieloosobowe + +- przekazanie do podagenta +- synteza fanout podagentów +- przepływy w stylu odzyskiwania po restarcie + +Te kategorie są istotne, ponieważ determinują wymagania DSL. Płaska lista promptów + oczekiwanego tekstu nie wystarczy. + +## Kierunek + +### Jedno źródło prawdy + +Używać `qa/scenarios.md` jako redagowanego źródła prawdy. + +Pakiet powinien pozostać: + +- czytelny dla człowieka podczas przeglądu +- możliwy do sparsowania maszynowo +- wystarczająco bogaty, aby napędzać: + - wykonywanie zestawu + - bootstrap workspace QA + - metadane UI QA Lab + - prompty dokumentacji/wykrywania + - generowanie raportów + +### Preferowany format redagowania + +Używać Markdown jako formatu najwyższego poziomu, z osadzonym w nim strukturalnym YAML. + +Zalecany kształt: + +- YAML frontmatter + - id + - title + - surface + - tags + - docs refs + - code refs + - nadpisania modelu/dostawcy + - wymagania wstępne +- sekcje prozatorskie + - cel + - uwagi + - wskazówki do debugowania +- otoczone blokami YAML + - setup + - steps + - assertions + - cleanup + +Daje to: + +- lepszą czytelność PR niż ogromny JSON +- bogatszy kontekst niż czysty YAML +- ścisłe parsowanie i walidację zod + +Surowy JSON jest akceptowalny tylko jako pośrednia forma wygenerowana. + +## Proponowany kształt pliku scenariusza + +Przykład: + +````md +--- +id: image-generation-roundtrip +title: Roundtrip generowania obrazów +surface: image +tags: [media, image, roundtrip] +models: + primary: openai/gpt-5.4 +requires: + tools: [image_generate] + plugins: [openai, qa-channel] +docsRefs: + - docs/help/testing.md + - docs/concepts/model-providers.md +codeRefs: + - extensions/qa-lab/src/suite.ts + - src/gateway/chat-attachments.ts +--- + +# Cel + +Zweryfikować, że wygenerowane media są ponownie dołączane w turze follow-up. + +# Konfiguracja + +```yaml scenario.setup +- action: config.patch + patch: + agents: + defaults: + imageGenerationModel: + primary: openai/gpt-image-1 +- action: session.create + key: agent:qa:image-roundtrip +``` + +# Kroki + +```yaml scenario.steps +- action: agent.send + session: agent:qa:image-roundtrip + message: | + Kontrola generowania obrazu: wygeneruj obraz latarni morskiej QA i podsumuj go w jednym krótkim zdaniu. +- action: artifact.capture + kind: generated-image + promptSnippet: Kontrola generowania obrazu + saveAs: lighthouseImage +- action: agent.send + session: agent:qa:image-roundtrip + message: | + Kontrola inspekcji obrazu po roundtrip: opisz wygenerowany załącznik z latarnią morską w jednym krótkim zdaniu. + attachments: + - fromArtifact: lighthouseImage +``` + +# Oczekiwania + +```yaml scenario.expect +- assert: outbound.textIncludes + value: lighthouse +- assert: requestLog.matches + where: + promptIncludes: Kontrola inspekcji obrazu po roundtrip + imageInputCountGte: 1 +- assert: artifact.exists + ref: lighthouseImage +``` +```` + +## Możliwości runnera, które DSL musi obejmować + +Na podstawie obecnego zestawu generyczny runner potrzebuje więcej niż wykonywania promptów. + +### Działania środowiskowe i konfiguracyjne + +- `bus.reset` +- `gateway.waitHealthy` +- `channel.waitReady` +- `session.create` +- `thread.create` +- `workspace.writeSkill` + +### Działania tur agenta + +- `agent.send` +- `agent.wait` +- `bus.injectInbound` +- `bus.injectOutbound` + +### Działania konfiguracji i runtime + +- `config.get` +- `config.patch` +- `config.apply` +- `gateway.restart` +- `tools.effective` +- `skills.status` + +### Działania na plikach i artefaktach + +- `file.write` +- `file.read` +- `file.delete` +- `file.touchTime` +- `artifact.captureGeneratedImage` +- `artifact.capturePath` + +### Działania pamięci i cron + +- `memory.indexForce` +- `memory.searchCli` +- `doctor.memory.status` +- `cron.list` +- `cron.run` +- `cron.waitCompletion` +- `sessionTranscript.write` + +### Działania MCP + +- `mcp.callTool` + +### Asercje + +- `outbound.textIncludes` +- `outbound.inThread` +- `outbound.notInRoot` +- `tool.called` +- `tool.notPresent` +- `skill.visible` +- `skill.disabled` +- `file.contains` +- `memory.contains` +- `requestLog.matches` +- `sessionStore.matches` +- `cron.managedPresent` +- `artifact.exists` + +## Zmienne i odwołania do artefaktów + +DSL musi obsługiwać zapisane wyniki i późniejsze odwołania. + +Przykłady z obecnego zestawu: + +- utworzyć wątek, a potem ponownie użyć `threadId` +- utworzyć sesję, a potem ponownie użyć `sessionKey` +- wygenerować obraz, a potem dołączyć plik w następnej turze +- wygenerować ciąg markera wybudzenia, a potem potwierdzić, że pojawia się później + +Potrzebne możliwości: + +- `saveAs` +- `${vars.name}` +- `${artifacts.name}` +- typowane odwołania do ścieżek, kluczy sesji, identyfikatorów wątków, markerów, wyników narzędzi + +Bez obsługi zmiennych harness będzie dalej przeciekał logiką scenariuszy z powrotem do TypeScript. + +## Co powinno pozostać jako furtki awaryjne + +W pełni czysto deklaratywny runner nie jest realistyczny w fazie 1. + +Niektóre scenariusze są z natury silnie oparte na orkiestracji: + +- przegląd memory dreaming +- wybudzenie po restarcie po `config apply` +- przełączenie możliwości po restarcie config +- rozwiązywanie artefaktów wygenerowanych obrazów po znaczniku czasu/ścieżce +- ocena raportu wykrywania + +Na razie powinny używać jawnych niestandardowych handlerów. + +Zalecana zasada: + +- 85-90% deklaratywnie +- jawne kroki `customHandler` dla trudnej reszty +- tylko nazwane i udokumentowane niestandardowe handlery +- bez anonimowego kodu inline w pliku scenariusza + +To utrzymuje generyczny silnik w czystości, a jednocześnie pozwala robić postęp. + +## Zmiana architektury + +### Obecnie + +Markdown scenariuszy jest już źródłem prawdy dla: + +- wykonywania zestawu +- plików bootstrap workspace +- katalogu scenariuszy UI QA Lab +- metadanych raportów +- promptów wykrywania + +Wygenerowana zgodność: + +- zainicjalizowany workspace nadal zawiera `QA_KICKOFF_TASK.md` +- zainicjalizowany workspace nadal zawiera `QA_SCENARIO_PLAN.md` +- zainicjalizowany workspace zawiera teraz także `QA_SCENARIOS.md` + +## Plan refaktoryzacji + +### Faza 1: loader i schemat + +Gotowe. + +- dodano `qa/scenarios.md` +- dodano parser dla nazwanej zawartości pakietu Markdown YAML +- zwalidowano przez zod +- przełączono odbiorców na sparsowany pakiet +- usunięto pliki repo-level `qa/seed-scenarios.json` i `qa/QA_KICKOFF_TASK.md` + +### Faza 2: generyczny silnik + +- podzielić `extensions/qa-lab/src/suite.ts` na: + - loader + - silnik + - rejestr akcji + - rejestr asercji + - niestandardowe handlery +- zachować istniejące funkcje pomocnicze jako operacje silnika + +Rezultat: + +- silnik wykonuje proste scenariusze deklaratywne + +Zacząć od scenariuszy, które są głównie prompt + wait + assert: + +- follow-up w wątku +- rozumienie obrazu z załącznika +- widoczność i wywołanie skillów +- bazowy kanał + +Rezultat: + +- pierwsze rzeczywiste scenariusze zdefiniowane w Markdown dostarczane przez generyczny silnik + +### Faza 4: migracja scenariuszy średniej trudności + +- roundtrip generowania obrazów +- narzędzia pamięci w kontekście kanału +- ranking pamięci sesji +- przekazanie do podagenta +- synteza fanout podagentów + +Rezultat: + +- sprawdzona obsługa zmiennych, artefaktów, asercji narzędzi i asercji request-log + +### Faza 5: pozostawienie trudnych scenariuszy na niestandardowych handlerach + +- przegląd memory dreaming +- wybudzenie po restarcie po `config apply` +- przełączenie możliwości po restarcie config +- dryf inwentarza runtime + +Rezultat: + +- ten sam format redagowania, ale z jawnymi blokami niestandardowych kroków tam, gdzie są potrzebne + +### Faza 6: usunięcie mapy scenariuszy zakodowanej na sztywno + +Gdy pokrycie pakietu będzie wystarczająco dobre: + +- usunąć większość rozgałęzień TypeScript specyficznych dla scenariuszy z `extensions/qa-lab/src/suite.ts` + +## Fałszywy Slack / obsługa rozbudowanych mediów + +Obecna magistrala QA jest zorientowana głównie na tekst. + +Powiązane pliki: + +- `extensions/qa-channel/src/protocol.ts` +- `extensions/qa-lab/src/bus-state.ts` +- `extensions/qa-lab/src/bus-queries.ts` +- `extensions/qa-lab/src/bus-server.ts` +- `extensions/qa-lab/web/src/ui-render.ts` + +Dzisiaj magistrala QA obsługuje: + +- tekst +- reakcje +- wątki + +Nie modeluje jeszcze załączników multimedialnych inline. + +### Potrzebny kontrakt transportowy + +Dodać generyczny model załączników magistrali QA: + +```ts +type QaBusAttachment = { + id: string; + kind: "image" | "video" | "audio" | "file"; + mimeType: string; + fileName?: string; + inline?: boolean; + url?: string; + contentBase64?: string; + width?: number; + height?: number; + durationMs?: number; + altText?: string; + transcript?: string; +}; +``` + +Następnie dodać `attachments?: QaBusAttachment[]` do: + +- `QaBusMessage` +- `QaBusInboundMessageInput` +- `QaBusOutboundMessageInput` + +### Dlaczego najpierw generycznie + +Nie budować modelu mediów tylko dla Slacka. + +Zamiast tego: + +- jeden generyczny model transportu QA +- wiele rendererów nad nim + - obecny czat QA Lab + - przyszły fałszywy Slack web + - dowolne inne widoki fałszywego transportu + +To zapobiega duplikacji logiki i pozwala scenariuszom medialnym pozostać niezależnymi od transportu. + +### Potrzebne prace w UI + +Zaktualizować UI QA tak, aby renderowało: + +- podgląd obrazu inline +- odtwarzacz audio inline +- odtwarzacz wideo inline +- chip załącznika pliku + +Obecne UI potrafi już renderować wątki i reakcje, więc renderowanie załączników powinno zostać dołożone do tego samego modelu kart wiadomości. + +### Prace scenariuszowe umożliwione przez transport mediów + +Gdy załączniki zaczną przepływać przez magistralę QA, będzie można dodać bogatsze scenariusze fałszywego czatu: + +- odpowiedź z obrazem inline w fałszywym Slacku +- rozumienie załącznika audio +- rozumienie załącznika wideo +- mieszana kolejność załączników +- odpowiedź w wątku z zachowaniem mediów + +## Rekomendacja + +Kolejny etap implementacji powinien wyglądać tak: + +1. dodać loader scenariuszy Markdown + schemat zod +2. wygenerować obecny katalog z Markdown +3. najpierw zmigrować kilka prostych scenariuszy +4. dodać generyczne wsparcie załączników magistrali QA +5. renderować obraz inline w UI QA +6. następnie rozszerzyć na audio i wideo + +To najmniejsza ścieżka, która potwierdza oba cele: + +- generyczne QA definiowane w Markdown +- bogatsze fałszywe powierzchnie wiadomości + +## Otwarte pytania + +- czy pliki scenariuszy powinny pozwalać na osadzone szablony promptów Markdown z interpolacją zmiennych +- czy setup/cleanup powinny być nazwanymi sekcjami, czy po prostu uporządkowanymi listami akcji +- czy odwołania do artefaktów powinny być silnie typowane w schemacie, czy oparte na stringach +- czy niestandardowe handlery powinny żyć w jednym rejestrze, czy w rejestrach per-surface +- czy wygenerowany plik zgodności JSON powinien pozostać zacommitowany podczas migracji diff --git a/docs/pl/reference/session-management-compaction.md b/docs/pl/reference/session-management-compaction.md index d0fbb334e..b1c1ae103 100644 --- a/docs/pl/reference/session-management-compaction.md +++ b/docs/pl/reference/session-management-compaction.md @@ -1,32 +1,32 @@ --- read_when: - - Musisz debugować identyfikatory sesji, JSONL transkryptów lub pola sessions.json - - Zmieniasz zachowanie auto-compaction lub dodajesz housekeeping „pre-compaction” - - Chcesz zaimplementować flush pamięci lub ciche tury systemowe -summary: 'Szczegółowe omówienie: store sesji + transkrypty, cykl życia i mechanizmy (auto)compaction' + - Musisz debugować identyfikatory sesji, JSONL transkryptu lub pola sessions.json + - Zmieniasz zachowanie auto-kompaktowania lub dodajesz porządki „przed kompaktowaniem” + - Chcesz zaimplementować opróżnianie pamięci lub ciche tury systemowe +summary: 'Szczegółowe omówienie: store sesji i transkrypty, cykl życia oraz mechanizmy (auto)kompaktowania' title: Szczegółowe omówienie zarządzania sesjami x-i18n: - generated_at: "2026-04-07T09:50:11Z" + generated_at: "2026-04-08T02:18:26Z" model: gpt-5.4 provider: openai - source_hash: e379d624dd7808d3af25ed011079268ce6a9da64bb3f301598884ad4c46ab091 + source_hash: cb1a4048646486693db8943a9e9c6c5bcb205f0ed532b34842de3d0346077454 source_path: reference/session-management-compaction.md workflow: 15 --- -# Zarządzanie sesjami i compaction (szczegółowe omówienie) +# Zarządzanie sesjami i kompaktowanie (szczegółowe omówienie) -Ten dokument wyjaśnia, jak OpenClaw zarządza sesjami end-to-end: +Ten dokument wyjaśnia, jak OpenClaw zarządza sesjami od początku do końca: -- **Session routing** (jak wiadomości przychodzące mapują się na `sessionKey`) +- **Routowanie sesji** (jak wiadomości przychodzące mapują się na `sessionKey`) - **Store sesji** (`sessions.json`) i co śledzi -- **Trwałość transkryptów** (`*.jsonl`) i ich struktura -- **Higiena transkryptów** (poprawki specyficzne dla providera przed uruchomieniami) +- **Trwałość transkryptu** (`*.jsonl`) i jego struktura +- **Higiena transkryptu** (poprawki specyficzne dla dostawcy przed uruchomieniami) - **Limity kontekstu** (okno kontekstu vs śledzone tokeny) -- **Compaction** (ręczny + auto-compaction) oraz gdzie podłączać pracę pre-compaction -- **Cichy housekeeping** (np. zapisy pamięci, które nie powinny generować widocznego dla użytkownika wyjścia) +- **Kompaktowanie** (ręczne + automatyczne kompaktowanie) i gdzie podpiąć pracę wykonywaną przed kompaktowaniem +- **Ciche porządki** (np. zapisy do pamięci, które nie powinny generować widocznego dla użytkownika wyjścia) -Jeśli najpierw chcesz przeczytać omówienie na wyższym poziomie, zacznij od: +Jeśli najpierw chcesz zobaczyć omówienie na wyższym poziomie, zacznij od: - [/concepts/session](/pl/concepts/session) - [/concepts/compaction](/pl/concepts/compaction) @@ -39,10 +39,10 @@ Jeśli najpierw chcesz przeczytać omówienie na wyższym poziomie, zacznij od: ## Źródło prawdy: Gateway -OpenClaw jest zaprojektowany wokół pojedynczego **procesu Gateway**, który zarządza stanem sesji. +OpenClaw został zaprojektowany wokół pojedynczego **procesu Gateway**, który zarządza stanem sesji. -- Interfejsy UI (aplikacja macOS, webowy Control UI, TUI) powinny odpytywać Gateway o listy sesji i liczbę tokenów. -- W trybie zdalnym pliki sesji znajdują się na zdalnym hoście; „sprawdzanie lokalnych plików na Macu” nie będzie odzwierciedlać tego, czego używa Gateway. +- Interfejsy użytkownika (aplikacja macOS, webowy Control UI, TUI) powinny odpytywać Gateway o listy sesji i liczniki tokenów. +- W trybie zdalnym pliki sesji znajdują się na zdalnym hoście; „sprawdzanie lokalnych plików na Macu” nie odzwierciedli tego, czego używa Gateway. --- @@ -56,21 +56,21 @@ OpenClaw zapisuje sesje w dwóch warstwach: - Śledzi metadane sesji (bieżący identyfikator sesji, ostatnią aktywność, przełączniki, liczniki tokenów itd.) 2. **Transkrypt (`.jsonl`)** - - Transkrypt append-only o strukturze drzewa (wpisy mają `id` + `parentId`) - - Przechowuje właściwą rozmowę + wywołania narzędzi + podsumowania compaction + - Transkrypt typu append-only o strukturze drzewa (wpisy mają `id` + `parentId`) + - Przechowuje właściwą konwersację + wywołania narzędzi + podsumowania kompaktowania - Służy do odbudowy kontekstu modelu dla przyszłych tur --- ## Lokalizacje na dysku -Per agent, na hoście Gateway: +Dla każdego agenta, na hoście Gateway: - Store: `~/.openclaw/agents//sessions/sessions.json` - Transkrypty: `~/.openclaw/agents//sessions/.jsonl` - Sesje tematów Telegram: `.../-topic-.jsonl` -OpenClaw rozwiązuje je przez `src/config/sessions.ts`. +OpenClaw rozwiązuje te ścieżki przez `src/config/sessions.ts`. --- @@ -79,18 +79,18 @@ OpenClaw rozwiązuje je przez `src/config/sessions.ts`. Trwałość sesji ma automatyczne mechanizmy utrzymania (`session.maintenance`) dla `sessions.json` i artefaktów transkryptów: - `mode`: `warn` (domyślnie) lub `enforce` -- `pruneAfter`: próg wieku nieaktualnych wpisów (domyślnie `30d`) +- `pruneAfter`: próg wieku dla starych wpisów (domyślnie `30d`) - `maxEntries`: limit wpisów w `sessions.json` (domyślnie `500`) -- `rotateBytes`: obraca `sessions.json`, gdy staje się zbyt duży (domyślnie `10mb`) +- `rotateBytes`: rotacja `sessions.json`, gdy plik jest zbyt duży (domyślnie `10mb`) - `resetArchiveRetention`: retencja dla archiwów transkryptów `*.reset.` (domyślnie: taka sama jak `pruneAfter`; `false` wyłącza czyszczenie) -- `maxDiskBytes`: opcjonalny budżet katalogu sesji -- `highWaterBytes`: opcjonalny cel po cleanupie (domyślnie `80%` z `maxDiskBytes`) +- `maxDiskBytes`: opcjonalny limit budżetu katalogu sesji +- `highWaterBytes`: opcjonalny cel po czyszczeniu (domyślnie `80%` z `maxDiskBytes`) -Kolejność egzekwowania cleanupu przy budżecie dyskowym (`mode: "enforce"`): +Kolejność egzekwowania przy czyszczeniu limitu dysku (`mode: "enforce"`): 1. Najpierw usuń najstarsze zarchiwizowane lub osierocone artefakty transkryptów. -2. Jeśli nadal przekroczony jest cel, usuń najstarsze wpisy sesji i ich pliki transkryptów. -3. Kontynuuj, aż użycie będzie na poziomie `highWaterBytes` lub poniżej. +2. Jeśli nadal jest powyżej celu, usuń najstarsze wpisy sesji i ich pliki transkryptów. +3. Kontynuuj, aż użycie spadnie do `highWaterBytes` lub niżej. W trybie `mode: "warn"` OpenClaw zgłasza potencjalne usunięcia, ale nie modyfikuje store ani plików. @@ -114,30 +114,30 @@ Izolowane uruchomienia cron również tworzą wpisy sesji/transkrypty i mają de ## Klucze sesji (`sessionKey`) -`sessionKey` identyfikuje, _w którym koszyku rozmowy_ się znajdujesz (routing + izolacja). +`sessionKey` identyfikuje _który koszyk konwersacji_ jest używany (routowanie + izolacja). Typowe wzorce: -- Główny/czat bezpośredni (per agent): `agent::` (domyślnie `main`) +- Główny/bezpośredni czat (per agent): `agent::` (domyślnie `main`) - Grupa: `agent:::group:` - Pokój/kanał (Discord/Slack): `agent:::channel:` lub `...:room:` - Cron: `cron:` - Webhook: `hook:` (chyba że nadpisano) -Kanoniczne zasady są opisane w [/concepts/session](/pl/concepts/session). +Kanoniczne zasady są udokumentowane w [/concepts/session](/pl/concepts/session). --- ## Identyfikatory sesji (`sessionId`) -Każdy `sessionKey` wskazuje na bieżący `sessionId` (plik transkryptu, który kontynuuje rozmowę). +Każdy `sessionKey` wskazuje na bieżący `sessionId` (plik transkryptu, który kontynuuje konwersację). Praktyczne zasady: - **Reset** (`/new`, `/reset`) tworzy nowy `sessionId` dla tego `sessionKey`. -- **Codzienny reset** (domyślnie 4:00 czasu lokalnego hosta gateway) tworzy nowy `sessionId` przy następnej wiadomości po przekroczeniu granicy resetu. -- **Wygaśnięcie bezczynności** (`session.reset.idleMinutes` lub starsze `session.idleMinutes`) tworzy nowy `sessionId`, gdy wiadomość nadejdzie po upływie okna bezczynności. Gdy skonfigurowane są jednocześnie reset dzienny i bezczynność, wygrywa ten, który wygaśnie wcześniej. -- **Zabezpieczenie forkowania po rodzicu wątku** (`session.parentForkMaxTokens`, domyślnie `100000`) pomija forkowanie transkryptu rodzica, gdy sesja nadrzędna jest już zbyt duża; nowy wątek zaczyna się od zera. Ustaw `0`, aby wyłączyć. +- **Codzienny reset** (domyślnie o 4:00 czasu lokalnego na hoście gatewaya) tworzy nowy `sessionId` przy następnej wiadomości po przekroczeniu granicy resetu. +- **Wygaśnięcie bezczynności** (`session.reset.idleMinutes` lub starsze `session.idleMinutes`) tworzy nowy `sessionId`, gdy wiadomość nadejdzie po oknie bezczynności. Gdy skonfigurowano jednocześnie reset dzienny i bezczynność, wygrywa ten, który wygaśnie wcześniej. +- **Zabezpieczenie przed rozwidleniem z rodzica dla wątków** (`session.parentForkMaxTokens`, domyślnie `100000`) pomija forking transkryptu rodzica, gdy sesja nadrzędna jest już zbyt duża; nowy wątek zaczyna się od zera. Ustaw `0`, aby wyłączyć. Szczegół implementacyjny: decyzja zapada w `initSessionState()` w `src/auto-reply/reply/session.ts`. @@ -149,44 +149,44 @@ Typ wartości store to `SessionEntry` w `src/config/sessions.ts`. Kluczowe pola (lista niepełna): -- `sessionId`: bieżący identyfikator transkryptu (nazwa pliku jest od niego wyprowadzana, chyba że ustawiono `sessionFile`) +- `sessionId`: bieżący identyfikator transkryptu (nazwa pliku jest z niego wyprowadzana, chyba że ustawiono `sessionFile`) - `updatedAt`: znacznik czasu ostatniej aktywności - `sessionFile`: opcjonalne jawne nadpisanie ścieżki transkryptu -- `chatType`: `direct | group | room` (pomaga UI i polityce wysyłania) +- `chatType`: `direct | group | room` (pomaga interfejsom użytkownika i polityce wysyłania) - `provider`, `subject`, `room`, `space`, `displayName`: metadane do etykietowania grup/kanałów - Przełączniki: - `thinkingLevel`, `verboseLevel`, `reasoningLevel`, `elevatedLevel` - `sendPolicy` (nadpisanie per sesja) - Wybór modelu: - `providerOverride`, `modelOverride`, `authProfileOverride` -- Liczniki tokenów (best-effort / zależne od providera): +- Liczniki tokenów (best-effort / zależne od dostawcy): - `inputTokens`, `outputTokens`, `totalTokens`, `contextTokens` -- `compactionCount`: jak często auto-compaction zakończył się dla tego klucza sesji -- `memoryFlushAt`: znacznik czasu ostatniego flush pamięci pre-compaction -- `memoryFlushCompactionCount`: licznik compaction, przy którym wykonano ostatni flush +- `compactionCount`: jak często auto-kompaktowanie zakończyło się dla tego klucza sesji +- `memoryFlushAt`: znacznik czasu ostatniego opróżnienia pamięci przed kompaktowaniem +- `memoryFlushCompactionCount`: licznik kompaktowań, przy którym uruchomiono ostatnie opróżnienie -Store można bezpiecznie edytować, ale autorytetem pozostaje Gateway: może przepisywać lub ponownie hydradować wpisy podczas działania sesji. +Store można bezpiecznie edytować, ale Gateway jest autorytetem: może przepisywać lub odtwarzać wpisy podczas działania sesji. --- ## Struktura transkryptu (`*.jsonl`) -Transkryptami zarządza `SessionManager` z `@mariozechner/pi-coding-agent`. +Transkrypty są zarządzane przez `SessionManager` z `@mariozechner/pi-coding-agent`. Plik ma format JSONL: - Pierwsza linia: nagłówek sesji (`type: "session"`, zawiera `id`, `cwd`, `timestamp`, opcjonalnie `parentSession`) -- Dalej: wpisy sesji z `id` + `parentId` (drzewo) +- Następnie: wpisy sesji z `id` + `parentId` (drzewo) -Ważne typy wpisów: +Istotne typy wpisów: -- `message`: wiadomości user/assistant/toolResult -- `custom_message`: wiadomości wstrzyknięte przez rozszerzenie, które _wchodzą_ do kontekstu modelu (mogą być ukryte przed UI) +- `message`: wiadomości użytkownika/asystenta/toolResult +- `custom_message`: wiadomości wstrzykiwane przez rozszerzenie, które _wchodzą_ do kontekstu modelu (mogą być ukryte w UI) - `custom`: stan rozszerzenia, który _nie wchodzi_ do kontekstu modelu -- `compaction`: utrwalone podsumowanie compaction z `firstKeptEntryId` i `tokensBefore` -- `branch_summary`: utrwalone podsumowanie przy nawigacji po gałęzi drzewa +- `compaction`: zapisane podsumowanie kompaktowania z `firstKeptEntryId` i `tokensBefore` +- `branch_summary`: zapisane podsumowanie przy nawigacji po gałęzi drzewa -OpenClaw celowo **nie** „naprawia” transkryptów; Gateway używa `SessionManager` do ich odczytu/zapisu. +OpenClaw celowo **nie** „naprawia” transkryptów; Gateway używa `SessionManager` do ich odczytu i zapisu. --- @@ -199,49 +199,49 @@ Znaczenie mają dwa różne pojęcia: Jeśli dostrajasz limity: -- Okno kontekstu pochodzi z katalogu modeli (i może być nadpisane przez config). -- `contextTokens` w store to wartość szacunkowa/raportowa z runtime; nie traktuj jej jako ścisłej gwarancji. +- Okno kontekstu pochodzi z katalogu modeli (i może być nadpisane przez konfigurację). +- `contextTokens` w store to wartość szacunkowa/raportowana przez runtime; nie traktuj jej jako ścisłej gwarancji. Więcej informacji znajdziesz w [/token-use](/pl/reference/token-use). --- -## Compaction: czym jest +## Kompaktowanie: czym jest -Compaction podsumowuje starszą część rozmowy do utrwalonego wpisu `compaction` w transkrypcie i pozostawia nienaruszone ostatnie wiadomości. +Kompaktowanie podsumowuje starszą część konwersacji do zapisanego wpisu `compaction` w transkrypcie i zachowuje nienaruszone ostatnie wiadomości. -Po compaction przyszłe tury widzą: +Po kompaktowaniu przyszłe tury widzą: -- Podsumowanie compaction +- Podsumowanie kompaktowania - Wiadomości po `firstKeptEntryId` -Compaction jest **trwały** (w przeciwieństwie do session pruning). Zobacz [/concepts/session-pruning](/pl/concepts/session-pruning). +Kompaktowanie jest **trwałe** (w przeciwieństwie do przycinania sesji). Zobacz [/concepts/session-pruning](/pl/concepts/session-pruning). -## Granice chunków compaction i parowanie narzędzi +## Granice chunków kompaktowania i parowanie narzędzi -Gdy OpenClaw dzieli długi transkrypt na chunki do compaction, utrzymuje -powiązanie wywołań narzędzi asystenta z odpowiadającymi im wpisami `toolResult`. +Gdy OpenClaw dzieli długi transkrypt na chunki do kompaktowania, utrzymuje +sparowanie wywołań narzędzi asystenta z odpowiadającymi im wpisami `toolResult`. - Jeśli podział według udziału tokenów wypada między wywołaniem narzędzia a jego wynikiem, OpenClaw - przesuwa granicę do wiadomości asystenta zawierającej wywołanie narzędzia zamiast rozdzielać - tę parę. -- Jeśli końcowy blok wyniku narzędzia w przeciwnym razie przesunąłby chunk ponad docelowy rozmiar, + przesuwa granicę do wiadomości asystenta z wywołaniem narzędzia zamiast rozdzielać + parę. +- Jeśli końcowy blok z wynikiem narzędzia w przeciwnym razie przekroczyłby docelowy rozmiar chunku, OpenClaw zachowuje ten oczekujący blok narzędzia i pozostawia niepodsumowany ogon bez zmian. -- Przerwane/błędne bloki wywołań narzędzi nie utrzymują otwartego oczekującego podziału. +- Przerwane/błędne bloki wywołań narzędzi nie utrzymują oczekującego podziału otwartego. --- -## Kiedy zachodzi auto-compaction (runtime Pi) +## Kiedy następuje auto-kompaktowanie (runtime Pi) -W osadzonym agencie Pi auto-compaction uruchamia się w dwóch przypadkach: +W osadzonym agencie Pi auto-kompaktowanie uruchamia się w dwóch przypadkach: -1. **Odzyskiwanie po overflow**: model zwraca błąd przepełnienia kontekstu +1. **Odzyskiwanie po przepełnieniu**: model zwraca błąd przepełnienia kontekstu (`request_too_large`, `context length exceeded`, `input exceeds the maximum number of tokens`, `input token count exceeds the maximum number of input tokens`, `input is too long for the model`, `ollama error: context length -exceeded` oraz podobne warianty zależne od providera) → compact → ponów próbę. -2. **Utrzymanie progu**: po pomyślnej turze, gdy: +exceeded` oraz podobne warianty zależne od dostawcy) → kompaktuj → ponów próbę. +2. **Utrzymanie progu**: po udanej turze, gdy: `contextTokens > contextWindow - reserveTokens` @@ -250,13 +250,13 @@ Gdzie: - `contextWindow` to okno kontekstu modelu - `reserveTokens` to zapas zarezerwowany na prompty + następne wyjście modelu -To semantyka runtime Pi (OpenClaw konsumuje zdarzenia, ale Pi decyduje, kiedy robić compact). +To semantyka runtime Pi (OpenClaw konsumuje zdarzenia, ale Pi decyduje, kiedy kompaktować). --- -## Ustawienia compaction (`reserveTokens`, `keepRecentTokens`) +## Ustawienia kompaktowania (`reserveTokens`, `keepRecentTokens`) -Ustawienia compaction Pi znajdują się w ustawieniach Pi: +Ustawienia kompaktowania Pi znajdują się w ustawieniach Pi: ```json5 { @@ -268,92 +268,107 @@ Ustawienia compaction Pi znajdują się w ustawieniach Pi: } ``` -OpenClaw wymusza też minimalny próg bezpieczeństwa dla osadzonych uruchomień: +OpenClaw wymusza też minimalny bezpieczny próg dla uruchomień osadzonych: - Jeśli `compaction.reserveTokens < reserveTokensFloor`, OpenClaw go podnosi. -- Domyślny próg to `20000` tokenów. +- Domyślny próg minimalny to `20000` tokenów. - Ustaw `agents.defaults.compaction.reserveTokensFloor: 0`, aby wyłączyć ten próg. - Jeśli wartość jest już wyższa, OpenClaw pozostawia ją bez zmian. -Dlaczego: pozostawia to wystarczający zapas na wieloturowy „housekeeping” (np. zapisy pamięci), zanim compaction stanie się nieunikniony. +Dlaczego: aby zostawić wystarczający zapas na wieloturowe „porządki” (takie jak zapisy do pamięci), zanim kompaktowanie stanie się nieuniknione. Implementacja: `ensurePiCompactionReserveTokens()` w `src/agents/pi-settings.ts` (wywoływane z `src/agents/pi-embedded-runner.ts`). --- +## Wymienni dostawcy kompaktowania + +Wtyczki mogą rejestrować dostawcę kompaktowania przez `registerCompactionProvider()` w API wtyczek. Gdy `agents.defaults.compaction.provider` jest ustawione na identyfikator zarejestrowanego dostawcy, rozszerzenie safeguard deleguje podsumowywanie do tego dostawcy zamiast do wbudowanego potoku `summarizeInStages`. + +- `provider`: identyfikator zarejestrowanej wtyczki dostawcy kompaktowania. Pozostaw nieustawione dla domyślnego podsumowywania przez LLM. +- Ustawienie `provider` wymusza `mode: "safeguard"`. +- Dostawcy otrzymują te same instrukcje kompaktowania i politykę zachowywania identyfikatorów co ścieżka wbudowana. +- Safeguard nadal zachowuje kontekst ostatnich tur i końcówki podzielonej tury po wyjściu dostawcy. +- Jeśli dostawca zawiedzie lub zwróci pusty wynik, OpenClaw automatycznie wraca do wbudowanego podsumowywania przez LLM. +- Sygnały przerwania/timeoutu są ponownie rzucane (nie są przechwytywane), aby respektować anulowanie przez wywołującego. + +Źródło: `src/plugins/compaction-provider.ts`, `src/agents/pi-hooks/compaction-safeguard.ts`. + +--- + ## Powierzchnie widoczne dla użytkownika -Możesz obserwować compaction i stan sesji przez: +Kompaktowanie i stan sesji można obserwować przez: - `/status` (w dowolnej sesji czatu) - `openclaw status` (CLI) - `openclaw sessions` / `sessions --json` -- Tryb verbose: `🧹 Auto-compaction complete` + liczba compaction +- Tryb szczegółowy: `🧹 Auto-compaction complete` + liczba kompaktowań --- -## Cichy housekeeping (`NO_REPLY`) +## Ciche porządki (`NO_REPLY`) -OpenClaw obsługuje „ciche” tury dla zadań w tle, w których użytkownik nie powinien widzieć pośredniego wyjścia. +OpenClaw obsługuje „ciche” tury dla zadań działających w tle, gdy użytkownik nie powinien widzieć pośredniego wyjścia. Konwencja: -- Asystent rozpoczyna wyjście dokładnym cichym tokenem `NO_REPLY` / +- Asystent rozpoczyna wyjście od dokładnego cichego tokena `NO_REPLY` / `no_reply`, aby wskazać „nie dostarczaj odpowiedzi użytkownikowi”. -- OpenClaw usuwa/wycisza to w warstwie dostarczania. -- Wyciszanie dokładnego cichego tokenu jest niewrażliwe na wielkość liter, więc `NO_REPLY` i - `no_reply` są traktowane tak samo, gdy cały payload składa się tylko z cichego tokenu. -- To rozwiązanie jest przeznaczone tylko dla prawdziwych tur w tle/bez dostarczania; nie jest skrótem dla - zwykłych żądań użytkownika wymagających działania. +- OpenClaw usuwa/tłumi to w warstwie dostarczania. +- Tłumienie dokładnego cichego tokena nie rozróżnia wielkości liter, więc `NO_REPLY` i + `no_reply` liczą się tak samo, gdy cały ładunek to tylko ten cichy token. +- Służy to wyłącznie do prawdziwych tur działających w tle / bez dostarczenia; nie jest to skrót + dla zwykłych, wymagających działania żądań użytkownika. -Od wersji `2026.1.10` OpenClaw wycisza też **draft/typing streaming**, gdy +Od wersji `2026.1.10` OpenClaw tłumi także **streaming wersji roboczych/pisania**, gdy częściowy chunk zaczyna się od `NO_REPLY`, aby ciche operacje nie ujawniały częściowego -wyjścia w trakcie tury. +wyjścia w połowie tury. --- -## „Memory flush” pre-compaction (zaimplementowane) +## „Opróżnianie pamięci” przed kompaktowaniem (zaimplementowane) -Cel: zanim nastąpi auto-compaction, uruchomić cichą, agentową turę, która zapisze trwały -stan na dysku (np. `memory/YYYY-MM-DD.md` w obszarze roboczym agenta), tak aby compaction nie mógł -wymazać krytycznego kontekstu. +Cel: zanim nastąpi auto-kompaktowanie, uruchomić cichą agentową turę, która zapisze trwały +stan na dysk (np. `memory/YYYY-MM-DD.md` w obszarze roboczym agenta), aby kompaktowanie nie mogło +usunąć krytycznego kontekstu. -OpenClaw używa podejścia **pre-threshold flush**: +OpenClaw używa podejścia **opróżniania przed progiem**: -1. Monitoruj użycie kontekstu sesji. -2. Gdy przekroczy „miękki próg” (poniżej progu compaction Pi), uruchom cichą - dyrektywę „zapisz pamięć teraz” dla agenta. -3. Użyj dokładnego cichego tokenu `NO_REPLY` / `no_reply`, aby użytkownik niczego - nie zobaczył. +1. Monitoruje użycie kontekstu sesji. +2. Gdy przekroczy ono „miękki próg” (poniżej progu kompaktowania Pi), uruchamia cichą + dyrektywę „zapisz pamięć teraz” do agenta. +3. Używa dokładnego cichego tokena `NO_REPLY` / `no_reply`, aby użytkownik niczego + nie widział. -Config (`agents.defaults.compaction.memoryFlush`): +Konfiguracja (`agents.defaults.compaction.memoryFlush`): - `enabled` (domyślnie: `true`) - `softThresholdTokens` (domyślnie: `4000`) -- `prompt` (wiadomość użytkownika dla tury flush) -- `systemPrompt` (dodatkowy system prompt dołączany do tury flush) +- `prompt` (wiadomość użytkownika dla tury opróżniania) +- `systemPrompt` (dodatkowy prompt systemowy dołączany dla tury opróżniania) Uwagi: -- Domyślny prompt/system prompt zawiera wskazówkę `NO_REPLY`, aby wyciszyć +- Domyślny prompt/system prompt zawierają wskazówkę `NO_REPLY`, aby tłumić dostarczanie. -- Flush jest uruchamiany raz na cykl compaction (śledzony w `sessions.json`). -- Flush działa tylko dla osadzonych sesji Pi (backendy CLI go pomijają). -- Flush jest pomijany, gdy obszar roboczy sesji jest tylko do odczytu (`workspaceAccess: "ro"` lub `"none"`). -- Zobacz [Memory](/pl/concepts/memory), aby poznać układ plików obszaru roboczego i wzorce zapisu. +- Opróżnianie uruchamia się raz na cykl kompaktowania (śledzone w `sessions.json`). +- Opróżnianie działa tylko dla sesji osadzonego Pi (backendy CLI je pomijają). +- Opróżnianie jest pomijane, gdy obszar roboczy sesji jest tylko do odczytu (`workspaceAccess: "ro"` lub `"none"`). +- Zobacz [Pamięć](/pl/concepts/memory), aby poznać układ plików obszaru roboczego i wzorce zapisu. Pi udostępnia też hook `session_before_compact` w API rozszerzeń, ale logika -flush w OpenClaw obecnie znajduje się po stronie Gateway. +opróżniania OpenClaw znajduje się obecnie po stronie Gateway. --- ## Lista kontrolna rozwiązywania problemów -- Zły klucz sesji? Zacznij od [/concepts/session](/pl/concepts/session) i potwierdź `sessionKey` w `/status`. +- Nieprawidłowy klucz sesji? Zacznij od [/concepts/session](/pl/concepts/session) i potwierdź `sessionKey` w `/status`. - Niezgodność store i transkryptu? Potwierdź host Gateway i ścieżkę store z `openclaw status`. -- Spam compaction? Sprawdź: +- Spam kompaktowania? Sprawdź: - okno kontekstu modelu (za małe) - - ustawienia compaction (`reserveTokens` ustawione zbyt wysoko względem okna modelu mogą powodować wcześniejszy compaction) - - rozrost `toolResult`: włącz/skonfiguruj session pruning -- Ciche tury przeciekają? Upewnij się, że odpowiedź zaczyna się od `NO_REPLY` (dokładny token, bez rozróżniania wielkości liter) i że używasz builda zawierającego poprawkę wyciszania streamingu. + - ustawienia kompaktowania (`reserveTokens` zbyt wysokie względem okna modelu mogą powodować wcześniejsze kompaktowanie) + - nadmiar `toolResult`: włącz/dostrój przycinanie sesji +- Wyciekają ciche tury? Potwierdź, że odpowiedź zaczyna się od `NO_REPLY` (dokładny token, bez rozróżniania wielkości liter) i że używasz kompilacji zawierającej poprawkę tłumienia streamingu. diff --git a/docs/pl/tools/acp-agents.md b/docs/pl/tools/acp-agents.md index 5934125b7..113c1cc96 100644 --- a/docs/pl/tools/acp-agents.md +++ b/docs/pl/tools/acp-agents.md @@ -1,236 +1,236 @@ --- read_when: - - Uruchamianie harnessów programistycznych przez ACP - - Konfigurowanie sesji ACP powiązanych z konwersacją na kanałach wiadomości - - Powiązanie konwersacji kanału wiadomości z trwałą sesją ACP - - Rozwiązywanie problemów z backendem ACP i połączeniem pluginu - - Obsługa poleceń /acp z czatu + - Uruchamiasz coding harnesses przez ACP + - Konfigurujesz sesje ACP powiązane z rozmową na kanałach wiadomości + - Powiązujesz rozmowę na kanale wiadomości z trwałą sesją ACP + - Rozwiązujesz problemy z backendem ACP i połączeniami pluginów + - Obsługujesz polecenia /acp z czatu summary: Używaj sesji runtime ACP dla Codex, Claude Code, Cursor, Gemini CLI, OpenClaw ACP i innych agentów harness title: Agenci ACP x-i18n: - generated_at: "2026-04-07T09:52:40Z" + generated_at: "2026-04-08T02:20:03Z" model: gpt-5.4 provider: openai - source_hash: fb651ab39b05e537398623ee06cb952a5a07730fc75d3f7e0de20dd3128e72c6 + source_hash: 71c7c0cdae5247aefef17a0029360950a1c2987ddcee21a1bb7d78c67da52950 source_path: tools/acp-agents.md workflow: 15 --- # Agenci ACP -Sesje [Agent Client Protocol (ACP)](https://agentclientprotocol.com/) pozwalają OpenClaw uruchamiać zewnętrzne harnessy programistyczne (na przykład Pi, Claude Code, Codex, Cursor, Copilot, OpenClaw ACP, OpenCode, Gemini CLI i inne obsługiwane harnessy ACPX) przez plugin backendu ACP. +Sesje [Agent Client Protocol (ACP)](https://agentclientprotocol.com/) pozwalają OpenClaw uruchamiać zewnętrzne coding harnesses (na przykład Pi, Claude Code, Codex, Cursor, Copilot, OpenClaw ACP, OpenCode, Gemini CLI i inne obsługiwane harnesses ACPX) przez plugin backendu ACP. -Jeśli poprosisz OpenClaw zwykłym językiem, aby „uruchomił to w Codex” albo „uruchomił Claude Code w wątku”, OpenClaw powinien skierować to żądanie do runtime ACP (a nie do natywnego runtime sub-agenta). Każde uruchomienie sesji ACP jest śledzone jako [zadanie w tle](/pl/automation/tasks). +Jeśli poprosisz OpenClaw zwykłym językiem, aby „uruchomił to w Codex” albo „uruchomił Claude Code w wątku”, OpenClaw powinien skierować to żądanie do runtime ACP (a nie do natywnego runtime podagentów). Każde uruchomienie sesji ACP jest śledzone jako [zadanie w tle](/pl/automation/tasks). -Jeśli chcesz, aby Codex lub Claude Code łączyły się jako zewnętrzny klient MCP bezpośrednio -z istniejącymi konwersacjami kanałów OpenClaw, użyj +Jeśli chcesz, aby Codex lub Claude Code połączyły się bezpośrednio jako zewnętrzny klient MCP +z istniejącymi rozmowami kanałowymi OpenClaw, użyj [`openclaw mcp serve`](/cli/mcp) zamiast ACP. -## Którą stronę wybrać? +## Którą stronę chcę? -Są tu trzy sąsiednie powierzchnie, które łatwo pomylić: +Są tu trzy powiązane powierzchnie, które łatwo pomylić: -| Chcesz... | Użyj tego | Uwagi | -| ---------------------------------------------------------------------------------- | ------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | -| Uruchamiać Codex, Claude Code, Gemini CLI lub inny zewnętrzny harness _przez_ OpenClaw | Ta strona: agenci ACP | Sesje powiązane z czatem, `/acp spawn`, `sessions_spawn({ runtime: "acp" })`, zadania w tle, kontrolki runtime | -| Udostępnić sesję OpenClaw Gateway _jako_ serwer ACP dla edytora lub klienta | [`openclaw acp`](/cli/acp) | Tryb mostu. IDE/klient mówi ACP do OpenClaw przez stdio/WebSocket | -| Użyć lokalnego AI CLI jako zapasowego modelu tylko tekstowego | [CLI Backends](/pl/gateway/cli-backends) | To nie ACP. Bez narzędzi OpenClaw, bez kontrolek ACP, bez runtime harness | +| Chcesz... | Użyj tego | Uwagi | +| --- | --- | --- | +| Uruchamiać Codex, Claude Code, Gemini CLI lub inny zewnętrzny harness _przez_ OpenClaw | Ta strona: agenci ACP | Sesje powiązane z czatem, `/acp spawn`, `sessions_spawn({ runtime: "acp" })`, zadania w tle, kontrolki runtime | +| Udostępnić sesję OpenClaw Gateway _jako_ serwer ACP dla edytora lub klienta | [`openclaw acp`](/cli/acp) | Tryb mostka. IDE/klient mówi ACP do OpenClaw przez stdio/WebSocket | +| Użyć lokalnego AI CLI ponownie jako tekstowego modelu zapasowego | [CLI Backends](/pl/gateway/cli-backends) | To nie jest ACP. Brak narzędzi OpenClaw, brak kontrolek ACP, brak runtime harness | ## Czy to działa od razu po instalacji? Zwykle tak. -- Świeże instalacje mają teraz domyślnie włączony dołączony plugin runtime `acpx`. -- Dołączony plugin `acpx` preferuje swój lokalny, przypięty plik binarny `acpx`. -- Przy starcie OpenClaw sonduje ten plik binarny i w razie potrzeby sam go naprawia. -- Zacznij od `/acp doctor`, jeśli chcesz wykonać szybkie sprawdzenie gotowości. +- Świeże instalacje są teraz dostarczane z włączonym domyślnie dołączonym pluginem runtime `acpx`. +- Dołączony plugin `acpx` preferuje własny, przypięty binarny plik `acpx`. +- Przy uruchomieniu OpenClaw sonduje ten plik binarny i w razie potrzeby sam go naprawia. +- Zacznij od `/acp doctor`, jeśli chcesz przeprowadzić szybki test gotowości. Co nadal może się zdarzyć przy pierwszym użyciu: -- Docelowy adapter harness może zostać pobrany na żądanie przez `npx` przy pierwszym użyciu tego harnessu. -- Uwierzytelnianie producenta nadal musi istnieć na hoście dla tego harnessu. -- Jeśli host nie ma dostępu do npm/sieci, pobrania adaptera przy pierwszym uruchomieniu mogą się nie udać, dopóki cache nie zostanie podgrzany lub adapter nie zostanie zainstalowany w inny sposób. +- Adapter docelowego harness może zostać pobrany na żądanie przez `npx` przy pierwszym użyciu tego harness. +- Uwierzytelnienie dostawcy nadal musi istnieć na hoście dla tego harness. +- Jeśli host nie ma dostępu do npm/sieci, pobrania adapterów przy pierwszym uruchomieniu mogą się nie powieść, dopóki pamięci podręczne nie zostaną rozgrzane albo adapter nie zostanie zainstalowany w inny sposób. Przykłady: -- `/acp spawn codex`: OpenClaw powinien być gotowy do bootstrapu `acpx`, ale adapter ACP dla Codex może nadal wymagać pobrania przy pierwszym uruchomieniu. -- `/acp spawn claude`: podobnie w przypadku adaptera ACP dla Claude, plus uwierzytelnianie po stronie Claude na tym hoście. +- `/acp spawn codex`: OpenClaw powinien być gotowy do bootstrapowania `acpx`, ale adapter ACP Codex może nadal wymagać pobrania przy pierwszym uruchomieniu. +- `/acp spawn claude`: podobnie w przypadku adaptera ACP Claude oraz uwierzytelnienia po stronie Claude na tym hoście. -## Szybki przepływ dla operatora +## Szybki przepływ operatora -Użyj tego, jeśli chcesz praktycznego runbooka `/acp`: +Użyj tego, gdy chcesz praktycznego poradnika do `/acp`: 1. Uruchom sesję: - `/acp spawn codex --bind here` - `/acp spawn codex --mode persistent --thread auto` -2. Pracuj w powiązanej konwersacji lub wątku (albo wskaż jawnie ten klucz sesji). +2. Pracuj w powiązanej rozmowie lub wątku (albo wskaż jawnie ten klucz sesji). 3. Sprawdź stan runtime: - `/acp status` 4. Dostosuj opcje runtime w razie potrzeby: - `/acp model ` - `/acp permissions ` - `/acp timeout ` -5. Delikatnie skieruj aktywną sesję bez zastępowania kontekstu: +5. Skieruj aktywną sesję bez zastępowania kontekstu: - `/acp steer tighten logging and continue` 6. Zatrzymaj pracę: - `/acp cancel` (zatrzymaj bieżącą turę), albo - - `/acp close` (zamknij sesję + usuń powiązania) + - `/acp close` (zamknij sesję i usuń powiązania) ## Szybki start dla ludzi Przykłady naturalnych próśb: - „Powiąż ten kanał Discord z Codex.” -- „Uruchom tu trwałą sesję Codex w wątku i utrzymuj ją w skupieniu.” +- „Uruchom trwałą sesję Codex w wątku tutaj i utrzymuj jej fokus.” - „Uruchom to jako jednorazową sesję Claude Code ACP i podsumuj wynik.” -- „Powiąż ten czat iMessage z Codex i utrzymuj kolejne wiadomości w tym samym workspace.” -- „Użyj Gemini CLI do tego zadania w wątku, a potem utrzymuj kolejne wiadomości w tym samym wątku.” +- „Powiąż ten czat iMessage z Codex i zachowaj kolejne wiadomości w tym samym obszarze roboczym.” +- „Użyj Gemini CLI do tego zadania w wątku, a potem zachowaj kolejne wiadomości w tym samym wątku.” Co OpenClaw powinien zrobić: 1. Wybrać `runtime: "acp"`. -2. Rozwiązać żądany cel harnessu (`agentId`, na przykład `codex`). -3. Jeśli żądane jest powiązanie z bieżącą konwersacją i aktywny kanał je obsługuje, powiązać sesję ACP z tą konwersacją. -4. W przeciwnym razie, jeśli żądane jest powiązanie z wątkiem i bieżący kanał je obsługuje, powiązać sesję ACP z wątkiem. -5. Kierować kolejne powiązane wiadomości do tej samej sesji ACP, dopóki nie zostanie wyłączona, zamknięta lub nie wygaśnie. +2. Rozpoznać żądany cel harness (`agentId`, na przykład `codex`). +3. Jeśli zażądano powiązania z bieżącą rozmową i aktywny kanał to obsługuje, powiązać sesję ACP z tą rozmową. +4. W przeciwnym razie, jeśli zażądano powiązania z wątkiem i bieżący kanał to obsługuje, powiązać sesję ACP z wątkiem. +5. Kierować kolejne wiadomości w powiązaniu do tej samej sesji ACP, dopóki nie zostanie odfokusowana/zamknięta/wygaśnie. -## ACP a sub-agenci +## ACP a podagenci -Używaj ACP, gdy chcesz zewnętrznego runtime harness. Używaj sub-agentów, gdy chcesz natywnych dla OpenClaw uruchomień delegowanych. +Używaj ACP, gdy chcesz zewnętrznego runtime harness. Używaj podagentów, gdy chcesz delegowanych uruchomień natywnych dla OpenClaw. -| Obszar | Sesja ACP | Uruchomienie sub-agenta | -| ------------- | ------------------------------------- | ---------------------------------- | -| Runtime | Plugin backendu ACP (na przykład acpx) | Natywny runtime sub-agenta OpenClaw | -| Klucz sesji | `agent::acp:` | `agent::subagent:` | -| Główne polecenia | `/acp ...` | `/subagents ...` | -| Narzędzie uruchamiania | `sessions_spawn` z `runtime:"acp"` | `sessions_spawn` (domyślny runtime) | +| Obszar | Sesja ACP | Uruchomienie podagenta | +| --- | --- | --- | +| Runtime | Plugin backendu ACP (na przykład acpx) | Natywny runtime podagentów OpenClaw | +| Klucz sesji | `agent::acp:` | `agent::subagent:` | +| Główne polecenia | `/acp ...` | `/subagents ...` | +| Narzędzie uruchamiania | `sessions_spawn` z `runtime:"acp"` | `sessions_spawn` (domyślny runtime) | Zobacz też [Sub-agents](/pl/tools/subagents). ## Jak ACP uruchamia Claude Code -Dla Claude Code przez ACP stos jest następujący: +W przypadku Claude Code przez ACP stos wygląda następująco: -1. Płaszczyzna sterowania sesjami OpenClaw ACP +1. Płaszczyzna sterowania sesjami ACP OpenClaw 2. dołączony plugin runtime `acpx` 3. adapter Claude ACP -4. runtime/mechanika sesji po stronie Claude +4. mechanizm runtime/sesji po stronie Claude Ważne rozróżnienie: -- ACP Claude to sesja harness z kontrolkami ACP, wznawianiem sesji, śledzeniem zadań w tle oraz opcjonalnym powiązaniem z konwersacją/wątkiem. -- Backendy CLI to oddzielne lokalne, tylko tekstowe runtime zapasowe. Zobacz [CLI Backends](/pl/gateway/cli-backends). +- ACP Claude to sesja harness z kontrolkami ACP, wznawianiem sesji, śledzeniem zadań w tle i opcjonalnym powiązaniem z rozmową/wątkiem. +- CLI backends to oddzielne tekstowe lokalne runtime zapasowe. Zobacz [CLI Backends](/pl/gateway/cli-backends). Dla operatorów praktyczna zasada jest taka: -- chcesz `/acp spawn`, sesji, które można powiązać, kontrolek runtime albo trwałej pracy harness: użyj ACP -- chcesz prostego lokalnego fallbacku tekstowego przez surowe CLI: użyj backendów CLI +- chcesz `/acp spawn`, sesje możliwe do powiązania, kontrolki runtime albo trwałą pracę harness: użyj ACP +- chcesz prosty lokalny fallback tekstowy przez surowe CLI: użyj CLI backends -## Sesje powiązane +## Powiązane sesje -### Powiązania z bieżącą konwersacją +### Powiązania z bieżącą rozmową -Użyj `/acp spawn --bind here`, gdy chcesz, aby bieżąca konwersacja stała się trwałym workspace ACP bez tworzenia podrzędnego wątku. +Użyj `/acp spawn --bind here`, gdy chcesz, aby bieżąca rozmowa stała się trwałym obszarem roboczym ACP bez tworzenia podrzędnego wątku. Zachowanie: -- OpenClaw nadal obsługuje transport kanału, uwierzytelnianie, bezpieczeństwo i dostarczanie. -- Bieżąca konwersacja jest przypinana do uruchomionego klucza sesji ACP. -- Kolejne wiadomości w tej konwersacji są kierowane do tej samej sesji ACP. +- OpenClaw nadal zarządza transportem kanału, auth, bezpieczeństwem i dostarczaniem. +- Bieżąca rozmowa jest przypinana do uruchomionego klucza sesji ACP. +- Kolejne wiadomości w tej rozmowie są kierowane do tej samej sesji ACP. - `/new` i `/reset` resetują tę samą powiązaną sesję ACP na miejscu. -- `/acp close` zamyka sesję i usuwa powiązanie z bieżącą konwersacją. +- `/acp close` zamyka sesję i usuwa powiązanie bieżącej rozmowy. Co to oznacza w praktyce: - `--bind here` zachowuje tę samą powierzchnię czatu. Na Discord bieżący kanał pozostaje bieżącym kanałem. -- `--bind here` może nadal utworzyć nową sesję ACP, jeśli uruchamiasz świeżą pracę. Powiązanie dołącza tę sesję do bieżącej konwersacji. -- `--bind here` samo z siebie nie tworzy podrzędnego wątku Discord ani tematu Telegram. -- Runtime ACP może nadal mieć własny katalog roboczy (`cwd`) lub workspace zarządzany przez backend na dysku. Ten workspace runtime jest oddzielny od powierzchni czatu i nie oznacza nowego wątku wiadomości. -- Jeśli uruchamiasz do innego agenta ACP i nie podasz `--cwd`, OpenClaw domyślnie dziedziczy workspace **docelowego agenta**, a nie żądającego. -- Jeśli odziedziczona ścieżka workspace nie istnieje (`ENOENT`/`ENOTDIR`), OpenClaw wraca do domyślnego `cwd` backendu zamiast po cichu użyć niewłaściwego drzewa. -- Jeśli odziedziczony workspace istnieje, ale nie można uzyskać do niego dostępu (na przykład `EACCES`), uruchomienie zwraca rzeczywisty błąd dostępu zamiast porzucać `cwd`. +- `--bind here` nadal może utworzyć nową sesję ACP, jeśli uruchamiasz nową pracę. +- `--bind here` sam z siebie nie tworzy podrzędnego wątku Discord ani tematu Telegram. +- Runtime ACP nadal może mieć własny katalog roboczy (`cwd`) albo obszar roboczy zarządzany przez backend na dysku. Ten obszar roboczy runtime jest oddzielny od powierzchni czatu i nie oznacza nowego wątku wiadomości. +- Jeśli uruchamiasz do innego agenta ACP i nie podajesz `--cwd`, OpenClaw domyślnie dziedziczy obszar roboczy **docelowego agenta**, a nie żądającego. +- Jeśli ta odziedziczona ścieżka obszaru roboczego nie istnieje (`ENOENT`/`ENOTDIR`), OpenClaw wraca do domyślnego `cwd` backendu zamiast po cichu ponownie użyć niewłaściwego drzewa. +- Jeśli odziedziczony obszar roboczy istnieje, ale nie można uzyskać do niego dostępu (na przykład `EACCES`), uruchomienie zwraca rzeczywisty błąd dostępu zamiast porzucać `cwd`. Model mentalny: -- powierzchnia czatu: gdzie ludzie dalej rozmawiają (`kanał Discord`, `temat Telegram`, `czat iMessage`) -- sesja ACP: trwały stan runtime Codex/Claude/Gemini, do którego kieruje OpenClaw +- powierzchnia czatu: gdzie ludzie nadal rozmawiają (`kanał Discord`, `temat Telegram`, `czat iMessage`) +- sesja ACP: trwały stan runtime Codex/Claude/Gemini, do którego OpenClaw kieruje wiadomości - podrzędny wątek/temat: opcjonalna dodatkowa powierzchnia wiadomości tworzona tylko przez `--thread ...` -- workspace runtime: lokalizacja w systemie plików, gdzie działa harness (`cwd`, checkout repozytorium, workspace backendu) +- obszar roboczy runtime: lokalizacja w systemie plików, w której działa harness (`cwd`, checkout repozytorium, obszar roboczy backendu) Przykłady: -- `/acp spawn codex --bind here`: zachowaj ten czat, uruchom lub dołącz sesję Codex ACP i kieruj tu do niej przyszłe wiadomości +- `/acp spawn codex --bind here`: zachowaj ten czat, uruchom lub dołącz sesję Codex ACP i kieruj do niej przyszłe wiadomości stąd - `/acp spawn codex --thread auto`: OpenClaw może utworzyć podrzędny wątek/temat i tam powiązać sesję ACP -- `/acp spawn codex --bind here --cwd /workspace/repo`: to samo powiązanie z czatem co wyżej, ale Codex działa w `/workspace/repo` +- `/acp spawn codex --bind here --cwd /workspace/repo`: to samo powiązanie czatu co wyżej, ale Codex działa w `/workspace/repo` -Obsługa powiązań z bieżącą konwersacją: +Obsługa powiązań z bieżącą rozmową: -- Kanały czatu/wiadomości, które ogłaszają obsługę powiązań z bieżącą konwersacją, mogą używać `--bind here` przez współdzieloną ścieżkę powiązań konwersacji. -- Kanały z niestandardową semantyką wątków/tematów mogą nadal dostarczać kanoniczność specyficzną dla kanału za tym samym współdzielonym interfejsem. -- `--bind here` zawsze oznacza „powiąż bieżącą konwersację na miejscu”. -- Ogólne powiązania z bieżącą konwersacją używają współdzielonego magazynu powiązań OpenClaw i przetrwają zwykłe restarty gateway. +- Kanały czatu/wiadomości, które ogłaszają obsługę powiązania z bieżącą rozmową, mogą używać `--bind here` przez współdzieloną ścieżkę powiązań rozmów. +- Kanały z niestandardową semantyką wątków/tematów nadal mogą zapewniać kanoniczność specyficzną dla kanału za tym samym współdzielonym interfejsem. +- `--bind here` zawsze oznacza „powiąż bieżącą rozmowę na miejscu”. +- Ogólne powiązania z bieżącą rozmową używają współdzielonego magazynu powiązań OpenClaw i przetrwają zwykłe restarty gateway. Uwagi: - `--bind here` i `--thread ...` wzajemnie się wykluczają w `/acp spawn`. - Na Discord `--bind here` wiąże bieżący kanał lub wątek na miejscu. `spawnAcpSessions` jest wymagane tylko wtedy, gdy OpenClaw musi utworzyć podrzędny wątek dla `--thread auto|here`. -- Jeśli aktywny kanał nie udostępnia powiązań ACP z bieżącą konwersacją, OpenClaw zwraca jasny komunikat o braku obsługi. +- Jeśli aktywny kanał nie udostępnia powiązań ACP z bieżącą rozmową, OpenClaw zwraca jasny komunikat o braku obsługi. - `resume` i pytania o „nową sesję” dotyczą sesji ACP, a nie kanału. Możesz ponownie użyć albo zastąpić stan runtime bez zmiany bieżącej powierzchni czatu. ### Sesje powiązane z wątkiem -Gdy adapter kanału ma włączoną obsługę powiązań wątków, sesje ACP mogą być powiązane z wątkami: +Gdy powiązania wątków są włączone dla adaptera kanału, sesje ACP mogą być powiązane z wątkami: - OpenClaw wiąże wątek z docelową sesją ACP. - Kolejne wiadomości w tym wątku są kierowane do powiązanej sesji ACP. -- Dane wyjściowe ACP są dostarczane z powrotem do tego samego wątku. -- Wyłączenie skupienia/zamknięcie/archiwizacja/timeout bezczynności albo wygaśnięcie maksymalnego wieku usuwa powiązanie. +- Wynik ACP jest dostarczany z powrotem do tego samego wątku. +- Odfokusowanie/zamknięcie/archiwizacja/wygaśnięcie limitu bezczynności lub maksymalnego wieku usuwa powiązanie. -Obsługa powiązań wątków jest specyficzna dla adaptera. Jeśli aktywny adapter kanału nie obsługuje powiązań wątków, OpenClaw zwraca jasny komunikat unsupported/unavailable. +Obsługa powiązań wątków zależy od adaptera. Jeśli aktywny adapter kanału nie obsługuje powiązań wątków, OpenClaw zwraca jasny komunikat, że funkcja jest nieobsługiwana/niedostępna. -Wymagane flagi funkcji dla ACP powiązanego z wątkiem: +Wymagane feature flags dla ACP powiązanego z wątkiem: - `acp.enabled=true` - `acp.dispatch.enabled` jest domyślnie włączone (ustaw `false`, aby wstrzymać dispatch ACP) -- Włączona flaga uruchamiania wątków ACP adaptera kanału (specyficzna dla adaptera) +- Włączona flaga uruchamiania wątków ACP adaptera kanału (zależna od adaptera) - Discord: `channels.discord.threadBindings.spawnAcpSessions=true` - Telegram: `channels.telegram.threadBindings.spawnAcpSessions=true` ### Kanały obsługujące wątki -- Dowolny adapter kanału, który udostępnia możliwość powiązań sesji/wątków. -- Obecne wbudowane wsparcie: +- Dowolny adapter kanału, który udostępnia możliwość powiązania sesji/wątku. +- Bieżąca wbudowana obsługa: - wątki/kanały Discord - - tematy Telegram (tematy forum w grupach/supergrupach oraz tematy DM) + - tematy Telegram (tematy forum w grupach/supergrupach i tematy DM) - Kanały pluginów mogą dodać obsługę przez ten sam interfejs powiązań. ## Ustawienia specyficzne dla kanału -W przypadku workflow nieefemerycznych skonfiguruj trwałe powiązania ACP w wpisach najwyższego poziomu `bindings[]`. +W przypadku nieefemerycznych przepływów pracy skonfiguruj trwałe powiązania ACP w wpisach najwyższego poziomu `bindings[]`. ### Model powiązań -- `bindings[].type="acp"` oznacza trwałe powiązanie konwersacji ACP. -- `bindings[].match` identyfikuje docelową konwersację: +- `bindings[].type="acp"` oznacza trwałe powiązanie rozmowy ACP. +- `bindings[].match` identyfikuje docelową rozmowę: - kanał lub wątek Discord: `match.channel="discord"` + `match.peer.id=""` - temat forum Telegram: `match.channel="telegram"` + `match.peer.id=":topic:"` - - czat DM/grupowy BlueBubbles: `match.channel="bluebubbles"` + `match.peer.id=""` + - czat DM/grupowy BlueBubbles: `match.channel="bluebubbles"` + `match.peer.id=""` Dla stabilnych powiązań grup preferuj `chat_id:*` lub `chat_identifier:*`. - - czat DM/grupowy iMessage: `match.channel="imessage"` + `match.peer.id=""` + - czat DM/grupowy iMessage: `match.channel="imessage"` + `match.peer.id=""` Dla stabilnych powiązań grup preferuj `chat_id:*`. -- `bindings[].agentId` to identyfikator właściciela agenta OpenClaw. +- `bindings[].agentId` to identyfikator właścicielskiego agenta OpenClaw. - Opcjonalne nadpisania ACP znajdują się w `bindings[].acp`: - `mode` (`persistent` lub `oneshot`) - `label` - `cwd` - `backend` -### Domyślne ustawienia runtime dla agenta +### Domyślne ustawienia runtime na agenta Użyj `agents.list[].runtime`, aby zdefiniować domyślne ustawienia ACP raz dla każdego agenta: - `agents.list[].runtime.type="acp"` -- `agents.list[].runtime.acp.agent` (identyfikator harnessu, na przykład `codex` albo `claude`) +- `agents.list[].runtime.acp.agent` (identyfikator harness, na przykład `codex` lub `claude`) - `agents.list[].runtime.acp.backend` - `agents.list[].runtime.acp.mode` - `agents.list[].runtime.acp.cwd` @@ -239,7 +239,7 @@ Kolejność pierwszeństwa nadpisań dla powiązanych sesji ACP: 1. `bindings[].acp.*` 2. `agents.list[].runtime.acp.*` -3. globalne wartości domyślne ACP (na przykład `acp.backend`) +3. globalne ustawienia domyślne ACP (na przykład `acp.backend`) Przykład: @@ -323,12 +323,12 @@ Przykład: Zachowanie: -- OpenClaw upewnia się, że skonfigurowana sesja ACP istnieje przed użyciem. +- OpenClaw zapewnia istnienie skonfigurowanej sesji ACP przed użyciem. - Wiadomości w tym kanale lub temacie są kierowane do skonfigurowanej sesji ACP. -- W powiązanych konwersacjach `/new` i `/reset` resetują ten sam klucz sesji ACP na miejscu. -- Tymczasowe powiązania runtime (na przykład utworzone przez przepływy focus wątków) nadal mają zastosowanie, jeśli istnieją. -- Przy uruchamianiu między agentami ACP bez jawnego `cwd` OpenClaw dziedziczy workspace docelowego agenta z konfiguracji agenta. -- Brakujące odziedziczone ścieżki workspace powodują fallback do domyślnego `cwd` backendu; rzeczywiste błędy dostępu do istniejących ścieżek są zwracane jako błędy uruchamiania. +- W powiązanych rozmowach `/new` i `/reset` resetują ten sam klucz sesji ACP na miejscu. +- Tymczasowe powiązania runtime (na przykład utworzone przez przepływy fokusu wątków) nadal mają zastosowanie tam, gdzie istnieją. +- Przy uruchamianiu ACP między agentami bez jawnego `cwd` OpenClaw dziedziczy obszar roboczy docelowego agenta z konfiguracji agenta. +- Brakujące odziedziczone ścieżki obszaru roboczego wracają do domyślnego `cwd` backendu; rzeczywiste błędy dostępu są zwracane jako błędy uruchomienia. ## Uruchamianie sesji ACP (interfejsy) @@ -348,29 +348,29 @@ Użyj `runtime: "acp"`, aby uruchomić sesję ACP z tury agenta lub wywołania n Uwagi: -- `runtime` domyślnie ma wartość `subagent`, więc dla sesji ACP ustaw jawnie `runtime: "acp"`. -- Jeśli `agentId` zostanie pominięte, OpenClaw używa `acp.defaultAgent`, gdy jest skonfigurowane. -- `mode: "session"` wymaga `thread: true`, aby zachować trwałą powiązaną konwersację. +- `runtime` domyślnie ma wartość `subagent`, więc ustaw `runtime: "acp"` jawnie dla sesji ACP. +- Jeśli pominięto `agentId`, OpenClaw użyje `acp.defaultAgent`, jeśli jest skonfigurowane. +- `mode: "session"` wymaga `thread: true`, aby zachować trwałą powiązaną rozmowę. Szczegóły interfejsu: - `task` (wymagane): początkowy prompt wysyłany do sesji ACP. - `runtime` (wymagane dla ACP): musi mieć wartość `"acp"`. -- `agentId` (opcjonalne): identyfikator docelowego harnessu ACP. Jeśli ustawione, fallback do `acp.defaultAgent`. -- `thread` (opcjonalne, domyślnie `false`): żądanie przepływu powiązania z wątkiem tam, gdzie jest obsługiwany. +- `agentId` (opcjonalne): identyfikator docelowego harness ACP. Wraca do `acp.defaultAgent`, jeśli jest ustawiony. +- `thread` (opcjonalne, domyślnie `false`): żądanie przepływu powiązania z wątkiem, gdy jest obsługiwane. - `mode` (opcjonalne): `run` (jednorazowe) albo `session` (trwałe). - domyślnie jest `run` - - jeśli `thread: true` i `mode` pominięte, OpenClaw może domyślnie przejść do zachowania trwałego zależnie od ścieżki runtime + - jeśli `thread: true` i `mode` pominięto, OpenClaw może domyślnie przejść do zachowania trwałego zależnie od ścieżki runtime - `mode: "session"` wymaga `thread: true` -- `cwd` (opcjonalne): żądany katalog roboczy runtime (walidowany przez backend/politykę runtime). Jeśli zostanie pominięte, uruchomienie ACP dziedziczy workspace docelowego agenta, jeśli jest skonfigurowane; brakujące odziedziczone ścieżki powodują fallback do domyślnych ustawień backendu, natomiast rzeczywiste błędy dostępu są zwracane. -- `label` (opcjonalne): etykieta widoczna dla operatora używana w tekście sesji/banneru. -- `resumeSessionId` (opcjonalne): wznów istniejącą sesję ACP zamiast tworzyć nową. Agent odtwarza historię konwersacji przez `session/load`. Wymaga `runtime: "acp"`. -- `streamTo` (opcjonalne): `"parent"` przesyła podsumowania postępu początkowego uruchomienia ACP z powrotem do sesji żądającej jako zdarzenia systemowe. - - Gdy jest dostępne, zaakceptowane odpowiedzi zawierają `streamLogPath` wskazujące plik JSONL z zakresem sesji (`.acp-stream.jsonl`), który można śledzić, aby zobaczyć pełną historię przekazywania. +- `cwd` (opcjonalne): żądany katalog roboczy runtime (walidowany przez politykę backendu/runtime). Jeśli pominięty, uruchomienie ACP dziedziczy obszar roboczy docelowego agenta, gdy jest skonfigurowany; brakujące odziedziczone ścieżki wracają do domyślnych backendu, a rzeczywiste błędy dostępu są zwracane. +- `label` (opcjonalne): etykieta widoczna dla operatora używana w tekście sesji/banera. +- `resumeSessionId` (opcjonalne): wznowienie istniejącej sesji ACP zamiast tworzenia nowej. Agent odtwarza historię rozmowy przez `session/load`. Wymaga `runtime: "acp"`. +- `streamTo` (opcjonalne): `"parent"` strumieniuje podsumowania postępu początkowego uruchomienia ACP z powrotem do sesji żądającej jako zdarzenia systemowe. + - Gdy dostępne, zaakceptowane odpowiedzi zawierają `streamLogPath`, wskazujące na plik JSONL logu o zakresie sesji (`.acp-stream.jsonl`), który można śledzić, aby zobaczyć pełną historię przekazywania. -### Wznawianie istniejącej sesji +### Wznowienie istniejącej sesji -Użyj `resumeSessionId`, aby kontynuować poprzednią sesję ACP zamiast rozpoczynać od nowa. Agent odtwarza historię konwersacji przez `session/load`, więc wznawia pracę z pełnym kontekstem wcześniejszych działań. +Użyj `resumeSessionId`, aby kontynuować poprzednią sesję ACP zamiast zaczynać od nowa. Agent odtwarza historię rozmowy przez `session/load`, więc wznawia pracę z pełnym kontekstem tego, co było wcześniej. ```json { @@ -383,39 +383,38 @@ Użyj `resumeSessionId`, aby kontynuować poprzednią sesję ACP zamiast rozpocz Typowe przypadki użycia: -- Przekazanie sesji Codex z laptopa na telefon — powiedz agentowi, aby podjął pracę tam, gdzie została przerwana -- Kontynuacja sesji programistycznej rozpoczętej interaktywnie w CLI, teraz bezobsługowo przez agenta -- Podjęcie pracy przerwanej przez restart gateway albo timeout bezczynności +- Przekazanie sesji Codex z laptopa na telefon — poproś agenta, aby podjął pracę tam, gdzie skończyłeś +- Kontynuowanie sesji programistycznej rozpoczętej interaktywnie w CLI, teraz bezgłowo przez agenta +- Wznowienie pracy przerwanej przez restart gateway albo timeout bezczynności Uwagi: -- `resumeSessionId` wymaga `runtime: "acp"` — zwraca błąd, jeśli zostanie użyte z runtime sub-agenta. -- `resumeSessionId` przywraca historię konwersacji upstream ACP; `thread` i `mode` nadal normalnie dotyczą nowej sesji OpenClaw, którą tworzysz, więc `mode: "session"` nadal wymaga `thread: true`. -- Docelowy agent musi obsługiwać `session/load` (Codex i Claude Code obsługują). -- Jeśli identyfikator sesji nie zostanie znaleziony, uruchomienie kończy się jasnym błędem — bez cichego fallbacku do nowej sesji. +- `resumeSessionId` wymaga `runtime: "acp"` — zwraca błąd, jeśli zostanie użyte z runtime podagenta. +- `resumeSessionId` przywraca historię rozmowy upstream ACP; `thread` i `mode` nadal stosują się normalnie do nowej sesji OpenClaw, którą tworzysz, więc `mode: "session"` nadal wymaga `thread: true`. +- Docelowy agent musi obsługiwać `session/load` (Codex i Claude Code to obsługują). +- Jeśli identyfikator sesji nie zostanie znaleziony, uruchomienie kończy się jawnym błędem — bez cichego przejścia do nowej sesji. -### Test smoke dla operatora +### Smoke test operatora -Użyj tego po wdrożeniu gateway, gdy chcesz szybko na żywo sprawdzić, czy uruchamianie ACP -rzeczywiście działa end-to-end, a nie tylko przechodzi testy jednostkowe. +Użyj tego po wdrożeniu gateway, gdy chcesz szybko na żywo sprawdzić, czy uruchamianie ACP naprawdę działa end-to-end, a nie tylko przechodzi testy jednostkowe. Zalecana bramka: -1. Zweryfikuj wdrożoną wersję/commit gateway na docelowym hoście. +1. Zweryfikuj wdrożoną wersję/commit gateway na hoście docelowym. 2. Potwierdź, że wdrożone źródło zawiera akceptację linii ACP w `src/gateway/sessions-patch.ts` (`subagent:* or acp:* sessions`). -3. Otwórz tymczasową sesję mostu ACPX do aktywnego agenta (na przykład +3. Otwórz tymczasową sesję mostka ACPX do aktywnego agenta (na przykład `razor(main)` na `jpclawhq`). 4. Poproś tego agenta o wywołanie `sessions_spawn` z: - `runtime: "acp"` - `agentId: "codex"` - `mode: "run"` - - zadaniem: `Reply with exactly LIVE-ACP-SPAWN-OK` -5. Zweryfikuj, że agent raportuje: + - task: `Reply with exactly LIVE-ACP-SPAWN-OK` +5. Zweryfikuj, że agent zgłasza: - `accepted=yes` - rzeczywisty `childSessionKey` - brak błędu walidatora -6. Wyczyść tymczasową sesję mostu ACPX. +6. Posprzątaj tymczasową sesję mostka ACPX. Przykładowy prompt do aktywnego agenta: @@ -427,16 +426,16 @@ Then report only: accepted=; childSessionKey=; error=` | -| `/acp steer` | Wysyła instrukcję sterującą do działającej sesji. | `/acp steer --session support inbox prioritize failing tests` | -| `/acp close` | Zamyka sesję i odwiązuje cele wątków. | `/acp close` | -| `/acp status` | Pokazuje backend, tryb, stan, opcje runtime, możliwości. | `/acp status` | -| `/acp set-mode` | Ustawia tryb runtime dla docelowej sesji. | `/acp set-mode plan` | -| `/acp set` | Ogólny zapis opcji konfiguracji runtime. | `/acp set model openai/gpt-5.4` | -| `/acp cwd` | Ustawia nadpisanie katalogu roboczego runtime. | `/acp cwd /Users/user/Projects/repo` | -| `/acp permissions` | Ustawia profil polityki zatwierdzeń. | `/acp permissions strict` | -| `/acp timeout` | Ustawia timeout runtime (sekundy). | `/acp timeout 120` | -| `/acp model` | Ustawia nadpisanie modelu runtime. | `/acp model anthropic/claude-opus-4-6` | -| `/acp reset-options` | Usuwa nadpisania opcji runtime dla sesji. | `/acp reset-options` | -| `/acp sessions` | Wyświetla ostatnie sesje ACP z magazynu. | `/acp sessions` | -| `/acp doctor` | Stan backendu, możliwości, konkretne poprawki. | `/acp doctor` | -| `/acp install` | Wypisuje deterministyczne kroki instalacji i włączenia. | `/acp install` | +| Polecenie | Co robi | Przykład | +| --- | --- | --- | +| `/acp spawn` | Tworzy sesję ACP; opcjonalnie powiązanie z bieżącą rozmową albo z wątkiem. | `/acp spawn codex --bind here --cwd /repo` | +| `/acp cancel` | Anuluje turę będącą w toku dla docelowej sesji. | `/acp cancel agent:codex:acp:` | +| `/acp steer` | Wysyła instrukcję sterującą do uruchomionej sesji. | `/acp steer --session support inbox prioritize failing tests` | +| `/acp close` | Zamyka sesję i odpina cele wątków. | `/acp close` | +| `/acp status` | Pokazuje backend, tryb, stan, opcje runtime, możliwości. | `/acp status` | +| `/acp set-mode` | Ustawia tryb runtime dla docelowej sesji. | `/acp set-mode plan` | +| `/acp set` | Ogólny zapis opcji konfiguracji runtime. | `/acp set model openai/gpt-5.4` | +| `/acp cwd` | Ustawia nadpisanie katalogu roboczego runtime. | `/acp cwd /Users/user/Projects/repo` | +| `/acp permissions` | Ustawia profil polityki zatwierdzeń. | `/acp permissions strict` | +| `/acp timeout` | Ustawia limit czasu runtime (sekundy). | `/acp timeout 120` | +| `/acp model` | Ustawia nadpisanie modelu runtime. | `/acp model anthropic/claude-opus-4-6` | +| `/acp reset-options` | Usuwa nadpisania opcji runtime sesji. | `/acp reset-options` | +| `/acp sessions` | Wyświetla ostatnie sesje ACP z magazynu. | `/acp sessions` | +| `/acp doctor` | Stan backendu, możliwości, możliwe działania naprawcze. | `/acp doctor` | +| `/acp install` | Wyświetla deterministyczne kroki instalacji i włączenia. | `/acp install` | -`/acp sessions` odczytuje magazyn dla bieżącej powiązanej sesji albo sesji żądającej. Polecenia akceptujące tokeny `session-key`, `session-id` albo `session-label` rozwiązują cele przez wykrywanie sesji gateway, w tym niestandardowe katalogi `session.store` dla poszczególnych agentów. +`/acp sessions` odczytuje magazyn dla bieżącej powiązanej sesji albo sesji żądającej. Polecenia, które akceptują tokeny `session-key`, `session-id` albo `session-label`, rozpoznają cele przez wykrywanie sesji gateway, w tym niestandardowe katalogi `session.store` dla poszczególnych agentów. ## Mapowanie opcji runtime -`/acp` ma polecenia wygodne i ogólny setter. +`/acp` ma wygodne polecenia i generyczny setter. -Operacje równoważne: +Równoważne operacje: -- `/acp model ` mapuje się na klucz konfiguracji runtime `model`. -- `/acp permissions ` mapuje się na klucz konfiguracji runtime `approval_policy`. -- `/acp timeout ` mapuje się na klucz konfiguracji runtime `timeout`. +- `/acp model ` mapuje do klucza konfiguracji runtime `model`. +- `/acp permissions ` mapuje do klucza konfiguracji runtime `approval_policy`. +- `/acp timeout ` mapuje do klucza konfiguracji runtime `timeout`. - `/acp cwd ` bezpośrednio aktualizuje nadpisanie `cwd` runtime. - `/acp set ` to ścieżka ogólna. - - Szczególny przypadek: `key=cwd` używa ścieżki nadpisania `cwd`. + - Przypadek specjalny: `key=cwd` używa ścieżki nadpisania `cwd`. - `/acp reset-options` czyści wszystkie nadpisania runtime dla docelowej sesji. -## Obsługa harnessów acpx (obecnie) +## Obsługa harness acpx (obecnie) -Obecne wbudowane aliasy harnessów acpx: +Bieżące wbudowane aliasy harness acpx: - `claude` - `codex` @@ -598,20 +597,20 @@ Obecne wbudowane aliasy harnessów acpx: - `pi` - `qwen` -Gdy OpenClaw używa backendu acpx, dla `agentId` preferuj te wartości, chyba że konfiguracja acpx definiuje niestandardowe aliasy agentów. -Jeśli lokalna instalacja Cursor nadal ujawnia ACP jako `agent acp`, nadpisz polecenie agenta `cursor` w konfiguracji acpx zamiast zmieniać wbudowaną wartość domyślną. +Gdy OpenClaw używa backendu acpx, preferuj te wartości dla `agentId`, chyba że konfiguracja acpx definiuje własne aliasy agentów. +Jeśli lokalna instalacja Cursor nadal udostępnia ACP jako `agent acp`, nadpisz polecenie agenta `cursor` w swojej konfiguracji acpx zamiast zmieniać wbudowaną wartość domyślną. -Bezpośrednie użycie CLI acpx może też kierować do dowolnych adapterów przez `--agent `, ale ta surowa furtka ucieczki jest funkcją CLI acpx (a nie normalną ścieżką `agentId` OpenClaw). +Bezpośrednie użycie CLI acpx może również kierować żądania do dowolnych adapterów przez `--agent `, ale ta surowa furtka jest funkcją CLI acpx (a nie zwykłą ścieżką `agentId` w OpenClaw). ## Wymagana konfiguracja -Podstawowa konfiguracja ACP: +Bazowa konfiguracja ACP: ```json5 { acp: { enabled: true, - // Opcjonalne. Wartość domyślna to true; ustaw false, aby wstrzymać dispatch ACP przy zachowaniu kontrolek /acp. + // Optional. Default is true; set false to pause ACP dispatch while keeping /acp controls. dispatch: { enabled: true }, backend: "acpx", defaultAgent: "codex", @@ -643,7 +642,7 @@ Podstawowa konfiguracja ACP: } ``` -Konfiguracja powiązań wątków jest specyficzna dla adaptera kanału. Przykład dla Discord: +Konfiguracja powiązania wątków zależy od adaptera kanału. Przykład dla Discord: ```json5 { @@ -669,14 +668,13 @@ Jeśli uruchamianie ACP powiązane z wątkiem nie działa, najpierw sprawdź fla - Discord: `channels.discord.threadBindings.spawnAcpSessions=true` -Powiązania z bieżącą konwersacją nie wymagają tworzenia podrzędnego wątku. Wymagają aktywnego kontekstu konwersacji i adaptera kanału, który udostępnia powiązania konwersacji ACP. +Powiązania z bieżącą rozmową nie wymagają tworzenia podrzędnego wątku. Wymagają aktywnego kontekstu rozmowy i adaptera kanału, który udostępnia powiązania rozmów ACP. Zobacz [Configuration Reference](/pl/gateway/configuration-reference). ## Konfiguracja pluginu dla backendu acpx -Świeże instalacje mają domyślnie włączony dołączony plugin runtime `acpx`, więc ACP -zwykle działa bez ręcznej instalacji pluginu. +Świeże instalacje są dostarczane z włączonym domyślnie dołączonym pluginem runtime `acpx`, więc ACP zwykle działa bez ręcznego kroku instalacji pluginu. Zacznij od: @@ -692,13 +690,13 @@ openclaw plugins install acpx openclaw config set plugins.entries.acpx.enabled true ``` -Instalacja lokalnego workspace podczas developmentu: +Lokalna instalacja obszaru roboczego podczas programowania: ```bash openclaw plugins install ./path/to/local/acpx-plugin ``` -Następnie zweryfikuj stan backendu: +Następnie sprawdź stan backendu: ```text /acp doctor @@ -706,14 +704,14 @@ Następnie zweryfikuj stan backendu: ### Konfiguracja polecenia i wersji acpx -Domyślnie dołączony plugin backendu acpx (`acpx`) używa lokalnego, przypiętego pliku binarnego pluginu: +Domyślnie dołączony plugin backendu acpx (`acpx`) używa lokalnego dla pluginu przypiętego pliku binarnego: -1. Polecenie domyślnie wskazuje na lokalny dla pluginu `node_modules/.bin/acpx` wewnątrz pakietu pluginu ACPX. -2. Oczekiwana wersja domyślnie odpowiada przypięciu rozszerzenia. -3. Przy starcie backend ACP jest natychmiast rejestrowany jako not-ready. +1. Polecenie domyślnie wskazuje lokalny dla pluginu `node_modules/.bin/acpx` wewnątrz pakietu pluginu ACPX. +2. Oczekiwana wersja domyślnie jest zgodna z przypięciem rozszerzenia. +3. Przy uruchomieniu ACP backend jest rejestrowany od razu jako niegotowy. 4. Zadanie ensure w tle weryfikuje `acpx --version`. -5. Jeśli lokalny plik binarny pluginu nie istnieje lub wersja się nie zgadza, uruchamia: - `npm install --omit=dev --no-save acpx@` i ponownie weryfikuje. +5. Jeśli lokalny dla pluginu plik binarny jest nieobecny albo ma niezgodną wersję, uruchamiane jest: + `npm install --omit=dev --no-save acpx@` i następuje ponowna weryfikacja. Możesz nadpisać polecenie/wersję w konfiguracji pluginu: @@ -735,25 +733,25 @@ Możesz nadpisać polecenie/wersję w konfiguracji pluginu: Uwagi: -- `command` akceptuje ścieżkę bezwzględną, ścieżkę względną lub nazwę polecenia (`acpx`). -- Ścieżki względne są rozwiązywane względem katalogu workspace OpenClaw. +- `command` akceptuje ścieżkę bezwzględną, ścieżkę względną albo nazwę polecenia (`acpx`). +- Ścieżki względne są rozwiązywane względem katalogu obszaru roboczego OpenClaw. - `expectedVersion: "any"` wyłącza ścisłe dopasowanie wersji. -- Gdy `command` wskazuje niestandardowy plik binarny/ścieżkę, automatyczna instalacja lokalna pluginu jest wyłączona. -- Uruchamianie OpenClaw pozostaje nieblokujące, gdy działa sprawdzanie stanu backendu w tle. +- Gdy `command` wskazuje niestandardowy plik binarny/ścieżkę, automatyczna instalacja lokalna dla pluginu jest wyłączona. +- Uruchamianie OpenClaw pozostaje nieblokujące podczas działania sprawdzania stanu backendu w tle. Zobacz [Plugins](/pl/tools/plugin). ### Automatyczna instalacja zależności -Gdy instalujesz OpenClaw globalnie przez `npm install -g openclaw`, zależności runtime `acpx` -(pliki binarne zależne od platformy) są instalowane automatycznie +Gdy instalujesz OpenClaw globalnie przez `npm install -g openclaw`, zależności runtime acpx +(binaria zależne od platformy) są instalowane automatycznie przez hook postinstall. Jeśli automatyczna instalacja się nie powiedzie, gateway nadal uruchamia się -normalnie i raportuje brakującą zależność przez `openclaw acp doctor`. +normalnie i zgłasza brakującą zależność przez `openclaw acp doctor`. ### Most MCP dla narzędzi pluginów -Domyślnie sesje ACPX **nie** udostępniają harnessowi ACP narzędzi -zarejestrowanych przez pluginy OpenClaw. +Domyślnie sesje ACPX **nie** udostępniają narzędzi rejestrowanych przez pluginy OpenClaw +harness ACP. Jeśli chcesz, aby agenci ACP, tacy jak Codex albo Claude Code, mogli wywoływać zainstalowane narzędzia pluginów OpenClaw, takie jak memory recall/store, włącz dedykowany most: @@ -764,45 +762,58 @@ openclaw config set plugins.entries.acpx.config.pluginToolsMcpBridge true Co to robi: -- Wstrzykuje w bootstrap sesji ACPX wbudowany serwer MCP o nazwie `openclaw-plugin-tools`. +- Wstrzykuje wbudowany serwer MCP o nazwie `openclaw-plugin-tools` do bootstrapu sesji ACPX. - Udostępnia narzędzia pluginów już zarejestrowane przez zainstalowane i włączone pluginy OpenClaw. -- Utrzymuje tę funkcję jako jawną i domyślnie wyłączoną. +- Zachowuje tę funkcję jako jawną i domyślnie wyłączoną. Uwagi dotyczące bezpieczeństwa i zaufania: -- To rozszerza powierzchnię narzędzi harnessu ACP. +- To rozszerza powierzchnię narzędzi harness ACP. - Agenci ACP otrzymują dostęp tylko do narzędzi pluginów już aktywnych w gateway. -- Traktuj to jako tę samą granicę zaufania co pozwolenie tym pluginom wykonywać się +- Traktuj to jako tę samą granicę zaufania, co pozwolenie tym pluginom na wykonywanie działań w samym OpenClaw. -- Przed włączeniem przejrzyj zainstalowane pluginy. +- Przejrzyj zainstalowane pluginy przed włączeniem tej funkcji. -Niestandardowe `mcpServers` nadal działają jak wcześniej. Wbudowany most plugin-tools to -dodatkowa, opcjonalna wygoda, a nie zamiennik ogólnej konfiguracji serwera MCP. +Niestandardowe `mcpServers` nadal działają jak wcześniej. Wbudowany most narzędzi pluginów jest +dodatkową wygodną funkcją opt-in, a nie zamiennikiem ogólnej konfiguracji serwera MCP. + +### Konfiguracja limitu czasu runtime + +Dołączony plugin `acpx` domyślnie ustawia 120-sekundowy +limit czasu dla osadzonych tur runtime. Daje to wolniejszym harnesses, takim jak Gemini CLI, dość czasu na ukończenie +uruchamiania i inicjalizacji ACP. Nadpisz tę wartość, jeśli host wymaga innego +limitu runtime: + +```bash +openclaw config set plugins.entries.acpx.config.timeoutSeconds 180 +``` + +Uruchom ponownie gateway po zmianie tej wartości. ## Konfiguracja uprawnień -Sesje ACP działają nieinteraktywnie — nie ma TTY do zatwierdzania ani odrzucania promptów uprawnień zapisu plików i wykonywania poleceń powłoki. Plugin acpx dostarcza dwa klucze konfiguracji, które kontrolują obsługę uprawnień: +Sesje ACP działają nieinteraktywnie — nie ma TTY do zatwierdzania ani odrzucania promptów uprawnień zapisu plików i wykonywania poleceń powłoki. Plugin acpx udostępnia dwa klucze konfiguracyjne kontrolujące sposób obsługi uprawnień: -Te uprawnienia harnessów ACPX są oddzielne od zatwierdzeń exec OpenClaw i oddzielne od flag omijania po stronie producenta backendów CLI, takich jak Claude CLI `--permission-mode bypassPermissions`. ACPX `approve-all` to awaryjny przełącznik na poziomie harnessu dla sesji ACP. +Te uprawnienia harness ACPX są oddzielne od zatwierdzeń exec OpenClaw i oddzielne od flag obejścia dostawcy backendu CLI, takich jak Claude CLI `--permission-mode bypassPermissions`. ACPX `approve-all` jest przełącznikiem awaryjnym na poziomie harness dla sesji ACP. ### `permissionMode` -Kontroluje, które operacje agent harnessu może wykonywać bez promptu. +Kontroluje, jakie operacje agent harness może wykonywać bez promptu. -| Wartość | Zachowanie | -| --------------- | --------------------------------------------------------- | -| `approve-all` | Automatycznie zatwierdza wszystkie zapisy plików i polecenia powłoki. | -| `approve-reads` | Automatycznie zatwierdza tylko odczyty; zapisy i wykonanie wymagają promptów. | -| `deny-all` | Odrzuca wszystkie prompty uprawnień. | +| Wartość | Zachowanie | +| --- | --- | +| `approve-all` | Automatycznie zatwierdza wszystkie zapisy plików i polecenia powłoki. | +| `approve-reads` | Automatycznie zatwierdza tylko odczyty; zapis i exec wymagają promptów. | +| `deny-all` | Odrzuca wszystkie prompty uprawnień. | ### `nonInteractivePermissions` -Kontroluje, co dzieje się, gdy prompt uprawnień miałby zostać pokazany, ale interaktywny TTY nie jest dostępny (co zawsze dotyczy sesji ACP). +Kontroluje, co dzieje się, gdy prompt uprawnień normalnie zostałby pokazany, ale nie ma dostępnego interaktywnego TTY (co zawsze ma miejsce w sesjach ACP). -| Wartość | Zachowanie | -| ------ | ----------------------------------------------------------------- | -| `fail` | Przerywa sesję z `AcpRuntimeError`. **(domyślnie)** | -| `deny` | Po cichu odrzuca uprawnienie i kontynuuje (łagodna degradacja). | +| Wartość | Zachowanie | +| --- | --- | +| `fail` | Przerywa sesję z `AcpRuntimeError`. **(domyślne)** | +| `deny` | Cicho odrzuca uprawnienie i kontynuuje (łagodna degradacja). | ### Konfiguracja @@ -817,25 +828,25 @@ Uruchom ponownie gateway po zmianie tych wartości. > **Ważne:** OpenClaw obecnie domyślnie używa `permissionMode=approve-reads` i `nonInteractivePermissions=fail`. W nieinteraktywnych sesjach ACP każdy zapis lub exec, który wywoła prompt uprawnień, może zakończyć się błędem `AcpRuntimeError: Permission prompt unavailable in non-interactive mode`. > -> Jeśli musisz ograniczyć uprawnienia, ustaw `nonInteractivePermissions` na `deny`, aby sesje łagodnie degradowały się zamiast kończyć awarią. +> Jeśli musisz ograniczyć uprawnienia, ustaw `nonInteractivePermissions` na `deny`, aby sesje ulegały łagodnej degradacji zamiast się wykrzaczać. ## Rozwiązywanie problemów -| Objaw | Prawdopodobna przyczyna | Poprawka | -| --------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `ACP runtime backend is not configured` | Brak pluginu backendu lub jest wyłączony. | Zainstaluj i włącz plugin backendu, a następnie uruchom `/acp doctor`. | -| `ACP is disabled by policy (acp.enabled=false)` | ACP jest globalnie wyłączone. | Ustaw `acp.enabled=true`. | -| `ACP dispatch is disabled by policy (acp.dispatch.enabled=false)` | Dispatch z normalnych wiadomości w wątku jest wyłączony. | Ustaw `acp.dispatch.enabled=true`. | -| `ACP agent "" is not allowed by policy` | Agent nie znajduje się na allowliście. | Użyj dozwolonego `agentId` albo zaktualizuj `acp.allowedAgents`. | -| `Unable to resolve session target: ...` | Błędny token key/id/label. | Uruchom `/acp sessions`, skopiuj dokładny key/label, spróbuj ponownie. | -| `--bind here requires running /acp spawn inside an active ... conversation` | `--bind here` użyte bez aktywnej konwersacji, którą można powiązać. | Przejdź do docelowego czatu/kanału i spróbuj ponownie albo użyj uruchomienia bez powiązania. | -| `Conversation bindings are unavailable for .` | Adapter nie ma możliwości powiązań ACP z bieżącą konwersacją. | Użyj `/acp spawn ... --thread ...` tam, gdzie jest obsługiwane, skonfiguruj wpisy najwyższego poziomu `bindings[]` albo przejdź na obsługiwany kanał. | -| `--thread here requires running /acp spawn inside an active ... thread` | `--thread here` użyte poza kontekstem wątku. | Przejdź do docelowego wątku albo użyj `--thread auto`/`off`. | -| `Only can rebind this channel/conversation/thread.` | Inny użytkownik jest właścicielem aktywnego celu powiązania. | Powiąż ponownie jako właściciel albo użyj innej konwersacji lub wątku. | -| `Thread bindings are unavailable for .` | Adapter nie ma możliwości powiązań wątków. | Użyj `--thread off` albo przejdź do obsługiwanego adaptera/kanału. | -| `Sandboxed sessions cannot spawn ACP sessions ...` | Runtime ACP działa po stronie hosta; sesja żądająca jest sandboxowana. | Użyj `runtime="subagent"` z sesji sandboxowanych albo uruchom ACP z sesji bez sandboxa. | -| `sessions_spawn sandbox="require" is unsupported for runtime="acp" ...` | Zażądano `sandbox="require"` dla runtime ACP. | Użyj `runtime="subagent"` dla wymaganego sandboxowania albo ACP z `sandbox="inherit"` z sesji bez sandboxa. | -| Brak metadanych ACP dla powiązanej sesji | Nieaktualne/usunięte metadane sesji ACP. | Odtwórz przez `/acp spawn`, a następnie ponownie powiąż/skup wątek. | -| `AcpRuntimeError: Permission prompt unavailable in non-interactive mode` | `permissionMode` blokuje zapis/exec w nieinteraktywnej sesji ACP. | Ustaw `plugins.entries.acpx.config.permissionMode` na `approve-all` i uruchom ponownie gateway. Zobacz [Konfiguracja uprawnień](#konfiguracja-uprawnień). | -| Sesja ACP kończy się bardzo wcześnie z niewielką ilością danych wyjściowych | Prompty uprawnień są blokowane przez `permissionMode`/`nonInteractivePermissions`. | Sprawdź logi gateway pod kątem `AcpRuntimeError`. Dla pełnych uprawnień ustaw `permissionMode=approve-all`; dla łagodnej degradacji ustaw `nonInteractivePermissions=deny`. | -| Sesja ACP zawiesza się bez końca po zakończeniu pracy | Proces harness zakończył się, ale sesja ACP nie zgłosiła zakończenia. | Monitoruj przez `ps aux \| grep acpx`; ręcznie zabij nieaktualne procesy. | +| Objaw | Prawdopodobna przyczyna | Poprawka | +| --- | --- | --- | +| `ACP runtime backend is not configured` | Brak pluginu backendu albo jest wyłączony. | Zainstaluj i włącz plugin backendu, a następnie uruchom `/acp doctor`. | +| `ACP is disabled by policy (acp.enabled=false)` | ACP jest globalnie wyłączone. | Ustaw `acp.enabled=true`. | +| `ACP dispatch is disabled by policy (acp.dispatch.enabled=false)` | Dispatch z normalnych wiadomości w wątku jest wyłączony. | Ustaw `acp.dispatch.enabled=true`. | +| `ACP agent "" is not allowed by policy` | Agent nie znajduje się na liście dozwolonych. | Użyj dozwolonego `agentId` albo zaktualizuj `acp.allowedAgents`. | +| `Unable to resolve session target: ...` | Nieprawidłowy token klucza/id/etykiety. | Uruchom `/acp sessions`, skopiuj dokładny klucz/etykietę i spróbuj ponownie. | +| `--bind here requires running /acp spawn inside an active ... conversation` | `--bind here` zostało użyte bez aktywnej rozmowy, którą można powiązać. | Przejdź do docelowego czatu/kanału i spróbuj ponownie albo użyj uruchomienia bez powiązania. | +| `Conversation bindings are unavailable for .` | Adapter nie ma możliwości powiązania ACP z bieżącą rozmową. | Użyj `/acp spawn ... --thread ...`, jeśli jest obsługiwane, skonfiguruj wpisy najwyższego poziomu `bindings[]` albo przejdź do obsługiwanego kanału. | +| `--thread here requires running /acp spawn inside an active ... thread` | `--thread here` zostało użyte poza kontekstem wątku. | Przejdź do docelowego wątku albo użyj `--thread auto`/`off`. | +| `Only can rebind this channel/conversation/thread.` | Inny użytkownik jest właścicielem aktywnego celu powiązania. | Powiąż ponownie jako właściciel albo użyj innej rozmowy lub wątku. | +| `Thread bindings are unavailable for .` | Adapter nie ma możliwości powiązania wątków. | Użyj `--thread off` albo przejdź do obsługiwanego adaptera/kanału. | +| `Sandboxed sessions cannot spawn ACP sessions ...` | Runtime ACP działa po stronie hosta; sesja żądająca jest sandboxowana. | Użyj `runtime="subagent"` z sesji sandboxowanych albo uruchamiaj ACP z sesji niesandboxowanej. | +| `sessions_spawn sandbox="require" is unsupported for runtime="acp" ...` | Zażądano `sandbox="require"` dla runtime ACP. | Użyj `runtime="subagent"` dla wymaganego sandboxowania albo użyj ACP z `sandbox="inherit"` z niesandboxowanej sesji. | +| Brak metadanych ACP dla powiązanej sesji | Nieaktualne/usunięte metadane sesji ACP. | Odtwórz je przez `/acp spawn`, a następnie ponownie powiąż/ustaw fokus wątku. | +| `AcpRuntimeError: Permission prompt unavailable in non-interactive mode` | `permissionMode` blokuje zapis/exec w nieinteraktywnej sesji ACP. | Ustaw `plugins.entries.acpx.config.permissionMode` na `approve-all` i uruchom ponownie gateway. Zobacz [Konfiguracja uprawnień](#konfiguracja-uprawnień). | +| Sesja ACP kończy się niepowodzeniem wcześnie i daje mało danych wyjściowych | Prompty uprawnień są blokowane przez `permissionMode`/`nonInteractivePermissions`. | Sprawdź logi gateway pod kątem `AcpRuntimeError`. Dla pełnych uprawnień ustaw `permissionMode=approve-all`; dla łagodnej degradacji ustaw `nonInteractivePermissions=deny`. | +| Sesja ACP zawiesza się bez końca po ukończeniu pracy | Proces harness zakończył się, ale sesja ACP nie zgłosiła ukończenia. | Monitoruj przez `ps aux \| grep acpx`; ręcznie zabij nieaktualne procesy. | diff --git a/docs/pl/tools/exec-approvals.md b/docs/pl/tools/exec-approvals.md index 10bc6e3e2..6363e0c2b 100644 --- a/docs/pl/tools/exec-approvals.md +++ b/docs/pl/tools/exec-approvals.md @@ -1,70 +1,70 @@ --- read_when: - - Konfigurowanie zatwierdzeń exec lub allowlist + - Konfigurowanie zatwierdzeń exec lub list dozwolonych - Implementowanie UX zatwierdzeń exec w aplikacji macOS - - Przegląd promptów wyjścia z sandboxa i ich konsekwencji -summary: Zatwierdzenia exec, allowlisty i prompty wyjścia z sandboxa + - Przeglądanie promptów wyjścia z sandboxa i ich konsekwencji +summary: Zatwierdzenia exec, listy dozwolonych i prompty wyjścia z sandboxa title: Zatwierdzenia exec x-i18n: - generated_at: "2026-04-06T03:14:33Z" + generated_at: "2026-04-08T02:19:40Z" model: gpt-5.4 provider: openai - source_hash: 39e91cd5c7615bdb9a6b201a85bde7514327910f6f12da5a4b0532bceb229c22 + source_hash: 6041929185bab051ad873cc4822288cb7d6f0470e19e7ae7a16b70f76dfc2cd9 source_path: tools/exec-approvals.md workflow: 15 --- # Zatwierdzenia exec -Zatwierdzenia exec to **zabezpieczenie aplikacji towarzyszącej / hosta node** umożliwiające uruchamianie przez sandboxowanego agenta -poleceń na prawdziwym hoście (`gateway` lub `node`). Potraktuj to jak blokadę bezpieczeństwa: -polecenia są dozwolone tylko wtedy, gdy zasada + allowlista + (opcjonalnie) zatwierdzenie użytkownika są zgodne. -Zatwierdzenia exec działają **dodatkowo** względem polityki narzędzi i bramkowania elevated (chyba że elevated ma wartość `full`, co pomija zatwierdzenia). -Skuteczna polityka jest **bardziej restrykcyjną** z `tools.exec.*` i domyślnych ustawień zatwierdzeń; jeśli pole zatwierdzeń zostanie pominięte, używana jest wartość z `tools.exec`. -Host exec używa też lokalnego stanu zatwierdzeń na tej maszynie. Lokalna dla hosta -wartość `ask: "always"` w `~/.openclaw/exec-approvals.json` będzie nadal wymuszać prompty, nawet jeśli +Zatwierdzenia exec to **zabezpieczenie aplikacji towarzyszącej / hosta węzła** pozwalające agentowi działającemu w sandboxie uruchamiać +polecenia na rzeczywistym hoście (`gateway` lub `node`). Potraktuj to jak blokadę bezpieczeństwa: +polecenia są dozwolone tylko wtedy, gdy polityka + lista dozwolonych + (opcjonalne) zatwierdzenie użytkownika są zgodne. +Zatwierdzenia exec są **dodatkiem** do polityki narzędzi i kontroli elevated (chyba że elevated jest ustawione na `full`, co pomija zatwierdzenia). +Efektywna polityka jest **bardziej rygorystyczną** z `tools.exec.*` i domyślnych ustawień zatwierdzeń; jeśli pole zatwierdzeń zostanie pominięte, używana jest wartość `tools.exec`. +Exec hosta używa również lokalnego stanu zatwierdzeń na tej maszynie. Lokalne dla hosta +`ask: "always"` w `~/.openclaw/exec-approvals.json` nadal wyświetla prompty, nawet jeśli domyślne ustawienia sesji lub konfiguracji żądają `ask: "on-miss"`. Użyj `openclaw approvals get`, `openclaw approvals get --gateway` lub `openclaw approvals get --node `, aby sprawdzić żądaną politykę, -źródła polityki hosta i wynik skuteczny. +źródła polityki hosta i wynik efektywny. -Jeśli UI aplikacji towarzyszącej **nie jest dostępny**, każde żądanie wymagające promptu -jest rozwiązywane przez **ask fallback** (domyślnie: deny). +Jeśli interfejs aplikacji towarzyszącej **nie jest dostępny**, każde żądanie wymagające promptu jest +rozstrzygane przez **ask fallback** (domyślnie: deny). -Natywni klienci zatwierdzeń na czacie mogą też udostępniać elementy interfejsu specyficzne dla kanału na -wiadomości z oczekującym zatwierdzeniem. Na przykład Matrix może dodać skróty reakcji do -promptu zatwierdzenia (`✅` pozwól raz, `❌` odmów i `♾️` zawsze pozwalaj, gdy dostępne), -jednocześnie pozostawiając w wiadomości polecenia `/approve ...` jako fallback. +Natywni klienci zatwierdzeń w czacie mogą również udostępniać specyficzne dla kanału elementy interakcji w +wiadomości oczekującego zatwierdzenia. Na przykład Matrix może dodawać skróty reakcji do +promptu zatwierdzenia (`✅` pozwól raz, `❌` odrzuć i `♾️` pozwól zawsze, gdy dostępne), +jednocześnie pozostawiając polecenia `/approve ...` w wiadomości jako rozwiązanie zapasowe. -## Gdzie ma to zastosowanie +## Gdzie to ma zastosowanie -Zatwierdzenia exec są egzekwowane lokalnie na hoście wykonawczym: +Zatwierdzenia exec są egzekwowane lokalnie na hoście wykonania: -- **host gatewaya** → proces `openclaw` na maszynie gatewaya -- **host node** → runner node (aplikacja towarzysząca macOS lub bezgłowy host node) +- **host gateway** → proces `openclaw` na maszynie gateway +- **host node** → runner węzła (aplikacja towarzysząca macOS lub bezgłowy host węzła) -Uwaga o modelu zaufania: +Uwaga dotycząca modelu zaufania: -- Wywołujący uwierzytelnieni przez Gateway są zaufanymi operatorami tego Gatewaya. -- Sparowane nody rozszerzają tę zdolność zaufanego operatora na host node. -- Zatwierdzenia exec zmniejszają ryzyko przypadkowego wykonania, ale nie stanowią granicy auth per użytkownik. +- Wywołujący uwierzytelnieni przez Gateway są zaufanymi operatorami dla tego Gateway. +- Sparowane węzły rozszerzają tę zdolność zaufanego operatora na host node. +- Zatwierdzenia exec zmniejszają ryzyko przypadkowego wykonania, ale nie są granicą uwierzytelniania per użytkownik. - Zatwierdzone uruchomienia na hoście node wiążą kanoniczny kontekst wykonania: kanoniczne cwd, dokładne argv, powiązanie env - gdy występuje oraz przypiętą ścieżkę wykonywalną, gdy ma to zastosowanie. -- Dla skryptów powłoki i bezpośrednich wywołań plików interpreterów/runtime OpenClaw próbuje również powiązać - jeden konkretny lokalny operand plikowy. Jeśli ten powiązany plik zmieni się po zatwierdzeniu, ale przed wykonaniem, - uruchomienie zostanie odrzucone zamiast wykonywać zmienioną treść. -- To powiązanie pliku jest celowo wykonywane w trybie best-effort, a nie jako kompletny model semantyczny dla każdej - ścieżki ładowania interpretera/runtime. Jeśli tryb zatwierdzania nie może zidentyfikować dokładnie jednego konkretnego lokalnego + gdy występuje oraz przypiętą ścieżkę do pliku wykonywalnego, gdy ma to zastosowanie. +- Dla skryptów powłoki i bezpośrednich wywołań plików interpreterów/runtime OpenClaw również próbuje powiązać + jeden konkretny lokalny operand pliku. Jeśli ten powiązany plik zmieni się po zatwierdzeniu, ale przed wykonaniem, + uruchomienie zostanie odrzucone zamiast wykonać zmienioną treść. +- To powiązanie pliku jest celowo realizowane według zasady best-effort, a nie jako pełny model semantyczny każdego + interpretera/runtime i ścieżki ładowania. Jeśli tryb zatwierdzania nie potrafi zidentyfikować dokładnie jednego konkretnego lokalnego pliku do powiązania, odmawia wygenerowania uruchomienia opartego na zatwierdzeniu zamiast udawać pełne pokrycie. Podział na macOS: - **usługa hosta node** przekazuje `system.run` do **aplikacji macOS** przez lokalne IPC. -- **aplikacja macOS** egzekwuje zatwierdzenia + wykonuje polecenie w kontekście UI. +- **aplikacja macOS** egzekwuje zatwierdzenia i wykonuje polecenie w kontekście UI. ## Ustawienia i przechowywanie -Zatwierdzenia znajdują się w lokalnym pliku JSON na hoście wykonawczym: +Zatwierdzenia są przechowywane w lokalnym pliku JSON na hoście wykonania: `~/.openclaw/exec-approvals.json` @@ -103,14 +103,14 @@ Przykładowy schemat: } ``` -## Tryb bez zatwierdzeń „YOLO” +## Tryb „YOLO” bez zatwierdzeń -Jeśli chcesz, aby host exec działał bez promptów zatwierdzania, musisz otworzyć **obie** warstwy polityki: +Jeśli chcesz, aby exec hosta działał bez promptów zatwierdzania, musisz otworzyć **obie** warstwy polityki: - żądaną politykę exec w konfiguracji OpenClaw (`tools.exec.*`) -- lokalną politykę zatwierdzeń hosta w `~/.openclaw/exec-approvals.json` +- lokalną dla hosta politykę zatwierdzeń w `~/.openclaw/exec-approvals.json` -To jest teraz domyślne zachowanie hosta, chyba że jawnie je zaostrzysz: +Jest to teraz domyślne zachowanie hosta, chyba że jawnie je zaostrzysz: - `tools.exec.security`: `full` na `gateway`/`node` - `tools.exec.ask`: `off` @@ -118,15 +118,15 @@ To jest teraz domyślne zachowanie hosta, chyba że jawnie je zaostrzysz: Ważne rozróżnienie: -- `tools.exec.host=auto` wybiera miejsce wykonania exec: sandbox, jeśli dostępny, w przeciwnym razie gateway. -- YOLO wybiera sposób zatwierdzania host exec: `security=full` plus `ask=off`. -- W trybie YOLO OpenClaw nie dodaje osobnej heurystycznej bramki zatwierdzenia zaciemniania poleceń ponad skonfigurowaną politykę host exec. -- `auto` nie sprawia, że routing do gatewaya staje się darmowym nadpisaniem z sesji sandboxowanej. Żądanie per wywołanie `host=node` jest dozwolone z `auto`, a `host=gateway` jest dozwolone z `auto` tylko wtedy, gdy żaden runtime sandboxa nie jest aktywny. Jeśli chcesz stabilną domyślną wartość inną niż auto, ustaw `tools.exec.host` albo użyj jawnie `/exec host=...`. +- `tools.exec.host=auto` wybiera miejsce uruchomienia exec: sandbox, jeśli dostępny, w przeciwnym razie gateway. +- YOLO wybiera sposób zatwierdzania exec hosta: `security=full` plus `ask=off`. +- W trybie YOLO OpenClaw nie dodaje osobnej heurystycznej bramki zatwierdzeń dla maskowania poleceń ponad skonfigurowaną politykę exec hosta. +- `auto` nie sprawia, że routing do gateway staje się darmowym obejściem z sesji działającej w sandboxie. Żądanie per wywołanie `host=node` jest dozwolone z `auto`, a `host=gateway` jest dozwolone z `auto` tylko wtedy, gdy nie jest aktywne środowisko sandbox. Jeśli chcesz stabilnej domyślnej wartości innej niż auto, ustaw `tools.exec.host` lub użyj jawnie `/exec host=...`. -Jeśli chcesz bardziej zachowawczej konfiguracji, zaostrz z powrotem którąkolwiek warstwę do `allowlist` / `on-miss` -albo `deny`. +Jeśli chcesz bardziej konserwatywnej konfiguracji, zaostrz z powrotem dowolną warstwę do `allowlist` / `on-miss` +lub `deny`. -Trwała konfiguracja „nigdy nie pytaj” dla hosta gatewaya: +Trwała konfiguracja hosta gateway „nigdy nie pytaj”: ```bash openclaw config set tools.exec.host gateway @@ -150,7 +150,7 @@ openclaw approvals set --stdin <<'EOF' EOF ``` -Dla hosta node zastosuj zamiast tego ten sam plik zatwierdzeń na tym nodzie: +Dla hosta node zastosuj zamiast tego ten sam plik zatwierdzeń na tym węźle: ```bash openclaw approvals set --node --stdin <<'EOF' @@ -168,36 +168,36 @@ EOF Skrót tylko dla sesji: - `/exec security=full ask=off` zmienia tylko bieżącą sesję. -- `/elevated full` to skrót break-glass, który również pomija zatwierdzenia exec dla tej sesji. +- `/elevated full` to skrót awaryjny, który również pomija zatwierdzenia exec dla tej sesji. -Jeśli plik zatwierdzeń hosta pozostaje bardziej restrykcyjny niż konfiguracja, nadal wygrywa bardziej restrykcyjna polityka hosta. +Jeśli plik zatwierdzeń hosta pozostaje bardziej rygorystyczny niż konfiguracja, nadal wygrywa bardziej rygorystyczna polityka hosta. -## Pokrętła polityki +## Przełączniki polityki ### Security (`exec.security`) -- **deny**: blokuje wszystkie żądania host exec. -- **allowlist**: pozwala tylko na polecenia z allowlisty. -- **full**: pozwala na wszystko (równoważne elevated). +- **deny**: zablokuj wszystkie żądania exec hosta. +- **allowlist**: zezwalaj tylko na polecenia z listy dozwolonych. +- **full**: zezwalaj na wszystko (odpowiednik elevated). ### Ask (`exec.ask`) -- **off**: nigdy nie pytaj. -- **on-miss**: pytaj tylko wtedy, gdy allowlista nie pasuje. -- **always**: pytaj przy każdym poleceniu. -- trwałe zaufanie `allow-always` nie tłumi promptów, gdy skuteczny tryb ask to `always` +- **off**: nigdy nie wyświetlaj promptu. +- **on-miss**: wyświetl prompt tylko wtedy, gdy lista dozwolonych nie pasuje. +- **always**: wyświetlaj prompt dla każdego polecenia. +- trwałe zaufanie `allow-always` nie tłumi promptów, gdy efektywny tryb ask to `always` ### Ask fallback (`askFallback`) -Jeśli prompt jest wymagany, ale żadne UI nie jest osiągalne, fallback decyduje: +Jeśli prompt jest wymagany, ale żaden UI nie jest osiągalny, fallback decyduje: - **deny**: blokuj. -- **allowlist**: pozwól tylko, jeśli allowlista pasuje. -- **full**: pozwól. +- **allowlist**: zezwalaj tylko wtedy, gdy lista dozwolonych pasuje. +- **full**: zezwalaj. -### Wzmacnianie inline interpreter eval (`tools.exec.strictInlineEval`) +### Wzmocnienie eval inline dla interpreterów (`tools.exec.strictInlineEval`) -Gdy `tools.exec.strictInlineEval=true`, OpenClaw traktuje formy inline code-eval jako wymagające zatwierdzenia, nawet jeśli sama binarka interpretera jest na allowliście. +Gdy `tools.exec.strictInlineEval=true`, OpenClaw traktuje formy eval kodu inline jako wymagające zatwierdzenia, nawet jeśli sam plik wykonywalny interpretera znajduje się na liście dozwolonych. Przykłady: @@ -209,18 +209,18 @@ Przykłady: - `lua -e` - `osascript -e` -To defense-in-depth dla loaderów interpreterów, które nie mapują się czysto do jednego stabilnego operandu plikowego. W trybie ścisłym: +To obrona warstwowa dla loaderów interpreterów, które nie mapują się czysto do jednego stabilnego operandu pliku. W trybie ścisłym: - te polecenia nadal wymagają jawnego zatwierdzenia; -- `allow-always` nie zapisuje dla nich automatycznie nowych wpisów allowlisty. +- `allow-always` nie zapisuje automatycznie dla nich nowych wpisów listy dozwolonych. -## Allowlista (per agent) +## Allowlist (per agent) -Allowlisty są **per agent**. Jeśli istnieje wielu agentów, przełącz agenta, którego -edytujesz, w aplikacji macOS. Wzorce to **dopasowania glob bez rozróżniania wielkości liter**. -Wzorce powinny rozwiązywać się do **ścieżek binarek** (wpisy tylko z basename są ignorowane). -Starsze wpisy `agents.default` są migrowane do `agents.main` przy ładowaniu. -Łańcuchy powłoki takie jak `echo ok && pwd` nadal wymagają, aby każdy segment najwyższego poziomu spełniał reguły allowlisty. +Listy dozwolonych są **per agent**. Jeśli istnieje wielu agentów, przełącz, którego agenta +edytujesz w aplikacji macOS. Wzorce są **niezależnymi od wielkości liter dopasowaniami glob**. +Wzorce powinny rozwiązywać się do **ścieżek plików wykonywalnych** (wpisy zawierające tylko basename są ignorowane). +Starsze wpisy `agents.default` są migrowane do `agents.main` podczas ładowania. +Łańcuchy powłoki, takie jak `echo ok && pwd`, nadal wymagają, aby każdy segment najwyższego poziomu spełniał reguły listy dozwolonych. Przykłady: @@ -228,43 +228,43 @@ Przykłady: - `~/.local/bin/*` - `/opt/homebrew/bin/rg` -Każdy wpis allowlisty śledzi: +Każdy wpis listy dozwolonych śledzi: -- **id** stabilny UUID używany do tożsamości w UI (opcjonalny) +- **id** stabilny UUID używany jako tożsamość w UI (opcjonalnie) - **last used** znacznik czasu - **last used command** - **last resolved path** -## Auto-allow Skills CLI +## Auto-allow skill CLIs -Gdy włączone jest **Auto-allow Skills CLI**, pliki wykonywalne wskazane przez znane Skills -są traktowane jako znajdujące się na allowliście na nodach (macOS node lub bezgłowy host node). Wykorzystuje to -`skills.bins` przez Gateway RPC do pobrania listy binarek skilli. Wyłącz to, jeśli chcesz ścisłych ręcznych allowlist. +Gdy **Auto-allow skill CLIs** jest włączone, pliki wykonywalne wskazywane przez znane Skills +są traktowane jako wpisy listy dozwolonych na węzłach (węzeł macOS lub bezgłowy host węzła). Używa to +`skills.bins` przez Gateway RPC do pobrania listy plików binarnych skill. Wyłącz to, jeśli chcesz rygorystycznych ręcznych list dozwolonych. Ważne uwagi dotyczące zaufania: -- To **niejawna wygodna allowlista**, oddzielona od ręcznych wpisów allowlisty ścieżek. +- To **niejawna wygodna lista dozwolonych**, oddzielna od ręcznych wpisów listy dozwolonych opartych na ścieżkach. - Jest przeznaczona dla zaufanych środowisk operatora, w których Gateway i node znajdują się w tej samej granicy zaufania. -- Jeśli wymagasz ścisłego jawnego zaufania, pozostaw `autoAllowSkills: false` i używaj wyłącznie ręcznych wpisów allowlisty ścieżek. +- Jeśli potrzebujesz rygorystycznego jawnego zaufania, pozostaw `autoAllowSkills: false` i używaj tylko ręcznych wpisów listy dozwolonych opartych na ścieżkach. ## Safe bins (tylko stdin) -`tools.exec.safeBins` definiuje małą listę binarek **tylko stdin** (na przykład `cut`), -które mogą działać w trybie allowlisty **bez** jawnych wpisów allowlisty. Safe bins odrzucają -pozycyjne argumenty plikowe i tokeny podobne do ścieżek, więc mogą działać tylko na strumieniu wejściowym. -Traktuj to jako wąską szybką ścieżkę dla filtrów strumieniowych, a nie ogólną listę zaufania. -**Nie** dodawaj binarek interpreterów ani runtime (na przykład `python3`, `node`, `ruby`, `bash`, `sh`, `zsh`) do `safeBins`. -Jeśli polecenie może z założenia wykonywać kod, uruchamiać podpolecenia lub odczytywać pliki, preferuj jawne wpisy allowlisty i pozostaw włączone prompty zatwierdzeń. +`tools.exec.safeBins` definiuje małą listę plików binarnych **tylko stdin** (na przykład `cut`), +które mogą działać w trybie allowlist **bez** jawnych wpisów listy dozwolonych. Safe bins odrzucają +pozycyjne argumenty plików i tokeny podobne do ścieżek, więc mogą działać tylko na przychodzącym strumieniu. +Traktuj to jako wąską szybką ścieżkę dla filtrów strumieni, a nie ogólną listę zaufania. +**Nie** dodawaj interpreterów ani plików binarnych runtime (na przykład `python3`, `node`, `ruby`, `bash`, `sh`, `zsh`) do `safeBins`. +Jeśli polecenie potrafi wykonywać eval kodu, uruchamiać podpolecenia lub z założenia czytać pliki, preferuj jawne wpisy listy dozwolonych i pozostaw włączone prompty zatwierdzeń. Niestandardowe safe bins muszą definiować jawny profil w `tools.exec.safeBinProfiles.`. Walidacja jest deterministyczna wyłącznie na podstawie kształtu argv (bez sprawdzania istnienia systemu plików hosta), co -zapobiega zachowaniu typu oracle istnienia pliku wynikającemu z różnic allow/deny. +zapobiega zachowaniu typu oracle istnienia plików wynikającemu z różnic allow/deny. Opcje zorientowane na pliki są odrzucane dla domyślnych safe bins (na przykład `sort -o`, `sort --output`, `sort --files0-from`, `sort --compress-program`, `sort --random-source`, `sort --temporary-directory`/`-T`, `wc --files0-from`, `jq -f/--from-file`, `grep -f/--file`). -Safe bins wymuszają również jawne zasady flag per binarka dla opcji, które łamią zachowanie tylko stdin -(na przykład `sort -o/--output/--compress-program` i flagi rekurencyjne grep). -Długie opcje są walidowane w trybie fail-closed w safe-bin mode: nieznane flagi i niejednoznaczne +Safe bins egzekwują również jawne polityki flag per plik binarny dla opcji, które łamią zachowanie wyłącznie stdin +(na przykład `sort -o/--output/--compress-program` i rekursywne flagi grep). +Długie opcje są walidowane w trybie fail-closed w trybie safe-bin: nieznane flagi i niejednoznaczne skróty są odrzucane. Odrzucane flagi według profilu safe-bin: @@ -277,31 +277,31 @@ Odrzucane flagi według profilu safe-bin: [//]: # "SAFE_BIN_DENIED_FLAGS:END" -Safe bins wymuszają również traktowanie tokenów argv jako **dosłowny tekst** w czasie wykonania (bez globbing -i bez rozwijania `$VARS`) dla segmentów tylko stdin, więc wzorce takie jak `*` lub `$HOME/...` nie mogą być -użyte do przemycania odczytów plików. -Safe bins muszą także rozwiązywać się z zaufanych katalogów binarek (domyślne katalogi systemowe plus opcjonalne +Safe bins wymuszają również traktowanie tokenów argv jako **dosłownego tekstu** podczas wykonywania (bez globbingu +i bez rozwijania `$VARS`) dla segmentów tylko stdin, więc wzorce takie jak `*` lub `$HOME/...` nie mogą zostać +użyte do przemycenia odczytu plików. +Safe bins muszą również rozwiązywać się z zaufanych katalogów plików binarnych (domyślne katalogi systemowe plus opcjonalne `tools.exec.safeBinTrustedDirs`). Wpisy `PATH` nigdy nie są automatycznie zaufane. Domyślne zaufane katalogi safe-bin są celowo minimalne: `/bin`, `/usr/bin`. Jeśli Twój plik wykonywalny safe-bin znajduje się w ścieżkach menedżera pakietów/użytkownika (na przykład `/opt/homebrew/bin`, `/usr/local/bin`, `/opt/local/bin`, `/snap/bin`), dodaj je jawnie do `tools.exec.safeBinTrustedDirs`. -Łańcuchy powłoki i przekierowania nie są automatycznie dozwolone w trybie allowlisty. +Łączenie poleceń powłoki i przekierowania nie są automatycznie dozwolone w trybie allowlist. -Łańcuchy powłoki (`&&`, `||`, `;`) są dozwolone, gdy każdy segment najwyższego poziomu spełnia allowlistę -(w tym safe bins lub skill auto-allow). Przekierowania nadal nie są obsługiwane w trybie allowlisty. -Podstawianie poleceń (`$()` / backticks) jest odrzucane podczas parsowania allowlisty, także wewnątrz -podwójnych cudzysłowów; użyj pojedynczych cudzysłowów, jeśli potrzebujesz dosłownego tekstu `$()`. -W zatwierdzeniach aplikacji towarzyszącej macOS surowy tekst powłoki zawierający składnię kontroli lub rozwijania powłoki -(`&&`, `||`, `;`, `|`, `` ` ``, `$`, `<`, `>`, `(`, `)`) jest traktowany jako nietrafienie allowlisty, chyba że -sama binarka powłoki znajduje się na allowliście. -Dla wrapperów powłoki (`bash|sh|zsh ... -c/-lc`) nadpisania env o zakresie żądania są redukowane do małej jawnej -allowlisty (`TERM`, `LANG`, `LC_*`, `COLORTERM`, `NO_COLOR`, `FORCE_COLOR`). -Dla decyzji allow-always w trybie allowlisty znane wrappery dispatch -(`env`, `nice`, `nohup`, `stdbuf`, `timeout`) zapisują wewnętrzne ścieżki wykonywalne zamiast ścieżek wrapperów. Multipleksery powłoki (`busybox`, `toybox`) są również rozpakowywane dla apletów powłoki (`sh`, `ash`, -itd.), tak aby zapisywane były wewnętrzne pliki wykonywalne zamiast binarek multipleksera. Jeśli wrapper lub -multiplekser nie może zostać bezpiecznie rozpakowany, żaden wpis allowlisty nie jest zapisywany automatycznie. -Jeśli umieszczasz na allowliście interpretery takie jak `python3` lub `node`, preferuj `tools.exec.strictInlineEval=true`, aby inline eval nadal wymagał jawnego zatwierdzenia. W trybie ścisłym `allow-always` nadal może zapisywać nieszkodliwe wywołania interpreterów/skryptów, ale nośniki inline-eval nie są zapisywane automatycznie. +Łączenie poleceń powłoki (`&&`, `||`, `;`) jest dozwolone, gdy każdy segment najwyższego poziomu spełnia zasady listy dozwolonych +(w tym safe bins lub auto-allow skill). Przekierowania nadal nie są obsługiwane w trybie allowlist. +Podstawianie poleceń (`$()` / backticks) jest odrzucane podczas parsowania allowlist, również wewnątrz +cudzysłowów; użyj pojedynczych cudzysłowów, jeśli potrzebujesz dosłownego tekstu `$()`. +W zatwierdzeniach aplikacji towarzyszącej macOS surowy tekst powłoki zawierający składnię sterowania lub rozwijania powłoki +(`&&`, `||`, `;`, `|`, `` ` ``, `$`, `<`, `>`, `(`, `)`) jest traktowany jako brak dopasowania listy dozwolonych, chyba że +sam plik binarny powłoki znajduje się na liście dozwolonych. +Dla wrapperów powłoki (`bash|sh|zsh ... -c/-lc`) nadpisania env ograniczone do zakresu żądania są redukowane do +małej jawnej listy dozwolonych (`TERM`, `LANG`, `LC_*`, `COLORTERM`, `NO_COLOR`, `FORCE_COLOR`). +Dla decyzji allow-always w trybie allowlist znane wrappery dispatch +(`env`, `nice`, `nohup`, `stdbuf`, `timeout`) utrwalają ścieżki wewnętrznych plików wykonywalnych zamiast ścieżek wrapperów. Multipleksery powłoki (`busybox`, `toybox`) są również odpakowywane dla apletów powłoki (`sh`, `ash`, +itd.), tak aby utrwalane były ścieżki wewnętrznych plików wykonywalnych zamiast plików binarnych multipleksera. Jeśli wrapper lub +multiplekser nie może zostać bezpiecznie odpakowany, żaden wpis listy dozwolonych nie jest utrwalany automatycznie. +Jeśli dodajesz do listy dozwolonych interpretery takie jak `python3` lub `node`, preferuj `tools.exec.strictInlineEval=true`, aby eval inline nadal wymagał jawnego zatwierdzenia. W trybie ścisłym `allow-always` może nadal utrwalać niegroźne wywołania interpreterów/skryptów, ale nośniki eval inline nie są utrwalane automatycznie. Domyślne safe bins: @@ -311,49 +311,49 @@ Domyślne safe bins: [//]: # "SAFE_BIN_DEFAULTS:END" -`grep` i `sort` nie znajdują się na liście domyślnej. Jeśli jawnie je włączysz, zachowaj jawne wpisy allowlisty dla +`grep` i `sort` nie znajdują się na liście domyślnej. Jeśli jawnie je włączysz, zachowaj jawne wpisy listy dozwolonych dla ich przepływów pracy innych niż stdin. -Dla `grep` w safe-bin mode podawaj wzorzec przez `-e`/`--regexp`; forma wzorca pozycyjnego jest -odrzucana, aby nie dało się przemycić operandów plikowych jako niejednoznacznych pozycji. +Dla `grep` w trybie safe-bin podawaj wzorzec za pomocą `-e`/`--regexp`; forma wzorca pozycyjnego jest +odrzucana, aby operandy plików nie mogły zostać przemycone jako niejednoznaczne argumenty pozycyjne. -### Safe bins a allowlista +### Safe bins versus allowlist -| Topic | `tools.exec.safeBins` | Allowlist (`exec-approvals.json`) | +| Temat | `tools.exec.safeBins` | Allowlist (`exec-approvals.json`) | | ---------------- | ------------------------------------------------------ | ------------------------------------------------------------ | -| Goal | Automatyczne zezwalanie na wąskie filtry stdin | Jawne zaufanie do określonych plików wykonywalnych | -| Match type | Nazwa pliku wykonywalnego + zasada argv safe-bin | Wzorzec glob rozwiązanej ścieżki pliku wykonywalnego | -| Argument scope | Ograniczany przez profil safe-bin i zasady tokenów dosłownych | Tylko dopasowanie ścieżki; argumenty są poza tym Twoją odpowiedzialnością | -| Typical examples | `head`, `tail`, `tr`, `wc` | `jq`, `python3`, `node`, `ffmpeg`, niestandardowe CLI | -| Best use | Niskiego ryzyka przekształcenia tekstu w pipeline | Dowolne narzędzie o szerszym zachowaniu lub efektach ubocznych | +| Cel | Automatyczne zezwalanie na wąskie filtry stdin | Jawne zaufanie określonym plikom wykonywalnym | +| Typ dopasowania | Nazwa pliku wykonywalnego + polityka argv safe-bin | Wzorzec glob rozwiązanego do ścieżki pliku wykonywalnego | +| Zakres argumentów| Ograniczony profilem safe-bin i regułami tokenów dosłownych | Tylko dopasowanie ścieżki; odpowiedzialność za argumenty spoczywa poza tym na Tobie | +| Typowe przykłady | `head`, `tail`, `tr`, `wc` | `jq`, `python3`, `node`, `ffmpeg`, niestandardowe CLI | +| Najlepsze użycie | Niskiego ryzyka transformacje tekstu w pipeline’ach | Każde narzędzie o szerszym zachowaniu lub skutkach ubocznych | Lokalizacja konfiguracji: - `safeBins` pochodzi z konfiguracji (`tools.exec.safeBins` lub per agent `agents.list[].tools.exec.safeBins`). - `safeBinTrustedDirs` pochodzi z konfiguracji (`tools.exec.safeBinTrustedDirs` lub per agent `agents.list[].tools.exec.safeBinTrustedDirs`). - `safeBinProfiles` pochodzi z konfiguracji (`tools.exec.safeBinProfiles` lub per agent `agents.list[].tools.exec.safeBinProfiles`). Klucze profili per agent nadpisują klucze globalne. -- wpisy allowlisty znajdują się w lokalnym dla hosta `~/.openclaw/exec-approvals.json` pod `agents..allowlist` (lub przez Control UI / `openclaw approvals allowlist ...`). -- `openclaw security audit` ostrzega przez `tools.exec.safe_bins_interpreter_unprofiled`, gdy binarki interpreterów/runtime pojawiają się w `safeBins` bez jawnych profili. -- `openclaw doctor --fix` może utworzyć szkielety brakujących wpisów `safeBinProfiles.` jako `{}` (po tym przejrzyj i zaostrz). Binarki interpreterów/runtime nie są tworzone automatycznie. +- wpisy listy dozwolonych znajdują się w lokalnym dla hosta `~/.openclaw/exec-approvals.json` pod `agents..allowlist` (lub przez Control UI / `openclaw approvals allowlist ...`). +- `openclaw security audit` ostrzega `tools.exec.safe_bins_interpreter_unprofiled`, gdy interpretery/pliki runtime pojawiają się w `safeBins` bez jawnych profili. +- `openclaw doctor --fix` może wygenerować brakujące wpisy niestandardowych `safeBinProfiles.` jako `{}` (następnie je przejrzyj i zaostrz). Pliki binarne interpreterów/runtime nie są generowane automatycznie. Przykład niestandardowego profilu: __OC_I18N_900004__ -Jeśli jawnie dodasz `jq` do `safeBins`, OpenClaw nadal odrzuci builtin `env` w safe-bin -mode, aby `jq -n env` nie mogło zrzucić środowiska procesu hosta bez jawnej ścieżki allowlisty +Jeśli jawnie dodasz `jq` do `safeBins`, OpenClaw nadal odrzuca builtin `env` w trybie safe-bin, +więc `jq -n env` nie może zrzucić środowiska procesu hosta bez jawnej ścieżki z listy dozwolonych lub promptu zatwierdzenia. ## Edycja w Control UI Użyj karty **Control UI → Nodes → Exec approvals**, aby edytować wartości domyślne, nadpisania -per agent i allowlisty. Wybierz zakres (Defaults lub agent), dostosuj politykę, -dodaj/usuń wzorce allowlisty, a następnie kliknij **Save**. UI pokazuje metadane **last used** +per agent i listy dozwolonych. Wybierz zakres (Defaults lub agent), dostosuj politykę, +dodaj/usuń wzorce listy dozwolonych, a następnie kliknij **Save**. UI pokazuje metadane **last used** dla każdego wzorca, aby ułatwić utrzymanie porządku na liście. -Selektor celu wybiera **Gateway** (lokalne zatwierdzenia) albo **Node**. Nody -muszą ogłaszać `system.execApprovals.get/set` (aplikacja macOS lub bezgłowy host node). -Jeśli node nie ogłasza jeszcze zatwierdzeń exec, edytuj jego lokalny -`~/.openclaw/exec-approvals.json` bezpośrednio. +Selektor celu wybiera **Gateway** (lokalne zatwierdzenia) lub **Node**. Węzły +muszą ogłaszać `system.execApprovals.get/set` (aplikacja macOS lub bezgłowy host węzła). +Jeśli węzeł nie ogłasza jeszcze zatwierdzeń exec, edytuj bezpośrednio jego lokalny +`~/.openclaw/exec-approvals.json`. -CLI: `openclaw approvals` obsługuje edycję gatewaya lub node (zobacz [CLI zatwierdzeń](/cli/approvals)). +CLI: `openclaw approvals` obsługuje edycję gateway lub node (zobacz [CLI zatwierdzeń](/cli/approvals)). ## Przepływ zatwierdzania @@ -361,14 +361,14 @@ Gdy prompt jest wymagany, gateway rozgłasza `exec.approval.requested` do klient Control UI i aplikacja macOS rozwiązują to przez `exec.approval.resolve`, a następnie gateway przekazuje zatwierdzone żądanie do hosta node. -Dla `host=node` żądania zatwierdzenia zawierają kanoniczny payload `systemRunPlan`. Gateway używa -tego planu jako autorytatywnego kontekstu polecenia/cwd/sesji przy przekazywaniu zatwierdzonych żądań `system.run`. +Dla `host=node` żądania zatwierdzeń zawierają kanoniczny payload `systemRunPlan`. Gateway używa +tego planu jako autorytatywnego kontekstu polecenia/cwd/sesji podczas przekazywania zatwierdzonych żądań `system.run`. To ma znaczenie przy opóźnieniach asynchronicznego zatwierdzania: -- ścieżka exec node przygotowuje z góry jeden kanoniczny plan +- ścieżka node exec przygotowuje z góry jeden kanoniczny plan - rekord zatwierdzenia przechowuje ten plan i jego metadane powiązania -- po zatwierdzeniu końcowe przekazane wywołanie `system.run` ponownie używa zapisanego planu +- po zatwierdzeniu końcowe przekazane wywołanie `system.run` używa ponownie zapisanego planu zamiast ufać późniejszym zmianom wywołującego - jeśli wywołujący zmieni `command`, `rawCommand`, `cwd`, `agentId` lub `sessionKey` po utworzeniu żądania zatwierdzenia, gateway odrzuci @@ -379,143 +379,144 @@ To ma znaczenie przy opóźnieniach asynchronicznego zatwierdzania: Uruchomienia interpreterów/runtime oparte na zatwierdzeniach są celowo konserwatywne: - Dokładny kontekst argv/cwd/env jest zawsze wiązany. -- Bezpośrednie formy skryptów powłoki i bezpośrednich plików runtime są wiązane w trybie best-effort z jedną konkretną migawką lokalnego +- Formy bezpośrednich skryptów powłoki i bezpośrednich plików runtime są według zasady best-effort wiązane z jednym konkretnym snapshotem lokalnego pliku. - Typowe formy wrapperów menedżerów pakietów, które nadal rozwiązują się do jednego bezpośredniego lokalnego pliku (na przykład - `pnpm exec`, `pnpm node`, `npm exec`, `npx`), są rozpakowywane przed powiązaniem. -- Jeśli OpenClaw nie może zidentyfikować dokładnie jednego konkretnego lokalnego pliku dla polecenia interpretera/runtime + `pnpm exec`, `pnpm node`, `npm exec`, `npx`), są odpakowywane przed powiązaniem. +- Jeśli OpenClaw nie potrafi zidentyfikować dokładnie jednego konkretnego lokalnego pliku dla polecenia interpretera/runtime (na przykład skrypty pakietów, formy eval, łańcuchy loaderów specyficzne dla runtime lub niejednoznaczne formy - wieloplikowe), wykonanie oparte na zatwierdzeniu jest odrzucane zamiast twierdzić, że obejmuje semantykę, której - nie obejmuje. -- Dla takich przepływów pracy preferuj sandboxing, oddzielną granicę hosta albo jawny zaufany + wieloplikowe), wykonanie oparte na zatwierdzeniu jest odrzucane zamiast deklarować pokrycie semantyczne, którego + faktycznie nie ma. +- Dla takich przepływów pracy preferuj sandboxing, oddzielną granicę hosta lub jawny zaufany przepływ allowlist/full, w którym operator akceptuje szerszą semantykę runtime. -Gdy zatwierdzenia są wymagane, narzędzie exec zwraca natychmiast identyfikator zatwierdzenia. Użyj tego identyfikatora, aby -powiązać późniejsze zdarzenia systemowe (`Exec finished` / `Exec denied`). Jeśli żadna decyzja nie nadejdzie przed -upływem limitu czasu, żądanie jest traktowane jako timeout zatwierdzenia i prezentowane jako powód odmowy. +Gdy zatwierdzenia są wymagane, narzędzie exec natychmiast zwraca identyfikator zatwierdzenia. Użyj tego identyfikatora, aby +powiązać późniejsze zdarzenia systemowe (`Exec finished` / `Exec denied`). Jeśli żadna decyzja nie nadejdzie przed upływem +limitu czasu, żądanie jest traktowane jako timeout zatwierdzenia i prezentowane jako powód odmowy. ### Zachowanie dostarczania follow-up -Po zakończeniu zatwierdzonego asynchronicznego exec OpenClaw wysyła follow-up jako turę `agent` do tej samej sesji. +Po zakończeniu zatwierdzonego asynchronicznego exec OpenClaw wysyła turn `agent` follow-up do tej samej sesji. -- Jeśli istnieje prawidłowy zewnętrzny cel dostarczenia (kanał z możliwością dostarczenia plus cel `to`), dostarczenie follow-up używa tego kanału. -- W przepływach wyłącznie webchat lub sesji wewnętrznych bez zewnętrznego celu, dostarczenie follow-up pozostaje tylko w sesji (`deliver: false`). -- Jeśli wywołujący jawnie zażąda ścisłego dostarczenia zewnętrznego bez możliwego do rozwiązania kanału zewnętrznego, żądanie kończy się błędem `INVALID_REQUEST`. -- Jeśli włączono `bestEffortDeliver` i nie można rozwiązać zewnętrznego kanału, dostarczenie jest obniżane do trybu tylko sesji zamiast kończyć się błędem. +- Jeśli istnieje prawidłowy zewnętrzny cel dostarczenia (kanał dostarczalny plus cel `to`), dostarczenie follow-up używa tego kanału. +- W przepływach wyłącznie webchat lub sesji wewnętrznych bez celu zewnętrznego dostarczenie follow-up pozostaje tylko w sesji (`deliver: false`). +- Jeśli wywołujący jawnie żąda rygorystycznego zewnętrznego dostarczenia, ale nie ma możliwego do rozwiązania zewnętrznego kanału, żądanie kończy się błędem `INVALID_REQUEST`. +- Jeśli włączono `bestEffortDeliver` i nie można rozwiązać zewnętrznego kanału, dostarczenie jest degradowane do trybu tylko sesyjnego zamiast zakończyć się błędem. -Okno potwierdzenia zawiera: +Okno dialogowe potwierdzenia zawiera: - polecenie + argumenty - cwd - identyfikator agenta - rozwiązaną ścieżkę pliku wykonywalnego -- host + metadane polityki +- metadane hosta + polityki -Działania: +Akcje: - **Allow once** → uruchom teraz -- **Always allow** → dodaj do allowlisty + uruchom +- **Always allow** → dodaj do listy dozwolonych + uruchom - **Deny** → zablokuj ## Przekazywanie zatwierdzeń do kanałów czatu Możesz przekazywać prompty zatwierdzeń exec do dowolnego kanału czatu (w tym kanałów pluginów) i zatwierdzać -je za pomocą `/approve`. Używa to zwykłego pipeline'u dostarczania wychodzącego. +je za pomocą `/approve`. Używa to zwykłego pipeline dostarczania wychodzącego. Konfiguracja: __OC_I18N_900005__ -Odpowiedź na czacie: +Odpowiedź w czacie: __OC_I18N_900006__ -Polecenie `/approve` obsługuje zarówno zatwierdzenia exec, jak i zatwierdzenia pluginów. Jeśli identyfikator nie pasuje do oczekującego zatwierdzenia exec, automatycznie sprawdza zamiast tego zatwierdzenia pluginów. +Polecenie `/approve` obsługuje zarówno zatwierdzenia exec, jak i zatwierdzenia pluginów. Jeśli identyfikator nie pasuje do oczekującego zatwierdzenia exec, automatycznie sprawdza zatwierdzenia pluginów. ### Przekazywanie zatwierdzeń pluginów -Przekazywanie zatwierdzeń pluginów używa tego samego pipeline'u dostarczania co zatwierdzenia exec, ale ma własną -niezależną konfigurację pod `approvals.plugin`. Włączenie lub wyłączenie jednego nie wpływa na drugie. +Przekazywanie zatwierdzeń pluginów używa tego samego pipeline dostarczania co zatwierdzenia exec, ale ma własną +niezależną konfigurację w `approvals.plugin`. Włączenie lub wyłączenie jednej z nich nie wpływa na drugą. __OC_I18N_900007__ Kształt konfiguracji jest identyczny jak `approvals.exec`: `enabled`, `mode`, `agentFilter`, `sessionFilter` i `targets` działają tak samo. -Kanały obsługujące współdzielone odpowiedzi interaktywne renderują te same przyciski zatwierdzeń zarówno dla zatwierdzeń exec, -jak i pluginów. Kanały bez współdzielonego interaktywnego UI wracają do zwykłego tekstu z instrukcjami `/approve`. +Kanały obsługujące współdzielone odpowiedzi interaktywne renderują te same przyciski zatwierdzeń zarówno dla zatwierdzeń exec, jak i +pluginów. Kanały bez współdzielonego interaktywnego UI przechodzą na zwykły tekst z instrukcjami `/approve`. ### Zatwierdzenia w tym samym czacie na dowolnym kanale Gdy żądanie zatwierdzenia exec lub pluginu pochodzi z dostarczalnej powierzchni czatu, ten sam czat może teraz domyślnie zatwierdzić je przez `/approve`. Dotyczy to kanałów takich jak Slack, Matrix i -Microsoft Teams, oprócz istniejących już przepływów Web UI i UI terminala. +Microsoft Teams, oprócz istniejących już przepływów Web UI i terminal UI. -Ta współdzielona ścieżka poleceń tekstowych używa zwykłego modelu auth kanału dla tej konwersacji. Jeśli -czat źródłowy może już wysyłać polecenia i odbierać odpowiedzi, żądania zatwierdzeń nie wymagają już -osobnego natywnego adaptera dostarczania tylko po to, aby pozostawać oczekującymi. +Ta współdzielona ścieżka polecenia tekstowego używa zwykłego modelu uwierzytelniania kanału dla tej rozmowy. Jeśli +czat źródłowy może już wysyłać polecenia i otrzymywać odpowiedzi, żądania zatwierdzeń nie potrzebują już +oddzielnego natywnego adaptera dostarczania tylko po to, by pozostać oczekujące. -Discord i Telegram również obsługują `/approve` w tym samym czacie, ale te kanały nadal używają -rozwiązanej listy zatwierdzających do autoryzacji, nawet gdy natywne dostarczanie zatwierdzeń jest wyłączone. +Discord i Telegram również obsługują `/approve` w tym samym czacie, ale te kanały nadal używają swoich +rozwiązanych list zatwierdzających do autoryzacji, nawet gdy natywne dostarczanie zatwierdzeń jest wyłączone. Dla Telegram i innych natywnych klientów zatwierdzeń, które wywołują Gateway bezpośrednio, -ten fallback jest celowo ograniczony do błędów typu „approval not found”. Prawdziwa -odmowa/błąd zatwierdzenia exec nie jest po cichu ponawiana jako zatwierdzenie pluginu. +ten fallback jest celowo ograniczony do błędów typu „zatwierdzenie nie znalezione”. Rzeczywista +odmowa/błąd zatwierdzenia exec nie wykonuje po cichu ponownej próby jako zatwierdzenie pluginu. ### Natywne dostarczanie zatwierdzeń -Niektóre kanały mogą też działać jako natywni klienci zatwierdzeń. Natywni klienci dodają wiadomości prywatne do zatwierdzających, fanout do czatu źródłowego -i interaktywny UX zatwierdzeń specyficzny dla kanału ponad współdzielonym przepływem `/approve` w tym samym czacie. +Niektóre kanały mogą także działać jako natywni klienci zatwierdzeń. Natywni klienci dodają DM zatwierdzających, fanout czatu źródłowego +oraz specyficzny dla kanału interaktywny UX zatwierdzeń ponad współdzielony przepływ `/approve` +w tym samym czacie. -Gdy dostępne są natywne karty/przyciski zatwierdzeń, to natywne UI jest podstawową -ścieżką po stronie agenta. Agent nie powinien też powtarzać zduplikowanego zwykłego polecenia czatu -`/approve`, chyba że wynik narzędzia mówi, że zatwierdzenia na czacie są niedostępne lub +Gdy natywne karty/przyciski zatwierdzeń są dostępne, ten natywny UI jest główną +ścieżką skierowaną do agenta. Agent nie powinien również powielać zwykłego polecenia czatu +`/approve`, chyba że wynik narzędzia mówi, że zatwierdzenia w czacie są niedostępne albo ręczne zatwierdzenie jest jedyną pozostałą ścieżką. Model ogólny: -- polityka host exec nadal decyduje, czy zatwierdzenie exec jest wymagane +- polityka hosta exec nadal decyduje, czy zatwierdzenie exec jest wymagane - `approvals.exec` kontroluje przekazywanie promptów zatwierdzeń do innych miejsc docelowych czatu - `channels..execApprovals` kontroluje, czy dany kanał działa jako natywny klient zatwierdzeń -Natywni klienci zatwierdzeń automatycznie włączają dostarczanie najpierw do wiadomości prywatnych, gdy wszystkie poniższe warunki są spełnione: +Natywni klienci zatwierdzeń automatycznie włączają dostarczanie najpierw do DM, gdy wszystkie poniższe warunki są spełnione: - kanał obsługuje natywne dostarczanie zatwierdzeń -- zatwierdzających można rozwiązać z jawnego `execApprovals.approvers` lub z - udokumentowanych dla tego kanału źródeł fallbacku -- `channels..execApprovals.enabled` nie jest ustawione albo ma wartość `"auto"` +- zatwierdzający mogą zostać rozwiązani z jawnych `execApprovals.approvers` lub udokumentowanych źródeł fallback dla + tego kanału +- `channels..execApprovals.enabled` jest nieustawione lub ma wartość `"auto"` Ustaw `enabled: false`, aby jawnie wyłączyć natywnego klienta zatwierdzeń. Ustaw `enabled: true`, aby wymusić -jego włączenie, gdy zatwierdzający zostaną rozwiązani. Publiczne dostarczanie do czatu źródłowego pozostaje jawne przez +jego włączenie, gdy zatwierdzający się rozwiązują. Publiczne dostarczanie do czatu źródłowego pozostaje jawne przez `channels..execApprovals.target`. -FAQ: [Dlaczego istnieją dwie konfiguracje zatwierdzeń exec dla zatwierdzeń na czacie?](/help/faq#why-are-there-two-exec-approval-configs-for-chat-approvals) +FAQ: [Dlaczego istnieją dwie konfiguracje zatwierdzeń exec dla zatwierdzeń w czacie?](/help/faq#why-are-there-two-exec-approval-configs-for-chat-approvals) - Discord: `channels.discord.execApprovals.*` - Slack: `channels.slack.execApprovals.*` - Telegram: `channels.telegram.execApprovals.*` -Ci natywni klienci zatwierdzeń dodają routing wiadomości prywatnych i opcjonalny fanout na kanał ponad współdzielonym -przepływem `/approve` w tym samym czacie i współdzielonymi przyciskami zatwierdzeń. +Ci natywni klienci zatwierdzeń dodają routing DM i opcjonalny fanout do kanału ponad współdzielony +przepływ `/approve` w tym samym czacie oraz współdzielone przyciski zatwierdzeń. -Wspólne zachowanie: +Współdzielone zachowanie: -- Slack, Matrix, Microsoft Teams i podobne dostarczalne czaty używają zwykłego modelu auth kanału +- Slack, Matrix, Microsoft Teams i podobne dostarczalne czaty używają zwykłego modelu uwierzytelniania kanału dla `/approve` w tym samym czacie -- gdy natywny klient zatwierdzeń włączy się automatycznie, domyślnym natywnym celem dostarczenia są wiadomości prywatne zatwierdzających -- dla Discord i Telegram tylko rozwiązani zatwierdzający mogą zatwierdzać lub odrzucać +- gdy natywny klient zatwierdzeń włącza się automatycznie, domyślnym celem natywnego dostarczania są DM zatwierdzających +- w przypadku Discord i Telegram tylko rozwiązani zatwierdzający mogą zatwierdzać lub odrzucać - zatwierdzający Discord mogą być jawni (`execApprovals.approvers`) lub wywnioskowani z `commands.ownerAllowFrom` -- zatwierdzający Telegram mogą być jawni (`execApprovals.approvers`) lub wywnioskowani z istniejącej konfiguracji właściciela (`allowFrom` oraz `defaultTo` dla wiadomości prywatnych, gdzie obsługiwane) +- zatwierdzający Telegram mogą być jawni (`execApprovals.approvers`) lub wywnioskowani z istniejącej konfiguracji właściciela (`allowFrom`, plus `defaultTo` dla wiadomości bezpośrednich, gdy jest obsługiwane) - zatwierdzający Slack mogą być jawni (`execApprovals.approvers`) lub wywnioskowani z `commands.ownerAllowFrom` - natywne przyciski Slack zachowują rodzaj identyfikatora zatwierdzenia, więc identyfikatory `plugin:` mogą rozwiązywać zatwierdzenia pluginów - bez drugiej lokalnej warstwy fallbacku Slack -- natywny routing wiadomości prywatnych/kanałów Matrix jest tylko dla exec; zatwierdzenia pluginów Matrix pozostają na współdzielonej - ścieżce `/approve` w tym samym czacie oraz opcjonalnym przekazywaniu `approvals.plugin` -- żądający nie musi być zatwierdzającym -- czat źródłowy może zatwierdzić bezpośrednio przez `/approve`, gdy ten czat już obsługuje polecenia i odpowiedzi -- natywne przyciski zatwierdzeń Discord kierują według rodzaju identyfikatora zatwierdzenia: identyfikatory `plugin:` trafiają - bezpośrednio do zatwierdzeń pluginów, wszystko inne do zatwierdzeń exec -- natywne przyciski zatwierdzeń Telegram stosują ten sam ograniczony fallback exec-do-plugin co `/approve` -- gdy natywne `target` włącza dostarczanie do czatu źródłowego, prompty zatwierdzeń zawierają tekst polecenia -- oczekujące zatwierdzenia exec wygasają domyślnie po 30 minutach -- jeśli żadne UI operatora ani skonfigurowany klient zatwierdzeń nie mogą przyjąć żądania, prompt wraca do `askFallback` + bez drugiej lokalnej warstwy fallback w Slack +- natywny routing DM/kanału Matrix i skróty reakcji obsługują zarówno zatwierdzenia exec, jak i pluginów; + autoryzacja pluginów nadal pochodzi z `channels.matrix.dm.allowFrom` +- osoba żądająca nie musi być zatwierdzającym +- czat źródłowy może zatwierdzać bezpośrednio przez `/approve`, gdy dany czat już obsługuje polecenia i odpowiedzi +- natywne przyciski zatwierdzeń Discord routują według rodzaju identyfikatora zatwierdzenia: identyfikatory `plugin:` trafiają + bezpośrednio do zatwierdzeń pluginów, wszystko inne trafia do zatwierdzeń exec +- natywne przyciski zatwierdzeń Telegram stosują ten sam ograniczony fallback exec→plugin co `/approve` +- gdy natywny `target` włącza dostarczanie do czatu źródłowego, prompty zatwierdzeń zawierają tekst polecenia +- oczekujące zatwierdzenia exec domyślnie wygasają po 30 minutach +- jeśli żaden interfejs operatora ani skonfigurowany klient zatwierdzeń nie może przyjąć żądania, prompt przechodzi do `askFallback` -Telegram domyślnie kieruje do wiadomości prywatnych zatwierdzających (`target: "dm"`). Możesz przełączyć na `channel` lub `both`, gdy -chcesz, aby prompty zatwierdzeń pojawiały się także w czacie/temacie źródłowym Telegram. W przypadku tematów forum Telegram +Telegram domyślnie używa DM zatwierdzających (`target: "dm"`). Możesz przełączyć na `channel` lub `both`, gdy +chcesz, aby prompty zatwierdzeń pojawiały się również w źródłowym czacie/temacie Telegram. Dla tematów forum Telegram OpenClaw zachowuje temat dla promptu zatwierdzenia i follow-up po zatwierdzeniu. Zobacz: @@ -523,42 +524,42 @@ Zobacz: - [Discord](/channels/discord) - [Telegram](/channels/telegram) -### Przepływ IPC na macOS +### Przepływ IPC macOS __OC_I18N_900008__ Uwagi dotyczące bezpieczeństwa: - Tryb gniazda Unix `0600`, token przechowywany w `exec-approvals.json`. -- Kontrola peera z tym samym UID. +- Sprawdzenie peera z tym samym UID. - Challenge/response (nonce + token HMAC + hash żądania) + krótki TTL. ## Zdarzenia systemowe -Cykl życia exec jest pokazywany jako wiadomości systemowe: +Cykl życia exec jest ujawniany jako komunikaty systemowe: - `Exec running` (tylko jeśli polecenie przekracza próg powiadomienia o uruchomieniu) - `Exec finished` - `Exec denied` -Są one publikowane do sesji agenta po zgłoszeniu zdarzenia przez node. -Zatwierdzenia exec na hoście gatewaya emitują ten sam cykl życia zdarzeń, gdy polecenie się zakończy (i opcjonalnie także podczas działania dłuższego niż próg). -Exec objęte zatwierdzeniem używają ponownie identyfikatora zatwierdzenia jako `runId` w tych wiadomościach, aby ułatwić korelację. +Są one publikowane do sesji agenta po zgłoszeniu zdarzenia przez węzeł. +Zatwierdzenia exec na hoście gateway emitują ten sam cykl życia zdarzeń, gdy polecenie się kończy (oraz opcjonalnie, gdy działa dłużej niż próg). +Exec objęte zatwierdzeniem używają ponownie identyfikatora zatwierdzenia jako `runId` w tych komunikatach, aby ułatwić korelację. -## Zachowanie przy odmowie zatwierdzenia +## Zachowanie po odrzuceniu zatwierdzenia Gdy asynchroniczne zatwierdzenie exec zostanie odrzucone, OpenClaw uniemożliwia agentowi ponowne użycie -wyjścia z jakiegokolwiek wcześniejszego uruchomienia tego samego polecenia w sesji. Powód odmowy -jest przekazywany z jawną informacją, że żadne wyjście polecenia nie jest dostępne, co powstrzymuje -agenta przed twierdzeniem, że istnieje nowe wyjście, albo przed powtarzaniem odrzuconego polecenia z +wyniku z jakiegokolwiek wcześniejszego uruchomienia tego samego polecenia w sesji. Powód odrzucenia +jest przekazywany z jawną wskazówką, że nie ma dostępnych danych wyjściowych polecenia, co zatrzymuje +agenta przed twierdzeniem, że istnieją nowe dane wyjściowe, lub przed powtarzaniem odrzuconego polecenia z nieaktualnymi wynikami z wcześniejszego udanego uruchomienia. ## Konsekwencje -- **full** jest potężne; jeśli to możliwe, preferuj allowlisty. -- **ask** utrzymuje Cię w pętli, a jednocześnie pozwala na szybkie zatwierdzanie. -- Allowlisty per agent zapobiegają przeciekaniu zatwierdzeń jednego agenta do innych. -- Zatwierdzenia dotyczą tylko żądań host exec od **autoryzowanych nadawców**. Nieautoryzowani nadawcy nie mogą wydawać `/exec`. +- **full** daje szerokie uprawnienia; gdy to możliwe, preferuj listy dozwolonych. +- **ask** pozwala Ci zachować kontrolę, jednocześnie umożliwiając szybkie zatwierdzenia. +- Listy dozwolonych per agent zapobiegają przenikaniu zatwierdzeń jednego agenta do innych. +- Zatwierdzenia mają zastosowanie tylko do żądań exec hosta od **autoryzowanych nadawców**. Nieautoryzowani nadawcy nie mogą wydawać `/exec`. - `/exec security=full` to wygodna opcja na poziomie sesji dla autoryzowanych operatorów i z założenia pomija zatwierdzenia. - Aby twardo zablokować host exec, ustaw security zatwierdzeń na `deny` albo zabroń narzędzia `exec` przez politykę narzędzi. + Aby twardo zablokować exec hosta, ustaw security zatwierdzeń na `deny` lub zablokuj narzędzie `exec` przez politykę narzędzi. Powiązane: @@ -568,7 +569,7 @@ Powiązane: ## Powiązane -- [Exec](/pl/tools/exec) — narzędzie wykonywania poleceń powłoki -- [Sandboxing](/pl/gateway/sandboxing) — tryby sandboxa i dostęp do workspace +- [Exec](/pl/tools/exec) — narzędzie do wykonywania poleceń powłoki +- [Sandboxing](/pl/gateway/sandboxing) — tryby sandbox i dostęp do obszaru roboczego - [Bezpieczeństwo](/pl/gateway/security) — model bezpieczeństwa i utwardzanie - [Sandbox vs Tool Policy vs Elevated](/pl/gateway/sandbox-vs-tool-policy-vs-elevated) — kiedy używać każdego z nich