Manifest Pluginu

Ta strona opisuje natywny manifest Pluginu OpenClaw, openclaw.plugin.json. Informacje o zgodnych układach pakietów (Codex, Claude, Cursor) zawiera strona 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 sprawdza ich zgodności z poniższym schematem openclaw.plugin.json. W przypadku zgodnego pakietu OpenClaw odczytuje metadane pakietu, zadeklarowane katalogi główne Skills, katalogi główne poleceń Claude, wartości domyślne Claude z pliku settings.json, wartości domyślne LSP Claude oraz obsługiwane pakiety hooków, jeśli układ spełnia wymagania środowiska uruchomieniowego OpenClaw.

Każdy natywny Plugin OpenClaw musi zawierać plik openclaw.plugin.json w katalogu głównym Pluginu. OpenClaw odczytuje go, aby zweryfikować konfigurację bez wykonywania kodu Pluginu. Brakujący lub nieprawidłowy manifest uniemożliwia weryfikację 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 lekkie, aby nie wymagało uruchamiania środowiska wykonawczego Pluginu.

Używaj go do definiowania:

• tożsamości Pluginu, walidacji konfiguracji i podpowiedzi interfejsu konfiguracji
• metadanych uwierzytelniania, wdrażania i konfiguracji (aliasu, automatycznego włączania, zmiennych środowiskowych dostawcy i opcji uwierzytelniania)
• wskazówek aktywacji dla powierzchni płaszczyzny sterowania
• skróconej deklaracji własności rodzin modeli
• statycznych migawek własności możliwości (contracts)
• metadanych modułu uruchamiającego QA, które może odczytać współdzielony host openclaw qa
• metadanych konfiguracji specyficznych dla kanału, scalanych z katalogiem i powierzchniami walidacji

Nie używaj go do: rejestrowania zachowania w środowisku uruchomieniowym, deklarowania punktów wejścia kodu ani 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": "OpenRouter provider plugin",  "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": "OpenRouter API key",      "groupId": "openrouter",      "groupLabel": "OpenRouter",      "optionKey": "openrouterApiKey",      "cliFlag": "--openrouter-api-key",      "cliOption": "--openrouter-api-key <key>",      "cliDescription": "OpenRouter API key",      "onboardingScopes": ["text-inference"]    }  ],  "uiHints": {    "apiKey": {      "label": "API key",      "placeholder": "sk-or-v1-...",      "sensitive": true    }  },  "configSchema": {    "type": "object",    "additionalProperties": false,    "properties": {      "apiKey": {        "type": "string"      }    }  }}

Opis pól najwyższego poziomu

Informacje o catalog

catalog udostępnia opcjonalne wskazówki dotyczące wyświetlania dla przeglądarek Pluginów. Hosty mogą ignorować te wskazówki. Nigdy nie instalują ani nie włączają one Pluginu oraz nie zmieniają jego zachowania w czasie działania ani poziomu zaufania.

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

Informacje o metadanych dostawcy generowania

Pola metadanych dostawcy generowania opisują statyczne sygnały uwierzytelniania dla dostawców zadeklarowanych na odpowiedniej 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.

Używaj tych pól wyłącznie do prostych faktów deklaratywnych, których sprawdzanie jest mało kosztowne. Transport, przekształcenia żądań, odświeżanie tokenów, weryfikacja danych uwierzytelniających i faktyczne generowanie 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 następujące pola:

Każdy wpis configSignals obsługuje następujące pola:

Każdy warunek mode obsługuje następujące pola:

Każdy wpis authSignals obsługuje następujące pola:

Każdy warunek providerBaseUrl obsługuje następujące pola:

Informacje o metadanych narzędzi

toolMetadata używa takich samych struktur configSignals i authSignals jak metadane dostawcy generowania, indeksowanych według nazwy narzędzia. contracts.tools deklaruje własność. toolMetadata deklaruje proste dowody dostępności, aby OpenClaw nie musiał importować środowiska uruchomieniowego Pluginu tylko po to, by jego fabryka narzędzi 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 przyjmują również pola optional (oznacza narzędzie jako niewymagane do aktywacji Pluginu) i 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 właścicielem, gdy kontrakt narzędzia jest zgodny z zasadami. W przypadku narzędzi używanych na ścieżkach krytycznych, których fabryka zależy od uwierzytelniania lub konfiguracji, autorzy Pluginów powinni zadeklarować toolMetadata, zamiast zmuszać rdzeń do importowania środowiska uruchomieniowego w celu wykonania sprawdzenia.

Informacje o providerAuthChoices

Każdy wpis providerAuthChoices opisuje jedną opcję wdrożenia początkowego lub uwierzytelniania. OpenClaw odczytuje go przed załadowaniem środowiska uruchomieniowego dostawcy. Listy konfiguracji dostawców korzystają z tych opcji manifestu, opcji konfiguracji pochodzących z deskryptorów oraz metadanych katalogu instalacyjnego bez ładowania środowiska uruchomieniowego dostawcy.

Dokumentacja commandAliases

Użyj commandAliases, gdy plugin jest właścicielem nazwy polecenia środowiska uruchomieniowego, 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 uruchomieniowego pluginu.

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

Dokumentacja activation

Użyj 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 uruchomieniowego, 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 w manifeście, takich jak providers, channels, commandAliases, setup.providers, contracts.tools i hooki.

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

Każdy plugin powinien jawnie ustawić activation.onStartup. Ustaw wartość true tylko wtedy, gdy plugin musi działać podczas uruchamiania Gateway. Ustaw wartość false, gdy plugin pozostaje nieaktywny podczas uruchamiania i powinien być ładowany wyłącznie przez bardziej szczegółowe wyzwalacze. Pominięcie onStartup nie powoduje już niejawnego ładowania pluginu podczas uruchamiania; użyj jawnych metadanych aktywacji dla uruchamiania, kanału, konfiguracji, uprzęży agenta, pamięci lub innych bardziej szczegółowych wyzwalaczy aktywacji.

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

Bieżący aktywni odbiorcy:

• Planowanie uruchamiania Gateway używa activation.onStartup do jawnego importu podczas uruchamiania.
• Planowanie CLI wyzwalane poleceniami korzysta awaryjnie ze starszego commandAliases[].cliCommand lub commandAliases[].name.
• Planowanie uruchamiania środowiska agenta używa activation.onAgentHarnesses dla osadzonych uprzęży oraz cliBackends[] najwyższego poziomu dla aliasów środowiska uruchomieniowego CLI.
• Planowanie konfiguracji lub kanału wyzwalane kanałem 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 obszarów konfiguracji niezwiązanych z kanałami, takich jak blok browser dołączonego pluginu przeglądarki.
• Planowanie konfiguracji lub środowiska uruchomieniowego wyzwalane dostawcą korzysta awaryjnie ze starszej własności providers[] i cliBackends[] najwyższego poziomu, gdy brakuje jawnych metadanych aktywacji dostawcy.

Diagnostyka planisty potrafi odróżnić jawne wskazówki aktywacji od awaryjnego użycia własności z 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 najlepiej opisujące własność.

Dokumentacja qaRunners

Użyj qaRunners, gdy plugin udostępnia jeden lub więcej modułów uruchamiających transport pod wspólnym głównym poleceniem openclaw qa. Te metadane powinny pozostać proste i statyczne; środowisko uruchomieniowe pluginu nadal odpowiada za właściwą rejestrację CLI za pośrednictwem lekkiego interfejsu runtime-api.ts, który eksportuje pasujące qaRunnerCliRegistrations. Opcjonalne adapterFactory udostępnia transport wspólnym scenariuszom QA bez zmiany modułu uruchamiającego zarejestrowanego polecenia.

{  "qaRunners": [    {      "commandName": "matrix",      "description": "Run the Docker-backed Matrix live QA lane against a disposable homeserver"    }  ]}

Identyfikator adapterFactory musi być zgodny z commandName. Nie eksportuj rejestracji dla poleceń nieobecnych w manifeście.

Dokumentacja setup

Użyj setup, gdy interfejsy konfiguracji i wdrażania potrzebują niedrogich 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": "openai local credentials"          }        ]      }    ],    "cliBackends": ["openai-cli"],    "configMigrations": ["legacy-openai-auth"],    "requiresRuntime": false  }}

cliBackends najwyższego poziomu pozostaje prawidłowe i nadal opisuje backendy wnioskowania CLI. setup.cliBackends to specyficzny dla konfiguracji interfejs deskryptorów przeznaczony dla przepływów płaszczyzny sterowania i konfiguracji, które powinny korzystać wyłącznie z metadanych.

Jeśli są dostępne, setup.providers i setup.cliBackends stanowią preferowany interfejs wyszukiwania oparty najpierw na deskryptorach podczas wykrywania konfiguracji. Jeśli deskryptor jedynie zawęża wybór pluginu, a konfiguracja nadal potrzebuje bogatszych hooków środowiska wykonawczego na etapie konfiguracji, ustaw requiresRuntime: true i zachowaj setup-api jako rezerwową ścieżkę wykonania.

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

Użyj providerUsageAuthEnvVars, gdy poświadczenie na poziomie rozliczeń lub organizacji musi aktywować resolveUsageAuth, nie stając się poświadczeniem wnioskowania. Nazwy te zostają objęte blokowaniem plików dotenv obszaru roboczego, usuwaniem ze zmiennych procesów potomnych ACP, filtrowaniem sekretów w piaskownicy oraz szerokim usuwaniem sekretów. Środowisko wykonawcze dostawcy nadal odczytuje i klasyfikuje wartość wewnątrz resolveUsageAuth.

OpenClaw może również wyprowadzić proste opcje konfiguracji z setup.providers[].authMethods, gdy nie jest dostępny punkt wejścia konfiguracji lub gdy setup.requiresRuntime: false deklaruje, że środowisko wykonawcze konfiguracji jest zbędne. Jawne wpisy providerAuthChoices pozostają preferowane dla niestandardowych etykiet, flag CLI, zakresu wdrażania i metadanych asystenta.

Ustaw requiresRuntime: false tylko wtedy, gdy te deskryptory są wystarczające dla interfejsu konfiguracji. OpenClaw traktuje jawne 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 udostępnia jeden z tych punktów wejścia środowiska wykonawczego konfiguracji, OpenClaw zgłasza dodatkowy komunikat diagnostyczny i nadal go ignoruje. Pominięcie requiresRuntime zachowuje starsze zachowanie rezerwowe, dzięki czemu istniejące pluginy, które dodały deskryptory bez tej flagi, nie przestaną działać.

Ponieważ wyszukiwanie konfiguracji może wykonywać należący do pluginu kod setup-api, znormalizowane wartości setup.providers[].id i setup.cliBackends[] muszą być unikatowe wśród wykrytych pluginów. W przypadku niejednoznacznej własności operacja kończy się bezpiecznym niepowodzeniem zamiast wyboru zwycięzcy na podstawie kolejności wykrywania.

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

Dokumentacja setup.providers

authEvidence służy do obsługi należących do dostawcy lokalnych znaczników poświadczeń, które można zweryfikować bez ładowania kodu środowiska wykonawczego. Te kontrole muszą być niedrogie i lokalne: bez wywołań sieciowych, odczytów z pęku kluczy lub menedżera sekretów, poleceń powłoki ani sondowania API dostawcy.

Obsługiwane wpisy dowodów:

Pola setup

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 mieć wartości __proto__, constructor ani prototype; konfiguracja odrzuca takie nazwy.

{  "uiHints": {    "apiKey": {      "label": "API key",      "help": "Used for OpenRouter requests",      "placeholder": "sk-or-v1-...",      "sensitive": true    }  }}

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

Dokumentacja contracts

Używaj contracts wyłącznie do 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 zachowano dla dołączonych fabryk rozszerzeń przeznaczonych wyłącznie dla serwera aplikacji Codex. Dołączone transformacje wyników narzędzi powinny zamiast tego deklarować contracts.agentToolResultMiddleware i rejestrować się za pomocą api.registerAgentToolResultMiddleware(...). Zainstalowane Pluginy mogą korzystać z tego samego mechanizmu oprogramowania pośredniczącego tylko wtedy, gdy zostanie on jawnie włączony, i tylko dla środowisk wykonawczych zadeklarowanych w contracts.agentToolResultMiddleware.

Zainstalowane Pluginy, które potrzebują zaufanej przez hosta warstwy zasad wykonywanych przed narzędziem, muszą zadeklarować każdy rejestrowany lokalny identyfikator w contracts.trustedToolPolicies i zostać jawnie włączone. Dołączone Pluginy zachowują istniejącą ścieżkę zaufanych zasad, ale zainstalowane Pluginy z niezadeklarowanymi identyfikatorami zasad są odrzucane przed rejestracją. Identyfikatory zasad są ograniczone do rejestrującego Pluginu, dlatego dwa Pluginy mogą zarówno zadeklarować, jak i zarejestrować workflow-budget; pojedynczy Plugin nie może dwukrotnie zarejestrować tego samego lokalnego identyfikatora.

Rejestracje api.registerTool(...) w środowisku wykonawczym muszą odpowiadać contracts.tools. Mechanizm wykrywania narzędzi używa tej listy, aby ładować tylko środowiska wykonawcze Pluginów, które mogą być właścicielami żądanych narzędzi.

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

Pluginy dostawców implementujące zarówno resolveUsageAuth, jak i fetchUsageSnapshot powinny deklarować w contracts.usageProviders każdy automatycznie wykrywany identyfikator dostawcy. Mechanizm wykrywania użycia odczytuje ten kontrakt przed załadowaniem kodu środowiska wykonawczego, 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 generowania wektorów wielokrotnego użytku, w tym przez dostawców używanych przez wyszukiwanie w pamięci. contracts.memoryEmbeddingProviders to przestarzały mechanizm zgodności specyficzny dla pamięci, który pozostaje dostępny tylko na czas migracji istniejących dostawców do ogólnego mechanizmu dostawców osadzania.

Dostawcy procesów roboczych muszą deklarować w contracts.workerProviders każdy identyfikator przekazywany do api.registerWorkerProvider(...). Rdzeń utrwala trwały zamiar przed wywołaniem provision; dostawcy weryfikują swoje ustawienia przed przydzieleniem zasobów zewnętrznych, a powtarzane wywołania z tym samym identyfikatorem operacji muszą przejmować tę samą dzierżawę. Rdzeń utrwala również migawkę zweryfikowanych 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ł klucza prywatnego SSH jest wskazywany wyłącznie przez SecretRef. Udostępnione punkty końcowe SSH muszą również zawierać publiczny hostKey z zaufanych danych wyjściowych udostępniania, dokładnie w postaci algorithm base64, bez nazwy hosta ani komentarza, aby rdzeń mógł przypiąć host przed połączeniem. Dostawcy tworzący dynamiczne odwołania do tożsamości mogą implementować autorytatywną funkcję resolveSshIdentity({ leaseId, profile, keyRef }); w przypadku dostawców bez tej funkcji używany jest ogólny mechanizm rozpoznawania sekretów rdzenia. Autorytatywny stan unknown osieroca aktywny rekord lokalny; po utrwalonym żądaniu zniszczenia potwierdza zakończenie usuwania zasobów.

contracts.gatewayMethodDispatch obecnie akceptuje "authenticated-request". Jest to mechanizm higieny API dla natywnych tras HTTP Pluginu, które celowo wywołują metody płaszczyzny sterowania Gateway wewnątrz procesu, a nie piaskownica chroniąca przed złośliwymi natywnymi Pluginami. Należy go używać wyłącznie dla dokładnie sprawdzonych dołączonych powierzchni operatorskich, które już wymagają uwierzytelniania HTTP Gateway. Uprawniona trasa pozostaje dostępna po zamknięciu przyjmowania zadań głównych przez Gateway tylko wtedy, gdy deklaruje również auth: "gateway" oraz specyficzne dla trasy gatewayRuntimeScopeSurface: "trusted-operator"; zwykłe trasy równorzędne z tego samego Pluginu pozostają za granicą przyjmowania. Dzięki temu stan wstrzymania i wznowienie pozostają dostępne bez przyznawania całemu Pluginowi możliwości omijania kontroli przyjmowania. Analizowanie i kształtowanie odpowiedzi powinno pozostać ograniczone poza wywołaniem; istotne lub modyfikujące operacje muszą przechodzić przez wywołanie metody Gateway, które odpowiada za egzekwowanie zasad przyjmowania i zakresu.

Dokumentacja configContracts

Używaj configContracts do zachowań konfiguracji należących do manifestu, których potrzebują ogólne pomocnicze mechanizmy rdzenia bez importowania środowiska wykonawczego 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

Użyj mediaUnderstandingProviderMetadata, gdy dostawca rozumienia multimediów ma domyślne modele, priorytet automatycznego uwierzytelniania awaryjnego lub natywną obsługę dokumentów, których ogólne mechanizmy rdzenia potrzebują przed załadowaniem środowiska wykonawczego. 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

Użyj channelConfigs, gdy plugin kanału potrzebuje łatwo dostępnych metadanych konfiguracji przed załadowaniem środowiska wykonawczego. Wykrywanie konfiguracji lub stanu kanału tylko do odczytu może bezpośrednio używać tych metadanych dla skonfigurowanych kanałów zewnętrznych, gdy wpis konfiguracji nie jest dostępny albo gdy setup.requiresRuntime: false deklaruje, że środowisko wykonawcze nie jest potrzebne do konfiguracji.

channelConfigs to metadane manifestu pluginu, a nie nowa sekcja najwyższego poziomu w 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 wykonawczego pluginu.

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

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

Pluginy niedołączone, które deklarują channels[], powinny również deklarować odpowiadające im wpisy channelConfigs. Bez nich OpenClaw nadal może załadować plugin, ale powierzchnie schematu konfiguracji ścieżki zimnej, konfiguracji i interfejsu Control UI nie mogą poznać struktury opcji należących do kanału, dopóki nie zostanie wykonane środowisko wykonawcze pluginu.

channelConfigs.<channel-id>.commands.nativeCommandsAutoEnabled i nativeSkillsAutoEnabled mogą deklarować statyczne wartości domyślne auto dla sprawdzania konfiguracji poleceń wykonywanego przed załadowaniem środowiska wykonawczego kanału. Dołączone kanały mogą również 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": "Homeserver URL",          "placeholder": "https://matrix.example.com"        }      },      "label": "Matrix",      "description": "Matrix homeserver connection",      "commands": {        "nativeCommandsAutoEnabled": true,        "nativeSkillsAutoEnabled": true      },      "preferOver": ["matrix-legacy"]    }  }}

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

Zastępowanie innego pluginu kanału

Użyj preferOver, gdy Twój 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, który zachowuje 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 wykonawczego, 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 zachowuje ten wybór i zgłasza diagnostykę zduplikowanych kanałów lub narzędzi zamiast po cichu zmieniać żądany zestaw pluginów.

Ogranicz zakres preferOver 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

Użyj modelSupport, gdy OpenClaw powinien wywnioskować plugin dostawcy na podstawie skróconych identyfikatorów modeli, takich jak gpt-5.6-sol lub claude-sonnet-4.6, przed załadowaniem środowiska wykonawczego 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 providers należących do odpowiedniego dostawcy
• modelPatterns mają pierwszeństwo przed modelPrefixes
• jeśli pasują zarówno jeden plugin niedołączony, jak i jeden dołączony, pierwszeństwo ma plugin niedołączony
• 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ą po cichu pomijane, podobnie jak wyrażenia regularne niepoprawne składniowo. Utrzymuj wzorce w prostej postaci i unikaj zagnieżdżonych kwantyfikatorów.

Dokumentacja modelCatalog

Użyj modelCatalog, gdy OpenClaw powinien znać metadane modeli dostawcy przed załadowaniem środowiska wykonawczego 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 działania nadal należy do kodu środowiska wykonawczego dostawcy, ale manifest informuje rdzeń, kiedy środowisko wykonawcze 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": "not available on 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ć dostawcami najwyższego poziomu 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/bazowego adresu URL aliasu bez ładowania środowiska uruchomieniowego dostawcy. Aliasy nie rozszerzają niefiltrowanych zestawień katalogu; szerokie listy zawierają wyłącznie wiersze kanonicznego dostawcy będącego właścicielem.

suppressions zastępuje stary hak środowiska uruchomieniowego dostawcy suppressBuiltInModel. Wpisy wykluczeń są uwzględniane tylko wtedy, gdy dostawca należy do pluginu albo został zadeklarowany jako klucz modelCatalog.aliases wskazujący dostawcę należącego do pluginu. Haki wykluczania środowiska uruchomieniowego nie są już wywoływane podczas rozpoznawania modelu.

Pola dostawcy:

Pola modelu:

Pola wykluczeń:

Nie umieszczaj w modelCatalog danych dostępnych wyłącznie w środowisku uruchomieniowym. Używaj static tylko wtedy, gdy wiersze manifestu są wystarczająco kompletne, aby listy filtrowane według dostawcy i interfejsy selektorów mogły pominąć wykrywanie rejestru/środowiska uruchomieniowego. Używaj refreshable, gdy wiersze manifestu są użytecznymi, możliwymi do wyświetlenia danymi początkowymi lub uzupełniającymi, lecz odświeżenie/pamięć podręczna może później dodać kolejne wiersze; wiersze odświeżalne nie są same w sobie źródłem rozstrzygającym. Używaj runtime, gdy OpenClaw musi załadować środowisko uruchomieniowe dostawcy, aby poznać listę.

Dokumentacja modelIdNormalization

Używaj modelIdNormalization do niedrogiego czyszczenia identyfikatorów modeli należących do dostawcy, 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 proxy, pozostają w manifeście pluginu będącego właścicielem, zamiast trafiać do podstawowych tabel wyboru modeli.

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

Pola dostawcy:

Dokumentacja providerEndpoints

Używaj providerEndpoints do klasyfikacji punktów końcowych, którą ogólna polityka żądań musi znać przed załadowaniem środowiska uruchomieniowego dostawcy. Rdzeń nadal określa znaczenie każdej wartości endpointClass; manifesty pluginów są właścicielami metadanych hosta i bazowego adresu URL.

Oficjalnie wydzielone zewnętrzne pluginy dostawców są wykluczone z dystrybucji rdzenia, więc ich manifesty są niewidoczne do czasu instalacji. Ich providerEndpoints muszą być również odzwierciedlone w scripts/lib/official-external-provider-catalog.json, aby klasyfikacja punktów końcowych działała bez pluginu; zgodność odzwierciedlenia jest wymuszana przez test kontraktowy.

Pola punktu końcowego:

Dokumentacja providerRequest

Użyj providerRequest dla niedrogich metadanych zgodności żądania, których wymagają ogólne zasady obsługi żądań bez ładowania środowiska wykonawczego dostawcy. Przekształcanie ładunku właściwe dla określonego zachowania pozostaw 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 publikować gotową, wielokrotnego użytku konfigurację dostawcy wykonawczego SecretRef. OpenClaw odczytuje te metadane przed załadowaniem środowiska wykonawczego pluginu, zapisuje własność pluginu w secrets.providers.<alias>.pluginIntegration, a właściwe rozpoznawanie sekretów pozostawia środowisku wykonawczemu SecretRef. Gotowe konfiguracje są udostępniane wyłącznie dla wbudowanych pluginów 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 w następującej postaci:

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

Podczas uruchamiania lub ponownego ładowania OpenClaw rozpoznaje 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 chcą używać samodzielnej konfiguracji wykonawczej, nadal mogą bezpośrednio definiować ręcznych dostawców za pomocą command/args.

Obecnie obsługiwane są wyłącznie gotowe konfiguracje source: "exec". Wartością command musi być ${node}, a args[0] musi wskazywać skrypt rozpoznawania względny wobec katalogu głównego pluginu i rozpoczynający się od ./. Podczas uruchamiania lub ponownego ładowania OpenClaw zastępuje je bieżącym plikiem wykonywalnym Node oraz bezwzględną ścieżką skryptu wewnątrz pluginu. Opcje Node, takie jak --require, --import, --loader, --env-file, --eval i --print, nie są częścią kontraktu gotowej konfiguracji manifestu. Operatorzy potrzebujący poleceń innych niż Node mogą bezpośrednio skonfigurować samodzielnych ręcznych dostawców wykonawczych.

OpenClaw wyznacza trustedDirs dla gotowych konfiguracji manifestu na podstawie katalogu głównego pluginu, a w przypadku konfiguracji ${node} również katalogu bieżącego pliku wykonywalnego Node. Wartości trustedDirs zdefiniowane 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 potrzebuje zachowania dotyczącego 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 on częścią manifestu pluginu. Manifesty pluginów pozostają źródłem prawdy o zainstalowanych pluginach. Indeks dostawców jest wewnętrznym kontraktem awaryjnym, z którego przyszłe interfejsy instalowalnych dostawców i wyboru modelu przed instalacją będą korzystać, gdy plugin dostawcy nie jest zainstalowany.

Kolejność źródeł katalogu:

1. Konfiguracja użytkownika.
2. modelCatalog manifestu zainstalowanego pluginu.
3. Pamięć podręczna katalogu modeli utworzona przez jawne odświeżenie.
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 określonego 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 wyświetlania, 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 obsługujący dynamiczne wykrywanie przez /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 z innego powodu nie jest jeszcze zainstalowany. Te metadane odzwierciedlają wzorzec katalogu kanałów: nazwa pakietu, specyfikacja instalacji npm, oczekiwana integralność oraz proste etykiety wyboru uwierzytelniania wystarczają do pokazania instalowalnej opcji konfiguracji. Po zainstalowaniu pluginu jego manifest ma pierwszeństwo, a wpis indeksu dostawców dla tego dostawcy jest ignorowany.

openclaw doctor --fix migruje mały, zamknięty zestaw starszych kluczy możliwości manifestu najwyższego poziomu do contracts.*: speechProviders, mediaUnderstandingProviders, imageGenerationProviders oraz tools. Żaden z nich ani żadna inna lista możliwości nie jest już odczytywana z pól 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:

Jeśli nie masz pewności, gdzie należy umieścić daną metadaną, zastosuj następującą regułę:

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

Pola package.json wpływające na wykrywanie

Niektóre metadane pluginu dostępne przed uruchomieniem celowo znajdują się w bloku openclaw pliku package.json, a nie 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 wymienionymi poniżej.

Ważne przykłady:

Metadane manifestu określają, które opcje dostawcy/kanału/konfiguracji pojawiają się podczas konfiguracji początkowej przed załadowaniem środowiska wykonawczego. package.json#openclaw.install informuje proces konfiguracji początkowej, jak pobrać lub włączyć dany plugin, gdy użytkownik wybierze jedną z tych opcji. Nie przenoś 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; nowsze, lecz prawidłowe wartości powodują pominięcie zewnętrznych pluginów na starszych hostach. Przyjmuje się, że dołączone pluginy źródłowe mają tę samą wersję co kopia robocza hosta.

openclaw.install.requiredPlatformPackages służy do określania pakietów npm, które udostępniają wymagane natywne pliki binarne za pośrednictwem opcjonalnych aliasów właściwych dla platformy. Dla każdego obsługiwanego aliasu platformowego podaj samą nazwę pakietu npm. Podczas instalacji npm OpenClaw weryfikuje wyłącznie zadeklarowany alias, którego ograniczenia w pliku blokady odpowiadają bieżącemu hostowi. Jeśli npm zgłosi powodzenie, ale pominie ten alias, OpenClaw ponowi próbę raz ze świeżą pamięcią podręczną i wycofa instalację, jeżeli alias nadal będzie nieobecny.

openclaw.compat.pluginApi jest egzekwowane podczas instalacji pakietów ze źródeł pluginów, które nie są dołączone. Użyj go do określenia minimalnej wersji interfejsu API SDK/środowiska wykonawczego pluginów OpenClaw, względem której zbudowano pakiet. Może być bardziej rygorystyczne niż minHostVersion, gdy pakiet pluginu wymaga nowszego interfejsu API, ale nadal zachowuje niższą wskazówkę instalacyjną dla innych przepływów. Oficjalna synchronizacja wydań OpenClaw domyślnie podnosi istniejące minimalne wersje interfejsu 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 używaj 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; konfiguracja początkowa traktuje je jako preferowane źródło zdalne i po instalacji zapisuje informacje o artefakcie ClawHub. npmSpec pozostaje zgodnościowym rozwiązaniem rezerwowym 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ę bezpiecznym niepowodzeniem, jeżeli pobrany artefakt npm przestanie odpowiadać przypiętemu wydaniu. Interaktywna konfiguracja początkowa nadal oferuje zaufane specyfikacje npm rejestru, w tym same nazwy pakietów i znaczniki dystrybucji, w celu zachowania zgodności. Diagnostyka katalogu może rozróżniać źródła dokładne, zmienne, przypięte integralnością, pozbawione integralności, z niezgodną nazwą pakietu oraz z nieprawidłową opcją domyślną. Ostrzega również, gdy expectedIntegrity jest obecne, ale nie istnieje prawidłowe źródło npm, do którego można je przypiąć. Gdy expectedIntegrity jest obecne, 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 musi identyfikować skonfigurowane konta bez ładowania pełnego środowiska wykonawczego. Punkt wejścia konfiguracji powinien udostępniać metadane kanału oraz bezpieczne dla konfiguracji adaptery konfiguracji, statusu i sekretów; klientów sieciowych, procesy nasłuchujące Gateway i środowiska wykonawcze transportu należy pozostawić w głównym punkcie wejścia rozszerzenia.

Pola punktów wejścia środowiska wykonawczego nie zastępują kontroli granic pakietu dla pól źródłowych punktów wejścia. Na przykład openclaw.runtimeExtensions nie może sprawić, że ścieżka openclaw.extensions wychodząca poza pakiet stanie się możliwa do załadowania.

openclaw.install.allowInvalidConfigRecovery jest celowo ściśle ograniczone. Nie umożliwia instalowania dowolnych uszkodzonych konfiguracji. Obecnie pozwala procesom instalacji odzyskać sprawność tylko po określonych błędach aktualizacji nieaktualnych dołączonych pluginów, takich jak brak ścieżki 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"      }    }  }}

Użyj ich, gdy konfiguracja, diagnostyka, status lub przepływy 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 stanem skonfigurowania kanału: nie używaj tych metadanych do automatycznego włączania pluginów, naprawiania zależności środowiska wykonawczego ani decydowania, czy środowisko wykonawcze kanału powinno zostać załadowane. Docelowy eksport powinien być małą funkcją odczytującą wyłącznie utrwalony stan; nie kieruj go przez główny moduł eksportowy pełnego środowiska wykonawczego kanału.

openclaw.channel.configuredState ma taką samą strukturę dla lekkich kontroli skonfigurowania opartych wyłącznie na zmiennych środowiskowych:

{  "openclaw": {    "channel": {      "id": "telegram",      "configuredState": {        "specifier": "./configured-state",        "exportName": "hasTelegramConfiguredState"      }    }  }}

Użyj go, gdy kanał może określić stan skonfigurowania na podstawie zmiennych środowiskowych lub innych niewielkich danych wejściowych niezależnych od środowiska wykonawczego. Jeśli kontrola wymaga pełnego rozstrzygnięcia konfiguracji lub rzeczywistego środowiska wykonawczego kanału, pozostaw tę logikę w haku pluginu config.hasConfiguredState.

Priorytet wykrywania (zduplikowane identyfikatory pluginów)

OpenClaw wykrywa pluginy z trzech katalogów głównych sprawdzanych w następującej kolejności: pluginy dołączone do OpenClaw, globalny katalog główny instalacji (~/.openclaw/extensions) oraz 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 wyłącznie manifest o najwyższym priorytecie; duplikaty o niższym priorytecie są odrzucane zamiast ładowania obok niego. Priorytet od najwyższego do najniższego:

1. Wybrany przez konfigurację — ścieżka jawnie przypięta w plugins.entries.<id>
2. Globalna instalacja zgodna ze śledzonym rekordem instalacji — plugin zainstalowany za pomocą openclaw plugin install/openclaw plugin update, który mechanizm śledzenia instalacji OpenClaw rozpoznaje dla tego samego identyfikatora, nawet gdy 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 przesłoni dołączonej kompilacji.
• Aby zastąpić dołączony plugin, uruchom openclaw plugin install dla danego identyfikatora, tak aby śledzona instalacja globalna uzyskała wyższy priorytet niż dołączona kopia, albo przypnij konkretną ścieżkę za pomocą plugins.entries.<id>, aby wygrała dzięki priorytetowi wyboru przez konfigurację.
• Odrzucanie duplikatów jest rejestrowane, dzięki czemu diagnostyka Doctor i uruchamiania może wskazać odrzuconą kopię.
• Zastąpienia duplikatów wybrane przez konfigurację są w diagnostyce opisywane jako jawne zastąpienia, ale nadal generują ostrzeżenie, aby nieaktualne rozgałęzienia i przypadkowe przesłonięcia pozostawały widoczne.

Wymagania 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ą weryfikowane podczas odczytu i zapisu konfiguracji, a nie w czasie działania.
• Rozszerzając lub tworząc fork dołączonego pluginu o nowe klucze konfiguracji, zaktualizuj jednocześnie configSchema w pliku openclaw.plugin.json tego pluginu. Schematy dołączonych pluginów są rygorystyczne, dlatego dodanie plugins.entries.<id>.config.myNewKey w konfiguracji użytkownika bez dodania myNewKey do configSchema.properties zostanie odrzucone przed załadowaniem środowiska wykonawczego pluginu.

Przykładowe rozszerzenie schematu:

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

Sposób walidacji

• Nieznane klucze channels.* są błędami, chyba że identyfikator kanału został 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 do nieznanych identyfikatorów pluginów w plugins.entries.<id>, plugins.allow i plugins.deny 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 do nieznanego identyfikatora pluginu w plugins.slots.memory jest błędem, z wyjątkiem znanego oficjalnego zewnętrznego pluginu memory-lancedb, dla którego generowane 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 dziennikach 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 wykonawcze nadal ładuje moduł pluginu oddzielnie; manifest służy wyłącznie do wykrywania i walidacji.
• Natywne manifesty są analizowane jako JSON5, więc komentarze, przecinki na końcu i klucze bez cudzysłowów są dozwolone, o ile końcowa wartość nadal jest obiektem.
• Moduł ładujący manifest odczytuje tylko udokumentowane pola manifestu. Unikaj niestandardowych kluczy najwyższego poziomu.
• Pola 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 wykonawczego; używaj go do statycznych metadanych katalogu dostawców lub precyzyjnych deskryptorów wykrywania, a nie do wykonywania operacji podczas obsługi żądań.
• Wyłączne rodzaje pluginów są wybierane za pomocą plugins.slots.*: kind: "memory" przez plugins.slots.memory (domyślnie memory-core), a kind: "context-engine" przez plugins.slots.contextEngine (domyślnie legacy).
• Zadeklaruj wyłączny rodzaj pluginu w tym manifeście. Pole OpenClawPluginDefinition.kind punktu wejścia środowiska wykonawczego jest przestarzałe i pozostaje jedynie jako mechanizm zgodności dla starszych pluginów.
• Metadane zmiennych środowiskowych (setup.providers[].envVars, przestarzałe providerAuthEnvVars oraz channelEnvVars) mają wyłącznie charakter deklaratywny. Mechanizmy statusu, audytu, walidacji dostarczania Cron i inne powierzchnie tylko do odczytu nadal stosują zasady zaufania pluginów oraz obowiązujące zasady aktywacji, zanim uznają zmienną środowiskową za skonfigurowaną.
• Metadane kreatora środowiska wykonawczego wymagające kodu dostawcy opisano w sekcji punkty zaczepienia środowiska wykonawczego dostawcy.
• Jeśli plugin zależy od modułów natywnych, udokumentuj kroki kompilacji i wszelkie wymagania dotyczące listy dozwolonych elementów menedżera pakietów (na przykład allow-build-scripts w pnpm oraz pnpm rebuild <package>).

Powiązane materiały