chore(i18n): refresh pl translations
This commit is contained in:
openclaw-docs-i18n[bot]
parent
3b832929cc
commit
e8ba7a0820
File diff suppressed because it is too large
Load Diff
@ -1,18 +1,18 @@
|
||||
---
|
||||
read_when:
|
||||
- Konfigurowanie Slack lub debugowanie trybu socket/HTTP Slack
|
||||
summary: Konfiguracja Slacka i zachowanie w czasie działania (tryb Socket + adresy URL żądań HTTP)
|
||||
summary: Konfiguracja Slack i zachowanie w czasie działania (Socket Mode + adresy URL żądań HTTP)
|
||||
title: Slack
|
||||
x-i18n:
|
||||
generated_at: "2026-05-04T02:22:29Z"
|
||||
generated_at: "2026-05-04T07:02:45Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 2be45f03511a64373b1f4316c59800eeeef8baccb4c00454b49999258b2e546b
|
||||
source_hash: d4a91fc1ae5f1e03f714308be54e164ef204809e74efabed8dc75c3035c14228
|
||||
source_path: channels/slack.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
Gotowo do produkcji dla wiadomości prywatnych i kanałów za pośrednictwem integracji aplikacji Slack. Domyślnym trybem jest Socket Mode; obsługiwane są także adresy URL żądań HTTP.
|
||||
Gotowe produkcyjnie dla wiadomości prywatnych i kanałów przez integracje aplikacji Slack. Domyślnym trybem jest Socket Mode; obsługiwane są też HTTP Request URLs.
|
||||
|
||||
<CardGroup cols={3}>
|
||||
<Card title="Pairing" icon="link" href="/pl/channels/pairing">
|
||||
@ -22,7 +22,7 @@ Gotowo do produkcji dla wiadomości prywatnych i kanałów za pośrednictwem int
|
||||
Natywne zachowanie poleceń i katalog poleceń.
|
||||
</Card>
|
||||
<Card title="Channel troubleshooting" icon="wrench" href="/pl/channels/troubleshooting">
|
||||
Diagnostyka międzykanałowa i scenariusze naprawcze.
|
||||
Diagnostyka międzykanałowa i procedury naprawcze.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
@ -34,8 +34,8 @@ Gotowo do produkcji dla wiadomości prywatnych i kanałów za pośrednictwem int
|
||||
<Step title="Create a new Slack app">
|
||||
W ustawieniach aplikacji Slack naciśnij przycisk **[Create New App](https://api.slack.com/apps/new)**:
|
||||
|
||||
- wybierz **from a manifest** i wybierz przestrzeń roboczą dla swojej aplikacji
|
||||
- wklej [przykładowy manifest](#manifest-and-scope-checklist) poniżej i kontynuuj tworzenie
|
||||
- wybierz **from a manifest** i wybierz obszar roboczy dla swojej aplikacji
|
||||
- wklej poniższy [przykładowy manifest](#manifest-and-scope-checklist) i kontynuuj tworzenie
|
||||
- wygeneruj **App-Level Token** (`xapp-...`) z `connections:write`
|
||||
- zainstaluj aplikację i skopiuj wyświetlony **Bot Token** (`xoxb-...`)
|
||||
|
||||
@ -64,7 +64,7 @@ openclaw config patch --file ./slack.socket.patch.json5 --dry-run
|
||||
openclaw config patch --file ./slack.socket.patch.json5
|
||||
```
|
||||
|
||||
Awaryjna konfiguracja przez zmienne środowiskowe (tylko konto domyślne):
|
||||
Rezerwowa konfiguracja env (tylko konto domyślne):
|
||||
|
||||
```bash
|
||||
SLACK_APP_TOKEN=xapp-...
|
||||
@ -89,7 +89,7 @@ openclaw gateway
|
||||
<Step title="Create a new Slack app">
|
||||
W ustawieniach aplikacji Slack naciśnij przycisk **[Create New App](https://api.slack.com/apps/new)**:
|
||||
|
||||
- wybierz **from a manifest** i wybierz przestrzeń roboczą dla swojej aplikacji
|
||||
- wybierz **from a manifest** i wybierz obszar roboczy dla swojej aplikacji
|
||||
- wklej [przykładowy manifest](#manifest-and-scope-checklist) i zaktualizuj adresy URL przed utworzeniem
|
||||
- zapisz **Signing Secret** do weryfikacji żądań
|
||||
- zainstaluj aplikację i skopiuj wyświetlony **Bot Token** (`xoxb-...`)
|
||||
@ -121,9 +121,9 @@ openclaw config patch --file ./slack.http.patch.json5
|
||||
```
|
||||
|
||||
<Note>
|
||||
Używaj unikatowych ścieżek Webhook dla wielu kont HTTP
|
||||
Używaj unikalnych ścieżek webhook dla HTTP z wieloma kontami
|
||||
|
||||
Nadaj każdemu kontu odrębną wartość `webhookPath` (domyślnie `/slack/events`), aby rejestracje nie kolidowały.
|
||||
Nadaj każdemu kontu odrębny `webhookPath` (domyślnie `/slack/events`), aby rejestracje nie kolidowały.
|
||||
</Note>
|
||||
|
||||
</Step>
|
||||
@ -140,9 +140,9 @@ openclaw gateway
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
## Dostrajanie transportu Socket Mode
|
||||
## Dostosowywanie transportu Socket Mode
|
||||
|
||||
OpenClaw domyślnie ustawia limit czasu pong klienta Slack SDK na 15 sekund dla Socket Mode. Nadpisuj ustawienia transportu tylko wtedy, gdy potrzebujesz dostrojenia specyficznego dla przestrzeni roboczej lub hosta:
|
||||
OpenClaw domyślnie ustawia limit czasu pong klienta Slack SDK na 15 sekund dla Socket Mode. Nadpisuj ustawienia transportu tylko wtedy, gdy potrzebujesz dostosowania specyficznego dla obszaru roboczego lub hosta:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -159,13 +159,13 @@ OpenClaw domyślnie ustawia limit czasu pong klienta Slack SDK na 15 sekund dla
|
||||
}
|
||||
```
|
||||
|
||||
Używaj tego tylko dla przestrzeni roboczych Socket Mode, które rejestrują przekroczenia limitu czasu pong websocket Slack lub pingów serwera, albo działają na hostach ze znanym głodzeniem pętli zdarzeń. `clientPingTimeout` to czas oczekiwania na pong po wysłaniu przez SDK pingu klienta; `serverPingTimeout` to czas oczekiwania na pingi serwera Slack. Wiadomości i zdarzenia aplikacji pozostają stanem aplikacji, a nie sygnałami żywotności transportu.
|
||||
Używaj tego tylko dla obszarów roboczych Socket Mode, które rejestrują limity czasu pong websocket Slack albo server-ping, lub działają na hostach ze znanym głodzeniem pętli zdarzeń. `clientPingTimeout` to czas oczekiwania na pong po wysłaniu przez SDK pingu klienta; `serverPingTimeout` to czas oczekiwania na pingi serwera Slack. Wiadomości i zdarzenia aplikacji pozostają stanem aplikacji, a nie sygnałami żywotności transportu.
|
||||
|
||||
## Lista kontrolna manifestu i zakresów
|
||||
|
||||
Podstawowy manifest aplikacji Slack jest taki sam dla Socket Mode i adresów URL żądań HTTP. Różni się tylko blok `settings` (oraz `url` polecenia slash).
|
||||
Podstawowy manifest aplikacji Slack jest taki sam dla Socket Mode i HTTP Request URLs. Różni się tylko blok `settings` (oraz `url` polecenia slash).
|
||||
|
||||
Manifest podstawowy (domyślnie Socket Mode):
|
||||
Podstawowy manifest (domyślny Socket Mode):
|
||||
|
||||
```json
|
||||
{
|
||||
@ -240,7 +240,7 @@ Manifest podstawowy (domyślnie Socket Mode):
|
||||
}
|
||||
```
|
||||
|
||||
Dla **trybu adresów URL żądań HTTP** zastąp `settings` wariantem HTTP i dodaj `url` do każdego polecenia slash. Wymagany jest publiczny adres URL:
|
||||
W trybie **HTTP Request URLs** zastąp `settings` wariantem HTTP i dodaj `url` do każdego polecenia slash. Wymagany publiczny URL:
|
||||
|
||||
```json
|
||||
{
|
||||
@ -284,14 +284,14 @@ Dla **trybu adresów URL żądań HTTP** zastąp `settings` wariantem HTTP i dod
|
||||
|
||||
### Dodatkowe ustawienia manifestu
|
||||
|
||||
Udostępnij różne funkcje rozszerzające powyższe wartości domyślne.
|
||||
Udostępnij różne funkcje rozszerzające powyższe ustawienia domyślne.
|
||||
|
||||
Domyślny manifest włącza kartę **Home** w Slack App Home i subskrybuje `app_home_opened`. Gdy członek przestrzeni roboczej otworzy kartę Home, OpenClaw publikuje bezpieczny domyślny widok Home za pomocą `views.publish`; nie są dołączane żadne dane konwersacji ani prywatna konfiguracja. Karta **Messages** pozostaje włączona dla wiadomości prywatnych Slack.
|
||||
Domyślny manifest włącza kartę **Home** w Slack App Home i subskrybuje `app_home_opened`. Gdy członek obszaru roboczego otworzy kartę Home, OpenClaw publikuje bezpieczny domyślny widok Home za pomocą `views.publish`; nie są dołączane żadne dane rozmowy ani prywatna konfiguracja. Karta **Messages** pozostaje włączona dla wiadomości prywatnych Slack.
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Optional native slash commands">
|
||||
|
||||
Zamiast jednego skonfigurowanego polecenia można używać wielu [natywnych poleceń slash](#commands-and-slash-behavior), z pewnymi niuansami:
|
||||
Zamiast pojedynczego skonfigurowanego polecenia można użyć wielu [natywnych poleceń slash](#commands-and-slash-behavior), z pewnymi niuansami:
|
||||
|
||||
- Użyj `/agentstatus` zamiast `/status`, ponieważ polecenie `/status` jest zarezerwowane.
|
||||
- Jednocześnie można udostępnić nie więcej niż 25 poleceń slash.
|
||||
@ -423,7 +423,7 @@ Domyślny manifest włącza kartę **Home** w Slack App Home i subskrybuje `app_
|
||||
|
||||
</Tab>
|
||||
<Tab title="HTTP Request URLs">
|
||||
Użyj tej samej listy `slash_commands` co powyżej dla Socket Mode i dodaj `"url": "https://gateway-host.example.com/slack/events"` do każdego wpisu. Przykład:
|
||||
Użyj tej samej listy `slash_commands` co w Socket Mode powyżej i dodaj `"url": "https://gateway-host.example.com/slack/events"` do każdego wpisu. Przykład:
|
||||
|
||||
```json
|
||||
{
|
||||
@ -471,27 +471,27 @@ Domyślny manifest włącza kartę **Home** w Slack App Home i subskrybuje `app_
|
||||
|
||||
## Model tokenów
|
||||
|
||||
- `botToken` + `appToken` są wymagane dla Socket Mode.
|
||||
- `botToken` + `appToken` są wymagane w trybie Socket Mode.
|
||||
- Tryb HTTP wymaga `botToken` + `signingSecret`.
|
||||
- `botToken`, `appToken`, `signingSecret` i `userToken` akceptują jawne
|
||||
- `botToken`, `appToken`, `signingSecret` i `userToken` przyjmują jawne
|
||||
ciągi tekstowe lub obiekty SecretRef.
|
||||
- Tokeny z konfiguracji zastępują rezerwowe wartości ze zmiennych środowiskowych.
|
||||
- Rezerwowe zmienne środowiskowe `SLACK_BOT_TOKEN` / `SLACK_APP_TOKEN` dotyczą tylko konta domyślnego.
|
||||
- `userToken` (`xoxp-...`) jest tylko konfiguracyjny (bez rezerwowej zmiennej środowiskowej) i domyślnie działa tylko do odczytu (`userTokenReadOnly: true`).
|
||||
- Tokeny z konfiguracji zastępują awaryjne wartości z env.
|
||||
- Awaryjne wartości env `SLACK_BOT_TOKEN` / `SLACK_APP_TOKEN` mają zastosowanie tylko do konta domyślnego.
|
||||
- `userToken` (`xoxp-...`) jest dostępny tylko w konfiguracji (bez awaryjnej wartości env) i domyślnie działa tylko do odczytu (`userTokenReadOnly: true`).
|
||||
|
||||
Zachowanie migawki statusu:
|
||||
Zachowanie migawki stanu:
|
||||
|
||||
- Inspekcja konta Slack śledzi pola `*Source` i `*Status`
|
||||
dla poszczególnych poświadczeń (`botToken`, `appToken`, `signingSecret`, `userToken`).
|
||||
- Status to `available`, `configured_unavailable` albo `missing`.
|
||||
- Stan to `available`, `configured_unavailable` albo `missing`.
|
||||
- `configured_unavailable` oznacza, że konto jest skonfigurowane przez SecretRef
|
||||
albo inne niewstawione bezpośrednio źródło sekretu, ale bieżąca ścieżka polecenia/środowiska uruchomieniowego
|
||||
nie mogła ustalić rzeczywistej wartości.
|
||||
- W trybie HTTP uwzględniany jest `signingSecretStatus`; w Socket Mode
|
||||
lub inne źródło sekretu spoza konfiguracji inline, ale bieżąca ścieżka polecenia/uruchomienia
|
||||
nie mogła rozwiązać rzeczywistej wartości.
|
||||
- W trybie HTTP uwzględniane jest `signingSecretStatus`; w trybie Socket Mode
|
||||
wymagana para to `botTokenStatus` + `appTokenStatus`.
|
||||
|
||||
<Tip>
|
||||
W przypadku akcji/odczytów katalogu token użytkownika może być preferowany, gdy jest skonfigurowany. W przypadku zapisów nadal preferowany jest token bota; zapisy przez token użytkownika są dozwolone tylko wtedy, gdy `userTokenReadOnly: false`, a token bota jest niedostępny.
|
||||
W przypadku akcji/odczytów katalogu token użytkownika może być preferowany, gdy jest skonfigurowany. W przypadku zapisów preferowany pozostaje token bota; zapisy z użyciem tokena użytkownika są dozwolone tylko wtedy, gdy `userTokenReadOnly: false`, a token bota jest niedostępny.
|
||||
</Tip>
|
||||
|
||||
## Akcje i bramki
|
||||
@ -501,20 +501,20 @@ Akcje Slack są kontrolowane przez `channels.slack.actions.*`.
|
||||
Dostępne grupy akcji w bieżących narzędziach Slack:
|
||||
|
||||
| Grupa | Domyślnie |
|
||||
| ---------- | --------- |
|
||||
| messages | włączone |
|
||||
| reactions | włączone |
|
||||
| pins | włączone |
|
||||
| memberInfo | włączone |
|
||||
| emojiList | włączone |
|
||||
| ---------- | ------- |
|
||||
| messages | włączone |
|
||||
| reactions | włączone |
|
||||
| pins | włączone |
|
||||
| memberInfo | włączone |
|
||||
| emojiList | włączone |
|
||||
|
||||
Bieżące akcje wiadomości Slack obejmują `send`, `upload-file`, `download-file`, `read`, `edit`, `delete`, `pin`, `unpin`, `list-pins`, `member-info` i `emoji-list`. `download-file` akceptuje identyfikatory plików Slack pokazywane w przychodzących placeholderach plików i zwraca podglądy obrazów dla obrazów albo lokalne metadane pliku dla innych typów plików.
|
||||
Bieżące akcje wiadomości Slack obejmują `send`, `upload-file`, `download-file`, `read`, `edit`, `delete`, `pin`, `unpin`, `list-pins`, `member-info` i `emoji-list`. `download-file` przyjmuje identyfikatory plików Slack widoczne w placeholderach plików przychodzących i zwraca podglądy obrazów dla obrazów albo metadane pliku lokalnego dla innych typów plików.
|
||||
|
||||
## Kontrola dostępu i routing
|
||||
|
||||
<Tabs>
|
||||
<Tab title="Zasady DM">
|
||||
`channels.slack.dmPolicy` kontroluje dostęp do DM. `channels.slack.allowFrom` jest kanoniczną listą dozwolonych DM.
|
||||
<Tab title="Polityka DM">
|
||||
`channels.slack.dmPolicy` kontroluje dostęp DM. `channels.slack.allowFrom` jest kanoniczną listą dozwolonych DM.
|
||||
|
||||
- `pairing` (domyślnie)
|
||||
- `allowlist`
|
||||
@ -529,19 +529,19 @@ Bieżące akcje wiadomości Slack obejmują `send`, `upload-file`, `download-fil
|
||||
- `dm.groupEnabled` (grupowe DM domyślnie false)
|
||||
- `dm.groupChannels` (opcjonalna lista dozwolonych MPIM)
|
||||
|
||||
Pierwszeństwo przy wielu kontach:
|
||||
Priorytet wielu kont:
|
||||
|
||||
- `channels.slack.accounts.default.allowFrom` dotyczy tylko konta `default`.
|
||||
- `channels.slack.accounts.default.allowFrom` ma zastosowanie tylko do konta `default`.
|
||||
- Nazwane konta dziedziczą `channels.slack.allowFrom`, gdy ich własne `allowFrom` nie jest ustawione.
|
||||
- Nazwane konta nie dziedziczą `channels.slack.accounts.default.allowFrom`.
|
||||
|
||||
Starsze `channels.slack.dm.policy` i `channels.slack.dm.allowFrom` są nadal odczytywane ze względu na zgodność. `openclaw doctor --fix` migruje je do `dmPolicy` i `allowFrom`, gdy może to zrobić bez zmiany dostępu.
|
||||
Starsze `channels.slack.dm.policy` i `channels.slack.dm.allowFrom` są nadal odczytywane dla zgodności. `openclaw doctor --fix` migruje je do `dmPolicy` i `allowFrom`, gdy może to zrobić bez zmiany dostępu.
|
||||
|
||||
Parowanie w DM używa `openclaw pairing approve slack <code>`.
|
||||
|
||||
</Tab>
|
||||
|
||||
<Tab title="Zasady kanału">
|
||||
<Tab title="Polityka kanału">
|
||||
`channels.slack.groupPolicy` kontroluje obsługę kanałów:
|
||||
|
||||
- `open`
|
||||
@ -550,18 +550,18 @@ Bieżące akcje wiadomości Slack obejmują `send`, `upload-file`, `download-fil
|
||||
|
||||
Lista dozwolonych kanałów znajduje się pod `channels.slack.channels` i **musi używać stabilnych identyfikatorów kanałów Slack** (na przykład `C12345678`) jako kluczy konfiguracji.
|
||||
|
||||
Uwaga dotycząca środowiska uruchomieniowego: jeśli `channels.slack` całkowicie brakuje (konfiguracja wyłącznie przez zmienne środowiskowe), środowisko uruchomieniowe wraca do `groupPolicy="allowlist"` i rejestruje ostrzeżenie (nawet jeśli ustawiono `channels.defaults.groupPolicy`).
|
||||
Uwaga dotycząca środowiska uruchomieniowego: jeśli `channels.slack` całkowicie brakuje (konfiguracja tylko z env), środowisko uruchomieniowe wraca do `groupPolicy="allowlist"` i zapisuje ostrzeżenie w logu (nawet jeśli ustawiono `channels.defaults.groupPolicy`).
|
||||
|
||||
Rozpoznawanie nazwy/ID:
|
||||
Rozwiązywanie nazw/identyfikatorów:
|
||||
|
||||
- wpisy listy dozwolonych kanałów i wpisy listy dozwolonych DM są rozpoznawane podczas uruchamiania, gdy pozwala na to dostęp tokena
|
||||
- nierozpoznane wpisy nazw kanałów są zachowywane zgodnie z konfiguracją, ale domyślnie ignorowane przy routingu
|
||||
- autoryzacja przychodząca i routing kanałów domyślnie najpierw używają ID; bezpośrednie dopasowywanie nazwy użytkownika/sluga wymaga `channels.slack.dangerouslyAllowNameMatching: true`
|
||||
- wpisy listy dozwolonych kanałów i wpisy listy dozwolonych DM są rozwiązywane przy starcie, gdy dostęp tokena na to pozwala
|
||||
- nierozwiązane wpisy nazw kanałów są zachowywane zgodnie z konfiguracją, ale domyślnie ignorowane przy routingu
|
||||
- autoryzacja przychodząca i routing kanałów domyślnie w pierwszej kolejności używają identyfikatorów; bezpośrednie dopasowywanie nazwy użytkownika/sluga wymaga `channels.slack.dangerouslyAllowNameMatching: true`
|
||||
|
||||
<Warning>
|
||||
Klucze oparte na nazwie (`#channel-name` albo `channel-name`) **nie** pasują przy `groupPolicy: "allowlist"`. Wyszukiwanie kanału domyślnie najpierw używa ID, więc klucz oparty na nazwie nigdy nie zostanie poprawnie zrutowany, a wszystkie wiadomości w tym kanale będą po cichu blokowane. Różni się to od `groupPolicy: "open"`, gdzie klucz kanału nie jest wymagany do routingu i klucz oparty na nazwie wydaje się działać.
|
||||
Klucze oparte na nazwach (`#channel-name` lub `channel-name`) **nie** pasują przy `groupPolicy: "allowlist"`. Wyszukiwanie kanałów domyślnie w pierwszej kolejności używa identyfikatorów, więc klucz oparty na nazwie nigdy nie zostanie poprawnie obsłużony przez routing, a wszystkie wiadomości w tym kanale zostaną po cichu zablokowane. Różni się to od `groupPolicy: "open"`, gdzie klucz kanału nie jest wymagany do routingu i klucz oparty na nazwie wydaje się działać.
|
||||
|
||||
Zawsze używaj ID kanału Slack jako klucza. Aby go znaleźć: kliknij kanał prawym przyciskiem w Slack → **Kopiuj link** — ID (`C...`) pojawia się na końcu adresu URL.
|
||||
Zawsze używaj identyfikatora kanału Slack jako klucza. Aby go znaleźć: kliknij kanał prawym przyciskiem myszy w Slack → **Copy link** — identyfikator (`C...`) pojawi się na końcu URL-a.
|
||||
|
||||
Poprawnie:
|
||||
|
||||
@ -578,7 +578,7 @@ Bieżące akcje wiadomości Slack obejmują `send`, `upload-file`, `download-fil
|
||||
}
|
||||
```
|
||||
|
||||
Niepoprawnie (po cichu blokowane przy `groupPolicy: "allowlist"`):
|
||||
Nieprawidłowo (cicho blokowane przy `groupPolicy: "allowlist"`):
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -596,17 +596,17 @@ Bieżące akcje wiadomości Slack obejmują `send`, `upload-file`, `download-fil
|
||||
|
||||
</Tab>
|
||||
|
||||
<Tab title="Wzmianki i użytkownicy kanału">
|
||||
Wiadomości kanału domyślnie wymagają wzmianki.
|
||||
<Tab title="Mentions and channel users">
|
||||
Wiadomości w kanałach domyślnie wymagają wzmianki.
|
||||
|
||||
Źródła wzmianki:
|
||||
Źródła wzmianek:
|
||||
|
||||
- jawna wzmianka o aplikacji (`<@botId>`)
|
||||
- wzmianka o grupie użytkowników Slack (`<!subteam^S...>`), gdy użytkownik bota jest członkiem tej grupy użytkowników; wymaga `usergroups:read`
|
||||
- wzorce wyrażeń regularnych wzmianki (`agents.list[].groupChat.mentionPatterns`, rezerwowo `messages.groupChat.mentionPatterns`)
|
||||
- niejawne zachowanie wątku jako odpowiedzi do bota (wyłączone, gdy `thread.requireExplicitMention` ma wartość `true`)
|
||||
- wzorce wyrażeń regularnych wzmianek (`agents.list[].groupChat.mentionPatterns`, awaryjnie `messages.groupChat.mentionPatterns`)
|
||||
- niejawne zachowanie wątków odpowiadających botowi (wyłączone, gdy `thread.requireExplicitMention` ma wartość `true`)
|
||||
|
||||
Kontrole dla poszczególnych kanałów (`channels.slack.channels.<id>`; nazwy tylko przez rozpoznawanie przy uruchomieniu albo `dangerouslyAllowNameMatching`):
|
||||
Kontrole dla poszczególnych kanałów (`channels.slack.channels.<id>`; nazwy tylko przez rozpoznawanie przy starcie lub `dangerouslyAllowNameMatching`):
|
||||
|
||||
- `requireMention`
|
||||
- `users` (lista dozwolonych)
|
||||
@ -614,38 +614,38 @@ Bieżące akcje wiadomości Slack obejmują `send`, `upload-file`, `download-fil
|
||||
- `skills`
|
||||
- `systemPrompt`
|
||||
- `tools`, `toolsBySender`
|
||||
- format klucza `toolsBySender`: `id:`, `e164:`, `username:`, `name:` albo symbol wieloznaczny `"*"`
|
||||
- format klucza `toolsBySender`: `id:`, `e164:`, `username:`, `name:` lub symbol wieloznaczny `"*"`
|
||||
(starsze klucze bez prefiksu nadal mapują tylko na `id:`)
|
||||
|
||||
`allowBots` jest zachowawcze dla kanałów i kanałów prywatnych: wiadomości w pokojach autorstwa botów są akceptowane tylko wtedy, gdy wysyłający bot jest jawnie wymieniony na liście dozwolonych `users` tego pokoju, albo gdy co najmniej jeden jawny ID właściciela Slack z `channels.slack.allowFrom` jest obecnie członkiem pokoju. Symbole wieloznaczne i wpisy właścicieli oparte na nazwie wyświetlanej nie spełniają warunku obecności właściciela. Obecność właściciela używa Slack `conversations.members`; upewnij się, że aplikacja ma odpowiedni zakres odczytu dla typu pokoju (`channels:read` dla kanałów publicznych, `groups:read` dla kanałów prywatnych). Jeśli wyszukiwanie członków się nie powiedzie, OpenClaw odrzuca wiadomość w pokoju autorstwa bota.
|
||||
`allowBots` działa konserwatywnie dla kanałów i kanałów prywatnych: wiadomości w pokoju napisane przez bota są akceptowane tylko wtedy, gdy wysyłający bot jest jawnie wymieniony na liście dozwolonych `users` tego pokoju albo gdy co najmniej jeden jawny identyfikator właściciela Slack z `channels.slack.allowFrom` jest obecnie członkiem pokoju. Symbole wieloznaczne i wpisy właścicieli oparte na nazwie wyświetlanej nie spełniają warunku obecności właściciela. Obecność właściciela używa Slack `conversations.members`; upewnij się, że aplikacja ma odpowiedni zakres odczytu dla typu pokoju (`channels:read` dla kanałów publicznych, `groups:read` dla kanałów prywatnych). Jeśli wyszukiwanie członków się nie powiedzie, OpenClaw odrzuca wiadomość w pokoju napisaną przez bota.
|
||||
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
## Wątki, sesje i tagi odpowiedzi
|
||||
|
||||
- DM są routowane jako `direct`; kanały jako `channel`; MPIM jako `group`.
|
||||
- Powiązania tras Slack akceptują surowe ID peerów oraz formy celów Slack, takie jak `channel:C12345678`, `user:U12345678` i `<@U12345678>`.
|
||||
- Przy domyślnym `session.dmScope=main` DM Slack zwijają się do głównej sesji agenta.
|
||||
- DM są kierowane jako `direct`; kanały jako `channel`; MPIM jako `group`.
|
||||
- Powiązania tras Slack akceptują surowe identyfikatory uczestników oraz formy celów Slack, takie jak `channel:C12345678`, `user:U12345678` i `<@U12345678>`.
|
||||
- Przy domyślnym `session.dmScope=main` DM Slack są scalane z główną sesją agenta.
|
||||
- Sesje kanałów: `agent:<agentId>:slack:channel:<channelId>`.
|
||||
- Odpowiedzi w wątkach mogą tworzyć sufiksy sesji wątku (`:thread:<threadTs>`), gdy ma to zastosowanie.
|
||||
- Domyślne `channels.slack.thread.historyScope` to `thread`; domyślne `thread.inheritParent` to `false`.
|
||||
- Odpowiedzi w wątku mogą tworzyć sufiksy sesji wątku (`:thread:<threadTs>`), gdy ma to zastosowanie.
|
||||
- Domyślną wartością `channels.slack.thread.historyScope` jest `thread`; domyślną wartością `thread.inheritParent` jest `false`.
|
||||
- `channels.slack.thread.initialHistoryLimit` kontroluje, ile istniejących wiadomości wątku jest pobieranych po rozpoczęciu nowej sesji wątku (domyślnie `20`; ustaw `0`, aby wyłączyć).
|
||||
- `channels.slack.thread.requireExplicitMention` (domyślnie `false`): gdy `true`, pomija niejawne wzmianki w wątku, aby bot odpowiadał tylko na jawne wzmianki `@bot` wewnątrz wątków, nawet jeśli bot już uczestniczył w wątku. Bez tego odpowiedzi w wątku, w którym uczestniczył bot, omijają bramkowanie `requireMention`.
|
||||
- `channels.slack.thread.requireExplicitMention` (domyślnie `false`): gdy ma wartość `true`, tłumi niejawne wzmianki w wątku, aby bot odpowiadał tylko na jawne wzmianki `@bot` w wątkach, nawet jeśli bot już uczestniczył w wątku. Bez tego odpowiedzi w wątku, w którym uczestniczył bot, omijają bramkowanie `requireMention`.
|
||||
|
||||
Kontrole wątków odpowiedzi:
|
||||
|
||||
- `channels.slack.replyToMode`: `off|first|all|batched` (domyślnie `off`)
|
||||
- `channels.slack.replyToModeByChatType`: dla każdego `direct|group|channel`
|
||||
- starszy mechanizm rezerwowy dla czatów bezpośrednich: `channels.slack.dm.replyToMode`
|
||||
- starszy mechanizm awaryjny dla czatów bezpośrednich: `channels.slack.dm.replyToMode`
|
||||
|
||||
Ręczne tagi odpowiedzi są obsługiwane:
|
||||
Obsługiwane są ręczne tagi odpowiedzi:
|
||||
|
||||
- `[[reply_to_current]]`
|
||||
- `[[reply_to:<id>]]`
|
||||
|
||||
<Note>
|
||||
`replyToMode="off"` wyłącza **wszystkie** wątki odpowiedzi w Slack, w tym jawne tagi `[[reply_to_*]]`. Różni się to od Telegram, gdzie jawne tagi nadal są honorowane w trybie `"off"`. Wątki Slack ukrywają wiadomości przed kanałem, podczas gdy odpowiedzi Telegram pozostają widoczne w wierszu.
|
||||
`replyToMode="off"` wyłącza **wszystkie** wątki odpowiedzi w Slack, w tym jawne tagi `[[reply_to_*]]`. Różni się to od Telegram, gdzie jawne tagi nadal są respektowane w trybie `"off"`. Wątki Slack ukrywają wiadomości przed kanałem, natomiast odpowiedzi Telegram pozostają widoczne w treści.
|
||||
</Note>
|
||||
|
||||
## Reakcje potwierdzenia
|
||||
@ -657,33 +657,52 @@ Kolejność rozstrzygania:
|
||||
- `channels.slack.accounts.<accountId>.ackReaction`
|
||||
- `channels.slack.ackReaction`
|
||||
- `messages.ackReaction`
|
||||
- rezerwowe emoji tożsamości agenta (`agents.list[].identity.emoji`, w przeciwnym razie "👀")
|
||||
- awaryjne emoji tożsamości agenta (`agents.list[].identity.emoji`, w przeciwnym razie "👀")
|
||||
|
||||
Uwagi:
|
||||
|
||||
- Slack oczekuje shortcode'ów (na przykład `"eyes"`).
|
||||
- Użyj `""`, aby wyłączyć reakcję dla konta Slack albo globalnie.
|
||||
- Slack oczekuje krótkich kodów (na przykład `"eyes"`).
|
||||
- Użyj `""`, aby wyłączyć reakcję dla konta Slack lub globalnie.
|
||||
|
||||
## Strumieniowanie tekstu
|
||||
|
||||
`channels.slack.streaming` kontroluje zachowanie podglądu na żywo:
|
||||
|
||||
- `off`: wyłącza strumieniowanie podglądu na żywo.
|
||||
- `partial` (domyślnie): zastępuje tekst podglądu najnowszym częściowym wynikiem.
|
||||
- `block`: dołącza fragmentaryczne aktualizacje podglądu.
|
||||
- `progress`: pokazuje tekst statusu postępu podczas generowania, a następnie wysyła tekst końcowy.
|
||||
- `streaming.preview.toolProgress`: gdy aktywny jest roboczy podgląd, kieruje aktualizacje narzędzi/postępu do tej samej edytowanej wiadomości podglądu (domyślnie: `true`). Ustaw `false`, aby zachować osobne wiadomości narzędzi/postępu.
|
||||
- `off`: wyłącz strumieniowanie podglądu na żywo.
|
||||
- `partial` (domyślnie): zastępuj tekst podglądu najnowszym częściowym wynikiem.
|
||||
- `block`: dołączaj porcjowane aktualizacje podglądu.
|
||||
- `progress`: pokazuj tekst statusu postępu podczas generowania, a następnie wyślij tekst końcowy.
|
||||
- `streaming.preview.toolProgress`: gdy podgląd roboczy jest aktywny, kieruj aktualizacje narzędzi/postępu do tej samej edytowanej wiadomości podglądu (domyślnie: `true`). Ustaw `false`, aby zachować oddzielne wiadomości narzędzi/postępu.
|
||||
- `streaming.preview.commandText` / `streaming.progress.commandText`: ustaw na `status`, aby zachować zwarte wiersze postępu narzędzi, ukrywając surowy tekst polecenia/wykonania (domyślnie: `raw`).
|
||||
|
||||
Ukryj surowy tekst polecenia/wykonania, zachowując zwarte wiersze postępu:
|
||||
|
||||
```json
|
||||
{
|
||||
"channels": {
|
||||
"slack": {
|
||||
"streaming": {
|
||||
"mode": "progress",
|
||||
"progress": {
|
||||
"toolProgress": true,
|
||||
"commandText": "status"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
`channels.slack.streaming.nativeTransport` kontroluje natywne strumieniowanie tekstu Slack, gdy `channels.slack.streaming.mode` ma wartość `partial` (domyślnie: `true`).
|
||||
|
||||
- Wątek odpowiedzi musi być dostępny, aby pojawiło się natywne strumieniowanie tekstu i status wątku asystenta Slack. Wybór wątku nadal wynika z `replyToMode`.
|
||||
- Kanały, czaty grupowe i główne korzenie DM nadal mogą używać zwykłego roboczego podglądu, gdy natywne strumieniowanie jest niedostępne albo nie istnieje wątek odpowiedzi.
|
||||
- Główne DM Slack domyślnie pozostają poza wątkiem, więc nie pokazują natywnego podglądu strumienia/statusu Slack w stylu wątku; zamiast tego OpenClaw publikuje i edytuje roboczy podgląd w DM.
|
||||
- Media i ładunki nietekstowe wracają do zwykłego dostarczania.
|
||||
- Końcowe media/błędy anulują oczekujące edycje podglądu; kwalifikujące się końcowe teksty/bloki są opróżniane tylko wtedy, gdy mogą edytować podgląd w miejscu.
|
||||
- Jeśli strumieniowanie nie powiedzie się w trakcie odpowiedzi, OpenClaw wraca do zwykłego dostarczania pozostałych ładunków.
|
||||
- Wątek odpowiedzi musi być dostępny, aby pojawiły się natywne strumieniowanie tekstu i status wątku asystenta Slack. Wybór wątku nadal przestrzega `replyToMode`.
|
||||
- Kanały, czaty grupowe i główne korzenie DM nadal mogą używać zwykłego podglądu roboczego, gdy natywne strumieniowanie jest niedostępne albo nie istnieje żaden wątek odpowiedzi.
|
||||
- Główne DM Slack domyślnie pozostają poza wątkiem, więc nie pokazują natywnego podglądu strumienia/statusu w stylu wątku Slack; OpenClaw zamiast tego publikuje i edytuje podgląd roboczy w DM.
|
||||
- Multimedia i ładunki nietekstowe przechodzą awaryjnie do zwykłego dostarczania.
|
||||
- Końcowe multimedia/błędy anulują oczekujące edycje podglądu; kwalifikujące się końcowe teksty/bloki są opróżniane tylko wtedy, gdy mogą edytować podgląd w miejscu.
|
||||
- Jeśli strumieniowanie nie powiedzie się w trakcie odpowiedzi, OpenClaw przechodzi awaryjnie do zwykłego dostarczania pozostałych ładunków.
|
||||
|
||||
Użyj roboczego podglądu zamiast natywnego strumieniowania tekstu Slack:
|
||||
Użyj podglądu roboczego zamiast natywnego strumieniowania tekstu Slack:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -700,58 +719,58 @@ Użyj roboczego podglądu zamiast natywnego strumieniowania tekstu Slack:
|
||||
|
||||
Starsze klucze:
|
||||
|
||||
- `channels.slack.streamMode` (`replace | status_final | append`) jest automatycznie migrowane do `channels.slack.streaming.mode`.
|
||||
- `channels.slack.streamMode` (`replace | status_final | append`) jest automatycznie migrowany do `channels.slack.streaming.mode`.
|
||||
- wartość logiczna `channels.slack.streaming` jest automatycznie migrowana do `channels.slack.streaming.mode` i `channels.slack.streaming.nativeTransport`.
|
||||
- starsze `channels.slack.nativeStreaming` jest automatycznie migrowane do `channels.slack.streaming.nativeTransport`.
|
||||
- starszy `channels.slack.nativeStreaming` jest automatycznie migrowany do `channels.slack.streaming.nativeTransport`.
|
||||
|
||||
## Rezerwowa reakcja pisania
|
||||
## Awaryjna reakcja pisania
|
||||
|
||||
`typingReaction` dodaje tymczasową reakcję do przychodzącej wiadomości Slack, gdy OpenClaw przetwarza odpowiedź, a następnie usuwa ją po zakończeniu uruchomienia. Jest to najbardziej przydatne poza odpowiedziami w wątkach, które używają domyślnego wskaźnika statusu „pisze...”.
|
||||
`typingReaction` dodaje tymczasową reakcję do przychodzącej wiadomości Slack, gdy OpenClaw przetwarza odpowiedź, a następnie usuwa ją po zakończeniu przebiegu. Jest to najbardziej przydatne poza odpowiedziami w wątkach, które używają domyślnego wskaźnika stanu „pisze...”.
|
||||
|
||||
Kolejność rozstrzygania:
|
||||
Kolejność rozwiązywania:
|
||||
|
||||
- `channels.slack.accounts.<accountId>.typingReaction`
|
||||
- `channels.slack.typingReaction`
|
||||
|
||||
Uwagi:
|
||||
|
||||
- Slack oczekuje skrótów (na przykład `"hourglass_flowing_sand"`).
|
||||
- Slack oczekuje shortcode'ów (na przykład `"hourglass_flowing_sand"`).
|
||||
- Reakcja działa w trybie best-effort, a czyszczenie jest podejmowane automatycznie po zakończeniu ścieżki odpowiedzi lub błędu.
|
||||
|
||||
## Multimedia, dzielenie na fragmenty i dostarczanie
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Załączniki przychodzące">
|
||||
<Accordion title="Inbound attachments">
|
||||
Załączniki plików Slack są pobierane z prywatnych adresów URL hostowanych przez Slack (przepływ żądań uwierzytelnianych tokenem) i zapisywane w magazynie multimediów, gdy pobieranie się powiedzie i pozwalają na to limity rozmiaru. Placeholdery plików zawierają Slack `fileId`, aby agenci mogli pobrać oryginalny plik za pomocą `download-file`.
|
||||
|
||||
Pobieranie używa ograniczonych limitów czasu bezczynności i całkowitego czasu. Jeśli pobieranie pliku Slack zatrzyma się lub nie powiedzie, OpenClaw kontynuuje przetwarzanie wiadomości i wraca do placeholdera pliku.
|
||||
Pobieranie używa ograniczonych timeoutów bezczynności i całkowitego czasu. Jeśli pobieranie pliku ze Slack zatrzyma się lub nie powiedzie, OpenClaw kontynuuje przetwarzanie wiadomości i wraca do placeholdera pliku.
|
||||
|
||||
Domyślny limit rozmiaru przychodzących danych w czasie wykonywania to `20MB`, chyba że zostanie zastąpiony przez `channels.slack.mediaMaxMb`.
|
||||
Domyślny limit rozmiaru przychodzących danych w czasie działania to `20MB`, chyba że zostanie nadpisany przez `channels.slack.mediaMaxMb`.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Tekst i pliki wychodzące">
|
||||
<Accordion title="Outbound text and files">
|
||||
- fragmenty tekstu używają `channels.slack.textChunkLimit` (domyślnie 4000)
|
||||
- `channels.slack.chunkMode="newline"` włącza dzielenie z pierwszeństwem akapitów
|
||||
- `channels.slack.chunkMode="newline"` włącza dzielenie najpierw według akapitów
|
||||
- wysyłanie plików używa API przesyłania Slack i może obejmować odpowiedzi w wątkach (`thread_ts`)
|
||||
- limit multimediów wychodzących stosuje `channels.slack.mediaMaxMb`, gdy jest skonfigurowany; w przeciwnym razie wysyłki kanału używają domyślnych wartości rodzaju MIME z potoku multimediów
|
||||
- limit multimediów wychodzących podąża za `channels.slack.mediaMaxMb`, gdy jest skonfigurowany; w przeciwnym razie wysyłanie kanałowe używa domyślnych wartości typu MIME z pipeline'u multimediów
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Cele dostarczania">
|
||||
<Accordion title="Delivery targets">
|
||||
Preferowane jawne cele:
|
||||
|
||||
- `user:<id>` dla DM
|
||||
- `channel:<id>` dla kanałów
|
||||
|
||||
DM Slack zawierające tylko tekst/bloki mogą publikować bezpośrednio do identyfikatorów użytkowników; przesyłanie plików i wysyłki w wątkach najpierw otwierają DM przez API konwersacji Slack, ponieważ te ścieżki wymagają konkretnego identyfikatora konwersacji.
|
||||
Slack DM zawierające tylko tekst/bloki mogą publikować bezpośrednio do identyfikatorów użytkowników; przesyłanie plików i wysyłanie w wątkach najpierw otwierają DM przez API konwersacji Slack, ponieważ te ścieżki wymagają konkretnego identyfikatora konwersacji.
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## Polecenia i zachowanie slash
|
||||
|
||||
Polecenia slash pojawiają się w Slack jako jedno skonfigurowane polecenie albo wiele poleceń natywnych. Skonfiguruj `channels.slack.slashCommand`, aby zmienić domyślne ustawienia polecenia:
|
||||
Polecenia slash pojawiają się w Slack jako pojedyncze skonfigurowane polecenie albo wiele poleceń natywnych. Skonfiguruj `channels.slack.slashCommand`, aby zmienić wartości domyślne poleceń:
|
||||
|
||||
- `enabled: false`
|
||||
- `name: "openclaw"`
|
||||
@ -762,7 +781,7 @@ Polecenia slash pojawiają się w Slack jako jedno skonfigurowane polecenie albo
|
||||
/openclaw /help
|
||||
```
|
||||
|
||||
Polecenia natywne wymagają [dodatkowych ustawień manifestu](#additional-manifest-settings) w aplikacji Slack i są włączane przez `channels.slack.commands.native: true` albo `commands.native: true` w konfiguracjach globalnych.
|
||||
Polecenia natywne wymagają [dodatkowych ustawień manifestu](#additional-manifest-settings) w aplikacji Slack i są zamiast tego włączane przez `channels.slack.commands.native: true` albo `commands.native: true` w konfiguracjach globalnych.
|
||||
|
||||
- Tryb automatyczny poleceń natywnych jest dla Slack **wyłączony**, więc `commands.native: "auto"` nie włącza natywnych poleceń Slack.
|
||||
|
||||
@ -785,7 +804,7 @@ Sesje slash używają izolowanych kluczy, takich jak `agent:<agentId>:slack:slas
|
||||
|
||||
## Odpowiedzi interaktywne
|
||||
|
||||
Slack może renderować kontrolki odpowiedzi interaktywnych tworzonych przez agenta, ale ta funkcja jest domyślnie wyłączona.
|
||||
Slack może renderować interaktywne kontrolki odpowiedzi utworzone przez agentów, ale ta funkcja jest domyślnie wyłączona.
|
||||
|
||||
Włącz ją globalnie:
|
||||
|
||||
@ -801,7 +820,7 @@ Włącz ją globalnie:
|
||||
}
|
||||
```
|
||||
|
||||
Lub włącz ją tylko dla jednego konta Slack:
|
||||
Albo włącz ją tylko dla jednego konta Slack:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -819,7 +838,7 @@ Lub włącz ją tylko dla jednego konta Slack:
|
||||
}
|
||||
```
|
||||
|
||||
Po włączeniu agenci mogą emitować dyrektywy odpowiedzi wyłącznie dla Slack:
|
||||
Po włączeniu agenci mogą emitować dyrektywy odpowiedzi tylko dla Slack:
|
||||
|
||||
- `[[slack_buttons: Approve:approve, Reject:reject]]`
|
||||
- `[[slack_select: Choose a target | Canary:canary, Production:production]]`
|
||||
@ -828,33 +847,33 @@ Te dyrektywy kompilują się do Slack Block Kit i kierują kliknięcia lub wybor
|
||||
|
||||
Uwagi:
|
||||
|
||||
- To jest interfejs specyficzny dla Slack. Inne kanały nie tłumaczą dyrektyw Slack Block Kit na własne systemy przycisków.
|
||||
- Wartości callbacków interaktywnych są nieprzezroczystymi tokenami generowanymi przez OpenClaw, a nie surowymi wartościami tworzonymi przez agenta.
|
||||
- To interfejs użytkownika specyficzny dla Slack. Inne kanały nie tłumaczą dyrektyw Slack Block Kit na własne systemy przycisków.
|
||||
- Wartości callbacków interaktywnych to nieprzezroczyste tokeny generowane przez OpenClaw, a nie surowe wartości utworzone przez agenta.
|
||||
- Jeśli wygenerowane bloki interaktywne przekroczyłyby limity Slack Block Kit, OpenClaw wraca do oryginalnej odpowiedzi tekstowej zamiast wysyłać nieprawidłowy payload bloków.
|
||||
|
||||
## Zatwierdzenia exec w Slack
|
||||
|
||||
Slack może działać jako natywny klient zatwierdzania z interaktywnymi przyciskami i interakcjami, zamiast wracać do Web UI lub terminala.
|
||||
Slack może działać jako natywny klient zatwierdzeń z interaktywnymi przyciskami i interakcjami, zamiast wracać do Web UI lub terminala.
|
||||
|
||||
- Zatwierdzenia exec używają `channels.slack.execApprovals.*` do natywnego routingu DM/kanałów.
|
||||
- Zatwierdzenia Plugin nadal mogą być rozstrzygane przez tę samą natywną powierzchnię przycisków Slack, gdy żądanie już trafia do Slack, a rodzaj identyfikatora zatwierdzenia to `plugin:`.
|
||||
- Autoryzacja zatwierdzającego jest nadal wymuszana: tylko użytkownicy zidentyfikowani jako zatwierdzający mogą zatwierdzać lub odrzucać żądania przez Slack.
|
||||
- Zatwierdzenia Plugin nadal mogą rozwiązywać się przez tę samą natywną powierzchnię przycisków Slack, gdy żądanie już trafia do Slack, a rodzaj identyfikatora zatwierdzenia to `plugin:`.
|
||||
- Autoryzacja zatwierdzającego nadal jest wymuszana: tylko użytkownicy zidentyfikowani jako zatwierdzający mogą zatwierdzać lub odrzucać żądania przez Slack.
|
||||
|
||||
Używa to tej samej współdzielonej powierzchni przycisków zatwierdzania co inne kanały. Gdy `interactivity` jest włączone w ustawieniach aplikacji Slack, monity o zatwierdzenie renderują się jako przyciski Block Kit bezpośrednio w konwersacji.
|
||||
Gdy te przyciski są obecne, stanowią podstawowy UX zatwierdzania; OpenClaw
|
||||
powinien dołączać ręczne polecenie `/approve` tylko wtedy, gdy wynik narzędzia mówi, że zatwierdzenia
|
||||
czatu są niedostępne albo ręczne zatwierdzenie jest jedyną ścieżką.
|
||||
Używa to tej samej współdzielonej powierzchni przycisków zatwierdzania co inne kanały. Gdy `interactivity` jest włączone w ustawieniach aplikacji Slack, monity zatwierdzeń renderują się jako przyciski Block Kit bezpośrednio w konwersacji.
|
||||
Gdy te przyciski są obecne, są podstawowym UX zatwierdzania; OpenClaw
|
||||
powinien dołączać ręczne polecenie `/approve` tylko wtedy, gdy wynik narzędzia mówi, że zatwierdzenia czatu
|
||||
są niedostępne albo ręczne zatwierdzenie jest jedyną ścieżką.
|
||||
|
||||
Ścieżka konfiguracji:
|
||||
|
||||
- `channels.slack.execApprovals.enabled`
|
||||
- `channels.slack.execApprovals.approvers` (opcjonalne; gdy to możliwe, wraca do `commands.ownerAllowFrom`)
|
||||
- `channels.slack.execApprovals.approvers` (opcjonalnie; wraca do `commands.ownerAllowFrom`, gdy to możliwe)
|
||||
- `channels.slack.execApprovals.target` (`dm` | `channel` | `both`, domyślnie: `dm`)
|
||||
- `agentFilter`, `sessionFilter`
|
||||
|
||||
Slack automatycznie włącza natywne zatwierdzenia exec, gdy `enabled` nie jest ustawione albo ma wartość `"auto"` i zostanie rozpoznany co najmniej jeden
|
||||
zatwierdzający. Ustaw `enabled: false`, aby jawnie wyłączyć Slack jako natywnego klienta zatwierdzania.
|
||||
Ustaw `enabled: true`, aby wymusić natywne zatwierdzenia, gdy zatwierdzający zostaną rozpoznani.
|
||||
Slack automatycznie włącza natywne zatwierdzenia exec, gdy `enabled` jest nieustawione lub `"auto"` i co najmniej jeden
|
||||
zatwierdzający zostanie rozwiązany. Ustaw `enabled: false`, aby jawnie wyłączyć Slack jako natywnego klienta zatwierdzeń.
|
||||
Ustaw `enabled: true`, aby wymusić włączenie natywnych zatwierdzeń, gdy zatwierdzający zostaną rozwiązani.
|
||||
|
||||
Domyślne zachowanie bez jawnej konfiguracji zatwierdzeń exec Slack:
|
||||
|
||||
@ -866,7 +885,7 @@ Domyślne zachowanie bez jawnej konfiguracji zatwierdzeń exec Slack:
|
||||
}
|
||||
```
|
||||
|
||||
Jawna konfiguracja natywna dla Slack jest potrzebna tylko wtedy, gdy chcesz zastąpić zatwierdzających, dodać filtry albo
|
||||
Jawna konfiguracja natywna dla Slack jest potrzebna tylko wtedy, gdy chcesz nadpisać zatwierdzających, dodać filtry albo
|
||||
włączyć dostarczanie do czatu źródłowego:
|
||||
|
||||
```json5
|
||||
@ -883,36 +902,36 @@ włączyć dostarczanie do czatu źródłowego:
|
||||
}
|
||||
```
|
||||
|
||||
Wspólne przekazywanie `approvals.exec` jest oddzielne. Używaj go tylko wtedy, gdy monity zatwierdzania exec muszą również
|
||||
trafiać do innych czatów lub jawnych celów poza pasmem. Wspólne przekazywanie `approvals.plugin` również jest
|
||||
oddzielne; natywne przyciski Slack nadal mogą rozstrzygać zatwierdzenia Plugin, gdy te żądania już trafiają
|
||||
Współdzielone przekazywanie `approvals.exec` jest oddzielne. Używaj go tylko wtedy, gdy monity zatwierdzeń exec muszą także
|
||||
trafiać do innych czatów lub jawnych celów poza pasmem. Współdzielone przekazywanie `approvals.plugin` również jest
|
||||
oddzielne; natywne przyciski Slack nadal mogą rozwiązywać zatwierdzenia Plugin, gdy te żądania już trafiają
|
||||
do Slack.
|
||||
|
||||
`/approve` w tym samym czacie działa również w kanałach Slack i DM, które już obsługują polecenia. Zobacz [Zatwierdzenia exec](/pl/tools/exec-approvals), aby poznać pełny model przekazywania zatwierdzeń.
|
||||
`/approve` w tym samym czacie działa także w kanałach Slack i DM, które już obsługują polecenia. Zobacz [zatwierdzenia exec](/pl/tools/exec-approvals), aby poznać pełny model przekazywania zatwierdzeń.
|
||||
|
||||
## Zdarzenia i zachowanie operacyjne
|
||||
|
||||
- Edycje/usunięcia wiadomości są mapowane na zdarzenia systemowe.
|
||||
- Transmisje wątków (odpowiedzi w wątku z opcją „Wyślij również do kanału”) są przetwarzane jak zwykłe wiadomości użytkownika.
|
||||
- Rozgłaszanie wątków (odpowiedzi w wątku „Wyślij także do kanału”) jest przetwarzane jak zwykłe wiadomości użytkowników.
|
||||
- Zdarzenia dodania/usunięcia reakcji są mapowane na zdarzenia systemowe.
|
||||
- Zdarzenia dołączenia/opuszczenia przez członka, utworzenia/zmiany nazwy kanału oraz dodania/usunięcia przypięcia są mapowane na zdarzenia systemowe.
|
||||
- `channel_id_changed` może migrować klucze konfiguracji kanału, gdy `configWrites` jest włączone.
|
||||
- Metadane tematu/celu kanału są traktowane jako niezaufany kontekst i mogą zostać wstrzyknięte do kontekstu routingu.
|
||||
- Inicjator wątku i początkowe zasilanie kontekstu historii wątku są filtrowane przez skonfigurowane listy dozwolonych nadawców, gdy ma to zastosowanie.
|
||||
- Inicjator wątku i początkowe zasilenie kontekstu historią wątku są filtrowane według skonfigurowanych allowlist nadawców, gdy ma to zastosowanie.
|
||||
- Akcje bloków i interakcje modalne emitują strukturalne zdarzenia systemowe `Slack interaction: ...` z bogatymi polami payloadu:
|
||||
- akcje bloków: wybrane wartości, etykiety, wartości selektorów i metadane `workflow_*`
|
||||
- zdarzenia modalne `view_submission` i `view_closed` z metadanymi routowanego kanału oraz danymi wejściowymi formularza
|
||||
- akcje bloków: wybrane wartości, etykiety, wartości pickerów i metadane `workflow_*`
|
||||
- zdarzenia modalne `view_submission` i `view_closed` z routowanymi metadanymi kanału oraz danymi formularzy
|
||||
|
||||
## Odniesienie konfiguracji
|
||||
## Dokumentacja konfiguracji
|
||||
|
||||
Podstawowe odniesienie: [Odniesienie konfiguracji - Slack](/pl/gateway/config-channels#slack).
|
||||
Główne odniesienie: [Dokumentacja konfiguracji - Slack](/pl/gateway/config-channels#slack).
|
||||
|
||||
<Accordion title="Pola Slack o wysokiej wartości sygnału">
|
||||
<Accordion title="High-signal Slack fields">
|
||||
|
||||
- tryb/uwierzytelnianie: `mode`, `botToken`, `appToken`, `signingSecret`, `webhookPath`, `accounts.*`
|
||||
- dostęp do DM: `dm.enabled`, `dmPolicy`, `allowFrom` (starsze: `dm.policy`, `dm.allowFrom`), `dm.groupEnabled`, `dm.groupChannels`
|
||||
- przełącznik zgodności: `dangerouslyAllowNameMatching` (awaryjny; pozostaw wyłączony, chyba że jest potrzebny)
|
||||
- dostęp do kanału: `groupPolicy`, `channels.*`, `channels.*.users`, `channels.*.requireMention`
|
||||
- dostęp DM: `dm.enabled`, `dmPolicy`, `allowFrom` (legacy: `dm.policy`, `dm.allowFrom`), `dm.groupEnabled`, `dm.groupChannels`
|
||||
- przełącznik zgodności: `dangerouslyAllowNameMatching` (break-glass; pozostaw wyłączone, chyba że jest potrzebne)
|
||||
- dostęp kanału: `groupPolicy`, `channels.*`, `channels.*.users`, `channels.*.requireMention`
|
||||
- wątki/historia: `replyToMode`, `replyToModeByChatType`, `thread.*`, `historyLimit`, `dmHistoryLimit`, `dms.*.historyLimit`
|
||||
- dostarczanie: `textChunkLimit`, `chunkMode`, `mediaMaxMb`, `streaming`, `streaming.nativeTransport`, `streaming.preview.toolProgress`
|
||||
- operacje/funkcje: `configWrites`, `commands.native`, `slashCommand.*`, `actions.*`, `userToken`, `userTokenReadOnly`
|
||||
@ -922,13 +941,13 @@ Podstawowe odniesienie: [Odniesienie konfiguracji - Slack](/pl/gateway/config-ch
|
||||
## Rozwiązywanie problemów
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Brak odpowiedzi w kanałach">
|
||||
Sprawdź kolejno:
|
||||
<Accordion title="No replies in channels">
|
||||
Sprawdź po kolei:
|
||||
|
||||
- `groupPolicy`
|
||||
- lista dozwolonych kanałów (`channels.slack.channels`) — **klucze muszą być identyfikatorami kanałów** (`C12345678`), nie nazwami (`#channel-name`). Klucze oparte na nazwach po cichu zawodzą przy `groupPolicy: "allowlist"`, ponieważ routing kanałów domyślnie najpierw używa identyfikatorów. Aby znaleźć identyfikator: kliknij kanał w Slack prawym przyciskiem → **Kopiuj link** — wartość `C...` na końcu URL to identyfikator kanału.
|
||||
- allowlist kanałów (`channels.slack.channels`) — **klucze muszą być identyfikatorami kanałów** (`C12345678`), a nie nazwami (`#channel-name`). Klucze oparte na nazwach po cichu zawodzą przy `groupPolicy: "allowlist"`, ponieważ routing kanałów jest domyślnie najpierw oparty na identyfikatorze. Aby znaleźć identyfikator: kliknij kanał w Slack prawym przyciskiem myszy → **Copy link** — wartość `C...` na końcu adresu URL to identyfikator kanału.
|
||||
- `requireMention`
|
||||
- lista dozwolonych `users` dla kanału
|
||||
- allowlist `users` dla kanału
|
||||
|
||||
Przydatne polecenia:
|
||||
|
||||
@ -940,15 +959,15 @@ openclaw doctor
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Wiadomości DM ignorowane">
|
||||
<Accordion title="DM messages ignored">
|
||||
Sprawdź:
|
||||
|
||||
- `channels.slack.dm.enabled`
|
||||
- `channels.slack.dmPolicy` (albo starsze `channels.slack.dm.policy`)
|
||||
- zatwierdzenia parowania / wpisy listy dozwolonych
|
||||
- `channels.slack.dmPolicy` (albo legacy `channels.slack.dm.policy`)
|
||||
- zatwierdzenia parowania / wpisy allowlist
|
||||
- zdarzenia DM Slack Assistant: szczegółowe logi wspominające `drop message_changed`
|
||||
zwykle oznaczają, że Slack wysłał zdarzenie edytowanego wątku Assistant bez
|
||||
możliwego do odzyskania nadawcy-człowieka w metadanych wiadomości
|
||||
zwykle oznaczają, że Slack wysłał edytowane zdarzenie wątku Assistant bez
|
||||
możliwego do odzyskania ludzkiego nadawcy w metadanych wiadomości
|
||||
|
||||
```bash
|
||||
openclaw pairing list slack
|
||||
@ -956,125 +975,125 @@ openclaw pairing list slack
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Socket mode nie łączy się">
|
||||
<Accordion title="Socket mode not connecting">
|
||||
Zweryfikuj tokeny bota i aplikacji oraz włączenie Socket Mode w ustawieniach aplikacji Slack.
|
||||
|
||||
Jeśli `openclaw channels status --probe --json` pokazuje `botTokenStatus` lub
|
||||
Jeśli `openclaw channels status --probe --json` pokazuje `botTokenStatus` albo
|
||||
`appTokenStatus: "configured_unavailable"`, konto Slack jest
|
||||
skonfigurowane, ale bieżące środowisko uruchomieniowe nie mogło rozpoznać wartości
|
||||
skonfigurowane, ale bieżący runtime nie mógł rozwiązać wartości
|
||||
opartej na SecretRef.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Tryb HTTP nie odbiera zdarzeń">
|
||||
<Accordion title="HTTP mode not receiving events">
|
||||
Zweryfikuj:
|
||||
|
||||
- sekret podpisywania
|
||||
- signing secret
|
||||
- ścieżkę Webhook
|
||||
- adresy Slack Request URLs (Events + Interactivity + Slash Commands)
|
||||
- adresy URL żądań Slack (zdarzenia + interaktywność + polecenia slash)
|
||||
- unikalny `webhookPath` dla każdego konta HTTP
|
||||
|
||||
Jeśli `signingSecretStatus: "configured_unavailable"` pojawia się w migawkach
|
||||
konta, konto HTTP jest skonfigurowane, ale bieżące środowisko uruchomieniowe nie mogło
|
||||
rozpoznać sekretu podpisywania opartego na SecretRef.
|
||||
Jeśli `signingSecretStatus: "configured_unavailable"` pojawia się w snapshotach
|
||||
kont, konto HTTP jest skonfigurowane, ale bieżący runtime nie mógł
|
||||
rozwiązać signing secret opartego na SecretRef.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Polecenia natywne/slash nie uruchamiają się">
|
||||
Sprawdź, czy zamierzonym trybem był:
|
||||
<Accordion title="Native/slash commands not firing">
|
||||
Sprawdź, czy zamierzony był:
|
||||
|
||||
- tryb poleceń natywnych (`channels.slack.commands.native: true`) z pasującymi poleceniami slash zarejestrowanymi w Slack
|
||||
- albo tryb pojedynczego polecenia slash (`channels.slack.slashCommand.enabled: true`)
|
||||
|
||||
Sprawdź też `commands.useAccessGroups` oraz listy dozwolonych kanałów/użytkowników.
|
||||
Sprawdź także `commands.useAccessGroups` oraz allowlisty kanałów/użytkowników.
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## Odniesienie do wizji załączników
|
||||
## Odniesienie do wizji dla załączników
|
||||
|
||||
Slack może dołączyć pobrane multimedia do tury agenta, gdy pobieranie plików Slack się powiedzie i pozwalają na to limity rozmiaru. Pliki obrazów mogą zostać przekazane przez ścieżkę rozumienia multimediów albo bezpośrednio do modelu odpowiedzi obsługującego wizję; inne pliki są zachowywane jako kontekst pliku do pobrania, a nie traktowane jako wejście obrazu.
|
||||
Slack może dołączyć pobrane multimedia do tury agenta, gdy pobieranie plików Slack się powiedzie i pozwalają na to limity rozmiaru. Pliki obrazów mogą być przekazywane przez ścieżkę rozumienia multimediów albo bezpośrednio do modelu odpowiedzi obsługującego wizję; inne pliki są zachowywane jako kontekst plików do pobrania, a nie traktowane jako wejście obrazu.
|
||||
|
||||
### Obsługiwane typy multimediów
|
||||
|
||||
| Typ multimediów | Źródło | Bieżące zachowanie | Uwagi |
|
||||
| -------------------------------- | -------------------------- | -------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
|
||||
| Obrazy JPEG / PNG / GIF / WebP | URL pliku Slack | Pobierane i dołączane do tury w celu obsługi przez mechanizmy obsługujące analizę obrazu | Limit na plik: `channels.slack.mediaMaxMb` (domyślnie 20 MB) |
|
||||
| Pliki PDF | URL pliku Slack | Pobierane i udostępniane jako kontekst pliku dla narzędzi takich jak `download-file` lub `pdf` | Dane przychodzące Slack nie konwertują automatycznie plików PDF na dane wejściowe analizy obrazu |
|
||||
| Inne pliki | URL pliku Slack | Pobierane, gdy to możliwe, i udostępniane jako kontekst pliku | Pliki binarne nie są traktowane jako dane wejściowe obrazu |
|
||||
| Odpowiedzi w wątku | Pliki wiadomości początkowej wątku | Pliki wiadomości głównej mogą zostać dołączone jako kontekst, gdy odpowiedź nie ma bezpośrednich multimediów | Wiadomości początkowe zawierające tylko pliki używają symbolu zastępczego załącznika |
|
||||
| Wiadomości z wieloma obrazami | Wiele plików Slack | Każdy plik jest oceniany niezależnie | Przetwarzanie Slack jest ograniczone do ośmiu plików na wiadomość |
|
||||
| Typ multimediów | Źródło | Obecne zachowanie | Uwagi |
|
||||
| ------------------------------- | ---------------------------- | ---------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
|
||||
| Obrazy JPEG / PNG / GIF / WebP | Adres URL pliku Slack | Pobierane i dołączane do tury na potrzeby obsługi z użyciem obrazu | Limit na plik: `channels.slack.mediaMaxMb` (domyślnie 20 MB) |
|
||||
| Pliki PDF | Adres URL pliku Slack | Pobierane i udostępniane jako kontekst pliku dla narzędzi takich jak `download-file` lub `pdf` | Przychodzące wiadomości Slack nie konwertują automatycznie PDF-ów na wejście obrazu |
|
||||
| Inne pliki | Adres URL pliku Slack | Pobierane, gdy to możliwe, i udostępniane jako kontekst pliku | Pliki binarne nie są traktowane jako wejście obrazu |
|
||||
| Odpowiedzi w wątku | Pliki wiadomości rozpoczynającej wątek | Pliki wiadomości głównej mogą zostać wczytane jako kontekst, gdy odpowiedź nie ma bezpośrednich multimediów | Wiadomości rozpoczynające zawierające tylko pliki używają zastępczego załącznika |
|
||||
| Wiadomości z wieloma obrazami | Wiele plików Slack | Każdy plik jest oceniany niezależnie | Przetwarzanie Slack jest ograniczone do ośmiu plików na wiadomość |
|
||||
|
||||
### Potok przychodzący
|
||||
|
||||
Gdy przychodzi wiadomość Slack z załącznikami plików:
|
||||
|
||||
1. OpenClaw pobiera plik z prywatnego URL Slack przy użyciu tokena bota (`xoxb-...`).
|
||||
1. OpenClaw pobiera plik z prywatnego adresu URL Slack przy użyciu tokenu bota (`xoxb-...`).
|
||||
2. Po powodzeniu plik jest zapisywany w magazynie multimediów.
|
||||
3. Ścieżki pobranych multimediów i typy zawartości są dodawane do kontekstu przychodzącego.
|
||||
4. Ścieżki modeli/narzędzi obsługujące obrazy mogą używać załączników obrazów z tego kontekstu.
|
||||
5. Pliki niebędące obrazami pozostają dostępne jako metadane plików lub odwołania do multimediów dla narzędzi, które potrafią je obsłużyć.
|
||||
3. Pobrane ścieżki multimediów i typy treści są dodawane do kontekstu przychodzącego.
|
||||
4. Ścieżki modelu/narzędzia obsługujące obrazy mogą używać załączników obrazów z tego kontekstu.
|
||||
5. Pliki niebędące obrazami pozostają dostępne jako metadane pliku lub odwołania do multimediów dla narzędzi, które potrafią je obsłużyć.
|
||||
|
||||
### Dziedziczenie załączników z początku wątku
|
||||
### Dziedziczenie załączników z głównej wiadomości wątku
|
||||
|
||||
Gdy wiadomość przychodzi w wątku (ma element nadrzędny `thread_ts`):
|
||||
Gdy wiadomość przychodzi w wątku (ma nadrzędne `thread_ts`):
|
||||
|
||||
- Jeśli sama odpowiedź nie ma bezpośrednich multimediów, a dołączona wiadomość główna ma pliki, Slack może dołączyć pliki główne jako kontekst wiadomości początkowej wątku.
|
||||
- Jeśli sama odpowiedź nie ma bezpośrednich multimediów, a dołączona wiadomość główna ma pliki, Slack może wczytać pliki główne jako kontekst wiadomości rozpoczynającej wątek.
|
||||
- Bezpośrednie załączniki odpowiedzi mają pierwszeństwo przed załącznikami wiadomości głównej.
|
||||
- Wiadomość główna, która ma tylko pliki i nie ma tekstu, jest reprezentowana przez symbol zastępczy załącznika, aby mechanizm awaryjny nadal mógł uwzględnić jej pliki.
|
||||
- Wiadomość główna, która ma tylko pliki i nie ma tekstu, jest reprezentowana przez zastępczy załącznik, aby mechanizm awaryjny nadal mógł uwzględnić jej pliki.
|
||||
|
||||
### Obsługa wielu załączników
|
||||
|
||||
Gdy pojedyncza wiadomość Slack zawiera wiele załączników plików:
|
||||
|
||||
- Każdy załącznik jest przetwarzany niezależnie przez potok multimediów.
|
||||
- Odwołania do pobranych multimediów są agregowane w kontekście wiadomości.
|
||||
- Pobrane odwołania do multimediów są agregowane w kontekście wiadomości.
|
||||
- Kolejność przetwarzania odpowiada kolejności plików Slack w ładunku zdarzenia.
|
||||
- Niepowodzenie pobierania jednego załącznika nie blokuje innych.
|
||||
- Niepowodzenie pobierania jednego załącznika nie blokuje pozostałych.
|
||||
|
||||
### Limity rozmiaru, pobierania i modelu
|
||||
|
||||
- **Limit rozmiaru**: Domyślnie 20 MB na plik. Konfigurowalne przez `channels.slack.mediaMaxMb`.
|
||||
- **Niepowodzenia pobierania**: Pliki, których Slack nie może udostępnić, wygasłe URL-e, niedostępne pliki, pliki przekraczające limit rozmiaru oraz odpowiedzi HTML autoryzacji/logowania Slack są pomijane zamiast zgłaszania ich jako nieobsługiwanych formatów.
|
||||
- **Model wizyjny**: Analiza obrazu używa aktywnego modelu odpowiedzi, gdy obsługuje analizę obrazu, albo modelu obrazu skonfigurowanego w `agents.defaults.imageModel`.
|
||||
- **Limit rozmiaru**: Domyślnie 20 MB na plik. Konfigurowalny przez `channels.slack.mediaMaxMb`.
|
||||
- **Niepowodzenia pobierania**: Pliki, których Slack nie może udostępnić, wygasłe adresy URL, niedostępne pliki, zbyt duże pliki oraz odpowiedzi HTML uwierzytelniania/logowania Slack są pomijane zamiast zgłaszania ich jako nieobsługiwanych formatów.
|
||||
- **Model obrazu**: Analiza obrazów używa aktywnego modelu odpowiedzi, gdy obsługuje obraz, albo modelu obrazu skonfigurowanego w `agents.defaults.imageModel`.
|
||||
|
||||
### Znane ograniczenia
|
||||
|
||||
| Scenariusz | Bieżące zachowanie | Obejście |
|
||||
| --------------------------------------- | ------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
|
||||
| Wygasły URL pliku Slack | Plik pominięty; nie jest wyświetlany żaden błąd | Prześlij plik ponownie w Slack |
|
||||
| Model wizyjny nie jest skonfigurowany | Załączniki obrazów są przechowywane jako odwołania do multimediów, ale nie są analizowane jako obrazy | Skonfiguruj `agents.defaults.imageModel` albo użyj modelu odpowiedzi obsługującego analizę obrazu |
|
||||
| Bardzo duże obrazy (> 20 MB domyślnie) | Pomijane zgodnie z limitem rozmiaru | Zwiększ `channels.slack.mediaMaxMb`, jeśli Slack na to pozwala |
|
||||
| Przekazane/udostępnione załączniki | Tekst oraz multimedia obrazów/plików hostowane przez Slack są obsługiwane na zasadzie best-effort | Udostępnij ponownie bezpośrednio w wątku OpenClaw |
|
||||
| Załączniki PDF | Przechowywane jako kontekst pliku/multimediów, nie są automatycznie kierowane przez analizę obrazu | Użyj `download-file` do metadanych pliku albo narzędzia `pdf` do analizy PDF |
|
||||
| Scenariusz | Obecne zachowanie | Obejście |
|
||||
| --------------------------------------- | ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
|
||||
| Wygasły adres URL pliku Slack | Plik pominięty; nie jest wyświetlany żaden błąd | Prześlij plik ponownie w Slack |
|
||||
| Model obrazu nie jest skonfigurowany | Załączniki obrazów są przechowywane jako odwołania do multimediów, ale nie są analizowane jako obrazy | Skonfiguruj `agents.defaults.imageModel` albo użyj modelu odpowiedzi obsługującego obraz |
|
||||
| Bardzo duże obrazy (> 20 MB domyślnie) | Pomijane zgodnie z limitem rozmiaru | Zwiększ `channels.slack.mediaMaxMb`, jeśli Slack na to pozwala |
|
||||
| Przekazane/udostępnione załączniki | Tekst oraz multimedia obrazów/plików hostowane przez Slack są obsługiwane w trybie najlepszych starań | Udostępnij ponownie bezpośrednio w wątku OpenClaw |
|
||||
| Załączniki PDF | Przechowywane jako kontekst pliku/multimediów, nie są automatycznie kierowane przez analizę obrazu | Użyj `download-file` dla metadanych pliku albo narzędzia `pdf` do analizy PDF |
|
||||
|
||||
### Powiązana dokumentacja
|
||||
|
||||
- [Potok rozumienia multimediów](/pl/nodes/media-understanding)
|
||||
- [Narzędzie PDF](/pl/tools/pdf)
|
||||
- Epik: [#51349](https://github.com/openclaw/openclaw/issues/51349) — włączenie analizy obrazu załączników Slack
|
||||
- Epik: [#51349](https://github.com/openclaw/openclaw/issues/51349) — włączenie obsługi obrazów z załączników Slack
|
||||
- Testy regresji: [#51353](https://github.com/openclaw/openclaw/issues/51353)
|
||||
- Weryfikacja na żywo: [#51354](https://github.com/openclaw/openclaw/issues/51354)
|
||||
|
||||
## Powiązane
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Parowanie" icon="link" href="/pl/channels/pairing">
|
||||
<Card title="Pairing" icon="link" href="/pl/channels/pairing">
|
||||
Sparuj użytkownika Slack z Gateway.
|
||||
</Card>
|
||||
<Card title="Grupy" icon="users" href="/pl/channels/groups">
|
||||
Zachowanie kanału i grupowych DM.
|
||||
<Card title="Groups" icon="users" href="/pl/channels/groups">
|
||||
Zachowanie kanałów i grupowych wiadomości bezpośrednich.
|
||||
</Card>
|
||||
<Card title="Routing kanałów" icon="route" href="/pl/channels/channel-routing">
|
||||
<Card title="Channel routing" icon="route" href="/pl/channels/channel-routing">
|
||||
Kieruj wiadomości przychodzące do agentów.
|
||||
</Card>
|
||||
<Card title="Bezpieczeństwo" icon="shield" href="/pl/gateway/security">
|
||||
Model zagrożeń i wzmacnianie zabezpieczeń.
|
||||
<Card title="Security" icon="shield" href="/pl/gateway/security">
|
||||
Model zagrożeń i utwardzanie.
|
||||
</Card>
|
||||
<Card title="Konfiguracja" icon="sliders" href="/pl/gateway/configuration">
|
||||
<Card title="Configuration" icon="sliders" href="/pl/gateway/configuration">
|
||||
Układ konfiguracji i priorytety.
|
||||
</Card>
|
||||
<Card title="Polecenia ukośnikiem" icon="terminal" href="/pl/tools/slash-commands">
|
||||
<Card title="Slash commands" icon="terminal" href="/pl/tools/slash-commands">
|
||||
Katalog poleceń i zachowanie.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
@ -1,28 +1,28 @@
|
||||
---
|
||||
read_when:
|
||||
- Praca nad funkcjami Telegrama lub Webhookami
|
||||
summary: Stan obsługi bota Telegram, możliwości i konfiguracja
|
||||
- Praca nad funkcjami Telegram lub Webhookami
|
||||
summary: Status obsługi bota Telegram, możliwości i konfiguracja
|
||||
title: Telegram
|
||||
x-i18n:
|
||||
generated_at: "2026-05-03T21:27:22Z"
|
||||
generated_at: "2026-05-04T07:02:39Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 528ace9dae29eda22f98cc1436ec16146eb9d83edc73aa6db1ab8283f4f873c0
|
||||
source_hash: 6ef1b019a6a0e261b33972b5edffaedd29310b1333d112bade2e79e9d56887c6
|
||||
source_path: channels/telegram.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
Gotowe do użycia produkcyjnego dla wiadomości prywatnych botów i grup przez grammY. Domyślnym trybem jest długie odpytywanie; tryb Webhook jest opcjonalny.
|
||||
Gotowe do użycia produkcyjnego dla wiadomości prywatnych botów i grup za pomocą grammY. Domyślnym trybem jest długie odpytywanie; tryb Webhook jest opcjonalny.
|
||||
|
||||
<CardGroup cols={3}>
|
||||
<Card title="Parowanie" icon="link" href="/pl/channels/pairing">
|
||||
Domyślną zasadą wiadomości prywatnych dla Telegram jest parowanie.
|
||||
Domyślną polityką wiadomości prywatnych dla Telegram jest parowanie.
|
||||
</Card>
|
||||
<Card title="Rozwiązywanie problemów z kanałami" icon="wrench" href="/pl/channels/troubleshooting">
|
||||
Diagnostyka międzykanałowa i procedury naprawcze.
|
||||
</Card>
|
||||
<Card title="Konfiguracja Gateway" icon="settings" href="/pl/gateway/configuration">
|
||||
Pełne wzorce konfiguracji kanałów i przykłady.
|
||||
Pełne wzorce i przykłady konfiguracji kanałów.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
@ -30,13 +30,13 @@ Gotowe do użycia produkcyjnego dla wiadomości prywatnych botów i grup przez g
|
||||
|
||||
<Steps>
|
||||
<Step title="Utwórz token bota w BotFather">
|
||||
Otwórz Telegram i porozmawiaj z **@BotFather** (upewnij się, że nazwa użytkownika to dokładnie `@BotFather`).
|
||||
Otwórz Telegram i porozmawiaj z **@BotFather** (upewnij się, że nazwa to dokładnie `@BotFather`).
|
||||
|
||||
Uruchom `/newbot`, postępuj zgodnie z instrukcjami i zapisz token.
|
||||
Uruchom `/newbot`, wykonaj instrukcje i zapisz token.
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Skonfiguruj token i zasadę wiadomości prywatnych">
|
||||
<Step title="Skonfiguruj token i politykę wiadomości prywatnych">
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -51,8 +51,8 @@ Gotowe do użycia produkcyjnego dla wiadomości prywatnych botów i grup przez g
|
||||
}
|
||||
```
|
||||
|
||||
Zapasowe źródło z env: `TELEGRAM_BOT_TOKEN=...` (tylko konto domyślne).
|
||||
Telegram **nie** używa `openclaw channels login telegram`; skonfiguruj token w konfiguracji/env, a potem uruchom gateway.
|
||||
Zapasowa zmienna środowiskowa: `TELEGRAM_BOT_TOKEN=...` (tylko konto domyślne).
|
||||
Telegram **nie** używa `openclaw channels login telegram`; skonfiguruj token w konfiguracji/środowisku, a następnie uruchom gateway.
|
||||
|
||||
</Step>
|
||||
|
||||
@ -69,24 +69,24 @@ openclaw pairing approve telegram <CODE>
|
||||
</Step>
|
||||
|
||||
<Step title="Dodaj bota do grupy">
|
||||
Dodaj bota do swojej grupy, a następnie ustaw `channels.telegram.groups` i `groupPolicy`, aby odpowiadały Twojemu modelowi dostępu.
|
||||
Dodaj bota do swojej grupy, a następnie ustaw `channels.telegram.groups` i `groupPolicy` zgodnie ze swoim modelem dostępu.
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
<Note>
|
||||
Kolejność rozwiązywania tokenów uwzględnia konta. W praktyce wartości z konfiguracji mają pierwszeństwo przed zapasowym env, a `TELEGRAM_BOT_TOKEN` ma zastosowanie tylko do konta domyślnego.
|
||||
Kolejność rozwiązywania tokena uwzględnia konto. W praktyce wartości z konfiguracji mają pierwszeństwo przed zapasową zmienną środowiskową, a `TELEGRAM_BOT_TOKEN` dotyczy tylko konta domyślnego.
|
||||
</Note>
|
||||
|
||||
## Ustawienia po stronie Telegram
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Tryb prywatności i widoczność grup">
|
||||
Boty Telegram domyślnie używają **trybu prywatności**, który ogranicza wiadomości grupowe, jakie otrzymują.
|
||||
Boty Telegram domyślnie używają **trybu prywatności**, który ogranicza wiadomości grupowe otrzymywane przez bota.
|
||||
|
||||
Jeśli bot musi widzieć wszystkie wiadomości grupowe, wykonaj jedno z tych działań:
|
||||
Jeśli bot musi widzieć wszystkie wiadomości grupowe:
|
||||
|
||||
- wyłącz tryb prywatności przez `/setprivacy`, albo
|
||||
- ustaw bota jako administratora grupy.
|
||||
- wyłącz tryb prywatności za pomocą `/setprivacy`, albo
|
||||
- nadaj botowi uprawnienia administratora grupy.
|
||||
|
||||
Po przełączeniu trybu prywatności usuń i ponownie dodaj bota w każdej grupie, aby Telegram zastosował zmianę.
|
||||
|
||||
@ -95,13 +95,13 @@ Kolejność rozwiązywania tokenów uwzględnia konta. W praktyce wartości z ko
|
||||
<Accordion title="Uprawnienia grupy">
|
||||
Status administratora jest kontrolowany w ustawieniach grupy Telegram.
|
||||
|
||||
Boty administracyjne otrzymują wszystkie wiadomości grupowe, co jest przydatne przy stale aktywnym działaniu w grupie.
|
||||
Boty administracyjne otrzymują wszystkie wiadomości grupowe, co jest przydatne dla stale aktywnego działania w grupie.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Przydatne przełączniki BotFather">
|
||||
|
||||
- `/setjoingroups`, aby zezwolić na dodawanie do grup lub go zabronić
|
||||
- `/setjoingroups`, aby zezwolić na dodawanie do grup lub je zablokować
|
||||
- `/setprivacy` dla zachowania widoczności w grupach
|
||||
|
||||
</Accordion>
|
||||
@ -110,31 +110,31 @@ Kolejność rozwiązywania tokenów uwzględnia konta. W praktyce wartości z ko
|
||||
## Kontrola dostępu i aktywacja
|
||||
|
||||
<Tabs>
|
||||
<Tab title="Zasada wiadomości prywatnych">
|
||||
`channels.telegram.dmPolicy` kontroluje dostęp przez wiadomości prywatne:
|
||||
<Tab title="Polityka wiadomości prywatnych">
|
||||
`channels.telegram.dmPolicy` kontroluje dostęp do wiadomości bezpośrednich:
|
||||
|
||||
- `pairing` (domyślnie)
|
||||
- `pairing` (domyślne)
|
||||
- `allowlist` (wymaga co najmniej jednego ID nadawcy w `allowFrom`)
|
||||
- `open` (wymaga, aby `allowFrom` zawierało `"*"`)
|
||||
- `disabled`
|
||||
|
||||
`dmPolicy: "open"` z `allowFrom: ["*"]` pozwala każdemu kontu Telegram, które znajdzie lub odgadnie nazwę użytkownika bota, wydawać botowi polecenia. Używaj tego tylko dla celowo publicznych botów z ściśle ograniczonymi narzędziami; boty jednego właściciela powinny używać `allowlist` z numerycznymi identyfikatorami użytkowników.
|
||||
`dmPolicy: "open"` z `allowFrom: ["*"]` pozwala każdemu kontu Telegram, które znajdzie lub odgadnie nazwę użytkownika bota, wydawać polecenia botowi. Używaj tego tylko dla celowo publicznych botów z mocno ograniczonymi narzędziami; boty z jednym właścicielem powinny używać `allowlist` z numerycznymi ID użytkowników.
|
||||
|
||||
`channels.telegram.allowFrom` przyjmuje numeryczne identyfikatory użytkowników Telegram. Prefiksy `telegram:` / `tg:` są akceptowane i normalizowane.
|
||||
W konfiguracjach wielokontowych restrykcyjne `channels.telegram.allowFrom` najwyższego poziomu jest traktowane jako granica bezpieczeństwa: wpisy `allowFrom: ["*"]` na poziomie konta nie czynią tego konta publicznym, chyba że efektywna allowlista konta po scaleniu nadal zawiera jawny wildcard.
|
||||
`channels.telegram.allowFrom` przyjmuje numeryczne ID użytkowników Telegram. Prefiksy `telegram:` / `tg:` są akceptowane i normalizowane.
|
||||
W konfiguracjach wielokontowych restrykcyjne `channels.telegram.allowFrom` najwyższego poziomu jest traktowane jako granica bezpieczeństwa: wpisy `allowFrom: ["*"]` na poziomie konta nie czynią tego konta publicznym, chyba że efektywna lista dozwolonych kont po scaleniu nadal zawiera jawny symbol wieloznaczny.
|
||||
`dmPolicy: "allowlist"` z pustym `allowFrom` blokuje wszystkie wiadomości prywatne i jest odrzucane przez walidację konfiguracji.
|
||||
Konfiguracja prosi wyłącznie o numeryczne identyfikatory użytkowników.
|
||||
Jeśli po aktualizacji Twoja konfiguracja zawiera wpisy allowlist w postaci `@username`, uruchom `openclaw doctor --fix`, aby je rozwiązać (best-effort; wymaga tokena bota Telegram).
|
||||
Jeśli wcześniej polegano na plikach allowlist magazynu parowania, `openclaw doctor --fix` może odzyskać wpisy do `channels.telegram.allowFrom` w przepływach allowlist (na przykład gdy `dmPolicy: "allowlist"` nie ma jeszcze jawnych identyfikatorów).
|
||||
Konfiguracja prosi wyłącznie o numeryczne ID użytkowników.
|
||||
Jeśli wykonano aktualizację i konfiguracja zawiera wpisy listy dozwolonych w formacie `@username`, uruchom `openclaw doctor --fix`, aby je rozwiązać (w miarę możliwości; wymaga tokena bota Telegram).
|
||||
Jeśli wcześniej używano plików listy dozwolonych z magazynu parowania, `openclaw doctor --fix` może odzyskać wpisy do `channels.telegram.allowFrom` w przepływach z listą dozwolonych (na przykład gdy `dmPolicy: "allowlist"` nie ma jeszcze jawnych ID).
|
||||
|
||||
W przypadku botów jednego właściciela preferuj `dmPolicy: "allowlist"` z jawnymi numerycznymi ID `allowFrom`, aby polityka dostępu była trwała w konfiguracji (zamiast zależeć od wcześniejszych zatwierdzeń parowania).
|
||||
Dla botów z jednym właścicielem preferuj `dmPolicy: "allowlist"` z jawnymi numerycznymi ID `allowFrom`, aby polityka dostępu była trwale zapisana w konfiguracji (zamiast zależeć od wcześniejszych zatwierdzeń parowania).
|
||||
|
||||
Częste nieporozumienie: zatwierdzenie parowania wiadomości prywatnych nie oznacza „ten nadawca jest autoryzowany wszędzie”.
|
||||
Parowanie przyznaje dostęp przez wiadomości prywatne. Jeśli właściciel poleceń jeszcze nie istnieje, pierwsze zatwierdzone parowanie ustawia także `commands.ownerAllowFrom`, aby polecenia tylko dla właściciela i zatwierdzenia exec miały jawne konto operatora.
|
||||
Autoryzacja nadawców w grupie nadal pochodzi z jawnych allowlist w konfiguracji.
|
||||
Jeśli chcesz, aby „jestem autoryzowany raz i działają zarówno wiadomości prywatne, jak i polecenia grupowe”, umieść swój numeryczny identyfikator użytkownika Telegram w `channels.telegram.allowFrom`; dla poleceń tylko dla właściciela upewnij się, że `commands.ownerAllowFrom` zawiera `telegram:<your user id>`.
|
||||
Parowanie przyznaje dostęp do wiadomości prywatnych. Jeśli nie ma jeszcze właściciela poleceń, pierwsze zatwierdzone parowanie ustawia również `commands.ownerAllowFrom`, aby polecenia tylko dla właściciela i zatwierdzenia wykonywania miały jawne konto operatora.
|
||||
Autoryzacja nadawcy w grupie nadal pochodzi z jawnych list dozwolonych w konfiguracji.
|
||||
Jeśli chcesz, aby „jestem autoryzowany raz i działają zarówno wiadomości prywatne, jak i polecenia grupowe”, umieść swoje numeryczne ID użytkownika Telegram w `channels.telegram.allowFrom`; dla poleceń tylko dla właściciela upewnij się, że `commands.ownerAllowFrom` zawiera `telegram:<your user id>`.
|
||||
|
||||
### Znajdowanie identyfikatora użytkownika Telegram
|
||||
### Znajdowanie swojego ID użytkownika Telegram
|
||||
|
||||
Bezpieczniej (bez bota zewnętrznego):
|
||||
|
||||
@ -152,29 +152,29 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
</Tab>
|
||||
|
||||
<Tab title="Zasada grupy i allowlisty">
|
||||
<Tab title="Polityka grup i listy dozwolonych">
|
||||
Dwie kontrolki działają razem:
|
||||
|
||||
1. **Które grupy są dozwolone** (`channels.telegram.groups`)
|
||||
- brak konfiguracji `groups`:
|
||||
- z `groupPolicy: "open"`: dowolna grupa może przejść kontrole ID grupy
|
||||
- z `groupPolicy: "allowlist"` (domyślnie): grupy są blokowane, dopóki nie dodasz wpisów `groups` (lub `"*"`)
|
||||
- skonfigurowane `groups`: działa jako allowlista (jawne ID lub `"*"`)
|
||||
- z `groupPolicy: "allowlist"` (domyślne): grupy są blokowane, dopóki nie dodasz wpisów `groups` (lub `"*"`)
|
||||
- `groups` skonfigurowane: działa jako lista dozwolonych (jawne ID lub `"*"`)
|
||||
|
||||
2. **Którzy nadawcy są dozwoleni w grupach** (`channels.telegram.groupPolicy`)
|
||||
- `open`
|
||||
- `allowlist` (domyślnie)
|
||||
- `allowlist` (domyślne)
|
||||
- `disabled`
|
||||
|
||||
`groupAllowFrom` służy do filtrowania nadawców w grupie. Jeśli nie jest ustawione, Telegram wraca do `allowFrom`.
|
||||
Wpisy `groupAllowFrom` powinny być numerycznymi identyfikatorami użytkowników Telegram (prefiksy `telegram:` / `tg:` są normalizowane).
|
||||
Nie umieszczaj identyfikatorów czatów grup Telegram ani supergrup w `groupAllowFrom`. Ujemne identyfikatory czatów należą do `channels.telegram.groups`.
|
||||
Wpisy nienumeryczne są ignorowane przy autoryzacji nadawców.
|
||||
Granica bezpieczeństwa (`2026.2.25+`): uwierzytelnianie nadawców w grupie **nie** dziedziczy zatwierdzeń magazynu parowania wiadomości prywatnych.
|
||||
Parowanie pozostaje tylko dla wiadomości prywatnych. Dla grup ustaw `groupAllowFrom` albo `allowFrom` per grupa/per temat.
|
||||
Jeśli `groupAllowFrom` nie jest ustawione, Telegram wraca do konfiguracyjnego `allowFrom`, a nie do magazynu parowania.
|
||||
Praktyczny wzorzec dla botów jednego właściciela: ustaw swój identyfikator użytkownika w `channels.telegram.allowFrom`, pozostaw `groupAllowFrom` nieustawione i zezwól na docelowe grupy w `channels.telegram.groups`.
|
||||
Uwaga runtime: jeśli `channels.telegram` całkowicie brakuje, runtime domyślnie działa w trybie fail-closed `groupPolicy="allowlist"`, chyba że `channels.defaults.groupPolicy` jest jawnie ustawione.
|
||||
`groupAllowFrom` służy do filtrowania nadawców grupowych. Jeśli nie jest ustawione, Telegram wraca do `allowFrom`.
|
||||
Wpisy `groupAllowFrom` powinny być numerycznymi ID użytkowników Telegram (prefiksy `telegram:` / `tg:` są normalizowane).
|
||||
Nie umieszczaj ID czatów grup Telegram ani supergrup w `groupAllowFrom`. Ujemne ID czatów należą do `channels.telegram.groups`.
|
||||
Wpisy nienumeryczne są ignorowane przy autoryzacji nadawcy.
|
||||
Granica bezpieczeństwa (`2026.2.25+`): uwierzytelnianie nadawcy grupowego **nie** dziedziczy zatwierdzeń z magazynu parowania wiadomości prywatnych.
|
||||
Parowanie pozostaje tylko dla wiadomości prywatnych. Dla grup ustaw `groupAllowFrom` albo `allowFrom` na poziomie grupy/tematu.
|
||||
Jeśli `groupAllowFrom` nie jest ustawione, Telegram używa zapasowo `allowFrom` z konfiguracji, a nie magazynu parowania.
|
||||
Praktyczny wzorzec dla botów z jednym właścicielem: ustaw swoje ID użytkownika w `channels.telegram.allowFrom`, pozostaw `groupAllowFrom` nieustawione i zezwól na docelowe grupy w `channels.telegram.groups`.
|
||||
Uwaga dotycząca środowiska uruchomieniowego: jeśli całkowicie brakuje `channels.telegram`, środowisko uruchomieniowe domyślnie działa w trybie bezpiecznie zamkniętym `groupPolicy="allowlist"`, chyba że `channels.defaults.groupPolicy` jest ustawione jawnie.
|
||||
|
||||
Przykład: zezwól dowolnemu członkowi w jednej konkretnej grupie:
|
||||
|
||||
@ -193,7 +193,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
}
|
||||
```
|
||||
|
||||
Przykład: zezwól tylko konkretnym użytkownikom w jednej konkretnej grupie:
|
||||
Przykład: zezwól tylko określonym użytkownikom w jednej konkretnej grupie:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -211,10 +211,10 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
```
|
||||
|
||||
<Warning>
|
||||
Częsty błąd: `groupAllowFrom` nie jest allowlistą grup Telegram.
|
||||
Częsty błąd: `groupAllowFrom` nie jest listą dozwolonych grup Telegram.
|
||||
|
||||
- Umieszczaj ujemne identyfikatory czatów grup Telegram lub supergrup, takie jak `-1001234567890`, w `channels.telegram.groups`.
|
||||
- Umieszczaj identyfikatory użytkowników Telegram, takie jak `8734062810`, w `groupAllowFrom`, gdy chcesz ograniczyć, które osoby w dozwolonej grupie mogą wywoływać bota.
|
||||
- Umieszczaj ujemne ID czatów grup Telegram lub supergrup, takie jak `-1001234567890`, pod `channels.telegram.groups`.
|
||||
- Umieszczaj ID użytkowników Telegram, takie jak `8734062810`, pod `groupAllowFrom`, gdy chcesz ograniczyć, które osoby w dozwolonej grupie mogą wywoływać bota.
|
||||
- Używaj `groupAllowFrom: ["*"]` tylko wtedy, gdy chcesz, aby każdy członek dozwolonej grupy mógł rozmawiać z botem.
|
||||
|
||||
</Warning>
|
||||
@ -222,7 +222,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
</Tab>
|
||||
|
||||
<Tab title="Zachowanie wzmianek">
|
||||
Odpowiedzi w grupie domyślnie wymagają wzmianki.
|
||||
Odpowiedzi grupowe domyślnie wymagają wzmianki.
|
||||
|
||||
Wzmianka może pochodzić z:
|
||||
|
||||
@ -236,7 +236,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
- `/activation always`
|
||||
- `/activation mention`
|
||||
|
||||
Aktualizują one tylko stan sesji. Do trwałości użyj konfiguracji.
|
||||
Aktualizują one wyłącznie stan sesji. Użyj konfiguracji dla trwałości.
|
||||
|
||||
Przykład trwałej konfiguracji:
|
||||
|
||||
@ -256,40 +256,41 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
- przekaż wiadomość grupową do `@userinfobot` / `@getidsbot`
|
||||
- albo odczytaj `chat.id` z `openclaw logs --follow`
|
||||
- albo sprawdź `getUpdates` w Bot API
|
||||
- albo sprawdź `getUpdates` Bot API
|
||||
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
## Zachowanie runtime
|
||||
## Zachowanie w środowisku uruchomieniowym
|
||||
|
||||
- Telegram jest własnością procesu gateway.
|
||||
- Routing jest deterministyczny: wiadomości przychodzące z Telegram odpowiadają z powrotem do Telegram (model nie wybiera kanałów).
|
||||
- Wiadomości przychodzące są normalizowane do wspólnej koperty kanału z metadanymi odpowiedzi i placeholderami mediów.
|
||||
- Sesje grupowe są izolowane według ID grupy. Tematy forum dodają `:topic:<threadId>`, aby utrzymać izolację tematów.
|
||||
- Wiadomości prywatne mogą zawierać `message_thread_id`; OpenClaw zachowuje ID wątku dla odpowiedzi, ale domyślnie utrzymuje wiadomości prywatne w płaskiej sesji. Skonfiguruj `channels.telegram.dm.threadReplies: "inbound"`, `channels.telegram.direct.<chatId>.threadReplies: "inbound"`, `requireTopic: true` albo pasującą konfigurację tematu, gdy celowo chcesz izolacji sesji tematów wiadomości prywatnych.
|
||||
- Długie odpytywanie używa runnera grammY z sekwencjonowaniem per czat/per wątek. Ogólna współbieżność sink runnera używa `agents.defaults.maxConcurrent`.
|
||||
- Długie odpytywanie jest chronione wewnątrz każdego procesu gateway, aby tylko jeden aktywny poller mógł używać tokena bota naraz. Jeśli nadal widzisz konflikty `getUpdates` 409, inny gateway OpenClaw, skrypt albo zewnętrzny poller prawdopodobnie używa tego samego tokena.
|
||||
- Restart watchdoga długiego odpytywania uruchamia się domyślnie po 120 sekundach bez ukończonej aktywności `getUpdates`. Zwiększ `channels.telegram.pollingStallThresholdMs` tylko wtedy, gdy wdrożenie nadal widzi fałszywe restarty polling-stall podczas długotrwałej pracy. Wartość jest w milisekundach i jest dozwolona od `30000` do `600000`; obsługiwane są nadpisania per konto.
|
||||
- Telegram jest obsługiwany przez proces gateway.
|
||||
- Routing jest deterministyczny: wiadomości przychodzące z Telegram otrzymują odpowiedzi w Telegram (model nie wybiera kanałów).
|
||||
- Wiadomości przychodzące są normalizowane do współdzielonej koperty kanału z metadanymi odpowiedzi i placeholderami multimediów.
|
||||
- Sesje grupowe są izolowane według ID grupy. Tematy forum dopisują `:topic:<threadId>`, aby utrzymać izolację tematów.
|
||||
- Wiadomości prywatne mogą zawierać `message_thread_id`; OpenClaw zachowuje ID wątku dla odpowiedzi, ale domyślnie utrzymuje wiadomości prywatne w płaskiej sesji. Skonfiguruj `channels.telegram.dm.threadReplies: "inbound"`, `channels.telegram.direct.<chatId>.threadReplies: "inbound"`, `requireTopic: true` albo pasującą konfigurację tematu, gdy celowo chcesz izolacji sesji tematu w wiadomościach prywatnych.
|
||||
- Długie odpytywanie używa runnera grammY z sekwencjonowaniem per czat/per wątek. Ogólna współbieżność ujścia runnera używa `agents.defaults.maxConcurrent`.
|
||||
- Długie odpytywanie jest chronione wewnątrz każdego procesu gateway, tak aby tylko jeden aktywny poller mógł używać tokena bota w danym czasie. Jeśli nadal widzisz konflikty `getUpdates` 409, inny gateway OpenClaw, skrypt lub zewnętrzny poller prawdopodobnie używa tego samego tokena.
|
||||
- Ponowne uruchomienia watchdog długiego odpytywania są domyślnie wyzwalane po 120 sekundach bez ukończonej żywotności `getUpdates`. Zwiększ `channels.telegram.pollingStallThresholdMs` tylko wtedy, gdy wdrożenie nadal widzi fałszywe ponowne uruchomienia z powodu zatrzymania odpytywania podczas długotrwałej pracy. Wartość jest w milisekundach i może wynosić od `30000` do `600000`; obsługiwane są nadpisania per konto.
|
||||
- Telegram Bot API nie obsługuje potwierdzeń odczytu (`sendReadReceipts` nie ma zastosowania).
|
||||
|
||||
## Odniesienie funkcji
|
||||
## Opis funkcji
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Podgląd transmisji na żywo (edycje wiadomości)">
|
||||
OpenClaw może przesyłać częściowe odpowiedzi w czasie rzeczywistym:
|
||||
OpenClaw może strumieniować częściowe odpowiedzi w czasie rzeczywistym:
|
||||
|
||||
- czaty bezpośrednie: wiadomość podglądu + `editMessageText`
|
||||
- grupy/tematy: wiadomość podglądu + `editMessageText`
|
||||
|
||||
Wymaganie:
|
||||
|
||||
- `channels.telegram.streaming` ma wartość `off | partial | block | progress` (domyślnie: `partial`)
|
||||
- `progress` utrzymuje jeden edytowalny szkic statusu i aktualizuje go postępem narzędzi aż do finalnej dostawy
|
||||
- `streaming.preview.toolProgress` kontroluje, czy aktualizacje narzędzi/postępu ponownie używają tej samej edytowanej wiadomości podglądu (domyślnie: `true`, gdy aktywne jest strumieniowanie podglądu)
|
||||
- starsze `channels.telegram.streamMode` i boolowskie wartości `streaming` są wykrywane; uruchom `openclaw doctor --fix`, aby zmigrować je do `channels.telegram.streaming.mode`
|
||||
- `channels.telegram.streaming` to `off | partial | block | progress` (domyślnie: `partial`)
|
||||
- `progress` utrzymuje jeden edytowalny szkic statusu i aktualizuje go postępem narzędzia aż do ostatecznego dostarczenia
|
||||
- `streaming.preview.toolProgress` kontroluje, czy aktualizacje narzędzia/postępu ponownie używają tej samej edytowanej wiadomości podglądu (domyślnie: `true`, gdy strumieniowanie podglądu jest aktywne)
|
||||
- `streaming.preview.commandText` kontroluje szczegóły polecenia/wykonania w tych wierszach postępu narzędzia: `raw` (domyślne, zachowuje wydane zachowanie) albo `status` (tylko etykieta narzędzia)
|
||||
- starsze `channels.telegram.streamMode` i logiczne wartości `streaming` są wykrywane; uruchom `openclaw doctor --fix`, aby zmigrować je do `channels.telegram.streaming.mode`
|
||||
|
||||
Aktualizacje podglądu postępu narzędzi to krótkie wiersze statusu pokazywane podczas działania narzędzi, na przykład wykonywanie poleceń, odczyty plików, aktualizacje planowania albo podsumowania patchy. Telegram domyślnie utrzymuje je włączone, aby odpowiadać zachowaniu OpenClaw wydanemu w `v2026.4.22` i później. Aby zachować edytowany podgląd tekstu odpowiedzi, ale ukryć wiersze postępu narzędzi, ustaw:
|
||||
Aktualizacje podglądu postępu narzędzi to krótkie wiersze statusu pokazywane podczas działania narzędzi, na przykład wykonywanie poleceń, odczyty plików, aktualizacje planowania lub podsumowania poprawek. Telegram domyślnie pozostawia je włączone, aby odpowiadały wydanemu zachowaniu OpenClaw od `v2026.4.22` i nowszych. Aby zachować edytowany podgląd dla tekstu odpowiedzi, ale ukryć wiersze postępu narzędzi, ustaw:
|
||||
|
||||
```json
|
||||
{
|
||||
@ -306,48 +307,84 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
}
|
||||
```
|
||||
|
||||
Używaj `streaming.mode: "off"` tylko wtedy, gdy chcesz dostarczania wyłącznie końcowego: edycje podglądu Telegram są wyłączone, a ogólne komunikaty narzędzi/postępu są tłumione zamiast wysyłania ich jako samodzielnych komunikatów stanu. Monity zatwierdzeń, ładunki multimedialne i błędy nadal przechodzą przez normalne dostarczanie końcowe. Użyj `streaming.preview.toolProgress: false`, gdy chcesz zachować tylko edycje podglądu odpowiedzi, ukrywając jednocześnie wiersze stanu postępu narzędzi.
|
||||
Aby zachować widoczny postęp narzędzi, ale ukryć tekst polecenia/wykonania, ustaw:
|
||||
|
||||
```json
|
||||
{
|
||||
"channels": {
|
||||
"telegram": {
|
||||
"streaming": {
|
||||
"mode": "partial",
|
||||
"preview": {
|
||||
"commandText": "status"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
W trybie wersji roboczej postępu umieść tę samą politykę tekstu polecenia pod `streaming.progress`:
|
||||
|
||||
```json
|
||||
{
|
||||
"channels": {
|
||||
"telegram": {
|
||||
"streaming": {
|
||||
"mode": "progress",
|
||||
"progress": {
|
||||
"toolProgress": true,
|
||||
"commandText": "status"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Używaj `streaming.mode: "off"` tylko wtedy, gdy chcesz dostarczać wyłącznie odpowiedzi końcowe: edycje podglądu Telegram są wyłączone, a ogólne komunikaty narzędzi/postępu są wyciszane zamiast wysyłane jako osobne wiadomości statusu. Monity zatwierdzeń, ładunki multimedialne i błędy nadal przechodzą przez normalne dostarczanie końcowe. Użyj `streaming.preview.toolProgress: false`, gdy chcesz zachować tylko edycje podglądu odpowiedzi, ukrywając wiersze statusu postępu narzędzi.
|
||||
|
||||
<Note>
|
||||
Odpowiedzi na wybrane cytaty w Telegram są wyjątkiem. Gdy `replyToMode` ma wartość `"first"`, `"all"` lub `"batched"`, a wiadomość przychodząca zawiera tekst wybranego cytatu, OpenClaw wysyła końcową odpowiedź przez natywną ścieżkę odpowiedzi z cytatem Telegram zamiast edytować podgląd odpowiedzi, więc `streaming.preview.toolProgress` nie może pokazać krótkich wierszy stanu dla tego przebiegu. Odpowiedzi na bieżącą wiadomość bez tekstu wybranego cytatu nadal zachowują strumieniowanie podglądu. Ustaw `replyToMode: "off"`, gdy widoczność postępu narzędzi jest ważniejsza niż natywne odpowiedzi z cytatem, albo ustaw `streaming.preview.toolProgress: false`, aby zaakceptować ten kompromis.
|
||||
Wyjątkiem są odpowiedzi Telegram z wybranym cytatem. Gdy `replyToMode` ma wartość `"first"`, `"all"` lub `"batched"` i wiadomość przychodząca zawiera wybrany tekst cytatu, OpenClaw wysyła odpowiedź końcową przez natywną ścieżkę odpowiedzi z cytatem Telegram zamiast edytować podgląd odpowiedzi, więc `streaming.preview.toolProgress` nie może pokazać krótkich wierszy statusu dla tej tury. Odpowiedzi na bieżącą wiadomość bez wybranego tekstu cytatu nadal zachowują strumieniowanie podglądu. Ustaw `replyToMode: "off"`, gdy widoczność postępu narzędzi jest ważniejsza niż natywne odpowiedzi z cytatem, albo ustaw `streaming.preview.toolProgress: false`, aby zaakceptować ten kompromis.
|
||||
</Note>
|
||||
|
||||
Dla odpowiedzi zawierających tylko tekst:
|
||||
Dla odpowiedzi tekstowych:
|
||||
|
||||
- krótkie podglądy w DM/grupach/tematach: OpenClaw zachowuje tę samą wiadomość podglądu i wykonuje końcową edycję w miejscu, chyba że po pojawieniu się podglądu została wysłana widoczna wiadomość niebędąca podglądem
|
||||
- podglądy, po których następuje widoczne wyjście niebędące podglądem: OpenClaw wysyła ukończoną odpowiedź jako nową wiadomość końcową i sprząta starszy podgląd, więc odpowiedź końcowa pojawia się po wyjściu pośrednim
|
||||
- podglądy starsze niż około jedna minuta: OpenClaw wysyła ukończoną odpowiedź jako nową wiadomość końcową, a następnie sprząta podgląd, więc widoczny znacznik czasu Telegram odzwierciedla czas ukończenia zamiast czasu utworzenia podglądu
|
||||
- krótkie podglądy w DM/grupie/temacie: OpenClaw zachowuje tę samą wiadomość podglądu i wykonuje końcową edycję w miejscu, chyba że po pojawieniu się podglądu wysłano widoczną wiadomość niebędącą podglądem
|
||||
- podglądy, po których następuje widoczna treść niebędąca podglądem: OpenClaw wysyła ukończoną odpowiedź jako nową wiadomość końcową i usuwa starszy podgląd, dzięki czemu odpowiedź końcowa pojawia się po treści pośredniej
|
||||
- podglądy starsze niż około jedna minuta: OpenClaw wysyła ukończoną odpowiedź jako nową wiadomość końcową, a następnie usuwa podgląd, dzięki czemu widoczny znacznik czasu Telegram odzwierciedla czas ukończenia zamiast czasu utworzenia podglądu
|
||||
|
||||
Dla złożonych odpowiedzi (na przykład ładunków multimedialnych) OpenClaw wraca do normalnego dostarczania końcowego, a następnie sprząta wiadomość podglądu.
|
||||
W przypadku złożonych odpowiedzi (na przykład ładunków multimedialnych) OpenClaw wraca do normalnego dostarczania końcowego, a następnie usuwa wiadomość podglądu.
|
||||
|
||||
Strumieniowanie podglądu jest oddzielne od strumieniowania bloków. Gdy strumieniowanie bloków jest jawnie włączone dla Telegram, OpenClaw pomija strumień podglądu, aby uniknąć podwójnego strumieniowania.
|
||||
Strumieniowanie podglądu jest niezależne od strumieniowania bloków. Gdy strumieniowanie bloków jest jawnie włączone dla Telegram, OpenClaw pomija strumień podglądu, aby uniknąć podwójnego strumieniowania.
|
||||
|
||||
Strumień rozumowania tylko dla Telegram:
|
||||
|
||||
- `/reasoning stream` wysyła rozumowanie do podglądu na żywo podczas generowania
|
||||
- podgląd rozumowania jest usuwany po dostarczeniu odpowiedzi końcowej; użyj `/reasoning on`, gdy rozumowanie ma pozostać widoczne
|
||||
- odpowiedź końcowa jest wysyłana bez tekstu rozumowania
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Formatowanie i awaryjny HTML">
|
||||
<Accordion title="Formatowanie i awaryjne użycie HTML">
|
||||
Tekst wychodzący używa Telegram `parse_mode: "HTML"`.
|
||||
|
||||
- Tekst w stylu Markdown jest renderowany do HTML bezpiecznego dla Telegram.
|
||||
- Surowy HTML modelu jest escape'owany, aby ograniczyć błędy parsowania Telegram.
|
||||
- Tekst podobny do Markdown jest renderowany do HTML bezpiecznego dla Telegram.
|
||||
- Surowy HTML z modelu jest escapowany, aby ograniczyć błędy parsowania Telegram.
|
||||
- Jeśli Telegram odrzuci sparsowany HTML, OpenClaw ponawia próbę jako zwykły tekst.
|
||||
|
||||
Podglądy linków są domyślnie włączone i można je wyłączyć za pomocą `channels.telegram.linkPreview: false`.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Natywne polecenia i polecenia niestandardowe">
|
||||
Rejestracja menu poleceń Telegram jest obsługiwana podczas uruchamiania za pomocą `setMyCommands`.
|
||||
<Accordion title="Polecenia natywne i polecenia niestandardowe">
|
||||
Rejestracja menu poleceń Telegram jest obsługiwana przy starcie przez `setMyCommands`.
|
||||
|
||||
Domyślne ustawienia natywnych poleceń:
|
||||
Domyślne ustawienia poleceń natywnych:
|
||||
|
||||
- `commands.native: "auto"` włącza natywne polecenia dla Telegram
|
||||
- `commands.native: "auto"` włącza polecenia natywne dla Telegram
|
||||
|
||||
Dodaj niestandardowe pozycje menu poleceń:
|
||||
Dodaj niestandardowe wpisy menu poleceń:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -371,19 +408,19 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
Uwagi:
|
||||
|
||||
- polecenia niestandardowe są tylko pozycjami menu; nie implementują automatycznie zachowania
|
||||
- polecenia Plugin/Skills mogą nadal działać po wpisaniu, nawet jeśli nie są pokazane w menu Telegram
|
||||
- polecenia niestandardowe są wyłącznie wpisami menu; nie implementują automatycznie zachowania
|
||||
- polecenia plugin/skill mogą nadal działać po wpisaniu, nawet jeśli nie są widoczne w menu Telegram
|
||||
|
||||
Jeśli natywne polecenia są wyłączone, wbudowane polecenia są usuwane. Polecenia niestandardowe/Plugin mogą nadal się rejestrować, jeśli są skonfigurowane.
|
||||
Jeśli polecenia natywne są wyłączone, wbudowane polecenia są usuwane. Polecenia niestandardowe/plugin mogą nadal zostać zarejestrowane, jeśli są skonfigurowane.
|
||||
|
||||
Typowe błędy konfiguracji:
|
||||
|
||||
- `setMyCommands failed` z `BOT_COMMANDS_TOO_MUCH` oznacza, że menu Telegram nadal było przepełnione po przycięciu; zmniejsz liczbę poleceń Plugin/Skills/niestandardowych albo wyłącz `channels.telegram.commands.native`.
|
||||
- Niepowodzenie `deleteWebhook`, `deleteMyCommands` lub `setMyCommands` z `404: Not Found`, gdy bezpośrednie polecenia curl Bot API działają, może oznaczać, że `channels.telegram.apiRoot` ustawiono na pełny punkt końcowy `/bot<TOKEN>`. `apiRoot` musi być tylko korzeniem Bot API, a `openclaw doctor --fix` usuwa przypadkowy końcowy fragment `/bot<TOKEN>`.
|
||||
- `getMe returned 401` oznacza, że Telegram odrzucił skonfigurowany token bota. Zaktualizuj `botToken`, `tokenFile` lub `TELEGRAM_BOT_TOKEN` bieżącym tokenem BotFather; OpenClaw zatrzymuje się przed odpytywaniem, więc nie jest to raportowane jako błąd sprzątania Webhook.
|
||||
- `setMyCommands failed` z `BOT_COMMANDS_TOO_MUCH` oznacza, że menu Telegram nadal przekroczyło limit po przycięciu; ogranicz polecenia plugin/skill/niestandardowe albo wyłącz `channels.telegram.commands.native`.
|
||||
- Niepowodzenie `deleteWebhook`, `deleteMyCommands` lub `setMyCommands` z `404: Not Found`, gdy bezpośrednie polecenia curl Bot API działają, może oznaczać, że `channels.telegram.apiRoot` ustawiono na pełny punkt końcowy `/bot<TOKEN>`. `apiRoot` musi być tylko katalogiem głównym Bot API, a `openclaw doctor --fix` usuwa przypadkowy końcowy `/bot<TOKEN>`.
|
||||
- `getMe returned 401` oznacza, że Telegram odrzucił skonfigurowany token bota. Zaktualizuj `botToken`, `tokenFile` lub `TELEGRAM_BOT_TOKEN` bieżącym tokenem BotFather; OpenClaw zatrzymuje się przed odpytywaniem, więc nie jest to zgłaszane jako błąd czyszczenia Webhook.
|
||||
- `setMyCommands failed` z błędami sieci/fetch zwykle oznacza, że wychodzące DNS/HTTPS do `api.telegram.org` jest zablokowane.
|
||||
|
||||
### Polecenia parowania urządzenia (Plugin `device-pair`)
|
||||
### Polecenia parowania urządzeń (Plugin `device-pair`)
|
||||
|
||||
Gdy Plugin `device-pair` jest zainstalowany:
|
||||
|
||||
@ -395,16 +432,16 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
- `/pair approve`, gdy istnieje tylko jedno oczekujące żądanie
|
||||
- `/pair approve latest` dla najnowszego
|
||||
|
||||
Kod konfiguracji przenosi krótkotrwały token bootstrap. Wbudowane przekazanie bootstrap utrzymuje token węzła głównego przy `scopes: []`; każdy przekazany token operatora pozostaje ograniczony do `operator.approvals`, `operator.read`, `operator.talk.secrets` i `operator.write`. Kontrole zakresu bootstrap są prefiksowane rolą, więc ta lista dozwolonych operatora spełnia tylko żądania operatora; role niebędące operatorem nadal potrzebują zakresów pod własnym prefiksem roli.
|
||||
Kod konfiguracji zawiera krótkotrwały token bootstrap. Wbudowane przekazanie bootstrap utrzymuje token węzła głównego przy `scopes: []`; każdy przekazany token operatora pozostaje ograniczony do `operator.approvals`, `operator.read`, `operator.talk.secrets` i `operator.write`. Sprawdzenia zakresów bootstrap mają prefiks roli, więc ta lista dozwolonych operatora spełnia tylko żądania operatora; role nieoperatorskie nadal wymagają zakresów pod własnym prefiksem roli.
|
||||
|
||||
Jeśli urządzenie ponawia próbę ze zmienionymi szczegółami uwierzytelniania (na przykład rolą/zakresami/kluczem publicznym), poprzednie oczekujące żądanie zostaje zastąpione, a nowe żądanie używa innego `requestId`. Uruchom ponownie `/pair pending` przed zatwierdzeniem.
|
||||
Jeśli urządzenie ponawia próbę ze zmienionymi szczegółami uwierzytelniania (na przykład rolą/zakresami/kluczem publicznym), poprzednie oczekujące żądanie jest zastępowane, a nowe żądanie używa innego `requestId`. Uruchom ponownie `/pair pending` przed zatwierdzeniem.
|
||||
|
||||
Więcej szczegółów: [Parowanie](/pl/channels/pairing#pair-via-telegram-recommended-for-ios).
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Przyciski w treści wiadomości">
|
||||
Skonfiguruj zakres klawiatury w treści wiadomości:
|
||||
<Accordion title="Przyciski inline">
|
||||
Skonfiguruj zakres klawiatury inline:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -464,7 +501,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
}
|
||||
```
|
||||
|
||||
Kliknięcia callback są przekazywane do agenta jako tekst:
|
||||
Kliknięcia callback są przekazywane agentowi jako tekst:
|
||||
`callback_data: <value>`
|
||||
|
||||
</Accordion>
|
||||
@ -472,15 +509,15 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
<Accordion title="Akcje wiadomości Telegram dla agentów i automatyzacji">
|
||||
Akcje narzędzi Telegram obejmują:
|
||||
|
||||
- `sendMessage` (`to`, `content`, opcjonalne `mediaUrl`, `replyToMessageId`, `messageThreadId`)
|
||||
- `sendMessage` (`to`, `content`, opcjonalnie `mediaUrl`, `replyToMessageId`, `messageThreadId`)
|
||||
- `react` (`chatId`, `messageId`, `emoji`)
|
||||
- `deleteMessage` (`chatId`, `messageId`)
|
||||
- `editMessage` (`chatId`, `messageId`, `content`)
|
||||
- `createForumTopic` (`chatId`, `name`, opcjonalne `iconColor`, `iconCustomEmojiId`)
|
||||
- `createForumTopic` (`chatId`, `name`, opcjonalnie `iconColor`, `iconCustomEmojiId`)
|
||||
|
||||
Akcje wiadomości kanału udostępniają ergonomiczne aliasy (`send`, `react`, `delete`, `edit`, `sticker`, `sticker-search`, `topic-create`).
|
||||
|
||||
Kontrole bramkowania:
|
||||
Kontrolki bramkowania:
|
||||
|
||||
- `channels.telegram.actions.sendMessage`
|
||||
- `channels.telegram.actions.deleteMessage`
|
||||
@ -488,47 +525,47 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
- `channels.telegram.actions.sticker` (domyślnie: wyłączone)
|
||||
|
||||
Uwaga: `edit` i `topic-create` są obecnie domyślnie włączone i nie mają osobnych przełączników `channels.telegram.actions.*`.
|
||||
Wysyłki w czasie wykonywania używają aktywnej migawki konfiguracji/sekretów (uruchomienie/przeładowanie), więc ścieżki akcji nie wykonują doraźnego ponownego rozwiązywania SecretRef dla każdej wysyłki.
|
||||
Wysyłki w czasie działania używają aktywnej migawki konfiguracji/sekretów (start/przeładowanie), więc ścieżki akcji nie wykonują doraźnego ponownego rozwiązywania SecretRef przy każdym wysłaniu.
|
||||
|
||||
Semantyka usuwania reakcji: [/tools/reactions](/pl/tools/reactions)
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Znaczniki wątków odpowiedzi">
|
||||
Telegram obsługuje jawne znaczniki wątków odpowiedzi w wygenerowanym wyjściu:
|
||||
<Accordion title="Tagi wątkowania odpowiedzi">
|
||||
Telegram obsługuje jawne tagi wątkowania odpowiedzi w wygenerowanej treści:
|
||||
|
||||
- `[[reply_to_current]]` odpowiada na wiadomość wyzwalającą
|
||||
- `[[reply_to:<id>]]` odpowiada na określony identyfikator wiadomości Telegram
|
||||
- `[[reply_to:<id>]]` odpowiada na konkretny identyfikator wiadomości Telegram
|
||||
|
||||
`channels.telegram.replyToMode` kontroluje obsługę:
|
||||
`channels.telegram.replyToMode` steruje obsługą:
|
||||
|
||||
- `off` (domyślnie)
|
||||
- `first`
|
||||
- `all`
|
||||
|
||||
Gdy wątki odpowiedzi są włączone, a oryginalny tekst lub podpis Telegram jest dostępny, OpenClaw automatycznie dołącza natywny fragment cytatu Telegram. Telegram ogranicza natywny tekst cytatu do 1024 jednostek kodu UTF-16, więc dłuższe wiadomości są cytowane od początku i wracają do zwykłej odpowiedzi, jeśli Telegram odrzuci cytat.
|
||||
Gdy wątkowanie odpowiedzi jest włączone i oryginalny tekst lub podpis Telegram jest dostępny, OpenClaw automatycznie dołącza natywny fragment cytatu Telegram. Telegram ogranicza natywny tekst cytatu do 1024 jednostek kodu UTF-16, więc dłuższe wiadomości są cytowane od początku i wracają do zwykłej odpowiedzi, jeśli Telegram odrzuci cytat.
|
||||
|
||||
Uwaga: `off` wyłącza niejawne wątki odpowiedzi. Jawne znaczniki `[[reply_to_*]]` są nadal honorowane.
|
||||
Uwaga: `off` wyłącza niejawne wątkowanie odpowiedzi. Jawne tagi `[[reply_to_*]]` są nadal respektowane.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Tematy forum i zachowanie wątków">
|
||||
Supergrupy forum:
|
||||
|
||||
- klucze sesji tematów dodają `:topic:<threadId>`
|
||||
- odpowiedzi i wskaźnik pisania trafiają do wątku tematu
|
||||
- klucze sesji tematów dopisują `:topic:<threadId>`
|
||||
- odpowiedzi i wskaźnik pisania są kierowane do wątku tematu
|
||||
- ścieżka konfiguracji tematu:
|
||||
`channels.telegram.groups.<chatId>.topics.<threadId>`
|
||||
|
||||
Specjalny przypadek tematu ogólnego (`threadId=1`):
|
||||
Szczególny przypadek tematu ogólnego (`threadId=1`):
|
||||
|
||||
- wysyłki wiadomości pomijają `message_thread_id` (Telegram odrzuca `sendMessage(...thread_id=1)`)
|
||||
- akcje pisania nadal obejmują `message_thread_id`
|
||||
- akcje pisania nadal zawierają `message_thread_id`
|
||||
|
||||
Dziedziczenie tematu: wpisy tematów dziedziczą ustawienia grupy, chyba że zostaną nadpisane (`requireMention`, `allowFrom`, `skills`, `systemPrompt`, `enabled`, `groupPolicy`).
|
||||
`agentId` dotyczy tylko tematu i nie dziedziczy wartości domyślnych grupy.
|
||||
Dziedziczenie tematów: wpisy tematów dziedziczą ustawienia grupy, chyba że zostaną nadpisane (`requireMention`, `allowFrom`, `skills`, `systemPrompt`, `enabled`, `groupPolicy`).
|
||||
`agentId` dotyczy tylko tematu i nie dziedziczy z domyślnych ustawień grupy.
|
||||
|
||||
**Routing agentów według tematu**: Każdy temat może kierować do innego agenta przez ustawienie `agentId` w konfiguracji tematu. Daje to każdemu tematowi własną izolowaną przestrzeń roboczą, pamięć i sesję. Przykład:
|
||||
**Routing agentów według tematów**: Każdy temat może kierować do innego agenta przez ustawienie `agentId` w konfiguracji tematu. Daje to każdemu tematowi własny izolowany obszar roboczy, pamięć i sesję. Przykład:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -550,11 +587,11 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
Każdy temat ma wtedy własny klucz sesji: `agent:zu:telegram:group:-1001234567890:topic:3`
|
||||
|
||||
**Trwałe wiązanie tematu ACP**: Tematy forum mogą przypinać sesje uprzęży ACP przez typowane wiązania ACP najwyższego poziomu (`bindings[]` z `type: "acp"` i `match.channel: "telegram"`, `peer.kind: "group"` oraz identyfikatorem kwalifikowanym tematem, takim jak `-1001234567890:topic:42`). Obecnie ograniczone do tematów forum w grupach/supergrupach. Zobacz [Agenci ACP](/pl/tools/acp-agents).
|
||||
**Trwałe powiązanie tematu ACP**: Tematy forum mogą przypinać sesje uprzęży ACP przez typowane powiązania ACP najwyższego poziomu (`bindings[]` z `type: "acp"` i `match.channel: "telegram"`, `peer.kind: "group"` oraz identyfikatorem z kwalifikatorem tematu, takim jak `-1001234567890:topic:42`). Obecnie zakres jest ograniczony do tematów forum w grupach/supergrupach. Zobacz [Agenci ACP](/pl/tools/acp-agents).
|
||||
|
||||
**Tworzenie ACP powiązanego z wątkiem z czatu**: `/acp spawn <agent> --thread here|auto` wiąże bieżący temat z nową sesją ACP; kolejne odpowiedzi są kierowane tam bezpośrednio. OpenClaw przypina potwierdzenie utworzenia w temacie. Wymaga, aby `channels.telegram.threadBindings.spawnSessions` pozostało włączone (domyślnie: `true`).
|
||||
**Uruchamianie ACP z czatu powiązane z wątkiem**: `/acp spawn <agent> --thread here|auto` wiąże bieżący temat z nową sesją ACP; kolejne wiadomości trafiają tam bezpośrednio. OpenClaw przypina potwierdzenie uruchomienia w temacie. Wymaga, aby `channels.telegram.threadBindings.spawnSessions` pozostało włączone (domyślnie: `true`).
|
||||
|
||||
Kontekst szablonu udostępnia `MessageThreadId` i `IsForum`. Czaty DM z `message_thread_id` domyślnie zachowują routing DM i metadane odpowiedzi w płaskich sesjach; używają kluczy sesji świadomych wątku tylko wtedy, gdy skonfigurowano `threadReplies: "inbound"`, `threadReplies: "always"`, `requireTopic: true` lub pasującą konfigurację tematu. Użyj najwyższego poziomu `channels.telegram.dm.threadReplies` jako wartości domyślnej konta albo `direct.<chatId>.threadReplies` dla jednego DM.
|
||||
Kontekst szablonu udostępnia `MessageThreadId` i `IsForum`. Czaty DM z `message_thread_id` domyślnie zachowują routing DM i metadane odpowiedzi w płaskich sesjach; używają kluczy sesji świadomych wątku tylko wtedy, gdy skonfigurowano `threadReplies: "inbound"`, `threadReplies: "always"`, `requireTopic: true` albo pasującą konfigurację tematu. Użyj nadrzędnego `channels.telegram.dm.threadReplies` jako ustawienia domyślnego konta albo `direct.<chatId>.threadReplies` dla pojedynczego DM.
|
||||
|
||||
</Accordion>
|
||||
|
||||
@ -564,10 +601,10 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
Telegram rozróżnia notatki głosowe i pliki audio.
|
||||
|
||||
- domyślnie: zachowanie pliku audio
|
||||
- znacznik `[[audio_as_voice]]` w odpowiedzi agenta wymusza wysłanie notatki głosowej
|
||||
- transkrypcje przychodzących notatek głosowych są ujmowane w kontekście agenta jako wygenerowany maszynowo,
|
||||
niezaufany tekst; wykrywanie wzmianek nadal używa surowej
|
||||
transkrypcji, więc wiadomości głosowe bramkowane wzmianką nadal działają.
|
||||
- tag `[[audio_as_voice]]` w odpowiedzi agenta wymusza wysłanie jako notatki głosowej
|
||||
- przychodzące transkrypcje notatek głosowych są ujmowane w kontekście agenta jako wygenerowany maszynowo,
|
||||
niezaufany tekst; wykrywanie wzmianki nadal używa surowej
|
||||
transkrypcji, więc wiadomości głosowe wymagające wzmianki nadal działają.
|
||||
|
||||
Przykład akcji wiadomości:
|
||||
|
||||
@ -603,9 +640,9 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
Obsługa przychodzących naklejek:
|
||||
|
||||
- statyczne WEBP: pobierane i przetwarzane (placeholder `<media:sticker>`)
|
||||
- animowane TGS: pomijane
|
||||
- wideo WEBM: pomijane
|
||||
- statyczny WEBP: pobierany i przetwarzany (placeholder `<media:sticker>`)
|
||||
- animowany TGS: pomijany
|
||||
- wideo WEBM: pomijany
|
||||
|
||||
Pola kontekstu naklejki:
|
||||
|
||||
@ -619,7 +656,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
- `~/.openclaw/telegram/sticker-cache.json`
|
||||
|
||||
Naklejki są opisywane raz (gdy to możliwe) i zapisywane w pamięci podręcznej, aby ograniczyć powtarzane wywołania wizji.
|
||||
Naklejki są opisywane raz (gdy to możliwe) i buforowane, aby ograniczyć powtarzające się wywołania wizyjne.
|
||||
|
||||
Włącz akcje naklejek:
|
||||
|
||||
@ -635,7 +672,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
}
|
||||
```
|
||||
|
||||
Akcja wysłania naklejki:
|
||||
Wyślij akcję naklejki:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -646,7 +683,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
}
|
||||
```
|
||||
|
||||
Przeszukaj naklejki z pamięci podręcznej:
|
||||
Przeszukaj zapisane w pamięci podręcznej naklejki:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -662,7 +699,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
<Accordion title="Powiadomienia o reakcjach">
|
||||
Reakcje Telegram przychodzą jako aktualizacje `message_reaction` (oddzielnie od ładunków wiadomości).
|
||||
|
||||
Po włączeniu OpenClaw dodaje do kolejki zdarzenia systemowe takie jak:
|
||||
Po włączeniu OpenClaw kolejkowuje zdarzenia systemowe takie jak:
|
||||
|
||||
- `Telegram reaction added: 👍 by Alice (@alice) on msg 42`
|
||||
|
||||
@ -673,17 +710,17 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
Uwagi:
|
||||
|
||||
- `own` oznacza reakcje użytkowników tylko na wiadomości wysłane przez bota (best-effort przez pamięć podręczną wysłanych wiadomości).
|
||||
- `own` oznacza wyłącznie reakcje użytkowników na wiadomości wysłane przez bota (best-effort przez pamięć podręczną wysłanych wiadomości).
|
||||
- Zdarzenia reakcji nadal respektują kontrole dostępu Telegram (`dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`); nieautoryzowani nadawcy są odrzucani.
|
||||
- Telegram nie udostępnia identyfikatorów wątków w aktualizacjach reakcji.
|
||||
- grupy niebędące forami są kierowane do sesji czatu grupowego
|
||||
- grupy forum są kierowane do sesji ogólnego tematu grupy (`:topic:1`), a nie do dokładnego tematu źródłowego
|
||||
- Telegram nie podaje identyfikatorów wątków w aktualizacjach reakcji.
|
||||
- grupy bez forum są kierowane do sesji czatu grupowego
|
||||
- grupy forum są kierowane do ogólnej sesji tematu grupy (`:topic:1`), a nie do dokładnego tematu źródłowego
|
||||
|
||||
`allowed_updates` dla odpytywania/webhooka automatycznie obejmuje `message_reaction`.
|
||||
`allowed_updates` dla polling/Webhook automatycznie obejmuje `message_reaction`.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Reakcje potwierdzenia">
|
||||
<Accordion title="Reakcje ack">
|
||||
`ackReaction` wysyła emoji potwierdzenia, gdy OpenClaw przetwarza wiadomość przychodzącą.
|
||||
|
||||
Kolejność rozstrzygania:
|
||||
@ -691,11 +728,11 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
- `channels.telegram.accounts.<accountId>.ackReaction`
|
||||
- `channels.telegram.ackReaction`
|
||||
- `messages.ackReaction`
|
||||
- awaryjne emoji tożsamości agenta (`agents.list[].identity.emoji`, w przeciwnym razie „👀”)
|
||||
- awaryjne emoji tożsamości agenta (`agents.list[].identity.emoji`, w przeciwnym razie "👀")
|
||||
|
||||
Uwagi:
|
||||
|
||||
- Telegram oczekuje emoji Unicode (na przykład „👀”).
|
||||
- Telegram oczekuje emoji unicode (na przykład "👀").
|
||||
- Użyj `""`, aby wyłączyć reakcję dla kanału lub konta.
|
||||
|
||||
</Accordion>
|
||||
@ -705,7 +742,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
Zapisy wyzwalane przez Telegram obejmują:
|
||||
|
||||
- zdarzenia migracji grup (`migrate_to_chat_id`) w celu zaktualizowania `channels.telegram.groups`
|
||||
- zdarzenia migracji grupy (`migrate_to_chat_id`) aktualizujące `channels.telegram.groups`
|
||||
- `/config set` i `/config unset` (wymaga włączenia poleceń)
|
||||
|
||||
Wyłącz:
|
||||
@ -722,13 +759,13 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Długie odpytywanie kontra webhook">
|
||||
Domyślnie używane jest długie odpytywanie. Dla trybu webhooka ustaw `channels.telegram.webhookUrl` i `channels.telegram.webhookSecret`; opcjonalnie `webhookPath`, `webhookHost`, `webhookPort` (domyślnie `/telegram-webhook`, `127.0.0.1`, `8787`).
|
||||
<Accordion title="Long polling a Webhook">
|
||||
Domyślnie używany jest long polling. Dla trybu Webhook ustaw `channels.telegram.webhookUrl` i `channels.telegram.webhookSecret`; opcjonalnie `webhookPath`, `webhookHost`, `webhookPort` (domyślnie `/telegram-webhook`, `127.0.0.1`, `8787`).
|
||||
|
||||
Lokalny nasłuch wiąże się z `127.0.0.1:8787`. Dla publicznego wejścia umieść reverse proxy przed lokalnym portem albo celowo ustaw `webhookHost: "0.0.0.0"`.
|
||||
Lokalny listener wiąże się z `127.0.0.1:8787`. Dla publicznego ruchu przychodzącego umieść reverse proxy przed lokalnym portem albo celowo ustaw `webhookHost: "0.0.0.0"`.
|
||||
|
||||
Tryb webhooka weryfikuje zabezpieczenia żądania, tajny token Telegram i treść JSON przed zwróceniem `200` do Telegram.
|
||||
Następnie OpenClaw przetwarza aktualizację asynchronicznie przez te same pasma bota dla czatu/tematu, których używa długie odpytywanie, więc wolne tury agenta nie blokują potwierdzenia dostarczenia Telegram.
|
||||
Tryb Webhook sprawdza zabezpieczenia żądania, tajny token Telegram i treść JSON przed zwróceniem `200` do Telegram.
|
||||
Następnie OpenClaw przetwarza aktualizację asynchronicznie przez te same pasy bota per czat/per temat, których używa long polling, więc wolne tury agenta nie blokują ACK dostarczenia Telegram.
|
||||
|
||||
</Accordion>
|
||||
|
||||
@ -736,18 +773,18 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
- Domyślna wartość `channels.telegram.textChunkLimit` to 4000.
|
||||
- `channels.telegram.chunkMode="newline"` preferuje granice akapitów (puste wiersze) przed dzieleniem według długości.
|
||||
- `channels.telegram.mediaMaxMb` (domyślnie 100) ogranicza rozmiar przychodzących i wychodzących multimediów Telegram.
|
||||
- `channels.telegram.mediaGroupFlushMs` (domyślnie 500) kontroluje, jak długo albumy/grupy multimediów Telegram są buforowane, zanim OpenClaw przekaże je jako jedną wiadomość przychodzącą. Zwiększ tę wartość, jeśli części albumu przychodzą z opóźnieniem; zmniejsz ją, aby ograniczyć opóźnienie odpowiedzi na album.
|
||||
- `channels.telegram.timeoutSeconds` nadpisuje limit czasu klienta API Telegram (jeśli nie ustawiono, obowiązuje domyślna wartość grammY). Klienci bota ograniczają skonfigurowane wartości poniżej 60-sekundowego zabezpieczenia żądania wychodzącego tekstu/wpisywania, aby grammY nie przerwał dostarczania widocznej odpowiedzi, zanim uruchomi się zabezpieczenie transportu i mechanizm awaryjny OpenClaw. Długie odpytywanie nadal używa 45-sekundowego zabezpieczenia żądania `getUpdates`, aby bezczynne odpytywania nie były porzucane bezterminowo.
|
||||
- `channels.telegram.pollingStallThresholdMs` domyślnie wynosi `120000`; dostrajaj w zakresie od `30000` do `600000` tylko przy fałszywie dodatnich restartach zastoju odpytywania.
|
||||
- `channels.telegram.mediaGroupFlushMs` (domyślnie 500) kontroluje, jak długo albumy/grupy multimediów Telegram są buforowane, zanim OpenClaw wyśle je jako jedną wiadomość przychodzącą. Zwiększ tę wartość, jeśli części albumu przychodzą z opóźnieniem; zmniejsz ją, aby ograniczyć opóźnienie odpowiedzi na album.
|
||||
- `channels.telegram.timeoutSeconds` nadpisuje timeout klienta API Telegram (jeśli nie ustawiono, obowiązuje domyślna wartość grammY). Klienci bota ograniczają skonfigurowane wartości poniżej 60-sekundowej straży żądań wychodzących tekstu/pisania, aby grammY nie przerwał dostarczenia widocznej odpowiedzi, zanim straż transportu OpenClaw i fallback zdążą zadziałać. Long polling nadal używa 45-sekundowej straży żądania `getUpdates`, aby bezczynne odpytywania nie były porzucane w nieskończoność.
|
||||
- `channels.telegram.pollingStallThresholdMs` domyślnie wynosi `120000`; ustawiaj w zakresie od `30000` do `600000` tylko przy fałszywie dodatnich restartach z powodu zastoju polling.
|
||||
- historia kontekstu grupy używa `channels.telegram.historyLimit` albo `messages.groupChat.historyLimit` (domyślnie 50); `0` wyłącza.
|
||||
- dodatkowy kontekst odpowiedzi/cytatu/przekazania jest obecnie przekazywany tak, jak został odebrany.
|
||||
- listy dozwolonych Telegram głównie kontrolują, kto może wyzwolić agenta, a nie stanowią pełnej granicy redakcji dodatkowego kontekstu.
|
||||
- dodatkowy kontekst odpowiedzi/cytatu/przekazania jest obecnie przekazywany w takiej postaci, w jakiej został odebrany.
|
||||
- listy dozwolonych Telegram przede wszystkim kontrolują, kto może wyzwolić agenta, a nie stanowią pełnej granicy redakcji dodatkowego kontekstu.
|
||||
- Kontrole historii DM:
|
||||
- `channels.telegram.dmHistoryLimit`
|
||||
- `channels.telegram.dms["<user_id>"].historyLimit`
|
||||
- Konfiguracja `channels.telegram.retry` dotyczy helperów wysyłania Telegram (CLI/narzędzia/akcje) dla możliwych do odzyskania błędów wychodzącego API. Dostarczanie końcowej odpowiedzi przychodzącej także używa ograniczonego bezpiecznego ponawiania wysyłki przy błędach Telegram przed połączeniem, ale nie ponawia niejednoznacznych kopert sieciowych po wysłaniu, które mogłyby zduplikować widoczne wiadomości.
|
||||
- Konfiguracja `channels.telegram.retry` ma zastosowanie do helperów wysyłania Telegram (CLI/narzędzia/akcje) dla możliwych do odzyskania błędów wychodzącego API. Dostarczenie końcowej odpowiedzi przychodzącej także używa ograniczonego bezpiecznego ponowienia wysyłki dla awarii Telegram przed połączeniem, ale nie ponawia niejednoznacznych kopert sieciowych po wysłaniu, które mogłyby zduplikować widoczne wiadomości.
|
||||
|
||||
Cel wysyłki CLI może być numerycznym identyfikatorem czatu albo nazwą użytkownika:
|
||||
Cel wysyłki CLI może być numerycznym ID czatu albo nazwą użytkownika:
|
||||
|
||||
```bash
|
||||
openclaw message send --channel telegram --target 123456789 --message "hi"
|
||||
@ -773,9 +810,9 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \
|
||||
|
||||
Wysyłanie Telegram obsługuje także:
|
||||
|
||||
- `--presentation` z blokami `buttons` dla klawiatur inline, gdy `channels.telegram.capabilities.inlineButtons` na to pozwala
|
||||
- `--presentation` z blokami `buttons` dla klawiatur inline, gdy pozwala na to `channels.telegram.capabilities.inlineButtons`
|
||||
- `--pin` albo `--delivery '{"pin":true}'`, aby zażądać przypiętego dostarczenia, gdy bot może przypinać w tym czacie
|
||||
- `--force-document`, aby wysyłać wychodzące obrazy i GIF-y jako dokumenty zamiast skompresowanych zdjęć lub przesyłek animowanych multimediów
|
||||
- `--force-document`, aby wysyłać wychodzące obrazy i GIF-y jako dokumenty zamiast skompresowanych zdjęć lub przesyłanych animowanych multimediów
|
||||
|
||||
Bramkowanie akcji:
|
||||
|
||||
@ -785,36 +822,36 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Zatwierdzenia exec w Telegram">
|
||||
Telegram obsługuje zatwierdzenia exec w DM-ach zatwierdzających i opcjonalnie może publikować monity w czacie lub temacie źródłowym. Zatwierdzający muszą być numerycznymi identyfikatorami użytkowników Telegram.
|
||||
Telegram obsługuje zatwierdzenia exec w DM zatwierdzających i może opcjonalnie publikować monity w czacie lub temacie źródłowym. Zatwierdzający muszą być numerycznymi identyfikatorami użytkowników Telegram.
|
||||
|
||||
Ścieżka konfiguracji:
|
||||
|
||||
- `channels.telegram.execApprovals.enabled` (włącza się automatycznie, gdy możliwe jest rozpoznanie co najmniej jednego zatwierdzającego)
|
||||
- `channels.telegram.execApprovals.approvers` (wraca do numerycznych identyfikatorów właścicieli z `commands.ownerAllowFrom`)
|
||||
- `channels.telegram.execApprovals.enabled` (włącza się automatycznie, gdy da się rozwiązać co najmniej jednego zatwierdzającego)
|
||||
- `channels.telegram.execApprovals.approvers` (używa awaryjnie numerycznych ID właścicieli z `commands.ownerAllowFrom`)
|
||||
- `channels.telegram.execApprovals.target`: `dm` (domyślnie) | `channel` | `both`
|
||||
- `agentFilter`, `sessionFilter`
|
||||
|
||||
`channels.telegram.allowFrom`, `groupAllowFrom` i `defaultTo` kontrolują, kto może rozmawiać z botem i gdzie bot wysyła zwykłe odpowiedzi. Nie czynią one nikogo zatwierdzającym exec. Pierwsze zatwierdzone parowanie DM inicjuje `commands.ownerAllowFrom`, gdy nie istnieje jeszcze właściciel poleceń, więc konfiguracja z jednym właścicielem nadal działa bez duplikowania identyfikatorów w `execApprovals.approvers`.
|
||||
`channels.telegram.allowFrom`, `groupAllowFrom` i `defaultTo` kontrolują, kto może rozmawiać z botem i gdzie bot wysyła zwykłe odpowiedzi. Nie czynią nikogo zatwierdzającym exec. Pierwsze zatwierdzone parowanie DM inicjalizuje `commands.ownerAllowFrom`, gdy nie istnieje jeszcze właściciel poleceń, więc konfiguracja z jednym właścicielem nadal działa bez duplikowania ID pod `execApprovals.approvers`.
|
||||
|
||||
Dostarczenie kanałem pokazuje tekst polecenia na czacie; włączaj `channel` albo `both` tylko w zaufanych grupach/tematach. Gdy monit trafia do tematu forum, OpenClaw zachowuje temat dla monitu zatwierdzenia i działania następczego. Zatwierdzenia exec domyślnie wygasają po 30 minutach.
|
||||
Dostarczenie do kanału pokazuje tekst polecenia na czacie; włączaj `channel` albo `both` tylko w zaufanych grupach/tematach. Gdy monit trafia do tematu forum, OpenClaw zachowuje temat dla monitu zatwierdzenia i dalszej wiadomości. Zatwierdzenia exec domyślnie wygasają po 30 minutach.
|
||||
|
||||
Przyciski zatwierdzania inline także wymagają, aby `channels.telegram.capabilities.inlineButtons` pozwalało na docelową powierzchnię (`dm`, `group` albo `all`). Identyfikatory zatwierdzeń z prefiksem `plugin:` są rozwiązywane przez zatwierdzenia pluginów; pozostałe najpierw przez zatwierdzenia exec.
|
||||
Przyciski zatwierdzania inline także wymagają, aby `channels.telegram.capabilities.inlineButtons` pozwalało na docelową powierzchnię (`dm`, `group` albo `all`). ID zatwierdzeń z prefiksem `plugin:` są rozwiązywane przez zatwierdzenia Plugin; pozostałe są najpierw rozwiązywane przez zatwierdzenia exec.
|
||||
|
||||
Zobacz [zatwierdzenia exec](/pl/tools/exec-approvals).
|
||||
Zobacz [Zatwierdzenia exec](/pl/tools/exec-approvals).
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## Kontrole odpowiedzi na błędy
|
||||
|
||||
Gdy agent napotka błąd dostarczenia lub dostawcy, Telegram może odpowiedzieć tekstem błędu albo go ukryć. Dwa klucze konfiguracji kontrolują to zachowanie:
|
||||
Gdy agent napotka błąd dostarczenia lub dostawcy, Telegram może odpowiedzieć tekstem błędu albo go pominąć. To zachowanie kontrolują dwa klucze konfiguracji:
|
||||
|
||||
| Klucz | Wartości | Domyślnie | Opis |
|
||||
| ----------------------------------- | ----------------- | --------- | --------------------------------------------------------------------------------------------- |
|
||||
| `channels.telegram.errorPolicy` | `reply`, `silent` | `reply` | `reply` wysyła przyjazny komunikat błędu do czatu. `silent` całkowicie ukrywa odpowiedzi na błędy. |
|
||||
| `channels.telegram.errorCooldownMs` | liczba (ms) | `60000` | Minimalny czas między odpowiedziami na błędy do tego samego czatu. Zapobiega spamowi błędów podczas awarii. |
|
||||
| Klucz | Wartości | Domyślne | Opis |
|
||||
| ----------------------------------- | ----------------- | -------- | ----------------------------------------------------------------------------------------------------- |
|
||||
| `channels.telegram.errorPolicy` | `reply`, `silent` | `reply` | `reply` wysyła przyjazny komunikat błędu do czatu. `silent` całkowicie pomija odpowiedzi na błędy. |
|
||||
| `channels.telegram.errorCooldownMs` | number (ms) | `60000` | Minimalny czas między odpowiedziami o błędach do tego samego czatu. Zapobiega spamowi błędów podczas awarii. |
|
||||
|
||||
Obsługiwane są nadpisania dla kont, grup i tematów (to samo dziedziczenie co w innych kluczach konfiguracji Telegram).
|
||||
Obsługiwane są nadpisania per konto, per grupa i per temat (takie samo dziedziczenie jak w innych kluczach konfiguracji Telegram).
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -841,7 +878,7 @@ Obsługiwane są nadpisania dla kont, grup i tematów (to samo dziedziczenie co
|
||||
- BotFather: `/setprivacy` -> Disable
|
||||
- następnie usuń i ponownie dodaj bota do grupy
|
||||
- `openclaw channels status` ostrzega, gdy konfiguracja oczekuje wiadomości grupowych bez wzmianki.
|
||||
- `openclaw channels status --probe` może sprawdzić jawne numeryczne identyfikatory grup; wildcard `"*"` nie może zostać sprawdzony pod kątem członkostwa.
|
||||
- `openclaw channels status --probe` może sprawdzać jawne numeryczne ID grup; wildcard `"*"` nie może być sprawdzony pod kątem członkostwa.
|
||||
- szybki test sesji: `/activation always`.
|
||||
|
||||
</Accordion>
|
||||
@ -850,41 +887,41 @@ Obsługiwane są nadpisania dla kont, grup i tematów (to samo dziedziczenie co
|
||||
|
||||
- gdy istnieje `channels.telegram.groups`, grupa musi być wymieniona (albo zawierać `"*"`)
|
||||
- zweryfikuj członkostwo bota w grupie
|
||||
- przejrzyj logi: `openclaw logs --follow` pod kątem powodów pomijania
|
||||
- przejrzyj logi: `openclaw logs --follow`, aby poznać powody pominięcia
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Polecenia działają częściowo albo wcale">
|
||||
|
||||
- autoryzuj swoją tożsamość nadawcy (parowanie i/lub numeryczne `allowFrom`)
|
||||
- autoryzacja poleceń nadal obowiązuje, nawet gdy polityka grupy to `open`
|
||||
- `setMyCommands failed` z `BOT_COMMANDS_TOO_MUCH` oznacza, że natywne menu ma zbyt wiele wpisów; ogranicz polecenia pluginów/skill/custom albo wyłącz natywne menu
|
||||
- Wywołania startowe `deleteMyCommands` / `setMyCommands` oraz wywołania wpisywania `sendChatAction` są ograniczone czasowo i ponawiane raz przez awaryjny transport Telegram po przekroczeniu limitu czasu żądania. Utrzymujące się błędy sieciowe/fetch zwykle wskazują na problemy z osiągalnością DNS/HTTPS do `api.telegram.org`
|
||||
- autoryzuj tożsamość nadawcy (parowanie i/lub numeryczne `allowFrom`)
|
||||
- autoryzacja poleceń nadal obowiązuje nawet wtedy, gdy zasada grupy to `open`
|
||||
- `setMyCommands failed` z `BOT_COMMANDS_TOO_MUCH` oznacza, że natywne menu ma zbyt wiele pozycji; ogranicz polecenia plugin/skill/niestandardowe albo wyłącz natywne menu
|
||||
- wywołania startowe `deleteMyCommands` / `setMyCommands` oraz wywołania wpisywania `sendChatAction` są ograniczone czasowo i ponawiane raz przez awaryjny transport Telegram w razie przekroczenia limitu czasu żądania. Utrzymujące się błędy sieciowe/fetch zwykle wskazują na problemy z osiągalnością DNS/HTTPS do `api.telegram.org`
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Uruchomienie zgłasza nieautoryzowany token">
|
||||
<Accordion title="Uruchamianie zgłasza nieautoryzowany token">
|
||||
|
||||
- `getMe returned 401` to błąd uwierzytelniania Telegram dla skonfigurowanego tokenu bota.
|
||||
- Skopiuj ponownie lub wygeneruj ponownie token bota w BotFather, a następnie zaktualizuj `channels.telegram.botToken`, `channels.telegram.tokenFile`, `channels.telegram.accounts.<id>.botToken` albo `TELEGRAM_BOT_TOKEN` dla konta domyślnego.
|
||||
- `deleteWebhook 401 Unauthorized` podczas uruchamiania także jest błędem uwierzytelniania; potraktowanie go jako „brak istniejącego webhooka” tylko odroczyłoby ten sam błąd nieprawidłowego tokenu do późniejszych wywołań API.
|
||||
- Skopiuj ponownie albo wygeneruj ponownie token bota w BotFather, a następnie zaktualizuj `channels.telegram.botToken`, `channels.telegram.tokenFile`, `channels.telegram.accounts.<id>.botToken` albo `TELEGRAM_BOT_TOKEN` dla konta domyślnego.
|
||||
- `deleteWebhook 401 Unauthorized` podczas uruchamiania również jest błędem uwierzytelniania; potraktowanie go jako „nie istnieje żaden webhook” tylko odroczyłoby tę samą awarię złego tokenu do późniejszych wywołań API.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Niestabilność odpytywania lub sieci">
|
||||
|
||||
- Node 22+ + niestandardowy fetch/proxy może wywołać natychmiastowe przerwanie, jeśli typy AbortSignal są niezgodne.
|
||||
- Niektóre hosty najpierw rozwiązują `api.telegram.org` na IPv6; niesprawne wyjście IPv6 może powodować sporadyczne błędy API Telegram.
|
||||
- Jeśli logi zawierają `TypeError: fetch failed` albo `Network request for 'getUpdates' failed!`, OpenClaw ponawia je teraz jako możliwe do odzyskania błędy sieciowe.
|
||||
- Podczas uruchamiania odpytywania OpenClaw ponownie używa udanej próby startowej `getMe` dla grammY, aby runner nie potrzebował drugiego `getMe` przed pierwszym `getUpdates`.
|
||||
- Jeśli `deleteWebhook` zakończy się przejściowym błędem sieci podczas uruchamiania odpytywania, OpenClaw przechodzi do długiego odpytywania zamiast wykonywać kolejne kontrolne wywołanie przed odpytywaniem. Nadal aktywny webhook ujawnia się jako konflikt `getUpdates`; OpenClaw przebudowuje wtedy transport Telegram i ponawia czyszczenie webhooka.
|
||||
- Jeśli gniazda Telegram są odświeżane w krótkim, stałym rytmie, sprawdź, czy `channels.telegram.timeoutSeconds` nie ma niskiej wartości; klienci botów ograniczają skonfigurowane wartości poniżej zabezpieczeń żądań wychodzących i `getUpdates`, ale starsze wydania mogły przerywać każde odpytywanie lub odpowiedź, gdy ustawiono ją poniżej tych zabezpieczeń.
|
||||
- Jeśli logi zawierają `Polling stall detected`, OpenClaw domyślnie ponownie uruchamia odpytywanie i przebudowuje transport Telegram po 120 sekundach bez ukończonej żywotności długiego odpytywania.
|
||||
- `openclaw channels status --probe` i `openclaw doctor` ostrzegają, gdy działające konto odpytywania nie ukończyło `getUpdates` po okresie karencji uruchomienia, gdy działające konto webhooka nie ukończyło `setWebhook` po okresie karencji uruchomienia albo gdy ostatnia udana aktywność transportu odpytywania jest nieaktualna.
|
||||
- Zwiększ `channels.telegram.pollingStallThresholdMs` tylko wtedy, gdy długo działające wywołania `getUpdates` są zdrowe, ale host nadal zgłasza fałszywe restarty z powodu zastoju odpytywania. Utrzymujące się zastoje zwykle wskazują na problemy z proxy, DNS, IPv6 lub wyjściem TLS między hostem a `api.telegram.org`.
|
||||
- Telegram honoruje także zmienne środowiskowe proxy procesu dla transportu Bot API, w tym `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY` oraz ich warianty pisane małymi literami. `NO_PROXY` / `no_proxy` nadal mogą omijać `api.telegram.org`.
|
||||
- Jeśli zarządzane proxy OpenClaw jest skonfigurowane przez `OPENCLAW_PROXY_URL` dla środowiska usługi i nie ma standardowej zmiennej środowiskowej proxy, Telegram także używa tego URL dla transportu Bot API.
|
||||
- Na hostach VPS z niestabilnym bezpośrednim wyjściem/TLS kieruj wywołania API Telegram przez `channels.telegram.proxy`:
|
||||
- Node 22+ + niestandardowy fetch/proxy mogą wywołać natychmiastowe zachowanie przerywania, jeśli typy AbortSignal nie pasują do siebie.
|
||||
- Niektóre hosty najpierw rozwiązują `api.telegram.org` do IPv6; uszkodzony ruch wychodzący IPv6 może powodować sporadyczne błędy API Telegram.
|
||||
- Jeśli logi zawierają `TypeError: fetch failed` albo `Network request for 'getUpdates' failed!`, OpenClaw ponawia je teraz jako odwracalne błędy sieciowe.
|
||||
- Podczas uruchamiania odpytywania OpenClaw ponownie używa udanej startowej próby `getMe` dla grammY, więc runner nie potrzebuje drugiego `getMe` przed pierwszym `getUpdates`.
|
||||
- Jeśli `deleteWebhook` zakończy się przejściowym błędem sieciowym podczas uruchamiania odpytywania, OpenClaw przechodzi do długiego odpytywania zamiast wykonywać kolejne przedodpytywaniowe wywołanie płaszczyzny sterowania. Nadal aktywny webhook ujawnia się jako konflikt `getUpdates`; wtedy OpenClaw odbudowuje transport Telegram i ponawia czyszczenie webhooka.
|
||||
- Jeśli gniazda Telegram są odtwarzane w krótkim, stałym rytmie, sprawdź, czy `channels.telegram.timeoutSeconds` nie ma niskiej wartości; klienci botów ograniczają skonfigurowane wartości poniżej zabezpieczeń żądań wychodzących i `getUpdates`, ale starsze wydania mogły przerywać każde odpytywanie albo odpowiedź, gdy ta wartość była ustawiona poniżej tych zabezpieczeń.
|
||||
- Jeśli logi zawierają `Polling stall detected`, OpenClaw domyślnie restartuje odpytywanie i odbudowuje transport Telegram po 120 sekundach bez zakończonej żywotności długiego odpytywania.
|
||||
- `openclaw channels status --probe` i `openclaw doctor` ostrzegają, gdy uruchomione konto odpytywania nie ukończyło `getUpdates` po okresie łaski uruchomienia, gdy uruchomione konto webhooka nie ukończyło `setWebhook` po okresie łaski uruchomienia albo gdy ostatnia udana aktywność transportu odpytywania jest nieaktualna.
|
||||
- Zwiększ `channels.telegram.pollingStallThresholdMs` tylko wtedy, gdy długotrwałe wywołania `getUpdates` są zdrowe, ale host nadal zgłasza fałszywe restarty z powodu zastoju odpytywania. Utrzymujące się zastoje zwykle wskazują na problemy z proxy, DNS, IPv6 albo ruchem wychodzącym TLS między hostem a `api.telegram.org`.
|
||||
- Telegram uwzględnia też zmienne env proxy procesu dla transportu Bot API, w tym `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY` oraz ich warianty pisane małymi literami. `NO_PROXY` / `no_proxy` nadal mogą omijać `api.telegram.org`.
|
||||
- Jeśli zarządzany proxy OpenClaw jest skonfigurowany przez `OPENCLAW_PROXY_URL` dla środowiska usługi i nie ma standardowej zmiennej env proxy, Telegram również używa tego URL-a dla transportu Bot API.
|
||||
- Na hostach VPS z niestabilnym bezpośrednim ruchem wychodzącym/TLS kieruj wywołania API Telegram przez `channels.telegram.proxy`:
|
||||
|
||||
```yaml
|
||||
channels:
|
||||
@ -892,8 +929,8 @@ channels:
|
||||
proxy: socks5://<user>:<password>@proxy-host:1080
|
||||
```
|
||||
|
||||
- Node 22+ domyślnie używa `autoSelectFamily=true` (z wyjątkiem WSL2). Kolejność wyników DNS Telegram honoruje najpierw `OPENCLAW_TELEGRAM_DNS_RESULT_ORDER`, następnie `channels.telegram.network.dnsResultOrder`, a potem domyślną wartość procesu, taką jak `NODE_OPTIONS=--dns-result-order=ipv4first`; jeśli żadna nie ma zastosowania, Node 22+ wraca do `ipv4first`.
|
||||
- Jeśli host to WSL2 albo wyraźnie działa lepiej w trybie tylko IPv4, wymuś wybór rodziny:
|
||||
- Node 22+ domyślnie używa `autoSelectFamily=true` (z wyjątkiem WSL2). Kolejność wyników DNS Telegram uwzględnia kolejno `OPENCLAW_TELEGRAM_DNS_RESULT_ORDER`, potem `channels.telegram.network.dnsResultOrder`, a następnie domyślne ustawienie procesu, takie jak `NODE_OPTIONS=--dns-result-order=ipv4first`; jeśli żadne z nich nie ma zastosowania, Node 22+ wraca do `ipv4first`.
|
||||
- Jeśli host to WSL2 albo wyraźnie działa lepiej przy zachowaniu wyłącznie IPv4, wymuś wybór rodziny:
|
||||
|
||||
```yaml
|
||||
channels:
|
||||
@ -903,9 +940,9 @@ channels:
|
||||
```
|
||||
|
||||
- Odpowiedzi z zakresu benchmarkowego RFC 2544 (`198.18.0.0/15`) są już domyślnie dozwolone
|
||||
dla pobierania multimediów Telegram. Jeśli zaufany fake-IP lub
|
||||
przezroczyste proxy przepisuje `api.telegram.org` na inny
|
||||
prywatny/wewnętrzny/specjalnego użytku adres podczas pobierania multimediów, możesz włączyć
|
||||
dla pobrań multimediów Telegram. Jeśli zaufany fake-IP albo
|
||||
transparentny proxy przepisuje `api.telegram.org` na inny
|
||||
prywatny/wewnętrzny/specjalnego użycia adres podczas pobierania multimediów, możesz włączyć
|
||||
obejście tylko dla Telegram:
|
||||
|
||||
```yaml
|
||||
@ -915,25 +952,25 @@ channels:
|
||||
dangerouslyAllowPrivateNetwork: true
|
||||
```
|
||||
|
||||
- To samo włączenie jest dostępne dla konta pod
|
||||
- Ta sama opcja włączenia jest dostępna dla każdego konta w
|
||||
`channels.telegram.accounts.<accountId>.network.dangerouslyAllowPrivateNetwork`.
|
||||
- Jeśli proxy rozwiązuje hosty multimediów Telegram na `198.18.x.x`, najpierw pozostaw
|
||||
niebezpieczną flagę wyłączoną. Multimedia Telegram już domyślnie zezwalają na zakres
|
||||
benchmarkowy RFC 2544.
|
||||
- Jeśli proxy rozwiązuje hosty multimediów Telegram na `198.18.x.x`, najpierw zostaw
|
||||
niebezpieczną flagę wyłączoną. Multimedia Telegram już domyślnie dopuszczają
|
||||
zakres benchmarkowy RFC 2544.
|
||||
|
||||
<Warning>
|
||||
`channels.telegram.network.dangerouslyAllowPrivateNetwork` osłabia zabezpieczenia Telegram
|
||||
przed SSRF dla multimediów. Używaj tego tylko w zaufanych środowiskach proxy kontrolowanych przez operatora,
|
||||
takich jak routing fake-IP Clash, Mihomo lub Surge, gdy syntetyzują
|
||||
prywatne lub specjalnego użytku odpowiedzi spoza zakresu benchmarkowego RFC 2544.
|
||||
Pozostaw wyłączone dla normalnego publicznego dostępu do Telegram przez internet.
|
||||
`channels.telegram.network.dangerouslyAllowPrivateNetwork` osłabia zabezpieczenia SSRF
|
||||
multimediów Telegram. Używaj jej tylko w zaufanych, kontrolowanych przez operatora środowiskach proxy,
|
||||
takich jak routing fake-IP Clash, Mihomo albo Surge, gdy syntetyzują
|
||||
odpowiedzi prywatne albo specjalnego użycia poza zakresem benchmarkowym RFC 2544.
|
||||
Pozostaw ją wyłączoną dla zwykłego publicznego dostępu Telegram przez internet.
|
||||
</Warning>
|
||||
|
||||
- Nadpisania środowiskowe (tymczasowe):
|
||||
- `OPENCLAW_TELEGRAM_DISABLE_AUTO_SELECT_FAMILY=1`
|
||||
- `OPENCLAW_TELEGRAM_ENABLE_AUTO_SELECT_FAMILY=1`
|
||||
- `OPENCLAW_TELEGRAM_DNS_RESULT_ORDER=ipv4first`
|
||||
- Sprawdź odpowiedzi DNS:
|
||||
- Zweryfikuj odpowiedzi DNS:
|
||||
|
||||
```bash
|
||||
dig +short api.telegram.org A
|
||||
@ -949,18 +986,18 @@ Więcej pomocy: [Rozwiązywanie problemów z kanałami](/pl/channels/troubleshoo
|
||||
|
||||
Główne odniesienie: [Odniesienie konfiguracji - Telegram](/pl/gateway/config-channels#telegram).
|
||||
|
||||
<Accordion title="Pola Telegram o wysokiej wartości diagnostycznej">
|
||||
<Accordion title="Najważniejsze pola Telegram">
|
||||
|
||||
- uruchamianie/uwierzytelnianie: `enabled`, `botToken`, `tokenFile`, `accounts.*` (`tokenFile` musi wskazywać zwykły plik; dowiązania symboliczne są odrzucane)
|
||||
- kontrola dostępu: `dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`, `groups`, `groups.*.topics.*`, `bindings[]` najwyższego poziomu (`type: "acp"`)
|
||||
- kontrola dostępu: `dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`, `groups`, `groups.*.topics.*`, najwyższego poziomu `bindings[]` (`type: "acp"`)
|
||||
- zatwierdzenia exec: `execApprovals`, `accounts.*.execApprovals`
|
||||
- polecenie/menu: `commands.native`, `commands.nativeSkills`, `customCommands`
|
||||
- polecenia/menu: `commands.native`, `commands.nativeSkills`, `customCommands`
|
||||
- wątki/odpowiedzi: `replyToMode`, `dm.threadReplies`, `direct.*.threadReplies`
|
||||
- streaming: `streaming` (podgląd), `streaming.preview.toolProgress`, `blockStreaming`
|
||||
- strumieniowanie: `streaming` (podgląd), `streaming.preview.toolProgress`, `blockStreaming`
|
||||
- formatowanie/dostarczanie: `textChunkLimit`, `chunkMode`, `linkPreview`, `responsePrefix`
|
||||
- multimedia/sieć: `mediaMaxMb`, `mediaGroupFlushMs`, `timeoutSeconds`, `pollingStallThresholdMs`, `retry`, `network.autoSelectFamily`, `network.dangerouslyAllowPrivateNetwork`, `proxy`
|
||||
- niestandardowy główny API: `apiRoot` (tylko główny Bot API; nie dołączaj `/bot<TOKEN>`)
|
||||
- webhook: `webhookUrl`, `webhookSecret`, `webhookPath`, `webhookHost`
|
||||
- niestandardowy katalog główny API: `apiRoot` (tylko katalog główny Bot API; nie dołączaj `/bot<TOKEN>`)
|
||||
- Webhook: `webhookUrl`, `webhookSecret`, `webhookPath`, `webhookHost`
|
||||
- akcje/możliwości: `capabilities.inlineButtons`, `actions.sendMessage|editMessage|deleteMessage|reactions|sticker`
|
||||
- reakcje: `reactionNotifications`, `reactionLevel`
|
||||
- błędy: `errorPolicy`, `errorCooldownMs`
|
||||
@ -969,26 +1006,26 @@ Główne odniesienie: [Odniesienie konfiguracji - Telegram](/pl/gateway/config-c
|
||||
</Accordion>
|
||||
|
||||
<Note>
|
||||
Pierwszeństwo wielu kont: gdy skonfigurowano co najmniej dwa identyfikatory kont, ustaw `channels.telegram.defaultAccount` (albo dołącz `channels.telegram.accounts.default`), aby jawnie określić domyślne routowanie. W przeciwnym razie OpenClaw wraca do pierwszego znormalizowanego identyfikatora konta, a `openclaw doctor` ostrzega. Nazwane konta dziedziczą `channels.telegram.allowFrom` / `groupAllowFrom`, ale nie wartości `accounts.default.*`.
|
||||
Kolejność pierwszeństwa wielu kont: gdy skonfigurowane są co najmniej dwa identyfikatory kont, ustaw `channels.telegram.defaultAccount` (albo dodaj `channels.telegram.accounts.default`), aby jawnie określić domyślny routing. W przeciwnym razie OpenClaw wraca do pierwszego znormalizowanego identyfikatora konta, a `openclaw doctor` ostrzega. Nazwane konta dziedziczą `channels.telegram.allowFrom` / `groupAllowFrom`, ale nie wartości `accounts.default.*`.
|
||||
</Note>
|
||||
|
||||
## Powiązane
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Parowanie" icon="link" href="/pl/channels/pairing">
|
||||
Sparuj użytkownika Telegram z gatewayem.
|
||||
Sparuj użytkownika Telegram z Gateway.
|
||||
</Card>
|
||||
<Card title="Grupy" icon="users" href="/pl/channels/groups">
|
||||
Zachowanie listy dozwolonych grup i tematów.
|
||||
</Card>
|
||||
<Card title="Routowanie kanałów" icon="route" href="/pl/channels/channel-routing">
|
||||
<Card title="Routing kanałów" icon="route" href="/pl/channels/channel-routing">
|
||||
Kieruj wiadomości przychodzące do agentów.
|
||||
</Card>
|
||||
<Card title="Bezpieczeństwo" icon="shield" href="/pl/gateway/security">
|
||||
Model zagrożeń i wzmacnianie zabezpieczeń.
|
||||
</Card>
|
||||
<Card title="Routowanie wielu agentów" icon="sitemap" href="/pl/concepts/multi-agent">
|
||||
Mapuj grupy i tematy do agentów.
|
||||
<Card title="Routing wielu agentów" icon="sitemap" href="/pl/concepts/multi-agent">
|
||||
Mapuj grupy i tematy na agentów.
|
||||
</Card>
|
||||
<Card title="Rozwiązywanie problemów" icon="wrench" href="/pl/channels/troubleshooting">
|
||||
Diagnostyka międzykanałowa.
|
||||
|
||||
492
docs/pl/ci.md
492
docs/pl/ci.md
@ -1,94 +1,94 @@
|
||||
---
|
||||
read_when:
|
||||
- Musisz zrozumieć, dlaczego zadanie CI zostało uruchomione albo dlaczego nie zostało uruchomione
|
||||
- Debugujesz nieudane sprawdzenie GitHub Actions
|
||||
- Musisz zrozumieć, dlaczego zadanie CI zostało albo nie zostało uruchomione
|
||||
- Debugujesz kończące się niepowodzeniem sprawdzenie GitHub Actions
|
||||
- Koordynujesz uruchomienie lub ponowne uruchomienie walidacji wydania
|
||||
- Zmieniasz wywoływanie ClawSweeper lub przekazywanie aktywności GitHub
|
||||
- Zmieniasz wysyłanie ClawSweeper lub przekazywanie aktywności GitHub
|
||||
summary: Graf zadań CI, bramki zakresu, parasole wydań i lokalne odpowiedniki poleceń
|
||||
title: Potok CI
|
||||
x-i18n:
|
||||
generated_at: "2026-05-03T21:27:44Z"
|
||||
generated_at: "2026-05-04T07:03:02Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: e07fc44aa844cb66ce529c570cbbbbf502a61bcbcbc3d9488557abb459ef7678
|
||||
source_hash: 72959d0feaf1339f01c9da263153fd89cc4727da6f928933819931991222714d
|
||||
source_path: ci.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
OpenClaw CI uruchamia się przy każdym pushu do `main` i przy każdym pull requeście. Zadanie `preflight` klasyfikuje diff i wyłącza kosztowne ścieżki, gdy zmieniły się tylko niepowiązane obszary. Ręczne uruchomienia `workflow_dispatch` celowo omijają inteligentne zawężanie zakresu i rozwijają pełny graf dla kandydatów do wydania oraz szerokiej walidacji. Ścieżki Android pozostają opcjonalne przez `include_android`. Pokrycie Plugin wyłącznie dla wydań znajduje się w osobnym workflow [`Wersja przedpremierowa Plugin`](#plugin-prerelease) i uruchamia się tylko z [`Pełnej walidacji wydania`](#full-release-validation) albo po jawnym ręcznym dispatchu.
|
||||
OpenClaw CI działa przy każdym wypchnięciu do `main` i każdym pull request. Zadanie `preflight` klasyfikuje diff i wyłącza kosztowne ścieżki, gdy zmieniły się tylko niepowiązane obszary. Ręczne uruchomienia `workflow_dispatch` celowo pomijają inteligentne zawężanie zakresu i rozwijają pełny graf dla kandydatów do wydania oraz szerokiej walidacji. Ścieżki Androida pozostają opcjonalne przez `include_android`. Pokrycie Plugin dotyczące tylko wydań znajduje się w osobnym workflow [`Plugin Prerelease`](#plugin-prerelease) i działa tylko z [`Full Release Validation`](#full-release-validation) albo z jawnego ręcznego uruchomienia.
|
||||
|
||||
## Przegląd potoku
|
||||
|
||||
| Zadanie | Cel | Kiedy się uruchamia |
|
||||
| -------------------------------- | ----------------------------------------------------------------------------------------------------------------- | ------------------------------------------- |
|
||||
| `preflight` | Wykrywa zmiany wyłącznie w dokumentacji, zmienione zakresy, zmienione rozszerzenia i buduje manifest CI | Zawsze przy pushach i PR-ach innych niż draft |
|
||||
| `security-scm-fast` | Wykrywanie kluczy prywatnych i audyt workflow przez `zizmor` | Zawsze przy pushach i PR-ach innych niż draft |
|
||||
| `security-dependency-audit` | Audyt produkcyjnego lockfile bez zależności względem ostrzeżeń npm | Zawsze przy pushach i PR-ach innych niż draft |
|
||||
| `security-fast` | Wymagany agregat dla szybkich zadań bezpieczeństwa | Zawsze przy pushach i PR-ach innych niż draft |
|
||||
| `check-dependencies` | Produkcyjny przebieg Knip tylko dla zależności oraz strażnik listy dozwolonych nieużywanych plików | Zmiany istotne dla Node |
|
||||
| `build-artifacts` | Buduje `dist/`, Control UI, sprawdza zbudowane artefakty i tworzy artefakty wielokrotnego użytku dla kolejnych zadań | Zmiany istotne dla Node |
|
||||
| `checks-fast-core` | Szybkie linuxowe ścieżki poprawności, takie jak kontrole bundled/plugin-contract/protocol | Zmiany istotne dla Node |
|
||||
| `checks-fast-contracts-channels` | Shardowane kontrole kontraktów kanałów ze stabilnym zagregowanym wynikiem sprawdzenia | Zmiany istotne dla Node |
|
||||
| `checks-node-core-test` | Shardy testów Core Node, z wyłączeniem ścieżek kanałów, bundled, kontraktów i rozszerzeń | Zmiany istotne dla Node |
|
||||
| `check` | Shardowany odpowiednik głównej lokalnej bramki: typy produkcyjne, lint, strażniki, typy testów i rygorystyczny smoke | Zmiany istotne dla Node |
|
||||
| `check-additional` | Architektura, shardowany dryf granic/promptów, strażniki rozszerzeń, granica pakietu i gateway watch | Zmiany istotne dla Node |
|
||||
| `build-smoke` | Testy smoke zbudowanego CLI i smoke pamięci startowej | Zmiany istotne dla Node |
|
||||
| `checks` | Weryfikator testów kanałów na zbudowanych artefaktach | Zmiany istotne dla Node |
|
||||
| `checks-node-compat-node22` | Build zgodności z Node 22 i ścieżka smoke | Ręczny dispatch CI dla wydań |
|
||||
| `check-docs` | Formatowanie dokumentacji, lint i kontrole uszkodzonych linków | Zmieniona dokumentacja |
|
||||
| `skills-python` | Ruff + pytest dla Skills wspieranych przez Python | Zmiany istotne dla Skills Python |
|
||||
| `checks-windows` | Testy procesów/ścieżek specyficzne dla Windows oraz regresje wspólnych specyfikatorów importu runtime | Zmiany istotne dla Windows |
|
||||
| `macos-node` | Ścieżka testów TypeScript na macOS używająca wspólnych zbudowanych artefaktów | Zmiany istotne dla macOS |
|
||||
| `macos-swift` | Swift lint, build i testy aplikacji macOS | Zmiany istotne dla macOS |
|
||||
| `android` | Testy jednostkowe Android dla obu wariantów oraz jeden build APK debug | Zmiany istotne dla Android |
|
||||
| `test-performance-agent` | Codzienna optymalizacja wolnych testów przez Codex po zaufanej aktywności | Sukces CI na main albo ręczny dispatch |
|
||||
| `openclaw-performance` | Codzienne/na żądanie raporty wydajności runtime Kova ze ścieżkami mock-provider, deep-profile i live GPT 5.4 | Harmonogram i ręczny dispatch |
|
||||
| Zadanie | Cel | Kiedy działa |
|
||||
| -------------------------------- | --------------------------------------------------------------------------------------------------------- | ----------------------------------- |
|
||||
| `preflight` | Wykrywa zmiany tylko w dokumentacji, zmienione zakresy, zmienione rozszerzenia i buduje manifest CI | Zawsze przy niedraftowych wypchnięciach i PR-ach |
|
||||
| `security-scm-fast` | Wykrywanie kluczy prywatnych i audyt workflow przez `zizmor` | Zawsze przy niedraftowych wypchnięciach i PR-ach |
|
||||
| `security-dependency-audit` | Audyt produkcyjnego lockfile bez instalowania zależności względem zaleceń bezpieczeństwa npm | Zawsze przy niedraftowych wypchnięciach i PR-ach |
|
||||
| `security-fast` | Wymagana agregacja dla szybkich zadań bezpieczeństwa | Zawsze przy niedraftowych wypchnięciach i PR-ach |
|
||||
| `check-dependencies` | Produkcyjne sprawdzenie Knip tylko dla zależności oraz strażnik listy dozwolonych nieużywanych plików | Zmiany istotne dla Node |
|
||||
| `build-artifacts` | Buduje `dist/`, Control UI, sprawdzenia zbudowanych artefaktów i artefakty wielokrotnego użytku dla dalszych zadań | Zmiany istotne dla Node |
|
||||
| `checks-fast-core` | Szybkie linuksowe ścieżki poprawności, takie jak sprawdzenia wbudowanych/kontraktów Plugin/protokołu | Zmiany istotne dla Node |
|
||||
| `checks-fast-contracts-channels` | Shardowane sprawdzenia kontraktów kanałów ze stabilnym zagregowanym wynikiem sprawdzenia | Zmiany istotne dla Node |
|
||||
| `checks-node-core-test` | Shardy testów rdzenia Node, z wyłączeniem ścieżek kanałów, wbudowanych, kontraktów i rozszerzeń | Zmiany istotne dla Node |
|
||||
| `check` | Shardowany odpowiednik głównej lokalnej bramki: typy produkcyjne, lint, strażniki, typy testów i ścisły smoke | Zmiany istotne dla Node |
|
||||
| `check-additional` | Architektura, shardowany drift granic/promptów, strażniki rozszerzeń, granica pakietu i obserwacja Gateway | Zmiany istotne dla Node |
|
||||
| `build-smoke` | Testy smoke zbudowanego CLI i smoke pamięci startowej | Zmiany istotne dla Node |
|
||||
| `checks` | Weryfikator testów kanałów na zbudowanych artefaktach | Zmiany istotne dla Node |
|
||||
| `checks-node-compat-node22` | Ścieżka kompilacji i smoke zgodności z Node 22 | Ręczne uruchomienie CI dla wydań |
|
||||
| `check-docs` | Formatowanie dokumentacji, lint i sprawdzenia uszkodzonych linków | Zmieniona dokumentacja |
|
||||
| `skills-python` | Ruff + pytest dla Skills opartych na Pythonie | Zmiany istotne dla Skills w Pythonie |
|
||||
| `checks-windows` | Testy procesów/ścieżek specyficzne dla Windows oraz współdzielone regresje specyfikatorów importu runtime | Zmiany istotne dla Windows |
|
||||
| `macos-node` | Ścieżka testów TypeScript na macOS używająca współdzielonych zbudowanych artefaktów | Zmiany istotne dla macOS |
|
||||
| `macos-swift` | Lint, kompilacja i testy Swift dla aplikacji macOS | Zmiany istotne dla macOS |
|
||||
| `android` | Testy jednostkowe Androida dla obu wariantów oraz jedna kompilacja debug APK | Zmiany istotne dla Androida |
|
||||
| `test-performance-agent` | Codzienna optymalizacja wolnych testów przez Codex po zaufanej aktywności | Sukces CI na main albo ręczne uruchomienie |
|
||||
| `openclaw-performance` | Codzienne/na żądanie raporty wydajności runtime Kova ze ścieżkami mock-provider, deep-profile i live GPT 5.4 | Harmonogram i ręczne uruchomienie |
|
||||
|
||||
## Kolejność fail-fast
|
||||
## Kolejność szybkiego przerywania
|
||||
|
||||
1. `preflight` decyduje, które ścieżki w ogóle istnieją. Logika `docs-scope` i `changed-scope` to kroki wewnątrz tego zadania, a nie samodzielne zadania.
|
||||
2. `security-scm-fast`, `security-dependency-audit`, `security-fast`, `check`, `check-additional`, `check-docs` i `skills-python` szybko kończą się niepowodzeniem bez czekania na cięższe zadania artefaktów i macierzy platform.
|
||||
3. `build-artifacts` nakłada się z szybkimi ścieżkami Linuksa, aby konsumenci downstream mogli zacząć, gdy tylko wspólny build będzie gotowy.
|
||||
4. Cięższe ścieżki platform i runtime rozwijają się potem: `checks-fast-core`, `checks-fast-contracts-channels`, `checks-node-core-test`, `checks`, `checks-windows`, `macos-node`, `macos-swift` i `android`.
|
||||
2. `security-scm-fast`, `security-dependency-audit`, `security-fast`, `check`, `check-additional`, `check-docs` i `skills-python` kończą się niepowodzeniem szybko, bez czekania na cięższe zadania macierzy artefaktów i platform.
|
||||
3. `build-artifacts` nakłada się z szybkimi ścieżkami Linuxa, dzięki czemu dalsi konsumenci mogą wystartować, gdy tylko współdzielona kompilacja będzie gotowa.
|
||||
4. Cięższe ścieżki platform i runtime rozwijają się później: `checks-fast-core`, `checks-fast-contracts-channels`, `checks-node-core-test`, `checks`, `checks-windows`, `macos-node`, `macos-swift` i `android`.
|
||||
|
||||
GitHub może oznaczać zastąpione zadania jako `cancelled`, gdy nowszy push trafi do tego samego PR-a albo refa `main`. Traktuj to jako szum CI, chyba że najnowsze uruchomienie dla tego samego refa również kończy się niepowodzeniem. Zagregowane kontrole shardów używają `!cancelled() && always()`, więc nadal raportują zwykłe awarie shardów, ale nie ustawiają się w kolejce po tym, jak cały workflow został już zastąpiony. Automatyczny klucz współbieżności CI jest wersjonowany (`CI-v7-*`), więc zombie po stronie GitHuba w starej grupie kolejki nie może bezterminowo blokować nowszych uruchomień main. Ręczne uruchomienia pełnego zestawu używają `CI-manual-v1-*` i nie anulują uruchomień w toku.
|
||||
GitHub może oznaczać zastąpione zadania jako `cancelled`, gdy nowsze wypchnięcie trafi na ten sam PR albo referencję `main`. Traktuj to jako szum CI, chyba że najnowsze uruchomienie dla tej samej referencji również kończy się niepowodzeniem. Zagregowane sprawdzenia shardów używają `!cancelled() && always()`, więc nadal raportują normalne awarie shardów, ale nie ustawiają się w kolejce po tym, jak cały workflow został już zastąpiony. Automatyczny klucz współbieżności CI jest wersjonowany (`CI-v7-*`), więc zombie po stronie GitHub w starej grupie kolejki nie może bez końca blokować nowszych uruchomień main. Ręczne uruchomienia pełnego zestawu używają `CI-manual-v1-*` i nie anulują trwających uruchomień.
|
||||
|
||||
## Zakres i routing
|
||||
## Zakres i trasowanie
|
||||
|
||||
Logika zakresu znajduje się w `scripts/ci-changed-scope.mjs` i jest pokryta testami jednostkowymi w `src/scripts/ci-changed-scope.test.ts`. Ręczny dispatch pomija wykrywanie changed-scope i sprawia, że manifest preflight zachowuje się tak, jakby zmienił się każdy obszar z zakresem.
|
||||
Logika zakresu znajduje się w `scripts/ci-changed-scope.mjs` i jest pokryta testami jednostkowymi w `src/scripts/ci-changed-scope.test.ts`. Ręczne uruchomienie pomija wykrywanie zmienionego zakresu i sprawia, że manifest preflight zachowuje się tak, jakby każdy obszar zakresu się zmienił.
|
||||
|
||||
- **Edycje workflow CI** walidują graf CI Node oraz lint workflow, ale same nie wymuszają natywnych buildów Windows, Android ani macOS; te ścieżki platformowe pozostają ograniczone do zmian źródeł platform.
|
||||
- **Edycje dotyczące wyłącznie routingu CI, wybrane tanie edycje fixture testów core oraz wąskie edycje pomocników/test-routing kontraktów Plugin** używają szybkiej ścieżki manifestu tylko dla Node: `preflight`, bezpieczeństwo i pojedyncze zadanie `checks-fast-core`. Ta ścieżka pomija artefakty buildu, zgodność Node 22, kontrakty kanałów, pełne shardy core, shardy bundled-plugin i dodatkowe macierze strażników, gdy zmiana ogranicza się do powierzchni routingu lub pomocników bezpośrednio ćwiczonych przez szybkie zadanie.
|
||||
- **Kontrole Windows Node** są ograniczone do specyficznych dla Windows wrapperów procesów/ścieżek, pomocników runnerów npm/pnpm/UI, konfiguracji menedżera pakietów i powierzchni workflow CI wykonujących tę ścieżkę; niepowiązane zmiany źródeł, Plugin, install-smoke i tylko testowe pozostają na linuxowych ścieżkach Node.
|
||||
- **Edycje workflow CI** walidują graf CI Node oraz lint workflow, ale same nie wymuszają natywnych kompilacji Windows, Androida ani macOS; te ścieżki platform pozostają zawężone do zmian w źródłach platform.
|
||||
- **Edycje dotyczące tylko trasowania CI, wybrane tanie edycje fixture testów rdzenia oraz wąskie edycje pomocników/test-routing kontraktów Plugin** używają szybkiej ścieżki manifestu tylko dla Node: `preflight`, bezpieczeństwo i pojedyncze zadanie `checks-fast-core`. Ta ścieżka pomija artefakty kompilacji, zgodność Node 22, kontrakty kanałów, pełne shardy rdzenia, shardy wbudowanych Plugin oraz dodatkowe macierze strażników, gdy zmiana jest ograniczona do powierzchni trasowania lub pomocników, które szybkie zadanie ćwiczy bezpośrednio.
|
||||
- **Sprawdzenia Node dla Windows** są zawężone do wrapperów procesów/ścieżek specyficznych dla Windows, pomocników runnerów npm/pnpm/UI, konfiguracji menedżera pakietów oraz powierzchni workflow CI, które wykonują tę ścieżkę; niepowiązane zmiany źródeł, Plugin, install-smoke i tylko testów pozostają na linuksowych ścieżkach Node.
|
||||
|
||||
Najwolniejsze rodziny testów Node są dzielone lub równoważone, aby każde zadanie pozostawało małe bez nadmiernego rezerwowania runnerów: kontrakty kanałów działają jako trzy ważone shardy, szybkie/wspierające ścieżki jednostkowe core działają osobno, infrastruktura runtime core jest podzielona między shardy stanu i procesów/konfiguracji, auto-reply działa jako zrównoważeni workerzy (z poddrzewem odpowiedzi podzielonym na shardy agent-runner, dispatch i commands/state-routing), a agentic gateway/server configs są podzielone między ścieżki chat/auth/model/http-plugin/runtime/startup zamiast czekać na zbudowane artefakty. Szerokie testy przeglądarkowe, QA, media i różne testy Plugin używają własnych dedykowanych konfiguracji Vitest zamiast wspólnego catch-all dla Plugin. Shardy include-pattern zapisują wpisy czasów z użyciem nazwy sharda CI, więc `.artifacts/vitest-shard-timings.json` może odróżnić całą konfigurację od filtrowanego sharda. `check-additional` trzyma razem prace kompilacji/canary granicy pakietu i oddziela architekturę topologii runtime od pokrycia gateway watch; lista strażników granic jest rozłożona paskami na cztery shardy macierzy, z których każdy uruchamia wybrane niezależne strażniki współbieżnie i drukuje czasy poszczególnych kontroli, w tym `pnpm prompt:snapshots:check`, aby dryf promptu szczęśliwej ścieżki runtime Codex był przypięty do PR-a, który go spowodował. Gateway watch, testy kanałów i shard granicy wsparcia core działają współbieżnie wewnątrz `build-artifacts` po tym, jak `dist/` i `dist-runtime/` są już zbudowane.
|
||||
Najwolniejsze rodziny testów Node są dzielone albo równoważone tak, aby każde zadanie pozostało małe bez nadmiernego rezerwowania runnerów: kontrakty kanałów działają jako trzy ważone shardy, szybkie/pomocnicze ścieżki jednostkowe rdzenia działają osobno, infrastruktura runtime rdzenia jest podzielona między shardy stanu i procesu/konfiguracji, auto-reply działa jako zrównoważeni workerzy (z poddrzewem odpowiedzi podzielonym na shardy agent-runner, dispatch i commands/state-routing), a agentowe konfiguracje gateway/server są podzielone między ścieżki chat/auth/model/http-plugin/runtime/startup zamiast czekać na zbudowane artefakty. Szerokie testy przeglądarki, QA, mediów i różne testy Plugin używają swoich dedykowanych konfiguracji Vitest zamiast współdzielonego catch-all dla Plugin. Shardy include-pattern zapisują wpisy czasu z użyciem nazwy sharda CI, więc `.artifacts/vitest-shard-timings.json` może odróżnić całą konfigurację od filtrowanego sharda. `check-additional` trzyma razem prace kompilacji/canary granicy pakietu i oddziela architekturę topologii runtime od pokrycia obserwacji Gateway; lista strażników granicy jest paskowana przez cztery shardy macierzy, z których każdy uruchamia wybrane niezależne strażniki współbieżnie i wypisuje czasy poszczególnych sprawdzeń, w tym `pnpm prompt:snapshots:check`, aby drift promptów szczęśliwej ścieżki runtime Codex był przypięty do PR-a, który go spowodował. Obserwacja Gateway, testy kanałów i shard granicy wsparcia rdzenia działają współbieżnie wewnątrz `build-artifacts` po tym, jak `dist/` i `dist-runtime/` zostały już zbudowane.
|
||||
|
||||
Android CI uruchamia zarówno `testPlayDebugUnitTest`, jak i `testThirdPartyDebugUnitTest`, a potem buduje APK debug Play. Wariant third-party nie ma osobnego zestawu źródeł ani manifestu; jego ścieżka testów jednostkowych nadal kompiluje wariant z flagami SMS/call-log BuildConfig, unikając jednocześnie duplikowania zadania pakowania debug APK przy każdym pushu istotnym dla Android.
|
||||
CI Androida uruchamia zarówno `testPlayDebugUnitTest`, jak i `testThirdPartyDebugUnitTest`, a następnie buduje Play debug APK. Wariant third-party nie ma osobnego zestawu źródeł ani manifestu; jego ścieżka testów jednostkowych nadal kompiluje wariant z flagami BuildConfig SMS/call-log, unikając przy tym duplikowania zadania pakowania debug APK przy każdym wypchnięciu istotnym dla Androida.
|
||||
|
||||
Shard `check-dependencies` uruchamia `pnpm deadcode:dependencies` (produkcyjny przebieg Knip tylko dla zależności przypięty do najnowszej wersji Knip, z wyłączonym minimalnym wiekiem wydania pnpm dla instalacji `dlx`) oraz `pnpm deadcode:unused-files`, który porównuje produkcyjne ustalenia Knip dotyczące nieużywanych plików z `scripts/deadcode-unused-files.allowlist.mjs`. Strażnik nieużywanych plików kończy się niepowodzeniem, gdy PR dodaje nowy niezweryfikowany nieużywany plik albo zostawia przestarzały wpis allowlisty, zachowując jednocześnie celowe dynamiczne powierzchnie Plugin, wygenerowane, build, live-test i mosty pakietów, których Knip nie może statycznie rozwiązać.
|
||||
Shard `check-dependencies` uruchamia `pnpm deadcode:dependencies` (produkcyjny przebieg Knip tylko dla zależności, przypięty do najnowszej wersji Knip, z wyłączonym minimalnym wiekiem wydania pnpm dla instalacji `dlx`) oraz `pnpm deadcode:unused-files`, który porównuje produkcyjne ustalenia Knip dotyczące nieużywanych plików z `scripts/deadcode-unused-files.allowlist.mjs`. Strażnik nieużywanych plików kończy się niepowodzeniem, gdy PR dodaje nowy nieprzejrzany nieużywany plik albo pozostawia nieaktualny wpis na liście dozwolonych, zachowując jednocześnie celowe dynamiczne powierzchnie Plugin, generowane, build, live-test i mosty pakietów, których Knip nie może rozwiązać statycznie.
|
||||
|
||||
## Przekazywanie aktywności ClawSweeper
|
||||
|
||||
`.github/workflows/clawsweeper-dispatch.yml` to most po stronie celu z aktywności repozytorium OpenClaw do ClawSweeper. Nie pobiera ani nie wykonuje niezaufanego kodu z pull requestów. Workflow tworzy token GitHub App z `CLAWSWEEPER_APP_PRIVATE_KEY`, a następnie wysyła zwarte payloady `repository_dispatch` do `openclaw/clawsweeper`.
|
||||
`.github/workflows/clawsweeper-dispatch.yml` jest mostem po stronie celu z aktywności repozytorium OpenClaw do ClawSweeper. Nie pobiera ani nie wykonuje niezaufanego kodu pull request. Workflow tworzy token GitHub App z `CLAWSWEEPER_APP_PRIVATE_KEY`, a następnie wysyła kompaktowe payloady `repository_dispatch` do `openclaw/clawsweeper`.
|
||||
|
||||
Workflow ma cztery ścieżki:
|
||||
|
||||
- `clawsweeper_item` dla dokładnych żądań przeglądu issue i pull requestów;
|
||||
- `clawsweeper_item` dla dokładnych żądań przeglądu issue i pull request;
|
||||
- `clawsweeper_comment` dla jawnych poleceń ClawSweeper w komentarzach issue;
|
||||
- `clawsweeper_commit_review` dla żądań przeglądu na poziomie commitów przy pushach do `main`;
|
||||
- `github_activity` dla ogólnej aktywności GitHub, którą agent ClawSweeper może sprawdzić.
|
||||
- `clawsweeper_commit_review` dla żądań przeglądu na poziomie commitów przy wypchnięciach do `main`;
|
||||
- `github_activity` dla ogólnej aktywności GitHub, którą agent ClawSweeper może sprawdzać.
|
||||
|
||||
Ścieżka `github_activity` przekazuje wyłącznie znormalizowane metadane: typ zdarzenia, akcję, aktora, repozytorium, numer elementu, URL, tytuł, stan oraz krótkie fragmenty komentarzy lub recenzji, gdy są obecne. Celowo unika przekazywania pełnej treści Webhook. Workflow odbierający w `openclaw/clawsweeper` to `.github/workflows/github-activity.yml`, który publikuje znormalizowane zdarzenie do hooka OpenClaw Gateway dla agenta ClawSweeper.
|
||||
Ścieżka `github_activity` przekazuje tylko znormalizowane metadane: typ zdarzenia, akcję, aktora, repozytorium, numer elementu, URL, tytuł, stan oraz krótkie fragmenty komentarzy lub przeglądów, jeśli występują. Celowo unika przekazywania pełnego ciała Webhook. Odbierający workflow w `openclaw/clawsweeper` to `.github/workflows/github-activity.yml`, który publikuje znormalizowane zdarzenie do hooka OpenClaw Gateway dla agenta ClawSweeper.
|
||||
|
||||
Ogólna aktywność jest obserwacją, a nie domyślnym dostarczaniem. Agent ClawSweeper otrzymuje cel Discord w swoim prompcie i powinien publikować na `#clawsweeper` tylko wtedy, gdy zdarzenie jest zaskakujące, wykonalne, ryzykowne lub operacyjnie użyteczne. Rutynowe otwarcia, edycje, szum botów, duplikaty szumu Webhook i zwykły ruch recenzji powinny skutkować `NO_REPLY`.
|
||||
Ogólna aktywność jest obserwacją, a nie domyślnym dostarczaniem. Agent ClawSweeper otrzymuje cel Discord w swoim prompcie i powinien publikować do `#clawsweeper` tylko wtedy, gdy zdarzenie jest zaskakujące, wykonalne, ryzykowne lub operacyjnie użyteczne. Rutynowe otwarcia, edycje, ruch botów, szum zduplikowanych Webhook i normalny ruch przeglądów powinny skutkować `NO_REPLY`.
|
||||
|
||||
Traktuj tytuły, komentarze, treści, tekst recenzji, nazwy gałęzi i komunikaty commitów GitHub jako niezaufane dane w całej tej ścieżce. Są wejściem do podsumowania i triage, a nie instrukcjami dla workflow ani runtime agenta.
|
||||
Traktuj tytuły, komentarze, treści, tekst przeglądów, nazwy gałęzi i komunikaty commitów z GitHub jako niezaufane dane w całej tej ścieżce. Są wejściem do podsumowania i triage, a nie instrukcjami dla workflow ani runtime agenta.
|
||||
|
||||
## Ręczne dispatche
|
||||
## Ręczne uruchomienia
|
||||
|
||||
Ręczne uruchomienia CI wykonują ten sam graf zadań co zwykłe CI, ale wymuszają włączenie każdej linii zakresowej spoza Androida: shardy Linux Node, shardy dołączonych Plugin, kontrakty kanałów, zgodność z Node 22, `check`, `check-additional`, build smoke, kontrole dokumentacji, Python Skills, Windows, macOS oraz i18n Control UI. Samodzielne ręczne uruchomienia CI wykonują tylko Androida z `include_android=true`; pełna parasolowa walidacja wydania włącza Androida przez przekazanie `include_android=true`. Kontrole statyczne przedwydania Plugin, dostępny tylko dla wydań shard `agentic-plugins`, pełny zbiorczy przegląd rozszerzeń oraz dockerowe linie przedwydania Plugin są wyłączone z CI. Zestaw dockerowy przedwydania działa tylko wtedy, gdy `Full Release Validation` uruchamia osobny workflow `Plugin Prerelease` z włączoną bramką walidacji wydania.
|
||||
Ręczne uruchomienia CI wykonują ten sam graf zadań co standardowe CI, ale wymuszają włączenie każdego zakresowego toru innego niż Android: shardy Linux Node, shardy bundled-plugin, kontrakty kanałów, zgodność z Node 22, `check`, `check-additional`, smoke test kompilacji, kontrole dokumentacji, Python skills, Windows, macOS oraz Control UI i18n. Samodzielne ręczne uruchomienia CI wykonują tylko Android z `include_android=true`; pełny parasol wydania włącza Android, przekazując `include_android=true`. Statyczne kontrole prerelease Plugin, shard `agentic-plugins` tylko dla wydania, pełny wsadowy sweep rozszerzeń oraz dockerowe tory prerelease Plugin są wykluczone z CI. Zestaw Docker prerelease uruchamia się tylko wtedy, gdy `Full Release Validation` uruchamia osobny workflow `Plugin Prerelease` z włączoną bramką walidacji wydania.
|
||||
|
||||
Ręczne przebiegi używają unikalnej grupy współbieżności, więc pełny zestaw dla kandydata do wydania nie zostanie anulowany przez inny przebieg push lub PR na tym samym refie. Opcjonalne wejście `target_ref` pozwala zaufanemu wywołującemu uruchomić ten graf względem gałęzi, taga lub pełnego SHA commita, używając pliku workflow z wybranego refa uruchomienia.
|
||||
Ręczne uruchomienia używają unikalnej grupy współbieżności, aby pełny zestaw release candidate nie został anulowany przez inne uruchomienie push lub PR na tej samej referencji. Opcjonalne wejście `target_ref` pozwala zaufanemu wywołującemu uruchomić ten graf względem gałęzi, taga lub pełnego SHA commita, używając pliku workflow z wybranej referencji uruchomienia.
|
||||
|
||||
```bash
|
||||
gh workflow run ci.yml --ref release/YYYY.M.D
|
||||
@ -96,17 +96,17 @@ gh workflow run ci.yml --ref main -f target_ref=<branch-or-sha> -f include_andro
|
||||
gh workflow run full-release-validation.yml --ref main -f ref=<branch-or-sha>
|
||||
```
|
||||
|
||||
## Uruchamiacze
|
||||
## Runnery
|
||||
|
||||
| Uruchamiacz | Zadania |
|
||||
| Runner | Zadania |
|
||||
| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `ubuntu-24.04` | `preflight`, szybkie zadania bezpieczeństwa i agregaty (`security-scm-fast`, `security-dependency-audit`, `security-fast`), szybkie kontrole protokołu/kontraktów/dołączonych komponentów, shardowane kontrole kontraktów kanałów, shardy `check` z wyjątkiem lintu, shardy i agregaty `check-additional`, weryfikatory agregatów testów Node, kontrole dokumentacji, Python Skills, workflow-sanity, labeler, auto-response; preflight install-smoke również używa Ubuntu hostowanego przez GitHub, aby macierz Blacksmith mogła wcześniej trafić do kolejki |
|
||||
| `blacksmith-4vcpu-ubuntu-2404` | `CodeQL Critical Quality`, lżejsze shardy rozszerzeń, `checks-fast-core`, `checks-node-compat-node22`, `check-prod-types` oraz `check-test-types` |
|
||||
| `blacksmith-8vcpu-ubuntu-2404` | `build-artifacts`, build-smoke, shardy testów Linux Node, shardy testów dołączonych Plugin, `android` |
|
||||
| `blacksmith-16vcpu-ubuntu-2404` | `check-lint` (na tyle wrażliwe na CPU, że 8 vCPU kosztowało więcej, niż oszczędzało); buildy Docker install-smoke (czas w kolejce dla 32 vCPU kosztował więcej, niż oszczędzał) |
|
||||
| `ubuntu-24.04` | `preflight`, szybkie zadania bezpieczeństwa i agregaty (`security-scm-fast`, `security-dependency-audit`, `security-fast`), szybkie kontrole protokołu/kontraktu/bundled, shardowane kontrole kontraktów kanałów, shardy `check` poza lintem, shardy i agregaty `check-additional`, weryfikatory agregatów testów Node, kontrole dokumentacji, Python skills, workflow-sanity, labeler, auto-response; preflight install-smoke także używa Ubuntu hostowanego przez GitHub, aby macierz Blacksmith mogła wcześniej wejść do kolejki |
|
||||
| `blacksmith-4vcpu-ubuntu-2404` | `CodeQL Critical Quality`, lżejsze shardy rozszerzeń, `checks-fast-core`, `checks-node-compat-node22`, `check-prod-types` oraz `check-test-types` |
|
||||
| `blacksmith-8vcpu-ubuntu-2404` | `build-artifacts`, build-smoke, shardy testów Linux Node, shardy testów bundled plugin, `android` |
|
||||
| `blacksmith-16vcpu-ubuntu-2404` | `check-lint` (na tyle wrażliwe na CPU, że 8 vCPU kosztowało więcej, niż oszczędzało); kompilacje Docker install-smoke (czas kolejki 32 vCPU kosztował więcej, niż oszczędzał) |
|
||||
| `blacksmith-16vcpu-windows-2025` | `checks-windows` |
|
||||
| `blacksmith-6vcpu-macos-latest` | `macos-node` w `openclaw/openclaw`; forki wracają do `macos-latest` |
|
||||
| `blacksmith-12vcpu-macos-latest` | `macos-swift` w `openclaw/openclaw`; forki wracają do `macos-latest` |
|
||||
| `blacksmith-6vcpu-macos-latest` | `macos-node` na `openclaw/openclaw`; forki przechodzą awaryjnie na `macos-latest` |
|
||||
| `blacksmith-12vcpu-macos-latest` | `macos-swift` na `openclaw/openclaw`; forki przechodzą awaryjnie na `macos-latest` |
|
||||
|
||||
## Lokalne odpowiedniki
|
||||
|
||||
@ -137,7 +137,7 @@ pnpm perf:kova:summary --report .artifacts/kova/reports/mock-provider/report.jso
|
||||
|
||||
## Wydajność OpenClaw
|
||||
|
||||
`OpenClaw Performance` to workflow wydajności produktu/runtime. Działa codziennie na `main` i można go uruchomić ręcznie:
|
||||
`OpenClaw Performance` to workflow wydajności produktu/runtime. Uruchamia się codziennie na `main` i można go uruchomić ręcznie:
|
||||
|
||||
```bash
|
||||
gh workflow run openclaw-performance.yml --ref main -f profile=diagnostic -f repeat=3
|
||||
@ -145,32 +145,32 @@ gh workflow run openclaw-performance.yml --ref main -f profile=smoke -f repeat=1
|
||||
gh workflow run openclaw-performance.yml --ref main -f target_ref=v2026.5.2 -f profile=diagnostic -f repeat=3
|
||||
```
|
||||
|
||||
Ręczne uruchomienie zwykle mierzy wydajność refa workflow. Ustaw `target_ref`, aby zmierzyć wydajność taga wydania lub innej gałęzi przy użyciu bieżącej implementacji workflow. Opublikowane ścieżki raportów i najnowsze wskaźniki są kluczowane według testowanego refa, a każdy `index.md` zapisuje testowany ref/SHA, ref/SHA workflow, ref Kova, profil, tryb auth linii, model, liczbę powtórzeń i filtry scenariuszy.
|
||||
Ręczne uruchomienie zwykle benchmarkuje referencję workflow. Ustaw `target_ref`, aby benchmarkować tag wydania lub inną gałąź z bieżącą implementacją workflow. Opublikowane ścieżki raportów i wskaźniki najnowszych wyników są kluczowane według testowanej referencji, a każdy `index.md` zapisuje testowaną referencję/SHA, referencję/SHA workflow, referencję Kova, profil, tryb autoryzacji toru, model, liczbę powtórzeń i filtry scenariuszy.
|
||||
|
||||
Workflow instaluje OCM z przypiętego wydania oraz Kova z `openclaw/Kova` przy przypiętym wejściu `kova_ref`, a następnie uruchamia trzy linie:
|
||||
Workflow instaluje OCM z przypiętego wydania oraz Kova z `openclaw/Kova` na przypiętym wejściu `kova_ref`, a następnie uruchamia trzy tory:
|
||||
|
||||
- `mock-provider`: scenariusze diagnostyczne Kova względem runtime zbudowanego lokalnie z deterministycznym fałszywym authem zgodnym z OpenAI.
|
||||
- `mock-deep-profile`: profilowanie CPU/sterty/trace dla hotspotów uruchamiania, Gateway i tury agenta.
|
||||
- `mock-provider`: scenariusze diagnostyczne Kova względem runtime z lokalnej kompilacji z deterministycznym fałszywym uwierzytelnianiem zgodnym z OpenAI.
|
||||
- `mock-deep-profile`: profilowanie CPU/sterty/śladu dla hotspotów startu, Gateway i tury agenta.
|
||||
- `live-gpt54`: rzeczywista tura agenta OpenAI `openai/gpt-5.4`, pomijana, gdy `OPENAI_API_KEY` jest niedostępny.
|
||||
|
||||
Linia mock-provider uruchamia też natywne sondy źródłowe OpenClaw po przebiegu Kova: pomiar czasu startu Gateway i pamięci w przypadkach uruchamiania domyślnego, z hookami oraz z 50 Plugin; powtarzane pętle hello mock-OpenAI `channel-chat-baseline`; oraz polecenia startowe CLI względem uruchomionego Gateway. Markdownowe podsumowanie sond źródłowych znajduje się w `source/index.md` w pakiecie raportu, z surowym JSON obok.
|
||||
Tor mock-provider uruchamia także natywne sondy źródłowe OpenClaw po przebiegu Kova: pomiar czasu rozruchu Gateway i pamięci dla przypadków startu domyślnego, z hookiem i z 50 Plugin; powtarzane pętle hello mock-OpenAI `channel-chat-baseline`; oraz polecenia startowe CLI względem uruchomionego Gateway. Podsumowanie Markdown sondy źródłowej znajduje się w `source/index.md` w pakiecie raportu, z surowym JSON obok.
|
||||
|
||||
Każda linia przesyła artefakty GitHub. Gdy skonfigurowano `CLAWGRIT_REPORTS_TOKEN`, workflow zatwierdza również `report.json`, `report.md`, pakiety, `index.md` oraz artefakty sond źródłowych do `openclaw/clawgrit-reports` pod `openclaw-performance/<tested-ref>/<run-id>-<attempt>/<lane>/`. Bieżący wskaźnik testowanego refa jest zapisywany jako `openclaw-performance/<tested-ref>/latest-<lane>.json`.
|
||||
Każdy tor przesyła artefakty GitHub. Gdy `CLAWGRIT_REPORTS_TOKEN` jest skonfigurowany, workflow dodatkowo commituje `report.json`, `report.md`, pakiety, `index.md` oraz artefakty sond źródłowych do `openclaw/clawgrit-reports` pod `openclaw-performance/<tested-ref>/<run-id>-<attempt>/<lane>/`. Bieżący wskaźnik testowanej referencji jest zapisywany jako `openclaw-performance/<tested-ref>/latest-<lane>.json`.
|
||||
|
||||
## Pełna walidacja wydania
|
||||
|
||||
`Full Release Validation` to ręczny parasolowy workflow dla „uruchom wszystko przed wydaniem”. Przyjmuje gałąź, tag lub pełny SHA commita, uruchamia ręczny workflow `CI` z tym celem, uruchamia `Plugin Prerelease` dla dowodów statycznych/Docker oraz dotyczących pakietów i Plugin dostępnych tylko dla wydań, a także uruchamia `OpenClaw Release Checks` dla install smoke, akceptacji pakietu, zestawów ścieżki wydania Docker, live/E2E, OpenWebUI, parytetu QA Lab, Matrix oraz linii Telegram. Z `rerun_group=all` i `release_profile=full` uruchamia też `NPM Telegram Beta E2E` względem artefaktu `release-package-under-test` z kontroli wydania. Po publikacji przekaż `npm_telegram_package_spec`, aby ponownie uruchomić tę samą linię pakietu Telegram względem opublikowanego pakietu npm.
|
||||
`Full Release Validation` to ręczny parasolowy workflow dla „uruchom wszystko przed wydaniem”. Przyjmuje gałąź, tag lub pełny SHA commita, uruchamia ręczny workflow `CI` z tym celem, uruchamia `Plugin Prerelease` dla dowodu plugin/package/static/Docker tylko dla wydania oraz uruchamia `OpenClaw Release Checks` dla install smoke, package acceptance, zestawów ścieżki wydania Docker, live/E2E, OpenWebUI, parzystości QA Lab, Matrix i torów Telegram. Z `rerun_group=all` i `release_profile=full` uruchamia także `NPM Telegram Beta E2E` względem artefaktu `release-package-under-test` z kontroli wydania. Po opublikowaniu przekaż `npm_telegram_package_spec`, aby ponownie uruchomić ten sam tor pakietu Telegram względem opublikowanego pakietu npm.
|
||||
|
||||
Zobacz [Pełna walidacja wydania](/pl/reference/full-release-validation), aby poznać
|
||||
macierz etapów, dokładne nazwy zadań workflow, różnice profili, artefakty i
|
||||
macierz etapów, dokładne nazwy zadań workflow, różnice profili, artefakty oraz
|
||||
uchwyty ukierunkowanych ponownych uruchomień.
|
||||
|
||||
`OpenClaw Release Publish` to ręczny mutujący workflow wydania. Uruchom go
|
||||
z `release/YYYY.M.D` lub `main` po utworzeniu taga wydania i po powodzeniu
|
||||
preflight OpenClaw npm. Weryfikuje `pnpm plugins:sync:check`,
|
||||
z `release/YYYY.M.D` lub `main` po tym, jak tag wydania istnieje i po tym, jak
|
||||
preflight OpenClaw npm zakończył się powodzeniem. Weryfikuje `pnpm plugins:sync:check`,
|
||||
uruchamia `Plugin NPM Release` dla wszystkich publikowalnych pakietów Plugin,
|
||||
uruchamia `Plugin ClawHub Release` dla tego samego SHA wydania, a dopiero potem
|
||||
uruchamia `OpenClaw NPM Release` z zapisanym `preflight_run_id`.
|
||||
uruchamia `Plugin ClawHub Release` dla tego samego SHA wydania, a dopiero potem uruchamia
|
||||
`OpenClaw NPM Release` z zapisanym `preflight_run_id`.
|
||||
|
||||
```bash
|
||||
gh workflow run openclaw-release-publish.yml \
|
||||
@ -180,40 +180,39 @@ gh workflow run openclaw-release-publish.yml \
|
||||
-f npm_dist_tag=beta
|
||||
```
|
||||
|
||||
Dla dowodu przypiętego commita na szybko zmieniającej się gałęzi użyj helpera zamiast
|
||||
Aby uzyskać dowód przypiętego commita na szybko zmieniającej się gałęzi, użyj helpera zamiast
|
||||
`gh workflow run ... --ref main -f ref=<sha>`:
|
||||
|
||||
```bash
|
||||
pnpm ci:full-release --sha <full-sha>
|
||||
```
|
||||
|
||||
Refy uruchamiania workflow GitHub muszą być gałęziami lub tagami, a nie surowymi SHA commitów. Helper wypycha tymczasową gałąź `release-ci/<sha>-...` na docelowym SHA,
|
||||
uruchamia `Full Release Validation` z tego przypiętego refa, weryfikuje, że każdy potomny
|
||||
workflow `headSha` pasuje do celu, i usuwa tymczasową gałąź po zakończeniu
|
||||
przebiegu. Weryfikator parasolowy również kończy się błędem, jeśli którykolwiek potomny workflow działał na
|
||||
Referencje uruchomienia workflow GitHub muszą być gałęziami lub tagami, nie surowymi SHA commitów. Helper wypycha tymczasową gałąź `release-ci/<sha>-...` na docelowym SHA,
|
||||
uruchamia `Full Release Validation` z tej przypiętej referencji, weryfikuje, że każdy potomny workflow `headSha` odpowiada celowi, i usuwa tymczasową gałąź po zakończeniu
|
||||
uruchomienia. Weryfikator parasolowy kończy się też niepowodzeniem, jeśli jakikolwiek potomny workflow został uruchomiony na
|
||||
innym SHA.
|
||||
|
||||
`release_profile` kontroluje zakres live/provider przekazywany do kontroli wydania. Ręczne workflow wydania domyślnie używają `stable`; użyj `full` tylko wtedy, gdy celowo chcesz szeroką macierz doradczą provider/media.
|
||||
`release_profile` kontroluje zakres live/provider przekazywany do sprawdzeń wydania. Ręczne przepływy pracy wydania domyślnie używają `stable`; użyj `full` tylko wtedy, gdy celowo chcesz uruchomić szeroką macierz doradczą provider/media.
|
||||
|
||||
- `minimum` zachowuje najszybsze krytyczne dla wydania ścieżki OpenAI/core.
|
||||
- `stable` dodaje stabilny zestaw provider/backend.
|
||||
- `full` uruchamia szeroką macierz doradczą provider/media.
|
||||
|
||||
Workflow nadrzędny zapisuje identyfikatory uruchomionych workflow podrzędnych, a końcowe zadanie `Verify full validation` ponownie sprawdza bieżące wyniki workflow podrzędnych i dopisuje tabele najwolniejszych zadań dla każdego workflow podrzędnego. Jeśli workflow podrzędny zostanie uruchomiony ponownie i zakończy się powodzeniem, uruchom ponownie tylko zadanie weryfikatora nadrzędnego, aby odświeżyć wynik workflow nadrzędnego i podsumowanie czasów.
|
||||
Przepływ nadrzędny zapisuje identyfikatory uruchomień wysłanych procesów potomnych, a końcowe zadanie `Verify full validation` ponownie sprawdza bieżące wyniki uruchomień potomnych i dołącza tabele najwolniejszych zadań dla każdego uruchomienia potomnego. Jeśli potomny przepływ pracy zostanie uruchomiony ponownie i zakończy się powodzeniem, uruchom ponownie tylko zadanie weryfikatora nadrzędnego, aby odświeżyć wynik przepływu nadrzędnego i podsumowanie czasu.
|
||||
|
||||
Do odzyskiwania zarówno `Full Release Validation`, jak i `OpenClaw Release Checks` akceptują `rerun_group`. Użyj `all` dla kandydata wydania, `ci` tylko dla zwykłego pełnego workflow podrzędnego CI, `plugin-prerelease` tylko dla workflow podrzędnego wersji przedpremierowej pluginu, `release-checks` dla każdego workflow podrzędnego wydania albo węższej grupy: `install-smoke`, `cross-os`, `live-e2e`, `package`, `qa`, `qa-parity`, `qa-live` lub `npm-telegram` w workflow nadrzędnym. Dzięki temu ponowne uruchomienie nieudanego środowiska wydania pozostaje ograniczone po ukierunkowanej poprawce.
|
||||
Do odzyskiwania zarówno `Full Release Validation`, jak i `OpenClaw Release Checks` akceptują `rerun_group`. Użyj `all` dla kandydata do wydania, `ci` tylko dla zwykłego pełnego potomnego CI, `plugin-prerelease` tylko dla potomnego przedwydania pluginu, `release-checks` dla każdego potomnego procesu wydania albo węższej grupy: `install-smoke`, `cross-os`, `live-e2e`, `package`, `qa`, `qa-parity`, `qa-live` lub `npm-telegram` w przepływie nadrzędnym. Dzięki temu ponowne uruchomienie nieudanego środowiska wydania pozostaje ograniczone po ukierunkowanej poprawce.
|
||||
|
||||
`OpenClaw Release Checks` używa zaufanego odwołania workflow, aby jednorazowo rozwiązać wybrane odwołanie do archiwum tar `release-package-under-test`, a następnie przekazuje ten artefakt zarówno do workflow Docker ścieżki wydania live/E2E, jak i sharda akceptacji pakietu. Dzięki temu bajty pakietu pozostają spójne między środowiskami wydania i unika się ponownego pakowania tego samego kandydata w wielu zadaniach podrzędnych.
|
||||
`OpenClaw Release Checks` używa zaufanego odwołania przepływu pracy, aby jednorazowo rozwiązać wybrane odwołanie do archiwum `release-package-under-test`, a następnie przekazuje ten artefakt zarówno do przepływu Docker ścieżki wydania live/E2E, jak i do fragmentu akceptacji pakietu. Dzięki temu bajty pakietu pozostają spójne we wszystkich środowiskach wydania i unika się ponownego pakowania tego samego kandydata w wielu zadaniach potomnych.
|
||||
|
||||
Zduplikowane uruchomienia `Full Release Validation` dla `ref=main` i `rerun_group=all`
|
||||
zastępują starszy workflow nadrzędny. Monitor nadrzędny anuluje każdy workflow podrzędny, który
|
||||
już uruchomił, gdy workflow nadrzędny zostanie anulowany, więc nowsza walidacja main
|
||||
nie czeka za przestarzałym dwugodzinnym uruchomieniem release-check. Walidacja gałęzi/tagu
|
||||
wydania i ukierunkowane grupy ponownych uruchomień zachowują `cancel-in-progress: false`.
|
||||
Duplikaty uruchomień `Full Release Validation` dla `ref=main` i `rerun_group=all`
|
||||
zastępują starszy przepływ nadrzędny. Monitor nadrzędny anuluje każdy potomny przepływ pracy, który
|
||||
już wysłał, gdy proces nadrzędny zostanie anulowany, więc nowsza walidacja gałęzi main
|
||||
nie czeka za przestarzałym dwugodzinnym uruchomieniem sprawdzeń wydania. Walidacja gałęzi/tagów
|
||||
wydania oraz ukierunkowane grupy ponownego uruchamiania zachowują `cancel-in-progress: false`.
|
||||
|
||||
## Shardy live i E2E
|
||||
## Fragmenty live i E2E
|
||||
|
||||
Workflow podrzędny live/E2E wydania zachowuje szerokie natywne pokrycie `pnpm test:live`, ale uruchamia je jako nazwane shardy przez `scripts/test-live-shard.mjs` zamiast jednego zadania sekwencyjnego:
|
||||
Potomny proces live/E2E wydania zachowuje szerokie natywne pokrycie `pnpm test:live`, ale uruchamia je jako nazwane fragmenty przez `scripts/test-live-shard.mjs`, zamiast jako jedno zadanie szeregowe:
|
||||
|
||||
- `native-live-src-agents`
|
||||
- `native-live-src-gateway-core`
|
||||
@ -225,61 +224,61 @@ Workflow podrzędny live/E2E wydania zachowuje szerokie natywne pokrycie `pnpm t
|
||||
- `native-live-extensions-openai`
|
||||
- `native-live-extensions-o-z-other`
|
||||
- `native-live-extensions-xai`
|
||||
- podzielone shardy audio/wideo mediów i shardy muzyki filtrowane według providera
|
||||
- podzielone fragmenty audio/wideo mediów oraz fragmenty muzyki filtrowane według providera
|
||||
|
||||
Zachowuje to to samo pokrycie plików, a jednocześnie ułatwia ponowne uruchamianie i diagnozowanie powolnych awarii providerów live. Zagregowane nazwy shardów `native-live-extensions-o-z`, `native-live-extensions-media` i `native-live-extensions-media-music` pozostają poprawne dla ręcznych jednorazowych ponownych uruchomień.
|
||||
Dzięki temu zachowane jest to samo pokrycie plików, a wolne awarie providerów live są łatwiejsze do ponownego uruchomienia i diagnozy. Zbiorcze nazwy fragmentów `native-live-extensions-o-z`, `native-live-extensions-media` i `native-live-extensions-media-music` pozostają prawidłowe dla ręcznych jednorazowych ponownych uruchomień.
|
||||
|
||||
Natywne shardy mediów live działają w `ghcr.io/openclaw/openclaw-live-media-runner:ubuntu-24.04`, budowanym przez workflow `Live Media Runner Image`. Ten obraz wstępnie instaluje `ffmpeg` i `ffprobe`; zadania mediów tylko weryfikują binaria przed konfiguracją. Utrzymuj zestawy live oparte na Dockerze na zwykłych runnerach Blacksmith — zadania kontenerowe nie są właściwym miejscem do uruchamiania zagnieżdżonych testów Docker.
|
||||
Natywne fragmenty mediów live działają w `ghcr.io/openclaw/openclaw-live-media-runner:ubuntu-24.04`, budowanym przez przepływ pracy `Live Media Runner Image`. Ten obraz wstępnie instaluje `ffmpeg` i `ffprobe`; zadania medialne tylko weryfikują binaria przed konfiguracją. Pakiety live oparte na Dockerze pozostaw na zwykłych runnerach Blacksmith — zadania kontenerowe nie są właściwym miejscem do uruchamiania zagnieżdżonych testów Docker.
|
||||
|
||||
Shardy modeli/backendów live oparte na Dockerze używają osobnego współdzielonego obrazu `ghcr.io/openclaw/openclaw-live-test:<sha>` dla wybranego commita. Workflow live wydania buduje i publikuje ten obraz raz, a następnie shardy modelu live Docker, Gateway podzielonego według providerów, backendu CLI, powiązania ACP i harnessu Codex działają z `OPENCLAW_SKIP_DOCKER_BUILD=1`. Shardy Docker Gateway mają jawne limity `timeout` na poziomie skryptu poniżej limitu czasu zadania workflow, aby zawieszony kontener lub ścieżka czyszczenia kończyły się szybko zamiast zużywać cały budżet release-check. Jeśli te shardy niezależnie przebudowują pełny docelowy obraz Docker ze źródeł, uruchomienie wydania jest błędnie skonfigurowane i zmarnuje czas ścienny na zduplikowane budowania obrazów.
|
||||
Fragmenty live model/backend oparte na Dockerze używają osobnego współdzielonego obrazu `ghcr.io/openclaw/openclaw-live-test:<sha>` dla wybranego commita. Przepływ live wydania buduje i wypycha ten obraz raz, a następnie fragmenty modelu live Docker, Gateway podzielone według providerów, backendu CLI, wiązania ACP i harnessu Codex uruchamiają się z `OPENCLAW_SKIP_DOCKER_BUILD=1`. Fragmenty Gateway Docker mają jawne limity `timeout` na poziomie skryptu, niższe od limitu czasu zadania przepływu pracy, aby zablokowany kontener lub ścieżka sprzątania szybko kończyły się niepowodzeniem zamiast zużywać cały budżet sprawdzeń wydania. Jeśli te fragmenty niezależnie przebudowują pełny docelowy obraz Docker ze źródeł, uruchomienie wydania jest błędnie skonfigurowane i zmarnuje czas ścienny na duplikujące się budowy obrazu.
|
||||
|
||||
## Akceptacja pakietu
|
||||
|
||||
Użyj `Package Acceptance`, gdy pytanie brzmi: „czy ten instalowalny pakiet OpenClaw działa jako produkt?”. Różni się to od zwykłego CI: zwykłe CI waliduje drzewo źródeł, natomiast akceptacja pakietu waliduje pojedyncze archiwum tar przez ten sam harness Docker E2E, którego użytkownicy używają po instalacji lub aktualizacji.
|
||||
Użyj `Package Acceptance`, gdy pytanie brzmi: „czy ten instalowalny pakiet OpenClaw działa jako produkt?”. Różni się to od zwykłego CI: zwykłe CI waliduje drzewo źródeł, podczas gdy akceptacja pakietu waliduje pojedyncze archiwum przez ten sam harness Docker E2E, z którego użytkownicy korzystają po instalacji lub aktualizacji.
|
||||
|
||||
### Zadania
|
||||
|
||||
1. `resolve_package` pobiera `workflow_ref`, rozwiązuje jednego kandydata pakietu, zapisuje `.artifacts/docker-e2e-package/openclaw-current.tgz`, zapisuje `.artifacts/docker-e2e-package/package-candidate.json`, przesyła oba jako artefakt `package-under-test` i wypisuje źródło, odwołanie workflow, odwołanie pakietu, wersję, SHA-256 oraz profil w podsumowaniu kroku GitHub.
|
||||
2. `docker_acceptance` wywołuje `openclaw-live-and-e2e-checks-reusable.yml` z `ref=workflow_ref` i `package_artifact_name=package-under-test`. Workflow wielokrotnego użytku pobiera ten artefakt, waliduje inwentarz archiwum tar, przygotowuje obrazy Docker z digestem pakietu, gdy są potrzebne, i uruchamia wybrane ścieżki Docker względem tego pakietu zamiast pakować checkout workflow. Gdy profil wybiera wiele ukierunkowanych `docker_lanes`, workflow wielokrotnego użytku przygotowuje pakiet i współdzielone obrazy raz, a następnie rozdziela te ścieżki jako równoległe ukierunkowane zadania Docker z unikalnymi artefaktami.
|
||||
3. `package_telegram` opcjonalnie wywołuje `NPM Telegram Beta E2E`. Działa, gdy `telegram_mode` nie jest `none`, i instaluje ten sam artefakt `package-under-test`, gdy Package Acceptance rozwiązało pakiet; samodzielne uruchomienie Telegram nadal może zainstalować opublikowaną specyfikację npm.
|
||||
4. `summary` kończy workflow niepowodzeniem, jeśli rozwiązywanie pakietu, akceptacja Docker lub opcjonalna ścieżka Telegram nie powiodły się.
|
||||
1. `resolve_package` pobiera `workflow_ref`, rozwiązuje jednego kandydata pakietu, zapisuje `.artifacts/docker-e2e-package/openclaw-current.tgz`, zapisuje `.artifacts/docker-e2e-package/package-candidate.json`, przesyła oba jako artefakt `package-under-test` oraz wypisuje źródło, odwołanie przepływu pracy, odwołanie pakietu, wersję, SHA-256 i profil w podsumowaniu kroku GitHub.
|
||||
2. `docker_acceptance` wywołuje `openclaw-live-and-e2e-checks-reusable.yml` z `ref=workflow_ref` i `package_artifact_name=package-under-test`. Wielokrotnego użytku przepływ pracy pobiera ten artefakt, waliduje inwentarz archiwum, przygotowuje obrazy Docker z digestem pakietu, gdy są potrzebne, i uruchamia wybrane ścieżki Docker względem tego pakietu zamiast pakować checkout przepływu pracy. Gdy profil wybiera wiele ukierunkowanych `docker_lanes`, wielokrotnego użytku przepływ pracy przygotowuje pakiet i współdzielone obrazy raz, a następnie rozsyła te ścieżki jako równoległe ukierunkowane zadania Docker z unikalnymi artefaktami.
|
||||
3. `package_telegram` opcjonalnie wywołuje `NPM Telegram Beta E2E`. Uruchamia się, gdy `telegram_mode` nie jest `none`, i instaluje ten sam artefakt `package-under-test`, gdy Akceptacja pakietu rozwiązała pakiet; samodzielne wysłanie Telegram nadal może zainstalować opublikowaną specyfikację npm.
|
||||
4. `summary` kończy przepływ pracy niepowodzeniem, jeśli rozwiązywanie pakietu, akceptacja Docker lub opcjonalna ścieżka Telegram zakończyły się niepowodzeniem.
|
||||
|
||||
### Źródła kandydata
|
||||
### Źródła kandydatów
|
||||
|
||||
- `source=npm` akceptuje tylko `openclaw@beta`, `openclaw@latest` albo dokładną wersję wydania OpenClaw, taką jak `openclaw@2026.4.27-beta.2`. Użyj tego do akceptacji opublikowanej wersji przedpremierowej/stabilnej.
|
||||
- `source=npm` akceptuje tylko `openclaw@beta`, `openclaw@latest` albo dokładną wersję wydania OpenClaw, taką jak `openclaw@2026.4.27-beta.2`. Użyj tego do akceptacji opublikowanego przedwydania/stabilnego wydania.
|
||||
- `source=ref` pakuje zaufaną gałąź, tag lub pełny SHA commita `package_ref`. Resolver pobiera gałęzie/tagi OpenClaw, weryfikuje, że wybrany commit jest osiągalny z historii gałęzi repozytorium lub tagu wydania, instaluje zależności w odłączonym worktree i pakuje go za pomocą `scripts/package-openclaw-for-docker.mjs`.
|
||||
- `source=url` pobiera `.tgz` przez HTTPS; `package_sha256` jest wymagane.
|
||||
- `source=artifact` pobiera jedno `.tgz` z `artifact_run_id` i `artifact_name`; `package_sha256` jest opcjonalne, ale powinno być podane dla artefaktów udostępnianych zewnętrznie.
|
||||
- `source=url` pobiera plik HTTPS `.tgz`; `package_sha256` jest wymagane.
|
||||
- `source=artifact` pobiera jedno `.tgz` z `artifact_run_id` i `artifact_name`; `package_sha256` jest opcjonalne, ale powinno zostać podane dla artefaktów udostępnianych zewnętrznie.
|
||||
|
||||
Trzymaj `workflow_ref` i `package_ref` osobno. `workflow_ref` to zaufany kod workflow/harnessu, który uruchamia test. `package_ref` to commit źródłowy, który zostaje spakowany, gdy `source=ref`. Dzięki temu bieżący harness testowy może walidować starsze zaufane commity źródłowe bez uruchamiania starej logiki workflow.
|
||||
Trzymaj `workflow_ref` i `package_ref` oddzielnie. `workflow_ref` to zaufany kod przepływu pracy/harnessu, który uruchamia test. `package_ref` to commit źródłowy, który zostaje spakowany, gdy `source=ref`. Dzięki temu bieżący harness testowy może walidować starsze zaufane commity źródłowe bez uruchamiania starej logiki przepływu pracy.
|
||||
|
||||
### Profile zestawu
|
||||
### Profile pakietów testów
|
||||
|
||||
- `smoke` — `npm-onboard-channel-agent`, `gateway-network`, `config-reload`
|
||||
- `package` — `npm-onboard-channel-agent`, `doctor-switch`, `update-channel-switch`, `upgrade-survivor`, `published-upgrade-survivor`, `plugins-offline`, `plugin-update`
|
||||
- `product` — `package` plus `mcp-channels`, `cron-mcp-cleanup`, `openai-web-search-minimal`, `openwebui`
|
||||
- `full` — pełne fragmenty ścieżki wydania Docker z OpenWebUI
|
||||
- `full` — pełne części Docker ścieżki wydania z OpenWebUI
|
||||
- `custom` — dokładne `docker_lanes`; wymagane, gdy `suite_profile=custom`
|
||||
|
||||
Profil `package` używa offline'owego pokrycia pluginów, więc walidacja opublikowanego pakietu nie jest zależna od dostępności live ClawHub. Opcjonalna ścieżka Telegram ponownie używa artefaktu `package-under-test` w `NPM Telegram Beta E2E`, a ścieżka opublikowanej specyfikacji npm jest zachowana dla samodzielnych uruchomień.
|
||||
Profil `package` używa offline’owego pokrycia pluginów, aby walidacja opublikowanego pakietu nie zależała od dostępności ClawHub live. Opcjonalna ścieżka Telegram ponownie używa artefaktu `package-under-test` w `NPM Telegram Beta E2E`, zachowując ścieżkę opublikowanej specyfikacji npm dla samodzielnych wysłań.
|
||||
|
||||
Dedykowaną politykę testowania aktualizacji i pluginów, w tym lokalne polecenia,
|
||||
ścieżki Docker, wejścia Package Acceptance, domyślne ustawienia wydania i triage awarii,
|
||||
Dedykowaną politykę testowania aktualizacji i pluginów, w tym polecenia lokalne,
|
||||
ścieżki Docker, wejścia Akceptacji pakietu, domyślne ustawienia wydania i triage awarii,
|
||||
zobacz w [Testowanie aktualizacji i pluginów](/pl/help/testing-updates-plugins).
|
||||
|
||||
Kontrole wydania wywołują Package Acceptance z `source=artifact`, przygotowanym artefaktem pakietu wydania, `suite_profile=custom`, `docker_lanes='doctor-switch update-channel-switch upgrade-survivor published-upgrade-survivor plugins-offline plugin-update'`, `published_upgrade_survivor_baselines=all-since-2026.4.23`, `published_upgrade_survivor_scenarios=reported-issues` i `telegram_mode=mock-openai`. Dzięki temu dowody migracji pakietu, aktualizacji, czyszczenia przestarzałych zależności pluginów, naprawy instalacji skonfigurowanego pluginu, pluginu offline, aktualizacji pluginu i Telegram pozostają na tym samym rozwiązanym archiwum tar pakietu. Ustaw `package_acceptance_package_spec` w Full Release Validation lub OpenClaw Release Checks, aby uruchomić tę samą macierz względem dostarczonego pakietu npm zamiast artefaktu zbudowanego z SHA. Kontrole wydania cross-OS nadal obejmują specyficzne dla systemu operacyjnego onboardowanie, instalator i zachowanie platformy; walidacja produktu pakietu/aktualizacji powinna zaczynać się od Package Acceptance. Ścieżka Docker `published-upgrade-survivor` waliduje jedną bazową opublikowaną paczkę na uruchomienie. W Package Acceptance rozwiązane archiwum tar `package-under-test` jest zawsze kandydatem, a `published_upgrade_survivor_baseline` wybiera zapasową opublikowaną bazę, domyślnie `openclaw@latest`; polecenia ponownego uruchomienia nieudanej ścieżki zachowują tę bazę. Ustaw `published_upgrade_survivor_baselines=all-since-2026.4.23`, aby rozszerzyć Full Release CI na każde stabilne wydanie npm od `2026.4.23` do `latest`; `release-history` pozostaje dostępne do ręcznego szerszego próbkowania ze starszym punktem początkowym sprzed tej daty. Ustaw `published_upgrade_survivor_scenarios=reported-issues`, aby rozszerzyć te same bazy o macierz fixture'ów odwzorowujących problemy dla konfiguracji Feishu, zachowanych plików bootstrap/persona, instalacji skonfigurowanych pluginów OpenClaw, ścieżek logów z tyldą i przestarzałych katalogów głównych zależności legacy pluginów. Osobny workflow `Update Migration` używa ścieżki Docker `update-migration` z `all-since-2026.4.23` i `plugin-deps-cleanup`, gdy pytaniem jest wyczerpujące czyszczenie aktualizacji opublikowanych pakietów, a nie zwykły zakres Full Release CI. Lokalne uruchomienia agregujące mogą przekazywać dokładne specyfikacje pakietów przez `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPECS`, zachować jedną ścieżkę z `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPEC`, taką jak `openclaw@2026.4.15`, albo ustawić `OPENCLAW_UPGRADE_SURVIVOR_SCENARIOS` dla macierzy scenariuszy. Opublikowana ścieżka konfiguruje bazę za pomocą wbudowanego przepisu polecenia `openclaw config set`, zapisuje kroki przepisu w `summary.json` i sprawdza `/healthz`, `/readyz` oraz status RPC po starcie Gateway. Świeże ścieżki pakietu i instalatora Windows weryfikują także, że zainstalowany pakiet potrafi zaimportować nadpisanie browser-control z surowej bezwzględnej ścieżki Windows. Smoke test kroku agenta OpenAI cross-OS domyślnie używa `OPENCLAW_CROSS_OS_OPENAI_MODEL`, jeśli jest ustawione, w przeciwnym razie `openai/gpt-5.4`, więc dowód instalacji i Gateway pozostaje na modelu testowym GPT-5, unikając domyślnych wartości GPT-4.x.
|
||||
Sprawdzenia wydania wywołują Akceptację pakietu z `source=artifact`, przygotowanym artefaktem pakietu wydania, `suite_profile=custom`, `docker_lanes='doctor-switch update-channel-switch upgrade-survivor published-upgrade-survivor plugins-offline plugin-update'`, `published_upgrade_survivor_baselines=all-since-2026.4.23`, `published_upgrade_survivor_scenarios=reported-issues` i `telegram_mode=mock-openai`. Dzięki temu dowody migracji pakietu, aktualizacji, sprzątania nieaktualnych zależności pluginów, naprawy instalacji skonfigurowanego pluginu, offline’owego pluginu, aktualizacji pluginu i Telegram pozostają na tym samym rozwiązanym archiwum pakietu. Ustaw `package_acceptance_package_spec` w Full Release Validation lub OpenClaw Release Checks, aby uruchomić tę samą macierz względem wydanego pakietu npm zamiast artefaktu zbudowanego z SHA. Sprawdzenia wydania Cross-OS nadal pokrywają zachowanie specyficzne dla systemu operacyjnego przy wdrażaniu, instalatorze i platformie; walidacja produktu dla pakietu/aktualizacji powinna zaczynać się od Akceptacji pakietu. Ścieżka Docker `published-upgrade-survivor` waliduje jedną opublikowaną bazę pakietu na uruchomienie. W Akceptacji pakietu rozwiązane archiwum `package-under-test` jest zawsze kandydatem, a `published_upgrade_survivor_baseline` wybiera zapasową opublikowaną bazę, domyślnie `openclaw@latest`; polecenia ponownego uruchomienia nieudanej ścieżki zachowują tę bazę. Ustaw `published_upgrade_survivor_baselines=all-since-2026.4.23`, aby rozszerzyć Full Release CI na każde stabilne wydanie npm od `2026.4.23` do `latest`; `release-history` pozostaje dostępne do ręcznego szerszego próbkowania ze starszą kotwicą daty sprzed zakresu. Ustaw `published_upgrade_survivor_scenarios=reported-issues`, aby rozszerzyć te same bazy na fixture’y odpowiadające zgłoszeniom dla konfiguracji Feishu, zachowanych plików bootstrap/persona, instalacji skonfigurowanych pluginów OpenClaw, ścieżek logów z tyldą i nieaktualnych korzeni zależności starszych pluginów. Osobny przepływ pracy `Update Migration` używa ścieżki Docker `update-migration` z `all-since-2026.4.23` i `plugin-deps-cleanup`, gdy pytanie dotyczy wyczerpującego sprzątania opublikowanych aktualizacji, a nie zwykłego zakresu Full Release CI. Lokalne uruchomienia zbiorcze mogą przekazywać dokładne specyfikacje pakietów przez `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPECS`, zachować pojedynczą ścieżkę z `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPEC`, taką jak `openclaw@2026.4.15`, albo ustawić `OPENCLAW_UPGRADE_SURVIVOR_SCENARIOS` dla macierzy scenariuszy. Opublikowana ścieżka konfiguruje bazę za pomocą wbudowanej receptury polecenia `openclaw config set`, zapisuje kroki receptury w `summary.json` i sprawdza `/healthz`, `/readyz` oraz status RPC po uruchomieniu Gateway. Świeże ścieżki pakietu i instalatora Windows weryfikują też, że zainstalowany pakiet może zaimportować nadpisanie browser-control z surowej bezwzględnej ścieżki Windows. Smoke test obrotu agenta OpenAI w Cross-OS domyślnie używa `OPENCLAW_CROSS_OS_OPENAI_MODEL`, gdy jest ustawione, w przeciwnym razie `openai/gpt-5.4`, dzięki czemu dowód instalacji i Gateway pozostaje na modelu testowym GPT-5, unikając domyślnych ustawień GPT-4.x.
|
||||
|
||||
### Okna zgodności legacy
|
||||
### Okna zgodności ze starszymi wersjami
|
||||
|
||||
Package Acceptance ma ograniczone okna zgodności legacy dla już opublikowanych pakietów. Pakiety do `2026.4.25` włącznie, w tym `2026.4.25-beta.*`, mogą używać ścieżki zgodności:
|
||||
Akceptacja pakietu ma ograniczone okna zgodności ze starszymi wersjami dla już opublikowanych pakietów. Pakiety do `2026.4.25` włącznie, w tym `2026.4.25-beta.*`, mogą używać ścieżki zgodności:
|
||||
|
||||
- znane prywatne wpisy QA w `dist/postinstall-inventory.json` mogą wskazywać pliki pominięte w archiwum tar;
|
||||
- `doctor-switch` może pominąć podprzypadek trwałości `gateway install --wrapper`, gdy pakiet nie udostępnia tej flagi;
|
||||
- `update-channel-switch` może przyciąć brakujące `pnpm.patchedDependencies` z fałszywego fixture'a git pochodzącego z archiwum tar i może logować brak utrwalonego `update.channel`;
|
||||
- smoke testy pluginów mogą odczytywać legacy lokalizacje rekordów instalacji albo akceptować brak trwałości rekordu instalacji marketplace;
|
||||
- `plugin-update` może zezwolić na migrację metadanych konfiguracji, nadal wymagając, aby rekord instalacji i zachowanie bez ponownej instalacji pozostały niezmienione.
|
||||
- znane prywatne wpisy QA w `dist/postinstall-inventory.json` mogą wskazywać pliki pominięte w archiwum;
|
||||
- `doctor-switch` może pominąć podprzypadek utrwalania `gateway install --wrapper`, gdy pakiet nie udostępnia tej flagi;
|
||||
- `update-channel-switch` może przyciąć brakujące `pnpm.patchedDependencies` z fałszywego fixture’a git pochodzącego z archiwum i może logować brakujące utrwalone `update.channel`;
|
||||
- smoke testy pluginów mogą odczytywać starsze lokalizacje rekordów instalacji lub akceptować brak utrwalenia rekordu instalacji marketplace;
|
||||
- `plugin-update` może pozwolić na migrację metadanych konfiguracji, nadal wymagając, aby rekord instalacji i zachowanie bez reinstalacji pozostały niezmienione.
|
||||
|
||||
Opublikowany pakiet `2026.4.26` może również ostrzegać o lokalnych plikach znaczników metadanych builda, które już zostały dostarczone. Późniejsze pakiety muszą spełniać nowoczesne kontrakty; te same warunki powodują niepowodzenie zamiast ostrzeżenia lub pominięcia.
|
||||
Opublikowany pakiet `2026.4.26` może też ostrzegać o lokalnych plikach znaczników metadanych budowy, które zostały już wydane. Późniejsze pakiety muszą spełniać nowoczesne kontrakty; te same warunki powodują niepowodzenie zamiast ostrzeżenia lub pominięcia.
|
||||
|
||||
### Przykłady
|
||||
|
||||
@ -322,151 +321,151 @@ gh workflow run package-acceptance.yml \
|
||||
-f docker_lanes='install-e2e plugin-update'
|
||||
```
|
||||
|
||||
Podczas debugowania nieudanego uruchomienia akceptacji pakietu zacznij od podsumowania `resolve_package`, aby potwierdzić źródło pakietu, wersję i SHA-256. Następnie sprawdź uruchomienie podrzędne `docker_acceptance` oraz jego artefakty Docker: `.artifacts/docker-tests/**/summary.json`, `failures.json`, logi torów, czasy faz i polecenia ponownego uruchomienia. Preferuj ponowne uruchomienie nieudanego profilu pakietu lub dokładnych torów Docker zamiast ponownego uruchamiania pełnej walidacji wydania.
|
||||
Podczas debugowania nieudanego uruchomienia akceptacji pakietu zacznij od podsumowania `resolve_package`, aby potwierdzić źródło pakietu, wersję i SHA-256. Następnie sprawdź uruchomienie podrzędne `docker_acceptance` oraz jego artefakty Docker: `.artifacts/docker-tests/**/summary.json`, `failures.json`, dzienniki linii, czasy faz i polecenia ponownego uruchomienia. Preferuj ponowne uruchamianie nieudanego profilu pakietu lub dokładnych linii Docker zamiast ponownego uruchamiania pełnej walidacji wydania.
|
||||
|
||||
## Smoke test instalacji
|
||||
## Test instalacji
|
||||
|
||||
Osobny workflow `Install Smoke` ponownie używa tego samego skryptu zakresu przez własne zadanie `preflight`. Dzieli zakres smoke testów na `run_fast_install_smoke` i `run_full_install_smoke`.
|
||||
Oddzielny przepływ pracy `Install Smoke` ponownie używa tego samego skryptu zakresu przez własne zadanie `preflight`. Dzieli pokrycie testu instalacji na `run_fast_install_smoke` i `run_full_install_smoke`.
|
||||
|
||||
- **Szybka ścieżka** uruchamia się dla pull requestów dotykających powierzchni Docker/pakietu, zmian pakietu/manifestu dołączonego Pluginu albo powierzchni rdzeniowego Pluginu/kanału/Gateway/Plugin SDK, które wykonują zadania smoke Docker. Zmiany dołączonego Pluginu dotyczące tylko źródeł, edycje wyłącznie testów i edycje wyłącznie dokumentacji nie rezerwują workerów Docker. Szybka ścieżka buduje obraz głównego Dockerfile raz, sprawdza CLI, uruchamia smoke CLI usuwania agentów ze współdzielonego obszaru roboczego, uruchamia e2e sieci Gateway kontenera, weryfikuje argument budowania dołączonego rozszerzenia i uruchamia ograniczony profil Docker dołączonego Pluginu z łącznym limitem czasu polecenia 240 sekund (każde uruchomienie Docker scenariusza jest limitowane osobno).
|
||||
- **Pełna ścieżka** zachowuje instalację pakietu QR oraz zakres instalatora Docker/aktualizacji dla nocnych zaplanowanych uruchomień, ręcznych wywołań, release checków z workflow-call i pull requestów, które rzeczywiście dotykają powierzchni instalatora/pakietu/Docker. W trybie pełnym install-smoke przygotowuje lub ponownie używa jednego obrazu GHCR smoke głównego Dockerfile dla docelowego SHA, a następnie uruchamia instalację pakietu QR, smoke testy głównego Dockerfile/Gateway, smoke testy instalatora/aktualizacji oraz szybkie E2E Docker dołączonego Pluginu jako osobne zadania, aby praca instalatora nie czekała za smoke testami obrazu głównego.
|
||||
- **Szybka ścieżka** uruchamia się dla pull requestów dotykających powierzchni Docker/pakietu, zmian pakietu/manifestu dołączonego pluginu albo powierzchni głównego pluginu/kanału/Gateway/Plugin SDK, które ćwiczą zadania testów Docker. Zmiany tylko w źródłach dołączonych pluginów, edycje wyłącznie testów i edycje wyłącznie dokumentacji nie rezerwują workerów Docker. Szybka ścieżka buduje obraz głównego Dockerfile raz, sprawdza CLI, uruchamia test CLI usuwania agentów we wspólnej przestrzeni roboczej, uruchamia e2e gateway-network kontenera, weryfikuje argument budowania dołączonego rozszerzenia i uruchamia ograniczony profil Docker dołączonych pluginów z łącznym limitem czasu polecenia 240 sekund (każde uruchomienie Docker w scenariuszu jest ograniczone osobno).
|
||||
- **Pełna ścieżka** zachowuje instalację pakietu QR oraz pokrycie Docker instalatora/aktualizacji dla nocnych uruchomień harmonogramu, ręcznych uruchomień, kontroli wydań przez workflow-call oraz pull requestów, które rzeczywiście dotykają powierzchni instalatora/pakietu/Docker. W trybie pełnym install-smoke przygotowuje lub ponownie używa jednego obrazu GHCR z testem głównego Dockerfile dla docelowego SHA, a następnie uruchamia instalację pakietu QR, testy głównego Dockerfile/Gateway, testy instalatora/aktualizacji oraz szybkie Docker E2E dołączonych pluginów jako osobne zadania, aby prace instalatora nie czekały za testami głównego obrazu.
|
||||
|
||||
Wypchnięcia do `main` (w tym commity scalające) nie wymuszają pełnej ścieżki; gdy logika zakresu zmian zażądałaby pełnego pokrycia przy wypchnięciu, workflow zachowuje szybki smoke test Docker i pozostawia pełny smoke test instalacji nocnym uruchomieniom lub walidacji wydania.
|
||||
Wypchnięcia na `main` (w tym commity scalające) nie wymuszają pełnej ścieżki; gdy logika zakresu zmian zażądałaby pełnego pokrycia przy wypchnięciu, przepływ pracy zachowuje szybki test Docker i zostawia pełny test instalacji nocnej walidacji albo walidacji wydania.
|
||||
|
||||
Powolny smoke test globalnej instalacji Bun dla dostawcy obrazów jest bramkowany osobno przez `run_bun_global_install_smoke`. Uruchamia się w nocnym harmonogramie i z workflow release checków, a ręczne wywołania `Install Smoke` mogą go włączyć, ale pull requesty i wypchnięcia do `main` tego nie robią. Testy Docker QR i instalatora zachowują własne Dockerfile skupione na instalacji.
|
||||
Wolny test dostawcy obrazu dla globalnej instalacji Bun jest oddzielnie bramkowany przez `run_bun_global_install_smoke`. Uruchamia się w nocnym harmonogramie i z przepływu kontroli wydania, a ręczne uruchomienia `Install Smoke` mogą go włączyć, ale pull requesty i wypchnięcia na `main` tego nie robią. Testy Docker dla QR i instalatora zachowują własne Dockerfile ukierunkowane na instalację.
|
||||
|
||||
## Lokalne Docker E2E
|
||||
|
||||
`pnpm test:docker:all` wstępnie buduje jeden współdzielony obraz live-test, pakuje OpenClaw raz jako tarball npm i buduje dwa współdzielone obrazy `scripts/e2e/Dockerfile`:
|
||||
`pnpm test:docker:all` wstępnie buduje jeden współdzielony obraz testów live, pakuje OpenClaw raz jako archiwum tarball npm i buduje dwa współdzielone obrazy `scripts/e2e/Dockerfile`:
|
||||
|
||||
- podstawowy runner Node/Git dla torów instalatora/aktualizacji/zależności Pluginu;
|
||||
- obraz funkcjonalny, który instaluje ten sam tarball w `/app` dla normalnych torów funkcjonalności.
|
||||
- prosty runner Node/Git dla linii instalatora/aktualizacji/zależności pluginów;
|
||||
- obraz funkcjonalny, który instaluje to samo archiwum tarball w `/app` dla standardowych linii funkcjonalności.
|
||||
|
||||
Definicje torów Docker znajdują się w `scripts/lib/docker-e2e-scenarios.mjs`, logika planera w `scripts/lib/docker-e2e-plan.mjs`, a runner wykonuje tylko wybrany plan. Scheduler wybiera obraz dla toru za pomocą `OPENCLAW_DOCKER_E2E_BARE_IMAGE` i `OPENCLAW_DOCKER_E2E_FUNCTIONAL_IMAGE`, a następnie uruchamia tory z `OPENCLAW_SKIP_DOCKER_BUILD=1`.
|
||||
Definicje linii Docker znajdują się w `scripts/lib/docker-e2e-scenarios.mjs`, logika planera w `scripts/lib/docker-e2e-plan.mjs`, a runner wykonuje tylko wybrany plan. Harmonogram wybiera obraz dla każdej linii za pomocą `OPENCLAW_DOCKER_E2E_BARE_IMAGE` i `OPENCLAW_DOCKER_E2E_FUNCTIONAL_IMAGE`, a następnie uruchamia linie z `OPENCLAW_SKIP_DOCKER_BUILD=1`.
|
||||
|
||||
### Parametry
|
||||
|
||||
| Zmienna | Domyślnie | Cel |
|
||||
| -------------------------------------- | --------- | --------------------------------------------------------------------------------------------- |
|
||||
| `OPENCLAW_DOCKER_ALL_PARALLELISM` | 10 | Liczba slotów głównej puli dla normalnych torów. |
|
||||
| `OPENCLAW_DOCKER_ALL_TAIL_PARALLELISM` | 10 | Liczba slotów puli końcowej wrażliwej na dostawców. |
|
||||
| `OPENCLAW_DOCKER_ALL_LIVE_LIMIT` | 9 | Limit współbieżnych torów live, aby dostawcy nie ograniczali przepustowości. |
|
||||
| `OPENCLAW_DOCKER_ALL_NPM_LIMIT` | 10 | Limit współbieżnych torów instalacji npm. |
|
||||
| `OPENCLAW_DOCKER_ALL_SERVICE_LIMIT` | 7 | Limit współbieżnych torów wielousługowych. |
|
||||
| `OPENCLAW_DOCKER_ALL_START_STAGGER_MS` | 2000 | Odstęp między startami torów, aby uniknąć nagłych fal tworzenia w daemonie Docker; ustaw `0`, aby wyłączyć odstęp. |
|
||||
| `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS` | 7200000 | Awaryjny limit czasu na tor (120 minut); wybrane tory live/końcowe używają ciaśniejszych limitów. |
|
||||
| `OPENCLAW_DOCKER_ALL_DRY_RUN` | nieustawione | `1` wypisuje plan schedulera bez uruchamiania torów. |
|
||||
| `OPENCLAW_DOCKER_ALL_LANES` | nieustawione | Oddzielona przecinkami dokładna lista torów; pomija smoke test czyszczenia, aby agenci mogli odtworzyć jeden nieudany tor. |
|
||||
| `OPENCLAW_DOCKER_ALL_PARALLELISM` | 10 | Liczba slotów głównej puli dla standardowych linii. |
|
||||
| `OPENCLAW_DOCKER_ALL_TAIL_PARALLELISM` | 10 | Liczba slotów końcowej puli wrażliwej na dostawców. |
|
||||
| `OPENCLAW_DOCKER_ALL_LIVE_LIMIT` | 9 | Limit równoczesnych linii live, aby dostawcy nie ograniczali przepustowości. |
|
||||
| `OPENCLAW_DOCKER_ALL_NPM_LIMIT` | 10 | Limit równoczesnych linii instalacji npm. |
|
||||
| `OPENCLAW_DOCKER_ALL_SERVICE_LIMIT` | 7 | Limit równoczesnych linii wielousługowych. |
|
||||
| `OPENCLAW_DOCKER_ALL_START_STAGGER_MS` | 2000 | Odstęp między startami linii, aby uniknąć burz tworzenia w demonie Docker; ustaw `0`, aby go wyłączyć. |
|
||||
| `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS` | 7200000 | Zastępczy limit czasu na linię (120 minut); wybrane linie live/końcowe używają ciaśniejszych limitów. |
|
||||
| `OPENCLAW_DOCKER_ALL_DRY_RUN` | nieustawione | `1` wypisuje plan harmonogramu bez uruchamiania linii. |
|
||||
| `OPENCLAW_DOCKER_ALL_LANES` | nieustawione | Lista dokładnych linii rozdzielona przecinkami; pomija test czyszczenia, aby agenci mogli odtworzyć jedną nieudaną linię. |
|
||||
|
||||
Tor cięższy niż jego efektywny limit nadal może wystartować z pustej puli, a potem działa samodzielnie, dopóki nie zwolni pojemności. Lokalne zbiorcze preflighty sprawdzają Docker, usuwają przestarzałe kontenery OpenClaw E2E, emitują status aktywnych torów, utrwalają czasy torów dla kolejności od najdłuższych i domyślnie przestają planować nowe tory z puli po pierwszym niepowodzeniu.
|
||||
Linia cięższa niż jej efektywny limit nadal może wystartować z pustej puli, a następnie działa sama, dopóki nie zwolni pojemności. Lokalny agregat wykonuje wstępne kontrole Docker, usuwa przestarzałe kontenery OpenClaw E2E, emituje status aktywnych linii, zapisuje czasy linii do sortowania od najdłuższych i domyślnie przestaje planować nowe linie z puli po pierwszej awarii.
|
||||
|
||||
### Workflow live/E2E wielokrotnego użytku
|
||||
### Wielokrotnego użytku przepływ pracy live/E2E
|
||||
|
||||
Workflow live/E2E wielokrotnego użytku pyta `scripts/test-docker-all.mjs --plan-json`, jakie pokrycie pakietu, rodzaju obrazu, obrazu live, toru i poświadczeń jest wymagane. `scripts/docker-e2e.mjs` konwertuje następnie ten plan na wyjścia i podsumowania GitHub. Albo pakuje OpenClaw przez `scripts/package-openclaw-for-docker.mjs`, pobiera artefakt pakietu z bieżącego uruchomienia, albo pobiera artefakt pakietu z `package_artifact_run_id`; waliduje inwentarz tarballa; buduje i wypycha oznaczone digestem pakietu podstawowe/funkcjonalne obrazy GHCR Docker E2E przez cache warstw Docker Blacksmith, gdy plan wymaga torów z zainstalowanym pakietem; oraz ponownie używa podanych wejść `docker_e2e_bare_image`/`docker_e2e_functional_image` lub istniejących obrazów z digestem pakietu zamiast budować je ponownie. Pobieranie obrazów Docker jest ponawiane z ograniczonym limitem 180 sekund na próbę, aby zablokowany strumień rejestru/cache szybko ponawiał próbę zamiast zużywać większość ścieżki krytycznej CI.
|
||||
Wielokrotnego użytku przepływ pracy live/E2E pyta `scripts/test-docker-all.mjs --plan-json`, jaki pakiet, rodzaj obrazu, obraz live, linia i pokrycie poświadczeń są wymagane. `scripts/docker-e2e.mjs` przekształca następnie ten plan w wyjścia i podsumowania GitHub. Albo pakuje OpenClaw przez `scripts/package-openclaw-for-docker.mjs`, pobiera artefakt pakietu z bieżącego uruchomienia, albo pobiera artefakt pakietu z `package_artifact_run_id`; waliduje inwentarz archiwum tarball; buduje i wypycha obrazy GHCR Docker E2E bare/funkcjonalne tagowane skrótem pakietu przez cache warstw Docker Blacksmith, gdy plan wymaga linii z zainstalowanym pakietem; oraz ponownie używa podanych wejść `docker_e2e_bare_image`/`docker_e2e_functional_image` lub istniejących obrazów ze skrótem pakietu zamiast budować ponownie. Pobieranie obrazów Docker jest ponawiane z ograniczonym limitem 180 sekund na próbę, aby zablokowany strumień rejestru/cache szybko ponawiał próbę zamiast zużywać większość ścieżki krytycznej CI.
|
||||
|
||||
### Fragmenty ścieżki wydania
|
||||
|
||||
Zakres Docker dla wydania uruchamia mniejsze, podzielone zadania z `OPENCLAW_SKIP_DOCKER_BUILD=1`, aby każdy fragment pobierał tylko rodzaj obrazu, którego potrzebuje, i wykonywał wiele torów przez ten sam ważony scheduler:
|
||||
Pokrycie Docker dla wydania działa jako mniejsze podzielone zadania z `OPENCLAW_SKIP_DOCKER_BUILD=1`, aby każdy fragment pobierał tylko potrzebny rodzaj obrazu i wykonywał wiele linii przez ten sam ważony harmonogram:
|
||||
|
||||
- `OPENCLAW_DOCKER_ALL_PROFILE=release-path`
|
||||
- `OPENCLAW_DOCKER_ALL_CHUNK=core | package-update-openai | package-update-anthropic | package-update-core | plugins-runtime-plugins | plugins-runtime-services | plugins-runtime-install-a..h`
|
||||
|
||||
Bieżące fragmenty Docker wydania to `core`, `package-update-openai`, `package-update-anthropic`, `package-update-core`, `plugins-runtime-plugins`, `plugins-runtime-services` oraz od `plugins-runtime-install-a` do `plugins-runtime-install-h`. `plugins-runtime-core`, `plugins-runtime` i `plugins-integrations` pozostają zbiorczymi aliasami Plugin/runtime. Alias toru `install-e2e` pozostaje zbiorczym aliasem ręcznego ponownego uruchomienia dla obu torów instalatora dostawcy.
|
||||
Bieżące fragmenty Docker wydania to `core`, `package-update-openai`, `package-update-anthropic`, `package-update-core`, `plugins-runtime-plugins`, `plugins-runtime-services` oraz od `plugins-runtime-install-a` do `plugins-runtime-install-h`. `plugins-runtime-core`, `plugins-runtime` i `plugins-integrations` pozostają agregującymi aliasami plugin/runtime. Alias linii `install-e2e` pozostaje agregującym ręcznym aliasem ponownego uruchomienia dla obu linii instalatora dostawcy.
|
||||
|
||||
OpenWebUI jest włączane do `plugins-runtime-services`, gdy żąda tego pełne pokrycie ścieżki wydania, i zachowuje samodzielny fragment `openwebui` tylko dla wywołań dotyczących wyłącznie OpenWebUI. Tory aktualizacji dołączonych kanałów ponawiają się raz przy przejściowych awariach sieci npm.
|
||||
OpenWebUI jest składany do `plugins-runtime-services`, gdy żąda tego pełne pokrycie release-path, i zachowuje samodzielny fragment `openwebui` tylko dla uruchomień dotyczących wyłącznie OpenWebUI. Linie aktualizacji dołączonych kanałów ponawiają raz w przypadku przejściowych awarii sieci npm.
|
||||
|
||||
Każdy fragment przesyła `.artifacts/docker-tests/` z logami torów, czasami, `summary.json`, `failures.json`, czasami faz, JSON planu schedulera, tabelami wolnych torów i poleceniami ponownego uruchomienia dla każdego toru. Wejście workflow `docker_lanes` uruchamia wybrane tory względem przygotowanych obrazów zamiast zadań fragmentów, co ogranicza debugowanie nieudanego toru do jednego celowanego zadania Docker i przygotowuje, pobiera lub ponownie używa artefaktu pakietu dla tego uruchomienia; jeśli wybrany tor jest torem live Docker, celowane zadanie buduje lokalnie obraz live-test dla tego ponownego uruchomienia. Wygenerowane polecenia GitHub ponownego uruchomienia dla każdego toru zawierają `package_artifact_run_id`, `package_artifact_name` i wejścia przygotowanych obrazów, gdy te wartości istnieją, aby nieudany tor mógł ponownie użyć dokładnego pakietu i obrazów z nieudanego uruchomienia.
|
||||
Każdy fragment przesyła `.artifacts/docker-tests/` z dziennikami linii, czasami, `summary.json`, `failures.json`, czasami faz, JSON planu harmonogramu, tabelami wolnych linii i poleceniami ponownego uruchomienia na linię. Wejście przepływu pracy `docker_lanes` uruchamia wybrane linie względem przygotowanych obrazów zamiast zadań fragmentów, co utrzymuje debugowanie nieudanej linii w ramach jednego ukierunkowanego zadania Docker oraz przygotowuje, pobiera albo ponownie używa artefaktu pakietu dla tego uruchomienia; jeśli wybrana linia jest linią Docker live, ukierunkowane zadanie buduje lokalnie obraz testów live dla tego ponownego uruchomienia. Wygenerowane polecenia GitHub ponownego uruchomienia na linię zawierają `package_artifact_run_id`, `package_artifact_name` i wejścia przygotowanych obrazów, gdy te wartości istnieją, dzięki czemu nieudana linia może ponownie użyć dokładnego pakietu i obrazów z nieudanego uruchomienia.
|
||||
|
||||
```bash
|
||||
pnpm test:docker:rerun <run-id> # download Docker artifacts and print combined/per-lane targeted rerun commands
|
||||
pnpm test:docker:timings <summary> # slow-lane and phase critical-path summaries
|
||||
```
|
||||
|
||||
Zaplanowany workflow live/E2E uruchamia codziennie pełny zestaw Docker ścieżki wydania.
|
||||
Zaplanowany przepływ pracy live/E2E uruchamia codziennie pełny zestaw Docker release-path.
|
||||
|
||||
## Plugin Prerelease
|
||||
## Wersja przedpremierowa Plugin
|
||||
|
||||
`Plugin Prerelease` to droższe pokrycie produktu/pakietu, więc jest osobnym workflow wywoływanym przez `Full Release Validation` albo jawnie przez operatora. Zwykłe pull requesty, wypchnięcia do `main` i samodzielne ręczne wywołania CI nie uruchamiają tego zestawu. Równoważy testy dołączonych Pluginów na ośmiu workerach rozszerzeń; te zadania shardów rozszerzeń uruchamiają do dwóch grup konfiguracji Pluginów naraz, z jednym workerem Vitest na grupę i większym stertą Node, aby ciężkie importowo partie Pluginów nie tworzyły dodatkowych zadań CI. Ścieżka prerelease Docker tylko dla wydania grupuje celowane tory Docker w małe grupy, aby uniknąć rezerwowania dziesiątek runnerów dla zadań trwających od jednej do trzech minut.
|
||||
`Plugin Prerelease` to droższe pokrycie produktu/pakietu, dlatego jest osobnym przepływem pracy uruchamianym przez `Full Release Validation` albo przez jawnego operatora. Zwykłe pull requesty, wypchnięcia na `main` i samodzielne ręczne uruchomienia CI pozostawiają ten zestaw wyłączony. Równoważy testy dołączonych pluginów na ośmiu workerach rozszerzeń; te zadania shardów rozszerzeń uruchamiają do dwóch grup konfiguracji pluginów naraz, z jednym workerem Vitest na grupę i większą stertą Node, aby ciężkie importami partie pluginów nie tworzyły dodatkowych zadań CI. Ścieżka Docker przedwydaniowa tylko dla wydań grupuje ukierunkowane linie Docker w małe grupy, aby uniknąć rezerwowania dziesiątek runnerów dla zadań trwających od jednej do trzech minut.
|
||||
|
||||
## QA Lab
|
||||
## Laboratorium QA
|
||||
|
||||
QA Lab ma dedykowane tory CI poza głównym workflow z inteligentnym zakresem. Parzystość agentowa jest zagnieżdżona pod szerokimi harnessami QA i wydania, a nie samodzielnym workflow PR. Użyj `Full Release Validation` z `rerun_group=qa-parity`, gdy parzystość ma jechać razem z szerokim uruchomieniem walidacji.
|
||||
QA Lab ma dedykowane linie CI poza głównym inteligentnie zakresowanym przepływem pracy. Parzystość agentowa jest zagnieżdżona pod szerokimi zestawami QA i wydania, a nie jako samodzielny przepływ pracy PR. Użyj `Full Release Validation` z `rerun_group=qa-parity`, gdy parzystość powinna iść razem z szerokim uruchomieniem walidacji.
|
||||
|
||||
- Workflow `QA-Lab - All Lanes` uruchamia się co noc na `main` i przy ręcznym wywołaniu; rozdziela tor parzystości mock, tor live Matrix oraz tory live Telegram i Discord jako zadania równoległe. Zadania live używają środowiska `qa-live-shared`, a Telegram/Discord używają dzierżaw Convex.
|
||||
- Przepływ pracy `QA-Lab - All Lanes` działa nocą na `main` i przy ręcznym uruchomieniu; rozdziela linię mock parity, linię live Matrix oraz linie live Telegram i Discord jako równoległe zadania. Zadania live używają środowiska `qa-live-shared`, a Telegram/Discord używają dzierżaw Convex.
|
||||
|
||||
Release checki uruchamiają tory transportu live Matrix i Telegram z deterministycznym dostawcą mock i modelami kwalifikowanymi jako mock (`mock-openai/gpt-5.5` i `mock-openai/gpt-5.5-alt`), aby kontrakt kanału był odizolowany od opóźnień modeli live i normalnego startu provider-plugin. Gateway transportu live wyłącza wyszukiwanie pamięci, ponieważ parzystość QA pokrywa zachowanie pamięci osobno; łączność dostawcy pokrywają osobne zestawy modeli live, natywnych dostawców i dostawców Docker.
|
||||
Kontrole wydania uruchamiają linie transportu live Matrix i Telegram z deterministycznym dostawcą mock i modelami kwalifikowanymi mock (`mock-openai/gpt-5.5` i `mock-openai/gpt-5.5-alt`), aby kontrakt kanału był odizolowany od opóźnień modelu live i standardowego startu pluginu dostawcy. Gateway transportu live wyłącza wyszukiwanie pamięci, ponieważ parzystość QA obejmuje zachowanie pamięci osobno; łączność dostawcy jest pokryta przez osobne zestawy modelu live, natywnego dostawcy i dostawcy Docker.
|
||||
|
||||
Matrix używa `--profile fast` dla zaplanowanych bramek i bramek wydania, dodając `--fail-fast` tylko wtedy, gdy sprawdzony CLI to obsługuje. Domyślne ustawienie CLI i wejście ręcznego workflow pozostają `all`; ręczne wywołanie `matrix_profile=all` zawsze sharduje pełne pokrycie Matrix na zadania `transport`, `media`, `e2ee-smoke`, `e2ee-deep` i `e2ee-cli`.
|
||||
Matrix używa `--profile fast` dla bramek harmonogramu i wydania, dodając `--fail-fast` tylko wtedy, gdy obsługuje to pobrane CLI. Domyślne CLI i ręczne wejście przepływu pracy pozostają `all`; ręczne uruchomienie `matrix_profile=all` zawsze dzieli pełne pokrycie Matrix na zadania `transport`, `media`, `e2ee-smoke`, `e2ee-deep` i `e2ee-cli`.
|
||||
|
||||
`OpenClaw Release Checks` uruchamia również krytyczne dla wydania tory QA Lab przed zatwierdzeniem wydania; jego bramka parzystości QA uruchamia paczki kandydata i bazową jako równoległe zadania torów, a następnie pobiera oba artefakty do małego zadania raportującego dla końcowego porównania parzystości.
|
||||
`OpenClaw Release Checks` uruchamia również krytyczne dla wydania linie QA Lab przed zatwierdzeniem wydania; jego bramka QA parity uruchamia pakiety kandydujące i bazowe jako równoległe zadania linii, a następnie pobiera oba artefakty do małego zadania raportu na potrzeby końcowego porównania parzystości.
|
||||
|
||||
Dla zwykłych PR-ów kieruj się dowodami z zakresowego CI/checków zamiast traktować parzystość jako wymagany status.
|
||||
Dla zwykłych PR-ów korzystaj z dowodów zakresowanego CI/kontroli zamiast traktować parzystość jako wymagany status.
|
||||
|
||||
## CodeQL
|
||||
|
||||
Przepływ pracy `CodeQL` jest celowo wąskim skanerem bezpieczeństwa pierwszego przebiegu, a nie pełnym przeglądem repozytorium. Codzienne, ręczne oraz ochronne uruchomienia dla pull requestów niebędących wersjami roboczymi skanują kod przepływów pracy Actions oraz najbardziej ryzykowne powierzchnie JavaScript/TypeScript za pomocą zapytań bezpieczeństwa o wysokiej pewności, filtrowanych do wysokiego/krytycznego `security-severity`.
|
||||
Przepływ pracy `CodeQL` jest celowo wąskim skanerem bezpieczeństwa pierwszego przebiegu, a nie pełnym przeglądem repozytorium. Codzienne, ręczne oraz ochronne uruchomienia dla nie-roboczych pull requestów skanują kod przepływów pracy Actions oraz powierzchnie JavaScript/TypeScript o najwyższym ryzyku, używając zapytań bezpieczeństwa o wysokiej pewności, filtrowanych do wysokiej/krytycznej wartości `security-severity`.
|
||||
|
||||
Ochrona pull requestów pozostaje lekka: uruchamia się tylko dla zmian w `.github/actions`, `.github/codeql`, `.github/workflows`, `packages` lub `src` i wykonuje tę samą macierz bezpieczeństwa o wysokiej pewności co zaplanowany przepływ pracy. Android i macOS CodeQL pozostają poza domyślnymi ustawieniami PR.
|
||||
|
||||
### Kategorie bezpieczeństwa
|
||||
|
||||
| Kategoria | Powierzchnia |
|
||||
| Kategoria | Powierzchnia |
|
||||
| ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `/codeql-security-high/core-auth-secrets` | Uwierzytelnianie, sekrety, piaskownica, cron i linia bazowa Gateway |
|
||||
| `/codeql-security-high/channel-runtime-boundary` | Kontrakty implementacji kanałów rdzenia oraz środowisko uruchomieniowe Plugin kanału, Gateway, Plugin SDK, sekrety i punkty styku audytu |
|
||||
| `/codeql-security-high/network-ssrf-boundary` | Powierzchnie zasad SSRF rdzenia, parsowania IP, ochrony sieci, pobierania z sieci oraz SSRF w Plugin SDK |
|
||||
| `/codeql-security-high/mcp-process-tool-boundary` | Serwery MCP, pomocnicze funkcje wykonywania procesów, dostarczanie wychodzące oraz bramki wykonywania narzędzi agenta |
|
||||
| `/codeql-security-high/core-auth-secrets` | Auth, sekrety, piaskownica, Cron i bazowe elementy Gateway |
|
||||
| `/codeql-security-high/channel-runtime-boundary` | Kontrakty implementacji kanałów rdzenia oraz środowisko uruchomieniowe Plugin kanału, Gateway, Plugin SDK, sekrety, punkty audytu |
|
||||
| `/codeql-security-high/network-ssrf-boundary` | Powierzchnie rdzenia SSRF, parsowania IP, osłony sieciowej, web-fetch oraz polityki SSRF w Plugin SDK |
|
||||
| `/codeql-security-high/mcp-process-tool-boundary` | Serwery MCP, pomocniki wykonywania procesów, dostarczanie wychodzące oraz bramki wykonywania narzędzi agenta |
|
||||
| `/codeql-security-high/plugin-trust-boundary` | Powierzchnie zaufania instalacji Plugin, loadera, manifestu, rejestru, instalacji menedżera pakietów, ładowania źródeł oraz kontraktu pakietu Plugin SDK |
|
||||
|
||||
### Shardy bezpieczeństwa specyficzne dla platform
|
||||
### Shardy bezpieczeństwa zależne od platformy
|
||||
|
||||
- `CodeQL Android Critical Security` — zaplanowany shard bezpieczeństwa Androida. Ręcznie buduje aplikację Android dla CodeQL na najmniejszym runnerze Blacksmith Linux akceptowanym przez kontrolę poprawności przepływu pracy. Przesyła wyniki pod `/codeql-critical-security/android`.
|
||||
- `CodeQL macOS Critical Security` — cotygodniowy/ręczny shard bezpieczeństwa macOS. Ręcznie buduje aplikację macOS dla CodeQL na Blacksmith macOS, odfiltrowuje wyniki budowania zależności z przesyłanego SARIF i przesyła wyniki pod `/codeql-critical-security/macos`. Pozostaje poza codziennymi ustawieniami domyślnymi, ponieważ kompilacja macOS dominuje czas działania nawet przy czystym przebiegu.
|
||||
- `CodeQL Android Critical Security` — zaplanowany shard bezpieczeństwa Androida. Buduje aplikację Android ręcznie dla CodeQL na najmniejszym runnerze Blacksmith Linux akceptowanym przez sanity przepływu pracy. Przesyła wyniki pod `/codeql-critical-security/android`.
|
||||
- `CodeQL macOS Critical Security` — tygodniowy/ręczny shard bezpieczeństwa macOS. Buduje aplikację macOS ręcznie dla CodeQL na Blacksmith macOS, odfiltrowuje wyniki budowania zależności z przesyłanego SARIF i przesyła pod `/codeql-critical-security/macos`. Utrzymywany poza codziennymi domyślnymi ustawieniami, ponieważ budowanie macOS dominuje czas działania nawet wtedy, gdy jest czyste.
|
||||
|
||||
### Kategorie jakości krytycznej
|
||||
### Kategorie krytycznej jakości
|
||||
|
||||
`CodeQL Critical Quality` to odpowiadający shard niezwiązany z bezpieczeństwem. Uruchamia tylko zapytania jakości JavaScript/TypeScript o poziomie błędu, niezwiązane z bezpieczeństwem, na wąskich powierzchniach o wysokiej wartości na mniejszym runnerze Blacksmith Linux. Jego ochrona pull requestów jest celowo mniejsza niż zaplanowany profil: PR-y niebędące wersjami roboczymi uruchamiają tylko odpowiadające shardy `agent-runtime-boundary`, `config-boundary`, `core-auth-secrets`, `channel-runtime-boundary`, `gateway-runtime-boundary`, `memory-runtime-boundary`, `mcp-process-runtime-boundary`, `provider-runtime-boundary`, `session-diagnostics-boundary`, `plugin-boundary`, `plugin-sdk-package-contract` i `plugin-sdk-reply-runtime` dla zmian w kodzie wykonywania poleceń/modeli/narzędzi agenta i wysyłania odpowiedzi, kodzie schematu konfiguracji/migracji/IO, kodzie uwierzytelniania/sekretów/piaskownicy/bezpieczeństwa, środowisku uruchomieniowym kanałów rdzenia i dołączonego Plugin kanału, protokole Gateway/metodzie serwera, kleju runtime/SDK pamięci, dostarczaniu MCP/procesów/wychodzącym, runtime dostawcy/katalogu modeli, diagnostyce sesji/kolejkach dostarczania, loaderze Plugin, kontrakcie Plugin SDK/pakietu lub runtime odpowiedzi Plugin SDK. Zmiany konfiguracji CodeQL i przepływu pracy jakości uruchamiają wszystkie dwanaście shardów jakości PR.
|
||||
`CodeQL Critical Quality` to odpowiadający shard niezwiązany z bezpieczeństwem. Uruchamia wyłącznie zapytania jakości JavaScript/TypeScript o ważności błędu, niezwiązane z bezpieczeństwem, na wąskich powierzchniach o wysokiej wartości, na mniejszym runnerze Blacksmith Linux. Jego ochrona pull requestów jest celowo mniejsza niż zaplanowany profil: nie-robocze PR-y uruchamiają tylko odpowiadające shardy `agent-runtime-boundary`, `config-boundary`, `core-auth-secrets`, `channel-runtime-boundary`, `gateway-runtime-boundary`, `memory-runtime-boundary`, `mcp-process-runtime-boundary`, `provider-runtime-boundary`, `session-diagnostics-boundary`, `plugin-boundary`, `plugin-sdk-package-contract` i `plugin-sdk-reply-runtime` dla zmian w kodzie wykonywania poleceń/modeli/narzędzi agenta i wysyłania odpowiedzi, kodzie schematu/migracji/IO konfiguracji, kodzie auth/sekretów/piaskownicy/bezpieczeństwa, rdzeniowym środowisku uruchomieniowym kanału i dołączonego Plugin kanału, protokole Gateway/metodach serwera, środowisku uruchomieniowym pamięci/kleju SDK, MCP/procesie/dostarczaniu wychodzącym, środowisku uruchomieniowym dostawcy/katalogu modeli, diagnostyce sesji/kolejkach dostarczania, loaderze Plugin, Plugin SDK/kontrakcie pakietu lub środowisku uruchomieniowym odpowiedzi Plugin SDK. Zmiany konfiguracji CodeQL i przepływu pracy jakości uruchamiają wszystkie dwanaście shardów jakości PR.
|
||||
|
||||
Ręczne wywołanie przyjmuje:
|
||||
Ręczne uruchomienie przyjmuje:
|
||||
|
||||
```
|
||||
profile=all|agent-runtime-boundary|config-boundary|core-auth-secrets|channel-runtime-boundary|gateway-runtime-boundary|memory-runtime-boundary|mcp-process-runtime-boundary|plugin-boundary|plugin-sdk-package-contract|plugin-sdk-reply-runtime|provider-runtime-boundary|session-diagnostics-boundary
|
||||
```
|
||||
|
||||
Wąskie profile są zaczepami do nauki/iteracji służącymi do uruchamiania jednego sharda jakości w izolacji.
|
||||
Wąskie profile są hakami dydaktycznymi/iteracyjnymi do uruchamiania jednego sharda jakości w izolacji.
|
||||
|
||||
| Kategoria | Powierzchnia |
|
||||
| Kategoria | Powierzchnia |
|
||||
| ------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `/codeql-critical-quality/core-auth-secrets` | Kod granicy bezpieczeństwa uwierzytelniania, sekretów, piaskownicy, cron i Gateway |
|
||||
| `/codeql-critical-quality/config-boundary` | Schemat konfiguracji, migracja, normalizacja i kontrakty IO |
|
||||
| `/codeql-critical-quality/gateway-runtime-boundary` | Schematy protokołu Gateway i kontrakty metod serwera |
|
||||
| `/codeql-critical-quality/channel-runtime-boundary` | Kontrakty implementacji kanału rdzenia i dołączonego Plugin kanału |
|
||||
| `/codeql-critical-quality/agent-runtime-boundary` | Wykonywanie poleceń, wysyłanie modelu/dostawcy, wysyłanie automatycznych odpowiedzi i kolejki oraz kontrakty runtime płaszczyzny sterowania ACP |
|
||||
| `/codeql-critical-quality/mcp-process-runtime-boundary` | Serwery MCP i mosty narzędzi, pomocnicze funkcje nadzoru procesów oraz kontrakty dostarczania wychodzącego |
|
||||
| `/codeql-critical-quality/memory-runtime-boundary` | SDK hosta pamięci, fasady runtime pamięci, aliasy Plugin SDK pamięci, klej aktywacji runtime pamięci oraz polecenia doctor pamięci |
|
||||
| `/codeql-critical-quality/session-diagnostics-boundary` | Wewnętrzne elementy kolejki odpowiedzi, kolejki dostarczania sesji, pomocnicze funkcje wiązania/dostarczania sesji wychodzących, powierzchnie pakietów zdarzeń/logów diagnostycznych oraz kontrakty CLI doctor sesji |
|
||||
| `/codeql-critical-quality/plugin-sdk-reply-runtime` | Wysyłanie odpowiedzi przychodzących w Plugin SDK, pomocnicze funkcje payloadów/fragmentacji/runtime odpowiedzi, opcje odpowiedzi kanału, kolejki dostarczania oraz pomocnicze funkcje wiązania sesji/wątku |
|
||||
| `/codeql-critical-quality/provider-runtime-boundary` | Normalizacja katalogu modeli, uwierzytelnianie i wykrywanie dostawców, rejestracja runtime dostawców, ustawienia domyślne/katalogi dostawców oraz rejestry sieci/wyszukiwania/pobierania/embeddingów |
|
||||
| `/codeql-critical-quality/ui-control-plane` | Bootstrap interfejsu sterowania, lokalna trwałość, przepływy sterowania Gateway oraz kontrakty runtime płaszczyzny sterowania zadaniami |
|
||||
| `/codeql-critical-quality/web-media-runtime-boundary` | Kontrakty runtime pobierania/wyszukiwania w sieci rdzenia, IO mediów, rozumienia mediów, generowania obrazów i generowania mediów |
|
||||
| `/codeql-critical-quality/plugin-boundary` | Kontrakty loadera, rejestru, powierzchni publicznej oraz punktu wejścia Plugin SDK |
|
||||
| `/codeql-critical-quality/plugin-sdk-package-contract` | Opublikowane źródło Plugin SDK po stronie pakietu oraz pomocnicze funkcje kontraktu pakietu pluginu |
|
||||
| `/codeql-critical-quality/core-auth-secrets` | Kod granicy bezpieczeństwa Auth, sekretów, piaskownicy, Cron i Gateway |
|
||||
| `/codeql-critical-quality/config-boundary` | Kontrakty schematu konfiguracji, migracji, normalizacji i IO |
|
||||
| `/codeql-critical-quality/gateway-runtime-boundary` | Schematy protokołu Gateway i kontrakty metod serwera |
|
||||
| `/codeql-critical-quality/channel-runtime-boundary` | Kontrakty implementacji rdzeniowego kanału i dołączonego Plugin kanału |
|
||||
| `/codeql-critical-quality/agent-runtime-boundary` | Kontrakty środowiska uruchomieniowego wykonywania poleceń, wysyłania modeli/dostawców, automatycznego wysyłania odpowiedzi i kolejek oraz płaszczyzny sterowania ACP |
|
||||
| `/codeql-critical-quality/mcp-process-runtime-boundary` | Serwery MCP i mosty narzędzi, pomocniki nadzoru procesów oraz kontrakty dostarczania wychodzącego |
|
||||
| `/codeql-critical-quality/memory-runtime-boundary` | SDK hosta pamięci, fasady środowiska uruchomieniowego pamięci, aliasy pamięci Plugin SDK, klej aktywacji środowiska uruchomieniowego pamięci i polecenia doctor pamięci |
|
||||
| `/codeql-critical-quality/session-diagnostics-boundary` | Wewnętrzne elementy kolejki odpowiedzi, kolejki dostarczania sesji, pomocniki wiązania/dostarczania sesji wychodzących, powierzchnie zdarzeń diagnostycznych/pakietów logów oraz kontrakty CLI doctor sesji |
|
||||
| `/codeql-critical-quality/plugin-sdk-reply-runtime` | Wysyłanie przychodzących odpowiedzi Plugin SDK, pomocniki payloadów/fragmentacji/środowiska uruchomieniowego odpowiedzi, opcje odpowiedzi kanału, kolejki dostarczania oraz pomocniki wiązania sesji/wątków |
|
||||
| `/codeql-critical-quality/provider-runtime-boundary` | Normalizacja katalogu modeli, auth i wykrywanie dostawców, rejestracja środowiska uruchomieniowego dostawcy, domyślne ustawienia/katalogi dostawców oraz rejestry web/search/fetch/embedding |
|
||||
| `/codeql-critical-quality/ui-control-plane` | Bootstrap Control UI, lokalna trwałość, przepływy sterowania Gateway oraz kontrakty środowiska uruchomieniowego płaszczyzny sterowania zadaniami |
|
||||
| `/codeql-critical-quality/web-media-runtime-boundary` | Kontrakty środowiska uruchomieniowego rdzeniowego web fetch/search, IO mediów, rozumienia mediów, generowania obrazów i generowania mediów |
|
||||
| `/codeql-critical-quality/plugin-boundary` | Kontrakty loadera, rejestru, powierzchni publicznej i punktów wejścia Plugin SDK |
|
||||
| `/codeql-critical-quality/plugin-sdk-package-contract` | Opublikowane źródło Plugin SDK po stronie pakietu i pomocniki kontraktu pakietu Plugin |
|
||||
|
||||
Jakość pozostaje oddzielona od bezpieczeństwa, aby ustalenia jakości można było planować, mierzyć, wyłączać lub rozszerzać bez zaciemniania sygnału bezpieczeństwa. Rozszerzenie CodeQL dla Swift, Python i dołączonych pluginów należy dodać ponownie jako zakresowane lub shardowane prace następcze dopiero po tym, jak wąskie profile będą miały stabilny czas działania i sygnał.
|
||||
Jakość pozostaje oddzielona od bezpieczeństwa, aby ustalenia jakościowe można było planować, mierzyć, wyłączać lub rozszerzać bez zasłaniania sygnału bezpieczeństwa. Rozszerzenie CodeQL dla Swift, Python i dołączonych Plugin powinno zostać dodane z powrotem jako zakresowana lub shardowana praca następcza dopiero po ustabilizowaniu czasu działania i sygnału wąskich profili.
|
||||
|
||||
## Przepływy pracy utrzymaniowej
|
||||
## Przepływy pracy utrzymania
|
||||
|
||||
### Docs Agent
|
||||
|
||||
Przepływ pracy `Docs Agent` to sterowana zdarzeniami ścieżka utrzymaniowa Codex do utrzymywania istniejącej dokumentacji w zgodzie z niedawno wprowadzonymi zmianami. Nie ma czystego harmonogramu: udany przebieg CI po wypchnięciu przez nie-bota na `main` może go wyzwolić, a ręczne wywołanie może uruchomić go bezpośrednio. Wywołania workflow-run są pomijane, gdy `main` przesunął się dalej albo gdy inny niepominięty przebieg Docs Agent został utworzony w ostatniej godzinie. Gdy działa, przegląda zakres commitów od poprzedniego niepominiętego źródłowego SHA Docs Agent do bieżącego `main`, więc jeden godzinny przebieg może objąć wszystkie zmiany na main zgromadzone od ostatniego przeglądu dokumentacji.
|
||||
Przepływ pracy `Docs Agent` to sterowana zdarzeniami ścieżka utrzymania Codex do utrzymywania istniejącej dokumentacji w zgodzie z ostatnio wprowadzonymi zmianami. Nie ma czystego harmonogramu: udany przebieg CI dla push na `main` od nie-bota może go wyzwolić, a ręczne uruchomienie może wykonać go bezpośrednio. Wywołania przez workflow-run są pomijane, gdy `main` przesunął się dalej albo gdy w ostatniej godzinie utworzono inny niepominięty przebieg Docs Agent. Gdy działa, przegląda zakres commitów od poprzedniego niepominiętego źródłowego SHA Docs Agent do bieżącego `main`, więc jeden godzinowy przebieg może objąć wszystkie zmiany na main zgromadzone od ostatniego przebiegu dokumentacji.
|
||||
|
||||
### Test Performance Agent
|
||||
|
||||
Przepływ pracy `Test Performance Agent` to sterowana zdarzeniami ścieżka utrzymaniowa Codex dla wolnych testów. Nie ma czystego harmonogramu: udany przebieg CI po wypchnięciu przez nie-bota na `main` może go wyzwolić, ale jest pomijany, jeśli inne wywołanie workflow-run już wykonało się lub działa tego dnia UTC. Ręczne wywołanie omija tę dzienną bramkę aktywności. Ścieżka buduje pogrupowany raport wydajności Vitest dla pełnego zestawu, pozwala Codex wprowadzać tylko małe poprawki wydajności testów zachowujące pokrycie zamiast szerokich refaktoryzacji, następnie ponownie uruchamia raport pełnego zestawu i odrzuca zmiany, które zmniejszają bazową liczbę przechodzących testów. Jeśli linia bazowa ma testy zakończone niepowodzeniem, Codex może naprawić tylko oczywiste awarie, a raport pełnego zestawu po agencie musi przejść, zanim cokolwiek zostanie zatwierdzone. Gdy `main` przesunie się, zanim wypchnięcie bota wyląduje, ścieżka rebazuje zweryfikowaną poprawkę, ponownie uruchamia `pnpm check:changed` i ponawia wypchnięcie; konfliktujące przestarzałe poprawki są pomijane. Używa GitHub-hosted Ubuntu, aby akcja Codex mogła zachować tę samą postawę bezpieczeństwa drop-sudo co agent dokumentacji.
|
||||
Przepływ pracy `Test Performance Agent` to sterowana zdarzeniami ścieżka utrzymania Codex dla wolnych testów. Nie ma czystego harmonogramu: udany przebieg CI dla push na `main` od nie-bota może go wyzwolić, ale jest pomijany, jeśli inne wywołanie workflow-run już działało lub działa tego dnia UTC. Ręczne uruchomienie omija tę dzienną bramkę aktywności. Ścieżka buduje pogrupowany raport wydajności Vitest dla pełnego zestawu, pozwala Codex wprowadzać tylko małe poprawki wydajności testów zachowujące pokrycie zamiast szerokich refaktoryzacji, a następnie ponownie uruchamia raport pełnego zestawu i odrzuca zmiany zmniejszające bazową liczbę przechodzących testów. Jeśli baza ma testy zakończone niepowodzeniem, Codex może naprawić tylko oczywiste niepowodzenia, a raport pełnego zestawu po agencie musi przejść, zanim cokolwiek zostanie zacommitowane. Gdy `main` przesuwa się, zanim push bota trafi do repozytorium, ścieżka rebase'uje zweryfikowaną poprawkę, ponownie uruchamia `pnpm check:changed` i ponawia push; konfliktujące, nieaktualne poprawki są pomijane. Używa hostowanego przez GitHub Ubuntu, aby akcja Codex mogła zachować tę samą postawę bezpieczeństwa drop-sudo co agent dokumentacji.
|
||||
|
||||
### Zduplikowane PR-y po scaleniu
|
||||
|
||||
Przepływ pracy `Duplicate PRs After Merge` to ręczny przepływ pracy maintainerów do sprzątania duplikatów po wylądowaniu. Domyślnie działa w trybie dry-run i zamyka tylko jawnie wymienione PR-y, gdy `apply=true`. Przed modyfikacją GitHub weryfikuje, że wylądowany PR został scalony oraz że każdy duplikat ma albo wspólne odwołanie do issue, albo nakładające się zmienione hunki.
|
||||
Przepływ pracy `Duplicate PRs After Merge` to ręczny przepływ pracy maintainerów do porządkowania duplikatów po wylądowaniu zmian. Domyślnie działa w trybie dry-run i zamyka tylko jawnie wymienione PR-y, gdy `apply=true`. Przed modyfikowaniem GitHub weryfikuje, że wylądowany PR jest scalony oraz że każdy duplikat ma wspólne powiązane issue albo nakładające się zmienione hunki.
|
||||
|
||||
```bash
|
||||
gh workflow run duplicate-after-merge.yml \
|
||||
@ -475,40 +474,117 @@ gh workflow run duplicate-after-merge.yml \
|
||||
-f apply=true
|
||||
```
|
||||
|
||||
## Lokalne bramki kontroli i routingu zmian
|
||||
## Lokalne bramki sprawdzania i routing zmian
|
||||
|
||||
Lokalna logika changed-lane znajduje się w `scripts/changed-lanes.mjs` i jest wykonywana przez `scripts/check-changed.mjs`. Ta lokalna bramka kontroli jest bardziej rygorystyczna wobec granic architektury niż szeroki zakres platformy CI:
|
||||
Lokalna logika changed-lane znajduje się w `scripts/changed-lanes.mjs` i jest wykonywana przez `scripts/check-changed.mjs`. Ta lokalna bramka sprawdzająca jest bardziej rygorystyczna wobec granic architektury niż szeroki zakres platformy CI:
|
||||
|
||||
- zmiany produkcyjne rdzenia uruchamiają typecheck produkcji rdzenia i testów rdzenia oraz lint/guardy rdzenia;
|
||||
- zmiany wyłącznie testowe rdzenia uruchamiają tylko typecheck testów rdzenia oraz lint rdzenia;
|
||||
- zmiany produkcyjne rozszerzeń uruchamiają typecheck produkcji rozszerzeń i testów rozszerzeń oraz lint rozszerzeń;
|
||||
- zmiany wyłącznie testowe rozszerzeń uruchamiają typecheck testów rozszerzeń oraz lint rozszerzeń;
|
||||
- publiczne zmiany Plugin SDK lub kontraktu pluginu rozszerzają się do typechecku rozszerzeń, ponieważ rozszerzenia zależą od tych kontraktów rdzenia (przeglądy Vitest rozszerzeń pozostają jawną pracą testową);
|
||||
- podbicia wersji wyłącznie w metadanych wydania uruchamiają ukierunkowane kontrole wersji/konfiguracji/zależności roota;
|
||||
- nieznane zmiany roota/konfiguracji bezpiecznie przechodzą do wszystkich ścieżek kontroli.
|
||||
- zmiany produkcyjne rdzenia uruchamiają typecheck produkcji rdzenia i testów rdzenia oraz lint/osłony rdzenia;
|
||||
- zmiany dotyczące wyłącznie testów rdzenia uruchamiają tylko typecheck testów rdzenia oraz lint rdzenia;
|
||||
- zmiany produkcyjne extension uruchamiają typecheck produkcji extension i testów extension oraz lint extension;
|
||||
- zmiany dotyczące wyłącznie testów extension uruchamiają typecheck testów extension oraz lint extension;
|
||||
- zmiany publicznego Plugin SDK lub kontraktu Plugin rozszerzają się do typecheck extension, ponieważ extension zależą od tych kontraktów rdzenia (przeglądy Vitest extension pozostają jawną pracą testową);
|
||||
- wersje podbijane wyłącznie w metadanych wydania uruchamiają ukierunkowane sprawdzenia wersji/konfiguracji/zależności root;
|
||||
- nieznane zmiany root/konfiguracji bezpiecznie przechodzą do wszystkich ścieżek sprawdzania.
|
||||
|
||||
Lokalny routing changed-test znajduje się w `scripts/test-projects.test-support.mjs` i jest celowo tańszy niż `check:changed`: bezpośrednie edycje testów uruchamiają same siebie, edycje źródeł preferują jawne mapowania, a następnie testy sąsiednie i zależne z grafu importów. Wspólna konfiguracja dostarczania group-room jest jednym z jawnych mapowań: zmiany w konfiguracji widocznych odpowiedzi grupy, trybie dostarczania odpowiedzi źródłowej lub systemowym promptcie narzędzia wiadomości są kierowane przez testy odpowiedzi rdzenia oraz regresje dostarczania Discord i Slack, aby wspólna zmiana domyślna zawiodła przed pierwszym wypchnięciem PR. Używaj `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed` tylko wtedy, gdy zmiana jest na tyle szeroka dla całego harnessu, że tani zestaw mapowany nie jest wiarygodnym przybliżeniem.
|
||||
Lokalny routing changed-test znajduje się w `scripts/test-projects.test-support.mjs` i jest celowo tańszy niż `check:changed`: bezpośrednie edycje testów uruchamiają same siebie, edycje źródeł preferują jawne mapowania, a następnie testy rodzeństwa i zależne elementy z grafu importów. Współdzielona konfiguracja dostarczania group-room jest jednym z jawnych mapowań: zmiany w konfiguracji odpowiedzi widocznej dla grupy, trybie dostarczania odpowiedzi źródłowej lub systemowym promptcie narzędzia wiadomości przechodzą przez testy odpowiedzi rdzenia oraz regresje dostarczania Discord i Slack, aby współdzielona zmiana domyślna zawiodła przed pierwszym pushem PR. Używaj `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed` tylko wtedy, gdy zmiana jest na tyle szeroka dla całego harnessu, że tani zmapowany zestaw nie jest wiarygodnym przybliżeniem.
|
||||
|
||||
## Walidacja Testbox
|
||||
|
||||
Uruchamiaj Testbox z katalogu głównego repozytorium i preferuj świeżo rozgrzaną maszynę do szerokiego potwierdzenia. Zanim poświęcisz wolną bramkę na maszynie, która została użyta ponownie, wygasła albo właśnie zgłosiła nieoczekiwanie dużą synchronizację, najpierw uruchom `pnpm testbox:sanity` wewnątrz tej maszyny.
|
||||
Uruchamiaj Testbox z katalogu głównego repozytorium i przy szerokiej weryfikacji preferuj świeżo przygotowaną instancję. Zanim poświęcisz wolną bramkę na instancję, która została użyta ponownie, wygasła albo właśnie zgłosiła nieoczekiwanie dużą synchronizację, najpierw uruchom w niej `pnpm testbox:sanity`.
|
||||
|
||||
Kontrola sanity szybko kończy się niepowodzeniem, gdy wymagane pliki główne, takie jak `pnpm-lock.yaml`, zniknęły albo gdy `git status --short` pokazuje co najmniej 200 śledzonych usunięć. Zwykle oznacza to, że zdalny stan synchronizacji nie jest wiarygodną kopią PR-a; zatrzymaj tę maszynę i rozgrzej świeżą zamiast debugować niepowodzenie testu produktu. W przypadku PR-ów z celowo dużą liczbą usunięć ustaw `OPENCLAW_TESTBOX_ALLOW_MASS_DELETIONS=1` dla tego uruchomienia sanity.
|
||||
Kontrola poprawności kończy się szybko niepowodzeniem, gdy wymagane pliki główne, takie jak `pnpm-lock.yaml`, zniknęły albo gdy `git status --short` pokazuje co najmniej 200 śledzonych usunięć. Zwykle oznacza to, że stan zdalnej synchronizacji nie jest wiarygodną kopią PR-a; zatrzymaj tę instancję i przygotuj świeżą, zamiast debugować błąd testu produktu. W przypadku PR-ów z celowym dużym usunięciem ustaw `OPENCLAW_TESTBOX_ALLOW_MASS_DELETIONS=1` dla tego uruchomienia kontroli poprawności.
|
||||
|
||||
`pnpm testbox:run` kończy również lokalne wywołanie Blacksmith CLI, które pozostaje w fazie synchronizacji przez ponad pięć minut bez danych wyjściowych po synchronizacji. Ustaw `OPENCLAW_TESTBOX_SYNC_TIMEOUT_MS=0`, aby wyłączyć tę ochronę, albo użyj większej wartości w milisekundach dla nietypowo dużych lokalnych różnic.
|
||||
`pnpm testbox:run` kończy też lokalne wywołanie Blacksmith CLI, które pozostaje w fazie synchronizacji przez ponad pięć minut bez danych wyjściowych po synchronizacji. Ustaw `OPENCLAW_TESTBOX_SYNC_TIMEOUT_MS=0`, aby wyłączyć tę osłonę, albo użyj większej wartości w milisekundach dla nietypowo dużych lokalnych diffów.
|
||||
|
||||
Crabbox to należąca do repozytorium druga ścieżka zdalnej maszyny do potwierdzenia w Linuksie, gdy Blacksmith jest niedostępny albo gdy preferowana jest własna pojemność w chmurze. Rozgrzej maszynę, zhydratyzuj ją przez przepływ pracy projektu, a następnie uruchamiaj polecenia przez Crabbox CLI:
|
||||
Crabbox to należący do repozytorium wrapper zdalnej instancji do maintainerowej weryfikacji na Linuksie. Używaj go, gdy sprawdzenie jest zbyt szerokie dla lokalnej pętli edycji, gdy liczy się zgodność z CI albo gdy weryfikacja wymaga sekretów, Dockera, ścieżek pakietowych, instancji wielokrotnego użytku lub zdalnych logów. Normalnym backendem OpenClaw jest `blacksmith-testbox`; należąca do projektu pojemność AWS/Hetzner jest fallbackiem na awarie Blacksmith, problemy z limitami albo jawne testowanie należącej pojemności.
|
||||
|
||||
Przed pierwszym uruchomieniem sprawdź wrapper z katalogu głównego repozytorium:
|
||||
|
||||
```bash
|
||||
pnpm crabbox:warmup -- --idle-timeout 90m
|
||||
pnpm crabbox:hydrate -- --id <cbx_id>
|
||||
pnpm crabbox:run -- --id <cbx_id> --shell "OPENCLAW_TESTBOX=1 pnpm check:changed"
|
||||
pnpm crabbox:stop -- <cbx_id>
|
||||
pnpm crabbox:run -- --help | sed -n '1,120p'
|
||||
```
|
||||
|
||||
`.crabbox.yaml` jest właścicielem domyślnych ustawień dostawcy, synchronizacji i hydratyzacji GitHub Actions. Wyklucza lokalne `.git`, dzięki czemu zhydratyzowany checkout Actions zachowuje własne zdalne metadane Git zamiast synchronizować zdalne repozytoria i magazyny obiektów lokalne dla maintainera, oraz wyklucza lokalne artefakty uruchomieniowe/kompilacji, które nigdy nie powinny być przesyłane. `.github/workflows/crabbox-hydrate.yml` jest właścicielem checkoutu, konfiguracji Node/pnpm, pobrania `origin/main` oraz przekazania niesekretnego środowiska, z którego później korzystają polecenia `crabbox run --id <cbx_id>`.
|
||||
Wrapper repozytorium odrzuca przestarzały binarny Crabbox, który nie reklamuje `blacksmith-testbox`. Przekaż providera jawnie, mimo że `.crabbox.yaml` ma domyślne ustawienia chmury należącej do projektu.
|
||||
|
||||
Brama zmian:
|
||||
|
||||
```bash
|
||||
pnpm crabbox:run -- --provider blacksmith-testbox \
|
||||
--blacksmith-org openclaw \
|
||||
--blacksmith-workflow .github/workflows/ci-check-testbox.yml \
|
||||
--blacksmith-job check \
|
||||
--blacksmith-ref main \
|
||||
--idle-timeout 90m \
|
||||
--ttl 240m \
|
||||
--timing-json \
|
||||
--shell -- \
|
||||
"env CI=1 NODE_OPTIONS=--max-old-space-size=4096 OPENCLAW_TEST_PROJECTS_PARALLEL=6 OPENCLAW_VITEST_MAX_WORKERS=1 OPENCLAW_VITEST_NO_OUTPUT_TIMEOUT_MS=900000 pnpm check:changed"
|
||||
```
|
||||
|
||||
Ukierunkowione ponowne uruchomienie testu:
|
||||
|
||||
```bash
|
||||
pnpm crabbox:run -- --provider blacksmith-testbox \
|
||||
--blacksmith-org openclaw \
|
||||
--blacksmith-workflow .github/workflows/ci-check-testbox.yml \
|
||||
--blacksmith-job check \
|
||||
--blacksmith-ref main \
|
||||
--idle-timeout 90m \
|
||||
--ttl 240m \
|
||||
--timing-json \
|
||||
--shell -- \
|
||||
"env CI=1 NODE_OPTIONS=--max-old-space-size=4096 OPENCLAW_VITEST_MAX_WORKERS=1 OPENCLAW_VITEST_NO_OUTPUT_TIMEOUT_MS=900000 pnpm test <path-or-filter>"
|
||||
```
|
||||
|
||||
Pełny zestaw:
|
||||
|
||||
```bash
|
||||
pnpm crabbox:run -- --provider blacksmith-testbox \
|
||||
--blacksmith-org openclaw \
|
||||
--blacksmith-workflow .github/workflows/ci-check-testbox.yml \
|
||||
--blacksmith-job check \
|
||||
--blacksmith-ref main \
|
||||
--idle-timeout 90m \
|
||||
--ttl 240m \
|
||||
--timing-json \
|
||||
--shell -- \
|
||||
"env CI=1 NODE_OPTIONS=--max-old-space-size=4096 OPENCLAW_TEST_PROJECTS_PARALLEL=6 OPENCLAW_VITEST_MAX_WORKERS=1 OPENCLAW_VITEST_NO_OUTPUT_TIMEOUT_MS=900000 pnpm test"
|
||||
```
|
||||
|
||||
Przeczytaj końcowe podsumowanie JSON. Przydatne pola to `provider`, `leaseId`, `syncDelegated`, `exitCode`, `commandMs` i `totalMs`. Jednorazowe uruchomienia Crabbox oparte na Blacksmith powinny automatycznie zatrzymać Testbox; jeśli uruchomienie zostanie przerwane albo czyszczenie jest niejasne, sprawdź aktywne instancje i zatrzymaj tylko te, które zostały przez ciebie utworzone:
|
||||
|
||||
```bash
|
||||
blacksmith testbox list
|
||||
blacksmith testbox stop --id <tbx_id>
|
||||
```
|
||||
|
||||
Używaj ponownego wykorzystania tylko wtedy, gdy celowo potrzebujesz wielu poleceń na tej samej przygotowanej instancji:
|
||||
|
||||
```bash
|
||||
pnpm crabbox:run -- --provider blacksmith-testbox --id <tbx_id> --no-sync --timing-json --shell -- "pnpm test <path-or-filter>"
|
||||
pnpm crabbox:stop -- <tbx_id>
|
||||
```
|
||||
|
||||
Jeśli Crabbox jest uszkodzoną warstwą, ale sam Blacksmith działa, użyj bezpośredniego Blacksmith jako wąskiego fallbacku:
|
||||
|
||||
```bash
|
||||
blacksmith testbox warmup ci-check-testbox.yml --ref main --idle-timeout 90
|
||||
blacksmith testbox run --id <tbx_id> "env CI=1 NODE_OPTIONS=--max-old-space-size=4096 OPENCLAW_TEST_PROJECTS_PARALLEL=6 OPENCLAW_VITEST_MAX_WORKERS=1 OPENCLAW_VITEST_NO_OUTPUT_TIMEOUT_MS=900000 pnpm check:changed"
|
||||
blacksmith testbox stop --id <tbx_id>
|
||||
```
|
||||
|
||||
Eskaluj do należącej pojemności Crabbox tylko wtedy, gdy Blacksmith nie działa, jest ograniczony limitem, nie ma potrzebnego środowiska albo należąca pojemność jest jawnym celem:
|
||||
|
||||
```bash
|
||||
pnpm crabbox:warmup -- --provider aws --class beast --market on-demand --idle-timeout 90m
|
||||
pnpm crabbox:hydrate -- --id <cbx_id-or-slug>
|
||||
pnpm crabbox:run -- --id <cbx_id-or-slug> --timing-json --shell -- "env NODE_OPTIONS=--max-old-space-size=4096 OPENCLAW_TEST_PROJECTS_PARALLEL=6 OPENCLAW_VITEST_MAX_WORKERS=1 OPENCLAW_VITEST_NO_OUTPUT_TIMEOUT_MS=900000 pnpm check:changed"
|
||||
pnpm crabbox:stop -- <cbx_id-or-slug>
|
||||
```
|
||||
|
||||
`.crabbox.yaml` zawiera domyślne ustawienia providera, synchronizacji i hydratacji GitHub Actions dla ścieżek w chmurze należącej do projektu. Wyklucza lokalny `.git`, dzięki czemu przygotowany checkout Actions zachowuje własne zdalne metadane Git zamiast synchronizować lokalne maintainerowe zdalne repozytoria i magazyny obiektów, oraz wyklucza lokalne artefakty uruchomieniowe/budowania, które nigdy nie powinny być przesyłane. `.github/workflows/crabbox-hydrate.yml` odpowiada za checkout, konfigurację Node/pnpm, pobranie `origin/main` oraz przekazanie nieobjętego sekretami środowiska dla poleceń `crabbox run --id <cbx_id>` w chmurze należącej do projektu.
|
||||
|
||||
## Powiązane
|
||||
|
||||
- [Omówienie instalacji](/pl/install)
|
||||
- [Przegląd instalacji](/pl/install)
|
||||
- [Kanały deweloperskie](/pl/install/development-channels)
|
||||
|
||||
@ -1,36 +1,36 @@
|
||||
---
|
||||
read_when:
|
||||
- Chcesz zainstalować Pluginy Gateway lub zgodne pakiety albo nimi zarządzać
|
||||
- Chcesz debugować błędy ładowania Plugin
|
||||
- Chcesz zainstalować pluginy Gateway lub zgodne pakiety
|
||||
- Chcesz debugować niepowodzenia ładowania Plugin
|
||||
sidebarTitle: Plugins
|
||||
summary: Dokumentacja referencyjna CLI dla `openclaw plugins` (list, install, marketplace, uninstall, enable/disable, doctor)
|
||||
title: Pluginy
|
||||
x-i18n:
|
||||
generated_at: "2026-05-03T21:28:47Z"
|
||||
generated_at: "2026-05-04T07:02:56Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: d854d052b0a012a86f9c775775676a9a8fe8ae86b2c38a18118f1abf0732174c
|
||||
source_hash: 36ae7edb12986ead7e126f25e0761bf312b2644b35017181b674082105886776
|
||||
source_path: cli/plugins.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
Zarządzaj Pluginami Gateway, pakietami hooków i kompatybilnymi pakietami.
|
||||
Zarządzaj Pluginami Gateway, pakietami hooków i zgodnymi pakietami.
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="System Plugin" href="/pl/tools/plugin">
|
||||
Przewodnik użytkownika końcowego dotyczący instalowania, włączania i rozwiązywania problemów z pluginami.
|
||||
<Card title="System Pluginów" href="/pl/tools/plugin">
|
||||
Przewodnik dla użytkowników końcowych po instalowaniu, włączaniu i rozwiązywaniu problemów z Pluginami.
|
||||
</Card>
|
||||
<Card title="Zarządzanie pluginami" href="/pl/plugins/manage-plugins">
|
||||
<Card title="Zarządzanie Pluginami" href="/pl/plugins/manage-plugins">
|
||||
Szybkie przykłady instalowania, wyświetlania listy, aktualizowania, odinstalowywania i publikowania.
|
||||
</Card>
|
||||
<Card title="Pakiety pluginów" href="/pl/plugins/bundles">
|
||||
Model kompatybilności pakietów.
|
||||
<Card title="Pakiety Pluginów" href="/pl/plugins/bundles">
|
||||
Model zgodności pakietów.
|
||||
</Card>
|
||||
<Card title="Manifest Plugin" href="/pl/plugins/manifest">
|
||||
<Card title="Manifest Pluginu" href="/pl/plugins/manifest">
|
||||
Pola manifestu i schemat konfiguracji.
|
||||
</Card>
|
||||
<Card title="Bezpieczeństwo" href="/pl/gateway/security">
|
||||
Wzmacnianie bezpieczeństwa instalacji pluginów.
|
||||
Wzmacnianie bezpieczeństwa instalacji Pluginów.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
@ -62,14 +62,16 @@ openclaw plugins marketplace list <marketplace>
|
||||
openclaw plugins marketplace list <marketplace> --json
|
||||
```
|
||||
|
||||
Aby zbadać powolną instalację, inspekcję, odinstalowanie lub odświeżenie rejestru, uruchom polecenie z `OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1`. Ślad zapisuje czasy faz do stderr i pozostawia wyjście JSON możliwe do sparsowania. Zobacz [Debugowanie](/pl/help/debugging#plugin-lifecycle-trace).
|
||||
Aby zbadać powolną instalację, inspekcję, odinstalowanie lub odświeżenie rejestru, uruchom
|
||||
polecenie z `OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1`. Ślad zapisuje czasy faz
|
||||
do stderr i pozostawia dane wyjściowe JSON możliwe do sparsowania. Zobacz [Debugowanie](/pl/help/debugging#plugin-lifecycle-trace).
|
||||
|
||||
<Note>
|
||||
Dołączone pluginy są dostarczane z OpenClaw. Niektóre są domyślnie włączone (na przykład dołączeni dostawcy modeli, dołączeni dostawcy mowy i dołączony plugin przeglądarki); inne wymagają `plugins enable`.
|
||||
Wbudowane Pluginy są dostarczane z OpenClaw. Niektóre są domyślnie włączone (na przykład wbudowani dostawcy modeli, wbudowani dostawcy mowy i wbudowany Plugin przeglądarki); inne wymagają `plugins enable`.
|
||||
|
||||
Natywne pluginy OpenClaw muszą dostarczać `openclaw.plugin.json` z wbudowanym JSON Schema (`configSchema`, nawet jeśli jest pusty). Kompatybilne pakiety używają zamiast tego własnych manifestów pakietów.
|
||||
Natywne Pluginy OpenClaw muszą dostarczać `openclaw.plugin.json` z wbudowanym schematem JSON Schema (`configSchema`, nawet jeśli jest pusty). Zgodne pakiety używają zamiast tego własnych manifestów pakietów.
|
||||
|
||||
`plugins list` pokazuje `Format: openclaw` albo `Format: bundle`. Szczegółowe wyjście listy/informacji pokazuje także podtyp pakietu (`codex`, `claude` albo `cursor`) oraz wykryte możliwości pakietu.
|
||||
`plugins list` pokazuje `Format: openclaw` albo `Format: bundle`. Szczegółowe dane wyjściowe list/info pokazują również podtyp pakietu (`codex`, `claude` albo `cursor`) oraz wykryte możliwości pakietu.
|
||||
</Note>
|
||||
|
||||
### Instalacja
|
||||
@ -91,63 +93,71 @@ openclaw plugins install <plugin> --marketplace https://github.com/<owner>/<repo
|
||||
```
|
||||
|
||||
<Warning>
|
||||
Gołe nazwy pakietów są domyślnie instalowane z npm podczas przełączenia startowego. Użyj `clawhub:<package>` dla ClawHub. Traktuj instalacje pluginów jak uruchamianie kodu. Preferuj przypięte wersje.
|
||||
Gołe nazwy pakietów instalują z npm domyślnie podczas przejścia startowego. Użyj `clawhub:<package>` dla ClawHub. Traktuj instalacje Pluginów jak uruchamianie kodu. Preferuj przypięte wersje.
|
||||
</Warning>
|
||||
|
||||
`plugins search` odpytuje ClawHub o możliwe do zainstalowania pakiety pluginów i wypisuje nazwy pakietów gotowe do instalacji. Wyszukuje pakiety code-plugin i bundle-plugin, a nie Skills. Użyj `openclaw skills search` dla ClawHub Skills.
|
||||
`plugins search` odpytuje ClawHub o możliwe do zainstalowania pakiety Pluginów i wypisuje
|
||||
nazwy pakietów gotowe do instalacji. Wyszukuje pakiety code-plugin i bundle-plugin,
|
||||
a nie Skills. Użyj `openclaw skills search` dla Skills z ClawHub.
|
||||
|
||||
<Note>
|
||||
ClawHub jest główną powierzchnią dystrybucji i odkrywania dla większości pluginów. Npm pozostaje obsługiwaną ścieżką awaryjną i bezpośredniej instalacji. Pakiety pluginów `@openclaw/*` należące do OpenClaw są ponownie publikowane w npm; zobacz aktualną listę na [npmjs.com/org/openclaw](https://www.npmjs.com/org/openclaw) albo [inwentarz pluginów](/pl/plugins/plugin-inventory). Stabilne instalacje używają `latest`. Instalacje i aktualizacje z kanału beta preferują npm `beta` dist-tag, gdy ten tag jest dostępny, a następnie wracają do `latest`.
|
||||
ClawHub jest główną powierzchnią dystrybucji i odkrywania większości Pluginów. Npm
|
||||
pozostaje obsługiwaną ścieżką awaryjną i ścieżką bezpośredniej instalacji. Należące do OpenClaw
|
||||
pakiety Pluginów `@openclaw/*` są ponownie publikowane w npm; bieżącą listę znajdziesz
|
||||
na [npmjs.com/org/openclaw](https://www.npmjs.com/org/openclaw) albo w
|
||||
[inwentarzu Pluginów](/pl/plugins/plugin-inventory). Stabilne instalacje używają `latest`.
|
||||
Instalacje i aktualizacje w kanale beta preferują npm `beta` dist-tag, gdy ten tag
|
||||
jest dostępny, a następnie wracają do `latest`.
|
||||
</Note>
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Dołączenia konfiguracji i naprawa nieprawidłowej konfiguracji">
|
||||
Jeśli twoja sekcja `plugins` jest oparta na jednoplikowym `$include`, `plugins install/update/enable/disable/uninstall` zapisują zmiany do tego dołączonego pliku i pozostawiają `openclaw.json` bez zmian. Dołączenia katalogu głównego, tablice dołączeń i dołączenia z sąsiednimi nadpisaniami kończą się bezpiecznym błędem zamiast spłaszczania. Zobacz [Dołączenia konfiguracji](/pl/gateway/configuration), aby poznać obsługiwane kształty.
|
||||
<Accordion title="Dołączanie konfiguracji i naprawa nieprawidłowej konfiguracji">
|
||||
Jeśli sekcja `plugins` jest oparta na jednoplikowym `$include`, `plugins install/update/enable/disable/uninstall` zapisują do tego dołączonego pliku i pozostawiają `openclaw.json` bez zmian. Dołączenia główne, tablice dołączeń i dołączenia z równoległymi nadpisaniami kończą się zamknięciem zamiast spłaszczania. Zobacz [Dołączanie konfiguracji](/pl/gateway/configuration), aby poznać obsługiwane kształty.
|
||||
|
||||
Jeśli konfiguracja jest nieprawidłowa podczas instalacji, `plugins install` zwykle kończy się bezpiecznym błędem i każe najpierw uruchomić `openclaw doctor --fix`. Podczas startu Gateway i przeładowania na gorąco nieprawidłowa konfiguracja pluginu kończy się bezpiecznym błędem jak każda inna nieprawidłowa konfiguracja; `openclaw doctor --fix` może poddać nieprawidłowy wpis pluginu kwarantannie. Jedynym udokumentowanym wyjątkiem w czasie instalacji jest wąska ścieżka odzyskiwania dla dołączonych pluginów, które jawnie włączają `openclaw.install.allowInvalidConfigRecovery`.
|
||||
Jeśli konfiguracja jest nieprawidłowa podczas instalacji, `plugins install` zwykle kończy się zamknięciem i informuje, aby najpierw uruchomić `openclaw doctor --fix`. Podczas uruchamiania Gateway i gorącego przeładowania nieprawidłowa konfiguracja Pluginów kończy się zamknięciem jak każda inna nieprawidłowa konfiguracja; `openclaw doctor --fix` może poddać kwarantannie nieprawidłowy wpis Pluginu. Jedynym udokumentowanym wyjątkiem w czasie instalacji jest wąska ścieżka odzyskiwania wbudowanego Pluginu dla Pluginów, które jawnie włączają `openclaw.install.allowInvalidConfigRecovery`.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="--force i reinstalacja a aktualizacja">
|
||||
`--force` ponownie używa istniejącego celu instalacji i nadpisuje już zainstalowany plugin lub pakiet hooków w miejscu. Użyj tego, gdy celowo reinstalujesz ten sam identyfikator z nowej ścieżki lokalnej, archiwum, pakietu ClawHub albo artefaktu npm. Do rutynowych aktualizacji już śledzonego pluginu npm preferuj `openclaw plugins update <id-or-npm-spec>`.
|
||||
<Accordion title="--force i ponowna instalacja a aktualizacja">
|
||||
`--force` ponownie używa istniejącego miejsca docelowego instalacji i nadpisuje już zainstalowany Plugin albo pakiet hooków w miejscu. Używaj go, gdy celowo ponownie instalujesz ten sam id z nowej ścieżki lokalnej, archiwum, pakietu ClawHub albo artefaktu npm. Do rutynowych aktualizacji już śledzonego Pluginu npm preferuj `openclaw plugins update <id-or-npm-spec>`.
|
||||
|
||||
Jeśli uruchomisz `plugins install` dla identyfikatora pluginu, który jest już zainstalowany, OpenClaw zatrzyma się i wskaże `plugins update <id-or-npm-spec>` dla normalnej aktualizacji albo `plugins install <package> --force`, gdy rzeczywiście chcesz nadpisać bieżącą instalację z innego źródła.
|
||||
Jeśli uruchomisz `plugins install` dla id Pluginu, który jest już zainstalowany, OpenClaw zatrzyma się i wskaże `plugins update <id-or-npm-spec>` dla normalnej aktualizacji albo `plugins install <package> --force`, gdy naprawdę chcesz nadpisać bieżącą instalację z innego źródła.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Zakres --pin">
|
||||
`--pin` dotyczy tylko instalacji npm. Nie jest obsługiwane z instalacjami `git:`; użyj jawnego ref git, takiego jak `git:github.com/acme/plugin@v1.2.3`, gdy chcesz przypięte źródło. Nie jest obsługiwane z `--marketplace`, ponieważ instalacje z marketplace utrwalają metadane źródła marketplace zamiast specyfikacji npm.
|
||||
`--pin` dotyczy tylko instalacji npm. Nie jest obsługiwane z instalacjami `git:`; użyj jawnego odwołania git, takiego jak `git:github.com/acme/plugin@v1.2.3`, gdy chcesz przypiąć źródło. Nie jest obsługiwane z `--marketplace`, ponieważ instalacje z marketplace utrwalają metadane źródła marketplace zamiast specyfikacji npm.
|
||||
</Accordion>
|
||||
<Accordion title="--dangerously-force-unsafe-install">
|
||||
`--dangerously-force-unsafe-install` to opcja awaryjna dla fałszywych alarmów we wbudowanym skanerze niebezpiecznego kodu. Pozwala kontynuować instalację nawet wtedy, gdy wbudowany skaner zgłasza ustalenia `critical`, ale **nie** omija blokad zasad hooka `before_install` pluginu i **nie** omija niepowodzeń skanowania.
|
||||
`--dangerously-force-unsafe-install` to awaryjna opcja dla wyników fałszywie dodatnich we wbudowanym skanerze niebezpiecznego kodu. Pozwala kontynuować instalację nawet wtedy, gdy wbudowany skaner zgłasza ustalenia `critical`, ale **nie** omija blokad zasad hooka Pluginu `before_install` i **nie** omija niepowodzeń skanowania.
|
||||
|
||||
Ta flaga CLI dotyczy przepływów instalacji/aktualizacji pluginów. Instalacje zależności Skills obsługiwane przez Gateway używają odpowiadającego nadpisania żądania `dangerouslyForceUnsafeInstall`, podczas gdy `openclaw skills install` pozostaje osobnym przepływem pobierania/instalacji ClawHub Skills.
|
||||
Ta flaga CLI dotyczy przepływów instalacji/aktualizacji Pluginów. Instalacje zależności Skills wspierane przez Gateway używają pasującego nadpisania żądania `dangerouslyForceUnsafeInstall`, natomiast `openclaw skills install` pozostaje osobnym przepływem pobierania/instalacji Skills z ClawHub.
|
||||
|
||||
Jeśli plugin opublikowany przez ciebie w ClawHub jest blokowany przez skan rejestru, użyj kroków dla wydawcy w [ClawHub](/pl/tools/clawhub).
|
||||
Jeśli Plugin opublikowany przez Ciebie w ClawHub jest blokowany przez skan rejestru, użyj kroków dla wydawców w [ClawHub](/pl/tools/clawhub).
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Pakiety hooków i specyfikacje npm">
|
||||
`plugins install` jest także powierzchnią instalacji dla pakietów hooków, które ujawniają `openclaw.hooks` w `package.json`. Użyj `openclaw hooks` do filtrowanej widoczności hooków i włączania poszczególnych hooków, a nie do instalacji pakietów.
|
||||
`plugins install` jest także powierzchnią instalacji pakietów hooków, które udostępniają `openclaw.hooks` w `package.json`. Użyj `openclaw hooks` do filtrowanej widoczności hooków i włączania poszczególnych hooków, a nie do instalacji pakietów.
|
||||
|
||||
Specyfikacje npm są **tylko rejestrowe** (nazwa pakietu + opcjonalnie **dokładna wersja** albo **dist-tag**). Specyfikacje Git/URL/plikowe oraz zakresy semver są odrzucane. Instalacje zależności są uruchamiane lokalnie dla projektu z `--ignore-scripts` dla bezpieczeństwa, nawet gdy twoja powłoka ma globalne ustawienia instalacji npm.
|
||||
Specyfikacje npm są **tylko rejestrowe** (nazwa pakietu + opcjonalna **dokładna wersja** albo **dist-tag**). Specyfikacje Git/URL/file i zakresy semver są odrzucane. Instalacje zależności działają lokalnie dla projektu z `--ignore-scripts` dla bezpieczeństwa, nawet jeśli powłoka ma globalne ustawienia instalacji npm.
|
||||
|
||||
Użyj `npm:<package>`, gdy chcesz jawnie wymusić rozwiązywanie npm. Gołe specyfikacje pakietów także instalują bezpośrednio z npm podczas przełączenia startowego.
|
||||
Użyj `npm:<package>`, gdy chcesz jawnie wskazać rozwiązywanie npm. Gołe specyfikacje pakietów również instalują bezpośrednio z npm podczas przejścia startowego.
|
||||
|
||||
Gołe specyfikacje i `@latest` pozostają na stabilnej ścieżce. Jeśli npm rozwiąże którykolwiek z nich do wersji prerelease, OpenClaw zatrzyma się i poprosi o jawne przystąpienie za pomocą tagu prerelease, takiego jak `@beta`/`@rc`, albo dokładnej wersji prerelease, takiej jak `@1.2.3-beta.4`.
|
||||
Gołe specyfikacje i `@latest` pozostają na stabilnej ścieżce. Opatrzone datą wersje korekcyjne OpenClaw, takie jak `2026.5.3-1`, są dla tego sprawdzenia stabilnymi wydaniami. Jeśli npm rozwiąże którąkolwiek z nich do wersji przedpremierowej, OpenClaw zatrzyma się i poprosi o jawne włączenie za pomocą tagu przedpremierowego, takiego jak `@beta`/`@rc`, albo dokładnej wersji przedpremierowej, takiej jak `@1.2.3-beta.4`.
|
||||
|
||||
Jeśli goła specyfikacja instalacji pasuje do oficjalnego identyfikatora pluginu (na przykład `diffs`), OpenClaw instaluje wpis katalogu bezpośrednio. Aby zainstalować pakiet npm o tej samej nazwie, użyj jawnej specyfikacji z zakresem (na przykład `@scope/diffs`).
|
||||
Jeśli goła specyfikacja instalacji pasuje do oficjalnego id Pluginu (na przykład `diffs`), OpenClaw zainstaluje wpis katalogu bezpośrednio. Aby zainstalować pakiet npm o tej samej nazwie, użyj jawnej specyfikacji z zakresem (na przykład `@scope/diffs`).
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Repozytoria Git">
|
||||
Użyj `git:<repo>`, aby zainstalować bezpośrednio z repozytorium git. Obsługiwane formy obejmują `git:github.com/owner/repo`, `git:owner/repo`, pełne adresy URL klonowania `https://`, `ssh://`, `git://`, `file://` oraz `git@host:owner/repo.git`. Dodaj `@<ref>` albo `#<ref>`, aby przed instalacją pobrać gałąź, tag albo commit.
|
||||
Użyj `git:<repo>`, aby instalować bezpośrednio z repozytorium git. Obsługiwane formy obejmują `git:github.com/owner/repo`, `git:owner/repo`, pełne adresy URL klonowania `https://`, `ssh://`, `git://`, `file://` oraz `git@host:owner/repo.git`. Dodaj `@<ref>` albo `#<ref>`, aby przed instalacją przełączyć się na gałąź, tag albo commit.
|
||||
|
||||
Instalacje Git klonują do katalogu tymczasowego, pobierają żądany ref, gdy jest obecny, a następnie używają normalnego instalatora katalogu pluginu. Oznacza to, że walidacja manifestu, skanowanie niebezpiecznego kodu, praca instalacyjna menedżera pakietów i rekordy instalacji zachowują się jak instalacje npm. Zarejestrowane instalacje git obejmują źródłowy URL/ref oraz rozwiązany commit, aby `openclaw plugins update` mógł później ponownie rozwiązać źródło.
|
||||
Instalacje Git klonują do katalogu tymczasowego, przełączają się na żądane odwołanie, jeśli jest obecne, a następnie używają normalnego instalatora katalogu Pluginu. Oznacza to, że walidacja manifestu, skanowanie niebezpiecznego kodu, praca instalacji menedżera pakietów i rekordy instalacji zachowują się jak w instalacjach npm. Zarejestrowane instalacje Git obejmują źródłowy URL/ref oraz rozwiązany commit, aby `openclaw plugins update` mógł później ponownie rozwiązać źródło.
|
||||
|
||||
Po instalacji z git użyj `openclaw plugins inspect <id> --runtime --json`, aby zweryfikować rejestracje runtime, takie jak metody gateway i polecenia CLI. Jeśli plugin zarejestrował korzeń CLI za pomocą `api.registerCli`, wykonaj to polecenie bezpośrednio przez główne CLI OpenClaw, na przykład `openclaw demo-plugin ping`.
|
||||
Po instalacji z Git użyj `openclaw plugins inspect <id> --runtime --json`, aby zweryfikować rejestracje środowiska uruchomieniowego, takie jak metody gateway i polecenia CLI. Jeśli Plugin zarejestrował główny CLI za pomocą `api.registerCli`, wykonaj to polecenie bezpośrednio przez główny CLI OpenClaw, na przykład `openclaw demo-plugin ping`.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Archiwa">
|
||||
Obsługiwane archiwa: `.zip`, `.tgz`, `.tar.gz`, `.tar`. Archiwa natywnych pluginów OpenClaw muszą zawierać prawidłowy `openclaw.plugin.json` w wyodrębnionym katalogu głównym pluginu; archiwa zawierające tylko `package.json` są odrzucane, zanim OpenClaw zapisze rekordy instalacji.
|
||||
Obsługiwane archiwa: `.zip`, `.tgz`, `.tar.gz`, `.tar`. Archiwa natywnych Pluginów OpenClaw muszą zawierać prawidłowy `openclaw.plugin.json` w wyodrębnionym katalogu głównym Pluginu; archiwa zawierające tylko `package.json` są odrzucane, zanim OpenClaw zapisze rekordy instalacji.
|
||||
|
||||
Instalacje z marketplace Claude są także obsługiwane.
|
||||
Instalacje z marketplace Claude są również obsługiwane.
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
@ -159,25 +169,25 @@ openclaw plugins install clawhub:openclaw-codex-app-server
|
||||
openclaw plugins install clawhub:openclaw-codex-app-server@1.2.3
|
||||
```
|
||||
|
||||
Gołe, bezpieczne dla npm specyfikacje pluginów są domyślnie instalowane z npm podczas przełączenia startowego:
|
||||
Gołe, bezpieczne dla npm specyfikacje Pluginów instalują domyślnie z npm podczas przejścia startowego:
|
||||
|
||||
```bash
|
||||
openclaw plugins install openclaw-codex-app-server
|
||||
```
|
||||
|
||||
Użyj `npm:`, aby jawnie wymusić rozwiązywanie tylko przez npm:
|
||||
Użyj `npm:`, aby jawnie wskazać rozwiązywanie tylko przez npm:
|
||||
|
||||
```bash
|
||||
openclaw plugins install npm:openclaw-codex-app-server
|
||||
openclaw plugins install npm:@scope/plugin-name@1.0.1
|
||||
```
|
||||
|
||||
OpenClaw sprawdza deklarowaną kompatybilność API pluginu / minimalnego Gateway przed instalacją. Gdy wybrana wersja ClawHub publikuje artefakt ClawPack, OpenClaw pobiera wersjonowany npm-pack `.tgz`, weryfikuje nagłówek skrótu ClawHub i skrót artefaktu, a następnie instaluje go przez normalną ścieżkę archiwum. Starsze wersje ClawHub bez metadanych ClawPack nadal instalują się przez starszą ścieżkę weryfikacji archiwum pakietu. Zarejestrowane instalacje zachowują metadane źródła ClawHub, rodzaj artefaktu, integralność npm, npm shasum, nazwę tarballa i fakty skrótu ClawPack do późniejszych aktualizacji.
|
||||
Niewersjonowane instalacje ClawHub zachowują niewersjonowaną zarejestrowaną specyfikację, aby `openclaw plugins update` mogło śledzić nowsze wydania ClawHub; jawne selektory wersji lub tagu, takie jak `clawhub:pkg@1.2.3` i `clawhub:pkg@beta`, pozostają przypięte do tego selektora.
|
||||
OpenClaw sprawdza reklamowaną zgodność API Pluginu / minimalną zgodność Gateway przed instalacją. Gdy wybrana wersja ClawHub publikuje artefakt ClawPack, OpenClaw pobiera wersjonowany npm-pack `.tgz`, weryfikuje nagłówek skrótu ClawHub i skrót artefaktu, a następnie instaluje go przez normalną ścieżkę archiwum. Starsze wersje ClawHub bez metadanych ClawPack nadal instalują się przez starszą ścieżkę weryfikacji archiwum pakietu. Zarejestrowane instalacje zachowują metadane źródła ClawHub, rodzaj artefaktu, integralność npm, shasum npm, nazwę tarballa oraz fakty dotyczące skrótu ClawPack na potrzeby późniejszych aktualizacji.
|
||||
Niewersjonowane instalacje ClawHub zachowują niewersjonowaną zarejestrowaną specyfikację, aby `openclaw plugins update` mógł śledzić nowsze wydania ClawHub; jawne selektory wersji albo tagów, takie jak `clawhub:pkg@1.2.3` i `clawhub:pkg@beta`, pozostają przypięte do tego selektora.
|
||||
|
||||
#### Skrót marketplace
|
||||
|
||||
Użyj skrótu `plugin@marketplace`, gdy nazwa marketplace istnieje w lokalnej pamięci podręcznej rejestru Claude pod `~/.claude/plugins/known_marketplaces.json`:
|
||||
Użyj skrótu `plugin@marketplace`, gdy nazwa marketplace istnieje w lokalnej pamięci podręcznej rejestru Claude w `~/.claude/plugins/known_marketplaces.json`:
|
||||
|
||||
```bash
|
||||
openclaw plugins marketplace list <marketplace-name>
|
||||
@ -194,20 +204,20 @@ openclaw plugins install <plugin-name> --marketplace ./my-marketplace
|
||||
```
|
||||
|
||||
<Tabs>
|
||||
<Tab title="Źródła marketplace">
|
||||
- znana nazwa marketplace Claude z `~/.claude/plugins/known_marketplaces.json`
|
||||
<Tab title="Marketplace sources">
|
||||
- nazwa znanego marketplace Claude z `~/.claude/plugins/known_marketplaces.json`
|
||||
- lokalny katalog główny marketplace lub ścieżka `marketplace.json`
|
||||
- skrót repozytorium GitHub, taki jak `owner/repo`
|
||||
- URL repozytorium GitHub, taki jak `https://github.com/owner/repo`
|
||||
- URL git
|
||||
- adres URL repozytorium GitHub, taki jak `https://github.com/owner/repo`
|
||||
- adres URL git
|
||||
|
||||
</Tab>
|
||||
<Tab title="Reguły zdalnego marketplace">
|
||||
W przypadku zdalnych marketplace wczytywanych z GitHub lub git wpisy pluginów muszą pozostać wewnątrz sklonowanego repozytorium marketplace. OpenClaw akceptuje źródła ze ścieżkami względnymi z tego repozytorium i odrzuca źródła pluginów typu HTTP(S), ścieżka bezwzględna, git, GitHub oraz inne źródła niebędące ścieżkami ze zdalnych manifestów.
|
||||
<Tab title="Remote marketplace rules">
|
||||
W przypadku zdalnych marketplace ładowanych z GitHub lub git wpisy pluginów muszą pozostawać wewnątrz sklonowanego repozytorium marketplace. OpenClaw akceptuje źródła ze ścieżkami względnymi z tego repozytorium i odrzuca źródła pluginów HTTP(S), ze ścieżkami bezwzględnymi, git, GitHub oraz inne źródła niebędące ścieżkami ze zdalnych manifestów.
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
W przypadku lokalnych ścieżek i archiwów OpenClaw wykrywa automatycznie:
|
||||
W przypadku ścieżek lokalnych i archiwów OpenClaw automatycznie wykrywa:
|
||||
|
||||
- natywne pluginy OpenClaw (`openclaw.plugin.json`)
|
||||
- pakiety zgodne z Codex (`.codex-plugin/plugin.json`)
|
||||
@ -215,7 +225,7 @@ W przypadku lokalnych ścieżek i archiwów OpenClaw wykrywa automatycznie:
|
||||
- pakiety zgodne z Cursor (`.cursor-plugin/plugin.json`)
|
||||
|
||||
<Note>
|
||||
Zgodne pakiety instalują się w normalnym katalogu głównym pluginów i uczestniczą w tym samym przepływie list/info/enable/disable. Obecnie obsługiwane są Skills pakietów, Skills poleceń Claude, domyślne wartości `settings.json` Claude, domyślne wartości `.lsp.json` Claude / zadeklarowane w manifeście domyślne wartości `lspServers`, Skills poleceń Cursor oraz zgodne katalogi hooków Codex; inne wykryte możliwości pakietów są pokazywane w diagnostyce/informacjach, ale nie są jeszcze podłączone do wykonywania w czasie działania.
|
||||
Zgodne pakiety instalują się w standardowym katalogu głównym pluginów i uczestniczą w tym samym przepływie list/info/enable/disable. Obecnie obsługiwane są Skills pakietów, command-skills Claude, domyślne ustawienia Claude `settings.json`, domyślne ustawienia Claude `.lsp.json` / zadeklarowane w manifeście `lspServers`, command-skills Cursor oraz zgodne katalogi hooków Codex; inne wykryte możliwości pakietów są pokazywane w diagnostyce/informacjach, ale nie są jeszcze podłączone do wykonywania w runtime.
|
||||
</Note>
|
||||
|
||||
### Lista
|
||||
@ -234,38 +244,38 @@ openclaw plugins search <query> --json
|
||||
Pokaż tylko włączone pluginy.
|
||||
</ParamField>
|
||||
<ParamField path="--verbose" type="boolean">
|
||||
Przełącz z widoku tabeli na osobne wiersze szczegółów dla każdego pluginu z metadanymi źródła/pochodzenia/wersji/aktywacji.
|
||||
Przełącz z widoku tabeli na szczegółowe wiersze dla każdego pluginu z metadanymi źródła/pochodzenia/wersji/aktywacji.
|
||||
</ParamField>
|
||||
<ParamField path="--json" type="boolean">
|
||||
Czytelny maszynowo spis wraz z diagnostyką rejestru i stanem instalacji zależności pakietu.
|
||||
Inwentarz czytelny maszynowo oraz diagnostyka rejestru i stan instalacji zależności pakietów.
|
||||
</ParamField>
|
||||
|
||||
<Note>
|
||||
`plugins list` najpierw odczytuje utrwalony lokalny rejestr pluginów, z awaryjnym wariantem wyprowadzonym wyłącznie z manifestów, gdy rejestru brakuje lub jest nieprawidłowy. Jest przydatne do sprawdzania, czy plugin jest zainstalowany, włączony i widoczny dla planowania zimnego startu, ale nie jest sondą runtime już działającego procesu Gateway. Po zmianie kodu pluginu, włączenia, zasad hooków lub `plugins.load.paths` zrestartuj Gateway obsługujący kanał, zanim oczekujesz uruchomienia nowego kodu `register(api)` lub hooków. W przypadku wdrożeń zdalnych/kontenerowych upewnij się, że restartujesz rzeczywisty proces potomny `openclaw gateway run`, a nie tylko proces opakowujący.
|
||||
`plugins list` najpierw odczytuje utrwalony lokalny rejestr pluginów, z zapasowym wariantem wyprowadzanym tylko z manifestów, gdy rejestru brakuje lub jest nieprawidłowy. Jest to przydatne do sprawdzenia, czy plugin jest zainstalowany, włączony i widoczny dla planowania zimnego startu, ale nie jest to sondowanie na żywo runtime już działającego procesu Gateway. Po zmianie kodu pluginu, jego włączenia, polityki hooków lub `plugins.load.paths` zrestartuj Gateway obsługujący kanał, zanim oczekujesz uruchomienia nowego kodu `register(api)` lub hooków. W przypadku wdrożeń zdalnych/kontenerowych sprawdź, czy restartujesz rzeczywisty proces potomny `openclaw gateway run`, a nie tylko proces opakowujący.
|
||||
|
||||
`plugins list --json` zawiera `dependencyStatus` każdego pluginu z `package.json`
|
||||
`dependencies` i `optionalDependencies`. OpenClaw sprawdza, czy te nazwy pakietów
|
||||
są obecne w normalnej ścieżce wyszukiwania Node `node_modules` pluginu; nie
|
||||
są obecne wzdłuż standardowej ścieżki wyszukiwania Node `node_modules` pluginu; nie
|
||||
importuje kodu runtime pluginu, nie uruchamia menedżera pakietów ani nie naprawia
|
||||
brakujących zależności.
|
||||
</Note>
|
||||
|
||||
`plugins search` to zdalne wyszukiwanie w katalogu ClawHub. Nie sprawdza stanu
|
||||
lokalnego, nie modyfikuje konfiguracji, nie instaluje pakietów ani nie wczytuje
|
||||
kodu runtime pluginu. Wyniki wyszukiwania obejmują nazwę pakietu ClawHub,
|
||||
rodzinę, kanał, wersję, podsumowanie oraz wskazówkę instalacji, taką jak
|
||||
`openclaw plugins install clawhub:<package>`.
|
||||
lokalnego, nie modyfikuje konfiguracji, nie instaluje pakietów ani nie ładuje kodu
|
||||
runtime pluginu. Wyniki wyszukiwania obejmują nazwę pakietu ClawHub, rodzinę, kanał,
|
||||
wersję, podsumowanie oraz podpowiedź instalacji, taką jak `openclaw plugins install clawhub:<package>`.
|
||||
|
||||
W przypadku pracy nad wbudowanym pluginem wewnątrz spakowanego obrazu Docker zamontuj przez bind mount katalog źródłowy pluginu na odpowiadającej mu spakowanej ścieżce źródłowej, takiej jak
|
||||
`/app/extensions/synology-chat`. OpenClaw wykryje tę zamontowaną nakładkę źródeł
|
||||
Podczas pracy nad dołączonym pluginem wewnątrz spakowanego obrazu Docker zamontuj przez bind-mount katalog
|
||||
źródłowy pluginu na odpowiadającej mu spakowanej ścieżce źródłowej, takiej jak
|
||||
`/app/extensions/synology-chat`. OpenClaw wykryje tę zamontowaną nakładkę źródłową
|
||||
przed `/app/dist/extensions/synology-chat`; zwykły skopiowany katalog źródłowy
|
||||
pozostaje bezczynny, więc normalne spakowane instalacje nadal używają skompilowanego dist.
|
||||
pozostaje nieaktywny, więc normalne instalacje pakietowe nadal używają skompilowanego dist.
|
||||
|
||||
Do debugowania hooków runtime:
|
||||
|
||||
- `openclaw plugins inspect <id> --runtime --json` pokazuje zarejestrowane hooki i diagnostykę z przebiegu inspekcji z wczytaniem modułu. Inspekcja runtime nigdy nie instaluje zależności; użyj `openclaw doctor --fix`, aby wyczyścić starszy stan zależności lub zainstalować brakujące skonfigurowane pluginy możliwe do pobrania.
|
||||
- `openclaw gateway status --deep --require-rpc` potwierdza osiągalny Gateway, wskazówki usługi/procesu, ścieżkę konfiguracji i kondycję RPC.
|
||||
- Niewbudowane hooki konwersacyjne (`llm_input`, `llm_output`, `before_agent_finalize`, `agent_end`) wymagają `plugins.entries.<id>.hooks.allowConversationAccess=true`.
|
||||
- `openclaw plugins inspect <id> --runtime --json` pokazuje zarejestrowane hooki i diagnostykę z przebiegu inspekcji z załadowanym modułem. Inspekcja runtime nigdy nie instaluje zależności; użyj `openclaw doctor --fix`, aby wyczyścić starszy stan zależności lub zainstalować brakujące skonfigurowane pluginy do pobrania.
|
||||
- `openclaw gateway status --deep --require-rpc` potwierdza osiągalny Gateway, podpowiedzi dotyczące usługi/procesu, ścieżkę konfiguracji oraz kondycję RPC.
|
||||
- Niedołączone hooki konwersacji (`llm_input`, `llm_output`, `before_agent_finalize`, `agent_end`) wymagają `plugins.entries.<id>.hooks.allowConversationAccess=true`.
|
||||
|
||||
Użyj `--link`, aby uniknąć kopiowania lokalnego katalogu (dodaje do `plugins.load.paths`):
|
||||
|
||||
@ -274,16 +284,16 @@ openclaw plugins install -l ./my-plugin
|
||||
```
|
||||
|
||||
<Note>
|
||||
`--force` nie jest obsługiwane z `--link`, ponieważ instalacje linkowane ponownie używają ścieżki źródłowej zamiast kopiować na zarządzany cel instalacji.
|
||||
`--force` nie jest obsługiwane z `--link`, ponieważ instalacje linkowane ponownie używają ścieżki źródłowej zamiast kopiować do zarządzanego celu instalacji.
|
||||
|
||||
Użyj `--pin` przy instalacjach npm, aby zapisać rozwiązaną dokładną specyfikację (`name@version`) w zarządzanym indeksie pluginów, zachowując domyślne zachowanie bez przypięcia.
|
||||
</Note>
|
||||
|
||||
### Indeks pluginów
|
||||
|
||||
Metadane instalacji pluginów są stanem zarządzanym maszynowo, a nie konfiguracją użytkownika. Instalacje i aktualizacje zapisują je do `plugins/installs.json` w aktywnym katalogu stanu OpenClaw. Jego mapa najwyższego poziomu `installRecords` jest trwałym źródłem metadanych instalacji, w tym rekordów uszkodzonych lub brakujących manifestów pluginów. Tablica `plugins` to wyprowadzona z manifestów pamięć podręczna zimnego rejestru. Plik zawiera ostrzeżenie, aby go nie edytować, i jest używany przez `openclaw plugins update`, odinstalowanie, diagnostykę oraz zimny rejestr pluginów.
|
||||
Metadane instalacji pluginów to stan zarządzany maszynowo, a nie konfiguracja użytkownika. Instalacje i aktualizacje zapisują je do `plugins/installs.json` w aktywnym katalogu stanu OpenClaw. Mapa najwyższego poziomu `installRecords` jest trwałym źródłem metadanych instalacji, w tym rekordów uszkodzonych lub brakujących manifestów pluginów. Tablica `plugins` jest pamięcią podręczną zimnego rejestru wyprowadzoną z manifestów. Plik zawiera ostrzeżenie, aby go nie edytować, i jest używany przez `openclaw plugins update`, odinstalowanie, diagnostykę oraz zimny rejestr pluginów.
|
||||
|
||||
Gdy OpenClaw zobaczy w konfiguracji dostarczone starsze rekordy `plugins.installs`, przenosi je do indeksu pluginów i usuwa klucz konfiguracji; jeśli którykolwiek zapis się nie powiedzie, rekordy konfiguracji są zachowywane, aby metadane instalacji nie zostały utracone.
|
||||
Gdy OpenClaw widzi dostarczone starsze rekordy `plugins.installs` w konfiguracji, przenosi je do indeksu pluginów i usuwa klucz konfiguracji; jeśli którykolwiek zapis się nie powiedzie, rekordy konfiguracji są zachowywane, aby metadane instalacji nie zostały utracone.
|
||||
|
||||
### Odinstalowanie
|
||||
|
||||
@ -293,7 +303,7 @@ openclaw plugins uninstall <id> --dry-run
|
||||
openclaw plugins uninstall <id> --keep-files
|
||||
```
|
||||
|
||||
`uninstall` usuwa rekordy pluginów z `plugins.entries`, utrwalonego indeksu pluginów, wpisów listy zezwalania/odmowy pluginów oraz linkowanych wpisów `plugins.load.paths`, gdy ma to zastosowanie. O ile nie ustawiono `--keep-files`, odinstalowanie usuwa też śledzony zarządzany katalog instalacji, gdy znajduje się on wewnątrz katalogu głównego rozszerzeń pluginów OpenClaw. W przypadku pluginów Active Memory slot pamięci resetuje się do `memory-core`.
|
||||
`uninstall` usuwa rekordy pluginów z `plugins.entries`, utrwalonego indeksu pluginów, wpisów listy dozwolonych/odrzuconych pluginów oraz linkowanych wpisów `plugins.load.paths`, gdy ma to zastosowanie. O ile nie ustawiono `--keep-files`, odinstalowanie usuwa też śledzony zarządzany katalog instalacji, gdy znajduje się on wewnątrz katalogu głównego rozszerzeń pluginów OpenClaw. W przypadku pluginów Active Memory slot pamięci resetuje się do `memory-core`.
|
||||
|
||||
<Note>
|
||||
`--keep-config` jest obsługiwane jako przestarzały alias `--keep-files`.
|
||||
@ -309,29 +319,29 @@ openclaw plugins update @openclaw/voice-call
|
||||
openclaw plugins update openclaw-codex-app-server --dangerously-force-unsafe-install
|
||||
```
|
||||
|
||||
Aktualizacje dotyczą śledzonych instalacji pluginów w zarządzanym indeksie pluginów oraz śledzonych instalacji pakietów hooków w `hooks.internal.installs`.
|
||||
Aktualizacje dotyczą śledzonych instalacji pluginów w zarządzanym indeksie pluginów oraz śledzonych instalacji hook-packów w `hooks.internal.installs`.
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Rozwiązywanie identyfikatora pluginu względem specyfikacji npm">
|
||||
Gdy podasz identyfikator pluginu, OpenClaw ponownie użyje zapisanej specyfikacji instalacji dla tego pluginu. Oznacza to, że wcześniej zapisane tagi dystrybucji, takie jak `@beta`, oraz dokładnie przypięte wersje będą nadal używane przy późniejszych uruchomieniach `update <id>`.
|
||||
<Accordion title="Resolving plugin id vs npm spec">
|
||||
Gdy podasz id pluginu, OpenClaw ponownie użyje zapisanej specyfikacji instalacji tego pluginu. Oznacza to, że wcześniej zapisane dist-tags, takie jak `@beta`, oraz dokładnie przypięte wersje będą nadal używane przy późniejszych uruchomieniach `update <id>`.
|
||||
|
||||
W przypadku instalacji npm możesz też podać jawną specyfikację pakietu npm z tagiem dystrybucji lub dokładną wersją. OpenClaw rozwiązuje tę nazwę pakietu z powrotem do śledzonego rekordu pluginu, aktualizuje ten zainstalowany plugin i zapisuje nową specyfikację npm na potrzeby przyszłych aktualizacji opartych na identyfikatorze.
|
||||
W przypadku instalacji npm możesz także podać jawną specyfikację pakietu npm z dist-tag lub dokładną wersją. OpenClaw rozwiązuje tę nazwę pakietu z powrotem do śledzonego rekordu pluginu, aktualizuje ten zainstalowany plugin i zapisuje nową specyfikację npm dla przyszłych aktualizacji opartych na id.
|
||||
|
||||
Podanie nazwy pakietu npm bez wersji lub tagu również rozwiązuje ją z powrotem do śledzonego rekordu pluginu. Użyj tego, gdy plugin był przypięty do dokładnej wersji i chcesz przenieść go z powrotem na domyślną linię wydań rejestru.
|
||||
Podanie nazwy pakietu npm bez wersji lub tagu również rozwiązuje się z powrotem do śledzonego rekordu pluginu. Użyj tego, gdy plugin był przypięty do dokładnej wersji i chcesz przenieść go z powrotem na domyślną linię wydań rejestru.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Aktualizacje kanału beta">
|
||||
`openclaw plugins update` ponownie używa śledzonej specyfikacji pluginu, chyba że podasz nową specyfikację. `openclaw update` dodatkowo zna aktywny kanał aktualizacji OpenClaw: na kanale beta rekordy pluginów npm i ClawHub z domyślnej linii najpierw próbują `@beta`, a potem wracają do zapisanej domyślnej/najnowszej specyfikacji, jeśli nie istnieje wydanie beta pluginu. Dokładne wersje i jawne tagi pozostają przypięte do tego selektora.
|
||||
<Accordion title="Beta channel updates">
|
||||
`openclaw plugins update` ponownie używa śledzonej specyfikacji pluginu, chyba że podasz nową specyfikację. `openclaw update` dodatkowo zna aktywny kanał aktualizacji OpenClaw: na kanale beta rekordy pluginów npm i ClawHub z domyślnej linii próbują najpierw `@beta`, a następnie wracają do zapisanej specyfikacji default/latest, jeśli nie istnieje beta wydanie pluginu. Dokładne wersje i jawne tagi pozostają przypięte do tego selektora.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Kontrole wersji i dryf integralności">
|
||||
Przed aktualizacją npm na żywo OpenClaw sprawdza zainstalowaną wersję pakietu względem metadanych rejestru npm. Jeśli zainstalowana wersja i zapisana tożsamość artefaktu już odpowiadają rozwiązanemu celowi, aktualizacja jest pomijana bez pobierania, ponownej instalacji ani przepisywania `openclaw.json`.
|
||||
<Accordion title="Version checks and integrity drift">
|
||||
Przed aktualizacją npm na żywo OpenClaw sprawdza zainstalowaną wersję pakietu względem metadanych rejestru npm. Jeśli zainstalowana wersja i zapisana tożsamość artefaktu już pasują do rozwiązanego celu, aktualizacja jest pomijana bez pobierania, ponownej instalacji ani przepisywania `openclaw.json`.
|
||||
|
||||
Gdy istnieje zapisany skrót integralności, a skrót pobranego artefaktu się zmieni, OpenClaw traktuje to jako dryf artefaktu npm. Interaktywne polecenie `openclaw plugins update` wypisuje oczekiwane i rzeczywiste skróty oraz prosi o potwierdzenie przed kontynuacją. Nieinteraktywne pomocniki aktualizacji kończą się bezpiecznym błędem, chyba że wywołujący poda jawną politykę kontynuacji.
|
||||
Gdy istnieje zapisany hash integralności, a hash pobranego artefaktu się zmieni, OpenClaw traktuje to jako dryf artefaktu npm. Interaktywne polecenie `openclaw plugins update` wypisuje oczekiwane i rzeczywiste hashe oraz prosi o potwierdzenie przed kontynuacją. Nieinteraktywne pomocniki aktualizacji kończą się zamknięciem, chyba że wywołujący dostarczy jawną politykę kontynuacji.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="--dangerously-force-unsafe-install przy aktualizacji">
|
||||
`--dangerously-force-unsafe-install` jest również dostępne w `plugins update` jako awaryjne obejście fałszywych alarmów wbudowanego skanowania niebezpiecznego kodu podczas aktualizacji pluginów. Nadal nie omija blokad zasad `before_install` pluginu ani blokowania po niepowodzeniu skanowania, a dotyczy tylko aktualizacji pluginów, nie aktualizacji pakietów hooków.
|
||||
<Accordion title="--dangerously-force-unsafe-install on update">
|
||||
`--dangerously-force-unsafe-install` jest także dostępne w `plugins update` jako awaryjne obejście fałszywych alarmów wbudowanego skanowania dangerous-code podczas aktualizacji pluginów. Nadal nie omija blokad polityki `before_install` pluginu ani blokowania po niepowodzeniu skanowania i dotyczy tylko aktualizacji pluginów, a nie aktualizacji hook-packów.
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
@ -343,34 +353,34 @@ openclaw plugins inspect <id> --runtime
|
||||
openclaw plugins inspect <id> --json
|
||||
```
|
||||
|
||||
Inspekcja domyślnie pokazuje tożsamość, stan wczytania, źródło, możliwości manifestu, flagi zasad, diagnostykę, metadane instalacji, możliwości pakietu oraz każdą wykrytą obsługę serwera MCP lub LSP bez importowania kodu runtime pluginu. Dodaj `--runtime`, aby wczytać moduł pluginu i uwzględnić zarejestrowane hooki, narzędzia, polecenia, usługi, metody Gateway oraz trasy HTTP. Inspekcja runtime zgłasza brakujące zależności pluginów bezpośrednio; instalacje i naprawy pozostają w `openclaw plugins install`, `openclaw plugins update` i `openclaw doctor --fix`.
|
||||
Inspekcja pokazuje tożsamość, stan ładowania, źródło, możliwości manifestu, flagi polityk, diagnostykę, metadane instalacji, możliwości pakietu oraz wszelką wykrytą obsługę serwerów MCP lub LSP bez domyślnego importowania runtime pluginu. Dodaj `--runtime`, aby załadować moduł pluginu i uwzględnić zarejestrowane hooki, narzędzia, polecenia, usługi, metody Gateway oraz trasy HTTP. Inspekcja runtime zgłasza brakujące zależności pluginu bezpośrednio; instalacje i naprawy pozostają w `openclaw plugins install`, `openclaw plugins update` oraz `openclaw doctor --fix`.
|
||||
|
||||
Polecenia CLI należące do pluginów są instalowane jako główne grupy poleceń `openclaw`. Gdy `inspect --runtime` pokaże polecenie w `cliCommands`, uruchom je jako `openclaw <command> ...`; na przykład plugin rejestrujący `demo-git` można zweryfikować poleceniem `openclaw demo-git ping`.
|
||||
Polecenia CLI należące do pluginu są instalowane jako główne grupy poleceń `openclaw`. Gdy `inspect --runtime` pokaże polecenie pod `cliCommands`, uruchom je jako `openclaw <command> ...`; na przykład plugin rejestrujący `demo-git` można zweryfikować za pomocą `openclaw demo-git ping`.
|
||||
|
||||
Każdy plugin jest klasyfikowany według tego, co faktycznie rejestruje w runtime:
|
||||
|
||||
- **plain-capability** — jeden typ możliwości (np. plugin wyłącznie dostawcy)
|
||||
- **plain-capability** — jeden typ możliwości (np. plugin tylko dla dostawcy)
|
||||
- **hybrid-capability** — wiele typów możliwości (np. tekst + mowa + obrazy)
|
||||
- **hook-only** — tylko hooki, bez możliwości ani powierzchni
|
||||
- **non-capability** — narzędzia/polecenia/usługi, ale bez możliwości
|
||||
|
||||
Zobacz [kształty pluginów](/pl/plugins/architecture#plugin-shapes), aby dowiedzieć się więcej o modelu możliwości.
|
||||
Więcej informacji o modelu możliwości znajdziesz w [Kształty pluginów](/pl/plugins/architecture#plugin-shapes).
|
||||
|
||||
<Note>
|
||||
Flaga `--json` wypisuje czytelny maszynowo raport odpowiedni do skryptów i audytu. `inspect --all` renderuje tabelę dla całej floty z kolumnami kształtu, rodzajów możliwości, powiadomień o zgodności, możliwości pakietów i podsumowania hooków. `info` jest aliasem `inspect`.
|
||||
Flaga `--json` generuje raport czytelny maszynowo, odpowiedni do skryptowania i audytu. `inspect --all` renderuje tabelę dla całej floty z kolumnami kształtu, rodzajów możliwości, uwag o zgodności, możliwości pakietów i podsumowania hooków. `info` jest aliasem `inspect`.
|
||||
</Note>
|
||||
|
||||
### Diagnostyka
|
||||
### Doctor
|
||||
|
||||
```bash
|
||||
openclaw plugins doctor
|
||||
```
|
||||
|
||||
`doctor` zgłasza błędy wczytywania pluginów, diagnostykę manifestów/wykrywania i powiadomienia o zgodności. Gdy wszystko jest czyste, wypisuje `No plugin issues detected.`
|
||||
`doctor` raportuje błędy ładowania pluginów, diagnostykę manifestów/odkrywania oraz uwagi o zgodności. Gdy wszystko jest czyste, wypisuje `No plugin issues detected.`
|
||||
|
||||
Jeśli skonfigurowany plugin jest obecny na dysku, ale blokowany przez kontrole bezpieczeństwa ścieżek loadera, walidacja konfiguracji zachowuje wpis pluginu i zgłasza go jako `present but blocked`. Napraw wcześniejszą diagnostykę zablokowanego pluginu, taką jak własność ścieżki lub uprawnienia zapisu dla wszystkich, zamiast usuwać konfigurację `plugins.entries.<id>` lub `plugins.allow`.
|
||||
Jeśli skonfigurowany plugin jest obecny na dysku, ale zablokowany przez kontrole bezpieczeństwa ścieżek loadera, walidacja konfiguracji zachowuje wpis pluginu i zgłasza go jako `present but blocked`. Napraw poprzedzającą diagnostykę zablokowanego pluginu, taką jak własność ścieżki lub uprawnienia world-writable, zamiast usuwać konfigurację `plugins.entries.<id>` lub `plugins.allow`.
|
||||
|
||||
W przypadku niepowodzeń kształtu modułu, takich jak brakujące eksporty `register`/`activate`, uruchom ponownie z `OPENCLAW_PLUGIN_LOAD_DEBUG=1`, aby dołączyć zwięzłe podsumowanie kształtu eksportów w wyniku diagnostycznym.
|
||||
W przypadku awarii kształtu modułu, takich jak brak eksportów `register`/`activate`, uruchom ponownie z `OPENCLAW_PLUGIN_LOAD_DEBUG=1`, aby uwzględnić zwięzłe podsumowanie kształtu eksportów w wyjściu diagnostycznym.
|
||||
|
||||
### Rejestr
|
||||
|
||||
@ -380,12 +390,12 @@ openclaw plugins registry --refresh
|
||||
openclaw plugins registry --json
|
||||
```
|
||||
|
||||
Lokalny rejestr pluginów to utrwalony zimny model odczytu OpenClaw dla tożsamości zainstalowanych pluginów, włączenia, metadanych źródła i własności wkładu. Normalne uruchamianie, wyszukiwanie właściciela dostawcy, klasyfikacja konfiguracji kanału i spis pluginów mogą go odczytywać bez importowania modułów runtime pluginów.
|
||||
Lokalny rejestr pluginów jest utrwalonym zimnym modelem odczytu OpenClaw dla tożsamości zainstalowanych pluginów, ich włączenia, metadanych źródła oraz własności wkładów. Normalne uruchomienie, wyszukiwanie właściciela dostawcy, klasyfikacja konfiguracji kanału i inwentarz pluginów mogą go odczytać bez importowania modułów runtime pluginów.
|
||||
|
||||
Użyj `plugins registry`, aby sprawdzić, czy utrwalony rejestr jest obecny, aktualny czy nieaktualny. Użyj `--refresh`, aby odbudować go na podstawie utrwalonego indeksu Plugin, zasad konfiguracji oraz metadanych manifestu/pakietu. To ścieżka naprawy, a nie ścieżka aktywacji w czasie wykonywania.
|
||||
Użyj `plugins registry`, aby sprawdzić, czy utrwalony rejestr jest obecny, aktualny czy nieaktualny. Użyj `--refresh`, aby odbudować go z utrwalonego indeksu pluginów, zasad konfiguracji oraz metadanych manifestu/pakietu. To jest ścieżka naprawy, a nie ścieżka aktywacji w czasie wykonywania.
|
||||
|
||||
<Warning>
|
||||
`OPENCLAW_DISABLE_PERSISTED_PLUGIN_REGISTRY=1` to przestarzały awaryjny przełącznik zgodności na wypadek błędów odczytu rejestru. Preferuj `plugins registry --refresh` lub `openclaw doctor --fix`; awaryjne użycie zmiennej środowiskowej służy wyłącznie do odzyskiwania uruchamiania w sytuacjach awaryjnych podczas wdrażania migracji.
|
||||
`OPENCLAW_DISABLE_PERSISTED_PLUGIN_REGISTRY=1` to przestarzały awaryjny przełącznik zgodności na wypadek błędów odczytu rejestru. Preferuj `plugins registry --refresh` albo `openclaw doctor --fix`; awaryjny mechanizm zmiennej środowiskowej służy wyłącznie do awaryjnego odzyskiwania rozruchu podczas wdrażania migracji.
|
||||
</Warning>
|
||||
|
||||
### Marketplace
|
||||
@ -395,10 +405,10 @@ openclaw plugins marketplace list <source>
|
||||
openclaw plugins marketplace list <source> --json
|
||||
```
|
||||
|
||||
Lista Marketplace akceptuje lokalną ścieżkę marketplace, ścieżkę `marketplace.json`, skrót GitHub taki jak `owner/repo`, adres URL repozytorium GitHub albo adres URL git. `--json` wypisuje rozpoznaną etykietę źródła oraz sparsowany manifest marketplace i wpisy Plugin.
|
||||
Lista Marketplace akceptuje lokalną ścieżkę Marketplace, ścieżkę `marketplace.json`, skrót GitHub w formacie `owner/repo`, adres URL repozytorium GitHub albo adres URL git. `--json` wypisuje rozwiązaną etykietę źródła oraz sparsowany manifest Marketplace i wpisy pluginów.
|
||||
|
||||
## Powiązane
|
||||
|
||||
- [Tworzenie Plugin](/pl/plugins/building-plugins)
|
||||
- [Tworzenie pluginów](/pl/plugins/building-plugins)
|
||||
- [Dokumentacja CLI](/pl/cli)
|
||||
- [Społecznościowe Plugin](/pl/plugins/community)
|
||||
- [Pluginy społeczności](/pl/plugins/community)
|
||||
|
||||
@ -1,29 +1,24 @@
|
||||
---
|
||||
read_when:
|
||||
- Musisz zweryfikować routing przez proxy zarządzane przez operatora przed wdrożeniem
|
||||
- Musisz lokalnie przechwycić ruch transportowy OpenClaw w celu debugowania.
|
||||
- Chcesz sprawdzić sesje proxy debugowania, obiekty blob lub wbudowane ustawienia wstępne zapytań
|
||||
summary: Dokumentacja referencyjna CLI dla `openclaw proxy`, obejmująca walidację proxy zarządzanego przez operatora i inspektor przechwytywania lokalnego proxy debugowania
|
||||
- Przed wdrożeniem musisz zweryfikować routing proxy zarządzany przez operatora
|
||||
- Musisz lokalnie przechwycić ruch transportowy OpenClaw w celu debugowania
|
||||
- Chcesz przejrzeć sesje proxy debugowania, obiekty blob lub wbudowane presety zapytań
|
||||
summary: Dokumentacja referencyjna CLI dla `openclaw proxy`, obejmująca walidację proxy zarządzanego przez operatora oraz inspektor przechwytywania lokalnego proxy debugowania
|
||||
title: Serwer proxy
|
||||
x-i18n:
|
||||
generated_at: "2026-05-01T09:57:47Z"
|
||||
generated_at: "2026-05-04T07:02:57Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: e0820de861bfe1ec14e0c1624d636d6474b5fedd317e3ba1baaa61f6530e06e9
|
||||
source_hash: 9589bedafb97c31bcb6536a04307cd0c6550e1f307693bd4401785d79f34a1eb
|
||||
source_path: cli/proxy.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
# `openclaw proxy`
|
||||
|
||||
Sprawdź routing proxy zarządzany przez operatora albo uruchom lokalny jawny proxy debugowania
|
||||
i przeanalizuj przechwycony ruch.
|
||||
Zweryfikuj routing proxy zarządzany przez operatora albo uruchom lokalny jawny proxy debugowania i sprawdź przechwycony ruch.
|
||||
|
||||
Użyj `validate`, aby wstępnie sprawdzić forward proxy zarządzany przez operatora przed włączeniem
|
||||
routingu proxy OpenClaw. Pozostałe polecenia to narzędzia debugowania do
|
||||
diagnostyki na poziomie transportu: mogą uruchomić lokalny proxy, uruchomić polecenie podrzędne
|
||||
z włączonym przechwytywaniem, wyświetlić sesje przechwytywania, wyszukiwać typowe wzorce ruchu, odczytywać
|
||||
przechwycone bloby oraz usuwać lokalne dane przechwytywania.
|
||||
Użyj `validate`, aby sprawdzić zarządzany przez operatora forward proxy przed włączeniem routingu proxy OpenClaw. Pozostałe polecenia są narzędziami debugowania do badania na poziomie transportu: mogą uruchomić lokalny proxy, uruchomić polecenie podrzędne z włączonym przechwytywaniem, wyświetlić sesje przechwytywania, wyszukać typowe wzorce ruchu, odczytać przechwycone bloby i usunąć lokalne dane przechwytywania.
|
||||
|
||||
## Polecenia
|
||||
|
||||
@ -40,28 +35,21 @@ openclaw proxy purge
|
||||
|
||||
## Walidacja
|
||||
|
||||
`openclaw proxy validate` sprawdza efektywny adres URL proxy zarządzanego przez operatora z
|
||||
`--proxy-url`, konfiguracji albo `OPENCLAW_PROXY_URL`. Zgłasza problem z konfiguracją, gdy
|
||||
żaden proxy nie jest włączony i skonfigurowany; użyj `--proxy-url` do jednorazowego wstępnego sprawdzenia
|
||||
przed zmianą konfiguracji. Domyślnie weryfikuje, czy publiczne miejsce docelowe działa
|
||||
przez proxy oraz czy proxy nie może dotrzeć do tymczasowego kanarka loopback.
|
||||
Niestandardowe odrzucane miejsca docelowe działają w trybie fail-closed: odpowiedzi HTTP i niejednoznaczne
|
||||
awarie transportowe kończą się niepowodzeniem, chyba że możesz osobno zweryfikować specyficzny dla wdrożenia
|
||||
sygnał odmowy.
|
||||
`openclaw proxy validate` sprawdza efektywny adres URL proxy zarządzanego przez operatora z `--proxy-url`, konfiguracji albo `OPENCLAW_PROXY_URL`. Zgłasza problem z konfiguracją, gdy żaden proxy nie jest włączony ani skonfigurowany; użyj `--proxy-url` do jednorazowego sprawdzenia przed zmianą konfiguracji. Domyślnie weryfikuje, że publiczny cel jest osiągalny przez proxy oraz że proxy nie może połączyć się z tymczasowym celem kontrolnym loopback. Niestandardowe blokowane cele działają w trybie fail-closed: odpowiedzi HTTP i niejednoznaczne błędy transportu powodują niepowodzenie, chyba że możesz osobno zweryfikować specyficzny dla wdrożenia sygnał odmowy.
|
||||
|
||||
Opcje:
|
||||
|
||||
- `--json`: wypisz JSON czytelny maszynowo.
|
||||
- `--proxy-url <url>`: zweryfikuj ten adres URL proxy zamiast konfiguracji lub zmiennej środowiskowej.
|
||||
- `--allowed-url <url>`: dodaj miejsce docelowe, które powinno działać przez proxy. Powtórz, aby sprawdzić wiele miejsc docelowych.
|
||||
- `--denied-url <url>`: dodaj miejsce docelowe, które powinno być blokowane przez proxy. Powtórz, aby sprawdzić wiele miejsc docelowych.
|
||||
- `--timeout-ms <ms>`: limit czasu na żądanie w milisekundach.
|
||||
- `--proxy-url <url>`: zweryfikuj ten adres URL proxy zamiast konfiguracji lub env.
|
||||
- `--allowed-url <url>`: dodaj cel, który powinien działać przez proxy. Powtórz, aby sprawdzić wiele celów.
|
||||
- `--denied-url <url>`: dodaj cel, który powinien być blokowany przez proxy. Powtórz, aby sprawdzić wiele celów.
|
||||
- `--timeout-ms <ms>`: limit czasu dla pojedynczego żądania w milisekundach.
|
||||
|
||||
Zobacz [Proxy sieciowy](/pl/security/network-proxy), aby uzyskać wskazówki dotyczące wdrożenia i semantyki odmowy.
|
||||
Zobacz [Network Proxy](/pl/security/network-proxy), aby uzyskać wskazówki dotyczące wdrożenia i semantykę odmowy.
|
||||
|
||||
## Presety zapytań
|
||||
|
||||
`openclaw proxy query --preset <name>` akceptuje:
|
||||
`openclaw proxy query --preset <name>` przyjmuje:
|
||||
|
||||
- `double-sends`
|
||||
- `retry-storms`
|
||||
@ -74,11 +62,12 @@ Zobacz [Proxy sieciowy](/pl/security/network-proxy), aby uzyskać wskazówki dot
|
||||
|
||||
- `start` domyślnie używa `127.0.0.1`, chyba że ustawiono `--host`.
|
||||
- `run` uruchamia lokalny proxy debugowania, a następnie uruchamia polecenie po `--`.
|
||||
- `validate` kończy działanie z kodem 1, gdy konfiguracja proxy lub sprawdzenia miejsc docelowych nie powiodą się.
|
||||
- Przechwycone dane są lokalnymi danymi debugowania; użyj `openclaw proxy purge` po zakończeniu.
|
||||
- Bezpośrednie przekazywanie debug proxy do upstreamu otwiera gniazda upstream na potrzeby diagnostyki. Gdy aktywny jest tryb zarządzanego proxy OpenClaw, bezpośrednie przekazywanie żądań proxy i tuneli CONNECT jest domyślnie wyłączone; ustaw `OPENCLAW_DEBUG_PROXY_ALLOW_DIRECT_CONNECT_WITH_MANAGED_PROXY=1` tylko dla zatwierdzonej lokalnej diagnostyki.
|
||||
- `validate` kończy działanie z kodem 1, gdy konfiguracja proxy lub sprawdzanie celów zakończą się niepowodzeniem.
|
||||
- Przechwycone dane są lokalnymi danymi debugowania; po zakończeniu użyj `openclaw proxy purge`.
|
||||
|
||||
## Powiązane
|
||||
|
||||
- [Dokumentacja CLI](/pl/cli)
|
||||
- [Proxy sieciowy](/pl/security/network-proxy)
|
||||
- [Uwierzytelnianie zaufanego proxy](/pl/gateway/trusted-proxy-auth)
|
||||
- [Network Proxy](/pl/security/network-proxy)
|
||||
- [Zaufane uwierzytelnianie proxy](/pl/gateway/trusted-proxy-auth)
|
||||
|
||||
@ -1,13 +1,13 @@
|
||||
---
|
||||
read_when:
|
||||
- Chcesz wyświetlić zapisane sesje i zobaczyć ostatnią aktywność
|
||||
summary: Dokumentacja CLI dla `openclaw sessions` (lista zapisanych sesji + użycie)
|
||||
summary: Dokumentacja referencyjna CLI dla `openclaw sessions` (lista zapisanych sesji + użycie)
|
||||
title: Sesje
|
||||
x-i18n:
|
||||
generated_at: "2026-05-02T20:42:20Z"
|
||||
generated_at: "2026-05-04T07:02:41Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 5c9ec3ca55f7c5b6217b481e9da62f5416df73e69405a0dc15e77d2afeac723f
|
||||
source_hash: 8dc90344f40c53513bd6db3696bc709279155f26e7c3b6ea27e81a07a2f9f15e
|
||||
source_path: cli/sessions.md
|
||||
workflow: 16
|
||||
---
|
||||
@ -16,12 +16,18 @@ x-i18n:
|
||||
|
||||
Wyświetla listę zapisanych sesji konwersacji.
|
||||
|
||||
Listy sesji nie są sprawdzeniami dostępności kanałów/dostawców. Pokazują utrwalone
|
||||
Listy sesji nie są sprawdzeniem aktywności kanału/dostawcy. Pokazują utrwalone
|
||||
wiersze konwersacji z magazynów sesji. Cichy Discord, Slack, Telegram lub
|
||||
inny kanał może ponownie połączyć się pomyślnie bez utworzenia nowego wiersza sesji
|
||||
do czasu przetworzenia wiadomości. Użyj `openclaw channels status --probe`,
|
||||
`openclaw status --deep` albo `openclaw health --verbose`, gdy potrzebujesz działającej
|
||||
łączności kanału.
|
||||
inny kanał może ponownie połączyć się pomyślnie bez utworzenia nowego wiersza
|
||||
sesji, dopóki nie zostanie przetworzona wiadomość. Użyj `openclaw channels status --probe`,
|
||||
`openclaw status --deep` lub `openclaw health --verbose`, gdy potrzebujesz
|
||||
łączności kanału na żywo.
|
||||
|
||||
Odpowiedzi Gateway `sessions.list` są domyślnie ograniczone, aby duże, długo działające
|
||||
magazyny nie mogły zmonopolizować pętli zdarzeń Gateway. Przekaż jawny dodatni
|
||||
`limit` z klientów RPC, gdy potrzebne jest inne okno wyników; odpowiedzi
|
||||
zawierają `totalCount`, `limitApplied` i `hasMore`, gdy wywołujący muszą pokazać,
|
||||
że istnieje więcej wierszy.
|
||||
|
||||
```bash
|
||||
openclaw sessions
|
||||
@ -40,22 +46,23 @@ Wybór zakresu:
|
||||
- `--all-agents`: agreguj wszystkie skonfigurowane magazyny agentów
|
||||
- `--store <path>`: jawna ścieżka magazynu (nie można łączyć z `--agent` ani `--all-agents`)
|
||||
|
||||
Wyeksportuj pakiet trajektorii dla zapisanej sesji:
|
||||
Eksport pakietu trajektorii dla zapisanej sesji:
|
||||
|
||||
```bash
|
||||
openclaw sessions export-trajectory --session-key "agent:main:telegram:direct:123" --workspace .
|
||||
openclaw sessions export-trajectory --session-key "agent:main:telegram:direct:123" --output bug-123 --json
|
||||
```
|
||||
|
||||
To ścieżka polecenia używana przez polecenie ukośnikowe `/export-trajectory` po tym, jak
|
||||
właściciel zatwierdzi żądanie wykonania. Katalog wyjściowy jest zawsze rozwiązywany
|
||||
To jest ścieżka polecenia używana przez polecenie slash `/export-trajectory` po tym,
|
||||
jak właściciel zatwierdzi żądanie wykonania. Katalog wyjściowy jest zawsze rozwiązywany
|
||||
wewnątrz `.openclaw/trajectory-exports/` w wybranym obszarze roboczym.
|
||||
|
||||
`openclaw sessions --all-agents` odczytuje skonfigurowane magazyny agentów. Wykrywanie sesji
|
||||
Gateway i ACP jest szersze: obejmuje także magazyny dostępne tylko na dysku, znalezione pod
|
||||
domyślnym katalogiem głównym `agents/` albo szablonowym katalogiem głównym `session.store`. Te
|
||||
wykryte magazyny muszą rozwiązywać się do zwykłych plików `sessions.json` wewnątrz
|
||||
katalogu głównego agenta; dowiązania symboliczne i ścieżki poza katalogiem głównym są pomijane.
|
||||
`openclaw sessions --all-agents` odczytuje skonfigurowane magazyny agentów. Wykrywanie
|
||||
sesji Gateway i ACP jest szersze: obejmuje także magazyny istniejące tylko na dysku,
|
||||
znalezione w domyślnym katalogu głównym `agents/` lub w szablonowym katalogu głównym
|
||||
`session.store`. Te wykryte magazyny muszą wskazywać zwykłe pliki `sessions.json`
|
||||
wewnątrz katalogu głównego agenta; dowiązania symboliczne i ścieżki poza katalogiem
|
||||
głównym są pomijane.
|
||||
|
||||
Przykłady JSON:
|
||||
|
||||
@ -93,21 +100,21 @@ openclaw sessions cleanup --json
|
||||
|
||||
`openclaw sessions cleanup` używa ustawień `session.maintenance` z konfiguracji:
|
||||
|
||||
- Uwaga dotycząca zakresu: `openclaw sessions cleanup` utrzymuje magazyny sesji, transkrypcje i pliki towarzyszące trajektorii. Nie przycina logów uruchomień Cron (`cron/runs/<jobId>.jsonl`), którymi zarządzają `cron.runLog.maxBytes` i `cron.runLog.keepLines` w [konfiguracji Cron](/pl/automation/cron-jobs#configuration) oraz które opisano w [konserwacji Cron](/pl/automation/cron-jobs#maintenance).
|
||||
- Uwaga dotycząca zakresu: `openclaw sessions cleanup` konserwuje magazyny sesji, transkrypty i pliki towarzyszące trajektorii. Nie przycina dzienników uruchomień Cron (`cron/runs/<jobId>.jsonl`), którymi zarządzają `cron.runLog.maxBytes` i `cron.runLog.keepLines` w [konfiguracji Cron](/pl/automation/cron-jobs#configuration) i które są wyjaśnione w [konserwacji Cron](/pl/automation/cron-jobs#maintenance).
|
||||
|
||||
- `--dry-run`: podgląd, ile wpisów zostałoby przyciętych/ograniczonych bez zapisu.
|
||||
- `--dry-run`: podgląd, ile wpisów zostałoby przyciętych/ograniczonych bez zapisywania.
|
||||
- W trybie tekstowym dry-run wypisuje tabelę działań dla każdej sesji (`Action`, `Key`, `Age`, `Model`, `Flags`), aby było widać, co zostałoby zachowane, a co usunięte.
|
||||
- `--enforce`: zastosuj konserwację nawet wtedy, gdy `session.maintenance.mode` ma wartość `warn`.
|
||||
- `--fix-missing`: usuń wpisy, których pliki transkrypcji nie istnieją, nawet jeśli zwykle nie zostałyby jeszcze usunięte ze względu na wiek/liczbę.
|
||||
- `--active-key <key>`: chroń określony aktywny klucz przed usunięciem w ramach budżetu dyskowego. Trwałe zewnętrzne wskaźniki konwersacji, takie jak sesje grupowe i sesje czatu w zakresie wątku, są także zachowywane przez konserwację opartą na wieku/liczbie/budżecie dyskowym.
|
||||
- `--fix-missing`: usuń wpisy, których pliki transkryptów nie istnieją, nawet jeśli normalnie nie zostałyby jeszcze usunięte ze względu na wiek/liczbę.
|
||||
- `--active-key <key>`: chroń określony aktywny klucz przed usunięciem z powodu budżetu dysku. Trwałe zewnętrzne wskaźniki konwersacji, takie jak sesje grupowe i sesje czatu o zakresie wątku, także są zachowywane przez konserwację według wieku/liczby/budżetu dysku.
|
||||
- `--agent <id>`: uruchom czyszczenie dla jednego skonfigurowanego magazynu agenta.
|
||||
- `--all-agents`: uruchom czyszczenie dla wszystkich skonfigurowanych magazynów agentów.
|
||||
- `--store <path>`: uruchom na określonym pliku `sessions.json`.
|
||||
- `--json`: wypisz podsumowanie JSON. Z `--all-agents` dane wyjściowe obejmują jedno podsumowanie na magazyn.
|
||||
- `--store <path>`: uruchom względem konkretnego pliku `sessions.json`.
|
||||
- `--json`: wypisz podsumowanie JSON. Z `--all-agents` dane wyjściowe zawierają jedno podsumowanie na magazyn.
|
||||
|
||||
Gdy Gateway jest osiągalny, czyszczenie bez dry-run dla skonfigurowanych magazynów agentów jest
|
||||
wysyłane przez Gateway, aby korzystało z tego samego mechanizmu zapisu magazynu sesji co ruch
|
||||
w czasie działania. Użyj `--store <path>` do jawnej naprawy offline pliku magazynu.
|
||||
Gdy Gateway jest osiągalny, czyszczenie bez dry-run dla skonfigurowanych magazynów agentów
|
||||
jest wysyłane przez Gateway, aby współdzieliło ten sam zapisujący magazyn sesji co ruch
|
||||
w czasie działania. Użyj `--store <path>` do jawnej naprawy pliku magazynu offline.
|
||||
|
||||
`openclaw sessions cleanup --all-agents --dry-run --json`:
|
||||
|
||||
|
||||
@ -1,77 +1,77 @@
|
||||
---
|
||||
read_when:
|
||||
- Tworzenie lub uruchamianie wizualnej kontroli jakości na żywo dla błędów OpenClaw
|
||||
- Dodawanie weryfikacji przed i po dla żądania ściągnięcia
|
||||
- Dodawanie scenariuszy dla Discord, Slack, WhatsApp lub innych transportów na żywo
|
||||
- Debugowanie uruchomień QA wymagających zrzutów ekranu, automatyzacji przeglądarki lub dostępu przez VNC
|
||||
summary: Mantis to wizualny system kompleksowej weryfikacji służący do odtwarzania błędów OpenClaw na aktywnych transportach, rejestrowania materiału dowodowego sprzed i po poprawce oraz dołączania artefaktów do PR-ów.
|
||||
- Budowanie lub uruchamianie wizualnej kontroli jakości na żywo dla błędów OpenClaw
|
||||
- Dodawanie weryfikacji przed i po dla żądania scalenia
|
||||
- Dodawanie scenariuszy transportu na żywo dla usług Discord, Slack, WhatsApp lub innych
|
||||
- Debugowanie uruchomień QA wymagających zrzutów ekranu, automatyzacji przeglądarki lub dostępu VNC
|
||||
summary: Mantis to wizualny system kompleksowej weryfikacji służący do odtwarzania błędów OpenClaw w rzeczywistych transportach, rejestrowania materiału dowodowego przed zmianą i po niej oraz dołączania artefaktów do PR-ów.
|
||||
title: Modliszka
|
||||
x-i18n:
|
||||
generated_at: "2026-05-04T02:23:29Z"
|
||||
generated_at: "2026-05-04T07:03:10Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 5a86ab4bc876d1c53ada1c30580034165f028194a072f559eb54a898a369211d
|
||||
source_hash: 9d3f3fa3db111b1b5c85f8efeccd749fbd5885cee6b7843ca4c8d049acfd9164
|
||||
source_path: concepts/mantis.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
Mantis to system weryfikacji end-to-end OpenClaw dla błędów, które wymagają rzeczywistego
|
||||
runtime, rzeczywistego transportu i widocznego dowodu. Uruchamia scenariusz względem znanego
|
||||
błędnego ref, przechwytuje dowody, uruchamia ten sam scenariusz względem ref kandydata i
|
||||
publikuje porównanie jako artefakty, które maintainer może sprawdzić z PR lub
|
||||
Mantis to system pełnej weryfikacji OpenClaw dla błędów, które wymagają prawdziwego
|
||||
środowiska uruchomieniowego, prawdziwego transportu i widocznego dowodu. Uruchamia scenariusz na znanym
|
||||
złym odwołaniu, przechwytuje dowody, uruchamia ten sam scenariusz na odwołaniu kandydującym i
|
||||
publikuje porównanie jako artefakty, które opiekun może sprawdzić z poziomu PR lub
|
||||
z lokalnego polecenia.
|
||||
|
||||
Mantis zaczyna od Discord, ponieważ Discord daje nam wartościową pierwszą ścieżkę:
|
||||
rzeczywiste uwierzytelnianie bota, rzeczywiste kanały serwera, reakcje, wątki, natywne polecenia oraz
|
||||
Mantis zaczyna od Discord, ponieważ Discord daje nam pierwszy tor o dużej wartości:
|
||||
prawdziwe uwierzytelnianie bota, prawdziwe kanały gildii, reakcje, wątki, natywne polecenia i
|
||||
interfejs przeglądarki, w którym ludzie mogą wizualnie potwierdzić, co pokazał transport.
|
||||
|
||||
## Cele
|
||||
|
||||
- Odtworzyć błąd z issue lub PR w GitHub z takim samym kształtem transportu, jaki widzą
|
||||
- Odtworzyć błąd z issue lub PR w GitHub z tym samym kształtem transportu, który widzą
|
||||
użytkownicy.
|
||||
- Przechwycić artefakt **przed** na bazowym ref przed zastosowaniem poprawki.
|
||||
- Przechwycić artefakt **po** na ref kandydata po zastosowaniu poprawki.
|
||||
- Używać deterministycznej wyroczni zawsze, gdy to możliwe, takiej jak odczyt reakcji
|
||||
Discord REST lub sprawdzenie transkrypcji kanału.
|
||||
- Przechwytywać zrzuty ekranu, gdy błąd ma widoczną powierzchnię UI.
|
||||
- Przechwycić artefakt **przed** na odwołaniu bazowym przed zastosowaniem poprawki.
|
||||
- Przechwycić artefakt **po** na odwołaniu kandydującym po zastosowaniu poprawki.
|
||||
- Użyć deterministycznej wyroczni, gdy tylko to możliwe, takiej jak odczyt reakcji
|
||||
Discord przez REST lub sprawdzenie transkrypcji kanału.
|
||||
- Przechwytywać zrzuty ekranu, gdy błąd ma widoczną powierzchnię interfejsu użytkownika.
|
||||
- Uruchamiać lokalnie z CLI kontrolowanego przez agenta i zdalnie z GitHub.
|
||||
- Zachować wystarczająco dużo stanu maszyny do ratunkowego VNC, gdy logowanie, automatyzacja przeglądarki lub
|
||||
uwierzytelnianie providera się zablokuje.
|
||||
- Publikować zwięzły status na operatorskim kanale Discord, gdy uruchomienie jest zablokowane,
|
||||
wymaga ręcznej pomocy przez VNC albo się kończy.
|
||||
- Zachować wystarczający stan maszyny do ratunku przez VNC, gdy logowanie, automatyzacja przeglądarki lub
|
||||
uwierzytelnianie dostawcy utknie.
|
||||
- Publikować zwięzły status w kanale operatora Discord, gdy uruchomienie jest zablokowane,
|
||||
potrzebuje ręcznej pomocy przez VNC albo się kończy.
|
||||
|
||||
## Poza Zakresem
|
||||
## Cele poza zakresem
|
||||
|
||||
- Mantis nie zastępuje testów jednostkowych. Uruchomienie Mantis powinno zwykle stać się
|
||||
- Mantis nie zastępuje testów jednostkowych. Uruchomienie Mantis zwykle powinno stać się
|
||||
mniejszym testem regresji po zrozumieniu poprawki.
|
||||
- Mantis nie jest normalną szybką bramką CI. Jest wolniejszy, używa danych uwierzytelniających na żywo i
|
||||
jest zarezerwowany dla błędów, w których środowisko live ma znaczenie.
|
||||
- Mantis nie powinien wymagać człowieka w normalnej pracy. Ręczne VNC to ścieżka ratunkowa,
|
||||
nie ścieżka domyślna.
|
||||
- Mantis nie przechowuje surowych sekretów w artefaktach, logach, zrzutach ekranu, raportach Markdown
|
||||
ani komentarzach PR.
|
||||
- Mantis nie jest zwykłą szybką bramką CI. Jest wolniejszy, używa żywych poświadczeń i
|
||||
jest zarezerwowany dla błędów, w których znaczenie ma środowisko live.
|
||||
- Mantis nie powinien wymagać człowieka do normalnego działania. Ręczne VNC to ścieżka
|
||||
ratunkowa, a nie ścieżka domyślna.
|
||||
- Mantis nie przechowuje surowych sekretów w artefaktach, logach, zrzutach ekranu, raportach
|
||||
Markdown ani komentarzach PR.
|
||||
|
||||
## Własność
|
||||
|
||||
Mantis należy do stosu QA OpenClaw.
|
||||
|
||||
- OpenClaw jest właścicielem runtime scenariuszy, adapterów transportu, schematu dowodów i
|
||||
lokalnego CLI pod `pnpm openclaw qa mantis`.
|
||||
- QA Lab jest właścicielem części harnessu transportu live, helperów przechwytywania przeglądarki i
|
||||
writerów artefaktów.
|
||||
- Crabbox jest właścicielem rozgrzanych maszyn Linux, gdy potrzebna jest zdalna VM.
|
||||
- GitHub Actions jest właścicielem zdalnego punktu wejścia workflow i retencji artefaktów.
|
||||
- ClawSweeper jest właścicielem routingu komentarzy GitHub: parsowania poleceń maintainerów,
|
||||
dispatchowania workflow i publikowania końcowego komentarza PR.
|
||||
- OpenClaw odpowiada za środowisko uruchomieniowe scenariuszy, adaptery transportu, schemat dowodów i
|
||||
lokalne CLI pod `pnpm openclaw qa mantis`.
|
||||
- QA Lab odpowiada za elementy uprzęży transportu live, pomocniki przechwytywania przeglądarki i
|
||||
zapisujące artefakty.
|
||||
- Crabbox odpowiada za rozgrzane maszyny Linux, gdy potrzebna jest zdalna VM.
|
||||
- GitHub Actions odpowiada za zdalny punkt wejścia przepływu pracy i retencję artefaktów.
|
||||
- ClawSweeper odpowiada za kierowanie komentarzy GitHub: parsowanie poleceń opiekunów,
|
||||
uruchamianie przepływu pracy i publikowanie końcowego komentarza PR.
|
||||
- Agenci OpenClaw sterują Mantis przez Codex, gdy scenariusz wymaga agentowego przygotowania,
|
||||
debugowania lub raportowania stanu zablokowania.
|
||||
debugowania lub raportowania zablokowanego stanu.
|
||||
|
||||
Ta granica utrzymuje wiedzę o transporcie w OpenClaw, harmonogramowanie maszyn w
|
||||
Crabbox, a klej workflow maintainera w ClawSweeper.
|
||||
Ta granica utrzymuje wiedzę o transporcie w OpenClaw, planowanie maszyn w
|
||||
Crabbox, a klej przepływu pracy opiekunów w ClawSweeper.
|
||||
|
||||
## Kształt Polecenia
|
||||
## Kształt poleceń
|
||||
|
||||
Pierwsze lokalne polecenie weryfikuje bota Discord, serwer, kanał, wysłanie wiadomości,
|
||||
Pierwsze lokalne polecenie weryfikuje bota Discord, gildię, kanał, wysłanie wiadomości,
|
||||
wysłanie reakcji i ścieżkę artefaktów:
|
||||
|
||||
```bash
|
||||
@ -79,7 +79,7 @@ pnpm openclaw qa mantis discord-smoke \
|
||||
--output-dir .artifacts/qa-e2e/mantis/discord-smoke
|
||||
```
|
||||
|
||||
Lokalny runner przed i po akceptuje taki kształt:
|
||||
Lokalny runner przed i po przyjmuje taki kształt:
|
||||
|
||||
```bash
|
||||
pnpm openclaw qa mantis run \
|
||||
@ -90,10 +90,10 @@ pnpm openclaw qa mantis run \
|
||||
--output-dir .artifacts/qa-e2e/mantis/local-discord-status-reactions
|
||||
```
|
||||
|
||||
Runner tworzy odłączone worktree bazowe i kandydata pod katalogiem wyjściowym,
|
||||
instaluje zależności, buduje każdy ref, uruchamia scenariusz z
|
||||
Runner tworzy odłączone drzewa robocze bazowe i kandydujące pod katalogiem wyjściowym,
|
||||
instaluje zależności, buduje każde odwołanie, uruchamia scenariusz z
|
||||
`--allow-failures`, a następnie zapisuje `baseline/`, `candidate/`, `comparison.json`
|
||||
i `mantis-report.md`. Dla pierwszego scenariusza Discord udana weryfikacja
|
||||
i `mantis-report.md`. Dla pierwszego scenariusza Discord pomyślna weryfikacja
|
||||
oznacza, że status bazowy to `fail`, a status kandydata to `pass`.
|
||||
|
||||
Pierwszym prymitywem VM/przeglądarki jest desktop smoke:
|
||||
@ -103,46 +103,92 @@ pnpm openclaw qa mantis desktop-browser-smoke \
|
||||
--output-dir .artifacts/qa-e2e/mantis/desktop-browser
|
||||
```
|
||||
|
||||
Wynajmuje lub ponownie używa maszyny desktopowej Crabbox, uruchamia widoczną przeglądarkę wewnątrz
|
||||
sesji VNC, przechwytuje pulpit, pobiera artefakty z powrotem do lokalnego katalogu wyjściowego
|
||||
i zapisuje polecenie ponownego połączenia w raporcie. Polecenie domyślnie używa
|
||||
providera Hetzner, ponieważ jest pierwszym providerem z działającym pokryciem desktop/VNC
|
||||
w ścieżce Mantis. Nadpisz go za pomocą `--provider`, `--crabbox-bin` lub
|
||||
Dzierżawi lub ponownie wykorzystuje maszynę desktopową Crabbox, uruchamia widoczną przeglądarkę w
|
||||
sesji VNC, przechwytuje pulpit, pobiera artefakty z powrotem do lokalnego katalogu
|
||||
wyjściowego i zapisuje polecenie ponownego połączenia w raporcie. Polecenie domyślnie
|
||||
używa dostawcy Hetzner, ponieważ jest pierwszym dostawcą z działającym pokryciem desktop/VNC
|
||||
w torze Mantis. Nadpisz go za pomocą `--provider`, `--crabbox-bin` lub
|
||||
`OPENCLAW_MANTIS_CRABBOX_PROVIDER`, gdy uruchamiasz na innej flocie Crabbox.
|
||||
|
||||
Przydatne flagi desktop smoke:
|
||||
|
||||
- `--lease-id <cbx_...>` lub `OPENCLAW_MANTIS_CRABBOX_LEASE_ID` ponownie używa rozgrzanego desktopu.
|
||||
- `--lease-id <cbx_...>` lub `OPENCLAW_MANTIS_CRABBOX_LEASE_ID` ponownie wykorzystuje rozgrzany desktop.
|
||||
- `--browser-url <url>` zmienia stronę otwieraną w widocznej przeglądarce.
|
||||
- `--html-file <path>` renderuje lokalny dla repo artefakt HTML w widocznej przeglądarce. Mantis używa tego do przechwycenia wygenerowanej osi czasu reakcji statusu Discord przez rzeczywisty desktop Crabbox.
|
||||
- `--keep-lease` lub `OPENCLAW_MANTIS_KEEP_VM=1` pozostawia nowo utworzoną, przechodzącą dzierżawę otwartą do inspekcji VNC. Nieudane uruchomienia domyślnie zachowują dzierżawę, gdy została utworzona, aby operator mógł połączyć się ponownie.
|
||||
- `--class`, `--idle-timeout` i `--ttl` dostrajają rozmiar maszyny oraz czas życia dzierżawy.
|
||||
- `--html-file <path>` renderuje artefakt HTML lokalny dla repozytorium w widocznej przeglądarce. Mantis używa tego do przechwycenia wygenerowanej osi czasu reakcji statusu Discord przez prawdziwy desktop Crabbox.
|
||||
- `--keep-lease` lub `OPENCLAW_MANTIS_KEEP_VM=1` pozostawia nowo utworzoną pomyślną dzierżawę otwartą do inspekcji przez VNC. Nieudane uruchomienia domyślnie zachowują dzierżawę, gdy została utworzona, aby operator mógł połączyć się ponownie.
|
||||
- `--class`, `--idle-timeout` i `--ttl` dostrajają rozmiar maszyny i czas życia dzierżawy.
|
||||
|
||||
Workflow smoke GitHub to `Mantis Discord Smoke`. Workflow GitHub przed i po
|
||||
dla pierwszego rzeczywistego scenariusza to `Mantis Discord Status Reactions`. Akceptuje:
|
||||
Pierwszym pełnym prymitywem transportu desktopowego jest Slack desktop smoke:
|
||||
|
||||
- `baseline_ref`: ref, po którym oczekuje się odtworzenia zachowania tylko queued.
|
||||
- `candidate_ref`: ref, po którym oczekuje się pokazania `queued -> thinking -> done`.
|
||||
```bash
|
||||
pnpm openclaw qa mantis slack-desktop-smoke \
|
||||
--output-dir .artifacts/qa-e2e/mantis/slack-desktop \
|
||||
--gateway-setup \
|
||||
--scenario slack-canary \
|
||||
--keep-lease
|
||||
```
|
||||
|
||||
Checkoutuje ref harnessu workflow, buduje osobne worktree bazowe i kandydata,
|
||||
uruchamia `discord-status-reactions-tool-only` względem każdego worktree i
|
||||
przesyła `baseline/`, `candidate/`, `comparison.json` oraz `mantis-report.md` jako
|
||||
artefakty Actions. Renderuje też HTML osi czasu każdej ścieżki w desktopowej przeglądarce Crabbox
|
||||
i publikuje te zrzuty ekranu VNC obok deterministycznych PNG osi czasu w komentarzu PR.
|
||||
Workflow buduje CLI Crabbox z `openclaw/crabbox` main, aby móc użyć bieżących flag dzierżawy desktop/przeglądarka
|
||||
przed wydaniem następnej wersji binarnej Crabbox.
|
||||
Dzierżawi lub ponownie wykorzystuje maszynę desktopową Crabbox, synchronizuje bieżący checkout do
|
||||
VM, uruchamia `pnpm openclaw qa slack` wewnątrz tej VM, otwiera Slack Web w przeglądarce
|
||||
VNC, przechwytuje widoczny pulpit i kopiuje zarówno artefakty Slack QA, jak i
|
||||
zrzut ekranu VNC z powrotem do lokalnego katalogu wyjściowego. To pierwszy kształt Mantis,
|
||||
w którym SUT OpenClaw gateway i przeglądarka działają wewnątrz tej samej
|
||||
desktopowej VM Linux.
|
||||
|
||||
Możesz też wywołać uruchomienie status-reactions bezpośrednio z komentarza PR:
|
||||
Z `--gateway-setup` polecenie przygotowuje trwały jednorazowy katalog domowy OpenClaw
|
||||
w `$HOME/.openclaw-mantis/slack-openclaw`, poprawia konfigurację Slack Socket Mode
|
||||
dla wybranego kanału, uruchamia `openclaw gateway run` na porcie
|
||||
`38973` i utrzymuje Chrome działający w sesji VNC. To tryb „zostaw mi
|
||||
desktop Linux ze Slack i działającym claw”; tor Slack QA bot-do-bota
|
||||
pozostaje domyślny, gdy `--gateway-setup` zostanie pominięte.
|
||||
|
||||
Wymagane wejścia dla `--credential-source env`:
|
||||
|
||||
- `OPENCLAW_QA_SLACK_CHANNEL_ID`
|
||||
- `OPENCLAW_QA_SLACK_DRIVER_BOT_TOKEN`
|
||||
- `OPENCLAW_QA_SLACK_SUT_BOT_TOKEN`
|
||||
- `OPENCLAW_QA_SLACK_SUT_APP_TOKEN`
|
||||
- `OPENCLAW_LIVE_OPENAI_KEY` dla zdalnego toru modelu. Jeśli lokalnie ustawiono tylko
|
||||
`OPENAI_API_KEY`, Mantis mapuje je na `OPENCLAW_LIVE_OPENAI_KEY`
|
||||
przed wywołaniem Crabbox, aby przekazywanie zmiennych env `OPENCLAW_*` przez Crabbox mogło przenieść je
|
||||
do VM.
|
||||
|
||||
Przydatne flagi Slack desktop:
|
||||
|
||||
- `--lease-id <cbx_...>` uruchamia ponownie na maszynie, na której operator już zalogował się do Slack Web przez VNC.
|
||||
- `--gateway-setup` uruchamia trwały Slack gateway OpenClaw w VM zamiast tylko uruchamiać tor QA bot-do-bota.
|
||||
- `--slack-url <url>` otwiera określony URL Slack Web. Bez niego Mantis wyprowadza `https://app.slack.com/client/<team>/<channel>` ze Slack `auth.test`, gdy token bota SUT jest dostępny.
|
||||
- `--slack-channel-id <id>` kontroluje allowlist kanałów Slack używaną przez konfigurację gateway.
|
||||
- `OPENCLAW_MANTIS_SLACK_BROWSER_PROFILE_DIR` kontroluje trwały profil Chrome wewnątrz VM. Domyślna wartość to `$HOME/.config/openclaw-mantis/slack-chrome-profile`, więc ręczne logowanie do Slack Web przetrwa ponowne uruchomienia na tej samej dzierżawie.
|
||||
- `--credential-source convex --credential-role ci` używa współdzielonej puli poświadczeń zamiast bezpośrednich tokenów Slack z env.
|
||||
- `--provider-mode`, `--model`, `--alt-model` i `--fast` są przekazywane dalej do toru live Slack.
|
||||
|
||||
Przepływ pracy smoke GitHub to `Mantis Discord Smoke`. Przepływ pracy przed i po GitHub
|
||||
dla pierwszego prawdziwego scenariusza to `Mantis Discord Status Reactions`. Przyjmuje:
|
||||
|
||||
- `baseline_ref`: odwołanie, które ma odtworzyć zachowanie tylko z kolejką.
|
||||
- `candidate_ref`: odwołanie, które ma pokazać `queued -> thinking -> done`.
|
||||
|
||||
Sprawdza odwołanie uprzęży przepływu pracy, buduje osobne drzewa robocze bazowe i kandydujące,
|
||||
uruchamia `discord-status-reactions-tool-only` dla każdego drzewa roboczego i
|
||||
przesyła `baseline/`, `candidate/`, `comparison.json` i `mantis-report.md` jako
|
||||
artefakty Actions. Renderuje też HTML osi czasu każdego toru w przeglądarce desktopowej
|
||||
Crabbox i publikuje te zrzuty ekranu VNC obok deterministycznych
|
||||
PNG osi czasu w komentarzu PR. Przepływ pracy buduje CLI Crabbox z
|
||||
`openclaw/crabbox` main, aby mógł używać bieżących flag dzierżawy desktop/przeglądarki
|
||||
zanim zostanie wydane następne binarium Crabbox.
|
||||
|
||||
Możesz też uruchomić status-reactions bezpośrednio z komentarza PR:
|
||||
|
||||
```text
|
||||
@Mantis discord status reactions
|
||||
```
|
||||
|
||||
Wyzwalacz komentarzem jest celowo wąski. Uruchamia się tylko na komentarzach pull request
|
||||
Wyzwalacz komentarza jest celowo wąski. Działa tylko na komentarzach pull request
|
||||
od użytkowników z dostępem write, maintain lub admin i rozpoznaje tylko
|
||||
żądania reakcji statusu Discord. Domyślnie używa znanego błędnego ref bazowego
|
||||
oraz bieżącego SHA głowy PR jako kandydata. Maintainerzy mogą nadpisać dowolny
|
||||
ref:
|
||||
żądania reakcji statusu Discord. Domyślnie używa znanego złego odwołania bazowego
|
||||
i bieżącego SHA głowy PR jako kandydata. Opiekunowie mogą nadpisać dowolne
|
||||
odwołanie:
|
||||
|
||||
```text
|
||||
@Mantis discord status reactions baseline=origin/main candidate=HEAD
|
||||
@ -157,47 +203,47 @@ Przykłady poleceń ClawSweeper:
|
||||
|
||||
Pierwsze polecenie jest jawne i skoncentrowane na scenariuszu. Drugie może później mapować PR
|
||||
lub issue na zalecane scenariusze Mantis na podstawie etykiet, zmienionych plików i
|
||||
ustaleń z przeglądu ClawSweeper.
|
||||
ustaleń przeglądu ClawSweeper.
|
||||
|
||||
## Cykl Życia Uruchomienia
|
||||
## Cykl życia uruchomienia
|
||||
|
||||
1. Pozyskaj dane uwierzytelniające.
|
||||
2. Przydziel lub ponownie użyj VM.
|
||||
3. Przygotuj profil desktop/przeglądarka, gdy scenariusz wymaga dowodów UI.
|
||||
4. Przygotuj czysty checkout dla bazowego ref.
|
||||
1. Pozyskaj poświadczenia.
|
||||
2. Przydziel lub ponownie wykorzystaj VM.
|
||||
3. Przygotuj profil desktop/przeglądarki, gdy scenariusz wymaga dowodów UI.
|
||||
4. Przygotuj czysty checkout dla odwołania bazowego.
|
||||
5. Zainstaluj zależności i zbuduj tylko to, czego potrzebuje scenariusz.
|
||||
6. Uruchom podrzędny OpenClaw Gateway z izolowanym katalogiem stanu.
|
||||
7. Skonfiguruj transport live, providera, model i profil przeglądarki.
|
||||
7. Skonfiguruj transport live, dostawcę, model i profil przeglądarki.
|
||||
8. Uruchom scenariusz i przechwyć dowody bazowe.
|
||||
9. Zatrzymaj Gateway i zachowaj logi.
|
||||
10. Przygotuj ref kandydata w tej samej VM.
|
||||
9. Zatrzymaj gateway i zachowaj logi.
|
||||
10. Przygotuj odwołanie kandydujące w tej samej VM.
|
||||
11. Uruchom ten sam scenariusz i przechwyć dowody kandydata.
|
||||
12. Porównaj wyniki wyroczni i dowody wizualne.
|
||||
13. Zapisz Markdown, JSON, logi, zrzuty ekranu i opcjonalne artefakty śladu.
|
||||
14. Prześlij artefakty GitHub Actions.
|
||||
15. Opublikuj zwięzły komunikat statusu PR lub Discord.
|
||||
15. Opublikuj zwięzłą wiadomość statusu w PR lub Discord.
|
||||
|
||||
Scenariusz powinien móc nie powieść się na dwa różne sposoby:
|
||||
Scenariusz powinien móc zakończyć się niepowodzeniem na dwa różne sposoby:
|
||||
|
||||
- **Błąd odtworzony**: baza nie powiodła się w oczekiwany sposób.
|
||||
- **Awaria harnessu**: konfiguracja środowiska, dane uwierzytelniające, API Discord, przeglądarka lub
|
||||
provider zawiodły, zanim wyrocznia błędu była znacząca.
|
||||
- **Awaria uprzęży**: konfiguracja środowiska, poświadczenia, API Discord, przeglądarka lub
|
||||
dostawca zawiodły, zanim wyrocznia błędu miała znaczenie.
|
||||
|
||||
Raport końcowy musi rozdzielać te przypadki, aby maintainerzy nie mylili niestabilnego
|
||||
Raport końcowy musi rozdzielać te przypadki, aby opiekunowie nie mylili niestabilnego
|
||||
środowiska z zachowaniem produktu.
|
||||
|
||||
## MVP Discord
|
||||
|
||||
Pierwszy scenariusz powinien celować w reakcje statusu Discord w kanałach serwera, gdzie
|
||||
Pierwszy scenariusz powinien celować w reakcje statusu Discord w kanałach gildii, gdzie
|
||||
tryb dostarczania odpowiedzi źródłowej to `message_tool_only`.
|
||||
|
||||
Dlaczego to dobry zalążek Mantis:
|
||||
Dlaczego to dobry punkt startowy Mantis:
|
||||
|
||||
- Jest widoczny w Discord jako reakcje na wiadomości wyzwalającej.
|
||||
- Ma silną wyrocznię REST przez stan reakcji wiadomości Discord.
|
||||
- Ćwiczy rzeczywisty OpenClaw Gateway, uwierzytelnianie bota Discord, dispatch wiadomości,
|
||||
- Ćwiczy prawdziwy OpenClaw Gateway, uwierzytelnianie bota Discord, wysyłanie wiadomości,
|
||||
tryb dostarczania odpowiedzi źródłowej, stan reakcji statusu i cykl życia tury modelu.
|
||||
- Jest wystarczająco wąski, aby utrzymać pierwszą implementację uczciwą.
|
||||
- Jest wystarczająco wąski, aby utrzymać pierwszą implementację w ryzach.
|
||||
|
||||
Oczekiwany kształt scenariusza:
|
||||
|
||||
@ -230,12 +276,12 @@ evidence:
|
||||
screenshotMessageRow: true
|
||||
```
|
||||
|
||||
Dowody bazowe powinny pokazywać reakcję potwierdzenia queued, ale bez
|
||||
przejścia cyklu życia w trybie tylko narzędziowym. Dowody kandydata powinny pokazywać działające reakcje
|
||||
statusu cyklu życia, gdy `messages.statusReactions.enabled` jest jawnie
|
||||
true.
|
||||
Dowody bazowe powinny pokazywać reakcję potwierdzenia w kolejce, ale bez
|
||||
przejścia cyklu życia w trybie tylko narzędzia. Dowody kandydata powinny pokazywać działające reakcje statusu
|
||||
cyklu życia, gdy `messages.statusReactions.enabled` jest jawnie
|
||||
`true`.
|
||||
|
||||
Pierwszym wykonywalnym wycinkiem jest opcjonalny scenariusz Discord live QA:
|
||||
Pierwszy wykonywalny wycinek to opcjonalny scenariusz QA live Discord:
|
||||
|
||||
```bash
|
||||
pnpm openclaw qa discord \
|
||||
@ -248,31 +294,31 @@ pnpm openclaw qa discord \
|
||||
```
|
||||
|
||||
Konfiguruje SUT z zawsze włączoną obsługą serwera, `visibleReplies:
|
||||
"message_tool"`, `ackReaction: "👀"` i jawnymi reakcjami statusu. Wyrocznia
|
||||
polluje rzeczywistą wiadomość wyzwalającą Discord i oczekuje zaobserwowanej sekwencji
|
||||
"message_tool"`, `ackReaction: "👀"` oraz jawnymi reakcjami statusu. Oracle
|
||||
odpytuje rzeczywistą wiadomość wyzwalającą w Discord i oczekuje zaobserwowanej sekwencji
|
||||
`👀 -> 🤔 -> 👍`. Artefakty obejmują `discord-qa-reaction-timelines.json`,
|
||||
`discord-status-reactions-tool-only-timeline.html` oraz
|
||||
`discord-status-reactions-tool-only-timeline.png`.
|
||||
|
||||
## Istniejące Elementy QA
|
||||
## Istniejące elementy QA
|
||||
|
||||
Mantis powinien bazować na istniejącym prywatnym stosie QA zamiast zaczynać od
|
||||
zera:
|
||||
|
||||
- `pnpm openclaw qa discord` już uruchamia ścieżkę Discord live z botami drivera i
|
||||
- `pnpm openclaw qa discord` już uruchamia ścieżkę live Discord z botami sterownika i
|
||||
SUT.
|
||||
- Runner transportu live już zapisuje raporty i artefakty zaobserwowanych wiadomości
|
||||
pod `.artifacts/qa-e2e/`.
|
||||
- Dzierżawy danych uwierzytelniających Convex już zapewniają wyłączny dostęp do współdzielonych danych uwierzytelniających
|
||||
transportu live.
|
||||
- Usługa kontroli przeglądarki już obsługuje zrzuty ekranu, migawki,
|
||||
zarządzane profile headless i zdalne profile CDP.
|
||||
- QA Lab ma już UI debuggera i magistralę do testowania w kształcie transportu.
|
||||
w `.artifacts/qa-e2e/`.
|
||||
- Dzierżawy poświadczeń Convex już zapewniają wyłączny dostęp do współdzielonych poświadczeń
|
||||
transportów live.
|
||||
- Usługa sterowania przeglądarką już obsługuje zrzuty ekranu, snapshoty,
|
||||
zarządzane profile headless oraz zdalne profile CDP.
|
||||
- QA Lab ma już interfejs debuggera i magistralę do testowania w kształcie transportu.
|
||||
|
||||
Pierwsza implementacja Mantis może być cienkim runnerem przed/po nad tymi
|
||||
elementami, plus jedna warstwa dowodów wizualnych.
|
||||
Pierwsza implementacja Mantis może być cienkim runnerem przed/po na tych
|
||||
elementach plus jedna warstwa dowodów wizualnych.
|
||||
|
||||
## Model Dowodów
|
||||
## Model dowodów
|
||||
|
||||
Każde uruchomienie zapisuje stabilny katalog artefaktów:
|
||||
|
||||
@ -294,72 +340,77 @@ Każde uruchomienie zapisuje stabilny katalog artefaktów:
|
||||
run.log
|
||||
```
|
||||
|
||||
`mantis-summary.json` powinien być maszynowo odczytywalnym źródłem prawdy. Raport
|
||||
Markdown jest przeznaczony do komentarzy PR i przeglądu przez ludzi.
|
||||
`mantis-summary.json` powinien być czytelnym maszynowo źródłem prawdy. Raport
|
||||
Markdown służy do komentarzy PR i przeglądu przez człowieka.
|
||||
|
||||
Podsumowanie musi zawierać:
|
||||
|
||||
- przetestowane refy i SHA
|
||||
- transport i id scenariusza
|
||||
- providera maszyny oraz id maszyny lub id dzierżawy
|
||||
- źródło danych uwierzytelniających bez wartości sekretów
|
||||
- wynik bazowy
|
||||
- wynik kandydata
|
||||
- czy błąd odtworzono na bazie
|
||||
- czy kandydat go naprawił
|
||||
- testowane refy i SHA
|
||||
- transport i identyfikator scenariusza
|
||||
- dostawcę maszyny oraz identyfikator maszyny lub identyfikator dzierżawy
|
||||
- źródło poświadczeń bez wartości sekretów
|
||||
- wynik baseline
|
||||
- wynik candidate
|
||||
- czy błąd odtworzył się na baseline
|
||||
- czy candidate go naprawił
|
||||
- ścieżki artefaktów
|
||||
- oczyszczone problemy z konfiguracją lub sprzątaniem
|
||||
- oczyszczone problemy z konfiguracją lub czyszczeniem
|
||||
|
||||
Zrzuty ekranu są dowodami, nie sekretami. Nadal wymagają dyscypliny redakcji:
|
||||
mogą pojawić się prywatne nazwy kanałów, nazwy użytkowników lub treść wiadomości. Dla publicznych PR
|
||||
mogą pojawić się prywatne nazwy kanałów, nazwy użytkowników lub treść wiadomości. W przypadku publicznych PR
|
||||
preferuj linki do artefaktów GitHub Actions zamiast obrazów inline, dopóki historia redakcji
|
||||
nie będzie mocniejsza.
|
||||
|
||||
## Przeglądarka I VNC
|
||||
## Przeglądarka i VNC
|
||||
|
||||
Ścieżka przeglądarki ma dwa tryby:
|
||||
|
||||
- **Automatyzacja headless**: domyślna dla CI. Chrome działa z włączonym CDP, a
|
||||
Playwright lub kontrola przeglądarki OpenClaw przechwytuje zrzuty ekranu.
|
||||
- **Automatyzacja headless**: domyślna w CI. Chrome działa z włączonym CDP, a
|
||||
Playwright lub sterowanie przeglądarką OpenClaw przechwytuje zrzuty ekranu.
|
||||
- **Ratunkowe VNC**: włączone na tej samej VM, gdy logowanie, MFA, antyautomatyzacja Discord
|
||||
lub debugowanie wizualne wymaga człowieka.
|
||||
|
||||
Obserwacyjny profil przeglądarki Discord powinien być wystarczająco trwały, aby nie wymagać logowania przy każdym uruchomieniu, ale odizolowany od osobistego stanu przeglądarki. Profil należy do puli maszyn Mantis, a nie do laptopa dewelopera.
|
||||
Profil przeglądarki obserwatora Discord powinien być wystarczająco trwały, aby uniknąć
|
||||
logowania przy każdym uruchomieniu, ale odizolowany od osobistego stanu przeglądarki. Profil
|
||||
należy do puli maszyn Mantis, a nie do laptopa dewelopera.
|
||||
|
||||
Gdy Mantis się zablokuje, publikuje komunikat statusu na Discord zawierający:
|
||||
Gdy Mantis utknie, publikuje wiadomość statusu Discord z:
|
||||
|
||||
- identyfikator uruchomienia
|
||||
- identyfikator scenariusza
|
||||
- dostawcę maszyny
|
||||
- katalog artefaktów
|
||||
- instrukcje połączenia VNC lub noVNC, jeśli są dostępne
|
||||
- krótki opis blokady
|
||||
- identyfikatorem uruchomienia
|
||||
- identyfikatorem scenariusza
|
||||
- dostawcą maszyny
|
||||
- katalogiem artefaktów
|
||||
- instrukcjami połączenia VNC lub noVNC, jeśli są dostępne
|
||||
- krótkim tekstem blokera
|
||||
|
||||
Pierwsze prywatne wdrożenie może publikować te komunikaty w istniejącym kanale operatorów, a później przenieść je do dedykowanego kanału Mantis.
|
||||
Pierwsze prywatne wdrożenie może publikować te wiadomości w istniejącym kanale operatorów,
|
||||
a później przenieść je do dedykowanego kanału Mantis.
|
||||
|
||||
## Maszyny
|
||||
|
||||
Mantis powinien preferować AWS przez Crabbox w pierwszej zdalnej implementacji.
|
||||
Crabbox zapewnia nam rozgrzane maszyny, śledzenie dzierżaw, hydratację, logi, wyniki i
|
||||
sprzątanie. Jeśli pojemność AWS jest zbyt wolna lub niedostępna, dodaj dostawcę Hetzner
|
||||
Crabbox daje nam rozgrzane maszyny, śledzenie dzierżaw, hydratację, logi, wyniki i
|
||||
czyszczenie. Jeśli pojemność AWS jest zbyt wolna lub niedostępna, dodaj dostawcę Hetzner
|
||||
za tym samym interfejsem maszyny.
|
||||
|
||||
Minimalne wymagania VM:
|
||||
|
||||
- Linux z instalacją Chrome lub Chromium obsługującą środowisko graficzne
|
||||
- Linux z instalacją Chrome lub Chromium zdolną do pracy z pulpitem
|
||||
- dostęp CDP do automatyzacji przeglądarki
|
||||
- VNC lub noVNC do ratunkowego dostępu
|
||||
- VNC lub noVNC do ratowania
|
||||
- Node 22 i pnpm
|
||||
- checkout OpenClaw i pamięć podręczna zależności
|
||||
- pamięć podręczna przeglądarki Playwright Chromium, gdy używany jest Playwright
|
||||
- wystarczająco dużo CPU i pamięci dla jednego OpenClaw Gateway, jednej przeglądarki i jednego uruchomienia modelu
|
||||
- dostęp wychodzący do Discord, GitHub, dostawców modeli i brokera poświadczeń
|
||||
|
||||
VM nie powinna przechowywać długotrwałych surowych sekretów poza oczekiwanymi magazynami poświadczeń lub profili przeglądarki.
|
||||
VM nie powinna przechowywać długotrwałych surowych sekretów poza oczekiwanymi magazynami poświadczeń lub
|
||||
profilu przeglądarki.
|
||||
|
||||
## Sekrety
|
||||
|
||||
Sekrety znajdują się w sekretach organizacji lub repozytorium GitHub dla zdalnych uruchomień oraz w lokalnym pliku sekretów kontrolowanym przez operatora dla uruchomień lokalnych.
|
||||
Sekrety znajdują się w sekretach organizacji lub repozytorium GitHub dla uruchomień zdalnych oraz w
|
||||
lokalnym pliku sekretów kontrolowanym przez operatora dla uruchomień lokalnych.
|
||||
|
||||
Zalecane nazwy sekretów:
|
||||
|
||||
@ -369,34 +420,50 @@ Zalecane nazwy sekretów:
|
||||
- `OPENCLAW_QA_DISCORD_GUILD_ID`
|
||||
- `OPENCLAW_QA_DISCORD_CHANNEL_ID`
|
||||
- `OPENCLAW_QA_DISCORD_NOTIFY_CHANNEL_ID`
|
||||
- `OPENCLAW_QA_REDACT_PUBLIC_METADATA=1` dla publicznych przesyłek artefaktów GitHub
|
||||
- `OPENCLAW_QA_REDACT_PUBLIC_METADATA=1` dla publicznych uploadów artefaktów GitHub
|
||||
- `OPENCLAW_QA_CONVEX_SITE_URL`
|
||||
- `OPENCLAW_QA_CONVEX_SECRET_CI`
|
||||
- `OPENCLAW_QA_MANTIS_CRABBOX_COORDINATOR`
|
||||
- `OPENCLAW_QA_MANTIS_CRABBOX_COORDINATOR_TOKEN`
|
||||
|
||||
Długoterminowo pula poświadczeń Convex powinna pozostać standardowym źródłem poświadczeń transportu na żywo. Sekrety GitHub uruchamiają brokera i ścieżki awaryjne.
|
||||
Przepływ status-reactions Discord mapuje sekrety Mantis Crabbox z powrotem na zmienne środowiskowe `CRABBOX_COORDINATOR` i `CRABBOX_COORDINATOR_TOKEN`, których oczekuje CLI Crabbox. Zwykłe nazwy sekretów GitHub `CRABBOX_*` pozostają akceptowane jako awaryjna kompatybilność.
|
||||
W długim terminie pula poświadczeń Convex powinna pozostać normalnym źródłem poświadczeń
|
||||
transportów live. Sekrety GitHub bootstrapują brokera i ścieżki fallback.
|
||||
Workflow reakcji statusu Discord mapuje sekrety Mantis Crabbox z powrotem na
|
||||
zmienne środowiskowe `CRABBOX_COORDINATOR` i `CRABBOX_COORDINATOR_TOKEN`,
|
||||
których oczekuje CLI Crabbox. Zwykłe nazwy sekretów GitHub `CRABBOX_*` pozostają
|
||||
akceptowane jako fallback zgodności.
|
||||
|
||||
Runner Mantis nigdy nie może drukować:
|
||||
Runner Mantis nigdy nie może wypisywać:
|
||||
|
||||
- tokenów botów Discord
|
||||
- kluczy API dostawców
|
||||
- plików cookie przeglądarki
|
||||
- ciasteczek przeglądarki
|
||||
- zawartości profili uwierzytelniania
|
||||
- haseł VNC
|
||||
- surowych ładunków poświadczeń
|
||||
- surowych payloadów poświadczeń
|
||||
|
||||
Publiczne przesyłki artefaktów powinny również redagować metadane celu Discord, takie jak identyfikatory bota, gildii, kanału i wiadomości. Z tego powodu przepływ smoke GitHub włącza
|
||||
`OPENCLAW_QA_REDACT_PUBLIC_METADATA=1`.
|
||||
Publiczne uploady artefaktów powinny też redagować metadane celu Discord, takie jak identyfikatory botów,
|
||||
serwerów, kanałów i wiadomości. Workflow smoke GitHub włącza
|
||||
`OPENCLAW_QA_REDACT_PUBLIC_METADATA=1` z tego powodu.
|
||||
|
||||
Jeśli token zostanie przypadkowo wklejony do zgłoszenia, PR, czatu lub logu, obróć go po zapisaniu nowego sekretu.
|
||||
Jeśli token zostanie przypadkowo wklejony do zgłoszenia, PR, czatu lub logu, obróć go
|
||||
po zapisaniu nowego sekretu.
|
||||
|
||||
## Artefakty GitHub i komentarze PR
|
||||
|
||||
Przepływy Mantis powinny przesyłać pełny pakiet dowodowy jako krótkotrwały artefakt Actions. Gdy przepływ jest uruchamiany dla raportu błędu lub PR z poprawką, powinien również opublikować zredagowane zrzuty ekranu PNG do gałęzi `qa-artifacts` i wykonać upsert komentarza w tym błędzie lub PR z poprawką, z osadzonymi zrzutami ekranu przed/po. Nie publikuj głównego dowodu tylko w ogólnym PR automatyzacji QA. Surowe logi, zaobserwowane wiadomości i inne obszerne dowody pozostają w artefakcie Actions.
|
||||
Workflowy Mantis powinny uploadować pełny pakiet dowodów jako krótkotrwały artefakt Actions.
|
||||
Gdy workflow jest uruchamiany dla zgłoszenia błędu lub PR z poprawką, powinien również
|
||||
opublikować zredagowane zrzuty ekranu PNG do gałęzi `qa-artifacts` i upsertować
|
||||
komentarz do tego błędu lub PR z poprawką ze zrzutami ekranu przed/po inline. Nie publikuj
|
||||
głównego dowodu tylko w ogólnym PR automatyzacji QA. Surowe logi, zaobserwowane
|
||||
wiadomości i inne obszerne dowody pozostają w artefakcie Actions.
|
||||
|
||||
Przepływy produkcyjne powinny publikować te komentarze za pomocą Mantis GitHub App, a nie za pomocą `github-actions[bot]`. Przechowuj identyfikator aplikacji i klucz prywatny jako sekrety GitHub Actions `MANTIS_GITHUB_APP_ID` i `MANTIS_GITHUB_APP_PRIVATE_KEY`. Przepływ używa ukrytego znacznika jako klucza upsert, aktualizuje ten komentarz, gdy token może go edytować, i tworzy nowy komentarz należący do Mantis, gdy starszego znacznika należącego do bota nie można edytować.
|
||||
Workflowy produkcyjne powinny publikować te komentarze za pomocą Mantis GitHub App, a nie
|
||||
`github-actions[bot]`. Przechowuj identyfikator aplikacji i klucz prywatny jako sekrety GitHub Actions
|
||||
`MANTIS_GITHUB_APP_ID` i `MANTIS_GITHUB_APP_PRIVATE_KEY`.
|
||||
Workflow używa ukrytego znacznika jako klucza upsert, aktualizuje ten
|
||||
komentarz, gdy token może go edytować, i tworzy nowy komentarz należący do Mantis, gdy
|
||||
starszego znacznika należącego do bota nie można edytować.
|
||||
|
||||
Komentarz PR powinien być krótki i wizualny:
|
||||
|
||||
@ -418,15 +485,22 @@ candidate showed the expected queued -> thinking -> done sequence.
|
||||
| <inline screenshot> | <inline screenshot> |
|
||||
```
|
||||
|
||||
Gdy uruchomienie kończy się niepowodzeniem, ponieważ zawiódł harness, komentarz musi to powiedzieć, zamiast sugerować, że kandydat zawiódł.
|
||||
Gdy uruchomienie kończy się niepowodzeniem, ponieważ zawiodła uprząż, komentarz musi to powiedzieć
|
||||
zamiast sugerować, że candidate zawiódł.
|
||||
|
||||
## Notatki dotyczące prywatnego wdrożenia
|
||||
## Uwagi dotyczące prywatnego wdrożenia
|
||||
|
||||
Prywatne wdrożenie może już mieć aplikację Mantis Discord. Użyj ponownie tej aplikacji zamiast tworzyć kolejną, gdy ma odpowiednie uprawnienia bota i można ją bezpiecznie obrócić.
|
||||
Prywatne wdrożenie może już mieć aplikację Mantis Discord. Użyj ponownie tej
|
||||
aplikacji zamiast tworzyć kolejną aplikację, gdy ma właściwe uprawnienia bota
|
||||
i można ją bezpiecznie obrócić.
|
||||
|
||||
Ustaw początkowy kanał powiadomień operatora przez sekrety lub konfigurację wdrożenia. Może on najpierw wskazywać istniejący kanał maintainerów lub operacyjny, a następnie przejść do dedykowanego kanału Mantis, gdy taki powstanie.
|
||||
Ustaw początkowy kanał powiadomień operatora przez sekrety lub konfigurację wdrożenia.
|
||||
Może najpierw wskazywać istniejący kanał maintainerów lub operacyjny,
|
||||
a następnie przenieść się do dedykowanego kanału Mantis, gdy taki powstanie.
|
||||
|
||||
Nie umieszczaj w tym dokumencie identyfikatorów gildii, identyfikatorów kanałów, tokenów botów, plików cookie przeglądarki ani haseł VNC. Przechowuj je w sekretach GitHub, brokerze poświadczeń albo lokalnym magazynie sekretów operatora.
|
||||
Nie umieszczaj identyfikatorów serwerów, identyfikatorów kanałów, tokenów botów, ciasteczek przeglądarki ani haseł VNC
|
||||
w tym dokumencie. Przechowuj je w sekretach GitHub, brokerze poświadczeń lub
|
||||
lokalnym magazynie sekretów operatora.
|
||||
|
||||
## Dodawanie scenariusza
|
||||
|
||||
@ -435,43 +509,49 @@ Scenariusz Mantis powinien deklarować:
|
||||
- identyfikator i tytuł
|
||||
- transport
|
||||
- wymagane poświadczenia
|
||||
- politykę ref bazowego
|
||||
- politykę ref kandydata
|
||||
- politykę ref baseline
|
||||
- politykę ref candidate
|
||||
- łatkę konfiguracji OpenClaw
|
||||
- kroki konfiguracji
|
||||
- bodziec
|
||||
- oczekiwaną wyrocznię bazową
|
||||
- oczekiwaną wyrocznię kandydata
|
||||
- oczekiwany oracle baseline
|
||||
- oczekiwany oracle candidate
|
||||
- cele przechwytywania wizualnego
|
||||
- budżet czasu oczekiwania
|
||||
- kroki sprzątania
|
||||
- budżet timeoutu
|
||||
- kroki czyszczenia
|
||||
|
||||
Scenariusze powinny preferować małe, typowane wyrocznie:
|
||||
Scenariusze powinny preferować małe, typowane oracle:
|
||||
|
||||
- stan reakcji Discord dla błędów reakcji
|
||||
- referencje wiadomości Discord dla błędów wątkowania
|
||||
- ts wątku Slack i stan API reakcji dla błędów Slack
|
||||
- identyfikatory wiadomości e-mail i nagłówki dla błędów poczty e-mail
|
||||
- zrzuty ekranu przeglądarki, gdy UI jest jedynym wiarygodnym obserwowalnym elementem
|
||||
- odwołania do wiadomości Discord dla błędów wątkowania
|
||||
- thread ts Slack i stan API reakcji dla błędów Slack
|
||||
- identyfikatory wiadomości e-mail i nagłówki dla błędów e-mail
|
||||
- zrzuty ekranu przeglądarki, gdy UI jest jedynym wiarygodnym obserwowalnym sygnałem
|
||||
|
||||
Kontrole wizyjne powinny być addytywne. Jeśli API platformy może udowodnić błąd, użyj API jako wyroczni powodzenia/niepowodzenia i zachowaj zrzuty ekranu dla ludzkiej pewności.
|
||||
Sprawdzenia vision powinny być addytywne. Jeśli API platformy może udowodnić błąd, użyj
|
||||
API jako oracle pass/fail i zachowaj zrzuty ekranu dla pewności człowieka.
|
||||
|
||||
## Rozszerzenie dostawców
|
||||
|
||||
Po Discord ten sam runner może dodać:
|
||||
|
||||
- Slack: reakcje, wątki, wzmianki aplikacji, modale, przesyłanie plików.
|
||||
- E-mail: uwierzytelnianie Gmail i wątkowanie wiadomości przy użyciu `gog`, gdy konektory nie wystarczają.
|
||||
- WhatsApp: logowanie QR, ponowna identyfikacja, dostarczanie wiadomości, multimedia, reakcje.
|
||||
- Slack: reakcje, wątki, wzmianki aplikacji, modale, uploady plików.
|
||||
- E-mail: uwierzytelnianie Gmail i wątkowanie wiadomości za pomocą `gog`, gdy konektory nie są
|
||||
wystarczające.
|
||||
- WhatsApp: logowanie QR, ponowna identyfikacja, dostarczanie wiadomości, media, reakcje.
|
||||
- Telegram: bramkowanie wzmianek grupowych, polecenia, reakcje tam, gdzie są dostępne.
|
||||
- Matrix: szyfrowane pokoje, relacje wątku lub odpowiedzi, wznowienie po restarcie.
|
||||
- Matrix: szyfrowane pokoje, relacje wątków lub odpowiedzi, wznowienie po restarcie.
|
||||
|
||||
Każdy transport powinien mieć jeden tani scenariusz smoke oraz co najmniej jeden scenariusz klasy błędów. Kosztowne scenariusze wizualne powinny pozostać opcjonalne.
|
||||
Każdy transport powinien mieć jeden tani scenariusz smoke i co najmniej jeden scenariusz klasy błędów.
|
||||
Kosztowne scenariusze wizualne powinny pozostać opcjonalne.
|
||||
|
||||
## Otwarte pytania
|
||||
|
||||
- Który bot Discord powinien być sterownikiem, a który SUT, gdy istniejący bot Mantis jest używany ponownie?
|
||||
- Czy logowanie przeglądarki obserwatora powinno używać ludzkiego konta Discord, konta testowego, czy tylko dowodów REST czytelnych dla bota w pierwszej fazie?
|
||||
- Który bot Discord powinien być sterownikiem, a który SUT, gdy
|
||||
istniejący bot Mantis jest używany ponownie?
|
||||
- Czy logowanie przeglądarki obserwatora powinno używać ludzkiego konta Discord, konta testowego,
|
||||
czy tylko dowodów REST czytelnych dla botów w pierwszej fazie?
|
||||
- Jak długo GitHub powinien przechowywać artefakty Mantis dla PR?
|
||||
- Kiedy ClawSweeper powinien automatycznie rekomendować Mantis zamiast czekać na polecenie maintainera?
|
||||
- Czy zrzuty ekranu powinny być redagowane lub kadrowane przed przesłaniem dla publicznych PR?
|
||||
- Kiedy ClawSweeper powinien automatycznie rekomendować Mantis zamiast czekać na
|
||||
polecenie maintainera?
|
||||
- Czy zrzuty ekranu powinny być redagowane lub przycinane przed uploadem dla publicznych PR?
|
||||
|
||||
@ -1,20 +1,20 @@
|
||||
---
|
||||
read_when:
|
||||
- Wyjaśnienie, jak wiadomości przychodzące stają się odpowiedziami
|
||||
- Wyjaśnianie sesji, trybów kolejkowania lub zachowania przesyłania strumieniowego
|
||||
- Dokumentowanie widoczności rozumowania i implikacji dotyczących użycia
|
||||
- Doprecyzowanie sesji, trybów kolejkowania lub zachowania strumieniowania
|
||||
- Dokumentowanie widoczności rozumowania i konsekwencji użycia
|
||||
summary: Przepływ wiadomości, sesje, kolejkowanie i widoczność rozumowania
|
||||
title: Wiadomości
|
||||
x-i18n:
|
||||
generated_at: "2026-04-30T16:27:48Z"
|
||||
generated_at: "2026-05-04T07:03:30Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: fdeee014d92767a725501691fbe0c4ee6b631acc9a2ab5cbbcf321bfee9679b9
|
||||
source_hash: 15242e21fd17a9f2013561003e108d197204d834caf51bbcdc53ffb3f118b14f
|
||||
source_path: concepts/messages.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
OpenClaw obsługuje wiadomości przychodzące przez potok rozpoznawania sesji, kolejkowania, streamingu, wykonywania narzędzi i widoczności rozumowania. Ta strona mapuje ścieżkę od wiadomości przychodzącej do odpowiedzi.
|
||||
OpenClaw obsługuje wiadomości przychodzące przez potok obejmujący rozpoznawanie sesji, kolejkowanie, streaming, wykonywanie narzędzi i widoczność rozumowania. Ta strona pokazuje ścieżkę od wiadomości przychodzącej do odpowiedzi.
|
||||
|
||||
## Przepływ wiadomości (wysoki poziom)
|
||||
|
||||
@ -26,27 +26,27 @@ Inbound message
|
||||
-> outbound replies (channel limits + chunking)
|
||||
```
|
||||
|
||||
Kluczowe ustawienia znajdują się w konfiguracji:
|
||||
Kluczowe pokrętła znajdują się w konfiguracji:
|
||||
|
||||
- `messages.*` dla prefiksów, kolejkowania i zachowania grup.
|
||||
- `agents.defaults.*` dla domyślnych ustawień streamingu blokowego i dzielenia na fragmenty.
|
||||
- Nadpisania kanałów (`channels.whatsapp.*`, `channels.telegram.*` itd.) dla limitów i przełączników streamingu.
|
||||
|
||||
Zobacz [Konfiguracja](/pl/gateway/configuration), aby poznać pełny schemat.
|
||||
Pełny schemat znajdziesz w [Konfiguracji](/pl/gateway/configuration).
|
||||
|
||||
## Deduplikacja przychodzących wiadomości
|
||||
|
||||
Kanały mogą ponownie dostarczyć tę samą wiadomość po ponownym połączeniu. OpenClaw utrzymuje
|
||||
krótkotrwałą pamięć podręczną kluczowaną według kanału/konta/peera/sesji/identyfikatora wiadomości, dzięki czemu zduplikowane
|
||||
dostarczenia nie uruchamiają kolejnego przebiegu agenta.
|
||||
krótkotrwały cache z kluczem opartym o kanał/konto/rozmówcę/sesję/identyfikator wiadomości, aby zduplikowane
|
||||
dostarczenia nie uruchamiały kolejnego przebiegu agenta.
|
||||
|
||||
## Debouncing przychodzących wiadomości
|
||||
|
||||
Szybkie kolejne wiadomości od **tego samego nadawcy** można zgrupować w jedną
|
||||
turę agenta za pomocą `messages.inbound`. Debouncing jest ograniczony do kanału + konwersacji
|
||||
i używa najnowszej wiadomości do wątkowania odpowiedzi/identyfikatorów.
|
||||
Szybkie kolejne wiadomości od **tego samego nadawcy** mogą zostać zebrane w jedną
|
||||
turę agenta przez `messages.inbound`. Debouncing jest zakresowany na kanał + konwersację
|
||||
i używa najnowszej wiadomości do wątkowania/identyfikatorów odpowiedzi.
|
||||
|
||||
Konfiguracja (globalna wartość domyślna + nadpisania per kanał):
|
||||
Konfiguracja (globalna wartość domyślna + nadpisania dla kanałów):
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -65,96 +65,96 @@ Konfiguracja (globalna wartość domyślna + nadpisania per kanał):
|
||||
|
||||
Uwagi:
|
||||
|
||||
- Debounce stosuje się do wiadomości **tylko tekstowych**; multimedia/załączniki opróżniają bufor natychmiast.
|
||||
- Komendy sterujące omijają debouncing, aby pozostawały samodzielne — **z wyjątkiem** sytuacji, gdy kanał jawnie włącza scalanie DM od tego samego nadawcy (np. [BlueBubbles `coalesceSameSenderDms`](/pl/channels/bluebubbles#coalescing-split-send-dms-command--url-in-one-composition)), gdzie komendy DM czekają w oknie debounce, aby ładunek wysłany w częściach mógł dołączyć do tej samej tury agenta.
|
||||
- Debounce dotyczy wiadomości **tylko tekstowych**; media/załączniki są wysyłane natychmiast.
|
||||
- Polecenia sterujące omijają debouncing, aby pozostały samodzielne — **z wyjątkiem** sytuacji, gdy kanał jawnie włącza łączenie DM od tego samego nadawcy (np. [BlueBubbles `coalesceSameSenderDms`](/pl/channels/bluebubbles#coalescing-split-send-dms-command--url-in-one-composition)), gdzie polecenia DM czekają w oknie debounce, aby podzielony payload wysyłki mógł dołączyć do tej samej tury agenta.
|
||||
|
||||
## Sesje i urządzenia
|
||||
|
||||
Sesje należą do gatewaya, a nie do klientów.
|
||||
Sesje są własnością Gateway, a nie klientów.
|
||||
|
||||
- Czaty bezpośrednie zwijają się do głównego klucza sesji agenta.
|
||||
- Czaty bezpośrednie są zwijane do głównego klucza sesji agenta.
|
||||
- Grupy/kanały otrzymują własne klucze sesji.
|
||||
- Magazyn sesji i transkrypty znajdują się na hoście gatewaya.
|
||||
- Magazyn sesji i transkrypty znajdują się na hoście Gateway.
|
||||
|
||||
Wiele urządzeń/kanałów może mapować na tę samą sesję, ale historia nie jest w pełni
|
||||
Wiele urządzeń/kanałów może mapować się na tę samą sesję, ale historia nie jest w pełni
|
||||
synchronizowana z powrotem do każdego klienta. Zalecenie: używaj jednego głównego urządzenia do długich
|
||||
konwersacji, aby uniknąć rozbieżnego kontekstu. Control UI i TUI zawsze pokazują
|
||||
transkrypt sesji obsługiwany przez gateway, więc są źródłem prawdy.
|
||||
transkrypt sesji oparty na Gateway, więc są źródłem prawdy.
|
||||
|
||||
Szczegóły: [Zarządzanie sesjami](/pl/concepts/session).
|
||||
|
||||
## Metadane wyników narzędzi
|
||||
|
||||
`content` wyniku narzędzia to wynik widoczny dla modelu. `details` wyniku narzędzia to
|
||||
metadane runtime do renderowania UI, diagnostyki, dostarczania multimediów i pluginów.
|
||||
metadane runtime do renderowania UI, diagnostyki, dostarczania mediów i Pluginów.
|
||||
|
||||
OpenClaw utrzymuje tę granicę jako jawną:
|
||||
OpenClaw utrzymuje tę granicę jawnie:
|
||||
|
||||
- `toolResult.details` jest usuwane przed ponownym odtworzeniem u providera i wejściem do compaction.
|
||||
- `toolResult.details` jest usuwane przed odtworzeniem przez dostawcę i wejściem Compaction.
|
||||
- Utrwalone transkrypty sesji przechowują tylko ograniczone `details`; zbyt duże metadane
|
||||
są zastępowane zwartym podsumowaniem oznaczonym `persistedDetailsTruncated: true`.
|
||||
- Pluginy i narzędzia powinny umieszczać tekst, który model musi przeczytać, w `content`, nie tylko
|
||||
są zastępowane zwięzłym podsumowaniem oznaczonym `persistedDetailsTruncated: true`.
|
||||
- Pluginy i narzędzia powinny umieszczać tekst, który model musi przeczytać, w `content`, a nie tylko
|
||||
w `details`.
|
||||
|
||||
## Treści przychodzące i kontekst historii
|
||||
|
||||
OpenClaw oddziela **treść promptu** od **treści komendy**:
|
||||
OpenClaw oddziela **treść promptu** od **treści polecenia**:
|
||||
|
||||
- `BodyForAgent`: podstawowy tekst dla bieżącej wiadomości przeznaczony dla modelu. Pluginy
|
||||
- `BodyForAgent`: główny tekst bieżącej wiadomości skierowany do modelu. Pluginy
|
||||
kanałów powinny utrzymywać go skupionym na bieżącym tekście nadawcy niosącym prompt.
|
||||
- `Body`: starszy fallback promptu. Może zawierać koperty kanału i
|
||||
opcjonalne opakowania historii, ale bieżące kanały nie powinny polegać na nim jako
|
||||
podstawowym wejściu modelu, gdy dostępne jest `BodyForAgent`.
|
||||
- `CommandBody`: surowy tekst użytkownika do parsowania dyrektyw/komend.
|
||||
- `RawBody`: starszy alias dla `CommandBody` (zachowany dla kompatybilności).
|
||||
- `Body`: starsza rezerwowa treść promptu. Może obejmować koperty kanału i
|
||||
opcjonalne opakowania historii, ale bieżące kanały nie powinny polegać na niej jako na
|
||||
głównym wejściu modelu, gdy dostępne jest `BodyForAgent`.
|
||||
- `CommandBody`: surowy tekst użytkownika do parsowania dyrektyw/poleceń.
|
||||
- `RawBody`: starszy alias dla `CommandBody` (zachowany dla zgodności).
|
||||
|
||||
Gdy kanał dostarcza historię, używa wspólnego opakowania:
|
||||
|
||||
- `[Chat messages since your last reply - for context]`
|
||||
- `[Current message - respond to this]`
|
||||
|
||||
W przypadku **czatów niebezpośrednich** (grup/kanałów/pokoi) **treść bieżącej wiadomości** jest poprzedzana
|
||||
etykietą nadawcy (w tym samym stylu, którego używają wpisy historii). Dzięki temu wiadomości
|
||||
czasu rzeczywistego i kolejkowane/historyczne pozostają spójne w prompcie agenta.
|
||||
Dla **czatów niebezpośrednich** (grup/kanałów/pokoi) **treść bieżącej wiadomości** jest poprzedzana
|
||||
etykietą nadawcy (tym samym stylem, który jest używany dla wpisów historii). Dzięki temu wiadomości
|
||||
w czasie rzeczywistym oraz wiadomości z kolejki/historii są spójne w prompcie agenta.
|
||||
|
||||
Bufory historii są **tylko oczekujące**: obejmują wiadomości grupowe, które _nie_
|
||||
uruchomiły przebiegu (na przykład wiadomości bramkowane wzmianką) i **wykluczają** wiadomości
|
||||
już znajdujące się w transkrypcie sesji.
|
||||
wywołały przebiegu (na przykład wiadomości ograniczone wzmianką), i **wykluczają** wiadomości,
|
||||
które już znajdują się w transkrypcie sesji.
|
||||
|
||||
Usuwanie dyrektyw stosuje się tylko do sekcji **bieżącej wiadomości**, aby historia
|
||||
pozostała nienaruszona. Kanały, które opakowują historię, powinny ustawić `CommandBody` (lub
|
||||
`RawBody`) na oryginalny tekst wiadomości i zachować `Body` jako połączony prompt.
|
||||
Ustrukturyzowana historia, odpowiedzi, przekazane wiadomości i metadane kanału są renderowane jako
|
||||
bloki niezaufanego kontekstu w roli użytkownika podczas składania promptu.
|
||||
Usuwanie dyrektyw dotyczy tylko sekcji **bieżącej wiadomości**, więc historia
|
||||
pozostaje nienaruszona. Kanały, które opakowują historię, powinny ustawiać `CommandBody` (lub
|
||||
`RawBody`) na oryginalny tekst wiadomości i utrzymywać `Body` jako połączony prompt.
|
||||
Ustrukturyzowana historia, odpowiedź, przekazane dalej wiadomości i metadane kanału są renderowane jako
|
||||
bloki niezaufanego kontekstu roli użytkownika podczas składania promptu.
|
||||
Bufory historii można konfigurować przez `messages.groupChat.historyLimit` (globalna
|
||||
wartość domyślna) oraz nadpisania per kanał, takie jak `channels.slack.historyLimit` lub
|
||||
wartość domyślna) oraz nadpisania dla kanałów, takie jak `channels.slack.historyLimit` lub
|
||||
`channels.telegram.accounts.<id>.historyLimit` (ustaw `0`, aby wyłączyć).
|
||||
|
||||
## Kolejkowanie i followupy
|
||||
## Kolejkowanie i kontynuacje
|
||||
|
||||
Jeśli przebieg jest już aktywny, wiadomości przychodzące mogą być kolejkowane, kierowane do
|
||||
bieżącego przebiegu albo zbierane do tury followup.
|
||||
Jeśli przebieg jest już aktywny, wiadomości przychodzące mogą zostać zakolejkowane, skierowane do
|
||||
bieżącego przebiegu albo zebrane na turę kontynuacji.
|
||||
|
||||
- Konfiguracja przez `messages.queue` (i `messages.queue.byChannel`).
|
||||
- Tryb domyślny to `steer`, z debounce followupu 500 ms, gdy sterowanie wraca
|
||||
do kolejkowanego dostarczenia followupu.
|
||||
- Skonfiguruj przez `messages.queue` (oraz `messages.queue.byChannel`).
|
||||
- Domyślny tryb to `steer`, z 500 ms debounce dla kontynuacji, gdy sterowanie wraca
|
||||
do zakolejkowanego dostarczania kontynuacji.
|
||||
- Tryby: `steer`, `followup`, `collect`, `steer-backlog`, `interrupt` oraz
|
||||
starszy tryb `queue` obsługujący jedną wiadomość naraz.
|
||||
|
||||
Szczegóły: [Kolejka komend](/pl/concepts/queue) i [Kolejka sterowania](/pl/concepts/queue-steering).
|
||||
Szczegóły: [Kolejka poleceń](/pl/concepts/queue) i [Kolejka sterowania](/pl/concepts/queue-steering).
|
||||
|
||||
## Własność przebiegu kanału
|
||||
|
||||
Pluginy kanałów mogą zachowywać kolejność, stosować debounce wejścia i nakładać transportowy
|
||||
backpressure, zanim wiadomość trafi do kolejki sesji. Nie powinny narzucać
|
||||
osobnego timeoutu wokół samej tury agenta. Gdy wiadomość zostanie przekierowana do
|
||||
sesji, długotrwała praca jest zarządzana przez cykl życia sesji, narzędzia i runtime,
|
||||
dzięki czemu wszystkie kanały raportują wolne tury i odzyskują po nich działanie spójnie.
|
||||
Pluginy kanałów mogą zachowywać kolejność, stosować debounce wejścia i nakładać transportowe
|
||||
ograniczanie zwrotne, zanim wiadomość trafi do kolejki sesji. Nie powinny nakładać
|
||||
osobnego timeoutu wokół samej tury agenta. Gdy wiadomość zostanie skierowana do
|
||||
sesji, długotrwałą pracą zarządzają cykl życia sesji, narzędzi i runtime,
|
||||
aby wszystkie kanały raportowały powolne tury i odzyskiwały się po nich spójnie.
|
||||
|
||||
## Streaming, dzielenie na fragmenty i grupowanie
|
||||
|
||||
Streaming blokowy wysyła częściowe odpowiedzi, gdy model tworzy bloki tekstu.
|
||||
Dzielenie na fragmenty respektuje limity tekstu kanału i unika dzielenia bloków kodu.
|
||||
Dzielenie na fragmenty respektuje limity tekstu kanału i unika rozdzielania ogrodzonych bloków kodu.
|
||||
|
||||
Kluczowe ustawienia:
|
||||
|
||||
@ -169,11 +169,11 @@ Szczegóły: [Streaming + dzielenie na fragmenty](/pl/concepts/streaming).
|
||||
|
||||
## Widoczność rozumowania i tokeny
|
||||
|
||||
OpenClaw może pokazywać albo ukrywać rozumowanie modelu:
|
||||
OpenClaw może ujawniać lub ukrywać rozumowanie modelu:
|
||||
|
||||
- `/reasoning on|off|stream` kontroluje widoczność.
|
||||
- Treść rozumowania nadal wlicza się do użycia tokenów, gdy jest tworzona przez model.
|
||||
- Telegram obsługuje strumień rozumowania w dymku wersji roboczej.
|
||||
- Treść rozumowania nadal wlicza się do użycia tokenów, gdy jest generowana przez model.
|
||||
- Telegram obsługuje streaming rozumowania do przejściowego dymka szkicu, który jest usuwany po końcowym dostarczeniu; użyj `/reasoning on` dla trwałego wyjścia rozumowania.
|
||||
|
||||
Szczegóły: [Dyrektywy myślenia + rozumowania](/pl/tools/thinking) i [Użycie tokenów](/pl/reference/token-use).
|
||||
|
||||
@ -182,38 +182,38 @@ Szczegóły: [Dyrektywy myślenia + rozumowania](/pl/tools/thinking) i [Użycie
|
||||
Formatowanie wiadomości wychodzących jest scentralizowane w `messages`:
|
||||
|
||||
- `messages.responsePrefix`, `channels.<channel>.responsePrefix` i `channels.<channel>.accounts.<id>.responsePrefix` (kaskada prefiksów wychodzących), plus `channels.whatsapp.messagePrefix` (prefiks przychodzący WhatsApp)
|
||||
- Wątkowanie odpowiedzi przez `replyToMode` i wartości domyślne per kanał
|
||||
- Wątkowanie odpowiedzi przez `replyToMode` i wartości domyślne kanałów
|
||||
|
||||
Szczegóły: [Konfiguracja](/pl/gateway/config-agents#messages) i dokumentacja kanałów.
|
||||
|
||||
## Ciche odpowiedzi
|
||||
|
||||
Dokładny token ciszy `NO_REPLY` / `no_reply` oznacza „nie dostarczaj odpowiedzi widocznej dla użytkownika”.
|
||||
Gdy tura ma także oczekujące multimedia narzędzi, takie jak wygenerowany dźwięk TTS, OpenClaw
|
||||
Dokładny cichy token `NO_REPLY` / `no_reply` oznacza „nie dostarczaj odpowiedzi widocznej dla użytkownika”.
|
||||
Gdy tura ma też oczekujące media narzędzia, takie jak wygenerowany dźwięk TTS, OpenClaw
|
||||
usuwa cichy tekst, ale nadal dostarcza załącznik multimedialny.
|
||||
OpenClaw rozstrzyga to zachowanie według typu konwersacji:
|
||||
|
||||
- Konwersacje bezpośrednie domyślnie nie zezwalają na ciszę i przepisują samą cichą
|
||||
odpowiedź na krótką widoczną odpowiedź fallback.
|
||||
- Grupy/kanały domyślnie zezwalają na ciszę.
|
||||
- Wewnętrzna orkiestracja domyślnie zezwala na ciszę.
|
||||
- Konwersacje bezpośrednie domyślnie nie pozwalają na ciszę i przepisują samą cichą
|
||||
odpowiedź na krótką widoczną odpowiedź rezerwową.
|
||||
- Grupy/kanały domyślnie pozwalają na ciszę.
|
||||
- Wewnętrzna orkiestracja domyślnie pozwala na ciszę.
|
||||
|
||||
OpenClaw używa także cichych odpowiedzi przy wewnętrznych awariach runnera, które występują
|
||||
OpenClaw używa też cichych odpowiedzi dla wewnętrznych awarii runnera, które występują
|
||||
przed jakąkolwiek odpowiedzią asystenta w czatach niebezpośrednich, aby grupy/kanały nie widziały
|
||||
szablonowego błędu gatewaya. Czaty bezpośrednie domyślnie pokazują zwięzłą treść awarii;
|
||||
szablonowego błędu Gateway. Czaty bezpośrednie domyślnie pokazują zwięzły komunikat awarii;
|
||||
surowe szczegóły runnera są pokazywane tylko wtedy, gdy `/verbose` ma wartość `on` lub `full`.
|
||||
|
||||
Wartości domyślne znajdują się pod `agents.defaults.silentReply` i
|
||||
`agents.defaults.silentReplyRewrite`; `surfaces.<id>.silentReply` i
|
||||
`surfaces.<id>.silentReplyRewrite` mogą je nadpisać per powierzchnia.
|
||||
`surfaces.<id>.silentReplyRewrite` mogą je nadpisać dla poszczególnych powierzchni.
|
||||
|
||||
Gdy sesja nadrzędna ma co najmniej jeden oczekujący uruchomiony przebieg podagenta, same
|
||||
ciche odpowiedzi są odrzucane na wszystkich powierzchniach zamiast przepisywania, więc
|
||||
sesja nadrzędna pozostaje cicha, dopóki zdarzenie ukończenia dziecka nie dostarczy właściwej odpowiedzi.
|
||||
Gdy sesja nadrzędna ma co najmniej jeden oczekujący uruchomiony przebieg subagenta, same
|
||||
ciche odpowiedzi są odrzucane na wszystkich powierzchniach zamiast przepisywania, dzięki czemu
|
||||
sesja nadrzędna pozostaje cicha do czasu, aż zdarzenie ukończenia dziecka dostarczy właściwą odpowiedź.
|
||||
|
||||
## Powiązane
|
||||
|
||||
- [Streaming](/pl/concepts/streaming) — dostarczanie wiadomości w czasie rzeczywistym
|
||||
- [Ponów](/pl/concepts/retry) — zachowanie ponawiania dostarczania wiadomości
|
||||
- [Ponawianie](/pl/concepts/retry) — zachowanie ponawiania dostarczania wiadomości
|
||||
- [Kolejka](/pl/concepts/queue) — kolejka przetwarzania wiadomości
|
||||
- [Kanały](/pl/channels) — integracje z platformami wiadomości
|
||||
- [Kanały](/pl/channels) — integracje z platformami komunikacyjnymi
|
||||
|
||||
@ -3,25 +3,21 @@ read_when:
|
||||
- Konfigurowanie widocznych aktualizacji postępu dla długo trwających tur czatu
|
||||
- Wybór między trybami strumieniowania częściowego, blokowego i postępu
|
||||
- Wyjaśnienie, jak OpenClaw aktualizuje jedną wiadomość w kanale podczas trwania pracy
|
||||
- Rozwiązywanie problemów z wersjami roboczymi postępu, samodzielnymi komunikatami o postępie lub awaryjnym mechanizmem finalizacji
|
||||
summary: 'Wersje robocze postępu: jedna widoczna wiadomość o pracy w toku, która aktualizuje się podczas działania agenta'
|
||||
title: Wersje robocze postępu
|
||||
- Rozwiązywanie problemów z roboczymi wersjami postępu, samodzielnymi komunikatami o postępie lub awaryjną finalizacją
|
||||
summary: 'Wersje robocze postępu: jeden widoczny komunikat o trwającej pracy, aktualizowany podczas działania agenta'
|
||||
title: Szkice postępu
|
||||
x-i18n:
|
||||
generated_at: "2026-05-04T02:23:40Z"
|
||||
generated_at: "2026-05-04T07:03:57Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 8ce19262800f1c3c3e505a3cf1d41ed5c3dffcbca168ad7b7afabdce62eee8fe
|
||||
source_hash: f78c07866cd7f613012a80a40413e5866c1dd2edd477088f9fc141347f5f3788
|
||||
source_path: concepts/progress-drafts.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
Szkice postępu sprawiają, że długie tury agenta w czacie wydają się żywe, bez zmieniania
|
||||
konwersacji w stos tymczasowych odpowiedzi statusowych.
|
||||
Wersje robocze postępu sprawiają, że długotrwałe tury agenta wydają się żywe na czacie, bez zamieniania rozmowy w stos tymczasowych odpowiedzi statusowych.
|
||||
|
||||
Gdy szkice postępu są włączone, OpenClaw tworzy jedną widoczną wiadomość roboczą
|
||||
dopiero po tym, jak tura potwierdzi, że wykonuje rzeczywistą pracę, aktualizuje ją, gdy
|
||||
agent czyta, planuje, wywołuje narzędzia lub czeka na zatwierdzenie, a następnie zamienia
|
||||
ten szkic w odpowiedź końcową, gdy kanał może zrobić to bezpiecznie.
|
||||
Gdy wersje robocze postępu są włączone, OpenClaw tworzy jedną widoczną wiadomość w toku dopiero wtedy, gdy tura udowodni, że wykonuje rzeczywistą pracę, aktualizuje ją, gdy agent czyta, planuje, wywołuje narzędzia lub czeka na zatwierdzenie, a następnie przekształca tę wersję roboczą w końcową odpowiedź, gdy kanał może zrobić to bezpiecznie.
|
||||
|
||||
```text
|
||||
Shelling...
|
||||
@ -30,12 +26,11 @@ Shelling...
|
||||
🛠️ Exec: run tests
|
||||
```
|
||||
|
||||
Używaj szkiców postępu, gdy chcesz mieć jedną uporządkowaną wiadomość statusową podczas pracy
|
||||
intensywnie korzystającej z narzędzi oraz odpowiedź końcową po zakończeniu tury.
|
||||
Używaj wersji roboczych postępu, gdy chcesz mieć jedną uporządkowaną wiadomość statusową podczas pracy intensywnie korzystającej z narzędzi oraz końcową odpowiedź po zakończeniu tury.
|
||||
|
||||
## Szybki start
|
||||
|
||||
Włącz szkice postępu dla kanału za pomocą `streaming.mode: "progress"`:
|
||||
Włącz wersje robocze postępu dla każdego kanału za pomocą `streaming.mode: "progress"`:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -49,58 +44,42 @@ Włącz szkice postępu dla kanału za pomocą `streaming.mode: "progress"`:
|
||||
}
|
||||
```
|
||||
|
||||
To zwykle wystarcza. OpenClaw wybierze automatyczną jednoznakową etykietę, poczeka,
|
||||
aż praca potrwa co najmniej pięć sekund lub wyemituje drugie zdarzenie pracy, doda zwięzłe
|
||||
wiersze postępu, gdy dzieje się użyteczna praca, i wyciszy zduplikowane samodzielne
|
||||
komunikaty postępu dla tej tury.
|
||||
To zwykle wystarcza. OpenClaw wybierze automatyczną jednoelementową etykietę, poczeka, aż praca potrwa co najmniej pięć sekund lub wyemituje drugie zdarzenie pracy, doda zwarte wiersze postępu, gdy trwa użyteczna praca, i wyciszy zduplikowane samodzielne komunikaty postępu dla tej tury.
|
||||
|
||||
## Co Widzą Użytkownicy
|
||||
## Co widzą użytkownicy
|
||||
|
||||
Szkic postępu ma dwie części:
|
||||
Wersja robocza postępu ma dwie części:
|
||||
|
||||
| Część | Cel |
|
||||
| Część | Cel |
|
||||
| -------------- | --------------------------------------------------------------------------- |
|
||||
| Etykieta | Krótki tytuł, taki jak `Thinking...` lub `Shelling...`. |
|
||||
| Wiersze postępu | Zwięzłe aktualizacje uruchomienia używające tych samych etykiet narzędzi i ikon co szczegółowe wyjście. |
|
||||
| Etykieta | Krótki tytuł, taki jak `Thinking...` lub `Shelling...`. |
|
||||
| Wiersze postępu | Zwarte aktualizacje uruchomienia używające tych samych etykiet narzędzi i ikon co szczegółowe wyjście. |
|
||||
|
||||
Etykieta pojawia się po rozpoczęciu przez agenta znaczącej pracy i gdy pozostaje on zajęty
|
||||
przez pięć sekund albo emituje drugie zdarzenie pracy. Odpowiedzi zawierające wyłącznie
|
||||
zwykły tekst nie pokazują szkicu postępu. Wiersze postępu są dodawane tylko wtedy, gdy agent
|
||||
emituje użyteczne aktualizacje pracy, na przykład `🛠️ Exec`, `🔎 Web Search` lub `✍️ Write: to /tmp/file`.
|
||||
Domyślnie używają tego samego zwięzłego trybu wyjaśnień co `/verbose`; ustaw
|
||||
`agents.defaults.toolProgressDetail: "raw"` podczas debugowania, gdy chcesz też dołączać surowe
|
||||
polecenia/szczegóły.
|
||||
Odpowiedź końcowa zastępuje szkic, gdy to możliwe; w przeciwnym razie
|
||||
OpenClaw wysyła odpowiedź końcową normalnie i czyści szkic lub przestaje go aktualizować
|
||||
zgodnie z transportem kanału.
|
||||
Etykieta pojawia się po rozpoczęciu przez agenta znaczącej pracy i gdy pozostaje zajęty przez pięć sekund albo wyemituje drugie zdarzenie pracy. Odpowiedzi składające się wyłącznie ze zwykłego tekstu nie pokazują wersji roboczej postępu. Wiersze postępu są dodawane tylko wtedy, gdy agent emituje użyteczne aktualizacje pracy, na przykład `🛠️ Exec`, `🔎 Web Search` lub `✍️ Write: to /tmp/file`. Domyślnie używają tego samego zwartego trybu objaśnień co `/verbose`; ustaw `agents.defaults.toolProgressDetail: "raw"` podczas debugowania, gdy chcesz również dołączać surowe polecenia/szczegóły.
|
||||
Końcowa odpowiedź zastępuje wersję roboczą, gdy jest to możliwe; w przeciwnym razie OpenClaw wysyła końcową odpowiedź normalnie i czyści albo przestaje aktualizować wersję roboczą zgodnie z transportem kanału.
|
||||
|
||||
## Wybór Trybu
|
||||
## Wybierz tryb
|
||||
|
||||
`channels.<channel>.streaming.mode` kontroluje widoczne zachowanie w toku:
|
||||
`channels.<channel>.streaming.mode` steruje widocznym zachowaniem w toku:
|
||||
|
||||
| Tryb | Najlepsze dla | Co pojawia się w czacie |
|
||||
| ---------- | -------------------------------- | ------------------------------------------------- |
|
||||
| `off` | Ciche kanały | Tylko odpowiedź końcowa. |
|
||||
| `partial` | Obserwowanie pojawiania się tekstu odpowiedzi | Jeden szkic edytowany najnowszym tekstem odpowiedzi. |
|
||||
| Tryb | Najlepsze dla | Co pojawia się na czacie |
|
||||
| ---------- | -------------------------------- | ------------------------------------------------ |
|
||||
| `off` | Ciche kanały | Tylko końcowa odpowiedź. |
|
||||
| `partial` | Obserwowanie pojawiania się tekstu odpowiedzi | Jedna wersja robocza edytowana najnowszym tekstem odpowiedzi. |
|
||||
| `block` | Większe fragmenty podglądu odpowiedzi | Jeden podgląd aktualizowany lub dołączany w większych fragmentach. |
|
||||
| `progress` | Tury intensywnie korzystające z narzędzi lub długotrwałe | Jeden szkic statusu, potem odpowiedź końcowa. |
|
||||
| `progress` | Tury intensywnie korzystające z narzędzi lub długotrwałe | Jedna wersja robocza statusu, a potem końcowa odpowiedź. |
|
||||
|
||||
Wybierz `progress`, gdy użytkownikom bardziej zależy na tym, „co się dzieje”, niż na obserwowaniu
|
||||
strumieniowania tekstu odpowiedzi token po tokenie.
|
||||
Wybierz `progress`, gdy użytkownikom bardziej zależy na tym, „co się dzieje”, niż na obserwowaniu strumieniowania tekstu odpowiedzi token po tokenie.
|
||||
|
||||
Wybierz `partial`, gdy sama odpowiedź jest sygnałem postępu.
|
||||
|
||||
Wybierz `block`, gdy chcesz otrzymywać aktualizacje podglądu szkicu w większych fragmentach tekstu. W
|
||||
Discord i Telegram, `streaming.mode: "block"` nadal oznacza strumieniowanie podglądu, a nie
|
||||
normalne dostarczanie bloków. Użyj `streaming.block.enabled` lub starszego
|
||||
`blockStreaming`, gdy chcesz normalnych odpowiedzi blokowych.
|
||||
Wybierz `block`, gdy chcesz aktualizacji podglądu wersji roboczej w większych fragmentach tekstu. W Discord i Telegram `streaming.mode: "block"` nadal oznacza strumieniowanie podglądu, a nie normalne dostarczanie blokowe. Użyj `streaming.block.enabled` lub starszego `blockStreaming`, gdy chcesz normalnych odpowiedzi blokowych.
|
||||
|
||||
## Konfigurowanie Etykiet
|
||||
## Skonfiguruj etykiety
|
||||
|
||||
Etykiety postępu znajdują się w `channels.<channel>.streaming.progress`.
|
||||
|
||||
Domyślna etykieta to `auto`, która wybiera z wbudowanej w OpenClaw
|
||||
puli jednoznakowych etykiet z wielokropkiem:
|
||||
Domyślna etykieta to `auto`, która wybiera z wbudowanej w OpenClaw puli jednoelementowych etykiet z wielokropkiem:
|
||||
|
||||
```text
|
||||
Thinking...
|
||||
@ -160,7 +139,7 @@ Użyj własnej automatycznej puli etykiet:
|
||||
}
|
||||
```
|
||||
|
||||
Ukryj etykietę i pokazuj tylko wiersze postępu:
|
||||
Ukryj etykietę i pokaż tylko wiersze postępu:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -177,13 +156,11 @@ Ukryj etykietę i pokazuj tylko wiersze postępu:
|
||||
}
|
||||
```
|
||||
|
||||
## Kontrola Wierszy Postępu
|
||||
## Kontroluj wiersze postępu
|
||||
|
||||
Wiersze postępu są domyślnie włączone w trybie postępu. Pochodzą z rzeczywistych
|
||||
zdarzeń uruchomienia: startów narzędzi, aktualizacji elementów, planów zadań, zatwierdzeń, wyjścia
|
||||
poleceń, podsumowań poprawek i podobnej aktywności agenta.
|
||||
Wiersze postępu są domyślnie włączone w trybie postępu. Pochodzą z rzeczywistych zdarzeń uruchomienia: uruchomień narzędzi, aktualizacji elementów, planów zadań, zatwierdzeń, wyjścia poleceń, podsumowań poprawek i podobnej aktywności agenta.
|
||||
|
||||
OpenClaw używa tego samego formatera dla szkiców postępu i `/verbose`:
|
||||
OpenClaw używa tego samego formatera dla wersji roboczych postępu i `/verbose`:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -195,10 +172,7 @@ OpenClaw używa tego samego formatera dla szkiców postępu i `/verbose`:
|
||||
}
|
||||
```
|
||||
|
||||
`"explain"` jest wartością domyślną i utrzymuje stabilność szkiców dzięki zwięzłym etykietom, takim jak
|
||||
`🛠️ Exec: check JS syntax for /tmp/app.js`. `"raw"` dołącza bazowe
|
||||
polecenie/szczegół, gdy jest dostępny, co jest przydatne podczas debugowania, ale powoduje więcej szumu w
|
||||
czacie.
|
||||
`"explain"` jest wartością domyślną i utrzymuje stabilność wersji roboczych dzięki zwięzłym etykietom, takim jak `🛠️ Exec: check JS syntax for /tmp/app.js`. `"raw"` dołącza bazowe polecenie/szczegół, gdy jest dostępny, co jest przydatne podczas debugowania, ale bardziej hałaśliwe na czacie.
|
||||
|
||||
Na przykład to samo polecenie wygląda inaczej w zależności od trybu szczegółowości:
|
||||
|
||||
@ -224,7 +198,30 @@ Ogranicz liczbę wierszy pozostających widocznymi:
|
||||
}
|
||||
```
|
||||
|
||||
Zachowaj pojedynczy szkic postępu, ale ukryj wiersze narzędzi i zadań:
|
||||
Wiersze postępu są automatycznie kompaktowane, aby ograniczyć przełamywanie układu dymka czatu podczas edytowania wersji roboczej.
|
||||
|
||||
OpenClaw domyślnie skraca długie wiersze postępu, aby powtarzane edycje wersji roboczej nie zawijały się inaczej przy każdej aktualizacji. Prefiks pozostaje czytelny, a długie szczegóły, takie jak ścieżki lub surowe polecenia, są skracane wielokropkiem.
|
||||
|
||||
Slack może renderować wiersze postępu jako strukturalne pola Block Kit zamiast pojedynczej treści tekstowej:
|
||||
|
||||
```json5
|
||||
{
|
||||
channels: {
|
||||
slack: {
|
||||
streaming: {
|
||||
mode: "progress",
|
||||
progress: {
|
||||
render: "rich",
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
Renderowanie wzbogacone zachowuje ten sam zwykłotekstowy fallback, dzięki czemu kanały i klienci, którzy nie obsługują bogatszej formy, nadal mogą pokazać zwarty tekst postępu.
|
||||
|
||||
Zachowaj pojedynczą wersję roboczą postępu, ale ukryj wiersze narzędzi i zadań:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -241,74 +238,54 @@ Zachowaj pojedynczy szkic postępu, ale ukryj wiersze narzędzi i zadań:
|
||||
}
|
||||
```
|
||||
|
||||
Przy `toolProgress: false` OpenClaw nadal wycisza starsze samodzielne
|
||||
wiadomości postępu narzędzi dla tej tury. Kanał pozostaje wizualnie cichy aż do
|
||||
odpowiedzi końcowej, z wyjątkiem etykiety, jeśli została skonfigurowana.
|
||||
Przy `toolProgress: false` OpenClaw nadal wycisza starsze samodzielne wiadomości postępu narzędzi dla tej tury. Kanał pozostaje wizualnie cichy aż do końcowej odpowiedzi, z wyjątkiem etykiety, jeśli została skonfigurowana.
|
||||
|
||||
## Zachowanie Kanałów
|
||||
## Zachowanie kanałów
|
||||
|
||||
Każdy kanał używa najczystszego obsługiwanego transportu:
|
||||
Każdy kanał używa najczystszego transportu, który obsługuje:
|
||||
|
||||
| Kanał | Transport postępu | Uwagi |
|
||||
| --------------- | -------------------------------------- | --------------------------------------------------------------------- |
|
||||
| Discord | Wyślij jedną wiadomość, a następnie ją edytuj. | Tekst końcowy jest edytowany w miejscu, gdy mieści się w jednej bezpiecznej wiadomości podglądu. |
|
||||
| Matrix | Wyślij jedno zdarzenie, a następnie je edytuj. | Konfiguracja strumieniowania na poziomie konta kontroluje szkice na poziomie konta. |
|
||||
| Microsoft Teams | Natywny strumień Teams w czatach osobistych. | `streaming.mode: "block"` mapuje się na dostarczanie bloków Teams. |
|
||||
| Slack | Natywny strumień lub edytowalny wpis szkicu. | Dostępność wątku wpływa na to, czy można użyć natywnego strumieniowania. |
|
||||
| Telegram | Wyślij jedną wiadomość, a następnie ją edytuj. | Starsze widoczne szkice mogą zostać zastąpione, aby końcowe znaczniki czasu pozostały użyteczne. |
|
||||
| Mattermost | Edytowalny wpis szkicu. | Aktywność narzędzi jest składana do tego samego wpisu w stylu szkicu. |
|
||||
| Kanał | Transport postępu | Uwagi |
|
||||
| --------------- | ------------------------------------ | --------------------------------------------------------------------- |
|
||||
| Discord | Wysyła jedną wiadomość, a następnie ją edytuje. | Końcowy tekst jest edytowany w miejscu, gdy mieści się w jednej bezpiecznej wiadomości podglądu. |
|
||||
| Matrix | Wysyła jedno zdarzenie, a następnie je edytuje. | Konfiguracja strumieniowania na poziomie konta steruje wersjami roboczymi na poziomie konta. |
|
||||
| Microsoft Teams | Natywny strumień Teams w czatach osobistych. | `streaming.mode: "block"` mapuje się na dostarczanie blokowe Teams. |
|
||||
| Slack | Natywny strumień lub edytowalny post wersji roboczej. | Dostępność wątku wpływa na to, czy można użyć natywnego strumieniowania. |
|
||||
| Telegram | Wysyła jedną wiadomość, a następnie ją edytuje. | Starsze widoczne wersje robocze mogą zostać zastąpione, aby końcowe znaczniki czasu pozostały użyteczne. |
|
||||
| Mattermost | Edytowalny post wersji roboczej. | Aktywność narzędzi jest składana do tego samego posta w stylu wersji roboczej. |
|
||||
|
||||
Kanały bez bezpiecznej obsługi edycji zwykle wracają do wskaźników pisania lub
|
||||
dostarczania wyłącznie odpowiedzi końcowej.
|
||||
Kanały bez bezpiecznej obsługi edycji zwykle wracają do wskaźników pisania lub dostarczania tylko końcowej odpowiedzi.
|
||||
|
||||
## Finalizacja
|
||||
|
||||
Gdy odpowiedź końcowa jest gotowa, OpenClaw próbuje utrzymać czat w czystości:
|
||||
Gdy końcowa odpowiedź jest gotowa, OpenClaw próbuje utrzymać czat w czystości:
|
||||
|
||||
- Jeśli szkic może bezpiecznie stać się odpowiedzią końcową, OpenClaw edytuje go w miejscu.
|
||||
- Jeśli kanał używa natywnego strumieniowania postępu, OpenClaw finalizuje ten strumień,
|
||||
gdy natywny transport akceptuje tekst końcowy.
|
||||
- Jeśli odpowiedź końcowa zawiera multimedia, monit o zatwierdzenie, jawny cel odpowiedzi,
|
||||
zbyt wiele fragmentów albo nieudaną edycję/wysyłkę, OpenClaw wysyła odpowiedź końcową przez
|
||||
normalną ścieżkę dostarczania kanału.
|
||||
- Jeśli wersja robocza może bezpiecznie stać się końcową odpowiedzią, OpenClaw edytuje ją w miejscu.
|
||||
- Jeśli kanał używa natywnego strumieniowania postępu, OpenClaw finalizuje ten strumień, gdy natywny transport zaakceptuje końcowy tekst.
|
||||
- Jeśli końcowa odpowiedź zawiera multimedia, monit zatwierdzenia, jawny cel odpowiedzi, zbyt wiele fragmentów albo nieudaną edycję/wysłanie, OpenClaw wysyła końcową odpowiedź przez normalną ścieżkę dostarczania kanału.
|
||||
|
||||
Ścieżka awaryjna jest celowa. Lepiej wysłać świeżą odpowiedź końcową, niż
|
||||
utracić tekst, błędnie przypiąć odpowiedź do wątku lub nadpisać szkic ładunkiem, którego kanał
|
||||
nie potrafi bezpiecznie reprezentować.
|
||||
Ścieżka awaryjna jest celowa. Lepiej wysłać świeżą końcową odpowiedź, niż utracić tekst, błędnie przypisać odpowiedź do wątku albo nadpisać wersję roboczą ładunkiem, którego kanał nie potrafi bezpiecznie reprezentować.
|
||||
|
||||
## Rozwiązywanie Problemów
|
||||
## Rozwiązywanie problemów
|
||||
|
||||
**Widzę tylko odpowiedź końcową.**
|
||||
**Widzę tylko końcową odpowiedź.**
|
||||
|
||||
Sprawdź, czy `channels.<channel>.streaming.mode` jest ustawione na `progress` dla
|
||||
konta lub kanału, który obsłużył wiadomość. Niektóre ścieżki grupowe lub odpowiedzi z cytatem mogą
|
||||
wyłączyć podglądy szkiców dla tury, gdy kanał nie może bezpiecznie edytować właściwej
|
||||
wiadomości.
|
||||
Sprawdź, czy `channels.<channel>.streaming.mode` jest ustawione na `progress` dla konta lub kanału, który obsłużył wiadomość. Niektóre ścieżki grupowe lub odpowiedzi z cytatem mogą wyłączać podglądy wersji roboczych dla tury, gdy kanał nie może bezpiecznie edytować właściwej wiadomości.
|
||||
|
||||
**Widzę etykietę, ale bez wierszy narzędzi.**
|
||||
**Widzę etykietę, ale nie widzę wierszy narzędzi.**
|
||||
|
||||
Sprawdź `streaming.progress.toolProgress`. Jeśli ma wartość `false`, OpenClaw zachowuje
|
||||
zachowanie pojedynczego szkicu, ale ukrywa wiersze postępu narzędzi i zadań.
|
||||
Sprawdź `streaming.progress.toolProgress`. Jeśli ma wartość `false`, OpenClaw zachowuje zachowanie pojedynczej wersji roboczej, ale ukrywa wiersze postępu narzędzi i zadań.
|
||||
|
||||
**Widzę świeżą wiadomość końcową zamiast edytowanego szkicu.**
|
||||
**Widzę świeżą wiadomość końcową zamiast edytowanej wersji roboczej.**
|
||||
|
||||
To awaryjne zachowanie bezpieczeństwa. Może wystąpić przy odpowiedziach z multimediami, długich odpowiedziach,
|
||||
jawnych celach odpowiedzi, starych szkicach Telegram, brakujących celach wątków Slack,
|
||||
usuniętych wiadomościach podglądu lub nieudanej finalizacji natywnego strumienia.
|
||||
To awaryjne zachowanie bezpieczeństwa. Może wystąpić dla odpowiedzi z multimediami, długich odpowiedzi, jawnych celów odpowiedzi, starych wersji roboczych Telegram, brakujących celów wątków Slack, usuniętych wiadomości podglądu lub nieudanej finalizacji natywnego strumienia.
|
||||
|
||||
**Nadal widzę samodzielne wiadomości postępu.**
|
||||
|
||||
Tryb postępu wycisza domyślne samodzielne wiadomości postępu narzędzi, gdy szkic
|
||||
jest aktywny. Jeśli samodzielne wiadomości nadal się pojawiają, sprawdź, czy tura rzeczywiście
|
||||
używa trybu postępu, a nie `streaming.mode: "off"` ani ścieżki kanału, która
|
||||
nie może utworzyć szkicu dla tej wiadomości.
|
||||
Tryb postępu wycisza domyślne samodzielne wiadomości postępu narzędzi, gdy wersja robocza jest aktywna. Jeśli samodzielne wiadomości nadal się pojawiają, sprawdź, czy tura rzeczywiście używa trybu postępu, a nie `streaming.mode: "off"` ani ścieżki kanału, która nie może utworzyć wersji roboczej dla tej wiadomości.
|
||||
|
||||
**Teams zachowuje się inaczej niż Discord lub Telegram.**
|
||||
|
||||
Microsoft Teams używa natywnego strumienia w czatach osobistych zamiast ogólnego
|
||||
transportu podglądu typu wyślij-i-edytuj. Teams traktuje też `streaming.mode: "block"` jako
|
||||
dostarczanie bloków Teams, ponieważ nie ma tego samego trybu blokowego podglądu szkicu
|
||||
używanego przez Discord i Telegram.
|
||||
Microsoft Teams używa natywnego strumienia w czatach osobistych zamiast ogólnego transportu podglądu typu wyślij-i-edytuj. Teams traktuje też `streaming.mode: "block"` jako dostarczanie blokowe Teams, ponieważ nie ma tego samego trybu blokowego podglądu wersji roboczej, którego używają Discord i Telegram.
|
||||
|
||||
## Powiązane
|
||||
|
||||
|
||||
@ -1,82 +1,82 @@
|
||||
---
|
||||
read_when:
|
||||
- Zrozumienie, jak współdziała stos QA
|
||||
- Rozszerzanie qa-lab, qa-channel lub adaptera transportowego
|
||||
- Zrozumienie, jak stos QA składa się w całość
|
||||
- Rozszerzanie qa-lab, qa-channel lub adaptera transportu
|
||||
- Dodawanie scenariuszy QA opartych na repozytorium
|
||||
- Tworzenie bardziej realistycznej automatyzacji QA wokół pulpitu Gateway
|
||||
summary: 'Omówienie stosu QA: qa-lab, qa-channel, scenariusze oparte na repozytorium, ścieżki transportu na żywo, adaptery transportu i raportowanie.'
|
||||
title: Przegląd QA
|
||||
- Tworzenie bardziej realistycznej automatyzacji QA wokół panelu Gateway
|
||||
summary: 'Przegląd stosu QA: qa-lab, qa-channel, scenariusze oparte na repozytorium, ścieżki transportu na żywo, adaptery transportu i raportowanie.'
|
||||
title: Omówienie QA
|
||||
x-i18n:
|
||||
generated_at: "2026-05-04T02:23:52Z"
|
||||
generated_at: "2026-05-04T07:04:39Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 0b376767b967a51cc8a45ca5ce420f78067b52e6368d2abe921ffed533f6f9ba
|
||||
source_hash: 067f5aa0831724659ae36d548ef2e7bd28b40aad9cef45f325a01a2748003b29
|
||||
source_path: concepts/qa-e2e-automation.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
Prywatny stos QA ma służyć do testowania OpenClaw w bardziej realistyczny,
|
||||
kanałowy sposób, niż pozwala na to pojedynczy test jednostkowy.
|
||||
Prywatny stos QA ma sprawdzać OpenClaw w bardziej realistyczny,
|
||||
ukształtowany przez kanały sposób niż pojedynczy test jednostkowy.
|
||||
|
||||
Bieżące elementy:
|
||||
Obecne elementy:
|
||||
|
||||
- `extensions/qa-channel`: syntetyczny kanał wiadomości z powierzchniami wiadomości prywatnych, kanału, wątku,
|
||||
- `extensions/qa-channel`: syntetyczny kanał wiadomości z powierzchniami DM, kanału, wątku,
|
||||
reakcji, edycji i usuwania.
|
||||
- `extensions/qa-lab`: interfejs debuggera i magistrala QA do obserwowania transkrypcji,
|
||||
wstrzykiwania wiadomości przychodzących oraz eksportowania raportu Markdown.
|
||||
- `extensions/qa-matrix`, przyszłe Pluginy runnerów: adaptery transportu live, które
|
||||
sterują rzeczywistym kanałem wewnątrz podrzędnego Gateway QA.
|
||||
- `qa/`: zasoby początkowe oparte na repozytorium dla zadania startowego i bazowych
|
||||
wstrzykiwania wiadomości przychodzących i eksportowania raportu Markdown.
|
||||
- `extensions/qa-matrix`, przyszłe pluginy runnera: adaptery transportu live, które
|
||||
sterują prawdziwym kanałem w podrzędnym Gateway QA.
|
||||
- `qa/`: zasoby seed oparte na repozytorium dla zadania startowego i bazowych
|
||||
scenariuszy QA.
|
||||
- [Mantis](/pl/concepts/mantis): weryfikacja live przed i po dla błędów, które
|
||||
wymagają rzeczywistych transportów, zrzutów ekranu z przeglądarki, stanu VM i dowodów PR.
|
||||
wymagają prawdziwych transportów, zrzutów ekranu przeglądarki, stanu VM i dowodów PR.
|
||||
|
||||
## Powierzchnia poleceń
|
||||
|
||||
Każdy przepływ QA działa pod `pnpm openclaw qa <subcommand>`. Wiele z nich ma aliasy skryptów `pnpm qa:*`;
|
||||
Każdy przepływ QA działa pod `pnpm openclaw qa <subcommand>`. Wiele ma aliasy skryptów `pnpm qa:*`;
|
||||
obsługiwane są obie formy.
|
||||
|
||||
| Polecenie | Cel |
|
||||
| --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `qa run` | Wbudowany samotest QA; zapisuje raport Markdown. |
|
||||
| `qa suite` | Uruchom scenariusze oparte na repozytorium względem toru Gateway QA. Aliasy: `pnpm openclaw qa suite --runner multipass` dla jednorazowej VM z Linuksem. |
|
||||
| `qa coverage` | Wypisz markdownowy inwentarz pokrycia scenariuszy (`--json` dla wyjścia maszynowego). |
|
||||
| `qa parity-report` | Porównaj dwa pliki `qa-suite-summary.json` i zapisz agentowy raport parzystości. |
|
||||
| `qa character-eval` | Uruchom scenariusz QA postaci na wielu modelach live z ocenianym raportem. Zobacz [Raportowanie](#reporting). |
|
||||
| `qa manual` | Uruchom jednorazowy prompt względem wybranego toru providera/modelu. |
|
||||
| `qa ui` | Uruchom interfejs debuggera QA i lokalną magistralę QA (alias: `pnpm qa:lab:ui`). |
|
||||
| `qa docker-build-image` | Zbuduj wstępnie przygotowany obraz Docker QA. |
|
||||
| `qa docker-scaffold` | Zapisz szkielet docker-compose dla dashboardu QA + toru Gateway. |
|
||||
| `qa up` | Zbuduj witrynę QA, uruchom stos oparty na Dockerze, wypisz URL (alias: `pnpm qa:lab:up`; wariant `:fast` dodaje `--use-prebuilt-image --bind-ui-dist --skip-ui-build`). |
|
||||
| `qa aimock` | Uruchom tylko serwer providera AIMock. |
|
||||
| `qa mock-openai` | Uruchom tylko świadomy scenariuszy serwer providera `mock-openai`. |
|
||||
| `qa credentials doctor` / `add` / `list` / `remove` | Zarządzaj współdzieloną pulą poświadczeń Convex. |
|
||||
| `qa matrix` | Tor transportu live względem jednorazowego homeservera Tuwunel. Zobacz [Matrix QA](/pl/concepts/qa-matrix). |
|
||||
| `qa telegram` | Tor transportu live względem rzeczywistej prywatnej grupy Telegram. |
|
||||
| `qa discord` | Tor transportu live względem rzeczywistego prywatnego kanału gildii Discord. |
|
||||
| `qa slack` | Tor transportu live względem rzeczywistego prywatnego kanału Slack. |
|
||||
| `qa mantis` | Runner weryfikacji przed i po dla błędów transportu live, z dowodami w postaci reakcji statusowych Discord i smoke testem pulpitu/przeglądarki Crabbox. Zobacz [Mantis](/pl/concepts/mantis). |
|
||||
| Polecenie | Cel |
|
||||
| --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `qa run` | Wbudowany samosprawdzian QA; zapisuje raport Markdown. |
|
||||
| `qa suite` | Uruchom scenariusze oparte na repozytorium względem ścieżki Gateway QA. Aliasy: `pnpm openclaw qa suite --runner multipass` dla jednorazowej VM z Linuksem. |
|
||||
| `qa coverage` | Wypisz inwentarz pokrycia scenariuszy w markdown (`--json` dla wyjścia maszynowego). |
|
||||
| `qa parity-report` | Porównaj dwa pliki `qa-suite-summary.json` i zapisz agentowy raport parytetu. |
|
||||
| `qa character-eval` | Uruchom scenariusz QA postaci na wielu modelach live z ocenionym raportem. Zobacz [Raportowanie](#reporting). |
|
||||
| `qa manual` | Uruchom jednorazowy prompt względem wybranej ścieżki dostawcy/modelu. |
|
||||
| `qa ui` | Uruchom interfejs debuggera QA i lokalną magistralę QA (alias: `pnpm qa:lab:ui`). |
|
||||
| `qa docker-build-image` | Zbuduj wstępnie przygotowany obraz Docker QA. |
|
||||
| `qa docker-scaffold` | Zapisz szkielet docker-compose dla dashboardu QA + ścieżki Gateway. |
|
||||
| `qa up` | Zbuduj witrynę QA, uruchom stos oparty na Dockerze, wypisz URL (alias: `pnpm qa:lab:up`; wariant `:fast` dodaje `--use-prebuilt-image --bind-ui-dist --skip-ui-build`). |
|
||||
| `qa aimock` | Uruchom tylko serwer dostawcy AIMock. |
|
||||
| `qa mock-openai` | Uruchom tylko świadomy scenariuszy serwer dostawcy `mock-openai`. |
|
||||
| `qa credentials doctor` / `add` / `list` / `remove` | Zarządzaj współdzieloną pulą poświadczeń Convex. |
|
||||
| `qa matrix` | Ścieżka transportu live względem jednorazowego homeservera Tuwunel. Zobacz [Matrix QA](/pl/concepts/qa-matrix). |
|
||||
| `qa telegram` | Ścieżka transportu live względem prawdziwej prywatnej grupy Telegram. |
|
||||
| `qa discord` | Ścieżka transportu live względem prawdziwego prywatnego kanału gildii Discord. |
|
||||
| `qa slack` | Ścieżka transportu live względem prawdziwego prywatnego kanału Slack. |
|
||||
| `qa mantis` | Runner weryfikacji przed i po dla błędów transportu live, z dowodami reakcji statusowych Discord, smoke Crabbox desktop/browser i smoke Slack w VNC. Zobacz [Mantis](/pl/concepts/mantis). |
|
||||
|
||||
## Przepływ operatora
|
||||
|
||||
Obecny przepływ operatora QA to dwupanelowa witryna QA:
|
||||
|
||||
- Lewy panel: dashboard Gateway (Control UI) z agentem.
|
||||
- Prawy panel: QA Lab, pokazujący transkrypcję w stylu Slacka i plan scenariusza.
|
||||
- Po lewej: dashboard Gateway (Control UI) z agentem.
|
||||
- Po prawej: QA Lab, pokazujący transkrypcję w stylu Slack i plan scenariusza.
|
||||
|
||||
Uruchom go za pomocą:
|
||||
Uruchom ją przez:
|
||||
|
||||
```bash
|
||||
pnpm qa:lab:up
|
||||
```
|
||||
|
||||
To buduje witrynę QA, uruchamia tor Gateway oparty na Dockerze i udostępnia stronę
|
||||
QA Lab, na której operator lub pętla automatyzacji może przekazać agentowi misję QA,
|
||||
obserwować rzeczywiste zachowanie kanału oraz zapisywać, co zadziałało, co się nie powiodło lub
|
||||
pozostało zablokowane.
|
||||
To buduje witrynę QA, uruchamia ścieżkę Gateway opartą na Dockerze i udostępnia
|
||||
stronę QA Lab, gdzie operator lub pętla automatyzacji może przekazać agentowi
|
||||
misję QA, obserwować prawdziwe zachowanie kanału oraz zapisać, co zadziałało, co się
|
||||
nie powiodło albo pozostało zablokowane.
|
||||
|
||||
Aby szybciej iterować nad interfejsem QA Lab bez każdorazowego przebudowywania obrazu Docker,
|
||||
uruchom stos z podmontowanym przez bind bundlem QA Lab:
|
||||
Dla szybszej iteracji interfejsu QA Lab bez przebudowywania obrazu Docker za każdym razem
|
||||
uruchom stos z podmontowanym pakietem QA Lab:
|
||||
|
||||
```bash
|
||||
pnpm openclaw qa docker-build-image
|
||||
@ -85,39 +85,40 @@ pnpm qa:lab:up:fast
|
||||
pnpm qa:lab:watch
|
||||
```
|
||||
|
||||
`qa:lab:up:fast` utrzymuje usługi Docker na wstępnie zbudowanym obrazie i podmontowuje przez bind
|
||||
`qa:lab:up:fast` utrzymuje usługi Docker na wstępnie zbudowanym obrazie i montuje
|
||||
`extensions/qa-lab/web/dist` do kontenera `qa-lab`. `qa:lab:watch`
|
||||
przebudowuje ten bundle przy zmianie, a przeglądarka automatycznie przeładowuje się, gdy zmienia się hash zasobów QA Lab.
|
||||
przebudowuje ten pakiet po zmianie, a przeglądarka automatycznie przeładowuje się, gdy zmienia się hash
|
||||
zasobu QA Lab.
|
||||
|
||||
Aby wykonać lokalny smoke test śladu OpenTelemetry, uruchom:
|
||||
Dla lokalnego smoke śladu OpenTelemetry uruchom:
|
||||
|
||||
```bash
|
||||
pnpm qa:otel:smoke
|
||||
```
|
||||
|
||||
Ten skrypt uruchamia lokalny odbiornik śladów OTLP/HTTP, uruchamia scenariusz QA
|
||||
`otel-trace-smoke` z włączonym Pluginem `diagnostics-otel`, a następnie
|
||||
`otel-trace-smoke` z włączonym pluginem `diagnostics-otel`, następnie
|
||||
dekoduje wyeksportowane spany protobuf i sprawdza krytyczny dla wydania kształt:
|
||||
`openclaw.run`, `openclaw.harness.run`, `openclaw.model.call`,
|
||||
`openclaw.context.assembled` i `openclaw.message.delivery` muszą być obecne;
|
||||
wywołania modeli nie mogą eksportować `StreamAbandoned` przy udanych turach; surowe identyfikatory diagnostyczne i
|
||||
atrybuty `openclaw.content.*` muszą pozostać poza śladem. Zapisuje
|
||||
`otel-smoke-summary.json` obok artefaktów pakietu QA.
|
||||
`otel-smoke-summary.json` obok artefaktów zestawu QA.
|
||||
|
||||
QA obserwowalności pozostaje dostępne tylko z checkoutu źródeł. Paczka npm celowo pomija
|
||||
QA Lab, więc tory wydań pakietów Docker nie uruchamiają poleceń `qa`. Użyj
|
||||
`pnpm qa:otel:smoke` ze zbudowanego checkoutu źródeł podczas zmieniania instrumentacji
|
||||
QA obserwowalności pozostaje wyłącznie dla checkoutu źródeł. Tarball npm celowo pomija
|
||||
QA Lab, więc ścieżki wydania Docker pakietu nie uruchamiają poleceń `qa`. Używaj
|
||||
`pnpm qa:otel:smoke` ze zbudowanego checkoutu źródeł przy zmianach instrumentacji
|
||||
diagnostycznej.
|
||||
|
||||
Aby uruchomić tor smoke Matrix z rzeczywistym transportem, użyj:
|
||||
Dla ścieżki smoke Matrix z prawdziwym transportem uruchom:
|
||||
|
||||
```bash
|
||||
pnpm openclaw qa matrix --profile fast --fail-fast
|
||||
```
|
||||
|
||||
Pełna dokumentacja CLI, katalog profili/scenariuszy, zmienne środowiskowe i układ artefaktów dla tego toru znajdują się w [Matrix QA](/pl/concepts/qa-matrix). W skrócie: provisionuje jednorazowy homeserver Tuwunel w Dockerze, rejestruje tymczasowych użytkowników driver/SUT/observer, uruchamia rzeczywisty Plugin Matrix wewnątrz podrzędnego Gateway QA ograniczonego do tego transportu (bez `qa-channel`), a następnie zapisuje raport Markdown, podsumowanie JSON, artefakt obserwowanych zdarzeń i połączony log wyjścia w `.artifacts/qa-e2e/matrix-<timestamp>/`.
|
||||
Pełna dokumentacja CLI, katalog profili/scenariuszy, zmienne env i układ artefaktów dla tej ścieżki znajdują się w [Matrix QA](/pl/concepts/qa-matrix). W skrócie: aprowizuje jednorazowy homeserver Tuwunel w Dockerze, rejestruje tymczasowych użytkowników driver/SUT/observer, uruchamia prawdziwy Plugin Matrix w podrzędnym Gateway QA ograniczonym do tego transportu (bez `qa-channel`), a następnie zapisuje raport Markdown, podsumowanie JSON, artefakt zaobserwowanych zdarzeń i połączony dziennik wyjściowy w `.artifacts/qa-e2e/matrix-<timestamp>/`.
|
||||
|
||||
Dla torów smoke Telegram, Discord i Slack z rzeczywistym transportem:
|
||||
Dla ścieżek smoke Telegram, Discord i Slack z prawdziwym transportem:
|
||||
|
||||
```bash
|
||||
pnpm openclaw qa telegram
|
||||
@ -125,7 +126,24 @@ pnpm openclaw qa discord
|
||||
pnpm openclaw qa slack
|
||||
```
|
||||
|
||||
Celują one w istniejący wcześniej rzeczywisty kanał z dwoma botami (driver + SUT). Wymagane zmienne środowiskowe, listy scenariuszy, artefakty wyjściowe i pula poświadczeń Convex są udokumentowane poniżej w [Dokumentacja QA Telegram, Discord i Slack](#telegram-discord-and-slack-qa-reference).
|
||||
Celują one w istniejący wcześniej prawdziwy kanał z dwoma botami (driver + SUT). Wymagane zmienne env, listy scenariuszy, artefakty wyjściowe i pula poświadczeń Convex są udokumentowane w [Dokumentacji QA Telegram, Discord i Slack](#telegram-discord-and-slack-qa-reference) poniżej.
|
||||
|
||||
Dla pełnego uruchomienia desktopowej VM Slack z ratunkowym VNC uruchom:
|
||||
|
||||
```bash
|
||||
pnpm openclaw qa mantis slack-desktop-smoke \
|
||||
--gateway-setup \
|
||||
--scenario slack-canary \
|
||||
--keep-lease
|
||||
```
|
||||
|
||||
To polecenie dzierżawi maszynę desktop/browser Crabbox, uruchamia ścieżkę live Slack
|
||||
wewnątrz VM, otwiera Slack Web w przeglądarce VNC, przechwytuje pulpit i
|
||||
kopiuje `slack-qa/` oraz `slack-desktop-smoke.png` z powrotem do katalogu artefaktów
|
||||
Mantis. Użyj ponownie `--lease-id <cbx_...>` po ręcznym zalogowaniu do Slack Web
|
||||
przez VNC. Z `--gateway-setup` Mantis pozostawia trwały Gateway Slack OpenClaw
|
||||
działający wewnątrz VM na porcie `38973`; bez tego polecenie uruchamia
|
||||
normalną ścieżkę QA Slack bot-do-bota i kończy po przechwyceniu artefaktów.
|
||||
|
||||
Przed użyciem poświadczeń live z puli uruchom:
|
||||
|
||||
@ -133,64 +151,65 @@ Przed użyciem poświadczeń live z puli uruchom:
|
||||
pnpm openclaw qa credentials doctor
|
||||
```
|
||||
|
||||
Doctor sprawdza środowisko brokera Convex, weryfikuje ustawienia endpointów i sprawdza osiągalność admin/list, gdy sekret maintenera jest obecny. Raportuje tylko status ustawione/brakujące dla sekretów.
|
||||
Doctor sprawdza env brokera Convex, waliduje ustawienia endpointu i weryfikuje osiągalność admin/list, gdy obecny jest sekret maintenera. Raportuje tylko status ustawione/brakujące dla sekretów.
|
||||
|
||||
## Pokrycie transportu live
|
||||
|
||||
Tory transportu live współdzielą jeden kontrakt zamiast wymyślać własny kształt listy scenariuszy. `qa-channel` to szeroki syntetyczny pakiet zachowań produktu i nie jest częścią macierzy pokrycia transportu live.
|
||||
Ścieżki transportu live współdzielą jeden kontrakt zamiast tworzyć własny kształt listy scenariuszy. `qa-channel` to szeroki syntetyczny zestaw zachowań produktu i nie jest częścią macierzy pokrycia transportu live.
|
||||
|
||||
| Tor | Canary | Bramkowanie wzmianek | Bot-do-bota | Blokada allowlisty | Odpowiedź najwyższego poziomu | Wznowienie po restarcie | Kontynuacja wątku | Izolacja wątku | Obserwacja reakcji | Polecenie pomocy | Rejestracja natywnego polecenia |
|
||||
| -------- | ------ | -------------------- | ----------- | ------------------ | ----------------------------- | ----------------------- | ----------------- | -------------- | ------------------ | ---------------- | ------------------------------- |
|
||||
| Matrix | x | x | x | x | x | x | x | x | x | | |
|
||||
| Telegram | x | x | x | | | | | | | x | |
|
||||
| Discord | x | x | x | | | | | | | | x |
|
||||
| Slack | x | x | x | | | | | | | | |
|
||||
| Ścieżka | Canary | Bramka wzmianki | Bot-do-bota | Blokada allowlist | Odpowiedź najwyższego poziomu | Wznowienie po restarcie | Kontynuacja wątku | Izolacja wątku | Obserwacja reakcji | Polecenie pomocy | Rejestracja natywnego polecenia |
|
||||
| -------- | ------ | --------------- | ----------- | ----------------- | ----------------------------- | ----------------------- | ----------------- | -------------- | ------------------ | ---------------- | -------------------------------- |
|
||||
| Matrix | x | x | x | x | x | x | x | x | x | | |
|
||||
| Telegram | x | x | x | | | | | | | x | |
|
||||
| Discord | x | x | x | | | | | | | | x |
|
||||
| Slack | x | x | x | | | | | | | | |
|
||||
|
||||
To utrzymuje `qa-channel` jako szeroki pakiet zachowań produktu, podczas gdy Matrix,
|
||||
Telegram i przyszłe transporty live współdzielą jedną jawną listę kontrolną kontraktu transportu.
|
||||
To utrzymuje `qa-channel` jako szeroki zestaw zachowań produktu, podczas gdy Matrix,
|
||||
Telegram i przyszłe transporty live współdzielą jedną wyraźną checklistę kontraktu
|
||||
transportu.
|
||||
|
||||
Aby uruchomić jednorazowy tor VM z Linuksem bez wprowadzania Dockera do ścieżki QA, użyj:
|
||||
Dla jednorazowej ścieżki VM z Linuksem bez wprowadzania Dockera do ścieżki QA uruchom:
|
||||
|
||||
```bash
|
||||
pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline
|
||||
```
|
||||
|
||||
To uruchamia świeżego gościa Multipass, instaluje zależności, buduje OpenClaw
|
||||
wewnątrz gościa, uruchamia `qa suite`, a następnie kopiuje normalny raport QA i
|
||||
Uruchamia świeżego gościa Multipass, instaluje zależności, buduje OpenClaw
|
||||
wewnątrz gościa, uruchamia `qa suite`, a następnie kopiuje standardowy raport QA i
|
||||
podsumowanie z powrotem do `.artifacts/qa-e2e/...` na hoście.
|
||||
Wykorzystuje to samo zachowanie wyboru scenariuszy co `qa suite` na hoście.
|
||||
Uruchomienia pakietu na hoście i w Multipass domyślnie wykonują wiele wybranych scenariuszy równolegle
|
||||
Używa tego samego zachowania wyboru scenariuszy co `qa suite` na hoście.
|
||||
Uruchomienia zestawu na hoście i w Multipass domyślnie wykonują wiele wybranych scenariuszy równolegle
|
||||
z izolowanymi workerami Gateway. `qa-channel` domyślnie używa współbieżności
|
||||
4, ograniczonej liczbą wybranych scenariuszy. Użyj `--concurrency <count>`, aby dostroić
|
||||
liczbę workerów, albo `--concurrency 1` dla wykonania szeregowego.
|
||||
Polecenie kończy się kodem niezerowym, gdy jakikolwiek scenariusz się nie powiedzie. Użyj `--allow-failures`, gdy
|
||||
chcesz uzyskać artefakty bez błędnego kodu wyjścia.
|
||||
liczbę workerów, albo `--concurrency 1` do wykonania szeregowego.
|
||||
Polecenie kończy się kodem niezerowym, gdy którykolwiek scenariusz się nie powiedzie. Użyj `--allow-failures`, gdy
|
||||
chcesz uzyskać artefakty bez kodu wyjścia oznaczającego błąd.
|
||||
Uruchomienia live przekazują obsługiwane wejścia uwierzytelniania QA, które są praktyczne dla
|
||||
gościa: klucze providerów oparte na env, ścieżkę konfiguracji providera QA live oraz
|
||||
`CODEX_HOME`, gdy jest obecne. Trzymaj `--output-dir` pod katalogiem głównym repozytorium, aby gość
|
||||
mógł zapisywać z powrotem przez podmontowany workspace.
|
||||
gościa: klucze dostawców oparte na env, ścieżkę konfiguracji dostawcy QA live oraz
|
||||
`CODEX_HOME`, gdy jest obecne. Trzymaj `--output-dir` pod katalogiem głównym repo, aby gość
|
||||
mógł zapisywać z powrotem przez zamontowany workspace.
|
||||
|
||||
## Dokumentacja QA Telegram, Discord i Slack
|
||||
## Dokumentacja QA dla Telegram, Discord i Slack
|
||||
|
||||
Matrix ma [dedykowaną stronę](/pl/concepts/qa-matrix) ze względu na liczbę scenariuszy i provisionowanie homeservera oparte na Dockerze. Telegram, Discord i Slack są mniejsze — po kilka scenariuszy każdy, bez systemu profili, względem istniejących wcześniej rzeczywistych kanałów — dlatego ich dokumentacja znajduje się tutaj.
|
||||
Matrix ma [dedykowaną stronę](/pl/concepts/qa-matrix) ze względu na liczbę scenariuszy i provisionowanie homeservera oparte na Dockerze. Telegram, Discord i Slack są mniejsze — po kilka scenariuszy każdy, bez systemu profili, wobec istniejących wcześniej prawdziwych kanałów — więc ich dokumentacja znajduje się tutaj.
|
||||
|
||||
### Wspólne flagi CLI
|
||||
|
||||
Te tory rejestrują się przez `extensions/qa-lab/src/live-transports/shared/live-transport-cli.ts` i akceptują te same flagi:
|
||||
Te ścieżki rejestrują się przez `extensions/qa-lab/src/live-transports/shared/live-transport-cli.ts` i akceptują te same flagi:
|
||||
|
||||
| Flaga | Domyślnie | Opis |
|
||||
| ------------------------------------- | --------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `--scenario <id>` | — | Uruchom tylko ten scenariusz. Można powtarzać. |
|
||||
| `--output-dir <path>` | `<repo>/.artifacts/qa-e2e/{telegram,discord,slack}-<timestamp>` | Miejsce zapisu raportów/podsumowania/zaobserwowanych wiadomości oraz dziennika wyjściowego. Ścieżki względne są rozwiązywane względem `--repo-root`. |
|
||||
| `--repo-root <path>` | `process.cwd()` | Katalog główny repozytorium przy wywołaniu z neutralnego cwd. |
|
||||
| `--sut-account <id>` | `sut` | Tymczasowy identyfikator konta w konfiguracji Gateway QA. |
|
||||
| `--provider-mode <mode>` | `live-frontier` | `mock-openai` albo `live-frontier` (starsze `live-openai` nadal działa). |
|
||||
| `--model <ref>` / `--alt-model <ref>` | domyślne ustawienie dostawcy | Referencje modelu podstawowego/alternatywnego. |
|
||||
| `--fast` | wyłączone | Tryb szybki dostawcy tam, gdzie jest obsługiwany. |
|
||||
| `--credential-source <env\|convex>` | `env` | Zobacz [pulę poświadczeń Convex](#convex-credential-pool). |
|
||||
| `--credential-role <maintainer\|ci>` | `ci` w CI, w przeciwnym razie `maintainer` | Rola używana, gdy `--credential-source convex`. |
|
||||
| Flaga | Domyślnie | Opis |
|
||||
| ------------------------------------- | -------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
|
||||
| `--scenario <id>` | — | Uruchom tylko ten scenariusz. Można powtarzać. |
|
||||
| `--output-dir <path>` | `<repo>/.artifacts/qa-e2e/{telegram,discord,slack}-<timestamp>` | Miejsce zapisu raportów/podsumowania/zaobserwowanych wiadomości i logu wyjściowego. Ścieżki względne są rozwiązywane względem `--repo-root`. |
|
||||
| `--repo-root <path>` | `process.cwd()` | Katalog główny repozytorium przy wywołaniu z neutralnego cwd. |
|
||||
| `--sut-account <id>` | `sut` | Tymczasowy identyfikator konta w konfiguracji QA Gateway. |
|
||||
| `--provider-mode <mode>` | `live-frontier` | `mock-openai` albo `live-frontier` (starsze `live-openai` nadal działa). |
|
||||
| `--model <ref>` / `--alt-model <ref>` | domyślne dostawcy | Referencje modelu podstawowego/alternatywnego. |
|
||||
| `--fast` | wyłączone | Tryb szybki dostawcy tam, gdzie jest obsługiwany. |
|
||||
| `--credential-source <env\|convex>` | `env` | Zobacz [Pula poświadczeń Convex](#convex-credential-pool). |
|
||||
| `--credential-role <maintainer\|ci>` | `ci` w CI, w przeciwnym razie `maintainer` | Rola używana, gdy `--credential-source convex`. |
|
||||
|
||||
Każda ścieżka kończy działanie kodem różnym od zera przy dowolnym nieudanym scenariuszu. `--allow-failures` zapisuje artefakty bez ustawiania kodu wyjścia oznaczającego błąd.
|
||||
Każda ścieżka kończy się kodem niezerowym przy dowolnym nieudanym scenariuszu. `--allow-failures` zapisuje artefakty bez ustawiania kodu wyjścia oznaczającego błąd.
|
||||
|
||||
### QA Telegram
|
||||
|
||||
@ -198,15 +217,15 @@ Każda ścieżka kończy działanie kodem różnym od zera przy dowolnym nieudan
|
||||
pnpm openclaw qa telegram
|
||||
```
|
||||
|
||||
Celuje w jedną rzeczywistą prywatną grupę Telegram z dwoma różnymi botami (sterownik + SUT). Bot SUT musi mieć nazwę użytkownika Telegram; obserwacja bot-do-bota działa najlepiej, gdy oba boty mają włączony **Bot-to-Bot Communication Mode** w `@BotFather`.
|
||||
Celuje w jedną prawdziwą prywatną grupę Telegram z dwoma różnymi botami (driver + SUT). Bot SUT musi mieć nazwę użytkownika Telegram; obserwacja bot-bot działa najlepiej, gdy oba boty mają włączony **Bot-to-Bot Communication Mode** w `@BotFather`.
|
||||
|
||||
Wymagane zmienne środowiskowe, gdy `--credential-source env`:
|
||||
Wymagane env, gdy `--credential-source env`:
|
||||
|
||||
- `OPENCLAW_QA_TELEGRAM_GROUP_ID` — numeryczny identyfikator czatu (ciąg znaków).
|
||||
- `OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN`
|
||||
- `OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN`
|
||||
|
||||
Opcjonalnie:
|
||||
Opcjonalne:
|
||||
|
||||
- `OPENCLAW_QA_TELEGRAM_CAPTURE_CONTENT=1` zachowuje treść wiadomości w artefaktach zaobserwowanych wiadomości (domyślnie redaguje).
|
||||
|
||||
@ -224,8 +243,8 @@ Scenariusze (`extensions/qa-lab/src/live-transports/telegram/telegram-live.runti
|
||||
Artefakty wyjściowe:
|
||||
|
||||
- `telegram-qa-report.md`
|
||||
- `telegram-qa-summary.json` — zawiera RTT dla każdej odpowiedzi (wysłanie przez sterownik → zaobserwowana odpowiedź SUT), zaczynając od canary.
|
||||
- `telegram-qa-observed-messages.json` — treści są redagowane, chyba że `OPENCLAW_QA_TELEGRAM_CAPTURE_CONTENT=1`.
|
||||
- `telegram-qa-summary.json` — zawiera RTT dla każdej odpowiedzi (wysłanie drivera → zaobserwowana odpowiedź SUT), zaczynając od canary.
|
||||
- `telegram-qa-observed-messages.json` — treści redagowane, chyba że `OPENCLAW_QA_TELEGRAM_CAPTURE_CONTENT=1`.
|
||||
|
||||
### QA Discord
|
||||
|
||||
@ -233,17 +252,17 @@ Artefakty wyjściowe:
|
||||
pnpm openclaw qa discord
|
||||
```
|
||||
|
||||
Celuje w jeden rzeczywisty prywatny kanał gildii Discord z dwoma botami: botem sterownika kontrolowanym przez harness oraz botem SUT uruchamianym przez podrzędny OpenClaw Gateway za pośrednictwem dołączonego Plugin Discord. Weryfikuje obsługę wzmianki kanału, to, że bot SUT zarejestrował natywne polecenie `/help` w Discord, oraz scenariusze dowodowe Mantis wymagające świadomego włączenia.
|
||||
Celuje w jeden prawdziwy prywatny kanał gildii Discord z dwoma botami: botem drivera kontrolowanym przez harness oraz botem SUT uruchamianym przez podrzędny OpenClaw Gateway przez dołączony Plugin Discord. Weryfikuje obsługę wzmianek kanału, to, że bot SUT zarejestrował natywne polecenie `/help` w Discord, oraz opcjonalne scenariusze dowodowe Mantis.
|
||||
|
||||
Wymagane zmienne środowiskowe, gdy `--credential-source env`:
|
||||
Wymagane env, gdy `--credential-source env`:
|
||||
|
||||
- `OPENCLAW_QA_DISCORD_GUILD_ID`
|
||||
- `OPENCLAW_QA_DISCORD_CHANNEL_ID`
|
||||
- `OPENCLAW_QA_DISCORD_DRIVER_BOT_TOKEN`
|
||||
- `OPENCLAW_QA_DISCORD_SUT_BOT_TOKEN`
|
||||
- `OPENCLAW_QA_DISCORD_SUT_APPLICATION_ID` — musi odpowiadać identyfikatorowi użytkownika bota SUT zwróconemu przez Discord (w przeciwnym razie ścieżka szybko kończy się niepowodzeniem).
|
||||
- `OPENCLAW_QA_DISCORD_SUT_APPLICATION_ID` — musi pasować do identyfikatora użytkownika bota SUT zwróconego przez Discord (w przeciwnym razie ścieżka szybko kończy się błędem).
|
||||
|
||||
Opcjonalnie:
|
||||
Opcjonalne:
|
||||
|
||||
- `OPENCLAW_QA_DISCORD_CAPTURE_CONTENT=1` zachowuje treść wiadomości w artefaktach zaobserwowanych wiadomości.
|
||||
|
||||
@ -252,9 +271,9 @@ Scenariusze (`extensions/qa-lab/src/live-transports/discord/discord-live.runtime
|
||||
- `discord-canary`
|
||||
- `discord-mention-gating`
|
||||
- `discord-native-help-command-registration`
|
||||
- `discord-status-reactions-tool-only` — scenariusz Mantis wymagający świadomego włączenia. Uruchamia się samodzielnie, ponieważ przełącza SUT na stale włączone odpowiedzi gildii wyłącznie narzędziowe z `messages.statusReactions.enabled=true`, a następnie przechwytuje oś czasu reakcji REST oraz artefakt wizualny HTML/PNG.
|
||||
- `discord-status-reactions-tool-only` — opcjonalny scenariusz Mantis. Działa samodzielnie, ponieważ przełącza SUT na zawsze włączone odpowiedzi gildii wyłącznie narzędziowe z `messages.statusReactions.enabled=true`, a następnie przechwytuje oś czasu reakcji REST oraz artefakt wizualny HTML/PNG.
|
||||
|
||||
Jawne uruchomienie scenariusza reakcji statusu Mantis:
|
||||
Uruchom scenariusz reakcji statusu Mantis jawnie:
|
||||
|
||||
```bash
|
||||
pnpm openclaw qa discord \
|
||||
@ -269,8 +288,8 @@ Artefakty wyjściowe:
|
||||
|
||||
- `discord-qa-report.md`
|
||||
- `discord-qa-summary.json`
|
||||
- `discord-qa-observed-messages.json` — treści są redagowane, chyba że `OPENCLAW_QA_DISCORD_CAPTURE_CONTENT=1`.
|
||||
- `discord-qa-reaction-timelines.json` i `discord-status-reactions-tool-only-timeline.png`, gdy działa scenariusz reakcji statusu.
|
||||
- `discord-qa-observed-messages.json` — treści redagowane, chyba że `OPENCLAW_QA_DISCORD_CAPTURE_CONTENT=1`.
|
||||
- `discord-qa-reaction-timelines.json` i `discord-status-reactions-tool-only-timeline.png`, gdy uruchamiany jest scenariusz reakcji statusu.
|
||||
|
||||
### QA Slack
|
||||
|
||||
@ -278,16 +297,16 @@ Artefakty wyjściowe:
|
||||
pnpm openclaw qa slack
|
||||
```
|
||||
|
||||
Celuje w jeden rzeczywisty prywatny kanał Slack z dwoma różnymi botami: botem sterownika kontrolowanym przez harness oraz botem SUT uruchamianym przez podrzędny OpenClaw Gateway za pośrednictwem dołączonego Plugin Slack.
|
||||
Celuje w jeden prawdziwy prywatny kanał Slack z dwoma różnymi botami: botem drivera kontrolowanym przez harness oraz botem SUT uruchamianym przez podrzędny OpenClaw Gateway przez dołączony Plugin Slack.
|
||||
|
||||
Wymagane zmienne środowiskowe, gdy `--credential-source env`:
|
||||
Wymagane env, gdy `--credential-source env`:
|
||||
|
||||
- `OPENCLAW_QA_SLACK_CHANNEL_ID`
|
||||
- `OPENCLAW_QA_SLACK_DRIVER_BOT_TOKEN`
|
||||
- `OPENCLAW_QA_SLACK_SUT_BOT_TOKEN`
|
||||
- `OPENCLAW_QA_SLACK_SUT_APP_TOKEN`
|
||||
|
||||
Opcjonalnie:
|
||||
Opcjonalne:
|
||||
|
||||
- `OPENCLAW_QA_SLACK_CAPTURE_CONTENT=1` zachowuje treść wiadomości w artefaktach zaobserwowanych wiadomości.
|
||||
|
||||
@ -300,85 +319,85 @@ Artefakty wyjściowe:
|
||||
|
||||
- `slack-qa-report.md`
|
||||
- `slack-qa-summary.json`
|
||||
- `slack-qa-observed-messages.json` — treści są redagowane, chyba że `OPENCLAW_QA_SLACK_CAPTURE_CONTENT=1`.
|
||||
- `slack-qa-observed-messages.json` — treści redagowane, chyba że `OPENCLAW_QA_SLACK_CAPTURE_CONTENT=1`.
|
||||
|
||||
### Pula poświadczeń Convex
|
||||
|
||||
Ścieżki Telegram, Discord i Slack mogą dzierżawić poświadczenia ze współdzielonej puli Convex zamiast odczytywać powyższe zmienne środowiskowe. Przekaż `--credential-source convex` (albo ustaw `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`); QA Lab uzyskuje wyłączną dzierżawę, wysyła jej Heartbeat przez czas trwania uruchomienia i zwalnia ją przy zamykaniu. Rodzaje puli to `"telegram"`, `"discord"` i `"slack"`.
|
||||
Ścieżki Telegram, Discord i Slack mogą dzierżawić poświadczenia ze współdzielonej puli Convex zamiast odczytywać powyższe zmienne env. Przekaż `--credential-source convex` (albo ustaw `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`); QA Lab uzyskuje wyłączną dzierżawę, wysyła Heartbeat przez czas trwania uruchomienia i zwalnia ją przy zamykaniu. Rodzaje puli to `"telegram"`, `"discord"` i `"slack"`.
|
||||
|
||||
Kształty payloadu walidowane przez broker w `admin/add`:
|
||||
Kształty payloadów, które broker waliduje przy `admin/add`:
|
||||
|
||||
- Telegram (`kind: "telegram"`): `{ groupId: string, driverToken: string, sutToken: string }` — `groupId` musi być numerycznym ciągiem identyfikatora czatu.
|
||||
- Telegram (`kind: "telegram"`): `{ groupId: string, driverToken: string, sutToken: string }` — `groupId` musi być numerycznym ciągiem chat-id.
|
||||
- Discord (`kind: "discord"`): `{ guildId: string, channelId: string, driverBotToken: string, sutBotToken: string, sutApplicationId: string }`.
|
||||
|
||||
Operacyjne zmienne środowiskowe i kontrakt punktu końcowego brokera Convex znajdują się w [Testowanie → Współdzielone poświadczenia Telegram przez Convex](/pl/help/testing#shared-telegram-credentials-via-convex-v1) (nazwa sekcji jest starsza niż obsługa Discord; semantyka brokera jest identyczna dla obu rodzajów).
|
||||
Operacyjne zmienne env i kontrakt endpointu brokera Convex znajdują się w [Testowanie → Współdzielone poświadczenia Telegram przez Convex](/pl/help/testing#shared-telegram-credentials-via-convex-v1) (nazwa sekcji poprzedza obsługę Discord; semantyka brokera jest identyczna dla obu rodzajów).
|
||||
|
||||
## Seedy oparte na repozytorium
|
||||
## Seedy oparte na repo
|
||||
|
||||
Zasoby seedów znajdują się w `qa/`:
|
||||
|
||||
- `qa/scenarios/index.md`
|
||||
- `qa/scenarios/<theme>/*.md`
|
||||
|
||||
Są celowo przechowywane w git, aby plan QA był widoczny zarówno dla ludzi, jak i dla
|
||||
Są celowo trzymane w git, aby plan QA był widoczny zarówno dla ludzi, jak i dla
|
||||
agenta.
|
||||
|
||||
`qa-lab` powinien pozostać ogólnym runnerem markdown. Każdy plik markdown scenariusza jest
|
||||
`qa-lab` powinien pozostać generycznym runnerem markdown. Każdy plik markdown scenariusza jest
|
||||
źródłem prawdy dla jednego uruchomienia testu i powinien definiować:
|
||||
|
||||
- metadane scenariusza
|
||||
- opcjonalne metadane kategorii, capability, ścieżki i ryzyka
|
||||
- odwołania do dokumentacji i kodu
|
||||
- referencje dokumentacji i kodu
|
||||
- opcjonalne wymagania Plugin
|
||||
- opcjonalną łatkę konfiguracji Gateway
|
||||
- opcjonalną poprawkę konfiguracji Gateway
|
||||
- wykonywalny `qa-flow`
|
||||
|
||||
Wielokrotnego użycia powierzchnia runtime obsługująca `qa-flow` może pozostać ogólna
|
||||
i przekrojowa. Na przykład scenariusze markdown mogą łączyć helpery po stronie transportu
|
||||
z helperami po stronie przeglądarki, które sterują osadzonym Control UI przez
|
||||
seam Gateway `browser.request` bez dodawania runnera dla specjalnego przypadku.
|
||||
Wielokrotnego użytku powierzchnia runtime, która obsługuje `qa-flow`, może pozostać generyczna
|
||||
i przekrojowa. Na przykład scenariusze markdown mogą łączyć pomocniki po stronie transportu
|
||||
z pomocnikami po stronie przeglądarki, które sterują osadzonym Control UI przez
|
||||
seam Gateway `browser.request`, bez dodawania runnera do przypadku szczególnego.
|
||||
|
||||
Pliki scenariuszy powinny być grupowane według capability produktu, a nie według folderu
|
||||
drzewa źródeł. Utrzymuj stabilne identyfikatory scenariuszy przy przenoszeniu plików; używaj `docsRefs` i `codeRefs`
|
||||
Pliki scenariuszy powinny być grupowane według capability produktu, a nie folderu
|
||||
drzewa źródłowego. Utrzymuj stabilne identyfikatory scenariuszy, gdy pliki są przenoszone; używaj `docsRefs` i `codeRefs`
|
||||
do śledzenia implementacji.
|
||||
|
||||
Lista bazowa powinna pozostać wystarczająco szeroka, aby obejmować:
|
||||
|
||||
- czat DM i kanałowy
|
||||
- zachowanie wątku
|
||||
- DM i czat kanału
|
||||
- zachowanie wątków
|
||||
- cykl życia akcji wiadomości
|
||||
- callbacki cron
|
||||
- przypominanie z pamięci
|
||||
- przywoływanie pamięci
|
||||
- przełączanie modeli
|
||||
- przekazanie do subagenta
|
||||
- czytanie repozytorium i dokumentacji
|
||||
- jedno małe zadanie kompilacji, takie jak Lobster Invaders
|
||||
- przekazanie subagentowi
|
||||
- czytanie repo i czytanie dokumentacji
|
||||
- jedno małe zadanie build, takie jak Lobster Invaders
|
||||
|
||||
## Ścieżki mock dostawcy
|
||||
## Ścieżki mock dostawców
|
||||
|
||||
`qa suite` ma dwie lokalne ścieżki mock dostawcy:
|
||||
`qa suite` ma dwie lokalne ścieżki mock dostawców:
|
||||
|
||||
- `mock-openai` to świadomy scenariuszy mock OpenClaw. Pozostaje domyślną
|
||||
deterministyczną ścieżką mock dla QA opartego na repozytorium i bramek parytetu.
|
||||
- `aimock` uruchamia serwer dostawcy oparty na AIMock dla eksperymentalnego protokołu,
|
||||
fixture, record/replay i pokrycia chaos. Jest addytywny i nie zastępuje
|
||||
dyspozytora scenariuszy `mock-openai`.
|
||||
deterministyczną ścieżką mock dla QA opartego na repo i bramek parzystości.
|
||||
- `aimock` uruchamia serwer dostawcy oparty na AIMock dla eksperymentalnego pokrycia protokołu,
|
||||
fixture, record/replay i chaos. Jest addytywny i nie
|
||||
zastępuje dyspozytora scenariuszy `mock-openai`.
|
||||
|
||||
Implementacja ścieżek dostawcy znajduje się pod `extensions/qa-lab/src/providers/`.
|
||||
Każdy dostawca jest właścicielem swoich wartości domyślnych, uruchamiania lokalnego serwera, konfiguracji modelu Gateway,
|
||||
potrzeb stagingu profilu uwierzytelniania oraz flag capability live/mock. Wspólny kod suite i
|
||||
Gateway powinien kierować przez rejestr dostawców zamiast rozgałęziać się według
|
||||
nazw dostawców.
|
||||
Implementacja ścieżek dostawców znajduje się pod `extensions/qa-lab/src/providers/`.
|
||||
Każdy dostawca posiada swoje wartości domyślne, uruchamianie lokalnego serwera, konfigurację modelu Gateway,
|
||||
potrzeby przygotowania profilu uwierzytelniania oraz flagi capability live/mock. Współdzielony zestaw i
|
||||
kod Gateway powinny routować przez rejestr dostawców zamiast rozgałęziać się po
|
||||
nazwach dostawców.
|
||||
|
||||
## Adaptery transportu
|
||||
|
||||
`qa-lab` jest właścicielem ogólnego seam transportu dla scenariuszy QA markdown. `qa-channel` jest pierwszym adapterem na tym seam, ale cel projektowy jest szerszy: przyszłe rzeczywiste lub syntetyczne kanały powinny wpinać się do tego samego runnera suite zamiast dodawać runner QA specyficzny dla transportu.
|
||||
`qa-lab` posiada generyczny seam transportu dla scenariuszy QA markdown. `qa-channel` jest pierwszym adapterem na tym seamie, ale cel projektowy jest szerszy: przyszłe kanały prawdziwe lub syntetyczne powinny wpinać się do tego samego runnera zestawu zamiast dodawać runner QA specyficzny dla transportu.
|
||||
|
||||
Na poziomie architektury podział jest następujący:
|
||||
|
||||
- `qa-lab` jest właścicielem ogólnego wykonywania scenariuszy, współbieżności workerów, zapisu artefaktów i raportowania.
|
||||
- Adapter transportu jest właścicielem konfiguracji Gateway, gotowości, obserwacji przychodzącej i wychodzącej, akcji transportu oraz znormalizowanego stanu transportu.
|
||||
- Pliki scenariuszy markdown pod `qa/scenarios/` definiują uruchomienie testu; `qa-lab` udostępnia wielokrotnego użycia powierzchnię runtime, która je wykonuje.
|
||||
- `qa-lab` odpowiada za generyczne wykonywanie scenariuszy, współbieżność workerów, zapisywanie artefaktów i raportowanie.
|
||||
- Adapter transportu odpowiada za konfigurację Gateway, gotowość, obserwację wejściową i wyjściową, akcje transportu oraz znormalizowany stan transportu.
|
||||
- Pliki scenariuszy markdown pod `qa/scenarios/` definiują uruchomienie testu; `qa-lab` zapewnia wielokrotnego użytku powierzchnię runtime, która je wykonuje.
|
||||
|
||||
### Dodawanie kanału
|
||||
|
||||
@ -387,45 +406,45 @@ Dodanie kanału do systemu QA markdown wymaga dokładnie dwóch rzeczy:
|
||||
1. Adaptera transportu dla kanału.
|
||||
2. Pakietu scenariuszy, który sprawdza kontrakt kanału.
|
||||
|
||||
Nie dodawaj nowego głównego korzenia poleceń QA najwyższego poziomu, gdy współdzielony host `qa-lab` może być właścicielem przepływu.
|
||||
Nie dodawaj nowego katalogu głównego poleceń QA najwyższego poziomu, gdy współdzielony host `qa-lab` może być właścicielem przepływu.
|
||||
|
||||
`qa-lab` jest właścicielem współdzielonej mechaniki hosta:
|
||||
`qa-lab` odpowiada za współdzieloną mechanikę hosta:
|
||||
|
||||
- korzenia poleceń `openclaw qa`
|
||||
- uruchamiania i zamykania suite
|
||||
- współbieżności workerów
|
||||
- zapisu artefaktów
|
||||
- generowania raportów
|
||||
- wykonywania scenariuszy
|
||||
- aliasów zgodności dla starszych scenariuszy `qa-channel`
|
||||
- korzeń polecenia `openclaw qa`
|
||||
- uruchamianie i zamykanie zestawu
|
||||
- współbieżność workerów
|
||||
- zapisywanie artefaktów
|
||||
- generowanie raportów
|
||||
- wykonywanie scenariuszy
|
||||
- aliasy zgodności dla starszych scenariuszy `qa-channel`
|
||||
|
||||
Plugin runnera są właścicielami kontraktu transportu:
|
||||
Pluginy runnerów odpowiadają za kontrakt transportu:
|
||||
|
||||
- sposobu montowania `openclaw qa <runner>` pod współdzielonym korzeniem `qa`
|
||||
- sposobu konfigurowania Gateway dla tego transportu
|
||||
- sposobu sprawdzania gotowości
|
||||
- sposobu wstrzykiwania zdarzeń przychodzących
|
||||
- sposobu obserwowania wiadomości wychodzących
|
||||
- sposobu udostępniania transkryptów i znormalizowanego stanu transportu
|
||||
- sposobu wykonywania akcji opartych na transporcie
|
||||
- sposobu obsługi resetu lub czyszczenia specyficznego dla transportu
|
||||
- sposób montowania `openclaw qa <runner>` pod współdzielonym korzeniem `qa`
|
||||
- sposób konfigurowania gatewaya dla tego transportu
|
||||
- sposób sprawdzania gotowości
|
||||
- sposób wstrzykiwania zdarzeń przychodzących
|
||||
- sposób obserwowania wiadomości wychodzących
|
||||
- sposób udostępniania transkrypcji i znormalizowanego stanu transportu
|
||||
- sposób wykonywania akcji wspieranych przez transport
|
||||
- sposób obsługi resetowania lub czyszczenia specyficznego dla transportu
|
||||
|
||||
Minimalny próg adopcji dla nowego kanału:
|
||||
|
||||
1. Zachowaj `qa-lab` jako właściciela współdzielonego korzenia `qa`.
|
||||
2. Zaimplementuj runner transportu na współdzielonym seamie hosta `qa-lab`.
|
||||
3. Zachowaj mechanikę specyficzną dla transportu wewnątrz pluginu runnera lub harnessu kanału.
|
||||
4. Zamontuj runner jako `openclaw qa <runner>` zamiast rejestrować konkurencyjne polecenie główne. Pluginy runnerów powinny deklarować `qaRunners` w `openclaw.plugin.json` i eksportować pasującą tablicę `qaRunnerCliRegistrations` z `runtime-api.ts`. Utrzymuj `runtime-api.ts` lekkim; leniwe wykonywanie CLI i runnera powinno pozostać za oddzielnymi punktami wejścia.
|
||||
5. Utwórz lub dostosuj scenariusze markdown w tematycznych katalogach `qa/scenarios/`.
|
||||
2. Zaimplementuj runner transportu na współdzielonym styku hosta `qa-lab`.
|
||||
3. Trzymaj mechanikę specyficzną dla transportu wewnątrz plugina runnera lub harnessu kanału.
|
||||
4. Zamontuj runner jako `openclaw qa <runner>` zamiast rejestrować konkurencyjne polecenie główne. Pluginy runnerów powinny deklarować `qaRunners` w `openclaw.plugin.json` i eksportować pasującą tablicę `qaRunnerCliRegistrations` z `runtime-api.ts`. Utrzymuj `runtime-api.ts` jako lekki plik; leniwe CLI i wykonywanie runnera powinny pozostać za osobnymi punktami wejścia.
|
||||
5. Utwórz lub dostosuj scenariusze Markdown w tematycznych katalogach `qa/scenarios/`.
|
||||
6. Używaj ogólnych helperów scenariuszy dla nowych scenariuszy.
|
||||
7. Utrzymuj istniejące aliasy zgodności, chyba że repo wykonuje zamierzoną migrację.
|
||||
7. Zachowaj działanie istniejących aliasów zgodności, chyba że repozytorium przeprowadza celową migrację.
|
||||
|
||||
Reguła decyzyjna jest ścisła:
|
||||
|
||||
- Jeśli zachowanie można wyrazić raz w `qa-lab`, umieść je w `qa-lab`.
|
||||
- Jeśli zachowanie zależy od jednego transportu kanału, zachowaj je w tym pluginie runnera lub harnessie pluginu.
|
||||
- Jeśli zachowanie zależy od jednego transportu kanału, trzymaj je w tym pluginie runnera lub harnessie plugina.
|
||||
- Jeśli scenariusz potrzebuje nowej możliwości, której może użyć więcej niż jeden kanał, dodaj ogólny helper zamiast gałęzi specyficznej dla kanału w `suite.ts`.
|
||||
- Jeśli zachowanie ma sens tylko dla jednego transportu, zachowaj scenariusz jako specyficzny dla transportu i wyraźnie zaznacz to w kontrakcie scenariusza.
|
||||
- Jeśli zachowanie ma sens tylko dla jednego transportu, zachowaj scenariusz jako specyficzny dla transportu i jasno zaznacz to w kontrakcie scenariusza.
|
||||
|
||||
### Nazwy helperów scenariuszy
|
||||
|
||||
@ -444,7 +463,7 @@ Preferowane ogólne helpery dla nowych scenariuszy:
|
||||
- `formatTransportTranscript`
|
||||
- `resetTransport`
|
||||
|
||||
Aliasy zgodności pozostają dostępne dla istniejących scenariuszy — `waitForQaChannelReady`, `waitForOutboundMessage`, `waitForNoOutbound`, `formatConversationTranscript`, `resetBus` — ale nowe scenariusze powinny używać ogólnych nazw. Aliasy istnieją po to, aby uniknąć migracji typu flag day, a nie jako docelowy model.
|
||||
Aliasy zgodności pozostają dostępne dla istniejących scenariuszy — `waitForQaChannelReady`, `waitForOutboundMessage`, `waitForNoOutbound`, `formatConversationTranscript`, `resetBus` — ale przy tworzeniu nowych scenariuszy należy używać nazw ogólnych. Aliasy istnieją po to, aby uniknąć jednorazowej migracji, a nie jako model na przyszłość.
|
||||
|
||||
## Raportowanie
|
||||
|
||||
@ -456,10 +475,10 @@ Raport powinien odpowiadać na pytania:
|
||||
- Co pozostało zablokowane
|
||||
- Jakie scenariusze uzupełniające warto dodać
|
||||
|
||||
Aby uzyskać inwentarz dostępnych scenariuszy — przydatny przy szacowaniu prac uzupełniających lub podłączaniu nowego transportu — uruchom `pnpm openclaw qa coverage` (dodaj `--json`, aby uzyskać wynik czytelny maszynowo).
|
||||
Aby uzyskać inwentarz dostępnych scenariuszy — przydatny przy szacowaniu dalszych prac lub podłączaniu nowego transportu — uruchom `pnpm openclaw qa coverage` (dodaj `--json`, aby uzyskać dane wyjściowe czytelne maszynowo).
|
||||
|
||||
W przypadku kontroli charakteru i stylu uruchom ten sam scenariusz dla wielu żywych
|
||||
referencji modeli i zapisz oceniony raport Markdown:
|
||||
W przypadku kontroli charakteru i stylu uruchom ten sam scenariusz na wielu żywych referencjach modeli
|
||||
i zapisz oceniony raport Markdown:
|
||||
|
||||
```bash
|
||||
pnpm openclaw qa character-eval \
|
||||
@ -478,42 +497,42 @@ pnpm openclaw qa character-eval \
|
||||
--judge-concurrency 16
|
||||
```
|
||||
|
||||
Polecenie uruchamia lokalne procesy potomne Gateway QA, a nie Docker. Scenariusze character eval
|
||||
powinny ustawiać personę przez `SOUL.md`, a następnie uruchamiać zwykłe tury użytkownika,
|
||||
takie jak czat, pomoc w workspace i małe zadania na plikach. Model kandydujący
|
||||
nie powinien być informowany, że jest oceniany. Polecenie zachowuje każdy pełny
|
||||
transkrypt, zapisuje podstawowe statystyki uruchomienia, a następnie prosi modele oceniające w trybie fast z
|
||||
rozumowaniem `xhigh`, gdzie jest obsługiwane, o uszeregowanie uruchomień według naturalności, vibe’u i humoru.
|
||||
Użyj `--blind-judge-models` podczas porównywania providerów: prompt oceniający nadal otrzymuje
|
||||
każdy transkrypt i status uruchomienia, ale referencje kandydatów są zastępowane neutralnymi
|
||||
Polecenie uruchamia lokalne procesy potomne gatewaya QA, nie Docker. Scenariusze oceny charakteru
|
||||
powinny ustawiać personę przez `SOUL.md`, a następnie wykonywać zwykłe tury użytkownika,
|
||||
takie jak czat, pomoc w obszarze roboczym i małe zadania na plikach. Model kandydacki nie powinien
|
||||
być informowany, że jest oceniany. Polecenie zachowuje każdą pełną
|
||||
transkrypcję, zapisuje podstawowe statystyki uruchomienia, a następnie prosi modele oceniające w trybie szybkim z
|
||||
rozumowaniem `xhigh`, tam gdzie jest obsługiwane, o uszeregowanie uruchomień według naturalności, klimatu i humoru.
|
||||
Użyj `--blind-judge-models` podczas porównywania dostawców: prompt oceniającego nadal otrzymuje
|
||||
każdą transkrypcję i status uruchomienia, ale referencje kandydatów są zastępowane neutralnymi
|
||||
etykietami, takimi jak `candidate-01`; raport mapuje rankingi z powrotem na rzeczywiste referencje po
|
||||
parsowaniu.
|
||||
Uruchomienia kandydatów domyślnie używają myślenia `high`, z `medium` dla GPT-5.5 i `xhigh`
|
||||
dla starszych referencji ewaluacyjnych OpenAI, które je obsługują. Nadpisz konkretnego kandydata inline za pomocą
|
||||
`--model provider/model,thinking=<level>`. `--thinking <level>` nadal ustawia
|
||||
globalny fallback, a starsza forma `--model-thinking <provider/model=level>` jest
|
||||
globalną wartość zapasową, a starsza forma `--model-thinking <provider/model=level>` jest
|
||||
zachowana dla zgodności.
|
||||
Referencje kandydatów OpenAI domyślnie używają trybu fast, aby korzystać z przetwarzania priorytetowego tam,
|
||||
gdzie provider je obsługuje. Dodaj `,fast`, `,no-fast` lub `,fast=false` inline, gdy
|
||||
Referencje kandydatów OpenAI domyślnie używają trybu szybkiego, dzięki czemu przetwarzanie priorytetowe jest używane tam,
|
||||
gdzie dostawca je obsługuje. Dodaj inline `,fast`, `,no-fast` lub `,fast=false`, gdy
|
||||
pojedynczy kandydat lub oceniający wymaga nadpisania. Przekaż `--fast` tylko wtedy, gdy chcesz
|
||||
wymusić tryb fast dla każdego modelu kandydującego. Czasy trwania kandydatów i oceniających są
|
||||
zapisywane w raporcie do analizy benchmarków, ale prompty oceniające wyraźnie mówią,
|
||||
aby nie ustalać rankingu według szybkości.
|
||||
Uruchomienia modeli kandydatów i oceniających domyślnie używają współbieżności 16. Obniż
|
||||
`--concurrency` lub `--judge-concurrency`, gdy limity providera lub lokalne obciążenie Gateway
|
||||
wymusić tryb szybki dla każdego modelu kandydackiego. Czasy trwania kandydatów i oceniających są
|
||||
zapisywane w raporcie do analizy porównawczej, ale prompty oceniających wyraźnie wskazują,
|
||||
aby nie klasyfikować według szybkości.
|
||||
Uruchomienia modeli kandydackich i oceniających domyślnie używają współbieżności 16. Obniż
|
||||
`--concurrency` lub `--judge-concurrency`, gdy limity dostawcy lub lokalne obciążenie gatewaya
|
||||
sprawiają, że uruchomienie jest zbyt zaszumione.
|
||||
Gdy nie przekazano żadnego kandydującego `--model`, character eval domyślnie używa
|
||||
Gdy nie podano kandydata `--model`, ocena charakteru domyślnie używa
|
||||
`openai/gpt-5.5`, `openai/gpt-5.2`, `openai/gpt-5`, `anthropic/claude-opus-4-6`,
|
||||
`anthropic/claude-sonnet-4-6`, `zai/glm-5.1`,
|
||||
`moonshot/kimi-k2.5` i
|
||||
`google/gemini-3.1-pro-preview`, gdy nie przekazano żadnego `--model`.
|
||||
Gdy nie przekazano `--judge-model`, domyślni oceniający to
|
||||
`openai/gpt-5.5,thinking=xhigh,fast` i
|
||||
`moonshot/kimi-k2.5` oraz
|
||||
`google/gemini-3.1-pro-preview`, gdy nie podano `--model`.
|
||||
Gdy nie podano `--judge-model`, domyślnymi oceniającymi są
|
||||
`openai/gpt-5.5,thinking=xhigh,fast` oraz
|
||||
`anthropic/claude-opus-4-6,thinking=high`.
|
||||
|
||||
## Powiązana dokumentacja
|
||||
|
||||
- [QA Matrix](/pl/concepts/qa-matrix)
|
||||
- [Kanał QA](/pl/channels/qa-channel)
|
||||
- [Matrix QA](/pl/concepts/qa-matrix)
|
||||
- [QA Channel](/pl/channels/qa-channel)
|
||||
- [Testowanie](/pl/help/testing)
|
||||
- [Dashboard](/pl/web/dashboard)
|
||||
|
||||
@ -1,29 +1,29 @@
|
||||
---
|
||||
read_when:
|
||||
- Wyjaśnienie, jak działa strumieniowanie lub dzielenie na fragmenty w kanałach
|
||||
- Wyjaśnianie, jak działa przesyłanie strumieniowe lub dzielenie na fragmenty w kanałach
|
||||
- Zmiana zachowania strumieniowania bloków lub dzielenia kanału na fragmenty
|
||||
- Debugowanie zduplikowanych/przedwczesnych odpowiedzi blokowych lub strumieniowania podglądu kanału
|
||||
summary: Zachowanie przesyłania strumieniowego + dzielenia na fragmenty (odpowiedzi blokowe, przesyłanie strumieniowe podglądu kanału, mapowanie trybów)
|
||||
- Debugowanie zduplikowanych/zbyt wczesnych odpowiedzi blokowych lub strumieniowania podglądu kanału
|
||||
summary: Zachowanie strumieniowania + dzielenia na fragmenty (odpowiedzi blokowe, strumieniowanie podglądu kanału, mapowanie trybu)
|
||||
title: Strumieniowanie i dzielenie na fragmenty
|
||||
x-i18n:
|
||||
generated_at: "2026-05-03T21:30:55Z"
|
||||
generated_at: "2026-05-04T07:04:51Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 1335f4f5532060bd8bf839683a2b1fbab38f38887c5583135652b4753e0f6a50
|
||||
source_hash: ff7b6cd8127255352fe16fb746469e9828e7d5aea183d3799ab10cc768515bd1
|
||||
source_path: concepts/streaming.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
OpenClaw ma dwie oddzielne warstwy strumieniowania:
|
||||
|
||||
- **Strumieniowanie bloków (kanały):** emitowanie ukończonych **bloków** podczas pisania przez asystenta. Są to normalne wiadomości kanału (nie delty tokenów).
|
||||
- **Strumieniowanie podglądu (Telegram/Discord/Slack):** aktualizowanie tymczasowej **wiadomości podglądu** podczas generowania.
|
||||
- **Strumieniowanie blokowe (kanały):** emituje ukończone **bloki** podczas pisania przez asystenta. Są to zwykłe wiadomości kanału (nie delty tokenów).
|
||||
- **Strumieniowanie podglądu (Telegram/Discord/Slack):** aktualizuje tymczasową **wiadomość podglądu** podczas generowania.
|
||||
|
||||
Obecnie nie ma **prawdziwego strumieniowania delt tokenów** do wiadomości kanału. Strumieniowanie podglądu opiera się na wiadomościach (wysyłanie + edycje/dopisania).
|
||||
Obecnie **nie ma prawdziwego strumieniowania delt tokenów** do wiadomości kanału. Strumieniowanie podglądu działa na poziomie wiadomości (wysyłanie + edycje/dołączanie).
|
||||
|
||||
## Strumieniowanie bloków (wiadomości kanału)
|
||||
## Strumieniowanie blokowe (wiadomości kanału)
|
||||
|
||||
Strumieniowanie bloków wysyła odpowiedź asystenta w większych fragmentach, gdy stają się dostępne.
|
||||
Strumieniowanie blokowe wysyła wynik asystenta w większych fragmentach, gdy tylko stają się dostępne.
|
||||
|
||||
```
|
||||
Model output
|
||||
@ -38,76 +38,75 @@ Model output
|
||||
Legenda:
|
||||
|
||||
- `text_delta/events`: zdarzenia strumienia modelu (mogą być rzadkie dla modeli niestrumieniujących).
|
||||
- `chunker`: `EmbeddedBlockChunker` stosujący minimalne/maksymalne limity + preferencję podziału.
|
||||
- `channel send`: rzeczywiste wiadomości wychodzące (odpowiedzi blokowe).
|
||||
- `chunker`: `EmbeddedBlockChunker` stosujący granice min./maks. + preferencję podziału.
|
||||
- `channel send`: faktyczne wiadomości wychodzące (odpowiedzi blokowe).
|
||||
|
||||
**Elementy sterujące:**
|
||||
**Kontrolki:**
|
||||
|
||||
- `agents.defaults.blockStreamingDefault`: `"on"`/`"off"` (domyślnie wyłączone).
|
||||
- Nadpisania kanałów: `*.blockStreaming` (oraz warianty per konto), aby wymusić `"on"`/`"off"` dla kanału.
|
||||
- `agents.defaults.blockStreamingBreak`: `"text_end"` albo `"message_end"`.
|
||||
- `agents.defaults.blockStreamingChunk`: `{ minChars, maxChars, breakPreference? }`.
|
||||
- `agents.defaults.blockStreamingCoalesce`: `{ minChars?, maxChars?, idleMs? }` (scalanie strumieniowanych bloków przed wysłaniem).
|
||||
- `agents.defaults.blockStreamingCoalesce`: `{ minChars?, maxChars?, idleMs? }` (scala strumieniowane bloki przed wysłaniem).
|
||||
- Twardy limit kanału: `*.textChunkLimit` (np. `channels.whatsapp.textChunkLimit`).
|
||||
- Tryb fragmentowania kanału: `*.chunkMode` (domyślnie `length`, `newline` dzieli po pustych wierszach (granicach akapitów) przed dzieleniem według długości).
|
||||
- Miękki limit Discord: `channels.discord.maxLinesPerMessage` (domyślnie 17) dzieli wysokie odpowiedzi, aby uniknąć obcinania w interfejsie.
|
||||
- Tryb dzielenia kanału: `*.chunkMode` (`length` domyślnie, `newline` dzieli po pustych wierszach (granicach akapitów) przed dzieleniem według długości).
|
||||
- Miękki limit Discord: `channels.discord.maxLinesPerMessage` (domyślnie 17) dzieli wysokie odpowiedzi, aby uniknąć przycinania w UI.
|
||||
|
||||
**Semantyka granic:**
|
||||
|
||||
- `text_end`: strumieniuj bloki, gdy tylko chunker je wyemituje; opróżniaj przy każdym `text_end`.
|
||||
- `message_end`: poczekaj, aż wiadomość asystenta się zakończy, a następnie opróżnij zbuforowaną odpowiedź.
|
||||
- `text_end`: strumieniuje bloki, gdy tylko emituje je dzielnik; opróżnia przy każdym `text_end`.
|
||||
- `message_end`: czeka do zakończenia wiadomości asystenta, a następnie opróżnia buforowany wynik.
|
||||
|
||||
`message_end` nadal używa chunkera, jeśli zbuforowany tekst przekracza `maxChars`, więc na końcu może wyemitować wiele fragmentów.
|
||||
`message_end` nadal używa dzielnika, jeśli buforowany tekst przekracza `maxChars`, więc może wyemitować kilka fragmentów na końcu.
|
||||
|
||||
### Dostarczanie mediów ze strumieniowaniem bloków
|
||||
### Dostarczanie multimediów ze strumieniowaniem blokowym
|
||||
|
||||
Dyrektywy `MEDIA:` są zwykłymi metadanymi dostarczania. Gdy strumieniowanie bloków wyśle blok multimedialny wcześniej, OpenClaw zapamiętuje to dostarczenie dla danej tury. Jeśli końcowy ładunek asystenta powtórzy ten sam URL multimediów, końcowe dostarczenie usuwa zduplikowane multimedia zamiast ponownie wysyłać załącznik.
|
||||
Dyrektywy `MEDIA:` są zwykłymi metadanymi dostarczania. Gdy strumieniowanie blokowe wcześnie wyśle blok multimediów, OpenClaw zapamiętuje to dostarczenie dla danej tury. Jeśli końcowy ładunek asystenta powtarza ten sam URL multimediów, końcowe dostarczenie usuwa zduplikowane multimedia zamiast ponownie wysyłać załącznik.
|
||||
|
||||
Dokładne duplikaty końcowych ładunków są pomijane. Jeśli końcowy ładunek dodaje odrębny tekst wokół multimediów, które zostały już zestrumieniowane, OpenClaw nadal wysyła nowy tekst, zachowując jednokrotne dostarczenie multimediów. Zapobiega to duplikowaniu notatek głosowych lub plików w kanałach takich jak Telegram, gdy agent emituje `MEDIA:` podczas strumieniowania, a dostawca uwzględnia je także w ukończonej odpowiedzi.
|
||||
Dokładne duplikaty końcowych ładunków są pomijane. Jeśli końcowy ładunek dodaje odrębny tekst wokół multimediów, które zostały już przesłane strumieniowo, OpenClaw nadal wysyła nowy tekst, zachowując jednokrotne dostarczenie multimediów. Zapobiega to duplikowaniu wiadomości głosowych lub plików w kanałach takich jak Telegram, gdy agent emituje `MEDIA:` podczas strumieniowania, a dostawca uwzględnia je także w ukończonej odpowiedzi.
|
||||
|
||||
## Algorytm fragmentowania (dolne/górne granice)
|
||||
## Algorytm dzielenia (dolne/górne granice)
|
||||
|
||||
Fragmentowanie bloków implementuje `EmbeddedBlockChunker`:
|
||||
Dzielenie bloków jest implementowane przez `EmbeddedBlockChunker`:
|
||||
|
||||
- **Dolna granica:** nie emituj, dopóki bufor >= `minChars` (chyba że wymuszone).
|
||||
- **Górna granica:** preferuj podziały przed `maxChars`; jeśli wymuszone, podziel przy `maxChars`.
|
||||
- **Preferencja podziału:** `paragraph` → `newline` → `sentence` → `whitespace` → twardy podział.
|
||||
- **Bloki kodu:** nigdy nie dziel wewnątrz bloków; przy wymuszeniu w `maxChars` zamknij + ponownie otwórz blok, aby zachować poprawny Markdown.
|
||||
- **Bloki kodu:** nigdy nie dziel wewnątrz bloków; po wymuszeniu przy `maxChars` zamknij + ponownie otwórz blok, aby Markdown pozostał poprawny.
|
||||
|
||||
`maxChars` jest ograniczane do kanałowego `textChunkLimit`, więc nie można przekroczyć limitów per kanał.
|
||||
|
||||
## Scalanie (łączenie strumieniowanych bloków)
|
||||
|
||||
Gdy strumieniowanie bloków jest włączone, OpenClaw może **scalać kolejne fragmenty bloków** przed ich wysłaniem. Ogranicza to „spam pojedynczymi wierszami”, a jednocześnie nadal zapewnia progresywne odpowiedzi.
|
||||
Gdy strumieniowanie blokowe jest włączone, OpenClaw może **scalać kolejne fragmenty bloków** przed ich wysłaniem. Ogranicza to „spam pojedynczymi wierszami”, nadal zapewniając progresywny wynik.
|
||||
|
||||
- Scalanie czeka na **przerwy bezczynności** (`idleMs`) przed opróżnieniem.
|
||||
- Bufory są ograniczone przez `maxChars` i zostaną opróżnione, jeśli go przekroczą.
|
||||
- `minChars` zapobiega wysyłaniu drobnych fragmentów, dopóki nie zbierze się wystarczająco dużo tekstu (końcowe opróżnienie zawsze wysyła pozostały tekst).
|
||||
- Łącznik jest wyprowadzany z `blockStreamingChunk.breakPreference`
|
||||
- Bufory są ograniczane przez `maxChars` i zostaną opróżnione po jego przekroczeniu.
|
||||
- `minChars` zapobiega wysyłaniu drobnych fragmentów, dopóki nie nagromadzi się wystarczająco dużo tekstu (końcowe opróżnienie zawsze wysyła pozostały tekst).
|
||||
- Łącznik pochodzi z `blockStreamingChunk.breakPreference`
|
||||
(`paragraph` → `\n\n`, `newline` → `\n`, `sentence` → spacja).
|
||||
- Nadpisania kanałów są dostępne przez `*.blockStreamingCoalesce` (w tym konfiguracje per konto).
|
||||
- Domyślne `minChars` dla scalania jest podniesione do 1500 dla Signal/Slack/Discord, chyba że zostanie nadpisane.
|
||||
- Domyślne `minChars` scalania jest podnoszone do 1500 dla Signal/Slack/Discord, chyba że zostanie nadpisane.
|
||||
|
||||
## Naturalne tempo między blokami
|
||||
## Ludzkie tempo między blokami
|
||||
|
||||
Gdy strumieniowanie bloków jest włączone, można dodać **losową pauzę** między odpowiedziami blokowymi (po pierwszym bloku). Dzięki temu odpowiedzi w wielu dymkach sprawiają bardziej naturalne wrażenie.
|
||||
Gdy strumieniowanie blokowe jest włączone, można dodać **losową pauzę** między odpowiedziami blokowymi (po pierwszym bloku). Dzięki temu odpowiedzi w wielu dymkach sprawiają bardziej naturalne wrażenie.
|
||||
|
||||
- Konfiguracja: `agents.defaults.humanDelay` (nadpisanie per agent przez `agents.list[].humanDelay`).
|
||||
- Tryby: `off` (domyślny), `natural` (800–2500 ms), `custom` (`minMs`/`maxMs`).
|
||||
- Dotyczy wyłącznie **odpowiedzi blokowych**, nie odpowiedzi końcowych ani podsumowań narzędzi.
|
||||
- Dotyczy tylko **odpowiedzi blokowych**, nie odpowiedzi końcowych ani podsumowań narzędzi.
|
||||
|
||||
## „Strumieniuj fragmenty albo całość”
|
||||
## „Strumieniuj fragmenty albo wszystko”
|
||||
|
||||
Odpowiada to:
|
||||
Odpowiada to następującym ustawieniom:
|
||||
|
||||
- **Strumieniuj fragmenty:** `blockStreamingDefault: "on"` + `blockStreamingBreak: "text_end"` (emituj na bieżąco). Kanały inne niż Telegram wymagają także `*.blockStreaming: true`.
|
||||
- **Strumieniuj całość na końcu:** `blockStreamingBreak: "message_end"` (opróżnij raz, potencjalnie w wielu fragmentach, jeśli odpowiedź jest bardzo długa).
|
||||
- **Bez strumieniowania bloków:** `blockStreamingDefault: "off"` (tylko odpowiedź końcowa).
|
||||
- **Strumieniuj fragmenty:** `blockStreamingDefault: "on"` + `blockStreamingBreak: "text_end"` (emituj na bieżąco). Kanały inne niż Telegram również wymagają `*.blockStreaming: true`.
|
||||
- **Strumieniuj wszystko na końcu:** `blockStreamingBreak: "message_end"` (opróżnij raz, potencjalnie w wielu fragmentach, jeśli bardzo długie).
|
||||
- **Bez strumieniowania blokowego:** `blockStreamingDefault: "off"` (tylko odpowiedź końcowa).
|
||||
|
||||
**Uwaga dotycząca kanałów:** strumieniowanie bloków jest **wyłączone, chyba że**
|
||||
`*.blockStreaming` zostanie jawnie ustawione na `true`. Kanały mogą strumieniować podgląd na żywo (`channels.<channel>.streaming`) bez odpowiedzi blokowych.
|
||||
**Uwaga o kanałach:** Strumieniowanie blokowe jest **wyłączone, chyba że** `*.blockStreaming` jest jawnie ustawione na `true`. Kanały mogą strumieniować podgląd na żywo (`channels.<channel>.streaming`) bez odpowiedzi blokowych.
|
||||
|
||||
Przypomnienie o lokalizacji konfiguracji: domyślne ustawienia `blockStreaming*` znajdują się w `agents.defaults`, a nie w konfiguracji głównej.
|
||||
Przypomnienie o lokalizacji konfiguracji: ustawienia domyślne `blockStreaming*` znajdują się w `agents.defaults`, a nie w konfiguracji głównej.
|
||||
|
||||
## Tryby strumieniowania podglądu
|
||||
|
||||
@ -117,25 +116,25 @@ Tryby:
|
||||
|
||||
- `off`: wyłącza strumieniowanie podglądu.
|
||||
- `partial`: pojedynczy podgląd zastępowany najnowszym tekstem.
|
||||
- `block`: podgląd aktualizowany krokami fragmentowanymi/dopisywanymi.
|
||||
- `progress`: podgląd postępu/statusu podczas generowania, odpowiedź końcowa po zakończeniu.
|
||||
- `block`: podgląd aktualizowany w krokach dzielonych/dołączanych.
|
||||
- `progress`: podgląd postępu/statusu podczas generowania, końcowa odpowiedź po ukończeniu.
|
||||
|
||||
`streaming.mode: "block"` jest trybem strumieniowania podglądu dla kanałów obsługujących edycję, takich jak Discord i Telegram. Nie włącza tam dostarczania bloków kanału. Użyj `streaming.block.enabled` albo starszego klucza kanału `blockStreaming`, gdy potrzebujesz normalnych odpowiedzi blokowych. Microsoft Teams jest wyjątkiem: nie ma transportu bloków podglądu roboczego, więc `streaming.mode: "block"` mapuje się na dostarczanie bloków Teams zamiast natywnego strumieniowania częściowego/postępu.
|
||||
`streaming.mode: "block"` jest trybem strumieniowania podglądu dla kanałów obsługujących edycję, takich jak Discord i Telegram. Nie włącza tam blokowego dostarczania w kanale. Użyj `streaming.block.enabled` albo starszego klucza kanału `blockStreaming`, gdy chcesz zwykłych odpowiedzi blokowych. Microsoft Teams jest wyjątkiem: nie ma transportu bloków podglądu roboczego, więc `streaming.mode: "block"` mapuje się na dostarczanie blokowe Teams zamiast natywnego strumieniowania częściowego/postępu.
|
||||
|
||||
### Mapowanie kanałów
|
||||
|
||||
| Kanał | `off` | `partial` | `block` | `progress` |
|
||||
| ---------- | ----- | --------- | ------- | ----------------------- |
|
||||
| Telegram | ✅ | ✅ | ✅ | edytowalny szkic postępu |
|
||||
| Discord | ✅ | ✅ | ✅ | edytowalny szkic postępu |
|
||||
| Slack | ✅ | ✅ | ✅ | ✅ |
|
||||
| Mattermost | ✅ | ✅ | ✅ | ✅ |
|
||||
| MS Teams | ✅ | ✅ | ✅ | natywny strumień postępu |
|
||||
| Kanał | `off` | `partial` | `block` | `progress` |
|
||||
| ---------- | ----- | --------- | ------- | -------------------------- |
|
||||
| Telegram | ✅ | ✅ | ✅ | edytowalna wersja robocza postępu |
|
||||
| Discord | ✅ | ✅ | ✅ | edytowalna wersja robocza postępu |
|
||||
| Slack | ✅ | ✅ | ✅ | ✅ |
|
||||
| Mattermost | ✅ | ✅ | ✅ | ✅ |
|
||||
| MS Teams | ✅ | ✅ | ✅ | natywny strumień postępu |
|
||||
|
||||
Tylko Slack:
|
||||
|
||||
- `channels.slack.streaming.nativeTransport` przełącza natywne wywołania API strumieniowania Slack, gdy `channels.slack.streaming.mode="partial"` (domyślnie: `true`).
|
||||
- Natywne strumieniowanie Slack i status wątku asystenta Slack wymagają docelowego wątku odpowiedzi. DM-y najwyższego poziomu nie pokazują tego podglądu w stylu wątku, ale nadal mogą używać postów i edycji szkicu podglądu Slack.
|
||||
- Natywne strumieniowanie Slack i status wątku asystenta Slack wymagają docelowego wątku odpowiedzi. DM najwyższego poziomu nie pokazują tego podglądu w stylu wątku, ale nadal mogą używać roboczych postów podglądu Slack i edycji.
|
||||
|
||||
Migracja starszych kluczy:
|
||||
|
||||
@ -143,56 +142,56 @@ Migracja starszych kluczy:
|
||||
- Discord: `streamMode` + logiczne `streaming` automatycznie migrują do wyliczenia `streaming`.
|
||||
- Slack: `streamMode` automatycznie migruje do `streaming.mode`; logiczne `streaming` automatycznie migruje do `streaming.mode` plus `streaming.nativeTransport`; starsze `nativeStreaming` automatycznie migruje do `streaming.nativeTransport`.
|
||||
|
||||
### Zachowanie w czasie działania
|
||||
### Zachowanie w czasie wykonywania
|
||||
|
||||
Telegram:
|
||||
|
||||
- Używa `sendMessage` + `editMessageText` do aktualizacji podglądu w DM-ach oraz grupach/tematach.
|
||||
- Wysyła świeżą wiadomość końcową zamiast edytować w miejscu, gdy podgląd był widoczny przez około minutę, a następnie usuwa podgląd, aby znacznik czasu Telegram odzwierciedlał ukończenie odpowiedzi.
|
||||
- Strumieniowanie podglądu jest pomijane, gdy strumieniowanie bloków Telegram jest jawnie włączone (aby uniknąć podwójnego strumieniowania).
|
||||
- `/reasoning stream` może zapisywać rozumowanie do podglądu.
|
||||
- Używa `sendMessage` + `editMessageText` do aktualizacji podglądu w DM i grupach/tematach.
|
||||
- Wysyła świeżą wiadomość końcową zamiast edytować w miejscu, gdy podgląd był widoczny przez około minutę, a następnie czyści podgląd, aby znacznik czasu Telegram odzwierciedlał ukończenie odpowiedzi.
|
||||
- Strumieniowanie podglądu jest pomijane, gdy strumieniowanie blokowe Telegram jest jawnie włączone (aby uniknąć podwójnego strumieniowania).
|
||||
- `/reasoning stream` może zapisywać rozumowanie do przejściowego podglądu, który jest usuwany po końcowym dostarczeniu.
|
||||
|
||||
Discord:
|
||||
|
||||
- Używa wysyłania + edycji wiadomości podglądu.
|
||||
- Tryb `block` używa fragmentowania szkicu (`draftChunk`).
|
||||
- Strumieniowanie podglądu jest pomijane, gdy strumieniowanie bloków Discord jest jawnie włączone.
|
||||
- Końcowe ładunki multimediów, błędów i jawnych odpowiedzi anulują oczekujące podglądy bez opróżniania nowego szkicu, a następnie używają normalnego dostarczania.
|
||||
- Tryb `block` używa dzielenia wersji roboczej (`draftChunk`).
|
||||
- Strumieniowanie podglądu jest pomijane, gdy strumieniowanie blokowe Discord jest jawnie włączone.
|
||||
- Końcowe multimedia, błędy i ładunki jawnej odpowiedzi anulują oczekujące podglądy bez opróżniania nowej wersji roboczej, a następnie używają zwykłego dostarczania.
|
||||
|
||||
Slack:
|
||||
|
||||
- `partial` może używać natywnego strumieniowania Slack (`chat.startStream`/`append`/`stop`), gdy jest dostępne.
|
||||
- `block` używa podglądów szkicu w stylu dopisywania.
|
||||
- `progress` używa tekstu podglądu statusu, a następnie odpowiedzi końcowej.
|
||||
- DM-y najwyższego poziomu bez wątku odpowiedzi używają postów i edycji szkicu podglądu zamiast natywnego strumieniowania Slack.
|
||||
- Natywne strumieniowanie i strumieniowanie podglądu szkicu pomijają odpowiedzi blokowe dla tej tury, więc odpowiedź Slack jest strumieniowana tylko jedną ścieżką dostarczania.
|
||||
- Końcowe ładunki multimediów/błędów oraz końcowe wiadomości postępu nie tworzą jednorazowych wiadomości szkicu; tylko końcowe teksty/bloki, które mogą edytować podgląd, opróżniają oczekujący tekst szkicu.
|
||||
- `block` używa podglądów wersji roboczych w stylu dołączania.
|
||||
- `progress` używa tekstu podglądu statusu, a następnie końcowej odpowiedzi.
|
||||
- DM najwyższego poziomu bez wątku odpowiedzi używają roboczych postów podglądu i edycji zamiast natywnego strumieniowania Slack.
|
||||
- Natywne i robocze strumieniowanie podglądu tłumią odpowiedzi blokowe dla tej tury, więc odpowiedź Slack jest strumieniowana tylko jedną ścieżką dostarczania.
|
||||
- Końcowe ładunki multimediów/błędów i końcowe wyniki postępu nie tworzą tymczasowych wiadomości roboczych; tylko końcowe teksty/bloki, które mogą edytować podgląd, opróżniają oczekujący tekst roboczy.
|
||||
|
||||
Mattermost:
|
||||
|
||||
- Strumieniuje myślenie, aktywność narzędzi i częściowy tekst odpowiedzi do pojedynczego posta szkicu podglądu, który finalizuje się w miejscu, gdy odpowiedź końcowa może zostać bezpiecznie wysłana.
|
||||
- W razie usunięcia posta podglądu lub jego niedostępności w momencie finalizacji wraca do wysłania świeżego posta końcowego.
|
||||
- Końcowe ładunki multimediów/błędów anulują oczekujące aktualizacje podglądu przed normalnym dostarczeniem zamiast opróżniać tymczasowy post podglądu.
|
||||
- Strumieniuje myślenie, aktywność narzędzi i częściowy tekst odpowiedzi do pojedynczego roboczego posta podglądu, który finalizuje się w miejscu, gdy końcowa odpowiedź jest bezpieczna do wysłania.
|
||||
- Przechodzi na wysłanie świeżego posta końcowego, jeśli post podglądu został usunięty lub z innego powodu jest niedostępny w czasie finalizacji.
|
||||
- Końcowe ładunki multimediów/błędów anulują oczekujące aktualizacje podglądu przed zwykłym dostarczeniem zamiast opróżniać tymczasowy post podglądu.
|
||||
|
||||
Matrix:
|
||||
|
||||
- Podglądy szkicu finalizują się w miejscu, gdy tekst końcowy może ponownie użyć zdarzenia podglądu.
|
||||
- Końcowe wiadomości tylko z multimediami, błędami oraz z niezgodnym celem odpowiedzi anulują oczekujące aktualizacje podglądu przed normalnym dostarczeniem; już widoczny nieaktualny podgląd jest redagowany.
|
||||
- Podglądy robocze finalizują się w miejscu, gdy tekst końcowy może ponownie użyć zdarzenia podglądu.
|
||||
- Końcowe ładunki tylko z multimediami, błędy i odpowiedzi z niezgodnym celem odpowiedzi anulują oczekujące aktualizacje podglądu przed zwykłym dostarczeniem; już widoczny nieaktualny podgląd jest redagowany.
|
||||
|
||||
### Aktualizacje podglądu postępu narzędzi
|
||||
|
||||
Strumieniowanie podglądu może także obejmować aktualizacje **postępu narzędzi** — krótkie wiersze statusu, takie jak „wyszukiwanie w sieci”, „czytanie pliku” albo „wywoływanie narzędzia” — które pojawiają się w tej samej wiadomości podglądu podczas działania narzędzi, przed odpowiedzią końcową. Dzięki temu wieloetapowe tury narzędzi pozostają wizualnie aktywne, zamiast milczeć między pierwszym podglądem myślenia a odpowiedzią końcową.
|
||||
Strumieniowanie podglądu może również obejmować aktualizacje **postępu narzędzi** — krótkie wiersze statusu, takie jak „przeszukiwanie sieci”, „odczytywanie pliku” albo „wywoływanie narzędzia” — które pojawiają się w tej samej wiadomości podglądu podczas działania narzędzi, przed końcową odpowiedzią. Dzięki temu wieloetapowe tury narzędzi pozostają wizualnie aktywne zamiast milczeć między pierwszym podglądem myślenia a końcową odpowiedzią.
|
||||
|
||||
Obsługiwane powierzchnie:
|
||||
|
||||
- **Discord**, **Slack**, **Telegram** i **Matrix** domyślnie strumieniują postęp narzędzi do edycji podglądu na żywo, gdy strumieniowanie podglądu jest aktywne. Microsoft Teams używa natywnego strumienia postępu w czatach osobistych.
|
||||
- Telegram ma aktualizacje podglądu postępu narzędzi włączone od `v2026.4.22`; pozostawienie ich włączonych zachowuje to wydane zachowanie.
|
||||
- **Mattermost** już włącza aktywność narzędzi do pojedynczego posta szkicu podglądu (patrz wyżej).
|
||||
- Edycje postępu narzędzi podążają za aktywnym trybem strumieniowania podglądu; są pomijane, gdy strumieniowanie podglądu jest `off` albo gdy strumieniowanie bloków przejęło wiadomość. W Telegram, `streaming.mode: "off"` oznacza tylko odpowiedź końcową: ogólne komunikaty o postępie są także tłumione zamiast być dostarczane jako samodzielne wiadomości statusu, natomiast prośby o zatwierdzenie, ładunki multimediów i błędy nadal są kierowane normalnie.
|
||||
- Aby zachować strumieniowanie podglądu, ale ukryć wiersze postępu narzędzi, ustaw `streaming.preview.toolProgress` na `false` dla tego kanału. Aby całkowicie wyłączyć edycje podglądu, ustaw `streaming.mode` na `off`.
|
||||
- Wybrane odpowiedzi z cytatem w Telegram są wyjątkiem: gdy `replyToMode` nie jest `"off"` i obecny jest tekst wybranego cytatu, OpenClaw pomija strumień podglądu odpowiedzi dla tej tury, więc wiersze podglądu postępu narzędzi nie mogą się renderować. Odpowiedzi do bieżącej wiadomości bez tekstu wybranego cytatu nadal zachowują strumieniowanie podglądu. Szczegóły znajdziesz w [dokumentacji kanału Telegram](/pl/channels/telegram).
|
||||
- Telegram jest dostarczany z włączonymi aktualizacjami podglądu postępu narzędzi od `v2026.4.22`; pozostawienie ich włączonych zachowuje to wydane zachowanie.
|
||||
- **Mattermost** już włącza aktywność narzędzi do swojego pojedynczego roboczego posta podglądu (zobacz wyżej).
|
||||
- Edycje postępu narzędzi podążają za aktywnym trybem strumieniowania podglądu; są pomijane, gdy strumieniowanie podglądu jest `off` albo gdy strumieniowanie blokowe przejęło wiadomość. W Telegram `streaming.mode: "off"` oznacza tylko wynik końcowy: ogólne komunikaty postępu również są tłumione zamiast być dostarczane jako samodzielne wiadomości statusu, natomiast prośby o zatwierdzenie, ładunki multimediów i błędy nadal są kierowane normalnie.
|
||||
- Aby zachować strumieniowanie podglądu, ale ukryć wiersze postępu narzędzi, ustaw `streaming.preview.toolProgress` na `false` dla tego kanału. Aby pozostawić widoczne wiersze postępu narzędzi, ukrywając tekst poleceń/wykonań, ustaw `streaming.preview.commandText` na `"status"` albo `streaming.progress.commandText` na `"status"`; domyślnie jest `"raw"`, aby zachować wydane zachowanie. Ta polityka jest współdzielona przez kanały robocze/postępu używające zwartego renderera postępu OpenClaw, w tym Discord, Matrix, Microsoft Teams, Mattermost, robocze podglądy Slack i Telegram. Aby całkowicie wyłączyć edycje podglądu, ustaw `streaming.mode` na `off`.
|
||||
- Wybrane odpowiedzi cytatem w Telegram są wyjątkiem: gdy `replyToMode` nie jest `"off"` i obecny jest wybrany tekst cytatu, OpenClaw pomija strumień podglądu odpowiedzi dla tej tury, więc wiersze podglądu postępu narzędzi nie mogą się renderować. Odpowiedzi do bieżącej wiadomości bez wybranego tekstu cytatu nadal zachowują strumieniowanie podglądu. Szczegóły znajdziesz w [dokumentacji kanału Telegram](/pl/channels/telegram).
|
||||
|
||||
Przykład:
|
||||
Zachowaj widoczność wierszy postępu, ale ukryj surowy tekst poleceń/wykonań:
|
||||
|
||||
```json
|
||||
{
|
||||
@ -201,7 +200,26 @@ Przykład:
|
||||
"streaming": {
|
||||
"mode": "partial",
|
||||
"preview": {
|
||||
"toolProgress": false
|
||||
"toolProgress": true,
|
||||
"commandText": "status"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Użyj tej samej struktury pod innym kluczem kanału kompaktowego postępu, na przykład `channels.discord`, `channels.matrix`, `channels.msteams`, `channels.mattermost` albo podglądami szkiców Slack. W trybie szkicu postępu umieść tę samą zasadę pod `streaming.progress`:
|
||||
|
||||
```json
|
||||
{
|
||||
"channels": {
|
||||
"telegram": {
|
||||
"streaming": {
|
||||
"mode": "progress",
|
||||
"progress": {
|
||||
"toolProgress": true,
|
||||
"commandText": "status"
|
||||
}
|
||||
}
|
||||
}
|
||||
@ -211,7 +229,7 @@ Przykład:
|
||||
|
||||
## Powiązane
|
||||
|
||||
- [Szkice postępu](/pl/concepts/progress-drafts) — widoczne wiadomości o pracy w toku, aktualizowane podczas długich tur
|
||||
- [Wiadomości](/pl/concepts/messages) — cykl życia wiadomości i dostarczanie
|
||||
- [Szkice postępu](/pl/concepts/progress-drafts) — widoczne komunikaty o pracy w toku, które aktualizują się podczas długich tur
|
||||
- [Wiadomości](/pl/concepts/messages) — cykl życia i dostarczanie wiadomości
|
||||
- [Ponawianie](/pl/concepts/retry) — zachowanie ponawiania po niepowodzeniu dostarczenia
|
||||
- [Kanały](/pl/channels) — obsługa strumieniowania per kanał
|
||||
- [Kanały](/pl/channels) — obsługa strumieniowania dla poszczególnych kanałów
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@ -1,29 +1,29 @@
|
||||
---
|
||||
read_when:
|
||||
- Aktualizacja OpenClaw
|
||||
- Aktualizowanie OpenClaw
|
||||
- Coś przestaje działać po aktualizacji
|
||||
summary: Bezpieczne aktualizowanie OpenClaw (instalacja globalna lub ze źródeł) oraz strategia przywracania poprzedniej wersji
|
||||
summary: Bezpieczne aktualizowanie OpenClaw (instalacja globalna lub ze źródła) oraz strategia wycofywania zmian
|
||||
title: Aktualizacja
|
||||
x-i18n:
|
||||
generated_at: "2026-05-03T21:34:50Z"
|
||||
generated_at: "2026-05-04T07:04:52Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: f9e26ea71748dfd1573cdca01126bf29ebc56be56eac604e2b6a009b463820d1
|
||||
source_hash: 3c9ff1d70d74f45efea3c148718e5cbc74001ce3d924b760edc4d68622d23714
|
||||
source_path: install/updating.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
Utrzymuj OpenClaw w aktualnej wersji.
|
||||
Dbaj o aktualność OpenClaw.
|
||||
|
||||
## Zalecane: `openclaw update`
|
||||
|
||||
Najszybszy sposób aktualizacji. Wykrywa typ instalacji (npm lub git), pobiera najnowszą wersję, uruchamia `openclaw doctor` i restartuje gateway.
|
||||
Najszybszy sposób aktualizacji. Wykrywa typ instalacji (npm lub git), pobiera najnowszą wersję, uruchamia `openclaw doctor` i restartuje Gateway.
|
||||
|
||||
```bash
|
||||
openclaw update
|
||||
```
|
||||
|
||||
Aby przełączyć kanały albo wskazać konkretną wersję:
|
||||
Aby przełączyć kanały lub wskazać konkretną wersję:
|
||||
|
||||
```bash
|
||||
openclaw update --channel beta
|
||||
@ -32,22 +32,23 @@ openclaw update --tag main
|
||||
openclaw update --dry-run # preview without applying
|
||||
```
|
||||
|
||||
`openclaw update` nie przyjmuje `--verbose`. Do diagnostyki aktualizacji użyj
|
||||
`--dry-run`, aby podejrzeć zaplanowane działania, `--json`, aby uzyskać wyniki strukturalne, albo
|
||||
`openclaw update status --json`, aby sprawdzić stan kanału i dostępności. Instalator ma własną flagę `--verbose`, ale ta flaga nie jest częścią
|
||||
`openclaw update` nie akceptuje `--verbose`. Do diagnostyki aktualizacji użyj
|
||||
`--dry-run`, aby podejrzeć planowane działania, `--json` do wyników strukturalnych albo
|
||||
`openclaw update status --json`, aby sprawdzić stan kanału i dostępności. Instalator
|
||||
ma własną flagę `--verbose`, ale ta flaga nie jest częścią
|
||||
`openclaw update`.
|
||||
|
||||
`--channel beta` preferuje betę, ale środowisko wykonawcze wraca do stable/latest, gdy
|
||||
tag beta nie istnieje albo jest starszy niż najnowsze stabilne wydanie. Użyj `--tag beta`,
|
||||
jeśli chcesz surowego npm dist-tag beta do jednorazowej aktualizacji pakietu.
|
||||
`--channel beta` preferuje kanał beta, ale środowisko uruchomieniowe wraca do stable/latest, gdy
|
||||
tag beta jest brakujący lub starszy niż najnowsze wydanie stabilne. Użyj `--tag beta`,
|
||||
jeśli chcesz surowy npm beta dist-tag dla jednorazowej aktualizacji pakietu.
|
||||
|
||||
Zobacz [Kanały deweloperskie](/pl/install/development-channels), aby poznać semantykę kanałów.
|
||||
|
||||
## Przełączanie między instalacjami npm i git
|
||||
|
||||
Używaj kanałów, gdy chcesz zmienić typ instalacji. Aktualizator zachowuje Twój
|
||||
stan, konfigurację, dane uwierzytelniające i obszar roboczy w `~/.openclaw`; zmienia tylko to,
|
||||
z której instalacji kodu OpenClaw korzystają CLI i gateway.
|
||||
stan, konfigurację, poświadczenia i obszar roboczy w `~/.openclaw`; zmienia tylko
|
||||
to, której instalacji kodu OpenClaw używają CLI i Gateway.
|
||||
|
||||
```bash
|
||||
# npm package install -> editable git checkout
|
||||
@ -66,10 +67,10 @@ openclaw update --channel stable --dry-run
|
||||
|
||||
Kanał `dev` zapewnia checkout git, buduje go i instaluje globalne CLI
|
||||
z tego checkoutu. Kanały `stable` i `beta` używają instalacji pakietowych. Jeśli
|
||||
gateway jest już zainstalowany, `openclaw update` odświeża metadane usługi
|
||||
Gateway jest już zainstalowany, `openclaw update` odświeża metadane usługi
|
||||
i restartuje ją, chyba że przekażesz `--no-restart`.
|
||||
|
||||
## Alternatywa: ponownie uruchom instalator
|
||||
## Alternatywa: ponowne uruchomienie instalatora
|
||||
|
||||
```bash
|
||||
curl -fsSL https://openclaw.ai/install.sh | bash
|
||||
@ -79,7 +80,7 @@ Dodaj `--no-onboard`, aby pominąć onboarding. Aby wymusić konkretny typ insta
|
||||
instalator, przekaż `--install-method git --no-onboard` albo
|
||||
`--install-method npm --no-onboard`.
|
||||
|
||||
Jeśli `openclaw update` nie powiedzie się po fazie instalacji pakietu npm, uruchom ponownie
|
||||
Jeśli `openclaw update` zakończy się niepowodzeniem po fazie instalacji pakietu npm, uruchom ponownie
|
||||
instalator. Instalator nie wywołuje starego aktualizatora; uruchamia bezpośrednio globalną
|
||||
instalację pakietu i może odzyskać częściowo zaktualizowaną instalację npm.
|
||||
|
||||
@ -87,24 +88,29 @@ instalację pakietu i może odzyskać częściowo zaktualizowaną instalację np
|
||||
curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method npm
|
||||
```
|
||||
|
||||
Aby przypiąć odzyskiwanie do konkretnej wersji albo dist-tag, dodaj `--version`:
|
||||
Aby przypiąć odzyskiwanie do konkretnej wersji lub dist-tag, dodaj `--version`:
|
||||
|
||||
```bash
|
||||
curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method npm --version <version-or-dist-tag>
|
||||
```
|
||||
|
||||
## Alternatywa: ręcznie przez npm, pnpm albo bun
|
||||
## Alternatywa: ręcznie przez npm, pnpm lub bun
|
||||
|
||||
```bash
|
||||
npm i -g openclaw@latest
|
||||
```
|
||||
|
||||
Gdy `openclaw update` zarządza globalną instalacją npm, najpierw instaluje cel w
|
||||
tymczasowym prefiksie npm, weryfikuje spis pakietowego `dist`, a następnie podmienia
|
||||
Preferuj `openclaw update` dla instalacji nadzorowanych, ponieważ może skoordynować
|
||||
podmianę pakietu z działającą usługą Gateway. Jeśli aktualizujesz ręcznie, gdy
|
||||
zarządzany Gateway działa, zrestartuj Gateway natychmiast po zakończeniu pracy
|
||||
menedżera pakietów, aby stary proces nie nadal obsługiwał plików z zastąpionego pakietu.
|
||||
|
||||
Gdy `openclaw update` zarządza globalną instalacją npm, najpierw instaluje cel do
|
||||
tymczasowego prefiksu npm, weryfikuje spis spakowanego `dist`, a następnie podmienia
|
||||
czyste drzewo pakietu do rzeczywistego globalnego prefiksu. Zapobiega to nakładaniu przez npm
|
||||
nowego pakietu na nieaktualne pliki ze starego pakietu. Jeśli polecenie instalacji się nie powiedzie,
|
||||
OpenClaw ponawia próbę raz z `--omit=optional`. Ta ponowna próba pomaga hostom, na których natywne
|
||||
opcjonalne zależności nie mogą się skompilować, zachowując widoczność pierwotnego błędu,
|
||||
nowego pakietu na przestarzałe pliki ze starego pakietu. Jeśli polecenie instalacji się nie powiedzie,
|
||||
OpenClaw ponawia próbę raz z `--omit=optional`. Ta próba pomaga hostom, na których natywne
|
||||
opcjonalne zależności nie mogą się skompilować, zachowując pierwotny błąd jako widoczny,
|
||||
jeśli obejście również się nie powiedzie.
|
||||
|
||||
```bash
|
||||
@ -118,22 +124,22 @@ bun add -g openclaw@latest
|
||||
### Zaawansowane tematy instalacji npm
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Drzewo pakietów tylko do odczytu">
|
||||
OpenClaw traktuje pakietowe instalacje globalne jako tylko do odczytu w czasie działania, nawet gdy globalny katalog pakietu jest zapisywalny dla bieżącego użytkownika. Instalacje pakietów Plugin znajdują się w należących do OpenClaw korzeniach npm/git w katalogu konfiguracji użytkownika, a uruchamianie Gateway nie modyfikuje drzewa pakietu OpenClaw.
|
||||
<Accordion title="Read-only package tree">
|
||||
OpenClaw traktuje spakowane instalacje globalne jako tylko do odczytu w czasie działania, nawet gdy globalny katalog pakietu jest zapisywalny dla bieżącego użytkownika. Instalacje pakietów Plugin znajdują się w należących do OpenClaw korzeniach npm/git pod katalogiem konfiguracji użytkownika, a uruchamianie Gateway nie modyfikuje drzewa pakietu OpenClaw.
|
||||
|
||||
Niektóre konfiguracje npm w Linuksie instalują pakiety globalne w katalogach należących do roota, takich jak `/usr/lib/node_modules/openclaw`. OpenClaw obsługuje taki układ, ponieważ polecenia instalacji/aktualizacji Plugin zapisują poza tym globalnym katalogiem pakietu.
|
||||
Niektóre konfiguracje npm w Linux instalują globalne pakiety w katalogach należących do root, takich jak `/usr/lib/node_modules/openclaw`. OpenClaw obsługuje taki układ, ponieważ polecenia instalacji/aktualizacji Plugin zapisują poza tym globalnym katalogiem pakietu.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Utwardzone jednostki systemd">
|
||||
Przyznaj OpenClaw dostęp zapisu do jego korzeni konfiguracji/stanu, aby jawne instalacje Plugin, aktualizacje Plugin i czyszczenie przez doctor mogły utrwalać swoje zmiany:
|
||||
<Accordion title="Hardened systemd units">
|
||||
Przyznaj OpenClaw dostęp do zapisu w jego korzeniach konfiguracji/stanu, aby jawne instalacje Plugin, aktualizacje Plugin i czyszczenie przez doctor mogły utrwalać swoje zmiany:
|
||||
|
||||
```ini
|
||||
ReadWritePaths=/var/lib/openclaw /home/openclaw/.openclaw /tmp
|
||||
```
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Wstępne sprawdzenie miejsca na dysku">
|
||||
Przed aktualizacjami pakietów i jawnymi instalacjami Plugin OpenClaw podejmuje najlepszą możliwą próbę sprawdzenia miejsca na dysku dla woluminu docelowego. Mała ilość miejsca powoduje ostrzeżenie ze sprawdzoną ścieżką, ale nie blokuje aktualizacji, ponieważ limity systemu plików, migawki i woluminy sieciowe mogą zmienić się po sprawdzeniu. Rzeczywista instalacja przez menedżera pakietów i weryfikacja po instalacji pozostają autorytatywne.
|
||||
<Accordion title="Disk-space preflight">
|
||||
Przed aktualizacjami pakietów i jawnymi instalacjami Plugin OpenClaw próbuje wykonać najlepszym możliwym wysiłkiem sprawdzenie miejsca na dysku dla woluminu docelowego. Mała ilość miejsca powoduje ostrzeżenie ze sprawdzoną ścieżką, ale nie blokuje aktualizacji, ponieważ limity systemu plików, migawki i woluminy sieciowe mogą się zmienić po sprawdzeniu. Faktyczna instalacja przez menedżera pakietów i weryfikacja po instalacji pozostają rozstrzygające.
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
@ -155,21 +161,21 @@ Automatyczny aktualizator jest domyślnie wyłączony. Włącz go w `~/.openclaw
|
||||
}
|
||||
```
|
||||
|
||||
| Kanał | Zachowanie |
|
||||
| -------- | ------------------------------------------------------------------------------------------------------------- |
|
||||
| `stable` | Czeka `stableDelayHours`, a następnie stosuje aktualizację z deterministycznym jitterem w ramach `stableJitterHours` (rozproszona wdrożenie). |
|
||||
| Kanał | Zachowanie |
|
||||
| -------- | ---------------------------------------------------------------------------------------------------------------- |
|
||||
| `stable` | Czeka `stableDelayHours`, a następnie stosuje z deterministycznym jitterem w zakresie `stableJitterHours` (rozłożone wdrożenie). |
|
||||
| `beta` | Sprawdza co `betaCheckIntervalHours` (domyślnie: co godzinę) i stosuje natychmiast. |
|
||||
| `dev` | Brak automatycznego stosowania. Użyj ręcznie `openclaw update`. |
|
||||
| `dev` | Brak automatycznego zastosowania. Użyj ręcznie `openclaw update`. |
|
||||
|
||||
Gateway zapisuje również wskazówkę aktualizacji przy starcie (wyłącz przez `update.checkOnStart: false`).
|
||||
W celu obniżenia wersji albo odzyskiwania po incydencie ustaw `OPENCLAW_NO_AUTO_UPDATE=1` w środowisku gateway, aby zablokować automatyczne stosowanie aktualizacji nawet wtedy, gdy skonfigurowano `update.auto.enabled`. Wskazówki aktualizacji przy starcie nadal mogą działać, chyba że `update.checkOnStart` także zostanie wyłączone.
|
||||
Gateway rejestruje także wskazówkę aktualizacyjną przy uruchomieniu (wyłącz przez `update.checkOnStart: false`).
|
||||
W celu downgrade’u lub odzyskiwania po incydencie ustaw `OPENCLAW_NO_AUTO_UPDATE=1` w środowisku Gateway, aby blokować automatyczne zastosowania nawet wtedy, gdy skonfigurowano `update.auto.enabled`. Wskazówki aktualizacyjne przy uruchomieniu nadal mogą działać, chyba że wyłączono także `update.checkOnStart`.
|
||||
|
||||
Aktualizacje menedżera pakietów żądane przez aktywny handler płaszczyzny sterowania Gateway
|
||||
wymuszają restart aktualizacji bez odroczenia i bez cooldownu po podmianie pakietu. Pozwala to
|
||||
uniknąć pozostawienia starego procesu w pamięci na tyle długo, aby leniwie załadował fragmenty
|
||||
wymuszają restart aktualizacji bez odroczenia i bez cooldownu po podmianie pakietu. To
|
||||
pozwala uniknąć pozostawienia starego procesu w pamięci wystarczająco długo, by leniwie ładował fragmenty
|
||||
z drzewa pakietu, które zostało już zastąpione. Powłokowe `openclaw update`
|
||||
pozostaje preferowaną ścieżką dla instalacji nadzorowanych, ponieważ może zatrzymać i
|
||||
zrestartować usługę wokół aktualizacji.
|
||||
uruchomić ponownie usługę wokół aktualizacji.
|
||||
|
||||
## Po aktualizacji
|
||||
|
||||
@ -181,9 +187,9 @@ zrestartować usługę wokół aktualizacji.
|
||||
openclaw doctor
|
||||
```
|
||||
|
||||
Migruje konfigurację, audytuje zasady DM i sprawdza kondycję gateway. Szczegóły: [Doctor](/pl/gateway/doctor)
|
||||
Migruje konfigurację, audytuje polityki DM i sprawdza kondycję Gateway. Szczegóły: [Doctor](/pl/gateway/doctor)
|
||||
|
||||
### Zrestartuj gateway
|
||||
### Uruchom ponownie Gateway
|
||||
|
||||
```bash
|
||||
openclaw gateway restart
|
||||
@ -208,10 +214,10 @@ openclaw gateway restart
|
||||
```
|
||||
|
||||
<Tip>
|
||||
`npm view openclaw version` pokazuje bieżącą opublikowaną wersję.
|
||||
`npm view openclaw version` pokazuje aktualnie opublikowaną wersję.
|
||||
</Tip>
|
||||
|
||||
### Przypnij commit (źródła)
|
||||
### Przypnij commit (źródło)
|
||||
|
||||
```bash
|
||||
git fetch origin
|
||||
@ -224,7 +230,7 @@ Aby wrócić do najnowszej wersji: `git checkout main && git pull`.
|
||||
|
||||
## Jeśli utkniesz
|
||||
|
||||
- Uruchom ponownie `openclaw doctor` i uważnie przeczytaj dane wyjściowe.
|
||||
- Uruchom ponownie `openclaw doctor` i uważnie przeczytaj wynik.
|
||||
- Dla `openclaw update --channel dev` na checkoutach źródłowych aktualizator automatycznie bootstrapuje `pnpm`, gdy jest to potrzebne. Jeśli zobaczysz błąd bootstrapu pnpm/corepack, zainstaluj `pnpm` ręcznie (albo ponownie włącz `corepack`) i uruchom aktualizację ponownie.
|
||||
- Sprawdź: [Rozwiązywanie problemów](/pl/gateway/troubleshooting)
|
||||
- Zapytaj na Discord: [https://discord.gg/clawd](https://discord.gg/clawd)
|
||||
@ -233,4 +239,4 @@ Aby wrócić do najnowszej wersji: `git checkout main && git pull`.
|
||||
|
||||
- [Przegląd instalacji](/pl/install): wszystkie metody instalacji.
|
||||
- [Doctor](/pl/gateway/doctor): kontrole kondycji po aktualizacjach.
|
||||
- [Migracja](/pl/install/migrating): przewodniki po migracji głównych wersji.
|
||||
- [Migracja](/pl/install/migrating): przewodniki migracji głównych wersji.
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@ -1,35 +1,35 @@
|
||||
---
|
||||
read_when:
|
||||
- Chcesz wykonać wychodzące połączenie głosowe z poziomu OpenClaw
|
||||
- Chcesz nawiązać wychodzące połączenie głosowe z poziomu OpenClaw
|
||||
- Konfigurujesz lub rozwijasz Plugin do połączeń głosowych
|
||||
- Potrzebujesz głosu w czasie rzeczywistym lub transkrypcji strumieniowej w telefonii
|
||||
sidebarTitle: Voice call
|
||||
summary: Wykonuj wychodzące i odbieraj przychodzące połączenia głosowe za pośrednictwem Twilio, Telnyx lub Plivo, z opcjonalną obsługą głosu w czasie rzeczywistym i strumieniowej transkrypcji
|
||||
summary: Nawiązuj wychodzące i odbieraj przychodzące połączenia głosowe za pośrednictwem Twilio, Telnyx lub Plivo, z opcjonalną obsługą głosu w czasie rzeczywistym i transkrypcji strumieniowej
|
||||
title: Plugin połączeń głosowych
|
||||
x-i18n:
|
||||
generated_at: "2026-05-02T22:22:16Z"
|
||||
generated_at: "2026-05-04T07:05:36Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 18a9a0d7095ec92036b516cc26c69219a0a2fd9bb8e0cb2e7509123bb4f3f65a
|
||||
source_hash: 8ec2c22dcc9073572963744685a432328787bcedb14025e0326c20d9d842f857
|
||||
source_path: plugins/voice-call.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
Voice calls for OpenClaw via a plugin. Supports outbound notifications,
|
||||
multi-turn conversations, full-duplex realtime voice, streaming
|
||||
transcription, and inbound calls with allowlist policies.
|
||||
Połączenia głosowe dla OpenClaw przez plugin. Obsługuje powiadomienia wychodzące,
|
||||
rozmowy wieloturowe, pełnodupleksowy głos w czasie rzeczywistym, strumieniową
|
||||
transkrypcję oraz połączenia przychodzące z zasadami listy dozwolonych.
|
||||
|
||||
**Current providers:** `twilio` (Programmable Voice + Media Streams),
|
||||
**Obecni dostawcy:** `twilio` (Programmable Voice + Media Streams),
|
||||
`telnyx` (Call Control v2), `plivo` (Voice API + XML transfer + GetInput
|
||||
speech), `mock` (dev/no network).
|
||||
speech), `mock` (dev/brak sieci).
|
||||
|
||||
<Note>
|
||||
The Voice Call plugin runs **inside the Gateway process**. If you use a
|
||||
remote Gateway, install and configure the plugin on the machine running
|
||||
the Gateway, then restart the Gateway to load it.
|
||||
Plugin Voice Call działa **wewnątrz procesu Gateway**. Jeśli używasz
|
||||
zdalnego Gateway, zainstaluj i skonfiguruj plugin na maszynie uruchamiającej
|
||||
Gateway, a następnie zrestartuj Gateway, aby go wczytać.
|
||||
</Note>
|
||||
|
||||
## Quick start
|
||||
## Szybki start
|
||||
|
||||
<Steps>
|
||||
<Step title="Install the plugin">
|
||||
@ -48,27 +48,27 @@ the Gateway, then restart the Gateway to load it.
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
Use the bare package to follow the current official release tag. Pin an
|
||||
exact version only when you need a reproducible install.
|
||||
Użyj samej nazwy pakietu, aby śledzić bieżący oficjalny tag wydania. Przypinaj
|
||||
dokładną wersję tylko wtedy, gdy potrzebujesz powtarzalnej instalacji.
|
||||
|
||||
Restart the Gateway afterwards so the plugin loads.
|
||||
Następnie zrestartuj Gateway, aby plugin został wczytany.
|
||||
|
||||
</Step>
|
||||
<Step title="Configure provider and webhook">
|
||||
Set config under `plugins.entries.voice-call.config` (see
|
||||
[Configuration](#configuration) below for the full shape). At minimum:
|
||||
`provider`, provider credentials, `fromNumber`, and a publicly
|
||||
reachable webhook URL.
|
||||
Ustaw konfigurację w `plugins.entries.voice-call.config` (pełny kształt znajdziesz
|
||||
niżej w sekcji [Konfiguracja](#configuration)). Co najmniej:
|
||||
`provider`, poświadczenia dostawcy, `fromNumber` oraz publicznie
|
||||
dostępny URL Webhook.
|
||||
</Step>
|
||||
<Step title="Verify setup">
|
||||
```bash
|
||||
openclaw voicecall setup
|
||||
```
|
||||
|
||||
The default output is readable in chat logs and terminals. It checks
|
||||
plugin enablement, provider credentials, webhook exposure, and that
|
||||
only one audio mode (`streaming` or `realtime`) is active. Use
|
||||
`--json` for scripts.
|
||||
Domyślne wyjście jest czytelne w logach czatu i terminalach. Sprawdza
|
||||
włączenie pluginu, poświadczenia dostawcy, ekspozycję Webhook oraz to,
|
||||
że aktywny jest tylko jeden tryb audio (`streaming` albo `realtime`). Użyj
|
||||
`--json` w skryptach.
|
||||
|
||||
</Step>
|
||||
<Step title="Smoke test">
|
||||
@ -77,8 +77,8 @@ the Gateway, then restart the Gateway to load it.
|
||||
openclaw voicecall smoke --to "+15555550123"
|
||||
```
|
||||
|
||||
Both are dry runs by default. Add `--yes` to actually place a short
|
||||
outbound notify call:
|
||||
Oba polecenia domyślnie są próbami bez wykonania zmian. Dodaj `--yes`, aby faktycznie wykonać krótkie
|
||||
połączenie wychodzące z powiadomieniem:
|
||||
|
||||
```bash
|
||||
openclaw voicecall smoke --to "+15555550123" --yes
|
||||
@ -88,21 +88,21 @@ the Gateway, then restart the Gateway to load it.
|
||||
</Steps>
|
||||
|
||||
<Warning>
|
||||
For Twilio, Telnyx, and Plivo, setup must resolve to a **public webhook URL**.
|
||||
If `publicUrl`, the tunnel URL, the Tailscale URL, or the serve fallback
|
||||
resolves to loopback or private network space, setup fails instead of
|
||||
starting a provider that cannot receive carrier webhooks.
|
||||
Dla Twilio, Telnyx i Plivo konfiguracja musi wskazywać **publiczny URL Webhook**.
|
||||
Jeśli `publicUrl`, URL tunelu, URL Tailscale albo zapasowa ścieżka udostępniania
|
||||
rozwiązuje się do loopback lub prywatnej przestrzeni sieciowej, konfiguracja kończy się niepowodzeniem zamiast
|
||||
uruchamiać dostawcę, który nie może odbierać webhooków operatorów.
|
||||
</Warning>
|
||||
|
||||
## Configuration
|
||||
## Konfiguracja
|
||||
|
||||
If `enabled: true` but the selected provider is missing credentials,
|
||||
Gateway startup logs a setup-incomplete warning with the missing keys and
|
||||
skips starting the runtime. Commands, RPC calls, and agent tools still
|
||||
return the exact missing provider configuration when used.
|
||||
Jeśli `enabled: true`, ale wybranemu dostawcy brakuje poświadczeń,
|
||||
uruchamianie Gateway zapisuje ostrzeżenie o niepełnej konfiguracji z brakującymi kluczami i
|
||||
pomija uruchomienie środowiska wykonawczego. Polecenia, wywołania RPC i narzędzia agenta nadal
|
||||
zwracają dokładnie brakującą konfigurację dostawcy, gdy są używane.
|
||||
|
||||
<Note>
|
||||
Voice-call credentials accept SecretRefs. `plugins.entries.voice-call.config.twilio.authToken`, `plugins.entries.voice-call.config.realtime.providers.*.apiKey`, `plugins.entries.voice-call.config.streaming.providers.*.apiKey`, and `plugins.entries.voice-call.config.tts.providers.*.apiKey` resolve through the standard SecretRef surface; see [SecretRef credential surface](/pl/reference/secretref-credential-surface).
|
||||
Poświadczenia Voice Call akceptują SecretRefs. `plugins.entries.voice-call.config.twilio.authToken`, `plugins.entries.voice-call.config.realtime.providers.*.apiKey`, `plugins.entries.voice-call.config.streaming.providers.*.apiKey` i `plugins.entries.voice-call.config.tts.providers.*.apiKey` są rozwiązywane przez standardową powierzchnię SecretRef; zobacz [powierzchnia poświadczeń SecretRef](/pl/reference/secretref-credential-surface).
|
||||
</Note>
|
||||
|
||||
```json5
|
||||
@ -176,30 +176,30 @@ Voice-call credentials accept SecretRefs. `plugins.entries.voice-call.config.twi
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Provider exposure and security notes">
|
||||
- Twilio, Telnyx, and Plivo all require a **publicly reachable** webhook URL.
|
||||
- `mock` is a local dev provider (no network calls).
|
||||
- Telnyx requires `telnyx.publicKey` (or `TELNYX_PUBLIC_KEY`) unless `skipSignatureVerification` is true.
|
||||
- `skipSignatureVerification` is for local testing only.
|
||||
- On ngrok free tier, set `publicUrl` to the exact ngrok URL; signature verification is always enforced.
|
||||
- `tunnel.allowNgrokFreeTierLoopbackBypass: true` allows Twilio webhooks with invalid signatures **only** when `tunnel.provider="ngrok"` and `serve.bind` is loopback (ngrok local agent). Local dev only.
|
||||
- Ngrok free-tier URLs can change or add interstitial behaviour; if `publicUrl` drifts, Twilio signatures fail. Production: prefer a stable domain or a Tailscale funnel.
|
||||
- Twilio, Telnyx i Plivo wymagają **publicznie osiągalnego** URL Webhook.
|
||||
- `mock` to lokalny dostawca deweloperski (bez wywołań sieciowych).
|
||||
- Telnyx wymaga `telnyx.publicKey` (albo `TELNYX_PUBLIC_KEY`), chyba że `skipSignatureVerification` ma wartość true.
|
||||
- `skipSignatureVerification` jest przeznaczone wyłącznie do testów lokalnych.
|
||||
- W darmowym planie ngrok ustaw `publicUrl` na dokładny URL ngrok; weryfikacja podpisu jest zawsze wymuszana.
|
||||
- `tunnel.allowNgrokFreeTierLoopbackBypass: true` zezwala na webhooki Twilio z nieprawidłowymi podpisami **tylko** wtedy, gdy `tunnel.provider="ngrok"` i `serve.bind` jest loopback (lokalny agent ngrok). Tylko lokalny dev.
|
||||
- URL-e darmowego planu ngrok mogą się zmieniać albo dodawać stronę pośrednią; jeśli `publicUrl` się rozjedzie, podpisy Twilio zawiodą. Produkcja: preferuj stabilną domenę albo lejek Tailscale.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Streaming connection caps">
|
||||
- `streaming.preStartTimeoutMs` closes sockets that never send a valid `start` frame.
|
||||
- `streaming.maxPendingConnections` caps total unauthenticated pre-start sockets.
|
||||
- `streaming.maxPendingConnectionsPerIp` caps unauthenticated pre-start sockets per source IP.
|
||||
- `streaming.maxConnections` caps total open media stream sockets (pending + active).
|
||||
- `streaming.preStartTimeoutMs` zamyka gniazda, które nigdy nie wysyłają prawidłowej ramki `start`.
|
||||
- `streaming.maxPendingConnections` ogranicza łączną liczbę nieuwierzytelnionych gniazd przed startem.
|
||||
- `streaming.maxPendingConnectionsPerIp` ogranicza nieuwierzytelnione gniazda przed startem dla każdego źródłowego adresu IP.
|
||||
- `streaming.maxConnections` ogranicza łączną liczbę otwartych gniazd strumienia mediów (oczekujących + aktywnych).
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Legacy config migrations">
|
||||
Older configs using `provider: "log"`, `twilio.from`, or legacy
|
||||
`streaming.*` OpenAI keys are rewritten by `openclaw doctor --fix`.
|
||||
Runtime fallback still accepts the old voice-call keys for now, but
|
||||
the rewrite path is `openclaw doctor --fix` and the compat shim is
|
||||
temporary.
|
||||
Starsze konfiguracje używające `provider: "log"`, `twilio.from` albo starszych
|
||||
kluczy OpenAI `streaming.*` są przepisywane przez `openclaw doctor --fix`.
|
||||
Zapasowa obsługa w środowisku wykonawczym na razie nadal akceptuje stare klucze voice-call, ale
|
||||
ścieżką przepisywania jest `openclaw doctor --fix`, a warstwa zgodności jest
|
||||
tymczasowa.
|
||||
|
||||
Auto-migrated streaming keys:
|
||||
Automatycznie migrowane klucze streaming:
|
||||
|
||||
- `streaming.sttProvider` → `streaming.provider`
|
||||
- `streaming.openaiApiKey` → `streaming.providers.openai.apiKey`
|
||||
@ -210,53 +210,56 @@ Voice-call credentials accept SecretRefs. `plugins.entries.voice-call.config.twi
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## Session scope
|
||||
## Zakres sesji
|
||||
|
||||
By default, Voice Call uses `sessionScope: "per-phone"` so repeat calls from
|
||||
the same caller keep conversation memory. Set `sessionScope: "per-call"` when
|
||||
each carrier call should start with fresh context, for example reception,
|
||||
booking, IVR, or Google Meet bridge flows where the same phone number may
|
||||
represent different meetings.
|
||||
Domyślnie Voice Call używa `sessionScope: "per-phone"`, więc kolejne połączenia od
|
||||
tego samego dzwoniącego zachowują pamięć rozmowy. Ustaw `sessionScope: "per-call"`, gdy
|
||||
każde połączenie operatora powinno zaczynać ze świeżym kontekstem, na przykład w recepcji,
|
||||
rezerwacjach, IVR albo przepływach mostka Google Meet, gdzie ten sam numer telefonu może
|
||||
reprezentować różne spotkania.
|
||||
|
||||
## Realtime voice conversations
|
||||
## Rozmowy głosowe w czasie rzeczywistym
|
||||
|
||||
`realtime` selects a full-duplex realtime voice provider for live call
|
||||
audio. It is separate from `streaming`, which only forwards audio to
|
||||
realtime transcription providers.
|
||||
`realtime` wybiera pełnodupleksowego dostawcę głosu w czasie rzeczywistym dla dźwięku
|
||||
połączenia na żywo. Jest to oddzielne od `streaming`, które tylko przekazuje dźwięk do
|
||||
dostawców transkrypcji w czasie rzeczywistym.
|
||||
|
||||
<Warning>
|
||||
`realtime.enabled` cannot be combined with `streaming.enabled`. Pick one
|
||||
audio mode per call.
|
||||
`realtime.enabled` nie może być łączone z `streaming.enabled`. Wybierz jeden
|
||||
tryb audio na połączenie.
|
||||
</Warning>
|
||||
|
||||
Current runtime behaviour:
|
||||
Bieżące zachowanie środowiska wykonawczego:
|
||||
|
||||
- `realtime.enabled` is supported for Twilio Media Streams.
|
||||
- `realtime.provider` is optional. If unset, Voice Call uses the first registered realtime voice provider.
|
||||
- Bundled realtime voice providers: Google Gemini Live (`google`) and OpenAI (`openai`), registered by their provider plugins.
|
||||
- Provider-owned raw config lives under `realtime.providers.<providerId>`.
|
||||
- Voice Call exposes the shared `openclaw_agent_consult` realtime tool by default. The realtime model can call it when the caller asks for deeper reasoning, current information, or normal OpenClaw tools.
|
||||
- `realtime.fastContext.enabled` is default-off. When enabled, Voice Call first searches indexed memory/session context for the consult question and returns those snippets to the realtime model within `realtime.fastContext.timeoutMs` before falling back to the full consult agent only if `realtime.fastContext.fallbackToConsult` is true.
|
||||
- If `realtime.provider` points at an unregistered provider, or no realtime voice provider is registered at all, Voice Call logs a warning and skips realtime media instead of failing the whole plugin.
|
||||
- Consult session keys reuse the stored call session when available, then fall back to the configured `sessionScope` (`per-phone` by default, or `per-call` for isolated calls).
|
||||
- `realtime.enabled` jest obsługiwane dla Twilio Media Streams.
|
||||
- `realtime.provider` jest opcjonalne. Jeśli nie jest ustawione, Voice Call używa pierwszego zarejestrowanego dostawcy głosu w czasie rzeczywistym.
|
||||
- Dołączeni dostawcy głosu w czasie rzeczywistym: Google Gemini Live (`google`) i OpenAI (`openai`), rejestrowani przez ich pluginy dostawców.
|
||||
- Surowa konfiguracja właściciela dostawcy znajduje się pod `realtime.providers.<providerId>`.
|
||||
- Voice Call domyślnie udostępnia współdzielone narzędzie czasu rzeczywistego `openclaw_agent_consult`. Model czasu rzeczywistego może je wywołać, gdy dzwoniący prosi o głębsze rozumowanie, aktualne informacje albo standardowe narzędzia OpenClaw.
|
||||
- `realtime.fastContext.enabled` jest domyślnie wyłączone. Po włączeniu Voice Call najpierw przeszukuje zaindeksowaną pamięć/kontekst sesji dla pytania konsultacji i zwraca te fragmenty modelowi czasu rzeczywistego w czasie `realtime.fastContext.timeoutMs`, zanim przejdzie do pełnego agenta konsultacji tylko wtedy, gdy `realtime.fastContext.fallbackToConsult` ma wartość true.
|
||||
- Jeśli `realtime.provider` wskazuje niezarejestrowanego dostawcę albo żaden dostawca głosu w czasie rzeczywistym nie jest w ogóle zarejestrowany, Voice Call zapisuje ostrzeżenie i pomija media czasu rzeczywistego zamiast powodować awarię całego pluginu.
|
||||
- Klucze sesji konsultacji ponownie używają zapisanej sesji połączenia, gdy jest dostępna, a następnie przechodzą do skonfigurowanego `sessionScope` (`per-phone` domyślnie albo `per-call` dla izolowanych połączeń).
|
||||
|
||||
### Tool policy
|
||||
### Zasady narzędzi
|
||||
|
||||
`realtime.toolPolicy` controls the consult run:
|
||||
`realtime.toolPolicy` kontroluje przebieg konsultacji:
|
||||
|
||||
| Policy | Behavior |
|
||||
| Zasada | Zachowanie |
|
||||
| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `safe-read-only` | Expose the consult tool and limit the regular agent to `read`, `web_search`, `web_fetch`, `x_search`, `memory_search`, and `memory_get`. |
|
||||
| `owner` | Expose the consult tool and let the regular agent use the normal agent tool policy. |
|
||||
| `none` | Do not expose the consult tool. Custom `realtime.tools` are still passed through to the realtime provider. |
|
||||
| `safe-read-only` | Udostępnij narzędzie konsultacji i ogranicz zwykłego agenta do `read`, `web_search`, `web_fetch`, `x_search`, `memory_search` i `memory_get`. |
|
||||
| `owner` | Udostępnij narzędzie konsultacji i pozwól zwykłemu agentowi używać normalnych zasad narzędzi agenta. |
|
||||
| `none` | Nie udostępniaj narzędzia konsultacji. Niestandardowe `realtime.tools` nadal są przekazywane do dostawcy czasu rzeczywistego. |
|
||||
|
||||
### Realtime provider examples
|
||||
### Przykłady dostawców czasu rzeczywistego
|
||||
|
||||
<Tabs>
|
||||
<Tab title="Google Gemini Live">
|
||||
Defaults: API key from `realtime.providers.google.apiKey`,
|
||||
`GEMINI_API_KEY`, or `GOOGLE_GENERATIVE_AI_API_KEY`; model
|
||||
`gemini-2.5-flash-native-audio-preview-12-2025`; voice `Kore`.
|
||||
Wartości domyślne: klucz API z `realtime.providers.google.apiKey`,
|
||||
`GEMINI_API_KEY` albo `GOOGLE_GENERATIVE_AI_API_KEY`; model
|
||||
`gemini-2.5-flash-native-audio-preview-12-2025`; głos `Kore`.
|
||||
`sessionResumption` i `contextWindowCompression` są domyślnie włączone dla dłuższych,
|
||||
wznawialnych połączeń. Użyj `silenceDurationMs`, `startSensitivity` i
|
||||
`endSensitivity`, aby dostroić szybsze przejmowanie tury przy dźwięku telefonicznym.
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -277,6 +280,8 @@ Current runtime behaviour:
|
||||
apiKey: "${GEMINI_API_KEY}",
|
||||
model: "gemini-2.5-flash-native-audio-preview-12-2025",
|
||||
voice: "Kore",
|
||||
silenceDurationMs: 500,
|
||||
startSensitivity: "high",
|
||||
},
|
||||
},
|
||||
},
|
||||
@ -311,21 +316,21 @@ Current runtime behaviour:
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
See [Google provider](/pl/providers/google) and
|
||||
[OpenAI provider](/pl/providers/openai) for provider-specific realtime voice
|
||||
options.
|
||||
Zobacz [dostawcę Google](/pl/providers/google) i
|
||||
[dostawcę OpenAI](/pl/providers/openai), aby poznać opcje głosu w czasie rzeczywistym
|
||||
specyficzne dla dostawcy.
|
||||
|
||||
## Streaming transcription
|
||||
## Transkrypcja strumieniowa
|
||||
|
||||
`streaming` selects a realtime transcription provider for live call audio.
|
||||
`streaming` wybiera dostawcę transkrypcji w czasie rzeczywistym dla dźwięku rozmowy na żywo.
|
||||
|
||||
Current runtime behavior:
|
||||
Bieżące zachowanie środowiska uruchomieniowego:
|
||||
|
||||
- `streaming.provider` jest opcjonalne. Jeśli nie jest ustawione, Voice Call używa pierwszego zarejestrowanego dostawcy transkrypcji w czasie rzeczywistym.
|
||||
- Dołączone dostawcy transkrypcji w czasie rzeczywistym: Deepgram (`deepgram`), ElevenLabs (`elevenlabs`), Mistral (`mistral`), OpenAI (`openai`) i xAI (`xai`), rejestrowani przez swoje Pluginy dostawców.
|
||||
- Surowa konfiguracja należąca do dostawcy znajduje się w `streaming.providers.<providerId>`.
|
||||
- Gdy Twilio wyśle zaakceptowany komunikat `start` strumienia, Voice Call natychmiast rejestruje strumień, kolejkowuje przychodzące media przez dostawcę transkrypcji podczas łączenia dostawcy i uruchamia początkowe powitanie dopiero wtedy, gdy transkrypcja w czasie rzeczywistym jest gotowa.
|
||||
- Jeśli `streaming.provider` wskazuje niezarejestrowanego dostawcę albo żaden dostawca nie jest zarejestrowany, Voice Call zapisuje ostrzeżenie w logu i pomija strumieniowanie multimediów zamiast powodować awarię całego Pluginu.
|
||||
- Wbudowani dostawcy transkrypcji w czasie rzeczywistym: Deepgram (`deepgram`), ElevenLabs (`elevenlabs`), Mistral (`mistral`), OpenAI (`openai`) oraz xAI (`xai`), rejestrowani przez ich pluginy dostawców.
|
||||
- Surowa konfiguracja należąca do dostawcy znajduje się pod `streaming.providers.<providerId>`.
|
||||
- Po wysłaniu przez Twilio zaakceptowanej wiadomości `start` strumienia Voice Call natychmiast rejestruje strumień, kolejkuje przychodzące media przez dostawcę transkrypcji podczas łączenia dostawcy i uruchamia początkowe powitanie dopiero wtedy, gdy transkrypcja w czasie rzeczywistym jest gotowa.
|
||||
- Jeśli `streaming.provider` wskazuje niezarejestrowanego dostawcę albo żaden dostawca nie jest zarejestrowany, Voice Call zapisuje ostrzeżenie w logach i pomija strumieniowanie mediów zamiast powodować błąd całego pluginu.
|
||||
|
||||
### Przykłady dostawców strumieniowania
|
||||
|
||||
@ -397,8 +402,8 @@ Current runtime behavior:
|
||||
|
||||
## TTS dla połączeń
|
||||
|
||||
Voice Call używa podstawowej konfiguracji `messages.tts` do strumieniowania
|
||||
mowy w połączeniach. Możesz nadpisać ją w konfiguracji Pluginu przy użyciu
|
||||
Voice Call używa podstawowej konfiguracji `messages.tts` do strumieniowej
|
||||
mowy w połączeniach. Możesz ją nadpisać w konfiguracji pluginu za pomocą
|
||||
**tego samego kształtu** — jest ona głęboko scalana z `messages.tts`.
|
||||
|
||||
```json5
|
||||
@ -416,22 +421,22 @@ mowy w połączeniach. Możesz nadpisać ją w konfiguracji Pluginu przy użyciu
|
||||
```
|
||||
|
||||
<Warning>
|
||||
**Microsoft speech jest ignorowane dla połączeń głosowych.** Audio telefoniczne wymaga PCM;
|
||||
obecny transport Microsoft nie udostępnia wyjścia telefonicznego PCM.
|
||||
**Microsoft speech jest ignorowany dla połączeń głosowych.** Dźwięk telefoniczny wymaga PCM;
|
||||
bieżący transport Microsoft nie udostępnia telefonicznego wyjścia PCM.
|
||||
</Warning>
|
||||
|
||||
Uwagi dotyczące zachowania:
|
||||
|
||||
- Starsze klucze `tts.<provider>` w konfiguracji Pluginu (`openai`, `elevenlabs`, `microsoft`, `edge`) są naprawiane przez `openclaw doctor --fix`; zatwierdzona konfiguracja powinna używać `tts.providers.<provider>`.
|
||||
- Podstawowe TTS jest używane, gdy strumieniowanie multimediów Twilio jest włączone; w przeciwnym razie połączenia wracają do natywnych głosów dostawcy.
|
||||
- Jeśli strumień multimediów Twilio jest już aktywny, Voice Call nie wraca do TwiML `<Say>`. Jeśli telefoniczne TTS jest w tym stanie niedostępne, żądanie odtwarzania kończy się niepowodzeniem zamiast mieszać dwie ścieżki odtwarzania.
|
||||
- Starsze klucze `tts.<provider>` w konfiguracji pluginu (`openai`, `elevenlabs`, `microsoft`, `edge`) są naprawiane przez `openclaw doctor --fix`; zatwierdzona konfiguracja powinna używać `tts.providers.<provider>`.
|
||||
- Podstawowe TTS jest używane, gdy strumieniowanie mediów Twilio jest włączone; w przeciwnym razie połączenia wracają do natywnych głosów dostawcy.
|
||||
- Jeśli strumień mediów Twilio jest już aktywny, Voice Call nie wraca do TwiML `<Say>`. Jeśli telefoniczne TTS jest w tym stanie niedostępne, żądanie odtwarzania kończy się błędem zamiast mieszać dwie ścieżki odtwarzania.
|
||||
- Gdy telefoniczne TTS wraca do dostawcy zapasowego, Voice Call zapisuje ostrzeżenie z łańcuchem dostawców (`from`, `to`, `attempts`) na potrzeby debugowania.
|
||||
- Gdy barge-in Twilio lub zamknięcie strumienia czyści oczekującą kolejkę TTS, zakolejkowane żądania odtwarzania zostają rozstrzygnięte zamiast zawieszać dzwoniących oczekujących na ukończenie odtwarzania.
|
||||
- Gdy barge-in Twilio lub zamknięcie strumienia czyści oczekującą kolejkę TTS, zakolejkowane żądania odtwarzania są rozstrzygane zamiast zawieszać rozmówców oczekujących na zakończenie odtwarzania.
|
||||
|
||||
### Przykłady TTS
|
||||
|
||||
<Tabs>
|
||||
<Tab title="Core TTS only">
|
||||
<Tab title="Tylko podstawowe TTS">
|
||||
```json5
|
||||
{
|
||||
messages: {
|
||||
@ -445,7 +450,7 @@ Uwagi dotyczące zachowania:
|
||||
}
|
||||
```
|
||||
</Tab>
|
||||
<Tab title="Override to ElevenLabs (calls only)">
|
||||
<Tab title="Nadpisanie na ElevenLabs (tylko połączenia)">
|
||||
```json5
|
||||
{
|
||||
plugins: {
|
||||
@ -469,7 +474,7 @@ Uwagi dotyczące zachowania:
|
||||
}
|
||||
```
|
||||
</Tab>
|
||||
<Tab title="OpenAI model override (deep-merge)">
|
||||
<Tab title="Nadpisanie modelu OpenAI (głębokie scalanie)">
|
||||
```json5
|
||||
{
|
||||
plugins: {
|
||||
@ -495,7 +500,7 @@ Uwagi dotyczące zachowania:
|
||||
|
||||
## Połączenia przychodzące
|
||||
|
||||
Polityka połączeń przychodzących ma domyślną wartość `disabled`. Aby włączyć połączenia przychodzące, ustaw:
|
||||
Domyślna polityka połączeń przychodzących to `disabled`. Aby włączyć połączenia przychodzące, ustaw:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -506,22 +511,21 @@ Polityka połączeń przychodzących ma domyślną wartość `disabled`. Aby wł
|
||||
```
|
||||
|
||||
<Warning>
|
||||
`inboundPolicy: "allowlist"` to niskopewnościowy filtr identyfikatora dzwoniącego. Plugin
|
||||
normalizuje dostarczoną przez dostawcę wartość `From` i porównuje ją z
|
||||
`inboundPolicy: "allowlist"` to ekran identyfikacji numeru dzwoniącego o niskim poziomie pewności. Plugin normalizuje dostarczoną przez dostawcę wartość `From` i porównuje ją z
|
||||
`allowFrom`. Weryfikacja Webhook uwierzytelnia dostarczenie przez dostawcę i
|
||||
integralność ładunku, ale **nie** dowodzi własności numeru dzwoniącego
|
||||
PSTN/VoIP. Traktuj `allowFrom` jako filtrowanie identyfikatora dzwoniącego, a nie silną
|
||||
integralność ładunku, ale **nie** potwierdza własności numeru dzwoniącego
|
||||
PSTN/VoIP. Traktuj `allowFrom` jako filtrowanie identyfikacji numeru dzwoniącego, a nie silną
|
||||
tożsamość dzwoniącego.
|
||||
</Warning>
|
||||
|
||||
Automatyczne odpowiedzi używają systemu agenta. Dostrój je za pomocą `responseModel`,
|
||||
Automatyczne odpowiedzi używają systemu agentów. Dostosuj je za pomocą `responseModel`,
|
||||
`responseSystemPrompt` i `responseTimeoutMs`.
|
||||
|
||||
### Routing według numeru
|
||||
|
||||
Użyj `numbers`, gdy jeden Plugin Voice Call odbiera połączenia dla wielu numerów telefonu
|
||||
i każdy numer powinien zachowywać się jak inna linia. Na przykład jeden
|
||||
numer może używać swobodnego osobistego asystenta, a inny osobowości biznesowej,
|
||||
Użyj `numbers`, gdy jeden plugin Voice Call odbiera połączenia dla wielu numerów
|
||||
telefonów, a każdy numer powinien zachowywać się jak osobna linia. Na przykład jeden
|
||||
numer może używać swobodnego osobistego asystenta, a inny persony biznesowej,
|
||||
innego agenta odpowiedzi i innego głosu TTS.
|
||||
|
||||
Trasy są wybierane na podstawie dostarczonego przez dostawcę wybranego numeru `To`. Klucze muszą być
|
||||
@ -532,7 +536,7 @@ TTS. Jeśli żadna trasa nie pasuje, używana jest globalna konfiguracja Voice C
|
||||
Połączenia wychodzące nie używają `numbers`; podczas inicjowania połączenia przekaż jawnie cel wychodzący, wiadomość i
|
||||
sesję.
|
||||
|
||||
Nadpisania tras obsługują obecnie:
|
||||
Nadpisania tras obecnie obsługują:
|
||||
|
||||
- `inboundGreeting`
|
||||
- `tts`
|
||||
@ -541,7 +545,7 @@ Nadpisania tras obsługują obecnie:
|
||||
- `responseSystemPrompt`
|
||||
- `responseTimeoutMs`
|
||||
|
||||
Wartość trasy `tts` jest głęboko scalana z globalną konfiguracją `tts` Voice Call, więc
|
||||
Wartość trasy `tts` jest głęboko scalana z globalną konfiguracją Voice Call `tts`, więc
|
||||
zwykle możesz nadpisać tylko głos dostawcy:
|
||||
|
||||
```json5
|
||||
@ -568,10 +572,9 @@ zwykle możesz nadpisać tylko głos dostawcy:
|
||||
}
|
||||
```
|
||||
|
||||
### Kontrakt wypowiedzi mówionej
|
||||
### Kontrakt wyjścia mówionego
|
||||
|
||||
W przypadku automatycznych odpowiedzi Voice Call dołącza ścisły kontrakt wypowiedzi mówionej do
|
||||
promptu systemowego:
|
||||
W przypadku automatycznych odpowiedzi Voice Call dołącza do promptu systemowego ścisły kontrakt wyjścia mówionego:
|
||||
|
||||
```text
|
||||
{"spoken":"..."}
|
||||
@ -580,41 +583,40 @@ promptu systemowego:
|
||||
Voice Call defensywnie wyodrębnia tekst mowy:
|
||||
|
||||
- Ignoruje ładunki oznaczone jako treść rozumowania/błędu.
|
||||
- Parsuje bezpośredni JSON, JSON w bloku kodu lub wbudowane klucze `"spoken"`.
|
||||
- Wraca do zwykłego tekstu i usuwa prawdopodobne akapity wstępne planowania/metadanych.
|
||||
- Parsuje bezpośredni JSON, JSON w bloku ogrodzonym albo wbudowane klucze `"spoken"`.
|
||||
- Wraca do zwykłego tekstu i usuwa prawdopodobne akapity wprowadzające planowania/metadanych.
|
||||
|
||||
Dzięki temu odtwarzanie mowy pozostaje skupione na tekście skierowanym do dzwoniącego i unika
|
||||
przeciekania tekstu planowania do audio.
|
||||
Dzięki temu odtwarzanie mówione koncentruje się na tekście przeznaczonym dla rozmówcy i unika
|
||||
wycieku tekstu planowania do dźwięku.
|
||||
|
||||
### Zachowanie uruchamiania rozmowy
|
||||
|
||||
W przypadku wychodzących połączeń `conversation` obsługa pierwszej wiadomości jest powiązana ze stanem odtwarzania
|
||||
na żywo:
|
||||
W przypadku wychodzących połączeń `conversation` obsługa pierwszej wiadomości jest powiązana ze stanem odtwarzania na żywo:
|
||||
|
||||
- Czyszczenie kolejki barge-in i automatyczna odpowiedź są tłumione tylko wtedy, gdy początkowe powitanie jest aktywnie wypowiadane.
|
||||
- Jeśli początkowe odtwarzanie się nie powiedzie, połączenie wraca do `listening`, a początkowa wiadomość pozostaje w kolejce do ponowienia.
|
||||
- Czyszczenie kolejki barge-in i automatyczna odpowiedź są wstrzymywane tylko wtedy, gdy początkowe powitanie aktywnie mówi.
|
||||
- Jeśli początkowe odtwarzanie się nie powiedzie, połączenie wraca do stanu `listening`, a początkowa wiadomość pozostaje w kolejce do ponowienia.
|
||||
- Początkowe odtwarzanie dla strumieniowania Twilio zaczyna się po połączeniu strumienia bez dodatkowego opóźnienia.
|
||||
- Barge-in przerywa aktywne odtwarzanie i czyści zakolejkowane, ale jeszcze nieodtwarzane wpisy TTS Twilio. Wyczyszczone wpisy są rozstrzygane jako pominięte, więc logika kolejnej odpowiedzi może kontynuować bez czekania na audio, które nigdy nie zostanie odtworzone.
|
||||
- Rozmowy głosowe w czasie rzeczywistym używają własnej początkowej tury strumienia w czasie rzeczywistym. Voice Call **nie** wysyła starszej aktualizacji TwiML `<Say>` dla tej początkowej wiadomości, więc wychodzące sesje `<Connect><Stream>` pozostają podłączone.
|
||||
- Barge-in przerywa aktywne odtwarzanie i czyści zakolejkowane, ale jeszcze nieodtwarzane wpisy Twilio TTS. Wyczyszczone wpisy rozstrzygają się jako pominięte, dzięki czemu logika odpowiedzi następczej może kontynuować bez czekania na dźwięk, który nigdy nie zostanie odtworzony.
|
||||
- Rozmowy głosowe w czasie rzeczywistym używają własnej tury otwarcia strumienia w czasie rzeczywistym. Voice Call **nie** publikuje starszej aktualizacji TwiML `<Say>` dla tej początkowej wiadomości, więc sesje wychodzące `<Connect><Stream>` pozostają podłączone.
|
||||
|
||||
### Okres karencji rozłączenia strumienia Twilio
|
||||
|
||||
Gdy strumień multimediów Twilio się rozłączy, Voice Call czeka **2000 ms** przed
|
||||
Gdy strumień mediów Twilio się rozłączy, Voice Call czeka **2000 ms** przed
|
||||
automatycznym zakończeniem połączenia:
|
||||
|
||||
- Jeśli strumień połączy się ponownie w tym oknie, automatyczne zakończenie zostanie anulowane.
|
||||
- Jeśli po okresie karencji żaden strumień nie zarejestruje się ponownie, połączenie zostanie zakończone, aby zapobiec zablokowanym aktywnym połączeniom.
|
||||
- Jeśli strumień połączy się ponownie w tym oknie, automatyczne zakończenie zostaje anulowane.
|
||||
- Jeśli po okresie karencji żaden strumień nie zarejestruje się ponownie, połączenie zostaje zakończone, aby zapobiec zablokowanym aktywnym połączeniom.
|
||||
|
||||
## Zbieracz nieaktualnych połączeń
|
||||
## Czyszczenie nieaktualnych połączeń
|
||||
|
||||
Użyj `staleCallReaperSeconds`, aby kończyć połączenia, które nigdy nie otrzymują końcowego
|
||||
Webhook (na przykład połączenia w trybie powiadamiania, które nigdy się nie kończą). Wartość domyślna
|
||||
Webhook (na przykład połączenia w trybie powiadomień, które nigdy się nie kończą). Wartość domyślna
|
||||
to `0` (wyłączone).
|
||||
|
||||
Zalecane zakresy:
|
||||
|
||||
- **Produkcja:** `120`–`300` sekund dla przepływów typu powiadomień.
|
||||
- Zachowaj tę wartość **wyższą niż `maxDurationSeconds`**, aby zwykłe połączenia mogły się zakończyć. Dobrym punktem wyjścia jest `maxDurationSeconds + 30–60` sekund.
|
||||
- **Produkcja:** `120`–`300` sekund dla przepływów typu powiadomienia.
|
||||
- Utrzymuj tę wartość **wyżej niż `maxDurationSeconds`**, aby normalne połączenia mogły się zakończyć. Dobrym punktem wyjścia jest `maxDurationSeconds + 30–60` sekund.
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -633,26 +635,26 @@ Zalecane zakresy:
|
||||
|
||||
## Bezpieczeństwo Webhook
|
||||
|
||||
Gdy proxy lub tunel znajduje się przed Gateway, Plugin
|
||||
Gdy proxy lub tunel znajduje się przed Gateway, plugin
|
||||
rekonstruuje publiczny URL do weryfikacji podpisu. Te opcje
|
||||
kontrolują, którym nagłówkom przekazywanym można ufać:
|
||||
kontrolują, które przekazane nagłówki są zaufane:
|
||||
|
||||
<ParamField path="webhookSecurity.allowedHosts" type="string[]">
|
||||
Lista dozwolonych hostów z nagłówków przekazywania.
|
||||
</ParamField>
|
||||
<ParamField path="webhookSecurity.trustForwardingHeaders" type="boolean">
|
||||
Ufaj przekazywanym nagłówkom bez listy dozwolonych.
|
||||
Ufaj przekazanym nagłówkom bez listy dozwolonych.
|
||||
</ParamField>
|
||||
<ParamField path="webhookSecurity.trustedProxyIPs" type="string[]">
|
||||
Ufaj przekazywanym nagłówkom tylko wtedy, gdy zdalny adres IP żądania pasuje do listy.
|
||||
Ufaj przekazanym nagłówkom tylko wtedy, gdy zdalny adres IP żądania pasuje do listy.
|
||||
</ParamField>
|
||||
|
||||
Dodatkowe zabezpieczenia:
|
||||
|
||||
- **Ochrona przed powtórzeniem** Webhook jest włączona dla Twilio i Plivo. Powtórzone prawidłowe żądania Webhook są potwierdzane, ale pomijane pod kątem skutków ubocznych.
|
||||
- **Ochrona przed powtórzeniem** Webhook jest włączona dla Twilio i Plivo. Powtórzone poprawne żądania Webhook są potwierdzane, ale pomijane pod kątem skutków ubocznych.
|
||||
- Tury rozmowy Twilio zawierają token dla każdej tury w wywołaniach zwrotnych `<Gather>`, więc nieaktualne/powtórzone wywołania zwrotne mowy nie mogą spełnić nowszej oczekującej tury transkrypcji.
|
||||
- Nieuwierzytelnione żądania Webhook są odrzucane przed odczytem treści, gdy brakuje wymaganych przez dostawcę nagłówków podpisu.
|
||||
- Webhook voice-call używa współdzielonego profilu treści przed uwierzytelnieniem (64 KB / 5 sekund) oraz limitu równoczesnych żądań na adres IP przed weryfikacją podpisu.
|
||||
- Nieuwierzytelnione żądania Webhook są odrzucane przed odczytem treści, gdy brakuje wymaganych nagłówków podpisu dostawcy.
|
||||
- Webhook voice-call używa współdzielonego profilu treści przed uwierzytelnieniem (64 KB / 5 sekund) oraz limitu jednoczesnych żądań na IP przed weryfikacją podpisu.
|
||||
|
||||
Przykład ze stabilnym hostem publicznym:
|
||||
|
||||
@ -689,14 +691,14 @@ openclaw voicecall expose --mode funnel
|
||||
```
|
||||
|
||||
Gdy Gateway już działa, operacyjne polecenia `voicecall` delegują
|
||||
do należącego do Gateway środowiska uruchomieniowego voice-call, aby CLI nie wiązało drugiego
|
||||
serwera Webhook. Jeśli żaden Gateway nie jest osiągalny, polecenia wracają do
|
||||
do środowiska uruchomieniowego połączeń głosowych należącego do Gateway, dzięki czemu CLI nie wiąże drugiego
|
||||
serwera webhooków. Jeśli żaden Gateway nie jest osiągalny, polecenia wracają do
|
||||
samodzielnego środowiska uruchomieniowego CLI.
|
||||
|
||||
`latency` odczytuje `calls.jsonl` z domyślnej ścieżki przechowywania połączeń głosowych.
|
||||
Użyj `--file <path>`, aby wskazać inny dziennik, oraz `--last <n>`, aby ograniczyć
|
||||
analizę do ostatnich N rekordów (domyślnie 200). Dane wyjściowe obejmują p50/p90/p99
|
||||
dla opóźnienia tury i czasów oczekiwania na nasłuch.
|
||||
dla opóźnienia tury i czasów oczekiwania na nasłuchiwanie.
|
||||
|
||||
## Narzędzie agenta
|
||||
|
||||
@ -711,7 +713,7 @@ Nazwa narzędzia: `voice_call`.
|
||||
| `end_call` | `callId` |
|
||||
| `get_status` | `callId` |
|
||||
|
||||
To repozytorium zawiera pasujący dokument skill pod adresem `skills/voice-call/SKILL.md`.
|
||||
To repozytorium zawiera zgodny dokument Skills pod adresem `skills/voice-call/SKILL.md`.
|
||||
|
||||
## RPC Gateway
|
||||
|
||||
@ -724,12 +726,13 @@ To repozytorium zawiera pasujący dokument skill pod adresem `skills/voice-call/
|
||||
| `voicecall.end` | `callId` |
|
||||
| `voicecall.status` | `callId` |
|
||||
|
||||
`dtmfSequence` jest prawidłowe tylko z `mode: "conversation"`. Połączenia w trybie powiadomień
|
||||
powinny używać `voicecall.dtmf` po utworzeniu połączenia, jeśli potrzebują cyfr po połączeniu.
|
||||
`dtmfSequence` jest prawidłowe tylko z `mode: "conversation"`. Połączenia w trybie powiadamiania,
|
||||
które potrzebują cyfr po nawiązaniu połączenia, powinny używać `voicecall.dtmf`
|
||||
po utworzeniu połączenia.
|
||||
|
||||
## Rozwiązywanie problemów
|
||||
|
||||
### Konfiguracja nie przechodzi sprawdzenia ekspozycji Webhook
|
||||
### Konfiguracja nie udostępnia webhooka
|
||||
|
||||
Uruchom konfigurację z tego samego środowiska, w którym działa Gateway:
|
||||
|
||||
@ -738,19 +741,19 @@ openclaw voicecall setup
|
||||
openclaw voicecall setup --json
|
||||
```
|
||||
|
||||
Dla `twilio`, `telnyx` i `plivo` `webhook-exposure` musi być zielone. Skonfigurowany
|
||||
`publicUrl` nadal kończy się niepowodzeniem, gdy wskazuje lokalną lub prywatną
|
||||
przestrzeń sieciową, ponieważ operator nie może wywołać zwrotnie tych adresów. Nie używaj
|
||||
Dla `twilio`, `telnyx` i `plivo` stan `webhook-exposure` musi być zielony.
|
||||
Skonfigurowane `publicUrl` nadal kończy się niepowodzeniem, gdy wskazuje lokalną lub prywatną przestrzeń sieciową,
|
||||
ponieważ operator nie może wywołać tych adresów zwrotnie. Nie używaj
|
||||
`localhost`, `127.0.0.1`, `0.0.0.0`, `10.x`, `172.16.x`-`172.31.x`,
|
||||
`192.168.x`, `169.254.x`, `fc00::/7` ani `fd00::/8` jako `publicUrl`.
|
||||
|
||||
Połączenia wychodzące Twilio w trybie powiadomień wysyłają początkowy TwiML `<Say>` bezpośrednio w
|
||||
żądaniu utworzenia połączenia, więc pierwsza wypowiadana wiadomość nie zależy od pobrania przez Twilio
|
||||
TwiML Webhook. Publiczny Webhook jest nadal wymagany dla wywołań zwrotnych statusu,
|
||||
Połączenia wychodzące Twilio w trybie powiadamiania wysyłają początkowy TwiML `<Say>` bezpośrednio w
|
||||
żądaniu utworzenia połączenia, więc pierwsza wypowiadana wiadomość nie zależy od tego, czy Twilio
|
||||
pobierze TwiML webhooka. Publiczny webhook jest nadal wymagany do wywołań zwrotnych statusu,
|
||||
połączeń konwersacyjnych, DTMF przed połączeniem, strumieni czasu rzeczywistego i sterowania połączeniem
|
||||
po połączeniu.
|
||||
po nawiązaniu połączenia.
|
||||
|
||||
Użyj jednej publicznej ścieżki ekspozycji:
|
||||
Użyj jednej publicznej ścieżki udostępniania:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -770,18 +773,18 @@ Użyj jednej publicznej ścieżki ekspozycji:
|
||||
}
|
||||
```
|
||||
|
||||
Po zmianie konfiguracji uruchom ponownie albo przeładuj Gateway, a następnie uruchom:
|
||||
Po zmianie konfiguracji uruchom ponownie lub przeładuj Gateway, a następnie uruchom:
|
||||
|
||||
```bash
|
||||
openclaw voicecall setup
|
||||
openclaw voicecall smoke
|
||||
```
|
||||
|
||||
`voicecall smoke` jest próbą bez skutków ubocznych, chyba że przekażesz `--yes`.
|
||||
`voicecall smoke` jest przebiegiem próbnym, chyba że przekażesz `--yes`.
|
||||
|
||||
### Poświadczenia dostawcy kończą się niepowodzeniem
|
||||
### Dane uwierzytelniające dostawcy nie działają
|
||||
|
||||
Sprawdź wybranego dostawcę i wymagane pola poświadczeń:
|
||||
Sprawdź wybranego dostawcę i wymagane pola danych uwierzytelniających:
|
||||
|
||||
- Twilio: `twilio.accountSid`, `twilio.authToken` i `fromNumber` albo
|
||||
`TWILIO_ACCOUNT_SID`, `TWILIO_AUTH_TOKEN` i `TWILIO_FROM_NUMBER`.
|
||||
@ -789,13 +792,13 @@ Sprawdź wybranego dostawcę i wymagane pola poświadczeń:
|
||||
`fromNumber`.
|
||||
- Plivo: `plivo.authId`, `plivo.authToken` i `fromNumber`.
|
||||
|
||||
Poświadczenia muszą istnieć na hoście Gateway. Edycja lokalnego profilu powłoki nie
|
||||
wpływa na już działający Gateway, dopóki nie uruchomi się ponownie albo nie przeładuje
|
||||
Dane uwierzytelniające muszą istnieć na hoście Gateway. Edycja lokalnego profilu powłoki
|
||||
nie wpływa na już działający Gateway, dopóki nie zostanie on ponownie uruchomiony lub nie przeładuje
|
||||
swojego środowiska.
|
||||
|
||||
### Połączenia się rozpoczynają, ale Webhook dostawcy nie docierają
|
||||
### Połączenia się rozpoczynają, ale webhooki dostawcy nie docierają
|
||||
|
||||
Potwierdź, że konsola dostawcy wskazuje dokładny publiczny adres URL Webhook:
|
||||
Potwierdź, że konsola dostawcy wskazuje dokładny publiczny URL webhooka:
|
||||
|
||||
```text
|
||||
https://voice.example.com/voice/webhook
|
||||
@ -809,35 +812,35 @@ openclaw voicecall tail
|
||||
openclaw logs --follow
|
||||
```
|
||||
|
||||
Częste przyczyny:
|
||||
Typowe przyczyny:
|
||||
|
||||
- `publicUrl` wskazuje inną ścieżkę niż `serve.path`.
|
||||
- Adres URL tunelu zmienił się po uruchomieniu Gateway.
|
||||
- Serwer proxy przekazuje żądanie, ale usuwa lub przepisuje nagłówki host/proto.
|
||||
- Zapora sieciowa lub DNS kieruje publiczną nazwę hosta gdzie indziej niż do Gateway.
|
||||
- Gateway został uruchomiony ponownie bez włączonego pluginu Voice Call.
|
||||
- URL tunelu zmienił się po uruchomieniu Gateway.
|
||||
- Proxy przekazuje żądanie, ale usuwa lub przepisuje nagłówki host/proto.
|
||||
- Zapora lub DNS kieruje publiczną nazwę hosta w inne miejsce niż Gateway.
|
||||
- Gateway został ponownie uruchomiony bez włączonego Pluginu Voice Call.
|
||||
|
||||
Gdy przed Gateway znajduje się odwrotny serwer proxy albo tunel, ustaw
|
||||
Gdy przed Gateway znajduje się odwrotne proxy lub tunel, ustaw
|
||||
`webhookSecurity.allowedHosts` na publiczną nazwę hosta albo użyj
|
||||
`webhookSecurity.trustedProxyIPs` dla znanego adresu proxy. Używaj
|
||||
`webhookSecurity.trustForwardingHeaders` tylko wtedy, gdy granica proxy jest pod
|
||||
Twoją kontrolą.
|
||||
|
||||
### Weryfikacja podpisu kończy się niepowodzeniem
|
||||
### Weryfikacja podpisu nie działa
|
||||
|
||||
Podpisy dostawcy są sprawdzane względem publicznego adresu URL, który OpenClaw odtwarza
|
||||
z przychodzącego żądania. Jeśli podpisy zawodzą:
|
||||
Podpisy dostawcy są sprawdzane względem publicznego URL-a, który OpenClaw rekonstruuje
|
||||
z przychodzącego żądania. Jeśli podpisy nie przechodzą weryfikacji:
|
||||
|
||||
- Potwierdź, że adres URL Webhook dostawcy dokładnie pasuje do `publicUrl`, w tym
|
||||
schemat, host i ścieżka.
|
||||
- W przypadku adresów URL ngrok w warstwie bezpłatnej aktualizuj `publicUrl`, gdy zmienia się nazwa hosta tunelu.
|
||||
- Upewnij się, że proxy zachowuje oryginalne nagłówki hosta i protokołu, albo skonfiguruj
|
||||
- Potwierdź, że URL webhooka dostawcy dokładnie odpowiada `publicUrl`, w tym
|
||||
schematowi, hostowi i ścieżce.
|
||||
- W przypadku adresów URL ngrok w bezpłatnej warstwie zaktualizuj `publicUrl`, gdy zmieni się nazwa hosta tunelu.
|
||||
- Upewnij się, że proxy zachowuje oryginalne nagłówki hosta i proto, albo skonfiguruj
|
||||
`webhookSecurity.allowedHosts`.
|
||||
- Nie włączaj `skipSignatureVerification` poza testami lokalnymi.
|
||||
|
||||
### Dołączenia Google Meet przez Twilio kończą się niepowodzeniem
|
||||
### Dołączenia Google Meet przez Twilio nie działają
|
||||
|
||||
Google Meet używa tego pluginu do dołączeń przez połączenie telefoniczne Twilio. Najpierw zweryfikuj Voice Call:
|
||||
Google Meet używa tego Pluginu do dołączeń przez wybieranie numeru Twilio. Najpierw zweryfikuj Voice Call:
|
||||
|
||||
```bash
|
||||
openclaw voicecall setup
|
||||
@ -850,43 +853,43 @@ Następnie jawnie zweryfikuj transport Google Meet:
|
||||
openclaw googlemeet setup --transport twilio
|
||||
```
|
||||
|
||||
Jeśli Voice Call jest zielony, ale uczestnik Meet nigdy nie dołącza, sprawdź numer
|
||||
telefoniczny Meet, PIN i `--dtmf-sequence`. Połączenie telefoniczne może być sprawne, mimo że
|
||||
Jeśli Voice Call jest zielony, ale uczestnik Meet nigdy nie dołącza, sprawdź
|
||||
numer telefoniczny Meet, PIN i `--dtmf-sequence`. Połączenie telefoniczne może być poprawne, podczas gdy
|
||||
spotkanie odrzuca lub ignoruje nieprawidłową sekwencję DTMF.
|
||||
|
||||
Google Meet przekazuje sekwencję DTMF Meet i tekst wprowadzenia do `voicecall.start`.
|
||||
W przypadku połączeń Twilio Voice Call najpierw serwuje TwiML DTMF, przekierowuje z powrotem do
|
||||
Webhook, a następnie otwiera strumień multimediów czasu rzeczywistego, więc zapisane wprowadzenie jest generowane
|
||||
Google Meet przekazuje sekwencję DTMF Meet i tekst wprowadzający do `voicecall.start`.
|
||||
W przypadku połączeń Twilio Voice Call najpierw obsługuje TwiML DTMF, przekierowuje z powrotem do
|
||||
webhooka, a następnie otwiera strumień multimediów czasu rzeczywistego, aby zapisane wprowadzenie zostało wygenerowane
|
||||
po dołączeniu uczestnika telefonicznego do spotkania.
|
||||
|
||||
Użyj `openclaw logs --follow` dla śledzenia fazy na żywo. Poprawne dołączenie Twilio Meet
|
||||
rejestruje tę kolejność:
|
||||
Użyj `openclaw logs --follow`, aby śledzić fazę na żywo. Poprawne dołączenie Twilio Meet
|
||||
loguje tę kolejność:
|
||||
|
||||
- Google Meet deleguje dołączenie Twilio do Voice Call.
|
||||
- Voice Call zapisuje TwiML DTMF przed połączeniem.
|
||||
- Początkowy TwiML Twilio zostaje zużyty i zaserwowany przed obsługą czasu rzeczywistego.
|
||||
- Voice Call serwuje TwiML czasu rzeczywistego dla połączenia Twilio.
|
||||
- Most czasu rzeczywistego startuje z początkowym powitaniem w kolejce.
|
||||
- Początkowy TwiML Twilio jest zużywany i obsługiwany przed obsługą czasu rzeczywistego.
|
||||
- Voice Call obsługuje TwiML czasu rzeczywistego dla połączenia Twilio.
|
||||
- Most czasu rzeczywistego uruchamia się z początkowym powitaniem w kolejce.
|
||||
|
||||
`openclaw voicecall tail` nadal pokazuje utrwalone rekordy połączeń; jest przydatne do
|
||||
stanu połączenia i transkrypcji, ale nie każde przejście Webhook/czasu rzeczywistego pojawia się
|
||||
tam.
|
||||
stanu połączeń i transkrypcji, ale nie każde przejście webhooka/czasu rzeczywistego
|
||||
jest tam widoczne.
|
||||
|
||||
### Połączenie czasu rzeczywistego nie ma mowy
|
||||
|
||||
Potwierdź, że włączony jest tylko jeden tryb audio. `realtime.enabled` i
|
||||
`streaming.enabled` nie mogą oba mieć wartości true.
|
||||
`streaming.enabled` nie mogą być jednocześnie ustawione na true.
|
||||
|
||||
W przypadku połączeń Twilio czasu rzeczywistego zweryfikuj także:
|
||||
|
||||
- Plugin dostawcy czasu rzeczywistego jest załadowany i zarejestrowany.
|
||||
- `realtime.provider` jest nieustawione albo wskazuje zarejestrowanego dostawcę.
|
||||
- Klucz API dostawcy jest dostępny dla procesu Gateway.
|
||||
- `openclaw logs --follow` pokazuje zaserwowany TwiML czasu rzeczywistego, uruchomiony most czasu rzeczywistego
|
||||
- `openclaw logs --follow` pokazuje obsłużony TwiML czasu rzeczywistego, uruchomiony most czasu rzeczywistego
|
||||
i początkowe powitanie dodane do kolejki.
|
||||
|
||||
## Powiązane
|
||||
|
||||
- [Tryb rozmowy](/pl/nodes/talk)
|
||||
- [Zamiana tekstu na mowę](/pl/tools/tts)
|
||||
- [Wybudzanie głosem](/pl/nodes/voicewake)
|
||||
- [Wybudzanie głosowe](/pl/nodes/voicewake)
|
||||
|
||||
@ -1,38 +1,38 @@
|
||||
---
|
||||
read_when:
|
||||
- Chcesz korzystać z syntezy mowy ElevenLabs w OpenClaw
|
||||
- Chcesz korzystać z rozpoznawania mowy ElevenLabs Scribe dla załączników audio
|
||||
- Chcesz korzystać z transkrypcji w czasie rzeczywistym ElevenLabs dla Voice Call
|
||||
summary: Używanie mowy ElevenLabs, Scribe STT i transkrypcji realtime z OpenClaw
|
||||
- Chcesz korzystać z zamiany tekstu na mowę ElevenLabs w OpenClaw
|
||||
- Chcesz używać ElevenLabs Scribe do transkrypcji mowy na tekst dla załączników audio
|
||||
- Chcesz transkrypcji ElevenLabs w czasie rzeczywistym dla połączenia głosowego lub Google Meet
|
||||
summary: Korzystaj z syntezy mowy ElevenLabs, Scribe STT i transkrypcji w czasie rzeczywistym w OpenClaw
|
||||
title: ElevenLabs
|
||||
x-i18n:
|
||||
generated_at: "2026-04-25T13:56:15Z"
|
||||
model: gpt-5.4
|
||||
generated_at: "2026-05-04T07:05:49Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 1f858a344228c6355cd5fdc3775cddac39e0075f2e9fcf7683271f11be03a31a
|
||||
source_hash: 4c880bf9dcab01ef70779c74576c70ea5d0203b96b5f739291842fafcb4bdb4b
|
||||
source_path: providers/elevenlabs.md
|
||||
workflow: 15
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
OpenClaw używa ElevenLabs do syntezy mowy, wsadowego rozpoznawania mowy za pomocą Scribe
|
||||
v2 oraz strumieniowego STT w Voice Call z użyciem Scribe v2 Realtime.
|
||||
OpenClaw używa ElevenLabs do zamiany tekstu na mowę, wsadowej zamiany mowy na tekst z użyciem Scribe
|
||||
v2 oraz strumieniowego STT z użyciem Scribe v2 Realtime.
|
||||
|
||||
| Funkcja | Powierzchnia OpenClaw | Domyślnie |
|
||||
| ------------------------ | --------------------------------------------- | ----------------------- |
|
||||
| Synteza mowy | `messages.tts` / `talk` | `eleven_multilingual_v2` |
|
||||
| Wsadowe rozpoznawanie mowy | `tools.media.audio` | `scribe_v2` |
|
||||
| Strumieniowe rozpoznawanie mowy | Voice Call `streaming.provider: "elevenlabs"` | `scribe_v2_realtime` |
|
||||
| Możliwość | Powierzchnia OpenClaw | Domyślne |
|
||||
| ------------------------ | -------------------------------------------------------------------- | ------------------------ |
|
||||
| Zamiana tekstu na mowę | `messages.tts` / `talk` | `eleven_multilingual_v2` |
|
||||
| Wsadowa zamiana mowy na tekst | `tools.media.audio` | `scribe_v2` |
|
||||
| Strumieniowa zamiana mowy na tekst | strumieniowanie Voice Call lub Google Meet `realtime.transcriptionProvider` | `scribe_v2_realtime` |
|
||||
|
||||
## Uwierzytelnianie
|
||||
|
||||
Ustaw `ELEVENLABS_API_KEY` w środowisku. `XI_API_KEY` jest również akceptowany
|
||||
dla zgodności z istniejącymi narzędziami ElevenLabs.
|
||||
Ustaw `ELEVENLABS_API_KEY` w środowisku. `XI_API_KEY` jest również akceptowany ze względu na
|
||||
zgodność z istniejącymi narzędziami ElevenLabs.
|
||||
|
||||
```bash
|
||||
export ELEVENLABS_API_KEY="..."
|
||||
```
|
||||
|
||||
## Synteza mowy
|
||||
## Zamiana tekstu na mowę
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -53,9 +53,9 @@ export ELEVENLABS_API_KEY="..."
|
||||
Ustaw `modelId` na `eleven_v3`, aby używać ElevenLabs v3 TTS. OpenClaw zachowuje
|
||||
`eleven_multilingual_v2` jako wartość domyślną dla istniejących instalacji.
|
||||
|
||||
## Rozpoznawanie mowy
|
||||
## Zamiana mowy na tekst
|
||||
|
||||
Używaj Scribe v2 dla przychodzących załączników audio i krótkich nagranych segmentów głosowych:
|
||||
Użyj Scribe v2 dla przychodzących załączników audio i krótkich nagranych segmentów głosowych:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -71,21 +71,21 @@ Używaj Scribe v2 dla przychodzących załączników audio i krótkich nagranych
|
||||
```
|
||||
|
||||
OpenClaw wysyła wieloczęściowe audio do ElevenLabs `/v1/speech-to-text` z
|
||||
`model_id: "scribe_v2"`. Wskazówki językowe są mapowane na `language_code`, jeśli są obecne.
|
||||
`model_id: "scribe_v2"`. Wskazówki językowe są mapowane na `language_code`, gdy są obecne.
|
||||
|
||||
## Strumieniowe STT w Voice Call
|
||||
## Strumieniowe STT
|
||||
|
||||
Dołączony Plugin `elevenlabs` rejestruje Scribe v2 Realtime dla
|
||||
strumieniowej transkrypcji w Voice Call.
|
||||
Dołączony Plugin `elevenlabs` rejestruje Scribe v2 Realtime dla strumieniowej transkrypcji Voice Call oraz
|
||||
Google Meet w trybie agenta.
|
||||
|
||||
| Ustawienie | Ścieżka konfiguracji | Domyślnie |
|
||||
| ---------------- | ------------------------------------------------------------------------- | ------------------------------------------------- |
|
||||
| Klucz API | `plugins.entries.voice-call.config.streaming.providers.elevenlabs.apiKey` | Używa `ELEVENLABS_API_KEY` / `XI_API_KEY` jako zapasowego |
|
||||
| Model | `...elevenlabs.modelId` | `scribe_v2_realtime` |
|
||||
| Format audio | `...elevenlabs.audioFormat` | `ulaw_8000` |
|
||||
| Częstotliwość próbkowania | `...elevenlabs.sampleRate` | `8000` |
|
||||
| Strategia zatwierdzania | `...elevenlabs.commitStrategy` | `vad` |
|
||||
| Język | `...elevenlabs.languageCode` | (nieustawione) |
|
||||
| Ustawienie | Ścieżka konfiguracji | Domyślne |
|
||||
| --------------- | ------------------------------------------------------------------------- | ------------------------------------------------- |
|
||||
| Klucz API | `plugins.entries.voice-call.config.streaming.providers.elevenlabs.apiKey` | Wraca do `ELEVENLABS_API_KEY` / `XI_API_KEY` |
|
||||
| Model | `...elevenlabs.modelId` | `scribe_v2_realtime` |
|
||||
| Format audio | `...elevenlabs.audioFormat` | `ulaw_8000` |
|
||||
| Częstotliwość próbkowania | `...elevenlabs.sampleRate` | `8000` |
|
||||
| Strategia zatwierdzania | `...elevenlabs.commitStrategy` | `vad` |
|
||||
| Język | `...elevenlabs.languageCode` | (nieustawione) |
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -113,12 +113,18 @@ strumieniowej transkrypcji w Voice Call.
|
||||
```
|
||||
|
||||
<Note>
|
||||
Voice Call odbiera multimedia Twilio jako 8 kHz G.711 u-law. Dostawca czasu rzeczywistego ElevenLabs
|
||||
domyślnie używa `ulaw_8000`, więc ramki telefoniczne mogą być przekazywane dalej bez
|
||||
Voice Call odbiera multimedia Twilio jako 8 kHz G.711 u-law. Dostawca ElevenLabs realtime
|
||||
domyślnie używa `ulaw_8000`, więc ramki telefoniczne mogą być przekazywane bez
|
||||
transkodowania.
|
||||
</Note>
|
||||
|
||||
W trybie agenta Google Meet ustaw
|
||||
`plugins.entries.google-meet.config.realtime.transcriptionProvider` na
|
||||
`"elevenlabs"` i skonfiguruj ten sam blok dostawcy w
|
||||
`plugins.entries.google-meet.config.realtime.providers.elevenlabs`.
|
||||
|
||||
## Powiązane
|
||||
|
||||
- [Synteza mowy](/pl/tools/tts)
|
||||
- [Zamiana tekstu na mowę](/pl/tools/tts)
|
||||
- [Google Meet](/pl/plugins/google-meet)
|
||||
- [Wybór modelu](/pl/concepts/model-providers)
|
||||
|
||||
@ -1,14 +1,14 @@
|
||||
---
|
||||
read_when:
|
||||
- Chcesz korzystać z modeli Google Gemini w OpenClaw
|
||||
- Chcesz używać modeli Google Gemini w OpenClaw
|
||||
- Potrzebujesz klucza API lub przepływu uwierzytelniania OAuth
|
||||
summary: Konfiguracja Google Gemini (klucz API + OAuth, generowanie obrazów, rozumienie multimediów, TTS, wyszukiwanie w internecie)
|
||||
summary: Konfiguracja Google Gemini (klucz API + OAuth, generowanie obrazów, rozumienie multimediów, TTS, wyszukiwanie w sieci)
|
||||
title: Google (Gemini)
|
||||
x-i18n:
|
||||
generated_at: "2026-05-02T10:00:17Z"
|
||||
generated_at: "2026-05-04T07:05:48Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 14605b88f0d1d7e01796d429113a73b2b52a48fde6443565dcb3db47653be5e7
|
||||
source_hash: 3e45627f5d5cd57e858c7590a90435b7fc0e9381509f3312a16fc9e9a4cbd908
|
||||
source_path: providers/google.md
|
||||
workflow: 16
|
||||
---
|
||||
@ -21,7 +21,7 @@ Gemini Grounding.
|
||||
- Uwierzytelnianie: `GEMINI_API_KEY` lub `GOOGLE_API_KEY`
|
||||
- API: Google Gemini API
|
||||
- Opcja środowiska uruchomieniowego: `agents.defaults.agentRuntime.id: "google-gemini-cli"`
|
||||
ponownie używa OAuth Gemini CLI, zachowując kanoniczne odwołania do modeli jako `google/*`.
|
||||
ponownie wykorzystuje OAuth Gemini CLI, zachowując kanoniczne odwołania do modeli jako `google/*`.
|
||||
|
||||
## Pierwsze kroki
|
||||
|
||||
@ -32,7 +32,7 @@ Wybierz preferowaną metodę uwierzytelniania i wykonaj kroki konfiguracji.
|
||||
**Najlepsze do:** standardowego dostępu do Gemini API przez Google AI Studio.
|
||||
|
||||
<Steps>
|
||||
<Step title="Uruchom onboarding">
|
||||
<Step title="Uruchom wdrażanie">
|
||||
```bash
|
||||
openclaw onboard --auth-choice gemini-api-key
|
||||
```
|
||||
@ -65,17 +65,17 @@ Wybierz preferowaną metodę uwierzytelniania i wykonaj kroki konfiguracji.
|
||||
</Steps>
|
||||
|
||||
<Tip>
|
||||
Zmienne środowiskowe `GEMINI_API_KEY` i `GOOGLE_API_KEY` są obsługiwane. Użyj tej, którą masz już skonfigurowaną.
|
||||
Obie zmienne środowiskowe `GEMINI_API_KEY` i `GOOGLE_API_KEY` są akceptowane. Użyj tej, którą masz już skonfigurowaną.
|
||||
</Tip>
|
||||
|
||||
</Tab>
|
||||
|
||||
<Tab title="Gemini CLI (OAuth)">
|
||||
**Najlepsze do:** ponownego użycia istniejącego logowania Gemini CLI przez PKCE OAuth zamiast osobnego klucza API.
|
||||
**Najlepsze do:** ponownego wykorzystania istniejącego logowania Gemini CLI przez PKCE OAuth zamiast osobnego klucza API.
|
||||
|
||||
<Warning>
|
||||
Dostawca `google-gemini-cli` jest nieoficjalną integracją. Niektórzy użytkownicy
|
||||
zgłaszają ograniczenia konta podczas używania OAuth w ten sposób. Używasz na własne ryzyko.
|
||||
zgłaszają ograniczenia konta podczas korzystania z OAuth w ten sposób. Używasz na własne ryzyko.
|
||||
</Warning>
|
||||
|
||||
<Steps>
|
||||
@ -109,28 +109,28 @@ Wybierz preferowaną metodę uwierzytelniania i wykonaj kroki konfiguracji.
|
||||
- Środowisko uruchomieniowe: `google-gemini-cli`
|
||||
- Alias: `gemini-cli`
|
||||
|
||||
Identyfikator modelu Gemini API dla Gemini 3.1 Pro to `gemini-3.1-pro-preview`. OpenClaw akceptuje krótszy `google/gemini-3.1-pro` jako wygodny alias i normalizuje go przed wywołaniami dostawcy.
|
||||
Identyfikator modelu Gemini API dla Gemini 3.1 Pro to `gemini-3.1-pro-preview`. OpenClaw akceptuje krótsze `google/gemini-3.1-pro` jako wygodny alias i normalizuje je przed wywołaniami dostawcy.
|
||||
|
||||
**Zmienne środowiskowe:**
|
||||
|
||||
- `OPENCLAW_GEMINI_OAUTH_CLIENT_ID`
|
||||
- `OPENCLAW_GEMINI_OAUTH_CLIENT_SECRET`
|
||||
|
||||
(Lub warianty `GEMINI_CLI_*`).
|
||||
(Lub warianty `GEMINI_CLI_*`.)
|
||||
|
||||
<Note>
|
||||
Jeśli żądania OAuth Gemini CLI nie powiodą się po zalogowaniu, ustaw `GOOGLE_CLOUD_PROJECT` lub
|
||||
`GOOGLE_CLOUD_PROJECT_ID` na hoście Gateway i spróbuj ponownie.
|
||||
Jeśli żądania Gemini CLI OAuth po zalogowaniu kończą się niepowodzeniem, ustaw `GOOGLE_CLOUD_PROJECT` lub
|
||||
`GOOGLE_CLOUD_PROJECT_ID` na hoście gateway i spróbuj ponownie.
|
||||
</Note>
|
||||
|
||||
<Note>
|
||||
Jeśli logowanie nie powiedzie się przed rozpoczęciem przepływu w przeglądarce, upewnij się, że lokalne polecenie `gemini`
|
||||
Jeśli logowanie kończy się niepowodzeniem przed rozpoczęciem przepływu w przeglądarce, upewnij się, że lokalne polecenie `gemini`
|
||||
jest zainstalowane i dostępne w `PATH`.
|
||||
</Note>
|
||||
|
||||
Odwołania do modeli `google-gemini-cli/*` są aliasami zgodności wstecznej. Nowe
|
||||
Odwołania do modeli `google-gemini-cli/*` są starszymi aliasami zgodności. Nowe
|
||||
konfiguracje powinny używać odwołań do modeli `google/*` oraz środowiska uruchomieniowego `google-gemini-cli`,
|
||||
gdy chcą lokalnego wykonywania Gemini CLI.
|
||||
gdy mają korzystać z lokalnego wykonywania Gemini CLI.
|
||||
|
||||
</Tab>
|
||||
</Tabs>
|
||||
@ -139,7 +139,7 @@ Wybierz preferowaną metodę uwierzytelniania i wykonaj kroki konfiguracji.
|
||||
|
||||
| Możliwość | Obsługiwane |
|
||||
| ---------------------- | ----------------------------- |
|
||||
| Uzupełnienia czatu | Tak |
|
||||
| Uzupełnianie czatu | Tak |
|
||||
| Generowanie obrazów | Tak |
|
||||
| Generowanie muzyki | Tak |
|
||||
| Zamiana tekstu na mowę | Tak |
|
||||
@ -147,15 +147,15 @@ Wybierz preferowaną metodę uwierzytelniania i wykonaj kroki konfiguracji.
|
||||
| Rozumienie obrazów | Tak |
|
||||
| Transkrypcja audio | Tak |
|
||||
| Rozumienie wideo | Tak |
|
||||
| Wyszukiwanie w sieci (Grounding) | Tak |
|
||||
| Wyszukiwanie w sieci (Grounding) | Tak |
|
||||
| Myślenie/rozumowanie | Tak (Gemini 2.5+ / Gemini 3+) |
|
||||
| Modele Gemma 4 | Tak |
|
||||
|
||||
## Wyszukiwanie w sieci
|
||||
|
||||
Dołączony dostawca wyszukiwania w sieci `gemini` używa grounding Google Search w Gemini.
|
||||
Skonfiguruj dedykowany klucz wyszukiwania pod `plugins.entries.google.config.webSearch`
|
||||
albo pozwól mu ponownie użyć `models.providers.google.apiKey` po `GEMINI_API_KEY`:
|
||||
Dołączony dostawca wyszukiwania w sieci `gemini` używa ugruntowania Gemini Google Search.
|
||||
Skonfiguruj dedykowany klucz wyszukiwania w `plugins.entries.google.config.webSearch`
|
||||
albo pozwól mu ponownie wykorzystać `models.providers.google.apiKey` po `GEMINI_API_KEY`:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -175,25 +175,25 @@ albo pozwól mu ponownie użyć `models.providers.google.apiKey` po `GEMINI_API_
|
||||
}
|
||||
```
|
||||
|
||||
Priorytet poświadczeń to dedykowany `webSearch.apiKey`, następnie `GEMINI_API_KEY`,
|
||||
a potem `models.providers.google.apiKey`. `webSearch.baseUrl` jest opcjonalny i
|
||||
istnieje dla proxy operatorów lub zgodnych punktów końcowych Gemini API; gdy zostanie pominięty,
|
||||
wyszukiwanie w sieci Gemini ponownie używa `models.providers.google.baseUrl`. Zobacz
|
||||
[Wyszukiwanie Gemini](/pl/tools/gemini-search), aby poznać zachowanie narzędzia właściwe dla dostawcy.
|
||||
Pierwszeństwo poświadczeń to dedykowane `webSearch.apiKey`, następnie `GEMINI_API_KEY`,
|
||||
a potem `models.providers.google.apiKey`. `webSearch.baseUrl` jest opcjonalne i
|
||||
istnieje dla proxy operatora lub zgodnych punktów końcowych Gemini API; gdy zostanie pominięte,
|
||||
wyszukiwanie w sieci Gemini ponownie wykorzystuje `models.providers.google.baseUrl`. Zobacz
|
||||
[wyszukiwanie Gemini](/pl/tools/gemini-search), aby poznać zachowanie narzędzia specyficzne dla dostawcy.
|
||||
|
||||
<Tip>
|
||||
Modele Gemini 3 używają `thinkingLevel` zamiast `thinkingBudget`. OpenClaw mapuje
|
||||
kontrolki rozumowania aliasów Gemini 3, Gemini 3.1 i `gemini-*-latest` na
|
||||
kontrolki rozumowania dla aliasów Gemini 3, Gemini 3.1 i `gemini-*-latest` na
|
||||
`thinkingLevel`, aby uruchomienia domyślne/o niskim opóźnieniu nie wysyłały wyłączonych
|
||||
wartości `thinkingBudget`.
|
||||
|
||||
`/think adaptive` zachowuje dynamiczną semantykę myślenia Google zamiast wybierać
|
||||
stały poziom OpenClaw. Gemini 3 i Gemini 3.1 pomijają stały `thinkingLevel`, aby
|
||||
Google mogło wybrać poziom; Gemini 2.5 wysyła dynamiczny sentinel Google
|
||||
`/think adaptive` zachowuje semantykę dynamicznego myślenia Google zamiast wybierać
|
||||
stały poziom OpenClaw. Gemini 3 i Gemini 3.1 pomijają stałe `thinkingLevel`, aby
|
||||
Google mógł wybrać poziom; Gemini 2.5 wysyła dynamiczny sentinel Google
|
||||
`thinkingBudget: -1`.
|
||||
|
||||
Modele Gemma 4 (na przykład `gemma-4-26b-a4b-it`) obsługują tryb myślenia. OpenClaw
|
||||
przepisuje `thinkingBudget` na obsługiwany przez Google `thinkingLevel` dla Gemma 4.
|
||||
przepisuje `thinkingBudget` na obsługiwane przez Google `thinkingLevel` dla Gemma 4.
|
||||
Ustawienie myślenia na `off` zachowuje wyłączone myślenie zamiast mapowania na
|
||||
`MINIMAL`.
|
||||
</Tip>
|
||||
@ -203,12 +203,12 @@ Ustawienie myślenia na `off` zachowuje wyłączone myślenie zamiast mapowania
|
||||
Dołączony dostawca generowania obrazów `google` domyślnie używa
|
||||
`google/gemini-3.1-flash-image-preview`.
|
||||
|
||||
- Obsługuje także `google/gemini-3-pro-image-preview`
|
||||
- Obsługuje też `google/gemini-3-pro-image-preview`
|
||||
- Generowanie: do 4 obrazów na żądanie
|
||||
- Tryb edycji: włączony, do 5 obrazów wejściowych
|
||||
- Kontrolki geometrii: `size`, `aspectRatio` i `resolution`
|
||||
|
||||
Aby użyć Google jako domyślnego dostawcy obrazów:
|
||||
Aby używać Google jako domyślnego dostawcy obrazów:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -223,20 +223,20 @@ Aby użyć Google jako domyślnego dostawcy obrazów:
|
||||
```
|
||||
|
||||
<Note>
|
||||
Zobacz [Generowanie obrazów](/pl/tools/image-generation), aby poznać wspólne parametry narzędzia, wybór dostawcy i zachowanie failover.
|
||||
Zobacz [Generowanie obrazów](/pl/tools/image-generation), aby poznać wspólne parametry narzędzia, wybór dostawcy i zachowanie awaryjnego przełączania.
|
||||
</Note>
|
||||
|
||||
## Generowanie wideo
|
||||
|
||||
Dołączony Plugin `google` rejestruje także generowanie wideo przez współdzielone
|
||||
Dołączony Plugin `google` rejestruje też generowanie wideo przez współdzielone
|
||||
narzędzie `video_generate`.
|
||||
|
||||
- Domyślny model wideo: `google/veo-3.1-fast-generate-preview`
|
||||
- Tryby: przepływy tekst-na-wideo, obraz-na-wideo i pojedynczego odniesienia wideo
|
||||
- Tryby: tekst-na-wideo, obraz-na-wideo i przepływy z pojedynczym wideo referencyjnym
|
||||
- Obsługuje `aspectRatio`, `resolution` i `audio`
|
||||
- Obecne ograniczenie czasu trwania: **od 4 do 8 sekund**
|
||||
- Bieżące ograniczenie czasu trwania: **od 4 do 8 sekund**
|
||||
|
||||
Aby użyć Google jako domyślnego dostawcy wideo:
|
||||
Aby używać Google jako domyślnego dostawcy wideo:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -251,22 +251,22 @@ Aby użyć Google jako domyślnego dostawcy wideo:
|
||||
```
|
||||
|
||||
<Note>
|
||||
Zobacz [Generowanie wideo](/pl/tools/video-generation), aby poznać wspólne parametry narzędzia, wybór dostawcy i zachowanie failover.
|
||||
Zobacz [Generowanie wideo](/pl/tools/video-generation), aby poznać wspólne parametry narzędzia, wybór dostawcy i zachowanie awaryjnego przełączania.
|
||||
</Note>
|
||||
|
||||
## Generowanie muzyki
|
||||
|
||||
Dołączony Plugin `google` rejestruje także generowanie muzyki przez współdzielone
|
||||
Dołączony Plugin `google` rejestruje też generowanie muzyki przez współdzielone
|
||||
narzędzie `music_generate`.
|
||||
|
||||
- Domyślny model muzyki: `google/lyria-3-clip-preview`
|
||||
- Obsługuje także `google/lyria-3-pro-preview`
|
||||
- Obsługuje też `google/lyria-3-pro-preview`
|
||||
- Kontrolki promptu: `lyrics` i `instrumental`
|
||||
- Format wyjściowy: domyślnie `mp3`, a także `wav` w `google/lyria-3-pro-preview`
|
||||
- Format wyjściowy: domyślnie `mp3`, dodatkowo `wav` w `google/lyria-3-pro-preview`
|
||||
- Wejścia referencyjne: do 10 obrazów
|
||||
- Uruchomienia oparte na sesji odłączają się przez współdzielony przepływ zadania/statusu, w tym `action: "status"`
|
||||
|
||||
Aby użyć Google jako domyślnego dostawcy muzyki:
|
||||
Aby używać Google jako domyślnego dostawcy muzyki:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -281,7 +281,7 @@ Aby użyć Google jako domyślnego dostawcy muzyki:
|
||||
```
|
||||
|
||||
<Note>
|
||||
Zobacz [Generowanie muzyki](/pl/tools/music-generation), aby poznać wspólne parametry narzędzia, wybór dostawcy i zachowanie failover.
|
||||
Zobacz [Generowanie muzyki](/pl/tools/music-generation), aby poznać wspólne parametry narzędzia, wybór dostawcy i zachowanie awaryjnego przełączania.
|
||||
</Note>
|
||||
|
||||
## Zamiana tekstu na mowę
|
||||
@ -292,9 +292,9 @@ Dołączony dostawca mowy `google` używa ścieżki TTS Gemini API z
|
||||
- Głos domyślny: `Kore`
|
||||
- Uwierzytelnianie: `messages.tts.providers.google.apiKey`, `models.providers.google.apiKey`, `GEMINI_API_KEY` lub `GOOGLE_API_KEY`
|
||||
- Wyjście: WAV dla zwykłych załączników TTS, Opus dla celów notatek głosowych, PCM dla Talk/telefonii
|
||||
- Wyjście notatki głosowej: Google PCM jest opakowywane jako WAV i transkodowane do Opus 48 kHz przy użyciu `ffmpeg`
|
||||
- Wyjście notatki głosowej: Google PCM jest opakowywany jako WAV i transkodowany do Opus 48 kHz za pomocą `ffmpeg`
|
||||
|
||||
Aby użyć Google jako domyślnego dostawcy TTS:
|
||||
Aby używać Google jako domyślnego dostawcy TTS:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -314,11 +314,11 @@ Aby użyć Google jako domyślnego dostawcy TTS:
|
||||
}
|
||||
```
|
||||
|
||||
TTS Gemini API używa promptów w języku naturalnym do kontroli stylu. Ustaw
|
||||
`audioProfile`, aby dodać przed wypowiadanym tekstem prompt stylu wielokrotnego użytku. Ustaw
|
||||
Gemini API TTS używa promptowania w języku naturalnym do kontroli stylu. Ustaw
|
||||
`audioProfile`, aby dodać wielokrotnego użytku prompt stylu przed tekstem mówionym. Ustaw
|
||||
`speakerName`, gdy tekst promptu odnosi się do nazwanego mówcy.
|
||||
|
||||
TTS Gemini API akceptuje także ekspresyjne tagi audio w nawiasach kwadratowych w tekście,
|
||||
Gemini API TTS akceptuje też ekspresyjne tagi audio w nawiasach kwadratowych w tekście,
|
||||
takie jak `[whispers]` lub `[laughs]`. Aby tagi nie pojawiały się w widocznej odpowiedzi czatu,
|
||||
ale były wysyłane do TTS, umieść je w bloku `[[tts:text]]...[[/tts:text]]`:
|
||||
|
||||
@ -335,21 +335,23 @@ dostawcy. To nie jest osobna ścieżka Cloud Text-to-Speech API.
|
||||
|
||||
## Głos w czasie rzeczywistym
|
||||
|
||||
Dołączony Plugin `google` rejestruje dostawcę głosu w czasie rzeczywistym opartego na
|
||||
Dołączony Plugin `google` rejestruje dostawcę głosu w czasie rzeczywistym obsługiwanego przez
|
||||
Gemini Live API dla mostów audio backendu, takich jak Voice Call i Google Meet.
|
||||
|
||||
| Ustawienie | Ścieżka konfiguracji | Domyślne |
|
||||
| ----------------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
|
||||
| Model | `plugins.entries.voice-call.config.realtime.providers.google.model` | `gemini-2.5-flash-native-audio-preview-12-2025` |
|
||||
| Głos | `...google.voice` | `Kore` |
|
||||
| Temperatura | `...google.temperature` | (nieustawione) |
|
||||
| Czułość rozpoczęcia VAD | `...google.startSensitivity` | (nieustawione) |
|
||||
| Czułość zakończenia VAD | `...google.endSensitivity` | (nieustawione) |
|
||||
| Czas trwania ciszy | `...google.silenceDurationMs` | (nieustawione) |
|
||||
| Obsługa aktywności | `...google.activityHandling` | domyślne Google, `start-of-activity-interrupts` |
|
||||
| Pokrycie tury | `...google.turnCoverage` | domyślne Google, `only-activity` |
|
||||
| Wyłącz automatyczne VAD | `...google.automaticActivityDetectionDisabled` | `false` |
|
||||
| Klucz API | `...google.apiKey` | Używa awaryjnie `models.providers.google.apiKey`, `GEMINI_API_KEY` lub `GOOGLE_API_KEY` |
|
||||
| Ustawienie | Ścieżka konfiguracji | Domyślnie |
|
||||
| --------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
|
||||
| Model | `plugins.entries.voice-call.config.realtime.providers.google.model` | `gemini-2.5-flash-native-audio-preview-12-2025` |
|
||||
| Głos | `...google.voice` | `Kore` |
|
||||
| Temperatura | `...google.temperature` | (nie ustawiono) |
|
||||
| Czułość początku VAD | `...google.startSensitivity` | (nie ustawiono) |
|
||||
| Czułość końca VAD | `...google.endSensitivity` | (nie ustawiono) |
|
||||
| Czas trwania ciszy | `...google.silenceDurationMs` | (nie ustawiono) |
|
||||
| Obsługa aktywności | `...google.activityHandling` | domyślne Google, `start-of-activity-interrupts` |
|
||||
| Pokrycie tury | `...google.turnCoverage` | domyślne Google, `only-activity` |
|
||||
| Wyłącz automatyczny VAD | `...google.automaticActivityDetectionDisabled` | `false` |
|
||||
| Wznawianie sesji | `...google.sessionResumption` | `true` |
|
||||
| Kompresja kontekstu | `...google.contextWindowCompression` | `true` |
|
||||
| Klucz API | `...google.apiKey` | Używa awaryjnie `models.providers.google.apiKey`, `GEMINI_API_KEY` lub `GOOGLE_API_KEY` |
|
||||
|
||||
Przykładowa konfiguracja połączeń głosowych w czasie rzeczywistym:
|
||||
|
||||
@ -381,8 +383,8 @@ Przykładowa konfiguracja połączeń głosowych w czasie rzeczywistym:
|
||||
|
||||
<Note>
|
||||
Google Live API używa dwukierunkowego audio i wywoływania funkcji przez WebSocket.
|
||||
OpenClaw adaptuje audio z mostka telefonii/Meet do strumienia PCM Live API Gemini i
|
||||
utrzymuje wywołania narzędzi we wspólnym kontrakcie głosu w czasie rzeczywistym. Pozostaw `temperature`
|
||||
OpenClaw dostosowuje audio mostka telefonii/Meet do strumienia Gemini PCM Live API i
|
||||
utrzymuje wywołania narzędzi we współdzielonym kontrakcie głosu w czasie rzeczywistym. Pozostaw `temperature`
|
||||
nieustawione, chyba że potrzebujesz zmian próbkowania; OpenClaw pomija wartości niedodatnie,
|
||||
ponieważ Google Live może zwracać transkrypcje bez audio dla `temperature: 0`.
|
||||
Transkrypcja Gemini API jest włączona bez `languageCodes`; obecny Google
|
||||
@ -390,29 +392,29 @@ SDK odrzuca podpowiedzi kodów języka w tej ścieżce API.
|
||||
</Note>
|
||||
|
||||
<Note>
|
||||
Control UI Talk obsługuje sesje Google Live w przeglądarce z ograniczonymi tokenami
|
||||
jednorazowego użytku. Backendowe dostawcy głosu w czasie rzeczywistym mogą także działać przez ogólny
|
||||
transport przekaźnikowy Gateway, który przechowuje dane uwierzytelniające dostawcy w Gateway.
|
||||
Control UI Talk obsługuje sesje Google Live w przeglądarce z ograniczonymi tokenami jednorazowego użytku.
|
||||
Dostawcy głosu w czasie rzeczywistym działający tylko w backendzie mogą też działać przez ogólny
|
||||
transport przekaźnikowy Gateway, który utrzymuje poświadczenia dostawcy w Gateway.
|
||||
</Note>
|
||||
|
||||
Do weryfikacji live przez maintainerów uruchom
|
||||
Do weryfikacji na żywo przez opiekuna uruchom
|
||||
`OPENAI_API_KEY=... GEMINI_API_KEY=... node --import tsx scripts/dev/realtime-talk-live-smoke.ts`.
|
||||
Część Google wystawia ten sam ograniczony kształt tokenu Live API, którego używa Control
|
||||
UI Talk, otwiera endpoint WebSocket przeglądarki, wysyła początkowy payload konfiguracji
|
||||
Odcinek Google wybija ten sam ograniczony kształt tokena Live API, którego używa Control
|
||||
UI Talk, otwiera punkt końcowy WebSocket przeglądarki, wysyła początkowy ładunek konfiguracji
|
||||
i czeka na `setupComplete`.
|
||||
|
||||
## Zaawansowana konfiguracja
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Bezpośrednie ponowne użycie cache Gemini">
|
||||
Dla bezpośrednich uruchomień Gemini API (`api: "google-generative-ai"`) OpenClaw
|
||||
<Accordion title="Direct Gemini cache reuse">
|
||||
W przypadku bezpośrednich uruchomień Gemini API (`api: "google-generative-ai"`) OpenClaw
|
||||
przekazuje skonfigurowany uchwyt `cachedContent` do żądań Gemini.
|
||||
|
||||
- Skonfiguruj parametry dla modelu lub globalne za pomocą
|
||||
`cachedContent` albo starszego `cached_content`
|
||||
- Jeśli obecne są oba, wygrywa `cachedContent`
|
||||
- Jeśli obecne są oba, pierwszeństwo ma `cachedContent`
|
||||
- Przykładowa wartość: `cachedContents/prebuilt-context`
|
||||
- Użycie trafień cache Gemini jest normalizowane do OpenClaw `cacheRead` z
|
||||
- Użycie trafień w pamięć podręczną Gemini jest normalizowane do OpenClaw `cacheRead` z
|
||||
nadrzędnego `cachedContentTokenCount`
|
||||
|
||||
```json5
|
||||
@ -433,19 +435,19 @@ i czeka na `setupComplete`.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Uwagi dotyczące użycia JSON Gemini CLI">
|
||||
<Accordion title="Gemini CLI JSON usage notes">
|
||||
Podczas używania dostawcy OAuth `google-gemini-cli` OpenClaw normalizuje
|
||||
wyjście JSON CLI w następujący sposób:
|
||||
wyjście CLI JSON w następujący sposób:
|
||||
|
||||
- Tekst odpowiedzi pochodzi z pola `response` w JSON CLI.
|
||||
- Użycie korzysta awaryjnie ze `stats`, gdy CLI pozostawia `usage` puste.
|
||||
- Tekst odpowiedzi pochodzi z pola CLI JSON `response`.
|
||||
- Użycie korzysta awaryjnie z `stats`, gdy CLI pozostawia `usage` puste.
|
||||
- `stats.cached` jest normalizowane do OpenClaw `cacheRead`.
|
||||
- Jeśli brakuje `stats.input`, OpenClaw wyprowadza tokeny wejściowe z
|
||||
- Jeśli brakuje `stats.input`, OpenClaw wylicza tokeny wejściowe z
|
||||
`stats.input_tokens - stats.cached`.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Konfiguracja środowiska i demona">
|
||||
<Accordion title="Environment and daemon setup">
|
||||
Jeśli Gateway działa jako demon (launchd/systemd), upewnij się, że `GEMINI_API_KEY`
|
||||
jest dostępny dla tego procesu (na przykład w `~/.openclaw/.env` lub przez
|
||||
`env.shellEnv`).
|
||||
@ -455,16 +457,16 @@ i czeka na `setupComplete`.
|
||||
## Powiązane
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Wybór modelu" href="/pl/concepts/model-providers" icon="layers">
|
||||
Wybór dostawców, odwołań do modeli i zachowania przełączania awaryjnego.
|
||||
<Card title="Model selection" href="/pl/concepts/model-providers" icon="layers">
|
||||
Wybieranie dostawców, referencji modeli i zachowania przełączania awaryjnego.
|
||||
</Card>
|
||||
<Card title="Generowanie obrazów" href="/pl/tools/image-generation" icon="image">
|
||||
Wspólne parametry narzędzia obrazów i wybór dostawcy.
|
||||
<Card title="Image generation" href="/pl/tools/image-generation" icon="image">
|
||||
Współdzielone parametry narzędzia obrazów i wybór dostawcy.
|
||||
</Card>
|
||||
<Card title="Generowanie wideo" href="/pl/tools/video-generation" icon="video">
|
||||
Wspólne parametry narzędzia wideo i wybór dostawcy.
|
||||
<Card title="Video generation" href="/pl/tools/video-generation" icon="video">
|
||||
Współdzielone parametry narzędzia wideo i wybór dostawcy.
|
||||
</Card>
|
||||
<Card title="Generowanie muzyki" href="/pl/tools/music-generation" icon="music">
|
||||
Wspólne parametry narzędzia muzyki i wybór dostawcy.
|
||||
<Card title="Music generation" href="/pl/tools/music-generation" icon="music">
|
||||
Współdzielone parametry narzędzia muzyki i wybór dostawcy.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
@ -2,179 +2,180 @@
|
||||
read_when:
|
||||
- Wyszukiwanie definicji publicznych kanałów wydań
|
||||
- Uruchamianie walidacji wydania lub akceptacji pakietu
|
||||
- Szukasz nazewnictwa wersji i cyklu wydań
|
||||
summary: Ścieżki wydań, lista kontrolna operatora, boksy walidacyjne, nazewnictwo wersji i rytm
|
||||
- Szukanie nazewnictwa wersji i cyklu wydań
|
||||
summary: Ścieżki wydań, lista kontrolna operatora, środowiska walidacyjne, nazewnictwo wersji i kadencja
|
||||
title: Polityka wydań
|
||||
x-i18n:
|
||||
generated_at: "2026-05-03T21:35:47Z"
|
||||
generated_at: "2026-05-04T07:06:14Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 566088d826e1e2bac21b11443b82b62cb73ed1fd9c508c3fb865149cf8a428ba
|
||||
source_hash: ef50d3ef5d1e23b4e2c2b097fc4ca9f6d46bf8acb9aea0c9bca6d14e213b88b6
|
||||
source_path: reference/RELEASING.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
OpenClaw ma trzy publiczne kanały wydań:
|
||||
OpenClaw ma trzy publiczne ścieżki wydań:
|
||||
|
||||
- stabilny: oznaczone tagami wydania, które domyślnie publikują do npm `beta`, albo do npm `latest`, gdy zostanie to wyraźnie zażądane
|
||||
- beta: tagi wydań przedpremierowych, które publikują do npm `beta`
|
||||
- dev: ruchoma głowica gałęzi `main`
|
||||
- stable: oznaczone wydania, które domyślnie publikują do npm `beta`, albo do npm `latest`, gdy zostanie to wyraźnie zażądane
|
||||
- beta: tagi przedpremierowe, które publikują do npm `beta`
|
||||
- dev: ruchoma głowica `main`
|
||||
|
||||
## Nazewnictwo wersji
|
||||
|
||||
- Wersja stabilnego wydania: `YYYY.M.D`
|
||||
- Wersja wydania stabilnego: `YYYY.M.D`
|
||||
- Tag Git: `vYYYY.M.D`
|
||||
- Wersja stabilnego wydania poprawkowego: `YYYY.M.D-N`
|
||||
- Tag Git: `vYYYY.M.D-N`
|
||||
- Wersja wydania przedpremierowego beta: `YYYY.M.D-beta.N`
|
||||
- Wersja przedpremierowa beta: `YYYY.M.D-beta.N`
|
||||
- Tag Git: `vYYYY.M.D-beta.N`
|
||||
- Nie dopełniaj miesiąca ani dnia zerami
|
||||
- `latest` oznacza bieżące promowane stabilne wydanie npm
|
||||
- `beta` oznacza bieżący docelowy wariant instalacji beta
|
||||
- Wydania stabilne i stabilne wydania poprawkowe domyślnie publikują do npm `beta`; operatorzy wydania mogą jawnie wskazać `latest` albo później promować sprawdzoną kompilację beta
|
||||
- `beta` oznacza bieżący cel instalacji beta
|
||||
- Wydania stabilne i stabilne wydania poprawkowe domyślnie publikują do npm `beta`; operatorzy wydania mogą jawnie wskazać `latest` albo później promować sprawdzony build beta
|
||||
- Każde stabilne wydanie OpenClaw dostarcza razem pakiet npm i aplikację macOS;
|
||||
wydania beta zwykle najpierw weryfikują i publikują ścieżkę npm/pakietu, a
|
||||
kompilowanie/podpisywanie/notaryzacja aplikacji Mac są zarezerwowane dla wydań stabilnych, chyba że zostaną wyraźnie zażądane
|
||||
wydania beta zwykle najpierw walidują i publikują ścieżkę npm/pakietu, a
|
||||
build/podpisywanie/notaryzację aplikacji mac rezerwują dla wydań stabilnych, chyba że wyraźnie zażądano inaczej
|
||||
|
||||
## Rytm wydań
|
||||
## Cykl wydań
|
||||
|
||||
- Wydania przechodzą najpierw przez beta
|
||||
- Wydanie stabilne następuje dopiero po zweryfikowaniu najnowszej wersji beta
|
||||
- Opiekunowie zwykle tworzą wydania z gałęzi `release/YYYY.M.D` utworzonej
|
||||
z bieżącej `main`, aby weryfikacja wydania i poprawki nie blokowały nowego
|
||||
- Stable następuje dopiero po zwalidowaniu najnowszej beta
|
||||
- Maintainerzy zwykle odcinają wydania z gałęzi `release/YYYY.M.D` utworzonej
|
||||
z bieżącej `main`, aby walidacja wydania i poprawki nie blokowały nowego
|
||||
rozwoju na `main`
|
||||
- Jeśli tag beta został wypchnięty lub opublikowany i wymaga poprawki, opiekunowie tworzą
|
||||
następny tag `-beta.N` zamiast usuwać lub odtwarzać stary tag beta
|
||||
- Jeśli tag beta został wypchnięty lub opublikowany i wymaga poprawki, maintainerzy odcinają
|
||||
następny tag `-beta.N` zamiast usuwać albo odtwarzać stary tag beta
|
||||
- Szczegółowa procedura wydania, zatwierdzenia, poświadczenia i notatki odzyskiwania są
|
||||
dostępne tylko dla opiekunów
|
||||
dostępne tylko dla maintainerów
|
||||
|
||||
## Lista kontrolna operatora wydania
|
||||
|
||||
Ta lista kontrolna pokazuje publiczny kształt przepływu wydania. Prywatne poświadczenia,
|
||||
podpisywanie, notaryzacja, odzyskiwanie dist-tagów i szczegóły awaryjnego wycofywania pozostają w
|
||||
runbooku wydań dostępnym tylko dla opiekunów.
|
||||
podpisywanie, notaryzacja, odzyskiwanie dist-tag i szczegóły awaryjnego rollbacku pozostają w
|
||||
runbooku wydaniowym dostępnym tylko dla maintainerów.
|
||||
|
||||
1. Zacznij od bieżącej `main`: pobierz najnowsze zmiany, potwierdź, że docelowy commit został wypchnięty,
|
||||
i potwierdź, że bieżące CI `main` jest wystarczająco zielone, aby utworzyć z niej gałąź.
|
||||
2. Przepisz najwyższą sekcję `CHANGELOG.md` na podstawie rzeczywistej historii commitów za pomocą
|
||||
`/changelog`, utrzymaj wpisy jako skierowane do użytkowników, zatwierdź je commitem, wypchnij, a następnie jeszcze raz wykonaj rebase/pull
|
||||
przed utworzeniem gałęzi.
|
||||
3. Przejrzyj rekordy zgodności wydań w
|
||||
2. Przepisz górną sekcję `CHANGELOG.md` na podstawie rzeczywistej historii commitów za pomocą
|
||||
`/changelog`, zachowaj wpisy skierowane do użytkowników, zatwierdź ją commitem, wypchnij ją i wykonaj rebase/pull
|
||||
jeszcze raz przed utworzeniem gałęzi.
|
||||
3. Przejrzyj rekordy kompatybilności wydania w
|
||||
`src/plugins/compat/registry.ts` i
|
||||
`src/commands/doctor/shared/deprecation-compat.ts`. Usuwaj wygasłą
|
||||
zgodność tylko wtedy, gdy ścieżka aktualizacji pozostaje pokryta, albo zapisz, dlaczego jest
|
||||
kompatybilność tylko wtedy, gdy ścieżka aktualizacji pozostaje pokryta, albo odnotuj, dlaczego jest
|
||||
celowo utrzymywana.
|
||||
4. Utwórz `release/YYYY.M.D` z bieżącej `main`; nie wykonuj normalnej pracy nad wydaniem
|
||||
4. Utwórz `release/YYYY.M.D` z bieżącej `main`; nie wykonuj normalnych prac wydaniowych
|
||||
bezpośrednio na `main`.
|
||||
5. Podbij każdą wymaganą lokalizację wersji dla zamierzonego tagu, uruchom
|
||||
`pnpm plugins:sync`, aby publikowalne pakiety Plugin miały wspólną wersję wydania
|
||||
i metadane zgodności, a następnie uruchom lokalny deterministyczny preflight:
|
||||
5. Podbij każde wymagane miejsce wersji dla zamierzonego taga, uruchom
|
||||
`pnpm plugins:sync`, aby publikowalne pakiety Plugin współdzieliły wersję wydania
|
||||
i metadane kompatybilności, a następnie uruchom lokalny deterministyczny preflight:
|
||||
`pnpm check:test-types`, `pnpm check:architecture`,
|
||||
`pnpm build && pnpm ui:build`, `pnpm plugins:sync:check` i
|
||||
`pnpm release:check`.
|
||||
6. Uruchom `OpenClaw NPM Release` z `preflight_only=true`. Zanim tag istnieje,
|
||||
pełny 40-znakowy SHA gałęzi wydania jest dozwolony wyłącznie do walidacji
|
||||
preflight. Zapisz pomyślny `preflight_run_id`.
|
||||
pełny 40-znakowy SHA gałęzi wydania jest dozwolony dla preflight tylko walidacyjnego.
|
||||
Zapisz udany `preflight_run_id`.
|
||||
7. Uruchom wszystkie testy przedwydaniowe za pomocą `Full Release Validation` dla
|
||||
gałęzi wydania, tagu albo pełnego SHA commita. To jedyny ręczny punkt wejścia
|
||||
dla czterech dużych testowych środowisk wydań: Vitest, Docker, QA Lab i Package.
|
||||
gałęzi wydania, taga lub pełnego SHA commita. To jest jedyny ręczny punkt wejścia
|
||||
dla czterech dużych skrzynek testowych wydania: Vitest, Docker, QA Lab i Package.
|
||||
8. Jeśli walidacja się nie powiedzie, napraw na gałęzi wydania i ponownie uruchom najmniejszy nieudany
|
||||
plik, kanał, zadanie workflow, profil pakietu, dostawcę albo listę dozwolonych modeli, które
|
||||
potwierdzają poprawkę. Ponownie uruchom pełny parasol tylko wtedy, gdy zmieniona powierzchnia sprawia, że
|
||||
wcześniejsze dowody są nieaktualne.
|
||||
plik, ścieżkę, zadanie workflow, profil pakietu, providera lub allowlistę modelu, która
|
||||
dowodzi poprawki. Ponownie uruchamiaj pełną parasolową walidację tylko wtedy, gdy zmieniony obszar sprawia,
|
||||
że wcześniejsze dowody są nieaktualne.
|
||||
9. Dla beta oznacz tagiem `vYYYY.M.D-beta.N`, a następnie uruchom `OpenClaw Release Publish` z
|
||||
odpowiadającej gałęzi `release/YYYY.M.D`. Weryfikuje `pnpm plugins:sync:check`,
|
||||
pasującej gałęzi `release/YYYY.M.D`. Weryfikuje `pnpm plugins:sync:check`,
|
||||
najpierw publikuje wszystkie publikowalne pakiety Plugin do npm, następnie publikuje ten sam
|
||||
zestaw do ClawHub jako tarballe ClawPack npm-pack, a potem promuje
|
||||
przygotowany artefakt preflight npm OpenClaw z pasującym dist-tagiem. Po
|
||||
zestaw do ClawHub jako tarballe npm-pack ClawPack, a potem promuje
|
||||
przygotowany artefakt preflight npm OpenClaw z pasującym dist-tag. Po
|
||||
publikacji uruchom akceptację pakietu po publikacji
|
||||
względem opublikowanego pakietu `openclaw@YYYY.M.D-beta.N` albo
|
||||
względem opublikowanego pakietu `openclaw@YYYY.M.D-beta.N` lub
|
||||
`openclaw@beta`. Jeśli wypchnięte lub opublikowane wydanie przedpremierowe wymaga poprawki,
|
||||
utwórz następny pasujący numer wydania przedpremierowego; nie usuwaj ani nie przepisuj starego
|
||||
odetnij następny pasujący numer wydania przedpremierowego; nie usuwaj ani nie przepisuj starego
|
||||
wydania przedpremierowego.
|
||||
10. Dla wydania stabilnego kontynuuj dopiero po tym, jak sprawdzona beta lub kandydat do wydania ma
|
||||
wymagane dowody walidacji. Publikacja stabilna npm również przechodzi przez
|
||||
`OpenClaw Release Publish`, ponownie używając pomyślnego artefaktu preflight przez
|
||||
`preflight_run_id`; gotowość stabilnego wydania macOS wymaga także
|
||||
10. Dla stable kontynuuj dopiero po tym, jak sprawdzona beta lub release candidate ma
|
||||
wymagane dowody walidacji. Publikacja stabilnego npm również przechodzi przez
|
||||
`OpenClaw Release Publish`, ponownie używając udanego artefaktu preflight przez
|
||||
`preflight_run_id`; gotowość stabilnego wydania macOS wymaga również
|
||||
spakowanych `.zip`, `.dmg`, `.dSYM.zip` i zaktualizowanego `appcast.xml` na `main`.
|
||||
11. Po publikacji uruchom weryfikator npm po publikacji, opcjonalne samodzielne
|
||||
E2E opublikowanego npm dla Telegram, gdy potrzebujesz dowodu kanału po publikacji,
|
||||
promocję dist-tagu, gdy jest potrzebna, notatki wydania/przedpremierowego GitHub z
|
||||
kompletnej pasującej sekcji `CHANGELOG.md` oraz kroki ogłoszenia wydania.
|
||||
11. Po publikacji uruchom weryfikator npm po publikacji, opcjonalny samodzielny
|
||||
opublikowany-npm Telegram E2E, gdy potrzebujesz dowodu kanału po publikacji,
|
||||
promocję dist-tag, gdy jest potrzebna, notatki GitHub wydania/wydania przedpremierowego z
|
||||
pełnej pasującej sekcji `CHANGELOG.md` oraz kroki ogłoszenia wydania.
|
||||
|
||||
## Preflight wydania
|
||||
|
||||
- Uruchom `pnpm check:test-types` przed kontrolą wstępną wydania, aby testowy TypeScript pozostał objęty kontrolą poza szybszą lokalną bramką `pnpm check`
|
||||
- Uruchom `pnpm check:architecture` przed kontrolą wstępną wydania, aby szersze kontrole cykli importu i granic architektury były zielone poza szybszą lokalną bramką
|
||||
- Uruchom `pnpm build && pnpm ui:build` przed `pnpm release:check`, aby oczekiwane artefakty wydania `dist/*` i pakiet Control UI istniały dla kroku walidacji pakietu
|
||||
- Uruchom `pnpm plugins:sync` po podbiciu wersji w katalogu głównym i przed tagowaniem. Aktualizuje wersje pakietów publikowalnych pluginów, metadane zgodności peer/API OpenClaw, metadane kompilacji i szkice dzienników zmian pluginów tak, aby pasowały do wersji wydania rdzenia. `pnpm plugins:sync:check` to niemutująca straż wydania; przepływ publikowania kończy się niepowodzeniem przed jakąkolwiek mutacją rejestru, jeśli ten krok został pominięty.
|
||||
- Uruchom ręczny przepływ `Full Release Validation` przed zatwierdzeniem wydania, aby uruchomić wszystkie przedwydaniowe boksy testowe z jednego punktu wejścia. Przyjmuje gałąź, tag albo pełny SHA commita, uruchamia ręczny `CI` i uruchamia `OpenClaw Release Checks` dla testu instalacji, akceptacji pakietu, zestawów ścieżki wydania Dockera, testów live/E2E, OpenWebUI, parytetu QA Lab, Matrix i ścieżek Telegram. Z `release_profile=full` oraz `rerun_group=all` uruchamia też pakietowe Telegram E2E względem artefaktu `release-package-under-test` z kontroli wydania. Podaj `npm_telegram_package_spec` po publikacji, gdy ten sam Telegram E2E ma także zweryfikować opublikowany pakiet npm. Podaj `package_acceptance_package_spec` po publikacji, gdy Package Acceptance ma uruchomić swoją macierz pakietu/aktualizacji względem wysłanego pakietu npm zamiast artefaktu zbudowanego z SHA. Podaj `evidence_package_spec`, gdy prywatny raport dowodowy ma potwierdzić, że walidacja odpowiada opublikowanemu pakietowi npm bez wymuszania Telegram E2E. Przykład:
|
||||
- Uruchom `pnpm check:test-types` przed preflightem wydania, aby testowy TypeScript pozostawał objęty sprawdzaniem poza szybszą lokalną bramką `pnpm check`
|
||||
- Uruchom `pnpm check:architecture` przed preflightem wydania, aby szersze kontrole cykli importów i granic architektury były zielone poza szybszą lokalną bramką
|
||||
- Uruchom `pnpm build && pnpm ui:build` przed `pnpm release:check`, aby oczekiwane artefakty wydania `dist/*` i pakiet Control UI istniały na potrzeby etapu walidacji pakietu
|
||||
- Uruchom `pnpm plugins:sync` po podbiciu wersji w katalogu głównym i przed tagowaniem. Aktualizuje wersje publikowalnych pakietów Plugin, metadane zgodności peer/API OpenClaw, metadane builda oraz szkielety changelogów Plugin, aby odpowiadały wersji wydania core. `pnpm plugins:sync:check` to niemutująca osłona wydania; workflow publikowania kończy się niepowodzeniem przed jakąkolwiek mutacją rejestru, jeśli ten krok został pominięty.
|
||||
- Uruchom ręczny workflow `Full Release Validation` przed zatwierdzeniem wydania, aby z jednego punktu wejścia uruchomić wszystkie przedwydaniowe testboksy. Przyjmuje gałąź, tag lub pełny SHA commita, uruchamia ręczny `CI` oraz uruchamia `OpenClaw Release Checks` dla instalacyjnego smoke testu, akceptacji pakietu, zestawów ścieżki wydania Docker, live/E2E, OpenWebUI, parytetu QA Lab, Matrix i ścieżek Telegram. Przy `release_profile=full` i `rerun_group=all` uruchamia także pakietowe Telegram E2E względem artefaktu `release-package-under-test` z kontroli wydania. Podaj `npm_telegram_package_spec` po publikacji, gdy to samo Telegram E2E ma również potwierdzić opublikowany pakiet npm. Podaj `package_acceptance_package_spec` po publikacji, gdy Package Acceptance ma uruchomić swoją macierz pakietu/aktualizacji względem wysłanego pakietu npm zamiast artefaktu zbudowanego z SHA. Podaj `evidence_package_spec`, gdy prywatny raport dowodowy ma potwierdzić, że walidacja odpowiada opublikowanemu pakietowi npm bez wymuszania Telegram E2E. Przykład:
|
||||
`gh workflow run full-release-validation.yml --ref main -f ref=release/YYYY.M.D`
|
||||
- Uruchom ręczny przepływ `Package Acceptance`, gdy chcesz uzyskać dowód kanałem pobocznym dla kandydata pakietu, podczas gdy prace nad wydaniem trwają. Użyj `source=npm` dla `openclaw@beta`, `openclaw@latest` albo dokładnej wersji wydania; `source=ref`, aby spakować zaufaną gałąź/tag/SHA `package_ref` z bieżącym zestawem `workflow_ref`; `source=url` dla tarballa HTTPS z wymaganym SHA-256; albo `source=artifact` dla tarballa przesłanego przez inny przebieg GitHub Actions. Przepływ rozwiązuje kandydata do `package-under-test`, ponownie używa harmonogramu wydania Docker E2E względem tego tarballa i może uruchomić QA Telegram względem tego samego tarballa z `telegram_mode=mock-openai` albo `telegram_mode=live-frontier`. Gdy wybrane ścieżki Dockera obejmują `published-upgrade-survivor`, artefakt pakietu jest kandydatem, a `published_upgrade_survivor_baseline` wybiera opublikowaną bazę.
|
||||
- Uruchom ręczny workflow `Package Acceptance`, gdy chcesz uzyskać dowód kanałem bocznym dla kandydata pakietu, podczas gdy prace nad wydaniem trwają. Użyj `source=npm` dla `openclaw@beta`, `openclaw@latest` lub dokładnej wersji wydania; `source=ref`, aby spakować zaufaną gałąź/tag/SHA `package_ref` z bieżącym harness `workflow_ref`; `source=url` dla archiwum tarball HTTPS z wymaganym SHA-256; albo `source=artifact` dla archiwum tarball przesłanego przez inny przebieg GitHub Actions. Workflow rozwiązuje kandydata do `package-under-test`, ponownie używa harmonogramu wydania Docker E2E względem tego archiwum tarball i może uruchomić QA Telegram względem tego samego archiwum tarball z `telegram_mode=mock-openai` lub `telegram_mode=live-frontier`. Gdy wybrane ścieżki Docker obejmują `published-upgrade-survivor`, artefakt pakietu jest kandydatem, a `published_upgrade_survivor_baseline` wybiera opublikowaną bazę.
|
||||
Przykład: `gh workflow run package-acceptance.yml --ref main -f workflow_ref=main -f source=npm -f package_spec=openclaw@beta -f suite_profile=product -f published_upgrade_survivor_baseline=openclaw@2026.4.26 -f telegram_mode=mock-openai`
|
||||
Typowe profile:
|
||||
- `smoke`: ścieżki instalacji/kanału/agenta, sieci Gateway i ponownego wczytania konfiguracji
|
||||
- `package`: natywne dla artefaktu ścieżki pakietu/aktualizacji/pluginu bez OpenWebUI ani live ClawHub
|
||||
- `product`: profil pakietu plus kanały MCP, czyszczenie cron/subagenta, wyszukiwanie internetowe OpenAI i OpenWebUI
|
||||
- `full`: fragmenty ścieżki wydania Dockera z OpenWebUI
|
||||
- `smoke`: ścieżki instalacji/kanału/agenta, sieci Gateway i przeładowania konfiguracji
|
||||
- `package`: natywne dla artefaktu ścieżki pakietu/aktualizacji/Plugin bez OpenWebUI ani live ClawHub
|
||||
- `product`: profil pakietu plus kanały MCP, czyszczenie cron/subagenta, wyszukiwanie webowe OpenAI i OpenWebUI
|
||||
- `full`: fragmenty ścieżki wydania Docker z OpenWebUI
|
||||
- `custom`: dokładny wybór `docker_lanes` dla ukierunkowanego ponownego uruchomienia
|
||||
- Uruchom ręczny przepływ `CI` bezpośrednio, gdy potrzebujesz tylko pełnego normalnego pokrycia CI dla kandydata wydania. Ręczne uruchomienia CI omijają zakresowanie zmian i wymuszają ścieżki shardów Linux Node, shardów bundled-plugin, kontraktów kanałów, zgodności Node 22, `check`, `check-additional`, testu kompilacji, kontroli dokumentacji, Python skills, Windows, macOS, Android oraz Control UI i18n.
|
||||
- Uruchom ręczny workflow `CI` bezpośrednio, gdy potrzebujesz tylko pełnego normalnego pokrycia CI dla kandydata wydania. Ręczne uruchomienia CI omijają zakresowanie zmian i wymuszają shardy Linux Node, shardy bundled-plugin, kontrakty kanałów, zgodność Node 22, `check`, `check-additional`, smoke test builda, kontrole dokumentacji, Python skills, Windows, macOS, Android oraz ścieżki i18n Control UI.
|
||||
Przykład: `gh workflow run ci.yml --ref release/YYYY.M.D`
|
||||
- Uruchom `pnpm qa:otel:smoke` podczas walidacji telemetrii wydania. Ćwiczy QA-lab przez lokalny odbiornik OTLP/HTTP i weryfikuje wyeksportowane nazwy spanów śladu, ograniczone atrybuty oraz redakcję treści/identyfikatorów bez wymagania Opik, Langfuse ani innego zewnętrznego kolektora.
|
||||
- Uruchom `pnpm qa:otel:smoke` podczas walidowania telemetrii wydania. Ćwiczy QA-lab przez lokalny odbiornik OTLP/HTTP i weryfikuje wyeksportowane nazwy spanów śledzenia, ograniczone atrybuty oraz redakcję treści/identyfikatorów bez wymagania Opik, Langfuse ani innego zewnętrznego kolektora.
|
||||
- Uruchom `pnpm release:check` przed każdym tagowanym wydaniem
|
||||
- Uruchom `OpenClaw Release Publish` dla mutującej sekwencji publikowania po utworzeniu taga. Wywołaj go z `release/YYYY.M.D` (albo `main`, gdy publikujesz tag osiągalny z main), przekaż tag wydania i udany `preflight_run_id` npm OpenClaw oraz zachowaj domyślny zakres publikowania pluginów `all-publishable`, chyba że celowo uruchamiasz ukierunkowaną naprawę. Przepływ serializuje publikowanie pluginów npm, publikowanie pluginów ClawHub i publikowanie npm OpenClaw, aby pakiet rdzenia nie został opublikowany przed jego zewnętrznymi pluginami.
|
||||
- Kontrole wydania działają teraz w osobnym ręcznym przepływie:
|
||||
- Uruchom `OpenClaw Release Publish` dla mutującej sekwencji publikowania po utworzeniu tagu. Uruchom go z `release/YYYY.M.D` (lub `main`, gdy publikujesz tag osiągalny z main), przekaż tag wydania i zakończony powodzeniem `preflight_run_id` npm OpenClaw oraz zachowaj domyślny zakres publikowania Plugin `all-publishable`, chyba że celowo uruchamiasz ukierunkowaną naprawę. Workflow serializuje publikowanie Plugin do npm, publikowanie Plugin do ClawHub i publikowanie OpenClaw do npm, aby pakiet core nie został opublikowany przed jego zewnętrznymi Plugin.
|
||||
- Kontrole wydania działają teraz w osobnym ręcznym workflow:
|
||||
`OpenClaw Release Checks`
|
||||
- `OpenClaw Release Checks` uruchamia też ścieżkę parytetu mock QA Lab oraz szybki profil live Matrix i ścieżkę QA Telegram przed zatwierdzeniem wydania. Ścieżki live używają środowiska `qa-live-shared`; Telegram używa też dzierżaw poświadczeń Convex CI. Uruchom ręczny przepływ `QA-Lab - All Lanes` z `matrix_profile=all` i `matrix_shards=true`, gdy chcesz pełny spis transportu Matrix, mediów i E2EE równolegle.
|
||||
- Międzysystemowa walidacja instalacji i aktualizacji w czasie działania jest częścią publicznych `OpenClaw Release Checks` i `Full Release Validation`, które wywołują bezpośrednio przepływ wielokrotnego użytku `.github/workflows/openclaw-cross-os-release-checks-reusable.yml`
|
||||
- Ten podział jest celowy: utrzymuje rzeczywistą ścieżkę wydania npm krótką, deterministyczną i skupioną na artefaktach, podczas gdy wolniejsze kontrole live pozostają we własnej ścieżce, aby nie opóźniały ani nie blokowały publikacji
|
||||
- Kontrole wydania zawierające sekrety powinny być uruchamiane przez `Full Release Validation` albo z referencji przepływu `main`/release, aby logika przepływu i sekrety pozostały kontrolowane
|
||||
- `OpenClaw Release Checks` przyjmuje gałąź, tag albo pełny SHA commita, o ile rozwiązany commit jest osiągalny z gałęzi OpenClaw albo taga wydania
|
||||
- Kontrola wstępna tylko walidacyjna `OpenClaw NPM Release` przyjmuje też bieżący pełny 40-znakowy SHA commita gałęzi przepływu bez wymagania wypchniętego taga
|
||||
- Ta ścieżka SHA jest wyłącznie walidacyjna i nie może zostać wypromowana do rzeczywistej publikacji
|
||||
- W trybie SHA przepływ syntetyzuje `v<package.json version>` tylko dla kontroli metadanych pakietu; rzeczywista publikacja nadal wymaga prawdziwego taga wydania
|
||||
- Oba przepływy utrzymują rzeczywistą ścieżkę publikowania i promocji na runnerach hostowanych przez GitHub, podczas gdy niemutująca ścieżka walidacji może używać większych runnerów Blacksmith Linux
|
||||
- Ten przepływ uruchamia
|
||||
- `OpenClaw Release Checks` uruchamia także ścieżkę parytetu mock QA Lab oraz szybki profil live Matrix i ścieżkę QA Telegram przed zatwierdzeniem wydania. Ścieżki live używają środowiska `qa-live-shared`; Telegram używa także dzierżaw poświadczeń Convex CI. Uruchom ręczny workflow `QA-Lab - All Lanes` z `matrix_profile=all` i `matrix_shards=true`, gdy chcesz pełny transport Matrix, media i inwentarz E2EE równolegle.
|
||||
- Walidacja runtime instalacji i aktualizacji między systemami OS jest częścią publicznych `OpenClaw Release Checks` i `Full Release Validation`, które wywołują bezpośrednio wielokrotnego użytku workflow `.github/workflows/openclaw-cross-os-release-checks-reusable.yml`
|
||||
- Ten podział jest celowy: utrzymuje rzeczywistą ścieżkę wydania npm krótką, deterministyczną i skoncentrowaną na artefaktach, podczas gdy wolniejsze kontrole live pozostają we własnej ścieżce, aby nie wstrzymywały ani nie blokowały publikacji
|
||||
- Kontrole wydania przenoszące sekrety powinny być uruchamiane przez `Full Release Validation` albo z referencji workflow `main`/release, aby logika workflow i sekrety pozostały kontrolowane
|
||||
- `OpenClaw Release Checks` przyjmuje gałąź, tag lub pełny SHA commita, o ile rozwiązany commit jest osiągalny z gałęzi OpenClaw albo tagu wydania
|
||||
- Preflight tylko walidacyjny `OpenClaw NPM Release` akceptuje także bieżący pełny 40-znakowy SHA commita gałęzi workflow bez wymagania wypchniętego tagu
|
||||
- Ta ścieżka SHA służy wyłącznie do walidacji i nie można jej awansować do rzeczywistej publikacji
|
||||
- W trybie SHA workflow syntetyzuje `v<package.json version>` tylko na potrzeby kontroli metadanych pakietu; rzeczywista publikacja nadal wymaga prawdziwego tagu wydania
|
||||
- Oba workflow utrzymują rzeczywistą ścieżkę publikowania i promocji na runnerach hostowanych przez GitHub, podczas gdy niemutująca ścieżka walidacji może używać większych runnerów Blacksmith Linux
|
||||
- Ten workflow uruchamia
|
||||
`OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_CACHE_TEST=1 pnpm test:live:cache`
|
||||
używając sekretów przepływu `OPENAI_API_KEY` i `ANTHROPIC_API_KEY`
|
||||
- Kontrola wstępna wydania npm nie czeka już na osobną ścieżkę kontroli wydania
|
||||
używając sekretów workflow `OPENAI_API_KEY` i `ANTHROPIC_API_KEY`
|
||||
- Preflight wydania npm nie czeka już na osobną ścieżkę kontroli wydania
|
||||
- Uruchom `RELEASE_TAG=vYYYY.M.D node --import tsx scripts/openclaw-npm-release-check.ts`
|
||||
(albo odpowiadający tag beta/korekty) przed zatwierdzeniem
|
||||
- Po publikacji npm uruchom
|
||||
`node --import tsx scripts/openclaw-npm-postpublish-verify.ts YYYY.M.D`
|
||||
(albo odpowiadającą wersję beta/korekty), aby zweryfikować opublikowaną ścieżkę instalacji z rejestru w świeżym tymczasowym prefiksie
|
||||
- Po publikacji beta uruchom `OPENCLAW_NPM_TELEGRAM_PACKAGE_SPEC=openclaw@YYYY.M.D-beta.N OPENCLAW_NPM_TELEGRAM_CREDENTIAL_SOURCE=convex OPENCLAW_NPM_TELEGRAM_CREDENTIAL_ROLE=ci pnpm test:docker:npm-telegram-live`, aby zweryfikować onboarding zainstalowanego pakietu, konfigurację Telegram i rzeczywiste Telegram E2E względem opublikowanego pakietu npm przy użyciu współdzielonej puli dzierżawionych poświadczeń Telegram. Jednorazowe lokalne uruchomienia maintainerów mogą pominąć zmienne Convex i przekazać trzy poświadczenia środowiskowe `OPENCLAW_QA_TELEGRAM_*` bezpośrednio.
|
||||
- Maintainerzy mogą uruchomić tę samą kontrolę po publikacji z GitHub Actions przez ręczny przepływ `NPM Telegram Beta E2E`. Jest celowo wyłącznie ręczny i nie uruchamia się przy każdym scaleniu.
|
||||
- Automatyzacja wydań maintainerów używa teraz schematu kontrola wstępna, potem promocja:
|
||||
- rzeczywista publikacja npm musi przejść pomyślny `preflight_run_id` npm
|
||||
- rzeczywista publikacja npm musi być uruchomiona z tej samej gałęzi `main` albo `release/YYYY.M.D` co udany przebieg kontroli wstępnej
|
||||
- stabilne wydania npm domyślnie trafiają do `beta`
|
||||
- stabilna publikacja npm może jawnie celować w `latest` przez wejście przepływu
|
||||
- mutacja npm dist-tag oparta na tokenie znajduje się teraz w `openclaw/releases-private/.github/workflows/openclaw-npm-dist-tags.yml` ze względów bezpieczeństwa, ponieważ `npm dist-tag add` nadal potrzebuje `NPM_TOKEN`, podczas gdy publiczne repo utrzymuje publikowanie wyłącznie przez OIDC
|
||||
- publiczny `macOS Release` jest wyłącznie walidacyjny; gdy tag istnieje tylko na gałęzi wydania, ale przepływ jest uruchamiany z `main`, ustaw `public_release_branch=release/YYYY.M.D`
|
||||
- rzeczywista prywatna publikacja mac musi przejść pomyślny prywatny mac `preflight_run_id` i `validate_run_id`
|
||||
(albo odpowiadającą wersję beta/korekty), aby zweryfikować ścieżkę instalacji z opublikowanego rejestru w świeżym tymczasowym prefiksie
|
||||
- Po publikacji beta uruchom `OPENCLAW_NPM_TELEGRAM_PACKAGE_SPEC=openclaw@YYYY.M.D-beta.N OPENCLAW_NPM_TELEGRAM_CREDENTIAL_SOURCE=convex OPENCLAW_NPM_TELEGRAM_CREDENTIAL_ROLE=ci pnpm test:docker:npm-telegram-live`, aby zweryfikować onboarding zainstalowanego pakietu, konfigurację Telegram i rzeczywiste Telegram E2E względem opublikowanego pakietu npm z użyciem współdzielonej puli dzierżawionych poświadczeń Telegram. Lokalne jednorazowe uruchomienia maintainerów mogą pominąć zmienne Convex i przekazać trzy poświadczenia env `OPENCLAW_QA_TELEGRAM_*` bezpośrednio.
|
||||
- Aby uruchomić pełny smoke test beta po publikacji z maszyny maintainera, użyj `pnpm release:beta-smoke -- --beta betaN`. Helper uruchamia walidację npm update/fresh-target w Parallels, uruchamia `NPM Telegram Beta E2E`, odpytuje dokładny przebieg workflow, pobiera artefakt i wypisuje raport Telegram.
|
||||
- Maintainerzy mogą uruchomić tę samą kontrolę po publikacji z GitHub Actions przez ręczny workflow `NPM Telegram Beta E2E`. Jest on celowo wyłącznie ręczny i nie uruchamia się przy każdym scaleniu.
|
||||
- Automatyzacja wydań maintainerów używa teraz schematu preflight-then-promote:
|
||||
- rzeczywista publikacja npm musi przejść zakończony powodzeniem `preflight_run_id` npm
|
||||
- rzeczywista publikacja npm musi być uruchomiona z tej samej gałęzi `main` lub `release/YYYY.M.D` co zakończony powodzeniem przebieg preflight
|
||||
- stabilne wydania npm domyślnie używają `beta`
|
||||
- stabilna publikacja npm może jawnie celować w `latest` przez input workflow
|
||||
- mutacja npm dist-tag oparta na tokenie znajduje się teraz w `openclaw/releases-private/.github/workflows/openclaw-npm-dist-tags.yml` ze względów bezpieczeństwa, ponieważ `npm dist-tag add` nadal potrzebuje `NPM_TOKEN`, podczas gdy publiczne repo utrzymuje publikowanie tylko z OIDC
|
||||
- publiczny `macOS Release` służy wyłącznie do walidacji; gdy tag istnieje tylko na gałęzi wydania, ale workflow jest uruchamiany z `main`, ustaw `public_release_branch=release/YYYY.M.D`
|
||||
- rzeczywista prywatna publikacja mac musi przejść zakończone powodzeniem prywatne mac `preflight_run_id` i `validate_run_id`
|
||||
- rzeczywiste ścieżki publikowania promują przygotowane artefakty zamiast budować je ponownie
|
||||
- Dla stabilnych wydań korekcyjnych takich jak `YYYY.M.D-N` weryfikator po publikacji sprawdza też tę samą ścieżkę aktualizacji z tymczasowym prefiksem z `YYYY.M.D` do `YYYY.M.D-N`, aby korekty wydania nie mogły po cichu pozostawić starszych globalnych instalacji na bazowym stabilnym ładunku
|
||||
- Kontrola wstępna wydania npm kończy się niepowodzeniem w trybie fail-closed, chyba że tarball zawiera zarówno `dist/control-ui/index.html`, jak i niepusty ładunek `dist/control-ui/assets/`, abyśmy ponownie nie wysłali pustego panelu przeglądarkowego
|
||||
- Weryfikacja po publikacji sprawdza też, czy opublikowane punkty wejścia pluginów i metadane pakietu są obecne w zainstalowanym układzie rejestru. Wydanie, które wysyła brakujące ładunki runtime pluginów, kończy się niepowodzeniem w weryfikatorze postpublish i nie może zostać wypromowane do `latest`.
|
||||
- `pnpm test:install:smoke` wymusza też budżet npm pack `unpackedSize` na tarballu kandydata aktualizacji, dzięki czemu instalator e2e wykrywa przypadkowe rozdęcie paczki przed ścieżką publikowania wydania
|
||||
- Jeśli prace nad wydaniem dotknęły planowania CI, manifestów czasowania pluginów albo macierzy testów pluginów, przed zatwierdzeniem zregeneruj i przejrzyj należące do planera wyjścia macierzy `plugin-prerelease-extension-shard` z `.github/workflows/plugin-prerelease.yml`, aby informacje o wydaniu nie opisywały nieaktualnego układu CI
|
||||
- Gotowość stabilnego wydania macOS obejmuje też powierzchnie aktualizatora:
|
||||
- Dla stabilnych wydań korekcyjnych takich jak `YYYY.M.D-N`, weryfikator po publikacji sprawdza także tę samą ścieżkę aktualizacji w tymczasowym prefiksie z `YYYY.M.D` do `YYYY.M.D-N`, aby korekty wydania nie mogły po cichu pozostawić starszych instalacji globalnych na bazowym stabilnym payloadzie
|
||||
- Preflight wydania npm kończy się niepowodzeniem w trybie zamkniętym, chyba że tarball zawiera zarówno `dist/control-ui/index.html`, jak i niepusty payload `dist/control-ui/assets/`, abyśmy ponownie nie wysłali pustego dashboardu przeglądarkowego
|
||||
- Weryfikacja po publikacji sprawdza także, czy opublikowane entrypointy Plugin i metadane pakietu są obecne w zainstalowanym układzie rejestru. Wydanie, które wysyła brakujące payloady runtime Plugin, nie przechodzi weryfikatora po publikacji i nie może zostać promowane do `latest`.
|
||||
- `pnpm test:install:smoke` wymusza także budżet `unpackedSize` npm pack na kandydackim archiwum tarball aktualizacji, więc installer e2e wychwytuje przypadkowe rozrosty pakietu przed ścieżką publikacji wydania
|
||||
- Jeśli prace nad wydaniem dotknęły planowania CI, manifestów czasu Plugin albo macierzy testów Plugin, wygeneruj ponownie i przejrzyj należące do planera wyjścia macierzy `plugin-prerelease-extension-shard` z `.github/workflows/plugin-prerelease.yml` przed zatwierdzeniem, aby informacje o wydaniu nie opisywały przestarzałego układu CI
|
||||
- Gotowość stabilnego wydania macOS obejmuje także powierzchnie aktualizatora:
|
||||
- wydanie GitHub musi ostatecznie zawierać spakowane `.zip`, `.dmg` i `.dSYM.zip`
|
||||
- `appcast.xml` na `main` musi wskazywać na nowy stabilny zip po publikacji
|
||||
- spakowana aplikacja musi zachować niedebugowy identyfikator pakietu, niepusty URL kanału Sparkle i `CFBundleVersion` na poziomie kanonicznego minimalnego buildu Sparkle dla tej wersji wydania albo wyższym
|
||||
- `appcast.xml` na `main` musi wskazywać nowy stabilny zip po publikacji
|
||||
- spakowana aplikacja musi zachować niedebugowy identyfikator pakietu, niepusty URL kanału Sparkle oraz `CFBundleVersion` na poziomie kanonicznego dolnego progu builda Sparkle dla tej wersji wydania lub powyżej
|
||||
|
||||
## Boksy testowe wydania
|
||||
## Testboksy wydania
|
||||
|
||||
`Full Release Validation` to sposób, w jaki operatorzy uruchamiają wszystkie testy przedwydaniowe z jednego punktu wejścia. Aby uzyskać dowód przypiętego commita na szybko zmieniającej się gałęzi, użyj pomocnika, aby każdy przepływ podrzędny działał z tymczasowej gałęzi ustalonej na docelowy SHA:
|
||||
`Full Release Validation` to sposób, w jaki operatorzy uruchamiają wszystkie testy przedwydaniowe z jednego punktu wejścia. Aby uzyskać dowód przypiętego commita na szybko zmieniającej się gałęzi, użyj helpera, tak aby każdy podrzędny workflow działał z tymczasowej gałęzi ustalonej na docelowy SHA:
|
||||
|
||||
```bash
|
||||
pnpm ci:full-release --sha <full-sha>
|
||||
```
|
||||
|
||||
Pomocnik wypycha `release-ci/<sha>-...`, uruchamia `Full Release Validation` z tej gałęzi z `ref=<sha>`, weryfikuje, że każdy `headSha` przepływu podrzędnego pasuje do celu, a następnie usuwa gałąź tymczasową. Zapobiega to przypadkowemu potwierdzeniu nowszego przebiegu podrzędnego `main`.
|
||||
Helper wypycha `release-ci/<sha>-...`, uruchamia `Full Release Validation` z tej gałęzi z `ref=<sha>`, weryfikuje, że każdy podrzędny workflow `headSha` odpowiada celowi, a następnie usuwa tymczasową gałąź. Pozwala to uniknąć przypadkowego udowodnienia nowszego podrzędnego przebiegu `main`.
|
||||
|
||||
Dla walidacji gałęzi wydania albo taga uruchom ją z zaufanej referencji przepływu `main` i przekaż gałąź wydania albo tag jako `ref`:
|
||||
Dla walidacji gałęzi wydania lub tagu uruchom ją z zaufanej referencji workflow `main` i przekaż gałąź wydania lub tag jako `ref`:
|
||||
|
||||
```bash
|
||||
gh workflow run full-release-validation.yml \
|
||||
@ -186,30 +187,50 @@ gh workflow run full-release-validation.yml \
|
||||
-f evidence_package_spec=openclaw@YYYY.M.D-beta.N
|
||||
```
|
||||
|
||||
Przepływ pracy rozwiązuje docelowy ref, uruchamia ręczne `CI` z
|
||||
Przepływ pracy rozpoznaje docelową referencję, uruchamia ręcznie `CI` z
|
||||
`target_ref=<release-ref>`, uruchamia `OpenClaw Release Checks`, przygotowuje
|
||||
nadrzędny artefakt `release-package-under-test` dla kontroli dotyczących
|
||||
pakietów oraz uruchamia samodzielne pakietowe Telegram E2E, gdy
|
||||
`release_profile=full` z `rerun_group=all` albo gdy ustawiono
|
||||
`npm_telegram_package_spec`. Następnie `OpenClaw Release
|
||||
Checks` rozdziela się na smoke test instalacji, międzyplatformowe kontrole wydania, pokrycie ścieżki wydania live/E2E Docker, Package Acceptance z pakietową QA Telegram, parzystość QA Lab, live Matrix i live Telegram. Pełne uruchomienie jest akceptowalne tylko wtedy, gdy podsumowanie
|
||||
`Full Release Validation`
|
||||
pokazuje `normal_ci` i `release_checks` jako zakończone powodzeniem. W trybie full/all podrzędny `npm_telegram` także musi zakończyć się powodzeniem; poza full/all jest pomijany, chyba że podano opublikowany `npm_telegram_package_spec`. Końcowe podsumowanie weryfikatora zawiera tabele najwolniejszych zadań dla każdego uruchomienia podrzędnego, dzięki czemu menedżer wydania może zobaczyć bieżącą ścieżkę krytyczną bez pobierania logów.
|
||||
Zobacz [Pełna walidacja wydania](/pl/reference/full-release-validation), aby uzyskać pełną macierz etapów, dokładne nazwy zadań przepływu pracy, różnice między profilami stable i full, artefakty oraz uchwyty ukierunkowanych ponownych uruchomień.
|
||||
Podrzędne przepływy pracy są uruchamiane z zaufanego ref, który uruchamia `Full Release
|
||||
Validation`, zwykle `--ref main`, nawet gdy docelowy `ref` wskazuje na starszą gałąź lub tag wydania. Nie ma oddzielnego wejścia ref przepływu pracy Full Release Validation; wybierz zaufany mechanizm, wybierając ref uruchomienia przepływu pracy.
|
||||
Nie używaj `--ref main -f ref=<sha>` do dowodu dokładnego commita na ruchomym `main`;
|
||||
surowe SHA commitów nie mogą być refami uruchomienia przepływu pracy, więc użyj
|
||||
nadrzędny artefakt `release-package-under-test` dla kontroli dotyczących pakietu
|
||||
oraz uruchamia samodzielne pakietowe E2E Telegram, gdy `release_profile=full` z
|
||||
`rerun_group=all` albo gdy ustawiono `npm_telegram_package_spec`. Następnie
|
||||
`OpenClaw Release Checks` rozdziela się na install smoke, kontrole wydania
|
||||
między systemami operacyjnymi, pokrycie ścieżki wydania Docker live/E2E,
|
||||
Package Acceptance z pakietowym QA Telegram, parytet QA Lab, live Matrix oraz
|
||||
live Telegram. Pełny przebieg jest akceptowalny tylko wtedy, gdy podsumowanie
|
||||
`Full Release Validation` pokazuje `normal_ci` i `release_checks` jako udane. W
|
||||
trybie full/all proces potomny `npm_telegram` również musi zakończyć się
|
||||
sukcesem; poza full/all jest pomijany, chyba że podano opublikowane
|
||||
`npm_telegram_package_spec`. Końcowe podsumowanie weryfikatora zawiera tabele
|
||||
najwolniejszych zadań dla każdego przebiegu potomnego, dzięki czemu kierownik
|
||||
wydania może zobaczyć bieżącą ścieżkę krytyczną bez pobierania logów.
|
||||
Zobacz [Pełna walidacja wydania](/pl/reference/full-release-validation), aby
|
||||
uzyskać kompletną macierz etapów, dokładne nazwy zadań przepływu pracy, różnice
|
||||
między profilami stable i full, artefakty oraz uchwyty do ukierunkowanych
|
||||
ponownych uruchomień.
|
||||
Przepływy potomne są uruchamiane z zaufanej referencji, która uruchamia
|
||||
`Full Release Validation`, zwykle `--ref main`, nawet gdy docelowe `ref`
|
||||
wskazuje na starszą gałąź wydania lub tag. Nie ma osobnego wejścia referencji
|
||||
przepływu pracy dla Full Release Validation; wybierz zaufany harness, wybierając
|
||||
referencję przebiegu przepływu pracy. Nie używaj `--ref main -f ref=<sha>` do
|
||||
dowodu dokładnego commita na przesuwającym się `main`; surowe SHA commitów nie
|
||||
mogą być referencjami uruchomienia przepływu pracy, więc użyj
|
||||
`pnpm ci:full-release --sha <sha>`, aby utworzyć przypiętą tymczasową gałąź.
|
||||
|
||||
Użyj `release_profile`, aby wybrać zakres live/dostawcy:
|
||||
Użyj `release_profile`, aby wybrać zakres live/provider:
|
||||
|
||||
- `minimum`: najszybsza krytyczna dla wydania ścieżka live OpenAI/core i Docker
|
||||
- `stable`: minimum plus stabilne pokrycie dostawców/backendów do zatwierdzenia wydania
|
||||
- `full`: stable plus szerokie doradcze pokrycie dostawców/mediów
|
||||
- `minimum`: najszybsza, krytyczna dla wydania ścieżka OpenAI/core live i Docker
|
||||
- `stable`: minimum plus stabilne pokrycie provider/backend do zatwierdzenia wydania
|
||||
- `full`: stable plus szerokie pokrycie doradczych providerów/mediów
|
||||
|
||||
`OpenClaw Release Checks` używa zaufanego ref przepływu pracy, aby jednorazowo rozwiązać docelowy ref jako `release-package-under-test` i ponownie używa tego artefaktu zarówno w kontrolach Docker ścieżki wydania, jak i w Package Acceptance. Dzięki temu wszystkie środowiska dotyczące pakietów pracują na tych samych bajtach i unikają powtarzania buildów pakietu.
|
||||
Międzyplatformowy smoke test instalacji OpenAI używa `OPENCLAW_CROSS_OS_OPENAI_MODEL`, gdy ustawiona jest zmienna repo/org, w przeciwnym razie `openai/gpt-5.4`, ponieważ ta ścieżka dowodzi instalacji pakietu, onboardingu, uruchomienia Gateway i jednej tury agenta live, a nie benchmarkuje najwolniejszego domyślnego modelu. Szersza macierz dostawców live pozostaje miejscem dla pokrycia specyficznego dla modeli.
|
||||
`OpenClaw Release Checks` używa zaufanej referencji przepływu pracy, aby
|
||||
jednorazowo rozpoznać docelową referencję jako `release-package-under-test`, i
|
||||
ponownie używa tego artefaktu zarówno w kontrolach Docker ścieżki wydania, jak i
|
||||
w Package Acceptance. Dzięki temu wszystkie maszyny dotyczące pakietu używają
|
||||
tych samych bajtów i unika się powtarzania budowania pakietu. Cross-OS OpenAI
|
||||
install smoke używa `OPENCLAW_CROSS_OS_OPENAI_MODEL`, gdy ustawiona jest zmienna
|
||||
repo/org, w przeciwnym razie `openai/gpt-5.4`, ponieważ ta ścieżka dowodzi
|
||||
instalacji pakietu, onboardingu, startu Gateway i jednej rundy agenta live,
|
||||
zamiast benchmarkować najwolniejszy model domyślny. Szersza macierz providerów
|
||||
live pozostaje miejscem dla pokrycia specyficznego dla modeli.
|
||||
|
||||
Użyj tych wariantów zależnie od etapu wydania:
|
||||
|
||||
@ -241,26 +262,47 @@ gh workflow run full-release-validation.yml \
|
||||
-f npm_telegram_provider_mode=mock-openai
|
||||
```
|
||||
|
||||
Nie używaj pełnego parasola jako pierwszego ponownego uruchomienia po ukierunkowanej poprawce. Jeśli jedno środowisko zawiedzie, użyj nieudanego podrzędnego przepływu pracy, zadania, ścieżki Docker, profilu pakietu, dostawcy modelu lub ścieżki QA jako następnego dowodu. Uruchom pełny parasol ponownie tylko wtedy, gdy poprawka zmieniła wspólną orkiestrację wydania albo sprawiła, że wcześniejsze dowody ze wszystkich środowisk stały się nieaktualne. Końcowy weryfikator parasola ponownie sprawdza zapisane identyfikatory uruchomień podrzędnych przepływów pracy, więc po pomyślnym ponownym uruchomieniu podrzędnego przepływu pracy uruchom ponownie tylko nieudane nadrzędne zadanie `Verify full validation`.
|
||||
Nie używaj pełnego parasola jako pierwszego ponownego uruchomienia po
|
||||
ukierunkowanej poprawce. Jeśli jedna maszyna zawiedzie, użyj nieudanego
|
||||
przepływu potomnego, zadania, ścieżki Docker, profilu pakietu, providera modelu
|
||||
lub ścieżki QA jako następnego dowodu. Uruchom pełny parasol ponownie tylko
|
||||
wtedy, gdy poprawka zmieniła współdzieloną orkiestrację wydania albo sprawiła,
|
||||
że wcześniejsze dowody ze wszystkich maszyn stały się nieaktualne. Końcowy
|
||||
weryfikator parasola ponownie sprawdza zapisane identyfikatory przebiegów
|
||||
potomnych przepływów pracy, więc po pomyślnym ponownym uruchomieniu przepływu
|
||||
potomnego uruchom ponownie tylko nieudane zadanie nadrzędne
|
||||
`Verify full validation`.
|
||||
|
||||
Do ograniczonego odzyskiwania przekaż `rerun_group` do parasola. `all` to rzeczywiste uruchomienie release-candidate, `ci` uruchamia tylko normalny podrzędny CI, `plugin-prerelease`
|
||||
uruchamia tylko podrzędny plugin wyłącznie dla wydania, `release-checks` uruchamia każde środowisko wydania, a węższe grupy wydania to `install-smoke`, `cross-os`,
|
||||
`live-e2e`, `package`, `qa`, `qa-parity`, `qa-live` i `npm-telegram`.
|
||||
Ukierunkowane ponowne uruchomienia `npm-telegram` wymagają `npm_telegram_package_spec`; pełne/wszystkie uruchomienia z `release_profile=full` używają artefaktu pakietu release-checks.
|
||||
Do ograniczonego odzyskiwania przekaż `rerun_group` do parasola. `all` to
|
||||
rzeczywisty przebieg release candidate, `ci` uruchamia tylko zwykły proces
|
||||
potomny CI, `plugin-prerelease` uruchamia tylko proces potomny plugin wyłącznie
|
||||
dla wydania, `release-checks` uruchamia każdą maszynę wydania, a węższe grupy
|
||||
wydania to `install-smoke`, `cross-os`, `live-e2e`, `package`, `qa`,
|
||||
`qa-parity`, `qa-live` i `npm-telegram`. Ukierunkowane ponowne uruchomienia
|
||||
`npm-telegram` wymagają `npm_telegram_package_spec`; przebiegi full/all z
|
||||
`release_profile=full` używają artefaktu pakietu z release-checks.
|
||||
|
||||
### Vitest
|
||||
|
||||
Środowisko Vitest to ręczny podrzędny przepływ pracy `CI`. Ręczny CI celowo omija zakres zmian i wymusza normalny graf testów dla release candidate: shardy Linux Node, shardy wbudowanych pluginów, kontrakty kanałów, zgodność Node 22, `check`, `check-additional`, smoke test buildu, kontrole dokumentacji, Python skills, Windows, macOS, Android oraz Control UI i18n.
|
||||
Maszyna Vitest to ręczny przepływ potomny `CI`. Ręczne CI celowo pomija
|
||||
zakresowanie zmian i wymusza zwykły graf testów dla release candidate: shardy
|
||||
Linux Node, shardy dołączonych pluginów, kontrakty kanałów, zgodność z Node 22,
|
||||
`check`, `check-additional`, build smoke, kontrole dokumentacji, Python Skills,
|
||||
Windows, macOS, Android oraz i18n Control UI.
|
||||
|
||||
Użyj tego środowiska, aby odpowiedzieć na pytanie „czy drzewo źródłowe przeszło pełny normalny zestaw testów?”
|
||||
Nie jest to to samo co walidacja produktu ścieżki wydania. Dowody do zachowania:
|
||||
Użyj tej maszyny, aby odpowiedzieć na pytanie „czy drzewo źródeł przeszło pełny
|
||||
zwykły zestaw testów?”. To nie jest to samo co walidacja produktu w ścieżce
|
||||
wydania. Dowody do zachowania:
|
||||
|
||||
- podsumowanie `Full Release Validation` pokazujące URL uruchomionego `CI`
|
||||
- zielone uruchomienie `CI` na dokładnym docelowym SHA
|
||||
- podsumowanie `Full Release Validation` pokazujące URL uruchomionego przebiegu `CI`
|
||||
- zielony przebieg `CI` na dokładnym docelowym SHA
|
||||
- nazwy nieudanych lub wolnych shardów z zadań CI podczas badania regresji
|
||||
- artefakty czasów Vitest, takie jak `.artifacts/vitest-shard-timings.json`, gdy uruchomienie wymaga analizy wydajności
|
||||
- artefakty czasów Vitest, takie jak `.artifacts/vitest-shard-timings.json`, gdy
|
||||
przebieg wymaga analizy wydajności
|
||||
|
||||
Uruchom ręczny CI bezpośrednio tylko wtedy, gdy wydanie potrzebuje deterministycznego normalnego CI, ale nie środowisk Docker, QA Lab, live, cross-OS ani pakietowych:
|
||||
Uruchom ręczne CI bezpośrednio tylko wtedy, gdy wydanie potrzebuje
|
||||
deterministycznego zwykłego CI, ale nie maszyn Docker, QA Lab, live, cross-OS ani
|
||||
pakietowych:
|
||||
|
||||
```bash
|
||||
gh workflow run ci.yml --ref main -f target_ref=release/YYYY.M.D
|
||||
@ -268,13 +310,15 @@ gh workflow run ci.yml --ref main -f target_ref=release/YYYY.M.D
|
||||
|
||||
### Docker
|
||||
|
||||
Środowisko Docker znajduje się w `OpenClaw Release Checks` przez
|
||||
`openclaw-live-and-e2e-checks-reusable.yml` oraz przepływ pracy `install-smoke` w trybie wydania. Waliduje release candidate przez spakowane środowiska Docker zamiast wyłącznie testów na poziomie źródeł.
|
||||
Maszyna Docker znajduje się w `OpenClaw Release Checks` przez
|
||||
`openclaw-live-and-e2e-checks-reusable.yml` oraz przepływ pracy
|
||||
`install-smoke` w trybie wydania. Waliduje release candidate przez spakowane
|
||||
środowiska Docker zamiast wyłącznie testów na poziomie źródeł.
|
||||
|
||||
Pokrycie Docker wydania obejmuje:
|
||||
|
||||
- pełny smoke test instalacji z włączonym wolnym smoke testem globalnej instalacji Bun
|
||||
- przygotowanie/ponowne użycie obrazu smoke głównego Dockerfile według docelowego SHA, z zadaniami QR, root/gateway oraz installer/Bun smoke działającymi jako oddzielne shardy install-smoke
|
||||
- pełny install smoke z włączonym wolnym smoke globalnej instalacji Bun
|
||||
- przygotowanie/ponowne użycie obrazu smoke głównego Dockerfile według docelowego SHA, z zadaniami QR, root/gateway i installer/Bun smoke uruchamianymi jako osobne shardy install-smoke
|
||||
- ścieżki E2E repozytorium
|
||||
- fragmenty Docker ścieżki wydania: `core`, `package-update-openai`,
|
||||
`package-update-anthropic`, `package-update-core`, `plugins-runtime-plugins`,
|
||||
@ -284,59 +328,99 @@ Pokrycie Docker wydania obejmuje:
|
||||
`plugins-runtime-install-e`, `plugins-runtime-install-f`,
|
||||
`plugins-runtime-install-g` i `plugins-runtime-install-h`
|
||||
- pokrycie OpenWebUI wewnątrz fragmentu `plugins-runtime-services`, gdy jest wymagane
|
||||
- podzielone ścieżki instalacji/deinstalacji wbudowanych pluginów
|
||||
- podzielone ścieżki instalacji/odinstalowania dołączonych pluginów
|
||||
`bundled-plugin-install-uninstall-0` do
|
||||
`bundled-plugin-install-uninstall-23`
|
||||
- zestawy dostawców live/E2E i pokrycie modeli Docker live, gdy kontrole wydania obejmują zestawy live
|
||||
- zestawy live/E2E providerów oraz pokrycie modeli Docker live, gdy kontrole wydania
|
||||
obejmują zestawy live
|
||||
|
||||
Użyj artefaktów Docker przed ponownym uruchomieniem. Harmonogram ścieżki wydania przesyła
|
||||
`.artifacts/docker-tests/` z logami ścieżek, `summary.json`, `failures.json`,
|
||||
czasami faz, JSON planu harmonogramu oraz poleceniami ponownego uruchomienia. Do ukierunkowanego odzyskiwania użyj `docker_lanes=<lane[,lane]>` w wielokrotnego użytku przepływie pracy live/E2E zamiast ponownie uruchamiać wszystkie fragmenty wydania. Wygenerowane polecenia ponownego uruchomienia zawierają wcześniejsze `package_artifact_run_id` i przygotowane wejścia obrazu Docker, gdy są dostępne, więc nieudana ścieżka może ponownie użyć tego samego tarballa i obrazów GHCR.
|
||||
Użyj artefaktów Docker przed ponownym uruchomieniem. Harmonogram ścieżki wydania
|
||||
przesyła `.artifacts/docker-tests/` z logami ścieżek, `summary.json`,
|
||||
`failures.json`, czasami faz, JSON planu harmonogramu oraz poleceniami ponownego
|
||||
uruchomienia. Do ukierunkowanego odzyskiwania użyj `docker_lanes=<lane[,lane]>`
|
||||
w wielokrotnego użytku przepływie live/E2E zamiast ponownie uruchamiać wszystkie
|
||||
fragmenty wydania. Wygenerowane polecenia ponownego uruchomienia obejmują
|
||||
wcześniejsze `package_artifact_run_id` i przygotowane wejścia obrazu Docker,
|
||||
gdy są dostępne, aby nieudana ścieżka mogła ponownie użyć tego samego archiwum
|
||||
tarball i obrazów GHCR.
|
||||
|
||||
### QA Lab
|
||||
|
||||
Środowisko QA Lab jest również częścią `OpenClaw Release Checks`. Jest to bramka wydania dla zachowania agentowego i poziomu kanału, oddzielna od Vitest oraz mechaniki pakietów Docker.
|
||||
Maszyna QA Lab jest również częścią `OpenClaw Release Checks`. To bramka wydania
|
||||
dla zachowania agentowego i na poziomie kanałów, osobna od mechaniki pakietów
|
||||
Vitest i Docker.
|
||||
|
||||
Pokrycie QA Lab wydania obejmuje:
|
||||
|
||||
- ścieżkę parzystości mock porównującą ścieżkę kandydata OpenAI z baseline Opus 4.6 przy użyciu pakietu parzystości agentowej
|
||||
- szybki profil QA live Matrix używający środowiska `qa-live-shared`
|
||||
- ścieżkę QA live Telegram używającą dzierżaw poświadczeń Convex CI
|
||||
- `pnpm qa:otel:smoke`, gdy telemetria wydania potrzebuje wyraźnego lokalnego dowodu
|
||||
- ścieżkę parytetu mock porównującą ścieżkę kandydata OpenAI z baseline Opus 4.6
|
||||
przy użyciu agentowego pakietu parytetu
|
||||
- szybki profil QA live Matrix z użyciem środowiska `qa-live-shared`
|
||||
- ścieżkę QA live Telegram z użyciem dzierżaw poświadczeń Convex CI
|
||||
- `pnpm qa:otel:smoke`, gdy telemetria wydania wymaga jawnego lokalnego dowodu
|
||||
|
||||
Użyj tego środowiska, aby odpowiedzieć na pytanie „czy wydanie zachowuje się poprawnie w scenariuszach QA i przepływach kanałów live?” Zachowaj URL-e artefaktów dla ścieżek parzystości, Matrix i Telegram podczas zatwierdzania wydania. Pełne pokrycie Matrix pozostaje dostępne jako ręczne shardowane uruchomienie QA-Lab, a nie domyślna ścieżka krytyczna dla wydania.
|
||||
Użyj tej maszyny, aby odpowiedzieć na pytanie „czy wydanie zachowuje się
|
||||
poprawnie w scenariuszach QA i przepływach kanałów live?”. Zachowaj URL-e
|
||||
artefaktów dla ścieżek parytetu, Matrix i Telegram podczas zatwierdzania
|
||||
wydania. Pełne pokrycie Matrix pozostaje dostępne jako ręczny shardowany
|
||||
przebieg QA-Lab, a nie domyślna ścieżka krytyczna dla wydania.
|
||||
|
||||
### Pakiet
|
||||
|
||||
Środowisko Package jest bramką produktu instalowalnego. Jest wspierane przez
|
||||
Maszyna Package to bramka instalowalnego produktu. Jest obsługiwana przez
|
||||
`Package Acceptance` i resolver
|
||||
`scripts/resolve-openclaw-package-candidate.mjs`. Resolver normalizuje kandydata do tarballa `package-under-test` używanego przez Docker E2E, waliduje inwentarz pakietu, zapisuje wersję pakietu i SHA-256 oraz oddziela ref mechanizmu przepływu pracy od ref źródła pakietu.
|
||||
`scripts/resolve-openclaw-package-candidate.mjs`. Resolver normalizuje kandydata
|
||||
do archiwum tarball `package-under-test` używanego przez Docker E2E, waliduje
|
||||
inwentarz pakietu, zapisuje wersję pakietu i SHA-256 oraz utrzymuje referencję
|
||||
harnessu przepływu pracy oddzielnie od referencji źródła pakietu.
|
||||
|
||||
Obsługiwane źródła kandydatów:
|
||||
|
||||
- `source=npm`: `openclaw@beta`, `openclaw@latest` albo dokładna wersja wydania OpenClaw
|
||||
- `source=ref`: spakuj zaufaną gałąź `package_ref`, tag albo pełny SHA commita z wybranym mechanizmem `workflow_ref`
|
||||
- `source=npm`: `openclaw@beta`, `openclaw@latest` lub dokładna wersja wydania OpenClaw
|
||||
- `source=ref`: spakuj zaufaną gałąź `package_ref`, tag lub pełny SHA commita
|
||||
z wybranym harnessem `workflow_ref`
|
||||
- `source=url`: pobierz HTTPS `.tgz` z wymaganym `package_sha256`
|
||||
- `source=artifact`: użyj ponownie `.tgz` przesłanego przez inne uruchomienie GitHub Actions
|
||||
- `source=artifact`: ponownie użyj `.tgz` przesłanego przez inny przebieg GitHub Actions
|
||||
|
||||
`OpenClaw Release Checks` uruchamia Package Acceptance z `source=artifact`, przygotowanym artefaktem pakietu wydania, `suite_profile=custom`,
|
||||
`OpenClaw Release Checks` uruchamia Package Acceptance z `source=artifact`,
|
||||
przygotowanym artefaktem pakietu wydania, `suite_profile=custom`,
|
||||
`docker_lanes=doctor-switch update-channel-switch upgrade-survivor published-upgrade-survivor plugins-offline plugin-update`,
|
||||
`published_upgrade_survivor_baselines=all-since-2026.4.23`,
|
||||
`published_upgrade_survivor_scenarios=reported-issues` i
|
||||
`telegram_mode=mock-openai`. Package Acceptance utrzymuje migrację, aktualizację, czyszczenie przestarzałych zależności pluginów, offline fixtures pluginów, aktualizację pluginów oraz pakietową QA Telegram wobec tego samego rozwiązanego tarballa. Macierz upgrade obejmuje każdy stabilny baseline opublikowany w npm od `2026.4.23` do `latest`; użyj
|
||||
Package Acceptance z `source=npm` dla już wydanego kandydata albo
|
||||
`source=ref`/`source=artifact` dla lokalnego tarballa npm opartego na SHA przed publikacją. Jest to natywne dla GitHub
|
||||
zastępstwo dla większości pokrycia pakietu/aktualizacji, które wcześniej wymagało Parallels. Międzyplatformowe kontrole wydania nadal mają znaczenie dla onboardingu, instalatora i zachowania platformowego specyficznego dla systemu operacyjnego, ale walidacja produktu pakietu/aktualizacji powinna preferować Package Acceptance.
|
||||
`published_upgrade_survivor_scenarios=reported-issues` oraz
|
||||
`telegram_mode=mock-openai`. Package Acceptance utrzymuje migrację,
|
||||
aktualizację, czyszczenie zależności nieaktualnych pluginów, offline fixtures
|
||||
pluginów, aktualizację pluginów oraz pakietowe QA Telegram względem tego samego
|
||||
rozpoznanego archiwum tarball. Macierz aktualizacji obejmuje każdy stabilny
|
||||
baseline opublikowany w npm od `2026.4.23` do `latest`; użyj Package Acceptance z
|
||||
`source=npm` dla już wysłanego kandydata albo `source=ref`/`source=artifact` dla
|
||||
lokalnego archiwum tarball npm opartego na SHA przed publikacją. To natywne dla
|
||||
GitHub zastępstwo większości pokrycia pakietów/aktualizacji, które wcześniej
|
||||
wymagało Parallels. Kontrole wydania cross-OS nadal są ważne dla
|
||||
specyficznego dla systemu onboardingu, instalatora i zachowania platformy, ale
|
||||
walidacja produktu dotycząca pakietu/aktualizacji powinna preferować Package
|
||||
Acceptance.
|
||||
|
||||
Kanoniczna lista kontrolna dla walidacji aktualizacji i pluginów to
|
||||
[Testowanie aktualizacji i pluginów](/pl/help/testing-updates-plugins). Użyj jej, gdy decydujesz, która lokalna ścieżka, Docker, Package Acceptance albo release-check potwierdza zmianę instalacji/aktualizacji pluginu, czyszczenia przez doctor albo migracji opublikowanego pakietu.
|
||||
Wyczerpująca migracja aktualizacji opublikowanych pakietów z każdego stabilnego pakietu `2026.4.23+` to oddzielny ręczny przepływ pracy `Update Migration`, a nie część Full Release CI.
|
||||
Kanoniczna lista kontrolna walidacji aktualizacji i pluginów to
|
||||
[Testowanie aktualizacji i pluginów](/pl/help/testing-updates-plugins). Użyj jej
|
||||
podczas decydowania, która ścieżka lokalna, Docker, Package Acceptance lub
|
||||
release-check dowodzi zmiany instalacji/aktualizacji pluginu, czyszczenia przez
|
||||
doctor albo migracji opublikowanego pakietu. Wyczerpująca migracja
|
||||
opublikowanych aktualizacji z każdego stabilnego pakietu `2026.4.23+` to osobny
|
||||
ręczny przepływ pracy `Update Migration`, a nie część Full Release CI.
|
||||
|
||||
Łagodność legacy package-acceptance jest celowo ograniczona czasowo. Pakiety do
|
||||
`2026.4.25` mogą używać ścieżki zgodności dla luk metadanych już opublikowanych w npm: prywatnych wpisów inwentarza QA brakujących w tarballu, brakującego
|
||||
`gateway install --wrapper`, brakujących plików patch w fixture git pochodzącej z tarballa, brakującego utrwalonego `update.channel`, legacy lokalizacji rekordów instalacji pluginów, brakującego utrwalenia rekordów instalacji marketplace oraz migracji metadanych konfiguracji podczas `plugins update`. Opublikowany pakiet `2026.4.26` może ostrzegać o lokalnych plikach znacznika metadanych buildu, które zostały już wydane. Późniejsze pakiety muszą spełniać nowoczesne kontrakty pakietów; te same luki powodują niepowodzenie walidacji wydania.
|
||||
Tolerancja starszego package-acceptance jest celowo ograniczona czasowo. Pakiety
|
||||
do `2026.4.25` włącznie mogą używać ścieżki zgodności dla luk w metadanych już
|
||||
opublikowanych w npm: prywatnych wpisów inwentarza QA brakujących w archiwum
|
||||
tarball, brakującego `gateway install --wrapper`, brakujących plików poprawek w
|
||||
fixture git wyprowadzonym z tarballa, brakującego utrwalonego `update.channel`,
|
||||
starszych lokalizacji rekordów instalacji pluginów, brakującej trwałości
|
||||
rekordów instalacji marketplace oraz migracji metadanych konfiguracji podczas
|
||||
`plugins update`. Opublikowany pakiet `2026.4.26` może ostrzegać o lokalnych
|
||||
plikach znaczników metadanych builda, które już zostały wysłane. Późniejsze
|
||||
pakiety muszą spełniać nowoczesne kontrakty pakietów; te same luki powodują
|
||||
niepowodzenie walidacji wydania.
|
||||
|
||||
Użyj szerszych profili Package Acceptance, gdy pytanie o wydanie dotyczy rzeczywistego instalowalnego pakietu:
|
||||
Używaj szerszych profili Package Acceptance, gdy pytanie o wydanie dotyczy
|
||||
rzeczywistego instalowalnego pakietu:
|
||||
|
||||
```bash
|
||||
gh workflow run package-acceptance.yml \
|
||||
@ -350,32 +434,32 @@ gh workflow run package-acceptance.yml \
|
||||
|
||||
Typowe profile pakietów:
|
||||
|
||||
- `smoke`: szybkie ścieżki instalacji pakietu/kanału/agenta, sieci Gateway oraz
|
||||
ponownego wczytania konfiguracji
|
||||
- `package`: kontrakty instalacji/aktualizacji/pakietu Plugin bez aktywnego ClawHub; to jest domyślna
|
||||
ścieżka sprawdzania wydania
|
||||
- `product`: `package` plus kanały MCP, czyszczenie Cron/podagentów, wyszukiwanie
|
||||
internetowe OpenAI oraz OpenWebUI
|
||||
- `smoke`: szybkie ścieżki instalacji pakietu/kanału/agenta, sieci Gateway i ponownego
|
||||
ładowania konfiguracji
|
||||
- `package`: kontrakty instalacji/aktualizacji/pakietu Plugin bez aktywnego ClawHub; jest to domyślna
|
||||
opcja sprawdzania wydania
|
||||
- `product`: `package` plus kanały MCP, czyszczenie cron/subagenta, wyszukiwanie w sieci
|
||||
OpenAI i OpenWebUI
|
||||
- `full`: fragmenty ścieżki wydania Docker z OpenWebUI
|
||||
- `custom`: dokładna lista `docker_lanes` do ukierunkowanych ponownych uruchomień
|
||||
|
||||
Aby uzyskać dowód Telegram dla kandydata pakietu, włącz `telegram_mode=mock-openai` lub
|
||||
`telegram_mode=live-frontier` w Package Acceptance. Workflow przekazuje
|
||||
rozwiązany tarball `package-under-test` do ścieżki Telegram; samodzielny
|
||||
workflow Telegram nadal przyjmuje opublikowaną specyfikację npm do kontroli po publikacji.
|
||||
workflow Telegram nadal akceptuje opublikowaną specyfikację npm na potrzeby kontroli po publikacji.
|
||||
|
||||
## Automatyzacja publikacji wydania
|
||||
|
||||
`OpenClaw Release Publish` to normalny modyfikujący punkt wejścia publikacji. Orkiestruje
|
||||
workflowy zaufanego wydawcy w kolejności wymaganej przez wydanie:
|
||||
`OpenClaw Release Publish` to normalny punkt wejścia do publikacji mutującej. Orkiestruje
|
||||
workflowy z zaufanym wydawcą w kolejności wymaganej przez wydanie:
|
||||
|
||||
1. Pobierz tag wydania i rozwiąż jego SHA commita.
|
||||
2. Zweryfikuj, że tag jest osiągalny z `main` lub `release/*`.
|
||||
2. Sprawdź, czy tag jest osiągalny z `main` lub `release/*`.
|
||||
3. Uruchom `pnpm plugins:sync:check`.
|
||||
4. Wywołaj `Plugin NPM Release` z `publish_scope=all-publishable` oraz
|
||||
4. Uruchom `Plugin NPM Release` z `publish_scope=all-publishable` i
|
||||
`ref=<release-sha>`.
|
||||
5. Wywołaj `Plugin ClawHub Release` z tym samym zakresem i SHA.
|
||||
6. Wywołaj `OpenClaw NPM Release` z tagiem wydania, dist-tagiem npm oraz
|
||||
5. Uruchom `Plugin ClawHub Release` z tym samym zakresem i SHA.
|
||||
6. Uruchom `OpenClaw NPM Release` z tagiem wydania, npm dist-tag i
|
||||
zapisanym `preflight_run_id`.
|
||||
|
||||
Przykład publikacji beta:
|
||||
@ -388,7 +472,7 @@ gh workflow run openclaw-release-publish.yml \
|
||||
-f npm_dist_tag=beta
|
||||
```
|
||||
|
||||
Publikacja stabilna do domyślnego dist-tagu beta:
|
||||
Publikacja stabilna do domyślnego beta dist-tag:
|
||||
|
||||
```bash
|
||||
gh workflow run openclaw-release-publish.yml \
|
||||
@ -398,7 +482,7 @@ gh workflow run openclaw-release-publish.yml \
|
||||
-f npm_dist_tag=beta
|
||||
```
|
||||
|
||||
Stabilna promocja bezpośrednio do `latest` jest jawna:
|
||||
Bezpośrednia promocja stabilna do `latest` jest jawna:
|
||||
|
||||
```bash
|
||||
gh workflow run openclaw-release-publish.yml \
|
||||
@ -409,25 +493,25 @@ gh workflow run openclaw-release-publish.yml \
|
||||
```
|
||||
|
||||
Używaj workflowów niższego poziomu `Plugin NPM Release` i `Plugin ClawHub Release`
|
||||
tylko do ukierunkowanej naprawy lub ponownej publikacji. Przy naprawie wybranego Plugin przekaż
|
||||
`plugin_publish_scope=selected` oraz `plugins=@openclaw/name` do
|
||||
`OpenClaw Release Publish`, albo wywołaj workflow podrzędny bezpośrednio, gdy
|
||||
tylko do ukierunkowanej naprawy lub ponownej publikacji. W przypadku naprawy wybranego pluginu przekaż
|
||||
`plugin_publish_scope=selected` i `plugins=@openclaw/name` do
|
||||
`OpenClaw Release Publish`, albo uruchom workflow podrzędny bezpośrednio, gdy
|
||||
pakiet OpenClaw nie może zostać opublikowany.
|
||||
|
||||
## Dane wejściowe workflow NPM
|
||||
## Dane wejściowe workflow npm
|
||||
|
||||
`OpenClaw NPM Release` przyjmuje te dane wejściowe kontrolowane przez operatora:
|
||||
`OpenClaw NPM Release` akceptuje te dane wejściowe kontrolowane przez operatora:
|
||||
|
||||
- `tag`: wymagany tag wydania, taki jak `v2026.4.2`, `v2026.4.2-1` lub
|
||||
`v2026.4.2-beta.1`; gdy `preflight_only=true`, może to być także bieżący
|
||||
pełny 40-znakowy SHA commita gałęzi workflow do preflightu wyłącznie walidacyjnego
|
||||
- `preflight_only`: `true` tylko dla walidacji/builda/pakietu, `false` dla
|
||||
- `preflight_only`: `true` tylko dla walidacji/kompilacji/pakietu, `false` dla
|
||||
rzeczywistej ścieżki publikacji
|
||||
- `preflight_run_id`: wymagane w rzeczywistej ścieżce publikacji, aby workflow ponownie użył
|
||||
przygotowanego tarballa z udanego przebiegu preflight
|
||||
- `npm_dist_tag`: docelowy tag npm dla ścieżki publikacji; domyślnie `beta`
|
||||
|
||||
`OpenClaw Release Publish` przyjmuje te dane wejściowe kontrolowane przez operatora:
|
||||
`OpenClaw Release Publish` akceptuje te dane wejściowe kontrolowane przez operatora:
|
||||
|
||||
- `tag`: wymagany tag wydania; musi już istnieć
|
||||
- `preflight_run_id`: identyfikator udanego przebiegu preflight `OpenClaw NPM Release`;
|
||||
@ -438,23 +522,23 @@ pakiet OpenClaw nie może zostać opublikowany.
|
||||
- `plugins`: rozdzielone przecinkami nazwy pakietów `@openclaw/*`, gdy
|
||||
`plugin_publish_scope=selected`
|
||||
- `publish_openclaw_npm`: domyślnie `true`; ustaw `false` tylko wtedy, gdy używasz
|
||||
workflow jako orkiestratora naprawy wyłącznie Plugin
|
||||
workflow jako orkiestratora napraw wyłącznie dla pluginów
|
||||
|
||||
`OpenClaw Release Checks` przyjmuje te dane wejściowe kontrolowane przez operatora:
|
||||
`OpenClaw Release Checks` akceptuje te dane wejściowe kontrolowane przez operatora:
|
||||
|
||||
- `ref`: gałąź, tag lub pełny SHA commita do walidacji. Kontrole wymagające sekretów
|
||||
- `ref`: gałąź, tag lub pełny SHA commita do walidacji. Kontrole korzystające z sekretów
|
||||
wymagają, aby rozwiązany commit był osiągalny z gałęzi OpenClaw lub
|
||||
taga wydania.
|
||||
tagu wydania.
|
||||
|
||||
Zasady:
|
||||
|
||||
- Tagi stabilne i korekcyjne mogą publikować do `beta` albo `latest`
|
||||
- Tagi przedwydaniowe beta mogą publikować wyłącznie do `beta`
|
||||
- Dla `OpenClaw NPM Release` pełny SHA commita jest dozwolony tylko wtedy, gdy
|
||||
- Tagi stabilne i korygujące mogą publikować do `beta` albo `latest`
|
||||
- Tagi przedwydania beta mogą publikować tylko do `beta`
|
||||
- W `OpenClaw NPM Release` pełny SHA commita jest dozwolony tylko wtedy, gdy
|
||||
`preflight_only=true`
|
||||
- `OpenClaw Release Checks` oraz `Full Release Validation` zawsze są
|
||||
- `OpenClaw Release Checks` i `Full Release Validation` są zawsze
|
||||
wyłącznie walidacyjne
|
||||
- Rzeczywista ścieżka publikacji musi używać tego samego `npm_dist_tag`, którego użyto podczas preflightu;
|
||||
- Rzeczywista ścieżka publikacji musi używać tego samego `npm_dist_tag`, którego użyto podczas preflight;
|
||||
workflow weryfikuje te metadane przed kontynuowaniem publikacji
|
||||
|
||||
## Sekwencja stabilnego wydania npm
|
||||
@ -462,39 +546,39 @@ Zasady:
|
||||
Podczas przygotowywania stabilnego wydania npm:
|
||||
|
||||
1. Uruchom `OpenClaw NPM Release` z `preflight_only=true`
|
||||
- Zanim tag będzie istnieć, możesz użyć bieżącego pełnego SHA commita gałęzi workflow
|
||||
do walidacyjnego próbnego uruchomienia workflow preflight
|
||||
2. Wybierz `npm_dist_tag=beta` dla normalnego przepływu najpierw do beta albo `latest` tylko
|
||||
- Zanim tag istnieje, możesz użyć bieżącego pełnego SHA commita gałęzi workflow
|
||||
do wyłącznie walidacyjnego próbnego uruchomienia workflow preflight
|
||||
2. Wybierz `npm_dist_tag=beta` dla normalnego przepływu najpierw beta albo `latest` tylko
|
||||
wtedy, gdy celowo chcesz bezpośredniej stabilnej publikacji
|
||||
3. Uruchom `Full Release Validation` na gałęzi wydania, tagu wydania lub pełnym
|
||||
SHA commita, gdy chcesz uzyskać z jednego ręcznego workflow normalne CI oraz pokrycie aktywnej pamięci podręcznej promptów, Docker, QA Lab,
|
||||
Matrix i Telegram
|
||||
SHA commita, gdy chcesz uzyskać normalne CI oraz pokrycie aktywnego prompt cache, Docker, QA Lab,
|
||||
Matrix i Telegram z jednego ręcznego workflow
|
||||
4. Jeśli celowo potrzebujesz tylko deterministycznego normalnego grafu testów, uruchom
|
||||
ręczny workflow `CI` na refie wydania
|
||||
5. Zapisz udane `preflight_run_id`
|
||||
ręczny workflow `CI` na ref wydania
|
||||
5. Zapisz udany `preflight_run_id`
|
||||
6. Uruchom `OpenClaw Release Publish` z tym samym `tag`, tym samym `npm_dist_tag`
|
||||
oraz zapisanym `preflight_run_id`; publikuje zewnętrzne pluginy do npm
|
||||
i zapisanym `preflight_run_id`; publikuje zewnętrzne pluginy do npm
|
||||
i ClawHub przed promowaniem pakietu npm OpenClaw
|
||||
7. Jeśli wydanie trafiło do `beta`, użyj prywatnego workflow
|
||||
`openclaw/releases-private/.github/workflows/openclaw-npm-dist-tags.yml`,
|
||||
aby promować tę stabilną wersję z `beta` do `latest`
|
||||
8. Jeśli wydanie celowo opublikowano bezpośrednio do `latest`, a `beta`
|
||||
powinien od razu wskazywać ten sam stabilny build, użyj tego samego prywatnego
|
||||
8. Jeśli wydanie zostało celowo opublikowane bezpośrednio do `latest`, a `beta`
|
||||
powinna natychmiast wskazywać tę samą stabilną kompilację, użyj tego samego prywatnego
|
||||
workflow, aby skierować oba dist-tagi na stabilną wersję, albo pozwól jego zaplanowanej
|
||||
samonaprawczej synchronizacji później przesunąć `beta`
|
||||
samonaprawiającej synchronizacji przenieść `beta` później
|
||||
|
||||
Mutacja dist-tagu znajduje się w prywatnym repo ze względów bezpieczeństwa, ponieważ nadal
|
||||
wymaga `NPM_TOKEN`, podczas gdy publiczne repo utrzymuje publikację wyłącznie przez OIDC.
|
||||
Mutacja dist-tag znajduje się w prywatnym repozytorium ze względów bezpieczeństwa, ponieważ nadal
|
||||
wymaga `NPM_TOKEN`, podczas gdy publiczne repozytorium zachowuje publikację wyłącznie przez OIDC.
|
||||
|
||||
Dzięki temu zarówno bezpośrednia ścieżka publikacji, jak i ścieżka promocji najpierw do beta
|
||||
pozostają udokumentowane i widoczne dla operatorów.
|
||||
Dzięki temu bezpośrednia ścieżka publikacji i ścieżka promocji najpierw beta są
|
||||
udokumentowane i widoczne dla operatora.
|
||||
|
||||
Jeśli maintainer musi wrócić do lokalnego uwierzytelniania npm, uruchamiaj wszelkie polecenia 1Password
|
||||
CLI (`op`) tylko w dedykowanej sesji tmux. Nie wywołuj `op`
|
||||
bezpośrednio z głównej powłoki agenta; trzymanie go w tmux sprawia, że prompty,
|
||||
Jeśli maintainer musi awaryjnie użyć lokalnego uwierzytelniania npm, uruchamiaj polecenia
|
||||
CLI 1Password (`op`) tylko w dedykowanej sesji tmux. Nie wywołuj `op`
|
||||
bezpośrednio z głównej powłoki agenta; trzymanie go w tmux sprawia, że monity,
|
||||
alerty i obsługa OTP są obserwowalne oraz zapobiega powtarzającym się alertom hosta.
|
||||
|
||||
## Publiczne odniesienia
|
||||
## Publiczne odnośniki
|
||||
|
||||
- [`.github/workflows/full-release-validation.yml`](https://github.com/openclaw/openclaw/blob/main/.github/workflows/full-release-validation.yml)
|
||||
- [`.github/workflows/package-acceptance.yml`](https://github.com/openclaw/openclaw/blob/main/.github/workflows/package-acceptance.yml)
|
||||
@ -506,10 +590,10 @@ alerty i obsługa OTP są obserwowalne oraz zapobiega powtarzającym się alerto
|
||||
- [`scripts/package-mac-dist.sh`](https://github.com/openclaw/openclaw/blob/main/scripts/package-mac-dist.sh)
|
||||
- [`scripts/make_appcast.sh`](https://github.com/openclaw/openclaw/blob/main/scripts/make_appcast.sh)
|
||||
|
||||
Maintainerzy używają prywatnej dokumentacji wydania w
|
||||
Maintainerzy używają prywatnej dokumentacji wydań w
|
||||
[`openclaw/maintainers/release/README.md`](https://github.com/openclaw/maintainers/blob/main/release/README.md)
|
||||
jako właściwej instrukcji operacyjnej.
|
||||
jako właściwej procedury operacyjnej.
|
||||
|
||||
## Powiązane
|
||||
|
||||
- [Kanały wydania](/pl/install/development-channels)
|
||||
- [Kanały wydań](/pl/install/development-channels)
|
||||
|
||||
@ -1,69 +1,69 @@
|
||||
---
|
||||
read_when:
|
||||
- Chcesz zapewnić wielowarstwową ochronę przed atakami SSRF i DNS rebinding
|
||||
- Konfigurowanie zewnętrznego przekazującego serwera proxy dla ruchu środowiska wykonawczego OpenClaw
|
||||
summary: Jak kierować ruch HTTP i WebSocket środowiska uruchomieniowego OpenClaw przez zarządzany przez operatora filtrujący serwer proxy
|
||||
title: Proxy sieciowe
|
||||
- Potrzebujesz wielowarstwowej ochrony przed atakami SSRF i atakami polegającymi na ponownym wiązaniu DNS
|
||||
- Konfigurowanie zewnętrznego serwera proxy typu forward dla ruchu środowiska uruchomieniowego OpenClaw
|
||||
summary: Jak kierować ruch HTTP i WebSocket środowiska uruchomieniowego OpenClaw przez filtrujący serwer proxy zarządzany przez operatora
|
||||
title: Proxy sieciowy
|
||||
x-i18n:
|
||||
generated_at: "2026-05-04T02:26:22Z"
|
||||
generated_at: "2026-05-04T07:06:31Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: cd5594324e8c6b7da51d903e98fda0feacb8970e0b15d980f7a249d6641461c9
|
||||
source_hash: fc7140c5ced0e7454a6f85d1ea8f3256bbd28cc0cb42eeafe8e5e6439b90e3f0
|
||||
source_path: security/network-proxy.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
# Sieciowy serwer proxy
|
||||
# Proxy sieciowy
|
||||
|
||||
OpenClaw może kierować ruch HTTP i WebSocket środowiska wykonawczego przez zarządzany przez operatora serwer proxy ruchu wychodzącego. Jest to opcjonalna obrona w głąb dla wdrożeń, które potrzebują centralnej kontroli ruchu wychodzącego, silniejszej ochrony przed SSRF i lepszej audytowalności sieci.
|
||||
OpenClaw może kierować ruch HTTP i WebSocket środowiska uruchomieniowego przez zarządzany przez operatora proxy przekazujący. To opcjonalna, warstwowa ochrona dla wdrożeń, które potrzebują centralnej kontroli ruchu wychodzącego, silniejszej ochrony przed SSRF i lepszej audytowalności sieci.
|
||||
|
||||
OpenClaw nie dostarcza, nie pobiera, nie uruchamia, nie konfiguruje ani nie certyfikuje serwera proxy. Uruchamiasz technologię proxy pasującą do Twojego środowiska, a OpenClaw kieruje przez nią zwykłe lokalne dla procesu klienty HTTP i WebSocket.
|
||||
OpenClaw nie dostarcza, nie pobiera, nie uruchamia, nie konfiguruje ani nie certyfikuje proxy. Uruchamiasz technologię proxy pasującą do swojego środowiska, a OpenClaw kieruje przez nią zwykłe lokalne dla procesu klienty HTTP i WebSocket.
|
||||
|
||||
## Dlaczego używać serwera proxy?
|
||||
## Dlaczego używać proxy?
|
||||
|
||||
Serwer proxy daje operatorom jeden punkt kontroli sieci dla wychodzącego ruchu HTTP i WebSocket. Może to być przydatne nawet poza utwardzaniem przeciw SSRF:
|
||||
Proxy daje operatorom jeden punkt kontroli sieciowej dla wychodzącego ruchu HTTP i WebSocket. Może to być przydatne nawet poza wzmacnianiem ochrony przed SSRF:
|
||||
|
||||
- Centralna polityka: utrzymuj jedną politykę ruchu wychodzącego zamiast polegać na tym, że każde miejsce wywołania HTTP w aplikacji poprawnie zastosuje reguły sieciowe.
|
||||
- Sprawdzanie przy połączeniu: oceniaj miejsce docelowe po rozwiązaniu DNS i bezpośrednio przed otwarciem przez serwer proxy połączenia z upstreamem.
|
||||
- Obrona przed DNS rebinding: zmniejsz odstęp między sprawdzeniem DNS na poziomie aplikacji a rzeczywistym połączeniem wychodzącym.
|
||||
- Szersze pokrycie JavaScript: kieruj zwykłe `fetch`, `node:http`, `node:https`, WebSocket, axios, got, node-fetch i podobne klienty tą samą ścieżką.
|
||||
- Audytowalność: rejestruj dozwolone i odrzucone miejsca docelowe na granicy ruchu wychodzącego.
|
||||
- Kontrola operacyjna: egzekwuj reguły miejsc docelowych, segmentację sieci, limity szybkości lub listy dozwolone ruchu wychodzącego bez przebudowy OpenClaw.
|
||||
- Kontrole w chwili połączenia: oceniaj miejsce docelowe po rozwiązaniu DNS i bezpośrednio przed otwarciem przez proxy połączenia nadrzędnego.
|
||||
- Obrona przed DNS rebinding: zmniejsz lukę między sprawdzeniem DNS na poziomie aplikacji a faktycznym połączeniem wychodzącym.
|
||||
- Szersze pokrycie JavaScript: kieruj zwykłe klienty `fetch`, `node:http`, `node:https`, WebSocket, axios, got, node-fetch i podobne tą samą ścieżką.
|
||||
- Audytowalność: rejestruj dozwolone i zablokowane miejsca docelowe na granicy ruchu wychodzącego.
|
||||
- Kontrola operacyjna: wymuszaj reguły miejsc docelowych, segmentację sieci, limity szybkości lub listy dozwolonych adresów wychodzących bez przebudowywania OpenClaw.
|
||||
|
||||
Kierowanie przez serwer proxy jest zabezpieczeniem na poziomie procesu dla zwykłego ruchu wychodzącego HTTP i WebSocket. Daje operatorom ścieżkę fail-closed do kierowania obsługiwanych klientów HTTP JavaScript przez własny filtrujący serwer proxy, ale nie jest piaskownicą sieciową na poziomie systemu operacyjnego i nie sprawia, że OpenClaw certyfikuje politykę miejsc docelowych serwera proxy.
|
||||
Trasowanie przez proxy jest zabezpieczeniem na poziomie procesu dla zwykłego wychodzącego ruchu HTTP i WebSocket. Daje operatorom ścieżkę zamkniętą w razie awarii do kierowania obsługiwanych klientów HTTP JavaScript przez własny filtrujący proxy, ale nie jest piaskownicą sieciową na poziomie systemu operacyjnego i nie sprawia, że OpenClaw certyfikuje politykę miejsc docelowych proxy.
|
||||
|
||||
## Jak OpenClaw kieruje ruch
|
||||
## Jak OpenClaw trasuje ruch
|
||||
|
||||
Gdy `proxy.enabled=true` i skonfigurowano URL serwera proxy, chronione procesy środowiska wykonawczego, takie jak `openclaw gateway run`, `openclaw node run` i `openclaw agent --local`, kierują zwykły ruch wychodzący HTTP i WebSocket przez skonfigurowany serwer proxy:
|
||||
Gdy `proxy.enabled=true` i skonfigurowano URL proxy, chronione procesy środowiska uruchomieniowego, takie jak `openclaw gateway run`, `openclaw node run` i `openclaw agent --local`, kierują zwykły wychodzący ruch HTTP i WebSocket przez skonfigurowany proxy:
|
||||
|
||||
```text
|
||||
Proces OpenClaw
|
||||
fetch -> zarządzany przez operatora filtrujący serwer proxy -> publiczny internet
|
||||
node:http and https -> zarządzany przez operatora filtrujący serwer proxy -> publiczny internet
|
||||
Klienty WebSocket -> zarządzany przez operatora filtrujący serwer proxy -> publiczny internet
|
||||
OpenClaw process
|
||||
fetch -> operator-managed filtering proxy -> public internet
|
||||
node:http and https -> operator-managed filtering proxy -> public internet
|
||||
WebSocket clients -> operator-managed filtering proxy -> public internet
|
||||
```
|
||||
|
||||
Publicznym kontraktem jest zachowanie kierowania ruchu, a nie wewnętrzne haki Node używane do jego implementacji. Klienty WebSocket płaszczyzny sterowania OpenClaw Gateway używają wąskiej ścieżki bezpośredniej dla ruchu local loopback Gateway RPC, gdy URL Gateway używa `localhost` albo literalnego adresu IP loopback, takiego jak `127.0.0.1` lub `[::1]`. Ta ścieżka płaszczyzny sterowania musi być w stanie dotrzeć do Gateway działających przez loopback, nawet gdy serwer proxy operatora blokuje miejsca docelowe loopback. Zwykłe żądania HTTP i WebSocket środowiska wykonawczego nadal używają skonfigurowanego serwera proxy.
|
||||
Publicznym kontraktem jest zachowanie trasowania, a nie wewnętrzne haki Node używane do jego implementacji. Klienty WebSocket płaszczyzny sterowania OpenClaw Gateway używają wąskiej ścieżki bezpośredniej dla ruchu RPC Gateway przez local loopback, gdy URL Gateway używa `localhost` albo literalnego adresu IP loopback, takiego jak `127.0.0.1` lub `[::1]`. Ta ścieżka płaszczyzny sterowania musi móc osiągać lokalne Gateway nawet wtedy, gdy proxy operatora blokuje miejsca docelowe loopback. Zwykłe żądania HTTP i WebSocket środowiska uruchomieniowego nadal używają skonfigurowanego proxy.
|
||||
|
||||
Wewnętrznie OpenClaw używa dwóch haków kierowania na poziomie procesu dla tej funkcji:
|
||||
Wewnętrznie OpenClaw używa dla tej funkcji dwóch haków trasowania na poziomie procesu:
|
||||
|
||||
- Kierowanie przez dispatcher Undici obejmuje `fetch`, klientów opartych na undici oraz transporty, które udostępniają własny dispatcher undici.
|
||||
- Kierowanie `global-agent` obejmuje wywołujących z rdzenia Node `node:http` i `node:https`, w tym wiele bibliotek opartych na `http.request`, `https.request`, `http.get` i `https.get`. Zarządzany tryb proxy wymusza tego globalnego agenta, aby jawni agenci HTTP Node nie omijali przypadkowo serwera proxy operatora.
|
||||
- Trasowanie dyspozytora Undici obejmuje `fetch`, klientów opartych na undici oraz transporty, które udostępniają własny dyspozytor undici.
|
||||
- Trasowanie `global-agent` obejmuje wywołujących z rdzenia Node `node:http` i `node:https`, w tym wiele bibliotek opartych na `http.request`, `https.request`, `http.get` i `https.get`. Zarządzany tryb proxy wymusza tego globalnego agenta, aby jawni agenci HTTP Node nie omijali przypadkowo proxy operatora.
|
||||
|
||||
Niektóre pluginy mają własne transporty, które wymagają jawnego podłączenia proxy nawet wtedy, gdy istnieje kierowanie na poziomie procesu. Na przykład transport Bot API Telegram używa własnego dispatchera HTTP/1 undici i dlatego respektuje zmienne środowiskowe proxy procesu oraz zarządzaną rezerwę `OPENCLAW_PROXY_URL` w tej ścieżce transportu właściwej dla właściciela.
|
||||
Niektóre Pluginy posiadają własne transporty, które wymagają jawnego podłączenia proxy nawet wtedy, gdy istnieje trasowanie na poziomie procesu. Na przykład transport Bot API Telegram używa własnego dyspozytora HTTP/1 undici i dlatego respektuje środowisko proxy procesu oraz zarządzane awaryjne `OPENCLAW_PROXY_URL` w tej ścieżce transportu specyficznej dla właściciela.
|
||||
|
||||
Sam URL serwera proxy musi używać `http://`. Miejsca docelowe HTTPS nadal są obsługiwane przez serwer proxy za pomocą HTTP `CONNECT`; oznacza to tylko, że OpenClaw oczekuje zwykłego nasłuchującego serwera forward proxy HTTP, takiego jak `http://127.0.0.1:3128`.
|
||||
Sam URL proxy musi używać `http://`. Miejsca docelowe HTTPS nadal są obsługiwane przez proxy za pomocą HTTP `CONNECT`; oznacza to tylko, że OpenClaw oczekuje zwykłego nasłuchującego proxy przekazującego HTTP, takiego jak `http://127.0.0.1:3128`.
|
||||
|
||||
Gdy serwer proxy jest aktywny, OpenClaw czyści `no_proxy`, `NO_PROXY` i `GLOBAL_AGENT_NO_PROXY`. Te listy obejść są oparte na miejscach docelowych, więc pozostawienie tam `localhost` lub `127.0.0.1` pozwoliłoby wysokiego ryzyka celom SSRF ominąć filtrujący serwer proxy.
|
||||
Gdy proxy jest aktywny, OpenClaw czyści `no_proxy`, `NO_PROXY` i `GLOBAL_AGENT_NO_PROXY`. Te listy obejść są oparte na miejscach docelowych, więc pozostawienie tam `localhost` lub `127.0.0.1` pozwoliłoby celom SSRF wysokiego ryzyka ominąć filtrujący proxy.
|
||||
|
||||
Podczas zamykania OpenClaw przywraca poprzednie środowisko proxy i resetuje buforowany stan kierowania procesu.
|
||||
Podczas wyłączania OpenClaw przywraca poprzednie środowisko proxy i resetuje buforowany stan trasowania procesu.
|
||||
|
||||
## Powiązane terminy proxy
|
||||
## Powiązane terminy dotyczące proxy
|
||||
|
||||
- `proxy.enabled` / `proxy.proxyUrl`: kierowanie ruchu wychodzącego przez forward proxy dla ruchu wychodzącego środowiska wykonawczego OpenClaw. Ta strona dokumentuje tę funkcję.
|
||||
- `gateway.auth.mode: "trusted-proxy"`: przychodzące uwierzytelnianie przez odwrotny serwer proxy świadomy tożsamości dla dostępu do Gateway. Zobacz [Uwierzytelnianie przez zaufany serwer proxy](/pl/gateway/trusted-proxy-auth).
|
||||
- `openclaw proxy`: lokalny debugujący serwer proxy i inspektor przechwytywania do rozwoju i wsparcia. Zobacz [openclaw proxy](/pl/cli/proxy).
|
||||
- Ustawienia proxy właściwe dla kanału lub dostawcy: nadpisania właściwe dla właściciela dla konkretnego transportu. Preferuj zarządzany sieciowy serwer proxy, gdy celem jest centralna kontrola ruchu wychodzącego w całym środowisku wykonawczym.
|
||||
- `proxy.enabled` / `proxy.proxyUrl`: trasowanie wychodzące przez proxy przekazujący dla ruchu środowiska uruchomieniowego OpenClaw. Ta strona dokumentuje tę funkcję.
|
||||
- `gateway.auth.mode: "trusted-proxy"`: uwierzytelnianie przychodzące przez świadomy tożsamości reverse proxy dla dostępu do Gateway. Zobacz [Uwierzytelnianie przez zaufany proxy](/pl/gateway/trusted-proxy-auth).
|
||||
- `openclaw proxy`: lokalny proxy debugowania i inspektor przechwytywania do rozwoju i wsparcia. Zobacz [openclaw proxy](/pl/cli/proxy).
|
||||
- Ustawienia proxy specyficzne dla kanału lub dostawcy: nadpisania specyficzne dla właściciela dla konkretnego transportu. Preferuj zarządzany proxy sieciowy, gdy celem jest centralna kontrola ruchu wychodzącego w całym środowisku uruchomieniowym.
|
||||
|
||||
## Konfiguracja
|
||||
|
||||
@ -73,7 +73,7 @@ proxy:
|
||||
proxyUrl: http://127.0.0.1:3128
|
||||
```
|
||||
|
||||
Możesz także podać URL przez środowisko, zachowując `proxy.enabled=true` w konfiguracji:
|
||||
Możesz też podać URL przez środowisko, zachowując `proxy.enabled=true` w konfiguracji:
|
||||
|
||||
```bash
|
||||
OPENCLAW_PROXY_URL=http://127.0.0.1:3128 openclaw gateway run
|
||||
@ -81,9 +81,9 @@ OPENCLAW_PROXY_URL=http://127.0.0.1:3128 openclaw gateway run
|
||||
|
||||
`proxy.proxyUrl` ma pierwszeństwo przed `OPENCLAW_PROXY_URL`.
|
||||
|
||||
Jeśli `enabled=true`, ale nie skonfigurowano prawidłowego URL serwera proxy, chronione polecenia kończą uruchamianie niepowodzeniem zamiast wracać do bezpośredniego dostępu do sieci.
|
||||
Jeśli `enabled=true`, ale nie skonfigurowano prawidłowego URL proxy, chronione polecenia kończą uruchamianie błędem zamiast wracać do bezpośredniego dostępu do sieci.
|
||||
|
||||
Dla zarządzanych usług Gateway uruchamianych za pomocą `openclaw gateway start` preferuj przechowywanie URL w konfiguracji:
|
||||
Dla zarządzanych usług Gateway uruchamianych za pomocą `openclaw gateway start` preferuj zapisanie URL w konfiguracji:
|
||||
|
||||
```bash
|
||||
openclaw config set proxy.enabled true
|
||||
@ -92,63 +92,63 @@ openclaw gateway install --force
|
||||
openclaw gateway start
|
||||
```
|
||||
|
||||
Rezerwa środowiskowa najlepiej nadaje się do uruchomień pierwszoplanowych. Jeśli używasz jej z zainstalowaną usługą, umieść `OPENCLAW_PROXY_URL` w trwałym środowisku usługi, takim jak `$OPENCLAW_STATE_DIR/.env` lub `~/.openclaw/.env`, a następnie ponownie zainstaluj usługę, aby launchd, systemd lub Zaplanowane zadania uruchamiały Gateway z tą wartością.
|
||||
Awaryjne użycie środowiska najlepiej nadaje się do uruchomień pierwszoplanowych. Jeśli używasz go z zainstalowaną usługą, umieść `OPENCLAW_PROXY_URL` w trwałym środowisku usługi, takim jak `$OPENCLAW_STATE_DIR/.env` lub `~/.openclaw/.env`, a następnie zainstaluj usługę ponownie, aby launchd, systemd lub Scheduled Tasks uruchamiały gateway z tą wartością.
|
||||
|
||||
Dla poleceń `openclaw --container ...` OpenClaw przekazuje `OPENCLAW_PROXY_URL` do podrzędnego CLI przeznaczonego dla kontenera, gdy jest ustawiony. URL musi być osiągalny z wnętrza kontenera; `127.0.0.1` odnosi się do samego kontenera, a nie hosta. OpenClaw odrzuca URL-e serwera proxy loopback dla poleceń przeznaczonych dla kontenera, chyba że jawnie nadpiszesz to sprawdzenie bezpieczeństwa.
|
||||
Dla poleceń `openclaw --container ...` OpenClaw przekazuje `OPENCLAW_PROXY_URL` do docelowego dla kontenera procesu potomnego CLI, gdy jest ustawiony. URL musi być osiągalny z wnętrza kontenera; `127.0.0.1` odnosi się do samego kontenera, a nie do hosta. OpenClaw odrzuca URL-e proxy loopback dla poleceń docelowych dla kontenera, chyba że jawnie nadpiszesz tę kontrolę bezpieczeństwa.
|
||||
|
||||
## Wymagania dotyczące serwera proxy
|
||||
## Wymagania proxy
|
||||
|
||||
Polityka serwera proxy jest granicą bezpieczeństwa. OpenClaw nie może zweryfikować, czy serwer proxy blokuje właściwe cele.
|
||||
Polityka proxy jest granicą bezpieczeństwa. OpenClaw nie może zweryfikować, czy proxy blokuje właściwe cele.
|
||||
|
||||
Skonfiguruj serwer proxy tak, aby:
|
||||
Skonfiguruj proxy tak, aby:
|
||||
|
||||
- Wiązał się tylko z loopback lub prywatnym zaufanym interfejsem.
|
||||
- Ograniczał dostęp tak, aby tylko proces OpenClaw, host, kontener lub konto usługi mogły go używać.
|
||||
- Wiązał się tylko z loopback albo prywatnym zaufanym interfejsem.
|
||||
- Ograniczał dostęp tak, aby mógł go używać tylko proces, host, kontener lub konto usługi OpenClaw.
|
||||
- Samodzielnie rozwiązywał miejsca docelowe i blokował docelowe adresy IP po rozwiązaniu DNS.
|
||||
- Stosował politykę przy połączeniu zarówno dla zwykłych żądań HTTP, jak i tuneli HTTPS `CONNECT`.
|
||||
- Odrzucał obejścia oparte na miejscu docelowym dla zakresów loopback, prywatnych, link-local, metadanych, multicast, zarezerwowanych lub dokumentacyjnych.
|
||||
- Stosował politykę w chwili połączenia zarówno dla zwykłych żądań HTTP, jak i tuneli HTTPS `CONNECT`.
|
||||
- Odrzucał obejścia oparte na miejscach docelowych dla zakresów loopback, prywatnych, link-local, metadanych, multicast, zarezerwowanych lub dokumentacyjnych.
|
||||
- Unikał list dozwolonych nazw hostów, chyba że w pełni ufasz ścieżce rozwiązywania DNS.
|
||||
- Rejestrował miejsce docelowe, decyzję, status i powód bez rejestrowania treści żądań, nagłówków autoryzacji, plików cookie ani innych sekretów.
|
||||
- Utrzymywał politykę proxy pod kontrolą wersji i przeglądał zmiany tak jak konfigurację wrażliwą na bezpieczeństwo.
|
||||
- Rejestrował miejsce docelowe, decyzję, status i powód bez rejestrowania treści żądań, nagłówków autoryzacji, ciasteczek ani innych sekretów.
|
||||
- Utrzymywał politykę proxy pod kontrolą wersji i przeglądał zmiany jak konfigurację wrażliwą pod kątem bezpieczeństwa.
|
||||
|
||||
## Zalecane blokowane miejsca docelowe
|
||||
|
||||
Użyj tej listy odmów jako punktu wyjścia dla dowolnego forward proxy, zapory lub polityki ruchu wychodzącego.
|
||||
Użyj tej listy blokowania jako punktu wyjścia dla dowolnego proxy przekazującego, zapory lub polityki ruchu wychodzącego.
|
||||
|
||||
Logika klasyfikatora na poziomie aplikacji OpenClaw znajduje się w `src/infra/net/ssrf.ts` i `src/shared/net/ip.ts`. Odpowiednie haki zgodności to `BLOCKED_HOSTNAMES`, `BLOCKED_IPV4_SPECIAL_USE_RANGES`, `BLOCKED_IPV6_SPECIAL_USE_RANGES`, `RFC2544_BENCHMARK_PREFIX` oraz obsługa osadzonych wartowników IPv4 dla NAT64, 6to4, Teredo, ISATAP i form mapowanych na IPv4. Te pliki są przydatnymi odniesieniami podczas utrzymywania zewnętrznej polityki proxy, ale OpenClaw nie eksportuje ani nie egzekwuje automatycznie tych reguł w Twoim serwerze proxy.
|
||||
Logika klasyfikatora na poziomie aplikacji OpenClaw znajduje się w `src/infra/net/ssrf.ts` i `src/shared/net/ip.ts`. Odpowiednie haki zgodności to `BLOCKED_HOSTNAMES`, `BLOCKED_IPV4_SPECIAL_USE_RANGES`, `BLOCKED_IPV6_SPECIAL_USE_RANGES`, `RFC2544_BENCHMARK_PREFIX` oraz obsługa osadzonego wartownika IPv4 dla NAT64, 6to4, Teredo, ISATAP i form mapowanych z IPv4. Te pliki są przydatnymi odniesieniami podczas utrzymywania zewnętrznej polityki proxy, ale OpenClaw nie eksportuje automatycznie ani nie wymusza tych reguł w Twoim proxy.
|
||||
|
||||
| Zakres lub host | Dlaczego blokować |
|
||||
| Zakres lub host | Dlaczego blokować |
|
||||
| ------------------------------------------------------------------------------------ | -------------------------------------------------- |
|
||||
| `127.0.0.0/8`, `localhost`, `localhost.localdomain` | IPv4 loopback |
|
||||
| `::1/128` | IPv6 loopback |
|
||||
| `0.0.0.0/8`, `::/128` | Adresy nieokreślone i tej sieci |
|
||||
| `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16` | Prywatne sieci RFC1918 |
|
||||
| `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16` | Sieci prywatne RFC1918 |
|
||||
| `169.254.0.0/16`, `fe80::/10` | Adresy link-local i typowe ścieżki metadanych chmur |
|
||||
| `169.254.169.254`, `metadata.google.internal` | Usługi metadanych chmury |
|
||||
| `100.64.0.0/10` | Współdzielona przestrzeń adresowa NAT operatorskiego |
|
||||
| `198.18.0.0/15`, `2001:2::/48` | Zakresy testów wydajności |
|
||||
| `169.254.169.254`, `metadata.google.internal` | Usługi metadanych chmur |
|
||||
| `100.64.0.0/10` | Wspólna przestrzeń adresowa NAT klasy operatorskiej |
|
||||
| `198.18.0.0/15`, `2001:2::/48` | Zakresy testów wydajnościowych |
|
||||
| `192.0.0.0/24`, `192.0.2.0/24`, `198.51.100.0/24`, `203.0.113.0/24`, `2001:db8::/32` | Zakresy specjalnego użycia i dokumentacyjne |
|
||||
| `224.0.0.0/4`, `ff00::/8` | Multicast |
|
||||
| `240.0.0.0/4` | Zarezerwowane IPv4 |
|
||||
| `240.0.0.0/4` | Zarezerwowany IPv4 |
|
||||
| `fc00::/7`, `fec0::/10` | Lokalne/prywatne zakresy IPv6 |
|
||||
| `100::/64`, `2001:20::/28` | Zakresy odrzucania IPv6 i ORCHIDv2 |
|
||||
| `100::/64`, `2001:20::/28` | Zakresy IPv6 discard i ORCHIDv2 |
|
||||
| `64:ff9b::/96`, `64:ff9b:1::/48` | Prefiksy NAT64 z osadzonym IPv4 |
|
||||
| `2002::/16`, `2001::/32` | 6to4 i Teredo z osadzonym IPv4 |
|
||||
| `::/96`, `::ffff:0:0/96` | IPv6 zgodne z IPv4 i IPv6 mapowane na IPv4 |
|
||||
| `::/96`, `::ffff:0:0/96` | IPv6 zgodny z IPv4 i IPv6 mapowany z IPv4 |
|
||||
|
||||
Jeśli Twój dostawca chmury lub platforma sieciowa dokumentuje dodatkowe hosty metadanych albo zarezerwowane zakresy, dodaj je również.
|
||||
|
||||
## Walidacja
|
||||
|
||||
Zweryfikuj serwer proxy z tego samego hosta, kontenera lub konta usługi, które uruchamia OpenClaw:
|
||||
Zweryfikuj proxy z tego samego hosta, kontenera lub konta usługi, które uruchamia OpenClaw:
|
||||
|
||||
```bash
|
||||
openclaw proxy validate --proxy-url http://127.0.0.1:3128
|
||||
```
|
||||
|
||||
Domyślnie, gdy nie podano niestandardowych miejsc docelowych, polecenie sprawdza, czy `https://example.com/` kończy się powodzeniem, i uruchamia tymczasowy kanarek loopback, do którego serwer proxy nie może dotrzeć. Domyślne sprawdzenie odmowy przechodzi, gdy serwer proxy zwraca odpowiedź odmowy inną niż 2xx albo blokuje kanarka błędem transportu; kończy się niepowodzeniem, jeśli skuteczna odpowiedź dotrze do kanarka. Jeśli żaden serwer proxy nie jest włączony i skonfigurowany, walidacja zgłasza problem z konfiguracją; użyj `--proxy-url` dla jednorazowego sprawdzenia wstępnego przed zmianą konfiguracji. Użyj `--allowed-url` i `--denied-url`, aby przetestować oczekiwania właściwe dla wdrożenia. Niestandardowe odrzucane miejsca docelowe działają fail-closed: dowolna odpowiedź HTTP oznacza, że miejsce docelowe było osiągalne przez serwer proxy, a każdy błąd transportu jest zgłaszany jako nierozstrzygający, ponieważ OpenClaw nie może udowodnić, że serwer proxy zablokował osiągalne źródło. Przy niepowodzeniu walidacji polecenie kończy działanie z kodem 1.
|
||||
Domyślnie, gdy nie podano niestandardowych miejsc docelowych, polecenie sprawdza, czy `https://example.com/` kończy się powodzeniem, oraz uruchamia tymczasowego kanarka loopback, którego proxy nie może osiągnąć. Domyślna kontrola odmowy przechodzi, gdy proxy zwraca odpowiedź odmowną inną niż 2xx albo blokuje kanarka błędem transportu; kończy się niepowodzeniem, jeśli skuteczna odpowiedź dotrze do kanarka. Jeśli żaden proxy nie jest włączony i skonfigurowany, walidacja zgłasza problem z konfiguracją; użyj `--proxy-url` do jednorazowej kontroli przed zmianą konfiguracji. Użyj `--allowed-url` i `--denied-url`, aby przetestować oczekiwania specyficzne dla wdrożenia. Niestandardowe zablokowane miejsca docelowe działają w trybie zamkniętym w razie niepowodzenia: dowolna odpowiedź HTTP oznacza, że miejsce docelowe było osiągalne przez proxy, a dowolny błąd transportu jest zgłaszany jako nierozstrzygający, ponieważ OpenClaw nie może udowodnić, że proxy zablokował osiągalne źródło. W razie niepowodzenia walidacji polecenie kończy działanie z kodem 1.
|
||||
|
||||
Użyj `--json` do automatyzacji. Dane wyjściowe JSON zawierają ogólny wynik, efektywne źródło konfiguracji proxy, wszelkie błędy konfiguracji oraz każde sprawdzenie miejsca docelowego. Poświadczenia URL serwera proxy są redagowane w danych wyjściowych tekstowych i JSON:
|
||||
Użyj `--json` do automatyzacji. Dane wyjściowe JSON zawierają ogólny wynik, efektywne źródło konfiguracji proxy, ewentualne błędy konfiguracji oraz każdą kontrolę miejsca docelowego. Dane uwierzytelniające w URL proxy są redagowane w danych wyjściowych tekstowych i JSON:
|
||||
|
||||
```json
|
||||
{
|
||||
@ -178,9 +178,9 @@ curl -x http://127.0.0.1:3128 http://127.0.0.1/
|
||||
curl -x http://127.0.0.1:3128 http://169.254.169.254/
|
||||
```
|
||||
|
||||
Żądanie publiczne powinno się powieść. Żądania do pętli zwrotnej i metadanych powinny zostać zablokowane przez proxy. W przypadku `openclaw proxy validate` wbudowany kanarek pętli zwrotnej może odróżnić odmowę proxy od osiągalnego źródła. Niestandardowe kontrole `--denied-url` nie mają tego kanarka, więc traktuj zarówno odpowiedzi HTTP, jak i niejednoznaczne awarie transportu jako błędy walidacji, chyba że proxy udostępnia specyficzny dla wdrożenia sygnał odmowy, który możesz zweryfikować osobno.
|
||||
Żądanie publiczne powinno się powieść. Żądania loopback i metadanych powinny zostać zablokowane przez proxy. W przypadku `openclaw proxy validate` wbudowany kanarek loopback potrafi odróżnić odmowę proxy od osiągalnego źródła. Niestandardowe kontrole `--denied-url` nie mają tego kanarka, więc traktuj zarówno odpowiedzi HTTP, jak i niejednoznaczne awarie transportu jako niepowodzenia walidacji, chyba że Twoje proxy udostępnia specyficzny dla wdrożenia sygnał odmowy, który możesz zweryfikować osobno.
|
||||
|
||||
Następnie włącz routing proxy OpenClaw:
|
||||
Następnie włącz trasowanie proxy OpenClaw:
|
||||
|
||||
```bash
|
||||
openclaw config set proxy.enabled true
|
||||
@ -198,10 +198,11 @@ proxy:
|
||||
|
||||
## Ograniczenia
|
||||
|
||||
- Proxy poprawia pokrycie dla lokalnych dla procesu klientów JavaScript HTTP i WebSocket, ale nie jest piaskownicą sieciową na poziomie systemu operacyjnego.
|
||||
- Surowe gniazda `net`, `tls` i `http2`, natywne dodatki oraz procesy potomne mogą omijać routing proxy na poziomie Node, chyba że dziedziczą zmienne środowiskowe proxy i ich przestrzegają.
|
||||
- IRC to surowy kanał TCP/TLS poza zarządzanym przez operatora routingiem przez proxy przekazujące. We wdrożeniach, które wymagają całego ruchu wychodzącego przez to proxy przekazujące, ustaw `channels.irc.enabled=false`, chyba że bezpośredni ruch wychodzący IRC jest jawnie zatwierdzony.
|
||||
- Lokalne WebUI użytkownika i lokalne serwery modeli należy w razie potrzeby dodać do listy dozwolonych w polityce proxy operatora; OpenClaw nie udostępnia dla nich ogólnego obejścia sieci lokalnej.
|
||||
- Obejście proxy płaszczyzny sterowania Gateway jest celowo ograniczone do `localhost` i URL-i z dosłownymi adresami IP pętli zwrotnej. Użyj `ws://127.0.0.1:18789`, `ws://[::1]:18789` albo `ws://localhost:18789` dla lokalnych bezpośrednich połączeń z płaszczyzną sterowania Gateway; inne nazwy hostów są routowane jak zwykły ruch oparty na nazwach hostów.
|
||||
- Proxy poprawia pokrycie dla lokalnych dla procesu klientów HTTP i WebSocket w JavaScript, ale nie jest piaskownicą sieciową na poziomie systemu operacyjnego.
|
||||
- Surowe gniazda `net`, `tls` i `http2`, natywne dodatki oraz procesy potomne mogą omijać trasowanie proxy na poziomie Node, chyba że dziedziczą i respektują zmienne środowiskowe proxy.
|
||||
- IRC jest surowym kanałem TCP/TLS poza trasowaniem przez zarządzane przez operatora proxy przekazujące. We wdrożeniach, które wymagają całego ruchu wychodzącego przez takie proxy przekazujące, ustaw `channels.irc.enabled=false`, chyba że bezpośredni ruch wychodzący IRC jest wyraźnie zatwierdzony.
|
||||
- Lokalne proxy debugowania jest narzędziem diagnostycznym, a jego bezpośrednie przekazywanie upstream dla żądań proxy i tuneli CONNECT jest domyślnie wyłączone, gdy aktywny jest tryb zarządzanego proxy; włącz bezpośrednie przekazywanie tylko dla zatwierdzonej lokalnej diagnostyki.
|
||||
- Lokalne WebUI użytkownika i lokalne serwery modeli powinny być w razie potrzeby dodane do listy dozwolonych w polityce proxy operatora; OpenClaw nie udostępnia dla nich ogólnego obejścia sieci lokalnej.
|
||||
- Obejście proxy dla płaszczyzny sterowania Gateway jest celowo ograniczone do `localhost` i dosłownych adresów URL IP loopback. Używaj `ws://127.0.0.1:18789`, `ws://[::1]:18789` lub `ws://localhost:18789` dla lokalnych bezpośrednich połączeń z płaszczyzną sterowania Gateway; inne nazwy hostów są trasowane jak zwykły ruch oparty na nazwie hosta.
|
||||
- OpenClaw nie sprawdza, nie testuje ani nie certyfikuje Twojej polityki proxy.
|
||||
- Traktuj zmiany polityki proxy jako operacyjne zmiany wrażliwe pod względem bezpieczeństwa.
|
||||
- Traktuj zmiany polityki proxy jako operacyjne zmiany wrażliwe z punktu widzenia bezpieczeństwa.
|
||||
|
||||
@ -1,44 +1,47 @@
|
||||
---
|
||||
read_when:
|
||||
- Chcesz wykonywać pracę w tle lub równolegle za pośrednictwem agenta
|
||||
- Zmieniasz sessions_spawn lub zasady narzędzi subagentów
|
||||
- Implementujesz lub rozwiązujesz problemy z sesjami podagentów powiązanymi z wątkiem
|
||||
- Chcesz wykonywać pracę w tle lub równoległą za pośrednictwem agenta
|
||||
- Zmieniasz zasady dotyczące sessions_spawn lub narzędzia subagentów
|
||||
- Implementujesz lub rozwiązujesz problemy z sesjami podagentów przypisanymi do wątku
|
||||
sidebarTitle: Sub-agents
|
||||
summary: Uruchamiaj izolowane przebiegi agentów w tle, które przekazują wyniki z powrotem na czacie osoby zgłaszającej
|
||||
summary: Uruchamiaj izolowane przebiegi agentów w tle, które ogłaszają wyniki z powrotem na czacie osoby zgłaszającej.
|
||||
title: Podagenci
|
||||
x-i18n:
|
||||
generated_at: "2026-05-04T02:27:20Z"
|
||||
generated_at: "2026-05-04T07:06:43Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: d0df39e06b952def3eb0b296f36c7dc8c0b0a115785d865236a970c5d453fc37
|
||||
source_hash: 65d60bf6813d667b7311aa28109d4bd6be012a16e638c64cfff130831db88cd8
|
||||
source_path: tools/subagents.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
Agenci podrzędni to działające w tle uruchomienia agentów utworzone z istniejącego uruchomienia agenta.
|
||||
Działają we własnej sesji (`agent:<agentId>:subagent:<uuid>`) i
|
||||
po zakończeniu **ogłaszają** swój wynik z powrotem na kanale czatu
|
||||
żądającego. Każde uruchomienie agenta podrzędnego jest śledzone jako
|
||||
Subagenci to uruchomienia agentów w tle, utworzone z istniejącego uruchomienia agenta.
|
||||
Działają we własnej sesji (`agent:<agentId>:subagent:<uuid>`) i,
|
||||
po zakończeniu, **ogłaszają** swój wynik z powrotem na kanale czatu
|
||||
żądającego. Każde uruchomienie subagenta jest śledzone jako
|
||||
[zadanie w tle](/pl/automation/tasks).
|
||||
|
||||
Główne cele:
|
||||
|
||||
- Równoległe wykonywanie pracy typu „badania / długie zadanie / wolne narzędzie” bez blokowania głównego uruchomienia.
|
||||
- Domyślna izolacja agentów podrzędnych (oddzielenie sesji + opcjonalny sandboxing).
|
||||
- Utrzymanie powierzchni narzędzi trudnej do niewłaściwego użycia: agenci podrzędni domyślnie **nie** otrzymują narzędzi sesji.
|
||||
- Obsługa konfigurowalnej głębokości zagnieżdżania dla wzorców orkiestratorów.
|
||||
- Równoległe wykonywanie prac typu „badanie / długie zadanie / wolne narzędzie” bez blokowania głównego uruchomienia.
|
||||
- Domyślna izolacja subagentów (separacja sesji + opcjonalny sandboxing).
|
||||
- Utrzymanie powierzchni narzędzi trudnej do niewłaściwego użycia: subagenci domyślnie **nie** dostają narzędzi sesji.
|
||||
- Obsługa konfigurowalnej głębokości zagnieżdżania dla wzorców orkiestratora.
|
||||
|
||||
<Note>
|
||||
**Uwaga o kosztach:** każdy agent podrzędny domyślnie ma własny kontekst i zużycie tokenów. Przy ciężkich lub powtarzalnych zadaniach ustaw tańszy model dla agentów podrzędnych i pozostaw głównego agenta na modelu wyższej jakości. Skonfiguruj to przez `agents.defaults.subagents.model` albo nadpisania dla konkretnego agenta. Gdy dziecko
|
||||
rzeczywiście potrzebuje bieżącego transkryptu żądającego, agent może zażądać
|
||||
`context: "fork"` przy tym jednym utworzeniu. Sesje agentów podrzędnych powiązane z wątkiem domyślnie używają
|
||||
**Uwaga o kosztach:** każdy subagent domyślnie ma własny kontekst i użycie tokenów.
|
||||
Dla ciężkich lub powtarzalnych zadań ustaw tańszy model dla subagentów
|
||||
i pozostaw głównego agenta na modelu wyższej jakości. Skonfiguruj przez
|
||||
`agents.defaults.subagents.model` albo nadpisania dla poszczególnych agentów. Gdy dziecko
|
||||
rzeczywiście potrzebuje bieżącej transkrypcji żądającego, agent może zażądać
|
||||
`context: "fork"` przy tym jednym utworzeniu. Sesje subagentów powiązane z wątkiem domyślnie używają
|
||||
`context: "fork"`, ponieważ rozgałęziają bieżącą rozmowę do
|
||||
wątku kontynuacji.
|
||||
</Note>
|
||||
|
||||
## Polecenie slash
|
||||
|
||||
Użyj `/subagents`, aby sprawdzać lub kontrolować uruchomienia agentów podrzędnych dla **bieżącej
|
||||
Użyj `/subagents`, aby sprawdzić lub kontrolować uruchomienia subagentów dla **bieżącej
|
||||
sesji**:
|
||||
|
||||
```text
|
||||
@ -51,16 +54,16 @@ sesji**:
|
||||
/subagents spawn <agentId> <task> [--model <model>] [--thinking <level>]
|
||||
```
|
||||
|
||||
Użyj najwyższego poziomu [`/steer <message>`](/pl/tools/steer), aby sterować aktywnym uruchomieniem bieżącej sesji żądającego. Użyj `/subagents steer <id|#> <message>`, gdy celem jest uruchomienie dziecka.
|
||||
Użyj polecenia najwyższego poziomu [`/steer <message>`](/pl/tools/steer), aby sterować aktywnym uruchomieniem bieżącej sesji żądającego. Użyj `/subagents steer <id|#> <message>`, gdy celem jest uruchomienie potomne.
|
||||
|
||||
`/subagents info` pokazuje metadane uruchomienia (status, znaczniki czasu, identyfikator sesji,
|
||||
ścieżkę transkryptu, czyszczenie). Użyj `sessions_history`, aby uzyskać ograniczony,
|
||||
filtrowany pod kątem bezpieczeństwa widok przypomnienia; sprawdź ścieżkę transkryptu na dysku, gdy
|
||||
potrzebujesz surowego pełnego transkryptu.
|
||||
ścieżkę transkrypcji, czyszczenie). Użyj `sessions_history`, aby uzyskać ograniczony,
|
||||
filtrowany pod kątem bezpieczeństwa widok przywołania; sprawdź ścieżkę transkrypcji na dysku, gdy
|
||||
potrzebujesz surowej pełnej transkrypcji.
|
||||
|
||||
### Kontrolki wiązania wątków
|
||||
### Kontrolki powiązania z wątkiem
|
||||
|
||||
Te polecenia działają na kanałach obsługujących trwałe wiązania wątków.
|
||||
Te polecenia działają na kanałach obsługujących trwałe powiązania z wątkami.
|
||||
Zobacz [Kanały obsługujące wątki](#thread-supporting-channels) poniżej.
|
||||
|
||||
```text
|
||||
@ -73,82 +76,83 @@ Zobacz [Kanały obsługujące wątki](#thread-supporting-channels) poniżej.
|
||||
|
||||
### Zachowanie tworzenia
|
||||
|
||||
`/subagents spawn` uruchamia agenta podrzędnego w tle jako polecenie użytkownika (nie jako
|
||||
wewnętrzne przekazanie) i wysyła jedną końcową aktualizację o ukończeniu z powrotem do
|
||||
czatu żądającego, gdy uruchomienie się zakończy.
|
||||
`/subagents spawn` uruchamia subagenta w tle jako polecenie użytkownika (nie jako
|
||||
wewnętrzne przekazanie) i wysyła jedną końcową aktualizację ukończenia z powrotem na
|
||||
czat żądającego, gdy uruchomienie się zakończy.
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Nieblokujące ukończenie oparte na wysyłaniu">
|
||||
- Polecenie tworzenia jest nieblokujące; natychmiast zwraca identyfikator uruchomienia.
|
||||
- Po ukończeniu agent podrzędny ogłasza komunikat z podsumowaniem/wynikiem z powrotem na kanale czatu żądającego.
|
||||
- Ukończenie jest oparte na wysyłaniu. Po utworzeniu **nie** odpytuj `/subagents list`, `sessions_list` ani `sessions_history` w pętli tylko po to, aby czekać na zakończenie; sprawdzaj status tylko na żądanie przy debugowaniu lub interwencji.
|
||||
- Po ukończeniu OpenClaw w miarę możliwości zamyka śledzone karty/procesy przeglądarki otwarte przez tę sesję agenta podrzędnego, zanim przepływ czyszczenia ogłoszenia będzie kontynuowany.
|
||||
<Accordion title="Non-blocking, push-based completion">
|
||||
- Polecenie tworzenia nie blokuje; natychmiast zwraca identyfikator uruchomienia.
|
||||
- Po ukończeniu subagent ogłasza wiadomość z podsumowaniem/wynikiem z powrotem na kanale czatu żądającego.
|
||||
- Ukończenie jest oparte na wypychaniu. Po utworzeniu **nie** odpytuj `/subagents list`, `sessions_list` ani `sessions_history` w pętli tylko po to, aby czekać na zakończenie; sprawdzaj status tylko na żądanie przy debugowaniu lub interwencji.
|
||||
- Po ukończeniu OpenClaw w miarę możliwości zamyka śledzone karty przeglądarki/procesy otwarte przez tę sesję subagenta, zanim będzie kontynuowany przepływ czyszczenia ogłoszenia.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Odporność dostarczania ręcznie utworzonych uruchomień">
|
||||
- OpenClaw najpierw próbuje bezpośredniego dostarczania `agent` ze stabilnym kluczem idempotencji.
|
||||
- Jeśli bezpośrednie dostarczenie się nie powiedzie, przechodzi na trasowanie przez kolejkę.
|
||||
- Jeśli trasowanie przez kolejkę nadal nie jest dostępne, ogłoszenie jest ponawiane z krótkim wykładniczym wycofywaniem przed ostateczną rezygnacją.
|
||||
- Dostarczenie ukończenia zachowuje rozwiązaną trasę żądającego: trasy ukończenia powiązane z wątkiem lub rozmową mają pierwszeństwo, gdy są dostępne; jeśli źródło ukończenia dostarcza tylko kanał, OpenClaw uzupełnia brakujący cel/konto z rozwiązanej trasy sesji żądającego (`lastChannel` / `lastTo` / `lastAccountId`), aby bezpośrednie dostarczenie nadal działało.
|
||||
<Accordion title="Manual-spawn delivery resilience">
|
||||
- OpenClaw najpierw próbuje bezpośredniego dostarczenia `agent` ze stabilnym kluczem idempotencji.
|
||||
- Jeśli tura ukończenia agenta żądającego nie powiedzie się, nie wygeneruje widocznego wyjścia albo zwróci oczywiście niepełny prefiks przechwyconego wyniku dziecka, OpenClaw wraca do bezpośredniego dostarczenia ukończenia z przechwyconego wyniku dziecka.
|
||||
- Jeśli nie można użyć bezpośredniego dostarczenia, wraca do routingu przez kolejkę.
|
||||
- Jeśli routing przez kolejkę nadal nie jest dostępny, ogłoszenie jest ponawiane z krótkim wykładniczym opóźnieniem przed ostatecznym zrezygnowaniem.
|
||||
- Dostarczanie ukończenia zachowuje rozwiązaną trasę żądającego: trasy ukończenia powiązane z wątkiem lub rozmową wygrywają, gdy są dostępne; jeśli źródło ukończenia podaje tylko kanał, OpenClaw uzupełnia brakujący cel/konto z rozwiązanej trasy sesji żądającego (`lastChannel` / `lastTo` / `lastAccountId`), aby bezpośrednie dostarczenie nadal działało.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Metadane przekazania ukończenia">
|
||||
Przekazanie ukończenia do sesji żądającego jest wygenerowanym w czasie wykonywania
|
||||
kontekstem wewnętrznym (nie tekstem napisanym przez użytkownika) i zawiera:
|
||||
<Accordion title="Completion handoff metadata">
|
||||
Przekazanie ukończenia do sesji żądającego to generowany w czasie działania
|
||||
kontekst wewnętrzny (nie tekst napisany przez użytkownika) i obejmuje:
|
||||
|
||||
- `Result` — najnowszy widoczny tekst odpowiedzi `assistant`, w przeciwnym razie oczyszczony najnowszy tekst narzędzia/toolResult. Końcowe nieudane uruchomienia nie używają ponownie przechwyconego tekstu odpowiedzi.
|
||||
- `Status` — `completed successfully` / `failed` / `timed out` / `unknown`.
|
||||
- Kompaktowe statystyki czasu wykonywania/tokenów.
|
||||
- Instrukcję dostarczenia mówiącą agentowi żądającego, aby przepisał treść normalnym głosem asystenta (nie przekazywał surowych metadanych wewnętrznych).
|
||||
- Kompaktowe statystyki czasu działania/tokenów.
|
||||
- Instrukcję dostarczenia mówiącą agentowi żądającemu, aby przepisał treść normalnym głosem asystenta (zamiast przekazywać surowe metadane wewnętrzne).
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Tryby i środowisko uruchomieniowe ACP">
|
||||
<Accordion title="Modes and ACP runtime">
|
||||
- `--model` i `--thinking` nadpisują wartości domyślne dla tego konkretnego uruchomienia.
|
||||
- Użyj `info`/`log`, aby sprawdzić szczegóły i dane wyjściowe po ukończeniu.
|
||||
- Użyj `info`/`log`, aby sprawdzić szczegóły i wyjście po ukończeniu.
|
||||
- `/subagents spawn` to tryb jednorazowy (`mode: "run"`). Dla trwałych sesji powiązanych z wątkiem użyj `sessions_spawn` z `thread: true` i `mode: "session"`.
|
||||
- Dla sesji uprzęży ACP (Claude Code, Gemini CLI, OpenCode albo jawnie Codex ACP/acpx) użyj `sessions_spawn` z `runtime: "acp"`, gdy narzędzie deklaruje to środowisko uruchomieniowe. Zobacz [model dostarczania ACP](/pl/tools/acp-agents#delivery-model) podczas debugowania ukończeń lub pętli agent-agent. Gdy Plugin `codex` jest włączony, sterowanie czatem/wątkiem Codex powinno preferować `/codex ...` zamiast ACP, chyba że użytkownik jawnie prosi o ACP/acpx.
|
||||
- OpenClaw ukrywa `runtime: "acp"`, dopóki ACP nie jest włączone, żądający nie jest w sandboxie, a Plugin backendu taki jak `acpx` jest załadowany. `runtime: "acp"` oczekuje zewnętrznego identyfikatora uprzęży ACP albo wpisu `agents.list[]` z `runtime.type="acp"`; użyj domyślnego środowiska uruchomieniowego agenta podrzędnego dla zwykłych agentów konfiguracji OpenClaw z `agents_list`.
|
||||
- Dla sesji uprzęży ACP (Claude Code, Gemini CLI, OpenCode albo jawne Codex ACP/acpx) użyj `sessions_spawn` z `runtime: "acp"`, gdy narzędzie reklamuje ten runtime. Zobacz [model dostarczania ACP](/pl/tools/acp-agents#delivery-model) podczas debugowania ukończeń albo pętli agent-do-agenta. Gdy Plugin `codex` jest włączony, sterowanie czatem/wątkiem Codex powinno preferować `/codex ...` zamiast ACP, chyba że użytkownik jawnie prosi o ACP/acpx.
|
||||
- OpenClaw ukrywa `runtime: "acp"` do czasu, aż ACP zostanie włączone, żądający nie jest w sandboxie, a Plugin backendu taki jak `acpx` jest załadowany. `runtime: "acp"` oczekuje identyfikatora zewnętrznej uprzęży ACP albo wpisu `agents.list[]` z `runtime.type="acp"`; użyj domyślnego runtime subagenta dla zwykłych agentów konfiguracji OpenClaw z `agents_list`.
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## Tryby kontekstu
|
||||
|
||||
Natywni agenci podrzędni startują w izolacji, chyba że wywołujący jawnie poprosi o rozgałęzienie
|
||||
bieżącego transkryptu.
|
||||
Natywni subagenci startują w izolacji, chyba że wywołujący jawnie poprosi o rozgałęzienie
|
||||
bieżącej transkrypcji.
|
||||
|
||||
| Tryb | Kiedy go używać | Zachowanie |
|
||||
| ---------- | -------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
|
||||
| `isolated` | Świeże badania, niezależna implementacja, wolna praca narzędziowa albo wszystko, co można streścić w tekście zadania | Tworzy czysty transkrypt dziecka. To ustawienie domyślne i utrzymuje niższe zużycie tokenów. |
|
||||
| `fork` | Praca zależna od bieżącej rozmowy, wcześniejszych wyników narzędzi lub niuansów instrukcji już obecnych w transkrypcie żądającego | Rozgałęzia transkrypt żądającego do sesji dziecka przed startem dziecka. |
|
||||
| `isolated` | Świeże badanie, niezależna implementacja, wolna praca narzędzia albo cokolwiek, co można opisać w treści zadania | Tworzy czystą transkrypcję dziecka. To ustawienie domyślne i utrzymuje niższe użycie tokenów. |
|
||||
| `fork` | Praca zależna od bieżącej rozmowy, wcześniejszych wyników narzędzi albo niuansów instrukcji już obecnych w transkrypcji żądającego | Rozgałęzia transkrypcję żądającego do sesji dziecka przed startem dziecka. |
|
||||
|
||||
Używaj `fork` oszczędnie. Służy do delegowania zależnego od kontekstu, a nie jako
|
||||
zamiennik napisania jasnego promptu zadania.
|
||||
|
||||
## Narzędzie: `sessions_spawn`
|
||||
|
||||
Uruchamia agenta podrzędnego z `deliver: false` na globalnej ścieżce `subagent`,
|
||||
Uruchamia subagenta z `deliver: false` na globalnym pasie `subagent`,
|
||||
następnie wykonuje krok ogłoszenia i publikuje odpowiedź ogłoszenia na kanale czatu
|
||||
żądającego.
|
||||
|
||||
Dostępność zależy od efektywnej polityki narzędzi wywołującego. Profile `coding` i
|
||||
`full` domyślnie udostępniają `sessions_spawn`. Profil `messaging`
|
||||
nie udostępnia; dodaj `tools.alsoAllow: ["sessions_spawn", "sessions_yield",
|
||||
tego nie robi; dodaj `tools.alsoAllow: ["sessions_spawn", "sessions_yield",
|
||||
"subagents"]` albo użyj `tools.profile: "coding"` dla agentów, którzy powinni delegować
|
||||
pracę. Polityki kanału/grupy, dostawcy, sandboxa i zezwalania/odmawiania dla konkretnego agenta nadal mogą
|
||||
pracę. Polityki kanału/grupy, dostawcy, sandboxu oraz zezwalania/odmawiania dla poszczególnych agentów nadal mogą
|
||||
usunąć narzędzie po etapie profilu. Użyj `/tools` z tej samej
|
||||
sesji, aby potwierdzić efektywną listę narzędzi.
|
||||
|
||||
**Wartości domyślne:**
|
||||
|
||||
- **Model:** dziedziczy po wywołującym, chyba że ustawisz `agents.defaults.subagents.model` (albo `agents.list[].subagents.model` dla konkretnego agenta); jawne `sessions_spawn.model` nadal ma pierwszeństwo.
|
||||
- **Thinking:** dziedziczy po wywołującym, chyba że ustawisz `agents.defaults.subagents.thinking` (albo `agents.list[].subagents.thinking` dla konkretnego agenta); jawne `sessions_spawn.thinking` nadal ma pierwszeństwo.
|
||||
- **Limit czasu uruchomienia:** jeśli `sessions_spawn.runTimeoutSeconds` jest pominięte, OpenClaw używa `agents.defaults.subagents.runTimeoutSeconds`, gdy jest ustawione; w przeciwnym razie przechodzi na `0` (brak limitu czasu).
|
||||
- **Model:** dziedziczy po wywołującym, chyba że ustawisz `agents.defaults.subagents.model` (albo `agents.list[].subagents.model` dla poszczególnych agentów); jawne `sessions_spawn.model` nadal wygrywa.
|
||||
- **Thinking:** dziedziczy po wywołującym, chyba że ustawisz `agents.defaults.subagents.thinking` (albo `agents.list[].subagents.thinking` dla poszczególnych agentów); jawne `sessions_spawn.thinking` nadal wygrywa.
|
||||
- **Limit czasu uruchomienia:** jeśli `sessions_spawn.runTimeoutSeconds` zostanie pominięte, OpenClaw używa `agents.defaults.subagents.runTimeoutSeconds`, gdy jest ustawione; w przeciwnym razie wraca do `0` (bez limitu czasu).
|
||||
|
||||
### Parametry narzędzia
|
||||
|
||||
<ParamField path="task" type="string" required>
|
||||
Opis zadania dla agenta podrzędnego.
|
||||
Opis zadania dla subagenta.
|
||||
</ParamField>
|
||||
<ParamField path="label" type="string">
|
||||
Opcjonalna etykieta czytelna dla człowieka.
|
||||
@ -160,53 +164,53 @@ sesji, aby potwierdzić efektywną listę narzędzi.
|
||||
`acp` jest tylko dla zewnętrznych uprzęży ACP (`claude`, `droid`, `gemini`, `opencode` albo jawnie zażądane Codex ACP/acpx) oraz dla wpisów `agents.list[]`, których `runtime.type` to `acp`.
|
||||
</ParamField>
|
||||
<ParamField path="resumeSessionId" type="string">
|
||||
Tylko ACP. Wznawia istniejącą sesję uprzęży ACP, gdy `runtime: "acp"`; ignorowane przy natywnym tworzeniu agentów podrzędnych.
|
||||
Tylko ACP. Wznawia istniejącą sesję uprzęży ACP, gdy `runtime: "acp"`; ignorowane dla natywnych utworzeń subagentów.
|
||||
</ParamField>
|
||||
<ParamField path="streamTo" type='"parent"'>
|
||||
Tylko ACP. Strumieniuje dane wyjściowe uruchomienia ACP do sesji nadrzędnej, gdy `runtime: "acp"`; pomiń przy natywnym tworzeniu agentów podrzędnych.
|
||||
Tylko ACP. Strumieniuje wyjście uruchomienia ACP do sesji nadrzędnej, gdy `runtime: "acp"`; pomiń dla natywnych utworzeń subagentów.
|
||||
</ParamField>
|
||||
<ParamField path="model" type="string">
|
||||
Nadpisz model agenta podrzędnego. Nieprawidłowe wartości są pomijane, a agent podrzędny działa na modelu domyślnym z ostrzeżeniem w wyniku narzędzia.
|
||||
Nadpisuje model subagenta. Nieprawidłowe wartości są pomijane, a subagent działa na domyślnym modelu z ostrzeżeniem w wyniku narzędzia.
|
||||
</ParamField>
|
||||
<ParamField path="thinking" type="string">
|
||||
Nadpisz poziom myślenia dla uruchomienia agenta podrzędnego.
|
||||
Nadpisuje poziom thinking dla uruchomienia subagenta.
|
||||
</ParamField>
|
||||
<ParamField path="runTimeoutSeconds" type="number">
|
||||
Domyślnie `agents.defaults.subagents.runTimeoutSeconds`, gdy ustawione, w przeciwnym razie `0`. Gdy ustawione, uruchomienie agenta podrzędnego jest przerywane po N sekundach.
|
||||
Domyślnie `agents.defaults.subagents.runTimeoutSeconds`, gdy jest ustawione, w przeciwnym razie `0`. Gdy ustawione, uruchomienie subagenta zostaje przerwane po N sekundach.
|
||||
</ParamField>
|
||||
<ParamField path="thread" type="boolean" default="false">
|
||||
Gdy `true`, żąda wiązania wątku kanału dla tej sesji agenta podrzędnego.
|
||||
Gdy `true`, żąda powiązania tej sesji subagenta z wątkiem kanału.
|
||||
</ParamField>
|
||||
<ParamField path="mode" type='"run" | "session"' default="run">
|
||||
Jeśli `thread: true` i `mode` pominięto, wartością domyślną staje się `session`. `mode: "session"` wymaga `thread: true`.
|
||||
</ParamField>
|
||||
<ParamField path="cleanup" type='"delete" | "keep"' default="keep">
|
||||
`"delete"` archiwizuje natychmiast po ogłoszeniu (nadal zachowuje transkrypt przez zmianę nazwy).
|
||||
`"delete"` archiwizuje natychmiast po ogłoszeniu (nadal zachowuje transkrypcję przez zmianę nazwy).
|
||||
</ParamField>
|
||||
<ParamField path="sandbox" type='"inherit" | "require"' default="inherit">
|
||||
`require` odrzuca utworzenie, chyba że docelowe środowisko uruchomieniowe dziecka jest w sandboxie.
|
||||
`require` odrzuca utworzenie, chyba że docelowy runtime dziecka jest w sandboxie.
|
||||
</ParamField>
|
||||
<ParamField path="context" type='"isolated" | "fork"' default="isolated">
|
||||
`fork` rozgałęzia bieżący transkrypt żądającego do sesji dziecka. Tylko natywni agenci podrzędni. Utworzenia powiązane z wątkiem domyślnie używają `fork`; utworzenia bez wątku domyślnie używają `isolated`.
|
||||
`fork` rozgałęzia bieżącą transkrypcję żądającego do sesji dziecka. Tylko natywni subagenci. Utworzenia powiązane z wątkiem domyślnie używają `fork`; utworzenia bez wątku domyślnie używają `isolated`.
|
||||
</ParamField>
|
||||
|
||||
<Warning>
|
||||
`sessions_spawn` **nie** akceptuje parametrów dostarczania kanałowego (`target`,
|
||||
`sessions_spawn` **nie** akceptuje parametrów dostarczania kanałem (`target`,
|
||||
`channel`, `to`, `threadId`, `replyTo`, `transport`). Do dostarczania użyj
|
||||
`message`/`sessions_send` z utworzonego uruchomienia.
|
||||
</Warning>
|
||||
|
||||
## Sesje powiązane z wątkiem
|
||||
|
||||
Gdy wiązania wątków są włączone dla kanału, agent podrzędny może pozostać powiązany
|
||||
Gdy powiązania z wątkiem są włączone dla kanału, subagent może pozostać powiązany
|
||||
z wątkiem, aby kolejne wiadomości użytkownika w tym wątku nadal były kierowane do
|
||||
tej samej sesji agenta podrzędnego.
|
||||
tej samej sesji subagenta.
|
||||
|
||||
### Kanały obsługujące wątki
|
||||
|
||||
**Discord** jest obecnie jedynym obsługiwanym kanałem. Obsługuje
|
||||
trwałe sesje subagentów powiązane z wątkiem (`sessions_spawn` z
|
||||
`thread: true`), ręczne kontrolki wątków (`/focus`, `/unfocus`, `/agents`,
|
||||
`thread: true`), ręczne kontrolki wątku (`/focus`, `/unfocus`, `/agents`,
|
||||
`/session idle`, `/session max-age`) oraz klucze adaptera
|
||||
`channels.discord.threadBindings.enabled`,
|
||||
`channels.discord.threadBindings.idleHours`,
|
||||
@ -216,90 +220,90 @@ trwałe sesje subagentów powiązane z wątkiem (`sessions_spawn` z
|
||||
### Szybki przepływ
|
||||
|
||||
<Steps>
|
||||
<Step title="Utwórz">
|
||||
`sessions_spawn` z `thread: true` (i opcjonalnie `mode: "session"`).
|
||||
<Step title="Utworzenie">
|
||||
`sessions_spawn` z `thread: true` (oraz opcjonalnie `mode: "session"`).
|
||||
</Step>
|
||||
<Step title="Powiąż">
|
||||
<Step title="Powiązanie">
|
||||
OpenClaw tworzy lub wiąże wątek z tym celem sesji w aktywnym kanale.
|
||||
</Step>
|
||||
<Step title="Kieruj kontynuacje">
|
||||
Odpowiedzi i kolejne wiadomości w tym wątku są kierowane do powiązanej sesji.
|
||||
<Step title="Kierowanie kontynuacji">
|
||||
Odpowiedzi i wiadomości kontynuacyjne w tym wątku są kierowane do powiązanej sesji.
|
||||
</Step>
|
||||
<Step title="Sprawdź limity czasu">
|
||||
Użyj `/session idle`, aby sprawdzić/zaktualizować automatyczne cofnięcie fokusu przy braku aktywności, oraz
|
||||
<Step title="Sprawdzenie limitów czasu">
|
||||
Użyj `/session idle`, aby sprawdzić/zaktualizować automatyczne odłączanie fokusu po bezczynności, oraz
|
||||
`/session max-age`, aby kontrolować twardy limit.
|
||||
</Step>
|
||||
<Step title="Odłącz">
|
||||
<Step title="Odłączenie">
|
||||
Użyj `/unfocus`, aby odłączyć ręcznie.
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
### Ręczne kontrolki
|
||||
### Sterowanie ręczne
|
||||
|
||||
| Polecenie | Efekt |
|
||||
| ------------------ | --------------------------------------------------------------------- |
|
||||
| `/focus <target>` | Powiąż bieżący wątek (lub utwórz nowy) z celem subagenta/sesji |
|
||||
| `/focus <target>` | Powiąż bieżący wątek (lub utwórz nowy) z celem podagenta/sesji |
|
||||
| `/unfocus` | Usuń powiązanie dla bieżącego powiązanego wątku |
|
||||
| `/agents` | Wyświetl aktywne uruchomienia i stan powiązania (`thread:<id>` lub `unbound`) |
|
||||
| `/session idle` | Sprawdź/zaktualizuj automatyczne usunięcie skupienia po bezczynności (tylko skupione powiązane wątki) |
|
||||
| `/session max-age` | Sprawdź/zaktualizuj twardy limit czasu (tylko skupione powiązane wątki) |
|
||||
| `/agents` | Wyświetl aktywne przebiegi i stan powiązania (`thread:<id>` lub `unbound`) |
|
||||
| `/session idle` | Sprawdź/zaktualizuj automatyczne odłączanie fokusu po bezczynności (tylko powiązane wątki z fokusem) |
|
||||
| `/session max-age` | Sprawdź/zaktualizuj twardy limit (tylko powiązane wątki z fokusem) |
|
||||
|
||||
### Przełączniki konfiguracji
|
||||
|
||||
- **Globalna wartość domyślna:** `session.threadBindings.enabled`, `session.threadBindings.idleHours`, `session.threadBindings.maxAgeHours`.
|
||||
- **Nadpisanie kanału i klucze automatycznego powiązania przy uruchomieniu** są specyficzne dla adaptera. Zobacz [Kanały obsługujące wątki](#thread-supporting-channels) powyżej.
|
||||
- **Nadpisanie kanału i klucze automatycznego powiązania przy tworzeniu** są specyficzne dla adaptera. Zobacz [Kanały obsługujące wątki](#thread-supporting-channels) powyżej.
|
||||
|
||||
Zobacz [Dokumentację konfiguracji](/pl/gateway/configuration-reference) i
|
||||
[Polecenia ukośnikowe](/pl/tools/slash-commands), aby poznać aktualne szczegóły adapterów.
|
||||
[Polecenia z ukośnikiem](/pl/tools/slash-commands), aby uzyskać bieżące szczegóły adaptera.
|
||||
|
||||
### Lista dozwolonych
|
||||
|
||||
<ParamField path="agents.list[].subagents.allowAgents" type="string[]">
|
||||
Lista identyfikatorów agentów, które mogą być celem przez jawne `agentId` (`["*"]` zezwala na dowolny). Domyślnie: tylko agent zgłaszający żądanie. Jeśli ustawisz listę i nadal chcesz, aby zgłaszający mógł uruchamiać samego siebie z `agentId`, uwzględnij identyfikator zgłaszającego na liście.
|
||||
Lista identyfikatorów agentów, które mogą być celem przez jawne `agentId` (`["*"]` zezwala na dowolny). Domyślnie: tylko agent wywołujący. Jeśli ustawisz listę i nadal chcesz, aby agent wywołujący tworzył samego siebie z `agentId`, uwzględnij identyfikator agenta wywołującego na liście.
|
||||
</ParamField>
|
||||
<ParamField path="agents.defaults.subagents.allowAgents" type="string[]">
|
||||
Domyślna lista dozwolonych agentów docelowych używana, gdy agent zgłaszający żądanie nie ustawi własnego `subagents.allowAgents`.
|
||||
Domyślna lista dozwolonych agentów docelowych używana, gdy agent wywołujący nie ustawia własnego `subagents.allowAgents`.
|
||||
</ParamField>
|
||||
<ParamField path="agents.defaults.subagents.requireAgentId" type="boolean" default="false">
|
||||
Blokuj wywołania `sessions_spawn`, które pomijają `agentId` (wymusza jawny wybór profilu). Nadpisanie dla agenta: `agents.list[].subagents.requireAgentId`.
|
||||
</ParamField>
|
||||
|
||||
Jeśli sesja zgłaszającego działa w piaskownicy, `sessions_spawn` odrzuca cele,
|
||||
które działałyby poza piaskownicą.
|
||||
Jeśli sesja wywołująca jest objęta piaskownicą, `sessions_spawn` odrzuca cele,
|
||||
które działałyby bez piaskownicy.
|
||||
|
||||
### Wykrywanie
|
||||
|
||||
Użyj `agents_list`, aby zobaczyć, które identyfikatory agentów są obecnie dozwolone dla
|
||||
`sessions_spawn`. Odpowiedź zawiera efektywny model każdego wymienionego agenta
|
||||
oraz osadzone metadane środowiska uruchomieniowego, dzięki czemu wywołujący mogą odróżnić PI, serwer aplikacji Codex
|
||||
i inne skonfigurowane natywne środowiska uruchomieniowe.
|
||||
oraz osadzone metadane środowiska wykonawczego, aby wywołujący mogli odróżnić PI, serwer aplikacji Codex
|
||||
i inne skonfigurowane natywne środowiska wykonawcze.
|
||||
|
||||
### Automatyczna archiwizacja
|
||||
|
||||
- Sesje subagentów są automatycznie archiwizowane po `agents.defaults.subagents.archiveAfterMinutes` (domyślnie `60`).
|
||||
- Archiwizacja używa `sessions.delete` i zmienia nazwę transkryptu na `*.deleted.<timestamp>` (ten sam folder).
|
||||
- `cleanup: "delete"` archiwizuje natychmiast po ogłoszeniu (nadal zachowuje transkrypt przez zmianę nazwy).
|
||||
- Automatyczna archiwizacja działa w trybie najlepszych starań; oczekujące timery zostają utracone, jeśli Gateway zostanie uruchomiony ponownie.
|
||||
- `runTimeoutSeconds` **nie** archiwizuje automatycznie; tylko zatrzymuje uruchomienie. Sesja pozostaje do czasu automatycznej archiwizacji.
|
||||
- Automatyczna archiwizacja dotyczy tak samo sesji na głębokości 1 i 2.
|
||||
- Czyszczenie przeglądarki jest oddzielne od czyszczenia archiwum: śledzone karty/procesy przeglądarki są zamykane w trybie najlepszych starań po zakończeniu uruchomienia, nawet jeśli transkrypt/rekord sesji zostaje zachowany.
|
||||
- Sesje podagentów są automatycznie archiwizowane po `agents.defaults.subagents.archiveAfterMinutes` (domyślnie `60`).
|
||||
- Archiwizacja używa `sessions.delete` i zmienia nazwę transkrypcji na `*.deleted.<timestamp>` (ten sam folder).
|
||||
- `cleanup: "delete"` archiwizuje natychmiast po zgłoszeniu (nadal zachowuje transkrypcję przez zmianę nazwy).
|
||||
- Automatyczna archiwizacja działa w trybie best-effort; oczekujące timery są tracone, jeśli Gateway zostanie uruchomiony ponownie.
|
||||
- `runTimeoutSeconds` **nie** archiwizuje automatycznie; tylko zatrzymuje przebieg. Sesja pozostaje do czasu automatycznej archiwizacji.
|
||||
- Automatyczna archiwizacja dotyczy tak samo sesji głębokości 1 i głębokości 2.
|
||||
- Czyszczenie przeglądarki jest oddzielne od czyszczenia archiwum: śledzone karty/procesy przeglądarki są zamykane w trybie best-effort po zakończeniu przebiegu, nawet jeśli rekord transkrypcji/sesji zostaje zachowany.
|
||||
|
||||
## Zagnieżdżone subagenty
|
||||
## Zagnieżdżone podagenty
|
||||
|
||||
Domyślnie subagenty nie mogą uruchamiać własnych subagentów
|
||||
Domyślnie podagenci nie mogą tworzyć własnych podagentów
|
||||
(`maxSpawnDepth: 1`). Ustaw `maxSpawnDepth: 2`, aby włączyć jeden poziom
|
||||
zagnieżdżenia — **wzorzec orkiestratora**: główny → subagent orkiestrujący →
|
||||
subsubagenci wykonawczy.
|
||||
zagnieżdżenia — **wzorzec orkiestratora**: główny → podagent orkiestrator →
|
||||
podagenci-pracownicy drugiego poziomu.
|
||||
|
||||
```json5
|
||||
{
|
||||
agents: {
|
||||
defaults: {
|
||||
subagents: {
|
||||
maxSpawnDepth: 2, // zezwól subagentom na uruchamianie dzieci (domyślnie: 1)
|
||||
maxChildrenPerAgent: 5, // maks. aktywnych dzieci na sesję agenta (domyślnie: 5)
|
||||
maxConcurrent: 8, // globalny limit równoległych pasów (domyślnie: 8)
|
||||
runTimeoutSeconds: 900, // domyślny limit czasu dla sessions_spawn, gdy pominięty (0 = bez limitu czasu)
|
||||
maxSpawnDepth: 2, // allow sub-agents to spawn children (default: 1)
|
||||
maxChildrenPerAgent: 5, // max active children per agent session (default: 5)
|
||||
maxConcurrent: 8, // global concurrency lane cap (default: 8)
|
||||
runTimeoutSeconds: 900, // default timeout for sessions_spawn when omitted (0 = no timeout)
|
||||
},
|
||||
},
|
||||
},
|
||||
@ -308,43 +312,44 @@ subsubagenci wykonawczy.
|
||||
|
||||
### Poziomy głębokości
|
||||
|
||||
| Głębokość | Kształt klucza sesji | Rola | Może uruchamiać? |
|
||||
| Głębokość | Kształt klucza sesji | Rola | Może tworzyć? |
|
||||
| --------- | -------------------------------------------- | --------------------------------------------- | ---------------------------- |
|
||||
| 0 | `agent:<id>:main` | Agent główny | Zawsze |
|
||||
| 1 | `agent:<id>:subagent:<uuid>` | Subagent (orkiestrator, gdy dozwolona głębokość 2) | Tylko jeśli `maxSpawnDepth >= 2` |
|
||||
| 2 | `agent:<id>:subagent:<uuid>:subagent:<uuid>` | Subsubagent (wykonawca liść) | Nigdy |
|
||||
| 1 | `agent:<id>:subagent:<uuid>` | Podagent (orkiestrator, gdy głębokość 2 jest dozwolona) | Tylko jeśli `maxSpawnDepth >= 2` |
|
||||
| 2 | `agent:<id>:subagent:<uuid>:subagent:<uuid>` | Podagent drugiego poziomu (pracownik końcowy) | Nigdy |
|
||||
|
||||
### Łańcuch ogłoszeń
|
||||
### Łańcuch zgłoszeń
|
||||
|
||||
Wyniki przepływają w górę łańcucha:
|
||||
Wyniki przepływają z powrotem w górę łańcucha:
|
||||
|
||||
1. Wykonawca z głębokości 2 kończy → ogłasza wynik rodzicowi (orkiestratorowi z głębokości 1).
|
||||
2. Orkiestrator z głębokości 1 odbiera ogłoszenie, syntetyzuje wyniki, kończy → ogłasza do głównego.
|
||||
3. Agent główny odbiera ogłoszenie i dostarcza je użytkownikowi.
|
||||
1. Pracownik głębokości 2 kończy → zgłasza do swojego rodzica (orkiestratora głębokości 1).
|
||||
2. Orkiestrator głębokości 1 odbiera zgłoszenie, syntetyzuje wyniki, kończy → zgłasza do głównego.
|
||||
3. Agent główny odbiera zgłoszenie i dostarcza je użytkownikowi.
|
||||
|
||||
Każdy poziom widzi tylko ogłoszenia od swoich bezpośrednich dzieci.
|
||||
Każdy poziom widzi tylko zgłoszenia od swoich bezpośrednich dzieci.
|
||||
|
||||
<Note>
|
||||
**Wytyczne operacyjne:** uruchamiaj pracę dziecka raz i czekaj na zdarzenia
|
||||
zakończenia zamiast budować pętle odpytywania wokół `sessions_list`,
|
||||
`sessions_history`, `/subagents list` lub poleceń `exec` z uśpieniem.
|
||||
**Wskazówki operacyjne:** uruchamiaj pracę dzieci raz i czekaj na zdarzenia
|
||||
ukończenia zamiast budować pętle odpytywania wokół `sessions_list`,
|
||||
`sessions_history`, `/subagents list` lub poleceń uśpienia `exec`.
|
||||
`sessions_list` i `/subagents list` utrzymują relacje sesji dzieci
|
||||
skupione na pracy na żywo — aktywne dzieci pozostają podłączone, zakończone dzieci pozostają
|
||||
widoczne przez krótki ostatni okres, a przestarzałe linki dzieci istniejące tylko w magazynie są
|
||||
ignorowane po upływie ich okna świeżości. Zapobiega to wskrzeszaniu widmowych dzieci przez stare metadane `spawnedBy` /
|
||||
`parentSessionKey` po ponownym uruchomieniu. Jeśli zdarzenie zakończenia dziecka nadejdzie po wysłaniu
|
||||
ostatecznej odpowiedzi, poprawną odpowiedzią uzupełniającą jest dokładny cichy token
|
||||
skupione na pracy na żywo — aktywne dzieci pozostają dołączone, zakończone dzieci pozostają
|
||||
widoczne przez krótkie ostatnie okno, a nieaktualne linki dzieci istniejące tylko w magazynie są
|
||||
ignorowane po upływie ich okna świeżości. Zapobiega to wskrzeszaniu przez stare metadane `spawnedBy` /
|
||||
`parentSessionKey` widmowych dzieci po
|
||||
ponownym uruchomieniu. Jeśli zdarzenie ukończenia dziecka nadejdzie po wysłaniu
|
||||
ostatecznej odpowiedzi, poprawną kontynuacją jest dokładny cichy token
|
||||
`NO_REPLY` / `no_reply`.
|
||||
</Note>
|
||||
|
||||
### Zasady narzędzi według głębokości
|
||||
|
||||
- Rola i zakres kontroli są zapisywane w metadanych sesji w momencie uruchomienia. Dzięki temu płaskie lub odtworzone klucze sesji nie odzyskują przypadkowo uprawnień orkiestratora.
|
||||
- **Głębokość 1 (orkiestrator, gdy `maxSpawnDepth >= 2`):** otrzymuje `sessions_spawn`, `subagents`, `sessions_list`, `sessions_history`, aby mógł zarządzać swoimi dziećmi. Inne narzędzia sesji/systemowe pozostają zabronione.
|
||||
- **Głębokość 1 (liść, gdy `maxSpawnDepth == 1`):** brak narzędzi sesji (obecne zachowanie domyślne).
|
||||
- **Głębokość 2 (wykonawca liść):** brak narzędzi sesji — `sessions_spawn` jest zawsze zabronione na głębokości 2. Nie może uruchamiać kolejnych dzieci.
|
||||
- Rola i zakres sterowania są zapisywane w metadanych sesji w momencie tworzenia. Dzięki temu płaskie lub odtworzone klucze sesji nie odzyskują przypadkowo uprawnień orkiestratora.
|
||||
- **Głębokość 1 (orkiestrator, gdy `maxSpawnDepth >= 2`):** otrzymuje `sessions_spawn`, `subagents`, `sessions_list`, `sessions_history`, aby mógł zarządzać swoimi dziećmi. Inne narzędzia sesji/systemowe pozostają odrzucone.
|
||||
- **Głębokość 1 (liść, gdy `maxSpawnDepth == 1`):** brak narzędzi sesji (bieżące zachowanie domyślne).
|
||||
- **Głębokość 2 (pracownik końcowy):** brak narzędzi sesji — `sessions_spawn` jest zawsze odrzucane na głębokości 2. Nie może tworzyć kolejnych dzieci.
|
||||
|
||||
### Limit uruchomień na agenta
|
||||
### Limit tworzenia na agenta
|
||||
|
||||
Każda sesja agenta (na dowolnej głębokości) może mieć jednocześnie najwyżej `maxChildrenPerAgent`
|
||||
(domyślnie `5`) aktywnych dzieci. Zapobiega to niekontrolowanemu rozgałęzianiu
|
||||
@ -352,108 +357,103 @@ z jednego orkiestratora.
|
||||
|
||||
### Kaskadowe zatrzymanie
|
||||
|
||||
Zatrzymanie orkiestratora z głębokości 1 automatycznie zatrzymuje wszystkie jego dzieci
|
||||
z głębokości 2:
|
||||
Zatrzymanie orkiestratora głębokości 1 automatycznie zatrzymuje wszystkie jego dzieci
|
||||
głębokości 2:
|
||||
|
||||
- `/stop` w głównym czacie zatrzymuje wszystkich agentów z głębokości 1 i kaskadowo zatrzymuje ich dzieci z głębokości 2.
|
||||
- `/subagents kill <id>` zatrzymuje konkretnego subagenta i kaskadowo zatrzymuje jego dzieci.
|
||||
- `/subagents kill all` zatrzymuje wszystkich subagentów zgłaszającego i uruchamia kaskadę.
|
||||
- `/stop` w głównym czacie zatrzymuje wszystkich agentów głębokości 1 i kaskadowo zatrzymuje ich dzieci głębokości 2.
|
||||
- `/subagents kill <id>` zatrzymuje konkretnego podagenta i kaskadowo zatrzymuje jego dzieci.
|
||||
- `/subagents kill all` zatrzymuje wszystkich podagentów dla wywołującego i wykonuje kaskadę.
|
||||
|
||||
## Uwierzytelnianie
|
||||
|
||||
Uwierzytelnianie subagenta jest rozstrzygane według **identyfikatora agenta**, a nie typu sesji:
|
||||
Uwierzytelnianie podagenta jest rozwiązywane według **identyfikatora agenta**, a nie według typu sesji:
|
||||
|
||||
- Klucz sesji subagenta to `agent:<agentId>:subagent:<uuid>`.
|
||||
- Klucz sesji podagenta to `agent:<agentId>:subagent:<uuid>`.
|
||||
- Magazyn uwierzytelniania jest ładowany z `agentDir` tego agenta.
|
||||
- Profile uwierzytelniania agenta głównego są scalane jako **fallback**; profile agenta nadpisują profile główne w przypadku konfliktów.
|
||||
- Profile uwierzytelniania agenta głównego są scalane jako **fallback**; profile agenta zastępują profile główne w przypadku konfliktów.
|
||||
|
||||
Scalanie jest addytywne, więc profile główne są zawsze dostępne jako
|
||||
fallbacki. W pełni izolowane uwierzytelnianie na agenta nie jest jeszcze obsługiwane.
|
||||
fallbacki. W pełni izolowane uwierzytelnianie dla każdego agenta nie jest jeszcze obsługiwane.
|
||||
|
||||
## Ogłoszenie
|
||||
## Zgłoszenie
|
||||
|
||||
Subagenty zgłaszają wyniki przez krok ogłoszenia:
|
||||
Podagenci raportują z powrotem przez krok zgłoszenia:
|
||||
|
||||
- Krok ogłoszenia działa wewnątrz sesji subagenta (nie w sesji zgłaszającego).
|
||||
- Jeśli subagent odpowie dokładnie `ANNOUNCE_SKIP`, nic nie zostanie opublikowane.
|
||||
- Jeśli najnowszy tekst asystenta to dokładny cichy token `NO_REPLY` / `no_reply`, wynik ogłoszenia jest tłumiony, nawet jeśli wcześniej istniał widoczny postęp.
|
||||
- Krok zgłoszenia działa wewnątrz sesji podagenta (nie w sesji wywołującej).
|
||||
- Jeśli podagent odpowie dokładnie `ANNOUNCE_SKIP`, nic nie zostanie opublikowane.
|
||||
- Jeśli najnowszy tekst asystenta jest dokładnym cichym tokenem `NO_REPLY` / `no_reply`, wynik zgłoszenia jest tłumiony nawet wtedy, gdy wcześniej istniał widoczny postęp.
|
||||
|
||||
Dostarczenie zależy od głębokości zgłaszającego:
|
||||
Dostarczenie zależy od głębokości wywołującego:
|
||||
|
||||
- Sesje zgłaszającego najwyższego poziomu używają uzupełniającego wywołania `agent` z dostarczaniem zewnętrznym (`deliver=true`).
|
||||
- Zagnieżdżone sesje subagenta zgłaszającego otrzymują wewnętrzne wstrzyknięcie uzupełniające (`deliver=false`), aby orkiestrator mógł syntetyzować wyniki dzieci w sesji.
|
||||
- Jeśli zagnieżdżona sesja subagenta zgłaszającego zniknie, OpenClaw wraca do zgłaszającego tej sesji, gdy jest dostępny.
|
||||
- Sesje wywołujące najwyższego poziomu używają kontynuacyjnego wywołania `agent` z dostarczeniem zewnętrznym (`deliver=true`).
|
||||
- Zagnieżdżone sesje podagentów wywołujących otrzymują wewnętrzne wstrzyknięcie kontynuacji (`deliver=false`), aby orkiestrator mógł syntetyzować wyniki dzieci w sesji.
|
||||
- Jeśli zagnieżdżona sesja podagenta wywołującego zniknęła, OpenClaw wraca do wywołującego tej sesji, gdy jest dostępny.
|
||||
|
||||
W przypadku sesji zgłaszającego najwyższego poziomu bezpośrednie dostarczanie w trybie ukończenia najpierw
|
||||
rozwiązuje dowolną powiązaną trasę rozmowy/wątku i nadpisanie hooka, a następnie uzupełnia
|
||||
brakujące pola celu kanału z zapisanej trasy sesji zgłaszającego.
|
||||
Dzięki temu ukończenia trafiają na właściwy czat/temat nawet wtedy, gdy źródło ukończenia
|
||||
Dla sesji wywołujących najwyższego poziomu bezpośrednie dostarczanie w trybie ukończenia najpierw
|
||||
rozwiązuje dowolną powiązaną trasę rozmowy/wątku i nadpisanie haka, a następnie wypełnia
|
||||
brakujące pola celu kanału z zapisanej trasy sesji wywołującej.
|
||||
Dzięki temu ukończenia trafiają do właściwego czatu/tematu nawet wtedy, gdy źródło ukończenia
|
||||
identyfikuje tylko kanał.
|
||||
|
||||
Agregacja ukończeń dzieci jest ograniczona do bieżącego uruchomienia zgłaszającego podczas
|
||||
tworzenia wyników zagnieżdżonych ukończeń, co zapobiega przeciekaniu przestarzałych wyników dzieci
|
||||
z wcześniejszych uruchomień do bieżącego ogłoszenia. Odpowiedzi ogłoszeń zachowują
|
||||
Agregacja ukończeń dzieci jest zawężona do bieżącego przebiegu wywołującego podczas
|
||||
budowania zagnieżdżonych ustaleń ukończenia, co zapobiega wyciekowi nieaktualnych wyników dzieci z wcześniejszych przebiegów
|
||||
do bieżącego zgłoszenia. Odpowiedzi zgłoszeń zachowują
|
||||
trasowanie wątku/tematu, gdy jest dostępne w adapterach kanałów.
|
||||
|
||||
### Kontekst ogłoszenia
|
||||
### Kontekst zgłoszenia
|
||||
|
||||
Kontekst ogłoszenia jest normalizowany do stabilnego wewnętrznego bloku zdarzenia:
|
||||
Kontekst zgłoszenia jest normalizowany do stabilnego wewnętrznego bloku zdarzenia:
|
||||
|
||||
| Pole | Źródło |
|
||||
| -------------- | ------------------------------------------------------------------------------------------------------------- |
|
||||
| Źródło | `subagent` lub `cron` |
|
||||
| Identyfikatory sesji | Klucz/id sesji dziecka |
|
||||
| Typ | Typ ogłoszenia + etykieta zadania |
|
||||
| Status | Pochodny od wyniku środowiska uruchomieniowego (`success`, `error`, `timeout` lub `unknown`) — **nie** wnioskowany z tekstu modelu |
|
||||
| Typ | Typ zgłoszenia + etykieta zadania |
|
||||
| Status | Pochodzi z wyniku środowiska wykonawczego (`success`, `error`, `timeout` lub `unknown`) — **nie** jest wnioskowany z tekstu modelu |
|
||||
| Treść wyniku | Najnowszy widoczny tekst asystenta, w przeciwnym razie oczyszczony najnowszy tekst narzędzia/toolResult |
|
||||
| Dalsza odpowiedź | Instrukcja opisująca, kiedy odpowiedzieć, a kiedy pozostać cicho |
|
||||
| Kontynuacja | Instrukcja opisująca, kiedy odpowiedzieć, a kiedy zachować ciszę |
|
||||
|
||||
Końcowe nieudane uruchomienia zgłaszają status niepowodzenia bez odtwarzania przechwyconego
|
||||
tekstu odpowiedzi. Przy przekroczeniu limitu czasu, jeśli dziecko dotarło tylko do wywołań narzędzi, ogłoszenie
|
||||
Końcowe nieudane przebiegi raportują status niepowodzenia bez odtwarzania przechwyconego
|
||||
tekstu odpowiedzi. W przypadku przekroczenia limitu czasu, jeśli dziecko przeszło tylko przez wywołania narzędzi, zgłoszenie
|
||||
może zwinąć tę historię do krótkiego podsumowania częściowego postępu zamiast
|
||||
odtwarzać surowy wynik narzędzia.
|
||||
|
||||
### Wiersz statystyk
|
||||
|
||||
Ładunki ogłoszeń zawierają wiersz statystyk na końcu (nawet po zawinięciu):
|
||||
Ładunki zgłoszeń zawierają na końcu wiersz statystyk (nawet po zawinięciu):
|
||||
|
||||
- Czas działania (np. `runtime 5m12s`).
|
||||
- Użycie tokenów (wejście/wyjście/łącznie).
|
||||
- Szacowany koszt, gdy skonfigurowano ceny modeli (`models.providers.*.models[].cost`).
|
||||
- `sessionKey`, `sessionId` i ścieżka transkryptu, aby agent główny mógł pobrać historię przez `sessions_history` lub sprawdzić plik na dysku.
|
||||
- `sessionKey`, `sessionId` i ścieżka transkrypcji, aby agent główny mógł pobrać historię przez `sessions_history` lub sprawdzić plik na dysku.
|
||||
|
||||
Metadane wewnętrzne są przeznaczone tylko do orkiestracji; odpowiedzi skierowane do użytkownika
|
||||
należy przepisać normalnym głosem asystenta.
|
||||
powinny zostać przepisane normalnym głosem asystenta.
|
||||
|
||||
### Dlaczego preferować `sessions_history`
|
||||
|
||||
`sessions_history` to bezpieczniejsza ścieżka orkiestracji:
|
||||
`sessions_history` jest bezpieczniejszą ścieżką orkiestracji:
|
||||
|
||||
- Pamięć asystenta jest najpierw normalizowana: tagi myślenia usuwane; rusztowanie `<relevant-memories>` / `<relevant_memories>` usuwane; bloki ładunku XML wywołań narzędzi w zwykłym tekście (`<tool_call>`, `<function_call>`, `<tool_calls>`, `<function_calls>`) usuwane, w tym ucięte ładunki, które nigdy nie zamykają się poprawnie; zdegradowane rusztowanie wywołań/wyników narzędzi oraz znaczniki kontekstu historycznego usuwane; wyciekłe tokeny sterujące modelu (`<|assistant|>`, inne ASCII `<|...|>`, pełnoszerokościowe `<｜...｜>`) usuwane; niepoprawny XML wywołań narzędzi MiniMax usuwany.
|
||||
- Przywołanie asystenta jest najpierw normalizowane: tagi myślenia są usuwane; rusztowanie `<relevant-memories>` / `<relevant_memories>` jest usuwane; bloki ładunku XML wywołań narzędzi w zwykłym tekście (`<tool_call>`, `<function_call>`, `<tool_calls>`, `<function_calls>`) są usuwane, w tym obcięte ładunki, które nigdy nie zamykają się poprawnie; zdegradowane rusztowanie wywołań/wyników narzędzi oraz znaczniki kontekstu historycznego są usuwane; wyciekłe tokeny sterowania modelu (`<|assistant|>`, inne ASCII `<|...|>`, pełnej szerokości `<｜...｜>`) są usuwane; niepoprawny XML wywołań narzędzi MiniMax jest usuwany.
|
||||
- Tekst przypominający dane uwierzytelniające/tokeny jest redagowany.
|
||||
- Długie bloki mogą zostać ucięte.
|
||||
- Bardzo duże historie mogą usuwać starsze wiersze lub zastąpić nadmiernie duży wiersz komunikatem `[sessions_history omitted: message too large]`.
|
||||
- Surowa inspekcja transkryptu na dysku jest fallbackiem, gdy potrzebujesz pełnego transkryptu bajt w bajt.
|
||||
- Długie bloki mogą być obcinane.
|
||||
- Bardzo duże historie mogą porzucać starsze wiersze lub zastępować zbyt duży wiersz tekstem `[sessions_history omitted: message too large]`.
|
||||
- Surowa inspekcja transkrypcji na dysku jest fallbackiem, gdy potrzebujesz pełnej transkrypcji bajt w bajt.
|
||||
|
||||
## Zasady narzędzi
|
||||
|
||||
Subagenty najpierw używają tego samego profilu i potoku zasad narzędzi co rodzic lub
|
||||
agent docelowy. Następnie OpenClaw stosuje warstwę ograniczeń subagenta.
|
||||
Podagenci najpierw używają tego samego profilu i potoku zasad narzędzi co agent nadrzędny lub docelowy. Następnie OpenClaw stosuje warstwę ograniczeń podagentów.
|
||||
|
||||
Bez restrykcyjnego `tools.profile` subagenty otrzymują **wszystkie narzędzia z wyjątkiem
|
||||
narzędzi sesji** i narzędzi systemowych:
|
||||
Bez ograniczającego `tools.profile` podagenci otrzymują **wszystkie narzędzia oprócz narzędzi sesji** i narzędzi systemowych:
|
||||
|
||||
- `sessions_list`
|
||||
- `sessions_history`
|
||||
- `sessions_send`
|
||||
- `sessions_spawn`
|
||||
|
||||
`sessions_history` także tutaj pozostaje ograniczonym, oczyszczonym widokiem przypominania —
|
||||
nie jest surowym zrzutem transkryptu.
|
||||
`sessions_history` także tutaj pozostaje ograniczonym, oczyszczonym widokiem przywołania — nie jest surowym zrzutem transkryptu.
|
||||
|
||||
Gdy `maxSpawnDepth >= 2`, subagenty orkiestrujące na głębokości 1 dodatkowo
|
||||
otrzymują `sessions_spawn`, `subagents`, `sessions_list` i
|
||||
`sessions_history`, aby mogły zarządzać swoimi dziećmi.
|
||||
Gdy `maxSpawnDepth >= 2`, podagenci-orkiestratorzy na głębokości 1 dodatkowo otrzymują `sessions_spawn`, `subagents`, `sessions_list` i `sessions_history`, aby mogli zarządzać swoimi dziećmi.
|
||||
|
||||
### Nadpisanie przez konfigurację
|
||||
|
||||
@ -469,9 +469,9 @@ otrzymują `sessions_spawn`, `subagents`, `sessions_list` i
|
||||
tools: {
|
||||
subagents: {
|
||||
tools: {
|
||||
// deny wins
|
||||
// deny ma pierwszeństwo
|
||||
deny: ["gateway", "cron"],
|
||||
// if allow is set, it becomes allow-only (deny still wins)
|
||||
// jeśli ustawiono allow, staje się listą wyłącznie dozwolonych (deny nadal ma pierwszeństwo)
|
||||
// allow: ["read", "exec", "process"]
|
||||
},
|
||||
},
|
||||
@ -479,12 +479,7 @@ otrzymują `sessions_spawn`, `subagents`, `sessions_list` i
|
||||
}
|
||||
```
|
||||
|
||||
`tools.subagents.tools.allow` to końcowy filtr typu allow-only. Może zawęzić
|
||||
już rozstrzygnięty zestaw narzędzi, ale nie może **dodać z powrotem** narzędzia usuniętego
|
||||
przez `tools.profile`. Na przykład `tools.profile: "coding"` zawiera
|
||||
`web_search`/`web_fetch`, ale nie narzędzie `browser`. Aby umożliwić
|
||||
podagentom profilu coding używanie automatyzacji przeglądarki, dodaj browser na
|
||||
etapie profilu:
|
||||
`tools.subagents.tools.allow` to końcowy filtr wyłącznie dozwolonych narzędzi. Może zawęzić już rozstrzygnięty zestaw narzędzi, ale nie może **przywrócić** narzędzia usuniętego przez `tools.profile`. Na przykład `tools.profile: "coding"` obejmuje `web_search`/`web_fetch`, ale nie narzędzie `browser`. Aby pozwolić podagentom z profilem coding używać automatyzacji przeglądarki, dodaj browser na etapie profilu:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -495,64 +490,44 @@ etapie profilu:
|
||||
}
|
||||
```
|
||||
|
||||
Użyj `agents.list[].tools.alsoAllow: ["browser"]` dla poszczególnego agenta, gdy tylko jeden
|
||||
agent powinien otrzymać automatyzację przeglądarki.
|
||||
Użyj `agents.list[].tools.alsoAllow: ["browser"]` dla konkretnego agenta, gdy tylko jeden agent powinien otrzymać automatyzację przeglądarki.
|
||||
|
||||
## Współbieżność
|
||||
|
||||
Podagenci używają dedykowanej kolejki działającej w tym samym procesie:
|
||||
Podagenci używają dedykowanej kolejki w procesie:
|
||||
|
||||
- **Nazwa kolejki:** `subagent`
|
||||
- **Współbieżność:** `agents.defaults.subagents.maxConcurrent` (domyślnie `8`)
|
||||
|
||||
## Żywotność i odzyskiwanie
|
||||
|
||||
OpenClaw nie traktuje braku `endedAt` jako trwałego dowodu, że
|
||||
podagent nadal działa. Niezakończone uruchomienia starsze niż okno przestarzałego uruchomienia
|
||||
przestają być liczone jako aktywne/oczekujące w `/subagents list`, podsumowaniach statusu,
|
||||
bramkowaniu ukończenia potomków oraz sprawdzeniach współbieżności dla sesji.
|
||||
OpenClaw nie traktuje braku `endedAt` jako trwałego dowodu, że podagent nadal działa. Niezakończone uruchomienia starsze niż okno nieaktualnego uruchomienia przestają liczyć się jako aktywne/oczekujące w `/subagents list`, podsumowaniach statusu, bramkowaniu ukończenia potomków i kontrolach współbieżności na sesję.
|
||||
|
||||
Po ponownym uruchomieniu Gateway przestarzałe, niezakończone odtworzone uruchomienia są przycinane, chyba że
|
||||
ich sesja podrzędna jest oznaczona jako `abortedLastRun: true`. Te
|
||||
sesje podrzędne przerwane przez restart pozostają możliwe do odzyskania przez przepływ odzyskiwania osieroconego podagenta, który wysyła syntetyczną wiadomość wznowienia przed
|
||||
wyczyszczeniem znacznika przerwania.
|
||||
Po ponownym uruchomieniu Gateway nieaktualne, niezakończone, odtworzone uruchomienia są usuwane, chyba że ich sesja potomna jest oznaczona jako `abortedLastRun: true`. Te przerwane przez restart sesje potomne pozostają możliwe do odzyskania przez przepływ odzyskiwania osieroconych podagentów, który wysyła syntetyczną wiadomość wznowienia przed wyczyszczeniem znacznika przerwania.
|
||||
|
||||
Automatyczne odzyskiwanie po restarcie jest ograniczone dla każdej sesji podrzędnej. Jeśli ten sam
|
||||
podagent podrzędny jest wielokrotnie akceptowany do odzyskiwania osieroconego uruchomienia w obrębie
|
||||
okna szybkiego ponownego zakleszczenia, OpenClaw utrwala na tej
|
||||
sesji znacznik tombstone odzyskiwania i przestaje automatycznie wznawiać ją po późniejszych restartach. Uruchom
|
||||
`openclaw tasks maintenance --apply`, aby uzgodnić rekord zadania, albo
|
||||
`openclaw doctor --fix`, aby wyczyścić przestarzałe flagi przerwanego odzyskiwania w
|
||||
sesjach oznaczonych tombstone.
|
||||
Automatyczne odzyskiwanie po restarcie jest ograniczone dla każdej sesji potomnej. Jeśli to samo dziecko podagenta jest wielokrotnie akceptowane do odzyskiwania osierocenia w oknie szybkiego ponownego zakleszczenia, OpenClaw zapisuje tombstone odzyskiwania w tej sesji i przestaje automatycznie wznawiać ją przy kolejnych restartach. Uruchom `openclaw tasks maintenance --apply`, aby uzgodnić rekord zadania, lub `openclaw doctor --fix`, aby wyczyścić nieaktualne flagi przerwanego odzyskiwania w sesjach z tombstone.
|
||||
|
||||
<Note>
|
||||
Jeśli uruchomienie podagenta nie powiedzie się z Gateway `PAIRING_REQUIRED` /
|
||||
`scope-upgrade`, sprawdź wywołującego RPC przed edytowaniem stanu parowania.
|
||||
Wewnętrzna koordynacja `sessions_spawn` powinna łączyć się jako
|
||||
`client.id: "gateway-client"` z `client.mode: "backend"` przez bezpośrednie
|
||||
uwierzytelnianie local loopback współdzielonym tokenem/hasłem; ta ścieżka nie zależy od
|
||||
bazowego zakresu sparowanego urządzenia CLI. Zdalni wywołujący, jawne
|
||||
`deviceIdentity`, jawne ścieżki tokenu urządzenia oraz klienci przeglądarkowi/node
|
||||
nadal wymagają normalnego zatwierdzenia urządzenia dla podniesienia zakresu.
|
||||
Jeśli utworzenie podagenta kończy się niepowodzeniem z Gateway `PAIRING_REQUIRED` / `scope-upgrade`, sprawdź wywołującego RPC przed edycją stanu parowania. Wewnętrzna koordynacja `sessions_spawn` powinna łączyć się jako `client.id: "gateway-client"` z `client.mode: "backend"` przez bezpośrednie uwierzytelnianie współdzielonym tokenem/hasłem przez local loopback; ta ścieżka nie zależy od bazowego zakresu sparowanego urządzenia CLI. Zdalni wywołujący, jawne `deviceIdentity`, jawne ścieżki tokenów urządzeń oraz klienci browser/node nadal wymagają normalnego zatwierdzenia urządzenia dla rozszerzeń zakresu.
|
||||
</Note>
|
||||
|
||||
## Zatrzymywanie
|
||||
|
||||
- Wysłanie `/stop` na czacie żądającego przerywa sesję żądającego i zatrzymuje wszystkie aktywne uruchomienia podagentów wywołane z niej, kaskadowo obejmując zagnieżdżone dzieci.
|
||||
- `/subagents kill <id>` zatrzymuje konkretnego podagenta i kaskadowo zatrzymuje jego dzieci.
|
||||
- Wysłanie `/stop` na czacie żądającego przerywa sesję żądającego i zatrzymuje wszystkie aktywne uruchomienia podagentów utworzone z niej, kaskadowo obejmując zagnieżdżone dzieci.
|
||||
- `/subagents kill <id>` zatrzymuje określonego podagenta i kaskadowo zatrzymuje jego dzieci.
|
||||
|
||||
## Ograniczenia
|
||||
|
||||
- Ogłaszanie podagenta działa na zasadzie **best-effort**. Jeśli gateway zostanie ponownie uruchomiony, oczekująca praca typu „announce back” zostanie utracona.
|
||||
- Podagenci nadal współdzielą te same zasoby procesu gateway; traktuj `maxConcurrent` jako zawór bezpieczeństwa.
|
||||
- Ogłaszanie podagenta działa na zasadzie **best-effort**. Jeśli Gateway uruchomi się ponownie, oczekująca praca „announce back” zostanie utracona.
|
||||
- Podagenci nadal współdzielą te same zasoby procesu Gateway; traktuj `maxConcurrent` jako zawór bezpieczeństwa.
|
||||
- `sessions_spawn` jest zawsze nieblokujące: natychmiast zwraca `{ status: "accepted", runId, childSessionKey }`.
|
||||
- Kontekst podagenta wstrzykuje tylko `AGENTS.md` + `TOOLS.md` (bez `SOUL.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md` ani `BOOTSTRAP.md`).
|
||||
- Maksymalna głębokość zagnieżdżenia to 5 (zakres `maxSpawnDepth`: 1–5). Dla większości przypadków użycia zalecana jest głębokość 2.
|
||||
- Maksymalna głębokość zagnieżdżenia wynosi 5 (zakres `maxSpawnDepth`: 1–5). Głębokość 2 jest zalecana dla większości przypadków użycia.
|
||||
- `maxChildrenPerAgent` ogranicza liczbę aktywnych dzieci na sesję (domyślnie `5`, zakres `1–20`).
|
||||
|
||||
## Powiązane
|
||||
|
||||
- [Agenci ACP](/pl/tools/acp-agents)
|
||||
- [Wysyłanie do agenta](/pl/tools/agent-send)
|
||||
- [Wysyłanie agenta](/pl/tools/agent-send)
|
||||
- [Zadania w tle](/pl/automation/tasks)
|
||||
- [Narzędzia piaskownicy wieloagentowej](/pl/tools/multi-agent-sandbox-tools)
|
||||
|
||||
@ -1,20 +1,20 @@
|
||||
---
|
||||
read_when:
|
||||
- Chcesz obsługiwać Gateway z poziomu przeglądarki
|
||||
- Chcesz dostępu do Tailnet bez tuneli SSH
|
||||
- Chcesz obsługiwać Gateway z przeglądarki
|
||||
- Chcesz mieć dostęp do Tailnet bez tuneli SSH
|
||||
sidebarTitle: Control UI
|
||||
summary: Przeglądarkowy interfejs sterowania Gateway (czat, węzły, konfiguracja)
|
||||
summary: Interfejs sterowania działający w przeglądarce dla Gateway (czat, węzły, konfiguracja)
|
||||
title: Interfejs sterowania
|
||||
x-i18n:
|
||||
generated_at: "2026-05-04T02:27:36Z"
|
||||
generated_at: "2026-05-04T07:06:41Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: c890d83da2c296b600e4b5a00a538f37e6bd54da31fbe62113ecd6177b15626e
|
||||
source_hash: 07fbbe1c7fec5f67a04a231e02bdf0f7d16be9c5fe188915674d71fcd69002a5
|
||||
source_path: web/control-ui.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
Control UI to mała jednostronicowa aplikacja **Vite + Lit** obsługiwana przez Gateway:
|
||||
Interfejs Control UI to mała jednostronicowa aplikacja **Vite + Lit** serwowana przez Gateway:
|
||||
|
||||
- domyślnie: `http://<host>:18789/`
|
||||
- opcjonalny prefiks: ustaw `gateway.controlUi.basePath` (np. `/openclaw`)
|
||||
@ -36,117 +36,117 @@ Uwierzytelnianie jest przekazywane podczas uzgadniania WebSocket przez:
|
||||
- nagłówki tożsamości Tailscale Serve, gdy `gateway.auth.allowTailscale: true`
|
||||
- nagłówki tożsamości zaufanego proxy, gdy `gateway.auth.mode: "trusted-proxy"`
|
||||
|
||||
Panel ustawień pulpitu przechowuje token dla bieżącej sesji karty przeglądarki i wybranego adresu URL gateway; hasła nie są utrwalane. Onboarding zwykle generuje token gateway do uwierzytelniania współdzielonym sekretem przy pierwszym połączeniu, ale uwierzytelnianie hasłem też działa, gdy `gateway.auth.mode` ma wartość `"password"`.
|
||||
Panel ustawień pulpitu zachowuje token dla bieżącej sesji karty przeglądarki i wybranego adresu URL gateway; hasła nie są utrwalane. Onboarding zwykle generuje token gateway dla uwierzytelniania współdzielonym sekretem przy pierwszym połączeniu, ale uwierzytelnianie hasłem też działa, gdy `gateway.auth.mode` ma wartość `"password"`.
|
||||
|
||||
## Parowanie urządzenia (pierwsze połączenie)
|
||||
|
||||
Gdy łączysz się z Control UI z nowej przeglądarki lub urządzenia, Gateway zwykle wymaga **jednorazowego zatwierdzenia parowania**. To środek bezpieczeństwa zapobiegający nieautoryzowanemu dostępowi.
|
||||
|
||||
**Co zobaczysz:** „rozłączono (1008): wymagane parowanie”
|
||||
**Co zobaczysz:** "disconnected (1008): pairing required"
|
||||
|
||||
<Steps>
|
||||
<Step title="Wyświetl oczekujące żądania">
|
||||
<Step title="List pending requests">
|
||||
```bash
|
||||
openclaw devices list
|
||||
```
|
||||
</Step>
|
||||
<Step title="Zatwierdź według identyfikatora żądania">
|
||||
<Step title="Approve by request ID">
|
||||
```bash
|
||||
openclaw devices approve <requestId>
|
||||
```
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
Jeśli przeglądarka ponowi próbę parowania ze zmienionymi szczegółami uwierzytelniania (rola/zakresy/klucz publiczny), poprzednie oczekujące żądanie zostanie zastąpione i powstanie nowy `requestId`. Przed zatwierdzeniem uruchom ponownie `openclaw devices list`.
|
||||
Jeśli przeglądarka ponawia parowanie ze zmienionymi szczegółami uwierzytelniania (rola/zakresy/klucz publiczny), poprzednie oczekujące żądanie zostaje zastąpione i tworzony jest nowy `requestId`. Przed zatwierdzeniem ponownie uruchom `openclaw devices list`.
|
||||
|
||||
Jeśli przeglądarka jest już sparowana i zmienisz jej dostęp z odczytu na zapis/administratora, zostanie to potraktowane jako podniesienie poziomu zatwierdzenia, a nie ciche ponowne połączenie. OpenClaw zachowuje stare zatwierdzenie jako aktywne, blokuje ponowne połączenie z szerszym zakresem i prosi o jawne zatwierdzenie nowego zestawu zakresów.
|
||||
Jeśli przeglądarka jest już sparowana i zmienisz jej dostęp z odczytu na zapis/administrację, jest to traktowane jako podniesienie poziomu zatwierdzenia, a nie ciche ponowne połączenie. OpenClaw utrzymuje stare zatwierdzenie jako aktywne, blokuje ponowne połączenie z szerszymi uprawnieniami i prosi o jawne zatwierdzenie nowego zestawu zakresów.
|
||||
|
||||
Po zatwierdzeniu urządzenie zostaje zapamiętane i nie będzie wymagać ponownego zatwierdzenia, chyba że je odwołasz przez `openclaw devices revoke --device <id> --role <role>`. Zobacz [CLI urządzeń](/pl/cli/devices), aby dowiedzieć się o rotacji i odwoływaniu tokenów.
|
||||
Po zatwierdzeniu urządzenie jest zapamiętywane i nie będzie wymagać ponownego zatwierdzenia, chyba że unieważnisz je poleceniem `openclaw devices revoke --device <id> --role <role>`. Zobacz [CLI urządzeń](/pl/cli/devices), aby poznać rotację i unieważnianie tokenów.
|
||||
|
||||
<Note>
|
||||
- Bezpośrednie połączenia przeglądarki przez local loopback (`127.0.0.1` / `localhost`) są zatwierdzane automatycznie.
|
||||
- Tailscale Serve może pominąć pełny cykl parowania dla sesji operatora Control UI, gdy `gateway.auth.allowTailscale: true`, tożsamość Tailscale zostanie zweryfikowana, a przeglądarka przedstawi swoją tożsamość urządzenia.
|
||||
- Bezpośrednie bindowania Tailnet, połączenia przeglądarki przez LAN oraz profile przeglądarki bez tożsamości urządzenia nadal wymagają jawnego zatwierdzenia.
|
||||
- Tailscale Serve może pominąć rundę parowania dla sesji operatora Control UI, gdy `gateway.auth.allowTailscale: true`, tożsamość Tailscale zostanie zweryfikowana, a przeglądarka przedstawi swoją tożsamość urządzenia.
|
||||
- Bezpośrednie powiązania Tailnet, połączenia przeglądarki z sieci LAN oraz profile przeglądarki bez tożsamości urządzenia nadal wymagają jawnego zatwierdzenia.
|
||||
- Każdy profil przeglądarki generuje unikalny identyfikator urządzenia, więc zmiana przeglądarki lub wyczyszczenie danych przeglądarki będzie wymagać ponownego parowania.
|
||||
|
||||
</Note>
|
||||
|
||||
## Tożsamość osobista (lokalna dla przeglądarki)
|
||||
|
||||
Control UI obsługuje osobistą tożsamość przypisaną do przeglądarki (nazwę wyświetlaną i awatar), dołączaną do wiadomości wychodzących w celu atrybucji we współdzielonych sesjach. Znajduje się ona w pamięci przeglądarki, jest ograniczona do bieżącego profilu przeglądarki i nie synchronizuje się z innymi urządzeniami ani nie jest utrwalana po stronie serwera poza zwykłymi metadanymi autorstwa transkrypcji przy wiadomościach, które faktycznie wysyłasz. Wyczyszczenie danych witryny lub zmiana przeglądarki resetuje ją do pustej wartości.
|
||||
Control UI obsługuje osobistą tożsamość per przeglądarka (nazwa wyświetlana i avatar), dołączaną do wiadomości wychodzących na potrzeby przypisania autorstwa we współdzielonych sesjach. Znajduje się w pamięci przeglądarki, jest ograniczona do bieżącego profilu przeglądarki i nie jest synchronizowana z innymi urządzeniami ani utrwalana po stronie serwera poza zwykłymi metadanymi autorstwa transkryptu dla wiadomości, które faktycznie wysyłasz. Wyczyszczenie danych witryny lub zmiana przeglądarki resetuje ją do pustej wartości.
|
||||
|
||||
Ten sam lokalny dla przeglądarki wzorzec dotyczy zastąpienia awatara asystenta. Przesłane awatary asystenta nakładają tożsamość rozwiązaną przez gateway tylko w lokalnej przeglądarce i nigdy nie przechodzą pełnego cyklu przez `config.patch`. Współdzielone pole konfiguracji `ui.assistant.avatar` jest nadal dostępne dla klientów innych niż UI, którzy zapisują pole bezpośrednio (takich jak skryptowane gateway lub niestandardowe pulpity).
|
||||
Ten sam wzorzec lokalny dla przeglądarki dotyczy nadpisania avatara asystenta. Przesłane avatary asystenta nakładają lokalnie w przeglądarce tożsamość rozwiązaną przez gateway i nigdy nie wykonują rundy przez `config.patch`. Wspólne pole konfiguracji `ui.assistant.avatar` pozostaje dostępne dla klientów innych niż UI, którzy zapisują to pole bezpośrednio (takich jak skryptowane gateway lub niestandardowe pulpity).
|
||||
|
||||
## Endpoint konfiguracji środowiska uruchomieniowego
|
||||
## Punkt końcowy konfiguracji runtime
|
||||
|
||||
Control UI pobiera swoje ustawienia środowiska uruchomieniowego z `/__openclaw/control-ui-config.json`. Ten endpoint jest chroniony tym samym uwierzytelnianiem gateway co reszta powierzchni HTTP: nieuwierzytelnione przeglądarki nie mogą go pobrać, a pomyślne pobranie wymaga już ważnego tokenu/hasła gateway, tożsamości Tailscale Serve albo tożsamości zaufanego proxy.
|
||||
Control UI pobiera swoje ustawienia runtime z `/__openclaw/control-ui-config.json`. Ten punkt końcowy jest chroniony tym samym uwierzytelnianiem gateway co reszta powierzchni HTTP: nieuwierzytelnione przeglądarki nie mogą go pobrać, a pomyślne pobranie wymaga już ważnego tokenu/hasła gateway, tożsamości Tailscale Serve albo tożsamości zaufanego proxy.
|
||||
|
||||
## Obsługa języków
|
||||
|
||||
Control UI może lokalizować się przy pierwszym ładowaniu na podstawie ustawień regionalnych przeglądarki. Aby zastąpić je później, otwórz **Przegląd -> Dostęp do Gateway -> Język**. Selektor ustawień regionalnych znajduje się na karcie Dostęp do Gateway, a nie w sekcji Wygląd.
|
||||
Control UI może zlokalizować się przy pierwszym ładowaniu na podstawie ustawień regionalnych przeglądarki. Aby później to nadpisać, otwórz **Overview -> Gateway Access -> Language**. Selektor ustawień regionalnych znajduje się w karcie Gateway Access, a nie w Appearance.
|
||||
|
||||
- Obsługiwane ustawienia regionalne: `en`, `zh-CN`, `zh-TW`, `pt-BR`, `de`, `es`, `ja-JP`, `ko`, `fr`, `ar`, `it`, `tr`, `uk`, `id`, `pl`, `th`, `vi`, `nl`, `fa`
|
||||
- Tłumaczenia inne niż angielskie są leniwie ładowane w przeglądarce.
|
||||
- Wybrane ustawienie regionalne jest zapisywane w pamięci przeglądarki i ponownie używane podczas przyszłych wizyt.
|
||||
- Brakujące klucze tłumaczeń wracają do angielskiego.
|
||||
- Wybrane ustawienia regionalne są zapisywane w pamięci przeglądarki i używane ponownie podczas przyszłych wizyt.
|
||||
- Brakujące klucze tłumaczeń wracają do języka angielskiego.
|
||||
|
||||
Tłumaczenia dokumentacji są generowane dla tego samego zestawu ustawień regionalnych innych niż angielskie, ale wbudowany selektor języka witryny dokumentacji Mintlify jest ograniczony do kodów ustawień regionalnych akceptowanych przez Mintlify. Dokumentacja tajska (`th`) i perska (`fa`) nadal jest generowana w repozytorium publikacji; może nie pojawiać się w tym selektorze, dopóki Mintlify nie obsłuży tych kodów.
|
||||
|
||||
## Motywy wyglądu
|
||||
|
||||
Panel Wygląd zachowuje wbudowane motywy Claw, Knot i Dash oraz jedno lokalne dla przeglądarki miejsce importu tweakcn. Aby zaimportować motyw, otwórz [motywy tweakcn](https://tweakcn.com/themes), wybierz lub utwórz motyw, kliknij **Udostępnij** i wklej skopiowany link motywu w sekcji Wygląd. Importer akceptuje również adresy URL rejestru `https://tweakcn.com/r/themes/<id>`, adresy URL edytora, takie jak `https://tweakcn.com/editor/theme?theme=amethyst-haze`, względne ścieżki `/themes/<id>`, surowe identyfikatory motywów oraz domyślne nazwy motywów, takie jak `amethyst-haze`.
|
||||
Panel Appearance zachowuje wbudowane motywy Claw, Knot i Dash oraz jedno lokalne dla przeglądarki miejsce importu tweakcn. Aby zaimportować motyw, otwórz [edytor tweakcn](https://tweakcn.com/editor/theme), wybierz lub utwórz motyw, kliknij **Share** i wklej skopiowany link motywu do Appearance. Importer akceptuje także adresy URL rejestru `https://tweakcn.com/r/themes/<id>`, adresy URL edytora takie jak `https://tweakcn.com/editor/theme?theme=amethyst-haze`, ścieżki względne `/themes/<id>`, surowe identyfikatory motywów oraz domyślne nazwy motywów, takie jak `amethyst-haze`.
|
||||
|
||||
Zaimportowane motywy są przechowywane tylko w bieżącym profilu przeglądarki. Nie są zapisywane w konfiguracji gateway i nie synchronizują się między urządzeniami. Zastąpienie zaimportowanego motywu aktualizuje jedno lokalne miejsce; wyczyszczenie go przełącza aktywny motyw z powrotem na Claw, jeśli zaimportowany motyw był wybrany.
|
||||
|
||||
## Co może robić (obecnie)
|
||||
## Co potrafi robić (dzisiaj)
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Czat i rozmowa">
|
||||
<Accordion title="Chat and Talk">
|
||||
- Czatuj z modelem przez Gateway WS (`chat.history`, `chat.send`, `chat.abort`, `chat.inject`).
|
||||
- Rozmawiaj przez sesje czasu rzeczywistego w przeglądarce. OpenAI używa bezpośredniego WebRTC, Google Live używa ograniczonego jednorazowego tokenu przeglądarki przez WebSocket, a działające tylko w backendzie Plugin głosu czasu rzeczywistego używają transportu przekaźnikowego Gateway. Przekaźnik utrzymuje poświadczenia dostawcy na Gateway, podczas gdy przeglądarka strumieniuje PCM z mikrofonu przez RPC `talk.realtime.relay*` i odsyła wywołania narzędzia `openclaw_agent_consult` przez `chat.send` do większego skonfigurowanego modelu OpenClaw.
|
||||
- Strumieniuj wywołania narzędzi i karty wyników narzędzi na żywo w Czacie (zdarzenia agenta).
|
||||
- Rozmawiaj przez sesje czasu rzeczywistego w przeglądarce. OpenAI używa bezpośredniego WebRTC, Google Live używa ograniczonego, jednorazowego tokenu przeglądarki przez WebSocket, a Plugin głosu czasu rzeczywistego działające wyłącznie po stronie backendu używają transportu przekaźnikowego Gateway. Przekaźnik utrzymuje poświadczenia dostawcy na Gateway, podczas gdy przeglądarka strumieniuje PCM z mikrofonu przez RPC `talk.realtime.relay*` i wysyła wywołania narzędzia `openclaw_agent_consult` z powrotem przez `chat.send` dla większego skonfigurowanego modelu OpenClaw.
|
||||
- Strumieniuj wywołania narzędzi oraz karty wyjścia narzędzi na żywo w czacie (zdarzenia agenta).
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Kanały, instancje, sesje, sny">
|
||||
- Kanały: wbudowane oraz spakowane/zewnętrzne statusy kanałów Plugin, logowanie QR i konfiguracja per kanał (`channels.status`, `web.login.*`, `config.patch`).
|
||||
<Accordion title="Channels, instances, sessions, dreams">
|
||||
- Kanały: wbudowane oraz dołączone/zewnętrzne kanały Plugin, status, logowanie QR i konfiguracja per kanał (`channels.status`, `web.login.*`, `config.patch`).
|
||||
- Instancje: lista obecności + odświeżanie (`system-presence`).
|
||||
- Sesje: lista + zastąpienia modelu/myślenia/szybkości/szczegółowości/śledzenia/rozumowania per sesja (`sessions.list`, `sessions.patch`).
|
||||
- Sny: status dreaming, przełącznik włączania/wyłączania i czytnik Dziennika snów (`doctor.memory.status`, `doctor.memory.dreamDiary`, `config.patch`).
|
||||
- Sesje: lista + nadpisania modelu/myślenia/trybu szybkiego/szczegółowości/śledzenia/rozumowania per sesja (`sessions.list`, `sessions.patch`).
|
||||
- Dreams: status Dreaming, przełącznik włącz/wyłącz oraz czytnik Dream Diary (`doctor.memory.status`, `doctor.memory.dreamDiary`, `config.patch`).
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Cron, skills, nodes, zatwierdzenia exec">
|
||||
<Accordion title="Cron, skills, nodes, exec approvals">
|
||||
- Zadania Cron: lista/dodaj/edytuj/uruchom/włącz/wyłącz + historia uruchomień (`cron.*`).
|
||||
- Skills: status, włączanie/wyłączanie, instalacja, aktualizacje kluczy API (`skills.*`).
|
||||
- Węzły: lista + możliwości (`node.list`).
|
||||
- Zatwierdzenia exec: edycja list dozwolonych gateway lub węzła + polityka pytania dla `exec host=gateway/node` (`exec.approvals.*`).
|
||||
- Skills: status, włączanie/wyłączanie, instalacja, aktualizacje klucza API (`skills.*`).
|
||||
- Node: lista + możliwości (`node.list`).
|
||||
- Zatwierdzenia exec: edytuj listy dozwolonych elementów gateway lub Node + politykę pytań dla `exec host=gateway/node` (`exec.approvals.*`).
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Konfiguracja">
|
||||
- Wyświetl/edytuj `~/.openclaw/openclaw.json` (`config.get`, `config.set`).
|
||||
<Accordion title="Config">
|
||||
- Wyświetlaj/edytuj `~/.openclaw/openclaw.json` (`config.get`, `config.set`).
|
||||
- Zastosuj + uruchom ponownie z walidacją (`config.apply`) i wybudź ostatnią aktywną sesję.
|
||||
- Zapisy obejmują zabezpieczenie bazowym hashem, aby zapobiec nadpisaniu równoległych edycji.
|
||||
- Zapisy (`config.set`/`config.apply`/`config.patch`) wstępnie sprawdzają rozwiązywanie aktywnych SecretRef dla odwołań w przesłanym ładunku konfiguracji; nierozwiązane aktywne przesłane odwołania są odrzucane przed zapisem.
|
||||
- Schemat + renderowanie formularza (`config.schema` / `config.schema.lookup`, w tym pola `title` / `description`, dopasowane wskazówki UI, natychmiastowe podsumowania elementów potomnych, metadane dokumentacji na zagnieżdżonych węzłach obiektów/wieloznaczników/tablic/kompozycji oraz schematy Plugin + kanałów, gdy są dostępne); edytor surowego JSON jest dostępny tylko wtedy, gdy migawka ma bezpieczny surowy pełny cykl.
|
||||
- Jeśli migawka nie może bezpiecznie wykonać pełnego cyklu surowego tekstu, Control UI wymusza tryb Formularz i wyłącza tryb Surowy dla tej migawki.
|
||||
- Edytor surowego JSON „Resetuj do zapisanej” zachowuje kształt utworzony w surowej postaci (formatowanie, komentarze, układ `$include`) zamiast ponownie renderować spłaszczoną migawkę, dzięki czemu zewnętrzne edycje przetrwają reset, gdy migawka może bezpiecznie wykonać pełny cykl.
|
||||
- Strukturalne wartości obiektów SecretRef są renderowane jako tylko do odczytu w tekstowych polach formularza, aby zapobiec przypadkowemu uszkodzeniu przez konwersję obiektu na ciąg znaków.
|
||||
- Zapisy obejmują strażnika skrótu bazowego, aby zapobiec nadpisaniu równoczesnych edycji.
|
||||
- Zapisy (`config.set`/`config.apply`/`config.patch`) wykonują wstępne rozwiązanie aktywnych SecretRef dla referencji w przesłanym ładunku konfiguracji; nierozwiązane aktywne przesłane referencje są odrzucane przed zapisem.
|
||||
- Schemat + renderowanie formularza (`config.schema` / `config.schema.lookup`, w tym pola `title` / `description`, dopasowane wskazówki UI, natychmiastowe podsumowania dzieci, metadane dokumentacji na zagnieżdżonych węzłach obiektów/wieloznaczników/tablic/kompozycji oraz schematy Plugin + kanałów, gdy są dostępne); edytor surowego JSON jest dostępny tylko wtedy, gdy migawka ma bezpieczną surową rundę zapisu i odczytu.
|
||||
- Jeśli migawka nie może bezpiecznie wykonać surowej rundy zapisu i odczytu tekstu, Control UI wymusza tryb Form i wyłącza tryb Raw dla tej migawki.
|
||||
- Edytor surowego JSON "Reset to saved" zachowuje kształt utworzony w surowym widoku (formatowanie, komentarze, układ `$include`) zamiast ponownie renderować spłaszczoną migawkę, dzięki czemu zewnętrzne edycje przetrwają reset, gdy migawka może bezpiecznie wykonać rundę zapisu i odczytu.
|
||||
- Ustrukturyzowane wartości obiektów SecretRef są renderowane w tekstowych polach formularza jako tylko do odczytu, aby zapobiec przypadkowemu uszkodzeniu przez konwersję obiektu na ciąg znaków.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Debugowanie, logi, aktualizacja">
|
||||
<Accordion title="Debug, logs, update">
|
||||
- Debugowanie: migawki statusu/kondycji/modeli + dziennik zdarzeń + ręczne wywołania RPC (`status`, `health`, `models.list`).
|
||||
- Logi: aktywne śledzenie logów plikowych gateway z filtrem/eksportem (`logs.tail`).
|
||||
- Aktualizacja: uruchom aktualizację pakietu/git + restart (`update.run`) z raportem restartu, a następnie odpytuj `update.status` po ponownym połączeniu, aby zweryfikować działającą wersję gateway.
|
||||
- Logi: ogon na żywo logów plików gateway z filtrem/eksportem (`logs.tail`).
|
||||
- Aktualizacja: uruchom aktualizację pakietu/git + restart (`update.run`) z raportem restartu, a potem odpytuj `update.status` po ponownym połączeniu, aby zweryfikować uruchomioną wersję gateway.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Uwagi panelu zadań Cron">
|
||||
- Dla zadań izolowanych dostarczanie domyślnie ogłasza podsumowanie. Możesz przełączyć na brak, jeśli chcesz uruchomienia wyłącznie wewnętrzne.
|
||||
- Pola kanału/celu pojawiają się po wybraniu ogłaszania.
|
||||
<Accordion title="Cron jobs panel notes">
|
||||
- Dla zadań izolowanych domyślną dostawą jest ogłoszenie podsumowania. Możesz przełączyć na brak, jeśli chcesz uruchomienia wyłącznie wewnętrzne.
|
||||
- Pola kanału/celu pojawiają się, gdy wybrano ogłoszenie.
|
||||
- Tryb Webhook używa `delivery.mode = "webhook"` z `delivery.to` ustawionym na prawidłowy adres URL Webhook HTTP(S).
|
||||
- Dla zadań sesji głównej dostępne są tryby dostarczania webhook i brak.
|
||||
- Zaawansowane kontrolki edycji obejmują usunięcie po uruchomieniu, wyczyszczenie zastąpienia agenta, dokładne/rozłożone opcje cron, zastąpienia modelu/myślenia agenta oraz przełączniki dostarczania best-effort.
|
||||
- Walidacja formularza jest wbudowana z błędami na poziomie pól; nieprawidłowe wartości wyłączają przycisk zapisu do czasu poprawy.
|
||||
- Ustaw `cron.webhookToken`, aby wysłać dedykowany token bearer; jeśli zostanie pominięty, webhook zostanie wysłany bez nagłówka auth.
|
||||
- Przestarzały fallback: zapisane starsze zadania z `notify: true` mogą nadal używać `cron.webhook` do czasu migracji.
|
||||
- Dla zadań głównej sesji dostępne są tryby dostawy Webhook i brak.
|
||||
- Zaawansowane kontrolki edycji obejmują usuń po uruchomieniu, wyczyszczenie nadpisania agenta, opcje dokładnego/rozłożonego Cron, nadpisania modelu/myślenia agenta oraz przełączniki dostawy w trybie najlepszych starań.
|
||||
- Walidacja formularza jest wbudowana z błędami na poziomie pól; nieprawidłowe wartości wyłączają przycisk zapisu do czasu naprawy.
|
||||
- Ustaw `cron.webhookToken`, aby wysłać dedykowany token bearer; jeśli zostanie pominięty, Webhook jest wysyłany bez nagłówka uwierzytelniania.
|
||||
- Przestarzały fallback: przechowywane starsze zadania z `notify: true` mogą nadal używać `cron.webhook`, dopóki nie zostaną zmigrowane.
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
@ -155,54 +155,54 @@ Zaimportowane motywy są przechowywane tylko w bieżącym profilu przeglądarki.
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Semantyka wysyłania i historii">
|
||||
- `chat.send` jest **nieblokujące**: natychmiast potwierdza z `{ runId, status: "started" }`, a odpowiedź jest przesyłana strumieniowo przez zdarzenia `chat`.
|
||||
- Przesyłanie do czatu akceptuje obrazy oraz pliki inne niż wideo. Obrazy zachowują natywną ścieżkę obrazu; pozostałe pliki są przechowywane jako zarządzane media i pokazywane w historii jako linki załączników.
|
||||
- `chat.send` jest **nieblokujące**: potwierdza natychmiast wartością `{ runId, status: "started" }`, a odpowiedź jest przesyłana strumieniowo przez zdarzenia `chat`.
|
||||
- Przesyłanie plików na czacie akceptuje obrazy oraz pliki inne niż wideo. Obrazy zachowują natywną ścieżkę obrazu; pozostałe pliki są przechowywane jako zarządzane multimedia i pokazywane w historii jako linki załączników.
|
||||
- Ponowne wysłanie z tym samym `idempotencyKey` zwraca `{ status: "in_flight" }` podczas działania oraz `{ status: "ok" }` po zakończeniu.
|
||||
- Odpowiedzi `chat.history` mają ograniczony rozmiar dla bezpieczeństwa UI. Gdy wpisy transkrypcji są zbyt duże, Gateway może przyciąć długie pola tekstowe, pominąć ciężkie bloki metadanych i zastąpić zbyt duże wiadomości placeholderem (`[chat.history omitted: message too large]`).
|
||||
- Obrazy asystenta/wygenerowane są utrwalane jako zarządzane odwołania do mediów i zwracane przez uwierzytelnione adresy URL mediów Gateway, więc ponowne wczytania nie zależą od pozostania surowych ładunków obrazów base64 w odpowiedzi historii czatu.
|
||||
- `chat.history` usuwa też z widocznego tekstu asystenta wyłącznie prezentacyjne wbudowane tagi dyrektyw (na przykład `[[reply_to_*]]` i `[[audio_as_voice]]`), tekstowe ładunki XML wywołań narzędzi (w tym `<tool_call>...</tool_call>`, `<function_call>...</function_call>`, `<tool_calls>...</tool_calls>`, `<function_calls>...</function_calls>` oraz przycięte bloki wywołań narzędzi), a także ujawnione tokeny sterujące modelu w ASCII/pełnej szerokości, oraz pomija wpisy asystenta, których cały widoczny tekst jest wyłącznie dokładnym cichym tokenem `NO_REPLY` / `no_reply`.
|
||||
- Podczas aktywnego wysyłania i końcowego odświeżania historii widok czatu utrzymuje lokalne optymistyczne wiadomości użytkownika/asystenta jako widoczne, jeśli `chat.history` przez chwilę zwraca starszą migawkę; kanoniczna transkrypcja zastępuje te lokalne wiadomości, gdy historia Gateway nadrobi zaległość.
|
||||
- Zdarzenia `chat` na żywo są stanem dostarczania, natomiast `chat.history` jest odbudowywane z trwałej transkrypcji sesji. Po zdarzeniach końcowych narzędzi Control UI ponownie wczytuje historię i scala tylko mały optymistyczny ogon; granica transkrypcji jest udokumentowana w [WebChat](/pl/web/webchat).
|
||||
- `chat.inject` dołącza notatkę asystenta do transkrypcji sesji i rozgłasza zdarzenie `chat` na potrzeby aktualizacji wyłącznie UI (bez uruchomienia agenta, bez dostarczania kanałem).
|
||||
- Wybieraki modelu i myślenia w nagłówku czatu natychmiast aktualizują aktywną sesję przez `sessions.patch`; są trwałymi nadpisaniami sesji, a nie opcjami wysyłania tylko dla jednej tury.
|
||||
- Wpisanie `/new` w Control UI tworzy tę samą świeżą sesję panelu co New Chat i przełącza na nią. Wpisanie `/reset` zachowuje jawny reset Gateway w miejscu dla bieżącej sesji.
|
||||
- Wybierak modelu czatu żąda skonfigurowanego widoku modeli Gateway. Jeśli istnieje `agents.defaults.models`, ta lista dozwolonych wartości steruje wybierakiem. W przeciwnym razie wybierak pokazuje jawne wpisy `models.providers.*.models` oraz dostawców z użytecznym uwierzytelnianiem. Pełny katalog pozostaje dostępny przez debugowe RPC `models.list` z `view: "all"`.
|
||||
- Gdy raporty użycia świeżej sesji Gateway pokazują wysoką presję kontekstu, obszar kompozytora czatu pokazuje powiadomienie o kontekście, a przy zalecanych poziomach Compaction także kompaktowy przycisk uruchamiający normalną ścieżkę Compaction sesji. Nieaktualne migawki tokenów są ukryte, dopóki Gateway ponownie nie zgłosi świeżego użycia.
|
||||
- Odpowiedzi `chat.history` mają ograniczony rozmiar dla bezpieczeństwa UI. Gdy wpisy transkrypcji są zbyt duże, Gateway może skrócić długie pola tekstowe, pominąć ciężkie bloki metadanych i zastąpić nadmiernie duże wiadomości symbolem zastępczym (`[chat.history omitted: message too large]`).
|
||||
- Obrazy asystenta/wygenerowane są utrwalane jako odwołania do zarządzanych multimediów i zwracane przez uwierzytelnione adresy URL multimediów Gateway, więc ponowne wczytania nie zależą od pozostawania surowych ładunków obrazów base64 w odpowiedzi historii czatu.
|
||||
- `chat.history` usuwa też z widocznego tekstu asystenta wyłącznie prezentacyjne wbudowane znaczniki dyrektyw (na przykład `[[reply_to_*]]` i `[[audio_as_voice]]`), zwykłotekstowe ładunki XML wywołań narzędzi (w tym `<tool_call>...</tool_call>`, `<function_call>...</function_call>`, `<tool_calls>...</tool_calls>`, `<function_calls>...</function_calls>` oraz skrócone bloki wywołań narzędzi), a także ujawnione tokeny sterujące modelu ASCII/pełnej szerokości, oraz pomija wpisy asystenta, których cały widoczny tekst jest tylko dokładnym cichym tokenem `NO_REPLY` / `no_reply`.
|
||||
- Podczas aktywnego wysyłania i końcowego odświeżania historii widok czatu utrzymuje widoczne lokalne optymistyczne wiadomości użytkownika/asystenta, jeśli `chat.history` na krótko zwróci starszy migawkowy stan; kanoniczna transkrypcja zastępuje te lokalne wiadomości, gdy historia Gateway nadrobi zaległości.
|
||||
- Zdarzenia `chat` na żywo są stanem dostarczenia, natomiast `chat.history` jest odbudowywane z trwałej transkrypcji sesji. Po zdarzeniach końcowych narzędzi Control UI ponownie wczytuje historię i scala tylko mały optymistyczny ogon; granica transkrypcji jest udokumentowana w [WebChat](/pl/web/webchat).
|
||||
- `chat.inject` dodaje notatkę asystenta do transkrypcji sesji i rozgłasza zdarzenie `chat` dla aktualizacji wyłącznie w UI (bez uruchomienia agenta, bez dostarczenia kanałowego).
|
||||
- Selektory modelu i myślenia w nagłówku czatu natychmiast aktualizują aktywną sesję przez `sessions.patch`; są trwałymi nadpisaniami sesji, a nie opcjami wysyłki tylko dla jednej tury.
|
||||
- Wpisanie `/new` w Control UI tworzy i przełącza na tę samą świeżą sesję pulpitu co Nowy czat. Wpisanie `/reset` zachowuje jawne resetowanie w miejscu Gateway dla bieżącej sesji.
|
||||
- Selektor modelu czatu żąda skonfigurowanego widoku modeli Gateway. Jeśli obecne jest `agents.defaults.models`, ta lista dozwolonych steruje selektorem. W przeciwnym razie selektor pokazuje jawne wpisy `models.providers.*.models` oraz dostawców z użytecznym uwierzytelnieniem. Pełny katalog pozostaje dostępny przez debugujące RPC `models.list` z `view: "all"`.
|
||||
- Gdy świeże raporty użycia sesji Gateway wskazują wysoką presję kontekstu, obszar kompozytora czatu pokazuje informację o kontekście, a przy zalecanych poziomach Compaction także przycisk kompaktowania uruchamiający normalną ścieżkę Compaction sesji. Nieaktualne migawki tokenów są ukrywane, dopóki Gateway ponownie nie zgłosi świeżego użycia.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Tryb rozmowy (czas rzeczywisty w przeglądarce)">
|
||||
Tryb rozmowy używa zarejestrowanego dostawcy głosu w czasie rzeczywistym. Skonfiguruj OpenAI przez `talk.provider: "openai"` oraz `talk.providers.openai.apiKey`, albo skonfiguruj Google przez `talk.provider: "google"` oraz `talk.providers.google.apiKey`; konfiguracja dostawcy czasu rzeczywistego Voice Call nadal może być używana jako rozwiązanie zapasowe. Przeglądarka nigdy nie otrzymuje standardowego klucza API dostawcy. OpenAI otrzymuje efemeryczny sekret klienta Realtime dla WebRTC. Google Live otrzymuje jednorazowy, ograniczony token uwierzytelniania Live API dla sesji WebSocket przeglądarki, z instrukcjami i deklaracjami narzędzi zablokowanymi w tokenie przez Gateway. Dostawcy, którzy udostępniają tylko most czasu rzeczywistego po stronie backendu, działają przez transport przekaźnikowy Gateway, więc poświadczenia i gniazda dostawcy pozostają po stronie serwera, podczas gdy dźwięk przeglądarki przechodzi przez uwierzytelnione RPC Gateway. Prompt sesji Realtime jest składany przez Gateway; `talk.realtime.session` nie akceptuje nadpisań instrukcji dostarczanych przez wywołującego.
|
||||
Tryb rozmowy używa zarejestrowanego dostawcy głosu w czasie rzeczywistym. Skonfiguruj OpenAI za pomocą `talk.provider: "openai"` oraz `talk.providers.openai.apiKey` albo skonfiguruj Google za pomocą `talk.provider: "google"` oraz `talk.providers.google.apiKey`; konfigurację dostawcy czasu rzeczywistego połączeń głosowych nadal można ponownie wykorzystać jako opcję awaryjną. Przeglądarka nigdy nie otrzymuje standardowego klucza API dostawcy. OpenAI otrzymuje efemeryczny sekret klienta Realtime dla WebRTC. Google Live otrzymuje jednorazowy ograniczony token uwierzytelniania Live API dla sesji WebSocket w przeglądarce, z instrukcjami i deklaracjami narzędzi zablokowanymi w tokenie przez Gateway. Dostawcy, którzy udostępniają tylko backendowy most czasu rzeczywistego, działają przez transport przekaźnika Gateway, więc poświadczenia i gniazda dostawców pozostają po stronie serwera, podczas gdy dźwięk przeglądarki przechodzi przez uwierzytelnione RPC Gateway. Prompt sesji Realtime jest składany przez Gateway; `talk.realtime.session` nie akceptuje nadpisań instrukcji dostarczanych przez wywołującego.
|
||||
|
||||
W kompozytorze czatu kontrolka Talk to przycisk fal obok przycisku dyktowania mikrofonem. Gdy Talk startuje, wiersz stanu kompozytora pokazuje `Connecting Talk...`, następnie `Talk live`, gdy dźwięk jest połączony, albo `Asking OpenClaw...`, gdy wywołanie narzędzia czasu rzeczywistego konsultuje się ze skonfigurowanym większym modelem przez `chat.send`.
|
||||
W kompozytorze czatu element sterujący rozmową to przycisk fal obok przycisku dyktowania mikrofonem. Po rozpoczęciu rozmowy wiersz statusu kompozytora pokazuje `Connecting Talk...`, potem `Talk live`, gdy dźwięk jest połączony, albo `Asking OpenClaw...`, gdy wywołanie narzędzia czasu rzeczywistego konsultuje się ze skonfigurowanym większym modelem przez `chat.send`.
|
||||
|
||||
Smoke test live dla maintainerów: `OPENAI_API_KEY=... GEMINI_API_KEY=... node --import tsx scripts/dev/realtime-talk-live-smoke.ts` weryfikuje wymianę SDP OpenAI WebRTC w przeglądarce, konfigurację WebSocket przeglądarki z ograniczonym tokenem Google Live oraz adapter przeglądarki przekaźnika Gateway z fałszywymi mediami mikrofonu. Polecenie wypisuje tylko status dostawcy i nie loguje sekretów.
|
||||
Dymny test na żywo dla opiekunów: `OPENAI_API_KEY=... GEMINI_API_KEY=... node --import tsx scripts/dev/realtime-talk-live-smoke.ts` weryfikuje wymianę SDP WebRTC przeglądarki OpenAI, konfigurację ograniczonego tokena Google Live dla WebSocket w przeglądarce oraz adapter przeglądarkowy przekaźnika Gateway z fałszywymi multimediami mikrofonu. Polecenie wypisuje tylko status dostawcy i nie loguje sekretów.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Zatrzymanie i przerwanie">
|
||||
- Kliknij **Stop** (wywołuje `chat.abort`).
|
||||
- Gdy uruchomienie jest aktywne, zwykłe kolejne wiadomości trafiają do kolejki. Kliknij **Steer** przy wiadomości w kolejce, aby wstrzyknąć tę kolejną wiadomość do trwającej tury.
|
||||
- Wpisz `/stop` (lub samodzielne frazy przerwania, takie jak `stop`, `stop action`, `stop run`, `stop openclaw`, `please stop`), aby przerwać poza pasmem.
|
||||
- Kliknij **Zatrzymaj** (wywołuje `chat.abort`).
|
||||
- Gdy uruchomienie jest aktywne, zwykłe odpowiedzi uzupełniające trafiają do kolejki. Kliknij **Steruj** przy wiadomości w kolejce, aby wstrzyknąć tę odpowiedź uzupełniającą do trwającej tury.
|
||||
- Wpisz `/stop` (lub samodzielne frazy przerwania, takie jak `stop`, `stop action`, `stop run`, `stop openclaw`, `please stop`), aby przerwać poza głównym kanałem.
|
||||
- `chat.abort` obsługuje `{ sessionKey }` (bez `runId`), aby przerwać wszystkie aktywne uruchomienia dla tej sesji.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Zachowanie części po przerwaniu">
|
||||
<Accordion title="Zachowywanie części po przerwaniu">
|
||||
- Gdy uruchomienie zostanie przerwane, częściowy tekst asystenta nadal może być pokazany w UI.
|
||||
- Gateway utrwala przerwany częściowy tekst asystenta w historii transkrypcji, gdy istnieje zbuforowane wyjście.
|
||||
- Utrwalone wpisy zawierają metadane przerwania, aby konsumenci transkrypcji mogli odróżnić części po przerwaniu od normalnego wyjścia ukończenia.
|
||||
- Utrwalone wpisy zawierają metadane przerwania, aby konsumenci transkrypcji mogli odróżnić części po przerwaniu od normalnego wyjścia zakończenia.
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## Instalacja PWA i Web Push
|
||||
|
||||
Control UI dostarcza `manifest.webmanifest` i service worker, więc nowoczesne przeglądarki mogą instalować go jako samodzielną PWA. Web Push pozwala Gateway wybudzać zainstalowaną PWA powiadomieniami nawet wtedy, gdy karta lub okno przeglądarki nie jest otwarte.
|
||||
Control UI zawiera `manifest.webmanifest` i service worker, więc nowoczesne przeglądarki mogą zainstalować go jako samodzielną PWA. Web Push pozwala Gateway wybudzać zainstalowaną PWA powiadomieniami nawet wtedy, gdy karta lub okno przeglądarki nie jest otwarte.
|
||||
|
||||
| Powierzchnia | Co robi |
|
||||
| ------------------------------------------------------ | ------------------------------------------------------------------- |
|
||||
| `ui/public/manifest.webmanifest` | Manifest PWA. Przeglądarki oferują „Zainstaluj aplikację”, gdy jest osiągalny. |
|
||||
| `ui/public/sw.js` | Service worker obsługujący zdarzenia `push` i kliknięcia powiadomień. |
|
||||
| `push/vapid-keys.json` (w katalogu stanu OpenClaw) | Automatycznie wygenerowana para kluczy VAPID używana do podpisywania ładunków Web Push. |
|
||||
| `push/web-push-subscriptions.json` | Utrwalone punkty końcowe subskrypcji przeglądarki. |
|
||||
| Powierzchnia | Co robi |
|
||||
| ----------------------------------------------------- | ------------------------------------------------------------------ |
|
||||
| `ui/public/manifest.webmanifest` | Manifest PWA. Przeglądarki oferują „Zainstaluj aplikację”, gdy jest osiągalny. |
|
||||
| `ui/public/sw.js` | Service worker obsługujący zdarzenia `push` i kliknięcia powiadomień. |
|
||||
| `push/vapid-keys.json` (w katalogu stanu OpenClaw) | Automatycznie wygenerowana para kluczy VAPID używana do podpisywania ładunków Web Push. |
|
||||
| `push/web-push-subscriptions.json` | Utrwalone punkty końcowe subskrypcji przeglądarki. |
|
||||
|
||||
Nadpisz parę kluczy VAPID przez zmienne środowiskowe w procesie Gateway, gdy chcesz przypiąć klucze (dla wdrożeń wielohostowych, rotacji sekretów lub testów):
|
||||
|
||||
@ -210,7 +210,7 @@ Nadpisz parę kluczy VAPID przez zmienne środowiskowe w procesie Gateway, gdy c
|
||||
- `OPENCLAW_VAPID_PRIVATE_KEY`
|
||||
- `OPENCLAW_VAPID_SUBJECT` (domyślnie `mailto:openclaw@localhost`)
|
||||
|
||||
Control UI używa tych metod Gateway ograniczonych zakresem do rejestrowania i testowania subskrypcji przeglądarki:
|
||||
Control UI używa tych metod Gateway ograniczonych zakresem, aby rejestrować i testować subskrypcje przeglądarki:
|
||||
|
||||
- `push.web.vapidPublicKey` — pobiera aktywny klucz publiczny VAPID.
|
||||
- `push.web.subscribe` — rejestruje `endpoint` oraz `keys.p256dh`/`keys.auth`.
|
||||
@ -218,22 +218,22 @@ Control UI używa tych metod Gateway ograniczonych zakresem do rejestrowania i t
|
||||
- `push.web.test` — wysyła powiadomienie testowe do subskrypcji wywołującego.
|
||||
|
||||
<Note>
|
||||
Web Push jest niezależny od ścieżki przekaźnika APNS iOS (zobacz [Konfiguracja](/pl/gateway/configuration) dla powiadomień push opartych na przekaźniku) oraz istniejącej metody `push.test`, które są skierowane do natywnego parowania mobilnego.
|
||||
Web Push jest niezależny od ścieżki przekaźnika APNS iOS (zobacz [Konfigurację](/pl/gateway/configuration) dla powiadomień push wspieranych przekaźnikiem) oraz od istniejącej metody `push.test`, które są kierowane do natywnego parowania mobilnego.
|
||||
</Note>
|
||||
|
||||
## Hostowane osadzenia
|
||||
## Osadzenia hostowane
|
||||
|
||||
Wiadomości asystenta mogą renderować hostowaną zawartość internetową wbudowaną za pomocą shortcode `[embed ...]`. Polityką sandbox iframe steruje `gateway.controlUi.embedSandbox`:
|
||||
Wiadomości asystenta mogą renderować hostowaną zawartość webową wbudowaną za pomocą shortcode'u `[embed ...]`. Polityką piaskownicy iframe steruje `gateway.controlUi.embedSandbox`:
|
||||
|
||||
<Tabs>
|
||||
<Tab title="strict">
|
||||
Wyłącza wykonywanie skryptów wewnątrz hostowanych osadzeń.
|
||||
</Tab>
|
||||
<Tab title="scripts (domyślne)">
|
||||
Pozwala na interaktywne osadzenia przy zachowaniu izolacji origin; to ustawienie domyślne i zwykle wystarcza dla samodzielnych gier/widgetów przeglądarkowych.
|
||||
Zezwala na interaktywne osadzenia, zachowując izolację pochodzenia; jest to wartość domyślna i zwykle wystarcza dla samodzielnych gier/widgetów przeglądarkowych.
|
||||
</Tab>
|
||||
<Tab title="trusted">
|
||||
Dodaje `allow-same-origin` oprócz `allow-scripts` dla dokumentów z tej samej witryny, które celowo potrzebują silniejszych uprawnień.
|
||||
Dodaje `allow-same-origin` oprócz `allow-scripts` dla dokumentów w tej samej witrynie, które celowo potrzebują silniejszych uprawnień.
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
@ -250,10 +250,10 @@ Przykład:
|
||||
```
|
||||
|
||||
<Warning>
|
||||
Używaj `trusted` tylko wtedy, gdy osadzony dokument naprawdę potrzebuje zachowania same-origin. Dla większości gier generowanych przez agentów i interaktywnych canvasów `scripts` jest bezpieczniejszym wyborem.
|
||||
Używaj `trusted` tylko wtedy, gdy osadzony dokument rzeczywiście potrzebuje zachowania tego samego pochodzenia. Dla większości gier generowanych przez agentów i interaktywnych płócien `scripts` jest bezpieczniejszym wyborem.
|
||||
</Warning>
|
||||
|
||||
Bezwzględne zewnętrzne adresy URL osadzeń `http(s)` domyślnie pozostają blokowane. Jeśli celowo chcesz, aby `[embed url="https://..."]` wczytywało strony firm trzecich, ustaw `gateway.controlUi.allowExternalEmbedUrls: true`.
|
||||
Bezwzględne zewnętrzne adresy URL osadzeń `http(s)` pozostają domyślnie blokowane. Jeśli celowo chcesz, aby `[embed url="https://..."]` wczytywał strony firm trzecich, ustaw `gateway.controlUi.allowExternalEmbedUrls: true`.
|
||||
|
||||
## Szerokość wiadomości czatu
|
||||
|
||||
@ -271,11 +271,11 @@ Zgrupowane wiadomości czatu używają czytelnej domyślnej maksymalnej szeroko
|
||||
|
||||
Wartość jest walidowana, zanim trafi do przeglądarki. Obsługiwane wartości obejmują proste długości i procenty, takie jak `960px` lub `82%`, a także ograniczone wyrażenia szerokości `min(...)`, `max(...)`, `clamp(...)`, `calc(...)` i `fit-content(...)`.
|
||||
|
||||
## Dostęp do tailnetu (zalecane)
|
||||
## Dostęp tailnet (zalecane)
|
||||
|
||||
<Tabs>
|
||||
<Tab title="Zintegrowane Tailscale Serve (preferowane)">
|
||||
Pozostaw Gateway na loopback i pozwól Tailscale Serve proxy'ować go przez HTTPS:
|
||||
Pozostaw Gateway na local loopback i pozwól Tailscale Serve pośredniczyć z HTTPS:
|
||||
|
||||
```bash
|
||||
openclaw gateway --tailscale serve
|
||||
@ -283,39 +283,39 @@ Wartość jest walidowana, zanim trafi do przeglądarki. Obsługiwane wartości
|
||||
|
||||
Otwórz:
|
||||
|
||||
- `https://<magicdns>/` (lub skonfigurowane `gateway.controlUi.basePath`)
|
||||
- `https://<magicdns>/` (lub skonfigurowany `gateway.controlUi.basePath`)
|
||||
|
||||
Domyślnie żądania Control UI/WebSocket Serve mogą uwierzytelniać się przez nagłówki tożsamości Tailscale (`tailscale-user-login`), gdy `gateway.auth.allowTailscale` ma wartość `true`. OpenClaw weryfikuje tożsamość, rozwiązując adres `x-forwarded-for` za pomocą `tailscale whois` i dopasowując go do nagłówka, oraz akceptuje je tylko wtedy, gdy żądanie trafia w loopback z nagłówkami `x-forwarded-*` Tailscale. Dla sesji operatora Control UI z tożsamością urządzenia przeglądarki ta zweryfikowana ścieżka Serve pomija też rundę parowania urządzenia; przeglądarki bez urządzenia i połączenia roli node nadal przechodzą normalne kontrole urządzenia. Ustaw `gateway.auth.allowTailscale: false`, jeśli chcesz wymagać jawnych poświadczeń współdzielonego sekretu nawet dla ruchu Serve. Następnie użyj `gateway.auth.mode: "token"` lub `"password"`.
|
||||
Domyślnie żądania Serve Control UI/WebSocket mogą uwierzytelniać się przez nagłówki tożsamości Tailscale (`tailscale-user-login`), gdy `gateway.auth.allowTailscale` ma wartość `true`. OpenClaw weryfikuje tożsamość, rozwiązując adres `x-forwarded-for` za pomocą `tailscale whois` i dopasowując go do nagłówka, oraz akceptuje je tylko wtedy, gdy żądanie trafia na local loopback z nagłówkami `x-forwarded-*` Tailscale. Dla sesji operatora Control UI z tożsamością urządzenia przeglądarki ta zweryfikowana ścieżka Serve pomija też rundę parowania urządzenia; przeglądarki bez urządzenia i połączenia w roli węzła nadal przechodzą normalne sprawdzenia urządzenia. Ustaw `gateway.auth.allowTailscale: false`, jeśli chcesz wymagać jawnych poświadczeń wspólnego sekretu nawet dla ruchu Serve. Następnie użyj `gateway.auth.mode: "token"` lub `"password"`.
|
||||
|
||||
Dla tej asynchronicznej ścieżki tożsamości Serve nieudane próby uwierzytelniania dla tego samego IP klienta i zakresu uwierzytelniania są serializowane przed zapisami limitu szybkości. Równoczesne błędne ponowienia z tej samej przeglądarki mogą więc pokazać `retry later` przy drugim żądaniu zamiast dwóch zwykłych niedopasowań ścigających się równolegle.
|
||||
Dla tej asynchronicznej ścieżki tożsamości Serve nieudane próby uwierzytelnienia dla tego samego adresu IP klienta i zakresu uwierzytelniania są serializowane przed zapisami limitu szybkości. Współbieżne błędne ponowienia z tej samej przeglądarki mogą więc pokazać `retry later` przy drugim żądaniu zamiast dwóch zwykłych niedopasowań ścigających się równolegle.
|
||||
|
||||
<Warning>
|
||||
Uwierzytelnianie Serve bez tokena zakłada, że host gateway jest zaufany. Jeśli niezaufany kod lokalny może działać na tym hoście, wymagaj uwierzytelniania tokenem/hasłem.
|
||||
Uwierzytelnianie Serve bez tokena zakłada, że host gatewaya jest zaufany. Jeśli na tym hoście może działać niezaufany kod lokalny, wymagaj uwierzytelniania tokenem/hasłem.
|
||||
</Warning>
|
||||
|
||||
</Tab>
|
||||
<Tab title="Powiąż z tailnetem + token">
|
||||
<Tab title="Powiązanie z tailnet + token">
|
||||
```bash
|
||||
openclaw gateway --bind tailnet --token "$(openssl rand -hex 32)"
|
||||
```
|
||||
|
||||
Następnie otwórz:
|
||||
|
||||
- `http://<tailscale-ip>:18789/` (lub skonfigurowane `gateway.controlUi.basePath`)
|
||||
- `http://<tailscale-ip>:18789/` (lub skonfigurowany `gateway.controlUi.basePath`)
|
||||
|
||||
Wklej pasujący współdzielony sekret w ustawieniach UI (wysyłany jako `connect.params.auth.token` lub `connect.params.auth.password`).
|
||||
Wklej pasujący wspólny sekret w ustawieniach UI (wysyłany jako `connect.params.auth.token` lub `connect.params.auth.password`).
|
||||
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
## Niezabezpieczone HTTP
|
||||
## Niezabezpieczony HTTP
|
||||
|
||||
Jeśli otworzysz panel przez zwykłe HTTP (`http://<lan-ip>` lub `http://<tailscale-ip>`), przeglądarka działa w **niezabezpieczonym kontekście** i blokuje WebCrypto. Domyślnie OpenClaw **blokuje** połączenia Control UI bez tożsamości urządzenia.
|
||||
Jeśli otworzysz pulpit przez zwykły HTTP (`http://<lan-ip>` lub `http://<tailscale-ip>`), przeglądarka działa w **niezabezpieczonym kontekście** i blokuje WebCrypto. Domyślnie OpenClaw **blokuje** połączenia Control UI bez tożsamości urządzenia.
|
||||
|
||||
Udokumentowane wyjątki:
|
||||
|
||||
- zgodność niezabezpieczonego HTTP tylko dla localhost z `gateway.controlUi.allowInsecureAuth=true`
|
||||
- udane uwierzytelnienie operatora Control UI przez `gateway.auth.mode: "trusted-proxy"`
|
||||
- pomyślne uwierzytelnianie operatora Control UI przez `gateway.auth.mode: "trusted-proxy"`
|
||||
- awaryjne `gateway.controlUi.dangerouslyDisableDeviceAuth=true`
|
||||
|
||||
**Zalecana poprawka:** użyj HTTPS (Tailscale Serve) albo otwórz UI lokalnie:
|
||||
@ -335,11 +335,11 @@ Udokumentowane wyjątki:
|
||||
}
|
||||
```
|
||||
|
||||
`allowInsecureAuth` jest wyłącznie lokalnym przełącznikiem zgodności:
|
||||
`allowInsecureAuth` to wyłącznie lokalny przełącznik zgodności:
|
||||
|
||||
- Pozwala lokalnym sesjom Control UI kontynuować bez tożsamości urządzenia w niezabezpieczonych kontekstach HTTP.
|
||||
- Pozwala sesjom localhost Control UI działać bez tożsamości urządzenia w niezabezpieczonych kontekstach HTTP.
|
||||
- Nie omija kontroli parowania.
|
||||
- Nie rozluźnia wymagań dotyczących tożsamości urządzenia dla zdalnych (innych niż localhost) połączeń.
|
||||
- Nie rozluźnia wymagań dotyczących tożsamości urządzenia zdalnego (spoza localhost).
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Tylko tryb awaryjny">
|
||||
@ -354,14 +354,14 @@ Udokumentowane wyjątki:
|
||||
```
|
||||
|
||||
<Warning>
|
||||
`dangerouslyDisableDeviceAuth` wyłącza kontrole tożsamości urządzenia w Control UI i stanowi poważne obniżenie poziomu bezpieczeństwa. Cofnij to szybko po użyciu awaryjnym.
|
||||
`dangerouslyDisableDeviceAuth` wyłącza kontrole tożsamości urządzenia w Control UI i jest poważnym obniżeniem poziomu zabezpieczeń. Cofnij tę zmianę szybko po użyciu awaryjnym.
|
||||
</Warning>
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Uwaga o zaufanym proxy">
|
||||
- Pomyślne uwierzytelnienie zaufanego proxy może dopuścić sesje Control UI **operatora** bez tożsamości urządzenia.
|
||||
- Nie obejmuje to sesji Control UI w roli węzła.
|
||||
- Zwrotne reverse proxy na tym samym hoście nadal nie spełniają wymagań uwierzytelnienia zaufanego proxy; zobacz [Uwierzytelnianie zaufanego proxy](/pl/gateway/trusted-proxy-auth).
|
||||
- Pomyślne uwierzytelnianie przez zaufane proxy może dopuścić sesje **operatora** Control UI bez tożsamości urządzenia.
|
||||
- Nie obejmuje to sesji Control UI z rolą węzła.
|
||||
- Zwrotne proxy loopback na tym samym hoście nadal nie spełniają wymagań uwierzytelniania zaufanego proxy; zobacz [Uwierzytelnianie zaufanego proxy](/pl/gateway/trusted-proxy-auth).
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
@ -370,7 +370,7 @@ Zobacz [Tailscale](/pl/gateway/tailscale), aby uzyskać wskazówki dotyczące ko
|
||||
|
||||
## Zasady bezpieczeństwa treści
|
||||
|
||||
Control UI jest dostarczane z rygorystyczną zasadą `img-src`: dozwolone są tylko zasoby **same-origin**, adresy URL `data:` oraz lokalnie wygenerowane adresy URL `blob:`. Zdalne adresy URL obrazów `http(s)` i względne względem protokołu są odrzucane przez przeglądarkę i nie powodują wysłania żądań sieciowych.
|
||||
Control UI jest dostarczany ze ścisłą polityką `img-src`: dozwolone są tylko zasoby **z tego samego źródła**, adresy URL `data:` i lokalnie wygenerowane adresy URL `blob:`. Zdalne adresy URL obrazów `http(s)` i względne względem protokołu są odrzucane przez przeglądarkę i nie powodują wysyłania żądań sieciowych.
|
||||
|
||||
Co to oznacza w praktyce:
|
||||
|
||||
@ -379,33 +379,43 @@ Co to oznacza w praktyce:
|
||||
- Lokalne adresy URL `blob:` utworzone przez Control UI nadal się renderują.
|
||||
- Zdalne adresy URL awatarów emitowane przez metadane kanałów są usuwane przez pomocnicze funkcje awatarów Control UI i zastępowane wbudowanym logo/odznaką, więc przejęty lub złośliwy kanał nie może wymusić dowolnych zdalnych pobrań obrazów z przeglądarki operatora.
|
||||
|
||||
Nie musisz nic zmieniać, aby uzyskać to zachowanie — jest zawsze włączone i nie można go konfigurować.
|
||||
Nie musisz niczego zmieniać, aby uzyskać to zachowanie — jest ono zawsze włączone i nie można go konfigurować.
|
||||
|
||||
## Uwierzytelnianie trasy awatara
|
||||
## Uwierzytelnianie trasy awatarów
|
||||
|
||||
Gdy uwierzytelnianie Gateway jest skonfigurowane, punkt końcowy awatara Control UI wymaga tego samego tokenu gateway co reszta API:
|
||||
Gdy uwierzytelnianie gateway jest skonfigurowane, punkt końcowy awatarów Control UI wymaga tego samego tokenu gateway co reszta API:
|
||||
|
||||
- `GET /avatar/<agentId>` zwraca obraz awatara tylko uwierzytelnionym wywołującym. `GET /avatar/<agentId>?meta=1` zwraca metadane awatara zgodnie z tą samą regułą.
|
||||
- Nieuwierzytelnione żądania do którejkolwiek z tras są odrzucane (tak jak w sąsiedniej trasie assistant-media). Zapobiega to wyciekowi tożsamości agenta przez trasę awatara na hostach, które poza tym są chronione.
|
||||
- Control UI samo przekazuje token gateway jako nagłówek bearer podczas pobierania awatarów i używa uwierzytelnionych adresów URL blob, dzięki czemu obraz nadal renderuje się w dashboardach.
|
||||
- `GET /avatar/<agentId>` zwraca obraz awatara tylko uwierzytelnionym wywołującym. `GET /avatar/<agentId>?meta=1` zwraca metadane awatara na tej samej zasadzie.
|
||||
- Nieuwierzytelnione żądania do dowolnej z tych tras są odrzucane (tak jak w siostrzanej trasie assistant-media). Zapobiega to ujawnianiu tożsamości agenta przez trasę awatara na hostach, które poza tym są chronione.
|
||||
- Sam Control UI przekazuje token gateway jako nagłówek bearer podczas pobierania awatarów i używa uwierzytelnionych adresów URL blob, dzięki czemu obraz nadal renderuje się w dashboardach.
|
||||
|
||||
Jeśli wyłączysz uwierzytelnianie gateway (niezalecane na współdzielonych hostach), trasa awatara również stanie się nieuwierzytelniona, zgodnie z resztą gateway.
|
||||
Jeśli wyłączysz uwierzytelnianie gateway (niezalecane na hostach współdzielonych), trasa awatara również staje się nieuwierzytelniona, zgodnie z resztą gateway.
|
||||
|
||||
## Uwierzytelnianie trasy multimediów asystenta
|
||||
|
||||
Gdy uwierzytelnianie gateway jest skonfigurowane, lokalne podglądy multimediów asystenta używają dwuetapowej trasy:
|
||||
|
||||
- `GET /__openclaw__/assistant-media?meta=1&source=<path>` wymaga standardowego uwierzytelniania operatora Control UI. Przeglądarka wysyła token gateway jako nagłówek bearer podczas sprawdzania dostępności.
|
||||
- Pomyślne odpowiedzi metadanych zawierają krótkotrwały `mediaTicket` ograniczony do dokładnie tej ścieżki źródłowej.
|
||||
- Renderowane przez przeglądarkę adresy URL obrazów, audio, wideo i dokumentów używają `mediaTicket=<ticket>` zamiast aktywnego tokenu lub hasła gateway. Bilet szybko wygasa i nie może autoryzować innego źródła.
|
||||
|
||||
Dzięki temu zwykłe renderowanie multimediów pozostaje zgodne z natywnymi elementami multimedialnymi przeglądarki bez umieszczania wielokrotnego użytku poświadczeń gateway w widocznych adresach URL multimediów.
|
||||
|
||||
## Budowanie UI
|
||||
|
||||
Gateway serwuje pliki statyczne z `dist/control-ui`. Zbuduj je za pomocą:
|
||||
Gateway serwuje pliki statyczne z `dist/control-ui`. Zbuduj je poleceniem:
|
||||
|
||||
```bash
|
||||
pnpm ui:build
|
||||
```
|
||||
|
||||
Opcjonalna bezwzględna baza (gdy chcesz stałe adresy URL zasobów):
|
||||
Opcjonalna bezwzględna baza (gdy chcesz stałych adresów URL zasobów):
|
||||
|
||||
```bash
|
||||
OPENCLAW_CONTROL_UI_BASE_PATH=/openclaw/ pnpm ui:build
|
||||
```
|
||||
|
||||
Do lokalnego rozwoju (osobny serwer deweloperski):
|
||||
Do lokalnego programowania (osobny serwer deweloperski):
|
||||
|
||||
```bash
|
||||
pnpm ui:dev
|
||||
@ -415,7 +425,7 @@ Następnie skieruj UI na adres URL WS swojego Gateway (np. `ws://127.0.0.1:18789
|
||||
|
||||
## Debugowanie/testowanie: serwer deweloperski + zdalny Gateway
|
||||
|
||||
Control UI to pliki statyczne; cel WebSocket jest konfigurowalny i może być inny niż origin HTTP. To przydatne, gdy chcesz używać lokalnego serwera deweloperskiego Vite, ale Gateway działa gdzie indziej.
|
||||
Control UI to pliki statyczne; cel WebSocket jest konfigurowalny i może różnić się od źródła HTTP. Jest to przydatne, gdy chcesz używać lokalnie serwera deweloperskiego Vite, ale Gateway działa gdzie indziej.
|
||||
|
||||
<Steps>
|
||||
<Step title="Uruchom serwer deweloperski UI">
|
||||
@ -428,7 +438,7 @@ Control UI to pliki statyczne; cel WebSocket jest konfigurowalny i może być in
|
||||
http://localhost:5173/?gatewayUrl=ws%3A%2F%2F<gateway-host>%3A18789
|
||||
```
|
||||
|
||||
Opcjonalne jednorazowe uwierzytelnienie (jeśli potrzebne):
|
||||
Opcjonalne jednorazowe uwierzytelnianie (jeśli potrzebne):
|
||||
|
||||
```text
|
||||
http://localhost:5173/?gatewayUrl=wss%3A%2F%2F<gateway-host>%3A18789#token=<gateway-token>
|
||||
@ -439,17 +449,17 @@ Control UI to pliki statyczne; cel WebSocket jest konfigurowalny i może być in
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Uwagi">
|
||||
- `gatewayUrl` jest zapisywany w localStorage po załadowaniu i usuwany z adresu URL.
|
||||
- Jeśli przekazujesz pełny punkt końcowy `ws://` lub `wss://` przez `gatewayUrl`, zakoduj wartość `gatewayUrl` jako URL, aby przeglądarka poprawnie przeanalizowała ciąg zapytania.
|
||||
- `token` należy przekazywać przez fragment adresu URL (`#token=...`), gdy tylko jest to możliwe. Fragmenty nie są wysyłane do serwera, co zapobiega wyciekom w logach żądań i Referer. Starsze parametry zapytania `?token=` są nadal jednorazowo importowane dla zgodności, ale tylko jako rozwiązanie awaryjne, i są usuwane natychmiast po inicjalizacji.
|
||||
- `password` jest przechowywane tylko w pamięci.
|
||||
- Gdy `gatewayUrl` jest ustawione, UI nie wraca do danych uwierzytelniających z konfiguracji ani środowiska. Podaj jawnie `token` (lub `password`). Brak jawnych danych uwierzytelniających jest błędem.
|
||||
- Używaj `wss://`, gdy Gateway znajduje się za TLS (Tailscale Serve, proxy HTTPS itd.).
|
||||
- `gatewayUrl` jest akceptowane tylko w oknie najwyższego poziomu (nie osadzone), aby zapobiec clickjackingowi.
|
||||
- Nielokalne wdrożenia Control UI muszą jawnie ustawić `gateway.controlUi.allowedOrigins` (pełne origins). Obejmuje to zdalne konfiguracje deweloperskie.
|
||||
- Start Gateway może zasiać lokalne origins, takie jak `http://localhost:<port>` i `http://127.0.0.1:<port>`, na podstawie efektywnego wiązania i portu runtime, ale origins zdalnych przeglądarek nadal wymagają jawnych wpisów.
|
||||
- Nie używaj `gateway.controlUi.allowedOrigins: ["*"]` poza ściśle kontrolowanym lokalnym testowaniem. Oznacza to zezwolenie na dowolny origin przeglądarki, a nie „dopasuj dowolny host, którego używam”.
|
||||
- `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback=true` włącza tryb awaryjny origin na podstawie nagłówka Host, ale jest to niebezpieczny tryb bezpieczeństwa.
|
||||
- `gatewayUrl` jest zapisywany w localStorage po wczytaniu i usuwany z adresu URL.
|
||||
- Jeśli przekazujesz pełny punkt końcowy `ws://` lub `wss://` przez `gatewayUrl`, zakoduj wartość `gatewayUrl` w URL, aby przeglądarka poprawnie sparsowała ciąg zapytania.
|
||||
- `token` należy przekazywać przez fragment adresu URL (`#token=...`), gdy tylko to możliwe. Fragmenty nie są wysyłane do serwera, co pozwala uniknąć wycieku w logach żądań i nagłówku Referer. Starsze parametry zapytania `?token=` nadal są importowane jednorazowo dla zgodności, ale tylko jako rozwiązanie awaryjne, i są usuwane natychmiast po bootstrapie.
|
||||
- `password` jest przechowywane wyłącznie w pamięci.
|
||||
- Gdy ustawiono `gatewayUrl`, UI nie wraca do poświadczeń z konfiguracji ani środowiska. Podaj jawnie `token` (lub `password`). Brak jawnych poświadczeń jest błędem.
|
||||
- Użyj `wss://`, gdy Gateway znajduje się za TLS (Tailscale Serve, proxy HTTPS itd.).
|
||||
- `gatewayUrl` jest akceptowany tylko w oknie najwyższego poziomu (nie osadzonym), aby zapobiec clickjackingowi.
|
||||
- Wdrożenia Control UI poza loopback muszą jawnie ustawić `gateway.controlUi.allowedOrigins` (pełne źródła). Obejmuje to zdalne konfiguracje deweloperskie.
|
||||
- Uruchomienie Gateway może zasilić lokalne źródła, takie jak `http://localhost:<port>` i `http://127.0.0.1:<port>`, na podstawie efektywnego bindowania i portu środowiska uruchomieniowego, ale zdalne źródła przeglądarki nadal wymagają jawnych wpisów.
|
||||
- Nie używaj `gateway.controlUi.allowedOrigins: ["*"]` poza ściśle kontrolowanym lokalnym testowaniem. Oznacza to zezwolenie na dowolne źródło przeglądarki, a nie „dopasuj dowolny host, którego używam”.
|
||||
- `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback=true` włącza tryb awaryjnego użycia źródła z nagłówka Host, ale jest to niebezpieczny tryb zabezpieczeń.
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
@ -466,11 +476,11 @@ Przykład:
|
||||
}
|
||||
```
|
||||
|
||||
Szczegóły konfiguracji zdalnego dostępu: [Zdalny dostęp](/pl/gateway/remote).
|
||||
Szczegóły konfiguracji dostępu zdalnego: [Dostęp zdalny](/pl/gateway/remote).
|
||||
|
||||
## Powiązane
|
||||
|
||||
- [Dashboard](/pl/web/dashboard) — dashboard gateway
|
||||
- [Kontrole kondycji](/pl/gateway/health) — monitorowanie kondycji gateway
|
||||
- [TUI](/pl/web/tui) — terminalowy interfejs użytkownika
|
||||
- [WebChat](/pl/web/webchat) — interfejs czatu w przeglądarce
|
||||
- [WebChat](/pl/web/webchat) — interfejs czatu oparty na przeglądarce
|
||||
|
||||
Loading…
Reference in New Issue
Block a user