diff --git a/docs/pl/gateway/configuration-reference.md b/docs/pl/gateway/configuration-reference.md
index c875a7b9a..522093f26 100644
--- a/docs/pl/gateway/configuration-reference.md
+++ b/docs/pl/gateway/configuration-reference.md
@@ -2,34 +2,34 @@
read_when:
- Potrzebujesz dokładnej semantyki pól konfiguracji lub wartości domyślnych
- Weryfikujesz bloki konfiguracji kanałów, modeli, bramy lub narzędzi
-summary: Konfiguracja bramy dla podstawowych kluczy OpenClaw, wartości domyślnych i linków do dedykowanych odnośników podsystemów
-title: Dokumentacja konfiguracji
+summary: Odwołanie do konfiguracji bramy dla podstawowych kluczy OpenClaw, wartości domyślnych i linków do dedykowanych odwołań podsystemów
+title: Odwołanie do konfiguracji
x-i18n:
- generated_at: "2026-04-11T02:44:27Z"
+ generated_at: "2026-04-11T15:16:03Z"
model: gpt-5.4
provider: openai
- source_hash: 32acb82e756e4740d13ef12277842081f4c90df7b67850c34f8a76701fcd37d0
+ source_hash: 351a245bed59d852ea8582e4e9fec5017a5c623cd6f0034766cdea1b5330be3c
source_path: gateway/configuration-reference.md
workflow: 15
---
-# Dokumentacja konfiguracji
+# Odwołanie do konfiguracji
-Dokumentacja podstawowej konfiguracji dla `~/.openclaw/openclaw.json`. Omówienie zorientowane na zadania znajdziesz w [Konfiguracja](/pl/gateway/configuration).
+Podstawowe odwołanie do konfiguracji `~/.openclaw/openclaw.json`. Aby zobaczyć omówienie zorientowane na zadania, przejdź do [Konfiguracja](/pl/gateway/configuration).
-Ta strona obejmuje główne powierzchnie konfiguracji OpenClaw i odsyła dalej, gdy dany podsystem ma własną, bardziej szczegółową dokumentację. **Nie** próbuje umieszczać na jednej stronie każdego katalogu poleceń należącego do kanału/wtyczki ani każdego szczegółowego parametru pamięci/QMD.
+Ta strona obejmuje główne powierzchnie konfiguracji OpenClaw i prowadzi do odpowiednich miejsc, gdy podsystem ma własne, bardziej szczegółowe odwołanie. **Nie** próbuje umieszczać na jednej stronie każdego katalogu poleceń należącego do kanału/pluginu ani każdego szczegółowego ustawienia pamięci/QMD.
Źródło prawdy w kodzie:
-- `openclaw config schema` wypisuje aktualny JSON Schema używany do walidacji i Control UI, z dołączonymi metadanymi pakietowymi/wtyczek/kanałów, gdy są dostępne
-- `config.schema.lookup` zwraca jeden węzeł schematu ograniczony do ścieżki dla narzędzi analizujących szczegóły
-- `pnpm config:docs:check` / `pnpm config:docs:gen` sprawdzają skrót bazowy dokumentacji konfiguracji względem bieżącej powierzchni schematu
+- `openclaw config schema` wypisuje aktualny schemat JSON Schema używany do walidacji i Control UI, z dołączonymi metadanymi bundlowanych/pluginowych/kanałowych elementów, gdy są dostępne
+- `config.schema.lookup` zwraca jeden węzeł schematu ograniczony do ścieżki dla narzędzi do szczegółowej inspekcji
+- `pnpm config:docs:check` / `pnpm config:docs:gen` walidują hash bazowy dokumentacji konfiguracji względem bieżącej powierzchni schematu
-Dedykowane szczegółowe dokumentacje:
+Dedykowane szczegółowe odwołania:
-- [Dokumentacja konfiguracji pamięci](/pl/reference/memory-config) dla `agents.defaults.memorySearch.*`, `memory.qmd.*`, `memory.citations` oraz konfiguracji dreaming w `plugins.entries.memory-core.config.dreaming`
-- [Polecenia Slash](/pl/tools/slash-commands) dla bieżącego katalogu poleceń wbudowanych + pakietowych
-- strony właściciela kanału/wtyczki dla powierzchni poleceń specyficznych dla kanału
+- [Odwołanie do konfiguracji pamięci](/pl/reference/memory-config) dla `agents.defaults.memorySearch.*`, `memory.qmd.*`, `memory.citations` oraz konfiguracji dreaming w `plugins.entries.memory-core.config.dreaming`
+- [Polecenia ukośnikowe](/pl/tools/slash-commands) dla bieżącego katalogu poleceń wbudowanych + bundlowanych
+- strony właścicieli kanałów/pluginów dla powierzchni poleceń specyficznych dla kanałów
Format konfiguracji to **JSON5** (dozwolone komentarze i końcowe przecinki). Wszystkie pola są opcjonalne — OpenClaw używa bezpiecznych wartości domyślnych, gdy zostaną pominięte.
@@ -37,34 +37,34 @@ Format konfiguracji to **JSON5** (dozwolone komentarze i końcowe przecinki). Ws
## 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 konfiguracyjna (chyba że ustawiono `enabled: false`).
-### Dostęp do DM i grup
+### Dostęp DM i grup
-Wszystkie kanały obsługują zasady dla DM i zasady dla grup:
+Wszystkie kanały obsługują zasady dla DM i grup:
| Zasada DM | Zachowanie |
| -------------------- | -------------------------------------------------------------- |
| `pairing` (domyślna) | Nieznani nadawcy otrzymują jednorazowy kod parowania; właściciel musi zatwierdzić |
| `allowlist` | Tylko nadawcy z `allowFrom` (lub sparowanego magazynu zezwoleń) |
-| `open` | Zezwala na wszystkie przychodzące DM (wymaga `allowFrom: ["*"]`) |
-| `disabled` | Ignoruje wszystkie przychodzące DM |
+| `open` | Zezwalaj na wszystkie przychodzące DM (wymaga `allowFrom: ["*"]`) |
+| `disabled` | Ignoruj wszystkie przychodzące DM |
-| Zasada grup | Zachowanie |
-| -------------------- | ---------------------------------------------------- |
-| `allowlist` (domyślna) | Tylko grupy pasujące do skonfigurowanej listy dozwolonych |
-| `open` | Pomija listy dozwolonych grup (nadal obowiązuje wymóg wzmianki) |
-| `disabled` | Blokuje wszystkie wiadomości grupowe/pokojów |
+| Zasada grup | Zachowanie |
+| -------------------- | ------------------------------------------------------ |
+| `allowlist` (domyślna) | Tylko grupy pasujące do skonfigurowanej listy zezwoleń |
+| `open` | Pomijaj listy zezwoleń grup (nadal obowiązuje wymóg wzmianki) |
+| `disabled` | Blokuj wszystkie wiadomości grupowe/pokojowe |
`channels.defaults.groupPolicy` ustawia wartość domyślną, gdy `groupPolicy` dostawcy nie jest ustawione.
Kody parowania wygasają po 1 godzinie. Oczekujące żądania parowania DM są ograniczone do **3 na kanał**.
-Jeśli blok dostawcy całkowicie nie istnieje (`channels.` jest nieobecne), zasada grupowa w czasie działania wraca do `allowlist` (fail-closed) z ostrzeżeniem przy uruchomieniu.
+Jeśli blok dostawcy całkowicie nie istnieje (`channels.` jest nieobecne), zasada grup runtime wraca do `allowlist` (fail-closed) z ostrzeżeniem podczas uruchamiania.
### Nadpisania modelu dla kanałów
-Użyj `channels.modelByChannel`, aby przypiąć konkretne identyfikatory kanałów do modelu. Wartości akceptują `provider/model` albo skonfigurowane aliasy modeli. Mapowanie kanału jest stosowane, gdy sesja nie ma już nadpisania modelu (na przykład ustawionego przez `/model`).
+Użyj `channels.modelByChannel`, aby przypisać określone identyfikatory kanałów do modelu. Wartości akceptują `provider/model` lub skonfigurowane aliasy modeli. Mapowanie kanału jest stosowane, gdy sesja nie ma już nadpisania modelu (na przykład ustawionego przez `/model`).
```json5
{
@@ -87,7 +87,7 @@ Użyj `channels.modelByChannel`, aby przypiąć konkretne identyfikatory kanał
### Domyślne ustawienia kanałów i heartbeat
-Użyj `channels.defaults` dla współdzielonego zachowania zasad grup i heartbeat między dostawcami:
+Użyj `channels.defaults` dla współdzielonych ustawień zasad grup i heartbeat we wszystkich dostawcach:
```json5
{
@@ -106,14 +106,14 @@ Użyj `channels.defaults` dla współdzielonego zachowania zasad grup i heartbea
```
- `channels.defaults.groupPolicy`: zapasowa zasada 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 listy dozwolonych), `allowlist_quote` (jak allowlist, ale zachowuje jawny kontekst cytatu/odpowiedzi). Nadpisanie dla kanału: `channels..contextVisibility`.
-- `channels.defaults.heartbeat.showOk`: uwzględnia zdrowe statusy kanałów w danych heartbeat.
-- `channels.defaults.heartbeat.showAlerts`: uwzględnia statusy obniżonej sprawności/błędów w danych heartbeat.
-- `channels.defaults.heartbeat.useIndicator`: renderuje kompaktowe dane heartbeat w stylu wskaźnika.
+- `channels.defaults.contextVisibility`: domyślny tryb widoczności kontekstu uzupełniającego dla wszystkich kanałów. Wartości: `all` (domyślna, uwzględnia cały cytowany/wątkowy/historyczny kontekst), `allowlist` (uwzględnia tylko kontekst od nadawców z listy zezwoleń), `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 pogorszone/błędów w wyjściu heartbeat.
+- `channels.defaults.heartbeat.useIndicator`: renderuje kompaktowe wyjście heartbeat w stylu wskaźnika.
### WhatsApp
-WhatsApp działa przez kanał web bramy (Baileys Web). Uruchamia się automatycznie, gdy istnieje połączona sesja.
+WhatsApp działa przez web channel bramy (Baileys Web). Uruchamia się automatycznie, gdy istnieje powiązana sesja.
```json5
{
@@ -124,7 +124,7 @@ WhatsApp działa przez kanał web bramy (Baileys Web). Uruchamia się automatycz
textChunkLimit: 4000,
chunkMode: "length", // length | newline
mediaMaxMb: 50,
- sendReadReceipts: true, // niebieskie znaczniki (false w trybie czatu z samym sobą)
+ sendReadReceipts: true, // blue ticks (false in self-chat mode)
groups: {
"*": { requireMention: true },
},
@@ -164,10 +164,10 @@ WhatsApp działa przez kanał web bramy (Baileys Web). Uruchamia się automatycz
}
```
-- Polecenia wychodzące domyślnie używają konta `default`, jeśli istnieje; w przeciwnym razie używane jest pierwsze skonfigurowane id konta (posortowane).
-- Opcjonalne `channels.whatsapp.defaultAccount` nadpisuje ten zapasowy wybór konta domyślnego, jeśli pasuje do skonfigurowanego id konta.
+- Polecenia wychodzące domyślnie używają konta `default`, jeśli istnieje; w przeciwnym razie używany jest pierwszy skonfigurowany identyfikator konta (posortowany).
+- Opcjonalne `channels.whatsapp.defaultAccount` nadpisuje ten domyślny wybór zapasowego konta, gdy pasuje do skonfigurowanego identyfikatora konta.
- Starszy katalog uwierzytelniania Baileys dla pojedynczego konta jest migrowany przez `openclaw doctor` do `whatsapp/default`.
-- Nadpisania dla pojedynczego konta: `channels.whatsapp.accounts..sendReadReceipts`, `channels.whatsapp.accounts..dmPolicy`, `channels.whatsapp.accounts..allowFrom`.
+- Nadpisania per konto: `channels.whatsapp.accounts..sendReadReceipts`, `channels.whatsapp.accounts..dmPolicy`, `channels.whatsapp.accounts..allowFrom`.
@@ -225,13 +225,13 @@ WhatsApp działa przez kanał web bramy (Baileys Web). Uruchamia się automatycz
}
```
-- Token bota: `channels.telegram.botToken` albo `channels.telegram.tokenFile` (tylko zwykły plik; dowiązania symboliczne są odrzucane), z `TELEGRAM_BOT_TOKEN` jako wartością zapasową dla konta domyślnego.
-- Opcjonalne `channels.telegram.defaultAccount` nadpisuje wybór konta domyślnego, jeśli pasuje do skonfigurowanego id konta.
-- W konfiguracjach wielokontowych (2+ id kont) ustaw jawne konto domyślne (`channels.telegram.defaultAccount` albo `channels.telegram.accounts.default`), aby uniknąć routingu zapasowego; `openclaw doctor` ostrzega, gdy tego brakuje albo 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 [Agenci ACP](/pl/tools/acp-agents#channel-specific-settings).
-- Podglądy strumienia Telegram używają `sendMessage` + `editMessageText` (działa w czatach bezpośrednich i grupowych).
-- Zasady ponawiania: zobacz [Zasady ponawiania](/pl/concepts/retry).
+- 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.
+- Opcjonalne `channels.telegram.defaultAccount` nadpisuje domyślny wybór konta, gdy pasuje do skonfigurowanego identyfikatora konta.
+- W konfiguracjach wielokontowych (2+ identyfikatory kont) ustaw jawne konto domyślne (`channels.telegram.defaultAccount` lub `channels.telegram.accounts.default`), aby uniknąć routingu zapasowego; `openclaw doctor` ostrzega, gdy tego brakuje lub jest nieprawidłowe.
+- `configWrites: false` blokuje zapisy konfiguracji inicjowane przez Telegrama (migracje identyfikatorów supergrup, `/config set|unset`).
+- Wpisy najwyższego poziomu `bindings[]` z `type: "acp"` konfigurują trwałe powiązania ACP dla tematów forum (użyj kanonicznego `chatId:topic:topicId` w `match.peer.id`). Semantyka pól jest współdzielona w [ACP Agents](/pl/tools/acp-agents#channel-specific-settings).
+- Podglądy strumieni Telegram używają `sendMessage` + `editMessageText` (działa w czatach bezpośrednich i grupowych).
+- Zasada ponawiania: zobacz [Zasada ponawiania](/pl/concepts/retry).
### Discord
@@ -335,32 +335,32 @@ WhatsApp działa przez kanał web bramy (Baileys Web). Uruchamia się automatycz
- 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 do wywołania; ustawienia ponawiania/zasad konta nadal pochodzą z wybranego konta w aktywnej migawce runtime.
-- Opcjonalne `channels.discord.defaultAccount` nadpisuje wybór konta domyślnego, jeśli pasuje do skonfigurowanego id konta.
-- Używaj `user:` (DM) lub `channel:` (kanał guild); same numeryczne ID są odrzucane.
-- Slugi guild są pisane małymi literami, a spacje są zastępowane przez `-`; klucze kanałów używają nazwy w formie sluga (bez `#`). Preferuj identyfikatory guild.
-- Wiadomości napisane przez bota 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 są 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).
+- Opcjonalne `channels.discord.defaultAccount` nadpisuje domyślny wybór konta, gdy pasuje do skonfigurowanego identyfikatora konta.
+- Używaj `user:` (DM) lub `channel:` (kanał serwera) jako celów dostarczenia; same numeryczne identyfikatory są odrzucane.
+- Slugi serwerów są pisane małymi literami, a spacje są zastępowane przez `-`; klucze kanałów używają nazwy w postaci sluga (bez `#`). Preferuj identyfikatory serwerów.
+- Wiadomości napisane przez bota 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 na poziomie kanału) odrzuca wiadomości, które wzmiankują innego użytkownika lub rolę, ale nie bota (z wyłączeniem @everyone/@here).
- `maxLinesPerMessage` (domyślnie 17) dzieli wysokie wiadomości nawet wtedy, gdy mają mniej niż 2000 znaków.
-- `channels.discord.threadBindings` steruje routingiem powiązanym z wątkami Discord:
- - `enabled`: nadpisanie Discord dla funkcji sesji powiązanych z wątkiem (`/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age` oraz dostarczania/routingu związanego z powiązaniem)
+- `channels.discord.threadBindings` steruje routingiem związanym z wątkami Discord:
+ - `enabled`: nadpisanie Discord dla funkcji sesji związanych z wątkiem (`/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age` oraz dostarczanie/routing związane z powiązaniem)
- `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)
- `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 id kanału/wątku w `match.peer.id`). Semantyka pól jest współdzielona w [Agenci ACP](/pl/tools/acp-agents#channel-specific-settings).
-- `channels.discord.ui.components.accentColor` ustawia kolor akcentu dla kontenerów komponentów v2 Discord.
+- Wpisy najwyższego poziomu `bindings[]` z `type: "acp"` konfigurują trwałe powiązania ACP dla kanałów i wątków (użyj identyfikatora kanału/wątku w `match.peer.id`). Semantyka pól jest współdzielona w [ACP Agents](/pl/tools/acp-agents#channel-specific-settings).
+- `channels.discord.ui.components.accentColor` ustawia kolor akcentu dla kontenerów Discord components v2.
- `channels.discord.voice` włącza rozmowy w kanałach głosowych Discord oraz opcjonalne automatyczne dołączanie + nadpisania TTS.
-- `channels.discord.voice.daveEncryption` i `channels.discord.voice.decryptionFailureTolerance` są przekazywane bezpośrednio do opcji DAVE w `@discordjs/voice` (`true` i `24` domyślnie).
-- 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 strumieniowania. Starsze wartości `streamMode` i logiczne `streaming` są automatycznie migrowane.
-- `channels.discord.autoPresence` mapuje dostępność runtime na obecność bota (healthy => online, degraded => idle, exhausted => dnd) i umożliwia opcjonalne nadpisania tekstu statusu.
-- `channels.discord.dangerouslyAllowNameMatching` ponownie włącza dopasowywanie według zmiennych nazw/tagów (awaryjny tryb zgodności).
+- `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, opuszczając i ponownie dołączając do sesji głosowej po powtarzających się błędach deszyfrowania.
+- `channels.discord.streaming` jest kanonicznym kluczem trybu strumieniowania. Starsze wartości `streamMode` i logiczne wartości `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 zmiennej nazwie/tagu (tryb zgodności break-glass).
- `channels.discord.execApprovals`: natywne dla Discord dostarczanie zatwierdzeń exec i autoryzacja zatwierdzających.
- - `enabled`: `true`, `false` lub `"auto"` (domyślnie). W trybie auto zatwierdzenia 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. Gdy pominięte, używana jest wartość zapasowa z `commands.ownerAllowFrom`.
- - `agentFilter`: opcjonalna lista dozwolonych identyfikatorów agentów. Pomiń, aby przekazywać zatwierdzenia dla wszystkich agentów.
+ - `enabled`: `true`, `false` lub `"auto"` (domyślnie). W trybie auto zatwierdzenia exec aktywują się, gdy zatwierdzający mogą zostać rozpoznani z `approvers` lub `commands.ownerAllowFrom`.
+ - `approvers`: identyfikatory użytkowników Discord, którym wolno zatwierdzać żądania exec. Gdy pominięte, używana jest wartość zapasowa z `commands.ownerAllowFrom`.
+ - `agentFilter`: opcjonalna lista zezwoleń identyfikatorów agentów. Pomiń, aby przekazywać zatwierdzenia dla wszystkich agentów.
- `sessionFilter`: opcjonalne wzorce kluczy sesji (podciąg lub regex).
- - `target`: gdzie wysyłać prompty zatwierdzeń. `"dm"` (domyślnie) wysyła do DM zatwierdzających, `"channel"` wysyła do kanału źródłowego, `"both"` wysyła do obu. Gdy target zawiera `"channel"`, przyciski mogą być używane tylko przez rozwiązanych zatwierdzających.
- - `cleanupAfterResolve`: gdy `true`, usuwa DM z zatwierdzeniami po zatwierdzeniu, odrzuceniu lub przekroczeniu czasu.
+ - `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 zawiera `"channel"`, przycisków mogą używać tylko rozpoznani zatwierdzający.
+ - `cleanupAfterResolve`: gdy `true`, usuwa DM z zatwierdzeniem po zatwierdzeniu, odrzuceniu lub przekroczeniu limitu 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).
@@ -393,11 +393,11 @@ WhatsApp działa przez kanał web bramy (Baileys Web). Uruchamia się automatycz
}
```
-- JSON konta usługi: inline (`serviceAccount`) albo z pliku (`serviceAccountFile`).
-- SecretRef dla konta usługi jest również obsługiwany (`serviceAccountRef`).
-- Zapasowe zmienne środowiskowe: `GOOGLE_CHAT_SERVICE_ACCOUNT` lub `GOOGLE_CHAT_SERVICE_ACCOUNT_FILE`.
-- Używaj `spaces/` lub `users/` jako celów dostarczania.
-- `channels.googlechat.dangerouslyAllowNameMatching` ponownie włącza dopasowywanie według zmiennego adresu e-mail principal (awaryjny tryb zgodności).
+- JSON konta usługi: inline (`serviceAccount`) lub na podstawie pliku (`serviceAccountFile`).
+- Obsługiwany jest również SecretRef konta usługi (`serviceAccountRef`).
+- Wartości zapasowe z env: `GOOGLE_CHAT_SERVICE_ACCOUNT` lub `GOOGLE_CHAT_SERVICE_ACCOUNT_FILE`.
+- Używaj `spaces/` lub `users/` jako celów dostarczenia.
+- `channels.googlechat.dangerouslyAllowNameMatching` ponownie włącza dopasowywanie po zmiennym principalu email (tryb zgodności break-glass).
### Slack
@@ -464,39 +464,39 @@ WhatsApp działa przez kanał web bramy (Baileys Web). Uruchamia się automatycz
}
```
-- **Tryb Socket** wymaga zarówno `botToken`, jak i `appToken` (`SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN` jako zapasowe zmienne środowiskowe dla konta domyślnego).
-- **Tryb HTTP** wymaga `botToken` oraz `signingSecret` (w katalogu głównym albo per konto).
+- **Tryb socket** wymaga zarówno `botToken`, jak i `appToken` (`SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN` jako wartość zapasowa z env dla konta domyślnego).
+- **Tryb HTTP** wymaga `botToken` oraz `signingSecret` (w katalogu głównym lub per konto).
- `botToken`, `appToken`, `signingSecret` i `userToken` akceptują zwykłe
- ciągi tekstowe albo obiekty SecretRef.
-- Migawki kont Slack udostępniają pola źródła/statusu dla poszczególnych danych uwierzytelniających, takie jak
+ ciągi znaków lub obiekty SecretRef.
+- Migawki kont Slack ujawniają pola źródła/statusu poświadczeń per poświadczenie, takie jak
`botTokenSource`, `botTokenStatus`, `appTokenStatus` oraz, w trybie HTTP,
`signingSecretStatus`. `configured_unavailable` oznacza, że konto jest
skonfigurowane przez SecretRef, ale bieżąca ścieżka polecenia/runtime nie mogła
rozwiązać wartości sekretu.
-- `configWrites: false` blokuje zapisy konfiguracji inicjowane ze Slacka.
-- Opcjonalne `channels.slack.defaultAccount` nadpisuje wybór konta domyślnego, jeśli pasuje do skonfigurowanego id konta.
-- `channels.slack.streaming.mode` to kanoniczny klucz trybu strumieniowania Slack. `channels.slack.streaming.nativeTransport` steruje natywnym transportem strumieniowym Slack. Starsze wartości `streamMode`, logiczne `streaming` i `nativeStreaming` są automatycznie migrowane.
-- Używaj `user:` (DM) lub `channel:` jako celów dostarczania.
+- `configWrites: false` blokuje zapisy konfiguracji inicjowane przez Slack.
+- Opcjonalne `channels.slack.defaultAccount` nadpisuje domyślny wybór konta, gdy pasuje do skonfigurowanego identyfikatora konta.
+- `channels.slack.streaming.mode` jest kanonicznym kluczem trybu strumieniowania Slack. `channels.slack.streaming.nativeTransport` steruje natywnym transportem strumieniowania Slack. Starsze wartości `streamMode`, logiczne wartości `streaming` oraz `nativeStreaming` są automatycznie migrowane.
+- Używaj `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) albo współdzielony 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) albo współdzielone w obrębie kanału. `thread.inheritParent` kopiuje transkrypt kanału nadrzędnego do nowych wątków.
-- Natywne strumieniowanie Slack oraz status wątku Slack w stylu asystenta „is typing...” wymagają celu odpowiedzi w wątku. DM najwyższego poziomu domyślnie pozostają poza wątkiem, więc używają `typingReaction` albo normalnego dostarczania zamiast podglądu w stylu wątku.
-- `typingReaction` dodaje tymczasową reakcję do przychodzącej wiadomości Slack podczas generowania odpowiedzi, a następnie usuwa ją po zakończeniu. Użyj shortcode emoji Slack, takiego jak `"hourglass_flowing_sand"`.
-- `channels.slack.execApprovals`: natywne dla Slack dostarczanie zatwierdzeń exec i autoryzacja zatwierdzających. Ten sam schemat co w Discord: `enabled` (`true`/`false`/`"auto"`), `approvers` (identyfikatory użytkowników Slack), `agentFilter`, `sessionFilter` i `target` (`"dm"`, `"channel"` lub `"both"`).
+- Natywne strumieniowanie Slack oraz status wątku Slack w stylu asystenta „pisze...” wymagają docelowego wątku odpowiedzi. DM najwyższego poziomu domyślnie pozostają poza wątkiem, więc używają `typingReaction` lub normalnego dostarczenia zamiast podglądu w stylu wątku.
+- `typingReaction` dodaje tymczasową reakcję do przychodzącej wiadomości Slack podczas generowania odpowiedzi, a następnie usuwa ją po zakończeniu. Użyj skrótu emoji Slack, takiego jak `"hourglass_flowing_sand"`.
+- `channels.slack.execApprovals`: natywne dla Slack dostarczanie zatwierdzeń exec i autoryzacja zatwierdzających. Ten sam schemat co w Discord: `enabled` (`true`/`false`/`"auto"`), `approvers` (identyfikatory użytkowników Slack), `agentFilter`, `sessionFilter` oraz `target` (`"dm"`, `"channel"` lub `"both"`).
| Grupa działań | Domyślnie | Uwagi |
| ------------- | --------- | ------------------------ |
| reactions | włączone | Reagowanie + lista reakcji |
| messages | włączone | Odczyt/wysyłanie/edycja/usuwanie |
| pins | włączone | Przypinanie/odpinanie/lista |
-| memberInfo | włączone | Informacje o członku |
+| memberInfo | włączone | Informacje o członkach |
| emojiList | włączone | Lista niestandardowych emoji |
### Mattermost
-Mattermost jest dostarczany jako wtyczka: `openclaw plugins install @openclaw/mattermost`.
+Mattermost jest dostarczany jako plugin: `openclaw plugins install @openclaw/mattermost`.
```json5
{
@@ -526,23 +526,23 @@ Mattermost jest dostarczany jako wtyczka: `openclaw plugins install @openclaw/ma
}
```
-Tryby czatu: `oncall` (odpowiada na wzmiankę @, domyślnie), `onmessage` (na każdą wiadomość), `onchar` (na wiadomości zaczynające się od prefiksu wyzwalacza).
+Tryby czatu: `oncall` (odpowiada na wzmiankę @, domyślnie), `onmessage` (na każdą wiadomość), `onchar` (wiadomości zaczynające się od prefiksu wyzwalającego).
-Gdy włączone są natywne polecenia Mattermost:
+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ć punkt końcowy bramy OpenClaw i być osiągalny z serwera Mattermost.
-- Natywne callbacki slash są uwierzytelniane tokenami per polecenie zwracanymi
- przez Mattermost podczas rejestracji poleceń slash. Jeśli rejestracja się nie powiedzie lub nie
- zostaną aktywowane żadne polecenia, OpenClaw odrzuci callbacki z komunikatem
+- Natywne wywołania slash callback są uwierzytelniane za pomocą tokenów per polecenie zwracanych
+ przez Mattermost podczas rejestracji polecenia slash. Jeśli rejestracja się nie powiedzie lub nie
+ zostaną aktywowane żadne polecenia, OpenClaw odrzuca callbacki z 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 zabrania zapisów konfiguracji inicjowanych z Mattermost.
+- `channels.mattermost.configWrites`: zezwala lub zabrania zapisów konfiguracji inicjowanych przez Mattermost.
- `channels.mattermost.requireMention`: wymaga `@mention` przed odpowiedzią w kanałach.
-- `channels.mattermost.groups..requireMention`: nadpisanie wymogu wzmianki per kanał (`"*"` dla wartości domyślnej).
-- Opcjonalne `channels.mattermost.defaultAccount` nadpisuje wybór konta domyślnego, jeśli pasuje do skonfigurowanego id konta.
+- `channels.mattermost.groups..requireMention`: nadpisanie wymogu wzmianki per kanał (`"*"` jako domyślne).
+- Opcjonalne `channels.mattermost.defaultAccount` nadpisuje domyślny wybór konta, gdy pasuje do skonfigurowanego identyfikatora konta.
### Signal
@@ -565,13 +565,13 @@ Gdy włączone są natywne polecenia Mattermost:
**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 zabrania zapisów konfiguracji inicjowanych z Signal.
-- Opcjonalne `channels.signal.defaultAccount` nadpisuje wybór konta domyślnego, jeśli pasuje do skonfigurowanego id konta.
+- `channels.signal.account`: przypina uruchamianie kanału do konkretnej tożsamości konta Signal.
+- `channels.signal.configWrites`: zezwala lub zabrania zapisów konfiguracji inicjowanych przez Signal.
+- Opcjonalne `channels.signal.defaultAccount` nadpisuje domyślny wybór konta, gdy pasuje do skonfigurowanego identyfikatora konta.
### BlueBubbles
-BlueBubbles to zalecana ścieżka dla iMessage (oparta na wtyczce, konfigurowana w `channels.bluebubbles`).
+BlueBubbles jest zalecaną ścieżką dla iMessage (opartą na pluginie, konfigurowaną w `channels.bluebubbles`).
```json5
{
@@ -586,9 +586,9 @@ BlueBubbles to zalecana ścieżka dla iMessage (oparta na wtyczce, konfigurowana
}
```
-- Główne ścieżki kluczy opisane tutaj: `channels.bluebubbles`, `channels.bluebubbles.dmPolicy`.
-- Opcjonalne `channels.bluebubbles.defaultAccount` nadpisuje wybór konta domyślnego, jeśli pasuje do skonfigurowanego id konta.
-- Wpisy najwyższego poziomu `bindings[]` z `type: "acp"` mogą wiązać konwersacje BlueBubbles z trwałymi sesjami ACP. Użyj uchwytu BlueBubbles albo ciągu docelowego (`chat_id:*`, `chat_guid:*`, `chat_identifier:*`) w `match.peer.id`. Współdzielona semantyka pól: [Agenci ACP](/pl/tools/acp-agents#channel-specific-settings).
+- Podstawowe ścieżki kluczy omawiane tutaj: `channels.bluebubbles`, `channels.bluebubbles.dmPolicy`.
+- Opcjonalne `channels.bluebubbles.defaultAccount` nadpisuje domyślny wybór konta, gdy pasuje do skonfigurowanego identyfikatora konta.
+- Wpisy najwyższego poziomu `bindings[]` z `type: "acp"` mogą wiązać 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 udokumentowana w [BlueBubbles](/pl/channels/bluebubbles).
### iMessage
@@ -617,17 +617,17 @@ OpenClaw uruchamia `imsg rpc` (JSON-RPC przez stdio). Nie jest wymagany daemon a
}
```
-- Opcjonalne `channels.imessage.defaultAccount` nadpisuje wybór konta domyślnego, jeśli pasuje do skonfigurowanego id konta.
+- Opcjonalne `channels.imessage.defaultAccount` nadpisuje domyślny wybór konta, gdy pasuje do skonfigurowanego identyfikatora konta.
- Wymaga Full Disk Access do bazy danych Messages.
- Preferuj cele `chat_id:`. Użyj `imsg chats --limit 20`, aby wyświetlić listę czatów.
-- `cliPath` może wskazywać na wrapper SSH; ustaw `remoteHost` (`host` albo `user@host`) dla pobierania załączników przez SCP.
+- `cliPath` może wskazywać na opakowanie 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 zabrania 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 albo 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`: zezwala lub zabrania zapisów konfiguracji inicjowanych przez iMessage.
+- Wpisy najwyższego poziomu `bindings[]` z `type: "acp"` mogą wiązać konwersacje iMessage z trwałymi sesjami ACP. Użyj znormalizowanego uchwytu lub jawnego celu czatu (`chat_id:*`, `chat_guid:*`, `chat_identifier:*`) w `match.peer.id`. Współdzielona semantyka pól: [ACP Agents](/pl/tools/acp-agents#channel-specific-settings).
-
+
```bash
#!/usr/bin/env bash
@@ -638,7 +638,7 @@ exec ssh -T gateway-host imsg "$@"
### Matrix
-Matrix jest obsługiwany przez rozszerzenie i konfigurowany w `channels.matrix`.
+Matrix jest oparty na rozszerzeniu i konfigurowany w `channels.matrix`.
```json5
{
@@ -669,24 +669,24 @@ 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ą to nadpisać przez `channels.matrix.accounts..proxy`.
-- `channels.matrix.network.dangerouslyAllowPrivateNetwork` zezwala na prywatne/wewnętrzne homeservery. `proxy` i ten opt-in sieciowy to niezależne mechanizmy sterowania.
+- `channels.matrix.proxy` kieruje ruch HTTP Matrix przez jawnie określony proxy HTTP(S). Nazwane konta mogą go nadpisywać za pomocą `channels.matrix.accounts..proxy`.
+- `channels.matrix.network.dangerouslyAllowPrivateNetwork` pozwala na prywatne/wewnętrzne homeservery. `proxy` i ta zgoda sieciowa opt-in to niezależne mechanizmy.
- `channels.matrix.defaultAccount` wybiera preferowane konto w konfiguracjach wielokontowych.
-- `channels.matrix.autoJoin` domyślnie ma wartość `off`, więc zaproszone pokoje i nowe zaproszenia w stylu DM są ignorowane, dopóki nie ustawisz `autoJoin: "allowlist"` wraz z `autoJoinAllowlist` albo `autoJoin: "always"`.
+- `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ący mogą zostać rozwiązani z `approvers` lub `commands.ownerAllowFrom`.
- - `approvers`: identyfikatory użytkowników Matrix (np. `@owner:example.org`) uprawnione do zatwierdzania żądań exec.
- - `agentFilter`: opcjonalna lista dozwolonych identyfikatorów agentów. Pomiń, aby przekazywać zatwierdzenia dla wszystkich agentów.
+ - `enabled`: `true`, `false` lub `"auto"` (domyślnie). W trybie auto zatwierdzenia exec aktywują się, gdy zatwierdzający mogą zostać rozpoznani z `approvers` lub `commands.ownerAllowFrom`.
+ - `approvers`: identyfikatory użytkowników Matrix (np. `@owner:example.org`), którym wolno zatwierdzać żądania exec.
+ - `agentFilter`: opcjonalna lista zezwoleń identyfikatorów agentów. Pomiń, aby przekazywać zatwierdzenia dla wszystkich agentów.
- `sessionFilter`: opcjonalne wzorce kluczy sesji (podciąg lub regex).
- - `target`: gdzie wysyłać prompty zatwierdzeń. `"dm"` (domyślnie), `"channel"` (pokój źródłowy) albo `"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 routowanego peera, a `per-room` izoluje każdy pokój DM.
-- Status probes Matrix i wyszukiwania w katalogu na żywo używają tych samych zasad proxy co ruch runtime.
+- `channels.matrix.dm.sessionScope` steruje tym, jak DM Matrix są grupowane w sesje: `per-user` (domyślnie) współdzieli według routowanego 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, reguły targetowania i przykłady konfiguracji są udokumentowane w [Matrix](/pl/channels/matrix).
### Microsoft Teams
-Microsoft Teams jest obsługiwany przez rozszerzenie i konfigurowany w `channels.msteams`.
+Microsoft Teams jest oparty na rozszerzeniu i konfigurowany w `channels.msteams`.
```json5
{
@@ -701,12 +701,12 @@ Microsoft Teams jest obsługiwany przez rozszerzenie i konfigurowany w `channels
}
```
-- Główne ścieżki kluczy opisane tutaj: `channels.msteams`, `channels.msteams.configWrites`.
+- Podstawowe ścieżki kluczy omawiane tutaj: `channels.msteams`, `channels.msteams.configWrites`.
- Pełna konfiguracja Teams (poświadczenia, webhook, zasady DM/grup, nadpisania per zespół/per kanał) jest udokumentowana w [Microsoft Teams](/pl/channels/msteams).
### IRC
-IRC jest obsługiwany przez rozszerzenie i konfigurowany w `channels.irc`.
+IRC jest oparte na rozszerzeniu i konfigurowane w `channels.irc`.
```json5
{
@@ -727,9 +727,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.*`.
-- Opcjonalne `channels.irc.defaultAccount` nadpisuje wybór konta domyślnego, jeśli pasuje do skonfigurowanego id konta.
-- Pełna konfiguracja kanału IRC (host/port/TLS/kanały/listy dozwolonych/wymóg wzmianki) jest udokumentowana w [IRC](/pl/channels/irc).
+- Podstawowe ścieżki kluczy omawiane tutaj: `channels.irc`, `channels.irc.dmPolicy`, `channels.irc.configWrites`, `channels.irc.nickserv.*`.
+- Opcjonalne `channels.irc.defaultAccount` nadpisuje domyślny wybór konta, gdy pasuje do skonfigurowanego identyfikatora konta.
+- Pełna konfiguracja kanału IRC (host/port/TLS/kanały/listy zezwoleń/wymóg wzmianki) jest udokumentowana w [IRC](/pl/channels/irc).
### Wiele kont (wszystkie kanały)
@@ -755,12 +755,12 @@ Uruchamiaj wiele kont na kanał (każde z własnym `accountId`):
```
- `default` jest używane, gdy `accountId` zostanie pominięte (CLI + routing).
-- Tokeny ze środowiska mają zastosowanie tylko do konta **default**.
-- Bazowe ustawienia kanału mają zastosowanie do wszystkich kont, chyba że zostaną nadpisane per konto.
+- Tokeny z env dotyczą tylko konta **default**.
+- Bazowe ustawienia kanału obowiązują dla wszystkich kont, chyba że zostaną nadpisane per konto.
- Użyj `bindings[].match.accountId`, aby kierować każde konto do innego agenta.
-- Jeśli dodasz konto inne niż domyślne przez `openclaw channels add` (lub onboarding kanału), gdy nadal używasz jednokontowej konfiguracji kanału na najwyższym poziomie, OpenClaw najpierw promuje najwyższego poziomu wartości jednokontowe przypisane do 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/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 najwyższego poziomu wartości jednokontowe przypisane do konta do promowanego konta wybranego dla tego kanału. Większość kanałów używa `accounts.default`; Matrix może zamiast tego zachować istniejący pasujący nazwany/docelowy wpis domyślny.
+- Jeśli dodasz konto inne niż domyślne przez `openclaw channels add` (lub onboarding kanału), pozostając jeszcze przy jednokontowej konfiguracji kanału na poziomie głównym, OpenClaw najpierw promuje przypisane do konta wartości najwyższego poziomu z konfiguracji jednokontowej do mapy kont kanału, aby oryginalne konto nadal działało. Większość kanałów przenosi je do `channels..accounts.default`; Matrix może zamiast tego zachować istniejący pasujący nazwany/domyslny cel.
+- Istniejące powiązania tylko kanałowe (bez `accountId`) nadal pasują do konta domyślnego; powiązania przypisane do kont pozostają opcjonalne.
+- `openclaw doctor --fix` również naprawia mieszane kształty, przenosząc przypisane do konta wartości najwyższego poziomu z konfiguracji jednokontowej do promowanego konta wybranego dla tego kanału. Większość kanałów używa `accounts.default`; Matrix może zamiast tego zachować istniejący pasujący nazwany/domyslny cel.
### Inne kanały rozszerzeń
@@ -769,13 +769,13 @@ Zobacz pełny indeks kanałów: [Kanały](/pl/channels).
### Wymóg wzmianki w czatach grupowych
-Wiadomości grupowe domyślnie **wymagają wzmianki** (wzmianka z metadanych albo bezpieczne wzorce regex). Dotyczy WhatsApp, Telegram, Discord, Google Chat i czatów grupowych iMessage.
+Wiadomości grupowe domyślnie **wymagają wzmianki** (wzmianka w metadanych lub bezpieczne wzorce regex). Dotyczy to WhatsApp, Telegram, Discord, Google Chat i czatów grupowych iMessage.
**Typy wzmianek:**
-- **Wzmianki w metadanych**: natywne wzmianki @ platformy. Ignorowane w trybie czatu z samym sobą w WhatsApp.
+- **Wzmianki w metadanych**: natywne wzmianki platformy @. Są ignorowane w trybie self-chat WhatsApp.
- **Wzorce tekstowe**: bezpieczne wzorce regex w `agents.list[].groupChat.mentionPatterns`. Nieprawidłowe wzorce i niebezpieczne zagnieżdżone powtórzenia są ignorowane.
-- Wymóg wzmianki jest egzekwowany tylko wtedy, gdy wykrywanie jest możliwe (natywne wzmianki albo co najmniej jeden wzorzec).
+- Wymóg wzmianki jest egzekwowany tylko wtedy, gdy wykrywanie jest możliwe (natywne wzmianki lub co najmniej jeden wzorzec).
```json5
{
@@ -805,13 +805,13 @@ Wiadomości grupowe domyślnie **wymagają wzmianki** (wzmianka z metadanych alb
}
```
-Rozstrzyganie: nadpisanie per DM → wartość domyślna dostawcy → brak limitu (zachowywane wszystko).
+Rozstrzyganie: nadpisanie per DM → domyślna wartość dostawcy → brak limitu (zachowywane jest wszystko).
Obsługiwane: `telegram`, `whatsapp`, `discord`, `slack`, `signal`, `imessage`, `msteams`.
-#### Tryb czatu z samym sobą
+#### Tryb self-chat
-Uwzględnij własny numer w `allowFrom`, aby włączyć tryb czatu z samym sobą (ignoruje natywne wzmianki @, odpowiada tylko na wzorce tekstowe):
+Uwzględnij własny numer w `allowFrom`, aby włączyć tryb self-chat (ignoruje natywne wzmianki @, odpowiada tylko na wzorce tekstowe):
```json5
{
@@ -832,7 +832,7 @@ Uwzględnij własny numer w `allowFrom`, aby włączyć tryb czatu z samym sobą
}
```
-### Polecenia (obsługa poleceń na czacie)
+### Polecenia (obsługa poleceń czatu)
```json5
{
@@ -861,27 +861,27 @@ Uwzględnij własny numer w `allowFrom`, aby włączyć tryb czatu z samym sobą
-- Ten blok konfiguruje powierzchnie poleceń. Aktualny katalog poleceń wbudowanych + pakietowych znajdziesz w [Polecenia Slash](/pl/tools/slash-commands).
-- Ta strona jest dokumentacją **kluczy konfiguracji**, a nie pełnym katalogiem poleceń. Polecenia należące do kanałów/wtyczek, takie jak QQ Bot `/bot-ping` `/bot-help` `/bot-logs`, LINE `/card`, device-pair `/pair`, memory `/dreaming`, phone-control `/phone` i Talk `/voice`, są udokumentowane na stronach ich kanałów/wtyczek oraz w [Polecenia Slash](/pl/tools/slash-commands).
-- Polecenia tekstowe muszą być **samodzielnymi** wiadomościami z początkowym `/`.
+- Ten blok konfiguruje powierzchnie poleceń. Bieżący katalog poleceń wbudowanych + bundlowanych znajdziesz w [Polecenia ukośnikowe](/pl/tools/slash-commands).
+- Ta strona jest **odwołaniem do kluczy konfiguracji**, a nie pełnym katalogiem poleceń. Polecenia należące do kanałów/pluginów, takie jak QQ Bot `/bot-ping` `/bot-help` `/bot-logs`, LINE `/card`, device-pair `/pair`, memory `/dreaming`, phone-control `/phone` i Talk `/voice`, są udokumentowane na stronach ich kanałów/pluginów oraz w [Poleceniach ukośnikowych](/pl/tools/slash-commands).
+- Polecenia tekstowe muszą być **samodzielnymi** wiadomościami zaczynającymi się od `/`.
- `native: "auto"` włącza natywne polecenia dla Discord/Telegram, pozostawia Slack wyłączony.
- `nativeSkills: "auto"` włącza natywne polecenia Skills dla Discord/Telegram, pozostawia Slack wyłączony.
-- Nadpisanie per kanał: `channels.discord.commands.native` (bool albo `"auto"`). `false` czyści wcześniej zarejestrowane polecenia.
+- Nadpisanie per kanał: `channels.discord.commands.native` (bool lub `"auto"`). `false` czyści wcześniej zarejestrowane polecenia.
- Nadpisz rejestrację natywnych poleceń Skills per kanał przez `channels..commands.nativeSkills`.
- `channels.telegram.customCommands` dodaje dodatkowe wpisy menu bota Telegram.
- `bash: true` włącza `! ` dla powłoki hosta. Wymaga `tools.elevated.enabled` oraz nadawcy w `tools.elevated.allowFrom.`.
-- `config: true` włącza `/config` (odczyt/zapis `openclaw.json`). Dla klientów bramy `chat.send` trwałe zapisy `/config set|unset` wymagają także `operator.admin`; tylko do odczytu `/config show` pozostaje dostępne dla zwykłych klientów operatora z zakresem zapisu.
-- `mcp: true` włącza `/mcp` dla konfiguracji serwerów MCP zarządzanych przez OpenClaw w `mcp.servers`.
-- `plugins: true` włącza `/plugins` dla wykrywania wtyczek, instalacji oraz sterowania włączaniem/wyłączaniem.
-- `channels..configWrites` kontroluje mutacje konfiguracji per kanał (domyślnie: true).
-- Dla kanałów wielokontowych `channels..accounts..configWrites` również kontroluje zapisy kierowane do tego konta (na przykład `/allowlist --config --account ` albo `/config set channels..accounts....`).
+- `config: true` włącza `/config` (odczytuje/zapisuje `openclaw.json`). Dla klientów bramy `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.
+- `mcp: true` włącza `/mcp` dla zarządzanej przez OpenClaw konfiguracji serwera MCP w `mcp.servers`.
+- `plugins: true` włącza `/plugins` dla wykrywania pluginów, instalacji oraz sterowania włączaniem/wyłączaniem.
+- `channels..configWrites` steruje możliwością mutacji konfiguracji per kanał (domyślnie: true).
+- Dla kanałów wielokontowych `channels..accounts..configWrites` również steruje zapisami ukierunkowanymi na to konto (na przykład `/allowlist --config --account ` lub `/config set channels..accounts....`).
- `restart: false` wyłącza `/restart` i działania narzędzia restartu bramy. Domyślnie: `true`.
-- `ownerAllowFrom` to jawna lista dozwolonych właścicieli dla poleceń/narzędzi tylko dla właściciela. Jest oddzielna od `allowFrom`.
-- `ownerDisplay: "hash"` hashuje identyfikatory właścicieli w system prompt. Ustaw `ownerDisplaySecret`, aby kontrolować hashowanie.
-- `allowFrom` jest per dostawca. Gdy jest ustawione, jest **jedynym** źródłem autoryzacji (listy dozwolonych/parowanie kanału i `useAccessGroups` są ignorowane).
+- `ownerAllowFrom` to jawna lista zezwoleń właściciela dla poleceń/narzędzi tylko dla właściciela. Jest oddzielna od `allowFrom`.
+- `ownerDisplay: "hash"` hashuje identyfikatory właściciela w system prompt. Ustaw `ownerDisplaySecret`, aby sterować hashowaniem.
+- `allowFrom` jest per dostawca. Gdy jest ustawione, jest **jedynym** źródłem autoryzacji (listy zezwoleń/parowanie kanałów i `useAccessGroups` są ignorowane).
- `useAccessGroups: false` pozwala poleceniom omijać zasady grup dostępu, gdy `allowFrom` nie jest ustawione.
- Mapa dokumentacji poleceń:
- - katalog wbudowany + pakietowy: [Polecenia Slash](/pl/tools/slash-commands)
+ - katalog wbudowany + bundlowany: [Polecenia ukośnikowe](/pl/tools/slash-commands)
- powierzchnie poleceń specyficzne dla kanałów: [Kanały](/pl/channels)
- polecenia QQ Bot: [QQ Bot](/pl/channels/qqbot)
- polecenia parowania: [Parowanie](/pl/channels/pairing)
@@ -906,7 +906,7 @@ Domyślnie: `~/.openclaw/workspace`.
### `agents.defaults.repoRoot`
-Opcjonalny katalog główny repozytorium wyświetlany w wierszu Runtime system prompt. Jeśli nie jest ustawiony, OpenClaw wykrywa go automatycznie, idąc w górę od workspace.
+Opcjonalny katalog główny repozytorium wyświetlany w linii Runtime system prompt. Jeśli nie jest ustawiony, OpenClaw wykrywa go automatycznie, przechodząc w górę od obszaru roboczego.
```json5
{
@@ -916,7 +916,7 @@ Opcjonalny katalog główny repozytorium wyświetlany w wierszu Runtime system p
### `agents.defaults.skills`
-Opcjonalna domyślna lista dozwolonych Skills dla agentów, które nie ustawiają
+Opcjonalna domyślna lista zezwoleń Skills dla agentów, które nie ustawiają
`agents.list[].skills`.
```json5
@@ -924,9 +924,9 @@ Opcjonalna domyślna lista dozwolonych Skills dla agentów, które nie ustawiaj
agents: {
defaults: { skills: ["github", "weather"] },
list: [
- { id: "writer" }, // dziedziczy github, weather
- { id: "docs", skills: ["docs-search"] }, // zastępuje wartości domyślne
- { id: "locked-down", skills: [] }, // bez Skills
+ { id: "writer" }, // inherits github, weather
+ { id: "docs", skills: ["docs-search"] }, // replaces defaults
+ { id: "locked-down", skills: [] }, // no skills
],
},
}
@@ -935,12 +935,12 @@ Opcjonalna domyślna lista dozwolonych Skills dla agentów, które nie ustawiaj
- Pomiń `agents.defaults.skills`, aby domyślnie nie ograniczać Skills.
- Pomiń `agents.list[].skills`, aby dziedziczyć wartości domyślne.
- Ustaw `agents.list[].skills: []`, aby nie mieć żadnych Skills.
-- Niepusta lista `agents.list[].skills` jest końcowym zestawem dla tego agenta; nie
+- Niepusta lista `agents.list[].skills` jest ostatecznym zestawem dla tego agenta; nie
łączy się z wartościami domyślnymi.
### `agents.defaults.skipBootstrap`
-Wyłącza automatyczne tworzenie plików bootstrap workspace (`AGENTS.md`, `SOUL.md`, `TOOLS.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md`, `BOOTSTRAP.md`).
+Wyłącza automatyczne tworzenie plików bootstrap obszaru roboczego (`AGENTS.md`, `SOUL.md`, `TOOLS.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md`, `BOOTSTRAP.md`).
```json5
{
@@ -950,9 +950,9 @@ Wyłącza automatyczne tworzenie plików bootstrap workspace (`AGENTS.md`, `SOUL
### `agents.defaults.contextInjection`
-Steruje tym, kiedy pliki bootstrap workspace są wstrzykiwane do system prompt. Domyślnie: `"always"`.
+Steruje tym, kiedy pliki bootstrap obszaru roboczego są wstrzykiwane do system prompt. Domyślnie: `"always"`.
-- `"continuation-skip"`: bezpieczne tury kontynuacji (po ukończonej odpowiedzi asystenta) pomijają ponowne wstrzyknięcie bootstrap workspace, zmniejszając rozmiar prompt. Uruchomienia heartbeat i ponowne próby po kompaktowaniu nadal odbudowują kontekst.
+- `"continuation-skip"`: bezpieczne tury kontynuacji (po ukończonej odpowiedzi asystenta) pomijają ponowne wstrzyknięcie bootstrap obszaru roboczego, zmniejszając rozmiar prompt. Przebiegi heartbeat i ponowne próby po kompaktowaniu nadal odbudowują kontekst.
```json5
{
@@ -962,7 +962,7 @@ Steruje tym, kiedy pliki bootstrap workspace są wstrzykiwane do system prompt.
### `agents.defaults.bootstrapMaxChars`
-Maksymalna liczba znaków na plik bootstrap workspace przed obcięciem. Domyślnie: `20000`.
+Maksymalna liczba znaków na plik bootstrap obszaru roboczego przed obcięciem. Domyślnie: `20000`.
```json5
{
@@ -972,7 +972,7 @@ Maksymalna liczba znaków na plik bootstrap workspace przed obcięciem. Domyśln
### `agents.defaults.bootstrapTotalMaxChars`
-Maksymalna łączna liczba znaków wstrzykiwanych przez wszystkie pliki bootstrap workspace. Domyślnie: `150000`.
+Maksymalna łączna liczba znaków wstrzykiwanych we wszystkich plikach bootstrap obszaru roboczego. Domyślnie: `150000`.
```json5
{
@@ -982,11 +982,11 @@ Maksymalna łączna liczba znaków wstrzykiwanych przez wszystkie pliki bootstra
### `agents.defaults.bootstrapPromptTruncationWarning`
-Steruje widocznym dla agenta tekstem ostrzeżenia, gdy kontekst bootstrap zostanie obcięty.
+Steruje widocznym dla agenta tekstem ostrzeżenia, gdy kontekst bootstrap zostaje obcięty.
Domyślnie: `"once"`.
- `"off"`: nigdy nie wstrzykuje tekstu ostrzeżenia do system prompt.
-- `"once"`: wstrzykuje ostrzeżenie raz dla każdego unikalnego podpisu obcięcia (zalecane).
+- `"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.
```json5
@@ -997,7 +997,7 @@ Domyślnie: `"once"`.
### `agents.defaults.imageMaxDimensionPx`
-Maksymalny rozmiar w pikselach dla dłuższego boku obrazu w blokach obrazu transkryptu/narzędzia przed wywołaniami dostawcy.
+Maksymalny rozmiar w pikselach dla dłuższego boku obrazu w blokach obrazu transkryptu/narzędzi przed wywołaniami dostawcy.
Domyślnie: `1200`.
Niższe wartości zwykle zmniejszają użycie vision tokenów i rozmiar ładunku żądania w przebiegach z dużą liczbą zrzutów ekranu.
@@ -1011,7 +1011,7 @@ Wyższe wartości zachowują więcej szczegółów wizualnych.
### `agents.defaults.userTimezone`
-Strefa czasowa dla kontekstu system prompt (nie znaczników czasu wiadomości). Wartością zapasową jest strefa czasowa hosta.
+Strefa czasowa dla kontekstu system prompt (nie dla znaczników czasu wiadomości). Wartość zapasowa to strefa czasowa hosta.
```json5
{
@@ -1083,43 +1083,43 @@ Format czasu w system prompt. Domyślnie: `auto` (preferencja systemu operacyjne
- Forma obiektu ustawia model główny oraz uporządkowane modele 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 także jako routing zapasowy, gdy wybrany/domyyślny model nie obsługuje wejścia obrazu.
+ - Używany także jako routing zapasowy, gdy wybrany/domyslny model nie może przyjmować danych wejściowych obrazu.
- `imageGenerationModel`: akceptuje albo ciąg (`"provider/model"`), albo obiekt (`{ primary, fallbacks }`).
- - Używany przez współdzieloną funkcję generowania obrazów oraz każdą przyszłą powierzchnię narzędzia/wtyczki, która generuje obrazy.
- - Typowe wartości: `google/gemini-3.1-flash-image-preview` dla natywnego generowania obrazów Gemini, `fal/fal-ai/flux/dev` dla fal albo `openai/gpt-image-1` dla OpenAI Images.
- - Jeśli wybierzesz bezpośrednio dostawcę/model, skonfiguruj też pasujące uwierzytelnianie/klucz API dostawcy (na przykład `GEMINI_API_KEY` lub `GOOGLE_API_KEY` dla `google/*`, `OPENAI_API_KEY` dla `openai/*`, `FAL_KEY` dla `fal/*`).
- - Jeśli pominięte, `image_generate` nadal może wywnioskować wartość domyślną dostawcy na podstawie uwierzytelniania. Najpierw próbuje bieżącego domyślnego dostawcy, a następnie pozostałych zarejestrowanych dostawców generowania obrazów w kolejności id dostawcy.
+ - Używany przez współdzieloną funkcję generowania obrazów oraz każdą przyszłą powierzchnię narzędzia/pluginu generującą obrazy.
+ - Typowe wartości: `google/gemini-3.1-flash-image-preview` dla natywnego generowania obrazów Gemini, `fal/fal-ai/flux/dev` dla fal lub `openai/gpt-image-1` dla OpenAI Images.
+ - Jeśli wybierzesz bezpośrednio dostawcę/model, skonfiguruj także pasujące uwierzytelnianie/klucz API dostawcy (na przykład `GEMINI_API_KEY` lub `GOOGLE_API_KEY` dla `google/*`, `OPENAI_API_KEY` dla `openai/*`, `FAL_KEY` dla `fal/*`).
+ - Jeśli pominięte, `image_generate` nadal może wywnioskować domyślny dostawca oparty na uwierzytelnieniu. 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ą funkcję generowania muzyki oraz wbudowane narzędzie `music_generate`.
- - Typowe wartości: `google/lyria-3-clip-preview`, `google/lyria-3-pro-preview` albo `minimax/music-2.5+`.
- - Jeśli pominięte, `music_generate` nadal może wywnioskować wartość domyślną dostawcy na podstawie uwierzytelniania. Najpierw próbuje bieżącego domyślnego dostawcy, a następnie pozostałych zarejestrowanych dostawców generowania muzyki w kolejności id dostawcy.
- - Jeśli wybierzesz bezpośrednio dostawcę/model, skonfiguruj też pasujące uwierzytelnianie/klucz API dostawcy.
+ - Typowe wartości: `google/lyria-3-clip-preview`, `google/lyria-3-pro-preview` lub `minimax/music-2.5+`.
+ - Jeśli pominięte, `music_generate` nadal może wywnioskować domyślny dostawca oparty na uwierzytelnieniu. 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 także pasujące uwierzytelnianie/klucz API dostawcy.
- `videoGenerationModel`: akceptuje albo ciąg (`"provider/model"`), albo obiekt (`{ primary, fallbacks }`).
- Używany przez współdzieloną funkcję generowania wideo oraz wbudowane narzędzie `video_generate`.
- - Typowe wartości: `qwen/wan2.6-t2v`, `qwen/wan2.6-i2v`, `qwen/wan2.6-r2v`, `qwen/wan2.6-r2v-flash` albo `qwen/wan2.7-r2v`.
- - Jeśli pominięte, `video_generate` nadal może wywnioskować wartość domyślną dostawcy na podstawie uwierzytelniania. Najpierw próbuje bieżącego domyślnego dostawcy, a następnie pozostałych zarejestrowanych dostawców generowania wideo w kolejności id dostawcy.
- - Jeśli wybierzesz bezpośrednio dostawcę/model, skonfiguruj też pasujące uwierzytelnianie/klucz API dostawcy.
- - Pakietowy dostawca generowania wideo Qwen obsługuje maksymalnie 1 wyjściowe wideo, 1 wejściowy obraz, 4 wejściowe filmy, czas trwania 10 sekund oraz opcje na poziomie dostawcy `size`, `aspectRatio`, `resolution`, `audio` i `watermark`.
+ - Typowe wartości: `qwen/wan2.6-t2v`, `qwen/wan2.6-i2v`, `qwen/wan2.6-r2v`, `qwen/wan2.6-r2v-flash` lub `qwen/wan2.7-r2v`.
+ - Jeśli pominięte, `video_generate` nadal może wywnioskować domyślny dostawca oparty na uwierzytelnieniu. 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 także pasujące uwierzytelnianie/klucz API dostawcy.
+ - Bundlowany dostawca generowania wideo Qwen obsługuje maksymalnie 1 wyjściowe wideo, 1 wejściowy obraz, 4 wejściowe wideo, czas trwania do 10 sekund oraz opcje na poziomie 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ęty, narzędzie PDF wraca do `imageModel`, a następnie do rozwiązanego modelu sesji/domyyślnego.
+ - Jeśli pominięty, narzędzie PDF używa wartości zapasowej z `imageModel`, a następnie z rozstrzygniętego modelu sesji/domyslnego.
- `pdfMaxBytesMb`: domyślny limit rozmiaru PDF dla narzędzia `pdf`, gdy `maxBytesMb` nie jest przekazane w czasie wywołania.
-- `pdfMaxPages`: domyślna maksymalna liczba stron uwzględnianych przez tryb ekstrakcji zapasowej w narzędziu `pdf`.
+- `pdfMaxPages`: domyślna maksymalna liczba stron uwzględnianych przez tryb zapasowy ekstrakcji w narzędziu `pdf`.
- `verboseDefault`: domyślny poziom verbose dla agentów. Wartości: `"off"`, `"on"`, `"full"`. Domyślnie: `"off"`.
-- `elevatedDefault`: domyślny poziom elevated output dla agentów. Wartości: `"off"`, `"on"`, `"ask"`, `"full"`. Domyślnie: `"on"`.
-- `model.primary`: format `provider/model` (np. `openai/gpt-5.4`). Jeśli pominiesz dostawcę, OpenClaw najpierw próbuje aliasu, potem unikalnego dopasowania dokładnego id modelu wśród skonfigurowanych dostawców, a dopiero potem wraca do skonfigurowanego dostawcy domyślnego (przestarzałe zachowanie zgodności, więc preferuj jawne `provider/model`). Jeśli ten dostawca nie udostępnia już skonfigurowanego modelu domyślnego, OpenClaw wraca do pierwszego skonfigurowanego dostawcy/modelu zamiast ujawniać nieaktualną wartość domyślną usuniętego dostawcy.
-- `models`: skonfigurowany katalog modeli i lista dozwolonych dla `/model`. Każdy wpis może zawierać `alias` (skrót) i `params` (specyficzne dla dostawcy, na przykład `temperature`, `maxTokens`, `cacheRetention`, `context1m`).
+- `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ładnie tego identyfikatora modelu, a dopiero potem wraca do skonfigurowanego domyślnego dostawcy (przestarzałe zachowanie zgodności, więc preferuj jawne `provider/model`). Jeśli ten dostawca nie udostępnia już skonfigurowanego modelu domyślnego, OpenClaw wraca do pierwszego skonfigurowanego dostawcy/modelu zamiast ujawniać nieaktualną wartość domyślną usuniętego dostawcy.
+- `models`: skonfigurowany katalog modeli i lista zezwoleń dla `/model`. Każdy wpis może zawierać `alias` (skrót) i `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 następnie `agents.list[].params` (pasujące id agenta) nadpisuje po kluczu. Szczegóły znajdziesz w [Prompt Caching](/pl/reference/prompt-caching).
-- `embeddedHarness`: domyślna niskopoziomowa polityka runtime dla osadzonego agenta. Użyj `runtime: "auto"`, aby zarejestrowane plugin harnesses mogły przejmować obsługiwane modele, `runtime: "pi"`, aby wymusić wbudowany harness PI, albo zarejestrowanego id harnessu, takiego jak `runtime: "codex"`. Ustaw `fallback: "none"`, aby wyłączyć automatyczny zapasowy fallback do PI.
-- Programy zapisujące konfigurację, które mutują te pola (na przykład `/models set`, `/models set-image` oraz polecenia dodawania/usuwania fallbacków), zapisują kanoniczną formę obiektową i zachowują istniejące listy fallbacków, gdy to możliwe.
+- Priorytet scalania `params` (konfiguracja): `agents.defaults.params` (globalna baza) jest nadpisywane przez `agents.defaults.models["provider/model"].params` (per model), a następnie `agents.list[].params` (pasujący identyfikator agenta) nadpisuje po kluczu. Szczegóły znajdziesz w [Prompt Caching](/pl/reference/prompt-caching).
+- `embeddedHarness`: domyślna polityka runtime dla niskopoziomowego osadzonego agenta. Użyj `runtime: "auto"`, aby zarejestrowane harnessy pluginów mogły przejmować obsługę wspieranych modeli, `runtime: "pi"`, aby wymusić wbudowany harness PI, albo zarejestrowanego identyfikatora harnessu, takiego jak `runtime: "codex"`. Ustaw `fallback: "none"`, aby wyłączyć automatyczny fallback do PI.
+- Narzędzia zapisujące konfigurację, które mutują te pola (na przykład `/models set`, `/models set-image` oraz polecenia dodawania/usuwania fallbacków), zapisują kanoniczną formę obiektu i w miarę możliwości zachowują istniejące listy fallbacków.
- `maxConcurrent`: maksymalna liczba równoległych uruchomień agentów między sesjami (każda sesja nadal jest serializowana). Domyślnie: 4.
### `agents.defaults.embeddedHarness`
-`embeddedHarness` steruje, który niskopoziomowy executor uruchamia osadzone tury agenta.
-W większości wdrożeń należy pozostawić wartość domyślną `{ runtime: "auto", fallback: "pi" }`.
-Użyj tego, gdy zaufana wtyczka udostępnia natywny harness, taki jak pakietowy
+`embeddedHarness` steruje tym, który niskopoziomowy executor uruchamia tury osadzonego agenta.
+W większości wdrożeń należy pozostawić domyślną wartość `{ runtime: "auto", fallback: "pi" }`.
+Użyj tego, gdy zaufany plugin udostępnia natywny harness, taki jak bundlowany
harness serwera aplikacji Codex.
```json5
@@ -1136,11 +1136,11 @@ harness serwera aplikacji Codex.
}
```
-- `runtime`: `"auto"`, `"pi"` albo id zarejestrowanego plugin harness. Pakietowa wtyczka Codex rejestruje `codex`.
-- `fallback`: `"pi"` albo `"none"`. `"pi"` zachowuje wbudowany harness PI jako fallback zgodności. `"none"` powoduje błąd przy brakującym lub nieobsługiwanym wyborze plugin harness zamiast cichego użycia PI.
-- Nadpisania środowiskowe: `OPENCLAW_AGENT_RUNTIME=` nadpisuje `runtime`; `OPENCLAW_AGENT_HARNESS_FALLBACK=none` wyłącza fallback do PI dla tego procesu.
-- Dla wdrożeń tylko z Codex ustaw `model: "codex/gpt-5.4"`, `embeddedHarness.runtime: "codex"` i `embeddedHarness.fallback: "none"`.
-- To steruje tylko osadzonym chat harness. Generowanie mediów, vision, PDF, muzyka, wideo i TTS nadal używają swoich ustawień dostawcy/modelu.
+- `runtime`: `"auto"`, `"pi"` lub identyfikator zarejestrowanego harnessu pluginu. Bundlowany plugin Codex rejestruje `codex`.
+- `fallback`: `"pi"` lub `"none"`. `"pi"` zachowuje wbudowany harness PI jako fallback zgodności. `"none"` powoduje, że brakujący lub niewspierany wybór harnessu pluginu kończy się błędem zamiast cichego użycia PI.
+- Nadpisania przez zmienne środowiskowe: `OPENCLAW_AGENT_RUNTIME=` nadpisuje `runtime`; `OPENCLAW_AGENT_HARNESS_FALLBACK=none` wyłącza fallback do PI dla tego procesu.
+- Dla wdrożeń tylko z Codex ustaw `model: "codex/gpt-5.4"`, `embeddedHarness.runtime: "codex"` oraz `embeddedHarness.fallback: "none"`.
+- To steruje wyłącznie osadzonym harness chat. Generowanie mediów, vision, PDF, muzyki, wideo i TTS nadal używają własnych ustawień dostawcy/modelu.
**Wbudowane skróty aliasów** (mają zastosowanie tylko wtedy, gdy model znajduje się w `agents.defaults.models`):
@@ -1155,15 +1155,15 @@ harness serwera aplikacji Codex.
| `gemini-flash` | `google/gemini-3-flash-preview` |
| `gemini-flash-lite` | `google/gemini-3.1-flash-lite-preview` |
-Skonfigurowane przez Ciebie aliasy zawsze mają pierwszeństwo przed domyślnymi.
+Twoje skonfigurowane aliasy zawsze mają pierwszeństwo przed domyślnymi.
-Modele Z.AI GLM-4.x automatycznie włączają tryb thinking, chyba że ustawisz `--thinking off` albo samodzielnie zdefiniujesz `agents.defaults.models["zai/"].params.thinking`.
+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 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ą `adaptive` thinking, gdy nie ustawiono jawnego poziomu thinking.
+Modele Anthropic Claude 4.6 domyślnie używają thinking `adaptive`, gdy nie ustawiono jawnego poziomu thinking.
### `agents.defaults.cliBackends`
-Opcjonalne backendy CLI dla tekstowych uruchomień zapasowych (bez wywołań narzędzi). Przydatne jako kopia zapasowa, gdy dostawcy API zawodzą.
+Opcjonalne backendy CLI dla zapasowych uruchomień tylko tekstowych (bez wywołań narzędzi). Przydatne jako kopia zapasowa, gdy zawodzą dostawcy API.
```json5
{
@@ -1197,7 +1197,7 @@ Opcjonalne backendy CLI dla tekstowych uruchomień zapasowych (bez wywołań nar
### `agents.defaults.systemPromptOverride`
-Zastępuje cały system prompt złożony przez OpenClaw stałym ciągiem. Ustawiane na poziomie domyślnym (`agents.defaults.systemPromptOverride`) albo per agent (`agents.list[].systemPromptOverride`). Wartości per agent mają pierwszeństwo; wartość pusta lub zawierająca tylko białe znaki jest ignorowana. Przydatne do kontrolowanych eksperymentów z promptami.
+Zastępuje cały system prompt złożony przez OpenClaw stałym ciągiem. Ustawiane na poziomie domyślnym (`agents.defaults.systemPromptOverride`) lub per agent (`agents.list[].systemPromptOverride`). Wartości per agent mają pierwszeństwo; pusta wartość lub wartość zawierająca wyłącznie białe znaki jest ignorowana. Przydatne do kontrolowanych eksperymentów z promptami.
```json5
{
@@ -1211,7 +1211,7 @@ Zastępuje cały system prompt złożony przez OpenClaw stałym ciągiem. Ustawi
### `agents.defaults.heartbeat`
-Okresowe uruchomienia heartbeat.
+Okresowe przebiegi heartbeat.
```json5
{
@@ -1238,15 +1238,15 @@ Okresowe uruchomienia heartbeat.
}
```
-- `every`: ciąg czasu trwania (ms/s/m/h). Domyślnie: `30m` (uwierzytelnianie kluczem API) albo `1h` (uwierzytelnianie OAuth). Ustaw `0m`, aby wyłączyć.
-- `includeSystemPromptSection`: gdy false, pomija sekcję Heartbeat w system prompt i pomija wstrzykiwanie `HEARTBEAT.md` do kontekstu bootstrap. Domyślnie: `true`.
-- `suppressToolErrorWarnings`: gdy true, wycisza ładunki ostrzeżeń o błędach narzędzi podczas uruchomień heartbeat.
-- `timeoutSeconds`: maksymalny czas w sekundach dozwolony dla tury agenta heartbeat, po którym zostaje przerwana. Pozostaw nieustawione, aby użyć `agents.defaults.timeoutSeconds`.
-- `directPolicy`: zasada dostarczania bezpośredniego/DM. `allow` (domyślnie) zezwala na dostarczanie do celu bezpośredniego. `block` blokuje dostarczanie do celu bezpośredniego i emituje `reason=dm-blocked`.
-- `lightContext`: gdy true, uruchomienia heartbeat używają lekkiego kontekstu bootstrap i zachowują tylko `HEARTBEAT.md` z plików bootstrap workspace.
-- `isolatedSession`: gdy true, każde uruchomienie heartbeat działa w świeżej sesji bez wcześniejszej historii rozmowy. Ten sam wzorzec izolacji co cron `sessionTarget: "isolated"`. Zmniejsza koszt tokenów per heartbeat z około 100K do około 2-5K tokenów.
-- Per agent: ustaw `agents.list[].heartbeat`. Gdy dowolny agent definiuje `heartbeat`, heartbeat uruchamiają **tylko ci agenci**.
-- Heartbeat uruchamia pełne tury agenta — krótsze interwały zużywają więcej tokenów.
+- `every`: ciąg czasu trwania (ms/s/m/h). Domyślnie: `30m` (uwierzytelnianie kluczem API) lub `1h` (uwierzytelnianie OAuth). Ustaw `0m`, aby wyłączyć.
+- `includeSystemPromptSection`: gdy `false`, pomija sekcję Heartbeat w system prompt i pomija wstrzykiwanie `HEARTBEAT.md` do kontekstu bootstrap. Domyślnie: `true`.
+- `suppressToolErrorWarnings`: gdy `true`, tłumi ładunki ostrzeżeń o błędach narzędzi podczas przebiegów heartbeat.
+- `timeoutSeconds`: maksymalny czas w sekundach dozwolony dla tury agenta heartbeat, po którym zostaje ona przerwana. Pozostaw nieustawione, aby użyć `agents.defaults.timeoutSeconds`.
+- `directPolicy`: zasada dostarczania bezpośredniego/DM. `allow` (domyślnie) zezwala na dostarczanie do celu bezpośredniego. `block` tłumi takie dostarczanie i emituje `reason=dm-blocked`.
+- `lightContext`: gdy `true`, przebiegi heartbeat używają lekkiego kontekstu bootstrap i zachowują tylko `HEARTBEAT.md` z plików bootstrap obszaru roboczego.
+- `isolatedSession`: gdy `true`, każdy przebieg heartbeat działa w świeżej sesji bez wcześniejszej historii konwersacji. Taki sam wzorzec izolacji jak cron `sessionTarget: "isolated"`. Zmniejsza koszt tokenów per heartbeat z około 100K do około 2-5K tokenów.
+- Per agent: ustaw `agents.list[].heartbeat`. Gdy dowolny agent definiuje `heartbeat`, **tylko ci agenci** uruchamiają heartbeat.
+- Heartbeat wykonuje pełne tury agenta — krótsze interwały zużywają więcej tokenów.
### `agents.defaults.compaction`
@@ -1276,19 +1276,19 @@ Okresowe uruchomienia heartbeat.
}
```
-- `mode`: `default` albo `safeguard` (segmentowe podsumowywanie dla długich historii). Zobacz [Compaction](/pl/concepts/compaction).
-- `provider`: id zarejestrowanej wtyczki dostawcy compaction. Gdy jest ustawione, wywoływane jest `summarize()` dostawcy zamiast wbudowanego podsumowywania przez LLM. W razie niepowodzenia wraca do wbudowanego rozwiązania. Ustawienie dostawcy wymusza `mode: "safeguard"`. Zobacz [Compaction](/pl/concepts/compaction).
+- `mode`: `default` lub `safeguard` (podzielone na części podsumowywanie dla długich historii). Zobacz [Compaction](/pl/concepts/compaction).
+- `provider`: identyfikator zarejestrowanego pluginu dostawcy compaction. Gdy jest ustawiony, wywoływane jest `summarize()` dostawcy zamiast wbudowanego podsumowywania przez LLM. W razie błędu wraca do wbudowanego mechanizmu. Ustawienie dostawcy wymusza `mode: "safeguard"`. Zobacz [Compaction](/pl/concepts/compaction).
- `timeoutSeconds`: maksymalna liczba sekund dozwolona dla pojedynczej operacji compaction, po której OpenClaw ją przerywa. Domyślnie: `900`.
-- `identifierPolicy`: `strict` (domyślnie), `off` albo `custom`. `strict` dodaje na początku wbudowane wskazówki zachowania nieprzezroczystych identyfikatorów podczas podsumowywania compaction.
-- `identifierInstructions`: opcjonalny własny tekst zachowania identyfikatorów używany, gdy `identifierPolicy=custom`.
-- `postCompactionSections`: opcjonalne nazwy sekcji H2/H3 z AGENTS.md do ponownego wstrzyknięcia po compaction. Domyślnie `["Session Startup", "Red Lines"]`; ustaw `[]`, aby wyłączyć ponowne wstrzyknięcie. Gdy nieustawione albo jawnie ustawione na tę domyślną parę, starsze nagłówki `Every Session`/`Safety` są również akceptowane jako starszy fallback.
-- `model`: opcjonalne nadpisanie `provider/model-id` tylko dla podsumowywania compaction. Użyj tego, gdy główna sesja ma pozostać przy jednym modelu, ale podsumowania compaction mają działać na innym; gdy nieustawione, compaction używa głównego modelu sesji.
-- `notifyUser`: gdy `true`, wysyła krótkie powiadomienie do użytkownika, gdy rozpoczyna się compaction (na przykład „Kompaktowanie kontekstu...”). Domyślnie wyłączone, aby compaction pozostawał cichy.
-- `memoryFlush`: cicha, agentowa tura przed automatycznym compaction w celu zapisania trwałych wspomnień. Pomijana, gdy workspace jest tylko do odczytu.
+- `identifierPolicy`: `strict` (domyślnie), `off` lub `custom`. `strict` dodaje na początku wbudowane wskazówki zachowania nieprzezroczystych identyfikatorów podczas podsumowywania compaction.
+- `identifierInstructions`: opcjonalny własny tekst dotyczący zachowania identyfikatorów, używany przy `identifierPolicy=custom`.
+- `postCompactionSections`: opcjonalne nazwy sekcji H2/H3 z AGENTS.md do ponownego wstrzyknięcia po compaction. Domyślnie `["Session Startup", "Red Lines"]`; ustaw `[]`, aby wyłączyć ponowne wstrzyknięcie. Gdy nie jest ustawione lub jest jawnie ustawione na tę domyślną parę, starsze nagłówki `Every Session`/`Safety` są również akceptowane jako zapasowe rozwiązanie dla starszych wersji.
+- `model`: opcjonalne nadpisanie `provider/model-id` tylko dla podsumowywania compaction. Użyj tego, gdy główna sesja ma pozostać przy jednym modelu, ale podsumowania compaction powinny działać na innym; gdy nie jest ustawione, compaction używa modelu głównego sesji.
+- `notifyUser`: gdy `true`, wysyła krótkie powiadomienie do użytkownika przy rozpoczęciu compaction (na przykład „Kompaktowanie kontekstu...” ). Domyślnie wyłączone, aby compaction pozostawało ciche.
+- `memoryFlush`: cicha agentowa tura przed automatycznym compaction w celu zapisania trwałych wspomnień. Pomijane, gdy obszar roboczy 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.
+Usuwa z kontekstu w pamięci **stare wyniki narzędzi** przed wysłaniem do LLM. **Nie** modyfikuje historii sesji na dysku.
```json5
{
@@ -1313,12 +1313,12 @@ 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ć ponownie uruchomione (od ostatniego dotknięcia cache).
-- Przycinanie najpierw miękko przycina zbyt duże wyniki narzędzi, a następnie w razie potrzeby twardo czyści starsze wyniki narzędzi.
+- `ttl` steruje tym, jak często przycinanie może zostać ponownie uruchomione (od ostatniego dotknięcia pamięci podręcznej).
+- Przycinanie najpierw miękko przycina zbyt duże wyniki narzędzi, a następnie w razie potrzeby całkowicie czyści starsze wyniki narzędzi.
-**Miękkie przycinanie** zachowuje początek i koniec oraz wstawia `...` pośrodku.
+**Soft-trim** zachowuje początek i koniec oraz wstawia `...` w środku.
-**Twarde czyszczenie** zastępuje cały wynik narzędzia placeholderem.
+**Hard-clear** zastępuje cały wynik narzędzia placeholderem.
Uwagi:
@@ -1328,7 +1328,7 @@ Uwagi:
-Szczegóły zachowania znajdziesz w [Przycinanie sesji](/pl/concepts/session-pruning).
+Szczegóły zachowania znajdziesz w [Session Pruning](/pl/concepts/session-pruning).
### Strumieniowanie blokowe
@@ -1347,10 +1347,10 @@ Szczegóły zachowania znajdziesz w [Przycinanie sesji](/pl/concepts/session-pru
```
- Kanały inne niż Telegram wymagają jawnego `*.blockStreaming: true`, aby włączyć odpowiedzi blokowe.
-- Nadpisania kanałów: `channels..blockStreamingCoalesce` (oraz warianty per konto). Signal/Slack/Discord/Google Chat domyślnie używają `minChars: 1500`.
+- Nadpisania per kanał: `channels..blockStreamingCoalesce` (oraz warianty per konto). Signal/Slack/Discord/Google Chat domyślnie używają `minChars: 1500`.
- `humanDelay`: losowa pauza między odpowiedziami blokowymi. `natural` = 800–2500 ms. Nadpisanie per agent: `agents.list[].humanDelay`.
-Szczegóły zachowania i segmentowania znajdziesz w [Streaming](/pl/concepts/streaming).
+Szczegóły zachowania i dzielenia na części znajdziesz w [Streaming](/pl/concepts/streaming).
### Wskaźniki pisania
@@ -1365,16 +1365,16 @@ Szczegóły zachowania i segmentowania znajdziesz w [Streaming](/pl/concepts/str
}
```
-- Domyślnie: `instant` dla czatów bezpośrednich/wzmianek, `message` dla grupowych czatów bez wzmianki.
+- Domyślnie: `instant` dla czatów bezpośrednich/wzmianek, `message` dla niewzmiankowanych 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).
### `agents.defaults.sandbox`
-Opcjonalne sandboxing dla osadzonego agenta. Pełny przewodnik znajdziesz w [Sandboxing](/pl/gateway/sandboxing).
+Opcjonalny sandboxing dla osadzonego agenta. Pełny przewodnik znajdziesz w [Sandboxing](/pl/gateway/sandboxing).
```json5
{
@@ -1477,16 +1477,16 @@ Opcjonalne sandboxing dla osadzonego agenta. Pełny przewodnik znajdziesz w [San
- `ssh`: ogólny zdalny runtime oparty na SSH
- `openshell`: runtime OpenShell
-Gdy wybrane jest `backend: "openshell"`, ustawienia specyficzne dla runtime przenoszą się do
+Gdy wybrane jest `backend: "openshell"`, ustawienia specyficzne dla runtime są przenoszone do
`plugins.entries.openshell.config`.
**Konfiguracja backendu SSH:**
-- `target`: cel SSH w formacie `user@host[:port]`
+- `target`: cel SSH w formie `user@host[:port]`
- `command`: polecenie klienta SSH (domyślnie: `ssh`)
-- `workspaceRoot`: bezwzględny zdalny katalog główny używany dla workspace per zakres
+- `workspaceRoot`: bezwzględny zdalny katalog główny używany dla obszarów roboczych per zakres
- `identityFile` / `certificateFile` / `knownHostsFile`: istniejące lokalne pliki przekazywane do OpenSSH
-- `identityData` / `certificateData` / `knownHostsData`: zawartość inline albo SecretRef, które OpenClaw materializuje do plików tymczasowych w czasie działania
+- `identityData` / `certificateData` / `knownHostsData`: zawartości inline lub SecretRefs, które OpenClaw materializuje do plików tymczasowych w runtime
- `strictHostKeyChecking` / `updateHostKeys`: ustawienia zasad kluczy hosta OpenSSH
**Priorytet uwierzytelniania SSH:**
@@ -1494,29 +1494,29 @@ Gdy wybrane jest `backend: "openshell"`, ustawienia specyficzne dla runtime prze
- `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 runtime sekretów przed uruchomieniem sesji sandbox
**Zachowanie backendu SSH:**
-- inicjalizuje zdalny workspace raz po utworzeniu lub odtworzeniu
-- następnie utrzymuje zdalny workspace SSH jako kanoniczny
-- prowadzi `exec`, narzędzia plikowe i ścieżki mediów przez SSH
-- nie synchronizuje automatycznie zdalnych zmian z powrotem na hosta
+- inicjalizuje zdalny obszar roboczy raz po utworzeniu lub odtworzeniu
+- następnie utrzymuje zdalny obszar roboczy SSH jako kanoniczny
+- kieruje `exec`, narzędzia plikowe i ścieżki mediów przez SSH
+- nie synchronizuje automatycznie zdalnych zmian z powrotem do hosta
- nie obsługuje kontenerów przeglądarki sandbox
-**Dostęp do workspace:**
+**Dostęp do obszaru roboczego:**
-- `none`: workspace sandbox per zakres w `~/.openclaw/sandboxes`
-- `ro`: workspace sandbox w `/workspace`, workspace agenta montowany tylko do odczytu w `/agent`
-- `rw`: workspace agenta montowany do odczytu i zapisu w `/workspace`
+- `none`: obszar roboczy sandbox per zakres w `~/.openclaw/sandboxes`
+- `ro`: obszar roboczy sandbox w `/workspace`, obszar roboczy agenta montowany tylko do odczytu w `/agent`
+- `rw`: obszar roboczy agenta montowany do odczytu i zapisu w `/workspace`
**Zakres:**
-- `session`: kontener + workspace per sesja
-- `agent`: jeden kontener + workspace na agenta (domyślnie)
-- `shared`: współdzielony kontener i workspace (brak izolacji między sesjami)
+- `session`: kontener + obszar roboczy per sesja
+- `agent`: jeden kontener + obszar roboczy per agent (domyślnie)
+- `shared`: współdzielony kontener i obszar roboczy (bez izolacji między sesjami)
-**Konfiguracja wtyczki OpenShell:**
+**Konfiguracja pluginu OpenShell:**
```json5
{
@@ -1544,30 +1544,30 @@ Gdy wybrane jest `backend: "openshell"`, ustawienia specyficzne dla runtime prze
**Tryb OpenShell:**
-- `mirror`: inicjalizuje zdalne środowisko z lokalnego przed `exec`, synchronizuje z powrotem po `exec`; lokalny workspace pozostaje kanoniczny
-- `remote`: inicjalizuje zdalne środowisko raz przy tworzeniu sandbox, a następnie utrzymuje zdalny workspace jako kanoniczny
+- `mirror`: inicjalizuje zdalny katalog z lokalnego przed `exec`, synchronizuje z powrotem po `exec`; lokalny obszar roboczy pozostaje kanoniczny
+- `remote`: inicjalizuje zdalny katalog raz podczas tworzenia sandbox, a następnie utrzymuje zdalny obszar roboczy jako kanoniczny
-W trybie `remote` edycje lokalne hosta wykonane poza OpenClaw nie są automatycznie synchronizowane do sandbox po kroku inicjalizacji.
-Transport odbywa się przez SSH do sandbox OpenShell, ale wtyczka zarządza cyklem życia sandbox i opcjonalną synchronizacją mirror.
+W trybie `remote` lokalne edycje hosta wykonane poza OpenClaw nie są automatycznie synchronizowane do sandbox po kroku inicjalizacji.
+Transport odbywa się przez SSH do sandbox OpenShell, ale plugin zarządza cyklem życia sandbox oraz opcjonalną synchronizacją mirror.
-**`setupCommand`** uruchamia się raz po utworzeniu kontenera (przez `sh -lc`). Wymaga ruchu wychodzącego do sieci, zapisywalnego katalogu głównego i użytkownika root.
+**`setupCommand`** uruchamia się raz po utworzeniu kontenera (przez `sh -lc`). Wymaga wychodzącego ruchu sieciowego, zapisywalnego katalogu głównego 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` (tryb awaryjny).
+`sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true` (tryb break-glass).
-**Przychodzące załączniki** są umieszczane w `media/inbound/*` w aktywnym workspace.
+**Przychodzące załączniki** są umieszczane tymczasowo w `media/inbound/*` w aktywnym obszarze roboczym.
**`docker.binds`** montuje dodatkowe katalogi hosta; globalne i per-agent bindy są scalane.
-**Przeglądarka w sandbox** (`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).
+**Przeglądarka w sandboxie** (`sandbox.browser.enabled`): Chromium + CDP w kontenerze. URL noVNC jest wstrzykiwany do system prompt. Nie wymaga `browser.enabled` w `openclaw.json`.
+Dostęp obserwatora przez noVNC domyślnie używa uwierzytelniania VNC, a OpenClaw emituje krótko żyjący URL z tokenem (zamiast ujawniać hasło we współdzielonym URL).
-- `allowHostControl: false` (domyślnie) blokuje możliwość kierowania sesji sandbox do przeglądarki hosta.
+- `allowHostControl: false` (domyślnie) blokuje sesjom sandbox targetowanie 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 parametry uruchamiania są zdefiniowane w `scripts/sandbox-browser-entrypoint.sh` i dostrojone dla hostów kontenerowych:
+- 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=`
- `--user-data-dir=${HOME}/.chrome`
@@ -1586,22 +1586,22 @@ Dostęp obserwatora noVNC domyślnie używa uwierzytelniania VNC, a OpenClaw emi
- `--metrics-recording-only`
- `--disable-extensions` (domyślnie włączone)
- `--disable-3d-apis`, `--disable-software-rasterizer` i `--disable-gpu` są
- domyślnie włączone i mogą zostać wyłączone przez
+ 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
+ - `OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0` ponownie włącza rozszerzenia, jeśli twój workflow
od nich zależy.
- `--renderer-process-limit=2` można zmienić przez
`OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=`; ustaw `0`, aby użyć
domyślnego limitu procesów Chromium.
- - dodatkowo `--no-sandbox` i `--disable-setuid-sandbox`, gdy `noSandbox` jest włączone.
- - Wartości domyślne to bazowa konfiguracja obrazu kontenera; użyj własnego obrazu przeglądarki z własnym
- entrypoint, aby zmienić domyślne ustawienia kontenera.
+ - oraz `--no-sandbox` i `--disable-setuid-sandbox`, gdy włączone jest `noSandbox`.
+ - Wartości domyślne 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ą dostępne tylko dla Docker.
-Zbuduj obrazy:
+Budowanie obrazów:
```bash
scripts/sandbox-setup.sh # main sandbox image
@@ -1657,25 +1657,25 @@ scripts/sandbox-browser-setup.sh # optional browser image
}
```
-- `id`: stabilne id agenta (wymagane).
-- `default`: gdy ustawionych jest wiele, wygrywa pierwsze (zapisywane jest ostrzeżenie). Jeśli nie ustawiono żadnego, domyślny jest pierwszy wpis na liście.
+- `id`: stabilny identyfikator agenta (wymagany).
+- `default`: gdy ustawionych jest wiele, wygrywa pierwszy (zapisywane jest ostrzeżenie). Jeśli nie ustawiono żadnego, 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 ponad wybranym wpisem modelu w `agents.defaults.models`. Użyj tego do nadpisań specyficznych dla agenta, takich jak `cacheRetention`, `temperature` albo `maxTokens`, bez duplikowania całego katalogu modeli.
-- `skills`: opcjonalna lista dozwolonych Skills per agent. Jeśli pominięta, agent dziedziczy `agents.defaults.skills`, gdy jest ustawione; jawna lista zastępuje wartości domyślne zamiast się z nimi scalać, a `[]` oznacza brak Skills.
-- `thinkingDefault`: opcjonalny domyślny poziom thinking per agent (`off | minimal | low | medium | high | xhigh | adaptive`). Nadpisuje `agents.defaults.thinkingDefault` dla tego agenta, gdy nie ustawiono nadpisania per wiadomość lub per sesję.
-- `reasoningDefault`: opcjonalna domyślna widoczność reasoning per agent (`on | off | stream`). Ma zastosowanie, gdy nie ustawiono nadpisania reasoning per wiadomość lub per sesję.
-- `fastModeDefault`: opcjonalna domyślna wartość fast mode per agent (`true | false`). Ma zastosowanie, gdy nie ustawiono nadpisania fast mode per wiadomość lub per sesję.
-- `embeddedHarness`: opcjonalne nadpisanie niskopoziomowej polityki harness per agent. Użyj `{ runtime: "codex", fallback: "none" }`, aby jeden agent był tylko Codex, podczas gdy inne agenty zachowają domyślny fallback PI.
-- `runtime`: opcjonalny deskryptor runtime per agent. Użyj `type: "acp"` z domyślnymi wartościami `runtime.acp` (`agent`, `backend`, `mode`, `cwd`), gdy agent powinien domyślnie używać sesji harness ACP.
-- `identity.avatar`: ścieżka względna do workspace, URL `http(s)` albo URI `data:`.
+- `params`: parametry strumienia per agent, scalane ponad wybranym wpisem modelu w `agents.defaults.models`. Użyj tego do nadpisań specyficznych dla agenta, takich jak `cacheRetention`, `temperature` lub `maxTokens`, bez duplikowania całego katalogu modeli.
+- `skills`: opcjonalna lista zezwoleń 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 ustawiono nadpisania per wiadomość ani per sesja.
+- `reasoningDefault`: opcjonalna domyślna widoczność reasoning per agent (`on | off | stream`). Stosowane, gdy nie ustawiono nadpisania reasoning per wiadomość ani per sesja.
+- `fastModeDefault`: opcjonalna wartość domyślna trybu szybkiego per agent (`true | false`). Stosowane, gdy nie ustawiono nadpisania fast mode per wiadomość ani per sesja.
+- `embeddedHarness`: opcjonalne nadpisanie polityki niskopoziomowego harnessu per agent. Użyj `{ runtime: "codex", fallback: "none" }`, aby jeden agent był tylko Codex, podczas gdy inni zachowują domyślny fallback PI.
+- `runtime`: opcjonalny deskryptor runtime per agent. Użyj `type: "acp"` z wartościami domyślnymi `runtime.acp` (`agent`, `backend`, `mode`, `cwd`), gdy agent ma domyślnie używać sesji harness ACP.
+- `identity.avatar`: ścieżka względna wobec obszaru roboczego, URL `http(s)` lub URI `data:`.
- `identity` wyprowadza wartości domyślne: `ackReaction` z `emoji`, `mentionPatterns` z `name`/`emoji`.
-- `subagents.allowAgents`: lista dozwolonych id agentów dla `sessions_spawn` (`["*"]` = dowolny; domyślnie: tylko ten sam agent).
-- Zabezpieczenie dziedziczenia sandbox: jeśli sesja żądająca działa w sandbox, `sessions_spawn` odrzuca cele, które działałyby bez sandbox.
-- `subagents.requireAgentId`: gdy true, blokuje wywołania `sessions_spawn`, które pomijają `agentId` (wymusza jawny wybór profilu; domyślnie: false).
+- `subagents.allowAgents`: lista zezwoleń identyfikatorów agentów dla `sessions_spawn` (`["*"]` = dowolny; domyślnie: tylko ten sam agent).
+- Ochrona dziedziczenia sandbox: jeśli sesja żądająca działa w sandboxie, `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).
---
-## Routing wielu agentów
+## Routing wieloagentowy
Uruchamiaj wielu izolowanych agentów w jednej bramie. Zobacz [Multi-Agent](/pl/concepts/multi-agent).
@@ -1696,12 +1696,12 @@ Uruchamiaj wielu izolowanych agentów w jednej bramie. Zobacz [Multi-Agent](/pl/
### Pola dopasowania powiązań
-- `type` (opcjonalne): `route` dla zwykłego routingu (brak typu domyślnie oznacza route), `acp` dla trwałych powiązań konwersacji ACP.
+- `type` (opcjonalne): `route` dla zwykłego routingu (brakujący typ domyślnie oznacza route), `acp` dla trwałych powiązań konwersacji ACP.
- `match.channel` (wymagane)
- `match.accountId` (opcjonalne; `*` = dowolne konto; pominięte = konto domyślne)
- `match.peer` (opcjonalne; `{ kind: direct|group|channel, id }`)
- `match.guildId` / `match.teamId` (opcjonalne; specyficzne dla kanału)
-- `acp` (opcjonalne; tylko dla `type: "acp"`): `{ mode, label, cwd, backend }`
+- `acp` (opcjonalne; tylko dla wpisów `type: "acp"`): `{ mode, label, cwd, backend }`
**Deterministyczna kolejność dopasowania:**
@@ -1714,11 +1714,11 @@ Uruchamiaj wielu izolowanych agentów w jednej bramie. Zobacz [Multi-Agent](/pl/
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 powiązań route.
+Dla wpisów `type: "acp"` OpenClaw rozstrzyga według dokładnej tożsamości konwersacji (`match.channel` + konto + `match.peer.id`) i nie używa powyższej kolejności poziomów powiązań route.
### Profile dostępu per agent
-
+
```json5
{
@@ -1736,7 +1736,7 @@ Dla wpisów `type: "acp"` OpenClaw rozwiązuje po dokładnej tożsamości konwer
-
+
```json5
{
@@ -1811,7 +1811,7 @@ Dla wpisów `type: "acp"` OpenClaw rozwiązuje po dokładnej tożsamości konwer
-Szczegóły priorytetów znajdziesz w [Multi-Agent Sandbox & Tools](/pl/tools/multi-agent-sandbox-tools).
+Szczegóły priorytetu znajdziesz w [Multi-Agent Sandbox & Tools](/pl/tools/multi-agent-sandbox-tools).
---
@@ -1864,34 +1864,34 @@ Szczegóły priorytetów znajdziesz w [Multi-Agent Sandbox & Tools](/pl/tools/mu
-- **`scope`**: bazowa strategia grupowania sesji dla kontekstów czatu grupowego.
- - `per-sender` (domyślnie): każdy nadawca otrzymuje odizolowaną sesję w obrębie kontekstu kanału.
+- **`scope`**: podstawowa strategia grupowania sesji dla kontekstów czatów grupowych.
+ - `per-sender` (domyślna): każdy nadawca otrzymuje izolowaną sesję w obrębie kontekstu kanału.
- `global`: wszyscy uczestnicy w kontekście kanału współdzielą jedną sesję (używaj tylko wtedy, gdy współdzielony kontekst jest zamierzony).
- **`dmScope`**: sposób grupowania DM.
- `main`: wszystkie DM współdzielą główną sesję.
- - `per-peer`: izolacja według id nadawcy między kanałami.
+ - `per-peer`: izolacja według identyfikatora nadawcy między kanałami.
- `per-channel-peer`: izolacja per kanał + nadawca (zalecane dla skrzynek odbiorczych wielu użytkowników).
- `per-account-channel-peer`: izolacja per konto + kanał + nadawca (zalecane dla wielu kont).
-- **`identityLinks`**: mapuje kanoniczne id na peery z prefiksem dostawcy do współdzielenia sesji między kanałami.
+- **`identityLinks`**: mapuje identyfikatory kanoniczne na peery z prefiksem dostawcy dla współdzielenia sesji między kanałami.
- **`reset`**: podstawowa zasada resetu. `daily` resetuje o `atHour` czasu lokalnego; `idle` resetuje po `idleMinutes`. Gdy skonfigurowane są oba, wygrywa to, co wygaśnie wcześniej.
- **`resetByType`**: nadpisania per typ (`direct`, `group`, `thread`). Starsze `dm` jest akceptowane jako alias `direct`.
-- **`parentForkMaxTokens`**: maksymalna wartość `totalTokens` sesji nadrzędnej dozwolona przy tworzeniu rozwidlonej sesji wątku (domyślnie `100000`).
- - Jeśli `totalTokens` nadrzędnego kontekstu jest powyżej tej wartości, OpenClaw rozpoczyna nową sesję wątku zamiast dziedziczyć historię transkryptu sesji nadrzędnej.
- - Ustaw `0`, aby wyłączyć to zabezpieczenie i zawsze pozwalać na rozwidlenie z rodzica.
-- **`mainKey`**: starsze pole. Runtime zawsze używa `"main"` dla głównego koszyka czatu bezpośredniego.
-- **`agentToAgent.maxPingPongTurns`**: maksymalna liczba tur odpowiedzi zwrotnych między agentami podczas wymiany agent-agent (liczba całkowita, zakres: `0`–`5`). `0` wyłącza łańcuchowanie ping-pong.
-- **`sendPolicy`**: dopasowuje według `channel`, `chatType` (`direct|group|channel`, ze starszym aliasem `dm`), `keyPrefix` albo `rawKeyPrefix`. Wygrywa pierwsza reguła deny.
-- **`maintenance`**: czyszczenie magazynu sesji + kontrola retencji.
+- **`parentForkMaxTokens`**: maksymalne `totalTokens` sesji nadrzędnej dozwolone przy tworzeniu rozwidlonej sesji wątku (domyślnie `100000`).
+ - Jeśli nadrzędne `totalTokens` jest powyżej tej wartości, OpenClaw rozpoczyna świeżą sesję wątku zamiast dziedziczyć historię transkryptu sesji nadrzędnej.
+ - Ustaw `0`, aby wyłączyć to zabezpieczenie i zawsze zezwalać na rozwidlanie od sesji nadrzędnej.
+- **`mainKey`**: pole starszego typu. Runtime zawsze używa `"main"` dla głównego koszyka czatu bezpośredniego.
+- **`agentToAgent.maxPingPongTurns`**: maksymalna liczba tur odpowiedzi zwrotnych między agentami podczas wymian agent-agent (liczba całkowita, zakres: `0`–`5`). `0` wyłącza łańcuchowanie ping-pong.
+- **`sendPolicy`**: dopasowuje według `channel`, `chatType` (`direct|group|channel`, ze starszym aliasem `dm`), `keyPrefix` lub `rawKeyPrefix`. Pierwsza odmowa wygrywa.
+- **`maintenance`**: kontrola czyszczenia + retencji magazynu sesji.
- `mode`: `warn` emituje tylko ostrzeżenia; `enforce` stosuje czyszczenie.
- `pruneAfter`: granica wieku dla nieaktualnych wpisów (domyślnie `30d`).
- `maxEntries`: maksymalna liczba wpisów w `sessions.json` (domyślnie `500`).
- `rotateBytes`: rotuje `sessions.json`, gdy przekroczy ten rozmiar (domyślnie `10mb`).
- - `resetArchiveRetention`: retencja dla archiwów transkryptów `*.reset.`. Domyślnie przyjmuje wartość `pruneAfter`; ustaw `false`, aby wyłączyć.
- - `maxDiskBytes`: opcjonalny budżet dyskowy katalogu sesji. W trybie `warn` zapisuje ostrzeżenia; w trybie `enforce` najpierw usuwa najstarsze artefakty/sesje.
+ - `resetArchiveRetention`: retencja dla archiwów transkryptów `*.reset.`. Domyślnie taka sama jak `pruneAfter`; ustaw `false`, aby wyłączyć.
+ - `maxDiskBytes`: opcjonalny twardy budżet dyskowy dla katalogu sesji. W trybie `warn` zapisuje ostrzeżenia; w trybie `enforce` najpierw usuwa najstarsze artefakty/sesje.
- `highWaterBytes`: opcjonalny cel po czyszczeniu budżetu. Domyślnie `80%` z `maxDiskBytes`.
-- **`threadBindings`**: globalne wartości domyślne dla funkcji sesji powiązanych z wątkami.
+- **`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ć)
+ - `idleHours`: domyślna automatyczna utrata fokusu 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ć)
@@ -1932,7 +1932,7 @@ Szczegóły priorytetów znajdziesz w [Multi-Agent Sandbox & Tools](/pl/tools/mu
Nadpisania per kanał/konto: `channels..responsePrefix`, `channels..accounts..responsePrefix`.
-Rozstrzyganie (wygrywa najbardziej szczegółowe): konto → kanał → globalne. `""` wyłącza i zatrzymuje kaskadę. `"auto"` wyprowadza `[{identity.name}]`.
+Rozstrzyganie (najbardziej specyficzne wygrywa): konto → kanał → globalne. `""` wyłącza i zatrzymuje kaskadę. `"auto"` wyprowadza `[{identity.name}]`.
**Zmienne szablonu:**
@@ -1944,20 +1944,20 @@ Rozstrzyganie (wygrywa najbardziej szczegółowe): konto → kanał → globalne
| `{thinkingLevel}` | Bieżący poziom thinking | `high`, `low`, `off` |
| `{identity.name}` | Nazwa tożsamości agenta | (to samo co `"auto"`) |
-Zmienne nie rozróżniają wielkości liter. `{think}` jest aliasem dla `{thinkingLevel}`.
+Zmienne są niewrażliwe na wielkość liter. `{think}` jest aliasem dla `{thinkingLevel}`.
-### Reakcja ack
+### Reakcja potwierdzenia
-- Domyślnie przyjmuje `identity.emoji` aktywnego agenta, w przeciwnym razie `"👀"`. Ustaw `""`, aby wyłączyć.
+- Domyślnie używa `identity.emoji` aktywnego agenta, w przeciwnym razie `"👀"`. Ustaw `""`, aby wyłączyć.
- Nadpisania per kanał: `channels..ackReaction`, `channels..accounts..ackReaction`.
-- Kolejność rozstrzygania: konto → kanał → `messages.ackReaction` → fallback 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.
+- `removeAckAfterReply`: usuwa potwierdzenie po odpowiedzi w Slack, Discord i Telegram.
- `messages.statusReactions.enabled`: włącza reakcje statusu cyklu życia w Slack, Discord i Telegram.
- W Slack i Discord brak ustawienia pozostawia reakcje statusu włączone, gdy aktywne są reakcje ack.
- W Telegram ustaw to jawnie na `true`, aby włączyć reakcje statusu cyklu życia.
+ W Slack i Discord brak ustawienia pozostawia reakcje statusu włączone, gdy aktywne są reakcje potwierdzenia.
+ W Telegram ustaw jawnie `true`, aby włączyć reakcje statusu cyklu życia.
-### Debounce przychodzących wiadomości
+### Debounce przychodzący
Łączy szybkie wiadomości tekstowe od tego samego nadawcy w jedną turę agenta. Media/załączniki są opróżniane natychmiast. Polecenia kontrolne omijają debounce.
@@ -2002,18 +2002,18 @@ Zmienne nie rozróżniają wielkości liter. `{think}` jest aliasem dla `{thinki
}
```
-- `auto` steruje domyślnym trybem auto-TTS: `off`, `always`, `inbound` albo `tagged`. `/tts on|off` może nadpisać lokalne preferencje, a `/tts status` pokazuje stan efektywny.
+- `auto` steruje domyślnym trybem auto-TTS: `off`, `always`, `inbound` lub `tagged`. `/tts on|off` może nadpisać lokalne preferencje, a `/tts status` pokazuje stan efektywny.
- `summaryModel` nadpisuje `agents.defaults.model.primary` dla automatycznego podsumowania.
- `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` oraz `OPENAI_API_KEY`.
-- `openai.baseUrl` nadpisuje endpoint OpenAI TTS. Kolejność rozstrzygania to konfiguracja, następnie `OPENAI_TTS_BASE_URL`, a potem `https://api.openai.com/v1`.
-- Gdy `openai.baseUrl` wskazuje na endpoint inny niż OpenAI, OpenClaw traktuje go jako serwer TTS zgodny z OpenAI i łagodzi walidację modelu/głosu.
+- Klucze API używają wartości zapasowych z `ELEVENLABS_API_KEY`/`XI_API_KEY` oraz `OPENAI_API_KEY`.
+- `openai.baseUrl` nadpisuje punkt końcowy OpenAI TTS. Kolejność rozstrzygania to konfiguracja, potem `OPENAI_TTS_BASE_URL`, a następnie `https://api.openai.com/v1`.
+- Gdy `openai.baseUrl` wskazuje punkt końcowy inny niż OpenAI, OpenClaw traktuje go jako serwer TTS zgodny z OpenAI i łagodzi walidację modelu/głosu.
---
## Talk
-Ustawienia domyślne dla trybu Talk (macOS/iOS/Android).
+Wartości domyślne dla trybu Talk (macOS/iOS/Android).
```json5
{
@@ -2037,13 +2037,13 @@ Ustawienia domyślne dla trybu Talk (macOS/iOS/Android).
}
```
-- `talk.provider` musi pasować do klucza w `talk.providers`, gdy skonfigurowano wielu dostawców Talk.
-- Starsze płaskie klucze Talk (`talk.voiceId`, `talk.voiceAliases`, `talk.modelId`, `talk.outputFormat`, `talk.apiKey`) służą wyłącznie do zgodności i są automatycznie migrowane do `talk.providers.`.
-- Identyfikatory głosów korzystają z wartości zapasowych `ELEVENLABS_VOICE_ID` albo `SAG_VOICE_ID`.
-- `providers.*.apiKey` akceptuje zwykłe ciągi tekstowe albo obiekty SecretRef.
-- Zapasowa wartość `ELEVENLABS_API_KEY` ma zastosowanie tylko wtedy, gdy nie skonfigurowano klucza API Talk.
+- `talk.provider` musi odpowiadać kluczowi w `talk.providers`, gdy skonfigurowano wielu dostawców Talk.
+- Starsze płaskie klucze Talk (`talk.voiceId`, `talk.voiceAliases`, `talk.modelId`, `talk.outputFormat`, `talk.apiKey`) służą wyłącznie zgodności i są automatycznie migrowane do `talk.providers.`.
+- Identyfikatory głosów używają wartości zapasowych z `ELEVENLABS_VOICE_ID` lub `SAG_VOICE_ID`.
+- `providers.*.apiKey` akceptuje zwykłe ciągi znaków lub obiekty SecretRef.
+- Wartość zapasowa `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` steruje tym, jak długo tryb Talk czeka po ciszy użytkownika, zanim wyśle transkrypt. Brak ustawienia zachowuje domyślne okno pauzy platformy (`700 ms na macOS i Android, 900 ms na iOS`).
---
@@ -2051,22 +2051,22 @@ Ustawienia domyślne dla trybu Talk (macOS/iOS/Android).
### Profile narzędzi
-`tools.profile` ustawia bazową listę dozwolonych przed `tools.allow`/`tools.deny`:
+`tools.profile` ustawia bazową listę zezwoleń 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 brak ustawienia (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) |
+| `messaging` | `group:messaging`, `sessions_list`, `sessions_history`, `sessions_send`, `session_status` |
+| `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:runtime` | `exec`, `process`, `code_execution` (`bash` jest akceptowane jako alias `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` |
@@ -2077,11 +2077,11 @@ Lokalny onboarding domyślnie ustawia `tools.profile: "coding"` w nowych lokalny
| `group:nodes` | `nodes` |
| `group:agents` | `agents_list` |
| `group:media` | `image`, `image_generate`, `video_generate`, `tts` |
-| `group:openclaw` | Wszystkie wbudowane narzędzia (z wyłączeniem wtyczek dostawców) |
+| `group:openclaw` | Wszystkie wbudowane narzędzia (z wyłączeniem pluginów dostawców) |
### `tools.allow` / `tools.deny`
-Globalna zasada allow/deny dla narzędzi (deny ma pierwszeństwo). Bez rozróżniania wielkości liter, obsługuje wildcardy `*`. Stosowana nawet wtedy, gdy sandbox Docker jest wyłączony.
+Globalna polityka zezwalania/odmawiania dla narzędzi (odmowa wygrywa). Niewrażliwa na wielkość liter, obsługuje wildcardy `*`. Stosowana nawet wtedy, gdy sandbox Docker jest wyłączony.
```json5
{
@@ -2091,7 +2091,7 @@ Globalna zasada allow/deny dla narzędzi (deny ma pierwszeństwo). Bez rozróżn
### `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
{
@@ -2107,7 +2107,7 @@ Dalsze ograniczanie narzędzi dla określonych dostawców lub modeli. Kolejnoś
### `tools.elevated`
-Steruje podwyższonym dostępem `exec` poza sandbox:
+Steruje podwyższonym dostępem `exec` poza sandboxem:
```json5
{
@@ -2124,8 +2124,8 @@ Steruje podwyższonym dostępem `exec` poza sandbox:
```
- Nadpisanie per agent (`agents.list[].tools.elevated`) może tylko dalej ograniczać.
-- `/elevated on|off|ask|full` przechowuje stan per sesja; dyrektywy inline mają zastosowanie do pojedynczej wiadomości.
-- Podwyższone `exec` omija sandboxing i używa skonfigurowanej ścieżki ucieczki (`gateway` domyślnie albo `node`, gdy celem exec jest `node`).
+- `/elevated on|off|ask|full` zapisuje stan per sesja; dyrektywy inline mają zastosowanie do pojedynczej wiadomości.
+- Podwyższone `exec` omija sandboxing i używa skonfigurowanej ścieżki wyjścia (`gateway` domyślnie lub `node`, gdy celem exec jest `node`).
### `tools.exec`
@@ -2149,7 +2149,7 @@ Steruje podwyższonym dostępem `exec` poza sandbox:
### `tools.loopDetection`
-Kontrole bezpieczeństwa pętli narzędzi są **domyślnie wyłączone**. Ustaw `enabled: true`, aby włączyć wykrywanie.
+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
@@ -2172,13 +2172,13 @@ Ustawienia można definiować globalnie w `tools.loopDetection` i nadpisywać pe
```
- `historySize`: maksymalna historia wywołań narzędzi zachowywana do analizy pętli.
-- `warningThreshold`: próg ostrzeżeń dla powtarzających się wzorców bez postępu.
-- `criticalThreshold`: wyższy próg powtórzeń do 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 dla znanych narzędzi odpytywania (`process.poll`, `command_status` itd.).
-- `detectors.pingPong`: ostrzega/blokuje przy naprzemiennych wzorcach par bez postępu.
-- Jeśli `warningThreshold >= criticalThreshold` albo `criticalThreshold >= globalCircuitBreakerThreshold`, walidacja kończy się niepowodzeniem.
+- `warningThreshold`: próg powtarzającego się wzorca bez postępu dla ostrzeżeń.
+- `criticalThreshold`: wyższy próg powtarzania do blokowania krytycznych pętli.
+- `globalCircuitBreakerThreshold`: próg twardego zatrzymania dla każdego przebiegu bez postępu.
+- `detectors.genericRepeat`: ostrzegaj przy powtarzanych wywołaniach tego samego narzędzia z tymi samymi argumentami.
+- `detectors.knownPollNoProgress`: ostrzegaj/blokuj przy znanych narzędziach odpytywania (`process.poll`, `command_status` itd.).
+- `detectors.pingPong`: ostrzegaj/blokuj przy naprzemiennych wzorcach par bez postępu.
+- Jeśli `warningThreshold >= criticalThreshold` lub `criticalThreshold >= globalCircuitBreakerThreshold`, walidacja kończy się błędem.
### `tools.web`
@@ -2212,7 +2212,7 @@ Ustawienia można definiować globalnie w `tools.loopDetection` i nadpisywać pe
### `tools.media`
-Konfiguruje rozumienie mediów przychodzących (obraz/audio/wideo):
+Konfiguruje rozumienie przychodzących mediów (obraz/audio/wideo):
```json5
{
@@ -2246,30 +2246,30 @@ Konfiguruje rozumienie mediów przychodzących (obraz/audio/wideo):
-**Wpis dostawcy** (`type: "provider"` albo pominięte):
+**Wpis dostawcy** (`type: "provider"` lub pominięte):
-- `provider`: id dostawcy API (`openai`, `anthropic`, `google`/`gemini`, `groq` itd.)
-- `model`: nadpisanie id modelu
+- `provider`: identyfikator dostawcy API (`openai`, `anthropic`, `google`/`gemini`, `groq` itd.)
+- `model`: nadpisanie identyfikatora modelu
- `profile` / `preferredProfile`: wybór profilu `auth-profiles.json`
**Wpis CLI** (`type: "cli"`):
- `command`: wykonywalne polecenie do uruchomienia
-- `args`: argumenty z szablonami (obsługuje `{{MediaPath}}`, `{{Prompt}}`, `{{MaxChars}}` itd.)
+- `args`: argumenty szablonowe (obsługuje `{{MediaPath}}`, `{{Prompt}}`, `{{MaxChars}}` itd.)
**Pola wspólne:**
- `capabilities`: opcjonalna lista (`image`, `audio`, `video`). Domyślnie: `openai`/`anthropic`/`minimax` → image, `google` → image+audio+video, `groq` → audio.
- `prompt`, `maxChars`, `maxBytes`, `timeoutSeconds`, `language`: nadpisania per wpis.
-- Przy niepowodzeniu następuje przejście do następnego wpisu.
+- W przypadku błędów używany jest następny wpis.
-Uwierzytelnianie dostawców przebiega według standardowej kolejności: `auth-profiles.json` → zmienne środowiskowe → `models.providers.*.apiKey`.
+Uwierzytelnianie dostawcy przebiega zgodnie ze standardową kolejnością: `auth-profiles.json` → zmienne środowiskowe → `models.providers.*.apiKey`.
**Pola async completion:**
- `asyncCompletion.directSend`: gdy `true`, ukończone asynchroniczne zadania `music_generate`
i `video_generate` najpierw próbują bezpośredniego dostarczenia do kanału. Domyślnie: `false`
- (starsza ścieżka wybudzania sesji żądającej/dostarczania modelu).
+ (starsza ścieżka wybudzania sesji żądającej/dostarczania przez model).
@@ -2288,9 +2288,9 @@ Uwierzytelnianie dostawców przebiega według standardowej kolejności: `auth-pr
### `tools.sessions`
-Steruje tym, które sesje mogą być wskazywane przez narzędzia sesji (`sessions_list`, `sessions_history`, `sessions_send`).
+Steruje tym, które sesje mogą być celem dla narzędzi sesji (`sessions_list`, `sessions_history`, `sessions_send`).
-Domyślnie: `tree` (bieżąca sesja + sesje uruchomione przez nią, takie jak subagenci).
+Domyślnie: `tree` (bieżąca sesja + sesje utworzone przez nią, takie jak subagenci).
```json5
{
@@ -2306,10 +2306,10 @@ Domyślnie: `tree` (bieżąca sesja + sesje uruchomione przez nią, takie jak su
Uwagi:
- `self`: tylko bieżący klucz sesji.
-- `tree`: bieżąca sesja + sesje uruchomione przez bieżącą sesję (subagenci).
-- `agent`: dowolna sesja należąca do bieżącego id agenta (może obejmować innych użytkowników, jeśli uruchamiasz sesje per nadawca pod tym samym id agenta).
+- `tree`: bieżąca sesja + sesje utworzone przez bieżącą sesję (subagenci).
+- `agent`: każda sesja należąca do bieżącego identyfikatora agenta (może obejmować innych użytkowników, jeśli uruchamiasz sesje per nadawca pod tym samym identyfikatorem agenta).
- `all`: dowolna sesja. Kierowanie między agentami nadal wymaga `tools.agentToAgent`.
-- Ograniczenie sandbox: gdy bieżąca sesja działa w sandbox i `agents.defaults.sandbox.sessionToolsVisibility="spawned"`, widoczność jest wymuszana na `tree`, nawet jeśli `tools.sessions.visibility="all"`.
+- Ograniczenie sandbox: gdy bieżąca sesja działa w sandboxie i `agents.defaults.sandbox.sessionToolsVisibility="spawned"`, widoczność jest wymuszana na `tree`, nawet jeśli `tools.sessions.visibility="all"`.
### `tools.sessions_spawn`
@@ -2334,15 +2334,15 @@ Steruje obsługą załączników inline dla `sessions_spawn`.
Uwagi:
- Załączniki są obsługiwane tylko dla `runtime: "subagent"`. Runtime ACP je odrzuca.
-- Pliki są materializowane w workspace podrzędnym pod `.openclaw/attachments//` z plikiem `.manifest.json`.
-- Zawartość załączników jest automatycznie redagowana z trwałego zapisu transkryptu.
-- Wejścia base64 są walidowane z użyciem ścisłych kontroli alfabetu/dopełnienia i zabezpieczenia rozmiaru przed dekodowaniem.
+- Pliki są materializowane do podrzędnego obszaru roboczego w `.openclaw/attachments//` z plikiem `.manifest.json`.
+- Zawartość załączników jest automatycznie redagowana z trwałości transkryptu.
+- Dane wejściowe base64 są walidowane za pomocą ścisłych kontroli alfabetu/dopełnienia oraz zabezpieczenia rozmiaru przed dekodowaniem.
- Uprawnienia plików to `0700` dla katalogów i `0600` dla plików.
-- Czyszczenie zależy od zasady `cleanup`: `delete` zawsze usuwa załączniki; `keep` zachowuje je tylko wtedy, gdy `retainOnSessionKeep: true`.
+- Czyszczenie przestrzega polityki `cleanup`: `delete` zawsze usuwa załączniki; `keep` zachowuje je tylko wtedy, gdy `retainOnSessionKeep: true`.
### `tools.experimental`
-Eksperymentalne flagi wbudowanych narzędzi. Domyślnie wyłączone, chyba że ma zastosowanie reguła automatycznego włączenia dla ścisłego agentowego GPT-5.
+Flagi eksperymentalnych wbudowanych narzędzi. Domyślnie wyłączone, chyba że ma zastosowanie reguła automatycznego włączenia strict-agentic GPT-5.
```json5
{
@@ -2356,9 +2356,9 @@ Eksperymentalne flagi wbudowanych narzędzi. Domyślnie wyłączone, chyba że m
Uwagi:
-- `planTool`: włącza strukturalne narzędzie `update_plan` do śledzenia nietrywialnych prac wieloetapowych.
-- Domyślnie: `false`, chyba że `agents.defaults.embeddedPi.executionContract` (albo nadpisanie per agent) jest ustawione na `"strict-agentic"` dla przebiegu OpenAI albo OpenAI Codex z rodziny GPT-5. Ustaw `true`, aby wymusić włączenie narzędzia poza tym zakresem, albo `false`, aby pozostawić je wyłączone nawet dla przebiegów ścisłego agentowego GPT-5.
-- Gdy włączone, system prompt dodaje też wskazówki użycia, aby model korzystał z niego tylko przy istotnej pracy i utrzymywał najwyżej jeden krok `in_progress`.
+- `planTool`: włącza strukturalne narzędzie `update_plan` do śledzenia nietrywialnej pracy wieloetapowej.
+- Domyślnie: `false`, chyba że `agents.defaults.embeddedPi.executionContract` (lub nadpisanie per agent) jest ustawione na `"strict-agentic"` dla przebiegu rodziny OpenAI lub OpenAI Codex GPT-5. Ustaw `true`, aby wymusić włączenie narzędzia poza tym zakresem, lub `false`, aby utrzymać je wyłączone nawet dla przebiegów strict-agentic GPT-5.
+- Gdy jest włączone, system prompt dodaje również wskazówki użycia, aby model używał go tylko do istotnej pracy i utrzymywał najwyżej jeden krok `in_progress`.
### `agents.defaults.subagents`
@@ -2379,15 +2379,15 @@ Uwagi:
```
- `model`: domyślny model dla uruchamianych subagentów. Jeśli pominięty, subagenci dziedziczą model wywołującego.
-- `allowAgents`: domyślna lista dozwolonych id 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 limit czasu (sekundy) dla `sessions_spawn`, gdy wywołanie narzędzia pomija `runTimeoutSeconds`. `0` oznacza brak limitu czasu.
-- Zasada narzędzi per subagent: `tools.subagents.tools.allow` / `tools.subagents.tools.deny`.
+- `allowAgents`: domyślna lista zezwoleń 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).
+- `runTimeoutSeconds`: domyślny timeout (w sekundach) 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`.
---
-## Własni dostawcy i bazowe URL
+## Niestandardowi dostawcy i base URL
-OpenClaw używa wbudowanego katalogu modeli. Dodawaj własnych dostawców przez `models.providers` w konfiguracji albo `~/.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
{
@@ -2416,46 +2416,46 @@ OpenClaw używa wbudowanego katalogu modeli. Dodawaj własnych dostawców przez
}
```
-- Użyj `authHeader: true` + `headers` dla własnych potrzeb uwierzytelniania.
-- Nadpisz katalog główny konfiguracji agenta przez `OPENCLAW_AGENT_DIR` (albo `PI_CODING_AGENT_DIR`, starszy alias zmiennej środowiskowej).
-- Priorytet scalania dla pasujących id dostawców:
- - Niepuste wartości `baseUrl` z agentowego `models.json` mają pierwszeństwo.
- - Niepuste wartości `apiKey` z agenta mają pierwszeństwo tylko wtedy, gdy dany dostawca nie jest zarządzany przez SecretRef w bieżącym kontekście konfiguracji/profilu auth.
- - Wartości `apiKey` dostawców zarządzanych przez SecretRef są odświeżane ze znaczników źródłowych (`ENV_VAR_NAME` dla odwołań env, `secretref-managed` dla odwołań file/exec) zamiast utrwalać rozwiązane sekrety.
- - Wartości nagłówków dostawców zarządzanych przez SecretRef są odświeżane ze znaczników źródłowych (`secretref-env:ENV_VAR_NAME` dla odwołań env, `secretref-managed` dla odwołań file/exec).
- - Puste albo brakujące wartości `apiKey`/`baseUrl` z agenta wracają do `models.providers` w konfiguracji.
- - Dla pasujących modeli `contextWindow`/`maxTokens` używają wyższej wartości między jawną konfiguracją a niejawnymi wartościami katalogowymi.
+- 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 agenta `models.json` mają pierwszeństwo.
+ - Niepuste wartości `apiKey` z agenta wygrywają tylko wtedy, gdy ten dostawca nie jest zarządzany przez SecretRef w bieżącym kontekście config/auth-profile.
+ - Wartości `apiKey` dostawców zarządzanych przez SecretRef są odświeżane z markeró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 dostawców zarządzanych 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` z agenta używają wartości zapasowych z `models.providers` w konfiguracji.
+ - Dla pasujących modeli `contextWindow`/`maxTokens` używają wyższej wartości spośród jawnej konfiguracji i niejawnych wartości katalogu.
- Dla pasujących modeli `contextTokens` zachowuje jawny limit runtime, gdy jest obecny; użyj go, aby ograniczyć efektywny kontekst bez zmiany natywnych metadanych modelu.
- Użyj `models.mode: "replace"`, gdy chcesz, aby konfiguracja całkowicie nadpisała `models.json`.
- - Utrwalanie znaczników jest autorytatywne względem źródła: znaczniki są zapisywane z aktywnej migawki konfiguracji źródła (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 runtime.
### Szczegóły pól dostawcy
-- `models.mode`: zachowanie katalogu dostawców (`merge` albo `replace`).
-- `models.providers`: mapa własnych dostawców indeksowana po id dostawcy.
+- `models.mode`: zachowanie katalogu dostawców (`merge` lub `replace`).
+- `models.providers`: mapa niestandardowych dostawców z kluczem będącym identyfikatorem dostawcy.
- `models.providers.*.api`: adapter żądań (`openai-completions`, `openai-responses`, `anthropic-messages`, `google-generative-ai` itd.).
-- `models.providers.*.apiKey`: poświadczenie dostawcy (preferuj SecretRef/podstawianie env).
+- `models.providers.*.apiKey`: poświadczenie dostawcy (preferuj SecretRef/podstawienie env).
- `models.providers.*.auth`: strategia uwierzytelniania (`api-key`, `token`, `oauth`, `aws-sdk`).
- `models.providers.*.injectNumCtxForOpenAICompat`: dla Ollama + `openai-completions` wstrzykuje `options.num_ctx` do żądań (domyślnie: `true`).
-- `models.providers.*.authHeader`: wymusza przesyłanie poświadczeń w nagłówku `Authorization`, gdy jest to wymagane.
+- `models.providers.*.authHeader`: wymusza transport poświadczenia w nagłówku `Authorization`, gdy jest to wymagane.
- `models.providers.*.baseUrl`: bazowy URL nadrzędnego API.
-- `models.providers.*.headers`: dodatkowe statyczne nagłówki dla routingu proxy/tenant.
-- `models.providers.*.request`: nadpisania transportu dla żądań HTTP dostawców modeli.
+- `models.providers.*.headers`: dodatkowe statyczne nagłówki dla routingu proxy/dzierżawy.
+- `models.providers.*.request`: nadpisania transportu dla żądań HTTP dostawcy modelu.
- `request.headers`: dodatkowe nagłówki (scalane z domyślnymi nagłówkami 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`, opcjonalnie `prefix`).
- - `request.proxy`: nadpisanie proxy HTTP. Tryby: `"env-proxy"` (użyj zmiennych środowiskowych `HTTP_PROXY`/`HTTPS_PROXY`), `"explicit-proxy"` (z `url`). Oba tryby akceptują opcjonalny pod-obiekt `tls`.
+ - `request.auth`: nadpisanie strategii uwierzytelniania. Tryby: `"provider-default"` (użyj wbudowanego uwierzytelniania dostawcy), `"authorization-bearer"` (z `token`), `"header"` (z `headerName`, `value`, opcjonalnym `prefix`).
+ - `request.proxy`: nadpisanie proxy HTTP. Tryby: `"env-proxy"` (użyj zmiennych środowiskowych `HTTP_PROXY`/`HTTPS_PROXY`), `"explicit-proxy"` (z `url`). Oba tryby akceptują opcjonalny podobiekt `tls`.
- `request.tls`: nadpisanie TLS dla połączeń bezpośrednich. Pola: `ca`, `cert`, `key`, `passphrase` (wszystkie akceptują SecretRef), `serverName`, `insecureSkipVerify`.
- - `request.allowPrivateNetwork`: gdy `true`, zezwala na HTTPS do `baseUrl`, gdy DNS rozwiązuje się do prywatnych, CGNAT lub podobnych zakresów, przez zabezpieczenie pobierania HTTP dostawcy (opt-in operatora dla zaufanych, samohostowanych endpointów zgodnych z OpenAI). WebSocket używa tego samego `request` dla nagłówków/TLS, ale nie tego zabezpieczenia SSRF dla fetch. Domyślnie `false`.
+ - `request.allowPrivateNetwork`: gdy `true`, zezwala na HTTPS do `baseUrl`, gdy DNS rozwiązuje się do prywatnych, CGNAT lub podobnych zakresów, przez zabezpieczenie pobierania HTTP dostawcy (opt-in operatora dla zaufanych samohostowanych punktów końcowych zgodnych z OpenAI). WebSocket używa tego samego `request` dla nagłówków/TLS, ale nie dla tego zabezpieczenia SSRF pobierania. Domyślnie `false`.
- `models.providers.*.models`: jawne wpisy katalogu modeli dostawcy.
-- `models.providers.*.models.*.contextWindow`: natywne metadane okna kontekstu modelu.
-- `models.providers.*.models.*.contextTokens`: opcjonalny limit kontekstu runtime. Użyj tego, gdy chcesz mniejszy efektywny budżet kontekstu niż natywne `contextWindow` modelu.
-- `models.providers.*.models.*.compat.supportsDeveloperRole`: opcjonalna wskazówka zgodności. Dla `api: "openai-completions"` z niepustym, nienatywnym `baseUrl` (host nie jest `api.openai.com`) OpenClaw wymusza tę wartość na `false` w runtime. 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 zgodnych z OpenAI, które akceptują tylko ciągi. Gdy `true`, OpenClaw spłaszcza czysto tekstowe tablice `messages[].content` do zwykłych ciągów przed wysłaniem żądania.
+- `models.providers.*.models.*.contextWindow`: metadane natywnego okna kontekstu modelu.
+- `models.providers.*.models.*.contextTokens`: opcjonalny limit kontekstu runtime. Użyj tego, 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 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 zgodnych z OpenAI punktów końcowych czatu obsługujących tylko ciągi znaków. Gdy `true`, OpenClaw spłaszcza czysto tekstowe tablice `messages[].content` do zwykłych ciągów przed wysłaniem żądania.
- `plugins.entries.amazon-bedrock.config.discovery`: główny katalog 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 id dostawcy dla wykrywania ukierunkowanego.
-- `plugins.entries.amazon-bedrock.config.discovery.refreshInterval`: interwał odświeżania wykrywania.
+- `plugins.entries.amazon-bedrock.config.discovery.providerFilter`: opcjonalny filtr identyfikatora dostawcy dla wykrywania ukierunkowanego.
+- `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.
@@ -2512,7 +2512,7 @@ Użyj `cerebras/zai-glm-4.7` dla Cerebras; `zai/glm-4.7` dla bezpośredniego Z.A
}
```
-Ustaw `OPENCODE_API_KEY` (albo `OPENCODE_ZEN_API_KEY`). Używaj odwołań `opencode/...` dla katalogu Zen albo `opencode-go/...` dla katalogu Go. Skrót: `openclaw onboard --auth-choice opencode-zen` albo `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`.
@@ -2531,9 +2531,9 @@ Ustaw `OPENCODE_API_KEY` (albo `OPENCODE_ZEN_API_KEY`). Używaj odwołań `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ślny): `https://api.z.ai/api/coding/paas/v4`
-- Dla ogólnego endpointu zdefiniuj własnego dostawcę z nadpisaniem `baseUrl`.
+- Punkt końcowy ogólny: `https://api.z.ai/api/paas/v4`
+- Punkt końcowy do kodowania (domyślny): `https://api.z.ai/api/coding/paas/v4`
+- Dla ogólnego punktu końcowego zdefiniuj niestandardowego dostawcę z nadpisaniem base URL.
@@ -2572,11 +2572,11 @@ Ustaw `ZAI_API_KEY`. `z.ai/*` i `z-ai/*` są akceptowanymi aliasami. Skrót: `op
}
```
-Dla endpointu China: `baseUrl: "https://api.moonshot.cn/v1"` albo `openclaw onboard --auth-choice moonshot-api-key-cn`.
+Dla punktu końcowego w Chinach: `baseUrl: "https://api.moonshot.cn/v1"` lub `openclaw onboard --auth-choice moonshot-api-key-cn`.
-Natywne endpointy Moonshot reklamują zgodność użycia strumieniowania na współdzielonym
-transporcie `openai-completions`, a OpenClaw opiera się tu na możliwościach endpointu,
-a nie wyłącznie na wbudowanym id dostawcy.
+Natywne punkty końcowe Moonshot reklamują zgodność użycia strumieniowania na współdzielonym
+transporcie `openai-completions`, a OpenClaw opiera to na możliwościach punktu końcowego,
+a nie wyłącznie na wbudowanym identyfikatorze dostawcy.
@@ -2633,7 +2633,7 @@ Zgodny z Anthropic, wbudowany dostawca. Skrót: `openclaw onboard --auth-choice
}
```
-Bazowy URL powinien pomijać `/v1` (klient Anthropic go 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`.
@@ -2674,11 +2674,11 @@ Bazowy URL powinien pomijać `/v1` (klient Anthropic go dopisuje). Skrót: `open
```
Ustaw `MINIMAX_API_KEY`. Skróty:
-`openclaw onboard --auth-choice minimax-global-api` albo
+`openclaw onboard --auth-choice minimax-global-api` lub
`openclaw onboard --auth-choice minimax-cn-api`.
Katalog modeli domyślnie zawiera tylko M2.7.
Na ścieżce strumieniowania zgodnej z Anthropic OpenClaw domyślnie wyłącza thinking MiniMax,
-chyba że jawnie ustawisz `thinking` samodzielnie. `/fast on` albo
+chyba że jawnie ustawisz `thinking`. `/fast on` lub
`params.fastMode: true` przepisuje `MiniMax-M2.7` na
`MiniMax-M2.7-highspeed`.
@@ -2686,7 +2686,7 @@ chyba że jawnie ustawisz `thinking` samodzielnie. `/fast on` albo
-Zobacz [Modele lokalne](/pl/gateway/local-models). W skrócie: uruchamiaj duży lokalny model przez LM Studio Responses API na wydajnym sprzęcie; zachowaj hostowane modele jako scalone dla fallbacku.
+Zobacz [Modele lokalne](/pl/gateway/local-models). W skrócie: uruchom duży model lokalny przez LM Studio Responses API na odpowiednim sprzęcie; zachowaj hostowane modele scalone jako fallback.
@@ -2717,18 +2717,18 @@ Zobacz [Modele lokalne](/pl/gateway/local-models). W skrócie: uruchamiaj duży
}
```
-- `allowBundled`: opcjonalna lista dozwolonych tylko dla pakietowych Skills (nie dotyczy zarządzanych/workspace Skills).
+- `allowBundled`: opcjonalna lista zezwoleń tylko dla bundlowanych Skills (managed/workspace Skills pozostają bez zmian).
- `load.extraDirs`: dodatkowe współdzielone katalogi główne Skills (najniższy priorytet).
-- `install.preferBrew`: gdy true, preferuje instalatory Homebrew, gdy `brew` jest
- dostępne, zanim przejdzie do innych typów instalatorów.
-- `install.nodeManager`: preferencja instalatora node dla specyfikacji `metadata.openclaw.install`
- (`npm` | `pnpm` | `yarn` | `bun`).
-- `entries..enabled: false` wyłącza Skill nawet wtedy, gdy jest pakietowy/zainstalowany.
-- `entries..apiKey`: ułatwienie dla Skills deklarujących podstawową zmienną env (zwykły ciąg albo obiekt SecretRef).
+- `install.preferBrew`: gdy `true`, preferuje instalatory Homebrew, jeśli `brew` jest
+ dostępne, zanim wróci do innych typó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 bundlowany/zainstalowany.
+- `entries..apiKey`: ułatwienie dla Skills deklarujących podstawową zmienną env (zwykły ciąg znaków lub obiekt SecretRef).
---
-## Wtyczki
+## Pluginy
```json5
{
@@ -2752,43 +2752,43 @@ Zobacz [Modele lokalne](/pl/gateway/local-models). W skrócie: uruchamiaj duży
}
```
-- Wczytywane z `~/.openclaw/extensions`, `/.openclaw/extensions` oraz `plugins.load.paths`.
-- Wykrywanie akceptuje natywne wtyczki OpenClaw oraz zgodne bundli Codex i Claude, w tym bundli Claude z domyślnym układem bez manifestu.
+- Ładowane z `~/.openclaw/extensions`, `/.openclaw/extensions` oraz `plugins.load.paths`.
+- Wykrywanie akceptuje natywne pluginy OpenClaw oraz zgodne bundlowane pakiety Codex i Claude, w tym pakiety Claude o domyślnym układzie bez manifestu.
- **Zmiany konfiguracji wymagają restartu bramy.**
-- `allow`: opcjonalna lista dozwolonych (ładowane są tylko wymienione wtyczki). `deny` ma pierwszeństwo.
-- `plugins.entries..apiKey`: pomocnicze pole klucza API na poziomie wtyczki (gdy jest obsługiwane przez wtyczkę).
-- `plugins.entries..env`: mapa zmiennych środowiskowych o zakresie wtyczki.
-- `plugins.entries..hooks.allowPromptInjection`: gdy `false`, rdzeń blokuje `before_prompt_build` i ignoruje pola mutujące prompt ze starszego `before_agent_start`, zachowując jednocześnie starsze `modelOverride` i `providerOverride`. Dotyczy natywnych hooków wtyczek i obsługiwanych katalogów hooków dostarczanych przez bundle.
-- `plugins.entries..subagent.allowModelOverride`: jawnie ufa tej wtyczce, że może żądać nadpisań `provider` i `model` per uruchomienie dla przebiegów subagentów w tle.
-- `plugins.entries..subagent.allowedModels`: opcjonalna lista dozwolonych kanonicznych celów `provider/model` dla zaufanych nadpisań subagentów. Używaj `"*"` tylko wtedy, gdy celowo chcesz zezwolić na dowolny model.
-- `plugins.entries..config`: obiekt konfiguracji zdefiniowany przez wtyczkę (walidowany przez natywny schemat wtyczki OpenClaw, gdy jest dostępny).
+- `allow`: opcjonalna lista zezwoleń (ładowane są tylko wymienione pluginy). `deny` ma pierwszeństwo.
+- `plugins.entries..apiKey`: pomocnicze pole klucza API na poziomie pluginu (gdy jest obsługiwane przez plugin).
+- `plugins.entries..env`: mapa zmiennych env w zakresie pluginu.
+- `plugins.entries..hooks.allowPromptInjection`: gdy `false`, rdzeń 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 oraz obsługiwanych katalogów hooków dostarczanych przez bundlowane pakiety.
+- `plugins.entries..subagent.allowModelOverride`: jawnie ufa temu pluginowi, że może żądać nadpisań `provider` i `model` per przebieg dla zadań subagenta w tle.
+- `plugins.entries..subagent.allowedModels`: opcjonalna lista zezwoleń kanonicznych celów `provider/model` dla zaufanych nadpisań subagenta. Używaj `"*"` tylko wtedy, gdy celowo chcesz zezwolić na dowolny model.
+- `plugins.entries..config`: obiekt konfiguracji zdefiniowany przez plugin (walidowany przez natywny schemat pluginu OpenClaw, gdy jest dostępny).
- `plugins.entries.firecrawl.config.webFetch`: ustawienia dostawcy web-fetch Firecrawl.
- - `apiKey`: klucz API Firecrawl (akceptuje SecretRef). Wraca do `plugins.entries.firecrawl.config.webSearch.apiKey`, starszego `tools.web.fetch.firecrawl.apiKey` albo zmiennej środowiskowej `FIRECRAWL_API_KEY`.
+ - `apiKey`: klucz API Firecrawl (akceptuje SecretRef). Używa wartości zapasowej 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`: wyodrębnia tylko główną treść ze stron (domyślnie: `true`).
- - `maxAgeMs`: maksymalny wiek cache w milisekundach (domyślnie: `172800000` / 2 dni).
+ - `onlyMainContent`: wyodrębnia tylko główną treść stron (domyślnie: `true`).
+ - `maxAgeMs`: maksymalny wiek pamięci podręcznej w milisekundach (domyślnie: `172800000` / 2 dni).
- `timeoutSeconds`: limit czasu żądania scrape w sekundach (domyślnie: `60`).
-- `plugins.entries.xai.config.xSearch`: ustawienia xAI X Search (wyszukiwanie w sieci Grok).
+- `plugins.entries.xai.config.xSearch`: ustawienia xAI X Search (wyszukiwanie webowe Grok).
- `enabled`: włącza dostawcę X Search.
- `model`: model Grok używany do wyszukiwania (np. `"grok-4-1-fast"`).
-- `plugins.entries.memory-core.config.dreaming`: ustawienia memory dreaming (eksperymentalne). Fazy i progi opisano w [Dreaming](/pl/concepts/dreaming).
+- `plugins.entries.memory-core.config.dreaming`: ustawienia memory dreaming (eksperymentalne). Informacje o fazach i progach znajdziesz w [Dreaming](/pl/concepts/dreaming).
- `enabled`: główny przełącznik dreaming (domyślnie `false`).
- `frequency`: harmonogram cron dla każdego pełnego przebiegu dreaming (`"0 3 * * *"` domyślnie).
- - zasady faz i progi są szczegółami implementacji (nie są kluczami konfiguracji skierowanymi do użytkownika).
-- Pełna konfiguracja pamięci znajduje się w [Dokumentacja konfiguracji pamięci](/pl/reference/memory-config):
+ - polityka faz i progi są szczegółami implementacyjnymi (nie są kluczami konfiguracji dla użytkownika).
+- Pełna konfiguracja pamięci znajduje się w [Odwołaniu do konfiguracji pamięci](/pl/reference/memory-config):
- `agents.defaults.memorySearch.*`
- `memory.backend`
- `memory.citations`
- `memory.qmd.*`
- `plugins.entries.memory-core.config.dreaming`
-- Włączone wtyczki Claude bundle mogą również wnosić osadzone ustawienia domyślne Pi z `settings.json`; OpenClaw stosuje je jako oczyszczone ustawienia agenta, a nie jako surowe patche konfiguracji OpenClaw.
-- `plugins.slots.memory`: wybiera id aktywnej wtyczki pamięci albo `"none"`, aby wyłączyć wtyczki pamięci.
-- `plugins.slots.contextEngine`: wybiera id aktywnej wtyczki silnika kontekstu; domyślnie `"legacy"`, chyba że zainstalujesz i wybierzesz inny silnik.
-- `plugins.installs`: metadane instalacji zarządzane przez CLI, używane przez `openclaw plugins update`.
- - Zawiera `source`, `spec`, `sourcePath`, `installPath`, `version`, `resolvedName`, `resolvedVersion`, `resolvedSpec`, `integrity`, `shasum`, `resolvedAt`, `installedAt`.
+- Włączone pluginy pakietów Claude mogą również dostarczać osadzone domyślne ustawienia Pi z `settings.json`; OpenClaw stosuje je jako oczyszczone ustawienia agenta, a nie jako surowe poprawki konfiguracji OpenClaw.
+- `plugins.slots.memory`: wybiera identyfikator aktywnego pluginu pamięci lub `"none"`, aby wyłączyć pluginy pamięci.
+- `plugins.slots.contextEngine`: wybiera identyfikator aktywnego pluginu silnika kontekstu; domyślnie `"legacy"`, dopóki nie zainstalujesz i nie wybierzesz innego silnika.
+- `plugins.installs`: metadane instalacji zarządzane przez CLI używane przez `openclaw plugins update`.
+ - Obejmuje `source`, `spec`, `sourcePath`, `installPath`, `version`, `resolvedName`, `resolvedVersion`, `resolvedSpec`, `integrity`, `shasum`, `resolvedAt`, `installedAt`.
- Traktuj `plugins.installs.*` jako stan zarządzany; preferuj polecenia CLI zamiast ręcznych edycji.
-Zobacz [Wtyczki](/pl/tools/plugin).
+Zobacz [Pluginy](/pl/tools/plugin).
---
@@ -2831,26 +2831,26 @@ Zobacz [Wtyczki](/pl/tools/plugin).
- `evaluateEnabled: false` wyłącza `act:evaluate` i `wait --fn`.
- `ssrfPolicy.dangerouslyAllowPrivateNetwork` jest wyłączone, gdy nie jest ustawione, więc nawigacja przeglądarki domyślnie pozostaje ścisła.
- Ustaw `ssrfPolicy.dangerouslyAllowPrivateNetwork: true` tylko wtedy, gdy celowo ufasz nawigacji przeglądarki do sieci prywatnej.
-- W trybie ścisłym zdalne endpointy profili CDP (`profiles.*.cdpUrl`) podlegają temu samemu blokowaniu sieci prywatnej podczas kontroli osiągalności/wykrywania.
+- W trybie ścisłym zdalne punkty końcowe profilu CDP (`profiles.*.cdpUrl`) podlegają temu samemu blokowaniu sieci prywatnej podczas sprawdzania osiągalności/wykrywania.
- `ssrfPolicy.allowPrivateNetwork` pozostaje obsługiwane jako starszy alias.
- W trybie ścisłym używaj `ssrfPolicy.hostnameAllowlist` i `ssrfPolicy.allowedHostnames` dla jawnych wyjątków.
- Profile zdalne są tylko do podłączania (uruchamianie/zatrzymywanie/reset są wyłączone).
- `profiles.*.cdpUrl` akceptuje `http://`, `https://`, `ws://` i `wss://`.
- Używaj HTTP(S), gdy chcesz, aby OpenClaw wykrywał `/json/version`; używaj WS(S),
- gdy dostawca daje bezpośredni URL DevTools WebSocket.
-- Profile `existing-session` są dostępne tylko na hoście i używają Chrome MCP zamiast CDP.
-- Profile `existing-session` mogą ustawiać `userDataDir`, aby wskazać konkretny
- profil przeglądarki opartej na Chromium, taki jak Brave lub Edge.
-- Profile `existing-session` zachowują obecne ograniczenia trasy Chrome MCP:
- działania oparte na snapshot/ref zamiast targetowania selektorem CSS, hooki przesyłania
- pojedynczych plików, brak nadpisywania limitów czasu dialogów, brak `wait --load networkidle`,
- oraz brak `responsebody`, eksportu PDF, przechwytywania pobierania czy działań wsadowych.
-- Lokalne zarządzane profile `openclaw` automatycznie przypisują `cdpPort` i `cdpUrl`; jawnie
- ustawiaj `cdpUrl` tylko dla zdalnego CDP.
-- Kolejność auto-wykrywania: domyślna przeglądarka, jeśli oparta na Chromium → Chrome → Brave → Edge → Chromium → Chrome Canary.
+ Użyj HTTP(S), gdy chcesz, aby OpenClaw wykrył `/json/version`; użyj WS(S),
+ gdy dostawca udostępnia bezpośredni URL WebSocket DevTools.
+- Profile `existing-session` są tylko dla hosta i używają Chrome MCP zamiast CDP.
+- Profile `existing-session` mogą ustawiać `userDataDir`, aby kierować do konkretnego
+ profilu przeglądarki opartej na Chromium, takiej jak Brave lub Edge.
+- Profile `existing-session` zachowują bieżące limity trasy Chrome MCP:
+ działania oparte na snapshot/ref zamiast targetowania selektorem CSS, hooki
+ przesyłania pojedynczego pliku, brak nadpisań timeoutu dialogów, brak `wait --load networkidle`,
+ a także brak `responsebody`, eksportu PDF, przechwytywania pobrań i działań wsadowych.
+- Lokalne zarządzane profile `openclaw` automatycznie przypisują `cdpPort` i `cdpUrl`; ustawiaj
+ `cdpUrl` jawnie tylko dla zdalnego CDP.
+- Kolejność automatycznego wykrywania: domyślna przeglądarka, jeśli oparta na Chromium → Chrome → Brave → Edge → Chromium → Chrome Canary.
- Usługa sterowania: tylko loopback (port wyprowadzany z `gateway.port`, domyślnie `18791`).
-- `extraArgs` dołącza dodatkowe flagi uruchamiania do lokalnego startu Chromium (na przykład
- `--disable-gpu`, rozmiar okna albo flagi debugowania).
+- `extraArgs` dopisuje dodatkowe flagi uruchamiania do lokalnego startu Chromium (na przykład
+ `--disable-gpu`, rozmiar okna lub flagi debugowania).
---
@@ -2868,8 +2868,8 @@ Zobacz [Wtyczki](/pl/tools/plugin).
}
```
-- `seamColor`: kolor akcentu natywnego interfejsu aplikacji (odcień dymku trybu Talk itd.).
-- `assistant`: nadpisanie tożsamości Control UI. Wraca do tożsamości aktywnego agenta.
+- `seamColor`: kolor akcentu dla chromu natywnego UI aplikacji (odcień bąbelka Talk Mode itd.).
+- `assistant`: nadpisanie tożsamości Control UI. Wartość zapasowa pochodzi z aktywnej tożsamości agenta.
---
@@ -2902,6 +2902,8 @@ Zobacz [Wtyczki](/pl/tools/plugin).
enabled: true,
basePath: "/openclaw",
// root: "dist/control-ui",
+ // embedSandbox: "scripts", // strict | scripts | trusted
+ // allowExternalEmbedUrls: false, // dangerous: allow absolute external http(s) embed URLs
// allowedOrigins: ["https://control.example.com"], // required for non-loopback Control UI
// dangerouslyAllowHostHeaderOriginFallback: false, // dangerous Host-header origin fallback mode
// allowInsecureAuth: false,
@@ -2936,60 +2938,60 @@ Zobacz [Wtyczki](/pl/tools/plugin).
-- `mode`: `local` (uruchom bramę) albo `remote` (połącz ze zdalną bramą). Brama odmawia uruchomienia, jeśli nie jest ustawione `local`.
+- `mode`: `local` (uruchom bramę) lub `remote` (połącz ze zdalną bramą). Brama odmawia uruchomienia, jeśli nie jest ustawione `local`.
- `port`: pojedynczy multipleksowany port dla WS + HTTP. Priorytet: `--port` > `OPENCLAW_GATEWAY_PORT` > `gateway.port` > `18789`.
-- `bind`: `auto`, `loopback` (domyślnie), `lan` (`0.0.0.0`), `tailnet` (tylko IP Tailscale) albo `custom`.
+- `bind`: `auto`, `loopback` (domyślnie), `lan` (`0.0.0.0`), `tailnet` (tylko adres IP Tailscale) lub `custom`.
- **Starsze aliasy bind**: używaj wartości trybu bind w `gateway.bind` (`auto`, `loopback`, `lan`, `tailnet`, `custom`), a nie aliasów hosta (`0.0.0.0`, `127.0.0.1`, `localhost`, `::`, `::1`).
-- **Uwaga dotycząca Docker**: domyślne powiązanie `loopback` nasłuchuje na `127.0.0.1` wewnątrz kontenera. Przy sieci bridge Docker (`-p 18789:18789`) ruch trafia na `eth0`, więc brama jest nieosiągalna. Użyj `--network host` albo ustaw `bind: "lan"` (lub `bind: "custom"` z `customBindHost: "0.0.0.0"`), aby nasłuchiwać na wszystkich interfejsach.
-- **Auth**: domyślnie wymagane. Powiązania inne niż loopback wymagają uwierzytelnienia bramy. W praktyce oznacza to współdzielony token/hasło albo reverse proxy świadome tożsamości z `gateway.auth.mode: "trusted-proxy"`. Kreator onboardingu domyślnie generuje token.
-- Jeśli skonfigurowane są jednocześnie `gateway.auth.token` i `gateway.auth.password` (w tym SecretRef), ustaw jawnie `gateway.auth.mode` na `token` albo `password`. Uruchamianie oraz przepływy instalacji/naprawy usługi kończą się błędem, gdy skonfigurowane są oba, a tryb nie jest ustawiony.
-- `gateway.auth.mode: "none"`: jawny tryb bez uwierzytelniania. Używaj tylko dla zaufanych lokalnych konfiguracji local loopback; ta opcja celowo nie jest oferowana w promptach onboardingu.
-- `gateway.auth.mode: "trusted-proxy"`: deleguje uwierzytelnianie do reverse proxy świadomego tożsamości i ufa nagłówkom tożsamości od `gateway.trustedProxies` (zobacz [Trusted Proxy Auth](/pl/gateway/trusted-proxy-auth)). Ten tryb oczekuje źródła proxy **innego niż loopback**; reverse proxy loopback na tym samym hoście nie spełniają wymagań trusted-proxy auth.
-- `gateway.auth.allowTailscale`: gdy `true`, nagłówki tożsamości Tailscale Serve mogą spełniać wymagania uwierzytelniania Control UI/WebSocket (weryfikowane przez `tailscale whois`). Endpointy HTTP API **nie** używają tego uwierzytelniania nagłówkami Tailscale; zamiast tego stosują normalny tryb uwierzytelniania HTTP bramy. Ten beztokenowy przepływ zakłada, że host bramy jest zaufany. Domyślnie `true`, gdy `tailscale.mode = "serve"`.
-- `gateway.auth.rateLimit`: opcjonalny ogranicznik nieudanych prób uwierzytelniania. Ma zastosowanie per IP klienta i per zakres auth (współdzielony sekret i token urządzenia są śledzone niezależnie). Zablokowane próby zwracają `429` + `Retry-After`.
- - Na asynchronicznej ścieżce Tailscale Serve Control UI nieudane próby dla tego samego `{scope, clientIp}` są serializowane przed zapisem niepowodzenia. Współbieżne błędne próby od tego samego klienta mogą więc uruchomić ogranicznik przy drugim żądaniu zamiast obu przejść wyścigowo jako zwykłe niedopasowania.
- - `gateway.auth.rateLimit.exemptLoopback` domyślnie ma wartość `true`; ustaw `false`, gdy celowo chcesz również ograniczać ruch localhost (dla środowisk testowych albo ścisłych wdrożeń proxy).
-- Próby uwierzytelnienia WS pochodzące z przeglądarki są zawsze ograniczane z wyłączonym zwolnieniem loopback (obrona warstwowa przed atakami brute force na localhost z poziomu przeglądarki).
-- W loopback te blokady pochodzące z przeglądarki są izolowane per znormalizowana wartość `Origin`,
- więc powtarzające się niepowodzenia z jednego localhost origin nie blokują automatycznie
- innego origin.
-- `tailscale.mode`: `serve` (tylko tailnet, bind loopback) albo `funnel` (publiczny, wymaga auth).
-- `controlUi.allowedOrigins`: jawna lista dozwolonych origin przeglądarek dla połączeń Gateway WebSocket. Wymagana, gdy oczekiwani są klienci przeglądarkowi spoza origin loopback.
-- `controlUi.dangerouslyAllowHostHeaderOriginFallback`: niebezpieczny tryb, który włącza fallback origin oparty na nagłówku Host dla wdrożeń celowo polegających na zasadzie origin z nagłówka Host.
-- `remote.transport`: `ssh` (domyślnie) albo `direct` (ws/wss). Dla `direct`, `remote.url` musi mieć postać `ws://` albo `wss://`.
-- `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`: awaryjne nadpisanie po stronie klienta, które zezwala na jawne `ws://` do zaufanych prywatnych adresów IP; domyślnie jawny tekst pozostaje dozwolony tylko dla loopback.
-- `gateway.remote.token` / `.password` to pola poświadczeń klienta zdalnego. Same w sobie nie konfigurują uwierzytelniania bramy.
-- `gateway.push.apns.relay.baseUrl`: bazowy HTTPS URL zewnętrznego przekaźnika APNs używanego przez oficjalne/TestFlight buildy iOS po opublikowaniu przez nie rejestracji opartych na relay do bramy. Ten URL musi odpowiadać URL relay skompilowanemu w buildzie iOS.
-- `gateway.push.apns.relay.timeoutMs`: limit czasu wysyłania z bramy do relay w milisekundach. Domyślnie `10000`.
-- Rejestracje oparte na relay są delegowane do konkretnej tożsamości bramy. Sparowana aplikacja iOS pobiera `gateway.identity.get`, uwzględnia tę tożsamość w rejestracji relay i przekazuje do bramy uprawnienie wysyłki ograniczone do tej rejestracji. Inna brama nie może ponownie użyć tej zapisanej rejestracji.
-- `OPENCLAW_APNS_RELAY_BASE_URL` / `OPENCLAW_APNS_RELAY_TIMEOUT_MS`: tymczasowe nadpisania środowiskowe dla powyższej konfiguracji relay.
-- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true`: wyłącznie deweloperska furtka dla URL relay HTTP na loopback. Produkcyjne URL relay powinny pozostać przy HTTPS.
-- `gateway.channelHealthCheckMinutes`: interwał monitora zdrowia kanałów w minutach. Ustaw `0`, aby globalnie wyłączyć restarty monitora zdrowia. Domyślnie: `5`.
-- `gateway.channelStaleEventThresholdMinutes`: próg nieświeżego socketu w minutach. Zachowaj wartość większą lub równą `gateway.channelHealthCheckMinutes`. Domyślnie: `30`.
+- **Uwaga dotycząca Docker**: domyślny bind `loopback` nasłuchuje na `127.0.0.1` wewnątrz kontenera. Przy sieci bridge Docker (`-p 18789:18789`) ruch przychodzi na `eth0`, więc brama jest nieosiągalna. Użyj `--network host` albo ustaw `bind: "lan"` (lub `bind: "custom"` z `customBindHost: "0.0.0.0"`), aby nasłuchiwać na wszystkich interfejsach.
+- **Uwierzytelnianie**: domyślnie wymagane. Bindowania inne niż loopback wymagają uwierzytelniania bramy. W praktyce oznacza to współdzielony token/hasło albo reverse proxy świadome tożsamości z `gateway.auth.mode: "trusted-proxy"`. Kreator onboardingu domyślnie generuje token.
+- Jeśli skonfigurowano zarówno `gateway.auth.token`, jak i `gateway.auth.password` (w tym SecretRefs), ustaw jawnie `gateway.auth.mode` na `token` lub `password`. Uruchamianie oraz przepływy instalacji/naprawy usługi kończą się błędem, gdy skonfigurowano oba, a tryb nie jest ustawiony.
+- `gateway.auth.mode: "none"`: jawny tryb bez uwierzytelniania. Używaj tylko dla zaufanych lokalnych konfiguracji local loopback; celowo nie jest oferowany w promptach onboardingu.
+- `gateway.auth.mode: "trusted-proxy"`: deleguje uwierzytelnianie do reverse proxy świadomego tożsamości i ufa nagłówkom tożsamości od `gateway.trustedProxies` (zobacz [Trusted Proxy Auth](/pl/gateway/trusted-proxy-auth)). Ten tryb oczekuje źródła proxy **spoza loopback**; reverse proxy loopback na tym samym hoście nie spełniają wymagań uwierzytelniania trusted-proxy.
+- `gateway.auth.allowTailscale`: gdy `true`, nagłówki tożsamości Tailscale Serve mogą spełniać wymagania uwierzytelniania Control UI/WebSocket (weryfikowane przez `tailscale whois`). Punkty końcowe HTTP API **nie** używają tego uwierzytelniania nagłówkiem Tailscale; zamiast tego stosują zwykły tryb uwierzytelniania HTTP bramy. Ten przepływ bez tokena zakłada, że host bramy jest zaufany. Domyślnie `true`, gdy `tailscale.mode = "serve"`.
+- `gateway.auth.rateLimit`: opcjonalny limiter nieudanych prób uwierzytelniania. Stosowany per IP klienta i per zakres uwierzytelniania (współdzielony sekret i token urządzenia są śledzone niezależnie). Zablokowane próby zwracają `429` + `Retry-After`.
+ - Na asynchronicznej ścieżce Tailscale Serve Control UI nieudane próby dla tego samego `{scope, clientIp}` są serializowane przed zapisem niepowodzenia. Współbieżne błędne próby od tego samego klienta mogą więc uruchomić limiter przy drugim żądaniu zamiast tego, by oba przeszły wyścigowo jako zwykłe niedopasowania.
+ - `gateway.auth.rateLimit.exemptLoopback` domyślnie ma wartość `true`; ustaw `false`, gdy celowo chcesz również ograniczać ruchem localhost (dla konfiguracji testowych lub ścisłych wdrożeń z proxy).
+- Próby uwierzytelniania WS pochodzące z przeglądarki są zawsze ograniczane z wyłączonym zwolnieniem dla loopback (defense-in-depth przeciwko brute force localhost z przeglądarki).
+- W loopback te blokady pochodzenia z przeglądarki są izolowane per znormalizowana wartość `Origin`,
+ więc powtarzane niepowodzenia z jednego źródła localhost nie blokują automatycznie
+ innego źródła.
+- `tailscale.mode`: `serve` (tylko tailnet, bind loopback) lub `funnel` (publiczny, wymaga uwierzytelniania).
+- `controlUi.allowedOrigins`: jawna lista zezwoleń pochodzeń przeglądarki dla połączeń Gateway WebSocket. Wymagana, gdy oczekiwani są klienci przeglądarkowi z pochodzeń innych niż loopback.
+- `controlUi.dangerouslyAllowHostHeaderOriginFallback`: niebezpieczny tryb włączający zapasowe pochodzenie oparte na nagłówku Host dla wdrożeń, które celowo polegają na polityce pochodzenia opartej na nagłówku Host.
+- `remote.transport`: `ssh` (domyślnie) lub `direct` (ws/wss). Dla `direct` `remote.url` musi mieć postać `ws://` lub `wss://`.
+- `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`: klienckie nadpisanie break-glass, które zezwala na jawny `ws://` do zaufanych adresów IP sieci prywatnej; domyślnie jawny tekst pozostaje dozwolony tylko dla loopback.
+- `gateway.remote.token` / `.password` to pola poświadczeń zdalnego klienta. Same w sobie nie konfigurują uwierzytelniania bramy.
+- `gateway.push.apns.relay.baseUrl`: bazowy HTTPS URL zewnętrznego przekaźnika APNs używanego przez oficjalne/TestFlight buildy iOS po opublikowaniu przez nie rejestracji opartych na przekaźniku do bramy. Ten URL musi odpowiadać URL przekaźnika skompilowanemu w buildzie iOS.
+- `gateway.push.apns.relay.timeoutMs`: timeout wysyłania brama-do-przekaźnika w milisekundach. Domyślnie `10000`.
+- Rejestracje oparte na przekaźniku są delegowane do konkretnej tożsamości bramy. Sparowana aplikacja iOS pobiera `gateway.identity.get`, dołącza tę tożsamość do rejestracji przekaźnika i przekazuje do bramy uprawnienie wysyłania ograniczone do tej rejestracji. Inna brama nie może ponownie użyć tej zapisanej rejestracji.
+- `OPENCLAW_APNS_RELAY_BASE_URL` / `OPENCLAW_APNS_RELAY_TIMEOUT_MS`: tymczasowe nadpisania env dla powyższej konfiguracji przekaźnika.
+- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true`: wyjście awaryjne tylko do celów deweloperskich dla URL przekaźnika HTTP na loopback. Produkcyjne URL przekaźnika powinny pozostać na HTTPS.
+- `gateway.channelHealthCheckMinutes`: interwał monitora zdrowia kanału w minutach. Ustaw `0`, aby globalnie wyłączyć restarty monitora zdrowia. Domyślnie: `5`.
+- `gateway.channelStaleEventThresholdMinutes`: próg nieaktualnego gniazda w minutach. Utrzymuj wartość większą lub równą `gateway.channelHealthCheckMinutes`. Domyślnie: `30`.
- `gateway.channelMaxRestartsPerHour`: maksymalna liczba restartów monitora zdrowia na kanał/konto w ruchomej godzinie. Domyślnie: `10`.
-- `channels..healthMonitor.enabled`: per-kanałowy opt-out z restartów monitora zdrowia przy zachowaniu włączonego monitora globalnego.
-- `channels..accounts..healthMonitor.enabled`: nadpisanie per konto dla kanałów wielokontowych. Gdy ustawione, ma pierwszeństwo przed nadpisaniem na poziomie kanału.
-- Lokalne ścieżki wywołań bramy mogą używać `gateway.remote.*` jako fallback tylko wtedy, gdy `gateway.auth.*` nie jest ustawione.
-- Jeśli `gateway.auth.token` / `gateway.auth.password` jest jawnie skonfigurowane przez SecretRef i nierozwiązane, rozwiązywanie kończy się fail-closed (bez maskującego fallbacku zdalnego).
-- `trustedProxies`: adresy IP reverse proxy, które terminują TLS albo wstrzykują nagłówki klienta przekazanego dalej. Wymieniaj tylko proxy, które kontrolujesz. Wpisy loopback są nadal poprawne dla konfiguracji proxy na tym samym hoście / wykrywania lokalnego (na przykład Tailscale Serve albo lokalne reverse proxy), ale **nie** sprawiają, że żądania loopback kwalifikują się do `gateway.auth.mode: "trusted-proxy"`.
-- `allowRealIpFallback`: gdy `true`, brama akceptuje `X-Real-IP`, jeśli brakuje `X-Forwarded-For`. Domyślnie `false` dla zachowania fail-closed.
-- `gateway.tools.deny`: dodatkowe nazwy narzędzi blokowane dla HTTP `POST /tools/invoke` (rozszerza domyślną listę deny).
-- `gateway.tools.allow`: usuwa nazwy narzędzi z domyślnej listy deny HTTP.
+- `channels..healthMonitor.enabled`: per kanał opt-out z restartów monitora zdrowia przy zachowaniu globalnego monitora.
+- `channels..accounts..healthMonitor.enabled`: nadpisanie per konto dla kanałów wielokontowych. Gdy jest ustawione, ma pierwszeństwo przed nadpisaniem na poziomie kanału.
+- Lokalne ścieżki wywołań bramy mogą używać `gateway.remote.*` jako wartości zapasowej tylko wtedy, gdy `gateway.auth.*` nie jest ustawione.
+- Jeśli `gateway.auth.token` / `gateway.auth.password` jest jawnie skonfigurowane przez SecretRef i nierozwiązane, rozwiązywanie kończy się zamknięciem fail-closed (bez maskowania przez zdalny fallback).
+- `trustedProxies`: adresy IP reverse proxy, które kończą TLS lub wstrzykują nagłówki klienta przekierowanego. Wymieniaj tylko proxy, które kontrolujesz. Wpisy loopback nadal są prawidłowe dla konfiguracji proxy na tym samym hoście/lokalnego wykrywania (na przykład Tailscale Serve lub lokalne reverse proxy), ale **nie** sprawiają, że żądania loopback kwalifikują się do `gateway.auth.mode: "trusted-proxy"`.
+- `allowRealIpFallback`: gdy `true`, brama akceptuje `X-Real-IP`, jeśli brak `X-Forwarded-For`. Domyślnie `false` dla zachowania fail-closed.
+- `gateway.tools.deny`: dodatkowe nazwy narzędzi blokowane dla HTTP `POST /tools/invoke` (rozszerza domyślną listę odmów).
+- `gateway.tools.allow`: usuwa nazwy narzędzi z domyślnej listy odmów HTTP.
-### Endpointy zgodne z OpenAI
+### Punkty końcowe zgodne z OpenAI
- Chat Completions: domyślnie wyłączone. Włącz przez `gateway.http.endpoints.chatCompletions.enabled: true`.
- Responses API: `gateway.http.endpoints.responses.enabled`.
-- Utwardzanie wejść URL w Responses:
+- Utwardzanie wejścia URL w Responses:
- `gateway.http.endpoints.responses.maxUrlParts`
- `gateway.http.endpoints.responses.files.urlAllowlist`
- `gateway.http.endpoints.responses.images.urlAllowlist`
- Puste listy dozwolonych są traktowane jak nieustawione; użyj `gateway.http.endpoints.responses.files.allowUrl=false`
+ Puste listy zezwoleń są traktowane jak brak ustawienia; użyj `gateway.http.endpoints.responses.files.allowUrl=false`
i/lub `gateway.http.endpoints.responses.images.allowUrl=false`, aby wyłączyć pobieranie URL.
- Opcjonalny nagłówek utwardzający odpowiedzi:
- - `gateway.http.securityHeaders.strictTransportSecurity` (ustawiaj tylko dla kontrolowanych przez siebie origin HTTPS; zobacz [Trusted Proxy Auth](/pl/gateway/trusted-proxy-auth#tls-termination-and-hsts))
+ - `gateway.http.securityHeaders.strictTransportSecurity` (ustawiaj tylko dla kontrolowanych przez siebie źródeł HTTPS; zobacz [Trusted Proxy Auth](/pl/gateway/trusted-proxy-auth#tls-termination-and-hsts))
### Izolacja wielu instancji
@@ -3001,7 +3003,7 @@ OPENCLAW_STATE_DIR=~/.openclaw-a \
openclaw gateway --port 19001
```
-Wygodne flagi: `--dev` (używa `~/.openclaw-dev` + port `19001`), `--profile ` (używa `~/.openclaw-`).
+Wygodne flagi: `--dev` (używa `~/.openclaw-dev` + portu `19001`), `--profile ` (używa `~/.openclaw-`).
Zobacz [Wiele bram](/pl/gateway/multiple-gateways).
@@ -3022,10 +3024,10 @@ Zobacz [Wiele bram](/pl/gateway/multiple-gateways).
```
- `enabled`: włącza terminację TLS na listenerze bramy (HTTPS/WSS) (domyślnie: `false`).
-- `autoGenerate`: automatycznie generuje lokalną parę certyfikat/klucz z podpisem własnym, gdy nie skonfigurowano jawnych plików; tylko do użytku lokalnego/deweloperskiego.
+- `autoGenerate`: automatycznie generuje lokalną samopodpisaną parę certyfikat/klucz, gdy nie skonfigurowano jawnych plików; tylko do użytku lokalnego/deweloperskiego.
- `certPath`: ścieżka systemu plików do pliku certyfikatu TLS.
-- `keyPath`: ścieżka systemu plików do pliku prywatnego klucza TLS; zachowaj ograniczone uprawnienia.
-- `caPath`: opcjonalna ścieżka do pakietu CA dla weryfikacji klienta albo własnych łańcuchów zaufania.
+- `keyPath`: ścieżka systemu plików do pliku klucza prywatnego TLS; zachowaj ograniczone uprawnienia.
+- `caPath`: opcjonalna ścieżka do pakietu CA do weryfikacji klienta lub niestandardowych łańcuchów zaufania.
### `gateway.reload`
@@ -3042,10 +3044,10 @@ Zobacz [Wiele bram](/pl/gateway/multiple-gateways).
```
- `mode`: steruje sposobem stosowania edycji konfiguracji w runtime.
- - `"off"`: ignoruje edycje na żywo; zmiany wymagają jawnego restartu.
- - `"restart"`: zawsze restartuje proces bramy przy zmianie konfiguracji.
- - `"hot"`: stosuje zmiany w procesie bez restartu.
- - `"hybrid"` (domyślnie): najpierw próbuje hot reload; w razie potrzeby wraca do restartu.
+ - `"off"`: ignoruj edycje na żywo; zmiany wymagają jawnego restartu.
+ - `"restart"`: zawsze restartuj proces bramy przy zmianie konfiguracji.
+ - `"hot"`: stosuj zmiany w procesie bez restartu.
+ - `"hybrid"` (domyślnie): najpierw spróbuj hot reload; jeśli to konieczne, wróć do restartu.
- `debounceMs`: okno debounce w ms przed zastosowaniem zmian konfiguracji (nieujemna liczba całkowita).
- `deferralTimeoutMs`: maksymalny czas oczekiwania w ms na operacje w toku przed wymuszeniem restartu (domyślnie: `300000` = 5 minut).
@@ -3084,41 +3086,41 @@ Zobacz [Wiele bram](/pl/gateway/multiple-gateways).
}
```
-Auth: `Authorization: Bearer ` albo `x-openclaw-token: `.
+Uwierzytelnianie: `Authorization: Bearer ` lub `x-openclaw-token: `.
Tokeny hooków w query string są odrzucane.
Uwagi dotyczące walidacji i bezpieczeństwa:
- `hooks.enabled=true` wymaga niepustego `hooks.token`.
-- `hooks.token` musi być **różny** od `gateway.auth.token`; ponowne użycie tokenu bramy jest odrzucane.
+- `hooks.token` musi być **inne** niż `gateway.auth.token`; ponowne użycie tokenu bramy jest odrzucane.
- `hooks.path` nie może być `/`; użyj dedykowanej podścieżki, takiej jak `/hooks`.
- Jeśli `hooks.allowRequestSessionKey=true`, ogranicz `hooks.allowedSessionKeyPrefixes` (na przykład `["hook:"]`).
-**Endpointy:**
+**Punkty końcowe:**
- `POST /hooks/wake` → `{ text, mode?: "now"|"next-heartbeat" }`
- `POST /hooks/agent` → `{ message, name?, agentId?, sessionKey?, wakeMode?, deliver?, channel?, to?, model?, thinking?, timeoutSeconds? }`
- - `sessionKey` z ładunku żądania jest akceptowany tylko wtedy, gdy `hooks.allowRequestSessionKey=true` (domyślnie: `false`).
-- `POST /hooks/` → rozwiązywane przez `hooks.mappings`
+ - `sessionKey` z ładunku żądania jest akceptowane tylko wtedy, gdy `hooks.allowRequestSessionKey=true` (domyślnie: `false`).
+- `POST /hooks/` → rozstrzygane przez `hooks.mappings`
- `match.path` dopasowuje podścieżkę po `/hooks` (np. `/hooks/gmail` → `gmail`).
- `match.source` dopasowuje pole ładunku dla ścieżek ogólnych.
-- Szablony takie jak `{{messages[0].subject}}` odczytują wartości z ładunku.
+- Szablony takie jak `{{messages[0].subject}}` odczytują dane z ładunku.
- `transform` może wskazywać moduł JS/TS zwracający akcję hooka.
- - `transform.module` musi być ścieżką względną i pozostawać w obrębie `hooks.transformsDir` (ścieżki bezwzględne i traversal są odrzucane).
-- `agentId` kieruje do konkretnego agenta; nieznane ID wracają do agenta domyślnego.
-- `allowedAgentIds`: ogranicza jawny routing (`*` albo brak = zezwól na wszystkie, `[]` = zabroń wszystkim).
-- `defaultSessionKey`: opcjonalny stały klucz sesji dla uruchomień hooków agenta bez jawnego `sessionKey`.
+ - `transform.module` musi być ścieżką względną i pozostawać w obrębie `hooks.transformsDir` (ścieżki bezwzględne i przechodzenie po katalogach są odrzucane).
+- `agentId` kieruje do konkretnego agenta; nieznane identyfikatory wracają do agenta domyślnego.
+- `allowedAgentIds`: ogranicza jawne kierowanie (`*` lub pominięte = zezwól na wszystkie, `[]` = odmów wszystkim).
+- `defaultSessionKey`: opcjonalny stały klucz sesji dla uruchomień agenta hooków bez jawnego `sessionKey`.
- `allowRequestSessionKey`: pozwala wywołującym `/hooks/agent` ustawiać `sessionKey` (domyślnie: `false`).
-- `allowedSessionKeyPrefixes`: opcjonalna lista dozwolonych prefiksów dla jawnych wartości `sessionKey` (żądanie + mapowanie), np. `["hook:"]`.
-- `deliver: true` wysyła końcową odpowiedź do kanału; `channel` domyślnie ma wartość `last`.
+- `allowedSessionKeyPrefixes`: opcjonalna lista zezwoleń prefiksów dla jawnych wartości `sessionKey` (żądanie + mapowanie), np. `["hook:"]`.
+- `deliver: true` wysyła odpowiedź końcową do kanału; `channel` domyślnie ma wartość `last`.
- `model` nadpisuje LLM dla tego uruchomienia hooka (musi być dozwolony, jeśli ustawiono katalog modeli).
-### Integracja z Gmail
+### Integracja Gmail
```json5
{
@@ -3141,7 +3143,7 @@ Uwagi dotyczące walidacji i bezpieczeństwa:
}
```
-- Brama automatycznie uruchamia `gog gmail watch serve` przy starcie, gdy jest skonfigurowane. Ustaw `OPENCLAW_SKIP_GMAIL_WATCHER=1`, aby to wyłączyć.
+- Brama automatycznie uruchamia `gog gmail watch serve` przy starcie, gdy jest skonfigurowane. Ustaw `OPENCLAW_SKIP_GMAIL_WATCHER=1`, aby wyłączyć.
- Nie uruchamiaj osobnego `gog gmail watch serve` równolegle z bramą.
---
@@ -3158,18 +3160,18 @@ Uwagi dotyczące walidacji i bezpieczeństwa:
}
```
-- Udostępnia edytowalne przez agenta HTML/CSS/JS i A2UI przez HTTP pod portem bramy:
+- Udostępnia edytowalne przez agenta HTML/CSS/JS oraz A2UI przez HTTP pod portem bramy:
- `http://:/__openclaw__/canvas/`
- `http://:/__openclaw__/a2ui/`
- Tylko lokalnie: zachowaj `gateway.bind: "loopback"` (domyślnie).
-- Powiązania inne niż loopback: trasy canvas wymagają uwierzytelniania bramy (token/hasło/trusted-proxy), tak samo jak inne powierzchnie HTTP bramy.
-- Node WebViews zazwyczaj nie wysyłają nagłówków auth; po sparowaniu i połączeniu noda brama reklamuje URL zdolności o zakresie noda dla dostępu do canvas/A2UI.
-- URL zdolności są powiązane z aktywną sesją WS noda i szybko wygasają. Fallback oparty na IP nie jest używany.
+- Bindowania inne niż loopback: ścieżki canvas wymagają uwierzytelniania bramy (token/hasło/trusted-proxy), tak samo jak inne powierzchnie HTTP bramy.
+- Node WebViews zwykle nie wysyłają nagłówków uwierzytelniania; po sparowaniu i połączeniu noda brama reklamuje adresy URL możliwości o zakresie noda do dostępu do canvas/A2UI.
+- Adresy URL możliwości są powiązane z aktywną sesją WS noda i szybko wygasają. Nie jest używany fallback oparty na IP.
- Wstrzykuje klienta live-reload do serwowanego HTML.
- Automatycznie tworzy startowy `index.html`, gdy katalog jest pusty.
-- Udostępnia także A2UI pod `/__openclaw__/a2ui/`.
+- Udostępnia również A2UI pod `/__openclaw__/a2ui/`.
- Zmiany wymagają restartu bramy.
-- Wyłącz live reload dla dużych katalogów albo przy błędach `EMFILE`.
+- Wyłącz live reload dla dużych katalogów lub błędów `EMFILE`.
---
@@ -3188,7 +3190,7 @@ Uwagi dotyczące walidacji i bezpieczeństwa:
```
- `minimal` (domyślnie): pomija `cliPath` + `sshPort` z rekordów TXT.
-- `full`: dołącza `cliPath` + `sshPort`.
+- `full`: zawiera `cliPath` + `sshPort`.
- Nazwa hosta domyślnie to `openclaw`. Nadpisz przez `OPENCLAW_MDNS_HOSTNAME`.
### Szeroki obszar (DNS-SD)
@@ -3201,7 +3203,7 @@ Uwagi dotyczące walidacji i bezpieczeństwa:
}
```
-Zapisuje strefę unicast DNS-SD w `~/.openclaw/dns/`. Do wykrywania między sieciami połącz to z serwerem DNS (zalecany CoreDNS) + split DNS Tailscale.
+Zapisuje strefę unicast DNS-SD w `~/.openclaw/dns/`. Dla wykrywania między sieciami połącz z serwerem DNS (zalecany CoreDNS) + split DNS Tailscale.
Konfiguracja: `openclaw dns setup --apply`.
@@ -3209,7 +3211,7 @@ Konfiguracja: `openclaw dns setup --apply`.
## Środowisko
-### `env` (inline env vars)
+### `env` (zmienne env inline)
```json5
{
@@ -3226,14 +3228,14 @@ Konfiguracja: `openclaw dns setup --apply`.
}
```
-- Inline env vars są stosowane tylko wtedy, gdy w środowisku procesu brakuje danego klucza.
-- Pliki `.env`: `.env` z CWD + `~/.openclaw/.env` (żaden nie nadpisuje istniejących zmiennych).
+- Zmienne env inline są stosowane tylko wtedy, gdy w środowisku procesu brakuje tego klucza.
+- Pliki `.env`: `.env` z bieżącego katalogu roboczego + `~/.openclaw/.env` (żaden nie nadpisuje istniejących zmiennych).
- `shellEnv`: importuje brakujące oczekiwane klucze z profilu powłoki logowania.
-- Pełną kolejność priorytetów znajdziesz w [Środowisko](/pl/help/environment).
+- Pełny priorytet znajdziesz w [Środowisko](/pl/help/environment).
-### Podstawianie zmiennych środowiskowych
+### Podstawianie zmiennych env
-Odwołuj się do zmiennych środowiskowych w dowolnym ciągu konfiguracji za pomocą `${VAR_NAME}`:
+Odwołuj się do zmiennych env w dowolnym ciągu konfiguracji przez `${VAR_NAME}`:
```json5
{
@@ -3243,20 +3245,20 @@ Odwołuj się do zmiennych środowiskowych w dowolnym ciągu konfiguracji za pom
}
```
-- Dopasowywane są tylko nazwy wielkimi literami: `[A-Z_][A-Z0-9_]*`.
-- Brakujące/puste zmienne powodują błąd podczas wczytywania konfiguracji.
-- Escapuj przez `$${VAR}`, aby uzyskać dosłowne `${VAR}`.
+- Dopasowywane są tylko nazwy pisane wielkimi literami: `[A-Z_][A-Z0-9_]*`.
+- Brakujące/puste zmienne powodują błąd przy ładowaniu konfiguracji.
+- Użyj `$${VAR}`, aby uzyskać dosłowne `${VAR}`.
- Działa z `$include`.
---
## Sekrety
-Odwołania do sekretów są addytywne: zwykłe wartości tekstowe nadal działają.
+Odwołania SecretRef są addytywne: zwykłe wartości tekstowe nadal działają.
### `SecretRef`
-Używaj jednego kształtu obiektu:
+Użyj jednej postaci obiektu:
```json5
{ source: "env" | "file" | "exec", provider: "default", id: "..." }
@@ -3266,15 +3268,15 @@ Walidacja:
- wzorzec `provider`: `^[a-z][a-z0-9_-]{0,63}$`
- wzorzec `id` dla `source: "env"`: `^[A-Z][A-Z0-9_]{0,127}$`
-- `id` dla `source: "file"`: bezwzględny wskaźnik JSON (np. `"/providers/openai/apiKey"`)
+- `source: "file"` `id`: bezwzględny wskaźnik JSON (na przykład `"/providers/openai/apiKey"`)
- wzorzec `id` dla `source: "exec"`: `^[A-Za-z0-9][A-Za-z0-9._:/-]{0,255}$`
-- `id` dla `source: "exec"` nie może zawierać segmentów ścieżki `.` ani `..` oddzielonych ukośnikami (na przykład `a/../b` jest odrzucane)
+- identyfikatory `source: "exec"` nie mogą zawierać segmentów ścieżki `.` ani `..` oddzielonych ukośnikami (na przykład `a/../b` jest odrzucane)
### Obsługiwana powierzchnia poświadczeń
-- Kanoniczna macierz: [Powierzchnia poświadczeń SecretRef](/pl/reference/secretref-credential-surface)
-- `secrets apply` kieruje na obsługiwane ścieżki poświadczeń w `openclaw.json`.
-- Odwołania w `auth-profiles.json` są uwzględniane w runtime resolution i pokryciu audytu.
+- Macierz kanoniczna: [Powierzchnia poświadczeń SecretRef](/pl/reference/secretref-credential-surface)
+- `secrets apply` kieruje do obsługiwanych ścieżek poświadczeń w `openclaw.json`.
+- Odwołania `auth-profiles.json` są uwzględniane w rozwiązywaniu runtime i pokryciu audytu.
### Konfiguracja dostawców sekretów
@@ -3306,17 +3308,17 @@ Walidacja:
Uwagi:
-- Dostawca `file` obsługuje `mode: "json"` i `mode: "singleValue"` (`id` musi mieć wartość `"value"` w trybie singleValue).
+- Dostawca `file` obsługuje `mode: "json"` i `mode: "singleValue"` (w trybie singleValue `id` musi mieć wartość `"value"`).
- Dostawca `exec` wymaga bezwzględnej ścieżki `command` i używa ładunków protokołu na stdin/stdout.
-- Domyślnie ścieżki poleceń będące dowiązaniami symbolicznymi są odrzucane. Ustaw `allowSymlinkCommand: true`, aby zezwolić na ścieżki symlink przy jednoczesnej walidacji ścieżki rozwiązanej.
-- Jeśli skonfigurowano `trustedDirs`, kontrola zaufanych katalogów dotyczy ścieżki rozwiązanej.
-- Środowisko procesu potomnego `exec` jest domyślnie minimalne; wymagane zmienne przekazuj jawnie przez `passEnv`.
-- Odwołania do sekretów są rozwiązywane w czasie aktywacji do migawki w pamięci, a następnie ścieżki żądań odczytują wyłącznie tę migawkę.
-- Podczas aktywacji stosowane jest filtrowanie aktywnej powierzchni: nierozwiązane odwołania na włączonych powierzchniach powodują błąd startu/przeładowania, a nieaktywne powierzchnie są pomijane z diagnostyką.
+- Domyślnie ścieżki poleceń będące symlinkami są odrzucane. Ustaw `allowSymlinkCommand: true`, aby zezwolić na ścieżki symlink przy jednoczesnej walidacji ścieżki docelowej po rozwiązaniu.
+- Jeśli skonfigurowano `trustedDirs`, sprawdzanie zaufanych katalogów dotyczy ścieżki docelowej po rozwiązaniu.
+- Środowisko potomne `exec` jest domyślnie minimalne; przekaż wymagane zmienne jawnie przez `passEnv`.
+- Odwołania do sekretów są rozwiązywane w chwili aktywacji do migawki w pamięci, a ścieżki żądań odczytują tylko tę migawkę.
+- Podczas aktywacji stosowane jest filtrowanie aktywnej powierzchni: nierozwiązane odwołania na włączonych powierzchniach powodują błąd uruchomienia/przeładowania, natomiast nieaktywne powierzchnie są pomijane z diagnostyką.
---
-## Magazyn auth
+## Magazyn uwierzytelniania
```json5
{
@@ -3336,9 +3338,9 @@ Uwagi:
- Profile per agent są przechowywane w `/auth-profiles.json`.
- `auth-profiles.json` obsługuje odwołania na poziomie wartości (`keyRef` dla `api_key`, `tokenRef` dla `token`) dla statycznych trybów poświadczeń.
-- Profile trybu OAuth (`auth.profiles..mode = "oauth"`) nie obsługują poświadczeń profili auth opartych na SecretRef.
+- Profile w trybie OAuth (`auth.profiles..mode = "oauth"`) nie obsługują poświadczeń auth-profile opartych na SecretRef.
- Statyczne poświadczenia runtime pochodzą z rozwiązanych migawek w pamięci; starsze statyczne wpisy `auth.json` są czyszczone po wykryciu.
-- Starsze importy OAuth pochodzą z `~/.openclaw/credentials/oauth.json`.
+- Starsze importy OAuth z `~/.openclaw/credentials/oauth.json`.
- Zobacz [OAuth](/pl/concepts/oauth).
- Zachowanie runtime sekretów oraz narzędzia `audit/configure/apply`: [Zarządzanie sekretami](/pl/gateway/secrets).
@@ -3362,20 +3364,20 @@ Uwagi:
}
```
-- `billingBackoffHours`: bazowy backoff w godzinach, gdy profil kończy się niepowodzeniem z powodu rzeczywistych błędów billing/braku środków
- (domyślnie: `5`). Jawny tekst billing może
- nadal trafić tutaj nawet przy odpowiedziach `401`/`403`, ale matchery tekstowe
- specyficzne dla dostawcy pozostają ograniczone do dostawcy, który nimi zarządza (na przykład OpenRouter
- `Key limit exceeded`). Żądania HTTP `402`, które można ponowić z powodu okna użycia lub
- komunikatów limitu wydatków organizacji/workspace, pozostają zamiast tego w ścieżce `rate_limit`.
-- `billingBackoffHoursByProvider`: opcjonalne nadpisania godzin backoff billing per dostawca.
-- `billingMaxHours`: limit w godzinach dla wykładniczego wzrostu backoff billing (domyślnie: `24`).
+- `billingBackoffHours`: bazowy backoff w godzinach, gdy profil kończy się błędem z powodu rzeczywistych
+ błędów rozliczeniowych/braku środków (domyślnie: `5`). Jawny tekst billingowy może
+ nadal trafić tutaj nawet przy odpowiedziach `401`/`403`, ale dopasowania tekstu specyficzne
+ dla dostawcy pozostają ograniczone do dostawcy, który nimi zarządza (na przykład OpenRouter
+ `Key limit exceeded`). Odpowiedzi `402` retryable dotyczące okna użycia lub
+ komunikaty limitów wydatków organizacji/obszaru roboczego pozostają zamiast tego w ścieżce `rate_limit`.
+- `billingBackoffHoursByProvider`: opcjonalne nadpisania per dostawca dla godzin backoff rozliczeń.
+- `billingMaxHours`: limit w godzinach dla wykładniczego wzrostu backoff rozliczeń (domyślnie: `24`).
- `authPermanentBackoffMinutes`: bazowy backoff w minutach dla błędów `auth_permanent` o wysokiej pewności (domyślnie: `10`).
- `authPermanentMaxMinutes`: limit w minutach dla wzrostu backoff `auth_permanent` (domyślnie: `60`).
- `failureWindowHours`: ruchome okno w godzinach używane dla liczników backoff (domyślnie: `24`).
-- `overloadedProfileRotations`: maksymalna liczba rotacji profili auth tego samego dostawcy dla błędów przeciążenia przed przełączeniem na fallback modelu (domyślnie: `1`). Wzorce typu provider-busy, takie jak `ModelNotReadyException`, trafiają tutaj.
-- `overloadedBackoffMs`: stałe opóźnienie przed ponowną próbą rotacji przeciążonego dostawcy/profilu (domyślnie: `0`).
-- `rateLimitedProfileRotations`: maksymalna liczba rotacji profili auth tego samego dostawcy dla błędów rate limit przed przełączeniem na fallback modelu (domyślnie: `1`). Ten koszyk rate limit obejmuje teksty charakterystyczne dla dostawcy, takie jak `Too many concurrent requests`, `ThrottlingException`, `concurrency limit reached`, `workers_ai ... quota limit exceeded` i `resource exhausted`.
+- `overloadedProfileRotations`: maksymalna liczba rotacji auth-profile tego samego dostawcy dla błędów przeciążenia przed przełączeniem na fallback modelu (domyślnie: `1`). Kształty typu provider-busy, takie jak `ModelNotReadyException`, trafiają tutaj.
+- `overloadedBackoffMs`: stałe opóźnienie przed ponowieniem rotacji przeciążonego dostawcy/profilu (domyślnie: `0`).
+- `rateLimitedProfileRotations`: maksymalna liczba rotacji auth-profile tego samego dostawcy dla błędów limitu szybkości przed przełączeniem na fallback modelu (domyślnie: `1`). Ten koszyk `rate_limit` obejmuje teksty w stylu dostawcy, takie jak `Too many concurrent requests`, `ThrottlingException`, `concurrency limit reached`, `workers_ai ... quota limit exceeded` i `resource exhausted`.
---
@@ -3395,9 +3397,9 @@ Uwagi:
```
- Domyślny plik logu: `/tmp/openclaw/openclaw-YYYY-MM-DD.log`.
-- Ustaw `logging.file` dla stałej ścieżki.
-- `consoleLevel` podnosi się do `debug`, gdy użyto `--verbose`.
-- `maxFileBytes`: maksymalny rozmiar pliku logu w bajtach, po którego przekroczeniu zapisy są wstrzymywane (dodatnia liczba całkowita; domyślnie: `524288000` = 500 MB). W środowiskach produkcyjnych używaj zewnętrznej rotacji logów.
+- Ustaw `logging.file`, aby użyć stałej ścieżki.
+- `consoleLevel` podnosi się do `debug` przy `--verbose`.
+- `maxFileBytes`: maksymalny rozmiar pliku logu w bajtach, po którym zapisy są wstrzymywane (dodatnia liczba całkowita; domyślnie: `524288000` = 500 MB). W środowiskach produkcyjnych używaj zewnętrznej rotacji logów.
---
@@ -3435,19 +3437,19 @@ Uwagi:
```
- `enabled`: główny przełącznik wyjścia instrumentacji (domyślnie: `true`).
-- `flags`: tablica ciągów flag włączających ukierunkowane wyjście logów (obsługuje wildcardy takie jak `"telegram.*"` albo `"*"`).
+- `flags`: tablica ciągów flag włączających ukierunkowane wyjście logów (obsługuje wildcardy, takie jak `"telegram.*"` lub `"*"`).
- `stuckSessionWarnMs`: próg wieku w ms dla emitowania ostrzeżeń o zablokowanej sesji, gdy sesja pozostaje w stanie przetwarzania.
- `otel.enabled`: włącza pipeline eksportu OpenTelemetry (domyślnie: `false`).
-- `otel.endpoint`: URL collectora dla eksportu OTel.
-- `otel.protocol`: `"http/protobuf"` (domyślnie) albo `"grpc"`.
-- `otel.headers`: dodatkowe nagłówki metadanych HTTP/gRPC wysyłane wraz z żądaniami eksportu OTel.
+- `otel.endpoint`: URL kolektora dla eksportu OTel.
+- `otel.protocol`: `"http/protobuf"` (domyślnie) lub `"grpc"`.
+- `otel.headers`: dodatkowe nagłówki metadanych HTTP/gRPC wysyłane z żądaniami eksportu OTel.
- `otel.serviceName`: nazwa usługi dla atrybutów zasobu.
-- `otel.traces` / `otel.metrics` / `otel.logs`: włącza eksport trace, metrics albo logów.
+- `otel.traces` / `otel.metrics` / `otel.logs`: włączają eksport trace, metrics lub logs.
- `otel.sampleRate`: współczynnik próbkowania trace `0`–`1`.
- `otel.flushIntervalMs`: okresowy interwał flush telemetrii w ms.
-- `cacheTrace.enabled`: zapisuje migawki cache trace dla osadzonych przebiegów (domyślnie: `false`).
-- `cacheTrace.filePath`: ścieżka wyjściowa dla cache trace JSONL (domyślnie: `$OPENCLAW_STATE_DIR/logs/cache-trace.jsonl`).
-- `cacheTrace.includeMessages` / `includePrompt` / `includeSystem`: kontroluje, co jest uwzględniane w wyjściu cache trace (wszystkie domyślnie: `true`).
+- `cacheTrace.enabled`: zapisuje migawki śledzenia cache dla uruchomień osadzonych (domyślnie: `false`).
+- `cacheTrace.filePath`: ścieżka wyjściowa dla JSONL śledzenia cache (domyślnie: `$OPENCLAW_STATE_DIR/logs/cache-trace.jsonl`).
+- `cacheTrace.includeMessages` / `includePrompt` / `includeSystem`: sterują tym, co jest uwzględniane w wyjściu śledzenia cache (wszystkie domyślnie: `true`).
---
@@ -3469,12 +3471,12 @@ Uwagi:
}
```
-- `channel`: kanał wydań dla instalacji npm/git — `"stable"`, `"beta"` albo `"dev"`.
-- `checkOnStart`: sprawdza aktualizacje npm przy uruchomieniu bramy (domyślnie: `true`).
-- `auto.enabled`: włącza automatyczną aktualizację w tle dla instalacji pakietowych (domyślnie: `false`).
+- `channel`: kanał wydań dla instalacji npm/git — `"stable"`, `"beta"` lub `"dev"`.
+- `checkOnStart`: sprawdza aktualizacje npm przy uruchamianiu bramy (domyślnie: `true`).
+- `auto.enabled`: włącza automatyczne aktualizacje w tle dla instalacji pakietów (domyślnie: `false`).
- `auto.stableDelayHours`: minimalne opóźnienie w godzinach przed automatycznym zastosowaniem na kanale stable (domyślnie: `6`; maks.: `168`).
-- `auto.stableJitterHours`: dodatkowe okno rozłożenia wdrażania stable w godzinach (domyślnie: `12`; maks.: `168`).
-- `auto.betaCheckIntervalHours`: jak często uruchamiane są kontrole kanału beta w godzinach (domyślnie: `1`; maks.: `24`).
+- `auto.stableJitterHours`: dodatkowe okno rozproszenia wdrożenia kanału stable w godzinach (domyślnie: `12`; maks.: `168`).
+- `auto.betaCheckIntervalHours`: jak często uruchamiane są sprawdzenia kanału beta, w godzinach (domyślnie: `1`; maks.: `24`).
---
@@ -3508,21 +3510,21 @@ Uwagi:
```
- `enabled`: globalna bramka funkcji ACP (domyślnie: `false`).
-- `dispatch.enabled`: niezależna bramka dla dyspozycji tur sesji ACP (domyślnie: `true`). Ustaw `false`, aby zachować dostępność poleceń ACP przy jednoczesnym blokowaniu wykonania.
-- `backend`: domyślne id backendu runtime ACP (musi odpowiadać zarejestrowanej wtyczce runtime ACP).
-- `defaultAgent`: zapasowe id docelowego agenta ACP, gdy uruchomienia nie wskazują jawnego celu.
-- `allowedAgents`: lista dozwolonych id agentów dopuszczonych do sesji runtime ACP; pusta oznacza brak dodatkowego ograniczenia.
+- `dispatch.enabled`: niezależna bramka dla wysyłania tur sesji ACP (domyślnie: `true`). Ustaw `false`, aby zachować dostępność poleceń ACP przy jednoczesnym blokowaniu wykonania.
+- `backend`: domyślny identyfikator backendu runtime ACP (musi odpowiadać zarejestrowanemu pluginowi runtime ACP).
+- `defaultAgent`: zapasowy identyfikator docelowego agenta ACP, gdy uruchomienia nie wskazują jawnego celu.
+- `allowedAgents`: lista zezwoleń identyfikatorów agentów dozwolonych dla sesji runtime ACP; pusta oznacza brak dodatkowego ograniczenia.
- `maxConcurrentSessions`: maksymalna liczba jednocześnie aktywnych sesji ACP.
-- `stream.coalesceIdleMs`: okno bezczynności w ms dla flush strumieniowanego tekstu.
-- `stream.maxChunkChars`: maksymalny rozmiar segmentu przed podzieleniem projekcji strumieniowanego bloku.
-- `stream.repeatSuppression`: tłumi powtarzane linie statusu/narzędzi per tura (domyślnie: `true`).
-- `stream.deliveryMode`: `"live"` strumieniuje przyrostowo; `"final_only"` buforuje do końcowych zdarzeń tury.
+- `stream.coalesceIdleMs`: okno flush bezczynności w ms dla strumieniowanego tekstu.
+- `stream.maxChunkChars`: maksymalny rozmiar części przed podziałem projekcji strumieniowanego bloku.
+- `stream.repeatSuppression`: tłumi powtarzające się linie statusu/narzędzi per tura (domyślnie: `true`).
+- `stream.deliveryMode`: `"live"` strumieniuje przyrostowo; `"final_only"` buforuje aż do terminalnych zdarzeń tury.
- `stream.hiddenBoundarySeparator`: separator przed widocznym tekstem po ukrytych zdarzeniach narzędzi (domyślnie: `"paragraph"`).
-- `stream.maxOutputChars`: maksymalna liczba znaków wyjścia asystenta projektowana per tura ACP.
+- `stream.maxOutputChars`: maksymalna liczba znaków wyjścia asystenta projektowana na turę ACP.
- `stream.maxSessionUpdateChars`: maksymalna liczba znaków dla projektowanych linii statusu/aktualizacji ACP.
-- `stream.tagVisibility`: zapis mapowania nazw tagów do logicznych nadpisań widoczności dla zdarzeń strumieniowanych.
-- `runtime.ttlMinutes`: bezczynny TTL w minutach dla workerów sesji ACP, po którym kwalifikują się do czyszczenia.
-- `runtime.installCommand`: opcjonalne polecenie instalacji uruchamiane przy bootstrapowaniu środowiska runtime ACP.
+- `stream.tagVisibility`: zapis nazw tagów do logicznych nadpisań widoczności dla strumieniowanych zdarzeń.
+- `runtime.ttlMinutes`: TTL bezczynności w minutach dla workerów sesji ACP przed kwalifikacją do czyszczenia.
+- `runtime.installCommand`: opcjonalne polecenie instalacji uruchamiane podczas bootstrapowania środowiska runtime ACP.
---
@@ -3538,11 +3540,11 @@ Uwagi:
}
```
-- `cli.banner.taglineMode` steruje stylem sloganu banera:
+- `cli.banner.taglineMode` steruje stylem sloganu bannera:
- `"random"` (domyślnie): rotujące zabawne/sezonowe slogany.
- `"default"`: stały neutralny slogan (`All your chats, one OpenClaw.`).
- - `"off"`: brak tekstu sloganu (tytuł/wersja banera nadal są wyświetlane).
-- Aby ukryć cały baner (nie tylko slogany), ustaw env `OPENCLAW_HIDE_BANNER=1`.
+ - `"off"`: brak tekstu sloganu (tytuł/wersja bannera nadal są pokazywane).
+- Aby ukryć cały banner (nie tylko slogany), ustaw env `OPENCLAW_HIDE_BANNER=1`.
---
@@ -3570,11 +3572,11 @@ Zobacz pola tożsamości `agents.list` w sekcji [Domyślne ustawienia agentów](
---
-## Bridge (starszy, usunięty)
+## Bridge (starsze, usunięte)
Bieżące buildy nie zawierają już TCP bridge. Nody łączą się przez Gateway WebSocket. Klucze `bridge.*` nie są już częścią schematu konfiguracji (walidacja kończy się błędem, dopóki nie zostaną usunięte; `openclaw doctor --fix` może usunąć nieznane klucze).
-
+
```json
{
@@ -3612,10 +3614,10 @@ Bieżące buildy nie zawierają już TCP bridge. Nody łączą się przez Gatewa
}
```
-- `sessionRetention`: jak długo przechowywać ukończone izolowane sesje uruchomień cron przed usunięciem z `sessions.json`. Steruje też czyszczeniem zarchiwizowanych usuniętych transkryptów cron. Domyślnie: `24h`; ustaw `false`, aby wyłączyć.
-- `runLog.maxBytes`: maksymalny rozmiar pliku logu pojedynczego uruchomienia (`cron/runs/.jsonl`) przed przycięciem. Domyślnie: `2_000_000` bajtów.
+- `sessionRetention`: jak długo zachowywać ukończone sesje izolowanych uruchomień cron przed usunięciem z `sessions.json`. Steruje także czyszczeniem zarchiwizowanych usuniętych transkryptów cron. Domyślnie: `24h`; ustaw `false`, aby wyłączyć.
+- `runLog.maxBytes`: maksymalny rozmiar pliku logu per uruchomienie (`cron/runs/.jsonl`) przed przycięciem. Domyślnie: `2_000_000` bajtów.
- `runLog.keepLines`: liczba najnowszych linii zachowywanych po uruchomieniu przycinania logu. Domyślnie: `2000`.
-- `webhookToken`: token bearer używany do dostarczania webhooków cron przez POST (`delivery.mode = "webhook"`); jeśli pominięty, żaden nagłówek auth nie jest wysyłany.
+- `webhookToken`: token bearer używany do dostarczania POST webhooków cron (`delivery.mode = "webhook"`); jeśli pominięty, nie jest wysyłany nagłówek auth.
- `webhook`: przestarzały starszy zapasowy URL webhooka (http/https) używany tylko dla zapisanych zadań, które nadal mają `notify: true`.
### `cron.retry`
@@ -3634,9 +3636,9 @@ Bieżące buildy nie zawierają już TCP bridge. Nody łączą się przez Gatewa
- `maxAttempts`: maksymalna liczba ponowień dla zadań jednorazowych przy błędach przejściowych (domyślnie: `3`; zakres: `0`–`10`).
- `backoffMs`: tablica opóźnień backoff w ms dla każdej próby ponowienia (domyślnie: `[30000, 60000, 300000]`; 1–10 wpisów).
-- `retryOn`: typy błędów wyzwalające ponowienia — `"rate_limit"`, `"overloaded"`, `"network"`, `"timeout"`, `"server_error"`. Pomiń, aby ponawiać wszystkie typy przejściowe.
+- `retryOn`: typy błędów wywołujące ponowienia — `"rate_limit"`, `"overloaded"`, `"network"`, `"timeout"`, `"server_error"`. Pomiń, aby ponawiać dla wszystkich typów przejściowych.
-Dotyczy tylko jednorazowych zadań cron. Zadania cykliczne używają osobnej obsługi niepowodzeń.
+Dotyczy tylko jednorazowych zadań cron. Zadania cykliczne używają oddzielnej obsługi błędów.
### `cron.failureAlert`
@@ -3654,11 +3656,11 @@ Dotyczy tylko jednorazowych zadań cron. Zadania cykliczne używają osobnej obs
}
```
-- `enabled`: włącza alerty o niepowodzeniach dla zadań cron (domyślnie: `false`).
-- `after`: liczba kolejnych niepowodzeń przed wysłaniem alertu (dodatnia liczba całkowita, min.: `1`).
-- `cooldownMs`: minimalna liczba milisekund między powtarzającymi się alertami dla tego samego zadania (nieujemna liczba całkowita).
-- `mode`: tryb dostarczania — `"announce"` wysyła przez wiadomość kanałową; `"webhook"` wysyła POST do skonfigurowanego webhooka.
-- `accountId`: opcjonalne id konta lub kanału do określenia zakresu dostarczania alertu.
+- `enabled`: włącza alerty o błędach dla zadań cron (domyślnie: `false`).
+- `after`: liczba kolejnych błędów przed wyzwoleniem alertu (dodatnia liczba całkowita, min.: `1`).
+- `cooldownMs`: minimalna liczba milisekund między powtarzanymi alertami dla tego samego zadania (nieujemna liczba całkowita).
+- `mode`: tryb dostarczania — `"announce"` wysyła przez wiadomość kanałową; `"webhook"` wykonuje POST do skonfigurowanego webhooka.
+- `accountId`: opcjonalny identyfikator konta lub kanału do ograniczenia dostarczania alertu.
### `cron.failureDestination`
@@ -3675,16 +3677,16 @@ Dotyczy tylko jednorazowych zadań cron. Zadania cykliczne używają osobnej obs
}
```
-- Domyślny cel powiadomień o niepowodzeniach cron dla wszystkich zadań.
-- `mode`: `"announce"` albo `"webhook"`; domyślnie `"announce"`, gdy istnieją wystarczające dane celu.
+- Domyślny cel powiadomień o błędach cron dla wszystkich zadań.
+- `mode`: `"announce"` lub `"webhook"`; domyślnie `"announce"`, gdy istnieje wystarczająco dużo danych celu.
- `channel`: nadpisanie kanału dla dostarczania announce. `"last"` ponownie używa ostatniego znanego kanału dostarczenia.
-- `to`: jawny cel announce albo URL webhooka. Wymagane w trybie webhook.
+- `to`: jawny cel announce lub URL webhooka. Wymagane dla trybu webhook.
- `accountId`: opcjonalne nadpisanie konta dla dostarczania.
- `delivery.failureDestination` per zadanie nadpisuje tę globalną wartość domyślną.
-- Gdy nie ustawiono ani globalnego, ani per-zadanie celu niepowodzenia, zadania, które już dostarczają przez `announce`, przy niepowodzeniu wracają do tego podstawowego celu announce.
-- `delivery.failureDestination` jest obsługiwane tylko dla zadań z `sessionTarget="isolated"`, chyba że podstawowy `delivery.mode` zadania ma wartość `"webhook"`.
+- Gdy nie ustawiono ani globalnego, ani per-zadanie celu błędów, zadania, które już dostarczają przez `announce`, w razie błędu wracają do tego głównego celu announce.
+- `delivery.failureDestination` jest obsługiwane tylko dla zadań `sessionTarget="isolated"`, chyba że główne `delivery.mode` zadania to `"webhook"`.
-Zobacz [Zadania Cron](/pl/automation/cron-jobs). Izolowane wykonania cron są śledzone jako [zadania w tle](/pl/automation/tasks).
+Zobacz [Zadania cron](/pl/automation/cron-jobs). Izolowane wykonania cron są śledzone jako [zadania w tle](/pl/automation/tasks).
---
@@ -3692,27 +3694,27 @@ Zobacz [Zadania Cron](/pl/automation/cron-jobs). Izolowane wykonania cron są ś
Placeholdery szablonu rozwijane w `tools.media.models[].args`:
-| Zmienna | Opis |
-| ----------------- | ------------------------------------------------ |
-| `{{Body}}` | Pełna treść wiadomości przychodzącej |
-| `{{RawBody}}` | Surowa treść (bez opakowań historii/nadawcy) |
-| `{{BodyStripped}}` | Treść z usuniętymi wzmiankami grupowymi |
-| `{{From}}` | Identyfikator nadawcy |
-| `{{To}}` | Identyfikator celu |
-| `{{MessageSid}}` | Id wiadomości kanału |
-| `{{SessionId}}` | UUID bieżącej sesji |
-| `{{IsNewSession}}` | `"true"` po utworzeniu nowej sesji |
-| `{{MediaUrl}}` | Pseudo-URL mediów przychodzących |
-| `{{MediaPath}}` | Lokalna ścieżka mediów |
-| `{{MediaType}}` | Typ mediów (image/audio/document/…) |
-| `{{Transcript}}` | Transkrypt audio |
-| `{{Prompt}}` | Rozwiązany prompt mediów dla wpisów CLI |
-| `{{MaxChars}}` | Rozwiązana maksymalna liczba znaków wyjścia dla wpisów CLI |
-| `{{ChatType}}` | `"direct"` albo `"group"` |
-| `{{GroupSubject}}` | Temat grupy (best effort) |
+| Zmienna | Opis |
+| ----------------- | ------------------------------------------------- |
+| `{{Body}}` | Pełna treść wiadomości przychodzącej |
+| `{{RawBody}}` | Surowa treść (bez opakowań historii/nadawcy) |
+| `{{BodyStripped}}` | Treść z usuniętymi wzmiankami grupowymi |
+| `{{From}}` | Identyfikator nadawcy |
+| `{{To}}` | Identyfikator celu |
+| `{{MessageSid}}` | Identyfikator wiadomości kanału |
+| `{{SessionId}}` | UUID bieżącej sesji |
+| `{{IsNewSession}}` | `"true"` przy utworzeniu nowej sesji |
+| `{{MediaUrl}}` | Pseudo-URL przychodzącego medium |
+| `{{MediaPath}}` | Lokalna ścieżka medium |
+| `{{MediaType}}` | Typ medium (image/audio/document/…) |
+| `{{Transcript}}` | Transkrypt audio |
+| `{{Prompt}}` | Rozstrzygnięty prompt mediów dla wpisów CLI |
+| `{{MaxChars}}` | Rozstrzygnięta maks. liczba znaków wyjścia dla wpisów CLI |
+| `{{ChatType}}` | `"direct"` lub `"group"` |
+| `{{GroupSubject}}` | Temat grupy (best effort) |
| `{{GroupMembers}}` | Podgląd członków grupy (best effort) |
-| `{{SenderName}}` | Wyświetlana nazwa nadawcy (best effort) |
-| `{{SenderE164}}` | Numer telefonu nadawcy (best effort) |
+| `{{SenderName}}` | Wyświetlana nazwa nadawcy (best effort) |
+| `{{SenderE164}}` | Numer telefonu nadawcy (best effort) |
| `{{Provider}}` | Wskazówka dostawcy (whatsapp, telegram, discord itd.) |
---
@@ -3736,10 +3738,10 @@ Podziel konfigurację na wiele plików:
- Pojedynczy plik: zastępuje obiekt zawierający.
- Tablica plików: głęboko scalana w kolejności (późniejsze nadpisują wcześniejsze).
-- Klucze równorzędne: scalane po include (nadpisują dołączone wartości).
-- Include zagnieżdżone: do 10 poziomów głębokości.
-- Ścieżki: rozwiązywane względem pliku zawierającego, ale muszą pozostać wewnątrz katalogu głównego konfiguracji najwyższego poziomu (`dirname` dla `openclaw.json`). Formy bezwzględne/`../` są dozwolone tylko wtedy, gdy nadal rozwiązują się wewnątrz tej granicy.
-- Błędy: czytelne komunikaty dla brakujących plików, błędów parsowania i cyklicznych include.
+- Klucze równorzędne: scalane po include (nadpisują uwzględnione wartości).
+- Zagnieżdżone include: do 10 poziomów głębokości.
+- Ścieżki: rozwiązywane względem pliku zawierającego, ale muszą pozostać wewnątrz katalogu głównego konfiguracji najwyższego poziomu (`dirname` dla `openclaw.json`). Formy bezwzględne/`../` są dozwolone tylko wtedy, gdy po rozwiązaniu nadal pozostają w tym ograniczeniu.
+- Błędy: jasne komunikaty dla brakujących plików, błędów parsowania i cyklicznych include.
---
diff --git a/docs/pl/help/gpt54-codex-agentic-parity-maintainers.md b/docs/pl/help/gpt54-codex-agentic-parity-maintainers.md
new file mode 100644
index 000000000..5e024121f
--- /dev/null
+++ b/docs/pl/help/gpt54-codex-agentic-parity-maintainers.md
@@ -0,0 +1,174 @@
+---
+x-i18n:
+ generated_at: "2026-04-11T15:15:56Z"
+ model: gpt-5.4
+ provider: openai
+ source_hash: 910bcf7668becf182ef48185b43728bf2fa69629d6d50189d47d47b06f807a9e
+ source_path: help/gpt54-codex-agentic-parity-maintainers.md
+ workflow: 15
+---
+
+# Notatki konserwatora dotyczące parytetu GPT-5.4 / Codex
+
+Ta notatka wyjaśnia, jak przeglądać program parytetu GPT-5.4 / Codex jako cztery jednostki scalania bez utraty oryginalnej architektury sześciu kontraktów.
+
+## Jednostki scalania
+
+### PR A: ścisłe wykonanie agentowe
+
+Obejmuje:
+
+- `executionContract`
+- GPT-5-first same-turn follow-through
+- `update_plan` jako nieterminalne śledzenie postępu
+- jawne stany zablokowania zamiast cichych zatrzymań opartych wyłącznie na planie
+
+Nie obejmuje:
+
+- klasyfikacji błędów uwierzytelniania/środowiska uruchomieniowego
+- prawdomówności uprawnień
+- przeprojektowania odtwarzania/kontynuacji
+- benchmarkingu parytetu
+
+### PR B: prawdomówność środowiska uruchomieniowego
+
+Obejmuje:
+
+- poprawność zakresów OAuth Codex
+- typowaną klasyfikację błędów dostawcy/środowiska uruchomieniowego
+- rzetelną dostępność `/elevated full` i powody zablokowania
+
+Nie obejmuje:
+
+- normalizacji schematu narzędzi
+- stanu odtwarzania/żywotności
+- bramkowania benchmarków
+
+### PR C: poprawność wykonania
+
+Obejmuje:
+
+- zgodność narzędzi OpenAI/Codex należącą do dostawcy
+- ścisłą obsługę schematów bez parametrów
+- ujawnianie nieprawidłowego odtwarzania
+- widoczność stanów wstrzymania, zablokowania i porzucenia dla zadań długotrwałych
+
+Nie obejmuje:
+
+- samodzielnie wybranej kontynuacji
+- ogólnego zachowania dialektu Codex poza hookami dostawcy
+- bramkowania benchmarków
+
+### PR D: harness parytetu
+
+Obejmuje:
+
+- pakiet scenariuszy pierwszej fali GPT-5.4 vs Opus 4.6
+- dokumentację parytetu
+- raport parytetu i mechanikę bramki wydania
+
+Nie obejmuje:
+
+- zmian zachowania środowiska uruchomieniowego poza QA-lab
+- symulacji auth/proxy/DNS wewnątrz harnessu
+
+## Mapowanie z powrotem na oryginalne sześć kontraktów
+
+| Oryginalny kontrakt | Jednostka scalania |
+| ---------------------------------------- | ------------------ |
+| Poprawność transportu/uwierzytelniania dostawcy | PR B |
+| Zgodność kontraktu/schematu narzędzi | PR C |
+| Wykonanie w tej samej turze | PR A |
+| Prawdomówność uprawnień | PR B |
+| Poprawność odtwarzania/kontynuacji/żywotności | PR C |
+| Bramka benchmarku/wydania | PR D |
+
+## Kolejność przeglądu
+
+1. PR A
+2. PR B
+3. PR C
+4. PR D
+
+PR D jest warstwą dowodową. Nie powinien być powodem opóźniania PR-ów dotyczących poprawności środowiska uruchomieniowego.
+
+## Na co zwracać uwagę
+
+### PR A
+
+- uruchomienia GPT-5 działają albo kończą się w sposób zamknięty, zamiast zatrzymywać się na komentarzu
+- `update_plan` nie wygląda już sam w sobie jak postęp
+- zachowanie pozostaje GPT-5-first i ograniczone do embedded-Pi
+
+### PR B
+
+- błędy auth/proxy/środowiska uruchomieniowego przestają zapadać się do ogólnej obsługi „model failed”
+- `/elevated full` jest opisywane jako dostępne tylko wtedy, gdy rzeczywiście jest dostępne
+- powody zablokowania są widoczne zarówno dla modelu, jak i dla środowiska uruchomieniowego skierowanego do użytkownika
+
+### PR C
+
+- ścisła rejestracja narzędzi OpenAI/Codex zachowuje się przewidywalnie
+- narzędzia bez parametrów nie kończą się niepowodzeniem przy ścisłych kontrolach schematu
+- wyniki odtwarzania i kompaktowania zachowują prawdziwy stan żywotności
+
+### PR D
+
+- pakiet scenariuszy jest zrozumiały i odtwarzalny
+- pakiet zawiera ścieżkę bezpieczeństwa odtwarzania z mutacjami, a nie tylko przepływy tylko do odczytu
+- raporty są czytelne dla ludzi i automatyzacji
+- twierdzenia o parytecie są poparte dowodami, a nie anegdotami
+
+Oczekiwane artefakty z PR D:
+
+- `qa-suite-report.md` / `qa-suite-summary.json` dla każdego uruchomienia modelu
+- `qa-agentic-parity-report.md` z porównaniem zbiorczym i na poziomie scenariuszy
+- `qa-agentic-parity-summary.json` z werdyktem możliwym do odczytu maszynowego
+
+## Bramka wydania
+
+Nie twierdź, że GPT-5.4 osiąga parytet lub przewagę nad Opus 4.6, dopóki:
+
+- PR A, PR B i PR C nie zostaną scalone
+- PR D nie uruchomi czysto pakietu parytetu pierwszej fali
+- zestawy regresji prawdomówności środowiska uruchomieniowego pozostają zielone
+- raport parytetu nie wykazuje przypadków fałszywego sukcesu ani regresji w zachowaniu zatrzymania
+
+```mermaid
+flowchart LR
+ A["PR A-C merged"] --> B["Run GPT-5.4 parity pack"]
+ A --> C["Run Opus 4.6 parity pack"]
+ B --> D["qa-suite-summary.json"]
+ C --> E["qa-suite-summary.json"]
+ D --> F["qa parity-report"]
+ E --> F
+ F --> G["Markdown report + JSON verdict"]
+ G --> H{"Pass?"}
+ H -- "yes" --> I["Parity claim allowed"]
+ H -- "no" --> J["Keep runtime fixes / review loop open"]
+```
+
+Harness parytetu nie jest jedynym źródłem dowodów. Zachowaj ten podział jako jawny podczas przeglądu:
+
+- PR D obejmuje porównanie GPT-5.4 vs Opus 4.6 oparte na scenariuszach
+- deterministyczne zestawy PR B nadal obejmują dowody dotyczące auth/proxy/DNS i prawdomówności pełnego dostępu
+
+## Mapa celu do dowodów
+
+| Element bramki ukończenia | Główny właściciel | Artefakt przeglądu |
+| ---------------------------------------- | ----------------- | ------------------------------------------------------------------- |
+| Brak zacięć opartych wyłącznie na planie | PR A | testy środowiska ścisłego wykonania agentowego i `approval-turn-tool-followthrough` |
+| Brak fałszywego postępu lub fałszywego zakończenia narzędzia | PR A + PR D | liczba fałszywych sukcesów w parytecie plus szczegóły raportu na poziomie scenariuszy |
+| Brak fałszywych wskazówek `/elevated full` | PR B | deterministyczne zestawy prawdomówności środowiska uruchomieniowego |
+| Błędy odtwarzania/żywotności pozostają jawne | PR C + PR D | zestawy lifecycle/replay plus `compaction-retry-mutating-tool` |
+| GPT-5.4 dorównuje Opus 4.6 lub go przewyższa | PR D | `qa-agentic-parity-report.md` i `qa-agentic-parity-summary.json` |
+
+## Skrót dla recenzenta: przed vs po
+
+| Problem widoczny dla użytkownika przed | Sygnał przeglądu po |
+| --------------------------------------------------------- | --------------------------------------------------------------------------------------- |
+| GPT-5.4 zatrzymywał się po planowaniu | PR A pokazuje zachowanie wykonaj-lub-zablokuj zamiast zakończenia opartego wyłącznie na komentarzu |
+| Użycie narzędzi wydawało się kruche przy ścisłych schematach OpenAI/Codex | PR C utrzymuje przewidywalność rejestracji narzędzi i wywołań bez parametrów |
+| Wskazówki `/elevated full` bywały czasem mylące | PR B wiąże wskazówki z rzeczywistą zdolnością środowiska uruchomieniowego i powodami zablokowania |
+| Długie zadania mogły zniknąć w niejednoznaczności odtwarzania/kompaktowania | PR C emituje jawny stan: wstrzymane, zablokowane, porzucone i replay-invalid |
+| Twierdzenia o parytecie były anegdotyczne | PR D tworzy raport oraz werdykt JSON z tym samym pokryciem scenariuszy dla obu modeli |
diff --git a/docs/pl/help/gpt54-codex-agentic-parity.md b/docs/pl/help/gpt54-codex-agentic-parity.md
new file mode 100644
index 000000000..f9da7c73b
--- /dev/null
+++ b/docs/pl/help/gpt54-codex-agentic-parity.md
@@ -0,0 +1,229 @@
+---
+x-i18n:
+ generated_at: "2026-04-11T15:15:56Z"
+ model: gpt-5.4
+ provider: openai
+ source_hash: 7ee6b925b8a0f8843693cea9d50b40544657b5fb8a9e0860e2ff5badb273acb6
+ source_path: help/gpt54-codex-agentic-parity.md
+ workflow: 15
+---
+
+# GPT-5.4 / Codex Agentic Parity w OpenClaw
+
+OpenClaw już dobrze działał z modelami granicznymi korzystającymi z narzędzi, ale modele w stylu GPT-5.4 i Codex nadal wypadały słabiej w kilku praktycznych aspektach:
+
+- mogły zatrzymać się po etapie planowania zamiast wykonać pracę
+- mogły niepoprawnie używać ścisłych schematów narzędzi OpenAI/Codex
+- mogły prosić o `/elevated full`, nawet gdy pełny dostęp był niemożliwy
+- mogły tracić stan długotrwałego zadania podczas odtwarzania lub kompaktowania
+- twierdzenia o parytecie względem Claude Opus 4.6 opierały się na anegdotach zamiast na powtarzalnych scenariuszach
+
+Ten program parytetu usuwa te luki w czterech fragmentach możliwych do przeglądu.
+
+## Co się zmieniło
+
+### PR A: ścisłe wykonanie agentyczne
+
+Ten fragment dodaje opcjonalny kontrakt wykonania `strict-agentic` dla osadzonych uruchomień Pi GPT-5.
+
+Gdy jest włączony, OpenClaw przestaje akceptować tury zawierające wyłącznie plan jako „wystarczająco dobre” zakończenie. Jeśli model tylko mówi, co zamierza zrobić, i faktycznie nie używa narzędzi ani nie robi postępu, OpenClaw ponawia próbę z nakierowaniem na natychmiastowe działanie, a następnie kończy się w trybie fail-closed z jawnym stanem blokady zamiast po cichu kończyć zadanie.
+
+Najbardziej poprawia to działanie GPT-5.4 w następujących przypadkach:
+
+- krótkie dopowiedzenia typu „ok, zrób to”
+- zadania programistyczne, w których pierwszy krok jest oczywisty
+- przepływy, w których `update_plan` powinno służyć do śledzenia postępu, a nie jako tekst wypełniający
+
+### PR B: zgodność z rzeczywistym stanem środowiska wykonawczego
+
+Ten fragment sprawia, że OpenClaw mówi prawdę o dwóch rzeczach:
+
+- dlaczego wywołanie dostawcy/środowiska wykonawczego nie powiodło się
+- czy `/elevated full` jest faktycznie dostępne
+
+Oznacza to, że GPT-5.4 otrzymuje lepsze sygnały środowiska wykonawczego dla brakującego zakresu uprawnień, błędów odświeżenia uwierzytelnienia, błędów uwierzytelnienia HTML 403, problemów z proxy, błędów DNS lub przekroczenia czasu oraz zablokowanych trybów pełnego dostępu. Model z mniejszym prawdopodobieństwem będzie halucynował błędne działania naprawcze albo nadal prosił o tryb uprawnień, którego środowisko wykonawcze nie może zapewnić.
+
+### PR C: poprawność wykonania
+
+Ten fragment poprawia dwa rodzaje poprawności:
+
+- zgodność schematów narzędzi należących do dostawcy z OpenAI/Codex
+- widoczność odtwarzania i żywotności długich zadań
+
+Prace nad zgodnością narzędzi zmniejszają tarcia związane ze ścisłą rejestracją narzędzi OpenAI/Codex, szczególnie w przypadku narzędzi bez parametrów i oczekiwań dotyczących ścisłego obiektu jako korzenia. Prace nad odtwarzaniem i żywotnością sprawiają, że zadania długotrwałe są lepiej obserwowalne, dzięki czemu stany wstrzymania, blokady i porzucenia są widoczne zamiast znikać w ogólnym komunikacie o błędzie.
+
+### PR D: wiązka testów parytetu
+
+Ten fragment dodaje pierwszą falę zestawu parytetu QA-lab, aby GPT-5.4 i Opus 4.6 można było uruchamiać w tych samych scenariuszach i porównywać na podstawie wspólnych dowodów.
+
+Zestaw parytetu jest warstwą dowodową. Sam z siebie nie zmienia zachowania środowiska wykonawczego.
+
+Gdy masz już dwa artefakty `qa-suite-summary.json`, wygeneruj porównanie bramki wydania za pomocą:
+
+```bash
+pnpm openclaw qa parity-report \
+ --repo-root . \
+ --candidate-summary .artifacts/qa-e2e/gpt54/qa-suite-summary.json \
+ --baseline-summary .artifacts/qa-e2e/opus46/qa-suite-summary.json \
+ --output-dir .artifacts/qa-e2e/parity
+```
+
+To polecenie zapisuje:
+
+- czytelny dla człowieka raport Markdown
+- czytelny maszynowo werdykt JSON
+- jawny wynik bramki `pass` / `fail`
+
+## Dlaczego to w praktyce poprawia GPT-5.4
+
+Przed tymi zmianami GPT-5.4 w OpenClaw mógł sprawiać wrażenie mniej agentycznego niż Opus w rzeczywistych sesjach programistycznych, ponieważ środowisko wykonawcze tolerowało zachowania szczególnie szkodliwe dla modeli w stylu GPT-5:
+
+- tury zawierające wyłącznie komentarz
+- tarcia schematów wokół narzędzi
+- niejasne informacje zwrotne o uprawnieniach
+- ciche uszkodzenia odtwarzania lub kompaktowania
+
+Celem nie jest sprawienie, by GPT-5.4 naśladował Opus. Celem jest zapewnienie GPT-5.4 kontraktu środowiska wykonawczego, który nagradza rzeczywisty postęp, dostarcza czytelniejszej semantyki narzędzi i uprawnień oraz zamienia tryby awarii w jawne stany czytelne zarówno dla maszyn, jak i ludzi.
+
+To zmienia doświadczenie użytkownika z:
+
+- „model miał dobry plan, ale się zatrzymał”
+
+na:
+
+- „model albo zadziałał, albo OpenClaw wskazał dokładny powód, dlaczego nie mógł”
+
+## Przed i po dla użytkowników GPT-5.4
+
+| Przed tym programem | Po PR A-D |
+| ---------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
+| GPT-5.4 mógł zatrzymać się po rozsądnym planie bez wykonania kolejnego kroku narzędziowego | PR A zamienia „sam plan” na „działaj teraz albo pokaż stan blokady” |
+| Ścisłe schematy narzędzi mogły w mylący sposób odrzucać narzędzia bez parametrów lub w kształcie OpenAI/Codex | PR C sprawia, że rejestracja i wywoływanie narzędzi należących do dostawcy są bardziej przewidywalne |
+| Wskazówki dotyczące `/elevated full` mogły być niejasne lub błędne w zablokowanych środowiskach wykonawczych | PR B daje GPT-5.4 i użytkownikowi prawdziwe wskazówki środowiska wykonawczego i uprawnień |
+| Błędy odtwarzania lub kompaktowania mogły sprawiać wrażenie, że zadanie po cichu zniknęło | PR C jawnie pokazuje wyniki paused, blocked, abandoned i replay-invalid |
+| „GPT-5.4 wypada gorzej niż Opus” było głównie anegdotyczne | PR D zamienia to w ten sam zestaw scenariuszy, te same metryki i twardą bramkę pass/fail |
+
+## Architektura
+
+```mermaid
+flowchart TD
+ A["Żądanie użytkownika"] --> B["Osadzone środowisko wykonawcze Pi"]
+ B --> C["Kontrakt ścisłego wykonania agentycznego"]
+ B --> D["Zgodność narzędzi należących do dostawcy"]
+ B --> E["Zgodność z rzeczywistym stanem środowiska wykonawczego"]
+ B --> F["Stan odtwarzania i żywotności"]
+ C --> G["Wywołanie narzędzia lub jawny stan blokady"]
+ D --> G
+ E --> G
+ F --> G
+ G --> H["Zestaw parytetu QA-lab"]
+ H --> I["Raport scenariuszy i bramka parytetu"]
+```
+
+## Przepływ wydania
+
+```mermaid
+flowchart LR
+ A["Scalone fragmenty środowiska wykonawczego (PR A-C)"] --> B["Uruchom zestaw parytetu GPT-5.4"]
+ A --> C["Uruchom zestaw parytetu Opus 4.6"]
+ B --> D["qa-suite-summary.json"]
+ C --> E["qa-suite-summary.json"]
+ D --> F["openclaw qa parity-report"]
+ E --> F
+ F --> G["qa-agentic-parity-report.md"]
+ F --> H["qa-agentic-parity-summary.json"]
+ H --> I{"Bramka zaliczona?"}
+ I -- "tak" --> J["Twierdzenie o parytecie poparte dowodami"]
+ I -- "nie" --> K["Pozostaw pętlę środowiska wykonawczego/przeglądu otwartą"]
+```
+
+## Zestaw scenariuszy
+
+Pierwsza fala zestawu parytetu obejmuje obecnie pięć scenariuszy:
+
+### `approval-turn-tool-followthrough`
+
+Sprawdza, czy model nie zatrzymuje się na „zrobię to” po krótkiej zgodzie. Powinien wykonać pierwsze konkretne działanie w tej samej turze.
+
+### `model-switch-tool-continuity`
+
+Sprawdza, czy praca z użyciem narzędzi pozostaje spójna po przełączeniu modelu/środowiska wykonawczego zamiast resetować się do komentarza lub tracić kontekst wykonania.
+
+### `source-docs-discovery-report`
+
+Sprawdza, czy model potrafi czytać kod źródłowy i dokumentację, syntetyzować ustalenia oraz kontynuować zadanie w sposób agentyczny zamiast tworzyć cienkie podsumowanie i zatrzymywać się zbyt wcześnie.
+
+### `image-understanding-attachment`
+
+Sprawdza, czy zadania mieszane obejmujące załączniki pozostają wykonalne i nie sprowadzają się do ogólnej narracji.
+
+### `compaction-retry-mutating-tool`
+
+Sprawdza, czy zadanie z rzeczywistym modyfikującym zapisem zachowuje jawną informację o niebezpieczeństwie odtwarzania zamiast sprawiać ciche wrażenie bezpiecznego odtworzenia, gdy uruchomienie ulega kompaktowaniu, ponownej próbie lub traci stan odpowiedzi pod presją.
+
+## Macierz scenariuszy
+
+| Scenariusz | Co testuje | Dobre zachowanie GPT-5.4 | Sygnał niepowodzenia |
+| ---------------------------------- | --------------------------------------- | ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
+| `approval-turn-tool-followthrough` | Krótkie zgody po planie | Natychmiast rozpoczyna pierwsze konkretne działanie narzędziowe zamiast powtarzać zamiar | dopowiedzenie ograniczające się do planu, brak aktywności narzędziowej lub tura zablokowana bez rzeczywistej przeszkody |
+| `model-switch-tool-continuity` | Przełączanie środowiska wykonawczego/modelu podczas użycia narzędzi | Zachowuje kontekst zadania i spójnie kontynuuje działanie | reset do komentarza, utrata kontekstu narzędzi lub zatrzymanie po przełączeniu |
+| `source-docs-discovery-report` | Czytanie kodu źródłowego + synteza + działanie | Znajduje źródła, używa narzędzi i tworzy użyteczny raport bez zastoju | cienkie podsumowanie, brak pracy z narzędziami lub zatrzymanie w niepełnej turze |
+| `image-understanding-attachment` | Agentyczna praca oparta na załączniku | Interpretuje załącznik, łączy go z narzędziami i kontynuuje zadanie | ogólna narracja, zignorowany załącznik lub brak konkretnego następnego działania |
+| `compaction-retry-mutating-tool` | Praca modyfikująca pod presją kompaktowania | Wykonuje rzeczywisty zapis i po skutku ubocznym zachowuje jawną informację o niebezpieczeństwie odtwarzania | następuje modyfikujący zapis, ale bezpieczeństwo odtwarzania jest sugerowane, nieobecne lub sprzeczne |
+
+## Bramka wydania
+
+Można uznać, że GPT-5.4 osiągnął parytet lub lepszy wynik tylko wtedy, gdy scalone środowisko wykonawcze jednocześnie przechodzi zestaw parytetu oraz regresje zgodności z rzeczywistym stanem środowiska wykonawczego.
+
+Wymagane wyniki:
+
+- brak zastoju na samym planie, gdy następne działanie narzędziowe jest oczywiste
+- brak fałszywego zakończenia bez rzeczywistego wykonania
+- brak niepoprawnych wskazówek `/elevated full`
+- brak cichego porzucenia podczas odtwarzania lub kompaktowania
+- metryki zestawu parytetu co najmniej tak dobre jak uzgodniona baza odniesienia Opus 4.6
+
+W pierwszej fali wiązki bramka porównuje:
+
+- wskaźnik ukończenia
+- wskaźnik niezamierzonych zatrzymań
+- wskaźnik prawidłowych wywołań narzędzi
+- liczbę fałszywych sukcesów
+
+Dowody parytetu są celowo podzielone na dwie warstwy:
+
+- PR D dowodzi zachowania GPT-5.4 vs Opus 4.6 w tych samych scenariuszach przy użyciu QA-lab
+- deterministyczne zestawy PR B dowodzą zgodności uwierzytelniania, proxy, DNS i `/elevated full` z rzeczywistym stanem poza tą wiązką
+
+## Macierz celu i dowodów
+
+| Element bramki ukończenia | Odpowiedzialny PR | Źródło dowodów | Sygnał zaliczenia |
+| ------------------------------------------------------- | ----------------- | ----------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
+| GPT-5.4 nie zatrzymuje się już po planowaniu | PR A | `approval-turn-tool-followthrough` oraz zestawy środowiska wykonawczego PR A | tury zatwierdzenia wywołują rzeczywistą pracę albo jawny stan blokady |
+| GPT-5.4 nie udaje już postępu ani fałszywego ukończenia narzędzia | PR A + PR D | wyniki scenariuszy w raporcie parytetu i liczba fałszywych sukcesów | brak podejrzanych wyników zaliczających i brak zakończeń opartych wyłącznie na komentarzu |
+| GPT-5.4 nie podaje już fałszywych wskazówek `/elevated full` | PR B | deterministyczne zestawy zgodności z rzeczywistym stanem | powody blokady i wskazówki pełnego dostępu pozostają zgodne z rzeczywistym stanem środowiska wykonawczego |
+| Błędy odtwarzania/żywotności pozostają jawne | PR C + PR D | zestawy lifecycle/replay PR C oraz `compaction-retry-mutating-tool` | praca modyfikująca zachowuje jawną informację o niebezpieczeństwie odtwarzania zamiast po cichu znikać |
+| GPT-5.4 dorównuje lub przewyższa Opus 4.6 w uzgodnionych metrykach | PR D | `qa-agentic-parity-report.md` i `qa-agentic-parity-summary.json` | ten sam zakres scenariuszy i brak regresji w ukończeniu, zachowaniu zatrzymania lub prawidłowym użyciu narzędzi |
+
+## Jak odczytać werdykt parytetu
+
+Użyj werdyktu w `qa-agentic-parity-summary.json` jako ostatecznej, czytelnej maszynowo decyzji dla zestawu parytetu pierwszej fali.
+
+- `pass` oznacza, że GPT-5.4 objął te same scenariusze co Opus 4.6 i nie odnotował regresji w uzgodnionych metrykach zbiorczych.
+- `fail` oznacza, że została uruchomiona co najmniej jedna twarda bramka: słabsze ukończenie, gorsze niezamierzone zatrzymania, słabsze prawidłowe użycie narzędzi, jakikolwiek przypadek fałszywego sukcesu lub niedopasowany zakres scenariuszy.
+- „shared/base CI issue” samo w sobie nie jest wynikiem parytetu. Jeśli szum CI poza PR D blokuje uruchomienie, werdykt powinien poczekać na czyste wykonanie na scalonym środowisku wykonawczym, zamiast być wywnioskowany z logów z okresu gałęzi.
+- Zgodność uwierzytelniania, proxy, DNS i `/elevated full` z rzeczywistym stanem nadal pochodzi z deterministycznych zestawów PR B, więc ostateczne twierdzenie wydaniowe wymaga obu elementów: pozytywnego werdyktu parytetu PR D i zielonego pokrycia zgodności z rzeczywistym stanem z PR B.
+
+## Kto powinien włączyć `strict-agentic`
+
+Użyj `strict-agentic`, gdy:
+
+- oczekuje się, że agent zacznie działać natychmiast, gdy kolejny krok jest oczywisty
+- modele z rodziny GPT-5.4 lub Codex są podstawowym środowiskiem wykonawczym
+- wolisz jawne stany blokady zamiast „pomocnych” odpowiedzi zawierających wyłącznie podsumowanie
+
+Pozostaw domyślny kontrakt, gdy:
+
+- chcesz zachować dotychczasowe, luźniejsze zachowanie
+- nie używasz modeli z rodziny GPT-5
+- testujesz prompty, a nie wymuszanie na poziomie środowiska wykonawczego
diff --git a/docs/pl/plugins/architecture.md b/docs/pl/plugins/architecture.md
index c27026d29..6deb9ab45 100644
--- a/docs/pl/plugins/architecture.md
+++ b/docs/pl/plugins/architecture.md
@@ -1,127 +1,125 @@
---
read_when:
- - Tworzysz lub debugujesz natywne pluginy OpenClaw
- - Chcesz zrozumieć model capability pluginów lub granice własności
- - Pracujesz nad pipeline ładowania pluginów lub rejestrem
- - Implementujesz hooki runtime dostawcy lub pluginy kanałów
+ - Tworzenie lub debugowanie natywnych pluginów OpenClaw
+ - Zrozumienie modelu możliwości pluginów lub granic własności
+ - Praca nad potokiem ładowania pluginów lub rejestrem
+ - Implementowanie hooków środowiska uruchomieniowego dostawcy lub pluginów kanałów
sidebarTitle: Internals
-summary: 'Wnętrze pluginów: model capability, własność, kontrakty, pipeline ładowania i helpery runtime'
-title: Wnętrze pluginów
+summary: 'Wewnętrzne elementy pluginów: model możliwości, własność, kontrakty, potok ładowania i pomocniki środowiska uruchomieniowego'
+title: Wewnętrzne elementy pluginów
x-i18n:
- generated_at: "2026-04-09T01:32:33Z"
+ generated_at: "2026-04-11T15:16:10Z"
model: gpt-5.4
provider: openai
- source_hash: 2575791f835990589219bb06d8ca92e16a8c38b317f0bfe50b421682f253ef18
+ source_hash: 7cac67984d0d729c0905bcf5c18372fb0d9b02bbd3a531580b7e2ef483ef40a6
source_path: plugins/architecture.md
workflow: 15
---
-# Wnętrze pluginów
+# Wewnętrzne elementy pluginów
- To jest **dogłębna dokumentacja architektury**. Praktyczne przewodniki znajdziesz tutaj:
- - [Install and use plugins](/pl/tools/plugin) — przewodnik użytkownika
- - [Getting Started](/pl/plugins/building-plugins) — samouczek tworzenia pierwszego pluginu
- - [Channel Plugins](/pl/plugins/sdk-channel-plugins) — zbuduj kanał komunikacyjny
- - [Provider Plugins](/pl/plugins/sdk-provider-plugins) — zbuduj dostawcę modeli
- - [SDK Overview](/pl/plugins/sdk-overview) — mapa importów i API rejestracji
+ To jest **szczegółowy opis architektury**. Praktyczne przewodniki znajdziesz tutaj:
+ - [Instalacja i używanie pluginów](/pl/tools/plugin) — przewodnik użytkownika
+ - [Pierwsze kroki](/pl/plugins/building-plugins) — samouczek tworzenia pierwszego pluginu
+ - [Pluginy kanałów](/pl/plugins/sdk-channel-plugins) — tworzenie kanału komunikacyjnego
+ - [Pluginy dostawców](/pl/plugins/sdk-provider-plugins) — tworzenie 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 capability
+## Publiczny model możliwości
-Capabilities to publiczny model **natywnych pluginów** w OpenClaw. Każdy
-natywny plugin OpenClaw rejestruje się względem co najmniej jednego typu capability:
+Możliwoś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` |
-| Transkrypcja realtime | `api.registerRealtimeTranscriptionProvider(...)` | `openai` |
-| Głos realtime | `api.registerRealtimeVoiceProvider(...)` | `openai` |
-| Rozumienie mediów | `api.registerMediaUnderstandingProvider(...)` | `openai`, `google` |
-| Generowanie obrazów | `api.registerImageGenerationProvider(...)` | `openai`, `google`, `fal`, `minimax` |
-| Generowanie muzyki | `api.registerMusicGenerationProvider(...)` | `google`, `minimax` |
-| Generowanie wideo | `api.registerVideoGenerationProvider(...)` | `qwen` |
-| Pobieranie z sieci | `api.registerWebFetchProvider(...)` | `firecrawl` |
-| Wyszukiwanie w sieci | `api.registerWebSearchProvider(...)` | `google` |
-| Kanał / komunikacja | `api.registerChannel(...)` | `msteams`, `matrix` |
+| 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 multimediów | `api.registerMediaUnderstandingProvider(...)` | `openai`, `google` |
+| Generowanie obrazów | `api.registerImageGenerationProvider(...)` | `openai`, `google`, `fal`, `minimax` |
+| Generowanie muzyki | `api.registerMusicGenerationProvider(...)` | `google`, `minimax` |
+| Generowanie wideo | `api.registerVideoGenerationProvider(...)` | `qwen` |
+| Pobieranie z sieci | `api.registerWebFetchProvider(...)` | `firecrawl` |
+| Wyszukiwanie w sieci | `api.registerWebSearchProvider(...)` | `google` |
+| Kanał / komunikacja | `api.registerChannel(...)` | `msteams`, `matrix` |
-Plugin, który rejestruje zero capabilities, ale dostarcza hooki, narzędzia lub
-usługi, jest pluginem **legacy hook-only**. Ten wzorzec jest nadal w pełni wspierany.
+Plugin, który rejestruje zero możliwości, ale udostępnia hooki, narzędzia lub
+usługi, jest pluginem **legacy hook-only**. Ten wzorzec nadal jest w pełni obsługiwany.
-### Stan kompatybilności zewnętrznej
+### Stanowisko dotyczące zgodności zewnętrznej
-Model capability jest wdrożony w core i używany dziś przez dołączone/natywne
-pluginy, ale kompatybilność z pluginami zewnętrznymi nadal wymaga wyższego progu
-niż „jest eksportowane, więc jest zamrożone”.
+Model możliwości jest już wdrożony w rdzeniu i używany dziś przez
+bundled/native plugins, ale zgodność zewnętrznych pluginów nadal wymaga
+bardziej rygorystycznego podejścia niż „jest eksportowane, więc jest zamrożone”.
Aktualne wytyczne:
- **istniejące pluginy zewnętrzne:** zachowuj działanie integracji opartych na hookach; traktuj
- to jako bazowy poziom kompatybilności
-- **nowe dołączone/natywne pluginy:** preferuj jawną rejestrację capability zamiast
- zależności od konkretnego dostawcy lub nowych projektów hook-only
-- **pluginy zewnętrzne przyjmujące rejestrację capability:** dozwolone, ale traktuj
- helpery specyficzne dla capability jako rozwijające się, chyba że dokumentacja
- wyraźnie oznacza kontrakt jako stabilny
+ to jako bazowy poziom zgodności
+- **nowe bundled/native plugins:** preferuj jawną rejestrację możliwości zamiast
+ specyficznych dla dostawcy sięgnięć do wnętrza lub nowych projektów opartych wyłącznie na hookach
+- **pluginy zewnętrzne przyjmujące rejestrację możliwości:** dozwolone, ale
+ traktuj powierzchnie pomocnicze specyficzne dla możliwości jako rozwijające się, chyba że dokumentacja wyraźnie oznacza dany kontrakt jako stabilny
Praktyczna zasada:
-- API rejestracji capability jest docelowym kierunkiem
-- legacy hooks pozostają najbezpieczniejszą ścieżką bez ryzyka złamania dla pluginów zewnętrznych podczas
+- API rejestracji możliwości to zamierzony kierunek
+- legacy hooks pozostają najbezpieczniejszą ścieżką bez ryzyka złamania zgodności dla pluginów zewnętrznych podczas
przejścia
-- eksportowane subścieżki helperów nie są równoważne; preferuj wąski, udokumentowany
- kontrakt, a nie przypadkowe eksporty helperów
+- eksportowane ścieżki pomocnicze nie są równoważne; preferuj wąski, udokumentowany
+ kontrakt, a nie przypadkowo eksportowane helpery
### Kształty pluginów
-OpenClaw klasyfikuje każdy załadowany plugin do jednego z kształtów na podstawie
-jego rzeczywistego zachowania rejestracyjnego (a nie tylko statycznych metadanych):
+OpenClaw klasyfikuje każdy załadowany plugin do określonego kształtu na podstawie jego rzeczywistego
+zachowania rejestracyjnego (a nie tylko statycznych metadanych):
-- **plain-capability** -- rejestruje dokładnie jeden typ capability (na przykład
- plugin tylko-dostawca, taki jak `mistral`)
-- **hybrid-capability** -- rejestruje wiele typów capability (na przykład
- `openai` obsługuje wnioskowanie tekstowe, mowę, rozumienie mediów i generowanie
+- **plain-capability** -- rejestruje dokładnie jeden typ możliwości (na przykład
+ plugin wyłącznie dostawcy, taki jak `mistral`)
+- **hybrid-capability** -- rejestruje wiele typów możliwości (na przykład
+ `openai` obsługuje wnioskowanie tekstowe, mowę, rozumienie multimediów i generowanie
obrazów)
-- **hook-only** -- rejestruje wyłącznie hooki (typowane lub niestandardowe), bez capabilities,
+- **hook-only** -- rejestruje tylko hooki (typowane lub własne), bez możliwości,
narzędzi, komend ani usług
- **non-capability** -- rejestruje narzędzia, komendy, usługi lub trasy, ale bez
- capabilities
+ możliwości
-Użyj `openclaw plugins inspect `, aby zobaczyć kształt pluginu i podział capability.
-Szczegóły znajdziesz w [CLI reference](/cli/plugins#inspect).
+Użyj `openclaw plugins inspect `, aby zobaczyć kształt pluginu i podział
+możliwości. Szczegóły znajdziesz w [dokumentacji CLI](/cli/plugins#inspect).
### Legacy hooks
-Hook `before_agent_start` pozostaje wspierany jako ścieżka kompatybilności dla
-pluginów hook-only. Legacy pluginy używane w praktyce nadal od niego zależą.
+Hook `before_agent_start` pozostaje obsługiwany jako ścieżka zgodności dla
+pluginów typu hook-only. Nadal zależą od niego rzeczywiste pluginy legacy.
Kierunek:
-- zachowaj jego działanie
-- dokumentuj go jako legacy
-- dla pracy z nadpisywaniem modelu/dostawcy preferuj `before_model_resolve`
-- dla modyfikacji promptów preferuj `before_prompt_build`
-- usuń go dopiero wtedy, gdy realne użycie spadnie, a pokrycie przez fixture potwierdzi
- bezpieczeństwo migracji
+- utrzymać jego działanie
+- dokumentować go jako legacy
+- dla pracy związanej z nadpisywaniem modelu/dostawcy preferować `before_model_resolve`
+- dla modyfikowania promptów preferować `before_prompt_build`
+- usuwać dopiero wtedy, gdy rzeczywiste użycie spadnie, a pokrycie testami fixture potwierdzi bezpieczeństwo migracji
-### Sygnały kompatybilności
+### Sygnały zgodności
Po uruchomieniu `openclaw doctor` lub `openclaw plugins inspect ` możesz zobaczyć
jedną z tych etykiet:
| Sygnał | Znaczenie |
| -------------------------- | ------------------------------------------------------------ |
-| **config valid** | Konfiguracja parsuje się poprawnie, a pluginy są rozwiązywane |
-| **compatibility advisory** | Plugin używa wspieranego, ale starszego wzorca (np. `hook-only`) |
+| **config valid** | Konfiguracja poprawnie się parsuje i 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óry jest przestarzały |
-| **hard error** | Konfiguracja jest nieprawidłowa lub plugin nie załadował się |
+| **hard error** | Konfiguracja jest nieprawidłowa lub nie udało się załadować pluginu |
-Ani `hook-only`, ani `before_agent_start` nie zepsują dziś Twojego pluginu --
-`hook-only` ma charakter informacyjny, a `before_agent_start` wywołuje tylko ostrzeżenie. Te
+Ani `hook-only`, ani `before_agent_start` nie spowodują dziś awarii Twojego pluginu --
+`hook-only` ma charakter informacyjny, a `before_agent_start` wywołuje jedynie ostrzeżenie. Te
sygnały pojawiają się również w `openclaw status --all` i `openclaw plugins doctor`.
## Przegląd architektury
@@ -129,60 +127,59 @@ sygnały pojawiają się również w `openclaw status --all` i `openclaw plugins
System pluginów OpenClaw ma cztery warstwy:
1. **Manifest + wykrywanie**
- OpenClaw znajduje kandydackie pluginy na podstawie skonfigurowanych ścieżek, katalogów
- workspace, globalnych katalogów rozszerzeń i dołączonych rozszerzeń. Wykrywanie najpierw odczytuje natywne
- manifesty `openclaw.plugin.json` oraz wspierane manifesty bundle.
+ OpenClaw znajduje kandydackie pluginy w skonfigurowanych ścieżkach, katalogach głównych workspace,
+ globalnych katalogach rozszerzeń i bundled extensions. Wykrywanie najpierw odczytuje natywne
+ manifesty `openclaw.plugin.json` oraz obsługiwane manifesty 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 wewnątrz procesu przez jiti i rejestrują
- capabilities w centralnym rejestrze. Kompatybilne bundle są normalizowane do
- rekordów rejestru bez importowania kodu runtime.
-4. **Korzystanie z powierzchni**
- Reszta OpenClaw odczytuje rejestr, aby udostępniać narzędzia, kanały, konfigurację
+3. **Ładowanie środowiska uruchomieniowego**
+ Natywne pluginy OpenClaw są ładowane w procesie przez jiti i rejestrują
+ możliwości w centralnym rejestrze. Zgodne bundle są normalizowane do rekordów
+ rejestru bez importowania kodu środowiska uruchomieniowego.
+4. **Konsumpcja powierzchni**
+ Pozostałe części OpenClaw odczytują rejestr, aby udostępnić narzędzia, kanały, konfigurację
dostawców, hooki, trasy HTTP, komendy CLI i usługi.
-W szczególności dla pluginowego CLI wykrywanie komend głównych jest podzielone na dwa etapy:
+W przypadku CLI pluginów wykrywanie komend głównych jest podzielone na dwa etapy:
-- metadane czasu parsowania pochodzą z `registerCli(..., { descriptors: [...] })`
-- właściwy moduł CLI pluginu może pozostać lazy i zarejestrować się przy pierwszym wywołaniu
+- metadane w czasie parsowania pochodzą z `registerCli(..., { descriptors: [...] })`
+- rzeczywisty moduł CLI pluginu może pozostać leniwy i rejestrować się przy pierwszym wywołaniu
-Dzięki temu kod CLI należący do pluginu pozostaje w pluginie, a jednocześnie OpenClaw może
+Dzięki temu kod CLI należący do pluginu pozostaje w pluginie, a OpenClaw nadal może
zarezerwować nazwy komend głównych przed parsowaniem.
Ważna granica projektowa:
-- wykrywanie + walidacja konfiguracji powinny działać na podstawie **metadanych manifestu/schematu**
+- wykrywanie i walidacja konfiguracji powinny działać na podstawie **metadanych manifestu/schematu**
bez wykonywania kodu pluginu
-- natywne zachowanie runtime pochodzi ze ścieżki `register(api)` modułu pluginu
+- natywne zachowanie środowiska uruchomieniowego 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 dla UI/schematu, zanim pełny runtime stanie się aktywny.
+budować podpowiedzi UI/schematu, zanim pełne środowisko uruchomieniowe stanie się aktywne.
### Pluginy kanałów i współdzielone narzędzie wiadomości
-Pluginy kanałów nie muszą rejestrować osobnego narzędzia send/edit/react dla
-zwykłych działań czatu. OpenClaw utrzymuje jedno współdzielone narzędzie `message` w core, a
-pluginy kanałów obsługują wykrywanie i wykonanie specyficzne dla kanału za nim.
+Pluginy kanałów nie muszą rejestrować osobnego narzędzia wysyłania/edycji/reakcji dla
+standardowych 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:
-- core zarządza hostem współdzielonego narzędzia `message`, podłączaniem promptów, prowadzeniem
- sesji/wątków i dyspozycją wykonania
-- pluginy kanałów obsługują wykrywanie działań z zakresem, wykrywanie capabilities i wszelkie
+- rdzeń odpowiada za host współdzielonego narzędzia `message`, powiązanie z promptami, prowadzenie sesji/wątków
+ oraz dyspozycję wykonania
+- pluginy kanałów odpowiadają za wykrywanie działań w danym zakresie, wykrywanie możliwości oraz wszelkie
fragmenty schematu specyficzne dla kanału
-- pluginy kanałów obsługują gramatykę konwersacji sesji specyficzną dla dostawcy, np.
- sposób, w jaki identyfikatory konwersacji kodują identyfikatory wątków lub dziedziczą po
- konwersacjach nadrzędnych
+- pluginy kanałów odpowiadają za gramatykę konwersacji sesji specyficzną dla dostawcy, na przykład
+ za to, jak identyfikatory konwersacji kodują identyfikatory wątków lub dziedziczą po konwersacjach nadrzędnych
- pluginy kanałów wykonują końcowe działanie przez swój adapter działań
-Dla pluginów kanałów powierzchnią SDK jest
+W przypadku pluginów kanałów powierzchnią SDK jest
`ChannelMessageActionAdapter.describeMessageTool(...)`. To ujednolicone wywołanie wykrywania
-pozwala pluginowi zwrócić widoczne działania, capabilities i wkłady do schematu
-razem, tak aby te elementy nie rozjeżdżały się z czasem.
+pozwala pluginowi zwrócić widoczne działania, możliwości i wkłady do schematu
+razem, aby te elementy się nie rozjeżdżały.
-Core przekazuje zakres runtime do tego kroku wykrywania. Ważne pola obejmują:
+Rdzeń przekazuje zakres środowiska uruchomieniowego do tego kroku wykrywania. Ważne pola obejmują:
- `accountId`
- `currentChannelId`
@@ -191,126 +188,125 @@ Core przekazuje zakres runtime do tego kroku wykrywania. Ważne pola obejmują:
- `sessionKey`
- `sessionId`
- `agentId`
-- zaufane przychodzące `requesterSenderId`
+- zaufany przychodzący `requesterSenderId`
-To ma znaczenie dla pluginów zależnych od kontekstu. Kanał może ukrywać lub ujawniać
-działania wiadomości na podstawie aktywnego konta, bieżącego pokoju/wątku/wiadomości lub
-zaufanej tożsamości nadawcy, bez hardcodowania gałęzi specyficznych dla kanału w
-core'owym narzędziu `message`.
+Ma to znaczenie dla pluginów zależnych od kontekstu. Kanał może ukrywać lub udostępniać
+działania wiadomości na podstawie aktywnego konta, bieżącego pokoju/wątku/wiadomości albo
+zaufanej tożsamości żądającego, bez twardego kodowania gałęzi specyficznych dla kanału w
+narzędziu rdzeniowym `message`.
-To dlatego zmiany routingu embedded-runner nadal są pracą po stronie pluginu: runner
-odpowiada za przekazanie bieżącej tożsamości czatu/sesji do granicy wykrywania pluginu,
-tak aby współdzielone narzędzie `message` ujawniało właściwą powierzchnię należącą do kanału
+Dlatego zmiany routingu embedded-runner nadal są pracą po stronie pluginów: runner
+odpowiada za przekazywanie bieżącej tożsamości czatu/sesji do granicy wykrywania pluginu,
+aby współdzielone narzędzie `message` udostępniało właściwą powierzchnię należącą do kanału
dla bieżącej tury.
-W przypadku helperów wykonania należących do kanału dołączone pluginy powinny trzymać runtime
-wykonania we własnych modułach rozszerzeń. Core nie zarządza już runtime'ami działań wiadomości dla
-Discord, Slack, Telegram ani WhatsApp w `src/agents/tools`.
-Nie publikujemy osobnych subścieżek `plugin-sdk/*-action-runtime`, a dołączone
-pluginy powinny importować własny lokalny kod runtime bezpośrednio ze swoich
+W przypadku helperów wykonawczych należących do kanału bundled plugins powinny utrzymywać logikę wykonania
+środowiska uruchomieniowego we własnych modułach rozszerzeń. Rdzeń nie odpowiada już za środowiska uruchomieniowe
+działań wiadomości Discord, Slack, Telegram ani WhatsApp w `src/agents/tools`.
+Nie publikujemy osobnych ścieżek `plugin-sdk/*-action-runtime`, a bundled
+plugins powinny importować własny lokalny kod środowiska uruchomieniowego bezpośrednio ze swoich
modułów należących do rozszerzenia.
-Ta sama granica dotyczy ogólnie nazwanych według dostawców granic SDK: core nie powinien
-importować wygodnych barrelów specyficznych dla kanałów takich jak Slack, Discord, Signal,
-WhatsApp ani podobnych rozszerzeń. Jeśli core potrzebuje danego zachowania, powinien albo
-korzystać z własnego `api.ts` / `runtime-api.ts` dołączonego pluginu, albo promować tę potrzebę
-do wąskiej, ogólnej capability w współdzielonym SDK.
+Ta sama granica obowiązuje ogólnie dla ścieżek SDK nazwanych od dostawcy: rdzeń nie powinien
+importować wygodnych barreli specyficznych dla kanałów, takich jak Slack, Discord, Signal,
+WhatsApp czy podobne rozszerzenia. Jeśli rdzeń potrzebuje jakiegoś zachowania, powinien albo
+korzystać z własnego barrel `api.ts` / `runtime-api.ts` bundled pluginu, albo podnieść tę potrzebę
+do wąskiej, generycznej możliwości we współdzielonym SDK.
-W przypadku ankiet istnieją obecnie dwie ścieżki wykonania:
+W przypadku ankiet istnieją konkretnie dwie ścieżki wykonania:
-- `outbound.sendPoll` jest współdzieloną bazą dla kanałów pasujących do wspólnego
+- `outbound.sendPoll` to współdzielona baza dla kanałów pasujących do wspólnego
modelu ankiet
-- `actions.handleAction("poll")` jest preferowaną ścieżką 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
+ lub dodatkowych parametrów ankiety
-Core odracza teraz współdzielone parsowanie ankiet do momentu, aż pluginowa dyspozycja ankiety
-odrzuci działanie, tak aby należące do pluginu handlery ankiet mogły akceptować pola ankiet
-specyficzne dla kanału bez wcześniejszego zablokowania przez ogólny parser ankiet.
+Rdzeń odkłada teraz współdzielone parsowanie ankiet do czasu, aż dyspozycja ankiety pluginu odrzuci
+działanie, dzięki czemu obsługujące ankiety handlery należące do pluginu mogą akceptować pola ankiet
+specyficzne dla kanału bez wcześniejszego blokowania przez generyczny parser ankiet.
-Pełną sekwencję uruchamiania znajdziesz w [Load pipeline](#load-pipeline).
+Pełną sekwencję uruchamiania znajdziesz w sekcji [Potok ładowania](#load-pipeline).
-## Model własności capability
+## Model własności możliwości
OpenClaw traktuje natywny plugin jako granicę własności dla **firmy** albo
-**funkcji**, a nie jako worek na niepowiązane integracje.
+**funkcji**, a nie jako zbiór niepowiązanych integracji.
-To oznacza, że:
+Oznacza to, że:
-- plugin firmowy powinien zwykle obsługiwać wszystkie powierzchnie OpenClaw skierowane do tej firmy
-- plugin funkcjonalny powinien zwykle obsługiwać pełną powierzchnię funkcji, którą wprowadza
-- kanały powinny korzystać ze współdzielonych capabilities core zamiast implementować
- zachowanie dostawców ad hoc
+- plugin firmy powinien zwykle posiadać wszystkie powierzchnie OpenClaw skierowane do 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 dostawców
Przykłady:
-- dołączony plugin `openai` obsługuje zachowanie dostawcy modeli OpenAI oraz
- zachowanie OpenAI dla mowy + realtime voice + rozumienia mediów + generowania obrazów
-- dołączony plugin `elevenlabs` obsługuje zachowanie mowy ElevenLabs
-- dołączony plugin `microsoft` obsługuje zachowanie mowy Microsoft
-- dołączony plugin `google` obsługuje zachowanie dostawcy modeli Google oraz Google
- media-understanding + image-generation + web-search
-- dołączony plugin `firecrawl` obsługuje zachowanie web-fetch Firecrawl
-- dołączone pluginy `minimax`, `mistral`, `moonshot` i `zai` obsługują własne
- backendy media-understanding
-- dołączony plugin `qwen` obsługuje zachowanie dostawcy tekstu Qwen oraz
- media-understanding i video-generation
-- plugin `voice-call` jest pluginem funkcjonalnym: obsługuje transport połączeń, narzędzia,
- CLI, trasy i mostkowanie strumieni mediów Twilio, ale korzysta ze współdzielonych capabilities speech
- oraz realtime-transcription i realtime-voice zamiast importować pluginy dostawców bezpośrednio
+- bundled plugin `openai` posiada zachowanie dostawcy modeli OpenAI oraz zachowanie OpenAI dla
+ mowy + głosu w czasie rzeczywistym + rozumienia multimediów + generowania obrazów
+- bundled plugin `elevenlabs` posiada zachowanie mowy ElevenLabs
+- bundled plugin `microsoft` posiada zachowanie mowy Microsoft
+- bundled plugin `google` posiada zachowanie dostawcy modeli Google oraz zachowanie Google dla
+ rozumienia multimediów + generowania obrazów + wyszukiwania w sieci
+- bundled plugin `firecrawl` posiada zachowanie pobierania z sieci Firecrawl
+- bundled pluginy `minimax`, `mistral`, `moonshot` i `zai` posiadają swoje
+ backendy rozumienia multimediów
+- bundled plugin `qwen` posiada zachowanie dostawcy tekstu Qwen oraz
+ rozumienie multimediów i generowanie wideo
+- plugin `voice-call` jest pluginem funkcji: posiada transport połączeń, narzędzia,
+ CLI, trasy i mostkowanie strumienia mediów Twilio, ale korzysta ze współdzielonych możliwości mowy
+ oraz transkrypcji i głosu w czasie rzeczywistym zamiast bezpośrednio importować pluginy dostawców
-Docelowy stan to:
+Zamierzony stan docelowy jest następujący:
-- OpenAI znajduje się w jednym pluginie nawet wtedy, gdy obejmuje modele tekstowe, mowę, obrazy i
+- OpenAI znajduje się w jednym pluginie, nawet jeśli obejmuje modele tekstowe, mowę, obrazy i
przyszłe wideo
-- inny dostawca może zrobić to samo dla własnej powierzchni
-- kanały nie obchodzą, który plugin dostawcy obsługuje provider; korzystają ze
- współdzielonego kontraktu capability udostępnionego przez core
+- inny dostawca może zrobić to samo dla własnego obszaru powierzchni
+- kanały nie interesują się tym, który plugin dostawcy jest właścicielem danego dostawcy; korzystają ze
+ współdzielonego kontraktu możliwości udostępnianego przez rdzeń
To jest kluczowe rozróżnienie:
- **plugin** = granica własności
-- **capability** = kontrakt core, który może być implementowany lub używany przez wiele pluginów
+- **capability** = kontrakt rdzenia, który wiele pluginów może implementować lub wykorzystywać
-Jeśli więc OpenClaw dodaje nową domenę, taką jak wideo, pierwsze pytanie nie brzmi
-„który dostawca powinien na sztywno obsłużyć wideo?”. Pierwsze pytanie brzmi „jaki jest
-kontrakt core capability dla wideo?”. Gdy taki kontrakt istnieje, pluginy dostawców
+Jeśli więc OpenClaw doda nową domenę, taką jak wideo, pierwsze pytanie nie brzmi
+„który dostawca powinien mieć na sztywno zakodowaną obsługę wideo?”. Pierwsze pytanie brzmi:
+„jaki jest kontrakt możliwości wideo w rdzeniu?”. Gdy taki kontrakt już 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 krokiem jest zwykle:
+Jeśli dana możliwość jeszcze nie istnieje, właściwym ruchem jest zwykle:
-1. zdefiniować brakującą capability w core
-2. udostępnić ją w typowany sposób przez API/runtime pluginu
-3. podłączyć kanały/funkcje do tej capability
-4. pozwolić pluginom dostawców zarejestrować implementacje
+1. zdefiniowanie brakującej możliwości w rdzeniu
+2. udostępnienie jej przez API/runtime pluginów w sposób typowany
+3. podłączenie kanałów/funkcji do tej możliwości
+4. umożliwienie pluginom dostawców rejestracji implementacji
-To utrzymuje jawną własność, jednocześnie unikając zachowania core zależnego od
+To utrzymuje jawną własność, jednocześnie unikając zachowania rdzenia zależnego od
jednego dostawcy lub jednorazowej ścieżki kodu specyficznej dla pluginu.
-### Warstwowanie capability
+### Warstwowanie możliwości
-Używaj tego modelu mentalnego przy podejmowaniu decyzji, gdzie powinien znajdować się kod:
+Używaj tego modelu myślowego przy decydowaniu, gdzie powinien znaleźć się kod:
-- **warstwa capability core**: współdzielona orkiestracja, polityka, fallback, zasady
- łączenia konfiguracji, semantyka dostarczania i typowane kontrakty
-- **warstwa pluginu dostawcy**: API specyficzne dla dostawcy, auth, katalogi modeli, synteza mowy,
+- **warstwa możliwości rdzenia**: współdzielona orkiestracja, polityka, fallback, zasady
+ scalania konfiguracji, semantyka dostarczania i typowane kontrakty
+- **warstwa pluginu dostawcy**: API specyficzne dla dostawcy, uwierzytelnianie, katalogi modeli, synteza mowy,
generowanie obrazów, przyszłe backendy wideo, endpointy użycia
-- **warstwa pluginu kanału/funkcji**: integracja Slack/Discord/voice-call/etc.,
- która korzysta z capabilities core i wystawia je na zewnątrz
+- **warstwa pluginu kanału/funkcji**: integracja ze Slack/Discord/voice-call itd.,
+ która wykorzystuje możliwości rdzenia i udostępnia je na swojej powierzchni
-Na przykład TTS ma taki kształt:
+Na przykład TTS ma następującą strukturę:
-- core zarządza polityką TTS przy odpowiedzi, kolejnością fallbacków, preferencjami i dostarczaniem do kanału
-- `openai`, `elevenlabs` i `microsoft` obsługują implementacje syntezy
-- `voice-call` korzysta z helpera runtime TTS dla telefonii
+- rdzeń odpowiada za politykę TTS w czasie odpowiedzi, kolejność fallbacku, preferencje i dostarczanie przez kanały
+- `openai`, `elevenlabs` i `microsoft` odpowiadają za implementacje syntezy
+- `voice-call` wykorzystuje helper środowiska uruchomieniowego 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 z wieloma capabilities
+### Przykład pluginu firmy z wieloma możliwościami
-Plugin firmowy powinien z zewnątrz sprawiać spójne wrażenie. Jeśli OpenClaw ma współdzielone
-kontrakty dla modeli, mowy, transkrypcji realtime, głosu realtime, rozumienia mediów,
-generowania obrazów, generowania wideo, web fetch i web search, dostawca może
-obsługiwać wszystkie swoje powierzchnie w jednym miejscu:
+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
+multimediów, generowania obrazów, generowania wideo, pobierania z sieci i wyszukiwania w sieci,
+dostawca może posiadać wszystkie swoje powierzchnie w jednym miejscu:
```ts
import type { OpenClawPluginDefinition } from "openclaw/plugin-sdk/plugin-entry";
@@ -364,31 +360,31 @@ const plugin: OpenClawPluginDefinition = {
export default plugin;
```
-Liczą się nie tyle dokładne nazwy helperów, co sam kształt:
+Znaczenie mają nie tyle dokładne nazwy helperów. Liczy się struktura:
-- jeden plugin obsługuje powierzchnię dostawcy
-- core nadal obsługuje kontrakty capability
-- kanały i pluginy funkcjonalne korzystają z helperów `api.runtime.*`, a nie z kodu dostawcy
-- testy kontraktów mogą potwierdzić, że plugin zarejestrował capabilities, których
- twierdzi, że jest właścicielem
+- jeden plugin jest właścicielem powierzchni dostawcy
+- rdzeń nadal jest właścicielem kontraktów możliwości
+- kanały i pluginy funkcji korzystają z helperów `api.runtime.*`, a nie z kodu dostawcy
+- testy kontraktowe mogą sprawdzać, że plugin zarejestrował możliwości, których własność
+ deklaruje
-### Przykład capability: rozumienie wideo
+### Przykład możliwości: rozumienie wideo
OpenClaw już traktuje rozumienie obrazów/audio/wideo jako jedną współdzieloną
-capability. Ten sam model własności ma tu zastosowanie:
+możliwość. Ten sam model własności obowiązuje również tutaj:
-1. core definiuje kontrakt media-understanding
-2. pluginy dostawców rejestrują `describeImage`, `transcribeAudio` i
- `describeVideo`, stosownie do możliwości
-3. kanały i pluginy funkcjonalne korzystają ze współdzielonego zachowania core zamiast
- bezpośrednio podłączać kod dostawcy
+1. rdzeń definiuje kontrakt media-understanding
+2. pluginy dostawców rejestrują odpowiednio `describeImage`, `transcribeAudio` oraz
+ `describeVideo`
+3. kanały i pluginy funkcji korzystają ze współdzielonego zachowania rdzenia zamiast
+ łączyć się bezpośrednio z kodem dostawcy
-To zapobiega wpisaniu założeń jednego dostawcy o wideo na stałe do core. Plugin obsługuje
-powierzchnię dostawcy; core obsługuje kontrakt capability i zachowanie fallback.
+Pozwala to uniknąć zaszywania założeń jednego dostawcy dotyczących wideo w rdzeniu. Plugin jest właścicielem
+powierzchni dostawcy; rdzeń jest właścicielem kontraktu możliwości i zachowania fallbacku.
-Generowanie wideo używa już tej samej sekwencji: core obsługuje typowany
-kontrakt capability i helper runtime, a pluginy dostawców rejestrują
-implementacje `api.registerVideoGenerationProvider(...)`.
+Generowanie wideo już używa tej samej sekwencji: rdzeń jest właścicielem typowanego
+kontraktu możliwości i helpera środowiska uruchomieniowego, a pluginy dostawców rejestrują
+implementacje `api.registerVideoGenerationProvider(...)` względem niego.
Potrzebujesz konkretnej listy wdrożeniowej? Zobacz
[Capability Cookbook](/pl/plugins/architecture).
@@ -396,190 +392,197 @@ Potrzebujesz konkretnej listy wdrożeniowej? Zobacz
## Kontrakty i egzekwowanie
Powierzchnia API pluginów jest celowo typowana i scentralizowana w
-`OpenClawPluginApi`. Ten kontrakt definiuje wspierane punkty rejestracji oraz
-helpery runtime, na których plugin może polegać.
+`OpenClawPluginApi`. Ten kontrakt definiuje obsługiwane punkty rejestracji oraz
+helpery środowiska uruchomieniowego, na których plugin może polegać.
-Dlaczego to ważne:
+Dlaczego to ma znaczenie:
-- autorzy pluginów dostają jeden stabilny wewnętrzny standard
-- core może odrzucać zduplikowaną własność, na przykład dwa pluginy rejestrujące ten sam
+- autorzy pluginów otrzymują jeden stabilny standard wewnętrzny
+- rdzeń może odrzucać duplikaty własności, takie jak dwa pluginy rejestrujące ten sam
identyfikator dostawcy
- podczas uruchamiania można pokazać użyteczne diagnostyki dla nieprawidłowej rejestracji
-- testy kontraktów mogą egzekwować własność dołączonych pluginów i zapobiegać cichemu driftowi
+- testy kontraktowe mogą wymuszać własność bundled-pluginów i zapobiegać cichemu dryfowi
Istnieją dwie warstwy egzekwowania:
-1. **egzekwowanie rejestracji w runtime**
+1. **egzekwowanie rejestracji w czasie wykonywania**
Rejestr pluginów waliduje rejestracje podczas ładowania pluginów. Przykłady:
- zduplikowane identyfikatory providerów, zduplikowane identyfikatory dostawców mowy i nieprawidłowe
+ zduplikowane identyfikatory dostawców, zduplikowane identyfikatory dostawców mowy i nieprawidłowe
rejestracje powodują diagnostyki pluginów zamiast niezdefiniowanego zachowania.
-2. **testy kontraktów**
- Dołączone pluginy są przechwytywane w rejestrach kontraktów podczas uruchamiania testów, aby
- OpenClaw mógł jawnie potwierdzać własność. Obecnie używa się tego dla
- providerów modeli, dostawców mowy, dostawców web search i własności rejestracji dołączonych pluginów.
+2. **testy kontraktowe**
+ Bundled plugins są przechwytywane w rejestrach kontraktowych podczas uruchomień testów, aby
+ OpenClaw mógł jednoznacznie sprawdzać własność. Obecnie jest to używane dla
+ dostawców modeli, dostawców mowy, dostawców wyszukiwania w sieci oraz własności
+ rejestracji bundled pluginów.
-Praktyczny efekt jest taki, że OpenClaw wie z góry, który plugin obsługuje którą
-powierzchnię. Dzięki temu core i kanały mogą składać się bezproblemowo, ponieważ własność jest
-zadeklarowana, typowana i testowalna, a nie dorozumiana.
+Praktyczny efekt jest taki, że OpenClaw z góry wie, który plugin jest właścicielem której
+powierzchni. Dzięki temu rdzeń i kanały mogą składać się bezproblemowo, ponieważ własność jest
+zadeklarowana, typowana i testowalna, a nie domyślna.
-### Co należy do kontraktu
+### Co powinno należeć do kontraktu
Dobre kontrakty pluginów są:
- typowane
- małe
-- specyficzne dla capability
-- należące do core
-- możliwe do ponownego użycia przez wiele pluginów
-- możliwe do użycia przez kanały/funkcje bez wiedzy o dostawcy
+- 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
Złe kontrakty pluginów to:
-- polityka specyficzna dla dostawcy ukryta w core
+- polityka specyficzna dla dostawcy ukryta w rdzeniu
- jednorazowe furtki dla pluginów omijające 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 niej 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ą **wewnątrz procesu** razem z Gateway. Nie są
-sandboxowane. Załadowany natywny plugin ma tę samą granicę zaufania na poziomie procesu co
-kod core.
+Natywne pluginy OpenClaw działają **w procesie** razem z Gateway. Nie są
+izolowane. Załadowany natywny plugin ma tę samą granicę zaufania na poziomie procesu co
+kod rdzenia.
-Implikacje:
+Konsekwencje:
- natywny plugin może rejestrować narzędzia, handlery sieciowe, hooki i usługi
-- błąd natywnego pluginu może zawiesić lub zdestabilizować gateway
+- błąd natywnego pluginu może spowodować awarię lub destabilizację gateway
- złośliwy natywny plugin jest równoważny dowolnemu wykonaniu kodu wewnątrz
procesu OpenClaw
-Kompatybilne bundle są domyślnie bezpieczniejsze, ponieważ OpenClaw obecnie traktuje je
-jako paczki metadanych/treści. W obecnych wydaniach oznacza to głównie dołączone
+Zgodne bundle są domyślnie bezpieczniejsze, ponieważ OpenClaw obecnie traktuje je
+jako pakiety metadanych/treści. W obecnych wydaniach oznacza to głównie bundled
Skills.
-Dla pluginów niedołączonych używaj allowlist i jawnych ścieżek instalacji/ładowania. Traktuj
-pluginy workspace jako kod deweloperski, a nie domyślne ustawienie produkcyjne.
+Dla pluginów, które nie są bundled, używaj list dozwolonych i jawnych ścieżek instalacji/ładowania. Traktuj
+pluginy workspace jako kod czasu programowania, a nie domyślne ustawienie produkcyjne.
-Dla nazw pakietów dołączonych pluginów workspace utrzymuj identyfikator pluginu zakotwiczony w nazwie npm:
-domyślnie `@openclaw/` albo zatwierdzony sufiks typowany, taki jak
+W przypadku nazw pakietów bundled workspace utrzymuj 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 wystawia węższą rolę pluginu.
+pakiet celowo udostępnia węższą rolę pluginu.
Ważna uwaga dotycząca zaufania:
- `plugins.allow` ufa **identyfikatorom pluginów**, a nie pochodzeniu źródła.
-- Plugin workspace o tym samym identyfikatorze co dołączony plugin celowo przesłania
- dołączoną kopię, gdy ten plugin workspace jest włączony/na allowliście.
-- To normalne i przydatne przy lokalnym rozwoju, testowaniu poprawek i hotfixach.
+- Plugin workspace o tym samym identyfikatorze co bundled plugin celowo zasłania
+ bundled copy, gdy ten plugin workspace jest włączony/znajduje się na liście dozwolonych.
+- To normalne i przydatne przy lokalnym programowaniu, testowaniu poprawek i hotfixach.
## Granica eksportu
-OpenClaw eksportuje capabilities, a nie implementacyjne ułatwienia.
+OpenClaw eksportuje możliwości, a nie wygodne szczegóły implementacyjne.
-Utrzymuj publiczną rejestrację capability. Ograniczaj eksport helperów, które nie są częścią kontraktu:
+Pozostaw publiczną rejestrację możliwości. Ogranicz eksport helperów niebędących częścią kontraktu:
-- subścieżki helperów specyficznych dla dołączonych pluginów
-- subścieżki infrastruktury runtime, które nie są przeznaczone jako publiczne API
-- helpery wygodne specyficzne dla dostawców
-- helpery konfiguracji/onboardingu będące szczegółami implementacji
+- ścieżki helperów specyficznych dla bundled pluginów
+- ścieżki logiki runtime, które nie są przeznaczone jako publiczne API
+- helpery wygody specyficzne dla dostawcy
+- helpery konfiguracji/onboardingu będące szczegółami implementacyjnymi
-Niektóre subścieżki helperów dołączonych pluginów nadal pozostają w wygenerowanej mapie eksportów SDK
-ze względów kompatybilności i utrzymania dołączonych pluginów. Aktualne przykłady to
+Niektóre ścieżki helperów bundled pluginów nadal pozostają w wygenerowanej mapie eksportów SDK
+ze względu na zgodność i utrzymanie bundled pluginów. Obecne przykłady to
`plugin-sdk/feishu`, `plugin-sdk/feishu-setup`, `plugin-sdk/zalo`,
-`plugin-sdk/zalo-setup` oraz kilka granic `plugin-sdk/matrix*`. Traktuj je jako
-zastrzeżone eksporty będące szczegółami implementacji, a nie jako zalecany wzorzec SDK dla
+`plugin-sdk/zalo-setup` oraz kilka ścieżek `plugin-sdk/matrix*`. Traktuj je jako
+zastrzeżone eksporty szczegółów implementacyjnych, a nie jako zalecany wzorzec SDK dla
nowych pluginów zewnętrznych.
-## Pipeline ładowania
+## Potok ładowania
-Podczas uruchamiania OpenClaw robi w przybliżeniu to:
+Podczas uruchamiania OpenClaw w przybliżeniu wykonuje następujące kroki:
1. wykrywa katalogi główne kandydackich pluginów
-2. odczytuje natywne lub kompatybilne manifesty bundle i metadane pakietów
+2. odczytuje natywne manifesty lub manifesty zgodnych 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 natywne moduły przez jiti
-7. wywołuje hooki natywnego `register(api)` (lub `activate(api)` — legacy alias) i zbiera rejestracje do rejestru pluginów
-8. udostępnia rejestr komendom/powierzchniom runtime
+5. podejmuje decyzję o włączeniu dla każdego kandydata
+6. ładuje włączone moduły natywne przez jiti
+7. wywołuje natywne hooki `register(api)` (lub `activate(api)` — alias legacy) i zbiera rejestracje do rejestru pluginów
+8. udostępnia rejestr powierzchniom komend/runtime
-`activate` jest legacy aliasem `register` — loader rozwiązuje to, co jest obecne (`def.register ?? def.activate`) i wywołuje je w tym samym miejscu. Wszystkie dołączone pluginy używają `register`; dla nowych pluginów preferuj `register`.
+`activate` to alias legacy dla `register` — loader rozwiązuje ten, który jest obecny (`def.register ?? def.activate`) i wywołuje go w tym samym miejscu. Wszystkie bundled plugins używają `register`; dla nowych pluginów preferuj `register`.
-Bramki bezpieczeństwa działają **przed** wykonaniem runtime. Kandydaci są blokowani,
-gdy entry wychodzi poza katalog główny pluginu, ścieżka ma uprawnienia world-writable albo
-własność ścieżki wygląda podejrzanie dla pluginów niedołączonych.
+Bramki bezpieczeństwa działają **przed** wykonaniem kodu runtime. Kandydaci są blokowani,
+gdy entry wychodzi poza katalog główny pluginu, ścieżka ma prawa world-writable albo
+własność ścieżki wygląda podejrzanie w przypadku pluginów, które nie są bundled.
### Zachowanie manifest-first
-Manifest jest źródłem prawdy dla control plane. OpenClaw używa go do:
+Manifest jest źródłem prawdy dla warstwy control plane. OpenClaw używa go do:
- identyfikacji pluginu
-- wykrywania deklarowanych 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
-- wyświetlania metadanych instalacji/katalogu
+- wzbogacania etykiet i placeholderów w Control UI
+- pokazywania metadanych instalacji/katalogu
+- zachowywania lekkich deskryptorów aktywacji i konfiguracji bez ładowania runtime pluginu
-Dla natywnych pluginów moduł runtime jest częścią data plane. Rejestruje
-rzeczywiste zachowania, takie jak hooki, narzędzia, komendy lub przepływy providerów.
+W przypadku natywnych pluginów moduł runtime jest częścią data plane. Rejestruje
+rzeczywiste zachowania, takie jak hooki, narzędzia, komendy czy przepływy dostawców.
-### Co loader przechowuje w cache
+Opcjonalne bloki manifestu `activation` i `setup` pozostają w control plane.
+Są to deskryptory wyłącznie metadanych do planowania aktywacji i wykrywania konfiguracji;
+nie zastępują rejestracji runtime, `register(...)` ani `setupEntry`.
-OpenClaw utrzymuje krótkie cache'e wewnątrz procesu dla:
+### Co loader przechowuje w pamięci podręcznej
+
+OpenClaw utrzymuje krótkotrwałe pamięci podręczne w procesie dla:
- wyników wykrywania
- danych rejestru manifestów
- załadowanych rejestrów pluginów
-Te cache'e zmniejszają koszt gwałtownych startów i powtarzanych komend. Można o nich myśleć
-jako o krótkotrwałych cache'ach wydajnościowych, a nie o trwałym stanie.
+Te pamięci podręczne ograniczają skokowe obciążenie przy starcie i narzut powtarzanych komend. Można je bezpiecznie
+traktować jako krótkotrwałe cache wydajnościowe, a nie trwałe przechowywanie.
Uwaga dotycząca wydajności:
- Ustaw `OPENCLAW_DISABLE_PLUGIN_DISCOVERY_CACHE=1` albo
- `OPENCLAW_DISABLE_PLUGIN_MANIFEST_CACHE=1`, aby wyłączyć te cache'e.
-- Okna cache można stroić przez `OPENCLAW_PLUGIN_DISCOVERY_CACHE_MS` i
+ `OPENCLAW_DISABLE_PLUGIN_MANIFEST_CACHE=1`, aby wyłączyć te pamięci podręczne.
+- Dostosuj okna cache za pomocą `OPENCLAW_PLUGIN_DISCOVERY_CACHE_MS` i
`OPENCLAW_PLUGIN_MANIFEST_CACHE_MS`.
## Model rejestru
-Załadowane pluginy nie mutują bezpośrednio losowych globali core. Rejestrują się w
+Załadowane pluginy nie mutują bezpośrednio przypadkowych globali rdzenia. Rejestrują się w
centralnym rejestrze pluginów.
Rejestr śledzi:
- rekordy pluginów (tożsamość, źródło, pochodzenie, status, diagnostyka)
- narzędzia
-- legacy hooks i hooki typowane
+- legacy hooks i typowane hooki
- kanały
-- providerów
+- dostawców
- handlery Gateway RPC
- trasy HTTP
- rejestratory CLI
-- usługi w tle
+- usługi działające w tle
- komendy należące do pluginów
-Funkcje core odczytują następnie z tego rejestru zamiast komunikować się bezpośrednio z modułami pluginów.
-Dzięki temu ładowanie pozostaje jednokierunkowe:
+Funkcje rdzenia odczytują następnie dane 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 „obsługuj osobno każdy moduł pluginu”.
+To rozdzielenie ma znaczenie dla utrzymania. Oznacza, że większość powierzchni rdzenia potrzebuje tylko
+jednego punktu integracji: „odczytaj rejestr”, a nie „obsłuż specjalnie każdy moduł
+pluginu”.
-## Callbacki powiązania konwersacji
+## Callbacki wiązania konwersacji
Pluginy, które wiążą konwersację, mogą reagować po rozstrzygnięciu zatwierdzenia.
-Użyj `api.onConversationBindingResolved(...)`, aby otrzymać callback po zatwierdzeniu lub odrzuceniu
-żądania powiązania:
+Użyj `api.onConversationBindingResolved(...)`, aby otrzymać callback po zatwierdzeniu
+lub odrzuceniu żądania powiązania:
```ts
export default {
@@ -599,25 +602,25 @@ export default {
};
```
-Pola ładunku callbacka:
+Pola ładunku callbacku:
- `status`: `"approved"` lub `"denied"`
- `decision`: `"allow-once"`, `"allow-always"` lub `"deny"`
- `binding`: rozstrzygnięte powiązanie dla zatwierdzonych żądań
-- `request`: oryginalne podsumowanie żądania, wskazówka odłączenia, identyfikator nadawcy oraz
+- `request`: podsumowanie oryginalnego żądania, wskazówka odłączenia, identyfikator nadawcy oraz
metadane konwersacji
Ten callback służy wyłącznie do powiadamiania. Nie zmienia tego, kto może powiązać
-konwersację, i uruchamia się po zakończeniu obsługi zatwierdzenia przez core.
+konwersację, i działa po zakończeniu obsługi zatwierdzenia przez rdzeń.
-## Hooki runtime dostawcy
+## Hooki środowiska uruchomieniowego dostawcy
Pluginy dostawców mają teraz dwie warstwy:
-- metadane manifestu: `providerAuthEnvVars` dla taniego sprawdzania auth dostawcy z env
- przed załadowaniem runtime, `providerAuthAliases` dla wariantów dostawców współdzielących
- auth, `channelEnvVars` dla taniego sprawdzania env/konfiguracji kanału przed
- załadowaniem runtime oraz `providerAuthChoices` dla tanich etykiet onboardingu/wyboru auth i
+- metadane manifestu: `providerAuthEnvVars` do taniego wyszukiwania uwierzytelniania dostawcy z env
+ przed załadowaniem runtime, `providerAuthAliases` dla wariantów dostawcy współdzielących
+ uwierzytelnianie, `channelEnvVars` do taniego wyszukiwania uwierzytelniania/konfiguracji kanału z env przed
+ załadowaniem runtime, a także `providerAuthChoices` do tanich etykiet onboardingu/wyboru uwierzytelniania i
metadanych flag CLI przed załadowaniem runtime
- hooki czasu konfiguracji: `catalog` / legacy `discovery` oraz `applyConfigDefaults`
- hooki runtime: `normalizeModelId`, `normalizeTransport`,
@@ -640,88 +643,88 @@ Pluginy dostawców mają teraz dwie warstwy:
`buildReplayPolicy`,
`sanitizeReplayHistory`, `validateReplayTurns`, `onModelSelected`
-OpenClaw nadal obsługuje ogólną pętlę agenta, failover, obsługę transkryptów i
-politykę narzędzi. Te hooki są powierzchnią rozszerzeń dla zachowań specyficznych dla dostawcy bez
-potrzeby budowania całkowicie niestandardowego transportu inferencyjnego.
+OpenClaw nadal odpowiada za ogólną pętlę agenta, failover, obsługę transkryptu i
+politykę narzędzi. Te hooki stanowią powierzchnię rozszerzeń dla zachowań specyficznych dla dostawców bez
+potrzeby tworzenia całego niestandardowego transportu wnioskowania.
-Używaj manifestowego `providerAuthEnvVars`, gdy dostawca ma poświadczenia oparte na env,
-które ogólne ścieżki auth/status/wyboru modelu powinny widzieć bez ładowania runtime pluginu.
-Używaj manifestowego `providerAuthAliases`, gdy jeden identyfikator dostawcy ma ponownie używać
-zmiennych env, profili auth, auth opartego na konfiguracji oraz wyboru onboardingu klucza API
-innego identyfikatora dostawcy. Używaj manifestowego `providerAuthChoices`, gdy powierzchnie
-CLI onboardingu/wyboru auth powinny znać identyfikator wyboru dostawcy, etykiety grup i prostą
-obsługę auth przez pojedynczą flagę bez ładowania runtime dostawcy. Zachowaj runtime'owe
-`envVars` dostawcy dla wskazówek operatora, takich jak etykiety onboardingowe lub zmienne
-konfiguracji OAuth client-id/client-secret.
+Używaj manifestu `providerAuthEnvVars`, gdy dostawca ma poświadczenia oparte na env,
+które generyczne ścieżki uwierzytelniania/statusu/wyboru modelu powinny widzieć bez ładowania runtime pluginu.
+Używaj manifestu `providerAuthAliases`, gdy jeden identyfikator dostawcy ma ponownie wykorzystywać
+zmienne env, profile uwierzytelniania, uwierzytelnianie oparte na konfiguracji oraz wybór onboardingowy klucza API
+innego identyfikatora dostawcy. Używaj manifestu `providerAuthChoices`, gdy powierzchnie CLI onboardingu/wyboru uwierzytelniania
+powinny znać identyfikator wyboru dostawcy, etykiety grup i proste
+powiązanie uwierzytelniania z jedną flagą bez ładowania runtime dostawcy. Pozostaw runtime dostawcy
+`envVars` dla wskazówek widocznych dla operatora, takich jak etykiety onboardingu lub zmienne konfiguracji
+client-id/client-secret OAuth.
-Używaj manifestowego `channelEnvVars`, gdy kanał ma auth lub konfigurację opartą na env, które
-ogólny fallback z shell-env, sprawdzania config/status albo prompty konfiguracji powinny widzieć
+Używaj manifestu `channelEnvVars`, gdy kanał ma uwierzytelnianie lub konfigurację sterowane przez env, które
+generyczny fallback do env powłoki, sprawdzenia konfiguracji/statusu lub prompty konfiguracji powinny widzieć
bez ładowania runtime kanału.
-### Kolejność hooków i ich użycie
+### Kolejność hooków i sposób użycia
-Dla pluginów model/provider OpenClaw wywołuje hooki mniej więcej w tej kolejności.
-Kolumna „Kiedy używać” to szybki przewodnik decyzyjny.
+W przypadku pluginów modeli/dostawców OpenClaw wywołuje hooki mniej więcej w tej kolejności.
+Kolumna „Kiedy używać” jest krótkim przewodnikiem decyzyjnym.
| # | Hook | Co robi | Kiedy używać |
-| --- | --------------------------------- | -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
-| 1 | `catalog` | Publikuje konfigurację dostawcy do `models.providers` podczas generowania `models.json` | Dostawca posiada katalog albo domyślne wartości `baseUrl` |
-| 2 | `applyConfigDefaults` | Stosuje globalne domyślne ustawienia konfiguracji należące do dostawcy podczas materializacji konfiguracji | Ustawienia domyślne zależą od trybu auth, env lub semantyki rodziny modeli dostawcy |
-| -- | _(wbudowane wyszukiwanie modelu)_ | OpenClaw najpierw próbuje normalnej ścieżki rejestru/katalogu | _(to nie jest hook pluginu)_ |
-| 3 | `normalizeModelId` | Normalizuje legacy aliasy identyfikatorów modeli lub wersji preview przed wyszukaniem | Dostawca zarządza porządkowaniem aliasów przed kanonicznym rozstrzygnięciem modelu |
-| 4 | `normalizeTransport` | Normalizuje `api` / `baseUrl` dla rodziny dostawców przed ogólnym składaniem modelu | Dostawca zarządza porządkowaniem transportu dla niestandardowych identyfikatorów dostawców w tej samej rodzinie transportu |
-| 5 | `normalizeConfig` | Normalizuje `models.providers.` przed rozstrzygnięciem runtime/dostawcy | Dostawca potrzebuje porządkowania konfiguracji, które powinno znajdować się w pluginie; dołączone helpery rodziny Google również wspierają tu wspierane wpisy konfiguracji Google |
-| 6 | `applyNativeStreamingUsageCompat` | Stosuje kompatybilnościowe przepisywanie natywnego użycia streaming do providerów konfiguracji | Dostawca potrzebuje poprawek metadanych natywnego użycia streaming zależnych od endpointu |
-| 7 | `resolveConfigApiKey` | Rozstrzyga auth typu env-marker dla providerów konfiguracji przed ładowaniem auth runtime | Dostawca ma własne rozstrzyganie klucza API przez env-marker; `amazon-bedrock` ma tu także wbudowany resolver env-marker AWS |
-| 8 | `resolveSyntheticAuth` | Ujawnia auth lokalny/self-hosted albo oparty na konfiguracji bez utrwalania jawnego tekstu | Dostawca może działać z syntetycznym/lokalnym markerem poświadczeń |
-| 9 | `resolveExternalAuthProfiles` | Nakłada profile zewnętrznego auth należące do dostawcy; domyślne `persistence` to `runtime-only` dla poświadczeń należących do CLI/aplikacji | Dostawca ponownie używa poświadczeń zewnętrznego auth bez utrwalania skopiowanych refresh tokenów |
-| 10 | `shouldDeferSyntheticProfileAuth` | Obniża priorytet zapisanych syntetycznych placeholderów profili względem auth opartego na env/konfiguracji | Dostawca przechowuje syntetyczne placeholdery profili, które nie powinny mieć pierwszeństwa |
-| 11 | `resolveDynamicModel` | Synchroniczny fallback dla identyfikatorów modeli należących do dostawcy, których nie ma jeszcze w lokalnym rejestrze | Dostawca akceptuje dowolne identyfikatory modeli upstream |
-| 12 | `prepareDynamicModel` | Asynchroniczne rozgrzanie, po czym `resolveDynamicModel` uruchamia się ponownie | Dostawca potrzebuje metadanych z sieci przed rozstrzyganiem nieznanych identyfikatorów |
-| 13 | `normalizeResolvedModel` | Ostateczne przepisanie przed użyciem rozstrzygniętego modelu przez embedded runner | Dostawca potrzebuje przepisań transportu, ale nadal używa transportu core |
-| 14 | `contributeResolvedModelCompat` | Dostarcza flagi kompatybilności dla modeli dostawcy działających przez inny kompatybilny transport | Dostawca rozpoznaje własne modele na transportach proxy bez przejmowania roli dostawcy |
-| 15 | `capabilities` | Metadane transkryptów/narzędzi należące do dostawcy, używane przez współdzieloną logikę core | Dostawca potrzebuje niuansów związanych z transkryptem/rodziną dostawców |
-| 16 | `normalizeToolSchemas` | Normalizuje schematy narzędzi, zanim zobaczy je embedded runner | Dostawca potrzebuje porządkowania schematów dla rodziny transportu |
-| 17 | `inspectToolSchemas` | Ujawnia diagnostykę schematów należącą do dostawcy po normalizacji | Dostawca chce ostrzeżeń o słowach kluczowych bez uczenia core zasad specyficznych dla dostawcy |
-| 18 | `resolveReasoningOutputMode` | Wybiera natywny albo tagowany kontrakt wyjścia reasoning | Dostawca potrzebuje tagowanego reasoning/final output zamiast natywnych pól |
-| 19 | `prepareExtraParams` | Normalizacja parametrów żądania przed ogólnymi wrapperami opcji stream | Dostawca potrzebuje domyślnych parametrów żądania lub porządkowania parametrów dla konkretnego dostawcy |
-| 20 | `createStreamFn` | W pełni zastępuje normalną ścieżkę stream własnym transportem | Dostawca potrzebuje własnego protokołu wire, a nie tylko wrappera |
-| 21 | `wrapStreamFn` | Wrapper stream po zastosowaniu ogólnych wrapperów | Dostawca potrzebuje wrapperów zgodności nagłówków/ciała/modelu bez własnego transportu |
-| 22 | `resolveTransportTurnState` | Dołącza natywne nagłówki per-turn transportu lub metadane | Dostawca chce, aby ogólne transporty wysyłały natywną tożsamość tury dostawcy |
-| 23 | `resolveWebSocketSessionPolicy` | Dołącza natywne nagłówki WebSocket albo politykę cool-down sesji | Dostawca chce, by ogólne transporty WS stroiły nagłówki sesji lub politykę fallback |
-| 24 | `formatApiKey` | Formatter profilu auth: zapisany profil staje się runtime'owym ciągiem `apiKey` | Dostawca przechowuje dodatkowe metadane auth i potrzebuje niestandardowego kształtu tokenu runtime |
-| 25 | `refreshOAuth` | Nadpisanie odświeżania OAuth dla niestandardowych endpointów odświeżania lub polityki błędów odświeżania | Dostawca nie pasuje do współdzielonych odświeżaczy `pi-ai` |
-| 26 | `buildAuthDoctorHint` | Wskazówka naprawcza dołączana po niepowodzeniu odświeżenia OAuth | Dostawca potrzebuje własnych wskazówek naprawy auth po błędzie odświeżenia |
-| 27 | `matchesContextOverflowError` | Matcher przepełnienia okna kontekstu należący do dostawcy | Dostawca ma surowe błędy przepełnienia, których ogólne heurystyki nie wychwycą |
-| 28 | `classifyFailoverReason` | Klasyfikacja przyczyn failover należąca do dostawcy | Dostawca potrafi mapować surowe błędy API/transportu na rate-limit/przeciążenie itp. |
-| 29 | `isCacheTtlEligible` | Polityka prompt-cache dla dostawców proxy/backhaul | Dostawca potrzebuje bramkowania TTL cache specyficznego dla proxy |
-| 30 | `buildMissingAuthMessage` | Zastępstwo dla ogólnego komunikatu odzyskiwania po braku auth | Dostawca potrzebuje specyficznej dla siebie wskazówki odzyskiwania po braku auth |
-| 31 | `suppressBuiltInModel` | Tłumienie przestarzałych modeli upstream plus opcjonalna wskazówka błędu dla użytkownika | Dostawca musi ukrywać przestarzałe wiersze upstream lub zastąpić je wskazówką dostawcy |
-| 32 | `augmentModelCatalog` | Syntetyczne/końcowe wiersze katalogu dodawane po wykryciu | Dostawca potrzebuje syntetycznych wierszy zgodnych z przyszłością w `models list` i selektorach |
-| 33 | `isBinaryThinking` | Przełącznik on/off reasoning dla providerów binary-thinking | Dostawca udostępnia tylko binarne włączenie/wyłączenie thinking |
-| 34 | `supportsXHighThinking` | Obsługa reasoning `xhigh` dla wybranych modeli | Dostawca chce `xhigh` tylko dla podzbioru modeli |
-| 35 | `resolveDefaultThinkingLevel` | Domyślny poziom `/think` dla konkretnej rodziny modeli | Dostawca zarządza domyślną polityką `/think` dla rodziny modeli |
-| 36 | `isModernModelRef` | Matcher nowoczesnych modeli do filtrów live profile i wyboru smoke | Dostawca zarządza dopasowaniem preferowanych modeli live/smoke |
-| 37 | `prepareRuntimeAuth` | Wymienia skonfigurowane poświadczenie na właściwy token/klucz runtime tuż przed inferencją | Dostawca potrzebuje wymiany tokenu albo krótkotrwałego poświadczenia dla żądania |
-| 38 | `resolveUsageAuth` | Rozstrzyga poświadczenia użycia/rozliczeń dla `/usage` i powiązanych powierzchni statusu | Dostawca potrzebuje własnego parsowania tokenów użycia/kwot lub innego poświadczenia użycia |
-| 39 | `fetchUsageSnapshot` | Pobiera i normalizuje snapshoty użycia/kwot specyficzne dla dostawcy po rozstrzygnięciu auth | Dostawca potrzebuje endpointu użycia lub parsera ładunku specyficznego dla dostawcy |
-| 40 | `createEmbeddingProvider` | Buduje adapter embeddingów należący do dostawcy dla pamięci/wyszukiwania | Zachowanie embeddingów pamięci należy do pluginu dostawcy |
-| 41 | `buildReplayPolicy` | Zwraca politykę replay kontrolującą obsługę transkryptu dla dostawcy | Dostawca potrzebuje własnej polityki transkryptów (na przykład usuwania bloków thinking) |
-| 42 | `sanitizeReplayHistory` | Przepisuje historię replay po ogólnym czyszczeniu transkryptu | Dostawca potrzebuje własnych przepisań replay wykraczających poza współdzielone helpery kompaktowania |
-| 43 | `validateReplayTurns` | Ostateczna walidacja lub przekształcenie tur replay przed embedded runnerem | Transport dostawcy wymaga surowszej walidacji tur po ogólnej sanitacji |
-| 44 | `onModelSelected` | Uruchamia skutki uboczne należące do dostawcy po wybraniu modelu | Dostawca potrzebuje telemetrii lub stanu należącego do dostawcy, gdy model staje się aktywny |
+| --- | --------------------------------- | -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
+| 1 | `catalog` | Publikuje konfigurację dostawcy do `models.providers` podczas generowania `models.json` | Dostawca posiada katalog lub domyślne wartości `base URL` |
+| 2 | `applyConfigDefaults` | Stosuje globalne domyślne ustawienia konfiguracji należące do dostawcy podczas materializacji konfiguracji | Wartości domyślne zależą od trybu uwierzytelniania, env lub semantyki rodziny modeli dostawcy |
+| -- | _(built-in model lookup)_ | OpenClaw najpierw próbuje zwykłej ścieżki rejestru/katalogu | _(to nie jest hook pluginu)_ |
+| 3 | `normalizeModelId` | Normalizuje aliasy legacy lub preview identyfikatorów modeli przed wyszukaniem | Dostawca odpowiada za porządkowanie aliasów przed rozstrzygnięciem kanonicznego modelu |
+| 4 | `normalizeTransport` | Normalizuje `api` / `baseUrl` rodziny dostawcy przed generycznym złożeniem modelu | Dostawca odpowiada za porządkowanie transportu dla niestandardowych identyfikatorów dostawców w tej samej rodzinie transportu |
+| 5 | `normalizeConfig` | Normalizuje `models.providers.` przed rozstrzygnięciem runtime/dostawcy | Dostawca potrzebuje porządkowania konfiguracji, które powinno znajdować się przy pluginie; bundled helpery rodziny Google dodatkowo wspierają obsługiwane wpisy konfiguracji Google |
+| 6 | `applyNativeStreamingUsageCompat` | Stosuje przepisywanie zgodności natywnego użycia streamingu do dostawców konfiguracji | Dostawca potrzebuje poprawek metadanych natywnego użycia streamingu zależnych od endpointu |
+| 7 | `resolveConfigApiKey` | Rozstrzyga uwierzytelnianie env-marker dla dostawców konfiguracji przed załadowaniem uwierzytelniania runtime | Dostawca ma należące do niego rozstrzyganie klucza API opartego na env-marker; `amazon-bedrock` ma tu również wbudowany resolver env-marker AWS |
+| 8 | `resolveSyntheticAuth` | Udostępnia lokalne/self-hosted lub oparte na konfiguracji uwierzytelnianie bez utrwalania jawnego tekstu | Dostawca może działać z syntetycznym/lokalnym markerem poświadczeń |
+| 9 | `resolveExternalAuthProfiles` | Nakłada zewnętrzne profile uwierzytelniania należące do dostawcy; domyślne `persistence` to `runtime-only` dla poświadczeń należących do CLI/aplikacji | Dostawca ponownie wykorzystuje zewnętrzne poświadczenia uwierzytelniania bez utrwalania skopiowanych tokenów odświeżania |
+| 10 | `shouldDeferSyntheticProfileAuth` | Obniża priorytet przechowywanych syntetycznych placeholderów profili względem uwierzytelniania opartego na env/konfiguracji | Dostawca przechowuje syntetyczne placeholdery profili, które nie powinny mieć pierwszeństwa |
+| 11 | `resolveDynamicModel` | Synchroniczny fallback dla identyfikatorów modeli należących do dostawcy, których jeszcze nie ma w lokalnym rejestrze | Dostawca akceptuje dowolne identyfikatory modeli z upstream |
+| 12 | `prepareDynamicModel` | Asynchroniczne rozgrzanie, po którym `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 działających za innym zgodnym transportem | Dostawca rozpoznaje własne modele na transportach proxy bez przejmowania roli dostawcy |
+| 15 | `capabilities` | Metadane transkryptu/narzędzi należące do dostawcy, używane przez współdzieloną logikę rdzenia | Dostawca potrzebuje niuansów specyficznych dla transkryptu/rodziny dostawcy |
+| 16 | `normalizeToolSchemas` | Normalizuje schematy narzędzi, zanim zobaczy je embedded runner | Dostawca potrzebuje porządkowania schematów specyficznego dla rodziny transportu |
+| 17 | `inspectToolSchemas` | Udostępnia diagnostykę schematów należącą do dostawcy po normalizacji | Dostawca chce ostrzeżeń o słowach kluczowych bez uczenia rdzenia reguł specyficznych dla dostawcy |
+| 18 | `resolveReasoningOutputMode` | Wybiera natywny kontrakt wyjścia reasoning albo kontrakt oznaczony tagami | Dostawca potrzebuje oznaczonego reasoning/final output zamiast natywnych pól |
+| 19 | `prepareExtraParams` | Normalizacja parametrów żądania przed generycznymi wrapperami opcji streamingu | Dostawca potrzebuje domyślnych parametrów żądania lub porządkowania parametrów specyficznego dla dostawcy |
+| 20 | `createStreamFn` | Całkowicie zastępuje normalną ścieżkę streamingu niestandardowym transportem | Dostawca potrzebuje niestandardowego protokołu połączenia, a nie tylko wrappera |
+| 21 | `wrapStreamFn` | Wrapper streamingu po zastosowaniu generycznych wrapperów | Dostawca potrzebuje wrapperów zgodności nagłówków/treści/modeli żądania bez niestandardowego transportu |
+| 22 | `resolveTransportTurnState` | Dołącza natywne nagłówki transportu lub metadane na turę | Dostawca chce, aby generyczne transporty wysyłały natywną tożsamość tury dostawcy |
+| 23 | `resolveWebSocketSessionPolicy` | Dołącza natywne nagłówki WebSocket lub politykę schładzania sesji | Dostawca chce, aby generyczne transporty WS dostrajały nagłówki sesji lub politykę fallbacku |
+| 24 | `formatApiKey` | Formatter profilu uwierzytelniania: zapisany profil staje się ciągiem `apiKey` w runtime | Dostawca przechowuje dodatkowe metadane uwierzytelniania i potrzebuje niestandardowego kształtu tokenu runtime |
+| 25 | `refreshOAuth` | Nadpisanie odświeżania OAuth dla niestandardowych endpointów odświeżania lub polityki błędu odświeżania | Dostawca nie pasuje do współdzielonych mechanizmów odświeżania `pi-ai` |
+| 26 | `buildAuthDoctorHint` | Wskazówka naprawcza dołączana, gdy odświeżenie OAuth się nie powiedzie | Dostawca potrzebuje własnych wskazówek naprawy uwierzytelniania po nieudanym odświeżeniu |
+| 27 | `matchesContextOverflowError` | Matcher przepełnienia okna kontekstu należący do dostawcy | Dostawca ma surowe błędy przepełnienia, których generyczne heurystyki nie wykryją |
+| 28 | `classifyFailoverReason` | Klasyfikacja przyczyny failover należąca do dostawcy | Dostawca potrafi mapować surowe błędy API/transportu na rate-limit, overload itp. |
+| 29 | `isCacheTtlEligible` | Polityka prompt-cache dla dostawców proxy/backhaul | Dostawca potrzebuje bramkowania TTL cache specyficznego dla proxy |
+| 30 | `buildMissingAuthMessage` | Zamiennik generycznego komunikatu odzyskiwania po brakującym uwierzytelnianiu | Dostawca potrzebuje własnej wskazówki odzyskiwania po brakującym uwierzytelnianiu |
+| 31 | `suppressBuiltInModel` | Ukrywanie nieaktualnych modeli z upstream plus opcjonalna wskazówka błędu dla użytkownika | Dostawca musi ukryć nieaktualne wiersze z upstream lub zastąpić je wskazówką dostawcy |
+| 32 | `augmentModelCatalog` | Syntetyczne/końcowe wiersze katalogu dodawane po wykryciu | Dostawca potrzebuje syntetycznych wierszy zgodności do przodu w `models list` i selektorach |
+| 33 | `isBinaryThinking` | Przełącznik reasoning w trybie włącz/wyłącz dla dostawców binary-thinking | Dostawca udostępnia tylko binarne włączanie/wyłączanie thinking |
+| 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 odpowiada za domyślną politykę `/think` dla rodziny modeli |
+| 36 | `isModernModelRef` | Matcher nowoczesnych modeli dla filtrów live profile i wyboru smoke | Dostawca odpowiada za dopasowywanie preferowanych modeli live/smoke |
+| 37 | `prepareRuntimeAuth` | Zamienia skonfigurowane poświadczenie na rzeczywisty token/klucz runtime tuż przed wnioskowaniem | Dostawca potrzebuje wymiany tokenu lub krótkotrwałego poświadczenia żądania |
+| 38 | `resolveUsageAuth` | Rozstrzyga poświadczenia użycia/rozliczeń dla `/usage` i powiązanych powierzchni statusu | Dostawca potrzebuje niestandardowego parsowania tokenu użycia/limitu lub innego poświadczenia użycia |
+| 39 | `fetchUsageSnapshot` | Pobiera i normalizuje snapshoty użycia/limitu specyficzne dla dostawcy po rozstrzygnięciu uwierzytelniania | Dostawca potrzebuje endpointu użycia specyficznego dla dostawcy lub parsera ładunku |
+| 40 | `createEmbeddingProvider` | Tworzy adapter embeddingów należący do dostawcy dla pamięci/wyszukiwania | Zachowanie embeddingów pamięci należy do pluginu dostawcy |
+| 41 | `buildReplayPolicy` | Zwraca politykę replay kontrolującą obsługę transkryptu dla dostawcy | Dostawca potrzebuje własnej polityki transkryptu (na przykład usuwania bloków thinking) |
+| 42 | `sanitizeReplayHistory` | Przepisuje historię replay po generycznym oczyszczeniu transkryptu | Dostawca potrzebuje przepisań replay specyficznych dla dostawcy wykraczających poza współdzielone helpery kompaktowania |
+| 43 | `validateReplayTurns` | Końcowa walidacja lub przekształcenie tur replay przed embedded runnerem | Transport dostawcy potrzebuje bardziej rygorystycznej walidacji tur po generycznej sanitizacji |
+| 44 | `onModelSelected` | Uruchamia skutki uboczne po wyborze modelu należące do dostawcy | Dostawca potrzebuje telemetrii lub stanu należącego do dostawcy, gdy model staje się aktywny |
`normalizeModelId`, `normalizeTransport` i `normalizeConfig` najpierw sprawdzają
-dopasowany plugin dostawcy, a następnie przechodzą do innych pluginów dostawców zdolnych do hooków,
+dopasowany plugin dostawcy, a następnie przechodzą przez inne pluginy dostawców obsługujące hooki,
dopóki któryś faktycznie nie zmieni identyfikatora modelu albo transportu/konfiguracji. Dzięki temu
-shimy aliasów/kompatybilności providerów nadal działają bez wymagania, aby wywołujący wiedział,
-który dołączony plugin obsługuje przepisanie. Jeśli żaden hook dostawcy nie przepisze
-wspieranego wpisu konfiguracji rodziny Google, dołączony normalizator konfiguracji Google nadal
-stosuje tę poprawkę kompatybilności.
+shimy aliasów/dostawców zgodności nadal działają bez wymagania od wywołującego wiedzy,
+który bundled plugin jest właścicielem danego przepisania. Jeśli żaden hook dostawcy nie przepisze
+obsługiwanego wpisu konfiguracji z rodziny Google, bundled normalizer konfiguracji Google nadal zastosuje
+to czyszczenie zgodności.
-Jeśli dostawca potrzebuje w pełni niestandardowego protokołu wire albo niestandardowego wykonawcy żądań,
-to jest inna klasa rozszerzenia. Te hooki są przeznaczone dla zachowań dostawców,
-które nadal działają na normalnej pętli inferencyjnej OpenClaw.
+Jeśli dostawca potrzebuje całkowicie niestandardowego protokołu połączenia lub własnego wykonawcy żądań,
+to jest inna klasa rozszerzenia. Te hooki są przeznaczone dla zachowania dostawcy, które nadal
+działa w normalnej pętli wnioskowania OpenClaw.
### Przykład dostawcy
@@ -782,114 +785,111 @@ api.registerProvider({
- Anthropic używa `resolveDynamicModel`, `capabilities`, `buildAuthDoctorHint`,
`resolveUsageAuth`, `fetchUsageSnapshot`, `isCacheTtlEligible`,
`resolveDefaultThinkingLevel`, `applyConfigDefaults`, `isModernModelRef`
- i `wrapStreamFn`, ponieważ obsługuje zgodność z przyszłością Claude 4.6,
- wskazówki dla rodziny providerów, wskazówki naprawy auth, integrację
- endpointu użycia, kwalifikowalność prompt-cache, domyślne ustawienia konfiguracji zależne od auth,
- politykę domyślnego/adaptacyjnego thinking dla Claude oraz kształtowanie streamu specyficzne dla Anthropic
- dla nagłówków beta, `/fast` / `serviceTier` i `context1m`.
-- Helpery streamów specyficznych dla Claude w Anthropic pozostają na razie
- w publicznej granicy `api.ts` / `contract-api.ts` należącej do dołączonego pluginu. Ta powierzchnia
- pakietu eksportuje `wrapAnthropicProviderStream`, `resolveAnthropicBetas`,
- `resolveAnthropicFastMode`, `resolveAnthropicServiceTier` oraz niższopoziomowe
- buildery wrapperów Anthropic zamiast poszerzać ogólne SDK o reguły nagłówków beta jednego
+ i `wrapStreamFn`, ponieważ odpowiada za zgodność do przodu Claude 4.6,
+ wskazówki rodziny dostawcy, wskazówki naprawy uwierzytelniania, integrację z
+ endpointem użycia, kwalifikację prompt-cache, domyślne ustawienia konfiguracji uwzględniające uwierzytelnianie,
+ domyślną/adaptacyjną politykę thinking dla Claude oraz kształtowanie streamingu specyficzne dla Anthropic dla
+ nagłówków beta, `/fast` / `serviceTier` i `context1m`.
+- Helpery streamingu specyficzne dla Claude w Anthropic pozostają na razie we własnej
+ publicznej granicy `api.ts` / `contract-api.ts` bundled pluginu. Ta powierzchnia pakietu
+ eksportuje `wrapAnthropicProviderStream`, `resolveAnthropicBetas`,
+ `resolveAnthropicFastMode`, `resolveAnthropicServiceTier` oraz pomocnicze buildery wrapperów
+ Anthropic niższego poziomu zamiast rozszerzać generyczne SDK o reguły nagłówków beta jednego
dostawcy.
- OpenAI używa `resolveDynamicModel`, `normalizeResolvedModel` i
- `capabilities` oraz `buildMissingAuthMessage`, `suppressBuiltInModel`,
+ `capabilities`, a także `buildMissingAuthMessage`, `suppressBuiltInModel`,
`augmentModelCatalog`, `supportsXHighThinking` i `isModernModelRef`,
- ponieważ obsługuje zgodność z przyszłością GPT-5.4, bezpośrednią normalizację OpenAI
- `openai-completions` -> `openai-responses`, wskazówki auth uwzględniające Codex,
- tłumienie Spark, syntetyczne wiersze list OpenAI oraz politykę thinking /
- modeli live dla GPT-5; rodzina streamów `openai-responses-defaults` obsługuje
+ ponieważ odpowiada za zgodność do przodu GPT-5.4, bezpośrednią normalizację OpenAI
+ `openai-completions` -> `openai-responses`, wskazówki uwierzytelniania uwzględniające Codex,
+ ukrywanie Spark, syntetyczne wiersze list OpenAI oraz politykę thinking /
+ modeli live dla GPT-5; rodzina streamingu `openai-responses-defaults` odpowiada za
współdzielone natywne wrappery OpenAI Responses dla nagłówków atrybucji,
`/fast`/`serviceTier`, szczegółowości tekstu, natywnego wyszukiwania w sieci Codex,
- kształtowania ładunku reasoning-compat oraz zarządzania kontekstem Responses.
-- OpenRouter używa `catalog` oraz `resolveDynamicModel` i
- `prepareDynamicModel`, ponieważ dostawca jest pass-through i może wystawiać nowe
- identyfikatory modeli przed aktualizacją statycznego katalogu OpenClaw; używa też
- `capabilities`, `wrapStreamFn` i `isCacheTtlEligible`, aby utrzymać
- nagłówki żądań specyficzne dla dostawcy, metadane routingu, łatki reasoning i politykę prompt-cache
- poza core. Jego polityka replay pochodzi z rodziny
- `passthrough-gemini`, a rodzina streamów `openrouter-thinking` obsługuje
- wstrzykiwanie reasoning proxy oraz pomijanie nieobsługiwanych modeli i `auto`.
+ kształtowania ładunku reasoning-compat i zarządzania kontekstem Responses.
+- OpenRouter używa `catalog`, a także `resolveDynamicModel` i
+ `prepareDynamicModel`, ponieważ dostawca jest pass-through i może udostępniać nowe
+ identyfikatory modeli zanim statyczny katalog OpenClaw zostanie zaktualizowany; używa też
+ `capabilities`, `wrapStreamFn` i `isCacheTtlEligible`, aby trzymać
+ nagłówki żądań, metadane routingu, poprawki reasoning i politykę prompt-cache specyficzne dla dostawcy poza rdzeniem. Jego polityka replay pochodzi z
+ rodziny `passthrough-gemini`, a rodzina streamingu `openrouter-thinking`
+ odpowiada za wstrzykiwanie reasoning przez proxy oraz pomijanie nieobsługiwanych modeli i `auto`.
- GitHub Copilot używa `catalog`, `auth`, `resolveDynamicModel` i
- `capabilities` oraz `prepareRuntimeAuth` i `fetchUsageSnapshot`, ponieważ
- potrzebuje własnego logowania urządzenia, zachowania fallback modeli, niuansów transkryptów Claude,
- wymiany tokenu GitHub -> token Copilot oraz własnego endpointu użycia.
+ `capabilities`, a także `prepareRuntimeAuth` i `fetchUsageSnapshot`,
+ ponieważ potrzebuje należącego do dostawcy logowania urządzenia, zachowania fallbacku modeli, niuansów transkryptu Claude,
+ wymiany tokena GitHub -> token Copilot oraz należącego do dostawcy endpointu użycia.
- OpenAI Codex używa `catalog`, `resolveDynamicModel`,
- `normalizeResolvedModel`, `refreshOAuth` i `augmentModelCatalog` oraz
+ `normalizeResolvedModel`, `refreshOAuth` i `augmentModelCatalog`, a także
`prepareExtraParams`, `resolveUsageAuth` i `fetchUsageSnapshot`, ponieważ
- nadal działa na transportach OpenAI core, ale obsługuje własną normalizację transportu/base URL,
- politykę fallback odświeżania OAuth, domyślny wybór transportu,
+ nadal działa na transportach rdzenia OpenAI, ale odpowiada za normalizację
+ transportu/base URL, politykę fallbacku odświeżania OAuth, domyślny wybór transportu,
syntetyczne wiersze katalogu Codex oraz integrację z endpointem użycia ChatGPT; współdzieli
- tę samą rodzinę streamów `openai-responses-defaults` co bezpośredni OpenAI.
+ tę samą rodzinę streamingu `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` obsługuje fallback zgodności z przyszłością Gemini 3.1,
- natywną walidację replay Gemini, sanitację replay bootstrap, tagowany tryb
- reasoning-output i dopasowywanie nowoczesnych modeli, natomiast rodzina streamów
- `google-thinking` obsługuje normalizację ładunku thinking Gemini;
+ `google-gemini` odpowiada za fallback zgodności do przodu Gemini 3.1,
+ natywną walidację replay Gemini, sanitizację bootstrap replay,
+ tryb wyjścia reasoning oznaczony tagami oraz dopasowywanie nowoczesnych modeli, podczas gdy
+ rodzina streamingu `google-thinking` odpowiada za normalizację ładunku thinking Gemini;
Gemini CLI OAuth używa również `formatApiKey`, `resolveUsageAuth` i
- `fetchUsageSnapshot` do formatowania tokenu, parsowania tokenu i podłączenia
- endpointu kwot.
-- Anthropic Vertex używa `buildReplayPolicy` przez rodzinę replay
- `anthropic-by-model`, aby czyszczenie replay specyficzne dla Claude pozostawało
- ograniczone do identyfikatorów Claude zamiast każdego transportu `anthropic-messages`.
+ `fetchUsageSnapshot` do formatowania tokenów, parsowania tokenów i
+ podłączenia endpointu limitu.
+- Anthropic Vertex używa `buildReplayPolicy` poprzez
+ rodzinę replay `anthropic-by-model`, aby czyszczenie replay specyficzne dla Claude pozostało
+ ograniczone do identyfikatorów Claude zamiast obejmować każdy transport `anthropic-messages`.
- Amazon Bedrock używa `buildReplayPolicy`, `matchesContextOverflowError`,
- `classifyFailoverReason` i `resolveDefaultThinkingLevel`, ponieważ obsługuje
+ `classifyFailoverReason` i `resolveDefaultThinkingLevel`, ponieważ odpowiada za
klasyfikację błędów throttle/not-ready/context-overflow specyficzną dla Bedrock
- dla ruchu Anthropic-on-Bedrock; jego polityka replay nadal współdzieli to samo
- zabezpieczenie `anthropic-by-model` tylko dla Claude.
+ dla ruchu Anthropic-on-Bedrock; jego polityka replay nadal współdzieli tę samą
+ ochronę `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 transporty kompatybilne z OpenAI i potrzebują sanitacji
- thought-signature Gemini bez natywnej walidacji replay Gemini lub
+ poprzez rodzinę replay `passthrough-gemini`, ponieważ proxy’ują modele Gemini
+ przez transporty zgodne z OpenAI i potrzebują sanitizacji
+ 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 semantykę zarówno
- Anthropic-message, jak i kompatybilną z OpenAI; utrzymuje usuwanie bloków
- thinking tylko dla Claude po stronie Anthropic, jednocześnie nadpisując tryb reasoning
- output z powrotem na natywny, a rodzina streamów `minimax-fast-mode` obsługuje
- przepisywanie modeli fast-mode na współdzielonej ścieżce stream.
+- MiniMax używa `buildReplayPolicy` poprzez
+ rodzinę replay `hybrid-anthropic-openai`, ponieważ jeden dostawca obsługuje zarówno
+ semantykę wiadomości Anthropic, jak i zgodną z OpenAI; zachowuje usuwanie bloków
+ thinking tylko dla Claude po stronie Anthropic, jednocześnie nadpisując tryb wyjścia
+ reasoning z powrotem na natywny, a rodzina streamingu `minimax-fast-mode` odpowiada za
+ przepisywanie modeli fast-mode na współdzielonej ścieżce streamingu.
- Moonshot używa `catalog` oraz `wrapStreamFn`, ponieważ nadal korzysta ze współdzielonego
- transportu OpenAI, ale potrzebuje normalizacji ładunku thinking należącej do dostawcy; rodzina
- streamów `moonshot-thinking` mapuje konfigurację oraz stan `/think` na
- natywny binarny ładunek thinking.
+ transportu OpenAI, ale potrzebuje normalizacji ładunku thinking należącej do dostawcy; rodzina streamingu
+ `moonshot-thinking` mapuje konfigurację i stan `/think` na natywny binarny ładunek thinking.
- Kilocode używa `catalog`, `capabilities`, `wrapStreamFn` i
`isCacheTtlEligible`, ponieważ potrzebuje nagłówków żądań należących do dostawcy,
- normalizacji ładunku reasoning, wskazówek dla transkryptów Gemini oraz bramkowania
- cache-TTL dla Anthropic; rodzina streamów `kilocode-thinking` utrzymuje
- wstrzykiwanie Kilo thinking na współdzielonej ścieżce stream proxy, pomijając `kilo/auto`
- i inne identyfikatory modeli proxy, które nie wspierają jawnych ładunków reasoning.
+ normalizacji ładunku reasoning, wskazówek dla transkryptu Gemini oraz bramkowania
+ cache-TTL Anthropic; rodzina streamingu `kilocode-thinking` utrzymuje wstrzykiwanie Kilo thinking
+ na współdzielonej ścieżce streamingu proxy, jednocześnie pomijając `kilo/auto` i
+ inne identyfikatory modeli proxy, które nie obsługują jawnych ładunków reasoning.
- Z.AI używa `resolveDynamicModel`, `prepareExtraParams`, `wrapStreamFn`,
`isCacheTtlEligible`, `isBinaryThinking`, `isModernModelRef`,
- `resolveUsageAuth` i `fetchUsageSnapshot`, ponieważ obsługuje fallback GLM-5,
- domyślne `tool_stream`, UX binarnego thinking, dopasowywanie nowoczesnych modeli oraz
- zarówno auth użycia, jak i pobieranie kwot; rodzina streamów `tool-stream-default-on`
- utrzymuje wrapper `tool_stream` włączony domyślnie poza ręcznie pisanym klejem dla poszczególnych dostawców.
+ `resolveUsageAuth` i `fetchUsageSnapshot`, ponieważ odpowiada za fallback GLM-5,
+ domyślne `tool_stream`, binarne UX thinking, dopasowywanie nowoczesnych modeli oraz zarówno
+ uwierzytelnianie użycia, jak i pobieranie limitu; rodzina streamingu `tool-stream-default-on` utrzymuje
+ wrapper `tool_stream` domyślnie włączony poza ręcznie pisanym klejem dla poszczególnych dostawców.
- xAI używa `normalizeResolvedModel`, `normalizeTransport`,
`contributeResolvedModelCompat`, `prepareExtraParams`, `wrapStreamFn`,
`resolveSyntheticAuth`, `resolveDynamicModel` i `isModernModelRef`,
- ponieważ obsługuje natywną normalizację transportu xAI Responses, przepisywanie aliasów
- Grok fast-mode, domyślne `tool_stream`, porządkowanie strict-tool / reasoning-payload,
- ponowne użycie fallback auth dla narzędzi należących do pluginu, zgodne z przyszłością rozstrzyganie modeli Grok
- oraz łatki kompatybilności należące do dostawcy, takie jak profil schematu narzędzi xAI,
- nieobsługiwane słowa kluczowe schematu, natywne `web_search` i dekodowanie argumentów
- wywołań narzędzi z encji HTML.
-- Mistral, OpenCode Zen i OpenCode Go używają wyłącznie `capabilities`, aby
- utrzymać niuanse transkryptów/narzędzi poza core.
-- Dołączone providery tylko-katalogowe, takie jak `byteplus`, `cloudflare-ai-gateway`,
+ ponieważ odpowiada za normalizację natywnego transportu xAI Responses, przepisywanie aliasów
+ Grok fast-mode, domyślne `tool_stream`, czyszczenie strict-tool / ładunku reasoning,
+ ponowne użycie fallbackowego uwierzytelniania dla narzędzi należących do pluginu, rozstrzyganie modeli Grok
+ zgodne do przodu 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 encjami HTML.
+- Mistral, OpenCode Zen i OpenCode Go używają tylko `capabilities`, aby utrzymać
+ niuanse transkryptu/narzędzi poza rdzeniem.
+- Bundled dostawcy wyłącznie katalogowi, tacy jak `byteplus`, `cloudflare-ai-gateway`,
`huggingface`, `kimi-coding`, `nvidia`, `qianfan`,
`synthetic`, `together`, `venice`, `vercel-ai-gateway` i `volcengine`, używają
- wyłącznie `catalog`.
-- Qwen używa `catalog` dla swojego dostawcy tekstu oraz współdzielonych rejestracji
- media-understanding i video-generation dla swoich multimodalnych powierzchni.
+ tylko `catalog`.
+- Qwen używa `catalog` dla swojego dostawcy tekstowego 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 inferencja nadal działa przez współdzielone transporty.
+ należy do pluginu, mimo że samo wnioskowanie nadal działa przez współdzielone transporty.
## Helpery runtime
-Pluginy mogą uzyskiwać dostęp do wybranych helperów core przez `api.runtime`. Dla TTS:
+Pluginy mogą uzyskiwać dostęp do wybranych helperów rdzenia przez `api.runtime`. Dla TTS:
```ts
const clip = await api.runtime.tts.textToSpeech({
@@ -910,14 +910,14 @@ const voices = await api.runtime.tts.listVoices({
Uwagi:
-- `textToSpeech` zwraca standardowy ładunek wyjściowy TTS core dla powierzchni plików/notatek głosowych.
-- Używa konfiguracji core `messages.tts` i wyboru dostawcy.
-- Zwraca bufor audio PCM + częstotliwość próbkowania. Pluginy muszą wykonać resampling/kodowanie dla dostawców.
-- `listVoices` jest opcjonalne per dostawca. Używaj tego dla selektorów głosów lub przepływów konfiguracji należących do dostawcy.
-- Listy głosów mogą zawierać bogatsze metadane, takie jak locale, gender i tagi personality dla selektorów świadomych dostawcy.
-- OpenAI i ElevenLabs wspierają dziś telefonię. Microsoft nie.
+- `textToSpeech` zwraca standardowy ładunek wyjściowy TTS rdzenia dla powierzchni plików/notatek głosowych.
+- Używa konfiguracji rdzenia `messages.tts` i wyboru dostawcy.
+- Zwraca bufor audio PCM + częstotliwość próbkowania. Pluginy muszą przeprowadzać resampling/kodowanie dla dostawców.
+- `listVoices` jest opcjonalne dla każdego dostawcy. Używaj go dla selektorów głosów lub przepływów konfiguracji należących do dostawcy.
+- Listy głosów mogą zawierać bogatsze metadane, takie jak ustawienia regionalne, płeć i tagi osobowości dla selektorów świadomych dostawcy.
+- OpenAI i ElevenLabs obsługują dziś telefonię. Microsoft nie.
-Pluginy mogą również rejestrować dostawców mowy przez `api.registerSpeechProvider(...)`.
+Pluginy mogą też rejestrować dostawców mowy przez `api.registerSpeechProvider(...)`.
```ts
api.registerSpeechProvider({
@@ -937,15 +937,15 @@ api.registerSpeechProvider({
Uwagi:
-- Utrzymuj politykę TTS, fallback i dostarczanie odpowiedzi w core.
-- Używaj dostawców mowy dla zachowań syntezy należących do dostawcy.
-- Legacy wartość wejściowa Microsoft `edge` jest normalizowana do identyfikatora dostawcy `microsoft`.
-- Preferowany model własności jest zorientowany firmowo: jeden plugin dostawcy może obsługiwać
- tekst, mowę, obraz i przyszłych dostawców mediów, gdy OpenClaw doda ich
- kontrakty capability.
+- Utrzymuj politykę TTS, fallback i dostarczanie odpowiedzi w rdzeniu.
+- Używaj dostawców mowy do zachowania syntezy należącego do dostawcy.
+- Legacy input Microsoft `edge` jest normalizowany do identyfikatora dostawcy `microsoft`.
+- Preferowany model własności jest zorientowany na firmę: jeden plugin dostawcy może posiadać
+ tekst, mowę, obrazy i przyszłych dostawców mediów wraz z dodawaniem przez OpenClaw odpowiednich
+ kontraktów możliwości.
-Dla rozumienia obrazów/audio/wideo pluginy rejestrują jednego typowanego
-dostawcę media-understanding zamiast ogólnej torby klucz/wartość:
+W przypadku rozumienia obrazów/audio/wideo pluginy rejestrują jednego typowanego
+dostawcę media-understanding zamiast generycznego worka klucz/wartość:
```ts
api.registerMediaUnderstandingProvider({
@@ -959,14 +959,14 @@ api.registerMediaUnderstandingProvider({
Uwagi:
-- Utrzymuj orkiestrację, fallback, konfigurację i podłączenie kanałów w core.
-- Utrzymuj zachowanie dostawcy w pluginie dostawcy.
+- Zachowaj orkiestrację, fallback, konfigurację i powiązanie z kanałami 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ż podąża tym samym wzorcem:
- - core obsługuje kontrakt capability i helper runtime
+ pola wyniku, nowe opcjonalne możliwości.
+- Generowanie wideo już postępuje według tego samego wzorca:
+ - rdzeń jest właścicielem kontraktu możliwości i helpera runtime
- pluginy dostawców rejestrują `api.registerVideoGenerationProvider(...)`
- - pluginy funkcjonalne/kanałów korzystają z `api.runtime.videoGeneration.*`
+ - pluginy funkcji/kanałów korzystają z `api.runtime.videoGeneration.*`
Dla helperów runtime media-understanding pluginy mogą wywoływać:
@@ -983,7 +983,7 @@ const video = await api.runtime.mediaUnderstanding.describeVideoFile({
});
```
-Dla transkrypcji audio pluginy mogą używać albo runtime media-understanding,
+Do transkrypcji audio pluginy mogą używać albo runtime media-understanding,
albo starszego aliasu STT:
```ts
@@ -997,13 +997,13 @@ const { text } = await api.runtime.mediaUnderstanding.transcribeAudioFile({
Uwagi:
-- `api.runtime.mediaUnderstanding.*` jest preferowaną współdzieloną powierzchnią dla
+- `api.runtime.mediaUnderstanding.*` to preferowana współdzielona powierzchnia dla
rozumienia obrazów/audio/wideo.
-- Używa konfiguracji audio media-understanding core (`tools.media.audio`) oraz kolejności fallback dostawców.
-- Zwraca `{ text: undefined }`, gdy nie zostanie wygenerowany wynik transkrypcji (na przykład dla pominiętego/nieobsługiwanego wejścia).
-- `api.runtime.stt.transcribeAudioFile(...)` pozostaje aliasem kompatybilności.
+- Używa konfiguracji audio media-understanding z rdzenia (`tools.media.audio`) oraz kolejności fallbacku dostawców.
+- Zwraca `{ text: undefined }`, gdy nie zostanie wygenerowany wynik transkrypcji (na przykład przy pominiętym/nieobsługiwanym wejściu).
+- `api.runtime.stt.transcribeAudioFile(...)` pozostaje aliasem zgodności.
-Pluginy mogą również uruchamiać podrzędne przebiegi subagentów w tle przez `api.runtime.subagent`:
+Pluginy mogą także uruchamiać podagentów w tle przez `api.runtime.subagent`:
```ts
const result = await api.runtime.subagent.run({
@@ -1017,14 +1017,14 @@ const result = await api.runtime.subagent.run({
Uwagi:
-- `provider` i `model` są opcjonalnymi nadpisaniami dla pojedynczego uruchomienia, a nie trwałymi zmianami sesji.
-- OpenClaw honoruje te pola nadpisania wyłącznie dla zaufanych wywołujących.
-- Dla przebiegów fallback należących do pluginu operatorzy muszą jawnie wyrazić zgodę przez `plugins.entries..subagent.allowModelOverride: true`.
-- Użyj `plugins.entries..subagent.allowedModels`, aby ograniczyć zaufane pluginy do konkretnych kanonicznych celów `provider/model`, albo `"*"`, aby jawnie dopuścić dowolny cel.
-- Niezaufane przebiegi subagentów nadal działają, ale żądania nadpisania są odrzucane zamiast cicho przechodzić do fallback.
+- `provider` i `model` to opcjonalne nadpisania dla pojedynczego uruchomienia, a nie trwałe zmiany sesji.
+- OpenClaw honoruje te pola nadpisania tylko dla zaufanych wywołujących.
+- W przypadku uruchomień fallback należących do pluginu operatorzy muszą wyrazić zgodę przez `plugins.entries..subagent.allowModelOverride: true`.
+- Użyj `plugins.entries..subagent.allowedModels`, aby ograniczyć zaufane pluginy do określonych kanonicznych celów `provider/model`, albo `"*"` w celu jawnego dopuszczenia dowolnego celu.
+- Uruchomienia podagentów z niezaufanych pluginów nadal działają, ale żądania nadpisania są odrzucane zamiast cicho przechodzić do fallbacku.
-Dla web search pluginy mogą korzystać ze współdzielonego helpera runtime zamiast
-sięgać do podłączenia narzędzia agenta:
+W przypadku wyszukiwania w sieci pluginy mogą korzystać ze współdzielonego helpera runtime zamiast
+sięgać do logiki narzędzi agenta:
```ts
const providers = api.runtime.webSearch.listProviders({
@@ -1040,14 +1040,14 @@ const result = await api.runtime.webSearch.search({
});
```
-Pluginy mogą również rejestrować dostawców web-search przez
+Pluginy mogą też rejestrować dostawców wyszukiwania w sieci przez
`api.registerWebSearchProvider(...)`.
Uwagi:
-- Utrzymuj wybór dostawcy, rozstrzyganie poświadczeń i współdzieloną semantykę żądań w core.
-- Używaj dostawców web-search dla transportów wyszukiwania specyficznych dla dostawcy.
-- `api.runtime.webSearch.*` jest preferowaną współdzieloną powierzchnią dla pluginów funkcjonalnych/kanałów, które potrzebują zachowania wyszukiwania bez zależności od wrappera narzędzia agenta.
+- Zachowaj wybór dostawcy, rozstrzyganie poświadczeń i współdzieloną semantykę żądań w rdzeniu.
+- Używaj dostawców wyszukiwania w sieci dla transportów wyszukiwania specyficznych dla dostawcy.
+- `api.runtime.webSearch.*` to preferowana współdzielona powierzchnia dla pluginów funkcji/kanałów, które potrzebują zachowania wyszukiwania bez zależności od wrappera narzędzia agenta.
### `api.runtime.imageGeneration`
@@ -1062,12 +1062,12 @@ 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 przy użyciu 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
-Pluginy mogą wystawiać endpointy HTTP przez `api.registerHttpRoute(...)`.
+Pluginy mogą udostępniać endpointy HTTP przez `api.registerHttpRoute(...)`.
```ts
api.registerHttpRoute({
@@ -1085,31 +1085,31 @@ 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 zarządzanego przez plugin / weryfikacji webhooka.
+- `auth`: wymagane. Użyj `"gateway"`, aby wymagać zwykłego uwierzytelniania gateway, albo `"plugin"` dla uwierzytelniania/werfikacji webhooków 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.
Uwagi:
-- `api.registerHttpHandler(...)` zostało usunięte i spowoduje błąd ładowania pluginu. Używaj `api.registerHttpRoute(...)`.
+- `api.registerHttpHandler(...)` zostało usunięte i spowoduje błąd ładowania pluginu. Zamiast tego używaj `api.registerHttpRoute(...)`.
- Trasy pluginów muszą jawnie deklarować `auth`.
-- Konflikty dokładnego `path + match` są odrzucane, chyba że ustawiono `replaceExisting: true`, i jeden plugin nie może zastąpić trasy innego pluginu.
-- Nakładające się trasy z różnymi poziomami `auth` są odrzucane. Utrzymuj łańcuchy przejścia `exact`/`prefix` tylko na tym samym poziomie auth.
-- Trasy `auth: "plugin"` **nie** otrzymują automatycznie zakresów runtime operatora. Służą do webhooków / weryfikacji podpisów zarządzanych przez plugin, a nie do uprzywilejowanych wywołań helperów Gateway.
-- Trasy `auth: "gateway"` działają wewnątrz zakresu runtime żądania Gateway, ale ten zakres jest celowo zachowawczy:
- - bearer auth oparty na współdzielonym sekrecie (`gateway.auth.mode = "token"` / `"password"`) utrzymuje zakresy runtime tras pluginów przypięte do `operator.write`, nawet jeśli wywołujący wysyła `x-openclaw-scopes`
- - zaufane tryby HTTP z tożsamością (na przykład `trusted-proxy` albo `gateway.auth.mode = "none"` na prywatnym ingressie) honorują `x-openclaw-scopes` tylko wtedy, gdy nagłówek jest jawnie obecny
- - jeśli w takich żądaniach tras pluginów z tożsamością brakuje `x-openclaw-scopes`, zakres runtime wraca do `operator.write`
-- Praktyczna zasada: nie zakładaj, że trasa pluginu z auth gateway jest domyślnie powierzchnią administracyjną. Jeśli trasa wymaga zachowania tylko dla administratora, wymagaj trybu auth z tożsamością i udokumentuj jawny kontrakt nagłówka `x-openclaw-scopes`.
+- Konflikty dokładnego `path + match` są odrzucane, chyba że ustawiono `replaceExisting: true`, a jeden plugin nie może zastąpić trasy innego pluginu.
+- Nakładające się trasy z różnymi poziomami `auth` są odrzucane. Utrzymuj łańcuchy przejścia `exact`/`prefix` tylko w obrębie tego samego poziomu auth.
+- Trasy `auth: "plugin"` **nie** otrzymują automatycznie zakresów runtime operatora. Są przeznaczone do webhooków/weryfikacji podpisów zarządzanych przez plugin, a nie do uprzywilejowanych wywołań helperów Gateway.
+- Trasy `auth: "gateway"` działają w zakresie runtime żądania Gateway, ale ten zakres jest celowo konserwatywny:
+ - uwierzytelnianie bearer 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` lub `gateway.auth.mode = "none"` przy prywatnym ingressie) honorują `x-openclaw-scopes` tylko wtedy, gdy nagłówek jest jawnie obecny
+ - jeśli `x-openclaw-scopes` jest nieobecny przy takich żądaniach tras pluginów przenoszących tożsamość, zakres runtime wraca do `operator.write`
+- Praktyczna zasada: nie zakładaj, że trasa pluginu uwierzytelniana przez gateway jest domyślnie powierzchnią administracyjną. Jeśli Twoja trasa wymaga zachowania tylko dla administratora, wymagaj trybu uwierzytelniania przenoszącego tożsamość i udokumentuj jawny kontrakt nagłówka `x-openclaw-scopes`.
## Ścieżki importu Plugin SDK
-Przy tworzeniu 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/core` dla generycznego współdzielonego kontraktu skierowanego do pluginów.
+- `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`,
@@ -1122,18 +1122,19 @@ Przy tworzeniu pluginów używaj subścieżek SDK zamiast monolitycznego importu
`openclaw/plugin-sdk/channel-lifecycle`,
`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 podłączania
- konfiguracji/auth/odpowiedzi/webhooków. `channel-inbound` jest współdzielonym domem dla debounce, dopasowywania mention,
- helperów polityki mention przychodzących, formatowania kopert oraz helperów kontekstu kopert przychodzących.
+ `openclaw/plugin-sdk/secret-input` oraz
+ `openclaw/plugin-sdk/webhook-ingress` dla współdzielonej logiki konfiguracji/uwierzytelniania/odpowiedzi/webhooków.
+ `channel-inbound` jest współdzielonym miejscem dla debounce, dopasowywania wzmianek,
+ helperów polityki wzmianek przychodzących, formatowania kopert i helperów kontekstu
+ kopert przychodzących.
`channel-setup` to wąska granica konfiguracji opcjonalnej instalacji.
- `setup-runtime` to bezpieczna w runtime powierzchnia konfiguracji używana przez `setupEntry` /
- odroczony start, w tym bezpieczne importowo adaptery łatek konfiguracji.
- `setup-adapter-runtime` to granica adaptera konfiguracji kont świadoma env.
+ `setup-runtime` to bezpieczna dla runtime powierzchnia konfiguracji używana przez `setupEntry` /
+ odroczone uruchamianie, w tym adaptery poprawek konfiguracji bezpieczne dla importu.
+ `setup-adapter-runtime` to granica adaptera konfiguracji kont uwzględniającego env.
`setup-tools` to mała granica helperów CLI/archiwów/dokumentacji (`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`,
@@ -1150,189 +1151,194 @@ Przy tworzeniu pluginów używaj subścieżek SDK zamiast monolitycznego importu
`openclaw/plugin-sdk/routing`,
`openclaw/plugin-sdk/status-helpers`,
`openclaw/plugin-sdk/text-runtime`,
- `openclaw/plugin-sdk/runtime-store` i
+ `openclaw/plugin-sdk/runtime-store` oraz
`openclaw/plugin-sdk/directory-runtime` dla współdzielonych helperów runtime/konfiguracji.
- `telegram-command-config` to wąska publiczna granica dla normalizacji/walidacji niestandardowych komend Telegram
- i pozostaje dostępna nawet wtedy, gdy dołączona powierzchnia kontraktu Telegram jest tymczasowo niedostępna.
- `text-runtime` to współdzielona granica tekst/markdown/logowanie, obejmująca
- usuwanie tekstu widocznego dla asystenta, helpery renderowania/dzielenia markdown,
- helpery redakcji, helpery tagów dyrektyw i bezpieczne narzędzia tekstowe.
-- Granice kanałów specyficzne dla zatwierdzeń powinny preferować jeden kontrakt
- `approvalCapability` na pluginie. Core odczytuje wtedy auth zatwierdzeń, dostarczanie, renderowanie,
- routing natywny i leniwe zachowanie natywnych handlerów przez tę jedną capability
+ `telegram-command-config` to wąska publiczna granica dla normalizacji/walidacji niestandardowych
+ komend Telegram i pozostaje dostępna nawet wtedy, gdy bundled
+ powierzchnia kontraktu Telegram jest tymczasowo niedostępna.
+ `text-runtime` to współdzielona granica tekstu/Markdown/logowania, obejmująca
+ usuwanie tekstu widocznego dla asystenta, helpery renderowania/dzielenia Markdown, helpery redakcji,
+ helpery tagów dyrektyw oraz bezpieczne narzędzia tekstowe.
+- Powierzchnie kanałów specyficzne dla zatwierdzeń powinny preferować jeden kontrakt `approvalCapability`
+ w pluginie. Rdzeń odczytuje wtedy uwierzytelnianie, dostarczanie, renderowanie,
+ natywny routing i zachowanie leniwego natywnego handlera zatwierdzeń przez tę jedną możliwość
zamiast mieszać zachowanie zatwierdzeń z niepowiązanymi polami pluginu.
-- `openclaw/plugin-sdk/channel-runtime` jest przestarzałe i pozostaje jedynie jako
- shim kompatybilności dla starszych pluginów. Nowy kod powinien importować węższe
- ogólne prymitywy, a kod repo nie powinien dodawać nowych importów tego shima.
-- Wnętrza dołączonych rozszerzeń pozostają prywatne. Pluginy zewnętrzne powinny używać wyłącznie
- subścieżek `openclaw/plugin-sdk/*`. Kod/testy core OpenClaw mogą używać publicznych punktów wejścia repo
- pod katalogiem głównym pakietu pluginu, takich jak `index.js`, `api.js`,
- `runtime-api.js`, `setup-entry.js` oraz wąsko wyspecjalizowanych plików takich jak
- `login-qr-api.js`. Nigdy nie importuj `src/*` pakietu pluginu z core ani z innego rozszerzenia.
+- `openclaw/plugin-sdk/channel-runtime` jest przestarzałe i pozostaje tylko jako
+ shim zgodności dla starszych pluginów. Nowy kod powinien importować węższe
+ generyczne prymitywy, a kod repo nie powinien dodawać nowych importów tego shimu.
+- Wewnętrzne elementy bundled extension pozostają prywatne. Pluginy zewnętrzne powinny używać tylko
+ podścieżek `openclaw/plugin-sdk/*`. Kod rdzenia/testów OpenClaw może używać repozytoryjnych
+ publicznych punktów wejścia pod katalogiem głównym pakietu pluginu, takich jak `index.js`, `api.js`,
+ `runtime-api.js`, `setup-entry.js` i wąsko wyspecjalizowane pliki, takie 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` jest barrelem helperów/typów,
- `/runtime-api.js` jest barrelem tylko runtime,
- `/index.js` jest punktem wejścia dołączonego pluginu,
- a `/setup-entry.js` jest punktem wejścia pluginu konfiguracji.
-- Aktualne przykłady dołączonych dostawców:
- - Anthropic używa `api.js` / `contract-api.js` dla helperów strumieni Claude, takich
- jak `wrapAnthropicProviderStream`, helpery nagłówków beta i parsowanie `service_tier`.
- - OpenAI używa `api.js` dla builderów providerów, helperów modeli domyślnych i
- builderów providerów realtime.
- - OpenRouter używa `api.js` dla swojego buildera providera oraz helperów onboardingu/konfiguracji,
- podczas gdy `register.runtime.js` może nadal re-eksportować ogólne
+ `/api.js` to barrel helperów/typów,
+ `/runtime-api.js` to barrel tylko dla runtime,
+ `/index.js` to punkt wejścia bundled pluginu,
+ a `/setup-entry.js` to punkt wejścia pluginu konfiguracji.
+- Bieżące przykłady bundled dostawców:
+ - Anthropic używa `api.js` / `contract-api.js` dla helperów streamingu Claude, takich
+ jak `wrapAnthropicProviderStream`, helpery nagłówków beta oraz parsowanie `service_tier`.
+ - OpenAI używa `api.js` dla builderów dostawcy, helperów domyślnego modelu 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` może nadal reeksportować generyczne
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 następnie wracają do rozstrzygniętego pliku konfiguracji na dysku, gdy
+ gdy taki istnieje, a następnie przechodzą 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 granic helperów dołączonych kanałów oznaczonych marką kanału. Traktuj je jako
- granice utrzymaniowe/kompatybilnościowe dołączonych pluginów, a nie nowe cele importu dla stron trzecich; nowe kontrakty międzykanałowe nadal powinny trafiać do
- ogólnych subścieżek `plugin-sdk/*` albo do lokalnych barrelów `api.js` /
- `runtime-api.js` pluginu.
+- Generyczne współdzielone prymitywy pozostają preferowanym publicznym kontraktem SDK. Nadal istnieje
+ mały zastrzeżony zestaw powierzchni helperów oznaczonych markami bundled kanałów służących zgodności. Traktuj je jako powierzchnie utrzymaniowe/zgodnościowe dla bundled pluginów, a nie jako nowe cele importu dla podmiotów trzecich; nowe kontrakty międzykanałowe nadal powinny trafiać do
+ generycznych podścieżek `plugin-sdk/*` albo do lokalnych barrelów pluginu `api.js` /
+ `runtime-api.js`.
-Uwaga dotycząca kompatybilności:
+Uwaga dotycząca zgodności:
-- Dla nowego kodu unikaj głównego barrelu `openclaw/plugin-sdk`.
-- Najpierw preferuj wąskie stabilne prymitywy. Nowsze subścieżki setup/pairing/reply/
+- Unikaj rootowego barrelu `openclaw/plugin-sdk` w nowym kodzie.
+- Najpierw preferuj wąskie, stabilne prymitywy. Nowsze podścieżki setup/pairing/reply/
feedback/contract/inbound/threading/command/secret-input/webhook/infra/
- allowlist/status/message-tool są docelowym kontraktem dla nowych
- prac nad dołączonymi i zewnętrznymi pluginami.
- Parsowanie/dopasowywanie targetów należy do `openclaw/plugin-sdk/channel-targets`.
- Bramki działań wiadomości i helpery identyfikatorów wiadomości reakcji należą do
+ allowlist/status/message-tool są zamierzonym kontraktem dla nowych prac nad
+ bundled i zewnętrznymi pluginami.
+ Parsowanie/dopasowywanie celów należy do `openclaw/plugin-sdk/channel-targets`.
+ Bramki działań wiadomości i helpery message-id reakcji należą do
`openclaw/plugin-sdk/channel-actions`.
-- Barrele helperów specyficznych dla dołączonych rozszerzeń nie są domyślnie stabilne. Jeśli
- helper jest potrzebny tylko dołączonemu rozszerzeniu, trzymaj go za lokalną granicą
- `api.js` lub `runtime-api.js` rozszerzenia zamiast promować go do
+- Barrele helperów specyficznych dla bundled extension nie są domyślnie stabilne. Jeśli
+ helper jest potrzebny tylko bundled extension, trzymaj go za lokalną granicą
+ `api.js` lub `runtime-api.js` tego rozszerzenia zamiast promować go do
`openclaw/plugin-sdk/`.
-- Nowe współdzielone granice helperów powinny być ogólne, a nie oznaczone marką kanału. Współdzielone parsowanie
- targetów należy do `openclaw/plugin-sdk/channel-targets`; wnętrza specyficzne dla kanału
- pozostają za lokalną granicą `api.js` lub `runtime-api.js` należącego pluginu.
-- Subścieżki specyficzne dla capability, takie jak `image-generation`,
- `media-understanding` i `speech`, istnieją, ponieważ dołączone/natywne pluginy używają
- ich dziś. Ich obecność sama w sobie nie oznacza, że każdy eksportowany helper jest
+- Nowe współdzielone granice helperów powinny być generyczne, a nie oznaczone marką kanału. Współdzielone parsowanie celów
+ należy do `openclaw/plugin-sdk/channel-targets`; elementy wewnętrzne specyficzne dla kanału
+ pozostają za lokalną granicą `api.js` lub `runtime-api.js` należącą do danego pluginu.
+- Podścieżki specyficzne dla możliwości, takie jak `image-generation`,
+ `media-understanding` i `speech`, istnieją, ponieważ bundled/native plugins używają
+ ich już dziś. Ich obecność sama w sobie nie oznacza, że każdy eksportowany helper jest
długoterminowym zamrożonym kontraktem zewnętrznym.
## Schematy narzędzia wiadomości
-Pluginy powinny obsługiwać wkłady do schematu `describeMessageTool(...)`
-specyficzne dla kanału. Pola specyficzne dla dostawcy trzymaj w pluginie, a nie we współdzielonym core.
+Pluginy powinny być właścicielami wkładów do schematu `describeMessageTool(...)` specyficznych dla kanału.
+Pola specyficzne dla dostawcy trzymaj w pluginie, a nie we współdzielonym rdzeniu.
-Dla współdzielonych, przenośnych fragmentów schematu używaj ponownie ogólnych helperów eksportowanych przez
+W przypadku współdzielonych przenośnych fragmentów schematu ponownie używaj generycznych helperów eksportowanych przez
`openclaw/plugin-sdk/channel-actions`:
- `createMessageToolButtonsSchema()` dla ładunków w stylu siatki przycisków
- `createMessageToolCardSchema()` dla ustrukturyzowanych ładunków kart
Jeśli dany kształt schematu ma sens tylko dla jednego dostawcy, zdefiniuj go w
-kodzie źródłowym tego pluginu zamiast promować go do współdzielonego SDK.
+źródle tego pluginu zamiast promować go do współdzielonego SDK.
-## Rozstrzyganie targetów kanałów
+## Rozstrzyganie celów kanałów
-Pluginy kanałów powinny obsługiwać semantykę targetów specyficzną dla kanału. Utrzymuj
-wspólny host outbound jako ogólny i używaj powierzchni adaptera komunikacji dla reguł dostawcy:
+Pluginy kanałów powinny być właścicielami semantyki celów specyficznej dla kanału. Zachowaj współdzielony
+host outbound jako generyczny i używaj powierzchni adaptera wiadomości dla reguł dostawcy:
-- `messaging.inferTargetChatType({ to })` decyduje, czy znormalizowany target
- ma być traktowany jako `direct`, `group` czy `channel` przed wyszukaniem w katalogu.
-- `messaging.targetResolver.looksLikeId(raw, normalized)` informuje core, czy dane
- wejście powinno od razu przejść do rozstrzygania podobnego do identyfikatora zamiast do wyszukiwania w katalogu.
-- `messaging.targetResolver.resolveTarget(...)` jest fallbackiem pluginu, gdy
- core potrzebuje końcowego rozstrzygnięcia należącego do dostawcy po normalizacji albo po
- nieudanym wyszukaniu w katalogu.
-- `messaging.resolveOutboundSessionRoute(...)` obsługuje budowę trasy sesji specyficznej dla dostawcy po rozstrzygnięciu targetu.
+- `messaging.inferTargetChatType({ to })` decyduje, czy znormalizowany cel
+ powinien być traktowany jako `direct`, `group` czy `channel` przed wyszukiwaniem w katalogu.
+- `messaging.targetResolver.looksLikeId(raw, normalized)` informuje rdzeń, czy dane
+ wejście powinno przejść od razu do rozstrzygania podobnego do identyfikatora zamiast wyszukiwania w katalogu.
+- `messaging.targetResolver.resolveTarget(...)` to fallback pluginu, gdy
+ rdzeń potrzebuje końcowego rozstrzygnięcia należącego do dostawcy po normalizacji albo po
+ nieudanym wyszukiwaniu w katalogu.
+- `messaging.resolveOutboundSessionRoute(...)` odpowiada za specyficzne dla dostawcy budowanie trasy sesji
+ po rozstrzygnięciu celu.
Zalecany podział:
-- Używaj `inferTargetChatType` dla decyzji kategorialnych, które powinny zapaść przed
+- Używaj `inferTargetChatType` do decyzji kategorycznych, które powinny zapadać przed
wyszukiwaniem peerów/grup.
-- Używaj `looksLikeId` dla sprawdzeń typu „traktuj to jako jawny/natywny identyfikator targetu”.
-- Używaj `resolveTarget` jako fallbacku normalizacji specyficznego dla dostawcy, a nie do
- szerokiego wyszukiwania katalogowego.
-- Natywne identyfikatory dostawcy, takie jak chat ids, thread ids, JIDs, handles i room
- ids, trzymaj w wartościach `target` albo parametrach specyficznych dla dostawcy, a nie w ogólnych polach SDK.
+- Używaj `looksLikeId` do sprawdzeń typu „traktuj to jako jawny/natywny identyfikator celu”.
+- Używaj `resolveTarget` do fallbacku normalizacji specyficznego dla dostawcy, a nie do
+ szerokiego wyszukiwania w katalogu.
+- Natywne identyfikatory dostawcy, takie jak chat ids, thread ids, JIDs, handle i room
+ ids, trzymaj wewnątrz wartości `target` albo parametrów specyficznych dla dostawcy, a nie w generycznych polach SDK.
## Katalogi oparte na konfiguracji
-Pluginy, które wyprowadzają wpisy katalogowe z konfiguracji, powinny utrzymywać 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 używać współdzielonych helperów z
`openclaw/plugin-sdk/directory-runtime`.
Używaj tego, gdy kanał potrzebuje peerów/grup opartych na konfiguracji, takich jak:
-- peery DM oparte na allowliście
+- peery DM sterowane przez allowlist
- skonfigurowane mapy kanałów/grup
-- statyczne fallbacki katalogowe zależne od konta
+- statyczne fallbacki katalogów o zakresie konta
-Współdzielone helpery w `directory-runtime` obsługują tylko ogólne operacje:
+Współdzielone helpery w `directory-runtime` obsługują tylko operacje generyczne:
- filtrowanie zapytań
- stosowanie limitów
- helpery deduplikacji/normalizacji
- budowanie `ChannelDirectoryEntry[]`
-Inspekcja kont i normalizacja identyfikatorów specyficzna dla kanału powinna pozostać w implementacji pluginu.
+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 inferencji przez
+Pluginy dostawców mogą definiować katalogi modeli do wnioskowania za pomocą
`registerProvider({ catalog: { run(...) { ... } } })`.
`catalog.run(...)` zwraca ten sam kształt, który OpenClaw zapisuje do
`models.providers`:
- `{ provider }` dla jednego wpisu dostawcy
-- `{ providers }` dla wielu wpisów dostawców
+- `{ providers }` dla wielu wpisów dostawcy
-Używaj `catalog`, gdy plugin obsługuje identyfikatory modeli specyficzne dla dostawcy, domyślne wartości base URL
-lub metadane modeli zależne od auth.
+Używaj `catalog`, gdy plugin jest właścicielem identyfikatorów modeli specyficznych dla dostawcy, domyślnych
+wartości base URL lub metadanych modeli ograniczonych uwierzytelnianiem.
-`catalog.order` kontroluje, kiedy katalog pluginu jest scalany względem wbudowanych
-niejawnych providerów OpenClaw:
+`catalog.order` kontroluje, kiedy katalog pluginu jest scalany względem
+wbudowanych niejawnych dostawców OpenClaw:
-- `simple`: zwykli dostawcy opierający się na kluczu API lub env
-- `profile`: dostawcy pojawiający się, gdy istnieją profile auth
-- `paired`: dostawcy syntetyzujący wiele powiązanych wpisów providerów
-- `late`: ostatni przebieg, po innych niejawnych dostawcach
+- `simple`: dostawcy oparti na zwykłym kluczu API lub env
+- `profile`: dostawcy pojawiający się, gdy istnieją profile uwierzytelniania
+- `paired`: dostawcy syntetyzujący wiele powiązanych wpisów dostawcy
+- `late`: ostatnie przejście, po innych niejawnych dostawcach
-Późniejsze providery wygrywają przy kolizji kluczy, więc pluginy mogą celowo nadpisywać
-wbudowany wpis providera o tym samym identyfikatorze.
+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 legacy alias
-- jeśli zarejestrowano zarówno `catalog`, jak i `discovery`, OpenClaw używa `catalog`
+- `discovery` nadal działa jako alias legacy
+- jeśli zarejestrowane są zarówno `catalog`, jak i `discovery`, OpenClaw używa `catalog`
-## Odczytowa inspekcja kanałów
+## Inspekcja kanału tylko do odczytu
Jeśli Twój plugin rejestruje kanał, preferuj implementację
`plugin.config.inspectAccount(cfg, accountId)` obok `resolveAccount(...)`.
Dlaczego:
-- `resolveAccount(...)` jest ścieżką runtime. Może zakładać, że poświadczenia
- są w pełni zmaterializowane, i może szybko zwracać błąd, gdy brakuje wymaganych sekretów.
+- `resolveAccount(...)` to ścieżka runtime. Może zakładać, że poświadczenia
+ są w pełni zmaterializowane, i może szybko kończyć się błędem, gdy brakuje wymaganych sekretów.
- Ścieżki komend tylko do odczytu, takie jak `openclaw status`, `openclaw status --all`,
- `openclaw channels status`, `openclaw channels resolve` oraz przepływy napraw doctor/config
- nie powinny wymagać materializacji poświadczeń runtime tylko po to, by opisać konfigurację.
+ `openclaw channels status`, `openclaw channels resolve` oraz przepływy
+ naprawy doctor/config, nie powinny wymagać materializacji poświadczeń runtime tylko po to,
+ aby opisać konfigurację.
Zalecane zachowanie `inspectAccount(...)`:
- Zwracaj tylko opisowy stan konta.
- Zachowuj `enabled` i `configured`.
-- Dołączaj pola źródła/statusu poświadczeń, gdy to istotne, takie jak:
+- Dołączaj pola źródła/statusu poświadczeń, gdy ma to znaczenie, takie jak:
- `tokenSource`, `tokenStatus`
- `botTokenSource`, `botTokenStatus`
- `appTokenSource`, `appTokenStatus`
- `signingSecretSource`, `signingSecretStatus`
-- Nie musisz zwracać surowych wartości tokenów tylko po to, aby zgłaszać dostępność
- w trybie tylko do odczytu. Wystarczy zwrócić `tokenStatus: "available"` (oraz odpowiadające pole źródła).
+- Nie musisz zwracać surowych wartości tokenów tylko po to, by raportować dostępność tylko do odczytu.
+ Wystarczy zwrócić `tokenStatus: "available"` (oraz odpowiadające mu pole źródła)
+ dla komend w stylu statusu.
- Używaj `configured_unavailable`, gdy poświadczenie jest skonfigurowane przez SecretRef, ale
niedostępne w bieżącej ścieżce komendy.
-Dzięki temu komendy tylko do odczytu mogą zgłaszać „skonfigurowane, ale niedostępne w tej ścieżce komendy”
-zamiast powodować awarię albo błędnie raportować konto jako nieskonfigurowane.
+Dzięki temu komendy tylko do odczytu mogą raportować „skonfigurowane, ale niedostępne w tej ścieżce komendy”
+zamiast kończyć się awarią lub błędnie zgłaszać, że konto nie jest skonfigurowane.
-## Package packs
+## Pakiety zbiorcze
Katalog pluginu może zawierać `package.json` z `openclaw.extensions`:
@@ -1346,61 +1352,62 @@ Katalog pluginu może zawierać `package.json` z `openclaw.extensions`:
}
```
-Każdy wpis staje się pluginem. Jeśli paczka zawiera wiele rozszerzeń, identyfikator pluginu
+Każdy wpis staje się pluginem. Jeśli pakiet zbiorczy zawiera wiele rozszerzeń, identyfikator pluginu
przyjmuje postać `name/`.
Jeśli Twój plugin importuje zależności npm, zainstaluj je w tym katalogu, aby
`node_modules` było dostępne (`npm install` / `pnpm install`).
-Zabezpieczenie bezpieczeństwa: każdy wpis `openclaw.extensions` musi pozostać wewnątrz katalogu pluginu
+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 pluginu 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ą buildów `postinstall`.
+`npm install --omit=dev --ignore-scripts` (bez skryptów cyklu życia i bez zależności dev w runtime). Utrzymuj drzewa zależności pluginu jako „czyste JS/TS” i unikaj pakietów wymagających kompilacji przez `postinstall`.
-Opcjonalnie: `openclaw.setupEntry` może wskazywać lekki moduł tylko-konfiguracyjny.
+Opcjonalnie: `openclaw.setupEntry` może wskazywać lekki moduł przeznaczony 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 entry pluginu. Dzięki temu uruchamianie i konfiguracja są lżejsze,
-gdy główne entry pluginu podłącza też narzędzia, hooki lub inny kod wyłącznie runtime.
+zamiast pełnego punktu wejścia pluginu. Dzięki temu uruchamianie i konfiguracja są lżejsze,
+gdy główny punkt wejścia pluginu podłącza też narzędzia, hooki lub inny kod tylko dla runtime.
Opcjonalnie: `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen`
-pozwala pluginowi kanału skorzystać z tej samej ścieżki `setupEntry` podczas
-fazy uruchamiania gateway przed nasłuchem, nawet gdy kanał jest już skonfigurowany.
+może włączyć plugin kanału do używania tej samej ścieżki `setupEntry` w fazie
+uruchamiania gateway 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ć
-przed rozpoczęciem nasłuchiwania przez gateway. W praktyce oznacza to, że entry konfiguracji
-musi rejestrować każdą capability należącą do kanału, od której zależy start, taką jak:
+Używaj tego tylko wtedy, gdy `setupEntry` w pełni pokrywa powierzchnię uruchamiania, która musi istnieć
+przed rozpoczęciem nasłuchu przez gateway. W praktyce oznacza to, że punkt wejścia konfiguracji
+musi rejestrować każdą możliwość należącą do kanału, od której zależy uruchamianie, taką jak:
- sama rejestracja kanału
-- wszelkie trasy HTTP, które muszą być dostępne przed rozpoczęciem nasłuchiwania przez gateway
-- wszelkie metody gateway, narzędzia lub usługi, które muszą istnieć w tym samym oknie czasu
+- wszelkie trasy HTTP, które muszą być dostępne przed rozpoczęciem nasłuchu przez gateway
+- wszelkie metody Gateway, narzędzia lub usługi, które muszą istnieć w tym samym oknie czasowym
-Jeśli Twoje pełne entry nadal obsługuje jakąkolwiek wymaganą capability startową, nie włączaj
-tej flagi. Zachowaj domyślne zachowanie pluginu i pozwól OpenClaw ładować
-pełne entry podczas startu.
+Jeśli Twój pełny punkt wejścia nadal jest właścicielem jakiejkolwiek wymaganej możliwości uruchamiania, nie włączaj
+tej flagi. Pozostaw plugin przy zachowaniu domyślnym i pozwól OpenClaw ładować
+pełny punkt wejścia podczas uruchamiania.
-Dołączone kanały mogą także publikować helpery powierzchni kontraktowej tylko-konfiguracyjnej, z których core
-może korzystać przed załadowaniem pełnego runtime kanału. Aktualna powierzchnia promowania konfiguracji to:
+Bundled kanały mogą też publikować helpery powierzchni kontraktu tylko do konfiguracji, z których rdzeń
+może korzystać przed załadowaniem pełnego runtime kanału. Obecna powierzchnia
+promocji konfiguracji to:
- `singleAccountKeysToMove`
- `namedAccountPromotionKeys`
- `resolveSingleAccountPromotionTarget(...)`
-Core używa tej powierzchni, gdy musi wypromować legacy konfigurację kanału z jednym kontem do
-`channels..accounts.*` bez ładowania pełnego entry pluginu.
-Matrix jest aktualnym dołączonym przykładem: przenosi tylko klucze auth/bootstrap do
-nazwanego wypromowanego konta, gdy nazwane konta już istnieją, i może zachować
+Rdzeń używa tej powierzchni, gdy musi promować legacy konfigurację kanału z jednym kontem do
+`channels..accounts.*` bez ładowania pełnego punktu wejścia pluginu.
+Matrix jest obecnym przykładem bundled: przenosi tylko klucze uwierzytelniania/bootstrap do
+nazwanego promowanego konta, gdy istnieją już nazwane konta, 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 pluginów.
-Czas importu pozostaje niski; powierzchnia promowania jest ładowana dopiero przy pierwszym użyciu, zamiast
-ponownie wchodzić w start dołączonego kanału przy imporcie modułu.
+Te adaptery poprawek konfiguracji utrzymują leniwe wykrywanie powierzchni kontraktu bundled. Czas
+importu pozostaje niski; powierzchnia promocji jest ładowana dopiero przy pierwszym użyciu zamiast
+ponownie wchodzić w uruchamianie bundled kanału przy imporcie modułu.
-Gdy te powierzchnie startowe zawierają metody Gateway RPC, trzymaj je pod
-prefiksem specyficznym dla pluginu. Przestrzenie nazw administracyjnych core (`config.*`,
+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.
@@ -1422,7 +1429,7 @@ Przykład:
### Metadane katalogu kanałów
Pluginy kanałów mogą reklamować metadane konfiguracji/wykrywania przez `openclaw.channel` oraz
-wskazówki instalacyjne przez `openclaw.install`. Dzięki temu dane katalogu core pozostają puste.
+wskazówki instalacyjne przez `openclaw.install`. Dzięki temu podstawowe dane katalogu nie muszą być trzymane w rdzeniu.
Przykład:
@@ -1450,41 +1457,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
+- `detailLabel`: etykieta dodatkowa dla bogatszych powierzchni katalogu/statusu
- `docsLabel`: nadpisuje tekst linku do dokumentacji
- `preferOver`: identyfikatory pluginów/kanałów o niższym priorytecie, które ten wpis katalogu powinien wyprzedzać
-- `selectionDocsPrefix`, `selectionDocsOmitLabel`, `selectionExtras`: kontrolki treści dla powierzchni wyboru
-- `markdownCapable`: oznacza kanał jako obsługujący markdown dla decyzji o formatowaniu outbound
-- `exposure.configured`: ukrywa kanał z powierzchni listy skonfigurowanych kanałów po ustawieniu na `false`
-- `exposure.setup`: ukrywa kanał z interaktywnych selektorów konfiguracji/ustawiania po ustawieniu na `false`
+- `selectionDocsPrefix`, `selectionDocsOmitLabel`, `selectionExtras`: elementy sterujące kopiami na powierzchni wyboru
+- `markdownCapable`: oznacza kanał jako obsługujący Markdown dla decyzji o formatowaniu outbound
+- `exposure.configured`: ukrywa kanał z powierzchni list skonfigurowanych kanałów, gdy ustawione na `false`
+- `exposure.setup`: ukrywa kanał z interaktywnych selektorów konfiguracji, gdy ustawione na `false`
- `exposure.docs`: oznacza kanał jako wewnętrzny/prywatny dla powierzchni nawigacji dokumentacji
-- `showConfigured` / `showInSetup`: legacy aliasy nadal akceptowane ze względów kompatybilności; preferuj `exposure`
-- `quickstartAllowFrom`: włącza kanał do standardowego przepływu quickstart `allowFrom`
-- `forceAccountBinding`: wymaga jawnego powiązania konta nawet wtedy, gdy istnieje tylko jedno konto
-- `preferSessionLookupForAnnounceTarget`: preferuje wyszukiwanie sesji przy rozstrzyganiu targetów ogłoszeń
+- `showConfigured` / `showInSetup`: aliasy legacy nadal akceptowane ze względu na zgodność; preferuj `exposure`
+- `quickstartAllowFrom`: włącza kanał do standardowego przepływu szybkiego startu `allowFrom`
+- `forceAccountBinding`: wymaga jawnego powiązania konta, nawet gdy istnieje tylko jedno konto
+- `preferSessionLookupForAnnounceTarget`: preferuje wyszukiwanie sesji przy rozstrzyganiu celów ogłoszeń
-OpenClaw może także scalać **zewnętrzne katalogi kanałów** (na przykład eksport rejestru MPM).
-Umieść plik JSON w jednej z lokalizacji:
+OpenClaw może też scalać **zewnętrzne katalogi kanałów** (na przykład eksport
+rejestru MPM). Umieść plik JSON w jednej z lokalizacji:
- `~/.openclaw/mpm/plugins.json`
- `~/.openclaw/mpm/catalog.json`
- `~/.openclaw/plugins/catalog.json`
-Albo wskaż `OPENCLAW_PLUGIN_CATALOG_PATHS` (lub `OPENCLAW_MPM_CATALOG_PATHS`) na
-jeden lub więcej plików JSON (rozdzielonych przecinkiem/średnikiem/formatem `PATH`). Każdy plik powinien
-zawierać `{ "entries": [ { "name": "@scope/pkg", "openclaw": { "channel": {...}, "install": {...} } } ] }`. Parser akceptuje także `"packages"` lub `"plugins"` jako legacy aliasy klucza `"entries"`.
+Lub wskaż `OPENCLAW_PLUGIN_CATALOG_PATHS` (albo `OPENCLAW_MPM_CATALOG_PATHS`) na
+jeden lub więcej plików JSON (rozdzielanych przecinkami, średnikami albo jak w `PATH`). Każdy plik powinien
+zawierać `{ "entries": [ { "name": "@scope/pkg", "openclaw": { "channel": {...}, "install": {...} } } ] }`. Parser akceptuje również `"packages"` lub `"plugins"` jako aliasy legacy dla klucza `"entries"`.
## Pluginy silnika kontekstu
-Pluginy silnika kontekstu obsługują orkiestrację kontekstu sesji dla ingest, składania
+Pluginy silnika kontekstu są właścicielami orkiestracji 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
`plugins.slots.contextEngine`.
-Używaj tego, gdy Twój plugin musi zastąpić lub rozszerzyć domyślny pipeline kontekstu,
-a nie tylko dodać wyszukiwanie pamięci lub hooki.
+Używaj tego, gdy Twój plugin musi zastąpić lub rozszerzyć domyślny potok
+kontekstu, zamiast tylko dodać wyszukiwanie w pamięci lub hooki.
```ts
import { buildMemorySystemPromptAddition } from "openclaw/plugin-sdk/core";
@@ -1512,8 +1519,8 @@ export default function (api) {
}
```
-Jeśli Twój silnik **nie** obsługuje algorytmu kompaktowania, pozostaw `compact()`
-zaimplementowane i jawnie je deleguj:
+Jeśli Twój silnik **nie** jest właścicielem algorytmu kompaktowania, pozostaw
+zaimplementowane `compact()` i jawnie deleguj je dalej:
```ts
import {
@@ -1548,50 +1555,50 @@ export default function (api) {
}
```
-## Dodawanie nowej capability
+## Dodawanie nowej możliwości
-Gdy plugin potrzebuje zachowania, które nie mieści się w obecnym API, nie omijaj
-systemu pluginów prywatnym reach-in. Dodaj brakującą capability.
+Gdy plugin potrzebuje zachowania, które nie pasuje do bieżącego API, nie omijaj
+systemu pluginów prywatnym sięgnięciem do wnętrza. Dodaj brakującą możliwość.
Zalecana sekwencja:
-1. zdefiniuj kontrakt core
- Ustal, jakie współdzielone zachowanie powinien obsługiwać core: politykę, fallback, łączenie konfiguracji,
- cykl życia, semantykę skierowaną do kanałów i kształt helperów runtime.
-2. dodaj typowane powierzchnie rejestracji/runtime pluginu
+1. zdefiniuj kontrakt rdzenia
+ Zdecyduj, jakie współdzielone zachowanie powinien posiadać rdzeń: politykę, fallback, scalanie konfiguracji,
+ cykl życia, semantykę skierowaną do kanałów i kształt helpera runtime.
+2. dodaj typowane powierzchnie rejestracji/runtime dla 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 funkcjonalne powinny korzystać z nowej capability przez core,
- a nie importować bezpośrednio implementacji dostawcy.
+ typowaną powierzchnię możliwości.
+3. podłącz konsumentów rdzenia + 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 tej capability.
+ Pluginy dostawców rejestrują wtedy 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 z czasem pozostawały jawne.
-Tak OpenClaw zachowuje opiniotwórczość bez twardego zakodowania światopoglądu jednego
-dostawcy. Zobacz [Capability Cookbook](/pl/plugins/architecture),
-aby znaleźć konkretną listę plików i opracowany przykład.
+W ten sposób OpenClaw zachowuje opiniotwórczość, nie stając się przy tym sztywno związany z
+wizją świata jednego dostawcy. Zobacz [Capability Cookbook](/pl/plugins/architecture),
+aby znaleźć konkretną listę plików i pełny przykład.
-### Lista kontrolna capability
+### Lista kontrolna możliwości
-Gdy dodajesz nową capability, implementacja zwykle powinna dotykać tych
-powierzchni jednocześnie:
+Gdy dodajesz nową możliwość, implementacja powinna zwykle jednocześnie dotknąć tych
+powierzchni:
-- typy kontraktu core w `src//types.ts`
-- helper runner/runtime core w `src//runtime.ts`
-- powierzchnia rejestracji API pluginu w `src/plugins/types.ts`
+- typy kontraktu rdzenia w `src//types.ts`
+- helper runnera/runtime rdzenia w `src//runtime.ts`
+- powierzchnia rejestracji API pluginów w `src/plugins/types.ts`
- podłączenie rejestru pluginów w `src/plugins/registry.ts`
-- udostępnienie runtime pluginów w `src/plugins/runtime/*`, gdy pluginy funkcjonalne/kanałów
- muszą z niego korzystać
+- ekspozycja runtime pluginów w `src/plugins/runtime/*`, gdy pluginy funkcji/kanałów
+ muszą z niej korzystać
- helpery przechwytywania/testów w `src/test-utils/plugin-registration.ts`
- asercje własności/kontraktu w `src/plugins/contracts/registry.ts`
- dokumentacja operatora/pluginów w `docs/`
-Jeśli którejś z tych powierzchni brakuje, zwykle jest to znak, że capability nie jest
-jeszcze w pełni zintegrowana.
+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:
@@ -1619,7 +1626,7 @@ const clip = await api.runtime.videoGeneration.generate({
});
```
-Wzorzec testu kontraktu:
+Wzorzec testu kontraktowego:
```ts
expect(findVideoGenerationProviderIdsForPlugin("openai")).toEqual(["openai"]);
@@ -1627,7 +1634,7 @@ expect(findVideoGenerationProviderIdsForPlugin("openai")).toEqual(["openai"]);
To utrzymuje prostą zasadę:
-- core obsługuje kontrakt capability + orkiestrację
-- pluginy dostawców obsługują implementacje dostawców
-- pluginy funkcjonalne/kanałów korzystają z helperów runtime
-- testy kontraktów utrzymują jawną własność
+- rdzeń jest właścicielem kontraktu możliwości + orkiestracji
+- pluginy dostawców są właścicielami implementacji dostawców
+- pluginy funkcji/kanałów korzystają z helperów runtime
+- testy kontraktowe utrzymują jawną własność
diff --git a/docs/pl/plugins/manifest.md b/docs/pl/plugins/manifest.md
index 260b9f3ac..89cb643c5 100644
--- a/docs/pl/plugins/manifest.md
+++ b/docs/pl/plugins/manifest.md
@@ -1,14 +1,14 @@
---
read_when:
- Budujesz plugin OpenClaw
- - Musisz dostarczyć schemat konfiguracji pluginu albo debugować błędy walidacji pluginu
+ - Musisz dostarczyć schemat konfiguracji pluginu lub debugować błędy walidacji pluginu
summary: Manifest pluginu + wymagania schematu JSON (ścisła walidacja konfiguracji)
title: Manifest pluginu
x-i18n:
- generated_at: "2026-04-11T02:46:17Z"
+ generated_at: "2026-04-11T15:16:04Z"
model: gpt-5.4
provider: openai
- source_hash: 6b254c121d1eb5ea19adbd4148243cf47339c960442ab1ca0e0bfd52e0154c88
+ source_hash: 42d454b560a8f6bf714c5d782f34216be1216d83d0a319d08d7349332c91a9e4
source_path: plugins/manifest.md
workflow: 15
---
@@ -22,42 +22,49 @@ Informacje o zgodnych układach bundli znajdziesz w [Bundlach pluginów](/pl/plu
Zgodne formaty bundli używają innych plików manifestu:
- Bundel Codex: `.codex-plugin/plugin.json`
-- Bundel Claude: `.claude-plugin/plugin.json` albo domyślny układ komponentów Claude
+- Bundel Claude: `.claude-plugin/plugin.json` lub domyślny układ komponentu Claude
bez manifestu
- Bundel Cursor: `.cursor-plugin/plugin.json`
OpenClaw automatycznie wykrywa także te układy bundli, ale nie są one walidowane
względem schematu `openclaw.plugin.json` opisanego tutaj.
-Dla zgodnych bundli OpenClaw obecnie odczytuje metadane bundla oraz zadeklarowane
-katalogi główne Skills, katalogi główne poleceń Claude, domyślne ustawienia `settings.json` bundla Claude,
-domyślne ustawienia LSP bundla Claude oraz obsługiwane zestawy hooków, gdy układ odpowiada oczekiwaniom runtime OpenClaw.
+W przypadku zgodnych bundli OpenClaw obecnie odczytuje metadane bundla oraz zadeklarowane
+korzenie Skills, korzenie poleceń Claude, domyślne wartości `settings.json` bundla Claude,
+domyślne ustawienia LSP bundla Claude oraz obsługiwane zestawy hooków, gdy układ odpowiada
+oczekiwaniom środowiska uruchomieniowego OpenClaw.
-Każdy natywny plugin OpenClaw **musi** dostarczać plik `openclaw.plugin.json` w
+Każdy natywny plugin OpenClaw **musi** zawierać plik `openclaw.plugin.json` w
**katalogu głównym pluginu**. OpenClaw używa tego manifestu do walidacji konfiguracji
**bez wykonywania kodu pluginu**. Brakujące lub nieprawidłowe manifesty są traktowane jako
błędy pluginu i blokują walidację konfiguracji.
-Pełny przewodnik po systemie pluginów: [Pluginy](/pl/tools/plugin).
-Informacje o natywnym modelu możliwości i aktualnych wskazówkach dotyczących zgodności zewnętrznej:
+Zobacz pełny przewodnik po systemie pluginów: [Pluginy](/pl/tools/plugin).
+Informacje o natywnym modelu możliwości i aktualnych wskazówkach dotyczących kompatybilności zewnętrznej:
[Model możliwości](/pl/plugins/architecture#public-capability-model).
## Do czego służy ten plik
-`openclaw.plugin.json` to metadane, które OpenClaw odczytuje przed załadowaniem
-kodu pluginu.
+`openclaw.plugin.json` to metadane, które OpenClaw odczytuje przed załadowaniem kodu
+Twojego pluginu.
Używaj go do:
- tożsamości pluginu
- walidacji konfiguracji
-- metadanych uwierzytelniania i onboardingu, które powinny być dostępne bez uruchamiania runtime pluginu
+- metadanych uwierzytelniania i onboardingu, które powinny być dostępne bez uruchamiania
+ środowiska wykonawczego pluginu
+- tanich wskazówek aktywacji, które powierzchnie płaszczyzny sterowania mogą sprawdzać przed załadowaniem runtime
+- tanich deskryptorów konfiguracji, które powierzchnie konfiguracji/onboardingu mogą sprawdzać przed
+ załadowaniem runtime
- metadanych aliasów i automatycznego włączania, które powinny być rozstrzygane przed załadowaniem runtime pluginu
-- metadanych własności skrótowych rodzin modeli, które powinny automatycznie aktywować
+- skróconych metadanych własności rodzin modeli, które powinny automatycznie aktywować
plugin przed załadowaniem runtime
-- statycznych migawek własności możliwości używanych do bundlowanego okablowania zgodności i pokrycia kontraktów
-- metadanych konfiguracji specyficznych dla kanału, które powinny scalać się z powierzchniami katalogu i walidacji bez ładowania runtime
-- podpowiedzi UI dla konfiguracji
+- statycznych migawek własności możliwości używanych do zgodnego okablowania bundli i
+ pokrycia kontraktów
+- metadanych konfiguracji specyficznych dla kanału, które powinny być scalane z powierzchniami katalogu i walidacji
+ bez ładowania runtime
+- wskazówek UI konfiguracji
Nie używaj go do:
@@ -65,7 +72,7 @@ Nie używaj go do:
- deklarowania punktów wejścia kodu
- metadanych instalacji npm
-To należy do kodu pluginu i `package.json`.
+Te elementy należą do kodu Twojego pluginu i `package.json`.
## Minimalny przykład
@@ -142,55 +149,57 @@ To należy do kodu pluginu i `package.json`.
| ----------------------------------- | -------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `id` | Tak | `string` | Kanoniczny identyfikator pluginu. To identyfikator używany w `plugins.entries.`. |
| `configSchema` | Tak | `object` | Wbudowany schemat JSON dla konfiguracji tego pluginu. |
-| `enabledByDefault` | Nie | `true` | Oznacza bundlowany plugin jako domyślnie włączony. Pomiń to pole albo ustaw dowolną wartość inną niż `true`, aby pozostawić plugin domyślnie wyłączony. |
-| `legacyPluginIds` | Nie | `string[]` | Starsze identyfikatory, które są normalizowane do tego kanonicznego identyfikatora pluginu. |
-| `autoEnableWhenConfiguredProviders` | Nie | `string[]` | Identyfikatory dostawców, które powinny automatycznie włączać ten plugin, gdy uwierzytelnianie, konfiguracja lub odwołania do modeli o nich wspominają. |
+| `enabledByDefault` | Nie | `true` | Oznacza plugin bundlowany jako domyślnie włączony. Pomiń to pole lub ustaw dowolną wartość inną niż `true`, aby pozostawić plugin domyślnie wyłączony. |
+| `legacyPluginIds` | Nie | `string[]` | Starsze identyfikatory normalizowane do tego kanonicznego identyfikatora pluginu. |
+| `autoEnableWhenConfiguredProviders` | Nie | `string[]` | Identyfikatory dostawców, które powinny automatycznie włączać ten plugin, gdy uwierzytelnianie, konfiguracja lub odwołania do modeli je wskazują. |
| `kind` | Nie | `"memory"` \| `"context-engine"` | Deklaruje wyłączny rodzaj pluginu używany przez `plugins.slots.*`. |
| `channels` | Nie | `string[]` | Identyfikatory kanałów należących do tego pluginu. Używane do wykrywania i walidacji konfiguracji. |
-| `providers` | Nie | `string[]` | Identyfikatory dostawców należących do tego pluginu. |
-| `modelSupport` | Nie | `object` | Należące do manifestu skrótowe metadane rodzin modeli używane do automatycznego załadowania pluginu przed runtime. |
-| `cliBackends` | Nie | `string[]` | Identyfikatory backendów inferencji CLI należących do tego pluginu. Używane do automatycznej aktywacji przy uruchamianiu na podstawie jawnych odwołań w konfiguracji. |
-| `commandAliases` | Nie | `object[]` | Nazwy poleceń należące do tego pluginu, które powinny generować diagnostykę konfiguracji i CLI uwzględniającą plugin przed załadowaniem runtime. |
-| `providerAuthEnvVars` | Nie | `Record` | Lekkie metadane env uwierzytelniania dostawcy, które OpenClaw może sprawdzać bez ładowania kodu pluginu. |
-| `providerAuthAliases` | Nie | `Record` | Identyfikatory dostawców, które powinny używać ponownie innego identyfikatora dostawcy do wyszukiwania uwierzytelniania, na przykład dostawca do kodowania, który współdzieli klucz API i profile uwierzytelniania dostawcy bazowego. |
-| `channelEnvVars` | Nie | `Record` | Lekkie metadane env kanału, które OpenClaw może sprawdzać bez ładowania kodu pluginu. Używaj tego dla konfiguracji kanału sterowanej env lub powierzchni uwierzytelniania, które powinny być widoczne dla ogólnych pomocników uruchamiania/konfiguracji. |
-| `providerAuthChoices` | Nie | `object[]` | Lekkie metadane wyboru uwierzytelniania dla selektorów onboardingu, rozstrzygania preferowanego dostawcy i prostego mapowania flag CLI. |
-| `contracts` | Nie | `object` | Statyczna migawka bundlowanych możliwości dla speech, realtime transcription, realtime voice, media-understanding, image-generation, music-generation, video-generation, web-fetch, web search i własności narzędzi. |
-| `channelConfigs` | Nie | `Record` | Należące do manifestu metadane konfiguracji kanału scalane z powierzchniami wykrywania i walidacji przed załadowaniem runtime. |
+| `providers` | Nie | `string[]` | Identyfikatory dostawców należących do tego pluginu. |
+| `modelSupport` | Nie | `object` | Skrócone metadane rodzin modeli należące do manifestu, używane do automatycznego załadowania pluginu przed runtime. |
+| `cliBackends` | Nie | `string[]` | Identyfikatory backendów inferencji CLI należących do tego pluginu. Używane do automatycznej aktywacji przy uruchomieniu na podstawie jawnych odwołań w konfiguracji. |
+| `commandAliases` | Nie | `object[]` | Nazwy poleceń należące do tego pluginu, które powinny generować diagnostykę konfiguracji i CLI świadomą pluginu przed załadowaniem runtime. |
+| `providerAuthEnvVars` | Nie | `Record` | Lekkie metadane zmiennych środowiskowych uwierzytelniania dostawcy, które OpenClaw może sprawdzać bez ładowania kodu pluginu. |
+| `providerAuthAliases` | Nie | `Record` | Identyfikatory dostawców, które powinny ponownie używać innego identyfikatora dostawcy do wyszukiwania uwierzytelniania, na przykład dostawca do kodowania współdzielący bazowy klucz API i profile auth. |
+| `channelEnvVars` | Nie | `Record` | Lekkie metadane zmiennych środowiskowych kanału, które OpenClaw może sprawdzać bez ładowania kodu pluginu. Używaj tego do konfiguracji kanału sterowanej env lub powierzchni auth, które powinny widzieć ogólne pomocniki uruchamiania/konfiguracji. |
+| `providerAuthChoices` | Nie | `object[]` | Lekkie metadane wyboru uwierzytelniania dla selektorów onboardingu, rozpoznawania preferowanego dostawcy i prostego mapowania flag CLI. |
+| `activation` | Nie | `object` | Lekkie wskazówki aktywacji dla ładowania wyzwalanego przez dostawcę, polecenie, kanał, trasę i możliwości. To tylko metadane; rzeczywiste zachowanie nadal należy do runtime pluginu. |
+| `setup` | Nie | `object` | Lekkie deskryptory konfiguracji/onboardingu, które powierzchnie wykrywania i konfiguracji mogą sprawdzać bez ładowania runtime pluginu. |
+| `contracts` | Nie | `object` | Statyczna migawka możliwości bundlowanych dla własności mowy, transkrypcji w czasie rzeczywistym, głosu w czasie rzeczywistym, rozumienia multimediów, generowania obrazów, generowania muzyki, generowania wideo, pobierania z sieci, wyszukiwania w sieci i własności narzędzi. |
+| `channelConfigs` | Nie | `Record` | Metadane konfiguracji kanału należące do manifestu, scalane z powierzchniami wykrywania i walidacji przed załadowaniem runtime. |
| `skills` | Nie | `string[]` | Katalogi Skills do załadowania, względne względem katalogu głównego pluginu. |
| `name` | Nie | `string` | Czytelna dla człowieka nazwa pluginu. |
| `description` | Nie | `string` | Krótkie podsumowanie wyświetlane na powierzchniach pluginu. |
| `version` | Nie | `string` | Informacyjna wersja pluginu. |
-| `uiHints` | Nie | `Record` | Etykiety UI, placeholdery i wskazówki dotyczące wrażliwości dla pól konfiguracji. |
+| `uiHints` | Nie | `Record` | Etykiety UI, placeholdery i wskazówki dotyczące wrażliwości dla pól konfiguracji. |
## Odniesienie do `providerAuthChoices`
Każdy wpis `providerAuthChoices` opisuje jeden wybór onboardingu lub uwierzytelniania.
OpenClaw odczytuje to przed załadowaniem runtime dostawcy.
-| Pole | Wymagane | Typ | Co oznacza |
-| --------------------- | -------- | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
-| `provider` | Tak | `string` | Identyfikator dostawcy, do którego należy ten wybór. |
-| `method` | Tak | `string` | Identyfikator metody uwierzytelniania, do której należy przekierować. |
-| `choiceId` | Tak | `string` | Stabilny identyfikator wyboru uwierzytelniania używany przez onboarding i przepływy CLI. |
-| `choiceLabel` | Nie | `string` | Etykieta widoczna dla użytkownika. Jeśli zostanie pominięta, OpenClaw użyje `choiceId`. |
-| `choiceHint` | Nie | `string` | Krótki tekst pomocniczy dla selektora. |
-| `assistantPriority` | Nie | `number` | Niższe wartości są sortowane wcześniej w interaktywnych selektorach sterowanych przez asystenta. |
-| `assistantVisibility` | Nie | `"visible"` \| `"manual-only"` | Ukrywa wybór przed selektorami asystenta, nadal pozwalając na ręczny wybór w CLI. |
-| `deprecatedChoiceIds` | Nie | `string[]` | Starsze identyfikatory wyboru, które powinny przekierowywać użytkowników do tego zamiennego wyboru. |
+| Pole | Wymagane | Typ | Co oznacza |
+| --------------------- | -------- | ----------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
+| `provider` | Tak | `string` | Identyfikator dostawcy, do którego należy ten wybór. |
+| `method` | Tak | `string` | Identyfikator metody uwierzytelniania, do której należy przekierować. |
+| `choiceId` | Tak | `string` | Stabilny identyfikator wyboru uwierzytelniania używany przez onboarding i przepływy CLI. |
+| `choiceLabel` | Nie | `string` | Etykieta widoczna dla użytkownika. Jeśli zostanie pominięta, OpenClaw użyje `choiceId`. |
+| `choiceHint` | Nie | `string` | Krótki tekst pomocniczy dla selektora. |
+| `assistantPriority` | Nie | `number` | Niższe wartości są sortowane wcześniej w interaktywnych selektorach sterowanych przez asystenta. |
+| `assistantVisibility` | Nie | `"visible"` \| `"manual-only"` | Ukrywa wybór w selektorach asystenta, nadal pozwalając na ręczny wybór w CLI. |
+| `deprecatedChoiceIds` | Nie | `string[]` | Starsze identyfikatory wyboru, które powinny przekierowywać użytkowników do tego zastępczego wyboru. |
| `groupId` | Nie | `string` | Opcjonalny identyfikator grupy do grupowania powiązanych wyborów. |
-| `groupLabel` | Nie | `string` | Etykieta tej grupy widoczna dla użytkownika. |
-| `groupHint` | Nie | `string` | Krótki tekst pomocniczy dla grupy. |
-| `optionKey` | Nie | `string` | Wewnętrzny klucz opcji dla prostych przepływów uwierzytelniania jedną flagą. |
-| `cliFlag` | Nie | `string` | Nazwa flagi CLI, na przykład `--openrouter-api-key`. |
-| `cliOption` | Nie | `string` | Pełna postać opcji CLI, na przykład `--openrouter-api-key `. |
-| `cliDescription` | Nie | `string` | Opis używany w pomocy CLI. |
+| `groupLabel` | Nie | `string` | Etykieta tej grupy widoczna dla użytkownika. |
+| `groupHint` | Nie | `string` | Krótki tekst pomocniczy dla grupy. |
+| `optionKey` | Nie | `string` | Wewnętrzny klucz opcji dla prostych przepływów auth z jedną flagą. |
+| `cliFlag` | Nie | `string` | Nazwa flagi CLI, na przykład `--openrouter-api-key`. |
+| `cliOption` | Nie | `string` | Pełna postać opcji CLI, na przykład `--openrouter-api-key `. |
+| `cliDescription` | Nie | `string` | Opis używany w pomocy CLI. |
| `onboardingScopes` | Nie | `Array<"text-inference" \| "image-generation">` | Na których powierzchniach onboardingu ten wybór powinien się pojawiać. Jeśli zostanie pominięte, domyślnie używane jest `["text-inference"]`. |
## Odniesienie do `commandAliases`
-Używaj `commandAliases`, gdy plugin posiada nazwę polecenia runtime, którą użytkownicy mogą
-omyłkowo umieścić w `plugins.allow` albo próbować uruchomić jako główne polecenie CLI. OpenClaw
+Używaj `commandAliases`, gdy plugin jest właścicielem nazwy polecenia runtime, którą użytkownicy mogą
+omyłkowo umieścić w `plugins.allow` lub próbować uruchomić jako główne polecenie CLI. OpenClaw
używa tych metadanych do diagnostyki bez importowania kodu runtime pluginu.
```json
@@ -205,22 +214,93 @@ używa tych metadanych do diagnostyki bez importowania kodu runtime pluginu.
}
```
-| Pole | Wymagane | Typ | Co oznacza |
-| ------------ | -------- | ----------------- | ---------------------------------------------------------------------------- |
-| `name` | Tak | `string` | Nazwa polecenia należąca do tego pluginu. |
-| `kind` | Nie | `"runtime-slash"` | Oznacza alias jako polecenie ukośnikowe czatu, a nie główne polecenie CLI. |
-| `cliCommand` | Nie | `string` | Powiązane główne polecenie CLI do zasugerowania przy operacjach CLI, jeśli istnieje. |
+| Pole | Wymagane | Typ | Co oznacza |
+| ------------ | -------- | ----------------- | -------------------------------------------------------------------------- |
+| `name` | Tak | `string` | Nazwa polecenia należącego do tego pluginu. |
+| `kind` | Nie | `"runtime-slash"` | Oznacza alias jako polecenie slash czatu, a nie główne polecenie CLI. |
+| `cliCommand` | Nie | `string` | Powiązane główne polecenie CLI, które można zasugerować dla operacji CLI, jeśli istnieje. |
+
+## Odniesienie do `activation`
+
+Używaj `activation`, gdy plugin może w prosty sposób zadeklarować, które zdarzenia płaszczyzny sterowania
+powinny później go aktywować.
+
+Ten blok zawiera wyłącznie metadane. Nie rejestruje zachowania runtime i nie
+zastępuje `register(...)`, `setupEntry` ani innych punktów wejścia runtime/pluginu.
+
+```json
+{
+ "activation": {
+ "onProviders": ["openai"],
+ "onCommands": ["models"],
+ "onChannels": ["web"],
+ "onRoutes": ["gateway-webhook"],
+ "onCapabilities": ["provider", "tool"]
+ }
+}
+```
+
+| Pole | Wymagane | Typ | Co oznacza |
+| ---------------- | -------- | ---------------------------------------------------- | ------------------------------------------------------------------- |
+| `onProviders` | Nie | `string[]` | Identyfikatory dostawców, które powinny aktywować ten plugin po żądaniu. |
+| `onCommands` | Nie | `string[]` | Identyfikatory poleceń, które powinny aktywować ten plugin. |
+| `onChannels` | Nie | `string[]` | Identyfikatory kanałów, które powinny aktywować ten plugin. |
+| `onRoutes` | Nie | `string[]` | Rodzaje tras, które powinny aktywować ten plugin. |
+| `onCapabilities` | Nie | `Array<"provider" \| "channel" \| "tool" \| "hook">` | Ogólne wskazówki dotyczące możliwości używane przez planowanie aktywacji płaszczyzny sterowania. |
+
+## Odniesienie do `setup`
+
+Używaj `setup`, gdy powierzchnie konfiguracji i onboardingu potrzebują lekkich metadanych należących do pluginu
+przed załadowaniem runtime.
+
+```json
+{
+ "setup": {
+ "providers": [
+ {
+ "id": "openai",
+ "authMethods": ["api-key"],
+ "envVars": ["OPENAI_API_KEY"]
+ }
+ ],
+ "cliBackends": ["openai-cli"],
+ "configMigrations": ["legacy-openai-auth"],
+ "requiresRuntime": false
+ }
+}
+```
+
+Pole najwyższego poziomu `cliBackends` pozostaje prawidłowe i nadal opisuje backendy inferencji CLI.
+`setup.cliBackends` to powierzchnia deskryptorów specyficzna dla konfiguracji dla
+przepływów płaszczyzny sterowania/konfiguracji, która powinna pozostać wyłącznie metadanymi.
+
+### Odniesienie do `setup.providers`
+
+| Pole | Wymagane | Typ | Co oznacza |
+| ------------- | -------- | ---------- | ----------------------------------------------------------------------------------------- |
+| `id` | Tak | `string` | Identyfikator dostawcy udostępniany podczas konfiguracji lub onboardingu. |
+| `authMethods` | Nie | `string[]` | Identyfikatory metod konfiguracji/auth, które ten dostawca obsługuje bez ładowania pełnego runtime. |
+| `envVars` | Nie | `string[]` | Zmienne środowiskowe, które ogólne powierzchnie konfiguracji/statusu mogą sprawdzać przed załadowaniem runtime pluginu. |
+
+### Pola `setup`
+
+| Pole | Wymagane | Typ | Co oznacza |
+| ------------------ | -------- | ---------- | ----------------------------------------------------------------------------- |
+| `providers` | Nie | `object[]` | Deskryptory konfiguracji dostawców udostępniane podczas konfiguracji i onboardingu. |
+| `cliBackends` | Nie | `string[]` | Identyfikatory backendów dostępnych podczas konfiguracji bez pełnej aktywacji runtime. |
+| `configMigrations` | Nie | `string[]` | Identyfikatory migracji konfiguracji należące do powierzchni konfiguracji tego pluginu. |
+| `requiresRuntime` | Nie | `boolean` | Czy konfiguracja nadal wymaga wykonania runtime pluginu po wyszukaniu deskryptora. |
## Odniesienie do `uiHints`
-`uiHints` to mapa od nazw pól konfiguracji do małych wskazówek renderowania.
+`uiHints` to mapa od nazw pól konfiguracji do niewielkich wskazówek renderowania.
```json
{
"uiHints": {
"apiKey": {
- "label": "Klucz API",
- "help": "Używany do żądań OpenRouter",
+ "label": "API key",
+ "help": "Used for OpenRouter requests",
"placeholder": "sk-or-v1-...",
"sensitive": true
}
@@ -237,11 +317,11 @@ Każda wskazówka pola może zawierać:
| `tags` | `string[]` | Opcjonalne tagi UI. |
| `advanced` | `boolean` | Oznacza pole jako zaawansowane. |
| `sensitive` | `boolean` | Oznacza pole jako sekretne lub wrażliwe. |
-| `placeholder` | `string` | Tekst zastępczy dla pól formularza. |
+| `placeholder` | `string` | Tekst placeholdera dla pól formularza. |
## Odniesienie do `contracts`
-Używaj `contracts` tylko dla statycznych metadanych własności możliwości, które OpenClaw może
+Używaj `contracts` wyłącznie do statycznych metadanych własności możliwości, które OpenClaw może
odczytać bez importowania runtime pluginu.
```json
@@ -262,17 +342,17 @@ odczytać bez importowania runtime pluginu.
Każda lista jest opcjonalna:
-| Pole | Typ | Co oznacza |
-| -------------------------------- | ---------- | ----------------------------------------------------------- |
-| `speechProviders` | `string[]` | Identyfikatory dostawców speech należące do tego pluginu. |
-| `realtimeTranscriptionProviders` | `string[]` | Identyfikatory dostawców realtime-transcription należące do tego pluginu. |
-| `realtimeVoiceProviders` | `string[]` | Identyfikatory dostawców realtime voice należące do tego pluginu. |
-| `mediaUnderstandingProviders` | `string[]` | Identyfikatory dostawców media-understanding należące do tego pluginu. |
-| `imageGenerationProviders` | `string[]` | Identyfikatory dostawców image-generation należące do tego pluginu. |
-| `videoGenerationProviders` | `string[]` | Identyfikatory dostawców video-generation należące do tego pluginu. |
-| `webFetchProviders` | `string[]` | Identyfikatory dostawców web-fetch należące do tego pluginu. |
-| `webSearchProviders` | `string[]` | Identyfikatory dostawców web search należące do tego pluginu. |
-| `tools` | `string[]` | Nazwy narzędzi agenta należące do tego pluginu dla bundlowanych kontroli kontraktów. |
+| Pole | Typ | Co oznacza |
+| -------------------------------- | ---------- | --------------------------------------------------------------- |
+| `speechProviders` | `string[]` | Identyfikatory dostawców mowy należące do tego pluginu. |
+| `realtimeTranscriptionProviders` | `string[]` | Identyfikatory dostawców transkrypcji w czasie rzeczywistym należące do tego pluginu. |
+| `realtimeVoiceProviders` | `string[]` | Identyfikatory dostawców głosu w czasie rzeczywistym należące do tego pluginu. |
+| `mediaUnderstandingProviders` | `string[]` | Identyfikatory dostawców rozumienia multimediów należące do tego pluginu. |
+| `imageGenerationProviders` | `string[]` | Identyfikatory dostawców generowania obrazów należące do tego pluginu. |
+| `videoGenerationProviders` | `string[]` | Identyfikatory dostawców generowania wideo należące do tego pluginu. |
+| `webFetchProviders` | `string[]` | Identyfikatory dostawców pobierania z sieci należące do tego pluginu. |
+| `webSearchProviders` | `string[]` | Identyfikatory dostawców wyszukiwania w sieci należące do tego pluginu. |
+| `tools` | `string[]` | Nazwy narzędzi agenta należące do tego pluginu na potrzeby sprawdzania kontraktów bundlowanych. |
## Odniesienie do `channelConfigs`
@@ -292,7 +372,7 @@ załadowaniem runtime.
},
"uiHints": {
"homeserverUrl": {
- "label": "URL homeservera",
+ "label": "Homeserver URL",
"placeholder": "https://matrix.example.com"
}
},
@@ -306,18 +386,19 @@ załadowaniem runtime.
Każdy wpis kanału może zawierać:
-| Pole | Typ | Co oznacza |
-| ------------- | ------------------------ | ------------------------------------------------------------------------------------------ |
+| Pole | Typ | Co oznacza |
+| ------------- | ------------------------ | --------------------------------------------------------------------------------------------- |
| `schema` | `object` | Schemat JSON dla `channels.`. Wymagany dla każdego zadeklarowanego wpisu konfiguracji kanału. |
-| `uiHints` | `Record` | Opcjonalne etykiety UI/placeholdery/wskazówki wrażliwości dla tej sekcji konfiguracji kanału. |
-| `label` | `string` | Etykieta kanału scalana z powierzchniami selektora i inspekcji, gdy metadane runtime nie są gotowe. |
-| `description` | `string` | Krótki opis kanału dla powierzchni inspekcji i katalogu. |
+| `uiHints` | `Record` | Opcjonalne etykiety UI/placeholdery/wskazówki dotyczące wrażliwości dla tej sekcji konfiguracji kanału. |
+| `label` | `string` | Etykieta kanału scalana z powierzchniami wyboru i inspekcji, gdy metadane runtime nie są jeszcze gotowe. |
+| `description` | `string` | Krótki opis kanału dla powierzchni inspekcji i katalogu. |
| `preferOver` | `string[]` | Starsze lub mniej priorytetowe identyfikatory pluginów, które ten kanał powinien wyprzedzać na powierzchniach wyboru. |
## Odniesienie do `modelSupport`
-Używaj `modelSupport`, gdy OpenClaw powinien wnioskować o Twoim pluginie dostawcy na podstawie
-skrótowych identyfikatorów modeli takich jak `gpt-5.4` lub `claude-sonnet-4.6` przed załadowaniem runtime pluginu.
+Używaj `modelSupport`, gdy OpenClaw ma wywnioskować plugin Twojego dostawcy na podstawie
+skróconych identyfikatorów modeli, takich jak `gpt-5.4` lub `claude-sonnet-4.6`, zanim runtime pluginu
+zostanie załadowane.
```json
{
@@ -332,73 +413,70 @@ OpenClaw stosuje następujący priorytet:
- jawne odwołania `provider/model` używają należących do właściciela metadanych manifestu `providers`
- `modelPatterns` mają pierwszeństwo przed `modelPrefixes`
-- jeśli pasuje jednocześnie jeden plugin niebundlowany i jeden bundlowany,
- wygrywa plugin niebundlowany
-- pozostała niejednoznaczność jest ignorowana, dopóki użytkownik lub konfiguracja nie określi dostawcy
+- jeśli pasują jednocześnie jeden plugin niebundlowany i jeden plugin bundlowany, wygrywa plugin niebundlowany
+- pozostała niejednoznaczność jest ignorowana, dopóki użytkownik lub konfiguracja nie określą dostawcy
Pola:
-| Pole | Typ | Co oznacza |
-| --------------- | ---------- | ----------------------------------------------------------------------------- |
-| `modelPrefixes` | `string[]` | Prefiksy dopasowywane przez `startsWith` do skrótowych identyfikatorów modeli. |
-| `modelPatterns` | `string[]` | Źródła regex dopasowywane do skrótowych identyfikatorów modeli po usunięciu sufiksu profilu. |
+| Pole | Typ | Co oznacza |
+| --------------- | ---------- | --------------------------------------------------------------------------------- |
+| `modelPrefixes` | `string[]` | Prefiksy dopasowywane przez `startsWith` do skróconych identyfikatorów modeli. |
+| `modelPatterns` | `string[]` | Źródła regex dopasowywane do skróconych identyfikatorów modeli po usunięciu sufiksu profilu. |
Starsze klucze możliwości na najwyższym poziomie są przestarzałe. Użyj `openclaw doctor --fix`, aby
przenieść `speechProviders`, `realtimeTranscriptionProviders`,
`realtimeVoiceProviders`, `mediaUnderstandingProviders`,
`imageGenerationProviders`, `videoGenerationProviders`,
-`webFetchProviders` i `webSearchProviders` do `contracts`; zwykłe
+`webFetchProviders` i `webSearchProviders` pod `contracts`; zwykłe
ładowanie manifestu nie traktuje już tych pól najwyższego poziomu jako
własności możliwości.
## Manifest a package.json
-Te dwa pliki pełnią różne role:
+Te dwa pliki służą do różnych zadań:
-| Plik | Używaj go do |
-| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
-| `openclaw.plugin.json` | Wykrywania, walidacji konfiguracji, metadanych wyboru uwierzytelniania i wskazówek UI, które muszą istnieć przed uruchomieniem kodu pluginu |
-| `package.json` | Metadanych npm, instalacji zależności oraz bloku `openclaw` używanego dla punktów wejścia, blokowania instalacji, konfiguracji lub metadanych katalogu |
+| Plik | Używaj go do |
+| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
+| `openclaw.plugin.json` | Wykrywania, walidacji konfiguracji, metadanych wyboru auth i wskazówek UI, które muszą istnieć przed uruchomieniem kodu pluginu |
+| `package.json` | Metadanych npm, instalacji zależności i bloku `openclaw` używanego do punktów wejścia, ograniczeń instalacji, konfiguracji lub metadanych katalogu |
-Jeśli nie masz pewności, gdzie powinien trafić dany element metadanych, użyj tej zasady:
+Jeśli nie masz pewności, gdzie powinien znaleźć się dany fragment metadanych, użyj tej zasady:
- jeśli OpenClaw musi znać go przed załadowaniem kodu pluginu, umieść go w `openclaw.plugin.json`
- jeśli dotyczy pakowania, plików wejściowych lub zachowania instalacji npm, umieść go w `package.json`
### Pola `package.json`, które wpływają na wykrywanie
-Niektóre metadane pluginu sprzed uruchomienia celowo znajdują się w `package.json` w bloku
-`openclaw`, a nie w `openclaw.plugin.json`.
+Niektóre metadane pluginu sprzed uruchomienia runtime celowo znajdują się w `package.json` pod
+blokiem `openclaw`, a nie w `openclaw.plugin.json`.
Ważne przykłady:
| Pole | Co oznacza |
| ----------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `openclaw.extensions` | Deklaruje natywne punkty wejścia pluginu. |
-| `openclaw.setupEntry` | Lekki punkt wejścia tylko do konfiguracji używany podczas onboardingu i odroczonego uruchamiania kanału. |
-| `openclaw.channel` | Lekkie metadane katalogu kanałów, takie jak etykiety, ścieżki dokumentacji, aliasy i teksty wyboru. |
-| `openclaw.channel.configuredState` | Lekkie metadane sprawdzania stanu konfiguracji, które mogą odpowiedzieć na pytanie „czy konfiguracja tylko przez env już istnieje?” bez ładowania pełnego runtime kanału. |
-| `openclaw.channel.persistedAuthState` | Lekkie metadane sprawdzania trwałego stanu uwierzytelnienia, które mogą odpowiedzieć na pytanie „czy coś jest już zalogowane?” bez ładowania pełnego runtime kanału. |
-| `openclaw.install.npmSpec` / `openclaw.install.localPath` | Wskazówki instalacji/aktualizacji dla pluginów bundlowanych i publikowanych zewnętrznie. |
-| `openclaw.install.defaultChoice` | Preferowana ścieżka instalacji, gdy dostępnych jest wiele źródeł instalacji. |
-| `openclaw.install.minHostVersion` | Minimalna obsługiwana wersja hosta OpenClaw, używająca dolnej granicy semver, takiej jak `>=2026.3.22`. |
-| `openclaw.install.allowInvalidConfigRecovery` | Pozwala na wąską ścieżkę odzyskiwania przez ponowną instalację bundlowanego pluginu, gdy konfiguracja jest nieprawidłowa. |
-| `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` | Pozwala ładować powierzchnie kanału tylko do konfiguracji przed pełnym pluginem kanału podczas uruchamiania. |
+| `openclaw.setupEntry` | Lekki punkt wejścia wyłącznie do konfiguracji używany podczas onboardingu i odroczonego uruchamiania kanału. |
+| `openclaw.channel` | Lekkie metadane katalogu kanałów, takie jak etykiety, ścieżki dokumentacji, aliasy i tekst wyboru. |
+| `openclaw.channel.configuredState` | Lekkie metadane sprawdzania stanu skonfigurowania, które mogą odpowiedzieć na pytanie „czy konfiguracja wyłącznie przez env już istnieje?” bez ładowania pełnego runtime kanału. |
+| `openclaw.channel.persistedAuthState` | Lekkie metadane sprawdzania utrwalonego auth, które mogą odpowiedzieć na pytanie „czy cokolwiek jest już zalogowane?” bez ładowania pełnego runtime kanału. |
+| `openclaw.install.npmSpec` / `openclaw.install.localPath` | Wskazówki instalacji/aktualizacji dla pluginów bundlowanych i publikowanych zewnętrznie. |
+| `openclaw.install.defaultChoice` | Preferowana ścieżka instalacji, gdy dostępnych jest wiele źródeł instalacji. |
+| `openclaw.install.minHostVersion` | Minimalna obsługiwana wersja hosta OpenClaw, z użyciem dolnej granicy semver, takiej jak `>=2026.3.22`. |
+| `openclaw.install.allowInvalidConfigRecovery` | Umożliwia wąską ścieżkę odzyskiwania przez ponowną instalację pluginu bundlowanego, gdy konfiguracja jest nieprawidłowa. |
+| `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` | Pozwala powierzchniom kanału tylko do konfiguracji ładować się przed pełnym pluginem kanału podczas uruchamiania. |
-`openclaw.install.minHostVersion` jest egzekwowane podczas instalacji i
-ładowania rejestru manifestów. Nieprawidłowe wartości są odrzucane; nowsze, ale
-prawidłowe wartości powodują pominięcie pluginu na starszych hostach.
+`openclaw.install.minHostVersion` jest egzekwowane podczas instalacji i ładowania rejestru
+manifestu. Nieprawidłowe wartości są odrzucane; nowsze, ale prawidłowe wartości powodują pominięcie
+pluginu na starszych hostach.
-`openclaw.install.allowInvalidConfigRecovery` jest celowo wąskie. Nie sprawia,
-że dowolne uszkodzone konfiguracje stają się możliwe do zainstalowania. Obecnie
-pozwala tylko przepływom instalacji odzyskać stan po konkretnych nieaktualnych
-błędach aktualizacji bundlowanych pluginów, takich jak brakująca ścieżka
-bundlowanego pluginu albo nieaktualny wpis `channels.` dla tego samego
-bundlowanego pluginu. Niezwiązane błędy konfiguracji nadal blokują instalację i
-kierują operatorów do `openclaw doctor --fix`.
+`openclaw.install.allowInvalidConfigRecovery` jest celowo bardzo wąskie. Nie
+sprawia, że dowolnie uszkodzone konfiguracje stają się możliwe do zainstalowania. Obecnie pozwala jedynie przepływom instalacji
+odzyskać sprawność po określonych nieaktualnych błędach aktualizacji pluginu bundlowanego, takich jak
+brak ścieżki do pluginu bundlowanego lub nieaktualny wpis `channels.` dla tego samego
+pluginu bundlowanego. Niepowiązane błędy konfiguracji nadal blokują instalację i kierują operatorów
+do `openclaw doctor --fix`.
-`openclaw.channel.persistedAuthState` to metadane pakietu dla małego modułu
-sprawdzającego:
+`openclaw.channel.persistedAuthState` to metadane pakietu dla małego modułu sprawdzającego:
```json
{
@@ -414,13 +492,13 @@ sprawdzającego:
}
```
-Używaj tego, gdy konfiguracja, doctor albo przepływy stanu konfiguracji
-potrzebują taniego sprawdzenia uwierzytelnienia typu tak/nie przed załadowaniem
-pełnego pluginu kanału. Docelowy eksport powinien być małą funkcją, która tylko
-odczytuje stan trwały; nie prowadź do niego przez pełny barrel runtime kanału.
+Używaj tego, gdy przepływy konfiguracji, doctor lub stanu skonfigurowania potrzebują taniego sondowania auth
+typu tak/nie przed załadowaniem pełnego pluginu kanału. Docelowy eksport powinien być małą
+funkcją odczytującą wyłącznie stan utrwalony; nie prowadź go przez pełny barrel runtime
+kanału.
-`openclaw.channel.configuredState` ma taki sam kształt dla tanich kontroli
-skonfigurowania tylko przez env:
+`openclaw.channel.configuredState` ma taki sam kształt dla tanich sprawdzeń
+skonfigurowania tylko na podstawie env:
```json
{
@@ -436,51 +514,51 @@ skonfigurowania tylko przez env:
}
```
-Używaj tego, gdy kanał może odpowiedzieć na pytanie o stan skonfigurowania na podstawie env lub innych małych
-wejść niezwiązanych z runtime. Jeśli sprawdzenie wymaga pełnego rozstrzygania konfiguracji lub
-rzeczywistego runtime kanału, zachowaj tę logikę w hooku pluginu `config.hasConfiguredState`.
+Używaj tego, gdy kanał może określić stan skonfigurowania na podstawie env lub innych małych
+wejść niezwiązanych z runtime. Jeśli sprawdzenie wymaga pełnego rozpoznania konfiguracji lub rzeczywistego
+runtime kanału, pozostaw tę logikę w hooku `config.hasConfiguredState` pluginu.
## Wymagania schematu JSON
-- **Każdy plugin musi dostarczać schemat JSON**, nawet jeśli nie przyjmuje żadnej konfiguracji.
-- Pusty schemat jest akceptowalny (na przykład `{ "type": "object", "additionalProperties": false }`).
+- **Każdy plugin musi dostarczać schemat JSON**, nawet jeśli nie akceptuje żadnej konfiguracji.
+- Pusty schemat jest akceptowalny, na przykład `{ "type": "object", "additionalProperties": false }`.
- Schematy są walidowane podczas odczytu/zapisu konfiguracji, a nie w runtime.
## Zachowanie walidacji
-- Nieznane klucze `channels.*` są **błędami**, chyba że identyfikator kanału został zadeklarowany przez
+- Nieznane klucze `channels.*` to **błędy**, chyba że identyfikator kanału jest zadeklarowany przez
manifest pluginu.
- `plugins.entries.`, `plugins.allow`, `plugins.deny` i `plugins.slots.*`
- muszą wskazywać **wykrywalne** identyfikatory pluginów. Nieznane identyfikatory są **błędami**.
+ muszą odwoływać się do identyfikatorów pluginów, które można **wykryć**. Nieznane identyfikatory to **błędy**.
- Jeśli plugin jest zainstalowany, ale ma uszkodzony lub brakujący manifest albo schemat,
walidacja kończy się niepowodzeniem, a Doctor zgłasza błąd pluginu.
-- Jeśli konfiguracja pluginu istnieje, ale plugin jest **wyłączony**, konfiguracja jest zachowywana i
- zgłaszane jest **ostrzeżenie** w Doctor + logach.
+- Jeśli konfiguracja pluginu istnieje, ale plugin jest **wyłączony**, konfiguracja jest zachowywana, a
+ w Doctor + logach pojawia się **ostrzeżenie**.
-Pełny schemat `plugins.*` znajdziesz w [Odniesieniu do konfiguracji](/pl/gateway/configuration).
+Zobacz [Odniesienie do konfiguracji](/pl/gateway/configuration), aby poznać pełny schemat `plugins.*`.
## Uwagi
-- Manifest jest **wymagany dla natywnych pluginów OpenClaw**, w tym ładowanych z lokalnego systemu plików.
+- Manifest jest **wymagany dla natywnych pluginów OpenClaw**, w tym przy ładowaniu z lokalnego systemu plików.
- Runtime nadal ładuje moduł pluginu osobno; manifest służy wyłącznie do
wykrywania + walidacji.
-- Natywne manifesty są parsowane przez JSON5, więc komentarze, końcowe przecinki i
- nieujęte w cudzysłów klucze są akceptowane, o ile końcowa wartość nadal jest obiektem.
-- Ładowarka manifestu odczytuje tylko udokumentowane pola manifestu. Unikaj dodawania
+- Natywne manifesty są parsowane przy użyciu JSON5, więc komentarze, końcowe przecinki i
+ nieujęte w cudzysłowy klucze są akceptowane, o ile końcowa wartość nadal jest obiektem.
+- Loader manifestu odczytuje tylko udokumentowane pola manifestu. Unikaj dodawania
tutaj własnych kluczy najwyższego poziomu.
-- `providerAuthEnvVars` to tania ścieżka metadanych dla sprawdzania uwierzytelnienia, walidacji znaczników env
- i podobnych powierzchni uwierzytelniania dostawców, które nie powinny uruchamiać runtime pluginu
+- `providerAuthEnvVars` to tania ścieżka metadanych dla sondowania auth, walidacji
+ znaczników env i podobnych powierzchni uwierzytelniania dostawcy, które nie powinny uruchamiać runtime pluginu
tylko po to, aby sprawdzić nazwy env.
-- `providerAuthAliases` pozwala wariantom dostawców ponownie używać env vars uwierzytelniania,
- profili uwierzytelniania, uwierzytelniania opartego na konfiguracji i wyboru onboardingu klucza API innego dostawcy
- bez zakodowywania tej relacji na sztywno w rdzeniu.
-- `channelEnvVars` to tania ścieżka metadanych dla fallbacku env powłoki, promptów konfiguracji
- i podobnych powierzchni kanałów, które nie powinny uruchamiać runtime pluginu
+- `providerAuthAliases` pozwala wariantom dostawcy ponownie używać auth
+ env vars, profili auth, auth opartego na konfiguracji i wyboru onboardingu klucza API innego dostawcy
+ bez twardego kodowania tej relacji w rdzeniu.
+- `channelEnvVars` to tania ścieżka metadanych dla rezerwowego użycia env powłoki, promptów konfiguracji
+ i podobnych powierzchni kanału, które nie powinny uruchamiać runtime pluginu
tylko po to, aby sprawdzić nazwy env.
-- `providerAuthChoices` to tania ścieżka metadanych dla selektorów wyboru uwierzytelniania,
- rozstrzygania `--auth-choice`, mapowania preferowanego dostawcy i prostego rejestrowania
- flag CLI onboardingu przed załadowaniem runtime dostawcy. Metadane kreatora runtime,
- które wymagają kodu dostawcy, opisano w
+- `providerAuthChoices` to tania ścieżka metadanych dla selektorów wyboru auth,
+ rozpoznawania `--auth-choice`, mapowania preferowanego dostawcy i prostej rejestracji flag CLI
+ onboardingu przed załadowaniem runtime dostawcy. Metadane kreatora runtime,
+ które wymagają kodu dostawcy, znajdziesz w
[Hookach runtime dostawcy](/pl/plugins/architecture#provider-runtime-hooks).
- Wyłączne rodzaje pluginów są wybierane przez `plugins.slots.*`.
- `kind: "memory"` jest wybierane przez `plugins.slots.memory`.
@@ -488,12 +566,12 @@ Pełny schemat `plugins.*` znajdziesz w [Odniesieniu do konfiguracji](/pl/gatewa
(domyślnie: wbudowane `legacy`).
- `channels`, `providers`, `cliBackends` i `skills` można pominąć, gdy
plugin ich nie potrzebuje.
-- Jeśli Twój plugin zależy od modułów natywnych, udokumentuj kroki budowania i wszelkie
- wymagania dotyczące listy dozwolonych menedżera pakietów (na przykład pnpm `allow-build-scripts`
- - `pnpm rebuild `).
+- Jeśli Twój plugin zależy od modułów natywnych, udokumentuj kroki budowania oraz wszelkie
+ wymagania dotyczące listy dozwolonych menedżera pakietów, na przykład pnpm `allow-build-scripts`
+ - `pnpm rebuild `.
## Powiązane
-- [Tworzenie pluginów](/pl/plugins/building-plugins) — wprowadzenie do pluginów
+- [Tworzenie pluginów](/pl/plugins/building-plugins) — jak zacząć pracę z pluginami
- [Architektura pluginów](/pl/plugins/architecture) — architektura wewnętrzna
-- [Przegląd SDK](/pl/plugins/sdk-overview) — odniesienie do Plugin SDK
+- [Przegląd SDK](/pl/plugins/sdk-overview) — odniesienie do SDK pluginów
diff --git a/docs/pl/reference/rich-output-protocol.md b/docs/pl/reference/rich-output-protocol.md
new file mode 100644
index 000000000..ee488e509
--- /dev/null
+++ b/docs/pl/reference/rich-output-protocol.md
@@ -0,0 +1,60 @@
+---
+x-i18n:
+ generated_at: "2026-04-11T15:15:56Z"
+ model: gpt-5.4
+ provider: openai
+ source_hash: 2a8884fc2c304bf96d4675f0c1d1ff781d6dc1ae8c49d92ce08040c9c7709035
+ source_path: reference/rich-output-protocol.md
+ workflow: 15
+---
+
+# Protokół rozbudowanego wyjścia
+
+Wynik asystenta może zawierać niewielki zestaw dyrektyw dostarczania/renderowania:
+
+- `MEDIA:` do dostarczania załączników
+- `[[audio_as_voice]]` do wskazówek dotyczących prezentacji audio
+- `[[reply_to_current]]` / `[[reply_to:]]` do metadanych odpowiedzi
+- `[embed ...]` do rozbudowanego renderowania w interfejsie użytkownika Control UI
+
+Te dyrektywy są odrębne. `MEDIA:` oraz tagi reply/voice pozostają metadanymi dostarczania; `[embed ...]` to ścieżka rozbudowanego renderowania tylko dla sieci.
+
+## `[embed ...]`
+
+`[embed ...]` to jedyna składnia rozbudowanego renderowania skierowana do agentów dla interfejsu użytkownika Control UI.
+
+Przykład samodomykający:
+
+```text
+[embed ref="cv_123" title="Status" /]
+```
+
+Zasady:
+
+- `[view ...]` nie jest już prawidłowe dla nowych wyników.
+- Krótkie kody embed są renderowane tylko na powierzchni wiadomości asystenta.
+- Renderowane są tylko osadzenia oparte na URL. Użyj `ref="..."` lub `url="..."`.
+- Krótkie kody osadzania w postaci blokowej, zapisane jako wbudowany HTML, nie są renderowane.
+- Interfejs webowy usuwa shortcode z widocznego tekstu i renderuje osadzenie w linii.
+- `MEDIA:` nie jest aliasem embed i nie należy go używać do renderowania rozbudowanych osadzeń.
+
+## Zapisany kształt renderowania
+
+Znormalizowany/zapisany blok treści asystenta ma postać uporządkowanego elementu `canvas`:
+
+```json
+{
+ "type": "canvas",
+ "preview": {
+ "kind": "canvas",
+ "surface": "assistant_message",
+ "render": "url",
+ "viewId": "cv_123",
+ "url": "/__openclaw__/canvas/documents/cv_123/index.html",
+ "title": "Status",
+ "preferredHeight": 320
+ }
+}
+```
+
+Zapisane/renderowane bloki rozbudowane używają bezpośrednio tego kształtu `canvas`. `present_view` nie jest rozpoznawane.