chore(i18n): refresh pl translations
This commit is contained in:
openclaw-docs-i18n[bot]
parent
6f6e9b6d4a
commit
08f7e3c846
@ -2,45 +2,41 @@
|
||||
read_when:
|
||||
- Sprawdzanie trwających lub niedawno zakończonych zadań w tle
|
||||
- Debugowanie błędów dostarczania dla odłączonych uruchomień agentów
|
||||
- Zrozumienie, jak uruchomienia w tle są powiązane z sesjami, cron i heartbeat
|
||||
summary: Śledzenie zadań w tle dla uruchomień ACP, subagentów, izolowanych zadań cron i operacji CLI
|
||||
- Zrozumienie, jak uruchomienia w tle odnoszą się do sesji, cron i heartbeat
|
||||
summary: Śledzenie zadań w tle dla uruchomień ACP, podagentów, izolowanych zadań cron i operacji CLI
|
||||
title: Zadania w tle
|
||||
x-i18n:
|
||||
generated_at: "2026-04-06T03:07:01Z"
|
||||
generated_at: "2026-04-10T09:44:53Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 2f56c1ac23237907a090c69c920c09578a2f56f5d8bf750c7f2136c603c8a8ff
|
||||
source_hash: d7b5ba41f1025e0089986342ce85698bc62f676439c3ccf03f3ed146beb1b1ac
|
||||
source_path: automation/tasks.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Zadania w tle
|
||||
|
||||
> **Szukasz planowania?** Zobacz [Automation & Tasks](/pl/automation), aby wybrać właściwy mechanizm. Ta strona dotyczy **śledzenia** pracy w tle, a nie jej planowania.
|
||||
> **Szukasz harmonogramowania?** Zobacz [Automatyzacja i zadania](/pl/automation), aby wybrać właściwy mechanizm. Ta strona dotyczy **śledzenia** pracy w tle, a nie jej harmonogramowania.
|
||||
|
||||
Zadania w tle śledzą pracę wykonywaną **poza główną sesją rozmowy**:
|
||||
uruchomienia ACP, uruchomienia subagentów, wykonania izolowanych zadań cron oraz operacje inicjowane przez CLI.
|
||||
Zadania w tle śledzą pracę uruchamianą **poza główną sesją rozmowy**:
|
||||
uruchomienia ACP, tworzenie podagentów, izolowane wykonania zadań cron oraz operacje inicjowane przez CLI.
|
||||
|
||||
Zadania **nie** zastępują sesji, zadań cron ani heartbeat — są **rejestrem aktywności**, który zapisuje, jaka odłączona praca została wykonana, kiedy i czy zakończyła się powodzeniem.
|
||||
|
||||
<Note>
|
||||
Nie każde uruchomienie agenta tworzy zadanie. Tury heartbeat i zwykły interaktywny czat tego nie robią. Wszystkie wykonania cron, uruchomienia ACP, uruchomienia subagentów i polecenia agenta z CLI tworzą zadania.
|
||||
Nie każde uruchomienie agenta tworzy zadanie. Tury heartbeat i zwykły interaktywny czat tego nie robią. Wszystkie wykonania cron, uruchomienia ACP, uruchomienia podagentów i polecenia agenta z CLI tworzą zadania.
|
||||
</Note>
|
||||
|
||||
## TL;DR
|
||||
## W skrócie
|
||||
|
||||
- Zadania to **rekordy**, a nie harmonogramy — cron i heartbeat decydują, _kiedy_ praca jest uruchamiana, a zadania śledzą, _co się wydarzyło_.
|
||||
- ACP, subagenty, wszystkie zadania cron i operacje CLI tworzą zadania. Tury heartbeat nie.
|
||||
- Każde zadanie przechodzi przez `queued → running → terminal` (`succeeded`, `failed`, `timed_out`, `cancelled` lub `lost`).
|
||||
- Zadania cron pozostają aktywne, dopóki środowisko uruchomieniowe cron nadal jest właścicielem zadania; zadania CLI oparte na czacie pozostają aktywne tylko wtedy, gdy ich kontekst uruchomienia właściciela nadal jest aktywny.
|
||||
- Zakończenie jest sterowane przez push: odłączona praca może powiadomić bezpośrednio lub wybudzić
|
||||
sesję żądającą/heartbeat po zakończeniu, więc pętle odpytywania stanu
|
||||
zwykle nie są właściwym rozwiązaniem.
|
||||
- Izolowane uruchomienia cron i zakończenia subagentów w trybie best-effort czyszczą śledzone karty/procesy przeglądarki dla swojej sesji podrzędnej przed końcowym rozliczeniem czyszczenia.
|
||||
- Dostarczanie izolowanych uruchomień cron pomija nieaktualne pośrednie odpowiedzi nadrzędne, gdy
|
||||
praca potomnych subagentów nadal się opróżnia, i preferuje końcowe dane wyjściowe potomka,
|
||||
jeśli dotrą przed dostarczeniem.
|
||||
- Powiadomienia o zakończeniu są dostarczane bezpośrednio do kanału lub umieszczane w kolejce do następnego heartbeat.
|
||||
- ACP, podagenci, wszystkie zadania cron i operacje CLI tworzą zadania. Tury heartbeat nie.
|
||||
- Każde zadanie przechodzi przez `queued → running → terminal` (succeeded, failed, timed_out, cancelled lub lost).
|
||||
- Zadania cron pozostają aktywne, dopóki środowisko uruchomieniowe cron nadal jest właścicielem zadania; zadania CLI powiązane z czatem pozostają aktywne tylko tak długo, jak długo aktywny jest ich kontekst uruchomienia.
|
||||
- Zakończenie jest obsługiwane przez mechanizm push: odłączona praca może powiadomić bezpośrednio albo wybudzić sesję żądającą/heartbeat po zakończeniu, więc pętle odpytywania o status zwykle nie są właściwym rozwiązaniem.
|
||||
- Izolowane uruchomienia cron i zakończenia podagentów w miarę możliwości porządkują śledzone karty/procesy przeglądarki dla swojej sesji podrzędnej przed końcowym rozliczeniem czyszczenia.
|
||||
- Dostarczanie dla izolowanego cron pomija nieaktualne tymczasowe odpowiedzi nadrzędne, gdy praca podrzędnych podagentów nadal się kończy, i preferuje końcowe dane wyjściowe potomka, jeśli dotrą przed dostarczeniem.
|
||||
- Powiadomienia o zakończeniu są dostarczane bezpośrednio do kanału lub kolejkowane do następnego heartbeat.
|
||||
- `openclaw tasks list` pokazuje wszystkie zadania; `openclaw tasks audit` ujawnia problemy.
|
||||
- Rekordy terminalne są przechowywane przez 7 dni, a następnie automatycznie usuwane.
|
||||
|
||||
@ -57,7 +53,7 @@ openclaw tasks list --status running
|
||||
# Pokaż szczegóły konkretnego zadania (według ID, ID uruchomienia lub klucza sesji)
|
||||
openclaw tasks show <lookup>
|
||||
|
||||
# Anuluj działające zadanie (zabija sesję podrzędną)
|
||||
# Anuluj uruchomione zadanie (zabija sesję podrzędną)
|
||||
openclaw tasks cancel <lookup>
|
||||
|
||||
# Zmień politykę powiadomień dla zadania
|
||||
@ -70,7 +66,7 @@ openclaw tasks audit
|
||||
openclaw tasks maintenance
|
||||
openclaw tasks maintenance --apply
|
||||
|
||||
# Sprawdź stan Task Flow
|
||||
# Sprawdź stan TaskFlow
|
||||
openclaw tasks flow list
|
||||
openclaw tasks flow show <lookup>
|
||||
openclaw tasks flow cancel <lookup>
|
||||
@ -79,18 +75,18 @@ openclaw tasks flow cancel <lookup>
|
||||
## Co tworzy zadanie
|
||||
|
||||
| Źródło | Typ środowiska uruchomieniowego | Kiedy tworzony jest rekord zadania | Domyślna polityka powiadomień |
|
||||
| ---------------------- | ------------------------------- | ------------------------------------------------------ | ----------------------------- |
|
||||
| Uruchomienia ACP w tle | `acp` | Utworzenie podrzędnej sesji ACP | `done_only` |
|
||||
| Orkiestracja subagentów | `subagent` | Uruchomienie subagenta przez `sessions_spawn` | `done_only` |
|
||||
| Zadania cron (wszystkie typy) | `cron` | Każde wykonanie cron (sesja główna i izolowana) | `silent` |
|
||||
| Operacje CLI | `cli` | Polecenia `openclaw agent` uruchamiane przez gateway | `silent` |
|
||||
| Zadania mediów agenta | `cli` | Uruchomienia `video_generate` powiązane z sesją | `silent` |
|
||||
| ---------------------- | -------------------------------- | ------------------------------------------------------ | ----------------------------- |
|
||||
| Uruchomienia ACP w tle | `acp` | Utworzenie podrzędnej sesji ACP | `done_only` |
|
||||
| Orkiestracja podagentów | `subagent` | Utworzenie podagenta przez `sessions_spawn` | `done_only` |
|
||||
| Zadania cron (wszystkie typy) | `cron` | Każde wykonanie cron (sesja główna i izolowana) | `silent` |
|
||||
| Operacje CLI | `cli` | Polecenia `openclaw agent` uruchamiane przez gateway | `silent` |
|
||||
| Zadania medialne agenta | `cli` | Uruchomienia `video_generate` powiązane z sesją | `silent` |
|
||||
|
||||
Zadania cron w sesji głównej domyślnie używają polityki powiadomień `silent` — tworzą rekordy do śledzenia, ale nie generują powiadomień. Izolowane zadania cron również domyślnie używają `silent`, ale są bardziej widoczne, ponieważ działają we własnej sesji.
|
||||
|
||||
Uruchomienia `video_generate` powiązane z sesją również używają polityki powiadomień `silent`. Nadal tworzą rekordy zadań, ale zakończenie jest przekazywane z powrotem do oryginalnej sesji agenta jako wewnętrzne wybudzenie, aby agent mógł sam napisać wiadomość uzupełniającą i dołączyć gotowy film. Jeśli włączysz `tools.media.asyncCompletion.directSend`, asynchroniczne zakończenia `music_generate` i `video_generate` najpierw próbują bezpośredniego dostarczenia do kanału, a dopiero potem wracają do ścieżki wybudzenia sesji żądającej.
|
||||
Uruchomienia `video_generate` powiązane z sesją także używają domyślnie polityki powiadomień `silent`. Nadal tworzą rekordy zadań, ale zakończenie jest przekazywane z powrotem do oryginalnej sesji agenta jako wewnętrzne wybudzenie, aby agent mógł sam napisać wiadomość uzupełniającą i dołączyć gotowy film. Jeśli włączysz `tools.media.asyncCompletion.directSend`, asynchroniczne zakończenia `music_generate` i `video_generate` najpierw próbują bezpośredniego dostarczenia do kanału, a dopiero potem wracają do ścieżki wybudzenia sesji żądającej.
|
||||
|
||||
Gdy zadanie `video_generate` powiązane z sesją jest nadal aktywne, narzędzie działa też jako zabezpieczenie: powtarzane wywołania `video_generate` w tej samej sesji zwracają status aktywnego zadania zamiast uruchamiać drugie równoległe generowanie. Użyj `action: "status"`, gdy chcesz uzyskać jawne sprawdzenie postępu/statusu po stronie agenta.
|
||||
Gdy zadanie `video_generate` powiązane z sesją jest nadal aktywne, narzędzie działa również jako zabezpieczenie: powtórzone wywołania `video_generate` w tej samej sesji zwracają status aktywnego zadania zamiast uruchamiać drugie równoległe generowanie. Użyj `action: "status"`, gdy chcesz wykonać jawne sprawdzenie postępu/statusu po stronie agenta.
|
||||
|
||||
**Co nie tworzy zadań:**
|
||||
|
||||
@ -112,52 +108,50 @@ stateDiagram-v2
|
||||
running --> lost : session gone > 5 min
|
||||
```
|
||||
|
||||
| Status | Co oznacza |
|
||||
| ----------- | ------------------------------------------------------------------------- |
|
||||
| `queued` | Utworzone, oczekuje na uruchomienie przez agenta |
|
||||
| `running` | Tura agenta jest aktywnie wykonywana |
|
||||
| `succeeded` | Zakończone pomyślnie |
|
||||
| `failed` | Zakończone błędem |
|
||||
| `timed_out` | Przekroczono skonfigurowany limit czasu |
|
||||
| `cancelled` | Zatrzymane przez operatora przez `openclaw tasks cancel` |
|
||||
| Status | Co oznacza |
|
||||
| ----------- | ------------------------------------------------------------------------ |
|
||||
| `queued` | Utworzone, oczekuje na uruchomienie przez agenta |
|
||||
| `running` | Tura agenta jest aktywnie wykonywana |
|
||||
| `succeeded` | Zakończone pomyślnie |
|
||||
| `failed` | Zakończone błędem |
|
||||
| `timed_out` | Przekroczono skonfigurowany limit czasu |
|
||||
| `cancelled` | Zatrzymane przez operatora za pomocą `openclaw tasks cancel` |
|
||||
| `lost` | Środowisko uruchomieniowe utraciło autorytatywny stan zaplecza po 5-minutowym okresie karencji |
|
||||
|
||||
Przejścia zachodzą automatycznie — gdy powiązane uruchomienie agenta się kończy, status zadania jest aktualizowany odpowiednio do wyniku.
|
||||
Przejścia zachodzą automatycznie — gdy skojarzone uruchomienie agenta się kończy, status zadania aktualizuje się odpowiednio.
|
||||
|
||||
`lost` jest zależne od środowiska uruchomieniowego:
|
||||
|
||||
- Zadania ACP: zniknęły metadane podrzędnej sesji ACP w zapleczu.
|
||||
- Zadania subagentów: podrzędna sesja zniknęła z docelowego magazynu agenta.
|
||||
- Zadania ACP: zniknęły metadane podrzędnej sesji ACP.
|
||||
- Zadania podagentów: podrzędna sesja zniknęła z docelowego magazynu agenta.
|
||||
- Zadania cron: środowisko uruchomieniowe cron nie śledzi już zadania jako aktywnego.
|
||||
- Zadania CLI: izolowane zadania sesji podrzędnej używają sesji podrzędnej; zadania CLI oparte na czacie używają zamiast tego aktywnego kontekstu uruchomienia, więc pozostające wiersze sesji kanału/grupy/bezpośredniej nie utrzymują ich przy życiu.
|
||||
- Zadania CLI: izolowane zadania sesji podrzędnej używają sesji podrzędnej; zadania CLI powiązane z czatem używają zamiast tego aktywnego kontekstu uruchomienia, więc utrzymujące się wiersze sesji kanału/grupy/wiadomości bezpośredniej nie podtrzymują ich aktywności.
|
||||
|
||||
## Dostarczanie i powiadomienia
|
||||
|
||||
Gdy zadanie osiągnie stan terminalny, OpenClaw Cię powiadomi. Istnieją dwie ścieżki dostarczania:
|
||||
|
||||
**Dostarczenie bezpośrednie** — jeśli zadanie ma cel kanałowy (`requesterOrigin`), wiadomość o zakończeniu trafia bezpośrednio do tego kanału (Telegram, Discord, Slack itd.). W przypadku zakończeń subagentów OpenClaw zachowuje też powiązane kierowanie do wątku/tematu, gdy jest dostępne, i może uzupełnić brakujące `to` / konto z zapisanej trasy sesji żądającej (`lastChannel` / `lastTo` / `lastAccountId`), zanim zrezygnuje z bezpośredniego dostarczenia.
|
||||
**Dostarczenie bezpośrednie** — jeśli zadanie ma docelowy kanał (`requesterOrigin`), wiadomość o zakończeniu trafia bezpośrednio do tego kanału (Telegram, Discord, Slack itd.). W przypadku zakończeń podagentów OpenClaw zachowuje również powiązane trasowanie wątku/tematu, jeśli jest dostępne, i może uzupełnić brakujące `to` / konto z zapisanej trasy sesji żądającej (`lastChannel` / `lastTo` / `lastAccountId`), zanim zrezygnuje z bezpośredniego dostarczenia.
|
||||
|
||||
**Dostarczenie w kolejce sesji** — jeśli bezpośrednie dostarczenie się nie powiedzie lub nie ustawiono źródła, aktualizacja jest umieszczana w kolejce jako zdarzenie systemowe w sesji żądającego i pojawia się przy następnym heartbeat.
|
||||
**Dostarczenie kolejkowane do sesji** — jeśli dostarczenie bezpośrednie się nie powiedzie albo nie ustawiono źródła, aktualizacja jest kolejkowana jako zdarzenie systemowe w sesji żądającej i pojawia się przy następnym heartbeat.
|
||||
|
||||
<Tip>
|
||||
Zakończenie zadania natychmiast wyzwala wybudzenie heartbeat, więc wynik zobaczysz szybko — nie musisz czekać na następny zaplanowany tick heartbeat.
|
||||
Zakończenie zadania wywołuje natychmiastowe wybudzenie heartbeat, dzięki czemu szybko widzisz wynik — nie musisz czekać na następny zaplanowany tick heartbeat.
|
||||
</Tip>
|
||||
|
||||
Oznacza to, że typowy przepływ pracy opiera się na push: uruchom odłączoną pracę raz, a następnie pozwól
|
||||
środowisku uruchomieniowemu wybudzić Cię lub powiadomić po zakończeniu. Odpytuj stan zadania tylko wtedy, gdy
|
||||
potrzebujesz debugowania, interwencji lub jawnego audytu.
|
||||
Oznacza to, że zwykły przepływ pracy jest oparty na mechanizmie push: uruchom odłączoną pracę raz, a następnie pozwól środowisku uruchomieniowemu wybudzić Cię lub powiadomić po zakończeniu. Odpytuj stan zadania tylko wtedy, gdy potrzebujesz debugowania, interwencji lub jawnego audytu.
|
||||
|
||||
### Polityki powiadomień
|
||||
|
||||
Określają, jak dużo informacji otrzymujesz o każdym zadaniu:
|
||||
Kontrolują, jak dużo informacji otrzymujesz o każdym zadaniu:
|
||||
|
||||
| Polityka | Co jest dostarczane |
|
||||
| -------------------- | ------------------------------------------------------------------------ |
|
||||
| `done_only` (domyślna) | Tylko stan terminalny (`succeeded`, `failed` itd.) — **to ustawienie domyślne** |
|
||||
| `state_changes` | Każda zmiana stanu i aktualizacja postępu |
|
||||
| `silent` | Nic |
|
||||
| Polityka | Co jest dostarczane |
|
||||
| --------------------- | ------------------------------------------------------------------------- |
|
||||
| `done_only` (domyślna) | Tylko stan terminalny (succeeded, failed itd.) — **to ustawienie domyślne** |
|
||||
| `state_changes` | Każda zmiana stanu i aktualizacja postępu |
|
||||
| `silent` | Nic |
|
||||
|
||||
Zmień politykę, gdy zadanie jest uruchomione:
|
||||
Zmień politykę podczas działania zadania:
|
||||
|
||||
```bash
|
||||
openclaw tasks notify <lookup> state_changes
|
||||
@ -179,7 +173,7 @@ Kolumny wyjściowe: ID zadania, rodzaj, status, dostarczenie, ID uruchomienia, s
|
||||
openclaw tasks show <lookup>
|
||||
```
|
||||
|
||||
Token wyszukiwania akceptuje ID zadania, ID uruchomienia lub klucz sesji. Pokazuje pełny rekord zawierający czas, stan dostarczenia, błąd i podsumowanie terminalne.
|
||||
Token lookup akceptuje ID zadania, ID uruchomienia lub klucz sesji. Pokazuje pełny rekord, w tym czasy, stan dostarczenia, błąd i terminalne podsumowanie.
|
||||
|
||||
### `tasks cancel`
|
||||
|
||||
@ -187,7 +181,7 @@ Token wyszukiwania akceptuje ID zadania, ID uruchomienia lub klucz sesji. Pokazu
|
||||
openclaw tasks cancel <lookup>
|
||||
```
|
||||
|
||||
W przypadku zadań ACP i subagentów powoduje to zabicie sesji podrzędnej. Status przechodzi do `cancelled`, a powiadomienie o dostarczeniu zostaje wysłane.
|
||||
W przypadku zadań ACP i podagentów powoduje to zabicie sesji podrzędnej. W przypadku zadań śledzonych przez CLI anulowanie jest rejestrowane w rejestrze zadań (nie ma osobnego uchwytu środowiska uruchomieniowego podrzędnego). Status przechodzi na `cancelled`, a w razie potrzeby wysyłane jest powiadomienie o dostarczeniu.
|
||||
|
||||
### `tasks notify`
|
||||
|
||||
@ -201,16 +195,16 @@ openclaw tasks notify <lookup> <done_only|state_changes|silent>
|
||||
openclaw tasks audit [--json]
|
||||
```
|
||||
|
||||
Ujawnia problemy operacyjne. Wyniki pojawiają się też w `openclaw status`, gdy zostaną wykryte problemy.
|
||||
Pokazuje problemy operacyjne. Ustalenia pojawiają się również w `openclaw status`, gdy wykryte zostaną problemy.
|
||||
|
||||
| Ustalenie | Ważność | Wyzwalacz |
|
||||
| ------------------------ | ------- | ----------------------------------------------------- |
|
||||
| `stale_queued` | warn | Oczekuje dłużej niż 10 minut |
|
||||
| `stale_running` | error | Działa dłużej niż 30 minut |
|
||||
| `lost` | error | Zniknęło środowisko uruchomieniowe będące właścicielem zadania |
|
||||
| `delivery_failed` | warn | Dostarczenie nie powiodło się, a polityka powiadomień nie jest `silent` |
|
||||
| `missing_cleanup` | warn | Zadanie terminalne bez znacznika czasu czyszczenia |
|
||||
| `inconsistent_timestamps`| warn | Naruszenie osi czasu (na przykład zakończono przed rozpoczęciem) |
|
||||
| Ustalenie | Ważność | Wyzwalacz |
|
||||
| ------------------------- | ------- | ---------------------------------------------------- |
|
||||
| `stale_queued` | warn | Kolejka trwa dłużej niż 10 minut |
|
||||
| `stale_running` | error | Uruchomione dłużej niż 30 minut |
|
||||
| `lost` | error | Zniknęła własność zadania oparta na środowisku uruchomieniowym |
|
||||
| `delivery_failed` | warn | Dostarczenie nie powiodło się, a polityka powiadomień nie jest `silent` |
|
||||
| `missing_cleanup` | warn | Zadanie terminalne bez znacznika czasu czyszczenia |
|
||||
| `inconsistent_timestamps` | warn | Naruszenie osi czasu (na przykład zakończone przed rozpoczęciem) |
|
||||
|
||||
### `tasks maintenance`
|
||||
|
||||
@ -219,22 +213,20 @@ openclaw tasks maintenance [--json]
|
||||
openclaw tasks maintenance --apply [--json]
|
||||
```
|
||||
|
||||
Użyj tego, aby wyświetlić podgląd lub zastosować uzgadnianie, oznaczanie czyszczenia i przycinanie
|
||||
dla zadań oraz stanu Task Flow.
|
||||
Użyj tego, aby wyświetlić podgląd lub zastosować uzgadnianie, oznaczanie czyszczenia i usuwanie przestarzałych danych dla zadań oraz stanu Task Flow.
|
||||
|
||||
Uzgadnianie jest zależne od środowiska uruchomieniowego:
|
||||
|
||||
- Zadania ACP/subagentów sprawdzają swoją podrzędną sesję zaplecza.
|
||||
- Zadania ACP/podagentów sprawdzają swoją podrzędną sesję zaplecza.
|
||||
- Zadania cron sprawdzają, czy środowisko uruchomieniowe cron nadal jest właścicielem zadania.
|
||||
- Zadania CLI oparte na czacie sprawdzają nadrzędny aktywny kontekst uruchomienia, a nie tylko wiersz sesji czatu.
|
||||
- Zadania CLI powiązane z czatem sprawdzają właścicielski aktywny kontekst uruchomienia, a nie tylko wiersz sesji czatu.
|
||||
|
||||
Czyszczenie po zakończeniu jest również zależne od środowiska uruchomieniowego:
|
||||
|
||||
- Zakończenie subagenta w trybie best-effort zamyka śledzone karty/procesy przeglądarki dla sesji podrzędnej, zanim będzie kontynuowane czyszczenie po ogłoszeniu.
|
||||
- Zakończenie izolowanego uruchomienia cron w trybie best-effort zamyka śledzone karty/procesy przeglądarki dla sesji cron, zanim uruchomienie zostanie całkowicie zakończone.
|
||||
- Dostarczanie zakończenia izolowanego uruchomienia cron w razie potrzeby czeka na dalsze działania potomnych subagentów
|
||||
i pomija nieaktualny tekst potwierdzenia nadrzędnego zamiast go ogłaszać.
|
||||
- Dostarczanie zakończenia subagenta preferuje najnowszy widoczny tekst asystenta; jeśli jest pusty, wraca do oczyszczonego najnowszego tekstu tool/toolResult, a uruchomienia wywołań narzędzi zakończone tylko przekroczeniem czasu mogą zostać zredukowane do krótkiego podsumowania częściowego postępu.
|
||||
- Zakończenie podagenta w miarę możliwości zamyka śledzone karty/procesy przeglądarki dla sesji podrzędnej, zanim kontynuowane będzie czyszczenie ogłoszenia.
|
||||
- Zakończenie izolowanego cron w miarę możliwości zamyka śledzone karty/procesy przeglądarki dla sesji cron, zanim uruchomienie zostanie całkowicie zakończone.
|
||||
- Dostarczenie dla izolowanego cron czeka na zakończenie następczej pracy podrzędnych podagentów, gdy jest to potrzebne, i pomija nieaktualny tekst potwierdzenia nadrzędnego zamiast go ogłaszać.
|
||||
- Dostarczenie zakończenia podagenta preferuje najnowszy widoczny tekst asystenta; jeśli jest pusty, używa oczyszczonego najnowszego tekstu tool/toolResult, a uruchomienia wyłącznie z wywołaniem narzędzia zakończone timeoutem mogą zostać zredukowane do krótkiego podsumowania częściowego postępu.
|
||||
- Błędy czyszczenia nie maskują rzeczywistego wyniku zadania.
|
||||
|
||||
### `tasks flow list|show|cancel`
|
||||
@ -245,22 +237,21 @@ openclaw tasks flow show <lookup> [--json]
|
||||
openclaw tasks flow cancel <lookup>
|
||||
```
|
||||
|
||||
Użyj tych poleceń, gdy interesuje Cię orkiestrujący Task Flow,
|
||||
a nie pojedynczy rekord zadania w tle.
|
||||
Używaj ich wtedy, gdy interesuje Cię orkiestrujący Task Flow, a nie pojedynczy rekord zadania w tle.
|
||||
|
||||
## Tablica zadań na czacie (`/tasks`)
|
||||
## Tablica zadań czatu (`/tasks`)
|
||||
|
||||
Użyj `/tasks` w dowolnej sesji czatu, aby zobaczyć zadania w tle powiązane z tą sesją. Tablica pokazuje
|
||||
aktywne i niedawno zakończone zadania wraz ze środowiskiem uruchomieniowym, statusem, czasem oraz szczegółami postępu lub błędu.
|
||||
|
||||
Gdy bieżąca sesja nie ma widocznych powiązanych zadań, `/tasks` wraca do lokalnych dla agenta liczników zadań,
|
||||
dzięki czemu nadal otrzymujesz przegląd bez ujawniania szczegółów innych sesji.
|
||||
Gdy bieżąca sesja nie ma widocznych powiązanych zadań, `/tasks` przełącza się na lokalne dla agenta liczniki zadań,
|
||||
dzięki czemu nadal masz ogólny obraz bez ujawniania szczegółów innych sesji.
|
||||
|
||||
Aby zobaczyć pełny rejestr operatora, użyj CLI: `openclaw tasks list`.
|
||||
|
||||
## Integracja statusu (obciążenie zadaniami)
|
||||
## Integracja ze statusem (obciążenie zadaniami)
|
||||
|
||||
`openclaw status` zawiera szybkie podsumowanie zadań:
|
||||
`openclaw status` zawiera skrócone podsumowanie zadań:
|
||||
|
||||
```
|
||||
Tasks: 3 queued · 2 running · 1 issues
|
||||
@ -272,64 +263,62 @@ Podsumowanie raportuje:
|
||||
- **failures** — liczba `failed` + `timed_out` + `lost`
|
||||
- **byRuntime** — podział według `acp`, `subagent`, `cron`, `cli`
|
||||
|
||||
Zarówno `/status`, jak i narzędzie `session_status` używają migawki zadań uwzględniającej czyszczenie: preferowane są aktywne zadania,
|
||||
nieaktualne zakończone wiersze są ukrywane, a niedawne niepowodzenia pojawiają się tylko wtedy, gdy nie pozostała żadna aktywna praca.
|
||||
Dzięki temu karta statusu skupia się na tym, co ma znaczenie w tej chwili.
|
||||
Zarówno `/status`, jak i narzędzie `session_status` używają migawki zadań uwzględniającej czyszczenie: preferowane są aktywne zadania, nieaktualne zakończone wiersze są ukrywane, a ostatnie błędy są pokazywane tylko wtedy, gdy nie pozostała żadna aktywna praca. Dzięki temu karta statusu skupia się na tym, co jest teraz najważniejsze.
|
||||
|
||||
## Przechowywanie i konserwacja
|
||||
|
||||
### Gdzie są przechowywane zadania
|
||||
### Gdzie przechowywane są zadania
|
||||
|
||||
Rekordy zadań są przechowywane w SQLite pod adresem:
|
||||
Rekordy zadań są trwale zapisywane w SQLite pod adresem:
|
||||
|
||||
```
|
||||
$OPENCLAW_STATE_DIR/tasks/runs.sqlite
|
||||
```
|
||||
|
||||
Rejestr jest ładowany do pamięci podczas uruchamiania gateway i synchronizuje zapisy do SQLite, aby zapewnić trwałość po restarcie.
|
||||
Rejestr jest ładowany do pamięci przy uruchomieniu gateway i synchronizuje zapisy do SQLite, aby zapewnić trwałość po ponownym uruchomieniu.
|
||||
|
||||
### Automatyczna konserwacja
|
||||
|
||||
Co **60 sekund** działa proces czyszczący, który obsługuje trzy rzeczy:
|
||||
Proces czyszczący uruchamia się co **60 sekund** i obsługuje trzy rzeczy:
|
||||
|
||||
1. **Uzgadnianie** — sprawdza, czy aktywne zadania nadal mają autorytatywne zaplecze środowiska uruchomieniowego. Zadania ACP/subagentów używają stanu sesji podrzędnej, zadania cron używają własności aktywnego zadania, a zadania CLI oparte na czacie używają nadrzędnego kontekstu uruchomienia. Jeśli ten stan zaplecza zniknie na dłużej niż 5 minut, zadanie zostaje oznaczone jako `lost`.
|
||||
1. **Uzgadnianie** — sprawdza, czy aktywne zadania nadal mają autorytatywne zaplecze w środowisku uruchomieniowym. Zadania ACP/podagentów używają stanu sesji podrzędnej, zadania cron używają własności aktywnego zadania, a zadania CLI powiązane z czatem używają właścicielskiego kontekstu uruchomienia. Jeśli ten stan zaplecza nie istnieje dłużej niż 5 minut, zadanie zostaje oznaczone jako `lost`.
|
||||
2. **Oznaczanie czyszczenia** — ustawia znacznik czasu `cleanupAfter` dla zadań terminalnych (`endedAt + 7 days`).
|
||||
3. **Przycinanie** — usuwa rekordy po dacie `cleanupAfter`.
|
||||
3. **Usuwanie** — usuwa rekordy po dacie `cleanupAfter`.
|
||||
|
||||
**Retencja**: rekordy zadań terminalnych są przechowywane przez **7 dni**, a następnie automatycznie usuwane. Nie jest wymagana żadna konfiguracja.
|
||||
**Retencja**: terminalne rekordy zadań są przechowywane przez **7 dni**, a następnie automatycznie usuwane. Nie jest wymagana żadna konfiguracja.
|
||||
|
||||
## Jak zadania są powiązane z innymi systemami
|
||||
## Jak zadania odnoszą się do innych systemów
|
||||
|
||||
### Zadania i Task Flow
|
||||
|
||||
[Task Flow](/pl/automation/taskflow) to warstwa orkiestracji przepływów nad zadaniami w tle. Pojedynczy przepływ może przez cały czas swojego życia koordynować wiele zadań, używając trybów synchronizacji zarządzanej lub lustrzanej. Użyj `openclaw tasks`, aby sprawdzić pojedyncze rekordy zadań, a `openclaw tasks flow`, aby sprawdzić orkiestrujący przepływ.
|
||||
[Task Flow](/pl/automation/taskflow) to warstwa orkiestracji przepływu ponad zadaniami w tle. Pojedynczy przepływ może w ciągu swojego cyklu życia koordynować wiele zadań, używając zarządzanych lub lustrzanych trybów synchronizacji. Użyj `openclaw tasks`, aby sprawdzić pojedyncze rekordy zadań, oraz `openclaw tasks flow`, aby sprawdzić orkiestrujący przepływ.
|
||||
|
||||
Szczegóły znajdziesz w [Task Flow](/pl/automation/taskflow).
|
||||
|
||||
### Zadania i cron
|
||||
|
||||
**Definicja** zadania cron znajduje się w `~/.openclaw/cron/jobs.json`. **Każde** wykonanie cron tworzy rekord zadania — zarówno w sesji głównej, jak i izolowanej. Zadania cron w sesji głównej domyślnie używają polityki powiadomień `silent`, aby śledzić bez generowania powiadomień.
|
||||
**Definicja** zadania cron znajduje się w `~/.openclaw/cron/jobs.json`. **Każde** wykonanie cron tworzy rekord zadania — zarówno w sesji głównej, jak i izolowanej. Zadania cron w sesji głównej domyślnie używają polityki powiadomień `silent`, dzięki czemu są śledzone bez generowania powiadomień.
|
||||
|
||||
Zobacz [Cron Jobs](/pl/automation/cron-jobs).
|
||||
Zobacz [Zadania cron](/pl/automation/cron-jobs).
|
||||
|
||||
### Zadania i heartbeat
|
||||
|
||||
Uruchomienia heartbeat to tury sesji głównej — nie tworzą rekordów zadań. Gdy zadanie się kończy, może wywołać wybudzenie heartbeat, aby wynik był szybko widoczny.
|
||||
Uruchomienia heartbeat są turami sesji głównej — nie tworzą rekordów zadań. Gdy zadanie się zakończy, może wywołać wybudzenie heartbeat, aby wynik był widoczny od razu.
|
||||
|
||||
Zobacz [Heartbeat](/pl/gateway/heartbeat).
|
||||
|
||||
### Zadania i sesje
|
||||
|
||||
Zadanie może odnosić się do `childSessionKey` (gdzie wykonywana jest praca) oraz `requesterSessionKey` (kto ją uruchomił). Sesje to kontekst rozmowy; zadania to warstwa śledzenia aktywności nad tym kontekstem.
|
||||
Zadanie może odwoływać się do `childSessionKey` (gdzie wykonywana jest praca) oraz `requesterSessionKey` (kto ją uruchomił). Sesje to kontekst rozmowy; zadania to warstwa śledzenia aktywności nad tym kontekstem.
|
||||
|
||||
### Zadania i uruchomienia agenta
|
||||
### Zadania i uruchomienia agentów
|
||||
|
||||
Pole `runId` zadania wskazuje uruchomienie agenta wykonujące pracę. Zdarzenia cyklu życia agenta (start, koniec, błąd) automatycznie aktualizują status zadania — nie musisz zarządzać cyklem życia ręcznie.
|
||||
`runId` zadania łączy je z uruchomieniem agenta wykonującym pracę. Zdarzenia cyklu życia agenta (start, koniec, błąd) automatycznie aktualizują status zadania — nie trzeba zarządzać cyklem życia ręcznie.
|
||||
|
||||
## Powiązane
|
||||
|
||||
- [Automation & Tasks](/pl/automation) — wszystkie mechanizmy automatyzacji w skrócie
|
||||
- [Task Flow](/pl/automation/taskflow) — orkiestracja przepływów nad zadaniami
|
||||
- [Scheduled Tasks](/pl/automation/cron-jobs) — planowanie pracy w tle
|
||||
- [Automatyzacja i zadania](/pl/automation) — wszystkie mechanizmy automatyzacji w skrócie
|
||||
- [Task Flow](/pl/automation/taskflow) — orkiestracja przepływu ponad zadaniami
|
||||
- [Zaplanowane zadania](/pl/automation/cron-jobs) — harmonogramowanie pracy w tle
|
||||
- [Heartbeat](/pl/gateway/heartbeat) — okresowe tury sesji głównej
|
||||
- [CLI: Tasks](/cli/index#tasks) — dokumentacja poleceń CLI
|
||||
- [CLI: Zadania](/cli/index#tasks) — dokumentacja poleceń CLI
|
||||
|
||||
614
docs/pl/concepts/active-memory.md
Normal file
614
docs/pl/concepts/active-memory.md
Normal file
@ -0,0 +1,614 @@
|
||||
---
|
||||
read_when:
|
||||
- Chcesz zrozumieć, do czego służy aktywna pamięć
|
||||
- Chcesz włączyć aktywną pamięć dla agenta konwersacyjnego
|
||||
- Chcesz dostroić działanie aktywnej pamięci bez włączania jej wszędzie
|
||||
summary: Podagent pamięci blokującej należący do pluginu, który wstrzykuje odpowiednią pamięć do interaktywnych sesji czatu
|
||||
title: Aktywna pamięć
|
||||
x-i18n:
|
||||
generated_at: "2026-04-10T09:44:39Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 6a51437df4ae4d9d57764601dfcfcdadb269e2895bf49dc82b9f496c1b3cb341
|
||||
source_path: concepts/active-memory.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Aktywna pamięć
|
||||
|
||||
Aktywna pamięć to opcjonalny, należący do pluginu blokujący podagent pamięci, który uruchamia się
|
||||
przed główną odpowiedzią dla kwalifikujących się sesji konwersacyjnych.
|
||||
|
||||
Istnieje, ponieważ większość systemów pamięci jest skuteczna, ale reaktywna. Polegają one na
|
||||
tym, że główny agent zdecyduje, kiedy przeszukać pamięć, albo na tym, że użytkownik powie coś
|
||||
w rodzaju „zapamiętaj to” lub „przeszukaj pamięć”. W tym momencie chwila, w której pamięć
|
||||
sprawiłaby, że odpowiedź byłaby naturalna, już minęła.
|
||||
|
||||
Aktywna pamięć daje systemowi jedną ograniczoną szansę na wydobycie istotnej pamięci
|
||||
przed wygenerowaniem głównej odpowiedzi.
|
||||
|
||||
## Wklej to do swojego agenta
|
||||
|
||||
Wklej to do swojego agenta, jeśli chcesz włączyć Aktywną pamięć z
|
||||
samowystarczalną konfiguracją z bezpiecznymi ustawieniami domyślnymi:
|
||||
|
||||
```json5
|
||||
{
|
||||
plugins: {
|
||||
entries: {
|
||||
"active-memory": {
|
||||
enabled: true,
|
||||
config: {
|
||||
enabled: true,
|
||||
agents: ["main"],
|
||||
allowedChatTypes: ["direct"],
|
||||
modelFallbackPolicy: "default-remote",
|
||||
queryMode: "recent",
|
||||
promptStyle: "balanced",
|
||||
timeoutMs: 15000,
|
||||
maxSummaryChars: 220,
|
||||
persistTranscripts: false,
|
||||
logging: true,
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
To włącza plugin dla agenta `main`, domyślnie ogranicza go do sesji
|
||||
w stylu wiadomości bezpośrednich, pozwala mu najpierw dziedziczyć bieżący model sesji, a
|
||||
także nadal dopuszcza wbudowany zdalny mechanizm awaryjny, jeśli nie jest dostępny
|
||||
żaden jawny ani odziedziczony model.
|
||||
|
||||
Następnie uruchom ponownie gateway:
|
||||
|
||||
```bash
|
||||
node scripts/run-node.mjs gateway --profile dev
|
||||
```
|
||||
|
||||
Aby obserwować to na żywo w rozmowie:
|
||||
|
||||
```text
|
||||
/verbose on
|
||||
```
|
||||
|
||||
## Włącz aktywną pamięć
|
||||
|
||||
Najbezpieczniejsza konfiguracja to:
|
||||
|
||||
1. włączenie pluginu
|
||||
2. wskazanie jednego agenta konwersacyjnego
|
||||
3. pozostawienie logowania włączonego tylko podczas dostrajania
|
||||
|
||||
Zacznij od tego w `openclaw.json`:
|
||||
|
||||
```json5
|
||||
{
|
||||
plugins: {
|
||||
entries: {
|
||||
"active-memory": {
|
||||
enabled: true,
|
||||
config: {
|
||||
agents: ["main"],
|
||||
allowedChatTypes: ["direct"],
|
||||
modelFallbackPolicy: "default-remote",
|
||||
queryMode: "recent",
|
||||
promptStyle: "balanced",
|
||||
timeoutMs: 15000,
|
||||
maxSummaryChars: 220,
|
||||
persistTranscripts: false,
|
||||
logging: true,
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
Następnie uruchom ponownie gateway:
|
||||
|
||||
```bash
|
||||
node scripts/run-node.mjs gateway --profile dev
|
||||
```
|
||||
|
||||
Co to oznacza:
|
||||
|
||||
- `plugins.entries.active-memory.enabled: true` włącza plugin
|
||||
- `config.agents: ["main"]` włącza aktywną pamięć tylko dla agenta `main`
|
||||
- `config.allowedChatTypes: ["direct"]` domyślnie utrzymuje aktywną pamięć tylko dla sesji w stylu wiadomości bezpośrednich
|
||||
- jeśli `config.model` nie jest ustawione, aktywna pamięć najpierw dziedziczy bieżący model sesji
|
||||
- `config.modelFallbackPolicy: "default-remote"` pozostawia wbudowany zdalny mechanizm awaryjny jako domyślny, gdy nie jest dostępny żaden jawny ani odziedziczony model
|
||||
- `config.promptStyle: "balanced"` używa domyślnego, ogólnego stylu promptu dla trybu `recent`
|
||||
- aktywna pamięć nadal działa tylko w kwalifikujących się interaktywnych trwałych sesjach czatu
|
||||
|
||||
## Jak to zobaczyć
|
||||
|
||||
Aktywna pamięć wstrzykuje ukryty kontekst systemowy dla modelu. Nie ujawnia
|
||||
surowych tagów `<active_memory_plugin>...</active_memory_plugin>` klientowi.
|
||||
|
||||
## Przełącznik sesji
|
||||
|
||||
Użyj polecenia pluginu, jeśli chcesz wstrzymać lub wznowić aktywną pamięć dla
|
||||
bieżącej sesji czatu bez edytowania konfiguracji:
|
||||
|
||||
```text
|
||||
/active-memory status
|
||||
/active-memory off
|
||||
/active-memory on
|
||||
```
|
||||
|
||||
To ustawienie dotyczy zakresu sesji. Nie zmienia
|
||||
`plugins.entries.active-memory.enabled`, wyboru agenta ani innej globalnej
|
||||
konfiguracji.
|
||||
|
||||
Jeśli chcesz, aby polecenie zapisało konfigurację oraz wstrzymało lub wznowiło aktywną pamięć
|
||||
dla wszystkich sesji, użyj jawnej formy globalnej:
|
||||
|
||||
```text
|
||||
/active-memory status --global
|
||||
/active-memory off --global
|
||||
/active-memory on --global
|
||||
```
|
||||
|
||||
Forma globalna zapisuje `plugins.entries.active-memory.config.enabled`. Pozostawia
|
||||
`plugins.entries.active-memory.enabled` włączone, aby polecenie nadal było dostępne i można było
|
||||
ponownie włączyć aktywną pamięć później.
|
||||
|
||||
Jeśli chcesz zobaczyć, co aktywna pamięć robi w sesji na żywo, włącz tryb
|
||||
szczegółowy dla tej sesji:
|
||||
|
||||
```text
|
||||
/verbose on
|
||||
```
|
||||
|
||||
Gdy tryb szczegółowy jest włączony, OpenClaw może pokazać:
|
||||
|
||||
- wiersz stanu aktywnej pamięci, taki jak `Active Memory: ok 842ms recent 34 chars`
|
||||
- czytelne podsumowanie debugowania, takie jak `Active Memory Debug: Lemon pepper wings with blue cheese.`
|
||||
|
||||
Te wiersze pochodzą z tego samego przebiegu aktywnej pamięci, który zasila ukryty
|
||||
kontekst systemowy, ale są sformatowane dla ludzi zamiast ujawniać surowe
|
||||
znaczniki promptu.
|
||||
|
||||
Domyślnie transkrypt blokującego podagenta pamięci jest tymczasowy i usuwany
|
||||
po zakończeniu działania.
|
||||
|
||||
Przykładowy przebieg:
|
||||
|
||||
```text
|
||||
/verbose on
|
||||
what wings should i order?
|
||||
```
|
||||
|
||||
Oczekiwany widoczny kształt odpowiedzi:
|
||||
|
||||
```text
|
||||
...normal assistant reply...
|
||||
|
||||
🧩 Active Memory: ok 842ms recent 34 chars
|
||||
🔎 Active Memory Debug: Lemon pepper wings with blue cheese.
|
||||
```
|
||||
|
||||
## Kiedy się uruchamia
|
||||
|
||||
Aktywna pamięć używa dwóch bramek:
|
||||
|
||||
1. **Włączenie w konfiguracji**
|
||||
Plugin musi być włączony, a identyfikator bieżącego agenta musi występować w
|
||||
`plugins.entries.active-memory.config.agents`.
|
||||
2. **Ścisła kwalifikacja w czasie działania**
|
||||
Nawet gdy jest włączona i skierowana do danego agenta, aktywna pamięć działa tylko dla
|
||||
kwalifikujących się interaktywnych trwałych sesji czatu.
|
||||
|
||||
Rzeczywista reguła jest następująca:
|
||||
|
||||
```text
|
||||
plugin enabled
|
||||
+
|
||||
agent id targeted
|
||||
+
|
||||
allowed chat type
|
||||
+
|
||||
eligible interactive persistent chat session
|
||||
=
|
||||
active memory runs
|
||||
```
|
||||
|
||||
Jeśli którykolwiek z tych warunków nie jest spełniony, aktywna pamięć się nie uruchamia.
|
||||
|
||||
## Typy sesji
|
||||
|
||||
`config.allowedChatTypes` kontroluje, w jakich rodzajach rozmów Aktywna
|
||||
Pamięć może się w ogóle uruchamiać.
|
||||
|
||||
Wartość domyślna to:
|
||||
|
||||
```json5
|
||||
allowedChatTypes: ["direct"]
|
||||
```
|
||||
|
||||
Oznacza to, że Aktywna pamięć domyślnie działa w sesjach w stylu wiadomości bezpośrednich, ale
|
||||
nie w sesjach grupowych ani kanałowych, chyba że jawnie je włączysz.
|
||||
|
||||
Przykłady:
|
||||
|
||||
```json5
|
||||
allowedChatTypes: ["direct"]
|
||||
```
|
||||
|
||||
```json5
|
||||
allowedChatTypes: ["direct", "group"]
|
||||
```
|
||||
|
||||
```json5
|
||||
allowedChatTypes: ["direct", "group", "channel"]
|
||||
```
|
||||
|
||||
## Gdzie działa
|
||||
|
||||
Aktywna pamięć to funkcja wzbogacająca rozmowę, a nie ogólnoplatformowa
|
||||
funkcja inferencji.
|
||||
|
||||
| Surface | Runs active memory? |
|
||||
| ------------------------------------------------------------------- | ------------------------------------------------------- |
|
||||
| Control UI / web chat persistent sessions | Yes, if the plugin is enabled and the agent is targeted |
|
||||
| Other interactive channel sessions on the same persistent chat path | Yes, if the plugin is enabled and the agent is targeted |
|
||||
| Headless one-shot runs | No |
|
||||
| Heartbeat/background runs | No |
|
||||
| Generic internal `agent-command` paths | No |
|
||||
| Sub-agent/internal helper execution | No |
|
||||
|
||||
## Dlaczego warto tego używać
|
||||
|
||||
Używaj aktywnej pamięci, gdy:
|
||||
|
||||
- sesja jest trwała i skierowana do użytkownika
|
||||
- agent ma istotną pamięć długoterminową do przeszukania
|
||||
- ciągłość i personalizacja są ważniejsze niż pełna deterministyczność promptu
|
||||
|
||||
Sprawdza się szczególnie dobrze w przypadku:
|
||||
|
||||
- stałych preferencji
|
||||
- powtarzających się nawyków
|
||||
- długoterminowego kontekstu użytkownika, który powinien naturalnie się pojawiać
|
||||
|
||||
Nie jest dobrym wyborem dla:
|
||||
|
||||
- automatyzacji
|
||||
- wewnętrznych workerów
|
||||
- jednorazowych zadań API
|
||||
- miejsc, w których ukryta personalizacja byłaby zaskakująca
|
||||
|
||||
## Jak to działa
|
||||
|
||||
Kształt działania w czasie wykonywania jest następujący:
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
U["User Message"] --> Q["Build Memory Query"]
|
||||
Q --> R["Active Memory Blocking Memory Sub-Agent"]
|
||||
R -->|NONE or empty| M["Main Reply"]
|
||||
R -->|relevant summary| I["Append Hidden active_memory_plugin System Context"]
|
||||
I --> M["Main Reply"]
|
||||
```
|
||||
|
||||
Blokujący podagent pamięci może używać tylko:
|
||||
|
||||
- `memory_search`
|
||||
- `memory_get`
|
||||
|
||||
Jeśli połączenie jest słabe, powinien zwrócić `NONE`.
|
||||
|
||||
## Tryby zapytań
|
||||
|
||||
`config.queryMode` kontroluje, jak dużą część rozmowy widzi blokujący podagent pamięci.
|
||||
|
||||
## Style promptu
|
||||
|
||||
`config.promptStyle` kontroluje, jak chętnie lub rygorystycznie blokujący podagent pamięci
|
||||
decyduje o tym, czy zwrócić pamięć.
|
||||
|
||||
Dostępne style:
|
||||
|
||||
- `balanced`: domyślne ustawienie ogólnego przeznaczenia dla trybu `recent`
|
||||
- `strict`: najmniej skłonny; najlepszy, gdy chcesz bardzo małego przenikania z pobliskiego kontekstu
|
||||
- `contextual`: najbardziej przyjazny dla ciągłości; najlepszy, gdy historia rozmowy powinna mieć większe znaczenie
|
||||
- `recall-heavy`: bardziej skłonny do wydobywania pamięci przy słabszych, ale nadal wiarygodnych dopasowaniach
|
||||
- `precision-heavy`: zdecydowanie preferuje `NONE`, chyba że dopasowanie jest oczywiste
|
||||
- `preference-only`: zoptymalizowany pod ulubione rzeczy, nawyki, rutyny, gust i powtarzające się fakty osobiste
|
||||
|
||||
Domyślne mapowanie, gdy `config.promptStyle` nie jest ustawione:
|
||||
|
||||
```text
|
||||
message -> strict
|
||||
recent -> balanced
|
||||
full -> contextual
|
||||
```
|
||||
|
||||
Jeśli jawnie ustawisz `config.promptStyle`, to nadpisanie ma pierwszeństwo.
|
||||
|
||||
Przykład:
|
||||
|
||||
```json5
|
||||
promptStyle: "preference-only"
|
||||
```
|
||||
|
||||
## Zasady mechanizmu awaryjnego modelu
|
||||
|
||||
Jeśli `config.model` nie jest ustawione, Aktywna pamięć próbuje rozwiązać model w tej kolejności:
|
||||
|
||||
```text
|
||||
explicit plugin model
|
||||
-> current session model
|
||||
-> agent primary model
|
||||
-> optional built-in remote fallback
|
||||
```
|
||||
|
||||
`config.modelFallbackPolicy` kontroluje ostatni krok.
|
||||
|
||||
Wartość domyślna:
|
||||
|
||||
```json5
|
||||
modelFallbackPolicy: "default-remote"
|
||||
```
|
||||
|
||||
Inna opcja:
|
||||
|
||||
```json5
|
||||
modelFallbackPolicy: "resolved-only"
|
||||
```
|
||||
|
||||
Użyj `resolved-only`, jeśli chcesz, aby Aktywna pamięć pomijała przywoływanie zamiast
|
||||
korzystać z wbudowanego zdalnego domyślnego mechanizmu awaryjnego, gdy nie jest dostępny
|
||||
żaden jawny ani odziedziczony model.
|
||||
|
||||
## Zaawansowane mechanizmy awaryjne
|
||||
|
||||
Te opcje celowo nie są częścią zalecanej konfiguracji.
|
||||
|
||||
`config.thinking` może nadpisać poziom myślenia blokującego podagenta pamięci:
|
||||
|
||||
```json5
|
||||
thinking: "medium"
|
||||
```
|
||||
|
||||
Wartość domyślna:
|
||||
|
||||
```json5
|
||||
thinking: "off"
|
||||
```
|
||||
|
||||
Nie włączaj tego domyślnie. Aktywna pamięć działa na ścieżce odpowiedzi, więc dodatkowy
|
||||
czas myślenia bezpośrednio zwiększa opóźnienie widoczne dla użytkownika.
|
||||
|
||||
`config.promptAppend` dodaje dodatkowe instrukcje operatora po domyślnym
|
||||
prompcie Aktywnej pamięci i przed kontekstem rozmowy:
|
||||
|
||||
```json5
|
||||
promptAppend: "Prefer stable long-term preferences over one-off events."
|
||||
```
|
||||
|
||||
`config.promptOverride` zastępuje domyślny prompt Aktywnej pamięci. OpenClaw
|
||||
nadal dołącza później kontekst rozmowy:
|
||||
|
||||
```json5
|
||||
promptOverride: "You are a memory search agent. Return NONE or one compact user fact."
|
||||
```
|
||||
|
||||
Dostosowywanie promptu nie jest zalecane, chyba że celowo testujesz inny
|
||||
kontrakt przywoływania. Domyślny prompt jest dostrojony tak, aby zwracać `NONE`
|
||||
albo zwięzły kontekst faktów o użytkowniku dla głównego modelu.
|
||||
|
||||
### `message`
|
||||
|
||||
Wysyłana jest tylko najnowsza wiadomość użytkownika.
|
||||
|
||||
```text
|
||||
Latest user message only
|
||||
```
|
||||
|
||||
Użyj tego, gdy:
|
||||
|
||||
- chcesz najszybszego działania
|
||||
- chcesz najsilniejszego nastawienia na przywoływanie stabilnych preferencji
|
||||
- kolejne tury nie wymagają kontekstu rozmowy
|
||||
|
||||
Zalecany limit czasu:
|
||||
|
||||
- zacznij od około `3000` do `5000` ms
|
||||
|
||||
### `recent`
|
||||
|
||||
Wysyłana jest najnowsza wiadomość użytkownika wraz z niewielkim ogonem ostatniej rozmowy.
|
||||
|
||||
```text
|
||||
Recent conversation tail:
|
||||
user: ...
|
||||
assistant: ...
|
||||
user: ...
|
||||
|
||||
Latest user message:
|
||||
...
|
||||
```
|
||||
|
||||
Użyj tego, gdy:
|
||||
|
||||
- chcesz lepszej równowagi między szybkością a osadzeniem w rozmowie
|
||||
- pytania uzupełniające często zależą od kilku ostatnich tur
|
||||
|
||||
Zalecany limit czasu:
|
||||
|
||||
- zacznij od około `15000` ms
|
||||
|
||||
### `full`
|
||||
|
||||
Do blokującego podagenta pamięci wysyłana jest cała rozmowa.
|
||||
|
||||
```text
|
||||
Full conversation context:
|
||||
user: ...
|
||||
assistant: ...
|
||||
user: ...
|
||||
...
|
||||
```
|
||||
|
||||
Użyj tego, gdy:
|
||||
|
||||
- najwyższa jakość przywoływania jest ważniejsza niż opóźnienie
|
||||
- rozmowa zawiera istotne przygotowanie daleko wcześniej w wątku
|
||||
|
||||
Zalecany limit czasu:
|
||||
|
||||
- zwiększ go znacząco w porównaniu z `message` lub `recent`
|
||||
- zacznij od około `15000` ms lub więcej, w zależności od rozmiaru wątku
|
||||
|
||||
Ogólnie limit czasu powinien rosnąć wraz z rozmiarem kontekstu:
|
||||
|
||||
```text
|
||||
message < recent < full
|
||||
```
|
||||
|
||||
## Trwałość transkryptów
|
||||
|
||||
Uruchomienia blokującego podagenta pamięci aktywnej pamięci tworzą rzeczywisty
|
||||
transkrypt `session.jsonl` podczas wywołania blokującego podagenta pamięci.
|
||||
|
||||
Domyślnie ten transkrypt jest tymczasowy:
|
||||
|
||||
- jest zapisywany w katalogu tymczasowym
|
||||
- jest używany tylko na potrzeby uruchomienia blokującego podagenta pamięci
|
||||
- jest usuwany natychmiast po zakończeniu działania
|
||||
|
||||
Jeśli chcesz zachować te transkrypty blokującego podagenta pamięci na dysku do debugowania lub
|
||||
inspekcji, jawnie włącz ich trwałość:
|
||||
|
||||
```json5
|
||||
{
|
||||
plugins: {
|
||||
entries: {
|
||||
"active-memory": {
|
||||
enabled: true,
|
||||
config: {
|
||||
agents: ["main"],
|
||||
persistTranscripts: true,
|
||||
transcriptDir: "active-memory",
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
Po włączeniu aktywna pamięć zapisuje transkrypty w osobnym katalogu w folderze
|
||||
sesji docelowego agenta, a nie w głównej ścieżce transkryptu rozmowy użytkownika.
|
||||
|
||||
Domyślny układ wygląda koncepcyjnie tak:
|
||||
|
||||
```text
|
||||
agents/<agent>/sessions/active-memory/<blocking-memory-sub-agent-session-id>.jsonl
|
||||
```
|
||||
|
||||
Możesz zmienić względny podkatalog za pomocą `config.transcriptDir`.
|
||||
|
||||
Używaj tego ostrożnie:
|
||||
|
||||
- transkrypty blokującego podagenta pamięci mogą szybko się gromadzić w aktywnych sesjach
|
||||
- tryb zapytań `full` może duplikować dużą część kontekstu rozmowy
|
||||
- te transkrypty zawierają ukryty kontekst promptu i przywołane wspomnienia
|
||||
|
||||
## Konfiguracja
|
||||
|
||||
Cała konfiguracja aktywnej pamięci znajduje się pod:
|
||||
|
||||
```text
|
||||
plugins.entries.active-memory
|
||||
```
|
||||
|
||||
Najważniejsze pola to:
|
||||
|
||||
| Klucz | Typ | Znaczenie |
|
||||
| --------------------------- | ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
|
||||
| `enabled` | `boolean` | Włącza sam plugin |
|
||||
| `config.agents` | `string[]` | Identyfikatory agentów, które mogą używać aktywnej pamięci |
|
||||
| `config.model` | `string` | Opcjonalne odwołanie do modelu blokującego podagenta pamięci; gdy nie jest ustawione, aktywna pamięć używa bieżącego modelu sesji |
|
||||
| `config.queryMode` | `"message" \| "recent" \| "full"` | Określa, jak dużą część rozmowy widzi blokujący podagent pamięci |
|
||||
| `config.promptStyle` | `"balanced" \| "strict" \| "contextual" \| "recall-heavy" \| "precision-heavy" \| "preference-only"` | Określa, jak chętnie lub rygorystycznie blokujący podagent pamięci decyduje, czy zwrócić pamięć |
|
||||
| `config.thinking` | `"off" \| "minimal" \| "low" \| "medium" \| "high" \| "xhigh" \| "adaptive"` | Zaawansowane nadpisanie poziomu myślenia dla blokującego podagenta pamięci; domyślnie `off` dla szybkości |
|
||||
| `config.promptOverride` | `string` | Zaawansowana pełna zamiana promptu; niezalecana do zwykłego użycia |
|
||||
| `config.promptAppend` | `string` | Zaawansowane dodatkowe instrukcje dołączane do domyślnego lub nadpisanego promptu |
|
||||
| `config.timeoutMs` | `number` | Twardy limit czasu dla blokującego podagenta pamięci |
|
||||
| `config.maxSummaryChars` | `number` | Maksymalna łączna liczba znaków dozwolona w podsumowaniu active-memory |
|
||||
| `config.logging` | `boolean` | Emituje logi aktywnej pamięci podczas dostrajania |
|
||||
| `config.persistTranscripts` | `boolean` | Zachowuje transkrypty blokującego podagenta pamięci na dysku zamiast usuwać pliki tymczasowe |
|
||||
| `config.transcriptDir` | `string` | Względny katalog transkryptów blokującego podagenta pamięci w folderze sesji agenta |
|
||||
|
||||
Przydatne pola do dostrajania:
|
||||
|
||||
| Klucz | Typ | Znaczenie |
|
||||
| ----------------------------- | -------- | ---------------------------------------------------------------- |
|
||||
| `config.maxSummaryChars` | `number` | Maksymalna łączna liczba znaków dozwolona w podsumowaniu active-memory |
|
||||
| `config.recentUserTurns` | `number` | Poprzednie tury użytkownika do uwzględnienia, gdy `queryMode` ma wartość `recent` |
|
||||
| `config.recentAssistantTurns` | `number` | Poprzednie tury asystenta do uwzględnienia, gdy `queryMode` ma wartość `recent` |
|
||||
| `config.recentUserChars` | `number` | Maksymalna liczba znaków na ostatnią turę użytkownika |
|
||||
| `config.recentAssistantChars` | `number` | Maksymalna liczba znaków na ostatnią turę asystenta |
|
||||
| `config.cacheTtlMs` | `number` | Ponowne użycie pamięci podręcznej dla powtarzających się identycznych zapytań |
|
||||
|
||||
## Zalecana konfiguracja
|
||||
|
||||
Zacznij od `recent`.
|
||||
|
||||
```json5
|
||||
{
|
||||
plugins: {
|
||||
entries: {
|
||||
"active-memory": {
|
||||
enabled: true,
|
||||
config: {
|
||||
agents: ["main"],
|
||||
queryMode: "recent",
|
||||
promptStyle: "balanced",
|
||||
timeoutMs: 15000,
|
||||
maxSummaryChars: 220,
|
||||
logging: true,
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
Jeśli chcesz sprawdzić działanie na żywo podczas dostrajania, użyj `/verbose on` w
|
||||
sesji zamiast szukać osobnego polecenia debugowania active-memory.
|
||||
|
||||
Następnie przejdź do:
|
||||
|
||||
- `message`, jeśli chcesz mniejszych opóźnień
|
||||
- `full`, jeśli uznasz, że dodatkowy kontekst jest wart wolniejszego blokującego podagenta pamięci
|
||||
|
||||
## Debugowanie
|
||||
|
||||
Jeśli aktywna pamięć nie pojawia się tam, gdzie się spodziewasz:
|
||||
|
||||
1. Potwierdź, że plugin jest włączony w `plugins.entries.active-memory.enabled`.
|
||||
2. Potwierdź, że identyfikator bieżącego agenta znajduje się w `config.agents`.
|
||||
3. Potwierdź, że testujesz przez interaktywną trwałą sesję czatu.
|
||||
4. Włącz `config.logging: true` i obserwuj logi gateway.
|
||||
5. Sprawdź, czy samo wyszukiwanie pamięci działa, używając `openclaw memory status --deep`.
|
||||
|
||||
Jeśli trafienia pamięci są zbyt zaszumione, zaostrz:
|
||||
|
||||
- `maxSummaryChars`
|
||||
|
||||
Jeśli aktywna pamięć jest zbyt wolna:
|
||||
|
||||
- obniż `queryMode`
|
||||
- obniż `timeoutMs`
|
||||
- zmniejsz liczbę ostatnich tur
|
||||
- zmniejsz limity znaków na turę
|
||||
|
||||
## Powiązane strony
|
||||
|
||||
- [Wyszukiwanie w pamięci](/pl/concepts/memory-search)
|
||||
- [Dokumentacja konfiguracji pamięci](/pl/reference/memory-config)
|
||||
- [Konfiguracja Plugin SDK](/pl/plugins/sdk-setup)
|
||||
@ -4,40 +4,39 @@ read_when:
|
||||
summary: Cykl życia pętli agenta, strumienie i semantyka oczekiwania
|
||||
title: Pętla agenta
|
||||
x-i18n:
|
||||
generated_at: "2026-04-09T01:27:54Z"
|
||||
generated_at: "2026-04-10T09:44:34Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 32d3a73df8dabf449211a6183a70dcfd2a9b6f584dc76d0c4c9147582b2ca6a1
|
||||
source_hash: b6831a5b11e9100e49f650feca51ab44a2bef242ce1b5db2766d0b3b5c5ba729
|
||||
source_path: concepts/agent-loop.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Pętla agenta (OpenClaw)
|
||||
|
||||
Pętla agentowa to pełny „rzeczywisty” przebieg działania agenta: przyjęcie danych wejściowych → złożenie kontekstu → wnioskowanie modelu →
|
||||
wykonanie narzędzi → strumieniowanie odpowiedzi → utrwalenie. To autorytatywna ścieżka, która przekształca wiadomość
|
||||
w działania i końcową odpowiedź, jednocześnie utrzymując spójny stan sesji.
|
||||
Pętla agenta to pełny, „rzeczywisty” przebieg działania agenta: przyjęcie danych wejściowych → złożenie kontekstu → wnioskowanie modelu →
|
||||
wykonanie narzędzi → strumieniowanie odpowiedzi → utrwalenie. To autorytatywna ścieżka, która zamienia wiadomość
|
||||
w działania i końcową odpowiedź, przy zachowaniu spójnego stanu sesji.
|
||||
|
||||
W OpenClaw pętla to pojedynczy, serializowany przebieg na sesję, który emituje zdarzenia cyklu życia i strumieni
|
||||
gdy model myśli, wywołuje narzędzia i strumieniuje dane wyjściowe. Ten dokument wyjaśnia, jak ta rzeczywista pętla
|
||||
jest połączona od początku do końca.
|
||||
W OpenClaw pętla to pojedynczy, serializowany przebieg na sesję, który emituje zdarzenia cyklu życia i zdarzenia strumienia,
|
||||
gdy model analizuje, wywołuje narzędzia i strumieniuje wynik. Ten dokument wyjaśnia, jak ta rzeczywista pętla jest połączona od początku do końca.
|
||||
|
||||
## Punkty wejścia
|
||||
|
||||
- Gateway RPC: `agent` i `agent.wait`.
|
||||
- CLI: polecenie `agent`.
|
||||
|
||||
## Jak to działa (na wysokim poziomie)
|
||||
## Jak to działa (wysoki poziom)
|
||||
|
||||
1. RPC `agent` weryfikuje parametry, rozwiązuje sesję (sessionKey/sessionId), utrwala metadane sesji i natychmiast zwraca `{ runId, acceptedAt }`.
|
||||
1. RPC `agent` sprawdza poprawność parametrów, rozpoznaje sesję (sessionKey/sessionId), utrwala metadane sesji i natychmiast zwraca `{ runId, acceptedAt }`.
|
||||
2. `agentCommand` uruchamia agenta:
|
||||
- rozwiązuje domyślne wartości modelu + thinking/verbose
|
||||
- rozpoznaje model + domyślne wartości thinking/verbose
|
||||
- ładuje migawkę Skills
|
||||
- wywołuje `runEmbeddedPiAgent` (środowisko uruchomieniowe pi-agent-core)
|
||||
- emituje **koniec/błąd cyklu życia**, jeśli osadzona pętla tego nie wyemituje
|
||||
- emituje **lifecycle end/error**, jeśli osadzona pętla sama go nie emituje
|
||||
3. `runEmbeddedPiAgent`:
|
||||
- serializuje przebiegi przez kolejki per sesja i globalne
|
||||
- rozwiązuje profil modelu + auth i buduje sesję pi
|
||||
- rozpoznaje model + profil uwierzytelniania i buduje sesję Pi
|
||||
- subskrybuje zdarzenia pi i strumieniuje delty asystenta/narzędzi
|
||||
- wymusza limit czasu -> przerywa przebieg po jego przekroczeniu
|
||||
- zwraca ładunki + metadane użycia
|
||||
@ -46,28 +45,28 @@ jest połączona od początku do końca.
|
||||
- delty asystenta => `stream: "assistant"`
|
||||
- zdarzenia cyklu życia => `stream: "lifecycle"` (`phase: "start" | "end" | "error"`)
|
||||
5. `agent.wait` używa `waitForAgentRun`:
|
||||
- czeka na **koniec/błąd cyklu życia** dla `runId`
|
||||
- czeka na **lifecycle end/error** dla `runId`
|
||||
- zwraca `{ status: ok|error|timeout, startedAt, endedAt, error? }`
|
||||
|
||||
## Kolejkowanie + współbieżność
|
||||
|
||||
- Przebiegi są serializowane dla każdego klucza sesji (pas sesji) i opcjonalnie przez pas globalny.
|
||||
- Przebiegi są serializowane dla każdego klucza sesji (pas sesji) i opcjonalnie przez globalny pas.
|
||||
- Zapobiega to wyścigom narzędzi/sesji i utrzymuje spójną historię sesji.
|
||||
- Kanały wiadomości mogą wybierać tryby kolejki (collect/steer/followup), które zasilają ten system pasów.
|
||||
Zobacz [Kolejka poleceń](/pl/concepts/queue).
|
||||
Zobacz [Command Queue](/pl/concepts/queue).
|
||||
|
||||
## Przygotowanie sesji + przestrzeni roboczej
|
||||
## Przygotowanie sesji + obszaru roboczego
|
||||
|
||||
- Przestrzeń robocza jest rozwiązywana i tworzona; przebiegi sandboxowane mogą przekierowywać do katalogu głównego przestrzeni roboczej sandboxa.
|
||||
- Skills są ładowane (lub ponownie używane z migawki) i wstrzykiwane do env oraz promptu.
|
||||
- Pliki bootstrap/kontekstu są rozwiązywane i wstrzykiwane do raportu promptu systemowego.
|
||||
- Uzyskiwana jest blokada zapisu sesji; `SessionManager` jest otwierany i przygotowywany przed strumieniowaniem.
|
||||
- Obszar roboczy jest rozpoznawany i tworzony; przebiegi piaskownicowane mogą zostać przekierowane do katalogu głównego obszaru roboczego sandboxa.
|
||||
- Skills są ładowane (lub ponownie używane z migawki) i wstrzykiwane do środowiska oraz promptu.
|
||||
- Pliki bootstrap/context są rozpoznawane i wstrzykiwane do raportu promptu systemowego.
|
||||
- Uzyskiwana jest blokada zapisu sesji; `SessionManager` jest otwierany i przygotowywany przed rozpoczęciem strumieniowania.
|
||||
|
||||
## Składanie promptu + prompt systemowy
|
||||
|
||||
- Prompt systemowy jest budowany z bazowego promptu OpenClaw, promptu Skills, kontekstu bootstrap i nadpisań dla przebiegu.
|
||||
- Wymuszane są limity specyficzne dla modelu i tokeny rezerwowe dla kompaktowania.
|
||||
- Zobacz [Prompt systemowy](/pl/concepts/system-prompt), aby sprawdzić, co widzi model.
|
||||
- Prompt systemowy jest budowany na podstawie bazowego promptu OpenClaw, promptu Skills, kontekstu bootstrap i nadpisań dla danego przebiegu.
|
||||
- Wymuszane są limity specyficzne dla modelu oraz rezerwa tokenów na kompaktowanie.
|
||||
- Zobacz [System prompt](/pl/concepts/system-prompt), aby sprawdzić, co widzi model.
|
||||
|
||||
## Punkty hooków (gdzie można przechwycić)
|
||||
|
||||
@ -78,71 +77,70 @@ OpenClaw ma dwa systemy hooków:
|
||||
|
||||
### Hooki wewnętrzne (hooki Gateway)
|
||||
|
||||
- **`agent:bootstrap`**: uruchamia się podczas budowania plików bootstrap przed finalizacją promptu systemowego.
|
||||
- **`agent:bootstrap`**: uruchamia się podczas budowania plików bootstrap, zanim prompt systemowy zostanie ostatecznie sfinalizowany.
|
||||
Użyj tego, aby dodawać/usuwać pliki kontekstu bootstrap.
|
||||
- **Hooki poleceń**: `/new`, `/reset`, `/stop` i inne zdarzenia poleceń (zobacz dokumentację hooków).
|
||||
- **Hooki poleceń**: `/new`, `/reset`, `/stop` i inne zdarzenia poleceń (zobacz dokumentację Hooks).
|
||||
|
||||
Zobacz [Hooki](/pl/automation/hooks), aby sprawdzić konfigurację i przykłady.
|
||||
Zobacz [Hooks](/pl/automation/hooks), aby poznać konfigurację i przykłady.
|
||||
|
||||
### Hooki pluginów (cykl życia agenta + gateway)
|
||||
|
||||
Uruchamiają się wewnątrz pętli agenta lub potoku gateway:
|
||||
Są uruchamiane wewnątrz pętli agenta lub potoku gateway:
|
||||
|
||||
- **`before_model_resolve`**: uruchamia się przed sesją (bez `messages`), aby deterministycznie nadpisać dostawcę/model przed rozwiązywaniem modelu.
|
||||
- **`before_prompt_build`**: uruchamia się po załadowaniu sesji (z `messages`), aby wstrzyknąć `prependContext`, `systemPrompt`, `prependSystemContext` lub `appendSystemContext` przed wysłaniem promptu. Używaj `prependContext` dla dynamicznego tekstu per tura, a pól kontekstu systemowego dla stabilnych wskazówek, które powinny znajdować się w przestrzeni promptu systemowego.
|
||||
- **`before_agent_start`**: hook zgodności wstecznej; może uruchamiać się w obu fazach; preferuj powyższe jawne hooki.
|
||||
- **`before_agent_reply`**: uruchamia się po działaniach inline i przed wywołaniem LLM, pozwalając pluginowi przejąć turę i zwrócić syntetyczną odpowiedź lub całkowicie wyciszyć turę.
|
||||
- **`agent_end`**: sprawdza końcową listę wiadomości i metadane przebiegu po zakończeniu.
|
||||
- **`before_model_resolve`**: uruchamia się przed sesją (bez `messages`), aby deterministycznie nadpisać dostawcę/model przed rozpoznaniem modelu.
|
||||
- **`before_prompt_build`**: uruchamia się po załadowaniu sesji (z `messages`), aby wstrzyknąć `prependContext`, `systemPrompt`, `prependSystemContext` lub `appendSystemContext` przed wysłaniem promptu. Używaj `prependContext` do dynamicznego tekstu dla danego obrotu i pól kontekstu systemowego do stabilnych wskazówek, które powinny znajdować się w obszarze promptu systemowego.
|
||||
- **`before_agent_start`**: hook zgodności wstecznej; może uruchamiać się w obu fazach — preferuj powyższe jawne hooki.
|
||||
- **`before_agent_reply`**: uruchamia się po działaniach inline i przed wywołaniem LLM, pozwalając pluginowi przejąć obrót i zwrócić syntetyczną odpowiedź lub całkowicie wyciszyć obrót.
|
||||
- **`agent_end`**: umożliwia inspekcję końcowej listy wiadomości i metadanych przebiegu po zakończeniu.
|
||||
- **`before_compaction` / `after_compaction`**: obserwują lub opisują cykle kompaktowania.
|
||||
- **`before_tool_call` / `after_tool_call`**: przechwytują parametry/wyniki narzędzi.
|
||||
- **`before_install`**: sprawdza wbudowane wyniki skanowania i opcjonalnie blokuje instalacje skillów lub pluginów.
|
||||
- **`before_install`**: umożliwia inspekcję wyników wbudowanego skanowania i opcjonalne blokowanie instalacji Skills lub pluginów.
|
||||
- **`tool_result_persist`**: synchronicznie przekształca wyniki narzędzi przed zapisaniem ich do transkryptu sesji.
|
||||
- **`message_received` / `message_sending` / `message_sent`**: hooki wiadomości przychodzących i wychodzących.
|
||||
- **`session_start` / `session_end`**: granice cyklu życia sesji.
|
||||
- **`gateway_start` / `gateway_stop`**: zdarzenia cyklu życia gateway.
|
||||
|
||||
Zasady decyzji hooków dla zabezpieczeń wychodzących/narzędzi:
|
||||
Zasady podejmowania decyzji przez hooki dla zabezpieczeń wiadomości wychodzących/narzędzi:
|
||||
|
||||
- `before_tool_call`: `{ block: true }` jest końcowe i zatrzymuje handlery o niższym priorytecie.
|
||||
- `before_tool_call`: `{ block: true }` jest terminalne i zatrzymuje handlery o niższym priorytecie.
|
||||
- `before_tool_call`: `{ block: false }` nic nie robi i nie usuwa wcześniejszej blokady.
|
||||
- `before_install`: `{ block: true }` jest końcowe i zatrzymuje handlery o niższym priorytecie.
|
||||
- `before_install`: `{ block: true }` jest terminalne i zatrzymuje handlery o niższym priorytecie.
|
||||
- `before_install`: `{ block: false }` nic nie robi i nie usuwa wcześniejszej blokady.
|
||||
- `message_sending`: `{ cancel: true }` jest końcowe i zatrzymuje handlery o niższym priorytecie.
|
||||
- `message_sending`: `{ cancel: true }` jest terminalne i zatrzymuje handlery o niższym priorytecie.
|
||||
- `message_sending`: `{ cancel: false }` nic nie robi i nie usuwa wcześniejszego anulowania.
|
||||
|
||||
Zobacz [Hooki pluginów](/pl/plugins/architecture#provider-runtime-hooks), aby sprawdzić API hooków i szczegóły rejestracji.
|
||||
Zobacz [Plugin hooks](/pl/plugins/architecture#provider-runtime-hooks), aby poznać API hooków i szczegóły rejestracji.
|
||||
|
||||
## Strumieniowanie + odpowiedzi częściowe
|
||||
|
||||
- Delty asystenta są strumieniowane z pi-agent-core i emitowane jako zdarzenia `assistant`.
|
||||
- Strumieniowanie bloków może emitować odpowiedzi częściowe na `text_end` lub `message_end`.
|
||||
- Strumieniowanie bloków może emitować odpowiedzi częściowe przy `text_end` lub `message_end`.
|
||||
- Strumieniowanie rozumowania może być emitowane jako osobny strumień lub jako odpowiedzi blokowe.
|
||||
- Zobacz [Strumieniowanie](/pl/concepts/streaming), aby sprawdzić dzielenie na fragmenty i zachowanie odpowiedzi blokowych.
|
||||
- Zobacz [Streaming](/pl/concepts/streaming), aby poznać zachowanie fragmentacji i odpowiedzi blokowych.
|
||||
|
||||
## Wykonanie narzędzi + narzędzia do wiadomości
|
||||
## Wykonywanie narzędzi + narzędzia wiadomości
|
||||
|
||||
- Zdarzenia start/aktualizacja/koniec narzędzi są emitowane w strumieniu `tool`.
|
||||
- Wyniki narzędzi są sanitizowane pod kątem rozmiaru i ładunków obrazów przed logowaniem/emisją.
|
||||
- Wysłania narzędzi do wiadomości są śledzone, aby wyeliminować zduplikowane potwierdzenia asystenta.
|
||||
- Zdarzenia start/update/end narzędzi są emitowane w strumieniu `tool`.
|
||||
- Wyniki narzędzi są oczyszczane pod kątem rozmiaru i ładunków obrazów przed logowaniem/emisją.
|
||||
- Wysłania przez narzędzia wiadomości są śledzone, aby tłumić zduplikowane potwierdzenia asystenta.
|
||||
|
||||
## Kształtowanie odpowiedzi + wyciszanie
|
||||
## Kształtowanie odpowiedzi + tłumienie
|
||||
|
||||
- Końcowe ładunki są składane z:
|
||||
- tekstu asystenta (i opcjonalnie rozumowania)
|
||||
- podsumowań narzędzi inline (gdy verbose + dozwolone)
|
||||
- tekstu błędu asystenta, gdy model zwraca błąd
|
||||
- Dokładny token wyciszenia `NO_REPLY` / `no_reply` jest odfiltrowywany z wychodzących
|
||||
- podsumowań narzędzi inline (gdy `verbose` jest włączone i dozwolone)
|
||||
- tekstu błędu asystenta, gdy model zwróci błąd
|
||||
- Dokładny cichy token `NO_REPLY` / `no_reply` jest odfiltrowywany z wychodzących
|
||||
ładunków.
|
||||
- Duplikaty narzędzi do wiadomości są usuwane z końcowej listy ładunków.
|
||||
- Jeśli nie pozostaną żadne renderowalne ładunki, a narzędzie zwróciło błąd, emitowana jest
|
||||
zapasowa odpowiedź błędu narzędzia
|
||||
(chyba że narzędzie do wiadomości już wysłało widoczną dla użytkownika odpowiedź).
|
||||
- Duplikaty z narzędzi wiadomości są usuwane z końcowej listy ładunków.
|
||||
- Jeśli nie pozostaną żadne renderowalne ładunki, a narzędzie zwróciło błąd, emitowana jest zapasowa odpowiedź błędu narzędzia
|
||||
(chyba że narzędzie wiadomości wysłało już odpowiedź widoczną dla użytkownika).
|
||||
|
||||
## Kompaktowanie + ponowienia
|
||||
|
||||
- Automatyczne kompaktowanie emituje zdarzenia strumienia `compaction` i może wywołać ponowienie.
|
||||
- Przy ponowieniu bufory w pamięci i podsumowania narzędzi są resetowane, aby uniknąć zduplikowanego wyjścia.
|
||||
- Zobacz [Kompaktowanie](/pl/concepts/compaction), aby sprawdzić potok kompaktowania.
|
||||
- Zobacz [Compaction](/pl/concepts/compaction), aby poznać potok kompaktowania.
|
||||
|
||||
## Strumienie zdarzeń (obecnie)
|
||||
|
||||
@ -152,14 +150,14 @@ Zobacz [Hooki pluginów](/pl/plugins/architecture#provider-runtime-hooks), aby s
|
||||
|
||||
## Obsługa kanału czatu
|
||||
|
||||
- Delty asystenta są buforowane do wiadomości czatu `delta`.
|
||||
- Końcowa wiadomość czatu `final` jest emitowana przy **końcu/błędzie cyklu życia**.
|
||||
- Delty asystenta są buforowane do komunikatów czatu `delta`.
|
||||
- Końcowy komunikat czatu `final` jest emitowany przy **lifecycle end/error**.
|
||||
|
||||
## Limity czasu
|
||||
|
||||
- Domyślnie `agent.wait`: 30 s (tylko oczekiwanie). Parametr `timeoutMs` nadpisuje tę wartość.
|
||||
- Czas działania agenta: domyślnie `agents.defaults.timeoutSeconds` to 172800 s (48 godzin); wymuszany przez licznik przerwania w `runEmbeddedPiAgent`.
|
||||
- Limit bezczynności LLM: `agents.defaults.llm.idleTimeoutSeconds` przerywa żądanie modelu, gdy przed upływem okna bezczynności nie nadejdą żadne fragmenty odpowiedzi. Ustaw tę wartość jawnie dla wolnych modeli lokalnych lub dostawców rozumowania/wywołań narzędzi; ustaw `0`, aby wyłączyć. Jeśli nie jest ustawiona, OpenClaw używa `agents.defaults.timeoutSeconds`, gdy jest skonfigurowane, w przeciwnym razie 60 s. Przebiegi wyzwalane przez cron bez jawnego limitu czasu LLM lub agenta wyłączają mechanizm bezczynności i polegają na zewnętrznym limicie czasu crona.
|
||||
- Domyślny `agent.wait`: 30 s (tylko oczekiwanie). Parametr `timeoutMs` go nadpisuje.
|
||||
- Czas działania agenta: domyślnie `agents.defaults.timeoutSeconds` wynosi 172800 s (48 godzin); egzekwowany przez licznik przerwania w `runEmbeddedPiAgent`.
|
||||
- Limit bezczynności LLM: `agents.defaults.llm.idleTimeoutSeconds` przerywa żądanie modelu, gdy przed upływem okna bezczynności nie nadejdą żadne fragmenty odpowiedzi. Ustaw go jawnie dla wolnych modeli lokalnych lub dostawców rozumowania/wywołań narzędzi; ustaw na 0, aby wyłączyć. Jeśli nie jest ustawiony, OpenClaw używa `agents.defaults.timeoutSeconds`, jeśli skonfigurowano, w przeciwnym razie 120 s. Przebiegi wyzwalane przez cron bez jawnego limitu czasu LLM lub agenta wyłączają nadzorcę bezczynności i polegają na zewnętrznym limicie czasu crona.
|
||||
|
||||
## Gdzie wszystko może zakończyć się wcześniej
|
||||
|
||||
@ -170,8 +168,8 @@ Zobacz [Hooki pluginów](/pl/plugins/architecture#provider-runtime-hooks), aby s
|
||||
|
||||
## Powiązane
|
||||
|
||||
- [Narzędzia](/pl/tools) — dostępne narzędzia agenta
|
||||
- [Hooki](/pl/automation/hooks) — skrypty sterowane zdarzeniami wyzwalane przez zdarzenia cyklu życia agenta
|
||||
- [Kompaktowanie](/pl/concepts/compaction) — jak podsumowywane są długie rozmowy
|
||||
- [Zgody exec](/pl/tools/exec-approvals) — bramki zatwierdzania dla poleceń powłoki
|
||||
- [Thinking](/pl/tools/thinking) — konfiguracja poziomu myślenia/rozumowania
|
||||
- [Tools](/pl/tools) — dostępne narzędzia agenta
|
||||
- [Hooks](/pl/automation/hooks) — skrypty sterowane zdarzeniami, wyzwalane przez zdarzenia cyklu życia agenta
|
||||
- [Compaction](/pl/concepts/compaction) — jak podsumowywane są długie rozmowy
|
||||
- [Exec Approvals](/pl/tools/exec-approvals) — bramki zatwierdzania dla poleceń powłoki
|
||||
- [Thinking](/pl/tools/thinking) — konfiguracja poziomu thinking/rozumowania
|
||||
|
||||
@ -1,15 +1,15 @@
|
||||
---
|
||||
read_when:
|
||||
- Chcesz zrozumieć, jak działa `memory_search`
|
||||
- Chcesz zrozumieć, jak działa memory_search
|
||||
- Chcesz wybrać dostawcę embeddingów
|
||||
- Chcesz dostroić jakość wyszukiwania
|
||||
summary: Jak wyszukiwanie pamięci znajduje odpowiednie notatki za pomocą embeddingów i wyszukiwania hybrydowego
|
||||
summary: Jak wyszukiwanie w pamięci znajduje odpowiednie notatki za pomocą embeddingów i wyszukiwania hybrydowego
|
||||
title: Wyszukiwanie w pamięci
|
||||
x-i18n:
|
||||
generated_at: "2026-04-06T03:06:39Z"
|
||||
generated_at: "2026-04-10T09:44:32Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: b6541cd702bff41f9a468dad75ea438b70c44db7c65a4b793cbacaf9e583c7e9
|
||||
source_hash: ca0237f4f1ee69dcbfb12e6e9527a53e368c0bf9b429e506831d4af2f3a3ac6f
|
||||
source_path: concepts/memory-search.md
|
||||
workflow: 15
|
||||
---
|
||||
@ -17,8 +17,8 @@ x-i18n:
|
||||
# Wyszukiwanie w pamięci
|
||||
|
||||
`memory_search` znajduje odpowiednie notatki z Twoich plików pamięci, nawet gdy
|
||||
sformułowania różnią się od oryginalnego tekstu. Działa przez indeksowanie pamięci w małych
|
||||
fragmentach i przeszukiwanie ich za pomocą embeddingów, słów kluczowych lub obu tych metod.
|
||||
sformułowania różnią się od oryginalnego tekstu. Działa poprzez indeksowanie pamięci na małe
|
||||
fragmenty i przeszukiwanie ich za pomocą embeddingów, słów kluczowych albo obu tych metod.
|
||||
|
||||
## Szybki start
|
||||
|
||||
@ -43,18 +43,18 @@ W przypadku lokalnych embeddingów bez klucza API użyj `provider: "local"` (wym
|
||||
## Obsługiwani dostawcy
|
||||
|
||||
| Dostawca | ID | Wymaga klucza API | Uwagi |
|
||||
| -------- | --------- | ------------- | ---------------------------------------------------- |
|
||||
| OpenAI | `openai` | Tak | Wykrywany automatycznie, szybki |
|
||||
| Gemini | `gemini` | Tak | Obsługuje indeksowanie obrazów i dźwięku |
|
||||
| Voyage | `voyage` | Tak | Wykrywany automatycznie |
|
||||
| Mistral | `mistral` | Tak | Wykrywany automatycznie |
|
||||
| Bedrock | `bedrock` | Nie | Wykrywany automatycznie, gdy łańcuch poświadczeń AWS zostanie rozwiązany |
|
||||
| Ollama | `ollama` | Nie | Lokalny, musi być ustawiony jawnie |
|
||||
| Local | `local` | Nie | Model GGUF, pobieranie ~0.6 GB |
|
||||
| -------- | --------- | ----------------- | ---------------------------------------------------- |
|
||||
| OpenAI | `openai` | Tak | Wykrywany automatycznie, szybki |
|
||||
| Gemini | `gemini` | Tak | Obsługuje indeksowanie obrazów/dźwięku |
|
||||
| Voyage | `voyage` | Tak | Wykrywany automatycznie |
|
||||
| Mistral | `mistral` | Tak | Wykrywany automatycznie |
|
||||
| Bedrock | `bedrock` | Nie | Wykrywany automatycznie, gdy łańcuch poświadczeń AWS zostanie rozwiązany |
|
||||
| Ollama | `ollama` | Nie | Lokalny, trzeba ustawić jawnie |
|
||||
| Local | `local` | Nie | Model GGUF, pobieranie ~0.6 GB |
|
||||
|
||||
## Jak działa wyszukiwanie
|
||||
|
||||
OpenClaw uruchamia równolegle dwie ścieżki pobierania i scala wyniki:
|
||||
OpenClaw uruchamia równolegle dwie ścieżki pobierania wyników i scala ich rezultaty:
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
@ -72,30 +72,30 @@ flowchart LR
|
||||
- **Wyszukiwanie słów kluczowych BM25** znajduje dokładne dopasowania (ID, ciągi błędów, klucze
|
||||
konfiguracji).
|
||||
|
||||
Jeśli dostępna jest tylko jedna ścieżka (brak embeddingów lub brak FTS), druga działa samodzielnie.
|
||||
Jeśli dostępna jest tylko jedna ścieżka (brak embeddingów albo brak FTS), działa samodzielnie tylko druga.
|
||||
|
||||
## Poprawianie jakości wyszukiwania
|
||||
## Poprawa jakości wyszukiwania
|
||||
|
||||
Dwie opcjonalne funkcje pomagają, gdy masz dużą historię notatek:
|
||||
|
||||
### Zanikanie czasowe
|
||||
|
||||
Stare notatki stopniowo tracą wagę w rankingu, dzięki czemu najpierw pojawiają się nowsze informacje.
|
||||
Przy domyślnym okresie półtrwania wynoszącym 30 dni notatka z zeszłego miesiąca uzyskuje wynik równy 50%
|
||||
swojej pierwotnej wagi. Stałe pliki, takie jak `MEMORY.md`, nigdy nie podlegają zanikaniu.
|
||||
Starsze notatki stopniowo tracą wagę w rankingu, dzięki czemu najpierw pojawiają się nowsze informacje.
|
||||
Przy domyślnym okresie półtrwania wynoszącym 30 dni notatka z zeszłego miesiąca ma wynik równy 50% swojej
|
||||
pierwotnej wagi. Pliki stałe, takie jak `MEMORY.md`, nigdy nie podlegają zanikaniu.
|
||||
|
||||
<Tip>
|
||||
Włącz zanikanie czasowe, jeśli Twój agent ma wiele miesięcy codziennych notatek, a nieaktualne
|
||||
informacje wciąż są wyżej w rankingu niż nowszy kontekst.
|
||||
informacje stale wyprzedzają nowszy kontekst.
|
||||
</Tip>
|
||||
|
||||
### MMR (różnorodność)
|
||||
|
||||
Ogranicza nadmiarowe wyniki. Jeśli pięć notatek wspomina tę samą konfigurację routera, MMR
|
||||
sprawia, że najwyższe wyniki obejmują różne tematy zamiast się powtarzać.
|
||||
Ogranicza powtarzające się wyniki. Jeśli pięć notatek wspomina tę samą konfigurację routera, MMR
|
||||
sprawia, że najwyższe wyniki obejmują różne tematy, zamiast się powtarzać.
|
||||
|
||||
<Tip>
|
||||
Włącz MMR, jeśli `memory_search` ciągle zwraca niemal zduplikowane fragmenty z
|
||||
Włącz MMR, jeśli `memory_search` stale zwraca niemal identyczne fragmenty z
|
||||
różnych codziennych notatek.
|
||||
</Tip>
|
||||
|
||||
@ -120,16 +120,16 @@ różnych codziennych notatek.
|
||||
|
||||
## Pamięć multimodalna
|
||||
|
||||
Dzięki Gemini Embedding 2 możesz indeksować obrazy i pliki audio razem z
|
||||
Markdownem. Zapytania wyszukiwania nadal pozostają tekstowe, ale są dopasowywane do treści wizualnych i audio.
|
||||
Instrukcje konfiguracji znajdziesz w [Dokumentacji konfiguracji pamięci](/pl/reference/memory-config).
|
||||
Z Gemini Embedding 2 możesz indeksować obrazy i pliki audio obok plików
|
||||
Markdown. Zapytania wyszukiwania nadal pozostają tekstowe, ale dopasowują się do treści wizualnych i audio.
|
||||
Informacje o konfiguracji znajdziesz w [dokumencie referencyjnym konfiguracji pamięci](/pl/reference/memory-config).
|
||||
|
||||
## Wyszukiwanie pamięci sesji
|
||||
## Wyszukiwanie w pamięci sesji
|
||||
|
||||
Opcjonalnie możesz indeksować transkrypcje sesji, aby `memory_search` mogło przypominać sobie
|
||||
wcześniejsze rozmowy. Jest to funkcja opcjonalna, włączana przez
|
||||
Możesz opcjonalnie indeksować transkrypcje sesji, aby `memory_search` mógł przywoływać
|
||||
wcześniejsze rozmowy. Jest to funkcja opt-in dostępna przez
|
||||
`memorySearch.experimental.sessionMemory`. Szczegóły znajdziesz w
|
||||
[dokumentacji konfiguracji](/pl/reference/memory-config).
|
||||
[dokumencie referencyjnym konfiguracji](/pl/reference/memory-config).
|
||||
|
||||
## Rozwiązywanie problemów
|
||||
|
||||
@ -139,10 +139,11 @@ wcześniejsze rozmowy. Jest to funkcja opcjonalna, włączana przez
|
||||
**Tylko dopasowania słów kluczowych?** Twój dostawca embeddingów może nie być skonfigurowany. Sprawdź
|
||||
`openclaw memory status --deep`.
|
||||
|
||||
**Nie można znaleźć tekstu CJK?** Odbuduj indeks FTS za pomocą
|
||||
**Nie znajduje tekstu CJK?** Odbuduj indeks FTS za pomocą
|
||||
`openclaw memory index --force`.
|
||||
|
||||
## Dalsza lektura
|
||||
|
||||
- [Aktywna pamięć](/pl/concepts/active-memory) -- pamięć sub-agentów dla interaktywnych sesji czatu
|
||||
- [Pamięć](/pl/concepts/memory) -- układ plików, backendy, narzędzia
|
||||
- [Dokumentacja konfiguracji pamięci](/pl/reference/memory-config) -- wszystkie opcje konfiguracji
|
||||
- [Dokument referencyjny konfiguracji pamięci](/pl/reference/memory-config) -- wszystkie opcje konfiguracji
|
||||
|
||||
@ -3,35 +3,34 @@ read_when:
|
||||
- Rozszerzanie qa-lab lub qa-channel
|
||||
- Dodawanie scenariuszy QA opartych na repozytorium
|
||||
- Tworzenie bardziej realistycznej automatyzacji QA wokół panelu Gateway
|
||||
summary: Prywatna struktura automatyzacji QA dla qa-lab, qa-channel, scenariuszy seed i raportów protokołu
|
||||
summary: Prywatny kształt automatyzacji QA dla qa-lab, qa-channel, scenariuszy inicjalizowanych seedem i raportów protokołu
|
||||
title: Automatyzacja QA E2E
|
||||
x-i18n:
|
||||
generated_at: "2026-04-09T01:27:48Z"
|
||||
generated_at: "2026-04-10T09:44:32Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: c922607d67e0f3a2489ac82bc9f510f7294ced039c1014c15b676d826441d833
|
||||
source_hash: 357d6698304ff7a8c4aa8a7be97f684d50f72b524740050aa761ac0ee68266de
|
||||
source_path: concepts/qa-e2e-automation.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Automatyzacja QA E2E
|
||||
|
||||
Prywatny stos QA ma na celu testowanie OpenClaw w bardziej realistyczny,
|
||||
zbliżony do kanałów sposób, niż może to zapewnić pojedynczy test jednostkowy.
|
||||
Prywatny stos QA ma na celu testowanie OpenClaw w sposób bardziej realistyczny,
|
||||
ukształtowany przez kanały, niż może to zrobić pojedynczy test jednostkowy.
|
||||
|
||||
Obecne elementy:
|
||||
|
||||
- `extensions/qa-channel`: syntetyczny kanał wiadomości z obsługą DM, kanałów, wątków,
|
||||
- `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 transkryptu,
|
||||
wstrzykiwania wiadomości przychodzących i eksportowania raportu Markdown.
|
||||
- `qa/`: zasoby seed oparte na repozytorium dla zadania startowego i bazowych
|
||||
scenariuszy QA.
|
||||
- `qa/`: zasoby seed oparte na repozytorium dla zadania startowego i bazowych scenariuszy QA.
|
||||
|
||||
Obecny przepływ pracy operatora QA to dwupanelowa witryna QA:
|
||||
|
||||
- Lewy panel: panel Gateway (Control UI) z agentem.
|
||||
- Prawy panel: QA Lab, pokazujący transkrypt w stylu Slacka i plan scenariusza.
|
||||
- Po lewej: panel Gateway (Control UI) z agentem.
|
||||
- Po prawej: QA Lab, pokazujący transkrypt w stylu Slacka i plan scenariusza.
|
||||
|
||||
Uruchom za pomocą:
|
||||
|
||||
@ -39,13 +38,13 @@ Uruchom za pomocą:
|
||||
pnpm qa:lab:up
|
||||
```
|
||||
|
||||
To buduje witrynę QA, uruchamia ścieżkę Gateway opartą na Dockerze i udostępnia
|
||||
stronę QA Lab, na której operator lub pętla automatyzacji może przekazać agentowi
|
||||
misję QA, obserwować rzeczywiste zachowanie kanału oraz zapisywać, co działało,
|
||||
co zawiodło lub co pozostało zablokowane.
|
||||
To buduje witrynę QA, uruchamia ścieżkę gateway opartą na Dockerze i udostępnia
|
||||
stronę QA Lab, na której operator lub pętla automatyzacji może przydzielić
|
||||
agentowi misję QA, obserwować rzeczywiste zachowanie kanału oraz rejestrować,
|
||||
co zadziałało, co zawiodło lub co pozostało zablokowane.
|
||||
|
||||
Aby szybciej iterować nad interfejsem QA Lab bez przebudowywania obrazu Dockera za każdym razem,
|
||||
uruchom stos z bind-mountowanym bundlem QA Lab:
|
||||
uruchom stos z bind-montowanym bundelem QA Lab:
|
||||
|
||||
```bash
|
||||
pnpm openclaw qa docker-build-image
|
||||
@ -54,10 +53,25 @@ pnpm qa:lab:up:fast
|
||||
pnpm qa:lab:watch
|
||||
```
|
||||
|
||||
`qa:lab:up:fast` utrzymuje usługi Dockera na wcześniej zbudowanym obrazie i bind-mountuje
|
||||
`qa:lab:up:fast` utrzymuje usługi Dockera na wcześniej zbudowanym obrazie i bind-montuje
|
||||
`extensions/qa-lab/web/dist` do kontenera `qa-lab`. `qa:lab:watch`
|
||||
przebudowuje ten bundle po zmianach, a przeglądarka automatycznie przeładowuje się,
|
||||
gdy hash zasobu QA Lab ulegnie zmianie.
|
||||
przebudowuje ten bundle przy zmianach, a przeglądarka automatycznie przeładowuje się,
|
||||
gdy zmienia się hash zasobu QA Lab.
|
||||
|
||||
Aby uruchomić jednorazową ścieżkę Linux VM bez włączania Dockera do ścieżki QA, użyj:
|
||||
|
||||
```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 zwykły raport QA i
|
||||
podsumowanie z powrotem do `.artifacts/qa-e2e/...` na hoście.
|
||||
Wykorzystuje to samo zachowanie wyboru scenariusza co `qa suite` na hoście.
|
||||
Uruchomienia live przekazują obsługiwane wejścia uwierzytelniania QA, które są praktyczne dla
|
||||
gościa: klucze dostawców oparte na env, ścieżkę konfiguracji dostawcy live QA oraz
|
||||
`CODEX_HOME`, gdy jest obecne. Utrzymuj `--output-dir` w katalogu repozytorium, aby gość
|
||||
mógł zapisywać z powrotem przez zamontowany workspace.
|
||||
|
||||
## Seedy oparte na repozytorium
|
||||
|
||||
@ -66,17 +80,17 @@ Zasoby seed znajdują się w `qa/`:
|
||||
- `qa/scenarios/index.md`
|
||||
- `qa/scenarios/*.md`
|
||||
|
||||
Są one celowo przechowywane w git, aby plan QA był widoczny zarówno dla ludzi, jak i dla
|
||||
agenta. Lista bazowa powinna pozostać na tyle szeroka, aby obejmować:
|
||||
Są one celowo przechowywane w git, aby plan QA był widoczny zarówno dla ludzi, jak i
|
||||
agenta. Lista bazowa powinna pozostać wystarczająco szeroka, aby obejmować:
|
||||
|
||||
- czat w DM i na kanałach
|
||||
- czat DM i kanałowy
|
||||
- zachowanie wątków
|
||||
- cykl życia akcji na wiadomościach
|
||||
- wywołania cron
|
||||
- wywołania zwrotne cron
|
||||
- przywoływanie pamięci
|
||||
- przełączanie modeli
|
||||
- przekazanie do subagenta
|
||||
- odczytywanie repozytorium i dokumentacji
|
||||
- odczyt repozytorium i dokumentacji
|
||||
- jedno małe zadanie build, takie jak Lobster Invaders
|
||||
|
||||
## Raportowanie
|
||||
@ -84,13 +98,13 @@ agenta. Lista bazowa powinna pozostać na tyle szeroka, aby obejmować:
|
||||
`qa-lab` eksportuje raport protokołu w Markdown na podstawie obserwowanej osi czasu magistrali.
|
||||
Raport powinien odpowiadać na pytania:
|
||||
|
||||
- Co działało
|
||||
- Co zadziałało
|
||||
- Co zawiodło
|
||||
- Co pozostało zablokowane
|
||||
- Jakie scenariusze uzupełniające warto dodać
|
||||
|
||||
W przypadku kontroli charakteru i stylu uruchom ten sam scenariusz dla wielu aktywnych
|
||||
referencji modeli i zapisz oceniany raport Markdown:
|
||||
W przypadku kontroli charakteru i stylu uruchom ten sam scenariusz dla wielu live refów modeli
|
||||
i zapisz oceniony raport Markdown:
|
||||
|
||||
```bash
|
||||
pnpm openclaw qa character-eval \
|
||||
@ -109,41 +123,41 @@ pnpm openclaw qa character-eval \
|
||||
--judge-concurrency 16
|
||||
```
|
||||
|
||||
Polecenie uruchamia lokalne podrzędne procesy QA Gateway, a nie Docker. Scenariusze
|
||||
oceny charakteru powinny ustawiać personę przez `SOUL.md`, a następnie wykonywać zwykłe
|
||||
tury użytkownika, takie jak czat, pomoc dotyczącą workspace i małe zadania na plikach. Modelowi
|
||||
kandydującemu nie należy mówić, że jest oceniany. Polecenie zachowuje każdy pełny
|
||||
transkrypt, rejestruje podstawowe statystyki uruchomienia, a następnie prosi modele oceniające
|
||||
w trybie fast z rozumowaniem `xhigh` o uszeregowanie uruchomień według naturalności, klimatu i humoru.
|
||||
Użyj `--blind-judge-models` podczas porównywania providerów: prompt oceniający nadal otrzymuje
|
||||
każdy transkrypt i status uruchomienia, ale referencje kandydatów są zastępowane neutralnymi
|
||||
etykietami, takimi jak `candidate-01`; raport mapuje rankingi z powrotem na rzeczywiste referencje po
|
||||
To polecenie uruchamia lokalne podrzędne procesy gateway QA, a nie Dockera. Scenariusze
|
||||
oceny charakteru powinny ustawiać personę przez `SOUL.md`, a następnie uruchamiać zwykłe
|
||||
tury użytkownika, takie jak czat, pomoc dotycząca workspace i małe zadania plikowe. Kandydacki model
|
||||
nie powinien być informowany, że jest oceniany. Polecenie zachowuje każdy pełny
|
||||
transkrypt, rejestruje podstawowe statystyki przebiegu, a następnie prosi modele sędziujące w trybie fast z
|
||||
rozumowaniem `xhigh`, aby uszeregowały przebiegi według naturalności, klimatu i humoru.
|
||||
Użyj `--blind-judge-models` podczas porównywania dostawców: prompt sędziego nadal otrzymuje
|
||||
każdy transkrypt i status przebiegu, ale refy kandydatów są zastępowane neutralnymi
|
||||
etykietami, takimi jak `candidate-01`; raport mapuje rankingi z powrotem na rzeczywiste refy po
|
||||
parsowaniu.
|
||||
Uruchomienia kandydatów domyślnie używają poziomu myślenia `high`, a dla modeli OpenAI,
|
||||
które go obsługują, `xhigh`. Zastąp ustawienie dla konkretnego kandydata inline za pomocą
|
||||
Przebiegi kandydatów domyślnie używają poziomu rozumowania `high`, z `xhigh` dla modeli OpenAI,
|
||||
które to obsługują. Zastąp ustawienie dla konkretnego kandydata inline za pomocą
|
||||
`--model provider/model,thinking=<level>`. `--thinking <level>` nadal ustawia
|
||||
globalne ustawienie zapasowe, a starsza forma `--model-thinking <provider/model=level>` jest
|
||||
zachowana dla zgodności.
|
||||
Referencje kandydatów OpenAI domyślnie używają trybu fast, aby tam, gdzie provider to obsługuje,
|
||||
korzystać z przetwarzania priorytetowego. Dodaj inline `,fast`, `,no-fast` lub `,fast=false`, gdy
|
||||
Refy kandydatów OpenAI domyślnie używają trybu fast, aby wykorzystywane było przetwarzanie priorytetowe tam,
|
||||
gdzie dostawca to obsługuje. Dodaj inline `,fast`, `,no-fast` lub `,fast=false`, gdy
|
||||
pojedynczy kandydat lub sędzia wymaga nadpisania. Przekaż `--fast` tylko wtedy, gdy chcesz
|
||||
wymusić tryb fast dla każdego modelu kandydującego. Czasy trwania dla kandydatów i modeli
|
||||
oceniających są zapisywane w raporcie do analizy benchmarków, ale prompty oceniające wyraźnie
|
||||
mówią, aby nie tworzyć rankingu na podstawie szybkości.
|
||||
Zarówno uruchomienia modeli kandydujących, jak i oceniających domyślnie używają współbieżności 16. Zmniejsz
|
||||
`--concurrency` lub `--judge-concurrency`, gdy limity providera lub obciążenie lokalnego Gateway
|
||||
powodują, że uruchomienie staje się zbyt zaszumione.
|
||||
Gdy nie zostanie przekazany żaden kandydat `--model`, ocena charakteru domyślnie używa
|
||||
wymusić tryb fast dla każdego modelu kandydującego. Czasy trwania kandydatów i sędziów są
|
||||
rejestrowane w raporcie do analizy porównawczej, ale prompty sędziów wyraźnie mówią,
|
||||
aby nie tworzyć rankingu według szybkości.
|
||||
Zarówno przebiegi modeli kandydatów, jak i sędziów domyślnie używają współbieżności 16. Zmniejsz
|
||||
`--concurrency` lub `--judge-concurrency`, gdy limity dostawcy lub obciążenie lokalnego gateway
|
||||
sprawiają, że przebieg staje się zbyt zaszumiony.
|
||||
Gdy nie zostanie przekazany żaden kandydacki `--model`, character eval domyślnie używa
|
||||
`openai/gpt-5.4`, `openai/gpt-5.2`, `openai/gpt-5`, `anthropic/claude-opus-4-6`,
|
||||
`anthropic/claude-sonnet-4-6`, `zai/glm-5.1`,
|
||||
`moonshot/kimi-k2.5` oraz
|
||||
`google/gemini-3.1-pro-preview`, gdy nie zostanie przekazany parametr `--model`.
|
||||
Gdy nie zostanie przekazany żaden `--judge-model`, modele oceniające domyślnie używają
|
||||
`google/gemini-3.1-pro-preview`, gdy nie zostanie przekazany `--model`.
|
||||
Gdy nie zostanie przekazany `--judge-model`, sędziowie domyślnie używają
|
||||
`openai/gpt-5.4,thinking=xhigh,fast` oraz
|
||||
`anthropic/claude-opus-4-6,thinking=high`.
|
||||
|
||||
## Powiązana dokumentacja
|
||||
|
||||
- [Testing](/pl/help/testing)
|
||||
- [Testowanie](/pl/help/testing)
|
||||
- [QA Channel](/pl/channels/qa-channel)
|
||||
- [Dashboard](/web/dashboard)
|
||||
- [Panel](/web/dashboard)
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@ -1,34 +1,34 @@
|
||||
---
|
||||
read_when:
|
||||
- Implementowanie lub aktualizowanie klientów WS gateway
|
||||
- Debugowanie niedopasowań protokołu lub niepowodzeń połączenia
|
||||
- Implementowanie lub aktualizowanie klientów WS bramy
|
||||
- Debugowanie niezgodności protokołu lub błędów połączenia
|
||||
- Ponowne generowanie schematu/modeli protokołu
|
||||
summary: 'Protokół Gateway WebSocket: uzgadnianie połączenia, ramki, wersjonowanie'
|
||||
title: Protokół Gateway
|
||||
summary: 'Protokół WebSocket bramy: uzgadnianie połączenia, ramki, wersjonowanie'
|
||||
title: Protokół bramy
|
||||
x-i18n:
|
||||
generated_at: "2026-04-08T02:15:42Z"
|
||||
generated_at: "2026-04-10T09:44:32Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 8635e3ac1dd311dbd3a770b088868aa1495a8d53b3ebc1eae0dfda3b2bf4694a
|
||||
source_hash: 83c820c46d4803d571c770468fd6782619eaa1dca253e156e8087dec735c127f
|
||||
source_path: gateway/protocol.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Protokół Gateway (WebSocket)
|
||||
# Protokół bramy (WebSocket)
|
||||
|
||||
Protokół Gateway WS jest **pojedynczą płaszczyzną sterowania + transportem węzłów** dla
|
||||
OpenClaw. Wszyscy klienci (CLI, interfejs webowy, aplikacja macOS, węzły iOS/Android, bezgłowe
|
||||
węzły) łączą się przez WebSocket i deklarują swoją **rolę** + **zakres** w czasie
|
||||
uzgadniania połączenia.
|
||||
Protokół Gateway WS to **jedyna płaszczyzna sterowania + transport węzłów** dla
|
||||
OpenClaw. Wszyscy klienci (CLI, interfejs webowy, aplikacja macOS, węzły
|
||||
iOS/Android, węzły bezgłowe) łączą się przez WebSocket i deklarują swoją **rolę**
|
||||
+ **zakres** podczas uzgadniania połączenia.
|
||||
|
||||
## Transport
|
||||
|
||||
- WebSocket, ramki tekstowe z ładunkami JSON.
|
||||
- Pierwsza ramka **musi** być żądaniem `connect`.
|
||||
|
||||
## Uzgadnianie połączenia (connect)
|
||||
## Uzgadnianie połączenia (`connect`)
|
||||
|
||||
Gateway → klient (wyzwanie przed połączeniem):
|
||||
Brama → klient (wyzwanie przed połączeniem):
|
||||
|
||||
```json
|
||||
{
|
||||
@ -38,7 +38,7 @@ Gateway → klient (wyzwanie przed połączeniem):
|
||||
}
|
||||
```
|
||||
|
||||
Klient → Gateway:
|
||||
Klient → brama:
|
||||
|
||||
```json
|
||||
{
|
||||
@ -73,7 +73,7 @@ Klient → Gateway:
|
||||
}
|
||||
```
|
||||
|
||||
Gateway → klient:
|
||||
Brama → klient:
|
||||
|
||||
```json
|
||||
{
|
||||
@ -96,8 +96,8 @@ Gdy zostanie wydany token urządzenia, `hello-ok` zawiera także:
|
||||
}
|
||||
```
|
||||
|
||||
Podczas przekazania w zaufanym przepływie bootstrap, `hello-ok.auth` może także zawierać dodatkowe
|
||||
ograniczone wpisy ról w `deviceTokens`:
|
||||
Podczas przekazywania w zaufanym bootstrapie, `hello-ok.auth` może także zawierać
|
||||
dodatkowe ograniczone wpisy ról w `deviceTokens`:
|
||||
|
||||
```json
|
||||
{
|
||||
@ -116,11 +116,12 @@ ograniczone wpisy ról w `deviceTokens`:
|
||||
}
|
||||
```
|
||||
|
||||
W przypadku wbudowanego przepływu bootstrap węzła/operatora podstawowy token węzła pozostaje
|
||||
`scopes: []`, a każdy przekazany token operatora pozostaje ograniczony do listy dozwolonych zakresów
|
||||
operatora bootstrap (`operator.approvals`, `operator.read`,
|
||||
`operator.talk.secrets`, `operator.write`). Sprawdzenia zakresu bootstrap pozostają
|
||||
prefiksowane rolą: wpisy operatora spełniają tylko żądania operatora, a role inne niż operator
|
||||
W przypadku wbudowanego przepływu bootstrap dla węzła/operatora podstawowy token
|
||||
węzła pozostaje z `scopes: []`, a każdy przekazany token operatora pozostaje
|
||||
ograniczony do listy dozwolonych zakresów operatora bootstrapu
|
||||
(`operator.approvals`, `operator.read`, `operator.talk.secrets`,
|
||||
`operator.write`). Kontrole zakresu bootstrapu pozostają prefiksowane rolą:
|
||||
wpisy operatora spełniają tylko żądania operatora, a role inne niż operator
|
||||
nadal wymagają zakresów pod własnym prefiksem roli.
|
||||
|
||||
### Przykład węzła
|
||||
@ -164,14 +165,15 @@ nadal wymagają zakresów pod własnym prefiksem roli.
|
||||
- **Odpowiedź**: `{type:"res", id, ok, payload|error}`
|
||||
- **Zdarzenie**: `{type:"event", event, payload, seq?, stateVersion?}`
|
||||
|
||||
Metody powodujące skutki uboczne wymagają **kluczy idempotencji** (zobacz schemat).
|
||||
Metody wywołujące skutki uboczne wymagają **kluczy idempotencji** (zobacz
|
||||
schemat).
|
||||
|
||||
## Role + zakresy
|
||||
|
||||
### Role
|
||||
|
||||
- `operator` = klient płaszczyzny sterowania (CLI/UI/automatyzacja).
|
||||
- `node` = host możliwości (`camera/screen/canvas/system.run`).
|
||||
- `node` = host możliwości (camera/screen/canvas/system.run).
|
||||
|
||||
### Zakresy (operator)
|
||||
|
||||
@ -187,62 +189,67 @@ Typowe zakresy:
|
||||
`talk.config` z `includeSecrets: true` wymaga `operator.talk.secrets`
|
||||
(lub `operator.admin`).
|
||||
|
||||
Metody Gateway RPC rejestrowane przez pluginy mogą żądać własnego zakresu operatora, ale
|
||||
zastrzeżone prefiksy administracyjne rdzenia (`config.*`, `exec.approvals.*`, `wizard.*`,
|
||||
`update.*`) zawsze są mapowane na `operator.admin`.
|
||||
Metody RPC bramy zarejestrowane przez pluginy mogą wymagać własnego zakresu
|
||||
operatora, ale zarezerwowane prefiksy administracyjne rdzenia (`config.*`,
|
||||
`exec.approvals.*`, `wizard.*`, `update.*`) zawsze są mapowane na
|
||||
`operator.admin`.
|
||||
|
||||
Zakres metody to tylko pierwszy próg kontroli. Niektóre polecenia slash osiągane przez
|
||||
`chat.send` nakładają dodatkowo bardziej rygorystyczne kontrole na poziomie polecenia. Na przykład trwałe
|
||||
zapisy `/config set` i `/config unset` wymagają `operator.admin`.
|
||||
Zakres metody jest tylko pierwszym progiem kontroli. Niektóre polecenia slash
|
||||
osiągane przez `chat.send` nakładają dodatkowo bardziej restrykcyjne kontrole na
|
||||
poziomie polecenia. Na przykład trwałe zapisy `/config set` i `/config unset`
|
||||
wymagają `operator.admin`.
|
||||
|
||||
`node.pair.approve` ma także dodatkową kontrolę zakresu w momencie zatwierdzania ponad
|
||||
bazowy zakres metody:
|
||||
`node.pair.approve` ma także dodatkową kontrolę zakresu podczas zatwierdzania,
|
||||
ponad bazowy zakres metody:
|
||||
|
||||
- żądania bez poleceń: `operator.pairing`
|
||||
- żądania bez polecenia: `operator.pairing`
|
||||
- żądania z poleceniami węzła innymi niż exec: `operator.pairing` + `operator.write`
|
||||
- żądania obejmujące `system.run`, `system.run.prepare` lub `system.which`:
|
||||
- żądania zawierające `system.run`, `system.run.prepare` lub `system.which`:
|
||||
`operator.pairing` + `operator.admin`
|
||||
|
||||
### Caps/commands/permissions (node)
|
||||
|
||||
Węzły deklarują roszczenia możliwości w czasie połączenia:
|
||||
Węzły deklarują żądania możliwości podczas łączenia:
|
||||
|
||||
- `caps`: wysokopoziomowe kategorie możliwości.
|
||||
- `caps`: kategorie możliwości wysokiego poziomu.
|
||||
- `commands`: lista dozwolonych poleceń dla invoke.
|
||||
- `permissions`: szczegółowe przełączniki (np. `screen.record`, `camera.capture`).
|
||||
|
||||
Gateway traktuje je jako **roszczenia** i egzekwuje listy dozwolonych po stronie serwera.
|
||||
Brama traktuje je jako **deklaracje** i egzekwuje listy dozwolonych po stronie
|
||||
serwera.
|
||||
|
||||
## Obecność
|
||||
|
||||
- `system-presence` zwraca wpisy kluczowane tożsamością urządzenia.
|
||||
- Wpisy obecności zawierają `deviceId`, `roles` i `scopes`, aby interfejsy mogły pokazywać jeden wiersz na urządzenie,
|
||||
nawet gdy łączy się ono zarówno jako **operator**, jak i **node**.
|
||||
- `system-presence` zwraca wpisy indeksowane tożsamością urządzenia.
|
||||
- Wpisy obecności zawierają `deviceId`, `roles` i `scopes`, aby interfejsy UI
|
||||
mogły pokazywać jeden wiersz na urządzenie, nawet gdy łączy się ono zarówno
|
||||
jako **operator**, jak i **node**.
|
||||
|
||||
## Typowe rodziny metod RPC
|
||||
|
||||
Ta strona nie jest wygenerowanym pełnym zrzutem, ale publiczna powierzchnia WS jest szersza
|
||||
niż przykłady uzgadniania połączenia/uwierzytelniania powyżej. To są główne rodziny metod, które
|
||||
Gateway udostępnia obecnie.
|
||||
Ta strona nie jest wygenerowanym pełnym zrzutem, ale publiczna powierzchnia WS
|
||||
jest szersza niż przykłady uzgadniania połączenia/uwierzytelniania powyżej. To
|
||||
główne rodziny metod, które brama udostępnia obecnie.
|
||||
|
||||
`hello-ok.features.methods` to zachowawcza lista wykrywania zbudowana z
|
||||
`src/gateway/server-methods-list.ts` oraz załadowanych eksportów metod pluginów/kanałów.
|
||||
Traktuj ją jako wykrywanie funkcji, a nie wygenerowany zrzut każdego pomocniczego wywołania
|
||||
zaimplementowanego w `src/gateway/server-methods/*.ts`.
|
||||
`hello-ok.features.methods` to zachowawcza lista wykrywania zbudowana na bazie
|
||||
`src/gateway/server-methods-list.ts` oraz załadowanych eksportów metod
|
||||
pluginów/kanałów. Traktuj ją jako wykrywanie funkcji, a nie jako wygenerowany
|
||||
zrzut każdego wywoływalnego helpera zaimplementowanego w
|
||||
`src/gateway/server-methods/*.ts`.
|
||||
|
||||
### System i tożsamość
|
||||
|
||||
- `health` zwraca buforowany lub świeżo sprawdzony snapshot kondycji gateway.
|
||||
- `status` zwraca podsumowanie gateway w stylu `/status`; pola wrażliwe są
|
||||
dołączane tylko dla klientów operatora z zakresem admin.
|
||||
- `gateway.identity.get` zwraca tożsamość urządzenia gateway używaną przez przepływy relay i
|
||||
parowania.
|
||||
- `system-presence` zwraca bieżący snapshot obecności dla połączonych
|
||||
urządzeń operatora/węzła.
|
||||
- `system-event` dopisuje zdarzenie systemowe i może aktualizować/rozgłaszać kontekst
|
||||
obecności.
|
||||
- `last-heartbeat` zwraca najnowsze zapisane zdarzenie heartbeat.
|
||||
- `set-heartbeats` przełącza przetwarzanie heartbeat w gateway.
|
||||
- `health` zwraca buforowaną lub świeżo sprawdzoną migawkę stanu zdrowia bramy.
|
||||
- `status` zwraca podsumowanie bramy w stylu `/status`; pola wrażliwe są
|
||||
dołączane tylko dla klientów operatora z zakresem administratora.
|
||||
- `gateway.identity.get` zwraca tożsamość urządzenia bramy używaną przez
|
||||
przepływy relay i parowania.
|
||||
- `system-presence` zwraca bieżącą migawkę obecności dla połączonych urządzeń
|
||||
operatora/węzła.
|
||||
- `system-event` dopisuje zdarzenie systemowe i może aktualizować/rozgłaszać
|
||||
kontekst obecności.
|
||||
- `last-heartbeat` zwraca ostatnie zapisane trwałe zdarzenie heartbeat.
|
||||
- `set-heartbeats` przełącza przetwarzanie heartbeatów na bramie.
|
||||
|
||||
### Modele i użycie
|
||||
|
||||
@ -250,30 +257,31 @@ zaimplementowanego w `src/gateway/server-methods/*.ts`.
|
||||
- `usage.status` zwraca okna użycia dostawcy/podsumowania pozostałego limitu.
|
||||
- `usage.cost` zwraca zagregowane podsumowania kosztów użycia dla zakresu dat.
|
||||
- `doctor.memory.status` zwraca gotowość pamięci wektorowej / embeddingów dla
|
||||
aktywnego domyślnego obszaru roboczego agenta.
|
||||
- `sessions.usage` zwraca podsumowania użycia dla poszczególnych sesji.
|
||||
aktywnego domyślnego workspace agenta.
|
||||
- `sessions.usage` zwraca podsumowania użycia dla każdej sesji.
|
||||
- `sessions.usage.timeseries` zwraca szereg czasowy użycia dla jednej sesji.
|
||||
- `sessions.usage.logs` zwraca wpisy dziennika użycia dla jednej sesji.
|
||||
|
||||
### Kanały i pomocniki logowania
|
||||
### Kanały i helpery logowania
|
||||
|
||||
- `channels.status` zwraca podsumowania statusu wbudowanych + dołączonych kanałów/pluginów.
|
||||
- `channels.logout` wylogowuje z określonego kanału/konta tam, gdzie kanał
|
||||
- `channels.status` zwraca podsumowania stanu kanałów/pluginów wbudowanych i
|
||||
dołączonych.
|
||||
- `channels.logout` wylogowuje z określonego kanału/konta, jeśli dany kanał
|
||||
obsługuje wylogowanie.
|
||||
- `web.login.start` uruchamia przepływ logowania QR/web dla bieżącego
|
||||
dostawcy kanału web obsługującego QR.
|
||||
- `web.login.wait` czeka na zakończenie tego przepływu logowania QR/web i przy powodzeniu uruchamia
|
||||
kanał.
|
||||
- `push.test` wysyła testowe powiadomienie APNs do zarejestrowanego węzła iOS.
|
||||
- `web.login.start` uruchamia przepływ logowania QR/web dla bieżącego dostawcy
|
||||
kanału web obsługującego QR.
|
||||
- `web.login.wait` czeka na zakończenie tego przepływu logowania QR/web i po
|
||||
sukcesie uruchamia kanał.
|
||||
- `push.test` wysyła testowe powiadomienie push APNs do zarejestrowanego węzła iOS.
|
||||
- `voicewake.get` zwraca zapisane wyzwalacze słowa aktywującego.
|
||||
- `voicewake.set` aktualizuje wyzwalacze słowa aktywującego i rozgłasza zmianę.
|
||||
|
||||
### Wiadomości i logi
|
||||
|
||||
- `send` jest bezpośrednim wywołaniem RPC dostarczania wychodzącego dla
|
||||
wysyłek kierowanych do kanału/konta/wątku poza runnerem czatu.
|
||||
- `logs.tail` zwraca ogon skonfigurowanego dziennika plikowego gateway z kursorem/limitem oraz
|
||||
kontrolami maksymalnej liczby bajtów.
|
||||
- `send` to bezpośrednia metoda RPC dostarczania wychodzącego dla wysyłek
|
||||
ukierunkowanych na kanał/konto/wątek poza runnerem czatu.
|
||||
- `logs.tail` zwraca końcówkę skonfigurowanego dziennika plikowego bramy z
|
||||
kontrolą kursora/limitu i maksymalnej liczby bajtów.
|
||||
|
||||
### Talk i TTS
|
||||
|
||||
@ -281,64 +289,65 @@ zaimplementowanego w `src/gateway/server-methods/*.ts`.
|
||||
wymaga `operator.talk.secrets` (lub `operator.admin`).
|
||||
- `talk.mode` ustawia/rozgłasza bieżący stan trybu Talk dla klientów
|
||||
WebChat/Control UI.
|
||||
- `talk.speak` syntetyzuje mowę przez aktywnego dostawcę mowy Talk.
|
||||
- `tts.status` zwraca stan włączenia TTS, aktywnego dostawcę, dostawców zapasowych
|
||||
oraz stan konfiguracji dostawcy.
|
||||
- `tts.providers` zwraca widoczny spis dostawców TTS.
|
||||
- `talk.speak` syntezuje mowę przez aktywnego dostawcę mowy Talk.
|
||||
- `tts.status` zwraca stan włączenia TTS, aktywnego dostawcę, dostawców
|
||||
zapasowych i stan konfiguracji dostawcy.
|
||||
- `tts.providers` zwraca widoczny inwentarz dostawców TTS.
|
||||
- `tts.enable` i `tts.disable` przełączają stan preferencji TTS.
|
||||
- `tts.setProvider` aktualizuje preferowanego dostawcę TTS.
|
||||
- `tts.convert` uruchamia jednorazową konwersję tekstu na mowę.
|
||||
|
||||
### Sekrety, konfiguracja, aktualizacja i kreator
|
||||
|
||||
- `secrets.reload` ponownie rozwiązuje aktywne SecretRef i podmienia stan sekretów w czasie działania
|
||||
tylko przy pełnym powodzeniu.
|
||||
- `secrets.resolve` rozwiązuje przypisania sekretów docelowych poleceń dla określonego
|
||||
zestawu poleceń/celów.
|
||||
- `config.get` zwraca bieżący snapshot konfiguracji i hash.
|
||||
- `config.set` zapisuje zwalidowany ładunek konfiguracji.
|
||||
- `secrets.reload` ponownie rozwiązuje aktywne SecretRef i podmienia stan
|
||||
sekretów w czasie działania tylko przy pełnym sukcesie.
|
||||
- `secrets.resolve` rozwiązuje przypisania sekretów docelowych poleceń dla
|
||||
określonego zestawu poleceń/celów.
|
||||
- `config.get` zwraca bieżącą migawkę konfiguracji i hash.
|
||||
- `config.set` zapisuje zweryfikowany ładunek konfiguracji.
|
||||
- `config.patch` scala częściową aktualizację konfiguracji.
|
||||
- `config.apply` waliduje i zastępuje pełny ładunek konfiguracji.
|
||||
- `config.schema` zwraca ładunek aktywnego schematu konfiguracji używany przez Control UI i
|
||||
narzędzia CLI: schemat, `uiHints`, wersję oraz metadane generowania, w tym
|
||||
metadane schematu pluginów + kanałów, gdy środowisko wykonawcze może je załadować. Schemat
|
||||
zawiera metadane pól `title` / `description` pochodzące z tych samych etykiet
|
||||
i tekstów pomocy używanych przez UI, w tym zagnieżdżone obiekty, wildcard, elementy tablic
|
||||
oraz gałęzie kompozycji `anyOf` / `oneOf` / `allOf`, gdy istnieje odpowiadająca
|
||||
dokumentacja pól.
|
||||
- `config.schema.lookup` zwraca ładunek wyszukiwania ograniczony do ścieżki dla jednej ścieżki konfiguracji:
|
||||
znormalizowaną ścieżkę, płytki węzeł schematu, dopasowaną wskazówkę + `hintPath` oraz
|
||||
podsumowania bezpośrednich elementów potomnych do drążenia w UI/CLI.
|
||||
- Węzły schematu wyszukiwania zachowują dokumentację skierowaną do użytkownika i typowe pola walidacji:
|
||||
`title`, `description`, `type`, `enum`, `const`, `format`, `pattern`,
|
||||
ograniczenia liczb/ciągów/tablic/obiektów oraz flagi logiczne takie jak
|
||||
`additionalProperties`, `deprecated`, `readOnly`, `writeOnly`.
|
||||
- Podsumowania elementów potomnych udostępniają `key`, znormalizowaną `path`, `type`, `required`,
|
||||
`hasChildren` oraz dopasowane `hint` / `hintPath`.
|
||||
- `update.run` uruchamia przepływ aktualizacji gateway i planuje restart tylko wtedy,
|
||||
gdy sama aktualizacja się powiodła.
|
||||
- `config.apply` weryfikuje i zastępuje pełny ładunek konfiguracji.
|
||||
- `config.schema` zwraca ładunek aktywnego schematu konfiguracji używany przez
|
||||
Control UI i narzędzia CLI: schemat, `uiHints`, wersję i metadane generowania,
|
||||
w tym metadane schematów pluginów + kanałów, gdy środowisko wykonawcze może je
|
||||
załadować. Schemat zawiera metadane pól `title` / `description` pochodzące z
|
||||
tych samych etykiet i tekstów pomocy używanych przez UI, w tym dla zagnieżdżonych
|
||||
obiektów, wildcard, elementów tablic i gałęzi kompozycji `anyOf` / `oneOf` / `allOf`,
|
||||
gdy istnieje odpowiadająca dokumentacja pola.
|
||||
- `config.schema.lookup` zwraca ładunek wyszukiwania ograniczony do ścieżki dla
|
||||
jednej ścieżki konfiguracji: znormalizowaną ścieżkę, płytki węzeł schematu,
|
||||
dopasowaną wskazówkę + `hintPath` oraz podsumowania bezpośrednich elementów
|
||||
podrzędnych do drążenia w UI/CLI.
|
||||
- Węzły schematu wyszukiwania zachowują dokumentację widoczną dla użytkownika
|
||||
i typowe pola walidacji: `title`, `description`, `type`, `enum`, `const`,
|
||||
`format`, `pattern`, ograniczenia liczbowe/tekstowe/tablicowe/obiektowe oraz
|
||||
flagi logiczne, takie jak `additionalProperties`, `deprecated`, `readOnly`,
|
||||
`writeOnly`.
|
||||
- Podsumowania elementów podrzędnych udostępniają `key`, znormalizowaną `path`,
|
||||
`type`, `required`, `hasChildren`, a także dopasowane `hint` / `hintPath`.
|
||||
- `update.run` uruchamia przepływ aktualizacji bramy i planuje restart tylko
|
||||
wtedy, gdy sama aktualizacja zakończyła się sukcesem.
|
||||
- `wizard.start`, `wizard.next`, `wizard.status` i `wizard.cancel` udostępniają
|
||||
kreator wdrożenia przez WS RPC.
|
||||
kreator onboardingu przez WS RPC.
|
||||
|
||||
### Istniejące główne rodziny
|
||||
|
||||
#### Pomocniki agenta i obszaru roboczego
|
||||
#### Helpery agentów i workspace
|
||||
|
||||
- `agents.list` zwraca skonfigurowane wpisy agentów.
|
||||
- `agents.create`, `agents.update` i `agents.delete` zarządzają rekordami agentów oraz
|
||||
powiązaniami obszaru roboczego.
|
||||
- `agents.create`, `agents.update` i `agents.delete` zarządzają rekordami
|
||||
agentów i okablowaniem workspace.
|
||||
- `agents.files.list`, `agents.files.get` i `agents.files.set` zarządzają
|
||||
plikami obszaru roboczego bootstrap udostępnianymi dla agenta.
|
||||
- `agent.identity.get` zwraca efektywną tożsamość asystenta dla agenta lub
|
||||
sesji.
|
||||
- `agent.wait` czeka na zakończenie uruchomienia i zwraca końcowy snapshot, gdy
|
||||
jest dostępny.
|
||||
plikami bootstrap workspace udostępnianymi dla agenta.
|
||||
- `agent.identity.get` zwraca efektywną tożsamość asystenta dla agenta lub sesji.
|
||||
- `agent.wait` czeka na zakończenie uruchomienia i zwraca terminalną migawkę,
|
||||
jeśli jest dostępna.
|
||||
|
||||
#### Sterowanie sesją
|
||||
|
||||
- `sessions.list` zwraca bieżący indeks sesji.
|
||||
- `sessions.subscribe` i `sessions.unsubscribe` przełączają subskrypcje zdarzeń zmian sesji
|
||||
dla bieżącego klienta WS.
|
||||
- `sessions.subscribe` i `sessions.unsubscribe` przełączają subskrypcje zdarzeń
|
||||
zmian sesji dla bieżącego klienta WS.
|
||||
- `sessions.messages.subscribe` i `sessions.messages.unsubscribe` przełączają
|
||||
subskrypcje zdarzeń transkryptu/wiadomości dla jednej sesji.
|
||||
- `sessions.preview` zwraca ograniczone podglądy transkryptu dla określonych
|
||||
@ -346,147 +355,174 @@ zaimplementowanego w `src/gateway/server-methods/*.ts`.
|
||||
- `sessions.resolve` rozwiązuje lub kanonizuje cel sesji.
|
||||
- `sessions.create` tworzy nowy wpis sesji.
|
||||
- `sessions.send` wysyła wiadomość do istniejącej sesji.
|
||||
- `sessions.steer` jest wariantem przerwania i sterowania dla aktywnej sesji.
|
||||
- `sessions.steer` to wariant przerwania i sterowania dla aktywnej sesji.
|
||||
- `sessions.abort` przerywa aktywną pracę dla sesji.
|
||||
- `sessions.patch` aktualizuje metadane/nadpisania sesji.
|
||||
- `sessions.reset`, `sessions.delete` i `sessions.compact` wykonują
|
||||
konserwację sesji.
|
||||
- `sessions.reset`, `sessions.delete` i `sessions.compact` wykonują działania
|
||||
konserwacyjne na sesji.
|
||||
- `sessions.get` zwraca pełny zapisany wiersz sesji.
|
||||
- wykonywanie czatu nadal używa `chat.history`, `chat.send`, `chat.abort` i
|
||||
- wykonanie czatu nadal używa `chat.history`, `chat.send`, `chat.abort` i
|
||||
`chat.inject`.
|
||||
- `chat.history` jest znormalizowane pod kątem wyświetlania dla klientów UI: wbudowane tagi dyrektyw są
|
||||
usuwane z widocznego tekstu, ładunki XML wywołań narzędzi w zwykłym tekście (w tym
|
||||
- `chat.history` jest znormalizowane do wyświetlania dla klientów UI:
|
||||
znaczniki dyrektyw inline są usuwane z widocznego tekstu, ładunki XML wywołań
|
||||
narzędzi w zwykłym tekście (w tym
|
||||
`<tool_call>...</tool_call>`, `<function_call>...</function_call>`,
|
||||
`<tool_calls>...</tool_calls>`, `<function_calls>...</function_calls>` oraz
|
||||
obcięte bloki wywołań narzędzi) i wyciekłe tokeny sterowania modelem ASCII/full-width
|
||||
są usuwane, czyste wiersze asystenta z cichymi tokenami, takie jak dokładne `NO_REPLY` /
|
||||
`no_reply`, są pomijane, a zbyt duże wiersze mogą zostać zastąpione placeholderami.
|
||||
obcięte bloki wywołań narzędzi) i wyciekłe tokeny sterujące modelu w ASCII/pełnej
|
||||
szerokości są usuwane, czyste wiersze asystenta zawierające wyłącznie ciche tokeny,
|
||||
takie jak dokładne `NO_REPLY` / `no_reply`, są pomijane, a zbyt duże wiersze mogą
|
||||
być zastępowane placeholderami.
|
||||
|
||||
#### Parowanie urządzeń i tokeny urządzeń
|
||||
|
||||
- `device.pair.list` zwraca oczekujące i zatwierdzone sparowane urządzenia.
|
||||
- `device.pair.approve`, `device.pair.reject` i `device.pair.remove` zarządzają
|
||||
rekordami parowania urządzeń.
|
||||
- `device.token.rotate` obraca token sparowanego urządzenia w granicach zatwierdzonej roli
|
||||
i zakresów.
|
||||
- `device.token.rotate` obraca token sparowanego urządzenia w granicach jego
|
||||
zatwierdzonej roli i zakresów.
|
||||
- `device.token.revoke` unieważnia token sparowanego urządzenia.
|
||||
|
||||
#### Parowanie węzłów, invoke i oczekująca praca
|
||||
|
||||
- `node.pair.request`, `node.pair.list`, `node.pair.approve`,
|
||||
`node.pair.reject` i `node.pair.verify` obejmują parowanie węzłów i bootstrap
|
||||
verification.
|
||||
- `node.list` i `node.describe` zwracają stan znanych/połączonych węzłów.
|
||||
`node.pair.reject` i `node.pair.verify` obejmują parowanie węzłów i
|
||||
weryfikację bootstrapu.
|
||||
- `node.list` i `node.describe` zwracają stan znanych/podłączonych węzłów.
|
||||
- `node.rename` aktualizuje etykietę sparowanego węzła.
|
||||
- `node.invoke` przekazuje polecenie do połączonego węzła.
|
||||
- `node.invoke.result` zwraca wynik żądania invoke.
|
||||
- `node.event` przenosi zdarzenia pochodzące z węzła z powrotem do gateway.
|
||||
- `node.invoke` przekazuje polecenie do podłączonego węzła.
|
||||
- `node.invoke.result` zwraca wynik dla żądania invoke.
|
||||
- `node.event` przenosi zdarzenia pochodzące z węzła z powrotem do bramy.
|
||||
- `node.canvas.capability.refresh` odświeża ograniczone tokeny możliwości canvas.
|
||||
- `node.pending.pull` i `node.pending.ack` to interfejsy API kolejki połączonych węzłów.
|
||||
- `node.pending.enqueue` i `node.pending.drain` zarządzają trwałą oczekującą pracą
|
||||
dla węzłów offline/rozłączonych.
|
||||
- `node.pending.pull` i `node.pending.ack` to API kolejki podłączonych węzłów.
|
||||
- `node.pending.enqueue` i `node.pending.drain` zarządzają trwałą oczekującą
|
||||
pracą dla węzłów offline/rozłączonych.
|
||||
|
||||
#### Rodziny zatwierdzeń
|
||||
|
||||
- `exec.approval.request`, `exec.approval.get`, `exec.approval.list` i
|
||||
`exec.approval.resolve` obejmują jednorazowe żądania zatwierdzenia exec oraz oczekujące
|
||||
wyszukiwanie/odtwarzanie zatwierdzeń.
|
||||
- `exec.approval.waitDecision` czeka na jedno oczekujące zatwierdzenie exec i zwraca
|
||||
ostateczną decyzję (lub `null` przy przekroczeniu czasu).
|
||||
- `exec.approvals.get` i `exec.approvals.set` zarządzają snapshotami polityki zatwierdzeń exec
|
||||
gateway.
|
||||
- `exec.approvals.node.get` i `exec.approvals.node.set` zarządzają lokalną dla węzła
|
||||
polityką zatwierdzeń exec przez polecenia relay węzła.
|
||||
`exec.approval.resolve` obejmują jednorazowe żądania zatwierdzenia exec oraz
|
||||
wyszukiwanie/odtwarzanie oczekujących zatwierdzeń.
|
||||
- `exec.approval.waitDecision` czeka na jedną oczekującą decyzję zatwierdzenia
|
||||
exec i zwraca ostateczną decyzję (lub `null` przy przekroczeniu limitu czasu).
|
||||
- `exec.approvals.get` i `exec.approvals.set` zarządzają migawkami polityki
|
||||
zatwierdzeń exec bramy.
|
||||
- `exec.approvals.node.get` i `exec.approvals.node.set` zarządzają lokalną dla
|
||||
węzła polityką zatwierdzeń exec za pośrednictwem poleceń relay węzła.
|
||||
- `plugin.approval.request`, `plugin.approval.list`,
|
||||
`plugin.approval.waitDecision` i `plugin.approval.resolve` obejmują
|
||||
przepływy zatwierdzeń definiowane przez pluginy.
|
||||
`plugin.approval.waitDecision` i `plugin.approval.resolve` obejmują przepływy
|
||||
zatwierdzeń zdefiniowane przez pluginy.
|
||||
|
||||
#### Inne główne rodziny
|
||||
|
||||
- automatyzacja:
|
||||
- `wake` planuje natychmiastowe lub przy następnym heartbeat wstrzyknięcie tekstu wybudzającego
|
||||
- `wake` planuje natychmiastowe lub przy następnym heartbeat wstrzyknięcie tekstu budzenia
|
||||
- `cron.list`, `cron.status`, `cron.add`, `cron.update`, `cron.remove`,
|
||||
`cron.run`, `cron.runs`
|
||||
- skills/tools: `skills.*`, `tools.catalog`, `tools.effective`
|
||||
- Skills/narzędzia: `commands.list`, `skills.*`, `tools.catalog`, `tools.effective`
|
||||
|
||||
### Typowe rodziny zdarzeń
|
||||
|
||||
- `chat`: aktualizacje czatu UI, takie jak `chat.inject` i inne zdarzenia czatu
|
||||
tylko dla transkryptu.
|
||||
- `session.message` i `session.tool`: aktualizacje transkryptu/strumienia zdarzeń dla
|
||||
subskrybowanej sesji.
|
||||
- `sessions.changed`: zmienił się indeks sesji lub metadane.
|
||||
- `presence`: aktualizacje snapshotu obecności systemu.
|
||||
- `tick`: okresowe zdarzenie keepalive / żywotności.
|
||||
- `health`: aktualizacja snapshotu kondycji gateway.
|
||||
dotyczące wyłącznie transkryptu.
|
||||
- `session.message` i `session.tool`: aktualizacje transkryptu/strumienia
|
||||
zdarzeń dla subskrybowanej sesji.
|
||||
- `sessions.changed`: indeks sesji lub metadane uległy zmianie.
|
||||
- `presence`: aktualizacje migawki obecności systemu.
|
||||
- `tick`: okresowe zdarzenie keepalive / liveness.
|
||||
- `health`: aktualizacja migawki stanu zdrowia bramy.
|
||||
- `heartbeat`: aktualizacja strumienia zdarzeń heartbeat.
|
||||
- `cron`: zdarzenie zmiany uruchomienia/zadania cron.
|
||||
- `shutdown`: powiadomienie o wyłączeniu gateway.
|
||||
- `node.pair.requested` / `node.pair.resolved`: cykl życia parowania węzłów.
|
||||
- `shutdown`: powiadomienie o zamknięciu bramy.
|
||||
- `node.pair.requested` / `node.pair.resolved`: cykl życia parowania węzła.
|
||||
- `node.invoke.request`: rozgłoszenie żądania invoke węzła.
|
||||
- `device.pair.requested` / `device.pair.resolved`: cykl życia sparowanych urządzeń.
|
||||
- `voicewake.changed`: zmieniła się konfiguracja wyzwalacza słowa aktywującego.
|
||||
- `exec.approval.requested` / `exec.approval.resolved`: cykl życia zatwierdzeń exec.
|
||||
- `plugin.approval.requested` / `plugin.approval.resolved`: cykl życia zatwierdzeń pluginów.
|
||||
- `device.pair.requested` / `device.pair.resolved`: cykl życia sparowanego urządzenia.
|
||||
- `voicewake.changed`: konfiguracja wyzwalaczy słowa aktywującego uległa zmianie.
|
||||
- `exec.approval.requested` / `exec.approval.resolved`: cykl życia
|
||||
zatwierdzenia exec.
|
||||
- `plugin.approval.requested` / `plugin.approval.resolved`: cykl życia
|
||||
zatwierdzenia pluginu.
|
||||
|
||||
### Metody pomocnicze węzłów
|
||||
### Metody pomocnicze węzła
|
||||
|
||||
- Węzły mogą wywoływać `skills.bins`, aby pobrać bieżącą listę plików wykonywalnych skill
|
||||
na potrzeby automatycznych kontroli listy dozwolonych.
|
||||
- Węzły mogą wywoływać `skills.bins`, aby pobrać bieżącą listę plików
|
||||
wykonywalnych Skills do automatycznych kontroli listy dozwolonych.
|
||||
|
||||
### Metody pomocnicze operatora
|
||||
|
||||
- Operatorzy mogą wywoływać `tools.catalog` (`operator.read`), aby pobrać katalog narzędzi środowiska wykonawczego dla
|
||||
agenta. Odpowiedź zawiera pogrupowane narzędzia i metadane pochodzenia:
|
||||
- Operatorzy mogą wywoływać `commands.list` (`operator.read`), aby pobrać
|
||||
inwentarz poleceń środowiska wykonawczego dla agenta.
|
||||
- `agentId` jest opcjonalne; pomiń je, aby odczytać domyślny workspace agenta.
|
||||
- `scope` określa, którą powierzchnię celuje podstawowa `name`:
|
||||
- `text` zwraca podstawowy tekstowy token polecenia bez wiodącego `/`
|
||||
- `native` oraz domyślna ścieżka `both` zwracają nazwy natywne zależne od
|
||||
dostawcy, gdy są dostępne
|
||||
- `textAliases` zawiera dokładne aliasy slash, takie jak `/model` i `/m`.
|
||||
- `nativeName` zawiera natywną nazwę zależną od dostawcy, gdy taka istnieje.
|
||||
- `provider` jest opcjonalne i wpływa tylko na nazewnictwo natywne oraz
|
||||
dostępność natywnych poleceń pluginów.
|
||||
- `includeArgs=false` pomija zserializowane metadane argumentów w odpowiedzi.
|
||||
- Operatorzy mogą wywoływać `tools.catalog` (`operator.read`), aby pobrać
|
||||
katalog narzędzi środowiska wykonawczego dla agenta. Odpowiedź zawiera
|
||||
pogrupowane narzędzia i metadane pochodzenia:
|
||||
- `source`: `core` lub `plugin`
|
||||
- `pluginId`: właściciel pluginu, gdy `source="plugin"`
|
||||
- `optional`: czy narzędzie pluginu jest opcjonalne
|
||||
- Operatorzy mogą wywoływać `tools.effective` (`operator.read`), aby pobrać efektywny w czasie działania
|
||||
spis narzędzi dla sesji.
|
||||
- Operatorzy mogą wywoływać `tools.effective` (`operator.read`), aby pobrać
|
||||
efektywny inwentarz narzędzi środowiska wykonawczego dla sesji.
|
||||
- `sessionKey` jest wymagane.
|
||||
- Gateway wyprowadza zaufany kontekst środowiska wykonawczego po stronie serwera z sesji zamiast akceptować
|
||||
kontekst uwierzytelniania lub dostarczenia dostarczony przez wywołującego.
|
||||
- Odpowiedź jest ograniczona do sesji i odzwierciedla to, czego aktywna rozmowa może użyć w danej chwili,
|
||||
w tym narzędzia rdzenia, pluginów i kanałów.
|
||||
- Operatorzy mogą wywoływać `skills.status` (`operator.read`), aby pobrać widoczny
|
||||
spis skills dla agenta.
|
||||
- `agentId` jest opcjonalne; pomiń je, aby odczytać domyślny obszar roboczy agenta.
|
||||
- Odpowiedź zawiera kwalifikowalność, brakujące wymagania, kontrole konfiguracji oraz
|
||||
zsanityzowane opcje instalacji bez ujawniania surowych wartości sekretów.
|
||||
- Operatorzy mogą wywoływać `skills.search` i `skills.detail` (`operator.read`) dla
|
||||
metadanych wykrywania ClawHub.
|
||||
- Brama wyprowadza zaufany kontekst środowiska wykonawczego po stronie serwera
|
||||
z sesji zamiast akceptować kontekst uwierzytelniania lub dostarczenia
|
||||
dostarczony przez wywołującego.
|
||||
- Odpowiedź jest ograniczona do sesji i odzwierciedla to, z czego aktywna
|
||||
konwersacja może korzystać w danej chwili, w tym z narzędzi rdzenia,
|
||||
pluginów i kanałów.
|
||||
- Operatorzy mogą wywoływać `skills.status` (`operator.read`), aby pobrać
|
||||
widoczny inwentarz Skills dla agenta.
|
||||
- `agentId` jest opcjonalne; pomiń je, aby odczytać domyślny workspace agenta.
|
||||
- Odpowiedź zawiera kwalifikowalność, brakujące wymagania, kontrole
|
||||
konfiguracji oraz oczyszczone opcje instalacji bez ujawniania surowych
|
||||
wartości sekretów.
|
||||
- Operatorzy mogą wywoływać `skills.search` i `skills.detail`
|
||||
(`operator.read`) dla metadanych wykrywania ClawHub.
|
||||
- Operatorzy mogą wywoływać `skills.install` (`operator.admin`) w dwóch trybach:
|
||||
- Tryb ClawHub: `{ source: "clawhub", slug, version?, force? }` instaluje
|
||||
folder skill w katalogu `skills/` domyślnego obszaru roboczego agenta.
|
||||
- Tryb instalatora Gateway: `{ name, installId, dangerouslyForceUnsafeInstall?, timeoutMs? }`
|
||||
uruchamia zadeklarowaną akcję `metadata.openclaw.install` na hoście gateway.
|
||||
- tryb ClawHub: `{ source: "clawhub", slug, version?, force? }` instaluje
|
||||
folder skill do katalogu `skills/` domyślnego workspace agenta.
|
||||
- tryb instalatora bramy: `{ name, installId, dangerouslyForceUnsafeInstall?, timeoutMs? }`
|
||||
uruchamia zadeklarowane działanie `metadata.openclaw.install` na hoście bramy.
|
||||
- Operatorzy mogą wywoływać `skills.update` (`operator.admin`) w dwóch trybach:
|
||||
- Tryb ClawHub aktualizuje jeden śledzony slug lub wszystkie śledzone instalacje ClawHub w
|
||||
domyślnym obszarze roboczym agenta.
|
||||
- Tryb konfiguracji łata wartości `skills.entries.<skillKey>`, takie jak `enabled`,
|
||||
`apiKey` i `env`.
|
||||
- tryb ClawHub aktualizuje jeden śledzony slug lub wszystkie śledzone
|
||||
instalacje ClawHub w domyślnym workspace agenta.
|
||||
- tryb konfiguracji modyfikuje wartości `skills.entries.<skillKey>`, takie jak
|
||||
`enabled`, `apiKey` i `env`.
|
||||
|
||||
## Zatwierdzenia exec
|
||||
|
||||
- Gdy żądanie exec wymaga zatwierdzenia, gateway rozgłasza `exec.approval.requested`.
|
||||
- Klienci operatora rozwiązują je przez wywołanie `exec.approval.resolve` (wymaga zakresu `operator.approvals`).
|
||||
- Dla `host=node`, `exec.approval.request` musi zawierać `systemRunPlan` (kanoniczne `argv`/`cwd`/`rawCommand`/metadane sesji). Żądania bez `systemRunPlan` są odrzucane.
|
||||
- Po zatwierdzeniu przekazane wywołania `node.invoke system.run` ponownie używają tego kanonicznego
|
||||
`systemRunPlan` jako autorytatywnego kontekstu polecenia/cwd/sesji.
|
||||
- Gdy żądanie exec wymaga zatwierdzenia, brama rozgłasza `exec.approval.requested`.
|
||||
- Klienci operatora rozwiązują je przez wywołanie `exec.approval.resolve`
|
||||
(wymaga zakresu `operator.approvals`).
|
||||
- Dla `host=node`, `exec.approval.request` musi zawierać `systemRunPlan`
|
||||
(kanoniczne `argv`/`cwd`/`rawCommand`/metadane sesji). Żądania bez
|
||||
`systemRunPlan` są odrzucane.
|
||||
- Po zatwierdzeniu przekazane dalej wywołania `node.invoke system.run` ponownie
|
||||
używają tego kanonicznego `systemRunPlan` jako autorytatywnego kontekstu
|
||||
polecenia/cwd/sesji.
|
||||
- Jeśli wywołujący zmieni `command`, `rawCommand`, `cwd`, `agentId` lub
|
||||
`sessionKey` między prepare a końcowym zatwierdzonym przekazaniem `system.run`,
|
||||
gateway odrzuci uruchomienie zamiast ufać zmodyfikowanemu ładunkowi.
|
||||
brama odrzuci uruchomienie zamiast ufać zmodyfikowanemu ładunkowi.
|
||||
|
||||
## Zapasowe dostarczanie agenta
|
||||
## Fallback dostarczania agenta
|
||||
|
||||
- Żądania `agent` mogą zawierać `deliver=true`, aby zażądać dostarczenia wychodzącego.
|
||||
- `bestEffortDeliver=false` zachowuje rygorystyczne działanie: nierozwiązane lub wyłącznie wewnętrzne cele dostarczenia zwracają `INVALID_REQUEST`.
|
||||
- `bestEffortDeliver=true` umożliwia przejście awaryjne do wykonania tylko w sesji, gdy nie można rozwiązać żadnej zewnętrznej trasy dostarczenia (na przykład sesje internal/webchat lub niejednoznaczne konfiguracje wielu kanałów).
|
||||
- `bestEffortDeliver=false` zachowuje ścisłe działanie: nierozwiązane lub
|
||||
wyłącznie wewnętrzne cele dostarczania zwracają `INVALID_REQUEST`.
|
||||
- `bestEffortDeliver=true` pozwala na fallback do wykonania tylko w sesji, gdy
|
||||
nie można rozwiązać zewnętrznej trasy dostarczania (na przykład sesje
|
||||
internal/webchat lub niejednoznaczne konfiguracje wielokanałowe).
|
||||
|
||||
## Wersjonowanie
|
||||
|
||||
- `PROTOCOL_VERSION` znajduje się w `src/gateway/protocol/schema.ts`.
|
||||
- Klienci wysyłają `minProtocol` + `maxProtocol`; serwer odrzuca niedopasowania.
|
||||
- Klienci wysyłają `minProtocol` + `maxProtocol`; serwer odrzuca niezgodności.
|
||||
- Schematy + modele są generowane z definicji TypeBox:
|
||||
- `pnpm protocol:gen`
|
||||
- `pnpm protocol:gen:swift`
|
||||
@ -494,99 +530,115 @@ zaimplementowanego w `src/gateway/server-methods/*.ts`.
|
||||
|
||||
## Uwierzytelnianie
|
||||
|
||||
- Uwierzytelnianie gateway współdzielonym sekretem używa `connect.params.auth.token` lub
|
||||
`connect.params.auth.password`, zależnie od skonfigurowanego trybu uwierzytelniania.
|
||||
- Tryby niosące tożsamość, takie jak Tailscale Serve
|
||||
(`gateway.auth.allowTailscale: true`) lub `gateway.auth.mode: "trusted-proxy"` inne niż
|
||||
local loopback, spełniają kontrolę uwierzytelniania connect na podstawie
|
||||
- Uwierzytelnianie bramy za pomocą wspólnego sekretu używa
|
||||
`connect.params.auth.token` lub `connect.params.auth.password`, zależnie od
|
||||
skonfigurowanego trybu uwierzytelniania.
|
||||
- Tryby przenoszące tożsamość, takie jak Tailscale Serve
|
||||
(`gateway.auth.allowTailscale: true`) lub `gateway.auth.mode: "trusted-proxy"`
|
||||
poza loopback, spełniają kontrolę uwierzytelniania połączenia na podstawie
|
||||
nagłówków żądania zamiast `connect.params.auth.*`.
|
||||
- Prywatny ingress `gateway.auth.mode: "none"` całkowicie pomija uwierzytelnianie connect współdzielonym sekretem; nie wystawiaj tego trybu na publiczny/niezaufany ingress.
|
||||
- Po sparowaniu Gateway wydaje **token urządzenia** ograniczony do roli + zakresów połączenia.
|
||||
Jest on zwracany w `hello-ok.auth.deviceToken` i powinien być
|
||||
utrwalony przez klienta na potrzeby przyszłych połączeń.
|
||||
- Klienci powinni utrwalać podstawowy `hello-ok.auth.deviceToken` po każdym
|
||||
- Prywatny ingress z `gateway.auth.mode: "none"` całkowicie pomija
|
||||
uwierzytelnianie połączenia wspólnym sekretem; nie wystawiaj tego trybu na
|
||||
publiczny/niezaufany ingress.
|
||||
- Po sparowaniu brama wydaje **token urządzenia** ograniczony do roli +
|
||||
zakresów połączenia. Jest on zwracany w `hello-ok.auth.deviceToken` i klient
|
||||
powinien zapisać go na potrzeby przyszłych połączeń.
|
||||
- Klienci powinni zapisywać podstawowy `hello-ok.auth.deviceToken` po każdym
|
||||
udanym połączeniu.
|
||||
- Ponowne łączenie z tym **zapisanym** tokenem urządzenia powinno także ponownie używać zapisanego
|
||||
zatwierdzonego zestawu zakresów dla tego tokenu. Pozwala to zachować już przyznany
|
||||
dostęp do odczytu/sprawdzeń/statusu i unika cichego zawężenia ponownych połączeń do
|
||||
węższego, domyślnego zakresu tylko admin.
|
||||
- Zwykła kolejność pierwszeństwa uwierzytelniania connect to najpierw jawny współdzielony token/hasło, potem
|
||||
jawny `deviceToken`, potem zapisany token per urządzenie, a następnie token bootstrap.
|
||||
- Ponowne połączenie z użyciem tego **zapisanego** tokenu urządzenia powinno
|
||||
również ponownie używać zapisanego zatwierdzonego zestawu zakresów dla tego
|
||||
tokenu. Zachowuje to wcześniej przyznany dostęp do odczytu/probe/status i
|
||||
zapobiega cichemu zawężeniu ponownych połączeń do węższego domyślnego zakresu
|
||||
tylko dla administratora.
|
||||
- Normalna kolejność pierwszeństwa uwierzytelniania połączenia to najpierw
|
||||
jawny współdzielony token/hasło, potem jawny `deviceToken`, następnie
|
||||
zapisany token per urządzenie, a na końcu token bootstrap.
|
||||
- Dodatkowe wpisy `hello-ok.auth.deviceTokens` to tokeny przekazania bootstrap.
|
||||
Utrwalaj je tylko wtedy, gdy połączenie użyło uwierzytelniania bootstrap na zaufanym transporcie,
|
||||
takim jak `wss://` lub loopback/local pairing.
|
||||
- Jeśli klient dostarczy **jawny** `deviceToken` lub jawne `scopes`, ten
|
||||
żądany przez wywołującego zestaw zakresów pozostaje autorytatywny; zakresy z pamięci podręcznej są ponownie używane tylko wtedy, gdy klient ponownie używa zapisanego tokenu per urządzenie.
|
||||
Zapisuj je tylko wtedy, gdy połączenie używało uwierzytelniania bootstrap na
|
||||
zaufanym transporcie, takim jak `wss://` lub loopback/lokalne parowanie.
|
||||
- Jeśli klient poda **jawny** `deviceToken` lub jawne `scopes`, żądany przez
|
||||
wywołującego zestaw zakresów pozostaje autorytatywny; zakresy z pamięci
|
||||
podręcznej są używane ponownie tylko wtedy, gdy klient ponownie używa
|
||||
zapisanego tokenu per urządzenie.
|
||||
- Tokeny urządzeń można obracać/unieważniać przez `device.token.rotate` i
|
||||
`device.token.revoke` (wymaga zakresu `operator.pairing`).
|
||||
- Wydawanie/obracanie tokenów pozostaje ograniczone do zatwierdzonego zestawu ról zapisanych w
|
||||
wpisie parowania tego urządzenia; obrót tokenu nie może rozszerzyć urządzenia do
|
||||
roli, której zatwierdzenie parowania nigdy nie nadało.
|
||||
- Dla sesji tokenów sparowanych urządzeń zarządzanie urządzeniem jest ograniczone do własnego zakresu, chyba że
|
||||
wywołujący ma także `operator.admin`: użytkownicy bez admina mogą usuwać/unieważniać/obracać
|
||||
tylko **własny** wpis urządzenia.
|
||||
- Wydawanie/obracanie tokenów pozostaje ograniczone do zatwierdzonego zestawu
|
||||
ról zapisanego w wpisie parowania tego urządzenia; obrót tokenu nie może
|
||||
rozszerzyć urządzenia do roli, której zatwierdzenie parowania nigdy nie nadało.
|
||||
- Dla sesji tokenów sparowanych urządzeń zarządzanie urządzeniami jest
|
||||
ograniczone do własnego zakresu, chyba że wywołujący ma także
|
||||
`operator.admin`: użytkownicy bez uprawnień administratora mogą
|
||||
usuwać/unieważniać/obracać tylko **własny** wpis urządzenia.
|
||||
- `device.token.rotate` sprawdza także żądany zestaw zakresów operatora względem
|
||||
bieżących zakresów sesji wywołującego. Użytkownicy bez admina nie mogą obracać tokenu do
|
||||
szerszego zestawu zakresów operatora, niż już posiadają.
|
||||
- Niepowodzenia uwierzytelniania zawierają `error.details.code` oraz wskazówki odzyskiwania:
|
||||
bieżących zakresów sesji wywołującego. Użytkownicy bez uprawnień administratora
|
||||
nie mogą obrócić tokenu do szerszego zestawu zakresów operatora, niż już posiadają.
|
||||
- Błędy uwierzytelniania zawierają `error.details.code` oraz wskazówki odzyskiwania:
|
||||
- `error.details.canRetryWithDeviceToken` (boolean)
|
||||
- `error.details.recommendedNextStep` (`retry_with_device_token`, `update_auth_configuration`, `update_auth_credentials`, `wait_then_retry`, `review_auth_configuration`)
|
||||
- Zachowanie klienta dla `AUTH_TOKEN_MISMATCH`:
|
||||
- Zaufani klienci mogą podjąć jedną ograniczoną próbę ponowienia z tokenem per urządzenie z pamięci podręcznej.
|
||||
- Jeśli to ponowienie się nie powiedzie, klienci powinni zatrzymać automatyczne pętle ponownego łączenia i wyświetlić operatorowi wskazówki dotyczące działania.
|
||||
- Zaufani klienci mogą podjąć jedną ograniczoną próbę ponownego połączenia z
|
||||
użyciem tokenu per urządzenie z pamięci podręcznej.
|
||||
- Jeśli ta próba się nie powiedzie, klienci powinni zatrzymać automatyczne
|
||||
pętle ponownego łączenia i pokazać operatorowi wskazówki dotyczące dalszych działań.
|
||||
|
||||
## Tożsamość urządzenia + parowanie
|
||||
|
||||
- Węzły powinny zawierać stabilną tożsamość urządzenia (`device.id`) wyprowadzoną z
|
||||
odcisku palca pary kluczy.
|
||||
- Gateway wydaje tokeny dla każdego urządzenia + roli.
|
||||
- Zatwierdzenia parowania są wymagane dla nowych identyfikatorów urządzeń, chyba że włączono
|
||||
lokalne automatyczne zatwierdzanie.
|
||||
- Automatyczne zatwierdzanie parowania jest skoncentrowane na bezpośrednich lokalnych połączeniach local loopback.
|
||||
- OpenClaw ma także wąską ścieżkę samopołączenia backend/kontener-local dla
|
||||
zaufanych przepływów pomocniczych ze współdzielonym sekretem.
|
||||
- Połączenia tailnet lub LAN z tego samego hosta są nadal traktowane jako zdalne na potrzeby parowania i
|
||||
wymagają zatwierdzenia.
|
||||
- Wszyscy klienci WS muszą dołączać tożsamość `device` podczas `connect` (operator + node).
|
||||
- Węzły powinny dołączać stabilną tożsamość urządzenia (`device.id`) wyprowadzoną
|
||||
z odcisku palca pary kluczy.
|
||||
- Bramy wydają tokeny dla każdego urządzenia + roli.
|
||||
- Zatwierdzenia parowania są wymagane dla nowych identyfikatorów urządzeń,
|
||||
chyba że włączono lokalne automatyczne zatwierdzanie.
|
||||
- Automatyczne zatwierdzanie parowania jest skoncentrowane na bezpośrednich
|
||||
lokalnych połączeniach loopback.
|
||||
- OpenClaw ma także wąską ścieżkę samopołączenia backend/container-local dla
|
||||
zaufanych przepływów pomocniczych ze wspólnym sekretem.
|
||||
- Połączenia tailnet lub LAN z tego samego hosta są nadal traktowane jako zdalne
|
||||
na potrzeby parowania i wymagają zatwierdzenia.
|
||||
- Wszyscy klienci WS muszą dołączać tożsamość `device` podczas `connect`
|
||||
(`operator` + `node`).
|
||||
Control UI może ją pominąć tylko w tych trybach:
|
||||
- `gateway.controlUi.allowInsecureAuth=true` dla zgodności z niezabezpieczonym HTTP tylko na localhost.
|
||||
- udane uwierzytelnianie operatora Control UI z `gateway.auth.mode: "trusted-proxy"`.
|
||||
- `gateway.controlUi.allowInsecureAuth=true` dla zgodności z niezabezpieczonym HTTP tylko dla localhost.
|
||||
- pomyślne uwierzytelnienie operatora Control UI przy `gateway.auth.mode: "trusted-proxy"`.
|
||||
- `gateway.controlUi.dangerouslyDisableDeviceAuth=true` (tryb awaryjny, poważne obniżenie bezpieczeństwa).
|
||||
- Wszystkie połączenia muszą podpisywać nonce dostarczone przez serwer w `connect.challenge`.
|
||||
- Wszystkie połączenia muszą podpisywać `connect.challenge` nonce dostarczony przez serwer.
|
||||
|
||||
### Diagnostyka migracji uwierzytelniania urządzenia
|
||||
### Diagnostyka migracji uwierzytelniania urządzeń
|
||||
|
||||
Dla starszych klientów, którzy nadal używają zachowania podpisywania sprzed wyzwania, `connect` teraz zwraca
|
||||
kody szczegółów `DEVICE_AUTH_*` pod `error.details.code` ze stabilnym `error.details.reason`.
|
||||
Dla starszych klientów, które nadal używają zachowania podpisywania sprzed
|
||||
wprowadzenia challenge, `connect` zwraca teraz kody szczegółów `DEVICE_AUTH_*`
|
||||
w `error.details.code` wraz ze stabilnym `error.details.reason`.
|
||||
|
||||
Typowe niepowodzenia migracji:
|
||||
Typowe błędy migracji:
|
||||
|
||||
| Komunikat | details.code | details.reason | Znaczenie |
|
||||
| --------------------------- | -------------------------------- | ------------------------ | -------------------------------------------------- |
|
||||
| `device nonce required` | `DEVICE_AUTH_NONCE_REQUIRED` | `device-nonce-missing` | Klient pominął `device.nonce` (lub wysłał pusty). |
|
||||
| `device nonce mismatch` | `DEVICE_AUTH_NONCE_MISMATCH` | `device-nonce-mismatch` | Klient podpisał starym/błędnym nonce. |
|
||||
| `device signature invalid` | `DEVICE_AUTH_SIGNATURE_INVALID` | `device-signature` | Ładunek podpisu nie pasuje do ładunku v2. |
|
||||
| `device nonce required` | `DEVICE_AUTH_NONCE_REQUIRED` | `device-nonce-missing` | Klient pominął `device.nonce` (lub wysłał pustą wartość). |
|
||||
| `device nonce mismatch` | `DEVICE_AUTH_NONCE_MISMATCH` | `device-nonce-mismatch` | Klient podpisał dane nieaktualnym/błędnym nonce. |
|
||||
| `device signature invalid` | `DEVICE_AUTH_SIGNATURE_INVALID` | `device-signature` | Ładunek podpisu nie odpowiada ładunkowi v2. |
|
||||
| `device signature expired` | `DEVICE_AUTH_SIGNATURE_EXPIRED` | `device-signature-stale` | Podpisany znacznik czasu jest poza dozwolonym odchyleniem. |
|
||||
| `device identity mismatch` | `DEVICE_AUTH_DEVICE_ID_MISMATCH` | `device-id-mismatch` | `device.id` nie pasuje do odcisku palca klucza publicznego. |
|
||||
| `device public key invalid` | `DEVICE_AUTH_PUBLIC_KEY_INVALID` | `device-public-key` | Format/kanonikalizacja klucza publicznego nie powiodły się. |
|
||||
| `device identity mismatch` | `DEVICE_AUTH_DEVICE_ID_MISMATCH` | `device-id-mismatch` | `device.id` nie odpowiada odciskowi palca klucza publicznego. |
|
||||
| `device public key invalid` | `DEVICE_AUTH_PUBLIC_KEY_INVALID` | `device-public-key` | Format/kanonikalizacja klucza publicznego nie powiodły się. |
|
||||
|
||||
Cel migracji:
|
||||
|
||||
- Zawsze czekaj na `connect.challenge`.
|
||||
- Podpisuj ładunek v2, który zawiera nonce serwera.
|
||||
- Wyślij ten sam nonce w `connect.params.device.nonce`.
|
||||
- Preferowany ładunek podpisu to `v3`, który wiąże `platform` i `deviceFamily`
|
||||
- Podpisuj ładunek v2 zawierający nonce serwera.
|
||||
- Wysyłaj ten sam nonce w `connect.params.device.nonce`.
|
||||
- Preferowanym ładunkiem podpisu jest `v3`, który wiąże `platform` i `deviceFamily`
|
||||
oprócz pól device/client/role/scopes/token/nonce.
|
||||
- Starsze podpisy `v2` pozostają akceptowane ze względu na zgodność, ale przypinanie metadanych sparowanego urządzenia nadal kontroluje politykę poleceń przy ponownym połączeniu.
|
||||
- Starsze podpisy `v2` pozostają akceptowane dla zgodności, ale przypięcie
|
||||
metadanych sparowanego urządzenia nadal kontroluje politykę poleceń przy
|
||||
ponownym połączeniu.
|
||||
|
||||
## TLS + pinning
|
||||
|
||||
- TLS jest obsługiwany dla połączeń WS.
|
||||
- Klienci mogą opcjonalnie przypiąć odcisk palca certyfikatu gateway (zobacz konfigurację `gateway.tls`
|
||||
oraz `gateway.remote.tlsFingerprint` lub flagę CLI `--tls-fingerprint`).
|
||||
- Klienci mogą opcjonalnie przypinać odcisk palca certyfikatu bramy (zobacz
|
||||
konfigurację `gateway.tls` oraz `gateway.remote.tlsFingerprint` lub flagę CLI
|
||||
`--tls-fingerprint`).
|
||||
|
||||
## Zakres
|
||||
|
||||
Ten protokół udostępnia **pełne API gateway** (status, kanały, modele, czat,
|
||||
agent, sesje, węzły, zatwierdzenia itd.). Dokładna powierzchnia jest zdefiniowana przez
|
||||
schematy TypeBox w `src/gateway/protocol/schema.ts`.
|
||||
Ten protokół udostępnia **pełne API bramy** (status, kanały, modele, chat,
|
||||
agent, sesje, węzły, zatwierdzenia itd.). Dokładna powierzchnia jest
|
||||
zdefiniowana przez schematy TypeBox w `src/gateway/protocol/schema.ts`.
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@ -1,84 +1,97 @@
|
||||
---
|
||||
read_when:
|
||||
- Chcesz skonfigurować dostawców wyszukiwania pamięci lub modele embeddingów
|
||||
- Chcesz skonfigurować dostawców wyszukiwania w pamięci lub modele embeddingów
|
||||
- Chcesz skonfigurować backend QMD
|
||||
- Chcesz dostroić wyszukiwanie hybrydowe, MMR lub zanik czasowy
|
||||
- Chcesz dostroić wyszukiwanie hybrydowe, MMR lub zanikanie czasowe
|
||||
- Chcesz włączyć multimodalne indeksowanie pamięci
|
||||
summary: Wszystkie ustawienia konfiguracji dla wyszukiwania pamięci, dostawców embeddingów, QMD, wyszukiwania hybrydowego i indeksowania multimodalnego
|
||||
title: Dokumentacja konfiguracji pamięci
|
||||
summary: Wszystkie opcje konfiguracji wyszukiwania w pamięci, dostawców embeddingów, QMD, wyszukiwania hybrydowego i indeksowania multimodalnego
|
||||
title: Dokument referencyjny konfiguracji pamięci
|
||||
x-i18n:
|
||||
generated_at: "2026-04-06T03:13:06Z"
|
||||
generated_at: "2026-04-10T09:45:08Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 0de0b85125443584f4e575cf673ca8d9bd12ecd849d73c537f4a17545afa93fd
|
||||
source_hash: 5f9076bdfad95b87bd70625821bf401326f8eaeb53842b70823881419dbe43cb
|
||||
source_path: reference/memory-config.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Dokumentacja konfiguracji pamięci
|
||||
# Dokument referencyjny konfiguracji pamięci
|
||||
|
||||
Ta strona zawiera wszystkie ustawienia konfiguracji wyszukiwania pamięci w OpenClaw. Aby zapoznać się z
|
||||
omówieniem koncepcyjnym, zobacz:
|
||||
Ta strona zawiera wszystkie opcje konfiguracji wyszukiwania w pamięci w OpenClaw. Aby zapoznać się z
|
||||
omówieniem pojęciowym, zobacz:
|
||||
|
||||
- [Przegląd pamięci](/pl/concepts/memory) -- jak działa pamięć
|
||||
- [Wbudowany silnik](/pl/concepts/memory-builtin) -- domyślny backend SQLite
|
||||
- [Silnik QMD](/pl/concepts/memory-qmd) -- lokalny sidecar
|
||||
- [Wyszukiwanie pamięci](/pl/concepts/memory-search) -- pipeline wyszukiwania i strojenie
|
||||
- [Silnik QMD](/pl/concepts/memory-qmd) -- lokalny sidecar działający local-first
|
||||
- [Wyszukiwanie w pamięci](/pl/concepts/memory-search) -- potok wyszukiwania i strojenie
|
||||
- [Aktywna pamięć](/pl/concepts/active-memory) -- włączanie sub-agenta pamięci dla interaktywnych sesji
|
||||
|
||||
Wszystkie ustawienia wyszukiwania pamięci znajdują się w `agents.defaults.memorySearch` w
|
||||
`openclaw.json`, chyba że zaznaczono inaczej.
|
||||
Wszystkie ustawienia wyszukiwania w pamięci znajdują się w `agents.defaults.memorySearch` w
|
||||
`openclaw.json`, o ile nie wskazano inaczej.
|
||||
|
||||
Jeśli szukasz przełącznika funkcji **aktywnej pamięci** i konfiguracji sub-agenta,
|
||||
znajdują się one w `plugins.entries.active-memory`, a nie w `memorySearch`.
|
||||
|
||||
Aktywna pamięć używa modelu dwóch bramek:
|
||||
|
||||
1. plugin musi być włączony i kierować na bieżące ID agenta
|
||||
2. żądanie musi dotyczyć kwalifikującej się interaktywnej trwałej sesji czatu
|
||||
|
||||
Zobacz [Aktywna pamięć](/pl/concepts/active-memory), aby poznać model aktywacji,
|
||||
konfigurację należącą do pluginu, trwałość transkryptów i bezpieczny schemat wdrażania.
|
||||
|
||||
---
|
||||
|
||||
## Wybór dostawcy
|
||||
|
||||
| Key | Type | Default | Opis |
|
||||
| ---------- | --------- | ---------------- | ------------------------------------------------------------------------------------------ |
|
||||
| `provider` | `string` | wykrywany automatycznie | Identyfikator adaptera embeddingów: `openai`, `gemini`, `voyage`, `mistral`, `bedrock`, `ollama`, `local` |
|
||||
| Klucz | Typ | Domyślnie | Opis |
|
||||
| --------- | --------- | --------------- | ------------------------------------------------------------------------------------------- |
|
||||
| `provider` | `string` | wykrywany automatycznie | ID adaptera embeddingów: `openai`, `gemini`, `voyage`, `mistral`, `bedrock`, `ollama`, `local` |
|
||||
| `model` | `string` | domyślny dostawcy | Nazwa modelu embeddingów |
|
||||
| `fallback` | `string` | `"none"` | Identyfikator adaptera fallback, gdy podstawowy zawiedzie |
|
||||
| `enabled` | `boolean` | `true` | Włącza lub wyłącza wyszukiwanie pamięci |
|
||||
| `fallback` | `string` | `"none"` | ID adaptera zapasowego, gdy podstawowy zawiedzie |
|
||||
| `enabled` | `boolean` | `true` | Włącza lub wyłącza wyszukiwanie w pamięci |
|
||||
|
||||
### Kolejność automatycznego wykrywania
|
||||
|
||||
Gdy `provider` nie jest ustawiony, OpenClaw wybiera pierwszy dostępny:
|
||||
|
||||
1. `local` -- jeśli `memorySearch.local.modelPath` jest skonfigurowane i plik istnieje.
|
||||
1. `local` -- jeśli skonfigurowano `memorySearch.local.modelPath` i plik istnieje.
|
||||
2. `openai` -- jeśli można rozpoznać klucz OpenAI.
|
||||
3. `gemini` -- jeśli można rozpoznać klucz Gemini.
|
||||
4. `voyage` -- jeśli można rozpoznać klucz Voyage.
|
||||
5. `mistral` -- jeśli można rozpoznać klucz Mistral.
|
||||
6. `bedrock` -- jeśli łańcuch poświadczeń AWS SDK zostanie rozpoznany (rola instancji, klucze dostępu, profil, SSO, tożsamość webowa lub współdzielona konfiguracja).
|
||||
6. `bedrock` -- jeśli łańcuch poświadczeń AWS SDK zostanie rozwiązany (rola instancji, klucze dostępu, profil, SSO, tożsamość webowa lub współdzielona konfiguracja).
|
||||
|
||||
`ollama` jest obsługiwane, ale nie jest wykrywane automatycznie (ustaw je jawnie).
|
||||
`ollama` jest obsługiwany, ale nie jest wykrywany automatycznie (ustaw go jawnie).
|
||||
|
||||
### Rozpoznawanie klucza API
|
||||
|
||||
Zdalne embeddingi wymagają klucza API. Bedrock zamiast tego używa domyślnego
|
||||
łańcucha poświadczeń AWS SDK (role instancji, SSO, klucze dostępu).
|
||||
|
||||
| Provider | Zmienna env | Klucz config |
|
||||
| -------- | ------------------------------ | --------------------------------- |
|
||||
| OpenAI | `OPENAI_API_KEY` | `models.providers.openai.apiKey` |
|
||||
| Gemini | `GEMINI_API_KEY` | `models.providers.google.apiKey` |
|
||||
| Voyage | `VOYAGE_API_KEY` | `models.providers.voyage.apiKey` |
|
||||
| Dostawca | Zmienna środowiskowa | Klucz konfiguracji |
|
||||
| -------- | ------------------------------ | -------------------------------- |
|
||||
| OpenAI | `OPENAI_API_KEY` | `models.providers.openai.apiKey` |
|
||||
| Gemini | `GEMINI_API_KEY` | `models.providers.google.apiKey` |
|
||||
| Voyage | `VOYAGE_API_KEY` | `models.providers.voyage.apiKey` |
|
||||
| Mistral | `MISTRAL_API_KEY` | `models.providers.mistral.apiKey` |
|
||||
| Bedrock | łańcuch poświadczeń AWS | Klucz API nie jest potrzebny |
|
||||
| Ollama | `OLLAMA_API_KEY` (placeholder) | -- |
|
||||
| Bedrock | łańcuch poświadczeń AWS | Klucz API nie jest potrzebny |
|
||||
| Ollama | `OLLAMA_API_KEY` (placeholder) | -- |
|
||||
|
||||
OAuth Codex obejmuje tylko czat/uzupełnienia i nie spełnia wymagań żądań embeddingów.
|
||||
OAuth Codex obejmuje tylko chat/completions i nie spełnia wymagań żądań
|
||||
embeddingów.
|
||||
|
||||
---
|
||||
|
||||
## Konfiguracja zdalnego endpointu
|
||||
## Konfiguracja zdalnego punktu końcowego
|
||||
|
||||
Dla niestandardowych endpointów zgodnych z OpenAI lub nadpisywania domyślnych wartości dostawcy:
|
||||
Do niestandardowych punktów końcowych zgodnych z OpenAI lub nadpisania ustawień domyślnych dostawcy:
|
||||
|
||||
| Key | Type | Opis |
|
||||
| ---------------- | -------- | -------------------------------------------------- |
|
||||
| `remote.baseUrl` | `string` | Niestandardowy bazowy URL API |
|
||||
| `remote.apiKey` | `string` | Nadpisanie klucza API |
|
||||
| `remote.headers` | `object` | Dodatkowe nagłówki HTTP (scalane z domyślnymi dostawcy) |
|
||||
| Klucz | Typ | Opis |
|
||||
| ----------------- | -------- | ------------------------------------------------ |
|
||||
| `remote.baseUrl` | `string` | Niestandardowy bazowy URL API |
|
||||
| `remote.apiKey` | `string` | Nadpisuje klucz API |
|
||||
| `remote.headers` | `object` | Dodatkowe nagłówki HTTP (łączone z domyślnymi ustawieniami dostawcy) |
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -101,21 +114,21 @@ Dla niestandardowych endpointów zgodnych z OpenAI lub nadpisywania domyślnych
|
||||
|
||||
## Konfiguracja specyficzna dla Gemini
|
||||
|
||||
| Key | Type | Default | Opis |
|
||||
| ---------------------- | -------- | ---------------------- | ------------------------------------------ |
|
||||
| `model` | `string` | `gemini-embedding-001` | Obsługuje też `gemini-embedding-2-preview` |
|
||||
| `outputDimensionality` | `number` | `3072` | Dla Embedding 2: 768, 1536 lub 3072 |
|
||||
| Klucz | Typ | Domyślnie | Opis |
|
||||
| ---------------------- | -------- | --------------------- | ------------------------------------------ |
|
||||
| `model` | `string` | `gemini-embedding-001` | Obsługuje także `gemini-embedding-2-preview` |
|
||||
| `outputDimensionality` | `number` | `3072` | Dla Embedding 2: 768, 1536 lub 3072 |
|
||||
|
||||
<Warning>
|
||||
Zmiana modelu lub `outputDimensionality` uruchamia automatyczne pełne ponowne indeksowanie.
|
||||
Zmiana modelu lub `outputDimensionality` uruchamia automatyczne pełne przeindeksowanie.
|
||||
</Warning>
|
||||
|
||||
---
|
||||
|
||||
## Konfiguracja embeddingów Bedrock
|
||||
|
||||
Bedrock używa domyślnego łańcucha poświadczeń AWS SDK -- klucze API nie są potrzebne.
|
||||
Jeśli OpenClaw działa na EC2 z rolą instancji z włączonym Bedrock, po prostu ustaw
|
||||
Bedrock używa domyślnego łańcucha poświadczeń AWS SDK -- nie są potrzebne żadne klucze API.
|
||||
Jeśli OpenClaw działa na EC2 z rolą instancji obsługującą Bedrock, po prostu ustaw
|
||||
dostawcę i model:
|
||||
|
||||
```json5
|
||||
@ -131,17 +144,17 @@ dostawcę i model:
|
||||
}
|
||||
```
|
||||
|
||||
| Key | Type | Default | Opis |
|
||||
| ---------------------- | -------- | ------------------------------ | ----------------------------- |
|
||||
| `model` | `string` | `amazon.titan-embed-text-v2:0` | Dowolny identyfikator modelu embeddingów Bedrock |
|
||||
| `outputDimensionality` | `number` | domyślna wartość modelu | Dla Titan V2: 256, 512 lub 1024 |
|
||||
| Klucz | Typ | Domyślnie | Opis |
|
||||
| ---------------------- | -------- | ----------------------------- | --------------------------------- |
|
||||
| `model` | `string` | `amazon.titan-embed-text-v2:0` | Dowolne ID modelu embeddingów Bedrock |
|
||||
| `outputDimensionality` | `number` | domyślna wartość modelu | Dla Titan V2: 256, 512 lub 1024 |
|
||||
|
||||
### Obsługiwane modele
|
||||
|
||||
Obsługiwane są następujące modele (z wykrywaniem rodziny i domyślnymi
|
||||
wymiarami):
|
||||
|
||||
| Model ID | Provider | Domyślne wymiary | Konfigurowalne wymiary |
|
||||
| ID modelu | Dostawca | Domyślne wymiary | Konfigurowalne wymiary |
|
||||
| ------------------------------------------ | ---------- | ---------------- | ---------------------- |
|
||||
| `amazon.titan-embed-text-v2:0` | Amazon | 1024 | 256, 512, 1024 |
|
||||
| `amazon.titan-embed-text-v1` | Amazon | 1536 | -- |
|
||||
@ -154,7 +167,7 @@ wymiarami):
|
||||
| `twelvelabs.marengo-embed-3-0-v1:0` | TwelveLabs | 512 | -- |
|
||||
| `twelvelabs.marengo-embed-2-7-v1:0` | TwelveLabs | 1024 | -- |
|
||||
|
||||
Warianty z sufiksem przepustowości (na przykład `amazon.titan-embed-text-v1:2:8k`) dziedziczą
|
||||
Warianty z sufiksem przepustowości (np. `amazon.titan-embed-text-v1:2:8k`) dziedziczą
|
||||
konfigurację modelu bazowego.
|
||||
|
||||
### Uwierzytelnianie
|
||||
@ -162,17 +175,17 @@ konfigurację modelu bazowego.
|
||||
Uwierzytelnianie Bedrock używa standardowej kolejności rozpoznawania poświadczeń AWS SDK:
|
||||
|
||||
1. Zmienne środowiskowe (`AWS_ACCESS_KEY_ID` + `AWS_SECRET_ACCESS_KEY`)
|
||||
2. Cache tokenów SSO
|
||||
3. Poświadczenia tokena tożsamości webowej
|
||||
2. Pamięć podręczna tokenów SSO
|
||||
3. Poświadczenia tokenu tożsamości webowej
|
||||
4. Współdzielone pliki poświadczeń i konfiguracji
|
||||
5. Poświadczenia metadanych ECS lub EC2
|
||||
|
||||
Region jest rozpoznawany z `AWS_REGION`, `AWS_DEFAULT_REGION`, `baseUrl`
|
||||
dostawcy `amazon-bedrock` lub domyślnie ustawiany na `us-east-1`.
|
||||
Region jest rozpoznawany na podstawie `AWS_REGION`, `AWS_DEFAULT_REGION`,
|
||||
`baseUrl` dostawcy `amazon-bedrock` albo domyślnie przyjmuje wartość `us-east-1`.
|
||||
|
||||
### Uprawnienia IAM
|
||||
|
||||
Rola IAM lub użytkownik potrzebują:
|
||||
Rola IAM lub użytkownik potrzebuje:
|
||||
|
||||
```json
|
||||
{
|
||||
@ -182,7 +195,7 @@ Rola IAM lub użytkownik potrzebują:
|
||||
}
|
||||
```
|
||||
|
||||
Dla zasady najmniejszych uprawnień ogranicz `InvokeModel` do konkretnego modelu:
|
||||
Aby zachować zasadę najmniejszych uprawnień, ogranicz `InvokeModel` do konkretnego modelu:
|
||||
|
||||
```
|
||||
arn:aws:bedrock:*::foundation-model/amazon.titan-embed-text-v2:0
|
||||
@ -192,42 +205,42 @@ arn:aws:bedrock:*::foundation-model/amazon.titan-embed-text-v2:0
|
||||
|
||||
## Konfiguracja lokalnych embeddingów
|
||||
|
||||
| Key | Type | Default | Opis |
|
||||
| --------------------- | -------- | ---------------------- | ------------------------------- |
|
||||
| `local.modelPath` | `string` | pobierane automatycznie | Ścieżka do pliku modelu GGUF |
|
||||
| `local.modelCacheDir` | `string` | domyślna wartość node-llama-cpp | Katalog cache dla pobranych modeli |
|
||||
| Klucz | Typ | Domyślnie | Opis |
|
||||
| --------------------- | -------- | --------------------- | ------------------------------ |
|
||||
| `local.modelPath` | `string` | pobierany automatycznie | Ścieżka do pliku modelu GGUF |
|
||||
| `local.modelCacheDir` | `string` | domyślna wartość node-llama-cpp | Katalog pamięci podręcznej dla pobranych modeli |
|
||||
|
||||
Domyślny model: `embeddinggemma-300m-qat-Q8_0.gguf` (~0.6 GB, pobierany automatycznie).
|
||||
Wymaga natywnej kompilacji: `pnpm approve-builds`, a następnie `pnpm rebuild node-llama-cpp`.
|
||||
Wymaga natywnego builda: `pnpm approve-builds`, a następnie `pnpm rebuild node-llama-cpp`.
|
||||
|
||||
---
|
||||
|
||||
## Konfiguracja wyszukiwania hybrydowego
|
||||
|
||||
Wszystko pod `memorySearch.query.hybrid`:
|
||||
Wszystko znajduje się w `memorySearch.query.hybrid`:
|
||||
|
||||
| Key | Type | Default | Opis |
|
||||
| --------------------- | --------- | ------- | -------------------------------- |
|
||||
| `enabled` | `boolean` | `true` | Włącza hybrydowe wyszukiwanie BM25 + wektorowe |
|
||||
| `vectorWeight` | `number` | `0.7` | Waga dla wyników wektorowych (0-1) |
|
||||
| `textWeight` | `number` | `0.3` | Waga dla wyników BM25 (0-1) |
|
||||
| `candidateMultiplier` | `number` | `4` | Mnożnik rozmiaru puli kandydatów |
|
||||
| Klucz | Typ | Domyślnie | Opis |
|
||||
| --------------------- | --------- | --------- | ---------------------------------- |
|
||||
| `enabled` | `boolean` | `true` | Włącza hybrydowe wyszukiwanie BM25 + wektorowe |
|
||||
| `vectorWeight` | `number` | `0.7` | Waga wyników wektorowych (0-1) |
|
||||
| `textWeight` | `number` | `0.3` | Waga wyników BM25 (0-1) |
|
||||
| `candidateMultiplier` | `number` | `4` | Mnożnik rozmiaru puli kandydatów |
|
||||
|
||||
### MMR (różnorodność)
|
||||
|
||||
| Key | Type | Default | Opis |
|
||||
| ------------- | --------- | ------- | ------------------------------------ |
|
||||
| `mmr.enabled` | `boolean` | `false` | Włącza ponowne rangowanie MMR |
|
||||
| `mmr.lambda` | `number` | `0.7` | 0 = maksymalna różnorodność, 1 = maksymalna trafność |
|
||||
| Klucz | Typ | Domyślnie | Opis |
|
||||
| ------------- | --------- | --------- | ---------------------------------------- |
|
||||
| `mmr.enabled` | `boolean` | `false` | Włącza ponowne rankingowanie MMR |
|
||||
| `mmr.lambda` | `number` | `0.7` | 0 = maksymalna różnorodność, 1 = maksymalna trafność |
|
||||
|
||||
### Zanik czasowy (świeżość)
|
||||
### Zanikanie czasowe (świeżość)
|
||||
|
||||
| Key | Type | Default | Opis |
|
||||
| ---------------------------- | --------- | ------- | ----------------------------- |
|
||||
| `temporalDecay.enabled` | `boolean` | `false` | Włącza premiowanie świeżości |
|
||||
| `temporalDecay.halfLifeDays` | `number` | `30` | Wynik spada o połowę co N dni |
|
||||
| Klucz | Typ | Domyślnie | Opis |
|
||||
| ---------------------------- | --------- | --------- | ----------------------------- |
|
||||
| `temporalDecay.enabled` | `boolean` | `false` | Włącza premiowanie świeżości |
|
||||
| `temporalDecay.halfLifeDays` | `number` | `30` | Wynik spada o połowę co N dni |
|
||||
|
||||
Pliki evergreen (`MEMORY.md`, pliki bez dat w `memory/`) nigdy nie podlegają zanikowi.
|
||||
Pliki stałe (`MEMORY.md`, pliki bez daty w `memory/`) nigdy nie podlegają zanikaniu.
|
||||
|
||||
### Pełny przykład
|
||||
|
||||
@ -254,9 +267,9 @@ Pliki evergreen (`MEMORY.md`, pliki bez dat w `memory/`) nigdy nie podlegają za
|
||||
|
||||
## Dodatkowe ścieżki pamięci
|
||||
|
||||
| Key | Type | Opis |
|
||||
| ------------ | ---------- | -------------------------------------------- |
|
||||
| `extraPaths` | `string[]` | Dodatkowe katalogi lub pliki do indeksowania |
|
||||
| Klucz | Typ | Opis |
|
||||
| ----------- | ---------- | --------------------------------------- |
|
||||
| `extraPaths` | `string[]` | Dodatkowe katalogi lub pliki do zindeksowania |
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -270,33 +283,31 @@ Pliki evergreen (`MEMORY.md`, pliki bez dat w `memory/`) nigdy nie podlegają za
|
||||
}
|
||||
```
|
||||
|
||||
Ścieżki mogą być bezwzględne lub względne względem obszaru roboczego. Katalogi są skanowane
|
||||
Ścieżki mogą być bezwzględne lub względne względem workspace. Katalogi są skanowane
|
||||
rekurencyjnie w poszukiwaniu plików `.md`. Obsługa symlinków zależy od aktywnego backendu:
|
||||
wbudowany silnik ignoruje symlinki, podczas gdy QMD korzysta z zachowania
|
||||
bazowego skanera QMD.
|
||||
wbudowany silnik ignoruje symlinki, a QMD stosuje zachowanie skanera QMD.
|
||||
|
||||
Dla wyszukiwania transkryptów między agentami w zakresie agenta użyj
|
||||
W przypadku wyszukiwania transkryptów między agentami w zakresie agenta użyj
|
||||
`agents.list[].memorySearch.qmd.extraCollections` zamiast `memory.qmd.paths`.
|
||||
Te dodatkowe kolekcje używają tego samego kształtu `{ path, name, pattern? }`, ale
|
||||
są scalane dla każdego agenta i mogą zachować jawne współdzielone nazwy, gdy ścieżka
|
||||
wskazuje poza bieżący obszar roboczy.
|
||||
Jeśli ta sama rozpoznana ścieżka pojawi się zarówno w `memory.qmd.paths`, jak i
|
||||
`memorySearch.qmd.extraCollections`, QMD zachowuje pierwszy wpis i pomija
|
||||
duplikat.
|
||||
Te dodatkowe kolekcje mają ten sam kształt `{ path, name, pattern? }`, ale
|
||||
są scalane per agent i mogą zachowywać jawne wspólne nazwy, gdy ścieżka
|
||||
wskazuje poza bieżący workspace.
|
||||
Jeśli ta sama rozpoznana ścieżka pojawi się zarówno w `memory.qmd.paths`, jak i w
|
||||
`memorySearch.qmd.extraCollections`, QMD zachowa pierwszy wpis i pominie duplikat.
|
||||
|
||||
---
|
||||
|
||||
## Pamięć multimodalna (Gemini)
|
||||
|
||||
Indeksuj obrazy i audio razem z Markdown przy użyciu Gemini Embedding 2:
|
||||
Indeksuj obrazy i audio obok Markdown za pomocą Gemini Embedding 2:
|
||||
|
||||
| Key | Type | Default | Opis |
|
||||
| ------------------------- | ---------- | ---------- | ------------------------------------------- |
|
||||
| `multimodal.enabled` | `boolean` | `false` | Włącza indeksowanie multimodalne |
|
||||
| `multimodal.modalities` | `string[]` | -- | `["image"]`, `["audio"]` lub `["all"]` |
|
||||
| `multimodal.maxFileBytes` | `number` | `10000000` | Maksymalny rozmiar pliku do indeksowania |
|
||||
| Klucz | Typ | Domyślnie | Opis |
|
||||
| ------------------------- | ---------- | ---------- | -------------------------------------- |
|
||||
| `multimodal.enabled` | `boolean` | `false` | Włącza indeksowanie multimodalne |
|
||||
| `multimodal.modalities` | `string[]` | -- | `["image"]`, `["audio"]` lub `["all"]` |
|
||||
| `multimodal.maxFileBytes` | `number` | `10000000` | Maksymalny rozmiar pliku do indeksowania |
|
||||
|
||||
Dotyczy tylko plików w `extraPaths`. Domyślne korzenie pamięci pozostają tylko dla Markdown.
|
||||
Dotyczy tylko plików w `extraPaths`. Domyślne katalogi pamięci pozostają tylko dla Markdown.
|
||||
Wymaga `gemini-embedding-2-preview`. `fallback` musi mieć wartość `"none"`.
|
||||
|
||||
Obsługiwane formaty: `.jpg`, `.jpeg`, `.png`, `.webp`, `.gif`, `.heic`, `.heif`
|
||||
@ -304,67 +315,67 @@ Obsługiwane formaty: `.jpg`, `.jpeg`, `.png`, `.webp`, `.gif`, `.heic`, `.heif`
|
||||
|
||||
---
|
||||
|
||||
## Cache embeddingów
|
||||
## Pamięć podręczna embeddingów
|
||||
|
||||
| Key | Type | Default | Opis |
|
||||
| ------------------ | --------- | ------- | -------------------------------- |
|
||||
| `cache.enabled` | `boolean` | `false` | Buforuje embeddingi fragmentów w SQLite |
|
||||
| `cache.maxEntries` | `number` | `50000` | Maksymalna liczba buforowanych embeddingów |
|
||||
| Klucz | Typ | Domyślnie | Opis |
|
||||
| ------------------ | --------- | --------- | --------------------------------- |
|
||||
| `cache.enabled` | `boolean` | `false` | Buforuje embeddingi fragmentów w SQLite |
|
||||
| `cache.maxEntries` | `number` | `50000` | Maksymalna liczba buforowanych embeddingów |
|
||||
|
||||
Zapobiega ponownemu osadzaniu niezmienionego tekstu podczas reindeksowania lub aktualizacji transkryptów.
|
||||
Zapobiega ponownemu tworzeniu embeddingów dla niezmienionego tekstu podczas ponownego indeksowania lub aktualizacji transkryptów.
|
||||
|
||||
---
|
||||
|
||||
## Indeksowanie wsadowe
|
||||
|
||||
| Key | Type | Default | Opis |
|
||||
| ----------------------------- | --------- | ------- | ---------------------------- |
|
||||
| `remote.batch.enabled` | `boolean` | `false` | Włącza API embeddingów wsadowych |
|
||||
| `remote.batch.concurrency` | `number` | `2` | Równoległe zadania wsadowe |
|
||||
| `remote.batch.wait` | `boolean` | `true` | Czeka na zakończenie wsadu |
|
||||
| `remote.batch.pollIntervalMs` | `number` | -- | Interwał odpytywania |
|
||||
| `remote.batch.timeoutMinutes` | `number` | -- | Limit czasu wsadu |
|
||||
| Klucz | Typ | Domyślnie | Opis |
|
||||
| -------------------------- | --------- | --------- | -------------------------- |
|
||||
| `remote.batch.enabled` | `boolean` | `false` | Włącza API embeddingów wsadowych |
|
||||
| `remote.batch.concurrency` | `number` | `2` | Równoległe zadania wsadowe |
|
||||
| `remote.batch.wait` | `boolean` | `true` | Czeka na zakończenie wsadu |
|
||||
| `remote.batch.pollIntervalMs` | `number` | -- | Interwał odpytywania |
|
||||
| `remote.batch.timeoutMinutes` | `number` | -- | Limit czasu wsadu |
|
||||
|
||||
Dostępne dla `openai`, `gemini` i `voyage`. Wsady OpenAI są zwykle
|
||||
najszybsze i najtańsze przy dużych uzupełnieniach zaległości.
|
||||
najszybsze i najtańsze przy dużych uzupełnieniach historycznych.
|
||||
|
||||
---
|
||||
|
||||
## Wyszukiwanie pamięci sesji (eksperymentalne)
|
||||
## Wyszukiwanie w pamięci sesji (eksperymentalne)
|
||||
|
||||
Indeksuj transkrypty sesji i udostępniaj je przez `memory_search`:
|
||||
Indeksuj transkrypcje sesji i udostępniaj je przez `memory_search`:
|
||||
|
||||
| Key | Type | Default | Opis |
|
||||
| ----------------------------- | ---------- | ------------ | ------------------------------------------- |
|
||||
| `experimental.sessionMemory` | `boolean` | `false` | Włącza indeksowanie sesji |
|
||||
| `sources` | `string[]` | `["memory"]` | Dodaj `"sessions"`, aby uwzględnić transkrypty |
|
||||
| `sync.sessions.deltaBytes` | `number` | `100000` | Próg bajtów dla reindeksowania |
|
||||
| `sync.sessions.deltaMessages` | `number` | `50` | Próg wiadomości dla reindeksowania |
|
||||
| Klucz | Typ | Domyślnie | Opis |
|
||||
| --------------------------- | ---------- | ------------ | ----------------------------------------- |
|
||||
| `experimental.sessionMemory` | `boolean` | `false` | Włącza indeksowanie sesji |
|
||||
| `sources` | `string[]` | `["memory"]` | Dodaj `"sessions"`, aby uwzględnić transkrypcje |
|
||||
| `sync.sessions.deltaBytes` | `number` | `100000` | Próg bajtów dla ponownego indeksowania |
|
||||
| `sync.sessions.deltaMessages` | `number` | `50` | Próg liczby wiadomości dla ponownego indeksowania |
|
||||
|
||||
Indeksowanie sesji jest opt-in i działa asynchronicznie. Wyniki mogą być nieco
|
||||
nieaktualne. Logi sesji są przechowywane na dysku, więc dostęp do systemu plików należy traktować jako
|
||||
granicę zaufania.
|
||||
Indeksowanie sesji jest funkcją opt-in i działa asynchronicznie. Wyniki mogą być nieco
|
||||
nieaktualne. Logi sesji są przechowywane na dysku, więc granicą zaufania pozostaje
|
||||
dostęp do systemu plików.
|
||||
|
||||
---
|
||||
|
||||
## Przyspieszenie wektorowe SQLite (sqlite-vec)
|
||||
## Akceleracja wektorowa SQLite (sqlite-vec)
|
||||
|
||||
| Key | Type | Default | Opis |
|
||||
| ---------------------------- | --------- | ------- | ---------------------------------- |
|
||||
| `store.vector.enabled` | `boolean` | `true` | Używa sqlite-vec dla zapytań wektorowych |
|
||||
| `store.vector.extensionPath` | `string` | dołączone | Nadpisuje ścieżkę sqlite-vec |
|
||||
| Klucz | Typ | Domyślnie | Opis |
|
||||
| ------------------------- | --------- | --------- | --------------------------------- |
|
||||
| `store.vector.enabled` | `boolean` | `true` | Używa sqlite-vec do zapytań wektorowych |
|
||||
| `store.vector.extensionPath` | `string` | dołączona | Nadpisuje ścieżkę do sqlite-vec |
|
||||
|
||||
Gdy sqlite-vec jest niedostępne, OpenClaw automatycznie przechodzi awaryjnie do
|
||||
podobieństwa cosinusowego w procesie.
|
||||
Gdy sqlite-vec jest niedostępne, OpenClaw automatycznie przełącza się na
|
||||
podobieństwo cosinusowe w procesie.
|
||||
|
||||
---
|
||||
|
||||
## Przechowywanie indeksu
|
||||
|
||||
| Key | Type | Default | Opis |
|
||||
| --------------------- | -------- | ------------------------------------- | -------------------------------------------- |
|
||||
| `store.path` | `string` | `~/.openclaw/memory/{agentId}.sqlite` | Lokalizacja indeksu (obsługuje token `{agentId}`) |
|
||||
| `store.fts.tokenizer` | `string` | `unicode61` | Tokenizer FTS5 (`unicode61` lub `trigram`) |
|
||||
| Klucz | Typ | Domyślnie | Opis |
|
||||
| -------------------- | -------- | ------------------------------------ | -------------------------------------------- |
|
||||
| `store.path` | `string` | `~/.openclaw/memory/{agentId}.sqlite` | Lokalizacja indeksu (obsługuje token `{agentId}`) |
|
||||
| `store.fts.tokenizer` | `string` | `unicode61` | Tokenizer FTS5 (`unicode61` lub `trigram`) |
|
||||
|
||||
---
|
||||
|
||||
@ -373,50 +384,49 @@ podobieństwa cosinusowego w procesie.
|
||||
Ustaw `memory.backend = "qmd"`, aby włączyć. Wszystkie ustawienia QMD znajdują się w
|
||||
`memory.qmd`:
|
||||
|
||||
| Key | Type | Default | Opis |
|
||||
| ------------------------ | --------- | -------- | -------------------------------------------- |
|
||||
| `command` | `string` | `qmd` | Ścieżka do pliku wykonywalnego QMD |
|
||||
| `searchMode` | `string` | `search` | Polecenie wyszukiwania: `search`, `vsearch`, `query` |
|
||||
| `includeDefaultMemory` | `boolean` | `true` | Automatycznie indeksuje `MEMORY.md` + `memory/**/*.md` |
|
||||
| `paths[]` | `array` | -- | Dodatkowe ścieżki: `{ name, path, pattern? }` |
|
||||
| `sessions.enabled` | `boolean` | `false` | Indeksuje transkrypty sesji |
|
||||
| `sessions.retentionDays` | `number` | -- | Retencja transkryptów |
|
||||
| `sessions.exportDir` | `string` | -- | Katalog eksportu |
|
||||
| Klucz | Typ | Domyślnie | Opis |
|
||||
| ----------------------- | --------- | --------- | -------------------------------------------- |
|
||||
| `command` | `string` | `qmd` | Ścieżka do pliku wykonywalnego QMD |
|
||||
| `searchMode` | `string` | `search` | Polecenie wyszukiwania: `search`, `vsearch`, `query` |
|
||||
| `includeDefaultMemory` | `boolean` | `true` | Automatycznie indeksuje `MEMORY.md` + `memory/**/*.md` |
|
||||
| `paths[]` | `array` | -- | Dodatkowe ścieżki: `{ name, path, pattern? }` |
|
||||
| `sessions.enabled` | `boolean` | `false` | Indeksuje transkrypcje sesji |
|
||||
| `sessions.retentionDays` | `number` | -- | Retencja transkryptów |
|
||||
| `sessions.exportDir` | `string` | -- | Katalog eksportu |
|
||||
|
||||
OpenClaw preferuje bieżące kształty kolekcji QMD i zapytań MCP, ale zachowuje
|
||||
zgodność ze starszymi wydaniami QMD, przechodząc awaryjnie do starszych flag kolekcji `--mask`
|
||||
i starszych nazw narzędzi MCP, gdy jest to potrzebne.
|
||||
zgodność ze starszymi wydaniami QMD, przechodząc w razie potrzeby na starsze flagi kolekcji `--mask`
|
||||
oraz starsze nazwy narzędzi MCP.
|
||||
|
||||
Nadpisania modeli QMD pozostają po stronie QMD, a nie w config OpenClaw. Jeśli musisz
|
||||
globalnie nadpisać modele QMD, ustaw zmienne środowiskowe, takie jak
|
||||
`QMD_EMBED_MODEL`, `QMD_RERANK_MODEL` i `QMD_GENERATE_MODEL`, w środowisku runtime
|
||||
gateway.
|
||||
Nadpisania modeli QMD pozostają po stronie QMD, a nie w konfiguracji OpenClaw. Jeśli chcesz
|
||||
globalnie nadpisać modele QMD, ustaw zmienne środowiskowe takie jak
|
||||
`QMD_EMBED_MODEL`, `QMD_RERANK_MODEL` i `QMD_GENERATE_MODEL` w środowisku uruchomieniowym gatewaya.
|
||||
|
||||
### Harmonogram aktualizacji
|
||||
|
||||
| Key | Type | Default | Opis |
|
||||
| ------------------------- | --------- | ------- | -------------------------------------- |
|
||||
| `update.interval` | `string` | `5m` | Interwał odświeżania |
|
||||
| `update.debounceMs` | `number` | `15000` | Opóźnienie zmian plików |
|
||||
| `update.onBoot` | `boolean` | `true` | Odświeżanie przy uruchomieniu |
|
||||
| `update.waitForBootSync` | `boolean` | `false` | Blokuje uruchomienie do zakończenia odświeżania |
|
||||
| `update.embedInterval` | `string` | -- | Oddzielna kadencja embeddingów |
|
||||
| `update.commandTimeoutMs` | `number` | -- | Limit czasu dla poleceń QMD |
|
||||
| `update.updateTimeoutMs` | `number` | -- | Limit czasu dla operacji aktualizacji QMD |
|
||||
| `update.embedTimeoutMs` | `number` | -- | Limit czasu dla operacji embeddingów QMD |
|
||||
| Klucz | Typ | Domyślnie | Opis |
|
||||
| ------------------------ | --------- | --------- | ----------------------------------------- |
|
||||
| `update.interval` | `string` | `5m` | Interwał odświeżania |
|
||||
| `update.debounceMs` | `number` | `15000` | Debounce zmian plików |
|
||||
| `update.onBoot` | `boolean` | `true` | Odświeża przy uruchomieniu |
|
||||
| `update.waitForBootSync` | `boolean` | `false` | Blokuje uruchamianie do zakończenia odświeżenia |
|
||||
| `update.embedInterval` | `string` | -- | Oddzielna częstotliwość embeddingów |
|
||||
| `update.commandTimeoutMs` | `number` | -- | Limit czasu dla poleceń QMD |
|
||||
| `update.updateTimeoutMs` | `number` | -- | Limit czasu dla operacji aktualizacji QMD |
|
||||
| `update.embedTimeoutMs` | `number` | -- | Limit czasu dla operacji embeddingów QMD |
|
||||
|
||||
### Limity
|
||||
|
||||
| Key | Type | Default | Opis |
|
||||
| ------------------------- | -------- | ------- | ------------------------------ |
|
||||
| `limits.maxResults` | `number` | `6` | Maksymalna liczba wyników wyszukiwania |
|
||||
| `limits.maxSnippetChars` | `number` | -- | Ogranicza długość fragmentu |
|
||||
| `limits.maxInjectedChars` | `number` | -- | Ogranicza łączną liczbę wstrzykniętych znaków |
|
||||
| `limits.timeoutMs` | `number` | `4000` | Limit czasu wyszukiwania |
|
||||
| Klucz | Typ | Domyślnie | Opis |
|
||||
| ------------------------ | -------- | --------- | ------------------------------ |
|
||||
| `limits.maxResults` | `number` | `6` | Maksymalna liczba wyników wyszukiwania |
|
||||
| `limits.maxSnippetChars` | `number` | -- | Ogranicza długość fragmentu |
|
||||
| `limits.maxInjectedChars` | `number` | -- | Ogranicza łączną liczbę wstrzykniętych znaków |
|
||||
| `limits.timeoutMs` | `number` | `4000` | Limit czasu wyszukiwania |
|
||||
|
||||
### Zakres
|
||||
|
||||
Steruje tym, które sesje mogą otrzymywać wyniki wyszukiwania QMD. Ten sam schemat co
|
||||
Kontroluje, które sesje mogą otrzymywać wyniki wyszukiwania QMD. Ten sam schemat co
|
||||
[`session.sendPolicy`](/pl/gateway/configuration-reference#session):
|
||||
|
||||
```json5
|
||||
@ -433,16 +443,16 @@ Steruje tym, które sesje mogą otrzymywać wyniki wyszukiwania QMD. Ten sam sch
|
||||
```
|
||||
|
||||
Domyślnie tylko DM. `match.keyPrefix` dopasowuje znormalizowany klucz sesji;
|
||||
`match.rawKeyPrefix` dopasowuje surowy klucz, w tym `agent:<id>:`.
|
||||
`match.rawKeyPrefix` dopasowuje surowy klucz zawierający `agent:<id>:`.
|
||||
|
||||
### Cytowania
|
||||
|
||||
`memory.citations` dotyczy wszystkich backendów:
|
||||
|
||||
| Value | Zachowanie |
|
||||
| ---------------- | ---------------------------------------------------- |
|
||||
| `auto` (domyślne) | Uwzględnia stopkę `Source: <path#line>` we fragmentach |
|
||||
| `on` | Zawsze uwzględnia stopkę |
|
||||
| Wartość | Zachowanie |
|
||||
| ---------------- | -------------------------------------------------- |
|
||||
| `auto` (domyślnie) | Dołącza stopkę `Source: <path#line>` w fragmentach |
|
||||
| `on` | Zawsze dołącza stopkę |
|
||||
| `off` | Pomija stopkę (ścieżka nadal jest przekazywana agentowi wewnętrznie) |
|
||||
|
||||
### Pełny przykład QMD
|
||||
@ -470,20 +480,20 @@ Domyślnie tylko DM. `match.keyPrefix` dopasowuje znormalizowany klucz sesji;
|
||||
|
||||
## Dreaming (eksperymentalne)
|
||||
|
||||
Dreaming jest konfigurowane pod `plugins.entries.memory-core.config.dreaming`,
|
||||
a nie pod `agents.defaults.memorySearch`.
|
||||
Dreaming jest konfigurowane w `plugins.entries.memory-core.config.dreaming`,
|
||||
a nie w `agents.defaults.memorySearch`.
|
||||
|
||||
Dreaming działa jako jedno zaplanowane przejście i wykorzystuje wewnętrzne fazy light/deep/REM jako
|
||||
szczegół implementacyjny.
|
||||
Dreaming działa jako jeden zaplanowany przebieg i używa wewnętrznych faz light/deep/REM jako
|
||||
szczegółu implementacyjnego.
|
||||
|
||||
Aby poznać zachowanie koncepcyjne i polecenia ukośnikowe, zobacz [Dreaming](/concepts/dreaming).
|
||||
Aby zapoznać się z działaniem pojęciowym i poleceniami slash, zobacz [Dreaming](/pl/concepts/dreaming).
|
||||
|
||||
### Ustawienia użytkownika
|
||||
|
||||
| Key | Type | Default | Opis |
|
||||
| Klucz | Typ | Domyślnie | Opis |
|
||||
| ----------- | --------- | ----------- | ------------------------------------------------- |
|
||||
| `enabled` | `boolean` | `false` | Włącza lub wyłącza dreaming całkowicie |
|
||||
| `frequency` | `string` | `0 3 * * *` | Opcjonalna kadencja cron dla pełnego przejścia dreaming |
|
||||
| `enabled` | `boolean` | `false` | Całkowicie włącza lub wyłącza dreaming |
|
||||
| `frequency` | `string` | `0 3 * * *` | Opcjonalna częstotliwość cron dla pełnego przebiegu dreaming |
|
||||
|
||||
### Przykład
|
||||
|
||||
@ -506,6 +516,6 @@ Aby poznać zachowanie koncepcyjne i polecenia ukośnikowe, zobacz [Dreaming](/c
|
||||
|
||||
Uwagi:
|
||||
|
||||
- Dreaming zapisuje stan maszyny do `memory/.dreams/`.
|
||||
- Dreaming zapisuje czytelne dla człowieka dane narracyjne do `DREAMS.md` (lub istniejącego `dreams.md`).
|
||||
- Polityka faz light/deep/REM i progi są zachowaniem wewnętrznym, a nie config dostępnym dla użytkownika.
|
||||
- Dreaming zapisuje stan maszyny w `memory/.dreams/`.
|
||||
- Dreaming zapisuje czytelne dla człowieka narracyjne dane wyjściowe w `DREAMS.md` (lub istniejącym `dreams.md`).
|
||||
- Zasady i progi faz light/deep/REM są zachowaniem wewnętrznym, a nie konfiguracją przeznaczoną dla użytkownika.
|
||||
|
||||
@ -1,40 +1,40 @@
|
||||
---
|
||||
read_when:
|
||||
- Dodawanie automatyzacji przeglądarki sterowanej przez agenta
|
||||
- Debugowanie, dlaczego openclaw ingeruje w Twoją własną przeglądarkę Chrome
|
||||
- Implementowanie ustawień przeglądarki i cyklu życia w aplikacji macOS
|
||||
- Debugowanie, dlaczego openclaw zakłóca działanie Twojego Chrome
|
||||
- Implementowanie ustawień i cyklu życia przeglądarki w aplikacji macOS
|
||||
summary: Zintegrowana usługa sterowania przeglądarką + polecenia akcji
|
||||
title: Browser (zarządzany przez OpenClaw)
|
||||
title: Przeglądarka (zarządzana przez OpenClaw)
|
||||
x-i18n:
|
||||
generated_at: "2026-04-05T14:09:23Z"
|
||||
generated_at: "2026-04-10T09:45:02Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: a41162efd397ea918469e16aa67e554bcbb517b3112df1d3e7927539b6a0926a
|
||||
source_hash: cd3424f62178bbf25923b8bc8e4d9f70e330f35428d01fe153574e5fa45d7604
|
||||
source_path: tools/browser.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Browser (zarządzany przez openclaw)
|
||||
# Przeglądarka (zarządzana przez openclaw)
|
||||
|
||||
OpenClaw może uruchamiać **dedykowany profil Chrome/Brave/Edge/Chromium**, którym steruje agent.
|
||||
Jest on odseparowany od Twojej osobistej przeglądarki i zarządzany przez małą lokalną
|
||||
OpenClaw może uruchamiać **dedykowany profil Chrome/Brave/Edge/Chromium**, który agent kontroluje.
|
||||
Jest on odizolowany od Twojej osobistej przeglądarki i zarządzany przez małą lokalną
|
||||
usługę sterowania wewnątrz Gateway (tylko loopback).
|
||||
|
||||
Perspektywa dla początkujących:
|
||||
Ujęcie dla początkujących:
|
||||
|
||||
- Traktuj to jak **oddzielną przeglądarkę tylko dla agenta**.
|
||||
- Potraktuj to jako **oddzielną przeglądarkę tylko dla agenta**.
|
||||
- Profil `openclaw` **nie** dotyka Twojego osobistego profilu przeglądarki.
|
||||
- Agent może **otwierać karty, czytać strony, klikać i wpisywać tekst** w bezpiecznym obszarze.
|
||||
- Wbudowany profil `user` podłącza się do Twojej prawdziwej zalogowanej sesji Chrome przez Chrome MCP.
|
||||
- Agent może **otwierać karty, odczytywać strony, klikać i wpisywać tekst** w bezpiecznej ścieżce.
|
||||
- Wbudowany profil `user` dołącza do Twojej prawdziwej zalogowanej sesji Chrome przez Chrome MCP.
|
||||
|
||||
## Co otrzymujesz
|
||||
|
||||
- Oddzielny profil przeglądarki o nazwie **openclaw** (domyślnie z pomarańczowym akcentem).
|
||||
- Deterministyczne sterowanie kartami (list/open/focus/close).
|
||||
- Akcje agenta (click/type/drag/select), snapshoty, zrzuty ekranu, PDF-y.
|
||||
- Deterministyczne sterowanie kartami (lista/otwieranie/fokus/zamykanie).
|
||||
- Akcje agenta (kliknięcie/wpisywanie/przeciąganie/zaznaczanie), snapshoty, zrzuty ekranu, pliki PDF.
|
||||
- Opcjonalną obsługę wielu profili (`openclaw`, `work`, `remote`, ...).
|
||||
|
||||
Ta przeglądarka **nie** jest Twoją codzienną przeglądarką. To bezpieczna, izolowana powierzchnia do
|
||||
Ta przeglądarka **nie** jest Twoją codzienną przeglądarką. To bezpieczna, odizolowana powierzchnia do
|
||||
automatyzacji i weryfikacji przez agenta.
|
||||
|
||||
## Szybki start
|
||||
@ -46,16 +46,16 @@ openclaw browser --browser-profile openclaw open https://example.com
|
||||
openclaw browser --browser-profile openclaw snapshot
|
||||
```
|
||||
|
||||
Jeśli pojawi się komunikat „Browser disabled”, włącz go w konfiguracji (patrz poniżej) i uruchom ponownie
|
||||
Jeśli pojawia się komunikat „Browser disabled”, włącz ją w konfiguracji (patrz niżej) i uruchom ponownie
|
||||
Gateway.
|
||||
|
||||
Jeśli całkowicie brakuje `openclaw browser`, albo agent mówi, że narzędzie browser
|
||||
jest niedostępne, przejdź do [Missing browser command or tool](/tools/browser#missing-browser-command-or-tool).
|
||||
Jeśli `openclaw browser` całkowicie nie istnieje albo agent mówi, że narzędzie przeglądarki
|
||||
jest niedostępne, przejdź do [Brak polecenia lub narzędzia browser](/pl/tools/browser#missing-browser-command-or-tool).
|
||||
|
||||
## Sterowanie pluginem
|
||||
## Sterowanie przez plugin
|
||||
|
||||
Domyślne narzędzie `browser` jest teraz dołączonym pluginem, który jest domyślnie
|
||||
włączony. Oznacza to, że możesz go wyłączyć lub zastąpić bez usuwania reszty
|
||||
Domyślne narzędzie `browser` jest teraz dołączonym pluginem, który jest
|
||||
domyślnie włączony. Oznacza to, że możesz go wyłączyć lub zastąpić bez usuwania reszty
|
||||
systemu pluginów OpenClaw:
|
||||
|
||||
```json5
|
||||
@ -71,29 +71,29 @@ systemu pluginów OpenClaw:
|
||||
```
|
||||
|
||||
Wyłącz dołączony plugin przed zainstalowaniem innego pluginu, który udostępnia
|
||||
to samo narzędzie `browser`. Domyślne działanie Browser wymaga obu warunków:
|
||||
tę samą nazwę narzędzia `browser`. Domyślne środowisko przeglądarki wymaga obu elementów:
|
||||
|
||||
- `plugins.entries.browser.enabled` nie jest wyłączone
|
||||
- `plugins.entries.browser.enabled` nie może być wyłączone
|
||||
- `browser.enabled=true`
|
||||
|
||||
Jeśli wyłączysz tylko plugin, dołączone CLI Browser (`openclaw browser`),
|
||||
metoda gateway (`browser.request`), narzędzie agenta i domyślna usługa sterowania
|
||||
Browser znikną razem. Twoja konfiguracja `browser.*` pozostaje nienaruszona, aby
|
||||
mogła zostać ponownie użyta przez plugin zastępczy.
|
||||
Jeśli wyłączysz tylko plugin, dołączone CLI przeglądarki (`openclaw browser`),
|
||||
metoda gateway (`browser.request`), narzędzie agenta i domyślna usługa sterowania przeglądarką
|
||||
znikną razem. Twoja konfiguracja `browser.*` pozostanie nienaruszona, aby mogła zostać
|
||||
ponownie użyta przez plugin zastępczy.
|
||||
|
||||
Dołączony plugin Browser jest teraz także właścicielem implementacji runtime Browser.
|
||||
Rdzeń zachowuje tylko współdzielone helpery Plugin SDK oraz re-eksporty zgodności dla
|
||||
starszych wewnętrznych ścieżek importu. W praktyce usunięcie lub zastąpienie pakietu pluginu Browser
|
||||
usuwa zestaw funkcji Browser zamiast pozostawiać drugi runtime należący do rdzenia.
|
||||
Dołączony plugin przeglądarki jest teraz również właścicielem implementacji runtime przeglądarki.
|
||||
Rdzeń zachowuje tylko współdzielone pomocniki Plugin SDK oraz re-eksporty zgodności dla
|
||||
starszych wewnętrznych ścieżek importu. W praktyce usunięcie lub zastąpienie pakietu pluginu
|
||||
przeglądarki usuwa zestaw funkcji przeglądarki zamiast pozostawiać drugi runtime należący do rdzenia.
|
||||
|
||||
Zmiany konfiguracji Browser nadal wymagają restartu Gateway, aby dołączony plugin
|
||||
mógł ponownie zarejestrować swoją usługę Browser z nowymi ustawieniami.
|
||||
Zmiany konfiguracji przeglądarki nadal wymagają ponownego uruchomienia Gateway, aby dołączony plugin
|
||||
mógł ponownie zarejestrować swoją usługę przeglądarki z nowymi ustawieniami.
|
||||
|
||||
## Brak polecenia browser lub narzędzia
|
||||
## Brak polecenia lub narzędzia browser
|
||||
|
||||
Jeśli `openclaw browser` nagle staje się nieznanym poleceniem po aktualizacji albo
|
||||
agent zgłasza brak narzędzia browser, najczęstszą przyczyną jest restrykcyjna
|
||||
lista `plugins.allow`, która nie zawiera `browser`.
|
||||
agent zgłasza brak narzędzia browser, najczęstszą przyczyną jest restrykcyjna lista
|
||||
`plugins.allow`, która nie zawiera `browser`.
|
||||
|
||||
Przykład błędnej konfiguracji:
|
||||
|
||||
@ -105,7 +105,7 @@ Przykład błędnej konfiguracji:
|
||||
}
|
||||
```
|
||||
|
||||
Napraw to, dodając `browser` do listy dozwolonych pluginów:
|
||||
Napraw to, dodając `browser` do allowlisty pluginów:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -117,34 +117,34 @@ Napraw to, dodając `browser` do listy dozwolonych pluginów:
|
||||
|
||||
Ważne uwagi:
|
||||
|
||||
- `browser.enabled=true` samo w sobie nie wystarczy, gdy ustawiono `plugins.allow`.
|
||||
- `plugins.entries.browser.enabled=true` także samo w sobie nie wystarczy, gdy ustawiono `plugins.allow`.
|
||||
- `tools.alsoAllow: ["browser"]` **nie** ładuje dołączonego pluginu Browser. Zmienia jedynie politykę narzędzi po tym, jak plugin został już załadowany.
|
||||
- Jeśli nie potrzebujesz restrykcyjnej listy dozwolonych pluginów, usunięcie `plugins.allow` także przywraca domyślne działanie dołączonego Browser.
|
||||
- `browser.enabled=true` samo w sobie nie wystarczy, gdy ustawione jest `plugins.allow`.
|
||||
- `plugins.entries.browser.enabled=true` samo w sobie również nie wystarczy, gdy ustawione jest `plugins.allow`.
|
||||
- `tools.alsoAllow: ["browser"]` **nie** ładuje dołączonego pluginu browser. To jedynie dostosowuje politykę narzędzi po tym, jak plugin został już załadowany.
|
||||
- Jeśli nie potrzebujesz restrykcyjnej allowlisty pluginów, usunięcie `plugins.allow` również przywraca domyślne zachowanie dołączonej przeglądarki.
|
||||
|
||||
Typowe objawy:
|
||||
|
||||
- `openclaw browser` jest nieznanym poleceniem.
|
||||
- brakuje `browser.request`.
|
||||
- agent zgłasza, że narzędzie browser jest niedostępne lub brakuje go.
|
||||
- Brakuje `browser.request`.
|
||||
- Agent zgłasza narzędzie browser jako niedostępne lub brakujące.
|
||||
|
||||
## Profile: `openclaw` kontra `user`
|
||||
## Profile: `openclaw` vs `user`
|
||||
|
||||
- `openclaw`: zarządzana, izolowana przeglądarka (nie wymaga rozszerzenia).
|
||||
- `user`: wbudowany profil podłączania Chrome MCP do Twojej **prawdziwej zalogowanej sesji Chrome**.
|
||||
- `openclaw`: zarządzana, odizolowana przeglądarka (nie wymaga rozszerzenia).
|
||||
- `user`: wbudowany profil dołączania Chrome MCP do Twojej **prawdziwej zalogowanej sesji Chrome**.
|
||||
|
||||
Dla wywołań narzędzia Browser przez agenta:
|
||||
Dla wywołań narzędzia przeglądarki przez agenta:
|
||||
|
||||
- Domyślnie: używaj izolowanej przeglądarki `openclaw`.
|
||||
- Preferuj `profile="user"`, gdy znaczenie mają istniejące zalogowane sesje i użytkownik
|
||||
siedzi przy komputerze, aby kliknąć/zatwierdzić ewentualny prompt podłączenia.
|
||||
- `profile` to jawne nadpisanie, gdy chcesz określony tryb przeglądarki.
|
||||
- Domyślnie: używaj odizolowanej przeglądarki `openclaw`.
|
||||
- Preferuj `profile="user"`, gdy mają znaczenie istniejące zalogowane sesje, a użytkownik
|
||||
jest przy komputerze, aby kliknąć/zatwierdzić ewentualny prompt dołączenia.
|
||||
- `profile` jest jawnym nadpisaniem, gdy chcesz konkretny tryb przeglądarki.
|
||||
|
||||
Ustaw `browser.defaultProfile: "openclaw"`, jeśli domyślnie chcesz tryb zarządzany.
|
||||
Ustaw `browser.defaultProfile: "openclaw"`, jeśli chcesz, aby domyślnie używany był tryb zarządzany.
|
||||
|
||||
## Konfiguracja
|
||||
|
||||
Ustawienia Browser znajdują się w `~/.openclaw/openclaw.json`.
|
||||
Ustawienia przeglądarki znajdują się w `~/.openclaw/openclaw.json`.
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -187,32 +187,32 @@ Ustawienia Browser znajdują się w `~/.openclaw/openclaw.json`.
|
||||
|
||||
Uwagi:
|
||||
|
||||
- Usługa sterowania Browser wiąże się z loopback na porcie wyprowadzonym z `gateway.port`
|
||||
- Usługa sterowania przeglądarką wiąże się z loopback na porcie wyprowadzonym z `gateway.port`
|
||||
(domyślnie: `18791`, czyli gateway + 2).
|
||||
- Jeśli nadpiszesz port Gateway (`gateway.port` lub `OPENCLAW_GATEWAY_PORT`),
|
||||
wyprowadzone porty Browser przesuwają się, aby pozostać w tej samej „rodzinie”.
|
||||
- `cdpUrl` domyślnie wskazuje zarządzany lokalny port CDP, jeśli nie jest ustawiony.
|
||||
- `remoteCdpTimeoutMs` dotyczy kontroli osiągalności zdalnego (nie-loopback) CDP.
|
||||
- `remoteCdpHandshakeTimeoutMs` dotyczy kontroli osiągalności handshake WebSocket zdalnego CDP.
|
||||
- Nawigacja Browser/otwieranie kart jest chronione przed SSRF przed nawigacją i ponownie sprawdzane w trybie best-effort na końcowym URL `http(s)` po nawigacji.
|
||||
- W ścisłym trybie SSRF sprawdzane są także wykrywanie/sondy zdalnych endpointów CDP (`cdpUrl`, w tym lookupi `/json/version`).
|
||||
- `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork` domyślnie ma wartość `true` (model zaufanej sieci). Ustaw `false`, aby wymusić ścisłe przeglądanie wyłącznie publiczne.
|
||||
- `browser.ssrfPolicy.allowPrivateNetwork` pozostaje obsługiwane jako starszy alias zgodności.
|
||||
- `attachOnly: true` oznacza „nigdy nie uruchamiaj lokalnej przeglądarki; tylko podłączaj się, jeśli już działa”.
|
||||
- `color` i per-profil `color` zabarwiają UI Browser, aby było widać, który profil jest aktywny.
|
||||
- Profil domyślny to `openclaw` (samodzielna przeglądarka zarządzana przez OpenClaw). Użyj `defaultProfile: "user"`, aby przejść do zalogowanej przeglądarki użytkownika.
|
||||
- Kolejność automatycznego wykrywania: domyślna systemowa przeglądarka, jeśli jest oparta na Chromium; w przeciwnym razie Chrome → Brave → Edge → Chromium → Chrome Canary.
|
||||
pochodne porty przeglądarki przesuną się tak, aby pozostać w tej samej „rodzinie”.
|
||||
- `cdpUrl` domyślnie wskazuje zarządzany lokalny port CDP, gdy nie jest ustawione.
|
||||
- `remoteCdpTimeoutMs` dotyczy kontroli osiągalności zdalnego (nie-loopbackowego) CDP.
|
||||
- `remoteCdpHandshakeTimeoutMs` dotyczy kontroli osiągalności handshaku WebSocket dla zdalnego CDP.
|
||||
- Nawigacja przeglądarki/otwieranie kart jest chronione przed SSRF przed nawigacją i w miarę możliwości sprawdzane ponownie dla końcowego adresu `http(s)` po nawigacji.
|
||||
- W ścisłym trybie SSRF zdalne wykrywanie/sondowanie endpointów CDP (`cdpUrl`, w tym wyszukiwania `/json/version`) również są sprawdzane.
|
||||
- `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork` domyślnie ma wartość `true` (model zaufanej sieci). Ustaw `false`, aby wymusić ścisłe przeglądanie tylko publicznych zasobów.
|
||||
- `browser.ssrfPolicy.allowPrivateNetwork` pozostaje obsługiwane jako starszy alias dla zgodności.
|
||||
- `attachOnly: true` oznacza „nigdy nie uruchamiaj lokalnej przeglądarki; dołączaj tylko wtedy, gdy już działa”.
|
||||
- `color` oraz `color` dla poszczególnych profili nadają interfejsowi przeglądarki kolor, dzięki czemu widać, który profil jest aktywny.
|
||||
- Domyślny profil to `openclaw` (samodzielna przeglądarka zarządzana przez OpenClaw). Użyj `defaultProfile: "user"`, aby przejść na zalogowaną przeglądarkę użytkownika.
|
||||
- Kolejność automatycznego wykrywania: domyślna przeglądarka systemowa, jeśli jest oparta na Chromium; w przeciwnym razie Chrome → Brave → Edge → Chromium → Chrome Canary.
|
||||
- Lokalne profile `openclaw` automatycznie przypisują `cdpPort`/`cdpUrl` — ustawiaj je tylko dla zdalnego CDP.
|
||||
- `driver: "existing-session"` używa Chrome DevTools MCP zamiast surowego CDP. Nie
|
||||
ustawiaj `cdpUrl` dla tego sterownika.
|
||||
- Ustaw `browser.profiles.<name>.userDataDir`, gdy profil existing-session
|
||||
ma podłączać się do niestandardowego profilu użytkownika Chromium, takiego jak Brave lub Edge.
|
||||
ma dołączać do niestandardowego profilu użytkownika Chromium, takiego jak Brave lub Edge.
|
||||
|
||||
## Używanie Brave (lub innej przeglądarki opartej na Chromium)
|
||||
|
||||
Jeśli Twoją **domyślną systemową** przeglądarką jest przeglądarka oparta na Chromium (Chrome/Brave/Edge itd.),
|
||||
OpenClaw użyje jej automatycznie. Ustaw `browser.executablePath`, aby nadpisać
|
||||
autowykrywanie:
|
||||
Jeśli Twoja **domyślna przeglądarka systemowa** jest oparta na Chromium (Chrome/Brave/Edge itd.),
|
||||
OpenClaw używa jej automatycznie. Ustaw `browser.executablePath`, aby nadpisać
|
||||
automatyczne wykrywanie:
|
||||
|
||||
Przykład CLI:
|
||||
|
||||
@ -243,52 +243,52 @@ openclaw config set browser.executablePath "/usr/bin/google-chrome"
|
||||
}
|
||||
```
|
||||
|
||||
## Sterowanie lokalne a zdalne
|
||||
## Sterowanie lokalne vs zdalne
|
||||
|
||||
- **Sterowanie lokalne (domyślne):** Gateway uruchamia usługę sterowania loopback i może uruchomić lokalną przeglądarkę.
|
||||
- **Sterowanie zdalne (host węzła):** uruchom hosta węzła na komputerze, który ma przeglądarkę; Gateway będzie proxy'ować do niego akcje Browser.
|
||||
- **Zdalne CDP:** ustaw `browser.profiles.<name>.cdpUrl` (lub `browser.cdpUrl`), aby
|
||||
podłączyć się do zdalnej przeglądarki opartej na Chromium. W takim przypadku OpenClaw nie uruchomi lokalnej przeglądarki.
|
||||
- **Sterowanie zdalne (host węzła):** uruchom host węzła na komputerze, na którym znajduje się przeglądarka; Gateway będzie proxyfikować do niego akcje przeglądarki.
|
||||
- **Zdalny CDP:** ustaw `browser.profiles.<name>.cdpUrl` (lub `browser.cdpUrl`), aby
|
||||
dołączyć do zdalnej przeglądarki opartej na Chromium. W takim przypadku OpenClaw nie uruchomi lokalnej przeglądarki.
|
||||
|
||||
Zachowanie zatrzymywania różni się zależnie od trybu profilu:
|
||||
Zachowanie przy zatrzymywaniu różni się w zależności od trybu profilu:
|
||||
|
||||
- lokalne profile zarządzane: `openclaw browser stop` zatrzymuje proces przeglądarki, który
|
||||
uruchomił OpenClaw
|
||||
- profile attach-only i zdalnego CDP: `openclaw browser stop` zamyka aktywną
|
||||
sesję sterowania i usuwa nadpisania emulacji Playwright/CDP (viewport,
|
||||
schemat kolorów, locale, timezone, tryb offline i podobny stan), mimo że
|
||||
OpenClaw nie uruchomił żadnego procesu Browser
|
||||
został uruchomiony przez OpenClaw
|
||||
- profile tylko-dołączane i zdalne profile CDP: `openclaw browser stop` zamyka aktywną
|
||||
sesję sterowania i zwalnia nadpisania emulacji Playwright/CDP (viewport,
|
||||
schemat kolorów, locale, strefę czasową, tryb offline i podobny stan), nawet
|
||||
jeśli żaden proces przeglądarki nie został uruchomiony przez OpenClaw
|
||||
|
||||
Zdalne URL-e CDP mogą zawierać auth:
|
||||
Zdalne adresy URL CDP mogą zawierać uwierzytelnianie:
|
||||
|
||||
- tokeny query (np. `https://provider.example?token=<token>`)
|
||||
- auth HTTP Basic (np. `https://user:pass@provider.example`)
|
||||
- Tokeny w query (np. `https://provider.example?token=<token>`)
|
||||
- Uwierzytelnianie HTTP Basic (np. `https://user:pass@provider.example`)
|
||||
|
||||
OpenClaw zachowuje auth przy wywoływaniu endpointów `/json/*` i przy łączeniu
|
||||
z WebSocket CDP. Preferuj zmienne środowiskowe lub menedżery sekretów dla
|
||||
tokenów zamiast commitować je do plików konfiguracji.
|
||||
OpenClaw zachowuje uwierzytelnianie przy wywoływaniu endpointów `/json/*` oraz podczas łączenia
|
||||
z WebSocketem CDP. Preferuj zmienne środowiskowe lub menedżery sekretów dla
|
||||
tokenów zamiast commitowania ich do plików konfiguracji.
|
||||
|
||||
## Proxy Browser dla węzłów (domyślnie zero konfiguracji)
|
||||
## Proxy przeglądarki węzła (domyślnie zero konfiguracji)
|
||||
|
||||
Jeśli uruchamiasz **hosta węzła** na komputerze, który ma Browser, OpenClaw może
|
||||
automatycznie kierować wywołania narzędzia Browser do tego węzła bez żadnej dodatkowej konfiguracji Browser.
|
||||
To domyślna ścieżka dla zdalnych gateway.
|
||||
Jeśli uruchamiasz **host węzła** na komputerze, który ma Twoją przeglądarkę, OpenClaw może
|
||||
automatycznie kierować wywołania narzędzia przeglądarki do tego węzła bez żadnej dodatkowej konfiguracji przeglądarki.
|
||||
To domyślna ścieżka dla zdalnych gatewayów.
|
||||
|
||||
Uwagi:
|
||||
|
||||
- Host węzła udostępnia swoją lokalną usługę sterowania Browser przez **polecenie proxy**.
|
||||
- Profile pochodzą z własnej konfiguracji węzła `browser.profiles` (takiej samej jak lokalnie).
|
||||
- `nodeHost.browserProxy.allowProfiles` jest opcjonalne. Pozostaw puste dla starszego/domyslnego zachowania: wszystkie skonfigurowane profile pozostają osiągalne przez proxy, w tym trasy tworzenia/usuwania profili.
|
||||
- Jeśli ustawisz `nodeHost.browserProxy.allowProfiles`, OpenClaw potraktuje to jako granicę minimalnych uprawnień: można kierować tylko do profili z listy dozwolonych, a trwałe trasy tworzenia/usuwania profili są blokowane na powierzchni proxy.
|
||||
- Wyłącz, jeśli tego nie chcesz:
|
||||
- Host węzła udostępnia swój lokalny serwer sterowania przeglądarką przez **polecenie proxy**.
|
||||
- Profile pochodzą z własnej konfiguracji `browser.profiles` węzła (takiej samej jak lokalnie).
|
||||
- `nodeHost.browserProxy.allowProfiles` jest opcjonalne. Pozostaw puste dla starszego/dom yślnego zachowania: wszystkie skonfigurowane profile pozostają dostępne przez proxy, łącznie z trasami tworzenia/usuwania profili.
|
||||
- Jeśli ustawisz `nodeHost.browserProxy.allowProfiles`, OpenClaw potraktuje to jako granicę minimalnych uprawnień: tylko profile z allowlisty mogą być celem, a trasy tworzenia/usuwania trwałych profili są blokowane na powierzchni proxy.
|
||||
- Wyłącz to, jeśli nie chcesz z tego korzystać:
|
||||
- Na węźle: `nodeHost.browserProxy.enabled=false`
|
||||
- Na gateway: `gateway.nodes.browser.mode="off"`
|
||||
|
||||
## Browserless (hostowany zdalny CDP)
|
||||
|
||||
[Browserless](https://browserless.io) to hostowana usługa Chromium, która udostępnia
|
||||
URL-e połączeń CDP przez HTTPS i WebSocket. OpenClaw może używać obu form, ale
|
||||
dla zdalnego profilu Browser najprostszą opcją jest bezpośredni URL WebSocket
|
||||
adresy URL połączeń CDP przez HTTPS i WebSocket. OpenClaw może używać obu form, ale
|
||||
dla zdalnego profilu przeglądarki najprostszą opcją jest bezpośredni adres WebSocket URL
|
||||
z dokumentacji połączeń Browserless.
|
||||
|
||||
Przykład:
|
||||
@ -312,30 +312,30 @@ Przykład:
|
||||
|
||||
Uwagi:
|
||||
|
||||
- Zastąp `<BROWSERLESS_API_KEY>` swoim prawdziwym tokenem Browserless.
|
||||
- Wybierz endpoint regionu odpowiadający Twojemu kontu Browserless (zobacz ich dokumentację).
|
||||
- Jeśli Browserless daje Ci bazowy URL HTTPS, możesz albo przekształcić go do
|
||||
`wss://` dla bezpośredniego połączenia CDP, albo pozostawić URL HTTPS i pozwolić OpenClaw
|
||||
- Zastąp `<BROWSERLESS_API_KEY>` swoim rzeczywistym tokenem Browserless.
|
||||
- Wybierz endpoint regionu zgodny z Twoim kontem Browserless (zobacz ich dokumentację).
|
||||
- Jeśli Browserless podaje bazowy adres HTTPS URL, możesz albo przekonwertować go na
|
||||
`wss://` dla bezpośredniego połączenia CDP, albo pozostawić adres HTTPS URL i pozwolić OpenClaw
|
||||
wykryć `/json/version`.
|
||||
|
||||
## Dostawcy bezpośredniego WebSocket CDP
|
||||
## Bezpośredni dostawcy WebSocket CDP
|
||||
|
||||
Niektóre hostowane usługi Browser udostępniają **bezpośredni endpoint WebSocket** zamiast
|
||||
standardowego wykrywania CDP opartego na HTTP (`/json/version`). OpenClaw obsługuje oba warianty:
|
||||
Niektóre hostowane usługi przeglądarki udostępniają **bezpośredni endpoint WebSocket**
|
||||
zamiast standardowego wykrywania CDP opartego na HTTP (`/json/version`). OpenClaw obsługuje oba tryby:
|
||||
|
||||
- **Endpointy HTTP(S)** — OpenClaw wywołuje `/json/version`, aby wykryć
|
||||
URL WebSocket debuggera, a następnie się łączy.
|
||||
adres URL debuggera WebSocket, a następnie się łączy.
|
||||
- **Endpointy WebSocket** (`ws://` / `wss://`) — OpenClaw łączy się bezpośrednio,
|
||||
pomijając `/json/version`. Użyj tego dla usług takich jak
|
||||
pomijając `/json/version`. Używaj tego w przypadku usług takich jak
|
||||
[Browserless](https://browserless.io),
|
||||
[Browserbase](https://www.browserbase.com) albo dowolnego dostawcy, który przekazuje Ci
|
||||
URL WebSocket.
|
||||
[Browserbase](https://www.browserbase.com) lub dowolnego dostawcy, który przekazuje Ci
|
||||
adres URL WebSocket.
|
||||
|
||||
### Browserbase
|
||||
|
||||
[Browserbase](https://www.browserbase.com) to chmurowa platforma do uruchamiania
|
||||
bezgłowych przeglądarek z wbudowanym rozwiązywaniem CAPTCHA, trybem stealth i
|
||||
proxy rezydencyjnymi.
|
||||
[Browserbase](https://www.browserbase.com) to platforma chmurowa do uruchamiania
|
||||
przeglądarek headless z wbudowanym rozwiązywaniem CAPTCHA, trybem stealth i
|
||||
rezydencyjnymi proxy.
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -357,61 +357,62 @@ proxy rezydencyjnymi.
|
||||
Uwagi:
|
||||
|
||||
- [Zarejestruj się](https://www.browserbase.com/sign-up) i skopiuj swój **API Key**
|
||||
z [dashboardu Overview](https://www.browserbase.com/overview).
|
||||
- Zastąp `<BROWSERBASE_API_KEY>` swoim prawdziwym kluczem API Browserbase.
|
||||
- Browserbase automatycznie tworzy sesję Browser przy połączeniu WebSocket, więc nie
|
||||
jest potrzebny ręczny krok tworzenia sesji.
|
||||
- Darmowa warstwa pozwala na jedną sesję współbieżną i jedną godzinę Browser miesięcznie.
|
||||
Limity płatnych planów znajdziesz w [cenniku](https://www.browserbase.com/pricing).
|
||||
- Pełne API reference, przewodniki SDK i przykłady integracji znajdziesz w [dokumentacji Browserbase](https://docs.browserbase.com).
|
||||
z [panelu Overview](https://www.browserbase.com/overview).
|
||||
- Zastąp `<BROWSERBASE_API_KEY>` swoim rzeczywistym kluczem API Browserbase.
|
||||
- Browserbase automatycznie tworzy sesję przeglądarki przy połączeniu WebSocket, więc
|
||||
nie jest potrzebny ręczny krok tworzenia sesji.
|
||||
- Warstwa darmowa pozwala na jedną współbieżną sesję i jedną godzinę przeglądarki miesięcznie.
|
||||
Zobacz [cennik](https://www.browserbase.com/pricing), aby poznać limity planów płatnych.
|
||||
- Zobacz [dokumentację Browserbase](https://docs.browserbase.com), aby uzyskać pełne
|
||||
odniesienie do API, przewodniki po SDK i przykłady integracji.
|
||||
|
||||
## Bezpieczeństwo
|
||||
|
||||
Kluczowe założenia:
|
||||
|
||||
- Sterowanie Browser działa tylko na loopback; dostęp przechodzi przez auth Gateway lub parowanie węzłów.
|
||||
- Samodzielne loopback HTTP API Browser używa **wyłącznie auth współdzielonym sekretem**:
|
||||
bearer auth tokenem gateway, `x-openclaw-password` albo HTTP Basic auth ze
|
||||
- Sterowanie przeglądarką działa tylko przez loopback; dostęp przechodzi przez uwierzytelnianie Gateway lub parowanie węzłów.
|
||||
- Samodzielne loopbackowe API HTTP przeglądarki używa **wyłącznie uwierzytelniania wspólnym sekretem**:
|
||||
auth bearer tokenem gateway, `x-openclaw-password` lub HTTP Basic auth z
|
||||
skonfigurowanym hasłem gateway.
|
||||
- Nagłówki tożsamości Tailscale Serve i `gateway.auth.mode: "trusted-proxy"` **nie**
|
||||
uwierzytelniają tego samodzielnego loopback API Browser.
|
||||
- Jeśli sterowanie Browser jest włączone i nie skonfigurowano auth współdzielonym sekretem, OpenClaw
|
||||
automatycznie generuje `gateway.auth.token` przy starcie i utrwala go w konfiguracji.
|
||||
- OpenClaw **nie** generuje automatycznie tego tokena, gdy `gateway.auth.mode` ma już wartość
|
||||
- Nagłówki tożsamości Tailscale Serve i `gateway.auth.mode: "trusted-proxy"`
|
||||
**nie** uwierzytelniają tego samodzielnego loopbackowego API przeglądarki.
|
||||
- Jeśli sterowanie przeglądarką jest włączone i nie skonfigurowano uwierzytelniania wspólnym sekretem, OpenClaw
|
||||
automatycznie generuje `gateway.auth.token` przy uruchomieniu i zapisuje go w konfiguracji.
|
||||
- OpenClaw **nie** generuje automatycznie tego tokenu, gdy `gateway.auth.mode` jest już ustawione na
|
||||
`password`, `none` lub `trusted-proxy`.
|
||||
- Utrzymuj Gateway i wszystkie hosty węzłów w prywatnej sieci (Tailscale); unikaj wystawiania publicznego.
|
||||
- Traktuj zdalne URL-e/tokeny CDP jako sekrety; preferuj zmienne env albo menedżer sekretów.
|
||||
- Utrzymuj Gateway i wszelkie hosty węzłów w sieci prywatnej (Tailscale); unikaj publicznej ekspozycji.
|
||||
- Traktuj zdalne adresy URL/tokeny CDP jako sekrety; preferuj zmienne env lub menedżer sekretów.
|
||||
|
||||
Wskazówki dla zdalnego CDP:
|
||||
Wskazówki dotyczące zdalnego CDP:
|
||||
|
||||
- Jeśli to możliwe, preferuj szyfrowane endpointy (HTTPS lub WSS) i tokeny krótkotrwałe.
|
||||
- Unikaj osadzania długowiecznych tokenów bezpośrednio w plikach konfiguracji.
|
||||
- W miarę możliwości preferuj szyfrowane endpointy (HTTPS lub WSS) i tokeny krótkotrwałe.
|
||||
- Unikaj osadzania długotrwałych tokenów bezpośrednio w plikach konfiguracyjnych.
|
||||
|
||||
## Profile (wiele przeglądarek)
|
||||
|
||||
OpenClaw obsługuje wiele nazwanych profili (konfiguracji routingu). Profile mogą być:
|
||||
|
||||
- **zarządzane przez openclaw**: dedykowana przeglądarka oparta na Chromium z własnym katalogiem danych użytkownika + portem CDP
|
||||
- **zdalne**: jawny URL CDP (przeglądarka oparta na Chromium uruchomiona gdzie indziej)
|
||||
- **istniejąca sesja**: Twój istniejący profil Chrome przez automatyczne połączenie Chrome DevTools MCP
|
||||
- **zarządzane przez openclaw**: dedykowana instancja przeglądarki opartej na Chromium z własnym katalogiem danych użytkownika i portem CDP
|
||||
- **zdalne**: jawny adres URL CDP (przeglądarka oparta na Chromium uruchomiona gdzie indziej)
|
||||
- **istniejąca sesja**: Twój istniejący profil Chrome przez auto-połączenie Chrome DevTools MCP
|
||||
|
||||
Wartości domyślne:
|
||||
Domyślne ustawienia:
|
||||
|
||||
- Profil `openclaw` jest tworzony automatycznie, jeśli go brakuje.
|
||||
- Profil `user` jest wbudowany dla podłączania existing-session Chrome MCP.
|
||||
- Profile existing-session poza `user` są opt-in; twórz je przy użyciu `--driver existing-session`.
|
||||
- Profil `user` jest wbudowany dla dołączania do istniejącej sesji Chrome MCP.
|
||||
- Profile istniejących sesji poza `user` są opcjonalne; twórz je za pomocą `--driver existing-session`.
|
||||
- Lokalne porty CDP są domyślnie przydzielane z zakresu **18800–18899**.
|
||||
- Usunięcie profilu przenosi jego lokalny katalog danych do Kosza.
|
||||
|
||||
Wszystkie endpointy sterowania akceptują `?profile=<name>`; CLI używa `--browser-profile`.
|
||||
|
||||
## Existing-session przez Chrome DevTools MCP
|
||||
## Istniejąca sesja przez Chrome DevTools MCP
|
||||
|
||||
OpenClaw może także podłączyć się do uruchomionego profilu przeglądarki opartej na Chromium przez
|
||||
oficjalny serwer Chrome DevTools MCP. Pozwala to ponownie używać kart i stanu logowania
|
||||
już otwartych w tym profilu Browser.
|
||||
OpenClaw może również dołączyć do działającego profilu przeglądarki opartej na Chromium przez
|
||||
oficjalny serwer Chrome DevTools MCP. Pozwala to ponownie wykorzystać karty i stan logowania
|
||||
już otwarte w tym profilu przeglądarki.
|
||||
|
||||
Oficjalne tło i dokumentacja konfiguracji:
|
||||
Oficjalne materiały wprowadzające i referencje konfiguracyjne:
|
||||
|
||||
- [Chrome for Developers: Use Chrome DevTools MCP with your browser session](https://developer.chrome.com/blog/chrome-devtools-mcp-debug-your-browser-session)
|
||||
- [Chrome DevTools MCP README](https://github.com/ChromeDevTools/chrome-devtools-mcp)
|
||||
@ -421,14 +422,14 @@ Wbudowany profil:
|
||||
- `user`
|
||||
|
||||
Opcjonalnie: utwórz własny niestandardowy profil existing-session, jeśli chcesz inną
|
||||
nazwę, kolor lub katalog danych Browser.
|
||||
nazwę, kolor lub katalog danych przeglądarki.
|
||||
|
||||
Domyślne zachowanie:
|
||||
Zachowanie domyślne:
|
||||
|
||||
- Wbudowany profil `user` używa automatycznego połączenia Chrome MCP, które kieruje do
|
||||
- Wbudowany profil `user` używa auto-połączenia Chrome MCP, które jest kierowane do
|
||||
domyślnego lokalnego profilu Google Chrome.
|
||||
|
||||
Używaj `userDataDir` dla Brave, Edge, Chromium lub niestandardowego profilu Chrome:
|
||||
Użyj `userDataDir` dla Brave, Edge, Chromium lub niestandardowego profilu Chrome:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -445,19 +446,19 @@ Używaj `userDataDir` dla Brave, Edge, Chromium lub niestandardowego profilu Chr
|
||||
}
|
||||
```
|
||||
|
||||
Następnie w odpowiedniej przeglądarce:
|
||||
Następnie w odpowiadającej przeglądarce:
|
||||
|
||||
1. Otwórz stronę inspect tej przeglądarki dla zdalnego debugowania.
|
||||
1. Otwórz stronę inspekcji tej przeglądarki dla zdalnego debugowania.
|
||||
2. Włącz zdalne debugowanie.
|
||||
3. Utrzymuj Browser uruchomioną i zatwierdź prompt połączenia, gdy OpenClaw się podłączy.
|
||||
3. Pozostaw przeglądarkę uruchomioną i zatwierdź prompt połączenia, gdy OpenClaw się dołączy.
|
||||
|
||||
Typowe strony inspect:
|
||||
Typowe strony inspekcji:
|
||||
|
||||
- Chrome: `chrome://inspect/#remote-debugging`
|
||||
- Brave: `brave://inspect/#remote-debugging`
|
||||
- Edge: `edge://inspect/#remote-debugging`
|
||||
|
||||
Test smoke aktywnego podłączenia:
|
||||
Test smoke dla live attach:
|
||||
|
||||
```bash
|
||||
openclaw browser --browser-profile user start
|
||||
@ -471,65 +472,67 @@ Jak wygląda powodzenie:
|
||||
- `status` pokazuje `driver: existing-session`
|
||||
- `status` pokazuje `transport: chrome-mcp`
|
||||
- `status` pokazuje `running: true`
|
||||
- `tabs` wyświetla już otwarte karty Browser
|
||||
- `snapshot` zwraca refs z wybranej aktywnej karty
|
||||
- `tabs` wyświetla listę już otwartych kart przeglądarki
|
||||
- `snapshot` zwraca refy z wybranej aktywnej karty
|
||||
|
||||
Co sprawdzić, jeśli podłączenie nie działa:
|
||||
Co sprawdzić, jeśli dołączenie nie działa:
|
||||
|
||||
- docelowa przeglądarka oparta na Chromium ma wersję `144+`
|
||||
- zdalne debugowanie jest włączone na stronie inspect tej przeglądarki
|
||||
- Browser wyświetliła prompt zgody na podłączenie i został on zaakceptowany
|
||||
- `openclaw doctor` migruje stare konfiguracje Browser oparte na rozszerzeniach i sprawdza,
|
||||
czy Chrome jest lokalnie zainstalowane dla domyślnych profili auto-connect, ale nie może
|
||||
włączyć po Twojej stronie zdalnego debugowania w Browser
|
||||
- zdalne debugowanie jest włączone na stronie inspekcji tej przeglądarki
|
||||
- przeglądarka wyświetliła prompt zgody na dołączenie i został on zaakceptowany
|
||||
- `openclaw doctor` migruje starą konfigurację przeglądarki opartą na rozszerzeniu i sprawdza, czy
|
||||
Chrome jest zainstalowany lokalnie dla domyślnych profili auto-połączenia, ale nie może
|
||||
włączyć po Twojej stronie zdalnego debugowania w przeglądarce
|
||||
|
||||
Użycie przez agenta:
|
||||
|
||||
- Używaj `profile="user"`, gdy potrzebujesz zalogowanego stanu Browser użytkownika.
|
||||
- Jeśli używasz niestandardowego profilu existing-session, przekaż jego jawną nazwę.
|
||||
- Wybieraj ten tryb tylko wtedy, gdy użytkownik siedzi przy komputerze, aby zatwierdzić prompt podłączenia.
|
||||
- Użyj `profile="user"`, gdy potrzebujesz stanu zalogowanej przeglądarki użytkownika.
|
||||
- Jeśli używasz niestandardowego profilu existing-session, przekaż jawną nazwę tego profilu.
|
||||
- Wybieraj ten tryb tylko wtedy, gdy użytkownik jest przy komputerze, aby zatwierdzić
|
||||
prompt dołączenia.
|
||||
- Gateway lub host węzła może uruchomić `npx chrome-devtools-mcp@latest --autoConnect`
|
||||
|
||||
Uwagi:
|
||||
|
||||
- Ta ścieżka jest bardziej ryzykowna niż izolowany profil `openclaw`, ponieważ może
|
||||
działać wewnątrz Twojej zalogowanej sesji Browser.
|
||||
- OpenClaw nie uruchamia Browser dla tego sterownika; podłącza się tylko do
|
||||
- Ta ścieżka jest bardziej ryzykowna niż odizolowany profil `openclaw`, ponieważ może
|
||||
działać wewnątrz Twojej zalogowanej sesji przeglądarki.
|
||||
- OpenClaw nie uruchamia przeglądarki dla tego sterownika; dołącza tylko do
|
||||
istniejącej sesji.
|
||||
- OpenClaw używa tu oficjalnego przepływu Chrome DevTools MCP `--autoConnect`. Jeśli
|
||||
ustawiono `userDataDir`, OpenClaw przekaże je dalej, aby wskazać ten jawny
|
||||
katalog danych użytkownika Chromium.
|
||||
- Zrzuty ekranu existing-session obsługują przechwytywanie całych stron i przechwytywanie elementów `--ref` ze snapshotów, ale nie selektory CSS `--element`.
|
||||
- Zrzuty ekranu stron existing-session działają bez Playwright przez Chrome MCP.
|
||||
Oparte na ref zrzuty ekranów elementów (`--ref`) także tam działają, ale `--full-page`
|
||||
- OpenClaw używa tutaj oficjalnego przepływu `--autoConnect` Chrome DevTools MCP. Jeśli
|
||||
ustawiono `userDataDir`, OpenClaw przekazuje je dalej, aby kierować do tego jawnego
|
||||
katalogu danych użytkownika Chromium.
|
||||
- Zrzuty ekranu existing-session obsługują przechwycenia strony i przechwycenia elementów `--ref`
|
||||
ze snapshotów, ale nie selektory CSS `--element`.
|
||||
- Zrzuty ekranu strony existing-session działają bez Playwright przez Chrome MCP.
|
||||
Zrzuty ekranów elementów oparte na refach (`--ref`) także tam działają, ale `--full-page`
|
||||
nie może być łączone z `--ref` ani `--element`.
|
||||
- Akcje existing-session są nadal bardziej ograniczone niż ścieżka
|
||||
zarządzanej Browser:
|
||||
zarządzanej przeglądarki:
|
||||
- `click`, `type`, `hover`, `scrollIntoView`, `drag` i `select` wymagają
|
||||
refów snapshotu zamiast selektorów CSS
|
||||
- `click` obsługuje tylko lewy przycisk (bez nadpisywania przycisku i modyfikatorów)
|
||||
- `type` nie obsługuje `slowly=true`; używaj `fill` albo `press`
|
||||
refów ze snapshotów zamiast selektorów CSS
|
||||
- `click` obsługuje tylko lewy przycisk myszy (bez nadpisywania przycisku ani modyfikatorów)
|
||||
- `type` nie obsługuje `slowly=true`; użyj `fill` lub `press`
|
||||
- `press` nie obsługuje `delayMs`
|
||||
- `hover`, `scrollIntoView`, `drag`, `select`, `fill` i `evaluate` nie
|
||||
obsługują nadpisań timeout per wywołanie
|
||||
- `select` obecnie obsługuje tylko pojedynczą wartość
|
||||
- Existing-session `wait --url` obsługuje wzorce exact, substring i glob
|
||||
tak jak inne sterowniki Browser. `wait --load networkidle` nie jest jeszcze obsługiwane.
|
||||
- Hooki upload existing-session wymagają `ref` lub `inputRef`, obsługują jeden plik na raz
|
||||
i nie obsługują kierowania do `element` przez CSS.
|
||||
- Hooki dialog existing-session nie obsługują nadpisań timeout.
|
||||
- Niektóre funkcje nadal wymagają ścieżki zarządzanej Browser, w tym batch
|
||||
actions, eksport PDF, przechwytywanie pobrań i `responsebody`.
|
||||
- Existing-session jest lokalne względem hosta. Jeśli Chrome znajduje się na innym komputerze lub
|
||||
w innej przestrzeni nazw sieci, użyj zdalnego CDP albo hosta węzła.
|
||||
obsługują nadpisywania timeoutów dla pojedynczego wywołania
|
||||
- `select` obecnie obsługuje tylko jedną wartość
|
||||
- Existing-session `wait --url` obsługuje wzorce dokładne, podciągi i globy
|
||||
tak jak inne sterowniki przeglądarki. `wait --load networkidle` nie jest jeszcze obsługiwane.
|
||||
- Hooki uploadu existing-session wymagają `ref` lub `inputRef`, obsługują po jednym pliku naraz
|
||||
i nie obsługują kierowania przez CSS `element`.
|
||||
- Hooki dialogów existing-session nie obsługują nadpisywania timeoutów.
|
||||
- Niektóre funkcje nadal wymagają ścieżki zarządzanej przeglądarki, w tym
|
||||
akcje wsadowe, eksport PDF, przechwytywanie pobrań i `responsebody`.
|
||||
- Existing-session jest lokalne względem hosta. Jeśli Chrome działa na innej maszynie lub w
|
||||
innej przestrzeni nazw sieci, użyj zamiast tego zdalnego CDP lub hosta węzła.
|
||||
|
||||
## Gwarancje izolacji
|
||||
|
||||
- **Dedykowany katalog danych użytkownika**: nigdy nie dotyka Twojego osobistego profilu Browser.
|
||||
- **Dedykowane porty**: unika `9222`, aby zapobiec kolizjom z przepływami deweloperskimi.
|
||||
- **Deterministyczne sterowanie kartami**: karty są wskazywane przez `targetId`, a nie „ostatnia karta”.
|
||||
- **Dedykowany katalog danych użytkownika**: nigdy nie dotyka Twojego osobistego profilu przeglądarki.
|
||||
- **Dedykowane porty**: unika `9222`, aby zapobiegać kolizjom z przepływami pracy deweloperskiej.
|
||||
- **Deterministyczne sterowanie kartami**: kierowanie na karty przez `targetId`, a nie „ostatnią kartę”.
|
||||
|
||||
## Wybór Browser
|
||||
## Wybór przeglądarki
|
||||
|
||||
Przy lokalnym uruchamianiu OpenClaw wybiera pierwszą dostępną:
|
||||
|
||||
@ -549,14 +552,14 @@ Platformy:
|
||||
|
||||
## API sterowania (opcjonalne)
|
||||
|
||||
Tylko dla integracji lokalnych Gateway udostępnia małe loopback HTTP API:
|
||||
Tylko dla integracji lokalnych, Gateway udostępnia niewielkie loopbackowe API HTTP:
|
||||
|
||||
- Status/start/stop: `GET /`, `POST /start`, `POST /stop`
|
||||
- Karty: `GET /tabs`, `POST /tabs/open`, `POST /tabs/focus`, `DELETE /tabs/:targetId`
|
||||
- Snapshot/zrzut ekranu: `GET /snapshot`, `POST /screenshot`
|
||||
- Akcje: `POST /navigate`, `POST /act`
|
||||
- Hooki: `POST /hooks/file-chooser`, `POST /hooks/dialog`
|
||||
- Pobrania: `POST /download`, `POST /wait/download`
|
||||
- Pobieranie: `POST /download`, `POST /wait/download`
|
||||
- Debugowanie: `GET /console`, `POST /pdf`
|
||||
- Debugowanie: `GET /errors`, `GET /requests`, `POST /trace/start`, `POST /trace/stop`, `POST /highlight`
|
||||
- Sieć: `POST /response/body`
|
||||
@ -566,17 +569,38 @@ Tylko dla integracji lokalnych Gateway udostępnia małe loopback HTTP API:
|
||||
|
||||
Wszystkie endpointy akceptują `?profile=<name>`.
|
||||
|
||||
Jeśli skonfigurowano auth gateway współdzielonym sekretem, trasy HTTP Browser także wymagają auth:
|
||||
Jeśli skonfigurowano uwierzytelnianie gateway wspólnym sekretem, trasy HTTP przeglądarki również wymagają uwierzytelnienia:
|
||||
|
||||
- `Authorization: Bearer <gateway token>`
|
||||
- `x-openclaw-password: <gateway password>` albo HTTP Basic auth z tym hasłem
|
||||
- `x-openclaw-password: <gateway password>` lub HTTP Basic auth z tym hasłem
|
||||
|
||||
Uwagi:
|
||||
|
||||
- To samodzielne loopback API Browser **nie** korzysta z trusted-proxy ani
|
||||
nagłówków tożsamości Tailscale Serve.
|
||||
- Jeśli `gateway.auth.mode` ma wartość `none` albo `trusted-proxy`, te loopbackowe trasy Browser
|
||||
nie dziedziczą tych trybów opartych na tożsamości; utrzymuj je tylko na loopback.
|
||||
- To samodzielne loopbackowe API przeglądarki **nie** używa nagłówków trusted-proxy ani
|
||||
tożsamości Tailscale Serve.
|
||||
- Jeśli `gateway.auth.mode` ma wartość `none` lub `trusted-proxy`, te loopbackowe trasy przeglądarki
|
||||
nie dziedziczą tych trybów opartych na tożsamości; utrzymuj je wyłącznie na loopback.
|
||||
|
||||
### Kontrakt błędów `/act`
|
||||
|
||||
`POST /act` używa ustrukturyzowanej odpowiedzi błędu dla walidacji na poziomie trasy i
|
||||
błędów polityki:
|
||||
|
||||
```json
|
||||
{ "error": "<message>", "code": "ACT_*" }
|
||||
```
|
||||
|
||||
Obecne wartości `code`:
|
||||
|
||||
- `ACT_KIND_REQUIRED` (HTTP 400): brakuje `kind` lub nie został rozpoznany.
|
||||
- `ACT_INVALID_REQUEST` (HTTP 400): payload akcji nie przeszedł normalizacji lub walidacji.
|
||||
- `ACT_SELECTOR_UNSUPPORTED` (HTTP 400): użyto `selector` z nieobsługiwanym rodzajem akcji.
|
||||
- `ACT_EVALUATE_DISABLED` (HTTP 403): `evaluate` (lub `wait --fn`) jest wyłączone w konfiguracji.
|
||||
- `ACT_TARGET_ID_MISMATCH` (HTTP 403): najwyższego poziomu lub wsadowe `targetId` koliduje z celem żądania.
|
||||
- `ACT_EXISTING_SESSION_UNSUPPORTED` (HTTP 501): akcja nie jest obsługiwana dla profili existing-session.
|
||||
|
||||
Inne błędy runtime nadal mogą zwracać `{ "error": "<message>" }` bez pola
|
||||
`code`.
|
||||
|
||||
### Wymaganie Playwright
|
||||
|
||||
@ -586,58 +610,58 @@ czytelny błąd 501.
|
||||
|
||||
Co nadal działa bez Playwright:
|
||||
|
||||
- snapshoty ARIA
|
||||
- zrzuty ekranów całych stron dla zarządzanej przeglądarki `openclaw`, gdy dostępny jest
|
||||
WebSocket CDP per karta
|
||||
- zrzuty ekranów całych stron dla profili `existing-session` / Chrome MCP
|
||||
- zrzuty ekranów `--ref` dla existing-session na podstawie wyjścia snapshotu
|
||||
- Snapshoty ARIA
|
||||
- Zrzuty ekranu strony dla zarządzanej przeglądarki `openclaw`, gdy dostępny jest WebSocket
|
||||
CDP dla danej karty
|
||||
- Zrzuty ekranu strony dla profili `existing-session` / Chrome MCP
|
||||
- Zrzuty ekranów existing-session oparte na `--ref` z danych wyjściowych snapshotu
|
||||
|
||||
Co nadal wymaga Playwright:
|
||||
|
||||
- `navigate`
|
||||
- `act`
|
||||
- snapshoty AI / snapshoty ról
|
||||
- zrzuty ekranów elementów przez selektory CSS (`--element`)
|
||||
- pełny eksport PDF Browser
|
||||
- AI snapshoty / snapshoty ról
|
||||
- Zrzuty ekranów elementów przez selektor CSS (`--element`)
|
||||
- eksport pełnego PDF przeglądarki
|
||||
|
||||
Zrzuty ekranów elementów odrzucają też `--full-page`; trasa zwraca `fullPage is
|
||||
Zrzuty ekranów elementów również odrzucają `--full-page`; trasa zwraca `fullPage is
|
||||
not supported for element screenshots`.
|
||||
|
||||
Jeśli widzisz `Playwright is not available in this gateway build`, zainstaluj pełny
|
||||
pakiet Playwright (nie `playwright-core`) i uruchom ponownie gateway albo ponownie zainstaluj
|
||||
OpenClaw z obsługą Browser.
|
||||
pakiet Playwright (nie `playwright-core`) i uruchom ponownie gateway albo zainstaluj
|
||||
OpenClaw ponownie z obsługą przeglądarki.
|
||||
|
||||
#### Instalacja Playwright w Dockerze
|
||||
|
||||
Jeśli Twój Gateway działa w Dockerze, unikaj `npx playwright` (konflikty z nadpisaniami npm).
|
||||
Użyj dołączonego CLI:
|
||||
Jeśli Twój Gateway działa w Dockerze, unikaj `npx playwright` (konflikty nadpisań npm).
|
||||
Zamiast tego użyj dołączonego CLI:
|
||||
|
||||
```bash
|
||||
docker compose run --rm openclaw-cli \
|
||||
node /app/node_modules/playwright-core/cli.js install chromium
|
||||
```
|
||||
|
||||
Aby utrwalać pobrania Browser, ustaw `PLAYWRIGHT_BROWSERS_PATH` (na przykład,
|
||||
Aby zachować pobrane przeglądarki, ustaw `PLAYWRIGHT_BROWSERS_PATH` (na przykład
|
||||
`/home/node/.cache/ms-playwright`) i upewnij się, że `/home/node` jest utrwalane przez
|
||||
`OPENCLAW_HOME_VOLUME` albo bind mount. Zobacz [Docker](/install/docker).
|
||||
`OPENCLAW_HOME_VOLUME` lub bind mount. Zobacz [Docker](/pl/install/docker).
|
||||
|
||||
## Jak to działa (wewnętrznie)
|
||||
|
||||
Przepływ na wysokim poziomie:
|
||||
|
||||
- Mały **serwer sterowania** akceptuje żądania HTTP.
|
||||
- Mały **serwer sterowania** przyjmuje żądania HTTP.
|
||||
- Łączy się z przeglądarkami opartymi na Chromium (Chrome/Brave/Edge/Chromium) przez **CDP**.
|
||||
- Dla bardziej zaawansowanych akcji (click/type/snapshot/PDF) używa **Playwright** na warstwie
|
||||
- W przypadku zaawansowanych akcji (kliknięcie/wpisywanie/snapshot/PDF) używa **Playwright** na wierzchu
|
||||
CDP.
|
||||
- Gdy brakuje Playwright, dostępne są tylko operacje niezależne od Playwright.
|
||||
- Gdy brakuje Playwright, dostępne są tylko operacje niewymagające Playwright.
|
||||
|
||||
Ten projekt utrzymuje po stronie agenta stabilny, deterministyczny interfejs, a jednocześnie pozwala
|
||||
przełączać lokalne/zdalne przeglądarki i profile.
|
||||
Taki projekt zapewnia agentowi stabilny, deterministyczny interfejs, a jednocześnie pozwala
|
||||
zamieniać lokalne/zdalne przeglądarki i profile.
|
||||
|
||||
## Krótka dokumentacja CLI
|
||||
## Krótkie odniesienie do CLI
|
||||
|
||||
Wszystkie polecenia akceptują `--browser-profile <name>`, aby wskazać konkretny profil.
|
||||
Wszystkie polecenia akceptują też `--json` dla maszynowo czytelnego wyjścia (stabilne ładunki).
|
||||
Wszystkie polecenia akceptują też `--json` dla danych wyjściowych czytelnych maszynowo (stabilne payloady).
|
||||
|
||||
Podstawy:
|
||||
|
||||
@ -670,9 +694,9 @@ Inspekcja:
|
||||
|
||||
Uwaga dotycząca cyklu życia:
|
||||
|
||||
- Dla profili attach-only i zdalnego CDP `openclaw browser stop` nadal jest
|
||||
poprawnym poleceniem czyszczenia po testach. Zamknie aktywną sesję sterowania i
|
||||
wyczyści tymczasowe nadpisania emulacji zamiast zabijać właściwą
|
||||
- Dla profili tylko-dołączanych i zdalnych profili CDP `openclaw browser stop` nadal jest
|
||||
właściwym poleceniem czyszczenia po testach. Zamyka aktywną sesję sterowania i
|
||||
czyści tymczasowe nadpisania emulacji zamiast zamykać bazową
|
||||
przeglądarkę.
|
||||
- `openclaw browser errors --clear`
|
||||
- `openclaw browser requests --filter api --clear`
|
||||
@ -724,37 +748,37 @@ Stan:
|
||||
|
||||
Uwagi:
|
||||
|
||||
- `upload` i `dialog` to wywołania **uzbrajające**; uruchamiaj je przed kliknięciem/naciśnięciem,
|
||||
które wyzwala wybór pliku/dialog.
|
||||
- Ścieżki wyjściowe pobrań i śladów są ograniczone do katalogów tymczasowych OpenClaw:
|
||||
- ślady: `/tmp/openclaw` (fallback: `${os.tmpdir()}/openclaw`)
|
||||
- pobrania: `/tmp/openclaw/downloads` (fallback: `${os.tmpdir()}/openclaw/downloads`)
|
||||
- Ścieżki uploadów są ograniczone do katalogu tymczasowego uploadów OpenClaw:
|
||||
- uploady: `/tmp/openclaw/uploads` (fallback: `${os.tmpdir()}/openclaw/uploads`)
|
||||
- `upload` może także ustawiać wejścia plików bezpośrednio przez `--input-ref` lub `--element`.
|
||||
- `upload` i `dialog` to wywołania **uzbrajające**; uruchom je przed kliknięciem/naciśnięciem,
|
||||
które wywoła wybór pliku/okno dialogowe.
|
||||
- Ścieżki wyjściowe pobierania i trace są ograniczone do tymczasowych katalogów głównych OpenClaw:
|
||||
- traces: `/tmp/openclaw` (fallback: `${os.tmpdir()}/openclaw`)
|
||||
- downloads: `/tmp/openclaw/downloads` (fallback: `${os.tmpdir()}/openclaw/downloads`)
|
||||
- Ścieżki uploadu są ograniczone do tymczasowego katalogu głównego uploadów OpenClaw:
|
||||
- uploads: `/tmp/openclaw/uploads` (fallback: `${os.tmpdir()}/openclaw/uploads`)
|
||||
- `upload` może też ustawiać wejścia plików bezpośrednio przez `--input-ref` lub `--element`.
|
||||
- `snapshot`:
|
||||
- `--format ai` (domyślnie, gdy Playwright jest zainstalowany): zwraca snapshot AI z liczbowymi refami (`aria-ref="<n>"`).
|
||||
- `--format ai` (domyślnie, gdy Playwright jest zainstalowany): zwraca snapshot AI z numerycznymi refami (`aria-ref="<n>"`).
|
||||
- `--format aria`: zwraca drzewo dostępności (bez refów; tylko do inspekcji).
|
||||
- `--efficient` (lub `--mode efficient`): kompaktowy preset snapshotu ról (interactive + compact + depth + niższe maxChars).
|
||||
- Domyślna konfiguracja (tylko narzędzie/CLI): ustaw `browser.snapshotDefaults.mode: "efficient"`, aby używać wydajnych snapshotów, gdy wywołujący nie przekazuje trybu (zobacz [Gateway configuration](/gateway/configuration-reference#browser)).
|
||||
- Domyślna konfiguracja (tylko tool/CLI): ustaw `browser.snapshotDefaults.mode: "efficient"`, aby używać wydajnych snapshotów, gdy wywołujący nie przekazuje trybu (zobacz [Konfiguracja Gateway](/pl/gateway/configuration-reference#browser)).
|
||||
- Opcje snapshotu ról (`--interactive`, `--compact`, `--depth`, `--selector`) wymuszają snapshot oparty na rolach z refami takimi jak `ref=e12`.
|
||||
- `--frame "<iframe selector>"` ogranicza snapshoty ról do iframe (łączy się z refami ról takimi jak `e12`).
|
||||
- `--interactive` wypisuje płaską, łatwą do wyboru listę elementów interaktywnych (najlepszą do wykonywania akcji).
|
||||
- `--labels` dodaje zrzut ekranu tylko aktualnego viewportu z nałożonymi etykietami refów (wypisuje `MEDIA:<path>`).
|
||||
- `click`/`type`/itd. wymagają `ref` ze `snapshot` (albo liczbowego `12`, albo refu roli `e12`).
|
||||
Selektory CSS są celowo nieobsługiwane dla akcji.
|
||||
- `--frame "<iframe selector>"` ogranicza snapshoty ról do iframe'a (paruje się z refami ról takimi jak `e12`).
|
||||
- `--interactive` wyświetla płaską, łatwą do wyboru listę elementów interaktywnych (najlepszą do sterowania akcjami).
|
||||
- `--labels` dodaje zrzut ekranu tylko viewportu z nałożonymi etykietami refów (wypisuje `MEDIA:<path>`).
|
||||
- `click`/`type`/itd. wymagają `ref` ze `snapshot` (numerycznego `12` albo refu roli `e12`).
|
||||
Selektory CSS celowo nie są obsługiwane dla akcji.
|
||||
|
||||
## Snapshoty i refy
|
||||
|
||||
OpenClaw obsługuje dwa style „snapshotów”:
|
||||
|
||||
- **AI snapshot (liczbowe refy)**: `openclaw browser snapshot` (domyślnie; `--format ai`)
|
||||
- Wyjście: tekstowy snapshot zawierający liczbowe refy.
|
||||
- **Snapshot AI (numeryczne refy)**: `openclaw browser snapshot` (domyślnie; `--format ai`)
|
||||
- Wynik: tekstowy snapshot zawierający numeryczne refy.
|
||||
- Akcje: `openclaw browser click 12`, `openclaw browser type 23 "hello"`.
|
||||
- Wewnętrznie ref jest rozwiązywany przez `aria-ref` Playwright.
|
||||
|
||||
- **Snapshot ról (refy ról jak `e12`)**: `openclaw browser snapshot --interactive` (albo `--compact`, `--depth`, `--selector`, `--frame`)
|
||||
- Wyjście: lista/drzewo oparte na rolach z `[ref=e12]` (oraz opcjonalnie `[nth=1]`).
|
||||
- **Snapshot ról (refy ról takie jak `e12`)**: `openclaw browser snapshot --interactive` (lub `--compact`, `--depth`, `--selector`, `--frame`)
|
||||
- Wynik: lista/drzewo oparte na rolach z `[ref=e12]` (i opcjonalnym `[nth=1]`).
|
||||
- Akcje: `openclaw browser click e12`, `openclaw browser highlight e12`.
|
||||
- Wewnętrznie ref jest rozwiązywany przez `getByRole(...)` (plus `nth()` dla duplikatów).
|
||||
- Dodaj `--labels`, aby dołączyć zrzut ekranu viewportu z nałożonymi etykietami `e12`.
|
||||
@ -762,13 +786,13 @@ OpenClaw obsługuje dwa style „snapshotów”:
|
||||
Zachowanie refów:
|
||||
|
||||
- Refy **nie są stabilne między nawigacjami**; jeśli coś się nie powiedzie, uruchom ponownie `snapshot` i użyj świeżego refu.
|
||||
- Jeśli snapshot ról został wykonany z `--frame`, refy ról są ograniczone do tego iframe do czasu następnego snapshotu ról.
|
||||
- Jeśli snapshot ról został wykonany z `--frame`, refy ról są ograniczone do tego iframe'a aż do następnego snapshotu ról.
|
||||
|
||||
## Rozszerzenia wait
|
||||
## Rozszerzone możliwości `wait`
|
||||
|
||||
Możesz czekać na coś więcej niż tylko czas/tekst:
|
||||
Możesz czekać na więcej niż tylko czas/tekst:
|
||||
|
||||
- Czekanie na URL (obsługiwane globy przez Playwright):
|
||||
- Czekanie na URL (globy obsługiwane przez Playwright):
|
||||
- `openclaw browser wait --url "**/dash"`
|
||||
- Czekanie na stan ładowania:
|
||||
- `openclaw browser wait --load networkidle`
|
||||
@ -777,7 +801,7 @@ Możesz czekać na coś więcej niż tylko czas/tekst:
|
||||
- Czekanie, aż selektor stanie się widoczny:
|
||||
- `openclaw browser wait "#main"`
|
||||
|
||||
Można to łączyć:
|
||||
Można je łączyć:
|
||||
|
||||
```bash
|
||||
openclaw browser wait "#main" \
|
||||
@ -793,16 +817,16 @@ Gdy akcja się nie powiedzie (np. „not visible”, „strict mode violation”
|
||||
|
||||
1. `openclaw browser snapshot --interactive`
|
||||
2. Użyj `click <ref>` / `type <ref>` (preferuj refy ról w trybie interactive)
|
||||
3. Jeśli nadal się nie powiedzie: `openclaw browser highlight <ref>`, aby zobaczyć, w co celuje Playwright
|
||||
3. Jeśli nadal się nie powiedzie: `openclaw browser highlight <ref>`, aby zobaczyć, na co kieruje Playwright
|
||||
4. Jeśli strona zachowuje się dziwnie:
|
||||
- `openclaw browser errors --clear`
|
||||
- `openclaw browser requests --filter api --clear`
|
||||
5. Do głębokiego debugowania: nagraj ślad:
|
||||
5. Do głębokiego debugowania: nagraj trace:
|
||||
- `openclaw browser trace start`
|
||||
- odtwórz problem
|
||||
- `openclaw browser trace stop` (wypisuje `TRACE:<path>`)
|
||||
|
||||
## Wyjście JSON
|
||||
## Dane wyjściowe JSON
|
||||
|
||||
`--json` służy do skryptów i narzędzi strukturalnych.
|
||||
|
||||
@ -815,18 +839,18 @@ openclaw browser requests --filter api --json
|
||||
openclaw browser cookies --json
|
||||
```
|
||||
|
||||
Snapshoty ról w JSON zawierają `refs` oraz mały blok `stats` (lines/chars/refs/interactive), dzięki czemu narzędzia mogą analizować rozmiar i gęstość ładunku.
|
||||
Snapshoty ról w JSON zawierają `refs` oraz mały blok `stats` (lines/chars/refs/interactive), aby narzędzia mogły analizować rozmiar i gęstość payloadu.
|
||||
|
||||
## Ustawienia stanu i środowiska
|
||||
## Pokrętła stanu i środowiska
|
||||
|
||||
Są przydatne w przepływach typu „spraw, żeby strona zachowywała się jak X”:
|
||||
Są przydatne w przepływach „spraw, aby witryna zachowywała się jak X”:
|
||||
|
||||
- Cookies: `cookies`, `cookies set`, `cookies clear`
|
||||
- Storage: `storage local|session get|set|clear`
|
||||
- Offline: `set offline on|off`
|
||||
- Headers: `set headers --headers-json '{"X-Debug":"1"}'` (starsze `set headers --json '{"X-Debug":"1"}'` nadal jest obsługiwane)
|
||||
- Auth HTTP Basic: `set credentials user pass` (lub `--clear`)
|
||||
- Geolokalizacja: `set geo <lat> <lon> --origin "https://example.com"` (lub `--clear`)
|
||||
- HTTP Basic auth: `set credentials user pass` (lub `--clear`)
|
||||
- Geolocation: `set geo <lat> <lon> --origin "https://example.com"` (lub `--clear`)
|
||||
- Media: `set media dark|light|no-preference|none`
|
||||
- Timezone / locale: `set timezone ...`, `set locale ...`
|
||||
- Device / viewport:
|
||||
@ -835,13 +859,13 @@ Są przydatne w przepływach typu „spraw, żeby strona zachowywała się jak X
|
||||
|
||||
## Bezpieczeństwo i prywatność
|
||||
|
||||
- Profil Browser openclaw może zawierać zalogowane sesje; traktuj go jako wrażliwy.
|
||||
- Profil przeglądarki openclaw może zawierać zalogowane sesje; traktuj go jako wrażliwy.
|
||||
- `browser act kind=evaluate` / `openclaw browser evaluate` oraz `wait --fn`
|
||||
wykonują dowolny JavaScript w kontekście strony. Prompt injection może tym sterować.
|
||||
Wyłącz to przez `browser.evaluateEnabled=false`, jeśli tego nie potrzebujesz.
|
||||
- W przypadku logowania i uwag dotyczących antybotów (X/Twitter itd.) zobacz [Browser login + X/Twitter posting](/tools/browser-login).
|
||||
- Utrzymuj Gateway/hosta węzła jako prywatne (tylko loopback lub tailnet).
|
||||
- Endpointy zdalnego CDP są potężne; tuneluj je i chroń.
|
||||
- W przypadku logowań i uwag dotyczących anti-botów (X/Twitter itd.) zobacz [Logowanie w przeglądarce + publikowanie na X/Twitter](/pl/tools/browser-login).
|
||||
- Utrzymuj Gateway/host węzła w prywatnym środowisku (tylko loopback lub tailnet).
|
||||
- Zdalne endpointy CDP są potężne; tuneluj je i zabezpieczaj.
|
||||
|
||||
Przykład trybu ścisłego (domyślnie blokowanie prywatnych/wewnętrznych miejsc docelowych):
|
||||
|
||||
@ -859,34 +883,34 @@ Przykład trybu ścisłego (domyślnie blokowanie prywatnych/wewnętrznych miejs
|
||||
|
||||
## Rozwiązywanie problemów
|
||||
|
||||
W przypadku problemów specyficznych dla Linuxa (szczególnie snap Chromium) zobacz
|
||||
[Browser troubleshooting](/tools/browser-linux-troubleshooting).
|
||||
W przypadku problemów specyficznych dla Linuxa (zwłaszcza snap Chromium) zobacz
|
||||
[Rozwiązywanie problemów z przeglądarką](/pl/tools/browser-linux-troubleshooting).
|
||||
|
||||
Dla konfiguracji split-host WSL2 Gateway + Windows Chrome zobacz
|
||||
[WSL2 + Windows + remote Chrome CDP troubleshooting](/tools/browser-wsl2-windows-remote-cdp-troubleshooting).
|
||||
W przypadku konfiguracji rozdzielonego hosta WSL2 Gateway + Windows Chrome zobacz
|
||||
[WSL2 + Windows + rozwiązywanie problemów ze zdalnym Chrome CDP](/pl/tools/browser-wsl2-windows-remote-cdp-troubleshooting).
|
||||
|
||||
## Narzędzia agenta + jak działa sterowanie
|
||||
|
||||
Agent otrzymuje **jedno narzędzie** do automatyzacji Browser:
|
||||
Agent otrzymuje **jedno narzędzie** do automatyzacji przeglądarki:
|
||||
|
||||
- `browser` — status/start/stop/tabs/open/focus/close/snapshot/screenshot/navigate/act
|
||||
|
||||
Jak to działa:
|
||||
Jak to się mapuje:
|
||||
|
||||
- `browser snapshot` zwraca stabilne drzewo UI (AI lub ARIA).
|
||||
- `browser act` używa identyfikatorów `ref` ze snapshotów do click/type/drag/select.
|
||||
- `browser screenshot` przechwytuje piksele (całą stronę albo element).
|
||||
- `browser act` używa identyfikatorów `ref` ze snapshotu do kliknięcia/wpisywania/przeciągania/zaznaczania.
|
||||
- `browser screenshot` przechwytuje piksele (cała strona lub element).
|
||||
- `browser` akceptuje:
|
||||
- `profile`, aby wybrać nazwany profil Browser (`openclaw`, `chrome` albo zdalny CDP).
|
||||
- `target` (`sandbox` | `host` | `node`), aby wybrać miejsce działania Browser.
|
||||
- `profile`, aby wybrać nazwany profil przeglądarki (openclaw, chrome lub zdalny CDP).
|
||||
- `target` (`sandbox` | `host` | `node`), aby wybrać, gdzie znajduje się przeglądarka.
|
||||
- W sesjach sandboxowanych `target: "host"` wymaga `agents.defaults.sandbox.browser.allowHostControl=true`.
|
||||
- Jeśli pominięto `target`: sesje sandboxowane domyślnie używają `sandbox`, a sesje niesandboxowane — `host`.
|
||||
- Jeśli połączony jest węzeł obsługujący Browser, narzędzie może automatycznie kierować ruch do niego, chyba że przypniesz `target="host"` lub `target="node"`.
|
||||
- Jeśli `target` zostanie pominięte: sesje sandboxowane domyślnie używają `sandbox`, a sesje niesandboxowane `host`.
|
||||
- Jeśli podłączony jest węzeł z obsługą przeglądarki, narzędzie może automatycznie kierować do niego wywołania, chyba że przypniesz `target="host"` lub `target="node"`.
|
||||
|
||||
To utrzymuje deterministyczne działanie agenta i pozwala uniknąć kruchych selektorów.
|
||||
Dzięki temu agent pozostaje deterministyczny i unika kruchych selektorów.
|
||||
|
||||
## Powiązane
|
||||
|
||||
- [Tools Overview](/tools) — wszystkie dostępne narzędzia agenta
|
||||
- [Sandboxing](/gateway/sandboxing) — sterowanie Browser w środowiskach sandboxowanych
|
||||
- [Security](/gateway/security) — ryzyka sterowania Browser i utwardzanie
|
||||
- [Przegląd narzędzi](/pl/tools) — wszystkie dostępne narzędzia agenta
|
||||
- [Sandboxing](/pl/gateway/sandboxing) — sterowanie przeglądarką w środowiskach sandboxowanych
|
||||
- [Bezpieczeństwo](/pl/gateway/security) — ryzyka i utwardzanie sterowania przeglądarką
|
||||
|
||||
@ -1,66 +1,69 @@
|
||||
---
|
||||
read_when:
|
||||
- Konfigurowanie zatwierdzeń exec lub list dozwolonych
|
||||
- Implementowanie UX zatwierdzeń exec w aplikacji macOS
|
||||
- Przeglądanie promptów wyjścia z sandboxa i ich konsekwencji
|
||||
- Implementacja UX zatwierdzeń exec w aplikacji macOS
|
||||
- Przegląd promptów wyjścia z sandboxa i ich konsekwencji
|
||||
summary: Zatwierdzenia exec, listy dozwolonych i prompty wyjścia z sandboxa
|
||||
title: Zatwierdzenia exec
|
||||
x-i18n:
|
||||
generated_at: "2026-04-08T02:19:40Z"
|
||||
generated_at: "2026-04-10T09:45:19Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 6041929185bab051ad873cc4822288cb7d6f0470e19e7ae7a16b70f76dfc2cd9
|
||||
source_hash: 5f4a2e2f1f3c13a1d1926c9de0720513ea8a74d1ca571dbe74b188d8c560c14c
|
||||
source_path: tools/exec-approvals.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Zatwierdzenia exec
|
||||
|
||||
Zatwierdzenia exec to **zabezpieczenie aplikacji towarzyszącej / hosta węzła** pozwalające agentowi działającemu w sandboxie uruchamiać
|
||||
polecenia na rzeczywistym hoście (`gateway` lub `node`). Potraktuj to jak blokadę bezpieczeństwa:
|
||||
polecenia są dozwolone tylko wtedy, gdy polityka + lista dozwolonych + (opcjonalne) zatwierdzenie użytkownika są zgodne.
|
||||
Zatwierdzenia exec są **dodatkiem** do polityki narzędzi i kontroli elevated (chyba że elevated jest ustawione na `full`, co pomija zatwierdzenia).
|
||||
Efektywna polityka jest **bardziej rygorystyczną** z `tools.exec.*` i domyślnych ustawień zatwierdzeń; jeśli pole zatwierdzeń zostanie pominięte, używana jest wartość `tools.exec`.
|
||||
Exec hosta używa również lokalnego stanu zatwierdzeń na tej maszynie. Lokalne dla hosta
|
||||
`ask: "always"` w `~/.openclaw/exec-approvals.json` nadal wyświetla prompty, nawet jeśli
|
||||
domyślne ustawienia sesji lub konfiguracji żądają `ask: "on-miss"`.
|
||||
Zatwierdzenia exec to **zabezpieczenie aplikacji towarzyszącej / hosta węzła** umożliwiające agentowi działającemu w sandboxie uruchamianie
|
||||
poleceń na rzeczywistym hoście (`gateway` lub `node`). Traktuj to jak blokadę bezpieczeństwa:
|
||||
polecenia są dozwolone tylko wtedy, gdy polityka + lista dozwolonych + (opcjonalnie) zgoda użytkownika są ze sobą zgodne.
|
||||
Zatwierdzenia exec działają **dodatkowo** względem polityki narzędzi i bramkowania elevated (chyba że elevated jest ustawione na `full`, co pomija zatwierdzenia).
|
||||
Skuteczna polityka jest **bardziej restrykcyjną** z `tools.exec.*` i domyślnych ustawień zatwierdzeń; jeśli pole zatwierdzeń jest pominięte, używana jest wartość z `tools.exec`.
|
||||
Exec hosta używa także lokalnego stanu zatwierdzeń na tej maszynie. Lokalne ustawienie hosta
|
||||
`ask: "always"` w `~/.openclaw/exec-approvals.json` powoduje dalsze wyświetlanie promptów, nawet jeśli
|
||||
sesja lub domyślna konfiguracja żądają `ask: "on-miss"`.
|
||||
Użyj `openclaw approvals get`, `openclaw approvals get --gateway` lub
|
||||
`openclaw approvals get --node <id|name|ip>`, aby sprawdzić żądaną politykę,
|
||||
źródła polityki hosta i wynik efektywny.
|
||||
źródła polityki hosta oraz wynik skuteczny.
|
||||
Dla maszyny lokalnej `openclaw exec-policy show` pokazuje ten sam scalony widok, a
|
||||
`openclaw exec-policy set|preset` może zsynchronizować lokalnie żądaną politykę z
|
||||
lokalnym plikiem zatwierdzeń hosta w jednym kroku. Gdy zakres lokalny żąda `host=node`,
|
||||
`openclaw exec-policy show` zgłasza ten zakres w czasie działania jako zarządzany przez node, zamiast
|
||||
udawać, że lokalny plik zatwierdzeń jest skutecznym źródłem prawdy.
|
||||
|
||||
Jeśli interfejs aplikacji towarzyszącej **nie jest dostępny**, każde żądanie wymagające promptu jest
|
||||
rozstrzygane przez **ask fallback** (domyślnie: deny).
|
||||
rozstrzygane przez **awaryjne zachowanie ask** (domyślnie: odmowa).
|
||||
|
||||
Natywni klienci zatwierdzeń w czacie mogą również udostępniać specyficzne dla kanału elementy interakcji w
|
||||
wiadomości oczekującego zatwierdzenia. Na przykład Matrix może dodawać skróty reakcji do
|
||||
promptu zatwierdzenia (`✅` pozwól raz, `❌` odrzuć i `♾️` pozwól zawsze, gdy dostępne),
|
||||
jednocześnie pozostawiając polecenia `/approve ...` w wiadomości jako rozwiązanie zapasowe.
|
||||
Natywne klienckie mechanizmy zatwierdzania na czacie mogą również udostępniać udogodnienia specyficzne dla kanału w oczekującej wiadomości o zatwierdzeniu. Na przykład Matrix może inicjalizować skróty reakcji w prompcie zatwierdzenia (`✅` zezwól raz, `❌` odmów oraz `♾️` zezwól zawsze, gdy dostępne),
|
||||
jednocześnie pozostawiając polecenia `/approve ...` w wiadomości jako mechanizm zapasowy.
|
||||
|
||||
## Gdzie to ma zastosowanie
|
||||
## Gdzie ma to zastosowanie
|
||||
|
||||
Zatwierdzenia exec są egzekwowane lokalnie na hoście wykonania:
|
||||
Zatwierdzenia exec są wymuszane lokalnie na hoście wykonania:
|
||||
|
||||
- **host gateway** → proces `openclaw` na maszynie gateway
|
||||
- **host node** → runner węzła (aplikacja towarzysząca macOS lub bezgłowy host węzła)
|
||||
- **host node** → runner węzła (aplikacja towarzysząca macOS lub bezgłowy host node)
|
||||
|
||||
Uwaga dotycząca modelu zaufania:
|
||||
|
||||
- Wywołujący uwierzytelnieni przez Gateway są zaufanymi operatorami dla tego Gateway.
|
||||
- Sparowane węzły rozszerzają tę zdolność zaufanego operatora na host node.
|
||||
- Zatwierdzenia exec zmniejszają ryzyko przypadkowego wykonania, ale nie są granicą uwierzytelniania per użytkownik.
|
||||
- Zatwierdzone uruchomienia na hoście node wiążą kanoniczny kontekst wykonania: kanoniczne cwd, dokładne argv, powiązanie env
|
||||
gdy występuje oraz przypiętą ścieżkę do pliku wykonywalnego, gdy ma to zastosowanie.
|
||||
- Dla skryptów powłoki i bezpośrednich wywołań plików interpreterów/runtime OpenClaw również próbuje powiązać
|
||||
jeden konkretny lokalny operand pliku. Jeśli ten powiązany plik zmieni się po zatwierdzeniu, ale przed wykonaniem,
|
||||
- Wywołujący uwierzytelnieni względem Gateway są zaufanymi operatorami tego Gateway.
|
||||
- Sparowane węzły rozszerzają te zaufane uprawnienia operatora na host node.
|
||||
- Zatwierdzenia exec ograniczają ryzyko przypadkowego wykonania, ale nie stanowią granicy uwierzytelniania per użytkownik.
|
||||
- Zatwierdzone uruchomienia na hoście node wiążą kanoniczny kontekst wykonania: kanoniczny cwd, dokładne argv, powiązanie env,
|
||||
gdy występuje, oraz przypiętą ścieżkę do pliku wykonywalnego, gdy ma to zastosowanie.
|
||||
- Dla skryptów powłoki i bezpośrednich wywołań plików interpretera/runtime OpenClaw próbuje także powiązać
|
||||
jeden konkretny operand lokalnego pliku. Jeśli ten powiązany plik zmieni się po zatwierdzeniu, ale przed wykonaniem,
|
||||
uruchomienie zostanie odrzucone zamiast wykonać zmienioną treść.
|
||||
- To powiązanie pliku jest celowo realizowane według zasady best-effort, a nie jako pełny model semantyczny każdego
|
||||
interpretera/runtime i ścieżki ładowania. Jeśli tryb zatwierdzania nie potrafi zidentyfikować dokładnie jednego konkretnego lokalnego
|
||||
pliku do powiązania, odmawia wygenerowania uruchomienia opartego na zatwierdzeniu zamiast udawać pełne pokrycie.
|
||||
- To wiązanie plików jest celowo rozwiązaniem opartym na najlepszej próbie, a nie kompletnym modelem semantycznym każdego
|
||||
interpretera/runtime i każdej ścieżki ładowania. Jeśli tryb zatwierdzania nie potrafi zidentyfikować dokładnie jednego konkretnego lokalnego
|
||||
pliku do powiązania, odmawia utworzenia uruchomienia opartego na zatwierdzeniu, zamiast udawać pełne pokrycie.
|
||||
|
||||
Podział na macOS:
|
||||
|
||||
- **usługa hosta node** przekazuje `system.run` do **aplikacji macOS** przez lokalne IPC.
|
||||
- **aplikacja macOS** egzekwuje zatwierdzenia i wykonuje polecenie w kontekście UI.
|
||||
- **aplikacja macOS** wymusza zatwierdzenia i wykonuje polecenie w kontekście UI.
|
||||
|
||||
## Ustawienia i przechowywanie
|
||||
|
||||
@ -103,14 +106,14 @@ Przykładowy schemat:
|
||||
}
|
||||
```
|
||||
|
||||
## Tryb „YOLO” bez zatwierdzeń
|
||||
## Tryb „YOLO” bez zatwierdzania
|
||||
|
||||
Jeśli chcesz, aby exec hosta działał bez promptów zatwierdzania, musisz otworzyć **obie** warstwy polityki:
|
||||
Jeśli chcesz, aby exec hosta działał bez promptów zatwierdzenia, musisz otworzyć **obie** warstwy polityki:
|
||||
|
||||
- żądaną politykę exec w konfiguracji OpenClaw (`tools.exec.*`)
|
||||
- lokalną dla hosta politykę zatwierdzeń w `~/.openclaw/exec-approvals.json`
|
||||
- lokalną politykę zatwierdzeń hosta w `~/.openclaw/exec-approvals.json`
|
||||
|
||||
Jest to teraz domyślne zachowanie hosta, chyba że jawnie je zaostrzysz:
|
||||
Jest to teraz domyślne zachowanie hosta, o ile nie zaostrzysz go jawnie:
|
||||
|
||||
- `tools.exec.security`: `full` na `gateway`/`node`
|
||||
- `tools.exec.ask`: `off`
|
||||
@ -118,12 +121,12 @@ Jest to teraz domyślne zachowanie hosta, chyba że jawnie je zaostrzysz:
|
||||
|
||||
Ważne rozróżnienie:
|
||||
|
||||
- `tools.exec.host=auto` wybiera miejsce uruchomienia exec: sandbox, jeśli dostępny, w przeciwnym razie gateway.
|
||||
- `tools.exec.host=auto` wybiera miejsce wykonywania exec: sandbox, jeśli jest dostępny, w przeciwnym razie gateway.
|
||||
- YOLO wybiera sposób zatwierdzania exec hosta: `security=full` plus `ask=off`.
|
||||
- W trybie YOLO OpenClaw nie dodaje osobnej heurystycznej bramki zatwierdzeń dla maskowania poleceń ponad skonfigurowaną politykę exec hosta.
|
||||
- `auto` nie sprawia, że routing do gateway staje się darmowym obejściem z sesji działającej w sandboxie. Żądanie per wywołanie `host=node` jest dozwolone z `auto`, a `host=gateway` jest dozwolone z `auto` tylko wtedy, gdy nie jest aktywne środowisko sandbox. Jeśli chcesz stabilnej domyślnej wartości innej niż auto, ustaw `tools.exec.host` lub użyj jawnie `/exec host=...`.
|
||||
- W trybie YOLO OpenClaw nie dodaje osobnej heurystycznej bramki zatwierdzania zaciemniania poleceń ponad skonfigurowaną politykę exec hosta.
|
||||
- `auto` nie sprawia, że routowanie do gateway staje się darmowym obejściem z sesji sandboxowanej. Żądanie per wywołanie `host=node` jest dozwolone z `auto`, a `host=gateway` jest dozwolone z `auto` tylko wtedy, gdy nie działa żadne środowisko sandbox. Jeśli chcesz stabilnej domyślnej wartości innej niż auto, ustaw `tools.exec.host` lub użyj jawnie `/exec host=...`.
|
||||
|
||||
Jeśli chcesz bardziej konserwatywnej konfiguracji, zaostrz z powrotem dowolną warstwę do `allowlist` / `on-miss`
|
||||
Jeśli chcesz bardziej zachowawczej konfiguracji, ponownie zaostrz dowolną z warstw do `allowlist` / `on-miss`
|
||||
lub `deny`.
|
||||
|
||||
Trwała konfiguracja hosta gateway „nigdy nie pytaj”:
|
||||
@ -135,7 +138,7 @@ openclaw config set tools.exec.ask off
|
||||
openclaw gateway restart
|
||||
```
|
||||
|
||||
Następnie ustaw plik zatwierdzeń hosta zgodnie z tym:
|
||||
Następnie ustaw zgodny plik zatwierdzeń hosta:
|
||||
|
||||
```bash
|
||||
openclaw approvals set --stdin <<'EOF'
|
||||
@ -150,7 +153,22 @@ openclaw approvals set --stdin <<'EOF'
|
||||
EOF
|
||||
```
|
||||
|
||||
Dla hosta node zastosuj zamiast tego ten sam plik zatwierdzeń na tym węźle:
|
||||
Lokalny skrót do tej samej polityki hosta gateway na bieżącej maszynie:
|
||||
|
||||
```bash
|
||||
openclaw exec-policy preset yolo
|
||||
```
|
||||
|
||||
Ten lokalny skrót aktualizuje oba elementy:
|
||||
|
||||
- lokalne `tools.exec.host/security/ask`
|
||||
- lokalne ustawienia domyślne `~/.openclaw/exec-approvals.json`
|
||||
|
||||
Jest on celowo ograniczony tylko do lokalnego środowiska. Jeśli musisz zdalnie zmienić zatwierdzenia hosta gateway lub hosta node,
|
||||
nadal używaj `openclaw approvals set --gateway` lub
|
||||
`openclaw approvals set --node <id|name|ip>`.
|
||||
|
||||
Dla hosta node zastosuj zamiast tego ten sam plik zatwierdzeń na danym węźle:
|
||||
|
||||
```bash
|
||||
openclaw approvals set --node <id|name|ip> --stdin <<'EOF'
|
||||
@ -165,39 +183,45 @@ openclaw approvals set --node <id|name|ip> --stdin <<'EOF'
|
||||
EOF
|
||||
```
|
||||
|
||||
Ważne ograniczenie tylko lokalne:
|
||||
|
||||
- `openclaw exec-policy` nie synchronizuje zatwierdzeń node
|
||||
- `openclaw exec-policy set --host node` jest odrzucane
|
||||
- zatwierdzenia exec dla node są pobierane z node w czasie działania, więc aktualizacje kierowane do node muszą używać `openclaw approvals --node ...`
|
||||
|
||||
Skrót tylko dla sesji:
|
||||
|
||||
- `/exec security=full ask=off` zmienia tylko bieżącą sesję.
|
||||
- `/elevated full` to skrót awaryjny, który również pomija zatwierdzenia exec dla tej sesji.
|
||||
- `/elevated full` to skrót awaryjny break-glass, który również pomija zatwierdzenia exec dla tej sesji.
|
||||
|
||||
Jeśli plik zatwierdzeń hosta pozostaje bardziej rygorystyczny niż konfiguracja, nadal wygrywa bardziej rygorystyczna polityka hosta.
|
||||
Jeśli plik zatwierdzeń hosta pozostanie bardziej restrykcyjny niż konfiguracja, bardziej restrykcyjna polityka hosta nadal wygrywa.
|
||||
|
||||
## Przełączniki polityki
|
||||
## Elementy sterujące polityki
|
||||
|
||||
### Security (`exec.security`)
|
||||
|
||||
- **deny**: zablokuj wszystkie żądania exec hosta.
|
||||
- **allowlist**: zezwalaj tylko na polecenia z listy dozwolonych.
|
||||
- **full**: zezwalaj na wszystko (odpowiednik elevated).
|
||||
- **deny**: blokuje wszystkie żądania exec hosta.
|
||||
- **allowlist**: zezwala tylko na polecenia znajdujące się na liście dozwolonych.
|
||||
- **full**: zezwala na wszystko (odpowiednik elevated).
|
||||
|
||||
### Ask (`exec.ask`)
|
||||
|
||||
- **off**: nigdy nie wyświetlaj promptu.
|
||||
- **on-miss**: wyświetl prompt tylko wtedy, gdy lista dozwolonych nie pasuje.
|
||||
- **always**: wyświetlaj prompt dla każdego polecenia.
|
||||
- trwałe zaufanie `allow-always` nie tłumi promptów, gdy efektywny tryb ask to `always`
|
||||
- **off**: nigdy nie wyświetla promptu.
|
||||
- **on-miss**: wyświetla prompt tylko wtedy, gdy lista dozwolonych nie pasuje.
|
||||
- **always**: wyświetla prompt przy każdym poleceniu.
|
||||
- trwałe zaufanie `allow-always` nie wyłącza promptów, gdy skuteczny tryb ask to `always`
|
||||
|
||||
### Ask fallback (`askFallback`)
|
||||
|
||||
Jeśli prompt jest wymagany, ale żaden UI nie jest osiągalny, fallback decyduje:
|
||||
Jeśli prompt jest wymagany, ale żaden UI nie jest osiągalny, zachowanie awaryjne określa wynik:
|
||||
|
||||
- **deny**: blokuj.
|
||||
- **allowlist**: zezwalaj tylko wtedy, gdy lista dozwolonych pasuje.
|
||||
- **full**: zezwalaj.
|
||||
- **deny**: blokuje.
|
||||
- **allowlist**: zezwala tylko wtedy, gdy lista dozwolonych pasuje.
|
||||
- **full**: zezwala.
|
||||
|
||||
### Wzmocnienie eval inline dla interpreterów (`tools.exec.strictInlineEval`)
|
||||
### Wzmocnienie inline interpreter eval (`tools.exec.strictInlineEval`)
|
||||
|
||||
Gdy `tools.exec.strictInlineEval=true`, OpenClaw traktuje formy eval kodu inline jako wymagające zatwierdzenia, nawet jeśli sam plik wykonywalny interpretera znajduje się na liście dozwolonych.
|
||||
Gdy `tools.exec.strictInlineEval=true`, OpenClaw traktuje formy inline code-eval jako wymagające zatwierdzenia, nawet jeśli sam binarny interpreter znajduje się na liście dozwolonych.
|
||||
|
||||
Przykłady:
|
||||
|
||||
@ -209,16 +233,16 @@ Przykłady:
|
||||
- `lua -e`
|
||||
- `osascript -e`
|
||||
|
||||
To obrona warstwowa dla loaderów interpreterów, które nie mapują się czysto do jednego stabilnego operandu pliku. W trybie ścisłym:
|
||||
To mechanizm defense-in-depth dla loaderów interpreterów, które nie mapują się czysto na jeden stabilny operand pliku. W trybie ścisłym:
|
||||
|
||||
- te polecenia nadal wymagają jawnego zatwierdzenia;
|
||||
- `allow-always` nie zapisuje automatycznie dla nich nowych wpisów listy dozwolonych.
|
||||
- `allow-always` nie utrwala dla nich automatycznie nowych wpisów listy dozwolonych.
|
||||
|
||||
## Allowlist (per agent)
|
||||
## Lista dozwolonych (per agent)
|
||||
|
||||
Listy dozwolonych są **per agent**. Jeśli istnieje wielu agentów, przełącz, którego agenta
|
||||
edytujesz w aplikacji macOS. Wzorce są **niezależnymi od wielkości liter dopasowaniami glob**.
|
||||
Wzorce powinny rozwiązywać się do **ścieżek plików wykonywalnych** (wpisy zawierające tylko basename są ignorowane).
|
||||
Listy dozwolonych są **per agent**. Jeśli istnieje wielu agentów, przełącz agenta,
|
||||
którego edytujesz, w aplikacji macOS. Wzorce to **dopasowania glob bez rozróżniania wielkości liter**.
|
||||
Wzorce powinny rozwiązywać się do **ścieżek binarnych** (wpisy zawierające tylko basename są ignorowane).
|
||||
Starsze wpisy `agents.default` są migrowane do `agents.main` podczas ładowania.
|
||||
Łańcuchy powłoki, takie jak `echo ok && pwd`, nadal wymagają, aby każdy segment najwyższego poziomu spełniał reguły listy dozwolonych.
|
||||
|
||||
@ -231,42 +255,42 @@ Przykłady:
|
||||
Każdy wpis listy dozwolonych śledzi:
|
||||
|
||||
- **id** stabilny UUID używany jako tożsamość w UI (opcjonalnie)
|
||||
- **last used** znacznik czasu
|
||||
- **last used command**
|
||||
- **last resolved path**
|
||||
- **ostatnie użycie** znacznik czasu
|
||||
- **ostatnio użyte polecenie**
|
||||
- **ostatnio rozpoznana ścieżka**
|
||||
|
||||
## Auto-allow skill CLIs
|
||||
## Automatyczne zezwalanie na CLI Skills
|
||||
|
||||
Gdy **Auto-allow skill CLIs** jest włączone, pliki wykonywalne wskazywane przez znane Skills
|
||||
są traktowane jako wpisy listy dozwolonych na węzłach (węzeł macOS lub bezgłowy host węzła). Używa to
|
||||
`skills.bins` przez Gateway RPC do pobrania listy plików binarnych skill. Wyłącz to, jeśli chcesz rygorystycznych ręcznych list dozwolonych.
|
||||
są traktowane jako znajdujące się na liście dozwolonych na węzłach (macOS node lub bezgłowy host node). Wykorzystuje to
|
||||
`skills.bins` przez Gateway RPC do pobrania listy binariów Skills. Wyłącz tę opcję, jeśli chcesz stosować ścisłe ręczne listy dozwolonych.
|
||||
|
||||
Ważne uwagi dotyczące zaufania:
|
||||
|
||||
- To **niejawna wygodna lista dozwolonych**, oddzielna od ręcznych wpisów listy dozwolonych opartych na ścieżkach.
|
||||
- To **niejawna wygodna lista dozwolonych**, oddzielona od ręcznych wpisów listy dozwolonych opartych na ścieżkach.
|
||||
- Jest przeznaczona dla zaufanych środowisk operatora, w których Gateway i node znajdują się w tej samej granicy zaufania.
|
||||
- Jeśli potrzebujesz rygorystycznego jawnego zaufania, pozostaw `autoAllowSkills: false` i używaj tylko ręcznych wpisów listy dozwolonych opartych na ścieżkach.
|
||||
- Jeśli potrzebujesz ściśle jawnego zaufania, pozostaw `autoAllowSkills: false` i używaj wyłącznie ręcznych wpisów ścieżek na liście dozwolonych.
|
||||
|
||||
## Safe bins (tylko stdin)
|
||||
|
||||
`tools.exec.safeBins` definiuje małą listę plików binarnych **tylko stdin** (na przykład `cut`),
|
||||
które mogą działać w trybie allowlist **bez** jawnych wpisów listy dozwolonych. Safe bins odrzucają
|
||||
pozycyjne argumenty plików i tokeny podobne do ścieżek, więc mogą działać tylko na przychodzącym strumieniu.
|
||||
Traktuj to jako wąską szybką ścieżkę dla filtrów strumieni, a nie ogólną listę zaufania.
|
||||
**Nie** dodawaj interpreterów ani plików binarnych runtime (na przykład `python3`, `node`, `ruby`, `bash`, `sh`, `zsh`) do `safeBins`.
|
||||
Jeśli polecenie potrafi wykonywać eval kodu, uruchamiać podpolecenia lub z założenia czytać pliki, preferuj jawne wpisy listy dozwolonych i pozostaw włączone prompty zatwierdzeń.
|
||||
`tools.exec.safeBins` definiuje małą listę binariów **tylko stdin** (na przykład `cut`),
|
||||
które mogą działać w trybie allowlist **bez** jawnych wpisów na liście dozwolonych. Safe bins odrzucają
|
||||
pozycyjne argumenty plików i tokeny przypominające ścieżki, więc mogą działać wyłącznie na strumieniu wejściowym.
|
||||
Traktuj to jako wąską szybką ścieżkę dla filtrów strumienia, a nie ogólną listę zaufania.
|
||||
**Nie** dodawaj interpreterów ani binariów runtime (na przykład `python3`, `node`, `ruby`, `bash`, `sh`, `zsh`) do `safeBins`.
|
||||
Jeśli polecenie z założenia może wykonywać kod, uruchamiać podpolecenia lub odczytywać pliki, preferuj jawne wpisy listy dozwolonych i pozostaw włączone prompty zatwierdzania.
|
||||
Niestandardowe safe bins muszą definiować jawny profil w `tools.exec.safeBinProfiles.<bin>`.
|
||||
Walidacja jest deterministyczna wyłącznie na podstawie kształtu argv (bez sprawdzania istnienia systemu plików hosta), co
|
||||
zapobiega zachowaniu typu oracle istnienia plików wynikającemu z różnic allow/deny.
|
||||
Walidacja jest deterministyczna wyłącznie na podstawie kształtu argv (bez sprawdzania istnienia plików w systemie plików hosta), co
|
||||
zapobiega zachowaniu typu oracle istnienia pliku wynikającemu z różnic między allow/deny.
|
||||
Opcje zorientowane na pliki są odrzucane dla domyślnych safe bins (na przykład `sort -o`, `sort --output`,
|
||||
`sort --files0-from`, `sort --compress-program`, `sort --random-source`,
|
||||
`sort --temporary-directory`/`-T`, `wc --files0-from`, `jq -f/--from-file`,
|
||||
`grep -f/--file`).
|
||||
Safe bins egzekwują również jawne polityki flag per plik binarny dla opcji, które łamią zachowanie wyłącznie stdin
|
||||
(na przykład `sort -o/--output/--compress-program` i rekursywne flagi grep).
|
||||
Długie opcje są walidowane w trybie fail-closed w trybie safe-bin: nieznane flagi i niejednoznaczne
|
||||
Safe bins wymuszają także jawną politykę flag per binarium dla opcji, które naruszają zachowanie ograniczone do stdin
|
||||
(na przykład `sort -o/--output/--compress-program` i flagi rekurencyjne grep).
|
||||
Długie opcje są walidowane w trybie safe-bin zgodnie z zasadą fail-closed: nieznane flagi i niejednoznaczne
|
||||
skróty są odrzucane.
|
||||
Odrzucane flagi według profilu safe-bin:
|
||||
Flagi odrzucane przez profil safe-bin:
|
||||
|
||||
[//]: # "SAFE_BIN_DENIED_FLAGS:START"
|
||||
|
||||
@ -277,31 +301,31 @@ Odrzucane flagi według profilu safe-bin:
|
||||
|
||||
[//]: # "SAFE_BIN_DENIED_FLAGS:END"
|
||||
|
||||
Safe bins wymuszają również traktowanie tokenów argv jako **dosłownego tekstu** podczas wykonywania (bez globbingu
|
||||
Safe bins wymuszają także traktowanie tokenów argv jako **tekstu dosłownego** podczas wykonania (bez rozwijania globów
|
||||
i bez rozwijania `$VARS`) dla segmentów tylko stdin, więc wzorce takie jak `*` lub `$HOME/...` nie mogą zostać
|
||||
użyte do przemycenia odczytu plików.
|
||||
Safe bins muszą również rozwiązywać się z zaufanych katalogów plików binarnych (domyślne katalogi systemowe plus opcjonalne
|
||||
`tools.exec.safeBinTrustedDirs`). Wpisy `PATH` nigdy nie są automatycznie zaufane.
|
||||
użyte do przemycania odczytów plików.
|
||||
Safe bins muszą również rozwiązywać się z zaufanych katalogów binarnych (domyślne katalogi systemowe plus opcjonalne
|
||||
`tools.exec.safeBinTrustedDirs`). Wpisy `PATH` nigdy nie są automatycznie uznawane za zaufane.
|
||||
Domyślne zaufane katalogi safe-bin są celowo minimalne: `/bin`, `/usr/bin`.
|
||||
Jeśli Twój plik wykonywalny safe-bin znajduje się w ścieżkach menedżera pakietów/użytkownika (na przykład
|
||||
`/opt/homebrew/bin`, `/usr/local/bin`, `/opt/local/bin`, `/snap/bin`), dodaj je jawnie
|
||||
do `tools.exec.safeBinTrustedDirs`.
|
||||
Łączenie poleceń powłoki i przekierowania nie są automatycznie dozwolone w trybie allowlist.
|
||||
|
||||
Łączenie poleceń powłoki (`&&`, `||`, `;`) jest dozwolone, gdy każdy segment najwyższego poziomu spełnia zasady listy dozwolonych
|
||||
(w tym safe bins lub auto-allow skill). Przekierowania nadal nie są obsługiwane w trybie allowlist.
|
||||
Łączenie poleceń powłoki (`&&`, `||`, `;`) jest dozwolone, gdy każdy segment najwyższego poziomu spełnia reguły allowlist
|
||||
(w tym safe bins lub automatyczne zezwalanie na Skills). Przekierowania pozostają nieobsługiwane w trybie allowlist.
|
||||
Podstawianie poleceń (`$()` / backticks) jest odrzucane podczas parsowania allowlist, również wewnątrz
|
||||
cudzysłowów; użyj pojedynczych cudzysłowów, jeśli potrzebujesz dosłownego tekstu `$()`.
|
||||
W zatwierdzeniach aplikacji towarzyszącej macOS surowy tekst powłoki zawierający składnię sterowania lub rozwijania powłoki
|
||||
(`&&`, `||`, `;`, `|`, `` ` ``, `$`, `<`, `>`, `(`, `)`) jest traktowany jako brak dopasowania listy dozwolonych, chyba że
|
||||
sam plik binarny powłoki znajduje się na liście dozwolonych.
|
||||
Dla wrapperów powłoki (`bash|sh|zsh ... -c/-lc`) nadpisania env ograniczone do zakresu żądania są redukowane do
|
||||
podwójnych cudzysłowów; użyj pojedynczych cudzysłowów, jeśli potrzebujesz dosłownego tekstu `$()`.
|
||||
W zatwierdzeniach aplikacji towarzyszącej macOS surowy tekst powłoki zawierający składnię sterowania powłoką lub rozwijania
|
||||
(`&&`, `||`, `;`, `|`, `` ` ``, `$`, `<`, `>`, `(`, `)`) jest traktowany jako brak dopasowania allowlist, chyba że
|
||||
sam binarny plik powłoki znajduje się na liście dozwolonych.
|
||||
Dla wrapperów powłoki (`bash|sh|zsh ... -c/-lc`) nadpisania env w zakresie żądania są redukowane do
|
||||
małej jawnej listy dozwolonych (`TERM`, `LANG`, `LC_*`, `COLORTERM`, `NO_COLOR`, `FORCE_COLOR`).
|
||||
Dla decyzji allow-always w trybie allowlist znane wrappery dispatch
|
||||
(`env`, `nice`, `nohup`, `stdbuf`, `timeout`) utrwalają ścieżki wewnętrznych plików wykonywalnych zamiast ścieżek wrapperów. Multipleksery powłoki (`busybox`, `toybox`) są również odpakowywane dla apletów powłoki (`sh`, `ash`,
|
||||
itd.), tak aby utrwalane były ścieżki wewnętrznych plików wykonywalnych zamiast plików binarnych multipleksera. Jeśli wrapper lub
|
||||
multiplekser nie może zostać bezpiecznie odpakowany, żaden wpis listy dozwolonych nie jest utrwalany automatycznie.
|
||||
Jeśli dodajesz do listy dozwolonych interpretery takie jak `python3` lub `node`, preferuj `tools.exec.strictInlineEval=true`, aby eval inline nadal wymagał jawnego zatwierdzenia. W trybie ścisłym `allow-always` może nadal utrwalać niegroźne wywołania interpreterów/skryptów, ale nośniki eval inline nie są utrwalane automatycznie.
|
||||
W przypadku decyzji allow-always w trybie allowlist znane wrappery dyspozytorskie
|
||||
(`env`, `nice`, `nohup`, `stdbuf`, `timeout`) utrwalają ścieżki wewnętrznych plików wykonywalnych zamiast ścieżek wrapperów. Multipleksery powłoki (`busybox`, `toybox`) są również rozwijane dla apletów powłoki (`sh`, `ash`,
|
||||
itp.), tak aby utrwalać wewnętrzne pliki wykonywalne zamiast binariów multipleksera. Jeśli wrapper lub
|
||||
multiplekser nie może zostać bezpiecznie rozwinięty, żaden wpis allowlist nie jest utrwalany automatycznie.
|
||||
Jeśli umieszczasz na liście dozwolonych interpretery takie jak `python3` lub `node`, preferuj `tools.exec.strictInlineEval=true`, aby inline eval nadal wymagało jawnego zatwierdzenia. W trybie ścisłym `allow-always` nadal może utrwalać nieszkodliwe wywołania interpretera/skryptu, ale nośniki inline-eval nie są utrwalane automatycznie.
|
||||
|
||||
Domyślne safe bins:
|
||||
|
||||
@ -311,161 +335,161 @@ Domyślne safe bins:
|
||||
|
||||
[//]: # "SAFE_BIN_DEFAULTS:END"
|
||||
|
||||
`grep` i `sort` nie znajdują się na liście domyślnej. Jeśli jawnie je włączysz, zachowaj jawne wpisy listy dozwolonych dla
|
||||
`grep` i `sort` nie znajdują się na liście domyślnej. Jeśli jawnie je włączysz, zachowaj jawne wpisy allowlist dla
|
||||
ich przepływów pracy innych niż stdin.
|
||||
Dla `grep` w trybie safe-bin podawaj wzorzec za pomocą `-e`/`--regexp`; forma wzorca pozycyjnego jest
|
||||
odrzucana, aby operandy plików nie mogły zostać przemycone jako niejednoznaczne argumenty pozycyjne.
|
||||
odrzucana, aby operandy plików nie mogły być przemycane jako niejednoznaczne argumenty pozycyjne.
|
||||
|
||||
### Safe bins versus allowlist
|
||||
### Safe bins a allowlist
|
||||
|
||||
| Temat | `tools.exec.safeBins` | Allowlist (`exec-approvals.json`) |
|
||||
| ---------------- | ------------------------------------------------------ | ------------------------------------------------------------ |
|
||||
| Cel | Automatyczne zezwalanie na wąskie filtry stdin | Jawne zaufanie określonym plikom wykonywalnym |
|
||||
| Typ dopasowania | Nazwa pliku wykonywalnego + polityka argv safe-bin | Wzorzec glob rozwiązanego do ścieżki pliku wykonywalnego |
|
||||
| Zakres argumentów| Ograniczony profilem safe-bin i regułami tokenów dosłownych | Tylko dopasowanie ścieżki; odpowiedzialność za argumenty spoczywa poza tym na Tobie |
|
||||
| Typ dopasowania | Nazwa pliku wykonywalnego + polityka argv safe-bin | Wzorzec glob dopasowujący rozwiązaną ścieżkę pliku wykonywalnego |
|
||||
| Zakres argumentów | Ograniczony przez profil safe-bin i reguły tokenów dosłownych | Tylko dopasowanie ścieżki; argumenty są poza tym Twoją odpowiedzialnością |
|
||||
| Typowe przykłady | `head`, `tail`, `tr`, `wc` | `jq`, `python3`, `node`, `ffmpeg`, niestandardowe CLI |
|
||||
| Najlepsze użycie | Niskiego ryzyka transformacje tekstu w pipeline’ach | Każde narzędzie o szerszym zachowaniu lub skutkach ubocznych |
|
||||
| Najlepsze zastosowanie | Niskiego ryzyka przekształcenia tekstu w potokach | Dowolne narzędzie o szerszym zachowaniu lub skutkach ubocznych |
|
||||
|
||||
Lokalizacja konfiguracji:
|
||||
|
||||
- `safeBins` pochodzi z konfiguracji (`tools.exec.safeBins` lub per agent `agents.list[].tools.exec.safeBins`).
|
||||
- `safeBinTrustedDirs` pochodzi z konfiguracji (`tools.exec.safeBinTrustedDirs` lub per agent `agents.list[].tools.exec.safeBinTrustedDirs`).
|
||||
- `safeBinProfiles` pochodzi z konfiguracji (`tools.exec.safeBinProfiles` lub per agent `agents.list[].tools.exec.safeBinProfiles`). Klucze profili per agent nadpisują klucze globalne.
|
||||
- wpisy listy dozwolonych znajdują się w lokalnym dla hosta `~/.openclaw/exec-approvals.json` pod `agents.<id>.allowlist` (lub przez Control UI / `openclaw approvals allowlist ...`).
|
||||
- `openclaw security audit` ostrzega `tools.exec.safe_bins_interpreter_unprofiled`, gdy interpretery/pliki runtime pojawiają się w `safeBins` bez jawnych profili.
|
||||
- `openclaw doctor --fix` może wygenerować brakujące wpisy niestandardowych `safeBinProfiles.<bin>` jako `{}` (następnie je przejrzyj i zaostrz). Pliki binarne interpreterów/runtime nie są generowane automatycznie.
|
||||
- wpisy allowlist znajdują się w lokalnym dla hosta pliku `~/.openclaw/exec-approvals.json` w `agents.<id>.allowlist` (lub przez Control UI / `openclaw approvals allowlist ...`).
|
||||
- `openclaw security audit` ostrzega za pomocą `tools.exec.safe_bins_interpreter_unprofiled`, gdy binaria interpretera/runtime pojawiają się w `safeBins` bez jawnych profili.
|
||||
- `openclaw doctor --fix` może utworzyć brakujące niestandardowe wpisy `safeBinProfiles.<bin>` jako `{}` (następnie przejrzyj je i zaostrz). Binaria interpretera/runtime nie są tworzone automatycznie.
|
||||
|
||||
Przykład niestandardowego profilu:
|
||||
__OC_I18N_900004__
|
||||
Jeśli jawnie dodasz `jq` do `safeBins`, OpenClaw nadal odrzuca builtin `env` w trybie safe-bin,
|
||||
więc `jq -n env` nie może zrzucić środowiska procesu hosta bez jawnej ścieżki z listy dozwolonych
|
||||
Przykład profilu niestandardowego:
|
||||
__OC_I18N_900005__
|
||||
Jeśli jawnie włączysz `jq` do `safeBins`, OpenClaw nadal odrzuci wbudowane `env` w trybie safe-bin,
|
||||
tak aby `jq -n env` nie mogło zrzucić środowiska procesu hosta bez jawnej ścieżki allowlist
|
||||
lub promptu zatwierdzenia.
|
||||
|
||||
## Edycja w Control UI
|
||||
|
||||
Użyj karty **Control UI → Nodes → Exec approvals**, aby edytować wartości domyślne, nadpisania
|
||||
Użyj karty **Control UI → Nodes → Exec approvals**, aby edytować ustawienia domyślne, nadpisania
|
||||
per agent i listy dozwolonych. Wybierz zakres (Defaults lub agent), dostosuj politykę,
|
||||
dodaj/usuń wzorce listy dozwolonych, a następnie kliknij **Save**. UI pokazuje metadane **last used**
|
||||
dla każdego wzorca, aby ułatwić utrzymanie porządku na liście.
|
||||
dodaj/usuń wzorce allowlist, a następnie kliknij **Save**. UI pokazuje metadane **ostatniego użycia**
|
||||
dla każdego wzorca, dzięki czemu można utrzymywać porządek na liście.
|
||||
|
||||
Selektor celu wybiera **Gateway** (lokalne zatwierdzenia) lub **Node**. Węzły
|
||||
muszą ogłaszać `system.execApprovals.get/set` (aplikacja macOS lub bezgłowy host węzła).
|
||||
Jeśli węzeł nie ogłasza jeszcze zatwierdzeń exec, edytuj bezpośrednio jego lokalny
|
||||
muszą ogłaszać `system.execApprovals.get/set` (aplikacja macOS lub bezgłowy host node).
|
||||
Jeśli węzeł nie ogłasza jeszcze zatwierdzeń exec, edytuj bezpośrednio jego lokalny plik
|
||||
`~/.openclaw/exec-approvals.json`.
|
||||
|
||||
CLI: `openclaw approvals` obsługuje edycję gateway lub node (zobacz [CLI zatwierdzeń](/cli/approvals)).
|
||||
CLI: `openclaw approvals` obsługuje edycję gateway lub node (zobacz [Approvals CLI](/cli/approvals)).
|
||||
|
||||
## Przepływ zatwierdzania
|
||||
|
||||
Gdy prompt jest wymagany, gateway rozgłasza `exec.approval.requested` do klientów operatora.
|
||||
Control UI i aplikacja macOS rozwiązują to przez `exec.approval.resolve`, a następnie gateway przekazuje
|
||||
Gdy prompt jest wymagany, gateway rozsyła `exec.approval.requested` do klientów operatora.
|
||||
Control UI i aplikacja macOS rozstrzygają go przez `exec.approval.resolve`, po czym gateway przekazuje
|
||||
zatwierdzone żądanie do hosta node.
|
||||
|
||||
Dla `host=node` żądania zatwierdzeń zawierają kanoniczny payload `systemRunPlan`. Gateway używa
|
||||
tego planu jako autorytatywnego kontekstu polecenia/cwd/sesji podczas przekazywania zatwierdzonych żądań `system.run`.
|
||||
Dla `host=node` żądania zatwierdzenia zawierają kanoniczny ładunek `systemRunPlan`. Gateway używa
|
||||
tego planu jako autorytatywnego kontekstu polecenia/cwd/sesji podczas przekazywania zatwierdzonych żądań
|
||||
`system.run`.
|
||||
|
||||
To ma znaczenie przy opóźnieniach asynchronicznego zatwierdzania:
|
||||
Ma to znaczenie przy opóźnieniach asynchronicznego zatwierdzania:
|
||||
|
||||
- ścieżka node exec przygotowuje z góry jeden kanoniczny plan
|
||||
- rekord zatwierdzenia przechowuje ten plan i jego metadane powiązania
|
||||
- po zatwierdzeniu końcowe przekazane wywołanie `system.run` używa ponownie zapisanego planu
|
||||
- po zatwierdzeniu końcowe przekazane wywołanie `system.run` ponownie używa zapisanego planu
|
||||
zamiast ufać późniejszym zmianom wywołującego
|
||||
- jeśli wywołujący zmieni `command`, `rawCommand`, `cwd`, `agentId` lub
|
||||
`sessionKey` po utworzeniu żądania zatwierdzenia, gateway odrzuci
|
||||
przekazane uruchomienie jako niedopasowanie zatwierdzenia
|
||||
`sessionKey` po utworzeniu żądania zatwierdzenia, gateway odrzuci przekazane
|
||||
uruchomienie jako niedopasowanie zatwierdzenia
|
||||
|
||||
## Polecenia interpreterów/runtime
|
||||
## Polecenia interpretera/runtime
|
||||
|
||||
Uruchomienia interpreterów/runtime oparte na zatwierdzeniach są celowo konserwatywne:
|
||||
Uruchomienia interpretera/runtime oparte na zatwierdzeniu są celowo konserwatywne:
|
||||
|
||||
- Dokładny kontekst argv/cwd/env jest zawsze wiązany.
|
||||
- Formy bezpośrednich skryptów powłoki i bezpośrednich plików runtime są według zasady best-effort wiązane z jednym konkretnym snapshotem lokalnego
|
||||
pliku.
|
||||
- Typowe formy wrapperów menedżerów pakietów, które nadal rozwiązują się do jednego bezpośredniego lokalnego pliku (na przykład
|
||||
`pnpm exec`, `pnpm node`, `npm exec`, `npx`), są odpakowywane przed powiązaniem.
|
||||
- Jeśli OpenClaw nie potrafi zidentyfikować dokładnie jednego konkretnego lokalnego pliku dla polecenia interpretera/runtime
|
||||
- Dokładny kontekst argv/cwd/env jest zawsze powiązany.
|
||||
- Bezpośrednie formy skryptów powłoki i bezpośrednich plików runtime są, zgodnie z najlepszą próbą, powiązywane z jedną konkretną migawką pliku lokalnego.
|
||||
- Typowe formy wrapperów menedżera pakietów, które nadal rozwiązują się do jednego bezpośredniego pliku lokalnego (na przykład
|
||||
`pnpm exec`, `pnpm node`, `npm exec`, `npx`), są rozwijane przed powiązaniem.
|
||||
- Jeśli OpenClaw nie potrafi zidentyfikować dokładnie jednego konkretnego pliku lokalnego dla polecenia interpretera/runtime
|
||||
(na przykład skrypty pakietów, formy eval, łańcuchy loaderów specyficzne dla runtime lub niejednoznaczne formy
|
||||
wieloplikowe), wykonanie oparte na zatwierdzeniu jest odrzucane zamiast deklarować pokrycie semantyczne, którego
|
||||
faktycznie nie ma.
|
||||
- Dla takich przepływów pracy preferuj sandboxing, oddzielną granicę hosta lub jawny zaufany
|
||||
wieloplikowe), wykonanie oparte na zatwierdzeniu zostaje odrzucone zamiast deklarować pokrycie semantyczne, którego faktycznie
|
||||
nie ma.
|
||||
- Dla takich przepływów pracy preferuj sandboxing, osobną granicę hosta lub jawny zaufany
|
||||
przepływ allowlist/full, w którym operator akceptuje szerszą semantykę runtime.
|
||||
|
||||
Gdy zatwierdzenia są wymagane, narzędzie exec natychmiast zwraca identyfikator zatwierdzenia. Użyj tego identyfikatora, aby
|
||||
powiązać późniejsze zdarzenia systemowe (`Exec finished` / `Exec denied`). Jeśli żadna decyzja nie nadejdzie przed upływem
|
||||
limitu czasu, żądanie jest traktowane jako timeout zatwierdzenia i prezentowane jako powód odmowy.
|
||||
Gdy zatwierdzenia są wymagane, narzędzie exec zwraca natychmiast identyfikator zatwierdzenia. Użyj tego identyfikatora do
|
||||
skorelowania późniejszych zdarzeń systemowych (`Exec finished` / `Exec denied`). Jeśli przed upływem limitu czasu nie nadejdzie
|
||||
żadna decyzja, żądanie jest traktowane jako przekroczenie czasu zatwierdzenia i prezentowane jako powód odmowy.
|
||||
|
||||
### Zachowanie dostarczania follow-up
|
||||
|
||||
Po zakończeniu zatwierdzonego asynchronicznego exec OpenClaw wysyła turn `agent` follow-up do tej samej sesji.
|
||||
Po zakończeniu zatwierdzonego asynchronicznego exec OpenClaw wysyła follow-upowy obrót `agent` do tej samej sesji.
|
||||
|
||||
- Jeśli istnieje prawidłowy zewnętrzny cel dostarczenia (kanał dostarczalny plus cel `to`), dostarczenie follow-up używa tego kanału.
|
||||
- W przepływach wyłącznie webchat lub sesji wewnętrznych bez celu zewnętrznego dostarczenie follow-up pozostaje tylko w sesji (`deliver: false`).
|
||||
- Jeśli wywołujący jawnie żąda rygorystycznego zewnętrznego dostarczenia, ale nie ma możliwego do rozwiązania zewnętrznego kanału, żądanie kończy się błędem `INVALID_REQUEST`.
|
||||
- Jeśli włączono `bestEffortDeliver` i nie można rozwiązać zewnętrznego kanału, dostarczenie jest degradowane do trybu tylko sesyjnego zamiast zakończyć się błędem.
|
||||
- Jeśli istnieje prawidłowy zewnętrzny cel dostarczenia (kanał dostarczalny plus docelowe `to`), dostarczenie follow-up używa tego kanału.
|
||||
- W przepływach wyłącznie webchat lub sesjach wewnętrznych bez zewnętrznego celu dostarczenie follow-up pozostaje tylko w sesji (`deliver: false`).
|
||||
- Jeśli wywołujący jawnie żąda ścisłego dostarczenia zewnętrznego, ale nie można rozwiązać żadnego zewnętrznego kanału, żądanie kończy się błędem `INVALID_REQUEST`.
|
||||
- Jeśli włączono `bestEffortDeliver` i nie można rozwiązać zewnętrznego kanału, dostarczenie zostaje obniżone do trybu tylko sesyjnego zamiast zakończyć się błędem.
|
||||
|
||||
Okno dialogowe potwierdzenia zawiera:
|
||||
Okno potwierdzenia zawiera:
|
||||
|
||||
- polecenie + argumenty
|
||||
- cwd
|
||||
- identyfikator agenta
|
||||
- id agenta
|
||||
- rozwiązaną ścieżkę pliku wykonywalnego
|
||||
- metadane hosta + polityki
|
||||
|
||||
Akcje:
|
||||
Działania:
|
||||
|
||||
- **Allow once** → uruchom teraz
|
||||
- **Always allow** → dodaj do listy dozwolonych + uruchom
|
||||
- **Always allow** → dodaj do allowlist + uruchom
|
||||
- **Deny** → zablokuj
|
||||
|
||||
## Przekazywanie zatwierdzeń do kanałów czatu
|
||||
|
||||
Możesz przekazywać prompty zatwierdzeń exec do dowolnego kanału czatu (w tym kanałów pluginów) i zatwierdzać
|
||||
je za pomocą `/approve`. Używa to zwykłego pipeline dostarczania wychodzącego.
|
||||
je za pomocą `/approve`. Używa to zwykłego potoku dostarczania wychodzącego.
|
||||
|
||||
Konfiguracja:
|
||||
__OC_I18N_900005__
|
||||
Odpowiedź w czacie:
|
||||
__OC_I18N_900006__
|
||||
Polecenie `/approve` obsługuje zarówno zatwierdzenia exec, jak i zatwierdzenia pluginów. Jeśli identyfikator nie pasuje do oczekującego zatwierdzenia exec, automatycznie sprawdza zatwierdzenia pluginów.
|
||||
Odpowiedź na czacie:
|
||||
__OC_I18N_900007__
|
||||
Polecenie `/approve` obsługuje zarówno zatwierdzenia exec, jak i zatwierdzenia pluginów. Jeśli identyfikator nie pasuje do oczekującego zatwierdzenia exec, automatycznie sprawdza zamiast tego zatwierdzenia pluginów.
|
||||
|
||||
### Przekazywanie zatwierdzeń pluginów
|
||||
|
||||
Przekazywanie zatwierdzeń pluginów używa tego samego pipeline dostarczania co zatwierdzenia exec, ale ma własną
|
||||
niezależną konfigurację w `approvals.plugin`. Włączenie lub wyłączenie jednej z nich nie wpływa na drugą.
|
||||
__OC_I18N_900007__
|
||||
Kształt konfiguracji jest identyczny jak `approvals.exec`: `enabled`, `mode`, `agentFilter`,
|
||||
Przekazywanie zatwierdzeń pluginów używa tego samego potoku dostarczania co zatwierdzenia exec, ale ma własną
|
||||
niezależną konfigurację w `approvals.plugin`. Włączenie lub wyłączenie jednego nie wpływa na drugie.
|
||||
__OC_I18N_900008__
|
||||
Kształt konfiguracji jest identyczny jak w `approvals.exec`: `enabled`, `mode`, `agentFilter`,
|
||||
`sessionFilter` i `targets` działają tak samo.
|
||||
|
||||
Kanały obsługujące współdzielone odpowiedzi interaktywne renderują te same przyciski zatwierdzeń zarówno dla zatwierdzeń exec, jak i
|
||||
pluginów. Kanały bez współdzielonego interaktywnego UI przechodzą na zwykły tekst z instrukcjami `/approve`.
|
||||
Kanały obsługujące współdzielone interaktywne odpowiedzi renderują te same przyciski zatwierdzania zarówno dla zatwierdzeń exec, jak i
|
||||
pluginów. Kanały bez współdzielonego interaktywnego UI wracają do zwykłego tekstu z instrukcjami `/approve`.
|
||||
|
||||
### Zatwierdzenia w tym samym czacie na dowolnym kanale
|
||||
|
||||
Gdy żądanie zatwierdzenia exec lub pluginu pochodzi z dostarczalnej powierzchni czatu, ten sam czat
|
||||
może teraz domyślnie zatwierdzić je przez `/approve`. Dotyczy to kanałów takich jak Slack, Matrix i
|
||||
Microsoft Teams, oprócz istniejących już przepływów Web UI i terminal UI.
|
||||
może je teraz domyślnie zatwierdzić za pomocą `/approve`. Dotyczy to kanałów takich jak Slack, Matrix i
|
||||
Microsoft Teams, oprócz istniejących przepływów Web UI i terminal UI.
|
||||
|
||||
Ta współdzielona ścieżka polecenia tekstowego używa zwykłego modelu uwierzytelniania kanału dla tej rozmowy. Jeśli
|
||||
czat źródłowy może już wysyłać polecenia i otrzymywać odpowiedzi, żądania zatwierdzeń nie potrzebują już
|
||||
oddzielnego natywnego adaptera dostarczania tylko po to, by pozostać oczekujące.
|
||||
Ta współdzielona ścieżka poleceń tekstowych używa normalnego modelu uwierzytelniania kanału dla danej rozmowy. Jeśli
|
||||
czat źródłowy może już wysyłać polecenia i odbierać odpowiedzi, żądania zatwierdzenia nie potrzebują już
|
||||
osobnego natywnego adaptera dostarczania tylko po to, by pozostać w stanie oczekiwania.
|
||||
|
||||
Discord i Telegram również obsługują `/approve` w tym samym czacie, ale te kanały nadal używają swoich
|
||||
rozwiązanych list zatwierdzających do autoryzacji, nawet gdy natywne dostarczanie zatwierdzeń jest wyłączone.
|
||||
Discord i Telegram również obsługują `/approve` w tym samym czacie, ale te kanały nadal używają
|
||||
swojej rozpoznanej listy zatwierdzających do autoryzacji, nawet gdy natywne dostarczanie zatwierdzeń jest wyłączone.
|
||||
|
||||
Dla Telegram i innych natywnych klientów zatwierdzeń, które wywołują Gateway bezpośrednio,
|
||||
ten fallback jest celowo ograniczony do błędów typu „zatwierdzenie nie znalezione”. Rzeczywista
|
||||
odmowa/błąd zatwierdzenia exec nie wykonuje po cichu ponownej próby jako zatwierdzenie pluginu.
|
||||
Dla Telegrama i innych natywnych klientów zatwierdzeń, które wywołują Gateway bezpośrednio,
|
||||
to zachowanie zapasowe jest celowo ograniczone do błędów typu „nie znaleziono zatwierdzenia”. Rzeczywista
|
||||
odmowa/błąd zatwierdzenia exec nie powoduje cichego ponownego sprawdzenia jako zatwierdzenie pluginu.
|
||||
|
||||
### Natywne dostarczanie zatwierdzeń
|
||||
|
||||
Niektóre kanały mogą także działać jako natywni klienci zatwierdzeń. Natywni klienci dodają DM zatwierdzających, fanout czatu źródłowego
|
||||
oraz specyficzny dla kanału interaktywny UX zatwierdzeń ponad współdzielony przepływ `/approve`
|
||||
Niektóre kanały mogą również działać jako natywni klienci zatwierdzeń. Natywni klienci dodają DM-y zatwierdzających, fanout do czatu źródłowego
|
||||
oraz interaktywny UX zatwierdzania specyficzny dla kanału ponad współdzielony przepływ `/approve`
|
||||
w tym samym czacie.
|
||||
|
||||
Gdy natywne karty/przyciski zatwierdzeń są dostępne, ten natywny UI jest główną
|
||||
ścieżką skierowaną do agenta. Agent nie powinien również powielać zwykłego polecenia czatu
|
||||
`/approve`, chyba że wynik narzędzia mówi, że zatwierdzenia w czacie są niedostępne albo
|
||||
ręczne zatwierdzenie jest jedyną pozostałą ścieżką.
|
||||
Gdy dostępne są natywne karty/przyciski zatwierdzania, to natywne UI jest podstawową
|
||||
ścieżką widoczną dla agenta. Agent nie powinien również powielać zwykłego polecenia czatu
|
||||
`/approve`, chyba że wynik narzędzia wskazuje, że zatwierdzenia na czacie są niedostępne lub
|
||||
jedyną pozostałą ścieżką jest zatwierdzenie ręczne.
|
||||
|
||||
Model ogólny:
|
||||
|
||||
@ -473,103 +497,103 @@ Model ogólny:
|
||||
- `approvals.exec` kontroluje przekazywanie promptów zatwierdzeń do innych miejsc docelowych czatu
|
||||
- `channels.<channel>.execApprovals` kontroluje, czy dany kanał działa jako natywny klient zatwierdzeń
|
||||
|
||||
Natywni klienci zatwierdzeń automatycznie włączają dostarczanie najpierw do DM, gdy wszystkie poniższe warunki są spełnione:
|
||||
Natywni klienci zatwierdzeń automatycznie włączają dostarczanie z priorytetem DM, gdy spełnione są wszystkie poniższe warunki:
|
||||
|
||||
- kanał obsługuje natywne dostarczanie zatwierdzeń
|
||||
- zatwierdzający mogą zostać rozwiązani z jawnych `execApprovals.approvers` lub udokumentowanych źródeł fallback dla
|
||||
tego kanału
|
||||
- `channels.<channel>.execApprovals.enabled` jest nieustawione lub ma wartość `"auto"`
|
||||
- osoby zatwierdzające można rozpoznać na podstawie jawnego `execApprovals.approvers` lub
|
||||
udokumentowanych źródeł zapasowych tego kanału
|
||||
- `channels.<channel>.execApprovals.enabled` nie jest ustawione lub ma wartość `"auto"`
|
||||
|
||||
Ustaw `enabled: false`, aby jawnie wyłączyć natywnego klienta zatwierdzeń. Ustaw `enabled: true`, aby wymusić
|
||||
jego włączenie, gdy zatwierdzający się rozwiązują. Publiczne dostarczanie do czatu źródłowego pozostaje jawne przez
|
||||
`channels.<channel>.execApprovals.target`.
|
||||
jego włączenie, gdy uda się rozpoznać osoby zatwierdzające. Publiczne dostarczanie do czatu źródłowego pozostaje
|
||||
jawnie kontrolowane przez `channels.<channel>.execApprovals.target`.
|
||||
|
||||
FAQ: [Dlaczego istnieją dwie konfiguracje zatwierdzeń exec dla zatwierdzeń w czacie?](/help/faq#why-are-there-two-exec-approval-configs-for-chat-approvals)
|
||||
FAQ: [Dlaczego istnieją dwie konfiguracje zatwierdzeń exec dla zatwierdzeń na czacie?](/help/faq#why-are-there-two-exec-approval-configs-for-chat-approvals)
|
||||
|
||||
- Discord: `channels.discord.execApprovals.*`
|
||||
- Slack: `channels.slack.execApprovals.*`
|
||||
- Telegram: `channels.telegram.execApprovals.*`
|
||||
|
||||
Ci natywni klienci zatwierdzeń dodają routing DM i opcjonalny fanout do kanału ponad współdzielony
|
||||
Ci natywni klienci zatwierdzeń dodają routowanie do DM-ów i opcjonalny fanout do kanału ponad współdzielony
|
||||
przepływ `/approve` w tym samym czacie oraz współdzielone przyciski zatwierdzeń.
|
||||
|
||||
Współdzielone zachowanie:
|
||||
Wspólne zachowanie:
|
||||
|
||||
- Slack, Matrix, Microsoft Teams i podobne dostarczalne czaty używają zwykłego modelu uwierzytelniania kanału
|
||||
- Slack, Matrix, Microsoft Teams i podobne dostarczalne czaty używają normalnego modelu uwierzytelniania kanału
|
||||
dla `/approve` w tym samym czacie
|
||||
- gdy natywny klient zatwierdzeń włącza się automatycznie, domyślnym celem natywnego dostarczania są DM zatwierdzających
|
||||
- w przypadku Discord i Telegram tylko rozwiązani zatwierdzający mogą zatwierdzać lub odrzucać
|
||||
- zatwierdzający Discord mogą być jawni (`execApprovals.approvers`) lub wywnioskowani z `commands.ownerAllowFrom`
|
||||
- zatwierdzający Telegram mogą być jawni (`execApprovals.approvers`) lub wywnioskowani z istniejącej konfiguracji właściciela (`allowFrom`, plus `defaultTo` dla wiadomości bezpośrednich, gdy jest obsługiwane)
|
||||
- zatwierdzający Slack mogą być jawni (`execApprovals.approvers`) lub wywnioskowani z `commands.ownerAllowFrom`
|
||||
- natywne przyciski Slack zachowują rodzaj identyfikatora zatwierdzenia, więc identyfikatory `plugin:` mogą rozwiązywać zatwierdzenia pluginów
|
||||
bez drugiej lokalnej warstwy fallback w Slack
|
||||
- natywny routing DM/kanału Matrix i skróty reakcji obsługują zarówno zatwierdzenia exec, jak i pluginów;
|
||||
- gdy natywny klient zatwierdzeń włącza się automatycznie, domyślnym celem natywnego dostarczania są DM-y osób zatwierdzających
|
||||
- dla Discorda i Telegrama tylko rozpoznane osoby zatwierdzające mogą zatwierdzać lub odmawiać
|
||||
- osoby zatwierdzające w Discord mogą być jawne (`execApprovals.approvers`) lub wywnioskowane z `commands.ownerAllowFrom`
|
||||
- osoby zatwierdzające w Telegramie mogą być jawne (`execApprovals.approvers`) lub wywnioskowane z istniejącej konfiguracji ownera (`allowFrom` oraz `defaultTo` dla wiadomości bezpośrednich tam, gdzie jest obsługiwane)
|
||||
- osoby zatwierdzające w Slack mogą być jawne (`execApprovals.approvers`) lub wywnioskowane z `commands.ownerAllowFrom`
|
||||
- natywne przyciski Slack zachowują rodzaj id zatwierdzenia, więc identyfikatory `plugin:` mogą rozwiązywać zatwierdzenia pluginów
|
||||
bez drugiej lokalnej warstwy zapasowej specyficznej dla Slacka
|
||||
- natywne routowanie DM/kanału i skróty reakcji w Matrix obsługują zarówno zatwierdzenia exec, jak i pluginów;
|
||||
autoryzacja pluginów nadal pochodzi z `channels.matrix.dm.allowFrom`
|
||||
- osoba żądająca nie musi być zatwierdzającym
|
||||
- czat źródłowy może zatwierdzać bezpośrednio przez `/approve`, gdy dany czat już obsługuje polecenia i odpowiedzi
|
||||
- natywne przyciski zatwierdzeń Discord routują według rodzaju identyfikatora zatwierdzenia: identyfikatory `plugin:` trafiają
|
||||
bezpośrednio do zatwierdzeń pluginów, wszystko inne trafia do zatwierdzeń exec
|
||||
- natywne przyciski zatwierdzeń Telegram stosują ten sam ograniczony fallback exec→plugin co `/approve`
|
||||
- gdy natywny `target` włącza dostarczanie do czatu źródłowego, prompty zatwierdzeń zawierają tekst polecenia
|
||||
- oczekujące zatwierdzenia exec domyślnie wygasają po 30 minutach
|
||||
- jeśli żaden interfejs operatora ani skonfigurowany klient zatwierdzeń nie może przyjąć żądania, prompt przechodzi do `askFallback`
|
||||
- zgłaszający nie musi być osobą zatwierdzającą
|
||||
- czat źródłowy może zatwierdzać bezpośrednio za pomocą `/approve`, gdy ten czat już obsługuje polecenia i odpowiedzi
|
||||
- natywne przyciski zatwierdzeń Discord routują według rodzaju id zatwierdzenia: identyfikatory `plugin:` trafiają
|
||||
bezpośrednio do zatwierdzeń pluginów, a wszystko inne do zatwierdzeń exec
|
||||
- natywne przyciski zatwierdzeń Telegram stosują to samo ograniczone zachowanie zapasowe exec-to-plugin co `/approve`
|
||||
- gdy natywne `target` włącza dostarczanie do czatu źródłowego, prompty zatwierdzeń zawierają tekst polecenia
|
||||
- oczekujące zatwierdzenia exec wygasają domyślnie po 30 minutach
|
||||
- jeśli żaden UI operatora ani skonfigurowany klient zatwierdzeń nie może przyjąć żądania, prompt wraca do `askFallback`
|
||||
|
||||
Telegram domyślnie używa DM zatwierdzających (`target: "dm"`). Możesz przełączyć na `channel` lub `both`, gdy
|
||||
chcesz, aby prompty zatwierdzeń pojawiały się również w źródłowym czacie/temacie Telegram. Dla tematów forum Telegram
|
||||
OpenClaw zachowuje temat dla promptu zatwierdzenia i follow-up po zatwierdzeniu.
|
||||
Telegram domyślnie kieruje do DM-ów osób zatwierdzających (`target: "dm"`). Możesz przełączyć na `channel` lub `both`, gdy
|
||||
chcesz, aby prompty zatwierdzeń pojawiały się również w źródłowym czacie/wątku Telegrama. Dla tematów forum Telegrama
|
||||
OpenClaw zachowuje temat dla promptu zatwierdzenia oraz follow-up po zatwierdzeniu.
|
||||
|
||||
Zobacz:
|
||||
|
||||
- [Discord](/channels/discord)
|
||||
- [Telegram](/channels/telegram)
|
||||
|
||||
### Przepływ IPC macOS
|
||||
__OC_I18N_900008__
|
||||
### Przepływ IPC na macOS
|
||||
__OC_I18N_900009__
|
||||
Uwagi dotyczące bezpieczeństwa:
|
||||
|
||||
- Tryb gniazda Unix `0600`, token przechowywany w `exec-approvals.json`.
|
||||
- Sprawdzenie peera z tym samym UID.
|
||||
- Sprawdzanie peera z tym samym UID.
|
||||
- Challenge/response (nonce + token HMAC + hash żądania) + krótki TTL.
|
||||
|
||||
## Zdarzenia systemowe
|
||||
|
||||
Cykl życia exec jest ujawniany jako komunikaty systemowe:
|
||||
|
||||
- `Exec running` (tylko jeśli polecenie przekracza próg powiadomienia o uruchomieniu)
|
||||
- `Exec running` (tylko jeśli polecenie przekroczy próg powiadomienia o wykonywaniu)
|
||||
- `Exec finished`
|
||||
- `Exec denied`
|
||||
|
||||
Są one publikowane do sesji agenta po zgłoszeniu zdarzenia przez węzeł.
|
||||
Zatwierdzenia exec na hoście gateway emitują ten sam cykl życia zdarzeń, gdy polecenie się kończy (oraz opcjonalnie, gdy działa dłużej niż próg).
|
||||
Exec objęte zatwierdzeniem używają ponownie identyfikatora zatwierdzenia jako `runId` w tych komunikatach, aby ułatwić korelację.
|
||||
Są one publikowane do sesji agenta po zgłoszeniu zdarzenia przez node.
|
||||
Zatwierdzenia exec na hoście gateway emitują te same zdarzenia cyklu życia, gdy polecenie się zakończy (oraz opcjonalnie, gdy działa dłużej niż próg).
|
||||
Exec objęte zatwierdzeniem używają ponownie identyfikatora zatwierdzenia jako `runId` w tych komunikatach, co ułatwia korelację.
|
||||
|
||||
## Zachowanie po odrzuceniu zatwierdzenia
|
||||
## Zachowanie przy odmowie zatwierdzenia
|
||||
|
||||
Gdy asynchroniczne zatwierdzenie exec zostanie odrzucone, OpenClaw uniemożliwia agentowi ponowne użycie
|
||||
wyniku z jakiegokolwiek wcześniejszego uruchomienia tego samego polecenia w sesji. Powód odrzucenia
|
||||
jest przekazywany z jawną wskazówką, że nie ma dostępnych danych wyjściowych polecenia, co zatrzymuje
|
||||
Gdy asynchroniczne zatwierdzenie exec zostaje odrzucone, OpenClaw uniemożliwia agentowi ponowne użycie
|
||||
wyników z wcześniejszego uruchomienia tego samego polecenia w sesji. Powód odmowy
|
||||
jest przekazywany wraz z jawną wskazówką, że żadne dane wyjściowe polecenia nie są dostępne, co powstrzymuje
|
||||
agenta przed twierdzeniem, że istnieją nowe dane wyjściowe, lub przed powtarzaniem odrzuconego polecenia z
|
||||
nieaktualnymi wynikami z wcześniejszego udanego uruchomienia.
|
||||
nieaktualnymi wynikami z wcześniejszego pomyślnego uruchomienia.
|
||||
|
||||
## Konsekwencje
|
||||
|
||||
- **full** daje szerokie uprawnienia; gdy to możliwe, preferuj listy dozwolonych.
|
||||
- **ask** pozwala Ci zachować kontrolę, jednocześnie umożliwiając szybkie zatwierdzenia.
|
||||
- **full** ma szerokie uprawnienia; gdy to możliwe, preferuj listy dozwolonych.
|
||||
- **ask** pozwala Ci zachować kontrolę, a jednocześnie umożliwia szybkie zatwierdzanie.
|
||||
- Listy dozwolonych per agent zapobiegają przenikaniu zatwierdzeń jednego agenta do innych.
|
||||
- Zatwierdzenia mają zastosowanie tylko do żądań exec hosta od **autoryzowanych nadawców**. Nieautoryzowani nadawcy nie mogą wydawać `/exec`.
|
||||
- `/exec security=full` to wygodna opcja na poziomie sesji dla autoryzowanych operatorów i z założenia pomija zatwierdzenia.
|
||||
Aby twardo zablokować exec hosta, ustaw security zatwierdzeń na `deny` lub zablokuj narzędzie `exec` przez politykę narzędzi.
|
||||
- `/exec security=full` to wygodne ustawienie na poziomie sesji dla autoryzowanych operatorów i zgodnie z założeniem pomija zatwierdzenia.
|
||||
Aby całkowicie zablokować exec hosta, ustaw security zatwierdzeń na `deny` lub zablokuj narzędzie `exec` za pomocą polityki narzędzi.
|
||||
|
||||
Powiązane:
|
||||
|
||||
- [Narzędzie exec](/pl/tools/exec)
|
||||
- [Tryb elevated](/pl/tools/elevated)
|
||||
- [Exec tool](/pl/tools/exec)
|
||||
- [Elevated mode](/pl/tools/elevated)
|
||||
- [Skills](/pl/tools/skills)
|
||||
|
||||
## Powiązane
|
||||
|
||||
- [Exec](/pl/tools/exec) — narzędzie do wykonywania poleceń powłoki
|
||||
- [Sandboxing](/pl/gateway/sandboxing) — tryby sandbox i dostęp do obszaru roboczego
|
||||
- [Bezpieczeństwo](/pl/gateway/security) — model bezpieczeństwa i utwardzanie
|
||||
- [Sandboxing](/pl/gateway/sandboxing) — tryby sandboxa i dostęp do obszaru roboczego
|
||||
- [Security](/pl/gateway/security) — model bezpieczeństwa i utwardzanie
|
||||
- [Sandbox vs Tool Policy vs Elevated](/pl/gateway/sandbox-vs-tool-policy-vs-elevated) — kiedy używać każdego z nich
|
||||
|
||||
Loading…
Reference in New Issue
Block a user