Manifest Pluginu

Ta strona opisuje natywny manifest pluginu OpenClaw, openclaw.plugin.json. Informacje o zgodnych układach pakietów (Codex, Claude, Cursor) zawiera sekcja Pakiety pluginów.

Zgodne formaty pakietów używają zamiast niego własnych plików manifestu:

• Pakiet Codex: .codex-plugin/plugin.json
• Pakiet Claude: .claude-plugin/plugin.json lub domyślny układ komponentów Claude bez manifestu
• Pakiet Cursor: .cursor-plugin/plugin.json

OpenClaw automatycznie wykrywa te układy, ale nie weryfikuje ich względem poniższego schematu openclaw.plugin.json. W przypadku zgodnego pakietu OpenClaw odczytuje metadane pakietu, zadeklarowane katalogi główne umiejętności, katalogi główne poleceń Claude, domyślne wartości settings.json Claude, domyślne wartości LSP Claude oraz obsługiwane pakiety hooków, jeśli układ odpowiada wymaganiom środowiska uruchomieniowego OpenClaw.

Każdy natywny plugin OpenClaw musi zawierać openclaw.plugin.json w katalogu głównym pluginu. OpenClaw odczytuje go, aby zweryfikować konfigurację bez wykonywania kodu pluginu. Brakujący lub nieprawidłowy manifest blokuje walidację konfiguracji i jest traktowany jako błąd pluginu.

Pełny przewodnik po systemie pluginów zawiera strona Pluginy, a opis natywnego modelu możliwości i aktualne wytyczne dotyczące zgodności zewnętrznej — strona Model możliwości.

Do czego służy ten plik

openclaw.plugin.json zawiera metadane odczytywane przez OpenClaw przed załadowaniem kodu pluginu. Sprawdzenie wszystkich zawartych w nim danych musi być na tyle tanie, aby nie wymagało uruchamiania środowiska wykonawczego pluginu.

Należy go używać do:

• tożsamości pluginu, walidacji konfiguracji i wskazówek interfejsu konfiguracji
• metadanych uwierzytelniania, wdrażania i konfiguracji (aliasu, automatycznego włączania, zmiennych środowiskowych dostawcy i metod uwierzytelniania)
• wskazówek dotyczących aktywacji dla powierzchni płaszczyzny sterowania
• własności skróconych rodzin modeli
• statycznych migawek własności możliwości (contracts)
• metadanych narzędzia uruchamiającego QA, które może sprawdzać współdzielony host openclaw qa
• metadanych konfiguracji specyficznych dla kanałów, scalanych z katalogiem i powierzchniami walidacji

Nie należy go używać do: rejestrowania zachowania w czasie wykonywania, deklarowania punktów wejścia kodu ani przechowywania metadanych instalacji npm. Należą one do kodu pluginu i pliku package.json.

Minimalny przykład

{  "id": "voice-call",  "configSchema": {    "type": "object",    "additionalProperties": false,    "properties": {}  }}

Rozbudowany przykład

{  "id": "openrouter",  "name": "OpenRouter",  "description": "Plugin dostawcy OpenRouter",  "version": "1.0.0",  "providers": ["openrouter"],  "modelSupport": {    "modelPrefixes": ["router-"]  },  "modelIdNormalization": {    "providers": {      "openrouter": {        "prefixWhenBare": "openrouter"      }    }  },  "providerEndpoints": [    {      "endpointClass": "openrouter",      "hostSuffixes": ["openrouter.ai"]    }  ],  "providerRequest": {    "providers": {      "openrouter": {        "family": "openrouter"      }    }  },  "cliBackends": ["openrouter-cli"],  "syntheticAuthRefs": ["openrouter-cli"],  "setup": {    "providers": [      {        "id": "openrouter",        "envVars": ["OPENROUTER_API_KEY"]      }    ]  },  "providerAuthAliases": {    "openrouter-coding": "openrouter"  },  "channelEnvVars": {    "openrouter-chatops": ["OPENROUTER_CHATOPS_TOKEN"]  },  "providerAuthChoices": [    {      "provider": "openrouter",      "method": "api-key",      "choiceId": "openrouter-api-key",      "choiceLabel": "Klucz API OpenRouter",      "groupId": "openrouter",      "groupLabel": "OpenRouter",      "optionKey": "openrouterApiKey",      "cliFlag": "--openrouter-api-key",      "cliOption": "--openrouter-api-key <key>",      "cliDescription": "Klucz API OpenRouter",      "onboardingScopes": ["text-inference"]    }  ],  "uiHints": {    "apiKey": {      "label": "Klucz API",      "placeholder": "sk-or-v1-...",      "sensitive": true    }  },  "configSchema": {    "type": "object",    "additionalProperties": false,    "properties": {      "apiKey": {        "type": "string"      }    }  }}

Opis pól najwyższego poziomu

dokumentacja pól katalogu

catalog udostępnia opcjonalne wskazówki dotyczące wyświetlania w przeglądarkach pluginów. Hosty mogą je ignorować. Wskazówki te nigdy nie instalują ani nie włączają pluginu oraz nie zmieniają jego działania w czasie wykonywania ani poziomu zaufania.

{  "catalog": {    "featured": true,    "order": 10  }}

Dokumentacja metadanych dostawcy generowania

Pola metadanych dostawcy generowania opisują statyczne sygnały uwierzytelniania dostawców zadeklarowanych na odpowiadającej im liście contracts.*GenerationProviders. OpenClaw odczytuje te pola przed załadowaniem środowiska uruchomieniowego dostawcy, aby podstawowe narzędzia mogły ustalić dostępność dostawcy generowania bez importowania każdego pluginu dostawcy.

Tych pól należy używać wyłącznie do prostych, deklaratywnych faktów. Transport, przekształcenia żądań, odświeżanie tokenów, weryfikacja danych uwierzytelniających i właściwe działanie generowania pozostają w środowisku uruchomieniowym pluginu.

{  "contracts": {    "imageGenerationProviders": ["example-image"]  },  "imageGenerationProviderMetadata": {    "example-image": {      "aliases": ["example-image-oauth"],      "authProviders": ["example-image"],      "configSignals": [        {          "rootPath": "plugins.entries.example-image.config",          "overlayPath": "image",          "mode": {            "path": "mode",            "default": "local",            "allowed": ["local"]          },          "requiredAny": ["workflow", "workflowPath"],          "required": ["promptNodeId"]        }      ],      "authSignals": [        {          "provider": "example-image"        },        {          "provider": "example-image-oauth",          "providerBaseUrl": {            "provider": "example-image",            "defaultBaseUrl": "https://api.example.com/v1",            "allowedBaseUrls": ["https://api.example.com/v1"]          }        }      ]    }  }}

Każdy wpis metadanych obsługuje:

Każdy wpis configSignals obsługuje:

Każdy warunek mode obsługuje:

Każdy wpis authSignals obsługuje:

Każdy warunek providerBaseUrl obsługuje:

Dokumentacja metadanych narzędzi

toolMetadata używa tych samych struktur configSignals i authSignals co metadane dostawcy generowania, indeksowanych według nazwy narzędzia. contracts.tools deklaruje własność. toolMetadata deklaruje prosty dowód dostępności, dzięki czemu OpenClaw może uniknąć importowania środowiska uruchomieniowego pluginu tylko po to, aby jego fabryka narzędzia zwróciła null.

{  "setup": {    "providers": [      {        "id": "example",        "envVars": ["EXAMPLE_API_KEY"]      }    ]  },  "contracts": {    "tools": ["example_search"]  },  "toolMetadata": {    "example_search": {      "authSignals": [        {          "provider": "example"        }      ],      "configSignals": [        {          "rootPath": "plugins.entries.example.config",          "overlayPath": "search",          "required": ["apiKey"]        }      ]    }  }}

Wpisy toolMetadata akceptują również optional (oznacza narzędzie jako niewymagane do aktywacji pluginu) oraz replaySafe (oznacza wykonanie narzędzia jako bezpieczne do powtórzenia po niepełnej turze modelu), oprócz wspólnych pól configSignals/authSignals opisanych powyżej.

Jeśli narzędzie nie ma toolMetadata, OpenClaw zachowuje dotychczasowe działanie i ładuje plugin będący jego właścicielem, gdy kontrakt narzędzia odpowiada zasadom. W przypadku narzędzi używanych w ścieżkach krytycznych, których fabryka zależy od uwierzytelniania lub konfiguracji, autorzy pluginów powinni zadeklarować toolMetadata, zamiast wymuszać import środowiska uruchomieniowego przez podstawowy system w celu uzyskania tej informacji.

Dokumentacja providerAuthChoices

Każdy wpis providerAuthChoices opisuje jedną opcję wdrażania lub uwierzytelniania. OpenClaw odczytuje ją przed załadowaniem środowiska uruchomieniowego dostawcy. Listy konfiguracji dostawców korzystają z tych opcji manifestu, opcji konfiguracji wyprowadzonych z deskryptorów oraz metadanych katalogu instalacyjnego bez ładowania środowiska uruchomieniowego dostawcy.

Gdy appGuidedDiscovery ma wartość true, odpowiadająca metoda uwierzytelniania dostawcy musi udostępniać appGuidedSetup.detect i appGuidedSetup.prepare. Wykrywanie musi odbywać się wyłącznie do odczytu: bez logowania, pobierania modelu, pobierania plików ani zapisywania konfiguracji. Przygotowanie ponownie sprawdza dokładnie wybrany model i zwraca propozycję konfiguracji; OpenClaw testuje tę propozycję na żywo w izolacji i zatwierdza ją dopiero po powodzeniu.

Dokumentacja commandAliases

Należy użyć commandAliases, gdy plugin zarządza nazwą polecenia środowiska wykonawczego, którą użytkownicy mogą omyłkowo umieścić w plugins.allow lub próbować uruchomić jako główne polecenie CLI. OpenClaw używa tych metadanych do diagnostyki bez importowania kodu środowiska wykonawczego pluginu.

{  "commandAliases": [    {      "name": "dreaming",      "kind": "runtime-slash",      "cliCommand": "memory"    }  ]}

Dokumentacja activation

Należy użyć activation, gdy plugin może niewielkim kosztem zadeklarować, które zdarzenia płaszczyzny sterowania powinny uwzględniać go w planie aktywacji lub ładowania.

Ten blok zawiera metadane planisty, a nie interfejs API cyklu życia. Nie rejestruje zachowania środowiska wykonawczego, nie zastępuje register(...) ani nie gwarantuje, że kod pluginu został już wykonany. Planista aktywacji używa tych pól do zawężenia listy pluginów kandydujących, zanim skorzysta z istniejących metadanych własności manifestu, takich jak providers, channels, commandAliases, setup.providers, contracts.tools oraz haki.

Preferowane są najbardziej szczegółowe metadane, które już opisują własność. Należy użyć providers, channels, commandAliases, deskryptorów konfiguracji lub contracts, gdy te pola wyrażają daną relację. activation należy używać do dodatkowych wskazówek dla planisty, których nie można przedstawić za pomocą tych pól własności. cliBackends najwyższego poziomu należy używać do aliasów środowiska wykonawczego CLI, takich jak claude-cli, my-cli lub google-gemini-cli; activation.onAgentHarnesses służy wyłącznie do identyfikatorów osadzonej infrastruktury agentów, które nie mają jeszcze pola własności.

Każdy plugin powinien świadomie ustawić activation.onStartup. Wartość true należy ustawić tylko wtedy, gdy plugin musi działać podczas uruchamiania Gateway. Wartość false należy ustawić, gdy plugin jest bezczynny podczas uruchamiania i powinien być ładowany wyłącznie przez bardziej szczegółowe wyzwalacze. Pominięcie onStartup nie powoduje już niejawnego ładowania pluginu podczas uruchamiania; należy użyć jawnych metadanych aktywacji dla wyzwalaczy aktywacji podczas uruchamiania, przez kanał, konfigurację, infrastrukturę agenta, pamięć lub innych bardziej szczegółowych wyzwalaczy.

{  "activation": {    "onStartup": false,    "onProviders": ["openai"],    "onCommands": ["models"],    "onChannels": ["web"],    "onRoutes": ["gateway-webhook"],    "onConfigPaths": ["browser"],    "onCapabilities": ["provider", "tool"]  }}

Bieżący aktywni konsumenci:

• Planowanie uruchamiania Gateway używa activation.onStartup do jawnego importu podczas uruchamiania.
• Planowanie CLI wyzwalane poleceniem korzysta awaryjnie ze starszego mechanizmu commandAliases[].cliCommand lub commandAliases[].name.
• Planowanie uruchamiania środowiska wykonawczego agenta używa activation.onAgentHarnesses dla osadzonych mechanizmów testowych oraz nadrzędnego cliBackends[] dla aliasów środowiska wykonawczego CLI.
• Planowanie konfiguracji/kanału wyzwalane przez kanał korzysta awaryjnie ze starszej własności channels[], gdy brakuje jawnych metadanych aktywacji kanału.
• Planowanie Pluginów podczas uruchamiania używa activation.onConfigPaths dla głównych powierzchni konfiguracji niezwiązanych z kanałami, takich jak blok browser dołączonego Pluginu przeglądarki.
• Planowanie konfiguracji/środowiska wykonawczego wyzwalane przez dostawcę korzysta awaryjnie ze starszej własności providers[] i nadrzędnej własności cliBackends[], gdy brakuje jawnych metadanych aktywacji dostawcy.

Diagnostyka planisty może odróżnić jawne wskazówki aktywacji od awaryjnego użycia własności manifestu. Na przykład activation-command-hint oznacza dopasowanie activation.onCommands, natomiast manifest-command-alias oznacza, że planista użył zamiast tego własności commandAliases. Te etykiety przyczyn służą do diagnostyki hosta i testów; autorzy Pluginów powinni nadal deklarować metadane, które najlepiej opisują własność.

Dokumentacja qaRunners

Należy użyć qaRunners, gdy Plugin udostępnia co najmniej jeden moduł uruchamiający transport poniżej wspólnego elementu głównego openclaw qa. Te metadane powinny pozostać proste i statyczne; środowisko wykonawcze Pluginu nadal odpowiada za faktyczną rejestrację CLI za pośrednictwem lekkiej powierzchni runtime-api.ts, która eksportuje pasujące elementy qaRunnerCliRegistrations. Opcjonalny element adapterFactory udostępnia transport wspólnym scenariuszom kontroli jakości bez zmiany modułu uruchamiającego zarejestrowanego polecenia.

{  "qaRunners": [    {      "commandName": "matrix",      "description": "Uruchom obsługiwaną przez Docker ścieżkę kontroli jakości Matrix na żywo względem jednorazowego serwera macierzystego"    }  ]}

Identyfikator adapterFactory musi odpowiadać commandName. Nie należy eksportować rejestracji dla poleceń nieobecnych w manifeście.

Dokumentacja konfiguracji

Należy użyć setup, gdy powierzchnie konfiguracji i wdrażania potrzebują prostych metadanych należących do Pluginu przed załadowaniem środowiska wykonawczego.

{  "setup": {    "providers": [      {        "id": "openai",        "authMethods": ["api-key"],        "envVars": ["OPENAI_API_KEY"],        "authEvidence": [          {            "type": "local-file-with-env",            "fileEnvVar": "OPENAI_CREDENTIALS_FILE",            "requiresAllEnv": ["OPENAI_PROJECT"],            "credentialMarker": "openai-local-credentials",            "source": "lokalne dane uwierzytelniające openai"          }        ]      }    ],    "cliBackends": ["openai-cli"],    "configMigrations": ["legacy-openai-auth"],    "requiresRuntime": false  }}

Nadrzędny element cliBackends pozostaje prawidłowy i nadal opisuje zaplecza wnioskowania CLI. setup.cliBackends to powierzchnia deskryptorów specyficzna dla konfiguracji, przeznaczona dla przepływów płaszczyzny sterowania/konfiguracji, które powinny opierać się wyłącznie na metadanych.

Gdy elementy setup.providers i setup.cliBackends są obecne, stanowią preferowaną powierzchnię wyszukiwania opartą najpierw na deskryptorach podczas wykrywania konfiguracji. Jeśli deskryptor jedynie zawęża kandydujący Plugin, a konfiguracja nadal wymaga bogatszych punktów zaczepienia środowiska wykonawczego na etapie konfiguracji, należy ustawić requiresRuntime: true i pozostawić setup-api jako awaryjną ścieżkę wykonania.

OpenClaw uwzględnia również setup.providers[].envVars w ogólnych wyszukiwaniach uwierzytelniania dostawców i zmiennych środowiskowych. providerAuthEnvVars pozostaje obsługiwane za pośrednictwem adaptera zgodności w okresie wycofywania, ale niedołączone Pluginy, które nadal go używają, otrzymują komunikat diagnostyczny manifestu. Nowe Pluginy powinny umieszczać metadane środowiska konfiguracji/stanu w setup.providers[].envVars.

Należy użyć providerUsageAuthEnvVars, gdy dane uwierzytelniające na poziomie rozliczeń lub organizacji muszą aktywować resolveUsageAuth, nie stając się danymi uwierzytelniającymi do wnioskowania. Nazwy te zostają objęte blokowaniem plików dotenv obszaru roboczego, usuwaniem ze środowiska procesów podrzędnych ACP, filtrowaniem sekretów w piaskownicy i ogólnym oczyszczaniem sekretów. Środowisko wykonawcze dostawcy nadal odczytuje i klasyfikuje wartość wewnątrz resolveUsageAuth.

OpenClaw może również wyprowadzać proste opcje konfiguracji z setup.providers[].authMethods, gdy wpis konfiguracji jest niedostępny albo gdy setup.requiresRuntime: false deklaruje, że środowisko wykonawcze konfiguracji jest zbędne. Jawne wpisy providerAuthChoices pozostają preferowane w przypadku niestandardowych etykiet, flag CLI, zakresu wdrażania i metadanych asystenta.

Element requiresRuntime: false należy ustawić tylko wtedy, gdy te deskryptory są wystarczające dla powierzchni konfiguracji. OpenClaw traktuje jawny element false jako kontrakt oparty wyłącznie na deskryptorach i nie wykona setup-api ani openclaw.setupEntry podczas wyszukiwania konfiguracji. Jeśli Plugin oparty wyłącznie na deskryptorach nadal zawiera jeden z tych wpisów środowiska wykonawczego konfiguracji, OpenClaw zgłasza dodatkowy komunikat diagnostyczny i nadal go ignoruje. Pominięcie requiresRuntime zachowuje starsze zachowanie awaryjne, dzięki czemu istniejące Pluginy, które dodały deskryptory bez tej flagi, nie przestają działać.

Ponieważ wyszukiwanie konfiguracji może wykonywać kod setup-api należący do Pluginu, znormalizowane wartości setup.providers[].id i setup.cliBackends[] muszą pozostać unikatowe we wszystkich wykrytych Pluginach. W przypadku niejednoznacznej własności operacja kończy się niepowodzeniem zamiast wybierać zwycięzcę na podstawie kolejności wykrywania.

Gdy środowisko wykonawcze konfiguracji zostanie wykonane, diagnostyka rejestru konfiguracji zgłasza rozbieżność deskryptorów, jeśli setup-api rejestruje dostawcę lub zaplecze CLI, którego nie deklarują deskryptory manifestu, albo jeśli deskryptor nie ma odpowiadającej mu rejestracji środowiska wykonawczego. Te komunikaty diagnostyczne są dodatkowe i nie powodują odrzucania starszych Pluginów.

Dokumentacja setup.providers

Element authEvidence służy do lokalnych znaczników danych uwierzytelniających należących do dostawcy, które można zweryfikować bez ładowania kodu środowiska wykonawczego. Kontrole te muszą pozostać proste i lokalne: bez wywołań sieciowych, odczytów z pęku kluczy lub menedżera sekretów, poleceń powłoki ani prób interfejsu API dostawcy.

Obsługiwane wpisy dowodów:

Pola konfiguracji

Dokumentacja uiHints

uiHints to mapa nazw pól konfiguracji na niewielkie wskazówki dotyczące renderowania. Klucze mogą używać kropek dla zagnieżdżonych pól konfiguracji, ale żaden segment ścieżki nie może być równy __proto__, constructor ani prototype; konfiguracja odrzuca takie nazwy.

{  "uiHints": {    "apiKey": {      "label": "Klucz API",      "help": "Używany do żądań OpenRouter",      "placeholder": "sk-or-v1-...",      "sensitive": true    }  }}

Każda wskazówka pola może zawierać:

Dokumentacja kontraktów

Należy używać contracts wyłącznie dla statycznych metadanych własności możliwości, które OpenClaw może odczytać bez importowania środowiska wykonawczego Pluginu.

{  "contracts": {    "agentToolResultMiddleware": ["openclaw", "codex"],    "trustedToolPolicies": ["workflow-budget"],    "externalAuthProviders": ["acme-ai"],    "embeddingProviders": ["openai-compatible"],    "speechProviders": ["openai"],    "realtimeTranscriptionProviders": ["openai"],    "realtimeVoiceProviders": ["openai"],    "memoryEmbeddingProviders": ["local"],    "mediaUnderstandingProviders": ["openai"],    "imageGenerationProviders": ["openai"],    "videoGenerationProviders": ["qwen"],    "musicGenerationProviders": ["stability-audio"],    "documentExtractors": ["example-docs"],    "webContentExtractors": ["firecrawl"],    "webFetchProviders": ["firecrawl"],    "webSearchProviders": ["gemini"],    "workerProviders": ["example-worker"],    "usageProviders": ["acme-ai"],    "migrationProviders": ["hermes"],    "gatewayMethodDispatch": ["authenticated-request"],    "tools": ["firecrawl_search", "firecrawl_scrape"]  }}

Każda lista jest opcjonalna:

contracts.embeddedExtensionFactories jest zachowane dla wbudowanych fabryk rozszerzeń przeznaczonych wyłącznie dla serwera aplikacji Codex. Wbudowane przekształcenia wyników narzędzi powinny zamiast tego deklarować contracts.agentToolResultMiddleware i rejestrować się za pomocą api.registerAgentToolResultMiddleware(...). Zainstalowane pluginy mogą korzystać z tego samego punktu integracji oprogramowania pośredniczącego tylko po jawnym włączeniu i wyłącznie dla środowisk uruchomieniowych zadeklarowanych w contracts.agentToolResultMiddleware.

Zainstalowane pluginy, które potrzebują warstwy zaufanych przez hosta zasad poprzedzających narzędzia, muszą zadeklarować każdy rejestrowany lokalny identyfikator w contracts.trustedToolPolicies i zostać jawnie włączone. Wbudowane pluginy zachowują istniejącą ścieżkę zaufanych zasad, lecz zainstalowane pluginy z niezadeklarowanymi identyfikatorami zasad są odrzucane przed rejestracją. Identyfikatory zasad mają zakres pluginu, który je rejestruje, dlatego dwa pluginy mogą zadeklarować i zarejestrować workflow-budget; jeden plugin nie może dwukrotnie zarejestrować tego samego lokalnego identyfikatora.

Rejestracje środowiska uruchomieniowego api.registerTool(...) muszą odpowiadać contracts.tools. Mechanizm wykrywania narzędzi używa tej listy, aby ładować wyłącznie środowiska uruchomieniowe pluginów, które mogą być właścicielami żądanych narzędzi.

Pluginy dostawców implementujące resolveExternalAuthProfiles powinny deklarować contracts.externalAuthProviders; niezadeklarowane haki zewnętrznego uwierzytelniania są ignorowane.

Pluginy dostawców implementujące zarówno resolveUsageAuth, jak i fetchUsageSnapshot powinny deklarować każdy automatycznie wykrywany identyfikator dostawcy w contracts.usageProviders. Mechanizm wykrywania użycia odczytuje ten kontrakt przed załadowaniem kodu środowiska uruchomieniowego, a następnie weryfikuje oba haki po załadowaniu wyłącznie zadeklarowanych właścicieli.

Ogólni dostawcy osadzania powinni deklarować contracts.embeddingProviders dla każdego adaptera zarejestrowanego za pomocą api.registerEmbeddingProvider(...). Ogólnego kontraktu należy używać do wielokrotnego generowania wektorów, w tym przez dostawców używanych przez wyszukiwanie w pamięci. contracts.memoryEmbeddingProviders jest przestarzałą warstwą zgodności specyficzną dla pamięci i pozostaje tylko na czas migracji istniejących dostawców do ogólnego punktu integracji dostawców osadzania.

Dostawcy pracowników muszą deklarować każdy identyfikator api.registerWorkerProvider(...) w contracts.workerProviders. Rdzeń utrwala trwały zamiar przed wywołaniem provision; dostawcy weryfikują swoje ustawienia przed zewnętrzną alokacją, a powtarzane wywołania z tym samym identyfikatorem operacji muszą przejąć tę samą dzierżawę. Rdzeń utrwala również tę zweryfikowaną migawkę ustawień i przekazuje ją wraz z leaseId do inspect({ leaseId, profile }) oraz destroy({ leaseId, profile }), także po zmianie lub usunięciu nazwanego profilu. Niszczenie jest idempotentne, inspekcja zwraca zamkniętą unię stanów active / destroyed / unknown, a materiał prywatnego klucza SSH jest wskazywany wyłącznie za pośrednictwem SecretRef. Aprowizowane punkty końcowe SSH muszą również zawierać publiczny hostKey z zaufanych danych wyjściowych aprowizacji w dokładnym formacie algorithm base64, bez nazwy hosta ani komentarza, aby rdzeń mógł przypiąć host przed nawiązaniem połączenia. Dostawcy generujący dynamiczne odwołania do tożsamości mogą implementować autorytatywny resolveSshIdentity({ leaseId, profile, keyRef }); dostawcy bez niego używają ogólnego mechanizmu rozpoznawania sekretów rdzenia. Autorytatywny unknown osieroca aktywny rekord lokalny; po utrwalonym żądaniu zniszczenia potwierdza zakończenie usuwania.

contracts.gatewayMethodDispatch obecnie akceptuje "authenticated-request". Jest to bramka higieny API dla natywnych tras HTTP pluginów, które celowo wysyłają metody płaszczyzny sterowania Gateway w obrębie procesu, a nie piaskownica chroniąca przed złośliwymi natywnymi pluginami. Należy jej używać wyłącznie dla dokładnie zweryfikowanych powierzchni wbudowanych lub operatorskich, które już wymagają uwierzytelniania HTTP Gateway. Trasa z uprawnieniem pozostaje osiągalna przy zamkniętym przyjmowaniu pracy głównej przez Gateway tylko wtedy, gdy deklaruje również auth: "gateway" oraz specyficzny dla trasy gatewayRuntimeScopeSurface: "trusted-operator"; zwykłe trasy równorzędne tego samego pluginu pozostają za granicą przyjmowania. Dzięki temu stan zawieszenia i wznowienie pozostają dostępne bez przyznawania całemu pluginowi obejścia mechanizmu przyjmowania. Analizowanie i kształtowanie odpowiedzi poza wysyłaniem należy utrzymywać w ograniczonym zakresie; istotna lub modyfikująca praca musi przechodzić przez wysyłanie metod Gateway, które odpowiada za przyjmowanie i egzekwowanie zakresu.

Dokumentacja configContracts

Należy używać configContracts do zachowań konfiguracji należących do manifestu, których potrzebują ogólne pomocnicze mechanizmy rdzenia bez importowania środowiska uruchomieniowego pluginu: wykrywania niebezpiecznych flag, celów migracji SecretRef oraz zawężania starszych ścieżek konfiguracji.

{  "configContracts": {    "compatibilityMigrationPaths": ["legacyProvider"],    "compatibilityRuntimePaths": ["legacyProvider.webhook"],    "dangerousFlags": [      {        "path": "accounts.*.allowUnverifiedSenders",        "equals": true      }    ],    "secretInputs": {      "bundledDefaultEnabled": false,      "paths": [        {          "path": "apiKey",          "expected": "string"        }      ]    }  }}

Każdy wpis dangerousFlags obsługuje:

secretInputs obsługuje:

Dokumentacja mediaUnderstandingProviderMetadata

Należy użyć mediaUnderstandingProviderMetadata, gdy dostawca rozumienia multimediów ma domyślne modele, priorytet automatycznego uwierzytelniania awaryjnego lub natywną obsługę dokumentów, których ogólne pomocnicze funkcje rdzenia potrzebują przed załadowaniem środowiska uruchomieniowego. Klucze muszą być również zadeklarowane w contracts.mediaUnderstandingProviders.

{  "contracts": {    "mediaUnderstandingProviders": ["example"]  },  "mediaUnderstandingProviderMetadata": {    "example": {      "capabilities": ["image", "audio"],      "defaultModels": {        "image": "example-vision-latest",        "audio": "example-transcribe-latest"      },      "autoPriority": {        "image": 40      },      "nativeDocumentInputs": ["pdf"],      "documentModels": {        "pdf": {          "textExtraction": "example-doc-text-latest",          "image": "example-doc-vision-latest"        }      }    }  }}

Każdy wpis dostawcy może zawierać:

Dokumentacja channelConfigs

Należy użyć channelConfigs, gdy plugin kanału potrzebuje prostych metadanych konfiguracji przed załadowaniem środowiska uruchomieniowego. Wykrywanie konfiguracji i stanu kanału w trybie tylko do odczytu może używać tych metadanych bezpośrednio w przypadku skonfigurowanych kanałów zewnętrznych, gdy wpis konfiguracji jest niedostępny lub gdy setup.requiresRuntime: false wskazuje, że środowisko uruchomieniowe konfiguracji nie jest wymagane.

channelConfigs to metadane manifestu pluginu, a nie nowa sekcja najwyższego poziomu konfiguracji użytkownika. Użytkownicy nadal konfigurują instancje kanałów w channels.<channel-id>. OpenClaw odczytuje metadane manifestu, aby określić, który plugin jest właścicielem skonfigurowanego kanału, zanim zostanie wykonany kod środowiska uruchomieniowego pluginu.

W przypadku pluginu kanału configSchema i channelConfigs opisują różne ścieżki:

• configSchema weryfikuje plugins.entries.<plugin-id>.config
• channelConfigs.<channel-id>.schema weryfikuje channels.<channel-id>

Niedołączone pluginy deklarujące channels[] powinny także deklarować pasujące wpisy channelConfigs. Bez nich OpenClaw nadal może załadować plugin, ale schemat konfiguracji ścieżki zimnej, konfiguracja i powierzchnie Control UI nie mogą poznać kształtu opcji należących do kanału, dopóki nie zostanie wykonane środowisko uruchomieniowe pluginu.

channelConfigs.<channel-id>.commands.nativeCommandsAutoEnabled i nativeSkillsAutoEnabled mogą deklarować statyczne wartości domyślne auto na potrzeby kontroli konfiguracji poleceń wykonywanych przed załadowaniem środowiska uruchomieniowego kanału. Dołączone kanały mogą także publikować te same wartości domyślne przez package.json#openclaw.channel.commands wraz z innymi metadanymi katalogu kanałów należącymi do pakietu.

{  "channelConfigs": {    "matrix": {      "schema": {        "type": "object",        "additionalProperties": false,        "properties": {          "homeserverUrl": { "type": "string" }        }      },      "uiHints": {        "homeserverUrl": {          "label": "Adres URL serwera domowego",          "placeholder": "https://matrix.example.com"        }      },      "label": "Matrix",      "description": "Połączenie z serwerem domowym Matrix",      "commands": {        "nativeCommandsAutoEnabled": true,        "nativeSkillsAutoEnabled": true      },      "preferOver": ["matrix-legacy"]    }  }}

Każdy wpis kanału może zawierać:

Zastępowanie innego pluginu kanału

Należy użyć preferOver, gdy dany plugin jest preferowanym właścicielem identyfikatora kanału, który może być również udostępniany przez inny plugin. Typowe przypadki to zmieniony identyfikator pluginu, samodzielny plugin zastępujący plugin dołączony lub utrzymywany fork zachowujący ten sam identyfikator kanału w celu zgodności konfiguracji.

{  "id": "acme-chat",  "channels": ["chat"],  "channelConfigs": {    "chat": {      "schema": {        "type": "object",        "additionalProperties": false,        "properties": {          "webhookUrl": { "type": "string" }        }      },      "preferOver": ["chat"]    }  }}

Gdy skonfigurowano channels.chat, OpenClaw uwzględnia zarówno identyfikator kanału, jak i identyfikator preferowanego pluginu. Jeśli plugin o niższym priorytecie został wybrany tylko dlatego, że jest dołączony lub domyślnie włączony, OpenClaw wyłącza go w efektywnej konfiguracji środowiska uruchomieniowego, dzięki czemu jeden plugin jest właścicielem kanału i jego narzędzi. Jawny wybór użytkownika nadal ma pierwszeństwo: jeśli użytkownik jawnie włączy oba pluginy (przez plugins.allow lub istotną konfigurację plugins.entries), OpenClaw zachowa ten wybór i zgłosi diagnostykę zduplikowanych kanałów lub narzędzi zamiast niejawnie zmieniać żądany zestaw pluginów.

Zakres preferOver należy ograniczyć do identyfikatorów pluginów, które rzeczywiście mogą udostępniać ten sam kanał. Nie jest to ogólne pole priorytetu i nie zmienia nazw kluczy konfiguracji użytkownika.

Dokumentacja modelSupport

Należy użyć modelSupport, gdy OpenClaw powinien wywnioskować plugin dostawcy ze skróconych identyfikatorów modeli, takich jak gpt-5.6-sol lub claude-sonnet-4.6, przed załadowaniem środowiska uruchomieniowego pluginu.

{  "modelSupport": {    "modelPrefixes": ["gpt-", "o1", "o3", "o4"],    "modelPatterns": ["^computer-use-preview"]  }}

OpenClaw stosuje następującą kolejność pierwszeństwa:

• jawne odwołania provider/model używają metadanych manifestu należącego do providers
• modelPatterns mają pierwszeństwo przed modelPrefixes
• jeśli pasują zarówno jeden niedołączony, jak i jeden dołączony plugin, pierwszeństwo ma niedołączony plugin
• pozostałe niejednoznaczności są ignorowane, dopóki użytkownik lub konfiguracja nie określi dostawcy

Pola:

Wpisy modelPatterns są kompilowane za pomocą compileSafeRegex, które odrzuca wzorce zawierające zagnieżdżone powtórzenia (na przykład (a+)+$). Wzorce, które nie przejdą kontroli bezpieczeństwa, są pomijane bez komunikatu, podobnie jak wyrażenia regularne niepoprawne składniowo. Wzorce powinny być proste i nie zawierać zagnieżdżonych kwantyfikatorów.

Dokumentacja modelCatalog

Należy użyć modelCatalog, gdy OpenClaw powinien znać metadane modeli dostawcy przed załadowaniem środowiska uruchomieniowego pluginu. Jest to należące do manifestu źródło stałych wierszy katalogu, aliasów dostawców, reguł pomijania i trybu wykrywania. Odświeżanie w czasie wykonywania nadal należy do kodu środowiska uruchomieniowego dostawcy, ale manifest informuje rdzeń, kiedy środowisko uruchomieniowe jest wymagane.

{  "providers": ["openai"],  "modelCatalog": {    "providers": {      "openai": {        "baseUrl": "https://api.openai.com/v1",        "api": "openai-responses",        "models": [          {            "id": "gpt-5.4",            "name": "GPT-5.4",            "input": ["text", "image"],            "reasoning": true,            "contextWindow": 256000,            "maxTokens": 128000,            "cost": {              "input": 1.25,              "output": 10,              "cacheRead": 0.125            },            "status": "available",            "tags": ["default"]          }        ]      }    },    "aliases": {      "azure-openai-responses": {        "provider": "openai",        "api": "azure-openai-responses"      }    },    "suppressions": [      {        "provider": "azure-openai-responses",        "model": "gpt-5.3-codex-spark",        "reason": "niedostępne w Azure OpenAI Responses"      }    ],    "discovery": {      "openai": "static"    }  }}

Pola najwyższego poziomu:

aliases uczestniczy w wyszukiwaniu właściciela dostawcy na potrzeby planowania katalogu modeli. Cele aliasów muszą być nadrzędnymi dostawcami należącymi do tego samego pluginu. Gdy lista filtrowana według dostawcy używa aliasu, OpenClaw może odczytać manifest właściciela i zastosować nadpisania interfejsu API oraz bazowego adresu URL aliasu bez ładowania środowiska uruchomieniowego dostawcy. Aliasy nie rozszerzają niefiltrowanych list katalogu; szerokie listy zawierają wyłącznie wiersze kanonicznego dostawcy będącego właścicielem.

suppressions zastępuje stary punkt zaczepienia suppressBuiltInModel środowiska uruchomieniowego dostawcy. Wpisy pomijania są uwzględniane tylko wtedy, gdy dostawca należy do pluginu lub jest zadeklarowany jako klucz modelCatalog.aliases wskazujący na należącego do pluginu dostawcę. Punkty zaczepienia pomijania w środowisku uruchomieniowym nie są już wywoływane podczas rozpoznawania modelu.

Pola dostawcy:

Pola modelu:

Pola pomijania:

Nie umieszczać danych dostępnych wyłącznie w środowisku uruchomieniowym w modelCatalog. Używać static tylko wtedy, gdy wiersze manifestu są wystarczająco kompletne, aby listy filtrowane według dostawcy i powierzchnie wyboru mogły pominąć wykrywanie rejestru lub środowiska uruchomieniowego. Używać refreshable, gdy wiersze manifestu stanowią przydatne początkowe lub uzupełniające pozycje listy, ale późniejsze odświeżenie lub pamięć podręczna może dodać kolejne wiersze; wiersze możliwe do odświeżenia nie są same w sobie miarodajne. Używać runtime, gdy OpenClaw musi załadować środowisko uruchomieniowe dostawcy, aby poznać listę.

Dokumentacja modelIdNormalization

Używać modelIdNormalization do niedrogiego, należącego do dostawcy porządkowania identyfikatora modelu, które musi nastąpić przed załadowaniem środowiska uruchomieniowego dostawcy. Dzięki temu aliasy, takie jak krótkie nazwy modeli, starsze lokalne identyfikatory dostawcy i reguły prefiksów serwera proxy, pozostają w manifeście pluginu będącego właścicielem zamiast w podstawowych tabelach wyboru modeli.

{  "providers": ["anthropic", "openrouter"],  "modelIdNormalization": {    "providers": {      "anthropic": {        "aliases": {          "sonnet-4.6": "claude-sonnet-4-6"        }      },      "openrouter": {        "prefixWhenBare": "openrouter"      }    }  }}

Pola dostawcy:

Dokumentacja providerEndpoints

Używać providerEndpoints do klasyfikacji punktów końcowych, którą ogólna polityka żądań musi znać przed załadowaniem środowiska uruchomieniowego dostawcy. Rdzeń nadal definiuje znaczenie każdego endpointClass; manifesty pluginów definiują metadane hosta i bazowego adresu URL.

Oficjalne, wyodrębnione pluginy dostawców są wykluczone z dystrybucji rdzenia, dlatego ich manifesty pozostają niewidoczne do czasu instalacji. Ich providerEndpoints musi również mieć odzwierciedlenie w scripts/lib/official-external-provider-catalog.json, aby klasyfikacja punktów końcowych nadal działała bez pluginu; test kontraktowy wymusza zgodność tego odzwierciedlenia.

Pola punktu końcowego:

Dokumentacja providerRequest

Użyj providerRequest do przechowywania niewymagających dużych nakładów metadanych zgodności żądań, których ogólne zasady obsługi żądań potrzebują bez ładowania środowiska wykonawczego dostawcy. Przepisywanie ładunku zależne od zachowania należy pozostawić hakom środowiska wykonawczego dostawcy lub współdzielonym funkcjom pomocniczym rodziny dostawców.

{  "providerRequest": {    "providers": {      "vllm": {        "family": "vllm",        "openAICompletions": {          "supportsStreamingUsage": true        }      }    }  }}

Pola dostawcy:

Dokumentacja secretProviderIntegrations

Użyj secretProviderIntegrations, gdy plugin może opublikować gotową konfigurację wielokrotnego użytku dla dostawcy wykonawczego SecretRef. OpenClaw odczytuje te metadane przed załadowaniem środowiska wykonawczego pluginu, zapisuje własność pluginu w secrets.providers.<alias>.pluginIntegration i pozostawia faktyczne rozwiązywanie sekretów środowisku wykonawczemu SecretRef. Gotowe konfiguracje są udostępniane tylko dla pluginów wbudowanych oraz zainstalowanych pluginów wykrytych w zarządzanych katalogach głównych instalacji pluginów, takich jak instalacje z git i ClawHub.

{  "secretProviderIntegrations": {    "secret-store": {      "providerAlias": "team-secrets",      "displayName": "Team secrets",      "source": "exec",      "command": "${node}",      "args": ["./bin/resolve-secrets.mjs"]    }  }}

Klucz mapy jest identyfikatorem integracji. Jeśli pominięto providerAlias, OpenClaw używa identyfikatora integracji jako aliasu dostawcy SecretRef. Aliasy dostawców muszą być zgodne ze standardowym wzorcem aliasu dostawcy SecretRef, na przykład team-secrets lub onepassword-work.

Gdy operator wybierze gotową konfigurację, OpenClaw zapisuje odwołanie do dostawcy podobne do poniższego:

{  "secrets": {    "providers": {      "team-secrets": {        "source": "exec",        "pluginIntegration": {          "pluginId": "acme-secrets",          "integrationId": "secret-store"        }      }    }  }}

Podczas uruchamiania lub ponownego ładowania OpenClaw rozwiązuje tego dostawcę, ładując bieżące metadane manifestu pluginu, sprawdzając, czy plugin będący właścicielem jest zainstalowany i aktywny, oraz tworząc polecenie wykonawcze na podstawie manifestu. Wyłączenie lub usunięcie pluginu unieważnia dostawcę dla aktywnych odwołań SecretRef. Operatorzy, którzy potrzebują autonomicznej konfiguracji wykonawczej, nadal mogą bezpośrednio definiować ręcznych dostawców command/args.

Obecnie obsługiwane są tylko gotowe konfiguracje source: "exec". command musi mieć wartość ${node}, a args[0] musi być skryptem rozpoznawania ./ ze ścieżką względną wobec katalogu głównego pluginu. Podczas uruchamiania lub ponownego ładowania OpenClaw przekształca go w bieżący plik wykonywalny Node i bezwzględną ścieżkę skryptu wewnątrz pluginu. Opcje Node, takie jak --require, --import, --loader, --env-file, --eval i --print, nie należą do kontraktu gotowej konfiguracji manifestu. Operatorzy potrzebujący poleceń innych niż Node mogą bezpośrednio skonfigurować autonomicznych ręcznych dostawców wykonawczych.

OpenClaw wyprowadza trustedDirs dla gotowych konfiguracji manifestu z katalogu głównego pluginu oraz, w przypadku gotowych konfiguracji ${node}, z katalogu bieżącego pliku wykonywalnego Node. Wartości trustedDirs określone w manifeście są ignorowane. Inne opcje dostawcy wykonawczego, takie jak timeoutMs, noOutputTimeoutMs, maxOutputBytes, jsonOnly, env, passEnv i allowInsecurePath, są przekazywane do standardowej konfiguracji dostawcy wykonawczego SecretRef.

Dokumentacja modelPricing

Użyj modelPricing, gdy dostawca wymaga sterowania zachowaniem cen w płaszczyźnie sterowania przed załadowaniem środowiska wykonawczego. Pamięć podręczna cen Gateway odczytuje te metadane bez importowania kodu środowiska wykonawczego dostawcy.

{  "providers": ["ollama", "openrouter"],  "modelPricing": {    "providers": {      "ollama": {        "external": false      },      "openrouter": {        "openRouter": {          "passthroughProviderModel": true        },        "liteLLM": false      }    }  }}

Pola dostawcy:

Pola źródła:

Indeks dostawców OpenClaw

Indeks dostawców OpenClaw to należące do OpenClaw metadane podglądu dostawców, których pluginy mogą nie być jeszcze zainstalowane. Nie jest częścią manifestu pluginu. Manifesty pluginów pozostają źródłem nadrzędnym dla zainstalowanych pluginów. Indeks dostawców jest wewnętrznym kontraktem rezerwowym, z którego przyszłe interfejsy instalowalnych dostawców i wyboru modelu przed instalacją będą korzystać, gdy plugin dostawcy nie jest zainstalowany.

Kolejność nadrzędności katalogów:

1. Konfiguracja użytkownika.
2. Manifest zainstalowanego pluginu modelCatalog.
3. Pamięć podręczna katalogu modeli po jawnym odświeżeniu.
4. Wiersze podglądu indeksu dostawców OpenClaw.

Indeks dostawców nie może zawierać sekretów, stanu włączenia, haków środowiska wykonawczego ani bieżących danych modeli właściwych dla konta. Jego katalogi podglądu używają tego samego kształtu wiersza dostawcy modelCatalog co manifesty pluginów, ale powinny ograniczać się do stabilnych metadanych prezentacyjnych, chyba że pola adaptera środowiska wykonawczego, takie jak api, baseUrl, ceny lub flagi zgodności są celowo utrzymywane w zgodności z manifestem zainstalowanego pluginu. Dostawcy z aktywnym wykrywaniem /models powinni zapisywać odświeżone wiersze za pośrednictwem jawnej ścieżki pamięci podręcznej katalogu modeli, zamiast wywoływać interfejsy API dostawcy podczas zwykłego wyświetlania listy lub wdrażania.

Wpisy indeksu dostawców mogą również zawierać metadane instalowalnego pluginu dla dostawców, których plugin został przeniesiony poza rdzeń lub nie jest jeszcze zainstalowany z innego powodu. Metadane te odzwierciedlają wzorzec katalogu kanałów: nazwa pakietu, specyfikacja instalacji npm, oczekiwana integralność oraz niewymagające dużych nakładów etykiety wyboru uwierzytelniania wystarczają do wyświetlenia instalowalnej opcji konfiguracji. Po zainstalowaniu pluginu jego manifest ma pierwszeństwo, a wpis indeksu dostawców jest ignorowany dla tego dostawcy.

openclaw doctor --fix migruje niewielki, zamknięty zestaw starszych kluczy możliwości najwyższego poziomu manifestu do contracts.*: speechProviders, mediaUnderstandingProviders, imageGenerationProviders i tools. Żaden z nich (ani żadna inna lista możliwości) nie jest już odczytywany jako pole najwyższego poziomu manifestu; standardowe ładowanie manifestu rozpoznaje je wyłącznie w contracts.

Manifest a package.json

Te dwa pliki służą do różnych celów:

W razie wątpliwości, gdzie powinny znaleźć się określone metadane, należy zastosować tę regułę:

• jeśli OpenClaw musi je znać przed załadowaniem kodu pluginu, umieść je w openclaw.plugin.json
• jeśli dotyczą pakowania, plików wejściowych lub zachowania instalacji npm, umieść je w package.json

Pola package.json wpływające na wykrywanie

Niektóre metadane pluginu używane przed uruchomieniem celowo znajdują się w package.json, w bloku openclaw, zamiast w openclaw.plugin.json. openclaw.bundle i openclaw.bundle.json nie są kontraktami pluginów OpenClaw; natywne pluginy muszą używać openclaw.plugin.json wraz z obsługiwanymi polami package.json#openclaw opisanymi poniżej.

Ważne przykłady:

Metadane manifestu określają, które opcje dostawcy/kanału/konfiguracji pojawiają się podczas wdrażania przed załadowaniem środowiska uruchomieniowego. package.json#openclaw.install informuje proces wdrażania, jak pobrać lub włączyć ten plugin, gdy zostanie wybrana jedna z tych opcji. Nie należy przenosić wskazówek instalacyjnych do openclaw.plugin.json.

openclaw.install.minHostVersion jest egzekwowane podczas instalacji i ładowania rejestru manifestów dla źródeł pluginów, które nie są dołączone. Nieprawidłowe wartości są odrzucane; wartości nowsze, ale prawidłowe powodują pominięcie zewnętrznych pluginów na starszych hostach. Zakłada się, że dołączone pluginy źródłowe mają tę samą wersję co kod źródłowy hosta.

openclaw.install.requiredPlatformPackages jest przeznaczone dla pakietów npm, które udostępniają wymagane natywne pliki binarne za pośrednictwem opcjonalnych aliasów właściwych dla platformy. Należy podać samą nazwę pakietu npm dla aliasu każdej obsługiwanej platformy. Podczas instalacji npm OpenClaw weryfikuje tylko zadeklarowany alias, którego ograniczenia w pliku blokady odpowiadają bieżącemu hostowi. Jeśli npm zgłosi powodzenie, ale pominie ten alias, OpenClaw ponawia próbę raz ze świeżą pamięcią podręczną i wycofuje instalację, jeśli aliasu nadal brakuje.

openclaw.compat.pluginApi jest egzekwowane podczas instalacji pakietu dla źródeł pluginów, które nie są dołączone. Należy używać go do określenia dolnej granicy API SDK/środowiska uruchomieniowego pluginów OpenClaw, względem której zbudowano pakiet. Może być bardziej rygorystyczne niż minHostVersion, gdy pakiet pluginu wymaga nowszego API, ale nadal zachowuje niższą wskazówkę instalacyjną dla innych procesów. Oficjalna synchronizacja wydań OpenClaw domyślnie podnosi istniejące dolne granice API oficjalnych pluginów do wersji wydania OpenClaw, ale wydania obejmujące wyłącznie plugin mogą zachować niższą granicę, gdy pakiet celowo obsługuje starsze hosty. Nie należy używać samej wersji pakietu jako kontraktu zgodności. peerDependencies.openclaw pozostaje metadanymi pakietu npm; OpenClaw używa kontraktu openclaw.compat.pluginApi do podejmowania decyzji o zgodności instalacji.

Oficjalne metadane instalacji na żądanie powinny używać clawhubSpec, gdy plugin jest opublikowany w ClawHub; proces wdrażania traktuje je jako preferowane źródło zdalne i po instalacji zapisuje informacje o artefakcie ClawHub. npmSpec pozostaje awaryjnym mechanizmem zgodności dla pakietów, które nie zostały jeszcze przeniesione do ClawHub.

Dokładne przypięcie wersji npm znajduje się już w npmSpec, na przykład "npmSpec": "@wecom/wecom-openclaw-plugin@1.2.3". Oficjalne wpisy katalogu zewnętrznego powinny łączyć dokładne specyfikacje z expectedIntegrity, aby procesy aktualizacji kończyły się niepowodzeniem w sposób bezpieczny, jeśli pobrany artefakt npm nie odpowiada już przypiętemu wydaniu. Interaktywny proces wdrażania nadal oferuje zaufane specyfikacje npm z rejestru, w tym same nazwy pakietów i znaczniki dystrybucji, ze względu na zgodność. Diagnostyka katalogu może rozróżniać źródła: dokładne, zmienne, przypięte integralnością, bez integralności, z niezgodnością nazwy pakietu oraz z nieprawidłową opcją domyślną. Ostrzega również, gdy występuje expectedIntegrity, ale nie istnieje prawidłowe źródło npm, które można przypiąć. Gdy występuje expectedIntegrity, procesy instalacji/aktualizacji je egzekwują; gdy zostanie pominięte, rozstrzygnięcie rejestru jest zapisywane bez przypięcia integralności.

Pluginy kanałów powinny udostępniać openclaw.setupEntry, gdy skanowanie statusu, listy kanałów lub SecretRef wymaga identyfikowania skonfigurowanych kont bez ładowania pełnego środowiska uruchomieniowego. Punkt wejścia konfiguracji powinien udostępniać metadane kanału oraz bezpieczne dla konfiguracji adaptery ustawień, statusu i sekretów; klientów sieciowych, procesy nasłuchujące Gateway i środowiska uruchomieniowe transportu należy pozostawić w głównym punkcie wejścia rozszerzenia.

Pola punktów wejścia środowiska uruchomieniowego nie zastępują kontroli granic pakietu dla pól źródłowych punktów wejścia. Na przykład openclaw.runtimeExtensions nie może umożliwić załadowania ścieżki openclaw.extensions, która wychodzi poza pakiet.

Zakres openclaw.install.allowInvalidConfigRecovery jest celowo wąski. Nie umożliwia instalowania dowolnych uszkodzonych konfiguracji. Obecnie pozwala procesom instalacji wyłącznie odzyskiwać sprawność po konkretnych błędach aktualizacji nieaktualnych dołączonych pluginów, takich jak brakująca ścieżka dołączonego pluginu lub nieaktualny wpis channels.<id> dotyczący tego samego dołączonego pluginu. Niepowiązane błędy konfiguracji nadal blokują instalację i kierują operatorów do openclaw doctor --fix.

openclaw.channel.persistedAuthState to metadane pakietu dla niewielkiego modułu sprawdzającego:

{  "openclaw": {    "channel": {      "id": "whatsapp",      "persistedAuthState": {        "specifier": "./auth-presence",        "exportName": "hasAnyWhatsAppAuth"      }    }  }}

Należy ich używać, gdy konfiguracja, narzędzie doctor, status lub procesy sprawdzania obecności w trybie tylko do odczytu wymagają taniego sprawdzenia uwierzytelnienia typu tak/nie przed załadowaniem pełnego pluginu kanału. Utrwalony stan uwierzytelnienia nie jest skonfigurowanym stanem kanału: nie należy używać tych metadanych do automatycznego włączania pluginów, naprawiania zależności środowiska uruchomieniowego ani decydowania, czy środowisko uruchomieniowe kanału powinno zostać załadowane. Docelowy eksport powinien być niewielką funkcją, która odczytuje wyłącznie utrwalony stan; nie należy kierować go przez pełny moduł zbiorczy środowiska uruchomieniowego kanału.

openclaw.channel.configuredState obsługuje tanie kontrole konfiguracji. Gdy zmienne środowiskowe są wystarczające, preferowane są deklaratywne metadane środowiska:

{  "openclaw": {    "channel": {      "id": "telegram",      "configuredState": {        "env": {          "allOf": ["TELEGRAM_BOT_TOKEN"]        }      }    }  }}

Należy używać env.allOf, gdy wymagana jest każda z wymienionych zmiennych, oraz env.anyOf, gdy wystarczy dowolna jedna niepusta zmienna. Jeśli niewielka kontrola niewymagająca środowiska uruchomieniowego potrzebuje czegoś więcej niż metadane środowiska, należy użyć specifier wraz z exportName, jak pokazano dla persistedAuthState; gdy występuje env, OpenClaw używa go bez ładowania tego modułu. Jeśli kontrola wymaga pełnego rozstrzygnięcia konfiguracji lub rzeczywistego środowiska uruchomieniowego kanału, tę logikę należy pozostawić w haku config.hasConfiguredState pluginu.

Kolejność pierwszeństwa wykrywania (zduplikowane identyfikatory pluginów)

OpenClaw wykrywa pluginy w trzech katalogach głównych, sprawdzanych w następującej kolejności: pluginy dołączone do OpenClaw, globalny katalog główny instalacji (~/.openclaw/extensions) i katalog główny bieżącego obszaru roboczego (<workspace>/.openclaw/extensions), a także wszystkie jawne wpisy plugins.load.paths.

Jeśli dwa wykryte elementy mają ten sam id, zachowywany jest tylko manifest o najwyższym pierwszeństwie; duplikaty o niższym pierwszeństwie są odrzucane zamiast ładowania obok niego. Kolejność od najwyższego do najniższego pierwszeństwa:

1. Wybrany przez konfigurację — ścieżka jawnie przypięta w plugins.entries.<id>
2. Instalacja globalna odpowiadająca śledzonemu rekordowi instalacji — plugin zainstalowany za pomocą openclaw plugin install/openclaw plugin update, którego śledzenie instalacji OpenClaw rozpoznaje dla tego samego identyfikatora, nawet jeśli identyfikator należy również do dołączonego pluginu
3. Dołączony — pluginy dostarczane z OpenClaw
4. Obszar roboczy — pluginy wykryte względem bieżącego obszaru roboczego
5. Każdy inny wykryty kandydat

Konsekwencje:

• Rozgałęziona lub nieaktualna kopia dołączonego pluginu, znajdująca się bez śledzenia w obszarze roboczym lub globalnym katalogu głównym, nie zastąpi dołączonej kompilacji.
• Aby zastąpić dołączony plugin, należy uruchomić openclaw plugin install dla tego identyfikatora, dzięki czemu śledzona instalacja globalna uzyska wyższe pierwszeństwo niż dołączona kopia, albo przypiąć konkretną ścieżkę za pomocą plugins.entries.<id>, aby wygrała dzięki pierwszeństwu wyboru przez konfigurację.
• Odrzucenia duplikatów są rejestrowane, aby narzędzie Doctor i diagnostyka uruchamiania mogły wskazać odrzuconą kopię.
• Zastąpienia duplikatów wybrane przez konfigurację są opisywane w diagnostyce jako jawne zastąpienia, ale nadal generują ostrzeżenie, aby nieaktualne rozwidlenia i przypadkowe przesłonięcia pozostawały widoczne.

Wymagania dotyczące schematu JSON

• Każdy plugin musi zawierać schemat JSON, nawet jeśli nie przyjmuje żadnej konfiguracji.
• Pusty schemat jest dopuszczalny (na przykład { "type": "object", "additionalProperties": false }).
• Schematy są walidowane podczas odczytu i zapisu konfiguracji, a nie w czasie wykonywania.
• Podczas rozszerzania lub tworzenia forka dołączonego pluginu o nowe klucze konfiguracji należy jednocześnie zaktualizować openclaw.plugin.json configSchema tego pluginu. Schematy dołączonych pluginów są rygorystyczne, więc dodanie plugins.entries.<id>.config.myNewKey w konfiguracji użytkownika bez dodania myNewKey do configSchema.properties zostanie odrzucone przed załadowaniem środowiska uruchomieniowego pluginu.

Przykład rozszerzenia schematu:

{  "configSchema": {    "type": "object",    "additionalProperties": false,    "properties": {      "myNewKey": {        "type": "string"      }    }  }}

Zachowanie walidacji

• Nieznane klucze channels.* są błędami, chyba że identyfikator kanału jest zadeklarowany w manifeście pluginu. Jeśli ten sam identyfikator występuje również w plugins.allow, plugins.entries lub plugins.installs (plugin, do którego istnieje odwołanie, ale którego obecnie nie można wykryć), OpenClaw obniża rangę problemu do ostrzeżenia.
• Odwołania w plugins.entries.<id>, plugins.allow i plugins.deny do nieznanych identyfikatorów pluginów są ostrzeżeniami („zignorowano nieaktualny wpis konfiguracji”), a nie błędami, dzięki czemu aktualizacje oraz usunięte lub przemianowane pluginy nie blokują uruchomienia Gateway.
• Odwołanie w plugins.slots.memory do nieznanego identyfikatora pluginu jest błędem, z wyjątkiem znanego oficjalnego zewnętrznego pluginu memory-lancedb, w przypadku którego wyświetlane jest ostrzeżenie.
• Jeśli plugin jest zainstalowany, ale jego manifest lub schemat jest uszkodzony albo go brakuje, walidacja kończy się niepowodzeniem, a Doctor zgłasza błąd pluginu.
• Jeśli konfiguracja pluginu istnieje, ale plugin jest wyłączony, konfiguracja zostaje zachowana, a w Doctor i logach pojawia się ostrzeżenie.

Pełny schemat plugins.* opisano w dokumentacji konfiguracji.

Uwagi

• Manifest jest wymagany w przypadku natywnych pluginów OpenClaw, w tym ładowanych z lokalnego systemu plików. Środowisko uruchomieniowe nadal ładuje moduł pluginu osobno; manifest służy wyłącznie do wykrywania i walidacji.
• Natywne manifesty są analizowane jako JSON5, dlatego komentarze, końcowe przecinki i klucze bez cudzysłowów są dozwolone, o ile końcowa wartość nadal jest obiektem.
• Moduł ładujący manifest odczytuje wyłącznie udokumentowane pola manifestu. Należy unikać niestandardowych kluczy najwyższego poziomu.
• channels, providers, cliBackends i skills można pominąć, jeśli plugin ich nie potrzebuje.
• providerCatalogEntry musi pozostać lekki i nie powinien importować rozbudowanego kodu środowiska uruchomieniowego; należy używać go do statycznych metadanych katalogu dostawców lub wąskich deskryptorów wykrywania, a nie do wykonywania operacji podczas obsługi żądań.
• Wyłączne rodzaje pluginów są wybierane przez plugins.slots.*: kind: "memory" za pomocą plugins.slots.memory (domyślnie memory-core), kind: "context-engine" za pomocą plugins.slots.contextEngine (domyślnie legacy).
• Wyłączny rodzaj pluginu należy zadeklarować w tym manifeście. Pole OpenClawPluginDefinition.kind punktu wejścia środowiska uruchomieniowego jest przestarzałe i pozostaje jedynie jako mechanizm zgodności ze starszymi pluginami.
• Metadane zmiennych środowiskowych (setup.providers[].envVars, przestarzałe providerAuthEnvVars oraz channelEnvVars) mają wyłącznie charakter deklaratywny. Status, audyt, walidacja dostarczania Cron i inne powierzchnie tylko do odczytu nadal uwzględniają poziom zaufania pluginu oraz obowiązujące zasady aktywacji, zanim uznają zmienną środowiskową za skonfigurowaną.
• Metadane kreatora środowiska uruchomieniowego wymagające kodu dostawcy opisano w sekcji Hooki środowiska uruchomieniowego dostawcy.
• Jeśli plugin zależy od modułów natywnych, należy udokumentować kroki kompilacji oraz wszelkie wymagania dotyczące listy dozwolonych elementów menedżera pakietów (na przykład pnpm allow-build-scripts + pnpm rebuild <package>).

Powiązane