chore(i18n): refresh pl translations
This commit is contained in:
openclaw-docs-i18n[bot]
parent
00251111b5
commit
b31940bd08
File diff suppressed because it is too large
Load Diff
@ -1,19 +1,19 @@
|
||||
---
|
||||
read_when:
|
||||
- Chcesz zrozumieć automatyczne kompaktowanie i /compact
|
||||
- Chcesz zrozumieć automatyczną kompakcję i /compact
|
||||
- Debugujesz długie sesje osiągające limity kontekstu
|
||||
summary: Jak OpenClaw podsumowuje długie rozmowy, aby zmieścić się w limitach modelu
|
||||
title: Kompaktowanie
|
||||
summary: Jak OpenClaw streszcza długie rozmowy, aby mieścić się w limitach modelu
|
||||
title: Kompakcja
|
||||
x-i18n:
|
||||
generated_at: "2026-04-05T13:50:10Z"
|
||||
generated_at: "2026-04-08T02:14:29Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 4c6dbd6ebdcd5f918805aafdc153925efef3e130faa3fab3c630832e938219fc
|
||||
source_hash: e6590b82a8c3a9c310998d653459ca4d8612495703ca0a8d8d306d7643142fd1
|
||||
source_path: concepts/compaction.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Kompaktowanie
|
||||
# Kompakcja
|
||||
|
||||
Każdy model ma okno kontekstu — maksymalną liczbę tokenów, które może przetworzyć.
|
||||
Gdy rozmowa zbliża się do tego limitu, OpenClaw **kompaktuje** starsze wiadomości
|
||||
@ -21,23 +21,23 @@ do postaci podsumowania, aby czat mógł być kontynuowany.
|
||||
|
||||
## Jak to działa
|
||||
|
||||
1. Starsze tury rozmowy są podsumowywane do zwartego wpisu.
|
||||
1. Starsze tury rozmowy są streszczane do zwartego wpisu.
|
||||
2. Podsumowanie jest zapisywane w transkrypcie sesji.
|
||||
3. Ostatnie wiadomości pozostają nienaruszone.
|
||||
|
||||
Gdy OpenClaw dzieli historię na fragmenty do kompaktowania, utrzymuje wywołania
|
||||
narzędzi asystenta sparowane z odpowiadającymi im wpisami `toolResult`. Jeśli punkt podziału
|
||||
wypada wewnątrz bloku narzędzia, OpenClaw przesuwa granicę tak, aby para pozostała razem, a
|
||||
bieżący niepodsumowany ogon został zachowany.
|
||||
Gdy OpenClaw dzieli historię na fragmenty do kompaktowania, zachowuje wywołania
|
||||
narzędzi asystenta sparowane z odpowiadającymi im wpisami `toolResult`. Jeśli punkt
|
||||
podziału wypada wewnątrz bloku narzędzia, OpenClaw przesuwa granicę tak, aby para
|
||||
pozostała razem, a bieżący niepodsumowany ogon został zachowany.
|
||||
|
||||
Pełna historia rozmowy pozostaje na dysku. Kompaktowanie zmienia tylko to,
|
||||
co model widzi w następnej turze.
|
||||
Pełna historia rozmowy pozostaje na dysku. Kompakcja zmienia tylko to, co model
|
||||
widzi w następnej turze.
|
||||
|
||||
## Automatyczne kompaktowanie
|
||||
## Automatyczna kompakcja
|
||||
|
||||
Automatyczne kompaktowanie jest domyślnie włączone. Uruchamia się, gdy sesja zbliża się do limitu
|
||||
kontekstu albo gdy model zwróci błąd przepełnienia kontekstu (w takim przypadku
|
||||
OpenClaw kompaktuje i ponawia próbę). Typowe sygnatury przepełnienia obejmują
|
||||
Automatyczna kompakcja jest domyślnie włączona. Uruchamia się, gdy sesja zbliża się do limitu
|
||||
kontekstu albo gdy model zwraca błąd przepełnienia kontekstu (w takim przypadku
|
||||
OpenClaw wykonuje kompakcję i ponawia próbę). Typowe sygnatury przepełnienia to
|
||||
`request_too_large`, `context length exceeded`, `input exceeds the maximum
|
||||
number of tokens`, `input token count exceeds the maximum number of input
|
||||
tokens`, `input is too long for the model` oraz `ollama error: context length
|
||||
@ -45,21 +45,86 @@ exceeded`.
|
||||
|
||||
<Info>
|
||||
Przed kompaktowaniem OpenClaw automatycznie przypomina agentowi o zapisaniu ważnych
|
||||
notatek do plików [memory](/concepts/memory). Zapobiega to utracie kontekstu.
|
||||
notatek do plików [memory](/pl/concepts/memory). Zapobiega to utracie kontekstu.
|
||||
</Info>
|
||||
|
||||
## Ręczne kompaktowanie
|
||||
Użyj ustawienia `agents.defaults.compaction` w pliku `openclaw.json`, aby skonfigurować zachowanie kompaktowania (tryb, docelową liczbę tokenów itd.).
|
||||
Streszczanie podczas kompaktowania domyślnie zachowuje nieprzezroczyste identyfikatory (`identifierPolicy: "strict"`). Możesz to zmienić za pomocą `identifierPolicy: "off"` albo podać własny tekst przy użyciu `identifierPolicy: "custom"` i `identifierInstructions`.
|
||||
|
||||
Wpisz `/compact` w dowolnym czacie, aby wymusić kompaktowanie. Dodaj instrukcje,
|
||||
aby ukierunkować podsumowanie:
|
||||
Opcjonalnie możesz określić inny model do streszczania podczas kompaktowania za pomocą `agents.defaults.compaction.model`. Jest to przydatne, gdy podstawowy model jest lokalny lub mały, a chcesz, aby podsumowania kompaktowania były tworzone przez bardziej zaawansowany model. To ustawienie przyjmuje dowolny ciąg `provider/model-id`:
|
||||
|
||||
```json
|
||||
{
|
||||
"agents": {
|
||||
"defaults": {
|
||||
"compaction": {
|
||||
"model": "openrouter/anthropic/claude-sonnet-4-6"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Działa to również z modelami lokalnymi, na przykład z drugim modelem Ollama przeznaczonym do streszczania albo specjalistycznym modelem dostrojonym do kompaktowania:
|
||||
|
||||
```json
|
||||
{
|
||||
"agents": {
|
||||
"defaults": {
|
||||
"compaction": {
|
||||
"model": "ollama/llama3.1:8b"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Jeśli nie jest ustawione, kompaktowanie używa podstawowego modelu agenta.
|
||||
|
||||
## Wtyczkowi dostawcy kompaktowania
|
||||
|
||||
Plugins mogą rejestrować niestandardowego dostawcę kompaktowania za pomocą `registerCompactionProvider()` w API pluginu. Gdy dostawca jest zarejestrowany i skonfigurowany, OpenClaw deleguje streszczanie do niego zamiast do wbudowanego potoku LLM.
|
||||
|
||||
Aby użyć zarejestrowanego dostawcy, ustaw identyfikator dostawcy w konfiguracji:
|
||||
|
||||
```json
|
||||
{
|
||||
"agents": {
|
||||
"defaults": {
|
||||
"compaction": {
|
||||
"provider": "my-provider"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Ustawienie `provider` automatycznie wymusza `mode: "safeguard"`. Dostawcy otrzymują te same instrukcje kompaktowania i tę samą politykę zachowywania identyfikatorów co ścieżka wbudowana, a OpenClaw nadal zachowuje kontekst sufiksu ostatnich tur i podzielonych tur po wyniku dostawcy. Jeśli dostawca zakończy się niepowodzeniem albo zwróci pusty wynik, OpenClaw wraca do wbudowanego streszczania przez LLM.
|
||||
|
||||
## Automatyczna kompakcja (domyślnie włączona)
|
||||
|
||||
Gdy sesja zbliża się do okna kontekstu modelu lub je przekracza, OpenClaw uruchamia automatyczną kompakcję i może ponowić pierwotne żądanie, używając skompaktowanego kontekstu.
|
||||
|
||||
Zobaczysz:
|
||||
|
||||
- `🧹 Auto-compaction complete` w trybie verbose
|
||||
- `/status` pokazujące `🧹 Compactions: <count>`
|
||||
|
||||
Przed kompaktowaniem OpenClaw może uruchomić **ciche opróżnienie pamięci** tury, aby zapisać
|
||||
trwałe notatki na dysk. Szczegóły i konfigurację znajdziesz w sekcji [Memory](/pl/concepts/memory).
|
||||
|
||||
## Ręczna kompakcja
|
||||
|
||||
Wpisz `/compact` w dowolnym czacie, aby wymusić kompakcję. Dodaj instrukcje, aby ukierunkować
|
||||
podsumowanie:
|
||||
|
||||
```
|
||||
/compact Skup się na decyzjach projektowych dotyczących API
|
||||
/compact Focus on the API design decisions
|
||||
```
|
||||
|
||||
## Używanie innego modelu
|
||||
|
||||
Domyślnie kompaktowanie używa głównego modelu agenta. Możesz użyć bardziej
|
||||
Domyślnie kompaktowanie używa podstawowego modelu agenta. Możesz użyć bardziej
|
||||
zaawansowanego modelu, aby uzyskać lepsze podsumowania:
|
||||
|
||||
```json5
|
||||
@ -91,39 +156,39 @@ się rozpoczyna, włącz `notifyUser`:
|
||||
}
|
||||
```
|
||||
|
||||
Po włączeniu użytkownik widzi krótki komunikat (na przykład „Kompaktowanie
|
||||
Po włączeniu użytkownik zobaczy krótki komunikat (na przykład „Kompaktowanie
|
||||
kontekstu...”) na początku każdego uruchomienia kompaktowania.
|
||||
|
||||
## Kompaktowanie a przycinanie
|
||||
## Kompakcja a przycinanie
|
||||
|
||||
| | Kompaktowanie | Przycinanie |
|
||||
| | Kompakcja | Przycinanie |
|
||||
| ---------------- | ----------------------------- | -------------------------------- |
|
||||
| **Co robi** | Podsumowuje starszą rozmowę | Przycina stare wyniki narzędzi |
|
||||
| **Co robi** | Streszcza starszą rozmowę | Przycina stare wyniki narzędzi |
|
||||
| **Zapisywane?** | Tak (w transkrypcie sesji) | Nie (tylko w pamięci, na żądanie) |
|
||||
| **Zakres** | Cała rozmowa | Tylko wyniki narzędzi |
|
||||
|
||||
[Przycinanie sesji](/concepts/session-pruning) to lżejsze uzupełnienie, które
|
||||
przycina dane wyjściowe narzędzi bez tworzenia podsumowania.
|
||||
[Przycinanie sesji](/pl/concepts/session-pruning) to lżejsze uzupełnienie, które
|
||||
przycina dane wyjściowe narzędzi bez streszczania.
|
||||
|
||||
## Rozwiązywanie problemów
|
||||
|
||||
**Kompaktowanie uruchamia się zbyt często?** Okno kontekstu modelu może być małe albo
|
||||
dane wyjściowe narzędzi mogą być duże. Spróbuj włączyć
|
||||
[przycinanie sesji](/concepts/session-pruning).
|
||||
**Kompaktowanie występuje zbyt często?** Okno kontekstu modelu może być małe albo wyniki
|
||||
narzędzi mogą być duże. Spróbuj włączyć
|
||||
[przycinanie sesji](/pl/concepts/session-pruning).
|
||||
|
||||
**Czy po kompaktowaniu kontekst wydaje się nieaktualny?** Użyj `/compact Skup się na <temat>`, aby
|
||||
ukierunkować podsumowanie, albo włącz [opróżnianie memory](/concepts/memory), aby notatki
|
||||
**Czy po kompaktowaniu kontekst wydaje się nieaktualny?** Użyj `/compact Focus on <topic>`, aby
|
||||
ukierunkować podsumowanie, albo włącz [opróżnianie pamięci](/pl/concepts/memory), aby notatki
|
||||
zostały zachowane.
|
||||
|
||||
**Potrzebujesz czystego startu?** `/new` rozpoczyna nową sesję bez kompaktowania.
|
||||
|
||||
Zaawansowaną konfigurację (rezerwowe tokeny, zachowanie identyfikatorów, niestandardowe
|
||||
silniki kontekstu, kompaktowanie po stronie serwera OpenAI) opisano w
|
||||
[Dogłębne omówienie zarządzania sesją](/reference/session-management-compaction).
|
||||
Zaawansowaną konfigurację (rezerwę tokenów, zachowywanie identyfikatorów, niestandardowe
|
||||
silniki kontekstu, kompaktowanie po stronie serwera OpenAI) znajdziesz w
|
||||
[szczegółowym omówieniu zarządzania sesją](/pl/reference/session-management-compaction).
|
||||
|
||||
## Powiązane
|
||||
|
||||
- [Session](/concepts/session) — zarządzanie sesją i jej cykl życia
|
||||
- [Session Pruning](/concepts/session-pruning) — przycinanie wyników narzędzi
|
||||
- [Context](/concepts/context) — jak budowany jest kontekst dla tur agenta
|
||||
- [Session](/pl/concepts/session) — zarządzanie sesją i jej cykl życia
|
||||
- [Session Pruning](/pl/concepts/session-pruning) — przycinanie wyników narzędzi
|
||||
- [Context](/pl/concepts/context) — jak budowany jest kontekst dla tur agenta
|
||||
- [Hooks](/pl/automation/hooks) — hooki cyklu życia kompaktowania (before_compaction, after_compaction)
|
||||
|
||||
@ -1,50 +1,51 @@
|
||||
---
|
||||
read_when:
|
||||
- Rozszerzasz qa-lab lub qa-channel
|
||||
- Dodajesz scenariusze QA oparte na repozytorium
|
||||
- Budujesz automatyzację QA o większym realizmie wokół dashboardu Gateway
|
||||
summary: Kształt prywatnej automatyzacji QA dla qa-lab, qa-channel, scenariuszy seed i raportów protokołu
|
||||
- Rozszerzanie qa-lab lub qa-channel
|
||||
- Dodawanie scenariuszy QA wspieranych przez repozytorium
|
||||
- Tworzenie bardziej realistycznej automatyzacji QA wokół panelu Gateway
|
||||
summary: Prywatna struktura automatyzacji QA dla qa-lab, qa-channel, scenariuszy seed i raportów protokołu
|
||||
title: Automatyzacja QA E2E
|
||||
x-i18n:
|
||||
generated_at: "2026-04-07T09:44:13Z"
|
||||
generated_at: "2026-04-08T02:14:14Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: b68cfcfb50532dbda93ba62e1ed8dc6a7ddd4214cb1db8c9a84a7bc0b32b3060
|
||||
source_hash: 3b4aa5acc8e77303f4045d4f04372494cae21b89d2fdaba856dbb4855ced9d27
|
||||
source_path: concepts/qa-e2e-automation.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Automatyzacja QA E2E
|
||||
|
||||
Prywatny stos QA ma testować OpenClaw w bardziej realistyczny,
|
||||
kanałowy sposób niż pojedynczy test jednostkowy.
|
||||
Prywatny stos QA ma na celu testowanie OpenClaw w bardziej realistyczny,
|
||||
kanałowy sposób niż może to zrobić pojedynczy test jednostkowy.
|
||||
|
||||
Obecne elementy:
|
||||
|
||||
- `extensions/qa-channel`: syntetyczny kanał wiadomości z powierzchniami DM, kanału, wątku,
|
||||
reakcji, edycji i usuwania.
|
||||
- `extensions/qa-lab`: interfejs debugowania i magistrala QA do obserwacji transkryptu,
|
||||
- `extensions/qa-lab`: interfejs debuggera i magistrala QA do obserwowania transkryptu,
|
||||
wstrzykiwania wiadomości przychodzących i eksportowania raportu Markdown.
|
||||
- `qa/`: zasoby seed oparte na repozytorium dla zadania startowego i bazowych scenariuszy QA.
|
||||
- `qa/`: zasoby seed wspierane przez repozytorium dla zadania startowego i bazowych
|
||||
scenariuszy QA.
|
||||
|
||||
Obecny przepływ pracy operatora QA to dwupanelowa witryna QA:
|
||||
|
||||
- Po lewej: dashboard Gateway (Control UI) z agentem.
|
||||
- Po prawej: QA Lab, pokazujący transkrypt w stylu Slack i plan scenariusza.
|
||||
- Po lewej: panel Gateway (Control UI) z agentem.
|
||||
- Po prawej: QA Lab, pokazujący transkrypt w stylu Slacka i plan scenariusza.
|
||||
|
||||
Uruchom ją poleceniem:
|
||||
Uruchom za pomocą:
|
||||
|
||||
```bash
|
||||
pnpm qa:lab:up
|
||||
```
|
||||
|
||||
To buduje witrynę QA, uruchamia obsługiwaną przez Docker ścieżkę gateway i udostępnia
|
||||
stronę QA Lab, na której operator lub pętla automatyzacji może dać agentowi misję
|
||||
QA, obserwować rzeczywiste zachowanie kanału oraz rejestrować, co działało, co się nie powiodło
|
||||
i co pozostało zablokowane.
|
||||
To buduje witrynę QA, uruchamia ścieżkę Gateway opartą na Dockerze i udostępnia
|
||||
stronę QA Lab, na której operator lub pętla automatyzacji może przekazać agentowi
|
||||
misję QA, obserwować rzeczywiste zachowanie kanału oraz rejestrować, co zadziałało,
|
||||
co się nie powiodło i co pozostało zablokowane.
|
||||
|
||||
Aby szybciej iterować nad interfejsem QA Lab bez przebudowywania obrazu Dockera za każdym razem,
|
||||
uruchom stos z bind-mountowanym bundle QA Lab:
|
||||
Aby szybciej iterować nad interfejsem QA Lab bez każdorazowego przebudowywania obrazu Docker,
|
||||
uruchom stos z pakietem QA Lab montowanym przez bind mount:
|
||||
|
||||
```bash
|
||||
pnpm openclaw qa docker-build-image
|
||||
@ -53,36 +54,35 @@ pnpm qa:lab:up:fast
|
||||
pnpm qa:lab:watch
|
||||
```
|
||||
|
||||
`qa:lab:up:fast` utrzymuje usługi Dockera na wcześniej zbudowanym obrazie i bind-mountuje
|
||||
`qa:lab:up:fast` utrzymuje usługi Dockera na wstępnie zbudowanym obrazie i montuje przez bind mount
|
||||
`extensions/qa-lab/web/dist` do kontenera `qa-lab`. `qa:lab:watch`
|
||||
przebudowuje ten bundle po zmianach, a przeglądarka automatycznie się przeładowuje, gdy hash zasobów QA Lab się zmieni.
|
||||
przebudowuje ten pakiet przy zmianach, a przeglądarka automatycznie przeładowuje się, gdy hash zasobu QA Lab się zmienia.
|
||||
|
||||
## Seedy oparte na repozytorium
|
||||
## Seedy wspierane przez repozytorium
|
||||
|
||||
Zasoby seed znajdują się w `qa/`:
|
||||
|
||||
- `qa/QA_KICKOFF_TASK.md`
|
||||
- `qa/seed-scenarios.json`
|
||||
- `qa/scenarios.md`
|
||||
|
||||
Celowo znajdują się one w git, aby plan QA był widoczny zarówno dla ludzi, jak i dla
|
||||
agenta. Lista bazowa powinna pozostać wystarczająco szeroka, aby obejmować:
|
||||
Są one celowo przechowywane w git, aby plan QA był widoczny zarówno dla ludzi, jak i dla
|
||||
agenta. Lista bazowa powinna pozostać na tyle szeroka, aby obejmować:
|
||||
|
||||
- czat DM i kanałowy
|
||||
- rozmowy DM i kanałowe
|
||||
- zachowanie wątków
|
||||
- cykl życia akcji na wiadomościach
|
||||
- wywołania zwrotne cron
|
||||
- cykl życia działań na wiadomościach
|
||||
- wywołania cron
|
||||
- przywoływanie pamięci
|
||||
- przełączanie modeli
|
||||
- przekazanie do subagenta
|
||||
- odczyt repozytorium i dokumentacji
|
||||
- czytanie repozytorium i dokumentacji
|
||||
- jedno małe zadanie build, takie jak Lobster Invaders
|
||||
|
||||
## Raportowanie
|
||||
|
||||
`qa-lab` eksportuje raport protokołu Markdown na podstawie obserwowanej osi czasu magistrali.
|
||||
`qa-lab` eksportuje raport protokołu w Markdown na podstawie obserwowanej osi czasu magistrali.
|
||||
Raport powinien odpowiadać na pytania:
|
||||
|
||||
- Co działało
|
||||
- Co zadziałało
|
||||
- Co się nie powiodło
|
||||
- Co pozostało zablokowane
|
||||
- Jakie scenariusze uzupełniające warto dodać
|
||||
@ -90,5 +90,5 @@ Raport powinien odpowiadać na pytania:
|
||||
## Powiązana dokumentacja
|
||||
|
||||
- [Testowanie](/pl/help/testing)
|
||||
- [QA Channel](/pl/channels/qa-channel)
|
||||
- [Dashboard](/web/dashboard)
|
||||
- [Kanał QA](/pl/channels/qa-channel)
|
||||
- [Panel](/web/dashboard)
|
||||
|
||||
@ -1,102 +1,99 @@
|
||||
---
|
||||
read_when:
|
||||
- Edytujesz tekst promptu systemowego, listę narzędzi albo sekcje czasu/heartbeat
|
||||
- Zmieniasz zachowanie bootstrapu workspace lub wstrzykiwania Skills
|
||||
- Edytowanie tekstu promptu systemowego, listy narzędzi lub sekcji czasu/heartbeatów
|
||||
- Zmiana zachowania bootstrapu workspace lub wstrzykiwania Skills
|
||||
summary: Co zawiera prompt systemowy OpenClaw i jak jest składany
|
||||
title: Prompt systemowy
|
||||
x-i18n:
|
||||
generated_at: "2026-04-05T13:52:10Z"
|
||||
generated_at: "2026-04-08T02:14:35Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: f14ba7f16dda81ac973d72be05931fa246bdfa0e1068df1a84d040ebd551c236
|
||||
source_hash: e55fc886bc8ec47584d07c9e60dfacd964dc69c7db976ea373877dc4fe09a79a
|
||||
source_path: concepts/system-prompt.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Prompt systemowy
|
||||
|
||||
OpenClaw buduje niestandardowy prompt systemowy dla każdego uruchomienia agenta. Prompt jest **własnością OpenClaw** i nie używa domyślnego promptu pi-coding-agent.
|
||||
OpenClaw tworzy niestandardowy prompt systemowy dla każdego uruchomienia agenta. Prompt jest **własnością OpenClaw** i nie używa domyślnego promptu pi-coding-agent.
|
||||
|
||||
Prompt jest składany przez OpenClaw i wstrzykiwany do każdego uruchomienia agenta.
|
||||
|
||||
Provider plugins mogą dodawać świadome pamięci podręcznej wskazówki do promptu bez zastępowania
|
||||
pełnego promptu należącego do OpenClaw. Runtime dostawcy może:
|
||||
Wtyczki dostawców mogą dodawać wskazówki do promptu uwzględniające pamięć podręczną bez zastępowania pełnego promptu należącego do OpenClaw. Środowisko wykonawcze dostawcy może:
|
||||
|
||||
- zastąpić mały zestaw nazwanych sekcji rdzeniowych (`interaction_style`,
|
||||
- zastąpić mały zestaw nazwanych sekcji rdzenia (`interaction_style`,
|
||||
`tool_call_style`, `execution_bias`)
|
||||
- wstrzyknąć **stabilny prefiks** powyżej granicy pamięci podręcznej promptu
|
||||
- wstrzyknąć **dynamiczny sufiks** poniżej granicy pamięci podręcznej promptu
|
||||
|
||||
Używaj wkładów należących do dostawcy do dostrajania specyficznego dla rodziny modeli. Zachowaj starszą
|
||||
mutację promptu `before_prompt_build` dla zgodności albo dla naprawdę globalnych zmian promptu, a nie dla zwykłego zachowania dostawcy.
|
||||
Używaj wkładów należących do dostawcy do strojenia specyficznego dla rodziny modeli. Zachowaj starszą mutację promptu `before_prompt_build` dla zgodności lub naprawdę globalnych zmian promptu, a nie dla typowego zachowania dostawcy.
|
||||
|
||||
## Struktura
|
||||
|
||||
Prompt jest celowo zwięzły i używa stałych sekcji:
|
||||
|
||||
- **Tooling**: przypomnienie o źródle prawdy dla narzędzi strukturalnych oraz wskazówki runtime dotyczące użycia narzędzi.
|
||||
- **Safety**: krótkie przypomnienie o zasadach bezpieczeństwa, aby unikać zachowań nastawionych na zdobywanie władzy lub omijanie nadzoru.
|
||||
- **Skills** (gdy dostępne): mówi modelowi, jak w razie potrzeby ładować instrukcje umiejętności.
|
||||
- **OpenClaw Self-Update**: jak bezpiecznie sprawdzać konfigurację za pomocą
|
||||
`config.schema.lookup`, poprawiać konfigurację przez `config.patch`, zastępować pełną
|
||||
konfigurację przez `config.apply` oraz uruchamiać `update.run` tylko na wyraźne żądanie użytkownika. Narzędzie `gateway`, dostępne wyłącznie dla właściciela, również odmawia przepisywania
|
||||
- **Narzędzia**: przypomnienie o źródle prawdy dla narzędzi strukturalnych oraz wskazówki środowiska wykonawczego dotyczące użycia narzędzi.
|
||||
- **Bezpieczeństwo**: krótkie przypomnienie o zabezpieczeniach, aby unikać zachowań dążących do przejęcia kontroli lub obchodzenia nadzoru.
|
||||
- **Skills** (gdy są dostępne): informuje model, jak na żądanie wczytywać instrukcje skillów.
|
||||
- **Samoaktualizacja OpenClaw**: jak bezpiecznie sprawdzać konfigurację za pomocą
|
||||
`config.schema.lookup`, poprawiać konfigurację za pomocą `config.patch`, zastępować pełną
|
||||
konfigurację za pomocą `config.apply` oraz uruchamiać `update.run` tylko na wyraźną prośbę użytkownika. Narzędzie `gateway`, dostępne tylko dla właściciela, również odmawia przepisywania
|
||||
`tools.exec.ask` / `tools.exec.security`, w tym starszych aliasów `tools.bash.*`,
|
||||
które normalizują się do tych chronionych ścieżek exec.
|
||||
które są normalizowane do tych chronionych ścieżek exec.
|
||||
- **Workspace**: katalog roboczy (`agents.defaults.workspace`).
|
||||
- **Documentation**: lokalna ścieżka do dokumentacji OpenClaw (repozytorium lub pakiet npm) oraz kiedy ją czytać.
|
||||
- **Workspace Files (injected)**: wskazuje, że pliki bootstrap są dołączone poniżej.
|
||||
- **Sandbox** (gdy włączony): wskazuje środowisko sandbox, ścieżki sandboxu i to, czy dostępny jest exec z podwyższonymi uprawnieniami.
|
||||
- **Current Date & Time**: lokalny czas użytkownika, strefa czasowa i format czasu.
|
||||
- **Reply Tags**: opcjonalna składnia tagów odpowiedzi dla obsługiwanych dostawców.
|
||||
- **Heartbeats**: prompt heartbeat i zachowanie potwierdzeń.
|
||||
- **Runtime**: host, system operacyjny, node, model, katalog główny repozytorium (gdy wykryty), poziom myślenia (jedna linia).
|
||||
- **Reasoning**: bieżący poziom widoczności + wskazówka dotycząca przełączania /reasoning.
|
||||
- **Dokumentacja**: lokalna ścieżka do dokumentacji OpenClaw (repozytorium lub pakiet npm) oraz informacja, kiedy ją czytać.
|
||||
- **Pliki workspace (wstrzyknięte)**: wskazuje, że pliki bootstrap są dołączone poniżej.
|
||||
- **Sandbox** (gdy włączony): wskazuje środowisko uruchomieniowe sandbox, ścieżki sandboxa oraz to, czy podwyższone exec jest dostępne.
|
||||
- **Bieżąca data i godzina**: lokalny czas użytkownika, strefa czasowa i format czasu.
|
||||
- **Tagi odpowiedzi**: opcjonalna składnia tagów odpowiedzi dla obsługiwanych dostawców.
|
||||
- **Heartbeaty**: prompt heartbeatów i zachowanie potwierdzeń, gdy heartbeaty są włączone dla domyślnego agenta.
|
||||
- **Środowisko wykonawcze**: host, system operacyjny, node, katalog główny repozytorium (gdy wykryty), poziom myślenia (jedna linia).
|
||||
- **Rozumowanie**: bieżący poziom widoczności + podpowiedź przełączania `/reasoning`.
|
||||
|
||||
Sekcja Tooling zawiera również wskazówki runtime dotyczące długotrwałej pracy:
|
||||
Sekcja Narzędzia zawiera również wskazówki środowiska wykonawczego dla długotrwałej pracy:
|
||||
|
||||
- używaj cron do przyszłych działań następczych (`check back later`, przypomnienia, praca cykliczna)
|
||||
zamiast pętli `exec` ze `sleep`, sztuczek opóźnienia `yieldMs` lub wielokrotnego odpytywania `process`
|
||||
zamiast pętli uśpienia `exec`, sztuczek opóźniania `yieldMs` lub powtarzanego odpytywania `process`
|
||||
- używaj `exec` / `process` tylko dla poleceń, które uruchamiają się teraz i dalej działają
|
||||
w tle
|
||||
- gdy włączone jest automatyczne budzenie po zakończeniu, uruchom polecenie raz i polegaj na
|
||||
ścieżce budzenia opartej na push, gdy wygeneruje dane wyjściowe lub zakończy się błędem
|
||||
- używaj `process` do logów, stanu, danych wejściowych lub interwencji, gdy musisz
|
||||
- gdy włączone jest automatyczne wybudzanie po zakończeniu, uruchom polecenie tylko raz i polegaj na
|
||||
ścieżce wybudzania opartej na push, gdy zwróci dane wyjściowe lub zakończy się błędem
|
||||
- używaj `process` do logów, statusu, wejścia lub interwencji, gdy musisz
|
||||
sprawdzić działające polecenie
|
||||
- jeśli zadanie jest większe, preferuj `sessions_spawn`; zakończenie sub-agenta działa
|
||||
w trybie push i automatycznie ogłasza się z powrotem do zlecającego
|
||||
- nie odpytuj w pętli `subagents list` / `sessions_list` tylko po to, by czekać na
|
||||
- jeśli zadanie jest większe, preferuj `sessions_spawn`; zakończenie podagenta działa
|
||||
w trybie push i jest automatycznie ogłaszane z powrotem do zgłaszającego
|
||||
- nie odpytywać `subagents list` / `sessions_list` w pętli tylko po to, aby czekać na
|
||||
zakończenie
|
||||
|
||||
Gdy eksperymentalne narzędzie `update_plan` jest włączone, Tooling mówi też modelowi,
|
||||
aby używał go tylko do nietrywialnej wieloetapowej pracy, utrzymywał dokładnie jeden krok
|
||||
Gdy eksperymentalne narzędzie `update_plan` jest włączone, sekcja Narzędzia mówi też modelowi,
|
||||
aby używał go tylko do nietrywialnej pracy wieloetapowej, utrzymywał dokładnie jeden krok
|
||||
`in_progress` i unikał powtarzania całego planu po każdej aktualizacji.
|
||||
|
||||
Zasady bezpieczeństwa w promptcie systemowym mają charakter doradczy. Kierują zachowaniem modelu, ale nie wymuszają polityki. Do twardego egzekwowania używaj polityki narzędzi, zatwierdzeń exec, sandboxingu i list dozwolonych kanałów; operatorzy mogą je celowo wyłączyć.
|
||||
Zabezpieczenia w promptcie systemowym mają charakter doradczy. Kierują zachowaniem modelu, ale nie wymuszają zasad. Do twardego egzekwowania używaj polityki narzędzi, zgód exec, sandboxingu i list dozwolonych kanałów; operatorzy mogą je celowo wyłączyć.
|
||||
|
||||
Na kanałach z natywnymi kartami/przyciskami zatwierdzania prompt runtime informuje teraz
|
||||
agenta, aby najpierw polegał na tym natywnym interfejsie zatwierdzania. Powinien dołączać ręczne
|
||||
polecenie `/approve` tylko wtedy, gdy wynik narzędzia mówi, że zatwierdzanie na czacie jest niedostępne lub
|
||||
jedyną ścieżką jest ręczne zatwierdzenie.
|
||||
W kanałach z natywnymi kartami/przyciskami zatwierdzania prompt środowiska wykonawczego informuje teraz
|
||||
agenta, aby najpierw polegał na tym natywnym interfejsie zatwierdzania. Powinien dołączać ręczne polecenie
|
||||
`/approve` tylko wtedy, gdy wynik narzędzia mówi, że zatwierdzenia na czacie są niedostępne lub
|
||||
ręczne zatwierdzenie jest jedyną drogą.
|
||||
|
||||
## Tryby promptu
|
||||
|
||||
OpenClaw może renderować mniejsze prompty systemowe dla sub-agentów. Runtime ustawia
|
||||
OpenClaw może renderować mniejsze prompty systemowe dla podagentów. Środowisko wykonawcze ustawia
|
||||
`promptMode` dla każdego uruchomienia (nie jest to konfiguracja widoczna dla użytkownika):
|
||||
|
||||
- `full` (domyślnie): zawiera wszystkie powyższe sekcje.
|
||||
- `minimal`: używany dla sub-agentów; pomija **Skills**, **Memory Recall**, **OpenClaw
|
||||
Self-Update**, **Model Aliases**, **User Identity**, **Reply Tags**,
|
||||
**Messaging**, **Silent Replies** i **Heartbeats**. Tooling, **Safety**,
|
||||
Workspace, Sandbox, Current Date & Time (gdy znane), Runtime oraz wstrzyknięty
|
||||
- `minimal`: używany dla podagentów; pomija **Skills**, **Przywoływanie pamięci**, **Samoaktualizację OpenClaw**, **Aliasy modeli**, **Tożsamość użytkownika**, **Tagi odpowiedzi**,
|
||||
**Wiadomości**, **Ciche odpowiedzi** i **Heartbeaty**. Narzędzia, **Bezpieczeństwo**,
|
||||
Workspace, Sandbox, Bieżąca data i godzina (gdy znane), Środowisko wykonawcze oraz wstrzyknięty
|
||||
kontekst pozostają dostępne.
|
||||
- `none`: zwraca tylko podstawową linię tożsamości.
|
||||
|
||||
Gdy `promptMode=minimal`, dodatkowe wstrzyknięte prompty są oznaczane jako **Subagent
|
||||
Context** zamiast **Group Chat Context**.
|
||||
Gdy `promptMode=minimal`, dodatkowe wstrzyknięte prompty są oznaczane jako **Kontekst podagenta**
|
||||
zamiast **Kontekst czatu grupowego**.
|
||||
|
||||
## Wstrzykiwanie bootstrapu workspace
|
||||
|
||||
Pliki bootstrap są przycinane i dołączane w sekcji **Project Context**, aby model widział kontekst tożsamości i profilu bez potrzeby jawnego odczytu:
|
||||
Pliki bootstrap są przycinane i dołączane w sekcji **Kontekst projektu**, aby model widział kontekst tożsamości i profilu bez potrzeby jawnego odczytu:
|
||||
|
||||
- `AGENTS.md`
|
||||
- `SOUL.md`
|
||||
@ -104,63 +101,66 @@ Pliki bootstrap są przycinane i dołączane w sekcji **Project Context**, aby m
|
||||
- `IDENTITY.md`
|
||||
- `USER.md`
|
||||
- `HEARTBEAT.md`
|
||||
- `BOOTSTRAP.md` (tylko w zupełnie nowych workspace)
|
||||
- `MEMORY.md`, gdy istnieje, w przeciwnym razie `memory.md` jako zapasowa wersja małymi literami
|
||||
- `BOOTSTRAP.md` (tylko w całkowicie nowych workspace'ach)
|
||||
- `MEMORY.md`, jeśli istnieje, w przeciwnym razie `memory.md` jako rezerwowy wariant pisany małymi literami
|
||||
|
||||
Wszystkie te pliki są **wstrzykiwane do okna kontekstu** przy każdej turze, co
|
||||
oznacza, że zużywają tokeny. Zachowuj je w zwięzłej formie — szczególnie `MEMORY.md`, który może
|
||||
rosnąć z czasem i prowadzić do nieoczekiwanie wysokiego użycia kontekstu oraz częstszego
|
||||
kompaktowania.
|
||||
Wszystkie te pliki są **wstrzykiwane do okna kontekstu** przy każdym kroku, chyba że obowiązuje
|
||||
bramka specyficzna dla pliku. `HEARTBEAT.md` jest pomijany przy normalnych uruchomieniach, gdy
|
||||
heartbeaty są wyłączone dla domyślnego agenta lub
|
||||
`agents.defaults.heartbeat.includeSystemPromptSection` ma wartość false. Zachowaj zwięzłość
|
||||
wstrzykiwanych plików — zwłaszcza `MEMORY.md`, który może z czasem rosnąć i prowadzić do
|
||||
nieoczekiwanie wysokiego zużycia kontekstu oraz częstszego kompaktowania.
|
||||
|
||||
> **Uwaga:** dzienne pliki `memory/*.md` **nie** są wstrzykiwane automatycznie.
|
||||
> Są dostępne na żądanie przez narzędzia `memory_search` i `memory_get`, więc
|
||||
> nie wliczają się do okna kontekstu, dopóki model ich jawnie nie odczyta.
|
||||
> **Uwaga:** dzienne pliki `memory/*.md` **nie** są wstrzykiwane automatycznie. Są
|
||||
> dostępne na żądanie przez narzędzia `memory_search` i `memory_get`, więc nie
|
||||
> wliczają się do okna kontekstu, chyba że model jawnie je odczyta.
|
||||
|
||||
Duże pliki są obcinane z markerem. Maksymalny rozmiar pojedynczego pliku jest kontrolowany przez
|
||||
Duże pliki są obcinane z użyciem znacznika. Maksymalny rozmiar pojedynczego pliku jest kontrolowany przez
|
||||
`agents.defaults.bootstrapMaxChars` (domyślnie: 20000). Łączna zawartość wstrzykniętego bootstrapu
|
||||
we wszystkich plikach jest ograniczona przez `agents.defaults.bootstrapTotalMaxChars`
|
||||
(domyślnie: 150000). Brakujące pliki wstrzykują krótki marker brakującego pliku. Gdy nastąpi obcięcie,
|
||||
OpenClaw może wstrzyknąć blok ostrzegawczy w Project Context; kontroluje to
|
||||
(domyślnie: 150000). Brakujące pliki wstrzykują krótki znacznik brakującego pliku. Gdy wystąpi obcięcie,
|
||||
OpenClaw może wstrzyknąć blok ostrzeżenia w Kontekście projektu; sterujesz tym przez
|
||||
`agents.defaults.bootstrapPromptTruncationWarning` (`off`, `once`, `always`;
|
||||
domyślnie: `once`).
|
||||
|
||||
Sesje sub-agentów wstrzykują tylko `AGENTS.md` i `TOOLS.md` (inne pliki bootstrap
|
||||
są odfiltrowywane, aby kontekst sub-agenta był mały).
|
||||
Sesje podagentów wstrzykują tylko `AGENTS.md` i `TOOLS.md` (pozostałe pliki bootstrapu
|
||||
są odfiltrowywane, aby zachować mały kontekst podagenta).
|
||||
|
||||
Wewnętrzne hooki mogą przechwycić ten krok przez `agent:bootstrap`, aby mutować lub zastępować
|
||||
wstrzyknięte pliki bootstrap (na przykład zamieniając `SOUL.md` na alternatywną personę).
|
||||
wstrzyknięte pliki bootstrapu (na przykład zamieniając `SOUL.md` na alternatywną personę).
|
||||
|
||||
Jeśli chcesz, aby agent brzmiał mniej generycznie, zacznij od
|
||||
[Przewodnika po osobowości SOUL.md](/concepts/soul).
|
||||
[Przewodnika osobowości SOUL.md](/pl/concepts/soul).
|
||||
|
||||
Aby sprawdzić, jaki wkład wnosi każdy wstrzyknięty plik (surowy vs wstrzyknięty, obcięcie, a także narzut schematu narzędzi), użyj `/context list` lub `/context detail`. Zobacz [Context](/concepts/context).
|
||||
Aby sprawdzić, jaki wkład ma każdy wstrzyknięty plik (surowy vs wstrzyknięty, obcięcie oraz narzut schematu narzędzi), użyj `/context list` lub `/context detail`. Zobacz [Kontekst](/pl/concepts/context).
|
||||
|
||||
## Obsługa czasu
|
||||
|
||||
Prompt systemowy zawiera dedykowaną sekcję **Current Date & Time**, gdy znana jest
|
||||
Prompt systemowy zawiera osobną sekcję **Bieżąca data i godzina**, gdy znana jest
|
||||
strefa czasowa użytkownika. Aby zachować stabilność pamięci podręcznej promptu, zawiera teraz tylko
|
||||
**strefę czasową** (bez dynamicznego zegara ani formatu czasu).
|
||||
|
||||
Używaj `session_status`, gdy agent potrzebuje aktualnego czasu; karta stanu
|
||||
zawiera wiersz ze znacznikiem czasu. To samo narzędzie może opcjonalnie ustawić nadpisanie modelu
|
||||
dla danej sesji (`model=default` je usuwa).
|
||||
Użyj `session_status`, gdy agent potrzebuje bieżącego czasu; karta statusu
|
||||
zawiera wiersz ze znacznikiem czasu. To samo narzędzie może opcjonalnie ustawić zastąpienie modelu
|
||||
dla sesji (`model=default` je czyści).
|
||||
|
||||
Konfiguracja:
|
||||
Skonfiguruj za pomocą:
|
||||
|
||||
- `agents.defaults.userTimezone`
|
||||
- `agents.defaults.timeFormat` (`auto` | `12` | `24`)
|
||||
|
||||
Pełne szczegóły zachowania znajdziesz w [Data i czas](/date-time).
|
||||
Pełne szczegóły zachowania znajdziesz w [Data i godzina](/pl/date-time).
|
||||
|
||||
## Skills
|
||||
|
||||
Gdy istnieją kwalifikujące się Skills, OpenClaw wstrzykuje zwartą **listę dostępnych umiejętności**
|
||||
(`formatSkillsForPrompt`), która zawiera **ścieżkę do pliku** dla każdej umiejętności. Prompt instruuje model, aby używał `read` do ładowania pliku SKILL.md w podanej lokalizacji
|
||||
(workspace, zarządzanej lub bundlowanej). Jeśli nie ma kwalifikujących się Skills, sekcja
|
||||
Skills jest pomijana.
|
||||
Gdy istnieją kwalifikujące się skille, OpenClaw wstrzykuje zwięzłą **listę dostępnych skillów**
|
||||
(`formatSkillsForPrompt`), która zawiera **ścieżkę pliku** dla każdego skilla. Prompt
|
||||
instruuje model, aby użył `read` do wczytania SKILL.md z podanej
|
||||
lokalizacji (workspace, zarządzanej lub dołączonej). Jeśli żadne skille się nie kwalifikują,
|
||||
sekcja Skills jest pomijana.
|
||||
|
||||
Kwalifikacja obejmuje bramki metadanych umiejętności, sprawdzenia środowiska runtime/konfiguracji
|
||||
oraz efektywną listę dozwolonych umiejętności agenta, gdy skonfigurowano `agents.defaults.skills` lub
|
||||
Kwalifikowalność obejmuje bramki metadanych skilli, kontrole środowiska wykonawczego/konfiguracji
|
||||
oraz efektywną listę dozwolonych skillów agenta, gdy skonfigurowano `agents.defaults.skills` lub
|
||||
`agents.list[].skills`.
|
||||
|
||||
```
|
||||
@ -173,12 +173,13 @@ oraz efektywną listę dozwolonych umiejętności agenta, gdy skonfigurowano `ag
|
||||
</available_skills>
|
||||
```
|
||||
|
||||
Dzięki temu bazowy prompt pozostaje mały, a jednocześnie umożliwia ukierunkowane użycie umiejętności.
|
||||
Dzięki temu podstawowy prompt pozostaje mały, a jednocześnie umożliwia użycie ukierunkowanych skillów.
|
||||
|
||||
## Documentation
|
||||
## Dokumentacja
|
||||
|
||||
Gdy jest dostępna, prompt systemowy zawiera sekcję **Documentation**, która wskazuje
|
||||
lokalny katalog dokumentacji OpenClaw (`docs/` w workspace repozytorium albo dokumentację
|
||||
z bundlowanego pakietu npm) i zawiera też informację o publicznym lustrze, repozytorium źródłowym, społecznościowym Discordzie oraz ClawHub ([https://clawhub.ai](https://clawhub.ai)) do odkrywania Skills. Prompt instruuje model, aby w pierwszej kolejności korzystał z lokalnej dokumentacji
|
||||
w sprawach dotyczących zachowania OpenClaw, poleceń, konfiguracji lub architektury, oraz aby
|
||||
w miarę możliwości sam uruchamiał `openclaw status` (pytając użytkownika tylko wtedy, gdy nie ma dostępu).
|
||||
Gdy jest dostępna, prompt systemowy zawiera sekcję **Dokumentacja**, która wskazuje
|
||||
lokalny katalog dokumentacji OpenClaw (albo `docs/` w workspace repozytorium, albo dołączoną dokumentację pakietu npm)
|
||||
oraz wspomina także o publicznym mirrorze, repozytorium źródłowym, społeczności Discord i
|
||||
ClawHub ([https://clawhub.ai](https://clawhub.ai)) do odkrywania skillów. Prompt instruuje model, aby najpierw konsultował lokalną dokumentację
|
||||
w sprawach dotyczących zachowania OpenClaw, poleceń, konfiguracji lub architektury oraz aby
|
||||
samodzielnie uruchamiał `openclaw status`, gdy to możliwe (prosząc użytkownika tylko wtedy, gdy nie ma dostępu).
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@ -1,22 +1,23 @@
|
||||
---
|
||||
read_when:
|
||||
- Dodajesz lub modyfikujesz migracje doctor
|
||||
- Wprowadzasz niezgodne wstecz zmiany konfiguracji
|
||||
- Dodawanie lub modyfikowanie migracji doctor
|
||||
- Wprowadzanie niekompatybilnych zmian konfiguracji
|
||||
summary: 'Polecenie Doctor: kontrole stanu, migracje konfiguracji i kroki naprawcze'
|
||||
title: Doctor
|
||||
x-i18n:
|
||||
generated_at: "2026-04-07T09:45:53Z"
|
||||
generated_at: "2026-04-08T02:15:39Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: a834dc7aec79c20d17bc23d37fb5f5e99e628d964d55bd8cf24525a7ee57130c
|
||||
source_hash: 3761a222d9db7088f78215575fa84e5896794ad701aa716e8bf9039a4424dca6
|
||||
source_path: gateway/doctor.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Doctor
|
||||
|
||||
`openclaw doctor` to narzędzie naprawcze i migracyjne dla OpenClaw. Naprawia nieaktualną
|
||||
konfigurację i stan, sprawdza kondycję systemu oraz podaje konkretne kroki naprawcze.
|
||||
`openclaw doctor` to narzędzie naprawy i migracji dla OpenClaw. Naprawia
|
||||
nieaktualną konfigurację i stan, sprawdza kondycję systemu oraz podaje
|
||||
konkretne kroki naprawcze.
|
||||
|
||||
## Szybki start
|
||||
|
||||
@ -24,19 +25,19 @@ konfigurację i stan, sprawdza kondycję systemu oraz podaje konkretne kroki nap
|
||||
openclaw doctor
|
||||
```
|
||||
|
||||
### Tryb headless / automatyzacja
|
||||
### Tryb bezgłowy / automatyzacja
|
||||
|
||||
```bash
|
||||
openclaw doctor --yes
|
||||
```
|
||||
|
||||
Akceptuje wartości domyślne bez pytań (w tym kroki naprawcze związane z restartem/usługą/sandboxem, gdy mają zastosowanie).
|
||||
Akceptuje domyślne opcje bez pytań (w tym kroki naprawy restartu/usługi/sandboxa, gdy mają zastosowanie).
|
||||
|
||||
```bash
|
||||
openclaw doctor --repair
|
||||
```
|
||||
|
||||
Stosuje zalecane naprawy bez pytań (naprawy + restarty tam, gdzie to bezpieczne).
|
||||
Stosuje zalecane naprawy bez pytań (naprawy + restarty tam, gdzie jest to bezpieczne).
|
||||
|
||||
```bash
|
||||
openclaw doctor --repair --force
|
||||
@ -48,16 +49,16 @@ Stosuje także agresywne naprawy (nadpisuje niestandardowe konfiguracje supervis
|
||||
openclaw doctor --non-interactive
|
||||
```
|
||||
|
||||
Uruchamia się bez pytań i stosuje tylko bezpieczne migracje (normalizacja konfiguracji + przenoszenie stanu na dysku). Pomija działania dotyczące restartu/usług/sandboxa, które wymagają potwierdzenia człowieka.
|
||||
Migracje starszego stanu są uruchamiane automatycznie po wykryciu.
|
||||
Uruchamia bez pytań i stosuje tylko bezpieczne migracje (normalizacja konfiguracji + przenoszenie stanu na dysku). Pomija działania restartu/usługi/sandboxa, które wymagają potwierdzenia człowieka.
|
||||
Migracje starszego stanu są uruchamiane automatycznie po ich wykryciu.
|
||||
|
||||
```bash
|
||||
openclaw doctor --deep
|
||||
```
|
||||
|
||||
Skanuje usługi systemowe pod kątem dodatkowych instalacji gateway (`launchd/systemd/schtasks`).
|
||||
Skanuje usługi systemowe pod kątem dodatkowych instalacji gatewaya (launchd/systemd/schtasks).
|
||||
|
||||
Jeśli chcesz przejrzeć zmiany przed zapisem, najpierw otwórz plik konfiguracji:
|
||||
Jeśli chcesz przejrzeć zmiany przed zapisaniem, najpierw otwórz plik konfiguracji:
|
||||
|
||||
```bash
|
||||
cat ~/.openclaw/openclaw.json
|
||||
@ -65,45 +66,46 @@ cat ~/.openclaw/openclaw.json
|
||||
|
||||
## Co robi (podsumowanie)
|
||||
|
||||
- Opcjonalna aktualizacja przed uruchomieniem dla instalacji git (tylko interaktywnie).
|
||||
- Opcjonalna aktualizacja przed uruchomieniem dla instalacji z gita (tylko interaktywnie).
|
||||
- Sprawdzenie aktualności protokołu UI (przebudowuje Control UI, gdy schemat protokołu jest nowszy).
|
||||
- Kontrola stanu + propozycja restartu.
|
||||
- Podsumowanie stanu Skills (kwalifikujące się/brakujące/zablokowane) i stanu pluginów.
|
||||
- Kontrola stanu + monit o restart.
|
||||
- Podsumowanie stanu Skills (kwalifikujące się/brakujące/zablokowane) oraz stanu pluginów.
|
||||
- Normalizacja konfiguracji dla starszych wartości.
|
||||
- Migracja konfiguracji Talk ze starszych płaskich pól `talk.*` do `talk.provider` + `talk.providers.<provider>`.
|
||||
- Kontrole migracji przeglądarki dla starszych konfiguracji rozszerzenia Chrome i gotowości Chrome MCP.
|
||||
- Ostrzeżenia o nadpisaniach dostawcy OpenCode (`models.providers.opencode` / `models.providers.opencode-go`).
|
||||
- Sprawdzenie wymagań wstępnych TLS dla OAuth OpenAI Codex.
|
||||
- Ostrzeżenia o nadpisaniu dostawcy OpenCode (`models.providers.opencode` / `models.providers.opencode-go`).
|
||||
- Ostrzeżenia o przesłanianiu Codex OAuth (`models.providers.openai-codex`).
|
||||
- Sprawdzenie wymagań TLS OAuth dla profili OpenAI Codex OAuth.
|
||||
- Migracja starszego stanu na dysku (sesje/katalog agenta/uwierzytelnianie WhatsApp).
|
||||
- Migracja starszych kluczy kontraktów manifestów pluginów (`speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, `webSearchProviders` → `contracts`).
|
||||
- Migracja starszego magazynu zadań cron (`jobId`, `schedule.cron`, pola delivery/payload na poziomie głównym, `provider` w payload, proste zadania zapasowe webhook z `notify: true`).
|
||||
- Inspekcja plików blokad sesji i usuwanie nieaktualnych blokad.
|
||||
- Kontrole integralności stanu i uprawnień (sesje, transkrypty, katalog stanu).
|
||||
- Migracja starszych kluczy kontraktu manifestu pluginu (`speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, `webSearchProviders` → `contracts`).
|
||||
- Migracja starszego magazynu cron (`jobId`, `schedule.cron`, pola delivery/payload na najwyższym poziomie, `provider` w payload, proste zadania zapasowe webhooka z `notify: true`).
|
||||
- Inspekcja plików blokady sesji i czyszczenie nieaktualnych blokad.
|
||||
- Kontrole integralności i uprawnień stanu (sesje, transkrypty, katalog stanu).
|
||||
- Kontrole uprawnień pliku konfiguracji (`chmod 600`) przy uruchomieniu lokalnym.
|
||||
- Kondycja uwierzytelniania modeli: sprawdza wygaśnięcie OAuth, może odświeżyć tokeny bliskie wygaśnięcia i raportuje stany cooldown/disabled profili auth.
|
||||
- Kondycja uwierzytelniania modeli: sprawdza wygaśnięcie OAuth, może odświeżyć wygasające tokeny i raportuje stany cooldown/wyłączenia profilu uwierzytelniania.
|
||||
- Wykrywanie dodatkowego katalogu workspace (`~/openclaw`).
|
||||
- Naprawa obrazu sandboxa, gdy sandboxing jest włączony.
|
||||
- Migracja starszych usług i wykrywanie dodatkowych gateway.
|
||||
- Migracja starszych usług i wykrywanie dodatkowych gatewayów.
|
||||
- Migracja starszego stanu kanału Matrix (w trybie `--fix` / `--repair`).
|
||||
- Kontrole środowiska uruchomieniowego gateway (usługa zainstalowana, ale nie działa; zapisany label `launchd`).
|
||||
- Ostrzeżenia o stanie kanałów (sondowane z działającego gateway).
|
||||
- Audyt konfiguracji supervisora (`launchd/systemd/schtasks`) z opcjonalną naprawą.
|
||||
- Kontrole dobrych praktyk środowiska uruchomieniowego gateway (Node vs Bun, ścieżki menedżerów wersji).
|
||||
- Diagnostyka kolizji portu gateway (domyślnie `18789`).
|
||||
- Ostrzeżenia bezpieczeństwa dla otwartych polityk wiadomości prywatnych.
|
||||
- Kontrole uwierzytelniania gateway dla lokalnego trybu tokenu (oferuje wygenerowanie tokenu, gdy nie istnieje jego źródło; nie nadpisuje konfiguracji tokenu opartych na SecretRef).
|
||||
- Sprawdzenie `systemd linger` na Linuksie.
|
||||
- Kontrola rozmiaru plików bootstrap workspace (ostrzeżenia o obcięciu/blisko limitu dla plików kontekstu).
|
||||
- Kontrola stanu autouzupełniania powłoki oraz automatyczna instalacja/aktualizacja.
|
||||
- Kontrola gotowości dostawcy embeddingów dla wyszukiwania pamięci (model lokalny, zdalny klucz API lub binarka QMD).
|
||||
- Kontrole instalacji ze źródeł (niedopasowanie workspace pnpm, brak zasobów UI, brak binarki tsx).
|
||||
- Zapisuje zaktualizowaną konfigurację i metadane kreatora.
|
||||
- Kontrole środowiska uruchomieniowego gatewaya (usługa zainstalowana, ale nie działa; zapisany w pamięci podręcznej label launchd).
|
||||
- Ostrzeżenia o stanie kanałów (sondowane z działającego gatewaya).
|
||||
- Audyt konfiguracji supervisora (launchd/systemd/schtasks) z opcjonalną naprawą.
|
||||
- Kontrole dobrych praktyk środowiska uruchomieniowego gatewaya (Node vs Bun, ścieżki menedżera wersji).
|
||||
- Diagnostyka kolizji portu gatewaya (domyślnie `18789`).
|
||||
- Ostrzeżenia bezpieczeństwa dla otwartych zasad DM.
|
||||
- Kontrole uwierzytelniania gatewaya dla lokalnego trybu tokena (oferuje wygenerowanie tokena, gdy nie istnieje żadne źródło tokena; nie nadpisuje konfiguracji tokenów SecretRef).
|
||||
- Sprawdzenie `systemd linger` w systemie Linux.
|
||||
- Sprawdzenie rozmiaru plików bootstrap workspace (ostrzeżenia o obcięciu / zbliżaniu się do limitu dla plików kontekstowych).
|
||||
- Sprawdzenie stanu autouzupełniania powłoki i automatyczna instalacja/aktualizacja.
|
||||
- Sprawdzenie gotowości dostawcy embeddingów wyszukiwania pamięci (model lokalny, zdalny klucz API lub binarka QMD).
|
||||
- Kontrole instalacji ze źródeł (niezgodność workspace pnpm, brakujące zasoby UI, brakująca binarka tsx).
|
||||
- Zapisuje zaktualizowaną konfigurację + metadane kreatora.
|
||||
|
||||
## Szczegółowe działanie i uzasadnienie
|
||||
|
||||
### 0) Opcjonalna aktualizacja (instalacje git)
|
||||
### 0) Opcjonalna aktualizacja (instalacje z gita)
|
||||
|
||||
Jeśli to checkout git i doctor działa interaktywnie, oferuje
|
||||
Jeśli jest to checkout z gita i doctor działa interaktywnie, oferuje
|
||||
aktualizację (fetch/rebase/build) przed uruchomieniem doctor.
|
||||
|
||||
### 1) Normalizacja konfiguracji
|
||||
@ -112,9 +114,9 @@ Jeśli konfiguracja zawiera starsze kształty wartości (na przykład `messages.
|
||||
bez nadpisania specyficznego dla kanału), doctor normalizuje je do bieżącego
|
||||
schematu.
|
||||
|
||||
Dotyczy to także starszych płaskich pól Talk. Aktualny publiczny model konfiguracji Talk to
|
||||
`talk.provider` + `talk.providers.<provider>`. Doctor przepisuje starsze
|
||||
kształty `talk.voiceId` / `talk.voiceAliases` / `talk.modelId` / `talk.outputFormat` /
|
||||
Dotyczy to także starszych płaskich pól Talk. Obecna publiczna konfiguracja Talk to
|
||||
`talk.provider` + `talk.providers.<provider>`. Doctor przepisuje stare kształty
|
||||
`talk.voiceId` / `talk.voiceAliases` / `talk.modelId` / `talk.outputFormat` /
|
||||
`talk.apiKey` do mapy dostawców.
|
||||
|
||||
### 2) Migracje starszych kluczy konfiguracji
|
||||
@ -122,14 +124,15 @@ kształty `talk.voiceId` / `talk.voiceAliases` / `talk.modelId` / `talk.outputFo
|
||||
Gdy konfiguracja zawiera przestarzałe klucze, inne polecenia odmawiają działania i proszą,
|
||||
aby uruchomić `openclaw doctor`.
|
||||
|
||||
Doctor:
|
||||
Doctor wykona wtedy:
|
||||
|
||||
- wyjaśnia, które starsze klucze zostały znalezione,
|
||||
- pokazuje zastosowaną migrację,
|
||||
- przepisuje `~/.openclaw/openclaw.json` do zaktualizowanego schematu.
|
||||
- Wyjaśni, które starsze klucze zostały znalezione.
|
||||
- Pokaże zastosowaną migrację.
|
||||
- Przepisze `~/.openclaw/openclaw.json` z użyciem zaktualizowanego schematu.
|
||||
|
||||
Gateway także automatycznie uruchamia migracje doctor przy starcie, gdy wykryje
|
||||
starszy format konfiguracji, więc nieaktualne konfiguracje są naprawiane bez ręcznej interwencji.
|
||||
Gateway uruchamia także migracje doctor automatycznie przy starcie, gdy wykryje
|
||||
starszy format konfiguracji, dzięki czemu nieaktualne konfiguracje są naprawiane
|
||||
bez ręcznej interwencji.
|
||||
Migracje magazynu zadań cron są obsługiwane przez `openclaw doctor --fix`.
|
||||
|
||||
Bieżące migracje:
|
||||
@ -139,7 +142,7 @@ Bieżące migracje:
|
||||
- `routing.groupChat.historyLimit` → `messages.groupChat.historyLimit`
|
||||
- `routing.groupChat.mentionPatterns` → `messages.groupChat.mentionPatterns`
|
||||
- `routing.queue` → `messages.queue`
|
||||
- `routing.bindings` → `bindings` na poziomie głównym
|
||||
- `routing.bindings` → najwyższy poziom `bindings`
|
||||
- `routing.agents`/`routing.defaultAgentId` → `agents.list` + `agents.list[].default`
|
||||
- starsze `talk.voiceId`/`talk.voiceAliases`/`talk.modelId`/`talk.outputFormat`/`talk.apiKey` → `talk.provider` + `talk.providers.<provider>`
|
||||
- `routing.agentToAgent` → `tools.agentToAgent`
|
||||
@ -154,71 +157,81 @@ Bieżące migracje:
|
||||
- `plugins.entries.voice-call.config.streaming.openaiApiKey|sttModel|silenceDurationMs|vadThreshold`
|
||||
→ `plugins.entries.voice-call.config.streaming.providers.openai.*`
|
||||
- `bindings[].match.accountID` → `bindings[].match.accountId`
|
||||
- Dla kanałów z nazwanymi `accounts`, ale z pozostawionymi wartościami kanału na najwyższym poziomie dla pojedynczego konta, przenieś te wartości przypisane do zakresu konta do promowanego konta wybranego dla tego kanału (`accounts.default` dla większości kanałów; Matrix może zachować istniejący pasujący nazwany/dom yślny cel)
|
||||
- Dla kanałów z nazwanymi `accounts`, ale z pozostałymi jednokontowymi wartościami kanału na najwyższym poziomie, przenieś te wartości przypisane do konta do wybranego promowanego konta dla tego kanału (`accounts.default` dla większości kanałów; Matrix może zachować istniejący pasujący nazwany/domyslny cel)
|
||||
- `identity` → `agents.list[].identity`
|
||||
- `agent.*` → `agents.defaults` + `tools.*` (tools/elevated/exec/sandbox/subagents)
|
||||
- `agent.model`/`allowedModels`/`modelAliases`/`modelFallbacks`/`imageModelFallbacks`
|
||||
→ `agents.defaults.models` + `agents.defaults.model.primary/fallbacks` + `agents.defaults.imageModel.primary/fallbacks`
|
||||
- `browser.ssrfPolicy.allowPrivateNetwork` → `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork`
|
||||
- `browser.profiles.*.driver: "extension"` → `"existing-session"`
|
||||
- usuwa `browser.relayBindHost` (starsze ustawienie relay rozszerzenia)
|
||||
- usuń `browser.relayBindHost` (starsze ustawienie relay rozszerzenia)
|
||||
|
||||
Ostrzeżenia doctor zawierają też wskazówki dotyczące kont domyślnych w kanałach wielokontowych:
|
||||
Ostrzeżenia doctor obejmują też wskazówki dotyczące domyślnego konta dla kanałów wielokontowych:
|
||||
|
||||
- Jeśli skonfigurowano co najmniej dwa wpisy `channels.<channel>.accounts` bez `channels.<channel>.defaultAccount` lub `accounts.default`, doctor ostrzega, że routing awaryjny może wybrać nieoczekiwane konto.
|
||||
- Jeśli `channels.<channel>.defaultAccount` jest ustawione na nieznany identyfikator konta, doctor ostrzega i wyświetla skonfigurowane identyfikatory kont.
|
||||
- Jeśli skonfigurowano dwa lub więcej wpisów `channels.<channel>.accounts` bez `channels.<channel>.defaultAccount` lub `accounts.default`, doctor ostrzega, że routing zapasowy może wybrać nieoczekiwane konto.
|
||||
- Jeśli ustawiono `channels.<channel>.defaultAccount` na nieznany identyfikator konta, doctor ostrzega i wyświetla listę skonfigurowanych identyfikatorów kont.
|
||||
|
||||
### 2b) Nadpisania dostawcy OpenCode
|
||||
|
||||
Jeśli ręcznie dodano `models.providers.opencode`, `opencode-zen` lub `opencode-go`,
|
||||
nadpisuje to wbudowany katalog OpenCode z `@mariozechner/pi-ai`.
|
||||
Może to wymuszać używanie niewłaściwego API przez modele albo zerować koszty. Doctor ostrzega, aby
|
||||
usunąć nadpisanie i przywrócić routing API oraz koszty per model.
|
||||
Może to wymusić użycie niewłaściwego API dla modeli albo wyzerować koszty. Doctor ostrzega, aby
|
||||
można było usunąć nadpisanie i przywrócić routing API oraz koszty dla każdego modelu.
|
||||
|
||||
### 2c) Migracja przeglądarki i gotowość Chrome MCP
|
||||
|
||||
Jeśli konfiguracja przeglądarki nadal wskazuje na usuniętą ścieżkę rozszerzenia Chrome, doctor
|
||||
normalizuje ją do aktualnego modelu podłączania host-local Chrome MCP:
|
||||
normalizuje ją do obecnego modelu dołączania Chrome MCP lokalnego dla hosta:
|
||||
|
||||
- `browser.profiles.*.driver: "extension"` staje się `"existing-session"`
|
||||
- `browser.profiles.*.driver: "extension"` zmienia się na `"existing-session"`
|
||||
- `browser.relayBindHost` jest usuwane
|
||||
|
||||
Doctor audytuje też ścieżkę host-local Chrome MCP, gdy używasz `defaultProfile:
|
||||
"user"` lub skonfigurowanego profilu `existing-session`:
|
||||
Doctor audytuje też lokalną dla hosta ścieżkę Chrome MCP, gdy używasz `defaultProfile:
|
||||
"user"` albo skonfigurowanego profilu `existing-session`:
|
||||
|
||||
- sprawdza, czy Google Chrome jest zainstalowany na tym samym hoście dla domyślnych
|
||||
profili automatycznego łączenia,
|
||||
- sprawdza wykrytą wersję Chrome i ostrzega, gdy jest niższa niż Chrome 144,
|
||||
profili automatycznego łączenia
|
||||
- sprawdza wykrytą wersję Chrome i ostrzega, gdy jest niższa niż Chrome 144
|
||||
- przypomina o włączeniu zdalnego debugowania na stronie inspekcji przeglądarki (na
|
||||
przykład `chrome://inspect/#remote-debugging`, `brave://inspect/#remote-debugging`
|
||||
przykład `chrome://inspect/#remote-debugging`, `brave://inspect/#remote-debugging`,
|
||||
lub `edge://inspect/#remote-debugging`)
|
||||
|
||||
Doctor nie może włączyć tego ustawienia po stronie Chrome za Ciebie. Host-local Chrome MCP
|
||||
Doctor nie może włączyć ustawienia po stronie Chrome za Ciebie. Lokalny dla hosta Chrome MCP
|
||||
nadal wymaga:
|
||||
|
||||
- przeglądarki opartej na Chromium 144+ na hoście gateway/node,
|
||||
- lokalnie uruchomionej przeglądarki,
|
||||
- włączonego zdalnego debugowania w tej przeglądarce,
|
||||
- zaakceptowania pierwszego monitu o zgodę na podłączenie w przeglądarce.
|
||||
- przeglądarki opartej na Chromium 144+ na hoście gatewaya/noda
|
||||
- lokalnie uruchomionej przeglądarki
|
||||
- włączonego zdalnego debugowania w tej przeglądarce
|
||||
- zatwierdzenia pierwszego monitu o zgodę na dołączenie w przeglądarce
|
||||
|
||||
Gotowość w tym miejscu dotyczy wyłącznie lokalnych wymagań wstępnych dla podłączania. Existing-session zachowuje
|
||||
Gotowość w tym miejscu dotyczy wyłącznie wymagań wstępnych lokalnego dołączania. Existing-session zachowuje
|
||||
obecne ograniczenia tras Chrome MCP; zaawansowane trasy, takie jak `responsebody`, eksport PDF,
|
||||
przechwytywanie pobierania i działania wsadowe, nadal wymagają zarządzanej
|
||||
przeglądarki lub surowego profilu CDP.
|
||||
|
||||
Ta kontrola **nie** dotyczy przepływów Docker, sandbox, remote-browser ani innych
|
||||
trybów headless. One nadal używają surowego CDP.
|
||||
To sprawdzenie **nie** dotyczy Docker, sandbox, remote-browser ani innych
|
||||
przepływów bezgłowych. One nadal używają surowego CDP.
|
||||
|
||||
### 2d) Wymagania wstępne TLS dla OAuth
|
||||
### 2d) Wymagania TLS OAuth
|
||||
|
||||
Gdy skonfigurowany jest profil OAuth OpenAI Codex, doctor sonduje punkt autoryzacji OpenAI,
|
||||
aby sprawdzić, czy lokalny stos TLS Node/OpenSSL potrafi
|
||||
Gdy skonfigurowany jest profil OpenAI Codex OAuth, doctor sonduje punkt końcowy
|
||||
autoryzacji OpenAI, aby sprawdzić, czy lokalny stos TLS Node/OpenSSL potrafi
|
||||
zweryfikować łańcuch certyfikatów. Jeśli sonda zakończy się błędem certyfikatu (na
|
||||
przykład `UNABLE_TO_GET_ISSUER_CERT_LOCALLY`, wygasły certyfikat lub certyfikat self-signed),
|
||||
doctor wyświetla wskazówki naprawcze specyficzne dla platformy. Na macOS z Node z Homebrew
|
||||
naprawą jest zwykle `brew postinstall ca-certificates`. Przy `--deep` sonda działa
|
||||
przykład `UNABLE_TO_GET_ISSUER_CERT_LOCALLY`, wygasły certyfikat lub certyfikat własny),
|
||||
doctor wyświetla wskazówki naprawcze specyficzne dla platformy. W systemie macOS z Node z Homebrew
|
||||
naprawą jest zwykle `brew postinstall ca-certificates`. Z `--deep` sonda działa
|
||||
nawet wtedy, gdy gateway jest zdrowy.
|
||||
|
||||
### 2c) Nadpisania dostawcy Codex OAuth
|
||||
|
||||
Jeśli wcześniej dodano starsze ustawienia transportu OpenAI w
|
||||
`models.providers.openai-codex`, mogą one przesłaniać wbudowaną ścieżkę
|
||||
dostawcy Codex OAuth, której nowsze wydania używają automatycznie. Doctor ostrzega, gdy wykryje
|
||||
te stare ustawienia transportu razem z Codex OAuth, aby można było usunąć lub przepisać
|
||||
nieaktualne nadpisanie transportu i odzyskać wbudowane zachowanie routingu/fallbacku.
|
||||
Niestandardowe proxy i nadpisania samych nagłówków są nadal obsługiwane i nie
|
||||
wywołują tego ostrzeżenia.
|
||||
|
||||
### 3) Migracje starszego stanu (układ na dysku)
|
||||
|
||||
Doctor może migrować starsze układy na dysku do bieżącej struktury:
|
||||
@ -228,58 +241,59 @@ Doctor może migrować starsze układy na dysku do bieżącej struktury:
|
||||
- Katalog agenta:
|
||||
- z `~/.openclaw/agent/` do `~/.openclaw/agents/<agentId>/agent/`
|
||||
- Stan uwierzytelniania WhatsApp (Baileys):
|
||||
- ze starszego `~/.openclaw/credentials/*.json` (oprócz `oauth.json`)
|
||||
- ze starszego `~/.openclaw/credentials/*.json` (z wyjątkiem `oauth.json`)
|
||||
- do `~/.openclaw/credentials/whatsapp/<accountId>/...` (domyślny identyfikator konta: `default`)
|
||||
|
||||
Te migracje są wykonywane w trybie best-effort i są idempotentne; doctor wyemituje ostrzeżenia, jeśli
|
||||
pozostawi starsze katalogi jako kopie zapasowe. Gateway/CLI także automatycznie migrują
|
||||
starsze sesje + katalog agenta przy starcie, aby historia/auth/modele trafiły do ścieżki
|
||||
per agent bez ręcznego uruchamiania doctor. Uwierzytelnianie WhatsApp jest celowo migrowane tylko przez `openclaw doctor`. Normalizacja dostawcy/mapy dostawców Talk
|
||||
porównuje teraz równość strukturalną, więc różnice wyłącznie w kolejności kluczy nie powodują już
|
||||
powtarzających się, pustych zmian `doctor --fix`.
|
||||
Te migracje są realizowane w trybie best-effort i są idempotentne; doctor wyemituje ostrzeżenia, gdy
|
||||
pozostawi jakiekolwiek starsze foldery jako kopie zapasowe. Gateway/CLI również automatycznie migruje
|
||||
starsze sesje + katalog agenta przy starcie, dzięki czemu historia/uwierzytelnianie/modele trafiają do
|
||||
ścieżki per-agent bez ręcznego uruchamiania doctor. Uwierzytelnianie WhatsApp jest celowo
|
||||
migrowane tylko przez `openclaw doctor`. Normalizacja dostawcy/mapy dostawców Talk porównuje teraz
|
||||
według równości strukturalnej, więc różnice wyłącznie w kolejności kluczy nie wywołują już
|
||||
powtarzanych zmian bez efektu przez `doctor --fix`.
|
||||
|
||||
### 3a) Migracje starszych manifestów pluginów
|
||||
|
||||
Doctor skanuje wszystkie zainstalowane manifesty pluginów pod kątem przestarzałych kluczy
|
||||
możliwości na poziomie głównym (`speechProviders`, `realtimeTranscriptionProviders`,
|
||||
możliwości na najwyższym poziomie (`speechProviders`, `realtimeTranscriptionProviders`,
|
||||
`realtimeVoiceProviders`, `mediaUnderstandingProviders`,
|
||||
`imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`,
|
||||
`webSearchProviders`). Po ich znalezieniu oferuje przeniesienie ich do obiektu `contracts`
|
||||
`webSearchProviders`). Gdy je znajdzie, oferuje przeniesienie ich do obiektu `contracts`
|
||||
i przepisanie pliku manifestu w miejscu. Ta migracja jest idempotentna;
|
||||
jeśli klucz `contracts` zawiera już te same wartości, starszy klucz jest usuwany
|
||||
jeśli klucz `contracts` ma już te same wartości, starszy klucz jest usuwany
|
||||
bez duplikowania danych.
|
||||
|
||||
### 3b) Migracje starszego magazynu cron
|
||||
|
||||
Doctor sprawdza też magazyn zadań cron (`~/.openclaw/cron/jobs.json` domyślnie,
|
||||
lub `cron.store`, jeśli został nadpisany) pod kątem starych kształtów zadań, które scheduler
|
||||
nadal akceptuje ze względów zgodności.
|
||||
Doctor sprawdza także magazyn zadań cron (`~/.openclaw/cron/jobs.json` domyślnie,
|
||||
lub `cron.store`, jeśli został nadpisany) pod kątem starych kształtów zadań, które harmonogram
|
||||
nadal akceptuje ze względów kompatybilności.
|
||||
|
||||
Bieżące porządki cron obejmują:
|
||||
|
||||
- `jobId` → `id`
|
||||
- `schedule.cron` → `schedule.expr`
|
||||
- pola payload na poziomie głównym (`message`, `model`, `thinking`, ...) → `payload`
|
||||
- pola delivery na poziomie głównym (`deliver`, `channel`, `to`, `provider`, ...) → `delivery`
|
||||
- pola payload na najwyższym poziomie (`message`, `model`, `thinking`, ...) → `payload`
|
||||
- pola delivery na najwyższym poziomie (`deliver`, `channel`, `to`, `provider`, ...) → `delivery`
|
||||
- aliasy delivery `provider` w payload → jawne `delivery.channel`
|
||||
- proste starsze zadania zapasowe webhook z `notify: true` → jawne `delivery.mode="webhook"` z `delivery.to=cron.webhook`
|
||||
- proste starsze zadania zapasowe webhooka `notify: true` → jawne `delivery.mode="webhook"` z `delivery.to=cron.webhook`
|
||||
|
||||
Doctor automatycznie migruje zadania `notify: true` tylko wtedy, gdy może to zrobić bez
|
||||
zmiany zachowania. Jeśli zadanie łączy starszy mechanizm zapasowy notify z istniejącym
|
||||
trybem delivery innym niż webhook, doctor ostrzega i pozostawia takie zadanie do ręcznego przeglądu.
|
||||
zmiany zachowania. Jeśli zadanie łączy starszy zapasowy mechanizm notify z istniejącym
|
||||
trybem delivery innym niż webhook, doctor ostrzega i pozostawia to zadanie do ręcznego przeglądu.
|
||||
|
||||
### 3c) Czyszczenie blokad sesji
|
||||
|
||||
Doctor skanuje katalog sesji każdego agenta w poszukiwaniu nieaktualnych plików blokad zapisu — plików
|
||||
Doctor skanuje każdy katalog sesji agenta w poszukiwaniu nieaktualnych plików blokady zapisu — plików
|
||||
pozostawionych po nieprawidłowym zakończeniu sesji. Dla każdego znalezionego pliku blokady raportuje:
|
||||
ścieżkę, PID, czy PID nadal działa, wiek blokady oraz czy
|
||||
jest uznawana za nieaktualną (martwy PID lub starsza niż 30 minut). W trybie `--fix` / `--repair`
|
||||
automatycznie usuwa nieaktualne pliki blokad; w przeciwnym razie wyświetla uwagę i
|
||||
poleca ponownie uruchomić z `--fix`.
|
||||
ścieżkę, PID, czy PID nadal żyje, wiek blokady i czy jest
|
||||
uznawana za nieaktualną (martwy PID lub więcej niż 30 minut). W trybie `--fix` / `--repair`
|
||||
automatycznie usuwa nieaktualne pliki blokady; w przeciwnym razie wyświetla notatkę i
|
||||
instrukcję, aby uruchomić ponownie z `--fix`.
|
||||
|
||||
### 4) Kontrole integralności stanu (utrwalanie sesji, routing i bezpieczeństwo)
|
||||
### 4) Kontrole integralności stanu (trwałość sesji, routing i bezpieczeństwo)
|
||||
|
||||
Katalog stanu to operacyjny pień mózgu systemu. Jeśli zniknie, tracisz
|
||||
Katalog stanu to operacyjny pień mózgu systemu. Jeśli zniknie, stracisz
|
||||
sesje, poświadczenia, logi i konfigurację (chyba że masz kopie zapasowe gdzie indziej).
|
||||
|
||||
Doctor sprawdza:
|
||||
@ -287,105 +301,106 @@ Doctor sprawdza:
|
||||
- **Brak katalogu stanu**: ostrzega o katastrofalnej utracie stanu, proponuje odtworzenie
|
||||
katalogu i przypomina, że nie może odzyskać brakujących danych.
|
||||
- **Uprawnienia katalogu stanu**: weryfikuje możliwość zapisu; oferuje naprawę uprawnień
|
||||
(i wyświetla wskazówkę `chown`, gdy wykryje niedopasowanie właściciela/grupy).
|
||||
- **Katalog stanu zsynchronizowany z chmurą na macOS**: ostrzega, gdy stan rozwiązuje się pod iCloud Drive
|
||||
(i wyświetla wskazówkę `chown`, gdy wykryje niezgodność właściciela/grupy).
|
||||
- **Katalog stanu synchronizowany z chmurą w macOS**: ostrzega, gdy stan znajduje się pod iCloud Drive
|
||||
(`~/Library/Mobile Documents/com~apple~CloudDocs/...`) lub
|
||||
`~/Library/CloudStorage/...`, ponieważ ścieżki oparte na synchronizacji mogą powodować wolniejsze I/O
|
||||
oraz wyścigi blokad/synchronizacji.
|
||||
- **Katalog stanu na Linux na SD lub eMMC**: ostrzega, gdy stan rozwiązuje się do źródła montowania `mmcblk*`,
|
||||
ponieważ losowe I/O na kartach SD lub eMMC może być wolniejsze i szybciej zużywać nośnik
|
||||
przy zapisach sesji i poświadczeń.
|
||||
- **Katalog stanu na Linux na SD lub eMMC**: ostrzega, gdy stan znajduje się na źródle montowania `mmcblk*`,
|
||||
ponieważ losowe I/O na nośnikach SD lub eMMC może być wolniejsze i szybciej zużywać nośnik
|
||||
przy zapisie sesji i poświadczeń.
|
||||
- **Brak katalogów sesji**: `sessions/` i katalog magazynu sesji są
|
||||
wymagane do utrwalania historii i unikania awarii `ENOENT`.
|
||||
- **Niedopasowanie transkryptów**: ostrzega, gdy ostatnie wpisy sesji mają brakujące
|
||||
pliki transkryptów.
|
||||
- **Główna sesja „1-line JSONL”**: sygnalizuje, gdy główny transkrypt ma tylko jedną
|
||||
linię (historia się nie kumuluje).
|
||||
wymagane do trwałego zapisywania historii i unikania awarii `ENOENT`.
|
||||
- **Niezgodność transkryptu**: ostrzega, gdy ostatnie wpisy sesji mają brakujące
|
||||
pliki transkryptu.
|
||||
- **Główna sesja „1-wierszowy JSONL”**: sygnalizuje, gdy główny transkrypt ma tylko jeden
|
||||
wiersz (historia się nie gromadzi).
|
||||
- **Wiele katalogów stanu**: ostrzega, gdy istnieje wiele folderów `~/.openclaw` w różnych
|
||||
katalogach domowych lub gdy `OPENCLAW_STATE_DIR` wskazuje gdzie indziej (historia może się rozdzielić między instalacje).
|
||||
katalogach domowych lub gdy `OPENCLAW_STATE_DIR` wskazuje inne miejsce (historia może się
|
||||
rozdzielać między instalacjami).
|
||||
- **Przypomnienie o trybie zdalnym**: jeśli `gateway.mode=remote`, doctor przypomina, aby uruchomić
|
||||
go na zdalnym hoście (tam znajduje się stan).
|
||||
- **Uprawnienia pliku konfiguracji**: ostrzega, jeśli `~/.openclaw/openclaw.json` ma prawa
|
||||
odczytu dla grupy/wszystkich, i oferuje ich zaostrzenie do `600`.
|
||||
- **Uprawnienia pliku konfiguracji**: ostrzega, jeśli `~/.openclaw/openclaw.json` jest
|
||||
czytelny dla grupy/świata i oferuje zaostrzenie do `600`.
|
||||
|
||||
### 5) Kondycja uwierzytelniania modeli (wygaśnięcie OAuth)
|
||||
|
||||
Doctor analizuje profile OAuth w magazynie auth, ostrzega, gdy tokeny
|
||||
wygasają lub już wygasły, i może je odświeżyć, gdy jest to bezpieczne. Jeśli profil
|
||||
Doctor sprawdza profile OAuth w magazynie uwierzytelniania, ostrzega, gdy tokeny
|
||||
wygasają lub wygasły, i może je odświeżyć, gdy jest to bezpieczne. Jeśli profil
|
||||
OAuth/token Anthropic jest nieaktualny, sugeruje użycie klucza API Anthropic albo
|
||||
ścieżki Anthropic setup-token.
|
||||
Monity o odświeżenie pojawiają się tylko podczas uruchomienia interaktywnego (TTY); `--non-interactive`
|
||||
pomija próby odświeżania.
|
||||
ścieżki setup-token Anthropic.
|
||||
Monity o odświeżenie pojawiają się tylko w trybie interaktywnym (TTY); `--non-interactive`
|
||||
pomija próby odświeżenia.
|
||||
|
||||
Doctor raportuje także profile auth, które są tymczasowo niedostępne z powodu:
|
||||
Doctor raportuje też profile uwierzytelniania, które są tymczasowo nieużywalne z powodu:
|
||||
|
||||
- krótkich cooldownów (rate limits/timeouts/błędy auth),
|
||||
- dłuższych wyłączeń (błędy rozliczeń/braku środków).
|
||||
- krótkich cooldownów (rate limits/timeouts/błędy uwierzytelniania)
|
||||
- dłuższych wyłączeń (problemy z rozliczeniami/kredytem)
|
||||
|
||||
### 6) Walidacja modelu hooks
|
||||
|
||||
Jeśli ustawiono `hooks.gmail.model`, doctor waliduje odwołanie do modelu względem
|
||||
katalogu i allowlisty oraz ostrzega, gdy nie zostanie rozwiązane albo jest niedozwolone.
|
||||
katalogu i listy dozwolonych modeli oraz ostrzega, gdy nie będzie się rozwiązywać lub jest niedozwolone.
|
||||
|
||||
### 7) Naprawa obrazu sandboxa
|
||||
|
||||
Gdy sandboxing jest włączony, doctor sprawdza obrazy Docker i oferuje ich zbudowanie albo
|
||||
przełączenie na starsze nazwy, jeśli bieżący obraz nie istnieje.
|
||||
Gdy sandboxing jest włączony, doctor sprawdza obrazy Docker i oferuje ich zbudowanie lub
|
||||
przełączenie na starsze nazwy, jeśli obecny obraz nie istnieje.
|
||||
|
||||
### 7b) Zależności runtime pakietów pluginów bundlowanych
|
||||
### 7b) Zależności uruchomieniowe bundlowanych pluginów
|
||||
|
||||
Doctor weryfikuje, czy zależności runtime bundlowanych pluginów (na przykład pakiety
|
||||
runtime pluginu Discord) są obecne w katalogu głównym instalacji OpenClaw.
|
||||
Jeśli którychś brakuje, doctor raportuje te pakiety i instaluje je w trybie
|
||||
Doctor weryfikuje, czy zależności uruchomieniowe bundlowanych pluginów (na przykład
|
||||
pakiety uruchomieniowe pluginu Discord) są obecne w katalogu głównym instalacji OpenClaw.
|
||||
Jeśli którychś brakuje, doctor raportuje pakiety i instaluje je w trybie
|
||||
`openclaw doctor --fix` / `openclaw doctor --repair`.
|
||||
|
||||
### 8) Migracje usług gateway i wskazówki dotyczące czyszczenia
|
||||
### 8) Migracje usług gatewaya i wskazówki dotyczące czyszczenia
|
||||
|
||||
Doctor wykrywa starsze usługi gateway (`launchd/systemd/schtasks`) i
|
||||
oferuje ich usunięcie oraz instalację usługi OpenClaw przy użyciu bieżącego portu gateway.
|
||||
Może też skanować w poszukiwaniu dodatkowych usług podobnych do gateway i wyświetlać wskazówki czyszczenia.
|
||||
Usługi OpenClaw gateway nazwane według profilu są traktowane jako pełnoprawne i nie są
|
||||
Doctor wykrywa starsze usługi gatewaya (launchd/systemd/schtasks) i
|
||||
oferuje ich usunięcie oraz instalację usługi OpenClaw z użyciem bieżącego portu gatewaya.
|
||||
Może też skanować w poszukiwaniu dodatkowych usług podobnych do gatewaya i wyświetlać wskazówki porządkowe.
|
||||
Usługi gatewaya OpenClaw nazwane według profilu są traktowane jako pełnoprawne i nie są
|
||||
oznaczane jako „dodatkowe”.
|
||||
|
||||
### 8b) Migracja Matrix przy starcie
|
||||
|
||||
Gdy konto kanału Matrix ma oczekującą lub możliwą do wykonania migrację starszego stanu,
|
||||
doctor (w trybie `--fix` / `--repair`) tworzy migawkę przed migracją, a następnie
|
||||
uruchamia kroki migracji best-effort: migrację starszego stanu Matrix oraz przygotowanie
|
||||
starszego stanu zaszyfrowanego. Oba kroki nie są krytyczne; błędy są logowane, a
|
||||
start jest kontynuowany. W trybie tylko do odczytu (`openclaw doctor` bez `--fix`) ta kontrola
|
||||
jest całkowicie pomijana.
|
||||
doctor (w trybie `--fix` / `--repair`) tworzy snapshot przed migracją, a następnie
|
||||
uruchamia kroki migracji w trybie best-effort: migrację starszego stanu Matrix oraz przygotowanie starszego
|
||||
stanu szyfrowanego. Oba kroki nie są krytyczne; błędy są logowane, a
|
||||
uruchamianie jest kontynuowane. W trybie tylko do odczytu (`openclaw doctor` bez `--fix`) to sprawdzenie
|
||||
jest całkowicie pomijane.
|
||||
|
||||
### 9) Ostrzeżenia bezpieczeństwa
|
||||
|
||||
Doctor emituje ostrzeżenia, gdy dostawca jest otwarty na wiadomości prywatne bez allowlisty lub
|
||||
gdy polityka jest skonfigurowana w niebezpieczny sposób.
|
||||
Doctor emituje ostrzeżenia, gdy dostawca jest otwarty na DM bez listy dozwolonych,
|
||||
albo gdy zasada jest skonfigurowana w niebezpieczny sposób.
|
||||
|
||||
### 10) systemd linger (Linux)
|
||||
|
||||
Jeśli działa jako usługa użytkownika systemd, doctor upewnia się, że włączone jest lingering,
|
||||
aby gateway pozostał aktywny po wylogowaniu.
|
||||
Jeśli działa jako usługa użytkownika systemd, doctor upewnia się, że lingering jest włączony, aby
|
||||
gateway pozostał aktywny po wylogowaniu.
|
||||
|
||||
### 11) Stan workspace (Skills, pluginy i starsze katalogi)
|
||||
|
||||
Doctor wyświetla podsumowanie stanu workspace dla domyślnego agenta:
|
||||
|
||||
- **Stan Skills**: zlicza Skills kwalifikujące się, z brakującymi wymaganiami i zablokowane przez allowlistę.
|
||||
- **Stan Skills**: liczba skills kwalifikujących się, z brakującymi wymaganiami i zablokowanych przez allowlistę.
|
||||
- **Starsze katalogi workspace**: ostrzega, gdy `~/openclaw` lub inne starsze katalogi workspace
|
||||
istnieją obok bieżącego workspace.
|
||||
- **Stan pluginów**: zlicza pluginy załadowane/wyłączone/z błędami; wyświetla identyfikatory pluginów dla
|
||||
błędów; raportuje możliwości bundle pluginów.
|
||||
- **Ostrzeżenia o zgodności pluginów**: oznacza pluginy mające problemy zgodności z
|
||||
bieżącym runtime.
|
||||
- **Stan pluginów**: liczba załadowanych/wyłączonych/pluginów z błędami; wyświetla identyfikatory pluginów dla wszystkich
|
||||
błędów; raportuje możliwości bundlowanych pluginów.
|
||||
- **Ostrzeżenia o zgodności pluginów**: oznacza pluginy, które mają problemy ze zgodnością z
|
||||
bieżącym środowiskiem uruchomieniowym.
|
||||
- **Diagnostyka pluginów**: pokazuje wszelkie ostrzeżenia lub błędy z czasu ładowania emitowane przez
|
||||
rejestr pluginów.
|
||||
|
||||
### 11b) Rozmiar pliku bootstrap
|
||||
|
||||
Doctor sprawdza, czy pliki bootstrap workspace (na przykład `AGENTS.md`,
|
||||
`CLAUDE.md` lub inne wstrzykiwane pliki kontekstu) są blisko skonfigurowanego
|
||||
limitu znaków albo go przekraczają. Raportuje dla każdego pliku liczbę surowych i wstrzykniętych znaków, procent obcięcia,
|
||||
przyczynę obcięcia (`max/file` lub `max/total`) oraz łączną liczbę wstrzykniętych
|
||||
`CLAUDE.md` lub inne wstrzykiwane pliki kontekstowe) są blisko skonfigurowanego
|
||||
limitu znaków lub go przekraczają. Raportuje dla każdego pliku liczbę surowych i wstrzykniętych znaków,
|
||||
procent obcięcia, przyczynę obcięcia (`max/file` lub `max/total`) oraz łączną liczbę wstrzykniętych
|
||||
znaków jako ułamek całkowitego budżetu. Gdy pliki są obcięte lub blisko limitu,
|
||||
doctor wyświetla wskazówki dotyczące dostrojenia `agents.defaults.bootstrapMaxChars`
|
||||
i `agents.defaults.bootstrapTotalMaxChars`.
|
||||
@ -399,101 +414,101 @@ Doctor sprawdza, czy autouzupełnianie tabulatorem jest zainstalowane dla bież
|
||||
(`source <(openclaw completion ...)`), doctor aktualizuje go do szybszego
|
||||
wariantu z plikiem cache.
|
||||
- Jeśli autouzupełnianie jest skonfigurowane w profilu, ale brakuje pliku cache,
|
||||
doctor automatycznie regeneruje cache.
|
||||
doctor automatycznie odtwarza cache.
|
||||
- Jeśli autouzupełnianie nie jest w ogóle skonfigurowane, doctor proponuje jego instalację
|
||||
(tylko w trybie interaktywnym; pomijane przy `--non-interactive`).
|
||||
(tylko w trybie interaktywnym; pomijane z `--non-interactive`).
|
||||
|
||||
Uruchom `openclaw completion --write-state`, aby ręcznie odtworzyć cache.
|
||||
|
||||
### 12) Kontrole uwierzytelniania gateway (lokalny token)
|
||||
### 12) Kontrole uwierzytelniania gatewaya (lokalny token)
|
||||
|
||||
Doctor sprawdza gotowość uwierzytelniania tokenem lokalnego gateway.
|
||||
Doctor sprawdza gotowość lokalnego uwierzytelniania tokenem gatewaya.
|
||||
|
||||
- Jeśli tryb tokenu wymaga tokenu i nie istnieje jego źródło, doctor proponuje jego wygenerowanie.
|
||||
- Jeśli tryb tokena potrzebuje tokena i nie istnieje żadne źródło tokena, doctor proponuje jego wygenerowanie.
|
||||
- Jeśli `gateway.auth.token` jest zarządzany przez SecretRef, ale niedostępny, doctor ostrzega i nie nadpisuje go jawnym tekstem.
|
||||
- `openclaw doctor --generate-gateway-token` wymusza wygenerowanie tylko wtedy, gdy nie skonfigurowano SecretRef tokenu.
|
||||
- `openclaw doctor --generate-gateway-token` wymusza generowanie tylko wtedy, gdy nie skonfigurowano tokena SecretRef.
|
||||
|
||||
### 12b) Naprawy tylko do odczytu, świadome SecretRef
|
||||
### 12b) Naprawy świadome SecretRef w trybie tylko do odczytu
|
||||
|
||||
Niektóre przepływy naprawcze muszą sprawdzać skonfigurowane poświadczenia bez osłabiania zachowania fail-fast w runtime.
|
||||
Niektóre ścieżki naprawy muszą sprawdzać skonfigurowane poświadczenia bez osłabiania zachowania fail-fast w runtime.
|
||||
|
||||
- `openclaw doctor --fix` używa teraz tego samego modelu podsumowania SecretRef tylko do odczytu, co polecenia z rodziny status, do ukierunkowanych napraw konfiguracji.
|
||||
- Przykład: naprawa `allowFrom` / `groupAllowFrom` z `@username` w Telegram próbuje użyć skonfigurowanych poświadczeń bota, gdy są dostępne.
|
||||
- Jeśli token bota Telegram jest skonfigurowany przez SecretRef, ale niedostępny w bieżącej ścieżce polecenia, doctor zgłasza, że poświadczenie jest skonfigurowane, ale niedostępne, i pomija automatyczne rozwiązanie zamiast kończyć się awarią lub błędnie raportować brak tokenu.
|
||||
- `openclaw doctor --fix` używa teraz tego samego modelu podsumowania SecretRef tylko do odczytu co polecenia z rodziny status dla ukierunkowanych napraw konfiguracji.
|
||||
- Przykład: naprawa Telegram `allowFrom` / `groupAllowFrom` `@username` próbuje użyć skonfigurowanych poświadczeń bota, jeśli są dostępne.
|
||||
- Jeśli token bota Telegram jest skonfigurowany przez SecretRef, ale niedostępny w bieżącej ścieżce polecenia, doctor zgłasza, że poświadczenie jest skonfigurowane-ale-niedostępne, i pomija automatyczne rozwiązywanie zamiast kończyć się awarią lub błędnie raportować brak tokena.
|
||||
|
||||
### 13) Kontrola stanu gateway + restart
|
||||
### 13) Kontrola stanu gatewaya + restart
|
||||
|
||||
Doctor uruchamia kontrolę stanu i oferuje restart gateway, gdy wygląda
|
||||
na niezdatny do pracy.
|
||||
Doctor uruchamia kontrolę stanu i oferuje restart gatewaya, gdy wygląda on na
|
||||
niezdrowy.
|
||||
|
||||
### 13b) Gotowość wyszukiwania pamięci
|
||||
|
||||
Doctor sprawdza, czy skonfigurowany dostawca embeddingów dla wyszukiwania pamięci jest gotowy
|
||||
Doctor sprawdza, czy skonfigurowany dostawca embeddingów wyszukiwania pamięci jest gotowy
|
||||
dla domyślnego agenta. Zachowanie zależy od skonfigurowanego backendu i dostawcy:
|
||||
|
||||
- **Backend QMD**: sonduje, czy binarka `qmd` jest dostępna i daje się uruchomić.
|
||||
Jeśli nie, wyświetla wskazówki naprawcze, w tym pakiet npm i opcję ręcznej ścieżki do binarki.
|
||||
- **Jawny dostawca lokalny**: sprawdza obecność lokalnego pliku modelu albo rozpoznawanego
|
||||
- **Jawny dostawca lokalny**: sprawdza istnienie lokalnego pliku modelu lub rozpoznanego
|
||||
zdalnego/pobieralnego URL modelu. Jeśli go brakuje, sugeruje przełączenie na zdalnego dostawcę.
|
||||
- **Jawny dostawca zdalny** (`openai`, `voyage` itd.): weryfikuje, czy klucz API jest
|
||||
obecny w środowisku lub magazynie auth. Jeśli go brakuje, wyświetla konkretne wskazówki naprawcze.
|
||||
- **Dostawca automatyczny**: najpierw sprawdza dostępność modelu lokalnego, a potem próbuje każdego zdalnego
|
||||
dostawcy zgodnie z kolejnością automatycznego wyboru.
|
||||
obecny w środowisku lub magazynie uwierzytelniania. Jeśli go brakuje, wyświetla praktyczne wskazówki naprawcze.
|
||||
- **Dostawca automatyczny**: najpierw sprawdza dostępność modelu lokalnego, a następnie próbuje każdego zdalnego
|
||||
dostawcę w kolejności automatycznego wyboru.
|
||||
|
||||
Gdy wynik sondy gateway jest dostępny (gateway był zdrowy w momencie
|
||||
sprawdzenia), doctor porównuje go z konfiguracją widoczną dla CLI i odnotowuje
|
||||
Gdy wynik sondy gatewaya jest dostępny (gateway był zdrowy w momencie
|
||||
sprawdzenia), doctor porównuje go z konfiguracją widoczną z CLI i odnotowuje
|
||||
wszelkie rozbieżności.
|
||||
|
||||
Użyj `openclaw memory status --deep`, aby zweryfikować gotowość embeddingów w runtime.
|
||||
|
||||
### 14) Ostrzeżenia o stanie kanałów
|
||||
|
||||
Jeśli gateway jest zdrowy, doctor uruchamia sondę stanu kanałów i raportuje
|
||||
Jeśli gateway jest zdrowy, doctor uruchamia sondę stanu kanałów i zgłasza
|
||||
ostrzeżenia wraz z sugerowanymi poprawkami.
|
||||
|
||||
### 15) Audyt konfiguracji supervisora + naprawa
|
||||
|
||||
Doctor sprawdza zainstalowaną konfigurację supervisora (`launchd/systemd/schtasks`) pod kątem
|
||||
brakujących lub nieaktualnych ustawień domyślnych (np. zależności `network-online` w systemd oraz
|
||||
opóźnienia restartu). Po wykryciu niedopasowania rekomenduje aktualizację i może
|
||||
przepisać plik usługi/zadanie do bieżących wartości domyślnych.
|
||||
Doctor sprawdza zainstalowaną konfigurację supervisora (launchd/systemd/schtasks) pod kątem
|
||||
brakujących lub nieaktualnych ustawień domyślnych (np. zależności systemd od network-online i
|
||||
opóźnienia restartu). Gdy wykryje niezgodność, rekomenduje aktualizację i może
|
||||
przepisać plik usługi/zadanie do bieżących ustawień domyślnych.
|
||||
|
||||
Uwagi:
|
||||
|
||||
- `openclaw doctor` pyta o potwierdzenie przed przepisaniem konfiguracji supervisora.
|
||||
- `openclaw doctor --yes` akceptuje domyślne monity naprawcze.
|
||||
- `openclaw doctor` pyta przed przepisaniem konfiguracji supervisora.
|
||||
- `openclaw doctor --yes` akceptuje domyślne monity naprawy.
|
||||
- `openclaw doctor --repair` stosuje zalecane poprawki bez pytań.
|
||||
- `openclaw doctor --repair --force` nadpisuje niestandardowe konfiguracje supervisora.
|
||||
- Jeśli uwierzytelnianie tokenem wymaga tokenu, a `gateway.auth.token` jest zarządzany przez SecretRef, ścieżka instalacji/naprawy usługi w doctor weryfikuje SecretRef, ale nie zapisuje rozwiązanego tokenu w postaci jawnego tekstu do metadanych środowiska usługi supervisora.
|
||||
- Jeśli uwierzytelnianie tokenem wymaga tokenu, a skonfigurowany SecretRef tokenu nie został rozwiązany, doctor blokuje ścieżkę instalacji/naprawy i wyświetla konkretne wskazówki.
|
||||
- Jeśli skonfigurowano jednocześnie `gateway.auth.token` i `gateway.auth.password`, a `gateway.auth.mode` nie jest ustawione, doctor blokuje instalację/naprawę, dopóki tryb nie zostanie jawnie ustawiony.
|
||||
- Dla jednostek user-systemd na Linuksie kontrole rozjazdu tokenów w doctor obejmują teraz zarówno źródła `Environment=`, jak i `EnvironmentFile=` podczas porównywania metadanych uwierzytelniania usługi.
|
||||
- Jeśli uwierzytelnianie tokenem wymaga tokena, a `gateway.auth.token` jest zarządzany przez SecretRef, doctor podczas instalacji/naprawy usługi waliduje SecretRef, ale nie zapisuje rozwiązanych jawnych wartości tokena do metadanych środowiska usługi supervisora.
|
||||
- Jeśli uwierzytelnianie tokenem wymaga tokena, a skonfigurowany token SecretRef nie jest rozwiązany, doctor blokuje ścieżkę instalacji/naprawy z konkretnymi wskazówkami.
|
||||
- Jeśli skonfigurowano zarówno `gateway.auth.token`, jak i `gateway.auth.password`, a `gateway.auth.mode` nie jest ustawione, doctor blokuje instalację/naprawę, dopóki tryb nie zostanie ustawiony jawnie.
|
||||
- W przypadku jednostek user-systemd w Linux, kontrole dryfu tokena w doctor obejmują teraz zarówno źródła `Environment=`, jak i `EnvironmentFile=` przy porównywaniu metadanych uwierzytelniania usługi.
|
||||
- Zawsze możesz wymusić pełne przepisanie przez `openclaw gateway install --force`.
|
||||
|
||||
### 16) Diagnostyka runtime gateway i portu
|
||||
### 16) Diagnostyka środowiska uruchomieniowego gatewaya + portu
|
||||
|
||||
Doctor analizuje runtime usługi (PID, ostatni status zakończenia) i ostrzega, gdy
|
||||
usługa jest zainstalowana, ale faktycznie nie działa. Sprawdza także kolizje portu
|
||||
gateway (domyślnie `18789`) i raportuje prawdopodobne przyczyny (gateway już działa,
|
||||
tunel SSH).
|
||||
Doctor sprawdza środowisko uruchomieniowe usługi (PID, ostatni status zakończenia) i ostrzega, gdy
|
||||
usługa jest zainstalowana, ale faktycznie nie działa. Sprawdza też kolizje portu
|
||||
gatewaya (domyślnie `18789`) i raportuje prawdopodobne przyczyny (gateway już
|
||||
działa, tunel SSH).
|
||||
|
||||
### 17) Dobre praktyki runtime gateway
|
||||
### 17) Najlepsze praktyki środowiska uruchomieniowego gatewaya
|
||||
|
||||
Doctor ostrzega, gdy usługa gateway działa na Bun albo na ścieżce Node zarządzanej przez menedżer wersji
|
||||
(`nvm`, `fnm`, `volta`, `asdf` itd.). Kanały WhatsApp i Telegram wymagają Node,
|
||||
Doctor ostrzega, gdy usługa gatewaya działa na Bun lub na ścieżce Node zarządzanej przez menedżer wersji
|
||||
(`nvm`, `fnm`, `volta`, `asdf` itd.). Kanały WhatsApp + Telegram wymagają Node,
|
||||
a ścieżki menedżerów wersji mogą przestać działać po aktualizacjach, ponieważ usługa nie
|
||||
ładuje inicjalizacji powłoki użytkownika. Doctor oferuje migrację do systemowej instalacji Node, jeśli
|
||||
ładuje inicjalizacji powłoki. Doctor oferuje migrację do systemowej instalacji Node, gdy
|
||||
jest dostępna (Homebrew/apt/choco).
|
||||
|
||||
### 18) Zapis konfiguracji + metadane kreatora
|
||||
|
||||
Doctor zapisuje wszystkie zmiany konfiguracji i oznacza metadane kreatora, aby odnotować
|
||||
Doctor utrwala wszystkie zmiany konfiguracji i zapisuje metadane kreatora, aby odnotować
|
||||
uruchomienie doctor.
|
||||
|
||||
### 19) Wskazówki dotyczące workspace (backup + system pamięci)
|
||||
### 19) Wskazówki dotyczące workspace (kopia zapasowa + system pamięci)
|
||||
|
||||
Doctor sugeruje system pamięci workspace, jeśli go brakuje, i wyświetla wskazówkę dotyczącą kopii zapasowej,
|
||||
jeśli workspace nie jest już pod kontrolą git.
|
||||
jeśli workspace nie jest już pod kontrolą gita.
|
||||
|
||||
Zobacz [/concepts/agent-workspace](/pl/concepts/agent-workspace), aby uzyskać pełny przewodnik po
|
||||
strukturze workspace i kopiach zapasowych git (zalecane prywatne GitHub lub GitLab).
|
||||
Zobacz [/concepts/agent-workspace](/pl/concepts/agent-workspace), aby przeczytać pełny przewodnik po
|
||||
strukturze workspace i kopiach zapasowych w git (zalecane prywatne GitHub lub GitLab).
|
||||
|
||||
@ -1,41 +1,41 @@
|
||||
---
|
||||
read_when:
|
||||
- Dostosowywanie częstotliwości heartbeat lub komunikatów
|
||||
- Podejmowanie decyzji między heartbeat a cron dla zaplanowanych zadań
|
||||
- Wybór między heartbeat a cron dla zaplanowanych zadań
|
||||
summary: Komunikaty odpytywania heartbeat i reguły powiadomień
|
||||
title: Heartbeat
|
||||
x-i18n:
|
||||
generated_at: "2026-04-05T13:53:47Z"
|
||||
generated_at: "2026-04-08T02:15:24Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: f417b0d4453bed9022144d364521a59dec919d44cca8f00f0def005cd38b146f
|
||||
source_hash: a8021d747637060eacb91ec5f75904368a08790c19f4fca32acda8c8c0a25e41
|
||||
source_path: gateway/heartbeat.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Heartbeat (Gateway)
|
||||
|
||||
> **Heartbeat czy Cron?** Zobacz [Automation & Tasks](/pl/automation), aby uzyskać wskazówki, kiedy używać każdego z nich.
|
||||
> **Heartbeat czy Cron?** Zobacz [Automatyzacja i zadania](/pl/automation), aby dowiedzieć się, kiedy używać każdego z nich.
|
||||
|
||||
Heartbeat uruchamia **okresowe tury agenta** w głównej sesji, dzięki czemu model może
|
||||
pokazać wszystko, co wymaga uwagi, bez spamowania Cię.
|
||||
Heartbeat uruchamia **okresowe tury agenta** w głównej sesji, aby model mógł
|
||||
zwracać uwagę na wszystko, co wymaga uwagi, bez spamowania Cię.
|
||||
|
||||
Heartbeat to zaplanowana tura głównej sesji — **nie** tworzy rekordów [background task](/pl/automation/tasks).
|
||||
Heartbeat to zaplanowana tura głównej sesji — **nie** tworzy rekordów [zadań w tle](/pl/automation/tasks).
|
||||
Rekordy zadań służą do pracy odłączonej (uruchomienia ACP, subagenci, izolowane zadania cron).
|
||||
|
||||
Rozwiązywanie problemów: [Scheduled Tasks](/pl/automation/cron-jobs#troubleshooting)
|
||||
Rozwiązywanie problemów: [Zaplanowane zadania](/pl/automation/cron-jobs#troubleshooting)
|
||||
|
||||
## Szybki start (dla początkujących)
|
||||
|
||||
1. Pozostaw heartbeat włączony (domyślnie `30m` albo `1h` dla uwierzytelniania Anthropic OAuth/token, w tym ponownego użycia Claude CLI) albo ustaw własną częstotliwość.
|
||||
2. Utwórz małą listę kontrolną `HEARTBEAT.md` lub blok `tasks:` w workspace agenta (opcjonalne, ale zalecane).
|
||||
3. Zdecyduj, dokąd mają trafiać komunikaty heartbeat (`target: "none"` jest wartością domyślną; ustaw `target: "last"`, aby kierować je do ostatniego kontaktu).
|
||||
4. Opcjonalnie włącz dostarczanie rozumowania heartbeat dla większej przejrzystości.
|
||||
5. Opcjonalnie użyj lekkiego kontekstu bootstrap, jeśli uruchomienia heartbeat potrzebują tylko `HEARTBEAT.md`.
|
||||
6. Opcjonalnie włącz izolowane sesje, aby nie wysyłać pełnej historii rozmowy przy każdym heartbeat.
|
||||
7. Opcjonalnie ogranicz heartbeat do aktywnych godzin (czas lokalny).
|
||||
1. Pozostaw heartbeat włączony (domyślnie `30m` lub `1h` dla uwierzytelniania Anthropic OAuth/token, w tym ponownego użycia Claude CLI) albo ustaw własną częstotliwość.
|
||||
2. Utwórz małą listę kontrolną `HEARTBEAT.md` lub blok `tasks:` w obszarze roboczym agenta (opcjonalne, ale zalecane).
|
||||
3. Zdecyduj, gdzie mają trafiać komunikaty heartbeat (`target: "none"` jest domyślne; ustaw `target: "last"`, aby kierować je do ostatniego kontaktu).
|
||||
4. Opcjonalnie: włącz dostarczanie rozumowania heartbeat dla większej przejrzystości.
|
||||
5. Opcjonalnie: użyj lekkiego kontekstu początkowego, jeśli uruchomienia heartbeat potrzebują tylko `HEARTBEAT.md`.
|
||||
6. Opcjonalnie: włącz izolowane sesje, aby nie wysyłać całej historii rozmowy przy każdym heartbeat.
|
||||
7. Opcjonalnie: ogranicz heartbeat do aktywnych godzin (czas lokalny).
|
||||
|
||||
Przykładowy config:
|
||||
Przykładowa konfiguracja:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -43,58 +43,61 @@ Przykładowy config:
|
||||
defaults: {
|
||||
heartbeat: {
|
||||
every: "30m",
|
||||
target: "last", // jawne dostarczanie do ostatniego kontaktu (domyślnie jest "none")
|
||||
directPolicy: "allow", // domyślnie: zezwalaj na cele direct/DM; ustaw "block", aby wyciszyć
|
||||
lightContext: true, // opcjonalnie: wstrzykuj tylko HEARTBEAT.md z plików bootstrap
|
||||
isolatedSession: true, // opcjonalnie: nowa sesja przy każdym uruchomieniu (bez historii rozmowy)
|
||||
target: "last", // jawne dostarczanie do ostatniego kontaktu (domyślnie "none")
|
||||
directPolicy: "allow", // domyślnie: zezwalaj na cele bezpośrednie/DM; ustaw "block", aby je wyciszyć
|
||||
lightContext: true, // opcjonalne: wstrzykuj tylko HEARTBEAT.md z plików bootstrap kontekstu
|
||||
isolatedSession: true, // opcjonalne: świeża sesja przy każdym uruchomieniu (bez historii rozmowy)
|
||||
// activeHours: { start: "08:00", end: "24:00" },
|
||||
// includeReasoning: true, // opcjonalnie: wyślij też osobny komunikat `Reasoning:`
|
||||
// includeReasoning: true, // opcjonalne: wysyłaj też osobny komunikat `Reasoning:`
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
## Wartości domyślne
|
||||
## Ustawienia domyślne
|
||||
|
||||
- Interwał: `30m` (albo `1h`, gdy wykrytym trybem uwierzytelniania jest Anthropic OAuth/token, w tym ponowne użycie Claude CLI). Ustaw `agents.defaults.heartbeat.every` albo per agent `agents.list[].heartbeat.every`; użyj `0m`, aby wyłączyć.
|
||||
- Interwał: `30m` (lub `1h`, gdy wykrytym trybem uwierzytelniania jest Anthropic OAuth/token, w tym ponowne użycie Claude CLI). Ustaw `agents.defaults.heartbeat.every` lub dla konkretnego agenta `agents.list[].heartbeat.every`; użyj `0m`, aby wyłączyć.
|
||||
- Treść promptu (konfigurowalna przez `agents.defaults.heartbeat.prompt`):
|
||||
`Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.`
|
||||
- Prompt heartbeat jest wysyłany **dosłownie** jako wiadomość użytkownika. Prompt
|
||||
systemowy zawiera sekcję „Heartbeat”, a uruchomienie jest oznaczane wewnętrznie.
|
||||
systemowy zawiera sekcję „Heartbeat” tylko wtedy, gdy heartbeat jest włączony dla
|
||||
domyślnego agenta, a uruchomienie jest oznaczone wewnętrznie.
|
||||
- Gdy heartbeat jest wyłączony przez `0m`, zwykłe uruchomienia także pomijają `HEARTBEAT.md`
|
||||
z kontekstu bootstrap, aby model nie widział instrukcji przeznaczonych wyłącznie dla heartbeat.
|
||||
- Aktywne godziny (`heartbeat.activeHours`) są sprawdzane w skonfigurowanej strefie czasowej.
|
||||
Poza oknem heartbeat są pomijane aż do następnego tyknięcia wewnątrz okna.
|
||||
Poza tym oknem heartbeat jest pomijany aż do następnego tyknięcia w obrębie okna.
|
||||
|
||||
## Do czego służy prompt heartbeat
|
||||
|
||||
Domyślny prompt jest celowo szeroki:
|
||||
|
||||
- **Background tasks**: „Consider outstanding tasks” skłania agenta do przeglądania
|
||||
zadań do wykonania (skrzynka odbiorcza, kalendarz, przypomnienia, kolejka pracy) i sygnalizowania wszystkiego, co pilne.
|
||||
- **Sprawdzenie u człowieka**: „Checkup sometimes on your human during day time” skłania do
|
||||
okazjonalnego lekkiego komunikatu „czy czegoś potrzebujesz?”, ale unika nocnego spamu
|
||||
dzięki użyciu Twojej skonfigurowanej lokalnej strefy czasowej (zobacz [/concepts/timezone](/concepts/timezone)).
|
||||
- **Zadania w tle**: „Rozważ zaległe zadania” zachęca agenta do przeglądu
|
||||
działań następczych (skrzynka odbiorcza, kalendarz, przypomnienia, kolejka pracy) i sygnalizowania wszystkiego, co pilne.
|
||||
- **Kontakt z człowiekiem**: „Sprawdź czasem swojego człowieka w ciągu dnia” zachęca do
|
||||
okazjonalnego lekkiego komunikatu w rodzaju „czy czegoś potrzebujesz?”, ale unika nocnego spamu
|
||||
dzięki użyciu skonfigurowanej lokalnej strefy czasowej (zobacz [/concepts/timezone](/pl/concepts/timezone)).
|
||||
|
||||
Heartbeat może reagować na ukończone [background tasks](/pl/automation/tasks), ale samo uruchomienie heartbeat nie tworzy rekordu zadania.
|
||||
Heartbeat może reagować na ukończone [zadania w tle](/pl/automation/tasks), ale samo uruchomienie heartbeat nie tworzy rekordu zadania.
|
||||
|
||||
Jeśli chcesz, aby heartbeat robił coś bardzo konkretnego (np. „sprawdź statystyki Gmail PubSub”
|
||||
albo „zweryfikuj stan gateway”), ustaw `agents.defaults.heartbeat.prompt` (lub
|
||||
`agents.list[].heartbeat.prompt`) na niestandardową treść (wysyłaną dosłownie).
|
||||
lub „zweryfikuj stan gateway”), ustaw `agents.defaults.heartbeat.prompt` (lub
|
||||
`agents.list[].heartbeat.prompt`) na własną treść (wysyłaną dosłownie).
|
||||
|
||||
## Kontrakt odpowiedzi
|
||||
|
||||
- Jeśli nic nie wymaga uwagi, odpowiedz **`HEARTBEAT_OK`**.
|
||||
- Podczas uruchomień heartbeat OpenClaw traktuje `HEARTBEAT_OK` jako potwierdzenie, gdy pojawia się
|
||||
na **początku lub końcu** odpowiedzi. Token jest usuwany, a odpowiedź jest
|
||||
na **początku lub końcu** odpowiedzi. Token jest usuwany, a odpowiedź
|
||||
odrzucana, jeśli pozostała treść ma **≤ `ackMaxChars`** (domyślnie: 300).
|
||||
- Jeśli `HEARTBEAT_OK` pojawia się **w środku** odpowiedzi, nie jest traktowane
|
||||
w specjalny sposób.
|
||||
- W przypadku alertów **nie** dołączaj `HEARTBEAT_OK`; zwróć tylko tekst alertu.
|
||||
- Jeśli `HEARTBEAT_OK` pojawia się **w środku** odpowiedzi, nie jest traktowany
|
||||
specjalnie.
|
||||
- W przypadku alertów **nie** dołączaj `HEARTBEAT_OK`; zwróć tylko treść alertu.
|
||||
|
||||
Poza heartbeat przypadkowe `HEARTBEAT_OK` na początku/końcu wiadomości jest usuwane
|
||||
i logowane; wiadomość zawierająca wyłącznie `HEARTBEAT_OK` jest odrzucana.
|
||||
i logowane; wiadomość będąca wyłącznie `HEARTBEAT_OK` jest odrzucana.
|
||||
|
||||
## Config
|
||||
## Konfiguracja
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -103,14 +106,14 @@ i logowane; wiadomość zawierająca wyłącznie `HEARTBEAT_OK` jest odrzucana.
|
||||
heartbeat: {
|
||||
every: "30m", // domyślnie: 30m (0m wyłącza)
|
||||
model: "anthropic/claude-opus-4-6",
|
||||
includeReasoning: false, // domyślnie: false (dostarczaj osobny komunikat Reasoning: gdy dostępny)
|
||||
lightContext: false, // domyślnie: false; true zachowuje tylko HEARTBEAT.md z plików bootstrap workspace
|
||||
isolatedSession: false, // domyślnie: false; true uruchamia każdy heartbeat w nowej sesji (bez historii rozmowy)
|
||||
target: "last", // domyślnie: none | opcje: last | none | <channel id> (core lub wtyczka, np. "bluebubbles")
|
||||
includeReasoning: false, // domyślnie: false (dostarczaj osobny komunikat Reasoning:, gdy dostępny)
|
||||
lightContext: false, // domyślnie: false; true zachowuje tylko HEARTBEAT.md z plików bootstrap obszaru roboczego
|
||||
isolatedSession: false, // domyślnie: false; true uruchamia każdy heartbeat w świeżej sesji (bez historii rozmowy)
|
||||
target: "last", // domyślnie: none | opcje: last | none | <id kanału> (rdzeń lub plugin, np. "bluebubbles")
|
||||
to: "+15551234567", // opcjonalne nadpisanie specyficzne dla kanału
|
||||
accountId: "ops-bot", // opcjonalny identyfikator kanału wielokontowego
|
||||
accountId: "ops-bot", // opcjonalny identyfikator kanału dla wielu kont
|
||||
prompt: "Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.",
|
||||
ackMaxChars: 300, // maks. liczba znaków dozwolona po HEARTBEAT_OK
|
||||
ackMaxChars: 300, // maksymalna liczba znaków dozwolona po HEARTBEAT_OK
|
||||
},
|
||||
},
|
||||
},
|
||||
@ -120,18 +123,18 @@ i logowane; wiadomość zawierająca wyłącznie `HEARTBEAT_OK` jest odrzucana.
|
||||
### Zakres i pierwszeństwo
|
||||
|
||||
- `agents.defaults.heartbeat` ustawia globalne zachowanie heartbeat.
|
||||
- `agents.list[].heartbeat` scala się na wierzchu; jeśli którykolwiek agent ma blok `heartbeat`, **tylko ci agenci** uruchamiają heartbeat.
|
||||
- `channels.defaults.heartbeat` ustawia domyślne ustawienia widoczności dla wszystkich kanałów.
|
||||
- `channels.<channel>.heartbeat` nadpisuje domyślne ustawienia kanału.
|
||||
- `channels.<channel>.accounts.<id>.heartbeat` (kanały wielokontowe) nadpisuje ustawienia per kanał.
|
||||
- `agents.list[].heartbeat` nakłada się na to; jeśli jakikolwiek agent ma blok `heartbeat`, heartbeat uruchamiają **tylko ci agenci**.
|
||||
- `channels.defaults.heartbeat` ustawia domyślną widoczność dla wszystkich kanałów.
|
||||
- `channels.<channel>.heartbeat` nadpisuje ustawienia domyślne kanałów.
|
||||
- `channels.<channel>.accounts.<id>.heartbeat` (kanały z wieloma kontami) nadpisuje ustawienia dla danego kanału.
|
||||
|
||||
### Heartbeat per agent
|
||||
### Heartbeat dla konkretnego agenta
|
||||
|
||||
Jeśli którykolwiek wpis `agents.list[]` zawiera blok `heartbeat`, **tylko ci agenci**
|
||||
uruchamiają heartbeat. Blok per agent scala się na wierzchu `agents.defaults.heartbeat`
|
||||
(dzięki czemu możesz ustawić wspólne wartości domyślne raz i nadpisać je per agent).
|
||||
Jeśli dowolny wpis `agents.list[]` zawiera blok `heartbeat`, heartbeat uruchamiają
|
||||
**tylko ci agenci**. Blok per-agent nakłada się na `agents.defaults.heartbeat`
|
||||
(dzięki czemu możesz raz ustawić wspólne wartości domyślne i nadpisać je dla poszczególnych agentów).
|
||||
|
||||
Przykład: dwóch agentów, tylko drugi agent uruchamia heartbeat.
|
||||
Przykład: dwóch agentów, heartbeat uruchamia tylko drugi agent.
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -139,7 +142,7 @@ Przykład: dwóch agentów, tylko drugi agent uruchamia heartbeat.
|
||||
defaults: {
|
||||
heartbeat: {
|
||||
every: "30m",
|
||||
target: "last", // jawne dostarczanie do ostatniego kontaktu (domyślnie jest "none")
|
||||
target: "last", // jawne dostarczanie do ostatniego kontaktu (domyślnie "none")
|
||||
},
|
||||
},
|
||||
list: [
|
||||
@ -168,11 +171,11 @@ Ogranicz heartbeat do godzin pracy w określonej strefie czasowej:
|
||||
defaults: {
|
||||
heartbeat: {
|
||||
every: "30m",
|
||||
target: "last", // jawne dostarczanie do ostatniego kontaktu (domyślnie jest "none")
|
||||
target: "last", // jawne dostarczanie do ostatniego kontaktu (domyślnie "none")
|
||||
activeHours: {
|
||||
start: "09:00",
|
||||
end: "22:00",
|
||||
timezone: "America/New_York", // opcjonalne; używa userTimezone, jeśli ustawiono, w przeciwnym razie strefy hosta
|
||||
timezone: "America/New_York", // opcjonalne; używa userTimezone, jeśli jest ustawione, w przeciwnym razie strefy hosta
|
||||
},
|
||||
},
|
||||
},
|
||||
@ -180,21 +183,21 @@ Ogranicz heartbeat do godzin pracy w określonej strefie czasowej:
|
||||
}
|
||||
```
|
||||
|
||||
Poza tym oknem (przed 9:00 lub po 22:00 czasu wschodniego) heartbeat są pomijane. Następne zaplanowane tyknięcie wewnątrz okna uruchomi się normalnie.
|
||||
Poza tym oknem (przed 9:00 lub po 22:00 czasu wschodniego) heartbeat jest pomijany. Następne zaplanowane tyknięcie w obrębie okna uruchomi się normalnie.
|
||||
|
||||
### Konfiguracja 24/7
|
||||
|
||||
Jeśli chcesz, aby heartbeat działał przez cały dzień, użyj jednego z tych wzorców:
|
||||
Jeśli chcesz, aby heartbeat działał przez całą dobę, użyj jednego z tych wzorców:
|
||||
|
||||
- Pomiń `activeHours` całkowicie (brak ograniczenia oknem czasowym; to zachowanie domyślne).
|
||||
- Ustaw okno całodniowe: `activeHours: { start: "00:00", end: "24:00" }`.
|
||||
- Całkowicie pomiń `activeHours` (brak ograniczenia okna czasowego; to zachowanie domyślne).
|
||||
- Ustaw pełnodobowe okno: `activeHours: { start: "00:00", end: "24:00" }`.
|
||||
|
||||
Nie ustawiaj tej samej godziny `start` i `end` (na przykład `08:00` do `08:00`).
|
||||
Jest to traktowane jako okno o zerowej szerokości, więc heartbeat są zawsze pomijane.
|
||||
Nie ustawiaj tej samej godziny dla `start` i `end` (na przykład `08:00` do `08:00`).
|
||||
Jest to traktowane jako okno o zerowej szerokości, więc heartbeat jest zawsze pomijany.
|
||||
|
||||
### Przykład wielu kont
|
||||
|
||||
Użyj `accountId`, aby kierować na konkretne konto w kanałach wielokontowych, takich jak Telegram:
|
||||
Użyj `accountId`, aby kierować do konkretnego konta w kanałach z wieloma kontami, takich jak Telegram:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -205,7 +208,7 @@ Użyj `accountId`, aby kierować na konkretne konto w kanałach wielokontowych,
|
||||
heartbeat: {
|
||||
every: "1h",
|
||||
target: "telegram",
|
||||
to: "12345678:topic:42", // opcjonalnie: kieruj do konkretnego tematu/wątku
|
||||
to: "12345678:topic:42", // opcjonalne: kierowanie do konkretnego tematu/wątku
|
||||
accountId: "ops-bot",
|
||||
},
|
||||
},
|
||||
@ -221,58 +224,58 @@ Użyj `accountId`, aby kierować na konkretne konto w kanałach wielokontowych,
|
||||
}
|
||||
```
|
||||
|
||||
### Uwagi dotyczące pól
|
||||
### Uwagi do pól
|
||||
|
||||
- `every`: interwał heartbeat (ciąg czasu trwania; domyślna jednostka = minuty).
|
||||
- `model`: opcjonalne nadpisanie modelu dla uruchomień heartbeat (`provider/model`).
|
||||
- `includeReasoning`: gdy włączone, dostarcza również osobny komunikat `Reasoning:` gdy jest dostępny (ten sam kształt co `/reasoning on`).
|
||||
- `lightContext`: gdy true, uruchomienia heartbeat używają lekkiego kontekstu bootstrap i zachowują tylko `HEARTBEAT.md` z plików bootstrap workspace.
|
||||
- `isolatedSession`: gdy true, każdy heartbeat działa w nowej sesji bez wcześniejszej historii rozmowy. Używa tego samego wzorca izolacji co cron `sessionTarget: "isolated"`. Radykalnie obniża koszt tokenów per heartbeat. Połącz z `lightContext: true`, aby uzyskać maksymalne oszczędności. Routing dostarczania nadal używa kontekstu głównej sesji.
|
||||
- `includeReasoning`: gdy włączone, dostarcza też osobny komunikat `Reasoning:`, gdy jest dostępny (ten sam format co `/reasoning on`).
|
||||
- `lightContext`: gdy true, uruchomienia heartbeat używają lekkiego kontekstu bootstrap i zachowują tylko `HEARTBEAT.md` z plików bootstrap obszaru roboczego.
|
||||
- `isolatedSession`: gdy true, każdy heartbeat działa w świeżej sesji bez wcześniejszej historii rozmowy. Używa tego samego wzorca izolacji co cron `sessionTarget: "isolated"`. Drastycznie zmniejsza koszt tokenów na jeden heartbeat. Połącz z `lightContext: true`, aby uzyskać maksymalne oszczędności. Routowanie dostarczania nadal używa kontekstu głównej sesji.
|
||||
- `session`: opcjonalny klucz sesji dla uruchomień heartbeat.
|
||||
- `main` (domyślnie): główna sesja agenta.
|
||||
- Jawny klucz sesji (skopiuj z `openclaw sessions --json` lub z [CLI sesji](/cli/sessions)).
|
||||
- Formaty kluczy sesji: zobacz [Sessions](/concepts/session) i [Groups](/pl/channels/groups).
|
||||
- Jawny klucz sesji (skopiuj z `openclaw sessions --json` lub z [sessions CLI](/cli/sessions)).
|
||||
- Formaty kluczy sesji: zobacz [Sesje](/pl/concepts/session) i [Grupy](/pl/channels/groups).
|
||||
- `target`:
|
||||
- `last`: dostarczaj do ostatnio użytego zewnętrznego kanału.
|
||||
- jawny kanał: dowolny skonfigurowany kanał lub identyfikator wtyczki, na przykład `discord`, `matrix`, `telegram` albo `whatsapp`.
|
||||
- `none` (domyślnie): uruchom heartbeat, ale **nie dostarczaj** niczego na zewnątrz.
|
||||
- `directPolicy`: steruje zachowaniem dostarczania direct/DM:
|
||||
- `allow` (domyślnie): zezwalaj na dostarczanie heartbeat do celów direct/DM.
|
||||
- `block`: wycisz dostarczanie direct/DM (`reason=dm-blocked`).
|
||||
- `to`: opcjonalne nadpisanie odbiorcy (identyfikator specyficzny dla kanału, np. E.164 dla WhatsApp albo identyfikator czatu Telegram). Dla tematów/wątków Telegram użyj `<chatId>:topic:<messageThreadId>`.
|
||||
- `accountId`: opcjonalny identyfikator konta dla kanałów wielokontowych. Gdy `target: "last"`, identyfikator konta ma zastosowanie do rozpoznanego ostatniego kanału, jeśli obsługuje konta; w przeciwnym razie jest ignorowany. Jeśli identyfikator konta nie pasuje do skonfigurowanego konta dla rozpoznanego kanału, dostarczenie jest pomijane.
|
||||
- jawny kanał: dowolny skonfigurowany kanał lub identyfikator pluginu, na przykład `discord`, `matrix`, `telegram` lub `whatsapp`.
|
||||
- `none` (domyślnie): uruchom heartbeat, ale **nie dostarczaj** go na zewnątrz.
|
||||
- `directPolicy`: steruje zachowaniem dostarczania bezpośredniego/DM:
|
||||
- `allow` (domyślnie): zezwalaj na bezpośrednie/DM dostarczanie heartbeat.
|
||||
- `block`: wycisz dostarczanie bezpośrednie/DM (`reason=dm-blocked`).
|
||||
- `to`: opcjonalne nadpisanie odbiorcy (identyfikator specyficzny dla kanału, np. E.164 dla WhatsApp lub identyfikator czatu Telegram). Dla tematów/wątków Telegram użyj `<chatId>:topic:<messageThreadId>`.
|
||||
- `accountId`: opcjonalny identyfikator konta dla kanałów z wieloma kontami. Gdy `target: "last"`, identyfikator konta ma zastosowanie do rozstrzygniętego ostatniego kanału, jeśli obsługuje konta; w przeciwnym razie jest ignorowany. Jeśli identyfikator konta nie pasuje do skonfigurowanego konta dla rozstrzygniętego kanału, dostarczenie jest pomijane.
|
||||
- `prompt`: nadpisuje domyślną treść promptu (bez scalania).
|
||||
- `ackMaxChars`: maks. liczba znaków dozwolona po `HEARTBEAT_OK` przed dostarczeniem.
|
||||
- `ackMaxChars`: maksymalna liczba znaków dozwolona po `HEARTBEAT_OK` przed dostarczeniem.
|
||||
- `suppressToolErrorWarnings`: gdy true, wycisza ładunki ostrzeżeń o błędach narzędzi podczas uruchomień heartbeat.
|
||||
- `activeHours`: ogranicza uruchomienia heartbeat do okna czasowego. Obiekt z `start` (HH:MM, włącznie; użyj `00:00` dla początku dnia), `end` (HH:MM, wyłącznie; `24:00` jest dozwolone dla końca dnia) oraz opcjonalnym `timezone`.
|
||||
- Pominięte lub `"user"`: używa Twojego `agents.defaults.userTimezone`, jeśli ustawiono, w przeciwnym razie wraca do strefy czasowej systemu hosta.
|
||||
- `activeHours`: ogranicza uruchomienia heartbeat do okna czasowego. Obiekt z `start` (HH:MM, włącznie; użyj `00:00` dla początku dnia), `end` (HH:MM, wyłącznie; `24:00` dozwolone dla końca dnia) oraz opcjonalnym `timezone`.
|
||||
- Pominięte lub `"user"`: używa Twojego `agents.defaults.userTimezone`, jeśli jest ustawione, w przeciwnym razie wraca do strefy czasowej systemu hosta.
|
||||
- `"local"`: zawsze używa strefy czasowej systemu hosta.
|
||||
- Dowolny identyfikator IANA (np. `America/New_York`): używany bezpośrednio; jeśli jest nieprawidłowy, następuje fallback do zachowania `"user"` opisanego powyżej.
|
||||
- Dowolny identyfikator IANA (np. `America/New_York`): używany bezpośrednio; jeśli jest nieprawidłowy, wraca do zachowania `"user"` opisanego wyżej.
|
||||
- `start` i `end` nie mogą być równe dla aktywnego okna; równe wartości są traktowane jako zerowa szerokość (zawsze poza oknem).
|
||||
- Poza aktywnym oknem heartbeat są pomijane aż do następnego tyknięcia wewnątrz okna.
|
||||
- Poza aktywnym oknem heartbeat jest pomijany aż do następnego tyknięcia w obrębie okna.
|
||||
|
||||
## Zachowanie dostarczania
|
||||
|
||||
- Heartbeat są domyślnie uruchamiane w głównej sesji agenta (`agent:<id>:<mainKey>`),
|
||||
albo `global`, gdy `session.scope = "global"`. Ustaw `session`, aby nadpisać na
|
||||
konkretną sesję kanału (Discord/WhatsApp/itd.).
|
||||
- Heartbeat domyślnie działa w głównej sesji agenta (`agent:<id>:<mainKey>`),
|
||||
lub `global`, gdy `session.scope = "global"`. Ustaw `session`, aby nadpisać na
|
||||
konkretną sesję kanału (Discord/WhatsApp/itp.).
|
||||
- `session` wpływa tylko na kontekst uruchomienia; dostarczaniem sterują `target` i `to`.
|
||||
- Aby dostarczyć do konkretnego kanału/odbiorcy, ustaw `target` + `to`. Przy
|
||||
`target: "last"` dostarczenie używa ostatniego zewnętrznego kanału dla tej sesji.
|
||||
- Dostarczanie heartbeat domyślnie zezwala na cele direct/DM. Ustaw `directPolicy: "block"`, aby wyciszyć wysyłanie do celów direct przy jednoczesnym zachowaniu tury heartbeat.
|
||||
- Aby dostarczać do konkretnego kanału/odbiorcy, ustaw `target` + `to`. Przy
|
||||
`target: "last"` dostarczanie używa ostatniego zewnętrznego kanału dla tej sesji.
|
||||
- Dostarczenia heartbeat domyślnie zezwalają na cele bezpośrednie/DM. Ustaw `directPolicy: "block"`, aby wyciszyć wysyłki do celów bezpośrednich, nadal uruchamiając turę heartbeat.
|
||||
- Jeśli główna kolejka jest zajęta, heartbeat jest pomijany i ponawiany później.
|
||||
- Jeśli `target` nie rozpozna żadnego zewnętrznego miejsca docelowego, uruchomienie nadal następuje, ale żadna
|
||||
- Jeśli `target` nie rozstrzyga się do zewnętrznego miejsca docelowego, uruchomienie nadal następuje, ale
|
||||
wiadomość wychodząca nie jest wysyłana.
|
||||
- Jeśli `showOk`, `showAlerts` i `useIndicator` są wszystkie wyłączone, uruchomienie jest pomijane od razu z `reason=alerts-disabled`.
|
||||
- Jeśli wyłączone jest tylko dostarczanie alertów, OpenClaw nadal może uruchomić heartbeat, zaktualizować znaczniki czasu zadań wymagających wykonania, przywrócić znacznik bezczynności sesji i wyciszyć zewnętrzny ładunek alertu.
|
||||
- Odpowiedzi tylko-heartbeat **nie** utrzymują sesji przy życiu; ostatnie `updatedAt`
|
||||
jest przywracane, aby wygaśnięcie bezczynności zachowywało się normalnie.
|
||||
- Odłączone [background tasks](/pl/automation/tasks) mogą umieścić zdarzenie systemowe w kolejce i wybudzić heartbeat, gdy główna sesja powinna szybko coś zauważyć. To wybudzenie nie sprawia, że heartbeat staje się background task.
|
||||
- Jeśli `showOk`, `showAlerts` i `useIndicator` są wszystkie wyłączone, uruchomienie jest od razu pomijane jako `reason=alerts-disabled`.
|
||||
- Jeśli wyłączone jest tylko dostarczanie alertów, OpenClaw nadal może uruchomić heartbeat, zaktualizować znaczniki czasu zadań należnych, przywrócić znacznik bezczynności sesji i wyciszyć zewnętrzny ładunek alertu.
|
||||
- Odpowiedzi wyłącznie heartbeat **nie** utrzymują sesji przy życiu; ostatnie `updatedAt`
|
||||
jest przywracane, aby wygaśnięcie bezczynności działało normalnie.
|
||||
- Odłączone [zadania w tle](/pl/automation/tasks) mogą umieszczać zdarzenie systemowe w kolejce i wybudzać heartbeat, gdy główna sesja powinna szybko coś zauważyć. Takie wybudzenie nie sprawia, że heartbeat staje się zadaniem w tle.
|
||||
|
||||
## Sterowanie widocznością
|
||||
## Kontrola widoczności
|
||||
|
||||
Domyślnie potwierdzenia `HEARTBEAT_OK` są ukrywane, podczas gdy treść alertów jest
|
||||
dostarczana. Możesz to dostosować per kanał lub per konto:
|
||||
Domyślnie potwierdzenia `HEARTBEAT_OK` są wyciszane, a treść alertów jest
|
||||
dostarczana. Możesz dostosować to dla kanału lub konta:
|
||||
|
||||
```yaml
|
||||
channels:
|
||||
@ -283,7 +286,7 @@ channels:
|
||||
useIndicator: true # Emituj zdarzenia wskaźnika (domyślnie)
|
||||
telegram:
|
||||
heartbeat:
|
||||
showOk: true # Pokazuj potwierdzenia OK na Telegramie
|
||||
showOk: true # Pokazuj potwierdzenia OK w Telegramie
|
||||
whatsapp:
|
||||
accounts:
|
||||
work:
|
||||
@ -291,17 +294,17 @@ channels:
|
||||
showAlerts: false # Wycisz dostarczanie alertów dla tego konta
|
||||
```
|
||||
|
||||
Pierwszeństwo: per konto → per kanał → domyślne kanału → wbudowane wartości domyślne.
|
||||
Pierwszeństwo: per-account → per-channel → domyślne kanału → wbudowane wartości domyślne.
|
||||
|
||||
### Co robi każda flaga
|
||||
|
||||
- `showOk`: wysyła potwierdzenie `HEARTBEAT_OK`, gdy model zwraca odpowiedź zawierającą wyłącznie OK.
|
||||
- `showOk`: wysyła potwierdzenie `HEARTBEAT_OK`, gdy model zwraca odpowiedź zawierającą tylko OK.
|
||||
- `showAlerts`: wysyła treść alertu, gdy model zwraca odpowiedź inną niż OK.
|
||||
- `useIndicator`: emituje zdarzenia wskaźnika dla powierzchni statusu UI.
|
||||
|
||||
Jeśli **wszystkie trzy** mają wartość false, OpenClaw całkowicie pomija uruchomienie heartbeat (bez wywołania modelu).
|
||||
|
||||
### Przykłady per kanał vs per konto
|
||||
### Przykłady per-channel i per-account
|
||||
|
||||
```yaml
|
||||
channels:
|
||||
@ -324,39 +327,44 @@ channels:
|
||||
|
||||
### Typowe wzorce
|
||||
|
||||
| Cel | Config |
|
||||
| Cel | Konfiguracja |
|
||||
| ---------------------------------------- | ---------------------------------------------------------------------------------------- |
|
||||
| Domyślne zachowanie (ciche OK, alerty włączone) | _(brak wymaganego config)_ |
|
||||
| Całkowicie cicho (bez wiadomości, bez wskaźnika) | `channels.defaults.heartbeat: { showOk: false, showAlerts: false, useIndicator: false }` |
|
||||
| Zachowanie domyślne (ciche OK, alerty włączone) | _(nie jest wymagana konfiguracja)_ |
|
||||
| Pełna cisza (bez wiadomości, bez wskaźnika) | `channels.defaults.heartbeat: { showOk: false, showAlerts: false, useIndicator: false }` |
|
||||
| Tylko wskaźnik (bez wiadomości) | `channels.defaults.heartbeat: { showOk: false, showAlerts: false, useIndicator: true }` |
|
||||
| OK tylko w jednym kanale | `channels.telegram.heartbeat: { showOk: true }` |
|
||||
|
||||
## HEARTBEAT.md (opcjonalne)
|
||||
## HEARTBEAT.md (opcjonalnie)
|
||||
|
||||
Jeśli plik `HEARTBEAT.md` istnieje w workspace, domyślny prompt instruuje
|
||||
agenta, aby go odczytał. Pomyśl o nim jak o swojej „liście kontrolnej heartbeat”: małej, stabilnej i
|
||||
bezpiecznej do dołączania co 30 minut.
|
||||
Jeśli plik `HEARTBEAT.md` istnieje w obszarze roboczym, domyślny prompt mówi
|
||||
agentowi, aby go przeczytał. Potraktuj go jako swoją „listę kontrolną heartbeat”: małą, stabilną i
|
||||
bezpieczną do dołączania co 30 minut.
|
||||
|
||||
Jeśli `HEARTBEAT.md` istnieje, ale jest praktycznie pusty (tylko puste linie i nagłówki markdown
|
||||
takie jak `# Heading`), OpenClaw pomija uruchomienie heartbeat, aby oszczędzić wywołania API.
|
||||
To pominięcie jest raportowane jako `reason=empty-heartbeat-file`.
|
||||
Jeśli plik nie istnieje, heartbeat nadal działa, a model sam decyduje, co zrobić.
|
||||
Przy zwykłych uruchomieniach `HEARTBEAT.md` jest wstrzykiwany tylko wtedy, gdy wskazówki heartbeat są
|
||||
włączone dla domyślnego agenta. Wyłączenie częstotliwości heartbeat przez `0m` lub
|
||||
ustawienie `includeSystemPromptSection: false` pomija go w zwykłym kontekście
|
||||
bootstrap.
|
||||
|
||||
Utrzymuj go w małym rozmiarze (krótka lista kontrolna albo przypomnienia), aby uniknąć rozrostu promptu.
|
||||
Jeśli `HEARTBEAT.md` istnieje, ale jest w praktyce pusty (tylko puste linie i nagłówki
|
||||
Markdown takie jak `# Heading`), OpenClaw pomija uruchomienie heartbeat, aby oszczędzić wywołania API.
|
||||
Takie pominięcie jest zgłaszane jako `reason=empty-heartbeat-file`.
|
||||
Jeśli pliku brakuje, heartbeat nadal działa, a model decyduje, co zrobić.
|
||||
|
||||
Utrzymuj go w małym rozmiarze (krótka lista kontrolna lub przypomnienia), aby uniknąć rozrostu promptu.
|
||||
|
||||
Przykładowy `HEARTBEAT.md`:
|
||||
|
||||
```md
|
||||
# Heartbeat checklist
|
||||
# Lista kontrolna heartbeat
|
||||
|
||||
- Quick scan: anything urgent in inboxes?
|
||||
- If it’s daytime, do a lightweight check-in if nothing else is pending.
|
||||
- If a task is blocked, write down _what is missing_ and ask Peter next time.
|
||||
- Szybki przegląd: czy w skrzynkach odbiorczych jest coś pilnego?
|
||||
- Jeśli jest dzień, wykonaj lekki check-in, jeśli nic innego nie czeka.
|
||||
- Jeśli zadanie jest zablokowane, zapisz _czego brakuje_ i zapytaj Petera następnym razem.
|
||||
```
|
||||
|
||||
### Bloki `tasks:`
|
||||
|
||||
`HEARTBEAT.md` obsługuje także mały ustrukturyzowany blok `tasks:` dla kontroli
|
||||
`HEARTBEAT.md` obsługuje także mały strukturalny blok `tasks:` dla sprawdzeń
|
||||
opartych na interwałach wewnątrz samego heartbeat.
|
||||
|
||||
Przykład:
|
||||
@ -366,77 +374,76 @@ tasks:
|
||||
|
||||
- name: inbox-triage
|
||||
interval: 30m
|
||||
prompt: "Check for urgent unread emails and flag anything time sensitive."
|
||||
prompt: "Sprawdź pilne nieprzeczytane e-maile i oznacz wszystko, co jest wrażliwe czasowo."
|
||||
- name: calendar-scan
|
||||
interval: 2h
|
||||
prompt: "Check for upcoming meetings that need prep or follow-up."
|
||||
prompt: "Sprawdź nadchodzące spotkania, które wymagają przygotowania lub działań następczych."
|
||||
|
||||
# Additional instructions
|
||||
# Dodatkowe instrukcje
|
||||
|
||||
- Keep alerts short.
|
||||
- If nothing needs attention after all due tasks, reply HEARTBEAT_OK.
|
||||
- Utrzymuj alerty krótkie.
|
||||
- Jeśli po wszystkich należnych zadaniach nic nie wymaga uwagi, odpowiedz HEARTBEAT_OK.
|
||||
```
|
||||
|
||||
Zachowanie:
|
||||
|
||||
- OpenClaw parsuje blok `tasks:` i sprawdza każde zadanie względem własnego `interval`.
|
||||
- Do promptu heartbeat dla danego tyknięcia są dołączane tylko zadania, które **mają termin wykonania**.
|
||||
- Jeśli żadne zadania nie mają terminu wykonania, heartbeat jest całkowicie pomijany (`reason=no-tasks-due`), aby uniknąć zmarnowanego wywołania modelu.
|
||||
- Treść spoza zadań w `HEARTBEAT.md` jest zachowywana i dołączana jako dodatkowy kontekst po liście zadań wymagających wykonania.
|
||||
- OpenClaw analizuje blok `tasks:` i sprawdza każde zadanie względem jego własnego `interval`.
|
||||
- Tylko **należne** zadania są dołączane do promptu heartbeat dla danego tyknięcia.
|
||||
- Jeśli żadne zadania nie są należne, heartbeat jest całkowicie pomijany (`reason=no-tasks-due`), aby uniknąć zmarnowanego wywołania modelu.
|
||||
- Treść spoza zadań w `HEARTBEAT.md` jest zachowywana i dołączana jako dodatkowy kontekst po liście należnych zadań.
|
||||
- Znaczniki czasu ostatniego uruchomienia zadań są przechowywane w stanie sesji (`heartbeatTaskState`), więc interwały przetrwają zwykłe restarty.
|
||||
- Znaczniki czasu zadań są przesuwane dopiero po tym, jak uruchomienie heartbeat przejdzie normalną ścieżkę odpowiedzi. Pominięte uruchomienia `empty-heartbeat-file` / `no-tasks-due` nie oznaczają zadań jako ukończonych.
|
||||
- Znaczniki czasu zadań są przesuwane dopiero po tym, jak uruchomienie heartbeat zakończy normalną ścieżkę odpowiedzi. Pominięte uruchomienia `empty-heartbeat-file` / `no-tasks-due` nie oznaczają zadań jako ukończonych.
|
||||
|
||||
Tryb zadań jest przydatny, gdy chcesz, aby jeden plik heartbeat zawierał kilka okresowych kontroli bez płacenia za wszystkie przy każdym tyknięciu.
|
||||
Tryb zadań jest przydatny, jeśli chcesz, aby jeden plik heartbeat zawierał kilka okresowych sprawdzeń bez płacenia za wszystkie przy każdym tyknięciu.
|
||||
|
||||
### Czy agent może aktualizować HEARTBEAT.md?
|
||||
|
||||
Tak — jeśli go o to poprosisz.
|
||||
Tak — jeśli mu to zlecisz.
|
||||
|
||||
`HEARTBEAT.md` to po prostu zwykły plik w workspace agenta, więc możesz powiedzieć
|
||||
agentowi (na zwykłym czacie) coś takiego:
|
||||
`HEARTBEAT.md` to po prostu zwykły plik w obszarze roboczym agenta, więc możesz powiedzieć
|
||||
agentowi (w zwykłym czacie) coś w rodzaju:
|
||||
|
||||
- „Zaktualizuj `HEARTBEAT.md`, aby dodać codzienną kontrolę kalendarza.”
|
||||
- „Przepisz `HEARTBEAT.md`, aby był krótszy i skupiał się na zadaniach związanych ze skrzynką odbiorczą.”
|
||||
- „Zaktualizuj `HEARTBEAT.md`, aby dodać codzienne sprawdzenie kalendarza.”
|
||||
- „Przeredaguj `HEARTBEAT.md`, aby był krótszy i skupiał się na działaniach następczych ze skrzynki odbiorczej.”
|
||||
|
||||
Jeśli chcesz, aby działo się to proaktywnie, możesz także dołączyć jawną linię w
|
||||
prompt heartbeat, na przykład: „If the checklist becomes stale, update HEARTBEAT.md
|
||||
with a better one.”
|
||||
Jeśli chcesz, aby działo się to proaktywnie, możesz także dodać jawną linię do
|
||||
promptu heartbeat, na przykład: „Jeśli lista kontrolna się zestarzeje, zaktualizuj HEARTBEAT.md
|
||||
na lepszą.”
|
||||
|
||||
Uwaga dotycząca bezpieczeństwa: nie umieszczaj sekretów (kluczy API, numerów telefonów, prywatnych tokenów) w
|
||||
`HEARTBEAT.md` — staje się częścią kontekstu promptu.
|
||||
|
||||
## Ręczne wybudzenie (na żądanie)
|
||||
|
||||
Możesz dodać zdarzenie systemowe do kolejki i natychmiast uruchomić heartbeat poleceniem:
|
||||
Możesz umieścić zdarzenie systemowe w kolejce i natychmiast wyzwolić heartbeat poleceniem:
|
||||
|
||||
```bash
|
||||
openclaw system event --text "Check for urgent follow-ups" --mode now
|
||||
```
|
||||
|
||||
Jeśli wiele agentów ma skonfigurowany `heartbeat`, ręczne wybudzenie natychmiast uruchamia heartbeat każdego z tych
|
||||
agentów.
|
||||
Jeśli wielu agentów ma skonfigurowany `heartbeat`, ręczne wybudzenie natychmiast uruchamia heartbeat każdego z nich.
|
||||
|
||||
Użyj `--mode next-heartbeat`, aby poczekać na następne zaplanowane tyknięcie.
|
||||
Użyj `--mode next-heartbeat`, aby zaczekać do następnego zaplanowanego tyknięcia.
|
||||
|
||||
## Dostarczanie rozumowania (opcjonalne)
|
||||
## Dostarczanie rozumowania (opcjonalnie)
|
||||
|
||||
Domyślnie heartbeat dostarcza tylko końcowy ładunek „odpowiedzi”.
|
||||
Domyślnie heartbeat dostarcza tylko końcowy ładunek „answer”.
|
||||
|
||||
Jeśli chcesz większej przejrzystości, włącz:
|
||||
|
||||
- `agents.defaults.heartbeat.includeReasoning: true`
|
||||
|
||||
Po włączeniu heartbeat będą również dostarczać osobny komunikat poprzedzony
|
||||
`Reasoning:` (ten sam kształt co `/reasoning on`). Może to być przydatne, gdy agent
|
||||
zarządza wieloma sesjami/codexami i chcesz zobaczyć, dlaczego zdecydował się Cię
|
||||
powiadomić — ale może to także ujawnić więcej szczegółów wewnętrznych, niż chcesz. W czatach grupowych lepiej pozostawić tę opcję
|
||||
wyłączoną.
|
||||
Po włączeniu heartbeat będzie również dostarczał osobną wiadomość z prefiksem
|
||||
`Reasoning:` (ten sam format co `/reasoning on`). Może to być przydatne, gdy agent
|
||||
zarządza wieloma sesjami/codexami i chcesz zobaczyć, dlaczego zdecydował się do Ciebie odezwać
|
||||
— ale może też ujawniać więcej szczegółów wewnętrznych, niż chcesz. Lepiej pozostawić to
|
||||
wyłączone w czatach grupowych.
|
||||
|
||||
## Świadomość kosztów
|
||||
|
||||
Heartbeat uruchamia pełne tury agenta. Krótsze interwały zużywają więcej tokenów. Aby obniżyć koszt:
|
||||
|
||||
- Użyj `isolatedSession: true`, aby uniknąć wysyłania pełnej historii rozmowy (~100K tokenów spada do ~2-5K na uruchomienie).
|
||||
- Użyj `isolatedSession: true`, aby uniknąć wysyłania pełnej historii rozmowy (~100K tokenów do ~2-5K na uruchomienie).
|
||||
- Użyj `lightContext: true`, aby ograniczyć pliki bootstrap tylko do `HEARTBEAT.md`.
|
||||
- Ustaw tańszy `model` (np. `ollama/llama3.2:1b`).
|
||||
- Utrzymuj `HEARTBEAT.md` w małym rozmiarze.
|
||||
@ -444,7 +451,7 @@ Heartbeat uruchamia pełne tury agenta. Krótsze interwały zużywają więcej t
|
||||
|
||||
## Powiązane
|
||||
|
||||
- [Automation & Tasks](/pl/automation) — wszystkie mechanizmy automatyzacji w skrócie
|
||||
- [Background Tasks](/pl/automation/tasks) — jak śledzona jest praca odłączona
|
||||
- [Timezone](/concepts/timezone) — jak strefa czasowa wpływa na harmonogram heartbeat
|
||||
- [Troubleshooting](/pl/automation/cron-jobs#troubleshooting) — debugowanie problemów z automatyzacją
|
||||
- [Automatyzacja i zadania](/pl/automation) — wszystkie mechanizmy automatyzacji w skrócie
|
||||
- [Zadania w tle](/pl/automation/tasks) — jak śledzona jest praca odłączona
|
||||
- [Strefa czasowa](/pl/concepts/timezone) — jak strefa czasowa wpływa na planowanie heartbeat
|
||||
- [Rozwiązywanie problemów](/pl/automation/cron-jobs#troubleshooting) — debugowanie problemów z automatyzacją
|
||||
|
||||
@ -1,28 +1,28 @@
|
||||
---
|
||||
read_when:
|
||||
- Chcesz udostępniać modele z własnej maszyny GPU
|
||||
- Podłączasz LM Studio lub proxy zgodne z OpenAI
|
||||
- Konfigurujesz LM Studio lub proxy zgodne z OpenAI
|
||||
- Potrzebujesz najbezpieczniejszych wskazówek dotyczących modeli lokalnych
|
||||
summary: Uruchamiaj OpenClaw na lokalnych LLM-ach (LM Studio, vLLM, LiteLLM, niestandardowe endpointy OpenAI)
|
||||
summary: Uruchamianie OpenClaw na lokalnych modelach LLM (LM Studio, vLLM, LiteLLM, niestandardowe endpointy OpenAI)
|
||||
title: Modele lokalne
|
||||
x-i18n:
|
||||
generated_at: "2026-04-05T13:53:24Z"
|
||||
generated_at: "2026-04-08T02:14:31Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 3b99c8fb57f65c0b765fc75bd36933221b5aeb94c4a3f3428f92640ae064f8b6
|
||||
source_hash: d619d72b0e06914ebacb7e9f38b746caf1b9ce8908c9c6638c3acdddbaa025e8
|
||||
source_path: gateway/local-models.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Modele lokalne
|
||||
|
||||
Tryb lokalny jest możliwy, ale OpenClaw oczekuje dużego kontekstu i silnej ochrony przed prompt injection. Małe karty obcinają kontekst i osłabiają bezpieczeństwo. Celuj wysoko: **≥2 maksymalnie wyposażone Mac Studio lub równoważny zestaw GPU (~30 tys. USD+)**. Pojedynczy GPU **24 GB** działa tylko przy lżejszych promptach i większych opóźnieniach. Używaj **największego / pełnowymiarowego wariantu modelu, jaki możesz uruchomić**; agresywnie kwantyzowane lub „małe” checkpointy zwiększają ryzyko prompt injection (zobacz [Security](/gateway/security)).
|
||||
Uruchamianie lokalne jest możliwe, ale OpenClaw oczekuje dużego kontekstu oraz silnych zabezpieczeń przed prompt injection. Małe karty skracają kontekst i osłabiają bezpieczeństwo. Celuj wysoko: **≥2 w pełni wyposażone Mac Studio lub równoważny zestaw GPU (~30 tys. USD+)**. Pojedynczy procesor GPU **24 GB** sprawdzi się tylko przy lżejszych promptach i większych opóźnieniach. Używaj **największego / pełnowymiarowego wariantu modelu, jaki możesz uruchomić**; agresywnie kwantyzowane lub „małe” checkpointy zwiększają ryzyko prompt injection (zobacz [Bezpieczeństwo](/pl/gateway/security)).
|
||||
|
||||
Jeśli chcesz lokalnej konfiguracji z najmniejszym tarciem, zacznij od [Ollama](/providers/ollama) i `openclaw onboard`. Ta strona to praktyczny przewodnik dla bardziej zaawansowanych lokalnych stosów i niestandardowych lokalnych serwerów zgodnych z OpenAI.
|
||||
Jeśli chcesz skonfigurować lokalne środowisko z jak najmniejszym tarciem, zacznij od [Ollama](/pl/providers/ollama) i `openclaw onboard`. Ta strona to opiniotwórczy przewodnik po bardziej zaawansowanych lokalnych stosach oraz niestandardowych lokalnych serwerach zgodnych z OpenAI.
|
||||
|
||||
## Zalecane: LM Studio + duży model lokalny (Responses API)
|
||||
|
||||
Obecnie najlepszy lokalny stos. Załaduj duży model w LM Studio (na przykład pełnowymiarową wersję Qwen, DeepSeek lub Llama), włącz lokalny serwer (domyślnie `http://127.0.0.1:1234`) i użyj Responses API, aby oddzielić rozumowanie od końcowego tekstu.
|
||||
Obecnie najlepszy lokalny stos. Załaduj duży model do LM Studio (na przykład pełnowymiarową kompilację Qwen, DeepSeek lub Llama), włącz lokalny serwer (domyślnie `http://127.0.0.1:1234`) i użyj Responses API, aby oddzielić rozumowanie od tekstu końcowego.
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -62,15 +62,15 @@ Obecnie najlepszy lokalny stos. Załaduj duży model w LM Studio (na przykład p
|
||||
**Lista kontrolna konfiguracji**
|
||||
|
||||
- Zainstaluj LM Studio: [https://lmstudio.ai](https://lmstudio.ai)
|
||||
- W LM Studio pobierz **największą dostępną wersję modelu** (unikaj wariantów „small” / mocno kwantyzowanych), uruchom serwer i potwierdź, że `http://127.0.0.1:1234/v1/models` go wyświetla.
|
||||
- W LM Studio pobierz **największą dostępną kompilację modelu** (unikaj wariantów „small” / mocno kwantyzowanych), uruchom serwer i potwierdź, że `http://127.0.0.1:1234/v1/models` go wyświetla.
|
||||
- Zastąp `my-local-model` rzeczywistym identyfikatorem modelu widocznym w LM Studio.
|
||||
- Utrzymuj model załadowany; zimne ładowanie zwiększa opóźnienie uruchamiania.
|
||||
- Dostosuj `contextWindow` / `maxTokens`, jeśli Twoja wersja LM Studio się różni.
|
||||
- W przypadku WhatsApp trzymaj się Responses API, aby wysyłany był tylko końcowy tekst.
|
||||
- Utrzymuj model załadowany; zimne ładowanie zwiększa opóźnienie startu.
|
||||
- Dostosuj `contextWindow`/`maxTokens`, jeśli Twoja kompilacja LM Studio się różni.
|
||||
- W przypadku WhatsApp trzymaj się Responses API, aby wysyłany był tylko tekst końcowy.
|
||||
|
||||
Nawet przy pracy lokalnej pozostaw skonfigurowane modele hostowane; użyj `models.mode: "merge"`, aby fallbacki nadal były dostępne.
|
||||
Nawet przy uruchamianiu lokalnym pozostaw skonfigurowane modele hostowane; użyj `models.mode: "merge"`, aby fallbacki pozostały dostępne.
|
||||
|
||||
### Konfiguracja hybrydowa: hostowany model główny, lokalny fallback
|
||||
### Konfiguracja hybrydowa: hostowany model podstawowy, lokalny fallback
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -113,16 +113,16 @@ Nawet przy pracy lokalnej pozostaw skonfigurowane modele hostowane; użyj `model
|
||||
|
||||
### Najpierw lokalnie, z hostowaną siatką bezpieczeństwa
|
||||
|
||||
Zamień kolejność modelu głównego i fallbacków; zachowaj ten sam blok dostawców i `models.mode: "merge"`, aby móc wrócić do Sonnet lub Opus, gdy lokalna maszyna będzie niedostępna.
|
||||
Zamień kolejność modelu podstawowego i fallbacku; zachowaj ten sam blok providerów oraz `models.mode: "merge"`, aby móc przełączyć się awaryjnie na Sonnet lub Opus, gdy lokalna maszyna będzie niedostępna.
|
||||
|
||||
### Hosting regionalny / routing danych
|
||||
|
||||
- Hostowane warianty MiniMax/Kimi/GLM istnieją także w OpenRouter z endpointami przypiętymi do regionu (np. hostowane w USA). Wybierz tam wariant regionalny, aby utrzymać ruch w wybranej jurysdykcji, nadal używając `models.mode: "merge"` dla fallbacków Anthropic/OpenAI.
|
||||
- Tryb wyłącznie lokalny pozostaje najsilniejszą ścieżką prywatności; hostowany routing regionalny to rozwiązanie pośrednie, gdy potrzebujesz funkcji dostawcy, ale chcesz kontrolować przepływ danych.
|
||||
- Hostowane warianty MiniMax/Kimi/GLM są również dostępne w OpenRouter z endpointami przypiętymi do regionu (np. hostowanymi w USA). Wybierz tam wariant regionalny, aby utrzymać ruch w wybranej jurysdykcji, nadal używając `models.mode: "merge"` dla fallbacków Anthropic/OpenAI.
|
||||
- Tryb wyłącznie lokalny pozostaje najmocniejszą ścieżką pod względem prywatności; hostowany routing regionalny to rozwiązanie pośrednie, gdy potrzebujesz funkcji dostawcy, ale chcesz zachować kontrolę nad przepływem danych.
|
||||
|
||||
## Inne lokalne proxy zgodne z OpenAI
|
||||
|
||||
vLLM, LiteLLM, OAI-proxy lub niestandardowe gatewaye działają, jeśli udostępniają endpoint `/v1` w stylu OpenAI. Zastąp powyższy blok dostawcy swoim endpointem i identyfikatorem modelu:
|
||||
vLLM, LiteLLM, OAI-proxy lub niestandardowe bramy działają, jeśli udostępniają endpoint `/v1` w stylu OpenAI. Zastąp powyższy blok providera swoim endpointem i identyfikatorem modelu:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -152,19 +152,39 @@ vLLM, LiteLLM, OAI-proxy lub niestandardowe gatewaye działają, jeśli udostęp
|
||||
|
||||
Zachowaj `models.mode: "merge"`, aby hostowane modele nadal były dostępne jako fallbacki.
|
||||
|
||||
Uwaga dotycząca działania dla lokalnych / proxowanych backendów `/v1`:
|
||||
Uwagi dotyczące działania dla lokalnych / proxowanych backendów `/v1`:
|
||||
|
||||
- OpenClaw traktuje je jako trasy proxy zgodne z OpenAI, a nie natywne
|
||||
endpointy OpenAI
|
||||
- nie stosuje się tutaj kształtowania żądań przeznaczonego wyłącznie dla natywnego OpenAI: brak
|
||||
`service_tier`, brak Responses `store`, brak kształtowania ładunku zgodności z reasoning OpenAI
|
||||
i brak wskazówek prompt-cache
|
||||
- OpenClaw traktuje je jako trasy proxy zgodne z OpenAI, a nie natywne endpointy OpenAI
|
||||
- natywne kształtowanie żądań tylko dla OpenAI nie ma tu zastosowania: brak
|
||||
`service_tier`, brak Responses `store`, brak kształtowania payloadu zgodności z rozumowaniem OpenAI
|
||||
oraz brak wskazówek dotyczących cache promptów
|
||||
- ukryte nagłówki atrybucji OpenClaw (`originator`, `version`, `User-Agent`)
|
||||
nie są wstrzykiwane do tych niestandardowych URL-i proxy
|
||||
nie są wstrzykiwane dla tych niestandardowych adresów URL proxy
|
||||
|
||||
Uwagi o zgodności dla bardziej rygorystycznych backendów zgodnych z OpenAI:
|
||||
|
||||
- Niektóre serwery akceptują w Chat Completions tylko string `messages[].content`, a nie
|
||||
ustrukturyzowane tablice części treści. Ustaw
|
||||
`models.providers.<provider>.models[].compat.requiresStringContent: true` dla
|
||||
takich endpointów.
|
||||
- Niektóre mniejsze lub bardziej rygorystyczne lokalne backendy są niestabilne przy pełnym
|
||||
kształcie promptu środowiska uruchomieniowego agenta OpenClaw, szczególnie gdy dołączone są schematy narzędzi. Jeśli
|
||||
backend działa dla małych bezpośrednich wywołań `/v1/chat/completions`, ale nie działa przy zwykłych
|
||||
turach agenta OpenClaw, najpierw spróbuj
|
||||
`models.providers.<provider>.models[].compat.supportsTools: false`.
|
||||
- Jeśli backend nadal zawodzi tylko przy większych uruchomieniach OpenClaw, pozostały problem
|
||||
zwykle leży po stronie przepustowości modelu/serwera upstream albo błędu backendu, a nie warstwy
|
||||
transportowej OpenClaw.
|
||||
|
||||
## Rozwiązywanie problemów
|
||||
|
||||
- Gateway może połączyć się z proxy? `curl http://127.0.0.1:1234/v1/models`.
|
||||
- Model LM Studio został wyładowany? Załaduj go ponownie; zimny start to częsta przyczyna „zawieszenia”.
|
||||
- Błędy kontekstu? Zmniejsz `contextWindow` lub zwiększ limit serwera.
|
||||
- Bezpieczeństwo: modele lokalne pomijają filtry po stronie dostawcy; utrzymuj agentów w wąskim zakresie i włącz kompaktowanie, aby ograniczyć skutki prompt injection.
|
||||
- Brama może połączyć się z proxy? `curl http://127.0.0.1:1234/v1/models`.
|
||||
- Model LM Studio został wyładowany? Załaduj go ponownie; zimny start jest częstą przyczyną „zawieszania się”.
|
||||
- Błędy kontekstu? Obniż `contextWindow` lub zwiększ limit serwera.
|
||||
- Serwer zgodny z OpenAI zwraca `messages[].content ... expected a string`?
|
||||
Dodaj `compat.requiresStringContent: true` do wpisu tego modelu.
|
||||
- Bezpośrednie małe wywołania `/v1/chat/completions` działają, ale `openclaw infer model run`
|
||||
nie działa na Gemma lub innym modelu lokalnym? Najpierw wyłącz schematy narzędzi za pomocą
|
||||
`compat.supportsTools: false`, a następnie przetestuj ponownie. Jeśli serwer nadal ulega awarii tylko
|
||||
przy większych promptach OpenClaw, traktuj to jako ograniczenie modelu/serwera upstream.
|
||||
- Bezpieczeństwo: modele lokalne pomijają filtry po stronie dostawcy; utrzymuj agentów w wąskim zakresie i włącz kompaktowanie, aby ograniczyć zasięg prompt injection.
|
||||
|
||||
@ -1,32 +1,32 @@
|
||||
---
|
||||
read_when:
|
||||
- Implementowanie lub aktualizowanie klientów WS gateway
|
||||
- Debugowanie niezgodności protokołu lub błędów połączenia
|
||||
- Debugowanie niedopasowań protokołu lub niepowodzeń połączenia
|
||||
- Ponowne generowanie schematu/modeli protokołu
|
||||
summary: 'Protokół WebSocket Gateway: handshake, ramki, wersjonowanie'
|
||||
summary: 'Protokół Gateway WebSocket: uzgadnianie połączenia, ramki, wersjonowanie'
|
||||
title: Protokół Gateway
|
||||
x-i18n:
|
||||
generated_at: "2026-04-05T13:55:25Z"
|
||||
generated_at: "2026-04-08T02:15:42Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: c37f5b686562dda3ba3516ac6982ad87b2f01d8148233284e9917099c6e96d87
|
||||
source_hash: 8635e3ac1dd311dbd3a770b088868aa1495a8d53b3ebc1eae0dfda3b2bf4694a
|
||||
source_path: gateway/protocol.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Protokół Gateway (WebSocket)
|
||||
|
||||
Protokół Gateway WS to **pojedyncza płaszczyzna sterowania + transport węzłów** dla
|
||||
OpenClaw. Wszyscy klienci (CLI, web UI, aplikacja macOS, węzły iOS/Android, bezgłowe
|
||||
węzły) łączą się przez WebSocket i deklarują swoją **rolę** + **zakres** w momencie
|
||||
handshake.
|
||||
Protokół Gateway WS jest **pojedynczą płaszczyzną sterowania + transportem węzłów** dla
|
||||
OpenClaw. Wszyscy klienci (CLI, interfejs webowy, aplikacja macOS, węzły iOS/Android, bezgłowe
|
||||
węzły) łączą się przez WebSocket i deklarują swoją **rolę** + **zakres** w czasie
|
||||
uzgadniania połączenia.
|
||||
|
||||
## Transport
|
||||
|
||||
- WebSocket, ramki tekstowe z ładunkami JSON.
|
||||
- Pierwsza ramka **musi** być żądaniem `connect`.
|
||||
|
||||
## Handshake (`connect`)
|
||||
## Uzgadnianie połączenia (connect)
|
||||
|
||||
Gateway → klient (wyzwanie przed połączeniem):
|
||||
|
||||
@ -84,7 +84,7 @@ Gateway → klient:
|
||||
}
|
||||
```
|
||||
|
||||
Gdy wydawany jest token urządzenia, `hello-ok` zawiera także:
|
||||
Gdy zostanie wydany token urządzenia, `hello-ok` zawiera także:
|
||||
|
||||
```json
|
||||
{
|
||||
@ -96,7 +96,7 @@ Gdy wydawany jest token urządzenia, `hello-ok` zawiera także:
|
||||
}
|
||||
```
|
||||
|
||||
Podczas wbudowanego zaufanego przekazania bootstrap `hello-ok.auth` może również zawierać dodatkowe
|
||||
Podczas przekazania w zaufanym przepływie bootstrap, `hello-ok.auth` może także zawierać dodatkowe
|
||||
ograniczone wpisy ról w `deviceTokens`:
|
||||
|
||||
```json
|
||||
@ -116,12 +116,12 @@ ograniczone wpisy ról w `deviceTokens`:
|
||||
}
|
||||
```
|
||||
|
||||
Dla wbudowanego przepływu bootstrap node/operator podstawowy token węzła pozostaje z
|
||||
`scopes: []`, a każdy przekazany token operatora pozostaje ograniczony do bootstrapowej
|
||||
listy dozwolonych operatora (`operator.approvals`, `operator.read`,
|
||||
`operator.talk.secrets`, `operator.write`). Kontrole zakresu bootstrap pozostają
|
||||
W przypadku wbudowanego przepływu bootstrap węzła/operatora podstawowy token węzła pozostaje
|
||||
`scopes: []`, a każdy przekazany token operatora pozostaje ograniczony do listy dozwolonych zakresów
|
||||
operatora bootstrap (`operator.approvals`, `operator.read`,
|
||||
`operator.talk.secrets`, `operator.write`). Sprawdzenia zakresu bootstrap pozostają
|
||||
prefiksowane rolą: wpisy operatora spełniają tylko żądania operatora, a role inne niż operator
|
||||
nadal wymagają zakresów z własnym prefiksem roli.
|
||||
nadal wymagają zakresów pod własnym prefiksem roli.
|
||||
|
||||
### Przykład węzła
|
||||
|
||||
@ -158,13 +158,13 @@ nadal wymagają zakresów z własnym prefiksem roli.
|
||||
}
|
||||
```
|
||||
|
||||
## Ramki
|
||||
## Ramkowanie
|
||||
|
||||
- **Żądanie**: `{type:"req", id, method, params}`
|
||||
- **Odpowiedź**: `{type:"res", id, ok, payload|error}`
|
||||
- **Zdarzenie**: `{type:"event", event, payload, seq?, stateVersion?}`
|
||||
|
||||
Metody powodujące skutki uboczne wymagają **kluczy idempotencyjnych** (zobacz schemat).
|
||||
Metody powodujące skutki uboczne wymagają **kluczy idempotencji** (zobacz schemat).
|
||||
|
||||
## Role + zakresy
|
||||
|
||||
@ -173,7 +173,7 @@ Metody powodujące skutki uboczne wymagają **kluczy idempotencyjnych** (zobacz
|
||||
- `operator` = klient płaszczyzny sterowania (CLI/UI/automatyzacja).
|
||||
- `node` = host możliwości (`camera/screen/canvas/system.run`).
|
||||
|
||||
### Zakresy (`operator`)
|
||||
### Zakresy (operator)
|
||||
|
||||
Typowe zakresy:
|
||||
|
||||
@ -187,93 +187,93 @@ Typowe zakresy:
|
||||
`talk.config` z `includeSecrets: true` wymaga `operator.talk.secrets`
|
||||
(lub `operator.admin`).
|
||||
|
||||
Metody Gateway RPC zarejestrowane przez pluginy mogą żądać własnego zakresu operatora, ale
|
||||
Metody Gateway RPC rejestrowane przez pluginy mogą żądać własnego zakresu operatora, ale
|
||||
zastrzeżone prefiksy administracyjne rdzenia (`config.*`, `exec.approvals.*`, `wizard.*`,
|
||||
`update.*`) zawsze są rozwiązywane do `operator.admin`.
|
||||
`update.*`) zawsze są mapowane na `operator.admin`.
|
||||
|
||||
Zakres metody jest tylko pierwszą bramką. Niektóre polecenia slash osiągane przez
|
||||
`chat.send` stosują na dodatek bardziej rygorystyczne kontrole na poziomie polecenia. Na przykład trwałe
|
||||
Zakres metody to tylko pierwszy próg kontroli. Niektóre polecenia slash osiągane przez
|
||||
`chat.send` nakładają dodatkowo bardziej rygorystyczne kontrole na poziomie polecenia. Na przykład trwałe
|
||||
zapisy `/config set` i `/config unset` wymagają `operator.admin`.
|
||||
|
||||
`node.pair.approve` ma także dodatkową kontrolę zakresu w momencie zatwierdzania ponad
|
||||
podstawowy zakres metody:
|
||||
bazowy zakres metody:
|
||||
|
||||
- żądania bez polecenia: `operator.pairing`
|
||||
- żądania bez poleceń: `operator.pairing`
|
||||
- żądania z poleceniami węzła innymi niż exec: `operator.pairing` + `operator.write`
|
||||
- żądania zawierające `system.run`, `system.run.prepare` lub `system.which`:
|
||||
- żądania obejmujące `system.run`, `system.run.prepare` lub `system.which`:
|
||||
`operator.pairing` + `operator.admin`
|
||||
|
||||
### `caps`/`commands`/`permissions` (`node`)
|
||||
### Caps/commands/permissions (node)
|
||||
|
||||
Węzły deklarują roszczenia możliwości w momencie połączenia:
|
||||
Węzły deklarują roszczenia możliwości w czasie połączenia:
|
||||
|
||||
- `caps`: kategorie możliwości wysokiego poziomu.
|
||||
- `caps`: wysokopoziomowe kategorie możliwości.
|
||||
- `commands`: lista dozwolonych poleceń dla invoke.
|
||||
- `permissions`: szczegółowe przełączniki (np. `screen.record`, `camera.capture`).
|
||||
|
||||
Gateway traktuje je jako **roszczenia** i wymusza listy dozwolonych po stronie serwera.
|
||||
Gateway traktuje je jako **roszczenia** i egzekwuje listy dozwolonych po stronie serwera.
|
||||
|
||||
## Presence
|
||||
## Obecność
|
||||
|
||||
- `system-presence` zwraca wpisy kluczowane tożsamością urządzenia.
|
||||
- Wpisy presence zawierają `deviceId`, `roles` i `scopes`, dzięki czemu UI może pokazywać jeden wiersz na urządzenie
|
||||
nawet wtedy, gdy łączy się ono zarówno jako **operator**, jak i **node**.
|
||||
- Wpisy obecności zawierają `deviceId`, `roles` i `scopes`, aby interfejsy mogły pokazywać jeden wiersz na urządzenie,
|
||||
nawet gdy łączy się ono zarówno jako **operator**, jak i **node**.
|
||||
|
||||
## Typowe rodziny metod RPC
|
||||
|
||||
Ta strona nie jest wygenerowanym pełnym zrzutem, ale publiczna powierzchnia WS jest
|
||||
szersza niż powyższe przykłady handshake/auth. To główne rodziny metod, które
|
||||
Ta strona nie jest wygenerowanym pełnym zrzutem, ale publiczna powierzchnia WS jest szersza
|
||||
niż przykłady uzgadniania połączenia/uwierzytelniania powyżej. To są główne rodziny metod, które
|
||||
Gateway udostępnia obecnie.
|
||||
|
||||
`hello-ok.features.methods` to zachowawcza lista wykrywania zbudowana z
|
||||
`src/gateway/server-methods-list.ts` oraz załadowanych eksportów metod pluginów/kanałów.
|
||||
Traktuj ją jako wykrywanie funkcji, a nie jako wygenerowany zrzut każdej wywoływalnej funkcji pomocniczej
|
||||
zaimplementowanej w `src/gateway/server-methods/*.ts`.
|
||||
Traktuj ją jako wykrywanie funkcji, a nie wygenerowany zrzut każdego pomocniczego wywołania
|
||||
zaimplementowanego w `src/gateway/server-methods/*.ts`.
|
||||
|
||||
### System i tożsamość
|
||||
|
||||
- `health` zwraca buforowaną lub świeżo sprawdzoną migawkę stanu gateway.
|
||||
- `health` zwraca buforowany lub świeżo sprawdzony snapshot kondycji gateway.
|
||||
- `status` zwraca podsumowanie gateway w stylu `/status`; pola wrażliwe są
|
||||
uwzględniane tylko dla klientów operatora o zakresie admin.
|
||||
dołączane tylko dla klientów operatora z zakresem admin.
|
||||
- `gateway.identity.get` zwraca tożsamość urządzenia gateway używaną przez przepływy relay i
|
||||
parowania.
|
||||
- `system-presence` zwraca bieżącą migawkę presence dla połączonych
|
||||
urządzeń operator/node.
|
||||
- `system-event` dopisuje zdarzenie systemowe i może aktualizować/rozgłaszać
|
||||
kontekst presence.
|
||||
- `last-heartbeat` zwraca najnowsze utrwalone zdarzenie heartbeat.
|
||||
- `set-heartbeats` przełącza przetwarzanie heartbeat na gateway.
|
||||
- `system-presence` zwraca bieżący snapshot obecności dla połączonych
|
||||
urządzeń operatora/węzła.
|
||||
- `system-event` dopisuje zdarzenie systemowe i może aktualizować/rozgłaszać kontekst
|
||||
obecności.
|
||||
- `last-heartbeat` zwraca najnowsze zapisane zdarzenie heartbeat.
|
||||
- `set-heartbeats` przełącza przetwarzanie heartbeat w gateway.
|
||||
|
||||
### Models i użycie
|
||||
### Modele i użycie
|
||||
|
||||
- `models.list` zwraca katalog modeli dozwolonych w runtime.
|
||||
- `usage.status` zwraca okna użycia dostawców/podsumowania pozostałego limitu.
|
||||
- `usage.cost` zwraca zagregowane podsumowania użycia kosztów dla zakresu dat.
|
||||
- `doctor.memory.status` zwraca gotowość pamięci wektorowej / osadzeń dla
|
||||
aktywnego domyślnego workspace agenta.
|
||||
- `models.list` zwraca katalog modeli dozwolonych w czasie działania.
|
||||
- `usage.status` zwraca okna użycia dostawcy/podsumowania pozostałego limitu.
|
||||
- `usage.cost` zwraca zagregowane podsumowania kosztów użycia dla zakresu dat.
|
||||
- `doctor.memory.status` zwraca gotowość pamięci wektorowej / embeddingów dla
|
||||
aktywnego domyślnego obszaru roboczego agenta.
|
||||
- `sessions.usage` zwraca podsumowania użycia dla poszczególnych sesji.
|
||||
- `sessions.usage.timeseries` zwraca szereg czasowy użycia dla jednej sesji.
|
||||
- `sessions.usage.logs` zwraca wpisy logu użycia dla jednej sesji.
|
||||
- `sessions.usage.logs` zwraca wpisy dziennika użycia dla jednej sesji.
|
||||
|
||||
### Kanały i pomocniki logowania
|
||||
|
||||
- `channels.status` zwraca podsumowania stanu wbudowanych + dołączonych kanałów/pluginów.
|
||||
- `channels.logout` wylogowuje konkretne konto kanału, jeśli kanał
|
||||
- `channels.status` zwraca podsumowania statusu wbudowanych + dołączonych kanałów/pluginów.
|
||||
- `channels.logout` wylogowuje z określonego kanału/konta tam, gdzie kanał
|
||||
obsługuje wylogowanie.
|
||||
- `web.login.start` uruchamia przepływ logowania QR/web dla bieżącego
|
||||
dostawcy kanału web obsługującego QR.
|
||||
- `web.login.wait` czeka na zakończenie tego przepływu logowania QR/web i uruchamia
|
||||
kanał po powodzeniu.
|
||||
- `push.test` wysyła testowy push APNs do zarejestrowanego węzła iOS.
|
||||
- `voicewake.get` zwraca zapisane wyzwalacze wake word.
|
||||
- `voicewake.set` aktualizuje wyzwalacze wake word i rozgłasza zmianę.
|
||||
- `web.login.wait` czeka na zakończenie tego przepływu logowania QR/web i przy powodzeniu uruchamia
|
||||
kanał.
|
||||
- `push.test` wysyła testowe powiadomienie APNs do zarejestrowanego węzła iOS.
|
||||
- `voicewake.get` zwraca zapisane wyzwalacze słowa aktywującego.
|
||||
- `voicewake.set` aktualizuje wyzwalacze słowa aktywującego i rozgłasza zmianę.
|
||||
|
||||
### Wiadomości i logi
|
||||
|
||||
- `send` to bezpośrednie RPC dostarczania wychodzącego dla wysyłek kierowanych do
|
||||
kanału/konta/wątku poza runnerem czatu.
|
||||
- `logs.tail` zwraca ogon skonfigurowanego logu plikowego gateway z kontrolą kursora/limitu i
|
||||
maksymalnej liczby bajtów.
|
||||
- `send` jest bezpośrednim wywołaniem RPC dostarczania wychodzącego dla
|
||||
wysyłek kierowanych do kanału/konta/wątku poza runnerem czatu.
|
||||
- `logs.tail` zwraca ogon skonfigurowanego dziennika plikowego gateway z kursorem/limitem oraz
|
||||
kontrolami maksymalnej liczby bajtów.
|
||||
|
||||
### Talk i TTS
|
||||
|
||||
@ -281,58 +281,58 @@ zaimplementowanej w `src/gateway/server-methods/*.ts`.
|
||||
wymaga `operator.talk.secrets` (lub `operator.admin`).
|
||||
- `talk.mode` ustawia/rozgłasza bieżący stan trybu Talk dla klientów
|
||||
WebChat/Control UI.
|
||||
- `talk.speak` syntezuje mowę przez aktywnego dostawcę mowy Talk.
|
||||
- `talk.speak` syntetyzuje mowę przez aktywnego dostawcę mowy Talk.
|
||||
- `tts.status` zwraca stan włączenia TTS, aktywnego dostawcę, dostawców zapasowych
|
||||
oraz stan konfiguracji dostawcy.
|
||||
- `tts.providers` zwraca widoczny inwentarz dostawców TTS.
|
||||
- `tts.providers` zwraca widoczny spis dostawców TTS.
|
||||
- `tts.enable` i `tts.disable` przełączają stan preferencji TTS.
|
||||
- `tts.setProvider` aktualizuje preferowanego dostawcę TTS.
|
||||
- `tts.convert` uruchamia jednorazową konwersję text-to-speech.
|
||||
- `tts.convert` uruchamia jednorazową konwersję tekstu na mowę.
|
||||
|
||||
### Secrets, config, update i wizard
|
||||
### Sekrety, konfiguracja, aktualizacja i kreator
|
||||
|
||||
- `secrets.reload` ponownie rozwiązuje aktywne SecretRef i podmienia stan sekretów runtime
|
||||
- `secrets.reload` ponownie rozwiązuje aktywne SecretRef i podmienia stan sekretów w czasie działania
|
||||
tylko przy pełnym powodzeniu.
|
||||
- `secrets.resolve` rozwiązuje przypisania sekretów docelowych dla poleceń dla konkretnego
|
||||
- `secrets.resolve` rozwiązuje przypisania sekretów docelowych poleceń dla określonego
|
||||
zestawu poleceń/celów.
|
||||
- `config.get` zwraca bieżącą migawkę konfiguracji i hash.
|
||||
- `config.get` zwraca bieżący snapshot konfiguracji i hash.
|
||||
- `config.set` zapisuje zwalidowany ładunek konfiguracji.
|
||||
- `config.patch` scala częściową aktualizację konfiguracji.
|
||||
- `config.apply` waliduje + zastępuje pełny ładunek konfiguracji.
|
||||
- `config.schema` zwraca aktywny ładunek schematu konfiguracji używany przez Control UI i
|
||||
narzędzia CLI: schemat, `uiHints`, wersję i metadane generowania, w tym
|
||||
metadane schematów pluginów + kanałów, gdy runtime może je załadować. Schemat
|
||||
zawiera metadane pól `title` / `description` wyprowadzone z tych samych etykiet
|
||||
i tekstu pomocy używanych przez UI, w tym dla zagnieżdżonych obiektów, wildcard,
|
||||
elementów tablic i gałęzi kompozycji `anyOf` / `oneOf` / `allOf`, gdy istnieje
|
||||
pasująca dokumentacja pól.
|
||||
- `config.schema.lookup` zwraca ładunek wyszukiwania o zakresie ścieżki dla jednej ścieżki konfiguracji:
|
||||
znormalizowaną ścieżkę, płytki węzeł schematu, dopasowaną podpowiedź + `hintPath` oraz
|
||||
podsumowania bezpośrednich elementów potomnych dla UI/CLI drill-down.
|
||||
- Węzły schematu lookup zachowują dokumentację widoczną dla użytkownika i typowe pola walidacji:
|
||||
- `config.apply` waliduje i zastępuje pełny ładunek konfiguracji.
|
||||
- `config.schema` zwraca ładunek aktywnego schematu konfiguracji używany przez Control UI i
|
||||
narzędzia CLI: schemat, `uiHints`, wersję oraz metadane generowania, w tym
|
||||
metadane schematu pluginów + kanałów, gdy środowisko wykonawcze może je załadować. Schemat
|
||||
zawiera metadane pól `title` / `description` pochodzące z tych samych etykiet
|
||||
i tekstów pomocy używanych przez UI, w tym zagnieżdżone obiekty, wildcard, elementy tablic
|
||||
oraz gałęzie kompozycji `anyOf` / `oneOf` / `allOf`, gdy istnieje odpowiadająca
|
||||
dokumentacja pól.
|
||||
- `config.schema.lookup` zwraca ładunek wyszukiwania ograniczony do ścieżki dla jednej ścieżki konfiguracji:
|
||||
znormalizowaną ścieżkę, płytki węzeł schematu, dopasowaną wskazówkę + `hintPath` oraz
|
||||
podsumowania bezpośrednich elementów potomnych do drążenia w UI/CLI.
|
||||
- Węzły schematu wyszukiwania zachowują dokumentację skierowaną do użytkownika i typowe pola walidacji:
|
||||
`title`, `description`, `type`, `enum`, `const`, `format`, `pattern`,
|
||||
ograniczenia liczb/stringów/tablic/obiektów oraz flagi boolowskie, takie jak
|
||||
ograniczenia liczb/ciągów/tablic/obiektów oraz flagi logiczne takie jak
|
||||
`additionalProperties`, `deprecated`, `readOnly`, `writeOnly`.
|
||||
- Podsumowania dzieci ujawniają `key`, znormalizowaną `path`, `type`, `required`,
|
||||
`hasChildren`, a także dopasowane `hint` / `hintPath`.
|
||||
- Podsumowania elementów potomnych udostępniają `key`, znormalizowaną `path`, `type`, `required`,
|
||||
`hasChildren` oraz dopasowane `hint` / `hintPath`.
|
||||
- `update.run` uruchamia przepływ aktualizacji gateway i planuje restart tylko wtedy,
|
||||
gdy sama aktualizacja zakończyła się powodzeniem.
|
||||
gdy sama aktualizacja się powiodła.
|
||||
- `wizard.start`, `wizard.next`, `wizard.status` i `wizard.cancel` udostępniają
|
||||
kreator onboardingu przez WS RPC.
|
||||
kreator wdrożenia przez WS RPC.
|
||||
|
||||
### Istniejące główne rodziny
|
||||
|
||||
#### Pomocniki agentów i workspace
|
||||
#### Pomocniki agenta i obszaru roboczego
|
||||
|
||||
- `agents.list` zwraca skonfigurowane wpisy agentów.
|
||||
- `agents.create`, `agents.update` i `agents.delete` zarządzają rekordami agentów i
|
||||
połączeniem workspace.
|
||||
- `agents.create`, `agents.update` i `agents.delete` zarządzają rekordami agentów oraz
|
||||
powiązaniami obszaru roboczego.
|
||||
- `agents.files.list`, `agents.files.get` i `agents.files.set` zarządzają
|
||||
plikami bootstrapowego workspace udostępnianymi dla agenta.
|
||||
plikami obszaru roboczego bootstrap udostępnianymi dla agenta.
|
||||
- `agent.identity.get` zwraca efektywną tożsamość asystenta dla agenta lub
|
||||
sesji.
|
||||
- `agent.wait` czeka na zakończenie uruchomienia i zwraca końcową migawkę, gdy
|
||||
jest dostępna.
|
||||
- `agent.wait` czeka na zakończenie uruchomienia i zwraca końcowy snapshot, gdy
|
||||
jest dostępny.
|
||||
|
||||
#### Sterowanie sesją
|
||||
|
||||
@ -341,252 +341,252 @@ zaimplementowanej w `src/gateway/server-methods/*.ts`.
|
||||
dla bieżącego klienta WS.
|
||||
- `sessions.messages.subscribe` i `sessions.messages.unsubscribe` przełączają
|
||||
subskrypcje zdarzeń transkryptu/wiadomości dla jednej sesji.
|
||||
- `sessions.preview` zwraca ograniczone podglądy transkryptu dla określonych kluczy
|
||||
sesji.
|
||||
- `sessions.preview` zwraca ograniczone podglądy transkryptu dla określonych
|
||||
kluczy sesji.
|
||||
- `sessions.resolve` rozwiązuje lub kanonizuje cel sesji.
|
||||
- `sessions.create` tworzy nowy wpis sesji.
|
||||
- `sessions.send` wysyła wiadomość do istniejącej sesji.
|
||||
- `sessions.steer` to wariant przerwania i sterowania dla aktywnej sesji.
|
||||
- `sessions.steer` jest wariantem przerwania i sterowania dla aktywnej sesji.
|
||||
- `sessions.abort` przerywa aktywną pracę dla sesji.
|
||||
- `sessions.patch` aktualizuje metadane/nadpisania sesji.
|
||||
- `sessions.reset`, `sessions.delete` i `sessions.compact` wykonują konserwację
|
||||
sesji.
|
||||
- `sessions.reset`, `sessions.delete` i `sessions.compact` wykonują
|
||||
konserwację sesji.
|
||||
- `sessions.get` zwraca pełny zapisany wiersz sesji.
|
||||
- wykonywanie czatu nadal używa `chat.history`, `chat.send`, `chat.abort` i
|
||||
`chat.inject`.
|
||||
- `chat.history` jest znormalizowane do wyświetlania dla klientów UI: inline tagi dyrektyw są
|
||||
usuwane z widocznego tekstu, ładunki XML wywołań narzędzi w czystym tekście (w tym
|
||||
- `chat.history` jest znormalizowane pod kątem wyświetlania dla klientów UI: wbudowane tagi dyrektyw są
|
||||
usuwane z widocznego tekstu, ładunki XML wywołań narzędzi w zwykłym tekście (w tym
|
||||
`<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 wyciekające tokeny sterujące modelu ASCII/full-width
|
||||
są usuwane, czyste wiersze asystenta ze znacznikami silent-token, takie jak dokładne `NO_REPLY` /
|
||||
`no_reply`, są pomijane, a zbyt duże wiersze mogą być zastępowane placeholderami.
|
||||
obcięte bloki wywołań narzędzi) i wyciekłe tokeny sterowania modelem ASCII/full-width
|
||||
są usuwane, czyste wiersze asystenta z cichymi tokenami, takie jak dokładne `NO_REPLY` /
|
||||
`no_reply`, są pomijane, a zbyt duże wiersze mogą zostać zastąpione placeholderami.
|
||||
|
||||
#### Parowanie urządzeń i tokeny urządzeń
|
||||
|
||||
- `device.pair.list` zwraca oczekujące i zatwierdzone sparowane urządzenia.
|
||||
- `device.pair.approve`, `device.pair.reject` i `device.pair.remove` zarządzają
|
||||
rekordami parowania urządzeń.
|
||||
- `device.token.rotate` obraca token sparowanego urządzenia w granicach jego zatwierdzonej roli
|
||||
- `device.token.rotate` obraca token sparowanego urządzenia w granicach zatwierdzonej roli
|
||||
i zakresów.
|
||||
- `device.token.revoke` unieważnia token sparowanego urządzenia.
|
||||
|
||||
#### Parowanie węzłów, invoke i oczekująca praca
|
||||
|
||||
- `node.pair.request`, `node.pair.list`, `node.pair.approve`,
|
||||
`node.pair.reject` i `node.pair.verify` obejmują parowanie węzłów i weryfikację
|
||||
bootstrap.
|
||||
`node.pair.reject` i `node.pair.verify` obejmują parowanie węzłów i bootstrap
|
||||
verification.
|
||||
- `node.list` i `node.describe` zwracają stan znanych/połączonych węzłów.
|
||||
- `node.rename` aktualizuje etykietę sparowanego węzła.
|
||||
- `node.invoke` przekazuje polecenie do połączonego węzła.
|
||||
- `node.invoke.result` zwraca wynik żądania invoke.
|
||||
- `node.event` przenosi zdarzenia pochodzące z węzła z powrotem do gateway.
|
||||
- `node.canvas.capability.refresh` odświeża tokeny możliwości canvas o określonym zakresie.
|
||||
- `node.pending.pull` i `node.pending.ack` to API kolejki dla połączonych węzłów.
|
||||
- `node.canvas.capability.refresh` odświeża ograniczone tokeny możliwości canvas.
|
||||
- `node.pending.pull` i `node.pending.ack` to interfejsy API kolejki połączonych węzłów.
|
||||
- `node.pending.enqueue` i `node.pending.drain` zarządzają trwałą oczekującą pracą
|
||||
dla węzłów offline/rozłączonych.
|
||||
|
||||
#### Rodziny zatwierdzeń
|
||||
|
||||
- `exec.approval.request` i `exec.approval.resolve` obejmują jednorazowe
|
||||
żądania zatwierdzenia exec.
|
||||
- `exec.approval.waitDecision` czeka na jedną oczekującą decyzję zatwierdzenia exec i zwraca
|
||||
ostateczną decyzję (lub `null` przy limicie czasu).
|
||||
- `exec.approvals.get` i `exec.approvals.set` zarządzają migawkami polityki
|
||||
zatwierdzeń exec gateway.
|
||||
- `exec.approvals.node.get` i `exec.approvals.node.set` zarządzają lokalną polityką exec
|
||||
węzła przez polecenia relay węzła.
|
||||
- `plugin.approval.request`, `plugin.approval.waitDecision` i
|
||||
`plugin.approval.resolve` obejmują przepływy zatwierdzeń definiowane przez pluginy.
|
||||
- `exec.approval.request`, `exec.approval.get`, `exec.approval.list` i
|
||||
`exec.approval.resolve` obejmują jednorazowe żądania zatwierdzenia exec oraz oczekujące
|
||||
wyszukiwanie/odtwarzanie zatwierdzeń.
|
||||
- `exec.approval.waitDecision` czeka na jedno oczekujące zatwierdzenie exec i zwraca
|
||||
ostateczną decyzję (lub `null` przy przekroczeniu czasu).
|
||||
- `exec.approvals.get` i `exec.approvals.set` zarządzają snapshotami polityki zatwierdzeń exec
|
||||
gateway.
|
||||
- `exec.approvals.node.get` i `exec.approvals.node.set` zarządzają lokalną dla węzła
|
||||
polityką zatwierdzeń exec przez polecenia relay węzła.
|
||||
- `plugin.approval.request`, `plugin.approval.list`,
|
||||
`plugin.approval.waitDecision` i `plugin.approval.resolve` obejmują
|
||||
przepływy zatwierdzeń definiowane przez pluginy.
|
||||
|
||||
#### Inne główne rodziny
|
||||
|
||||
- automatyzacja:
|
||||
- `wake` planuje natychmiastowe lub najbliższe wstrzyknięcie tekstu wake przy heartbeat
|
||||
- `wake` planuje natychmiastowe lub przy następnym heartbeat wstrzyknięcie tekstu wybudzającego
|
||||
- `cron.list`, `cron.status`, `cron.add`, `cron.update`, `cron.remove`,
|
||||
`cron.run`, `cron.runs`
|
||||
- Skills/narzędzia: `skills.*`, `tools.catalog`, `tools.effective`
|
||||
- skills/tools: `skills.*`, `tools.catalog`, `tools.effective`
|
||||
|
||||
### Typowe rodziny zdarzeń
|
||||
|
||||
- `chat`: aktualizacje czatu UI, takie jak `chat.inject` i inne zdarzenia czatu
|
||||
dotyczące wyłącznie transkryptu.
|
||||
tylko dla transkryptu.
|
||||
- `session.message` i `session.tool`: aktualizacje transkryptu/strumienia zdarzeń dla
|
||||
subskrybowanej sesji.
|
||||
- `sessions.changed`: indeks sesji lub metadane uległy zmianie.
|
||||
- `presence`: aktualizacje migawki presence systemu.
|
||||
- `tick`: okresowe zdarzenie keepalive / liveness.
|
||||
- `health`: aktualizacja migawki stanu gateway.
|
||||
- `sessions.changed`: zmienił się indeks sesji lub metadane.
|
||||
- `presence`: aktualizacje snapshotu obecności systemu.
|
||||
- `tick`: okresowe zdarzenie keepalive / żywotności.
|
||||
- `health`: aktualizacja snapshotu kondycji gateway.
|
||||
- `heartbeat`: aktualizacja strumienia zdarzeń heartbeat.
|
||||
- `cron`: zdarzenie zmiany uruchomienia/zadania cron.
|
||||
- `shutdown`: powiadomienie o zamknięciu gateway.
|
||||
- `node.pair.requested` / `node.pair.resolved`: cykl życia parowania węzła.
|
||||
- `shutdown`: powiadomienie o wyłączeniu gateway.
|
||||
- `node.pair.requested` / `node.pair.resolved`: cykl życia parowania węzłów.
|
||||
- `node.invoke.request`: rozgłoszenie żądania invoke węzła.
|
||||
- `device.pair.requested` / `device.pair.resolved`: cykl życia sparowanego urządzenia.
|
||||
- `voicewake.changed`: zmieniono konfigurację wyzwalaczy wake word.
|
||||
- `exec.approval.requested` / `exec.approval.resolved`: cykl życia
|
||||
zatwierdzenia exec.
|
||||
- `plugin.approval.requested` / `plugin.approval.resolved`: cykl życia zatwierdzenia pluginu.
|
||||
- `device.pair.requested` / `device.pair.resolved`: cykl życia sparowanych urządzeń.
|
||||
- `voicewake.changed`: zmieniła się konfiguracja wyzwalacza słowa aktywującego.
|
||||
- `exec.approval.requested` / `exec.approval.resolved`: cykl życia zatwierdzeń exec.
|
||||
- `plugin.approval.requested` / `plugin.approval.resolved`: cykl życia zatwierdzeń pluginów.
|
||||
|
||||
### Metody pomocnicze węzła
|
||||
### Metody pomocnicze węzłów
|
||||
|
||||
- Węzły mogą wywoływać `skills.bins`, aby pobrać bieżącą listę wykonywalnych plików Skill
|
||||
do kontroli auto-allow.
|
||||
- Węzły mogą wywoływać `skills.bins`, aby pobrać bieżącą listę plików wykonywalnych skill
|
||||
na potrzeby automatycznych kontroli listy dozwolonych.
|
||||
|
||||
### Metody pomocnicze operatora
|
||||
|
||||
- Operatorzy mogą wywoływać `tools.catalog` (`operator.read`), aby pobrać katalog narzędzi runtime dla
|
||||
- Operatorzy mogą wywoływać `tools.catalog` (`operator.read`), aby pobrać katalog narzędzi środowiska wykonawczego dla
|
||||
agenta. Odpowiedź zawiera pogrupowane narzędzia i metadane pochodzenia:
|
||||
- `source`: `core` lub `plugin`
|
||||
- `pluginId`: właściciel pluginu, gdy `source="plugin"`
|
||||
- `optional`: czy narzędzie pluginu jest opcjonalne
|
||||
- Operatorzy mogą wywoływać `tools.effective` (`operator.read`), aby pobrać efektywny inwentarz narzędzi runtime
|
||||
dla sesji.
|
||||
- Operatorzy mogą wywoływać `tools.effective` (`operator.read`), aby pobrać efektywny w czasie działania
|
||||
spis narzędzi dla sesji.
|
||||
- `sessionKey` jest wymagane.
|
||||
- Gateway wyprowadza zaufany kontekst runtime po stronie serwera z sesji zamiast akceptować
|
||||
auth lub kontekst dostarczenia dostarczony przez wywołującego.
|
||||
- Odpowiedź ma zakres sesji i odzwierciedla to, czego aktywna rozmowa może używać w tej chwili,
|
||||
w tym narzędzi rdzenia, pluginów i kanałów.
|
||||
- Gateway wyprowadza zaufany kontekst środowiska wykonawczego po stronie serwera z sesji zamiast akceptować
|
||||
kontekst uwierzytelniania lub dostarczenia dostarczony przez wywołującego.
|
||||
- Odpowiedź jest ograniczona do sesji i odzwierciedla to, czego aktywna rozmowa może użyć w danej chwili,
|
||||
w tym narzędzia rdzenia, pluginów i kanałów.
|
||||
- Operatorzy mogą wywoływać `skills.status` (`operator.read`), aby pobrać widoczny
|
||||
inwentarz Skill dla agenta.
|
||||
- `agentId` jest opcjonalne; pomiń je, aby odczytać domyślny workspace agenta.
|
||||
- Odpowiedź zawiera kwalifikowalność, brakujące wymagania, kontrole konfiguracji i
|
||||
oczyszczone opcje instalacji bez ujawniania surowych wartości sekretów.
|
||||
spis skills dla agenta.
|
||||
- `agentId` jest opcjonalne; pomiń je, aby odczytać domyślny obszar roboczy agenta.
|
||||
- Odpowiedź zawiera kwalifikowalność, brakujące wymagania, kontrole konfiguracji oraz
|
||||
zsanityzowane opcje instalacji bez ujawniania surowych wartości sekretów.
|
||||
- Operatorzy mogą wywoływać `skills.search` i `skills.detail` (`operator.read`) dla
|
||||
metadanych wykrywania ClawHub.
|
||||
- Operatorzy mogą wywoływać `skills.install` (`operator.admin`) w dwóch trybach:
|
||||
- Tryb ClawHub: `{ source: "clawhub", slug, version?, force? }` instaluje
|
||||
folder Skill do katalogu `skills/` domyślnego workspace agenta.
|
||||
folder skill w katalogu `skills/` domyślnego obszaru roboczego agenta.
|
||||
- Tryb instalatora Gateway: `{ name, installId, dangerouslyForceUnsafeInstall?, timeoutMs? }`
|
||||
uruchamia zadeklarowaną akcję `metadata.openclaw.install` na hoście gateway.
|
||||
- Operatorzy mogą wywoływać `skills.update` (`operator.admin`) w dwóch trybach:
|
||||
- Tryb ClawHub aktualizuje jeden śledzony slug lub wszystkie śledzone instalacje ClawHub w
|
||||
domyślnym workspace agenta.
|
||||
- Tryb config łata wartości `skills.entries.<skillKey>`, takie jak `enabled`,
|
||||
domyślnym obszarze roboczym agenta.
|
||||
- Tryb konfiguracji łata 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ą to przez wywołanie `exec.approval.resolve` (wymaga zakresu `operator.approvals`).
|
||||
- Klienci operatora rozwiązują je przez wywołanie `exec.approval.resolve` (wymaga zakresu `operator.approvals`).
|
||||
- Dla `host=node`, `exec.approval.request` musi zawierać `systemRunPlan` (kanoniczne `argv`/`cwd`/`rawCommand`/metadane sesji). Żądania bez `systemRunPlan` są odrzucane.
|
||||
- Po zatwierdzeniu przekazane wywołania `node.invoke system.run` używają ponownie tego kanonicznego
|
||||
- Po zatwierdzeniu przekazane wywołania `node.invoke system.run` ponownie używają tego kanonicznego
|
||||
`systemRunPlan` jako autorytatywnego kontekstu polecenia/cwd/sesji.
|
||||
- Jeśli wywołujący zmieni `command`, `rawCommand`, `cwd`, `agentId` lub
|
||||
`sessionKey` między prepare a końcowym zatwierdzonym przekazaniem `system.run`, gateway odrzuci uruchomienie zamiast ufać zmodyfikowanemu ładunkowi.
|
||||
`sessionKey` między prepare a końcowym zatwierdzonym przekazaniem `system.run`,
|
||||
gateway odrzuci uruchomienie zamiast ufać zmodyfikowanemu ładunkowi.
|
||||
|
||||
## Zapasowe dostarczenie agenta
|
||||
## Zapasowe dostarczanie agenta
|
||||
|
||||
- Żądania `agent` mogą zawierać `deliver=true`, aby zażądać dostarczenia wychodzącego.
|
||||
- `bestEffortDeliver=false` zachowuje ścisłe działanie: nierozwiązane lub wyłącznie wewnętrzne cele dostarczenia zwracają `INVALID_REQUEST`.
|
||||
- `bestEffortDeliver=true` pozwala na przejście do wykonania wyłącznie w sesji, gdy nie można rozwiązać zewnętrznej trasy dostarczalnej (na przykład sesje internal/webchat lub niejednoznaczne konfiguracje wielokanałowe).
|
||||
- `bestEffortDeliver=false` zachowuje rygorystyczne działanie: nierozwiązane lub wyłącznie wewnętrzne cele dostarczenia zwracają `INVALID_REQUEST`.
|
||||
- `bestEffortDeliver=true` umożliwia przejście awaryjne do wykonania tylko w sesji, gdy nie można rozwiązać żadnej zewnętrznej trasy dostarczenia (na przykład sesje internal/webchat lub niejednoznaczne konfiguracje wielu kanałów).
|
||||
|
||||
## Wersjonowanie
|
||||
|
||||
- `PROTOCOL_VERSION` znajduje się w `src/gateway/protocol/schema.ts`.
|
||||
- Klienci wysyłają `minProtocol` + `maxProtocol`; serwer odrzuca niezgodności.
|
||||
- Klienci wysyłają `minProtocol` + `maxProtocol`; serwer odrzuca niedopasowania.
|
||||
- Schematy + modele są generowane z definicji TypeBox:
|
||||
- `pnpm protocol:gen`
|
||||
- `pnpm protocol:gen:swift`
|
||||
- `pnpm protocol:check`
|
||||
|
||||
## Auth
|
||||
## Uwierzytelnianie
|
||||
|
||||
- Uwierzytelnianie gateway przy użyciu współdzielonego sekretu używa `connect.params.auth.token` lub
|
||||
`connect.params.auth.password`, zależnie od skonfigurowanego trybu auth.
|
||||
- Tryby przenoszące tożsamość, takie jak Tailscale Serve
|
||||
(`gateway.auth.allowTailscale: true`) lub `gateway.auth.mode: "trusted-proxy"` poza loopback,
|
||||
spełniają kontrolę auth dla connect na podstawie nagłówków żądania zamiast
|
||||
`connect.params.auth.*`.
|
||||
- Prywatny ingress `gateway.auth.mode: "none"` całkowicie pomija uwierzytelnianie connect współdzielonym sekretem;
|
||||
nie wystawiaj tego trybu na publiczny/niezaufany ingress.
|
||||
- Po sparowaniu Gateway wydaje **token urządzenia** o zakresie zgodnym z rolą + zakresami połączenia.
|
||||
Jest on zwracany w `hello-ok.auth.deviceToken` i powinien zostać
|
||||
utrwalony przez klienta do przyszłych połączeń.
|
||||
- Uwierzytelnianie gateway współdzielonym sekretem używa `connect.params.auth.token` lub
|
||||
`connect.params.auth.password`, zależnie od skonfigurowanego trybu uwierzytelniania.
|
||||
- Tryby niosące tożsamość, takie jak Tailscale Serve
|
||||
(`gateway.auth.allowTailscale: true`) lub `gateway.auth.mode: "trusted-proxy"` inne niż
|
||||
local loopback, spełniają kontrolę uwierzytelniania connect na podstawie
|
||||
nagłówków żądania zamiast `connect.params.auth.*`.
|
||||
- Prywatny ingress `gateway.auth.mode: "none"` całkowicie pomija uwierzytelnianie connect współdzielonym sekretem; nie wystawiaj tego trybu na publiczny/niezaufany ingress.
|
||||
- Po sparowaniu Gateway wydaje **token urządzenia** ograniczony do roli + zakresów połączenia.
|
||||
Jest on zwracany w `hello-ok.auth.deviceToken` i powinien być
|
||||
utrwalony przez klienta na potrzeby przyszłych połączeń.
|
||||
- Klienci powinni utrwalać podstawowy `hello-ok.auth.deviceToken` po każdym
|
||||
udanym połączeniu.
|
||||
- Ponowne połączenie z tym **zapisanym** tokenem urządzenia powinno również ponownie używać zapisanego
|
||||
zestawu zatwierdzonych zakresów dla tego tokena. Pozwala to zachować już przyznany
|
||||
dostęp do odczytu/sond/statusu i unika cichego zawężania ponownych połączeń do
|
||||
węższego domyślnego zakresu wyłącznie admin.
|
||||
- Normalna kolejność auth dla connect to najpierw jawny współdzielony token/hasło, potem
|
||||
jawne `deviceToken`, potem zapisany token per urządzenie, a następnie token bootstrap.
|
||||
- Ponowne łączenie z tym **zapisanym** tokenem urządzenia powinno także ponownie używać zapisanego
|
||||
zatwierdzonego zestawu zakresów dla tego tokenu. Pozwala to zachować już przyznany
|
||||
dostęp do odczytu/sprawdzeń/statusu i unika cichego zawężenia ponownych połączeń do
|
||||
węższego, domyślnego zakresu tylko admin.
|
||||
- Zwykła kolejność pierwszeństwa uwierzytelniania connect to najpierw jawny współdzielony token/hasło, potem
|
||||
jawny `deviceToken`, potem zapisany token per urządzenie, a następnie token bootstrap.
|
||||
- Dodatkowe wpisy `hello-ok.auth.deviceTokens` to tokeny przekazania bootstrap.
|
||||
Utrwalaj je tylko wtedy, gdy połączenie używało auth bootstrap na zaufanym transporcie,
|
||||
Utrwalaj je tylko wtedy, gdy połączenie użyło uwierzytelniania bootstrap na zaufanym transporcie,
|
||||
takim jak `wss://` lub loopback/local pairing.
|
||||
- Jeśli klient dostarcza **jawne** `deviceToken` lub jawne `scopes`, ten
|
||||
zestaw zakresów żądany przez wywołującego pozostaje autorytatywny; buforowane zakresy są ponownie używane tylko wtedy,
|
||||
gdy klient używa zapisanego tokena per urządzenie.
|
||||
- Tokeny urządzeń mogą być obracane/unieważniane przez `device.token.rotate` i
|
||||
- Jeśli klient dostarczy **jawny** `deviceToken` lub jawne `scopes`, ten
|
||||
żądany przez wywołującego zestaw zakresów pozostaje autorytatywny; zakresy z pamięci podręcznej są ponownie używane tylko wtedy, gdy klient ponownie używa zapisanego tokenu per urządzenie.
|
||||
- Tokeny urządzeń można obracać/unieważniać przez `device.token.rotate` i
|
||||
`device.token.revoke` (wymaga zakresu `operator.pairing`).
|
||||
- Wydawanie/obracanie tokenów pozostaje ograniczone do zatwierdzonego zestawu ról zapisanego we
|
||||
wpisie parowania tego urządzenia; obrót tokena nie może rozszerzyć urządzenia do
|
||||
roli, której zatwierdzenie parowania nigdy nie przyznało.
|
||||
- Dla sesji tokenów sparowanych urządzeń zarządzanie urządzeniem ma zakres własny, chyba że
|
||||
wywołujący ma również `operator.admin`: wywołujący bez admin może usuwać/unieważniać/obracać
|
||||
- Wydawanie/obracanie tokenów pozostaje ograniczone do zatwierdzonego zestawu ról zapisanych w
|
||||
wpisie parowania tego urządzenia; obrót tokenu nie może rozszerzyć urządzenia do
|
||||
roli, której zatwierdzenie parowania nigdy nie nadało.
|
||||
- Dla sesji tokenów sparowanych urządzeń zarządzanie urządzeniem jest ograniczone do własnego zakresu, chyba że
|
||||
wywołujący ma także `operator.admin`: użytkownicy bez admina mogą usuwać/unieważniać/obracać
|
||||
tylko **własny** wpis urządzenia.
|
||||
- `device.token.rotate` sprawdza także żądany zestaw zakresów operatora względem
|
||||
bieżących zakresów sesji wywołującego. Wywołujący bez admin nie może obrócić tokena do
|
||||
szerszego zestawu zakresów operatora, niż już posiada.
|
||||
- Błędy auth zawierają `error.details.code` oraz podpowiedzi naprawcze:
|
||||
bieżących zakresów sesji wywołującego. Użytkownicy bez admina nie mogą obracać tokenu do
|
||||
szerszego zestawu zakresów operatora, niż już posiadają.
|
||||
- Niepowodzenia uwierzytelniania zawierają `error.details.code` oraz wskazówki odzyskiwania:
|
||||
- `error.details.canRetryWithDeviceToken` (boolean)
|
||||
- `error.details.recommendedNextStep` (`retry_with_device_token`, `update_auth_configuration`, `update_auth_credentials`, `wait_then_retry`, `review_auth_configuration`)
|
||||
- Zachowanie klienta dla `AUTH_TOKEN_MISMATCH`:
|
||||
- Zaufani klienci mogą podjąć jedną ograniczoną próbę ponowną z buforowanym tokenem per urządzenie.
|
||||
- Jeśli ta próba się nie powiedzie, klienci powinni zatrzymać automatyczne pętle ponownego łączenia i wyświetlić operatorowi wskazówki wymagające działania.
|
||||
- Zaufani klienci mogą podjąć jedną ograniczoną próbę ponowienia z tokenem per urządzenie z pamięci podręcznej.
|
||||
- Jeśli to ponowienie się nie powiedzie, klienci powinni zatrzymać automatyczne pętle ponownego łączenia i wyświetlić operatorowi wskazówki dotyczące działania.
|
||||
|
||||
## Tożsamość urządzenia + parowanie
|
||||
|
||||
- Węzły powinny zawierać stabilną tożsamość urządzenia (`device.id`) wyprowadzoną z
|
||||
fingerprintu pary kluczy.
|
||||
- Gateway wydaje tokeny per urządzenie + rola.
|
||||
- Dla nowych `deviceId` wymagane są zatwierdzenia parowania, chyba że włączono lokalne auto-zatwierdzanie.
|
||||
- Auto-zatwierdzanie parowania jest skoncentrowane na bezpośrednich lokalnych połączeniach loopback.
|
||||
- OpenClaw ma także wąską ścieżkę backend/container-local self-connect dla
|
||||
odcisku palca pary kluczy.
|
||||
- Gateway wydaje tokeny dla każdego urządzenia + roli.
|
||||
- Zatwierdzenia parowania są wymagane dla nowych identyfikatorów urządzeń, chyba że włączono
|
||||
lokalne automatyczne zatwierdzanie.
|
||||
- Automatyczne zatwierdzanie parowania jest skoncentrowane na bezpośrednich lokalnych połączeniach local loopback.
|
||||
- OpenClaw ma także wąską ścieżkę samopołączenia backend/kontener-local dla
|
||||
zaufanych przepływów pomocniczych ze współdzielonym sekretem.
|
||||
- Połączenia tailnet lub LAN z tego samego hosta nadal są traktowane jako zdalne w kontekście parowania i
|
||||
- Połączenia tailnet lub LAN z tego samego hosta są nadal traktowane jako zdalne na potrzeby parowania i
|
||||
wymagają zatwierdzenia.
|
||||
- Wszyscy klienci WS muszą zawierać tożsamość `device` podczas `connect` (operator + node).
|
||||
- Wszyscy klienci WS muszą dołączać tożsamość `device` podczas `connect` (operator + node).
|
||||
Control UI może ją pominąć tylko w tych trybach:
|
||||
- `gateway.controlUi.allowInsecureAuth=true` dla zgodności z niezabezpieczonym HTTP tylko dla localhost.
|
||||
- udane auth operatora `gateway.auth.mode: "trusted-proxy"` dla Control UI.
|
||||
- `gateway.controlUi.allowInsecureAuth=true` dla zgodności z niezabezpieczonym HTTP tylko na localhost.
|
||||
- udane uwierzytelnianie operatora Control UI z `gateway.auth.mode: "trusted-proxy"`.
|
||||
- `gateway.controlUi.dangerouslyDisableDeviceAuth=true` (tryb awaryjny, poważne obniżenie bezpieczeństwa).
|
||||
- Wszystkie połączenia muszą podpisywać dostarczony przez serwer nonce `connect.challenge`.
|
||||
- Wszystkie połączenia muszą podpisywać nonce dostarczone przez serwer w `connect.challenge`.
|
||||
|
||||
### Diagnostyka migracji auth urządzeń
|
||||
### Diagnostyka migracji uwierzytelniania urządzenia
|
||||
|
||||
Dla starszych klientów, którzy nadal używają zachowania podpisywania sprzed wyzwania, `connect` zwraca teraz
|
||||
Dla starszych klientów, którzy nadal używają zachowania podpisywania sprzed wyzwania, `connect` teraz zwraca
|
||||
kody szczegółów `DEVICE_AUTH_*` pod `error.details.code` ze stabilnym `error.details.reason`.
|
||||
|
||||
Typowe błędy migracji:
|
||||
Typowe niepowodzenia migracji:
|
||||
|
||||
| Komunikat | details.code | details.reason | Znaczenie |
|
||||
| Komunikat | details.code | details.reason | Znaczenie |
|
||||
| --------------------------- | -------------------------------- | ------------------------ | -------------------------------------------------- |
|
||||
| `device nonce required` | `DEVICE_AUTH_NONCE_REQUIRED` | `device-nonce-missing` | Klient pominął `device.nonce` (lub wysłał pusty). |
|
||||
| `device nonce mismatch` | `DEVICE_AUTH_NONCE_MISMATCH` | `device-nonce-mismatch` | Klient podpisał przy użyciu nieaktualnego/błędnego nonce. |
|
||||
| `device signature invalid` | `DEVICE_AUTH_SIGNATURE_INVALID` | `device-signature` | Ładunek podpisu nie odpowiada ładunkowi v2. |
|
||||
| `device signature expired` | `DEVICE_AUTH_SIGNATURE_EXPIRED` | `device-signature-stale` | Podpisany znacznik czasu jest poza dozwolonym odchyleniem. |
|
||||
| `device identity mismatch` | `DEVICE_AUTH_DEVICE_ID_MISMATCH` | `device-id-mismatch` | `device.id` nie pasuje do fingerprintu klucza publicznego. |
|
||||
| `device public key invalid` | `DEVICE_AUTH_PUBLIC_KEY_INVALID` | `device-public-key` | Format/kanonizacja klucza publicznego nie powiodły się. |
|
||||
| `device nonce required` | `DEVICE_AUTH_NONCE_REQUIRED` | `device-nonce-missing` | Klient pominął `device.nonce` (lub wysłał pusty). |
|
||||
| `device nonce mismatch` | `DEVICE_AUTH_NONCE_MISMATCH` | `device-nonce-mismatch` | Klient podpisał starym/błędnym nonce. |
|
||||
| `device signature invalid` | `DEVICE_AUTH_SIGNATURE_INVALID` | `device-signature` | Ładunek podpisu nie pasuje do ładunku v2. |
|
||||
| `device signature expired` | `DEVICE_AUTH_SIGNATURE_EXPIRED` | `device-signature-stale` | Podpisany znacznik czasu jest poza dozwolonym odchyleniem. |
|
||||
| `device identity mismatch` | `DEVICE_AUTH_DEVICE_ID_MISMATCH` | `device-id-mismatch` | `device.id` nie pasuje do odcisku palca klucza publicznego. |
|
||||
| `device public key invalid` | `DEVICE_AUTH_PUBLIC_KEY_INVALID` | `device-public-key` | Format/kanonikalizacja klucza publicznego nie powiodły się. |
|
||||
|
||||
Cel migracji:
|
||||
|
||||
- Zawsze czekaj na `connect.challenge`.
|
||||
- Podpisuj ładunek v2, który zawiera nonce serwera.
|
||||
- Wysyłaj ten sam nonce w `connect.params.device.nonce`.
|
||||
- Wyślij ten sam nonce w `connect.params.device.nonce`.
|
||||
- Preferowany ładunek podpisu to `v3`, który wiąże `platform` i `deviceFamily`
|
||||
oprócz pól device/client/role/scopes/token/nonce.
|
||||
- Starsze podpisy `v2` pozostają akceptowane dla zgodności, ale przypinanie metadanych
|
||||
sparowanych urządzeń nadal steruje polityką poleceń przy ponownym połączeniu.
|
||||
- Starsze podpisy `v2` pozostają akceptowane ze względu na zgodność, ale przypinanie metadanych sparowanego urządzenia nadal kontroluje politykę poleceń przy ponownym połączeniu.
|
||||
|
||||
## TLS + pinning
|
||||
|
||||
- TLS jest obsługiwany dla połączeń WS.
|
||||
- Klienci mogą opcjonalnie przypinać fingerprint certyfikatu gateway (zobacz konfigurację `gateway.tls`
|
||||
- Klienci mogą opcjonalnie przypiąć odcisk palca certyfikatu gateway (zobacz konfigurację `gateway.tls`
|
||||
oraz `gateway.remote.tlsFingerprint` lub flagę CLI `--tls-fingerprint`).
|
||||
|
||||
## Zakres
|
||||
|
||||
Ten protokół udostępnia **pełne API gateway** (status, kanały, models, chat,
|
||||
agent, sessions, nodes, approvals itd.). Dokładna powierzchnia jest definiowana przez
|
||||
Ten protokół udostępnia **pełne API gateway** (status, kanały, modele, czat,
|
||||
agent, sesje, węzły, zatwierdzenia itd.). Dokładna powierzchnia jest zdefiniowana przez
|
||||
schematy TypeBox w `src/gateway/protocol/schema.ts`.
|
||||
|
||||
@ -1,26 +1,26 @@
|
||||
---
|
||||
read_when:
|
||||
- Centrum rozwiązywania problemów skierowało Cię tutaj w celu głębszej diagnostyki
|
||||
- Potrzebujesz stabilnych sekcji podręcznika opartych na objawach z dokładnymi poleceniami
|
||||
summary: Szczegółowy podręcznik rozwiązywania problemów dotyczących gateway, kanałów, automatyzacji, węzłów i przeglądarki
|
||||
- Centrum rozwiązywania problemów skierowało Cię tutaj w celu głębszej diagnozy
|
||||
- Potrzebujesz stabilnych sekcji poradnika opartych na objawach z dokładnymi poleceniami
|
||||
summary: Szczegółowy poradnik rozwiązywania problemów z gateway, kanałami, automatyzacją, węzłami i przeglądarką
|
||||
title: Rozwiązywanie problemów
|
||||
x-i18n:
|
||||
generated_at: "2026-04-07T09:46:00Z"
|
||||
generated_at: "2026-04-08T02:16:03Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: e0202e8858310a0bfc1c994cd37b01c3b2d6c73c8a74740094e92dc3c4c36729
|
||||
source_hash: 02c9537845248db0c9d315bf581338a93215fe6fe3688ed96c7105cbb19fe6ba
|
||||
source_path: gateway/troubleshooting.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Rozwiązywanie problemów z gateway
|
||||
|
||||
Ta strona to szczegółowy podręcznik.
|
||||
Zacznij od [/help/troubleshooting](/pl/help/troubleshooting), jeśli najpierw chcesz skorzystać z szybkiego przepływu triage.
|
||||
Ta strona to szczegółowy poradnik.
|
||||
Zacznij od [/help/troubleshooting](/pl/help/troubleshooting), jeśli najpierw chcesz skorzystać z szybkiego procesu diagnostycznego.
|
||||
|
||||
## Drabina poleceń
|
||||
|
||||
Uruchom najpierw te polecenia, w tej kolejności:
|
||||
Uruchom te polecenia najpierw, w tej kolejności:
|
||||
|
||||
```bash
|
||||
openclaw status
|
||||
@ -33,11 +33,11 @@ openclaw channels status --probe
|
||||
Oczekiwane sygnały zdrowego działania:
|
||||
|
||||
- `openclaw gateway status` pokazuje `Runtime: running` i `RPC probe: ok`.
|
||||
- `openclaw doctor` nie zgłasza blokujących problemów z konfiguracją/usługą.
|
||||
- `openclaw channels status --probe` pokazuje stan transportu dla każdego konta na żywo oraz,
|
||||
tam gdzie jest to obsługiwane, wyniki probe/audytu, takie jak `works` lub `audit ok`.
|
||||
- `openclaw doctor` nie zgłasza blokujących problemów z konfiguracją ani usługą.
|
||||
- `openclaw channels status --probe` pokazuje bieżący stan transportu dla każdego konta oraz,
|
||||
tam gdzie jest to obsługiwane, wyniki sondy/audytu, takie jak `works` lub `audit ok`.
|
||||
|
||||
## Anthropic 429: dodatkowe użycie wymagane dla długiego kontekstu
|
||||
## Anthropic 429: wymagane dodatkowe użycie dla długiego kontekstu
|
||||
|
||||
Użyj tego, gdy logi/błędy zawierają:
|
||||
`HTTP 429: rate_limit_error: Extra usage is required for long context requests`.
|
||||
@ -48,17 +48,17 @@ openclaw models status
|
||||
openclaw config get agents.defaults.models
|
||||
```
|
||||
|
||||
Poszukaj:
|
||||
Szukaj:
|
||||
|
||||
- Wybrany model Anthropic Opus/Sonnet ma `params.context1m: true`.
|
||||
- Bieżące poświadczenie Anthropic nie kwalifikuje się do użycia długiego kontekstu.
|
||||
- Żądania zawodzą tylko w długich sesjach/uruchomieniach modelu, które wymagają ścieżki beta 1M.
|
||||
- Żądania kończą się niepowodzeniem tylko w długich sesjach/uruchomieniach modelu, które wymagają ścieżki 1M beta.
|
||||
|
||||
Opcje naprawy:
|
||||
|
||||
1. Wyłącz `context1m` dla tego modelu, aby wrócić do zwykłego okna kontekstu.
|
||||
2. Użyj poświadczenia Anthropic, które kwalifikuje się do żądań długiego kontekstu, albo przełącz się na klucz API Anthropic.
|
||||
3. Skonfiguruj modele zapasowe, aby uruchomienia były kontynuowane, gdy żądania Anthropic dla długiego kontekstu są odrzucane.
|
||||
3. Skonfiguruj modele zapasowe, aby uruchomienia były kontynuowane, gdy żądania długiego kontekstu Anthropic są odrzucane.
|
||||
|
||||
Powiązane:
|
||||
|
||||
@ -66,9 +66,60 @@ Powiązane:
|
||||
- [/reference/token-use](/pl/reference/token-use)
|
||||
- [/help/faq#why-am-i-seeing-http-429-ratelimiterror-from-anthropic](/pl/help/faq#why-am-i-seeing-http-429-ratelimiterror-from-anthropic)
|
||||
|
||||
## Lokalny backend zgodny z OpenAI przechodzi bezpośrednie sondy, ale uruchomienia agenta kończą się niepowodzeniem
|
||||
|
||||
Użyj tego, gdy:
|
||||
|
||||
- `curl ... /v1/models` działa
|
||||
- małe bezpośrednie wywołania `/v1/chat/completions` działają
|
||||
- uruchomienia modeli OpenClaw kończą się niepowodzeniem tylko podczas zwykłych tur agenta
|
||||
|
||||
```bash
|
||||
curl http://127.0.0.1:1234/v1/models
|
||||
curl http://127.0.0.1:1234/v1/chat/completions \
|
||||
-H 'content-type: application/json' \
|
||||
-d '{"model":"<id>","messages":[{"role":"user","content":"hi"}],"stream":false}'
|
||||
openclaw infer model run --model <provider/model> --prompt "hi" --json
|
||||
openclaw logs --follow
|
||||
```
|
||||
|
||||
Szukaj:
|
||||
|
||||
- małe bezpośrednie wywołania kończą się powodzeniem, ale uruchomienia OpenClaw kończą się niepowodzeniem tylko przy większych promptach
|
||||
- błędów backendu dotyczących tego, że `messages[].content` ma oczekiwać ciągu znaków
|
||||
- awarii backendu, które pojawiają się tylko przy większej liczbie tokenów promptu lub pełnych promptach środowiska uruchomieniowego agenta
|
||||
|
||||
Typowe sygnatury:
|
||||
|
||||
- `messages[...].content: invalid type: sequence, expected a string` → backend
|
||||
odrzuca strukturalne części treści Chat Completions. Poprawka: ustaw
|
||||
`models.providers.<provider>.models[].compat.requiresStringContent: true`.
|
||||
- małe bezpośrednie żądania kończą się powodzeniem, ale uruchomienia agenta OpenClaw kończą się niepowodzeniem z awariami backendu/modelu
|
||||
(na przykład Gemma w niektórych kompilacjach `inferrs`) → transport OpenClaw
|
||||
jest prawdopodobnie już poprawny; to backend zawodzi przy większym kształcie promptu środowiska uruchomieniowego agenta.
|
||||
- niepowodzenia zmniejszają się po wyłączeniu narzędzi, ale nie znikają → schematy narzędzi
|
||||
były częścią obciążenia, ale pozostały problem nadal dotyczy pojemności modelu/serwera po stronie upstream albo błędu backendu.
|
||||
|
||||
Opcje naprawy:
|
||||
|
||||
1. Ustaw `compat.requiresStringContent: true` dla backendów Chat Completions obsługujących wyłącznie ciągi znaków.
|
||||
2. Ustaw `compat.supportsTools: false` dla modeli/backendów, które nie są w stanie
|
||||
niezawodnie obsłużyć powierzchni schematu narzędzi OpenClaw.
|
||||
3. Ogranicz obciążenie promptu tam, gdzie to możliwe: mniejszy bootstrap obszaru roboczego, krótsza
|
||||
historia sesji, lżejszy model lokalny lub backend z lepszym wsparciem dla długiego kontekstu.
|
||||
4. Jeśli małe bezpośrednie żądania nadal przechodzą, a tury agenta OpenClaw wciąż ulegają awarii
|
||||
wewnątrz backendu, potraktuj to jako ograniczenie serwera/modelu po stronie upstream i zgłoś tam
|
||||
reprodukcję z zaakceptowanym kształtem ładunku.
|
||||
|
||||
Powiązane:
|
||||
|
||||
- [/gateway/local-models](/pl/gateway/local-models)
|
||||
- [/gateway/configuration#models](/pl/gateway/configuration#models)
|
||||
- [/gateway/configuration-reference#openai-compatible-endpoints](/pl/gateway/configuration-reference#openai-compatible-endpoints)
|
||||
|
||||
## Brak odpowiedzi
|
||||
|
||||
Jeśli kanały działają, ale nic nie odpowiada, sprawdź routing i zasady przed ponownym łączeniem czegokolwiek.
|
||||
Jeśli kanały działają, ale nic nie odpowiada, sprawdź routing i politykę, zanim cokolwiek ponownie połączysz.
|
||||
|
||||
```bash
|
||||
openclaw status
|
||||
@ -78,17 +129,17 @@ openclaw config get channels
|
||||
openclaw logs --follow
|
||||
```
|
||||
|
||||
Poszukaj:
|
||||
Szukaj:
|
||||
|
||||
- Oczekującego parowania dla nadawców DM.
|
||||
- Bramek wzmianek w grupie (`requireMention`, `mentionPatterns`).
|
||||
- Niezgodności list dozwolonych kanałów/grup.
|
||||
- Oczekiwania na parowanie dla nadawców wiadomości prywatnych.
|
||||
- Wymogu wspomnienia w grupie (`requireMention`, `mentionPatterns`).
|
||||
- Niezgodności z listą dozwolonych kanałów/grup.
|
||||
|
||||
Typowe sygnatury:
|
||||
|
||||
- `drop guild message (mention required` → wiadomość grupowa ignorowana do czasu wzmianki.
|
||||
- `drop guild message (mention required` → wiadomość grupowa została zignorowana do czasu wspomnienia.
|
||||
- `pairing request` → nadawca wymaga zatwierdzenia.
|
||||
- `blocked` / `allowlist` → nadawca/kanał został odfiltrowany przez zasady.
|
||||
- `blocked` / `allowlist` → nadawca/kanał został odfiltrowany przez politykę.
|
||||
|
||||
Powiązane:
|
||||
|
||||
@ -98,7 +149,7 @@ Powiązane:
|
||||
|
||||
## Łączność dashboard/control UI
|
||||
|
||||
Gdy dashboard/control UI nie chce się połączyć, zweryfikuj URL, tryb auth i założenia dotyczące secure context.
|
||||
Gdy dashboard/control UI nie chce się połączyć, sprawdź adres URL, tryb uwierzytelniania i założenia dotyczące bezpiecznego kontekstu.
|
||||
|
||||
```bash
|
||||
openclaw gateway status
|
||||
@ -108,50 +159,50 @@ openclaw doctor
|
||||
openclaw gateway status --json
|
||||
```
|
||||
|
||||
Poszukaj:
|
||||
Szukaj:
|
||||
|
||||
- Prawidłowego adresu probe i adresu dashboard.
|
||||
- Niezgodności trybu auth/tokenu między klientem a gateway.
|
||||
- Poprawnego adresu URL sondy i adresu URL dashboardu.
|
||||
- Niezgodności trybu/tokena uwierzytelniania między klientem a gateway.
|
||||
- Użycia HTTP tam, gdzie wymagana jest tożsamość urządzenia.
|
||||
|
||||
Typowe sygnatury:
|
||||
|
||||
- `device identity required` → niebezpieczny kontekst lub brak auth urządzenia.
|
||||
- `device identity required` → niezabezpieczony kontekst lub brak uwierzytelnienia urządzenia.
|
||||
- `origin not allowed` → `Origin` przeglądarki nie znajduje się w `gateway.controlUi.allowedOrigins`
|
||||
(albo łączysz się z pochodzenia przeglądarki innego niż loopback bez jawnej
|
||||
listy dozwolonych).
|
||||
- `device nonce required` / `device nonce mismatch` → klient nie kończy
|
||||
przepływu auth urządzenia opartego na wyzwaniu (`connect.challenge` + `device.nonce`).
|
||||
- `device signature invalid` / `device signature expired` → klient podpisał niewłaściwy
|
||||
ładunek (albo użył nieaktualnego znacznika czasu) dla bieżącego handshake.
|
||||
- `AUTH_TOKEN_MISMATCH` z `canRetryWithDeviceToken=true` → klient może wykonać jedną zaufaną ponowną próbę z buforowanym tokenem urządzenia.
|
||||
- Ta ponowna próba z buforowanym tokenem ponownie używa buforowanego zestawu zakresów przechowywanego z sparowanym
|
||||
tokenem urządzenia. Wywołania z jawnym `deviceToken` / jawnymi `scopes` zachowują
|
||||
swój żądany zestaw zakresów.
|
||||
- Poza tą ścieżką ponownej próby kolejność auth przy połączeniu to najpierw jawny współdzielony
|
||||
token/hasło, potem jawny `deviceToken`, potem zapisany token urządzenia,
|
||||
a na końcu token bootstrap.
|
||||
- W asynchronicznej ścieżce Tailscale Serve Control UI nieudane próby dla tego samego
|
||||
`{scope, ip}` są serializowane, zanim limiter zarejestruje niepowodzenie. Dwie błędne
|
||||
równoczesne ponowne próby od tego samego klienta mogą więc skutkować komunikatem `retry later`
|
||||
przy drugiej próbie zamiast dwóch zwykłych niezgodności.
|
||||
- `too many failed authentication attempts (retry later)` z klienta loopback
|
||||
o pochodzeniu przeglądarki → powtarzające się niepowodzenia z tego samego znormalizowanego `Origin` są tymczasowo blokowane; inne pochodzenie localhost używa oddzielnego bucketu.
|
||||
- powtarzające się `unauthorized` po tej ponownej próbie → rozjazd współdzielonego tokenu/tokenu urządzenia; odśwież konfigurację tokenu i ponownie zatwierdź/obróć token urządzenia, jeśli to potrzebne.
|
||||
- `gateway connect failed:` → nieprawidłowy host/port/docelowy URL.
|
||||
przepływu uwierzytelniania urządzenia opartego na wyzwaniu (`connect.challenge` + `device.nonce`).
|
||||
- `device signature invalid` / `device signature expired` → klient podpisał nieprawidłowy
|
||||
ładunek (albo użył nieaktualnego znacznika czasu) dla bieżącego uzgadniania.
|
||||
- `AUTH_TOKEN_MISMATCH` z `canRetryWithDeviceToken=true` → klient może wykonać jedną zaufaną ponowną próbę z użyciem buforowanego tokena urządzenia.
|
||||
- Ta ponowna próba z użyciem tokena z pamięci podręcznej wykorzystuje zestaw zakresów przechowywany z powiązanym
|
||||
tokenem urządzenia. Wywołujący z jawnym `deviceToken` / jawnymi `scopes` zachowują zamiast tego
|
||||
żądany zestaw zakresów.
|
||||
- Poza tą ścieżką ponownej próby pierwszeństwo uwierzytelniania połączenia jest następujące: jawny współdzielony
|
||||
token/hasło najpierw, potem jawny `deviceToken`, potem zapisany token urządzenia,
|
||||
a następnie token bootstrap.
|
||||
- Na asynchronicznej ścieżce Tailscale Serve Control UI nieudane próby dla tego samego
|
||||
`{scope, ip}` są serializowane, zanim ogranicznik zarejestruje niepowodzenie. Dwie błędne
|
||||
równoczesne ponowne próby od tego samego klienta mogą więc skutkować `retry later`
|
||||
przy drugiej próbie zamiast dwóch zwykłych niedopasowań.
|
||||
- `too many failed authentication attempts (retry later)` z klienta loopback o pochodzeniu przeglądarki
|
||||
→ powtarzające się niepowodzenia z tego samego znormalizowanego `Origin` są tymczasowo blokowane; inne pochodzenie localhost używa osobnego zasobnika.
|
||||
- powtarzające się `unauthorized` po tej ponownej próbie → rozjazd współdzielonego tokena/tokena urządzenia; odśwież konfigurację tokena i ponownie zatwierdź/obróć token urządzenia, jeśli to konieczne.
|
||||
- `gateway connect failed:` → nieprawidłowy host/port/docelowy adres URL.
|
||||
|
||||
### Szybka mapa kodów szczegółów auth
|
||||
### Szybka mapa szczegółowych kodów uwierzytelniania
|
||||
|
||||
Użyj `error.details.code` z nieudanego response `connect`, aby wybrać następne działanie:
|
||||
Użyj `error.details.code` z nieudanego połączenia `connect`, aby wybrać następne działanie:
|
||||
|
||||
| Detail code | Meaning | Recommended action |
|
||||
| ---------------------------- | ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `AUTH_TOKEN_MISSING` | Klient nie wysłał wymaganego współdzielonego tokenu. | Wklej/ustaw token w kliencie i spróbuj ponownie. Dla ścieżek dashboard: `openclaw config get gateway.auth.token`, a następnie wklej do ustawień Control UI. |
|
||||
| `AUTH_TOKEN_MISMATCH` | Współdzielony token nie pasował do tokenu auth gateway. | Jeśli `canRetryWithDeviceToken=true`, pozwól na jedną zaufaną ponowną próbę. Ponowne próby z buforowanym tokenem używają zapisanych zatwierdzonych zakresów; wywołania z jawnym `deviceToken` / `scopes` zachowują żądane zakresy. Jeśli nadal się nie udaje, uruchom [listę kontrolną odzyskiwania po rozjeździe tokenu](/cli/devices#token-drift-recovery-checklist). |
|
||||
| `AUTH_DEVICE_TOKEN_MISMATCH` | Buforowany token per urządzenie jest nieaktualny lub cofnięty. | Obróć/ponownie zatwierdź token urządzenia za pomocą [CLI urządzeń](/cli/devices), a następnie połącz ponownie. |
|
||||
| `PAIRING_REQUIRED` | Tożsamość urządzenia jest znana, ale niezatwierdzona dla tej roli. | Zatwierdź oczekujące żądanie: `openclaw devices list`, a następnie `openclaw devices approve <requestId>`. |
|
||||
| Detail code | Znaczenie | Zalecane działanie |
|
||||
| ---------------------------- | -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
||||
| `AUTH_TOKEN_MISSING` | Klient nie wysłał wymaganego współdzielonego tokena. | Wklej/ustaw token w kliencie i spróbuj ponownie. Dla ścieżek dashboardu: `openclaw config get gateway.auth.token`, a następnie wklej go do ustawień Control UI. |
|
||||
| `AUTH_TOKEN_MISMATCH` | Współdzielony token nie pasował do tokena auth gateway. | Jeśli `canRetryWithDeviceToken=true`, zezwól na jedną zaufaną ponowną próbę. Ponowne próby z tokenem z pamięci podręcznej wykorzystują zapisane zatwierdzone zakresy; wywołujący z jawnym `deviceToken` / `scopes` zachowują żądane zakresy. Jeśli nadal się nie powiedzie, wykonaj [listę kontrolną odzyskiwania po rozjeździe tokena](/cli/devices#token-drift-recovery-checklist). |
|
||||
| `AUTH_DEVICE_TOKEN_MISMATCH` | Buforowany token dla urządzenia jest nieaktualny lub cofnięty. | Obróć/ponownie zatwierdź token urządzenia za pomocą [CLI urządzeń](/cli/devices), a następnie połącz się ponownie. |
|
||||
| `PAIRING_REQUIRED` | Tożsamość urządzenia jest znana, ale niezatwierdzona dla tej roli. | Zatwierdź oczekujące żądanie: `openclaw devices list`, a następnie `openclaw devices approve <requestId>`. |
|
||||
|
||||
Kontrola migracji auth urządzeń v2:
|
||||
Sprawdzenie migracji uwierzytelniania urządzenia v2:
|
||||
|
||||
```bash
|
||||
openclaw --version
|
||||
@ -159,23 +210,23 @@ openclaw doctor
|
||||
openclaw gateway status
|
||||
```
|
||||
|
||||
Jeśli logi pokazują błędy nonce/signature, zaktualizuj klienta łączącego się i zweryfikuj, że:
|
||||
Jeśli logi pokazują błędy nonce/podpisu, zaktualizuj łączącego się klienta i sprawdź, czy:
|
||||
|
||||
1. czeka na `connect.challenge`
|
||||
2. podpisuje ładunek związany z wyzwaniem
|
||||
2. podpisuje ładunek powiązany z wyzwaniem
|
||||
3. wysyła `connect.params.device.nonce` z tym samym nonce wyzwania
|
||||
|
||||
Jeśli `openclaw devices rotate` / `revoke` / `remove` jest nieoczekiwanie odrzucane:
|
||||
|
||||
- sesje tokenów sparowanych urządzeń mogą zarządzać tylko **własnym** urządzeniem, chyba że
|
||||
- sesje tokena sparowanego urządzenia mogą zarządzać tylko **własnym** urządzeniem, chyba że
|
||||
wywołujący ma również `operator.admin`
|
||||
- `openclaw devices rotate --scope ...` może żądać tylko takich zakresów operatora,
|
||||
które sesja wywołująca już posiada
|
||||
- `openclaw devices rotate --scope ...` może żądać tylko zakresów operatora, które
|
||||
sesja wywołującego już posiada
|
||||
|
||||
Powiązane:
|
||||
|
||||
- [/web/control-ui](/web/control-ui)
|
||||
- [/gateway/configuration](/pl/gateway/configuration) (tryby auth gateway)
|
||||
- [/gateway/configuration](/pl/gateway/configuration) (tryby uwierzytelniania gateway)
|
||||
- [/gateway/trusted-proxy-auth](/pl/gateway/trusted-proxy-auth)
|
||||
- [/gateway/remote](/pl/gateway/remote)
|
||||
- [/cli/devices](/cli/devices)
|
||||
@ -189,23 +240,23 @@ openclaw gateway status
|
||||
openclaw status
|
||||
openclaw logs --follow
|
||||
openclaw doctor
|
||||
openclaw gateway status --deep # skanuje też usługi na poziomie systemu
|
||||
openclaw gateway status --deep # also scan system-level services
|
||||
```
|
||||
|
||||
Poszukaj:
|
||||
Szukaj:
|
||||
|
||||
- `Runtime: stopped` ze wskazówkami dotyczącymi zakończenia.
|
||||
- `Runtime: stopped` z podpowiedziami dotyczącymi zakończenia.
|
||||
- Niezgodności konfiguracji usługi (`Config (cli)` vs `Config (service)`).
|
||||
- Konfliktów portów/listenerów.
|
||||
- Dodatkowych instalacji launchd/systemd/schtasks, gdy użyto `--deep`.
|
||||
- Dodatkowych instalacji launchd/systemd/schtasks przy użyciu `--deep`.
|
||||
- Wskazówek czyszczenia `Other gateway-like services detected (best effort)`.
|
||||
|
||||
Typowe sygnatury:
|
||||
|
||||
- `Gateway start blocked: set gateway.mode=local` lub `existing config is missing gateway.mode` → lokalny tryb gateway nie jest włączony albo plik konfiguracji został nadpisany i utracił `gateway.mode`. Naprawa: ustaw `gateway.mode="local"` w konfiguracji albo uruchom ponownie `openclaw onboard --mode local` / `openclaw setup`, aby ponownie zapisać oczekiwaną konfigurację trybu lokalnego. Jeśli uruchamiasz OpenClaw przez Podman, domyślną ścieżką konfiguracji jest `~/.openclaw/openclaw.json`.
|
||||
- `refusing to bind gateway ... without auth` → powiązanie inne niż loopback bez prawidłowej ścieżki auth gateway (token/hasło lub trusted-proxy, jeśli skonfigurowano).
|
||||
- `Gateway start blocked: set gateway.mode=local` lub `existing config is missing gateway.mode` → tryb lokalny gateway nie jest włączony albo plik konfiguracji został uszkodzony i utracił `gateway.mode`. Poprawka: ustaw `gateway.mode="local"` w konfiguracji albo uruchom ponownie `openclaw onboard --mode local` / `openclaw setup`, aby ponownie zapisać oczekiwaną konfigurację trybu lokalnego. Jeśli uruchamiasz OpenClaw przez Podman, domyślna ścieżka konfiguracji to `~/.openclaw/openclaw.json`.
|
||||
- `refusing to bind gateway ... without auth` → powiązanie inne niż loopback bez prawidłowej ścieżki uwierzytelniania gateway (token/hasło albo trusted-proxy tam, gdzie jest skonfigurowane).
|
||||
- `another gateway instance is already listening` / `EADDRINUSE` → konflikt portu.
|
||||
- `Other gateway-like services detected (best effort)` → istnieją nieaktualne lub równoległe jednostki launchd/systemd/schtasks. Większość konfiguracji powinna utrzymywać jeden gateway na maszynę; jeśli rzeczywiście potrzebujesz więcej niż jednego, odizoluj porty + konfigurację/stan/workspace. Zobacz [/gateway#multiple-gateways-same-host](/pl/gateway#multiple-gateways-same-host).
|
||||
- `Other gateway-like services detected (best effort)` → istnieją nieaktualne lub równoległe jednostki launchd/systemd/schtasks. Większość konfiguracji powinna utrzymywać jeden gateway na maszynę; jeśli faktycznie potrzebujesz więcej niż jednego, odizoluj porty + konfigurację/stan/obszar roboczy. Zobacz [/gateway#multiple-gateways-same-host](/pl/gateway#multiple-gateways-same-host).
|
||||
|
||||
Powiązane:
|
||||
|
||||
@ -213,9 +264,9 @@ Powiązane:
|
||||
- [/gateway/configuration](/pl/gateway/configuration)
|
||||
- [/gateway/doctor](/pl/gateway/doctor)
|
||||
|
||||
## Ostrzeżenia probe gateway
|
||||
## Ostrzeżenia sondy gateway
|
||||
|
||||
Użyj tego, gdy `openclaw gateway probe` do czegoś dociera, ale nadal wyświetla blok ostrzeżenia.
|
||||
Użyj tego, gdy `openclaw gateway probe` dociera do celu, ale mimo to wyświetla blok ostrzeżenia.
|
||||
|
||||
```bash
|
||||
openclaw gateway probe
|
||||
@ -223,17 +274,17 @@ openclaw gateway probe --json
|
||||
openclaw gateway probe --ssh user@gateway-host
|
||||
```
|
||||
|
||||
Poszukaj:
|
||||
Szukaj:
|
||||
|
||||
- `warnings[].code` i `primaryTargetId` w wyjściu JSON.
|
||||
- Czy ostrzeżenie dotyczy zapasowej ścieżki SSH, wielu gateway, brakujących zakresów czy nierozwiązanych odwołań auth.
|
||||
- `warnings[].code` i `primaryTargetId` w danych wyjściowych JSON.
|
||||
- Czy ostrzeżenie dotyczy zapasowej ścieżki SSH, wielu gateway, brakujących zakresów, czy nierozwiązanych odwołań auth.
|
||||
|
||||
Typowe sygnatury:
|
||||
|
||||
- `SSH tunnel failed to start; falling back to direct probes.` → konfiguracja SSH nie powiodła się, ale polecenie nadal próbowało bezpośrednich skonfigurowanych/docelowych loopback.
|
||||
- `multiple reachable gateways detected` → odpowiedziało więcej niż jedno miejsce docelowe. Zwykle oznacza to zamierzoną konfigurację wielu gateway albo nieaktualne/zduplikowane listenery.
|
||||
- `Probe diagnostics are limited by gateway scopes (missing operator.read)` → połączenie działa, ale szczegóły RPC są ograniczone zakresem; sparuj tożsamość urządzenia albo użyj poświadczeń z `operator.read`.
|
||||
- nierozwiązany tekst ostrzeżenia `gateway.auth.*` / `gateway.remote.*` SecretRef → materiał auth był niedostępny w tej ścieżce polecenia dla nieudanego celu.
|
||||
- `multiple reachable gateways detected` → odpowiedział więcej niż jeden cel. Zwykle oznacza to celową konfigurację wielu gateway albo nieaktualne/zduplikowane listenery.
|
||||
- `Probe diagnostics are limited by gateway scopes (missing operator.read)` → połączenie zadziałało, ale szczegółowe RPC jest ograniczone zakresem; sparuj tożsamość urządzenia albo użyj poświadczeń z `operator.read`.
|
||||
- nierozwiązany tekst ostrzeżenia `gateway.auth.*` / `gateway.remote.*` SecretRef → materiał uwierzytelniający był niedostępny na tej ścieżce polecenia dla nieudanego celu.
|
||||
|
||||
Powiązane:
|
||||
|
||||
@ -241,9 +292,9 @@ Powiązane:
|
||||
- [/gateway#multiple-gateways-same-host](/pl/gateway#multiple-gateways-same-host)
|
||||
- [/gateway/remote](/pl/gateway/remote)
|
||||
|
||||
## Kanał jest połączony, ale wiadomości nie płyną
|
||||
## Kanał jest połączony, ale wiadomości nie przepływają
|
||||
|
||||
Jeśli stan kanału pokazuje połączenie, ale przepływ wiadomości nie działa, skup się na zasadach, uprawnieniach i regułach dostarczania specyficznych dla kanału.
|
||||
Jeśli stan kanału to connected, ale przepływ wiadomości nie działa, skup się na polityce, uprawnieniach i regułach dostarczania specyficznych dla kanału.
|
||||
|
||||
```bash
|
||||
openclaw channels status --probe
|
||||
@ -253,17 +304,17 @@ openclaw logs --follow
|
||||
openclaw config get channels
|
||||
```
|
||||
|
||||
Poszukaj:
|
||||
Szukaj:
|
||||
|
||||
- Zasad DM (`pairing`, `allowlist`, `open`, `disabled`).
|
||||
- Listy dozwolonych grup i wymagań wzmianek.
|
||||
- Polityki DM (`pairing`, `allowlist`, `open`, `disabled`).
|
||||
- Listy dozwolonych grup i wymogów wspomnienia.
|
||||
- Brakujących uprawnień/zakresów API kanału.
|
||||
|
||||
Typowe sygnatury:
|
||||
|
||||
- `mention required` → wiadomość zignorowana przez zasady wzmianek grupowych.
|
||||
- ślady `pairing` / oczekującego zatwierdzenia → nadawca nie jest zatwierdzony.
|
||||
- `missing_scope`, `not_in_channel`, `Forbidden`, `401/403` → problem z auth/uprawnieniami kanału.
|
||||
- `mention required` → wiadomość została zignorowana przez politykę wspomnień grupowych.
|
||||
- `pairing` / ślady oczekującego zatwierdzenia → nadawca nie jest zatwierdzony.
|
||||
- `missing_scope`, `not_in_channel`, `Forbidden`, `401/403` → problem z uwierzytelnianiem/uprawnieniami kanału.
|
||||
|
||||
Powiązane:
|
||||
|
||||
@ -274,7 +325,7 @@ Powiązane:
|
||||
|
||||
## Dostarczanie cron i heartbeat
|
||||
|
||||
Jeśli cron lub heartbeat nie uruchomiły się albo nic nie dostarczyły, najpierw zweryfikuj stan harmonogramu, a potem cel dostarczania.
|
||||
Jeśli cron lub heartbeat nie uruchomił się albo nie dostarczył wyniku, najpierw sprawdź stan harmonogramu, a następnie cel dostarczenia.
|
||||
|
||||
```bash
|
||||
openclaw cron status
|
||||
@ -284,21 +335,21 @@ openclaw system heartbeat last
|
||||
openclaw logs --follow
|
||||
```
|
||||
|
||||
Poszukaj:
|
||||
Szukaj:
|
||||
|
||||
- Włączonego cron i obecności następnego wybudzenia.
|
||||
- Czy cron jest włączony i czy ma zaplanowane następne wybudzenie.
|
||||
- Statusu historii uruchomień zadania (`ok`, `skipped`, `error`).
|
||||
- Powodów pominięcia heartbeat (`quiet-hours`, `requests-in-flight`, `alerts-disabled`, `empty-heartbeat-file`, `no-tasks-due`).
|
||||
|
||||
Typowe sygnatury:
|
||||
|
||||
- `cron: scheduler disabled; jobs will not run automatically` → cron wyłączony.
|
||||
- `cron: timer tick failed` → tick harmonogramu nie powiódł się; sprawdź błędy pliku/logów/runtime.
|
||||
- `cron: scheduler disabled; jobs will not run automatically` → cron jest wyłączony.
|
||||
- `cron: timer tick failed` → tyknięcie harmonogramu nie powiodło się; sprawdź błędy plików/logów/runtime.
|
||||
- `heartbeat skipped` z `reason=quiet-hours` → poza oknem aktywnych godzin.
|
||||
- `heartbeat skipped` z `reason=empty-heartbeat-file` → `HEARTBEAT.md` istnieje, ale zawiera tylko puste linie / nagłówki markdown, więc OpenClaw pomija wywołanie modelu.
|
||||
- `heartbeat skipped` z `reason=no-tasks-due` → `HEARTBEAT.md` zawiera blok `tasks:`, ale żadne zadania nie są należne przy tym ticku.
|
||||
- `heartbeat: unknown accountId` → nieprawidłowy account id dla celu dostarczania heartbeat.
|
||||
- `heartbeat skipped` z `reason=dm-blocked` → cel heartbeat został rozwiązany do miejsca docelowego w stylu DM, podczas gdy `agents.defaults.heartbeat.directPolicy` (lub nadpisanie per agent) ma wartość `block`.
|
||||
- `heartbeat skipped` z `reason=no-tasks-due` → `HEARTBEAT.md` zawiera blok `tasks:`, ale żadne zadanie nie jest wymagalne przy tym tyknięciu.
|
||||
- `heartbeat: unknown accountId` → nieprawidłowy identyfikator konta dla celu dostarczenia heartbeat.
|
||||
- `heartbeat skipped` z `reason=dm-blocked` → cel heartbeat został rozpoznany jako miejsce docelowe w stylu DM, podczas gdy `agents.defaults.heartbeat.directPolicy` (lub nadpisanie dla konkretnego agenta) ma ustawienie `block`.
|
||||
|
||||
Powiązane:
|
||||
|
||||
@ -306,7 +357,7 @@ Powiązane:
|
||||
- [/automation/cron-jobs](/pl/automation/cron-jobs)
|
||||
- [/gateway/heartbeat](/pl/gateway/heartbeat)
|
||||
|
||||
## Narzędzie sparowanego węzła nie działa
|
||||
## Narzędzie sparowanego węzła kończy się niepowodzeniem
|
||||
|
||||
Jeśli węzeł jest sparowany, ale narzędzia nie działają, odizoluj stan pierwszego planu, uprawnień i zatwierdzeń.
|
||||
|
||||
@ -318,18 +369,18 @@ openclaw logs --follow
|
||||
openclaw status
|
||||
```
|
||||
|
||||
Poszukaj:
|
||||
Szukaj:
|
||||
|
||||
- Czy węzeł jest online i ma oczekiwane możliwości.
|
||||
- Czy przyznano uprawnienia systemu operacyjnego do kamery/mikrofonu/lokalizacji/ekranu.
|
||||
- Stanu zatwierdzeń exec i listy dozwolonych.
|
||||
- Czy węzeł jest online z oczekiwanymi możliwościami.
|
||||
- Przyznanych uprawnień systemu operacyjnego do kamery/mikrofonu/lokalizacji/ekranu.
|
||||
- Stanu zatwierdzeń wykonania i listy dozwolonych.
|
||||
|
||||
Typowe sygnatury:
|
||||
|
||||
- `NODE_BACKGROUND_UNAVAILABLE` → aplikacja węzła musi być na pierwszym planie.
|
||||
- `*_PERMISSION_REQUIRED` / `LOCATION_PERMISSION_REQUIRED` → brak wymaganego uprawnienia systemowego.
|
||||
- `SYSTEM_RUN_DENIED: approval required` → oczekujące zatwierdzenie exec.
|
||||
- `SYSTEM_RUN_DENIED: allowlist miss` → polecenie zablokowane przez listę dozwolonych.
|
||||
- `*_PERMISSION_REQUIRED` / `LOCATION_PERMISSION_REQUIRED` → brak uprawnienia systemowego.
|
||||
- `SYSTEM_RUN_DENIED: approval required` → oczekuje zatwierdzenie wykonania.
|
||||
- `SYSTEM_RUN_DENIED: allowlist miss` → polecenie zostało zablokowane przez listę dozwolonych.
|
||||
|
||||
Powiązane:
|
||||
|
||||
@ -337,9 +388,9 @@ Powiązane:
|
||||
- [/nodes/index](/pl/nodes/index)
|
||||
- [/tools/exec-approvals](/pl/tools/exec-approvals)
|
||||
|
||||
## Narzędzie przeglądarki nie działa
|
||||
## Narzędzie przeglądarki kończy się niepowodzeniem
|
||||
|
||||
Użyj tego, gdy działania narzędzia przeglądarki zawodzą, mimo że sam gateway działa poprawnie.
|
||||
Użyj tego, gdy działania narzędzia przeglądarki kończą się niepowodzeniem, mimo że sam gateway działa prawidłowo.
|
||||
|
||||
```bash
|
||||
openclaw browser status
|
||||
@ -349,10 +400,10 @@ openclaw logs --follow
|
||||
openclaw doctor
|
||||
```
|
||||
|
||||
Poszukaj:
|
||||
Szukaj:
|
||||
|
||||
- Czy `plugins.allow` jest ustawione i zawiera `browser`.
|
||||
- Prawidłowej ścieżki do pliku wykonywalnego przeglądarki.
|
||||
- Prawidłowej ścieżki do wykonywalnego pliku przeglądarki.
|
||||
- Osiągalności profilu CDP.
|
||||
- Dostępności lokalnego Chrome dla profili `existing-session` / `user`.
|
||||
|
||||
@ -362,19 +413,19 @@ Typowe sygnatury:
|
||||
- brak / niedostępność narzędzia przeglądarki przy `browser.enabled=true` → `plugins.allow` wyklucza `browser`, więc plugin nigdy się nie załadował.
|
||||
- `Failed to start Chrome CDP on port` → proces przeglądarki nie uruchomił się.
|
||||
- `browser.executablePath not found` → skonfigurowana ścieżka jest nieprawidłowa.
|
||||
- `browser.cdpUrl must be http(s) or ws(s)` → skonfigurowany URL CDP używa nieobsługiwanego schematu, takiego jak `file:` lub `ftp:`.
|
||||
- `browser.cdpUrl has invalid port` → skonfigurowany URL CDP ma błędny lub spoza zakresu port.
|
||||
- `browser.cdpUrl must be http(s) or ws(s)` → skonfigurowany adres URL CDP używa nieobsługiwanego schematu, takiego jak `file:` lub `ftp:`.
|
||||
- `browser.cdpUrl has invalid port` → skonfigurowany adres URL CDP ma nieprawidłowy lub wykraczający poza zakres port.
|
||||
- `No Chrome tabs found for profile="user"` → profil dołączania Chrome MCP nie ma otwartych lokalnych kart Chrome.
|
||||
- `Remote CDP for profile "<name>" is not reachable` → skonfigurowany zdalny endpoint CDP jest nieosiągalny z hosta gateway.
|
||||
- `Browser attachOnly is enabled ... not reachable` lub `Browser attachOnly is enabled and CDP websocket ... is not reachable` → profil tylko-do-dołączenia nie ma osiągalnego celu albo endpoint HTTP odpowiedział, ale nadal nie udało się otworzyć WebSocket CDP.
|
||||
- `Playwright is not available in this gateway build; '<feature>' is unsupported.` → bieżąca instalacja gateway nie zawiera pełnego pakietu Playwright; migawki ARIA i podstawowe zrzuty ekranu strony nadal mogą działać, ale nawigacja, migawki AI, zrzuty ekranu elementów według selektorów CSS i eksport PDF pozostają niedostępne.
|
||||
- `fullPage is not supported for element screenshots` → żądanie zrzutu ekranu połączyło `--full-page` z `--ref` lub `--element`.
|
||||
- `Remote CDP for profile "<name>" is not reachable` → skonfigurowany zdalny punkt końcowy CDP nie jest osiągalny z hosta gateway.
|
||||
- `Browser attachOnly is enabled ... not reachable` lub `Browser attachOnly is enabled and CDP websocket ... is not reachable` → profil tylko dołączania nie ma osiągalnego celu albo punkt końcowy HTTP odpowiedział, ale nadal nie udało się otworzyć gniazda WebSocket CDP.
|
||||
- `Playwright is not available in this gateway build; '<feature>' is unsupported.` → bieżąca instalacja gateway nie zawiera pełnego pakietu Playwright; migawki ARIA i podstawowe zrzuty ekranu strony nadal mogą działać, ale nawigacja, migawki AI, zrzuty elementów według selektora CSS i eksport PDF pozostają niedostępne.
|
||||
- `fullPage is not supported for element screenshots` → żądanie zrzutu ekranu łączyło `--full-page` z `--ref` lub `--element`.
|
||||
- `element screenshots are not supported for existing-session profiles; use ref from snapshot.` → wywołania zrzutów ekranu Chrome MCP / `existing-session` muszą używać przechwycenia strony albo `--ref` z migawki, a nie CSS `--element`.
|
||||
- `existing-session file uploads do not support element selectors; use ref/inputRef.` → hooki przesyłania plików Chrome MCP wymagają odwołań do migawek, a nie selektorów CSS.
|
||||
- `existing-session file uploads currently support one file at a time.` → w profilach Chrome MCP wysyłaj jedno przesłanie na wywołanie.
|
||||
- `existing-session dialog handling does not support timeoutMs.` → hooki dialogów w profilach Chrome MCP nie obsługują nadpisania timeoutów.
|
||||
- `existing-session file uploads do not support element selectors; use ref/inputRef.` → haki przesyłania plików Chrome MCP wymagają odwołań do migawek, a nie selektorów CSS.
|
||||
- `existing-session file uploads currently support one file at a time.` → wysyłaj po jednym przesłaniu na wywołanie w profilach Chrome MCP.
|
||||
- `existing-session dialog handling does not support timeoutMs.` → haki okien dialogowych w profilach Chrome MCP nie obsługują nadpisywania limitu czasu.
|
||||
- `response body is not supported for existing-session profiles yet.` → `responsebody` nadal wymaga zarządzanej przeglądarki albo surowego profilu CDP.
|
||||
- nieaktualne nadpisania viewport / dark-mode / locale / offline w profilach tylko-do-dołączenia lub zdalnego CDP → uruchom `openclaw browser stop --browser-profile <name>`, aby zamknąć aktywną sesję sterowania i zwolnić stan emulacji Playwright/CDP bez restartowania całego gateway.
|
||||
- nieaktualne nadpisania viewportu / trybu ciemnego / ustawień regionalnych / trybu offline w profilach tylko dołączania lub zdalnych CDP → uruchom `openclaw browser stop --browser-profile <name>`, aby zamknąć aktywną sesję sterowania i zwolnić stan emulacji Playwright/CDP bez restartowania całego gateway.
|
||||
|
||||
Powiązane:
|
||||
|
||||
@ -383,9 +434,9 @@ Powiązane:
|
||||
|
||||
## Jeśli po aktualizacji coś nagle przestało działać
|
||||
|
||||
Większość problemów po aktualizacji wynika z rozjazdu konfiguracji albo z bardziej rygorystycznie egzekwowanych wartości domyślnych.
|
||||
Większość problemów po aktualizacji to dryf konfiguracji albo egzekwowanie bardziej rygorystycznych ustawień domyślnych.
|
||||
|
||||
### 1) Zmieniło się zachowanie auth i nadpisywania URL
|
||||
### 1) Zmieniło się zachowanie uwierzytelniania i nadpisywania URL
|
||||
|
||||
```bash
|
||||
openclaw gateway status
|
||||
@ -396,15 +447,15 @@ openclaw config get gateway.auth.mode
|
||||
|
||||
Co sprawdzić:
|
||||
|
||||
- Jeśli `gateway.mode=remote`, wywołania CLI mogą trafiać zdalnie, mimo że lokalna usługa działa poprawnie.
|
||||
- Jeśli `gateway.mode=remote`, wywołania CLI mogą trafiać do zdalnego celu, podczas gdy lokalna usługa działa poprawnie.
|
||||
- Jawne wywołania `--url` nie wracają do zapisanych poświadczeń.
|
||||
|
||||
Typowe sygnatury:
|
||||
|
||||
- `gateway connect failed:` → nieprawidłowy docelowy URL.
|
||||
- `unauthorized` → endpoint jest osiągalny, ale auth jest błędne.
|
||||
- `unauthorized` → punkt końcowy jest osiągalny, ale uwierzytelnianie jest błędne.
|
||||
|
||||
### 2) Guardraile bind i auth są bardziej rygorystyczne
|
||||
### 2) Ograniczenia dotyczące powiązań i uwierzytelniania są bardziej rygorystyczne
|
||||
|
||||
```bash
|
||||
openclaw config get gateway.bind
|
||||
@ -416,13 +467,13 @@ openclaw logs --follow
|
||||
|
||||
Co sprawdzić:
|
||||
|
||||
- Powiązania inne niż loopback (`lan`, `tailnet`, `custom`) wymagają prawidłowej ścieżki auth gateway: współdzielonego auth tokenem/hasłem albo poprawnie skonfigurowanego wdrożenia `trusted-proxy` bez loopback.
|
||||
- Powiązania inne niż loopback (`lan`, `tailnet`, `custom`) wymagają prawidłowej ścieżki uwierzytelniania gateway: współdzielonego tokena/hasła albo poprawnie skonfigurowanego wdrożenia `trusted-proxy` bez loopback.
|
||||
- Stare klucze, takie jak `gateway.token`, nie zastępują `gateway.auth.token`.
|
||||
|
||||
Typowe sygnatury:
|
||||
|
||||
- `refusing to bind gateway ... without auth` → powiązanie inne niż loopback bez prawidłowej ścieżki auth gateway.
|
||||
- `RPC probe: failed` mimo że runtime działa → gateway działa, ale jest niedostępny przy bieżącym auth/url.
|
||||
- `refusing to bind gateway ... without auth` → powiązanie inne niż loopback bez prawidłowej ścieżki uwierzytelniania gateway.
|
||||
- `RPC probe: failed` przy działającym runtime → gateway działa, ale jest niedostępny przy bieżącym auth/url.
|
||||
|
||||
### 3) Zmienił się stan parowania i tożsamości urządzenia
|
||||
|
||||
@ -435,15 +486,15 @@ openclaw doctor
|
||||
|
||||
Co sprawdzić:
|
||||
|
||||
- Oczekujące zatwierdzenia urządzeń dla dashboard/węzłów.
|
||||
- Oczekujące zatwierdzenia parowania DM po zmianach zasad lub tożsamości.
|
||||
- Oczekujące zatwierdzenia urządzeń dla dashboardu/węzłów.
|
||||
- Oczekujące zatwierdzenia parowania DM po zmianach polityki lub tożsamości.
|
||||
|
||||
Typowe sygnatury:
|
||||
|
||||
- `device identity required` → auth urządzenia nie jest spełnione.
|
||||
- `device identity required` → uwierzytelnienie urządzenia nie zostało spełnione.
|
||||
- `pairing required` → nadawca/urządzenie musi zostać zatwierdzone.
|
||||
|
||||
Jeśli po sprawdzeniu konfiguracja usługi i runtime nadal się nie zgadzają, zainstaluj ponownie metadane usługi z tego samego katalogu profilu/stanu:
|
||||
Jeśli po sprawdzeniach konfiguracja usługi i runtime nadal się różnią, zainstaluj ponownie metadane usługi z tego samego katalogu profilu/stanu:
|
||||
|
||||
```bash
|
||||
openclaw gateway install --force
|
||||
|
||||
1541
docs/pl/help/faq.md
1541
docs/pl/help/faq.md
File diff suppressed because it is too large
Load Diff
@ -1,14 +1,14 @@
|
||||
---
|
||||
read_when:
|
||||
- Uruchamiasz skrypty z repozytorium
|
||||
- Dodajesz lub zmieniasz skrypty w ./scripts
|
||||
- Uruchamianie skryptów z repozytorium
|
||||
- Dodawanie lub zmienianie skryptów w `./scripts`
|
||||
summary: 'Skrypty repozytorium: przeznaczenie, zakres i uwagi dotyczące bezpieczeństwa'
|
||||
title: Skrypty
|
||||
x-i18n:
|
||||
generated_at: "2026-04-05T13:55:11Z"
|
||||
generated_at: "2026-04-08T02:14:44Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: de53d64d91c564931bdd4e8b9f4a8e88646332a07cc2a6bf1d517b89debb29cd
|
||||
source_hash: 3ecf1e9327929948fb75f80e306963af49b353c0aa8d3b6fa532ca964ff8b975
|
||||
source_path: help/scripts.md
|
||||
workflow: 15
|
||||
---
|
||||
@ -20,15 +20,41 @@ Używaj ich, gdy zadanie jest wyraźnie powiązane ze skryptem; w przeciwnym raz
|
||||
|
||||
## Konwencje
|
||||
|
||||
- Skrypty są **opcjonalne**, chyba że są wymienione w dokumentacji lub checklistach wydań.
|
||||
- Preferuj powierzchnie CLI, jeśli istnieją (przykład: monitorowanie uwierzytelniania używa `openclaw models status --check`).
|
||||
- Zakładaj, że skrypty są zależne od hosta; przeczytaj je przed uruchomieniem na nowej maszynie.
|
||||
- Skrypty są **opcjonalne**, chyba że odwołuje się do nich dokumentacja lub checklisty wydania.
|
||||
- Preferuj powierzchnie CLI, gdy istnieją (przykład: monitorowanie uwierzytelniania używa `openclaw models status --check`).
|
||||
- Zakładaj, że skrypty są specyficzne dla hosta; przeczytaj je przed uruchomieniem na nowej maszynie.
|
||||
|
||||
## Skrypty monitorowania uwierzytelniania
|
||||
|
||||
Monitorowanie uwierzytelniania opisano w [Uwierzytelnianie](/gateway/authentication). Skrypty w `scripts/` to opcjonalne dodatki dla przepływów systemd/Termux phone.
|
||||
Monitorowanie uwierzytelniania opisano w [Uwierzytelnianie](/pl/gateway/authentication). Skrypty w `scripts/` to opcjonalne dodatki do przepływów pracy systemd/Termux na telefonie.
|
||||
|
||||
## Przy dodawaniu skryptów
|
||||
## Pomocnik odczytu GitHub
|
||||
|
||||
- Utrzymuj skrypty w skupionej formie i dobrze udokumentowane.
|
||||
- Dodaj krótki wpis w odpowiedniej dokumentacji (lub utwórz ją, jeśli brakuje).
|
||||
Użyj `scripts/gh-read`, gdy chcesz, aby `gh` używało tokenu instalacji GitHub App do wywołań odczytu ograniczonych do repozytorium, pozostawiając zwykłe `gh` na twoim osobistym loginie do działań zapisu.
|
||||
|
||||
Wymagane zmienne środowiskowe:
|
||||
|
||||
- `OPENCLAW_GH_READ_APP_ID`
|
||||
- `OPENCLAW_GH_READ_PRIVATE_KEY_FILE`
|
||||
|
||||
Opcjonalne zmienne środowiskowe:
|
||||
|
||||
- `OPENCLAW_GH_READ_INSTALLATION_ID`, gdy chcesz pominąć wyszukiwanie instalacji na podstawie repozytorium
|
||||
- `OPENCLAW_GH_READ_PERMISSIONS` jako rozdzielane przecinkami zastąpienie podzbioru uprawnień odczytu do zażądania
|
||||
|
||||
Kolejność rozwiązywania repozytorium:
|
||||
|
||||
- `gh ... -R owner/repo`
|
||||
- `GH_REPO`
|
||||
- `git remote origin`
|
||||
|
||||
Przykłady:
|
||||
|
||||
- `scripts/gh-read pr view 123`
|
||||
- `scripts/gh-read run list -R openclaw/openclaw`
|
||||
- `scripts/gh-read api repos/openclaw/openclaw/pulls/123`
|
||||
|
||||
## Podczas dodawania skryptów
|
||||
|
||||
- Zachowuj skupienie skryptów i dokumentuj je.
|
||||
- Dodaj krótki wpis w odpowiednim dokumencie (lub utwórz go, jeśli go brakuje).
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@ -1,25 +1,25 @@
|
||||
---
|
||||
read_when:
|
||||
- OpenClaw nie działa i potrzebujesz najszybszej drogi do naprawy
|
||||
- Chcesz przejść przez proces triage, zanim zagłębisz się w szczegółowe runbooki
|
||||
summary: Hub rozwiązywania problemów OpenClaw z podejściem opartym najpierw na objawach
|
||||
- OpenClaw nie działa i potrzebujesz najszybszej drogi do rozwiązania
|
||||
- Chcesz przejść przez proces triage, zanim zagłębisz się w szczegółowe instrukcje
|
||||
summary: Centrum rozwiązywania problemów OpenClaw zorientowane na objawy
|
||||
title: Ogólne rozwiązywanie problemów
|
||||
x-i18n:
|
||||
generated_at: "2026-04-05T13:56:11Z"
|
||||
generated_at: "2026-04-08T02:16:21Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 23ae9638af5edf5a5e0584ccb15ba404223ac3b16c2d62eb93b2c9dac171c252
|
||||
source_hash: 8abda90ef80234c2f91a51c5e1f2c004d4a4da12a5d5631b5927762550c6d5e3
|
||||
source_path: help/troubleshooting.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Rozwiązywanie problemów
|
||||
|
||||
Jeśli masz tylko 2 minuty, użyj tej strony jako punktu wejścia do triage.
|
||||
Jeśli masz tylko 2 minuty, potraktuj tę stronę jako punkt wejścia do triage.
|
||||
|
||||
## Pierwsze 60 sekund
|
||||
|
||||
Uruchom dokładnie tę sekwencję po kolei:
|
||||
Uruchom dokładnie tę sekwencję, po kolei:
|
||||
|
||||
```bash
|
||||
openclaw status
|
||||
@ -31,32 +31,47 @@ openclaw channels status --probe
|
||||
openclaw logs --follow
|
||||
```
|
||||
|
||||
Prawidłowy wynik w jednym wierszu:
|
||||
Prawidłowe dane wyjściowe w jednym wierszu:
|
||||
|
||||
- `openclaw status` → pokazuje skonfigurowane kanały i brak oczywistych błędów auth.
|
||||
- `openclaw status` → pokazuje skonfigurowane kanały i brak oczywistych błędów uwierzytelniania.
|
||||
- `openclaw status --all` → pełny raport jest dostępny i można go udostępnić.
|
||||
- `openclaw gateway probe` → oczekiwany cel gateway jest osiągalny (`Reachable: yes`). `RPC: limited - missing scope: operator.read` oznacza zdegradowaną diagnostykę, a nie błąd połączenia.
|
||||
- `openclaw gateway status` → `Runtime: running` oraz `RPC probe: ok`.
|
||||
- `openclaw doctor` → brak blokujących błędów config/usługi.
|
||||
- `openclaw channels status --probe` → osiągalna gateway zwraca aktywny stan transportu dla każdego konta oraz wyniki probe/audytu, takie jak `works` lub `audit ok`; jeśli gateway jest nieosiągalna, polecenie wraca do podsumowań opartych tylko na config.
|
||||
- `openclaw logs --follow` → stabilna aktywność, brak powtarzających się błędów krytycznych.
|
||||
- `openclaw gateway probe` → oczekiwany cel gateway jest osiągalny (`Reachable: yes`). `RPC: limited - missing scope: operator.read` oznacza pogorszoną diagnostykę, a nie błąd połączenia.
|
||||
- `openclaw gateway status` → `Runtime: running` i `RPC probe: ok`.
|
||||
- `openclaw doctor` → brak blokujących błędów konfiguracji/usługi.
|
||||
- `openclaw channels status --probe` → osiągalny gateway zwraca stan transportu na żywo dla każdego konta oraz wyniki probe/audytu, takie jak `works` lub `audit ok`; jeśli gateway jest nieosiągalny, polecenie wraca do podsumowań opartych wyłącznie na konfiguracji.
|
||||
- `openclaw logs --follow` → stabilna aktywność, bez powtarzających się błędów krytycznych.
|
||||
|
||||
## Anthropic long context 429
|
||||
|
||||
Jeśli widzisz:
|
||||
`HTTP 429: rate_limit_error: Extra usage is required for long context requests`,
|
||||
przejdź do [/gateway/troubleshooting#anthropic-429-extra-usage-required-for-long-context](/gateway/troubleshooting#anthropic-429-extra-usage-required-for-long-context).
|
||||
przejdź do [/gateway/troubleshooting#anthropic-429-extra-usage-required-for-long-context](/pl/gateway/troubleshooting#anthropic-429-extra-usage-required-for-long-context).
|
||||
|
||||
## Instalacja pluginu kończy się błędem z brakującymi rozszerzeniami openclaw
|
||||
## Lokalny backend zgodny z OpenAI działa bezpośrednio, ale nie działa w OpenClaw
|
||||
|
||||
Jeśli lokalny lub samodzielnie hostowany backend `/v1` odpowiada na małe bezpośrednie
|
||||
zapytania testowe `/v1/chat/completions`, ale nie działa z `openclaw infer model run` ani podczas zwykłych
|
||||
tur agenta:
|
||||
|
||||
1. Jeśli błąd wspomina o `messages[].content` oczekującym ciągu znaków, ustaw
|
||||
`models.providers.<provider>.models[].compat.requiresStringContent: true`.
|
||||
2. Jeśli backend nadal zawodzi tylko podczas tur agenta OpenClaw, ustaw
|
||||
`models.providers.<provider>.models[].compat.supportsTools: false` i spróbuj ponownie.
|
||||
3. Jeśli małe bezpośrednie wywołania nadal działają, ale większe prompty OpenClaw powodują awarię
|
||||
backendu, potraktuj pozostały problem jako ograniczenie modelu/serwera po stronie upstream i
|
||||
przejdź do szczegółowej instrukcji:
|
||||
[/gateway/troubleshooting#local-openai-compatible-backend-passes-direct-probes-but-agent-runs-fail](/pl/gateway/troubleshooting#local-openai-compatible-backend-passes-direct-probes-but-agent-runs-fail)
|
||||
|
||||
## Instalacja pluginu kończy się błędem z powodu brakujących rozszerzeń openclaw
|
||||
|
||||
Jeśli instalacja kończy się błędem `package.json missing openclaw.extensions`, pakiet pluginu
|
||||
używa starego formatu, którego OpenClaw już nie akceptuje.
|
||||
używa starej struktury, której OpenClaw już nie akceptuje.
|
||||
|
||||
Napraw w pakiecie pluginu:
|
||||
Naprawa w pakiecie pluginu:
|
||||
|
||||
1. Dodaj `openclaw.extensions` do `package.json`.
|
||||
2. Skieruj wpisy do zbudowanych plików runtime (zwykle `./dist/index.js`).
|
||||
3. Opublikuj plugin ponownie i jeszcze raz uruchom `openclaw plugins install <package>`.
|
||||
3. Opublikuj plugin ponownie i uruchom `openclaw plugins install <package>` jeszcze raz.
|
||||
|
||||
Przykład:
|
||||
|
||||
@ -70,28 +85,28 @@ Przykład:
|
||||
}
|
||||
```
|
||||
|
||||
Informacje referencyjne: [Plugin architecture](/plugins/architecture)
|
||||
Odwołanie: [Architektura pluginów](/pl/plugins/architecture)
|
||||
|
||||
## Drzewo decyzji
|
||||
## Drzewo decyzyjne
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A[OpenClaw nie działa] --> B{Co psuje się jako pierwsze}
|
||||
B --> C[Brak odpowiedzi]
|
||||
B --> D[Dashboard lub Control UI nie może się połączyć]
|
||||
B --> D[Dashboard lub Control UI nie łączy się]
|
||||
B --> E[Gateway nie uruchamia się lub usługa nie działa]
|
||||
B --> F[Kanał łączy się, ale wiadomości nie przepływają]
|
||||
B --> G[Cron lub heartbeat nie uruchomił się albo nie dostarczył]
|
||||
B --> H[Node jest sparowany, ale camera canvas screen exec kończy się błędem]
|
||||
B --> I[Narzędzie browser nie działa]
|
||||
B --> H[Node jest sparowany, ale camera canvas screen exec nie działa]
|
||||
B --> I[Narzędzie przeglądarki nie działa]
|
||||
|
||||
C --> C1[/Sekcja Brak odpowiedzi/]
|
||||
D --> D1[/Sekcja Control UI/]
|
||||
E --> E1[/Sekcja Gateway/]
|
||||
F --> F1[/Sekcja przepływu kanału/]
|
||||
G --> G1[/Sekcja automatyzacji/]
|
||||
H --> H1[/Sekcja narzędzi node/]
|
||||
I --> I1[/Sekcja Browser/]
|
||||
F --> F1[/Sekcja Przepływ kanału/]
|
||||
G --> G1[/Sekcja Automatyzacja/]
|
||||
H --> H1[/Sekcja Narzędzia node/]
|
||||
I --> I1[/Sekcja Przeglądarka/]
|
||||
```
|
||||
|
||||
<AccordionGroup>
|
||||
@ -104,28 +119,28 @@ flowchart TD
|
||||
openclaw logs --follow
|
||||
```
|
||||
|
||||
Prawidłowy wynik wygląda tak:
|
||||
Prawidłowe dane wyjściowe wyglądają tak:
|
||||
|
||||
- `Runtime: running`
|
||||
- `RPC probe: ok`
|
||||
- Twój kanał pokazuje połączony transport i, tam gdzie jest to obsługiwane, `works` lub `audit ok` w `channels status --probe`
|
||||
- Nadawca widnieje jako zatwierdzony (lub polityka DM jest otwarta/allowlist)
|
||||
- Twój kanał pokazuje podłączony transport oraz, jeśli jest obsługiwane, `works` lub `audit ok` w `channels status --probe`
|
||||
- Nadawca jest zatwierdzony (lub polityka DM jest otwarta/lista dozwolonych)
|
||||
|
||||
Typowe sygnatury w logach:
|
||||
Typowe sygnatury logów:
|
||||
|
||||
- `drop guild message (mention required` → bramka mention zablokowała wiadomość w Discord.
|
||||
- `pairing request` → nadawca nie jest zatwierdzony i czeka na zatwierdzenie parowania DM.
|
||||
- `drop guild message (mention required` → bramka wzmianek zablokowała wiadomość w Discord.
|
||||
- `pairing request` → nadawca jest niezatwierdzony i czeka na zgodę sparowania DM.
|
||||
- `blocked` / `allowlist` w logach kanału → nadawca, pokój lub grupa są filtrowane.
|
||||
|
||||
Szczegółowe strony:
|
||||
|
||||
- [/gateway/troubleshooting#no-replies](/gateway/troubleshooting#no-replies)
|
||||
- [/gateway/troubleshooting#no-replies](/pl/gateway/troubleshooting#no-replies)
|
||||
- [/channels/troubleshooting](/pl/channels/troubleshooting)
|
||||
- [/channels/pairing](/pl/channels/pairing)
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Dashboard lub Control UI nie może się połączyć">
|
||||
<Accordion title="Dashboard lub Control UI nie łączy się">
|
||||
```bash
|
||||
openclaw status
|
||||
openclaw gateway status
|
||||
@ -134,30 +149,28 @@ flowchart TD
|
||||
openclaw channels status --probe
|
||||
```
|
||||
|
||||
Prawidłowy wynik wygląda tak:
|
||||
Prawidłowe dane wyjściowe wyglądają tak:
|
||||
|
||||
- `Dashboard: http://...` jest pokazywane w `openclaw gateway status`
|
||||
- `Dashboard: http://...` jest pokazane w `openclaw gateway status`
|
||||
- `RPC probe: ok`
|
||||
- Brak pętli auth w logach
|
||||
- Brak pętli uwierzytelniania w logach
|
||||
|
||||
Typowe sygnatury w logach:
|
||||
Typowe sygnatury logów:
|
||||
|
||||
- `device identity required` → kontekst HTTP/niebezpieczny nie może zakończyć auth urządzenia.
|
||||
- `origin not allowed` → `Origin` przeglądarki nie jest dozwolony dla celu gateway w Control UI.
|
||||
- `AUTH_TOKEN_MISMATCH` ze wskazówkami ponowienia (`canRetryWithDeviceToken=true`) → może automatycznie wystąpić jedna zaufana próba ponowienia z tokenem urządzenia.
|
||||
- To ponowienie z tokenem z cache używa ponownie zestawu zakresów z cache zapisanego wraz z tokenem sparowanego urządzenia. Wywołujący z jawnym `deviceToken` / jawnymi `scopes` zachowują zamiast tego żądany zestaw zakresów.
|
||||
- W asynchronicznej ścieżce Tailscale Serve Control UI nieudane próby dla tego samego
|
||||
`{scope, ip}` są serializowane, zanim limiter zapisze porażkę, więc
|
||||
druga równoległa zła próba może już pokazać `retry later`.
|
||||
- `too many failed authentication attempts (retry later)` z originu przeglądarki localhost → powtarzane błędy z tego samego `Origin` są tymczasowo blokowane; inny origin localhost używa osobnego bucketu.
|
||||
- powtarzające się `unauthorized` po tym ponowieniu → zły token/hasło, niedopasowanie trybu auth albo nieaktualny token sparowanego urządzenia.
|
||||
- `gateway connect failed:` → UI celuje w zły URL/port albo nieosiągalną gateway.
|
||||
- `device identity required` → kontekst HTTP/niezabezpieczony nie może ukończyć uwierzytelniania urządzenia.
|
||||
- `origin not allowed` → przeglądarkowy `Origin` nie jest dozwolony dla celu gateway Control UI.
|
||||
- `AUTH_TOKEN_MISMATCH` z podpowiedziami ponownej próby (`canRetryWithDeviceToken=true`) → może automatycznie wystąpić jedna ponowna próba z zaufanym tokenem urządzenia.
|
||||
- Ta ponowna próba z pamięci podręcznej ponownie używa zestawu scope z pamięci podręcznej zapisanego razem ze sparowanym tokenem urządzenia. Wywołania z jawnym `deviceToken` / jawnymi `scopes` zachowują zamiast tego żądany zestaw scope.
|
||||
- W asynchronicznej ścieżce Tailscale Serve dla Control UI nieudane próby dla tego samego `{scope, ip}` są serializowane, zanim ogranicznik zarejestruje niepowodzenie, więc druga równoległa błędna ponowna próba może już zwrócić `retry later`.
|
||||
- `too many failed authentication attempts (retry later)` z pochodzenia przeglądarki localhost → powtarzające się niepowodzenia z tego samego `Origin` są tymczasowo blokowane; inne pochodzenie localhost używa osobnego bucketu.
|
||||
- powtarzające się `unauthorized` po tej ponownej próbie → błędny token/hasło, niedopasowanie trybu uwierzytelniania lub nieaktualny sparowany token urządzenia.
|
||||
- `gateway connect failed:` → UI kieruje do błędnego URL/portu lub do nieosiągalnego gateway.
|
||||
|
||||
Szczegółowe strony:
|
||||
|
||||
- [/gateway/troubleshooting#dashboard-control-ui-connectivity](/gateway/troubleshooting#dashboard-control-ui-connectivity)
|
||||
- [/gateway/troubleshooting#dashboard-control-ui-connectivity](/pl/gateway/troubleshooting#dashboard-control-ui-connectivity)
|
||||
- [/web/control-ui](/web/control-ui)
|
||||
- [/gateway/authentication](/gateway/authentication)
|
||||
- [/gateway/authentication](/pl/gateway/authentication)
|
||||
|
||||
</Accordion>
|
||||
|
||||
@ -170,23 +183,23 @@ flowchart TD
|
||||
openclaw channels status --probe
|
||||
```
|
||||
|
||||
Prawidłowy wynik wygląda tak:
|
||||
Prawidłowe dane wyjściowe wyglądają tak:
|
||||
|
||||
- `Service: ... (loaded)`
|
||||
- `Runtime: running`
|
||||
- `RPC probe: ok`
|
||||
|
||||
Typowe sygnatury w logach:
|
||||
Typowe sygnatury logów:
|
||||
|
||||
- `Gateway start blocked: set gateway.mode=local` lub `existing config is missing gateway.mode` → tryb gateway to remote albo w pliku config brakuje stempla trybu lokalnego i należy go naprawić.
|
||||
- `refusing to bind gateway ... without auth` → powiązanie inne niż loopback bez prawidłowej ścieżki auth gateway (token/hasło lub trusted-proxy, jeśli skonfigurowano).
|
||||
- `Gateway start blocked: set gateway.mode=local` lub `existing config is missing gateway.mode` → tryb gateway jest zdalny albo w pliku konfiguracji brakuje oznaczenia trybu lokalnego i należy go naprawić.
|
||||
- `refusing to bind gateway ... without auth` → powiązanie spoza loopback bez prawidłowej ścieżki uwierzytelniania gateway (token/hasło lub trusted-proxy, jeśli skonfigurowano).
|
||||
- `another gateway instance is already listening` lub `EADDRINUSE` → port jest już zajęty.
|
||||
|
||||
Szczegółowe strony:
|
||||
|
||||
- [/gateway/troubleshooting#gateway-service-not-running](/gateway/troubleshooting#gateway-service-not-running)
|
||||
- [/gateway/background-process](/gateway/background-process)
|
||||
- [/gateway/configuration](/gateway/configuration)
|
||||
- [/gateway/troubleshooting#gateway-service-not-running](/pl/gateway/troubleshooting#gateway-service-not-running)
|
||||
- [/gateway/background-process](/pl/gateway/background-process)
|
||||
- [/gateway/configuration](/pl/gateway/configuration)
|
||||
|
||||
</Accordion>
|
||||
|
||||
@ -199,21 +212,21 @@ flowchart TD
|
||||
openclaw channels status --probe
|
||||
```
|
||||
|
||||
Prawidłowy wynik wygląda tak:
|
||||
Prawidłowe dane wyjściowe wyglądają tak:
|
||||
|
||||
- Transport kanału jest połączony.
|
||||
- Kontrole pairing/allowlist przechodzą pomyślnie.
|
||||
- Wymagane mentions są wykrywane.
|
||||
- Wzmianki są wykrywane tam, gdzie jest to wymagane.
|
||||
|
||||
Typowe sygnatury w logach:
|
||||
Typowe sygnatury logów:
|
||||
|
||||
- `mention required` → bramka mention w grupie zablokowała przetwarzanie.
|
||||
- `pairing` / `pending` → nadawca DM nie został jeszcze zatwierdzony.
|
||||
- `mention required` → bramka wzmianek grupowych zablokowała przetwarzanie.
|
||||
- `pairing` / `pending` → nadawca DM nie jest jeszcze zatwierdzony.
|
||||
- `not_in_channel`, `missing_scope`, `Forbidden`, `401/403` → problem z tokenem uprawnień kanału.
|
||||
|
||||
Szczegółowe strony:
|
||||
|
||||
- [/gateway/troubleshooting#channel-connected-messages-not-flowing](/gateway/troubleshooting#channel-connected-messages-not-flowing)
|
||||
- [/gateway/troubleshooting#channel-connected-messages-not-flowing](/pl/gateway/troubleshooting#channel-connected-messages-not-flowing)
|
||||
- [/channels/troubleshooting](/pl/channels/troubleshooting)
|
||||
|
||||
</Accordion>
|
||||
@ -228,30 +241,30 @@ flowchart TD
|
||||
openclaw logs --follow
|
||||
```
|
||||
|
||||
Prawidłowy wynik wygląda tak:
|
||||
Prawidłowe dane wyjściowe wyglądają tak:
|
||||
|
||||
- `cron.status` pokazuje włączony stan i następne wybudzenie.
|
||||
- `cron.status` pokazuje, że jest włączony i ma następne wybudzenie.
|
||||
- `cron runs` pokazuje ostatnie wpisy `ok`.
|
||||
- Heartbeat jest włączony i nie znajduje się poza godzinami aktywności.
|
||||
- Heartbeat jest włączony i nie znajduje się poza aktywnymi godzinami.
|
||||
|
||||
Typowe sygnatury w logach:
|
||||
Typowe sygnatury logów:
|
||||
|
||||
- `cron: scheduler disabled; jobs will not run automatically` → cron jest wyłączony.
|
||||
- `heartbeat skipped` z `reason=quiet-hours` → poza skonfigurowanymi godzinami aktywności.
|
||||
- `heartbeat skipped` z `reason=empty-heartbeat-file` → `HEARTBEAT.md` istnieje, ale zawiera tylko pusty/szablonowy nagłówek.
|
||||
- `heartbeat skipped` z `reason=no-tasks-due` → aktywny jest tryb zadań `HEARTBEAT.md`, ale żaden z interwałów zadań nie jest jeszcze należny.
|
||||
- `heartbeat skipped` z `reason=alerts-disabled` → cała widoczność heartbeat jest wyłączona (`showOk`, `showAlerts` i `useIndicator` są wszystkie wyłączone).
|
||||
- `requests-in-flight` → pas main jest zajęty; wybudzenie heartbeat zostało odroczone. - `unknown accountId` → docelowe konto dostarczania heartbeat nie istnieje.
|
||||
- `heartbeat skipped` z `reason=quiet-hours` → poza skonfigurowanymi aktywnymi godzinami.
|
||||
- `heartbeat skipped` z `reason=empty-heartbeat-file` → `HEARTBEAT.md` istnieje, ale zawiera tylko puste/nagłówkowe szkielety.
|
||||
- `heartbeat skipped` z `reason=no-tasks-due` → tryb zadań `HEARTBEAT.md` jest aktywny, ale żaden z interwałów zadań nie jest jeszcze należny.
|
||||
- `heartbeat skipped` z `reason=alerts-disabled` → cała widoczność heartbeat jest wyłączona (`showOk`, `showAlerts` i `useIndicator` są wyłączone).
|
||||
- `requests-in-flight` → główna ścieżka jest zajęta; wybudzenie heartbeat zostało odroczone. - `unknown accountId` → docelowe konto dostarczania heartbeat nie istnieje.
|
||||
|
||||
Szczegółowe strony:
|
||||
|
||||
- [/gateway/troubleshooting#cron-and-heartbeat-delivery](/gateway/troubleshooting#cron-and-heartbeat-delivery)
|
||||
- [/gateway/troubleshooting#cron-and-heartbeat-delivery](/pl/gateway/troubleshooting#cron-and-heartbeat-delivery)
|
||||
- [/automation/cron-jobs#troubleshooting](/pl/automation/cron-jobs#troubleshooting)
|
||||
- [/gateway/heartbeat](/gateway/heartbeat)
|
||||
- [/gateway/heartbeat](/pl/gateway/heartbeat)
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Node jest sparowany, ale narzędzie camera canvas screen exec kończy się błędem">
|
||||
<Accordion title="Node jest sparowany, ale narzędzie camera canvas screen exec nie działa">
|
||||
```bash
|
||||
openclaw status
|
||||
openclaw gateway status
|
||||
@ -260,24 +273,24 @@ flowchart TD
|
||||
openclaw logs --follow
|
||||
```
|
||||
|
||||
Prawidłowy wynik wygląda tak:
|
||||
Prawidłowe dane wyjściowe wyglądają tak:
|
||||
|
||||
- Node jest pokazany jako połączony i sparowany dla roli `node`.
|
||||
- Możliwość istnieje dla polecenia, które wywołujesz.
|
||||
- Node jest wymieniony jako połączony i sparowany dla roli `node`.
|
||||
- Dla wywoływanego polecenia istnieje capability.
|
||||
- Stan uprawnień jest przyznany dla narzędzia.
|
||||
|
||||
Typowe sygnatury w logach:
|
||||
Typowe sygnatury logów:
|
||||
|
||||
- `NODE_BACKGROUND_UNAVAILABLE` → przenieś aplikację node na pierwszy plan.
|
||||
- `*_PERMISSION_REQUIRED` → uprawnienie systemowe zostało odrzucone lub go brakuje.
|
||||
- `SYSTEM_RUN_DENIED: approval required` → zatwierdzenie exec oczekuje.
|
||||
- `SYSTEM_RUN_DENIED: allowlist miss` → polecenia nie ma na allowlist exec.
|
||||
- `*_PERMISSION_REQUIRED` → uprawnienie systemowe zostało odrzucone lub nie istnieje.
|
||||
- `SYSTEM_RUN_DENIED: approval required` → oczekuje zatwierdzenie exec.
|
||||
- `SYSTEM_RUN_DENIED: allowlist miss` → polecenia nie ma na liście dozwolonych exec.
|
||||
|
||||
Szczegółowe strony:
|
||||
|
||||
- [/gateway/troubleshooting#node-paired-tool-fails](/gateway/troubleshooting#node-paired-tool-fails)
|
||||
- [/nodes/troubleshooting](/nodes/troubleshooting)
|
||||
- [/tools/exec-approvals](/tools/exec-approvals)
|
||||
- [/gateway/troubleshooting#node-paired-tool-fails](/pl/gateway/troubleshooting#node-paired-tool-fails)
|
||||
- [/nodes/troubleshooting](/pl/nodes/troubleshooting)
|
||||
- [/tools/exec-approvals](/pl/tools/exec-approvals)
|
||||
|
||||
</Accordion>
|
||||
|
||||
@ -291,14 +304,14 @@ flowchart TD
|
||||
|
||||
Co się zmieniło:
|
||||
|
||||
- Jeśli `tools.exec.host` nie jest ustawione, domyślna wartość to `auto`.
|
||||
- `host=auto` rozwiązuje się do `sandbox`, gdy aktywny jest runtime sandboxa, a w przeciwnym razie do `gateway`.
|
||||
- `host=auto` dotyczy tylko routingu; zachowanie „YOLO” bez pytań wynika z `security=full` plus `ask=off` na gateway/node.
|
||||
- Dla `gateway` i `node` nieustawione `tools.exec.security` domyślnie przyjmuje `full`.
|
||||
- Nieustawione `tools.exec.ask` domyślnie przyjmuje `off`.
|
||||
- Wynik: jeśli widzisz zatwierdzenia, jakaś lokalna dla hosta lub sesji polityka zaostrzyła exec w stosunku do bieżących ustawień domyślnych.
|
||||
- Jeśli `tools.exec.host` nie jest ustawione, wartością domyślną jest `auto`.
|
||||
- `host=auto` rozstrzyga się do `sandbox`, gdy aktywne jest środowisko sandbox, w przeciwnym razie do `gateway`.
|
||||
- `host=auto` dotyczy tylko routingu; zachowanie „YOLO” bez promptu wynika z `security=full` oraz `ask=off` na gateway/node.
|
||||
- W `gateway` i `node` nieustawione `tools.exec.security` domyślnie przyjmuje wartość `full`.
|
||||
- Nieustawione `tools.exec.ask` domyślnie przyjmuje wartość `off`.
|
||||
- Wniosek: jeśli widzisz zatwierdzenia, jakaś lokalna dla hosta lub dla sesji polityka zaostrzyła exec względem obecnych wartości domyślnych.
|
||||
|
||||
Przywróć bieżące domyślne zachowanie bez zatwierdzeń:
|
||||
Przywróć obecne domyślne zachowanie bez zatwierdzeń:
|
||||
|
||||
```bash
|
||||
openclaw config set tools.exec.host gateway
|
||||
@ -310,24 +323,24 @@ flowchart TD
|
||||
Bezpieczniejsze alternatywy:
|
||||
|
||||
- Ustaw tylko `tools.exec.host=gateway`, jeśli chcesz po prostu stabilnego routingu hosta.
|
||||
- Użyj `security=allowlist` z `ask=on-miss`, jeśli chcesz exec na hoście, ale nadal chcesz przeglądu przy trafieniu poza allowlist.
|
||||
- Włącz tryb sandbox, jeśli chcesz, aby `host=auto` znów rozwiązywał się do `sandbox`.
|
||||
- Użyj `security=allowlist` z `ask=on-miss`, jeśli chcesz exec na hoście, ale nadal chcesz przeglądu przy chybieniach allowlist.
|
||||
- Włącz tryb sandbox, jeśli chcesz, aby `host=auto` znowu rozstrzygał się do `sandbox`.
|
||||
|
||||
Typowe sygnatury w logach:
|
||||
Typowe sygnatury logów:
|
||||
|
||||
- `Approval required.` → polecenie czeka na `/approve ...`.
|
||||
- `SYSTEM_RUN_DENIED: approval required` → zatwierdzenie exec dla hosta node oczekuje.
|
||||
- `exec host=sandbox requires a sandbox runtime for this session` → niejawny/jawny wybór sandboxa, ale tryb sandbox jest wyłączony.
|
||||
- `SYSTEM_RUN_DENIED: approval required` → oczekuje zatwierdzenie exec na hoście node.
|
||||
- `exec host=sandbox requires a sandbox runtime for this session` → niejawny/jawny wybór sandbox, ale tryb sandbox jest wyłączony.
|
||||
|
||||
Szczegółowe strony:
|
||||
|
||||
- [/tools/exec](/tools/exec)
|
||||
- [/tools/exec-approvals](/tools/exec-approvals)
|
||||
- [/gateway/security#runtime-expectation-drift](/gateway/security#runtime-expectation-drift)
|
||||
- [/tools/exec](/pl/tools/exec)
|
||||
- [/tools/exec-approvals](/pl/tools/exec-approvals)
|
||||
- [/gateway/security#runtime-expectation-drift](/pl/gateway/security#runtime-expectation-drift)
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Narzędzie browser nie działa">
|
||||
<Accordion title="Narzędzie przeglądarki nie działa">
|
||||
```bash
|
||||
openclaw status
|
||||
openclaw gateway status
|
||||
@ -336,37 +349,37 @@ flowchart TD
|
||||
openclaw doctor
|
||||
```
|
||||
|
||||
Prawidłowy wynik wygląda tak:
|
||||
Prawidłowe dane wyjściowe wyglądają tak:
|
||||
|
||||
- Status browser pokazuje `running: true` oraz wybraną przeglądarkę/profil.
|
||||
- `openclaw` uruchamia się, albo `user` widzi lokalne karty Chrome.
|
||||
- Status przeglądarki pokazuje `running: true` oraz wybraną przeglądarkę/profil.
|
||||
- `openclaw` uruchamia się lub `user` widzi lokalne karty Chrome.
|
||||
|
||||
Typowe sygnatury w logach:
|
||||
Typowe sygnatury logów:
|
||||
|
||||
- `unknown command "browser"` lub `unknown command 'browser'` → ustawiono `plugins.allow` i nie zawiera ono `browser`.
|
||||
- `Failed to start Chrome CDP on port` → nie udało się uruchomić lokalnej przeglądarki.
|
||||
- `browser.executablePath not found` → skonfigurowana ścieżka binarki jest błędna.
|
||||
- `browser.executablePath not found` → skonfigurowana ścieżka do pliku binarnego jest błędna.
|
||||
- `browser.cdpUrl must be http(s) or ws(s)` → skonfigurowany URL CDP używa nieobsługiwanego schematu.
|
||||
- `browser.cdpUrl has invalid port` → skonfigurowany URL CDP ma błędny lub spoza zakresu port.
|
||||
- `No Chrome tabs found for profile="user"` → profil attach Chrome MCP nie ma otwartych lokalnych kart Chrome.
|
||||
- `browser.cdpUrl has invalid port` → skonfigurowany URL CDP ma nieprawidłowy port lub port spoza zakresu.
|
||||
- `No Chrome tabs found for profile="user"` → profil dołączania Chrome MCP nie ma otwartych lokalnych kart Chrome.
|
||||
- `Remote CDP for profile "<name>" is not reachable` → skonfigurowany zdalny endpoint CDP jest nieosiągalny z tego hosta.
|
||||
- `Browser attachOnly is enabled ... not reachable` lub `Browser attachOnly is enabled and CDP websocket ... is not reachable` → profil tylko dołączania nie ma aktywnego celu CDP.
|
||||
- nieaktualne nadpisania viewport / dark-mode / locale / offline na profilach attach-only lub remote CDP → uruchom `openclaw browser stop --browser-profile <name>`, aby zamknąć aktywną sesję sterowania i zwolnić stan emulacji bez restartu gateway.
|
||||
- `Browser attachOnly is enabled ... not reachable` lub `Browser attachOnly is enabled and CDP websocket ... is not reachable` → profil tylko-dołączania nie ma aktywnego celu CDP.
|
||||
- nieaktualne nadpisania viewport / dark-mode / locale / offline w profilach tylko-dołączania lub zdalnego CDP → uruchom `openclaw browser stop --browser-profile <name>`, aby zamknąć aktywną sesję sterowania i zwolnić stan emulacji bez restartowania gateway.
|
||||
|
||||
Szczegółowe strony:
|
||||
|
||||
- [/gateway/troubleshooting#browser-tool-fails](/gateway/troubleshooting#browser-tool-fails)
|
||||
- [/tools/browser#missing-browser-command-or-tool](/tools/browser#missing-browser-command-or-tool)
|
||||
- [/tools/browser-linux-troubleshooting](/tools/browser-linux-troubleshooting)
|
||||
- [/tools/browser-wsl2-windows-remote-cdp-troubleshooting](/tools/browser-wsl2-windows-remote-cdp-troubleshooting)
|
||||
- [/gateway/troubleshooting#browser-tool-fails](/pl/gateway/troubleshooting#browser-tool-fails)
|
||||
- [/tools/browser#missing-browser-command-or-tool](/pl/tools/browser#missing-browser-command-or-tool)
|
||||
- [/tools/browser-linux-troubleshooting](/pl/tools/browser-linux-troubleshooting)
|
||||
- [/tools/browser-wsl2-windows-remote-cdp-troubleshooting](/pl/tools/browser-wsl2-windows-remote-cdp-troubleshooting)
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## Powiązane
|
||||
|
||||
- [FAQ](/help/faq) — często zadawane pytania
|
||||
- [Gateway Troubleshooting](/gateway/troubleshooting) — problemy specyficzne dla gateway
|
||||
- [Doctor](/gateway/doctor) — automatyczne kontrole kondycji i naprawy
|
||||
- [Channel Troubleshooting](/pl/channels/troubleshooting) — problemy z łącznością kanałów
|
||||
- [Automation Troubleshooting](/pl/automation/cron-jobs#troubleshooting) — problemy z cron i heartbeat
|
||||
- [FAQ](/pl/help/faq) — często zadawane pytania
|
||||
- [Rozwiązywanie problemów z Gateway](/pl/gateway/troubleshooting) — problemy specyficzne dla gateway
|
||||
- [Doctor](/pl/gateway/doctor) — zautomatyzowane kontrole kondycji i naprawy
|
||||
- [Rozwiązywanie problemów z kanałami](/pl/channels/troubleshooting) — problemy z łącznością kanałów
|
||||
- [Rozwiązywanie problemów z automatyzacją](/pl/automation/cron-jobs#troubleshooting) — problemy z cron i heartbeat
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@ -7,131 +7,147 @@ sidebarTitle: Channel Plugins
|
||||
summary: Przewodnik krok po kroku po tworzeniu pluginu kanału wiadomości dla OpenClaw
|
||||
title: Tworzenie pluginów kanałów
|
||||
x-i18n:
|
||||
generated_at: "2026-04-07T09:47:54Z"
|
||||
generated_at: "2026-04-08T02:17:00Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 0aab6cc835b292c62e33c52ad0c35f989fb1a5b225511e8bdc2972feb3c64f09
|
||||
source_hash: d23365b6d92006b30e671f9f0afdba40a2b88c845c5d2299d71c52a52985672f
|
||||
source_path: plugins/sdk-channel-plugins.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Tworzenie pluginów kanałów
|
||||
|
||||
Ten przewodnik prowadzi krok po kroku przez tworzenie pluginu kanału, który łączy OpenClaw z
|
||||
Ten przewodnik pokazuje, jak zbudować plugin kanału, który łączy OpenClaw z
|
||||
platformą komunikacyjną. Na końcu będziesz mieć działający kanał z zabezpieczeniami DM,
|
||||
parowaniem, wątkowaniem odpowiedzi i wiadomościami wychodzącymi.
|
||||
parowaniem, wątkowaniem odpowiedzi i wysyłaniem wiadomości wychodzących.
|
||||
|
||||
<Info>
|
||||
Jeśli nie tworzono wcześniej żadnego pluginu OpenClaw, najpierw przeczytaj
|
||||
[Getting Started](/pl/plugins/building-plugins), aby poznać podstawową strukturę
|
||||
Jeśli nie tworzyłeś wcześniej żadnego pluginu OpenClaw, najpierw przeczytaj
|
||||
[Pierwsze kroki](/pl/plugins/building-plugins), aby poznać podstawową strukturę
|
||||
pakietu i konfigurację manifestu.
|
||||
</Info>
|
||||
|
||||
## Jak działają pluginy kanałów
|
||||
|
||||
Pluginy kanałów nie potrzebują własnych narzędzi send/edit/react. OpenClaw utrzymuje jedno
|
||||
wspólne narzędzie `message` w core. Plugin zarządza:
|
||||
Pluginy kanałów nie potrzebują własnych narzędzi do wysyłania/edycji/reakcji. OpenClaw utrzymuje
|
||||
jedno współdzielone narzędzie `message` w rdzeniu. Twój plugin odpowiada za:
|
||||
|
||||
- **Config** — rozwiązywaniem kont i kreatorem konfiguracji
|
||||
- **Security** — polityką DM i allowlistami
|
||||
- **Pairing** — przepływem zatwierdzania DM
|
||||
- **Session grammar** — tym, jak identyfikatory rozmów specyficzne dla providera mapują się na czaty bazowe, identyfikatory wątków i fallbacki do elementów nadrzędnych
|
||||
- **Outbound** — wysyłaniem tekstu, mediów i ankiet na platformę
|
||||
- **Threading** — sposobem wątkowania odpowiedzi
|
||||
- **Konfigurację** — rozwiązywanie kont i kreator konfiguracji
|
||||
- **Bezpieczeństwo** — politykę DM i listy dozwolonych
|
||||
- **Parowanie** — przepływ zatwierdzania DM
|
||||
- **Gramatykę sesji** — sposób, w jaki identyfikatory rozmów specyficzne dla dostawcy mapują się na bazowe czaty, identyfikatory wątków i zapasowe relacje nadrzędne
|
||||
- **Ruch wychodzący** — wysyłanie tekstu, multimediów i ankiet na platformę
|
||||
- **Wątkowanie** — sposób wątkowania odpowiedzi
|
||||
|
||||
Core zarządza wspólnym narzędziem wiadomości, okablowaniem promptów, zewnętrznym kształtem klucza sesji,
|
||||
ogólnym bookkeepingiem `:thread:` i dispatch.
|
||||
Rdzeń odpowiada za współdzielone narzędzie wiadomości, połączenia promptów, zewnętrzny kształt klucza sesji,
|
||||
ogólne prowadzenie ewidencji `:thread:` oraz dispatch.
|
||||
|
||||
Jeśli platforma przechowuje dodatkowy zakres wewnątrz identyfikatorów rozmów, utrzymuj to parsowanie
|
||||
w pluginie za pomocą `messaging.resolveSessionConversation(...)`. To jest
|
||||
Jeśli Twoja platforma przechowuje dodatkowy zakres w identyfikatorach rozmów, zachowaj to parsowanie
|
||||
w pluginie przy użyciu `messaging.resolveSessionConversation(...)`. To jest
|
||||
kanoniczny hook do mapowania `rawId` na bazowy identyfikator rozmowy, opcjonalny identyfikator wątku,
|
||||
jawny `baseConversationId` oraz wszelkie `parentConversationCandidates`.
|
||||
Gdy zwracasz `parentConversationCandidates`, zachowuj kolejność od
|
||||
najwęższego elementu nadrzędnego do najszerszej/bazowej rozmowy.
|
||||
jawny `baseConversationId` oraz ewentualne `parentConversationCandidates`.
|
||||
Gdy zwracasz `parentConversationCandidates`, zachowaj ich kolejność od
|
||||
najwęższego nadrzędnego do najszerszej/bazowej rozmowy.
|
||||
|
||||
Dołączone pluginy, które potrzebują tego samego parsowania przed uruchomieniem rejestru kanałów,
|
||||
mogą też udostępniać plik najwyższego poziomu `session-key-api.ts` z pasującym
|
||||
eksportem `resolveSessionConversation(...)`. Core używa tej bezpiecznej przy bootstrapie powierzchni
|
||||
tylko wtedy, gdy rejestr pluginów runtime nie jest jeszcze dostępny.
|
||||
Bundled plugins, które potrzebują tego samego parsowania przed uruchomieniem rejestru kanałów,
|
||||
mogą również udostępniać plik najwyższego poziomu `session-key-api.ts` z pasującym
|
||||
eksportem `resolveSessionConversation(...)`. Rdzeń używa tej bezpiecznej dla bootstrap powierzchni
|
||||
tylko wtedy, gdy rejestr pluginów środowiska wykonawczego nie jest jeszcze dostępny.
|
||||
|
||||
`messaging.resolveParentConversationCandidates(...)` pozostaje dostępne jako
|
||||
starszy fallback zgodności, gdy plugin potrzebuje tylko fallbacków elementów nadrzędnych
|
||||
ponad ogólnym/surowym identyfikatorem. Jeśli istnieją oba hooki, core używa najpierw
|
||||
`resolveSessionConversation(...).parentConversationCandidates` i wraca do
|
||||
`resolveParentConversationCandidates(...)` tylko wtedy, gdy kanoniczny hook
|
||||
ich nie poda.
|
||||
`messaging.resolveParentConversationCandidates(...)` nadal pozostaje dostępne jako
|
||||
starszy zapasowy mechanizm zgodności, gdy plugin potrzebuje tylko zapasowych relacji nadrzędnych
|
||||
na bazie ogólnego/surowego identyfikatora. Jeśli istnieją oba hooki, rdzeń używa najpierw
|
||||
`resolveSessionConversation(...).parentConversationCandidates` i przechodzi do
|
||||
`resolveParentConversationCandidates(...)` tylko wtedy, gdy hook kanoniczny ich
|
||||
nie zwraca.
|
||||
|
||||
## Zatwierdzenia i możliwości kanału
|
||||
## Zatwierdzenia i możliwości kanałów
|
||||
|
||||
Większość pluginów kanałów nie potrzebuje kodu specyficznego dla zatwierdzeń.
|
||||
|
||||
- Core zarządza `/approve` w tym samym czacie, współdzielonymi payloadami przycisków zatwierdzania oraz ogólnym dostarczaniem fallback.
|
||||
- Preferuj jeden obiekt `approvalCapability` na pluginie kanału, gdy kanał potrzebuje zachowania specyficznego dla zatwierdzeń.
|
||||
- `approvalCapability.authorizeActorAction` i `approvalCapability.getActionAvailabilityState` to kanoniczna szczelina autoryzacji zatwierdzeń.
|
||||
- Jeśli kanał udostępnia natywne zatwierdzenia exec, zaimplementuj `approvalCapability.getActionAvailabilityState` nawet wtedy, gdy natywny transport znajduje się całkowicie pod `approvalCapability.native`. Core używa tego hooka dostępności, aby odróżnić `enabled` od `disabled`, zdecydować, czy kanał inicjujący obsługuje natywne zatwierdzenia, oraz uwzględnić kanał w wskazówkach fallback dla klientów natywnych.
|
||||
- Używaj `outbound.shouldSuppressLocalPayloadPrompt` lub `outbound.beforeDeliverPayload` dla zachowań cyklu życia payloadu specyficznych dla kanału, takich jak ukrywanie zduplikowanych lokalnych promptów zatwierdzania lub wysyłanie wskaźników pisania przed dostarczeniem.
|
||||
- Używaj `approvalCapability.delivery` tylko do natywnego routowania zatwierdzeń lub wyciszania fallbacku.
|
||||
- Używaj `approvalCapability.render` tylko wtedy, gdy kanał naprawdę potrzebuje niestandardowych payloadów zatwierdzeń zamiast współdzielonego renderera.
|
||||
- Używaj `approvalCapability.describeExecApprovalSetup`, gdy kanał chce, aby odpowiedź na ścieżce wyłączonej wyjaśniała dokładne klucze configu potrzebne do włączenia natywnych zatwierdzeń exec. Hook otrzymuje `{ channel, channelLabel, accountId }`; kanały z nazwanymi kontami powinny renderować ścieżki z zakresem konta, takie jak `channels.<channel>.accounts.<id>.execApprovals.*`, zamiast domyślnych ścieżek najwyższego poziomu.
|
||||
- Jeśli kanał potrafi wywnioskować stabilne tożsamości DM podobne do właściciela na podstawie istniejącego configu, użyj `createResolvedApproverActionAuthAdapter` z `openclaw/plugin-sdk/approval-runtime`, aby ograniczyć `/approve` w tym samym czacie bez dodawania logiki specyficznej dla zatwierdzeń w core.
|
||||
- Jeśli kanał potrzebuje natywnego dostarczania zatwierdzeń, utrzymuj kod kanału skoncentrowany na normalizacji targetu i hookach transportowych. Użyj `createChannelExecApprovalProfile`, `createChannelNativeOriginTargetResolver`, `createChannelApproverDmTargetResolver`, `createApproverRestrictedNativeApprovalCapability` oraz `createChannelNativeApprovalRuntime` z `openclaw/plugin-sdk/approval-runtime`, aby core zarządzał filtrowaniem żądań, routowaniem, deduplikacją, wygasaniem i subskrypcją gateway.
|
||||
- Natywne kanały zatwierdzeń muszą routować zarówno `accountId`, jak i `approvalKind` przez te helpery. `accountId` utrzymuje zakres polityki zatwierdzeń dla wielu kont powiązany z właściwym kontem bota, a `approvalKind` utrzymuje zachowanie exec vs plugin dostępne dla kanału bez hardcoded branchy w core.
|
||||
- Zachowuj dostarczony rodzaj identyfikatora zatwierdzenia end-to-end. Klienci natywni nie powinni
|
||||
zgadywać ani przepisywać routowania zatwierdzeń exec vs plugin na podstawie lokalnego stanu kanału.
|
||||
- Różne rodzaje zatwierdzeń mogą celowo udostępniać różne natywne powierzchnie.
|
||||
Bieżące dołączone przykłady:
|
||||
- Slack zachowuje natywne routowanie zatwierdzeń dostępne zarówno dla identyfikatorów exec, jak i plugin.
|
||||
- Matrix zachowuje natywne routowanie DM/kanału tylko dla zatwierdzeń exec i pozostawia
|
||||
zatwierdzenia pluginów na współdzielonej ścieżce `/approve` w tym samym czacie.
|
||||
- Rdzeń odpowiada za `/approve` w tym samym czacie, współdzielone ładunki przycisków zatwierdzeń i ogólne zapasowe dostarczanie.
|
||||
- Preferuj pojedynczy obiekt `approvalCapability` w pluginie kanału, gdy kanał potrzebuje zachowania specyficznego dla zatwierdzeń.
|
||||
- `ChannelPlugin.approvals` zostało usunięte. Umieszczaj fakty dotyczące dostarczania/natywnego renderowania/uwierzytelniania zatwierdzeń w `approvalCapability`.
|
||||
- `plugin.auth` służy tylko do logowania/wylogowania; rdzeń nie odczytuje już z tego obiektu hooków uwierzytelniania zatwierdzeń.
|
||||
- `approvalCapability.authorizeActorAction` i `approvalCapability.getActionAvailabilityState` to kanoniczna powierzchnia dla uwierzytelniania zatwierdzeń.
|
||||
- Używaj `approvalCapability.getActionAvailabilityState` dla dostępności uwierzytelniania zatwierdzeń w tym samym czacie.
|
||||
- Jeśli Twój kanał udostępnia natywne zatwierdzenia exec, użyj `approvalCapability.getExecInitiatingSurfaceState` dla stanu powierzchni inicjującej/klienta natywnego, gdy różni się on od uwierzytelniania zatwierdzeń w tym samym czacie. Rdzeń używa tego hooka specyficznego dla exec, aby rozróżniać `enabled` i `disabled`, zdecydować, czy kanał inicjujący obsługuje natywne zatwierdzenia exec, oraz uwzględnić kanał we wskazówkach zapasowych dla klientów natywnych. `createApproverRestrictedNativeApprovalCapability(...)` uzupełnia to dla typowego przypadku.
|
||||
- Używaj `outbound.shouldSuppressLocalPayloadPrompt` lub `outbound.beforeDeliverPayload` dla zachowań cyklu życia ładunku specyficznych dla kanału, takich jak ukrywanie zduplikowanych lokalnych promptów zatwierdzeń albo wysyłanie wskaźników pisania przed dostarczeniem.
|
||||
- Używaj `approvalCapability.delivery` tylko do natywnego routingu zatwierdzeń albo wyłączania routingu zapasowego.
|
||||
- Używaj `approvalCapability.nativeRuntime` do faktów o natywnych zatwierdzeniach należących do kanału. Utrzymuj go jako leniwy w gorących punktach wejścia kanału za pomocą `createLazyChannelApprovalNativeRuntimeAdapter(...)`, który może importować moduł runtime na żądanie, a jednocześnie pozwalać rdzeniowi składać cykl życia zatwierdzeń.
|
||||
- Używaj `approvalCapability.render` tylko wtedy, gdy kanał naprawdę potrzebuje własnych ładunków zatwierdzeń zamiast współdzielonego renderer.
|
||||
- Używaj `approvalCapability.describeExecApprovalSetup`, gdy kanał chce, aby odpowiedź dla ścieżki wyłączonej wyjaśniała dokładnie, jakie przełączniki konfiguracji są potrzebne do włączenia natywnych zatwierdzeń exec. Hook otrzymuje `{ channel, channelLabel, accountId }`; kanały z nazwanymi kontami powinny renderować ścieżki ograniczone do konta, takie jak `channels.<channel>.accounts.<id>.execApprovals.*`, zamiast domyślnych ustawień najwyższego poziomu.
|
||||
- Jeśli kanał może wywnioskować stabilne, podobne do właściciela tożsamości DM z istniejącej konfiguracji, użyj `createResolvedApproverActionAuthAdapter` z `openclaw/plugin-sdk/approval-runtime`, aby ograniczyć `/approve` w tym samym czacie bez dodawania logiki specyficznej dla zatwierdzeń do rdzenia.
|
||||
- Jeśli kanał potrzebuje natywnego dostarczania zatwierdzeń, utrzymuj kod kanału skupiony na normalizacji celu oraz faktach transportu/prezentacji. Użyj `createChannelExecApprovalProfile`, `createChannelNativeOriginTargetResolver`, `createChannelApproverDmTargetResolver` i `createApproverRestrictedNativeApprovalCapability` z `openclaw/plugin-sdk/approval-runtime`. Umieść fakty specyficzne dla kanału za `approvalCapability.nativeRuntime`, najlepiej przez `createChannelApprovalNativeRuntimeAdapter(...)` lub `createLazyChannelApprovalNativeRuntimeAdapter(...)`, aby rdzeń mógł złożyć handler i przejąć filtrowanie żądań, routing, deduplikację, wygasanie, subskrypcję gateway oraz komunikaty o przekierowaniu gdzie indziej. `nativeRuntime` jest podzielone na kilka mniejszych powierzchni:
|
||||
- `availability` — czy konto jest skonfigurowane i czy żądanie powinno zostać obsłużone
|
||||
- `presentation` — mapowanie współdzielonego view model zatwierdzeń na natywne ładunki oczekujące/rozwiązane/wygasłe lub końcowe akcje
|
||||
- `transport` — przygotowanie celów oraz wysyłanie/aktualizowanie/usuwanie natywnych wiadomości zatwierdzeń
|
||||
- `interactions` — opcjonalne hooki bind/unbind/clear-action dla natywnych przycisków lub reakcji
|
||||
- `observe` — opcjonalne hooki diagnostyki dostarczania
|
||||
- Jeśli kanał potrzebuje obiektów należących do runtime, takich jak klient, token, aplikacja Bolt lub odbiornik webhooków, zarejestruj je przez `openclaw/plugin-sdk/channel-runtime-context`. Ogólny rejestr kontekstu runtime pozwala rdzeniowi bootstrapować handlery oparte na możliwościach ze stanu uruchomienia kanału bez dodawania glue wrapperów specyficznych dla zatwierdzeń.
|
||||
- Sięgaj po niższopoziomowe `createChannelApprovalHandler` lub `createChannelNativeApprovalRuntime` tylko wtedy, gdy powierzchnia oparta na możliwościach nie jest jeszcze wystarczająco wyrażalna.
|
||||
- Kanały z natywnymi zatwierdzeniami muszą przekazywać zarówno `accountId`, jak i `approvalKind` przez te helpery. `accountId` utrzymuje politykę zatwierdzeń dla wielu kont w odpowiednim zakresie konta bota, a `approvalKind` utrzymuje zachowanie zatwierdzeń exec vs plugin dostępne dla kanału bez zakodowanych na sztywno rozgałęzień w rdzeniu.
|
||||
- Rdzeń odpowiada teraz także za komunikaty o przekierowaniu zatwierdzeń. Pluginy kanałów nie powinny wysyłać własnych wiadomości uzupełniających typu „zatwierdzenie trafiło do DM / innego kanału” z `createChannelNativeApprovalRuntime`; zamiast tego należy udostępnić poprawny routing źródła + DM zatwierdzającego przez współdzielone helpery możliwości zatwierdzeń i pozwolić rdzeniowi agregować rzeczywiste dostarczenia przed opublikowaniem jakiegokolwiek komunikatu z powrotem do czatu inicjującego.
|
||||
- Zachowuj rodzaj identyfikatora dostarczonego zatwierdzenia od początku do końca. Klienci natywni nie powinni
|
||||
zgadywać ani przepisywać routingu zatwierdzeń exec vs plugin na podstawie lokalnego stanu kanału.
|
||||
- Różne rodzaje zatwierdzeń mogą celowo udostępniać różne powierzchnie natywne.
|
||||
Aktualne przykłady bundled:
|
||||
- Slack utrzymuje dostępność natywnego routingu zatwierdzeń zarówno dla identyfikatorów exec, jak i plugin.
|
||||
- Matrix zachowuje ten sam natywny routing DM/kanału i UX oparty na reakcjach dla zatwierdzeń exec
|
||||
i plugin, jednocześnie nadal pozwalając, aby uwierzytelnianie różniło się w zależności od rodzaju zatwierdzenia.
|
||||
- `createApproverRestrictedNativeApprovalAdapter` nadal istnieje jako wrapper zgodności, ale nowy kod powinien preferować builder możliwości i udostępniać `approvalCapability` w pluginie.
|
||||
|
||||
Dla gorących entrypointów kanału preferuj węższe subścieżki runtime, gdy potrzebna
|
||||
jest tylko jedna część tej rodziny:
|
||||
Dla gorących punktów wejścia kanału preferuj węższe podścieżki runtime, gdy potrzebujesz tylko
|
||||
jednej części tej rodziny:
|
||||
|
||||
- `openclaw/plugin-sdk/approval-auth-runtime`
|
||||
- `openclaw/plugin-sdk/approval-client-runtime`
|
||||
- `openclaw/plugin-sdk/approval-delivery-runtime`
|
||||
- `openclaw/plugin-sdk/approval-gateway-runtime`
|
||||
- `openclaw/plugin-sdk/approval-handler-adapter-runtime`
|
||||
- `openclaw/plugin-sdk/approval-handler-runtime`
|
||||
- `openclaw/plugin-sdk/approval-native-runtime`
|
||||
- `openclaw/plugin-sdk/approval-reply-runtime`
|
||||
- `openclaw/plugin-sdk/channel-runtime-context`
|
||||
|
||||
Podobnie preferuj `openclaw/plugin-sdk/setup-runtime`,
|
||||
`openclaw/plugin-sdk/setup-adapter-runtime`,
|
||||
`openclaw/plugin-sdk/reply-runtime`,
|
||||
`openclaw/plugin-sdk/reply-dispatch-runtime`,
|
||||
`openclaw/plugin-sdk/reply-reference` oraz
|
||||
`openclaw/plugin-sdk/reply-chunking`, gdy nie potrzebujesz szerszej
|
||||
powierzchni parasolowej.
|
||||
`openclaw/plugin-sdk/reply-chunking`, gdy nie potrzebujesz szerszej,
|
||||
zbiorczej powierzchni.
|
||||
|
||||
Konkretnie dla setupu:
|
||||
W przypadku konfiguracji w szczególności:
|
||||
|
||||
- `openclaw/plugin-sdk/setup-runtime` obejmuje bezpieczne dla runtime helpery setupu:
|
||||
bezpieczne importowo adaptery patchowania setupu (`createPatchedAccountSetupAdapter`,
|
||||
- `openclaw/plugin-sdk/setup-runtime` obejmuje bezpieczne dla runtime helpery konfiguracji:
|
||||
bezpieczne przy importowaniu adaptery łatania konfiguracji (`createPatchedAccountSetupAdapter`,
|
||||
`createEnvPatchedAccountSetupAdapter`,
|
||||
`createSetupInputPresenceValidator`), wyjście lookup-note,
|
||||
`promptResolvedAllowFrom`, `splitSetupEntries` oraz delegowane
|
||||
buildery setup-proxy
|
||||
- `openclaw/plugin-sdk/setup-adapter-runtime` to wąska, świadoma env
|
||||
szczelina adaptera dla `createEnvPatchedAccountSetupAdapter`
|
||||
- `openclaw/plugin-sdk/channel-setup` obejmuje buildery setupu dla opcjonalnej instalacji
|
||||
oraz kilka prymitywów bezpiecznych dla setupu:
|
||||
`createSetupInputPresenceValidator`), wyjście notatek wyszukiwania,
|
||||
`promptResolvedAllowFrom`, `splitSetupEntries` oraz buildery
|
||||
setup-proxy delegowanych
|
||||
- `openclaw/plugin-sdk/setup-adapter-runtime` to wąska, świadoma środowiska powierzchnia adaptera
|
||||
dla `createEnvPatchedAccountSetupAdapter`
|
||||
- `openclaw/plugin-sdk/channel-setup` obejmuje buildery konfiguracji z opcjonalną instalacją
|
||||
oraz kilka prymitywów bezpiecznych dla konfiguracji:
|
||||
`createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`,
|
||||
|
||||
Jeśli kanał obsługuje setup lub auth sterowane env i ogólne przepływy startup/config
|
||||
mają znać te nazwy env przed załadowaniem runtime, zadeklaruj je w
|
||||
manifeście pluginu za pomocą `channelEnvVars`. Zachowaj runtime `envVars` kanału
|
||||
lub lokalne stałe tylko do kopii operator-facing.
|
||||
Jeśli Twój kanał obsługuje konfigurację lub uwierzytelnianie sterowane zmiennymi środowiskowymi i ogólne
|
||||
przepływy uruchamiania/konfiguracji powinny znać nazwy tych zmiennych przed załadowaniem runtime, zadeklaruj je w
|
||||
manifeście pluginu przy użyciu `channelEnvVars`. Zachowaj kanałowe `envVars` runtime lub lokalne
|
||||
stałe tylko dla tekstów skierowanych do operatora.
|
||||
`createOptionalChannelSetupWizard`, `DEFAULT_ACCOUNT_ID`,
|
||||
`createTopLevelChannelDmPolicy`, `setSetupChannelEnabled` oraz
|
||||
`splitSetupEntries`
|
||||
|
||||
- używaj szerszej szczeliny `openclaw/plugin-sdk/setup` tylko wtedy, gdy potrzebujesz też
|
||||
cięższych współdzielonych helperów setup/config, takich jak
|
||||
- używaj szerszej powierzchni `openclaw/plugin-sdk/setup` tylko wtedy, gdy potrzebujesz również
|
||||
cięższych współdzielonych helperów konfiguracji, takich jak
|
||||
`moveSingleAccountChannelSectionToDefaultAccount(...)`
|
||||
|
||||
Jeśli kanał chce tylko informować w powierzchniach setupu „najpierw zainstaluj ten plugin”, preferuj `createOptionalChannelSetupSurface(...)`. Wygenerowany
|
||||
adapter/kreator domyślnie blokuje zapisy do configu i finalizację oraz ponownie używa
|
||||
tego samego komunikatu „wymagana instalacja” w walidacji, finalizacji i tekście
|
||||
odnośników do dokumentacji.
|
||||
Jeśli Twój kanał chce jedynie reklamować w powierzchniach konfiguracji komunikat „najpierw zainstaluj ten plugin”,
|
||||
preferuj `createOptionalChannelSetupSurface(...)`. Wygenerowany
|
||||
adapter/kreator domyślnie odmawia zapisu konfiguracji i finalizacji oraz ponownie wykorzystuje
|
||||
ten sam komunikat o wymaganej instalacji w walidacji, finalizacji i tekstach z linkami do dokumentacji.
|
||||
|
||||
Dla innych gorących ścieżek kanału preferuj wąskie helpery zamiast szerszych starszych
|
||||
powierzchni:
|
||||
@ -139,55 +155,53 @@ powierzchni:
|
||||
- `openclaw/plugin-sdk/account-core`,
|
||||
`openclaw/plugin-sdk/account-id`,
|
||||
`openclaw/plugin-sdk/account-resolution` oraz
|
||||
`openclaw/plugin-sdk/account-helpers` dla configu wielu kont i
|
||||
fallbacku konta domyślnego
|
||||
`openclaw/plugin-sdk/account-helpers` dla konfiguracji wielu kont i
|
||||
zapasowego użycia konta domyślnego
|
||||
- `openclaw/plugin-sdk/inbound-envelope` oraz
|
||||
`openclaw/plugin-sdk/inbound-reply-dispatch` dla okablowania trasy/koperty przychodzącej i
|
||||
record-and-dispatch
|
||||
- `openclaw/plugin-sdk/messaging-targets` dla parsowania/dopasowywania targetów
|
||||
`openclaw/plugin-sdk/inbound-reply-dispatch` dla routingu/koperty wejściowej i
|
||||
połączenia record-and-dispatch
|
||||
- `openclaw/plugin-sdk/messaging-targets` dla parsowania/dopasowywania celów
|
||||
- `openclaw/plugin-sdk/outbound-media` oraz
|
||||
`openclaw/plugin-sdk/outbound-runtime` dla ładowania mediów oraz delegatów tożsamości/wysyłania
|
||||
`openclaw/plugin-sdk/outbound-runtime` dla ładowania multimediów oraz delegatów tożsamości/wysyłania
|
||||
wychodzącego
|
||||
- `openclaw/plugin-sdk/thread-bindings-runtime` dla cyklu życia
|
||||
powiązań wątków i rejestracji adapterów
|
||||
- `openclaw/plugin-sdk/agent-media-payload` tylko wtedy, gdy nadal wymagany
|
||||
jest starszy układ pól payloadu agent/media
|
||||
- `openclaw/plugin-sdk/telegram-command-config` dla normalizacji niestandardowych poleceń Telegram,
|
||||
walidacji duplikatów/konfliktów oraz kontraktu configu poleceń
|
||||
stabilnego względem fallbacku
|
||||
- `openclaw/plugin-sdk/thread-bindings-runtime` dla cyklu życia powiązań wątków
|
||||
i rejestracji adapterów
|
||||
- `openclaw/plugin-sdk/agent-media-payload` tylko wtedy, gdy nadal wymagany jest
|
||||
starszy układ pól ładunku agent/media
|
||||
- `openclaw/plugin-sdk/telegram-command-config` dla normalizacji niestandardowych poleceń Telegram, walidacji duplikatów/konfliktów oraz stabilnego w razie fallback kontraktu konfiguracji poleceń
|
||||
|
||||
Kanały tylko-auth zwykle mogą zatrzymać się na ścieżce domyślnej: core obsługuje zatwierdzenia, a plugin jedynie udostępnia możliwości outbound/auth. Kanały z natywnymi zatwierdzeniami, takie jak Matrix, Slack, Telegram i niestandardowe transporty czatu, powinny używać współdzielonych helperów natywnych zamiast pisać własny cykl życia zatwierdzeń.
|
||||
Kanały wyłącznie uwierzytelniające zwykle mogą zakończyć na ścieżce domyślnej: rdzeń obsługuje zatwierdzenia, a plugin po prostu udostępnia możliwości outbound/auth. Kanały z natywnymi zatwierdzeniami, takie jak Matrix, Slack, Telegram oraz niestandardowe transporty czatu, powinny używać współdzielonych helperów natywnych zamiast implementować własny cykl życia zatwierdzeń.
|
||||
|
||||
## Polityka wzmianek przychodzących
|
||||
## Polityka wzmianek przy wiadomościach przychodzących
|
||||
|
||||
Obsługę przychodzących wzmianek utrzymuj rozdzieloną na dwie warstwy:
|
||||
Zachowaj obsługę przychodzących wzmianek rozdzieloną na dwie warstwy:
|
||||
|
||||
- gromadzenie dowodów po stronie pluginu
|
||||
- współdzieloną ocenę polityki
|
||||
- gromadzenie danych należące do pluginu
|
||||
- współdzielona ewaluacja polityki
|
||||
|
||||
Do warstwy współdzielonej używaj `openclaw/plugin-sdk/channel-inbound`.
|
||||
Dla warstwy współdzielonej używaj `openclaw/plugin-sdk/channel-inbound`.
|
||||
|
||||
Dobre zastosowania logiki lokalnej dla pluginu:
|
||||
Dobre dopasowanie do logiki lokalnej pluginu:
|
||||
|
||||
- wykrywanie odpowiedzi do bota
|
||||
- wykrywanie cytatu bota
|
||||
- sprawdzanie udziału w wątku
|
||||
- wykluczanie komunikatów usługowych/systemowych
|
||||
- cache specyficzne dla platformy potrzebne do wykazania udziału bota
|
||||
- sprawdzanie uczestnictwa wątku
|
||||
- wykluczanie wiadomości usługowych/systemowych
|
||||
- natywne dla platformy pamięci podręczne potrzebne do potwierdzenia udziału bota
|
||||
|
||||
Dobre zastosowania helpera współdzielonego:
|
||||
Dobre dopasowanie do helpera współdzielonego:
|
||||
|
||||
- `requireMention`
|
||||
- wynik jawnej wzmianki
|
||||
- allowlista niejawnych wzmianek
|
||||
- obejście poleceń
|
||||
- końcowa decyzja o pominięciu
|
||||
- jawny wynik wzmianki
|
||||
- lista dozwolonych niejawnych wzmianek
|
||||
- obejście dla poleceń
|
||||
- ostateczna decyzja o pominięciu
|
||||
|
||||
Preferowany przepływ:
|
||||
|
||||
1. Oblicz lokalne fakty dotyczące wzmianek.
|
||||
2. Przekaż te fakty do `resolveInboundMentionDecision({ facts, policy })`.
|
||||
3. Użyj `decision.effectiveWasMentioned`, `decision.shouldBypassMention` oraz `decision.shouldSkip` w bramce przychodzącej.
|
||||
3. Użyj `decision.effectiveWasMentioned`, `decision.shouldBypassMention` i `decision.shouldSkip` w bramce wiadomości przychodzących.
|
||||
|
||||
```typescript
|
||||
import {
|
||||
@ -227,7 +241,7 @@ if (decision.shouldSkip) return;
|
||||
```
|
||||
|
||||
`api.runtime.channel.mentions` udostępnia te same współdzielone helpery wzmianek dla
|
||||
dołączonych pluginów kanałów, które już zależą od wstrzykiwania runtime:
|
||||
bundled plugins kanałów, które już zależą od wstrzykiwania runtime:
|
||||
|
||||
- `buildMentionRegexes`
|
||||
- `matchesMentionPatterns`
|
||||
@ -236,17 +250,17 @@ dołączonych pluginów kanałów, które już zależą od wstrzykiwania runtime
|
||||
- `resolveInboundMentionDecision`
|
||||
|
||||
Starsze helpery `resolveMentionGating*` pozostają w
|
||||
`openclaw/plugin-sdk/channel-inbound` tylko jako eksporty zgodności. Nowy kod
|
||||
`openclaw/plugin-sdk/channel-inbound` wyłącznie jako eksporty zgodności. Nowy kod
|
||||
powinien używać `resolveInboundMentionDecision({ facts, policy })`.
|
||||
|
||||
## Instrukcja krok po kroku
|
||||
## Przewodnik krok po kroku
|
||||
|
||||
<Steps>
|
||||
<a id="step-1-package-and-manifest"></a>
|
||||
<Step title="Pakiet i manifest">
|
||||
Utwórz standardowe pliki pluginu. Pole `channel` w `package.json`
|
||||
sprawia, że jest to plugin kanału. Pełny zakres metadanych pakietu
|
||||
znajdziesz w [Plugin Setup and Config](/pl/plugins/sdk-setup#openclawchannel):
|
||||
sprawia, że jest to plugin kanału. Pełny zakres metadanych pakietu znajdziesz
|
||||
w [Konfiguracja pluginu i konfiguracja](/pl/plugins/sdk-setup#openclawchannel):
|
||||
|
||||
<CodeGroup>
|
||||
```json package.json
|
||||
@ -260,7 +274,7 @@ powinien używać `resolveInboundMentionDecision({ facts, policy })`.
|
||||
"channel": {
|
||||
"id": "acme-chat",
|
||||
"label": "Acme Chat",
|
||||
"blurb": "Połącz OpenClaw z Acme Chat."
|
||||
"blurb": "Connect OpenClaw to Acme Chat."
|
||||
}
|
||||
}
|
||||
}
|
||||
@ -272,7 +286,7 @@ powinien używać `resolveInboundMentionDecision({ facts, policy })`.
|
||||
"kind": "channel",
|
||||
"channels": ["acme-chat"],
|
||||
"name": "Acme Chat",
|
||||
"description": "Plugin kanału Acme Chat",
|
||||
"description": "Acme Chat channel plugin",
|
||||
"configSchema": {
|
||||
"type": "object",
|
||||
"additionalProperties": false,
|
||||
@ -307,7 +321,7 @@ powinien używać `resolveInboundMentionDecision({ facts, policy })`.
|
||||
createChannelPluginBase,
|
||||
} from "openclaw/plugin-sdk/channel-core";
|
||||
import type { OpenClawConfig } from "openclaw/plugin-sdk/channel-core";
|
||||
import { acmeChatApi } from "./client.js"; // klient API twojej platformy
|
||||
import { acmeChatApi } from "./client.js"; // your platform API client
|
||||
|
||||
type ResolvedAccount = {
|
||||
accountId: string | null;
|
||||
@ -348,7 +362,7 @@ powinien używać `resolveInboundMentionDecision({ facts, policy })`.
|
||||
},
|
||||
}),
|
||||
|
||||
// Zabezpieczenia DM: kto może pisać do bota
|
||||
// DM security: who can message the bot
|
||||
security: {
|
||||
dm: {
|
||||
channelKey: "acme-chat",
|
||||
@ -358,21 +372,21 @@ powinien używać `resolveInboundMentionDecision({ facts, policy })`.
|
||||
},
|
||||
},
|
||||
|
||||
// Pairing: przepływ zatwierdzania dla nowych kontaktów DM
|
||||
// Pairing: approval flow for new DM contacts
|
||||
pairing: {
|
||||
text: {
|
||||
idLabel: "Nazwa użytkownika Acme Chat",
|
||||
message: "Wyślij ten kod, aby zweryfikować swoją tożsamość:",
|
||||
idLabel: "Acme Chat username",
|
||||
message: "Send this code to verify your identity:",
|
||||
notify: async ({ target, code }) => {
|
||||
await acmeChatApi.sendDm(target, `Pairing code: ${code}`);
|
||||
},
|
||||
},
|
||||
},
|
||||
|
||||
// Wątkowanie: jak dostarczane są odpowiedzi
|
||||
// Threading: how replies are delivered
|
||||
threading: { topLevelReplyToMode: "reply" },
|
||||
|
||||
// Outbound: wysyłanie wiadomości na platformę
|
||||
// Outbound: send messages to the platform
|
||||
outbound: {
|
||||
attachedResults: {
|
||||
sendText: async (params) => {
|
||||
@ -392,16 +406,16 @@ powinien używać `resolveInboundMentionDecision({ facts, policy })`.
|
||||
});
|
||||
```
|
||||
|
||||
<Accordion title="Co daje createChatChannelPlugin">
|
||||
<Accordion title="Co robi za Ciebie createChatChannelPlugin">
|
||||
Zamiast ręcznie implementować niskopoziomowe interfejsy adapterów,
|
||||
przekazujesz deklaratywne opcje, a builder składa je razem:
|
||||
przekazujesz deklaratywne opcje, a builder je składa:
|
||||
|
||||
| Option | Co jest podłączane |
|
||||
| Opcja | Co jest podłączane |
|
||||
| --- | --- |
|
||||
| `security.dm` | Resolver zabezpieczeń DM z zakresem opartym na polach configu |
|
||||
| `pairing.text` | Tekstowy przepływ pairing DM z wymianą kodów |
|
||||
| `threading` | Resolver trybu reply-to (stały, z zakresem konta lub niestandardowy) |
|
||||
| `outbound.attachedResults` | Funkcje wysyłania zwracające metadane wyniku (ID wiadomości) |
|
||||
| `security.dm` | Resolver zabezpieczeń DM ograniczony do pól konfiguracji |
|
||||
| `pairing.text` | Tekstowy przepływ parowania DM z wymianą kodów |
|
||||
| `threading` | Resolver trybu odpowiedzi (stały, ograniczony do konta lub niestandardowy) |
|
||||
| `outbound.attachedResults` | Funkcje wysyłania zwracające metadane wyniku (identyfikatory wiadomości) |
|
||||
|
||||
Możesz też przekazać surowe obiekty adapterów zamiast opcji deklaratywnych,
|
||||
jeśli potrzebujesz pełnej kontroli.
|
||||
@ -409,7 +423,7 @@ powinien używać `resolveInboundMentionDecision({ facts, policy })`.
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Podłącz entry point">
|
||||
<Step title="Podłącz punkt wejścia">
|
||||
Utwórz `index.ts`:
|
||||
|
||||
```typescript index.ts
|
||||
@ -419,20 +433,20 @@ powinien używać `resolveInboundMentionDecision({ facts, policy })`.
|
||||
export default defineChannelPluginEntry({
|
||||
id: "acme-chat",
|
||||
name: "Acme Chat",
|
||||
description: "Plugin kanału Acme Chat",
|
||||
description: "Acme Chat channel plugin",
|
||||
plugin: acmeChatPlugin,
|
||||
registerCliMetadata(api) {
|
||||
api.registerCli(
|
||||
({ program }) => {
|
||||
program
|
||||
.command("acme-chat")
|
||||
.description("Zarządzanie Acme Chat");
|
||||
.description("Acme Chat management");
|
||||
},
|
||||
{
|
||||
descriptors: [
|
||||
{
|
||||
name: "acme-chat",
|
||||
description: "Zarządzanie Acme Chat",
|
||||
description: "Acme Chat management",
|
||||
hasSubcommands: false,
|
||||
},
|
||||
],
|
||||
@ -446,20 +460,20 @@ powinien używać `resolveInboundMentionDecision({ facts, policy })`.
|
||||
```
|
||||
|
||||
Umieszczaj deskryptory CLI należące do kanału w `registerCliMetadata(...)`, aby OpenClaw
|
||||
mógł je pokazać w głównej pomocy bez aktywowania pełnego runtime kanału,
|
||||
a zwykłe pełne ładowanie nadal pobierało te same deskryptory do rzeczywistej
|
||||
rejestracji poleceń. Zachowaj `registerFull(...)` dla pracy tylko runtime.
|
||||
Jeśli `registerFull(...)` rejestruje metody gateway RPC, użyj
|
||||
prefiksu specyficznego dla pluginu. Przestrzenie nazw administratora core (`config.*`,
|
||||
`exec.approvals.*`, `wizard.*`, `update.*`) pozostają zarezerwowane i zawsze
|
||||
rozwiązują się do `operator.admin`.
|
||||
`defineChannelPluginEntry` automatycznie obsługuje ten podział trybów rejestracji. Zobacz
|
||||
[Entry Points](/pl/plugins/sdk-entrypoints#definechannelpluginentry), aby poznać wszystkie
|
||||
mógł pokazywać je w głównej pomocy bez aktywowania pełnego runtime kanału,
|
||||
podczas gdy zwykłe pełne ładowania nadal pobierają te same deskryptory do rzeczywistej rejestracji
|
||||
poleceń. Zachowaj `registerFull(...)` do pracy tylko w runtime.
|
||||
Jeśli `registerFull(...)` rejestruje metody Gateway RPC, używaj
|
||||
prefiksu specyficznego dla pluginu. Przestrzenie nazw administratora rdzenia (`config.*`,
|
||||
`exec.approvals.*`, `wizard.*`, `update.*`) pozostają zastrzeżone i zawsze
|
||||
są mapowane na `operator.admin`.
|
||||
`defineChannelPluginEntry` automatycznie obsługuje podział trybów rejestracji. Zobacz
|
||||
[Punkty wejścia](/pl/plugins/sdk-entrypoints#definechannelpluginentry), aby poznać wszystkie
|
||||
opcje.
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Dodaj setup entry">
|
||||
<Step title="Dodaj wpis konfiguracji">
|
||||
Utwórz `setup-entry.ts` do lekkiego ładowania podczas onboardingu:
|
||||
|
||||
```typescript setup-entry.ts
|
||||
@ -469,28 +483,28 @@ powinien używać `resolveInboundMentionDecision({ facts, policy })`.
|
||||
export default defineSetupPluginEntry(acmeChatPlugin);
|
||||
```
|
||||
|
||||
OpenClaw ładuje ten plik zamiast pełnego entry, gdy kanał jest wyłączony
|
||||
albo nieskonfigurowany. Pozwala to uniknąć wciągania ciężkiego kodu runtime podczas przepływów setupu.
|
||||
Szczegóły znajdziesz w [Setup and Config](/pl/plugins/sdk-setup#setup-entry).
|
||||
OpenClaw ładuje to zamiast pełnego punktu wejścia, gdy kanał jest wyłączony
|
||||
lub nieskonfigurowany. Pozwala to uniknąć wciągania ciężkiego kodu runtime podczas przepływów konfiguracji.
|
||||
Szczegóły znajdziesz w [Konfiguracja i ustawienia](/pl/plugins/sdk-setup#setup-entry).
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Obsłuż wiadomości przychodzące">
|
||||
Plugin musi odbierać wiadomości z platformy i przekazywać je do
|
||||
Twój plugin musi odbierać wiadomości z platformy i przekazywać je do
|
||||
OpenClaw. Typowy wzorzec to webhook, który weryfikuje żądanie i
|
||||
dispatchuje je przez przychodzący handler kanału:
|
||||
dispatchuje je przez handler wejściowy Twojego kanału:
|
||||
|
||||
```typescript
|
||||
registerFull(api) {
|
||||
api.registerHttpRoute({
|
||||
path: "/acme-chat/webhook",
|
||||
auth: "plugin", // uwierzytelnianie zarządzane przez plugin (zweryfikuj podpisy samodzielnie)
|
||||
auth: "plugin", // plugin-managed auth (verify signatures yourself)
|
||||
handler: async (req, res) => {
|
||||
const event = parseWebhookPayload(req);
|
||||
|
||||
// Twój handler przychodzący dispatchuje wiadomość do OpenClaw.
|
||||
// Dokładne okablowanie zależy od SDK twojej platformy —
|
||||
// zobacz rzeczywisty przykład w dołączonym pakiecie pluginu Microsoft Teams lub Google Chat.
|
||||
// Your inbound handler dispatches the message to OpenClaw.
|
||||
// The exact wiring depends on your platform SDK —
|
||||
// see a real example in the bundled Microsoft Teams or Google Chat plugin package.
|
||||
await handleAcmeChatInbound(api, event);
|
||||
|
||||
res.statusCode = 200;
|
||||
@ -503,22 +517,22 @@ powinien używać `resolveInboundMentionDecision({ facts, policy })`.
|
||||
|
||||
<Note>
|
||||
Obsługa wiadomości przychodzących jest specyficzna dla kanału. Każdy plugin kanału
|
||||
zarządza własnym pipeline przychodzącym. Zajrzyj do dołączonych pluginów kanałów
|
||||
(na przykład do pakietu pluginu Microsoft Teams lub Google Chat), aby zobaczyć rzeczywiste wzorce.
|
||||
odpowiada za własny pipeline wejściowy. Sprawdź bundled plugins kanałów
|
||||
(na przykład pakiet pluginów Microsoft Teams lub Google Chat), aby zobaczyć rzeczywiste wzorce.
|
||||
</Note>
|
||||
|
||||
</Step>
|
||||
|
||||
<a id="step-6-test"></a>
|
||||
<Step title="Testuj">
|
||||
Pisz testy współlokowane w `src/channel.test.ts`:
|
||||
<Step title="Testowanie">
|
||||
Napisz testy colocated w `src/channel.test.ts`:
|
||||
|
||||
```typescript src/channel.test.ts
|
||||
import { describe, it, expect } from "vitest";
|
||||
import { acmeChatPlugin } from "./channel.js";
|
||||
|
||||
describe("acme-chat plugin", () => {
|
||||
it("rozwiązuje konto z configu", () => {
|
||||
it("resolves account from config", () => {
|
||||
const cfg = {
|
||||
channels: {
|
||||
"acme-chat": { token: "test-token", allowFrom: ["user1"] },
|
||||
@ -528,7 +542,7 @@ Pisz testy współlokowane w `src/channel.test.ts`:
|
||||
expect(account.token).toBe("test-token");
|
||||
});
|
||||
|
||||
it("sprawdza konto bez materializowania sekretów", () => {
|
||||
it("inspects account without materializing secrets", () => {
|
||||
const cfg = {
|
||||
channels: { "acme-chat": { token: "test-token" } },
|
||||
} as any;
|
||||
@ -537,7 +551,7 @@ Pisz testy współlokowane w `src/channel.test.ts`:
|
||||
expect(result.tokenStatus).toBe("available");
|
||||
});
|
||||
|
||||
it("zgłasza brakujący config", () => {
|
||||
it("reports missing config", () => {
|
||||
const cfg = { channels: {} } as any;
|
||||
const result = acmeChatPlugin.setup!.inspectAccount!(cfg, undefined);
|
||||
expect(result.configured).toBe(false);
|
||||
@ -549,7 +563,7 @@ Pisz testy współlokowane w `src/channel.test.ts`:
|
||||
pnpm test -- <bundled-plugin-root>/acme-chat/
|
||||
```
|
||||
|
||||
Współdzielone helpery testowe opisano w [Testing](/pl/plugins/sdk-testing).
|
||||
Współdzielone helpery testowe znajdziesz w [Testowanie](/pl/plugins/sdk-testing).
|
||||
|
||||
</Step>
|
||||
</Steps>
|
||||
@ -559,45 +573,45 @@ Pisz testy współlokowane w `src/channel.test.ts`:
|
||||
```
|
||||
<bundled-plugin-root>/acme-chat/
|
||||
├── package.json # metadane openclaw.channel
|
||||
├── openclaw.plugin.json # Manifest ze schematem configu
|
||||
├── openclaw.plugin.json # Manifest ze schematem konfiguracji
|
||||
├── index.ts # defineChannelPluginEntry
|
||||
├── setup-entry.ts # defineSetupPluginEntry
|
||||
├── api.ts # Eksporty publiczne (opcjonalnie)
|
||||
├── api.ts # Publiczne eksporty (opcjonalnie)
|
||||
├── runtime-api.ts # Wewnętrzne eksporty runtime (opcjonalnie)
|
||||
└── src/
|
||||
├── channel.ts # ChannelPlugin przez createChatChannelPlugin
|
||||
├── channel.test.ts # Testy
|
||||
├── client.ts # Klient API platformy
|
||||
└── runtime.ts # Store runtime (jeśli potrzebny)
|
||||
└── runtime.ts # Magazyn runtime (jeśli potrzebny)
|
||||
```
|
||||
|
||||
## Tematy zaawansowane
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Opcje wątkowania" icon="git-branch" href="/pl/plugins/sdk-entrypoints#registration-mode">
|
||||
Stałe tryby odpowiedzi, tryby z zakresem konta lub niestandardowe
|
||||
Stałe tryby odpowiedzi, ograniczone do konta lub niestandardowe
|
||||
</Card>
|
||||
<Card title="Integracja z narzędziem wiadomości" icon="puzzle" href="/pl/plugins/architecture#channel-plugins-and-the-shared-message-tool">
|
||||
<Card title="Integracja narzędzia wiadomości" icon="puzzle" href="/pl/plugins/architecture#channel-plugins-and-the-shared-message-tool">
|
||||
describeMessageTool i wykrywanie akcji
|
||||
</Card>
|
||||
<Card title="Rozwiązywanie targetów" icon="crosshair" href="/pl/plugins/architecture#channel-target-resolution">
|
||||
<Card title="Rozwiązywanie celu" icon="crosshair" href="/pl/plugins/architecture#channel-target-resolution">
|
||||
inferTargetChatType, looksLikeId, resolveTarget
|
||||
</Card>
|
||||
<Card title="Helpery runtime" icon="settings" href="/pl/plugins/sdk-runtime">
|
||||
TTS, STT, media, subagent przez api.runtime
|
||||
TTS, STT, multimedia, subagent przez api.runtime
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
<Note>
|
||||
Niektóre dołączone szczeliny helperów nadal istnieją na potrzeby utrzymania dołączonych pluginów i
|
||||
Niektóre bundled helper seams nadal istnieją na potrzeby utrzymania bundled plugins i
|
||||
zgodności. Nie są one zalecanym wzorcem dla nowych pluginów kanałów;
|
||||
preferuj ogólne subścieżki channel/setup/reply/runtime ze wspólnej
|
||||
powierzchni SDK, chyba że bezpośrednio utrzymujesz tę rodzinę dołączonych pluginów.
|
||||
preferuj ogólne podścieżki channel/setup/reply/runtime ze wspólnej
|
||||
powierzchni SDK, chyba że bezpośrednio utrzymujesz tę rodzinę bundled plugins.
|
||||
</Note>
|
||||
|
||||
## Kolejne kroki
|
||||
|
||||
- [Provider Plugins](/pl/plugins/sdk-provider-plugins) — jeśli plugin udostępnia również modele
|
||||
- [SDK Overview](/pl/plugins/sdk-overview) — pełne odniesienie do importów subścieżek
|
||||
- [SDK Testing](/pl/plugins/sdk-testing) — narzędzia testowe i testy kontraktowe
|
||||
- [Plugin Manifest](/pl/plugins/manifest) — pełny schemat manifestu
|
||||
- [Pluginy dostawców](/pl/plugins/sdk-provider-plugins) — jeśli Twój plugin dostarcza także modele
|
||||
- [Przegląd SDK](/pl/plugins/sdk-overview) — pełne odniesienie do importów podścieżek
|
||||
- [Testowanie SDK](/pl/plugins/sdk-testing) — narzędzia testowe i testy kontraktowe
|
||||
- [Manifest pluginu](/pl/plugins/manifest) — pełny schemat manifestu
|
||||
|
||||
@ -2,104 +2,129 @@
|
||||
read_when:
|
||||
- Widzisz ostrzeżenie OPENCLAW_PLUGIN_SDK_COMPAT_DEPRECATED
|
||||
- Widzisz ostrzeżenie OPENCLAW_EXTENSION_API_DEPRECATED
|
||||
- Aktualizujesz wtyczkę do nowoczesnej architektury wtyczek
|
||||
- Utrzymujesz zewnętrzną wtyczkę OpenClaw
|
||||
- Aktualizujesz plugin do nowoczesnej architektury pluginów OpenClaw
|
||||
- Utrzymujesz zewnętrzny plugin OpenClaw
|
||||
sidebarTitle: Migrate to SDK
|
||||
summary: Migracja ze starszej warstwy zgodności wstecznej do nowoczesnego SDK wtyczek
|
||||
summary: Migracja ze starszej warstwy zgodności wstecznej do nowoczesnego Plugin SDK
|
||||
title: Migracja Plugin SDK
|
||||
x-i18n:
|
||||
generated_at: "2026-04-07T09:48:40Z"
|
||||
generated_at: "2026-04-08T02:17:46Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 3691060e9dc00ca8bee49240a047f0479398691bd14fb96e9204cc9243fdb32c
|
||||
source_hash: 155a8b14bc345319c8516ebdb8a0ccdea2c5f7fa07dad343442996daee21ecad
|
||||
source_path: plugins/sdk-migration.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Migracja Plugin SDK
|
||||
|
||||
OpenClaw przeszedł od szerokiej warstwy zgodności wstecznej do nowoczesnej
|
||||
architektury wtyczek z precyzyjnymi, udokumentowanymi importami. Jeśli Twoja
|
||||
wtyczka została zbudowana przed wprowadzeniem nowej architektury, ten przewodnik
|
||||
pomoże Ci przeprowadzić migrację.
|
||||
OpenClaw przeszedł od szerokiej warstwy zgodności wstecznej do nowoczesnej architektury
|
||||
pluginów z ukierunkowanymi, udokumentowanymi importami. Jeśli Twój plugin powstał przed
|
||||
nową architekturą, ten przewodnik pomoże Ci przeprowadzić migrację.
|
||||
|
||||
## Co się zmienia
|
||||
|
||||
Stary system wtyczek udostępniał dwie szeroko otwarte powierzchnie, które pozwalały wtyczkom importować
|
||||
Stary system pluginów udostępniał dwie bardzo szerokie powierzchnie, które pozwalały pluginom importować
|
||||
wszystko, czego potrzebowały, z jednego punktu wejścia:
|
||||
|
||||
- **`openclaw/plugin-sdk/compat`** — pojedynczy import, który re-eksportował dziesiątki
|
||||
helperów. Został wprowadzony, aby utrzymać działanie starszych wtyczek opartych na hookach,
|
||||
podczas gdy budowano nową architekturę wtyczek.
|
||||
- **`openclaw/extension-api`** — most, który dawał wtyczkom bezpośredni dostęp do
|
||||
helperów po stronie hosta, takich jak osadzony runner agenta.
|
||||
- **`openclaw/plugin-sdk/compat`** — pojedynczy import, który reeksportował dziesiątki
|
||||
pomocników. Został wprowadzony po to, aby starsze pluginy oparte na hookach nadal działały
|
||||
podczas budowy nowej architektury pluginów.
|
||||
- **`openclaw/extension-api`** — most, który dawał pluginom bezpośredni dostęp do
|
||||
pomocników po stronie hosta, takich jak osadzony runner agenta.
|
||||
|
||||
Obie powierzchnie są teraz **przestarzałe**. Nadal działają w czasie wykonywania, ale nowe
|
||||
wtyczki nie mogą ich używać, a istniejące wtyczki powinny przeprowadzić migrację, zanim kolejna
|
||||
główna wersja je usunie.
|
||||
Obie powierzchnie są teraz **przestarzałe**. Nadal działają w czasie działania, ale nowe
|
||||
pluginy nie mogą ich używać, a istniejące pluginy powinny przeprowadzić migrację przed następnym
|
||||
głównym wydaniem, które je usunie.
|
||||
|
||||
<Warning>
|
||||
Warstwa zgodności wstecznej zostanie usunięta w jednej z przyszłych głównych wersji.
|
||||
Wtyczki, które nadal importują z tych powierzchni, przestaną działać, gdy to nastąpi.
|
||||
Warstwa zgodności wstecznej zostanie usunięta w jednym z przyszłych głównych wydań.
|
||||
Pluginy, które nadal importują z tych powierzchni, przestaną działać, gdy to nastąpi.
|
||||
</Warning>
|
||||
|
||||
## Dlaczego to się zmieniło
|
||||
|
||||
Stare podejście powodowało problemy:
|
||||
|
||||
- **Powolny start** — zaimportowanie jednego helpera ładowało dziesiątki niezwiązanych modułów
|
||||
- **Zależności cykliczne** — szerokie re-eksporty ułatwiały tworzenie cykli importu
|
||||
- **Niejasna powierzchnia API** — nie było sposobu, aby stwierdzić, które eksporty są stabilne, a które wewnętrzne
|
||||
- **Powolne uruchamianie** — zaimportowanie jednego pomocnika ładowało dziesiątki niepowiązanych modułów
|
||||
- **Zależności cykliczne** — szerokie reeksporty ułatwiały tworzenie cykli importów
|
||||
- **Niejasna powierzchnia API** — nie było sposobu, aby odróżnić stabilne eksporty od wewnętrznych
|
||||
|
||||
Nowoczesne SDK wtyczek rozwiązuje ten problem: każda ścieżka importu (`openclaw/plugin-sdk/\<subpath\>`)
|
||||
jest małym, samodzielnym modułem z jasno określonym przeznaczeniem i udokumentowanym kontraktem.
|
||||
Nowoczesny Plugin SDK to naprawia: każda ścieżka importu (`openclaw/plugin-sdk/\<subpath\>`)
|
||||
jest małym, samodzielnym modułem o jasno określonym celu i udokumentowanym kontrakcie.
|
||||
|
||||
Starsze wygodne granice dostawców dla dołączonych kanałów również zniknęły. Importy
|
||||
Starsze wygodne warstwy dostawców dla dołączonych kanałów również zniknęły. Importy
|
||||
takie jak `openclaw/plugin-sdk/slack`, `openclaw/plugin-sdk/discord`,
|
||||
`openclaw/plugin-sdk/signal`, `openclaw/plugin-sdk/whatsapp`,
|
||||
pomocnicze granice oznaczone marką kanału oraz
|
||||
`openclaw/plugin-sdk/telegram-core` były prywatnymi skrótami monorepo, a nie
|
||||
stabilnymi kontraktami wtyczek. Zamiast tego używaj wąskich, generycznych ścieżek podrzędnych SDK. W obrębie
|
||||
dołączonego workspace wtyczek trzymaj helpery należące do dostawcy we własnym
|
||||
`api.ts` lub `runtime-api.ts` tej wtyczki.
|
||||
warstwy pomocnicze oznaczone marką kanału oraz
|
||||
`openclaw/plugin-sdk/telegram-core` były prywatnymi skrótami mono-repo, a nie
|
||||
stabilnymi kontraktami pluginów. Zamiast tego używaj wąskich, ogólnych podścieżek SDK. Wewnątrz
|
||||
dołączonego obszaru roboczego pluginów trzymaj pomocniki należące do dostawcy we własnym
|
||||
`api.ts` lub `runtime-api.ts` tego pluginu.
|
||||
|
||||
Aktualne przykłady dołączonych dostawców:
|
||||
|
||||
- Anthropic przechowuje helpery strumieni specyficzne dla Claude we własnej granicy `api.ts` /
|
||||
- Anthropic przechowuje pomocniki strumieni specyficzne dla Claude we własnej warstwie `api.ts` /
|
||||
`contract-api.ts`
|
||||
- OpenAI przechowuje konstruktory dostawcy, helpery modeli domyślnych i konstruktory
|
||||
dostawców realtime we własnym `api.ts`
|
||||
- OpenRouter przechowuje konstruktor dostawcy oraz helpery onboardingu/konfiguracji we własnym
|
||||
- OpenAI przechowuje konstruktory dostawców, pomocniki modeli domyślnych i konstruktory dostawców realtime
|
||||
we własnym `api.ts`
|
||||
- OpenRouter przechowuje konstruktor dostawcy oraz pomocniki onboardingu/konfiguracji we własnym
|
||||
`api.ts`
|
||||
|
||||
## Jak przeprowadzić migrację
|
||||
|
||||
<Steps>
|
||||
<Step title="Sprawdź zachowanie fallbacku wrappera Windows">
|
||||
Jeśli Twoja wtyczka używa `openclaw/plugin-sdk/windows-spawn`, nierozwiązane wrappery Windows
|
||||
`.cmd`/`.bat` teraz kończą działanie w trybie fail-closed, chyba że jawnie przekażesz
|
||||
<Step title="Przenieś handlery natywne dla zatwierdzeń na fakty możliwości">
|
||||
Pluginy kanałów obsługujące zatwierdzenia udostępniają teraz natywne zachowanie zatwierdzeń przez
|
||||
`approvalCapability.nativeRuntime` oraz współdzielony rejestr runtime-context.
|
||||
|
||||
Najważniejsze zmiany:
|
||||
|
||||
- Zamień `approvalCapability.handler.loadRuntime(...)` na
|
||||
`approvalCapability.nativeRuntime`
|
||||
- Przenieś uwierzytelnianie/dostarczanie specyficzne dla zatwierdzeń ze starszego okablowania `plugin.auth` /
|
||||
`plugin.approvals` na `approvalCapability`
|
||||
- `ChannelPlugin.approvals` zostało usunięte z publicznego kontraktu pluginów kanałowych;
|
||||
przenieś pola delivery/native/render do `approvalCapability`
|
||||
- `plugin.auth` pozostaje tylko dla przepływów logowania/wylogowania kanału; hooki
|
||||
uwierzytelniania zatwierdzeń nie są już tam odczytywane przez core
|
||||
- Rejestruj obiekty runtime należące do kanału, takie jak klienci, tokeny lub aplikacje
|
||||
Bolt, przez `openclaw/plugin-sdk/channel-runtime-context`
|
||||
- Nie wysyłaj komunikatów o przekierowaniu należących do pluginu z natywnych handlerów zatwierdzeń;
|
||||
core odpowiada teraz za komunikaty „dostarczono gdzie indziej” na podstawie rzeczywistych wyników dostarczenia
|
||||
- Przy przekazywaniu `channelRuntime` do `createChannelManager(...)` podaj
|
||||
rzeczywistą powierzchnię `createPluginRuntime().channel`. Częściowe stuby są odrzucane.
|
||||
|
||||
Zobacz `/plugins/sdk-channel-plugins`, aby poznać bieżący układ
|
||||
approval capability.
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Sprawdź zachowanie zapasowe wrapperów Windows">
|
||||
Jeśli Twój plugin używa `openclaw/plugin-sdk/windows-spawn`, nierozwiązane wrappery Windows
|
||||
`.cmd`/`.bat` teraz domyślnie kończą się błędem, chyba że jawnie przekażesz
|
||||
`allowShellFallback: true`.
|
||||
|
||||
```typescript
|
||||
// Przed
|
||||
// Before
|
||||
const program = applyWindowsSpawnProgramPolicy({ candidate });
|
||||
|
||||
// Po
|
||||
// After
|
||||
const program = applyWindowsSpawnProgramPolicy({
|
||||
candidate,
|
||||
// Ustaw to tylko dla zaufanych wywołań zgodności, które celowo
|
||||
// akceptują fallback pośredniczony przez powłokę.
|
||||
// Only set this for trusted compatibility callers that intentionally
|
||||
// accept shell-mediated fallback.
|
||||
allowShellFallback: true,
|
||||
});
|
||||
```
|
||||
|
||||
Jeśli Twój kod wywołujący nie polega celowo na fallbacku powłoki, nie ustawiaj
|
||||
`allowShellFallback` i zamiast tego obsłuż zgłoszony błąd.
|
||||
Jeśli wywołujący nie polega celowo na zapasowym użyciu powłoki, nie ustawiaj
|
||||
`allowShellFallback`, tylko obsłuż zgłaszany błąd.
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Znajdź przestarzałe importy">
|
||||
Przeszukaj swoją wtyczkę pod kątem importów z jednej z tych przestarzałych powierzchni:
|
||||
Przeszukaj plugin w poszukiwaniu importów z którejkolwiek z przestarzałych powierzchni:
|
||||
|
||||
```bash
|
||||
grep -r "plugin-sdk/compat" my-plugin/
|
||||
@ -108,36 +133,36 @@ Aktualne przykłady dołączonych dostawców:
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Zastąp je precyzyjnymi importami">
|
||||
Każdy eksport ze starej powierzchni mapuje się na konkretną nowoczesną ścieżkę importu:
|
||||
<Step title="Zastąp je ukierunkowanymi importami">
|
||||
Każdy eksport ze starej powierzchni odpowiada konkretnej nowoczesnej ścieżce importu:
|
||||
|
||||
```typescript
|
||||
// Przed (przestarzała warstwa zgodności wstecznej)
|
||||
// Before (deprecated backwards-compatibility layer)
|
||||
import {
|
||||
createChannelReplyPipeline,
|
||||
createPluginRuntimeStore,
|
||||
resolveControlCommandGate,
|
||||
} from "openclaw/plugin-sdk/compat";
|
||||
|
||||
// Po (nowoczesne precyzyjne importy)
|
||||
// After (modern focused imports)
|
||||
import { createChannelReplyPipeline } from "openclaw/plugin-sdk/channel-reply-pipeline";
|
||||
import { createPluginRuntimeStore } from "openclaw/plugin-sdk/runtime-store";
|
||||
import { resolveControlCommandGate } from "openclaw/plugin-sdk/command-auth";
|
||||
```
|
||||
|
||||
W przypadku helperów po stronie hosta użyj wstrzykniętego runtime wtyczki zamiast importować je
|
||||
bezpośrednio:
|
||||
W przypadku pomocników po stronie hosta używaj wstrzykniętego runtime pluginu zamiast
|
||||
bezpośredniego importu:
|
||||
|
||||
```typescript
|
||||
// Przed (przestarzały most extension-api)
|
||||
// Before (deprecated extension-api bridge)
|
||||
import { runEmbeddedPiAgent } from "openclaw/extension-api";
|
||||
const result = await runEmbeddedPiAgent({ sessionId, prompt });
|
||||
|
||||
// Po (wstrzyknięty runtime)
|
||||
// After (injected runtime)
|
||||
const result = await api.runtime.agent.runEmbeddedPiAgent({ sessionId, prompt });
|
||||
```
|
||||
|
||||
Ten sam wzorzec dotyczy innych helperów starszego mostu:
|
||||
Ten sam wzorzec dotyczy innych starszych pomocników mostu:
|
||||
|
||||
| Stary import | Nowoczesny odpowiednik |
|
||||
| --- | --- |
|
||||
@ -147,7 +172,7 @@ Aktualne przykłady dołączonych dostawców:
|
||||
| `resolveThinkingDefault` | `api.runtime.agent.resolveThinkingDefault` |
|
||||
| `resolveAgentTimeoutMs` | `api.runtime.agent.resolveAgentTimeoutMs` |
|
||||
| `ensureAgentWorkspace` | `api.runtime.agent.ensureAgentWorkspace` |
|
||||
| helpery session store | `api.runtime.agent.session.*` |
|
||||
| pomocniki magazynu sesji | `api.runtime.agent.session.*` |
|
||||
|
||||
</Step>
|
||||
|
||||
@ -161,200 +186,205 @@ Aktualne przykłady dołączonych dostawców:
|
||||
|
||||
## Dokumentacja ścieżek importu
|
||||
|
||||
<Accordion title="Tabela typowych ścieżek importu">
|
||||
| Ścieżka importu | Przeznaczenie | Kluczowe eksporty |
|
||||
<Accordion title="Tabela najczęściej używanych ścieżek importu">
|
||||
| Import path | Cel | Kluczowe eksporty |
|
||||
| --- | --- | --- |
|
||||
| `plugin-sdk/plugin-entry` | Kanoniczny helper punktu wejścia wtyczki | `definePluginEntry` |
|
||||
| `plugin-sdk/core` | Starszy parasolowy re-eksport dla definicji/builderów punktów wejścia kanału | `defineChannelPluginEntry`, `createChatChannelPlugin` |
|
||||
| `plugin-sdk/config-schema` | Eksport schematu głównej konfiguracji | `OpenClawSchema` |
|
||||
| `plugin-sdk/provider-entry` | Helper punktu wejścia pojedynczego dostawcy | `defineSingleProviderPluginEntry` |
|
||||
| `plugin-sdk/channel-core` | Precyzyjne definicje i buildery punktów wejścia kanału | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` |
|
||||
| `plugin-sdk/setup` | Wspólne helpery kreatora konfiguracji | Prompty allowlisty, buildery statusu konfiguracji |
|
||||
| `plugin-sdk/setup-runtime` | Helpery runtime dla czasu konfiguracji | Bezpieczne importowo adaptery poprawek konfiguracji, helpery notatek wyszukiwania, `promptResolvedAllowFrom`, `splitSetupEntries`, delegowane proxy konfiguracji |
|
||||
| `plugin-sdk/setup-adapter-runtime` | Helpery adaptera konfiguracji | `createEnvPatchedAccountSetupAdapter` |
|
||||
| `plugin-sdk/setup-tools` | Helpery narzędzi konfiguracji | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` |
|
||||
| `plugin-sdk/account-core` | Helpery wielu kont | Helpery listy kont/konfiguracji/bramkowania działań |
|
||||
| `plugin-sdk/account-id` | Helpery identyfikatora konta | `DEFAULT_ACCOUNT_ID`, normalizacja identyfikatora konta |
|
||||
| `plugin-sdk/account-resolution` | Helpery wyszukiwania konta | Helpery wyszukiwania konta + fallbacku do wartości domyślnej |
|
||||
| `plugin-sdk/account-helpers` | Wąskie helpery konta | Helpery listy kont/działań na koncie |
|
||||
| `plugin-sdk/channel-setup` | Adaptery kreatora konfiguracji | `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, `createOptionalChannelSetupWizard`, a także `DEFAULT_ACCOUNT_ID`, `createTopLevelChannelDmPolicy`, `setSetupChannelEnabled`, `splitSetupEntries` |
|
||||
| `plugin-sdk/plugin-entry` | Kanoniczny pomocnik punktu wejścia pluginu | `definePluginEntry` |
|
||||
| `plugin-sdk/core` | Starszy zbiorczy reeksport dla definicji/builderów punktów wejścia kanałów | `defineChannelPluginEntry`, `createChatChannelPlugin` |
|
||||
| `plugin-sdk/config-schema` | Eksport głównego schematu konfiguracji | `OpenClawSchema` |
|
||||
| `plugin-sdk/provider-entry` | Pomocnik punktu wejścia pojedynczego dostawcy | `defineSingleProviderPluginEntry` |
|
||||
| `plugin-sdk/channel-core` | Ukierunkowane definicje i buildery punktów wejścia kanałów | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` |
|
||||
| `plugin-sdk/setup` | Współdzielone pomocniki kreatora konfiguracji | Prompty allowlist, buildery statusu konfiguracji |
|
||||
| `plugin-sdk/setup-runtime` | Pomocniki runtime na etapie konfiguracji | Bezpieczne importowo adaptery łatek konfiguracji, pomocniki notatek lookup, `promptResolvedAllowFrom`, `splitSetupEntries`, delegowane proxy konfiguracji |
|
||||
| `plugin-sdk/setup-adapter-runtime` | Pomocniki adaptera konfiguracji | `createEnvPatchedAccountSetupAdapter` |
|
||||
| `plugin-sdk/setup-tools` | Pomocniki narzędzi konfiguracji | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` |
|
||||
| `plugin-sdk/account-core` | Pomocniki dla wielu kont | Pomocniki list kont/konfiguracji/bram akcji |
|
||||
| `plugin-sdk/account-id` | Pomocniki identyfikatorów kont | `DEFAULT_ACCOUNT_ID`, normalizacja identyfikatora konta |
|
||||
| `plugin-sdk/account-resolution` | Pomocniki wyszukiwania kont | Wyszukiwanie konta + pomocniki zapasowego wyboru domyślnego |
|
||||
| `plugin-sdk/account-helpers` | Wąskie pomocniki kont | Pomocniki list kont/akcji na kontach |
|
||||
| `plugin-sdk/channel-setup` | Adaptery kreatora konfiguracji | `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, `createOptionalChannelSetupWizard`, plus `DEFAULT_ACCOUNT_ID`, `createTopLevelChannelDmPolicy`, `setSetupChannelEnabled`, `splitSetupEntries` |
|
||||
| `plugin-sdk/channel-pairing` | Prymitywy parowania DM | `createChannelPairingController` |
|
||||
| `plugin-sdk/channel-reply-pipeline` | Łączenie prefiksu odpowiedzi i typing | `createChannelReplyPipeline` |
|
||||
| `plugin-sdk/channel-reply-pipeline` | Okablowanie prefiksu odpowiedzi + typing | `createChannelReplyPipeline` |
|
||||
| `plugin-sdk/channel-config-helpers` | Fabryki adapterów konfiguracji | `createHybridChannelConfigAdapter` |
|
||||
| `plugin-sdk/channel-config-schema` | Buildery schematów konfiguracji | Typy schematów konfiguracji kanału |
|
||||
| `plugin-sdk/telegram-command-config` | Helpery konfiguracji poleceń Telegram | Normalizacja nazw poleceń, przycinanie opisów, walidacja duplikatów/konfliktów |
|
||||
| `plugin-sdk/channel-policy` | Rozstrzyganie polityki grup/DM | `resolveChannelGroupRequireMention` |
|
||||
| `plugin-sdk/channel-config-schema` | Buildery schematów konfiguracji | Typy schematu konfiguracji kanału |
|
||||
| `plugin-sdk/telegram-command-config` | Pomocniki konfiguracji poleceń Telegram | Normalizacja nazw poleceń, przycinanie opisów, walidacja duplikatów/konfliktów |
|
||||
| `plugin-sdk/channel-policy` | Rozstrzyganie polityk grup/DM | `resolveChannelGroupRequireMention` |
|
||||
| `plugin-sdk/channel-lifecycle` | Śledzenie statusu konta | `createAccountStatusSink` |
|
||||
| `plugin-sdk/inbound-envelope` | Helpery koperty wejściowej | Wspólne helpery routingu i budowania koperty |
|
||||
| `plugin-sdk/inbound-reply-dispatch` | Helpery odpowiedzi wejściowej | Wspólne helpery zapisu i dyspozycji |
|
||||
| `plugin-sdk/messaging-targets` | Parsowanie celów wiadomości | Helpery parsowania/dopasowywania celów |
|
||||
| `plugin-sdk/outbound-media` | Helpery mediów wychodzących | Wspólne ładowanie mediów wychodzących |
|
||||
| `plugin-sdk/outbound-runtime` | Helpery runtime dla ruchu wychodzącego | Helpery tożsamości wychodzącej/delegatów wysyłki |
|
||||
| `plugin-sdk/thread-bindings-runtime` | Helpery powiązań wątków | Helpery cyklu życia powiązań wątków i adapterów |
|
||||
| `plugin-sdk/agent-media-payload` | Starsze helpery ładunku mediów | Builder ładunku mediów agenta dla starszych układów pól |
|
||||
| `plugin-sdk/channel-runtime` | Przestarzały shim zgodności | Tylko starsze narzędzia runtime kanału |
|
||||
| `plugin-sdk/inbound-envelope` | Pomocniki kopert wejściowych | Współdzielone pomocniki routingu + buildera kopert |
|
||||
| `plugin-sdk/inbound-reply-dispatch` | Pomocniki odpowiedzi wejściowych | Współdzielone pomocniki zapisu i dispatchu |
|
||||
| `plugin-sdk/messaging-targets` | Parsowanie celów wiadomości | Pomocniki parsowania/dopasowywania celów |
|
||||
| `plugin-sdk/outbound-media` | Pomocniki mediów wychodzących | Współdzielone ładowanie mediów wychodzących |
|
||||
| `plugin-sdk/outbound-runtime` | Pomocniki runtime wychodzącego | Pomocniki tożsamości wychodzącej/delegatów wysyłki |
|
||||
| `plugin-sdk/thread-bindings-runtime` | Pomocniki powiązań wątków | Cykl życia powiązań wątków i pomocniki adapterów |
|
||||
| `plugin-sdk/agent-media-payload` | Starsze pomocniki payloadów mediów | Builder payloadu mediów agenta dla starszych układów pól |
|
||||
| `plugin-sdk/channel-runtime` | Przestarzały shim zgodności | Tylko starsze narzędzia channel runtime |
|
||||
| `plugin-sdk/channel-send-result` | Typy wyników wysyłki | Typy wyników odpowiedzi |
|
||||
| `plugin-sdk/runtime-store` | Trwałe przechowywanie wtyczki | `createPluginRuntimeStore` |
|
||||
| `plugin-sdk/runtime` | Szerokie helpery runtime | Helpery runtime/logowania/kopii zapasowych/instalacji wtyczek |
|
||||
| `plugin-sdk/runtime-env` | Wąskie helpery środowiska runtime | Logger/środowisko runtime, timeout, retry i helpery backoff |
|
||||
| `plugin-sdk/plugin-runtime` | Wspólne helpery runtime wtyczek | Helpery poleceń/hooków/http/interaktywne dla wtyczek |
|
||||
| `plugin-sdk/hook-runtime` | Helpery pipeline hooków | Wspólne helpery pipeline webhooków/wewnętrznych hooków |
|
||||
| `plugin-sdk/lazy-runtime` | Helpery leniwego runtime | `createLazyRuntimeModule`, `createLazyRuntimeMethod`, `createLazyRuntimeMethodBinder`, `createLazyRuntimeNamedExport`, `createLazyRuntimeSurface` |
|
||||
| `plugin-sdk/process-runtime` | Helpery procesów | Wspólne helpery exec |
|
||||
| `plugin-sdk/cli-runtime` | Helpery runtime CLI | Formatowanie poleceń, oczekiwania, helpery wersji |
|
||||
| `plugin-sdk/gateway-runtime` | Helpery Gateway | Klient Gateway i helpery poprawek statusu kanałów |
|
||||
| `plugin-sdk/config-runtime` | Helpery konfiguracji | Helpery ładowania/zapisu konfiguracji |
|
||||
| `plugin-sdk/telegram-command-config` | Helpery poleceń Telegram | Stabilne w fallbacku helpery walidacji poleceń Telegram, gdy dołączona powierzchnia kontraktu Telegram jest niedostępna |
|
||||
| `plugin-sdk/approval-runtime` | Helpery promptów zatwierdzania | Ładunek zatwierdzania exec/wtyczki, helpery capability/profili zatwierdzania, natywny routing/runtime zatwierdzania |
|
||||
| `plugin-sdk/approval-auth-runtime` | Helpery uwierzytelniania zatwierdzania | Rozstrzyganie zatwierdzającego, uwierzytelnianie akcji w tym samym czacie |
|
||||
| `plugin-sdk/approval-client-runtime` | Helpery klienta zatwierdzania | Natywne helpery profili/filtrów zatwierdzania exec |
|
||||
| `plugin-sdk/approval-delivery-runtime` | Helpery dostarczania zatwierdzania | Natywne adaptery capability/dostarczania zatwierdzania |
|
||||
| `plugin-sdk/approval-native-runtime` | Helpery celu zatwierdzania | Natywne helpery celu zatwierdzania/powiązania konta |
|
||||
| `plugin-sdk/approval-reply-runtime` | Helpery odpowiedzi zatwierdzania | Helpery ładunku odpowiedzi zatwierdzania exec/wtyczki |
|
||||
| `plugin-sdk/security-runtime` | Helpery bezpieczeństwa | Wspólne helpery zaufania, bramkowania DM, treści zewnętrznych i zbierania sekretów |
|
||||
| `plugin-sdk/ssrf-policy` | Helpery polityki SSRF | Helpery allowlisty hostów i polityki sieci prywatnych |
|
||||
| `plugin-sdk/ssrf-runtime` | Helpery runtime SSRF | Helpery pinned-dispatcher, guarded fetch i polityki SSRF |
|
||||
| `plugin-sdk/collection-runtime` | Helpery ograniczonego cache | `pruneMapToMaxSize` |
|
||||
| `plugin-sdk/diagnostic-runtime` | Helpery bramkowania diagnostyki | `isDiagnosticFlagEnabled`, `isDiagnosticsEnabled` |
|
||||
| `plugin-sdk/error-runtime` | Helpery formatowania błędów | `formatUncaughtError`, `isApprovalNotFoundError`, helpery grafu błędów |
|
||||
| `plugin-sdk/fetch-runtime` | Helpery opakowanego fetch/proxy | `resolveFetch`, helpery proxy |
|
||||
| `plugin-sdk/host-runtime` | Helpery normalizacji hosta | `normalizeHostname`, `normalizeScpRemoteHost` |
|
||||
| `plugin-sdk/retry-runtime` | Helpery retry | `RetryConfig`, `retryAsync`, wykonawcy polityk |
|
||||
| `plugin-sdk/allow-from` | Formatowanie allowlisty | `formatAllowFromLowercase` |
|
||||
| `plugin-sdk/allowlist-resolution` | Mapowanie wejść allowlisty | `mapAllowlistResolutionInputs` |
|
||||
| `plugin-sdk/command-auth` | Bramkowanie poleceń i helpery powierzchni poleceń | `resolveControlCommandGate`, helpery autoryzacji nadawcy, helpery rejestru poleceń |
|
||||
| `plugin-sdk/secret-input` | Parsowanie wejścia sekretów | Helpery wejścia sekretów |
|
||||
| `plugin-sdk/webhook-ingress` | Helpery żądań webhook | Narzędzia celu webhooka |
|
||||
| `plugin-sdk/webhook-request-guards` | Helpery strażników treści webhooka | Helpery odczytu/limitów treści żądania |
|
||||
| `plugin-sdk/reply-runtime` | Wspólny runtime odpowiedzi | Dyspozycja wejściowa, heartbeat, planer odpowiedzi, chunking |
|
||||
| `plugin-sdk/reply-dispatch-runtime` | Wąskie helpery dyspozycji odpowiedzi | Helpery finalizacji i dyspozycji dostawcy |
|
||||
| `plugin-sdk/reply-history` | Helpery historii odpowiedzi | `buildHistoryContext`, `buildPendingHistoryContextFromMap`, `recordPendingHistoryEntry`, `clearHistoryEntriesIfEnabled` |
|
||||
| `plugin-sdk/runtime-store` | Trwałe przechowywanie pluginu | `createPluginRuntimeStore` |
|
||||
| `plugin-sdk/runtime` | Szerokie pomocniki runtime | Pomocniki runtime/logowania/kopii zapasowych/instalacji pluginów |
|
||||
| `plugin-sdk/runtime-env` | Wąskie pomocniki środowiska runtime | Logger/runtime env, timeout, retry i pomocniki backoff |
|
||||
| `plugin-sdk/plugin-runtime` | Współdzielone pomocniki runtime pluginów | Pomocniki poleceń/hooków/http/interakcji pluginów |
|
||||
| `plugin-sdk/hook-runtime` | Pomocniki potoku hooków | Współdzielone pomocniki potoku webhooków/wewnętrznych hooków |
|
||||
| `plugin-sdk/lazy-runtime` | Pomocniki leniwego runtime | `createLazyRuntimeModule`, `createLazyRuntimeMethod`, `createLazyRuntimeMethodBinder`, `createLazyRuntimeNamedExport`, `createLazyRuntimeSurface` |
|
||||
| `plugin-sdk/process-runtime` | Pomocniki procesów | Współdzielone pomocniki exec |
|
||||
| `plugin-sdk/cli-runtime` | Pomocniki runtime CLI | Formatowanie poleceń, oczekiwania, pomocniki wersji |
|
||||
| `plugin-sdk/gateway-runtime` | Pomocniki gateway | Klient gateway i pomocniki łat statusu kanału |
|
||||
| `plugin-sdk/config-runtime` | Pomocniki konfiguracji | Pomocniki ładowania/zapisu konfiguracji |
|
||||
| `plugin-sdk/telegram-command-config` | Pomocniki poleceń Telegram | Pomocniki walidacji poleceń Telegram stabilne jako fallback, gdy powierzchnia kontraktu dołączonego Telegram jest niedostępna |
|
||||
| `plugin-sdk/approval-runtime` | Pomocniki promptów zatwierdzeń | Payload exec/plugin approval, pomocniki approval capability/profile, natywne pomocniki routingu/runtime zatwierdzeń |
|
||||
| `plugin-sdk/approval-auth-runtime` | Pomocniki auth zatwierdzeń | Rozstrzyganie osoby zatwierdzającej, uwierzytelnianie akcji w tym samym czacie |
|
||||
| `plugin-sdk/approval-client-runtime` | Pomocniki klienta zatwierdzeń | Natywne pomocniki profili/filtrów zatwierdzeń exec |
|
||||
| `plugin-sdk/approval-delivery-runtime` | Pomocniki dostarczania zatwierdzeń | Adaptery natywnych approval capability/delivery |
|
||||
| `plugin-sdk/approval-gateway-runtime` | Pomocniki gateway zatwierdzeń | Współdzielony pomocnik rozstrzygania approval gateway |
|
||||
| `plugin-sdk/approval-handler-adapter-runtime` | Pomocniki adaptera zatwierdzeń | Lekkie pomocniki ładowania natywnych adapterów zatwierdzeń dla gorących punktów wejścia kanałów |
|
||||
| `plugin-sdk/approval-handler-runtime` | Pomocniki handlerów zatwierdzeń | Szersze pomocniki runtime handlerów zatwierdzeń; preferuj węższe warstwy adapter/gateway, gdy wystarczą |
|
||||
| `plugin-sdk/approval-native-runtime` | Pomocniki celów zatwierdzeń | Pomocniki natywnych powiązań celu/konta zatwierdzeń |
|
||||
| `plugin-sdk/approval-reply-runtime` | Pomocniki odpowiedzi zatwierdzeń | Pomocniki payloadów odpowiedzi exec/plugin approval |
|
||||
| `plugin-sdk/channel-runtime-context` | Pomocniki channel runtime-context | Ogólne pomocniki register/get/watch dla channel runtime-context |
|
||||
| `plugin-sdk/security-runtime` | Pomocniki bezpieczeństwa | Współdzielone pomocniki trust, bramkowania DM, treści zewnętrznych i zbierania sekretów |
|
||||
| `plugin-sdk/ssrf-policy` | Pomocniki polityki SSRF | Pomocniki allowlist hostów i polityki sieci prywatnych |
|
||||
| `plugin-sdk/ssrf-runtime` | Pomocniki runtime SSRF | Pinned-dispatcher, guarded fetch, pomocniki polityki SSRF |
|
||||
| `plugin-sdk/collection-runtime` | Pomocniki ograniczonej pamięci podręcznej | `pruneMapToMaxSize` |
|
||||
| `plugin-sdk/diagnostic-runtime` | Pomocniki bramkowania diagnostyki | `isDiagnosticFlagEnabled`, `isDiagnosticsEnabled` |
|
||||
| `plugin-sdk/error-runtime` | Pomocniki formatowania błędów | `formatUncaughtError`, `isApprovalNotFoundError`, pomocniki grafu błędów |
|
||||
| `plugin-sdk/fetch-runtime` | Pomocniki opakowanego fetch/proxy | `resolveFetch`, pomocniki proxy |
|
||||
| `plugin-sdk/host-runtime` | Pomocniki normalizacji hosta | `normalizeHostname`, `normalizeScpRemoteHost` |
|
||||
| `plugin-sdk/retry-runtime` | Pomocniki retry | `RetryConfig`, `retryAsync`, uruchamiacze polityk |
|
||||
| `plugin-sdk/allow-from` | Formatowanie allowlist | `formatAllowFromLowercase` |
|
||||
| `plugin-sdk/allowlist-resolution` | Mapowanie wejść allowlist | `mapAllowlistResolutionInputs` |
|
||||
| `plugin-sdk/command-auth` | Bramkowanie poleceń i pomocniki powierzchni poleceń | `resolveControlCommandGate`, pomocniki autoryzacji nadawcy, pomocniki rejestru poleceń |
|
||||
| `plugin-sdk/secret-input` | Parsowanie tajnych danych wejściowych | Pomocniki secret input |
|
||||
| `plugin-sdk/webhook-ingress` | Pomocniki żądań webhooków | Narzędzia celu webhooka |
|
||||
| `plugin-sdk/webhook-request-guards` | Pomocniki guardów żądań webhooków | Pomocniki odczytu/limitowania treści żądań |
|
||||
| `plugin-sdk/reply-runtime` | Współdzielony runtime odpowiedzi | Inbound dispatch, heartbeat, planner odpowiedzi, chunking |
|
||||
| `plugin-sdk/reply-dispatch-runtime` | Wąskie pomocniki dispatchu odpowiedzi | Finalizacja + pomocniki dispatchu dostawcy |
|
||||
| `plugin-sdk/reply-history` | Pomocniki historii odpowiedzi | `buildHistoryContext`, `buildPendingHistoryContextFromMap`, `recordPendingHistoryEntry`, `clearHistoryEntriesIfEnabled` |
|
||||
| `plugin-sdk/reply-reference` | Planowanie referencji odpowiedzi | `createReplyReferencePlanner` |
|
||||
| `plugin-sdk/reply-chunking` | Helpery chunków odpowiedzi | Helpery dzielenia tekstu/Markdown |
|
||||
| `plugin-sdk/session-store-runtime` | Helpery session store | Helpery ścieżki store i updated-at |
|
||||
| `plugin-sdk/state-paths` | Helpery ścieżek stanu | Helpery katalogów stanu i OAuth |
|
||||
| `plugin-sdk/routing` | Helpery routingu/kluczy sesji | `resolveAgentRoute`, `buildAgentSessionKey`, `resolveDefaultAgentBoundAccountId`, helpery normalizacji klucza sesji |
|
||||
| `plugin-sdk/status-helpers` | Helpery statusu kanałów | Buildery podsumowania statusu kanału/konta, domyślne wartości stanu runtime, helpery metadanych problemów |
|
||||
| `plugin-sdk/target-resolver-runtime` | Helpery rozstrzygania celu | Wspólne helpery rozstrzygania celu |
|
||||
| `plugin-sdk/string-normalization-runtime` | Helpery normalizacji ciągów | Helpery normalizacji slugów/ciągów |
|
||||
| `plugin-sdk/request-url` | Helpery URL żądania | Wyodrębnianie tekstowych URL-i z wejść podobnych do żądania |
|
||||
| `plugin-sdk/run-command` | Helpery poleceń z pomiarem czasu | Runner poleceń z normalizowanym stdout/stderr |
|
||||
| `plugin-sdk/param-readers` | Odczytywacze parametrów | Typowe odczytywacze parametrów narzędzi/CLI |
|
||||
| `plugin-sdk/tool-send` | Ekstrakcja wysyłki narzędzia | Wyodrębnianie kanonicznych pól celu wysyłki z argumentów narzędzia |
|
||||
| `plugin-sdk/temp-path` | Helpery ścieżek tymczasowych | Wspólne helpery ścieżek tymczasowego pobierania |
|
||||
| `plugin-sdk/logging-core` | Helpery logowania | Logger podsystemu i helpery redakcji |
|
||||
| `plugin-sdk/markdown-table-runtime` | Helpery tabel Markdown | Helpery trybu tabel Markdown |
|
||||
| `plugin-sdk/reply-payload` | Typy ładunku odpowiedzi | Typy ładunku odpowiedzi |
|
||||
| `plugin-sdk/provider-setup` | Kuratorowane helpery konfiguracji lokalnego/self-hosted dostawcy | Helpery wykrywania/konfiguracji self-hosted dostawcy |
|
||||
| `plugin-sdk/self-hosted-provider-setup` | Precyzyjne helpery konfiguracji self-hosted dostawców zgodnych z OpenAI | Te same helpery wykrywania/konfiguracji self-hosted dostawcy |
|
||||
| `plugin-sdk/provider-auth-runtime` | Helpery runtime uwierzytelniania dostawcy | Helpery rozstrzygania kluczy API w runtime |
|
||||
| `plugin-sdk/provider-auth-api-key` | Helpery konfiguracji klucza API dostawcy | Helpery onboardingu/zapisu profilu dla kluczy API |
|
||||
| `plugin-sdk/provider-auth-result` | Helpery wyniku uwierzytelniania dostawcy | Standardowy builder wyniku uwierzytelniania OAuth |
|
||||
| `plugin-sdk/provider-auth-login` | Helpery interaktywnego logowania dostawcy | Wspólne helpery interaktywnego logowania |
|
||||
| `plugin-sdk/provider-env-vars` | Helpery zmiennych środowiskowych dostawcy | Helpery wyszukiwania zmiennych środowiskowych uwierzytelniania dostawcy |
|
||||
| `plugin-sdk/provider-model-shared` | Wspólne helpery modeli/replay dostawców | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`, wspólne buildery polityki replay, helpery punktów końcowych dostawcy i helpery normalizacji identyfikatorów modeli |
|
||||
| `plugin-sdk/provider-catalog-shared` | Wspólne helpery katalogu dostawcy | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat` |
|
||||
| `plugin-sdk/provider-onboard` | Poprawki onboardingu dostawcy | Helpery konfiguracji onboardingu |
|
||||
| `plugin-sdk/provider-http` | Helpery HTTP dostawcy | Generyczne helpery HTTP/zdolności punktów końcowych dostawcy |
|
||||
| `plugin-sdk/provider-web-fetch` | Helpery web-fetch dostawcy | Helpery rejestracji/cache dostawcy web-fetch |
|
||||
| `plugin-sdk/provider-web-search-contract` | Helpery kontraktu web-search dostawcy | Wąskie helpery kontraktu konfiguracji/poświadczeń web-search, takie jak `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig` oraz zakresowane settery/gettery poświadczeń |
|
||||
| `plugin-sdk/provider-web-search` | Helpery web-search dostawcy | Helpery rejestracji/cache/runtime dostawcy web-search |
|
||||
| `plugin-sdk/provider-tools` | Helpery zgodności narzędzi/schematów dostawcy | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, czyszczenie schematów Gemini + diagnostyka oraz helpery zgodności xAI, takie jak `resolveXaiModelCompatPatch` / `applyXaiModelCompat` |
|
||||
| `plugin-sdk/provider-usage` | Helpery użycia dostawcy | `fetchClaudeUsage`, `fetchGeminiUsage`, `fetchGithubCopilotUsage` i inne helpery użycia dostawcy |
|
||||
| `plugin-sdk/provider-stream` | Helpery wrapperów strumieni dostawcy | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`, typy wrapperów strumieni oraz wspólne helpery wrapperów Anthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot |
|
||||
| `plugin-sdk/keyed-async-queue` | Uporządkowana kolejka asynchroniczna | `KeyedAsyncQueue` |
|
||||
| `plugin-sdk/media-runtime` | Wspólne helpery mediów | Helpery pobierania/transformacji/przechowywania mediów oraz buildery ładunków mediów |
|
||||
| `plugin-sdk/media-generation-runtime` | Wspólne helpery generowania mediów | Wspólne helpery failover, wybór kandydatów i komunikaty o brakującym modelu dla generowania obrazów/wideo/muzyki |
|
||||
| `plugin-sdk/media-understanding` | Helpery rozumienia mediów | Typy dostawców rozumienia mediów oraz eksporty helperów obrazów/audio dla dostawców |
|
||||
| `plugin-sdk/text-runtime` | Wspólne helpery tekstu | Usuwanie tekstu widocznego dla asystenta, helpery renderowania/chunkingu/tabel Markdown, helpery redakcji, helpery znaczników dyrektyw, narzędzia bezpiecznego tekstu i powiązane helpery tekstu/logowania |
|
||||
| `plugin-sdk/text-chunking` | Helpery chunkingu tekstu | Helper dzielenia tekstu wychodzącego na chunki |
|
||||
| `plugin-sdk/speech` | Helpery mowy | Typy dostawców mowy oraz eksporty helperów dyrektyw, rejestru i walidacji dla dostawców |
|
||||
| `plugin-sdk/speech-core` | Wspólny rdzeń mowy | Typy dostawców mowy, rejestr, dyrektywy, normalizacja |
|
||||
| `plugin-sdk/realtime-transcription` | Helpery transkrypcji realtime | Typy dostawców i helpery rejestru |
|
||||
| `plugin-sdk/realtime-voice` | Helpery głosu realtime | Typy dostawców i helpery rejestru |
|
||||
| `plugin-sdk/image-generation-core` | Wspólny rdzeń generowania obrazów | Typy generowania obrazów, failover, uwierzytelnianie i helpery rejestru |
|
||||
| `plugin-sdk/music-generation` | Helpery generowania muzyki | Typy dostawców/żądań/wyników generowania muzyki |
|
||||
| `plugin-sdk/music-generation-core` | Wspólny rdzeń generowania muzyki | Typy generowania muzyki, helpery failover, wyszukiwanie dostawcy i parsowanie model-ref |
|
||||
| `plugin-sdk/video-generation` | Helpery generowania wideo | Typy dostawców/żądań/wyników generowania wideo |
|
||||
| `plugin-sdk/video-generation-core` | Wspólny rdzeń generowania wideo | Typy generowania wideo, helpery failover, wyszukiwanie dostawcy i parsowanie model-ref |
|
||||
| `plugin-sdk/interactive-runtime` | Helpery odpowiedzi interaktywnych | Normalizacja/redukcja ładunku odpowiedzi interaktywnych |
|
||||
| `plugin-sdk/reply-chunking` | Pomocniki dzielenia odpowiedzi | Pomocniki dzielenia tekstu/markdown |
|
||||
| `plugin-sdk/session-store-runtime` | Pomocniki magazynu sesji | Ścieżka magazynu + pomocniki updated-at |
|
||||
| `plugin-sdk/state-paths` | Pomocniki ścieżek stanu | Pomocniki katalogów stanu i OAuth |
|
||||
| `plugin-sdk/routing` | Pomocniki routingu/kluczy sesji | `resolveAgentRoute`, `buildAgentSessionKey`, `resolveDefaultAgentBoundAccountId`, pomocniki normalizacji kluczy sesji |
|
||||
| `plugin-sdk/status-helpers` | Pomocniki statusu kanału | Buildery podsumowań statusu kanału/konta, domyślne stany runtime, pomocniki metadanych problemów |
|
||||
| `plugin-sdk/target-resolver-runtime` | Pomocniki rozstrzygania celów | Współdzielone pomocniki target resolver |
|
||||
| `plugin-sdk/string-normalization-runtime` | Pomocniki normalizacji tekstu | Pomocniki normalizacji slugów/ciągów |
|
||||
| `plugin-sdk/request-url` | Pomocniki URL żądań | Wyodrębnianie URL jako ciągów z danych wejściowych podobnych do żądania |
|
||||
| `plugin-sdk/run-command` | Pomocniki poleceń z pomiarem czasu | Runner poleceń z normalizowanym stdout/stderr |
|
||||
| `plugin-sdk/param-readers` | Czytniki parametrów | Typowe czytniki parametrów narzędzi/CLI |
|
||||
| `plugin-sdk/tool-send` | Wyodrębnianie wysyłki z narzędzia | Wyodrębnianie kanonicznych pól celu wysyłki z argumentów narzędzia |
|
||||
| `plugin-sdk/temp-path` | Pomocniki ścieżek tymczasowych | Współdzielone pomocniki ścieżek tymczasowych pobrań |
|
||||
| `plugin-sdk/logging-core` | Pomocniki logowania | Logger podsystemu i pomocniki redakcji |
|
||||
| `plugin-sdk/markdown-table-runtime` | Pomocniki tabel markdown | Pomocniki trybów tabel markdown |
|
||||
| `plugin-sdk/reply-payload` | Typy payloadów odpowiedzi | Typy payloadów odpowiedzi wiadomości |
|
||||
| `plugin-sdk/provider-setup` | Dobrane pomocniki konfiguracji lokalnych/samohostowanych dostawców | Pomocniki wykrywania/konfiguracji samohostowanych dostawców |
|
||||
| `plugin-sdk/self-hosted-provider-setup` | Ukierunkowane pomocniki konfiguracji samohostowanych dostawców zgodnych z OpenAI | Te same pomocniki wykrywania/konfiguracji samohostowanych dostawców |
|
||||
| `plugin-sdk/provider-auth-runtime` | Pomocniki auth runtime dostawców | Pomocniki rozstrzygania kluczy API runtime |
|
||||
| `plugin-sdk/provider-auth-api-key` | Pomocniki konfiguracji kluczy API dostawców | Pomocniki onboardingu/zapisu profilu dla kluczy API |
|
||||
| `plugin-sdk/provider-auth-result` | Pomocniki wyników auth dostawców | Standardowy builder wyniku auth OAuth |
|
||||
| `plugin-sdk/provider-auth-login` | Pomocniki interaktywnego logowania dostawców | Współdzielone pomocniki interaktywnego logowania |
|
||||
| `plugin-sdk/provider-env-vars` | Pomocniki zmiennych środowiskowych dostawców | Pomocniki wyszukiwania zmiennych środowiskowych auth dostawców |
|
||||
| `plugin-sdk/provider-model-shared` | Współdzielone pomocniki modeli/replay dostawców | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`, współdzielone buildery polityk replay, pomocniki endpointów dostawców i normalizacji identyfikatorów modeli |
|
||||
| `plugin-sdk/provider-catalog-shared` | Współdzielone pomocniki katalogów dostawców | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat` |
|
||||
| `plugin-sdk/provider-onboard` | Łatki onboardingu dostawców | Pomocniki konfiguracji onboardingu |
|
||||
| `plugin-sdk/provider-http` | Pomocniki HTTP dostawców | Ogólne pomocniki HTTP/możliwości endpointów dostawców |
|
||||
| `plugin-sdk/provider-web-fetch` | Pomocniki web-fetch dostawców | Pomocniki rejestracji/cache dostawców web-fetch |
|
||||
| `plugin-sdk/provider-web-search-contract` | Pomocniki kontraktu web-search dostawców | Wąskie pomocniki kontraktu konfiguracji/poświadczeń web-search, takie jak `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig` oraz funkcje ustawiania/pobierania poświadczeń o ograniczonym zakresie |
|
||||
| `plugin-sdk/provider-web-search` | Pomocniki web-search dostawców | Pomocniki rejestracji/cache/runtime dostawców web-search |
|
||||
| `plugin-sdk/provider-tools` | Pomocniki zgodności narzędzi/schematów dostawców | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, czyszczenie schematów Gemini + diagnostyka oraz pomocniki zgodności xAI, takie jak `resolveXaiModelCompatPatch` / `applyXaiModelCompat` |
|
||||
| `plugin-sdk/provider-usage` | Pomocniki użycia dostawców | `fetchClaudeUsage`, `fetchGeminiUsage`, `fetchGithubCopilotUsage` i inne pomocniki użycia dostawców |
|
||||
| `plugin-sdk/provider-stream` | Pomocniki wrapperów strumieni dostawców | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`, typy wrapperów strumieni oraz współdzielone pomocniki wrapperów Anthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot |
|
||||
| `plugin-sdk/keyed-async-queue` | Uporządkowana kolejka async | `KeyedAsyncQueue` |
|
||||
| `plugin-sdk/media-runtime` | Współdzielone pomocniki mediów | Pomocniki pobierania/przekształcania/przechowywania mediów oraz buildery payloadów mediów |
|
||||
| `plugin-sdk/media-generation-runtime` | Współdzielone pomocniki generowania mediów | Współdzielone pomocniki failover, wyboru kandydatów i komunikatów o braku modeli dla generowania obrazów/wideo/muzyki |
|
||||
| `plugin-sdk/media-understanding` | Pomocniki media-understanding | Typy dostawców media understanding oraz eksporty pomocników obrazów/audio dla dostawców |
|
||||
| `plugin-sdk/text-runtime` | Współdzielone pomocniki tekstu | Usuwanie tekstu widocznego dla asystenta, pomocniki renderowania/dzielenia/tabel markdown, redakcji, tagów dyrektyw, bezpiecznego tekstu oraz powiązane pomocniki tekstowe/logowania |
|
||||
| `plugin-sdk/text-chunking` | Pomocniki dzielenia tekstu | Pomocnik dzielenia tekstu wychodzącego |
|
||||
| `plugin-sdk/speech` | Pomocniki speech | Typy dostawców speech oraz eksporty pomocników dyrektyw, rejestru i walidacji dla dostawców |
|
||||
| `plugin-sdk/speech-core` | Współdzielony rdzeń speech | Typy dostawców speech, rejestr, dyrektywy, normalizacja |
|
||||
| `plugin-sdk/realtime-transcription` | Pomocniki transkrypcji realtime | Typy dostawców i pomocniki rejestru |
|
||||
| `plugin-sdk/realtime-voice` | Pomocniki głosu realtime | Typy dostawców i pomocniki rejestru |
|
||||
| `plugin-sdk/image-generation-core` | Współdzielony rdzeń generowania obrazów | Pomocniki typów, failover, auth i rejestru generowania obrazów |
|
||||
| `plugin-sdk/music-generation` | Pomocniki generowania muzyki | Typy dostawców/żądań/wyników generowania muzyki |
|
||||
| `plugin-sdk/music-generation-core` | Współdzielony rdzeń generowania muzyki | Pomocniki typów, failover, wyszukiwania dostawców i parsowania model-ref dla generowania muzyki |
|
||||
| `plugin-sdk/video-generation` | Pomocniki generowania wideo | Typy dostawców/żądań/wyników generowania wideo |
|
||||
| `plugin-sdk/video-generation-core` | Współdzielony rdzeń generowania wideo | Pomocniki typów, failover, wyszukiwania dostawców i parsowania model-ref dla generowania wideo |
|
||||
| `plugin-sdk/interactive-runtime` | Pomocniki odpowiedzi interaktywnych | Normalizacja/redukcja payloadów odpowiedzi interaktywnych |
|
||||
| `plugin-sdk/channel-config-primitives` | Prymitywy konfiguracji kanału | Wąskie prymitywy channel config-schema |
|
||||
| `plugin-sdk/channel-config-writes` | Helpery zapisu konfiguracji kanału | Helpery autoryzacji zapisu konfiguracji kanału |
|
||||
| `plugin-sdk/channel-plugin-common` | Wspólne preludium kanału | Wspólne eksporty preludium wtyczki kanału |
|
||||
| `plugin-sdk/channel-status` | Helpery statusu kanału | Wspólne helpery snapshotów/podsumowań statusu kanału |
|
||||
| `plugin-sdk/allowlist-config-edit` | Helpery konfiguracji allowlisty | Helpery edycji/odczytu konfiguracji allowlisty |
|
||||
| `plugin-sdk/group-access` | Helpery dostępu grupowego | Wspólne helpery decyzji dostępu grupowego |
|
||||
| `plugin-sdk/direct-dm` | Helpery direct-DM | Wspólne helpery uwierzytelniania/ochrony direct-DM |
|
||||
| `plugin-sdk/extension-shared` | Wspólne helpery rozszerzeń | Prymitywy pomocnicze dla pasywnego kanału/statusu i ambient proxy |
|
||||
| `plugin-sdk/webhook-targets` | Helpery celów webhook | Rejestr celów webhook i helpery instalacji tras |
|
||||
| `plugin-sdk/webhook-path` | Helpery ścieżek webhook | Helpery normalizacji ścieżek webhook |
|
||||
| `plugin-sdk/web-media` | Wspólne helpery mediów web | Helpery ładowania zdalnych/lokalnych mediów |
|
||||
| `plugin-sdk/zod` | Re-eksport Zod | Re-eksportowany `zod` dla użytkowników plugin SDK |
|
||||
| `plugin-sdk/memory-core` | Dołączone helpery memory-core | Powierzchnia helperów menedżera pamięci/konfiguracji/plików/CLI |
|
||||
| `plugin-sdk/channel-config-writes` | Pomocniki zapisu konfiguracji kanału | Pomocniki autoryzacji zapisu konfiguracji kanału |
|
||||
| `plugin-sdk/channel-plugin-common` | Wspólny prelude kanału | Eksporty wspólnego preludium pluginu kanału |
|
||||
| `plugin-sdk/channel-status` | Pomocniki statusu kanału | Współdzielone pomocniki snapshotów/podsumowań statusu kanału |
|
||||
| `plugin-sdk/allowlist-config-edit` | Pomocniki konfiguracji allowlist | Pomocniki edycji/odczytu konfiguracji allowlist |
|
||||
| `plugin-sdk/group-access` | Pomocniki dostępu grupowego | Współdzielone pomocniki decyzji o dostępie grupowym |
|
||||
| `plugin-sdk/direct-dm` | Pomocniki bezpośrednich DM | Współdzielone pomocniki auth/guard bezpośrednich DM |
|
||||
| `plugin-sdk/extension-shared` | Współdzielone pomocniki rozszerzeń | Prymitywy pomocników pasywnego kanału/statusu i ambient proxy |
|
||||
| `plugin-sdk/webhook-targets` | Pomocniki celów webhooków | Rejestr celów webhooków i pomocniki instalacji tras |
|
||||
| `plugin-sdk/webhook-path` | Pomocniki ścieżek webhooków | Pomocniki normalizacji ścieżek webhooków |
|
||||
| `plugin-sdk/web-media` | Współdzielone pomocniki web media | Pomocniki ładowania zdalnych/lokalnych mediów |
|
||||
| `plugin-sdk/zod` | Reeksport Zod | Reeksport `zod` dla użytkowników Plugin SDK |
|
||||
| `plugin-sdk/memory-core` | Dołączone pomocniki memory-core | Powierzchnia pomocników menedżera/konfiguracji/plików/CLI pamięci |
|
||||
| `plugin-sdk/memory-core-engine-runtime` | Fasada runtime silnika pamięci | Fasada runtime indeksu/wyszukiwania pamięci |
|
||||
| `plugin-sdk/memory-core-host-engine-foundation` | Silnik podstawowy hosta pamięci | Eksporty silnika podstawowego hosta pamięci |
|
||||
| `plugin-sdk/memory-core-host-engine-foundation` | Bazowy silnik hosta pamięci | Eksporty bazowego silnika hosta pamięci |
|
||||
| `plugin-sdk/memory-core-host-engine-embeddings` | Silnik embeddingów hosta pamięci | Eksporty silnika embeddingów hosta pamięci |
|
||||
| `plugin-sdk/memory-core-host-engine-qmd` | Silnik QMD hosta pamięci | Eksporty silnika QMD hosta pamięci |
|
||||
| `plugin-sdk/memory-core-host-engine-storage` | Silnik przechowywania hosta pamięci | Eksporty silnika przechowywania hosta pamięci |
|
||||
| `plugin-sdk/memory-core-host-multimodal` | Multimodalne helpery hosta pamięci | Multimodalne helpery hosta pamięci |
|
||||
| `plugin-sdk/memory-core-host-query` | Helpery zapytań hosta pamięci | Helpery zapytań hosta pamięci |
|
||||
| `plugin-sdk/memory-core-host-secret` | Helpery sekretów hosta pamięci | Helpery sekretów hosta pamięci |
|
||||
| `plugin-sdk/memory-core-host-events` | Helpery dziennika zdarzeń hosta pamięci | Helpery dziennika zdarzeń hosta pamięci |
|
||||
| `plugin-sdk/memory-core-host-status` | Helpery statusu hosta pamięci | Helpery statusu hosta pamięci |
|
||||
| `plugin-sdk/memory-core-host-runtime-cli` | Runtime CLI hosta pamięci | Helpery runtime CLI hosta pamięci |
|
||||
| `plugin-sdk/memory-core-host-runtime-core` | Główny runtime hosta pamięci | Helpery głównego runtime hosta pamięci |
|
||||
| `plugin-sdk/memory-core-host-runtime-files` | Helpery plików/runtime hosta pamięci | Helpery plików/runtime hosta pamięci |
|
||||
| `plugin-sdk/memory-host-core` | Alias głównego runtime hosta pamięci | Neutralny wobec dostawcy alias helperów głównego runtime hosta pamięci |
|
||||
| `plugin-sdk/memory-host-events` | Alias dziennika zdarzeń hosta pamięci | Neutralny wobec dostawcy alias helperów dziennika zdarzeń hosta pamięci |
|
||||
| `plugin-sdk/memory-host-files` | Alias plików/runtime hosta pamięci | Neutralny wobec dostawcy alias helperów plików/runtime hosta pamięci |
|
||||
| `plugin-sdk/memory-host-markdown` | Helpery zarządzanego Markdown | Wspólne helpery zarządzanego Markdown dla wtyczek związanych z pamięcią |
|
||||
| `plugin-sdk/memory-core-host-multimodal` | Wielomodalne pomocniki hosta pamięci | Wielomodalne pomocniki hosta pamięci |
|
||||
| `plugin-sdk/memory-core-host-query` | Pomocniki zapytań hosta pamięci | Pomocniki zapytań hosta pamięci |
|
||||
| `plugin-sdk/memory-core-host-secret` | Pomocniki sekretów hosta pamięci | Pomocniki sekretów hosta pamięci |
|
||||
| `plugin-sdk/memory-core-host-events` | Pomocniki dziennika zdarzeń hosta pamięci | Pomocniki dziennika zdarzeń hosta pamięci |
|
||||
| `plugin-sdk/memory-core-host-status` | Pomocniki statusu hosta pamięci | Pomocniki statusu hosta pamięci |
|
||||
| `plugin-sdk/memory-core-host-runtime-cli` | Runtime CLI hosta pamięci | Pomocniki runtime CLI hosta pamięci |
|
||||
| `plugin-sdk/memory-core-host-runtime-core` | Runtime core hosta pamięci | Pomocniki runtime core hosta pamięci |
|
||||
| `plugin-sdk/memory-core-host-runtime-files` | Pomocniki plików/runtime hosta pamięci | Pomocniki plików/runtime hosta pamięci |
|
||||
| `plugin-sdk/memory-host-core` | Alias runtime core hosta pamięci | Neutralny względem dostawcy alias pomocników runtime core hosta pamięci |
|
||||
| `plugin-sdk/memory-host-events` | Alias dziennika zdarzeń hosta pamięci | Neutralny względem dostawcy alias pomocników dziennika zdarzeń hosta pamięci |
|
||||
| `plugin-sdk/memory-host-files` | Alias plików/runtime hosta pamięci | Neutralny względem dostawcy alias pomocników plików/runtime hosta pamięci |
|
||||
| `plugin-sdk/memory-host-markdown` | Pomocniki zarządzanego markdown | Współdzielone pomocniki zarządzanego markdown dla pluginów powiązanych z pamięcią |
|
||||
| `plugin-sdk/memory-host-search` | Fasada aktywnego wyszukiwania pamięci | Leniwa fasada runtime menedżera wyszukiwania aktywnej pamięci |
|
||||
| `plugin-sdk/memory-host-status` | Alias statusu hosta pamięci | Neutralny wobec dostawcy alias helperów statusu hosta pamięci |
|
||||
| `plugin-sdk/memory-lancedb` | Dołączone helpery memory-lancedb | Powierzchnia helperów memory-lancedb |
|
||||
| `plugin-sdk/testing` | Narzędzia testowe | Helpery testowe i mocki |
|
||||
| `plugin-sdk/memory-host-status` | Alias statusu hosta pamięci | Neutralny względem dostawcy alias pomocników statusu hosta pamięci |
|
||||
| `plugin-sdk/memory-lancedb` | Dołączone pomocniki memory-lancedb | Powierzchnia pomocników memory-lancedb |
|
||||
| `plugin-sdk/testing` | Narzędzia testowe | Pomocniki testowe i mocki |
|
||||
</Accordion>
|
||||
|
||||
Ta tabela celowo obejmuje typowy podzbiór migracyjny, a nie pełną powierzchnię
|
||||
SDK. Pełna lista ponad 200 punktów wejścia znajduje się w
|
||||
Ta tabela celowo obejmuje wspólny podzbiór do migracji, a nie pełną powierzchnię SDK.
|
||||
Pełna lista ponad 200 punktów wejścia znajduje się w
|
||||
`scripts/lib/plugin-sdk-entrypoints.json`.
|
||||
|
||||
Ta lista nadal obejmuje niektóre pomocnicze granice dołączonych wtyczek, takie jak
|
||||
Ta lista nadal zawiera niektóre warstwy pomocnicze dołączonych pluginów, takie jak
|
||||
`plugin-sdk/feishu`, `plugin-sdk/feishu-setup`, `plugin-sdk/zalo`,
|
||||
`plugin-sdk/zalo-setup` oraz `plugin-sdk/matrix*`. Pozostają one eksportowane na potrzeby
|
||||
utrzymania i zgodności dołączonych wtyczek, ale są celowo pominięte w typowej tabeli migracyjnej
|
||||
i nie są zalecanym celem dla nowego kodu wtyczek.
|
||||
`plugin-sdk/zalo-setup` i `plugin-sdk/matrix*`. Nadal są one eksportowane dla
|
||||
utrzymania zgodności i konserwacji dołączonych pluginów, ale celowo
|
||||
pominięto je w tabeli najczęstszych migracji i nie są zalecanym celem dla
|
||||
nowego kodu pluginów.
|
||||
|
||||
Ta sama zasada dotyczy innych rodzin dołączonych helperów, takich jak:
|
||||
Ta sama zasada dotyczy innych rodzin dołączonych pomocników, takich jak:
|
||||
|
||||
- helpery obsługi przeglądarki: `plugin-sdk/browser-cdp`, `plugin-sdk/browser-config-runtime`, `plugin-sdk/browser-config-support`, `plugin-sdk/browser-control-auth`, `plugin-sdk/browser-node-runtime`, `plugin-sdk/browser-profiles`, `plugin-sdk/browser-security-runtime`, `plugin-sdk/browser-setup-tools`, `plugin-sdk/browser-support`
|
||||
- pomocniki wsparcia przeglądarki: `plugin-sdk/browser-cdp`, `plugin-sdk/browser-config-runtime`, `plugin-sdk/browser-config-support`, `plugin-sdk/browser-control-auth`, `plugin-sdk/browser-node-runtime`, `plugin-sdk/browser-profiles`, `plugin-sdk/browser-security-runtime`, `plugin-sdk/browser-setup-tools`, `plugin-sdk/browser-support`
|
||||
- Matrix: `plugin-sdk/matrix*`
|
||||
- LINE: `plugin-sdk/line*`
|
||||
- IRC: `plugin-sdk/irc*`
|
||||
- dołączone powierzchnie helperów/wtyczek, takie jak `plugin-sdk/googlechat`,
|
||||
- dołączone powierzchnie pomocnicze/pluginów, takie jak `plugin-sdk/googlechat`,
|
||||
`plugin-sdk/zalouser`, `plugin-sdk/bluebubbles*`,
|
||||
`plugin-sdk/mattermost*`, `plugin-sdk/msteams`,
|
||||
`plugin-sdk/nextcloud-talk`, `plugin-sdk/nostr`, `plugin-sdk/tlon`,
|
||||
`plugin-sdk/twitch`,
|
||||
`plugin-sdk/github-copilot-login`, `plugin-sdk/github-copilot-token`,
|
||||
`plugin-sdk/diagnostics-otel`, `plugin-sdk/diffs`, `plugin-sdk/llm-task`,
|
||||
`plugin-sdk/thread-ownership` oraz `plugin-sdk/voice-call`
|
||||
`plugin-sdk/thread-ownership` i `plugin-sdk/voice-call`
|
||||
|
||||
`plugin-sdk/github-copilot-token` obecnie udostępnia wąską powierzchnię
|
||||
helperów tokena `DEFAULT_COPILOT_API_BASE_URL`,
|
||||
`deriveCopilotApiBaseUrlFromToken` i `resolveCopilotApiToken`.
|
||||
`plugin-sdk/github-copilot-token` obecnie udostępnia wąską
|
||||
powierzchnię pomocników tokenów `DEFAULT_COPILOT_API_BASE_URL`,
|
||||
`deriveCopilotApiBaseUrlFromToken` oraz `resolveCopilotApiToken`.
|
||||
|
||||
Używaj możliwie najwęższego importu, który pasuje do zadania. Jeśli nie możesz znaleźć eksportu,
|
||||
sprawdź źródło w `src/plugin-sdk/` lub zapytaj na Discord.
|
||||
Używaj najwęższego importu, który pasuje do zadania. Jeśli nie możesz znaleźć eksportu,
|
||||
sprawdź źródło w `src/plugin-sdk/` albo zapytaj na Discord.
|
||||
|
||||
## Harmonogram usunięcia
|
||||
|
||||
| Kiedy | Co się dzieje |
|
||||
| Kiedy | Co się dzieje |
|
||||
| ---------------------- | ----------------------------------------------------------------------- |
|
||||
| **Teraz** | Przestarzałe powierzchnie emitują ostrzeżenia w czasie wykonywania |
|
||||
| **Następna główna wersja** | Przestarzałe powierzchnie zostaną usunięte; wtyczki nadal z nich korzystające przestaną działać |
|
||||
| **Teraz** | Przestarzałe powierzchnie emitują ostrzeżenia w czasie działania |
|
||||
| **Następne główne wydanie** | Przestarzałe powierzchnie zostaną usunięte; pluginy nadal z nich korzystające przestaną działać |
|
||||
|
||||
Wszystkie główne wtyczki zostały już zmigrowane. Zewnętrzne wtyczki powinny przeprowadzić migrację
|
||||
przed następną główną wersją.
|
||||
Wszystkie główne pluginy zostały już zmigrowane. Zewnętrzne pluginy powinny przeprowadzić migrację
|
||||
przed następnym głównym wydaniem.
|
||||
|
||||
## Tymczasowe wyciszenie ostrzeżeń
|
||||
|
||||
@ -369,9 +399,9 @@ To tymczasowa furtka awaryjna, a nie trwałe rozwiązanie.
|
||||
|
||||
## Powiązane
|
||||
|
||||
- [Pierwsze kroki](/pl/plugins/building-plugins) — zbuduj swoją pierwszą wtyczkę
|
||||
- [Przegląd SDK](/pl/plugins/sdk-overview) — pełna dokumentacja importów ścieżek podrzędnych
|
||||
- [Wtyczki kanałów](/pl/plugins/sdk-channel-plugins) — budowanie wtyczek kanałów
|
||||
- [Wtyczki dostawców](/pl/plugins/sdk-provider-plugins) — budowanie wtyczek dostawców
|
||||
- [Wnętrze wtyczek](/pl/plugins/architecture) — szczegółowe omówienie architektury
|
||||
- [Manifest wtyczki](/pl/plugins/manifest) — dokumentacja schematu manifestu
|
||||
- [Getting Started](/pl/plugins/building-plugins) — zbuduj swój pierwszy plugin
|
||||
- [SDK Overview](/pl/plugins/sdk-overview) — pełna dokumentacja importów podścieżek
|
||||
- [Channel Plugins](/pl/plugins/sdk-channel-plugins) — budowanie pluginów kanałów
|
||||
- [Provider Plugins](/pl/plugins/sdk-provider-plugins) — budowanie pluginów dostawców
|
||||
- [Plugin Internals](/pl/plugins/architecture) — szczegółowe omówienie architektury
|
||||
- [Plugin Manifest](/pl/plugins/manifest) — dokumentacja schematu manifestu
|
||||
|
||||
@ -1,72 +1,71 @@
|
||||
---
|
||||
read_when:
|
||||
- Musisz wiedzieć, z którego subpath SDK importować
|
||||
- Chcesz mieć referencję wszystkich metod rejestracji w OpenClawPluginApi
|
||||
- Musisz wiedzieć, z której ścieżki podrzędnej SDK importować
|
||||
- Chcesz mieć dokumentację wszystkich metod rejestracji w OpenClawPluginApi
|
||||
- Szukasz konkretnego eksportu SDK
|
||||
sidebarTitle: SDK Overview
|
||||
summary: Mapa importów, referencja API rejestracji i architektura SDK
|
||||
summary: Mapa importów, dokumentacja API rejestracji i architektura SDK
|
||||
title: Przegląd Plugin SDK
|
||||
x-i18n:
|
||||
generated_at: "2026-04-07T09:49:10Z"
|
||||
generated_at: "2026-04-08T02:18:20Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 6ba11d1708a117f3872a09fd0bebb0481d36b89b473aec861192e8c2745ef727
|
||||
source_hash: c5a41bd82d165dfbb7fbd6e4528cf322e9133a51efe55fa8518a7a0a626d9d30
|
||||
source_path: plugins/sdk-overview.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Przegląd Plugin SDK
|
||||
|
||||
Plugin SDK to typowany kontrakt między pluginami a core. Ta strona jest
|
||||
referencją dla **tego, co importować** i **co można rejestrować**.
|
||||
Plugin SDK to typowany kontrakt między pluginami a rdzeniem. Ta strona jest
|
||||
dokumentacją tego, **co importować** i **co można rejestrować**.
|
||||
|
||||
<Tip>
|
||||
**Szukasz przewodnika krok po kroku?**
|
||||
- Pierwszy plugin? Zacznij od [Getting Started](/pl/plugins/building-plugins)
|
||||
- Plugin kanału? Zobacz [Channel Plugins](/pl/plugins/sdk-channel-plugins)
|
||||
- Plugin dostawcy? Zobacz [Provider Plugins](/pl/plugins/sdk-provider-plugins)
|
||||
- Pierwszy plugin? Zacznij od [Pierwsze kroki](/pl/plugins/building-plugins)
|
||||
- Plugin kanału? Zobacz [Pluginy kanałów](/pl/plugins/sdk-channel-plugins)
|
||||
- Plugin dostawcy? Zobacz [Pluginy dostawców](/pl/plugins/sdk-provider-plugins)
|
||||
</Tip>
|
||||
|
||||
## Konwencja importu
|
||||
|
||||
Zawsze importuj z konkretnego subpath:
|
||||
Zawsze importuj z konkretnej ścieżki podrzędnej:
|
||||
|
||||
```typescript
|
||||
import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
|
||||
import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core";
|
||||
```
|
||||
|
||||
Każdy subpath to mały, samodzielny moduł. Dzięki temu uruchamianie jest szybkie i
|
||||
zapobiega to problemom z zależnościami cyklicznymi. Dla helperów wejścia/buildu specyficznych dla kanałów
|
||||
preferuj `openclaw/plugin-sdk/channel-core`; `openclaw/plugin-sdk/core` zachowaj dla
|
||||
Każda ścieżka podrzędna to mały, samowystarczalny moduł. Dzięki temu uruchamianie pozostaje szybkie
|
||||
i zapobiega to problemom z zależnościami cyklicznymi. W przypadku pomocników wejścia/budowania specyficznych dla kanału
|
||||
preferuj `openclaw/plugin-sdk/channel-core`; zachowaj `openclaw/plugin-sdk/core` dla
|
||||
szerszej powierzchni parasolowej i współdzielonych helperów, takich jak
|
||||
`buildChannelConfigSchema`.
|
||||
|
||||
Nie dodawaj ani nie opieraj się na pomocniczych interfejsach nazwanych od dostawców, takich jak
|
||||
Nie dodawaj ani nie polegaj na pomocniczych ścieżkach wygodnych nazwanych od dostawców, takich jak
|
||||
`openclaw/plugin-sdk/slack`, `openclaw/plugin-sdk/discord`,
|
||||
`openclaw/plugin-sdk/signal`, `openclaw/plugin-sdk/whatsapp` ani
|
||||
helperowych interfejsach oznaczonych marką kanału. Dołączone pluginy powinny składać ogólne
|
||||
subpathy SDK we własnych barrelach `api.ts` lub `runtime-api.ts`, a core
|
||||
powinno albo używać tych lokalnych barreli pluginu, albo dodać wąski ogólny kontrakt SDK,
|
||||
gdy potrzeba jest rzeczywiście międzykanałowa.
|
||||
pomocniczych ścieżkach markowanych kanałami. Wbudowane pluginy powinny składać ogólne
|
||||
ścieżki podrzędne SDK we własnych barrelach `api.ts` lub `runtime-api.ts`, a rdzeń
|
||||
powinien używać albo tych lokalnych barrelów pluginu, albo dodać wąski ogólny kontrakt SDK, gdy potrzeba jest rzeczywiście międzykanałowa.
|
||||
|
||||
Wygenerowana mapa eksportów nadal zawiera mały zestaw helperowych
|
||||
interfejsów dołączonych pluginów, takich jak `plugin-sdk/feishu`, `plugin-sdk/feishu-setup`,
|
||||
`plugin-sdk/zalo`, `plugin-sdk/zalo-setup` oraz `plugin-sdk/matrix*`. Te
|
||||
subpathy istnieją wyłącznie dla utrzymania zgodności i obsługi dołączonych pluginów; są
|
||||
Wygenerowana mapa eksportów nadal zawiera mały zestaw pomocniczych ścieżek dla wbudowanych pluginów,
|
||||
takich jak `plugin-sdk/feishu`, `plugin-sdk/feishu-setup`,
|
||||
`plugin-sdk/zalo`, `plugin-sdk/zalo-setup` i `plugin-sdk/matrix*`. Te
|
||||
ścieżki podrzędne istnieją wyłącznie dla utrzymania i zgodności wbudowanych pluginów; są
|
||||
celowo pominięte w poniższej wspólnej tabeli i nie są zalecaną
|
||||
ścieżką importu dla nowych pluginów zewnętrznych.
|
||||
ścieżką importu dla nowych zewnętrznych pluginów.
|
||||
|
||||
## Referencja subpath
|
||||
## Dokumentacja ścieżek podrzędnych
|
||||
|
||||
Najczęściej używane subpathy, pogrupowane według przeznaczenia. Wygenerowana pełna lista
|
||||
ponad 200 subpath znajduje się w `scripts/lib/plugin-sdk-entrypoints.json`.
|
||||
Najczęściej używane ścieżki podrzędne, pogrupowane według przeznaczenia. Wygenerowana pełna lista
|
||||
ponad 200 ścieżek podrzędnych znajduje się w `scripts/lib/plugin-sdk-entrypoints.json`.
|
||||
|
||||
Zarezerwowane helperowe subpathy dołączonych pluginów nadal pojawiają się w tej wygenerowanej liście.
|
||||
Traktuj je jako szczegół implementacyjny/powierzchnie zgodności, chyba że strona dokumentacji
|
||||
jawnie promuje któryś z nich jako publiczny.
|
||||
Zarezerwowane pomocnicze ścieżki dla wbudowanych pluginów nadal pojawiają się w tej wygenerowanej liście.
|
||||
Traktuj je jako powierzchnie szczegółów implementacyjnych/zgodności, chyba że strona dokumentacji
|
||||
jawnie promuje którąś z nich jako publiczną.
|
||||
|
||||
### Punkt wejścia pluginu
|
||||
### Wejście pluginu
|
||||
|
||||
| Subpath | Kluczowe eksporty |
|
||||
| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
@ -76,222 +75,226 @@ jawnie promuje któryś z nich jako publiczny.
|
||||
| `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` |
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Subpathy kanałów">
|
||||
<Accordion title="Ścieżki podrzędne kanałów">
|
||||
| Subpath | Kluczowe eksporty |
|
||||
| --- | --- |
|
||||
| `plugin-sdk/channel-core` | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` |
|
||||
| `plugin-sdk/config-schema` | Eksport głównego schematu Zod `openclaw.json` (`OpenClawSchema`) |
|
||||
| `plugin-sdk/channel-setup` | `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, `createOptionalChannelSetupWizard`, plus `DEFAULT_ACCOUNT_ID`, `createTopLevelChannelDmPolicy`, `setSetupChannelEnabled`, `splitSetupEntries` |
|
||||
| `plugin-sdk/setup` | Współdzielone helpery kreatora konfiguracji, prompty list dozwolonych, konstruktory statusu konfiguracji |
|
||||
| `plugin-sdk/setup` | Współdzielone helpery kreatora konfiguracji, prompty allowlist, konstruktory statusu konfiguracji |
|
||||
| `plugin-sdk/setup-runtime` | `createPatchedAccountSetupAdapter`, `createEnvPatchedAccountSetupAdapter`, `createSetupInputPresenceValidator`, `noteChannelLookupFailure`, `noteChannelLookupSummary`, `promptResolvedAllowFrom`, `splitSetupEntries`, `createAllowlistSetupWizardProxy`, `createDelegatedSetupWizardProxy` |
|
||||
| `plugin-sdk/setup-adapter-runtime` | `createEnvPatchedAccountSetupAdapter` |
|
||||
| `plugin-sdk/setup-tools` | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` |
|
||||
| `plugin-sdk/account-core` | Helpery konfiguracji/akcyjnych bramek dla wielu kont, helpery fallbacku konta domyślnego |
|
||||
| `plugin-sdk/account-id` | `DEFAULT_ACCOUNT_ID`, helpery normalizacji identyfikatorów kont |
|
||||
| `plugin-sdk/account-resolution` | Helpery wyszukiwania kont + fallbacku domyślnego |
|
||||
| `plugin-sdk/account-helpers` | Wąskie helpery list kont/akcji na kontach |
|
||||
| `plugin-sdk/account-core` | Helpery konfiguracji/wrót akcji dla wielu kont, helpery fallbacku konta domyślnego |
|
||||
| `plugin-sdk/account-id` | `DEFAULT_ACCOUNT_ID`, helpery normalizacji identyfikatora konta |
|
||||
| `plugin-sdk/account-resolution` | Helpery wyszukiwania konta + fallbacku do domyślnego |
|
||||
| `plugin-sdk/account-helpers` | Wąskie helpery listy kont/akcji na koncie |
|
||||
| `plugin-sdk/channel-pairing` | `createChannelPairingController` |
|
||||
| `plugin-sdk/channel-reply-pipeline` | `createChannelReplyPipeline` |
|
||||
| `plugin-sdk/channel-config-helpers` | `createHybridChannelConfigAdapter` |
|
||||
| `plugin-sdk/channel-config-schema` | Typy schematu konfiguracji kanału |
|
||||
| `plugin-sdk/telegram-command-config` | Helpery normalizacji/walidacji niestandardowych poleceń Telegram z fallbackiem kontraktu dołączonego |
|
||||
| `plugin-sdk/telegram-command-config` | Helpery normalizacji/walidacji niestandardowych poleceń Telegram z fallbackiem kontraktu wbudowanego |
|
||||
| `plugin-sdk/channel-policy` | `resolveChannelGroupRequireMention` |
|
||||
| `plugin-sdk/channel-lifecycle` | `createAccountStatusSink` |
|
||||
| `plugin-sdk/inbound-envelope` | Współdzielone helpery routingu przychodzącego + budowania envelope |
|
||||
| `plugin-sdk/inbound-reply-dispatch` | Współdzielone helpery zapisu i dispatchu przychodzących wiadomości |
|
||||
| `plugin-sdk/inbound-envelope` | Współdzielone helpery routingu przychodzącego + budowania kopert |
|
||||
| `plugin-sdk/inbound-reply-dispatch` | Współdzielone helpery rejestrowania i dispatchu danych przychodzących |
|
||||
| `plugin-sdk/messaging-targets` | Helpery parsowania/dopasowywania celów |
|
||||
| `plugin-sdk/outbound-media` | Współdzielone helpery ładowania mediów wychodzących |
|
||||
| `plugin-sdk/outbound-runtime` | Helpery tożsamości wychodzącej/delegowania wysyłki |
|
||||
| `plugin-sdk/thread-bindings-runtime` | Helpery cyklu życia powiązań wątków i adapterów |
|
||||
| `plugin-sdk/agent-media-payload` | Starszy builder payloadów mediów agenta |
|
||||
| `plugin-sdk/conversation-runtime` | Helpery konwersacji/powiązań wątków, parowania i skonfigurowanych powiązań |
|
||||
| `plugin-sdk/runtime-config-snapshot` | Helper snapshotu konfiguracji runtime |
|
||||
| `plugin-sdk/runtime-group-policy` | Helpery rozwiązywania polityki grup w runtime |
|
||||
| `plugin-sdk/channel-status` | Współdzielone helpery snapshotu/podsumowania statusu kanału |
|
||||
| `plugin-sdk/outbound-runtime` | Helpery tożsamości wychodzącej/delegacji wysyłki |
|
||||
| `plugin-sdk/thread-bindings-runtime` | Helpery cyklu życia i adapterów powiązań wątków |
|
||||
| `plugin-sdk/agent-media-payload` | Starszy konstruktor ładunku mediów agenta |
|
||||
| `plugin-sdk/conversation-runtime` | Helpery powiązań rozmowy/wątku, pairingu i skonfigurowanych powiązań |
|
||||
| `plugin-sdk/runtime-config-snapshot` | Helper migawki konfiguracji runtime |
|
||||
| `plugin-sdk/runtime-group-policy` | Helpery rozstrzygania polityki grup w runtime |
|
||||
| `plugin-sdk/channel-status` | Współdzielone helpery migawki/podsumowania statusu kanału |
|
||||
| `plugin-sdk/channel-config-primitives` | Wąskie prymitywy schematu konfiguracji kanału |
|
||||
| `plugin-sdk/channel-config-writes` | Helpery autoryzacji zapisów konfiguracji kanału |
|
||||
| `plugin-sdk/channel-plugin-common` | Współdzielone eksporty prelude pluginu kanału |
|
||||
| `plugin-sdk/channel-plugin-common` | Współdzielone eksporty preambuły pluginów kanałów |
|
||||
| `plugin-sdk/allowlist-config-edit` | Helpery edycji/odczytu konfiguracji allowlist |
|
||||
| `plugin-sdk/group-access` | Współdzielone helpery decyzji dostępu do grup |
|
||||
| `plugin-sdk/group-access` | Współdzielone helpery decyzji dostępu grupowego |
|
||||
| `plugin-sdk/direct-dm` | Współdzielone helpery uwierzytelniania/ochrony bezpośrednich DM |
|
||||
| `plugin-sdk/interactive-runtime` | Helpery normalizacji/redukcji interaktywnych payloadów odpowiedzi |
|
||||
| `plugin-sdk/channel-inbound` | Helpery debounce przychodzących wiadomości, dopasowania wzmianek, polityki wzmianek i helpery envelope |
|
||||
| `plugin-sdk/interactive-runtime` | Helpery normalizacji/redukcji ładunków odpowiedzi interaktywnych |
|
||||
| `plugin-sdk/channel-inbound` | Helpery debounce dla wejścia, dopasowywania wzmianek, polityki wzmianek i helpery kopert |
|
||||
| `plugin-sdk/channel-send-result` | Typy wyników odpowiedzi |
|
||||
| `plugin-sdk/channel-actions` | `createMessageToolButtonsSchema`, `createMessageToolCardSchema` |
|
||||
| `plugin-sdk/channel-targets` | Helpery parsowania/dopasowywania celów |
|
||||
| `plugin-sdk/channel-contract` | Typy kontraktu kanału |
|
||||
| `plugin-sdk/channel-feedback` | Integracja feedbacku/reakcji |
|
||||
| `plugin-sdk/channel-secret-runtime` | Wąskie helpery kontraktu sekretów, takie jak `collectSimpleChannelFieldAssignments`, `getChannelSurface`, `pushAssignment` oraz typy docelowe sekretów |
|
||||
| `plugin-sdk/channel-feedback` | Powiązanie feedbacku/reakcji |
|
||||
| `plugin-sdk/channel-secret-runtime` | Wąskie helpery kontraktu sekretów, takie jak `collectSimpleChannelFieldAssignments`, `getChannelSurface`, `pushAssignment`, oraz typy celu sekretu |
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Subpathy dostawców">
|
||||
<Accordion title="Ścieżki podrzędne dostawców">
|
||||
| Subpath | Kluczowe eksporty |
|
||||
| --- | --- |
|
||||
| `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` |
|
||||
| `plugin-sdk/provider-setup` | Kuratorowane helpery konfiguracji dostawców local/self-hosted |
|
||||
| `plugin-sdk/self-hosted-provider-setup` | Skoncentrowane helpery konfiguracji self-hosted dostawców zgodnych z OpenAI |
|
||||
| `plugin-sdk/cli-backend` | Domyślne ustawienia backendu CLI + stałe watchdog |
|
||||
| `plugin-sdk/provider-auth-runtime` | Helpery rozwiązywania kluczy API w runtime dla pluginów dostawców |
|
||||
| `plugin-sdk/provider-auth-api-key` | Helpery onboardingu/zapisu profilu dla kluczy API, takie jak `upsertApiKeyProfile` |
|
||||
| `plugin-sdk/provider-auth-result` | Standardowy builder wyniku uwierzytelniania OAuth |
|
||||
| `plugin-sdk/provider-setup` | Kuratorowane helpery konfiguracji lokalnych/samodzielnie hostowanych dostawców |
|
||||
| `plugin-sdk/self-hosted-provider-setup` | Skoncentrowane helpery konfiguracji samodzielnie hostowanego dostawcy zgodnego z OpenAI |
|
||||
| `plugin-sdk/cli-backend` | Domyślne ustawienia backendu CLI + stałe watchdoga |
|
||||
| `plugin-sdk/provider-auth-runtime` | Helpery runtime rozstrzygania klucza API dla pluginów dostawców |
|
||||
| `plugin-sdk/provider-auth-api-key` | Helpery wdrażania/zapisu profilu klucza API, takie jak `upsertApiKeyProfile` |
|
||||
| `plugin-sdk/provider-auth-result` | Standardowy konstruktor wyniku uwierzytelniania OAuth |
|
||||
| `plugin-sdk/provider-auth-login` | Współdzielone interaktywne helpery logowania dla pluginów dostawców |
|
||||
| `plugin-sdk/provider-env-vars` | Helpery wyszukiwania zmiennych środowiskowych uwierzytelniania dostawców |
|
||||
| `plugin-sdk/provider-auth` | `createProviderApiKeyAuthMethod`, `ensureApiKeyFromOptionEnvOrPrompt`, `upsertAuthProfile`, `upsertApiKeyProfile`, `writeOAuthCredentials` |
|
||||
| `plugin-sdk/provider-model-shared` | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`, współdzielone buildery polityk replay, helpery endpointów dostawców i helpery normalizacji identyfikatorów modeli, takie jak `normalizeNativeXaiModelId` |
|
||||
| `plugin-sdk/provider-model-shared` | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`, współdzielone konstruktory polityki replay, helpery endpointów dostawców oraz helpery normalizacji identyfikatorów modeli, takie jak `normalizeNativeXaiModelId` |
|
||||
| `plugin-sdk/provider-catalog-shared` | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat` |
|
||||
| `plugin-sdk/provider-http` | Ogólne helpery HTTP/możliwości endpointów dostawców |
|
||||
| `plugin-sdk/provider-http` | Ogólne helpery HTTP/zdolności endpointów dostawców |
|
||||
| `plugin-sdk/provider-web-fetch-contract` | Wąskie helpery kontraktu konfiguracji/wyboru web-fetch, takie jak `enablePluginInConfig` i `WebFetchProviderPlugin` |
|
||||
| `plugin-sdk/provider-web-fetch` | Helpery rejestracji/pamięci podręcznej web-fetch |
|
||||
| `plugin-sdk/provider-web-search-contract` | Wąskie helpery kontraktu konfiguracji/poświadczeń web-search, takie jak `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig` oraz setter/getter poświadczeń o ograniczonym zakresie |
|
||||
| `plugin-sdk/provider-web-search` | Helpery rejestracji/pamięci podręcznej/runtime dla web-search |
|
||||
| `plugin-sdk/provider-tools` | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, czyszczenie schematów Gemini + diagnostyka oraz helpery zgodności xAI, takie jak `resolveXaiModelCompatPatch` / `applyXaiModelCompat` |
|
||||
| `plugin-sdk/provider-web-fetch` | Helpery rejestracji/pamięci podręcznej dostawców web-fetch |
|
||||
| `plugin-sdk/provider-web-search-contract` | Wąskie helpery kontraktu konfiguracji/poświadczeń web-search, takie jak `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig` oraz ustawiające/pobierające poświadczenia o ograniczonym zakresie |
|
||||
| `plugin-sdk/provider-web-search` | Helpery rejestracji/pamięci podręcznej/runtime dostawców web-search |
|
||||
| `plugin-sdk/provider-tools` | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, czyszczenie schematu Gemini + diagnostyka oraz helpery zgodności xAI, takie jak `resolveXaiModelCompatPatch` / `applyXaiModelCompat` |
|
||||
| `plugin-sdk/provider-usage` | `fetchClaudeUsage` i podobne |
|
||||
| `plugin-sdk/provider-stream` | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`, typy wrapperów streamów oraz współdzielone helpery wrapperów Anthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot |
|
||||
| `plugin-sdk/provider-stream` | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`, typy wrapperów strumieni oraz współdzielone helpery wrapperów Anthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot |
|
||||
| `plugin-sdk/provider-onboard` | Helpery łatek konfiguracji onboardingu |
|
||||
| `plugin-sdk/global-singleton` | Lokalne dla procesu helpery singletonów/map/cache |
|
||||
| `plugin-sdk/global-singleton` | Pomocniki singletonów/map/pamięci podręcznej lokalnych dla procesu |
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Subpathy uwierzytelniania i bezpieczeństwa">
|
||||
<Accordion title="Ścieżki podrzędne uwierzytelniania i bezpieczeństwa">
|
||||
| Subpath | Kluczowe eksporty |
|
||||
| --- | --- |
|
||||
| `plugin-sdk/command-auth` | `resolveControlCommandGate`, helpery rejestru poleceń, helpery autoryzacji nadawców |
|
||||
| `plugin-sdk/approval-auth-runtime` | Helpery rozwiązywania approvera i uwierzytelniania akcji w tym samym czacie |
|
||||
| `plugin-sdk/approval-client-runtime` | Helpery natywnego profilu/filtrowania zatwierdzeń exec |
|
||||
| `plugin-sdk/approval-delivery-runtime` | Natywne adaptery możliwości/dostarczania zatwierdzeń |
|
||||
| `plugin-sdk/approval-native-runtime` | Helpery natywnych celów zatwierdzeń + powiązań kont |
|
||||
| `plugin-sdk/approval-reply-runtime` | Helpery payloadów odpowiedzi zatwierdzeń exec/pluginów |
|
||||
| `plugin-sdk/command-auth-native` | Natywne uwierzytelnianie poleceń + helpery natywnych celów sesji |
|
||||
| `plugin-sdk/command-auth` | `resolveControlCommandGate`, helpery rejestru poleceń, helpery autoryzacji nadawcy |
|
||||
| `plugin-sdk/approval-auth-runtime` | Helpery rozstrzygania zatwierdzającego i uwierzytelniania akcji w tym samym czacie |
|
||||
| `plugin-sdk/approval-client-runtime` | Natywne helpery profilu/filtru zatwierdzeń exec |
|
||||
| `plugin-sdk/approval-delivery-runtime` | Natywne adaptery zdolności/dostarczania zatwierdzeń |
|
||||
| `plugin-sdk/approval-gateway-runtime` | Współdzielony helper rozstrzygania gateway zatwierdzeń |
|
||||
| `plugin-sdk/approval-handler-adapter-runtime` | Lekkie helpery ładowania natywnego adaptera zatwierdzeń dla gorących punktów wejścia kanałów |
|
||||
| `plugin-sdk/approval-handler-runtime` | Szersze helpery runtime obsługi zatwierdzeń; preferuj węższe ścieżki adapter/gateway, gdy są wystarczające |
|
||||
| `plugin-sdk/approval-native-runtime` | Natywne helpery celu zatwierdzeń + powiązań kont |
|
||||
| `plugin-sdk/approval-reply-runtime` | Helpery ładunków odpowiedzi dla zatwierdzeń exec/pluginów |
|
||||
| `plugin-sdk/command-auth-native` | Natywne uwierzytelnianie poleceń + natywne helpery celu sesji |
|
||||
| `plugin-sdk/command-detection` | Współdzielone helpery wykrywania poleceń |
|
||||
| `plugin-sdk/command-surface` | Normalizacja treści polecenia i helpery powierzchni poleceń |
|
||||
| `plugin-sdk/command-surface` | Helpery normalizacji treści poleceń i powierzchni poleceń |
|
||||
| `plugin-sdk/allow-from` | `formatAllowFromLowercase` |
|
||||
| `plugin-sdk/channel-secret-runtime` | Wąskie helpery zbierania kontraktu sekretów dla powierzchni sekretów kanałów/pluginów |
|
||||
| `plugin-sdk/secret-ref-runtime` | Wąskie helpery `coerceSecretRef` i typowania SecretRef do parsowania kontraktów sekretów/konfiguracji |
|
||||
| `plugin-sdk/security-runtime` | Współdzielone helpery zaufania, bramek DM, treści zewnętrznych i zbierania sekretów |
|
||||
| `plugin-sdk/channel-secret-runtime` | Wąskie helpery zbierania kontraktów sekretów dla powierzchni sekretów kanałów/pluginów |
|
||||
| `plugin-sdk/secret-ref-runtime` | Wąskie helpery `coerceSecretRef` i typowania SecretRef dla parsowania kontraktów sekretów/konfiguracji |
|
||||
| `plugin-sdk/security-runtime` | Współdzielone helpery zaufania, bramkowania DM, treści zewnętrznej i zbierania sekretów |
|
||||
| `plugin-sdk/ssrf-policy` | Helpery allowlist hostów i polityki SSRF dla sieci prywatnych |
|
||||
| `plugin-sdk/ssrf-runtime` | Helpery pinned-dispatcher, fetch chronionego przed SSRF i polityki SSRF |
|
||||
| `plugin-sdk/secret-input` | Helpery parsowania danych wejściowych sekretów |
|
||||
| `plugin-sdk/webhook-ingress` | Helpery żądań/celów webhooków |
|
||||
| `plugin-sdk/webhook-request-guards` | Helpery rozmiaru body/timeoutu żądań |
|
||||
| `plugin-sdk/ssrf-runtime` | Helpery pinned-dispatcher, fetch chronionego SSRF i polityki SSRF |
|
||||
| `plugin-sdk/secret-input` | Helpery parsowania wejścia sekretów |
|
||||
| `plugin-sdk/webhook-ingress` | Helpery requestów/celów webhooków |
|
||||
| `plugin-sdk/webhook-request-guards` | Helpery rozmiaru body/timeoutu requestów |
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Subpathy runtime i storage">
|
||||
<Accordion title="Ścieżki podrzędne runtime i storage">
|
||||
| Subpath | Kluczowe eksporty |
|
||||
| --- | --- |
|
||||
| `plugin-sdk/runtime` | Szeroka powierzchnia helperów runtime/logowania/kopii zapasowych/instalacji pluginów |
|
||||
| `plugin-sdk/runtime-env` | Wąskie helpery env runtime, loggera, timeoutu, retry i backoff |
|
||||
| `plugin-sdk/runtime` | Szerokie helpery runtime/logowania/kopii zapasowych/instalacji pluginów |
|
||||
| `plugin-sdk/runtime-env` | Wąskie helpery środowiska runtime, loggera, timeoutu, retry i backoff |
|
||||
| `plugin-sdk/channel-runtime-context` | Ogólne helpery rejestracji i wyszukiwania kontekstu runtime kanału |
|
||||
| `plugin-sdk/runtime-store` | `createPluginRuntimeStore` |
|
||||
| `plugin-sdk/plugin-runtime` | Współdzielone helpery poleceń/hooków/http/interaktywne pluginów |
|
||||
| `plugin-sdk/plugin-runtime` | Współdzielone helpery poleceń/hooków/http/interaktywności pluginów |
|
||||
| `plugin-sdk/hook-runtime` | Współdzielone helpery pipeline webhooków/wewnętrznych hooków |
|
||||
| `plugin-sdk/lazy-runtime` | Helpery leniwego importu/powiązania runtime, takie jak `createLazyRuntimeModule`, `createLazyRuntimeMethod` i `createLazyRuntimeSurface` |
|
||||
| `plugin-sdk/process-runtime` | Helpery wykonywania procesów |
|
||||
| `plugin-sdk/cli-runtime` | Helpery formatowania, oczekiwania i wersji CLI |
|
||||
| `plugin-sdk/gateway-runtime` | Helpery klienta Gateway i łatek statusu kanału |
|
||||
| `plugin-sdk/lazy-runtime` | Helpery leniwego importu/powiązań runtime, takie jak `createLazyRuntimeModule`, `createLazyRuntimeMethod` i `createLazyRuntimeSurface` |
|
||||
| `plugin-sdk/process-runtime` | Helpery exec procesów |
|
||||
| `plugin-sdk/cli-runtime` | Helpery formatowania CLI, oczekiwania i wersji |
|
||||
| `plugin-sdk/gateway-runtime` | Helpery klienta gateway i łatek statusu kanałów |
|
||||
| `plugin-sdk/config-runtime` | Helpery ładowania/zapisu konfiguracji |
|
||||
| `plugin-sdk/telegram-command-config` | Helpery normalizacji nazwy/opisu poleceń Telegram i sprawdzania duplikatów/konfliktów, nawet gdy powierzchnia kontraktu dołączonego Telegram nie jest dostępna |
|
||||
| `plugin-sdk/approval-runtime` | Helpery zatwierdzeń exec/pluginów, buildery możliwości zatwierdzeń, helpery auth/profili, natywne helpery routingu/runtime |
|
||||
| `plugin-sdk/reply-runtime` | Współdzielone helpery runtime dla wiadomości przychodzących/odpowiedzi, chunking, dispatch, heartbeat, planer odpowiedzi |
|
||||
| `plugin-sdk/telegram-command-config` | Helpery normalizacji nazw/opisów poleceń Telegram i kontroli duplikatów/konfliktów, nawet gdy powierzchnia kontraktu wbudowanego Telegrama jest niedostępna |
|
||||
| `plugin-sdk/approval-runtime` | Helpery zatwierdzeń exec/pluginów, konstruktory zdolności zatwierdzeń, helpery auth/profili, natywne helpery routingu/runtime |
|
||||
| `plugin-sdk/reply-runtime` | Współdzielone helpery runtime wejścia/odpowiedzi, chunkingu, dispatchu, heartbeat i planisty odpowiedzi |
|
||||
| `plugin-sdk/reply-dispatch-runtime` | Wąskie helpery dispatchu/finalizacji odpowiedzi |
|
||||
| `plugin-sdk/reply-history` | Współdzielone helpery krótkiego okna historii odpowiedzi, takie jak `buildHistoryContext`, `recordPendingHistoryEntry` i `clearHistoryEntriesIfEnabled` |
|
||||
| `plugin-sdk/reply-history` | Współdzielone helpery historii odpowiedzi dla krótkiego okna, takie jak `buildHistoryContext`, `recordPendingHistoryEntry` i `clearHistoryEntriesIfEnabled` |
|
||||
| `plugin-sdk/reply-reference` | `createReplyReferencePlanner` |
|
||||
| `plugin-sdk/reply-chunking` | Wąskie helpery chunkingu tekstu/Markdown |
|
||||
| `plugin-sdk/session-store-runtime` | Helpery ścieżek magazynu sesji + updated-at |
|
||||
| `plugin-sdk/state-paths` | Helpery ścieżek katalogów stanu/OAuth |
|
||||
| `plugin-sdk/routing` | Helpery routingu/kluczy sesji/powiązań kont, takie jak `resolveAgentRoute`, `buildAgentSessionKey` i `resolveDefaultAgentBoundAccountId` |
|
||||
| `plugin-sdk/routing` | Helpery routingu/klucza sesji/powiązania kont, takie jak `resolveAgentRoute`, `buildAgentSessionKey` i `resolveDefaultAgentBoundAccountId` |
|
||||
| `plugin-sdk/status-helpers` | Współdzielone helpery podsumowań statusu kanałów/kont, domyślne stany runtime i helpery metadanych problemów |
|
||||
| `plugin-sdk/target-resolver-runtime` | Współdzielone helpery rozwiązywania celów |
|
||||
| `plugin-sdk/target-resolver-runtime` | Współdzielone helpery resolvera celów |
|
||||
| `plugin-sdk/string-normalization-runtime` | Helpery normalizacji slugów/ciągów |
|
||||
| `plugin-sdk/request-url` | Wyodrębnianie URL-i tekstowych z wejść typu fetch/request |
|
||||
| `plugin-sdk/run-command` | Runner poleceń z timeoutem i znormalizowanymi wynikami stdout/stderr |
|
||||
| `plugin-sdk/param-readers` | Wspólni czytelnicy parametrów narzędzi/CLI |
|
||||
| `plugin-sdk/tool-send` | Wyodrębnianie kanonicznych pól celu wysyłki z argumentów narzędzia |
|
||||
| `plugin-sdk/temp-path` | Współdzielone helpery ścieżek tymczasowego pobierania |
|
||||
| `plugin-sdk/logging-core` | Logger podsystemu i helpery redakcji |
|
||||
| `plugin-sdk/request-url` | Wyodrębnia ciągi URL z wejść podobnych do fetch/request |
|
||||
| `plugin-sdk/run-command` | Uruchamianie poleceń z limitem czasu i znormalizowanymi wynikami stdout/stderr |
|
||||
| `plugin-sdk/param-readers` | Typowe czytniki parametrów narzędzi/CLI |
|
||||
| `plugin-sdk/tool-send` | Wyodrębnia kanoniczne pola celu wysyłki z argumentów narzędzi |
|
||||
| `plugin-sdk/temp-path` | Współdzielone helpery ścieżek tymczasowych pobrań |
|
||||
| `plugin-sdk/logging-core` | Logger subsystemu i helpery redakcji |
|
||||
| `plugin-sdk/markdown-table-runtime` | Helpery trybu tabel Markdown |
|
||||
| `plugin-sdk/json-store` | Małe helpery odczytu/zapisu stanu JSON |
|
||||
| `plugin-sdk/file-lock` | Helpery reentrant file-lock |
|
||||
| `plugin-sdk/persistent-dedupe` | Helpery pamięci podręcznej deduplikacji opartej na dysku |
|
||||
| `plugin-sdk/file-lock` | Rekurencyjne helpery blokowania plików |
|
||||
| `plugin-sdk/persistent-dedupe` | Helpery pamięci podręcznej deduplikacji na dysku |
|
||||
| `plugin-sdk/acp-runtime` | Helpery runtime/sesji ACP i dispatchu odpowiedzi |
|
||||
| `plugin-sdk/agent-config-primitives` | Wąskie prymitywy schematu konfiguracji runtime agenta |
|
||||
| `plugin-sdk/boolean-param` | Luźny czytnik parametrów bool |
|
||||
| `plugin-sdk/dangerous-name-runtime` | Helpery rozwiązywania niebezpiecznego dopasowania nazw |
|
||||
| `plugin-sdk/device-bootstrap` | Helpery bootstrapu urządzenia i tokenów parowania |
|
||||
| `plugin-sdk/boolean-param` | Elastyczny czytnik parametrów logicznych |
|
||||
| `plugin-sdk/dangerous-name-runtime` | Helpery rozstrzygania dopasowań niebezpiecznych nazw |
|
||||
| `plugin-sdk/device-bootstrap` | Helpery bootstrapu urządzenia i tokenów pairingu |
|
||||
| `plugin-sdk/extension-shared` | Współdzielone prymitywy helperów kanałów pasywnych, statusu i ambient proxy |
|
||||
| `plugin-sdk/models-provider-runtime` | Helpery odpowiedzi dla polecenia `/models` i dostawców |
|
||||
| `plugin-sdk/models-provider-runtime` | Helpery odpowiedzi polecenia `/models` / dostawców |
|
||||
| `plugin-sdk/skill-commands-runtime` | Helpery listowania poleceń Skills |
|
||||
| `plugin-sdk/native-command-registry` | Helpery rejestru/build/serializacji natywnych poleceń |
|
||||
| `plugin-sdk/provider-zai-endpoint` | Helpery wykrywania endpointu Z.AI |
|
||||
| `plugin-sdk/native-command-registry` | Natywne helpery rejestru/budowania/serializacji poleceń |
|
||||
| `plugin-sdk/provider-zai-endpoint` | Helpery wykrywania endpointów Z.AI |
|
||||
| `plugin-sdk/infra-runtime` | Helpery zdarzeń systemowych/heartbeat |
|
||||
| `plugin-sdk/collection-runtime` | Małe helpery ograniczonej pamięci podręcznej |
|
||||
| `plugin-sdk/diagnostic-runtime` | Helpery flag i zdarzeń diagnostycznych |
|
||||
| `plugin-sdk/error-runtime` | Graf błędów, formatowanie, współdzielone helpery klasyfikacji błędów, `isApprovalNotFoundError` |
|
||||
| `plugin-sdk/fetch-runtime` | Opakowany fetch, proxy i helpery pinned lookup |
|
||||
| `plugin-sdk/host-runtime` | Helpery normalizacji hostname i hostów SCP |
|
||||
| `plugin-sdk/retry-runtime` | Helpery konfiguracji retry i runnera retry |
|
||||
| `plugin-sdk/agent-runtime` | Helpery katalogu/tożsamości/workspace agenta |
|
||||
| `plugin-sdk/directory-runtime` | Zapytania/dedup directory oparte na konfiguracji |
|
||||
| `plugin-sdk/host-runtime` | Helpery normalizacji hostname i hosta SCP |
|
||||
| `plugin-sdk/retry-runtime` | Helpery konfiguracji retry i wykonawcy retry |
|
||||
| `plugin-sdk/agent-runtime` | Helpery katalogu/tożsamości/obszaru roboczego agenta |
|
||||
| `plugin-sdk/directory-runtime` | Zapytania o katalog oparte na konfiguracji/deduplikacja |
|
||||
| `plugin-sdk/keyed-async-queue` | `KeyedAsyncQueue` |
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Subpathy możliwości i testowania">
|
||||
<Accordion title="Ścieżki podrzędne capabilities i testów">
|
||||
| Subpath | Kluczowe eksporty |
|
||||
| --- | --- |
|
||||
| `plugin-sdk/media-runtime` | Współdzielone helpery pobierania/przekształcania/przechowywania mediów oraz buildery payloadów mediów |
|
||||
| `plugin-sdk/media-generation-runtime` | Współdzielone helpery failover generowania mediów, wybór kandydatów i komunikaty o brakującym modelu |
|
||||
| `plugin-sdk/media-understanding` | Typy dostawców rozumienia mediów oraz eksporty helperów obrazów/audio dla dostawców |
|
||||
| `plugin-sdk/text-runtime` | Współdzielone helpery tekstu/Markdown/logowania, takie jak usuwanie tekstu widocznego dla asystenta, renderowanie/chunking/tabele Markdown, helpery redakcji, helpery tagów dyrektyw i bezpieczne narzędzia tekstowe |
|
||||
| `plugin-sdk/media-runtime` | Współdzielone helpery pobierania/przekształcania/przechowywania mediów oraz konstruktory ładunków mediów |
|
||||
| `plugin-sdk/media-generation-runtime` | Współdzielone helpery failover generowania mediów, wybór kandydatów i komunikaty o brakujących modelach |
|
||||
| `plugin-sdk/media-understanding` | Typy dostawców rozumienia mediów oraz eksporty helperów obrazu/audio dla dostawców |
|
||||
| `plugin-sdk/text-runtime` | Współdzielone helpery tekstu/Markdown/logowania, takie jak usuwanie tekstu widocznego dla asystenta, helpery renderowania/chunkingu/tabel Markdown, helpery redakcji, helpery tagów dyrektyw i narzędzia bezpiecznego tekstu |
|
||||
| `plugin-sdk/text-chunking` | Helper chunkingu tekstu wychodzącego |
|
||||
| `plugin-sdk/speech` | Typy dostawców mowy oraz eksporty helperów dyrektyw, rejestru i walidacji dla dostawców |
|
||||
| `plugin-sdk/speech-core` | Współdzielone typy dostawców mowy, helpery rejestru, dyrektyw i normalizacji |
|
||||
| `plugin-sdk/realtime-transcription` | Typy dostawców transkrypcji w czasie rzeczywistym i helpery rejestru |
|
||||
| `plugin-sdk/realtime-voice` | Typy dostawców głosu w czasie rzeczywistym i helpery rejestru |
|
||||
| `plugin-sdk/speech-core` | Współdzielone typy dostawców mowy, rejestr, dyrektywy i helpery normalizacji |
|
||||
| `plugin-sdk/realtime-transcription` | Typy dostawców transkrypcji realtime i helpery rejestru |
|
||||
| `plugin-sdk/realtime-voice` | Typy dostawców głosu realtime i helpery rejestru |
|
||||
| `plugin-sdk/image-generation` | Typy dostawców generowania obrazów |
|
||||
| `plugin-sdk/image-generation-core` | Współdzielone typy, failover, helpery auth i rejestru dla generowania obrazów |
|
||||
| `plugin-sdk/music-generation` | Typy dostawców/żądań/wyników generowania muzyki |
|
||||
| `plugin-sdk/music-generation-core` | Współdzielone typy generowania muzyki, helpery failover, wyszukiwania dostawców i parsowania referencji modeli |
|
||||
| `plugin-sdk/video-generation` | Typy dostawców/żądań/wyników generowania wideo |
|
||||
| `plugin-sdk/video-generation-core` | Współdzielone typy generowania wideo, helpery failover, wyszukiwania dostawców i parsowania referencji modeli |
|
||||
| `plugin-sdk/image-generation-core` | Współdzielone typy generowania obrazów, failover, uwierzytelnianie i helpery rejestru |
|
||||
| `plugin-sdk/music-generation` | Typy dostawców/requestów/wyników generowania muzyki |
|
||||
| `plugin-sdk/music-generation-core` | Współdzielone typy generowania muzyki, helpery failover, wyszukiwanie dostawców i parsowanie model-ref |
|
||||
| `plugin-sdk/video-generation` | Typy dostawców/requestów/wyników generowania wideo |
|
||||
| `plugin-sdk/video-generation-core` | Współdzielone typy generowania wideo, helpery failover, wyszukiwanie dostawców i parsowanie model-ref |
|
||||
| `plugin-sdk/webhook-targets` | Rejestr celów webhooków i helpery instalacji tras |
|
||||
| `plugin-sdk/webhook-path` | Helpery normalizacji ścieżek webhooków |
|
||||
| `plugin-sdk/web-media` | Współdzielone helpery ładowania zdalnych/lokalnych mediów |
|
||||
| `plugin-sdk/zod` | Reeksport `zod` dla użytkowników Plugin SDK |
|
||||
| `plugin-sdk/zod` | Reeksportowane `zod` dla użytkowników plugin SDK |
|
||||
| `plugin-sdk/testing` | `installCommonResolveTargetErrorCases`, `shouldAckReaction` |
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Subpathy pamięci">
|
||||
<Accordion title="Ścieżki podrzędne pamięci">
|
||||
| Subpath | Kluczowe eksporty |
|
||||
| --- | --- |
|
||||
| `plugin-sdk/memory-core` | Dołączona pomocnicza powierzchnia memory-core dla helperów managera/konfiguracji/plików/CLI |
|
||||
| `plugin-sdk/memory-core` | Powierzchnia helperów wbudowanego memory-core dla managera/konfiguracji/plików/CLI |
|
||||
| `plugin-sdk/memory-core-engine-runtime` | Fasada runtime indeksu/wyszukiwania pamięci |
|
||||
| `plugin-sdk/memory-core-host-engine-foundation` | Eksporty silnika podstawowego hosta pamięci |
|
||||
| `plugin-sdk/memory-core-host-engine-foundation` | Eksporty silnika bazowego hosta pamięci |
|
||||
| `plugin-sdk/memory-core-host-engine-embeddings` | Eksporty silnika embeddingów hosta pamięci |
|
||||
| `plugin-sdk/memory-core-host-engine-qmd` | Eksporty silnika QMD hosta pamięci |
|
||||
| `plugin-sdk/memory-core-host-engine-storage` | Eksporty silnika storage hosta pamięci |
|
||||
| `plugin-sdk/memory-core-host-multimodal` | Helpery multimodalne hosta pamięci |
|
||||
| `plugin-sdk/memory-core-host-multimodal` | Helpery multimodalnego hosta pamięci |
|
||||
| `plugin-sdk/memory-core-host-query` | Helpery zapytań hosta pamięci |
|
||||
| `plugin-sdk/memory-core-host-secret` | Helpery sekretów hosta pamięci |
|
||||
| `plugin-sdk/memory-core-host-events` | Helpery dziennika zdarzeń hosta pamięci |
|
||||
| `plugin-sdk/memory-core-host-status` | Helpery statusu hosta pamięci |
|
||||
| `plugin-sdk/memory-core-host-runtime-cli` | Helpery runtime CLI hosta pamięci |
|
||||
| `plugin-sdk/memory-core-host-runtime-core` | Helpery podstawowego runtime hosta pamięci |
|
||||
| `plugin-sdk/memory-core-host-runtime-core` | Helpery głównego runtime hosta pamięci |
|
||||
| `plugin-sdk/memory-core-host-runtime-files` | Helpery plików/runtime hosta pamięci |
|
||||
| `plugin-sdk/memory-host-core` | Neutralny wobec producenta alias helperów podstawowego runtime hosta pamięci |
|
||||
| `plugin-sdk/memory-host-events` | Neutralny wobec producenta alias helperów dziennika zdarzeń hosta pamięci |
|
||||
| `plugin-sdk/memory-host-files` | Neutralny wobec producenta alias helperów plików/runtime hosta pamięci |
|
||||
| `plugin-sdk/memory-host-markdown` | Współdzielone helpery managed-markdown dla pluginów sąsiadujących z pamięcią |
|
||||
| `plugin-sdk/memory-host-search` | Fasada aktywnego runtime pamięci dla dostępu do search-manager |
|
||||
| `plugin-sdk/memory-host-status` | Neutralny wobec producenta alias helperów statusu hosta pamięci |
|
||||
| `plugin-sdk/memory-lancedb` | Dołączona pomocnicza powierzchnia memory-lancedb |
|
||||
| `plugin-sdk/memory-host-core` | Neutralny względem dostawcy alias helperów głównego runtime hosta pamięci |
|
||||
| `plugin-sdk/memory-host-events` | Neutralny względem dostawcy alias helperów dziennika zdarzeń hosta pamięci |
|
||||
| `plugin-sdk/memory-host-files` | Neutralny względem dostawcy alias helperów plików/runtime hosta pamięci |
|
||||
| `plugin-sdk/memory-host-markdown` | Współdzielone helpery zarządzanego Markdown dla pluginów sąsiadujących z pamięcią |
|
||||
| `plugin-sdk/memory-host-search` | Aktywna fasada runtime pamięci dla dostępu do menedżera wyszukiwania |
|
||||
| `plugin-sdk/memory-host-status` | Neutralny względem dostawcy alias helperów statusu hosta pamięci |
|
||||
| `plugin-sdk/memory-lancedb` | Powierzchnia helperów wbudowanego memory-lancedb |
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Zarezerwowane subpathy helperów dołączonych">
|
||||
| Rodzina | Aktualne subpathy | Zamierzone użycie |
|
||||
<Accordion title="Zarezerwowane ścieżki podrzędne wbudowanych helperów">
|
||||
| Family | Current subpaths | Intended use |
|
||||
| --- | --- | --- |
|
||||
| Browser | `plugin-sdk/browser-cdp`, `plugin-sdk/browser-config-runtime`, `plugin-sdk/browser-config-support`, `plugin-sdk/browser-control-auth`, `plugin-sdk/browser-node-runtime`, `plugin-sdk/browser-profiles`, `plugin-sdk/browser-security-runtime`, `plugin-sdk/browser-setup-tools`, `plugin-sdk/browser-support` | Helpery wsparcia dołączonego pluginu browser (`browser-support` pozostaje barrelem zgodności) |
|
||||
| Matrix | `plugin-sdk/matrix`, `plugin-sdk/matrix-helper`, `plugin-sdk/matrix-runtime-heavy`, `plugin-sdk/matrix-runtime-shared`, `plugin-sdk/matrix-runtime-surface`, `plugin-sdk/matrix-surface`, `plugin-sdk/matrix-thread-bindings` | Powierzchnia helperów/runtime dołączonego Matrix |
|
||||
| Line | `plugin-sdk/line`, `plugin-sdk/line-core`, `plugin-sdk/line-runtime`, `plugin-sdk/line-surface` | Powierzchnia helperów/runtime dołączonego LINE |
|
||||
| IRC | `plugin-sdk/irc`, `plugin-sdk/irc-surface` | Powierzchnia helperów dołączonego IRC |
|
||||
| Helpery specyficzne dla kanału | `plugin-sdk/googlechat`, `plugin-sdk/zalouser`, `plugin-sdk/bluebubbles`, `plugin-sdk/bluebubbles-policy`, `plugin-sdk/mattermost`, `plugin-sdk/mattermost-policy`, `plugin-sdk/feishu-conversation`, `plugin-sdk/msteams`, `plugin-sdk/nextcloud-talk`, `plugin-sdk/nostr`, `plugin-sdk/tlon`, `plugin-sdk/twitch` | Interfejsy zgodności/helperów dołączonych kanałów |
|
||||
| Helpery specyficzne dla auth/pluginów | `plugin-sdk/github-copilot-login`, `plugin-sdk/github-copilot-token`, `plugin-sdk/diagnostics-otel`, `plugin-sdk/diffs`, `plugin-sdk/llm-task`, `plugin-sdk/thread-ownership`, `plugin-sdk/voice-call` | Interfejsy helperów dołączonych funkcji/pluginów; `plugin-sdk/github-copilot-token` eksportuje obecnie `DEFAULT_COPILOT_API_BASE_URL`, `deriveCopilotApiBaseUrlFromToken` i `resolveCopilotApiToken` |
|
||||
| Browser | `plugin-sdk/browser-cdp`, `plugin-sdk/browser-config-runtime`, `plugin-sdk/browser-config-support`, `plugin-sdk/browser-control-auth`, `plugin-sdk/browser-node-runtime`, `plugin-sdk/browser-profiles`, `plugin-sdk/browser-security-runtime`, `plugin-sdk/browser-setup-tools`, `plugin-sdk/browser-support` | Helpery wsparcia wbudowanego pluginu przeglądarki (`browser-support` pozostaje barrelem zgodności) |
|
||||
| Matrix | `plugin-sdk/matrix`, `plugin-sdk/matrix-helper`, `plugin-sdk/matrix-runtime-heavy`, `plugin-sdk/matrix-runtime-shared`, `plugin-sdk/matrix-runtime-surface`, `plugin-sdk/matrix-surface`, `plugin-sdk/matrix-thread-bindings` | Powierzchnia helperów/runtime wbudowanego Matrix |
|
||||
| Line | `plugin-sdk/line`, `plugin-sdk/line-core`, `plugin-sdk/line-runtime`, `plugin-sdk/line-surface` | Powierzchnia helperów/runtime wbudowanego LINE |
|
||||
| IRC | `plugin-sdk/irc`, `plugin-sdk/irc-surface` | Powierzchnia helperów wbudowanego IRC |
|
||||
| Channel-specific helpers | `plugin-sdk/googlechat`, `plugin-sdk/zalouser`, `plugin-sdk/bluebubbles`, `plugin-sdk/bluebubbles-policy`, `plugin-sdk/mattermost`, `plugin-sdk/mattermost-policy`, `plugin-sdk/feishu-conversation`, `plugin-sdk/msteams`, `plugin-sdk/nextcloud-talk`, `plugin-sdk/nostr`, `plugin-sdk/tlon`, `plugin-sdk/twitch` | Wbudowane ścieżki zgodności/helperów kanałów |
|
||||
| Auth/plugin-specific helpers | `plugin-sdk/github-copilot-login`, `plugin-sdk/github-copilot-token`, `plugin-sdk/diagnostics-otel`, `plugin-sdk/diffs`, `plugin-sdk/llm-task`, `plugin-sdk/thread-ownership`, `plugin-sdk/voice-call` | Wbudowane ścieżki helperów funkcji/pluginów; `plugin-sdk/github-copilot-token` obecnie eksportuje `DEFAULT_COPILOT_API_BASE_URL`, `deriveCopilotApiBaseUrlFromToken` i `resolveCopilotApiToken` |
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
@ -300,59 +303,58 @@ jawnie promuje któryś z nich jako publiczny.
|
||||
Callback `register(api)` otrzymuje obiekt `OpenClawPluginApi` z następującymi
|
||||
metodami:
|
||||
|
||||
### Rejestracja możliwości
|
||||
### Rejestracja capabilities
|
||||
|
||||
| Metoda | Co rejestruje |
|
||||
| Method | What it registers |
|
||||
| ------------------------------------------------ | -------------------------------- |
|
||||
| `api.registerProvider(...)` | Wnioskowanie tekstowe (LLM) |
|
||||
| `api.registerCliBackend(...)` | Lokalny backend wnioskowania CLI |
|
||||
| `api.registerChannel(...)` | Kanał wiadomości |
|
||||
| `api.registerSpeechProvider(...)` | Synteza text-to-speech / STT |
|
||||
| `api.registerRealtimeTranscriptionProvider(...)` | Strumieniową transkrypcję w czasie rzeczywistym |
|
||||
| `api.registerRealtimeVoiceProvider(...)` | Dwukierunkowe sesje głosowe w czasie rzeczywistym |
|
||||
| `api.registerMediaUnderstandingProvider(...)` | Analizę obrazu/audio/wideo |
|
||||
| `api.registerSpeechProvider(...)` | Synteza tekst-na-mowę / STT |
|
||||
| `api.registerRealtimeTranscriptionProvider(...)` | Strumieniowa transkrypcja realtime |
|
||||
| `api.registerRealtimeVoiceProvider(...)` | Dwukierunkowe sesje głosu realtime |
|
||||
| `api.registerMediaUnderstandingProvider(...)` | Analiza obrazu/audio/wideo |
|
||||
| `api.registerImageGenerationProvider(...)` | Generowanie obrazów |
|
||||
| `api.registerMusicGenerationProvider(...)` | Generowanie muzyki |
|
||||
| `api.registerVideoGenerationProvider(...)` | Generowanie wideo |
|
||||
| `api.registerWebFetchProvider(...)` | Dostawcę web fetch / scrape |
|
||||
| `api.registerWebFetchProvider(...)` | Dostawca web fetch / scrape |
|
||||
| `api.registerWebSearchProvider(...)` | Wyszukiwanie w sieci |
|
||||
|
||||
### Narzędzia i polecenia
|
||||
|
||||
| Metoda | Co rejestruje |
|
||||
| ------------------------------- | -------------------------------------------- |
|
||||
| Method | What it registers |
|
||||
| ------------------------------- | --------------------------------------------- |
|
||||
| `api.registerTool(tool, opts?)` | Narzędzie agenta (wymagane lub `{ optional: true }`) |
|
||||
| `api.registerCommand(def)` | Polecenie niestandardowe (omija LLM) |
|
||||
| `api.registerCommand(def)` | Polecenie niestandardowe (pomija LLM) |
|
||||
|
||||
### Infrastruktura
|
||||
|
||||
| Metoda | Co rejestruje |
|
||||
| ---------------------------------------------- | ----------------------------------- |
|
||||
| `api.registerHook(events, handler, opts?)` | Hook zdarzeń |
|
||||
| `api.registerHttpRoute(params)` | Endpoint HTTP Gateway |
|
||||
| `api.registerGatewayMethod(name, handler)` | Metodę RPC Gateway |
|
||||
| `api.registerCli(registrar, opts?)` | Podpolecenie CLI |
|
||||
| `api.registerService(service)` | Usługę działającą w tle |
|
||||
| `api.registerInteractiveHandler(registration)` | Handler interaktywny |
|
||||
| `api.registerMemoryPromptSupplement(builder)` | Addytywną sekcję promptu sąsiadującą z pamięcią |
|
||||
| `api.registerMemoryCorpusSupplement(adapter)` | Addytywny korpus pamięci do wyszukiwania/odczytu |
|
||||
| Method | What it registers |
|
||||
| ---------------------------------------------- | --------------------------------------- |
|
||||
| `api.registerHook(events, handler, opts?)` | Hook zdarzeń |
|
||||
| `api.registerHttpRoute(params)` | Endpoint HTTP gateway |
|
||||
| `api.registerGatewayMethod(name, handler)` | Metoda RPC gateway |
|
||||
| `api.registerCli(registrar, opts?)` | Podpolecenie CLI |
|
||||
| `api.registerService(service)` | Usługa działająca w tle |
|
||||
| `api.registerInteractiveHandler(registration)` | Handler interaktywny |
|
||||
| `api.registerMemoryPromptSupplement(builder)` | Addytywna sekcja promptu sąsiadująca z pamięcią |
|
||||
| `api.registerMemoryCorpusSupplement(adapter)` | Addytywny korpus wyszukiwania/odczytu pamięci |
|
||||
|
||||
Zarezerwowane podstawowe administracyjne przestrzenie nazw (`config.*`, `exec.approvals.*`, `wizard.*`,
|
||||
`update.*`) zawsze pozostają `operator.admin`, nawet jeśli plugin spróbuje przypisać
|
||||
węższy zakres metody Gateway. Dla metod należących do pluginu preferuj prefiksy
|
||||
specyficzne dla pluginu.
|
||||
Zarezerwowane przestrzenie nazw administracyjnych rdzenia (`config.*`, `exec.approvals.*`, `wizard.*`,
|
||||
`update.*`) zawsze pozostają `operator.admin`, nawet jeśli plugin próbuje przypisać
|
||||
węższy zakres metody gateway. Dla metod należących do pluginów preferuj prefiksy specyficzne dla pluginu.
|
||||
|
||||
### Metadane rejestracji CLI
|
||||
|
||||
`api.registerCli(registrar, opts?)` akceptuje dwa rodzaje metadanych najwyższego poziomu:
|
||||
|
||||
- `commands`: jawne rooty poleceń należące do registrara
|
||||
- `descriptors`: deskryptory poleceń używane w czasie parsowania dla głównej pomocy CLI,
|
||||
- `commands`: jawne korzenie poleceń należące do rejestratora
|
||||
- `descriptors`: deskryptory poleceń na etapie parsowania używane do pomocy głównego CLI,
|
||||
routingu i leniwej rejestracji CLI pluginów
|
||||
|
||||
Jeśli chcesz, aby polecenie pluginu pozostawało leniwie ładowane w normalnej ścieżce głównego CLI,
|
||||
podaj `descriptors`, które obejmują każdy root polecenia najwyższego poziomu ujawniany przez tego
|
||||
registrara.
|
||||
Jeśli chcesz, aby polecenie pluginu pozostało ładowane leniwie w zwykłej ścieżce głównego CLI,
|
||||
podaj `descriptors`, które obejmują każdy korzeń poleceń najwyższego poziomu udostępniany przez ten
|
||||
rejestrator.
|
||||
|
||||
```typescript
|
||||
api.registerCli(
|
||||
@ -364,7 +366,7 @@ api.registerCli(
|
||||
descriptors: [
|
||||
{
|
||||
name: "matrix",
|
||||
description: "Manage Matrix accounts, verification, devices, and profile state",
|
||||
description: "Zarządzaj kontami Matrix, weryfikacją, urządzeniami i stanem profilu",
|
||||
hasSubcommands: true,
|
||||
},
|
||||
],
|
||||
@ -374,82 +376,82 @@ api.registerCli(
|
||||
|
||||
Używaj samego `commands` tylko wtedy, gdy nie potrzebujesz leniwej rejestracji głównego CLI.
|
||||
Ta ścieżka zgodności eager nadal jest obsługiwana, ale nie instaluje
|
||||
placeholderów opartych na deskryptorach dla leniwego ładowania w czasie parsowania.
|
||||
placeholderów opartych na deskryptorach dla leniwego ładowania na etapie parsowania.
|
||||
|
||||
### Rejestracja backendu CLI
|
||||
|
||||
`api.registerCliBackend(...)` pozwala pluginowi posiadać domyślną konfigurację lokalnego
|
||||
backendu AI CLI, takiego jak `codex-cli`.
|
||||
backendu CLI AI, takiego jak `codex-cli`.
|
||||
|
||||
- `id` backendu staje się prefiksem dostawcy w referencjach modeli takich jak `codex-cli/gpt-5`.
|
||||
- `id` backendu staje się prefiksem dostawcy w odwołaniach do modeli, takich jak `codex-cli/gpt-5`.
|
||||
- `config` backendu używa tego samego kształtu co `agents.defaults.cliBackends.<id>`.
|
||||
- Konfiguracja użytkownika nadal wygrywa. OpenClaw scala `agents.defaults.cliBackends.<id>` z
|
||||
domyślną konfiguracją pluginu przed uruchomieniem CLI.
|
||||
- Użyj `normalizeConfig`, gdy backend wymaga przepisania zgodności po scaleniu
|
||||
- Konfiguracja użytkownika nadal ma pierwszeństwo. OpenClaw scala `agents.defaults.cliBackends.<id>` z
|
||||
wartością domyślną pluginu przed uruchomieniem CLI.
|
||||
- Użyj `normalizeConfig`, gdy backend potrzebuje przeróbek zgodności po scaleniu
|
||||
(na przykład normalizacji starych kształtów flag).
|
||||
|
||||
### Sloty wyłączne
|
||||
### Wyłączne sloty
|
||||
|
||||
| Metoda | Co rejestruje |
|
||||
| ------------------------------------------ | ------------------------------------ |
|
||||
| `api.registerContextEngine(id, factory)` | Silnik kontekstu (aktywny jeden naraz) |
|
||||
| `api.registerMemoryCapability(capability)` | Ujednoliconą możliwość pamięci |
|
||||
| `api.registerMemoryPromptSection(builder)` | Builder sekcji promptu pamięci |
|
||||
| `api.registerMemoryFlushPlan(resolver)` | Resolver planu flush pamięci |
|
||||
| `api.registerMemoryRuntime(runtime)` | Adapter runtime pamięci |
|
||||
| Method | What it registers |
|
||||
| ------------------------------------------ | ------------------------------------- |
|
||||
| `api.registerContextEngine(id, factory)` | Silnik kontekstu (aktywny naraz jest jeden) |
|
||||
| `api.registerMemoryCapability(capability)` | Ujednolicona capability pamięci |
|
||||
| `api.registerMemoryPromptSection(builder)` | Konstruktor sekcji promptu pamięci |
|
||||
| `api.registerMemoryFlushPlan(resolver)` | Resolver planu opróżniania pamięci |
|
||||
| `api.registerMemoryRuntime(runtime)` | Adapter runtime pamięci |
|
||||
|
||||
### Adaptery embeddingów pamięci
|
||||
|
||||
| Metoda | Co rejestruje |
|
||||
| ---------------------------------------------- | --------------------------------------------- |
|
||||
| Method | What it registers |
|
||||
| ---------------------------------------------- | ---------------------------------------------- |
|
||||
| `api.registerMemoryEmbeddingProvider(adapter)` | Adapter embeddingów pamięci dla aktywnego pluginu |
|
||||
|
||||
- `registerMemoryCapability` to preferowane wyłączne API pluginu pamięci.
|
||||
- `registerMemoryCapability` może również udostępniać `publicArtifacts.listArtifacts(...)`,
|
||||
aby pluginy towarzyszące mogły korzystać z eksportowanych artefaktów pamięci przez
|
||||
`openclaw/plugin-sdk/memory-host-core` zamiast sięgać do prywatnego układu konkretnego
|
||||
pluginu pamięci.
|
||||
- `registerMemoryPromptSection`, `registerMemoryFlushPlan` oraz
|
||||
`registerMemoryRuntime` to starsze, zgodne wstecz wyłączne API pluginów pamięci.
|
||||
- `registerMemoryEmbeddingProvider` pozwala aktywnemu pluginowi pamięci rejestrować jeden
|
||||
- `registerMemoryCapability` to preferowane wyłączne API pluginów pamięci.
|
||||
- `registerMemoryCapability` może też udostępniać `publicArtifacts.listArtifacts(...)`,
|
||||
aby pluginy towarzyszące mogły używać eksportowanych artefaktów pamięci przez
|
||||
`openclaw/plugin-sdk/memory-host-core` zamiast sięgać do prywatnego układu
|
||||
konkretnego pluginu pamięci.
|
||||
- `registerMemoryPromptSection`, `registerMemoryFlushPlan` i
|
||||
`registerMemoryRuntime` to zgodne wstecz, wyłączne API starszych pluginów pamięci.
|
||||
- `registerMemoryEmbeddingProvider` pozwala aktywnemu pluginowi pamięci zarejestrować jeden
|
||||
lub więcej identyfikatorów adapterów embeddingów (na przykład `openai`, `gemini` lub własny identyfikator zdefiniowany przez plugin).
|
||||
- Konfiguracja użytkownika, taka jak `agents.defaults.memorySearch.provider` i
|
||||
`agents.defaults.memorySearch.fallback`, rozwiązuje się względem tych zarejestrowanych
|
||||
`agents.defaults.memorySearch.fallback`, jest rozstrzygana względem tych zarejestrowanych
|
||||
identyfikatorów adapterów.
|
||||
|
||||
### Zdarzenia i cykl życia
|
||||
|
||||
| Metoda | Co robi |
|
||||
| -------------------------------------------- | ------------------------------ |
|
||||
| `api.on(hookName, handler, opts?)` | Typowany hook cyklu życia |
|
||||
| `api.onConversationBindingResolved(handler)` | Callback rozwiązania powiązania konwersacji |
|
||||
| Method | What it does |
|
||||
| -------------------------------------------- | ----------------------------- |
|
||||
| `api.on(hookName, handler, opts?)` | Typowany hook cyklu życia |
|
||||
| `api.onConversationBindingResolved(handler)` | Callback rozstrzygnięcia powiązania rozmowy |
|
||||
|
||||
### Semantyka decyzji hooków
|
||||
|
||||
- `before_tool_call`: zwrócenie `{ block: true }` jest rozstrzygające. Gdy dowolny handler to ustawi, handlery o niższym priorytecie są pomijane.
|
||||
- `before_tool_call`: zwrócenie `{ block: true }` jest ostateczne. Gdy dowolny handler to ustawi, handlery o niższym priorytecie są pomijane.
|
||||
- `before_tool_call`: zwrócenie `{ block: false }` jest traktowane jako brak decyzji (tak samo jak pominięcie `block`), a nie jako nadpisanie.
|
||||
- `before_install`: zwrócenie `{ block: true }` jest rozstrzygające. Gdy dowolny handler to ustawi, handlery o niższym priorytecie są pomijane.
|
||||
- `before_install`: zwrócenie `{ block: true }` jest ostateczne. Gdy dowolny handler to ustawi, handlery o niższym priorytecie są pomijane.
|
||||
- `before_install`: zwrócenie `{ block: false }` jest traktowane jako brak decyzji (tak samo jak pominięcie `block`), a nie jako nadpisanie.
|
||||
- `reply_dispatch`: zwrócenie `{ handled: true, ... }` jest rozstrzygające. Gdy dowolny handler przejmie dispatch, handlery o niższym priorytecie i domyślna ścieżka dispatchu modelu są pomijane.
|
||||
- `message_sending`: zwrócenie `{ cancel: true }` jest rozstrzygające. Gdy dowolny handler to ustawi, handlery o niższym priorytecie są pomijane.
|
||||
- `reply_dispatch`: zwrócenie `{ handled: true, ... }` jest ostateczne. Gdy dowolny handler przejmie dispatch, handlery o niższym priorytecie i domyślna ścieżka dispatchu modelu są pomijane.
|
||||
- `message_sending`: zwrócenie `{ cancel: true }` jest ostateczne. Gdy dowolny handler to ustawi, handlery o niższym priorytecie są pomijane.
|
||||
- `message_sending`: zwrócenie `{ cancel: false }` jest traktowane jako brak decyzji (tak samo jak pominięcie `cancel`), a nie jako nadpisanie.
|
||||
|
||||
### Pola obiektu API
|
||||
|
||||
| Pole | Typ | Opis |
|
||||
| ------------------------ | ------------------------- | --------------------------------------------------------------------------------------------- |
|
||||
| `api.id` | `string` | Identyfikator pluginu |
|
||||
| `api.name` | `string` | Nazwa wyświetlana |
|
||||
| `api.version` | `string?` | Wersja pluginu (opcjonalnie) |
|
||||
| `api.description` | `string?` | Opis pluginu (opcjonalnie) |
|
||||
| `api.source` | `string` | Ścieżka źródłowa pluginu |
|
||||
| `api.rootDir` | `string?` | Katalog główny pluginu (opcjonalnie) |
|
||||
| `api.config` | `OpenClawConfig` | Bieżący snapshot konfiguracji (aktywny snapshot runtime w pamięci, gdy dostępny) |
|
||||
| `api.pluginConfig` | `Record<string, unknown>` | Konfiguracja specyficzna dla pluginu z `plugins.entries.<id>.config` |
|
||||
| `api.runtime` | `PluginRuntime` | [Runtime Helpers](/pl/plugins/sdk-runtime) |
|
||||
| `api.logger` | `PluginLogger` | Logger o ograniczonym zakresie (`debug`, `info`, `warn`, `error`) |
|
||||
| Field | Type | Description |
|
||||
| ------------------------ | ------------------------- | ------------------------------------------------------------------------------------------- |
|
||||
| `api.id` | `string` | Identyfikator pluginu |
|
||||
| `api.name` | `string` | Nazwa wyświetlana |
|
||||
| `api.version` | `string?` | Wersja pluginu (opcjonalnie) |
|
||||
| `api.description` | `string?` | Opis pluginu (opcjonalnie) |
|
||||
| `api.source` | `string` | Ścieżka źródłowa pluginu |
|
||||
| `api.rootDir` | `string?` | Katalog główny pluginu (opcjonalnie) |
|
||||
| `api.config` | `OpenClawConfig` | Bieżąca migawka konfiguracji (aktywna migawka runtime w pamięci, gdy jest dostępna) |
|
||||
| `api.pluginConfig` | `Record<string, unknown>` | Konfiguracja specyficzna dla pluginu z `plugins.entries.<id>.config` |
|
||||
| `api.runtime` | `PluginRuntime` | [Helpery runtime](/pl/plugins/sdk-runtime) |
|
||||
| `api.logger` | `PluginLogger` | Logger o ograniczonym zakresie (`debug`, `info`, `warn`, `error`) |
|
||||
| `api.registrationMode` | `PluginRegistrationMode` | Bieżący tryb ładowania; `"setup-runtime"` to lekkie okno uruchamiania/konfiguracji przed pełnym wejściem |
|
||||
| `api.resolvePath(input)` | `(string) => string` | Rozwiązanie ścieżki względem katalogu głównego pluginu |
|
||||
| `api.resolvePath(input)` | `(string) => string` | Rozstrzyga ścieżkę względem katalogu głównego pluginu |
|
||||
|
||||
## Konwencja modułów wewnętrznych
|
||||
|
||||
@ -457,7 +459,7 @@ Wewnątrz pluginu używaj lokalnych plików barrel do importów wewnętrznych:
|
||||
|
||||
```
|
||||
my-plugin/
|
||||
api.ts # Publiczne eksporty dla zewnętrznych konsumentów
|
||||
api.ts # Publiczne eksporty dla odbiorców zewnętrznych
|
||||
runtime-api.ts # Eksporty runtime tylko do użytku wewnętrznego
|
||||
index.ts # Punkt wejścia pluginu
|
||||
setup-entry.ts # Lekki punkt wejścia tylko do konfiguracji (opcjonalnie)
|
||||
@ -465,41 +467,41 @@ my-plugin/
|
||||
|
||||
<Warning>
|
||||
Nigdy nie importuj własnego pluginu przez `openclaw/plugin-sdk/<your-plugin>`
|
||||
w kodzie produkcyjnym. Prowadź importy wewnętrzne przez `./api.ts` lub
|
||||
z kodu produkcyjnego. Kieruj importy wewnętrzne przez `./api.ts` lub
|
||||
`./runtime-api.ts`. Ścieżka SDK jest wyłącznie kontraktem zewnętrznym.
|
||||
</Warning>
|
||||
|
||||
Publiczne powierzchnie dołączonych pluginów ładowane przez fasady (`api.ts`, `runtime-api.ts`,
|
||||
`index.ts`, `setup-entry.ts` i podobne publiczne pliki wejściowe) preferują teraz
|
||||
aktywny snapshot konfiguracji runtime, gdy OpenClaw już działa. Jeśli snapshot runtime
|
||||
nie istnieje jeszcze, wracają do rozpoznanego pliku konfiguracyjnego na dysku.
|
||||
Publiczne powierzchnie wbudowanych pluginów ładowane przez fasadę (`api.ts`, `runtime-api.ts`,
|
||||
`index.ts`, `setup-entry.ts` i podobne publiczne pliki wejściowe) teraz preferują
|
||||
aktywną migawkę konfiguracji runtime, gdy OpenClaw już działa. Jeśli migawka runtime
|
||||
jeszcze nie istnieje, wracają do rozstrzygniętego pliku konfiguracji na dysku.
|
||||
|
||||
Pluginy dostawców mogą także ujawniać wąski lokalny barrel kontraktu pluginu, gdy
|
||||
helper jest celowo specyficzny dla dostawcy i jeszcze nie należy do ogólnego subpath SDK.
|
||||
Aktualny dołączony przykład: dostawca Anthropic przechowuje swoje helpery
|
||||
strumieni Claude we własnym publicznym interfejsie `api.ts` / `contract-api.ts` zamiast
|
||||
promować logikę nagłówków beta Anthropic i `service_tier` do ogólnego
|
||||
kontraktu `plugin-sdk/*`.
|
||||
Pluginy dostawców mogą także udostępniać wąski lokalny barrel kontraktu pluginu, gdy
|
||||
helper jest celowo specyficzny dla dostawcy i jeszcze nie należy do ogólnej ścieżki podrzędnej SDK.
|
||||
Aktualny wbudowany przykład: dostawca Anthropic przechowuje helpery strumienia Claude
|
||||
we własnej publicznej ścieżce `api.ts` / `contract-api.ts` zamiast promować logikę
|
||||
nagłówka beta Anthropic i `service_tier` do ogólnego kontraktu
|
||||
`plugin-sdk/*`.
|
||||
|
||||
Inne aktualne dołączone przykłady:
|
||||
Inne aktualne wbudowane przykłady:
|
||||
|
||||
- `@openclaw/openai-provider`: `api.ts` eksportuje buildery dostawców,
|
||||
helpery modeli domyślnych i buildery dostawców realtime
|
||||
- `@openclaw/openrouter-provider`: `api.ts` eksportuje builder dostawcy oraz
|
||||
- `@openclaw/openai-provider`: `api.ts` eksportuje konstruktory dostawców,
|
||||
helpery modeli domyślnych i konstruktory dostawców realtime
|
||||
- `@openclaw/openrouter-provider`: `api.ts` eksportuje konstruktor dostawcy oraz
|
||||
helpery onboardingu/konfiguracji
|
||||
|
||||
<Warning>
|
||||
Produkcyjny kod rozszerzeń powinien także unikać importów `openclaw/plugin-sdk/<other-plugin>`.
|
||||
Jeśli helper jest rzeczywiście współdzielony, przenieś go do neutralnego subpath SDK,
|
||||
takiego jak `openclaw/plugin-sdk/speech`, `.../provider-model-shared` lub innej
|
||||
powierzchni zorientowanej na możliwości zamiast łączyć dwa pluginy ze sobą.
|
||||
Kod produkcyjny rozszerzeń powinien też unikać importów `openclaw/plugin-sdk/<other-plugin>`.
|
||||
Jeśli helper jest rzeczywiście współdzielony, przenieś go do neutralnej ścieżki podrzędnej SDK,
|
||||
takiej jak `openclaw/plugin-sdk/speech`, `.../provider-model-shared` lub innej
|
||||
powierzchni zorientowanej na capability, zamiast sprzęgać dwa pluginy ze sobą.
|
||||
</Warning>
|
||||
|
||||
## Powiązane
|
||||
|
||||
- [Entry Points](/pl/plugins/sdk-entrypoints) — opcje `definePluginEntry` i `defineChannelPluginEntry`
|
||||
- [Runtime Helpers](/pl/plugins/sdk-runtime) — pełna referencja przestrzeni nazw `api.runtime`
|
||||
- [Setup and Config](/pl/plugins/sdk-setup) — pakowanie, manifesty, schematy konfiguracji
|
||||
- [Testing](/pl/plugins/sdk-testing) — narzędzia testowe i reguły lint
|
||||
- [SDK Migration](/pl/plugins/sdk-migration) — migracja ze starych powierzchni
|
||||
- [Plugin Internals](/pl/plugins/architecture) — szczegółowa architektura i model możliwości
|
||||
- [Punkty wejścia](/pl/plugins/sdk-entrypoints) — opcje `definePluginEntry` i `defineChannelPluginEntry`
|
||||
- [Helpery runtime](/pl/plugins/sdk-runtime) — pełna dokumentacja przestrzeni nazw `api.runtime`
|
||||
- [Konfiguracja i config](/pl/plugins/sdk-setup) — pakowanie, manifesty, schematy konfiguracji
|
||||
- [Testowanie](/pl/plugins/sdk-testing) — narzędzia testowe i reguły lint
|
||||
- [Migracja SDK](/pl/plugins/sdk-migration) — migracja ze zdeprecjonowanych powierzchni
|
||||
- [Wnętrze pluginów](/pl/plugins/architecture) — szczegółowa architektura i model capabilities
|
||||
|
||||
@ -1,29 +1,29 @@
|
||||
---
|
||||
read_when:
|
||||
- Chcesz wybrać providera modeli
|
||||
- Chcesz wybrać dostawcę modelu
|
||||
- Potrzebujesz szybkiego przeglądu obsługiwanych backendów LLM
|
||||
summary: Providerzy modeli (LLM-y) obsługiwani przez OpenClaw
|
||||
title: Katalog providerów
|
||||
summary: Dostawcy modeli (LLM) obsługiwani przez OpenClaw
|
||||
title: Katalog dostawców
|
||||
x-i18n:
|
||||
generated_at: "2026-04-07T09:48:56Z"
|
||||
generated_at: "2026-04-08T02:17:13Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 39d9ace35fd9452a4fb510fd980d251b6e51480e4647f051020bee2f1f2222e1
|
||||
source_hash: e7bee5528b7fc9a982b3d0eaa4930cb77f7bded19a47aec00572b6fcbd823a70
|
||||
source_path: providers/index.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Providerzy modeli
|
||||
# Dostawcy modeli
|
||||
|
||||
OpenClaw może korzystać z wielu providerów LLM. Wybierz providera, uwierzytelnij się, a następnie ustaw
|
||||
model domyślny jako `provider/model`.
|
||||
OpenClaw może korzystać z wielu dostawców LLM. Wybierz dostawcę, uwierzytelnij się, a następnie ustaw
|
||||
domyślny model jako `provider/model`.
|
||||
|
||||
Szukasz dokumentacji kanałów czatu (WhatsApp/Telegram/Discord/Slack/Mattermost (plugin)/itd.)? Zobacz [Channels](/pl/channels).
|
||||
Szukasz dokumentacji kanałów czatu (WhatsApp/Telegram/Discord/Slack/Mattermost (plugin)/itp.)? Zobacz [Kanały](/pl/channels).
|
||||
|
||||
## Szybki start
|
||||
|
||||
1. Uwierzytelnij się u providera (zwykle przez `openclaw onboard`).
|
||||
2. Ustaw model domyślny:
|
||||
1. Uwierzytelnij się u dostawcy (zwykle przez `openclaw onboard`).
|
||||
2. Ustaw domyślny model:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -31,7 +31,7 @@ Szukasz dokumentacji kanałów czatu (WhatsApp/Telegram/Discord/Slack/Mattermost
|
||||
}
|
||||
```
|
||||
|
||||
## Dokumentacja providerów
|
||||
## Dokumentacja dostawców
|
||||
|
||||
- [Alibaba Model Studio](/pl/providers/alibaba)
|
||||
- [Amazon Bedrock](/pl/providers/bedrock)
|
||||
@ -47,15 +47,16 @@ Szukasz dokumentacji kanałów czatu (WhatsApp/Telegram/Discord/Slack/Mattermost
|
||||
- [GitHub Copilot](/pl/providers/github-copilot)
|
||||
- [Modele GLM](/pl/providers/glm)
|
||||
- [Google (Gemini)](/pl/providers/google)
|
||||
- [Groq (wnioskowanie LPU)](/pl/providers/groq)
|
||||
- [Hugging Face (Inference)](/pl/providers/huggingface)
|
||||
- [Groq (inferencja LPU)](/pl/providers/groq)
|
||||
- [Hugging Face (inferencja)](/pl/providers/huggingface)
|
||||
- [inferrs (modele lokalne)](/pl/providers/inferrs)
|
||||
- [Kilocode](/pl/providers/kilocode)
|
||||
- [LiteLLM (ujednolicony gateway)](/pl/providers/litellm)
|
||||
- [LiteLLM (ujednolicona brama)](/pl/providers/litellm)
|
||||
- [MiniMax](/pl/providers/minimax)
|
||||
- [Mistral](/pl/providers/mistral)
|
||||
- [Moonshot AI (Kimi + Kimi Coding)](/pl/providers/moonshot)
|
||||
- [NVIDIA](/pl/providers/nvidia)
|
||||
- [Ollama (modele chmurowe + lokalne)](/pl/providers/ollama)
|
||||
- [Ollama (chmura + modele lokalne)](/pl/providers/ollama)
|
||||
- [OpenAI (API + Codex)](/pl/providers/openai)
|
||||
- [OpenCode](/pl/providers/opencode)
|
||||
- [OpenCode Go](/pl/providers/opencode-go)
|
||||
@ -80,16 +81,16 @@ Szukasz dokumentacji kanałów czatu (WhatsApp/Telegram/Discord/Slack/Mattermost
|
||||
## Wspólne strony przeglądowe
|
||||
|
||||
- [Dodatkowe dołączone warianty](/pl/providers/models#additional-bundled-provider-variants) - Anthropic Vertex, Copilot Proxy i Gemini CLI OAuth
|
||||
- [Generowanie obrazów](/pl/tools/image-generation) - Wspólne narzędzie `image_generate`, wybór providera i failover
|
||||
- [Generowanie muzyki](/pl/tools/music-generation) - Wspólne narzędzie `music_generate`, wybór providera i failover
|
||||
- [Generowanie wideo](/pl/tools/video-generation) - Wspólne narzędzie `video_generate`, wybór providera i failover
|
||||
- [Generowanie obrazów](/pl/tools/image-generation) - Współdzielone narzędzie `image_generate`, wybór dostawcy i failover
|
||||
- [Generowanie muzyki](/pl/tools/music-generation) - Współdzielone narzędzie `music_generate`, wybór dostawcy i failover
|
||||
- [Generowanie wideo](/pl/tools/video-generation) - Współdzielone narzędzie `video_generate`, wybór dostawcy i failover
|
||||
|
||||
## Providerzy transkrypcji
|
||||
## Dostawcy transkrypcji
|
||||
|
||||
- [Deepgram (transkrypcja audio)](/pl/providers/deepgram)
|
||||
|
||||
## Narzędzia społeczności
|
||||
|
||||
- [Claude Max API Proxy](/pl/providers/claude-max-api-proxy) - Proxy społecznościowe dla poświadczeń subskrypcji Claude (przed użyciem zweryfikuj zasady/warunki Anthropic)
|
||||
- [Claude Max API Proxy](/pl/providers/claude-max-api-proxy) - Społecznościowy proxy dla poświadczeń subskrypcji Claude (przed użyciem zweryfikuj zasady/warunki Anthropic)
|
||||
|
||||
Pełny katalog providerów (xAI, Groq, Mistral itd.) oraz zaawansowaną konfigurację znajdziesz w [Model providers](/pl/concepts/model-providers).
|
||||
Pełny katalog dostawców (xAI, Groq, Mistral itd.) oraz zaawansowaną konfigurację znajdziesz w [Dostawcy modeli](/pl/concepts/model-providers).
|
||||
|
||||
179
docs/pl/providers/inferrs.md
Normal file
179
docs/pl/providers/inferrs.md
Normal file
@ -0,0 +1,179 @@
|
||||
---
|
||||
read_when:
|
||||
- Chcesz uruchomić OpenClaw z lokalnym serwerem inferrs
|
||||
- Udostępniasz Gemma lub inny model przez inferrs
|
||||
- Potrzebujesz dokładnych flag zgodności OpenClaw dla inferrs
|
||||
summary: Uruchamianie OpenClaw przez inferrs (lokalny serwer zgodny z OpenAI)
|
||||
title: inferrs
|
||||
x-i18n:
|
||||
generated_at: "2026-04-08T02:17:28Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: d84f660d49a682d0c0878707eebe1bc1e83dd115850687076ea3938b9f9c86c6
|
||||
source_path: providers/inferrs.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# inferrs
|
||||
|
||||
[inferrs](https://github.com/ericcurtin/inferrs) może udostępniać lokalne modele za
|
||||
interfejsem API `/v1` zgodnym z OpenAI. OpenClaw współpracuje z `inferrs` przez ogólną
|
||||
ścieżkę `openai-completions`.
|
||||
|
||||
`inferrs` najlepiej obecnie traktować jako niestandardowy, samodzielnie hostowany backend
|
||||
zgodny z OpenAI, a nie dedykowaną wtyczkę dostawcy OpenClaw.
|
||||
|
||||
## Szybki start
|
||||
|
||||
1. Uruchom `inferrs` z modelem.
|
||||
|
||||
Przykład:
|
||||
|
||||
```bash
|
||||
inferrs serve gg-hf-gg/gemma-4-E2B-it \
|
||||
--host 127.0.0.1 \
|
||||
--port 8080 \
|
||||
--device metal
|
||||
```
|
||||
|
||||
2. Sprawdź, czy serwer jest osiągalny.
|
||||
|
||||
```bash
|
||||
curl http://127.0.0.1:8080/health
|
||||
curl http://127.0.0.1:8080/v1/models
|
||||
```
|
||||
|
||||
3. Dodaj jawny wpis dostawcy OpenClaw i skieruj na niego swój model domyślny.
|
||||
|
||||
## Pełny przykład konfiguracji
|
||||
|
||||
Ten przykład używa Gemma 4 na lokalnym serwerze `inferrs`.
|
||||
|
||||
```json5
|
||||
{
|
||||
agents: {
|
||||
defaults: {
|
||||
model: { primary: "inferrs/gg-hf-gg/gemma-4-E2B-it" },
|
||||
models: {
|
||||
"inferrs/gg-hf-gg/gemma-4-E2B-it": {
|
||||
alias: "Gemma 4 (inferrs)",
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
models: {
|
||||
mode: "merge",
|
||||
providers: {
|
||||
inferrs: {
|
||||
baseUrl: "http://127.0.0.1:8080/v1",
|
||||
apiKey: "inferrs-local",
|
||||
api: "openai-completions",
|
||||
models: [
|
||||
{
|
||||
id: "gg-hf-gg/gemma-4-E2B-it",
|
||||
name: "Gemma 4 E2B (inferrs)",
|
||||
reasoning: false,
|
||||
input: ["text"],
|
||||
cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
|
||||
contextWindow: 131072,
|
||||
maxTokens: 4096,
|
||||
compat: {
|
||||
requiresStringContent: true,
|
||||
},
|
||||
},
|
||||
],
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
## Dlaczego `requiresStringContent` ma znaczenie
|
||||
|
||||
Niektóre ścieżki Chat Completions w `inferrs` akceptują tylko ciąg znaków w
|
||||
`messages[].content`, a nie strukturalne tablice części treści.
|
||||
|
||||
Jeśli uruchomienia OpenClaw kończą się błędem takim jak:
|
||||
|
||||
```text
|
||||
messages[1].content: invalid type: sequence, expected a string
|
||||
```
|
||||
|
||||
ustaw:
|
||||
|
||||
```json5
|
||||
compat: {
|
||||
requiresStringContent: true
|
||||
}
|
||||
```
|
||||
|
||||
OpenClaw spłaszczy części treści zawierające wyłącznie tekst do zwykłych ciągów znaków przed wysłaniem
|
||||
żądania.
|
||||
|
||||
## Zastrzeżenie dotyczące Gemma i schematu narzędzi
|
||||
|
||||
Niektóre obecne kombinacje `inferrs` + Gemma akceptują małe, bezpośrednie
|
||||
żądania `/v1/chat/completions`, ale nadal kończą się niepowodzeniem przy pełnych turach
|
||||
runtime agenta OpenClaw.
|
||||
|
||||
Jeśli tak się dzieje, najpierw spróbuj tego:
|
||||
|
||||
```json5
|
||||
compat: {
|
||||
requiresStringContent: true,
|
||||
supportsTools: false
|
||||
}
|
||||
```
|
||||
|
||||
To wyłącza powierzchnię schematu narzędzi OpenClaw dla modelu i może zmniejszyć presję promptu
|
||||
na bardziej restrykcyjnych lokalnych backendach.
|
||||
|
||||
Jeśli małe bezpośrednie żądania nadal działają, ale zwykłe tury agenta OpenClaw wciąż
|
||||
powodują awarie wewnątrz `inferrs`, pozostały problem zwykle leży po stronie zachowania modelu/serwera upstream, a nie warstwy transportowej OpenClaw.
|
||||
|
||||
## Ręczny test smoke
|
||||
|
||||
Po konfiguracji przetestuj obie warstwy:
|
||||
|
||||
```bash
|
||||
curl http://127.0.0.1:8080/v1/chat/completions \
|
||||
-H 'content-type: application/json' \
|
||||
-d '{"model":"gg-hf-gg/gemma-4-E2B-it","messages":[{"role":"user","content":"What is 2 + 2?"}],"stream":false}'
|
||||
|
||||
openclaw infer model run \
|
||||
--model inferrs/gg-hf-gg/gemma-4-E2B-it \
|
||||
--prompt "What is 2 + 2? Reply with one short sentence." \
|
||||
--json
|
||||
```
|
||||
|
||||
Jeśli pierwsze polecenie działa, ale drugie kończy się niepowodzeniem, skorzystaj z poniższych uwag
|
||||
dotyczących rozwiązywania problemów.
|
||||
|
||||
## Rozwiązywanie problemów
|
||||
|
||||
- `curl /v1/models` kończy się niepowodzeniem: `inferrs` nie działa, nie jest osiągalny lub nie
|
||||
jest powiązany z oczekiwanym hostem/portem.
|
||||
- `messages[].content ... expected a string`: ustaw
|
||||
`compat.requiresStringContent: true`.
|
||||
- Bezpośrednie małe wywołania `/v1/chat/completions` przechodzą, ale `openclaw infer model run`
|
||||
kończy się niepowodzeniem: spróbuj `compat.supportsTools: false`.
|
||||
- OpenClaw nie dostaje już błędów schematu, ale `inferrs` nadal ulega awarii przy większych
|
||||
turach agenta: potraktuj to jako ograniczenie `inferrs` lub modelu upstream i zmniejsz
|
||||
presję promptu albo zmień lokalny backend/model.
|
||||
|
||||
## Zachowanie w stylu proxy
|
||||
|
||||
`inferrs` jest traktowany jako backend `/v1` zgodny z OpenAI w stylu proxy, a nie
|
||||
natywny endpoint OpenAI.
|
||||
|
||||
- natywne kształtowanie żądań tylko dla OpenAI nie ma tu zastosowania
|
||||
- brak `service_tier`, brak `store` dla Responses, brak wskazówek prompt-cache i brak
|
||||
kształtowania ładunku zgodności reasoning OpenAI
|
||||
- ukryte nagłówki atrybucji OpenClaw (`originator`, `version`, `User-Agent`)
|
||||
nie są wstrzykiwane do niestandardowych adresów `inferrs` base URLs
|
||||
|
||||
## Zobacz też
|
||||
|
||||
- [Modele lokalne](/pl/gateway/local-models)
|
||||
- [Rozwiązywanie problemów z gatewayem](/pl/gateway/troubleshooting#local-openai-compatible-backend-passes-direct-probes-but-agent-runs-fail)
|
||||
- [Dostawcy modeli](/pl/concepts/model-providers)
|
||||
@ -1,21 +1,21 @@
|
||||
---
|
||||
read_when:
|
||||
- Chcesz używać modeli NVIDIA w OpenClaw
|
||||
- Chcesz używać otwartych modeli w OpenClaw za darmo
|
||||
- Potrzebujesz konfiguracji NVIDIA_API_KEY
|
||||
summary: Używaj zgodnego z OpenAI API NVIDIA w OpenClaw
|
||||
title: NVIDIA
|
||||
x-i18n:
|
||||
generated_at: "2026-04-05T14:03:12Z"
|
||||
generated_at: "2026-04-08T02:17:20Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: a24c5e46c0cf0fbc63bf09c772b486dd7f8f4b52e687d3b835bb54a1176b28da
|
||||
source_hash: b00f8cedaf223a33ba9f6a6dd8cf066d88cebeea52d391b871e435026182228a
|
||||
source_path: providers/nvidia.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# NVIDIA
|
||||
|
||||
NVIDIA udostępnia zgodne z OpenAI API pod adresem `https://integrate.api.nvidia.com/v1` dla modeli Nemotron i NeMo. Uwierzytelnianie odbywa się przez klucz API z [NVIDIA NGC](https://catalog.ngc.nvidia.com/).
|
||||
NVIDIA udostępnia zgodne z OpenAI API pod adresem `https://integrate.api.nvidia.com/v1` dla otwartych modeli za darmo. Uwierzytelnij się za pomocą klucza API z [build.nvidia.com](https://build.nvidia.com/settings/api-keys).
|
||||
|
||||
## Konfiguracja CLI
|
||||
|
||||
@ -24,12 +24,12 @@ Wyeksportuj klucz raz, a następnie uruchom onboarding i ustaw model NVIDIA:
|
||||
```bash
|
||||
export NVIDIA_API_KEY="nvapi-..."
|
||||
openclaw onboard --auth-choice skip
|
||||
openclaw models set nvidia/nvidia/llama-3.1-nemotron-70b-instruct
|
||||
openclaw models set nvidia/nvidia/nemotron-3-super-120b-a12b
|
||||
```
|
||||
|
||||
Jeśli nadal przekazujesz `--token`, pamiętaj, że trafia on do historii powłoki i wyjścia `ps`; jeśli to możliwe, preferuj zmienną env.
|
||||
Jeśli nadal przekazujesz `--token`, pamiętaj, że trafia on do historii powłoki i danych wyjściowych `ps`; jeśli to możliwe, preferuj zmienną środowiskową.
|
||||
|
||||
## Fragment config
|
||||
## Fragment konfiguracji
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -44,7 +44,7 @@ Jeśli nadal przekazujesz `--token`, pamiętaj, że trafia on do historii powło
|
||||
},
|
||||
agents: {
|
||||
defaults: {
|
||||
model: { primary: "nvidia/nvidia/llama-3.1-nemotron-70b-instruct" },
|
||||
model: { primary: "nvidia/nvidia/nemotron-3-super-120b-a12b" },
|
||||
},
|
||||
},
|
||||
}
|
||||
@ -52,14 +52,15 @@ Jeśli nadal przekazujesz `--token`, pamiętaj, że trafia on do historii powło
|
||||
|
||||
## Identyfikatory modeli
|
||||
|
||||
| Model ref | Name | Context | Max output |
|
||||
| ---------------------------------------------------- | ---------------------------------------- | ------- | ---------- |
|
||||
| `nvidia/nvidia/llama-3.1-nemotron-70b-instruct` | NVIDIA Llama 3.1 Nemotron 70B Instruct | 131,072 | 4,096 |
|
||||
| `nvidia/meta/llama-3.3-70b-instruct` | Meta Llama 3.3 70B Instruct | 131,072 | 4,096 |
|
||||
| `nvidia/nvidia/mistral-nemo-minitron-8b-8k-instruct` | NVIDIA Mistral NeMo Minitron 8B Instruct | 8,192 | 2,048 |
|
||||
| Model ref | Nazwa | Kontekst | Maks. wynik |
|
||||
| ------------------------------------------ | ---------------------------- | -------- | ----------- |
|
||||
| `nvidia/nvidia/nemotron-3-super-120b-a12b` | NVIDIA Nemotron 3 Super 120B | 262,144 | 8,192 |
|
||||
| `nvidia/moonshotai/kimi-k2.5` | Kimi K2.5 | 262,144 | 8,192 |
|
||||
| `nvidia/minimaxai/minimax-m2.5` | Minimax M2.5 | 196,608 | 8,192 |
|
||||
| `nvidia/z-ai/glm5` | GLM 5 | 202,752 | 8,192 |
|
||||
|
||||
## Uwagi
|
||||
|
||||
- Endpoint `/v1` zgodny z OpenAI; użyj klucza API z NVIDIA NGC.
|
||||
- Provider włącza się automatycznie, gdy ustawiono `NVIDIA_API_KEY`.
|
||||
- Dołączony katalog jest statyczny; koszty domyślnie mają wartość `0` w źródłach.
|
||||
- Zgodny z OpenAI punkt końcowy `/v1`; użyj klucza API z [build.nvidia.com](https://build.nvidia.com/).
|
||||
- Dostawca włącza się automatycznie, gdy ustawiono `NVIDIA_API_KEY`.
|
||||
- Dołączony katalog jest statyczny; koszty domyślnie wynoszą `0` w źródle.
|
||||
|
||||
@ -1,24 +1,24 @@
|
||||
---
|
||||
read_when:
|
||||
- Chcesz uruchamiać OpenClaw z modelami chmurowymi lub lokalnymi przez Ollama
|
||||
- Potrzebujesz wskazówek dotyczących instalacji i konfiguracji Ollama
|
||||
- Potrzebujesz wskazówek dotyczących konfiguracji i ustawień Ollama
|
||||
summary: Uruchamianie OpenClaw z Ollama (modele chmurowe i lokalne)
|
||||
title: Ollama
|
||||
x-i18n:
|
||||
generated_at: "2026-04-05T14:04:01Z"
|
||||
generated_at: "2026-04-08T02:17:58Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 337b8ec3a7756e591e6d6f82e8ad13417f0f20c394ec540e8fc5756e0fc13c29
|
||||
source_hash: 222ec68f7d4bb29cc7796559ddef1d5059f5159e7a51e2baa3a271ddb3abb716
|
||||
source_path: providers/ollama.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Ollama
|
||||
|
||||
Ollama to lokalne środowisko uruchomieniowe LLM, które ułatwia uruchamianie modeli open source na własnej maszynie. OpenClaw integruje się z natywnym API Ollama (`/api/chat`), obsługuje streaming i wywoływanie narzędzi oraz może automatycznie wykrywać lokalne modele Ollama, gdy włączysz to przez `OLLAMA_API_KEY` (lub profil auth) i nie zdefiniujesz jawnego wpisu `models.providers.ollama`.
|
||||
Ollama to lokalne środowisko uruchomieniowe LLM, które ułatwia uruchamianie modeli open source na Twoim komputerze. OpenClaw integruje się z natywnym API Ollama (`/api/chat`), obsługuje streaming i wywoływanie narzędzi oraz może automatycznie wykrywać lokalne modele Ollama, gdy włączysz to przez `OLLAMA_API_KEY` (lub profil uwierzytelniania) i nie zdefiniujesz jawnego wpisu `models.providers.ollama`.
|
||||
|
||||
<Warning>
|
||||
**Użytkownicy zdalnego Ollama**: Nie używaj URL zgodnego z OpenAI `/v1` (`http://host:11434/v1`) z OpenClaw. To psuje wywoływanie narzędzi i modele mogą zwracać surowy JSON narzędzi jako zwykły tekst. Zamiast tego użyj natywnego URL API Ollama: `baseUrl: "http://host:11434"` (bez `/v1`).
|
||||
**Użytkownicy zdalnego Ollama**: Nie używaj zgodnego z OpenAI adresu URL `/v1` (`http://host:11434/v1`) z OpenClaw. Powoduje to uszkodzenie wywoływania narzędzi, a modele mogą zwracać surowy JSON narzędzi jako zwykły tekst. Zamiast tego użyj natywnego adresu URL API Ollama: `baseUrl: "http://host:11434"` (bez `/v1`).
|
||||
</Warning>
|
||||
|
||||
## Szybki start
|
||||
@ -33,13 +33,13 @@ openclaw onboard
|
||||
|
||||
Wybierz **Ollama** z listy dostawców. Onboarding:
|
||||
|
||||
1. Poprosi o bazowy URL Ollama, pod którym twoja instancja jest dostępna (domyślnie `http://127.0.0.1:11434`).
|
||||
2. Pozwoli wybrać **Cloud + Local** (modele chmurowe i lokalne) albo **Local** (tylko modele lokalne).
|
||||
3. Otworzy w przeglądarce przepływ logowania, jeśli wybierzesz **Cloud + Local** i nie jesteś zalogowany w ollama.com.
|
||||
4. Wykryje dostępne modele i zasugeruje ustawienia domyślne.
|
||||
1. Poprosi o podstawowy adres URL Ollama, pod którym Twoja instancja jest dostępna (domyślnie `http://127.0.0.1:11434`).
|
||||
2. Pozwoli wybrać **Cloud + Local** (modele chmurowe i lokalne) lub **Local** (tylko modele lokalne).
|
||||
3. Otworzy w przeglądarce przepływ logowania, jeśli wybierzesz **Cloud + Local** i nie jesteś zalogowany do ollama.com.
|
||||
4. Wykryje dostępne modele i zasugeruje wartości domyślne.
|
||||
5. Automatycznie pobierze wybrany model, jeśli nie jest dostępny lokalnie.
|
||||
|
||||
Obsługiwany jest także tryb nieinteraktywny:
|
||||
Obsługiwany jest również tryb nieinteraktywny:
|
||||
|
||||
```bash
|
||||
openclaw onboard --non-interactive \
|
||||
@ -47,7 +47,7 @@ openclaw onboard --non-interactive \
|
||||
--accept-risk
|
||||
```
|
||||
|
||||
Opcjonalnie możesz podać niestandardowy bazowy URL lub model:
|
||||
Opcjonalnie podaj niestandardowy podstawowy adres URL lub model:
|
||||
|
||||
```bash
|
||||
openclaw onboard --non-interactive \
|
||||
@ -61,17 +61,17 @@ openclaw onboard --non-interactive \
|
||||
|
||||
1. Zainstaluj Ollama: [https://ollama.com/download](https://ollama.com/download)
|
||||
|
||||
2. Pobierz model lokalny, jeśli chcesz używać inferencji lokalnej:
|
||||
2. Pobierz lokalny model, jeśli chcesz korzystać z inferencji lokalnej:
|
||||
|
||||
```bash
|
||||
ollama pull glm-4.7-flash
|
||||
ollama pull gemma4
|
||||
# lub
|
||||
ollama pull gpt-oss:20b
|
||||
# lub
|
||||
ollama pull llama3.3
|
||||
```
|
||||
|
||||
3. Jeśli chcesz także modele chmurowe, zaloguj się:
|
||||
3. Jeśli chcesz korzystać także z modeli chmurowych, zaloguj się:
|
||||
|
||||
```bash
|
||||
ollama signin
|
||||
@ -84,13 +84,13 @@ openclaw onboard
|
||||
```
|
||||
|
||||
- `Local`: tylko modele lokalne
|
||||
- `Cloud + Local`: modele lokalne plus modele chmurowe
|
||||
- Modele chmurowe, takie jak `kimi-k2.5:cloud`, `minimax-m2.5:cloud` i `glm-5:cloud`, **nie** wymagają lokalnego `ollama pull`
|
||||
- `Cloud + Local`: modele lokalne oraz modele chmurowe
|
||||
- Modele chmurowe takie jak `kimi-k2.5:cloud`, `minimax-m2.7:cloud` i `glm-5.1:cloud` **nie** wymagają lokalnego `ollama pull`
|
||||
|
||||
OpenClaw obecnie sugeruje:
|
||||
|
||||
- domyślny model lokalny: `glm-4.7-flash`
|
||||
- domyślne modele chmurowe: `kimi-k2.5:cloud`, `minimax-m2.5:cloud`, `glm-5:cloud`
|
||||
- domyślny model lokalny: `gemma4`
|
||||
- domyślne modele chmurowe: `kimi-k2.5:cloud`, `minimax-m2.7:cloud`, `glm-5.1:cloud`
|
||||
|
||||
5. Jeśli wolisz konfigurację ręczną, włącz Ollama bezpośrednio dla OpenClaw (dowolna wartość działa; Ollama nie wymaga prawdziwego klucza):
|
||||
|
||||
@ -102,36 +102,36 @@ export OLLAMA_API_KEY="ollama-local"
|
||||
openclaw config set models.providers.ollama.apiKey "ollama-local"
|
||||
```
|
||||
|
||||
6. Sprawdź lub przełącz modele:
|
||||
6. Sprawdź dostępne modele lub przełącz model:
|
||||
|
||||
```bash
|
||||
openclaw models list
|
||||
openclaw models set ollama/glm-4.7-flash
|
||||
openclaw models set ollama/gemma4
|
||||
```
|
||||
|
||||
7. Lub ustaw domyślny model w konfiguracji:
|
||||
7. Albo ustaw domyślny model w konfiguracji:
|
||||
|
||||
```json5
|
||||
{
|
||||
agents: {
|
||||
defaults: {
|
||||
model: { primary: "ollama/glm-4.7-flash" },
|
||||
model: { primary: "ollama/gemma4" },
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
## Wykrywanie modeli (niejawny dostawca)
|
||||
## Wykrywanie modeli (dostawca niejawny)
|
||||
|
||||
Gdy ustawisz `OLLAMA_API_KEY` (lub profil auth) i **nie** zdefiniujesz `models.providers.ollama`, OpenClaw wykrywa modele z lokalnej instancji Ollama pod adresem `http://127.0.0.1:11434`:
|
||||
Gdy ustawisz `OLLAMA_API_KEY` (lub profil uwierzytelniania) i **nie** zdefiniujesz `models.providers.ollama`, OpenClaw wykryje modele z lokalnej instancji Ollama pod adresem `http://127.0.0.1:11434`:
|
||||
|
||||
- Odpytuje `/api/tags`
|
||||
- Używa mechanizmu best-effort do odpytań `/api/show`, aby odczytać `contextWindow`, gdy jest dostępne
|
||||
- Oznacza `reasoning` przy użyciu heurystyki nazwy modelu (`r1`, `reasoning`, `think`)
|
||||
- Używa najlepszego możliwego wyszukiwania `/api/show`, aby odczytać `contextWindow`, gdy jest dostępne
|
||||
- Oznacza `reasoning` za pomocą heurystyki nazwy modelu (`r1`, `reasoning`, `think`)
|
||||
- Ustawia `maxTokens` na domyślny limit maksymalnej liczby tokenów Ollama używany przez OpenClaw
|
||||
- Ustawia wszystkie koszty na `0`
|
||||
|
||||
Pozwala to uniknąć ręcznego dodawania modeli, a jednocześnie utrzymuje katalog zgodny z lokalną instancją Ollama.
|
||||
Pozwala to uniknąć ręcznego wpisywania modeli, jednocześnie utrzymując katalog zgodny z lokalną instancją Ollama.
|
||||
|
||||
Aby zobaczyć, jakie modele są dostępne:
|
||||
|
||||
@ -148,24 +148,24 @@ ollama pull mistral
|
||||
|
||||
Nowy model zostanie automatycznie wykryty i będzie dostępny do użycia.
|
||||
|
||||
Jeśli jawnie ustawisz `models.providers.ollama`, automatyczne wykrywanie zostanie pominięte i modele trzeba będzie zdefiniować ręcznie (patrz niżej).
|
||||
Jeśli jawnie ustawisz `models.providers.ollama`, automatyczne wykrywanie zostanie pominięte i musisz zdefiniować modele ręcznie (zobacz poniżej).
|
||||
|
||||
## Konfiguracja
|
||||
|
||||
### Podstawowa konfiguracja (niejawne wykrywanie)
|
||||
### Podstawowa konfiguracja (wykrywanie niejawne)
|
||||
|
||||
Najprostszy sposób włączenia Ollama to użycie zmiennej środowiskowej:
|
||||
Najprostszym sposobem włączenia Ollama jest użycie zmiennej środowiskowej:
|
||||
|
||||
```bash
|
||||
export OLLAMA_API_KEY="ollama-local"
|
||||
```
|
||||
|
||||
### Jawna konfiguracja (modele ręczne)
|
||||
### Konfiguracja jawna (ręczne modele)
|
||||
|
||||
Użyj jawnej konfiguracji, gdy:
|
||||
Używaj jawnej konfiguracji, gdy:
|
||||
|
||||
- Ollama działa na innym hoście lub porcie.
|
||||
- Chcesz wymusić konkretne okna kontekstu lub listy modeli.
|
||||
- Chcesz wymusić określone okna kontekstu lub listy modeli.
|
||||
- Chcesz w pełni ręcznie definiować modele.
|
||||
|
||||
```json5
|
||||
@ -193,9 +193,9 @@ Użyj jawnej konfiguracji, gdy:
|
||||
}
|
||||
```
|
||||
|
||||
Jeśli ustawiono `OLLAMA_API_KEY`, możesz pominąć `apiKey` we wpisie dostawcy, a OpenClaw uzupełni go na potrzeby sprawdzania dostępności.
|
||||
Jeśli ustawiono `OLLAMA_API_KEY`, możesz pominąć `apiKey` we wpisie dostawcy, a OpenClaw uzupełni je na potrzeby sprawdzania dostępności.
|
||||
|
||||
### Niestandardowy bazowy URL (jawna konfiguracja)
|
||||
### Niestandardowy podstawowy adres URL (konfiguracja jawna)
|
||||
|
||||
Jeśli Ollama działa na innym hoście lub porcie (jawna konfiguracja wyłącza automatyczne wykrywanie, więc modele trzeba zdefiniować ręcznie):
|
||||
|
||||
@ -205,8 +205,8 @@ Jeśli Ollama działa na innym hoście lub porcie (jawna konfiguracja wyłącza
|
||||
providers: {
|
||||
ollama: {
|
||||
apiKey: "ollama-local",
|
||||
baseUrl: "http://ollama-host:11434", // Bez /v1 - użyj natywnego URL API Ollama
|
||||
api: "ollama", // Ustaw jawnie, aby zagwarantować natywne wywoływanie narzędzi
|
||||
baseUrl: "http://ollama-host:11434", // Bez /v1 - użyj natywnego adresu URL API Ollama
|
||||
api: "ollama", // Ustaw jawnie, aby zagwarantować natywne zachowanie wywoływania narzędzi
|
||||
},
|
||||
},
|
||||
},
|
||||
@ -214,12 +214,12 @@ Jeśli Ollama działa na innym hoście lub porcie (jawna konfiguracja wyłącza
|
||||
```
|
||||
|
||||
<Warning>
|
||||
Nie dodawaj `/v1` do URL. Ścieżka `/v1` używa trybu zgodnego z OpenAI, w którym wywoływanie narzędzi nie jest niezawodne. Użyj bazowego URL Ollama bez sufiksu ścieżki.
|
||||
Nie dodawaj `/v1` do adresu URL. Ścieżka `/v1` używa trybu zgodnego z OpenAI, w którym wywoływanie narzędzi nie jest niezawodne. Używaj podstawowego adresu URL Ollama bez sufiksu ścieżki.
|
||||
</Warning>
|
||||
|
||||
### Wybór modelu
|
||||
|
||||
Po skonfigurowaniu wszystkie twoje modele Ollama są dostępne:
|
||||
Po skonfigurowaniu wszystkie modele Ollama są dostępne:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -236,24 +236,24 @@ Po skonfigurowaniu wszystkie twoje modele Ollama są dostępne:
|
||||
|
||||
## Modele chmurowe
|
||||
|
||||
Modele chmurowe pozwalają uruchamiać modele hostowane w chmurze (na przykład `kimi-k2.5:cloud`, `minimax-m2.5:cloud`, `glm-5:cloud`) obok modeli lokalnych.
|
||||
Modele chmurowe pozwalają uruchamiać modele hostowane w chmurze (na przykład `kimi-k2.5:cloud`, `minimax-m2.7:cloud`, `glm-5.1:cloud`) obok modeli lokalnych.
|
||||
|
||||
Aby używać modeli chmurowych, podczas konfiguracji wybierz tryb **Cloud + Local**. Kreator sprawdza, czy jesteś zalogowany, i w razie potrzeby otwiera w przeglądarce przepływ logowania. Jeśli nie można zweryfikować uwierzytelnienia, kreator wraca do domyślnych modeli lokalnych.
|
||||
Aby używać modeli chmurowych, wybierz tryb **Cloud + Local** podczas konfiguracji. Kreator sprawdza, czy jesteś zalogowany, i w razie potrzeby otwiera w przeglądarce przepływ logowania. Jeśli nie można zweryfikować uwierzytelnienia, kreator przechodzi do domyślnych modeli lokalnych.
|
||||
|
||||
Możesz też zalogować się bezpośrednio na [ollama.com/signin](https://ollama.com/signin).
|
||||
|
||||
## Ollama Web Search
|
||||
|
||||
OpenClaw obsługuje także **Ollama Web Search** jako wbudowanego dostawcę
|
||||
OpenClaw obsługuje także **Ollama Web Search** jako dołączonego dostawcę
|
||||
`web_search`.
|
||||
|
||||
- Używa skonfigurowanego hosta Ollama (`models.providers.ollama.baseUrl`, jeśli
|
||||
ustawiono, w przeciwnym razie `http://127.0.0.1:11434`).
|
||||
jest ustawione, w przeciwnym razie `http://127.0.0.1:11434`).
|
||||
- Nie wymaga klucza.
|
||||
- Wymaga uruchomionego Ollama oraz zalogowania przez `ollama signin`.
|
||||
- Wymaga uruchomionego Ollama i zalogowania przez `ollama signin`.
|
||||
|
||||
Wybierz **Ollama Web Search** podczas `openclaw onboard` albo
|
||||
`openclaw configure --section web`, lub ustaw:
|
||||
Wybierz **Ollama Web Search** podczas `openclaw onboard` lub
|
||||
`openclaw configure --section web`, albo ustaw:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -267,13 +267,13 @@ Wybierz **Ollama Web Search** podczas `openclaw onboard` albo
|
||||
}
|
||||
```
|
||||
|
||||
Pełne informacje o konfiguracji i zachowaniu znajdziesz w [Ollama Web Search](/tools/ollama-search).
|
||||
Pełną konfigurację i szczegóły działania znajdziesz w [Ollama Web Search](/pl/tools/ollama-search).
|
||||
|
||||
## Zaawansowane
|
||||
|
||||
### Modele reasoning
|
||||
|
||||
OpenClaw domyślnie traktuje modele o nazwach takich jak `deepseek-r1`, `reasoning` lub `think` jako modele obsługujące reasoning:
|
||||
OpenClaw domyślnie traktuje modele o nazwach takich jak `deepseek-r1`, `reasoning` lub `think` jako zdolne do reasoning:
|
||||
|
||||
```bash
|
||||
ollama pull deepseek-r1:32b
|
||||
@ -281,11 +281,11 @@ ollama pull deepseek-r1:32b
|
||||
|
||||
### Koszty modeli
|
||||
|
||||
Ollama jest bezpłatna i działa lokalnie, więc wszystkie koszty modeli są ustawione na $0.
|
||||
Ollama jest darmowe i działa lokalnie, więc wszystkie koszty modeli są ustawione na $0.
|
||||
|
||||
### Konfiguracja streamingu
|
||||
|
||||
Integracja OpenClaw z Ollama domyślnie używa **natywnego API Ollama** (`/api/chat`), które w pełni obsługuje jednocześnie streaming i wywoływanie narzędzi. Nie jest wymagana żadna specjalna konfiguracja.
|
||||
Integracja OpenClaw z Ollama domyślnie używa **natywnego API Ollama** (`/api/chat`), które w pełni obsługuje jednocześnie streaming i wywoływanie narzędzi. Nie jest potrzebna żadna specjalna konfiguracja.
|
||||
|
||||
#### Starszy tryb zgodny z OpenAI
|
||||
|
||||
@ -293,7 +293,7 @@ Integracja OpenClaw z Ollama domyślnie używa **natywnego API Ollama** (`/api/c
|
||||
**Wywoływanie narzędzi nie jest niezawodne w trybie zgodnym z OpenAI.** Używaj tego trybu tylko wtedy, gdy potrzebujesz formatu OpenAI dla proxy i nie polegasz na natywnym zachowaniu wywoływania narzędzi.
|
||||
</Warning>
|
||||
|
||||
Jeśli zamiast tego musisz użyć punktu końcowego zgodnego z OpenAI (na przykład za proxy, które obsługuje tylko format OpenAI), jawnie ustaw `api: "openai-completions"`:
|
||||
Jeśli zamiast tego musisz używać punktu końcowego zgodnego z OpenAI (np. za proxy, które obsługuje tylko format OpenAI), ustaw jawnie `api: "openai-completions"`:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -311,9 +311,9 @@ Jeśli zamiast tego musisz użyć punktu końcowego zgodnego z OpenAI (na przyk
|
||||
}
|
||||
```
|
||||
|
||||
Ten tryb może nie obsługiwać jednocześnie streamingu i wywoływania narzędzi. Może być konieczne wyłączenie streamingu przez `params: { streaming: false }` w konfiguracji modelu.
|
||||
Ten tryb może nie obsługiwać jednocześnie streamingu i wywoływania narzędzi. Może być konieczne wyłączenie streamingu za pomocą `params: { streaming: false }` w konfiguracji modelu.
|
||||
|
||||
Gdy `api: "openai-completions"` jest używane z Ollama, OpenClaw domyślnie wstrzykuje `options.num_ctx`, aby Ollama nie wracała po cichu do okna kontekstu 4096. Jeśli twoje proxy/upstream odrzuca nieznane pola `options`, wyłącz to zachowanie:
|
||||
Gdy `api: "openai-completions"` jest używane z Ollama, OpenClaw domyślnie wstrzykuje `options.num_ctx`, aby Ollama nie przechodziło po cichu na okno kontekstu 4096. Jeśli Twoje proxy/upstream odrzuca nieznane pola `options`, wyłącz to zachowanie:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -333,19 +333,19 @@ Gdy `api: "openai-completions"` jest używane z Ollama, OpenClaw domyślnie wstr
|
||||
|
||||
### Okna kontekstu
|
||||
|
||||
Dla modeli wykrytych automatycznie OpenClaw używa okna kontekstu raportowanego przez Ollama, gdy jest dostępne, w przeciwnym razie wraca do domyślnego okna kontekstu Ollama używanego przez OpenClaw. Możesz nadpisać `contextWindow` i `maxTokens` w jawnej konfiguracji dostawcy.
|
||||
Dla modeli wykrytych automatycznie OpenClaw używa okna kontekstu zgłaszanego przez Ollama, jeśli jest dostępne, w przeciwnym razie przechodzi na domyślne okno kontekstu Ollama używane przez OpenClaw. Możesz nadpisać `contextWindow` i `maxTokens` w jawnej konfiguracji dostawcy.
|
||||
|
||||
## Rozwiązywanie problemów
|
||||
|
||||
### Nie wykryto Ollama
|
||||
|
||||
Upewnij się, że Ollama działa, że ustawiono `OLLAMA_API_KEY` (lub profil auth), i że **nie** zdefiniowano jawnego wpisu `models.providers.ollama`:
|
||||
Upewnij się, że Ollama działa, że ustawiono `OLLAMA_API_KEY` (lub profil uwierzytelniania) i że **nie** zdefiniowano jawnego wpisu `models.providers.ollama`:
|
||||
|
||||
```bash
|
||||
ollama serve
|
||||
```
|
||||
|
||||
Upewnij się też, że API jest dostępne:
|
||||
Oraz że API jest dostępne:
|
||||
|
||||
```bash
|
||||
curl http://localhost:11434/api/tags
|
||||
@ -353,16 +353,16 @@ curl http://localhost:11434/api/tags
|
||||
|
||||
### Brak dostępnych modeli
|
||||
|
||||
Jeśli twojego modelu nie ma na liście, zrób jedną z tych rzeczy:
|
||||
Jeśli Twojego modelu nie ma na liście, zrób jedno z poniższych:
|
||||
|
||||
- Pobierz model lokalnie albo
|
||||
- Pobierz model lokalnie, lub
|
||||
- Zdefiniuj model jawnie w `models.providers.ollama`.
|
||||
|
||||
Aby dodać modele:
|
||||
|
||||
```bash
|
||||
ollama list # Zobacz, co jest zainstalowane
|
||||
ollama pull glm-4.7-flash
|
||||
ollama pull gemma4
|
||||
ollama pull gpt-oss:20b
|
||||
ollama pull llama3.3 # Lub inny model
|
||||
```
|
||||
@ -375,12 +375,12 @@ Sprawdź, czy Ollama działa na właściwym porcie:
|
||||
# Sprawdź, czy Ollama działa
|
||||
ps aux | grep ollama
|
||||
|
||||
# Lub uruchom Ollama ponownie
|
||||
# Lub uruchom ponownie Ollama
|
||||
ollama serve
|
||||
```
|
||||
|
||||
## Zobacz także
|
||||
|
||||
- [Dostawcy modeli](/pl/concepts/model-providers) - przegląd wszystkich dostawców
|
||||
- [Wybór modelu](/pl/concepts/models) - jak wybierać modele
|
||||
- [Konfiguracja](/pl/gateway/configuration) - pełne odniesienie do konfiguracji
|
||||
- [Dostawcy modeli](/pl/concepts/model-providers) - Przegląd wszystkich dostawców
|
||||
- [Wybór modeli](/pl/concepts/models) - Jak wybierać modele
|
||||
- [Konfiguracja](/pl/gateway/configuration) - Pełna dokumentacja konfiguracji
|
||||
|
||||
534
docs/pl/refactor/qa.md
Normal file
534
docs/pl/refactor/qa.md
Normal file
@ -0,0 +1,534 @@
|
||||
---
|
||||
x-i18n:
|
||||
generated_at: "2026-04-08T02:18:06Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 0e156cc8e2fe946a0423862f937754a7caa1fe7e6863b50a80bff49a1c86e1e8
|
||||
source_path: refactor/qa.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Refaktoryzacja QA
|
||||
|
||||
Status: wdrożono podstawową migrację.
|
||||
|
||||
## Cel
|
||||
|
||||
Przenieść QA OpenClaw z modelu rozdzielonych definicji do jednego źródła prawdy:
|
||||
|
||||
- metadane scenariusza
|
||||
- prompty wysyłane do modelu
|
||||
- konfiguracja i czyszczenie
|
||||
- logika harnessu
|
||||
- asercje i kryteria sukcesu
|
||||
- artefakty i wskazówki do raportów
|
||||
|
||||
Pożądanym stanem końcowym jest generyczny harness QA, który wczytuje rozbudowane pliki definicji scenariuszy zamiast kodować większość zachowania na sztywno w TypeScript.
|
||||
|
||||
## Stan obecny
|
||||
|
||||
Główne źródło prawdy znajduje się teraz w `qa/scenarios.md`.
|
||||
|
||||
Zaimplementowano:
|
||||
|
||||
- `qa/scenarios.md`
|
||||
- kanoniczny pakiet QA
|
||||
- tożsamość operatora
|
||||
- misja startowa
|
||||
- metadane scenariuszy
|
||||
- powiązania handlerów
|
||||
- `extensions/qa-lab/src/scenario-catalog.ts`
|
||||
- parser pakietu Markdown + walidacja zod
|
||||
- `extensions/qa-lab/src/qa-agent-bootstrap.ts`
|
||||
- renderowanie planu z pakietu Markdown
|
||||
- `extensions/qa-lab/src/qa-agent-workspace.ts`
|
||||
- inicjuje wygenerowane pliki zgodności oraz `QA_SCENARIOS.md`
|
||||
- `extensions/qa-lab/src/suite.ts`
|
||||
- wybiera wykonywalne scenariusze przez powiązania handlerów zdefiniowane w Markdown
|
||||
- Protokół magistrali QA + UI
|
||||
- generyczne załączniki inline do renderowania obrazów/wideo/audio/plików
|
||||
|
||||
Pozostałe rozdzielone powierzchnie:
|
||||
|
||||
- `extensions/qa-lab/src/suite.ts`
|
||||
- nadal zawiera większość wykonywalnej niestandardowej logiki handlerów
|
||||
- `extensions/qa-lab/src/report.ts`
|
||||
- nadal wyprowadza strukturę raportu z wyników runtime
|
||||
|
||||
Czyli rozdział źródła prawdy został naprawiony, ale wykonanie nadal jest w większości oparte na handlerach, a nie w pełni deklaratywne.
|
||||
|
||||
## Jak naprawdę wygląda powierzchnia scenariuszy
|
||||
|
||||
Odczyt obecnego zestawu pokazuje kilka odrębnych klas scenariuszy.
|
||||
|
||||
### Prosta interakcja
|
||||
|
||||
- bazowy kanał
|
||||
- bazowe DM
|
||||
- follow-up w wątku
|
||||
- przełączanie modelu
|
||||
- kontynuacja po zatwierdzeniu
|
||||
- reakcja/edycja/usunięcie
|
||||
|
||||
### Mutacja konfiguracji i runtime
|
||||
|
||||
- wyłączenie skilla przez poprawkę config
|
||||
- wybudzenie po restarcie po `config apply`
|
||||
- przełączenie możliwości po restarcie config
|
||||
- sprawdzenie dryfu inwentarza runtime
|
||||
|
||||
### Asercje systemu plików i repozytorium
|
||||
|
||||
- raport wykrywania source/docs
|
||||
- zbudowanie Lobster Invaders
|
||||
- wyszukiwanie artefaktu wygenerowanego obrazu
|
||||
|
||||
### Orkiestracja pamięci
|
||||
|
||||
- przywołanie pamięci
|
||||
- narzędzia pamięci w kontekście kanału
|
||||
- fallback po błędzie pamięci
|
||||
- ranking pamięci sesji
|
||||
- izolacja pamięci wątków
|
||||
- przegląd memory dreaming
|
||||
|
||||
### Integracja narzędzi i wtyczek
|
||||
|
||||
- wywołanie MCP plugin-tools
|
||||
- widoczność skilli
|
||||
- hot install skilla
|
||||
- natywne generowanie obrazów
|
||||
- image roundtrip
|
||||
- rozumienie obrazu z załącznika
|
||||
|
||||
### Wieloturowe i wieloosobowe
|
||||
|
||||
- przekazanie do podagenta
|
||||
- synteza fanout podagentów
|
||||
- przepływy w stylu odzyskiwania po restarcie
|
||||
|
||||
Te kategorie są istotne, ponieważ determinują wymagania DSL. Płaska lista promptów + oczekiwanego tekstu nie wystarczy.
|
||||
|
||||
## Kierunek
|
||||
|
||||
### Jedno źródło prawdy
|
||||
|
||||
Używać `qa/scenarios.md` jako redagowanego źródła prawdy.
|
||||
|
||||
Pakiet powinien pozostać:
|
||||
|
||||
- czytelny dla człowieka podczas przeglądu
|
||||
- możliwy do sparsowania maszynowo
|
||||
- wystarczająco bogaty, aby napędzać:
|
||||
- wykonywanie zestawu
|
||||
- bootstrap workspace QA
|
||||
- metadane UI QA Lab
|
||||
- prompty dokumentacji/wykrywania
|
||||
- generowanie raportów
|
||||
|
||||
### Preferowany format redagowania
|
||||
|
||||
Używać Markdown jako formatu najwyższego poziomu, z osadzonym w nim strukturalnym YAML.
|
||||
|
||||
Zalecany kształt:
|
||||
|
||||
- YAML frontmatter
|
||||
- id
|
||||
- title
|
||||
- surface
|
||||
- tags
|
||||
- docs refs
|
||||
- code refs
|
||||
- nadpisania modelu/dostawcy
|
||||
- wymagania wstępne
|
||||
- sekcje prozatorskie
|
||||
- cel
|
||||
- uwagi
|
||||
- wskazówki do debugowania
|
||||
- otoczone blokami YAML
|
||||
- setup
|
||||
- steps
|
||||
- assertions
|
||||
- cleanup
|
||||
|
||||
Daje to:
|
||||
|
||||
- lepszą czytelność PR niż ogromny JSON
|
||||
- bogatszy kontekst niż czysty YAML
|
||||
- ścisłe parsowanie i walidację zod
|
||||
|
||||
Surowy JSON jest akceptowalny tylko jako pośrednia forma wygenerowana.
|
||||
|
||||
## Proponowany kształt pliku scenariusza
|
||||
|
||||
Przykład:
|
||||
|
||||
````md
|
||||
---
|
||||
id: image-generation-roundtrip
|
||||
title: Roundtrip generowania obrazów
|
||||
surface: image
|
||||
tags: [media, image, roundtrip]
|
||||
models:
|
||||
primary: openai/gpt-5.4
|
||||
requires:
|
||||
tools: [image_generate]
|
||||
plugins: [openai, qa-channel]
|
||||
docsRefs:
|
||||
- docs/help/testing.md
|
||||
- docs/concepts/model-providers.md
|
||||
codeRefs:
|
||||
- extensions/qa-lab/src/suite.ts
|
||||
- src/gateway/chat-attachments.ts
|
||||
---
|
||||
|
||||
# Cel
|
||||
|
||||
Zweryfikować, że wygenerowane media są ponownie dołączane w turze follow-up.
|
||||
|
||||
# Konfiguracja
|
||||
|
||||
```yaml scenario.setup
|
||||
- action: config.patch
|
||||
patch:
|
||||
agents:
|
||||
defaults:
|
||||
imageGenerationModel:
|
||||
primary: openai/gpt-image-1
|
||||
- action: session.create
|
||||
key: agent:qa:image-roundtrip
|
||||
```
|
||||
|
||||
# Kroki
|
||||
|
||||
```yaml scenario.steps
|
||||
- action: agent.send
|
||||
session: agent:qa:image-roundtrip
|
||||
message: |
|
||||
Kontrola generowania obrazu: wygeneruj obraz latarni morskiej QA i podsumuj go w jednym krótkim zdaniu.
|
||||
- action: artifact.capture
|
||||
kind: generated-image
|
||||
promptSnippet: Kontrola generowania obrazu
|
||||
saveAs: lighthouseImage
|
||||
- action: agent.send
|
||||
session: agent:qa:image-roundtrip
|
||||
message: |
|
||||
Kontrola inspekcji obrazu po roundtrip: opisz wygenerowany załącznik z latarnią morską w jednym krótkim zdaniu.
|
||||
attachments:
|
||||
- fromArtifact: lighthouseImage
|
||||
```
|
||||
|
||||
# Oczekiwania
|
||||
|
||||
```yaml scenario.expect
|
||||
- assert: outbound.textIncludes
|
||||
value: lighthouse
|
||||
- assert: requestLog.matches
|
||||
where:
|
||||
promptIncludes: Kontrola inspekcji obrazu po roundtrip
|
||||
imageInputCountGte: 1
|
||||
- assert: artifact.exists
|
||||
ref: lighthouseImage
|
||||
```
|
||||
````
|
||||
|
||||
## Możliwości runnera, które DSL musi obejmować
|
||||
|
||||
Na podstawie obecnego zestawu generyczny runner potrzebuje więcej niż wykonywania promptów.
|
||||
|
||||
### Działania środowiskowe i konfiguracyjne
|
||||
|
||||
- `bus.reset`
|
||||
- `gateway.waitHealthy`
|
||||
- `channel.waitReady`
|
||||
- `session.create`
|
||||
- `thread.create`
|
||||
- `workspace.writeSkill`
|
||||
|
||||
### Działania tur agenta
|
||||
|
||||
- `agent.send`
|
||||
- `agent.wait`
|
||||
- `bus.injectInbound`
|
||||
- `bus.injectOutbound`
|
||||
|
||||
### Działania konfiguracji i runtime
|
||||
|
||||
- `config.get`
|
||||
- `config.patch`
|
||||
- `config.apply`
|
||||
- `gateway.restart`
|
||||
- `tools.effective`
|
||||
- `skills.status`
|
||||
|
||||
### Działania na plikach i artefaktach
|
||||
|
||||
- `file.write`
|
||||
- `file.read`
|
||||
- `file.delete`
|
||||
- `file.touchTime`
|
||||
- `artifact.captureGeneratedImage`
|
||||
- `artifact.capturePath`
|
||||
|
||||
### Działania pamięci i cron
|
||||
|
||||
- `memory.indexForce`
|
||||
- `memory.searchCli`
|
||||
- `doctor.memory.status`
|
||||
- `cron.list`
|
||||
- `cron.run`
|
||||
- `cron.waitCompletion`
|
||||
- `sessionTranscript.write`
|
||||
|
||||
### Działania MCP
|
||||
|
||||
- `mcp.callTool`
|
||||
|
||||
### Asercje
|
||||
|
||||
- `outbound.textIncludes`
|
||||
- `outbound.inThread`
|
||||
- `outbound.notInRoot`
|
||||
- `tool.called`
|
||||
- `tool.notPresent`
|
||||
- `skill.visible`
|
||||
- `skill.disabled`
|
||||
- `file.contains`
|
||||
- `memory.contains`
|
||||
- `requestLog.matches`
|
||||
- `sessionStore.matches`
|
||||
- `cron.managedPresent`
|
||||
- `artifact.exists`
|
||||
|
||||
## Zmienne i odwołania do artefaktów
|
||||
|
||||
DSL musi obsługiwać zapisane wyniki i późniejsze odwołania.
|
||||
|
||||
Przykłady z obecnego zestawu:
|
||||
|
||||
- utworzyć wątek, a potem ponownie użyć `threadId`
|
||||
- utworzyć sesję, a potem ponownie użyć `sessionKey`
|
||||
- wygenerować obraz, a potem dołączyć plik w następnej turze
|
||||
- wygenerować ciąg markera wybudzenia, a potem potwierdzić, że pojawia się później
|
||||
|
||||
Potrzebne możliwości:
|
||||
|
||||
- `saveAs`
|
||||
- `${vars.name}`
|
||||
- `${artifacts.name}`
|
||||
- typowane odwołania do ścieżek, kluczy sesji, identyfikatorów wątków, markerów, wyników narzędzi
|
||||
|
||||
Bez obsługi zmiennych harness będzie dalej przeciekał logiką scenariuszy z powrotem do TypeScript.
|
||||
|
||||
## Co powinno pozostać jako furtki awaryjne
|
||||
|
||||
W pełni czysto deklaratywny runner nie jest realistyczny w fazie 1.
|
||||
|
||||
Niektóre scenariusze są z natury silnie oparte na orkiestracji:
|
||||
|
||||
- przegląd memory dreaming
|
||||
- wybudzenie po restarcie po `config apply`
|
||||
- przełączenie możliwości po restarcie config
|
||||
- rozwiązywanie artefaktów wygenerowanych obrazów po znaczniku czasu/ścieżce
|
||||
- ocena raportu wykrywania
|
||||
|
||||
Na razie powinny używać jawnych niestandardowych handlerów.
|
||||
|
||||
Zalecana zasada:
|
||||
|
||||
- 85-90% deklaratywnie
|
||||
- jawne kroki `customHandler` dla trudnej reszty
|
||||
- tylko nazwane i udokumentowane niestandardowe handlery
|
||||
- bez anonimowego kodu inline w pliku scenariusza
|
||||
|
||||
To utrzymuje generyczny silnik w czystości, a jednocześnie pozwala robić postęp.
|
||||
|
||||
## Zmiana architektury
|
||||
|
||||
### Obecnie
|
||||
|
||||
Markdown scenariuszy jest już źródłem prawdy dla:
|
||||
|
||||
- wykonywania zestawu
|
||||
- plików bootstrap workspace
|
||||
- katalogu scenariuszy UI QA Lab
|
||||
- metadanych raportów
|
||||
- promptów wykrywania
|
||||
|
||||
Wygenerowana zgodność:
|
||||
|
||||
- zainicjalizowany workspace nadal zawiera `QA_KICKOFF_TASK.md`
|
||||
- zainicjalizowany workspace nadal zawiera `QA_SCENARIO_PLAN.md`
|
||||
- zainicjalizowany workspace zawiera teraz także `QA_SCENARIOS.md`
|
||||
|
||||
## Plan refaktoryzacji
|
||||
|
||||
### Faza 1: loader i schemat
|
||||
|
||||
Gotowe.
|
||||
|
||||
- dodano `qa/scenarios.md`
|
||||
- dodano parser dla nazwanej zawartości pakietu Markdown YAML
|
||||
- zwalidowano przez zod
|
||||
- przełączono odbiorców na sparsowany pakiet
|
||||
- usunięto pliki repo-level `qa/seed-scenarios.json` i `qa/QA_KICKOFF_TASK.md`
|
||||
|
||||
### Faza 2: generyczny silnik
|
||||
|
||||
- podzielić `extensions/qa-lab/src/suite.ts` na:
|
||||
- loader
|
||||
- silnik
|
||||
- rejestr akcji
|
||||
- rejestr asercji
|
||||
- niestandardowe handlery
|
||||
- zachować istniejące funkcje pomocnicze jako operacje silnika
|
||||
|
||||
Rezultat:
|
||||
|
||||
- silnik wykonuje proste scenariusze deklaratywne
|
||||
|
||||
Zacząć od scenariuszy, które są głównie prompt + wait + assert:
|
||||
|
||||
- follow-up w wątku
|
||||
- rozumienie obrazu z załącznika
|
||||
- widoczność i wywołanie skillów
|
||||
- bazowy kanał
|
||||
|
||||
Rezultat:
|
||||
|
||||
- pierwsze rzeczywiste scenariusze zdefiniowane w Markdown dostarczane przez generyczny silnik
|
||||
|
||||
### Faza 4: migracja scenariuszy średniej trudności
|
||||
|
||||
- roundtrip generowania obrazów
|
||||
- narzędzia pamięci w kontekście kanału
|
||||
- ranking pamięci sesji
|
||||
- przekazanie do podagenta
|
||||
- synteza fanout podagentów
|
||||
|
||||
Rezultat:
|
||||
|
||||
- sprawdzona obsługa zmiennych, artefaktów, asercji narzędzi i asercji request-log
|
||||
|
||||
### Faza 5: pozostawienie trudnych scenariuszy na niestandardowych handlerach
|
||||
|
||||
- przegląd memory dreaming
|
||||
- wybudzenie po restarcie po `config apply`
|
||||
- przełączenie możliwości po restarcie config
|
||||
- dryf inwentarza runtime
|
||||
|
||||
Rezultat:
|
||||
|
||||
- ten sam format redagowania, ale z jawnymi blokami niestandardowych kroków tam, gdzie są potrzebne
|
||||
|
||||
### Faza 6: usunięcie mapy scenariuszy zakodowanej na sztywno
|
||||
|
||||
Gdy pokrycie pakietu będzie wystarczająco dobre:
|
||||
|
||||
- usunąć większość rozgałęzień TypeScript specyficznych dla scenariuszy z `extensions/qa-lab/src/suite.ts`
|
||||
|
||||
## Fałszywy Slack / obsługa rozbudowanych mediów
|
||||
|
||||
Obecna magistrala QA jest zorientowana głównie na tekst.
|
||||
|
||||
Powiązane pliki:
|
||||
|
||||
- `extensions/qa-channel/src/protocol.ts`
|
||||
- `extensions/qa-lab/src/bus-state.ts`
|
||||
- `extensions/qa-lab/src/bus-queries.ts`
|
||||
- `extensions/qa-lab/src/bus-server.ts`
|
||||
- `extensions/qa-lab/web/src/ui-render.ts`
|
||||
|
||||
Dzisiaj magistrala QA obsługuje:
|
||||
|
||||
- tekst
|
||||
- reakcje
|
||||
- wątki
|
||||
|
||||
Nie modeluje jeszcze załączników multimedialnych inline.
|
||||
|
||||
### Potrzebny kontrakt transportowy
|
||||
|
||||
Dodać generyczny model załączników magistrali QA:
|
||||
|
||||
```ts
|
||||
type QaBusAttachment = {
|
||||
id: string;
|
||||
kind: "image" | "video" | "audio" | "file";
|
||||
mimeType: string;
|
||||
fileName?: string;
|
||||
inline?: boolean;
|
||||
url?: string;
|
||||
contentBase64?: string;
|
||||
width?: number;
|
||||
height?: number;
|
||||
durationMs?: number;
|
||||
altText?: string;
|
||||
transcript?: string;
|
||||
};
|
||||
```
|
||||
|
||||
Następnie dodać `attachments?: QaBusAttachment[]` do:
|
||||
|
||||
- `QaBusMessage`
|
||||
- `QaBusInboundMessageInput`
|
||||
- `QaBusOutboundMessageInput`
|
||||
|
||||
### Dlaczego najpierw generycznie
|
||||
|
||||
Nie budować modelu mediów tylko dla Slacka.
|
||||
|
||||
Zamiast tego:
|
||||
|
||||
- jeden generyczny model transportu QA
|
||||
- wiele rendererów nad nim
|
||||
- obecny czat QA Lab
|
||||
- przyszły fałszywy Slack web
|
||||
- dowolne inne widoki fałszywego transportu
|
||||
|
||||
To zapobiega duplikacji logiki i pozwala scenariuszom medialnym pozostać niezależnymi od transportu.
|
||||
|
||||
### Potrzebne prace w UI
|
||||
|
||||
Zaktualizować UI QA tak, aby renderowało:
|
||||
|
||||
- podgląd obrazu inline
|
||||
- odtwarzacz audio inline
|
||||
- odtwarzacz wideo inline
|
||||
- chip załącznika pliku
|
||||
|
||||
Obecne UI potrafi już renderować wątki i reakcje, więc renderowanie załączników powinno zostać dołożone do tego samego modelu kart wiadomości.
|
||||
|
||||
### Prace scenariuszowe umożliwione przez transport mediów
|
||||
|
||||
Gdy załączniki zaczną przepływać przez magistralę QA, będzie można dodać bogatsze scenariusze fałszywego czatu:
|
||||
|
||||
- odpowiedź z obrazem inline w fałszywym Slacku
|
||||
- rozumienie załącznika audio
|
||||
- rozumienie załącznika wideo
|
||||
- mieszana kolejność załączników
|
||||
- odpowiedź w wątku z zachowaniem mediów
|
||||
|
||||
## Rekomendacja
|
||||
|
||||
Kolejny etap implementacji powinien wyglądać tak:
|
||||
|
||||
1. dodać loader scenariuszy Markdown + schemat zod
|
||||
2. wygenerować obecny katalog z Markdown
|
||||
3. najpierw zmigrować kilka prostych scenariuszy
|
||||
4. dodać generyczne wsparcie załączników magistrali QA
|
||||
5. renderować obraz inline w UI QA
|
||||
6. następnie rozszerzyć na audio i wideo
|
||||
|
||||
To najmniejsza ścieżka, która potwierdza oba cele:
|
||||
|
||||
- generyczne QA definiowane w Markdown
|
||||
- bogatsze fałszywe powierzchnie wiadomości
|
||||
|
||||
## Otwarte pytania
|
||||
|
||||
- czy pliki scenariuszy powinny pozwalać na osadzone szablony promptów Markdown z interpolacją zmiennych
|
||||
- czy setup/cleanup powinny być nazwanymi sekcjami, czy po prostu uporządkowanymi listami akcji
|
||||
- czy odwołania do artefaktów powinny być silnie typowane w schemacie, czy oparte na stringach
|
||||
- czy niestandardowe handlery powinny żyć w jednym rejestrze, czy w rejestrach per-surface
|
||||
- czy wygenerowany plik zgodności JSON powinien pozostać zacommitowany podczas migracji
|
||||
@ -1,32 +1,32 @@
|
||||
---
|
||||
read_when:
|
||||
- Musisz debugować identyfikatory sesji, JSONL transkryptów lub pola sessions.json
|
||||
- Zmieniasz zachowanie auto-compaction lub dodajesz housekeeping „pre-compaction”
|
||||
- Chcesz zaimplementować flush pamięci lub ciche tury systemowe
|
||||
summary: 'Szczegółowe omówienie: store sesji + transkrypty, cykl życia i mechanizmy (auto)compaction'
|
||||
- Musisz debugować identyfikatory sesji, JSONL transkryptu lub pola sessions.json
|
||||
- Zmieniasz zachowanie auto-kompaktowania lub dodajesz porządki „przed kompaktowaniem”
|
||||
- Chcesz zaimplementować opróżnianie pamięci lub ciche tury systemowe
|
||||
summary: 'Szczegółowe omówienie: store sesji i transkrypty, cykl życia oraz mechanizmy (auto)kompaktowania'
|
||||
title: Szczegółowe omówienie zarządzania sesjami
|
||||
x-i18n:
|
||||
generated_at: "2026-04-07T09:50:11Z"
|
||||
generated_at: "2026-04-08T02:18:26Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: e379d624dd7808d3af25ed011079268ce6a9da64bb3f301598884ad4c46ab091
|
||||
source_hash: cb1a4048646486693db8943a9e9c6c5bcb205f0ed532b34842de3d0346077454
|
||||
source_path: reference/session-management-compaction.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Zarządzanie sesjami i compaction (szczegółowe omówienie)
|
||||
# Zarządzanie sesjami i kompaktowanie (szczegółowe omówienie)
|
||||
|
||||
Ten dokument wyjaśnia, jak OpenClaw zarządza sesjami end-to-end:
|
||||
Ten dokument wyjaśnia, jak OpenClaw zarządza sesjami od początku do końca:
|
||||
|
||||
- **Session routing** (jak wiadomości przychodzące mapują się na `sessionKey`)
|
||||
- **Routowanie sesji** (jak wiadomości przychodzące mapują się na `sessionKey`)
|
||||
- **Store sesji** (`sessions.json`) i co śledzi
|
||||
- **Trwałość transkryptów** (`*.jsonl`) i ich struktura
|
||||
- **Higiena transkryptów** (poprawki specyficzne dla providera przed uruchomieniami)
|
||||
- **Trwałość transkryptu** (`*.jsonl`) i jego struktura
|
||||
- **Higiena transkryptu** (poprawki specyficzne dla dostawcy przed uruchomieniami)
|
||||
- **Limity kontekstu** (okno kontekstu vs śledzone tokeny)
|
||||
- **Compaction** (ręczny + auto-compaction) oraz gdzie podłączać pracę pre-compaction
|
||||
- **Cichy housekeeping** (np. zapisy pamięci, które nie powinny generować widocznego dla użytkownika wyjścia)
|
||||
- **Kompaktowanie** (ręczne + automatyczne kompaktowanie) i gdzie podpiąć pracę wykonywaną przed kompaktowaniem
|
||||
- **Ciche porządki** (np. zapisy do pamięci, które nie powinny generować widocznego dla użytkownika wyjścia)
|
||||
|
||||
Jeśli najpierw chcesz przeczytać omówienie na wyższym poziomie, zacznij od:
|
||||
Jeśli najpierw chcesz zobaczyć omówienie na wyższym poziomie, zacznij od:
|
||||
|
||||
- [/concepts/session](/pl/concepts/session)
|
||||
- [/concepts/compaction](/pl/concepts/compaction)
|
||||
@ -39,10 +39,10 @@ Jeśli najpierw chcesz przeczytać omówienie na wyższym poziomie, zacznij od:
|
||||
|
||||
## Źródło prawdy: Gateway
|
||||
|
||||
OpenClaw jest zaprojektowany wokół pojedynczego **procesu Gateway**, który zarządza stanem sesji.
|
||||
OpenClaw został zaprojektowany wokół pojedynczego **procesu Gateway**, który zarządza stanem sesji.
|
||||
|
||||
- Interfejsy UI (aplikacja macOS, webowy Control UI, TUI) powinny odpytywać Gateway o listy sesji i liczbę tokenów.
|
||||
- W trybie zdalnym pliki sesji znajdują się na zdalnym hoście; „sprawdzanie lokalnych plików na Macu” nie będzie odzwierciedlać tego, czego używa Gateway.
|
||||
- Interfejsy użytkownika (aplikacja macOS, webowy Control UI, TUI) powinny odpytywać Gateway o listy sesji i liczniki tokenów.
|
||||
- W trybie zdalnym pliki sesji znajdują się na zdalnym hoście; „sprawdzanie lokalnych plików na Macu” nie odzwierciedli tego, czego używa Gateway.
|
||||
|
||||
---
|
||||
|
||||
@ -56,21 +56,21 @@ OpenClaw zapisuje sesje w dwóch warstwach:
|
||||
- Śledzi metadane sesji (bieżący identyfikator sesji, ostatnią aktywność, przełączniki, liczniki tokenów itd.)
|
||||
|
||||
2. **Transkrypt (`<sessionId>.jsonl`)**
|
||||
- Transkrypt append-only o strukturze drzewa (wpisy mają `id` + `parentId`)
|
||||
- Przechowuje właściwą rozmowę + wywołania narzędzi + podsumowania compaction
|
||||
- Transkrypt typu append-only o strukturze drzewa (wpisy mają `id` + `parentId`)
|
||||
- Przechowuje właściwą konwersację + wywołania narzędzi + podsumowania kompaktowania
|
||||
- Służy do odbudowy kontekstu modelu dla przyszłych tur
|
||||
|
||||
---
|
||||
|
||||
## Lokalizacje na dysku
|
||||
|
||||
Per agent, na hoście Gateway:
|
||||
Dla każdego agenta, na hoście Gateway:
|
||||
|
||||
- Store: `~/.openclaw/agents/<agentId>/sessions/sessions.json`
|
||||
- Transkrypty: `~/.openclaw/agents/<agentId>/sessions/<sessionId>.jsonl`
|
||||
- Sesje tematów Telegram: `.../<sessionId>-topic-<threadId>.jsonl`
|
||||
|
||||
OpenClaw rozwiązuje je przez `src/config/sessions.ts`.
|
||||
OpenClaw rozwiązuje te ścieżki przez `src/config/sessions.ts`.
|
||||
|
||||
---
|
||||
|
||||
@ -79,18 +79,18 @@ OpenClaw rozwiązuje je przez `src/config/sessions.ts`.
|
||||
Trwałość sesji ma automatyczne mechanizmy utrzymania (`session.maintenance`) dla `sessions.json` i artefaktów transkryptów:
|
||||
|
||||
- `mode`: `warn` (domyślnie) lub `enforce`
|
||||
- `pruneAfter`: próg wieku nieaktualnych wpisów (domyślnie `30d`)
|
||||
- `pruneAfter`: próg wieku dla starych wpisów (domyślnie `30d`)
|
||||
- `maxEntries`: limit wpisów w `sessions.json` (domyślnie `500`)
|
||||
- `rotateBytes`: obraca `sessions.json`, gdy staje się zbyt duży (domyślnie `10mb`)
|
||||
- `rotateBytes`: rotacja `sessions.json`, gdy plik jest zbyt duży (domyślnie `10mb`)
|
||||
- `resetArchiveRetention`: retencja dla archiwów transkryptów `*.reset.<timestamp>` (domyślnie: taka sama jak `pruneAfter`; `false` wyłącza czyszczenie)
|
||||
- `maxDiskBytes`: opcjonalny budżet katalogu sesji
|
||||
- `highWaterBytes`: opcjonalny cel po cleanupie (domyślnie `80%` z `maxDiskBytes`)
|
||||
- `maxDiskBytes`: opcjonalny limit budżetu katalogu sesji
|
||||
- `highWaterBytes`: opcjonalny cel po czyszczeniu (domyślnie `80%` z `maxDiskBytes`)
|
||||
|
||||
Kolejność egzekwowania cleanupu przy budżecie dyskowym (`mode: "enforce"`):
|
||||
Kolejność egzekwowania przy czyszczeniu limitu dysku (`mode: "enforce"`):
|
||||
|
||||
1. Najpierw usuń najstarsze zarchiwizowane lub osierocone artefakty transkryptów.
|
||||
2. Jeśli nadal przekroczony jest cel, usuń najstarsze wpisy sesji i ich pliki transkryptów.
|
||||
3. Kontynuuj, aż użycie będzie na poziomie `highWaterBytes` lub poniżej.
|
||||
2. Jeśli nadal jest powyżej celu, usuń najstarsze wpisy sesji i ich pliki transkryptów.
|
||||
3. Kontynuuj, aż użycie spadnie do `highWaterBytes` lub niżej.
|
||||
|
||||
W trybie `mode: "warn"` OpenClaw zgłasza potencjalne usunięcia, ale nie modyfikuje store ani plików.
|
||||
|
||||
@ -114,30 +114,30 @@ Izolowane uruchomienia cron również tworzą wpisy sesji/transkrypty i mają de
|
||||
|
||||
## Klucze sesji (`sessionKey`)
|
||||
|
||||
`sessionKey` identyfikuje, _w którym koszyku rozmowy_ się znajdujesz (routing + izolacja).
|
||||
`sessionKey` identyfikuje _który koszyk konwersacji_ jest używany (routowanie + izolacja).
|
||||
|
||||
Typowe wzorce:
|
||||
|
||||
- Główny/czat bezpośredni (per agent): `agent:<agentId>:<mainKey>` (domyślnie `main`)
|
||||
- Główny/bezpośredni czat (per agent): `agent:<agentId>:<mainKey>` (domyślnie `main`)
|
||||
- Grupa: `agent:<agentId>:<channel>:group:<id>`
|
||||
- Pokój/kanał (Discord/Slack): `agent:<agentId>:<channel>:channel:<id>` lub `...:room:<id>`
|
||||
- Cron: `cron:<job.id>`
|
||||
- Webhook: `hook:<uuid>` (chyba że nadpisano)
|
||||
|
||||
Kanoniczne zasady są opisane w [/concepts/session](/pl/concepts/session).
|
||||
Kanoniczne zasady są udokumentowane w [/concepts/session](/pl/concepts/session).
|
||||
|
||||
---
|
||||
|
||||
## Identyfikatory sesji (`sessionId`)
|
||||
|
||||
Każdy `sessionKey` wskazuje na bieżący `sessionId` (plik transkryptu, który kontynuuje rozmowę).
|
||||
Każdy `sessionKey` wskazuje na bieżący `sessionId` (plik transkryptu, który kontynuuje konwersację).
|
||||
|
||||
Praktyczne zasady:
|
||||
|
||||
- **Reset** (`/new`, `/reset`) tworzy nowy `sessionId` dla tego `sessionKey`.
|
||||
- **Codzienny reset** (domyślnie 4:00 czasu lokalnego hosta gateway) tworzy nowy `sessionId` przy następnej wiadomości po przekroczeniu granicy resetu.
|
||||
- **Wygaśnięcie bezczynności** (`session.reset.idleMinutes` lub starsze `session.idleMinutes`) tworzy nowy `sessionId`, gdy wiadomość nadejdzie po upływie okna bezczynności. Gdy skonfigurowane są jednocześnie reset dzienny i bezczynność, wygrywa ten, który wygaśnie wcześniej.
|
||||
- **Zabezpieczenie forkowania po rodzicu wątku** (`session.parentForkMaxTokens`, domyślnie `100000`) pomija forkowanie transkryptu rodzica, gdy sesja nadrzędna jest już zbyt duża; nowy wątek zaczyna się od zera. Ustaw `0`, aby wyłączyć.
|
||||
- **Codzienny reset** (domyślnie o 4:00 czasu lokalnego na hoście gatewaya) tworzy nowy `sessionId` przy następnej wiadomości po przekroczeniu granicy resetu.
|
||||
- **Wygaśnięcie bezczynności** (`session.reset.idleMinutes` lub starsze `session.idleMinutes`) tworzy nowy `sessionId`, gdy wiadomość nadejdzie po oknie bezczynności. Gdy skonfigurowano jednocześnie reset dzienny i bezczynność, wygrywa ten, który wygaśnie wcześniej.
|
||||
- **Zabezpieczenie przed rozwidleniem z rodzica dla wątków** (`session.parentForkMaxTokens`, domyślnie `100000`) pomija forking transkryptu rodzica, gdy sesja nadrzędna jest już zbyt duża; nowy wątek zaczyna się od zera. Ustaw `0`, aby wyłączyć.
|
||||
|
||||
Szczegół implementacyjny: decyzja zapada w `initSessionState()` w `src/auto-reply/reply/session.ts`.
|
||||
|
||||
@ -149,44 +149,44 @@ Typ wartości store to `SessionEntry` w `src/config/sessions.ts`.
|
||||
|
||||
Kluczowe pola (lista niepełna):
|
||||
|
||||
- `sessionId`: bieżący identyfikator transkryptu (nazwa pliku jest od niego wyprowadzana, chyba że ustawiono `sessionFile`)
|
||||
- `sessionId`: bieżący identyfikator transkryptu (nazwa pliku jest z niego wyprowadzana, chyba że ustawiono `sessionFile`)
|
||||
- `updatedAt`: znacznik czasu ostatniej aktywności
|
||||
- `sessionFile`: opcjonalne jawne nadpisanie ścieżki transkryptu
|
||||
- `chatType`: `direct | group | room` (pomaga UI i polityce wysyłania)
|
||||
- `chatType`: `direct | group | room` (pomaga interfejsom użytkownika i polityce wysyłania)
|
||||
- `provider`, `subject`, `room`, `space`, `displayName`: metadane do etykietowania grup/kanałów
|
||||
- Przełączniki:
|
||||
- `thinkingLevel`, `verboseLevel`, `reasoningLevel`, `elevatedLevel`
|
||||
- `sendPolicy` (nadpisanie per sesja)
|
||||
- Wybór modelu:
|
||||
- `providerOverride`, `modelOverride`, `authProfileOverride`
|
||||
- Liczniki tokenów (best-effort / zależne od providera):
|
||||
- Liczniki tokenów (best-effort / zależne od dostawcy):
|
||||
- `inputTokens`, `outputTokens`, `totalTokens`, `contextTokens`
|
||||
- `compactionCount`: jak często auto-compaction zakończył się dla tego klucza sesji
|
||||
- `memoryFlushAt`: znacznik czasu ostatniego flush pamięci pre-compaction
|
||||
- `memoryFlushCompactionCount`: licznik compaction, przy którym wykonano ostatni flush
|
||||
- `compactionCount`: jak często auto-kompaktowanie zakończyło się dla tego klucza sesji
|
||||
- `memoryFlushAt`: znacznik czasu ostatniego opróżnienia pamięci przed kompaktowaniem
|
||||
- `memoryFlushCompactionCount`: licznik kompaktowań, przy którym uruchomiono ostatnie opróżnienie
|
||||
|
||||
Store można bezpiecznie edytować, ale autorytetem pozostaje Gateway: może przepisywać lub ponownie hydradować wpisy podczas działania sesji.
|
||||
Store można bezpiecznie edytować, ale Gateway jest autorytetem: może przepisywać lub odtwarzać wpisy podczas działania sesji.
|
||||
|
||||
---
|
||||
|
||||
## Struktura transkryptu (`*.jsonl`)
|
||||
|
||||
Transkryptami zarządza `SessionManager` z `@mariozechner/pi-coding-agent`.
|
||||
Transkrypty są zarządzane przez `SessionManager` z `@mariozechner/pi-coding-agent`.
|
||||
|
||||
Plik ma format JSONL:
|
||||
|
||||
- Pierwsza linia: nagłówek sesji (`type: "session"`, zawiera `id`, `cwd`, `timestamp`, opcjonalnie `parentSession`)
|
||||
- Dalej: wpisy sesji z `id` + `parentId` (drzewo)
|
||||
- Następnie: wpisy sesji z `id` + `parentId` (drzewo)
|
||||
|
||||
Ważne typy wpisów:
|
||||
Istotne typy wpisów:
|
||||
|
||||
- `message`: wiadomości user/assistant/toolResult
|
||||
- `custom_message`: wiadomości wstrzyknięte przez rozszerzenie, które _wchodzą_ do kontekstu modelu (mogą być ukryte przed UI)
|
||||
- `message`: wiadomości użytkownika/asystenta/toolResult
|
||||
- `custom_message`: wiadomości wstrzykiwane przez rozszerzenie, które _wchodzą_ do kontekstu modelu (mogą być ukryte w UI)
|
||||
- `custom`: stan rozszerzenia, który _nie wchodzi_ do kontekstu modelu
|
||||
- `compaction`: utrwalone podsumowanie compaction z `firstKeptEntryId` i `tokensBefore`
|
||||
- `branch_summary`: utrwalone podsumowanie przy nawigacji po gałęzi drzewa
|
||||
- `compaction`: zapisane podsumowanie kompaktowania z `firstKeptEntryId` i `tokensBefore`
|
||||
- `branch_summary`: zapisane podsumowanie przy nawigacji po gałęzi drzewa
|
||||
|
||||
OpenClaw celowo **nie** „naprawia” transkryptów; Gateway używa `SessionManager` do ich odczytu/zapisu.
|
||||
OpenClaw celowo **nie** „naprawia” transkryptów; Gateway używa `SessionManager` do ich odczytu i zapisu.
|
||||
|
||||
---
|
||||
|
||||
@ -199,49 +199,49 @@ Znaczenie mają dwa różne pojęcia:
|
||||
|
||||
Jeśli dostrajasz limity:
|
||||
|
||||
- Okno kontekstu pochodzi z katalogu modeli (i może być nadpisane przez config).
|
||||
- `contextTokens` w store to wartość szacunkowa/raportowa z runtime; nie traktuj jej jako ścisłej gwarancji.
|
||||
- Okno kontekstu pochodzi z katalogu modeli (i może być nadpisane przez konfigurację).
|
||||
- `contextTokens` w store to wartość szacunkowa/raportowana przez runtime; nie traktuj jej jako ścisłej gwarancji.
|
||||
|
||||
Więcej informacji znajdziesz w [/token-use](/pl/reference/token-use).
|
||||
|
||||
---
|
||||
|
||||
## Compaction: czym jest
|
||||
## Kompaktowanie: czym jest
|
||||
|
||||
Compaction podsumowuje starszą część rozmowy do utrwalonego wpisu `compaction` w transkrypcie i pozostawia nienaruszone ostatnie wiadomości.
|
||||
Kompaktowanie podsumowuje starszą część konwersacji do zapisanego wpisu `compaction` w transkrypcie i zachowuje nienaruszone ostatnie wiadomości.
|
||||
|
||||
Po compaction przyszłe tury widzą:
|
||||
Po kompaktowaniu przyszłe tury widzą:
|
||||
|
||||
- Podsumowanie compaction
|
||||
- Podsumowanie kompaktowania
|
||||
- Wiadomości po `firstKeptEntryId`
|
||||
|
||||
Compaction jest **trwały** (w przeciwieństwie do session pruning). Zobacz [/concepts/session-pruning](/pl/concepts/session-pruning).
|
||||
Kompaktowanie jest **trwałe** (w przeciwieństwie do przycinania sesji). Zobacz [/concepts/session-pruning](/pl/concepts/session-pruning).
|
||||
|
||||
## Granice chunków compaction i parowanie narzędzi
|
||||
## Granice chunków kompaktowania i parowanie narzędzi
|
||||
|
||||
Gdy OpenClaw dzieli długi transkrypt na chunki do compaction, utrzymuje
|
||||
powiązanie wywołań narzędzi asystenta z odpowiadającymi im wpisami `toolResult`.
|
||||
Gdy OpenClaw dzieli długi transkrypt na chunki do kompaktowania, utrzymuje
|
||||
sparowanie wywołań narzędzi asystenta z odpowiadającymi im wpisami `toolResult`.
|
||||
|
||||
- Jeśli podział według udziału tokenów wypada między wywołaniem narzędzia a jego wynikiem, OpenClaw
|
||||
przesuwa granicę do wiadomości asystenta zawierającej wywołanie narzędzia zamiast rozdzielać
|
||||
tę parę.
|
||||
- Jeśli końcowy blok wyniku narzędzia w przeciwnym razie przesunąłby chunk ponad docelowy rozmiar,
|
||||
przesuwa granicę do wiadomości asystenta z wywołaniem narzędzia zamiast rozdzielać
|
||||
parę.
|
||||
- Jeśli końcowy blok z wynikiem narzędzia w przeciwnym razie przekroczyłby docelowy rozmiar chunku,
|
||||
OpenClaw zachowuje ten oczekujący blok narzędzia i pozostawia niepodsumowany ogon
|
||||
bez zmian.
|
||||
- Przerwane/błędne bloki wywołań narzędzi nie utrzymują otwartego oczekującego podziału.
|
||||
- Przerwane/błędne bloki wywołań narzędzi nie utrzymują oczekującego podziału otwartego.
|
||||
|
||||
---
|
||||
|
||||
## Kiedy zachodzi auto-compaction (runtime Pi)
|
||||
## Kiedy następuje auto-kompaktowanie (runtime Pi)
|
||||
|
||||
W osadzonym agencie Pi auto-compaction uruchamia się w dwóch przypadkach:
|
||||
W osadzonym agencie Pi auto-kompaktowanie uruchamia się w dwóch przypadkach:
|
||||
|
||||
1. **Odzyskiwanie po overflow**: model zwraca błąd przepełnienia kontekstu
|
||||
1. **Odzyskiwanie po przepełnieniu**: model zwraca błąd przepełnienia kontekstu
|
||||
(`request_too_large`, `context length exceeded`, `input exceeds the maximum
|
||||
number of tokens`, `input token count exceeds the maximum number of input
|
||||
tokens`, `input is too long for the model`, `ollama error: context length
|
||||
exceeded` oraz podobne warianty zależne od providera) → compact → ponów próbę.
|
||||
2. **Utrzymanie progu**: po pomyślnej turze, gdy:
|
||||
exceeded` oraz podobne warianty zależne od dostawcy) → kompaktuj → ponów próbę.
|
||||
2. **Utrzymanie progu**: po udanej turze, gdy:
|
||||
|
||||
`contextTokens > contextWindow - reserveTokens`
|
||||
|
||||
@ -250,13 +250,13 @@ Gdzie:
|
||||
- `contextWindow` to okno kontekstu modelu
|
||||
- `reserveTokens` to zapas zarezerwowany na prompty + następne wyjście modelu
|
||||
|
||||
To semantyka runtime Pi (OpenClaw konsumuje zdarzenia, ale Pi decyduje, kiedy robić compact).
|
||||
To semantyka runtime Pi (OpenClaw konsumuje zdarzenia, ale Pi decyduje, kiedy kompaktować).
|
||||
|
||||
---
|
||||
|
||||
## Ustawienia compaction (`reserveTokens`, `keepRecentTokens`)
|
||||
## Ustawienia kompaktowania (`reserveTokens`, `keepRecentTokens`)
|
||||
|
||||
Ustawienia compaction Pi znajdują się w ustawieniach Pi:
|
||||
Ustawienia kompaktowania Pi znajdują się w ustawieniach Pi:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -268,92 +268,107 @@ Ustawienia compaction Pi znajdują się w ustawieniach Pi:
|
||||
}
|
||||
```
|
||||
|
||||
OpenClaw wymusza też minimalny próg bezpieczeństwa dla osadzonych uruchomień:
|
||||
OpenClaw wymusza też minimalny bezpieczny próg dla uruchomień osadzonych:
|
||||
|
||||
- Jeśli `compaction.reserveTokens < reserveTokensFloor`, OpenClaw go podnosi.
|
||||
- Domyślny próg to `20000` tokenów.
|
||||
- Domyślny próg minimalny to `20000` tokenów.
|
||||
- Ustaw `agents.defaults.compaction.reserveTokensFloor: 0`, aby wyłączyć ten próg.
|
||||
- Jeśli wartość jest już wyższa, OpenClaw pozostawia ją bez zmian.
|
||||
|
||||
Dlaczego: pozostawia to wystarczający zapas na wieloturowy „housekeeping” (np. zapisy pamięci), zanim compaction stanie się nieunikniony.
|
||||
Dlaczego: aby zostawić wystarczający zapas na wieloturowe „porządki” (takie jak zapisy do pamięci), zanim kompaktowanie stanie się nieuniknione.
|
||||
|
||||
Implementacja: `ensurePiCompactionReserveTokens()` w `src/agents/pi-settings.ts`
|
||||
(wywoływane z `src/agents/pi-embedded-runner.ts`).
|
||||
|
||||
---
|
||||
|
||||
## Wymienni dostawcy kompaktowania
|
||||
|
||||
Wtyczki mogą rejestrować dostawcę kompaktowania przez `registerCompactionProvider()` w API wtyczek. Gdy `agents.defaults.compaction.provider` jest ustawione na identyfikator zarejestrowanego dostawcy, rozszerzenie safeguard deleguje podsumowywanie do tego dostawcy zamiast do wbudowanego potoku `summarizeInStages`.
|
||||
|
||||
- `provider`: identyfikator zarejestrowanej wtyczki dostawcy kompaktowania. Pozostaw nieustawione dla domyślnego podsumowywania przez LLM.
|
||||
- Ustawienie `provider` wymusza `mode: "safeguard"`.
|
||||
- Dostawcy otrzymują te same instrukcje kompaktowania i politykę zachowywania identyfikatorów co ścieżka wbudowana.
|
||||
- Safeguard nadal zachowuje kontekst ostatnich tur i końcówki podzielonej tury po wyjściu dostawcy.
|
||||
- Jeśli dostawca zawiedzie lub zwróci pusty wynik, OpenClaw automatycznie wraca do wbudowanego podsumowywania przez LLM.
|
||||
- Sygnały przerwania/timeoutu są ponownie rzucane (nie są przechwytywane), aby respektować anulowanie przez wywołującego.
|
||||
|
||||
Źródło: `src/plugins/compaction-provider.ts`, `src/agents/pi-hooks/compaction-safeguard.ts`.
|
||||
|
||||
---
|
||||
|
||||
## Powierzchnie widoczne dla użytkownika
|
||||
|
||||
Możesz obserwować compaction i stan sesji przez:
|
||||
Kompaktowanie i stan sesji można obserwować przez:
|
||||
|
||||
- `/status` (w dowolnej sesji czatu)
|
||||
- `openclaw status` (CLI)
|
||||
- `openclaw sessions` / `sessions --json`
|
||||
- Tryb verbose: `🧹 Auto-compaction complete` + liczba compaction
|
||||
- Tryb szczegółowy: `🧹 Auto-compaction complete` + liczba kompaktowań
|
||||
|
||||
---
|
||||
|
||||
## Cichy housekeeping (`NO_REPLY`)
|
||||
## Ciche porządki (`NO_REPLY`)
|
||||
|
||||
OpenClaw obsługuje „ciche” tury dla zadań w tle, w których użytkownik nie powinien widzieć pośredniego wyjścia.
|
||||
OpenClaw obsługuje „ciche” tury dla zadań działających w tle, gdy użytkownik nie powinien widzieć pośredniego wyjścia.
|
||||
|
||||
Konwencja:
|
||||
|
||||
- Asystent rozpoczyna wyjście dokładnym cichym tokenem `NO_REPLY` /
|
||||
- Asystent rozpoczyna wyjście od dokładnego cichego tokena `NO_REPLY` /
|
||||
`no_reply`, aby wskazać „nie dostarczaj odpowiedzi użytkownikowi”.
|
||||
- OpenClaw usuwa/wycisza to w warstwie dostarczania.
|
||||
- Wyciszanie dokładnego cichego tokenu jest niewrażliwe na wielkość liter, więc `NO_REPLY` i
|
||||
`no_reply` są traktowane tak samo, gdy cały payload składa się tylko z cichego tokenu.
|
||||
- To rozwiązanie jest przeznaczone tylko dla prawdziwych tur w tle/bez dostarczania; nie jest skrótem dla
|
||||
zwykłych żądań użytkownika wymagających działania.
|
||||
- OpenClaw usuwa/tłumi to w warstwie dostarczania.
|
||||
- Tłumienie dokładnego cichego tokena nie rozróżnia wielkości liter, więc `NO_REPLY` i
|
||||
`no_reply` liczą się tak samo, gdy cały ładunek to tylko ten cichy token.
|
||||
- Służy to wyłącznie do prawdziwych tur działających w tle / bez dostarczenia; nie jest to skrót
|
||||
dla zwykłych, wymagających działania żądań użytkownika.
|
||||
|
||||
Od wersji `2026.1.10` OpenClaw wycisza też **draft/typing streaming**, gdy
|
||||
Od wersji `2026.1.10` OpenClaw tłumi także **streaming wersji roboczych/pisania**, gdy
|
||||
częściowy chunk zaczyna się od `NO_REPLY`, aby ciche operacje nie ujawniały częściowego
|
||||
wyjścia w trakcie tury.
|
||||
wyjścia w połowie tury.
|
||||
|
||||
---
|
||||
|
||||
## „Memory flush” pre-compaction (zaimplementowane)
|
||||
## „Opróżnianie pamięci” przed kompaktowaniem (zaimplementowane)
|
||||
|
||||
Cel: zanim nastąpi auto-compaction, uruchomić cichą, agentową turę, która zapisze trwały
|
||||
stan na dysku (np. `memory/YYYY-MM-DD.md` w obszarze roboczym agenta), tak aby compaction nie mógł
|
||||
wymazać krytycznego kontekstu.
|
||||
Cel: zanim nastąpi auto-kompaktowanie, uruchomić cichą agentową turę, która zapisze trwały
|
||||
stan na dysk (np. `memory/YYYY-MM-DD.md` w obszarze roboczym agenta), aby kompaktowanie nie mogło
|
||||
usunąć krytycznego kontekstu.
|
||||
|
||||
OpenClaw używa podejścia **pre-threshold flush**:
|
||||
OpenClaw używa podejścia **opróżniania przed progiem**:
|
||||
|
||||
1. Monitoruj użycie kontekstu sesji.
|
||||
2. Gdy przekroczy „miękki próg” (poniżej progu compaction Pi), uruchom cichą
|
||||
dyrektywę „zapisz pamięć teraz” dla agenta.
|
||||
3. Użyj dokładnego cichego tokenu `NO_REPLY` / `no_reply`, aby użytkownik niczego
|
||||
nie zobaczył.
|
||||
1. Monitoruje użycie kontekstu sesji.
|
||||
2. Gdy przekroczy ono „miękki próg” (poniżej progu kompaktowania Pi), uruchamia cichą
|
||||
dyrektywę „zapisz pamięć teraz” do agenta.
|
||||
3. Używa dokładnego cichego tokena `NO_REPLY` / `no_reply`, aby użytkownik niczego
|
||||
nie widział.
|
||||
|
||||
Config (`agents.defaults.compaction.memoryFlush`):
|
||||
Konfiguracja (`agents.defaults.compaction.memoryFlush`):
|
||||
|
||||
- `enabled` (domyślnie: `true`)
|
||||
- `softThresholdTokens` (domyślnie: `4000`)
|
||||
- `prompt` (wiadomość użytkownika dla tury flush)
|
||||
- `systemPrompt` (dodatkowy system prompt dołączany do tury flush)
|
||||
- `prompt` (wiadomość użytkownika dla tury opróżniania)
|
||||
- `systemPrompt` (dodatkowy prompt systemowy dołączany dla tury opróżniania)
|
||||
|
||||
Uwagi:
|
||||
|
||||
- Domyślny prompt/system prompt zawiera wskazówkę `NO_REPLY`, aby wyciszyć
|
||||
- Domyślny prompt/system prompt zawierają wskazówkę `NO_REPLY`, aby tłumić
|
||||
dostarczanie.
|
||||
- Flush jest uruchamiany raz na cykl compaction (śledzony w `sessions.json`).
|
||||
- Flush działa tylko dla osadzonych sesji Pi (backendy CLI go pomijają).
|
||||
- Flush jest pomijany, gdy obszar roboczy sesji jest tylko do odczytu (`workspaceAccess: "ro"` lub `"none"`).
|
||||
- Zobacz [Memory](/pl/concepts/memory), aby poznać układ plików obszaru roboczego i wzorce zapisu.
|
||||
- Opróżnianie uruchamia się raz na cykl kompaktowania (śledzone w `sessions.json`).
|
||||
- Opróżnianie działa tylko dla sesji osadzonego Pi (backendy CLI je pomijają).
|
||||
- Opróżnianie jest pomijane, gdy obszar roboczy sesji jest tylko do odczytu (`workspaceAccess: "ro"` lub `"none"`).
|
||||
- Zobacz [Pamięć](/pl/concepts/memory), aby poznać układ plików obszaru roboczego i wzorce zapisu.
|
||||
|
||||
Pi udostępnia też hook `session_before_compact` w API rozszerzeń, ale logika
|
||||
flush w OpenClaw obecnie znajduje się po stronie Gateway.
|
||||
opróżniania OpenClaw znajduje się obecnie po stronie Gateway.
|
||||
|
||||
---
|
||||
|
||||
## Lista kontrolna rozwiązywania problemów
|
||||
|
||||
- Zły klucz sesji? Zacznij od [/concepts/session](/pl/concepts/session) i potwierdź `sessionKey` w `/status`.
|
||||
- Nieprawidłowy klucz sesji? Zacznij od [/concepts/session](/pl/concepts/session) i potwierdź `sessionKey` w `/status`.
|
||||
- Niezgodność store i transkryptu? Potwierdź host Gateway i ścieżkę store z `openclaw status`.
|
||||
- Spam compaction? Sprawdź:
|
||||
- Spam kompaktowania? Sprawdź:
|
||||
- okno kontekstu modelu (za małe)
|
||||
- ustawienia compaction (`reserveTokens` ustawione zbyt wysoko względem okna modelu mogą powodować wcześniejszy compaction)
|
||||
- rozrost `toolResult`: włącz/skonfiguruj session pruning
|
||||
- Ciche tury przeciekają? Upewnij się, że odpowiedź zaczyna się od `NO_REPLY` (dokładny token, bez rozróżniania wielkości liter) i że używasz builda zawierającego poprawkę wyciszania streamingu.
|
||||
- ustawienia kompaktowania (`reserveTokens` zbyt wysokie względem okna modelu mogą powodować wcześniejsze kompaktowanie)
|
||||
- nadmiar `toolResult`: włącz/dostrój przycinanie sesji
|
||||
- Wyciekają ciche tury? Potwierdź, że odpowiedź zaczyna się od `NO_REPLY` (dokładny token, bez rozróżniania wielkości liter) i że używasz kompilacji zawierającej poprawkę tłumienia streamingu.
|
||||
|
||||
@ -1,236 +1,236 @@
|
||||
---
|
||||
read_when:
|
||||
- Uruchamianie harnessów programistycznych przez ACP
|
||||
- Konfigurowanie sesji ACP powiązanych z konwersacją na kanałach wiadomości
|
||||
- Powiązanie konwersacji kanału wiadomości z trwałą sesją ACP
|
||||
- Rozwiązywanie problemów z backendem ACP i połączeniem pluginu
|
||||
- Obsługa poleceń /acp z czatu
|
||||
- Uruchamiasz coding harnesses przez ACP
|
||||
- Konfigurujesz sesje ACP powiązane z rozmową na kanałach wiadomości
|
||||
- Powiązujesz rozmowę na kanale wiadomości z trwałą sesją ACP
|
||||
- Rozwiązujesz problemy z backendem ACP i połączeniami pluginów
|
||||
- Obsługujesz polecenia /acp z czatu
|
||||
summary: Używaj sesji runtime ACP dla Codex, Claude Code, Cursor, Gemini CLI, OpenClaw ACP i innych agentów harness
|
||||
title: Agenci ACP
|
||||
x-i18n:
|
||||
generated_at: "2026-04-07T09:52:40Z"
|
||||
generated_at: "2026-04-08T02:20:03Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: fb651ab39b05e537398623ee06cb952a5a07730fc75d3f7e0de20dd3128e72c6
|
||||
source_hash: 71c7c0cdae5247aefef17a0029360950a1c2987ddcee21a1bb7d78c67da52950
|
||||
source_path: tools/acp-agents.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Agenci ACP
|
||||
|
||||
Sesje [Agent Client Protocol (ACP)](https://agentclientprotocol.com/) pozwalają OpenClaw uruchamiać zewnętrzne harnessy programistyczne (na przykład Pi, Claude Code, Codex, Cursor, Copilot, OpenClaw ACP, OpenCode, Gemini CLI i inne obsługiwane harnessy ACPX) przez plugin backendu ACP.
|
||||
Sesje [Agent Client Protocol (ACP)](https://agentclientprotocol.com/) pozwalają OpenClaw uruchamiać zewnętrzne coding harnesses (na przykład Pi, Claude Code, Codex, Cursor, Copilot, OpenClaw ACP, OpenCode, Gemini CLI i inne obsługiwane harnesses ACPX) przez plugin backendu ACP.
|
||||
|
||||
Jeśli poprosisz OpenClaw zwykłym językiem, aby „uruchomił to w Codex” albo „uruchomił Claude Code w wątku”, OpenClaw powinien skierować to żądanie do runtime ACP (a nie do natywnego runtime sub-agenta). Każde uruchomienie sesji ACP jest śledzone jako [zadanie w tle](/pl/automation/tasks).
|
||||
Jeśli poprosisz OpenClaw zwykłym językiem, aby „uruchomił to w Codex” albo „uruchomił Claude Code w wątku”, OpenClaw powinien skierować to żądanie do runtime ACP (a nie do natywnego runtime podagentów). Każde uruchomienie sesji ACP jest śledzone jako [zadanie w tle](/pl/automation/tasks).
|
||||
|
||||
Jeśli chcesz, aby Codex lub Claude Code łączyły się jako zewnętrzny klient MCP bezpośrednio
|
||||
z istniejącymi konwersacjami kanałów OpenClaw, użyj
|
||||
Jeśli chcesz, aby Codex lub Claude Code połączyły się bezpośrednio jako zewnętrzny klient MCP
|
||||
z istniejącymi rozmowami kanałowymi OpenClaw, użyj
|
||||
[`openclaw mcp serve`](/cli/mcp) zamiast ACP.
|
||||
|
||||
## Którą stronę wybrać?
|
||||
## Którą stronę chcę?
|
||||
|
||||
Są tu trzy sąsiednie powierzchnie, które łatwo pomylić:
|
||||
Są tu trzy powiązane powierzchnie, które łatwo pomylić:
|
||||
|
||||
| Chcesz... | Użyj tego | Uwagi |
|
||||
| ---------------------------------------------------------------------------------- | ------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
|
||||
| Uruchamiać Codex, Claude Code, Gemini CLI lub inny zewnętrzny harness _przez_ OpenClaw | Ta strona: agenci ACP | Sesje powiązane z czatem, `/acp spawn`, `sessions_spawn({ runtime: "acp" })`, zadania w tle, kontrolki runtime |
|
||||
| Udostępnić sesję OpenClaw Gateway _jako_ serwer ACP dla edytora lub klienta | [`openclaw acp`](/cli/acp) | Tryb mostu. IDE/klient mówi ACP do OpenClaw przez stdio/WebSocket |
|
||||
| Użyć lokalnego AI CLI jako zapasowego modelu tylko tekstowego | [CLI Backends](/pl/gateway/cli-backends) | To nie ACP. Bez narzędzi OpenClaw, bez kontrolek ACP, bez runtime harness |
|
||||
| Chcesz... | Użyj tego | Uwagi |
|
||||
| --- | --- | --- |
|
||||
| Uruchamiać Codex, Claude Code, Gemini CLI lub inny zewnętrzny harness _przez_ OpenClaw | Ta strona: agenci ACP | Sesje powiązane z czatem, `/acp spawn`, `sessions_spawn({ runtime: "acp" })`, zadania w tle, kontrolki runtime |
|
||||
| Udostępnić sesję OpenClaw Gateway _jako_ serwer ACP dla edytora lub klienta | [`openclaw acp`](/cli/acp) | Tryb mostka. IDE/klient mówi ACP do OpenClaw przez stdio/WebSocket |
|
||||
| Użyć lokalnego AI CLI ponownie jako tekstowego modelu zapasowego | [CLI Backends](/pl/gateway/cli-backends) | To nie jest ACP. Brak narzędzi OpenClaw, brak kontrolek ACP, brak runtime harness |
|
||||
|
||||
## Czy to działa od razu po instalacji?
|
||||
|
||||
Zwykle tak.
|
||||
|
||||
- Świeże instalacje mają teraz domyślnie włączony dołączony plugin runtime `acpx`.
|
||||
- Dołączony plugin `acpx` preferuje swój lokalny, przypięty plik binarny `acpx`.
|
||||
- Przy starcie OpenClaw sonduje ten plik binarny i w razie potrzeby sam go naprawia.
|
||||
- Zacznij od `/acp doctor`, jeśli chcesz wykonać szybkie sprawdzenie gotowości.
|
||||
- Świeże instalacje są teraz dostarczane z włączonym domyślnie dołączonym pluginem runtime `acpx`.
|
||||
- Dołączony plugin `acpx` preferuje własny, przypięty binarny plik `acpx`.
|
||||
- Przy uruchomieniu OpenClaw sonduje ten plik binarny i w razie potrzeby sam go naprawia.
|
||||
- Zacznij od `/acp doctor`, jeśli chcesz przeprowadzić szybki test gotowości.
|
||||
|
||||
Co nadal może się zdarzyć przy pierwszym użyciu:
|
||||
|
||||
- Docelowy adapter harness może zostać pobrany na żądanie przez `npx` przy pierwszym użyciu tego harnessu.
|
||||
- Uwierzytelnianie producenta nadal musi istnieć na hoście dla tego harnessu.
|
||||
- Jeśli host nie ma dostępu do npm/sieci, pobrania adaptera przy pierwszym uruchomieniu mogą się nie udać, dopóki cache nie zostanie podgrzany lub adapter nie zostanie zainstalowany w inny sposób.
|
||||
- Adapter docelowego harness może zostać pobrany na żądanie przez `npx` przy pierwszym użyciu tego harness.
|
||||
- Uwierzytelnienie dostawcy nadal musi istnieć na hoście dla tego harness.
|
||||
- Jeśli host nie ma dostępu do npm/sieci, pobrania adapterów przy pierwszym uruchomieniu mogą się nie powieść, dopóki pamięci podręczne nie zostaną rozgrzane albo adapter nie zostanie zainstalowany w inny sposób.
|
||||
|
||||
Przykłady:
|
||||
|
||||
- `/acp spawn codex`: OpenClaw powinien być gotowy do bootstrapu `acpx`, ale adapter ACP dla Codex może nadal wymagać pobrania przy pierwszym uruchomieniu.
|
||||
- `/acp spawn claude`: podobnie w przypadku adaptera ACP dla Claude, plus uwierzytelnianie po stronie Claude na tym hoście.
|
||||
- `/acp spawn codex`: OpenClaw powinien być gotowy do bootstrapowania `acpx`, ale adapter ACP Codex może nadal wymagać pobrania przy pierwszym uruchomieniu.
|
||||
- `/acp spawn claude`: podobnie w przypadku adaptera ACP Claude oraz uwierzytelnienia po stronie Claude na tym hoście.
|
||||
|
||||
## Szybki przepływ dla operatora
|
||||
## Szybki przepływ operatora
|
||||
|
||||
Użyj tego, jeśli chcesz praktycznego runbooka `/acp`:
|
||||
Użyj tego, gdy chcesz praktycznego poradnika do `/acp`:
|
||||
|
||||
1. Uruchom sesję:
|
||||
- `/acp spawn codex --bind here`
|
||||
- `/acp spawn codex --mode persistent --thread auto`
|
||||
2. Pracuj w powiązanej konwersacji lub wątku (albo wskaż jawnie ten klucz sesji).
|
||||
2. Pracuj w powiązanej rozmowie lub wątku (albo wskaż jawnie ten klucz sesji).
|
||||
3. Sprawdź stan runtime:
|
||||
- `/acp status`
|
||||
4. Dostosuj opcje runtime w razie potrzeby:
|
||||
- `/acp model <provider/model>`
|
||||
- `/acp permissions <profile>`
|
||||
- `/acp timeout <seconds>`
|
||||
5. Delikatnie skieruj aktywną sesję bez zastępowania kontekstu:
|
||||
5. Skieruj aktywną sesję bez zastępowania kontekstu:
|
||||
- `/acp steer tighten logging and continue`
|
||||
6. Zatrzymaj pracę:
|
||||
- `/acp cancel` (zatrzymaj bieżącą turę), albo
|
||||
- `/acp close` (zamknij sesję + usuń powiązania)
|
||||
- `/acp close` (zamknij sesję i usuń powiązania)
|
||||
|
||||
## Szybki start dla ludzi
|
||||
|
||||
Przykłady naturalnych próśb:
|
||||
|
||||
- „Powiąż ten kanał Discord z Codex.”
|
||||
- „Uruchom tu trwałą sesję Codex w wątku i utrzymuj ją w skupieniu.”
|
||||
- „Uruchom trwałą sesję Codex w wątku tutaj i utrzymuj jej fokus.”
|
||||
- „Uruchom to jako jednorazową sesję Claude Code ACP i podsumuj wynik.”
|
||||
- „Powiąż ten czat iMessage z Codex i utrzymuj kolejne wiadomości w tym samym workspace.”
|
||||
- „Użyj Gemini CLI do tego zadania w wątku, a potem utrzymuj kolejne wiadomości w tym samym wątku.”
|
||||
- „Powiąż ten czat iMessage z Codex i zachowaj kolejne wiadomości w tym samym obszarze roboczym.”
|
||||
- „Użyj Gemini CLI do tego zadania w wątku, a potem zachowaj kolejne wiadomości w tym samym wątku.”
|
||||
|
||||
Co OpenClaw powinien zrobić:
|
||||
|
||||
1. Wybrać `runtime: "acp"`.
|
||||
2. Rozwiązać żądany cel harnessu (`agentId`, na przykład `codex`).
|
||||
3. Jeśli żądane jest powiązanie z bieżącą konwersacją i aktywny kanał je obsługuje, powiązać sesję ACP z tą konwersacją.
|
||||
4. W przeciwnym razie, jeśli żądane jest powiązanie z wątkiem i bieżący kanał je obsługuje, powiązać sesję ACP z wątkiem.
|
||||
5. Kierować kolejne powiązane wiadomości do tej samej sesji ACP, dopóki nie zostanie wyłączona, zamknięta lub nie wygaśnie.
|
||||
2. Rozpoznać żądany cel harness (`agentId`, na przykład `codex`).
|
||||
3. Jeśli zażądano powiązania z bieżącą rozmową i aktywny kanał to obsługuje, powiązać sesję ACP z tą rozmową.
|
||||
4. W przeciwnym razie, jeśli zażądano powiązania z wątkiem i bieżący kanał to obsługuje, powiązać sesję ACP z wątkiem.
|
||||
5. Kierować kolejne wiadomości w powiązaniu do tej samej sesji ACP, dopóki nie zostanie odfokusowana/zamknięta/wygaśnie.
|
||||
|
||||
## ACP a sub-agenci
|
||||
## ACP a podagenci
|
||||
|
||||
Używaj ACP, gdy chcesz zewnętrznego runtime harness. Używaj sub-agentów, gdy chcesz natywnych dla OpenClaw uruchomień delegowanych.
|
||||
Używaj ACP, gdy chcesz zewnętrznego runtime harness. Używaj podagentów, gdy chcesz delegowanych uruchomień natywnych dla OpenClaw.
|
||||
|
||||
| Obszar | Sesja ACP | Uruchomienie sub-agenta |
|
||||
| ------------- | ------------------------------------- | ---------------------------------- |
|
||||
| Runtime | Plugin backendu ACP (na przykład acpx) | Natywny runtime sub-agenta OpenClaw |
|
||||
| Klucz sesji | `agent:<agentId>:acp:<uuid>` | `agent:<agentId>:subagent:<uuid>` |
|
||||
| Główne polecenia | `/acp ...` | `/subagents ...` |
|
||||
| Narzędzie uruchamiania | `sessions_spawn` z `runtime:"acp"` | `sessions_spawn` (domyślny runtime) |
|
||||
| Obszar | Sesja ACP | Uruchomienie podagenta |
|
||||
| --- | --- | --- |
|
||||
| Runtime | Plugin backendu ACP (na przykład acpx) | Natywny runtime podagentów OpenClaw |
|
||||
| Klucz sesji | `agent:<agentId>:acp:<uuid>` | `agent:<agentId>:subagent:<uuid>` |
|
||||
| Główne polecenia | `/acp ...` | `/subagents ...` |
|
||||
| Narzędzie uruchamiania | `sessions_spawn` z `runtime:"acp"` | `sessions_spawn` (domyślny runtime) |
|
||||
|
||||
Zobacz też [Sub-agents](/pl/tools/subagents).
|
||||
|
||||
## Jak ACP uruchamia Claude Code
|
||||
|
||||
Dla Claude Code przez ACP stos jest następujący:
|
||||
W przypadku Claude Code przez ACP stos wygląda następująco:
|
||||
|
||||
1. Płaszczyzna sterowania sesjami OpenClaw ACP
|
||||
1. Płaszczyzna sterowania sesjami ACP OpenClaw
|
||||
2. dołączony plugin runtime `acpx`
|
||||
3. adapter Claude ACP
|
||||
4. runtime/mechanika sesji po stronie Claude
|
||||
4. mechanizm runtime/sesji po stronie Claude
|
||||
|
||||
Ważne rozróżnienie:
|
||||
|
||||
- ACP Claude to sesja harness z kontrolkami ACP, wznawianiem sesji, śledzeniem zadań w tle oraz opcjonalnym powiązaniem z konwersacją/wątkiem.
|
||||
- Backendy CLI to oddzielne lokalne, tylko tekstowe runtime zapasowe. Zobacz [CLI Backends](/pl/gateway/cli-backends).
|
||||
- ACP Claude to sesja harness z kontrolkami ACP, wznawianiem sesji, śledzeniem zadań w tle i opcjonalnym powiązaniem z rozmową/wątkiem.
|
||||
- CLI backends to oddzielne tekstowe lokalne runtime zapasowe. Zobacz [CLI Backends](/pl/gateway/cli-backends).
|
||||
|
||||
Dla operatorów praktyczna zasada jest taka:
|
||||
|
||||
- chcesz `/acp spawn`, sesji, które można powiązać, kontrolek runtime albo trwałej pracy harness: użyj ACP
|
||||
- chcesz prostego lokalnego fallbacku tekstowego przez surowe CLI: użyj backendów CLI
|
||||
- chcesz `/acp spawn`, sesje możliwe do powiązania, kontrolki runtime albo trwałą pracę harness: użyj ACP
|
||||
- chcesz prosty lokalny fallback tekstowy przez surowe CLI: użyj CLI backends
|
||||
|
||||
## Sesje powiązane
|
||||
## Powiązane sesje
|
||||
|
||||
### Powiązania z bieżącą konwersacją
|
||||
### Powiązania z bieżącą rozmową
|
||||
|
||||
Użyj `/acp spawn <harness> --bind here`, gdy chcesz, aby bieżąca konwersacja stała się trwałym workspace ACP bez tworzenia podrzędnego wątku.
|
||||
Użyj `/acp spawn <harness> --bind here`, gdy chcesz, aby bieżąca rozmowa stała się trwałym obszarem roboczym ACP bez tworzenia podrzędnego wątku.
|
||||
|
||||
Zachowanie:
|
||||
|
||||
- OpenClaw nadal obsługuje transport kanału, uwierzytelnianie, bezpieczeństwo i dostarczanie.
|
||||
- Bieżąca konwersacja jest przypinana do uruchomionego klucza sesji ACP.
|
||||
- Kolejne wiadomości w tej konwersacji są kierowane do tej samej sesji ACP.
|
||||
- OpenClaw nadal zarządza transportem kanału, auth, bezpieczeństwem i dostarczaniem.
|
||||
- Bieżąca rozmowa jest przypinana do uruchomionego klucza sesji ACP.
|
||||
- Kolejne wiadomości w tej rozmowie są kierowane do tej samej sesji ACP.
|
||||
- `/new` i `/reset` resetują tę samą powiązaną sesję ACP na miejscu.
|
||||
- `/acp close` zamyka sesję i usuwa powiązanie z bieżącą konwersacją.
|
||||
- `/acp close` zamyka sesję i usuwa powiązanie bieżącej rozmowy.
|
||||
|
||||
Co to oznacza w praktyce:
|
||||
|
||||
- `--bind here` zachowuje tę samą powierzchnię czatu. Na Discord bieżący kanał pozostaje bieżącym kanałem.
|
||||
- `--bind here` może nadal utworzyć nową sesję ACP, jeśli uruchamiasz świeżą pracę. Powiązanie dołącza tę sesję do bieżącej konwersacji.
|
||||
- `--bind here` samo z siebie nie tworzy podrzędnego wątku Discord ani tematu Telegram.
|
||||
- Runtime ACP może nadal mieć własny katalog roboczy (`cwd`) lub workspace zarządzany przez backend na dysku. Ten workspace runtime jest oddzielny od powierzchni czatu i nie oznacza nowego wątku wiadomości.
|
||||
- Jeśli uruchamiasz do innego agenta ACP i nie podasz `--cwd`, OpenClaw domyślnie dziedziczy workspace **docelowego agenta**, a nie żądającego.
|
||||
- Jeśli odziedziczona ścieżka workspace nie istnieje (`ENOENT`/`ENOTDIR`), OpenClaw wraca do domyślnego `cwd` backendu zamiast po cichu użyć niewłaściwego drzewa.
|
||||
- Jeśli odziedziczony workspace istnieje, ale nie można uzyskać do niego dostępu (na przykład `EACCES`), uruchomienie zwraca rzeczywisty błąd dostępu zamiast porzucać `cwd`.
|
||||
- `--bind here` nadal może utworzyć nową sesję ACP, jeśli uruchamiasz nową pracę.
|
||||
- `--bind here` sam z siebie nie tworzy podrzędnego wątku Discord ani tematu Telegram.
|
||||
- Runtime ACP nadal może mieć własny katalog roboczy (`cwd`) albo obszar roboczy zarządzany przez backend na dysku. Ten obszar roboczy runtime jest oddzielny od powierzchni czatu i nie oznacza nowego wątku wiadomości.
|
||||
- Jeśli uruchamiasz do innego agenta ACP i nie podajesz `--cwd`, OpenClaw domyślnie dziedziczy obszar roboczy **docelowego agenta**, a nie żądającego.
|
||||
- Jeśli ta odziedziczona ścieżka obszaru roboczego nie istnieje (`ENOENT`/`ENOTDIR`), OpenClaw wraca do domyślnego `cwd` backendu zamiast po cichu ponownie użyć niewłaściwego drzewa.
|
||||
- Jeśli odziedziczony obszar roboczy istnieje, ale nie można uzyskać do niego dostępu (na przykład `EACCES`), uruchomienie zwraca rzeczywisty błąd dostępu zamiast porzucać `cwd`.
|
||||
|
||||
Model mentalny:
|
||||
|
||||
- powierzchnia czatu: gdzie ludzie dalej rozmawiają (`kanał Discord`, `temat Telegram`, `czat iMessage`)
|
||||
- sesja ACP: trwały stan runtime Codex/Claude/Gemini, do którego kieruje OpenClaw
|
||||
- powierzchnia czatu: gdzie ludzie nadal rozmawiają (`kanał Discord`, `temat Telegram`, `czat iMessage`)
|
||||
- sesja ACP: trwały stan runtime Codex/Claude/Gemini, do którego OpenClaw kieruje wiadomości
|
||||
- podrzędny wątek/temat: opcjonalna dodatkowa powierzchnia wiadomości tworzona tylko przez `--thread ...`
|
||||
- workspace runtime: lokalizacja w systemie plików, gdzie działa harness (`cwd`, checkout repozytorium, workspace backendu)
|
||||
- obszar roboczy runtime: lokalizacja w systemie plików, w której działa harness (`cwd`, checkout repozytorium, obszar roboczy backendu)
|
||||
|
||||
Przykłady:
|
||||
|
||||
- `/acp spawn codex --bind here`: zachowaj ten czat, uruchom lub dołącz sesję Codex ACP i kieruj tu do niej przyszłe wiadomości
|
||||
- `/acp spawn codex --bind here`: zachowaj ten czat, uruchom lub dołącz sesję Codex ACP i kieruj do niej przyszłe wiadomości stąd
|
||||
- `/acp spawn codex --thread auto`: OpenClaw może utworzyć podrzędny wątek/temat i tam powiązać sesję ACP
|
||||
- `/acp spawn codex --bind here --cwd /workspace/repo`: to samo powiązanie z czatem co wyżej, ale Codex działa w `/workspace/repo`
|
||||
- `/acp spawn codex --bind here --cwd /workspace/repo`: to samo powiązanie czatu co wyżej, ale Codex działa w `/workspace/repo`
|
||||
|
||||
Obsługa powiązań z bieżącą konwersacją:
|
||||
Obsługa powiązań z bieżącą rozmową:
|
||||
|
||||
- Kanały czatu/wiadomości, które ogłaszają obsługę powiązań z bieżącą konwersacją, mogą używać `--bind here` przez współdzieloną ścieżkę powiązań konwersacji.
|
||||
- Kanały z niestandardową semantyką wątków/tematów mogą nadal dostarczać kanoniczność specyficzną dla kanału za tym samym współdzielonym interfejsem.
|
||||
- `--bind here` zawsze oznacza „powiąż bieżącą konwersację na miejscu”.
|
||||
- Ogólne powiązania z bieżącą konwersacją używają współdzielonego magazynu powiązań OpenClaw i przetrwają zwykłe restarty gateway.
|
||||
- Kanały czatu/wiadomości, które ogłaszają obsługę powiązania z bieżącą rozmową, mogą używać `--bind here` przez współdzieloną ścieżkę powiązań rozmów.
|
||||
- Kanały z niestandardową semantyką wątków/tematów nadal mogą zapewniać kanoniczność specyficzną dla kanału za tym samym współdzielonym interfejsem.
|
||||
- `--bind here` zawsze oznacza „powiąż bieżącą rozmowę na miejscu”.
|
||||
- Ogólne powiązania z bieżącą rozmową używają współdzielonego magazynu powiązań OpenClaw i przetrwają zwykłe restarty gateway.
|
||||
|
||||
Uwagi:
|
||||
|
||||
- `--bind here` i `--thread ...` wzajemnie się wykluczają w `/acp spawn`.
|
||||
- Na Discord `--bind here` wiąże bieżący kanał lub wątek na miejscu. `spawnAcpSessions` jest wymagane tylko wtedy, gdy OpenClaw musi utworzyć podrzędny wątek dla `--thread auto|here`.
|
||||
- Jeśli aktywny kanał nie udostępnia powiązań ACP z bieżącą konwersacją, OpenClaw zwraca jasny komunikat o braku obsługi.
|
||||
- Jeśli aktywny kanał nie udostępnia powiązań ACP z bieżącą rozmową, OpenClaw zwraca jasny komunikat o braku obsługi.
|
||||
- `resume` i pytania o „nową sesję” dotyczą sesji ACP, a nie kanału. Możesz ponownie użyć albo zastąpić stan runtime bez zmiany bieżącej powierzchni czatu.
|
||||
|
||||
### Sesje powiązane z wątkiem
|
||||
|
||||
Gdy adapter kanału ma włączoną obsługę powiązań wątków, sesje ACP mogą być powiązane z wątkami:
|
||||
Gdy powiązania wątków są włączone dla adaptera kanału, sesje ACP mogą być powiązane z wątkami:
|
||||
|
||||
- OpenClaw wiąże wątek z docelową sesją ACP.
|
||||
- Kolejne wiadomości w tym wątku są kierowane do powiązanej sesji ACP.
|
||||
- Dane wyjściowe ACP są dostarczane z powrotem do tego samego wątku.
|
||||
- Wyłączenie skupienia/zamknięcie/archiwizacja/timeout bezczynności albo wygaśnięcie maksymalnego wieku usuwa powiązanie.
|
||||
- Wynik ACP jest dostarczany z powrotem do tego samego wątku.
|
||||
- Odfokusowanie/zamknięcie/archiwizacja/wygaśnięcie limitu bezczynności lub maksymalnego wieku usuwa powiązanie.
|
||||
|
||||
Obsługa powiązań wątków jest specyficzna dla adaptera. Jeśli aktywny adapter kanału nie obsługuje powiązań wątków, OpenClaw zwraca jasny komunikat unsupported/unavailable.
|
||||
Obsługa powiązań wątków zależy od adaptera. Jeśli aktywny adapter kanału nie obsługuje powiązań wątków, OpenClaw zwraca jasny komunikat, że funkcja jest nieobsługiwana/niedostępna.
|
||||
|
||||
Wymagane flagi funkcji dla ACP powiązanego z wątkiem:
|
||||
Wymagane feature flags dla ACP powiązanego z wątkiem:
|
||||
|
||||
- `acp.enabled=true`
|
||||
- `acp.dispatch.enabled` jest domyślnie włączone (ustaw `false`, aby wstrzymać dispatch ACP)
|
||||
- Włączona flaga uruchamiania wątków ACP adaptera kanału (specyficzna dla adaptera)
|
||||
- Włączona flaga uruchamiania wątków ACP adaptera kanału (zależna od adaptera)
|
||||
- Discord: `channels.discord.threadBindings.spawnAcpSessions=true`
|
||||
- Telegram: `channels.telegram.threadBindings.spawnAcpSessions=true`
|
||||
|
||||
### Kanały obsługujące wątki
|
||||
|
||||
- Dowolny adapter kanału, który udostępnia możliwość powiązań sesji/wątków.
|
||||
- Obecne wbudowane wsparcie:
|
||||
- Dowolny adapter kanału, który udostępnia możliwość powiązania sesji/wątku.
|
||||
- Bieżąca wbudowana obsługa:
|
||||
- wątki/kanały Discord
|
||||
- tematy Telegram (tematy forum w grupach/supergrupach oraz tematy DM)
|
||||
- tematy Telegram (tematy forum w grupach/supergrupach i tematy DM)
|
||||
- Kanały pluginów mogą dodać obsługę przez ten sam interfejs powiązań.
|
||||
|
||||
## Ustawienia specyficzne dla kanału
|
||||
|
||||
W przypadku workflow nieefemerycznych skonfiguruj trwałe powiązania ACP w wpisach najwyższego poziomu `bindings[]`.
|
||||
W przypadku nieefemerycznych przepływów pracy skonfiguruj trwałe powiązania ACP w wpisach najwyższego poziomu `bindings[]`.
|
||||
|
||||
### Model powiązań
|
||||
|
||||
- `bindings[].type="acp"` oznacza trwałe powiązanie konwersacji ACP.
|
||||
- `bindings[].match` identyfikuje docelową konwersację:
|
||||
- `bindings[].type="acp"` oznacza trwałe powiązanie rozmowy ACP.
|
||||
- `bindings[].match` identyfikuje docelową rozmowę:
|
||||
- kanał lub wątek Discord: `match.channel="discord"` + `match.peer.id="<channelOrThreadId>"`
|
||||
- temat forum Telegram: `match.channel="telegram"` + `match.peer.id="<chatId>:topic:<topicId>"`
|
||||
- czat DM/grupowy BlueBubbles: `match.channel="bluebubbles"` + `match.peer.id="<handle|chat_id:*|chat_guid:*|chat_identifier:*>"`
|
||||
- czat DM/grupowy BlueBubbles: `match.channel="bluebubbles"` + `match.peer.id="<handle|chat_id:*|chat_guid:*|chat_identifier:*>"`
|
||||
Dla stabilnych powiązań grup preferuj `chat_id:*` lub `chat_identifier:*`.
|
||||
- czat DM/grupowy iMessage: `match.channel="imessage"` + `match.peer.id="<handle|chat_id:*|chat_guid:*|chat_identifier:*>"`
|
||||
- czat DM/grupowy iMessage: `match.channel="imessage"` + `match.peer.id="<handle|chat_id:*|chat_guid:*|chat_identifier:*>"`
|
||||
Dla stabilnych powiązań grup preferuj `chat_id:*`.
|
||||
- `bindings[].agentId` to identyfikator właściciela agenta OpenClaw.
|
||||
- `bindings[].agentId` to identyfikator właścicielskiego agenta OpenClaw.
|
||||
- Opcjonalne nadpisania ACP znajdują się w `bindings[].acp`:
|
||||
- `mode` (`persistent` lub `oneshot`)
|
||||
- `label`
|
||||
- `cwd`
|
||||
- `backend`
|
||||
|
||||
### Domyślne ustawienia runtime dla agenta
|
||||
### Domyślne ustawienia runtime na agenta
|
||||
|
||||
Użyj `agents.list[].runtime`, aby zdefiniować domyślne ustawienia ACP raz dla każdego agenta:
|
||||
|
||||
- `agents.list[].runtime.type="acp"`
|
||||
- `agents.list[].runtime.acp.agent` (identyfikator harnessu, na przykład `codex` albo `claude`)
|
||||
- `agents.list[].runtime.acp.agent` (identyfikator harness, na przykład `codex` lub `claude`)
|
||||
- `agents.list[].runtime.acp.backend`
|
||||
- `agents.list[].runtime.acp.mode`
|
||||
- `agents.list[].runtime.acp.cwd`
|
||||
@ -239,7 +239,7 @@ Kolejność pierwszeństwa nadpisań dla powiązanych sesji ACP:
|
||||
|
||||
1. `bindings[].acp.*`
|
||||
2. `agents.list[].runtime.acp.*`
|
||||
3. globalne wartości domyślne ACP (na przykład `acp.backend`)
|
||||
3. globalne ustawienia domyślne ACP (na przykład `acp.backend`)
|
||||
|
||||
Przykład:
|
||||
|
||||
@ -323,12 +323,12 @@ Przykład:
|
||||
|
||||
Zachowanie:
|
||||
|
||||
- OpenClaw upewnia się, że skonfigurowana sesja ACP istnieje przed użyciem.
|
||||
- OpenClaw zapewnia istnienie skonfigurowanej sesji ACP przed użyciem.
|
||||
- Wiadomości w tym kanale lub temacie są kierowane do skonfigurowanej sesji ACP.
|
||||
- W powiązanych konwersacjach `/new` i `/reset` resetują ten sam klucz sesji ACP na miejscu.
|
||||
- Tymczasowe powiązania runtime (na przykład utworzone przez przepływy focus wątków) nadal mają zastosowanie, jeśli istnieją.
|
||||
- Przy uruchamianiu między agentami ACP bez jawnego `cwd` OpenClaw dziedziczy workspace docelowego agenta z konfiguracji agenta.
|
||||
- Brakujące odziedziczone ścieżki workspace powodują fallback do domyślnego `cwd` backendu; rzeczywiste błędy dostępu do istniejących ścieżek są zwracane jako błędy uruchamiania.
|
||||
- W powiązanych rozmowach `/new` i `/reset` resetują ten sam klucz sesji ACP na miejscu.
|
||||
- Tymczasowe powiązania runtime (na przykład utworzone przez przepływy fokusu wątków) nadal mają zastosowanie tam, gdzie istnieją.
|
||||
- Przy uruchamianiu ACP między agentami bez jawnego `cwd` OpenClaw dziedziczy obszar roboczy docelowego agenta z konfiguracji agenta.
|
||||
- Brakujące odziedziczone ścieżki obszaru roboczego wracają do domyślnego `cwd` backendu; rzeczywiste błędy dostępu są zwracane jako błędy uruchomienia.
|
||||
|
||||
## Uruchamianie sesji ACP (interfejsy)
|
||||
|
||||
@ -348,29 +348,29 @@ Użyj `runtime: "acp"`, aby uruchomić sesję ACP z tury agenta lub wywołania n
|
||||
|
||||
Uwagi:
|
||||
|
||||
- `runtime` domyślnie ma wartość `subagent`, więc dla sesji ACP ustaw jawnie `runtime: "acp"`.
|
||||
- Jeśli `agentId` zostanie pominięte, OpenClaw używa `acp.defaultAgent`, gdy jest skonfigurowane.
|
||||
- `mode: "session"` wymaga `thread: true`, aby zachować trwałą powiązaną konwersację.
|
||||
- `runtime` domyślnie ma wartość `subagent`, więc ustaw `runtime: "acp"` jawnie dla sesji ACP.
|
||||
- Jeśli pominięto `agentId`, OpenClaw użyje `acp.defaultAgent`, jeśli jest skonfigurowane.
|
||||
- `mode: "session"` wymaga `thread: true`, aby zachować trwałą powiązaną rozmowę.
|
||||
|
||||
Szczegóły interfejsu:
|
||||
|
||||
- `task` (wymagane): początkowy prompt wysyłany do sesji ACP.
|
||||
- `runtime` (wymagane dla ACP): musi mieć wartość `"acp"`.
|
||||
- `agentId` (opcjonalne): identyfikator docelowego harnessu ACP. Jeśli ustawione, fallback do `acp.defaultAgent`.
|
||||
- `thread` (opcjonalne, domyślnie `false`): żądanie przepływu powiązania z wątkiem tam, gdzie jest obsługiwany.
|
||||
- `agentId` (opcjonalne): identyfikator docelowego harness ACP. Wraca do `acp.defaultAgent`, jeśli jest ustawiony.
|
||||
- `thread` (opcjonalne, domyślnie `false`): żądanie przepływu powiązania z wątkiem, gdy jest obsługiwane.
|
||||
- `mode` (opcjonalne): `run` (jednorazowe) albo `session` (trwałe).
|
||||
- domyślnie jest `run`
|
||||
- jeśli `thread: true` i `mode` pominięte, OpenClaw może domyślnie przejść do zachowania trwałego zależnie od ścieżki runtime
|
||||
- jeśli `thread: true` i `mode` pominięto, OpenClaw może domyślnie przejść do zachowania trwałego zależnie od ścieżki runtime
|
||||
- `mode: "session"` wymaga `thread: true`
|
||||
- `cwd` (opcjonalne): żądany katalog roboczy runtime (walidowany przez backend/politykę runtime). Jeśli zostanie pominięte, uruchomienie ACP dziedziczy workspace docelowego agenta, jeśli jest skonfigurowane; brakujące odziedziczone ścieżki powodują fallback do domyślnych ustawień backendu, natomiast rzeczywiste błędy dostępu są zwracane.
|
||||
- `label` (opcjonalne): etykieta widoczna dla operatora używana w tekście sesji/banneru.
|
||||
- `resumeSessionId` (opcjonalne): wznów istniejącą sesję ACP zamiast tworzyć nową. Agent odtwarza historię konwersacji przez `session/load`. Wymaga `runtime: "acp"`.
|
||||
- `streamTo` (opcjonalne): `"parent"` przesyła podsumowania postępu początkowego uruchomienia ACP z powrotem do sesji żądającej jako zdarzenia systemowe.
|
||||
- Gdy jest dostępne, zaakceptowane odpowiedzi zawierają `streamLogPath` wskazujące plik JSONL z zakresem sesji (`<sessionId>.acp-stream.jsonl`), który można śledzić, aby zobaczyć pełną historię przekazywania.
|
||||
- `cwd` (opcjonalne): żądany katalog roboczy runtime (walidowany przez politykę backendu/runtime). Jeśli pominięty, uruchomienie ACP dziedziczy obszar roboczy docelowego agenta, gdy jest skonfigurowany; brakujące odziedziczone ścieżki wracają do domyślnych backendu, a rzeczywiste błędy dostępu są zwracane.
|
||||
- `label` (opcjonalne): etykieta widoczna dla operatora używana w tekście sesji/banera.
|
||||
- `resumeSessionId` (opcjonalne): wznowienie istniejącej sesji ACP zamiast tworzenia nowej. Agent odtwarza historię rozmowy przez `session/load`. Wymaga `runtime: "acp"`.
|
||||
- `streamTo` (opcjonalne): `"parent"` strumieniuje podsumowania postępu początkowego uruchomienia ACP z powrotem do sesji żądającej jako zdarzenia systemowe.
|
||||
- Gdy dostępne, zaakceptowane odpowiedzi zawierają `streamLogPath`, wskazujące na plik JSONL logu o zakresie sesji (`<sessionId>.acp-stream.jsonl`), który można śledzić, aby zobaczyć pełną historię przekazywania.
|
||||
|
||||
### Wznawianie istniejącej sesji
|
||||
### Wznowienie istniejącej sesji
|
||||
|
||||
Użyj `resumeSessionId`, aby kontynuować poprzednią sesję ACP zamiast rozpoczynać od nowa. Agent odtwarza historię konwersacji przez `session/load`, więc wznawia pracę z pełnym kontekstem wcześniejszych działań.
|
||||
Użyj `resumeSessionId`, aby kontynuować poprzednią sesję ACP zamiast zaczynać od nowa. Agent odtwarza historię rozmowy przez `session/load`, więc wznawia pracę z pełnym kontekstem tego, co było wcześniej.
|
||||
|
||||
```json
|
||||
{
|
||||
@ -383,39 +383,38 @@ Użyj `resumeSessionId`, aby kontynuować poprzednią sesję ACP zamiast rozpocz
|
||||
|
||||
Typowe przypadki użycia:
|
||||
|
||||
- Przekazanie sesji Codex z laptopa na telefon — powiedz agentowi, aby podjął pracę tam, gdzie została przerwana
|
||||
- Kontynuacja sesji programistycznej rozpoczętej interaktywnie w CLI, teraz bezobsługowo przez agenta
|
||||
- Podjęcie pracy przerwanej przez restart gateway albo timeout bezczynności
|
||||
- Przekazanie sesji Codex z laptopa na telefon — poproś agenta, aby podjął pracę tam, gdzie skończyłeś
|
||||
- Kontynuowanie sesji programistycznej rozpoczętej interaktywnie w CLI, teraz bezgłowo przez agenta
|
||||
- Wznowienie pracy przerwanej przez restart gateway albo timeout bezczynności
|
||||
|
||||
Uwagi:
|
||||
|
||||
- `resumeSessionId` wymaga `runtime: "acp"` — zwraca błąd, jeśli zostanie użyte z runtime sub-agenta.
|
||||
- `resumeSessionId` przywraca historię konwersacji upstream ACP; `thread` i `mode` nadal normalnie dotyczą nowej sesji OpenClaw, którą tworzysz, więc `mode: "session"` nadal wymaga `thread: true`.
|
||||
- Docelowy agent musi obsługiwać `session/load` (Codex i Claude Code obsługują).
|
||||
- Jeśli identyfikator sesji nie zostanie znaleziony, uruchomienie kończy się jasnym błędem — bez cichego fallbacku do nowej sesji.
|
||||
- `resumeSessionId` wymaga `runtime: "acp"` — zwraca błąd, jeśli zostanie użyte z runtime podagenta.
|
||||
- `resumeSessionId` przywraca historię rozmowy upstream ACP; `thread` i `mode` nadal stosują się normalnie do nowej sesji OpenClaw, którą tworzysz, więc `mode: "session"` nadal wymaga `thread: true`.
|
||||
- Docelowy agent musi obsługiwać `session/load` (Codex i Claude Code to obsługują).
|
||||
- Jeśli identyfikator sesji nie zostanie znaleziony, uruchomienie kończy się jawnym błędem — bez cichego przejścia do nowej sesji.
|
||||
|
||||
### Test smoke dla operatora
|
||||
### Smoke test operatora
|
||||
|
||||
Użyj tego po wdrożeniu gateway, gdy chcesz szybko na żywo sprawdzić, czy uruchamianie ACP
|
||||
rzeczywiście działa end-to-end, a nie tylko przechodzi testy jednostkowe.
|
||||
Użyj tego po wdrożeniu gateway, gdy chcesz szybko na żywo sprawdzić, czy uruchamianie ACP naprawdę działa end-to-end, a nie tylko przechodzi testy jednostkowe.
|
||||
|
||||
Zalecana bramka:
|
||||
|
||||
1. Zweryfikuj wdrożoną wersję/commit gateway na docelowym hoście.
|
||||
1. Zweryfikuj wdrożoną wersję/commit gateway na hoście docelowym.
|
||||
2. Potwierdź, że wdrożone źródło zawiera akceptację linii ACP w
|
||||
`src/gateway/sessions-patch.ts` (`subagent:* or acp:* sessions`).
|
||||
3. Otwórz tymczasową sesję mostu ACPX do aktywnego agenta (na przykład
|
||||
3. Otwórz tymczasową sesję mostka ACPX do aktywnego agenta (na przykład
|
||||
`razor(main)` na `jpclawhq`).
|
||||
4. Poproś tego agenta o wywołanie `sessions_spawn` z:
|
||||
- `runtime: "acp"`
|
||||
- `agentId: "codex"`
|
||||
- `mode: "run"`
|
||||
- zadaniem: `Reply with exactly LIVE-ACP-SPAWN-OK`
|
||||
5. Zweryfikuj, że agent raportuje:
|
||||
- task: `Reply with exactly LIVE-ACP-SPAWN-OK`
|
||||
5. Zweryfikuj, że agent zgłasza:
|
||||
- `accepted=yes`
|
||||
- rzeczywisty `childSessionKey`
|
||||
- brak błędu walidatora
|
||||
6. Wyczyść tymczasową sesję mostu ACPX.
|
||||
6. Posprzątaj tymczasową sesję mostka ACPX.
|
||||
|
||||
Przykładowy prompt do aktywnego agenta:
|
||||
|
||||
@ -427,16 +426,16 @@ Then report only: accepted=<yes/no>; childSessionKey=<value or none>; error=<exa
|
||||
|
||||
Uwagi:
|
||||
|
||||
- Utrzymuj ten test smoke w `mode: "run"`, chyba że celowo testujesz
|
||||
- Trzymaj ten smoke test w `mode: "run"`, chyba że celowo testujesz
|
||||
trwałe sesje ACP powiązane z wątkiem.
|
||||
- Nie wymagaj `streamTo: "parent"` dla podstawowej bramki. Ta ścieżka zależy od
|
||||
możliwości sesji żądającej i jest osobnym sprawdzeniem integracyjnym.
|
||||
- Testowanie `mode: "session"` powiązanego z wątkiem traktuj jako drugi, bogatszy przebieg integracyjny
|
||||
z prawdziwego wątku Discord albo tematu Telegram.
|
||||
możliwości żądającego/sesji i jest osobnym testem integracyjnym.
|
||||
- Traktuj testowanie `mode: "session"` powiązanego z wątkiem jako drugi, bogatszy przebieg integracyjny
|
||||
z rzeczywistego wątku Discord albo tematu Telegram.
|
||||
|
||||
## Zgodność z sandbox
|
||||
|
||||
Sesje ACP działają obecnie na runtime hosta, a nie wewnątrz sandbox OpenClaw.
|
||||
Sesje ACP obecnie działają w runtime hosta, a nie wewnątrz sandbox OpenClaw.
|
||||
|
||||
Obecne ograniczenia:
|
||||
|
||||
@ -445,7 +444,7 @@ Obecne ograniczenia:
|
||||
- `sessions_spawn` z `runtime: "acp"` nie obsługuje `sandbox: "require"`.
|
||||
- Błąd: `sessions_spawn sandbox="require" is unsupported for runtime="acp" because ACP sessions run outside the sandbox. Use runtime="subagent" or sandbox="inherit".`
|
||||
|
||||
Użyj `runtime: "subagent"`, gdy potrzebujesz wykonania wymuszonego przez sandbox.
|
||||
Używaj `runtime: "subagent"`, gdy potrzebujesz wykonania wymuszanego przez sandbox.
|
||||
|
||||
### Z polecenia `/acp`
|
||||
|
||||
@ -468,56 +467,56 @@ Kluczowe flagi:
|
||||
|
||||
Zobacz [Slash Commands](/pl/tools/slash-commands).
|
||||
|
||||
## Rozwiązywanie celu sesji
|
||||
## Rozpoznawanie celu sesji
|
||||
|
||||
Większość działań `/acp` akceptuje opcjonalny cel sesji (`session-key`, `session-id` lub `session-label`).
|
||||
Większość akcji `/acp` akceptuje opcjonalny cel sesji (`session-key`, `session-id` albo `session-label`).
|
||||
|
||||
Kolejność rozwiązywania:
|
||||
Kolejność rozpoznawania:
|
||||
|
||||
1. Jawny argument celu (lub `--session` dla `/acp steer`)
|
||||
- najpierw próba jako key
|
||||
- potem jako identyfikator sesji w kształcie UUID
|
||||
- potem jako label
|
||||
2. Bieżące powiązanie z wątkiem (jeśli ta konwersacja/wątek jest powiązana z sesją ACP)
|
||||
3. Fallback do bieżącej sesji żądającej
|
||||
1. Jawny argument celu (albo `--session` dla `/acp steer`)
|
||||
- próbuje najpierw klucza
|
||||
- potem identyfikatora sesji w formacie UUID
|
||||
- potem etykiety
|
||||
2. Bieżące powiązanie wątku (jeśli ta rozmowa/wątek jest powiązana z sesją ACP)
|
||||
3. Powrót do bieżącej sesji żądającej
|
||||
|
||||
Powiązania z bieżącą konwersacją i z wątkiem uczestniczą w kroku 2.
|
||||
Powiązania z bieżącą rozmową i powiązania wątków biorą udział w kroku 2.
|
||||
|
||||
Jeśli nie uda się rozwiązać celu, OpenClaw zwraca jasny błąd (`Unable to resolve session target: ...`).
|
||||
Jeśli nie uda się rozpoznać żadnego celu, OpenClaw zwraca jasny błąd (`Unable to resolve session target: ...`).
|
||||
|
||||
## Tryby powiązania przy uruchamianiu
|
||||
|
||||
`/acp spawn` obsługuje `--bind here|off`.
|
||||
|
||||
| Tryb | Zachowanie |
|
||||
| ------ | ---------------------------------------------------------------------- |
|
||||
| `here` | Powiąż bieżącą aktywną konwersację na miejscu; zakończ błędem, jeśli żadna nie jest aktywna. |
|
||||
| `off` | Nie twórz powiązania z bieżącą konwersacją. |
|
||||
| Tryb | Zachowanie |
|
||||
| --- | --- |
|
||||
| `here` | Powiąż bieżącą aktywną rozmowę na miejscu; zakończ błędem, jeśli żadna nie jest aktywna. |
|
||||
| `off` | Nie twórz powiązania z bieżącą rozmową. |
|
||||
|
||||
Uwagi:
|
||||
|
||||
- `--bind here` to najprostsza ścieżka operatora dla „zrób z tego kanału lub czatu zaplecze Codex”.
|
||||
- `--bind here` to najprostsza ścieżka operatora dla „niech ten kanał lub czat będzie obsługiwany przez Codex”.
|
||||
- `--bind here` nie tworzy podrzędnego wątku.
|
||||
- `--bind here` jest dostępne tylko na kanałach, które udostępniają obsługę powiązań z bieżącą konwersacją.
|
||||
- `--bind here` jest dostępne tylko w kanałach, które udostępniają obsługę powiązania z bieżącą rozmową.
|
||||
- `--bind` i `--thread` nie mogą być łączone w tym samym wywołaniu `/acp spawn`.
|
||||
|
||||
## Tryby wątków przy uruchamianiu
|
||||
|
||||
`/acp spawn` obsługuje `--thread auto|here|off`.
|
||||
|
||||
| Tryb | Zachowanie |
|
||||
| ------ | --------------------------------------------------------------------------------------------------- |
|
||||
| Tryb | Zachowanie |
|
||||
| --- | --- |
|
||||
| `auto` | W aktywnym wątku: powiąż ten wątek. Poza wątkiem: utwórz/powiąż podrzędny wątek, jeśli jest obsługiwany. |
|
||||
| `here` | Wymagaj bieżącego aktywnego wątku; zakończ błędem, jeśli nie jesteś w wątku. |
|
||||
| `off` | Bez powiązania. Sesja uruchamia się bez powiązania. |
|
||||
| `here` | Wymagaj bieżącego aktywnego wątku; zakończ błędem, jeśli nie jesteś w wątku. |
|
||||
| `off` | Brak powiązania. Sesja uruchamia się bez powiązania. |
|
||||
|
||||
Uwagi:
|
||||
|
||||
- Na powierzchniach bez obsługi powiązań wątków domyślne zachowanie jest w praktyce `off`.
|
||||
- Uruchamianie powiązane z wątkiem wymaga obsługi w polityce kanału:
|
||||
- Na powierzchniach bez obsługi powiązań wątków domyślne zachowanie jest w praktyce równe `off`.
|
||||
- Uruchamianie powiązane z wątkiem wymaga obsługi polityki kanału:
|
||||
- Discord: `channels.discord.threadBindings.spawnAcpSessions=true`
|
||||
- Telegram: `channels.telegram.threadBindings.spawnAcpSessions=true`
|
||||
- Użyj `--bind here`, gdy chcesz przypiąć bieżącą konwersację bez tworzenia podrzędnego wątku.
|
||||
- Użyj `--bind here`, jeśli chcesz przypiąć bieżącą rozmowę bez tworzenia podrzędnego wątku.
|
||||
|
||||
## Kontrolki ACP
|
||||
|
||||
@ -539,49 +538,49 @@ Dostępna rodzina poleceń:
|
||||
- `/acp doctor`
|
||||
- `/acp install`
|
||||
|
||||
`/acp status` pokazuje efektywne opcje runtime oraz, gdy są dostępne, zarówno identyfikatory sesji na poziomie runtime, jak i backendu.
|
||||
`/acp status` pokazuje efektywne opcje runtime i, gdy są dostępne, identyfikatory sesji zarówno na poziomie runtime, jak i backendu.
|
||||
|
||||
Niektóre kontrolki zależą od możliwości backendu. Jeśli backend nie obsługuje danej kontrolki, OpenClaw zwraca jasny błąd unsupported-control.
|
||||
Niektóre kontrolki zależą od możliwości backendu. Jeśli backend nie obsługuje danej kontrolki, OpenClaw zwraca jasny błąd nieobsługiwanej kontrolki.
|
||||
|
||||
## Książka kucharska poleceń ACP
|
||||
|
||||
| Polecenie | Co robi | Przykład |
|
||||
| -------------------- | --------------------------------------------------------- | ------------------------------------------------------------- |
|
||||
| `/acp spawn` | Tworzy sesję ACP; opcjonalnie powiązanie z bieżącą konwersacją lub wątkiem. | `/acp spawn codex --bind here --cwd /repo` |
|
||||
| `/acp cancel` | Anuluje turę w locie dla docelowej sesji. | `/acp cancel agent:codex:acp:<uuid>` |
|
||||
| `/acp steer` | Wysyła instrukcję sterującą do działającej sesji. | `/acp steer --session support inbox prioritize failing tests` |
|
||||
| `/acp close` | Zamyka sesję i odwiązuje cele wątków. | `/acp close` |
|
||||
| `/acp status` | Pokazuje backend, tryb, stan, opcje runtime, możliwości. | `/acp status` |
|
||||
| `/acp set-mode` | Ustawia tryb runtime dla docelowej sesji. | `/acp set-mode plan` |
|
||||
| `/acp set` | Ogólny zapis opcji konfiguracji runtime. | `/acp set model openai/gpt-5.4` |
|
||||
| `/acp cwd` | Ustawia nadpisanie katalogu roboczego runtime. | `/acp cwd /Users/user/Projects/repo` |
|
||||
| `/acp permissions` | Ustawia profil polityki zatwierdzeń. | `/acp permissions strict` |
|
||||
| `/acp timeout` | Ustawia timeout runtime (sekundy). | `/acp timeout 120` |
|
||||
| `/acp model` | Ustawia nadpisanie modelu runtime. | `/acp model anthropic/claude-opus-4-6` |
|
||||
| `/acp reset-options` | Usuwa nadpisania opcji runtime dla sesji. | `/acp reset-options` |
|
||||
| `/acp sessions` | Wyświetla ostatnie sesje ACP z magazynu. | `/acp sessions` |
|
||||
| `/acp doctor` | Stan backendu, możliwości, konkretne poprawki. | `/acp doctor` |
|
||||
| `/acp install` | Wypisuje deterministyczne kroki instalacji i włączenia. | `/acp install` |
|
||||
| Polecenie | Co robi | Przykład |
|
||||
| --- | --- | --- |
|
||||
| `/acp spawn` | Tworzy sesję ACP; opcjonalnie powiązanie z bieżącą rozmową albo z wątkiem. | `/acp spawn codex --bind here --cwd /repo` |
|
||||
| `/acp cancel` | Anuluje turę będącą w toku dla docelowej sesji. | `/acp cancel agent:codex:acp:<uuid>` |
|
||||
| `/acp steer` | Wysyła instrukcję sterującą do uruchomionej sesji. | `/acp steer --session support inbox prioritize failing tests` |
|
||||
| `/acp close` | Zamyka sesję i odpina cele wątków. | `/acp close` |
|
||||
| `/acp status` | Pokazuje backend, tryb, stan, opcje runtime, możliwości. | `/acp status` |
|
||||
| `/acp set-mode` | Ustawia tryb runtime dla docelowej sesji. | `/acp set-mode plan` |
|
||||
| `/acp set` | Ogólny zapis opcji konfiguracji runtime. | `/acp set model openai/gpt-5.4` |
|
||||
| `/acp cwd` | Ustawia nadpisanie katalogu roboczego runtime. | `/acp cwd /Users/user/Projects/repo` |
|
||||
| `/acp permissions` | Ustawia profil polityki zatwierdzeń. | `/acp permissions strict` |
|
||||
| `/acp timeout` | Ustawia limit czasu runtime (sekundy). | `/acp timeout 120` |
|
||||
| `/acp model` | Ustawia nadpisanie modelu runtime. | `/acp model anthropic/claude-opus-4-6` |
|
||||
| `/acp reset-options` | Usuwa nadpisania opcji runtime sesji. | `/acp reset-options` |
|
||||
| `/acp sessions` | Wyświetla ostatnie sesje ACP z magazynu. | `/acp sessions` |
|
||||
| `/acp doctor` | Stan backendu, możliwości, możliwe działania naprawcze. | `/acp doctor` |
|
||||
| `/acp install` | Wyświetla deterministyczne kroki instalacji i włączenia. | `/acp install` |
|
||||
|
||||
`/acp sessions` odczytuje magazyn dla bieżącej powiązanej sesji albo sesji żądającej. Polecenia akceptujące tokeny `session-key`, `session-id` albo `session-label` rozwiązują cele przez wykrywanie sesji gateway, w tym niestandardowe katalogi `session.store` dla poszczególnych agentów.
|
||||
`/acp sessions` odczytuje magazyn dla bieżącej powiązanej sesji albo sesji żądającej. Polecenia, które akceptują tokeny `session-key`, `session-id` albo `session-label`, rozpoznają cele przez wykrywanie sesji gateway, w tym niestandardowe katalogi `session.store` dla poszczególnych agentów.
|
||||
|
||||
## Mapowanie opcji runtime
|
||||
|
||||
`/acp` ma polecenia wygodne i ogólny setter.
|
||||
`/acp` ma wygodne polecenia i generyczny setter.
|
||||
|
||||
Operacje równoważne:
|
||||
Równoważne operacje:
|
||||
|
||||
- `/acp model <id>` mapuje się na klucz konfiguracji runtime `model`.
|
||||
- `/acp permissions <profile>` mapuje się na klucz konfiguracji runtime `approval_policy`.
|
||||
- `/acp timeout <seconds>` mapuje się na klucz konfiguracji runtime `timeout`.
|
||||
- `/acp model <id>` mapuje do klucza konfiguracji runtime `model`.
|
||||
- `/acp permissions <profile>` mapuje do klucza konfiguracji runtime `approval_policy`.
|
||||
- `/acp timeout <seconds>` mapuje do klucza konfiguracji runtime `timeout`.
|
||||
- `/acp cwd <path>` bezpośrednio aktualizuje nadpisanie `cwd` runtime.
|
||||
- `/acp set <key> <value>` to ścieżka ogólna.
|
||||
- Szczególny przypadek: `key=cwd` używa ścieżki nadpisania `cwd`.
|
||||
- Przypadek specjalny: `key=cwd` używa ścieżki nadpisania `cwd`.
|
||||
- `/acp reset-options` czyści wszystkie nadpisania runtime dla docelowej sesji.
|
||||
|
||||
## Obsługa harnessów acpx (obecnie)
|
||||
## Obsługa harness acpx (obecnie)
|
||||
|
||||
Obecne wbudowane aliasy harnessów acpx:
|
||||
Bieżące wbudowane aliasy harness acpx:
|
||||
|
||||
- `claude`
|
||||
- `codex`
|
||||
@ -598,20 +597,20 @@ Obecne wbudowane aliasy harnessów acpx:
|
||||
- `pi`
|
||||
- `qwen`
|
||||
|
||||
Gdy OpenClaw używa backendu acpx, dla `agentId` preferuj te wartości, chyba że konfiguracja acpx definiuje niestandardowe aliasy agentów.
|
||||
Jeśli lokalna instalacja Cursor nadal ujawnia ACP jako `agent acp`, nadpisz polecenie agenta `cursor` w konfiguracji acpx zamiast zmieniać wbudowaną wartość domyślną.
|
||||
Gdy OpenClaw używa backendu acpx, preferuj te wartości dla `agentId`, chyba że konfiguracja acpx definiuje własne aliasy agentów.
|
||||
Jeśli lokalna instalacja Cursor nadal udostępnia ACP jako `agent acp`, nadpisz polecenie agenta `cursor` w swojej konfiguracji acpx zamiast zmieniać wbudowaną wartość domyślną.
|
||||
|
||||
Bezpośrednie użycie CLI acpx może też kierować do dowolnych adapterów przez `--agent <command>`, ale ta surowa furtka ucieczki jest funkcją CLI acpx (a nie normalną ścieżką `agentId` OpenClaw).
|
||||
Bezpośrednie użycie CLI acpx może również kierować żądania do dowolnych adapterów przez `--agent <command>`, ale ta surowa furtka jest funkcją CLI acpx (a nie zwykłą ścieżką `agentId` w OpenClaw).
|
||||
|
||||
## Wymagana konfiguracja
|
||||
|
||||
Podstawowa konfiguracja ACP:
|
||||
Bazowa konfiguracja ACP:
|
||||
|
||||
```json5
|
||||
{
|
||||
acp: {
|
||||
enabled: true,
|
||||
// Opcjonalne. Wartość domyślna to true; ustaw false, aby wstrzymać dispatch ACP przy zachowaniu kontrolek /acp.
|
||||
// Optional. Default is true; set false to pause ACP dispatch while keeping /acp controls.
|
||||
dispatch: { enabled: true },
|
||||
backend: "acpx",
|
||||
defaultAgent: "codex",
|
||||
@ -643,7 +642,7 @@ Podstawowa konfiguracja ACP:
|
||||
}
|
||||
```
|
||||
|
||||
Konfiguracja powiązań wątków jest specyficzna dla adaptera kanału. Przykład dla Discord:
|
||||
Konfiguracja powiązania wątków zależy od adaptera kanału. Przykład dla Discord:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -669,14 +668,13 @@ Jeśli uruchamianie ACP powiązane z wątkiem nie działa, najpierw sprawdź fla
|
||||
|
||||
- Discord: `channels.discord.threadBindings.spawnAcpSessions=true`
|
||||
|
||||
Powiązania z bieżącą konwersacją nie wymagają tworzenia podrzędnego wątku. Wymagają aktywnego kontekstu konwersacji i adaptera kanału, który udostępnia powiązania konwersacji ACP.
|
||||
Powiązania z bieżącą rozmową nie wymagają tworzenia podrzędnego wątku. Wymagają aktywnego kontekstu rozmowy i adaptera kanału, który udostępnia powiązania rozmów ACP.
|
||||
|
||||
Zobacz [Configuration Reference](/pl/gateway/configuration-reference).
|
||||
|
||||
## Konfiguracja pluginu dla backendu acpx
|
||||
|
||||
Świeże instalacje mają domyślnie włączony dołączony plugin runtime `acpx`, więc ACP
|
||||
zwykle działa bez ręcznej instalacji pluginu.
|
||||
Świeże instalacje są dostarczane z włączonym domyślnie dołączonym pluginem runtime `acpx`, więc ACP zwykle działa bez ręcznego kroku instalacji pluginu.
|
||||
|
||||
Zacznij od:
|
||||
|
||||
@ -692,13 +690,13 @@ openclaw plugins install acpx
|
||||
openclaw config set plugins.entries.acpx.enabled true
|
||||
```
|
||||
|
||||
Instalacja lokalnego workspace podczas developmentu:
|
||||
Lokalna instalacja obszaru roboczego podczas programowania:
|
||||
|
||||
```bash
|
||||
openclaw plugins install ./path/to/local/acpx-plugin
|
||||
```
|
||||
|
||||
Następnie zweryfikuj stan backendu:
|
||||
Następnie sprawdź stan backendu:
|
||||
|
||||
```text
|
||||
/acp doctor
|
||||
@ -706,14 +704,14 @@ Następnie zweryfikuj stan backendu:
|
||||
|
||||
### Konfiguracja polecenia i wersji acpx
|
||||
|
||||
Domyślnie dołączony plugin backendu acpx (`acpx`) używa lokalnego, przypiętego pliku binarnego pluginu:
|
||||
Domyślnie dołączony plugin backendu acpx (`acpx`) używa lokalnego dla pluginu przypiętego pliku binarnego:
|
||||
|
||||
1. Polecenie domyślnie wskazuje na lokalny dla pluginu `node_modules/.bin/acpx` wewnątrz pakietu pluginu ACPX.
|
||||
2. Oczekiwana wersja domyślnie odpowiada przypięciu rozszerzenia.
|
||||
3. Przy starcie backend ACP jest natychmiast rejestrowany jako not-ready.
|
||||
1. Polecenie domyślnie wskazuje lokalny dla pluginu `node_modules/.bin/acpx` wewnątrz pakietu pluginu ACPX.
|
||||
2. Oczekiwana wersja domyślnie jest zgodna z przypięciem rozszerzenia.
|
||||
3. Przy uruchomieniu ACP backend jest rejestrowany od razu jako niegotowy.
|
||||
4. Zadanie ensure w tle weryfikuje `acpx --version`.
|
||||
5. Jeśli lokalny plik binarny pluginu nie istnieje lub wersja się nie zgadza, uruchamia:
|
||||
`npm install --omit=dev --no-save acpx@<pinned>` i ponownie weryfikuje.
|
||||
5. Jeśli lokalny dla pluginu plik binarny jest nieobecny albo ma niezgodną wersję, uruchamiane jest:
|
||||
`npm install --omit=dev --no-save acpx@<pinned>` i następuje ponowna weryfikacja.
|
||||
|
||||
Możesz nadpisać polecenie/wersję w konfiguracji pluginu:
|
||||
|
||||
@ -735,25 +733,25 @@ Możesz nadpisać polecenie/wersję w konfiguracji pluginu:
|
||||
|
||||
Uwagi:
|
||||
|
||||
- `command` akceptuje ścieżkę bezwzględną, ścieżkę względną lub nazwę polecenia (`acpx`).
|
||||
- Ścieżki względne są rozwiązywane względem katalogu workspace OpenClaw.
|
||||
- `command` akceptuje ścieżkę bezwzględną, ścieżkę względną albo nazwę polecenia (`acpx`).
|
||||
- Ścieżki względne są rozwiązywane względem katalogu obszaru roboczego OpenClaw.
|
||||
- `expectedVersion: "any"` wyłącza ścisłe dopasowanie wersji.
|
||||
- Gdy `command` wskazuje niestandardowy plik binarny/ścieżkę, automatyczna instalacja lokalna pluginu jest wyłączona.
|
||||
- Uruchamianie OpenClaw pozostaje nieblokujące, gdy działa sprawdzanie stanu backendu w tle.
|
||||
- Gdy `command` wskazuje niestandardowy plik binarny/ścieżkę, automatyczna instalacja lokalna dla pluginu jest wyłączona.
|
||||
- Uruchamianie OpenClaw pozostaje nieblokujące podczas działania sprawdzania stanu backendu w tle.
|
||||
|
||||
Zobacz [Plugins](/pl/tools/plugin).
|
||||
|
||||
### Automatyczna instalacja zależności
|
||||
|
||||
Gdy instalujesz OpenClaw globalnie przez `npm install -g openclaw`, zależności runtime `acpx`
|
||||
(pliki binarne zależne od platformy) są instalowane automatycznie
|
||||
Gdy instalujesz OpenClaw globalnie przez `npm install -g openclaw`, zależności runtime acpx
|
||||
(binaria zależne od platformy) są instalowane automatycznie
|
||||
przez hook postinstall. Jeśli automatyczna instalacja się nie powiedzie, gateway nadal uruchamia się
|
||||
normalnie i raportuje brakującą zależność przez `openclaw acp doctor`.
|
||||
normalnie i zgłasza brakującą zależność przez `openclaw acp doctor`.
|
||||
|
||||
### Most MCP dla narzędzi pluginów
|
||||
|
||||
Domyślnie sesje ACPX **nie** udostępniają harnessowi ACP narzędzi
|
||||
zarejestrowanych przez pluginy OpenClaw.
|
||||
Domyślnie sesje ACPX **nie** udostępniają narzędzi rejestrowanych przez pluginy OpenClaw
|
||||
harness ACP.
|
||||
|
||||
Jeśli chcesz, aby agenci ACP, tacy jak Codex albo Claude Code, mogli wywoływać zainstalowane
|
||||
narzędzia pluginów OpenClaw, takie jak memory recall/store, włącz dedykowany most:
|
||||
@ -764,45 +762,58 @@ openclaw config set plugins.entries.acpx.config.pluginToolsMcpBridge true
|
||||
|
||||
Co to robi:
|
||||
|
||||
- Wstrzykuje w bootstrap sesji ACPX wbudowany serwer MCP o nazwie `openclaw-plugin-tools`.
|
||||
- Wstrzykuje wbudowany serwer MCP o nazwie `openclaw-plugin-tools` do bootstrapu sesji ACPX.
|
||||
- Udostępnia narzędzia pluginów już zarejestrowane przez zainstalowane i włączone pluginy OpenClaw.
|
||||
- Utrzymuje tę funkcję jako jawną i domyślnie wyłączoną.
|
||||
- Zachowuje tę funkcję jako jawną i domyślnie wyłączoną.
|
||||
|
||||
Uwagi dotyczące bezpieczeństwa i zaufania:
|
||||
|
||||
- To rozszerza powierzchnię narzędzi harnessu ACP.
|
||||
- To rozszerza powierzchnię narzędzi harness ACP.
|
||||
- Agenci ACP otrzymują dostęp tylko do narzędzi pluginów już aktywnych w gateway.
|
||||
- Traktuj to jako tę samą granicę zaufania co pozwolenie tym pluginom wykonywać się
|
||||
- Traktuj to jako tę samą granicę zaufania, co pozwolenie tym pluginom na wykonywanie działań
|
||||
w samym OpenClaw.
|
||||
- Przed włączeniem przejrzyj zainstalowane pluginy.
|
||||
- Przejrzyj zainstalowane pluginy przed włączeniem tej funkcji.
|
||||
|
||||
Niestandardowe `mcpServers` nadal działają jak wcześniej. Wbudowany most plugin-tools to
|
||||
dodatkowa, opcjonalna wygoda, a nie zamiennik ogólnej konfiguracji serwera MCP.
|
||||
Niestandardowe `mcpServers` nadal działają jak wcześniej. Wbudowany most narzędzi pluginów jest
|
||||
dodatkową wygodną funkcją opt-in, a nie zamiennikiem ogólnej konfiguracji serwera MCP.
|
||||
|
||||
### Konfiguracja limitu czasu runtime
|
||||
|
||||
Dołączony plugin `acpx` domyślnie ustawia 120-sekundowy
|
||||
limit czasu dla osadzonych tur runtime. Daje to wolniejszym harnesses, takim jak Gemini CLI, dość czasu na ukończenie
|
||||
uruchamiania i inicjalizacji ACP. Nadpisz tę wartość, jeśli host wymaga innego
|
||||
limitu runtime:
|
||||
|
||||
```bash
|
||||
openclaw config set plugins.entries.acpx.config.timeoutSeconds 180
|
||||
```
|
||||
|
||||
Uruchom ponownie gateway po zmianie tej wartości.
|
||||
|
||||
## Konfiguracja uprawnień
|
||||
|
||||
Sesje ACP działają nieinteraktywnie — nie ma TTY do zatwierdzania ani odrzucania promptów uprawnień zapisu plików i wykonywania poleceń powłoki. Plugin acpx dostarcza dwa klucze konfiguracji, które kontrolują obsługę uprawnień:
|
||||
Sesje ACP działają nieinteraktywnie — nie ma TTY do zatwierdzania ani odrzucania promptów uprawnień zapisu plików i wykonywania poleceń powłoki. Plugin acpx udostępnia dwa klucze konfiguracyjne kontrolujące sposób obsługi uprawnień:
|
||||
|
||||
Te uprawnienia harnessów ACPX są oddzielne od zatwierdzeń exec OpenClaw i oddzielne od flag omijania po stronie producenta backendów CLI, takich jak Claude CLI `--permission-mode bypassPermissions`. ACPX `approve-all` to awaryjny przełącznik na poziomie harnessu dla sesji ACP.
|
||||
Te uprawnienia harness ACPX są oddzielne od zatwierdzeń exec OpenClaw i oddzielne od flag obejścia dostawcy backendu CLI, takich jak Claude CLI `--permission-mode bypassPermissions`. ACPX `approve-all` jest przełącznikiem awaryjnym na poziomie harness dla sesji ACP.
|
||||
|
||||
### `permissionMode`
|
||||
|
||||
Kontroluje, które operacje agent harnessu może wykonywać bez promptu.
|
||||
Kontroluje, jakie operacje agent harness może wykonywać bez promptu.
|
||||
|
||||
| Wartość | Zachowanie |
|
||||
| --------------- | --------------------------------------------------------- |
|
||||
| `approve-all` | Automatycznie zatwierdza wszystkie zapisy plików i polecenia powłoki. |
|
||||
| `approve-reads` | Automatycznie zatwierdza tylko odczyty; zapisy i wykonanie wymagają promptów. |
|
||||
| `deny-all` | Odrzuca wszystkie prompty uprawnień. |
|
||||
| Wartość | Zachowanie |
|
||||
| --- | --- |
|
||||
| `approve-all` | Automatycznie zatwierdza wszystkie zapisy plików i polecenia powłoki. |
|
||||
| `approve-reads` | Automatycznie zatwierdza tylko odczyty; zapis i exec wymagają promptów. |
|
||||
| `deny-all` | Odrzuca wszystkie prompty uprawnień. |
|
||||
|
||||
### `nonInteractivePermissions`
|
||||
|
||||
Kontroluje, co dzieje się, gdy prompt uprawnień miałby zostać pokazany, ale interaktywny TTY nie jest dostępny (co zawsze dotyczy sesji ACP).
|
||||
Kontroluje, co dzieje się, gdy prompt uprawnień normalnie zostałby pokazany, ale nie ma dostępnego interaktywnego TTY (co zawsze ma miejsce w sesjach ACP).
|
||||
|
||||
| Wartość | Zachowanie |
|
||||
| ------ | ----------------------------------------------------------------- |
|
||||
| `fail` | Przerywa sesję z `AcpRuntimeError`. **(domyślnie)** |
|
||||
| `deny` | Po cichu odrzuca uprawnienie i kontynuuje (łagodna degradacja). |
|
||||
| Wartość | Zachowanie |
|
||||
| --- | --- |
|
||||
| `fail` | Przerywa sesję z `AcpRuntimeError`. **(domyślne)** |
|
||||
| `deny` | Cicho odrzuca uprawnienie i kontynuuje (łagodna degradacja). |
|
||||
|
||||
### Konfiguracja
|
||||
|
||||
@ -817,25 +828,25 @@ Uruchom ponownie gateway po zmianie tych wartości.
|
||||
|
||||
> **Ważne:** OpenClaw obecnie domyślnie używa `permissionMode=approve-reads` i `nonInteractivePermissions=fail`. W nieinteraktywnych sesjach ACP każdy zapis lub exec, który wywoła prompt uprawnień, może zakończyć się błędem `AcpRuntimeError: Permission prompt unavailable in non-interactive mode`.
|
||||
>
|
||||
> Jeśli musisz ograniczyć uprawnienia, ustaw `nonInteractivePermissions` na `deny`, aby sesje łagodnie degradowały się zamiast kończyć awarią.
|
||||
> Jeśli musisz ograniczyć uprawnienia, ustaw `nonInteractivePermissions` na `deny`, aby sesje ulegały łagodnej degradacji zamiast się wykrzaczać.
|
||||
|
||||
## Rozwiązywanie problemów
|
||||
|
||||
| Objaw | Prawdopodobna przyczyna | Poprawka |
|
||||
| --------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `ACP runtime backend is not configured` | Brak pluginu backendu lub jest wyłączony. | Zainstaluj i włącz plugin backendu, a następnie uruchom `/acp doctor`. |
|
||||
| `ACP is disabled by policy (acp.enabled=false)` | ACP jest globalnie wyłączone. | Ustaw `acp.enabled=true`. |
|
||||
| `ACP dispatch is disabled by policy (acp.dispatch.enabled=false)` | Dispatch z normalnych wiadomości w wątku jest wyłączony. | Ustaw `acp.dispatch.enabled=true`. |
|
||||
| `ACP agent "<id>" is not allowed by policy` | Agent nie znajduje się na allowliście. | Użyj dozwolonego `agentId` albo zaktualizuj `acp.allowedAgents`. |
|
||||
| `Unable to resolve session target: ...` | Błędny token key/id/label. | Uruchom `/acp sessions`, skopiuj dokładny key/label, spróbuj ponownie. |
|
||||
| `--bind here requires running /acp spawn inside an active ... conversation` | `--bind here` użyte bez aktywnej konwersacji, którą można powiązać. | Przejdź do docelowego czatu/kanału i spróbuj ponownie albo użyj uruchomienia bez powiązania. |
|
||||
| `Conversation bindings are unavailable for <channel>.` | Adapter nie ma możliwości powiązań ACP z bieżącą konwersacją. | Użyj `/acp spawn ... --thread ...` tam, gdzie jest obsługiwane, skonfiguruj wpisy najwyższego poziomu `bindings[]` albo przejdź na obsługiwany kanał. |
|
||||
| `--thread here requires running /acp spawn inside an active ... thread` | `--thread here` użyte poza kontekstem wątku. | Przejdź do docelowego wątku albo użyj `--thread auto`/`off`. |
|
||||
| `Only <user-id> can rebind this channel/conversation/thread.` | Inny użytkownik jest właścicielem aktywnego celu powiązania. | Powiąż ponownie jako właściciel albo użyj innej konwersacji lub wątku. |
|
||||
| `Thread bindings are unavailable for <channel>.` | Adapter nie ma możliwości powiązań wątków. | Użyj `--thread off` albo przejdź do obsługiwanego adaptera/kanału. |
|
||||
| `Sandboxed sessions cannot spawn ACP sessions ...` | Runtime ACP działa po stronie hosta; sesja żądająca jest sandboxowana. | Użyj `runtime="subagent"` z sesji sandboxowanych albo uruchom ACP z sesji bez sandboxa. |
|
||||
| `sessions_spawn sandbox="require" is unsupported for runtime="acp" ...` | Zażądano `sandbox="require"` dla runtime ACP. | Użyj `runtime="subagent"` dla wymaganego sandboxowania albo ACP z `sandbox="inherit"` z sesji bez sandboxa. |
|
||||
| Brak metadanych ACP dla powiązanej sesji | Nieaktualne/usunięte metadane sesji ACP. | Odtwórz przez `/acp spawn`, a następnie ponownie powiąż/skup wątek. |
|
||||
| `AcpRuntimeError: Permission prompt unavailable in non-interactive mode` | `permissionMode` blokuje zapis/exec w nieinteraktywnej sesji ACP. | Ustaw `plugins.entries.acpx.config.permissionMode` na `approve-all` i uruchom ponownie gateway. Zobacz [Konfiguracja uprawnień](#konfiguracja-uprawnień). |
|
||||
| Sesja ACP kończy się bardzo wcześnie z niewielką ilością danych wyjściowych | Prompty uprawnień są blokowane przez `permissionMode`/`nonInteractivePermissions`. | Sprawdź logi gateway pod kątem `AcpRuntimeError`. Dla pełnych uprawnień ustaw `permissionMode=approve-all`; dla łagodnej degradacji ustaw `nonInteractivePermissions=deny`. |
|
||||
| Sesja ACP zawiesza się bez końca po zakończeniu pracy | Proces harness zakończył się, ale sesja ACP nie zgłosiła zakończenia. | Monitoruj przez `ps aux \| grep acpx`; ręcznie zabij nieaktualne procesy. |
|
||||
| Objaw | Prawdopodobna przyczyna | Poprawka |
|
||||
| --- | --- | --- |
|
||||
| `ACP runtime backend is not configured` | Brak pluginu backendu albo jest wyłączony. | Zainstaluj i włącz plugin backendu, a następnie uruchom `/acp doctor`. |
|
||||
| `ACP is disabled by policy (acp.enabled=false)` | ACP jest globalnie wyłączone. | Ustaw `acp.enabled=true`. |
|
||||
| `ACP dispatch is disabled by policy (acp.dispatch.enabled=false)` | Dispatch z normalnych wiadomości w wątku jest wyłączony. | Ustaw `acp.dispatch.enabled=true`. |
|
||||
| `ACP agent "<id>" is not allowed by policy` | Agent nie znajduje się na liście dozwolonych. | Użyj dozwolonego `agentId` albo zaktualizuj `acp.allowedAgents`. |
|
||||
| `Unable to resolve session target: ...` | Nieprawidłowy token klucza/id/etykiety. | Uruchom `/acp sessions`, skopiuj dokładny klucz/etykietę i spróbuj ponownie. |
|
||||
| `--bind here requires running /acp spawn inside an active ... conversation` | `--bind here` zostało użyte bez aktywnej rozmowy, którą można powiązać. | Przejdź do docelowego czatu/kanału i spróbuj ponownie albo użyj uruchomienia bez powiązania. |
|
||||
| `Conversation bindings are unavailable for <channel>.` | Adapter nie ma możliwości powiązania ACP z bieżącą rozmową. | Użyj `/acp spawn ... --thread ...`, jeśli jest obsługiwane, skonfiguruj wpisy najwyższego poziomu `bindings[]` albo przejdź do obsługiwanego kanału. |
|
||||
| `--thread here requires running /acp spawn inside an active ... thread` | `--thread here` zostało użyte poza kontekstem wątku. | Przejdź do docelowego wątku albo użyj `--thread auto`/`off`. |
|
||||
| `Only <user-id> can rebind this channel/conversation/thread.` | Inny użytkownik jest właścicielem aktywnego celu powiązania. | Powiąż ponownie jako właściciel albo użyj innej rozmowy lub wątku. |
|
||||
| `Thread bindings are unavailable for <channel>.` | Adapter nie ma możliwości powiązania wątków. | Użyj `--thread off` albo przejdź do obsługiwanego adaptera/kanału. |
|
||||
| `Sandboxed sessions cannot spawn ACP sessions ...` | Runtime ACP działa po stronie hosta; sesja żądająca jest sandboxowana. | Użyj `runtime="subagent"` z sesji sandboxowanych albo uruchamiaj ACP z sesji niesandboxowanej. |
|
||||
| `sessions_spawn sandbox="require" is unsupported for runtime="acp" ...` | Zażądano `sandbox="require"` dla runtime ACP. | Użyj `runtime="subagent"` dla wymaganego sandboxowania albo użyj ACP z `sandbox="inherit"` z niesandboxowanej sesji. |
|
||||
| Brak metadanych ACP dla powiązanej sesji | Nieaktualne/usunięte metadane sesji ACP. | Odtwórz je przez `/acp spawn`, a następnie ponownie powiąż/ustaw fokus wątku. |
|
||||
| `AcpRuntimeError: Permission prompt unavailable in non-interactive mode` | `permissionMode` blokuje zapis/exec w nieinteraktywnej sesji ACP. | Ustaw `plugins.entries.acpx.config.permissionMode` na `approve-all` i uruchom ponownie gateway. Zobacz [Konfiguracja uprawnień](#konfiguracja-uprawnień). |
|
||||
| Sesja ACP kończy się niepowodzeniem wcześnie i daje mało danych wyjściowych | Prompty uprawnień są blokowane przez `permissionMode`/`nonInteractivePermissions`. | Sprawdź logi gateway pod kątem `AcpRuntimeError`. Dla pełnych uprawnień ustaw `permissionMode=approve-all`; dla łagodnej degradacji ustaw `nonInteractivePermissions=deny`. |
|
||||
| Sesja ACP zawiesza się bez końca po ukończeniu pracy | Proces harness zakończył się, ale sesja ACP nie zgłosiła ukończenia. | Monitoruj przez `ps aux \| grep acpx`; ręcznie zabij nieaktualne procesy. |
|
||||
|
||||
@ -1,70 +1,70 @@
|
||||
---
|
||||
read_when:
|
||||
- Konfigurowanie zatwierdzeń exec lub allowlist
|
||||
- Konfigurowanie zatwierdzeń exec lub list dozwolonych
|
||||
- Implementowanie UX zatwierdzeń exec w aplikacji macOS
|
||||
- Przegląd promptów wyjścia z sandboxa i ich konsekwencji
|
||||
summary: Zatwierdzenia exec, allowlisty i prompty wyjścia z sandboxa
|
||||
- Przeglądanie promptów wyjścia z sandboxa i ich konsekwencji
|
||||
summary: Zatwierdzenia exec, listy dozwolonych i prompty wyjścia z sandboxa
|
||||
title: Zatwierdzenia exec
|
||||
x-i18n:
|
||||
generated_at: "2026-04-06T03:14:33Z"
|
||||
generated_at: "2026-04-08T02:19:40Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 39e91cd5c7615bdb9a6b201a85bde7514327910f6f12da5a4b0532bceb229c22
|
||||
source_hash: 6041929185bab051ad873cc4822288cb7d6f0470e19e7ae7a16b70f76dfc2cd9
|
||||
source_path: tools/exec-approvals.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Zatwierdzenia exec
|
||||
|
||||
Zatwierdzenia exec to **zabezpieczenie aplikacji towarzyszącej / hosta node** umożliwiające uruchamianie przez sandboxowanego agenta
|
||||
poleceń na prawdziwym hoście (`gateway` lub `node`). Potraktuj to jak blokadę bezpieczeństwa:
|
||||
polecenia są dozwolone tylko wtedy, gdy zasada + allowlista + (opcjonalnie) zatwierdzenie użytkownika są zgodne.
|
||||
Zatwierdzenia exec działają **dodatkowo** względem polityki narzędzi i bramkowania elevated (chyba że elevated ma wartość `full`, co pomija zatwierdzenia).
|
||||
Skuteczna polityka jest **bardziej restrykcyjną** z `tools.exec.*` i domyślnych ustawień zatwierdzeń; jeśli pole zatwierdzeń zostanie pominięte, używana jest wartość z `tools.exec`.
|
||||
Host exec używa też lokalnego stanu zatwierdzeń na tej maszynie. Lokalna dla hosta
|
||||
wartość `ask: "always"` w `~/.openclaw/exec-approvals.json` będzie nadal wymuszać prompty, nawet jeśli
|
||||
Zatwierdzenia exec to **zabezpieczenie aplikacji towarzyszącej / hosta węzła** pozwalające agentowi działającemu w sandboxie uruchamiać
|
||||
polecenia na rzeczywistym hoście (`gateway` lub `node`). Potraktuj to jak blokadę bezpieczeństwa:
|
||||
polecenia są dozwolone tylko wtedy, gdy polityka + lista dozwolonych + (opcjonalne) zatwierdzenie użytkownika są zgodne.
|
||||
Zatwierdzenia exec są **dodatkiem** do polityki narzędzi i kontroli elevated (chyba że elevated jest ustawione na `full`, co pomija zatwierdzenia).
|
||||
Efektywna polityka jest **bardziej rygorystyczną** z `tools.exec.*` i domyślnych ustawień zatwierdzeń; jeśli pole zatwierdzeń zostanie pominięte, używana jest wartość `tools.exec`.
|
||||
Exec hosta używa również lokalnego stanu zatwierdzeń na tej maszynie. Lokalne dla hosta
|
||||
`ask: "always"` w `~/.openclaw/exec-approvals.json` nadal wyświetla prompty, nawet jeśli
|
||||
domyślne ustawienia sesji lub konfiguracji żądają `ask: "on-miss"`.
|
||||
Użyj `openclaw approvals get`, `openclaw approvals get --gateway` lub
|
||||
`openclaw approvals get --node <id|name|ip>`, aby sprawdzić żądaną politykę,
|
||||
źródła polityki hosta i wynik skuteczny.
|
||||
źródła polityki hosta i wynik efektywny.
|
||||
|
||||
Jeśli UI aplikacji towarzyszącej **nie jest dostępny**, każde żądanie wymagające promptu
|
||||
jest rozwiązywane przez **ask fallback** (domyślnie: deny).
|
||||
Jeśli interfejs aplikacji towarzyszącej **nie jest dostępny**, każde żądanie wymagające promptu jest
|
||||
rozstrzygane przez **ask fallback** (domyślnie: deny).
|
||||
|
||||
Natywni klienci zatwierdzeń na czacie mogą też udostępniać elementy interfejsu specyficzne dla kanału na
|
||||
wiadomości z oczekującym zatwierdzeniem. Na przykład Matrix może dodać skróty reakcji do
|
||||
promptu zatwierdzenia (`✅` pozwól raz, `❌` odmów i `♾️` zawsze pozwalaj, gdy dostępne),
|
||||
jednocześnie pozostawiając w wiadomości polecenia `/approve ...` jako fallback.
|
||||
Natywni klienci zatwierdzeń w czacie mogą również udostępniać specyficzne dla kanału elementy interakcji w
|
||||
wiadomości oczekującego zatwierdzenia. Na przykład Matrix może dodawać skróty reakcji do
|
||||
promptu zatwierdzenia (`✅` pozwól raz, `❌` odrzuć i `♾️` pozwól zawsze, gdy dostępne),
|
||||
jednocześnie pozostawiając polecenia `/approve ...` w wiadomości jako rozwiązanie zapasowe.
|
||||
|
||||
## Gdzie ma to zastosowanie
|
||||
## Gdzie to ma zastosowanie
|
||||
|
||||
Zatwierdzenia exec są egzekwowane lokalnie na hoście wykonawczym:
|
||||
Zatwierdzenia exec są egzekwowane lokalnie na hoście wykonania:
|
||||
|
||||
- **host gatewaya** → proces `openclaw` na maszynie gatewaya
|
||||
- **host node** → runner node (aplikacja towarzysząca macOS lub bezgłowy host node)
|
||||
- **host gateway** → proces `openclaw` na maszynie gateway
|
||||
- **host node** → runner węzła (aplikacja towarzysząca macOS lub bezgłowy host węzła)
|
||||
|
||||
Uwaga o modelu zaufania:
|
||||
Uwaga dotycząca modelu zaufania:
|
||||
|
||||
- Wywołujący uwierzytelnieni przez Gateway są zaufanymi operatorami tego Gatewaya.
|
||||
- Sparowane nody rozszerzają tę zdolność zaufanego operatora na host node.
|
||||
- Zatwierdzenia exec zmniejszają ryzyko przypadkowego wykonania, ale nie stanowią granicy auth per użytkownik.
|
||||
- Wywołujący uwierzytelnieni przez Gateway są zaufanymi operatorami dla tego Gateway.
|
||||
- Sparowane węzły rozszerzają tę zdolność zaufanego operatora na host node.
|
||||
- Zatwierdzenia exec zmniejszają ryzyko przypadkowego wykonania, ale nie są granicą uwierzytelniania per użytkownik.
|
||||
- Zatwierdzone uruchomienia na hoście node wiążą kanoniczny kontekst wykonania: kanoniczne cwd, dokładne argv, powiązanie env
|
||||
gdy występuje oraz przypiętą ścieżkę wykonywalną, gdy ma to zastosowanie.
|
||||
- Dla skryptów powłoki i bezpośrednich wywołań plików interpreterów/runtime OpenClaw próbuje również powiązać
|
||||
jeden konkretny lokalny operand plikowy. Jeśli ten powiązany plik zmieni się po zatwierdzeniu, ale przed wykonaniem,
|
||||
uruchomienie zostanie odrzucone zamiast wykonywać zmienioną treść.
|
||||
- To powiązanie pliku jest celowo wykonywane w trybie best-effort, a nie jako kompletny model semantyczny dla każdej
|
||||
ścieżki ładowania interpretera/runtime. Jeśli tryb zatwierdzania nie może zidentyfikować dokładnie jednego konkretnego lokalnego
|
||||
gdy występuje oraz przypiętą ścieżkę do pliku wykonywalnego, gdy ma to zastosowanie.
|
||||
- Dla skryptów powłoki i bezpośrednich wywołań plików interpreterów/runtime OpenClaw również próbuje powiązać
|
||||
jeden konkretny lokalny operand pliku. Jeśli ten powiązany plik zmieni się po zatwierdzeniu, ale przed wykonaniem,
|
||||
uruchomienie zostanie odrzucone zamiast wykonać zmienioną treść.
|
||||
- To powiązanie pliku jest celowo realizowane według zasady best-effort, a nie jako pełny model semantyczny każdego
|
||||
interpretera/runtime i ścieżki ładowania. Jeśli tryb zatwierdzania nie potrafi zidentyfikować dokładnie jednego konkretnego lokalnego
|
||||
pliku do powiązania, odmawia wygenerowania uruchomienia opartego na zatwierdzeniu zamiast udawać pełne pokrycie.
|
||||
|
||||
Podział na macOS:
|
||||
|
||||
- **usługa hosta node** przekazuje `system.run` do **aplikacji macOS** przez lokalne IPC.
|
||||
- **aplikacja macOS** egzekwuje zatwierdzenia + wykonuje polecenie w kontekście UI.
|
||||
- **aplikacja macOS** egzekwuje zatwierdzenia i wykonuje polecenie w kontekście UI.
|
||||
|
||||
## Ustawienia i przechowywanie
|
||||
|
||||
Zatwierdzenia znajdują się w lokalnym pliku JSON na hoście wykonawczym:
|
||||
Zatwierdzenia są przechowywane w lokalnym pliku JSON na hoście wykonania:
|
||||
|
||||
`~/.openclaw/exec-approvals.json`
|
||||
|
||||
@ -103,14 +103,14 @@ Przykładowy schemat:
|
||||
}
|
||||
```
|
||||
|
||||
## Tryb bez zatwierdzeń „YOLO”
|
||||
## Tryb „YOLO” bez zatwierdzeń
|
||||
|
||||
Jeśli chcesz, aby host exec działał bez promptów zatwierdzania, musisz otworzyć **obie** warstwy polityki:
|
||||
Jeśli chcesz, aby exec hosta działał bez promptów zatwierdzania, musisz otworzyć **obie** warstwy polityki:
|
||||
|
||||
- żądaną politykę exec w konfiguracji OpenClaw (`tools.exec.*`)
|
||||
- lokalną politykę zatwierdzeń hosta w `~/.openclaw/exec-approvals.json`
|
||||
- lokalną dla hosta politykę zatwierdzeń w `~/.openclaw/exec-approvals.json`
|
||||
|
||||
To jest teraz domyślne zachowanie hosta, chyba że jawnie je zaostrzysz:
|
||||
Jest to teraz domyślne zachowanie hosta, chyba że jawnie je zaostrzysz:
|
||||
|
||||
- `tools.exec.security`: `full` na `gateway`/`node`
|
||||
- `tools.exec.ask`: `off`
|
||||
@ -118,15 +118,15 @@ To jest teraz domyślne zachowanie hosta, chyba że jawnie je zaostrzysz:
|
||||
|
||||
Ważne rozróżnienie:
|
||||
|
||||
- `tools.exec.host=auto` wybiera miejsce wykonania exec: sandbox, jeśli dostępny, w przeciwnym razie gateway.
|
||||
- YOLO wybiera sposób zatwierdzania host exec: `security=full` plus `ask=off`.
|
||||
- W trybie YOLO OpenClaw nie dodaje osobnej heurystycznej bramki zatwierdzenia zaciemniania poleceń ponad skonfigurowaną politykę host exec.
|
||||
- `auto` nie sprawia, że routing do gatewaya staje się darmowym nadpisaniem z sesji sandboxowanej. Żądanie per wywołanie `host=node` jest dozwolone z `auto`, a `host=gateway` jest dozwolone z `auto` tylko wtedy, gdy żaden runtime sandboxa nie jest aktywny. Jeśli chcesz stabilną domyślną wartość inną niż auto, ustaw `tools.exec.host` albo użyj jawnie `/exec host=...`.
|
||||
- `tools.exec.host=auto` wybiera miejsce uruchomienia exec: sandbox, jeśli dostępny, w przeciwnym razie gateway.
|
||||
- YOLO wybiera sposób zatwierdzania exec hosta: `security=full` plus `ask=off`.
|
||||
- W trybie YOLO OpenClaw nie dodaje osobnej heurystycznej bramki zatwierdzeń dla maskowania poleceń ponad skonfigurowaną politykę exec hosta.
|
||||
- `auto` nie sprawia, że routing do gateway staje się darmowym obejściem z sesji działającej w sandboxie. Żądanie per wywołanie `host=node` jest dozwolone z `auto`, a `host=gateway` jest dozwolone z `auto` tylko wtedy, gdy nie jest aktywne środowisko sandbox. Jeśli chcesz stabilnej domyślnej wartości innej niż auto, ustaw `tools.exec.host` lub użyj jawnie `/exec host=...`.
|
||||
|
||||
Jeśli chcesz bardziej zachowawczej konfiguracji, zaostrz z powrotem którąkolwiek warstwę do `allowlist` / `on-miss`
|
||||
albo `deny`.
|
||||
Jeśli chcesz bardziej konserwatywnej konfiguracji, zaostrz z powrotem dowolną warstwę do `allowlist` / `on-miss`
|
||||
lub `deny`.
|
||||
|
||||
Trwała konfiguracja „nigdy nie pytaj” dla hosta gatewaya:
|
||||
Trwała konfiguracja hosta gateway „nigdy nie pytaj”:
|
||||
|
||||
```bash
|
||||
openclaw config set tools.exec.host gateway
|
||||
@ -150,7 +150,7 @@ openclaw approvals set --stdin <<'EOF'
|
||||
EOF
|
||||
```
|
||||
|
||||
Dla hosta node zastosuj zamiast tego ten sam plik zatwierdzeń na tym nodzie:
|
||||
Dla hosta node zastosuj zamiast tego ten sam plik zatwierdzeń na tym węźle:
|
||||
|
||||
```bash
|
||||
openclaw approvals set --node <id|name|ip> --stdin <<'EOF'
|
||||
@ -168,36 +168,36 @@ EOF
|
||||
Skrót tylko dla sesji:
|
||||
|
||||
- `/exec security=full ask=off` zmienia tylko bieżącą sesję.
|
||||
- `/elevated full` to skrót break-glass, który również pomija zatwierdzenia exec dla tej sesji.
|
||||
- `/elevated full` to skrót awaryjny, który również pomija zatwierdzenia exec dla tej sesji.
|
||||
|
||||
Jeśli plik zatwierdzeń hosta pozostaje bardziej restrykcyjny niż konfiguracja, nadal wygrywa bardziej restrykcyjna polityka hosta.
|
||||
Jeśli plik zatwierdzeń hosta pozostaje bardziej rygorystyczny niż konfiguracja, nadal wygrywa bardziej rygorystyczna polityka hosta.
|
||||
|
||||
## Pokrętła polityki
|
||||
## Przełączniki polityki
|
||||
|
||||
### Security (`exec.security`)
|
||||
|
||||
- **deny**: blokuje wszystkie żądania host exec.
|
||||
- **allowlist**: pozwala tylko na polecenia z allowlisty.
|
||||
- **full**: pozwala na wszystko (równoważne elevated).
|
||||
- **deny**: zablokuj wszystkie żądania exec hosta.
|
||||
- **allowlist**: zezwalaj tylko na polecenia z listy dozwolonych.
|
||||
- **full**: zezwalaj na wszystko (odpowiednik elevated).
|
||||
|
||||
### Ask (`exec.ask`)
|
||||
|
||||
- **off**: nigdy nie pytaj.
|
||||
- **on-miss**: pytaj tylko wtedy, gdy allowlista nie pasuje.
|
||||
- **always**: pytaj przy każdym poleceniu.
|
||||
- trwałe zaufanie `allow-always` nie tłumi promptów, gdy skuteczny tryb ask to `always`
|
||||
- **off**: nigdy nie wyświetlaj promptu.
|
||||
- **on-miss**: wyświetl prompt tylko wtedy, gdy lista dozwolonych nie pasuje.
|
||||
- **always**: wyświetlaj prompt dla każdego polecenia.
|
||||
- trwałe zaufanie `allow-always` nie tłumi promptów, gdy efektywny tryb ask to `always`
|
||||
|
||||
### Ask fallback (`askFallback`)
|
||||
|
||||
Jeśli prompt jest wymagany, ale żadne UI nie jest osiągalne, fallback decyduje:
|
||||
Jeśli prompt jest wymagany, ale żaden UI nie jest osiągalny, fallback decyduje:
|
||||
|
||||
- **deny**: blokuj.
|
||||
- **allowlist**: pozwól tylko, jeśli allowlista pasuje.
|
||||
- **full**: pozwól.
|
||||
- **allowlist**: zezwalaj tylko wtedy, gdy lista dozwolonych pasuje.
|
||||
- **full**: zezwalaj.
|
||||
|
||||
### Wzmacnianie inline interpreter eval (`tools.exec.strictInlineEval`)
|
||||
### Wzmocnienie eval inline dla interpreterów (`tools.exec.strictInlineEval`)
|
||||
|
||||
Gdy `tools.exec.strictInlineEval=true`, OpenClaw traktuje formy inline code-eval jako wymagające zatwierdzenia, nawet jeśli sama binarka interpretera jest na allowliście.
|
||||
Gdy `tools.exec.strictInlineEval=true`, OpenClaw traktuje formy eval kodu inline jako wymagające zatwierdzenia, nawet jeśli sam plik wykonywalny interpretera znajduje się na liście dozwolonych.
|
||||
|
||||
Przykłady:
|
||||
|
||||
@ -209,18 +209,18 @@ Przykłady:
|
||||
- `lua -e`
|
||||
- `osascript -e`
|
||||
|
||||
To defense-in-depth dla loaderów interpreterów, które nie mapują się czysto do jednego stabilnego operandu plikowego. W trybie ścisłym:
|
||||
To obrona warstwowa dla loaderów interpreterów, które nie mapują się czysto do jednego stabilnego operandu pliku. W trybie ścisłym:
|
||||
|
||||
- te polecenia nadal wymagają jawnego zatwierdzenia;
|
||||
- `allow-always` nie zapisuje dla nich automatycznie nowych wpisów allowlisty.
|
||||
- `allow-always` nie zapisuje automatycznie dla nich nowych wpisów listy dozwolonych.
|
||||
|
||||
## Allowlista (per agent)
|
||||
## Allowlist (per agent)
|
||||
|
||||
Allowlisty są **per agent**. Jeśli istnieje wielu agentów, przełącz agenta, którego
|
||||
edytujesz, w aplikacji macOS. Wzorce to **dopasowania glob bez rozróżniania wielkości liter**.
|
||||
Wzorce powinny rozwiązywać się do **ścieżek binarek** (wpisy tylko z basename są ignorowane).
|
||||
Starsze wpisy `agents.default` są migrowane do `agents.main` przy ładowaniu.
|
||||
Łańcuchy powłoki takie jak `echo ok && pwd` nadal wymagają, aby każdy segment najwyższego poziomu spełniał reguły allowlisty.
|
||||
Listy dozwolonych są **per agent**. Jeśli istnieje wielu agentów, przełącz, którego agenta
|
||||
edytujesz w aplikacji macOS. Wzorce są **niezależnymi od wielkości liter dopasowaniami glob**.
|
||||
Wzorce powinny rozwiązywać się do **ścieżek plików wykonywalnych** (wpisy zawierające tylko basename są ignorowane).
|
||||
Starsze wpisy `agents.default` są migrowane do `agents.main` podczas ładowania.
|
||||
Łańcuchy powłoki, takie jak `echo ok && pwd`, nadal wymagają, aby każdy segment najwyższego poziomu spełniał reguły listy dozwolonych.
|
||||
|
||||
Przykłady:
|
||||
|
||||
@ -228,43 +228,43 @@ Przykłady:
|
||||
- `~/.local/bin/*`
|
||||
- `/opt/homebrew/bin/rg`
|
||||
|
||||
Każdy wpis allowlisty śledzi:
|
||||
Każdy wpis listy dozwolonych śledzi:
|
||||
|
||||
- **id** stabilny UUID używany do tożsamości w UI (opcjonalny)
|
||||
- **id** stabilny UUID używany jako tożsamość w UI (opcjonalnie)
|
||||
- **last used** znacznik czasu
|
||||
- **last used command**
|
||||
- **last resolved path**
|
||||
|
||||
## Auto-allow Skills CLI
|
||||
## Auto-allow skill CLIs
|
||||
|
||||
Gdy włączone jest **Auto-allow Skills CLI**, pliki wykonywalne wskazane przez znane Skills
|
||||
są traktowane jako znajdujące się na allowliście na nodach (macOS node lub bezgłowy host node). Wykorzystuje to
|
||||
`skills.bins` przez Gateway RPC do pobrania listy binarek skilli. Wyłącz to, jeśli chcesz ścisłych ręcznych allowlist.
|
||||
Gdy **Auto-allow skill CLIs** jest włączone, pliki wykonywalne wskazywane przez znane Skills
|
||||
są traktowane jako wpisy listy dozwolonych na węzłach (węzeł macOS lub bezgłowy host węzła). Używa to
|
||||
`skills.bins` przez Gateway RPC do pobrania listy plików binarnych skill. Wyłącz to, jeśli chcesz rygorystycznych ręcznych list dozwolonych.
|
||||
|
||||
Ważne uwagi dotyczące zaufania:
|
||||
|
||||
- To **niejawna wygodna allowlista**, oddzielona od ręcznych wpisów allowlisty ścieżek.
|
||||
- To **niejawna wygodna lista dozwolonych**, oddzielna od ręcznych wpisów listy dozwolonych opartych na ścieżkach.
|
||||
- Jest przeznaczona dla zaufanych środowisk operatora, w których Gateway i node znajdują się w tej samej granicy zaufania.
|
||||
- Jeśli wymagasz ścisłego jawnego zaufania, pozostaw `autoAllowSkills: false` i używaj wyłącznie ręcznych wpisów allowlisty ścieżek.
|
||||
- Jeśli potrzebujesz rygorystycznego jawnego zaufania, pozostaw `autoAllowSkills: false` i używaj tylko ręcznych wpisów listy dozwolonych opartych na ścieżkach.
|
||||
|
||||
## Safe bins (tylko stdin)
|
||||
|
||||
`tools.exec.safeBins` definiuje małą listę binarek **tylko stdin** (na przykład `cut`),
|
||||
które mogą działać w trybie allowlisty **bez** jawnych wpisów allowlisty. Safe bins odrzucają
|
||||
pozycyjne argumenty plikowe i tokeny podobne do ścieżek, więc mogą działać tylko na strumieniu wejściowym.
|
||||
Traktuj to jako wąską szybką ścieżkę dla filtrów strumieniowych, a nie ogólną listę zaufania.
|
||||
**Nie** dodawaj binarek interpreterów ani runtime (na przykład `python3`, `node`, `ruby`, `bash`, `sh`, `zsh`) do `safeBins`.
|
||||
Jeśli polecenie może z założenia wykonywać kod, uruchamiać podpolecenia lub odczytywać pliki, preferuj jawne wpisy allowlisty i pozostaw włączone prompty zatwierdzeń.
|
||||
`tools.exec.safeBins` definiuje małą listę plików binarnych **tylko stdin** (na przykład `cut`),
|
||||
które mogą działać w trybie allowlist **bez** jawnych wpisów listy dozwolonych. Safe bins odrzucają
|
||||
pozycyjne argumenty plików i tokeny podobne do ścieżek, więc mogą działać tylko na przychodzącym strumieniu.
|
||||
Traktuj to jako wąską szybką ścieżkę dla filtrów strumieni, a nie ogólną listę zaufania.
|
||||
**Nie** dodawaj interpreterów ani plików binarnych runtime (na przykład `python3`, `node`, `ruby`, `bash`, `sh`, `zsh`) do `safeBins`.
|
||||
Jeśli polecenie potrafi wykonywać eval kodu, uruchamiać podpolecenia lub z założenia czytać pliki, preferuj jawne wpisy listy dozwolonych i pozostaw włączone prompty zatwierdzeń.
|
||||
Niestandardowe safe bins muszą definiować jawny profil w `tools.exec.safeBinProfiles.<bin>`.
|
||||
Walidacja jest deterministyczna wyłącznie na podstawie kształtu argv (bez sprawdzania istnienia systemu plików hosta), co
|
||||
zapobiega zachowaniu typu oracle istnienia pliku wynikającemu z różnic allow/deny.
|
||||
zapobiega zachowaniu typu oracle istnienia plików wynikającemu z różnic allow/deny.
|
||||
Opcje zorientowane na pliki są odrzucane dla domyślnych safe bins (na przykład `sort -o`, `sort --output`,
|
||||
`sort --files0-from`, `sort --compress-program`, `sort --random-source`,
|
||||
`sort --temporary-directory`/`-T`, `wc --files0-from`, `jq -f/--from-file`,
|
||||
`grep -f/--file`).
|
||||
Safe bins wymuszają również jawne zasady flag per binarka dla opcji, które łamią zachowanie tylko stdin
|
||||
(na przykład `sort -o/--output/--compress-program` i flagi rekurencyjne grep).
|
||||
Długie opcje są walidowane w trybie fail-closed w safe-bin mode: nieznane flagi i niejednoznaczne
|
||||
Safe bins egzekwują również jawne polityki flag per plik binarny dla opcji, które łamią zachowanie wyłącznie stdin
|
||||
(na przykład `sort -o/--output/--compress-program` i rekursywne flagi grep).
|
||||
Długie opcje są walidowane w trybie fail-closed w trybie safe-bin: nieznane flagi i niejednoznaczne
|
||||
skróty są odrzucane.
|
||||
Odrzucane flagi według profilu safe-bin:
|
||||
|
||||
@ -277,31 +277,31 @@ Odrzucane flagi według profilu safe-bin:
|
||||
|
||||
[//]: # "SAFE_BIN_DENIED_FLAGS:END"
|
||||
|
||||
Safe bins wymuszają również traktowanie tokenów argv jako **dosłowny tekst** w czasie wykonania (bez globbing
|
||||
i bez rozwijania `$VARS`) dla segmentów tylko stdin, więc wzorce takie jak `*` lub `$HOME/...` nie mogą być
|
||||
użyte do przemycania odczytów plików.
|
||||
Safe bins muszą także rozwiązywać się z zaufanych katalogów binarek (domyślne katalogi systemowe plus opcjonalne
|
||||
Safe bins wymuszają również traktowanie tokenów argv jako **dosłownego tekstu** podczas wykonywania (bez globbingu
|
||||
i bez rozwijania `$VARS`) dla segmentów tylko stdin, więc wzorce takie jak `*` lub `$HOME/...` nie mogą zostać
|
||||
użyte do przemycenia odczytu plików.
|
||||
Safe bins muszą również rozwiązywać się z zaufanych katalogów plików binarnych (domyślne katalogi systemowe plus opcjonalne
|
||||
`tools.exec.safeBinTrustedDirs`). Wpisy `PATH` nigdy nie są automatycznie zaufane.
|
||||
Domyślne zaufane katalogi safe-bin są celowo minimalne: `/bin`, `/usr/bin`.
|
||||
Jeśli Twój plik wykonywalny safe-bin znajduje się w ścieżkach menedżera pakietów/użytkownika (na przykład
|
||||
`/opt/homebrew/bin`, `/usr/local/bin`, `/opt/local/bin`, `/snap/bin`), dodaj je jawnie
|
||||
do `tools.exec.safeBinTrustedDirs`.
|
||||
Łańcuchy powłoki i przekierowania nie są automatycznie dozwolone w trybie allowlisty.
|
||||
Łączenie poleceń powłoki i przekierowania nie są automatycznie dozwolone w trybie allowlist.
|
||||
|
||||
Łańcuchy powłoki (`&&`, `||`, `;`) są dozwolone, gdy każdy segment najwyższego poziomu spełnia allowlistę
|
||||
(w tym safe bins lub skill auto-allow). Przekierowania nadal nie są obsługiwane w trybie allowlisty.
|
||||
Podstawianie poleceń (`$()` / backticks) jest odrzucane podczas parsowania allowlisty, także wewnątrz
|
||||
podwójnych cudzysłowów; użyj pojedynczych cudzysłowów, jeśli potrzebujesz dosłownego tekstu `$()`.
|
||||
W zatwierdzeniach aplikacji towarzyszącej macOS surowy tekst powłoki zawierający składnię kontroli lub rozwijania powłoki
|
||||
(`&&`, `||`, `;`, `|`, `` ` ``, `$`, `<`, `>`, `(`, `)`) jest traktowany jako nietrafienie allowlisty, chyba że
|
||||
sama binarka powłoki znajduje się na allowliście.
|
||||
Dla wrapperów powłoki (`bash|sh|zsh ... -c/-lc`) nadpisania env o zakresie żądania są redukowane do małej jawnej
|
||||
allowlisty (`TERM`, `LANG`, `LC_*`, `COLORTERM`, `NO_COLOR`, `FORCE_COLOR`).
|
||||
Dla decyzji allow-always w trybie allowlisty znane wrappery dispatch
|
||||
(`env`, `nice`, `nohup`, `stdbuf`, `timeout`) zapisują wewnętrzne ścieżki wykonywalne zamiast ścieżek wrapperów. Multipleksery powłoki (`busybox`, `toybox`) są również rozpakowywane dla apletów powłoki (`sh`, `ash`,
|
||||
itd.), tak aby zapisywane były wewnętrzne pliki wykonywalne zamiast binarek multipleksera. Jeśli wrapper lub
|
||||
multiplekser nie może zostać bezpiecznie rozpakowany, żaden wpis allowlisty nie jest zapisywany automatycznie.
|
||||
Jeśli umieszczasz na allowliście interpretery takie jak `python3` lub `node`, preferuj `tools.exec.strictInlineEval=true`, aby inline eval nadal wymagał jawnego zatwierdzenia. W trybie ścisłym `allow-always` nadal może zapisywać nieszkodliwe wywołania interpreterów/skryptów, ale nośniki inline-eval nie są zapisywane automatycznie.
|
||||
Łączenie poleceń powłoki (`&&`, `||`, `;`) jest dozwolone, gdy każdy segment najwyższego poziomu spełnia zasady listy dozwolonych
|
||||
(w tym safe bins lub auto-allow skill). Przekierowania nadal nie są obsługiwane w trybie allowlist.
|
||||
Podstawianie poleceń (`$()` / backticks) jest odrzucane podczas parsowania allowlist, również wewnątrz
|
||||
cudzysłowów; użyj pojedynczych cudzysłowów, jeśli potrzebujesz dosłownego tekstu `$()`.
|
||||
W zatwierdzeniach aplikacji towarzyszącej macOS surowy tekst powłoki zawierający składnię sterowania lub rozwijania powłoki
|
||||
(`&&`, `||`, `;`, `|`, `` ` ``, `$`, `<`, `>`, `(`, `)`) jest traktowany jako brak dopasowania listy dozwolonych, chyba że
|
||||
sam plik binarny powłoki znajduje się na liście dozwolonych.
|
||||
Dla wrapperów powłoki (`bash|sh|zsh ... -c/-lc`) nadpisania env ograniczone do zakresu żądania są redukowane do
|
||||
małej jawnej listy dozwolonych (`TERM`, `LANG`, `LC_*`, `COLORTERM`, `NO_COLOR`, `FORCE_COLOR`).
|
||||
Dla decyzji allow-always w trybie allowlist znane wrappery dispatch
|
||||
(`env`, `nice`, `nohup`, `stdbuf`, `timeout`) utrwalają ścieżki wewnętrznych plików wykonywalnych zamiast ścieżek wrapperów. Multipleksery powłoki (`busybox`, `toybox`) są również odpakowywane dla apletów powłoki (`sh`, `ash`,
|
||||
itd.), tak aby utrwalane były ścieżki wewnętrznych plików wykonywalnych zamiast plików binarnych multipleksera. Jeśli wrapper lub
|
||||
multiplekser nie może zostać bezpiecznie odpakowany, żaden wpis listy dozwolonych nie jest utrwalany automatycznie.
|
||||
Jeśli dodajesz do listy dozwolonych interpretery takie jak `python3` lub `node`, preferuj `tools.exec.strictInlineEval=true`, aby eval inline nadal wymagał jawnego zatwierdzenia. W trybie ścisłym `allow-always` może nadal utrwalać niegroźne wywołania interpreterów/skryptów, ale nośniki eval inline nie są utrwalane automatycznie.
|
||||
|
||||
Domyślne safe bins:
|
||||
|
||||
@ -311,49 +311,49 @@ Domyślne safe bins:
|
||||
|
||||
[//]: # "SAFE_BIN_DEFAULTS:END"
|
||||
|
||||
`grep` i `sort` nie znajdują się na liście domyślnej. Jeśli jawnie je włączysz, zachowaj jawne wpisy allowlisty dla
|
||||
`grep` i `sort` nie znajdują się na liście domyślnej. Jeśli jawnie je włączysz, zachowaj jawne wpisy listy dozwolonych dla
|
||||
ich przepływów pracy innych niż stdin.
|
||||
Dla `grep` w safe-bin mode podawaj wzorzec przez `-e`/`--regexp`; forma wzorca pozycyjnego jest
|
||||
odrzucana, aby nie dało się przemycić operandów plikowych jako niejednoznacznych pozycji.
|
||||
Dla `grep` w trybie safe-bin podawaj wzorzec za pomocą `-e`/`--regexp`; forma wzorca pozycyjnego jest
|
||||
odrzucana, aby operandy plików nie mogły zostać przemycone jako niejednoznaczne argumenty pozycyjne.
|
||||
|
||||
### Safe bins a allowlista
|
||||
### Safe bins versus allowlist
|
||||
|
||||
| Topic | `tools.exec.safeBins` | Allowlist (`exec-approvals.json`) |
|
||||
| Temat | `tools.exec.safeBins` | Allowlist (`exec-approvals.json`) |
|
||||
| ---------------- | ------------------------------------------------------ | ------------------------------------------------------------ |
|
||||
| Goal | Automatyczne zezwalanie na wąskie filtry stdin | Jawne zaufanie do określonych plików wykonywalnych |
|
||||
| Match type | Nazwa pliku wykonywalnego + zasada argv safe-bin | Wzorzec glob rozwiązanej ścieżki pliku wykonywalnego |
|
||||
| Argument scope | Ograniczany przez profil safe-bin i zasady tokenów dosłownych | Tylko dopasowanie ścieżki; argumenty są poza tym Twoją odpowiedzialnością |
|
||||
| Typical examples | `head`, `tail`, `tr`, `wc` | `jq`, `python3`, `node`, `ffmpeg`, niestandardowe CLI |
|
||||
| Best use | Niskiego ryzyka przekształcenia tekstu w pipeline | Dowolne narzędzie o szerszym zachowaniu lub efektach ubocznych |
|
||||
| Cel | Automatyczne zezwalanie na wąskie filtry stdin | Jawne zaufanie określonym plikom wykonywalnym |
|
||||
| Typ dopasowania | Nazwa pliku wykonywalnego + polityka argv safe-bin | Wzorzec glob rozwiązanego do ścieżki pliku wykonywalnego |
|
||||
| Zakres argumentów| Ograniczony profilem safe-bin i regułami tokenów dosłownych | Tylko dopasowanie ścieżki; odpowiedzialność za argumenty spoczywa poza tym na Tobie |
|
||||
| Typowe przykłady | `head`, `tail`, `tr`, `wc` | `jq`, `python3`, `node`, `ffmpeg`, niestandardowe CLI |
|
||||
| Najlepsze użycie | Niskiego ryzyka transformacje tekstu w pipeline’ach | Każde narzędzie o szerszym zachowaniu lub skutkach ubocznych |
|
||||
|
||||
Lokalizacja konfiguracji:
|
||||
|
||||
- `safeBins` pochodzi z konfiguracji (`tools.exec.safeBins` lub per agent `agents.list[].tools.exec.safeBins`).
|
||||
- `safeBinTrustedDirs` pochodzi z konfiguracji (`tools.exec.safeBinTrustedDirs` lub per agent `agents.list[].tools.exec.safeBinTrustedDirs`).
|
||||
- `safeBinProfiles` pochodzi z konfiguracji (`tools.exec.safeBinProfiles` lub per agent `agents.list[].tools.exec.safeBinProfiles`). Klucze profili per agent nadpisują klucze globalne.
|
||||
- wpisy allowlisty znajdują się w lokalnym dla hosta `~/.openclaw/exec-approvals.json` pod `agents.<id>.allowlist` (lub przez Control UI / `openclaw approvals allowlist ...`).
|
||||
- `openclaw security audit` ostrzega przez `tools.exec.safe_bins_interpreter_unprofiled`, gdy binarki interpreterów/runtime pojawiają się w `safeBins` bez jawnych profili.
|
||||
- `openclaw doctor --fix` może utworzyć szkielety brakujących wpisów `safeBinProfiles.<bin>` jako `{}` (po tym przejrzyj i zaostrz). Binarki interpreterów/runtime nie są tworzone automatycznie.
|
||||
- wpisy listy dozwolonych znajdują się w lokalnym dla hosta `~/.openclaw/exec-approvals.json` pod `agents.<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.
|
||||
|
||||
Przykład niestandardowego profilu:
|
||||
__OC_I18N_900004__
|
||||
Jeśli jawnie dodasz `jq` do `safeBins`, OpenClaw nadal odrzuci builtin `env` w safe-bin
|
||||
mode, aby `jq -n env` nie mogło zrzucić środowiska procesu hosta bez jawnej ścieżki allowlisty
|
||||
Jeśli jawnie dodasz `jq` do `safeBins`, OpenClaw nadal odrzuca builtin `env` w trybie safe-bin,
|
||||
więc `jq -n env` nie może zrzucić środowiska procesu hosta bez jawnej ścieżki z listy dozwolonych
|
||||
lub promptu zatwierdzenia.
|
||||
|
||||
## Edycja w Control UI
|
||||
|
||||
Użyj karty **Control UI → Nodes → Exec approvals**, aby edytować wartości domyślne, nadpisania
|
||||
per agent i allowlisty. Wybierz zakres (Defaults lub agent), dostosuj politykę,
|
||||
dodaj/usuń wzorce allowlisty, a następnie kliknij **Save**. UI pokazuje metadane **last used**
|
||||
per agent i listy dozwolonych. Wybierz zakres (Defaults lub agent), dostosuj politykę,
|
||||
dodaj/usuń wzorce listy dozwolonych, a następnie kliknij **Save**. UI pokazuje metadane **last used**
|
||||
dla każdego wzorca, aby ułatwić utrzymanie porządku na liście.
|
||||
|
||||
Selektor celu wybiera **Gateway** (lokalne zatwierdzenia) albo **Node**. Nody
|
||||
muszą ogłaszać `system.execApprovals.get/set` (aplikacja macOS lub bezgłowy host node).
|
||||
Jeśli node nie ogłasza jeszcze zatwierdzeń exec, edytuj jego lokalny
|
||||
`~/.openclaw/exec-approvals.json` bezpośrednio.
|
||||
Selektor celu wybiera **Gateway** (lokalne zatwierdzenia) lub **Node**. Węzły
|
||||
muszą ogłaszać `system.execApprovals.get/set` (aplikacja macOS lub bezgłowy host węzła).
|
||||
Jeśli węzeł nie ogłasza jeszcze zatwierdzeń exec, edytuj bezpośrednio jego lokalny
|
||||
`~/.openclaw/exec-approvals.json`.
|
||||
|
||||
CLI: `openclaw approvals` obsługuje edycję gatewaya lub node (zobacz [CLI zatwierdzeń](/cli/approvals)).
|
||||
CLI: `openclaw approvals` obsługuje edycję gateway lub node (zobacz [CLI zatwierdzeń](/cli/approvals)).
|
||||
|
||||
## Przepływ zatwierdzania
|
||||
|
||||
@ -361,14 +361,14 @@ Gdy prompt jest wymagany, gateway rozgłasza `exec.approval.requested` do klient
|
||||
Control UI i aplikacja macOS rozwiązują to przez `exec.approval.resolve`, a następnie gateway przekazuje
|
||||
zatwierdzone żądanie do hosta node.
|
||||
|
||||
Dla `host=node` żądania zatwierdzenia zawierają kanoniczny payload `systemRunPlan`. Gateway używa
|
||||
tego planu jako autorytatywnego kontekstu polecenia/cwd/sesji przy przekazywaniu zatwierdzonych żądań `system.run`.
|
||||
Dla `host=node` żądania zatwierdzeń zawierają kanoniczny payload `systemRunPlan`. Gateway używa
|
||||
tego planu jako autorytatywnego kontekstu polecenia/cwd/sesji podczas przekazywania zatwierdzonych żądań `system.run`.
|
||||
|
||||
To ma znaczenie przy opóźnieniach asynchronicznego zatwierdzania:
|
||||
|
||||
- ścieżka exec node przygotowuje z góry jeden kanoniczny plan
|
||||
- ścieżka node exec przygotowuje z góry jeden kanoniczny plan
|
||||
- rekord zatwierdzenia przechowuje ten plan i jego metadane powiązania
|
||||
- po zatwierdzeniu końcowe przekazane wywołanie `system.run` ponownie używa zapisanego planu
|
||||
- po zatwierdzeniu końcowe przekazane wywołanie `system.run` używa ponownie zapisanego planu
|
||||
zamiast ufać późniejszym zmianom wywołującego
|
||||
- jeśli wywołujący zmieni `command`, `rawCommand`, `cwd`, `agentId` lub
|
||||
`sessionKey` po utworzeniu żądania zatwierdzenia, gateway odrzuci
|
||||
@ -379,143 +379,144 @@ To ma znaczenie przy opóźnieniach asynchronicznego zatwierdzania:
|
||||
Uruchomienia interpreterów/runtime oparte na zatwierdzeniach są celowo konserwatywne:
|
||||
|
||||
- Dokładny kontekst argv/cwd/env jest zawsze wiązany.
|
||||
- Bezpośrednie formy skryptów powłoki i bezpośrednich plików runtime są wiązane w trybie best-effort z jedną konkretną migawką lokalnego
|
||||
- Formy bezpośrednich skryptów powłoki i bezpośrednich plików runtime są według zasady best-effort wiązane z jednym konkretnym snapshotem lokalnego
|
||||
pliku.
|
||||
- Typowe formy wrapperów menedżerów pakietów, które nadal rozwiązują się do jednego bezpośredniego lokalnego pliku (na przykład
|
||||
`pnpm exec`, `pnpm node`, `npm exec`, `npx`), są rozpakowywane przed powiązaniem.
|
||||
- Jeśli OpenClaw nie może zidentyfikować dokładnie jednego konkretnego lokalnego pliku dla polecenia interpretera/runtime
|
||||
`pnpm exec`, `pnpm node`, `npm exec`, `npx`), są odpakowywane przed powiązaniem.
|
||||
- Jeśli OpenClaw nie potrafi zidentyfikować dokładnie jednego konkretnego lokalnego pliku dla polecenia interpretera/runtime
|
||||
(na przykład skrypty pakietów, formy eval, łańcuchy loaderów specyficzne dla runtime lub niejednoznaczne formy
|
||||
wieloplikowe), wykonanie oparte na zatwierdzeniu jest odrzucane zamiast twierdzić, że obejmuje semantykę, której
|
||||
nie obejmuje.
|
||||
- Dla takich przepływów pracy preferuj sandboxing, oddzielną granicę hosta albo jawny zaufany
|
||||
wieloplikowe), wykonanie oparte na zatwierdzeniu jest odrzucane zamiast deklarować pokrycie semantyczne, którego
|
||||
faktycznie nie ma.
|
||||
- Dla takich przepływów pracy preferuj sandboxing, oddzielną granicę hosta lub jawny zaufany
|
||||
przepływ allowlist/full, w którym operator akceptuje szerszą semantykę runtime.
|
||||
|
||||
Gdy zatwierdzenia są wymagane, narzędzie exec zwraca natychmiast identyfikator zatwierdzenia. Użyj tego identyfikatora, aby
|
||||
powiązać późniejsze zdarzenia systemowe (`Exec finished` / `Exec denied`). Jeśli żadna decyzja nie nadejdzie przed
|
||||
upływem limitu czasu, żądanie jest traktowane jako timeout zatwierdzenia i prezentowane jako powód odmowy.
|
||||
Gdy zatwierdzenia są wymagane, narzędzie exec natychmiast zwraca identyfikator zatwierdzenia. Użyj tego identyfikatora, aby
|
||||
powiązać późniejsze zdarzenia systemowe (`Exec finished` / `Exec denied`). Jeśli żadna decyzja nie nadejdzie przed upływem
|
||||
limitu czasu, żądanie jest traktowane jako timeout zatwierdzenia i prezentowane jako powód odmowy.
|
||||
|
||||
### Zachowanie dostarczania follow-up
|
||||
|
||||
Po zakończeniu zatwierdzonego asynchronicznego exec OpenClaw wysyła follow-up jako turę `agent` do tej samej sesji.
|
||||
Po zakończeniu zatwierdzonego asynchronicznego exec OpenClaw wysyła turn `agent` follow-up do tej samej sesji.
|
||||
|
||||
- Jeśli istnieje prawidłowy zewnętrzny cel dostarczenia (kanał z możliwością dostarczenia plus cel `to`), dostarczenie follow-up używa tego kanału.
|
||||
- W przepływach wyłącznie webchat lub sesji wewnętrznych bez zewnętrznego celu, dostarczenie follow-up pozostaje tylko w sesji (`deliver: false`).
|
||||
- Jeśli wywołujący jawnie zażąda ścisłego dostarczenia zewnętrznego bez możliwego do rozwiązania kanału zewnętrznego, żądanie kończy się błędem `INVALID_REQUEST`.
|
||||
- Jeśli włączono `bestEffortDeliver` i nie można rozwiązać zewnętrznego kanału, dostarczenie jest obniżane do trybu tylko sesji zamiast kończyć się błędem.
|
||||
- Jeśli istnieje prawidłowy zewnętrzny cel dostarczenia (kanał dostarczalny plus cel `to`), dostarczenie follow-up używa tego kanału.
|
||||
- W przepływach wyłącznie webchat lub sesji wewnętrznych bez celu zewnętrznego dostarczenie follow-up pozostaje tylko w sesji (`deliver: false`).
|
||||
- Jeśli wywołujący jawnie żąda rygorystycznego zewnętrznego dostarczenia, ale nie ma możliwego do rozwiązania zewnętrznego kanału, żądanie kończy się błędem `INVALID_REQUEST`.
|
||||
- Jeśli włączono `bestEffortDeliver` i nie można rozwiązać zewnętrznego kanału, dostarczenie jest degradowane do trybu tylko sesyjnego zamiast zakończyć się błędem.
|
||||
|
||||
Okno potwierdzenia zawiera:
|
||||
Okno dialogowe potwierdzenia zawiera:
|
||||
|
||||
- polecenie + argumenty
|
||||
- cwd
|
||||
- identyfikator agenta
|
||||
- rozwiązaną ścieżkę pliku wykonywalnego
|
||||
- host + metadane polityki
|
||||
- metadane hosta + polityki
|
||||
|
||||
Działania:
|
||||
Akcje:
|
||||
|
||||
- **Allow once** → uruchom teraz
|
||||
- **Always allow** → dodaj do allowlisty + uruchom
|
||||
- **Always allow** → dodaj do listy dozwolonych + uruchom
|
||||
- **Deny** → zablokuj
|
||||
|
||||
## Przekazywanie zatwierdzeń do kanałów czatu
|
||||
|
||||
Możesz przekazywać prompty zatwierdzeń exec do dowolnego kanału czatu (w tym kanałów pluginów) i zatwierdzać
|
||||
je za pomocą `/approve`. Używa to zwykłego pipeline'u dostarczania wychodzącego.
|
||||
je za pomocą `/approve`. Używa to zwykłego pipeline dostarczania wychodzącego.
|
||||
|
||||
Konfiguracja:
|
||||
__OC_I18N_900005__
|
||||
Odpowiedź na czacie:
|
||||
Odpowiedź w czacie:
|
||||
__OC_I18N_900006__
|
||||
Polecenie `/approve` obsługuje zarówno zatwierdzenia exec, jak i zatwierdzenia pluginów. Jeśli identyfikator nie pasuje do oczekującego zatwierdzenia exec, automatycznie sprawdza zamiast tego zatwierdzenia pluginów.
|
||||
Polecenie `/approve` obsługuje zarówno zatwierdzenia exec, jak i zatwierdzenia pluginów. Jeśli identyfikator nie pasuje do oczekującego zatwierdzenia exec, automatycznie sprawdza zatwierdzenia pluginów.
|
||||
|
||||
### Przekazywanie zatwierdzeń pluginów
|
||||
|
||||
Przekazywanie zatwierdzeń pluginów używa tego samego pipeline'u dostarczania co zatwierdzenia exec, ale ma własną
|
||||
niezależną konfigurację pod `approvals.plugin`. Włączenie lub wyłączenie jednego nie wpływa na drugie.
|
||||
Przekazywanie zatwierdzeń pluginów używa tego samego pipeline dostarczania co zatwierdzenia exec, ale ma własną
|
||||
niezależną konfigurację w `approvals.plugin`. Włączenie lub wyłączenie jednej z nich nie wpływa na drugą.
|
||||
__OC_I18N_900007__
|
||||
Kształt konfiguracji jest identyczny jak `approvals.exec`: `enabled`, `mode`, `agentFilter`,
|
||||
`sessionFilter` i `targets` działają tak samo.
|
||||
|
||||
Kanały obsługujące współdzielone odpowiedzi interaktywne renderują te same przyciski zatwierdzeń zarówno dla zatwierdzeń exec,
|
||||
jak i pluginów. Kanały bez współdzielonego interaktywnego UI wracają do zwykłego tekstu z instrukcjami `/approve`.
|
||||
Kanały obsługujące współdzielone odpowiedzi interaktywne renderują te same przyciski zatwierdzeń zarówno dla zatwierdzeń exec, jak i
|
||||
pluginów. Kanały bez współdzielonego interaktywnego UI przechodzą na zwykły tekst z instrukcjami `/approve`.
|
||||
|
||||
### Zatwierdzenia w tym samym czacie na dowolnym kanale
|
||||
|
||||
Gdy żądanie zatwierdzenia exec lub pluginu pochodzi z dostarczalnej powierzchni czatu, ten sam czat
|
||||
może teraz domyślnie zatwierdzić je przez `/approve`. Dotyczy to kanałów takich jak Slack, Matrix i
|
||||
Microsoft Teams, oprócz istniejących już przepływów Web UI i UI terminala.
|
||||
Microsoft Teams, oprócz istniejących już przepływów Web UI i terminal UI.
|
||||
|
||||
Ta współdzielona ścieżka poleceń tekstowych używa zwykłego modelu auth kanału dla tej konwersacji. Jeśli
|
||||
czat źródłowy może już wysyłać polecenia i odbierać odpowiedzi, żądania zatwierdzeń nie wymagają już
|
||||
osobnego natywnego adaptera dostarczania tylko po to, aby pozostawać oczekującymi.
|
||||
Ta współdzielona ścieżka polecenia tekstowego używa zwykłego modelu uwierzytelniania kanału dla tej rozmowy. Jeśli
|
||||
czat źródłowy może już wysyłać polecenia i otrzymywać odpowiedzi, żądania zatwierdzeń nie potrzebują już
|
||||
oddzielnego natywnego adaptera dostarczania tylko po to, by pozostać oczekujące.
|
||||
|
||||
Discord i Telegram również obsługują `/approve` w tym samym czacie, ale te kanały nadal używają
|
||||
rozwiązanej listy zatwierdzających do autoryzacji, nawet gdy natywne dostarczanie zatwierdzeń jest wyłączone.
|
||||
Discord i Telegram również obsługują `/approve` w tym samym czacie, ale te kanały nadal używają swoich
|
||||
rozwiązanych list zatwierdzających do autoryzacji, nawet gdy natywne dostarczanie zatwierdzeń jest wyłączone.
|
||||
|
||||
Dla Telegram i innych natywnych klientów zatwierdzeń, które wywołują Gateway bezpośrednio,
|
||||
ten fallback jest celowo ograniczony do błędów typu „approval not found”. Prawdziwa
|
||||
odmowa/błąd zatwierdzenia exec nie jest po cichu ponawiana jako zatwierdzenie pluginu.
|
||||
ten fallback jest celowo ograniczony do błędów typu „zatwierdzenie nie znalezione”. Rzeczywista
|
||||
odmowa/błąd zatwierdzenia exec nie wykonuje po cichu ponownej próby jako zatwierdzenie pluginu.
|
||||
|
||||
### Natywne dostarczanie zatwierdzeń
|
||||
|
||||
Niektóre kanały mogą też działać jako natywni klienci zatwierdzeń. Natywni klienci dodają wiadomości prywatne do zatwierdzających, fanout do czatu źródłowego
|
||||
i interaktywny UX zatwierdzeń specyficzny dla kanału ponad współdzielonym przepływem `/approve` w tym samym czacie.
|
||||
Niektóre kanały mogą także działać jako natywni klienci zatwierdzeń. Natywni klienci dodają DM zatwierdzających, fanout czatu źródłowego
|
||||
oraz specyficzny dla kanału interaktywny UX zatwierdzeń ponad współdzielony przepływ `/approve`
|
||||
w tym samym czacie.
|
||||
|
||||
Gdy dostępne są natywne karty/przyciski zatwierdzeń, to natywne UI jest podstawową
|
||||
ścieżką po stronie agenta. Agent nie powinien też powtarzać zduplikowanego zwykłego polecenia czatu
|
||||
`/approve`, chyba że wynik narzędzia mówi, że zatwierdzenia na czacie są niedostępne lub
|
||||
Gdy natywne karty/przyciski zatwierdzeń są dostępne, ten natywny UI jest główną
|
||||
ścieżką skierowaną do agenta. Agent nie powinien również powielać zwykłego polecenia czatu
|
||||
`/approve`, chyba że wynik narzędzia mówi, że zatwierdzenia w czacie są niedostępne albo
|
||||
ręczne zatwierdzenie jest jedyną pozostałą ścieżką.
|
||||
|
||||
Model ogólny:
|
||||
|
||||
- polityka host exec nadal decyduje, czy zatwierdzenie exec jest wymagane
|
||||
- polityka hosta exec nadal decyduje, czy zatwierdzenie exec jest wymagane
|
||||
- `approvals.exec` kontroluje przekazywanie promptów zatwierdzeń do innych miejsc docelowych czatu
|
||||
- `channels.<channel>.execApprovals` kontroluje, czy dany kanał działa jako natywny klient zatwierdzeń
|
||||
|
||||
Natywni klienci zatwierdzeń automatycznie włączają dostarczanie najpierw do wiadomości prywatnych, gdy wszystkie poniższe warunki są spełnione:
|
||||
Natywni klienci zatwierdzeń automatycznie włączają dostarczanie najpierw do DM, gdy wszystkie poniższe warunki są spełnione:
|
||||
|
||||
- kanał obsługuje natywne dostarczanie zatwierdzeń
|
||||
- zatwierdzających można rozwiązać z jawnego `execApprovals.approvers` lub z
|
||||
udokumentowanych dla tego kanału źródeł fallbacku
|
||||
- `channels.<channel>.execApprovals.enabled` nie jest ustawione albo ma wartość `"auto"`
|
||||
- zatwierdzający mogą zostać rozwiązani z jawnych `execApprovals.approvers` lub udokumentowanych źródeł fallback dla
|
||||
tego kanału
|
||||
- `channels.<channel>.execApprovals.enabled` jest nieustawione lub ma wartość `"auto"`
|
||||
|
||||
Ustaw `enabled: false`, aby jawnie wyłączyć natywnego klienta zatwierdzeń. Ustaw `enabled: true`, aby wymusić
|
||||
jego włączenie, gdy zatwierdzający zostaną rozwiązani. Publiczne dostarczanie do czatu źródłowego pozostaje jawne przez
|
||||
jego włączenie, gdy zatwierdzający się rozwiązują. Publiczne dostarczanie do czatu źródłowego pozostaje jawne przez
|
||||
`channels.<channel>.execApprovals.target`.
|
||||
|
||||
FAQ: [Dlaczego istnieją dwie konfiguracje zatwierdzeń exec dla zatwierdzeń na czacie?](/help/faq#why-are-there-two-exec-approval-configs-for-chat-approvals)
|
||||
FAQ: [Dlaczego istnieją dwie konfiguracje zatwierdzeń exec dla zatwierdzeń w czacie?](/help/faq#why-are-there-two-exec-approval-configs-for-chat-approvals)
|
||||
|
||||
- Discord: `channels.discord.execApprovals.*`
|
||||
- Slack: `channels.slack.execApprovals.*`
|
||||
- Telegram: `channels.telegram.execApprovals.*`
|
||||
|
||||
Ci natywni klienci zatwierdzeń dodają routing wiadomości prywatnych i opcjonalny fanout na kanał ponad współdzielonym
|
||||
przepływem `/approve` w tym samym czacie i współdzielonymi przyciskami zatwierdzeń.
|
||||
Ci natywni klienci zatwierdzeń dodają routing DM i opcjonalny fanout do kanału ponad współdzielony
|
||||
przepływ `/approve` w tym samym czacie oraz współdzielone przyciski zatwierdzeń.
|
||||
|
||||
Wspólne zachowanie:
|
||||
Współdzielone zachowanie:
|
||||
|
||||
- Slack, Matrix, Microsoft Teams i podobne dostarczalne czaty używają zwykłego modelu auth kanału
|
||||
- Slack, Matrix, Microsoft Teams i podobne dostarczalne czaty używają zwykłego modelu uwierzytelniania kanału
|
||||
dla `/approve` w tym samym czacie
|
||||
- gdy natywny klient zatwierdzeń włączy się automatycznie, domyślnym natywnym celem dostarczenia są wiadomości prywatne zatwierdzających
|
||||
- dla Discord i Telegram tylko rozwiązani zatwierdzający mogą zatwierdzać lub odrzucać
|
||||
- gdy natywny klient zatwierdzeń włącza się automatycznie, domyślnym celem natywnego dostarczania są DM zatwierdzających
|
||||
- w przypadku Discord i Telegram tylko rozwiązani zatwierdzający mogą zatwierdzać lub odrzucać
|
||||
- zatwierdzający Discord mogą być jawni (`execApprovals.approvers`) lub wywnioskowani z `commands.ownerAllowFrom`
|
||||
- zatwierdzający Telegram mogą być jawni (`execApprovals.approvers`) lub wywnioskowani z istniejącej konfiguracji właściciela (`allowFrom` oraz `defaultTo` dla wiadomości prywatnych, gdzie obsługiwane)
|
||||
- zatwierdzający Telegram mogą być jawni (`execApprovals.approvers`) lub wywnioskowani z istniejącej konfiguracji właściciela (`allowFrom`, plus `defaultTo` dla wiadomości bezpośrednich, gdy jest obsługiwane)
|
||||
- zatwierdzający Slack mogą być jawni (`execApprovals.approvers`) lub wywnioskowani z `commands.ownerAllowFrom`
|
||||
- natywne przyciski Slack zachowują rodzaj identyfikatora zatwierdzenia, więc identyfikatory `plugin:` mogą rozwiązywać zatwierdzenia pluginów
|
||||
bez drugiej lokalnej warstwy fallbacku Slack
|
||||
- natywny routing wiadomości prywatnych/kanałów Matrix jest tylko dla exec; zatwierdzenia pluginów Matrix pozostają na współdzielonej
|
||||
ścieżce `/approve` w tym samym czacie oraz opcjonalnym przekazywaniu `approvals.plugin`
|
||||
- żądający nie musi być zatwierdzającym
|
||||
- czat źródłowy może zatwierdzić bezpośrednio przez `/approve`, gdy ten czat już obsługuje polecenia i odpowiedzi
|
||||
- natywne przyciski zatwierdzeń Discord kierują według rodzaju identyfikatora zatwierdzenia: identyfikatory `plugin:` trafiają
|
||||
bezpośrednio do zatwierdzeń pluginów, wszystko inne do zatwierdzeń exec
|
||||
- natywne przyciski zatwierdzeń Telegram stosują ten sam ograniczony fallback exec-do-plugin co `/approve`
|
||||
- gdy natywne `target` włącza dostarczanie do czatu źródłowego, prompty zatwierdzeń zawierają tekst polecenia
|
||||
- oczekujące zatwierdzenia exec wygasają domyślnie po 30 minutach
|
||||
- jeśli żadne UI operatora ani skonfigurowany klient zatwierdzeń nie mogą przyjąć żądania, prompt wraca do `askFallback`
|
||||
bez drugiej lokalnej warstwy fallback w Slack
|
||||
- natywny routing DM/kanału Matrix i skróty reakcji obsługują zarówno zatwierdzenia exec, jak i pluginów;
|
||||
autoryzacja pluginów nadal pochodzi z `channels.matrix.dm.allowFrom`
|
||||
- osoba żądająca nie musi być zatwierdzającym
|
||||
- czat źródłowy może zatwierdzać bezpośrednio przez `/approve`, gdy dany czat już obsługuje polecenia i odpowiedzi
|
||||
- natywne przyciski zatwierdzeń Discord routują według rodzaju identyfikatora zatwierdzenia: identyfikatory `plugin:` trafiają
|
||||
bezpośrednio do zatwierdzeń pluginów, wszystko inne trafia do zatwierdzeń exec
|
||||
- natywne przyciski zatwierdzeń Telegram stosują ten sam ograniczony fallback exec→plugin co `/approve`
|
||||
- gdy natywny `target` włącza dostarczanie do czatu źródłowego, prompty zatwierdzeń zawierają tekst polecenia
|
||||
- oczekujące zatwierdzenia exec domyślnie wygasają po 30 minutach
|
||||
- jeśli żaden interfejs operatora ani skonfigurowany klient zatwierdzeń nie może przyjąć żądania, prompt przechodzi do `askFallback`
|
||||
|
||||
Telegram domyślnie kieruje do wiadomości prywatnych zatwierdzających (`target: "dm"`). Możesz przełączyć na `channel` lub `both`, gdy
|
||||
chcesz, aby prompty zatwierdzeń pojawiały się także w czacie/temacie źródłowym Telegram. W przypadku tematów forum Telegram
|
||||
Telegram domyślnie używa DM zatwierdzających (`target: "dm"`). Możesz przełączyć na `channel` lub `both`, gdy
|
||||
chcesz, aby prompty zatwierdzeń pojawiały się również w źródłowym czacie/temacie Telegram. Dla tematów forum Telegram
|
||||
OpenClaw zachowuje temat dla promptu zatwierdzenia i follow-up po zatwierdzeniu.
|
||||
|
||||
Zobacz:
|
||||
@ -523,42 +524,42 @@ Zobacz:
|
||||
- [Discord](/channels/discord)
|
||||
- [Telegram](/channels/telegram)
|
||||
|
||||
### Przepływ IPC na macOS
|
||||
### Przepływ IPC macOS
|
||||
__OC_I18N_900008__
|
||||
Uwagi dotyczące bezpieczeństwa:
|
||||
|
||||
- Tryb gniazda Unix `0600`, token przechowywany w `exec-approvals.json`.
|
||||
- Kontrola peera z tym samym UID.
|
||||
- Sprawdzenie peera z tym samym UID.
|
||||
- Challenge/response (nonce + token HMAC + hash żądania) + krótki TTL.
|
||||
|
||||
## Zdarzenia systemowe
|
||||
|
||||
Cykl życia exec jest pokazywany jako wiadomości systemowe:
|
||||
Cykl życia exec jest ujawniany jako komunikaty systemowe:
|
||||
|
||||
- `Exec running` (tylko jeśli polecenie przekracza próg powiadomienia o uruchomieniu)
|
||||
- `Exec finished`
|
||||
- `Exec denied`
|
||||
|
||||
Są one publikowane do sesji agenta po zgłoszeniu zdarzenia przez node.
|
||||
Zatwierdzenia exec na hoście gatewaya emitują ten sam cykl życia zdarzeń, gdy polecenie się zakończy (i opcjonalnie także podczas działania dłuższego niż próg).
|
||||
Exec objęte zatwierdzeniem używają ponownie identyfikatora zatwierdzenia jako `runId` w tych wiadomościach, aby ułatwić korelację.
|
||||
Są one publikowane do sesji agenta po zgłoszeniu zdarzenia przez węzeł.
|
||||
Zatwierdzenia exec na hoście gateway emitują ten sam cykl życia zdarzeń, gdy polecenie się kończy (oraz opcjonalnie, gdy działa dłużej niż próg).
|
||||
Exec objęte zatwierdzeniem używają ponownie identyfikatora zatwierdzenia jako `runId` w tych komunikatach, aby ułatwić korelację.
|
||||
|
||||
## Zachowanie przy odmowie zatwierdzenia
|
||||
## Zachowanie po odrzuceniu zatwierdzenia
|
||||
|
||||
Gdy asynchroniczne zatwierdzenie exec zostanie odrzucone, OpenClaw uniemożliwia agentowi ponowne użycie
|
||||
wyjścia z jakiegokolwiek wcześniejszego uruchomienia tego samego polecenia w sesji. Powód odmowy
|
||||
jest przekazywany z jawną informacją, że żadne wyjście polecenia nie jest dostępne, co powstrzymuje
|
||||
agenta przed twierdzeniem, że istnieje nowe wyjście, albo przed powtarzaniem odrzuconego polecenia z
|
||||
wyniku z jakiegokolwiek wcześniejszego uruchomienia tego samego polecenia w sesji. Powód odrzucenia
|
||||
jest przekazywany z jawną wskazówką, że nie ma dostępnych danych wyjściowych polecenia, co zatrzymuje
|
||||
agenta przed twierdzeniem, że istnieją nowe dane wyjściowe, lub przed powtarzaniem odrzuconego polecenia z
|
||||
nieaktualnymi wynikami z wcześniejszego udanego uruchomienia.
|
||||
|
||||
## Konsekwencje
|
||||
|
||||
- **full** jest potężne; jeśli to możliwe, preferuj allowlisty.
|
||||
- **ask** utrzymuje Cię w pętli, a jednocześnie pozwala na szybkie zatwierdzanie.
|
||||
- Allowlisty per agent zapobiegają przeciekaniu zatwierdzeń jednego agenta do innych.
|
||||
- Zatwierdzenia dotyczą tylko żądań host exec od **autoryzowanych nadawców**. Nieautoryzowani nadawcy nie mogą wydawać `/exec`.
|
||||
- **full** daje szerokie uprawnienia; gdy to możliwe, preferuj listy dozwolonych.
|
||||
- **ask** pozwala Ci zachować kontrolę, jednocześnie umożliwiając szybkie zatwierdzenia.
|
||||
- Listy dozwolonych per agent zapobiegają przenikaniu zatwierdzeń jednego agenta do innych.
|
||||
- Zatwierdzenia mają zastosowanie tylko do żądań exec hosta od **autoryzowanych nadawców**. Nieautoryzowani nadawcy nie mogą wydawać `/exec`.
|
||||
- `/exec security=full` to wygodna opcja na poziomie sesji dla autoryzowanych operatorów i z założenia pomija zatwierdzenia.
|
||||
Aby twardo zablokować host exec, ustaw security zatwierdzeń na `deny` albo zabroń narzędzia `exec` przez politykę narzędzi.
|
||||
Aby twardo zablokować exec hosta, ustaw security zatwierdzeń na `deny` lub zablokuj narzędzie `exec` przez politykę narzędzi.
|
||||
|
||||
Powiązane:
|
||||
|
||||
@ -568,7 +569,7 @@ Powiązane:
|
||||
|
||||
## Powiązane
|
||||
|
||||
- [Exec](/pl/tools/exec) — narzędzie wykonywania poleceń powłoki
|
||||
- [Sandboxing](/pl/gateway/sandboxing) — tryby sandboxa i dostęp do workspace
|
||||
- [Exec](/pl/tools/exec) — narzędzie do wykonywania poleceń powłoki
|
||||
- [Sandboxing](/pl/gateway/sandboxing) — tryby sandbox i dostęp do obszaru roboczego
|
||||
- [Bezpieczeństwo](/pl/gateway/security) — model bezpieczeństwa i utwardzanie
|
||||
- [Sandbox vs Tool Policy vs Elevated](/pl/gateway/sandbox-vs-tool-policy-vs-elevated) — kiedy używać każdego z nich
|
||||
|
||||
Loading…
Reference in New Issue
Block a user