chore(i18n): refresh pl translations
This commit is contained in:
openclaw-docs-i18n[bot]
parent
672f5206e6
commit
eccfa024fb
@ -1,36 +1,36 @@
|
||||
---
|
||||
read_when:
|
||||
- Chcesz zainstalować Pluginy Gateway lub zgodne pakiety albo nimi zarządzać
|
||||
- Chcesz debugować błędy ładowania Plugin
|
||||
- Chcesz instalować pluginy Gateway lub zgodne pakiety albo nimi zarządzać
|
||||
- Chcesz debugować błędy ładowania pluginów
|
||||
sidebarTitle: Plugins
|
||||
summary: Dokumentacja referencyjna CLI dla `openclaw plugins` (list, install, marketplace, uninstall, enable/disable, doctor)
|
||||
title: Pluginy
|
||||
x-i18n:
|
||||
generated_at: "2026-05-06T09:06:08Z"
|
||||
generated_at: "2026-05-06T10:05:26Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: e584092c6cdaf87681aef2ed106c299e3bab0552305b669c66b05deb61bf25ce
|
||||
source_hash: c888d3fc8de0e25edc1c38f679d522a4e75cb09d986702451e29418d70a939f2
|
||||
source_path: cli/plugins.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
Zarządzaj pluginami Gateway, pakietami hooków i zgodnymi pakietami zbiorczymi.
|
||||
Zarządzaj Plugin Gateway, pakietami hooków i zgodnymi bundlami.
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Plugin system" href="/pl/tools/plugin">
|
||||
Przewodnik dla użytkowników końcowych dotyczący instalowania, włączania i rozwiązywania problemów z pluginami.
|
||||
<Card title="System Plugin" href="/pl/tools/plugin">
|
||||
Przewodnik dla użytkownika końcowego dotyczący instalowania, włączania i rozwiązywania problemów z pluginami.
|
||||
</Card>
|
||||
<Card title="Manage plugins" href="/pl/plugins/manage-plugins">
|
||||
<Card title="Zarządzaj pluginami" href="/pl/plugins/manage-plugins">
|
||||
Szybkie przykłady instalowania, wyświetlania listy, aktualizowania, odinstalowywania i publikowania.
|
||||
</Card>
|
||||
<Card title="Plugin bundles" href="/pl/plugins/bundles">
|
||||
Model zgodności pakietów zbiorczych.
|
||||
<Card title="Bundle Plugin" href="/pl/plugins/bundles">
|
||||
Model zgodności bundli.
|
||||
</Card>
|
||||
<Card title="Plugin manifest" href="/pl/plugins/manifest">
|
||||
<Card title="Manifest Plugin" href="/pl/plugins/manifest">
|
||||
Pola manifestu i schemat konfiguracji.
|
||||
</Card>
|
||||
<Card title="Security" href="/pl/gateway/security">
|
||||
Utwardzanie zabezpieczeń instalacji pluginów.
|
||||
<Card title="Bezpieczeństwo" href="/pl/gateway/security">
|
||||
Wzmacnianie bezpieczeństwa instalacji pluginów.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
@ -64,14 +64,14 @@ openclaw plugins marketplace list <marketplace> --json
|
||||
|
||||
Aby zbadać powolne instalowanie, inspekcję, odinstalowywanie lub odświeżanie rejestru, uruchom
|
||||
polecenie z `OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1`. Ślad zapisuje czasy faz
|
||||
do stderr i pozostawia dane wyjściowe JSON możliwe do parsowania. Zobacz [Debugowanie](/pl/help/debugging#plugin-lifecycle-trace).
|
||||
do stderr i zachowuje możliwość parsowania wyjścia JSON. Zobacz [Debugowanie](/pl/help/debugging#plugin-lifecycle-trace).
|
||||
|
||||
<Note>
|
||||
Dołączone pluginy są dostarczane z OpenClaw. Niektóre są włączone domyślnie (na przykład dołączeni dostawcy modeli, dołączeni dostawcy mowy i dołączony plugin przeglądarki); inne wymagają `plugins enable`.
|
||||
Dołączone pluginy są dostarczane z OpenClaw. Niektóre są domyślnie włączone (na przykład dołączeni dostawcy modeli, dołączeni dostawcy mowy i dołączony Plugin przeglądarki); inne wymagają `plugins enable`.
|
||||
|
||||
Natywne pluginy OpenClaw muszą zawierać `openclaw.plugin.json` z wbudowanym schematem JSON (`configSchema`, nawet jeśli jest pusty). Zgodne pakiety zbiorcze używają zamiast tego własnych manifestów pakietów zbiorczych.
|
||||
Natywne pluginy OpenClaw muszą dostarczać `openclaw.plugin.json` z wbudowanym JSON Schema (`configSchema`, nawet jeśli pustym). Zgodne bundle używają zamiast tego własnych manifestów bundli.
|
||||
|
||||
`plugins list` pokazuje `Format: openclaw` lub `Format: bundle`. Szczegółowe dane wyjściowe list/info pokazują także podtyp pakietu zbiorczego (`codex`, `claude` lub `cursor`) oraz wykryte możliwości pakietu zbiorczego.
|
||||
`plugins list` pokazuje `Format: openclaw` lub `Format: bundle`. Szczegółowe wyjście listy/informacji pokazuje też podtyp bundla (`codex`, `claude` lub `cursor`) oraz wykryte możliwości bundla.
|
||||
</Note>
|
||||
|
||||
### Instalacja
|
||||
@ -94,77 +94,77 @@ openclaw plugins install <plugin> --marketplace https://github.com/<owner>/<repo
|
||||
```
|
||||
|
||||
<Warning>
|
||||
Nagie nazwy pakietów są domyślnie instalowane z npm podczas przejścia startowego. Użyj `clawhub:<package>` dla ClawHub. Traktuj instalacje pluginów jak uruchamianie kodu. Preferuj przypięte wersje.
|
||||
Same nazwy pakietów podczas przejścia po uruchomieniu są domyślnie instalowane z npm. Użyj `clawhub:<package>` dla ClawHub. Traktuj instalacje pluginów jak uruchamianie kodu. Preferuj przypięte wersje.
|
||||
</Warning>
|
||||
|
||||
`plugins search` odpytuje ClawHub o możliwe do zainstalowania pakiety pluginów i wypisuje
|
||||
nazwy pakietów gotowe do instalacji. Wyszukuje pakiety code-plugin i bundle-plugin,
|
||||
nazwy pakietów gotowe do instalacji. Przeszukuje pakiety code-plugin i bundle-plugin,
|
||||
a nie Skills. Użyj `openclaw skills search` dla Skills z ClawHub.
|
||||
|
||||
<Note>
|
||||
ClawHub to podstawowa powierzchnia dystrybucji i odkrywania większości pluginów. Npm
|
||||
ClawHub jest główną powierzchnią dystrybucji i odkrywania dla większości pluginów. Npm
|
||||
pozostaje obsługiwaną ścieżką awaryjną i bezpośredniej instalacji. Należące do OpenClaw
|
||||
pakiety pluginów `@openclaw/*` są ponownie publikowane w npm; aktualną listę
|
||||
znajdziesz na [npmjs.com/org/openclaw](https://www.npmjs.com/org/openclaw) albo w
|
||||
[inwentarzu pluginów](/pl/plugins/plugin-inventory). Stabilne instalacje używają `latest`.
|
||||
Instalacje i aktualizacje z kanału beta preferują npm `beta` dist-tag, gdy taki tag
|
||||
pakiety pluginów `@openclaw/*` są ponownie publikowane w npm; zobacz bieżącą listę
|
||||
na [npmjs.com/org/openclaw](https://www.npmjs.com/org/openclaw) lub
|
||||
[inwentarz pluginów](/pl/plugins/plugin-inventory). Stabilne instalacje używają `latest`.
|
||||
Instalacje i aktualizacje kanału beta preferują npm dist-tag `beta`, gdy ten tag
|
||||
jest dostępny, a następnie wracają do `latest`.
|
||||
</Note>
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Config includes and invalid-config repair">
|
||||
Jeśli sekcja `plugins` jest oparta na jednoplikowym `$include`, `plugins install/update/enable/disable/uninstall` zapisują zmiany do tego dołączonego pliku i pozostawiają `openclaw.json` bez zmian. Dołączenia główne, tablice dołączeń i dołączenia z sąsiednimi nadpisaniami kończą się zamknięciem zamiast spłaszczania. Zobacz [Dołączenia konfiguracji](/pl/gateway/configuration), aby poznać obsługiwane kształty.
|
||||
<Accordion title="Dołączenia konfiguracji i naprawa nieprawidłowej konfiguracji">
|
||||
Jeśli Twoja sekcja `plugins` jest oparta na jednoplikowym `$include`, `plugins install/update/enable/disable/uninstall` zapisują do tego dołączonego pliku i pozostawiają `openclaw.json` bez zmian. Dołączenia główne, tablice dołączeń i dołączenia z sąsiednimi nadpisaniami kończą się bezpiecznym niepowodzeniem zamiast spłaszczania. Zobacz [Dołączenia konfiguracji](/pl/gateway/configuration), aby poznać obsługiwane kształty.
|
||||
|
||||
Jeśli konfiguracja jest nieprawidłowa podczas instalacji, `plugins install` zwykle kończy się zamknięciem i informuje, aby najpierw uruchomić `openclaw doctor --fix`. Podczas uruchamiania Gateway i przeładowania na gorąco nieprawidłowa konfiguracja pluginów kończy się zamknięciem jak każda inna nieprawidłowa konfiguracja; `openclaw doctor --fix` może poddać kwarantannie nieprawidłowy wpis pluginu. Jedynym udokumentowanym wyjątkiem w czasie instalacji jest wąska ścieżka odzyskiwania dołączonego pluginu dla pluginów, które jawnie wybiorą `openclaw.install.allowInvalidConfigRecovery`.
|
||||
Jeśli konfiguracja jest nieprawidłowa podczas instalacji, `plugins install` zwykle kończy się bezpiecznym niepowodzeniem i informuje, aby najpierw uruchomić `openclaw doctor --fix`. Podczas uruchamiania Gateway i przeładowania na gorąco nieprawidłowa konfiguracja pluginów kończy się bezpiecznym niepowodzeniem jak każda inna nieprawidłowa konfiguracja; `openclaw doctor --fix` może poddać kwarantannie nieprawidłowy wpis pluginu. Jedynym udokumentowanym wyjątkiem w czasie instalacji jest wąska ścieżka odzyskiwania dołączonych pluginów dla pluginów, które jawnie zgadzają się na `openclaw.install.allowInvalidConfigRecovery`.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="--force and reinstall vs update">
|
||||
`--force` ponownie używa istniejącego celu instalacji i nadpisuje już zainstalowany plugin lub pakiet hooków w miejscu. Użyj go, gdy celowo ponownie instalujesz ten sam identyfikator z nowej ścieżki lokalnej, archiwum, pakietu ClawHub lub artefaktu npm. Do rutynowych uaktualnień już śledzonego pluginu npm preferuj `openclaw plugins update <id-or-npm-spec>`.
|
||||
<Accordion title="--force i ponowna instalacja a aktualizacja">
|
||||
`--force` ponownie używa istniejącego celu instalacji i nadpisuje już zainstalowany Plugin lub pakiet hooków w miejscu. Użyj tego, gdy celowo ponownie instalujesz ten sam identyfikator z nowej ścieżki lokalnej, archiwum, pakietu ClawHub lub artefaktu npm. W przypadku rutynowych aktualizacji już śledzonego pluginu npm preferuj `openclaw plugins update <id-or-npm-spec>`.
|
||||
|
||||
Jeśli uruchomisz `plugins install` dla identyfikatora pluginu, który jest już zainstalowany, OpenClaw zatrzyma się i wskaże `plugins update <id-or-npm-spec>` dla zwykłego uaktualnienia albo `plugins install <package> --force`, gdy naprawdę chcesz nadpisać bieżącą instalację z innego źródła.
|
||||
Jeśli uruchomisz `plugins install` dla identyfikatora pluginu, który jest już zainstalowany, OpenClaw zatrzyma się i wskaże `plugins update <id-or-npm-spec>` dla zwykłej aktualizacji albo `plugins install <package> --force`, gdy naprawdę chcesz nadpisać bieżącą instalację z innego źródła.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="--pin scope">
|
||||
`--pin` dotyczy tylko instalacji npm. Nie jest obsługiwane z instalacjami `git:`; użyj jawnego odwołania git, takiego jak `git:github.com/acme/plugin@v1.2.3`, gdy chcesz przypięte źródło. Nie jest obsługiwane z `--marketplace`, ponieważ instalacje z marketplace utrwalają metadane źródła marketplace zamiast specyfikacji npm.
|
||||
<Accordion title="Zakres --pin">
|
||||
`--pin` dotyczy tylko instalacji npm. Nie jest obsługiwane z instalacjami `git:`; użyj jawnego refa git, takiego jak `git:github.com/acme/plugin@v1.2.3`, gdy chcesz przypięte źródło. Nie jest obsługiwane z `--marketplace`, ponieważ instalacje marketplace utrwalają metadane źródła marketplace zamiast specyfikacji npm.
|
||||
</Accordion>
|
||||
<Accordion title="--dangerously-force-unsafe-install">
|
||||
`--dangerously-force-unsafe-install` to opcja awaryjna dla fałszywych alarmów we wbudowanym skanerze niebezpiecznego kodu. Pozwala kontynuować instalację nawet wtedy, gdy wbudowany skaner zgłasza wyniki `critical`, ale **nie** omija blokad polityki hooka pluginu `before_install` i **nie** omija niepowodzeń skanowania.
|
||||
`--dangerously-force-unsafe-install` to opcja awaryjna dla fałszywych alarmów we wbudowanym skanerze niebezpiecznego kodu. Pozwala kontynuować instalację nawet wtedy, gdy wbudowany skaner zgłasza znaleziska `critical`, ale **nie** omija blokad zasad hooka pluginu `before_install` i **nie** omija niepowodzeń skanowania.
|
||||
|
||||
Ta flaga CLI dotyczy przepływów instalacji/aktualizacji pluginów. Instalacje zależności Skills obsługiwane przez Gateway używają odpowiadającego nadpisania żądania `dangerouslyForceUnsafeInstall`, natomiast `openclaw skills install` pozostaje oddzielnym przepływem pobierania/instalowania Skills z ClawHub.
|
||||
Ta flaga CLI dotyczy przepływów instalacji/aktualizacji pluginów. Instalacje zależności Skills obsługiwane przez Gateway używają odpowiadającego jej nadpisania żądania `dangerouslyForceUnsafeInstall`, podczas gdy `openclaw skills install` pozostaje osobnym przepływem pobierania/instalacji Skills z ClawHub.
|
||||
|
||||
Jeśli plugin opublikowany przez Ciebie w ClawHub jest blokowany przez skan rejestru, użyj kroków dla wydawcy w [ClawHub](/pl/tools/clawhub).
|
||||
Jeśli Plugin opublikowany przez Ciebie w ClawHub jest blokowany przez skan rejestru, użyj kroków dla wydawcy w [ClawHub](/pl/tools/clawhub).
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Hook packs and npm specs">
|
||||
`plugins install` jest także powierzchnią instalacji dla pakietów hooków, które udostępniają `openclaw.hooks` w `package.json`. Użyj `openclaw hooks` do filtrowanej widoczności hooków i włączania poszczególnych hooków, a nie do instalacji pakietów.
|
||||
<Accordion title="Pakiety hooków i specyfikacje npm">
|
||||
`plugins install` jest też powierzchnią instalacji dla pakietów hooków, które udostępniają `openclaw.hooks` w `package.json`. Używaj `openclaw hooks` do filtrowanej widoczności hooków i włączania poszczególnych hooków, a nie do instalacji pakietów.
|
||||
|
||||
Specyfikacje npm są **tylko rejestrowe** (nazwa pakietu + opcjonalna **dokładna wersja** albo **dist-tag**). Specyfikacje Git/URL/plik i zakresy semver są odrzucane. Instalacje zależności działają lokalnie w projekcie z `--ignore-scripts` dla bezpieczeństwa, nawet jeśli Twoja powłoka ma globalne ustawienia instalacji npm.
|
||||
Specyfikacje npm są **tylko rejestrowe** (nazwa pakietu + opcjonalna **dokładna wersja** lub **dist-tag**). Specyfikacje Git/URL/plik oraz zakresy semver są odrzucane. Instalacje zależności działają lokalnie w projekcie z `--ignore-scripts` dla bezpieczeństwa, nawet gdy Twoja powłoka ma globalne ustawienia instalacji npm. Zarządzane korzenie npm pluginów dziedziczą pakietowe `overrides` npm OpenClaw, więc piny bezpieczeństwa hosta dotyczą też wyniesionych zależności pluginów.
|
||||
|
||||
Użyj `npm:<package>`, gdy chcesz jawnie wymusić rozwiązywanie npm. Nagie specyfikacje pakietów także instalują bezpośrednio z npm podczas przejścia startowego.
|
||||
Użyj `npm:<package>`, gdy chcesz jawnie wskazać rozwiązywanie przez npm. Same specyfikacje pakietów podczas przejścia po uruchomieniu również instalują bezpośrednio z npm.
|
||||
|
||||
Nagie specyfikacje i `@latest` pozostają na stabilnej ścieżce. Oznaczone datą wersje korygujące OpenClaw, takie jak `2026.5.3-1`, są stabilnymi wydaniami dla tego sprawdzenia. Jeśli npm rozwiąże którąkolwiek z nich do wydania wstępnego, OpenClaw zatrzyma się i poprosi o jawne wyrażenie zgody za pomocą tagu wydania wstępnego, takiego jak `@beta`/`@rc`, albo dokładnej wersji wstępnej, takiej jak `@1.2.3-beta.4`.
|
||||
Same specyfikacje i `@latest` pozostają na stabilnej ścieżce. Wersje poprawek OpenClaw ze stemplem daty, takie jak `2026.5.3-1`, są stabilnymi wydaniami dla tego sprawdzenia. Jeśli npm rozwiąże którąkolwiek z nich do wersji przedpremierowej, OpenClaw zatrzyma się i poprosi o jawne wyrażenie zgody za pomocą tagu przedpremierowego, takiego jak `@beta`/`@rc`, albo dokładnej wersji przedpremierowej, takiej jak `@1.2.3-beta.4`.
|
||||
|
||||
Jeśli naga specyfikacja instalacji pasuje do oficjalnego identyfikatora pluginu (na przykład `diffs`), OpenClaw instaluje bezpośrednio wpis katalogu. Aby zainstalować pakiet npm o tej samej nazwie, użyj jawnej specyfikacji z zakresem (na przykład `@scope/diffs`).
|
||||
Jeśli sama specyfikacja instalacji pasuje do oficjalnego identyfikatora pluginu (na przykład `diffs`), OpenClaw instaluje wpis katalogu bezpośrednio. Aby zainstalować pakiet npm o tej samej nazwie, użyj jawnej specyfikacji ze scope (na przykład `@scope/diffs`).
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Git repositories">
|
||||
Użyj `git:<repo>`, aby instalować bezpośrednio z repozytorium git. Obsługiwane formy obejmują `git:github.com/owner/repo`, `git:owner/repo`, pełne adresy klonowania `https://`, `ssh://`, `git://`, `file://` oraz `git@host:owner/repo.git`. Dodaj `@<ref>` albo `#<ref>`, aby przed instalacją wybrać gałąź, tag lub commit.
|
||||
<Accordion title="Repozytoria Git">
|
||||
Użyj `git:<repo>`, aby instalować bezpośrednio z repozytorium git. Obsługiwane formy obejmują `git:github.com/owner/repo`, `git:owner/repo`, pełne adresy klonowania `https://`, `ssh://`, `git://`, `file://` oraz `git@host:owner/repo.git`. Dodaj `@<ref>` lub `#<ref>`, aby przed instalacją wybrać branch, tag lub commit.
|
||||
|
||||
Instalacje Git klonują do katalogu tymczasowego, wybierają żądane odwołanie, gdy jest obecne, a następnie używają zwykłego instalatora katalogu pluginów. Oznacza to, że walidacja manifestu, skanowanie niebezpiecznego kodu, praca instalacyjna menedżera pakietów i rekordy instalacji zachowują się jak instalacje npm. Zarejestrowane instalacje Git zawierają źródłowy URL/odwołanie oraz rozwiązany commit, aby `openclaw plugins update` mógł później ponownie rozwiązać źródło.
|
||||
Instalacje Git klonują do katalogu tymczasowego, wybierają żądany ref, gdy jest obecny, a następnie używają normalnego instalatora katalogu pluginu. Oznacza to, że walidacja manifestu, skanowanie niebezpiecznego kodu, prace instalacyjne menedżera pakietów i rekordy instalacji zachowują się jak instalacje npm. Zarejestrowane instalacje git zawierają źródłowy URL/ref oraz rozwiązany commit, aby `openclaw plugins update` mógł później ponownie rozwiązać źródło.
|
||||
|
||||
Po instalacji z git użyj `openclaw plugins inspect <id> --runtime --json`, aby zweryfikować rejestracje uruchomieniowe, takie jak metody Gateway i polecenia CLI. Jeśli plugin zarejestrował główny punkt CLI za pomocą `api.registerCli`, wykonaj to polecenie bezpośrednio przez główny CLI OpenClaw, na przykład `openclaw demo-plugin ping`.
|
||||
Po instalacji z git użyj `openclaw plugins inspect <id> --runtime --json`, aby zweryfikować rejestracje runtime, takie jak metody Gateway i polecenia CLI. Jeśli Plugin zarejestrował korzeń CLI za pomocą `api.registerCli`, wykonaj to polecenie bezpośrednio przez główne CLI OpenClaw, na przykład `openclaw demo-plugin ping`.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Archives">
|
||||
<Accordion title="Archiwa">
|
||||
Obsługiwane archiwa: `.zip`, `.tgz`, `.tar.gz`, `.tar`. Archiwa natywnych pluginów OpenClaw muszą zawierać prawidłowy `openclaw.plugin.json` w wyodrębnionym katalogu głównym pluginu; archiwa zawierające tylko `package.json` są odrzucane, zanim OpenClaw zapisze rekordy instalacji.
|
||||
|
||||
Użyj `npm-pack:<path.tgz>`, gdy plik jest tarballem npm-pack i chcesz
|
||||
przetestować tę samą zarządzaną ścieżkę instalacji w katalogu głównym npm, której używają instalacje z rejestru,
|
||||
przetestować tę samą zarządzaną ścieżkę instalacji korzenia npm, której używają instalacje rejestrowe,
|
||||
w tym weryfikację `package-lock.json`, skanowanie wyniesionych zależności i
|
||||
rekordy instalacji npm. Zwykłe ścieżki archiwów nadal instalują jako archiwa lokalne
|
||||
rekordy instalacji npm. Zwykłe ścieżki archiwów nadal instalują się jako archiwa lokalne
|
||||
pod katalogiem głównym rozszerzeń pluginów.
|
||||
|
||||
Obsługiwane są także instalacje z Claude marketplace.
|
||||
Instalacje Claude marketplace są również obsługiwane.
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
@ -176,25 +176,25 @@ openclaw plugins install clawhub:openclaw-codex-app-server
|
||||
openclaw plugins install clawhub:openclaw-codex-app-server@1.2.3
|
||||
```
|
||||
|
||||
Nagie specyfikacje pluginów bezpieczne dla npm instalują z npm domyślnie podczas przejścia startowego:
|
||||
Same specyfikacje pluginów bezpieczne dla npm podczas przejścia po uruchomieniu instalują domyślnie z npm:
|
||||
|
||||
```bash
|
||||
openclaw plugins install openclaw-codex-app-server
|
||||
```
|
||||
|
||||
Użyj `npm:`, aby jawnie wybrać rozwiązywanie wyłącznie przez npm:
|
||||
Użyj `npm:`, aby jawnie wskazać rozwiązywanie tylko przez npm:
|
||||
|
||||
```bash
|
||||
openclaw plugins install npm:openclaw-codex-app-server
|
||||
openclaw plugins install npm:@scope/plugin-name@1.0.1
|
||||
```
|
||||
|
||||
OpenClaw sprawdza deklarowaną zgodność API pluginu / minimalną zgodność Gateway przed instalacją. Gdy wybrana wersja ClawHub publikuje artefakt ClawPack, OpenClaw pobiera wersjonowany `.tgz` npm-pack, weryfikuje nagłówek skrótu ClawHub i skrót artefaktu, a następnie instaluje go przez zwykłą ścieżkę archiwum. Starsze wersje ClawHub bez metadanych ClawPack nadal instalują przez starszą ścieżkę weryfikacji archiwum pakietu. Zarejestrowane instalacje zachowują metadane źródła ClawHub, rodzaj artefaktu, integralność npm, shasum npm, nazwę tarballa i fakty dotyczące skrótu ClawPack na potrzeby późniejszych aktualizacji.
|
||||
OpenClaw sprawdza reklamowaną zgodność API pluginu / minimalną zgodność Gateway przed instalacją. Gdy wybrana wersja ClawHub publikuje artefakt ClawPack, OpenClaw pobiera wersjonowany `.tgz` npm-pack, weryfikuje nagłówek digest ClawHub i digest artefaktu, a następnie instaluje go przez normalną ścieżkę archiwum. Starsze wersje ClawHub bez metadanych ClawPack nadal instalują się przez starszą ścieżkę weryfikacji archiwum pakietu. Zarejestrowane instalacje zachowują metadane źródła ClawHub, rodzaj artefaktu, integralność npm, shasum npm, nazwę tarballa i fakty digest ClawPack do późniejszych aktualizacji.
|
||||
Niewersjonowane instalacje ClawHub zachowują niewersjonowaną zarejestrowaną specyfikację, aby `openclaw plugins update` mógł śledzić nowsze wydania ClawHub; jawne selektory wersji lub tagów, takie jak `clawhub:pkg@1.2.3` i `clawhub:pkg@beta`, pozostają przypięte do tego selektora.
|
||||
|
||||
#### Skrót marketplace
|
||||
|
||||
Użyj skrótu `plugin@marketplace`, gdy nazwa marketplace istnieje w lokalnej pamięci podręcznej rejestru Claude pod adresem `~/.claude/plugins/known_marketplaces.json`:
|
||||
Użyj skrótu `plugin@marketplace`, gdy nazwa marketplace istnieje w lokalnej pamięci podręcznej rejestru Claude pod `~/.claude/plugins/known_marketplaces.json`:
|
||||
|
||||
```bash
|
||||
openclaw plugins marketplace list <marketplace-name>
|
||||
@ -211,28 +211,28 @@ openclaw plugins install <plugin-name> --marketplace ./my-marketplace
|
||||
```
|
||||
|
||||
<Tabs>
|
||||
<Tab title="Źródła marketplace">
|
||||
- znana nazwa marketplace Claude z `~/.claude/plugins/known_marketplaces.json`
|
||||
- lokalny katalog główny marketplace albo ścieżka `marketplace.json`
|
||||
<Tab title="Marketplace sources">
|
||||
- nazwa znanego marketplace Claude z `~/.claude/plugins/known_marketplaces.json`
|
||||
- lokalny katalog główny marketplace lub ścieżka `marketplace.json`
|
||||
- skrót repozytorium GitHub, taki jak `owner/repo`
|
||||
- URL repozytorium GitHub, taki jak `https://github.com/owner/repo`
|
||||
- URL git
|
||||
|
||||
</Tab>
|
||||
<Tab title="Reguły zdalnego marketplace">
|
||||
W przypadku zdalnych marketplace ładowanych z GitHub lub git wpisy pluginów muszą pozostać wewnątrz sklonowanego repozytorium marketplace. OpenClaw akceptuje względne źródła ścieżek z tego repozytorium i odrzuca HTTP(S), ścieżki bezwzględne, git, GitHub oraz inne niebędące ścieżkami źródła pluginów ze zdalnych manifestów.
|
||||
<Tab title="Remote marketplace rules">
|
||||
W przypadku zdalnych marketplace ładowanych z GitHub lub git wpisy Plugin muszą pozostawać wewnątrz sklonowanego repozytorium marketplace. OpenClaw akceptuje źródła ze ścieżką względną z tego repozytorium i odrzuca HTTP(S), ścieżki bezwzględne, git, GitHub oraz inne niebędące ścieżkami źródła Plugin ze zdalnych manifestów.
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
Dla lokalnych ścieżek i archiwów OpenClaw wykrywa automatycznie:
|
||||
W przypadku ścieżek lokalnych i archiwów OpenClaw automatycznie wykrywa:
|
||||
|
||||
- natywne pluginy OpenClaw (`openclaw.plugin.json`)
|
||||
- natywne Plugin OpenClaw (`openclaw.plugin.json`)
|
||||
- pakiety zgodne z Codex (`.codex-plugin/plugin.json`)
|
||||
- pakiety zgodne z Claude (`.claude-plugin/plugin.json` albo domyślny układ komponentów Claude)
|
||||
- pakiety zgodne z Claude (`.claude-plugin/plugin.json` lub domyślny układ komponentów Claude)
|
||||
- pakiety zgodne z Cursor (`.cursor-plugin/plugin.json`)
|
||||
|
||||
<Note>
|
||||
Zgodne pakiety instalują się w normalnym katalogu głównym pluginów i uczestniczą w tym samym przepływie wyświetlania informacji, włączania i wyłączania. Obecnie obsługiwane są Skills pakietów, umiejętności poleceń Claude, domyślne wartości Claude `settings.json`, domyślne wartości Claude `.lsp.json` / zadeklarowane w manifeście `lspServers`, umiejętności poleceń Cursor oraz zgodne katalogi hooków Codex; inne wykryte możliwości pakietów są pokazywane w diagnostyce/informacjach, ale nie są jeszcze podłączone do wykonywania w środowisku uruchomieniowym.
|
||||
Zgodne pakiety instalują się w normalnym katalogu głównym Plugin i uczestniczą w tym samym przepływie wyświetlania informacji, włączania i wyłączania. Obecnie obsługiwane są Skills pakietów, command-skills Claude, wartości domyślne `settings.json` Claude, wartości domyślne `.lsp.json` Claude / zadeklarowane w manifeście `lspServers`, command-skills Cursor oraz zgodne katalogi hooków Codex; inne wykryte możliwości pakietów są pokazywane w diagnostyce/informacjach, ale nie są jeszcze podłączone do wykonywania w czasie działania.
|
||||
</Note>
|
||||
|
||||
### Lista
|
||||
@ -248,43 +248,41 @@ openclaw plugins search <query> --json
|
||||
```
|
||||
|
||||
<ParamField path="--enabled" type="boolean">
|
||||
Pokaż tylko włączone pluginy.
|
||||
Pokaż tylko włączone Plugin.
|
||||
</ParamField>
|
||||
<ParamField path="--verbose" type="boolean">
|
||||
Przełącz z widoku tabeli na szczegółowe wiersze dla każdego pluginu z metadanymi źródła/pochodzenia/wersji/aktywacji.
|
||||
Przełącz z widoku tabeli na wiersze szczegółów dla każdego Plugin, z metadanymi źródła/pochodzenia/wersji/aktywacji.
|
||||
</ParamField>
|
||||
<ParamField path="--json" type="boolean">
|
||||
Inwentarz czytelny maszynowo oraz diagnostyka rejestru i stan instalacji zależności pakietów.
|
||||
</ParamField>
|
||||
|
||||
<Note>
|
||||
`plugins list` najpierw odczytuje utrwalony lokalny rejestr pluginów, z awaryjną wersją wyprowadzoną wyłącznie z manifestów, gdy rejestr nie istnieje lub jest nieprawidłowy. Jest to przydatne do sprawdzania, czy plugin jest zainstalowany, włączony i widoczny dla planowania zimnego startu, ale nie jest to sonda aktywnego środowiska uruchomieniowego już działającego procesu Gateway. Po zmianie kodu pluginu, włączenia, zasad hooków lub `plugins.load.paths` uruchom ponownie Gateway obsługujący kanał, zanim zaczniesz oczekiwać, że nowy kod `register(api)` lub hooki zostaną uruchomione. W przypadku wdrożeń zdalnych/kontenerowych sprawdź, czy restartujesz rzeczywisty proces podrzędny `openclaw gateway run`, a nie tylko proces opakowujący.
|
||||
`plugins list` najpierw odczytuje utrwalony lokalny rejestr Plugin, z awaryjnym wariantem wyprowadzanym wyłącznie z manifestów, gdy rejestr jest brakujący lub nieprawidłowy. Przydaje się do sprawdzenia, czy Plugin jest zainstalowany, włączony i widoczny dla planowania zimnego startu, ale nie jest sondą czasu działania działającego już procesu Gateway. Po zmianie kodu Plugin, stanu włączenia, zasad hooków lub `plugins.load.paths` uruchom ponownie Gateway obsługujący kanał, zanim będziesz oczekiwać uruchomienia nowego kodu `register(api)` lub hooków. W przypadku wdrożeń zdalnych/kontenerowych sprawdź, czy restartujesz rzeczywisty proces potomny `openclaw gateway run`, a nie tylko proces opakowujący.
|
||||
|
||||
`plugins list --json` zawiera `dependencyStatus` każdego pluginu z `package.json`
|
||||
`plugins list --json` obejmuje `dependencyStatus` każdego Plugin z `package.json`
|
||||
`dependencies` i `optionalDependencies`. OpenClaw sprawdza, czy te nazwy pakietów
|
||||
są obecne na normalnej ścieżce wyszukiwania Node `node_modules` pluginu; nie
|
||||
importuje kodu środowiska uruchomieniowego pluginu, nie uruchamia menedżera
|
||||
pakietów ani nie naprawia brakujących zależności.
|
||||
są obecne w normalnej ścieżce wyszukiwania `node_modules` danego Plugin w Node; nie
|
||||
importuje kodu czasu działania Plugin, nie uruchamia menedżera pakietów ani nie naprawia
|
||||
brakujących zależności.
|
||||
</Note>
|
||||
|
||||
`plugins search` to zdalne wyszukiwanie w katalogu ClawHub. Nie sprawdza lokalnego
|
||||
stanu, nie modyfikuje konfiguracji, nie instaluje pakietów ani nie ładuje kodu
|
||||
środowiska uruchomieniowego pluginu. Wyniki wyszukiwania zawierają nazwę pakietu
|
||||
ClawHub, rodzinę, kanał, wersję, podsumowanie oraz wskazówkę instalacji, taką jak
|
||||
`openclaw plugins install clawhub:<package>`.
|
||||
`plugins search` to zdalne wyszukiwanie w katalogu ClawHub. Nie sprawdza stanu
|
||||
lokalnego, nie modyfikuje konfiguracji, nie instaluje pakietów ani nie ładuje kodu
|
||||
czasu działania Plugin. Wyniki wyszukiwania obejmują nazwę pakietu ClawHub, rodzinę,
|
||||
kanał, wersję, podsumowanie oraz wskazówkę instalacji, taką jak `openclaw plugins install clawhub:<package>`.
|
||||
|
||||
Podczas pracy nad wbudowanym pluginem wewnątrz spakowanego obrazu Docker zamontuj
|
||||
katalog źródłowy pluginu przez bind mount na pasującej spakowanej ścieżce źródłowej,
|
||||
takiej jak `/app/extensions/synology-chat`. OpenClaw wykryje tę zamontowaną
|
||||
nakładkę źródłową przed `/app/dist/extensions/synology-chat`; zwykły skopiowany
|
||||
katalog źródłowy pozostanie nieaktywny, więc normalne spakowane instalacje nadal
|
||||
używają skompilowanego dist.
|
||||
W przypadku pracy nad dołączonym Plugin wewnątrz spakowanego obrazu Docker zamontuj przez bind katalog
|
||||
źródłowy Plugin na odpowiadającej mu spakowanej ścieżce źródłowej, takiej jak
|
||||
`/app/extensions/synology-chat`. OpenClaw wykryje tę zamontowaną nakładkę źródłową
|
||||
przed `/app/dist/extensions/synology-chat`; zwykły skopiowany katalog źródłowy
|
||||
pozostaje bezczynny, dzięki czemu normalne instalacje pakietowe nadal używają skompilowanego dist.
|
||||
|
||||
Do debugowania hooków środowiska uruchomieniowego:
|
||||
Do debugowania hooków czasu działania:
|
||||
|
||||
- `openclaw plugins inspect <id> --runtime --json` pokazuje zarejestrowane hooki i diagnostykę z przebiegu inspekcji z załadowanym modułem. Inspekcja środowiska uruchomieniowego nigdy nie instaluje zależności; użyj `openclaw doctor --fix`, aby wyczyścić starszy stan zależności lub odzyskać brakujące pluginy możliwe do pobrania, do których odwołuje się konfiguracja.
|
||||
- `openclaw plugins inspect <id> --runtime --json` pokazuje zarejestrowane hooki i diagnostykę z przebiegu inspekcji z załadowanym modułem. Inspekcja czasu działania nigdy nie instaluje zależności; użyj `openclaw doctor --fix`, aby wyczyścić starszy stan zależności lub odzyskać brakujące pobieralne Plugin, do których odwołuje się konfiguracja.
|
||||
- `openclaw gateway status --deep --require-rpc` potwierdza osiągalny Gateway, wskazówki dotyczące usługi/procesu, ścieżkę konfiguracji i kondycję RPC.
|
||||
- Niewbudowane hooki konwersacji (`llm_input`, `llm_output`, `before_agent_finalize`, `agent_end`) wymagają `plugins.entries.<id>.hooks.allowConversationAccess=true`.
|
||||
- Niedostarczane w pakiecie hooki konwersacji (`llm_input`, `llm_output`, `before_agent_finalize`, `agent_end`) wymagają `plugins.entries.<id>.hooks.allowConversationAccess=true`.
|
||||
|
||||
Użyj `--link`, aby uniknąć kopiowania lokalnego katalogu (dodaje do `plugins.load.paths`):
|
||||
|
||||
@ -293,16 +291,16 @@ openclaw plugins install -l ./my-plugin
|
||||
```
|
||||
|
||||
<Note>
|
||||
`--force` nie jest obsługiwane z `--link`, ponieważ instalacje linkowane ponownie używają ścieżki źródłowej zamiast kopiować na zarządzany cel instalacji.
|
||||
`--force` nie jest obsługiwane z `--link`, ponieważ instalacje linkowane ponownie używają ścieżki źródłowej zamiast kopiować nad zarządzanym celem instalacji.
|
||||
|
||||
Użyj `--pin` przy instalacjach npm, aby zapisać rozwiązaną dokładną specyfikację (`name@version`) w zarządzanym indeksie pluginów, zachowując domyślne zachowanie bez przypięcia.
|
||||
Użyj `--pin` przy instalacjach npm, aby zapisać rozwiązaną dokładną specyfikację (`name@version`) w zarządzanym indeksie Plugin, zachowując domyślne zachowanie bez przypinania.
|
||||
</Note>
|
||||
|
||||
### Indeks pluginów
|
||||
### Indeks Plugin
|
||||
|
||||
Metadane instalacji pluginów to stan zarządzany maszynowo, a nie konfiguracja użytkownika. Instalacje i aktualizacje zapisują je do `plugins/installs.json` w aktywnym katalogu stanu OpenClaw. Jego mapa najwyższego poziomu `installRecords` jest trwałym źródłem metadanych instalacji, w tym rekordów uszkodzonych lub brakujących manifestów pluginów. Tablica `plugins` to wyprowadzona z manifestów pamięć podręczna zimnego rejestru. Plik zawiera ostrzeżenie, aby go nie edytować, i jest używany przez `openclaw plugins update`, odinstalowanie, diagnostykę oraz zimny rejestr pluginów.
|
||||
Metadane instalacji Plugin są stanem zarządzanym maszynowo, a nie konfiguracją użytkownika. Instalacje i aktualizacje zapisują je do `plugins/installs.json` w aktywnym katalogu stanu OpenClaw. Jego mapa najwyższego poziomu `installRecords` jest trwałym źródłem metadanych instalacji, w tym rekordów dla uszkodzonych lub brakujących manifestów Plugin. Tablica `plugins` jest pochodzącą z manifestów pamięcią podręczną rejestru zimnego startu. Plik zawiera ostrzeżenie, aby go nie edytować, i jest używany przez `openclaw plugins update`, odinstalowanie, diagnostykę oraz zimny rejestr Plugin.
|
||||
|
||||
Gdy OpenClaw zobaczy dostarczone starsze rekordy `plugins.installs` w konfiguracji, przenosi je do indeksu pluginów i usuwa klucz konfiguracji; jeśli którykolwiek zapis się nie powiedzie, rekordy konfiguracji są zachowywane, aby metadane instalacji nie zostały utracone.
|
||||
Gdy OpenClaw znajdzie dostarczone starsze rekordy `plugins.installs` w konfiguracji, przenosi je do indeksu Plugin i usuwa klucz konfiguracji; jeśli którykolwiek zapis się nie powiedzie, rekordy konfiguracji zostają zachowane, aby metadane instalacji nie zostały utracone.
|
||||
|
||||
### Odinstalowanie
|
||||
|
||||
@ -312,10 +310,10 @@ openclaw plugins uninstall <id> --dry-run
|
||||
openclaw plugins uninstall <id> --keep-files
|
||||
```
|
||||
|
||||
`uninstall` usuwa rekordy pluginu z `plugins.entries`, utrwalonego indeksu pluginów, wpisów listy dozwolonych/zabronionych pluginów oraz linkowanych wpisów `plugins.load.paths`, gdy ma to zastosowanie. O ile nie ustawiono `--keep-files`, odinstalowanie usuwa także śledzony zarządzany katalog instalacji, gdy znajduje się on w katalogu głównym rozszerzeń pluginów OpenClaw. W przypadku pluginów aktywnej pamięci slot pamięci resetuje się do `memory-core`.
|
||||
`uninstall` usuwa rekordy Plugin z `plugins.entries`, utrwalonego indeksu Plugin, wpisów list zezwalania/odmawiania Plugin oraz linkowanych wpisów `plugins.load.paths`, gdy ma to zastosowanie. O ile nie ustawiono `--keep-files`, odinstalowanie usuwa również śledzony zarządzany katalog instalacji, gdy znajduje się on w głównym katalogu rozszerzeń Plugin OpenClaw. W przypadku Plugin aktywnej pamięci slot pamięci resetuje się do `memory-core`.
|
||||
|
||||
<Note>
|
||||
`--keep-config` jest obsługiwane jako przestarzały alias `--keep-files`.
|
||||
`--keep-config` jest obsługiwane jako przestarzały alias dla `--keep-files`.
|
||||
</Note>
|
||||
|
||||
### Aktualizacja
|
||||
@ -328,29 +326,29 @@ openclaw plugins update @openclaw/voice-call
|
||||
openclaw plugins update openclaw-codex-app-server --dangerously-force-unsafe-install
|
||||
```
|
||||
|
||||
Aktualizacje dotyczą śledzonych instalacji pluginów w zarządzanym indeksie pluginów oraz śledzonych instalacji pakietów hooków w `hooks.internal.installs`.
|
||||
Aktualizacje dotyczą śledzonych instalacji Plugin w zarządzanym indeksie Plugin oraz śledzonych instalacji hook-pack w `hooks.internal.installs`.
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Rozwiązywanie identyfikatora pluginu względem specyfikacji npm">
|
||||
Gdy przekazujesz identyfikator pluginu, OpenClaw ponownie używa zapisanej specyfikacji instalacji dla tego pluginu. Oznacza to, że wcześniej zapisane dist-tagi, takie jak `@beta`, oraz dokładne przypięte wersje nadal będą używane przy późniejszych uruchomieniach `update <id>`.
|
||||
<Accordion title="Resolving plugin id vs npm spec">
|
||||
Gdy przekażesz identyfikator Plugin, OpenClaw ponownie użyje zapisanej specyfikacji instalacji dla tego Plugin. Oznacza to, że wcześniej zapisane dist-tags, takie jak `@beta`, oraz dokładnie przypięte wersje nadal będą używane przy późniejszych uruchomieniach `update <id>`.
|
||||
|
||||
W przypadku instalacji npm możesz także przekazać jawną specyfikację pakietu npm z dist-tagiem lub dokładną wersją. OpenClaw rozwiązuje tę nazwę pakietu z powrotem do śledzonego rekordu pluginu, aktualizuje ten zainstalowany plugin i zapisuje nową specyfikację npm dla przyszłych aktualizacji opartych na identyfikatorze.
|
||||
W przypadku instalacji npm możesz także przekazać jawną specyfikację pakietu npm z dist-tag lub dokładną wersją. OpenClaw rozwiązuje tę nazwę pakietu z powrotem do śledzonego rekordu Plugin, aktualizuje ten zainstalowany Plugin i zapisuje nową specyfikację npm na potrzeby przyszłych aktualizacji opartych na identyfikatorze.
|
||||
|
||||
Przekazanie nazwy pakietu npm bez wersji ani tagu także rozwiązuje się z powrotem do śledzonego rekordu pluginu. Użyj tego, gdy plugin był przypięty do dokładnej wersji i chcesz przenieść go z powrotem na domyślną linię wydania rejestru.
|
||||
Przekazanie nazwy pakietu npm bez wersji lub tagu także rozwiązuje się z powrotem do śledzonego rekordu Plugin. Użyj tego, gdy Plugin został przypięty do dokładnej wersji i chcesz przenieść go z powrotem na domyślną linię wydań rejestru.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Aktualizacje kanału beta">
|
||||
`openclaw plugins update` ponownie używa śledzonej specyfikacji pluginu, chyba że przekażesz nową specyfikację. `openclaw update` dodatkowo zna aktywny kanał aktualizacji OpenClaw: na kanale beta rekordy pluginów npm z domyślnej linii i ClawHub najpierw próbują `@beta`, a potem wracają do zapisanej domyślnej/najnowszej specyfikacji, jeśli nie istnieje wydanie beta pluginu. Dokładne wersje i jawne tagi pozostają przypięte do tego selektora.
|
||||
<Accordion title="Beta channel updates">
|
||||
`openclaw plugins update` ponownie używa śledzonej specyfikacji Plugin, chyba że przekażesz nową specyfikację. `openclaw update` dodatkowo zna aktywny kanał aktualizacji OpenClaw: na kanale beta domyślne rekordy npm i Plugin ClawHub najpierw próbują `@beta`, a następnie wracają do zapisanej domyślnej/najnowszej specyfikacji, jeśli nie istnieje wydanie beta Plugin. Dokładne wersje i jawne tagi pozostają przypięte do tego selektora.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Kontrole wersji i dryf integralności">
|
||||
Przed aktualizacją npm na żywo OpenClaw sprawdza zainstalowaną wersję pakietu względem metadanych rejestru npm. Jeśli zainstalowana wersja i zapisana tożsamość artefaktu już pasują do rozwiązanego celu, aktualizacja jest pomijana bez pobierania, ponownej instalacji ani przepisywania `openclaw.json`.
|
||||
<Accordion title="Version checks and integrity drift">
|
||||
Przed aktualizacją npm na żywo OpenClaw sprawdza wersję zainstalowanego pakietu względem metadanych rejestru npm. Jeśli zainstalowana wersja i zapisana tożsamość artefaktu już pasują do rozwiązanego celu, aktualizacja jest pomijana bez pobierania, ponownej instalacji ani przepisywania `openclaw.json`.
|
||||
|
||||
Gdy istnieje zapisany hash integralności, a hash pobranego artefaktu się zmienia, OpenClaw traktuje to jako dryf artefaktu npm. Interaktywne polecenie `openclaw plugins update` wypisuje oczekiwany i rzeczywisty hash oraz prosi o potwierdzenie przed kontynuacją. Nieinteraktywne pomocniki aktualizacji kończą się bezpieczną porażką, chyba że wywołujący dostarczy jawną politykę kontynuacji.
|
||||
Gdy istnieje zapisany hash integralności, a hash pobranego artefaktu się zmienia, OpenClaw traktuje to jako dryf artefaktu npm. Interaktywne polecenie `openclaw plugins update` wypisuje oczekiwane i rzeczywiste hashe oraz prosi o potwierdzenie przed kontynuacją. Nieinteraktywne pomocniki aktualizacji kończą się w trybie fail-closed, chyba że wywołujący poda jawną politykę kontynuacji.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="--dangerously-force-unsafe-install przy aktualizacji">
|
||||
`--dangerously-force-unsafe-install` jest także dostępne w `plugins update` jako awaryjne obejście fałszywych alarmów wbudowanego skanowania niebezpiecznego kodu podczas aktualizacji pluginów. Nadal nie omija blokad polityki `before_install` pluginu ani blokowania po niepowodzeniu skanowania i dotyczy wyłącznie aktualizacji pluginów, a nie aktualizacji pakietów hooków.
|
||||
<Accordion title="--dangerously-force-unsafe-install on update">
|
||||
`--dangerously-force-unsafe-install` jest również dostępne w `plugins update` jako awaryjne obejście fałszywych alarmów wbudowanego skanowania niebezpiecznego kodu podczas aktualizacji Plugin. Nadal nie omija blokad polityki `before_install` Plugin ani blokowania po niepowodzeniu skanowania i ma zastosowanie tylko do aktualizacji Plugin, a nie aktualizacji hook-pack.
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
@ -362,21 +360,21 @@ openclaw plugins inspect <id> --runtime
|
||||
openclaw plugins inspect <id> --json
|
||||
```
|
||||
|
||||
Inspekcja pokazuje tożsamość, stan ładowania, źródło, możliwości manifestu, flagi polityki, diagnostykę, metadane instalacji, możliwości pakietu oraz wszelkie wykryte wsparcie serwera MCP lub LSP bez domyślnego importowania środowiska uruchomieniowego pluginu. Dodaj `--runtime`, aby załadować moduł pluginu i dołączyć zarejestrowane hooki, narzędzia, polecenia, usługi, metody Gateway i trasy HTTP. Inspekcja środowiska uruchomieniowego zgłasza brakujące zależności pluginu bezpośrednio; instalacje i naprawy pozostają w `openclaw plugins install`, `openclaw plugins update` i `openclaw doctor --fix`.
|
||||
Inspekcja pokazuje tożsamość, stan ładowania, źródło, możliwości manifestu, flagi polityk, diagnostykę, metadane instalacji, możliwości pakietu oraz wykryte wsparcie serwerów MCP lub LSP bez domyślnego importowania kodu czasu działania Plugin. Dodaj `--runtime`, aby załadować moduł Plugin i uwzględnić zarejestrowane hooki, narzędzia, polecenia, usługi, metody Gateway i trasy HTTP. Inspekcja czasu działania raportuje brakujące zależności Plugin bezpośrednio; instalacje i naprawy pozostają w `openclaw plugins install`, `openclaw plugins update` oraz `openclaw doctor --fix`.
|
||||
|
||||
Polecenia CLI należące do pluginu są instalowane jako główne grupy poleceń `openclaw`. Gdy `inspect --runtime` pokaże polecenie pod `cliCommands`, uruchom je jako `openclaw <command> ...`; na przykład plugin rejestrujący `demo-git` można zweryfikować za pomocą `openclaw demo-git ping`.
|
||||
Polecenia CLI należące do Plugin są instalowane jako główne grupy poleceń `openclaw`. Po tym, jak `inspect --runtime` pokaże polecenie pod `cliCommands`, uruchom je jako `openclaw <command> ...`; na przykład Plugin rejestrujący `demo-git` można zweryfikować za pomocą `openclaw demo-git ping`.
|
||||
|
||||
Każdy plugin jest klasyfikowany według tego, co faktycznie rejestruje w środowisku uruchomieniowym:
|
||||
Każdy Plugin jest klasyfikowany według tego, co faktycznie rejestruje w czasie działania:
|
||||
|
||||
- **plain-capability** — jeden typ możliwości (np. plugin tylko dostawcy)
|
||||
- **plain-capability** — jeden typ możliwości (np. Plugin tylko dla dostawcy)
|
||||
- **hybrid-capability** — wiele typów możliwości (np. tekst + mowa + obrazy)
|
||||
- **hook-only** — tylko hooki, bez możliwości ani powierzchni
|
||||
- **non-capability** — narzędzia/polecenia/usługi, ale bez możliwości
|
||||
|
||||
Zobacz [Kształty pluginów](/pl/plugins/architecture#plugin-shapes), aby dowiedzieć się więcej o modelu możliwości.
|
||||
Zobacz [kształty Plugin](/pl/plugins/architecture#plugin-shapes), aby dowiedzieć się więcej o modelu możliwości.
|
||||
|
||||
<Note>
|
||||
Flaga `--json` wypisuje raport czytelny maszynowo, odpowiedni do skryptowania i audytu. `inspect --all` renderuje tabelę dla całego zestawu z kolumnami kształtu, rodzajów możliwości, powiadomień o zgodności, możliwości pakietu i podsumowania hooków. `info` jest aliasem `inspect`.
|
||||
Flaga `--json` generuje raport czytelny maszynowo, odpowiedni do skryptów i audytów. `inspect --all` renderuje tabelę dla całej floty z kolumnami kształtu, rodzajów możliwości, powiadomień o zgodności, możliwości pakietu i podsumowania hooków. `info` jest aliasem dla `inspect`.
|
||||
</Note>
|
||||
|
||||
### Doctor
|
||||
@ -385,11 +383,11 @@ Flaga `--json` wypisuje raport czytelny maszynowo, odpowiedni do skryptowania i
|
||||
openclaw plugins doctor
|
||||
```
|
||||
|
||||
`doctor` zgłasza błędy ładowania pluginów, diagnostykę manifestu/wykrywania oraz powiadomienia o zgodności. Gdy wszystko jest czyste, wypisuje `No plugin issues detected.`
|
||||
`doctor` raportuje błędy ładowania Plugin, diagnostykę manifestu/wykrywania oraz powiadomienia o zgodności. Gdy wszystko jest w porządku, wypisuje `No plugin issues detected.`
|
||||
|
||||
Jeśli skonfigurowany plugin jest obecny na dysku, ale zablokowany przez kontrole bezpieczeństwa ścieżki loadera, walidacja konfiguracji zachowuje wpis pluginu i zgłasza go jako `present but blocked`. Napraw poprzedzającą diagnostykę zablokowanego pluginu, taką jak własność ścieżki lub uprawnienia do zapisu dla wszystkich, zamiast usuwać konfigurację `plugins.entries.<id>` albo `plugins.allow`.
|
||||
Jeśli skonfigurowany Plugin jest obecny na dysku, ale zablokowany przez kontrole bezpieczeństwa ścieżek w loaderze, walidacja konfiguracji zachowuje wpis Plugin i raportuje go jako `present but blocked`. Napraw poprzedzającą diagnostykę zablokowanego Plugin, taką jak własność ścieżki lub uprawnienia do zapisu dla wszystkich, zamiast usuwać konfigurację `plugins.entries.<id>` lub `plugins.allow`.
|
||||
|
||||
W przypadku awarii kształtu modułu, takich jak brakujące eksporty `register`/`activate`, uruchom ponownie z `OPENCLAW_PLUGIN_LOAD_DEBUG=1`, aby dołączyć zwarte podsumowanie kształtu eksportów w wyjściu diagnostycznym.
|
||||
W przypadku awarii kształtu modułu, takich jak brakujące eksporty `register`/`activate`, uruchom ponownie z `OPENCLAW_PLUGIN_LOAD_DEBUG=1`, aby uwzględnić zwięzłe podsumowanie kształtu eksportów w wyjściu diagnostycznym.
|
||||
|
||||
### Rejestr
|
||||
|
||||
@ -399,14 +397,14 @@ openclaw plugins registry --refresh
|
||||
openclaw plugins registry --json
|
||||
```
|
||||
|
||||
Lokalny rejestr pluginów to utrwalony model zimnego odczytu OpenClaw dla tożsamości zainstalowanych pluginów, ich włączenia, metadanych źródła i własności wkładu. Normalne uruchamianie, wyszukiwanie właściciela dostawcy, klasyfikacja konfiguracji kanałów i inwentarz pluginów mogą go odczytywać bez importowania modułów wykonawczych pluginów.
|
||||
Lokalny rejestr Plugin to utrwalony model zimnego odczytu OpenClaw dla tożsamości zainstalowanych Plugin, ich włączenia, metadanych źródła i własności wkładów. Normalne uruchamianie, wyszukiwanie właściciela dostawcy, klasyfikacja konfiguracji kanałów i inwentarz Plugin mogą go odczytywać bez importowania modułów środowiska uruchomieniowego Plugin.
|
||||
|
||||
Użyj `plugins registry`, aby sprawdzić, czy utrwalony rejestr jest obecny, aktualny lub przestarzały. Użyj `--refresh`, aby odbudować go z utrwalonego indeksu pluginów, polityki konfiguracji oraz metadanych manifestu/pakietu. To ścieżka naprawy, a nie ścieżka aktywacji w czasie wykonywania.
|
||||
Użyj `plugins registry`, aby sprawdzić, czy utrwalony rejestr jest obecny, aktualny lub nieaktualny. Użyj `--refresh`, aby odbudować go z utrwalonego indeksu Plugin, zasad konfiguracji oraz metadanych manifestu/pakietu. To ścieżka naprawy, a nie ścieżka aktywacji w czasie działania.
|
||||
|
||||
`openclaw doctor --fix` naprawia także dryf zarządzanego npm sąsiadujący z rejestrem: jeśli osierocony lub odzyskany pakiet `@openclaw/*` pod zarządzanym głównym katalogiem npm pluginów przesłania wbudowany plugin, doctor usuwa ten przestarzały pakiet i odbudowuje rejestr, aby uruchamianie walidowało się względem wbudowanego manifestu.
|
||||
`openclaw doctor --fix` naprawia również dryf zarządzanych npm przyległy do rejestru: jeśli osierocony lub odzyskany pakiet `@openclaw/*` w zarządzanym katalogu głównym npm Plugin przesłania wbudowany Plugin, doctor usuwa ten nieaktualny pakiet i odbudowuje rejestr, aby uruchamianie walidowało względem wbudowanego manifestu.
|
||||
|
||||
<Warning>
|
||||
`OPENCLAW_DISABLE_PERSISTED_PLUGIN_REGISTRY=1` to przestarzały awaryjny przełącznik zgodności na wypadek błędów odczytu rejestru. Preferuj `plugins registry --refresh` lub `openclaw doctor --fix`; awaryjne użycie zmiennej środowiskowej służy tylko do odzyskiwania uruchamiania w sytuacji krytycznej podczas wdrażania migracji.
|
||||
`OPENCLAW_DISABLE_PERSISTED_PLUGIN_REGISTRY=1` to przestarzały awaryjny przełącznik zgodności na wypadek błędów odczytu rejestru. Preferuj `plugins registry --refresh` lub `openclaw doctor --fix`; awaryjna opcja env służy wyłącznie do odzyskiwania uruchamiania w sytuacjach nagłych podczas wdrażania migracji.
|
||||
</Warning>
|
||||
|
||||
### Marketplace
|
||||
@ -416,7 +414,7 @@ openclaw plugins marketplace list <source>
|
||||
openclaw plugins marketplace list <source> --json
|
||||
```
|
||||
|
||||
Lista Marketplace akceptuje lokalną ścieżkę marketplace, ścieżkę `marketplace.json`, skrót GitHub w formie `owner/repo`, URL repozytorium GitHub albo URL git. `--json` wypisuje rozwiązaną etykietę źródła oraz sparsowany manifest marketplace i wpisy pluginów.
|
||||
`marketplace list` przyjmuje ścieżkę do lokalnego marketplace, ścieżkę do `marketplace.json`, skrót GitHub w rodzaju `owner/repo`, adres URL repozytorium GitHub albo adres URL git. `--json` wypisuje rozpoznaną etykietę źródła oraz przeanalizowany manifest marketplace i wpisy pluginów.
|
||||
|
||||
## Powiązane
|
||||
|
||||
|
||||
@ -1,40 +1,40 @@
|
||||
---
|
||||
read_when:
|
||||
- Chcesz wysyłać dane o użyciu modelu OpenClaw, przepływie wiadomości lub metrykach sesji do kolektora OpenTelemetry
|
||||
- Integrujesz ślady, metryki lub logi z Grafana, Datadog, Honeycomb, New Relic, Tempo lub innym backendem OTLP
|
||||
- Do tworzenia pulpitów nawigacyjnych lub alertów potrzebne są dokładne nazwy metryk, nazwy spanów albo struktury atrybutów.
|
||||
summary: Eksportuj diagnostykę OpenClaw do dowolnego kolektora OpenTelemetry za pomocą pluginu diagnostics-otel (OTLP/HTTP)
|
||||
- Chcesz wysyłać metryki OpenClaw dotyczące użycia modeli, przepływu wiadomości lub sesji do kolektora OpenTelemetry
|
||||
- Podłączasz ślady, metryki lub logi do Grafana, Datadog, Honeycomb, New Relic, Tempo albo innego zaplecza OTLP
|
||||
- Potrzebujesz dokładnych nazw metryk, nazw spanów lub struktur atrybutów, aby tworzyć pulpity nawigacyjne lub alerty
|
||||
summary: Eksportuj dane diagnostyczne OpenClaw do dowolnego kolektora OpenTelemetry za pośrednictwem Plugin diagnostics-otel (OTLP/HTTP)
|
||||
title: Eksport OpenTelemetry
|
||||
x-i18n:
|
||||
generated_at: "2026-05-06T09:14:13Z"
|
||||
generated_at: "2026-05-06T10:05:24Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 2d52e5072fcdb097a3dce36a13d9470cea8c169d2af49998cd727814013c411e
|
||||
source_hash: b09453a4a1592d2698de6340e5f006ef16edfd8e86132285c48865d468d20ab6
|
||||
source_path: gateway/opentelemetry.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
OpenClaw eksportuje diagnostykę przez oficjalny plugin `diagnostics-otel`
|
||||
za pomocą **OTLP/HTTP (protobuf)**. Każdy kolektor lub backend akceptujący OTLP/HTTP
|
||||
OpenClaw eksportuje diagnostykę przez oficjalny Plugin `diagnostics-otel`
|
||||
przy użyciu **OTLP/HTTP (protobuf)**. Każdy kolektor lub backend akceptujący OTLP/HTTP
|
||||
działa bez zmian w kodzie. Informacje o lokalnych logach plikowych i sposobie ich odczytywania znajdziesz w
|
||||
[Logowanie](/pl/logging).
|
||||
|
||||
## Jak to działa razem
|
||||
## Jak to wszystko się łączy
|
||||
|
||||
- **Zdarzenia diagnostyczne** to ustrukturyzowane rekordy wewnątrz procesu emitowane przez
|
||||
Gateway i dołączone pluginy dla uruchomień modeli, przepływu wiadomości, sesji, kolejek
|
||||
i exec.
|
||||
- **Plugin `diagnostics-otel`** subskrybuje te zdarzenia i eksportuje je jako
|
||||
**metryki**, **ślady** i **logi** OpenTelemetry przez OTLP/HTTP.
|
||||
- **Wywołania dostawców** otrzymują nagłówek W3C `traceparent` z zaufanego kontekstu
|
||||
przedziału wywołania modelu OpenClaw, gdy transport dostawcy akceptuje niestandardowe
|
||||
nagłówki. Kontekst śladu emitowany przez plugin nie jest propagowany.
|
||||
- Eksportery są dołączane tylko wtedy, gdy włączone są zarówno powierzchnia diagnostyczna, jak i plugin,
|
||||
- **Wywołania dostawcy** otrzymują nagłówek W3C `traceparent` z należącego do OpenClaw
|
||||
zaufanego kontekstu zakresu wywołania modelu, gdy transport dostawcy akceptuje niestandardowe
|
||||
nagłówki. Kontekst śledzenia emitowany przez Plugin nie jest propagowany.
|
||||
- Eksportery są podłączane tylko wtedy, gdy włączone są zarówno powierzchnia diagnostyczna, jak i Plugin,
|
||||
więc domyślnie koszt wewnątrz procesu pozostaje bliski zeru.
|
||||
|
||||
## Szybki start
|
||||
|
||||
W przypadku instalacji pakietowych najpierw zainstaluj plugin:
|
||||
W przypadku instalacji pakietowych najpierw zainstaluj Plugin:
|
||||
|
||||
```bash
|
||||
openclaw plugins install clawhub:@openclaw/diagnostics-otel
|
||||
@ -65,28 +65,28 @@ openclaw plugins install clawhub:@openclaw/diagnostics-otel
|
||||
}
|
||||
```
|
||||
|
||||
Plugin możesz też włączyć z CLI:
|
||||
Możesz też włączyć Plugin z poziomu CLI:
|
||||
|
||||
```bash
|
||||
openclaw plugins enable diagnostics-otel
|
||||
```
|
||||
|
||||
<Note>
|
||||
`protocol` obecnie obsługuje tylko `http/protobuf`. `grpc` jest ignorowane.
|
||||
`protocol` obecnie obsługuje tylko `http/protobuf`. `grpc` jest ignorowany.
|
||||
</Note>
|
||||
|
||||
## Eksportowane sygnały
|
||||
|
||||
| Sygnał | Co do niego trafia |
|
||||
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
|
||||
| **Metryki** | Liczniki i histogramy użycia tokenów, kosztu, czasu trwania uruchomienia, przepływu wiadomości, pasów kolejek, stanu sesji, exec i presji pamięci. |
|
||||
| **Ślady** | Przedziały dla użycia modeli, wywołań modeli, cyklu życia harnessu, wykonywania narzędzi, exec, przetwarzania webhooków/wiadomości, składania kontekstu i pętli narzędzi. |
|
||||
| **Logi** | Ustrukturyzowane rekordy `logging.file` eksportowane przez OTLP, gdy włączone jest `diagnostics.otel.logs`. |
|
||||
| Sygnał | Co trafia do środka |
|
||||
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| **Metryki** | Liczniki i histogramy użycia tokenów, kosztów, czasu trwania uruchomień, przepływu wiadomości, zdarzeń Talk, pasów kolejek, stanu/odzyskiwania sesji, exec i presji pamięci. |
|
||||
| **Ślady** | Zakresy dla użycia modeli, wywołań modeli, cyklu życia harness, wykonywania narzędzi, exec, przetwarzania Webhook/wiadomości, składania kontekstu i pętli narzędzi. |
|
||||
| **Logi** | Ustrukturyzowane rekordy `logging.file` eksportowane przez OTLP, gdy włączone jest `diagnostics.otel.logs`. |
|
||||
|
||||
Przełączaj `traces`, `metrics` i `logs` niezależnie. Wszystkie trzy są domyślnie włączone,
|
||||
gdy `diagnostics.otel.enabled` ma wartość true.
|
||||
|
||||
## Dokumentacja konfiguracji
|
||||
## Informacje o konfiguracji
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -124,159 +124,171 @@ gdy `diagnostics.otel.enabled` ma wartość true.
|
||||
| Zmienna | Cel |
|
||||
| ----------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
||||
| `OTEL_EXPORTER_OTLP_ENDPOINT` | Nadpisuje `diagnostics.otel.endpoint`. Jeśli wartość zawiera już `/v1/traces`, `/v1/metrics` lub `/v1/logs`, jest używana bez zmian. |
|
||||
| `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` / `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT` / `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT` | Nadpisania endpointów specyficzne dla sygnału, używane, gdy pasujący klucz konfiguracji `diagnostics.otel.*Endpoint` nie jest ustawiony. Konfiguracja specyficzna dla sygnału ma pierwszeństwo przed env specyficznym dla sygnału, a ten ma pierwszeństwo przed współdzielonym endpointem. |
|
||||
| `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` / `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT` / `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT` | Nadpisania punktów końcowych specyficzne dla sygnału, używane, gdy pasujący klucz konfiguracji `diagnostics.otel.*Endpoint` nie jest ustawiony. Konfiguracja specyficzna dla sygnału ma pierwszeństwo przed zmienną środowiskową specyficzną dla sygnału, która ma pierwszeństwo przed wspólnym punktem końcowym. |
|
||||
| `OTEL_SERVICE_NAME` | Nadpisuje `diagnostics.otel.serviceName`. |
|
||||
| `OTEL_EXPORTER_OTLP_PROTOCOL` | Nadpisuje protokół przesyłania (obecnie honorowane jest tylko `http/protobuf`). |
|
||||
| `OTEL_SEMCONV_STABILITY_OPT_IN` | Ustaw na `gen_ai_latest_experimental`, aby emitować najnowszy eksperymentalny atrybut przedziału GenAI (`gen_ai.provider.name`) zamiast starszego `gen_ai.system`. Metryki GenAI zawsze używają ograniczonych atrybutów semantycznych o niskiej kardynalności. |
|
||||
| `OPENCLAW_OTEL_PRELOADED` | Ustaw na `1`, gdy inny preload lub proces hosta zarejestrował już globalny OpenTelemetry SDK. Plugin pomija wtedy własny cykl życia NodeSDK, ale nadal podłącza listenery diagnostyczne i honoruje `traces`/`metrics`/`logs`. |
|
||||
| `OTEL_EXPORTER_OTLP_PROTOCOL` | Nadpisuje protokół transmisji (dziś honorowane jest tylko `http/protobuf`). |
|
||||
| `OTEL_SEMCONV_STABILITY_OPT_IN` | Ustaw na `gen_ai_latest_experimental`, aby emitować najnowszy eksperymentalny atrybut zakresu GenAI (`gen_ai.provider.name`) zamiast starszego `gen_ai.system`. Metryki GenAI zawsze używają ograniczonych, niskokardynalnych atrybutów semantycznych niezależnie od tego. |
|
||||
| `OPENCLAW_OTEL_PRELOADED` | Ustaw na `1`, gdy inny preload lub proces hosta już zarejestrował globalny SDK OpenTelemetry. Plugin pomija wtedy własny cykl życia NodeSDK, ale nadal podłącza listenery diagnostyczne i honoruje `traces`/`metrics`/`logs`. |
|
||||
|
||||
## Prywatność i przechwytywanie treści
|
||||
|
||||
Surowa treść modelu/narzędzia **nie** jest eksportowana domyślnie. Przedziały przenoszą ograniczone
|
||||
identyfikatory (kanał, dostawca, model, kategoria błędu, identyfikatory żądań wyłącznie jako hashe)
|
||||
i nigdy nie zawierają tekstu promptu, tekstu odpowiedzi, wejść narzędzi, wyjść narzędzi ani
|
||||
Surowa treść modelu/narzędzia **nie** jest domyślnie eksportowana. Zakresy przenoszą ograniczone
|
||||
identyfikatory (kanał, dostawca, model, kategoria błędu, identyfikatory żądań tylko jako hash)
|
||||
i nigdy nie zawierają tekstu promptu, tekstu odpowiedzi, danych wejściowych narzędzia, danych wyjściowych narzędzia ani
|
||||
kluczy sesji.
|
||||
Metryki Talk eksportują tylko ograniczone metadane zdarzeń, takie jak tryb, transport,
|
||||
dostawca i typ zdarzenia. Nie zawierają transkryptów, ładunków audio,
|
||||
identyfikatorów sesji, identyfikatorów tur, identyfikatorów wywołań, identyfikatorów pokojów ani tokenów przekazania.
|
||||
|
||||
Wychodzące żądania modelu mogą zawierać nagłówek W3C `traceparent`. Ten nagłówek jest
|
||||
generowany wyłącznie z kontekstu śladu diagnostycznego należącego do OpenClaw dla aktywnego
|
||||
generowany wyłącznie z należącego do OpenClaw diagnostycznego kontekstu śledzenia dla aktywnego
|
||||
wywołania modelu. Istniejące nagłówki `traceparent` dostarczone przez wywołującego są zastępowane, więc pluginy lub
|
||||
niestandardowe opcje dostawcy nie mogą podszyć się pod pochodzenie śladu między usługami.
|
||||
niestandardowe opcje dostawcy nie mogą fałszować pochodzenia śladu między usługami.
|
||||
|
||||
Ustaw `diagnostics.otel.captureContent.*` na `true` tylko wtedy, gdy twój kolektor i
|
||||
polityka retencji są zatwierdzone dla tekstu promptu, odpowiedzi, narzędzia lub promptu systemowego.
|
||||
Ustaw `diagnostics.otel.captureContent.*` na `true` tylko wtedy, gdy Twój kolektor i
|
||||
polityka przechowywania są zatwierdzone dla tekstu promptu, odpowiedzi, narzędzia lub promptu systemowego.
|
||||
Każdy podklucz jest włączany niezależnie:
|
||||
|
||||
- `inputMessages` - treść promptu użytkownika.
|
||||
- `outputMessages` - treść odpowiedzi modelu.
|
||||
- `toolInputs` - ładunki argumentów narzędzi.
|
||||
- `toolOutputs` - ładunki wyników narzędzi.
|
||||
- `systemPrompt` - złożony prompt systemowy/deweloperski.
|
||||
- `toolInputs` - ładunki argumentów narzędzia.
|
||||
- `toolOutputs` - ładunki wyników narzędzia.
|
||||
- `systemPrompt` - złożony prompt systemowy/developerski.
|
||||
|
||||
Gdy dowolny podklucz jest włączony, przedziały modeli i narzędzi otrzymują ograniczone, zredagowane
|
||||
Gdy dowolny podklucz jest włączony, zakresy modelu i narzędzia otrzymują ograniczone, zredagowane
|
||||
atrybuty `openclaw.content.*` tylko dla tej klasy.
|
||||
|
||||
## Próbkowanie i opróżnianie
|
||||
|
||||
- **Ślady:** `diagnostics.otel.sampleRate` (tylko root-span, `0.0` odrzuca wszystko,
|
||||
`1.0` zachowuje wszystko).
|
||||
- **Ślady:** `diagnostics.otel.sampleRate` (tylko zakres główny, `0.0` odrzuca wszystkie,
|
||||
`1.0` zachowuje wszystkie).
|
||||
- **Metryki:** `diagnostics.otel.flushIntervalMs` (minimum `1000`).
|
||||
- **Logi:** Logi OTLP respektują `logging.level` (poziom logów plikowych). Używają
|
||||
ścieżki redakcji rekordów logów diagnostycznych, a nie formatowania konsoli. Instalacje o dużym wolumenie
|
||||
- **Logi:** logi OTLP respektują `logging.level` (poziom logu plikowego). Używają
|
||||
ścieżki redakcji diagnostycznych rekordów logów, a nie formatowania konsoli. Instalacje o dużym wolumenie
|
||||
powinny preferować próbkowanie/filtrowanie w kolektorze OTLP zamiast lokalnego próbkowania.
|
||||
- **Korelacja logów plikowych:** Logi plikowe JSONL zawierają na najwyższym poziomie `traceId`,
|
||||
- **Korelacja logów plikowych:** logi plikowe JSONL zawierają na najwyższym poziomie `traceId`,
|
||||
`spanId`, `parentSpanId` i `traceFlags`, gdy wywołanie logowania przenosi prawidłowy
|
||||
kontekst śladu diagnostycznego, co pozwala procesorom logów łączyć lokalne wiersze logów z
|
||||
eksportowanymi przedziałami.
|
||||
- **Korelacja żądań:** Żądania HTTP Gateway i ramki WebSocket tworzą
|
||||
wewnętrzny zakres śladu żądania. Logi i zdarzenia diagnostyczne w tym zakresie
|
||||
domyślnie dziedziczą ślad żądania, a przedziały uruchomienia agenta i wywołania modelu są
|
||||
tworzone jako dzieci, dzięki czemu nagłówki `traceparent` dostawcy pozostają w tym samym śladzie.
|
||||
diagnostyczny kontekst śledzenia, co pozwala procesorom logów łączyć lokalne wiersze logów z
|
||||
eksportowanymi zakresami.
|
||||
- **Korelacja żądań:** żądania HTTP Gateway i ramki WebSocket tworzą
|
||||
wewnętrzny zakres śladu żądania. Logi i zdarzenia diagnostyczne wewnątrz tego zakresu
|
||||
domyślnie dziedziczą ślad żądania, a zakresy uruchomień agenta i wywołań modelu są
|
||||
tworzone jako dzieci, dzięki czemu nagłówki dostawcy `traceparent` pozostają w tym samym śladzie.
|
||||
|
||||
## Eksportowane metryki
|
||||
|
||||
### Użycie modelu
|
||||
|
||||
- `openclaw.tokens` (licznik, attrs: `openclaw.token`, `openclaw.channel`, `openclaw.provider`, `openclaw.model`, `openclaw.agent`)
|
||||
- `openclaw.cost.usd` (licznik, attrs: `openclaw.channel`, `openclaw.provider`, `openclaw.model`)
|
||||
- `openclaw.run.duration_ms` (histogram, attrs: `openclaw.channel`, `openclaw.provider`, `openclaw.model`)
|
||||
- `openclaw.context.tokens` (histogram, attrs: `openclaw.context`, `openclaw.channel`, `openclaw.provider`, `openclaw.model`)
|
||||
- `gen_ai.client.token.usage` (histogram, metryka konwencji semantycznych GenAI, attrs: `gen_ai.token.type` = `input`/`output`, `gen_ai.provider.name`, `gen_ai.operation.name`, `gen_ai.request.model`)
|
||||
- `gen_ai.client.operation.duration` (histogram, sekundy, metryka konwencji semantycznych GenAI, attrs: `gen_ai.provider.name`, `gen_ai.operation.name`, `gen_ai.request.model`, opcjonalnie `error.type`)
|
||||
- `openclaw.model_call.duration_ms` (histogram, attrs: `openclaw.provider`, `openclaw.model`, `openclaw.api`, `openclaw.transport`, plus `openclaw.errorCategory` i `openclaw.failureKind` przy sklasyfikowanych błędach)
|
||||
- `openclaw.tokens` (licznik, atrybuty: `openclaw.token`, `openclaw.channel`, `openclaw.provider`, `openclaw.model`, `openclaw.agent`)
|
||||
- `openclaw.cost.usd` (licznik, atrybuty: `openclaw.channel`, `openclaw.provider`, `openclaw.model`)
|
||||
- `openclaw.run.duration_ms` (histogram, atrybuty: `openclaw.channel`, `openclaw.provider`, `openclaw.model`)
|
||||
- `openclaw.context.tokens` (histogram, atrybuty: `openclaw.context`, `openclaw.channel`, `openclaw.provider`, `openclaw.model`)
|
||||
- `gen_ai.client.token.usage` (histogram, metryka konwencji semantycznych GenAI, atrybuty: `gen_ai.token.type` = `input`/`output`, `gen_ai.provider.name`, `gen_ai.operation.name`, `gen_ai.request.model`)
|
||||
- `gen_ai.client.operation.duration` (histogram, sekundy, metryka konwencji semantycznych GenAI, atrybuty: `gen_ai.provider.name`, `gen_ai.operation.name`, `gen_ai.request.model`, opcjonalnie `error.type`)
|
||||
- `openclaw.model_call.duration_ms` (histogram, atrybuty: `openclaw.provider`, `openclaw.model`, `openclaw.api`, `openclaw.transport` oraz `openclaw.errorCategory` i `openclaw.failureKind` przy sklasyfikowanych błędach)
|
||||
- `openclaw.model_call.request_bytes` (histogram, rozmiar w bajtach UTF-8 końcowego ładunku żądania modelu; bez surowej treści ładunku)
|
||||
- `openclaw.model_call.response_bytes` (histogram, rozmiar w bajtach UTF-8 strumieniowanych zdarzeń odpowiedzi modelu; bez surowej treści odpowiedzi)
|
||||
- `openclaw.model_call.time_to_first_byte_ms` (histogram, czas, który upłynął przed pierwszym strumieniowanym zdarzeniem odpowiedzi)
|
||||
|
||||
### Przepływ wiadomości
|
||||
|
||||
- `openclaw.webhook.received` (licznik, attrs: `openclaw.channel`, `openclaw.webhook`)
|
||||
- `openclaw.webhook.error` (licznik, attrs: `openclaw.channel`, `openclaw.webhook`)
|
||||
- `openclaw.webhook.duration_ms` (histogram, attrs: `openclaw.channel`, `openclaw.webhook`)
|
||||
- `openclaw.message.queued` (licznik, attrs: `openclaw.channel`, `openclaw.source`)
|
||||
- `openclaw.message.processed` (licznik, attrs: `openclaw.channel`, `openclaw.outcome`)
|
||||
- `openclaw.message.duration_ms` (histogram, attrs: `openclaw.channel`, `openclaw.outcome`)
|
||||
- `openclaw.message.delivery.started` (licznik, attrs: `openclaw.channel`, `openclaw.delivery.kind`)
|
||||
- `openclaw.message.delivery.duration_ms` (histogram, attrs: `openclaw.channel`, `openclaw.delivery.kind`, `openclaw.outcome`, `openclaw.errorCategory`)
|
||||
- `openclaw.webhook.received` (licznik, atrybuty: `openclaw.channel`, `openclaw.webhook`)
|
||||
- `openclaw.webhook.error` (licznik, atrybuty: `openclaw.channel`, `openclaw.webhook`)
|
||||
- `openclaw.webhook.duration_ms` (histogram, atrybuty: `openclaw.channel`, `openclaw.webhook`)
|
||||
- `openclaw.message.queued` (licznik, atrybuty: `openclaw.channel`, `openclaw.source`)
|
||||
- `openclaw.message.processed` (licznik, atrybuty: `openclaw.channel`, `openclaw.outcome`)
|
||||
- `openclaw.message.duration_ms` (histogram, atrybuty: `openclaw.channel`, `openclaw.outcome`)
|
||||
- `openclaw.message.delivery.started` (licznik, atrybuty: `openclaw.channel`, `openclaw.delivery.kind`)
|
||||
- `openclaw.message.delivery.duration_ms` (histogram, atrybuty: `openclaw.channel`, `openclaw.delivery.kind`, `openclaw.outcome`, `openclaw.errorCategory`)
|
||||
|
||||
### Talk
|
||||
|
||||
- `openclaw.talk.event` (licznik, atrybuty: `openclaw.talk.event_type`, `openclaw.talk.mode`, `openclaw.talk.transport`, `openclaw.talk.brain`, `openclaw.talk.provider`)
|
||||
- `openclaw.talk.event.duration_ms` (histogram, atrybuty: takie same jak `openclaw.talk.event`; emitowany, gdy zdarzenie Talk zgłasza czas trwania)
|
||||
- `openclaw.talk.audio.bytes` (histogram, atrybuty: takie same jak `openclaw.talk.event`; emitowany dla zdarzeń ramek audio Talk, które zgłaszają długość w bajtach)
|
||||
|
||||
### Kolejki i sesje
|
||||
|
||||
- `openclaw.queue.lane.enqueue` (licznik, attrs: `openclaw.lane`)
|
||||
- `openclaw.queue.lane.dequeue` (licznik, attrs: `openclaw.lane`)
|
||||
- `openclaw.queue.depth` (histogram, attrs: `openclaw.lane` lub `openclaw.channel=heartbeat`)
|
||||
- `openclaw.queue.wait_ms` (histogram, attrs: `openclaw.lane`)
|
||||
- `openclaw.session.state` (licznik, attrs: `openclaw.state`, `openclaw.reason`)
|
||||
- `openclaw.session.stuck` (licznik, attrs: `openclaw.state`; emitowane tylko dla księgowania nieaktualnych sesji bez aktywnej pracy)
|
||||
- `openclaw.session.stuck_age_ms` (histogram, attrs: `openclaw.state`; emitowane tylko dla księgowania nieaktualnych sesji bez aktywnej pracy)
|
||||
- `openclaw.run.attempt` (licznik, attrs: `openclaw.attempt`)
|
||||
- `openclaw.queue.lane.enqueue` (licznik, atrybuty: `openclaw.lane`)
|
||||
- `openclaw.queue.lane.dequeue` (licznik, atrybuty: `openclaw.lane`)
|
||||
- `openclaw.queue.depth` (histogram, atrybuty: `openclaw.lane` lub `openclaw.channel=heartbeat`)
|
||||
- `openclaw.queue.wait_ms` (histogram, atrybuty: `openclaw.lane`)
|
||||
- `openclaw.session.state` (licznik, atrybuty: `openclaw.state`, `openclaw.reason`)
|
||||
- `openclaw.session.stuck` (licznik, atrybuty: `openclaw.state`; emitowane tylko dla ewidencji przestarzałej sesji bez aktywnej pracy)
|
||||
- `openclaw.session.stuck_age_ms` (histogram, atrybuty: `openclaw.state`; emitowane tylko dla ewidencji przestarzałej sesji bez aktywnej pracy)
|
||||
- `openclaw.session.recovery.requested` (licznik, atrybuty: `openclaw.state`, `openclaw.action`, `openclaw.active_work_kind`, `openclaw.reason`)
|
||||
- `openclaw.session.recovery.completed` (licznik, atrybuty: `openclaw.state`, `openclaw.action`, `openclaw.status`, `openclaw.active_work_kind`, `openclaw.reason`)
|
||||
- `openclaw.session.recovery.age_ms` (histogram, atrybuty: takie same jak w pasującym liczniku odzyskiwania)
|
||||
- `openclaw.run.attempt` (licznik, atrybuty: `openclaw.attempt`)
|
||||
|
||||
### Telemetria żywotności sesji
|
||||
|
||||
`diagnostics.stuckSessionWarnMs` to próg wieku bez postępu dla diagnostyki
|
||||
żywotności sesji. Sesja `processing` nie zbliża się do tego progu,
|
||||
żywotności sesji. Sesja `processing` nie zbliża się wiekiem do tego progu,
|
||||
gdy OpenClaw obserwuje postęp odpowiedzi, narzędzia, statusu, bloku lub środowiska wykonawczego ACP.
|
||||
Keepalive'y pisania nie są liczone jako postęp, więc cichy model lub harness nadal może
|
||||
zostać wykryty.
|
||||
Sygnały podtrzymujące pisanie nie są liczone jako postęp, więc cichy model lub uprząż
|
||||
nadal mogą zostać wykryte.
|
||||
|
||||
OpenClaw klasyfikuje sesje według pracy, którą nadal może obserwować:
|
||||
|
||||
- `session.long_running`: aktywna praca osadzona, wywołania modelu lub wywołania narzędzi
|
||||
nadal postępują.
|
||||
- `session.stalled`: istnieje aktywna praca, ale aktywne uruchomienie nie zgłosiło
|
||||
ostatnio postępu. Zatrzymane uruchomienia osadzone początkowo pozostają tylko do obserwacji, a następnie
|
||||
przechodzą w abort-drain po `diagnostics.stuckSessionAbortMs` bez postępu, aby oczekujące
|
||||
tury za lane mogły zostać wznowione. Gdy nie ustawiono tej wartości, próg przerwania domyślnie używa
|
||||
bezpieczniejszego rozszerzonego okna wynoszącego co najmniej 10 minut i 5x
|
||||
nadal robią postęp.
|
||||
- `session.stalled`: aktywna praca istnieje, ale aktywne uruchomienie nie zgłosiło
|
||||
ostatnio postępu. Zablokowane uruchomienia osadzone najpierw pozostają tylko obserwowane, a następnie
|
||||
przechodzą w przerwanie z opróżnianiem po `diagnostics.stuckSessionAbortMs` bez postępu, aby zakolejkowane
|
||||
tury za pasem mogły zostać wznowione. Gdy nie ustawiono, próg przerwania domyślnie przyjmuje
|
||||
bezpieczniejsze rozszerzone okno wynoszące co najmniej 10 minut i 5x
|
||||
`diagnostics.stuckSessionWarnMs`.
|
||||
- `session.stuck`: nieaktualna ewidencja sesji bez aktywnej pracy. To natychmiast zwalnia
|
||||
dotknięty lane sesji.
|
||||
- `session.stuck`: ewidencja przestarzałej sesji bez aktywnej pracy. To natychmiast
|
||||
zwalnia dotknięty pas sesji.
|
||||
|
||||
Odzyskiwanie emituje ustrukturyzowane zdarzenia `session.recovery.requested` i
|
||||
`session.recovery.completed`. Diagnostyczny stan sesji jest oznaczany jako bezczynny
|
||||
dopiero po mutującym wyniku odzyskiwania (`aborted` lub `released`) i tylko wtedy, gdy
|
||||
dopiero po mutującym wyniku odzyskiwania (`aborted` lub `released`) i tylko jeśli
|
||||
ta sama generacja przetwarzania jest nadal bieżąca.
|
||||
|
||||
Tylko `session.stuck` emituje licznik `openclaw.session.stuck`,
|
||||
histogram `openclaw.session.stuck_age_ms` oraz span `openclaw.session.stuck`.
|
||||
Tylko `session.stuck` emituje licznik `openclaw.session.stuck`, histogram
|
||||
`openclaw.session.stuck_age_ms` oraz span `openclaw.session.stuck`.
|
||||
Powtarzające się diagnostyki `session.stuck` wycofują się, dopóki sesja pozostaje
|
||||
bez zmian, więc pulpity powinny alarmować o utrzymujących się wzrostach, a nie o każdym
|
||||
takcie heartbeat. Informacje o pokrętle konfiguracji i wartościach domyślnych znajdziesz w
|
||||
[Informacje o konfiguracji](/pl/gateway/configuration-reference#diagnostics).
|
||||
niezmieniona, więc pulpity powinny alarmować przy utrzymujących się wzrostach, a nie przy każdym
|
||||
takcie Heartbeat. Pokrętło konfiguracji i wartości domyślne znajdziesz w
|
||||
[Dokumentacji konfiguracji](/pl/gateway/configuration-reference#diagnostics).
|
||||
|
||||
### Cykl życia harness
|
||||
### Cykl życia uprzęży
|
||||
|
||||
- `openclaw.harness.duration_ms` (histogram, attrs: `openclaw.harness.id`, `openclaw.harness.plugin`, `openclaw.outcome`, `openclaw.harness.phase` przy błędach)
|
||||
- `openclaw.harness.duration_ms` (histogram, atrybuty: `openclaw.harness.id`, `openclaw.harness.plugin`, `openclaw.outcome`, `openclaw.harness.phase` przy błędach)
|
||||
|
||||
### Exec
|
||||
|
||||
- `openclaw.exec.duration_ms` (histogram, attrs: `openclaw.exec.target`, `openclaw.exec.mode`, `openclaw.outcome`, `openclaw.failureKind`)
|
||||
- `openclaw.exec.duration_ms` (histogram, atrybuty: `openclaw.exec.target`, `openclaw.exec.mode`, `openclaw.outcome`, `openclaw.failureKind`)
|
||||
|
||||
### Wewnętrzne mechanizmy diagnostyki (pamięć i pętla narzędzi)
|
||||
|
||||
- `openclaw.memory.heap_used_bytes` (histogram, attrs: `openclaw.memory.kind`)
|
||||
- `openclaw.memory.heap_used_bytes` (histogram, atrybuty: `openclaw.memory.kind`)
|
||||
- `openclaw.memory.rss_bytes` (histogram)
|
||||
- `openclaw.memory.pressure` (counter, attrs: `openclaw.memory.level`)
|
||||
- `openclaw.tool.loop.iterations` (counter, attrs: `openclaw.toolName`, `openclaw.outcome`)
|
||||
- `openclaw.tool.loop.duration_ms` (histogram, attrs: `openclaw.toolName`, `openclaw.outcome`)
|
||||
- `openclaw.memory.pressure` (licznik, atrybuty: `openclaw.memory.level`)
|
||||
- `openclaw.tool.loop.iterations` (licznik, atrybuty: `openclaw.toolName`, `openclaw.outcome`)
|
||||
- `openclaw.tool.loop.duration_ms` (histogram, atrybuty: `openclaw.toolName`, `openclaw.outcome`)
|
||||
|
||||
## Eksportowane spany
|
||||
|
||||
- `openclaw.model.usage`
|
||||
- `openclaw.channel`, `openclaw.provider`, `openclaw.model`
|
||||
- `openclaw.tokens.*` (input/output/cache_read/cache_write/total)
|
||||
- `gen_ai.system` domyślnie albo `gen_ai.provider.name`, gdy włączono najnowsze konwencje semantyczne GenAI
|
||||
- domyślnie `gen_ai.system`, albo `gen_ai.provider.name`, gdy włączono najnowsze konwencje semantyczne GenAI
|
||||
- `gen_ai.request.model`, `gen_ai.operation.name`, `gen_ai.usage.*`
|
||||
- `openclaw.run`
|
||||
- `openclaw.outcome`, `openclaw.channel`, `openclaw.provider`, `openclaw.model`, `openclaw.errorCategory`
|
||||
- `openclaw.model.call`
|
||||
- `gen_ai.system` domyślnie albo `gen_ai.provider.name`, gdy włączono najnowsze konwencje semantyczne GenAI
|
||||
- domyślnie `gen_ai.system`, albo `gen_ai.provider.name`, gdy włączono najnowsze konwencje semantyczne GenAI
|
||||
- `gen_ai.request.model`, `gen_ai.operation.name`, `openclaw.provider`, `openclaw.model`, `openclaw.api`, `openclaw.transport`
|
||||
- `openclaw.errorCategory` i opcjonalnie `openclaw.failureKind` przy błędach
|
||||
- `openclaw.errorCategory` i opcjonalne `openclaw.failureKind` przy błędach
|
||||
- `openclaw.model_call.request_bytes`, `openclaw.model_call.response_bytes`, `openclaw.model_call.time_to_first_byte_ms`
|
||||
- `openclaw.provider.request_id_hash` (ograniczony hash oparty na SHA identyfikatora żądania dostawcy upstream; surowe identyfikatory nie są eksportowane)
|
||||
- `openclaw.harness.run`
|
||||
- `openclaw.harness.id`, `openclaw.harness.plugin`, `openclaw.outcome`, `openclaw.provider`, `openclaw.model`, `openclaw.channel`
|
||||
- Po zakończeniu: `openclaw.harness.result_classification`, `openclaw.harness.yield_detected`, `openclaw.harness.items.started`, `openclaw.harness.items.completed`, `openclaw.harness.items.active`
|
||||
- Przy błędzie: `openclaw.harness.phase`, `openclaw.errorCategory`, opcjonalnie `openclaw.harness.cleanup_failed`
|
||||
- Przy ukończeniu: `openclaw.harness.result_classification`, `openclaw.harness.yield_detected`, `openclaw.harness.items.started`, `openclaw.harness.items.completed`, `openclaw.harness.items.active`
|
||||
- Przy błędzie: `openclaw.harness.phase`, `openclaw.errorCategory`, opcjonalne `openclaw.harness.cleanup_failed`
|
||||
- `openclaw.tool.execution`
|
||||
- `gen_ai.tool.name`, `openclaw.toolName`, `openclaw.errorCategory`, `openclaw.tool.params.*`
|
||||
- `openclaw.exec`
|
||||
@ -298,23 +310,23 @@ takcie heartbeat. Informacje o pokrętle konfiguracji i wartościach domyślnych
|
||||
- `openclaw.memory.pressure`
|
||||
- `openclaw.memory.level`, `openclaw.memory.heap_used_bytes`, `openclaw.memory.rss_bytes`
|
||||
|
||||
Gdy przechwytywanie treści jest jawnie włączone, spany modelu i narzędzi mogą również
|
||||
Gdy przechwytywanie treści jest jawnie włączone, spany modelu i narzędzi mogą także
|
||||
zawierać ograniczone, zredagowane atrybuty `openclaw.content.*` dla konkretnych
|
||||
klas treści, na które wyrażono zgodę.
|
||||
klas treści, które włączono.
|
||||
|
||||
## Katalog zdarzeń diagnostycznych
|
||||
|
||||
Poniższe zdarzenia zasilają metryki i spany powyżej. Pluginy mogą też subskrybować
|
||||
Poniższe zdarzenia wspierają powyższe metryki i spany. Pluginy mogą również subskrybować
|
||||
je bezpośrednio bez eksportu OTLP.
|
||||
|
||||
**Użycie modelu**
|
||||
|
||||
- `model.usage` - tokeny, koszt, czas trwania, kontekst, dostawca/model/kanał,
|
||||
identyfikatory sesji. `usage` to rozliczanie dostawcy/tury na potrzeby kosztów i telemetrii;
|
||||
`context.used` to bieżąca migawka promptu/kontekstu i może być niższa niż
|
||||
`usage.total` dostawcy, gdy w grę wchodzą buforowane dane wejściowe lub wywołania pętli narzędzi.
|
||||
`context.used` to bieżący zrzut promptu/kontekstu i może być niższy niż
|
||||
`usage.total` dostawcy, gdy używane są buforowane dane wejściowe lub wywołania pętli narzędzi.
|
||||
|
||||
**Przepływ wiadomości**
|
||||
**Przepływ komunikatów**
|
||||
|
||||
- `webhook.received` / `webhook.processed` / `webhook.error`
|
||||
- `message.queued` / `message.processed`
|
||||
@ -325,27 +337,27 @@ je bezpośrednio bez eksportu OTLP.
|
||||
- `queue.lane.enqueue` / `queue.lane.dequeue`
|
||||
- `session.state` / `session.long_running` / `session.stalled` / `session.stuck`
|
||||
- `run.attempt` / `run.progress`
|
||||
- `diagnostic.heartbeat` (zagregowane liczniki: webhooki/kolejka/sesja)
|
||||
- `diagnostic.heartbeat` (liczniki zbiorcze: webhooki/kolejka/sesja)
|
||||
|
||||
**Cykl życia harness**
|
||||
**Cykl życia uprzęży**
|
||||
|
||||
- `harness.run.started` / `harness.run.completed` / `harness.run.error` -
|
||||
cykl życia pojedynczego uruchomienia dla harness agenta. Obejmuje `harnessId`, opcjonalny
|
||||
`pluginId`, dostawcę/model/kanał oraz identyfikator uruchomienia. Zakończenie dodaje
|
||||
`durationMs`, `outcome`, opcjonalnie `resultClassification`, `yieldDetected`
|
||||
oraz liczniki `itemLifecycle`. Błędy dodają `phase`
|
||||
cykl życia na uruchomienie dla uprzęży agenta. Obejmuje `harnessId`, opcjonalne
|
||||
`pluginId`, dostawcę/model/kanał oraz identyfikator uruchomienia. Ukończenie dodaje
|
||||
`durationMs`, `outcome`, opcjonalne `resultClassification`, `yieldDetected`
|
||||
oraz liczby `itemLifecycle`. Błędy dodają `phase`
|
||||
(`prepare`/`start`/`send`/`resolve`/`cleanup`), `errorCategory` oraz
|
||||
opcjonalnie `cleanupFailed`.
|
||||
opcjonalne `cleanupFailed`.
|
||||
|
||||
**Exec**
|
||||
|
||||
- `exec.process.completed` - końcowy wynik terminala, czas trwania, cel, tryb, kod wyjścia
|
||||
oraz rodzaj błędu. Tekst polecenia i katalogi robocze nie są
|
||||
- `exec.process.completed` - końcowy wynik, czas trwania, cel, tryb, kod wyjścia
|
||||
oraz rodzaj awarii. Tekst polecenia i katalogi robocze nie są
|
||||
uwzględniane.
|
||||
|
||||
## Bez eksportera
|
||||
|
||||
Możesz utrzymać dostępność zdarzeń diagnostycznych dla pluginów lub niestandardowych odbiorników bez
|
||||
Możesz pozostawić zdarzenia diagnostyczne dostępne dla pluginów lub niestandardowych odbiorników bez
|
||||
uruchamiania `diagnostics-otel`:
|
||||
|
||||
```json5
|
||||
@ -354,7 +366,7 @@ uruchamiania `diagnostics-otel`:
|
||||
}
|
||||
```
|
||||
|
||||
Aby uzyskać ukierunkowane wyjście debugowania bez podnoszenia `logging.level`, użyj flag diagnostycznych.
|
||||
Aby uzyskać ukierunkowane wyjście debugowania bez podnoszenia `logging.level`, użyj flag diagnostyki.
|
||||
Flagi nie rozróżniają wielkości liter i obsługują symbole wieloznaczne (np. `telegram.*` lub
|
||||
`*`):
|
||||
|
||||
@ -364,7 +376,7 @@ Flagi nie rozróżniają wielkości liter i obsługują symbole wieloznaczne (np
|
||||
}
|
||||
```
|
||||
|
||||
Albo jako jednorazowe nadpisanie zmienną środowiskową:
|
||||
Lub jako jednorazowe nadpisanie env:
|
||||
|
||||
```bash
|
||||
OPENCLAW_DIAGNOSTICS=telegram.http,telegram.payload openclaw gateway
|
||||
@ -372,7 +384,7 @@ OPENCLAW_DIAGNOSTICS=telegram.http,telegram.payload openclaw gateway
|
||||
|
||||
Wyjście flag trafia do standardowego pliku dziennika (`logging.file`) i nadal jest
|
||||
redagowane przez `logging.redactSensitive`. Pełny przewodnik:
|
||||
[Flagi diagnostyczne](/pl/diagnostics/flags).
|
||||
[Flagi diagnostyki](/pl/diagnostics/flags).
|
||||
|
||||
## Wyłączanie
|
||||
|
||||
@ -382,13 +394,13 @@ redagowane przez `logging.redactSensitive`. Pełny przewodnik:
|
||||
}
|
||||
```
|
||||
|
||||
Możesz też pominąć `diagnostics-otel` w `plugins.allow` albo uruchomić
|
||||
Możesz także pominąć `diagnostics-otel` w `plugins.allow` albo uruchomić
|
||||
`openclaw plugins disable diagnostics-otel`.
|
||||
|
||||
## Powiązane
|
||||
|
||||
- [Logowanie](/pl/logging) - dzienniki w pliku, wyjście konsoli, śledzenie przez CLI oraz karta Logs w Control UI
|
||||
- [Wewnętrzne mechanizmy logowania Gateway](/pl/gateway/logging) - style logów WS, prefiksy podsystemów i przechwytywanie konsoli
|
||||
- [Flagi diagnostyczne](/pl/diagnostics/flags) - ukierunkowane flagi dziennika debugowania
|
||||
- [Eksport diagnostyki](/pl/gateway/diagnostics) - narzędzie pakietu wsparcia dla operatorów (oddzielne od eksportu OTEL)
|
||||
- [Informacje o konfiguracji](/pl/gateway/configuration-reference#diagnostics) - pełne informacje o polach `diagnostics.*`
|
||||
- [Rejestrowanie](/pl/logging) - dzienniki plikowe, wyjście konsoli, śledzenie CLI oraz karta dzienników interfejsu Control UI
|
||||
- [Wewnętrzne mechanizmy rejestrowania Gateway](/pl/gateway/logging) - style dzienników WS, prefiksy podsystemów i przechwytywanie konsoli
|
||||
- [Flagi diagnostyki](/pl/diagnostics/flags) - ukierunkowane flagi dzienników debugowania
|
||||
- [Eksport diagnostyki](/pl/gateway/diagnostics) - narzędzie pakietu wsparcia operatora (oddzielne od eksportu OTEL)
|
||||
- [Dokumentacja konfiguracji](/pl/gateway/configuration-reference#diagnostics) - pełna dokumentacja pól `diagnostics.*`
|
||||
|
||||
@ -1,21 +1,21 @@
|
||||
---
|
||||
read_when:
|
||||
- Chcesz, aby Prometheus, Grafana, VictoriaMetrics lub inne narzędzie zbierające zbierało metryki OpenClaw Gateway
|
||||
- Potrzebujesz nazw metryk Prometheus oraz zasad dotyczących etykiet dla paneli kontrolnych lub alertów
|
||||
- Chcesz mieć metryki bez uruchamiania kolektora OpenTelemetry
|
||||
- Chcesz, aby Prometheus, Grafana, VictoriaMetrics lub inne narzędzie zbierające dane zbierało metryki OpenClaw Gateway
|
||||
- Potrzebujesz nazw metryk Prometheus oraz zasad dotyczących etykiet dla pulpitów nawigacyjnych lub alertów
|
||||
- Chcesz metryk bez uruchamiania kolektora OpenTelemetry
|
||||
sidebarTitle: Prometheus
|
||||
summary: Udostępnij diagnostykę OpenClaw jako metryki tekstowe Prometheus za pomocą Plugin diagnostics-prometheus
|
||||
title: Metryki Prometheusa
|
||||
summary: Udostępniaj diagnostykę OpenClaw jako metryki tekstowe Prometheus za pomocą Plugin diagnostics-prometheus
|
||||
title: Metryki Prometheus
|
||||
x-i18n:
|
||||
generated_at: "2026-05-02T20:44:56Z"
|
||||
generated_at: "2026-05-06T10:05:27Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 49df17348c5b63c4b5f3c05f3378d43764e5de985135ad30c1e74ef607e0dd37
|
||||
source_hash: 864e2a343266d84baaaaca9d8e494359198a3b43e8663ec8dcfcd4e2e4c6c004
|
||||
source_path: gateway/prometheus.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
OpenClaw może udostępniać metryki diagnostyczne za pomocą oficjalnego Plugin `diagnostics-prometheus`. Nasłuchuje on zaufanych wewnętrznych zdarzeń diagnostycznych i renderuje tekstowy endpoint Prometheus pod adresem:
|
||||
OpenClaw może udostępniać metryki diagnostyczne przez oficjalny Plugin `diagnostics-prometheus`. Nasłuchuje zaufanej diagnostyki wewnętrznej i renderuje tekstowy punkt końcowy Prometheus pod adresem:
|
||||
|
||||
```text
|
||||
GET /api/diagnostics/prometheus
|
||||
@ -24,10 +24,10 @@ GET /api/diagnostics/prometheus
|
||||
Typ zawartości to `text/plain; version=0.0.4; charset=utf-8`, czyli standardowy format ekspozycji Prometheus.
|
||||
|
||||
<Warning>
|
||||
Trasa używa uwierzytelniania Gateway (zakres operatora). Nie udostępniaj jej jako publicznego, nieuwierzytelnionego endpointu `/metrics`. Scrapuj ją przez tę samą ścieżkę uwierzytelniania, której używasz dla innych API operatora.
|
||||
Ta trasa używa uwierzytelniania Gateway (zakres operatora). Nie udostępniaj jej jako publicznego, nieuwierzytelnionego punktu końcowego `/metrics`. Zbieraj ją przez tę samą ścieżkę uwierzytelniania, której używasz dla innych interfejsów API operatora.
|
||||
</Warning>
|
||||
|
||||
Informacje o śladach, logach, wypychaniu OTLP i atrybutach semantycznych OpenTelemetry GenAI znajdziesz w [eksport OpenTelemetry](/pl/gateway/opentelemetry).
|
||||
Informacje o śladach, logach, wypychaniu OTLP i atrybutach semantycznych OpenTelemetry GenAI znajdziesz w sekcji [eksport OpenTelemetry](/pl/gateway/opentelemetry).
|
||||
|
||||
## Szybki start
|
||||
|
||||
@ -62,9 +62,9 @@ Informacje o śladach, logach, wypychaniu OTLP i atrybutach semantycznych OpenTe
|
||||
</Tabs>
|
||||
</Step>
|
||||
<Step title="Uruchom ponownie Gateway">
|
||||
Trasa HTTP jest rejestrowana podczas uruchamiania Plugin, więc przeładuj po włączeniu.
|
||||
Trasa HTTP jest rejestrowana przy uruchamianiu Plugin, więc po włączeniu wykonaj przeładowanie.
|
||||
</Step>
|
||||
<Step title="Scrapuj chronioną trasę">
|
||||
<Step title="Zbieraj chronioną trasę">
|
||||
Wyślij to samo uwierzytelnianie Gateway, którego używają klienci operatora:
|
||||
|
||||
```bash
|
||||
@ -109,12 +109,18 @@ Informacje o śladach, logach, wypychaniu OTLP i atrybutach semantycznych OpenTe
|
||||
| `openclaw_harness_run_duration_seconds` | histogram | `channel`, `error_category`, `harness`, `model`, `outcome`, `phase`, `plugin`, `provider` |
|
||||
| `openclaw_message_processed_total` | counter | `channel`, `outcome`, `reason` |
|
||||
| `openclaw_message_processed_duration_seconds` | histogram | `channel`, `outcome`, `reason` |
|
||||
| `openclaw_message_delivery_started_total` | counter | `channel`, `delivery_kind` |
|
||||
| `openclaw_message_delivery_total` | counter | `channel`, `delivery_kind`, `error_category`, `outcome` |
|
||||
| `openclaw_message_delivery_duration_seconds` | histogram | `channel`, `delivery_kind`, `error_category`, `outcome` |
|
||||
| `openclaw_talk_event_total` | counter | `brain`, `event_type`, `mode`, `provider`, `transport` |
|
||||
| `openclaw_talk_event_duration_seconds` | histogram | `brain`, `event_type`, `mode`, `provider`, `transport` |
|
||||
| `openclaw_talk_audio_bytes` | histogram | `brain`, `event_type`, `mode`, `provider`, `transport` |
|
||||
| `openclaw_queue_lane_size` | gauge | `lane` |
|
||||
| `openclaw_queue_lane_wait_seconds` | histogram | `lane` |
|
||||
| `openclaw_session_state_total` | counter | `reason`, `state` |
|
||||
| `openclaw_session_queue_depth` | gauge | `state` |
|
||||
| `openclaw_session_recovery_total` | counter | `action`, `active_work_kind`, `state`, `status` |
|
||||
| `openclaw_session_recovery_age_seconds` | histogram | `action`, `active_work_kind`, `state`, `status` |
|
||||
| `openclaw_memory_bytes` | gauge | `kind` |
|
||||
| `openclaw_memory_rss_bytes` | histogram | brak |
|
||||
| `openclaw_memory_pressure_total` | counter | `level`, `reason` |
|
||||
@ -124,21 +130,22 @@ Informacje o śladach, logach, wypychaniu OTLP i atrybutach semantycznych OpenTe
|
||||
## Zasady etykiet
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Ograniczone etykiety o niskiej kardynalności">
|
||||
Etykiety Prometheus pozostają ograniczone i mają niską kardynalność. Eksporter nie emituje surowych identyfikatorów diagnostycznych, takich jak `runId`, `sessionKey`, `sessionId`, `callId`, `toolCallId`, identyfikatory wiadomości, identyfikatory czatów ani identyfikatory żądań dostawcy.
|
||||
<Accordion title="Ograniczone etykiety o niskiej krotności">
|
||||
Etykiety Prometheus pozostają ograniczone i mają niską krotność. Eksporter nie emituje surowych identyfikatorów diagnostycznych, takich jak `runId`, `sessionKey`, `sessionId`, `callId`, `toolCallId`, identyfikatory wiadomości, identyfikatory czatów ani identyfikatory żądań dostawcy.
|
||||
|
||||
Wartości etykiet są redagowane i muszą spełniać zasady OpenClaw dotyczące znaków o niskiej kardynalności. Wartości, które nie spełniają zasad, są zastępowane przez `unknown`, `other` lub `none`, zależnie od metryki.
|
||||
Wartości etykiet są redagowane i muszą być zgodne z polityką znaków o niskiej krotności OpenClaw. Wartości, które nie spełniają tej polityki, są zastępowane przez `unknown`, `other` lub `none`, zależnie od metryki.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Limit serii i rozliczanie przepełnienia">
|
||||
Eksporter ogranicza przechowywane szeregi czasowe w pamięci do **2048** serii łącznie dla liczników, wskaźników i histogramów. Nowe serie ponad ten limit są odrzucane, a `openclaw_prometheus_series_dropped_total` zwiększa się o jeden za każdym razem.
|
||||
Eksporter ogranicza przechowywane w pamięci szeregi czasowe do **2048** serii łącznie dla liczników, wskaźników i histogramów. Nowe serie powyżej tego limitu są odrzucane, a `openclaw_prometheus_series_dropped_total` zwiększa się o jeden za każdym razem.
|
||||
|
||||
Monitoruj ten licznik jako twardy sygnał, że atrybut wyżej w łańcuchu przepuszcza wartości o wysokiej kardynalności. Eksporter nigdy automatycznie nie podnosi limitu; jeśli licznik rośnie, napraw źródło zamiast wyłączać limit.
|
||||
Traktuj ten licznik jako twardy sygnał, że atrybut po stronie źródła przecieka wartości o wysokiej kardynalności. Eksporter nigdy nie podnosi limitu automatycznie; jeśli licznik rośnie, napraw źródło zamiast wyłączać limit.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Co nigdy nie pojawia się w wyjściu Prometheus">
|
||||
- tekst promptu, tekst odpowiedzi, dane wejściowe narzędzi, dane wyjściowe narzędzi, prompty systemowe
|
||||
- surowe identyfikatory żądań dostawcy (tylko ograniczone hashe, tam gdzie ma to zastosowanie, w spanach — nigdy w metrykach)
|
||||
- transkrypcje rozmów, ładunki audio, identyfikatory połączeń, identyfikatory pokoi, tokeny przekazania, identyfikatory tur i surowe identyfikatory sesji
|
||||
- surowe identyfikatory żądań dostawcy (tylko ograniczone hashe, tam gdzie mają zastosowanie, w spanach — nigdy w metrykach)
|
||||
- klucze sesji i identyfikatory sesji
|
||||
- nazwy hostów, ścieżki plików, wartości sekretów
|
||||
|
||||
@ -172,27 +179,27 @@ increase(openclaw_prometheus_series_dropped_total[15m]) > 0
|
||||
```
|
||||
|
||||
<Tip>
|
||||
Preferuj `gen_ai_client_token_usage` dla pulpitów między dostawcami: podąża za konwencjami semantycznymi OpenTelemetry GenAI i jest spójne z metrykami z usług GenAI innych niż OpenClaw.
|
||||
W przypadku pulpitów obejmujących wielu dostawców preferuj `gen_ai_client_token_usage`: jest zgodne z konwencjami semantycznymi OpenTelemetry GenAI i spójne z metrykami usług GenAI innych niż OpenClaw.
|
||||
</Tip>
|
||||
|
||||
## Wybór między eksportem Prometheus i OpenTelemetry
|
||||
## Wybór między eksportem Prometheus a OpenTelemetry
|
||||
|
||||
OpenClaw obsługuje obie powierzchnie niezależnie. Możesz uruchomić jedną, obie albo żadnej.
|
||||
OpenClaw obsługuje obie powierzchnie niezależnie. Możesz uruchomić jedną, obie albo żadną.
|
||||
|
||||
<Tabs>
|
||||
<Tab title="diagnostics-prometheus">
|
||||
- Model **pull**: Prometheus scrapuje `/api/diagnostics/prometheus`.
|
||||
- Nie jest wymagany zewnętrzny kolektor.
|
||||
- Model **pull**: Prometheus odczytuje `/api/diagnostics/prometheus`.
|
||||
- Nie wymaga zewnętrznego kolektora.
|
||||
- Uwierzytelnianie odbywa się przez normalne uwierzytelnianie Gateway.
|
||||
- Powierzchnia obejmuje tylko metryki (bez śladów ani logów).
|
||||
- Powierzchnia obejmuje tylko metryki (bez śladów ani dzienników).
|
||||
- Najlepsze dla stosów już ustandaryzowanych na Prometheus + Grafana.
|
||||
|
||||
</Tab>
|
||||
<Tab title="diagnostics-otel">
|
||||
- Model **push**: OpenClaw wysyła OTLP/HTTP do kolektora lub backendu zgodnego z OTLP.
|
||||
- Powierzchnia obejmuje metryki, ślady i logi.
|
||||
- Łączy z Prometheus przez OpenTelemetry Collector (eksporter `prometheus` lub `prometheusremotewrite`), gdy potrzebujesz obu.
|
||||
- Pełny katalog znajdziesz w [eksport OpenTelemetry](/pl/gateway/opentelemetry).
|
||||
- Powierzchnia obejmuje metryki, ślady i dzienniki.
|
||||
- Łączy się z Prometheus przez OpenTelemetry Collector (eksporter `prometheus` lub `prometheusremotewrite`), gdy potrzebujesz obu.
|
||||
- Pełny katalog znajdziesz w [eksporcie OpenTelemetry](/pl/gateway/opentelemetry).
|
||||
|
||||
</Tab>
|
||||
</Tabs>
|
||||
@ -202,7 +209,7 @@ OpenClaw obsługuje obie powierzchnie niezależnie. Możesz uruchomić jedną, o
|
||||
<AccordionGroup>
|
||||
<Accordion title="Pusta treść odpowiedzi">
|
||||
- Sprawdź `diagnostics.enabled: true` w konfiguracji.
|
||||
- Potwierdź, że Plugin jest włączony i załadowany poleceniem `openclaw plugins list --enabled`.
|
||||
- Potwierdź, że Plugin jest włączony i załadowany za pomocą `openclaw plugins list --enabled`.
|
||||
- Wygeneruj trochę ruchu; liczniki i histogramy emitują wiersze dopiero po co najmniej jednym zdarzeniu.
|
||||
|
||||
</Accordion>
|
||||
@ -210,16 +217,16 @@ OpenClaw obsługuje obie powierzchnie niezależnie. Możesz uruchomić jedną, o
|
||||
Endpoint wymaga zakresu operatora Gateway (`auth: "gateway"` z `gatewayRuntimeScopeSurface: "trusted-operator"`). Użyj tego samego tokenu lub hasła, którego Prometheus używa dla dowolnej innej trasy operatora Gateway. Nie ma publicznego trybu bez uwierzytelniania.
|
||||
</Accordion>
|
||||
<Accordion title="`openclaw_prometheus_series_dropped_total` rośnie">
|
||||
Nowy atrybut przekracza limit **2048** serii. Sprawdź ostatnie metryki pod kątem etykiety o nieoczekiwanie wysokiej kardynalności i napraw ją u źródła. Eksporter celowo odrzuca nowe serie zamiast po cichu przepisywać etykiety.
|
||||
Nowy atrybut przekracza limit **2048** serii. Sprawdź ostatnie metryki pod kątem etykiety o niespodziewanie wysokiej kardynalności i napraw ją u źródła. Eksporter celowo odrzuca nowe serie zamiast po cichu przepisywać etykiety.
|
||||
</Accordion>
|
||||
<Accordion title="Prometheus pokazuje nieaktualne serie po restarcie">
|
||||
Plugin przechowuje stan tylko w pamięci. Po restarcie Gateway liczniki resetują się do zera, a wskaźniki wznawiają działanie przy następnej zgłoszonej wartości. Użyj PromQL `rate()` i `increase()`, aby poprawnie obsługiwać resety.
|
||||
Plugin przechowuje stan wyłącznie w pamięci. Po restarcie Gateway liczniki resetują się do zera, a wskaźniki wznawiają pracę od następnej zgłoszonej wartości. Użyj PromQL `rate()` i `increase()`, aby czysto obsługiwać resety.
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## Powiązane
|
||||
|
||||
- [Eksport diagnostyki](/pl/gateway/diagnostics) — lokalne archiwum zip diagnostyki dla pakietów wsparcia
|
||||
- [Eksport diagnostyki](/pl/gateway/diagnostics) — lokalne archiwum ZIP z diagnostyką dla pakietów wsparcia
|
||||
- [Kondycja i gotowość](/pl/gateway/health) — sondy `/healthz` i `/readyz`
|
||||
- [Logowanie](/pl/logging) — logowanie oparte na plikach
|
||||
- [Eksport OpenTelemetry](/pl/gateway/opentelemetry) — wypychanie OTLP dla śladów, metryk i logów
|
||||
- [Eksport OpenTelemetry](/pl/gateway/opentelemetry) — wysyłanie OTLP dla śladów, metryk i logów
|
||||
|
||||
@ -1,47 +1,47 @@
|
||||
---
|
||||
read_when:
|
||||
- Wyszukiwanie definicji publicznych kanałów wydań
|
||||
- Szukanie definicji publicznych kanałów wydań
|
||||
- Uruchamianie walidacji wydania lub akceptacji pakietu
|
||||
- Szukasz informacji o nazewnictwie wersji i rytmie wydań
|
||||
summary: Ścieżki wydań, lista kontrolna operatora, środowiska walidacyjne, nazewnictwo wersji i harmonogram
|
||||
- Szukasz nazewnictwa wersji i cyklu wydań
|
||||
summary: Ścieżki wydań, lista kontrolna operatora, środowiska walidacyjne, nazewnictwo wersji i cykl
|
||||
title: Polityka wydań
|
||||
x-i18n:
|
||||
generated_at: "2026-05-05T06:18:50Z"
|
||||
generated_at: "2026-05-06T10:05:21Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 9980265c30c6a6571db5512749ec173cca79ac70494fd09968add793be9717a5
|
||||
source_hash: d3b9f4875496d7278ba18a8b5cb2735fb870cf32254bfc1fd819e4f233db489e
|
||||
source_path: reference/RELEASING.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
OpenClaw ma trzy publiczne ścieżki wydań:
|
||||
|
||||
- stable: wydania oznaczone tagami, które domyślnie publikują do npm `beta`, albo do npm `latest`, gdy zostanie to wyraźnie zażądane
|
||||
- beta: tagi przedwydań publikowane do npm `beta`
|
||||
- dev: ruchoma głowica gałęzi `main`
|
||||
- stable: oznaczone tagami wydania, które domyślnie publikują do npm `beta`, albo do npm `latest`, gdy zostanie to jawnie zażądane
|
||||
- beta: tagi przedwydaniowe, które publikują do npm `beta`
|
||||
- dev: ruchoma głowica `main`
|
||||
|
||||
## Nazewnictwo wersji
|
||||
|
||||
- Wersja wydania stabilnego: `YYYY.M.D`
|
||||
- Wersja wydania stable: `YYYY.M.D`
|
||||
- Tag Git: `vYYYY.M.D`
|
||||
- Wersja wydania poprawkowego stabilnego: `YYYY.M.D-N`
|
||||
- Wersja wydania poprawkowego stable: `YYYY.M.D-N`
|
||||
- Tag Git: `vYYYY.M.D-N`
|
||||
- Wersja przedwydania beta: `YYYY.M.D-beta.N`
|
||||
- Wersja przedwydaniowa beta: `YYYY.M.D-beta.N`
|
||||
- Tag Git: `vYYYY.M.D-beta.N`
|
||||
- Nie dodawaj zer wiodących do miesiąca ani dnia
|
||||
- `latest` oznacza aktualnie promowane stabilne wydanie npm
|
||||
- `beta` oznacza aktualny docelowy pakiet instalacyjny beta
|
||||
- Wydania stabilne i poprawkowe stabilne domyślnie publikują do npm `beta`; operatorzy wydania mogą jawnie wskazać `latest` albo później wypromować zweryfikowaną kompilację beta
|
||||
- Każde stabilne wydanie OpenClaw dostarcza razem pakiet npm i aplikację macOS;
|
||||
wydania beta zwykle najpierw walidują i publikują ścieżkę npm/pakietu, a
|
||||
kompilacja/podpisywanie/notaryzacja aplikacji mac jest zarezerwowana dla wydań stabilnych, chyba że wyraźnie zażądano inaczej
|
||||
- `latest` oznacza aktualne promowane wydanie stable w npm
|
||||
- `beta` oznacza aktualny cel instalacji beta
|
||||
- Wydania stable i poprawkowe stable domyślnie publikują do npm `beta`; operatorzy wydania mogą jawnie wskazać `latest` albo później promować zweryfikowaną kompilację beta
|
||||
- Każde wydanie stable OpenClaw dostarcza razem pakiet npm i aplikację macOS;
|
||||
wydania beta zwykle najpierw weryfikują i publikują ścieżkę npm/pakietu, a
|
||||
kompilacja/podpisywanie/notaryzacja aplikacji mac jest zarezerwowana dla wydań stable, chyba że zostanie jawnie zażądana
|
||||
|
||||
## Rytm wydań
|
||||
|
||||
- Wydania przechodzą najpierw przez beta
|
||||
- Stabilne wydanie następuje dopiero po zweryfikowaniu najnowszej bety
|
||||
- Stable następuje dopiero po zweryfikowaniu najnowszej beta
|
||||
- Maintainerzy zwykle przygotowują wydania z gałęzi `release/YYYY.M.D` utworzonej
|
||||
z bieżącej `main`, aby walidacja wydania i poprawki nie blokowały nowego
|
||||
z aktualnego `main`, aby walidacja wydania i poprawki nie blokowały nowego
|
||||
rozwoju na `main`
|
||||
- Jeśli tag beta został wypchnięty lub opublikowany i wymaga poprawki, maintainerzy tworzą
|
||||
następny tag `-beta.N` zamiast usuwać albo odtwarzać stary tag beta
|
||||
@ -50,128 +50,245 @@ OpenClaw ma trzy publiczne ścieżki wydań:
|
||||
|
||||
## Lista kontrolna operatora wydania
|
||||
|
||||
Ta lista kontrolna pokazuje publiczny kształt procesu wydania. Prywatne poświadczenia,
|
||||
podpisywanie, notaryzacja, odzyskiwanie dist-tagów i szczegóły awaryjnego wycofania pozostają w
|
||||
Ta lista kontrolna pokazuje publiczny kształt przepływu wydania. Prywatne poświadczenia,
|
||||
podpisywanie, notaryzacja, odzyskiwanie dist-tag i szczegóły awaryjnego wycofania pozostają w
|
||||
runbooku wydania dostępnym tylko dla maintainerów.
|
||||
|
||||
1. Zacznij od bieżącej `main`: pobierz najnowsze zmiany, potwierdź, że docelowy commit został wypchnięty,
|
||||
1. Zacznij od aktualnego `main`: pobierz najnowsze zmiany, potwierdź, że docelowy commit jest wypchnięty,
|
||||
i potwierdź, że bieżące CI `main` jest wystarczająco zielone, aby utworzyć z niego gałąź.
|
||||
2. Przepisz górną sekcję `CHANGELOG.md` na podstawie rzeczywistej historii commitów za pomocą
|
||||
`/changelog`, utrzymuj wpisy jako skierowane do użytkowników, zatwierdź je, wypchnij i wykonaj jeszcze raz rebase/pull
|
||||
przed utworzeniem gałęzi.
|
||||
3. Przejrzyj rekordy zgodności wydania w
|
||||
2. Przepisz najwyższą sekcję `CHANGELOG.md` na podstawie rzeczywistej historii commitów za pomocą
|
||||
`/changelog`, zachowaj wpisy zorientowane na użytkownika, commituj ją, wypchnij i wykonaj rebase/pull
|
||||
jeszcze raz przed utworzeniem gałęzi.
|
||||
3. Przejrzyj rekordy kompatybilności wydania w
|
||||
`src/plugins/compat/registry.ts` i
|
||||
`src/commands/doctor/shared/deprecation-compat.ts`. Usuwaj wygasłą
|
||||
zgodność tylko wtedy, gdy ścieżka aktualizacji pozostaje objęta ochroną, albo zapisz, dlaczego jest
|
||||
`src/commands/doctor/shared/deprecation-compat.ts`. Usuń wygasłą
|
||||
kompatybilność tylko wtedy, gdy ścieżka aktualizacji pozostaje pokryta, albo zapisz, dlaczego jest
|
||||
celowo utrzymywana.
|
||||
4. Utwórz `release/YYYY.M.D` z bieżącej `main`; nie wykonuj normalnej pracy wydaniowej
|
||||
4. Utwórz `release/YYYY.M.D` z aktualnego `main`; nie wykonuj normalnej pracy nad wydaniem
|
||||
bezpośrednio na `main`.
|
||||
5. Podbij wszystkie wymagane lokalizacje wersji dla zamierzonego tagu, uruchom
|
||||
5. Podbij każdą wymaganą lokalizację wersji dla zamierzonego tagu, uruchom
|
||||
`pnpm plugins:sync`, aby publikowalne pakiety Plugin miały wspólną wersję wydania
|
||||
i metadane zgodności, a następnie uruchom lokalną deterministyczną weryfikację wstępną:
|
||||
i metadane kompatybilności, a następnie uruchom lokalny deterministyczny preflight:
|
||||
`pnpm check:test-types`, `pnpm check:architecture`,
|
||||
`pnpm build && pnpm ui:build`, `pnpm plugins:sync:check` oraz
|
||||
`pnpm build && pnpm ui:build`, `pnpm plugins:sync:check` i
|
||||
`pnpm release:check`.
|
||||
6. Uruchom `OpenClaw NPM Release` z `preflight_only=true`. Zanim tag istnieje,
|
||||
pełny 40-znakowy SHA gałęzi wydania jest dozwolony tylko do walidacji
|
||||
wstępnej. Zapisz udany `preflight_run_id`.
|
||||
7. Uruchom wszystkie testy przedwydaniowe przez `Full Release Validation` dla
|
||||
gałęzi wydania, tagu albo pełnego SHA commitu. To jest jedyny ręczny punkt wejścia
|
||||
dla czterech dużych skrzynek testowych wydania: Vitest, Docker, QA Lab i Package.
|
||||
preflight. Zapisz udany `preflight_run_id`.
|
||||
7. Uruchom wszystkie testy przedwydaniowe za pomocą `Full Release Validation` dla
|
||||
gałęzi wydania, tagu albo pełnego SHA commita. To jest jeden ręczny punkt wejścia
|
||||
dla czterech dużych testowych środowisk wydania: Vitest, Docker, QA Lab i Package.
|
||||
8. Jeśli walidacja się nie powiedzie, napraw problem na gałęzi wydania i ponownie uruchom najmniejszy nieudany
|
||||
plik, ścieżkę, zadanie workflow, profil pakietu, dostawcę albo allowlistę modeli, które
|
||||
potwierdzają poprawkę. Ponownie uruchamiaj pełną parasolową walidację tylko wtedy, gdy zmieniony obszar sprawia,
|
||||
plik, ścieżkę, zadanie workflow, profil pakietu, providera albo allowlistę modeli, która
|
||||
potwierdza poprawkę. Ponownie uruchom pełny parasol tylko wtedy, gdy zmieniona powierzchnia sprawia,
|
||||
że wcześniejsze dowody są nieaktualne.
|
||||
9. Dla beta oznacz tagiem `vYYYY.M.D-beta.N`, a następnie uruchom `OpenClaw Release Publish` z
|
||||
pasującej gałęzi `release/YYYY.M.D`. Sprawdza `pnpm plugins:sync:check`,
|
||||
najpierw publikuje wszystkie publikowalne pakiety Plugin do npm, następnie publikuje ten sam
|
||||
zestaw do ClawHub jako tarballe ClawPack npm-pack, a potem promuje
|
||||
przygotowany artefakt wstępny OpenClaw npm z pasującym dist-tagiem. Po
|
||||
publikacji uruchom akceptację pakietu po publikacji
|
||||
9. Dla beta otaguj `vYYYY.M.D-beta.N`, a następnie uruchom `OpenClaw Release Publish` z
|
||||
pasującej gałęzi `release/YYYY.M.D`. Weryfikuje `pnpm plugins:sync:check`,
|
||||
wysyła wszystkie publikowalne pakiety Plugin do npm i ten sam zestaw do
|
||||
ClawHub równolegle, a następnie promuje przygotowany artefakt preflight OpenClaw npm
|
||||
z pasującym dist-tag, gdy tylko publikacja pakietów Plugin do npm się powiedzie.
|
||||
Publikacja do ClawHub może nadal trwać, gdy OpenClaw npm jest publikowany, ale
|
||||
workflow publikacji wydania nie kończy się, dopóki obie ścieżki publikacji pakietów Plugin i
|
||||
ścieżka publikacji OpenClaw npm nie zakończą się pomyślnie. Po publikacji uruchom
|
||||
akceptację pakietu po publikacji
|
||||
względem opublikowanego pakietu `openclaw@YYYY.M.D-beta.N` albo
|
||||
`openclaw@beta`. Jeśli wypchnięte lub opublikowane przedwydanie wymaga poprawki,
|
||||
utwórz następny pasujący numer przedwydania; nie usuwaj ani nie przepisuj starego
|
||||
przedwydania.
|
||||
10. Dla wydania stabilnego kontynuuj dopiero po tym, jak zweryfikowana beta lub kandydat do wydania ma
|
||||
wymagane dowody walidacji. Stabilna publikacja npm również przechodzi przez
|
||||
`OpenClaw Release Publish`, ponownie używając udanego artefaktu wstępnego przez
|
||||
`preflight_run_id`; gotowość stabilnego wydania macOS wymaga także
|
||||
`openclaw@beta`. Jeśli wypchnięte albo opublikowane wydanie przedwydaniowe wymaga poprawki,
|
||||
utwórz następny pasujący numer przedwydaniowy; nie usuwaj ani nie przepisuj starego
|
||||
wydania przedwydaniowego.
|
||||
10. Dla stable kontynuuj dopiero wtedy, gdy zweryfikowana beta albo kandydat wydania ma
|
||||
wymagane dowody walidacji. Publikacja stable do npm również przechodzi przez
|
||||
`OpenClaw Release Publish`, ponownie używając udanego artefaktu preflight przez
|
||||
`preflight_run_id`; gotowość wydania stable na macOS wymaga też
|
||||
spakowanych `.zip`, `.dmg`, `.dSYM.zip` oraz zaktualizowanego `appcast.xml` na `main`.
|
||||
11. Po publikacji uruchom weryfikator npm po publikacji, opcjonalny samodzielny
|
||||
opublikowany-npm Telegram E2E, gdy potrzebujesz dowodu kanału po publikacji,
|
||||
promocję dist-tagu, gdy jest potrzebna, notatki wydania/przedwydania GitHub z
|
||||
pełnej pasującej sekcji `CHANGELOG.md` oraz kroki ogłoszenia
|
||||
wydania.
|
||||
11. Po publikacji uruchom weryfikator npm po publikacji, opcjonalne samodzielne
|
||||
opublikowane-npm Telegram E2E, gdy potrzebujesz dowodu kanału po publikacji,
|
||||
promocję dist-tag, gdy jest potrzebna, notatki wydania/przedwydania GitHub z
|
||||
kompletnej pasującej sekcji `CHANGELOG.md` oraz kroki ogłoszenia wydania.
|
||||
|
||||
## Weryfikacja wstępna wydania
|
||||
## Preflight wydania
|
||||
|
||||
- Uruchom `pnpm check:test-types` przed kontrolą wstępną wydania, aby testowy TypeScript pozostawał objęty sprawdzeniem poza szybszą lokalną bramką `pnpm check`
|
||||
- Uruchom `pnpm check:architecture` przed kontrolą wstępną wydania, aby szersze sprawdzenia cykli importów i granic architektury były zielone poza szybszą lokalną bramką
|
||||
- Uruchom `pnpm build && pnpm ui:build` przed `pnpm release:check`, aby oczekiwane artefakty wydania `dist/*` i pakiet Control UI istniały na potrzeby kroku walidacji paczki
|
||||
- Uruchom `pnpm plugins:sync` po podbiciu wersji głównej i przed tagowaniem. Aktualizuje wersje publikowalnych pakietów plugin, metadane zgodności peer/API OpenClaw, metadane kompilacji oraz szkice changelogów pluginów tak, aby odpowiadały wersji wydania rdzenia. `pnpm plugins:sync:check` to niemutująca osłona wydania; przepływ publikowania kończy się niepowodzeniem przed jakąkolwiek mutacją rejestru, jeśli ten krok został pominięty.
|
||||
- Uruchom ręczny przepływ `Full Release Validation` przed zatwierdzeniem wydania, aby z jednego punktu wejścia uruchomić wszystkie przedwydaniowe testboxy. Przyjmuje gałąź, tag albo pełny SHA commita, wywołuje ręczny `CI` i wywołuje `OpenClaw Release Checks` dla smoke testu instalacji, akceptacji pakietu, międzyplatformowych sprawdzeń pakietu, parytetu QA Lab, torów Matrix i Telegram. Stabilne/domyślne uruchomienia trzymają wyczerpujące live/E2E oraz soak ścieżki wydania Docker za `run_release_soak=true`; `release_profile=full` wymusza soak. Z `release_profile=full` i `rerun_group=all` uruchamia też pakietowe E2E Telegram względem artefaktu `release-package-under-test` z kontroli wydania. Podaj `npm_telegram_package_spec` po publikacji, gdy to samo E2E Telegram ma również potwierdzić opublikowany pakiet npm. Podaj `package_acceptance_package_spec` po publikacji, gdy Package Acceptance ma uruchomić swoją macierz pakietu/aktualizacji względem wysłanego pakietu npm zamiast artefaktu zbudowanego z SHA. Podaj `evidence_package_spec`, gdy prywatny raport dowodowy ma potwierdzić, że walidacja odpowiada opublikowanemu pakietowi npm bez wymuszania E2E Telegram. Przykład:
|
||||
- Uruchom `pnpm check:test-types` przed kontrolą wstępną wydania, aby testowy TypeScript pozostał
|
||||
objęty sprawdzaniem poza szybszą lokalną bramką `pnpm check`
|
||||
- Uruchom `pnpm check:architecture` przed kontrolą wstępną wydania, aby szersze
|
||||
sprawdzanie cykli importów i granic architektury było zielone poza szybszą lokalną bramką
|
||||
- Uruchom `pnpm build && pnpm ui:build` przed `pnpm release:check`, aby oczekiwane
|
||||
artefakty wydania `dist/*` i pakiet Control UI istniały dla kroku
|
||||
walidacji paczki
|
||||
- Uruchom `pnpm plugins:sync` po podbiciu wersji w katalogu głównym i przed tagowaniem. Aktualizuje
|
||||
wersje publikowalnych pakietów pluginów, metadane zgodności OpenClaw peer/API,
|
||||
metadane kompilacji oraz szkielety dzienników zmian pluginów, aby pasowały do wersji
|
||||
wydania rdzenia. `pnpm plugins:sync:check` to niemodyfikująca bramka wydania;
|
||||
przepływ publikowania zawiedzie przed jakąkolwiek mutacją rejestru, jeśli ten krok został
|
||||
pominięty.
|
||||
- Uruchom ręczny przepływ pracy `Full Release Validation` przed zatwierdzeniem wydania, aby
|
||||
uruchomić wszystkie przedwydaniowe środowiska testowe z jednego punktu wejścia. Przyjmuje gałąź,
|
||||
tag albo pełny SHA commita, uruchamia ręczny `CI` oraz uruchamia
|
||||
`OpenClaw Release Checks` dla smoke testu instalacji, akceptacji pakietu, międzyplatformowych
|
||||
sprawdzeń pakietów, zgodności QA Lab, ścieżek Matrix i Telegram. Stabilne/domyślne uruchomienia
|
||||
trzymają wyczerpujące live/E2E i soak ścieżki wydania Docker za
|
||||
`run_release_soak=true`; `release_profile=full` wymusza soak. Z
|
||||
`release_profile=full` i `rerun_group=all` uruchamia też pakietowe Telegram
|
||||
E2E względem artefaktu `release-package-under-test` ze sprawdzeń wydania.
|
||||
Podaj `npm_telegram_package_spec` po publikacji, gdy to samo
|
||||
Telegram E2E ma też potwierdzić opublikowany pakiet npm. Podaj
|
||||
`package_acceptance_package_spec` po publikacji, gdy Package Acceptance
|
||||
ma uruchomić swoją macierz pakietu/aktualizacji względem wysłanego pakietu npm zamiast
|
||||
artefaktu zbudowanego z SHA. Podaj
|
||||
`evidence_package_spec`, gdy prywatny raport dowodowy ma potwierdzić, że
|
||||
walidacja odpowiada opublikowanemu pakietowi npm bez wymuszania Telegram E2E.
|
||||
Przykład:
|
||||
`gh workflow run full-release-validation.yml --ref main -f ref=release/YYYY.M.D`
|
||||
- Uruchom ręczny przepływ `Package Acceptance`, gdy chcesz uzyskać dowód kanałem bocznym dla kandydata pakietu, podczas gdy prace nad wydaniem trwają dalej. Użyj `source=npm` dla `openclaw@beta`, `openclaw@latest` albo dokładnej wersji wydania; `source=ref`, aby spakować zaufaną gałąź/tag/SHA `package_ref` z bieżącą uprzężą `workflow_ref`; `source=url` dla archiwum tarball HTTPS z wymaganym SHA-256; albo `source=artifact` dla archiwum tarball przesłanego przez inne uruchomienie GitHub Actions. Przepływ rozwiązuje kandydata do `package-under-test`, ponownie używa harmonogramu wydania Docker E2E względem tego archiwum tarball i może uruchomić QA Telegram względem tego samego archiwum tarball z `telegram_mode=mock-openai` albo `telegram_mode=live-frontier`. Gdy wybrane tory Docker obejmują `published-upgrade-survivor`, artefakt pakietu jest kandydatem, a `published_upgrade_survivor_baseline` wybiera opublikowaną bazę. `update-restart-auth` używa pakietu kandydata zarówno jako zainstalowanego CLI, jak i package-under-test, dzięki czemu ćwiczy zarządzaną ścieżkę restartu polecenia aktualizacji kandydata.
|
||||
- Uruchom ręczny przepływ pracy `Package Acceptance`, gdy chcesz uzyskać dowód kanałem bocznym
|
||||
dla kandydata pakietu, podczas gdy prace nad wydaniem trwają dalej. Użyj `source=npm` dla
|
||||
`openclaw@beta`, `openclaw@latest` albo dokładnej wersji wydania; `source=ref`
|
||||
do spakowania zaufanej gałęzi/tagu/SHA `package_ref` z bieżącą
|
||||
uprzężą `workflow_ref`; `source=url` dla tarballa HTTPS z wymaganym
|
||||
SHA-256; albo `source=artifact` dla tarballa przesłanego przez inne uruchomienie GitHub
|
||||
Actions. Przepływ pracy rozwiązuje kandydata do
|
||||
`package-under-test`, ponownie używa harmonogramu wydania Docker E2E względem tego
|
||||
tarballa i może uruchomić QA Telegram względem tego samego tarballa z
|
||||
`telegram_mode=mock-openai` albo `telegram_mode=live-frontier`. Gdy
|
||||
wybrane ścieżki Docker obejmują `published-upgrade-survivor`, artefakt
|
||||
pakietu jest kandydatem, a `published_upgrade_survivor_baseline` wybiera
|
||||
opublikowaną bazę. `update-restart-auth` używa pakietu kandydującego jako
|
||||
zarówno zainstalowanego CLI, jak i package-under-test, więc ćwiczy ścieżkę
|
||||
zarządzanego restartu polecenia aktualizacji kandydata.
|
||||
Przykład: `gh workflow run package-acceptance.yml --ref main -f workflow_ref=main -f source=npm -f package_spec=openclaw@beta -f suite_profile=product -f published_upgrade_survivor_baseline=openclaw@2026.4.26 -f telegram_mode=mock-openai`
|
||||
Typowe profile:
|
||||
- `smoke`: tory instalacji/kanału/agenta, sieci Gateway i przeładowania konfiguracji
|
||||
- `package`: natywne dla artefaktu tory pakietu/aktualizacji/restartu/pluginów bez OpenWebUI ani live ClawHub
|
||||
- `product`: profil pakietu plus kanały MCP, czyszczenie cron/subagentów, wyszukiwanie internetowe OpenAI i OpenWebUI
|
||||
- `smoke`: ścieżki instalacji/kanału/agenta, sieci Gateway i przeładowania konfiguracji
|
||||
- `package`: natywne dla artefaktu ścieżki pakietu/aktualizacji/restartu/pluginów bez OpenWebUI ani live ClawHub
|
||||
- `product`: profil pakietowy oraz kanały MCP, czyszczenie cron/subagenta,
|
||||
wyszukiwanie webowe OpenAI i OpenWebUI
|
||||
- `full`: fragmenty ścieżki wydania Docker z OpenWebUI
|
||||
- `custom`: dokładny wybór `docker_lanes` dla ukierunkowanego ponownego uruchomienia
|
||||
- Uruchom ręczny przepływ `CI` bezpośrednio, gdy potrzebujesz tylko pełnego zwykłego pokrycia CI dla kandydata wydania. Ręczne wywołania CI omijają ograniczanie do zmienionego zakresu i wymuszają shardy Linux Node, shardy wbudowanych pluginów, kontrakty kanałów, zgodność Node 22, `check`, `check-additional`, smoke test kompilacji, sprawdzenia dokumentacji, Python skills, Windows, macOS, Android oraz tory i18n Control UI.
|
||||
- `custom`: dokładny wybór `docker_lanes` dla skoncentrowionego ponownego uruchomienia
|
||||
- Uruchom ręczny przepływ pracy `CI` bezpośrednio, gdy potrzebujesz tylko pełnego normalnego
|
||||
pokrycia CI dla kandydata wydania. Ręczne uruchomienia CI omijają zakresowanie według zmian
|
||||
i wymuszają shardy Linux Node, shardy pakietowych pluginów, kontrakty kanałów,
|
||||
zgodność Node 22, `check`, `check-additional`, smoke test kompilacji,
|
||||
sprawdzenia dokumentacji, Python skills, Windows, macOS, Android oraz ścieżki i18n
|
||||
Control UI.
|
||||
Przykład: `gh workflow run ci.yml --ref release/YYYY.M.D`
|
||||
- Uruchom `pnpm qa:otel:smoke` podczas walidacji telemetrii wydania. Ćwiczy QA-lab przez lokalny odbiornik OTLP/HTTP i weryfikuje wyeksportowane nazwy spanów śladu, ograniczone atrybuty oraz redakcję treści/identyfikatorów bez wymagania Opik, Langfuse ani innego zewnętrznego kolektora.
|
||||
- Uruchom `pnpm release:check` przed każdym tagowanym wydaniem
|
||||
- Uruchom `OpenClaw Release Publish` dla mutującej sekwencji publikowania po utworzeniu taga. Wywołaj go z `release/YYYY.M.D` (albo `main`, gdy publikujesz tag osiągalny z main), przekaż tag wydania i udane OpenClaw npm `preflight_run_id`, a domyślny zakres publikowania pluginów `all-publishable` zachowaj, chyba że celowo uruchamiasz ukierunkowaną naprawę. Przepływ serializuje publikację npm pluginów, publikację pluginów ClawHub i publikację npm OpenClaw, aby pakiet rdzenia nie został opublikowany przed swoimi zewnętrznymi pluginami.
|
||||
- Kontrole wydania działają teraz w osobnym ręcznym przepływie:
|
||||
- Uruchom `pnpm qa:otel:smoke` podczas walidacji telemetrii wydania. Ćwiczy
|
||||
QA-lab przez lokalny odbiornik OTLP/HTTP i weryfikuje wyeksportowane nazwy spanów
|
||||
śladu, ograniczone atrybuty oraz redakcję treści/identyfikatorów bez
|
||||
wymagania Opik, Langfuse ani innego zewnętrznego kolektora.
|
||||
- Uruchom `pnpm release:check` przed każdym otagowanym wydaniem
|
||||
- Uruchom `OpenClaw Release Publish` dla modyfikującej sekwencji publikowania po
|
||||
utworzeniu tagu. Uruchom go z `release/YYYY.M.D` (albo `main`, gdy publikujesz
|
||||
tag osiągalny z main), przekaż tag wydania i udany `preflight_run_id` npm
|
||||
OpenClaw oraz pozostaw domyślny zakres publikacji pluginów
|
||||
`all-publishable`, chyba że celowo uruchamiasz skoncentrowaną naprawę. Ten
|
||||
przepływ pracy serializuje publikację pluginów npm, publikację pluginów ClawHub i publikację npm OpenClaw,
|
||||
aby pakiet rdzenia nie został opublikowany przed swoimi zewnętrznymi
|
||||
pluginami.
|
||||
- Sprawdzenia wydania działają teraz w oddzielnym ręcznym przepływie pracy:
|
||||
`OpenClaw Release Checks`
|
||||
- `OpenClaw Release Checks` uruchamia także tor parytetu mock QA Lab oraz szybki profil live Matrix i tor QA Telegram przed zatwierdzeniem wydania. Tory live używają środowiska `qa-live-shared`; Telegram używa też dzierżaw poświadczeń Convex CI. Uruchom ręczny przepływ `QA-Lab - All Lanes` z `matrix_profile=all` i `matrix_shards=true`, gdy chcesz pełny inwentarz transportu Matrix, multimediów i E2EE równolegle.
|
||||
- Międzyplatformowa walidacja runtime instalacji i aktualizacji jest częścią publicznych `OpenClaw Release Checks` i `Full Release Validation`, które bezpośrednio wywołują przepływ wielokrotnego użytku `.github/workflows/openclaw-cross-os-release-checks-reusable.yml`
|
||||
- Ten podział jest celowy: utrzymuje prawdziwą ścieżkę wydania npm krótką, deterministyczną i skoncentrowaną na artefaktach, podczas gdy wolniejsze kontrole live pozostają we własnym torze, aby nie wstrzymywały ani nie blokowały publikacji
|
||||
- Kontrole wydania zawierające sekrety powinny być wywoływane przez `Full Release Validation` albo z referencji przepływu `main`/release, aby logika przepływu i sekrety pozostały kontrolowane
|
||||
- `OpenClaw Release Checks` przyjmuje gałąź, tag albo pełny SHA commita, o ile rozwiązany commit jest osiągalny z gałęzi OpenClaw albo taga wydania
|
||||
- Wstępna kontrola tylko walidacyjna `OpenClaw NPM Release` akceptuje też bieżący pełny 40-znakowy SHA commita gałęzi przepływu bez wymagania wypchniętego taga
|
||||
- Ta ścieżka SHA służy tylko do walidacji i nie może zostać wypromowana do prawdziwej publikacji
|
||||
- W trybie SHA przepływ syntetyzuje `v<package.json version>` tylko na potrzeby sprawdzenia metadanych pakietu; prawdziwa publikacja nadal wymaga prawdziwego taga wydania
|
||||
- Oba przepływy utrzymują prawdziwą ścieżkę publikacji i promocji na runnerach hostowanych przez GitHub, podczas gdy niemutująca ścieżka walidacji może używać większych runnerów Blacksmith Linux
|
||||
- Ten przepływ uruchamia `OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_CACHE_TEST=1 pnpm test:live:cache`, używając sekretów przepływu `OPENAI_API_KEY` i `ANTHROPIC_API_KEY`
|
||||
- Wstępna kontrola wydania npm nie czeka już na osobny tor kontroli wydania
|
||||
- Uruchom `RELEASE_TAG=vYYYY.M.D node --import tsx scripts/openclaw-npm-release-check.ts` (albo pasujący tag beta/poprawki) przed zatwierdzeniem
|
||||
- Po publikacji npm uruchom `node --import tsx scripts/openclaw-npm-postpublish-verify.ts YYYY.M.D` (albo pasującą wersję beta/poprawki), aby zweryfikować ścieżkę instalacji z opublikowanego rejestru w świeżym prefiksie tymczasowym
|
||||
- Po publikacji beta uruchom `OPENCLAW_NPM_TELEGRAM_PACKAGE_SPEC=openclaw@YYYY.M.D-beta.N OPENCLAW_NPM_TELEGRAM_CREDENTIAL_SOURCE=convex OPENCLAW_NPM_TELEGRAM_CREDENTIAL_ROLE=ci pnpm test:docker:npm-telegram-live`, aby zweryfikować onboarding zainstalowanego pakietu, konfigurację Telegram i prawdziwe E2E Telegram względem opublikowanego pakietu npm przy użyciu współdzielonej puli dzierżawionych poświadczeń Telegram. Lokalne jednorazowe uruchomienia maintainerów mogą pominąć zmienne Convex i przekazać trzy poświadczenia env `OPENCLAW_QA_TELEGRAM_*` bezpośrednio.
|
||||
- Aby uruchomić pełny postpublikacyjny smoke test beta z maszyny maintainera, użyj `pnpm release:beta-smoke -- --beta betaN`. Helper uruchamia walidację aktualizacji npm Parallels/świeżego celu, wywołuje `NPM Telegram Beta E2E`, odpytuje dokładne uruchomienie przepływu, pobiera artefakt i wypisuje raport Telegram.
|
||||
- Maintainerzy mogą uruchomić tę samą postpublikacyjną kontrolę z GitHub Actions przez ręczny przepływ `NPM Telegram Beta E2E`. Jest celowo tylko ręczny i nie działa przy każdym scaleniu.
|
||||
- Automatyzacja wydań maintainerów używa teraz schematu preflight-then-promote:
|
||||
- prawdziwa publikacja npm musi przejść udane npm `preflight_run_id`
|
||||
- prawdziwa publikacja npm musi być wywołana z tej samej gałęzi `main` albo `release/YYYY.M.D`, co udane uruchomienie wstępnej kontroli
|
||||
- stabilne wydania npm domyślnie celują w `beta`
|
||||
- stabilna publikacja npm może jawnie celować w `latest` przez wejście przepływu
|
||||
- mutacja dist-tag npm oparta na tokenie znajduje się teraz w `openclaw/releases-private/.github/workflows/openclaw-npm-dist-tags.yml` ze względów bezpieczeństwa, ponieważ `npm dist-tag add` nadal wymaga `NPM_TOKEN`, podczas gdy publiczne repo zachowuje publikację wyłącznie przez OIDC
|
||||
- publiczny `macOS Release` służy tylko do walidacji; gdy tag istnieje wyłącznie na gałęzi wydania, ale przepływ jest wywoływany z `main`, ustaw `public_release_branch=release/YYYY.M.D`
|
||||
- prawdziwa prywatna publikacja Mac musi przejść udane prywatne mac `preflight_run_id` i `validate_run_id`
|
||||
- prawdziwe ścieżki publikacji promują przygotowane artefakty zamiast budować je ponownie
|
||||
- Dla stabilnych wydań poprawkowych takich jak `YYYY.M.D-N` weryfikator postpublikacyjny sprawdza także tę samą ścieżkę aktualizacji z prefiksu tymczasowego z `YYYY.M.D` do `YYYY.M.D-N`, aby poprawki wydania nie mogły po cichu zostawić starszych globalnych instalacji na bazowym stabilnym ładunku
|
||||
- Wstępna kontrola wydania npm kończy się niepowodzeniem domyślnie, chyba że archiwum tarball zawiera zarówno `dist/control-ui/index.html`, jak i niepusty ładunek `dist/control-ui/assets/`, abyśmy ponownie nie wysłali pustego panelu przeglądarkowego
|
||||
- Weryfikacja postpublikacyjna sprawdza również, czy opublikowane punkty wejścia pluginów i metadane pakietu są obecne w zainstalowanym układzie rejestru. Wydanie, które wysyła brakujące ładunki runtime pluginów, nie przechodzi weryfikatora postpublish i nie może zostać wypromowane do `latest`.
|
||||
- `pnpm test:install:smoke` egzekwuje też budżet `unpackedSize` paczki npm względem kandydującego archiwum tarball aktualizacji, więc e2e instalatora wykrywa przypadkowe nadmuchanie paczki przed ścieżką publikacji wydania
|
||||
- Jeśli prace nad wydaniem dotknęły planowania CI, manifestów czasu rozszerzeń albo macierzy testów rozszerzeń, przed zatwierdzeniem wygeneruj ponownie i przejrzyj wyjścia macierzy `plugin-prerelease-extension-shard` zarządzanej przez planner z `.github/workflows/plugin-prerelease.yml`, aby informacje o wydaniu nie opisywały przestarzałego układu CI
|
||||
- `OpenClaw Release Checks` uruchamia też ścieżkę zgodności mock QA Lab oraz szybki
|
||||
profil live Matrix i ścieżkę QA Telegram przed zatwierdzeniem wydania. Ścieżki live
|
||||
używają środowiska `qa-live-shared`; Telegram używa też dzierżaw poświadczeń Convex CI.
|
||||
Uruchom ręczny przepływ pracy `QA-Lab - All Lanes` z
|
||||
`matrix_profile=all` i `matrix_shards=true`, gdy chcesz pełny inwentarz transportu,
|
||||
mediów i E2EE Matrix równolegle.
|
||||
- Walidacja uruchomieniowa instalacji i aktualizacji między systemami jest częścią publicznych
|
||||
`OpenClaw Release Checks` i `Full Release Validation`, które wywołują
|
||||
bezpośrednio wielokrotnego użytku przepływ pracy
|
||||
`.github/workflows/openclaw-cross-os-release-checks-reusable.yml`
|
||||
- Ten podział jest celowy: utrzymuje prawdziwą ścieżkę wydania npm krótką,
|
||||
deterministyczną i skupioną na artefaktach, a wolniejsze sprawdzenia live pozostawia
|
||||
w ich własnej ścieżce, aby nie wstrzymywały ani nie blokowały publikacji
|
||||
- Sprawdzenia wydania zawierające sekrety powinny być uruchamiane przez `Full Release
|
||||
Validation` albo z referencji przepływu pracy `main`/wydania, aby logika przepływu pracy i
|
||||
sekrety pozostały kontrolowane
|
||||
- `OpenClaw Release Checks` przyjmuje gałąź, tag albo pełny SHA commita, o ile
|
||||
rozwiązany commit jest osiągalny z gałęzi OpenClaw lub tagu wydania
|
||||
- Walidacyjna tylko kontrola wstępna `OpenClaw NPM Release` przyjmuje też bieżący
|
||||
pełny 40-znakowy SHA commita gałęzi przepływu pracy bez wymagania wypchniętego tagu
|
||||
- Ta ścieżka SHA służy tylko do walidacji i nie może zostać awansowana do prawdziwej publikacji
|
||||
- W trybie SHA przepływ pracy syntetyzuje `v<package.json version>` tylko na potrzeby
|
||||
sprawdzenia metadanych pakietu; prawdziwa publikacja nadal wymaga prawdziwego tagu wydania
|
||||
- Oba przepływy pracy trzymają prawdziwą ścieżkę publikacji i promocji na runnerach
|
||||
hostowanych przez GitHub, podczas gdy niemodyfikująca ścieżka walidacji może używać większych
|
||||
runnerów Blacksmith Linux
|
||||
- Ten przepływ pracy uruchamia
|
||||
`OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_CACHE_TEST=1 pnpm test:live:cache`
|
||||
z użyciem sekretów przepływu pracy `OPENAI_API_KEY` i `ANTHROPIC_API_KEY`
|
||||
- Kontrola wstępna wydania npm nie czeka już na oddzielną ścieżkę sprawdzeń wydania
|
||||
- Uruchom `RELEASE_TAG=vYYYY.M.D node --import tsx scripts/openclaw-npm-release-check.ts`
|
||||
(albo odpowiadający tag beta/korekty) przed zatwierdzeniem
|
||||
- Po publikacji npm uruchom
|
||||
`node --import tsx scripts/openclaw-npm-postpublish-verify.ts YYYY.M.D`
|
||||
(albo odpowiadającą wersję beta/korekty), aby zweryfikować ścieżkę instalacji z opublikowanego rejestru
|
||||
w świeżym tymczasowym prefiksie
|
||||
- Po publikacji beta uruchom `OPENCLAW_NPM_TELEGRAM_PACKAGE_SPEC=openclaw@YYYY.M.D-beta.N OPENCLAW_NPM_TELEGRAM_CREDENTIAL_SOURCE=convex OPENCLAW_NPM_TELEGRAM_CREDENTIAL_ROLE=ci pnpm test:docker:npm-telegram-live`,
|
||||
aby zweryfikować onboarding zainstalowanego pakietu, konfigurację Telegram oraz prawdziwe Telegram E2E
|
||||
względem opublikowanego pakietu npm z użyciem współdzielonej puli dzierżawionych poświadczeń Telegram.
|
||||
Lokalne jednorazowe uruchomienia maintainerów mogą pominąć zmienne Convex i przekazać trzy
|
||||
poświadczenia środowiskowe `OPENCLAW_QA_TELEGRAM_*` bezpośrednio.
|
||||
- Aby uruchomić pełny smoke test beta po publikacji z maszyny maintainera, użyj `pnpm release:beta-smoke -- --beta betaN`. Helper uruchamia walidację aktualizacji npm Parallels/świeżego celu, uruchamia `NPM Telegram Beta E2E`, odpytuje dokładne uruchomienie przepływu pracy, pobiera artefakt i wypisuje raport Telegram.
|
||||
- Maintainerzy mogą uruchomić to samo sprawdzenie po publikacji z GitHub Actions przez
|
||||
ręczny przepływ pracy `NPM Telegram Beta E2E`. Jest celowo wyłącznie ręczny i
|
||||
nie działa przy każdym scaleniu.
|
||||
- Automatyzacja wydań maintainerów używa teraz modelu kontrola wstępna, potem promocja:
|
||||
- prawdziwa publikacja npm musi przejść udany `preflight_run_id` npm
|
||||
- prawdziwa publikacja npm musi zostać uruchomiona z tej samej gałęzi `main` lub
|
||||
`release/YYYY.M.D` co udane uruchomienie kontroli wstępnej
|
||||
- stabilne wydania npm domyślnie używają `beta`
|
||||
- stabilna publikacja npm może jawnie celować w `latest` przez wejście przepływu pracy
|
||||
- mutacja npm dist-tag oparta na tokenie znajduje się teraz w
|
||||
`openclaw/releases-private/.github/workflows/openclaw-npm-dist-tags.yml`
|
||||
ze względów bezpieczeństwa, ponieważ `npm dist-tag add` nadal potrzebuje `NPM_TOKEN`, podczas gdy
|
||||
publiczne repo zachowuje publikację wyłącznie przez OIDC
|
||||
- publiczny `macOS Release` służy tylko do walidacji; gdy tag istnieje tylko na
|
||||
gałęzi wydania, ale przepływ pracy jest uruchamiany z `main`, ustaw
|
||||
`public_release_branch=release/YYYY.M.D`
|
||||
- prawdziwa prywatna publikacja mac musi przejść udane prywatne mac
|
||||
`preflight_run_id` i `validate_run_id`
|
||||
- prawdziwe ścieżki publikacji promują przygotowane artefakty zamiast budować
|
||||
je ponownie
|
||||
- Dla stabilnych wydań korekcyjnych takich jak `YYYY.M.D-N` weryfikator po publikacji
|
||||
sprawdza też tę samą ścieżkę aktualizacji z tymczasowym prefiksem z `YYYY.M.D` do `YYYY.M.D-N`,
|
||||
aby korekty wydania nie mogły po cichu zostawić starszych globalnych instalacji na
|
||||
bazowym stabilnym ładunku
|
||||
- Kontrola wstępna wydania npm zawodzi bezpiecznie, chyba że tarball zawiera zarówno
|
||||
`dist/control-ui/index.html`, jak i niepusty ładunek `dist/control-ui/assets/`,
|
||||
abyśmy ponownie nie wysłali pustego panelu przeglądarkowego
|
||||
- Weryfikacja po publikacji sprawdza też, czy opublikowane punkty wejścia pluginów i
|
||||
metadane pakietów są obecne w zainstalowanym układzie rejestru. Wydanie, które
|
||||
wysyła brakujące ładunki uruchomieniowe pluginów, zawodzi weryfikator po publikacji i
|
||||
nie może zostać promowane do `latest`.
|
||||
- `pnpm test:install:smoke` egzekwuje też budżet `unpackedSize` paczki npm dla
|
||||
tarballa kandydującej aktualizacji, więc instalacyjne e2e wyłapuje przypadkowy rozrost paczki
|
||||
przed ścieżką publikacji wydania
|
||||
- Jeśli prace nad wydaniem dotknęły planowania CI, manifestów czasu pluginów lub
|
||||
macierzy testów pluginów, wygeneruj ponownie i przejrzyj należące do planera
|
||||
wyniki macierzy `plugin-prerelease-extension-shard` z
|
||||
`.github/workflows/plugin-prerelease.yml` przed zatwierdzeniem, aby notatki wydania nie
|
||||
opisywały przestarzałego układu CI
|
||||
- Gotowość stabilnego wydania macOS obejmuje też powierzchnie aktualizatora:
|
||||
- wydanie GitHub musi ostatecznie zawierać spakowane `.zip`, `.dmg` i `.dSYM.zip`
|
||||
- `appcast.xml` na `main` musi po publikacji wskazywać nowy stabilny zip
|
||||
- spakowana aplikacja musi zachować niedebugowy identyfikator pakietu, niepusty URL kanału Sparkle i `CFBundleVersion` co najmniej równy kanonicznemu minimalnemu numerowi kompilacji Sparkle dla tej wersji wydania
|
||||
- `appcast.xml` na `main` musi wskazywać nowy stabilny zip po publikacji
|
||||
- spakowana aplikacja musi zachować nie-debugowy identyfikator pakietu, niepusty URL
|
||||
kanału Sparkle oraz `CFBundleVersion` równy kanonicznemu minimalnemu progowi kompilacji Sparkle
|
||||
dla tej wersji wydania albo wyższy
|
||||
|
||||
## Testboxy wydania
|
||||
## Środowiska testowe wydania
|
||||
|
||||
`Full Release Validation` to sposób, w jaki operatorzy uruchamiają wszystkie testy przedwydaniowe z jednego punktu wejścia. Aby uzyskać dowód przypiętego commita na szybko zmieniającej się gałęzi, użyj helpera, aby każdy przepływ potomny działał z gałęzi tymczasowej przypiętej do docelowego SHA:
|
||||
`Full Release Validation` to sposób, w jaki operatorzy uruchamiają wszystkie testy przedwydaniowe z
|
||||
jednego punktu wejścia. Aby uzyskać dowód przypiętego commita na szybko zmieniającej się gałęzi, użyj
|
||||
helpera, aby każdy podrzędny przepływ pracy działał z tymczasowej gałęzi ustalonej na docelowym
|
||||
SHA:
|
||||
|
||||
```bash
|
||||
pnpm ci:full-release --sha <full-sha>
|
||||
```
|
||||
|
||||
Helper wypycha `release-ci/<sha>-...`, wywołuje `Full Release Validation` z tej gałęzi z `ref=<sha>`, weryfikuje, że każdy `headSha` przepływu potomnego odpowiada celowi, a następnie usuwa gałąź tymczasową. Pozwala to uniknąć przypadkowego potwierdzenia nowszego uruchomienia potomnego z `main`.
|
||||
Helper wypycha `release-ci/<sha>-...`, uruchamia `Full Release Validation`
|
||||
z tej gałęzi z `ref=<sha>`, weryfikuje, że każdy podrzędny przepływ pracy `headSha`
|
||||
pasuje do celu, a następnie usuwa tymczasową gałąź. Zapobiega to przypadkowemu potwierdzeniu
|
||||
nowszego uruchomienia podrzędnego `main`.
|
||||
|
||||
Dla walidacji gałęzi wydania albo taga uruchom go z zaufanej referencji przepływu `main` i przekaż gałąź wydania albo tag jako `ref`:
|
||||
W przypadku walidacji gałęzi wydania lub tagu uruchom ją z zaufanej referencji przepływu pracy `main`
|
||||
i przekaż gałąź wydania lub tag jako `ref`:
|
||||
|
||||
```bash
|
||||
gh workflow run full-release-validation.yml \
|
||||
@ -183,58 +300,52 @@ gh workflow run full-release-validation.yml \
|
||||
-f evidence_package_spec=openclaw@YYYY.M.D-beta.N
|
||||
```
|
||||
|
||||
Workflow rozwiązuje docelowy ref, uruchamia ręcznie `CI` z
|
||||
Workflow rozwiązuje docelowy ref, uruchamia ręczne `CI` z
|
||||
`target_ref=<release-ref>`, uruchamia `OpenClaw Release Checks`, przygotowuje
|
||||
nadrzędny artefakt `release-package-under-test` dla kontroli dotyczących pakietu
|
||||
oraz uruchamia samodzielne pakietowe Telegram E2E, gdy `release_profile=full` z
|
||||
nadrzędny artefakt `release-package-under-test` dla testów pakietowych oraz
|
||||
uruchamia samodzielne pakietowe Telegram E2E, gdy `release_profile=full` z
|
||||
`rerun_group=all` albo gdy ustawiono `npm_telegram_package_spec`. Następnie
|
||||
`OpenClaw Release Checks` rozgałęzia się na install smoke, międzyplatformowe
|
||||
kontrole wydania, pokrycie ścieżki wydania live/E2E Docker, gdy soak jest
|
||||
włączony, Package Acceptance z Telegram package QA, parytet QA Lab, live Matrix
|
||||
i live Telegram. Pełne uruchomienie jest akceptowalne tylko wtedy, gdy
|
||||
`OpenClaw Release Checks` rozdziela pracę na testy install smoke, międzyplatformowe
|
||||
testy wydania, pokrycie ścieżki wydania live/E2E Docker, gdy soak jest włączony,
|
||||
Package Acceptance z Telegram package QA, parytet QA Lab, live Matrix i live Telegram. Pełne uruchomienie jest akceptowalne tylko wtedy, gdy
|
||||
podsumowanie `Full Release Validation`
|
||||
pokazuje `normal_ci` i `release_checks` jako zakończone sukcesem. W trybie full/all
|
||||
dziecko `npm_telegram` także musi zakończyć się sukcesem; poza full/all jest
|
||||
pomijane, chyba że podano opublikowane `npm_telegram_package_spec`. Końcowe
|
||||
podsumowanie weryfikatora zawiera tabele najwolniejszych zadań dla każdego
|
||||
uruchomienia potomnego, dzięki czemu menedżer wydania może zobaczyć bieżącą
|
||||
ścieżkę krytyczną bez pobierania logów.
|
||||
Zobacz [pełną walidację wydania](/pl/reference/full-release-validation), aby poznać
|
||||
pełną macierz etapów, dokładne nazwy zadań workflow, różnice między profilami
|
||||
stable i full, artefakty oraz uchwyty ukierunkowanych ponownych uruchomień.
|
||||
Workflow potomne są uruchamiane z zaufanego ref, który uruchamia `Full Release
|
||||
Validation`, zwykle `--ref main`, nawet gdy docelowy `ref` wskazuje na starszą
|
||||
gałąź wydania lub tag. Nie ma osobnego wejścia workflow-ref dla Full Release
|
||||
Validation; wybierz zaufany harness, wybierając ref uruchomienia workflow.
|
||||
pokazuje `normal_ci` i `release_checks` jako zakończone powodzeniem. W trybie full/all
|
||||
proces podrzędny `npm_telegram` również musi zakończyć się powodzeniem; poza trybem full/all jest pomijany,
|
||||
chyba że podano opublikowany `npm_telegram_package_spec`. Końcowe
|
||||
podsumowanie weryfikatora zawiera tabele najwolniejszych zadań dla każdego uruchomienia podrzędnego, dzięki czemu menedżer wydania może zobaczyć obecną ścieżkę krytyczną bez pobierania logów.
|
||||
Zobacz [Pełna walidacja wydania](/pl/reference/full-release-validation), aby uzyskać
|
||||
pełną macierz etapów, dokładne nazwy zadań workflow, różnice między profilami stable i full,
|
||||
artefakty oraz uchwyty do ukierunkowanych ponownych uruchomień.
|
||||
Workflow podrzędne są uruchamiane z zaufanego ref, który uruchamia `Full Release
|
||||
Validation`, zwykle `--ref main`, nawet gdy docelowy `ref` wskazuje
|
||||
starszą gałąź wydania lub tag. Nie ma osobnego wejścia workflow-ref dla Full Release Validation; wybierz zaufany harness przez wybór ref uruchomienia workflow.
|
||||
Nie używaj `--ref main -f ref=<sha>` do dowodu dokładnego commita na ruchomym `main`;
|
||||
surowe SHA commitów nie mogą być refami uruchomienia workflow, więc użyj
|
||||
`pnpm ci:full-release --sha <sha>`, aby utworzyć przypiętą tymczasową gałąź.
|
||||
|
||||
Użyj `release_profile`, aby wybrać zakres live/dostawcy:
|
||||
Użyj `release_profile`, aby wybrać zakres live/provider:
|
||||
|
||||
- `minimum`: najszybsza krytyczna dla wydania ścieżka live OpenAI/core i Docker
|
||||
- `stable`: minimum plus stabilne pokrycie dostawców/backendów do zatwierdzenia wydania
|
||||
- `full`: stable plus szerokie doradcze pokrycie dostawców/mediów
|
||||
- `minimum`: najszybsza krytyczna dla wydania ścieżka OpenAI/core live i Docker
|
||||
- `stable`: minimum plus stabilne pokrycie provider/backend do zatwierdzenia wydania
|
||||
- `full`: stable plus szerokie doradcze pokrycie provider/media
|
||||
|
||||
Użyj `run_release_soak=true` ze `stable`, gdy blokujące wydanie lane'y są
|
||||
zielone i chcesz wykonać wyczerpujący live/E2E, ścieżkę wydania Docker oraz
|
||||
ograniczony przegląd upgrade-survivor opublikowanych pakietów przed promocją.
|
||||
Ten przegląd obejmuje najnowsze cztery stabilne pakiety oraz przypięte
|
||||
bazowe wersje `2026.4.23` i `2026.5.2`, a także starsze pokrycie `2026.4.15`,
|
||||
z usunięciem zduplikowanych baz i podziałem każdej bazy na osobne zadanie
|
||||
runnera Docker. `full` implikuje `run_release_soak=true`.
|
||||
Użyj `run_release_soak=true` ze `stable`, gdy pasma blokujące wydanie są
|
||||
zielone i chcesz przeprowadzić wyczerpujące live/E2E, ścieżkę wydania Docker oraz
|
||||
ograniczony przegląd upgrade-survivor opublikowanych pakietów przed promocją. Ten przegląd obejmuje
|
||||
najnowsze cztery stabilne pakiety oraz przypięte punkty bazowe `2026.4.23` i `2026.5.2`
|
||||
plus starsze pokrycie `2026.4.15`, z usuniętymi duplikatami punktów bazowych i
|
||||
każdym punktem bazowym podzielonym do osobnego zadania runnera Docker. `full` implikuje
|
||||
`run_release_soak=true`.
|
||||
|
||||
`OpenClaw Release Checks` używa zaufanego ref workflow, aby jednorazowo rozwiązać
|
||||
docelowy ref jako `release-package-under-test` i ponownie używa tego artefaktu w
|
||||
kontrolach międzyplatformowych, Package Acceptance oraz kontrolach Docker ścieżki
|
||||
wydania, gdy działa soak. Dzięki temu wszystkie maszyny dotyczące pakietu używają
|
||||
tych samych bajtów i unikają wielokrotnych buildów pakietu. Międzyplatformowy
|
||||
OpenAI install smoke używa `OPENCLAW_CROSS_OS_OPENAI_MODEL`, gdy zmienna
|
||||
repozytorium/organizacji jest ustawiona, w przeciwnym razie `openai/gpt-5.4`,
|
||||
ponieważ ten lane sprawdza instalację pakietu, onboarding, uruchomienie Gateway
|
||||
i jedną turę live agenta, a nie benchmarkuje najwolniejszy model domyślny.
|
||||
Szersza macierz dostawców live pozostaje miejscem dla pokrycia specyficznego dla
|
||||
modelu.
|
||||
`OpenClaw Release Checks` używa zaufanego ref workflow, aby jednorazowo rozwiązać docelowy
|
||||
ref jako `release-package-under-test` i ponownie używa tego artefaktu w testach międzyplatformowych,
|
||||
Package Acceptance oraz testach Docker ścieżki wydania, gdy działa soak. Dzięki temu
|
||||
wszystkie środowiska pakietowe używają tych samych bajtów i unikają powtarzanych buildów pakietów.
|
||||
Międzyplatformowy install smoke OpenAI używa `OPENCLAW_CROSS_OS_OPENAI_MODEL`, gdy
|
||||
ustawiono zmienną repo/org, w przeciwnym razie `openai/gpt-5.4`, ponieważ to pasmo
|
||||
dowodzi instalacji pakietu, onboardingu, uruchomienia gateway i jednego ruchu agenta live,
|
||||
a nie benchmarkuje najwolniejszy domyślny model. Szersza macierz live provider
|
||||
pozostaje miejscem dla pokrycia specyficznego dla modelu.
|
||||
|
||||
Użyj tych wariantów zależnie od etapu wydania:
|
||||
|
||||
@ -266,39 +377,35 @@ gh workflow run full-release-validation.yml \
|
||||
-f npm_telegram_provider_mode=mock-openai
|
||||
```
|
||||
|
||||
Nie używaj pełnego parasola jako pierwszego ponownego uruchomienia po
|
||||
ukierunkowanej poprawce. Jeśli jedna maszyna zawiedzie, użyj nieudanego workflow
|
||||
potomnego, zadania, lane'u Docker, profilu pakietu, dostawcy modelu lub lane'u QA
|
||||
jako kolejnego dowodu. Uruchom pełny parasol ponownie tylko wtedy, gdy poprawka
|
||||
zmieniła współdzieloną orkiestrację wydania albo sprawiła, że wcześniejszy dowód
|
||||
ze wszystkich maszyn stał się nieaktualny. Końcowy weryfikator parasola ponownie
|
||||
sprawdza zapisane identyfikatory uruchomień workflow potomnych, więc po udanym
|
||||
ponownym uruchomieniu workflow potomnego uruchom ponownie tylko nieudane zadanie
|
||||
nadrzędne `Verify full validation`.
|
||||
Nie używaj pełnego parasola jako pierwszego ponownego uruchomienia po ukierunkowanej poprawce. Jeśli jedno środowisko
|
||||
zawiedzie, użyj nieudanego workflow podrzędnego, zadania, pasma Docker, profilu pakietu, providera modelu
|
||||
lub pasma QA do kolejnego dowodu. Uruchom pełny parasol ponownie tylko wtedy,
|
||||
gdy poprawka zmieniła współdzieloną orkiestrację wydania albo sprawiła, że wcześniejsze dowody ze wszystkich środowisk
|
||||
stały się nieaktualne. Końcowy weryfikator parasola ponownie sprawdza zapisane identyfikatory uruchomień workflow
|
||||
podrzędnych, więc po pomyślnym ponownym uruchomieniu workflow podrzędnego uruchom ponownie tylko nieudane
|
||||
nadrzędne zadanie `Verify full validation`.
|
||||
|
||||
Dla ograniczonego odzyskiwania przekaż `rerun_group` do parasola. `all` to
|
||||
rzeczywiste uruchomienie kandydata wydania, `ci` uruchamia tylko normalne dziecko
|
||||
CI, `plugin-prerelease` uruchamia tylko dziecko pluginów wyłącznie dla wydania,
|
||||
`release-checks` uruchamia każdą maszynę wydania, a węższe grupy wydania to
|
||||
`install-smoke`, `cross-os`, `live-e2e`, `package`, `qa`, `qa-parity`, `qa-live`
|
||||
i `npm-telegram`. Ukierunkowane ponowne uruchomienia `npm-telegram` wymagają
|
||||
`npm_telegram_package_spec`; uruchomienia full/all z `release_profile=full`
|
||||
używają artefaktu pakietu z release-checks. Ukierunkowane ponowne uruchomienia
|
||||
cross-OS mogą dodać `cross_os_suite_filter=windows/packaged-upgrade` albo inny
|
||||
filtr OS/zestawu. Niepowodzenia QA release-check są doradcze; awaria tylko QA nie
|
||||
blokuje walidacji wydania.
|
||||
Do ograniczonego odzyskiwania przekaż `rerun_group` do parasola. `all` to rzeczywiste
|
||||
uruchomienie kandydata do wydania, `ci` uruchamia tylko normalny proces podrzędny CI, `plugin-prerelease`
|
||||
uruchamia tylko podrzędny proces plugin przeznaczony wyłącznie dla wydania, `release-checks` uruchamia każde środowisko wydania,
|
||||
a węższe grupy wydania to `install-smoke`, `cross-os`,
|
||||
`live-e2e`, `package`, `qa`, `qa-parity`, `qa-live` i `npm-telegram`.
|
||||
Ukierunkowane ponowne uruchomienia `npm-telegram` wymagają `npm_telegram_package_spec`; pełne/all uruchomienia
|
||||
z `release_profile=full` używają artefaktu pakietu z release-checks. Ukierunkowane
|
||||
ponowne uruchomienia cross-OS mogą dodać `cross_os_suite_filter=windows/packaged-upgrade` lub
|
||||
inny filtr OS/suite. Niepowodzenia QA release-checks są doradcze; niepowodzenie wyłącznie QA
|
||||
nie blokuje walidacji wydania.
|
||||
|
||||
### Vitest
|
||||
|
||||
Maszyna Vitest to ręczny workflow potomny `CI`. Ręczne CI celowo omija
|
||||
zakresowanie zmian i wymusza normalny graf testów dla kandydata wydania: shardy
|
||||
Linux Node, shardy bundled-plugin, kontrakty kanałów, zgodność Node 22, `check`,
|
||||
`check-additional`, build smoke, kontrole dokumentacji, Python skills, Windows,
|
||||
macOS, Android i Control UI i18n.
|
||||
Środowisko Vitest to ręczny podrzędny workflow `CI`. Ręczne CI celowo
|
||||
omija zakres zmian i wymusza normalny graf testów dla kandydata
|
||||
do wydania: shardy Linux Node, shardy bundled-plugin, kontrakty kanałów, zgodność Node 22,
|
||||
`check`, `check-additional`, build smoke, testy dokumentacji, Python
|
||||
skills, Windows, macOS, Android i Control UI i18n.
|
||||
|
||||
Użyj tej maszyny, aby odpowiedzieć: „czy drzewo źródeł przeszło pełny normalny
|
||||
zestaw testów?” To nie jest to samo co produktowa walidacja ścieżki wydania.
|
||||
Dowody do zachowania:
|
||||
Użyj tego środowiska, aby odpowiedzieć: „czy drzewo źródłowe przeszło pełny normalny zestaw testów?”
|
||||
Nie jest to to samo co walidacja produktu na ścieżce wydania. Dowody do zachowania:
|
||||
|
||||
- podsumowanie `Full Release Validation` pokazujące URL uruchomionego `CI`
|
||||
- zielone uruchomienie `CI` na dokładnym docelowym SHA
|
||||
@ -306,8 +413,8 @@ Dowody do zachowania:
|
||||
- artefakty czasów Vitest, takie jak `.artifacts/vitest-shard-timings.json`, gdy
|
||||
uruchomienie wymaga analizy wydajności
|
||||
|
||||
Uruchom ręczne CI bezpośrednio tylko wtedy, gdy wydanie potrzebuje deterministycznego
|
||||
normalnego CI, ale nie maszyn Docker, QA Lab, live, cross-OS ani pakietowych:
|
||||
Uruchamiaj ręczne CI bezpośrednio tylko wtedy, gdy wydanie wymaga deterministycznego normalnego CI, ale
|
||||
nie środowisk Docker, QA Lab, live, cross-OS ani pakietowych:
|
||||
|
||||
```bash
|
||||
gh workflow run ci.yml --ref main -f target_ref=release/YYYY.M.D
|
||||
@ -315,76 +422,70 @@ gh workflow run ci.yml --ref main -f target_ref=release/YYYY.M.D
|
||||
|
||||
### Docker
|
||||
|
||||
Maszyna Docker znajduje się w `OpenClaw Release Checks` przez
|
||||
`openclaw-live-and-e2e-checks-reusable.yml` oraz workflow `install-smoke` w trybie
|
||||
wydania. Waliduje kandydata wydania przez spakowane środowiska Docker, a nie
|
||||
tylko testy na poziomie źródeł.
|
||||
Środowisko Docker znajduje się w `OpenClaw Release Checks` przez
|
||||
`openclaw-live-and-e2e-checks-reusable.yml` oraz workflow `install-smoke`
|
||||
w trybie wydania. Waliduje kandydata do wydania przez pakietowane
|
||||
środowiska Docker zamiast wyłącznie testów na poziomie źródeł.
|
||||
|
||||
Pokrycie Docker wydania obejmuje:
|
||||
|
||||
- pełny install smoke z włączonym wolnym Bun global install smoke
|
||||
- przygotowanie/ponowne użycie obrazu smoke root Dockerfile według docelowego SHA,
|
||||
z zadaniami QR, root/gateway i installer/Bun smoke działającymi jako osobne
|
||||
shardy install-smoke
|
||||
- lane'y E2E repozytorium
|
||||
- chunki Docker ścieżki wydania: `core`, `package-update-openai`,
|
||||
- pełny install smoke z włączonym wolnym globalnym install smoke Bun
|
||||
- przygotowanie/ponowne użycie obrazu smoke głównego Dockerfile według docelowego SHA, z QR,
|
||||
root/gateway oraz zadaniami installer/Bun smoke uruchamianymi jako osobne shardy install-smoke
|
||||
- pasma E2E repozytorium
|
||||
- fragmenty Docker ścieżki wydania: `core`, `package-update-openai`,
|
||||
`package-update-anthropic`, `package-update-core`, `plugins-runtime-plugins`,
|
||||
`plugins-runtime-services`,
|
||||
`plugins-runtime-install-a`, `plugins-runtime-install-b`,
|
||||
`plugins-runtime-install-c`, `plugins-runtime-install-d`,
|
||||
`plugins-runtime-install-e`, `plugins-runtime-install-f`,
|
||||
`plugins-runtime-install-g` i `plugins-runtime-install-h`
|
||||
- pokrycie OpenWebUI w chunku `plugins-runtime-services`, gdy jest wymagane
|
||||
- podzielone lane'y instalacji/odinstalowania bundled pluginów
|
||||
- pokrycie OpenWebUI wewnątrz fragmentu `plugins-runtime-services`, gdy jest wymagane
|
||||
- podzielone pasma instalacji/dezinstalacji bundled plugin
|
||||
`bundled-plugin-install-uninstall-0` do
|
||||
`bundled-plugin-install-uninstall-23`
|
||||
- zestawy dostawców live/E2E i pokrycie modeli live Docker, gdy kontrole wydania
|
||||
obejmują zestawy live
|
||||
- pakiety live/E2E provider i pokrycie modeli live Docker, gdy testy wydania
|
||||
obejmują pakiety live
|
||||
|
||||
Użyj artefaktów Docker przed ponownym uruchamianiem. Harmonogram ścieżki wydania
|
||||
przesyła `.artifacts/docker-tests/` z logami lane'ów, `summary.json`,
|
||||
`failures.json`, czasami faz, JSON planu harmonogramu i poleceniami ponownego
|
||||
uruchomienia. Dla ukierunkowanego odzyskiwania użyj
|
||||
`docker_lanes=<lane[,lane]>` w wielokrotnego użytku workflow live/E2E zamiast
|
||||
ponownie uruchamiać wszystkie chunki wydania. Wygenerowane polecenia ponownego
|
||||
uruchomienia zawierają wcześniejsze `package_artifact_run_id` i przygotowane
|
||||
wejścia obrazów Docker, gdy są dostępne, więc nieudany lane może ponownie użyć
|
||||
tego samego tarballa i obrazów GHCR.
|
||||
Używaj artefaktów Docker przed ponownym uruchamianiem. Harmonogram ścieżki wydania przesyła
|
||||
`.artifacts/docker-tests/` z logami pasm, `summary.json`, `failures.json`,
|
||||
czasami faz, JSON planu harmonogramu i poleceniami ponownego uruchomienia. Do ukierunkowanego odzyskiwania
|
||||
użyj `docker_lanes=<lane[,lane]>` w wielokrotnego użytku workflow live/E2E zamiast
|
||||
ponownie uruchamiać wszystkie fragmenty wydania. Wygenerowane polecenia ponownego uruchomienia zawierają wcześniejsze
|
||||
`package_artifact_run_id` oraz przygotowane wejścia obrazów Docker, gdy są dostępne, więc
|
||||
nieudane pasmo może ponownie użyć tego samego tarballa i obrazów GHCR.
|
||||
|
||||
### QA Lab
|
||||
|
||||
Maszyna QA Lab także jest częścią `OpenClaw Release Checks`. Jest to bramka
|
||||
wydania dla zachowania agentowego i poziomu kanałów, oddzielna od Vitest i
|
||||
mechaniki pakietów Docker.
|
||||
Środowisko QA Lab jest także częścią `OpenClaw Release Checks`. To agentowa
|
||||
bramka wydania na poziomie zachowania i kanałów, osobna od Vitest i mechaniki pakietów Docker.
|
||||
|
||||
Pokrycie QA Lab wydania obejmuje:
|
||||
|
||||
- lane parytetu mock porównujący lane kandydata OpenAI z bazą Opus 4.6 przy użyciu
|
||||
agentowego pakietu parytetu
|
||||
- pasmo parytetu mock porównujące pasmo kandydata OpenAI z punktem bazowym Opus 4.6
|
||||
przy użyciu pakietu agentic parity
|
||||
- szybki profil live Matrix QA używający środowiska `qa-live-shared`
|
||||
- lane live Telegram QA używający dzierżaw poświadczeń Convex CI
|
||||
- pasmo live Telegram QA używające dzierżaw poświadczeń Convex CI
|
||||
- `pnpm qa:otel:smoke`, gdy telemetria wydania wymaga jawnego lokalnego dowodu
|
||||
|
||||
Użyj tej maszyny, aby odpowiedzieć: „czy wydanie zachowuje się poprawnie w
|
||||
scenariuszach QA i przepływach kanałów live?” Zachowaj URL-e artefaktów dla lane'ów
|
||||
parytetu, Matrix i Telegram podczas zatwierdzania wydania. Pełne pokrycie Matrix
|
||||
pozostaje dostępne jako ręczne shardowane uruchomienie QA-Lab, a nie domyślny
|
||||
lane krytyczny dla wydania.
|
||||
Użyj tego środowiska, aby odpowiedzieć: „czy wydanie zachowuje się poprawnie w scenariuszach QA i przepływach kanałów live?”
|
||||
Zachowaj URL-e artefaktów dla pasm parytetu, Matrix i Telegram podczas zatwierdzania wydania. Pełne pokrycie Matrix pozostaje dostępne jako
|
||||
ręczne shardowane uruchomienie QA-Lab, a nie domyślne pasmo krytyczne dla wydania.
|
||||
|
||||
### Package
|
||||
### Pakiet
|
||||
|
||||
Maszyna Package jest bramką instalowalnego produktu. Jest wspierana przez
|
||||
Środowisko pakietowe jest bramką produktu instalowalnego. Jest wspierane przez
|
||||
`Package Acceptance` i resolver
|
||||
`scripts/resolve-openclaw-package-candidate.mjs`. Resolver normalizuje kandydata
|
||||
do tarballa `package-under-test` używanego przez Docker E2E, waliduje inwentarz
|
||||
pakietu, zapisuje wersję pakietu i SHA-256 oraz utrzymuje ref harnessu workflow
|
||||
oddzielnie od ref źródła pakietu.
|
||||
`scripts/resolve-openclaw-package-candidate.mjs`. Resolver normalizuje
|
||||
kandydata do tarballa `package-under-test` używanego przez Docker E2E, waliduje
|
||||
inwentarz pakietu, zapisuje wersję pakietu i SHA-256 oraz utrzymuje
|
||||
ref harnessu workflow oddzielnie od ref źródła pakietu.
|
||||
|
||||
Obsługiwane źródła kandydata:
|
||||
Obsługiwane źródła kandydatów:
|
||||
|
||||
- `source=npm`: `openclaw@beta`, `openclaw@latest` albo dokładna wersja wydania OpenClaw
|
||||
- `source=ref`: spakuj zaufaną gałąź `package_ref`, tag albo pełny SHA commita
|
||||
z wybranym harnessem `workflow_ref`
|
||||
- `source=npm`: `openclaw@beta`, `openclaw@latest` lub dokładna wersja wydania OpenClaw
|
||||
- `source=ref`: spakuj zaufaną gałąź `package_ref`, tag lub pełny SHA commita
|
||||
z wybranym harmessem `workflow_ref`
|
||||
- `source=url`: pobierz HTTPS `.tgz` z wymaganym `package_sha256`
|
||||
- `source=artifact`: użyj ponownie `.tgz` przesłanego przez inne uruchomienie GitHub Actions
|
||||
|
||||
@ -392,41 +493,41 @@ Obsługiwane źródła kandydata:
|
||||
przygotowanym artefaktem pakietu wydania, `suite_profile=custom`,
|
||||
`docker_lanes=doctor-switch update-channel-switch upgrade-survivor published-upgrade-survivor update-restart-auth plugins-offline plugin-update`,
|
||||
`telegram_mode=mock-openai`. Package Acceptance utrzymuje migrację, aktualizację,
|
||||
restart po aktualizacji skonfigurowanego uwierzytelnienia, czyszczenie przestarzałych
|
||||
zależności pluginów, offline fixtures pluginów, aktualizację pluginów i Telegram
|
||||
package QA względem tego samego rozwiązanego tarballa. Blokujące kontrole wydania
|
||||
używają domyślnej bazy najnowszego opublikowanego pakietu; `run_release_soak=true`
|
||||
lub `release_profile=full` rozszerza to do każdego stabilnego bazowego pakietu
|
||||
opublikowanego w npm od `2026.4.23` do `latest` plus fixtures zgłoszonych
|
||||
problemów. Użyj Package Acceptance z `source=npm` dla już wydanego kandydata albo
|
||||
restart aktualizacji skonfigurowanego uwierzytelniania, czyszczenie nieaktualnych zależności plugin, offline’owe
|
||||
fixtures plugin, aktualizację plugin oraz Telegram package QA względem tego samego rozwiązanego
|
||||
tarballa. Blokujące testy wydania używają domyślnego najnowszego opublikowanego
|
||||
punktu bazowego pakietu; `run_release_soak=true` lub
|
||||
`release_profile=full` rozszerza zakres na każdy stabilny punkt bazowy opublikowany w npm od
|
||||
`2026.4.23` do `latest` plus fixtures zgłoszonych problemów. Użyj
|
||||
Package Acceptance z `source=npm` dla już wydanego kandydata albo
|
||||
`source=ref`/`source=artifact` dla lokalnego tarballa npm opartego na SHA przed
|
||||
publikacją. Jest to natywny dla GitHub zamiennik większości pokrycia pakietu/
|
||||
aktualizacji, które wcześniej wymagało Parallels. Międzyplatformowe kontrole
|
||||
wydania nadal mają znaczenie dla onboardingu, instalatora i zachowania platformy
|
||||
specyficznych dla OS, ale produktowa walidacja pakietu/aktualizacji powinna
|
||||
publikacją. To natywne dla GitHub
|
||||
zastępstwo dla większości pokrycia pakietów/aktualizacji, które wcześniej wymagało
|
||||
Parallels. Międzyplatformowe testy wydania nadal mają znaczenie dla onboardingu,
|
||||
instalatora i zachowania platformy specyficznego dla OS, ale walidacja produktu pakietu/aktualizacji powinna
|
||||
preferować Package Acceptance.
|
||||
|
||||
Kanoniczna lista kontrolna dla walidacji aktualizacji i pluginów to
|
||||
[Testowanie aktualizacji i pluginów](/pl/help/testing-updates-plugins). Użyj jej
|
||||
przy decydowaniu, który lokalny lane, Docker, Package Acceptance albo release-check
|
||||
dowodzi instalacji/aktualizacji pluginu, czyszczenia doctor albo zmiany migracji
|
||||
opublikowanego pakietu. Wyczerpująca migracja opublikowanych aktualizacji z każdego
|
||||
stabilnego pakietu `2026.4.23+` jest osobnym ręcznym workflow `Update Migration`,
|
||||
a nie częścią Full Release CI.
|
||||
Kanoniczna lista kontrolna walidacji aktualizacji i plugin to
|
||||
[Testowanie aktualizacji i plugin](/pl/help/testing-updates-plugins). Użyj jej podczas
|
||||
decydowania, które lokalne pasmo, Docker, Package Acceptance lub release-checks dowodzi
|
||||
instalacji/aktualizacji plugin, czyszczenia doctor albo zmiany migracji opublikowanego pakietu.
|
||||
Wyczerpująca migracja aktualizacji opublikowanych z każdego stabilnego pakietu `2026.4.23+` jest
|
||||
osobnym ręcznym workflow `Update Migration`, a nie częścią Full Release CI.
|
||||
|
||||
Dotychczasowa pobłażliwość package-acceptance jest celowo ograniczona czasowo. Pakiety do
|
||||
`2026.4.25` włącznie mogą używać ścieżki zgodności dla luk w metadanych już opublikowanych
|
||||
Dawne złagodzenia Package Acceptance są celowo ograniczone czasowo. Pakiety do
|
||||
`2026.4.25` mogą używać ścieżki zgodności dla luk w metadanych już opublikowanych
|
||||
w npm: prywatnych wpisów inwentarza QA brakujących w archiwum tarball, brakującego
|
||||
`gateway install --wrapper`, brakujących plików poprawek w gitowym fixture pochodzącym
|
||||
z archiwum tarball, brakującego utrwalonego `update.channel`, starszych lokalizacji
|
||||
rekordów instalacji pluginów, brakującego utrwalania rekordów instalacji z marketplace
|
||||
oraz migracji metadanych konfiguracji podczas `plugins update`. Opublikowany pakiet
|
||||
`2026.4.26` może ostrzegać o lokalnych plikach znaczników metadanych kompilacji, które
|
||||
zostały już wydane. Późniejsze pakiety muszą spełniać współczesne kontrakty pakietów;
|
||||
te same luki powodują niepowodzenie walidacji wydania.
|
||||
`gateway install --wrapper`, brakujących plików poprawek w fixture git
|
||||
pochodzącym z archiwum tarball, brakującego utrwalonego `update.channel`, dawnych
|
||||
lokalizacji rekordu instalacji pluginu, brakującego utrwalania rekordu instalacji
|
||||
z marketplace oraz migracji metadanych konfiguracji podczas `plugins update`.
|
||||
Opublikowany pakiet `2026.4.26` może ostrzegać o plikach znaczników metadanych
|
||||
lokalnej kompilacji, które zostały już wydane. Późniejsze pakiety muszą spełniać
|
||||
współczesne kontrakty pakietów; te same luki powodują niepowodzenie walidacji
|
||||
wydania.
|
||||
|
||||
Używaj szerszych profili Package Acceptance, gdy pytanie o wydanie dotyczy
|
||||
rzeczywistego pakietu możliwego do zainstalowania:
|
||||
rzeczywistego pakietu nadającego się do instalacji:
|
||||
|
||||
```bash
|
||||
gh workflow run package-acceptance.yml \
|
||||
@ -440,32 +541,32 @@ gh workflow run package-acceptance.yml \
|
||||
|
||||
Typowe profile pakietów:
|
||||
|
||||
- `smoke`: szybkie ścieżki instalacji pakietu/kanału/agenta, sieci Gateway i
|
||||
przeładowania konfiguracji
|
||||
- `package`: kontrakty instalacji/aktualizacji/restartu/pakietu pluginu bez działającego
|
||||
ClawHub; to domyślny profil sprawdzania wydania
|
||||
- `product`: `package` plus kanały MCP, czyszczenie cron/subagent, wyszukiwanie w sieci
|
||||
OpenAI i OpenWebUI
|
||||
- `smoke`: szybkie ścieżki instalacji pakietu/kanału/agenta, sieci Gateway oraz
|
||||
ponownego wczytania konfiguracji
|
||||
- `package`: kontrakty instalacji/aktualizacji/restartu/pakietu pluginu bez
|
||||
aktywnego ClawHub; to domyślna wartość sprawdzania wydania
|
||||
- `product`: `package` oraz kanały MCP, czyszczenie cron/subagent, wyszukiwanie
|
||||
webowe OpenAI i OpenWebUI
|
||||
- `full`: fragmenty ścieżki wydania Docker z OpenWebUI
|
||||
- `custom`: dokładna lista `docker_lanes` do ukierunkowanych ponownych uruchomień
|
||||
|
||||
Aby uzyskać dowód Telegram dla kandydata pakietu, włącz `telegram_mode=mock-openai` lub
|
||||
`telegram_mode=live-frontier` w Package Acceptance. Workflow przekazuje rozwiązany
|
||||
tarball `package-under-test` do ścieżki Telegram; samodzielny workflow Telegram nadal
|
||||
akceptuje opublikowaną specyfikację npm do kontroli po publikacji.
|
||||
Aby uzyskać dowód Telegram dla kandydata pakietu, włącz `telegram_mode=mock-openai`
|
||||
lub `telegram_mode=live-frontier` w Package Acceptance. Workflow przekazuje
|
||||
rozwiązany tarball `package-under-test` do ścieżki Telegram; samodzielny workflow
|
||||
Telegram nadal akceptuje opublikowaną specyfikację npm do kontroli po publikacji.
|
||||
|
||||
## Automatyzacja publikacji wydania
|
||||
|
||||
`OpenClaw Release Publish` to normalny mutujący punkt wejścia publikacji. Orkiestruje
|
||||
workflow zaufanego publikowania w kolejności wymaganej przez wydanie:
|
||||
`OpenClaw Release Publish` jest normalnym mutującym punktem wejścia publikacji.
|
||||
Koordynuje workflow zaufanego wydawcy w kolejności wymaganej przez wydanie:
|
||||
|
||||
1. Pobiera tag wydania i ustala jego SHA commita.
|
||||
1. Pobiera tag wydania i rozwiązuje jego SHA commitu.
|
||||
2. Weryfikuje, że tag jest osiągalny z `main` lub `release/*`.
|
||||
3. Uruchamia `pnpm plugins:sync:check`.
|
||||
4. Uruchamia `Plugin NPM Release` z `publish_scope=all-publishable` i
|
||||
`ref=<release-sha>`.
|
||||
5. Uruchamia `Plugin ClawHub Release` z tym samym zakresem i SHA.
|
||||
6. Uruchamia `OpenClaw NPM Release` z tagiem wydania, npm dist-tag i
|
||||
6. Uruchamia `OpenClaw NPM Release` z tagiem wydania, tagiem dist npm oraz
|
||||
zapisanym `preflight_run_id`.
|
||||
|
||||
Przykład publikacji beta:
|
||||
@ -478,7 +579,7 @@ gh workflow run openclaw-release-publish.yml \
|
||||
-f npm_dist_tag=beta
|
||||
```
|
||||
|
||||
Stabilna publikacja do domyślnego beta dist-tag:
|
||||
Publikacja stabilna do domyślnego tagu dist beta:
|
||||
|
||||
```bash
|
||||
gh workflow run openclaw-release-publish.yml \
|
||||
@ -488,7 +589,7 @@ gh workflow run openclaw-release-publish.yml \
|
||||
-f npm_dist_tag=beta
|
||||
```
|
||||
|
||||
Stabilne promowanie bezpośrednio do `latest` jest jawne:
|
||||
Stabilna promocja bezpośrednio do `latest` jest jawna:
|
||||
|
||||
```bash
|
||||
gh workflow run openclaw-release-publish.yml \
|
||||
@ -498,96 +599,104 @@ gh workflow run openclaw-release-publish.yml \
|
||||
-f npm_dist_tag=latest
|
||||
```
|
||||
|
||||
Używaj niskopoziomowych workflow `Plugin NPM Release` i `Plugin ClawHub Release`
|
||||
tylko do ukierunkowanych napraw lub ponownych publikacji. Dla wybranej naprawy pluginu
|
||||
przekaż `plugin_publish_scope=selected` i `plugins=@openclaw/name` do
|
||||
`OpenClaw Release Publish` albo uruchom workflow podrzędny bezpośrednio, gdy
|
||||
Używaj niższopoziomowych workflow `Plugin NPM Release` i `Plugin ClawHub Release`
|
||||
tylko do ukierunkowanych napraw lub ponownej publikacji. W przypadku naprawy
|
||||
wybranego pluginu przekaż `plugin_publish_scope=selected` i `plugins=@openclaw/name`
|
||||
do `OpenClaw Release Publish` albo uruchom workflow podrzędny bezpośrednio, gdy
|
||||
pakiet OpenClaw nie może zostać opublikowany.
|
||||
|
||||
## Dane wejściowe workflow NPM
|
||||
|
||||
`OpenClaw NPM Release` akceptuje te dane wejściowe kontrolowane przez operatora:
|
||||
`OpenClaw NPM Release` akceptuje następujące dane wejściowe kontrolowane przez
|
||||
operatora:
|
||||
|
||||
- `tag`: wymagany tag wydania, taki jak `v2026.4.2`, `v2026.4.2-1` lub
|
||||
`v2026.4.2-beta.1`; gdy `preflight_only=true`, może to być także bieżący
|
||||
pełny 40-znakowy SHA commita gałęzi workflow dla preflight wyłącznie walidacyjnego
|
||||
`v2026.4.2-beta.1`; gdy `preflight_only=true`, może to być również bieżący
|
||||
pełny 40-znakowy SHA commitu gałęzi workflow na potrzeby preflight tylko do
|
||||
walidacji
|
||||
- `preflight_only`: `true` tylko dla walidacji/kompilacji/pakietu, `false` dla
|
||||
rzeczywistej ścieżki publikacji
|
||||
- `preflight_run_id`: wymagany w rzeczywistej ścieżce publikacji, aby workflow ponownie użył
|
||||
przygotowanego tarballa z udanego uruchomienia preflight
|
||||
- `preflight_run_id`: wymagane na rzeczywistej ścieżce publikacji, aby workflow
|
||||
ponownie użył przygotowanego tarballa z pomyślnego uruchomienia preflight
|
||||
- `npm_dist_tag`: docelowy tag npm dla ścieżki publikacji; domyślnie `beta`
|
||||
|
||||
`OpenClaw Release Publish` akceptuje te dane wejściowe kontrolowane przez operatora:
|
||||
`OpenClaw Release Publish` akceptuje następujące dane wejściowe kontrolowane przez
|
||||
operatora:
|
||||
|
||||
- `tag`: wymagany tag wydania; musi już istnieć
|
||||
- `preflight_run_id`: identyfikator udanego uruchomienia preflight `OpenClaw NPM Release`;
|
||||
wymagany, gdy `publish_openclaw_npm=true`
|
||||
- `preflight_run_id`: identyfikator pomyślnego uruchomienia preflight
|
||||
`OpenClaw NPM Release`; wymagany, gdy `publish_openclaw_npm=true`
|
||||
- `npm_dist_tag`: docelowy tag npm dla pakietu OpenClaw
|
||||
- `plugin_publish_scope`: domyślnie `all-publishable`; używaj `selected` tylko
|
||||
do ukierunkowanych napraw
|
||||
- `plugins`: rozdzielone przecinkami nazwy pakietów `@openclaw/*`, gdy
|
||||
`plugin_publish_scope=selected`
|
||||
- `publish_openclaw_npm`: domyślnie `true`; ustaw `false` tylko wtedy, gdy używasz
|
||||
workflow jako orkiestratora napraw wyłącznie dla pluginów
|
||||
- `publish_openclaw_npm`: domyślnie `true`; ustaw `false` tylko wtedy, gdy
|
||||
używasz workflow jako orkiestratora napraw wyłącznie dla pluginów
|
||||
|
||||
`OpenClaw Release Checks` akceptuje te dane wejściowe kontrolowane przez operatora:
|
||||
`OpenClaw Release Checks` akceptuje następujące dane wejściowe kontrolowane przez
|
||||
operatora:
|
||||
|
||||
- `ref`: gałąź, tag lub pełny SHA commita do walidacji. Kontrole wymagające sekretów
|
||||
wymagają, aby rozwiązany commit był osiągalny z gałęzi OpenClaw lub
|
||||
- `ref`: gałąź, tag lub pełny SHA commitu do zwalidowania. Kontrole wymagające
|
||||
sekretów wymagają, aby rozwiązany commit był osiągalny z gałęzi OpenClaw lub
|
||||
tagu wydania.
|
||||
- `run_release_soak`: włącza wyczerpujące testy live/E2E, ścieżkę wydania Docker oraz
|
||||
soak wszystkich upgrade-survivor od początku dla stabilnych/domyślnych kontroli wydania.
|
||||
Jest wymuszane przez `release_profile=full`.
|
||||
- `run_release_soak`: włącza wyczerpujące testy live/E2E, ścieżkę wydania Docker
|
||||
oraz soak upgrade-survivor od początku na stabilnych/domyślnych kontrolach
|
||||
wydania. Jest wymuszane przez `release_profile=full`.
|
||||
|
||||
Zasady:
|
||||
Reguły:
|
||||
|
||||
- Tagi stabilne i korygujące mogą być publikowane do `beta` albo `latest`
|
||||
- Tagi prerelease beta mogą być publikowane tylko do `beta`
|
||||
- Dla `OpenClaw NPM Release` pełny SHA commita jako dane wejściowe jest dozwolony tylko wtedy,
|
||||
gdy `preflight_only=true`
|
||||
- `OpenClaw Release Checks` i `Full Release Validation` są zawsze
|
||||
wyłącznie walidacyjne
|
||||
- Rzeczywista ścieżka publikacji musi używać tego samego `npm_dist_tag`, który został użyty podczas preflight;
|
||||
workflow weryfikuje te metadane przed kontynuowaniem publikacji
|
||||
- Tagi stabilne i korekcyjne mogą publikować do `beta` albo `latest`
|
||||
- Tagi przedwydania beta mogą publikować tylko do `beta`
|
||||
- W przypadku `OpenClaw NPM Release` wejście pełnego SHA commitu jest dozwolone
|
||||
tylko wtedy, gdy `preflight_only=true`
|
||||
- `OpenClaw Release Checks` i `Full Release Validation` zawsze są wyłącznie
|
||||
walidacyjne
|
||||
- Rzeczywista ścieżka publikacji musi używać tego samego `npm_dist_tag`, którego
|
||||
użyto podczas preflight; workflow weryfikuje te metadane przed kontynuowaniem
|
||||
publikacji
|
||||
|
||||
## Sekwencja stabilnego wydania npm
|
||||
|
||||
Podczas przygotowywania stabilnego wydania npm:
|
||||
|
||||
1. Uruchom `OpenClaw NPM Release` z `preflight_only=true`
|
||||
- Zanim tag będzie istnieć, możesz użyć bieżącego pełnego SHA commita gałęzi workflow
|
||||
do walidacyjnego dry run workflow preflight
|
||||
2. Wybierz `npm_dist_tag=beta` dla normalnego przepływu najpierw-do-beta albo `latest` tylko
|
||||
wtedy, gdy celowo chcesz bezpośredniej stabilnej publikacji
|
||||
- Zanim tag istnieje, możesz użyć bieżącego pełnego SHA commitu gałęzi
|
||||
workflow do suchego przebiegu workflow preflight tylko do walidacji
|
||||
2. Wybierz `npm_dist_tag=beta` dla zwykłego przepływu beta-first albo `latest`
|
||||
tylko wtedy, gdy celowo chcesz bezpośredniej stabilnej publikacji
|
||||
3. Uruchom `Full Release Validation` na gałęzi wydania, tagu wydania lub pełnym
|
||||
SHA commita, gdy chcesz uzyskać z jednego ręcznego workflow normalne CI oraz pokrycie
|
||||
live prompt cache, Docker, QA Lab, Matrix i Telegram
|
||||
4. Jeśli celowo potrzebujesz tylko deterministycznego normalnego grafu testów, uruchom
|
||||
ręczny workflow `CI` na referencji wydania
|
||||
5. Zapisz udany `preflight_run_id`
|
||||
SHA commitu, gdy chcesz uzyskać zwykłe CI oraz pokrycie aktywnej pamięci
|
||||
podręcznej promptów, Docker, QA Lab, Matrix i Telegram z jednego ręcznego
|
||||
workflow
|
||||
4. Jeśli celowo potrzebujesz tylko deterministycznego zwykłego grafu testów,
|
||||
uruchom ręczny workflow `CI` na refie wydania
|
||||
5. Zapisz pomyślny `preflight_run_id`
|
||||
6. Uruchom `OpenClaw Release Publish` z tym samym `tag`, tym samym `npm_dist_tag`
|
||||
i zapisanym `preflight_run_id`; publikuje on zewnętrzne pluginy do npm
|
||||
i ClawHub przed promowaniem pakietu npm OpenClaw
|
||||
oraz zapisanym `preflight_run_id`; publikuje zewnętrzne pluginy do npm i
|
||||
ClawHub przed promowaniem pakietu npm OpenClaw
|
||||
7. Jeśli wydanie trafiło na `beta`, użyj prywatnego workflow
|
||||
`openclaw/releases-private/.github/workflows/openclaw-npm-dist-tags.yml`,
|
||||
aby promować tę stabilną wersję z `beta` do `latest`
|
||||
8. Jeśli wydanie celowo opublikowano bezpośrednio do `latest`, a `beta`
|
||||
powinna natychmiast wskazywać tę samą stabilną kompilację, użyj tego samego prywatnego
|
||||
workflow, aby skierować oba dist-tags na stabilną wersję, albo pozwól, by jego zaplanowana
|
||||
samonaprawiająca synchronizacja przeniosła `beta` później
|
||||
8. Jeśli wydanie zostało celowo opublikowane bezpośrednio do `latest`, a `beta`
|
||||
ma natychmiast wskazywać tę samą stabilną kompilację, użyj tego samego
|
||||
prywatnego workflow, aby skierować oba tagi dist na stabilną wersję, albo
|
||||
pozwól zaplanowanej synchronizacji samonaprawiającej przenieść `beta` później
|
||||
|
||||
Mutacja dist-tag znajduje się w prywatnym repo ze względów bezpieczeństwa, ponieważ nadal
|
||||
wymaga `NPM_TOKEN`, podczas gdy publiczne repo zachowuje publikację wyłącznie przez OIDC.
|
||||
Mutacja tagu dist znajduje się w prywatnym repo ze względów bezpieczeństwa,
|
||||
ponieważ nadal wymaga `NPM_TOKEN`, podczas gdy publiczne repo zachowuje publikację
|
||||
wyłącznie przez OIDC.
|
||||
|
||||
Dzięki temu zarówno bezpośrednia ścieżka publikacji, jak i ścieżka promowania najpierw-do-beta
|
||||
pozostają udokumentowane i widoczne dla operatora.
|
||||
Dzięki temu zarówno bezpośrednia ścieżka publikacji, jak i ścieżka promocji
|
||||
beta-first są udokumentowane i widoczne dla operatora.
|
||||
|
||||
Jeśli maintainer musi awaryjnie użyć lokalnego uwierzytelniania npm, uruchamiaj wszystkie
|
||||
polecenia 1Password CLI (`op`) wyłącznie w dedykowanej sesji tmux. Nie wywołuj `op`
|
||||
bezpośrednio z głównej powłoki agenta; trzymanie go w tmux sprawia, że monity,
|
||||
alerty i obsługa OTP są obserwowalne oraz zapobiega powtarzającym się alertom hosta.
|
||||
Jeśli maintainer musi awaryjnie użyć lokalnego uwierzytelniania npm, uruchamiaj
|
||||
wszystkie polecenia CLI 1Password (`op`) wyłącznie w dedykowanej sesji tmux. Nie
|
||||
wywołuj `op` bezpośrednio z głównej powłoki agenta; utrzymywanie go w tmux
|
||||
sprawia, że prompty, alerty i obsługa OTP są obserwowalne, oraz zapobiega
|
||||
powtarzającym się alertom hosta.
|
||||
|
||||
## Odnośniki publiczne
|
||||
## Referencje publiczne
|
||||
|
||||
- [`.github/workflows/full-release-validation.yml`](https://github.com/openclaw/openclaw/blob/main/.github/workflows/full-release-validation.yml)
|
||||
- [`.github/workflows/package-acceptance.yml`](https://github.com/openclaw/openclaw/blob/main/.github/workflows/package-acceptance.yml)
|
||||
@ -599,7 +708,7 @@ alerty i obsługa OTP są obserwowalne oraz zapobiega powtarzającym się alerto
|
||||
- [`scripts/package-mac-dist.sh`](https://github.com/openclaw/openclaw/blob/main/scripts/package-mac-dist.sh)
|
||||
- [`scripts/make_appcast.sh`](https://github.com/openclaw/openclaw/blob/main/scripts/make_appcast.sh)
|
||||
|
||||
Maintainerzy używają prywatnej dokumentacji wydań w
|
||||
Maintainerzy używają prywatnej dokumentacji wydania w
|
||||
[`openclaw/maintainers/release/README.md`](https://github.com/openclaw/maintainers/blob/main/release/README.md)
|
||||
jako właściwego runbooka.
|
||||
|
||||
|
||||
@ -1,34 +1,29 @@
|
||||
---
|
||||
read_when:
|
||||
- Instalowanie lub konfigurowanie pluginów
|
||||
- Zrozumienie reguł wykrywania i ładowania Pluginów
|
||||
- Zrozumienie reguł wykrywania i ładowania Plugin
|
||||
- Praca z pakietami Plugin zgodnymi z Codex/Claude
|
||||
sidebarTitle: Install and Configure
|
||||
summary: Instaluj, konfiguruj i zarządzaj pluginami OpenClaw
|
||||
summary: Instalowanie, konfigurowanie i zarządzanie Pluginami OpenClaw
|
||||
title: Pluginy
|
||||
x-i18n:
|
||||
generated_at: "2026-05-06T09:34:21Z"
|
||||
generated_at: "2026-05-06T10:05:29Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 0d68ad3cbd040d3f973d219cf273a792f11df382f6c4ccbf80c07acb0d26c658
|
||||
source_hash: ad3000dbd6dd660f4dbab9a25c476e4c4e3fba0a9781ae344ea3cc147598d0b0
|
||||
source_path: tools/plugin.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
Pluginy rozszerzają OpenClaw o nowe możliwości: kanały, dostawców modeli,
|
||||
środowiska agentów, narzędzia, Skills, mowę, transkrypcję w czasie rzeczywistym,
|
||||
głos w czasie rzeczywistym, rozumienie mediów, generowanie obrazów, generowanie
|
||||
wideo, pobieranie z sieci, wyszukiwanie w sieci i nie tylko. Niektóre pluginy są
|
||||
**rdzeniowe** (dostarczane z OpenClaw), inne są **zewnętrzne**. Większość
|
||||
zewnętrznych pluginów jest publikowana i odkrywana przez
|
||||
[ClawHub](/pl/tools/clawhub). Npm pozostaje obsługiwany dla bezpośrednich instalacji
|
||||
oraz dla tymczasowego zestawu pakietów pluginów należących do OpenClaw do czasu
|
||||
zakończenia tej migracji.
|
||||
harnesse agentów, narzędzia, Skills, mowę, transkrypcję w czasie rzeczywistym, głos w czasie rzeczywistym, rozumienie mediów, generowanie obrazów, generowanie wideo, pobieranie z internetu, wyszukiwanie w internecie i więcej. Niektóre pluginy są **core** (dostarczane z OpenClaw), inne
|
||||
są **zewnętrzne**. Większość zewnętrznych pluginów jest publikowana i odkrywana przez
|
||||
[ClawHub](/pl/tools/clawhub). Npm pozostaje obsługiwany dla bezpośrednich instalacji oraz dla
|
||||
tymczasowego zestawu pakietów pluginów należących do OpenClaw, dopóki ta migracja się nie zakończy.
|
||||
|
||||
## Szybki start
|
||||
|
||||
Przykłady instalacji, listowania, odinstalowania, aktualizacji i publikowania do
|
||||
skopiowania i wklejenia znajdziesz w
|
||||
Przykłady instalacji, wyświetlania listy, odinstalowywania, aktualizowania i publikowania do skopiowania i wklejenia znajdziesz w
|
||||
[Zarządzanie pluginami](/pl/plugins/manage-plugins).
|
||||
|
||||
<Steps>
|
||||
@ -65,17 +60,17 @@ skopiowania i wklejenia znajdziesz w
|
||||
openclaw gateway restart
|
||||
```
|
||||
|
||||
Następnie skonfiguruj pod `plugins.entries.\<id\>.config` w pliku konfiguracyjnym.
|
||||
Następnie skonfiguruj w `plugins.entries.\<id\>.config` w pliku konfiguracyjnym.
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Zarządzanie natywne dla czatu">
|
||||
W działającym Gateway polecenia tylko dla właściciela `/plugins enable` i `/plugins disable`
|
||||
wyzwalają moduł przeładowywania konfiguracji Gateway. Gateway przeładowuje
|
||||
powierzchnie runtime pluginów w procesie, a nowe tury agentów odbudowują swoją
|
||||
listę narzędzi z odświeżonego rejestru. `/plugins install` zmienia kod źródłowy
|
||||
pluginu, więc Gateway żąda ponownego uruchomienia zamiast udawać, że bieżący
|
||||
proces może bezpiecznie przeładować już zaimportowane moduły.
|
||||
wyzwalają ponowne ładowanie konfiguracji Gateway. Gateway ponownie ładuje powierzchnie wykonawcze pluginu
|
||||
w procesie, a nowe tury agentów odbudowują swoją listę narzędzi na podstawie
|
||||
odświeżonego rejestru. `/plugins install` zmienia kod źródłowy pluginu, więc
|
||||
Gateway żąda ponownego uruchomienia zamiast udawać, że bieżący proces może
|
||||
bezpiecznie ponownie załadować już zaimportowane moduły.
|
||||
|
||||
</Step>
|
||||
|
||||
@ -87,9 +82,9 @@ skopiowania i wklejenia znajdziesz w
|
||||
openclaw <plugin-command> --help
|
||||
```
|
||||
|
||||
Użyj `--runtime`, gdy musisz potwierdzić zarejestrowane narzędzia, usługi, metody gateway,
|
||||
hooki lub należące do pluginu polecenia CLI. Zwykłe `inspect` jest zimnym
|
||||
sprawdzeniem manifestu/rejestru i celowo unika importowania runtime pluginu.
|
||||
Użyj `--runtime`, gdy musisz potwierdzić zarejestrowane narzędzia, usługi, metody Gateway,
|
||||
hooki lub polecenia CLI należące do pluginu. Zwykłe `inspect` jest zimnym
|
||||
sprawdzeniem manifestu/rejestru i celowo unika importowania środowiska wykonawczego pluginu.
|
||||
|
||||
</Step>
|
||||
</Steps>
|
||||
@ -102,62 +97,61 @@ Jeśli wolisz sterowanie natywne dla czatu, włącz `commands.plugins: true` i u
|
||||
/plugin enable <plugin-id>
|
||||
```
|
||||
|
||||
Ścieżka instalacji używa tego samego resolvera co CLI: lokalna ścieżka/archiwum, jawne
|
||||
Ścieżka instalacji używa tego samego resolwera co CLI: lokalna ścieżka/archiwum, jawne
|
||||
`clawhub:<pkg>`, jawne `npm:<pkg>`, jawne `npm-pack:<path.tgz>`,
|
||||
jawne `git:<repo>` albo goła specyfikacja pakietu przez npm.
|
||||
jawne `git:<repo>` albo niekwalifikowana specyfikacja pakietu przez npm.
|
||||
|
||||
Jeśli konfiguracja jest nieprawidłowa, instalacja zwykle kończy się zamknięciem i wskazuje
|
||||
`openclaw doctor --fix`. Jedynym wyjątkiem odzyskiwania jest wąska ścieżka
|
||||
ponownej instalacji pluginu wbudowanego dla pluginów, które włączają
|
||||
Jeśli konfiguracja jest nieprawidłowa, instalacja zwykle kończy się bezpiecznym niepowodzeniem i kieruje do
|
||||
`openclaw doctor --fix`. Jedynym wyjątkiem odzyskiwania jest wąska ścieżka ponownej instalacji pluginu dostarczanego w pakiecie
|
||||
dla pluginów, które włączają
|
||||
`openclaw.install.allowInvalidConfigRecovery`.
|
||||
Podczas uruchamiania Gateway nieprawidłowa konfiguracja pluginu kończy się zamknięciem,
|
||||
tak jak każda inna nieprawidłowa konfiguracja. Uruchom `openclaw doctor --fix`, aby
|
||||
poddać wadliwą konfigurację pluginu kwarantannie przez wyłączenie tego wpisu pluginu
|
||||
i usunięcie jego nieprawidłowego ładunku konfiguracji; zwykła kopia zapasowa konfiguracji
|
||||
zachowuje poprzednie wartości.
|
||||
Gdy konfiguracja kanału odwołuje się do pluginu, którego nie da się już odkryć, ale ten sam
|
||||
nieaktualny identyfikator pluginu pozostaje w konfiguracji pluginu lub rekordach instalacji,
|
||||
uruchamianie Gateway zapisuje ostrzeżenia i pomija ten kanał zamiast blokować każdy inny kanał.
|
||||
Podczas uruchamiania Gateway nieprawidłowa konfiguracja pluginu kończy się bezpiecznym niepowodzeniem jak każda inna nieprawidłowa
|
||||
konfiguracja. Uruchom `openclaw doctor --fix`, aby poddać złą konfigurację pluginu kwarantannie przez
|
||||
wyłączenie tego wpisu pluginu i usunięcie jego nieprawidłowego ładunku konfiguracji; zwykła
|
||||
kopia zapasowa konfiguracji zachowuje poprzednie wartości.
|
||||
Gdy konfiguracja kanału odwołuje się do pluginu, którego nie można już odkryć, ale ten
|
||||
sam nieaktualny identyfikator pluginu pozostaje w konfiguracji pluginu lub rekordach instalacji, uruchamianie Gateway
|
||||
zapisuje ostrzeżenia i pomija ten kanał zamiast blokować każdy inny kanał.
|
||||
Uruchom `openclaw doctor --fix`, aby usunąć nieaktualne wpisy kanału/pluginu; nieznane
|
||||
klucze kanałów bez dowodów na nieaktualny plugin nadal nie przechodzą walidacji, aby literówki
|
||||
pozostały widoczne.
|
||||
Jeśli ustawiono `plugins.enabled: false`, nieaktualne odwołania do pluginów są traktowane jako bezczynne:
|
||||
klucze kanałów bez dowodów na nieaktualny plugin nadal powodują niepowodzenie walidacji, aby literówki pozostały
|
||||
widoczne.
|
||||
Jeśli ustawiono `plugins.enabled: false`, nieaktualne odwołania do pluginów są traktowane jako bezwładne:
|
||||
uruchamianie Gateway pomija odkrywanie/ładowanie pluginów, a `openclaw doctor` zachowuje
|
||||
wyłączoną konfigurację pluginów zamiast usuwać ją automatycznie. Ponownie włącz pluginy przed
|
||||
uruchomieniem czyszczenia przez doctor, jeśli chcesz usunąć nieaktualne identyfikatory pluginów.
|
||||
wyłączoną konfigurację pluginu zamiast automatycznie ją usuwać. Ponownie włącz pluginy przed
|
||||
uruchomieniem czyszczenia doctor, jeśli chcesz usunąć nieaktualne identyfikatory pluginów.
|
||||
|
||||
Instalacja zależności pluginów odbywa się tylko podczas jawnych przepływów instalacji/aktualizacji
|
||||
albo naprawy przez doctor. Uruchamianie Gateway, przeładowanie konfiguracji i inspekcja runtime
|
||||
nie uruchamiają menedżerów pakietów ani nie naprawiają drzew zależności. Lokalne pluginy muszą
|
||||
mieć już zainstalowane zależności, a pluginy npm, git i ClawHub są instalowane pod zarządzanymi
|
||||
katalogami głównymi pluginów OpenClaw. Zależności npm mogą zostać hoistowane w zarządzanym
|
||||
katalogu głównym npm OpenClaw; instalacja/aktualizacja skanuje ten zarządzany katalog główny
|
||||
przed zaufaniem, a odinstalowanie usuwa pakiety zarządzane przez npm przez npm. Zewnętrzne pluginy
|
||||
Instalacja zależności pluginów odbywa się tylko podczas jawnych przepływów instalacji/aktualizacji lub
|
||||
naprawy doctor. Uruchamianie Gateway, ponowne ładowanie konfiguracji i inspekcja środowiska wykonawczego
|
||||
nie uruchamiają menedżerów pakietów ani nie naprawiają drzew zależności. Lokalne pluginy muszą już
|
||||
mieć zainstalowane swoje zależności, natomiast pluginy npm, git i ClawHub są
|
||||
instalowane w zarządzanych katalogach głównych pluginów OpenClaw. Zależności npm mogą być hoistowane
|
||||
w zarządzanym katalogu głównym npm OpenClaw; instalacja/aktualizacja skanuje ten zarządzany katalog główny przed
|
||||
zaufaniem, a odinstalowanie usuwa pakiety zarządzane przez npm przez npm. Zewnętrzne pluginy
|
||||
i niestandardowe ścieżki ładowania nadal muszą być instalowane przez `openclaw plugins install`.
|
||||
Użyj `openclaw plugins list --json`, aby zobaczyć statyczny `dependencyStatus` dla każdego
|
||||
widocznego pluginu bez importowania kodu runtime ani naprawiania zależności.
|
||||
Użyj `openclaw plugins list --json`, aby zobaczyć statyczne `dependencyStatus` dla każdego
|
||||
widocznego pluginu bez importowania kodu środowiska wykonawczego ani naprawiania zależności.
|
||||
Zobacz [Rozwiązywanie zależności pluginów](/pl/plugins/dependency-resolution), aby poznać
|
||||
cykl życia w czasie instalacji.
|
||||
cykl życia podczas instalacji.
|
||||
|
||||
### Zablokowana własność ścieżki pluginu
|
||||
|
||||
Jeśli diagnostyka pluginów mówi
|
||||
Jeśli diagnostyka pluginu mówi
|
||||
`blocked plugin candidate: suspicious ownership (... uid=1000, expected uid=0 or root)`
|
||||
a po walidacji konfiguracji pojawia się `plugin present but blocked`, OpenClaw znalazł
|
||||
pliki pluginu należące do innego użytkownika Unix niż proces, który je ładuje.
|
||||
Pozostaw konfigurację pluginu na miejscu; napraw własność systemu plików albo uruchom
|
||||
OpenClaw jako ten sam użytkownik, który jest właścicielem katalogu stanu.
|
||||
|
||||
W instalacjach Docker oficjalny obraz działa jako `node` (uid `1000`), więc
|
||||
katalogi konfiguracji i obszaru roboczego OpenClaw montowane z hosta powinny zwykle
|
||||
W przypadku instalacji Docker oficjalny obraz działa jako `node` (uid `1000`), więc
|
||||
montowane z hosta katalogi konfiguracji i przestrzeni roboczej OpenClaw zwykle powinny
|
||||
należeć do uid `1000`:
|
||||
|
||||
```bash
|
||||
sudo chown -R 1000:1000 /path/to/openclaw-config /path/to/openclaw-workspace
|
||||
```
|
||||
|
||||
Jeśli celowo uruchamiasz OpenClaw jako root, napraw zarządzany katalog główny pluginów,
|
||||
przypisując go zamiast tego do root:
|
||||
Jeśli celowo uruchamiasz OpenClaw jako root, napraw zarządzany katalog główny pluginów, aby
|
||||
należał do root:
|
||||
|
||||
```bash
|
||||
sudo chown -R root:root /path/to/openclaw-config/npm
|
||||
@ -167,56 +161,58 @@ Po naprawieniu własności uruchom ponownie `openclaw doctor --fix` albo
|
||||
`openclaw plugins registry --refresh`, aby utrwalony rejestr pluginów odpowiadał
|
||||
naprawionym plikom.
|
||||
|
||||
W instalacjach npm mutowalne selektory, takie jak `latest` albo dist-tag, są rozwiązywane
|
||||
przed instalacją, a następnie przypinane do dokładnie zweryfikowanej wersji w zarządzanym
|
||||
katalogu głównym npm OpenClaw. Po zakończeniu npm OpenClaw weryfikuje, że zainstalowany
|
||||
wpis `package-lock.json` nadal odpowiada rozwiązanej wersji i integralności. Jeśli npm
|
||||
zapisze inne metadane pakietu, instalacja kończy się niepowodzeniem, a zarządzany pakiet
|
||||
jest wycofywany zamiast akceptować inny artefakt pluginu.
|
||||
W przypadku instalacji npm zmienne selektory, takie jak `latest` lub dist-tag, są rozwiązywane
|
||||
przed instalacją, a następnie przypinane do dokładnej zweryfikowanej wersji w zarządzanym
|
||||
katalogu głównym npm OpenClaw. Po zakończeniu działania npm OpenClaw weryfikuje, czy zainstalowany
|
||||
wpis `package-lock.json` nadal odpowiada rozwiązanej wersji i integralności. Jeśli
|
||||
npm zapisze inne metadane pakietu, instalacja kończy się niepowodzeniem, a zarządzany pakiet
|
||||
jest wycofywany zamiast zaakceptowania innego artefaktu pluginu.
|
||||
Zarządzane katalogi główne npm dziedziczą także `overrides` npm na poziomie pakietu OpenClaw, więc
|
||||
przypięcia bezpieczeństwa chroniące spakowanego hosta dotyczą także hoistowanych zewnętrznych
|
||||
zależności pluginów.
|
||||
|
||||
Checkouty źródłowe są obszarami roboczymi pnpm. Jeśli klonujesz OpenClaw, aby pracować
|
||||
nad wbudowanymi pluginami, uruchom `pnpm install`; OpenClaw ładuje wtedy wbudowane pluginy z
|
||||
Checkouty źródłowe są workspace'ami pnpm. Jeśli klonujesz OpenClaw, aby pracować nad dołączonymi
|
||||
pluginami, uruchom `pnpm install`; OpenClaw ładuje wtedy dołączone pluginy z
|
||||
`extensions/<id>`, więc edycje i zależności lokalne dla pakietu są używane bezpośrednio.
|
||||
Zwykłe instalacje w katalogu głównym npm są przeznaczone dla spakowanego OpenClaw, a nie dla
|
||||
developmentu checkoutu źródłowego.
|
||||
Zwykłe instalacje w katalogu głównym npm są przeznaczone dla spakowanego OpenClaw, a nie do
|
||||
programowania w checkoutcie źródłowym.
|
||||
|
||||
## Typy pluginów
|
||||
|
||||
OpenClaw rozpoznaje dwa formaty pluginów:
|
||||
|
||||
| Format | Jak działa | Przykłady |
|
||||
| ---------- | ------------------------------------------------------------------ | ------------------------------------------------------ |
|
||||
| **Natywny** | `openclaw.plugin.json` + moduł runtime; wykonuje się w procesie | Oficjalne pluginy, społecznościowe pakiety npm |
|
||||
| **Bundle** | Układ zgodny z Codex/Claude/Cursor; mapowany na funkcje OpenClaw | `.codex-plugin/`, `.claude-plugin/`, `.cursor-plugin/` |
|
||||
| Format | Jak działa | Przykłady |
|
||||
| ---------- | ----------------------------------------------------------------- | ------------------------------------------------------- |
|
||||
| **Native** | `openclaw.plugin.json` + moduł środowiska wykonawczego; wykonuje się w procesie | Oficjalne pluginy, społecznościowe pakiety npm |
|
||||
| **Bundle** | Układ zgodny z Codex/Claude/Cursor; mapowany na funkcje OpenClaw | `.codex-plugin/`, `.claude-plugin/`, `.cursor-plugin/` |
|
||||
|
||||
Oba pojawiają się pod `openclaw plugins list`. Szczegóły bundle znajdziesz w [Plugin Bundles](/pl/plugins/bundles).
|
||||
Oba pojawiają się w `openclaw plugins list`. Zobacz [Pakiety pluginów](/pl/plugins/bundles), aby poznać szczegóły bundle.
|
||||
|
||||
Jeśli piszesz natywny plugin, zacznij od [Budowanie pluginów](/pl/plugins/building-plugins)
|
||||
Jeśli piszesz plugin native, zacznij od [Budowanie pluginów](/pl/plugins/building-plugins)
|
||||
oraz [Przegląd Plugin SDK](/pl/plugins/sdk-overview).
|
||||
|
||||
## Punkty wejścia pakietu
|
||||
|
||||
Natywne pakiety npm pluginów muszą deklarować `openclaw.extensions` w `package.json`.
|
||||
Pakiety npm pluginów native muszą deklarować `openclaw.extensions` w `package.json`.
|
||||
Każdy wpis musi pozostać wewnątrz katalogu pakietu i rozwiązywać się do czytelnego
|
||||
pliku runtime albo do pliku źródłowego TypeScript z wywnioskowanym zbudowanym odpowiednikiem
|
||||
JavaScript, takim jak `src/index.ts` do `dist/index.js`.
|
||||
Spakowane instalacje muszą dostarczać ten wynik runtime JavaScript. Fallback do źródła
|
||||
TypeScript jest przeznaczony dla checkoutów źródłowych i lokalnych ścieżek developmentu,
|
||||
a nie dla pakietów npm instalowanych w zarządzanym katalogu głównym pluginów OpenClaw.
|
||||
pliku środowiska wykonawczego albo do pliku źródłowego TypeScript z wywnioskowanym zbudowanym odpowiednikiem JavaScript,
|
||||
takim jak `src/index.ts` do `dist/index.js`.
|
||||
Spakowane instalacje muszą dostarczać ten wynik środowiska wykonawczego JavaScript. Awaryjna ścieżka
|
||||
źródła TypeScript jest przeznaczona dla checkoutów źródłowych i lokalnych ścieżek programistycznych, a nie dla
|
||||
pakietów npm zainstalowanych w zarządzanym katalogu głównym pluginów OpenClaw.
|
||||
|
||||
Jeśli ostrzeżenie pakietu zarządzanego mówi, że `requires compiled runtime output for
|
||||
TypeScript entry ...`, pakiet został opublikowany bez plików JavaScript potrzebnych
|
||||
OpenClaw w runtime. To problem pakowania pluginu, a nie lokalnej konfiguracji.
|
||||
Zaktualizuj lub zainstaluj ponownie plugin po tym, jak wydawca ponownie opublikuje
|
||||
skompilowany JavaScript, albo wyłącz/odinstaluj ten plugin do czasu dostępności
|
||||
naprawionego pakietu.
|
||||
TypeScript entry ...`, pakiet został opublikowany bez plików JavaScript
|
||||
potrzebnych OpenClaw w czasie działania. To problem pakowania pluginu, a nie problem lokalnej konfiguracji.
|
||||
Zaktualizuj lub ponownie zainstaluj plugin po ponownym opublikowaniu skompilowanego
|
||||
JavaScript przez wydawcę albo wyłącz/odinstaluj ten plugin, dopóki poprawiony pakiet nie będzie dostępny.
|
||||
|
||||
Użyj `openclaw.runtimeExtensions`, gdy opublikowane pliki runtime nie znajdują się w tych
|
||||
samych ścieżkach co wpisy źródłowe. Gdy `runtimeExtensions` jest obecne, musi zawierać
|
||||
dokładnie jeden wpis dla każdego wpisu `extensions`. Niedopasowane listy powodują
|
||||
niepowodzenie instalacji i odkrywania pluginów zamiast cicho wracać do ścieżek źródłowych.
|
||||
Jeśli publikujesz także `openclaw.setupEntry`, użyj `openclaw.runtimeSetupEntry` dla jego
|
||||
zbudowanego odpowiednika JavaScript; ten plik jest wymagany, gdy zostanie zadeklarowany.
|
||||
Użyj `openclaw.runtimeExtensions`, gdy opublikowane pliki środowiska wykonawczego nie znajdują się pod
|
||||
tymi samymi ścieżkami co wpisy źródłowe. Gdy istnieje, `runtimeExtensions` musi zawierać
|
||||
dokładnie jeden wpis dla każdego wpisu `extensions`. Niedopasowane listy powodują niepowodzenie instalacji i
|
||||
odkrywania pluginów zamiast cichego powrotu do ścieżek źródłowych. Jeśli publikujesz także
|
||||
`openclaw.setupEntry`, użyj `openclaw.runtimeSetupEntry` dla jego zbudowanego
|
||||
odpowiednika JavaScript; ten plik jest wymagany, gdy zostanie zadeklarowany.
|
||||
|
||||
```json
|
||||
{
|
||||
@ -233,16 +229,16 @@ zbudowanego odpowiednika JavaScript; ten plik jest wymagany, gdy zostanie zadekl
|
||||
### Pakiety npm należące do OpenClaw podczas migracji
|
||||
|
||||
ClawHub jest główną ścieżką dystrybucji dla większości pluginów. Bieżące spakowane
|
||||
wydania OpenClaw zawierają już wiele oficjalnych pluginów, więc w normalnych konfiguracjach
|
||||
nie wymagają one osobnych instalacji npm. Dopóki każdy plugin należący do OpenClaw nie
|
||||
przejdzie migracji do ClawHub, OpenClaw nadal dostarcza niektóre pakiety pluginów `@openclaw/*`
|
||||
wydania OpenClaw zawierają już wiele oficjalnych pluginów, więc w normalnych konfiguracjach nie wymagają one
|
||||
oddzielnych instalacji npm. Dopóki każdy plugin należący do OpenClaw nie
|
||||
zmigruje do ClawHub, OpenClaw nadal dostarcza część pakietów pluginów `@openclaw/*`
|
||||
w npm dla starszych/niestandardowych instalacji i bezpośrednich przepływów npm.
|
||||
|
||||
Jeśli npm zgłasza pakiet pluginu `@openclaw/*` jako przestarzały, ta wersja pakietu pochodzi
|
||||
ze starszej zewnętrznej linii pakietów. Użyj wbudowanego pluginu z bieżącego OpenClaw albo
|
||||
lokalnego checkoutu, dopóki nowszy pakiet npm nie zostanie opublikowany.
|
||||
Jeśli npm zgłasza pakiet pluginu `@openclaw/*` jako przestarzały, ta wersja pakietu
|
||||
pochodzi ze starszej zewnętrznej linii pakietów. Użyj pluginu dołączonego do
|
||||
bieżącego OpenClaw albo lokalnego checkoutu, dopóki nowszy pakiet npm nie zostanie opublikowany.
|
||||
|
||||
| Plugin | Pakiet | Dokumentacja |
|
||||
| Plugin | Pakiet | Dokumentacja |
|
||||
| --------------- | -------------------------- | ------------------------------------------ |
|
||||
| BlueBubbles | `@openclaw/bluebubbles` | [BlueBubbles](/pl/channels/bluebubbles) |
|
||||
| Discord | `@openclaw/discord` | [Discord](/pl/channels/discord) |
|
||||
@ -258,7 +254,7 @@ lokalnego checkoutu, dopóki nowszy pakiet npm nie zostanie opublikowany.
|
||||
| Zalo | `@openclaw/zalo` | [Zalo](/pl/channels/zalo) |
|
||||
| Zalo Personal | `@openclaw/zalouser` | [Zalo Personal](/pl/plugins/zalouser) |
|
||||
|
||||
### Rdzeniowe (dostarczane z OpenClaw)
|
||||
### Core (dostarczane z OpenClaw)
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Dostawcy modeli (włączeni domyślnie)">
|
||||
@ -270,11 +266,11 @@ lokalnego checkoutu, dopóki nowszy pakiet npm nie zostanie opublikowany.
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Pluginy pamięci">
|
||||
- `memory-core` - wbudowane wyszukiwanie pamięci (domyślnie przez `plugins.slots.memory`)
|
||||
- `memory-core` - wbudowane wyszukiwanie w pamięci (domyślnie przez `plugins.slots.memory`)
|
||||
- `memory-lancedb` - pamięć długoterminowa oparta na LanceDB z automatycznym przywoływaniem/przechwytywaniem (ustaw `plugins.slots.memory = "memory-lancedb"`)
|
||||
|
||||
Zobacz [Memory LanceDB](/pl/plugins/memory-lancedb), aby skonfigurować embeddingi zgodne z OpenAI,
|
||||
przykłady Ollama, limity przywoływania i rozwiązywanie problemów.
|
||||
Zobacz [Memory LanceDB](/pl/plugins/memory-lancedb), aby uzyskać konfigurację
|
||||
osadzania zgodną z OpenAI, przykłady Ollama, limity przywoływania i rozwiązywanie problemów.
|
||||
|
||||
</Accordion>
|
||||
|
||||
@ -283,13 +279,13 @@ lokalnego checkoutu, dopóki nowszy pakiet npm nie zostanie opublikowany.
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Inne">
|
||||
- `browser` - dołączony Plugin przeglądarki dla narzędzia przeglądarki, CLI `openclaw browser`, metody Gateway `browser.request`, środowiska wykonawczego przeglądarki i domyślnej usługi sterowania przeglądarką (włączony domyślnie; wyłącz przed zastąpieniem)
|
||||
- `browser` - wbudowany Plugin przeglądarki dla narzędzia przeglądarki, CLI `openclaw browser`, metody Gateway `browser.request`, środowiska uruchomieniowego przeglądarki oraz domyślnej usługi sterowania przeglądarką (włączony domyślnie; wyłącz przed zastąpieniem)
|
||||
- `copilot-proxy` - most VS Code Copilot Proxy (domyślnie wyłączony)
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
Szukasz Pluginów zewnętrznych? Zobacz [Pluginy społeczności](/pl/plugins/community).
|
||||
Szukasz Pluginów innych firm? Zobacz [Pluginy społeczności](/pl/plugins/community).
|
||||
|
||||
## Konfiguracja
|
||||
|
||||
@ -310,44 +306,44 @@ Szukasz Pluginów zewnętrznych? Zobacz [Pluginy społeczności](/pl/plugins/com
|
||||
| Pole | Opis |
|
||||
| ------------------ | --------------------------------------------------------- |
|
||||
| `enabled` | Główny przełącznik (domyślnie: `true`) |
|
||||
| `allow` | Lista dozwolonych Pluginów (opcjonalnie) |
|
||||
| `bundledDiscovery` | Tryb wykrywania dołączonych Pluginów (domyślnie `allowlist`) |
|
||||
| `deny` | Lista blokowanych Pluginów (opcjonalnie; blokada ma pierwszeństwo) |
|
||||
| `allow` | Lista dozwolonych Pluginów (opcjonalna) |
|
||||
| `bundledDiscovery` | Tryb wykrywania wbudowanych Pluginów (domyślnie `allowlist`) |
|
||||
| `deny` | Lista zablokowanych Pluginów (opcjonalna; blokada wygrywa) |
|
||||
| `load.paths` | Dodatkowe pliki/katalogi Pluginów |
|
||||
| `slots` | Wyłączne selektory slotów (np. `memory`, `contextEngine`) |
|
||||
| `slots` | Selektory wyłącznych slotów (np. `memory`, `contextEngine`) |
|
||||
| `entries.\<id\>` | Przełączniki i konfiguracja dla poszczególnych Pluginów |
|
||||
|
||||
`plugins.allow` jest wyłączna. Gdy nie jest pusta, tylko wymienione Pluginy mogą się ładować
|
||||
lub udostępniać narzędzia, nawet jeśli `tools.allow` zawiera `"*"` albo konkretną nazwę
|
||||
narzędzia należącego do Pluginu. Jeśli lista dozwolonych narzędzi odwołuje się do narzędzi Pluginów, dodaj identyfikatory
|
||||
Pluginów właścicieli do `plugins.allow` albo usuń `plugins.allow`; `openclaw doctor` ostrzega o takiej
|
||||
postaci konfiguracji.
|
||||
właścicielskich Pluginów do `plugins.allow` albo usuń `plugins.allow`; `openclaw doctor` ostrzega przed
|
||||
taką strukturą.
|
||||
|
||||
`plugins.bundledDiscovery` domyślnie ma wartość `"allowlist"` dla nowych konfiguracji, więc
|
||||
restrykcyjny inwentarz `plugins.allow` blokuje też pominięte dołączone Pluginy dostawców,
|
||||
w tym wykrywanie dostawców wyszukiwania w sieci w czasie wykonywania. Doctor oznacza starsze
|
||||
restrykcyjne konfiguracje list dozwolonych wartością `"compat"` podczas migracji, aby aktualizacje zachowały
|
||||
starsze zachowanie dołączonych dostawców do czasu, aż operator wybierze bardziej restrykcyjny tryb.
|
||||
Pusta wartość `plugins.allow` nadal jest traktowana jako nieustawiona/otwarta.
|
||||
`plugins.bundledDiscovery` ma domyślną wartość `"allowlist"` dla nowych konfiguracji, więc
|
||||
restrykcyjny spis `plugins.allow` blokuje także pominięte wbudowane Pluginy dostawców,
|
||||
w tym wykrywanie dostawców wyszukiwania w sieci w czasie działania. Doctor oznacza starsze
|
||||
restrykcyjne konfiguracje listy dozwolonych wartością `"compat"` podczas migracji, aby aktualizacje zachowały
|
||||
starsze zachowanie wbudowanych dostawców, dopóki operator nie przełączy się na bardziej rygorystyczny tryb.
|
||||
Puste `plugins.allow` nadal jest traktowane jako nieustawione/otwarte.
|
||||
|
||||
Zmiany konfiguracji wykonane przez `/plugins enable` lub `/plugins disable` wyzwalają
|
||||
przeładowanie Pluginów Gateway w procesie. Nowe tury agenta odbudowują listę narzędzi z
|
||||
Zmiany konfiguracji wprowadzone przez `/plugins enable` lub `/plugins disable` wyzwalają
|
||||
przeładowanie Pluginów Gateway w tym samym procesie. Nowe tury agentów odbudowują listę narzędzi z
|
||||
odświeżonego rejestru Pluginów. Operacje zmieniające źródła, takie jak instalacja,
|
||||
aktualizacja i odinstalowanie, nadal restartują proces Gateway, ponieważ już zaimportowanych
|
||||
modułów Pluginów nie da się bezpiecznie zastąpić w miejscu.
|
||||
|
||||
`openclaw plugins list` to lokalny zrzut rejestru/konfiguracji Pluginów. Włączony
|
||||
Plugin oznacza tam, że utrwalony rejestr i bieżąca konfiguracja pozwalają
|
||||
`openclaw plugins list` to lokalny zrzut rejestru/konfiguracji Pluginów. Plugin
|
||||
`enabled` oznacza tam, że utrwalony rejestr i bieżąca konfiguracja pozwalają
|
||||
Pluginowi uczestniczyć. Nie dowodzi to, że już działający zdalny Gateway
|
||||
został przeładowany lub zrestartowany z tym samym kodem Pluginu. W konfiguracjach VPS/kontenerów
|
||||
z procesami opakowującymi wysyłaj restarty lub zapisy wyzwalające przeładowanie do rzeczywistego
|
||||
przeładował się lub zrestartował do tego samego kodu Pluginu. W konfiguracjach VPS/kontenerowych
|
||||
z procesami opakowującymi wysyłaj restarty albo zapisy wyzwalające przeładowanie do faktycznego
|
||||
procesu `openclaw gateway run`, albo użyj `openclaw gateway restart` wobec
|
||||
działającego Gateway, gdy przeładowanie zgłasza błąd.
|
||||
|
||||
<Accordion title="Stany Pluginów: wyłączony vs brakujący vs nieprawidłowy">
|
||||
- **Wyłączony**: Plugin istnieje, ale reguły włączania go wyłączyły. Konfiguracja jest zachowana.
|
||||
- **Brakujący**: konfiguracja odwołuje się do identyfikatora Pluginu, którego wykrywanie nie znalazło.
|
||||
- **Nieprawidłowy**: Plugin istnieje, ale jego konfiguracja nie pasuje do zadeklarowanego schematu. Uruchamianie Gateway pomija tylko ten Plugin; `openclaw doctor --fix` może poddać nieprawidłowy wpis kwarantannie, wyłączając go i usuwając jego ładunek konfiguracji.
|
||||
- **Nieprawidłowy**: Plugin istnieje, ale jego konfiguracja nie pasuje do zadeklarowanego schematu. Uruchamianie Gateway pomija tylko ten Plugin; `openclaw doctor --fix` może odizolować nieprawidłowy wpis, wyłączając go i usuwając jego ładunek konfiguracji.
|
||||
|
||||
</Accordion>
|
||||
|
||||
@ -358,76 +354,76 @@ OpenClaw skanuje Pluginy w tej kolejności (pierwsze dopasowanie wygrywa):
|
||||
<Steps>
|
||||
<Step title="Ścieżki konfiguracji">
|
||||
`plugins.load.paths` - jawne ścieżki plików lub katalogów. Ścieżki wskazujące
|
||||
z powrotem na własne spakowane katalogi dołączonych Pluginów OpenClaw są ignorowane;
|
||||
z powrotem na własne spakowane katalogi wbudowanych Pluginów OpenClaw są ignorowane;
|
||||
uruchom `openclaw doctor --fix`, aby usunąć te nieaktualne aliasy.
|
||||
</Step>
|
||||
|
||||
<Step title="Pluginy obszaru roboczego">
|
||||
`\<workspace\>/.openclaw/<plugin-root>/*.ts` i `\<workspace\>/.openclaw/<plugin-root>/*/index.ts`.
|
||||
`\<workspace\>/.openclaw/<plugin-root>/*.ts` oraz `\<workspace\>/.openclaw/<plugin-root>/*/index.ts`.
|
||||
</Step>
|
||||
|
||||
<Step title="Globalne Pluginy">
|
||||
`~/.openclaw/<plugin-root>/*.ts` i `~/.openclaw/<plugin-root>/*/index.ts`.
|
||||
<Step title="Pluginy globalne">
|
||||
`~/.openclaw/<plugin-root>/*.ts` oraz `~/.openclaw/<plugin-root>/*/index.ts`.
|
||||
</Step>
|
||||
|
||||
<Step title="Dołączone Pluginy">
|
||||
<Step title="Wbudowane Pluginy">
|
||||
Dostarczane z OpenClaw. Wiele jest włączonych domyślnie (dostawcy modeli, mowa).
|
||||
Inne wymagają jawnego włączenia.
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
Instalacje pakietowe i obrazy Dockera zwykle rozwiązują dołączone Pluginy z
|
||||
skompilowanego drzewa `dist/extensions`. Jeśli katalog źródłowy dołączonego Pluginu jest
|
||||
Instalacje pakietowe i obrazy Docker zwykle rozwiązują wbudowane Pluginy z
|
||||
skompilowanego drzewa `dist/extensions`. Jeśli katalog źródłowy wbudowanego Pluginu jest
|
||||
zamontowany przez bind mount na pasującej spakowanej ścieżce źródłowej, na przykład
|
||||
`/app/extensions/synology-chat`, OpenClaw traktuje ten zamontowany katalog źródłowy
|
||||
jako nakładkę źródeł dołączonych i wykrywa go przed spakowanym pakietem
|
||||
`/app/dist/extensions/synology-chat`. Dzięki temu pętle kontenerowe opiekunów
|
||||
działają bez przełączania każdego dołączonego Pluginu z powrotem na źródła TypeScript.
|
||||
jako nakładkę źródłową wbudowanego Pluginu i wykrywa go przed spakowanym pakietem
|
||||
`/app/dist/extensions/synology-chat`. Dzięki temu kontenerowe pętle maintainerów
|
||||
działają bez przełączania każdego wbudowanego Pluginu z powrotem na źródła TypeScript.
|
||||
Ustaw `OPENCLAW_DISABLE_BUNDLED_SOURCE_OVERLAYS=1`, aby wymusić spakowane pakiety dist
|
||||
nawet wtedy, gdy obecne są montowania nakładek źródeł.
|
||||
nawet wtedy, gdy obecne są montowania nakładek źródłowych.
|
||||
|
||||
### Reguły włączania
|
||||
|
||||
- `plugins.enabled: false` wyłącza wszystkie Pluginy i pomija pracę wykrywania/ładowania Pluginów
|
||||
- `plugins.deny` zawsze ma pierwszeństwo przed allow
|
||||
- `plugins.enabled: false` wyłącza wszystkie Pluginy i pomija wykrywanie/ładowanie Pluginów
|
||||
- `plugins.deny` zawsze wygrywa z listą dozwolonych
|
||||
- `plugins.entries.\<id\>.enabled: false` wyłącza ten Plugin
|
||||
- Pluginy pochodzące z obszaru roboczego są **domyślnie wyłączone** (muszą być jawnie włączone)
|
||||
- Dołączone Pluginy podążają za wbudowanym zestawem domyślnie włączonym, chyba że zostanie nadpisany
|
||||
- Wyłączne sloty mogą wymusić włączenie wybranego Pluginu dla tego slotu
|
||||
- Niektóre dołączone Pluginy wymagające zgody są włączane automatycznie, gdy konfiguracja wskazuje
|
||||
powierzchnię należącą do Pluginu, taką jak referencja modelu dostawcy, konfiguracja kanału lub środowisko wykonawcze harness
|
||||
- Nieaktualna konfiguracja Pluginu jest zachowywana, gdy aktywne jest `plugins.enabled: false`;
|
||||
ponownie włącz Pluginy przed uruchomieniem czyszczenia doctor, jeśli chcesz usunąć nieaktualne identyfikatory
|
||||
- Wbudowane Pluginy korzystają z wbudowanego zestawu domyślnie włączonych, chyba że zostanie to nadpisane
|
||||
- Wyłączne sloty mogą wymusić włączenie wybranego Pluginu dla danego slotu
|
||||
- Niektóre wbudowane Pluginy opt-in są włączane automatycznie, gdy konfiguracja wskazuje
|
||||
powierzchnię należącą do Pluginu, taką jak referencja modelu dostawcy, konfiguracja kanału lub środowisko uruchomieniowe harnessu
|
||||
- Nieaktualna konfiguracja Pluginu jest zachowywana, gdy `plugins.enabled: false` jest aktywne;
|
||||
włącz ponownie Pluginy przed uruchomieniem czyszczenia przez doctor, jeśli chcesz usunąć nieaktualne identyfikatory
|
||||
- Trasy Codex z rodziny OpenAI zachowują oddzielne granice Pluginów:
|
||||
`openai-codex/*` należy do Pluginu OpenAI, natomiast dołączony Plugin serwera aplikacji Codex
|
||||
`openai-codex/*` należy do Pluginu OpenAI, natomiast wbudowany Plugin serwera aplikacji Codex
|
||||
jest wybierany przez `agentRuntime.id: "codex"` albo starsze referencje modeli
|
||||
`codex/*`
|
||||
|
||||
## Rozwiązywanie problemów z hookami czasu wykonywania
|
||||
## Rozwiązywanie problemów z hakami środowiska uruchomieniowego
|
||||
|
||||
Jeśli Plugin pojawia się w `plugins list`, ale efekty uboczne lub hooki `register(api)`
|
||||
nie działają w ruchu czatu na żywo, najpierw sprawdź te elementy:
|
||||
Jeśli Plugin pojawia się w `plugins list`, ale efekty uboczne lub haki `register(api)`
|
||||
nie działają w ruchu czatu na żywo, najpierw sprawdź:
|
||||
|
||||
- Uruchom `openclaw gateway status --deep --require-rpc` i potwierdź, że aktywne
|
||||
- Uruchom `openclaw gateway status --deep --require-rpc` i potwierdź, że aktywny
|
||||
URL Gateway, profil, ścieżka konfiguracji i proces są tymi, które edytujesz.
|
||||
- Zrestartuj działający Gateway po zmianach instalacji/konfiguracji/kodu Pluginu. W kontenerach
|
||||
opakowujących PID 1 może być tylko supervisorem; zrestartuj lub zasygnalizuj proces potomny
|
||||
opakowujących PID 1 może być tylko supervisorem; zrestartuj albo wyślij sygnał do procesu potomnego
|
||||
`openclaw gateway run`.
|
||||
- Użyj `openclaw plugins inspect <id> --runtime --json`, aby potwierdzić rejestracje hooków i
|
||||
diagnostykę. Hooki rozmów spoza dołączonych Pluginów, takie jak `llm_input`,
|
||||
- Użyj `openclaw plugins inspect <id> --runtime --json`, aby potwierdzić rejestracje haków i
|
||||
diagnostykę. Haki rozmów niewbudowanych Pluginów, takie jak `llm_input`,
|
||||
`llm_output`, `before_agent_finalize` i `agent_end`, wymagają
|
||||
`plugins.entries.<id>.hooks.allowConversationAccess=true`.
|
||||
- Do przełączania modeli preferuj `before_model_resolve`. Działa przed rozwiązywaniem modelu
|
||||
dla tur agenta; `llm_output` działa dopiero po tym, jak próba modelu
|
||||
wygeneruje wyjście asystenta.
|
||||
- Aby uzyskać dowód efektywnego modelu sesji, użyj `openclaw sessions` lub
|
||||
- Przy przełączaniu modelu preferuj `before_model_resolve`. Działa przed rozstrzyganiem modelu
|
||||
dla tur agentów; `llm_output` działa dopiero po tym, jak próba modelu
|
||||
wytworzy wyjście asystenta.
|
||||
- Aby udowodnić efektywny model sesji, użyj `openclaw sessions` albo
|
||||
powierzchni sesji/statusu Gateway, a podczas debugowania ładunków dostawcy uruchom
|
||||
Gateway z `--raw-stream --raw-stream-path <path>`.
|
||||
|
||||
### Wolna konfiguracja narzędzi Pluginów
|
||||
### Powolne przygotowywanie narzędzi Pluginu
|
||||
|
||||
Jeśli tury agenta wydają się zatrzymywać podczas przygotowywania narzędzi, włącz logowanie śledzące i
|
||||
sprawdź wiersze czasu działania fabryk narzędzi Pluginów:
|
||||
Jeśli tury agenta wydają się zatrzymywać podczas przygotowywania narzędzi, włącz logowanie trace i
|
||||
sprawdź wiersze czasu fabryk narzędzi Pluginów:
|
||||
|
||||
```bash
|
||||
openclaw config set logging.level trace
|
||||
@ -440,26 +436,26 @@ Szukaj:
|
||||
[trace:plugin-tools] factory timings ...
|
||||
```
|
||||
|
||||
Podsumowanie wymienia łączny czas fabryk i najwolniejsze fabryki narzędzi Pluginów,
|
||||
w tym identyfikator Pluginu, zadeklarowane nazwy narzędzi, kształt wyniku oraz informację, czy narzędzie jest
|
||||
opcjonalne. Wolne wiersze są promowane do ostrzeżeń, gdy pojedyncza fabryka zajmuje
|
||||
co najmniej 1 s albo łączne przygotowanie fabryk narzędzi Pluginów zajmuje co najmniej 5 s.
|
||||
Podsumowanie zawiera łączny czas fabryk i najwolniejsze fabryki narzędzi Pluginów,
|
||||
w tym identyfikator Pluginu, zadeklarowane nazwy narzędzi, kształt wyniku oraz to, czy narzędzie jest
|
||||
opcjonalne. Powolne wiersze są podnoszone do ostrzeżeń, gdy pojedyncza fabryka trwa
|
||||
co najmniej 1 s albo łączny czas przygotowania fabryk narzędzi Pluginów trwa co najmniej 5 s.
|
||||
|
||||
OpenClaw buforuje udane wyniki fabryk narzędzi Pluginów dla powtarzanych rozwiązań
|
||||
OpenClaw buforuje pomyślne wyniki fabryk narzędzi Pluginów dla powtarzanych rozstrzygnięć
|
||||
z tym samym efektywnym kontekstem żądania. Klucz pamięci podręcznej obejmuje efektywną
|
||||
konfigurację czasu wykonywania, obszar roboczy, identyfikatory agenta/sesji, politykę sandboxa, ustawienia przeglądarki,
|
||||
konfigurację środowiska uruchomieniowego, obszar roboczy, identyfikatory agenta/sesji, politykę sandboxa, ustawienia przeglądarki,
|
||||
kontekst dostarczania, tożsamość żądającego i stan własności, więc fabryki, które
|
||||
zależą od tych zaufanych pól, są uruchamiane ponownie, gdy kontekst się zmienia.
|
||||
|
||||
Jeśli jeden Plugin dominuje w czasie działania, sprawdź jego rejestracje czasu wykonywania:
|
||||
Jeśli jeden Plugin dominuje w pomiarach czasu, sprawdź jego rejestracje środowiska uruchomieniowego:
|
||||
|
||||
```bash
|
||||
openclaw plugins inspect <plugin-id> --runtime --json
|
||||
```
|
||||
|
||||
Następnie zaktualizuj, ponownie zainstaluj albo wyłącz ten Plugin. Autorzy Pluginów powinni przenieść
|
||||
kosztowne ładowanie zależności za ścieżkę wykonywania narzędzia zamiast robić to
|
||||
wewnątrz fabryki narzędzi.
|
||||
Następnie zaktualizuj, zainstaluj ponownie albo wyłącz ten Plugin. Autorzy Pluginów powinni przenieść
|
||||
kosztowne ładowanie zależności za ścieżkę wykonywania narzędzia, zamiast robić to
|
||||
wewnątrz fabryki narzędzia.
|
||||
|
||||
### Zduplikowana własność kanału lub narzędzia
|
||||
|
||||
@ -469,9 +465,9 @@ Objawy:
|
||||
- `channel setup already registered: <channel-id> (<plugin-id>)`
|
||||
- `plugin tool name conflict (<plugin-id>): <tool-name>`
|
||||
|
||||
Oznacza to, że więcej niż jeden włączony Plugin próbuje posiadać ten sam kanał,
|
||||
przepływ konfiguracji albo nazwę narzędzia. Najczęstszą przyczyną jest zewnętrzny Plugin kanału
|
||||
zainstalowany obok dołączonego Pluginu, który teraz udostępnia ten sam identyfikator kanału.
|
||||
Oznacza to, że więcej niż jeden włączony Plugin próbuje być właścicielem tego samego kanału,
|
||||
przepływu konfiguracji albo nazwy narzędzia. Najczęstszą przyczyną jest zewnętrzny Plugin kanału
|
||||
zainstalowany obok wbudowanego Pluginu, który teraz zapewnia ten sam identyfikator kanału.
|
||||
|
||||
Kroki debugowania:
|
||||
|
||||
@ -486,17 +482,18 @@ Kroki debugowania:
|
||||
Opcje naprawy:
|
||||
|
||||
- Jeśli jeden Plugin celowo zastępuje inny dla tego samego identyfikatora kanału, preferowany
|
||||
Plugin powinien zadeklarować `channelConfigs.<channel-id>.preferOver` z identyfikatorem Pluginu
|
||||
o niższym priorytecie. Zobacz [/plugins/manifest#replacing-another-channel-plugin](/pl/plugins/manifest#replacing-another-channel-plugin).
|
||||
- Jeśli duplikat jest przypadkowy, wyłącz jedną stronę przez
|
||||
`plugins.entries.<plugin-id>.enabled: false` albo usuń nieaktualną instalację Pluginu.
|
||||
Plugin powinien zadeklarować `channelConfigs.<channel-id>.preferOver` z
|
||||
identyfikatorem Pluginu o niższym priorytecie. Zobacz [/plugins/manifest#replacing-another-channel-plugin](/pl/plugins/manifest#replacing-another-channel-plugin).
|
||||
- Jeśli duplikat jest przypadkowy, wyłącz jedną stronę za pomocą
|
||||
`plugins.entries.<plugin-id>.enabled: false` albo usuń nieaktualną instalację
|
||||
Pluginu.
|
||||
- Jeśli jawnie włączono oba Pluginy, OpenClaw zachowuje to żądanie i
|
||||
zgłasza konflikt. Wybierz jednego właściciela kanału albo zmień nazwy narzędzi należących do Pluginu,
|
||||
aby powierzchnia czasu wykonywania była jednoznaczna.
|
||||
aby powierzchnia środowiska uruchomieniowego była jednoznaczna.
|
||||
|
||||
## Sloty Pluginów (kategorie wyłączne)
|
||||
## Sloty Pluginów (wyłączne kategorie)
|
||||
|
||||
Niektóre kategorie są wyłączne (tylko jedna aktywna naraz):
|
||||
Niektóre kategorie są wyłączne (aktywny może być tylko jeden naraz):
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -509,10 +506,10 @@ Niektóre kategorie są wyłączne (tylko jedna aktywna naraz):
|
||||
}
|
||||
```
|
||||
|
||||
| Slot | Co kontroluje | Domyślnie |
|
||||
| --------------- | ------------------------- | ------------------- |
|
||||
| `memory` | Aktywny Plugin pamięci | `memory-core` |
|
||||
| `contextEngine` | Aktywny silnik kontekstu | `legacy` (wbudowany) |
|
||||
| Slot | Co kontroluje | Domyślnie |
|
||||
| --------------- | ------------------------ | ------------------- |
|
||||
| `memory` | Aktywny Plugin pamięci | `memory-core` |
|
||||
| `contextEngine` | Aktywny silnik kontekstu | `legacy` (wbudowany) |
|
||||
|
||||
## Odwołanie CLI
|
||||
|
||||
@ -562,32 +559,31 @@ openclaw plugins enable <id>
|
||||
openclaw plugins disable <id>
|
||||
```
|
||||
|
||||
Dołączone pluginy są dostarczane razem z OpenClaw. Wiele z nich jest domyślnie włączonych (na przykład dołączeni dostawcy modeli, dołączeni dostawcy mowy oraz dołączony plugin przeglądarki). Inne dołączone pluginy nadal wymagają `openclaw plugins enable <id>`.
|
||||
Dołączone pluginy są dostarczane z OpenClaw. Wiele z nich jest domyślnie włączonych (na przykład dołączone dostawcy modeli, dołączeni dostawcy mowy i dołączony plugin przeglądarki). Inne dołączone pluginy nadal wymagają `openclaw plugins enable <id>`.
|
||||
|
||||
`--force` nadpisuje istniejący zainstalowany plugin lub pakiet hooków w miejscu. Do rutynowych aktualizacji śledzonych pluginów npm używaj `openclaw plugins update <id-or-npm-spec>`. Nie jest to obsługiwane z `--link`, które ponownie używa ścieżki źródłowej zamiast kopiować ją do zarządzanego celu instalacji.
|
||||
`--force` nadpisuje istniejący zainstalowany plugin lub pakiet hooków w miejscu. Użyj `openclaw plugins update <id-or-npm-spec>` do rutynowych aktualizacji śledzonych pluginów npm. Nie jest obsługiwane z `--link`, które ponownie używa ścieżki źródłowej zamiast kopiować do zarządzanego celu instalacji.
|
||||
|
||||
Gdy `plugins.allow` jest już ustawione, `openclaw plugins install` dodaje identyfikator zainstalowanego pluginu do tej listy dozwolonych przed jego włączeniem. Jeśli ten sam identyfikator pluginu znajduje się w `plugins.deny`, instalacja usuwa ten nieaktualny wpis odmowy, aby jawnie zainstalowany plugin można było załadować natychmiast po ponownym uruchomieniu.
|
||||
Gdy `plugins.allow` jest już ustawione, `openclaw plugins install` dodaje identyfikator zainstalowanego pluginu do tej listy dozwolonych przed jego włączeniem. Jeśli ten sam identyfikator pluginu znajduje się w `plugins.deny`, instalacja usuwa ten nieaktualny wpis odmowy, dzięki czemu jawnie zainstalowany plugin można załadować natychmiast po restarcie.
|
||||
|
||||
OpenClaw utrzymuje utrwalony lokalny rejestr pluginów jako model zimnego odczytu dla inwentarza pluginów, własności wkładów i planowania uruchomienia. Przepływy instalacji, aktualizacji, odinstalowania, włączania i wyłączania odświeżają ten rejestr po zmianie stanu pluginu. Ten sam plik `plugins/installs.json` przechowuje trwałe metadane instalacji w najwyższego poziomu `installRecords` oraz odbudowywalne metadane manifestów w `plugins`. Jeśli rejestru brakuje, jest nieaktualny lub nieprawidłowy, `openclaw plugins registry
|
||||
--refresh` odbudowuje jego widok manifestów z rekordów instalacji, polityki konfiguracji oraz metadanych manifestu/pakietu bez ładowania modułów runtime pluginów.
|
||||
`openclaw plugins update <id-or-npm-spec>` dotyczy śledzonych instalacji. Przekazanie specyfikacji pakietu npm z tagiem dystrybucyjnym lub dokładną wersją rozwiązuje nazwę pakietu z powrotem do śledzonego rekordu pluginu i zapisuje nową specyfikację dla przyszłych aktualizacji. Przekazanie nazwy pakietu bez wersji przenosi dokładnie przypiętą instalację z powrotem na domyślną linię wydań rejestru. Jeśli zainstalowany plugin npm już pasuje do rozwiązanej wersji i zapisanej tożsamości artefaktu, OpenClaw pomija aktualizację bez pobierania, ponownej instalacji ani przepisywania konfiguracji.
|
||||
Gdy `openclaw update` działa w kanale beta, rekordy pluginów npm i ClawHub z domyślnej linii najpierw próbują `@beta`, a następnie przechodzą do default/latest, gdy nie istnieje wydanie beta pluginu. Dokładne wersje i jawne tagi pozostają przypięte.
|
||||
OpenClaw utrzymuje trwały lokalny rejestr pluginów jako model zimnego odczytu dla inwentarza pluginów, własności wkładów i planowania uruchamiania. Przepływy instalacji, aktualizacji, odinstalowania, włączania i wyłączania odświeżają ten rejestr po zmianie stanu pluginów. Ten sam plik `plugins/installs.json` przechowuje trwałe metadane instalacji w najwyższego poziomu `installRecords` oraz możliwe do odbudowania metadane manifestów w `plugins`. Jeśli rejestr jest brakujący, nieaktualny lub nieprawidłowy, `openclaw plugins registry --refresh` odbudowuje jego widok manifestów z rekordów instalacji, polityki konfiguracji oraz metadanych manifestu/pakietu bez ładowania modułów wykonawczych pluginów.
|
||||
`openclaw plugins update <id-or-npm-spec>` dotyczy śledzonych instalacji. Przekazanie specyfikacji pakietu npm z dist-tagiem lub dokładną wersją rozwiązuje nazwę pakietu z powrotem do śledzonego rekordu pluginu i zapisuje nową specyfikację dla przyszłych aktualizacji. Przekazanie nazwy pakietu bez wersji przenosi dokładnie przypiętą instalację z powrotem na domyślną linię wydań rejestru. Jeśli zainstalowany plugin npm już odpowiada rozwiązanej wersji i zapisanej tożsamości artefaktu, OpenClaw pomija aktualizację bez pobierania, ponownej instalacji ani przepisywania konfiguracji.
|
||||
Gdy `openclaw update` działa na kanale beta, rekordy pluginów npm i ClawHub z domyślnej linii najpierw próbują `@beta`, a gdy wydanie beta pluginu nie istnieje, wracają do domyślnego/najnowszego. Dokładne wersje i jawne tagi pozostają przypięte.
|
||||
|
||||
`--pin` działa tylko z npm. Nie jest obsługiwane z `--marketplace`, ponieważ instalacje z marketplace utrwalają metadane źródła marketplace zamiast specyfikacji npm.
|
||||
`--pin` jest przeznaczone tylko dla npm. Nie jest obsługiwane z `--marketplace`, ponieważ instalacje z marketplace utrwalają metadane źródła marketplace zamiast specyfikacji npm.
|
||||
|
||||
`--dangerously-force-unsafe-install` to awaryjne obejście dla fałszywych alarmów z wbudowanego skanera niebezpiecznego kodu. Pozwala instalacjom i aktualizacjom pluginów kontynuować mimo wbudowanych ustaleń `critical`, ale nadal nie omija blokad polityki pluginu `before_install` ani blokowania po niepowodzeniu skanowania. Skanowanie instalacji ignoruje typowe pliki i katalogi testowe, takie jak `tests/`, `__tests__/`, `*.test.*` i `*.spec.*`, aby uniknąć blokowania spakowanych mocków testowych; zadeklarowane punkty wejścia runtime pluginu nadal są skanowane, nawet jeśli używają jednej z tych nazw.
|
||||
`--dangerously-force-unsafe-install` to awaryjne obejście dla fałszywych alarmów z wbudowanego skanera niebezpiecznego kodu. Pozwala instalacjom i aktualizacjom pluginów przejść mimo wbudowanych ustaleń `critical`, ale nadal nie omija blokad polityki pluginu `before_install` ani blokowania po niepowodzeniu skanowania. Skanowania instalacyjne ignorują typowe pliki i katalogi testowe, takie jak `tests/`, `__tests__/`, `*.test.*` i `*.spec.*`, aby uniknąć blokowania spakowanych atrap testowych; zadeklarowane punkty wejścia środowiska wykonawczego pluginu nadal są skanowane, nawet jeśli używają jednej z tych nazw.
|
||||
|
||||
Ta flaga CLI dotyczy tylko przepływów instalacji/aktualizacji pluginów. Instalacje zależności Skills obsługiwane przez Gateway używają zamiast tego odpowiadającego nadpisania żądania `dangerouslyForceUnsafeInstall`, podczas gdy `openclaw skills install` pozostaje osobnym przepływem pobierania/instalacji Skills z ClawHub.
|
||||
Ta flaga CLI dotyczy tylko przepływów instalacji/aktualizacji pluginów. Instalacje zależności Skills obsługiwane przez Gateway używają zamiast tego odpowiadającego nadpisania żądania `dangerouslyForceUnsafeInstall`, natomiast `openclaw skills install` pozostaje osobnym przepływem pobierania/instalacji Skills z ClawHub.
|
||||
|
||||
Jeśli plugin opublikowany przez Ciebie w ClawHub jest ukryty lub zablokowany przez skanowanie, otwórz panel ClawHub albo uruchom `clawhub package rescan <name>`, aby poprosić ClawHub o ponowne sprawdzenie. `--dangerously-force-unsafe-install` wpływa tylko na instalacje na Twoim własnym komputerze; nie prosi ClawHub o ponowne przeskanowanie pluginu ani o upublicznienie zablokowanego wydania.
|
||||
Jeśli plugin opublikowany przez Ciebie w ClawHub jest ukryty lub zablokowany przez skanowanie, otwórz panel ClawHub albo uruchom `clawhub package rescan <name>`, aby poprosić ClawHub o ponowne sprawdzenie. `--dangerously-force-unsafe-install` wpływa tylko na instalacje na Twojej własnej maszynie; nie prosi ClawHub o ponowne przeskanowanie pluginu ani o upublicznienie zablokowanego wydania.
|
||||
|
||||
Zgodne pakiety uczestniczą w tym samym przepływie listy/sprawdzania/włączania/wyłączania pluginów. Obecna obsługa runtime obejmuje Skills pakietów, Claude command-skills, domyślne ustawienia Claude `settings.json`, domyślne ustawienia Claude `.lsp.json` i zadeklarowanych w manifeście `lspServers`, Cursor command-skills oraz zgodne katalogi hooków Codex.
|
||||
Zgodne pakiety uczestniczą w tym samym przepływie listy/inspekcji/włączania/wyłączania pluginów. Obecna obsługa środowiska wykonawczego obejmuje Skills pakietów, command-skills Claude, domyślne ustawienia Claude `settings.json`, domyślne ustawienia Claude `.lsp.json` i zadeklarowane w manifeście `lspServers`, command-skills Cursor oraz zgodne katalogi hooków Codex.
|
||||
|
||||
`openclaw plugins inspect <id>` zgłasza także wykryte możliwości pakietu oraz obsługiwane lub nieobsługiwane wpisy serwerów MCP i LSP dla pluginów opartych na pakietach.
|
||||
`openclaw plugins inspect <id>` raportuje także wykryte możliwości pakietu oraz obsługiwane lub nieobsługiwane wpisy serwerów MCP i LSP dla pluginów opartych na pakietach.
|
||||
|
||||
Źródłami marketplace mogą być znana nazwa marketplace Claude z `~/.claude/plugins/known_marketplaces.json`, lokalny katalog główny marketplace lub ścieżka `marketplace.json`, skrót GitHub taki jak `owner/repo`, URL repozytorium GitHub albo URL git. W przypadku zdalnych marketplace wpisy pluginów muszą pozostawać wewnątrz sklonowanego repozytorium marketplace i używać wyłącznie źródeł ścieżek względnych.
|
||||
Źródła marketplace mogą być znaną nazwą marketplace Claude z `~/.claude/plugins/known_marketplaces.json`, lokalnym katalogiem głównym marketplace lub ścieżką `marketplace.json`, skrótem GitHub takim jak `owner/repo`, adresem URL repozytorium GitHub albo adresem URL git. W przypadku zdalnych marketplace wpisy pluginów muszą pozostać wewnątrz sklonowanego repozytorium marketplace i używać wyłącznie względnych źródeł ścieżek.
|
||||
|
||||
Pełne szczegóły znajdziesz w [dokumentacji CLI `openclaw plugins`](/pl/cli/plugins).
|
||||
Zobacz [referencję CLI `openclaw plugins`](/pl/cli/plugins), aby uzyskać pełne szczegóły.
|
||||
|
||||
## Omówienie API pluginów
|
||||
|
||||
@ -611,60 +607,60 @@ export default definePluginEntry({
|
||||
});
|
||||
```
|
||||
|
||||
OpenClaw ładuje obiekt wejściowy i wywołuje `register(api)` podczas aktywacji pluginu. Loader nadal wraca do `activate(api)` dla starszych pluginów, ale dołączone pluginy i nowe zewnętrzne pluginy powinny traktować `register` jako kontrakt publiczny.
|
||||
OpenClaw ładuje obiekt wejściowy i wywołuje `register(api)` podczas aktywacji pluginu. Loader nadal wraca do `activate(api)` dla starszych pluginów, ale dołączone pluginy i nowe pluginy zewnętrzne powinny traktować `register` jako kontrakt publiczny.
|
||||
|
||||
`api.registrationMode` informuje plugin, dlaczego jego punkt wejścia jest ładowany:
|
||||
|
||||
| Tryb | Znaczenie |
|
||||
| --------------- | -------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `full` | Aktywacja runtime. Rejestruj narzędzia, hooki, usługi, polecenia, trasy i inne aktywne efekty uboczne. |
|
||||
| `discovery` | Wykrywanie możliwości tylko do odczytu. Rejestruj dostawców i metadane; zaufany kod wejściowy pluginu może zostać załadowany, ale pomiń aktywne efekty uboczne. |
|
||||
| `setup-only` | Ładowanie metadanych konfiguracji kanału przez lekki punkt wejścia konfiguracji. |
|
||||
| `setup-runtime` | Ładowanie konfiguracji kanału, które wymaga także punktu wejścia runtime. |
|
||||
| `cli-metadata` | Wyłącznie zbieranie metadanych poleceń CLI. |
|
||||
| Tryb | Znaczenie |
|
||||
| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `full` | Aktywacja środowiska wykonawczego. Rejestruje narzędzia, hooki, usługi, polecenia, trasy i inne aktywne efekty uboczne. |
|
||||
| `discovery` | Odkrywanie możliwości tylko do odczytu. Rejestruje dostawców i metadane; zaufany kod punktu wejścia pluginu może się ładować, ale pomija aktywne efekty uboczne. |
|
||||
| `setup-only` | Ładowanie metadanych konfiguracji kanału przez lekki punkt wejścia konfiguracji. |
|
||||
| `setup-runtime` | Ładowanie konfiguracji kanału, które wymaga także punktu wejścia środowiska wykonawczego. |
|
||||
| `cli-metadata` | Tylko zbieranie metadanych poleceń CLI. |
|
||||
|
||||
Punkty wejścia pluginów, które otwierają gniazda, bazy danych, pracowników w tle lub długotrwałych klientów, powinny zabezpieczać te efekty uboczne warunkiem `api.registrationMode === "full"`. Ładowania wykrywania są buforowane oddzielnie od ładowań aktywujących i nie zastępują działającego rejestru Gateway. Wykrywanie nie aktywuje, ale nie jest wolne od importu: OpenClaw może wykonać zaufany punkt wejścia pluginu lub moduł pluginu kanału, aby zbudować snapshot. Utrzymuj najwyższe poziomy modułów lekkie i wolne od efektów ubocznych, a klientów sieciowych, podprocesy, nasłuchiwacze, odczyty poświadczeń i uruchamianie usług przenieś za ścieżki pełnego runtime.
|
||||
Punkty wejścia pluginów, które otwierają gniazda, bazy danych, pracowników w tle lub długotrwałych klientów, powinny chronić te efekty uboczne warunkiem `api.registrationMode === "full"`. Ładowania odkrywania są buforowane oddzielnie od ładowań aktywujących i nie zastępują działającego rejestru Gateway. Odkrywanie nie aktywuje, ale nie jest wolne od importów: OpenClaw może ocenić zaufany punkt wejścia pluginu lub moduł pluginu kanału, aby zbudować migawkę. Utrzymuj najwyższe poziomy modułów jako lekkie i pozbawione efektów ubocznych, a klientów sieciowych, podprocesy, nasłuchiwacze, odczyty poświadczeń i uruchamianie usług przenieś za ścieżki pełnego środowiska wykonawczego.
|
||||
|
||||
Typowe metody rejestracji:
|
||||
|
||||
| Metoda | Co rejestruje |
|
||||
| --------------------------------------- | ---------------------------- |
|
||||
| `registerProvider` | Dostawca modeli (LLM) |
|
||||
| `registerChannel` | Kanał czatu |
|
||||
| `registerTool` | Narzędzie agenta |
|
||||
| `registerHook` / `on(...)` | Hooki cyklu życia |
|
||||
| `registerSpeechProvider` | Text-to-speech / STT |
|
||||
| `registerRealtimeTranscriptionProvider` | Strumieniowe STT |
|
||||
| `registerRealtimeVoiceProvider` | Dwukierunkowy głos realtime |
|
||||
| `registerMediaUnderstandingProvider` | Analiza obrazów/audio |
|
||||
| `registerImageGenerationProvider` | Generowanie obrazów |
|
||||
| `registerMusicGenerationProvider` | Generowanie muzyki |
|
||||
| `registerVideoGenerationProvider` | Generowanie wideo |
|
||||
| `registerWebFetchProvider` | Dostawca web fetch / scrape |
|
||||
| `registerWebSearchProvider` | Wyszukiwanie w sieci |
|
||||
| `registerHttpRoute` | Punkt końcowy HTTP |
|
||||
| `registerCommand` / `registerCli` | Polecenia CLI |
|
||||
| `registerContextEngine` | Silnik kontekstu |
|
||||
| `registerService` | Usługa w tle |
|
||||
| Metoda | Co rejestruje |
|
||||
| --------------------------------------- | ----------------------------------- |
|
||||
| `registerProvider` | Dostawca modeli (LLM) |
|
||||
| `registerChannel` | Kanał czatu |
|
||||
| `registerTool` | Narzędzie agenta |
|
||||
| `registerHook` / `on(...)` | Hooki cyklu życia |
|
||||
| `registerSpeechProvider` | Zamiana tekstu na mowę / STT |
|
||||
| `registerRealtimeTranscriptionProvider` | Strumieniowe STT |
|
||||
| `registerRealtimeVoiceProvider` | Dwukierunkowy głos w czasie rzeczywistym |
|
||||
| `registerMediaUnderstandingProvider` | Analiza obrazów/dźwięku |
|
||||
| `registerImageGenerationProvider` | Generowanie obrazów |
|
||||
| `registerMusicGenerationProvider` | Generowanie muzyki |
|
||||
| `registerVideoGenerationProvider` | Generowanie wideo |
|
||||
| `registerWebFetchProvider` | Dostawca pobierania/scrapowania WWW |
|
||||
| `registerWebSearchProvider` | Wyszukiwanie w sieci |
|
||||
| `registerHttpRoute` | Punkt końcowy HTTP |
|
||||
| `registerCommand` / `registerCli` | Polecenia CLI |
|
||||
| `registerContextEngine` | Silnik kontekstu |
|
||||
| `registerService` | Usługa w tle |
|
||||
|
||||
Zachowanie guardów hooków dla typowanych hooków cyklu życia:
|
||||
Zachowanie strażników hooków dla typowanych hooków cyklu życia:
|
||||
|
||||
- `before_tool_call`: `{ block: true }` jest końcowe; handlery o niższym priorytecie są pomijane.
|
||||
- `before_tool_call`: `{ block: false }` jest no-op i nie usuwa wcześniejszej blokady.
|
||||
- `before_install`: `{ block: true }` jest końcowe; handlery o niższym priorytecie są pomijane.
|
||||
- `before_install`: `{ block: false }` jest no-op i nie usuwa wcześniejszej blokady.
|
||||
- `message_sending`: `{ cancel: true }` jest końcowe; handlery o niższym priorytecie są pomijane.
|
||||
- `message_sending`: `{ cancel: false }` jest no-op i nie usuwa wcześniejszego anulowania.
|
||||
- `before_tool_call`: `{ block: true }` jest końcowe; procedury obsługi o niższym priorytecie są pomijane.
|
||||
- `before_tool_call`: `{ block: false }` jest operacją bez efektu i nie czyści wcześniejszej blokady.
|
||||
- `before_install`: `{ block: true }` jest końcowe; procedury obsługi o niższym priorytecie są pomijane.
|
||||
- `before_install`: `{ block: false }` jest operacją bez efektu i nie czyści wcześniejszej blokady.
|
||||
- `message_sending`: `{ cancel: true }` jest końcowe; procedury obsługi o niższym priorytecie są pomijane.
|
||||
- `message_sending`: `{ cancel: false }` jest operacją bez efektu i nie czyści wcześniejszego anulowania.
|
||||
|
||||
Natywny serwer aplikacji Codex mostkuje natywne zdarzenia narzędzi Codex z powrotem do tej powierzchni hooków. Pluginy mogą blokować natywne narzędzia Codex przez `before_tool_call`, obserwować wyniki przez `after_tool_call` i uczestniczyć w zatwierdzeniach Codex `PermissionRequest`. Mostek nie przepisuje jeszcze argumentów natywnych narzędzi Codex. Dokładna granica obsługi runtime Codex znajduje się w [kontrakcie obsługi Codex harness v1](/pl/plugins/codex-harness#v1-support-contract).
|
||||
Natywny app-server Codex mostkuje natywne zdarzenia narzędzi Codex z powrotem do tej powierzchni hooków. Pluginy mogą blokować natywne narzędzia Codex przez `before_tool_call`, obserwować wyniki przez `after_tool_call` i uczestniczyć w zatwierdzeniach Codex `PermissionRequest`. Mostek nie przepisuje jeszcze argumentów natywnych narzędzi Codex. Dokładna granica obsługi środowiska wykonawczego Codex znajduje się w [kontrakcie obsługi harness Codex v1](/pl/plugins/codex-harness#v1-support-contract).
|
||||
|
||||
Pełne zachowanie typowanych hooków znajdziesz w [omówieniu SDK](/pl/plugins/sdk-overview#hook-decision-semantics).
|
||||
Pełne zachowanie typowanych hooków opisuje [omówienie SDK](/pl/plugins/sdk-overview#hook-decision-semantics).
|
||||
|
||||
## Powiązane
|
||||
|
||||
- [Tworzenie pluginów](/pl/plugins/building-plugins) - utwórz własny plugin
|
||||
- [Pakiety pluginów](/pl/plugins/bundles) - zgodność pakietów Codex/Claude/Cursor
|
||||
- [Manifest pluginu](/pl/plugins/manifest) - schemat manifestu
|
||||
- [Pakiety Plugin](/pl/plugins/bundles) - zgodność pakietów Codex/Claude/Cursor
|
||||
- [Manifest Plugin](/pl/plugins/manifest) - schemat manifestu
|
||||
- [Rejestrowanie narzędzi](/pl/plugins/building-plugins#registering-agent-tools) - dodawanie narzędzi agenta w pluginie
|
||||
- [Wewnętrzna architektura pluginów](/pl/plugins/architecture) - model możliwości i potok ładowania
|
||||
- [Pluginy społeczności](/pl/plugins/community) - listy od firm trzecich
|
||||
- [Mechanizmy wewnętrzne Plugin](/pl/plugins/architecture) - model możliwości i potok ładowania
|
||||
- [Pluginy społeczności](/pl/plugins/community) - listy rozwiązań zewnętrznych
|
||||
|
||||
Loading…
Reference in New Issue
Block a user